@dzhechkov/harness-core 0.8.45 → 0.8.47

package/src/round-exec-claim.ts

@@ -0,0 +1,43 @@
+/**
+ * round-exec-claim-takeover (FR-1): the pure verdict behind `dz round exec`'s claim transaction.
+ *
+ * A round claimed by an `exec` whose process died (SIGTERM, OOM, reboot) used to refuse every later
+ * `exec` forever (backlog 280e914607397474). This decides — from facts the caller measured under the
+ * state lock — whether the standing claim is held, provably stale-dead, or unknowable:
+ *
+ * - `pidAlive === true`  ⇒ `held`, regardless of age (a live owner is never taken over);
+ * - `pidAlive === null`  ⇒ `unknown` (the probe was inconclusive — refusal is the safe side);
+ * - `pid` not a positive safe integer ⇒ `unknown` («no pid recorded») — nothing to probe;
+ * - `execClaimedAt` unparsable ⇒ `unknown` («claim time unreadable») — no age to debounce on;
+ * - `pidAlive === false` and age ≥ `staleMinutes` ⇒ `stale-dead` with the floored age;
+ * - `pidAlive === false` but younger ⇒ `held` — a just-died claim may be a restart in flight, and
+ *   the threshold is the debounce.
+ *
+ * Pure: no clock, no process table — `now` and `pidAlive` are inputs so the caller keeps the
+ * critical section short (`process.kill(pid, 0)`, NFR-1) and tests need no real processes.
+ */
+export type ExecClaimVerdict =
+  | { kind: 'held' }
+  | { kind: 'stale-dead'; ageMinutes: number }
+  | { kind: 'unknown'; reason: string };
+
+export type ExecClaimTakeoverInput = {
+  readonly execClaimedAt?: string | undefined;
+  readonly pid?: number | undefined;
+  readonly pidAlive: boolean | null;
+  readonly now: number;
+  readonly staleMinutes: number;
+};
+
+export function decideExecClaimTakeover(input: ExecClaimTakeoverInput): ExecClaimVerdict {
+  if (input.pidAlive === true) return { kind: 'held' };
+  if (input.pid === undefined || !Number.isSafeInteger(input.pid) || input.pid <= 0) {
+    return { kind: 'unknown', reason: 'no pid recorded' };
+  }
+  if (input.pidAlive === null) return { kind: 'unknown', reason: 'PID probe inconclusive' };
+  const claimedMs = input.execClaimedAt === undefined ? Number.NaN : Date.parse(input.execClaimedAt);
+  if (!Number.isFinite(claimedMs)) return { kind: 'unknown', reason: 'claim time unreadable' };
+  const ageMinutes = Math.floor((input.now - claimedMs) / 60_000);
+  if (ageMinutes >= input.staleMinutes) return { kind: 'stale-dead', ageMinutes };
+  return { kind: 'held' };
+}

package/src/round.ts

@@ -102,6 +102,8 @@ export interface RoundLedgerRow {
    *  fix-round-1 #1/#2 (ADR-001 п.2 amended): also present when an EXPLICIT `--reviewer` AGREES with
    *  the sidecar's own `gradedBy` (`reviewSource:'flag+qe-bridge'` below names that case). */
   readonly reviewMinutes?: number;
+  readonly reviewIdentitySource?: 'round-run-task' | 'partial-identity' | 'legacy-window';
+  readonly reviewIdentity?: { readonly round: number | null; readonly roundRun: string | null; readonly taskId: string | null; readonly bridgeRunId: string | null };
   /** measurement-integrity FR-7: present ONLY alongside `reviewMinutes` — names where `reviewer` and
    *  `reviewMinutes` came from, so a reader never confuses a sidecar-sourced figure for a flag.
    *  review-cost-ledger fix-round-1 #1/#2 (ADR-001 п.2 amended): `'qe-bridge'` when `reviewer` was
@@ -188,6 +190,8 @@ export interface RoundLedgerRow {
  * `closeRound` never opens a file.
  */
 export interface RoundReviewSidecar {
+  readonly reviewIdentitySource?: RoundLedgerRow['reviewIdentitySource'];
+  readonly reviewIdentity?: RoundLedgerRow['reviewIdentity'];
   /** Who graded it — family + model, e.g. `codex:gpt-5.6-sol`. */
   readonly gradedBy: string;
   readonly elapsedMs: number;
@@ -609,6 +613,8 @@ export function closeRound(input: {
     ...(nonEmpty(input.stateId) ? { stateId: input.stateId } : {}),
     ...(input.state.envelope !== undefined ? { envelope: input.state.envelope } : {}),
     ...(reviewSource !== null ? { reviewSource } : {}),
+    ...(reviewerTiedToSidecar && input.reviewSidecar?.reviewIdentitySource !== undefined ? { reviewIdentitySource: input.reviewSidecar.reviewIdentitySource } : {}),
+    ...(reviewerTiedToSidecar && input.reviewSidecar?.reviewIdentity !== undefined ? { reviewIdentity: input.reviewSidecar.reviewIdentity } : {}),
     ...(reviewMinutes !== null ? { reviewMinutes } : {}),
     taskId,
     ...(taskIdSource !== null ? { taskIdSource } : {}),
@@ -700,11 +706,13 @@ export function readOpenRoundTaskId(
   states: readonly RoundState[],
   slug: string,
   unreadableStateCount = 0,
+  authorityReadError = false,
 ): {
   readonly taskId: string | null;
   readonly source: 'open-round' | 'derived-legacy' | 'no-open-round' | 'ambiguous' | 'unavailable';
 } {
   const matches = states.filter((s) => s.slug === slug);
+  if (authorityReadError) return { taskId: null, source: 'unavailable' };
   const unreadable = Number.isFinite(unreadableStateCount) && unreadableStateCount > 0 ? Math.floor(unreadableStateCount) : 0;
   if (unreadable > 0 && matches.length === 0) return { taskId: null, source: 'unavailable' };
   if (unreadable > 0) return { taskId: null, source: 'ambiguous' };

package/src/run-records.ts

@@ -13,11 +13,28 @@
  * Pure: payload in, verdict out. The CLI owns paths, the append, the read-back and the exit code.
  */
 
+import { createHash } from 'node:crypto';
 import { matchCodexRollouts } from './codex-rollouts.js';
 import type { CodexRollout } from './codex-rollouts.js';
-import { redactTrainingPayload } from './feature-adr-checkpoints.js';
+import { fnv1a64, redactTrainingPayload } from './feature-adr-checkpoints.js';
 import { validateExperimentEnvelope } from './feature-adr-envelope.js';
 
+// Capture contract: ordered named fields, with absent distinct from explicit null.
+// Kept private at producer/reader boundaries; both use this exact sha256 representation.
+function capturedPayload(evidence: Record<string, unknown>): string {
+  const value = (v: unknown) => v === undefined ? { absent: true } : v;
+  const receipts = Array.isArray(evidence['receipts']) ? evidence['receipts'] : [];
+  return JSON.stringify([
+    ...['schema', 'sessionId', 'turnId', 'sourcePath', 'matchBasis', 'capturedFrom', 'capturedTo', 'model', 'cwd', 'reportedTotalBasis', 'inputCacheSemantics'].map((k) => [k, value(evidence[k])]),
+    ['owner', ...['runId', 'taskId', 'stage', 'attempt', 'role'].map((k) => [k, value((evidence['owner'] as Record<string, unknown> | undefined)?.[k])])],
+    receipts.map((raw) => {
+      const r = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw as Record<string, unknown> : {}; const t = r['totals'] as Record<string, unknown> | undefined;
+      return [...['key', 'responseId', 'turnId', 'turnIndex', 'timestamp', 'payloadDigest', 'source'].map((k) => [k, value(r[k])]),
+        ['totals', ...['input', 'output', 'cachedInput', 'cachedWrite', 'reasoning', 'total'].map((k) => [k, value(t?.[k])])]];
+    }),
+  ]);
+}
+
 /** Structural — a caller passes `cost-scoring.ts`'s `ModelPricing`; kept local so `run-records.ts`
  *  does not have to import `cost-scoring.ts` just to name a type.
  *
@@ -86,6 +103,44 @@ export function parseModelSpec(spec: unknown): ParsedModelSpec | null {
   return null;
 }
 
+/** Internal shared ledger authority resolver; not a package-public barrel API.
+ * Capture/source values are comparison targets and never participate in claimant resolution. */
+export function resolveLedgerModelProvenance(row: Readonly<Record<string, unknown>>) {
+  const diagnostics: string[] = [];
+  const canonicalFamily = (v: string) => v === 'openai' ? 'codex' : v;
+  const direct = typeof row['model'] === 'string' && row['model'].length <= 128 && /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)?$/.test(row['model']) ? row['model'] : null;
+  if (row['model'] != null && direct === null) diagnostics.push('model-invalid-direct');
+  const family = typeof row['family'] === 'string' && SPEC_PART.test(row['family']) ? row['family'] : null;
+  if (row['family'] != null && family === null) diagnostics.push('model-invalid-family');
+  const specs: ParsedModelSpec[] = []; const familyHints: string[] = [];
+  for (const key of ['coder', 'reviewer']) {
+    const raw = row[key]; if (raw == null) continue;
+    if (raw === 'codex' || raw === 'claude') { familyHints.push(raw); continue; }
+    const spec = parseModelSpec(raw);
+    const parts = typeof raw === 'string' ? raw.trim().split(':') : [];
+    if (!spec || !SPEC_PART.test(spec.model) || (parts[0] === 'claude' && parts.length !== 2)) {
+      diagnostics.push('model-invalid-executor:' + key); continue;
+    }
+    specs.push(spec); familyHints.push(spec.family);
+  }
+  const models = new Set(specs.map((v) => v.model)); const families = new Set(familyHints);
+  if (models.size > 1 || families.size > 1) diagnostics.push('model-executor-conflict');
+  const unique = models.size === 1 ? specs[0]! : null;
+  if (direct !== null && unique && direct !== unique.model) diagnostics.push('model-direct-executor-conflict');
+  if (family !== null && [...families].some((v) => canonicalFamily(family) !== v)) diagnostics.push('model-family-conflict');
+  const declaredProvenance = row['modelProvenance'];
+  const validProvenance = new Set(['caller-recorded', 'executor-spec', 'provider-reported', 'dispatcher-reported', 'probed-request', 'not-recorded']);
+  if (declaredProvenance != null && (typeof declaredProvenance !== 'string' || !validProvenance.has(declaredProvenance))) diagnostics.push('model-invalid-provenance');
+  if (declaredProvenance === 'executor-spec' && (!unique || (direct !== null && direct !== unique.model))) diagnostics.push('model-provenance-conflict');
+  if (declaredProvenance != null && declaredProvenance !== 'executor-spec' && declaredProvenance !== 'not-recorded' && direct === null) diagnostics.push('model-provenance-conflict');
+  const conflict = diagnostics.some((d) => /invalid|conflict/.test(d));
+  const model = conflict ? null : direct ?? unique?.model ?? null;
+  if (model === null && !conflict) diagnostics.push('model-not-recorded');
+  const resolvedFamily = family ?? (families.size === 1 ? [...families][0]! : null);
+  return { model, family: resolvedFamily, modelProvenance: model === null ? 'not-recorded' : direct !== null
+    ? typeof declaredProvenance === 'string' ? declaredProvenance : 'caller-recorded' : 'executor-spec', diagnostics };
+}
+
 /** measurement-integrity FR-5/FR-6: enrichment the WRITER supplies at write time — the rollout logs
  *  it already read (I/O lives in the CLI; this stays pure) and the price table snapshot. Absent
  *  entirely ⇒ zero behavior change from before this feature (NFR-1). */
@@ -93,6 +148,9 @@ export interface LedgerEnrichInput {
   /** Parsed Codex rollout logs for the window the CLI read — usually every rollout from the days the
    *  window spans. Pure data; the CLI is the one that walked `~/.codex/sessions`. */
   readonly rollouts?: readonly CodexRollout[];
+  readonly rolloutId?: string;
+  readonly turnId?: string;
+  readonly discoveryDiagnostics?: readonly string[];
   /** The stage's own time window — usually [the previous ledger row's `ts`, this write's `ts`], or
    *  an explicit `--window-from/--window-to`. Omitted ⇒ no rollout match is even attempted. */
   readonly window?: { readonly from: string; readonly to: string };
@@ -492,32 +550,29 @@ export function decideRecordWrite(input: {
     // one that already has a token figure, is left untouched. The loose `/codex/i` check below only
     // decides whether this row is WORTH TRYING at all.
     const tokensIsNull = stamped['tokens'] === null;
-    const looksCodexFamily = isCodexFamily(stamped['coder']) || isCodexFamily(stamped['reviewer']);
-    if (tokensIsNull && looksCodexFamily) {
-      // measurement-integrity fix-round-1/F4 (Codex r1 HIGH #4): the matcher REQUIRES a reliable
-      // model, parsed the same way FR-7's price lookup parses one — never `/codex/i` alone. If
-      // `coder`/`reviewer` do not resolve to exactly ONE codex model between them (a bare `'codex'`
-      // with no model at all, or the two fields naming DIFFERENT codex models), the matcher is never
-      // even called with an unreliable/omitted model filter — a lone rollout in the window would
-      // otherwise be accepted as `'one'` on time+cwd alone and its tokens misattributed to the wrong
-      // model's stage.
-      const codexModels = new Set(
-        [parseModelSpec(stamped['coder']), parseModelSpec(stamped['reviewer'])]
-          .filter((s): s is ParsedModelSpec => s !== null && s.family === 'codex')
-          .map((s) => s.model),
-      );
-      if (codexModels.size !== 1) {
+    const looksCodexFamily = isCodexFamily(stamped['coder']) || isCodexFamily(stamped['reviewer']) || stamped['family'] === 'codex' || stamped['family'] === 'openai';
+    if (enrich.discoveryDiagnostics?.length) {
+      stamped['usageDiagnostics'] = enrich.discoveryDiagnostics;
+      stamped['tokensSource'] = 'codex-rollout:source-discovery-unavailable';
+    } else if ((tokensIsNull || enrich.rolloutId !== undefined || enrich.turnId !== undefined) && looksCodexFamily) {
+      // Use the same authority contract as the readonly source comparison and normalized report.
+      // A direct model or unique agreeing executor specs supply authority; a source never does.
+      const identity = resolveLedgerModelProvenance(stamped);
+      if (identity.model === null || !['codex', 'openai'].includes(identity.family ?? '')) {
         stamped['tokensSource'] = 'codex-rollout:no-model';
-      } else if (enrich.window !== undefined) {
-        const model = [...codexModels][0]!;
+        stamped['usageDiagnostics'] = [...(Array.isArray(stamped['usageDiagnostics']) ? stamped['usageDiagnostics'] : []), ...identity.diagnostics];
+      } else if (enrich.window !== undefined || enrich.rolloutId !== undefined || enrich.turnId !== undefined) {
+        const model = identity.model;
         const match = matchCodexRollouts(enrich.rollouts ?? [], {
-          from: enrich.window.from,
-          to: enrich.window.to,
+          ...(enrich.window !== undefined ? { from: enrich.window.from, to: enrich.window.to } : {}),
           model,
+          ...(enrich.rolloutId !== undefined ? { rolloutId: enrich.rolloutId } : {}),
+          ...(enrich.turnId !== undefined ? { turnId: enrich.turnId } : {}),
           ...(enrich.cwd !== undefined ? { cwd: enrich.cwd } : {}),
         });
         if (match.status === 'one') {
-          stamped['tokens'] = match.rollout.totals.total;
+          if (tokensIsNull || stamped['tokens'] === undefined) stamped['tokens'] = match.rollout.totals.total;
+          else if (stamped['tokens'] !== match.rollout.totals.total) stamped['usageDiagnostics'] = ['caller-source-total-mismatch'];
           const startMs = match.rollout.startedAt !== null ? Date.parse(match.rollout.startedAt) : NaN;
           const endMs = match.rollout.endedAt !== null ? Date.parse(match.rollout.endedAt) : NaN;
           // measurement-integrity fix-round-1/F6 (Codex r1 HIGH #6): fill-ONLY-null — an existing
@@ -528,9 +583,26 @@ export function decideRecordWrite(input: {
           }
           stamped['tokensSource'] = 'codex-rollout';
           stamped['rolloutId'] = match.rollout.id;
+          const found = match.rollout;
+          for (const [key, value] of Object.entries({ tokensTotal: found.totals.total, tokensIn: found.totals.input,
+            tokensOut: found.totals.output, tokensCacheRead: found.totals.cachedInput, tokensCacheWrite: found.totals.cachedWrite ?? null,
+            tokensReasoning: found.totals.reasoning, reportedTotalBasis: 'raw-inclusive', inputCacheSemantics: 'includes-cache-read-write',
+            usageDiagnostics: found.diagnostics ?? [] })) if (stamped[key] === undefined || stamped[key] === null) stamped[key] = value;
+          const receipts = (found.receipts ?? []).map((receipt) => ({ ...receipt, key: JSON.stringify([found.id, receipt.key]) }));
+          const usageEvidence: Record<string, unknown> = { schema: 'codex-rollout-scope-1', sessionId: found.id, turnId: found.turnId ?? null,
+            sourcePath: found.sourcePath ?? null, matchBasis: enrich.rolloutId !== undefined || enrich.turnId !== undefined ? 'exact' : 'legacy-window',
+            capturedFrom: found.startedAt, capturedTo: found.endedAt, receipts, model: found.model, cwd: found.cwd,
+            owner: Object.fromEntries(['runId', 'taskId', 'stage', 'attempt', 'role'].map((key) => [key, stamped[key] ?? null])),
+            reportedTotalBasis: 'raw-inclusive', inputCacheSemantics: 'includes-cache-read-write',
+            payloadDigest: fnv1a64(JSON.stringify(receipts.map((r) => [r.key, r.payloadDigest]))) };
+          usageEvidence['captureSha256'] = createHash('sha256').update(capturedPayload(usageEvidence)).digest('hex');
+          if (JSON.stringify(usageEvidence).length <= 16000) {
+            if (stamped['usageEvidence'] === undefined || stamped['usageEvidence'] === null) stamped['usageEvidence'] = usageEvidence;
+          } else stamped['usageDiagnostics'] = [...(Array.isArray(stamped['usageDiagnostics']) ? stamped['usageDiagnostics'] : []), 'source-scope-over-record-limit'];
+
         } else {
           // `none` or `ambiguous` — NFR-3: an explicit status, never a guessed number.
-          stamped['tokensSource'] = `codex-rollout:${match.status}`;
+          stamped['tokensSource'] = `codex-rollout:${enrich.rolloutId !== undefined || enrich.turnId !== undefined ? 'exact-' : ''}${match.status}`;
         }
       } else {
         // Eligible in principle (codex family, one reliable model, tokens null) but no window was
@@ -544,6 +616,7 @@ export function decideRecordWrite(input: {
     // above (a Claude row gets priced too; only tokens enrichment is codex-specific).
     if (enrich.prices !== undefined) {
       const modelIds = new Set<string>();
+      if (typeof stamped['model'] === 'string' && stamped['model'].trim()) modelIds.add(stamped['model'].trim());
       for (const v of [stamped['coder'], stamped['reviewer']]) {
         if (typeof v === 'string' && v.trim() !== '') modelIds.add(v.trim());
       }
@@ -566,7 +639,13 @@ export function decideRecordWrite(input: {
         if (price === null) unknown.push(modelId);
         else table[modelId] = { prompt: price.prompt, completion: price.completion, cachedInput: price.cachedInput, cacheCreation: price.cacheCreation };
       }
+      const matches = Object.fromEntries([...modelIds].map((id) => {
+        const parsed = parseModelSpec(id); const normalized = parsed?.family === 'claude' ? 'claude-' + parsed.model : parsed?.model ?? id;
+        const key = Object.keys(enrich.prices ?? {}).filter((k) => normalized.toLowerCase().startsWith(k)).sort((a,b) => b.length-a.length)[0] ?? null;
+        return [id, { tableKey: key, kind: key !== null && key === normalized && !key.includes('claude') ? 'exact' : key !== null ? 'family-estimate' : 'unknown' }];
+      }));
       const computedPrices = {
+        matches,
         snapshotAt: input.timestamp ?? null,
         table,
         ...(unknown.length > 0 ? { unknown } : {}),

package/src/session-retro.ts

@@ -14,9 +14,10 @@
  * is taught silently but NOT drilled — no nagging on a one-off. Drills are for recurrent patterns only.
  */
 
-import { existsSync, readFileSync, readdirSync, statSync, openSync, readSync, closeSync, writeFileSync, renameSync, unlinkSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync, openSync, readSync, closeSync, writeFileSync, renameSync, unlinkSync, mkdirSync, rmSync } from 'node:fs';
 import { join, basename, dirname } from 'node:path';
 import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
 
 import { withProjectLockSync, NamedLockTimeoutError } from './named-lock.js';
 
@@ -538,11 +539,62 @@ export function findLatestTranscript(repoRoot: string): string | null {
 // ── Per-turn admission-debt scan (feature narrated-error-must-be-taught, ADR-001 D2/D4) ────────────
 // The Stop hook runs `dz retro --scan-tail` after EVERY assistant turn, so this half is built around
 // one budget: O(new bytes) — a persisted byte offset, no full re-read, no store open, no subprocess.
-// The sentinel `.dz/retro-pending.json` is the debt; the recall hook turns it into a next-prompt
-// directive; a REAL teach invocation (a TOOL event — prose promises never pay, ADR-001 D4) clears it.
+// The sentinel `.dz/retro/<session>/pending.json` is the debt; the recall hook turns it into a
+// next-prompt directive; a REAL teach invocation (a TOOL event — prose promises never pay, ADR-001 D4)
+// clears it.
 
+/** LEGACY flat names (pre retro-debt-sentinel-per-session): the ONE pair every session in a worktree
+ * once shared under `.dz/`. A scan ADOPTS its own transcript's flat files once (FR-4) and never
+ * writes them again; a stranger's flat file is never touched. */
 export const RETRO_SCAN_STATE_FILE = 'retro-scan-state.json';
 export const RETRO_PENDING_FILE = 'retro-pending.json';
+
+// ── Per-session layout (feature retro-debt-sentinel-per-session, FR-1; backlog 58f3c56fbb9d6893) ──
+// Two sessions in one worktree shared the flat pair above, so a Stop scan of EITHER unlinked the
+// other's LIVE debt as "foreign", and the shared bookmark made each session's offset meaningless to
+// the other (foreign transcript ⇒ offset 0 ⇒ a bounded re-scan every turn; MEASURED 22.09 20:23, a
+// second session in this repo). The pair now lives in a directory named after the session.
+export const RETRO_SESSION_DIRNAME = 'retro';
+export const RETRO_SESSION_PENDING_BASENAME = 'pending.json';
+export const RETRO_SESSION_STATE_BASENAME = 'scan-state.json';
+/** A session dir whose scan-state is older than this belongs to a dead session: the next scan of
+ * any other session sweeps it (FR-5). A live session that ran no Stop for 7 days loses only a debt
+ * the hook would have called stale anyway (SENTINEL_FRESH_MS is 30 min) — accepted risk R2. */
+export const RETRO_SESSION_STALE_MS = 7 * 24 * 3600 * 1000;
+/** At most this many `.dz/retro/*` entries are examined per scan — the sweep's cost bound (NFR-1). */
+const RETRO_SWEEP_MAX_ENTRIES = 64;
+const SAFE_SESSION_ID_RE = /^[A-Za-z0-9._-]{1,128}$/;
+
+/**
+ * The directory name for a session id. PURE. A plain token is used as is; anything else — a
+ * path-like string, the empty string, an over-long id, and the two dot names the charset regex
+ * alone would let through (`.` ⇒ `<dzDir>/retro`, `..` ⇒ `<dzDir>` itself) — becomes the first
+ * 32 hex of its sha256, so a session id can never name a path outside `.dz/retro/` (AC-2).
+ * TWIN: the recall hook in `apply-leg.ts` carries a copy (the hook must stay dependency-free);
+ * `test/retro-sentinel-per-session.test.ts` pins the two to equal outputs.
+ */
+export function safeSessionDirName(sessionId: string): string {
+  if (SAFE_SESSION_ID_RE.test(sessionId) && sessionId !== '.' && sessionId !== '..') return sessionId;
+  return createHash('sha256').update(sessionId).digest('hex').slice(0, 32);
+}
+
+/** The session id the SCANNER derives: the transcript basename without `.jsonl`. Claude Code names
+ * the transcript after the session id, so this equals the `session_id` the hook payload carries. PURE. */
+export function sessionIdFromTranscript(transcriptPath: string): string {
+  return basename(transcriptPath).replace(/\.jsonl$/, '');
+}
+
+export interface RetroSessionPaths {
+  readonly dir: string;
+  readonly pendingPath: string;
+  readonly statePath: string;
+}
+
+/** Where ONE session's debt and bookmark live: `<dzDir>/retro/<safeId>/{pending,scan-state}.json`. PURE, no fs. */
+export function retroSessionPaths(dzDir: string, sessionId: string): RetroSessionPaths {
+  const dir = join(dzDir, RETRO_SESSION_DIRNAME, safeSessionDirName(sessionId));
+  return { dir, pendingPath: join(dir, RETRO_SESSION_PENDING_BASENAME), statePath: join(dir, RETRO_SESSION_STATE_BASENAME) };
+}
 /** Bound the very FIRST scan of an already-huge transcript; later scans read only the new bytes. */
 const MAX_TAIL_SCAN_BYTES = 8 * 1024 * 1024;
 /** Without a session id to compare, a sentinel older than this is stale (fallback freshness only). */
@@ -628,6 +680,10 @@ export interface TailScanOutcome {
   readonly snippet?: string;
   readonly scannedBytes: number;
   readonly offset: number;
+  /** The session the scan was scoped to (FR-6) — absent only when no transcript was named. */
+  readonly sessionId?: string;
+  /** The per-session sentinel path the scan wrote, cleared, or left absent (FR-6). */
+  readonly pendingPath?: string;
 }
 
 /** The scan-state + sentinel pair is a read-modify-write store; per the repo concurrency rule
@@ -728,6 +784,8 @@ const writeJsonAtomic = (path: string, value: unknown): void => {
  */
 export function runRetroTailScan(dzDir: string, transcriptPath: string | null, nowIso?: string): TailScanOutcome {
   if (transcriptPath === null || transcriptPath === '') return { status: 'no-transcript', scannedBytes: 0, offset: 0 };
+  const sessionId = sessionIdFromTranscript(transcriptPath);
+  const ids = { sessionId, pendingPath: retroSessionPaths(dzDir, sessionId).pendingPath };
   try {
     return withProjectLockSync(
       dirname(dzDir),
@@ -736,43 +794,71 @@ export function runRetroTailScan(dzDir: string, transcriptPath: string | null, n
       { timeoutMs: RETRO_SCAN_LOCK_TIMEOUT_MS },
     );
   } catch (e) {
-    if (e instanceof NamedLockTimeoutError) return { status: 'contended', scannedBytes: 0, offset: 0 };
+    if (e instanceof NamedLockTimeoutError) return { status: 'contended', scannedBytes: 0, offset: 0, ...ids };
     // Compromised lock or any unexpected failure: report nothing, advance nothing (never-block).
-    return { status: 'none', scannedBytes: 0, offset: 0 };
+    return { status: 'none', scannedBytes: 0, offset: 0, ...ids };
   }
 }
 
 /** The transaction body — call ONLY under the named lock. Never throws for ordinary fs failures. */
 function scanTailUnderLock(dzDir: string, transcriptPath: string, nowIso?: string): TailScanOutcome {
+  // FR-2: every path this scan writes or removes is inside ITS OWN session dir; the only files it
+  // ever touches outside are the legacy flat pair, and only to adopt its own (FR-4).
+  const sessionId = sessionIdFromTranscript(transcriptPath);
+  const { dir, pendingPath, statePath } = retroSessionPaths(dzDir, sessionId);
+  const ids = { sessionId, pendingPath };
   try {
-    const statePath = join(dzDir, RETRO_SCAN_STATE_FILE);
-    const pendingPath = join(dzDir, RETRO_PENDING_FILE);
+    const legacyStatePath = join(dzDir, RETRO_SCAN_STATE_FILE);
+    const legacyPendingPath = join(dzDir, RETRO_PENDING_FILE);
 
+    const readOffset = (p: string): number | null => {
+      try {
+        const st = JSON.parse(readFileSync(p, 'utf8')) as { transcript?: string; offset?: number };
+        if (st.transcript === transcriptPath && typeof st.offset === 'number' && Number.isFinite(st.offset) && st.offset >= 0) return Math.floor(st.offset);
+      } catch { /* absent or unreadable */ }
+      return null;
+    };
     let offset = 0;
-    try {
-      const st = JSON.parse(readFileSync(statePath, 'utf8')) as { transcript?: string; offset?: number };
-      if (st.transcript === transcriptPath && typeof st.offset === 'number' && Number.isFinite(st.offset) && st.offset >= 0) offset = Math.floor(st.offset);
-    } catch { /* first scan of this transcript */ }
-
-    // Prior debt carries over ONLY for the same session; a stale sentinel (another session's debt)
-    // is dropped — the PreCompact/SessionEnd retro of THAT session was its collector, and injecting
-    // an old session's debt into a new one is noise (acid A9).
-    let prior: AdmissionDebt | null = null;
-    let hadSentinel = false;
-    try {
-      const s = JSON.parse(readFileSync(pendingPath, 'utf8')) as Partial<RetroPendingSentinel>;
-      if (s.transcript === transcriptPath && typeof s.snippet === 'string') {
-        prior = { snippet: s.snippet, ...(s.awaiting !== undefined ? { awaiting: s.awaiting } : {}) };
-        hadSentinel = true;
-      }
-      else { try { unlinkSync(pendingPath); } catch { /* already gone */ } }
-    } catch { /* no sentinel */ }
+    let adoptLegacyState = false;
+    const ownOffset = readOffset(statePath);
+    if (ownOffset !== null) offset = ownOffset;
+    else if (!existsSync(statePath)) {
+      // FR-4: the flat bookmark is adopted ONCE — only while this session has no bookmark of its own,
+      // and only when it names THIS transcript. Another session's stays where it is.
+      const legacyOffset = readOffset(legacyStatePath);
+      if (legacyOffset !== null) { offset = legacyOffset; adoptLegacyState = true; }
+    }
+
+    const readSentinel = (p: string): { prior: AdmissionDebt | null; present: boolean } => {
+      try {
+        const s = JSON.parse(readFileSync(p, 'utf8')) as Partial<RetroPendingSentinel>;
+        if (s.transcript === transcriptPath && typeof s.snippet === 'string') {
+          return { prior: { snippet: s.snippet, ...(s.awaiting !== undefined ? { awaiting: s.awaiting } : {}) }, present: true };
+        }
+        return { prior: null, present: true };
+      } catch { return { prior: null, present: false }; }
+    };
+    // Prior debt: this session's own sentinel. One naming ANOTHER transcript can only mean the
+    // transcript was moved or renamed under the same basename — it is IGNORED and overwritten (or
+    // removed below when nothing is armed), never deleted as "foreign": the pre-feature branch that
+    // unlinked a sentinel of another transcript deleted the NEIGHBOUR session's live debt (FR-2).
+    const own = readSentinel(pendingPath);
+    let prior = own.prior;
+    const staleOwn = own.present && own.prior === null;
+    let adoptLegacyPending = false;
+    if (!own.present) {
+      // FR-4: the flat sentinel is adopted only when it is THIS transcript's and this session has no
+      // per-session copy yet; a stranger's, or a nobody's (no transcript field), is left untouched.
+      const legacy = readSentinel(legacyPendingPath);
+      if (legacy.prior !== null) { prior = legacy.prior; adoptLegacyPending = true; }
+    }
+    const hadSentinel = prior !== null;
 
     let size = 0;
     try { size = statSync(transcriptPath).size; } catch {
       return prior !== null
-        ? { status: 'pending', snippet: prior.snippet, scannedBytes: 0, offset }
-        : { status: 'none', scannedBytes: 0, offset };
+        ? { status: 'pending', snippet: prior.snippet, scannedBytes: 0, offset, ...ids }
+        : { status: 'none', scannedBytes: 0, offset, ...ids };
     }
     if (size < offset) offset = 0;                                        // truncated/rotated transcript
     let jumped = offset === 0 && size > MAX_TAIL_SCAN_BYTES;              // bound the first scan of a huge file
@@ -802,12 +888,12 @@ function scanTailUnderLock(dzDir: string, transcriptPath: string, nowIso?: strin
 
     const next = foldAdmissionDebt(events, prior);
     const newOffset = offset + consumed;
-    mkdirSync(dzDir, { recursive: true });
+    mkdirSync(dir, { recursive: true });
     let outcome: TailScanOutcome;
     if (next !== null) {
       const sentinel: RetroPendingSentinel = {
         schema: 1,
-        sessionId: basename(transcriptPath).replace(/\.jsonl$/, ''),
+        sessionId,
         transcript: transcriptPath,
         snippet: next.snippet.replace(/\s+/g, ' ').trim().slice(0, 200),
         ts: nowIso ?? new Date().toISOString(),
@@ -826,13 +912,45 @@ function scanTailUnderLock(dzDir: string, transcriptPath: string, nowIso?: strin
       catch (e) { if ((e as NodeJS.ErrnoException).code !== 'ENOENT') throw e; }
       outcome = { status: 'cleared', scannedBytes: consumed, offset: newOffset };
     } else {
+      // Our own stale sentinel (moved transcript, see above) with nothing armed: removed, so the hook
+      // never confronts a debt this transcript no longer carries. Same ENOENT-only tolerance.
+      if (staleOwn) {
+        try { unlinkSync(pendingPath); }
+        catch (e) { if ((e as NodeJS.ErrnoException).code !== 'ENOENT') throw e; }
+      }
       outcome = { status: 'none', scannedBytes: consumed, offset: newOffset };
     }
     // Commit the debt BEFORE its offset: an interruption must leave these bytes replayable.
     writeJsonAtomic(statePath, { schema: 1, transcript: transcriptPath, offset: newOffset });
-    return outcome;
+    // FR-4: the adopted flat files go only AFTER the per-session copies are committed — a failure
+    // above leaves them in place for the next scan to adopt again. Best-effort: leftover debris
+    // is harmless (a present per-session file blocks re-adoption), a thrown error here would
+    // misreport an already-committed scan.
+    if (adoptLegacyPending) { try { unlinkSync(legacyPendingPath); } catch { /* debris */ } }
+    if (adoptLegacyState) { try { unlinkSync(legacyStatePath); } catch { /* debris */ } }
+    sweepStaleSessionDirs(dzDir, dir, nowIso === undefined ? Date.now() : Date.parse(nowIso));
+    return { ...outcome, ...ids };
   } catch {
-    return { status: 'none', scannedBytes: 0, offset: 0 };
+    return { status: 'none', scannedBytes: 0, offset: 0, ...ids };
+  }
+}
+
+/**
+ * FR-5: remove dead sessions' dirs — `<dzDir>/retro/<x>/` whose `scan-state.json` mtime is older
+ * than {@link RETRO_SESSION_STALE_MS}. The scanning session's own dir is excluded; a dir with no
+ * readable scan-state cannot be dated and is left alone; every error is swallowed; at most
+ * {@link RETRO_SWEEP_MAX_ENTRIES} entries are examined (one readdir + ≤64 stats — NFR-1).
+ */
+function sweepStaleSessionDirs(dzDir: string, ownDir: string, nowMs: number): void {
+  let names: string[];
+  try { names = readdirSync(join(dzDir, RETRO_SESSION_DIRNAME)).slice(0, RETRO_SWEEP_MAX_ENTRIES); } catch { return; }
+  for (const name of names) {
+    const d = join(dzDir, RETRO_SESSION_DIRNAME, name);
+    if (d === ownDir) continue;
+    try {
+      const age = nowMs - statSync(join(d, RETRO_SESSION_STATE_BASENAME)).mtimeMs;
+      if (age > RETRO_SESSION_STALE_MS) rmSync(d, { recursive: true, force: true });
+    } catch { /* undatable or vanished: leave it */ }
   }
 }
 
@@ -851,6 +969,10 @@ export function retroSentinelIsFresh(
   ctx: { sessionId?: string; transcriptPath?: string; nowMs: number },
 ): boolean {
   if (typeof sentinel.snippet !== 'string' || sentinel.snippet === '') return false;
+  // AM-1 (retro-debt-sentinel-per-session): an EMPTY session id carries no identity — a sentinel that
+  // names no session never matches anyone, and an empty ctx id is the same as none (the hook side
+  // returns '' before any fs call for it; this is the core half of the same rule).
+  if (sentinel.sessionId === '') return false;
   if (typeof ctx.sessionId === 'string' && ctx.sessionId !== '') return sentinel.sessionId === ctx.sessionId;
   if (typeof ctx.transcriptPath === 'string' && ctx.transcriptPath !== '') return sentinel.transcript === ctx.transcriptPath;
   const ts = typeof sentinel.ts === 'string' ? Date.parse(sentinel.ts) : NaN;