@sabaiway/agent-workflow-kit 5.9.0 → 5.11.0

package/bridges/antigravity-cli-bridge/bin/agy-review.test.mjs

@@ -18,18 +18,70 @@ const WRAPPER = join(HERE, 'agy-review.sh');
 // --add-dir escape — the staging dir's perms + the offloaded artifact's perms/contents WHILE they
 // still exist (agy-review's trap removes the staging dir on exit). Kept inline so the file is
 // standalone (the kit mirror is byte-equality; no shared helper grows that set).
+// The envelope `agy --output-format json` returns: ONE object whose `response` carries the model's
+// text VERBATIM. Encoded in node so an arbitrary body (quotes, backslashes, multibyte) round-trips
+// exactly — hand-rolled JSON quoting in bash is the defect farm this fake exists to avoid.
+const FAKE_ENVELOPE_ENCODER = [
+  'const text = require("node:fs").readFileSync(0, "utf8");',
+  'const [cid, status, shape] = process.argv.slice(1);',
+  'const envelope = { conversation_id: cid, status, response: text, duration_seconds: 1.5, num_turns: 1,',
+  '  usage: { input_tokens: 10, output_tokens: 5, thinking_tokens: 0, cache_read_tokens: 0, total_tokens: 15 } };',
+  // The fed lane ROUTES later turns at this field, so the two ways it can be present-but-unusable —
+  // absent, and present with the wrong TYPE — are knobs, not just a bad-grammar string.
+  'if (shape === "missing") delete envelope.conversation_id;',
+  'if (shape === "number") envelope.conversation_id = 42;',
+  'process.stdout.write(`${JSON.stringify(envelope)}\\n`);',
+].join('\n');
+
 const FAKE_AGY = [
   '#!/usr/bin/env bash',
   'set -u',
+  // A capability probe is NOT a paid dispatch: --help / --version answer BEFORE any capture file is
+  // touched, so the wrapper's pre-spend door can never read as a spent run (the sentinel) nor shift
+  // the fed lane's per-turn counter. Keyed on the FIRST argument like the real CLI, so a prompt that
+  // merely CONTAINS "--help" is never intercepted.
+  'case "${1:-}" in',
+  '  --help|-h)',
+  '    if [[ -n "${AGY_FAKE_HELP_EXIT:-}" ]]; then echo "fake agy: help unavailable" >&2; exit "$AGY_FAKE_HELP_EXIT"; fi',
+  '    for f in --output-format --json-schema --disable-slash-commands --effort --mode; do',
+  '      if [[ "$f" == "${AGY_FAKE_HELP_OMIT:-}" ]]; then continue; fi',
+  '      printf "  %s   fake capability line\\n" "$f"',
+  '    done',
+  '    if [[ -n "${AGY_FAKE_HELP_EXTRA:-}" ]]; then printf "%s\\n" "$AGY_FAKE_HELP_EXTRA"; fi',
+  '    exit 0 ;;',
+  '  --version) printf "%s\\n" "${AGY_FAKE_VERSION:-1.1.13}"; exit 0 ;;',
+  'esac',
   ': "${AGY_FAKE_ARGV:=/dev/null}"',
   ': "${AGY_FAKE_ENV:=/dev/null}"',
   ': "${AGY_FAKE_PROMPT:=/dev/null}"',
   ': "${AGY_FAKE_SENTINEL:=/dev/null}"',
   'printf invoked > "$AGY_FAKE_SENTINEL"',
+  // The fed lane dispatches from the private staging dir (deliberately — see the wrapper), so the
+  // fake's own cwd is the only handle a test has on a directory the exit trap then removes.
+  'printf "%s" "$PWD" > "${AGY_FAKE_CWD:-/dev/null}"',
   '{ for a in "$@"; do printf "%s\\n" "$a"; done; } > "$AGY_FAKE_ARGV"',
   '{ echo "FOO_API_KEY=${FOO_API_KEY:-<unset>}"; echo "ANTIGRAVITY_API_KEY=${ANTIGRAVITY_API_KEY:-<unset>}"; } > "$AGY_FAKE_ENV"',
   'prompt=""',
   'prev=""; for a in "$@"; do if [[ "$prev" == "-p" ]]; then prompt="$a"; printf "%s" "$a" > "$AGY_FAKE_PROMPT"; fi; prev="$a"; done',
+  // Every answer leaves through ONE emitter, so the transport is a property of the INVOCATION
+  // (`--output-format json` ⇒ an envelope, otherwise text) and every existing output knob keeps
+  // meaning exactly what it meant. AGY_FAKE_RAW_STDOUT bypasses the encoder entirely — the
+  // unparseable-payload arm; AGY_FAKE_STDERR is the CLI's own diagnostic.
+  'aw_fmt=""',
+  'prev=""; for a in "$@"; do if [[ "$prev" == "--output-format" ]]; then aw_fmt="$a"; fi; prev="$a"; done',
+  // AGY_FAKE_BAD_TURN scopes the two transport-breaking knobs to ONE turn: a fed run whose turn 1
+  // answers normally and whose turn 2 does not is the only way to reach the "no LATER turn is spent"
+  // arms — an unscoped knob breaks turn 1 and the run never gets there.
+  'aw_fake_emit() {',
+  '  local body="$1" aw_status="${AGY_FAKE_STATUS:-SUCCESS}" aw_raw=""',
+  '  if [[ -n "${AGY_FAKE_RAW_STDOUT+x}" ]]; then aw_raw=1; fi',
+  '  if [[ -n "${AGY_FAKE_BAD_TURN:-}" && "$turn" != "${AGY_FAKE_BAD_TURN}" ]]; then aw_status="SUCCESS"; aw_raw=""; fi',
+  '  if [[ -n "${AGY_FAKE_STDERR:-}" ]]; then printf "%s\\n" "$AGY_FAKE_STDERR" >&2; fi',
+  '  if [[ -n "$aw_raw" ]]; then printf "%s" "$AGY_FAKE_RAW_STDOUT"; return 0; fi',
+  '  if [[ "$aw_fmt" != "json" ]]; then printf "%s\\n" "$body"; return 0; fi',
+  `  printf "%s\\n" "$body" | node -e '${FAKE_ENVELOPE_ENCODER}' \\`,
+  '    "${AGY_FAKE_CONV_ID:-11111111-2222-3333-4444-555555555555}" "$aw_status" "${AGY_FAKE_CONV_SHAPE:-ok}"',
+  '}',
   'prev=""; for a in "$@"; do',
   '  if [[ "$prev" == "--add-dir" ]]; then',
   '    printf "%s" "$a" > "${AGY_FAKE_ADDDIR:-/dev/null}"',
@@ -49,14 +101,6 @@ const FAKE_AGY = [
   '  printf "%s" "$prompt" > "${AGY_FAKE_PROMPT}.$turn"',
   '  { for a in "$@"; do printf "%s\\n" "$a"; done; } > "${AGY_FAKE_ARGV}.$turn"',
   'fi',
-  // agy writes the conversation id into its --log-file; AGY_FAKE_BAD_CONV_LOG=1 writes a log the
-  // wrapper cannot parse (the D9 degrade arm).
-  'prev=""; for a in "$@"; do',
-  '  if [[ "$prev" == "--log-file" ]]; then',
-  '    if [[ "${AGY_FAKE_BAD_CONV_LOG:-}" == "1" ]]; then printf "no conversation marker here\\n" > "$a"',
-  '    else printf "Starting new conversation %s\\n" "${AGY_FAKE_CONV_ID:-11111111-2222-3333-4444-555555555555}" > "$a"; fi',
-  '  fi; prev="$a"',
-  'done',
   'if [[ -n "${AGY_FAKE_FAIL_TURN:-}" && "$turn" == "${AGY_FAKE_FAIL_TURN}" ]]; then',
   '  printf "FAKE_TURN_FAILURE\\n" >&2; exit 3',
   'fi',
@@ -64,7 +108,7 @@ const FAKE_AGY = [
   // PREMATURE verdict — so the isolation invariant (feed output never reaches stdout or the parsed
   // capture) is proven against the worst case, not the polite one.
   'if [[ -z "${AGY_FAKE_OUTPUT+x}" && "$prompt" == *"--- BEGIN CHANGE-SET PART "* && "$prompt" != *"Requested addresses"* ]]; then',
-  '  printf "PREMATURE_FEED_CHATTER\\n### Verdict\\nREWORK\\n"; exit 0',
+  '  aw_fake_emit "$(printf "PREMATURE_FEED_CHATTER\\n### Verdict\\nREWORK")"; exit 0',
   'fi',
   // The FINAL turn carries the delivery-proof request. The fake answers it the only honest way:
   // by reading the bodies it was actually fed, turn by turn — so a wrapper that never delivered a
@@ -93,20 +137,23 @@ const FAKE_AGY = [
   '  done',
   '  if [[ "${AGY_FAKE_PROOF_EXTRA:-}" == "1" ]]; then entries+=("part 99 line 1: an address nobody asked for"); fi',
   '  if [[ "${AGY_FAKE_PROOF_HUGE_EXTRA:-}" == "1" ]]; then entries+=("part 99999999999999999999 line 1: an invented giant address"); fi',
-  '  if [[ "${AGY_FAKE_PROOF_LATE:-}" == "1" ]]; then printf "### Verdict\\nSHIP\\n"; fi',
-  '  if [[ "${AGY_FAKE_PROOF_CASE:-}" == "1" ]]; then printf "### Delivery Proof\\n"; else printf "### Delivery proof\\n"; fi',
-  '  if [[ "${AGY_FAKE_PROOF_OUTSIDE:-}" == "1" ]]; then',
-  '    printf "(nothing here)\\n### Verdict\\nSHIP\\n"',
-  '    if (( ${#entries[@]} > 0 )); then printf "%s\\n" "${entries[@]}"; fi',
-  '  else',
-  '    if (( ${#entries[@]} > 0 )); then printf "%s\\n" "${entries[@]}"; fi',
-  '    printf "### Verdict\\nSHIP\\n"',
-  '  fi',
+  '  out="$( {',
+  '    if [[ "${AGY_FAKE_PROOF_LATE:-}" == "1" ]]; then printf "### Verdict\\nSHIP\\n"; fi',
+  '    if [[ "${AGY_FAKE_PROOF_CASE:-}" == "1" ]]; then printf "### Delivery Proof\\n"; else printf "### Delivery proof\\n"; fi',
+  '    if [[ "${AGY_FAKE_PROOF_OUTSIDE:-}" == "1" ]]; then',
+  '      printf "(nothing here)\\n### Verdict\\nSHIP\\n"',
+  '      if (( ${#entries[@]} > 0 )); then printf "%s\\n" "${entries[@]}"; fi',
+  '    else',
+  '      if (( ${#entries[@]} > 0 )); then printf "%s\\n" "${entries[@]}"; fi',
+  '      printf "### Verdict\\nSHIP\\n"',
+  '    fi',
+  '  } )"',
+  '  aw_fake_emit "$out"',
   '  exit 0',
   'fi',
   // Unset AGY_FAKE_OUTPUT → a verdict-carrying default (D4: a verdict-less run is a FAILURE, so
   // the success-path tests need one); an EXPLICIT empty value exercises the empty-output failure.
-  'if [[ -z "${AGY_FAKE_OUTPUT+x}" ]]; then printf "FAKE_AGY_REVIEW_OUTPUT\\n### Verdict\\nSHIP\\n"; else printf "%s\\n" "$AGY_FAKE_OUTPUT"; fi',
+  'if [[ -z "${AGY_FAKE_OUTPUT+x}" ]]; then aw_fake_emit "$(printf "FAKE_AGY_REVIEW_OUTPUT\\n### Verdict\\nSHIP")"; else aw_fake_emit "$AGY_FAKE_OUTPUT"; fi',
   'exit "${AGY_FAKE_EXIT:-0}"',
   '',
 ].join('\n');
@@ -176,7 +223,7 @@ const makeSandbox = ({ clean = false } = {}) => {
 // Capture files are per-INVOCATION: a second run() on the same sandbox must not inherit the first
 // run's turn counter or per-turn prompt files (the fed lane reads them back by turn index).
 let runSeq = 0;
-const run = (sb, { args, env = {}, cwd } = {}) => {
+const run = (sb, { args, env = {}, cwd, wrapper } = {}) => {
   const { home, bin, repo } = sb;
   const farm = farmFor(['agy', 'agy-run']);
   const tag = `cap-${++runSeq}`;
@@ -185,8 +232,9 @@ const run = (sb, { args, env = {}, cwd } = {}) => {
     sentinel: join(home, `${tag}-sentinel`), adddir: join(home, `${tag}-adddir`),
     adddirMode: join(home, `${tag}-adddir-mode`), artifactMode: join(home, `${tag}-artifact-mode`),
     artifactCopy: join(home, `${tag}-artifact-copy`), turns: join(home, `${tag}-turns`),
+    dispatchCwd: join(home, `${tag}-dispatch-cwd`),
   };
-  const r = spawnSync('bash', [WRAPPER, ...args], {
+  const r = spawnSync('bash', [wrapper || WRAPPER, ...args], {
     cwd: cwd || repo,
     encoding: 'utf8',
     timeout: 30000,
@@ -199,7 +247,7 @@ const run = (sb, { args, env = {}, cwd } = {}) => {
       AGY_FAKE_ARGV: cap.argv, AGY_FAKE_ENV: cap.env, AGY_FAKE_PROMPT: cap.prompt,
       AGY_FAKE_SENTINEL: cap.sentinel, AGY_FAKE_ADDDIR: cap.adddir, AGY_FAKE_ADDDIR_MODE: cap.adddirMode,
       AGY_FAKE_ARTIFACT_MODE: cap.artifactMode, AGY_FAKE_ARTIFACT_COPY: cap.artifactCopy,
-      AGY_FAKE_TURNS: cap.turns,
+      AGY_FAKE_TURNS: cap.turns, AGY_FAKE_CWD: cap.dispatchCwd,
       ...env,
     },
   });
@@ -218,7 +266,7 @@ const run = (sb, { args, env = {}, cwd } = {}) => {
     argv: readIf(cap.argv), capEnv: readIf(cap.env), prompt: readIf(cap.prompt),
     adddir: readIf(cap.adddir).trim(), adddirMode: readIf(cap.adddirMode).trim(),
     artifactMode: readIf(cap.artifactMode).trim(), artifactCopy: readIf(cap.artifactCopy),
-    turns, prompts, argvs,
+    dispatchCwd: readIf(cap.dispatchCwd).trim(), turns, prompts, argvs,
   };
 };
 
@@ -298,6 +346,355 @@ describe('agy-review.sh — model policy advisory (1)', () => {
   });
 });
 
+// ── the pre-spend capability door (AGY-1.1.13, Decision 2) ───────────────────────────────────────
+// The wrapper drives agy in --output-format json and reads the returned envelope in node, so a host
+// that cannot do that must refuse BEFORE a subscription turn is spent. The door probes CAPABILITY,
+// never a version floor — the release that introduced the flag is unmeasurable from one installed
+// build. Every case asserts ZERO paid dispatch: the fake answers --help/--version without touching
+// the invocation sentinel, so a probe can never read as a spent run.
+const FAKE_OLD_NODE = '#!/usr/bin/env bash\nprintf "v18.20.0\\n"\n';
+
+describe('agy-review.sh — the pre-spend capability door (Decision 2)', () => {
+  for (const flag of ['--output-format', '--disable-slash-commands']) {
+    it(`a --help that does not advertise ${flag} refuses pre-spend and names it`, () => {
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['code', '--facts', 'f'], env: { AGY_FAKE_HELP_OMIT: flag } });
+      const receipts = readReceipts(sb.repo);
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.notEqual(r.status, 0, r.stderr);
+      assert.equal(r.invoked, false, 'the door refuses BEFORE any paid dispatch');
+      assert.match(r.stderr, /does not advertise the flag/);
+      assert.ok(r.stderr.includes(flag), `the refusal names the missing flag: ${r.stderr}`);
+      assert.equal(receipts.length, 0);
+    });
+  }
+
+  // Each required flag buys something DIFFERENT, so the refusal must name the cost of the flag that
+  // is actually missing: a build lacking --disable-slash-commands answers perfectly readably and
+  // corrupts the delivered BODY instead, which the envelope explanation would send an operator
+  // hunting the wrong bug.
+  it('the refusal names what the MISSING flag buys, not one blanket envelope explanation', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'f'], env: { AGY_FAKE_HELP_OMIT: '--disable-slash-commands' } });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.notEqual(r.status, 0, r.stderr);
+    assert.equal(r.invoked, false);
+    assert.match(r.stderr, /slash command/i, 'the stated cost is command expansion of the change-set body');
+    assert.doesNotMatch(r.stderr, /cannot read/, 'the unreadable-answer cost belongs to --output-format alone');
+  });
+
+  it('`agy --help` exiting non-zero refuses with a DISTINCT cause — never read as "capability present"', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'f'], env: { AGY_FAKE_HELP_EXIT: '3' } });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.notEqual(r.status, 0, r.stderr);
+    assert.equal(r.invoked, false, 'a failed probe never becomes a paid dispatch');
+    assert.match(r.stderr, /'agy --help' exited 3/, 'the failed probe is the stated cause');
+    assert.doesNotMatch(r.stderr, /does not advertise the flag/, 'a failed probe is not a missing-flag verdict');
+  });
+
+  it('node ABSENT refuses pre-spend, naming Node and the floor', () => {
+    const sb = makeSandbox();
+    const r = run(sb, {
+      args: ['code', '--facts', 'f'],
+      env: { PATH: `${sb.bin}:${farmFor(['agy', 'agy-run', 'node'])}` },
+    });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.notEqual(r.status, 0, r.stderr);
+    assert.equal(r.invoked, false);
+    assert.match(r.stderr, /'node' is not on PATH/);
+    assert.match(r.stderr, /Node >= 22/);
+  });
+
+  it('node PRESENT but BELOW the floor refuses pre-spend — the version comparison really runs', () => {
+    const sb = makeSandbox();
+    // Into $HOME/.local/bin, which the wrapper itself prepends — so the fake wins over the real node.
+    writeFileSync(join(sb.bin, 'node'), FAKE_OLD_NODE, { mode: 0o755 });
+    const r = run(sb, { args: ['code', '--facts', 'f'] });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.notEqual(r.status, 0, r.stderr);
+    assert.equal(r.invoked, false, 'an existence-only check would have dispatched here');
+    assert.match(r.stderr, /v18\.20\.0/, 'the refusal quotes the version it read');
+    assert.match(r.stderr, /below the family floor \(Node >= 22\)/);
+  });
+
+  // The door reads option DECLARATIONS, not substrings. A near-miss flag and a prose mention are the
+  // two ways a substring search opens the door to a build that cannot honour the flag — and the
+  // failure would then surface only AFTER a subscription turn was already spent.
+  for (const [name, extraHelpLine] of [
+    ['a NEAR-MISS flag name', '  --output-formatting   a longer flag that is not the one we pass'],
+    ['a prose mention outside any declaration', 'Note: pass --output-format json to get structured output.'],
+    ['the flag named inside ANOTHER option`s description', '  --json-schema   enforce structured output; see --output-format'],
+    ['another option whose description BEGINS with the flag name', '  --other   --output-format is unsupported on this build'],
+  ]) {
+    it(`${name} does NOT open the door — an option declaration is required`, () => {
+      const sb = makeSandbox();
+      const r = run(sb, {
+        args: ['code', '--facts', 'f'],
+        env: { AGY_FAKE_HELP_OMIT: '--output-format', AGY_FAKE_HELP_EXTRA: extraHelpLine },
+      });
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.notEqual(r.status, 0, r.stderr);
+      assert.equal(r.invoked, false, 'a false-positive door would have spent a subscription turn here');
+      assert.match(r.stderr, /does not advertise the flag/);
+      assert.ok(r.stderr.includes('--output-format '), `the refusal still names the flag really missing: ${r.stderr}`);
+    });
+  }
+
+  // The other direction: a declaration the parser fails to READ refuses a build that CAN honour the
+  // flag — the false refusal Decision 2 exists to avoid. Both common clustered renderings count.
+  for (const [name, extraHelpLine] of [
+    ['a comma-clustered alias', '  -o, --output-format   the clustered rendering'],
+    ['a metavar rendering', '  -o FORMAT, --output-format FORMAT   the metavar rendering'],
+    ['an =<value> rendering', '  --output-format=<fmt>   the joined-value rendering'],
+    ['a declaration with no description at all', '  --output-format'],
+  ]) {
+    it(`${name} READS as declared — a capable build is never falsely refused`, () => {
+      const sb = makeSandbox();
+      const r = run(sb, {
+        args: ['code', '--facts', 'f'],
+        env: { AGY_FAKE_HELP_OMIT: '--output-format', AGY_FAKE_HELP_EXTRA: extraHelpLine },
+      });
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.equal(r.status, 0, `${name} must read as a declaration: ${r.stderr}`);
+      assert.equal(r.invoked, true);
+    });
+  }
+
+  it('the agy-capability refusal carries the INSTALLED version and the upgrade command', () => {
+    const sb = makeSandbox();
+    const r = run(sb, {
+      args: ['code', '--facts', 'f'],
+      env: { AGY_FAKE_HELP_OMIT: '--output-format', AGY_FAKE_VERSION: '1.0.9' },
+    });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.notEqual(r.status, 0, r.stderr);
+    assert.match(r.stderr, /Installed agy version: 1\.0\.9/, 'the operator is told what they actually have');
+    assert.match(r.stderr, /agy update/, 'and the command that fixes it');
+  });
+
+  it('a capable host passes the door and still dispatches (the door is not a blanket refusal)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'f'] });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(r.invoked, true);
+  });
+});
+
+// ── characterize-first: what the operator sees TODAY, pinned before the transport moves ──────────
+// Phase 4.1 of the envelope plan. The switch from raw stdout to the CLI's JSON envelope must not
+// change one byte of this: stdout carries the model's answer and NOTHING else (the posture banner
+// is stderr), and the receipt records the verdict parsed out of that same answer. Green before the
+// switch, green after — anything the transport quietly rewrites fails here.
+describe('agy-review.sh — the operator-visible answer, byte-for-byte (characterization)', () => {
+  it('stdout is EXACTLY the model answer, and the receipt records the verdict parsed from it', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(r.stdout, `${VERDICT_OUTPUT}\n`, 'the answer reaches the operator with nothing added and nothing dropped');
+    assert.equal(receipts[0].verdict, 'SHIP WITH NITS', 'and the receipt verdict comes from that same answer');
+  });
+
+  // The bytes a transport is most likely to mangle: blank lines, non-ASCII, quotes, a backslash, a
+  // tab. If the answer ever rides a JSON field, this is the test that catches a lossy round-trip.
+  it('blank lines, multibyte, quotes, backslashes and tabs all survive to stdout unchanged', () => {
+    const answer = [
+      '### Verdict',
+      'SHIP — «clean», no nits.',
+      '',
+      '### Blocking',
+      'none',
+      '',
+      '### Non-blocking',
+      '1. a "quoted" path C:\\tmp\\x and a\ttab',
+      '',
+      '### Questions',
+      'none',
+    ].join('\n');
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_FAKE_OUTPUT: answer } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(r.stdout, `${answer}\n`, 'the answer is transported verbatim');
+    assert.equal(receipts[0].verdict, 'SHIP');
+  });
+});
+
+// ── the dispatch rides agy's structured envelope (Phase 4.3) ─────────────────────────────────────
+// Every lane runs `--output-format json` and the wrapper reads the envelope's `response` instead of
+// raw stdout. The review CONTRACT does not move: the same prompt, the same mandated shape, the same
+// D4 arm. What changes is that a fact the wrapper used to guess at now arrives named.
+describe('agy-review.sh — the dispatch rides the JSON envelope (Phase 4.3)', () => {
+  // The transport is BOTH flags: the envelope carries the answer, and --disable-slash-commands keeps
+  // a change-set line that happens to begin with a slash command as BODY rather than an instruction
+  // the CLI expands. The pre-spend door requires both, so the dispatch must pass both — a door that
+  // demands a capability the wrapper never uses refuses working installs for nothing.
+  const argvCarriesTransport = (argv) => {
+    const tokens = argv.split('\n');
+    const at = tokens.indexOf('--output-format');
+    return at !== -1 && tokens[at + 1] === 'json' && tokens.includes('--disable-slash-commands');
+  };
+
+  it('all three lanes carry the transport flags (single, fed, resume)', () => {
+    const single = makeSandbox();
+    const one = run(single, { args: ['code', '--facts', 'f'] });
+    rmSync(single.home, { recursive: true, force: true });
+    assert.equal(one.status, 0, one.stderr);
+    assert.ok(argvCarriesTransport(one.argv), `single lane argv: ${one.argv}`);
+
+    const fedSb = makeSandbox();
+    seedFedChangeSet(fedSb);
+    const fed = fedRun(fedSb);
+    rmSync(fedSb.home, { recursive: true, force: true });
+    assert.equal(fed.status, 0, fed.stderr);
+    assert.ok(fed.argvs.length >= 3, 'the fixture really chunks');
+    for (const [i, argv] of fed.argvs.entries()) {
+      assert.ok(argvCarriesTransport(argv), `fed turn ${i + 1} argv: ${argv}`);
+    }
+
+    const resumeSb = makeSandbox();
+    const resumed = run(resumeSb, { args: ['--continue'] });
+    rmSync(resumeSb.home, { recursive: true, force: true });
+    assert.equal(resumed.status, 0, resumed.stderr);
+    assert.ok(argvCarriesTransport(resumed.argv), `resume lane argv: ${resumed.argv}`);
+  });
+
+  it('operator-visible stdout IS the envelope response — and a feed turn`s response is neither published nor parsed', () => {
+    const sb = makeSandbox();
+    seedFedChangeSet(sb);
+    const fed = fedRun(sb);
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(fed.status, 0, fed.stderr);
+    assert.ok(fed.stdout.startsWith('### Delivery proof\n'), `stdout must be the FINAL response: ${fed.stdout.slice(0, 80)}`);
+    assert.ok(fed.stdout.endsWith('### Verdict\nSHIP\n'), 'and nothing is appended after it');
+    assert.ok(!fed.stdout.includes('PREMATURE_FEED_CHATTER'), 'a feed turn never publishes');
+    assert.ok(!fed.stdout.includes('conversation_id'), 'the raw envelope never reaches the operator');
+    assert.equal(receipts[0].verdict, 'SHIP', 'only the FINAL response is parsed');
+  });
+
+  it('a non-JSON blob on a ZERO exit is an UNREADABLE review: distinct exit, NO receipt, the cause names the envelope', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'f'], env: { AGY_FAKE_RAW_STDOUT: 'jetski: not an envelope at all\n' } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 5, `an unreadable envelope has its OWN code, not the D4 4: ${r.stderr}`);
+    assert.equal(receipts.length, 0);
+    assert.match(r.stderr, /agy-envelope: not-json/, 'the module names the cause');
+    assert.match(r.stderr, /not a readable agy JSON envelope/, 'and the wrapper says what that means');
+  });
+
+  it('a non-SUCCESS status is unreadable too — its own named cause, NO receipt', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'f'], env: { AGY_FAKE_STATUS: 'ERROR' } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 5, r.stderr);
+    assert.equal(receipts.length, 0);
+    assert.match(r.stderr, /agy-envelope: status/);
+  });
+
+  // Decision 4: the CLI's own failure WINS. The envelope is parsed only on a zero exit, so a
+  // non-zero run keeps its code and its message and never has a parse error layered over it.
+  it('a non-zero CLI exit keeps its code and message on the SINGLE lane — no envelope error replaces them', () => {
+    const sb = makeSandbox();
+    const r = run(sb, {
+      args: ['code', '--facts', 'f'],
+      env: { AGY_FAKE_EXIT: '7', AGY_FAKE_RAW_STDOUT: 'partial plain text\n', AGY_FAKE_STDERR: 'AGY_CLI_OWN_FAILURE' },
+    });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 7, 'the CLI exit code survives verbatim');
+    assert.match(r.stderr, /AGY_CLI_OWN_FAILURE/, 'and so does its own message');
+    assert.doesNotMatch(r.stderr, /agy-envelope:/, 'the envelope is never parsed on a non-zero exit');
+    assert.match(r.stdout, /partial plain text/, 'whatever the CLI printed still reaches the operator');
+    assert.equal(receipts.length, 0);
+  });
+
+  it('a non-zero CLI exit keeps its code and message on the FED lane too', () => {
+    const sb = makeSandbox();
+    seedFedChangeSet(sb);
+    const fed = fedRun(sb, { AGY_FAKE_FAIL_TURN: '2' });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(fed.status, 3, 'the failing turn`s own exit code survives');
+    assert.match(fed.stderr, /FAKE_TURN_FAILURE/);
+    assert.doesNotMatch(fed.stderr, /agy-envelope:/, 'no parse is attempted on a failed turn');
+    assert.equal(fed.turns, 2, 'no later turn is spent');
+    assert.equal(receipts.length, 0);
+  });
+
+  // The switch must not move WHICH arm fires: a readable envelope carrying a verdict-less answer is
+  // still the D4 failed review, exit 4 — not the transport failure.
+  it('a READABLE envelope with no verdict still exits 4 through the EXISTING D4 arm', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'f'], env: { AGY_FAKE_OUTPUT: 'prose without the mandated section' } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 4, 'the D4 arm owns this, not the envelope arm');
+    assert.equal(receipts.length, 0);
+    assert.match(r.stderr, /no recognized '### Verdict' section/);
+    assert.doesNotMatch(r.stderr, /agy-envelope:/, 'the envelope was perfectly readable');
+  });
+
+  // The MANAGED INSTALL shape: `agy-review` on PATH is a SYMLINK into the placed skill
+  // (~/.local/bin/agy-review -> <placed>/bin/agy-review.sh). An unresolved BASH_SOURCE names the
+  // LINK's directory, so every sibling payload — the envelope reader above all — would be looked
+  // for beside the link and EVERY review would refuse pre-spend on a correct install.
+  it('a review launched through a managed SYMLINK resolves its own sibling payload and still attests', () => {
+    const sb = makeSandbox();
+    const linked = join(sb.bin, 'agy-review');
+    symlinkSync(WRAPPER, linked);
+    const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], wrapper: linked });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, `a symlinked launch must behave identically: ${r.stderr}`);
+    assert.equal(r.invoked, true, 'the dispatch really happened');
+    assert.doesNotMatch(r.stderr, /envelope reader .* is missing/, 'the reader is found beside the SCRIPT, not beside the link');
+    assert.equal(receipts.length, 1, 'and the review still attests');
+  });
+
+  // The walk that resolves the wrapper's own directory must TERMINATE. A cycle cannot be reached
+  // through exec (the kernel resolves the path first, and would fail with ELOOP), so the reachable
+  // shape is an absurd CHAIN — and it is testable exactly because the kernel tolerates a far longer
+  // chain than this bound. An unbounded walk spins until the harness kills it and prints nothing,
+  // so the assertion is on the MESSAGE: an infinite loop can never produce it.
+  it('a symlink chain past the hop bound refuses LOUDLY and spends nothing', () => {
+    const sb = makeSandbox();
+    const chainDir = join(sb.home, 'link-chain');
+    mkdirSync(chainDir, { recursive: true });
+    const chainTip = Array.from({ length: 24 }).reduce((previous, _unused, i) => {
+      const link = join(chainDir, `hop-${i}`);
+      symlinkSync(previous, link);
+      return link;
+    }, WRAPPER);
+    const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], wrapper: chainTip });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 127, `the walk must refuse, not spin: ${r.stderr}`);
+    assert.match(r.stderr, /exceeded 16 symlink hops/, 'the refusal names the bound it hit');
+    assert.match(r.stderr, /could not resolve its OWN directory/, 'and what that costs');
+    assert.equal(r.invoked, false, 'nothing is spent');
+  });
+
+  it('the resume lanes parse the envelope and mint the continuation receipt exactly as before', () => {
+    for (const args of [['--continue'], ['--conversation', 'conv-xyz']]) {
+      const sb = makeSandbox();
+      const r = run(sb, { args, env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT } });
+      const receipts = readReceipts(sb.repo);
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.equal(r.status, 0, `${args[0]}: ${r.stderr}`);
+      assert.equal(r.stdout, `${VERDICT_OUTPUT}\n`, `${args[0]}: stdout is the envelope response`);
+      assert.equal(receipts.length, 1);
+      assert.equal(receipts[0].fresh, false, `${args[0]}: a continuation still cannot attest`);
+      assert.equal(receipts[0].verdict, 'SHIP WITH NITS');
+    }
+  });
+});
+
 describe('agy-review.sh — guard + grounding (2, 3)', () => {
   it('the model/cutoff GUARD line is in the captured prompt', () => {
     const sb = makeSandbox();
@@ -573,7 +970,7 @@ const FED_CAP = 6000;
 const seedFedChangeSet = (sb, { lines = 400, multibyte = false } = {}) => {
   const body = Array.from({ length: lines }, (_, i) =>
     multibyte
-      ? `строка ${String(i).padStart(4, '0')} — многобайтовый маркер ${'ю'.repeat(20)}`
+      ? `line ${String(i).padStart(4, '0')} — multibyte marker ${'\u044e'.repeat(20)}`
       : `unique change-set line ${String(i).padStart(4, '0')} — a distinctive body marker ${'x'.repeat(20)}`).join('\n');
   writeFileSync(join(sb.repo, 'oversized.txt'), `${body}\n`);
 };
@@ -943,29 +1340,77 @@ describe('agy-review.sh — the agy permission fact is surfaced, never applied',
   });
 });
 
+// ── fed lane: the conversation id comes from the ENVELOPE (Phase 5.1) ────────────────────────────
+// The id used to be scraped out of agy's own run log — a format that is agy's to change, degrading
+// to `--continue` when it changed. It is now a NAMED envelope field the reader validates against the
+// UUID grammar, so the pin that used to rot SILENTLY now fails LOUDLY: there is no `--continue`
+// fallback left in this lane and no later turn is spent when turn 1 cannot name its conversation.
 describe('agy-review.sh — fed lane: turn targeting (D9)', () => {
-  it('every turn after the first pins the captured conversation id', () => {
+  it('every turn after the first is ROUTED at the id turn 1`s envelope named', () => {
     const sb = makeSandbox();
     seedFedChangeSet(sb);
     const fed = fedRun(sb, { AGY_FAKE_CONV_ID: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' });
     rmSync(sb.home, { recursive: true, force: true });
     assert.equal(fed.status, 0, fed.stderr);
-    assert.match(fed.argvs[0], /(^|\n)--log-file(\n|$)/, 'turn 1 asks agy for its run log');
     assert.ok(!fed.argvs[0].includes('--conversation'), 'turn 1 is fresh');
+    for (const [i, argv] of fed.argvs.entries()) {
+      assert.ok(!argv.includes('--log-file'), `turn ${i + 1} must not ask for a run log any more: ${argv}`);
+      assert.ok(!argv.includes('--continue'), `turn ${i + 1} must never ride the guessing lane: ${argv}`);
+    }
     for (const argv of fed.argvs.slice(1)) {
       assert.match(argv, /(^|\n)--conversation(\n|$)/);
       assert.match(argv, /(^|\n)aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee(\n|$)/);
     }
   });
 
-  it('an unparseable log degrades to --continue with a stated notice, not silently', () => {
-    const sb = makeSandbox();
-    seedFedChangeSet(sb);
-    const fed = fedRun(sb, { AGY_FAKE_BAD_CONV_LOG: '1' });
-    rmSync(sb.home, { recursive: true, force: true });
-    assert.equal(fed.status, 0, fed.stderr);
-    assert.match(fed.stderr, /could not capture the conversation id/, 'the degrade is STATED');
-    for (const argv of fed.argvs.slice(1)) assert.match(argv, /(^|\n)--continue(\n|$)/);
+  // The three ways a NAMED field can still be unusable. Each one would otherwise route every later
+  // turn at an arbitrary conversation, so each stops the run before turn 2 is spent.
+  for (const [name, env] of [
+    ['absent', { AGY_FAKE_CONV_SHAPE: 'missing' }],
+    ['not a string', { AGY_FAKE_CONV_SHAPE: 'number' }],
+    ['failing the UUID grammar', { AGY_FAKE_CONV_ID: 'not-a-conversation-id' }],
+  ]) {
+    it(`a turn-1 conversation id ${name} fails LOUDLY before turn 2, with NO receipt`, () => {
+      const sb = makeSandbox();
+      seedFedChangeSet(sb);
+      const fed = fedRun(sb, env);
+      const receipts = readReceipts(sb.repo);
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.equal(fed.status, 5, `an unusable envelope has the transport code: ${fed.stderr}`);
+      assert.equal(fed.turns, 1, 'no later turn is spent');
+      assert.equal(receipts.length, 0);
+      assert.match(fed.stderr, /agy-envelope: conversation-id/, 'the reader names the field');
+      assert.doesNotMatch(fed.stderr, /--continue/, 'there is no degrade lane to fall back to');
+    });
+  }
+
+  // A LATER turn breaking is a different arm from turn 1 breaking: turn 1 already answered, so the
+  // run has spent real subscription turns and must still stop without attesting anything.
+  for (const [name, env, cause] of [
+    ['whose payload is not an envelope', { AGY_FAKE_BAD_TURN: '2', AGY_FAKE_RAW_STDOUT: 'jetski: not an envelope\n' }, /agy-envelope: not-json/],
+    ['reporting a non-SUCCESS status', { AGY_FAKE_BAD_TURN: '2', AGY_FAKE_STATUS: 'ERROR' }, /agy-envelope: status/],
+  ]) {
+    it(`a fed turn 2 ${name} stops the run: NO receipt, no turn 3`, () => {
+      const sb = makeSandbox();
+      seedFedChangeSet(sb);
+      const fed = fedRun(sb, env);
+      const receipts = readReceipts(sb.repo);
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.equal(fed.status, 5, fed.stderr);
+      assert.equal(fed.turns, 2, 'the failing turn is the last one spent');
+      assert.equal(receipts.length, 0);
+      assert.match(fed.stderr, cause, 'the reader names the cause');
+      assert.match(fed.stderr, /feed turn 2 of/, 'and the wrapper names which turn');
+    });
+  }
+
+  // The doc must not describe BOTH routings at once: a residual recording the retired log scrape
+  // beside the envelope statement leaves an operator unable to tell which lane their build runs.
+  it('the fed-lane doc states envelope routing and keeps no log-scrape residual (doc contract)', () => {
+    const prompt = readFileSync(resolve(HERE, '..', 'references', 'review-prompt.md'), 'utf8');
+    assert.match(prompt, /Later turns are routed by a NAMED field/, 'the live routing is stated');
+    assert.doesNotMatch(prompt, /conversation id is parsed from/i, 'the retired scrape is no longer described as live');
+    assert.doesNotMatch(prompt, /degrades[^\n]*--continue/, 'and neither is its degrade lane');
   });
 });
 
@@ -1289,9 +1734,8 @@ describe('agy-review.sh — size ceiling + gated --add-dir escape (6)', () => {
     const sb = makeSandbox();
     seedFedChangeSet(sb);
     const r = run(sb, { args: ['code', '--facts', 'f'], env: { AGY_MAX_PROMPT_BYTES: String(FED_CAP) } });
-    // Turn 1 hands agy `--log-file <staging>/turn1.log`, so the fed lane's own argv names the dir.
-    const logFile = r.argvs[0].split('\n')[r.argvs[0].split('\n').indexOf('--log-file') + 1];
-    const stagingPath = logFile ? dirname(logFile) : '';
+    // The fed lane dispatches every turn FROM the staging dir, so the fake's own cwd names it.
+    const stagingPath = r.dispatchCwd;
     const stillThere = stagingPath ? existsSync(stagingPath) : false;
     rmSync(sb.home, { recursive: true, force: true });
     assert.ok(stagingPath, 'a staging path was captured from the run');
@@ -1984,7 +2428,7 @@ describe('agy-review.sh — review receipts (AD-038)', () => {
       // The grammar ENUMERATES the ASCII set (no ranges): a locale-collated [A-Za-z] could admit a
       // non-ASCII letter the kit's JS reader then refuses, breaking correlation after a paid run.
       const utf8 = makeSandbox();
-      const r2 = run(utf8, { args: ['code', '--facts', 'a tiny fact'], env: { AW_REVIEW_NONCE: 'ré1', LC_ALL: 'en_US.UTF-8', LANG: 'en_US.UTF-8' } });
+      const r2 = run(utf8, { args: ['code', '--facts', 'a tiny fact'], env: { AW_REVIEW_NONCE: 'r\u00e91', LC_ALL: 'en_US.UTF-8', LANG: 'en_US.UTF-8' } });
       rmSync(utf8.home, { recursive: true, force: true });
       assert.equal(r2.status, 2, 'a non-ASCII nonce letter refuses whatever the locale collation says');
       assert.match(r2.stderr, /safe nonce grammar/);