@sabaiway/agent-workflow-kit 5.1.0 → 5.2.0

package/tools/cheap-agents.mjs

@@ -28,7 +28,7 @@
 import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { shellQuoteArg } from './review-state.mjs';
+import { shellQuoteArg } from './repo-lex.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -48,6 +48,12 @@ export const CHEAP_AGENTS_STAMP = 'CHEAP_AGENTS_STAMP';
 export const CHEAP_AGENTS_SYMLINK = 'CHEAP_AGENTS_SYMLINK';
 export const CHEAP_AGENTS_BUNDLE = 'CHEAP_AGENTS_BUNDLE';
 
+// The fallback-lens contract, formalized where it lives (flow-orchestration #15/#3, Phase 4.3):
+// the internal-attestation evaluation consumes this sentence — a lens set claiming a configured
+// backend's slot without a then-active down-mark REFUSES, quoting it (substitution is recorded,
+// never silent).
+export const FALLBACK_LENS_ADDITIONAL_ONLY = 'review-lens is an ADDITIONAL read-only review opinion, not a replacement for your configured review recipe.';
+
 const USAGE = `usage: cheap-agents [--dry-run | --apply] [--cwd <dir>] [--help]
 
 Places the bundled READ-ONLY subagent definitions into the project's ${AGENTS_DIR}/. No vehicle
@@ -191,7 +197,7 @@ export const formatResult = (result) => {
   }
   lines.push(
     'the vehicles are Claude Code subagents with READ-ONLY tools and NO shell — so a fan-out can never turn into a wave of approval prompts.',
-    'three ride the cheap lane (model: haiku, effort: low) for mechanical work; review-lens is an ADDITIONAL read-only review opinion, not a replacement for your configured review recipe. Writing code and running gates stay on your main lane.',
+    `three ride the cheap lane (model: haiku, effort: low) for mechanical work; ${FALLBACK_LENS_ADDITIONAL_ONLY} Writing code and running gates stay on your main lane.`,
   );
   // A preview must print the EXACT command that applies it. The advisor renders this dry-run as an
   // item's one-liner, and that flow's contract is "run the printed command, no improvisation" — a

package/tools/commands.mjs

@@ -196,6 +196,20 @@ const CATALOG = [
     kind: WRITER,
     oneLine: 'Set the per-project autonomy policy from plain language — which actions always ask (commit/push/publish/network) and how autonomously each activity runs; previews the change, then writes the policy when you confirm.',
   },
+  {
+    key: 'set-flow',
+    invocation: invocationOf('set-flow'),
+    group: 'Orchestrate',
+    kind: WRITER,
+    oneLine: 'Arm the per-project review-flow settings from a preset plus explicit keys — previews the merged flow block, verifies the declared bookkeeping files and the kit version floor, then writes the config when you confirm.',
+  },
+  {
+    key: 'flow-writer',
+    invocation: invocationOf('flow-writer'),
+    group: 'Orchestrate',
+    kind: WRITER,
+    oneLine: 'Record an explicit review-flow step (adoption/park/resume/complete of a plan, re-baseline, a rerun cause, a reviewer down-mark, a degrade justification, a checkpoint-approved override, a manifest-bound consult attestation) into the shared flow record store — flow-check refusals print the exact command to paste, and the store itself validates every append.',
+  },
   {
     key: 'review-state',
     invocation: invocationOf('review-state'),
@@ -203,6 +217,13 @@ const CATALOG = [
     kind: READ_ONLY,
     oneLine: 'Check that every configured review backend has receipted the current uncommitted tree with a fresh grounded review; --check turns it into a gate exit code.',
   },
+  {
+    key: 'receipt-deadline',
+    invocation: invocationOf('receipt-deadline'),
+    group: 'Orchestrate',
+    kind: READ_ONLY,
+    oneLine: 'Wait for ONE dispatched review to answer — a strictly-newer receipt line from that backend past the pre-dispatch watermark (or its nonce-named finding manifest); a shrunken or rewritten receipts file refuses loudly, and the timeout names the watermark.',
+  },
   {
     key: 'grounding',
     invocation: invocationOf('grounding'),
@@ -271,8 +292,9 @@ export const kindOf = (key) => byKey.get(key)?.kind ?? null;
 // (`upgrade`) OR the full slash form (`/agent-workflow-kit upgrade`); the first word is significant
 // and trailing args are ignored. Precise semantics:
 //   undefined / null / '' / whitespace-only / the exact bare invocation → 'bootstrap'
-//   a known first token (upgrade/status/setup/backends/recipes/procedures/velocity/agents/hook/
-//     gates/set-recipe/uninstall/migrate-adr-store/help) → that mode
+//   a known first token (any non-bootstrap catalog key — upgrade/status/setup/backends/recipes/
+//     procedures/velocity/agents/hook/gates/set-recipe/set-flow/flow-writer/uninstall/
+//     migrate-adr-store/help/…) → that mode
 //   anything else (unrecognized / ambiguous) → 'help'  (read-only — NEVER a writer/guarded mode)
 export const routeInvocation = (token) => {
   if (token == null) return BARE_INVOCATION_MODE;

package/tools/commit-guard.mjs

@@ -20,8 +20,15 @@
 //      from the recorded one · evidence hashes that no longer match the store's canonical
 //      red-proof/degrade serializations · an lcov file whose sha moved. The guard's own reads
 //      resolve FIXED git-dir paths (env overrides are producer test seams, never guard inputs);
-//   3. re-computes the review-state decision (the ship-receipt arm) — a missing/vetoed ship
-//      receipt refuses.
+//   3. consults the flow decision (Plan 3 Phase 2, two-tier): with NO flow store file the guard is
+//      byte-identical to the pre-flow guard; a PRESENT store must read clean and its refusals
+//      (open own chain, base motion, coverage, ordering) refuse the commit with the flow-check
+//      reason verbatim — a foreign worktree's chain stays advisory; the armed state extends the
+//      PASS line;
+//   4. re-computes the review-state decision (the ship-receipt arm) — a missing/vetoed ship
+//      receipt refuses. The env it hands over is SANITIZED (receipts/evidence/flow-store producer
+//      seams stripped) so a poisoned override can neither redirect nor mask any store this guard
+//      reads.
 // `git commit --no-verify` stays the stated residual (a self-discipline mechanism, not a security
 // boundary). Read-only; dependency-free; Node >= 22. No side effects on import.
 
@@ -34,6 +41,7 @@ import { computeTreeFingerprint, buildState, decideCheck, quoteReportName, shell
 import { resolveEvidencePath, readEvidence, authoritativeOfKind, canonicalKindSerialization, computeWorkingState } from './core-evidence.mjs';
 import { resolveLcovPath } from './coverage-check.mjs';
 import { GATES_REL, loadDeclaration } from './run-gates.mjs';
+import { computeFlowDecision } from './flow-check.mjs';
 
 const usageFail = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { exitCode: 2 });
 const sha = (text) => createHash('sha256').update(text).digest('hex');
@@ -238,18 +246,42 @@ export const runGuard = ({ cwd = process.cwd(), env = process.env } = {}) => {
       return { code: 1, lines: ['commit-guard: REFUSED — the lcov file the receipt consumed moved or vanished; re-run run-gates.mjs --final'] };
     }
   }
-  // The ship-receipt arm: the SAME normative decision review-state --check computes (configured
-  // obligations, ship-class-only, veto, degrade escape) — a file-read recompute, no subprocess —
-  // over a SANITIZED env: the store overrides are producer test seams, and honoring them HERE
-  // would let a forged receipts/degrade store bypass the fixed-path reads above.
+  // The flow arm (#43/P3, two-tier over FIXED git-derived paths): no store file ⇒ byte-exact
+  // prior behavior; a present store's refusals (malformed reads included) refuse with the
+  // flow-check reason verbatim. The commit-guard consumer mode arms the D10 flow→final
+  // comparison (Plan 4 Decision 2) — the in-matrix flow-check gate stays inert on it.
+  const flow = computeFlowDecision({ cwd, consumer: 'commit-guard' });
+  // NOT gated on flow.present: the D10 binding refusal fires precisely when a receipt carries
+  // evidenceHashes.flow and the store has since VANISHED (present=false) — a deletion must
+  // never un-arm the binding. A no-store repo with no flow-bearing receipt still yields zero
+  // refusals (byte-exact pre-flow behavior).
+  if (flow.refusals.length > 0) {
+    return {
+      code: 1,
+      lines: [
+        `commit-guard: REFUSED — the flow store refuses this commit: ${flow.refusals[0]}`,
+        ...flow.refusals.slice(1).map((r) => `commit-guard: flow refusal — ${r}`),
+      ],
+    };
+  }
+  // The ship-receipt arm: the SAME normative decision review-state --check computes, over a
+  // SANITIZED env — the receipts/evidence/flow-store overrides are producer test seams, and
+  // honoring them HERE would let a forged store bypass the fixed-path reads above.
   const reviewEnv = { ...env };
   delete reviewEnv.AW_REVIEW_RECEIPTS;
   delete reviewEnv.AW_CORE_EVIDENCE;
+  delete reviewEnv.AW_FLOW_STORE;
   const review = decideCheck(buildState({ cwd, env: reviewEnv }));
   if (review.code !== 0) {
     return { code: 1, lines: [`commit-guard: REFUSED — the review obligations are not satisfied: ${review.reason}`] };
   }
-  return { code: 0, lines: [`commit-guard: PASS — a green final receipt binds this exact tree (${fingerprint.slice(0, 12)}…), the declaration and evidence hashes match, and the review obligations are satisfied`] };
+  const flowSuffix = flow.present && flow.armed
+    ? ` — flow: armed${review.flowLabels?.length ? ` (${review.flowLabels.join('; ')})` : ''}`
+    : '';
+  const flowAdvisoryLines = flow.present && flow.armed
+    ? flow.advisories.map((a) => `commit-guard: flow advisory — ${a}`)
+    : [];
+  return { code: 0, lines: [`commit-guard: PASS — a green final receipt binds this exact tree (${fingerprint.slice(0, 12)}…), the declaration and evidence hashes match, and the review obligations are satisfied${flowSuffix}`, ...flowAdvisoryLines] };
 };
 
 const HELP = `commit-guard — the read-only pre-commit guard (agent-workflow family, D10).
@@ -262,8 +294,11 @@ paths, reviewable untracked paths, or a dirty tracked submodule, each named with
 this deliberately blocks a partial commit), then recomputes the current tree fingerprint and binds
 the LATEST completed run-gates --final receipt — refusing on { no receipt for this tree · a red
 latest attempt · before≠after · declaration content drift · evidence-hash drift · lcov drift ·
-unsatisfied review obligations (the review-state decision) }. Wire it into pre-commit;
-\`git commit --no-verify\` stays the stated residual (self-discipline, not a security boundary).
+a flow-store refusal (a PRESENT store's open own chain / base motion / coverage — verbatim; no
+store file = byte-exact pre-flow behavior) · unsatisfied review obligations (the review-state
+decision, over a sanitized env — receipts/evidence/flow-store seams stripped) }. Wire it into
+pre-commit; \`git commit --no-verify\` stays the stated residual (self-discipline, not a security
+boundary).
 
 Exit codes: 0 pass; 1 refused (reason named); 2 usage.`;
 

package/tools/core-evidence.mjs

@@ -34,12 +34,14 @@
 // checker, not here. Dependency-free. No side effects on import.
 
 import { readFileSync, lstatSync, realpathSync, readlinkSync, openSync, readSync, closeSync } from 'node:fs';
-import { join, dirname, isAbsolute, normalize, sep, basename } from 'node:path';
+import { join, dirname, normalize, sep, basename } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { writeContainedFileAtomic } from './atomic-write.mjs';
 import { parsePositiveIntKnob, probeVerdict } from './changed-surface.mjs';
+import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { lexicalRepoRelative } from './repo-lex.mjs';
 
 export const CORE_EVIDENCE_STOP = 'CORE_EVIDENCE_STOP';
 const stop = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'CoreEvidenceStop', code: CORE_EVIDENCE_STOP });
@@ -399,17 +401,20 @@ export const resolveReceiptsPath = (cwd, env = process.env) => {
 };
 
 // Parse the receipt file → { receipts, malformed, readError? }. Absent file → empty (not an
-// error: no review ever ran). A NON-ENOENT read failure surfaces as readError — an unreadable
-// store must never silently read as "no receipts" (the summary withholds its verdicts section on
-// it). A malformed line is counted + reported, never silently dropped.
-export const readReceipts = (path, readFile = readFileSync) => {
-  let raw;
-  try {
-    raw = readFile(path, 'utf8');
-  } catch (err) {
-    if (err && err.code === 'ENOENT') return { receipts: [], malformed: 0 };
-    return { receipts: [], malformed: 0, readError: (err && err.code) || (err && err.message) || 'read failed' };
+// error: no review ever ran). The read rides the fs-read-nofollow leaf (RECEIPTS-READER-NOFOLLOW):
+// a symlinked/FIFO/directory receipts path surfaces as readError — never content, never an empty
+// success — and any NON-ENOENT failure surfaces as readError too; an unreadable store must never
+// silently read as "no receipts" (the summary withholds its verdicts section on it). A malformed
+// line is counted + reported, never silently dropped. `io` is the injectable-read test seam
+// (readRegularFileNoFollow's descriptor-level io).
+export const readReceipts = (path, io = {}) => {
+  const read = readRegularFileNoFollow(path, io);
+  if (read.outcome === 'absent') return { receipts: [], malformed: 0 };
+  if (read.outcome === 'foreign') {
+    return { receipts: [], malformed: 0, readError: `the receipts store is a ${read.className}, not a regular file — refusing to read it (fail closed)` };
   }
+  if (read.outcome === 'error') return { receipts: [], malformed: 0, readError: read.code };
+  const raw = read.content;
   const receipts = [];
   let malformed = 0;
   for (const line of raw.split('\n')) {
@@ -593,17 +598,10 @@ const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
 const HEX64_RE = /^[0-9a-f]{64}$/;
 const HEX40_RE = /^[0-9a-f]{40}$/;
 
-// The LEXICAL half of the repo-relative rule — ONE home shared by the record validator (which has
-// no fs to resolve against) and the fs resolver below, so the two can never drift: a forged record
-// carrying an equal-but-absolute (or escaping) testId/file pair is refused at validation, not just
-// at observation time.
-export const lexicalRepoRelative = (rel) => {
-  if (typeof rel !== 'string' || rel.length === 0) return { ok: false, reason: 'empty file path' };
-  if (isAbsolute(rel)) return { ok: false, reason: `absolute path "${rel}" — the testId file half must be repo-relative` };
-  const norm = normalize(rel);
-  if (norm === '..' || norm.startsWith(`..${sep}`)) return { ok: false, reason: `path "${rel}" escapes the repo root` };
-  return { ok: true };
-};
+// The LEXICAL half of the repo-relative rule lives in the repo-lex.mjs LEAF (ONE home shared by
+// the record validators — flow-record has no fs to resolve against — and the fs resolver below,
+// so the two can never drift); re-exported here so every historical consumer keeps its import site.
+export { lexicalRepoRelative } from './repo-lex.mjs';
 
 export const validateEvidenceRecord = (record) => {
   if (!isPlainObject(record)) return { ok: false, reason: 'record is not an object' };
@@ -664,6 +662,11 @@ export const validateEvidenceRecord = (record) => {
       || typeof record.evidenceHashes.degrade !== 'string' || !HEX64_RE.test(record.evidenceHashes.degrade)) {
       return { ok: false, reason: 'final: evidenceHashes must carry 64-hex sha256 of the canonical red-proof and degrade serializations' };
     }
+    // The D10 flow binding (Plan 4 Decision 2) is ADDITIVE: absent = a pre-flow-binding final
+    // (still valid); present must be the 64-hex owner-scoped projection hash.
+    if ('flow' in record.evidenceHashes && (typeof record.evidenceHashes.flow !== 'string' || !HEX64_RE.test(record.evidenceHashes.flow))) {
+      return { ok: false, reason: 'final: evidenceHashes.flow, when present, must be a 64-hex sha256 of the owner-scoped flow projection' };
+    }
     if (record.lcovSha256 !== null && (typeof record.lcovSha256 !== 'string' || !HEX64_RE.test(record.lcovSha256))) {
       return { ok: false, reason: 'final: lcovSha256 must be a 64-hex sha256 of the consumed lcov file, or null when none was produced' };
     }

package/tools/detect-backends.mjs

@@ -90,19 +90,22 @@ const RAW_BACKENDS = [
       },
       review: {
         invocations: [
-          'codex-review plan <plan-file>',
-          'codex-review code [extra focus...]',
+          'codex-review plan <plan-file> [--nonce <n>]',
+          'codex-review code [--nonce <n>] [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',
         continue: [],
-        receipt: 'side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan mode; verdict parsed from the mandated literal verdict line (schema mode: the verdict field); always fresh:true (one-shot) + grounded:true (native AGENTS.md auto-merge, factsHash null); probe = whether the run relaxed the quality guards (CODEX_PROBE=1), written on EVERY receipt so it self-declares — the kit\'s review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); posture = the ACTUAL run posture {model, effort, tier} (tier null on the standard tier), written on EVERY receipt (D5) — the gate rejects a receipt with an absent/invalid posture (a pre-D5 wrapper minted it; re-run the review), one stderr banner line states the same posture, and a posture value carrying control bytes refuses pre-spend in every mode; a run whose final message carries NO recognized \'Verdict: <ship|revise|rethink>\' line — empty or missing output included — exits 4 with NO receipt (D4: a FAILED review to RE-RUN, never a fatal session error); a write failure warns, never fails the review',
+        receipt: 'side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan mode; verdict parsed from the mandated literal verdict line (schema mode: the verdict field); always fresh:true (one-shot) + grounded:true (native AGENTS.md auto-merge, factsHash null); probe = whether the run relaxed the quality guards (CODEX_PROBE=1), written on EVERY receipt so it self-declares — the kit\'s review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); posture = the ACTUAL run posture {model, effort, tier} (tier null on the standard tier), written on EVERY receipt (D5) — the gate rejects a receipt with an absent/invalid posture (a pre-D5 wrapper minted it; re-run the review), one stderr banner line states the same posture, and a posture value carrying control bytes refuses pre-spend in every mode; a run whose final message carries NO recognized \'Verdict: <ship|revise|rethink>\' line — empty or missing output included — exits 4 with NO receipt (D4: a FAILED review to RE-RUN, never a fatal session error); when the dispatch nonce seam is supplied — the AW_REVIEW_NONCE environment value or its plain-argument equivalent --nonce <n> (one seam: the flag assigns the same value; supplying both with different values refuses pre-spend) — under the safe grammar [A-Za-z0-9._-]{1,64} (anything else refuses pre-spend), the wrapper first mints the finding MANIFEST {schema, backend, nonce, fingerprint, findings} beside the receipts file (agent-workflow-finding-manifest-<backend>-<nonce>.json; atomic, no-clobber — a byte-identical rewrite is an idempotent no-op, different bytes refuse loudly) ORDERED before the receipt append — a failed manifest write EXCLUDES the receipt append, so a nonce-supplied dispatch can never land a receipt without its readable manifest; a nonce-less invocation adds NO nonce field and mints NO finding manifest (the existing wrapperVersion field still changes with each bridge release); a write failure warns, never fails the review',
         notes: [
-          'the review posture banner appends a banner-only timeout=<duration|uncapped> field — exactly the duration handed to timeout(1), uncapped when no timeout/gtimeout binary caps the run; INFORMATIONAL only: it never enters the receipt posture or the D5 banner↔receipt parity',
+          'the review posture banner appends a banner-only timeout=<duration> field — exactly the duration handed to timeout(1); the hard-timeout preflight fails CLOSED when no timeout/gtimeout binary exists (the wrapper refuses by name before any CLI run, so an uncapped review run can no longer happen), and the field never enters the receipt posture or the D5 banner↔receipt parity',
           'quote the posture banner verbatim when labeling this dispatch — the banner is the machine-stated posture; a prose re-type drifts',
         ],
       },
     },
     bin: 'codex',
+    // The per-backend receipt-deadline default (seconds) the capability block reports — the review
+    // wrapper's built-in hard cap (CODEX_HARD_TIMEOUT review default), an OFFLINE registry fact.
+    deadlineDefaultS: 1800,
     credential: { env: 'CODEX_HOME', default: '~/.codex', file: 'auth.json' },
     setupUrl: 'https://github.com/sabaiway/agent-workflow/blob/main/codex-cli-bridge/setup/README.md',
     setupPathLocal: 'setup/README.md',
@@ -118,9 +121,9 @@ const RAW_BACKENDS = [
     roleContracts: {
       review: {
         invocations: [
-          'agy-review code [--facts @f] [--ungrounded] [--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 "…"]',
+          'agy-review code [--facts @f] [--ungrounded] [--decided @f] [--focus "…"] [--nonce <n>] [extra focus…]',
+          'agy-review plan <plan-file> [--facts @f] [--decided @f] [--focus "…"] [--nonce <n>]',
+          'agy-review diff <diff-file> [--facts @f] [--decided @f] [--focus "…"] [--nonce <n>]',
         ],
         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). code mode REQUIRES a non-empty --facts payload and refuses BEFORE spending a run (escapes: --ungrounded, AGY_PROBE=1); plan/diff proceed with a loud warning',
         flags: [
@@ -128,20 +131,23 @@ const RAW_BACKENDS = [
           '--ungrounded — deliberately ungrounded CODE review, a throwaway opinion (code mode only, contradicts --facts; the receipt records grounded:false and never attests)',
           '--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)',
+          '--nonce <n> — the flow dispatch nonce, the plain-argument lane onto the AW_REVIEW_NONCE seam (one seam: flag and a non-empty env must agree; a disagreeing pair refuses pre-spend)',
         ],
         continue: [
-          'agy-review --continue [--decided @f] [--focus "…"]',
-          'agy-review --conversation <id> [--decided @f] [--focus "…"]',
+          'agy-review --continue [--decided @f] [--focus "…"] [--nonce <n>]',
+          'agy-review --conversation <id> [--decided @f] [--focus "…"] [--nonce <n>]',
         ],
-        receipt: "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (code mode refuses pre-spend without one — no run, no receipt — unless --ungrounded/AGY_PROBE=1; in plan/diff an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); probe = whether the run relaxed the quality guards (AGY_PROBE=1), written on EVERY receipt so it self-declares — the kit's review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); posture = the ACTUAL run posture {model} (agy has no tier), written on EVERY receipt (D5) — the gate rejects a receipt with an absent/invalid posture (a pre-D5 wrapper minted it; re-run the review), one stderr banner line states the same posture, an ATTESTING review with AGY_MODEL explicitly emptied refuses pre-spend, and a model string carrying control bytes refuses pre-spend in every mode; delivery = how the change set REACHED the model, currently emitted as 'inline' (the whole set rode one prompt — proven by construction) or 'fed' (a chunked feed whose per-part echo proof verified); REQUIRED on every agy code receipt and its ABSENCE is what stops a pre-fed-lane receipt attesting, while the gate accepts any well-formed declaration rather than a particular value; absent by construction on plan/diff/continuation receipts, which carry no change set; a run whose output carries NO recognized '### Verdict' section — empty output included — exits 4 with NO receipt (D4: a FAILED review to RE-RUN, never a fatal session error); a write failure warns, never fails the review",
+        receipt: "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (code mode refuses pre-spend without one — no run, no receipt — unless --ungrounded/AGY_PROBE=1; in plan/diff an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); probe = whether the run relaxed the quality guards (AGY_PROBE=1), written on EVERY receipt so it self-declares — the kit's review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); posture = the ACTUAL run posture {model} (agy has no tier), written on EVERY receipt (D5) — the gate rejects a receipt with an absent/invalid posture (a pre-D5 wrapper minted it; re-run the review), one stderr banner line states the same posture, an ATTESTING review with AGY_MODEL explicitly emptied refuses pre-spend, and a model string carrying control bytes refuses pre-spend in every mode; delivery = how the change set REACHED the model, currently emitted as 'inline' (the whole set rode one prompt — proven by construction) or 'fed' (a chunked feed whose per-part echo proof verified); REQUIRED on every agy code receipt and its ABSENCE is what stops a pre-fed-lane receipt attesting, while the gate accepts any well-formed declaration rather than a particular value; absent by construction on plan/diff/continuation receipts, which carry no change set; a run whose output carries NO recognized '### Verdict' section — empty output included — exits 4 with NO receipt (D4: a FAILED review to RE-RUN, never a fatal session error); when the dispatch nonce seam is supplied — the AW_REVIEW_NONCE environment value or its plain-argument equivalent --nonce <n> (one seam: the flag assigns the same value; supplying both with different values refuses pre-spend) — under the safe grammar [A-Za-z0-9._-]{1,64} (anything else refuses pre-spend), the wrapper first mints the finding MANIFEST {schema, backend, nonce, fingerprint, findings} beside the receipts file (agent-workflow-finding-manifest-<backend>-<nonce>.json; atomic, no-clobber — a byte-identical rewrite is an idempotent no-op, different bytes refuse loudly) ORDERED before the receipt append — a failed manifest write EXCLUDES the receipt append, so a nonce-supplied dispatch can never land a receipt without its readable manifest; a nonce-less invocation adds NO nonce field and mints NO finding manifest (the existing wrapperVersion field still changes with each bridge release); a write failure warns, never fails the review",
         notes: [
           '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',
-          'the review posture banner appends a banner-only timeout=<duration|uncapped> field — exactly the duration agy-run hands to timeout(1), uncapped when no timeout/gtimeout binary caps the run; INFORMATIONAL only: it never enters the receipt posture or the D5 banner↔receipt parity',
+          'the review posture banner appends a banner-only timeout=<duration> field — exactly the duration agy-run hands to timeout(1); the hard-timeout preflight fails CLOSED when no timeout/gtimeout binary exists (the wrapper refuses by name before any CLI run, so an uncapped review run can no longer happen), and the field never enters the receipt posture or the D5 banner↔receipt parity',
           'quote the posture banner verbatim when labeling this dispatch — the banner is the machine-stated posture; a prose re-type drifts',
         ],
       },
     },
     bin: 'agy',
+    // AGY_HARD_TIMEOUT's built-in review default is 30m — reported in seconds, an OFFLINE registry fact.
+    deadlineDefaultS: 1800,
     credential: { env: null, default: '~/.gemini/antigravity-cli', file: 'antigravity-oauth-token' },
     setupUrl: 'https://github.com/sabaiway/agent-workflow/blob/main/antigravity-cli-bridge/setup/README.md',
     setupPathLocal: 'setup/README.md',
@@ -169,6 +175,20 @@ export const wrapperCmdFor = (backendName, role) =>
 export const wrapperContractFor = (backendName, role) =>
   KNOWN_BACKENDS.find((b) => b.name === backendName)?.roleContracts?.[role] ?? null;
 
+// The declared per-backend CAPABILITY block (flow-orchestration #15): roles, review-contract
+// presence, and the receipt-deadline default — sourced OFFLINE from the registry alone. PURE over
+// KNOWN_BACKENDS: no fs probe, no spawn, and never a live subscription CLI run (the detector as a
+// whole spawns nothing — a source-level pin holds that).
+export const backendCapability = (backendName) => {
+  const entry = KNOWN_BACKENDS.find((b) => b.name === backendName);
+  if (entry === undefined) return null;
+  return {
+    roles: Object.keys(entry.roleCmds ?? {}),
+    reviewContract: (entry.roleContracts?.review ?? null) !== null,
+    deadlineDefaultS: entry.deadlineDefaultS,
+  };
+};
+
 // ── pure helpers ─────────────────────────────────────────────────────────────
 
 // Expand a leading "~" / "~/x" against home; absolute and relative paths pass through untouched.
@@ -329,6 +349,7 @@ export const detectBackend = (entry, deps = {}) => {
     wrappers,
     readiness,
     setupHint,
+    capability: backendCapability(entry.name),
   };
 };
 

package/tools/doc-parity.mjs

@@ -35,9 +35,13 @@ import {
 import { SKIPPED_READONLY } from './setup-backends.mjs';
 import { LATENT_ARM_NOTICE } from './review-state.mjs';
 import { QUEUE_SHARED_RULE, LANDING_FROM_MAIN, NO_DEPENDENCIES_POSTURE, CLEANUP_OWNERSHIP_RULE, INCLUDE_IDENTITY_RULE, RESUME_VERIFY_RULE } from './worktrees.mjs';
-// The flow tolerate contract (tolerate-only release): the accepted schema version + the honest
-// lagging-kit sentence, both owned by the config validator and pinned into procedures.md.
+// The flow contract constants: the accepted schema version + the honest lagging-kit sentence
+// (owned by the config validator), and the set-flow bookkeeping-floor residual (owned by the
+// arming writer) — each pinned byte-exact into its mode doc(s).
 import { FLOW_SCHEMA_VERSION, FLOW_LAGGING_KIT_CONTRACT } from './orchestration-config.mjs';
+import { FLOW_BOOKKEEPING_FLOOR_RESIDUAL } from './set-flow.mjs';
+import { FLOW_ARMED_HALVES_HEADER } from './procedures.mjs';
+import { RECEIPT_DEADLINE_CONTRACT } from './receipt-deadline.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -49,6 +53,8 @@ const SETUP_DOC = 'references/modes/setup.md';
 const REVIEW_STATE_DOC = 'references/modes/review-state.md';
 const WORKTREES_DOC = 'references/modes/worktrees.md';
 const PROCEDURES_DOC = 'references/modes/procedures.md';
+const SET_FLOW_DOC = 'references/modes/set-flow.md';
+const RECEIPT_DEADLINE_DOC = 'references/modes/receipt-deadline.md';
 
 // A typed usage failure (exit 2) for the CLI parser — the codebase's typed-error idiom (no classes).
 const usageFail = (message) => Object.assign(new Error(message), { exitCode: 2 });
@@ -120,13 +126,22 @@ export const BINDINGS = Object.freeze([
   // a reworded mode doc dropping the per-owned-path × session-never-probed contract fails this pin
   // plus the gate.
   valueBinding('resume-verify-rule', RESUME_VERIFY_RULE, RESUME_VERIFY_RULE, [WORKTREES_DOC]),
-  // The flow tolerate contract: (a) the accepted NUMERIC `flow` schema version renders into the
+  // The flow contract pins: (a) the accepted NUMERIC `flow` schema version renders into the
   // procedures.md allowed-shape contract line — a bumped constant with an unchanged doc fails this
   // pin plus the gate; (b) the honest lagging-kit sentence — what a pre-flow kit does on meeting a
-  // `flow` block, and that this release enforces nothing against such a reader — renders as the
-  // exact exported sentence into the exit-1 contract line, so the admission cannot be reworded away.
+  // `flow` block, and exactly what the now-armed set-flow floor can and cannot reach — renders as
+  // the exact exported sentence into BOTH flow-facing mode docs (amended with set-flow, P12);
+  // (c) the set-flow bookkeeping-floor residual — the honest boundary of what the arming floors
+  // decide — renders byte-exact into the set-flow mode doc; (d) the procedures armed-halves header —
+  // the session-start flow-state surface (P8) — renders into procedures.md.
   valueBinding('flow-schema-version', FLOW_SCHEMA_VERSION, `\`"schema": ${FLOW_SCHEMA_VERSION}\``, [PROCEDURES_DOC]),
-  valueBinding('flow-lagging-kit', FLOW_LAGGING_KIT_CONTRACT, FLOW_LAGGING_KIT_CONTRACT, [PROCEDURES_DOC]),
+  valueBinding('flow-lagging-kit', FLOW_LAGGING_KIT_CONTRACT, FLOW_LAGGING_KIT_CONTRACT, [PROCEDURES_DOC, SET_FLOW_DOC]),
+  valueBinding('flow-bookkeeping-floor-residual', FLOW_BOOKKEEPING_FLOOR_RESIDUAL, FLOW_BOOKKEEPING_FLOOR_RESIDUAL, [SET_FLOW_DOC]),
+  valueBinding('flow-armed-halves-header', FLOW_ARMED_HALVES_HEADER, FLOW_ARMED_HALVES_HEADER, [PROCEDURES_DOC]),
+  // The receipt-deadline runner's contract sentence (Plan-3 Phase 4.1): arrival — never obligation
+  // satisfaction — is the tool's identity; a mode doc silently drifting off it would re-open the
+  // #50 misclassification this runner exists to close.
+  valueBinding('receipt-deadline-contract', RECEIPT_DEADLINE_CONTRACT, RECEIPT_DEADLINE_CONTRACT, [RECEIPT_DEADLINE_DOC]),
 ].map((b) => Object.freeze(b)));
 
 // ── the pure checker (readText is injectable for hermetic tests) ────────────────────────