@sabaiway/agent-workflow-kit 5.9.0 → 5.11.0

package/tools/commit-guard.mjs

@@ -11,7 +11,15 @@
 //      up to INDEX_LAG_PATH_CAP with the remainder stated. A dirty tracked SUBMODULE is named
 //      separately with its own recovery. Fail-closed on an undecidable probe. This BLOCKS the
 //      deliberate partial commit by design — `--no-verify` is the stated residual, not a flag;
-//   1. recomputes the CURRENT tree fingerprint (the review-state export — read-only git plumbing);
+//   1. recomputes the CURRENT tree fingerprint (the review-state export — read-only git plumbing),
+//      and decides the two CONTENT-FREE lanes here, because no store read can answer them: a
+//      payload with no bytes yields the ONE fingerprint every clean moment of every repository
+//      shares, so any receipt at it was minted elsewhere and may attest nothing. With a DIRTY
+//      index that means staged content the payload cannot see (a gitlink hidden by
+//      `submodule.<name>.ignore` / `diff.ignoreSubmodules`) and the guard REFUSES, naming the
+//      configuration rather than re-staging; with a clean index the commit introduces no bytes
+//      (`--allow-empty`, a message-only `--amend`, an empty merge) and the guard PASSES while
+//      stating that it attests NOTHING — the receipt arms are skipped, never satisfied;
 //   2. reads the LATEST completed final-run record from the core-evidence store (only the latest
 //      attempt at a fingerprint is authoritative — a green receipt is DEAD once a later attempt at
 //      the same fingerprint went red) and refuses on: no record for the current fingerprint · a
@@ -38,7 +46,10 @@ import { pathToFileURL, fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { computeTreeFingerprint, buildState, decideCheck, quoteReportName, shellQuoteArg } from './review-state.mjs';
-import { resolveEvidencePath, readEvidence, authoritativeOfKind, canonicalKindSerialization, computeWorkingState } from './core-evidence.mjs';
+import {
+  resolveEvidencePath, readEvidence, authoritativeOfKind, canonicalKindSerialization,
+  computeWorkingState, CONTENT_FREE_FINGERPRINT,
+} from './core-evidence.mjs';
 import { resolveLcovPath } from './coverage-check.mjs';
 import { GATES_REL, loadDeclaration } from './run-gates.mjs';
 import { computeFlowDecision } from './flow-check.mjs';
@@ -177,15 +188,42 @@ export const decideIndexLag = (state) => {
 };
 
 // runGuard({ cwd, env }) → { code, lines }. Every refusal names its recovery.
+// The flow decision's two renders, shared by every lane that consults it — the empty-commit lane
+// reaches the same store through the same consumer mode, so its wording can never drift from the
+// byte-carrying one.
+const flowRefusalLines = (flow) => [
+  `commit-guard: REFUSED — the flow store refuses this commit: ${flow.refusals[0]}`,
+  ...flow.refusals.slice(1).map((r) => `commit-guard: flow refusal — ${r}`),
+];
+const flowAdvisoryLines = (flow) => (flow.present && flow.armed
+  ? flow.advisories.map((a) => `commit-guard: flow advisory — ${a}`)
+  : []);
+
 export const runGuard = ({ cwd = process.cwd(), env = process.env } = {}) => {
   const rootTop = gitLine(['rev-parse', '--show-toplevel'], cwd);
   if (rootTop == null) return { code: 1, lines: ['commit-guard: not a git work tree — nothing to guard'] };
   // FIRST: a pure tree property needing no store read. Its recovery re-stages the tree and re-mints
   // the receipt, so every arm below is re-decided anyway — naming a stale fingerprint ahead of it
   // would send the operator down a recovery they must redo.
-  const indexLag = decideIndexLag(computeWorkingState(cwd));
+  const working = computeWorkingState(cwd);
+  const indexLag = decideIndexLag(working);
   if (indexLag !== null) return indexLag;
   const fingerprint = computeTreeFingerprint(cwd);
+  // The CONTENT-FREE lanes — the second pure tree property, decided here for the same reason the
+  // index lag is: no store read can answer it. A payload with no bytes states nothing about what
+  // this commit will carry, and its fingerprint is the ONE value every clean moment of every
+  // repository shares, so a receipt found at it was minted by some other moment, possibly at
+  // another base. Such evidence must therefore decide NOTHING here — neither refuse nor attest
+  // (the same fact flow-check-rungs.mjs applies to a red final). The index tells the two lanes
+  // apart, and `computeWorkingState` probes it with --ignore-submodules=none precisely so a
+  // config-hidden gitlink cannot pass for a clean one.
+  const contentFree = fingerprint === CONTENT_FREE_FINGERPRINT;
+  if (contentFree && working.stagedDirty) {
+    return {
+      code: 1,
+      lines: [`commit-guard: REFUSED — the index carries staged content the fingerprint domain cannot see (a submodule gitlink hidden from \`git diff\` by \`submodule.<name>.ignore\` or \`diff.ignoreSubmodules\`), so no final receipt can describe what this commit will carry. Recovery: clear that ignore setting (or set it to \`none\`) until \`git diff --cached --no-ext-diff\` shows the change, then re-run node ${FINAL_RUN_TOOL} --final`],
+    };
+  }
   // The guard's OWN reads resolve FIXED git-dir paths — a stray AW_CORE_EVIDENCE / AW_LCOV_FILE
   // in the committing shell must never redirect the LAST line of defense to a forged artifact
   // (the env stays a test seam for the producers, never for this consumer).
@@ -194,6 +232,27 @@ export const runGuard = ({ cwd = process.cwd(), env = process.env } = {}) => {
   if ((read.malformed ?? 0) > 0 || read.readError) {
     return { code: 1, lines: [`commit-guard: REFUSED — evidence store unavailable (${read.malformed} malformed line(s)${read.readError ? `, read error: ${read.readError}` : ''}); inspect ${storePath}`] };
   }
+  // The empty-commit lane: the index equals HEAD, so this commit introduces no bytes at all
+  // (`git commit --allow-empty`, a message- or signature-only `--amend`, an empty merge). The
+  // guard's whole claim is about bytes, so here it has none to make and says so. The receipt arms
+  // are SKIPPED rather than satisfied — consulting a content-free receipt would make the outcome
+  // depend on which stray clean moment happened to be recorded last. The flow arm still runs: an
+  // empty commit still moves HEAD, and the chain bookkeeping is about that, not about bytes; its
+  // own fingerprint-keyed correlations (the D10 flow→final binding, receipt and degrade coverage)
+  // drop out inside flow-check on the same fact, so no stray content-free record decides here
+  // either. Store HEALTH is deliberately NOT waived above: an unreadable store is not a
+  // correlation, and a store that cannot be read cannot answer the chain questions either.
+  if (contentFree) {
+    const emptyFlow = computeFlowDecision({ cwd, consumer: 'commit-guard', treeCarriesBytes: false });
+    if (emptyFlow.refusals.length > 0) return { code: 1, lines: flowRefusalLines(emptyFlow) };
+    return {
+      code: 0,
+      lines: [
+        'commit-guard: PASS — this commit changes no tree content (the index contributes no tree-content delta and the work tree adds nothing), so the guard attests NOTHING about it: a receipt found at the shared content-free fingerprint cannot be correlated to THIS moment or base',
+        ...flowAdvisoryLines(emptyFlow),
+      ],
+    };
+  }
   const finals = authoritativeOfKind(read.records, 'final');
   const current = finals.find((r) => r.fingerprintBefore === fingerprint) ?? null;
   if (!current) {
@@ -255,15 +314,7 @@ export const runGuard = ({ cwd = process.cwd(), env = process.env } = {}) => {
   // 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}`),
-      ],
-    };
-  }
+  if (flow.refusals.length > 0) return { code: 1, lines: flowRefusalLines(flow) };
   // 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.
@@ -278,10 +329,7 @@ export const runGuard = ({ cwd = process.cwd(), env = process.env } = {}) => {
   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] };
+  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(flow)] };
 };
 
 const HELP = `commit-guard — the read-only pre-commit guard (agent-workflow family, D10).
@@ -291,7 +339,16 @@ Usage:
 
 Re-runs NOTHING: refuses an INDEX that lags the verified working tree (FIRST — unstaged tracked
 paths, reviewable untracked paths, or a dirty tracked submodule, each named with its recovery;
-this deliberately blocks a partial commit), then recomputes the current tree fingerprint and binds
+this deliberately blocks a partial commit), then recomputes the current tree fingerprint.
+
+A CONTENT-FREE fingerprint (a payload with no bytes — the value every clean work tree shares)
+decides WITHOUT a receipt, because one found there was minted by another clean moment: with a dirty
+index it REFUSES (staged content the payload cannot see — a gitlink hidden by
+\`submodule.<name>.ignore\` / \`diff.ignoreSubmodules\`; the recovery is that configuration, not
+\`git add\`), and with a clean index it PASSES stating it attests NOTHING (the commit carries no
+bytes: \`--allow-empty\`, a message-only \`--amend\`, an empty merge).
+
+Otherwise it 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 ·
 a flow-store refusal (a PRESENT store's open own chain / base motion / coverage — verbatim; no

package/tools/core-evidence.mjs

@@ -160,6 +160,16 @@ export const computeTreeFingerprint = (cwd, fsx) => {
   return payload == null ? null : createHash('sha256').update(payload).digest('hex');
 };
 
+// The fingerprint of a CONTENT-FREE payload — a clean work tree emits no bytes at all, so this ONE
+// value is shared by every clean moment of every repository. It therefore identifies no working
+// state and correlates to no base: evidence found at it was minted by some other clean moment,
+// possibly at another base, and can decide nothing in either direction. Two situations reach it,
+// and only the INDEX tells them apart (never the payload): an empty commit, where the index equals
+// HEAD and no byte enters the repository, and staged content the payload cannot see — a gitlink
+// hidden from `git diff` by an ignore configuration. Read by the consumers that correlate a
+// fingerprint to a base (flow-check-rungs.mjs #65) and by commit-guard's two content-free lanes.
+export const CONTENT_FREE_FINGERPRINT = createHash('sha256').update(Buffer.alloc(0)).digest('hex');
+
 // The index↔worktree split the fingerprint deliberately CANNOT see: the payload above concatenates
 // the staged and unstaged diffs, so against an otherwise-empty index a hunk moving into the index
 // leaves it byte-identical — while `git commit` builds the commit from the INDEX alone. This is the

package/tools/detect-backends.mjs

@@ -141,6 +141,7 @@ const RAW_BACKENDS = [
         ],
         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: [
+          'transport: every review dispatch drives the CLI in --output-format json (plus --disable-slash-commands) and the returned envelope is parsed in node (bin/agy-envelope.mjs) — the operator-facing invocations and flags above do NOT change, and on a ZERO exit the wrapper still PRINTS the review text, never JSON. A missing or unreadable envelope on a zero exit is a loud failure with NO receipt, never a downgraded verdict and never a fallback to raw-stdout parsing; a non-zero CLI exit keeps its own code and message, and publishes the captured stdout unchanged from the SINGLE dispatch or the FINAL fed turn (which may therefore be a JSON or partial payload — the envelope is parsed only on a zero exit); an INTERMEDIATE feed turn is the exception, its output stays private (Invariant E) and its failure prints only a named error. Enforced by a PRE-SPEND capability probe, not a version floor: agy --help must advertise --output-format and --disable-slash-commands, node must be >= 22, and bin/agy-envelope.mjs must be present — otherwise the review refuses before any run is spent and names the missing capability',
           'pre-dispatch host-diff: before the FIRST dispatch of this bridge, diff its declared networkHosts against the live sandbox allow-list — a missing host is surfaced to the maintainer BEFORE dispatching, never fired into a known prompt',
           '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',

package/tools/dispatch-advisor.mjs

@@ -0,0 +1,323 @@
+// dispatch-advisor.mjs — the vehicle-routing ADVISOR (delegation Plan 3, Phase 1; D1-D4).
+//
+// One question, one answer: *which vehicle carries this step class on THIS host, and what has the
+// ledger already recorded for it.* That answer lived only in prose canon and in a remembered rule,
+// so a cold session routed a sub-task from memory or not at all. It is now a printed block at two
+// points of use — `dispatch advise` and the footer of a form-valid `dispatch check`.
+//
+// What it deliberately is NOT:
+//   • it never gates. Nothing here refuses a dispatch, and the footer prints ONLY over a form-valid
+//     contract, so the checker's exit contract and FIRST line stay byte-identical whatever this
+//     module concludes. A choice that diverges from the advice is a NOTE, never a refusal.
+//   • THIS MODULE writes nothing and spawns nothing — but the VERB that prints it is not spawn-free,
+//     and the honest split is stated in ADVISOR_PROBE_POSTURE below rather than claimed away here.
+//     Host capability is filesystem-only: the execute backend through the detector (which spawns
+//     nothing by a source-level pin), the cheap vehicles through the PRESENCE of
+//     `.claude/agents/<name>.md` at the repository top-level, which the CALLER resolves and declares.
+//   • it opens no second ledger door. The recorded history arrives as the CALLER's read outcome —
+//     `{ok:true, records}` or `{ok:false, reason}` — and is counted through the store's OWN thread
+//     walk (`delegationThreadState`), never a second walker. An unreadable store degrades the
+//     history line and leaves the advice standing.
+//
+// Portability is stated rather than assumed: the four bundled vehicles and the kit's own worktrees
+// mode are portable rows; `doc-research` is HOST-LOCAL — a per-host web grant the kit does not
+// bundle — and the host's own subagent lane is ASSUMED/manual, carrying no availability verdict at
+// all. Dependency-free, Node >= 22. No side effects on import; no CLI (the verb lives on dispatch).
+
+import { lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { STEP_CLASSES } from './dispatch-record.mjs';
+import { delegationThreadState } from './dispatch-store.mjs';
+import { AGENTS_DIR, FALLBACK_LENS_ADDITIONAL_ONLY } from './cheap-agents.mjs';
+import { detectBackends, wrapperCmdFor, READY } from './detect-backends.mjs';
+
+// The two sentences doc-parity binds into references/modes/dispatch.md. Stated ONCE, here, so the
+// mode doc can never drift into promising a gate this module does not own.
+export const ADVISOR_NO_GATE = 'the advice never gates a dispatch: which vehicle carries a sub-task stays orchestrator judgment, and a divergence from the advice is recorded as a note rather than refused';
+export const HARNESS_SUBAGENT_LANE = "the harness's own subagent lane is ASSUMED/manual — it is not kit-detectable, so it carries no availability verdict here and no acceptance weight";
+
+// The other lane, always printed: an unavailable vehicle is not a dead end, it is a degrade you record.
+export const ADVISOR_FALLBACK = 'solo (this orchestrator) — recorded as a degrade, never a silent skip';
+
+// The verb's honest posture, bound into the mode doc and interpolated into the tool's HELP so the
+// three surfaces state ONE thing. "Spawns nothing" was false of the VERB from the first line of this
+// lane — the store path is resolved through git unless AW_DELEGATION_STORE names it — so the claim
+// is stated where it is true (the module) and qualified where it is not (the verb).
+export const ADVISOR_PROBE_POSTURE = 'the advisor module itself writes nothing, spawns nothing and opens no second ledger door; the VERB may run read-only git probes — the delegation store path (unless AW_DELEGATION_STORE names it outright) and the repository top-level the cheap vehicles are anchored at — and it never runs a vehicle, a subscription CLI, or anything that writes';
+
+// The table's shape, stated ONCE. The header line, the alignment rule, the rendered rows and the
+// parser's arity + per-cell diagnosis all DERIVE from this: three separate statements of one column
+// order is exactly how a reordered header keeps a green gate over rows that no longer mean what
+// their columns say.
+export const ADVISOR_MATRIX_COLUMNS = Object.freeze([
+  Object.freeze({ key: 'stepClass', label: 'step class' }),
+  Object.freeze({ key: 'vehicle', label: 'vehicle' }),
+  Object.freeze({ key: 'availabilityNote', label: 'availability' }),
+  Object.freeze({ key: 'returns', label: 'returns' }),
+]);
+
+const matrixRow = (cells) => `| ${ADVISOR_MATRIX_COLUMNS.map(({ key }) => cells[key]).join(' | ')} |`;
+
+export const ADVISOR_MATRIX_HEADER = matrixRow(Object.fromEntries(ADVISOR_MATRIX_COLUMNS.map(({ key, label }) => [key, label])));
+export const ADVISOR_MATRIX_RULE = matrixRow(Object.fromEntries(ADVISOR_MATRIX_COLUMNS.map(({ key }) => [key, '---'])));
+
+// The execute backend is named once; its wrapper cmd is READ from the detector's role registry
+// rather than re-typed, so a renamed wrapper moves this row with it.
+const EXECUTE_BACKEND = 'codex-cli-bridge';
+const EXECUTE_ROLE = 'execute';
+
+const BUNDLED = 'bundled vehicle — present once placed in .claude/agents/';
+const HOST_LOCAL = 'HOST-LOCAL — a per-host web grant, never bundled with the kit';
+
+// ── the frozen row set: exactly one row per D9 step class ─────────────────────────────────────────
+// Totality is a TEST, not a comment: a class added to dispatch-record.mjs reddens the advisor suite
+// rather than printing nothing at the point of use.
+
+const row = (entry) => Object.freeze(entry);
+
+export const ADVISOR_ROWS = Object.freeze([
+  row({
+    stepClass: 'code',
+    vehicle: wrapperCmdFor(EXECUTE_BACKEND, EXECUTE_ROLE),
+    kind: 'backend',
+    backend: EXECUTE_BACKEND,
+    portable: true,
+    availabilityNote: 'execute backend — readiness read from the bridge install, never from a spawn',
+    returns: "a diff plus the wrapper's exec receipt",
+    why: 'a bounded code sub-task returns a diff you review + gate',
+  }),
+  row({
+    stepClass: 'extraction',
+    vehicle: 'mechanical-sweep',
+    kind: 'agent',
+    portable: true,
+    availabilityNote: BUNDLED,
+    returns: 'an extraction report you verify',
+    why: 'a mechanical multi-file sweep returns facts, on a read-only vehicle that can never shell out',
+  }),
+  row({
+    stepClass: 'triage',
+    vehicle: 'gate-triage',
+    kind: 'agent',
+    portable: true,
+    availabilityNote: BUNDLED,
+    returns: 'a structured gate-failure classification',
+    why: "a failing gate's output returns classified, never fixed — the fix stays yours",
+  }),
+  row({
+    stepClass: 'draft',
+    vehicle: 'changelog-skeleton',
+    kind: 'agent',
+    portable: true,
+    availabilityNote: BUNDLED,
+    returns: 'a factual skeleton',
+    why: 'the factual bones come back cheap; the lead and the final text stay yours',
+  }),
+  row({
+    stepClass: 'research',
+    vehicle: 'doc-research',
+    kind: 'agent',
+    portable: false,
+    availabilityNote: HOST_LOCAL,
+    returns: 'cited findings',
+    why: 'an external documentation question returns cited findings, on the one vehicle granted web access',
+  }),
+  row({
+    stepClass: 'review-opinion',
+    vehicle: 'review-lens',
+    kind: 'agent',
+    portable: true,
+    availabilityNote: BUNDLED,
+    returns: 'one additional review opinion',
+    why: FALLBACK_LENS_ADDITIONAL_ONLY,
+  }),
+  row({
+    stepClass: 'worktree-stream',
+    vehicle: 'worktrees',
+    kind: 'kit',
+    portable: true,
+    availabilityNote: 'ships with the kit — available wherever the kit is deployed',
+    returns: 'a prepared satellite diff plus its handoff',
+    why: 'a parallel feature stream runs in its own worktree and returns a prepared diff plus its handoff',
+  }),
+]);
+
+export const advisorRow = (stepClass) => ADVISOR_ROWS.find((r) => r.stepClass === stepClass);
+
+// ── host capability, resolved by filesystem facts only (D2) ───────────────────────────────────────
+
+// The agent lane is FOUR-valued, and the two unknowns are kept apart because they are two different
+// ignorances. `.claude/agents/` is a repository-ROOT surface, so a probe run from anywhere else
+// proves nothing — an absent file under an UNANCHORED cwd is not evidence the vehicle is unplaced,
+// and a PRESENT one there is not evidence it is the repository's vehicle either, since a nested
+// shadow copy reads identically. Separately, an anchored probe can simply fail to answer (any errno
+// but ENOENT — EACCES is not absence), and saying "the repository root was not resolved" there would
+// be a false statement about a root that WAS resolved. Both render as `unknown`; each names its own
+// cause.
+export const AGENT_PRESENT = 'present';
+export const AGENT_MISSING = 'missing';
+export const AGENT_UNANCHORED = 'unanchored';
+export const AGENT_PROBE_ERROR = 'probe-error';
+
+// The states that are NOT a verdict — exported so a consumer can ask the question without re-deriving
+// which values happen to be ignorance today.
+export const AGENT_UNKNOWN_STATES = Object.freeze([AGENT_UNANCHORED, AGENT_PROBE_ERROR]);
+
+// No-follow by construction: the placement writer refuses to write through a symlink, so a symlinked
+// entry is not a vehicle this kit placed and is not counted as one.
+const probeAgentFile = (cwd, name) => {
+  try {
+    return lstatSync(join(cwd, AGENTS_DIR, `${name}.md`)).isFile() ? AGENT_PRESENT : AGENT_MISSING;
+  } catch (err) {
+    return err?.code === 'ENOENT' ? AGENT_MISSING : AGENT_PROBE_ERROR;
+  }
+};
+
+// advisorDeps({cwd, anchored, detect}) → the injected host half. `anchored` states whether `cwd` IS
+// the repository top-level; when it is not, the agent lane answers `unanchored` rather than guessing.
+// Both probes are pure reads; `detect` is the detector's own no-spawn pass, resolved ONCE per call so
+// seven rows cost one detection.
+export const advisorDeps = ({ cwd = process.cwd(), anchored = true, detect = detectBackends } = {}) => {
+  let detected = null;
+  return {
+    agentState: (name) => (anchored ? probeAgentFile(cwd, name) : AGENT_UNANCHORED),
+    backendReadiness: (backend) => {
+      detected ??= detect();
+      return detected.find((b) => b.name === backend)?.readiness ?? 'not-installed';
+    },
+  };
+};
+
+const AGENT_LABELS = Object.freeze({
+  portable: Object.freeze({
+    [AGENT_PRESENT]: 'ready',
+    [AGENT_MISSING]: 'unavailable — not placed; run /agent-workflow-kit agents',
+    [AGENT_UNANCHORED]: 'unknown — the repository root was not resolved, so .claude/agents/ was never located',
+    [AGENT_PROBE_ERROR]: 'unknown — the repository root resolved, but .claude/agents/ could not be probed there',
+  }),
+  'host-local': Object.freeze({
+    [AGENT_PRESENT]: 'ready — host-local',
+    [AGENT_MISSING]: 'unavailable — host-local, not bundled',
+    [AGENT_UNANCHORED]: 'unknown — host-local, and the repository root was not resolved',
+    [AGENT_PROBE_ERROR]: 'unknown — host-local, and .claude/agents/ could not be probed',
+  }),
+});
+
+// The label for a state this module does not recognize. It claims NOTHING — not that the root
+// resolved, not that it did not. Reusing the probe-error wording here would assert "the repository
+// root resolved" about a value that establishes no such thing, which is the same class of false
+// statement the two named unknowns exist to avoid, one level down.
+export const AGENT_UNRECOGNIZED_LABEL = 'unknown — the availability probe returned an unrecognized state, so nothing about this vehicle is established';
+
+export const availabilityOf = (entry, deps) => {
+  if (entry.kind === 'kit') return { ready: true, label: 'ready — ships with the kit' };
+  if (entry.kind === 'backend') {
+    const readiness = deps.backendReadiness(entry.backend);
+    return readiness === READY
+      ? { ready: true, label: 'ready' }
+      : { ready: false, label: `unavailable — ${readiness}` };
+  }
+  const state = deps.agentState(entry.vehicle);
+  const labels = AGENT_LABELS[entry.portable ? 'portable' : 'host-local'];
+  return { ready: state === AGENT_PRESENT, label: labels[state] ?? AGENT_UNRECOGNIZED_LABEL };
+};
+
+// ── the recorded history: the store's OWN thread walk, over a CLOSED state taxonomy (D4) ──────────
+
+const THREAD_KINDS = ['dispatch', 'return', 'fold', 'degrade'];
+
+// The four states are exactly what delegationThreadState distinguishes. `open` is printed SEPARATELY
+// and is never among the closed threads: a live thread is not evidence about a finished one.
+const threadStateName = (state) => {
+  if (state.closure?.kind === 'fold') return 'folded';
+  if (state.closure?.kind === 'degrade') return 'degrade-closed';
+  return state.terminal ? 'failure-terminal' : 'open';
+};
+
+export const countThreadStates = (records, stepClass) => {
+  const counts = { folded: 0, 'failure-terminal': 0, 'degrade-closed': 0, open: 0 };
+  const seen = new Set();
+  for (const record of records) {
+    if (!THREAD_KINDS.includes(record?.kind)) continue;
+    const { nonce } = record;
+    // A PRE-DISPATCH degrade carries nonce null and belongs to no thread at all.
+    if (typeof nonce !== 'string' || nonce === '' || seen.has(nonce)) continue;
+    seen.add(nonce);
+    const state = delegationThreadState(records, nonce);
+    if (state.dispatch === null || state.dispatch.stepClass !== stepClass) continue;
+    counts[threadStateName(state)] += 1;
+  }
+  return counts;
+};
+
+const CLOSED_ORDER = ['folded', 'failure-terminal', 'degrade-closed'];
+
+export const historyLine = (stepClass, ledger) => {
+  if (ledger?.ok !== true) {
+    return `history: unavailable — ${ledger?.reason ?? 'the ledger read reported no outcome at all'}`;
+  }
+  const counts = countThreadStates(ledger.records ?? [], stepClass);
+  const closed = CLOSED_ORDER.reduce((sum, key) => sum + counts[key], 0);
+  if (closed === 0 && counts.open === 0) return 'history: no recorded history';
+  const parts = CLOSED_ORDER.filter((key) => counts[key] > 0).map((key) => `${counts[key]} ${key}`);
+  const closedClause = closed === 0
+    ? '0 closed threads'
+    : `${closed} closed thread${closed === 1 ? '' : 's'} — ${parts.join(', ')}`;
+  return `history: ${closedClause} · ${counts.open} open`;
+};
+
+// ── rendering ─────────────────────────────────────────────────────────────────────────────────────
+
+// renderAdvisorBlock({stepClass, ledger, deps}) → the five-line block, or null for an unknown class.
+// The refusal of an unknown class belongs to the CALLER (a usage exit naming the closed set), not
+// here: this module answers a question and never decides an exit code.
+export const renderAdvisorBlock = ({ stepClass, ledger, deps }) => {
+  const entry = advisorRow(stepClass);
+  if (entry === undefined) return null;
+  const availability = availabilityOf(entry, deps);
+  return [
+    `dispatch advisor — step class: ${stepClass}`,
+    `  advice: ${entry.vehicle} (${availability.label}) — ${entry.why}`,
+    `  fallback: ${ADVISOR_FALLBACK}`,
+    `  ${historyLine(stepClass, ledger)}`,
+    `  note: ${ADVISOR_NO_GATE}`,
+  ].join('\n');
+};
+
+// renderSelectionNote({stepClass, vehicle}) → the divergence NOTE, or null when the contract's
+// SELECTED vehicle is the advised one. `vehicle.requested` is named only when it differs from
+// `selected` — where the pair agrees there is nothing to distinguish, and printing it twice would
+// read as a second fact.
+export const renderSelectionNote = ({ stepClass, vehicle }) => {
+  const entry = advisorRow(stepClass);
+  if (entry === undefined || vehicle == null) return null;
+  const { requested, selected } = vehicle;
+  if (selected === entry.vehicle) return null;
+  const requestedClause = requested !== selected ? ` (requested "${requested}")` : '';
+  return `  divergence: the contract selected "${selected}"${requestedClause}; the advisor advises "${entry.vehicle}" — a NOTE, never a refusal`;
+};
+
+// The harness lane, as a row rather than as a rendered string: it joins the table through the same
+// column order as every other row, and it is NOT a step class — no availability verdict, no
+// acceptance weight, and it never enters the registry the advice is read from.
+export const HARNESS_LANE_ROW = Object.freeze({
+  stepClass: 'harness subagent',
+  vehicle: "the host's own",
+  availabilityNote: HARNESS_SUBAGENT_LANE,
+  returns: 'not measured',
+});
+
+// renderAdvisorMatrix() → the vehicle-routing matrix the mode doc carries, WHOLE: header, alignment
+// rule, one row per registry row in registry order, and the lane. The doc's copy is held to this
+// exact block by doc-parity's structure check, so a deleted rule row, a rewritten lane and an extra
+// row are all caught by the same comparison that catches a drifted cell.
+export const renderAdvisorMatrix = () => [
+  ADVISOR_MATRIX_HEADER,
+  ADVISOR_MATRIX_RULE,
+  ...ADVISOR_ROWS.map((entry) => matrixRow({ ...entry, stepClass: `\`${entry.stepClass}\`` })),
+  matrixRow(HARNESS_LANE_ROW),
+].join('\n');
+
+// The closed class set, rendered for the caller's usage refusal — one source with the record
+// vocabulary, so a class added there is offered here without a second edit.
+export const ADVISOR_STEP_CLASSES = STEP_CLASSES;