@event4u/agent-config 9.31.0 → 9.32.0

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/carrier_divergence.ts

@@ -22,8 +22,16 @@
  * provenance-only difference survives even a perfect version alignment. Keeping
  * it apart from class 3 is what turns a bare "0 identical twins" into an answer:
  * `provenanceOnly == shared` means aligning versions would buy nothing, and
- * `bodyDiff > 0` means the two carriers are delivering different text — the only
- * class where a reader has to act.
+ * `bodyDiff > 0` means the two carriers are delivering different bytes.
+ *
+ * `bodyDiff > 0` is NOT the same as "a reader has to act", and an earlier version
+ * of this paragraph said it was. Measured 2026-08-10: all 109 shared rules
+ * classified `bodyDiff` and NONE of them differed in prose. The reader-facing
+ * split lives in `report_carrier_divergence`, which subdivides this class into
+ * prose divergence (act), a `paths:`-scope disagreement (act — it changes WHEN a
+ * rule loads), and a metadata-only difference (do not act). The three-way split
+ * below stays three-way on purpose: it is the DEDUP predicate, and every class
+ * here is a real byte difference.
  *
  * NOT A LICENCE TO DEDUP. Classifying a pair `provenance-only` says the bodies
  * match; it does NOT say the rule is safe to drop from one carrier. Byte-identity
@@ -81,24 +89,47 @@ export function comparePair(a: Buffer, b: Buffer): PairVerdict {
     return 'body-diff';
 }
 
+/** One rule file, split at its frontmatter fence. */
+export interface FrontmatterSplit {
+    /** `true` only when a terminated `---` fence was actually found. */
+    hadFrontmatter: boolean;
+    /** The fence block WITHOUT its delimiters, or `''` when there is none. */
+    frontmatter: string;
+    /** Everything after the fence — the prose the host delivers. */
+    body: string;
+}
+
 /**
- * Drop a leading YAML frontmatter block, returning the prose the host actually
- * delivers.
+ * THE fence parser. One definition, for the reason the header gives: a second
+ * copy is how two surfaces drift into disagreeing about what frontmatter is.
  *
- * A file with no `---` fence, or an unterminated one, is returned unchanged —
- * the same tolerance `report_carrier_divergence`'s own `type:` reader applies,
- * because a malformed fence must not silently swallow a rule's whole text.
+ * An absent or UNTERMINATED fence yields `hadFrontmatter: false` and the whole
+ * text as body. That is deliberate and it is the safe direction: a malformed
+ * fence must not silently swallow a rule's governed text. Note this is the
+ * OPPOSITE of what a naive `type:` reader does — treating the whole file as
+ * frontmatter — and that asymmetry was a live inconsistency between this
+ * function and `report_carrier_divergence._ruleType` until the latter was moved
+ * onto this parser.
  */
-export function stripFrontmatter(text: string): string {
-    if (!text.startsWith('---')) return text;
+export function splitFrontmatter(text: string): FrontmatterSplit {
+    if (!text.startsWith('---')) return { hadFrontmatter: false, frontmatter: '', body: text };
     const end = text.indexOf('\n---', 3);
-    if (end === -1) return text;
+    if (end === -1) return { hadFrontmatter: false, frontmatter: '', body: text };
     const afterFence = text.indexOf('\n', end + 1);
-    return afterFence === -1 ? '' : text.slice(afterFence + 1);
+    return {
+        hadFrontmatter: true,
+        frontmatter: text.slice(3, end),
+        body: afterFence === -1 ? '' : text.slice(afterFence + 1),
+    };
+}
+
+/** The prose a rule file delivers, with any frontmatter block removed. */
+export function stripFrontmatter(text: string): string {
+    return splitFrontmatter(text).body;
 }
 
 /**
- * Do the two copies carry the same governed PROSE, ignoring frontmatter?
+ * Is the ONLY difference between these two copies inside the frontmatter block?
  *
  * WHY THIS IS SEPARATE FROM `comparePair`, AND MUST STAY SEPARATE
  * --------------------------------------------------------------
@@ -109,23 +140,63 @@ export function stripFrontmatter(text: string): string {
  * strict. `measure_scope_dedup` asks exactly that question and its arithmetic
  * stays untouched.
  *
- * This answers the different, reader-facing question `report_carrier_divergence`
- * asks: *must a human act on this pair*. Measured 2026-08-10 over the live
- * carriers at commit `a5b2f4cb7`: 109 shared rules, **0** byte-identical, **109**
- * classified `body-diff` — and after this strip, **0** of the 109 differ in
- * prose. The whole divergence was the metadata block. Reporting that as body
- * divergence manufactures the one class the report tells a reader to act on,
- * which is precisely the failure `compareCarriers` already refuses to commit for
- * an unreadable copy.
- *
- * Edge trimming only, on purpose: the frontmatter fence leaves the two sides one
- * leading newline apart, and that is not a content difference. Internal
- * whitespace and line endings are NOT normalized — a CRLF-vs-LF body stays a
- * prose difference, so this stays no softer than the dedup predicate on the text
- * the host reads.
+ * WHAT IT PROVES, EXACTLY — AND WHY NOT `trim()`
+ * ---------------------------------------------
+ * Two conditions, both required:
+ *
+ *   1. at least one side actually HAD a frontmatter block. Without this the
+ *      predicate would answer "the prose matches" for a pair with no frontmatter
+ *      anywhere, and the caller would print "differs only in frontmatter" about
+ *      a difference that is not in any frontmatter.
+ *   2. the bodies match after removing LEADING newlines only. The fence
+ *      necessarily leaves the stripped side one newline ahead, so that one
+ *      character is a parsing artefact. A `trim()` would additionally absorb a
+ *      TRAILING difference, which is a real byte difference no fence explains —
+ *      and it was measured to be unnecessary: all 109 live pairs on 2026-08-10
+ *      matched on leading-only, 0 needed a trailing trim.
+ *
+ * Nothing else is normalized. Internal whitespace and line endings stay
+ * significant, so a CRLF-vs-LF body is still a prose difference and this stays
+ * no softer than the dedup predicate on the text the host reads.
  */
 export function proseEqual(a: string, b: string): boolean {
-    return stripFrontmatter(a).trim() === stripFrontmatter(b).trim();
+    const sa = splitFrontmatter(a);
+    const sb = splitFrontmatter(b);
+    if (!sa.hadFrontmatter && !sb.hadFrontmatter) return false;
+    const leading = /^\n+/;
+    return sa.body.replace(leading, '') === sb.body.replace(leading, '');
+}
+
+/**
+ * The `paths:` block of a rule's frontmatter, normalized, or `null` when absent.
+ *
+ * `paths` is the ONE frontmatter key this host reads
+ * (`agents/evidence/analysis/claude-code-rules-dir-contract.md`), and it decides
+ * WHEN a rule loads: with it, the rule fires when a matching file is read and is
+ * not re-injected after `/compact`; without it, the rule loads unconditionally
+ * at launch. So two carriers that disagree here deliver the same text on
+ * different schedules, which a reader must act on even though the prose is
+ * identical. Measured 2026-08-10: 24 of the 109 shared rules carry `paths:` in
+ * the project copy and NONE in the global copy, so on a machine with both the
+ * always-on global copy defeats the project copy's scoping for all 24.
+ *
+ * Normalization is deliberately shallow — the key line plus its indented
+ * continuation, whitespace-collapsed. It answers "do these two agree" and is not
+ * a YAML parser; a reordered list reads as a difference, which is the
+ * conservative direction for a report that asks a human to look.
+ */
+export function frontmatterPaths(text: string): string | null {
+    const { hadFrontmatter, frontmatter } = splitFrontmatter(text);
+    if (!hadFrontmatter) return null;
+    const lines = frontmatter.split('\n');
+    const start = lines.findIndex((l) => /^paths:/.test(l));
+    if (start === -1) return null;
+    const block = [lines[start] as string];
+    for (const line of lines.slice(start + 1)) {
+        if (/^\s/.test(line) && line.trim() !== '') block.push(line);
+        else break;
+    }
+    return block.map((l) => l.trim()).join(' ');
 }
 
 export interface RuleDirCensus {

package/src/scripts/_lib/envelope_grounding.ts

@@ -0,0 +1,206 @@
+/**
+ * Deterministic environment grounding for the handoff envelope
+ * (road-to-cost-parity-3 Phase 3.2–3.3).
+ *
+ * The factual half of an envelope — where the work was, on what branch, at
+ * which commit, what was uncommitted, what was last verified — is collected
+ * by THIS module, not composed by a model. Scripted facts are free and
+ * verifiable; deriving them through a model is the right idea at the wrong
+ * price, and a model-composed "branch" is a claim rather than a reading.
+ *
+ * Every git read goes through `gitEnv()`. An inherited `GIT_DIR` (which any
+ * hook exports) silently redirects `git` at the wrong repository, which would
+ * make the drift anchor confidently wrong — the one failure mode worse than
+ * having no anchor.
+ */
+
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { git_common_dir } from './git_common_dir.js';
+import { gitEnv } from './git_env.js';
+
+/** Longest ref/line this module will emit — mirrors the envelope's own caps. */
+const MAX_FIELD_CHARS = 200;
+/** Uncommitted paths are a pointer list, not a diff. */
+const MAX_PATHS = 40;
+
+function git(root: string, args: string[]): string | null {
+    try {
+        return execFileSync('git', args, {
+            cwd: root,
+            env: gitEnv(),
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Canonical form of a repo identity, so the SAME repository never reads as
+ * two different ones. Committed rules, in order:
+ *
+ *   1. scheme stripped (`https://`, `ssh://`, `git://`)
+ *   2. credentials stripped (`user:pass@`, `git@`)
+ *   3. scp-style `host:org/repo` → `host/org/repo`
+ *   4. host segment lower-cased
+ *   5. trailing `.git` and trailing `/` removed
+ *
+ * Without these, one checkout's `git@github.com:Org/Repo.git` and another's
+ * `https://github.com/org/repo` compare as drift while being the same repo —
+ * a false alarm every time, which trains the reader to ignore the real one.
+ */
+export function canonicalizeRepoIdentity(raw: string): string {
+    let s = raw.trim();
+    s = s.replace(/^[a-z][a-z0-9+.-]*:\/\//i, ''); // scheme
+    s = s.replace(/^[^/@]+@/, ''); // credentials / ssh user
+    s = s.replace(/^([^/:]+):(?!\/)/, '$1/'); // scp-style separator
+    s = s.replace(/\/+$/, '');
+    s = s.replace(/\.git$/i, '');
+    const slash = s.indexOf('/');
+    if (slash > 0) {
+        s = s.slice(0, slash).toLowerCase() + s.slice(slash);
+    } else {
+        s = s.toLowerCase();
+    }
+    return s;
+}
+
+/** The three fields that together identify a working tree at a point in time. */
+export interface RepoAnchor {
+    repo_identity: string | null;
+    branch: string | null;
+    head: string | null;
+}
+
+/**
+ * Read the anchor for `root`.
+ *
+ * Identity is the canonicalized `origin` remote, or — when the repo has no
+ * remote — the realpath of the common git dir. Branch and HEAD alone are NOT
+ * an anchor: this repo routinely runs many worktrees, a branch name is unique
+ * in neither, and two checkouts sitting at the same commit on a same-named
+ * branch would compare as "no drift" while being different working trees.
+ */
+export function collectRepoAnchor(root: string): RepoAnchor {
+    const remote = git(root, ['config', '--get', 'remote.origin.url']);
+    let identity: string | null = null;
+    if (remote) {
+        identity = canonicalizeRepoIdentity(remote);
+    } else {
+        const common = git_common_dir(root);
+        if (common !== null) {
+            try {
+                identity = fs.realpathSync(common);
+            } catch {
+                identity = common;
+            }
+        }
+    }
+    return {
+        repo_identity: identity ? identity.slice(0, MAX_FIELD_CHARS) : null,
+        branch: git(root, ['rev-parse', '--abbrev-ref', 'HEAD']),
+        head: git(root, ['rev-parse', 'HEAD']),
+    };
+}
+
+/** The scripted fields the model never composes. */
+export interface Grounding extends RepoAnchor {
+    uncommitted_paths: string[];
+    status_summary: string | null;
+    last_verify: string | null;
+}
+
+const VERIFY_STATE_REL = path.join('agents', 'runtime', 'state', 'verify-before-complete.json');
+
+/**
+ * The last verification this workspace recorded, as one line.
+ *
+ * **What this is not:** an exit code. The roadmap step asked for "last verify
+ * exit", and nothing in the tree records one — `before_complete_hook` stores
+ * `{command, tool, at, …}` and no status. Emitting a fabricated exit would be
+ * worse than emitting less, so the field carries the command and its
+ * timestamp and says so, rather than implying a pass/fail the source never
+ * held.
+ */
+export function readLastVerify(root: string): string | null {
+    try {
+        const raw = fs.readFileSync(path.join(root, VERIFY_STATE_REL), 'utf-8');
+        const state = JSON.parse(raw) as Record<string, unknown>;
+        const lv = state['last_verification'];
+        if (typeof lv !== 'object' || lv === null || Array.isArray(lv)) return null;
+        const rec = lv as Record<string, unknown>;
+        const command = typeof rec['command'] === 'string' ? rec['command'] : null;
+        if (!command) return null;
+        const at = typeof rec['at'] === 'string' ? rec['at'] : 'unknown time';
+        return `${command} @ ${at} (no exit status is recorded anywhere)`.slice(0, MAX_FIELD_CHARS);
+    } catch {
+        return null;
+    }
+}
+
+/** Collect every scripted field. Never throws — an unreadable fact is `null`. */
+export function collectGrounding(root: string): Grounding {
+    const anchor = collectRepoAnchor(root);
+    const porcelain = git(root, ['status', '--porcelain']);
+    if (porcelain === null) {
+        // A FAILED read is not a clean tree. Collapsing the two would make
+        // this the one field in the module that asserts something it never
+        // read — and it would assert it exactly when every sibling field is
+        // null, so `describeDrift` is silent and nothing challenges it.
+        return { ...anchor, uncommitted_paths: [], status_summary: null, last_verify: readLastVerify(root) };
+    }
+    const lines = porcelain.split('\n').filter((l) => l.trim().length > 0);
+    const paths = lines
+        .map((l) => l.slice(3).trim())
+        .filter((p) => p.length > 0 && p.length <= MAX_FIELD_CHARS)
+        .slice(0, MAX_PATHS);
+    return {
+        ...anchor,
+        uncommitted_paths: paths,
+        status_summary:
+            lines.length === 0
+                ? 'clean working tree'
+                : `${lines.length} uncommitted path(s)${lines.length > MAX_PATHS ? `, first ${MAX_PATHS} listed` : ''}`,
+        last_verify: readLastVerify(root),
+    };
+}
+
+/**
+ * Compare an envelope's recorded anchor against the tree it is being injected
+ * into. Returns one line per mismatch — the consumer LEADS the injected block
+ * with them, so a stale resume can never be silent.
+ *
+ * A field the envelope never recorded produces no line: an absent anchor is
+ * an older envelope, not evidence of drift.
+ */
+export function describeDrift(envelope: unknown, actual: RepoAnchor): string[] {
+    if (typeof envelope !== 'object' || envelope === null || Array.isArray(envelope)) return [];
+    const e = envelope as Record<string, unknown>;
+    const drift: string[] = [];
+    const recordedIdentity = typeof e['repo_identity'] === 'string' ? e['repo_identity'] : null;
+    if (recordedIdentity && actual.repo_identity && recordedIdentity !== actual.repo_identity) {
+        drift.push(
+            `IDENTITY DRIFT: this envelope was written in "${recordedIdentity}", you are in ` +
+                `"${actual.repo_identity}". Re-verify every path before acting — same branch name ` +
+                `does not mean same working tree.`,
+        );
+    }
+    const recordedBranch = typeof e['branch'] === 'string' ? e['branch'] : null;
+    if (recordedBranch && actual.branch && recordedBranch !== actual.branch) {
+        drift.push(
+            `BRANCH DRIFT: envelope written on "${recordedBranch}", checkout is on "${actual.branch}".`,
+        );
+    }
+    const recordedHead = typeof e['head'] === 'string' ? e['head'] : null;
+    if (recordedHead && actual.head && recordedHead !== actual.head) {
+        drift.push(
+            `COMMIT DRIFT: envelope written at ${recordedHead.slice(0, 12)}, HEAD is now ` +
+                `${actual.head.slice(0, 12)} — re-read anything the envelope quotes.`,
+        );
+    }
+    return drift;
+}

package/src/scripts/_lib/host_capability.ts

@@ -31,6 +31,11 @@
  * parameter stays for back-compat (tests, and any caller that genuinely has a
  * host-knowledge object of its own) — no production caller passes a
  * settings-derived value into it any more.
+ *
+ * `describeHostCapabilities` (road-to-capability-answerability Phase 1.2) is
+ * the same resolution plus per-field provenance, because five of the six
+ * fields come from a committed table rather than from any live check and the
+ * `probe*` name says otherwise.
  */
 import process from 'node:process';
 
@@ -197,3 +202,77 @@ export function probeHostCapabilities(hostId: string | null | undefined): HostCa
     const probedAgentTeams = typeof flag === 'string' && flag !== '';
     return { ...base, agent_teams: base.agent_teams || probedAgentTeams };
 }
+
+/** Every manifest field that carries a capability answer (i.e. not `schema_version`). */
+export type CapabilityField = Exclude<keyof HostCapabilityManifest, 'schema_version'>;
+
+/**
+ * Where one field's resolved value came from.
+ *
+ * `registry` is deliberately NOT called "detected": a registry row is a
+ * capability this repo OBSERVED on that host once and then committed to a
+ * hardcoded table. It is an assertion about the host, checked at authoring
+ * time and never re-checked at run time. `live-probe` is the only value that
+ * was established in THIS process, from the environment. `default` means
+ * nothing answered and the all-false safe default applied.
+ */
+export type CapabilitySource = 'registry' | 'live-probe' | 'default';
+
+/** Per-field provenance for a resolved manifest. */
+export type HostCapabilitySources = Record<CapabilityField, CapabilitySource>;
+
+export interface HostCapabilityDescription {
+    manifest: HostCapabilityManifest;
+    sources: HostCapabilitySources;
+}
+
+const CAPABILITY_FIELDS: readonly CapabilityField[] = [
+    'subagent_spawn',
+    'parallel_spawn',
+    'status_polling',
+    'separate_quota_pool',
+    'agent_teams',
+    'worker_respawn',
+];
+
+/**
+ * Resolve the manifest AND say, per field, what answered it.
+ *
+ * `probeHostCapabilities` returns six booleans that look alike and are not:
+ * on the one host with a registry row, two of them come from a committed
+ * table, one can come from a live environment read, and the rest are the
+ * safe default — i.e. "we have no answer", rendered as `false`, which is
+ * indistinguishable from "we checked and it is absent". A caller deciding
+ * whether to trust `subagent_spawn: false` needs that difference, and the
+ * function name `probe*` actively suggests the wrong one.
+ *
+ * The manifest half delegates to {@link probeHostCapabilities} rather than
+ * re-deriving it, so a provenance readout can never disagree with the value
+ * the delegation layer actually gated on — the same
+ * two-readers-of-one-fact failure `routing_doctor` already records against
+ * its own pre-registry bug.
+ */
+export function describeHostCapabilities(
+    hostId: string | null | undefined,
+): HostCapabilityDescription {
+    const manifest = probeHostCapabilities(hostId);
+    const row =
+        hostId !== null && hostId !== undefined ? HOST_CAPABILITY_REGISTRY[hostId] : undefined;
+    const flag = process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
+    const probedAgentTeams = typeof flag === 'string' && flag !== '';
+
+    const sources = {} as HostCapabilitySources;
+    for (const field of CAPABILITY_FIELDS) {
+        // A row entry claims the field whatever its value: an explicit
+        // `false` in the table is an observation ("checked, absent"), which is
+        // a different fact from the default's "nobody answered".
+        if (row !== undefined && typeof row[field] === 'boolean') {
+            sources[field] = 'registry';
+        } else if (field === 'agent_teams' && probedAgentTeams) {
+            sources[field] = 'live-probe';
+        } else {
+            sources[field] = 'default';
+        }
+    }
+    return { manifest, sources };
+}