@event4u/agent-config 9.30.0 → 9.32.0

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,6 +89,116 @@ 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;
+}
+
+/**
+ * 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.
+ *
+ * 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 splitFrontmatter(text: string): FrontmatterSplit {
+    if (!text.startsWith('---')) return { hadFrontmatter: false, frontmatter: '', body: text };
+    const end = text.indexOf('\n---', 3);
+    if (end === -1) return { hadFrontmatter: false, frontmatter: '', body: text };
+    const afterFence = text.indexOf('\n', end + 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;
+}
+
+/**
+ * Is the ONLY difference between these two copies inside the frontmatter block?
+ *
+ * WHY THIS IS SEPARATE FROM `comparePair`, AND MUST STAY SEPARATE
+ * --------------------------------------------------------------
+ * `comparePair` answers *can a byte-identity dedup skip this pair* — it is the
+ * dedup predicate, and a frontmatter difference is a real byte difference, so
+ * folding this in would relax the predicate that
+ * `agents/settings/contexts/dedup-reachability-refusal.md` deliberately keeps
+ * strict. `measure_scope_dedup` asks exactly that question and its arithmetic
+ * stays untouched.
+ *
+ * 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 {
+    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 {
     files: number;
     /**

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 };
+}

package/src/scripts/_lib/session_eol.ts

@@ -30,7 +30,9 @@
  * 50 MB `isSafeTranscriptPath` cap away.
  */
 
+import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
+import * as path from 'node:path';
 
 import { billableInputTokens } from './cc_transcript.js';
 
@@ -57,6 +59,13 @@ export interface EolCounters {
     turns: number;
     /** Main-chain assistant records carrying a `usage` block. */
     assistant_records: number;
+    /**
+     * Main-chain assistant records carrying at least one `tool_use` content
+     * block. Added after the initial schema, so a state file written before
+     * it is missing the key — readers MUST treat `undefined` as *unknown*,
+     * never as zero (`is_substantive` in `_cli/handoff_sessions.ts` does).
+     */
+    tool_calls: number;
     /** Billable input tokens of the LAST main-chain assistant record — the fill level. */
     final_context_tokens: number | null;
     /** `timestamp` of that record. */
@@ -75,6 +84,7 @@ export function emptyCounters(): EolCounters {
         scanned_bytes: 0,
         turns: 0,
         assistant_records: 0,
+        tool_calls: 0,
         final_context_tokens: null,
         final_context_at: null,
         compactions: [],
@@ -165,6 +175,26 @@ export function scanEolSlice(text: string, prior: EolCounters): EolCounters {
         }
         if (record['type'] === 'assistant') {
             const message = record['message'];
+            const content =
+                typeof message === 'object' && message !== null
+                    ? (message as Record<string, unknown>)['content']
+                    : undefined;
+            if (
+                Array.isArray(content) &&
+                content.some(
+                    (b) =>
+                        typeof b === 'object' &&
+                        b !== null &&
+                        (b as Record<string, unknown>)['type'] === 'tool_use',
+                )
+            ) {
+                // `{...prior}` carries `undefined` forward from a state file
+                // written before this counter existed, and `undefined + 1` is
+                // NaN — which `JSON.stringify` writes as `null`, i.e. as a
+                // counted zero rather than as the unknown it is. Coerce here
+                // so the writer can never persist that.
+                next.tool_calls = (Number.isFinite(next.tool_calls) ? next.tool_calls : 0) + 1;
+            }
             const usage =
                 typeof message === 'object' && message !== null
                     ? ((message as Record<string, unknown>)['usage'] as Record<string, unknown> | undefined)
@@ -184,6 +214,61 @@ export function scanEolSlice(text: string, prior: EolCounters): EolCounters {
     return next;
 }
 
+// ---------------------------------------------------------------------
+// State location — one derivation, shared by the writer (the Stop-slot
+// concern) and every reader (`agent-config handoff`).
+// ---------------------------------------------------------------------
+
+/** Directory holding the per-session counts-only state files. */
+export function eolStateDir(workspaceRoot: string): string {
+    return path.join(workspaceRoot, 'agents', 'runtime', 'state', 'session-eol');
+}
+
+/** Absolute path of one session's state file. */
+export function eolStateFile(workspaceRoot: string, sessionKey: string): string {
+    return path.join(eolStateDir(workspaceRoot), `${sessionKey}.json`);
+}
+
+/**
+ * The state-file key for a session: sha256 of the raw session id, or of the
+ * transcript path when no id is known. Hashed, never raw — the filename must
+ * not carry an identifier.
+ */
+export function eolSessionKey(raw: string | null | undefined): string {
+    return crypto.createHash('sha256').update(raw || 'unknown-session').digest('hex');
+}
+
+/**
+ * Counters as they come off DISK. `tool_calls` is optional here and required
+ * in `EolCounters` on purpose: a file written before that counter existed
+ * carries no key, and "the writer never counted" must stay distinguishable
+ * from "the writer counted zero".
+ */
+export type StoredEolCounters = Omit<EolCounters, 'tool_calls'> & { tool_calls?: number };
+
+/**
+ * Read one session's counters. Returns `null` for absent, unreadable, or
+ * mis-shaped state — the caller decides what that means, and every current
+ * caller fails OPEN (a wrongly listed session is noise; a wrongly hidden one
+ * is data loss).
+ */
+export function readEolCounters(
+    workspaceRoot: string,
+    sessionKey: string,
+): StoredEolCounters | null {
+    try {
+        const raw = fs.readFileSync(eolStateFile(workspaceRoot, sessionKey), 'utf-8');
+        const parsed = JSON.parse(raw) as Record<string, unknown>;
+        const counters = parsed['counters'];
+        if (typeof counters !== 'object' || counters === null || Array.isArray(counters)) {
+            return null;
+        }
+        return counters as StoredEolCounters;
+    } catch {
+        return null;
+    }
+}
+
 export interface NewLinesRead {
     /** The complete lines appended since `fromByte` (possibly empty). */
     text: string;