@sabaiway/agent-workflow-kit 5.10.0 → 5.11.0

package/tools/flow-check-cores.mjs

@@ -20,6 +20,7 @@ import {
   short, shellQuote, writerCommand,
   collectUnansweredRedRefusals, collectDegradeCoverageRefusals, collectReceiptCoverageRefusals,
 } from './flow-check-rungs.mjs';
+import { CONTENT_FREE_FINGERPRINT } from './core-evidence.mjs';
 
 // The checker only refuses — park/resume/complete are explicit writer actions (#59). Printed
 // operand shapes: flag values ride the inline --flag='value' form and positionals follow a
@@ -128,10 +129,21 @@ const deltaRefusals = (records, owner) => {
 // degrade after a final-start at the same fingerprint refuses unless a LATER final-start at that
 // fingerprint completed (its `final` record landed after it). The checker reads raw records,
 // never the authoritative selection (#65).
-const degradeOrderingRefusals = (coreRecords) => {
+const degradeOrderingRefusals = (coreRecords, advisories) => {
   const refusals = [];
+  let contentFree = 0;
   coreRecords.forEach((r, i) => {
     if (r.kind !== 'degrade') return;
+    // A degrade carries no base and no attempt, so on the content-free fingerprint two records
+    // from unrelated clean moments pair up and this rung refuses EVERY commit, whatever tree is
+    // being judged. Their order is not a fact about any tree, so it decides nothing here. Stated
+    // residual: #64 is therefore unenforceable for a degrade minted on a clean tree until the
+    // record carries a base — the queued store migration owns that, and a clean tree gates nothing
+    // meanwhile.
+    if (r.fingerprint === CONTENT_FREE_FINGERPRINT) {
+      contentFree += 1;
+      return;
+    }
     const startedBefore = coreRecords.some((s, j) => j < i && s.kind === 'final-start' && s.fingerprint === r.fingerprint);
     if (!startedBefore) return;
     const cured = coreRecords.some((s, j) => j > i && s.kind === 'final-start' && s.fingerprint === r.fingerprint
@@ -140,6 +152,9 @@ const degradeOrderingRefusals = (coreRecords) => {
       refusals.push(`a core degrade (backend "${r.backend}") landed AFTER a final-start at its fingerprint (${short(r.fingerprint)}) with no later completed re-run at it — degrades mint strictly BEFORE the final run (#64); re-run run-gates.mjs --final on this tree`);
     }
   });
+  if (contentFree > 0) {
+    advisories.push(`${contentFree} core degrade(s) minted on a CONTENT-FREE tree are outside the ordering rung (#64): the record carries no base, so two clean moments cannot be shown to be one and their order states nothing about any tree`);
+  }
   return refusals;
 };
 
@@ -225,7 +240,7 @@ const baseMotionRefusals = (chain, planId, owner, motion) => {
 // Phase-1 rungs (#65/#25/#42 — each self-gates on an OWN adoption). Absent inputs keep the decision
 // byte-identical to the Plan-2 checker. `consumer` rides through to the #65 lane split and defaults
 // to the STRICT lane, so a caller that forgets to thread it inherits strictness.
-export const decideFlowCheck = ({ flowRead, coreRead, owner, flowPath = 'the flow store', corePath = 'the core evidence store', motion = null, evidence = null, consumer = 'commit-guard' }) => {
+export const decideFlowCheck = ({ flowRead, coreRead, owner, flowPath = 'the flow store', corePath = 'the core evidence store', motion = null, evidence = null, consumer = 'commit-guard', treeCarriesBytes = true }) => {
   const refusals = [];
   const advisories = [];
   if (flowRead.readError) refusals.push(`the flow store is unreadable (${flowRead.readError}) — the checker consumes the FULL read-result; inspect ${flowPath} (fail closed)`);
@@ -243,11 +258,25 @@ export const decideFlowCheck = ({ flowRead, coreRead, owner, flowPath = 'the flo
     if (motion != null && plan.integrityClean) refusals.push(...baseMotionRefusals(chain, planId, owner, motion));
   }
   refusals.push(...deltaRefusals(records, owner));
-  refusals.push(...degradeOrderingRefusals(coreRead.records));
+  refusals.push(...degradeOrderingRefusals(coreRead.records, advisories));
   if (evidence != null) {
-    refusals.push(...collectUnansweredRedRefusals({ flowRecords: records, coreRecords: coreRead.records, currentBase: evidence.tree.base, owner, consumer, currentFingerprint: evidence.tree.fingerprint }));
-    refusals.push(...collectDegradeCoverageRefusals({ flowRecords: records, coreRecords: coreRead.records, tree: evidence.tree, owner, backends: evidence.degradeBackends }));
-    refusals.push(...collectReceiptCoverageRefusals({ flowRecords: records, receipts: evidence.receipts, tree: evidence.tree, owner, backends: evidence.receiptBackends, declaredPaths: evidence.declaredPaths, refreshCap: evidence.refreshCap }));
+    // The base-keyed rung always runs — it asks about this BASE's gate history, which a tree with
+    // no content does not change. The two FINGERPRINT-keyed rungs do not, when the CALLER states
+    // that the tree carries no bytes: their coverage would then be demanded of the one fingerprint
+    // every clean moment shares, so whatever they found there was minted by another moment and
+    // possibly another base (the symmetry the #65 content-free arm and commit-guard's content-free
+    // lanes state — such evidence must decide nothing, in either direction). The fact is DECLARED
+    // by the caller rather than derived here: only the caller knows whether it is judging a commit
+    // at all, and a checker that keyed it off the fingerprint alone would also silence the rungs
+    // for every routine clean-tree check, where they are exactly what the operator asked for. The
+    // skip is RECORDED, never silent.
+    refusals.push(...collectUnansweredRedRefusals({ flowRecords: records, coreRecords: coreRead.records, currentBase: evidence.tree.base, owner, consumer, currentFingerprint: evidence.tree.fingerprint, advisories }));
+    if (!treeCarriesBytes) {
+      advisories.push('the caller states this tree carries NO bytes, so the fingerprint-keyed correlations are skipped: degrade coverage (#25) and receipt coverage (#42) here, and the D10 flow-to-final binding at the guard — evidence at a content-free fingerprint belongs to some other clean moment');
+    } else {
+      refusals.push(...collectDegradeCoverageRefusals({ flowRecords: records, coreRecords: coreRead.records, tree: evidence.tree, owner, backends: evidence.degradeBackends }));
+      refusals.push(...collectReceiptCoverageRefusals({ flowRecords: records, receipts: evidence.receipts, tree: evidence.tree, owner, backends: evidence.receiptBackends, declaredPaths: evidence.declaredPaths, refreshCap: evidence.refreshCap }));
+    }
   }
   return { refusals, advisories };
 };

package/tools/flow-check-rungs.mjs

@@ -13,7 +13,7 @@ import {
   CHAIN_KIND, canonicalFlowDigest, authoritativeFlowRecords, flowTreeIdentity,
 } from './flow-record.mjs';
 import { resolveRecordReference } from './flow-store.mjs';
-import { authoritativeOfKind, summarizeReviewReceiptsForTree } from './core-evidence.mjs';
+import { authoritativeOfKind, summarizeReviewReceiptsForTree, CONTENT_FREE_FINGERPRINT } from './core-evidence.mjs';
 import { FALLBACK_LENS_ADDITIONAL_ONLY } from './cheap-agents.mjs';
 
 export const short = (digest) => `${digest.slice(0, 12)}…`;
@@ -161,7 +161,21 @@ export const evaluateVetoOverride = ({ records, vetoReceipt, tree }) => {
 // runner-attested capability (a one-time unpublished nonce over stdin or an inherited FD, verified
 // against a one-way commitment recorded in the final-start); it needs its own IPC contract and is
 // QUEUED, never pretended here.
-export const collectUnansweredRedRefusals = ({ flowRecords, coreRecords, currentBase, owner, consumer = 'commit-guard', currentFingerprint = null }) => {
+//
+// The CONTENT-FREE arm (FINGERPRINT-BASE-BINDING, second face): a red final minted while the work
+// tree was CLEAN hashes an empty payload, and that one value is shared by every clean moment of
+// every repository — so the base correlation resolves to as many bases as the store has clean
+// moments and refuses fail-closed forever, on a record that describes no working state at all.
+// The arm is keyed on the FINGERPRINT, not on how many bases happen to correlate: resolving to
+// exactly one base is an accident of store history, never a statement about the tree. It is one
+// half of a symmetry, and it is only sound WITH the other: content-free evidence must decide
+// nothing in either direction, so commit-guard equally refuses to ATTEST from a content-free
+// receipt (commit-guard.mjs, the two content-free lanes) — without that half, stepping over a red
+// here would leave a stale green free to acquit. The skip is RECORDED in the `advisories` sink —
+// a rung that steps over evidence says so. That sink is the ONLY place the skip is observable:
+// decideFlowCheck always passes one, and a caller that omits it (a test, a future consumer) gets
+// the same refusals and no record of the step.
+export const collectUnansweredRedRefusals = ({ flowRecords, coreRecords, currentBase, owner, consumer = 'commit-guard', currentFingerprint = null, advisories = [] }) => {
   if (!hasOwnAdoption(flowRecords, owner)) return [];
   const adoptionInstants = flowRecords
     .filter((r) => r.kind === CHAIN_KIND && r.purpose === 'adoption' && r.owner === owner)
@@ -192,6 +206,10 @@ export const collectUnansweredRedRefusals = ({ flowRecords, coreRecords, current
   for (const { r, i } of finals) {
     if (r.status !== 'red') continue;
     if (armingInstant !== null && isCanonicalInstant(r.timestamp) && Date.parse(r.timestamp) < armingInstant) continue;
+    if (r.fingerprintBefore === CONTENT_FREE_FINGERPRINT) {
+      advisories.push(`a red final (attempt "${r.attempt}") is OUTSIDE the rung: its tree fingerprint ${short(r.fingerprintBefore)} is CONTENT-FREE — a clean work tree emits an empty payload, so the value identifies no working state, correlates to no base, and gates no commit (#65 content-free arm)`);
+      continue;
+    }
     const bases = basesAt(r.fingerprintBefore);
     if (bases.length === 0) {
       refusals.push(`a red final (attempt "${r.attempt}") cannot be base-correlated: no flow record carries its tree fingerprint ${short(r.fingerprintBefore)} — the zero-base lane is a fail-closed ambiguity (#65); the rung demands exactly ONE base through the flow store`);

package/tools/flow-check.mjs

@@ -60,7 +60,7 @@ const usageFail = (message) => Object.assign(new Error(message), { exitCode: 2 }
 // PREVIOUS one and an in-matrix comparison would make a new green final unreachable. The SAME
 // distinction reaches the #65 unanswered-red rung (its own header states the split): the 'gate'
 // lane also answers a red under a provable in-progress retry, for the same reason.
-export const computeFlowDecision = ({ cwd = process.cwd(), consumer = 'gate', probes = {} } = {}) => {
+export const computeFlowDecision = ({ cwd = process.cwd(), consumer = 'gate', probes = {}, treeCarriesBytes = true } = {}) => {
   const fingerprintProbe = probes.fingerprint ?? computeTreeFingerprint;
   const owner = deriveFlowOwner(cwd);
   if (owner == null) {
@@ -161,14 +161,29 @@ export const computeFlowDecision = ({ cwd = process.cwd(), consumer = 'gate', pr
   // authoritative completed final at the CURRENT fingerprint, status green FIRST (a newer red
   // is never bypassed by an older green's matching hash — the guard's own red arm refuses it),
   // then the hash comparison.
+  // …and NOT when the CALLER states the tree carries no bytes: the receipt it would bind was then
+  // found at the one fingerprint every clean moment of every repository shares, so it was minted by
+  // some other moment and its projection hash describes that moment's store, not this one.
+  // Correlating it would make the outcome depend on which stray clean moment the store recorded
+  // last — the same fact the #65 rung and commit-guard's own content-free lanes apply.
+  // The probe stays INSIDE this lane: an armed decision already paid for the tree (evidence.tree),
+  // and every other lane — the gate consumer, a broken store, an unarmed flow — must stay inert.
+  // A hoisted probe would make those lanes read the whole tree and let an unreadable untracked
+  // file throw where the answer is otherwise a quiet, healthy no-op.
   const bindingRefusals = [];
-  if (consumer === 'commit-guard' && !healthBroken) {
+  const completedFinals = consumer === 'commit-guard' && !healthBroken && treeCarriesBytes
+    ? authoritativeOfKind(coreRead.records, 'final')
+    : [];
+  // …and only when a final record EXISTS to bind: with none in the store there is no binding to
+  // verify, so reading the tree would answer a question nobody asked.
+  if (completedFinals.length > 0) {
     const currentFingerprint = evidence?.tree.fingerprint ?? fingerprintProbe(cwd);
     if (currentFingerprint == null) {
       bindingRefusals.push('the current tree fingerprint is unresolvable — the D10 flow binding cannot be verified (fail closed); re-run run-gates.mjs --final on a healthy tree');
     }
-    const currentFinal = currentFingerprint == null ? undefined : authoritativeOfKind(coreRead.records, 'final')
-      .find((r) => r.fingerprintBefore === currentFingerprint);
+    const currentFinal = currentFingerprint == null
+      ? undefined
+      : completedFinals.find((r) => r.fingerprintBefore === currentFingerprint);
     if (currentFinal !== undefined && currentFinal.status === 'green') {
       const bound = currentFinal.evidenceHashes?.flow;
       if (typeof bound === 'string') {
@@ -193,7 +208,7 @@ export const computeFlowDecision = ({ cwd = process.cwd(), consumer = 'gate', pr
       }
     }
   }
-  const { refusals, advisories } = decideFlowCheck({ flowRead, coreRead, owner, flowPath, corePath, motion, evidence, consumer });
+  const { refusals, advisories } = decideFlowCheck({ flowRead, coreRead, owner, flowPath, corePath, motion, evidence, consumer, treeCarriesBytes });
   // Semantic refusals bind only an ARMED store; the D10 binding refusals ride the commit-guard
   // lane UNCONDITIONALLY — a deleted or truncated store must never un-arm the binding.
   const effectiveRefusals = healthBroken ? refusals : [...(armed ? [...refusals, ...evidenceRefusals] : []), ...bindingRefusals];

package/tools/observation-builder.mjs

@@ -0,0 +1,123 @@
+// observation-builder.mjs — measure a scope and construct the OBSERVATION record (delegation
+// Plan 3, Phase 3). Extracted from dispatch.mjs so `dispatch observe` and the handoff-return rung
+// build the IDENTICAL record through ONE path: the rung is imported by dispatch.mjs for its verb,
+// so a rung importing dispatch.mjs back would be exactly the cycle test/read-graph-purity.test.mjs
+// pins the tools graph against. Every function here moved byte-for-byte; the only new export is
+// the record construction the observe verb previously inlined.
+//
+// Spawns nothing but git READS (through the shared gitLine). No CLI, no writes, no side effects on
+// import. Dependency-free, Node >= 22.
+
+import { readFileSync, openSync, closeSync, realpathSync, constants as fsConstants } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import {
+  DELEGATION_SCHEMA_VERSION, computeNumerator, evaluateObservationEligibility,
+} from './dispatch-record.mjs';
+import { lstatNoFollowRead, describeNonRegular } from './fs-read-nofollow.mjs';
+import { gitLine } from './flow-store-read.mjs';
+import { lexicalRepoRelative } from './repo-lex.mjs';
+
+// 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 measured observation can never claim a partial object.
+const SOLO_COMPONENT_KIND = 'new';
+
+// 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.
+export 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.
+export 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 entry, 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.
+export 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 };
+};
+
+export 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.
+export const formatRatio = (metric) => (metric.eligible
+  ? `L = ${ratio(metric.numeratorBytes / metric.denominatorBytes)} (${metric.numeratorBytes} B / ${metric.denominatorBytes} B)`
+  : `L = n/a — INELIGIBLE (${metric.ineligibleReason})`);
+
+// The ONE observation-record construction: the eligibility is evaluated here, over the same two
+// numbers the record carries, so a record and its own eligibility can never disagree at the door.
+export const buildObservationRecord = ({ waveId, stepClass, measured, provenance, denominatorBytes, planId, phase, timestamp }) => {
+  const eligibility = evaluateObservationEligibility({ numeratorBytes: measured.numeratorBytes, denominatorBytes });
+  return {
+    schema: DELEGATION_SCHEMA_VERSION,
+    kind: 'observation',
+    waveId,
+    stepClass,
+    scope: measured.scope,
+    metric: {
+      numeratorBytes: measured.numeratorBytes,
+      denominatorBytes,
+      components: measured.components,
+      provenance,
+      eligible: eligibility.eligible,
+      ineligibleReason: eligibility.ineligibleReason,
+    },
+    planId,
+    phase,
+    timestamp,
+  };
+};

package/tools/satellite-locator.mjs

@@ -0,0 +1,179 @@
+// satellite-locator.mjs — slug → satellite worktree, and the proof that the handoff found there IS
+// that satellite's identity (delegation Plan 3, Phase 2).
+//
+// Extracted out of worktrees.mjs so BOTH modes can ask the question: `worktrees prompt` composes a
+// satellite's cold-start prompt today, and the dispatch-side handoff-return rung — a later phase,
+// not yet wired — will read what came back through this same leaf. That rung is a `dispatch` verb,
+// so this leaf is what will keep the 3200-line worktrees tool out of the dispatch CLI's closure.
+//
+// READ-ONLY by construction: it writes nothing, spawns nothing, and — deliberately — CONTENT-READS
+// nothing of its own. The git runner and the fs seams are INJECTED, so a caller decides what may
+// run, and the content read arrives as `fs.readFileNoFollow(abs)` returning the family's structured
+// outcome { bytes } | { absent } | { unsafe } | { error: code }. That is not fastidiousness: the ONE
+// no-follow read door lives in worktrees.mjs, its single body is pinned there by a tripwire, and a
+// second body here would be exactly the duplication that pin exists to prevent. `fs` is the shape
+// worktrees.mjs builds: { lstat, readdir, realpath, readFileNoFollow }.
+//
+// Node built-ins plus two pure leaves. No side effects on import; no CLI. Dependency-free, Node >= 22.
+
+import { join } from 'node:path';
+import { PLANS_REL } from './plan-files.mjs';
+import { stop, handoffBasename, parseProvisionRecord, displayValue } from './worktrees-record.mjs';
+
+// Every refusal below is the worktrees STOP, unchanged — a caller that reached this leaf directly
+// (the dispatch side does) must be able to recognize it without importing worktrees.mjs.
+export { WORKTREES_STOP } from './worktrees-record.mjs';
+
+export const DEFAULT_BRANCH_PREFIX = 'aw/';
+
+export const parseWorktreeList = (text) => {
+  const entries = [];
+  let fields = [];
+  const finishEntry = () => {
+    if (fields.length === 0) return;
+    const entry = { path: null, head: null, branch: null, detached: false, prunable: false, bare: false };
+    for (const field of fields) {
+      if (field.startsWith('worktree ')) entry.path = field.slice('worktree '.length);
+      else if (field.startsWith('HEAD ')) entry.head = field.slice('HEAD '.length);
+      else if (field.startsWith('branch ')) entry.branch = field.slice('branch '.length);
+      else if (field === 'detached') entry.detached = true;
+      else if (field === 'bare') entry.bare = true;
+      else if (field === 'prunable' || field.startsWith('prunable ')) entry.prunable = true;
+    }
+    if (entry.path !== null) entries.push(entry);
+    fields = [];
+  };
+  for (const field of String(text).split('\0')) {
+    if (field === '') finishEntry();
+    else fields.push(field);
+  }
+  finishEntry();
+  return entries;
+};
+
+export const listWorktrees = (git, cwd) => {
+  const r = git(['worktree', 'list', '--porcelain', '-z'], cwd);
+  if (r.status !== 0) throw stop(`git worktree list failed: ${r.stderr.trim() || r.stdout.trim()}`);
+  return parseWorktreeList(r.stdout);
+};
+
+export const classifyNodeNoFollow = (path, fs) => {
+  const node = (() => {
+    try {
+      return { stat: fs.lstat(path) };
+    } catch (error) {
+      return error?.code === 'ENOENT'
+        ? { stat: null }
+        : { error: error?.code ?? 'fs error' };
+    }
+  })();
+  if (node.error) return { kind: 'error', error: node.error };
+  if (node.stat === null) return { kind: 'absent' };
+  if (!node.stat.isSymbolicLink()) {
+    if (node.stat.isDirectory()) return { kind: 'plain-directory', stat: node.stat };
+    if (node.stat.isFile()) return { kind: 'regular-file', stat: node.stat };
+    return { kind: 'special', stat: node.stat };
+  }
+  const realPath = (() => {
+    try {
+      return { path: fs.realpath(path) };
+    } catch (error) {
+      return { error: error?.code ?? 'fs error' };
+    }
+  })();
+  if (realPath.error) return { kind: 'symlink-unresolvable', error: realPath.error };
+  const target = (() => {
+    try {
+      return { stat: fs.lstat(realPath.path) };
+    } catch (error) {
+      return { error: error?.code ?? 'fs error' };
+    }
+  })();
+  if (target.error) return { kind: 'symlink-unresolvable', error: target.error };
+  if (target.stat.isDirectory()) return { kind: 'symlink-to-directory', realPath: realPath.path, stat: node.stat };
+  if (target.stat.isFile()) return { kind: 'symlink-to-file', realPath: realPath.path, stat: node.stat };
+  return { kind: 'symlink-to-special', realPath: realPath.path, stat: node.stat };
+};
+
+// Whole-chain no-follow: the worktree root, docs, and docs/plans must be plain directories;
+// handoff candidates count ONLY as regular files. states: ok | absent | unreadable.
+// ANY stat failure (not just readdir) renders honestly — list must never crash on a bad node.
+export const scanPlansDir = ({ wtRoot, fs }) => {
+  if (classifyNodeNoFollow(wtRoot, fs).kind !== 'plain-directory') return { state: 'unreadable' };
+  const docs = classifyNodeNoFollow(join(wtRoot, 'docs'), fs);
+  if (docs.kind === 'absent') return { state: 'absent' };
+  if (docs.kind !== 'plain-directory') return { state: 'unreadable' };
+  const plans = classifyNodeNoFollow(join(wtRoot, PLANS_REL), fs);
+  if (plans.kind === 'absent') return { state: 'absent' };
+  if (plans.kind !== 'plain-directory') return { state: 'unreadable' };
+  let names;
+  try {
+    names = fs.readdir(join(wtRoot, PLANS_REL));
+  } catch {
+    return { state: 'unreadable' };
+  }
+  const handoffs = [];
+  const nonRegular = [];
+  for (const n of names) {
+    if (!/^handoff-.+\.md$/.test(n)) continue;
+    const cand = classifyNodeNoFollow(join(wtRoot, PLANS_REL, n), fs);
+    if (cand.kind !== 'regular-file') nonRegular.push(n);
+    else handoffs.push(n);
+  }
+  return { state: 'ok', handoffs, nonRegular };
+};
+
+export const branchNameOf = (entry) => entry.branch?.replace(/^refs\/heads\//, '') ?? null;
+
+export const findSatelliteEntry = ({ root, slug, branch, git, fs }) => {
+  const entries = listWorktrees(git, root).slice(1);
+  const exactHandoff = [];
+  for (const entry of entries) {
+    if (entry.prunable) continue;
+    const scan = scanPlansDir({ wtRoot: entry.path, fs });
+    if (scan.state === 'ok' && scan.handoffs.includes(handoffBasename(slug))) exactHandoff.push(entry);
+  }
+  if (exactHandoff.length > 1) {
+    throw stop(`multiple worktrees carry ${handoffBasename(slug)} — cleanup the duplicate identity before continuing`);
+  }
+  if (branch !== null) {
+    const byBranch = entries.filter((entry) => entry.branch === `refs/heads/${branch}`);
+    if (byBranch.length > 1) throw stop(`multiple worktrees claim branch ${branch}`);
+    if (byBranch.length === 1) return byBranch[0];
+  }
+  if (exactHandoff.length === 1) return exactHandoff[0];
+  const fallback = entries.filter((entry) => entry.branch === `refs/heads/${DEFAULT_BRANCH_PREFIX}${slug}`);
+  if (fallback.length === 1) return fallback[0];
+  throw stop(`no registered satellite worktree for ${slug}`);
+};
+
+export const readSatelliteIdentity = ({ entry, slug, expectedBranch, fs, abandon = false }) => {
+  const name = handoffBasename(slug);
+  const scan = scanPlansDir({ wtRoot: entry.path, fs });
+  if (scan.state === 'ok' && scan.nonRegular.includes(name)) {
+    throw stop(`handoff identity mismatch: ${name} is not a regular file`);
+  }
+  if (scan.state !== 'ok' || !scan.handoffs.includes(name)) {
+    if (abandon) throw stop(`${name} is absent — force deletion is forbidden without the handoff identity`);
+    throw stop(`handoff identity mismatch: expected ${name} in the satellite`);
+  }
+  // Every value below reaches a terminal, and every one of them is foreign: the names come from a
+  // directory listing, the record fields from a hand-editable file. They render ESCAPED — the guard
+  // that refuses them for the prompt must not be undone by the message that reports them.
+  if (scan.handoffs.length !== 1) {
+    throw stop(`handoff identity mismatch: expected exactly ${name}, found [${scan.handoffs.map(displayValue).join(', ')}]`);
+  }
+  const leaf = fs.readFileNoFollow(join(entry.path, PLANS_REL, name));
+  if (!leaf.bytes) throw stop(`handoff identity mismatch: ${name} is not readable as a regular file`);
+  const record = parseProvisionRecord(String(leaf.bytes));
+  const liveBranch = branchNameOf(entry);
+  const wantedBranch = expectedBranch ?? liveBranch;
+  if (record.slug !== slug || record.branch !== wantedBranch || liveBranch !== wantedBranch) {
+    throw stop(
+      `handoff identity mismatch: expected slug ${slug} and branch ${displayValue(wantedBranch)}; ` +
+      `record has slug ${record.slug === null ? '(missing)' : displayValue(record.slug)} and branch ${record.branch === null ? '(missing)' : displayValue(record.branch)}, ` +
+      `live branch ${liveBranch === null ? '(detached)' : displayValue(liveBranch)}`,
+    );
+  }
+  return { record, path: join(entry.path, PLANS_REL, name), branch: wantedBranch };
+};