@sabaiway/agent-workflow-kit 5.9.0 → 5.11.0

package/tools/dispatch.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 // dispatch.mjs — the delegation ENGINE (delegation Plan 1, Phase 3; the writer verbs are Plan 2,
 // Phase 2 and the waiter Plan 2, Phase 4): the ONE human-facing surface over the record vocabulary
-// (dispatch-record.mjs) and the ledger (dispatch-store.mjs). Nine verbs:
+// (dispatch-record.mjs) and the ledger (dispatch-store.mjs). Eleven verbs:
 //
-//   check <dispatch-file>  the D8 sub-task contract header, FORM-only, exit 0/1
+//   check <dispatch-file>  the D8 sub-task contract header, FORM-only, exit 0/1 (+ the advisory footer)
+//   advise --step-class    which vehicle carries this step class on THIS host — advice, never a gate
 //   register               the wave's PRE-REGISTRATION record (classes, pairing key, thresholds)
 //   observe                one OBSERVATION record (the solo baseline / a self-reported datum)
 //   open                   the DISPATCH record — every mint-time field COPIED from the header
@@ -11,6 +12,7 @@
 //   return                 the RETURN record — the wrapper's exec receipt ABSORBED through this door
 //   fold                   the FOLD record — the integration re-confirmation
 //   degrade                the DEGRADE record — the recorded no-fold closure
+//   handoff-return         the worktree-stream return rung — deliver, prove, then count
 //   aggregate [--wave]     the L0 deterministic report over ONE wave
 //
 // Why an engine at all: the funded metric — how much leverage a delegated sub-task actually buys —
@@ -58,31 +60,39 @@
 //
 // Writer: appends to the delegation ledger through the store's lock-serialized append (the store's
 // preflight is the single legality door — this module adds NO second validator). Never commits,
-// never runs a subscription CLI, spawns nothing but git READS. Dependency-free, Node >= 22. No side
-// effects on import (the isDirectRun idiom).
+// never runs a subscription CLI, spawns nothing but git READS — with ONE stated exception:
+// `handoff-return` attests MAIN's index with `git write-tree`, which may write a tree OBJECT into
+// the odb and moves no ref (the same probe `land --prepare` itself uses). Dependency-free,
+// Node >= 22. No side effects on import (the isDirectRun idiom).
 
-import { readFileSync, openSync, closeSync, realpathSync, readlinkSync, constants as fsConstants } from 'node:fs';
-import { resolve, isAbsolute, sep, dirname, basename, join } from 'node:path';
+import { readFileSync, realpathSync, readlinkSync } from 'node:fs';
+import { resolve, isAbsolute, dirname, basename, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHash } from 'node:crypto';
 import {
   DELEGATION_SCHEMA_VERSION, STEP_CLASSES, OBSERVATION_PROVENANCE, RETURN_OUTCOMES,
   SESSION_ID_NULLABLE_OUTCOMES, checkDispatchContractForm, checkDispatchMintConsistency,
   contractDigest, canonicalDelegationDigest, computeNumerator, evaluateMetricEligibility,
-  evaluateObservationEligibility,
 } from './dispatch-record.mjs';
 import {
   appendDelegationRecord, readDelegationStore, resolveDelegationStorePath, delegationThreadState,
   auditDelegationStoreSemantics, uncommittedStateFingerprint, DELEGATION_STORE_BASENAME,
 } from './dispatch-store.mjs';
+import {
+  renderAdvisorBlock, renderSelectionNote, advisorDeps, advisorRow, ADVISOR_STEP_CLASSES,
+  ADVISOR_PROBE_POSTURE,
+} from './dispatch-advisor.mjs';
 import { execReceiptBasename, execReportBasename, parseExecReceipt } from './exec-receipt.mjs';
 import {
   enumerateReturnedObjects, computeReturnedDiff, assembleIntegrationBundle,
 } from './exec-producer.mjs';
 import { gitBuf, isTreeClean } from './core-evidence.mjs';
-import { lstatNoFollowRead, describeNonRegular, readRegularFileNoFollow, readFileBytesNoFollow } from './fs-read-nofollow.mjs';
+import { lstatNoFollowRead, readRegularFileNoFollow, readFileBytesNoFollow } from './fs-read-nofollow.mjs';
 import { gitLine } from './flow-store-read.mjs';
-import { lexicalRepoRelative } from './repo-lex.mjs';
+import {
+  resolveRepoRoot, measureScope, ratio, formatRatio, buildObservationRecord,
+} from './observation-builder.mjs';
+import { handoffReturn, HANDOFF_SLUG_RE } from './worktree-handoff-return.mjs';
 
 const usageFail = (message) => Object.assign(new Error(message), { exitCode: 2 });
 
@@ -195,11 +205,6 @@ const OBSERVE_REPEATABLE = new Set(['--scope']);
 // would record a contract the computation does not follow — refused at both ends.
 export const IMPLEMENTED_PAIRING_KEYS = Object.freeze(['stepClass']);
 
-// The solo baseline counts each scope object's POST-IMAGE — the bytes on disk after the construction
-// — which is exactly the `new` numerator rule (D6). No exec diff kind enumerates ranges, so a solo
-// observation can never claim a partial object.
-const SOLO_COMPONENT_KIND = 'new';
-
 // Acceptance aggregates the git-provable domain only (D6/R2).
 const ACCEPTANCE_PROVENANCE = 'wrapper-git';
 
@@ -285,9 +290,65 @@ const asNumber = (flag, raw) => {
 
 const refusal = (verb, reason) => ({ code: 1, stdout: '', stderr: `dispatch ${verb}: ${reason}` });
 
+// ── advise: the vehicle-routing advisory, at its two points of use ────────────────────────────────
+// It refuses nothing and decides nothing (D1). The ledger is read through the SAME single door every
+// deriving verb uses, and its OUTCOME is handed to the advisor — an unreadable store degrades the
+// history line rather than suppressing the advice or moving an exit code.
+
+export const ADVISE_FLAG_FIELDS = Object.freeze({ '--step-class': 'stepClass' });
+
+// The advisory probe may never own an exit code, so neither of its two throwing inputs escapes it.
+// The store path resolution REFUSES a relative override and one ending in a separator by throwing
+// (dispatch-store.mjs:61-71), and the top-level resolution spawns git: an exception from either would
+// delete a form-valid `check`'s verdict line and turn its exit 0 into a refusal — which is exactly
+// the gate D1 says this surface never becomes. Caught here, the store's own words still travel, as
+// the history line, which is already where an unreadable ledger speaks.
+const ledgerOutcome = (cwd, env) => {
+  try {
+    return readLegalLedger(cwd, env);
+  } catch (err) {
+    return { ok: false, reason: err?.message ?? String(err) };
+  }
+};
+
+// The cheap vehicles live at the REPOSITORY top-level (.claude/agents/), never at the caller's cwd —
+// a run from a subdirectory would otherwise report a placed vehicle as absent. Only the VEHICLE probe
+// is re-anchored: the ledger keeps the original cwd, because its own resolution is git-common-dir
+// based and already answers the same from anywhere inside the tree.
+//
+// The result is a PAIR, not a path. `resolveRepoRoot` answers null both for "not a work tree" and for
+// "the git probe did not answer", and a throw is a third way to learn nothing — collapsing all three
+// into the caller's cwd made an unlocatable vehicle print as "not placed", which is a fact this tool
+// does not have. Unanchored, the agent lane says `unknown` instead.
+// The resolver is a SEAM (ctx.repoRoot) rather than a hard call, because "the probe threw" is a lane
+// with its own printed answer and a lane nothing can reach by arranging a directory: the throw comes
+// from a git spawn or a realpath the caller cannot make fail on demand. A seam makes the branch
+// exercisable in-process, which is the only place coverage can see it (D14).
+const vehicleAnchor = (cwd, repoRoot) => {
+  try {
+    const root = repoRoot(cwd);
+    return root === null ? { cwd, anchored: false } : { cwd: root, anchored: true };
+  } catch {
+    return { cwd, anchored: false };
+  }
+};
+
+const advisoryBlock = ({ cwd, env, stepClass, repoRoot }) =>
+  renderAdvisorBlock({ stepClass, ledger: ledgerOutcome(cwd, env), deps: advisorDeps(vehicleAnchor(cwd, repoRoot)) });
+
+const runAdvise = ({ argv, baseCwd, env, repoRoot }) => {
+  const { values, operands, cwd } = scan(argv, ADVISE_FLAG_FIELDS, baseCwd);
+  refuseOperands('advise', operands);
+  const stepClass = need(values, '--step-class');
+  if (advisorRow(stepClass) === undefined) {
+    throw usageFail(`--step-class must be one of the D9 step classes ${ADVISOR_STEP_CLASSES.join(' | ')} (got "${stepClass}")`);
+  }
+  return { code: 0, stdout: advisoryBlock({ cwd, env, stepClass, repoRoot }), stderr: '' };
+};
+
 // ── check: the D8 contract header, FORM only ──────────────────────────────────────────────────────
 
-const runCheck = ({ argv, baseCwd }) => {
+const runCheck = ({ argv, baseCwd, env, repoRoot }) => {
   const { operands, cwd } = scan(argv, {}, baseCwd);
   if (operands.length > 1) throw usageFail(`unknown argument: ${operands[1]}`);
   const file = operands[0];
@@ -302,9 +363,17 @@ const runCheck = ({ argv, baseCwd }) => {
   const form = checkDispatchContractForm(text);
   if (!form.ok) return { code: 1, stdout: `dispatch check: FORM VIOLATION — ${form.reason}`, stderr: '' };
   const c = form.contract;
+  // The advisory footer prints ONLY here, under a form-valid contract, so it can never mask a
+  // refusal: the exit code and the FIRST line above are identical whatever the advisor concludes.
+  const advisory = [advisoryBlock({ cwd, env, stepClass: c.stepClass, repoRoot }), renderSelectionNote(c)]
+    .filter((line) => line !== null && line !== undefined);
   return {
     code: 0,
-    stdout: `dispatch check: FORM OK — nonce "${c.nonce}", step class "${c.stepClass}", vehicle ${c.vehicle.requested} → ${c.vehicle.selected}, deadline ${c.deadlineS}s, retry ${c.retry.index}/${c.retry.cap}\n  (${DISPATCH_CONTRACT})`,
+    stdout: [
+      `dispatch check: FORM OK — nonce "${c.nonce}", step class "${c.stepClass}", vehicle ${c.vehicle.requested} → ${c.vehicle.selected}, deadline ${c.deadlineS}s, retry ${c.retry.index}/${c.retry.cap}`,
+      `  (${DISPATCH_CONTRACT})`,
+      ...advisory,
+    ].join('\n'),
     stderr: '',
   };
 };
@@ -342,84 +411,13 @@ const runRegister = ({ baseCwd, env, argv, now }) => {
 };
 
 // ── observe: one hand-recorded observation ────────────────────────────────────────────────────────
-
-const ratio = (value) => value.toFixed(3);
-
-// L is printed ONLY where the metric is eligible: an ineligible metric has a NAMED reason and no
-// ratio at all, and printing a number beside the name is how a silent zero gets read as a measurement.
-const formatRatio = (metric) => (metric.eligible
-  ? `L = ${ratio(metric.numeratorBytes / metric.denominatorBytes)} (${metric.numeratorBytes} B / ${metric.denominatorBytes} B)`
-  : `L = n/a — INELIGIBLE (${metric.ineligibleReason})`);
+// The scope measurement and the record construction live in observation-builder.mjs, so this verb
+// and the handoff-return rung build the IDENTICAL record through ONE path (the rung cannot import
+// this module back — dispatch.mjs imports the rung for its verb, and the tools graph is pinned
+// acyclic).
 
 const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
 
-// The scope's anchor is the git TOP-LEVEL, never the caller's cwd: a recorded scope must name the
-// same objects whoever runs the tool from wherever. `null` outside a work tree — a repo-relative
-// domain with no repository has nothing to be relative TO, and falling back to cwd would be a
-// second, incompatible semantics for the same field.
-const resolveRepoRoot = (cwd) => {
-  if (gitLine(['rev-parse', '--is-inside-work-tree'], cwd) !== 'true') return null;
-  const top = gitLine(['rev-parse', '--show-toplevel'], cwd);
-  return top === null ? null : realpathSync(top);
-};
-
-// The read is no-follow on the LEAF (a symlinked leaf is already refused by name above; O_NOFOLLOW
-// makes a swap between the classification and the read fail loudly rather than counting another
-// object's bytes). Honest limit: classify-then-read is not race-free, and it is not meant to be —
-// the scope is the orchestrator's OWN work tree and the result is a MAGNITUDE, never a store
-// identity, so a pathname race costs a wrong byte count, not a forged record.
-const readObjectBytes = (path) => {
-  const fd = openSync(path, (fsConstants.O_RDONLY ?? 0) | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0));
-  try {
-    return readFileSync(fd);
-  } finally {
-    closeSync(fd);
-  }
-};
-
-// One scope object → one numerator entry. Refuses by NAME on anything it cannot count honestly: a
-// path escaping the repo LEXICALLY, an absent path, a non-regular path (a symlinked leaf included —
-// following one would count another object's bytes under this name), and a path whose REAL location
-// is outside the repository. The last one is the case the lexical rule alone cannot see: it rejects
-// `../x` while accepting `link/x`, where `link` is an ancestor symlink pointing out of the tree.
-// The identity is the CANONICAL repo-relative path taken from the verified real path — not a content
-// hash. The solo domain has no rename lineage for a content id to protect, and a content id would
-// let one object read between two measurements look like TWO objects instead of refusing as the
-// producer contradiction it is ("one identity, one size"). Two equal-byte files at different paths
-// are two objects and count twice; one path reached twice (a second listing, an in-repo ancestor
-// symlink) is one object and counts once.
-const measureObject = (root, rel) => {
-  const lexical = lexicalRepoRelative(rel);
-  if (!lexical.ok) return { ok: false, reason: `scope path "${rel}": ${lexical.reason}` };
-  const path = resolve(root, rel);
-  const stat = lstatNoFollowRead(path);
-  if (stat === null) return { ok: false, reason: `scope path "${rel}" does not exist — an observation counts objects that are actually there (fail closed)` };
-  if (!stat.isFile()) return { ok: false, reason: `scope path "${rel}" is a ${describeNonRegular(stat)}, not a regular file — the scope names repository objects (fail closed)` };
-  const real = realpathSync(path);
-  if (!real.startsWith(`${root}${sep}`)) {
-    return { ok: false, reason: `scope path "${rel}" resolves to ${real}, which leaves the repository at ${root} — an ancestor symlink is not a way out of the scope domain (fail closed)` };
-  }
-  const canonical = real.slice(root.length + 1);
-  const bytes = readObjectBytes(path);
-  return { ok: true, entry: { kind: SOLO_COMPONENT_KIND, path: canonical, objectId: canonical, postImageBytes: bytes.length } };
-};
-
-// One repo-relative path per `--scope` occurrence, in the order given. The measured CANONICAL paths
-// become the record's `scope` as a canonical JSON array, so what was measured and what is written
-// down are the same statement — and a path carrying a space says so unambiguously.
-const measureScope = (root, paths) => {
-  const entries = [];
-  for (const rel of paths) {
-    const measured = measureObject(root, rel);
-    if (!measured.ok) return measured;
-    entries.push(measured.entry);
-  }
-  const numerator = computeNumerator(entries);
-  return numerator.ok
-    ? { ...numerator, scope: JSON.stringify(entries.map((e) => e.path)) }
-    : { ok: false, reason: numerator.reason };
-};
-
 const runObserve = ({ baseCwd, env, argv, now }) => {
   const { values, operands, cwd } = scan(argv, OBSERVE_FLAG_FIELDS, baseCwd, { repeatable: OBSERVE_REPEATABLE });
   refuseOperands('observe', operands);
@@ -444,25 +442,16 @@ const runObserve = ({ baseCwd, env, argv, now }) => {
   const denominatorBytes = solo
     ? measured.numeratorBytes
     : asInteger('--denominator-bytes', need(values, '--denominator-bytes'));
-  const eligibility = evaluateObservationEligibility({ numeratorBytes: measured.numeratorBytes, denominatorBytes });
-  const record = {
-    schema: DELEGATION_SCHEMA_VERSION,
-    kind: 'observation',
+  const record = buildObservationRecord({
     waveId: need(values, '--wave'),
     stepClass: need(values, '--step-class'),
-    scope: measured.scope,
-    metric: {
-      numeratorBytes: measured.numeratorBytes,
-      denominatorBytes,
-      components: measured.components,
-      provenance,
-      eligible: eligibility.eligible,
-      ineligibleReason: eligibility.ineligibleReason,
-    },
+    measured,
+    provenance,
+    denominatorBytes,
     planId: need(values, '--plan'),
     phase: asInteger('--phase', need(values, '--phase')),
     timestamp: now(),
-  };
+  });
   const { writtenPath } = appendDelegationRecord({ cwd, record, env });
   // DISTINCT objects, not scope entries: the numerator dedups on the canonical path, so counting
   // entries would report two objects where one was counted — the echo must agree with the number.
@@ -1348,6 +1337,40 @@ const runDegrade = ({ baseCwd, env, argv, now }) => {
   };
 };
 
+// ── handoff-return: the worktree-stream return rung ───────────────────────────────────────────────
+// The rung itself lives in worktree-handoff-return.mjs (it locates the satellite through the shared
+// locator leaf, so the worktrees tool never enters this CLI's import closure); this wrapper owns
+// only the flag surface, exactly like every other verb.
+
+export const HANDOFF_RETURN_FLAG_FIELDS = Object.freeze({
+  '--wave': 'waveId',
+  '--plan': 'planId',
+  '--phase': 'phase',
+});
+export const HANDOFF_RETURN_INPUT_FLAGS = Object.freeze({
+  '--slug': 'the satellite slug the handoff identity is resolved from',
+});
+
+const runHandoffReturn = ({ baseCwd, env, argv, now }) => {
+  const { values, operands, cwd } = scan(argv, { ...HANDOFF_RETURN_FLAG_FIELDS, ...HANDOFF_RETURN_INPUT_FLAGS }, baseCwd);
+  refuseOperands('handoff-return', operands);
+  const slug = need(values, '--slug');
+  // Refused as USAGE before any probe: the locator's own refusals interpolate the slug into a
+  // terminal message, and the worktrees grammar is what keeps that echo safe.
+  if (!HANDOFF_SLUG_RE.test(slug)) {
+    throw usageFail(`--slug must match the worktrees slug grammar (lowercase letters, digits, hyphens, max 64 chars, letter/digit first; got ${JSON.stringify(slug)})`);
+  }
+  return handoffReturn({
+    cwd,
+    env,
+    now,
+    slug,
+    waveId: need(values, '--wave'),
+    planId: need(values, '--plan'),
+    phase: asInteger('--phase', need(values, '--phase')),
+  });
+};
+
 // ── aggregate: the L0 report over ONE wave ────────────────────────────────────────────────────────
 
 const WAVE_BEARING_KINDS = ['pre-registration', 'dispatch', 'observation', 'degrade'];
@@ -1542,6 +1565,7 @@ record, the arrival waiter, and the L0 acceptance report.
 
 Usage:
   node dispatch.mjs check <dispatch-file> [--cwd <dir>]
+  node dispatch.mjs advise --step-class <c> [--cwd <dir>]
   node dispatch.mjs register --wave <id> --step-classes <c[,c...]>
                              --pairing-key ${IMPLEMENTED_PAIRING_KEYS.join('|')}
                              --min-per-class <n> --mean-l-threshold <x>
@@ -1558,10 +1582,25 @@ Usage:
   node dispatch.mjs fold --nonce <n> --verdict <text> [--cwd <dir>]
   node dispatch.mjs degrade --wave <id> --step-class <c> --rationale <text>
                             [--nonce <n>] [--cwd <dir>]
+  node dispatch.mjs handoff-return --slug <s> --wave <id> --plan <id> --phase <n> [--cwd <dir>]
   node dispatch.mjs aggregate [--wave <id>] [--cwd <dir>]
 
 check reads the ONE \`\`\`aw-dispatch-contract fenced block in the dispatch file and validates its
-FORM: ${DISPATCH_CONTRACT}. Exit 0 form-valid; 1 names the FIRST violated field.
+FORM: ${DISPATCH_CONTRACT}. Exit 0 form-valid; 1 names the FIRST violated field. On a form-VALID
+contract it then prints the advisory block below, plus a divergence NOTE when the contract's SELECTED
+vehicle is not the advised one — the footer prints only over a valid form, so it can never mask a
+refusal, and the exit code and the FIRST line never move with it.
+
+advise answers "which vehicle carries this step class on THIS host, and what has the ledger recorded
+for it" — and DECIDES nothing: it refuses no dispatch and gates no verb. Posture: ${ADVISOR_PROBE_POSTURE}.
+Host capability is read from the filesystem (the execute backend from the bridge install, the cheap
+vehicles from the presence of .claude/agents/<name>.md at the REPOSITORY top-level — where that root
+is not resolved the lane answers "unknown" rather than claiming a vehicle is unplaced);
+doc-research is HOST-LOCAL and never claimed portable, and the
+harness's own subagent lane carries no availability verdict at all. The recorded history is the
+ledger's own thread walk over the four states folded | failure-terminal | degrade-closed | open, with
+open counted SEPARATELY; an absent ledger prints "no recorded history" and an unreadable one prints
+the store's own words while the advice still prints. Exit 0 for every legal step class; 2 on usage.
 
 register appends the wave's PRE-REGISTRATION record (immutable per wave: a second one refuses).
 observe appends ONE observation — provenance ${OBSERVATION_PROVENANCE.join(' or ')} only, since
@@ -1653,6 +1692,24 @@ degrade appends the recorded no-fold closure, threaded (with --nonce) or PRE-DIS
 pre-dispatch form opens no nonce thread, so aggregate REFUSES the whole wave by name once one is
 recorded — stated here because it is a live cost of writing that record.
 
+handoff-return is the worktree-stream return rung: run FROM MAIN after land --prepare, it locates
+the satellite through the handoff identity, DELIVERS every user-owned fragment of the handoff byte
+verbatim (with its boundaries and byte lengths, naming the MAIN-owned destinations), requires BOTH
+prepared-tree and prepared-head from the record and re-attests them against MAIN's staged write-tree
+and HEAD (a record with no prepared-head was written by an earlier kit — re-run land --prepare), and
+appends ONE self-reported worktree-stream observation (numerator: the prepared change set's blob
+bytes, read from the ATTESTED tree itself via git cat-file — never from disk, which an unstaged
+edit after the prepare moves silently; denominator: the handoff byte count) ONLY when the prepared
+change set lies wholly inside the observation domain, re-checking the staged write-tree and HEAD
+once more immediately before EITHER answer (the pre-append idiom: it narrows the race window rather
+than closing it). A deletion, a rename's absent old side, a symlink, a submodule, a mode-only
+change, a path whose name is not valid UTF-8, and every other unrepresentable form end instead with
+"observation: NOT RECORDED — <form> at <path> is outside the observation domain" at exit 0,
+delivery and proof still printed — no partial scope is ever recorded. The handoff digest and the two OIDs are the rung's printed PROOF,
+not ledger fields (the closed observation key set carries no artifact digest — an accepted
+limitation). The fold stays orchestrator judgment, and a fold landed after the gates leaves them
+stale: the printed next-step order says so.
+
 aggregate reports ONE wave: the registered thresholds, every observation (context, never acceptance),
 and per registered step class the delegated threads with the D7 inclusion table applied — a folded
 success with an eligible wrapper-git metric contributes its L; a folded success whose metric is
@@ -1687,7 +1744,9 @@ against the payload, not claimed away here. A receipt is forgeable exactly like
 and D10 stands as a BAR, not a mechanism — at most one in-tree exec dispatch at a time, and nothing
 refuses a second.
 
-Never commits, never runs a subscription CLI, spawns nothing but git READS. Exit codes: 0 success;
+Never commits, never runs a subscription CLI, spawns nothing but git READS — except handoff-return,
+which attests MAIN's index with git write-tree: that may write a tree OBJECT into the odb and moves
+no ref (the same probe land --prepare itself uses). Exit codes: 0 success;
 1 a refusal (store STOP verbatim, a form violation, an unreadable file, a supervision question); 2
 usage; ${AWAIT_UNANSWERED_STATUS} an await that ended with no terminal receipt (the absolute deadline or the --timeout
 bound) — its own status so a caller that BRANCHES on the code can tell it from a refusal; a caller
@@ -1696,6 +1755,10 @@ that discards failure wholesale discards this one too.`;
 export const main = (argv, ctx = {}) => {
   const env = ctx.env ?? process.env;
   const now = ctx.now ?? (() => new Date().toISOString());
+  // The ADVISORY lane's repository-root resolver, injectable for exactly one reason: the "the probe
+  // threw" branch cannot be reached by arranging a directory, and an unexercised branch in a lane
+  // whose whole claim is "it never owns an exit code" is the branch worth exercising.
+  const repoRoot = ctx.repoRoot ?? resolveRepoRoot;
   try {
     // Help is the FIRST argument or nothing: past the verb, `--help` is an ordinary operand or an
     // already-claimed flag value, so `check --help` reads a file by that name rather than turning a
@@ -1703,18 +1766,20 @@ export const main = (argv, ctx = {}) => {
     if (HELP_FLAGS.has(argv[0])) return { code: 0, stdout: HELP, stderr: '' };
     const [verb, ...rest] = argv;
     const baseCwd = ctx.cwd ?? process.cwd();
-    if (verb === 'check') return runCheck({ argv: rest, baseCwd });
+    if (verb === 'check') return runCheck({ argv: rest, baseCwd, env, repoRoot });
+    if (verb === 'advise') return runAdvise({ argv: rest, baseCwd, env, repoRoot });
     if (verb === 'register') return runRegister({ baseCwd, env, argv: rest, now });
     if (verb === 'observe') return runObserve({ baseCwd, env, argv: rest, now });
     if (verb === 'open') return runOpen({ baseCwd, env, argv: rest, now });
     if (verb === 'return') return runReturn({ baseCwd, env, argv: rest, now });
     if (verb === 'fold') return runFold({ baseCwd, env, argv: rest, now });
     if (verb === 'degrade') return runDegrade({ baseCwd, env, argv: rest, now });
+    if (verb === 'handoff-return') return runHandoffReturn({ baseCwd, env, argv: rest, now });
     if (verb === 'aggregate') return runAggregate({ baseCwd, env, argv: rest });
     if (verb === 'await') {
       throw usageFail('await is the one verb that WAITS, so it answers through mainAwait (the CLI routes it there) — main() returns the answer a verb has already computed, and a promise handed back here would read as a result object with no code at all');
     }
-    throw usageFail(`unknown verb: ${verb ?? '(none)'} — expected check | register | observe | open | await | return | fold | degrade | aggregate (see --help)`);
+    throw usageFail(`unknown verb: ${verb ?? '(none)'} — expected check | advise | register | observe | open | await | return | fold | degrade | handoff-return | aggregate (see --help)`);
   } catch (err) {
     return { code: err.exitCode ?? 1, stdout: '', stderr: `dispatch: ${err.message}` };
   }

package/tools/doc-parity.mjs

@@ -19,9 +19,7 @@
 // Read-only: never writes, never commits, never runs a subscription CLI, spawns nothing. Dependency-
 // free, Node >= 22. No side effects on import (the isDirectRun idiom).
 
-import { readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { pathToFileURL } from 'node:url';
 import { EXIT as DOCTOR_EXIT, STATUS as DOCTOR_STATUS, TRUSTED_DIRS as DOCTOR_TRUSTED_DIRS } from './autonomy-doctor.mjs';
 import {
   RECOMMENDATIONS_SECTION_HEADER,
@@ -39,6 +37,12 @@ import { PARITY } from './refresh-parity.mjs';
 import { HOST_HONORS_QUALIFIER } from './velocity-profile.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 one-writer BAR the satellite cold-start prompt states at both of its print sites — read from
+// the composer that emits it, not from the worktrees tool, so the lint keeps the leaf's own words.
+import { ONE_WRITER_BAR } from './worktree-prompt.mjs';
+// The after-the-fold order the handoff-return rung prints (D9) — bound from the rung that owns it,
+// so the Landing-flow doc can never drift from what the tool actually tells an operator to do.
+import { AFTER_FOLD_ORDER } from './worktree-handoff-return.mjs';
 // 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).
@@ -47,6 +51,14 @@ 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';
 import { DISPATCH_CONTRACT } from './dispatch.mjs';
+// The routing advisor's two bound sentences, plus the matrix STRUCTURE check that holds the mode
+// doc's routing table to the advisor's frozen registry cell for cell — a correspondence no per-row
+// token check could establish, since every token survives a reorder.
+import { ADVISOR_NO_GATE, HARNESS_SUBAGENT_LANE, ADVISOR_PROBE_POSTURE } from './dispatch-advisor.mjs';
+import {
+  ADVISOR_MATRIX_DOC, ADVISOR_MATRIX_BEGIN, ADVISOR_MATRIX_END,
+  parseAdvisorMatrix, checkMatrixStructure, readKitDoc,
+} from './advisor-matrix.mjs';
 // The coverage vocabulary leaf: a CLOSED value set the gates contract doc must enumerate.
 import { COVERAGE } from './coverage-state.mjs';
 // The canonical producer body: gates.md prints the whole command byte for byte, so the doc is a
@@ -58,8 +70,6 @@ import { COVERAGE_PRODUCER_BODY } from './coverage-producer.mjs';
 // implementation — and through it the orchestration writer — into its import graph.
 import { RELAYED_ENSURE_TOKENS, RELAYED_FAILURE_CAUSES } from './ensure-vocabulary.mjs';
 
-const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-
 const AUTONOMY_DOCTOR_DOC = 'references/modes/autonomy-doctor.md';
 const RECOMMENDATIONS_DOC = 'references/modes/recommendations.md';
 const UPGRADE_DOC = 'references/modes/upgrade.md';
@@ -71,7 +81,9 @@ 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';
 const GATES_DOC = 'references/modes/gates.md';
-const DISPATCH_DOC = 'references/modes/dispatch.md';
+// One literal for the dispatch mode doc: the structure leaf already names it as the file it anchors
+// its table in, and a second copy here is exactly the drift this lint exists to catch.
+const DISPATCH_DOC = ADVISOR_MATRIX_DOC;
 
 // 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 });
@@ -151,6 +163,11 @@ export const BINDINGS = Object.freeze([
   // prose-only bars a doc could silently drop, so all are pinned to the live strings the record
   // actually carries.
   valueBinding('queue-shared-rule', QUEUE_SHARED_RULE, QUEUE_SHARED_RULE, [WORKTREES_DOC]),
+  // D7, the same class: one writer per worktree is a BAR and nothing refuses a second writer. The
+  // prompt states it at every print site, so the mode doc must carry the exact words the satellite
+  // reads — a doc that softened it would promise a guard the tool does not have.
+  valueBinding('one-writer-bar', ONE_WRITER_BAR, ONE_WRITER_BAR, [WORKTREES_DOC]),
+  valueBinding('after-fold-order', AFTER_FOLD_ORDER, AFTER_FOLD_ORDER, [WORKTREES_DOC]),
   valueBinding('landing-from-main', LANDING_FROM_MAIN, LANDING_FROM_MAIN, [WORKTREES_DOC]),
   valueBinding('no-dependencies-posture', NO_DEPENDENCIES_POSTURE, NO_DEPENDENCIES_POSTURE, [WORKTREES_DOC]),
   // The cleanup-ownership contract (AD-069): the exact live sentence every ownership STOP emits —
@@ -185,6 +202,15 @@ export const BINDINGS = Object.freeze([
   // doc — a doc that softened either would promise a judgment the checker never makes, or a number
   // the aggregator refuses to compute.
   valueBinding('dispatch-contract', DISPATCH_CONTRACT, DISPATCH_CONTRACT, [DISPATCH_DOC]),
+  // The routing advisor's honesty pair (delegation Plan 3): what the advice is NOT (it never gates),
+  // and the one lane that carries no availability verdict at all. Both were prose bars a doc edit
+  // could soften into a promise the module does not make.
+  valueBinding('advisor-no-gate', ADVISOR_NO_GATE, ADVISOR_NO_GATE, [DISPATCH_DOC]),
+  valueBinding('harness-subagent-lane', HARNESS_SUBAGENT_LANE, HARNESS_SUBAGENT_LANE, [DISPATCH_DOC]),
+  // And the verb's honest PROBE posture: "spawns nothing" was true of the module and false of the
+  // verb, which resolves the store path and the vehicle anchor through git. Stated once, live, so
+  // the mode doc, the HELP and the module header can never drift into three different claims.
+  valueBinding('advisor-probe-posture', ADVISOR_PROBE_POSTURE, ADVISOR_PROBE_POSTURE, [DISPATCH_DOC]),
   // The runner's `coverage=` summary vocabulary (Decision 8): the gates contract doc enumerates the
   // CLOSED value set, so a renamed or added value fails here instead of leaving the doc describing
   // a vocabulary the runner no longer speaks. One binding per value — the set is small and closed.
@@ -215,22 +241,35 @@ export const checkBinding = (binding, readText) => {
   return { constant: binding.constant, token: binding.token, files, ok: files.every((f) => f.ok) };
 };
 
-const defaultReadText = (rel) => readFileSync(resolve(KIT_ROOT, rel), 'utf8');
+const defaultReadText = readKitDoc;
+
+// The matrix STRUCTURE check rides beside the bindings, from its own leaf: a binding proves a token
+// is somewhere in a file, while correspondence — one row per registry row, in order, every CELL
+// equal — is a different claim with its own parser and its own refusal vocabulary. Re-exported here
+// so the lint stays the ONE surface a caller reaches either check through.
+export { ADVISOR_MATRIX_DOC, ADVISOR_MATRIX_BEGIN, ADVISOR_MATRIX_END, parseAdvisorMatrix, checkMatrixStructure, readKitDoc };
 
 // checkParity(bindings, readText) → [ per-binding result ]. Default reads the real modes/*.md files
 // relative to the kit root.
 export const checkParity = (bindings = BINDINGS, readText = defaultReadText) => bindings.map((b) => checkBinding(b, readText));
 
 // ── rendering ───────────────────────────────────────────────────────────────────────
-const formatHuman = (results) => {
+const structureLine = (structure) =>
+  `  ${structure.ok ? '✓' : '✗'} ${structure.constant} → ${structure.files[0].rel}${structure.ok ? '' : ` — ${structure.files[0].reason}`}`;
+
+const formatHuman = (results, structure) => {
   const lines = ['doc-parity — code constants ⟷ references/modes/*.md contract (read-only, BUGFREE-3)'];
   for (const r of results) {
     for (const f of r.files) {
       lines.push(`  ${f.ok ? '✓' : '✗'} ${r.constant} → ${f.rel}${f.ok ? '' : ` — ${f.reason}`}`);
     }
   }
+  lines.push(structureLine(structure));
   const failed = results.flatMap((r) => r.files.filter((f) => !f.ok).map((f) => `${r.constant} @ ${f.rel}`));
-  lines.push(`  check: ${failed.length === 0 ? 'PASS' : 'FAIL'} — ${failed.length === 0 ? `${results.length} binding(s) consistent` : `${failed.length} drifted binding(s): ${failed.join('; ')}`}`);
+  // The summary verdict derives from BOTH halves. A PASS token computed from the bindings alone read
+  // as a green report while the structure check below it said FAIL — the one surface that lied.
+  const green = failed.length === 0 && structure.ok;
+  lines.push(`  check: ${green ? 'PASS' : 'FAIL'} — ${failed.length === 0 ? `${results.length} binding(s) consistent` : `${failed.length} drifted binding(s): ${failed.join('; ')}`}, structure ${structure.ok ? 'PASS' : 'FAIL'}`);
   return lines.join('\n');
 };
 
@@ -248,13 +287,25 @@ orientation contract (shared-queue rule, landing-from-main, no-dependencies inst
 worktrees cleanup-ownership rule, the worktrees include-identity rule, the worktrees
 resume-verify rule, the flow tolerate contract (the accepted flow schema version + the
 lagging-kit sentence, procedures.md), the receipt-deadline arrival contract, the dispatch engine's
-FORM-only + aggregate-refusal contract (dispatch.md), the runner's closed coverage= summary
+FORM-only + aggregate-refusal contract and the routing advisor's two honesty sentences — the
+advice never gates, and the harness-subagent lane carries no availability verdict (dispatch.md), the
+runner's closed coverage= summary
 vocabulary (gates.md), and the canonical coverage-producer-body command the same doc prints in full
 (gates.md) — to
 the exact token its references/modes/*.md contract must carry, and
 asserts the CURRENT value renders into every bound file. A drifted doc, an unreadable bound file,
 or an absent token FAILS CLOSED.
 
+Beside the bindings runs ONE structure check: the dispatch mode doc's routing matrix must CORRESPOND
+to the frozen advisor registry — one row per step class, in registry order, no duplicates, and every
+CELL of every row equal to the registry's (vehicle, availability and returns alike), with the column
+arity pinned so a fifth cell cannot sit there unread. A reorder, a duplicate, a dropped row, a
+mis-bound vehicle and a drifted availability or returns cell each leave every token present, so a
+token check would pass every one of them; this one names the first CELL that disagrees. The table is
+read only from the surface anchored between the doc's advisor-matrix begin/end markers, so a copy
+elsewhere in the doc can neither stand in for it nor mask its drift, and a drifted header inside the
+anchor fails closed rather than falling through to another table.
+
 --check exits 0/1 as a gate (declare it in docs/ai/gates.json by hand). --json prints the structured
 result. Default prints the per-binding report.
 
@@ -270,15 +321,18 @@ export const main = (argv, ctx = {}) => {
     const unknown = argv.find((a) => !KNOWN_ARGS.has(a));
     if (unknown !== undefined) throw usageFail(`unknown argument: ${unknown}`);
     const results = checkParity(BINDINGS, readText);
+    const structure = checkMatrixStructure(readText);
     const failed = results.filter((r) => !r.ok);
+    const green = failed.length === 0 && structure.ok;
     if (argv.includes('--json')) {
-      return { code: argv.includes('--check') && failed.length > 0 ? 1 : 0, stdout: JSON.stringify({ results, ok: failed.length === 0 }, null, 2), stderr: '' };
+      return { code: argv.includes('--check') && !green ? 1 : 0, stdout: JSON.stringify({ results, structure, ok: green }, null, 2), stderr: '' };
     }
     if (argv.includes('--check')) {
-      const reason = failed.length === 0 ? `${results.length} binding(s) consistent` : `${failed.length} drifted binding(s): ${failed.map((r) => r.constant).join(', ')} — update the contract doc(s) in the SAME edit as the code`;
-      return { code: failed.length === 0 ? 0 : 1, stdout: `doc-parity check: ${failed.length === 0 ? 'PASS' : 'FAIL'} — ${reason}`, stderr: '' };
+      const bindingReason = failed.length === 0 ? `${results.length} binding(s) consistent` : `${failed.length} drifted binding(s): ${failed.map((r) => r.constant).join(', ')} — update the contract doc(s) in the SAME edit as the code`;
+      const structureReason = structure.ok ? 'the advisor matrix structure corresponds' : `the advisor matrix structure DRIFTED — ${structure.files[0].reason}`;
+      return { code: green ? 0 : 1, stdout: `doc-parity check: ${green ? 'PASS' : 'FAIL'} — ${bindingReason}; ${structureReason}`, stderr: '' };
     }
-    return { code: 0, stdout: formatHuman(results), stderr: '' };
+    return { code: 0, stdout: formatHuman(results, structure), stderr: '' };
   } catch (err) {
     return { code: err.exitCode ?? 1, stdout: '', stderr: `doc-parity: ${err.message}` };
   }

package/tools/ensure-configs.mjs

@@ -8,8 +8,8 @@
 //   index          docs/ai/index.md            regenerate-if-missing-or-stale (a GENERATED artifact)
 //
 // Each was prose in references/modes/upgrade.md that an agent performed by hand. One command instead
-// of four is deliberate: four independent runs would be four chances to skip one, and the mode doc now
-// has a single invocation point whose four outcome lines it relays.
+// of five is deliberate: five independent runs would be five chances to skip one, and the mode doc now
+// has a single invocation point whose five outcome lines it relays.
 //
 // The contract (pinned by this module's tests):
 //   • --reconcile is REQUIRED. A bare run is a usage error, so nothing writes by accident.
@@ -17,7 +17,7 @@
 //   • The ops run in a FIXED order and one op's failure NEVER skips the rest: every op reports its own
 //     token, and the exit is non-zero when any of them failed.
 //   • The deployment gate runs ONCE, before any op: an absent/symlinked docs/ai stops the whole run
-//     with the gate's own message rather than four copies of it.
+//     with the gate's own message rather than five copies of it.
 //
 // Output is ENGLISH/structured (repo-artifact Hard Constraint); the agent localizes when narrating.
 // Exit codes: 0 every op fine · 1 an op failed, or the deployment gate stopped the run · 2 usage.
@@ -138,7 +138,7 @@ export const main = (argv = [], ctx = {}) => {
     const cwd = resolve(args.cwd ?? ctx.cwd ?? process.cwd());
     const deps = ctx.deps ?? {};
     // ONE deployment gate for the whole run (see the header): with no docs/ai there is nothing to
-    // reconcile, and four identical STOPs would read as four separate problems.
+    // reconcile, and five identical STOPs would read as five separate problems.
     assertDocsAiDeployment(cwd, deps, { noun: 'the project configuration', rel: 'under docs/ai' });
     const outcomes = runEnsures({ cwd, kitRoot: ctx.kitRoot ?? KIT_ROOT, dryRun: args.dryRun, deps, only: args.only });
     return {