@sabaiway/agent-workflow-kit 1.24.0 → 1.26.0

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

@@ -439,3 +439,189 @@ describe('agy-review.sh — subdir invocation is repo-complete (13)', () => {
     assert.match(r.prompt, /SUBDIR_RELATIVE_FACT/, 'a relative --facts path resolves against the invocation cwd, before the cd');
   });
 });
+
+// ── driving contract: --help ⟷ manifest ⟷ real arg-parsing (drift-guarded) ─────
+// The manifest roles.review.contract is the single machine-readable source of the
+// driving contract; these suites pin (a) --help renders it verbatim (set-EQUALITY,
+// both directions), (b) the wrapper's REAL parser arms equal the declared sets
+// (source-level reverse guard), (c) each declared mode/flag is really accepted and
+// the CLOSED grammar really rejects an invented flag. Helpers are inline — each
+// bridge test file stays standalone (mirror byte-equality).
+
+const MANIFEST = JSON.parse(readFileSync(join(HERE, '..', 'capability.json'), 'utf8'));
+const REVIEW_CONTRACT = MANIFEST.roles.review.contract;
+const norm = (s) => s.replace(/\s+/g, ' ').trim();
+const setEq = (got, want, msg) => assert.deepEqual([...got].sort(), [...want].sort(), msg);
+const leadingFlag = (descriptor) => {
+  const m = norm(descriptor).match(/(^|\s)(--[a-z-]+)/);
+  assert.ok(m, `descriptor "${descriptor}" carries no --flag token`);
+  return m[2];
+};
+
+// Run `--help`/-h with PATH stripped of codex/agy/git, from a non-git cwd —
+// proving the short-circuit fires BEFORE every preflight.
+const runHelp = (arg) => {
+  const root = mkdtempSync(join(tmpdir(), 'agy-review-help-'));
+  const nongit = join(root, 'nongit');
+  mkdirSync(nongit, { recursive: true });
+  const path = makePathWithout(root, ['codex', 'agy', 'git']);
+  const r = spawnSync('bash', [WRAPPER, arg], {
+    cwd: nongit, encoding: 'utf8', timeout: 15000, env: { HOME: root, PATH: path },
+  });
+  rmSync(root, { recursive: true, force: true });
+  return r;
+};
+
+// The lines of a labelled --help section (header line → the next blank line).
+const helpSection = (text, header) => {
+  const lines = text.split('\n');
+  const i = lines.findIndex((l) => l.trim() === header);
+  assert.notEqual(i, -1, `--help must carry a "${header}" section`);
+  const out = [];
+  for (let j = i + 1; j < lines.length; j += 1) {
+    if (lines[j].trim() === '') break;
+    out.push(lines[j].trim());
+  }
+  return out;
+};
+
+// Source-level parser-arm extractor — the reverse drift guard. Scans ONLY `case`
+// statements whose SUBJECT is a CLI-argument variable (allowlisted), skipping
+// heredoc bodies (a heredoc may carry non-CLI `case` arms — e.g. codex-exec's
+// git-shim). Returns Map(subject → [raw arm label, …]) in source order.
+const ARG_SUBJECTS = new Set(['"$mode"', '"${1:-}"', '"$1"', '"$_arg"']);
+const extractArgCaseArms = (source) => {
+  const arms = new Map();
+  const stack = [];
+  let heredoc = null;
+  for (const raw of source.split('\n')) {
+    if (heredoc) {
+      if (raw.trim() === heredoc) heredoc = null;
+      continue;
+    }
+    if (raw.trimStart().startsWith('#')) continue; // a comment line may carry a stray ')'
+    const hd = raw.match(/<<-?\s*['"]?([A-Za-z_][A-Za-z0-9_]*)['"]?/);
+    if (hd) { heredoc = hd[1]; continue; }
+    const cs = raw.match(/^\s*case\s+(\S+)\s+in\b/);
+    if (cs) { stack.push(cs[1]); continue; }
+    if (/^\s*esac\b/.test(raw)) { stack.pop(); continue; }
+    if (stack.length && ARG_SUBJECTS.has(stack[stack.length - 1])) {
+      const arm = raw.match(/^\s*([^)(\s][^)(]*)\)/);
+      if (arm) {
+        const subject = stack[stack.length - 1];
+        if (!arms.has(subject)) arms.set(subject, []);
+        arms.get(subject).push(arm[1].trim());
+      }
+    }
+  }
+  return arms;
+};
+const splitArms = (labels) => (labels ?? []).flatMap((l) => l.split('|'));
+
+describe('agy-review.sh — --help contract (manifest-pinned)', () => {
+  it('--help and -h exit 0 pre-preflight (no agy, no git)', () => {
+    for (const arg of ['--help', '-h']) {
+      const r = runHelp(arg);
+      assert.equal(r.status, 0, `${arg}: ${r.stderr}`);
+      assert.match(r.stdout, /Usage:/, `${arg} prints the contract to stdout`);
+      assert.equal(r.stderr, '', `${arg} prints nothing to stderr`);
+    }
+  });
+
+  it('Usage set-EQUALS the manifest invocation descriptors (both directions)', () => {
+    const help = runHelp('--help').stdout;
+    const got = helpSection(help, 'Usage:').filter((l) => l.startsWith('agy-review')).map(norm);
+    assert.ok(REVIEW_CONTRACT.invocations.length > 0, 'manifest invocations must be non-empty');
+    setEq(got, REVIEW_CONTRACT.invocations.map(norm), 'help Usage ⟷ manifest invocations');
+  });
+
+  it('Flags set-EQUALS the manifest flag descriptors (both directions)', () => {
+    const help = runHelp('--help').stdout;
+    const got = helpSection(help, 'Flags:').filter((l) => l.startsWith('--')).map(norm);
+    assert.ok(REVIEW_CONTRACT.flags.length > 0, 'manifest flags must be non-empty');
+    setEq(got, REVIEW_CONTRACT.flags.map(norm), 'help Flags ⟷ manifest flags');
+  });
+
+  it('Grounding renders the manifest grounding note verbatim', () => {
+    const help = runHelp('--help').stdout;
+    assert.equal(norm(helpSection(help, 'Grounding:').join(' ')), norm(REVIEW_CONTRACT.grounding));
+  });
+
+  it('Round-2 / resume set-EQUALS the manifest continue descriptors', () => {
+    const help = runHelp('--help').stdout;
+    const got = helpSection(help, 'Round-2 / resume:').filter((l) => l.startsWith('agy-review')).map(norm);
+    assert.ok(REVIEW_CONTRACT.continue.length > 0, 'manifest continue must be non-empty');
+    setEq(got, REVIEW_CONTRACT.continue.map(norm), 'help continue ⟷ manifest continue');
+  });
+});
+
+describe('agy-review.sh — source-level reverse guard (parser arms ⟷ manifest)', () => {
+  const arms = extractArgCaseArms(readFileSync(WRAPPER, 'utf8'));
+
+  it('the real mode arms equal the manifest modes (adding a mode without the manifest fails here)', () => {
+    // Deliberately a UNION over every `case "$mode"` in the wrapper (the CLI dispatch AND the
+    // emit_artifact renderer): the union can only be conservative — a mode added to EITHER case
+    // without the manifest goes red; no renderer-only arm can make a missing manifest entry green.
+    const modes = splitArms(arms.get('"$mode"')).filter((a) => a !== '*');
+    assert.ok(MANIFEST.roles.review.modes.length > 0, 'manifest modes must be non-empty');
+    setEq(new Set(modes), MANIFEST.roles.review.modes, 'parser mode arms ⟷ manifest modes');
+  });
+
+  it('the real flag arms equal the manifest flag set (closed grammar; catch-alls excluded)', () => {
+    const flagArms = splitArms(arms.get('"$1"')).filter((a) => !['--', '--*', '*'].includes(a));
+    const declared = REVIEW_CONTRACT.flags.map(leadingFlag);
+    assert.ok(declared.length > 0, 'manifest flag set must be non-empty');
+    setEq(new Set(flagArms), new Set(declared), 'parser flag arms ⟷ manifest flags');
+  });
+
+  it('the first-arg entrypoints are exactly --help/-h + the manifest continue flags', () => {
+    const declared = REVIEW_CONTRACT.continue.map(leadingFlag);
+    assert.ok(declared.length > 0, 'manifest continue set must be non-empty');
+    setEq(new Set(splitArms(arms.get('"${1:-}"'))), new Set(['--help', '-h', ...declared]));
+  });
+});
+
+describe('agy-review.sh — declared contract is really accepted (forward guard)', () => {
+  it('every manifest mode runs green', () => {
+    const drive = {
+      code: () => ['code', '--facts', 'f'],
+      plan: (sb) => { writeFileSync(join(sb.repo, 'p.md'), '# p\n'); return ['plan', 'p.md', '--facts', 'f']; },
+      diff: (sb) => { writeFileSync(join(sb.repo, 'c.diff'), 'diff body\n'); return ['diff', 'c.diff', '--facts', 'f']; },
+    };
+    for (const mode of MANIFEST.roles.review.modes) {
+      assert.ok(drive[mode], `no test drive for manifest mode "${mode}" — add one`);
+      const sb = makeSandbox();
+      const r = run(sb, { args: drive[mode](sb) });
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.equal(r.status, 0, `mode ${mode}: ${r.stderr}`);
+      assert.equal(r.invoked, true, `mode ${mode} must reach agy`);
+    }
+  });
+
+  it('every manifest flag is accepted in code mode', () => {
+    for (const descriptor of REVIEW_CONTRACT.flags) {
+      const flag = leadingFlag(descriptor);
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['code', flag, 'f'] });
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.equal(r.status, 0, `${flag}: ${r.stderr}`);
+    }
+  });
+
+  it('an invented flag is rejected (closed grammar negative)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'f', '--bogus-flag'] });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 2);
+    assert.match(r.stderr, /unknown flag '--bogus-flag'/);
+    assert.equal(r.invoked, false, 'an unknown flag must not spend a run');
+  });
+
+  it('--help NOT in first position is an unknown flag, never an intercepted help', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'f', '--help'] });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 2, 'help is keyed on the FIRST argument only');
+    assert.doesNotMatch(r.stdout, /Usage:/);
+  });
+});

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

@@ -34,6 +34,29 @@
 #                                            # passthrough agy flags (future flows)
 set -euo pipefail
 
+# --- --help / -h (pre-preflight: no agy, no login needed) ----------------------
+# Keyed ONLY on the FIRST argument — never a scan of all args, else a passthrough
+# payload like `agy-run "prompt" -- --help` would be intercepted. agy-run is the
+# probe role (not dispatched by any activity slot), so this help is authored here
+# — not manifest-pinned (candidate C only).
+case "${1:-}" in
+  --help|-h)
+    cat <<'HELP'
+agy-run — thin, flow-agnostic wrapper around Google's Antigravity CLI (agy; subscription-only, hard wall-clock cap).
+
+Usage:
+  agy-run "your prompt"
+  echo "your prompt" | agy-run -
+  agy-run @path/to/prompt.md
+  agy-run <prompt|-|@file> -- <extra agy flags...>
+
+Environment: AGY_MODEL (exact display string from `agy models`; empty ⇒ agy's settings.json), AGY_TIMEOUT / AGY_HARD_TIMEOUT (duration strings), AGY_MAX_PROMPT_BYTES (single-argv byte ceiling; the override only lowers it).
+Requires at run time: the agy CLI on PATH + a Google AI subscription login (--help needs neither).
+HELP
+    exit 0
+    ;;
+esac
+
 # 1. Make `agy` findable even when ~/.bashrc was not sourced.
 export PATH="$HOME/.local/bin:$PATH"
 

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

@@ -1,8 +1,8 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, writeFileSync, chmodSync, rmSync, existsSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, chmodSync, rmSync, existsSync, readdirSync, symlinkSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join, dirname } from 'node:path';
+import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 
@@ -152,3 +152,59 @@ describe('agy.sh — argv byte-ceiling guard (AGY_MAX_PROMPT_BYTES)', () => {
     assert.equal(invoked, false, 'raising the ceiling past the OS limit must fail loud, not pass through to E2BIG');
   });
 });
+
+// ── --help (candidate C only — the probe role is not dispatched by any activity
+// slot, so this help is authored in the wrapper, NOT manifest-pinned; the lighter
+// guard pins pre-preflight reachability + the documented usage forms). ──────────
+
+// A PATH farm mirroring the real one MINUS the named binaries — so the reachability claim
+// ("--help needs no agy/git") holds even on a host that has the real CLIs installed.
+// Ported from agy-review.test.mjs (inline: each bridge test file stays standalone).
+const makePathWithout = (root, exclude = []) => {
+  const skip = new Set(exclude);
+  const dir = mkdtempSync(join(root, 'nobin-'));
+  for (const d of (process.env.PATH || '').split(':').filter(Boolean)) {
+    let names;
+    try { names = readdirSync(d); } catch { continue; }
+    for (const name of names) {
+      if (skip.has(name)) continue;
+      const link = join(dir, name);
+      if (existsSync(link)) continue;
+      try { symlinkSync(resolve(d, name), link); } catch { /* dup / race — ignore */ }
+    }
+  }
+  return dir;
+};
+
+describe('agy.sh — --help (pre-preflight, candidate C)', () => {
+  it('--help and -h exit 0 with NO agy on PATH and name the documented usage', () => {
+    for (const arg of ['--help', '-h']) {
+      // A bare HOME with no ~/.local/bin/agy stub AND a PATH farm stripped of agy/git —
+      // the help must not need the CLI even when the host has a real agy installed.
+      const home = mkdtempSync(join(tmpdir(), 'agy-help-'));
+      const r = spawnSync('bash', [WRAPPER, arg], {
+        env: { HOME: home, PATH: makePathWithout(home, ['agy', 'git']) },
+        encoding: 'utf8',
+        timeout: 15000,
+      });
+      rmSync(home, { recursive: true, force: true });
+      assert.equal(r.status, 0, `${arg}: ${r.stderr}`);
+      assert.equal(r.stderr, '', `${arg} prints nothing to stderr`);
+      assert.match(r.stdout, /Usage:/);
+      assert.match(r.stdout, /agy-run "your prompt"/);
+      assert.match(r.stdout, /agy-run @path\/to\/prompt\.md/);
+      assert.match(r.stdout, /agy-run <prompt\|-\|@file> -- <extra agy flags\.\.\.>/);
+    }
+  });
+
+  it('--help after the -- separator is passthrough payload, never intercepted', () => {
+    const home = makeSandbox(RECORDING_STUB);
+    const sentinel = join(home, 'sentinel');
+    const r = runArgs(home, { args: ['prompt', '--', '--help'], env: { AGY_STUB_SENTINEL: sentinel } });
+    const invoked = existsSync(sentinel);
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.doesNotMatch(r.stdout, /Usage:/, 'help is keyed on the FIRST argument only');
+    assert.equal(invoked, true, 'the run must proceed to agy with the payload');
+  });
+});

package/bridges/antigravity-cli-bridge/capability.json

@@ -3,10 +3,33 @@
   "schema": 1,
   "name": "antigravity-cli-bridge",
   "kind": "execution-backend",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "provides": ["review", "probe"],
   "roles": {
-    "review": { "cmd": "agy-review", "source": "bin/agy-review.sh", "template": "references/review-prompt.md", "modes": ["code", "plan", "diff"], "output": "advisory" },
+    "review": {
+      "cmd": "agy-review",
+      "source": "bin/agy-review.sh",
+      "template": "references/review-prompt.md",
+      "modes": ["code", "plan", "diff"],
+      "output": "advisory",
+      "contract": {
+        "invocations": [
+          "agy-review code [--facts @f] [--decided @f] [--focus \"…\"] [extra focus…]",
+          "agy-review plan <plan-file> [--facts @f] [--decided @f] [--focus \"…\"]",
+          "agy-review diff <diff-file> [--facts @f] [--decided @f] [--focus \"…\"]"
+        ],
+        "grounding": "grounded review — agy reads NOTHING by default, an ungrounded review GUESSES: --facts @f = the verified facts to review AGAINST; --decided @f = decisions already made, do NOT re-raise (anti-circling)",
+        "flags": [
+          "--facts @f — verified facts the review runs AGAINST (omit ⇒ loud ungrounded-review warning)",
+          "--decided @f — already-decided / already-addressed list; do NOT re-raise (anti-circling; the round-2 payload)",
+          "--focus \"…\" — extra focus (repeatable; code mode also takes trailing focus words)"
+        ],
+        "continue": [
+          "agy-review --continue [--decided @f] [--focus \"…\"]",
+          "agy-review --conversation <id> [--decided @f] [--focus \"…\"]"
+        ]
+      }
+    },
     "probe": { "cmd": "agy-run", "source": "bin/agy.sh", "output": "advisory" }
   },
   "detect": {

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

@@ -2,7 +2,7 @@
 name: codex-cli-bridge
 description: Delegate work to the OpenAI Codex CLI (`codex`) under a ChatGPT subscription — run plan/instruction EXECUTION in a sandboxed workspace, or get a read-only ADVISORY review of a plan or working-tree diff — as a second delegated-execution backend beside Antigravity. Use when the user wants to hand a bounded coding task or plan to `codex exec`, get a second-opinion review from codex, install or authenticate Codex CLI, understand its sandbox/network/approval policy, drive codex efficiently from the main agent (exec vs review, resume, the commit boundary), bridge project context (`AGENTS.md`) into codex, or troubleshoot codex flags, models, auth, or its no-TTY headless behaviour.
 metadata:
-  version: '2.0.0'
+  version: '2.1.0'
 ---
 
 # codex-cli-bridge
@@ -77,7 +77,7 @@ Drive codex only through the two wrappers (installed on `PATH`), run from the ta
 # EXECUTION (workspace-write sandbox, network OFF, never prompts):
 codex-exec docs/plans/<slug>.md                 # drive a plan file
 echo "apply review fix: ..." | codex-exec -      # ad-hoc instruction from stdin
-codex-exec <file|-> -- <unguarded codex flags...> # passthrough codex flags after `--` (guarded ones rejected)
+codex-exec <file|-> -- <extra codex flags...>     # GUARDED passthrough after `--` (policy/model/capture flags rejected; some relaxed only under CODEX_PROBE=1)
 
 # RESUME (iterate on the SAME session without re-sending context):
 codex-exec --resume-last docs/plans/<slug>.md    # continue the last session (id from the sidecar)

package/bridges/codex-cli-bridge/bin/codex-exec.sh

@@ -40,6 +40,40 @@
 #   CODEX_PROBE=1 CODEX_MODEL=<slug> codex-exec <file>   # throwaway probe (relaxes the guard)
 set -euo pipefail
 
+# --- --help / -h (pre-preflight: no codex, no login, no git tree needed) -------
+# Keyed ONLY on the FIRST argument — never a scan of all args, else a passthrough
+# payload like `codex-exec f - -- --help` would be intercepted.
+# The contract below is drift-guarded against capability.json roles.execute.contract.
+case "${1:-}" in
+  --help|-h)
+    cat <<'HELP'
+codex-exec — delegate plan/instruction EXECUTION to the OpenAI Codex CLI (subscription-only; workspace-write sandbox, network OFF, git writes blocked — the orchestrator commits).
+
+Usage:
+  codex-exec <plan-file|->
+  codex-exec <plan-file|-> -- <extra codex flags...>
+
+Grounding:
+  automatic — the root AGENTS.md (Hard Constraints) is auto-merged into codex's
+  context and the wrapper prepends the orchestrator execution contract; no
+  grounding flags
+
+Round-2 / resume:
+  codex-exec --resume-last <plan-file|->
+  codex-exec --resume <session-id> <plan-file|->
+  (resume continues the recorded session without re-sending context; takes no '--' passthrough)
+
+Guarded passthrough after '--':
+  blocked always: -c* --config* -s* --sandbox* --dangerously-bypass-approvals-and-sandbox --dangerously-bypass-hook-trust --full-auto --oss --local-provider* -p* --profile* -m* --model* -o* --output-last-message* --json* --color* --output-schema* --ephemeral*
+  relaxed only under CODEX_PROBE=1: --add-dir* -C* --cd* --skip-git-repo-check --ignore-rules --enable* --disable*
+
+Environment: CODEX_HARD_TIMEOUT (seconds, default 3600), CODEX_PROBE=1 (throwaway probe only).
+Requires at run time: the codex CLI on PATH, a ChatGPT-subscription login, a git work tree with a root AGENTS.md (--help needs none of these).
+HELP
+    exit 0
+    ;;
+esac
+
 DEFAULT_CODEX_MODEL="gpt-5.5"   # frontier coding model (verified locally) — pinned
 DEFAULT_CODEX_EFFORT="xhigh"    # maximum reasoning effort — pinned
 CODEX_MODEL="${CODEX_MODEL:-$DEFAULT_CODEX_MODEL}"

package/bridges/codex-cli-bridge/bin/codex-exec.test.mjs

@@ -149,7 +149,8 @@ describe('codex-exec.sh — quality-first model/effort guard (1.1)', () => {
 // capture flags: rejected ALWAYS, even under CODEX_PROBE=1.
 const ALWAYS_BLOCKED = [
   ['-s', 'read-only'], ['--sandbox', 'danger-full-access'], ['-c', 'k=v'], ['--config', 'k=v'],
-  ['--full-auto'], ['--dangerously-bypass-approvals-and-sandbox'], ['--oss'], ['--local-provider', 'x'],
+  ['--full-auto'], ['--dangerously-bypass-approvals-and-sandbox'], ['--dangerously-bypass-hook-trust'],
+  ['--oss'], ['--local-provider', 'x'],
   ['-p', 'prof'], ['--profile', 'prof'], ['-m', 'gpt-5.5'], ['--model', 'gpt-5.5'],
   ['-o', '/x'], ['--output-last-message', '/x'], ['--json'], ['--color', 'always'],
   ['--output-schema', '/x'], ['--ephemeral'],
@@ -591,3 +592,161 @@ describe('codex-exec.sh — session id absent', () => {
     assert.match(r.stdout, /FAKE_FINAL_MESSAGE/, 'the run still succeeds');
   });
 });
+
+// ── driving contract: --help ⟷ manifest ⟷ real arg-parsing (drift-guarded) ─────
+// The manifest roles.execute.contract is the single machine-readable source of the
+// driving contract; these suites pin (a) --help renders it verbatim (set-EQUALITY,
+// both directions, incl. the TIERED guarded-passthrough sets), (b) the wrapper's
+// REAL parser arms equal the declared sets (source-level reverse guard — the
+// git-shim heredoc's own `case` arms are NOT CLI modes and must be skipped).
+// Helpers are inline — each bridge test file stays standalone (mirror byte-equality).
+
+const MANIFEST = JSON.parse(readFileSync(join(HERE, '..', 'capability.json'), 'utf8'));
+const EXEC_CONTRACT = MANIFEST.roles.execute.contract;
+const norm = (s) => s.replace(/\s+/g, ' ').trim();
+const setEq = (got, want, msg) => assert.deepEqual([...got].sort(), [...want].sort(), msg);
+const leadingFlag = (descriptor) => {
+  const m = norm(descriptor).match(/(^|\s)(--[a-z-]+)/);
+  assert.ok(m, `descriptor "${descriptor}" carries no --flag token`);
+  return m[2];
+};
+
+// Run `--help`/-h with PATH stripped of codex/agy/git, from a non-git cwd with no
+// AGENTS.md — proving the short-circuit fires BEFORE every preflight.
+const runHelp = (arg) => {
+  const root = mkdtempSync(join(tmpdir(), 'codex-exec-help-'));
+  const nongit = join(root, 'nongit');
+  mkdirSync(nongit, { recursive: true });
+  const path = makePathWithout(root, ['codex', 'agy', 'git']);
+  const r = spawnSync('bash', [WRAPPER, arg], {
+    cwd: nongit, encoding: 'utf8', timeout: 15000, env: { HOME: root, PATH: path },
+  });
+  rmSync(root, { recursive: true, force: true });
+  return r;
+};
+
+// The lines of a labelled --help section (header line → the next blank line).
+const helpSection = (text, header) => {
+  const lines = text.split('\n');
+  const i = lines.findIndex((l) => l.trim() === header);
+  assert.notEqual(i, -1, `--help must carry a "${header}" section`);
+  const out = [];
+  for (let j = i + 1; j < lines.length; j += 1) {
+    if (lines[j].trim() === '') break;
+    out.push(lines[j].trim());
+  }
+  return out;
+};
+
+// Source-level parser-arm extractor — the reverse drift guard. Scans ONLY `case`
+// statements whose SUBJECT is a CLI-argument variable (allowlisted), skipping
+// heredoc bodies (codex-exec's git-shim heredoc carries its own `case "$verb"`
+// git-verb arms that are NOT CLI modes). Returns Map(subject → [raw arm label, …]).
+const ARG_SUBJECTS = new Set(['"$mode"', '"${1:-}"', '"$1"', '"$_arg"']);
+const extractArgCaseArms = (source) => {
+  const arms = new Map();
+  const stack = [];
+  let heredoc = null;
+  for (const raw of source.split('\n')) {
+    if (heredoc) {
+      if (raw.trim() === heredoc) heredoc = null;
+      continue;
+    }
+    if (raw.trimStart().startsWith('#')) continue; // a comment line may carry a stray ')'
+    const hd = raw.match(/<<-?\s*['"]?([A-Za-z_][A-Za-z0-9_]*)['"]?/);
+    if (hd) { heredoc = hd[1]; continue; }
+    const cs = raw.match(/^\s*case\s+(\S+)\s+in\b/);
+    if (cs) { stack.push(cs[1]); continue; }
+    if (/^\s*esac\b/.test(raw)) { stack.pop(); continue; }
+    if (stack.length && ARG_SUBJECTS.has(stack[stack.length - 1])) {
+      const arm = raw.match(/^\s*([^)(\s][^)(]*)\)/);
+      if (arm) {
+        const subject = stack[stack.length - 1];
+        if (!arms.has(subject)) arms.set(subject, []);
+        arms.get(subject).push(arm[1].trim());
+      }
+    }
+  }
+  return arms;
+};
+const splitArms = (labels) => (labels ?? []).flatMap((l) => l.split('|'));
+
+describe('codex-exec.sh — --help contract (manifest-pinned)', () => {
+  it('--help and -h exit 0 pre-preflight (no codex, no git, no AGENTS.md)', () => {
+    for (const arg of ['--help', '-h']) {
+      const r = runHelp(arg);
+      assert.equal(r.status, 0, `${arg}: ${r.stderr}`);
+      assert.match(r.stdout, /Usage:/, `${arg} prints the contract to stdout`);
+      assert.equal(r.stderr, '', `${arg} prints nothing to stderr`);
+    }
+  });
+
+  it('Usage set-EQUALS the manifest invocation descriptors (both directions)', () => {
+    const help = runHelp('--help').stdout;
+    const got = helpSection(help, 'Usage:').filter((l) => l.startsWith('codex-exec')).map(norm);
+    assert.ok(EXEC_CONTRACT.invocations.length > 0, 'manifest invocations must be non-empty');
+    setEq(got, EXEC_CONTRACT.invocations.map(norm), 'help Usage ⟷ manifest invocations');
+  });
+
+  it('Grounding renders the manifest grounding note verbatim', () => {
+    const help = runHelp('--help').stdout;
+    assert.equal(norm(helpSection(help, 'Grounding:').join(' ')), norm(EXEC_CONTRACT.grounding));
+  });
+
+  it('Round-2 / resume set-EQUALS the manifest continue descriptors', () => {
+    const help = runHelp('--help').stdout;
+    const got = helpSection(help, 'Round-2 / resume:').filter((l) => l.startsWith('codex-exec')).map(norm);
+    assert.ok(EXEC_CONTRACT.continue.length > 0, 'manifest continue must be non-empty');
+    setEq(got, EXEC_CONTRACT.continue.map(norm), 'help continue ⟷ manifest continue');
+  });
+
+  it('the guarded-passthrough TIERS set-EQUAL the manifest tiers (never a flat set)', () => {
+    const help = runHelp('--help').stdout;
+    const section = helpSection(help, "Guarded passthrough after '--':");
+    const tier = (prefix) => {
+      const line = section.find((l) => l.startsWith(prefix));
+      assert.ok(line, `passthrough section must carry a "${prefix}" line`);
+      return line.slice(prefix.length).trim().split(/\s+/);
+    };
+    assert.ok(EXEC_CONTRACT.passthrough.blocked.length > 0, 'manifest blocked tier must be non-empty');
+    assert.ok(EXEC_CONTRACT.passthrough.probeRelaxed.length > 0, 'manifest probe tier must be non-empty');
+    setEq(tier('blocked always:'), EXEC_CONTRACT.passthrough.blocked, 'help tier-1 ⟷ manifest blocked');
+    setEq(tier('relaxed only under CODEX_PROBE=1:'), EXEC_CONTRACT.passthrough.probeRelaxed, 'help tier-2 ⟷ manifest probeRelaxed');
+  });
+
+  it('--help after the -- separator is passthrough payload, never intercepted', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['-', '--', '--help'], input: 'go' });
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.doesNotMatch(r.stdout, /Usage:/, 'help is keyed on the FIRST argument only');
+    assert.match(r.argv, /(^|\n)--help(\n|$)/, 'the payload --help reaches codex argv');
+  });
+});
+
+describe('codex-exec.sh — source-level reverse guard (parser arms ⟷ manifest)', () => {
+  const arms = extractArgCaseArms(readFileSync(WRAPPER, 'utf8'));
+
+  it('the first-arg entrypoints are exactly --help/-h + the manifest resume flags', () => {
+    const declared = EXEC_CONTRACT.continue.map(leadingFlag);
+    assert.ok(declared.length > 0, 'manifest resume set must be non-empty');
+    setEq(new Set(splitArms(arms.get('"${1:-}"'))), new Set(['--help', '-h', ...declared]));
+  });
+
+  it('the real passthrough tier arms equal the manifest tiers (git-shim heredoc excluded)', () => {
+    const tierArms = arms.get('"$_arg"') ?? [];
+    assert.equal(tierArms.length, 2, 'exactly two passthrough tiers: always-blocked, probe-relaxed');
+    setEq(tierArms[0].split('|'), EXEC_CONTRACT.passthrough.blocked, 'tier-1 arm ⟷ manifest blocked');
+    setEq(tierArms[1].split('|'), EXEC_CONTRACT.passthrough.probeRelaxed, 'tier-2 arm ⟷ manifest probeRelaxed');
+  });
+
+  it('the in-test tier samples cover every manifest tier pattern (behavioural forward guard)', () => {
+    // ALWAYS_BLOCKED / PROBE_RELAXABLE drive the real behaviour suite above; pin them
+    // to the manifest so a tier edit cannot leave the behavioural samples stale.
+    const sample = (patterns) => patterns.map((p) => p.replace(/\*$/, ''));
+    const covered = (flags, patterns) =>
+      sample(patterns).every((p) => flags.some(([f]) => f === p || f.startsWith(p)));
+    assert.ok(covered(ALWAYS_BLOCKED, EXEC_CONTRACT.passthrough.blocked), 'every blocked pattern has a behavioural sample');
+    assert.ok(covered(PROBE_RELAXABLE, EXEC_CONTRACT.passthrough.probeRelaxed), 'every probe pattern has a behavioural sample');
+  });
+});

package/bridges/codex-cli-bridge/bin/codex-review.sh

@@ -31,6 +31,34 @@
 # on disk remain readable under read-only — read-scoping is a prompt concern).
 set -euo pipefail
 
+# --- --help / -h (pre-preflight: no codex, no login, no git tree needed) -------
+# Keyed ONLY on the FIRST argument — never a scan of all args (uniform rule across
+# the four wrappers, so an open wrapper's passthrough payload is never intercepted).
+# The contract below is drift-guarded against capability.json roles.review.contract.
+case "${1:-}" in
+  --help|-h)
+    cat <<'HELP'
+codex-review — read-only ADVISORY review by the OpenAI Codex CLI (subscription-only; frontier model at max effort).
+
+Usage:
+  codex-review plan <plan-file>
+  codex-review code [extra focus...]
+
+Grounding:
+  automatic — the wrapper precomputes the full working-tree change set (repo map,
+  status, diffs, untracked contents) and codex auto-merges the root AGENTS.md;
+  no grounding flags
+
+Round-2 / resume:
+  (none — one-shot; a follow-up review is a fresh run)
+
+Environment: CODEX_REVIEW_SCHEMA=1 (structured JSON findings), CODEX_HARD_TIMEOUT (seconds, default 1800), CODEX_PROBE=1 (throwaway probe only).
+Requires at run time: the codex CLI on PATH, a ChatGPT-subscription login, a git work tree with a root AGENTS.md (--help needs none of these).
+HELP
+    exit 0
+    ;;
+esac
+
 DEFAULT_CODEX_MODEL="gpt-5.5"
 DEFAULT_CODEX_EFFORT="xhigh"
 CODEX_MODEL="${CODEX_MODEL:-$DEFAULT_CODEX_MODEL}"