@sabaiway/agent-workflow-kit 5.8.0 → 5.10.0

package/CHANGELOG.md

@@ -4,6 +4,89 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 5.10.0 — the bundled agy review reads the CLI's own envelope, and refuses a host that cannot honour the dispatch (AD-098; antigravity-cli-bridge 5.3.0, memory 4.5.0)
+
+**A review used to read whatever the CLI happened to print, and recover the conversation id by
+scraping the CLI's run log with a pattern its own comment called "agy's own to change".** Antigravity
+CLI 1.1.13 answers `--output-format json` with one object whose `response` carries the model's
+Markdown verbatim and whose `conversation_id` is a first-class field. The bundled bridge now drives
+every dispatch that way and reads named fields instead of guessing — and the guess that used to rot
+silently is deleted rather than hardened.
+
+- **The envelope is transport, not contract.** The model is asked for exactly what it was asked for
+  before, so the delivery-proof echo, the mandated section shape, the receipt and the "no recognized
+  verdict" arm keep their semantics. On a successful run the wrapper still PRINTS the review text,
+  never JSON. An unreadable envelope on a zero exit is its own loud failure (exit 5) with no receipt,
+  distinct from a verdict-less answer (exit 4); a non-zero CLI exit keeps the CLI's own code and
+  message, because the envelope is parsed only on a zero exit.
+- **A pre-spend capability door, not a version floor.** Before anything is spent, the wrapper probes
+  the DECLARED option tokens of `agy --help` for `--output-format` and `--disable-slash-commands`,
+  requires `node >= 22` and the reader module, and refuses with the cost of the capability that is
+  actually missing, the installed `agy` version and the recovery command. A `--help` that itself
+  fails is never read as "capability present". A guessed version floor would have refused working
+  installs — the release that introduced the flag is not measurable from one build.
+- **The conversation id comes from the envelope; the log scrape and its `--continue` fallback are
+  gone.** The UUID grammar the scrape validated is kept and applied to the field, so a missing,
+  wrong-typed or malformed id stops the run before the next turn is spent instead of routing it at
+  an arbitrary conversation.
+- **`--disable-slash-commands` on every review dispatch.** A change-set line that begins with a slash
+  command stays BODY, so the model reviews the delivered bytes rather than an expansion of them.
+- **`--json-schema` was measured and REFUSED, and the reference says why.** It is not a constrained
+  decode: the model answers in prose and the CLI spends a second turn asking it to restate that
+  answer in schema shape. Matched control, same prompt and model, schema off vs on: 16,585 vs 33,446
+  total tokens, with the structured reason coming back reworded rather than quoted. `stream-json`
+  stays unadopted, with its two real gains named in the reference.
+- **Node is now required for the review role** (the JSON parse lives in `bin/agy-envelope.mjs`, not
+  in bash); `SKILL.md`, `setup/README.md` and the flags reference carry the requirement and the
+  probed capability list in place of the old "1.1.13 or newer" line.
+- **The state-block guard ships ONE vocabulary — English — and enumerates no other language.** A
+  shipped phrase list is a guess about somebody else's dialogue and it never stops growing; a
+  deployment whose dialogue language differs extends its own placed copy, and the mode contract
+  states that silence instead of hiding it. The always-loaded rules template gains the closing
+  state-block rule in the same shape: the slot LABELS stay English, because they are what lets a
+  checker find the block at all, while everything written into a slot is in the project's dialogue
+  language.
+- **Two smaller consequences of that sweep, both load-bearing.** `lens-region.mjs` now recognizes the
+  intermediate communications canon that shipped between the plain-language bullet and the
+  state-block rule, so a deployment sitting on it is still detected as canon rather than flagged as a
+  custom edit; and the index reader behind the size practice carries each entry's object id, so a
+  consumer can read what the index HOLDS instead of what the worktree happens to show.
+
+## 5.9.0 — the always-loaded navigator becomes something every deploy path actually creates (AD-096; memory 4.4.0)
+
+**A fresh deployment's entry point declared `docs/ai/index.md` always-loaded, and no step ever
+created it.** The navigator is generated, not templated, and nothing in bootstrap ran the generator:
+a Node project was born with a pre-commit hook failing its own index check, and a project without
+Node stayed quietly broken, its entry point pointing at a file nothing writes. The kit's own
+fallback bootstrap carried the same gap. Every deploy and upgrade path now finishes by materializing
+it, and two new guards make "the entry point only points at things a deploy creates" a test rather
+than an intention.
+
+- **A fifth project-configuration ensure: `index`.** `ensure-configs --reconcile` now regenerates
+  `docs/ai/index.md` whenever it is missing or stale, so an existing deployment gains its navigator
+  without a lineage bump — exactly like the config seeds. It never skips a No-Node project: the
+  generator runs from the kit's own bundled copy, not the project's `scripts/`.
+- **The LATE run is the authoritative one.** The agent-rules lens rewrites `docs/ai` after the
+  step-3 reconcile, so `upgrade.md` documents a late `--reconcile --only index` rung at BOTH exits —
+  after the lens block on the equal-head exit, at the end of step 7 on the migrated one — and the
+  step-4/8 reports relay THAT line.
+- **`ensure-configs --only <op>`** runs exactly one ensure. An unknown, missing or repeated
+  selector is a usage error with zero writes: a run that cannot be narrowed as asked must not widen.
+- **Failure says how far it got.** The index op classifies `generator-unlaunchable` (nothing ran),
+  `generator-failed`, `index-probe-failed` and `index-stale-after-write`; every cause that can only
+  arise after the generator ran DISCLOSES that a write may already have landed, and a claimed
+  regeneration is verified by a re-probe that must ANSWER — an exit code alone would turn a failed
+  probe into a false "still stale". Every relayed cause is now doc-parity-bound into `upgrade.md`.
+- **The bundled generator's write is contained and atomic** (mirrored from the memory canon): a
+  symlink at any level of `docs/ai/index.md` refuses, the body is published through an
+  exclusive-create temp + rename, and the containment guard runs BEFORE the freshness read — a
+  symlink whose target happens to hold current bytes is refused, not reported "already current".
+- **Hidden mode now names the whole payload.** `KIT_OWN_PATHS` listed 14 of the 21 files a deploy
+  copies into `scripts/`, so six shipped scripts besides the new one stayed visible in a hidden
+  project's `git status`. The registry is complete (20 → 27) and a new test derives the expected set
+  from the deploy payload itself. Known residual: a registered path is still hidden by NAME rather
+  than proven ownership (`known_issues.md` → Issue-018).
+
 ## 5.8.0 — the bundled agy bridge speaks the catalog the installed CLI actually serves, and grounding stops needing a shell (AD-095; antigravity-cli-bridge 5.2.0)
 
 **A model display string is matched exactly, so a stale one is not a documentation bug — it is a

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '5.8.0'
+  version: '5.10.0'
 ---
 
 # agent-workflow-kit

package/bridges/antigravity-cli-bridge/SKILL.md

@@ -2,7 +2,7 @@
 name: antigravity-cli-bridge
 description: Delegate work to Google's Antigravity CLI (`agy`) — the successor to Gemini CLI — to reach Gemini, Claude, and GPT-OSS models under a Google AI Pro/Ultra subscription from the terminal. Use when the user wants to run a headless `agy` prompt, hand a focused task or second-opinion review to `agy`, install or authenticate Antigravity CLI, check or economise its quota/models, bridge project context into `agy`, set up a second delegated-execution backend beside Codex, or troubleshoot `agy` flags, models, auth, conversations, or its headless behaviour.
 metadata:
-  version: '5.2.0'
+  version: '5.3.0'
 ---
 
 # antigravity-cli-bridge
@@ -95,11 +95,11 @@ AGY_HARD_TIMEOUT=8m agy-run "..."             # hard wall-clock cap via timeout(
 agy-run "..." -- --add-dir .                  # passthrough agy flags (never a permission widener)
 ```
 
-`agy` is **headless-only** here (`-p`/`--print`); v1.1.13 adds `--output-format json|stream-json`,
-and text stays the wrapper default — JSON can ride passthrough (`-- --output-format json`) but with
-no first-class parsing/validation (adoption is a backlog item). If you need structure, ask
-for Markdown with explicit headings and validate it
-yourself. Wrapper inputs: first argument is the prompt (`text`, `-` for stdin, or `@file`);
+`agy` is **headless-only** here (`-p`/`--print`). `agy-run` stays **text**: `--output-format json`
+can ride passthrough (`-- --output-format json`) but this wrapper adds no parsing/validation, so if
+you need structure, ask for Markdown with explicit headings and validate it yourself. (The `review`
+role is the one that adopted the JSON envelope — see below.) Wrapper inputs: first argument is the
+prompt (`text`, `-` for stdin, or `@file`);
 `AGY_MODEL` (default `Gemini 3.7 Flash (High)`); `AGY_TIMEOUT` → `--print-timeout` (default `5m`);
 `AGY_HARD_TIMEOUT` → hard `timeout(1)` wall-clock cap (default = `AGY_TIMEOUT`); extra `agy` flags
 after `--`. Full detail: [`references/models-and-flags.md`](references/models-and-flags.md).
@@ -142,6 +142,25 @@ agy-review diff <diff-file> [--facts @f] …      # review a supplied diff
 agy-review --continue --decided @round1.md --focus "still-open items"   # round-2 delta, no re-assembly
 ```
 
+**Transport + host requirements (probed, never a version floor).** Every review dispatch runs
+`--output-format json` and `--disable-slash-commands`, and the wrapper reads the returned envelope
+in node ([`bin/agy-envelope.mjs`](bin/agy-envelope.mjs)) instead of guessing at raw stdout — a
+change-set line beginning with a slash command therefore stays BODY, and the answer TEXT plus the
+conversation id arrive as **named fields**. The **review contract stays prose-shaped**: the verdict
+is still parsed from that text's `### Verdict` section, unchanged. **On a zero exit** what
+`agy-review` prints is the review text, never JSON; when the **single dispatch or the FINAL fed
+turn** exits non-zero the captured stdout is published as-is (the CLI's own failure wins and the
+envelope is parsed only on a zero exit), so a failing run may print a JSON or partial payload — an
+**intermediate** feed turn is the exception, its output stays private (Invariant E) and its failure
+prints only a named error. So it **probes before
+spending anything**: `agy --help` must advertise both flags, **Node ≥ 22** must be on `PATH`, and
+`bin/agy-envelope.mjs` must be present — each refusal names the missing capability and its recovery.
+A version floor is deliberately not used (the release that introduced a flag is not measurable from
+one installed build, so a guessed floor would refuse working installs), and a failed probe is never
+read as "capability present". `--json-schema` is **rejected on measurement** — it costs a second
+billed turn restating the model's own prose (16,585 → 33,446 tokens on a matched control); see
+[`references/models-and-flags.md`](references/models-and-flags.md).
+
 **Honesty + posture (D4/D5):** a run with no recognized `### Verdict` section — empty output
 included — **exits 4 with NO receipt**: treat it as a *failed review to re-run*, never a fatal
 session error. One stderr banner states the actual posture (`review posture: model=… timeout=…`)
@@ -249,9 +268,10 @@ checklist, prompt templates, output handling). Essentials:
 - Subdirectory `CLAUDE.md` files are **not** auto-loaded by `agy` (only the cwd context file +
   `.agents/skills/`). Put cross-cutting rules in the root context file, or include local rules in the
   prompt when they matter.
-- **Text is the wrapper default** — the CLI's 1.1.x `--output-format json|stream-json` can ride
-  passthrough but with no first-class parsing/validation (adoption is backlog) — and there is
-  **no `agy inspect`**: no machine-readable introspection.
+- **`agy-run` leaves JSON unparsed** — `--output-format json|stream-json` can ride its passthrough
+  with no first-class parsing/validation. (`agy-review` is the exception: it **adopted `json`** and
+  parses the envelope; only `stream-json` stays deferred there.) And there is **no `agy inspect`**:
+  no machine-readable introspection.
 - Model names must match the `agy models` display strings **exactly**.
 - **Quota is finite.** Heavy use of Pro/Claude models can exhaust the subscription; prefer Flash for
   cheap work.
@@ -260,5 +280,6 @@ checklist, prompt templates, output handling). Essentials:
   kill (a run was seen surviving 32 min past a 10m `--print-timeout`). A heavy `--add-dir` agentic
   prompt on a slow model (e.g. `Gemini 3.1 Pro (High)`) can run unbounded — prefer a faster model or
   a **self-contained prompt** (no `--add-dir`); an "exceeded the hard cap" error is the guard firing.
-- `agy` output is plain text and may be incomplete or out of date — treat it as advisory until the
-  main agent verifies it.
+- `agy` output may be incomplete or out of date — treat it as advisory until the main agent verifies
+  it. (Its FORMAT is not one thing: see the transport section for which wrapper prints text, when,
+  and what a failing run prints instead.)

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

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+// agy-envelope.mjs — read ONE captured `agy --output-format json` payload and hand the review
+// wrapper the fields it needs, or fail with a DISTINGUISHABLE cause.
+//
+// Why a module and not bash: the CLI answers with ONE JSON object whose `response` carries the
+// model's Markdown VERBATIM, and JSON parsing in bash is a defect farm. The trade — node becomes a
+// hard runtime requirement for every review — is paid deliberately and bought back by the wrapper's
+// pre-spend capability door, which refuses BEFORE a subscription turn is spent rather than after
+// one is wasted.
+//
+// Every failure is LOUD: a named cause, a non-zero exit. There is no degraded verdict and no
+// fallback to parsing raw stdout — a review whose answer cannot be read has not happened, and
+// saying otherwise would attest a tree nobody reviewed.
+//
+// The parse is a PURE function so it can be tested without a subprocess; the CLI below is a thin
+// file-I/O shell around it, exercised end-to-end by the wrapper's own acceptance tests.
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+
+const EXIT_NAMED_CAUSE = 1;
+const EXIT_USAGE = 2;
+const SUCCESS_STATUS = 'SUCCESS';
+// The SAME grammar the retired `capture_conversation_id` log scrape validated. A named envelope
+// field can still carry a malformed or wrong-typed value, and an unvalidated one would route every
+// later feed turn at an arbitrary conversation.
+const CONVERSATION_ID_GRAMMAR = /^[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}$/;
+
+const failed = (cause, sentence) => ({ ok: false, cause, sentence });
+
+// Read one captured payload. `requireConversationId` is the caller's declaration that it will ROUTE
+// a later turn at this conversation: only then is the field required and validated, so a lane that
+// never routes one cannot fail over a value it does not use.
+export const parseAgyEnvelope = (text, { requireConversationId = false } = {}) => {
+  if (text.length === 0) {
+    return failed('empty-payload', 'the captured payload is empty — the CLI printed nothing at all.');
+  }
+  // Parsed-ness is carried SEPARATELY from the parsed value: `null` is both a legal JSON document
+  // and the obvious failure sentinel, and conflating them reported valid JSON `null` as "not JSON".
+  const parsed = (() => {
+    try {
+      return { parsed: true, value: JSON.parse(text) };
+    } catch {
+      return { parsed: false, value: null };
+    }
+  })();
+  if (!parsed.parsed) {
+    return failed('not-json', 'the captured payload is not JSON — the dispatch did not return an envelope.');
+  }
+  const envelope = parsed.value;
+  if (envelope === null || typeof envelope !== 'object' || Array.isArray(envelope)) {
+    return failed('not-an-envelope', 'the captured payload is JSON but not a single object.');
+  }
+  if (envelope.status !== SUCCESS_STATUS) {
+    return failed('status', `the envelope reports status ${JSON.stringify(envelope.status ?? null)}, not "${SUCCESS_STATUS}".`);
+  }
+  // An EMPTY response is a real (if useless) answer and rides through to the wrapper's verdict-less
+  // arm; only an ABSENT or wrong-typed field means the answer is not in the envelope at all.
+  if (typeof envelope.response !== 'string') {
+    return failed('response', 'the envelope carries no string `response` field — the model\'s answer is not in it.');
+  }
+  if (!requireConversationId) {
+    return { ok: true, response: envelope.response, conversationId: '' };
+  }
+  if (typeof envelope.conversation_id !== 'string') {
+    return failed('conversation-id', 'the envelope carries no string `conversation_id` field, so a later turn could not be routed at this conversation.');
+  }
+  if (!CONVERSATION_ID_GRAMMAR.test(envelope.conversation_id)) {
+    return failed('conversation-id', 'the envelope\'s `conversation_id` does not match the UUID grammar — routing a later turn at it would target an arbitrary conversation.');
+  }
+  return { ok: true, response: envelope.response, conversationId: envelope.conversation_id };
+};
+
+const FLAG_KEYS = {
+  '--envelope': 'envelope',
+  '--response-out': 'responseOut',
+  '--conversation-id-out': 'conversationIdOut',
+};
+
+const USAGE = [
+  'agy-envelope — read ONE captured `agy --output-format json` payload, or fail with a named cause.',
+  '',
+  'Usage:',
+  '  node agy-envelope.mjs --envelope <path> --response-out <path> [--conversation-id-out <path>]',
+  '',
+  '  --envelope <path>             the captured stdout of ONE `agy --output-format json` dispatch',
+  '  --response-out <path>         write the envelope\'s `response` VERBATIM here',
+  '  --conversation-id-out <path>  ALSO require `conversation_id`, validate it against the UUID',
+  '                                grammar, and write it here',
+  '',
+  'Exit: 0 parsed; 1 a named failure cause on stderr; 2 usage.',
+].join('\n');
+
+const usageOutcome = (message) => ({ code: EXIT_USAGE, message: `agy-envelope: ${message}\n\n${USAGE}\n` });
+const causeOutcome = (cause, sentence) => ({ code: EXIT_NAMED_CAUSE, message: `agy-envelope: ${cause} — ${sentence}\n` });
+const isOutcome = (value) => value !== null && typeof value === 'object' && typeof value.code === 'number';
+
+const parseArguments = (argv) =>
+  argv.reduce((options, token, index) => {
+    if (isOutcome(options)) return options;
+    if (!Object.hasOwn(FLAG_KEYS, token)) {
+      if (index > 0 && Object.hasOwn(FLAG_KEYS, argv[index - 1])) return options;
+      return usageOutcome(`unknown argument '${token}'`);
+    }
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith('--')) return usageOutcome(`${token} needs a value`);
+    return { ...options, [FLAG_KEYS[token]]: value };
+  }, { envelope: '', responseOut: '', conversationIdOut: '' });
+
+const readPayloadText = (path) => {
+  const bytes = (() => {
+    try {
+      return readFileSync(path);
+    } catch {
+      return null;
+    }
+  })();
+  if (bytes === null) return causeOutcome('unreadable-payload', `the captured payload '${path}' could not be read.`);
+  try {
+    // A BOM is stripped rather than fed to JSON.parse; any other invalid byte refuses loudly.
+    return { text: new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(bytes) };
+  } catch {
+    return causeOutcome('not-utf8', `the captured payload '${path}' is not valid UTF-8.`);
+  }
+};
+
+const writeField = (path, value, field) => {
+  try {
+    writeFileSync(path, value, 'utf8');
+    return null;
+  } catch {
+    return causeOutcome('write-failed', `the envelope's ${field} could not be written to '${path}'.`);
+  }
+};
+
+// The CLI as a PURE-ish function: every arm RETURNS its outcome instead of exiting, so each one can
+// be driven in-process by a test. Writing and exiting happen once, at the entry point below — the
+// single impure boundary. (Subprocess tests could not close this: coverage is collected in the test
+// process, so an arm only reachable through a spawn is an arm nothing can prove was exercised.)
+export const runEnvelopeCli = (argv) => {
+  const options = parseArguments(argv);
+  if (isOutcome(options)) return options;
+  if (!options.envelope) return usageOutcome('--envelope is required.');
+  if (!options.responseOut) return usageOutcome('--response-out is required.');
+  const payload = readPayloadText(options.envelope);
+  if (isOutcome(payload)) return payload;
+  const result = parseAgyEnvelope(payload.text, { requireConversationId: Boolean(options.conversationIdOut) });
+  if (!result.ok) return causeOutcome(result.cause, result.sentence);
+  const wroteResponse = writeField(options.responseOut, result.response, 'response');
+  if (wroteResponse !== null) return wroteResponse;
+  if (!options.conversationIdOut) return { code: 0 };
+  const wroteId = writeField(options.conversationIdOut, result.conversationId, 'conversation_id');
+  return wroteId === null ? { code: 0 } : wroteId;
+};
+
+// Entry-point guard (not import.meta.main — that landed after the family's Node >= 22 floor). ONE
+// statement so the line is executed on import and carries no unreachable-by-test body.
+const entryOutcome = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url) ? runEnvelopeCli(process.argv.slice(2)) : null;
+if (entryOutcome !== null) { if (entryOutcome.message) process.stderr.write(entryOutcome.message); process.exit(entryOutcome.code); }

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');