@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/hooks/orchestration_record_hook.ts

@@ -68,7 +68,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { buildOrchestrationLine, type RecordInput } from '../_lib/orchestration_record.js';
+import { TIER_TO_CLAUDE_MODEL } from '../_lib/model_tier.js';
+import { buildOrchestrationLine, type RecordInput, type TierChosen } from '../_lib/orchestration_record.js';
 import { DEFAULT_DIR } from '../orchestration_record.js';
 import { is_replay_mode } from './state_io.js';
 import { readHookStdin } from './hook_stdin.js';
@@ -137,6 +138,10 @@ export interface DispatchFacts {
     returnChannelChars: number | null;
     isAsync: boolean;
     isError: boolean;
+    /** The per-call `model` argument of the dispatch, verbatim; null when it carried none. */
+    requestedModel?: string | null;
+    /** The model id of the head's latest assistant call, read from its transcript tail. */
+    sessionModel?: string | null;
 }
 
 function numOrNull(v: JsonValue | undefined): number | null {
@@ -215,9 +220,71 @@ export function extractDispatchFacts(payload: JsonObject): DispatchFacts {
         }
     }
 
-    return { subagentType, resolvedModel, totalTokens, totalDurationMs, returnChannelChars, isAsync, isError };
+    const requestedModel = input && typeof input['model'] === 'string' && input['model'] ? (input['model'] as string) : null;
+    const sessionModel = lastAssistantModel(payload['transcript_path']);
+
+    return {
+        subagentType,
+        resolvedModel,
+        totalTokens,
+        totalDurationMs,
+        returnChannelChars,
+        isAsync,
+        isError,
+        requestedModel,
+        sessionModel,
+    };
 }
 
+const TRANSCRIPT_TAIL_BYTES = 256 * 1024;
+
+/**
+ * The `model` of the last assistant line in a host transcript, read from its
+ * tail only. The path is host-supplied: anything but an existing `.jsonl`
+ * regular file is not read, and only a model id leaves this function.
+ */
+function lastAssistantModel(transcriptPath: JsonValue | undefined): string | null {
+    if (typeof transcriptPath !== 'string' || !path.isAbsolute(transcriptPath) || !transcriptPath.endsWith('.jsonl')) {
+        return null;
+    }
+    let fd: number | null = null;
+    try {
+        const st = fs.statSync(transcriptPath);
+        if (!st.isFile()) return null;
+        const len = Math.min(st.size, TRANSCRIPT_TAIL_BYTES);
+        const buf = Buffer.alloc(len);
+        fd = fs.openSync(transcriptPath, 'r');
+        fs.readSync(fd, buf, 0, len, st.size - len);
+        const lines = buf.toString('utf8').split('\n');
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const line = lines[i]!;
+            if (!line.includes('"assistant"')) continue;
+            try {
+                const rec = JSON.parse(line) as JsonObject;
+                const msg = rec['message'];
+                if (rec['type'] === 'assistant' && isObject(msg) && typeof msg['model'] === 'string') return msg['model'];
+            } catch {
+                // A line cut by the tail window, or not JSON.
+            }
+        }
+    } catch {
+        return null;
+    } finally {
+        if (fd !== null) fs.closeSync(fd);
+    }
+    return null;
+}
+
+/** The tier whose model family a model id or alias names, via the one tier→model map. */
+function tierForModel(model: string | null | undefined): string | null {
+    if (model == null) return null;
+    const family = extractModelFamily(model);
+    if (family === null) return null;
+    return Object.entries(TIER_TO_CLAUDE_MODEL).find(([, m]) => m === family)?.[0] ?? null;
+}
+
+const CHOSEN_TIERS: readonly string[] = ['lite', 'medium', 'high'];
+
 /**
  * Build the `RecordInput` for one dispatch-completion event. Pure — no I/O,
  * no `Date.now()` / random call inside (both are supplied by the caller so
@@ -238,6 +305,17 @@ export function buildRecordInput(facts: DispatchFacts, ts: string, id: string):
         id,
     };
     if (facts.subagentType) input.agent_combo = [facts.subagentType];
+
+    const requestedTier = tierForModel(facts.requestedModel);
+    if (facts.requestedModel != null) input.model_requested = facts.requestedModel;
+    if (requestedTier !== null && CHOSEN_TIERS.includes(requestedTier)) {
+        input.tier_chosen = requestedTier as TierChosen;
+        input.tier_source = 'static';
+    } else if (facts.requestedModel == null) {
+        input.tier_source = 'inherit';
+    }
+    const sessionTier = tierForModel(facts.sessionModel);
+    if (sessionTier !== null) input.session_tier = sessionTier;
     if (facts.isError) input.dispatch_outcome = 'killed';
 
     if (!facts.isAsync) {

package/src/scripts/hooks/payload_stub.ts

@@ -389,8 +389,11 @@ export function _concern_body_classes(concern: JsonObject): Set<BodyClass> {
 
 /** The per-dispatch shaping plan. Built once, read per concern. */
 export interface PayloadShapePlan {
-  /** The envelope a concern with this keep-set receives. */
-  shapeFor(keep: ReadonlySet<BodyClass>): JsonObject;
+  /**
+   * The envelope a concern with this keep-set receives, built from the
+   * placeholder view when one was planned and `view` asks for it.
+   */
+  shapeFor(keep: ReadonlySet<BodyClass>, view?: "execution" | "placeholder"): JsonObject;
   /** How many payload keys were omitted for that concern. */
   stubsFor(keep: ReadonlySet<BodyClass>): number;
   /** The classes actually SERVED — declared AND present. Sorted. */
@@ -416,10 +419,16 @@ export interface PayloadShapePlan {
  * Extracted from the dispatcher loop rather than inlined there: the decision
  * has four moving parts that are only correct together, and the source-size
  * ratchet was right to object to a dispatcher carrying them.
+ *
+ * `placeholder` is the egress stage's placeholder view of the same envelope.
+ * Presence and byte lengths are always read from the received envelope, so a
+ * stub reports the size the host sent whichever view it was cut from; only
+ * the body that survives differs between the two views.
  */
 export function planPayloadShapes(
   envelope: JsonObject,
   keepSets: Iterable<ReadonlySet<BodyClass>>,
+  placeholder?: JsonObject,
 ): PayloadShapePlan {
   const present = presentBodyClasses(envelope);
   const stubbedSomewhere = new Set<BodyClass>();
@@ -436,12 +445,13 @@ export function planPayloadShapes(
   const cacheKey = (keep: ReadonlySet<BodyClass>): string =>
     [...keep].sort().join(",");
   return {
-    shapeFor(keep) {
-      if (present.size === 0) return envelope;
-      const key = cacheKey(keep);
+    shapeFor(keep, view = "execution") {
+      const base = view === "placeholder" && placeholder !== undefined ? placeholder : envelope;
+      if (present.size === 0) return base;
+      const key = `${base === envelope ? "execution" : "placeholder"}:${cacheKey(keep)}`;
       const hit = shaped.get(key);
       if (hit !== undefined) return hit;
-      const built = stubPayloadBodies(envelope, keep, measured);
+      const built = stubPayloadBodies(base, keep, measured);
       shaped.set(key, built);
       return built;
     },

package/src/scripts/hooks/permission_gate.ts

@@ -14,7 +14,7 @@
  * concerns and reduces exit codes, this module reads the result and decides
  * what the host is told about permission.
  */
-import { isCategoryA, type ToolInput } from "./category_a.js";
+import { categoryAVerdict, type ToolInput } from "./category_a.js";
 import {
   composePermissionDecision,
   type PermissionDecision,
@@ -104,13 +104,13 @@ export function _permission_for(
   if (final_rc !== EXIT_ALLOW) return null;
   if (composePermissionDecision(verdicts) !== "allow") return null;
   const tool_name = _payload_tool_name(envelope);
-  if (!isCategoryA(tool_name, _payload_tool_input(envelope), _working_tree_root(envelope))) {
-    return null;
-  }
+  const verdict = categoryAVerdict(tool_name, _payload_tool_input(envelope), _working_tree_root(envelope));
+  if (!verdict.categoryA) return null;
+  // The reason may only name a check that ran for this call: a bare `pwd`
+  // had no path argument to confine, so it must not claim it was confined.
+  const where = verdict.confined ? " inside the working tree" : ", no path argument to confine";
   return {
     decision: "allow",
-    reason:
-      `agent-config: category-A ${tool_name} inside the working tree — ` +
-      `no concern gates it and none asked to.`,
+    reason: `agent-config: category-A ${tool_name}${where} — no concern gates it and none asked to.`,
   };
 }

package/src/scripts/hooks/push_settle_hook.ts

@@ -55,6 +55,7 @@ import { execFileSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { readHookStdin } from "./hook_stdin.js";
 import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
+import { writeMergeMarker } from "../retro_queue.js";
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };
@@ -171,13 +172,21 @@ export function resolvePr(
   }
 }
 
+/**
+ * How a consumer reaches the waiter. A project-local install puts the binary in
+ * `node_modules/.bin`, which is not on an ordinary shell's PATH; `npm exec --no`
+ * resolves that, a global install and the package's own checkout alike, and
+ * `--no` refuses to fetch an unrelated registry package named `agent-config`.
+ */
+export const CI_SETTLE_INVOCATION = "npm exec --no -- agent-config ci:settle";
+
 /** The reminder text. Split out so the test can read it without a `gh` on PATH. */
 export function buildReminder(branch: string, pr: number | null): { reason: string; additional_context: string } {
   const settle =
     pr === null
       ? `gh pr view ${branch} --json number -q .number   # then:\n` +
-        `./scripts-run src/scripts/ci_settle <that number>`
-      : `./scripts-run src/scripts/ci_settle ${pr}`;
+        `${CI_SETTLE_INVOCATION} <that number>`
+      : `${CI_SETTLE_INVOCATION} ${pr}`;
   const subject = pr === null ? `branch ${branch}` : `PR #${pr} (${branch})`;
   const reason =
     `Pushed ${subject} — the turn is not finished until its CI has settled green ` +
@@ -205,6 +214,24 @@ export function buildReminder(branch: string, pr: number | null): { reason: stri
   return { reason, additional_context };
 }
 
+/**
+ * Path B of the retro (`docs/contracts/retro-v1.md`): a push that resolved a
+ * PR leaves a marker, so a later merge through the web UI, by automerge or by
+ * someone else is found by the daily probe even though no session existed at
+ * merge time. Off with `retro.enabled: false`; best effort, never a block.
+ */
+export function recordMergeMarker(envelope: JsonObject, pr: number | null, branch: string): void {
+  if (pr === null) return;
+  const root = typeof envelope["workspace_root"] === "string" && envelope["workspace_root"] !== ""
+    ? envelope["workspace_root"]
+    : process.cwd();
+  try {
+    writeMergeMarker(root, { pr, branch }, new Date().toISOString());
+  } catch {
+    // a marker that cannot be written costs one retro, never the push reminder
+  }
+}
+
 export function main(): number {
   let envelope: JsonValue;
   try {
@@ -225,7 +252,9 @@ export function main(): number {
   const branch = pushedBranch(toolOutput(inner));
   if (branch === null) return EXIT_ALLOW; // up-to-date, rejected, delete — nothing advanced
 
-  const { reason, additional_context } = buildReminder(branch, resolvePr(branch));
+  const pr = resolvePr(branch);
+  recordMergeMarker(envelope, pr, branch);
+  const { reason, additional_context } = buildReminder(branch, pr);
   process.stdout.write(`${JSON.stringify({ decision: "warn", reason, additional_context })}\n`);
   return EXIT_WARN;
 }

package/src/scripts/hooks/replay_hook.ts

@@ -37,6 +37,15 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { EXIT_USAGE } from './exit_codes.js';
+import {
+  countEnvelope,
+  ENGINE_UNAVAILABLE,
+  readEgressMode,
+  type EgressCount,
+  type EgressMode,
+  type EgressRefusal,
+} from "./egress_stage.js";
+import type { JsonObject } from "./payload_stub.js";
 
 // src/scripts/hooks/replay_hook.ts → parents[3] is the repo root.
 const REPO_ROOT = path.resolve(
@@ -208,6 +217,8 @@ export function main(argv?: string[]): number {
     return 2;
   }
 
+  const egress = _egressPreview(decoded);
+
   const env = { ...process.env };
   env[REPLAY_ENV_VAR] = "1";
 
@@ -253,6 +264,7 @@ export function main(argv?: string[]): number {
       dispatcher_stdout: (proc.stdout || "").trim(),
       dispatcher_stderr: (proc.stderr || "").trim(),
       replay_mode: true,
+      egress,
     };
     process.stdout.write(_py_json_dumps(summary, 2) + "\n");
   } else {
@@ -267,10 +279,41 @@ export function main(argv?: string[]): number {
         `payload=${path.basename(payload_path)} rc=${returncode} ` +
         `(AGENT_CONFIG_REPLAY=1, no writes)\n`,
     );
+    const found = egress.counts.map((c) => `${c.field}:${c.type}×${c.count}`).join(" ") || "nothing";
+    process.stderr.write(
+      `replay_hook: egress mode=${egress.mode} action=${egress.action} found=${found}` +
+        (egress.refused.length > 0 ? ` refused=${egress.refused.map((x) => x.rule).join(",")}` : "") +
+        "\n",
+    );
   }
   return returncode;
 }
 
+/**
+ * What the egress stage would do with this payload under the workspace's
+ * mode: counts and refusals by type, never a value. Pure — no state written.
+ */
+export function _egressPreview(decoded: unknown): {
+  mode: EgressMode;
+  action: "none" | "count" | "replace";
+  counts: readonly EgressCount[];
+  refused: readonly EgressRefusal[];
+} {
+  const mode = readEgressMode(process.cwd());
+  const isObj = decoded !== null && typeof decoded === "object" && !Array.isArray(decoded);
+  let counted: Pick<ReturnType<typeof countEnvelope>, "counts" | "refused"> = { counts: [], refused: [] };
+  if (isObj) {
+    try {
+      counted = countEnvelope({ payload: decoded as JsonObject });
+    } catch {
+      // The engine did not load: say so rather than reporting zero findings.
+      counted = { counts: [], refused: [{ field: "prompt", rule: ENGINE_UNAVAILABLE }] };
+    }
+  }
+  const action = mode === "off" ? "none" : mode === "observe" ? "count" : "replace";
+  return { mode, action, counts: counted.counts, refused: counted.refused };
+}
+
 // Python json.dumps(summary, indent=2) byte-for-byte (ensure_ascii=True).
 function _py_json_dumps(value: unknown, indent: number): string {
   const pad = " ".repeat(indent);

package/src/scripts/hooks/reread_guard_hook.ts

@@ -6,7 +6,9 @@
  * Two signals, one session-scoped read ledger:
  *
  *   6.1 A full-file `Read` of a path that was ALREADY fully read this session
- *       AND is unchanged since (mtime + size compare against the ledger) gets
+ *       AND whose content is unchanged since (sha256 compare against the
+ *       ledger; above HASH_BOUND_BYTES, mtime + size, said so in the line; a
+ *       file under the bound without both digests never fires) gets
  *       one advisory line naming the earlier read and the ranged-read
  *       alternative. A ranged read (any `offset`/`limit` in the tool input)
  *       is already the cheap form and never fires — nor is it recorded as a
@@ -21,8 +23,8 @@
  * `<workspace_root>/agents/runtime/state/reread-guard/<sha256(session)>.json`
  * (gitignored — `agents/runtime/` is blanket-ignored), keyed by session id
  * the same way `end_review_nudge_hook.deriveSessionKey` does (hashed, never
- * raw). Per path it stores `{mtime, size, ts}` for reads, a `ts` for the last
- * own write, and a per-path fired flag — NO field can hold file content, by
+ * raw). Per path it stores `{mtime, size, ts, sha256?}` for reads, a `ts` for the last
+ * own write, and a per-path fired flag — numbers and a digest; NO field can hold file content, by
  * construction (same PII/content-exclusion-by-construction discipline as the
  * telemetry schemas).
  *
@@ -105,11 +107,81 @@ export function isExemptPath(filePath: string): boolean {
     return EXEMPT_PATH_PATTERNS.some((re) => re.test(normalized));
 }
 
-/** Per-path read record — NUMBERS ONLY (mtime ms, byte size, epoch-ms ts). */
+/** Per-path read record — numbers and a digest, never content. */
 export interface ReadRecord {
     mtime: number;
     size: number;
     ts: number;
+    /** sha256 of the file; absent above {@link HASH_BOUND_BYTES}, on a read failure, or in a legacy entry. */
+    sha256?: string;
+}
+
+/**
+ * Above this size the guard keeps mtime + size and says so: the
+ * hash is a full read of the file on the pre_tool_use path.
+ */
+export const HASH_BOUND_BYTES = 2 * 1024 * 1024;
+
+/**
+ * What the content key could say about one read. Only `over-bound` — the stat
+ * itself was over — licenses the stat fallback: after `grew-during-read` the
+ * stat pair is stale, and after `unreadable` nothing was compared.
+ */
+export type Digest =
+    | { kind: 'sha256'; value: string }
+    | { kind: 'over-bound' }
+    | { kind: 'grew-during-read' }
+    | { kind: 'unreadable' };
+
+/**
+ * sha256 of a file at or under the bound. The stat `size` skips the read when it
+ * is already over; the read itself stops at `HASH_BOUND_BYTES + 1`, because the
+ * file can grow between the stat and the read.
+ */
+export function contentDigest(absPath: string, size: number): Digest {
+    if (size > HASH_BOUND_BYTES) return { kind: 'over-bound' };
+    let fd: number | undefined;
+    try {
+        fd = fs.openSync(absPath, 'r');
+        // Sized to the stat, not the bound: a full 2 MB buffer per small Read
+        // is the hottest slot's largest cost. One byte over the stat size is
+        // enough to see that the file grew, which voids the stat pair anyway.
+        const limit = Math.max(0, Math.min(size, HASH_BOUND_BYTES));
+        const buf = Buffer.allocUnsafe(limit + 1);
+        let filled = 0;
+        while (filled < buf.length) {
+            const n = fs.readSync(fd, buf, filled, buf.length - filled, null);
+            if (n === 0) break;
+            filled += n;
+        }
+        if (filled > limit) return { kind: 'grew-during-read' };
+        return { kind: 'sha256', value: crypto.createHash('sha256').update(buf.subarray(0, filled)).digest('hex') };
+    } catch {
+        return { kind: 'unreadable' };
+    } finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            } catch {
+                // closing a descriptor we opened cannot change the answer
+            }
+        }
+    }
+}
+
+/** The basis on which a read was found unchanged. */
+export type CompareBasis = 'content' | 'stat-over-bound';
+
+/**
+ * The basis on which the file is unchanged since `prior`, or `null` when that
+ * cannot be asserted. Content equality needs both digests; the stat pair
+ * decides only for a file over the bound. A hash-eligible file missing either
+ * digest — a legacy ledger entry, a read that failed — is never called unchanged.
+ */
+export function compareRead(prior: ReadRecord, mtime: number, size: number, digest: Digest): CompareBasis | null {
+    if (digest.kind === 'over-bound') return prior.mtime === mtime && prior.size === size ? 'stat-over-bound' : null;
+    if (digest.kind === 'sha256' && prior.sha256 !== undefined) return prior.sha256 === digest.value ? 'content' : null;
+    return null;
 }
 
 /** The session ledger — paths as keys, numbers as values, no content field. */
@@ -183,11 +255,13 @@ export function isRangedRead(toolInput: JsonObject): boolean {
 }
 
 /** 6.1 advisory — duplicate full read of an unchanged, already-read path. */
-export function buildDuplicateReadLine(relPath: string, earlierTs: number): string {
+export function buildDuplicateReadLine(relPath: string, earlierTs: number, compared: CompareBasis): string {
     const when = new Date(earlierTs).toISOString();
+    const basis =
+        compared === 'content' ? 'unchanged content (same sha256)' : 'unchanged since (same mtime+size; over the 2 MB hash bound)';
     return (
-        `re-read guard: ${relPath} was already fully read this session (${when}) and is ` +
-        `unchanged since (same mtime+size) — the content is still in context; if you only ` +
+        `re-read guard: ${relPath} was already fully read this session (${when}) with ` +
+        `${basis} — the content is still in context; if you only ` +
         `need part of it, a ranged Read (offset/limit) pays for the range, not the file.`
     );
 }
@@ -252,20 +326,23 @@ export function main(): number {
             return EXIT_ALLOW; // unreadable/missing target — nothing to compare
         }
 
+        const digest = contentDigest(absPath, size);
         const prior = ledger.reads[key];
         const ownWrite = ledger.writes[key];
         const alreadyFired = ledger.fired[key] === true;
 
         let advisory: string | null = null;
+        const compared = prior === undefined ? null : compareRead(prior, mtime, size, digest);
         if (!alreadyFired && ownWrite !== undefined) {
             advisory = buildPostEditReadLine(key); // 6.2 wins when both hold
-        } else if (!alreadyFired && prior !== undefined && prior.mtime === mtime && prior.size === size) {
-            advisory = buildDuplicateReadLine(key, prior.ts);
+        } else if (!alreadyFired && prior !== undefined && compared !== null) {
+            advisory = buildDuplicateReadLine(key, prior.ts, compared);
         }
 
         // Record the read that is about to happen (numbers only), consume the
         // one-shot own-write marker, and latch the per-path fire flag.
-        ledger.reads[key] = { mtime, size, ts: Date.now() };
+        ledger.reads[key] =
+            digest.kind === 'sha256' ? { mtime, size, ts: Date.now(), sha256: digest.value } : { mtime, size, ts: Date.now() };
         if (ownWrite !== undefined) delete ledger.writes[key];
         if (advisory !== null) ledger.fired[key] = true;
         writeLedger(workspaceRoot, sessionKey, ledger);

package/src/scripts/hooks/rtk_wrap_hook.ts

@@ -24,7 +24,8 @@
  * (`agents/evidence/analysis/host-input-rewrite-probe-2026-08-23.md`).
  *
  * What IS true, and is why this hook still only warns: **this dispatcher does not
- * emit it, and no accepted composition policy exists for it.** The dispatcher
+ * emit it, and since ADR-285 no concern may produce a rewrite at all** — one
+ * egress stage is the only writer, and a command nudge is not egress. The dispatcher
  * aggregates many concerns per event and reduces them to one exit code; what
  * happens when two concerns both want to rewrite the same tool input is an
  * unanswered design question, not a plumbing detail. A default-OFF hook that
@@ -209,8 +210,8 @@ export function classify(command: string): Eligibility {
 // carries no `updatedInput`". Re-probed against Claude Code 2.1.241: the host
 // carries it (see the header, and
 // agents/evidence/analysis/host-input-rewrite-probe-2026-08-23.md). The real
-// reason is that THIS dispatcher emits no such field and has no accepted
-// composition policy for one across concerns. Same outcome, correct cause: a committed
+// reason is that THIS dispatcher emits no such field and, under ADR-285, no
+// concern may produce one. Same outcome, correct cause: a committed
 // per-command cap table (this constant — rows individually removable,
 // per-row opt-out via `enabled`) and a warn naming the bounded alternative.
 // Nothing is ever truncated; ignoring the advisory IS the uncapped re-run,

package/src/scripts/hooks/rule_inject_hook.ts

@@ -970,7 +970,14 @@ export function gateOpen(root: string, cliEntry: boolean, packageRoot?: string |
     // found; inside the bundle nothing else can locate it.
     const { mode, hosts } = resolveLeanProjection({
         projectRoot: root,
-        packageRoot: packageRoot ?? null,
+        // FALLS BACK TO `root`, and the fallback is what makes this work in a
+        // source checkout. Since ADR-293 the form comes from the package-owned
+        // record under `<packageRoot>/src/config/`, and `packageRoot` here is
+        // `AGENT_CONFIG_PACKAGE_ROOT` — unset outside an install, where the
+        // project root IS the package root. A consumer project has no such
+        // record, so the fallback reads nothing there and the full form stands,
+        // which is the same answer it gave before.
+        packageRoot: packageRoot ?? root,
     });
     if (deliversBodies(mode) && hosts.hosts.includes(DELIVERY_HOST)) return true;
     if (hookSectionEnabled(root, 'rule_inject')) return true;

package/src/scripts/hooks/session_eol_hook.ts

@@ -76,6 +76,10 @@ import {
     run_checkpoints_enabled,
 } from '../_lib/continuity_writer.js';
 import { publishContinuityRecord } from '../_lib/continuity_slot.js';
+import { current_branch } from '../_lib/git_common_dir.js';
+import { derive_session_tag } from '../_lib/session_tag.js';
+import { localDay, pruneStaleMarkers, pruneStalePointers, writeSessionPointer } from '../retro_queue.js';
+import { probeRanToday, stampProbeRun } from './probe_throttle.js';
 import { read_claimed_slug } from '../session_register_hook.js';
 import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
@@ -377,7 +381,7 @@ export function main(): number {
     //     record, which is the deliberate departure from resuming by
     //     bookkeeping (Phase 3.2).
     //
-    // "Inside a running contract" is the same carrier `run-continuation`
+    // "Inside a running contract" is the same carrier the withdrawn `run-continuation`
     // uses — a `sessions:claim` for this session — and no second one is
     // invented. Outside a contract this is silent: a checkpoint for a
     // conversational session names work nobody is executing.
@@ -408,6 +412,7 @@ export function main(): number {
     }
 
     writeContinuityRecord(workspaceRoot, rawSessionId, counters, threshold, tokens);
+    writeRetroPointer(workspaceRoot, sessionKey, rawSessionId, now);
 
     // No warn path. Both emitters this hook used to carry were the recycle
     // advisory and its counter-check, and both are retired (step 3.2). The hook
@@ -416,6 +421,48 @@ export function main(): number {
     return 0;
 }
 
+/**
+ * The retro's session pointer (`docs/contracts/retro-v1.md`, path C): one small
+ * file per session in the git common directory, refreshed on every Stop. It is
+ * what lets the next day's sweep find a session that ran only in a worktree,
+ * after the worktree is gone, and what records the session's branch. A fourth
+ * handler inside this concern for the reason the continuity record is one: the
+ * concern count is ratcheted. Off with `retro.enabled: false`, which
+ * `writeSessionPointer` reads; never blocks.
+ */
+export function writeRetroPointer(
+    workspaceRoot: string,
+    eolKey: string,
+    rawSessionId: string | null,
+    now: string,
+): boolean {
+    const sessionId = String(rawSessionId ?? '').trim();
+    if (sessionId === '') return false;
+    try {
+        const written = writeSessionPointer(workspaceRoot, {
+            eol_key: eolKey,
+            tag: derive_session_tag(sessionId),
+            branch: current_branch(workspaceRoot),
+            workspace: workspaceRoot,
+            ended_at: now,
+        });
+        // Once a day, drop pointers and markers nothing can still use, so the
+        // stores stay bounded even while no sweep runs.
+        if (written && !probeRanToday(workspaceRoot, RETRO_PRUNE_STAMP)) {
+            const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+            pruneStalePointers(workspaceRoot, localDay(now, tz), tz);
+            pruneStaleMarkers(workspaceRoot, Date.parse(now));
+            stampProbeRun(workspaceRoot, RETRO_PRUNE_STAMP);
+        }
+        return written;
+    } catch {
+        return false;
+    }
+}
+
+/** The `probe_throttle` stamp for the once-a-day retro store prune. */
+const RETRO_PRUNE_STAMP = 'retro-prune';
+
 /**
  * The continuity-record handler — one of the three lifecycle handlers this
  * concern carries, and independently switchable from the other two.

package/src/scripts/hooks/source_first_gate_hook.ts

@@ -96,6 +96,7 @@ import { is_replay_mode } from './state_io.js';
 import { readHookStdin } from './hook_stdin.js';
 import { resolveConsumerRoot } from './subagent_ledger_hook.js';
 import { EXIT_ALLOW } from './exit_codes.js';
+import { isHandoverShape } from '../_lib/ui_surface.js';
 
 /** Would-warns per session before the valve goes silent — `MAX_NUDGES` shape. */
 export const MAX_SHADOW_WARNS = 2;
@@ -170,20 +171,17 @@ export const COMMAND_MATCHERS: readonly { pattern: RegExp; hit: MatcherHit }[] =
 
 /**
  * The handover path shapes `design-fidelity` routes on a FILE rather than on a
- * word: `file_pattern: *design.html` and `path_prefix: .claude/design-system/`.
+ * word, read from the one shared list `HANDOVER_SHAPES` in `_lib/ui_surface`.
  *
  * DIRECTION-AGNOSTIC ON PURPOSE, and that is the one difference from
  * `ui_route_nudge_hook.isArtifactRead`, which requires a non-write. Handover
  * *presence* and handover *having been read* are the two separate facts this
- * concern needs, and a single predicate cannot carry both. The read latch
- * below delegates to that exported predicate rather than re-deriving it;
- * `source_first_gate.test.ts` pins the two path shapes against each other so
- * the copy cannot drift.
+ * concern needs, and a single predicate cannot carry both.
+ * `handover_predicate_parity.test.ts` probes every carrier with one example per
+ * shape, so a shape no carrier accepts reds there.
  */
 export function isHandoverPath(file: string): boolean {
-    if (!file) return false;
-    const normalized = file.replace(/\\/g, '/').toLowerCase();
-    return normalized.endsWith('design.html') || normalized.includes('.claude/design-system/');
+    return isHandoverShape(file);
 }
 
 export interface CaptureEvent {