You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit f3b1339
Browse filesBrowse the repository at this point in the historyBrowse 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]>
Copy file name to clipboardExpand all lines: AGENTS.md
+18-8Lines changed: 18 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -448,14 +448,24 @@ obligation.
448
448
(contract v27). A setup command that could not finish publishes the same
449
449
envelope on stderr that it would have published on stdout, so one routing rule
450
450
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`.
459
469
460
470
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).
Copy file name to clipboardExpand all lines: STABILITY.md
+51-9Lines changed: 51 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -28,13 +28,29 @@ left the error stream out; `doctor`'s failure routes picked it up during that
28
28
rollout, and `detect`'s and five of `init`'s did not. So whether a caller
29
29
that routes on `control` could route at all depended on which setup command had
30
30
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.
38
54
39
55
**Two error lines still carry no `control`, by design.** The shared
40
56
`--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
45
61
control pointer, and `check` — which publishes no pointer — through
46
62
`--format agent-control-json`.
47
63
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
49
67
a manifest that already exists published `next_action.kind: "edit"` on
50
68
`shipgate.yaml` with `expects: "The manifest reflects the desired tool sources,
51
69
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
57
75
manifest on disk, which reports what that manifest still owes. Exit code 2 and
58
76
the "already exists — edit it directly or remove it before re-running init
59
77
--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
Copy file name to clipboardExpand all lines: docs/errors.json
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -10,7 +10,7 @@
10
10
"yes",
11
11
"on"
12
12
],
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.",
14
14
"exit_codes": {
15
15
"0": "pass (advisory mode, or strict-no-blockers)",
0 commit comments