@event4u/agent-config 14.23.0 → 16.0.0

package/src/scripts/hooks/end_review_nudge_hook.ts

@@ -28,17 +28,26 @@
  * (`git ls-files --others --exclude-standard`, each one READ from the
  * filesystem rather than diffed in a subprocess — see "Untracked files" below;
  * fixes a review finding, F6, that a brand-new file was previously invisible
- * to this count entirely). Chosen over a session-start SHA/timestamp
- * baseline because no such baseline exists anywhere a `stop` concern can
- * read it (recording one would be new session-wide state, out of this
- * roadmap phase's one-concern scope). Two consequences, stated rather than
- * hidden:
- *   - Uncommitted changes that PREDATE this session (a dirty working tree
- *     the user already had) are counted as if they were this session's
- *     mutation. Per `commit-policy`, an agent almost never commits without
- *     explicit permission, so "uncommitted since HEAD" is usually a good
- *     proxy for "mutated this session" in practice — but it is a proxy, not
- *     an exact measure.
+ * to this count entirely).
+ *
+ * SINCE 2026-09-11 THIS READING IS BASELINE-CORRECTED ON `claude`, and this
+ * block used to say the opposite — that a session-start baseline was rejected
+ * "because no such baseline exists anywhere a `stop` concern can read it". That
+ * was true of a one-concern roadmap phase and stale by the time it mattered:
+ * `session_start` is bound on seven hosts, and `review-baseline` now records
+ * HEAD plus the already-dirty non-doc line count there. `_lib/review_baseline.ts`
+ * cites this paragraph as the defect it closes, so leaving the paragraph
+ * standing would have made the two files contradict each other.
+ *
+ * What the correction does and does not cover:
+ *   - Uncommitted changes that PREDATE the session are SUBTRACTED where a
+ *     baseline is readable and its HEAD and measure still match. Absent,
+ *     unreadable, head-moved or mixed-measure → the unsubtracted count, with
+ *     the reason carried in the `review_skipped` row.
+ *   - The baseline is written once per session and never refreshed, so from a
+ *     session's first commit onward `head-moved` holds and the pre-existing
+ *     tree is charged again. Over-reporting is the safe direction; the limit is
+ *     real and is stated in `review_baseline.ts` rather than implied away.
  *   - A session that DID commit mid-turn (one of `commit-policy`'s four
  *     exceptions) moves HEAD, so mutations already committed are invisible
  *     to this diff. Declared, not silently assumed away.
@@ -207,11 +216,20 @@
  * exit-2 warn onto an unverified propagation path is exactly the
  * speculative mapping `host_semantics.ts` exists to avoid.
  *
- * CONTRACT: never blocks THE ACTUAL TURN. The DISPATCHER-INTERNAL exit is 2
- * on a fire (never 1/BLOCK, never >=3), `fail_closed: false`; the HOST-FACING
- * exit on `claude` is 0 either way, per the proof above. Doc-only
- * diffs, a reviewer having run, or any unreadable/malformed input all
- * resolve to silence (dispatcher-internal exit 0), not a crash.
+ * CONTRACT: never REFUSES a turn. The DISPATCHER-INTERNAL exit is 2 on a fire
+ * (never 1/BLOCK, never >=3), `fail_closed: false`; the HOST-FACING exit on
+ * `claude` is 0 either way, per the proof above. Doc-only diffs, a reviewer
+ * having run, or any unreadable/malformed input all resolve to silence
+ * (dispatcher-internal exit 0), not a crash.
+ *
+ * WHAT THE PROOF ABOVE DOES NOT COVER. Every term of it is an exit code, so it
+ * settles refusal and nothing else. Whether the `additionalContext` payload
+ * this concern emits at `stop` causes the host to run the agent AGAIN is a
+ * separate question, and this tree does not answer it — see
+ * `docs/contracts/hook-architecture-v1.md` under the exit-code table, which
+ * names the measurement that would. So do not read the proof above as
+ * establishing that this concern leaves the turn alone; it establishes only
+ * that the concern never refuses it.
  */
 import { spawnSync } from 'node:child_process';
 import * as crypto from 'node:crypto';
@@ -220,7 +238,18 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { buildReviewSkippedLine, type MutationMeasure } from '../_lib/review_skipped_record.js';
+import {
+    applyBaseline,
+    currentHeadSha,
+    readBaseline,
+    type BaselineFallback,
+    type BaselineOutcome,
+} from '../_lib/review_baseline.js';
+import {
+    buildReviewSkippedLine,
+    type BaselineApplication,
+    type MutationMeasure,
+} from '../_lib/review_skipped_record.js';
 import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
 import { atomic_write_json, is_replay_mode } from './state_io.js';
@@ -606,6 +635,7 @@ export function appendReviewSkippedTelemetry(
     workspaceRoot: string,
     diffLines: number,
     mutationMeasure: MutationMeasure,
+    baseline?: BaselineApplication,
 ): void {
     if (is_replay_mode()) return;
     const ts = new Date().toISOString();
@@ -614,6 +644,7 @@ export function appendReviewSkippedTelemetry(
         mutation_measure: mutationMeasure,
         ts,
         id: crypto.randomUUID(),
+        baseline,
     });
     if (errors.length || line === null) return; // refused input — never write a broken line
     try {
@@ -694,6 +725,23 @@ function _read_stdin(): string {
     return readHookStdin();
 }
 
+/**
+ * The one place the two spellings meet.
+ *
+ * `BaselineFallback` is kebab-cased because it is a TypeScript union read only
+ * in this process; `BaselineApplication` is snake_cased because it is written
+ * into an audit line and every other enum in that stream is. A hand-written
+ * ternary translated them until a review pointed out that `head-moved` and
+ * `head_moved` differ by one character in a conditional nobody would re-read —
+ * an exhaustive record makes a new fallback a compile error instead.
+ */
+const FALLBACK_TO_TELEMETRY: Readonly<Record<BaselineFallback, BaselineApplication>> = {
+    absent: 'absent',
+    unreadable: 'unreadable',
+    'head-moved': 'head_moved',
+    'mixed-measure': 'mixed_measure',
+};
+
 export function main(): number {
     const [envelope, payload] = unwrap(_read_stdin(), 'claude');
 
@@ -705,15 +753,43 @@ export function main(): number {
     const workspace_root =
         String(envelope['workspace_root'] ?? '').trim() || process.cwd();
 
-    let diffLines: number;
+    let measuredLines: number;
     let mutationMeasure: MutationMeasure;
     try {
         const measured = totalNonDocMutatedLinesWithMeasure(workspace_root);
-        diffLines = measured.lines;
+        measuredLines = measured.lines;
         mutationMeasure = measured.measure;
     } catch {
         return 0; // fail-open — never block the agent loop
     }
+
+    // The session key is derived HERE rather than after the threshold test,
+    // because the threshold is now taken on the SUBTRACTED count and the
+    // baseline is keyed on the session. That is a real reordering: one extra
+    // `sha256` of a string and one `readFileSync` of a ~100-byte JSON file now
+    // run on every stop, including the majority that end below threshold. The
+    // alternative — testing the unsubtracted count first as a cheap
+    // pre-filter — is wrong in the one direction that matters: on an
+    // accumulator branch EVERY turn clears the unsubtracted threshold, so the
+    // pre-filter would pass exactly when the subtraction is needed and save
+    // nothing.
+    const sessionKey = deriveSessionKey(envelope, payload);
+    const baselineOutcome: BaselineOutcome = applyBaseline(
+        measuredLines,
+        readBaseline(workspace_root, sessionKey),
+        // A THUNK, not a value: on the `absent` and `unreadable` branches the
+        // result is discarded, and those two are the steady state on every host
+        // without this nudge and on every session before its first baseline
+        // write. Passing the value eagerly spent an 11-14 ms `git rev-parse` on
+        // each of those stops for nothing.
+        () => currentHeadSha(workspace_root),
+        mutationMeasure,
+    );
+    const diffLines = baselineOutcome.lines;
+    const baselineApplication: BaselineApplication = baselineOutcome.applied
+        ? 'applied'
+        : FALLBACK_TO_TELEMETRY[baselineOutcome.fallback];
+
     if (diffLines <= MUTATION_LINE_THRESHOLD) {
         return 0; // below threshold, or a doc-only diff — nothing to nudge
     }
@@ -723,7 +799,6 @@ export function main(): number {
     // JSON parse below. A session that already fired stops here, at a
     // single `fs.existsSync` call, without re-reading a (potentially
     // large) transcript file it already knows the answer for.
-    const sessionKey = deriveSessionKey(envelope, payload);
     if (hasFiredThisSession(workspace_root, sessionKey)) {
         return 0;
     }
@@ -756,7 +831,12 @@ export function main(): number {
     markFiredThisSession(workspace_root, sessionKey, new Date().toISOString());
 
     try {
-        appendReviewSkippedTelemetry(workspace_root, diffLines, mutationMeasure);
+        appendReviewSkippedTelemetry(
+            workspace_root,
+            diffLines,
+            mutationMeasure,
+            baselineApplication,
+        );
     } catch {
         // never let a telemetry failure block or fail the turn
     }

package/src/scripts/hooks/review_baseline_hook.ts

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * review-baseline — `session_start` concern
+ * (road-to-a-question-that-survives-the-turn Phase 2).
+ *
+ * WHAT IT DOES, and it is the whole of it: on session start, record how many
+ * non-doc lines were ALREADY dirty, and what HEAD was. `end-review-nudge`
+ * subtracts that at `stop` so a session is charged for its own mutation instead
+ * of for whatever the working tree happened to be carrying.
+ *
+ * THE DEFECT IT CLOSES. `end_review_nudge_hook`'s own header names it: a dirty
+ * tree that predates the session is counted as the session's, and the reason it
+ * was not fixed was "no such baseline exists anywhere a `stop` concern can read
+ * it". That was true of a phase with a one-concern scope, and stale by the time
+ * it mattered — `session_start` is bound on seven hosts carrying fourteen
+ * concerns. The measured consequence of leaving it: on a branch deliberately
+ * accumulating work, the nudge read 1,771 lines of two crashed sessions'
+ * uncommitted work and fired every turn. An advisory that always fires is noise,
+ * and noise is worse than silence because it trains the reader to skip the one
+ * that mattered.
+ *
+ * MEASURED WITH THE READER'S OWN INSTRUMENT. `totalNonDocMutatedLinesWithMeasure`
+ * is imported from the nudge rather than reimplemented, so the two sides cannot
+ * drift on what a "non-doc mutated line" is. A second counting implementation
+ * would produce a baseline in one unit and a measurement in another, and the
+ * subtraction would be silently wrong rather than visibly broken.
+ *
+ * CAPTURE ONLY. It never emits context, never warns, and always returns 0. A
+ * `session_start` concern that could refuse would turn an unreadable git
+ * directory into a session that cannot start, which is a far worse failure than
+ * the noise it is fixing.
+ *
+ * NO PATHS, NO FINGERPRINTS. The record is two numbers and a timestamp. A
+ * path-level change set was the shape the source draft proposed; it is a bigger
+ * object with a bigger privacy surface, and nothing in the nudge consumes one.
+ * The file cannot hold a path, a diff or a file body by construction, which is
+ * the same PII-exclusion-by-construction the telemetry record keeps.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    baselineStateFile,
+    currentHeadSha,
+    type ReviewBaseline,
+} from '../_lib/review_baseline.js';
+import { deriveSessionKey, totalNonDocMutatedLinesWithMeasure } from './end_review_nudge_hook.js';
+import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
+import { readHookStdin } from './hook_stdin.js';
+import { atomic_write_json } from './state_io.js';
+
+const EXIT_OK = 0;
+
+export function buildBaseline(workspaceRoot: string, now: Date = new Date()): ReviewBaseline {
+    const measured = totalNonDocMutatedLinesWithMeasure(workspaceRoot);
+    return {
+        head_sha: currentHeadSha(workspaceRoot),
+        baseline_lines: measured.lines,
+        // Carried, not discarded. Past `UNTRACKED_FILE_CAP` the count is a
+        // synthetic `THRESHOLD + 1 + tracked` chosen to be over the bar rather
+        // than to be true, and subtracting that from a later exact count is
+        // arithmetic over two different quantities. The consumer refuses the
+        // subtraction when the two measures disagree; it can only do that if the
+        // writer says which one it took.
+        measure: measured.measure,
+        written_at: now.toISOString(),
+    };
+}
+
+export function main(): number {
+    let envelope: JsonObject;
+    let payload: JsonObject;
+    try {
+        [envelope, payload] = unwrap(readHookStdin(), 'claude');
+    } catch {
+        return EXIT_OK;
+    }
+
+    const event = String(envelope['event'] ?? '');
+    if (event !== '' && event !== 'session_start') return EXIT_OK;
+
+    const workspaceRoot =
+        String((envelope['workspace_root'] as JsonValue | undefined) ?? '').trim() || process.cwd();
+
+    // A baseline is written ONCE per session. A host that fires session_start
+    // twice — Cline maps both TaskStart and TaskResume onto it — must not
+    // re-baseline mid-session: the second write would fold everything the
+    // session had already changed into its own baseline and the nudge would go
+    // permanently quiet for that session. Over-writing is the silent failure
+    // direction, so it is the one guarded.
+    const sessionKey = deriveSessionKey(envelope, payload);
+    const file = baselineStateFile(workspaceRoot, sessionKey);
+    try {
+        if (fs.existsSync(file)) return EXIT_OK;
+    } catch {
+        return EXIT_OK;
+    }
+
+    try {
+        // `atomic_write_json` is already `AGENT_CONFIG_REPLAY`-aware, so a
+        // fixture-replay run leaves no baseline behind.
+        atomic_write_json(file, buildBaseline(workspaceRoot) as unknown as JsonObject);
+    } catch {
+        // An unwritable state dir degrades to today's behaviour — the nudge
+        // reads `absent` and does not subtract. Never a failed session start.
+    }
+    return EXIT_OK;
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url`.
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) return false;
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/hooks/session_eol_hook.ts

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 /**
- * session-eol — Stop-slot session end-of-life instrument + recycle advisory
- * (road-to-token-economy-recycling Phases 1.1 / 3.2 / 4.2).
+ * session-eol — Stop-slot session end-of-life instrument + automatic
+ * continuity record (road-to-token-economy-recycling Phases 1.1 / 3.2 / 4.2,
+ * road-to-continuity-writer-activation Phase 1 and step 3.2).
  *
  * Phase 1.1 (record-only): per session, maintain counts-only end-of-life
  * state — final main-chain context size in parsed tokens (via
@@ -10,22 +11,31 @@
  * `agents/runtime/state/session-eol/<sha256(session)>.json`. Incremental:
  * each Stop reads only the transcript bytes appended since the last scan.
  *
- * Phase 3.2 (advisory, once per session): past the committed recycle
- * threshold (`src/config/recycle-threshold-budget.json`), inject ONE line
- * advising `session:recycle` — the F2 once-per-session pattern of
- * `end_review_nudge_hook.ts`. Absent/unreadable config or transcript is
- * SILENCE, never a block (fail-open); hooks cannot inject `/clear`, so the
- * recycle action itself stays advisory-carried by design (roadmap 5.1).
+ * Phase 3.2 — RETIRED 2026-09-10 (road-to-continuity-writer-activation step
+ * 3.2). This hook used to inject one line past the committed recycle threshold
+ * (`src/config/recycle-threshold-budget.json`) advising a human to run
+ * `agent-config session:recycle` before `/clear`, plus a second line when that
+ * advice had been given and no envelope had appeared. Both are gone. They
+ * existed because nothing else wrote the continuity record, and
+ * `writeContinuityRecord` below now does — armed by default since the same
+ * change, on an AI-council verdict of 2026-09-10 (2 seats, convergent, under
+ * the owner's written delegation). An advisory telling a human to do by hand
+ * what the concern now does on its own is a manual action on the normal path,
+ * which is what step 3.2 removes and what `check_continuity_surface` counts on
+ * its `normal_path_manual_actions` axis.
  *
- * Counter-check (second warn path, also once per session): when the advisory
- * fired on an earlier Stop and no envelope written since then exists, inject
- * one further line saying so — the advisory recommends an action whose next
- * step destroys the session, so recommending it without ever checking the
- * result is how a silent write failure becomes total context loss. Stamped by
- * `missing_envelope_warned_at`, gated on the same threshold, so the emergency
- * off-switch silences BOTH paths. Two independent emitters, at most one line
- * each per session — the budget the Stop slot carries from this hook is two,
- * not one.
+ * `agent-config session:recycle` itself is RETAINED, and deliberately: the
+ * same verdict refused to retire a public callable contract, and the automatic
+ * writer is not a strict superset of it — it skips a session that claimed no
+ * roadmap and omits the `git status` anchors the command collects. It is an
+ * explicit affordance now, not a step anybody is told to remember.
+ *
+ * What SURVIVES the retirement is the state machine underneath it.
+ * `advisory_fired_at` still stamps the first Stop at which a session crosses
+ * the recycle threshold, because the run-checkpoint writer below gates on
+ * exactly that edge. The field keeps its name: it is a persisted state key
+ * under `agents/runtime/state/session-eol/`, and renaming it would strand
+ * every state file already on disk to make one docblock read better.
  *
  * Phase 4.2 (read surface): every Stop also overwrites
  * `agents/runtime/state/context-fill.json` with the machine-readable fill
@@ -33,9 +43,10 @@
  * carries counts only, and this hook's behaviour is identical whether or
  * not anything reads it.
  *
- * Never blocks: exit 0 on every silent path; the advisory reports at
- * exit 2 ({decision:"warn", additional_context}) which `host_semantics`
- * reduces to a non-blocking warn on claude. `AGENT_CONFIG_REPLAY=1` → no-op.
+ * Never blocks: exit 0 on every path. With both advisory emitters retired this
+ * hook no longer returns the warn exit at all — it records, writes the context
+ * fill, the run checkpoint and the continuity record, and says nothing.
+ * `AGENT_CONFIG_REPLAY=1` → no-op.
  */
 
 import * as fs from 'node:fs';
@@ -48,7 +59,6 @@ import recycleThresholdConfig from '../../config/recycle-threshold-budget.json';
 import {
     listContinuityRecords,
     RECYCLE_MAX_AGE_HOURS,
-    recycle_envelope_rel,
 } from '../_lib/recycle_envelope_paths.js';
 import {
     emptyCounters,
@@ -72,12 +82,11 @@ import { readHookStdin } from './hook_stdin.js';
 import { atomic_write_json, is_replay_mode } from './state_io.js';
 import { isSafeTranscriptPath } from './end_review_nudge_hook.js';
 
-const EXIT_WARN = 2;
-
 /**
  * Per-process threshold override — the test seam and the emergency off
- * switch (`0` or any non-positive value disables the advisory lane while
- * recording continues). The committed value lives in
+ * switch (`0` or any non-positive value disables the threshold lane, so the
+ * run checkpoint and the continuity record stop while plain recording
+ * continues). The committed value lives in
  * `src/config/recycle-threshold-budget.json` and is statically imported so
  * the hook bundle carries it into consumers — one threshold, one constant.
  */
@@ -89,11 +98,24 @@ export const CONTEXT_FILL_REL = path.join('agents', 'runtime', 'state', 'context
 export interface SessionEolState {
     schema_version: 1;
     counters: EolCounters;
-    /** ISO stamp when the recycle advisory fired for this session (F2), or null. */
+    /**
+     * ISO stamp of the first Stop at which this session crossed the recycle
+     * threshold, or null.
+     *
+     * Named for the advisory it used to fire (retired 2026-09-10, step 3.2).
+     * The name is kept because this is a persisted key: renaming it would
+     * strand every `session-eol/<key>.json` already on disk. What it marks is
+     * the threshold-crossing edge, which the run-checkpoint writer still gates
+     * on.
+     */
     advisory_fired_at: string | null;
     /**
      * ISO stamp when the follow-up "advised, but no envelope exists" line
-     * fired, or null. Separate from `advisory_fired_at` so the counter-check
+     * fired, or null. NOTHING WRITES THIS ANY MORE — the counter-check was
+     * retired with the advisory on 2026-09-10 (step 3.2). It is still parsed,
+     * and `session_eol_report.ts` still counts it, because state files written
+     * before that date carry it and dropping the read would silently reinterpret
+     * their history as "never happened". Separate from `advisory_fired_at` so the counter-check
      * is once-per-session in its own right: one reminder is a safety net, one
      * per Stop for the rest of the session is a nag the reader learns to skip.
      */
@@ -172,54 +194,6 @@ export function readState(file: string): SessionEolState {
     };
 }
 
-/**
- * Is there a recycle envelope under this workspace, written since `since`?
- *
- * Two properties, both load-bearing:
- *
- * **Only ENOENT counts as missing.** `fs.existsSync` swallows every error into
- * `false`, so an unreadable directory (EACCES on a mounted or root-owned tree)
- * would read as "no envelope" and produce the manufactured "your envelope is
- * gone" warning this check exists to avoid. `statSync` + an errno test is the
- * only shape that can tell the two apart.
- *
- * **Freshness, not mere existence.** The consumer moves the envelope aside at
- * session_start, so a file still sitting here belongs to a session that never
- * cleared. Counting it would silence the warning in the case it exists to
- * catch, and worse: `/clear` would then resume the successor from another
- * session's state — a wrong resume instead of an empty one. An envelope whose
- * `written_at` predates the advisory is not this session's.
- */
-export function envelopeExists(
-    workspaceRoot: string,
-    since: string | null = null,
-    sessionId: string | null = null,
-): boolean {
-    // Phase 2.1: the record is keyed by session, so the counter-check must look
-    // at THIS session's path. Checking the shared name would read a peer's
-    // record as proof that this session wrote one — the same cross-session
-    // confusion the key exists to remove, re-created in the checker.
-    const target = path.join(workspaceRoot, recycle_envelope_rel(sessionId));
-    let raw: string;
-    try {
-        raw = fs.readFileSync(target, 'utf-8');
-    } catch (exc) {
-        // ENOENT is the real "no envelope"; anything else is a failed CHECK,
-        // and a failed check must never assert absence.
-        return (exc as NodeJS.ErrnoException)?.code !== 'ENOENT';
-    }
-    if (since === null) return true;
-    try {
-        const written = (JSON.parse(raw) as { written_at?: unknown }).written_at;
-        // Unparseable or undated: present, and not provably stale. Treat it as
-        // this session's — the alternative warns about a file that is there.
-        if (typeof written !== 'string') return true;
-        return Date.parse(written) >= Date.parse(since);
-    } catch {
-        return true;
-    }
-}
-
 /**
  * Records that were written and never read — the detection layer this defect
  * did not have.
@@ -276,25 +250,6 @@ export function unconsumedRecordLines(
     return out;
 }
 
-/**
- * The follow-up line: the advisory already fired, and no envelope arrived.
- *
- * This is the half of the reported minimum fix that lives outside the command
- * — the hook that recommends the call making the same counter-check before the
- * operator acts on it. Whatever stopped the write (a wrong root, a refusal
- * scrolled past, a forgotten step), the state visible here is identical, and
- * the next action the advisory recommended is the one that destroys the
- * session.
- */
-export function buildMissingEnvelopeLine(workspaceRoot: string, sessionId: string | null = null): string {
-    return (
-        `recycle advised earlier, but no envelope exists at ` +
-        `${path.join(workspaceRoot, recycle_envelope_rel(sessionId))} — /clear now starts the successor ` +
-        `from nothing. Re-run \`agent-config session:recycle\` and check that it prints the ` +
-        `absolute path it wrote before clearing.`
-    );
-}
-
 /**
  * Resolve the recycle threshold (Phase 3.1): the per-process override wins
  * (tests; `0` = advisory lane off), else the committed constant from
@@ -312,25 +267,6 @@ export function readThresholdTokens(): number | null {
     return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : null;
 }
 
-/**
- * The exactly-one advisory line injected past threshold (Phase 3.2).
- *
- * The `/clear` half is conditional on purpose. An earlier wording read
- * `run X … then /clear`, which is an instruction to destroy the session with
- * no check in between — and a reader who followed it while the command was
- * silently writing nothing lost everything. The proof to wait for is the
- * absolute path the command prints; naming it costs one clause.
- */
-export function buildAdvisoryLine(tokens: number, threshold: number): string {
-    return (
-        `context past recycle threshold (${tokens.toLocaleString('en-US')} of ` +
-        `${threshold.toLocaleString('en-US')} tokens): run \`agent-config session:recycle\` to ` +
-        `write the recycle envelope. It prints the absolute path it wrote — /clear only after ` +
-        `you have seen that line. The successor session then resumes from the envelope at ` +
-        `session_start (road-to-token-economy-recycling)`
-    );
-}
-
 /** Overwrite the Phase 4.2 read surface. Counts only; failures are swallowed. */
 function writeContextFill(
     workspaceRoot: string,
@@ -392,38 +328,32 @@ export function main(): number {
     const threshold = readThresholdTokens();
     const tokens = counters.final_context_tokens;
 
-    const shouldAdvise =
+    // The threshold-crossing edge: the first Stop at which this session went
+    // past the recycle threshold. It used to fire the recycle advisory (retired
+    // 2026-09-10, step 3.2) and it still gates the run-checkpoint writer below,
+    // which needs "crossed, once" rather than "is above".
+    const crossedThresholdNow =
         threshold !== null &&
         tokens !== null &&
         tokens >= threshold &&
         state.advisory_fired_at === null;
 
-    // The counter-check: the advisory fired on an EARLIER Stop (so `state`,
-    // the pre-update snapshot, already carries the stamp) and no envelope has
-    // appeared since. It can never collide with `shouldAdvise` — that branch
-    // requires `advisory_fired_at === null` — so at most one line is emitted
-    // per Stop, and this one at most once per session.
-    //
-    // `threshold !== null` gates it for the same reason the advisory is gated:
-    // `AGENT_RECYCLE_THRESHOLD_TOKENS=0` is documented as the emergency switch
-    // for the whole advisory lane, and a lane that keeps one more warn after
-    // being switched off is not off.
     // Raw id, not `sessionKey`: the record path is built from the id the host
     // exported (`safe_stem`), never from the hashed state-file key.
     const rawSessionId = payloadSessionId(payload, envelope) || null;
-    const shouldWarnMissing =
-        threshold !== null &&
-        state.advisory_fired_at !== null &&
-        (state.missing_envelope_warned_at ?? null) === null &&
-        !envelopeExists(workspaceRoot, state.advisory_fired_at, rawSessionId);
 
+    // `missing_envelope_warned_at` is carried forward, never set. Its writer —
+    // the "advised, but no envelope exists" counter-check — retired with the
+    // advisory it was checking on: with the record written automatically there
+    // is no advice to have been ignored, and the line it emitted told a human
+    // to run the command that step 3.2 removed from the normal path. The field
+    // is preserved on read so state written before that date keeps its history
+    // (`session_eol_report.ts` still counts it).
     const nextState: SessionEolState = {
         schema_version: 1,
         counters,
-        advisory_fired_at: shouldAdvise ? now : state.advisory_fired_at,
-        missing_envelope_warned_at: shouldWarnMissing
-            ? now
-            : (state.missing_envelope_warned_at ?? null),
+        advisory_fired_at: crossedThresholdNow ? now : state.advisory_fired_at,
+        missing_envelope_warned_at: state.missing_envelope_warned_at ?? null,
         updated_at: now,
     };
     try {
@@ -455,7 +385,7 @@ export function main(): number {
     // Best-effort throughout. A checkpoint is a recovery aid, and a
     // recovery aid that can fail a Stop is a liability.
     const checkpointRunId = payloadSessionId(payload, envelope);
-    if (shouldAdvise && checkpointRunId !== '' && run_checkpoints_enabled(workspaceRoot)) {
+    if (crossedThresholdNow && checkpointRunId !== '' && run_checkpoints_enabled(workspaceRoot)) {
         try {
             const slug = read_claimed_slug(workspaceRoot, checkpointRunId);
             if (slug !== null) {
@@ -479,26 +409,10 @@ export function main(): number {
 
     writeContinuityRecord(workspaceRoot, rawSessionId, counters, threshold, tokens);
 
-    if (shouldAdvise && threshold !== null && tokens !== null) {
-        process.stdout.write(
-            `${JSON.stringify({
-                decision: 'warn',
-                reason: `session-eol: context ${tokens} >= recycle threshold ${threshold}`,
-                additional_context: buildAdvisoryLine(tokens, threshold),
-            })}\n`,
-        );
-        return EXIT_WARN;
-    }
-    if (shouldWarnMissing) {
-        process.stdout.write(
-            `${JSON.stringify({
-                decision: 'warn',
-                reason: 'session-eol: recycle advised, no envelope written',
-                additional_context: buildMissingEnvelopeLine(workspaceRoot, rawSessionId),
-            })}\n`,
-        );
-        return EXIT_WARN;
-    }
+    // 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
+    // records, writes the context fill, the checkpoint and the continuity
+    // record, and returns silently.
     return 0;
 }
 

package/src/scripts/hooks/source_first_gate_hook.ts

@@ -70,6 +70,18 @@
  * candidate spread is what tells them apart. Picking one now would be the
  * threshold-first mistake the activation policy names.
  *
+ * ── A SECOND RECORD KIND SHARES THIS LOG ──────────────────────────────────
+ *
+ * `_lib/tolerance_shadow.ts` appends `record: "tolerance_shadow"` lines here.
+ * It is NOT a second concern and registers nothing: `check_estate_count`
+ * reports zero growth allowance on hook concerns, so the value-reconciliation
+ * window rides this file rather than opening its own
+ * (`road-to-design-intent-conformance` 4.2). Readers of this log MUST
+ * discriminate on `record` — a consumer that assumed one shape would silently
+ * mis-parse the other. That module carries its own pre-registered flip
+ * criterion, on the same terms as the one above and with the same reverse
+ * trigger discipline.
+ *
  * PRIVACY BY CONSTRUCTION: booleans, counts, a matcher label, and the
  * id-shaped `agent_type` enum (recorded verbatim, the same stance
  * `subagent_ledger_hook.ts` states for that field). No prompt, no command