@event4u/agent-config 14.21.0 → 14.23.0

package/src/scripts/_lib/lean_projection_mode.ts

@@ -42,3 +42,130 @@ export function writesThinFiles(mode: LeanProjectionMode): boolean {
 export function deliversBodies(mode: LeanProjectionMode): boolean {
     return mode === 'delivery';
 }
+
+/**
+ * The hosts a thinning mode may actually thin.
+ *
+ * Deliberately NOT "every host id the package knows". `condense`'s `TOOL_DIRS`
+ * writes a per-rule tree for exactly three hosts, so those are the only ids for
+ * which `lean_projection.hosts` can mean anything: naming `windsurf` there would
+ * be a request to thin a single concatenated file that has no per-rule stub
+ * shape, and naming `codex` a request to thin a tree the installer writes and
+ * `condense` never touches. Accepting such an id silently would leave the
+ * operator believing a host was scoped when nothing reads the entry.
+ */
+export const THINNABLE_HOSTS: readonly string[] = ['claude-code', 'cursor', 'cline'];
+
+/**
+ * The shipped default host set for a thinning mode.
+ *
+ * One host, and it is the one host that both binds `pre_tool_use` and honours a
+ * deny (`docs/enforcement-by-host.md:18-28`) — i.e. the only host where the
+ * delivery concern's verdict is acted on. Widening this is a decision, never a
+ * default: see `resolveLeanProjectionHosts`, which never widens implicitly.
+ */
+export const DEFAULT_LEAN_PROJECTION_HOSTS: readonly string[] = ['claude-code'];
+
+/** Why an id in a configured `hosts:` list was not kept. */
+export type DroppedHostReason = 'unknown' | 'not-thinnable';
+
+export interface LeanProjectionHosts {
+    /** The ids that survived, sorted and de-duplicated. */
+    readonly hosts: readonly string[];
+    /** Ids that were dropped, with the reason — reported, never silently discarded. */
+    readonly dropped: ReadonlyArray<{ readonly id: string; readonly reason: DroppedHostReason }>;
+    /** True when nothing was configured and the default was applied. */
+    readonly usedDefault: boolean;
+}
+
+/**
+ * Resolve a configured `lean_projection.hosts` list.
+ *
+ * Three properties, each of which is a failure this repository has seen in a
+ * neighbouring config surface:
+ *
+ * 1. **Absent means the default, never "all".** An empty or missing list
+ *    resolves to `DEFAULT_LEAN_PROJECTION_HOSTS`. A key nobody set must not
+ *    thin every host — that is D1, the defect this axis exists to repair.
+ * 2. **The set never widens implicitly.** Every id is checked against
+ *    `THINNABLE_HOSTS`; anything else is dropped. A typo cannot enrol a host,
+ *    and neither can a real host id that has no per-rule tree.
+ * 3. **A drop is reported, not swallowed.** The caller gets the ids and the
+ *    reason so it can print them. Silently ignoring an entry an operator wrote
+ *    is how a setting comes to mean nothing while looking configured.
+ *
+ * A configured list that resolves to NOTHING keeps `usedDefault: false` and an
+ * empty `hosts` — that is "thin no host", which is a legitimate and safe answer
+ * and must not fall back to the default. Falling back there would turn a
+ * fully-typo'd list into a Claude Code flip the operator never asked for.
+ *
+ * WHICH FILES REACH THIS AT ALL, stated because R2 finding 6 read the drop path
+ * as unreachable: `agent-settings.schema.json` and the wizard's Zod schema both
+ * constrain the items to an `enum`, so an out-of-vocabulary id written through
+ * either surface is a hard validation FAILURE and never arrives here. What
+ * arrives here is a HAND-EDITED `.agent-settings.yml` — the file
+ * `condense._lean_projection_settings` and `hooks/rule_inject_hook.gateOpen`
+ * both read directly, with no validation step in between. The two layers are
+ * defence in depth, not one contract stated twice: the schema is the authoring
+ * gate, this function is the read-time gate, and the drop wording below exists
+ * for the file the schema never saw.
+ */
+export function resolveLeanProjectionHosts(raw: unknown): LeanProjectionHosts {
+    const known = new Set(THINNABLE_HOSTS);
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return { hosts: [...DEFAULT_LEAN_PROJECTION_HOSTS], dropped: [], usedDefault: true };
+    }
+    const hosts: string[] = [];
+    const dropped: Array<{ id: string; reason: DroppedHostReason }> = [];
+    for (const entry of raw) {
+        const id = typeof entry === 'string' ? entry.trim().toLowerCase() : '';
+        if (id === '') {
+            dropped.push({ id: String(entry), reason: 'unknown' });
+            continue;
+        }
+        if (!known.has(id)) {
+            // `not-thinnable` is reserved for an id this package genuinely knows
+            // as a host but which owns no per-rule tree. Everything else is a
+            // typo or an invention, and the two deserve different wording
+            // because the operator's next action differs: fix the spelling, or
+            // learn that the host cannot be thinned at all.
+            dropped.push({ id, reason: KNOWN_NON_THINNABLE_HOSTS.has(id) ? 'not-thinnable' : 'unknown' });
+            continue;
+        }
+        if (!hosts.includes(id)) hosts.push(id);
+    }
+    hosts.sort();
+    return { hosts, dropped, usedDefault: false };
+}
+
+/**
+ * Host ids the package ships surfaces for that own no per-rule rule tree.
+ *
+ * Only used to word a drop precisely; it grants nothing. Sourced from
+ * `condense._ALL_TOOLS` plus the two hosts outside it that the host table
+ * carries (`codex`, `cowork`).
+ */
+const KNOWN_NON_THINNABLE_HOSTS: ReadonlySet<string> = new Set([
+    'claude-desktop', 'augment', 'copilot', 'windsurf', 'gemini', 'codex', 'cowork',
+]);
+
+/** One line per dropped id, for a caller that prints warnings. Empty when nothing was dropped. */
+export function describeDroppedHosts(res: LeanProjectionHosts): string[] {
+    return res.dropped.map(({ id, reason }) =>
+        reason === 'not-thinnable'
+            ? `lean_projection.hosts: "${id}" is a known host but has no per-rule rule tree — dropped`
+            : `lean_projection.hosts: "${id}" is not a thinnable host id — dropped`,
+    );
+}
+
+/**
+ * Does the projector write stubs for this host, under this mode and host set?
+ *
+ * The single predicate `condense` calls. Mode is checked FIRST and on purpose:
+ * with `mode` unset the answer is `false` for every host regardless of what
+ * `hosts` says, so a `hosts:` list left behind after a rollback to `eager-all`
+ * thins nothing.
+ */
+export function thinsHost(mode: LeanProjectionMode, hosts: readonly string[], hostId: string): boolean {
+    return writesThinFiles(mode) && hosts.includes(hostId);
+}

package/src/scripts/_lib/packed_binary_predicate.ts

@@ -0,0 +1,262 @@
+/**
+ * Binary-payload eligibility — the mechanically verified predicate that
+ * reopened the `binary` class.
+ *
+ * WHAT THIS IS, SAID PLAINLY.
+ *
+ * `f573d628c` closed `binary` as a hard zero on 2026-09-07. This REOPENS it,
+ * 24 hours later, and that IS A WEAKENING OF A CONTROL. An AI council
+ * (2026-09-08, 2 seats, unanimous, deep tier) authorised it, and one seat
+ * explicitly refused the framing that this is merely "correcting an
+ * over-generalisation" — that distinction is cosmetic. The control was closed
+ * for the wrong reason, so reopening it is a weakening: justified, and still a
+ * weakening. It is written down here rather than softened because a control
+ * that gets quietly relaxed is worse than one that never existed.
+ *
+ * WHY THE CLOSURE WAS WRONG.
+ *
+ * Decision A over-generalised. Its reasoning was "the three observed binaries
+ * are unused, therefore no binary can ever be required" — an invalid
+ * generalisation from an observed sample to a universal rule. The vendored
+ * tree-sitter grammars are the direct counterexample: bytes the production path
+ * loads and the engine requires. A textual placeholder was lossless for three
+ * PNGs nothing decoded; for a grammar it does not degrade a fixture, it breaks
+ * the engine.
+ *
+ * WHAT REPLACES THE HARD ZERO — AND WHAT DOES NOT.
+ *
+ * Not a prose exception. A binary is admitted only when EVERY condition below
+ * is verified mechanically, on the bytes that are actually in the tarball:
+ *
+ *   1. exactly one manifest entry for the path
+ *   2. no wildcard or directory grant anywhere in the manifest
+ *   3. the packed tarball really contains the path
+ *   4. sha256(bytes) equals the manifest hash
+ *   5. size equals the manifest size
+ *   6. kind is `tree-sitter-wasm-grammar`
+ *   7. WASM magic and version are valid
+ *   8. the PRODUCTION loader reports the manifest's grammar_id
+ *   9. the PRODUCTION loader reports the manifest's ABI
+ *  10. a defined invalid-header mutation of the bytes is REJECTED
+ *  11. a defined unsupported-ABI expectation is REJECTED
+ *
+ * 8 and 9 go through `probeGrammarFile`, the engine's own loader, deliberately:
+ * a second implementation inside the gate could accept bytes the engine
+ * rejects, which is exactly the gap that would let a broken grammar ship while
+ * the gate called it valid.
+ *
+ * 10 and 11 run on every invocation, not in a separate test, because a
+ * predicate whose refusals nobody exercises is a predicate nobody has checked.
+ *
+ * `archive` IS NOT REOPENED.
+ *
+ * This collision produced evidence about grammars and none whatsoever about
+ * archives. `archive` stays a hard zero with no manifest path, and this module
+ * offers none.
+ *
+ * ELIGIBILITY NEVER TOUCHES THE MEASUREMENT.
+ *
+ * The gate reports `observed` as the true count and byte total on every run.
+ * Compliance is `observed <= allowed`, where `allowed` is the number of entries
+ * that passed every condition above — never `observed` minus something excused.
+ * A file that fails one condition lowers `allowed`; it never disappears from
+ * `observed`.
+ *
+ * THE THREAT BOUNDARY — WHO THIS REFUSES, AND WHO IT DOES NOT.
+ *
+ * Written down because the eleven conditions read as a security control and are
+ * only half of one, and a reader could not previously tell that boundary from
+ * an oversight. The `release/14.22.0` self-review finding `d1696732ac28` is
+ * exactly that misreading: it reached for a signature this repository has no
+ * infrastructure to provide (`grep -rniE 'cosign|sigstore|minisign|slsa'`
+ * returns nothing in this tree), because nothing here said where the line was.
+ *
+ * REFUSED. A byte that drifts from what the manifest says — a corrupted copy, a
+ * truncated checkout, a refresh that updated the file and forgot the row, a
+ * grammar whose ABI moved under a version bump, a second row quietly widening a
+ * path. Each of those is one side of the pair changing while the other does
+ * not, and every condition above is a re-derivation from the bytes rather than
+ * a restatement of the row.
+ *
+ * NOT REFUSED, DELIBERATELY. An attacker who edits the manifest and the bytes in
+ * the SAME COMMIT. Every condition here reads the manifest, so a same-commit
+ * pair is internally consistent and passes all eleven. That case is out of
+ * scope for this module and is held by review instead: the manifest is a small
+ * JSON file whose diff a human reads, and a hash changing next to a binary
+ * changing is the most visible shape a diff has.
+ *
+ * WHAT CLOSES IT, AND WHERE. `_lib/vendored_grammar_upstream.ts` compares the
+ * vendored bytes against the `tree-sitter-wasms` release pinned in
+ * `package-lock.json` and installed by `npm ci` — a source outside this
+ * repository's own diff — and refuses rather than passes when that comparison
+ * cannot be made. It is exercised by `tests/scripts/vendored_grammar_upstream.test.ts`,
+ * which is where a reader auditing "what enforces these bytes" should go next.
+ * Its own docblock states what it may not claim: it is not independent of all
+ * repository state, and it does not verify the grammars against the registry
+ * independent of local build state.
+ *
+ * STILL OPEN, AND OWNED BY REVIEW. A `package-lock.json` row that points at a
+ * hostile package. No check in this tree defends that; the lock is
+ * human-readable text declaring dependencies, and reviewing it is the control.
+ */
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** One manifest row. Path-exact; `why` is documentation, never a condition. */
+export interface PackedBinaryEntry {
+    readonly path: string;
+    readonly sha256: string;
+    readonly size: number;
+    readonly kind: string;
+    readonly grammar_id: string;
+    readonly abi: number;
+    readonly why?: string;
+}
+
+export interface PackedBinaryManifest {
+    readonly schema_version: number;
+    readonly entries: readonly PackedBinaryEntry[];
+}
+
+/** The one kind this predicate knows how to verify. */
+export const VERIFIABLE_KIND = 'tree-sitter-wasm-grammar';
+
+/** What the production loader reported for a file. */
+export interface GrammarProbe {
+    readonly abi: number;
+    readonly grammar_id: string;
+}
+
+/** A per-file verdict, with the failing condition named. */
+export interface EligibilityVerdict {
+    readonly path: string;
+    readonly eligible: boolean;
+    /** Every condition that failed, in predicate order. Empty iff eligible. */
+    readonly failures: readonly string[];
+}
+
+/** WASM preamble: `\0asm` followed by little-endian version 1. */
+const WASM_MAGIC = [0x00, 0x61, 0x73, 0x6d] as const;
+const WASM_VERSION = [0x01, 0x00, 0x00, 0x00] as const;
+
+/**
+ * Condition 7, on its own so the header mutation in condition 10 has something
+ * specific to defeat.
+ */
+export function wasmMagicAndVersionValid(bytes: Uint8Array): boolean {
+    if (bytes.length < 8) return false;
+    for (let i = 0; i < 4; i += 1) if (bytes[i] !== WASM_MAGIC[i]) return false;
+    for (let i = 0; i < 4; i += 1) if (bytes[4 + i] !== WASM_VERSION[i]) return false;
+    return true;
+}
+
+/**
+ * The DEFINED invalid-header mutation for condition 10.
+ *
+ * One byte of the magic, flipped. Deliberately NOT `corrupt(bytes)`: arbitrary
+ * corruption can land in a custom section and leave a still-valid module, or
+ * hit padding and change nothing, so a test built on it can pass while proving
+ * nothing. This targets a property the predicate actually validates.
+ */
+export function definedInvalidHeaderMutation(bytes: Uint8Array): Uint8Array {
+    const out = Uint8Array.from(bytes);
+    if (out.length > 1) out[1] = (out[1] as number) ^ 0xff;
+    return out;
+}
+
+/**
+ * The DEFINED unsupported-ABI expectation for condition 11.
+ *
+ * The ABI is not a byte at a known offset — it is what the loader reports after
+ * parsing the module — so this mutates the EXPECTATION rather than the bytes:
+ * an entry claiming an ABI the grammar does not have must be refused. Same
+ * validated property, targeted from the side where it can be stated exactly.
+ */
+export function definedUnsupportedAbiEntry(entry: PackedBinaryEntry): PackedBinaryEntry {
+    return { ...entry, abi: entry.abi + 1 };
+}
+
+/** Condition 2, evaluated over the whole manifest rather than per file. */
+export function wildcardGrants(manifest: PackedBinaryManifest): string[] {
+    return manifest.entries
+        .filter((e) => e.path.includes('*') || e.path.includes('?') || e.path.endsWith('/'))
+        .map((e) => e.path);
+}
+
+/** Paths carrying more than one row — condition 1's uniqueness half. */
+export function duplicatePaths(manifest: PackedBinaryManifest): string[] {
+    const seen = new Map<string, number>();
+    for (const e of manifest.entries) seen.set(e.path, (seen.get(e.path) ?? 0) + 1);
+    return [...seen.entries()].filter(([, n]) => n > 1).map(([p]) => p);
+}
+
+/**
+ * Evaluate every condition for one packed file.
+ *
+ * `probe` is injected so the caller decides how the production loader is
+ * reached — in the gate it is a child process, in a test it can be a stub that
+ * returns a wrong ABI. `null` means the loader could not answer, which fails
+ * conditions 8 and 9 rather than passing them by default.
+ */
+export function evaluateEntry(options: {
+    readonly filePath: string;
+    readonly packedPaths: ReadonlySet<string>;
+    readonly manifest: PackedBinaryManifest;
+    readonly bytes: Uint8Array | null;
+    readonly probe: GrammarProbe | null;
+}): EligibilityVerdict {
+    const { filePath, packedPaths, manifest, bytes, probe } = options;
+    const failures: string[] = [];
+
+    const rows = manifest.entries.filter((e) => e.path === filePath);
+    if (rows.length === 0) failures.push('no manifest entry for this path');
+    if (rows.length > 1) failures.push('more than one manifest entry for this path');
+    const wild = wildcardGrants(manifest);
+    if (wild.length > 0) failures.push(`manifest carries wildcard or directory grants: ${wild.join(', ')}`);
+    if (!packedPaths.has(filePath)) failures.push('path is not in the packed tarball');
+
+    const entry = rows[0];
+    if (entry === undefined) return { path: filePath, eligible: false, failures };
+
+    if (bytes === null) {
+        failures.push('bytes could not be read');
+        return { path: filePath, eligible: false, failures };
+    }
+    const digest = createHash('sha256').update(bytes).digest('hex');
+    if (digest !== entry.sha256) failures.push(`sha256 mismatch: ${digest} != ${entry.sha256}`);
+    if (bytes.length !== entry.size) failures.push(`size mismatch: ${String(bytes.length)} != ${String(entry.size)}`);
+    if (entry.kind !== VERIFIABLE_KIND) failures.push(`kind is not ${VERIFIABLE_KIND}: ${entry.kind}`);
+    if (!wasmMagicAndVersionValid(bytes)) failures.push('WASM magic or version invalid');
+
+    if (probe === null) {
+        failures.push('the production loader could not read this file');
+    } else {
+        if (probe.grammar_id !== entry.grammar_id) {
+            failures.push(`grammar_id mismatch: loader says ${probe.grammar_id}, manifest says ${entry.grammar_id}`);
+        }
+        if (probe.abi !== entry.abi) {
+            failures.push(`ABI mismatch: loader says ${String(probe.abi)}, manifest says ${String(entry.abi)}`);
+        }
+    }
+
+    // Conditions 10 and 11 — the predicate refusing what it must refuse. Run
+    // here, on every invocation, so a refusal path is never merely asserted in
+    // a test somebody can skip.
+    if (wasmMagicAndVersionValid(definedInvalidHeaderMutation(bytes))) {
+        failures.push('self-check failed: a defined invalid-header mutation was NOT rejected');
+    }
+    if (probe !== null && probe.abi === definedUnsupportedAbiEntry(entry).abi) {
+        failures.push('self-check failed: a defined unsupported-ABI expectation was NOT rejected');
+    }
+
+    return { path: filePath, eligible: failures.length === 0, failures };
+}
+
+/** Read and shape-check the manifest. Throws rather than degrading to empty. */
+export function loadManifest(repoRoot: string): PackedBinaryManifest {
+    const p = path.join(repoRoot, 'src', 'config', 'packed-binary-manifest.json');
+    const raw = JSON.parse(fs.readFileSync(p, 'utf-8')) as PackedBinaryManifest;
+    if (!Array.isArray(raw.entries)) throw new Error(`packed-binary-manifest: entries must be an array (${p})`);
+    return raw;
+}

package/src/scripts/_lib/pin_resolver.ts

@@ -253,10 +253,23 @@ function _parse_cli(argv: string[]): { cwd: string; installed: string; forward:
 }
 
 // Script entry — mirrors the Python `if __name__ == "__main__"` block.
+// `build:delegate-aux` bundles this file with `--splitting`, which can move the
+// module body into a shared chunk: `import.meta.url` then names the CHUNK, the
+// URL comparison below never matches, and the entry silently no-ops. Inside that
+// bundle the invoked file name is the reliable signal (same pattern as
+// src/scripts/_cli/cmd_migrate.ts). Defined by that build only.
+declare const __AGENT_CONFIG_CLI_DELEGATE__: boolean | undefined;
 function _isCliEntry(): boolean {
     if (process.argv[1] === undefined) {
         return false;
     }
+    if (typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' && __AGENT_CONFIG_CLI_DELEGATE__) {
+        // A miss falls THROUGH to the URL comparison below, which is the
+        // symlinked-invocation case that fallback exists for.
+        if (path.basename(process.argv[1], '.js') === 'pin_resolver') {
+            return true;
+        }
+    }
     const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
     if (import.meta.url === argvUrl) {
         return true;

package/src/scripts/_lib/recycle_envelope_paths.ts

@@ -73,11 +73,49 @@ export function recycle_envelope_rel(session_id: string | null | undefined): str
     return _sessionKeyed(session_id, RECYCLE_ENVELOPE_REL, 'recycle-envelope', '.json');
 }
 
+/**
+ * THE KEYING CONTRACT, in one place because its absence is what allowed the
+ * 2026-09-09 defect: the record is keyed by the **producing session** — the one
+ * that ran `session:recycle` — and it is READ by the **consuming session**,
+ * which is a different session with a different id. Those two facts were each
+ * true in their own module and were never written down together, so the
+ * producer and the consumer agreed on a PATH and disagreed about whose id
+ * filled it. {@link resolveContinuityRecord} is where that is now reconciled:
+ * it admits the unique record that is NOT the reader's own.
+ */
+
 /** Consumed sibling of {@link recycle_envelope_rel}, same keying. */
 export function recycle_consumed_rel(session_id: string | null | undefined): string {
     return _sessionKeyed(session_id, RECYCLE_CONSUMED_REL, 'recycle-envelope', '.consumed.json');
 }
 
+/**
+ * Where an UNUSABLE resident record is moved aside so the slot can be
+ * published into — never deleted.
+ *
+ * `road-to-continuity-writer-activation` step 1.1. The reader already discards
+ * a malformed, schema-invalid or expired record loudly
+ * ({@link resolveContinuityRecord}'s callers), so nothing is lost by taking it
+ * out of the authoritative name. What WOULD be lost by `unlink` is the evidence
+ * of why a resume did not happen, and that is the only artefact anyone
+ * debugging a missed resume has. Quarantine is one file per session and is
+ * pruned by the same janitor as the rest of `agents/runtime/state/`.
+ *
+ * Deliberately NOT the consumed name: `.consumed.json` is a claim that a
+ * successor read the record, and `predecessorTracePresent` reads exactly that
+ * file to corroborate a lineage. Writing a never-consumed record there would
+ * manufacture a predecessor trace, which is the one thing that check exists to
+ * refuse.
+ */
+export function recycle_quarantine_rel(session_id: string | null | undefined): string {
+    return _sessionKeyed(
+        session_id,
+        path.join(_STATE_REL, 'recycle-envelope.quarantined.json'),
+        'recycle-envelope',
+        '.quarantined.json',
+    );
+}
+
 /**
  * Shared builder. Containment is asserted locally rather than trusted from
  * `safe_stem`: a guarantee living in another module's implementation is one
@@ -133,44 +171,94 @@ export interface ContinuityResolution {
 /**
  * Which record THIS session may read.
  *
- * Three cases, and the third is the one the per-session key exists for:
+ * **A resume reads the PREDECESSOR's record, and this function used to look for
+ * the reader's own.** Corrected 2026-09-09 after measuring it: the producer
+ * writes under the PRODUCING session's id and the consumer arrives with its
+ * OWN, so the two never coincided and every successor was told `absent`. The
+ * mechanism resolved only for a caller with no session id at all — the one
+ * shape no host produces, and the only shape the 19 pre-existing consumer tests
+ * exercised. `road-to-a-recycle-envelope-that-is-consumed` carries the
+ * five-fixture table; AI council 2026-09-09, 2/2, chose the rule below.
+ *
+ * Four cases, and the second is the resume:
+ *
+ * 1. **Own record.** NEVER read. A session re-reading its own state is a loop,
+ *    not a resume, and a second `session_start` for one session (resume, host
+ *    reconnect) made it reachable. Excluded by construction here rather than
+ *    guarded downstream.
+ * 2. **Exactly one record that is not the reader's own.** Read it. That is the
+ *    predecessor.
+ * 3. **Several such records.** START CLEAN and say so — the existing refusal,
+ *    unchanged and now reachable from both branches. Picking the newest is
+ *    precisely the recency resolution the no-index rule below forbids.
+ * 4. **None.** `absent`.
  *
- * 1. **Own id resolves.** Read the record keyed to it, and nothing else. A peer
- *    session's record is not a candidate at any point, so "neither observes the
- *    other's" holds by construction rather than by a comparison that could be
- *    skipped.
- * 2. **No id, one candidate.** Read it. A single record in a checkout with no
- *    resolvable identity is the pre-key situation and is unchanged.
- * 3. **No id, several candidates.** START CLEAN and say so. Picking the newest
- *    is precisely the recency resolution the no-index rule forbids: it would
- *    hand this session a stranger's state and look like a successful resume.
+ * **Why this is not recency, stated because the rule it must not become is one
+ * line away:** nothing is sorted and nothing is compared by time. Uniqueness
+ * admits; ambiguity refuses. The peer-isolation intent the per-session key was
+ * introduced for therefore moves from the KEY to the REFUSAL — a live peer's
+ * record is no longer excluded by its filename, so the branch gate in
+ * `consume_recycle_envelope` is what keeps an unrelated session from resuming
+ * it. That gate is part of this rule, not a decoration on it.
  */
 export function resolveContinuityRecord(
     workspace_root: string,
     session_id: string | null | undefined,
 ): ContinuityResolution {
     const id = String(session_id ?? '').trim();
-    if (id !== '') {
-        const own = path.join(workspace_root, recycle_envelope_rel(id));
-        return fs.existsSync(own)
-            ? { file: own, reason: `continuity record for this session (${safe_stem(id)})` }
-            : { file: null, reason: `no continuity record for this session (${safe_stem(id)})` };
-    }
-    const candidates = listContinuityRecords(workspace_root);
+    const own = id === '' ? null : path.join(workspace_root, recycle_envelope_rel(id));
+    const candidates = listContinuityRecords(workspace_root).filter((f) => f !== own);
     if (candidates.length === 0) {
-        return { file: null, reason: 'no continuity record present' };
+        return {
+            file: null,
+            reason:
+                id === ''
+                    ? 'no continuity record present'
+                    : `no predecessor record in this workspace (own: ${safe_stem(id)})`,
+        };
     }
     if (candidates.length === 1) {
-        return { file: candidates[0] as string, reason: 'one continuity record, no session id to key on' };
+        return {
+            file: candidates[0] as string,
+            reason:
+                id === ''
+                    ? 'one continuity record, no session id to key on'
+                    : `predecessor record, one candidate (own: ${safe_stem(id)})`,
+        };
     }
     return {
         file: null,
         reason:
-            `starting clean: ${candidates.length} continuity records in this workspace and no session id ` +
-            'to tell them apart — resuming from the newest would resume a peer session, not this one',
+            `starting clean: ${candidates.length} continuity records in this workspace and no way to tell ` +
+            'which is the predecessor — resuming from the newest would resume a peer session, not this one',
     };
 }
 
+/**
+ * Which session this one continues — read, never composed.
+ *
+ * The chain is derivable without any new artifact: when this session started,
+ * its reader consumed the predecessor's record and MOVED it to this session's
+ * consumed path (`recycle_consumed_rel`). So the file sitting there is, by
+ * construction, the record this session resumed from, and its `session_id` is
+ * the predecessor.
+ *
+ * Returns the explicit string `none` when there is nothing there. `none` is a
+ * CLAIM — "this session starts a chain" — and is deliberately not an empty
+ * value: a reader must be able to tell "no predecessor" from "nobody wrote the
+ * field", because only the second one is a reason to go looking.
+ */
+export function resolvePredecessor(projectRoot: string, sessionId: string | null): string {
+    try {
+        const consumed = path.join(projectRoot, recycle_consumed_rel(sessionId));
+        const raw = JSON.parse(fs.readFileSync(consumed, 'utf-8')) as { session_id?: unknown };
+        const prior = String(raw.session_id ?? '').trim();
+        return prior === '' ? 'none' : prior;
+    } catch {
+        return 'none';
+    }
+}
+
 /**
  * Is there any trace in this workspace of the session a record names as its
  * predecessor?