docs(aosguard): record the raw-response defect and the path that works #1064

Merged

coilysiren merged 1 commit from aos/claude/bk79 into main

2026-08-15 16:23:14 +00:00

coilyco-ops commented

2026-08-15 15:55:17 +00:00

Member

Refs #1044. The engine fix is coilyco-flight-deck/umbra#291; this is the part that belongs in this repo.

What I confirmed

Still reproduces, on a freshly built binary as well as the installed one, so it is not a stale release:

$ aosguard ops forgejo action-job logs coilyco-gaming sirens-echo 33908
aosguard: invalid character '-' after top-level value
$ aosguard ops forgejo action-run logs coilyco-gaming sirens-echo 20593
aosguard: invalid character 'P' looking for beginning of value

Two corrections to the issue thread

The guardfile and the spec are both already correct. The vendored snapshot and the committed lock each declare produces: text/plain and produces: application/zip for these ops, and the engine's rawResponseOp returns true for both when I ran it against that exact lock. The engine then discards the answer: FireCapture JSON-decodes every success body and errors, and both call sites check their raw flag only after that returns. The raw branch was unreachable.

The severity is lower again than the follow-up comment argued, in a way that matters. That comment corrected the body by naming ward exec forgejo-actions-logs. There is a nearer answer: aosguard ops actions logs is a guarded leaf running the same agentic_os.forgejo_actions_logs module, and docs/forgejo-actions-logs.md already documents it as the recommended resolved command. I used it successfully on the same job the broken leaf refused. So the operator surface never had a hole - it had a broken leaf sitting directly beneath a working one, with nothing saying so.

Why nothing here can patch it

output "raw" exists only on fetch overlays. Adding it to a can grant is rejected:

guardfile: grant body: unknown node "output"
    (want op | body | message | describe; fail-closed)

So per authoring-vs-rollout the fix is upstream, and it went there.

This PR

Docs only, no behavior change.

docs/forgejo-actions-logs.md no longer presents the two logs leaves as working, and points at the defect page. It was one line under the 80-line cap, hence the split rather than an inline note.
docs/aosguard-raw-response-defect.md carries the diagnosis, the reproduction, what to use meanwhile, and an explicit removal condition - re-lock .specgen onto an umbra release carrying umbra#291, currently pinned at v0.139.0, then delete the page.

No docs/FEATURES.md entry: this documents a defect, it does not add or remove a capability.

pre-commit passes on both files.

Follow-up, not in this PR

Bumping .specgen/guardfiles/specverb.lock off umbra v0.139.0 once umbra#291 releases. That is gated on the upstream release, so it wants its own issue rather than a branch that sits waiting.

Refs #1044. The engine fix is `coilyco-flight-deck/umbra#291`; this is the part that belongs in this repo. ## What I confirmed Still reproduces, on a freshly built binary as well as the installed one, so it is not a stale release: ``` $ aosguard ops forgejo action-job logs coilyco-gaming sirens-echo 33908 aosguard: invalid character '-' after top-level value $ aosguard ops forgejo action-run logs coilyco-gaming sirens-echo 20593 aosguard: invalid character 'P' looking for beginning of value ``` ## Two corrections to the issue thread **The guardfile and the spec are both already correct.** The vendored snapshot and the committed lock each declare `produces: text/plain` and `produces: application/zip` for these ops, and the engine's `rawResponseOp` returns true for both when I ran it against that exact lock. The engine then discards the answer: `FireCapture` JSON-decodes every success body and errors, and both call sites check their raw flag only after that returns. The raw branch was unreachable. **The severity is lower again than the follow-up comment argued, in a way that matters.** That comment corrected the body by naming `ward exec forgejo-actions-logs`. There is a nearer answer: `aosguard ops actions logs` is a **guarded leaf** running the same `agentic_os.forgejo_actions_logs` module, and `docs/forgejo-actions-logs.md` already documents it as the recommended resolved command. I used it successfully on the same job the broken leaf refused. So the operator surface never had a hole - it had a broken leaf sitting directly beneath a working one, with nothing saying so. ## Why nothing here can patch it `output "raw"` exists only on `fetch` overlays. Adding it to a `can` grant is rejected: ``` guardfile: grant body: unknown node "output" (want op | body | message | describe; fail-closed) ``` So per authoring-vs-rollout the fix is upstream, and it went there. ## This PR Docs only, no behavior change. * `docs/forgejo-actions-logs.md` no longer presents the two `logs` leaves as working, and points at the defect page. It was one line under the 80-line cap, hence the split rather than an inline note. * `docs/aosguard-raw-response-defect.md` carries the diagnosis, the reproduction, what to use meanwhile, and an explicit **removal condition** - re-lock `.specgen` onto an umbra release carrying umbra#291, currently pinned at `v0.139.0`, then delete the page. No `docs/FEATURES.md` entry: this documents a defect, it does not add or remove a capability. `pre-commit` passes on both files. ## Follow-up, not in this PR Bumping `.specgen/guardfiles/specverb.lock` off `umbra v0.139.0` once umbra#291 releases. That is gated on the upstream release, so it wants its own issue rather than a branch that sits waiting.

coilyco-ops added 1 commit

2026-08-15 15:55:17 +00:00

docs(aosguard): record the raw-response defect and the path that works

ci / aos-cli-tests (pull_request) Successful in 1m7s

Details

ci / gate (pull_request) Successful in 1m54s

Details

ci / ward-doctor (pull_request) Successful in 8m58s

Details

c2d5b76f75

The Actions-logs page listed the two `forgejo ... logs` leaves as direct
API access with no caveat, while both fail on every call. It also gave a
reader no signal that `aosguard ops actions logs` reaches the same bytes,
so the surface read as having a hole it does not have.

Diagnosis lives in its own page: the guardfile and the vendored spec are
both correct, the engine reads the declared media type correctly, and
then decodes JSON before consulting the result. A `can` grant cannot
express `output "raw"`, so there is no authoring-layer workaround.

Fixed upstream in umbra#291. The page names its own removal condition.

Refs #1044

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-15 15:55:17 +00:00

coilyco-ops referenced this pull request

2026-08-15 15:55:49 +00:00

aosguard ops forgejo action-job logs JSON-decodes a plaintext body, so CI logs are unreachable through the guarded surface #1044

coilyco-ops referenced this pull request

2026-08-15 15:56:06 +00:00

Re-lock .specgen onto the umbra release carrying the raw-response fix, then drop the defect page #1065