@sabaiway/agent-workflow-kit 5.9.0 → 5.11.0

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

@@ -0,0 +1,235 @@
+// agy-envelope.test.mjs — the envelope parse and the CLI boundary, both driven IN-PROCESS: no
+// subprocess, ever. The parse suites are pure; the CLI suite writes real temporary files under one
+// mkdtemp root, because its failure arms ARE filesystem failures (an unreadable payload, an
+// unwritable destination) and stubbing them would test the stub.
+// Fixtures are INLINE (the packed tarball bans fixtures/ directories) and REDACTED per the plan's
+// Decision 7: no local absolute path, no real conversation id. The payload below is the RECORDED
+// bytes of a live `agy --output-format json` run with only its id replaced, so the test really
+// parses what the CLI printed rather than something this file serialized for itself.
+
+import { describe, it, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { parseAgyEnvelope, runEnvelopeCli } from './agy-envelope.mjs';
+
+const REDACTED_ID = '00000000-1111-2222-3333-444444444444';
+
+const RECORDED_RESPONSE = [
+  '### Delivery proof',
+  'part 1 line 7: alpha-bravo-charlie-delta',
+  'Requested addresses, one per line:',
+  'part 1 line 7',
+  '### Verdict',
+  'SHIP — probe run, nothing reviewed.',
+  '### Blocking',
+  'none',
+  '### Non-blocking',
+  'none',
+  '### Questions',
+  'none',
+  '',
+].join('\n');
+
+const RECORDED_PAYLOAD = `{"conversation_id":"${REDACTED_ID}","status":"SUCCESS","response":"### Delivery proof\\npart 1 line 7: alpha-bravo-charlie-delta\\nRequested addresses, one per line:\\npart 1 line 7\\n### Verdict\\nSHIP — probe run, nothing reviewed.\\n### Blocking\\nnone\\n### Non-blocking\\nnone\\n### Questions\\nnone\\n","duration_seconds":3.640368748,"num_turns":1,"usage":{"input_tokens":16398,"output_tokens":187,"thinking_tokens":118,"cache_read_tokens":0,"total_tokens":16585}}`;
+
+const withFields = (fields) => JSON.stringify({ conversation_id: REDACTED_ID, status: 'SUCCESS', response: 'body', ...fields });
+
+describe('agy-envelope — a recorded envelope parses', () => {
+  it('yields the response text byte-for-byte and the conversation id', () => {
+    const result = parseAgyEnvelope(RECORDED_PAYLOAD, { requireConversationId: true });
+    assert.equal(result.ok, true, result.sentence);
+    assert.equal(result.response, RECORDED_RESPONSE, 'the model Markdown survives the envelope VERBATIM');
+    assert.equal(result.conversationId, REDACTED_ID);
+  });
+
+  it('an EMPTY response is a real answer, not an unreadable envelope (the verdict-less arm owns it)', () => {
+    const result = parseAgyEnvelope(withFields({ response: '' }));
+    assert.equal(result.ok, true, result.sentence);
+    assert.equal(result.response, '');
+  });
+});
+
+describe('agy-envelope — every failure carries its OWN named cause', () => {
+  for (const [name, payload, cause] of [
+    ['empty input', '', 'empty-payload'],
+    ['a non-JSON blob', 'jetski: no output produced\n', 'not-json'],
+    ['JSON that is not one object', '[{"status":"SUCCESS","response":"body"}]', 'not-an-envelope'],
+    // `null` is a LEGAL JSON document and the obvious failure sentinel at once — it must report
+    // what it actually is, or the operator hunts a transport bug that is really a shape bug.
+    ['the literal JSON document `null`', 'null', 'not-an-envelope'],
+    ['a bare JSON string', '"just a string"', 'not-an-envelope'],
+    ['a bare JSON number', '42', 'not-an-envelope'],
+    ['valid JSON with no response field', '{"conversation_id":"x","status":"SUCCESS"}', 'response'],
+    ['a non-string response', withFields({ response: 42 }), 'response'],
+    ['a non-SUCCESS status', withFields({ status: 'ERROR' }), 'status'],
+    ['an absent status', '{"response":"body"}', 'status'],
+  ]) {
+    it(`${name} → cause "${cause}"`, () => {
+      const result = parseAgyEnvelope(payload);
+      assert.equal(result.ok, false, `${name} must not parse`);
+      assert.equal(result.cause, cause);
+      assert.ok(result.sentence.length > 0, 'a cause without a sentence tells the operator nothing');
+    });
+  }
+});
+
+// The id is required ONLY when the caller declares it will route a later turn at this conversation.
+// Failing a single-turn review over a field it never uses would be a refusal with no defect behind it.
+describe('agy-envelope — the conversation id is validated exactly when it is needed', () => {
+  for (const [name, payload] of [
+    ['an absent id', '{"status":"SUCCESS","response":"body"}'],
+    ['a non-string id', withFields({ conversation_id: 12345 })],
+    ['an id failing the UUID grammar', withFields({ conversation_id: 'not-a-uuid' })],
+    ['a TRUNCATED uuid', withFields({ conversation_id: '00000000-1111-2222-3333-4444444444' })],
+  ]) {
+    it(`${name} fails with cause "conversation-id" when routing is required`, () => {
+      const result = parseAgyEnvelope(payload, { requireConversationId: true });
+      assert.equal(result.ok, false);
+      assert.equal(result.cause, 'conversation-id');
+    });
+
+    it(`${name} parses fine when routing is NOT required`, () => {
+      const result = parseAgyEnvelope(payload);
+      assert.equal(result.ok, true, result.sentence);
+      assert.equal(result.response, 'body');
+      assert.equal(result.conversationId, '', 'an unrequested id is never handed back as if it were validated');
+    });
+  }
+});
+
+// ── evidence: the plan's REJECTED and DEFERRED decisions stay checkable ──────────────────────────
+// STRUCTURAL EXCERPTS of two recorded probes (redacted). Nothing here is claimed byte-complete —
+// only the fields the Appendix really recorded are asserted.
+
+// Probe C: probe A's prompt with a schema ON — the matched control for the schema-cost claim.
+const SCHEMA_RUN_RESULT = {
+  conversation_id: REDACTED_ID,
+  status: 'SUCCESS',
+  response: 'the full prose review, with the structured JSON appended as trailing text',
+  duration_seconds: 6.718974944,
+  num_turns: 2,
+  usage: { input_tokens: 33165, output_tokens: 281, thinking_tokens: 185, cache_read_tokens: 0, total_tokens: 33446 },
+};
+
+// The stream-json `init` event of the same run — the ONLY place the ACTUALLY resolved model appears.
+const STREAM_INIT_EVENT = {
+  event: 'init',
+  conversation_id: REDACTED_ID,
+  init: { model: 'Gemini 3.7 Flash (High)', cwd: '<redacted local path>', permission_mode: 'request-review' },
+};
+
+// ── the CLI boundary, driven IN-PROCESS ──────────────────────────────────────────────────────────
+// Every CLI arm RETURNS its outcome, so each one is exercised here rather than through a spawn.
+// That is not a convenience: coverage is collected in the test process, so an arm reachable only
+// through a subprocess is an arm nothing can prove was ever run. Real temp files, no subprocess.
+const CLI_ROOT = mkdtempSync(join(tmpdir(), 'agy-envelope-cli-'));
+after(() => rmSync(CLI_ROOT, { recursive: true, force: true }));
+
+const cliCase = (name, payload) => {
+  const dir = join(CLI_ROOT, name);
+  mkdirSync(dir, { recursive: true });
+  const envelope = join(dir, 'envelope.json');
+  writeFileSync(envelope, payload);
+  return { envelope, responseOut: join(dir, 'response.txt'), conversationIdOut: join(dir, 'conv.txt'), dir };
+};
+
+describe('agy-envelope — the CLI boundary returns an outcome for every arm', () => {
+  it('a complete invocation writes the response VERBATIM and the conversation id, exit 0', () => {
+    const c = cliCase('ok', RECORDED_PAYLOAD);
+    const outcome = runEnvelopeCli(['--envelope', c.envelope, '--response-out', c.responseOut, '--conversation-id-out', c.conversationIdOut]);
+    assert.equal(outcome.code, 0, outcome.message);
+    assert.equal(readFileSync(c.responseOut, 'utf8'), RECORDED_RESPONSE);
+    assert.equal(readFileSync(c.conversationIdOut, 'utf8'), REDACTED_ID);
+  });
+
+  it('without --conversation-id-out no id file is written and the id is never required', () => {
+    const c = cliCase('no-id', withFields({ conversation_id: 'not-a-uuid' }));
+    const outcome = runEnvelopeCli(['--envelope', c.envelope, '--response-out', c.responseOut]);
+    assert.equal(outcome.code, 0, outcome.message);
+    assert.equal(readFileSync(c.responseOut, 'utf8'), 'body');
+  });
+
+  for (const [name, argv, fragment] of [
+    ['an unknown argument', ['--bogus', 'x'], "unknown argument '--bogus'"],
+    ['a flag with no value', ['--envelope'], '--envelope needs a value'],
+    ['a flag swallowing the next flag', ['--envelope', '--response-out'], '--envelope needs a value'],
+    ['a missing --envelope', ['--response-out', '/dev/null'], '--envelope is required'],
+    ['a missing --response-out', ['--envelope', '/dev/null'], '--response-out is required'],
+  ]) {
+    it(`${name} is a USAGE refusal (exit 2) carrying the usage text`, () => {
+      const outcome = runEnvelopeCli(argv);
+      assert.equal(outcome.code, 2, `${name}: ${outcome.message}`);
+      assert.ok(outcome.message.includes(fragment), `${name}: ${outcome.message}`);
+      assert.ok(outcome.message.includes('Usage:'), 'a usage refusal prints the usage');
+    });
+  }
+
+  it('an unreadable payload (a DIRECTORY at the path) is the named unreadable-payload cause', () => {
+    const c = cliCase('unreadable', '{}');
+    const outcome = runEnvelopeCli(['--envelope', c.dir, '--response-out', c.responseOut]);
+    assert.equal(outcome.code, 1, outcome.message);
+    assert.ok(outcome.message.includes('unreadable-payload'), outcome.message);
+  });
+
+  it('a payload that is not valid UTF-8 is the named not-utf8 cause', () => {
+    const dir = join(CLI_ROOT, 'not-utf8');
+    mkdirSync(dir, { recursive: true });
+    const envelope = join(dir, 'envelope.json');
+    writeFileSync(envelope, Buffer.from([0x7b, 0xff, 0xfe, 0x7d]));
+    const outcome = runEnvelopeCli(['--envelope', envelope, '--response-out', join(dir, 'r.txt')]);
+    assert.equal(outcome.code, 1, outcome.message);
+    assert.ok(outcome.message.includes('not-utf8'), outcome.message);
+  });
+
+  it('a parse failure rides out as its own named cause (exit 1), not as usage', () => {
+    const c = cliCase('bad-json', 'not json at all');
+    const outcome = runEnvelopeCli(['--envelope', c.envelope, '--response-out', c.responseOut]);
+    assert.equal(outcome.code, 1, outcome.message);
+    assert.ok(outcome.message.includes('not-json'), outcome.message);
+  });
+
+  it('an unwritable response destination is the named write-failed cause', () => {
+    const c = cliCase('unwritable-response', RECORDED_PAYLOAD);
+    const outcome = runEnvelopeCli(['--envelope', c.envelope, '--response-out', join(c.dir, 'no-such-dir', 'r.txt')]);
+    assert.equal(outcome.code, 1, outcome.message);
+    assert.ok(outcome.message.includes('write-failed'), outcome.message);
+    assert.ok(outcome.message.includes('response'), 'the failing field is named');
+  });
+
+  it('an unwritable conversation-id destination is named too — the response write already succeeded', () => {
+    const c = cliCase('unwritable-id', RECORDED_PAYLOAD);
+    const outcome = runEnvelopeCli([
+      '--envelope', c.envelope, '--response-out', c.responseOut,
+      '--conversation-id-out', join(c.dir, 'no-such-dir', 'conv.txt'),
+    ]);
+    assert.equal(outcome.code, 1, outcome.message);
+    assert.ok(outcome.message.includes('conversation_id'), outcome.message);
+    assert.equal(readFileSync(c.responseOut, 'utf8'), RECORDED_RESPONSE, 'the response was already written');
+  });
+});
+
+describe('agy-envelope — recorded evidence for the rejected and deferred decisions', () => {
+  it('--json-schema is REJECTED: it buys a SECOND billed turn, not a constrained decode', () => {
+    const plain = JSON.parse(RECORDED_PAYLOAD);
+    assert.equal(plain.num_turns, 1, 'the plain envelope answers in ONE turn');
+    assert.equal(SCHEMA_RUN_RESULT.num_turns, 2, 'the schema run answers in TWO — the model restates its own prose');
+    assert.ok(
+      SCHEMA_RUN_RESULT.usage.total_tokens > 2 * plain.usage.total_tokens,
+      `matched control: ${plain.usage.total_tokens} tokens without a schema against ${SCHEMA_RUN_RESULT.usage.total_tokens} with one`,
+    );
+  });
+
+  it('stream-json is DEFERRED for a real gain: the RESOLVED model rides `init` and nothing else', () => {
+    assert.equal(typeof STREAM_INIT_EVENT.init.model, 'string', 'the init event names the model that actually answered');
+    assert.ok(!Object.hasOwn(JSON.parse(RECORDED_PAYLOAD), 'model'), 'the plain envelope carries no resolved model');
+    assert.ok(!Object.hasOwn(SCHEMA_RUN_RESULT, 'model'), 'and neither does the stream-json result event');
+  });
+
+  it('the parse ignores the envelope fields it does not need — an added CLI field is not a breakage', () => {
+    const result = parseAgyEnvelope(JSON.stringify({ ...SCHEMA_RUN_RESULT, structured_output: { verdict: 'REWORK' } }));
+    assert.equal(result.ok, true, result.sentence);
+    assert.equal(result.response, SCHEMA_RUN_RESULT.response);
+  });
+});

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

@@ -16,11 +16,33 @@ import { spawnSync } from 'node:child_process';
 const HERE = dirname(fileURLToPath(import.meta.url));
 const WRAPPER = join(HERE, 'agy-review.sh');
 
+// Same shape as the sibling spec's fake, minimally: --help / --version answer the wrapper's
+// pre-spend capability door WITHOUT touching the invocation sentinel (a probe is not a paid
+// dispatch), and the answer leaves as an `--output-format json` envelope when the dispatch asked
+// for one — the model's text rides `response` VERBATIM.
+const FAKE_ENVELOPE_ENCODER = [
+  'const text = require("node:fs").readFileSync(0, "utf8");',
+  'const envelope = { conversation_id: "11111111-2222-3333-4444-555555555555", status: "SUCCESS",',
+  '  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 } };',
+  'process.stdout.write(`${JSON.stringify(envelope)}\\n`);',
+].join('\n');
+
 const FAKE_AGY = [
   '#!/usr/bin/env bash',
   'set -u',
+  'case "${1:-}" in',
+  '  --help|-h) printf "  --output-format\\n  --disable-slash-commands\\n"; exit 0 ;;',
+  '  --version) printf "1.1.13\\n"; exit 0 ;;',
+  'esac',
   'printf invoked > "${AGY_FAKE_SENTINEL:-/dev/null}"',
-  'printf "%s\\n" "${AGY_FAKE_OUTPUT:-### Verdict}"',
+  'aw_fmt=""',
+  'prev=""; for a in "$@"; do if [[ "$prev" == "--output-format" ]]; then aw_fmt="$a"; fi; prev="$a"; done',
+  'if [[ "$aw_fmt" == "json" ]]; then',
+  `  printf "%s\\n" "\${AGY_FAKE_OUTPUT:-### Verdict}" | node -e '${FAKE_ENVELOPE_ENCODER}'`,
+  'else',
+  '  printf "%s\\n" "${AGY_FAKE_OUTPUT:-### Verdict}"',
+  'fi',
   'exit 0',
   '',
 ].join('\n');

package/bridges/antigravity-cli-bridge/bin/agy-review.sh

@@ -80,6 +80,18 @@ Grounding:
   AGY_PROBE=1); plan/diff proceed with a loud warning
 
 Notes:
+  transport: every review dispatch drives the CLI in --output-format json (plus
+  --disable-slash-commands) and the returned envelope is parsed in node (bin/agy-envelope.mjs) — the
+  operator-facing invocations and flags above do NOT change, and on a ZERO exit the wrapper still
+  PRINTS the review text, never JSON. A missing or unreadable envelope on a zero exit is a loud
+  failure with NO receipt, never a downgraded verdict and never a fallback to raw-stdout parsing; a
+  non-zero CLI exit keeps its own code and message, and publishes the captured stdout unchanged from
+  the SINGLE dispatch or the FINAL fed turn (which may therefore be a JSON or partial payload — the
+  envelope is parsed only on a zero exit); an INTERMEDIATE feed turn is the exception, its output
+  stays private (Invariant E) and its failure prints only a named error. Enforced by a PRE-SPEND
+  capability probe, not a version floor: agy --help must advertise --output-format and
+  --disable-slash-commands, node must be >= 22, and bin/agy-envelope.mjs must be present — otherwise
+  the review refuses before any run is spent and names the missing capability
   pre-dispatch host-diff: before the FIRST dispatch of this bridge, diff its declared networkHosts
   against the live sandbox allow-list — a missing host is surfaced to the maintainer BEFORE
   dispatching, never fired into a known prompt
@@ -326,7 +338,7 @@ DEFAULT_AGY_REVIEW_MODEL="Gemini 3.7 Flash (High)"
 # Review-receipt identity (AD-038). AW_BRIDGE_VERSION mirrors this bridge's SKILL.md/capability.json
 # version (drift-guarded by agy-review.test.mjs against capability.json).
 AW_RECEIPT_BACKEND="agy"
-AW_BRIDGE_VERSION="5.2.0"  # aw-version-anchor
+AW_BRIDGE_VERSION="5.3.0"  # aw-version-anchor
 # `-` not `:-` so an EXPLICIT empty AGY_MODEL= survives (drop --model, use settings.json — agy.sh:52).
 AGY_MODEL="${AGY_MODEL-$DEFAULT_AGY_REVIEW_MODEL}"
 # D5 control-byte screen — IMMEDIATELY after resolution, BEFORE the off-frontier advisory (or any
@@ -455,7 +467,68 @@ FED_ECHO_MAX_BYTES=200
 # address nobody requested and FAILS the proof, rather than vanishing from the check entirely.
 FED_PROOF_ADDRESS_MAX=1000000000
 
-HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# This wrapper's REAL directory, symlinks RESOLVED. The managed install puts a symlink on PATH
+# (~/.local/bin/agy-review -> <placed skill>/bin/agy-review.sh), so an unresolved BASH_SOURCE names
+# the LINK's directory — and every sibling payload below, the envelope reader most of all, would be
+# looked for beside the link instead of beside the script. `readlink -f` is GNU-only (macOS ships
+# BSD readlink), so the chain is walked by hand; `cd -P` resolves a symlinked directory too.
+# The walk is HOP-BOUNDED with a loud refusal, never an unbounded loop. A symlink CYCLE cannot be
+# reached by construction — the kernel already resolved this path to exec the script and would have
+# failed with ELOOP — but it becomes reachable if a link is rewritten in the window between exec and
+# this walk, and an unbounded `while` would then spin until something killed it. Past the bound the
+# wrapper refuses BY NAME rather than guessing at a directory: a wrong answer here sends every
+# sibling lookup somewhere arbitrary. 16 is far above any managed install (which uses ONE hop) and
+# below the kernel's own chain limit, so it never truncates a real chain.
+AW_SCRIPT_LINK_MAX_HOPS=16
+aw_script_dir() {
+  local src="${BASH_SOURCE[0]}" dir hops=0
+  while [[ -L "$src" ]]; do
+    if (( hops >= AW_SCRIPT_LINK_MAX_HOPS )); then
+      echo "error: resolving this wrapper's own path exceeded ${AW_SCRIPT_LINK_MAX_HOPS} symlink hops at" >&2
+      echo "       '$src' — a symlink cycle, or an absurd chain." >&2
+      return 1
+    fi
+    hops=$(( hops + 1 ))
+    dir="$(cd -P "$(dirname "$src")" && pwd)" || return 1
+    src="$(readlink "$src")" || return 1
+    case "$src" in /*) ;; *) src="$dir/$src" ;; esac
+  done
+  ( cd -P "$(dirname "$src")" && pwd )
+}
+if ! HERE="$(aw_script_dir)"; then
+  echo "error: this wrapper could not resolve its OWN directory, so the sibling payload every review" >&2
+  echo "       depends on cannot be located. Refusing before anything is spent — repair the link, or" >&2
+  echo "       invoke the real script path." >&2
+  exit 127
+fi
+
+# --- The dispatch transport (AGY-1.1.13, Decision 1) ---------------------------
+# EVERY review dispatch runs `--output-format json`: the CLI then answers with ONE envelope whose
+# `response` carries the model's Markdown VERBATIM, so the wrapper reads a NAMED FIELD instead of
+# guessing at raw stdout. The review CONTRACT is untouched — the model is asked for exactly what it
+# was asked for before; only the wrapper's reading of the answer moved.
+# `--disable-slash-commands` rides the same array: a change set is delivered as prompt TEXT, and a
+# body line that happens to begin with a slash command is body — never an instruction for the CLI to
+# expand. It is also what makes the pre-spend door below honest: that door refuses an install whose
+# --help does not advertise this flag, and a door may never require a capability the wrapper leaves
+# unused.
+AGY_TRANSPORT_FLAGS=(--output-format json --disable-slash-commands)
+AGY_ENVELOPE_READER="$HERE/agy-envelope.mjs"
+# A captured answer that is not a readable envelope on a ZERO exit (Decision 3). Its own code, not
+# the D4 verdict-less 4: those are different failures and an operator must be able to tell them
+# apart — D4 means the model answered without a verdict, this means the CLI's answer never arrived
+# in the shape this wrapper reads.
+AGY_ENVELOPE_EXIT=5
+
+# Read ONE captured envelope through the sibling module. This PRINTS NOTHING on success — the caller
+# decides what reaches stdout, which is exactly what keeps Invariant E intact when a feed turn's
+# envelope has to be validated without ever becoming operator-visible. A failure is loud and carries
+# the module's own named cause on stderr.
+read_agy_envelope() {  # $1 = captured payload, $2 = response destination, $3 = "" | conversation-id destination
+  local args=(--envelope "$1" --response-out "$2")
+  if [[ -n "${3:-}" ]]; then args+=(--conversation-id-out "$3"); fi
+  node "$AGY_ENVELOPE_READER" "${args[@]}"
+}
 
 # --- Subscription invariant (reuse agy.sh's security pattern verbatim) --------
 export PATH="$HOME/.local/bin:$PATH"
@@ -499,6 +572,106 @@ if ! grep -q "AGY_REQUIRE_TIMEOUT_BIN" "$aw_child_path" 2>/dev/null; then
   exit 127
 fi
 
+# --- Pre-spend capability door (AGY-1.1.13, Decision 2) ------------------------
+# This wrapper drives the CLI in `--output-format json`, passes --disable-slash-commands, and reads
+# the returned envelope in node. A host that cannot do all three must refuse BEFORE a subscription
+# turn is spent — never after a paid run returns something unreadable.
+# A version FLOOR is deliberately NOT the door: the release that introduced --output-format is not
+# measurable from one installed build, so a guessed floor would refuse working installs. The door
+# probes the CAPABILITY the dispatch actually uses instead — the flags `agy --help` advertises, plus
+# a usable node. A probe that FAILS is never read as "capability present" (fail closed).
+AW_REQUIRED_AGY_FLAGS=(--output-format --disable-slash-commands)
+AW_MIN_NODE_MAJOR=22
+aw_agy_version() {
+  local v
+  v="$(agy --version 2>/dev/null | LC_ALL=C awk 'NR == 1 { print }' || true)"
+  printf '%s' "${v:-unknown}"
+}
+set +e
+aw_help_probe="$(agy --help 2>&1)"
+aw_help_rc=$?
+set -e
+if (( aw_help_rc != 0 )); then
+  echo "error: could not read the agy capability list — 'agy --help' exited ${aw_help_rc}. A failed probe is" >&2
+  echo "       NEVER read as 'capability present', so this review refuses BEFORE any run is spent." >&2
+  echo "       Installed agy version: $(aw_agy_version). Repair the install, then re-run; to update: agy update" >&2
+  exit 127
+fi
+# The DECLARED option tokens of the probed help, never a substring search: `--output-formatting`, or
+# the flag merely NAMED in prose, would both open the door to a build that cannot honour the flag.
+# A line contributes only when its first non-space character is a dash, and only its DECLARATION
+# SEGMENT counts — the part before the description column, which help renderers separate by a run of
+# two or more spaces or a tab. Inside that segment EVERY dash-token declares (so `-o FORMAT,
+# --output-format FORMAT` declares both and a metavar declares nothing), and `--flag=<value>`
+# declares `--flag`.
+# Stated residual: a renderer that separates its columns by a SINGLE space has no machine-readable
+# boundary at all, and a description beginning with a flag name would read as a declaration there.
+# No such rendering is known; the guarantee below is the column convention, not a parse of English.
+aw_declared_flags="$(printf '%s\n' "$aw_help_probe" | LC_ALL=C awk '
+  {
+    line = $0
+    sub(/^[ \t]+/, "", line)
+    if (substr(line, 1, 1) != "-") next
+    if (match(line, /  +|\t/)) line = substr(line, 1, RSTART - 1)
+    n = split(line, token, /[ \t,]+/)
+    for (i = 1; i <= n; i++) {
+      t = token[i]
+      sub(/=.*$/, "", t)
+      if (substr(t, 1, 1) == "-") print t
+    }
+  }')"
+# What each required capability BUYS — the refusal names the cost of the flag that is actually
+# missing. One blanket explanation would be false for half of them: a build without
+# --disable-slash-commands answers perfectly readably and corrupts the delivered BODY instead, and an
+# operator sent hunting an unreadable envelope would be hunting the wrong bug.
+# The subject is a NAMED local, never "$1": the source-level reverse guard reads every `case "$1"`
+# as an argument-parser arm, and this table is not one.
+aw_agy_flag_cost() {  # $1 = required flag
+  local flag="$1"
+  case "$flag" in
+    --output-format) printf '%s' 'the answer arrives as ONE JSON envelope this wrapper reads; without it a spent turn answers in a shape the wrapper cannot read' ;;
+    --disable-slash-commands) printf '%s' 'a change-set line beginning with a slash command stays BODY; without it the CLI expands it and the model reviews something other than the delivered bytes' ;;
+    *) printf '%s' 'this dispatch passes the flag and the installed build does not declare it' ;;
+  esac
+}
+aw_missing_flags=()
+for _flag in "${AW_REQUIRED_AGY_FLAGS[@]}"; do
+  case $'\n'"$aw_declared_flags"$'\n' in
+    *$'\n'"$_flag"$'\n'*) ;;
+    *) aw_missing_flags+=("$_flag") ;;
+  esac
+done
+if (( ${#aw_missing_flags[@]} > 0 )); then
+  echo "error: the installed agy CLI does not advertise the flag(s) this review dispatch passes: ${aw_missing_flags[*]}" >&2
+  echo "       Refusing BEFORE any run is spent — what each missing capability costs:" >&2
+  for _flag in "${aw_missing_flags[@]}"; do
+    echo "         ${_flag} — $(aw_agy_flag_cost "$_flag")" >&2
+  done
+  echo "       Installed agy version: $(aw_agy_version). Update the CLI: agy update" >&2
+  exit 127
+fi
+if ! command -v node >/dev/null 2>&1; then
+  echo "error: 'node' is not on PATH, and this review parses agy's JSON envelope in node (Node >= ${AW_MIN_NODE_MAJOR})." >&2
+  echo "       Refusing BEFORE any run is spent. Install Node >= ${AW_MIN_NODE_MAJOR}, then re-run." >&2
+  exit 127
+fi
+aw_node_version="$(node --version 2>/dev/null || true)"
+aw_node_major="${aw_node_version#v}"
+aw_node_major="${aw_node_major%%.*}"
+if [[ ! "$aw_node_major" =~ ^[0-9]+$ ]] || (( aw_node_major < AW_MIN_NODE_MAJOR )); then
+  echo "error: node '${aw_node_version:-<unreadable>}' is below the family floor (Node >= ${AW_MIN_NODE_MAJOR}) this review needs" >&2
+  echo "       to parse agy's JSON envelope. Refusing BEFORE any run is spent." >&2
+  echo "       Upgrade Node to >= ${AW_MIN_NODE_MAJOR}, then re-run." >&2
+  exit 127
+fi
+if [[ ! -f "$AGY_ENVELOPE_READER" ]]; then
+  echo "error: the envelope reader '$AGY_ENVELOPE_READER' is missing — every review reads agy's JSON" >&2
+  echo "       envelope through it, so a bridge install without it could only fail AFTER a paid run." >&2
+  echo "       Refusing BEFORE any run is spent. Refresh the placed bridges:" >&2
+  echo "         /agent-workflow-kit setup --refresh-placed" >&2
+  exit 127
+fi
+
 # --- Model policy (advisory, NOT a gate) -------------------------------------
 is_frontier=0
 for _m in "${FRONTIER_SET[@]}"; do
@@ -1026,20 +1199,6 @@ fixed_occurrences() {
   printf '%s' "$(( n ))"
 }
 
-# The conversation id agy writes into its own run log (D9, Arm A). The format is agy's own to change,
-# which is exactly why an unparseable log DEGRADES LOUDLY to --continue instead of failing: the
-# correctness guarantee is the D1 echo proof, which fails closed if the wrong conversation answers.
-capture_conversation_id() {  # $1 = run log → the id, or empty
-  local id
-  [[ -f "$1" ]] || { printf ''; return 0; }
-  id="$(LC_ALL=C awk '/onversation/ && match($0, /[0-9a-fA-F]+-[0-9a-fA-F]+-[0-9a-fA-F]+-[0-9a-fA-F]+-[0-9a-fA-F]+/) { print substr($0, RSTART, RLENGTH); exit }' "$1")"
-  if [[ "$id" =~ ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ ]]; then
-    printf '%s' "$id"
-  else
-    printf ''
-  fi
-}
-
 # A validated duration string → integer seconds (floor 1). The fed lane needs arithmetic on the cap
 # because ONE wall-clock budget has to cover N+1 turns; the banner keeps printing the duration
 # verbatim, so this conversion never changes what the user is told about the cap itself.
@@ -1186,7 +1345,8 @@ verify_delivery_proof() {  # $1 = captured final-turn output
 # produced (an OK, or a premature verdict) reaches this wrapper's stdout or the parsed capture, and
 # the FIRST non-zero feed turn stops the run so no later turn is spent.
 run_fed_review() {
-  local k conv_id="" log_file="$staging/turn1.log" feed_out="$staging/feed-turn-out" turn_rc turn_pass=()
+  local k conv_id="" conv_id_file="$staging/turn1-conversation-id" feed_out="$staging/feed-turn-out" turn_rc turn_pass=()
+  local final_envelope="$staging/final-envelope"
   # ONE wall-clock budget for the WHOLE fed review, not one per turn. Handing every call the full
   # AGY_HARD_TIMEOUT multiplied the stated cap by the turn count — a 30m cap silently became up to
   # 30m × (N+1). Each turn now gets only what is LEFT of the shared deadline, and a review that runs
@@ -1214,9 +1374,8 @@ run_fed_review() {
     budget=$(( remaining - AGY_TURN_KILL_GRACE_S ))
     turn_hard="${budget}s"
     turn_soft="$(( soft_budget < budget ? soft_budget : budget ))s"
-    if (( k == 1 )); then turn_pass=(--log-file "$log_file")
-    elif [[ -n "$conv_id" ]]; then turn_pass=(--conversation "$conv_id")
-    else turn_pass=(--continue)
+    if (( k == 1 )); then turn_pass=()
+    else turn_pass=(--conversation "$conv_id")
     fi
     set +e
     # Dispatched from the STAGING dir, never the work tree: agy surfaces the cwd's context file
@@ -1225,7 +1384,7 @@ run_fed_review() {
     # byte the model can read, so the fed lane removes the uncontrolled input instead of guessing
     # at it. Nothing is lost: the grounded facts already carry what the review must know.
     ( cd "$staging" && AGY_MODEL="$AGY_MODEL" AGY_TIMEOUT="$turn_soft" AGY_HARD_TIMEOUT="$turn_hard" \
-      "$AGY_RUN" "@$staging/turn-$k" -- "${turn_pass[@]}" ) > "$feed_out"
+      "$AGY_RUN" "@$staging/turn-$k" -- "${AGY_TRANSPORT_FLAGS[@]}" "${turn_pass[@]}" ) > "$feed_out"
     turn_rc=$?
     set -e
     if (( turn_rc != 0 )); then
@@ -1233,16 +1392,34 @@ run_fed_review() {
       echo "       delivered, so no later turn is spent and NO receipt is written. Re-run the review." >&2
       return "$turn_rc"
     fi
+    # Invariant E: a feed turn's envelope is validated PRIVATELY. Its response — an OK, or the
+    # premature verdict a misbehaving turn might emit — reaches neither stdout nor the parsed
+    # capture; only its READABILITY is consumed here. A turn that exited 0 without answering in the
+    # shape this wrapper reads stops the run before any later turn is spent.
+    # Turn 1 ALSO takes the conversation id, from the envelope's NAMED field, validated against the
+    # UUID grammar by the reader. Every later turn is then routed at THIS conversation — there is no
+    # --continue lane left to guess with, so an id that is absent, wrong-typed or malformed is the
+    # same class of loud stop as an unreadable envelope, before turn 2 is spent.
+    set +e
     if (( k == 1 )); then
-      conv_id="$(capture_conversation_id "$log_file")"
-      if [[ -z "$conv_id" ]]; then
-        echo "notice: could not capture the conversation id from agy's run log — the remaining turns ride" >&2
-        echo "        --continue instead. Stated, never silent; the delivery proof still fails closed if" >&2
-        echo "        another conversation answers." >&2
-      fi
+      read_agy_envelope "$feed_out" "$staging/feed-turn-response" "$conv_id_file"
+    else
+      read_agy_envelope "$feed_out" "$staging/feed-turn-response"
     fi
+    turn_rc=$?
+    set -e
+    if (( turn_rc != 0 )); then
+      echo "error: feed turn ${k} of ${FED_PART_COUNT} exited 0 but its answer is not a usable agy JSON" >&2
+      echo "       envelope — unreadable, or (turn 1) carrying no routable conversation id; cause above." >&2
+      echo "       Delivery cannot be confirmed, so no later turn is spent and NO receipt is written." >&2
+      echo "       Re-run the review." >&2
+      return "$AGY_ENVELOPE_EXIT"
+    fi
+    if (( k == 1 )); then conv_id="$(cat "$conv_id_file")"; fi
   done
-  if [[ -n "$conv_id" ]]; then turn_pass=(--conversation "$conv_id"); else turn_pass=(--continue); fi
+  # The partitioner refuses a zero-part change set, so this loop ran at least once: either turn 1 set
+  # a grammar-valid conv_id or the run already returned above.
+  turn_pass=(--conversation "$conv_id")
   remaining=$(( deadline - $(date +%s) ))
   if (( remaining <= AGY_TURN_KILL_GRACE_S )); then
     echo "error: the fed review exhausted its hard wall-clock cap (AGY_HARD_TIMEOUT=${AGY_HARD_TIMEOUT}) before the" >&2
@@ -1256,8 +1433,20 @@ run_fed_review() {
   turn_soft="$(( soft_budget < budget ? soft_budget : budget ))s"
   set +e
   ( cd "$staging" && AGY_MODEL="$AGY_MODEL" AGY_TIMEOUT="$turn_soft" AGY_HARD_TIMEOUT="$turn_hard" \
-    "$AGY_RUN" "@$staging/turn-final" -- "${turn_pass[@]}" ) | tee "$review_out_file"
-  turn_rc=${PIPESTATUS[0]}
+    "$AGY_RUN" "@$staging/turn-final" -- "${AGY_TRANSPORT_FLAGS[@]}" "${turn_pass[@]}" ) > "$final_envelope"
+  turn_rc=$?
+  if (( turn_rc == 0 )); then
+    if ! read_agy_envelope "$final_envelope" "$review_out_file"; then
+      set -e
+      echo "error: the final review turn exited 0 but its answer is not a readable agy JSON envelope" >&2
+      echo "       (cause above). The review is UNREADABLE, not merely verdict-less: NO receipt was" >&2
+      echo "       written. Re-run the review." >&2
+      return "$AGY_ENVELOPE_EXIT"
+    fi
+    cat "$review_out_file"
+  else
+    cat "$final_envelope"
+  fi
   set -e
   return "$turn_rc"
 }
@@ -1807,21 +1996,36 @@ aw_timeout_banner="$(aw_timeout_label "$aw_review_timeout_bin" "$AGY_HARD_TIMEOU
 echo "review posture: model=${AGY_MODEL:-<agy settings default>} timeout=$aw_timeout_banner" >&2
 
 # --- Execute via agy-run (single home of timeout + subscription + byte ceiling) ---
-# The output is teed into the private staging dir so the mandated '### Verdict' section can be
-# parsed into the review receipt — the user-facing stream is unchanged.
+# The dispatch is captured PRIVATELY as an envelope and its `response` becomes both the
+# operator-visible stream and the parsed capture — one source, so what the reader sees and what the
+# receipt attests can never diverge.
+# Error priority (Decision 4): the CLI's OWN failure wins. The envelope is parsed only on a ZERO
+# exit; on a non-zero one the captured stdout is republished untouched and the CLI's exit code and
+# its stderr survive, with no envelope-parse error layered over them.
 review_out_file="$staging/review-output"
+envelope_file="$staging/review-envelope"
+dispatch_flags=("${AGY_TRANSPORT_FLAGS[@]}")
+if (( ${#run_passthrough[@]} > 0 )); then dispatch_flags+=("${run_passthrough[@]}"); fi
 set +e
 if (( FED_MODE == 1 )); then
   run_fed_review
   rc=$?
-elif (( ${#run_passthrough[@]} > 0 )); then
-  AGY_MODEL="$AGY_MODEL" AGY_TIMEOUT="$AGY_TIMEOUT" AGY_HARD_TIMEOUT="$AGY_HARD_TIMEOUT" \
-    "$AGY_RUN" "@$prompt_file" -- "${run_passthrough[@]}" | tee "$review_out_file"
-  rc=${PIPESTATUS[0]}
 else
   AGY_MODEL="$AGY_MODEL" AGY_TIMEOUT="$AGY_TIMEOUT" AGY_HARD_TIMEOUT="$AGY_HARD_TIMEOUT" \
-    "$AGY_RUN" "@$prompt_file" | tee "$review_out_file"
-  rc=${PIPESTATUS[0]}
+    "$AGY_RUN" "@$prompt_file" -- "${dispatch_flags[@]}" > "$envelope_file"
+  rc=$?
+  if (( rc == 0 )); then
+    if ! read_agy_envelope "$envelope_file" "$review_out_file"; then
+      set -e
+      echo "error: the dispatch exited 0 but its answer is not a readable agy JSON envelope (cause above)." >&2
+      echo "       The review is UNREADABLE, not merely verdict-less: NO receipt was written. Re-run the" >&2
+      echo "       review; if it recurs, the installed CLI is not honouring --output-format json." >&2
+      exit "$AGY_ENVELOPE_EXIT"
+    fi
+    cat "$review_out_file"
+  else
+    cat "$envelope_file"
+  fi
 fi
 set -e