@event4u/agent-config 9.31.0 → 9.33.0

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

@@ -64,6 +64,20 @@ export interface RecordInput {
     dispatch_tokens?: number | null | undefined;
     /** The orchestrator's own tier — the baseline the downshift cost-% measures against. */
     session_tier?: string | null | undefined;
+    /**
+     * The model id that was ASKED for. `tier_chosen`, `tier_source`,
+     * `session_tier` and the downshift cost-percentage are all read off the
+     * requested tier, so on an alias or a provider substitution every one of
+     * them attributes the saving to a model that never ran. Recording the
+     * requested id beside the served one is what makes that detectable.
+     */
+    model_requested?: string | null | undefined;
+    /**
+     * The model id the provider reported SERVING. `''` / null when the
+     * transport reports none (every CLI client) — absent is honest, not a
+     * defect, and is NOT a divergence.
+     */
+    model_served?: string | null | undefined;
     dispatch_outcome?: DispatchOutcome | undefined;
     verify_mode?: VerifyMode | undefined;
     /** QUALITY: subagent return adopted without parent rework. Optional boolean (null = not measured). */
@@ -176,6 +190,23 @@ function isInt(n: unknown): n is number {
     return typeof n === 'number' && Number.isFinite(n) && Number.isInteger(n);
 }
 
+/**
+ * Did the provider answer with a different model than the one requested?
+ *
+ * `null` — not decidable — whenever either id is missing or empty. That is the
+ * common case (every CLI transport reports no served id) and it is not the
+ * same as "no divergence": a `false` here would claim a comparison that never
+ * happened, which is the exact mis-attribution this field exists to expose.
+ */
+function modelDivergent(
+    requested: string | null | undefined,
+    served: string | null | undefined,
+): boolean | null {
+    if (typeof requested !== 'string' || typeof served !== 'string') return null;
+    if (!requested || !served) return null;
+    return requested !== served;
+}
+
 /**
  * Build + validate the audit-log-v1 line. Returns `{line, errors}`; when
  * `errors` is non-empty, `line` is null and the caller must NOT write.
@@ -290,6 +321,13 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
         errors.push(`trigger_arm_earlier must be one of ${TRIGGER_ARMS.join(' | ')} (or omitted / null when neither arm fired)`);
     }
 
+    for (const [key, v] of [
+        ['model_requested', input.model_requested],
+        ['model_served', input.model_served],
+    ] as const) {
+        if (v != null && typeof v !== 'string') errors.push(`${key} must be a string or omitted`);
+    }
+
     if (!input.ts) errors.push('ts (ISO-8601 UTC) is required');
     if (!input.id) errors.push('id (ULID or content hash) is required');
 
@@ -310,6 +348,13 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
         tier_source: input.tier_source ?? null,
         dispatch_tokens: input.dispatch_tokens ?? null,
         session_tier: input.session_tier ?? null,
+        // Served-model attribution. `model_divergent` is DERIVED, never
+        // supplied: `null` when either id is absent — a transport that reports
+        // no served id cannot disagree with anything, and calling that `false`
+        // would read as "checked, and they matched".
+        model_requested: input.model_requested ?? null,
+        model_served: input.model_served ?? null,
+        model_divergent: modelDivergent(input.model_requested, input.model_served),
         first_pass_success: input.first_pass_success ?? null,
         escalated: input.escalated ?? null,
         agent_combo: input.agent_combo ?? [],

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;