@event4u/agent-config 14.9.0 → 14.11.0

package/src/scripts/_lib/run_checkpoint.ts

@@ -57,6 +57,21 @@ export interface RunCheckpoint {
     readonly next_step: string | null;
     /** Commit the tree was on. A resume onto a different commit is normal, and visible. */
     readonly head: string | null;
+    /**
+     * The situational-awareness reading this run last took —
+     * `contextFingerprint()` over `origin/main` plus every open PR's head SHA.
+     *
+     * `road-to-roadmap-situational-awareness` § 5.6. Every other field here
+     * reports **roadmap** drift; none reported **repository** drift, so a run
+     * resumed after a long gap trusted a context reading it never re-took. A
+     * disagreement here forces a re-probe before the first step.
+     *
+     * Optional: a checkpoint written before this field existed, or by a run that
+     * could not reach the probe, is still a valid checkpoint. Absent means "not
+     * known", never "unchanged" — `verifyCheckpoint` treats a null on either
+     * side as unknown, the same way it already treats `head`.
+     */
+    readonly context_fingerprint?: string | null;
     readonly written_at: string;
 }
 
@@ -109,6 +124,16 @@ export interface BuildOptions {
     /** Injected so a test does not depend on the ambient git state. */
     readonly head?: string | null;
     readonly now?: () => Date;
+    /**
+     * The run's situational-awareness fingerprint
+     * (`roadmap:context --fingerprint`). Injected rather than read here, so this
+     * library keeps its no-subprocess property — `readHead` reads `.git`
+     * directly for the same reason, and the probe cannot.
+     *
+     * Omitted → the field is absent, and a resume reports "not known" rather
+     * than asserting the repository stood still.
+     */
+    readonly contextFingerprint?: string | null;
 }
 
 /**
@@ -204,6 +229,12 @@ export function buildCheckpoint(
         parked_steps: counts.parked,
         next_step: counts.next,
         head: opts.head ?? readHead(repoRoot),
+        // Absent rather than null when nothing was supplied: a checkpoint that
+        // predates this field and one written without a probe are the same
+        // state, and both must read as "not known".
+        ...(opts.contextFingerprint !== undefined
+            ? { context_fingerprint: opts.contextFingerprint }
+            : {}),
         written_at: (opts.now ?? ((): Date => new Date()))().toISOString(),
     };
 }
@@ -310,7 +341,16 @@ export interface VerifyResult {
  * 4, actual 3" tells it a step landed after the checkpoint was written and
  * which count to trust.
  */
-export function verifyCheckpoint(repoRoot: string, cp: RunCheckpoint): VerifyResult {
+export function verifyCheckpoint(
+    repoRoot: string,
+    cp: RunCheckpoint,
+    /**
+     * The fingerprint a fresh `roadmap:context --fingerprint` returned, when the
+     * resumed run took one. Omitted → the field reports "not known" rather than
+     * asserting the repository stood still.
+     */
+    currentFingerprint?: string | null,
+): VerifyResult {
     let text: string;
     try {
         text = fs.readFileSync(roadmapPath(repoRoot, cp.roadmap), 'utf-8');
@@ -349,6 +389,19 @@ export function verifyCheckpoint(repoRoot: string, cp: RunCheckpoint): VerifyRes
             // than a missing one: it trains the reader to skip the line.
             agrees: cp.head === null || head === null || cp.head === head,
         },
+        // Repository drift, which no other field here reports. The `actual` is
+        // supplied by the caller (the probe is a subprocess and this library
+        // stays I/O-light) — absent means the caller did not re-probe, and an
+        // unknown on either side is never a disagreement, exactly as for `head`.
+        {
+            field: 'context_fingerprint',
+            claimed: cp.context_fingerprint ?? null,
+            actual: currentFingerprint ?? null,
+            agrees:
+                (cp.context_fingerprint ?? null) === null ||
+                (currentFingerprint ?? null) === null ||
+                cp.context_fingerprint === currentFingerprint,
+        },
     ];
     return { readable: true, fields, agrees: fields.every((f) => f.agrees) };
 }

package/src/scripts/_lib/scoped_projection.ts

@@ -260,3 +260,99 @@ export function scoped_projection_stats(
         workspaces: [...SCOPED_ACTIVE_WORKSPACES].sort(),
     };
 }
+
+/** The installer's deploy tuple: [written, skipped, status, paths]. */
+export type DeployTuple = [number, number, string, string[]];
+
+// --- Deploy-tree prune mechanics ------------------------------------------
+// Moved here WHOLE from `install.ts` (a pure move, names forwarded there) so
+// the prune sits beside `is_pruned_under_scoped`, the predicate it consumes —
+// which is what this module's header says it exists for. It also pays for the
+// `check_source_size_budget` ratchet, which counts every line in a file above
+// 1,500 and which `install.ts` at 5,466 lines cannot grow past.
+
+/**
+ * Remove skills/commands matching `is_pruned` from a completed deploy.
+ *
+ * road-to-install-contract-stability Phase 2 Step 2 (generalized in
+ * road-to-credible-install Phase 2 to back both the core-only lab prune and
+ * the scoped-projection pack prune off the same mechanics). Skills are
+ * pruned by whole directory (tier decided by the skill's `SKILL.md`
+ * frontmatter); commands by file (own frontmatter). Rules / personas /
+ * contexts / templates are core/shared and left intact. Returns
+ * `[pruned_count, adjusted_results]` with the pruned paths removed from each
+ * tool's `written_paths` so the manifest never records them.
+ */
+export function prune_modules_by(
+    deploy_results: Record<string, DeployTuple>,
+    is_pruned: (md_path: string) => boolean,
+): [number, Record<string, DeployTuple>] {
+    let pruned = 0;
+    const adjusted: Record<string, DeployTuple> = {};
+    for (const tool_id of Object.keys(deploy_results)) {
+        const [written, skipped, status, paths] = deploy_results[tool_id] as DeployTuple;
+        const pruned_skill_dirs = new Set<string>();
+        for (const p of paths) {
+            const parts = p.split(path.sep);
+            if (parts.includes('skills')) {
+                const i = parts.indexOf('skills');
+                if (i + 1 < parts.length) {
+                    const skill_root = parts.slice(0, i + 2).join(path.sep);
+                    if (!pruned_skill_dirs.has(skill_root)) {
+                        const skillmd = path.join(skill_root, 'SKILL.md');
+                        if (fs.existsSync(skillmd) && is_pruned(skillmd)) {
+                            pruned_skill_dirs.add(skill_root);
+                        }
+                    }
+                }
+            }
+        }
+        const keep: string[] = [];
+        const delete_files: string[] = [];
+        for (const p of paths) {
+            const parts = p.split(path.sep);
+            let is_target = false;
+            if (parts.includes('skills')) {
+                const i = parts.indexOf('skills');
+                if (i + 1 < parts.length && pruned_skill_dirs.has(parts.slice(0, i + 2).join(path.sep))) {
+                    is_target = true;
+                }
+            } else if (
+                parts.includes('commands') &&
+                path.extname(p) === '.md' &&
+                is_pruned(p)
+            ) {
+                is_target = true;
+            }
+            (is_target ? delete_files : keep).push(p);
+        }
+        for (const d of pruned_skill_dirs) {
+            fs.rmSync(d, { recursive: true, force: true });
+        }
+        for (const p of delete_files) {
+            if (p.split(path.sep).includes('commands') && fs.existsSync(p)) {
+                try {
+                    fs.unlinkSync(p);
+                } catch {
+                    // OSError → swallow, mirroring the .py.
+                }
+            }
+        }
+        pruned += delete_files.length;
+        adjusted[tool_id] = [Math.max(0, written - delete_files.length), skipped, status, keep];
+    }
+    return [pruned, adjusted];
+}
+
+/**
+ * Remove lab-tier skills/commands from a completed deploy (core-only).
+ *
+ * road-to-install-contract-stability Phase 2 Step 2. Thin wrapper over
+ * `_prune_modules_by` — see that function for the mechanics.
+ */
+export function prune_lab_modules(
+    deploy_results: Record<string, DeployTuple>,
+    lab_ids: Set<string>,
+): [number, Record<string, DeployTuple>] {
+    return prune_modules_by(deploy_results, (p) => surface_tiers.is_lab_artefact(p, lab_ids));
+}

package/src/scripts/_lib/session_register.ts

@@ -226,6 +226,22 @@ export interface SessionRecord {
      * session that was never refused, is still a valid record.
      */
     turn_end_refusals?: Record<string, number>;
+    /**
+     * Repo-relative paths this session has declared it owns, or absent when it
+     * has declared none.
+     *
+     * `road-to-roadmap-situational-awareness` § 3.1. The register compared slugs
+     * and branch names and nothing else, so two sessions on two different
+     * roadmaps that happen to edit the same file were invisible to each other —
+     * the axis that actually predicts a merge conflict was the one axis nobody
+     * carried.
+     *
+     * Additive on exactly the terms `turn_end_refusals` established: a session
+     * that declared no paths leaves the record **byte-identical** to what it was
+     * before this field existed, so a reader that does not know the field is
+     * unaffected and a diff of two records still shows only what changed.
+     */
+    owned_paths?: string[];
 }
 
 /**
@@ -430,11 +446,21 @@ export function foreign_live_records(
  * so the branch comparison was silent by construction while a whole
  * implementation was duplicated. One of the two PRs is thrown away either way.
  */
-export type CollisionKind = 'roadmap' | 'branch';
+/**
+ * `path` is the third axis, added last and cheapest to be wrong about: two
+ * sessions can be on different roadmaps and different branches and still be
+ * editing one file. It is reported SEPARATELY rather than folded into either of
+ * the two above, because the response differs — a roadmap collision means stop,
+ * a branch collision means coordinate, a path collision means take the disjoint
+ * steps first and say so.
+ */
+export type CollisionKind = 'roadmap' | 'branch' | 'path';
 
 export interface Collision {
     kind: CollisionKind;
     record: SessionRecord;
+    /** For `kind: 'path'`, the shared paths. Absent on the other two kinds. */
+    paths?: string[];
 }
 
 /**
@@ -451,7 +477,11 @@ export interface Collision {
  */
 export function classify_collisions(
     others: readonly SessionRecord[],
-    here: { branch: string | null; roadmap_slug: string | null },
+    here: {
+        branch: string | null;
+        roadmap_slug: string | null;
+        owned_paths?: readonly string[];
+    },
 ): Collision[] {
     const out: Collision[] = [];
     for (const r of others) {
@@ -468,5 +498,17 @@ export function classify_collisions(
             out.push({ kind: 'branch', record: r });
         }
     }
+    // Last, and last on purpose: the two axes above are unchanged in meaning and
+    // in order, so a consumer that filters on `roadmap` or `branch` sees exactly
+    // what it saw before this axis existed.
+    const mine = new Set(here.owned_paths ?? []);
+    if (mine.size > 0) {
+        for (const r of others) {
+            const shared = (r.owned_paths ?? []).filter((p) => mine.has(p)).sort();
+            if (shared.length > 0) {
+                out.push({ kind: 'path', record: r, paths: shared });
+            }
+        }
+    }
     return out;
 }

package/src/scripts/_lib/skill_catalogue.ts

@@ -730,6 +730,17 @@ export interface ProjectionModeCounts {
     prunedUnderScoped: number;
     /** Pack ids active by default under `scoped`, sorted. */
     activePacks: string[];
+    /**
+     * Skills a `projection.mode: tiered` install deploys natively — those
+     * predicted to reach the model WITH their description. `null` when no tier
+     * split exists on this machine, which is the common case and is NOT zero.
+     */
+    tierACount: number | null;
+    /**
+     * Skills `tiered` withholds from the native catalogue; still served by the
+     * MCP recovery tools. `null` under the same condition as `tierACount`.
+     */
+    tierBCount: number | null;
 }
 
 /**
@@ -791,8 +802,26 @@ export function formatProjectionModes(
         `  legacy-all:  ${counts.legacyAll}`,
         `  pruned under scoped: ${counts.prunedUnderScoped}`,
         `  active packs under scoped: ${counts.activePacks.length}`,
-        '',
     ];
+    if (counts.tierACount === null || counts.tierBCount === null) {
+        lines.push(
+            '  tiered:      no split on this machine (agents/runtime/state/skill-tiers.json',
+            '               absent) — not zero, unmeasured. `tiered` ships the full surface',
+            '               until a split exists.',
+        );
+    } else {
+        lines.push(
+            `  tiered:      tier A ${counts.tierACount} native + tier B ${counts.tierBCount} ` +
+                `MCP-only = ${counts.tierACount + counts.tierBCount}`,
+        );
+        if (counts.tierACount + counts.tierBCount !== counts.legacyAll) {
+            lines.push(
+                `               ⚠️  tier A + tier B (${counts.tierACount + counts.tierBCount}) != ` +
+                    `legacy-all (${counts.legacyAll}) — the split is STALE, recompute it.`,
+            );
+        }
+    }
+    lines.push('');
     if (rows.length === 0) {
         lines.push(
             'No host root measured. Pass --host-root <dir> (repeatable) to read what',
@@ -959,6 +988,7 @@ export interface MigrationEligibility {
         | 'observation-not-comparable'
         | 'no-truncation-observed'
         | 'already-scoped'
+        | 'already-tiered'
         | 'below-observed-skill-volume';
     /** Populated only when eligible, for the message. */
     droppedEntries?: number;
@@ -981,11 +1011,17 @@ export interface MigrationEligibility {
  */
 export function migrationEligibility(
     host: string,
-    resolvedMode: 'scoped' | 'legacy-all',
+    resolvedMode: 'scoped' | 'legacy-all' | 'tiered',
     currentSkillCount: number,
     limits: ReadonlyMap<string, KnownHostLimit>,
 ): MigrationEligibility {
     if (resolvedMode === 'scoped') return { eligible: false, reason: 'already-scoped' };
+    // `tiered` already withholds skills from the native catalogue, so an offer to
+    // migrate to `scoped` has nothing to buy. It gets its OWN reason rather than
+    // reusing `already-scoped`: the two narrow on different axes (packs vs the
+    // host's listing budget), and a caller reading the reason should be able to
+    // tell which one the install is actually on.
+    if (resolvedMode === 'tiered') return { eligible: false, reason: 'already-tiered' };
     const limit = limits.get(host);
     if (limit === undefined) return { eligible: false, reason: 'no-observation-for-host' };
     if (limit.projectedSkills === null) return { eligible: false, reason: 'observation-not-comparable' };

package/src/scripts/_lib/transcript_reads.ts

@@ -0,0 +1,207 @@
+/**
+ * Re-read measurement over Claude Code transcript legs.
+ *
+ * `road-to-role-scoped-spawn-profiles` Phase 3 Step 3 requires a re-read
+ * measurement BEFORE any suppression: *"A suppression built without this
+ * measurement is suppressing whatever the author happened to notice."* This
+ * module is that measurement, and it is deliberately a sibling of
+ * `cc_transcript.ts` rather than a widening of it — `scanTranscripts` keeps
+ * only `type: "assistant"` records carrying a `usage` block, which is exactly
+ * the population a `tool_result` is NOT in.
+ *
+ * **What a "leg" is, stated because every count below depends on it.** One
+ * `.jsonl` file is one leg. Claude Code writes the main session to
+ * `<project>/<sessionId>.jsonl` and each subagent to
+ * `<project>/<sessionId>/subagents/agent-*.jsonl`, so a leg is a single
+ * conversation whose context window is its own. A file read once in the main
+ * leg and once inside a subagent is NOT a re-read — the second leg never had
+ * the first one's context — and {@link computeRereads} counts per leg for that
+ * reason.
+ *
+ * **The wasted-token figure is a `chars / 4` PROXY, not a measurement.** The
+ * transcript records no per-tool-result token count, so the size of a
+ * duplicate read is estimated from the JSON-encoded length of its
+ * `tool_result` body. Every caller must label it as a proxy; this module names
+ * the field `wasted_tokens_proxy` so the label cannot be dropped by accident.
+ *
+ * Read-only: no writes, no network, no spawn.
+ */
+
+import * as fs from 'node:fs';
+
+/**
+ * Tools whose result is a file body the model already holds after the first
+ * call. Deliberately narrow: `Edit` and `Write` also carry a `file_path`, but
+ * re-reading after a mutation is correct behaviour, not waste, so counting
+ * them would manufacture "re-reads" out of the loop this measurement exists to
+ * distinguish from.
+ */
+export const READ_SHAPED_TOOLS: ReadonlySet<string> = new Set(['Read', 'NotebookRead']);
+
+/** One observed read-shaped tool call inside one leg. */
+export interface ReadEvent {
+    filePath: string;
+    /** JSON-encoded length of the matching `tool_result` body; 0 when no result was recorded. */
+    resultChars: number;
+}
+
+/** Per-path rollup across every leg that read it more than once. */
+export interface RereadFile {
+    file_path: string;
+    /** Total read-shaped calls on this path, across all legs. */
+    total_reads: number;
+    /** Reads beyond the first WITHIN a leg, summed over legs. */
+    duplicate_reads: number;
+    /** Number of legs in which this path was read at least twice. */
+    legs_with_reread: number;
+    /** `chars / 4` proxy over the duplicate reads only — never a measurement. */
+    wasted_tokens_proxy: number;
+}
+
+export interface RereadResult {
+    legs_scanned: number;
+    total_reads: number;
+    duplicate_reads: number;
+    wasted_tokens_proxy: number;
+    /** Only paths with at least one duplicate, ranked by `wasted_tokens_proxy` desc. */
+    files: RereadFile[];
+}
+
+function parseLine(line: string): Record<string, unknown> | null {
+    const t = line.trim();
+    if (t.length === 0) return null;
+    try {
+        const v = JSON.parse(t) as unknown;
+        return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : null;
+    } catch {
+        return null;
+    }
+}
+
+function contentBlocks(rec: Record<string, unknown>): Array<Record<string, unknown>> {
+    const msg = rec.message;
+    if (!msg || typeof msg !== 'object' || Array.isArray(msg)) return [];
+    const content = (msg as Record<string, unknown>).content;
+    if (!Array.isArray(content)) return [];
+    return content.filter((c): c is Record<string, unknown> => !!c && typeof c === 'object' && !Array.isArray(c));
+}
+
+function readPathOf(input: unknown): string | null {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+    const o = input as Record<string, unknown>;
+    for (const key of ['file_path', 'filePath', 'notebook_path', 'notebookPath']) {
+        const v = o[key];
+        if (typeof v === 'string' && v.length > 0) return v;
+    }
+    return null;
+}
+
+/**
+ * Every read-shaped call in one leg, in call order, each paired with the size
+ * of its result.
+ *
+ * Two passes on purpose: a `tool_result` can only be matched by
+ * `tool_use_id`, and nothing guarantees it appears after its `tool_use` in
+ * file order once a transcript has been resumed or replayed. An unreadable or
+ * malformed file yields `[]` — this is instrumentation, and a measurement that
+ * throws on one bad leg reports nothing about the other two thousand.
+ */
+export function collectReadEvents(file: string): ReadEvent[] {
+    let text: string;
+    try {
+        text = fs.readFileSync(file, 'utf-8');
+    } catch {
+        return [];
+    }
+
+    const order: Array<{ id: string | null; filePath: string }> = [];
+    const sizes = new Map<string, number>();
+
+    for (const line of text.split('\n')) {
+        const rec = parseLine(line);
+        if (!rec) continue;
+        for (const block of contentBlocks(rec)) {
+            if (block.type === 'tool_use') {
+                if (typeof block.name !== 'string' || !READ_SHAPED_TOOLS.has(block.name)) continue;
+                const filePath = readPathOf(block.input);
+                if (filePath === null) continue;
+                order.push({ id: typeof block.id === 'string' ? block.id : null, filePath });
+            } else if (block.type === 'tool_result') {
+                const id = block.tool_use_id ?? block.toolUseId;
+                if (typeof id !== 'string') continue;
+                let chars = 0;
+                try {
+                    chars = JSON.stringify(block.content ?? '').length;
+                } catch {
+                    chars = 0;
+                }
+                sizes.set(id, chars);
+            }
+        }
+    }
+
+    return order.map((o) => ({
+        filePath: o.filePath,
+        resultChars: o.id === null ? 0 : (sizes.get(o.id) ?? 0),
+    }));
+}
+
+const CHARS_PER_TOKEN_PROXY = 4;
+
+/**
+ * Roll every leg up into a per-path re-read ranking.
+ *
+ * The duplicate count is per leg: the first read of a path in a leg is the
+ * cost of knowing it, every later read in the SAME leg is the waste. Legs are
+ * never joined, so a path read once in each of two legs contributes zero
+ * duplicates — see the module doc.
+ */
+export function computeRereads(files: readonly string[]): RereadResult {
+    const acc = new Map<string, RereadFile>();
+    let legsScanned = 0;
+    let totalReads = 0;
+
+    for (const file of files) {
+        const events = collectReadEvents(file);
+        legsScanned += 1;
+        if (events.length === 0) continue;
+
+        const seenInLeg = new Map<string, number>();
+        for (const ev of events) {
+            totalReads += 1;
+            const priorInLeg = seenInLeg.get(ev.filePath) ?? 0;
+            seenInLeg.set(ev.filePath, priorInLeg + 1);
+
+            const row = acc.get(ev.filePath) ?? {
+                file_path: ev.filePath,
+                total_reads: 0,
+                duplicate_reads: 0,
+                legs_with_reread: 0,
+                wasted_tokens_proxy: 0,
+            };
+            row.total_reads += 1;
+            if (priorInLeg >= 1) {
+                row.duplicate_reads += 1;
+                row.wasted_tokens_proxy += Math.round(ev.resultChars / CHARS_PER_TOKEN_PROXY);
+                if (priorInLeg === 1) row.legs_with_reread += 1;
+            }
+            acc.set(ev.filePath, row);
+        }
+    }
+
+    const withDuplicates = [...acc.values()].filter((r) => r.duplicate_reads > 0);
+    withDuplicates.sort(
+        (a, b) =>
+            b.wasted_tokens_proxy - a.wasted_tokens_proxy ||
+            b.duplicate_reads - a.duplicate_reads ||
+            a.file_path.localeCompare(b.file_path),
+    );
+
+    return {
+        legs_scanned: legsScanned,
+        total_reads: totalReads,
+        duplicate_reads: withDuplicates.reduce((s, r) => s + r.duplicate_reads, 0),
+        wasted_tokens_proxy: withDuplicates.reduce((s, r) => s + r.wasted_tokens_proxy, 0),
+        files: withDuplicates,
+    };
+}