@event4u/agent-config 14.5.0 → 14.7.0

package/src/scripts/session_register_hook.ts

@@ -354,8 +354,17 @@ export function claim_is_stale(
     // roadmaps directory" — and it is the same check for a traversal, an absolute
     // path, and an encoding nobody enumerated. A slug that fails it is reported
     // stale rather than resolved, so no read happens at all.
+    // Structural, not textual. Round 6 finding 3: the previous form ANDed a
+    // `!rel.includes('..')` substring test onto the prefix check, and round 5
+    // finding 10 removed exactly that test from `resolveRoadmap` — one-sided. The
+    // two functions then disagreed about one claim string in the opposite
+    // direction: for a legal slug like `road-to-a..b` the register rendered a live
+    // claim as stale (dropping it from the collision set and disabling the
+    // duplicate-work warning) while the hook resolved it and engaged. `path.dirname`
+    // asks the only question that matters — is the result a file directly inside the
+    // roadmaps directory — and is the same check both sides now make.
     const rel = path.normalize(path.join('agents', 'roadmaps', `${base}.md`));
-    const inside = rel.startsWith(`agents${path.sep}roadmaps${path.sep}`) && !rel.includes('..');
+    const inside = path.dirname(rel) === path.join('agents', 'roadmaps');
     if (!inside || path.isAbsolute(base)) {
         return true; // not a slug this repo can hold; never render it as live work
     }
@@ -409,29 +418,98 @@ export function claim_is_stale(
  * conditions, because a wrong anchor is worse than the fallback:
  *
  * 1. it is an existing directory;
- * 2. it is the ROOT of a checkout (`git_dir` looks for `<dir>/.git` and does not
- *    walk up, so a session whose cwd is a subdirectory degrades to
- *    `workspace_root` — today's behaviour, never something worse);
- * 3. it belongs to the SAME repository — identical git common dir. A cwd in
- *    another repo would otherwise write this repo's register with a foreign
+ * 2. it resolves to the NEAREST enclosing checkout root, walking up from the
+ *    reported directory;
+ * 3. that root belongs to the SAME repository — identical git common dir. A cwd
+ *    in another repo would otherwise write this repo's register with a foreign
  *    branch, and the register is shared by every worktree here.
+ *
+ * ## Condition 2 used to reject a subdirectory, and that was wrong here
+ *
+ * It required the reported directory to BE a checkout root, and defended the
+ * rejection as "a session whose cwd is a subdirectory degrades to
+ * `workspace_root` — today's behaviour, never something worse". R2 round 3
+ * finding 2 measured that claim false in this repository's own layout, where
+ * worktrees live at `<parent>/.claude/worktrees/<name>` — NESTED under the
+ * parent. For a session standing at `<parent>/.claude/worktrees/wt/src`:
+ *
+ *   - the degraded root is `<parent>`, i.e. equal to `workspace_root`;
+ *   - so `git_dir` and `git_common_dir` taken from it are both `<parent>/.git`;
+ *   - and the reported cwd is under `<parent>` as well.
+ *
+ * Every available signal then reports a healthy same-tree run for a genuine
+ * two-tree one. That is not a loss of precision, it is a confident wrong answer,
+ * which is strictly worse than the fallback the docblock was defending.
+ *
+ * The walk is bounded twice over, per the AI council's condition (2026-08-19,
+ * 2/2 convergent on this shape): it stops at the FIRST enclosing checkout root,
+ * so a nested worktree is found before the parent that contains it, and the
+ * same-repository check is retained on whatever it finds — a cwd inside an
+ * unrelated repo nested in this tree resolves to that repo's root, fails the
+ * identity check, and falls back. Paths are canonicalised before the walk so a
+ * symlinked cwd cannot walk a different chain than the one it names.
  */
 export function session_checkout(
     workspace_root: string,
     payload_cwd: string | null | undefined,
 ): string {
+    // EVERY branch returns a canonical path, resolve and fallback alike.
+    //
+    // Round 4 finding 5: the resolve branch realpath-normalised and the four
+    // fallback branches returned `workspace_root` verbatim, so under a repo
+    // reached through a symlinked ancestor two sessions in the SAME working tree
+    // stored different strings for it — `/private/var/…/repo` from the resolver
+    // and `/var/…/repo` from the envelope. `foreign_sessions_block` compares the
+    // stored forms with `path.resolve`, which does not follow symlinks, so it read
+    // them as different worktrees and printed the benign "separate trees" note
+    // where the same-worktree COLLISION prompt belongs. The walk-up widened the
+    // exposure by moving subdirectory sessions onto the normalising branch.
+    const fallback = canonical(workspace_root);
     const cwd = String(payload_cwd ?? '').trim();
-    if (cwd === '') return workspace_root;
+    if (cwd === '') return fallback;
+    let start: string;
     try {
-        if (!fs.statSync(cwd).isDirectory()) return workspace_root;
+        if (!fs.statSync(cwd).isDirectory()) return fallback;
+        start = fs.realpathSync(cwd);
     } catch {
-        return workspace_root;
+        return fallback;
     }
-    if (git_dir(cwd) === null) return workspace_root;
-    const mine = git_common_dir(cwd);
+    const root = nearest_checkout_root(start);
+    if (root === null) return fallback;
+    const mine = git_common_dir(root);
     const theirs = git_common_dir(workspace_root);
-    if (mine === null || theirs === null || mine !== theirs) return workspace_root;
-    return cwd;
+    if (mine === null || theirs === null || mine !== theirs) return fallback;
+    return root;
+}
+
+/** `realpath` that falls back to an absolute form when the path is unreadable. */
+function canonical(p: string): string {
+    const abs = path.resolve(p);
+    try {
+        return fs.realpathSync(abs);
+    } catch {
+        return abs;
+    }
+}
+
+/**
+ * The nearest enclosing directory that is a checkout root, or `null`.
+ *
+ * The iteration cap is a loop guard, not a policy: `path.dirname` is a fixed
+ * point at the filesystem root, so the terminating condition is the unchanged
+ * path and the counter only bounds a pathological filesystem. The FIRST hit
+ * wins, which is what makes a nested worktree resolve to itself rather than to
+ * the checkout it sits inside.
+ */
+function nearest_checkout_root(start: string): string | null {
+    let dir = start;
+    for (let i = 0; i < 64; i++) {
+        if (git_dir(dir) !== null) return dir;
+        const up = path.dirname(dir);
+        if (up === dir) return null;
+        dir = up;
+    }
+    return null;
 }
 
 /**
@@ -619,13 +697,35 @@ export function foreign_sessions_block(
     // `session_checkout`. Before that every record claimed the main checkout, so
     // every collision looked like the dangerous one.
     if (branch_hit !== null) {
-        const peer_tree = path.resolve(branch_hit.record.worktree ?? '');
-        const same_tree = peer_tree !== '' && peer_tree === path.resolve(workspace_root);
+        // Compared through `canonical`, not `path.resolve`, because resolve does not
+        // follow symlinks — round 5 finding 11. Round 4 finding 5 made every
+        // `session_checkout` branch canonical, which fixes records written from now
+        // on; it does nothing for a record already in the register from before the
+        // upgrade, and those live for the whole TTL window. Under a symlinked
+        // ancestor such a peer holds `/var/…/repo` while this session holds
+        // `/private/var/…/repo`, and comparing the raw strings reads two sessions
+        // in ONE working tree as separate trees — printing the benign note where
+        // the collision prompt belongs. Canonicalising at the comparison closes the
+        // upgrade boundary the writer side cannot reach.
+        const peer_tree = canonical(branch_hit.record.worktree ?? '');
+        const same_tree =
+            (branch_hit.record.worktree ?? '') !== '' && peer_tree === canonical(workspace_root);
         if (same_tree) {
             parts.push(
                 '',
                 `COLLISION: another live session is on branch \`${here}\` in THIS SAME worktree`,
                 `(${branch_hit.record.worktree}) — the same files and the same git index.`,
+                'What "join anyway" actually costs, because option 1 is chosen routinely and',
+                'the price was not in this text until 2026-08-20 (road-to-session-closeout 6.3):',
+                '  · SHARED INDEX — `git add -A` stages the peer\'s work too. Measured: a peer',
+                '    session\'s untracked roadmap was swept into an unrelated merge commit and',
+                '    surfaced three commits later at an estate gate. Use pathspecs, never -A.',
+                '  · SHARED STASH STACK — `git stash` is repo-wide, so your stash is visible and',
+                '    poppable by the peer, and `stash@{0}` means a different thing to each of you.',
+                '  · PRE-PUSH runs over the shared tree — it sees the peer\'s files, not only',
+                '    yours. `task consistency` is now scoped to the paths it regenerates, so a',
+                '    peer\'s unrelated edit no longer fails it; anything else in that hook still',
+                '    reads one tree written by two sessions.',
                 'Ask the user ONCE PER SESSION, as numbered options, before writing anything:',
                 '  1. Join anyway and coordinate manually (this register is advisory, not a lock)',
                 '  2. Spawn a separate worktree for this session',

package/src/scripts/skill_usage_collect.ts

@@ -31,7 +31,17 @@ const _HERE = fileURLToPath(import.meta.url);
 
 // src/scripts/skill_usage_collect.ts → parents[2] of the .py file is repo root.
 export const REPO = path.resolve(path.dirname(_HERE), '..', '..');
-const OUT = path.join(REPO, 'agents', 'metrics', 'skill-usage.jsonl');
+// `agents/metrics/` was retired by the agents/ taxonomy consolidation (the
+// same finding `skill_overlap.ts` records), so this collector was appending to
+// a directory that does not exist while the real record set sat untouched at
+// `agents/runtime/metrics/skill-usage.jsonl` — last written 2026-05-16. The
+// report script read the same dead path, so the pair agreed with each other
+// and with nothing else. road-to-org-telemetry Phase 0 measured the
+// consequence (spike 3: 0 of 89 invocations detected on the set the collector
+// reads) and named the repair a Phase 4 prerequisite. `runtime/` is the typed,
+// gitignored home for a record set nothing tracks, per the agents/ layout
+// contract.
+const OUT = path.join(REPO, 'agents', 'runtime', 'metrics', 'skill-usage.jsonl');
 
 // LISTING_LINE_RE = re.compile(r"^-\s+([a-z0-9][a-z0-9_-]+):\s", re.MULTILINE)
 const LISTING_LINE_RE = /^-\s+([a-z0-9][a-z0-9_-]+):\s/gm;

package/src/scripts/skill_usage_report.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 /**
- * Aggregate `agents/runtime/metrics/skill-usage.jsonl` into a per-skill report.
+ * Aggregate `agents/runtime/metrics/skill-usage.jsonl` into a per-skill report,
+ * plus a second section over the Class-A sink export when one is present.
  *
  * Ported from the retired Python `src/scripts/skill_usage_report.py` (ADR-200,
  * Phase 8 / Wave 8b). The public surface, CLI contract, exit code,
@@ -19,13 +20,47 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+// The "existing threshold constant" the step names — the distinct-user bar the
+// tier-usage re-tier already ships. Imported rather than restated so the sink
+// section and the re-tier decision cannot drift to two different numbers.
+import { DEFAULT_TIER_USAGE_RETIER } from '../agent-src/templates/scripts/telemetry/settings.js';
 
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
 // parent.parent.parent of the .py file (src/scripts/skill_usage_report.py)
 // is the repo root — two dirs up from src/scripts.
 const REPO = path.resolve(_HERE, '..', '..');
-const IN = path.join(REPO, 'agents', 'metrics', 'skill-usage.jsonl');
-const OUT = path.join(REPO, 'agents', 'metrics', 'skill-usage-report.md');
+// Both of these pointed into `agents/metrics/`, a directory the agents/
+// taxonomy consolidation retired — so the report read a file that does not
+// exist and wrote beside it, while the real record set sat at
+// `agents/runtime/metrics/` and the tracked report at
+// `agents/evidence/metrics/`. road-to-org-telemetry Phase 0 named this repair
+// a Phase 4 prerequisite: adding the sink as a SECOND source lands beside a
+// first source that reads nothing. Destinations follow the agents/ layout
+// contract, and both match what `taskfiles/ci-fast.yml`'s own task
+// descriptions already claimed this script does.
+//
+// OUT IS THE RUNTIME COPY, NOT THE TRACKED ONE, AND THAT IS DELIBERATE. The
+// tracked `agents/evidence/metrics/skill-usage-report.md` is a promoted
+// baseline snapshot the roadmap cites by its numbers. Pointing OUT at it makes
+// every run in a checkout WITHOUT the gitignored record set overwrite that
+// baseline with zeros — measured while writing this change: 297 insertions /
+// 339 deletions, every row reclassified `dead`, from a worktree where the
+// JSONL simply does not exist. A measurement that corrupts its own baseline is
+// worse than no measurement. Promotion to `evidence/` stays a deliberate copy.
+const IN = path.join(REPO, 'agents', 'runtime', 'metrics', 'skill-usage.jsonl');
+const OUT = path.join(REPO, 'agents', 'runtime', 'metrics', 'skill-usage-report.md');
+
+/**
+ * The sink export — the SECOND source (Phase 4, step 4.1).
+ *
+ * Class-A records as JSONL, either an export of the org sink or one install's
+ * own local `.agent-telemetry.jsonl`. Default-absent is the normal state and
+ * is reported as such: `sink-choice` is transferred, so no sink exists for
+ * this repository to read, and a section that silently rendered nothing would
+ * be indistinguishable from a sink that answered zero — which is the exact
+ * blind-zero confusion this roadmap exists to remove.
+ */
+const SINK_IN = path.join(REPO, 'agents', 'runtime', 'metrics', 'telemetry-class-a.jsonl');
 
 interface Bucket {
     exposures_total: number;
@@ -197,7 +232,214 @@ function _dateIso(d: Date): string {
     return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}`;
 }
 
-export function render(per: Map<string, Bucket>, known: Set<string>): string {
+// ── The sink as a second source (Phase 4, step 4.1) ────────────────────────
+//
+// WHY THIS IS A SEPARATE SECTION AND NOT EXTRA COLUMNS. The two sources do not
+// measure the same thing and cannot share a row. The first source is a regex
+// scan of the maintainer's own transcripts, so it counts *exposure* and
+// *mention* on one machine; Phase 0's third spike measured it detecting **0 of
+// 89** real invocations on the set it reads. The sink counts *invocations* with
+// a pseudonymous user per record, across every consenting install. Merging them
+// into one table would produce a row whose numbers come from different
+// populations, which is exactly the kind of arithmetic the zero-activation
+// reading already taught this repository not to trust.
+//
+// DISTINCT USERS ARE THE POINT. A per-skill invocation count from one heavy
+// user is not adoption. `user_hash` is a salted digest of host + login, so it
+// distinguishes people without naming them, and the threshold below is the bar
+// the tier-usage re-tier already uses.
+
+/** One Class-A usage record, as the emitter writes it. */
+interface ClassALine {
+    skill: string;
+    user_hash: string;
+    session_hash: string | null;
+    host: string | null;
+    ts_bucket: string;
+    record_class: string;
+}
+
+export interface SinkBucket {
+    invocations_total: number;
+    invocations_window: number;
+    users_window: Set<string>;
+    sessions_window: Set<string>;
+    hosts: Set<string>;
+    last_seen: Date | null;
+}
+
+/**
+ * Parse an hour bucket (`2026-08-20T10:00Z`).
+ *
+ * Its own parser rather than `parse_ts`: the first source carries a full ISO
+ * timestamp and the sink deliberately carries hour resolution only, so one
+ * parser over both would quietly accept a precision neither guarantees.
+ */
+export function parse_hour_bucket(raw: unknown): Date | null {
+    if (typeof raw !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:00Z$/u.test(raw)) {
+        return null;
+    }
+    const d = new Date(raw);
+    return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/** Load Class-A records. A missing sink export is a normal state, not an error. */
+export function load_class_a(p: string): ClassALine[] {
+    let text = '';
+    try {
+        text = fs.readFileSync(p, 'utf-8');
+    } catch {
+        return [];
+    }
+    const out: ClassALine[] = [];
+    for (const line of text.split('\n')) {
+        if (!line.trim()) continue;
+        try {
+            const rec = JSON.parse(line) as Record<string, unknown>;
+            const skill = rec['skill'];
+            const user_hash = rec['user_hash'];
+            const ts_bucket = rec['ts_bucket'];
+            // A record missing any of the three fields the aggregate is built
+            // from is dropped rather than counted with a substitute: a
+            // fabricated user or a fabricated hour both inflate the very
+            // numbers an estate decision would cite.
+            if (typeof skill !== 'string' || typeof user_hash !== 'string') continue;
+            if (typeof ts_bucket !== 'string') continue;
+            out.push({
+                skill,
+                user_hash,
+                session_hash: typeof rec['session_hash'] === 'string' ? rec['session_hash'] : null,
+                host: typeof rec['host'] === 'string' ? rec['host'] : null,
+                ts_bucket,
+                record_class: typeof rec['record_class'] === 'string' ? rec['record_class'] : '',
+            });
+        } catch {
+            // Same tolerance as the first source: a truncated tail line does
+            // not discard the file.
+        }
+    }
+    return out;
+}
+
+export function aggregate_sink(
+    records: readonly ClassALine[],
+    now: Date,
+    window_days: number,
+): Map<string, SinkBucket> {
+    const cutoff = now.getTime() - window_days * 86400_000;
+    const per = new Map<string, SinkBucket>();
+    for (const r of records) {
+        // Only usage records feed a usage report. Phase 5 adds a self-repair
+        // class to the same schema, and counting those as invocations would
+        // read defect reports as adoption.
+        if (r.record_class !== 'usage') continue;
+        const ts = parse_hour_bucket(r.ts_bucket);
+        if (ts === null) continue;
+        let b = per.get(r.skill);
+        if (b === undefined) {
+            b = {
+                invocations_total: 0,
+                invocations_window: 0,
+                users_window: new Set<string>(),
+                sessions_window: new Set<string>(),
+                hosts: new Set<string>(),
+                last_seen: null,
+            };
+            per.set(r.skill, b);
+        }
+        b.invocations_total += 1;
+        if (r.host !== null) b.hosts.add(r.host);
+        if (b.last_seen === null || ts.getTime() > b.last_seen.getTime()) b.last_seen = ts;
+        if (ts.getTime() >= cutoff) {
+            b.invocations_window += 1;
+            b.users_window.add(r.user_hash);
+            if (r.session_hash !== null) b.sessions_window.add(r.session_hash);
+        }
+    }
+    return per;
+}
+
+/** The distinct-user bar, from the constant the re-tier already ships. */
+export const MIN_DISTINCT_USERS = DEFAULT_TIER_USAGE_RETIER.min_distinct_users;
+
+/**
+ * Render the sink section.
+ *
+ * An ABSENT or EMPTY sink renders a paragraph saying so, naming the path and
+ * the reason. That is the load-bearing case today: `sink-choice` is
+ * transferred, so no sink exists for this repository to read. A section that
+ * rendered nothing would leave a reader unable to tell "no sink" from "a sink
+ * that answered zero" — the blind-zero confusion this whole roadmap exists to
+ * remove, reproduced one layer up.
+ */
+export function render_sink_section(
+    per: Map<string, SinkBucket>,
+    window_days: number,
+    source_rel: string,
+    present: boolean,
+): string[] {
+    const lines: string[] = ['', '## Second source — org sink (Class-A)', ''];
+    if (!present || per.size === 0) {
+        lines.push(
+            `> **No sink data.** \`${source_rel}\` ` +
+                (present ? 'holds no usage records' : 'does not exist') +
+                '. This is the expected state while the sink itself is transferred ' +
+                '(`sink-choice`, see `agents/roadmaps/stubs/road-to-org-telemetry-sink.md`): ' +
+                'nothing has been stood up for this report to read. Read it as ' +
+                '**no instrument**, never as no adoption — the distinction is the ' +
+                'reason this roadmap exists.',
+        );
+        lines.push('');
+        return lines;
+    }
+
+    const rows = [...per.entries()].sort((a, b) => {
+        const du = b[1].users_window.size - a[1].users_window.size;
+        if (du !== 0) return du;
+        const iv = b[1].invocations_window - a[1].invocations_window;
+        if (iv !== 0) return iv;
+        return pyStrCmp(a[0], b[0]);
+    });
+    const meeting = rows.filter(([, b]) => b.users_window.size >= MIN_DISTINCT_USERS).length;
+    lines.push(
+        `**Window:** ${window_days}-day rolling · **Source:** \`${source_rel}\` · ` +
+            `**Skills with any invocation:** ${rows.length} · ` +
+            `**At or above the ${MIN_DISTINCT_USERS}-distinct-user bar:** ${meeting}`,
+    );
+    lines.push('');
+    lines.push(
+        `| # | slug | invocations_${window_days}d | distinct_users_${window_days}d | ` +
+            `distinct_sessions_${window_days}d | hosts | meets_bar | last_seen |`,
+    );
+    lines.push('|---|---|---|---|---|---|---|---|');
+    let i = 0;
+    for (const [slug, b] of rows) {
+        i += 1;
+        const hosts = [...b.hosts].sort(pyStrCmp).join(', ') || '—';
+        const meets = b.users_window.size >= MIN_DISTINCT_USERS ? 'yes' : 'no';
+        const last = b.last_seen ? _dateIso(b.last_seen) : '—';
+        lines.push(
+            `| ${i} | \`${slug}\` | ${b.invocations_window} | ${b.users_window.size} | ` +
+                `${b.sessions_window.size} | ${hosts} | ${meets} | ${last} |`,
+        );
+    }
+    lines.push('');
+    lines.push(
+        `**Read-out:** \`meets_bar\` is the ${MIN_DISTINCT_USERS}-distinct-user threshold ` +
+            'the tier-usage re-tier already uses; below it, a count is one person\'s habit ' +
+            'rather than adoption. A host with no `Skill` tool emits no records at all, so ' +
+            'a missing host in this table is a missing instrument and not a missing user.',
+    );
+    lines.push('');
+    return lines;
+}
+
+export function render(
+    per: Map<string, Bucket>,
+    known: Set<string>,
+    sink: { per: Map<string, SinkBucket>; source_rel: string; present: boolean } | null = null,
+    window_days = 30,
+): string {
     // sorted(known | set(per))
     const allSlugs = pySortedUnique([...known, ...per.keys()]);
     const rows: ReportRow[] = [];
@@ -227,7 +469,7 @@ export function render(per: Map<string, Bucket>, known: Set<string>): string {
     const lines: string[] = [
         '# Skill Usage Report (baseline)',
         '',
-        '> Generated by `scripts/skill_usage_report.py`. Source:',
+        '> Generated by `src/scripts/skill_usage_report.ts`. Source:',
         '> `agents/runtime/metrics/skill-usage.jsonl` (collector emits per-turn',
         '> exposure/mention records). See',
         '> [`step-2-skill-inventory-rationalization.md`](../roadmaps/step-2-skill-inventory-rationalization.md)',
@@ -257,6 +499,9 @@ export function render(per: Map<string, Bucket>, known: Set<string>): string {
             'structural overlap before any deletion.',
     );
     lines.push('');
+    if (sink !== null) {
+        lines.push(...render_sink_section(sink.per, window_days, sink.source_rel, sink.present));
+    }
     return lines.join('\n');
 }
 
@@ -286,12 +531,14 @@ function _relativeToRepo(p: string): string {
 interface ParsedArgs {
     inp: string;
     out: string;
+    /** The Class-A sink export — the second source. */
+    sink: string;
     window: number;
     quiet: boolean;
 }
 
 export function parse_args(argv: string[]): ParsedArgs {
-    const out: ParsedArgs = { inp: IN, out: OUT, window: 30, quiet: false };
+    const out: ParsedArgs = { inp: IN, out: OUT, sink: SINK_IN, window: 30, quiet: false };
     const fail = (msg: string): never => {
         process.stderr.write(`skill_usage_report: error: ${msg}\n`);
         process.exit(2);
@@ -310,6 +557,12 @@ export function parse_args(argv: string[]): ParsedArgs {
             out.out = path.resolve(v as string);
         } else if (a.startsWith('--out=')) {
             out.out = path.resolve(a.slice('--out='.length));
+        } else if (a === '--sink') {
+            const v = argv[++i];
+            if (v === undefined) fail('argument --sink: expected one argument');
+            out.sink = path.resolve(v as string);
+        } else if (a.startsWith('--sink=')) {
+            out.sink = path.resolve(a.slice('--sink='.length));
         } else if (a === '--window') {
             const v = argv[++i];
             if (v === undefined) fail('argument --window: expected one argument');
@@ -319,7 +572,7 @@ export function parse_args(argv: string[]): ParsedArgs {
         } else if (a === '--quiet') {
             out.quiet = true;
         } else if (a === '-h' || a === '--help') {
-            process.stdout.write('usage: skill_usage_report [-h] [--in INP] [--out OUT] [--window WINDOW] [--quiet]\n');
+            process.stdout.write('usage: skill_usage_report [-h] [--in INP] [--out OUT] [--sink SINK] [--window WINDOW] [--quiet]\n');
             process.exit(0);
         } else {
             fail(`unrecognized arguments: ${a}`);
@@ -353,8 +606,25 @@ export function main(argv?: string[]): number {
         }
         throw exc;
     }
+    // The second source. Absent is the normal state and is rendered as such
+    // rather than omitted — see `render_sink_section`.
+    const sink_present = fs.existsSync(args.sink);
+    const sink_per = aggregate_sink(load_class_a(args.sink), now, args.window);
+    let sink_rel: string;
+    try {
+        sink_rel = _relativeToRepo(args.sink);
+    } catch {
+        // A sink export outside the repo is legitimate (an org may mount one);
+        // the report then names it by basename rather than refusing to render.
+        sink_rel = path.basename(args.sink);
+    }
+
     fs.mkdirSync(path.dirname(args.out), { recursive: true });
-    fs.writeFileSync(args.out, render(per, known), 'utf-8');
+    fs.writeFileSync(
+        args.out,
+        render(per, known, { per: sink_per, source_rel: sink_rel, present: sink_present }, args.window),
+        'utf-8',
+    );
     if (!args.quiet) {
         const count = new Set([...known, ...per.keys()]).size;
         process.stdout.write(`✅  Wrote ${_relativeToRepo(args.out)} (${count} skill(s))\n`);

package/src/scripts/sync_pr_branch.ts

@@ -40,6 +40,13 @@ const GENERATED = [
     'docs/catalog.md',
     'dist/agent-src/',
     '.augment/',
+    // Compiled from `hook_manifest.yaml` by `task build-ts`, never hand-written.
+    // It was classified AUTHORED until 2026-08-20, so this tool told the reader
+    // to "read both sides" on a file where mixing hunks yields a concern table
+    // matching NEITHER branch. One session resolved this same conflict three
+    // times and named it structural: main adds a concern and recompiles, so
+    // every open branch collides here. Regenerate; never merge.
+    'src/scripts/hook_manifest.json',
 ];
 
 function sh(cmd: string, args: readonly string[], cwd: string): { ok: boolean; out: string; err: string } {

package/src/server/schemas/settings.ts

@@ -200,6 +200,14 @@ export const settingsSchema = z.object({
         horizon_weeks: z.number().int().min(0).default(0).describe(
             'Optional planning horizon (weeks) the agent shows in roadmap framing ("next 4 weeks"). Set 0 to omit the horizon — most teams prefer to ship without a hardcoded window.',
         ),
+        gate_budget: z.object({
+            max_cost_per_run_usd: z.number().min(0).default(5).describe(
+                'Per-run USD ceiling for a CLASS-1 roadmap blocker executed via `agent-config gates --execute`. A class-1 entry whose **Budget:** field states a larger figure renders its consent line instead of running. Bounds the size of an authorised spend; never supplies the authorisation — `--confirm` is still required on every class-1 run.',
+            ),
+            max_cost_per_rolling_7d_usd: z.number().min(0).default(25).describe(
+                'Rolling 7-day USD ceiling for class-1 gate execution, summed from the append-only receipt ledger at agents/runtime/state/gate-budget-ledger.jsonl. A run whose estimate would cross it renders instead of running. A per-run cap alone bounds one mistake, not a week of them, which is why option (a) of b-gate-budget-preauth carries two numbers.',
+            ),
+        }).default({ max_cost_per_run_usd: 5, max_cost_per_rolling_7d_usd: 25 }),
     }),
     planning: z.object({
         challenge_on_create: z.boolean().default(true).describe(