Skip to content

Commit f3b1339

Browse files
fix(agent-mode): a refused run must not lose what it was asked for (#323 review)
Four review findings, and all four are the same defect at different depths: a route that reports it advanced the run while dropping part of what the caller asked for. On the shared envelope `next_action` **is** the step, so each of these was published as the authoritative answer. **[P1] A refused write handed the caller onward under the wrong pack.** `init --write --control-pack financial-strict` over a manifest selecting `default` refuses to overwrite and routes onward — to `doctor` on the plain path, to the gate on the `--agent-instructions` refresh path. Both read a manifest that loads fine and advance under the pack that is *there*, so an envelope-only caller proceeded under `default` having asked for `financial-strict`, with only a payload field recording the difference. The route now names `policies.control_pack` and the exact value, and reaches the onward step only when the manifest already matches. "Asked for" is `--control-pack` at other than its default — the same rule `_requested_setup_flags` already applies when deciding whether to repeat the flag, because Typer cannot tell an omitted option from one passed at its default and two rules for that would disagree at the boundary. The pack is the only manifest-scoped request a refused write can be compared against, and the docstring says why each of the others cannot be. **[P1] Every recovery command was built from the wrong list.** `_requested_setup_flags` answers what a rerun in a *different* workspace may repeat; every recovery `init` publishes reruns the same one. So `init --write --minimal --control-pack <bad>` emitted a recovery with no `--minimal`, and following it wrote a detected manifest where the legacy template was explicitly asked for; an explicit kit became the default kit, and a raised `--max-python-files` was dropped so the rerun refused again on a truncation the caller had already answered. One `_invocation_flags` builder now feeds all five sites, and correcting a value means passing the corrected value rather than dropping the flag. **[P2] `input_id` did not cover every fact that selects the route.** `action_kind` is not carried by the action and decides `next_action.kind` and `verify_required`; diagnostics were reduced to their rank-1 actions, dropping the id that decides ownership and the severity that decides precedence. Both are hashed now, with the same fix applied to `detect`'s and `init`'s own `advance_kind`. `doctor`'s success identity is deliberately untouched: `STABILITY.md` promises it is the same on every machine. **[P1] The published `execution` guarantee was false.** `STABILITY.md` said a setup error envelope always reports `"failed"`. The most common one does not — `init --write` over an existing manifest reached an answer and refused, so it exits 2 with `"succeeded"`, and that line is the resume of the adoption walk itself. A consumer taking the contract literally would have rejected it. The contract now states what actually holds on every setup error line (`decision_source: "setup"`, a setup-vocabulary `decision`, `permissions` all false, never `complete`) and describes `execution` as what it is: whether the command reached an answer, not whether the line is an error. Corrected in `STABILITY.md`, `docs/agent-contract-current.md`, `AGENTS.md`, and `docs/errors.json`, and pinned by a test that asserts both shapes occur. Also from the review: `docs/passed-verdict-contract.md` still stamped contract v26, and the two command-value migrations — the recovery flags and the `internal_error` fallback — are now stated explicitly rather than left under "nothing is removed". **Coverage is of the routes, not their shapes.** The walk fixture now runs the emitted recovery and inspects the manifest it produced, with the no-`--minimal` case as the control so the assertion cannot pass vacuously; it follows the unapplied-pack edit and requires the obligation to be gone afterwards. The `advance_kind` identity guard is structural and says why: no branch varies the kind without varying the action today, so a behavioural test would pass for a reason unrelated to the fix. **And one defect found reviewing the fix.** `_unapplied_control_pack`'s docstring claimed it guarded a `None` on-disk pack; the code did not, so a manifest that loads while its pack does not resolve would have published an edit whose `why` read "the manifest still selects None". Today no such manifest is reachable — an unknown pack id fails schema validation and the defect route claims it first — but that is `_manifest_defect` and `_manifest_control_pack` happening to agree, and they run different amounts of the loader. The guard is what makes a disagreement fall through to `doctor` instead of becoming a route. Co-Authored-By: Claude Opus 5 <[email protected]>
1 parent 4eeda18 commit f3b1339

13 files changed

Lines changed: 970 additions & 93 deletions

‎AGENTS.md‎

Lines changed: 18 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -448,14 +448,24 @@ obligation.
448448
(contract v27). A setup command that could not finish publishes the same
449449
envelope on stderr that it would have published on stdout, so one routing rule
450450
covers both documented streams; `next_action` / `next_actions[]` are unchanged
451-
beside it. Such an envelope always reports `execution: "failed"`,
452-
`decision: "setup_incomplete"`, and `permissions` all false. The one exception
453-
is the shared `--workspace` refusal, which fires before the workspace exists
454-
and therefore has no setup subject to describe: it carries
455-
`next_action`/`next_actions` only. Error lines from `scan`, `verify`, and
456-
`check` also carry no `control`: the first two answer through their control
457-
pointer (`agents-shipgate agent control`), and `check` through
458-
`--format agent-control-json`.
451+
beside it. Every such envelope reports `decision_source: "setup"`, a `decision`
452+
from the setup vocabulary, `permissions` all false, and never
453+
`control_state: "complete"`.
454+
455+
**Do not use `execution` to tell an error line from an answer** — the `error`
456+
field does that. `execution` says whether the command reached an answer about
457+
the workspace, so an error line carries `"failed"` when it could not (a flag
458+
value it could not parse, discovery it could not bound, a manifest it could not
459+
open) and `"succeeded"` with a non-zero `exit_code` when it did and the answer
460+
is a refusal it can route past (`config_already_exists`, the unresolved-scope
461+
`config_error`). Both authorize nothing.
462+
463+
The one setup line with no `control` is the shared `--workspace` refusal, which
464+
fires before the workspace exists and therefore has no setup subject to
465+
describe: it carries `next_action`/`next_actions` only. Error lines from
466+
`scan`, `verify`, and `check` also carry no `control`: the first two answer
467+
through their control pointer (`agents-shipgate agent control`), and `check`
468+
through `--format agent-control-json`.
459469

460470
Every emitted command names the entry point that started the running process, so it is runnable where it was produced: a console-script run emits `agents-shipgate …`, and a `python -m agents_shipgate` run emits `<sys.executable> -m agents_shipgate …`. Set `AGENTS_SHIPGATE_CLI` to name the entry point explicitly; it wins over detection. **On `next_actions[]`, run `[*executable, *args]` (contract v23+) rather than parsing `command`** — it needs no shell and is computed from `command`, so it cannot disagree with it; it is omitted, never `null`, when the command has no faithful argv form. The operational control contracts (`control.next_action`, `allowed_next_commands`, verifier repairs) carry the string only: recover argv there with `shlex.split(command)`, which is exact on every platform because every emitted command is POSIX-rendered. Never use `shell=True`, and do not paste `command` into `cmd.exe` or PowerShell. Durable artifacts (`report.json`, `packet.*`) stay canonical so that same inputs still produce the same report. See [docs/diagnostics.md](docs/diagnostics.md#invocation-policy).
461471

‎CHANGELOG.md‎

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,30 @@
3434
invocation for the manifest on disk, which reports what that manifest still
3535
owes. The exit code and the sentence a person acts on are unchanged.
3636

37+
**A refused write must not lose what the run asked for.** `init --write`
38+
over a manifest that already exists hands the caller onward — to the gate on
39+
the refresh path, to `doctor` on the plain one. Both read a manifest that
40+
loads fine and advance under the pack it selects, so
41+
`init --write --control-pack financial-strict` over a `default` manifest
42+
proceeded under `default` with nothing in the route saying the request had
43+
been dropped. That route now names `policies.control_pack` and the exact
44+
value, and only reaches the onward step when the manifest already matches.
45+
For the same reason, every recovery command `init` publishes repeats the
46+
**whole** invocation with only the invalid value corrected: they were built
47+
from the smaller flag list a rerun in a *different* workspace may repeat, so
48+
`init --write --minimal --control-pack <bad>` emitted a recovery without
49+
`--minimal` and following it wrote a detected manifest where a legacy
50+
template was asked for.
51+
52+
**`execution` is not a marker for "this line is an error".** The `error`
53+
field is. `execution` says whether the command reached an answer about the
54+
workspace, and both values occur on error lines: `"failed"` where it could
55+
not, `"succeeded"` beside a non-zero `exit_code` where it did and the answer
56+
is a refusal it can route past — `config_already_exists`, the resume of the
57+
adoption walk itself. What every setup error line does guarantee, in the
58+
published schema: `decision_source: "setup"`, a setup-vocabulary `decision`,
59+
every `permissions` field false, and never `control_state: "complete"`.
60+
3761
**Proved by walking it.** `tests/test_adoption_walk.py` takes an unadopted
3862
repository from `verify --preview` to a release decision as real
3963
subprocesses, choosing every step from the envelope alone — no
@@ -42,7 +66,9 @@
4266
asks for at each step (one vocabulary, one typed rank-1 action, setup and
4367
gate states naming their source, setup authorizing nothing, the gate's
4468
decision equal to `report.json`'s) and fails a step that hands back the same
45-
action for an unchanged subject, which is how the route above was found.
69+
action for an unchanged subject, which is how the route above was found. The
70+
recovery routes are followed rather than read: the test runs the emitted
71+
command and looks at the manifest it produced.
4672

4773
- **The declaration continuation: a drafted proposal can now reach the person
4874
it was drafted for.** (#429 review) `apply-patches --kinds declare_action`

‎STABILITY.md‎

Lines changed: 51 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -28,13 +28,29 @@ left the error stream out; `doctor`'s failure routes picked it up during that
2828
rollout, and `detect`'s and five of `init`'s did not. So whether a caller
2929
that routes on `control` could route at all depended on which setup command had
3030
failed and on which of its failures — and the run that most needs a route is
31-
the one that printed no payload to carry it. Additive: `next_action` and
32-
`next_actions[]` are unchanged on those lines and are derived from the same
33-
selected route as `control.next_action`.
34-
35-
A setup failure envelope is fail-closed by construction, and a consumer may
36-
rely on it: `execution: "failed"`, `decision: "setup_incomplete"`,
37-
`decision_source: "setup"`, and every field of `permissions` false.
31+
the one that printed no payload to carry it. The `next_action` and
32+
`next_actions[]` **fields** are unchanged on those lines, and are derived from
33+
the same selected route as `control.next_action`; two of their command *values*
34+
move, and both are listed under "Routing behaviour" below.
35+
36+
**What a consumer may rely on across every setup error line**, enforced by the
37+
published schema and not only by the producer: `decision_source: "setup"`, a
38+
`decision` from `setup_complete | setup_incomplete | setup_not_applicable`,
39+
every field of `permissions` false, and `control_state` never `complete`.
40+
Setup authorizes nothing, on either stream.
41+
42+
**`execution` is not a stream marker, and must not be read as one.** The
43+
`error` field is what says a line is an error. `execution` answers a different
44+
question — whether the command reached an answer about the workspace — and both
45+
values occur on error lines:
46+
47+
| `execution` | When | Examples |
48+
| ----------- | ---- | -------- |
49+
| `"failed"` | The command could not reach an answer. | An unparseable `--control-pack` or `--agent-instructions` value, discovery that could not be bounded, a manifest that could not be opened or decoded, a generated manifest that failed validation. |
50+
| `"succeeded"`, with a non-zero `exit_code` | The command reached an answer and that answer is a refusal it can route past. | `config_already_exists` (`init --write` declining to overwrite), and the unresolved-scope `config_error`. |
51+
52+
Do not infer authority from either value: the row above that says `"succeeded"`
53+
still carries `permissions` all false, because it is a setup envelope.
3854

3955
**Two error lines still carry no `control`, by design.** The shared
4056
`--workspace` refusal (`config_error`, exit 2, emitted by every command that
@@ -45,7 +61,9 @@ and `check` error lines are also unchanged: the first two answer through their
4561
control pointer, and `check` — which publishes no pointer — through
4662
`--format agent-control-json`.
4763

48-
**One routing behaviour changes, and it is not additive.** `init --write` over
64+
**Routing behaviour: three changes, none of them additive.**
65+
66+
**1.** `init --write` over
4967
a manifest that already exists published `next_action.kind: "edit"` on
5068
`shipgate.yaml` with `expects: "The manifest reflects the desired tool sources,
5169
agent declared_purpose, and policies"`. That postcondition was already
@@ -57,7 +75,31 @@ It is now `next_action.kind: "command"` naming the `doctor` invocation for the
5775
manifest on disk, which reports what that manifest still owes. Exit code 2 and
5876
the "already exists — edit it directly or remove it before re-running init
5977
--write" sentence are unchanged; a consumer that branched on
60-
`next_action.kind == "edit"` here now sees `"command"`.
78+
`next_action.kind == "edit"` here now sees `"command"` — **except** when this
79+
invocation asked for a manifest configuration the existing manifest does not
80+
carry. `init --write --control-pack <id>` over a manifest selecting a different
81+
pack now routes to an `edit` naming `policies.control_pack` and the exact value,
82+
because both onward routes would otherwise advance under the pack that is
83+
*there* and the request would be lost without anything saying so. "Asked for"
84+
means `--control-pack` at other than its default, the same rule that decides
85+
whether a recovery command repeats the flag.
86+
87+
**2.** Every recovery command `init` publishes now repeats the **whole**
88+
invocation with only the invalid value corrected. They were built from the
89+
smaller flag list that a rerun in a *different* workspace may repeat, so
90+
`init --write --minimal --control-pack <bad>` emitted a recovery without
91+
`--minimal` — following it wrote an auto-detected manifest instead of the legacy
92+
template that was asked for. `--minimal`, `--allow-unresolved-scope`,
93+
`--agent-instructions-kit`, and a non-default `--max-python-files` now ride
94+
along. Command *values* change; no field is added or removed.
95+
96+
**3.** The `internal_error` route for a generated manifest that fails validation
97+
named a bare `agents-shipgate init --minimal`. It now names the same invocation
98+
with `--minimal` added — the workspace, `--write`, and `--json` are carried
99+
through, so following it writes the fallback template where the caller asked
100+
for it rather than in the process directory. This is a `next_action` /
101+
`next_actions[0].command` value change on a route that is now also
102+
`control.next_action.command`.
61103

62104
---
63105

‎docs/agent-contract-current.md‎

Lines changed: 36 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,12 +19,26 @@ route at all depended on which setup command had failed and on which of its
1919
failures — a caller cannot branch on that, and the run that most needs a route
2020
is the one that printed no payload to carry it.
2121

22-
Nothing is removed. `next_action` (single string) and `next_actions[]` (ranked
22+
No field is removed. `next_action` (single string) and `next_actions[]` (ranked
2323
array) are unchanged on those lines, and are derived from the same selected
2424
route as `control.next_action`, so the three cannot send you to different work.
25-
The failure envelope is fail-closed by construction: `execution: "failed"`,
26-
`decision: "setup_incomplete"`, and — setup authorizing nothing — every field
27-
of `permissions` false.
25+
Three *command values* do move, and they are listed at the end of this section.
26+
27+
**What every setup error line guarantees**, in the published schema and not
28+
only in the producer: `decision_source: "setup"`, a `decision` from
29+
`setup_complete | setup_incomplete | setup_not_applicable`, every field of
30+
`permissions` false, and `control_state` never `complete`. Setup authorizes
31+
nothing, on either stream.
32+
33+
**Do not read `execution` as "this is an error line".** The `error` field says
34+
that. `execution` answers whether the command reached an answer about the
35+
workspace, and both values appear on error lines: `"failed"` when it could not
36+
(an unparseable flag value, discovery that could not be bounded, a manifest it
37+
could not open), and `"succeeded"` with a non-zero `exit_code` when it did and
38+
the answer is a refusal it can route past — `config_already_exists` from
39+
`init --write` declining to overwrite, and the unresolved-scope `config_error`.
40+
The second kind still carries `permissions` all false, because it is still a
41+
setup envelope.
2842

2943
**One stated exception.** The shared `--workspace` refusal (`config_error`,
3044
exit 2, emitted by every command that takes a `--workspace`) carries
@@ -51,6 +65,24 @@ invocation for the manifest on disk, which reports what that manifest still
5165
owes. The exit code (2) and the "already exists — edit it directly or remove
5266
it" sentence are unchanged.
5367

68+
**Unless the request was not applied.** `init --write --control-pack <id>` over
69+
a manifest that selects a different pack keeps an `edit` route, now naming
70+
`policies.control_pack` and the exact value. Both onward routes would otherwise
71+
advance under the pack that is *there*, and the request would be lost with
72+
nothing saying so — a recovery that completes with less than the caller asked
73+
for reports success for work it did not do. "Asked for" means `--control-pack`
74+
at other than its default, the same rule that decides whether a recovery
75+
command repeats the flag.
76+
77+
**Two command values also move.** Every recovery `init` publishes now repeats
78+
the whole invocation with only the invalid value corrected — `--minimal`,
79+
`--allow-unresolved-scope`, `--agent-instructions-kit`, and a non-default
80+
`--max-python-files` ride along, where before they were dropped; and the
81+
`internal_error` fallback names this invocation with `--minimal` added instead
82+
of a bare `agents-shipgate init --minimal` that ran in the process directory.
83+
These are `command` value changes on `next_action`, `next_actions[0]`, and
84+
`control.next_action` alike, which are one route.
85+
5486
Both the `AgentControl` union and `shipgate.agent_control/v1` are
5587
byte-identical to v26 — the same envelope reaches one more place — so
5688
`minimum_control_contract_version` stays at `21`.

‎docs/errors.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
"yes",
1111
"on"
1212
],
13-
"stderr_format": "Single JSON line, one object per emitted error. Always carries an `error` field naming the kind plus `next_action` (single-string back-compat) and `next_actions` (ranked array). Additional fields per kind are command-dependent and may be absent when they are not relevant. `message`, `next_action`, and `next_actions[]` are written for a person to act on and name files, symbols, and manifest keys rather than internal identity fields; a `details` object, where a kind emits one, carries those identifiers for routing and bug reports. An error line from `detect`, `init`, or `doctor` also carries `control` \u2014 the same `shipgate.agent_control/v1` envelope those commands publish on `--json`, so one routing rule covers both streams (contract v27). It always reports `execution: \"failed\"`, `decision: \"setup_incomplete\"`, and every `permissions` field false. Two lines carry no `control` by design: the shared `--workspace` refusal, which fires before a workspace exists, and `environment_error`, which is emitted before Agents Shipgate is running.",
13+
"stderr_format": "Single JSON line, one object per emitted error. Always carries an `error` field naming the kind plus `next_action` (single-string back-compat) and `next_actions` (ranked array). Additional fields per kind are command-dependent and may be absent when they are not relevant. `message`, `next_action`, and `next_actions[]` are written for a person to act on and name files, symbols, and manifest keys rather than internal identity fields; a `details` object, where a kind emits one, carries those identifiers for routing and bug reports. An error line from `detect`, `init`, or `doctor` also carries `control` \u2014 the same `shipgate.agent_control/v1` envelope those commands publish on `--json`, so one routing rule covers both streams (contract v27). Every such envelope reports `decision_source: \"setup\"`, a `decision` from the setup vocabulary, every `permissions` field false, and never `control_state: \"complete\"`. `execution` is NOT a marker for \"this is an error\" \u2014 the `error` field is: it reports `\"failed\"` when the command could not reach an answer about the workspace, and `\"succeeded\"` beside a non-zero `exit_code` when it reached one and the answer is a refusal it can route past (`config_already_exists`, the unresolved-scope `config_error`). Two lines carry no `control` by design: the shared `--workspace` refusal, which fires before a workspace exists, and `environment_error`, which is emitted before Agents Shipgate is running.",
1414
"exit_codes": {
1515
"0": "pass (advisory mode, or strict-no-blockers)",
1616
"2": "configuration, catalog lookup, or patch-payload error (config_error, config_already_exists, unknown_check_id, unknown_fingerprint, malformed_patch)",

‎docs/passed-verdict-contract.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Evidence-backed `passed` verdict
22

3-
In the Agents Shipgate `0.16.0b7` runtime (contract v26, report schema v0.42),
3+
In the Agents Shipgate `0.16.0b7` runtime (contract v27, report schema v0.42),
44
`release_decision.decision: passed` means the configured root
55
agent and its complete reachable tool/handoff graph were statically proven,
66
and every reachable capability has complete, conflict-free static identity,

0 commit comments

Comments
 (0)