@event4u/agent-config 9.30.0 → 9.32.0

package/src/agent-src/templates/scripts/work_engine/state.ts

@@ -220,6 +220,7 @@ export class WorkState {
     ui_polish: Dict | null;
     contract: Dict | null;
     stitch: Dict | null;
+    self_fix: Dict | null;
     halts: Dict[];
     version: number;
     persona: string;
@@ -245,6 +246,7 @@ export class WorkState {
         ui_polish?: Dict | null;
         contract?: Dict | null;
         stitch?: Dict | null;
+        self_fix?: Dict | null;
         halts?: Dict[];
         version?: number;
         persona?: string;
@@ -269,6 +271,7 @@ export class WorkState {
         this.ui_polish = opts.ui_polish ?? null;
         this.contract = opts.contract ?? null;
         this.stitch = opts.stitch ?? null;
+        this.self_fix = opts.self_fix ?? null;
         this.halts = opts.halts ?? [];
         this.version = opts.version ?? SCHEMA_VERSION;
         this.persona = opts.persona ?? 'senior-engineer';
@@ -309,6 +312,7 @@ export function to_dict(state: WorkState): Dict {
     _validate_ui_polish(state.ui_polish);
     _validate_contract(state.contract);
     _validate_stitch(state.stitch);
+    _validate_self_fix(state.self_fix);
     _validate_halts(state.halts);
     return {
         version: state.version,
@@ -324,6 +328,7 @@ export function to_dict(state: WorkState): Dict {
         ui_polish: state.ui_polish,
         contract: state.contract,
         stitch: state.stitch,
+        self_fix: state.self_fix,
         halts: [...state.halts],
         persona: state.persona,
         memory: state.memory,
@@ -406,6 +411,9 @@ export function from_dict(payload: JsonValue): WorkState {
     const stitch = payload['stitch'] ?? null;
     _validate_stitch(stitch);
 
+    const self_fix = payload['self_fix'] ?? null;
+    _validate_self_fix(self_fix);
+
     const halts = 'halts' in payload ? payload['halts'] : [];
     _validate_halts(halts);
 
@@ -422,6 +430,7 @@ export function from_dict(payload: JsonValue): WorkState {
         ui_polish: _isDict(ui_polish) ? { ...ui_polish } : null,
         contract: _isDict(contract) ? { ...contract } : null,
         stitch: _isDict(stitch) ? { ...stitch } : null,
+        self_fix: _isDict(self_fix) ? { ...self_fix } : null,
         halts: Array.isArray(halts) ? ([...halts] as Dict[]) : [],
         version: version as number,
         persona: _get(payload, 'persona', 'senior-engineer') as string,
@@ -866,6 +875,71 @@ function _validate_ui_review(ui_review: JsonValue): void {
     }
 }
 
+/**
+ * Reject malformed `self_fix` envelopes; tolerate `null` and `{}`.
+ *
+ * `null` means no red check has been seen. Once populated, each key is a lane
+ * name (`test`, `verify`) whose record may carry `attempts` (a non-negative
+ * int) and `signatures` (a list of strings). As with `ui_polish`, the schema
+ * enforces only shape: the ceiling and the no-progress floor are the handler's
+ * business (`directives/backend/_self_fix.ts`), so a state file cannot decide
+ * how many attempts are allowed.
+ *
+ * `attempts` is validated but NOT bounded here on purpose. A file carrying
+ * `attempts: 99` is well-formed and simply exhausted — rejecting it would turn
+ * a spent budget into a crash, and the loop's whole point is a clean exit.
+ */
+function _validate_self_fix(self_fix: JsonValue): void {
+    if (self_fix === null) {
+        return;
+    }
+    if (!_isDict(self_fix)) {
+        throw new SchemaError(
+            `state.self_fix must be a JSON object or null; ` +
+                `got ${pyTypeName(self_fix)}`,
+        );
+    }
+    for (const [lane, record] of Object.entries(self_fix)) {
+        if (!_isDict(record)) {
+            throw new SchemaError(
+                `state.self_fix.${lane} must be a JSON object; ` +
+                    `got ${pyTypeName(record)}`,
+            );
+        }
+        if ('attempts' in record) {
+            const attempts = record['attempts'];
+            if (
+                typeof attempts !== 'number' ||
+                typeof attempts === 'boolean' ||
+                !Number.isInteger(attempts) ||
+                attempts < 0
+            ) {
+                throw new SchemaError(
+                    `state.self_fix.${lane}.attempts must be a non-negative ` +
+                        `integer when present; got ${pyRepr(attempts)}`,
+                );
+            }
+        }
+        if ('signatures' in record) {
+            const signatures = record['signatures'];
+            if (!Array.isArray(signatures)) {
+                throw new SchemaError(
+                    `state.self_fix.${lane}.signatures must be a list when ` +
+                        `present; got ${pyTypeName(signatures)}`,
+                );
+            }
+            for (const entry of signatures) {
+                if (typeof entry !== 'string') {
+                    throw new SchemaError(
+                        `state.self_fix.${lane}.signatures entries must be ` +
+                            `strings; got ${pyTypeName(entry)}`,
+                    );
+                }
+            }
+        }
+    }
+}
+
 /**
  * Reject malformed `ui_polish` envelopes; tolerate `null` and `{}`.
  *

package/src/agent-src/templates/scripts/work_engine/state_io.ts

@@ -150,6 +150,7 @@ export function _to_delivery(work: WorkState): DeliveryState {
         contract: work.contract as Record<string, DeliveryAny> | null,
         stitch: work.stitch as Record<string, DeliveryAny> | null,
         stack: work.stack as Record<string, DeliveryAny> | null,
+        self_fix: work.self_fix as Record<string, DeliveryAny> | null,
     });
 }
 
@@ -182,6 +183,11 @@ export function _sync_back(work: WorkState, delivery: DeliveryState): void {
     work.contract = delivery.contract as Dict | null;
     work.stitch = delivery.stitch as Dict | null;
     work.stack = delivery.stack as Dict | null;
+    // Reassigned (not mutated) by `record_attempt`, so the defensive mirror
+    // above is load-bearing here rather than a no-op: without this line the
+    // attempt counter would reset on every dispatch and the loop would never
+    // reach either floor.
+    work.self_fix = delivery.self_fix as Dict | null;
 }
 
 /**

package/src/config/pack-size-budget.json

@@ -7,9 +7,10 @@
     "measurement_conditions": "npm pack --dry-run --json --ignore-scripts, run at the repo root on a clean checkout. `--ignore-scripts` means NO build runs, so dist/cli, dist/ui, dist/mcp and dist/hooks are absent and the figure covers only the TRACKED payload (src/scripts/, dist/agent-src/, dist/install/, docs/guidelines/, templates). That is deliberate: this gate is always-on for every PR, and the tracked content tree is exactly the surface that grows by accretion. The built artifact is ~5.4 MB larger and is gated separately, at release time, by evaluator-budgets.unpacked_size_mb.",
     "budgets": {
         "packed_size_mb": {
-            "max": 6.9,
-            "last_measured": 6.398,
+            "max": 7.8,
+            "last_measured": 7.238,
             "method": "npm pack --dry-run --json --ignore-scripts → dist.size / 1e6 (the compressed tarball a consumer actually downloads)",
+            "baseline_note_2026_08_10": "6.9 → 7.8 re-baselined 2026-08-10. WHICH OF THE TWO THIS IS, stated because the guard asks: a RATCHET RESET, not the config bent around a failing check — and the discriminator is that the payload is real and needed rather than that the check was inconvenient. The 44 KB is two source files a shipped instruction depends on, the cheaper alternative was examined and rejected on that ground (below), the new cap carries ~8% headroom over the higher of two disagreeing measurements rather than clearing by a hair, and the raise was put to the maintainer as a decision instead of applied to make a red go away. A reader who disagrees has everything needed to reverse it: the measurement, its method, the trip cause, and the rejected option. Maintainer-decided in the PR that tripped it, surfaced rather than smuggled — the same standing this file's `owner: maintainer` requires. MEASURED TWICE, and the two do not agree: CI reported 6.907 on this exact commit, a local run under the documented conditions reports 7.238. The 331 KB gap is UNEXPLAINED — the tree matches the pushed commit and only this file differs — so the cap is set over the HIGHER figure rather than the convenient one, and the discrepancy is recorded here as an open question instead of resolved by assumption. A third party reproducing this should expect either number and should not treat the lower one as authoritative. Separately, and this part IS understood: `npm pack --dry-run --ignore-scripts` in a worktree that has been BUILT reads 8.45, because the flag assumes dist/cli, dist/ui, dist/mcp and dist/hooks are absent and a built tree has them. That figure is not comparable to this budget and must never be written here — recorded because it is a trap the documented method invites. Trip cause: road-to-conformance-round5 Phase 3 added src/scripts/hooks/turn_end_gate_hook.ts (32 KB) and src/scripts/measure_turn_end_gate.ts (12 KB) in packed paths plus schema/template/contract growth, landing 7 KB over a 6.9 cap. Max set to 7.8 (~8% headroom over 7.238, and ~13% over CI's 6.907) for the reason the 2026-08-05 note already gives: a cap pinned just above the measurement reds on the next commit and teaches the reader to raise it again. ALTERNATIVE EXAMINED AND REJECTED, so it is not re-proposed: dropping measure_turn_end_gate.ts from the pack would have cleared the cap with room, but the settings description added in the same change instructs CONSUMERS to run that script against their own transcript store before arming the gate — excluding it would break a shipped instruction.",
             "baseline_note": "5.903 → 6.398 re-baselined 2026-08-05. This is a RE-BASELINE, not a carve-out for the change that tripped it: measured on the tracked tree, `origin/main` alone was already at 6.372 of a 6.4 cap, so 28 KB of headroom remained after months of accretion and the next legitimate addition of any size was going to cross it. The addition here is 26 KB — docs/contracts/settings-classes.md (the A/B/C fence, read at RUNTIME by the settings writer, so it must ship) plus src/server/io/yamlIO.ts (imported by that writer to preserve the user's comments). CI measures ~4 KB above the local figure because it regenerates dist/agent-src first. Max set to 6.9 rather than to a number that merely clears: a cap pinned 2 KB above the measurement reds on the next commit and teaches the reader to raise it again, which is how a budget becomes a formality. That restores the ~8% headroom the 5.903/6.4 pair originally carried. The `owner: maintainer` on this file stands — this raise is surfaced in the PR for that decision, not smuggled."
         }
     },

package/src/scripts/_cli/cmd_session_recycle.ts

@@ -38,6 +38,7 @@ import {
     CAPSULE_SCHEMA_VERSION,
     validateRecycleEnvelope,
 } from '../_lib/subagent_capsule.js';
+import { collectGrounding } from '../_lib/envelope_grounding.js';
 import { atomic_write_json } from '../hooks/state_io.js';
 
 export interface RecycleResult {
@@ -61,6 +62,9 @@ export function templateEnvelope(): Record<string, unknown> {
         open_worker_envelopes: [],
         artifact_paths: ['<path to a deliverable / note / evidence file>'],
         assumptions: [],
+        next_task: '<the ONE task this envelope is written for — select content for it>',
+        suggested_skills: ['<skill the successor should invoke>'],
+        failed_approaches: ['<tried X, failed because Y — or the single entry "none">'],
     };
 }
 
@@ -123,6 +127,27 @@ export function runSessionRecycle(
     }
     if (envelope['workspace'] === undefined) envelope['workspace'] = projectRoot;
 
+    // Scripted grounding (Phase 3.3): the factual fields are READ, never
+    // composed. A model-written branch is a claim; this is a reading. The
+    // composer cannot override them — a "next_task" it got wrong is a
+    // proposal, a "head" it got wrong is a silent stale resume.
+    const grounding = collectGrounding(projectRoot);
+    // Drop the composer's factual keys UNCONDITIONALLY first. Guarding each
+    // assignment on `!== null` would leave a model-composed branch or head
+    // standing whenever the git read fails — the consumer would then compare
+    // a fabricated anchor against the real tree and produce either false
+    // drift or, worse, false silence. An unreadable fact is absent, never
+    // inherited from the composer.
+    for (const key of ['repo_identity', 'branch', 'head', 'status_summary', 'last_verify', 'uncommitted_paths']) {
+        delete envelope[key];
+    }
+    if (grounding.repo_identity !== null) envelope['repo_identity'] = grounding.repo_identity;
+    if (grounding.branch !== null) envelope['branch'] = grounding.branch;
+    if (grounding.head !== null) envelope['head'] = grounding.head;
+    if (grounding.status_summary !== null) envelope['status_summary'] = grounding.status_summary;
+    if (grounding.last_verify !== null) envelope['last_verify'] = grounding.last_verify;
+    envelope['uncommitted_paths'] = grounding.uncommitted_paths;
+
     const violations = validateRecycleEnvelope(envelope);
     if (violations.length > 0) {
         return {

package/src/scripts/_cli/explain_last/inputs.ts

@@ -132,6 +132,19 @@ export function build(project_root: string): Record<string, unknown> | null {
         rule_loading_tier = null;
     }
     let rule_loading_tier_source = _pyTruthy(rule_loading_tier) ? 'user' : 'default';
+    // The one read-site divergence from the template that is NOT a
+    // `settingsCarveOut` row, so it is explained here instead
+    // (`road-to-scripts-settings-defaults` Phase 1, § 2 of the Evidence Report).
+    // The template ships `rule_loading_tier: __RULE_LOADING_TIER__` — an
+    // installer placeholder, not a value — so the template-defaults layer in
+    // `load_agent_settings` deliberately does not inject it and an absent key
+    // arrives here as `undefined`. `balanced` is therefore this reader's own
+    // default, matching what the installer substitutes.
+    // The second arm is the deliberate part: a settings file that still
+    // literally contains the placeholder is a BROKEN install, and this reports
+    // it as `source: default` — i.e. the trace looks healthy. Surfacing it
+    // instead would be a reporting change beyond this roadmap's scope; it is
+    // recorded rather than silently kept.
     if (!_pyTruthy(rule_loading_tier) || rule_loading_tier === '__RULE_LOADING_TIER__') {
         rule_loading_tier = _DEFAULT_RULE_LOADING_TIER;
         rule_loading_tier_source = 'default';

package/src/scripts/_cli/handoff_generate.ts

@@ -35,6 +35,19 @@ export const WORD_CAP = 1200;
 const SNIPPET_CHARS = 200;
 const DONE_SNIPPET_CHARS = 400;
 const MAX_ERRORS = 5;
+/**
+ * Per-error cap. Above `SNIPPET_CHARS` because an error string is kept
+ * verbatim so it stays greppable — but deliberately not far above.
+ *
+ * The section competes for a fixed word cap whose trim pops the NEWEST entry
+ * first, and the newest failure is the one a successor needs. Enlarging each
+ * entry therefore makes that pre-existing trim order bite more often. 400 is
+ * twice the old truncation — enough to carry a real error line whole — while
+ * keeping the five-entry section within roughly a sixth of the cap. The
+ * pop()-newest ordering is pre-existing and is not this change's to alter;
+ * this bound is what keeps the change from amplifying it.
+ */
+const MAX_ERROR_CHARS = 400;
 const MAX_DECISIONS = 5;
 const MAX_FILES = 15;
 
@@ -325,11 +338,23 @@ export function build_handoff(
     );
 
     // Errors + fixes — failure-pattern turns, oldest→newest, last 5.
+    //
+    // Precision rule (Phase 3.1): the error string is carried VERBATIM. It
+    // used to be `_snippet`-ed like every other section, which truncates
+    // mid-string — and a truncated error cannot be grepped, matched against a
+    // tracker, or recognised when it recurs, which is the only reason to
+    // carry it at all. So the FAILURE-matching line is taken whole (capped
+    // only against an absurd single line) instead of the turn being cut at an
+    // arbitrary offset.
     const errors = _redact_items(
         toolish
             .filter((t) => FAILURE_RE.test(t.text))
             .slice(-MAX_ERRORS)
-            .map((t) => _snippet(`${t.tool ? `${t.tool}: ` : ''}${t.text}`, SNIPPET_CHARS)),
+            .map((t) => {
+                const line = t.text.split('\n').find((l) => FAILURE_RE.test(l))?.trim() ?? t.text.trim();
+                const prefix = t.tool ? `${t.tool}: ` : '';
+                return `${prefix}${line}`.slice(0, MAX_ERROR_CHARS);
+            }),
     );
 
     // Key decisions — decision-pattern assistant turns, last 5.
@@ -396,6 +421,16 @@ export function build_handoff(
         }
         for (const s of sections) {
             lines.push('', `## ${s.title}`, '');
+            if (s.title === 'Resume pointer') {
+                // Precision rules (Phase 3.1), rendered where the successor
+                // reads them rather than filed in a doc nobody opens.
+                lines.push(
+                    '> Precision contract: identify code by signature or `path:line`, never by',
+                    '> description; quote error strings verbatim; give every resume step its',
+                    '> expected outcome, so "done" is checkable rather than felt.',
+                    '',
+                );
+            }
             if (s.items.length === 0) {
                 if (s.verbatim && verbatim.withheldLines > 0) {
                     lines.push(`- [${verbatim.withheldLines} line(s) withheld by privacy floor]`);

package/src/scripts/_cli/handoff_sessions.ts

@@ -19,6 +19,11 @@
  * De-dup: native-store sessions whose platform id maps (via
  * `derive_session_tag`) to a chat-history bucket are dropped — the
  * chat-history entry wins.
+ *
+ * Two exclusions then apply to the merged list (road-to-cost-parity-3
+ * Phase 1): the ISSUING session, by exact id and never heuristically, and
+ * every candidate holding nothing worth resuming (`is_substantive`). Both
+ * fail OPEN — an unknown lists.
  */
 
 import * as fs from 'node:fs';
@@ -26,10 +31,35 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 
 import { derive_session_tag, list_sessions, read_entries } from '../chat_history.js';
+import { eolSessionKey, readEolCounters, type StoredEolCounters } from '../_lib/session_eol.js';
 
 export const DEFAULT_CAP = 15;
+/**
+ * Per-source over-fetch factor. The exclusions run after the per-source cap,
+ * so fetching exactly `cap` lets a filtered candidate consume a slot no
+ * eligible session can reclaim. 3× is a backfill margin, not a measurement:
+ * on the observed store 10 of 217 sessions are filtered (~5%), so 3× covers
+ * that comfortably while keeping the per-file scan bounded.
+ */
+const FETCH_OVERSHOOT = 3;
 const SUMMARY_SNIPPET_CHARS = 120;
 
+/**
+ * Committed substantive-content floor, in parsed transcript tokens (billable
+ * input of the last main-chain assistant record, per `cc_transcript.ts`) — the
+ * OR-arm for a session that produced real discussion without ever calling a
+ * tool.
+ *
+ * Derivation (`agents/evidence/analysis/handoff-substantive-threshold.md`,
+ * 217 sessions of the local Claude store, 2026-08-10): 206 of the 207 sessions
+ * carrying an assistant record also carry a `tool_use` block, so this arm
+ * serves the ~0.5 % tail and the hosts whose transcripts log no tool blocks at
+ * all. 10 000 sits **25× below** the p10 of real working sessions (254 939),
+ * so it cannot hide one, and above a single trivial exchange. Changing it is a
+ * PR citing evidence, never a drive-by edit.
+ */
+export const SUBSTANTIVE_TOKEN_FLOOR = 10_000;
+
 export type HandoffSource = 'chat-history' | 'claude-transcript' | 'codex-session';
 
 export interface HandoffSession {
@@ -55,6 +85,21 @@ export interface ListOptions {
     codexSessionsRoot?: string;
     /** Max sessions per source AND in the merged result. Default 15. */
     cap?: number;
+    /**
+     * The ISSUING session's id — excluded from the result unconditionally.
+     *
+     * Default: `AGENT_SESSION_ID` (this package's own envelope convention),
+     * else `CLAUDE_CODE_SESSION_ID`. The second name is **measured, not
+     * guessed**: a live Claude Code session (host 2026-08-10) exports
+     * `CLAUDE_CODE_SESSION_ID` into every Bash tool call and its value is the
+     * session uuid that also names the transcript file — a plausible-looking
+     * `CLAUDE_SESSION_ID` is not exported and would leave this filter inert.
+     *
+     * Pass `null` to disable (a caller that genuinely is not a session).
+     */
+    selfSessionId?: string | null;
+    /** Workspace root holding `agents/runtime/state/session-eol/`. Default: `cwd`. */
+    workspaceRoot?: string;
 }
 
 /** Mirrors the Claude Code project-dir naming: `/` and `.` → `-`. */
@@ -408,28 +453,114 @@ function _sort_key(s: HandoffSession): string {
     return s.endedAt ?? s.startedAt ?? '';
 }
 
+/**
+ * Does this session hold anything worth resuming?
+ *
+ * `≥ 1 assistant turn AND (≥ 1 tool call OR parsed tokens ≥ the committed
+ * floor)`, read from the counts-only session-eol state.
+ *
+ * **Fail-open, deliberately** (Phase 1.2): absent, unreadable or mis-shaped
+ * state LISTS the candidate rather than filtering it, and a `tool_calls` key
+ * missing from a state file written before that counter existed reads as
+ * *unknown*, never as zero. A wrongly listed candidate is noise the user
+ * scrolls past; a wrongly hidden one is data loss they cannot even see.
+ */
+export function is_substantive(counters: StoredEolCounters | null): boolean {
+    if (counters === null) return true;
+    // Every "unknown" below is a NUMBER test, not an `=== undefined` test.
+    // Absent, null and NaN are all unknown, and each one reaches this code by
+    // a real path: a state file written before the counter existed is absent,
+    // `JSON.stringify` turns NaN into null on the way to disk, and a
+    // half-written file yields a parseable object with missing keys. Reading
+    // any of them as "counted zero" hides a session that did real work.
+    if (!Number.isFinite(counters.assistant_records)) return true;
+    if ((counters.assistant_records as number) < 1) return false;
+    if (!Number.isFinite(counters.tool_calls)) return true;
+    if ((counters.tool_calls as number) >= 1) return true;
+    if (!Number.isFinite(counters.final_context_tokens)) return true;
+    return (counters.final_context_tokens as number) >= SUBSTANTIVE_TOKEN_FLOOR;
+}
+
+function _derive_tag(id: string): string | null {
+    try {
+        return derive_session_tag(id);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * The state file is keyed on the RAW session id (or transcript path) the hook
+ * saw. A chat-history bucket carries only the derived tag, so the native scan
+ * — which holds both — supplies the raw identity for those buckets.
+ */
+function _counters_for(
+    session: HandoffSession,
+    byTag: Map<string, HandoffSession>,
+    workspaceRoot: string,
+): StoredEolCounters | null {
+    const native = session.source === 'chat-history' ? byTag.get(session.id) : session;
+    const candidates = [
+        ...(session.source === 'chat-history' ? [] : [session.id]),
+        native?.id,
+        native?.transcriptPath,
+    ];
+    for (const candidate of candidates) {
+        if (!candidate) continue;
+        const counters = readEolCounters(workspaceRoot, eolSessionKey(candidate));
+        if (counters !== null) return counters;
+    }
+    return null;
+}
+
 /**
  * Unified newest-first session list. Native-store sessions whose platform
  * id maps to an existing chat-history bucket are dropped (chat-history is
  * the primary source).
+ *
+ * Two exclusions apply to the merged list: the ISSUING session, by exact id
+ * (never heuristically — a heuristic here hides a session the user wanted),
+ * and every candidate `is_substantive` rejects.
  */
 export function list_handoff_sessions(opts: ListOptions = {}): HandoffSession[] {
     const cap = opts.cap ?? DEFAULT_CAP;
+    const workspaceRoot = opts.workspaceRoot ?? opts.cwd ?? process.cwd();
+    const selfId =
+        opts.selfSessionId === null
+            ? null
+            : (opts.selfSessionId ??
+              process.env.AGENT_SESSION_ID ??
+              process.env.CLAUDE_CODE_SESSION_ID ??
+              null);
+    const selfTag = selfId ? _derive_tag(selfId) : null;
+
     const primary = _chat_history_sessions(opts);
     const knownTags = new Set(primary.map((s) => s.id));
 
-    const native = [
-        ..._claude_transcript_sessions(opts, cap),
-        ..._codex_sessions(opts, cap),
-    ].filter((s) => {
-        try {
-            return !knownTags.has(derive_session_tag(s.id));
-        } catch {
-            return true;
-        }
+    // Over-fetch per source, because the two filters below run AFTER it and
+    // the issuing session is by construction among the newest — with a
+    // per-source cap of exactly `cap`, the caller always burns a slot and
+    // every filtered empty session burns another, so a substantive session
+    // just outside the window is silently dropped instead of backfilled.
+    // That is the hidden-session direction Phase 1.2 calls data loss.
+    const fetchCap = cap * FETCH_OVERSHOOT;
+    const nativeAll = [
+        ..._claude_transcript_sessions(opts, fetchCap),
+        ..._codex_sessions(opts, fetchCap),
+    ];
+    const byTag = new Map<string, HandoffSession>();
+    for (const s of nativeAll) {
+        const tag = _derive_tag(s.id);
+        if (tag) byTag.set(tag, s);
+    }
+    const native = nativeAll.filter((s) => {
+        const tag = _derive_tag(s.id);
+        return tag === null || !knownTags.has(tag);
     });
 
     return [...primary, ...native]
+        .filter((s) => s.id !== selfId && (selfTag === null || s.id !== selfTag))
+        .filter((s) => is_substantive(_counters_for(s, byTag, workspaceRoot)))
         .sort((a, b) => (_sort_key(a) < _sort_key(b) ? 1 : _sort_key(a) > _sort_key(b) ? -1 : 0))
         .slice(0, cap);
 }

package/src/scripts/_lib/agent_settings.ts

@@ -9,6 +9,7 @@
  *
  * Resolution order (deepest wins; user-global is whitelist-filtered only):
  *
+ *   N+1. `src/config/agent-settings.template.yml`     (shipped defaults; base)
  *   N.   `~/.event4u/agent-config/agent-settings.yml` (user-global; whitelist only)
  *   N-1. `<repo-root>/.agent-settings.yml`            (project-wide; all keys)
  *   N-2. `<intermediate-dir>/.agent-settings.yml`     (subsystem-scoped; all keys)
@@ -36,13 +37,22 @@
  * - YAML parse failure / unreadable file → defaults, logged at WARNING.
  * - Missing files → defaults.
  * - No file is ever created or written by this module.
+ *
+ * The template-defaults base ({@link template_defaults}) gives this path the
+ * guarantee the server read path already had: a key absent from every layer
+ * resolves to its shipped default rather than `undefined`. Two sets are
+ * excluded from it — the `settingsCarveOut` keys, whose absence deliberately
+ * means something else, and placeholder-valued leaves the installer fills.
+ * An unreadable template degrades to the pre-existing empty-defaults behaviour.
  */
 import { createRequire } from 'node:module';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import * as user_global_paths from './user_global_paths.js';
+import { carveOutKeys } from '../../shared/settingsCarveOut.js';
 import type * as YamlModule from 'yaml';
 
 // ESM has no `require`; `createRequire(import.meta.url)` restores it so the
@@ -286,7 +296,106 @@ export const MERGEABLE_KEYS: readonly string[] = [
     'knowledge.global_sharing.freshness.stale_after_days',
 ];
 
-const _DEFAULTS: SettingsDict = {};
+/** The shipped template, relative to the package root. */
+const TEMPLATE_RELATIVE = path.join('src', 'config', 'agent-settings.template.yml');
+
+/**
+ * Package root: `src/scripts/_lib/agent_settings.ts` → three levels up.
+ * Same idiom as `cli_wrapper.ts:28`, and it holds in an installed consumer
+ * too because `src/config/` ships (`package.json` `files[]`).
+ */
+const _PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+
+/** Default template path — overridable per call for tests. */
+export function default_template_path(): string {
+    return path.join(_PACKAGE_ROOT, TEMPLATE_RELATIVE);
+}
+
+/**
+ * A leaf whose template value is still an installer placeholder
+ * (`__RULE_LOADING_TIER__`, `__CHAT_HISTORY_FREQUENCY__`, …). The installer
+ * substitutes these from the chosen profile preset; the template alone does
+ * not carry a usable default, so the defaults layer must not inject one.
+ *
+ * Matched by shape rather than against `TEMPLATE_PLACEHOLDER_DEFAULTS`
+ * (`src/server/io/yamlIO.ts:139`) on purpose: the scripts family does not
+ * import from the server family, and a duplicated map would be one more thing
+ * that can drift. A new placeholder is covered the day it is added.
+ */
+function _is_placeholder(value: SettingsValue): boolean {
+    return typeof value === 'string' && /^__[A-Z0-9_]+__$/.test(value);
+}
+
+/**
+ * Prune a parsed template into the tree the defaults layer may contribute:
+ * every placeholder-valued leaf and every carve-out key removed, and any
+ * branch that empties out as a result dropped with them.
+ */
+function _prune_template(tree: SettingsDict, excluded: ReadonlySet<string>, prefix = ''): SettingsDict {
+    const out: SettingsDict = {};
+    for (const [key, value] of Object.entries(tree)) {
+        const dotted = prefix === '' ? key : `${prefix}.${key}`;
+        if (excluded.has(dotted) || _is_placeholder(value)) {
+            continue;
+        }
+        if (_is_plain_dict(value)) {
+            const child = _prune_template(value as SettingsDict, excluded, dotted);
+            if (Object.keys(child).length > 0) {
+                out[key] = child;
+            }
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+}
+
+/** Parsed-and-pruned template, memoised for the default path only. */
+let _template_defaults_cache: SettingsDict | null = null;
+
+/**
+ * The template-defaults layer — the base every real settings layer sits on.
+ *
+ * Gives the scripts read path the guarantee the server read path already has:
+ * a key absent from every layer resolves to its shipped default instead of
+ * `undefined`. Two exclusions, both load-bearing:
+ *
+ * - **Carve-out keys** (`src/shared/settingsCarveOut.ts`). For these an absent
+ *   key deliberately resolves to something other than the template default,
+ *   and injecting the default here would flip existing installs — precisely
+ *   the silent narrowing that module exists to prevent (`settingsCarveOut.ts:18-21`).
+ * - **Placeholder-valued leaves**, which carry no default until the installer
+ *   substitutes them.
+ *
+ * Tolerant like the rest of this module: an unreadable or malformed template
+ * yields `{}`, i.e. exactly the pre-existing no-defaults behaviour.
+ *
+ * The result is a full `_deepcopy`, never `_deep_copy_defaults`. The latter is
+ * built on `_deep_merge`, which assigns a nested value by REFERENCE whenever
+ * the destination has no dict at that key — so its "copy" of a fresh `{}`
+ * shares every sub-tree with the source. The caller then merges the real
+ * layers into that shared sub-tree and silently rewrites the cache: the first
+ * settings file read in a process would become the defaults every later read
+ * sees. The predecessor `_DEFAULTS` was `{}`, so the hazard existed but had
+ * nothing to poison; a populated base makes it live.
+ */
+export function template_defaults(template_path?: string): SettingsDict {
+    const use_cache = template_path === undefined;
+    if (use_cache && _template_defaults_cache !== null) {
+        return _deepcopy(_template_defaults_cache);
+    }
+    const parsed = _read_yaml(template_path ?? default_template_path()) ?? {};
+    const pruned = _prune_template(parsed, new Set(carveOutKeys()));
+    if (use_cache) {
+        _template_defaults_cache = pruned;
+    }
+    return _deepcopy(pruned);
+}
+
+/** Drop the memoised template — tests only; production reads it once per process. */
+export function _reset_template_defaults_cache(): void {
+    _template_defaults_cache = null;
+}
 
 /**
  * Defaults applied by `get_modules_config` when a key is absent from both
@@ -730,12 +839,17 @@ export function load_agent_settings(
         user_global_path?: string | null;
         verbose?: boolean;
         cwd?: string | null;
+        template_path?: string | null;
     } = {},
 ): SettingsDict {
     const project_path = options.project_path ?? null;
     const user_global_path = options.user_global_path ?? null;
     const verbose = options.verbose ?? false;
     const cwd = options.cwd ?? null;
+    // Same caller-override contract as `project_path` / `user_global_path`:
+    // a test or tool that pins every other input can pin the defaults base
+    // too, and point it at a nonexistent file to isolate the cascade.
+    const template_path = options.template_path ?? null;
 
     // An explicit path is a caller override (tests, tooling) and stays single;
     // otherwise every user-global file merges in precedence order.
@@ -754,7 +868,10 @@ export function load_agent_settings(
 
     const cascade = _resolve_cascade_paths(cwd, project_path);
 
-    const merged: SettingsDict = _deep_copy_defaults(_DEFAULTS);
+    // Template defaults sit BELOW every real layer — never above one. The
+    // precedence here is the inverse of the server family's, so the order of
+    // these three statements is the whole contract.
+    const merged: SettingsDict = template_defaults(template_path ?? undefined);
     _deep_merge(merged, user_global_filtered);
     for (const p of cascade) {
         const layer = _read_yaml(p) ?? {};