acts[].ok is documented in two supervision legends and absent from the payload; delegation budgets can enter 'exhausted' with no exit

[serge-ivo]

Two supervision legends tell the model to read acts[].ok; the payload has never carried it. And a budget can enter a state it cannot leave.

1. acts[].ok is promised twice and delivered never

subordinate-payload.ts:270 (subordinate_status) and connectors/supervision.ts:756 (check_delegation) both state:

An act with ok: false FAILED and one with ok: null was not observed to succeed.

ActItem (lib/instance-work.ts:60-73) declares instanceId, kind, summary, command, irreversible, traceId, at — no ok. toActItem (:281-289) never reads it, though engine-acts.ts:595 writes it into agent_events.context. The payload map (supervision.ts:457) spreads that same object.

The outcome does survive inside summary — describeEngineAct appends " — FAILED" / " — outcome not observed" (engine-acts.ts:527) — so no information is lost. But a model told to check a key that is absent reads absence as "fine", which inverts the intended default for an unobserved act.

2. delegation_budgets: 'closed' has no writer and 'exhausted' has no exit

grep -rn "closeBudget\|raiseBudget" workers store packages docs platform-docs → 11 hits, all in .test.ts, plus the two definitions (delegation-budget-store.ts:421,442).

• raiseBudget is the only path out of exhausted — reachable from no route. delegation-budget.test.ts:171 already records it as "reachable from no route".
• closeBudget is the only writer of 'closed' — so that state is unreachable.

markExhausted's docblock (:394-395) says "the work is intact and resumable once a human raises the limit" — describing a path with no caller.

Worse, the refusal a user actually sees names a state the system cannot enter (delegation-budget-store.ts:356):

if (current.status !== "open") return { ok: false, reason: "closed", message: "This run's budget is already closed." }

It is reached only when the status is exhausted. So a delegated run that hits its budget stops with a message describing the wrong state, and there is no supported way to resume it.

Why this misleads into a wrong action

Both are the same shape: a contract stated to the reader that the code does not honour. The first makes a supervisor treat unobserved acts as successful; the second tells an owner their budget is "closed" when it is exhausted-and-recoverable-in-principle, with no way to recover it.

Acceptance criteria

1. ActItem carries ok, or both legends stop naming it. Prefer carrying it — engine-acts.ts:595 already writes it and summary already encodes it, so the two would agree.
2. exhausted gains a supported exit, or markExhausted's docblock stops promising one.
3. The refusal message names the state the budget is actually in.
4. 'closed' gains a writer or is removed from the declared values.
5. A guard asserts every field named in a tool description exists in that tool's payload type, denominator stated per ADR 0002 over all descriptions — this is the same class as list_instance_tools and the published docs still tell operators to audit external reach by filtering on connector — the proxy #584 disproved #585 (prose recommending a field the code had replaced) and warrants one check rather than three fixes.

Verified vs inferred

• Verified: both legend strings; ActItem's declaration and toActItem; the grep with its count; all four delegation-budget-store.ts line references.
• Inferred: that no caller exists outside the swept paths — the grep covered workers, store, packages, docs, platform-docs. A caller outside those trees would falsify it.

[serge-ivo]

Done in 2badcaf, scoped in b4d6ea3. CI green on both, API deployed. Leaving open on AC2 and AC4 — both are design decisions rather than missing lines, stated below.

AC1 — done, carried rather than removed

ActItem declares ok: boolean | null and toActItem reads it. As you noted, engine-acts.ts:595 was already writing it and summary already encodes it, so the two now agree instead of one being unreadable. Anything that is not an explicit boolean maps to null, never false — "we did not see" and "it failed" are different claims and a corrupt context must land on the one that asserts less. Both act reads (recentActsForInstances, actsInWindow) go through the same projection, so subordinate_status and check_delegation cannot disagree.

A scope correction, from the adjacent lane (now #597). ok is obtainable for CONSEQUENTIAL acts and not in general: #581 AC7's per-tool-call record has no outcome field because the runner computes block.is_error (headless.ts:750) and toolResult() writes the row without it (:676) — a runner change plus a CLI publish plus users upgrading. So b4d6ea3 makes both legends name the list they govern ("CONSEQUENTIAL acts only … not the agent's ordinary tool calls"). An unscoped promise is how one gets inherited by a list that cannot keep it, which is this issue's own thesis.

Verified live: agent_events rows on act.consequential in production do carry ok in context — e.g. two push.trunk acts on 2026-08-15 under run 308b4672, "ok":true, "irreversible":true. Every one of ~25 rows sampled carries it. So the data the projection reads is present and well-formed; the payload key itself is only emitted by an agent-side connector tool and was not called (that would mean messaging the instance).

AC3 — done, and this was the user-visible bug

delegation-budget-store.ts:356 returned "This run's budget is already closed" for both non-open states, and is only ever reached in one of them. Since 'closed' has no writer, every user who has ever seen that sentence had an EXHAUSTED budget. The message now names the actual state, which limit ran out, at what depth, that the work already done is intact, and who to ask.

The reason code stays closed deliberately, and that is not laziness: workflows/agent-loop.ts:113 and coding-decide-budget.ts:38 both read it as "do not call markExhausted", which is correct for either state. Splitting the reason to improve a sentence would change a branch in two workflows to say something neither of them asks. Documented at the call site.

Red demonstrated: expected 'This run\'s budget is already closed.' to contain 'EXHAUSTED'.

AC5 — delivered SCOPED, and the scope is the honest part

workers/api/src/lib/supervision-legend-contract.test.ts. It asserts the legend still teaches ok, that the payload delivers it, that all three outcome states are reachable (true/false/null), that all 7 promised act fields exist on the item, and that the scope claim is true of the reader (instance-work.ts keys on one ACT_EVENT constant) rather than merely present in the prose. Red on the shipped tree: "the legend names ok and the payload has no such key".

The general form you asked for was not built, and I would rather say so than approximate it. "Every field named in ANY tool description exists in that tool's payload, denominator over all descriptions" is not buildable today: most of ~100 tools JSON.stringify an ad-hoc object with no declared payload type, so there is nothing to compare a name against, and a fixture farm covering all of them would be a larger artefact than the thing it guards. The supervision family is where the payload is a pure function of its inputs and can be built in full, so that is what is guarded, with the denominator stated as what it is. The general case is worth its own issue with a design step first.

AC2 and AC4 — why they stay open

Both were offered as either/or, and I have done the "or" half honestly rather than guessing at the other.

AC2 — markExhausted's docblock no longer promises the work is "resumable once a human raises the limit", because raiseBudget is reachable from no route. A supported exit is a product decision: who may raise a budget, by how much, through which surface, and whether approving it is itself an audited act. Adding a route on my own judgement would be inventing policy about spending limits.

AC4 — 'closed' still has no writer. Deleting it is wrong (it is the correct design and re-adding costs a migration); wiring closeBudget needs a tree-lifecycle hook that does not exist: nothing today knows when a delegation TREE is finished — a root run ending does not mean a sibling delegation has stopped drawing — so closing on the first terminal run would refuse legitimate work. Both functions now say plainly in their docblocks that they have no caller and why, so the next reader does not take 'closed' for a state they can observe.

The user-facing harm (a wrong state name, and a message implying a remedy that does not exist) is fixed. What remains is "should an exhausted delegation tree be resumable, and how" — worth its own issue.

[serge-ivo]

Per-tool-call outcomes are now available for 0.4.52+ rows — a scoping decision this issue can revisit

2dc1e65 (#597) made the runner record whether each tool call succeeded, and @proagentstore/cli@0.4.52 is published. EngineToolCall.ok is boolean | null, emitted explicitly as null when not observed — in-flight, or a row written by an older runner — never omitted, which is precisely this issue's point about absence reading as fine.

This does not change what #594 should ship, but it widens what it could. The supervision payload currently scopes its ok promise to consequential acts, which was correct when that was the only place an outcome existed. For a machine running 0.4.52+, a supervisor could now be given per-call outcomes for ordinary reads, greps and file opens too.

That is a design decision, not a defect: a supervisor roster carrying every tool call's outcome is a much larger payload, and #503 is open on subordinate_status already returning 60,239 bytes and showing a Lead only 3 of its 6 agents. So the scoping may well remain correct on size grounds alone — but it should now be a decision rather than a limitation.

If the scope stays as-is, say so in the legend. The current wording promises a field for acts generally; scoping it explicitly to consequential acts is the honest form, and it is the same correction #602 and #585 made elsewhere — a legend must state what is true for every case, not the best one.

Verified vs inferred

• Verified: 2dc1e65 on main; 0.4.52 published and the bundled runner confirmed by unpacking the tarball; ok emitted explicitly as null for unobserved calls.
• Inferred: that carrying per-call outcomes would materially enlarge the supervision payload. Plausible given [bug] The Coder Lead can only ever see 3 of 6 agents — subordinate_status returns 60,239 chars into a 24,000 cap, so half the roster is silently dropped #503's measured 60 KB, but not measured for this field specifically — measure before deciding on size grounds.