@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/network_sources.ts

@@ -0,0 +1,236 @@
+/**
+ * network_sources.ts — the network half of the foreign-source door (step 4.2b,
+ * ADR-288 D7): a URL or article read once, a repository cloned at depth 1, and
+ * the codebook that keeps every source's identity out of tracked output.
+ *
+ * D7 bounds what this may do: an invocation that names a source authorises
+ * read-only fetches of THAT source for that run, and private or authenticated
+ * network content stays excluded. So a URL carrying credentials is refused, a
+ * host resolving to a private, loopback or link-local address is refused at
+ * every redirect hop, redirects and body size are capped, no auth header is
+ * ever sent, and a clone runs with hooks disabled, follows no redirect and is
+ * never executed.
+ * DNS is checked before the request, not pinned for it; a rebinding resolver
+ * between the two is the residual this module does not close.
+ *
+ * Fetched text is data. It is digested and quoted (≤ 15 words per anchor),
+ * never followed as an instruction.
+ */
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { lookup } from 'node:dns/promises';
+import * as fs from 'node:fs';
+import { isIP } from 'node:net';
+import * as path from 'node:path';
+
+import { encrypt } from './_lib/link_crypto.js';
+import { sanitize_text } from './_lib/retrieval_sanitize.js';
+import { SourceError, resolveSource, type SourceRef } from './source_adapters.js';
+
+export const DEGRADED_NO_NETWORK = 'degraded: no-network';
+export const DEFAULT_MAX_BYTES = 2 * 1024 * 1024;
+export const DEFAULT_MAX_REDIRECTS = 3;
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const MAX_QUOTE_WORDS = 15;
+
+export const RESEARCH_BRIEF = [
+    'Read the code, not the README.',
+    'Follow the source to the other repositories, links and posts it builds on.',
+    'Search the web for the same problem solved elsewhere.',
+    'Record every source as a coded id (S1, S2, …) with a digest and a quoted anchor; never its name.',
+].join(' ');
+
+export interface NetworkOptions {
+    network: boolean;
+    allowPrivateHosts?: boolean;
+    /** Hosts treated as public although they resolve privately — fixture servers only. */
+    hostAllowlistForTests?: readonly string[];
+    maxBytes?: number;
+    maxRedirects?: number;
+    /** Wall-clock cap on one request (body read included) and on one git call. */
+    timeoutMs?: number;
+}
+
+export interface UrlSourceRef {
+    identity: string;
+    kind: 'url';
+    pin: string;
+    digest: string;
+    tier: 'read';
+    text: string;
+    degraded: typeof DEGRADED_NO_NETWORK | null;
+}
+
+function ipv4Private([p, q, r]: readonly number[]): boolean {
+    return (
+        p === 0 || p === 10 || p === 127 || (p as number) >= 224 ||
+        (p === 169 && q === 254) || (p === 172 && (q as number) >= 16 && (q as number) <= 31) || (p === 192 && q === 168) ||
+        (p === 100 && (q as number) >= 64 && (q as number) <= 127) || (p === 192 && q === 0 && r === 0) || (p === 198 && (q === 18 || q === 19))
+    );
+}
+
+/** The 16 bytes of an IPv6 address, an embedded dotted quad included. */
+function ipv6Bytes(a: string): number[] {
+    const quad = /(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(a);
+    const hex = quad === null ? a : `${a.slice(0, quad.index)}${((Number(quad[1]) << 8) | Number(quad[2])).toString(16)}:${((Number(quad[3]) << 8) | Number(quad[4])).toString(16)}`;
+    const [head, tail] = hex.split('::') as [string, string | undefined];
+    const groups = (s: string | undefined): string[] => (s === undefined || s === '' ? [] : s.split(':'));
+    const h = groups(head);
+    const t = groups(tail);
+    const words = [...h, ...Array<string>(tail === undefined ? 0 : 8 - h.length - t.length).fill('0'), ...t].map((g) => parseInt(g, 16));
+    return words.flatMap((w) => [w >> 8, w & 0xff]);
+}
+
+/**
+ * Loopback, private, link-local, unique-local, reserved and unspecified addresses,
+ * v4 and v6 — an IPv6 address that embeds an IPv4 one (mapped, compatible, NAT64,
+ * 6to4) is judged by the IPv4 address it reaches.
+ */
+export function isPrivateAddress(address: string): boolean {
+    const a = address.toLowerCase();
+    if (isIP(a) === 4) return ipv4Private(a.split('.').map(Number));
+    if (isIP(a) !== 6) return true;
+    const b = ipv6Bytes(a);
+    const zero = (from: number, to: number): boolean => b.slice(from, to).every((x) => x === 0);
+    if (zero(0, 10) && ((b[10] === 0xff && b[11] === 0xff) || (b[10] === 0 && b[11] === 0))) return ipv4Private(b.slice(12));
+    if (b[0] === 0x00 && b[1] === 0x64 && b[2] === 0xff && b[3] === 0x9b && zero(4, 12)) return ipv4Private(b.slice(12));
+    if (b[0] === 0x20 && b[1] === 0x02) return ipv4Private(b.slice(2, 6));
+    return (b[0] as number) >= 0xfc && (b[0] !== 0xfe || (b[1] as number) >= 0x80);
+}
+
+/** Throws unless `raw` is an http(s) URL without credentials whose host resolves only to public addresses. */
+export async function validateSourceUrl(raw: string, opts: NetworkOptions): Promise<URL> {
+    let url: URL;
+    try {
+        url = new URL(raw);
+    } catch {
+        throw new SourceError(`${raw}: not a URL`);
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') throw new SourceError(`${raw}: scheme ${url.protocol} is not read`);
+    if (url.username !== '' || url.password !== '') throw new SourceError(`${url.host}: a URL carrying credentials is refused`);
+    const host = url.hostname.replace(/^\[|\]$/g, '');
+    if (opts.allowPrivateHosts === true || (opts.hostAllowlistForTests ?? []).includes(host)) return url;
+    const addresses = isIP(host) !== 0 ? [host] : (await lookup(host, { all: true })).map((r) => r.address);
+    if (addresses.length === 0 || addresses.some(isPrivateAddress)) {
+        throw new SourceError(`${host}: resolves to a private, loopback or link-local address`);
+    }
+    return url;
+}
+
+async function readCapped(res: Response, maxBytes: number, where: string): Promise<Buffer> {
+    const reader = res.body?.getReader();
+    if (reader === undefined) return Buffer.alloc(0);
+    const chunks: Buffer[] = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel();
+            throw new SourceError(`${where}: body exceeds ${maxBytes} bytes`);
+        }
+        chunks.push(Buffer.from(value));
+    }
+    return Buffer.concat(chunks);
+}
+
+/** One read-only GET of a named source, every redirect hop re-validated. */
+export async function fetchUrlSource(raw: string, opts: NetworkOptions): Promise<UrlSourceRef> {
+    if (!opts.network) {
+        return { identity: raw, kind: 'url', pin: '', digest: '', tier: 'read', text: '', degraded: DEGRADED_NO_NETWORK };
+    }
+    const maxRedirects = opts.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+    let current = raw;
+    for (let hop = 0; hop <= maxRedirects; hop += 1) {
+        const url = await validateSourceUrl(current, opts);
+        const res = await fetch(url, {
+            redirect: 'manual',
+            headers: { accept: 'text/*, application/json' },
+            signal: AbortSignal.timeout(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+        });
+        if (res.status >= 300 && res.status < 400) {
+            const location = res.headers.get('location');
+            if (location === null) throw new SourceError(`${url.host}: redirect without a location`);
+            current = new URL(location, url).toString();
+            continue;
+        }
+        if (!res.ok) throw new SourceError(`${url.host}: HTTP ${res.status}`);
+        const body = await readCapped(res, opts.maxBytes ?? DEFAULT_MAX_BYTES, url.host);
+        const digest = `sha256:${createHash('sha256').update(body).digest('hex')}`;
+        return { identity: raw, kind: 'url', pin: digest, digest, tier: 'read', text: sanitize_text(body.toString('utf8')), degraded: null };
+    }
+    throw new SourceError(`${raw}: more than ${maxRedirects} redirects`);
+}
+
+/**
+ * A repository cloned at depth 1 into `workDir`, hooks disabled, then read
+ * through the local-clone adapter so the pin is the clone's HEAD as a file.
+ */
+export async function cloneRepoSource(raw: string, workDir: string, opts: NetworkOptions & { pinSha?: string }): Promise<SourceRef> {
+    if (!opts.network) throw new SourceError(`${raw}: ${DEGRADED_NO_NETWORK} — a repository needs the network`);
+    // Passed to git as an argument: anything but a full SHA could be read as an option.
+    if (opts.pinSha !== undefined && !/^[0-9a-f]{40}$/.test(opts.pinSha)) throw new SourceError(`${raw}: pin ${opts.pinSha} is not a 40-hex commit SHA`);
+    const local = raw.startsWith('file://') && opts.allowPrivateHosts === true;
+    if (!local) await validateSourceUrl(raw, opts);
+    const dest = path.join(workDir, 'source');
+    fs.mkdirSync(workDir, { recursive: true });
+    // An inherited GIT_DIR (a hook, a worktree) would point the clone at the caller's repository.
+    const { GIT_DIR: _d, GIT_WORK_TREE: _w, GIT_INDEX_FILE: _i, ...env } = process.env;
+    // git follows the first redirect by default, and only the URL above was validated: refuse every hop.
+    const git = (args: string[], cwd?: string): void => {
+        execFileSync('git', ['-c', 'core.hooksPath=/dev/null', '-c', 'protocol.ext.allow=never', '-c', 'http.followRedirects=false', ...args], {
+            cwd,
+            stdio: 'pipe',
+            timeout: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            env: { ...env, GIT_TERMINAL_PROMPT: '0' },
+        });
+    };
+    git(['clone', '--depth', '1', '--no-tags', '--', raw, dest]);
+    if (opts.pinSha !== undefined) {
+        git(['fetch', '--depth', '1', 'origin', opts.pinSha], dest);
+        git(['checkout', '--detach', opts.pinSha], dest);
+    }
+    const ref = resolveSource(dest);
+    if (opts.pinSha !== undefined && ref.pin !== opts.pinSha) throw new SourceError(`${raw}: HEAD ${ref.pin} is not the pin ${opts.pinSha}`);
+    return { ...ref, identity: raw };
+}
+
+/** The line of `needle` and at most fifteen words around it — the content-quoting floor. */
+export function quotedAnchor(text: string, needle: string): { line: number; quote: string } {
+    const lines = text.split('\n');
+    const i = lines.findIndex((l) => l.includes(needle));
+    if (i === -1) return { line: 0, quote: '' };
+    const words = (lines[i] as string).trim().split(/\s+/);
+    const at = Math.max(0, words.findIndex((w) => w.includes(needle)));
+    const start = Math.max(0, Math.min(at - 5, words.length - MAX_QUOTE_WORDS));
+    return { line: i + 1, quote: words.slice(start, start + MAX_QUOTE_WORDS).join(' ') };
+}
+
+/** Codes source identities S1, S2, …; the identities leave only as ENC1 tokens in the round's intake.md. */
+export class SourceCodebook {
+    private readonly ids: string[] = [];
+    private readonly tokens: string[] = [];
+
+    constructor(private readonly key: string) {}
+
+    code(identity: string): string {
+        let i = this.ids.indexOf(identity);
+        if (i === -1) {
+            this.ids.push(identity);
+            this.tokens.push(encrypt(identity, this.key));
+            i = this.ids.length - 1;
+        }
+        return `S${String(i + 1)}`;
+    }
+
+    intakeMarkdown(): string {
+        const rows = this.tokens.map((token, i) => `- S${String(i + 1)}: ${token}`);
+        return ['# Sources', '', 'Identities are encrypted (`link_crypto`); tracked output names only the codes.', '', ...rows, ''].join('\n');
+    }
+
+    writeIntake(roundDir: string): void {
+        fs.mkdirSync(roundDir, { recursive: true });
+        fs.writeFileSync(path.join(roundDir, 'intake.md'), this.intakeMarkdown());
+    }
+}

package/src/scripts/no_go_deny_rows.ts

@@ -0,0 +1,225 @@
+#!/usr/bin/env tsx
+/**
+ * Show what a consumer's `## No-gos` section would become as host deny rows —
+ * and, only with `--apply`, append them.
+ *
+ * `road-to-a-project-contract-written-down` step 2.2. `/agents:init` runs this
+ * WITHOUT `--apply` first, shows the rows, asks once, and runs it again with
+ * `--apply` only on a yes.
+ *
+ * ```
+ * WITHOUT --apply THIS WRITES NOTHING. THAT IS THE DEFAULT AND THE POINT.
+ * A HOST WITH NO ESTABLISHED DENY LIST GETS A REPORT, NEVER A FILE.
+ * ```
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/no_go_deny_rows [AGENTS.md] [--host claude]
+ *                                             [--settings .claude/settings.json]
+ *                                             [--apply]
+ *
+ * Exit codes: 0 — shown (or applied) · 1 — the file could not be read or the
+ * settings body is malformed · 2 — usage error.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+
+import { extractNoGosSection } from '../install/noGoRules.js';
+import {
+    appendDenyRules,
+    planDenyRows,
+    renderDenyPlan,
+} from '../install/noGoDenyRows.js';
+
+const USAGE =
+    'usage: no_go_deny_rows [AGENTS.md] [--host <host>] [--settings <path>] [--apply]\n\n' +
+    'Without --apply nothing is written.\n';
+
+interface Args {
+    readonly agentsMd: string;
+    readonly host: string;
+    readonly settings: string;
+    readonly apply: boolean;
+}
+
+function parse(argv: readonly string[]): Args | number {
+    if (argv.includes('-h') || argv.includes('--help')) {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    let host = 'claude';
+    let settings = '.claude/settings.json';
+    let apply = false;
+    const positional: string[] = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i] as string;
+        if (a === '--apply') {
+            apply = true;
+        } else if (a === '--host' || a === '--settings') {
+            const next = argv[i + 1];
+            if (next === undefined) {
+                process.stderr.write(`no_go_deny_rows: ${a} needs a value\n`);
+                return 2;
+            }
+            if (a === '--host') host = next;
+            else settings = next;
+            i += 1;
+        } else if (a.startsWith('-')) {
+            process.stderr.write(`no_go_deny_rows: unknown argument ${a}\n${USAGE}`);
+            return 2;
+        } else {
+            positional.push(a);
+        }
+    }
+    return { agentsMd: positional[0] ?? 'AGENTS.md', host, settings, apply };
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const args = parse(argv);
+    if (typeof args === 'number') return args;
+
+    const mdPath = path.resolve(args.agentsMd);
+    if (!fs.existsSync(mdPath)) {
+        process.stderr.write(`no_go_deny_rows: ${mdPath} not found\n`);
+        return 1;
+    }
+    const section = extractNoGosSection(fs.readFileSync(mdPath, 'utf8'));
+    const plan = planDenyRows(section, args.host);
+    process.stdout.write(renderDenyPlan(plan, args.host));
+
+    if (!args.apply) {
+        if (plan.rules.length > 0 && plan.enforceable) {
+            process.stdout.write(
+                '\nNothing was written. Re-run with --apply to append these rows.\n',
+            );
+        }
+        return 0;
+    }
+    if (!plan.enforceable) {
+        process.stdout.write(
+            `\n--apply ignored: no deny list is established for ${args.host}.\n`,
+        );
+        return 0;
+    }
+    if (plan.rules.length === 0) return 0;
+
+    const target = path.resolve(args.settings);
+    // `{\n}\n`, not `{}`. The splice inserts after the opening brace, so an
+    // inline `{}` produced a file ending `    }}` — which every consumer
+    // WITHOUT a settings file would have seen, the common case for a fresh
+    // repository. The "never reformat a file the consumer owns" rationale does
+    // not reach a file this command creates, so the created one is given a
+    // shape the splice lands in cleanly.
+    const before = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : '{\n}\n';
+    let result;
+    try {
+        result = appendDenyRules(before, plan.rules);
+    } catch (err) {
+        process.stderr.write(
+            `no_go_deny_rows: ${target} — ${err instanceof Error ? err.message : String(err)}\n`,
+        );
+        return 1;
+    }
+    if (result.added.length === 0) {
+        process.stdout.write('\nEvery row was already present; the file is unchanged.\n');
+        return 0;
+    }
+
+    // Verify BEFORE the file moves, not after. The settings file is the
+    // consumer's; a write that lands and then turns out to have dropped an
+    // entry has already cost them the file. Both checks run on the candidate
+    // text, and a failure writes nothing at all.
+    let roundTrip: { permissions?: { deny?: unknown } };
+    try {
+        roundTrip = JSON.parse(result.text) as { permissions?: { deny?: unknown } };
+    } catch {
+        process.stderr.write('no_go_deny_rows: the result would not parse — nothing written\n');
+        return 1;
+    }
+    const deny = roundTrip.permissions?.deny;
+    const kept = Array.isArray(deny) ? deny.filter((e): e is string => typeof e === 'string') : [];
+    const lost = priorDeny(before).filter((e) => !kept.includes(e));
+    if (lost.length > 0) {
+        process.stderr.write(
+            `no_go_deny_rows: ${String(lost.length)} existing entr(ies) would be lost — nothing written\n`,
+        );
+        return 1;
+    }
+    // The STRONG form of the module's own claim: the result is the file that
+    // was there, plus text at one point.
+    //
+    // It is NOT what catches a duplicated key, and an earlier version of this
+    // comment said it was. A second `"permissions"` inserted after the root
+    // brace IS the existing file plus one contiguous insertion, so this check
+    // returns true on exactly that output — measured by a reviewer. What
+    // refuses it is the consented-row check below, which reads the PARSED
+    // result and finds the row missing because the later duplicate won.
+    //
+    // Both stay. This one covers a different class: a splice that deleted or
+    // moved existing content, which a parse-level check cannot see.
+    if (!isSingleInsertion(before, result.text)) {
+        process.stderr.write(
+            'no_go_deny_rows: the result is not the existing file plus one insertion — ' +
+                'nothing written\n',
+        );
+        return 1;
+    }
+    // THIS is the duplicate-key net. It reads the parsed result, so a row that
+    // a later duplicate key shadowed is simply absent, whatever the text looks
+    // like.
+    if (!plan.rules.every((r) => kept.includes(r))) {
+        process.stderr.write(
+            'no_go_deny_rows: a consented row is not in the result — nothing written\n',
+        );
+        return 1;
+    }
+
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    // Write beside the target and rename, so an interrupted write leaves the
+    // consumer's file as it was rather than half of it.
+    const tmp = `${target}.agent-config.tmp`;
+    fs.writeFileSync(tmp, result.text, 'utf8');
+    fs.renameSync(tmp, target);
+    process.stdout.write(
+        `\n${String(result.added.length)} row(s) appended to ${args.settings}.\n`,
+    );
+    return 0;
+}
+
+/**
+ * Is `after` exactly `before` with one contiguous run of text inserted?
+ *
+ * Longest common prefix plus longest common suffix must account for every byte
+ * of `before`. Nothing is deleted, nothing is reordered, and nothing outside
+ * the insertion point moved — which is the property the splice claims and the
+ * property a deny-entry comparison cannot see.
+ */
+function isSingleInsertion(before: string, after: string): boolean {
+    if (after.length < before.length) return false;
+    let head = 0;
+    while (head < before.length && before[head] === after[head]) head += 1;
+    let tail = 0;
+    while (
+        tail < before.length - head &&
+        before[before.length - 1 - tail] === after[after.length - 1 - tail]
+    ) {
+        tail += 1;
+    }
+    return head + tail === before.length;
+}
+
+/** The deny entries a settings body already carried, or `[]`. */
+function priorDeny(body: string): readonly string[] {
+    try {
+        const parsed = JSON.parse(body) as { permissions?: { deny?: unknown } };
+        const deny = parsed.permissions?.deny;
+        return Array.isArray(deny) ? deny.filter((e): e is string => typeof e === 'string') : [];
+    } catch {
+        return [];
+    }
+}
+
+if (process.argv[1] !== undefined && import.meta.url === `file://${process.argv[1]}`) {
+    process.exit(main());
+}

package/src/scripts/orchestration_record.ts

@@ -9,15 +9,19 @@
  * Usage:
  *   ./scripts-run src/scripts/orchestration_record \
  *     --spawn-count 1 --token-delta -72000 --provenance measured \
- *     --tier-chosen lite --tier-source inferred --task-class read-only-fanout \
+ *     --tier-chosen lite --model-requested haiku --tier-source inferred --task-class read-only-fanout \
+ *     [--model-served claude-haiku-5-5] [--session-tier high] \
  *     [--rules-applied a,b] [--tiers sonnet,opus] [--agent-combo implementer,judge] [--wall-clock-ms 18500] [--dispatch-outcome DONE] \
- *     [--first-pass-success true|false] [--escalated true|false] \
+ *     [--first-pass-success true|false] [--escalated true|false] [--escalated-from lite|medium] \
  *     [--init-tokens 1200] [--payload-hash <hex8-64>] [--lookup-class definition|references|string-existence|report-run] \
  *     [--route-taken primitive|subagent|ask] [--budget-hit true|false] [--correctness-match true|false] \
  *     [--cache-hit true|false] [--origin lean-init-2026] \
  *     [--rules-carried 32] [--rules-used 5] \
  *     [--work-tokens 41000] [--floor-provenance measured|estimated] \
  *     [--capsule-emitted true|false] [--capsule-entries 9] \
+ *     [--hand-kind classify] [--schema-valid true|false] \
+ *     [--route-billing free-quota|self-hosted|per-token|subscription] \
+ *     [--verified pass|fail|skipped] [--verify-tokens 320] [--work-id <ask work id>] \
  *     [--dir <audit-dir>] [--dry-run]
  *
  * Read by `src/scripts/orchestration_savings_report.ts`.
@@ -29,6 +33,7 @@ import * as path from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 import type { LookupClass } from './_lib/auto_dispatch.js';
+import type { HandKind, RouteBilling, VerifyVerdict } from './_lib/hand_kinds.js';
 import {
     buildOrchestrationLine,
     type Provenance,
@@ -154,10 +159,13 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         wall_clock_ms: int(flags, 'wall-clock-ms'),
         dispatch_tokens: int(flags, 'dispatch-tokens'),
         session_tier: str(flags, 'session-tier'),
+        model_requested: str(flags, 'model-requested'),
+        model_served: str(flags, 'model-served'),
         dispatch_outcome: str(flags, 'dispatch-outcome') as DispatchOutcome | undefined,
         verify_mode: str(flags, 'verify-mode') as VerifyMode | undefined,
         first_pass_success: bool(flags, 'first-pass-success'),
         escalated: bool(flags, 'escalated'),
+        escalated_from: str(flags, 'escalated-from') as TierChosen | undefined,
         init_tokens: int(flags, 'init-tokens'),
         payload_hash: str(flags, 'payload-hash'),
         lookup_class: str(flags, 'lookup-class') as LookupClass | undefined,
@@ -172,6 +180,11 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         floor_provenance: str(flags, 'floor-provenance') as Provenance | undefined,
         capsule_emitted: bool(flags, 'capsule-emitted'),
         capsule_entries: int(flags, 'capsule-entries'),
+        hand_kind: str(flags, 'hand-kind') as HandKind | undefined,
+        schema_valid: bool(flags, 'schema-valid'),
+        route_billing: str(flags, 'route-billing') as RouteBilling | undefined,
+        verified: str(flags, 'verified') as VerifyVerdict | undefined,
+        verify_tokens: int(flags, 'verify-tokens'),
         phase: str(flags, 'phase') as LinePhase | undefined,
         outcome: str(flags, 'outcome') as LineOutcome | undefined,
         confidence_band: str(flags, 'confidence-band') as Band | undefined,

package/src/scripts/plan_test_shards.ts

@@ -0,0 +1,103 @@
+#!/usr/bin/env tsx
+/**
+ * Refresh `tests/timing-manifest.json`, the per-file seconds the balanced
+ * vitest sequencer (`tests/_lib/balanced-sequencer.ts`) assigns shards by.
+ *
+ * Input is the log of the node-tests jobs of one CI run, as
+ * `gh run view --job <id> --log` prints it: every file line of vitest's default
+ * reporter carries the file's duration, and the line prefix names the job, so
+ * the OS comes from the log itself. Measured on CI rather than locally, because
+ * a laptop's relative file costs are not a runner's.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/plan_test_shards --run <run-id> [--write]
+ *   ./scripts-run src/scripts/plan_test_shards --from-logs <file...> [--write]
+ *
+ * Without --write it prints the summary and leaves the manifest alone.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const MANIFEST = path.join(REPO_ROOT, 'tests', 'timing-manifest.json');
+const REPO = 'event4u-app/agent-config';
+
+const ANSI = /\x1b\[[0-9;]*m|\^\[\[[0-9;]*m/g;
+const FILE_LINE = /(?:✓|×|↓)\s+(?:\S+\s+)?((?:tests|src)\/\S+\.test\.tsx?)\s+\([^)]*\)\s+(\d+)ms\s*$/;
+
+export interface Durations {
+    ubuntu: Record<string, number>;
+    macos: Record<string, number>;
+}
+
+/** Per-file seconds by OS from one or more node-tests job logs. */
+export function parseLogs(text: string): Durations {
+    const out: Durations = { ubuntu: {}, macos: {} };
+    for (const raw of text.split('\n')) {
+        const line = raw.replace(ANSI, '');
+        const m = FILE_LINE.exec(line);
+        if (m === null) continue;
+        const os = /macos/i.test(line.split('\t')[0] ?? '') ? 'macos' : 'ubuntu';
+        out[os][m[1] as string] = Math.round(Number(m[2]) / 10) / 100;
+    }
+    return out;
+}
+
+function sortedRecord(r: Record<string, number>): Record<string, number> {
+    return Object.fromEntries(Object.entries(r).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+
+function logsForRun(runId: string): string {
+    const jobs = spawnSync('gh', ['api', `repos/${REPO}/actions/runs/${runId}/jobs?per_page=100`, '--jq',
+        '.jobs[] | select(.name|startswith("Node Tests")) | .id'], { encoding: 'utf-8' });
+    if (jobs.status !== 0) throw new Error(`gh api failed: ${jobs.stderr}`);
+    return jobs.stdout
+        .split('\n')
+        .filter((id) => id.trim() !== '')
+        .map((id) => {
+            const r = spawnSync('gh', ['run', 'view', '--job', id.trim(), '--repo', REPO, '--log'], {
+                encoding: 'utf-8',
+                maxBuffer: 256 * 1024 * 1024,
+            });
+            if (r.status !== 0) throw new Error(`gh run view --job ${id} failed: ${r.stderr}`);
+            return r.stdout;
+        })
+        .join('\n');
+}
+
+export function main(argv: readonly string[]): number {
+    const runAt = argv.indexOf('--run');
+    const logsAt = argv.indexOf('--from-logs');
+    let text: string;
+    let source: string;
+    if (runAt >= 0 && argv[runAt + 1] !== undefined) {
+        source = `run ${argv[runAt + 1] as string}`;
+        text = logsForRun(argv[runAt + 1] as string);
+    } else if (logsAt >= 0) {
+        const files = argv.slice(logsAt + 1).filter((a) => !a.startsWith('--'));
+        source = files.map((f) => path.basename(f)).join(', ');
+        text = files.map((f) => fs.readFileSync(f, 'utf-8')).join('\n');
+    } else {
+        process.stderr.write('usage: plan_test_shards --run <run-id> | --from-logs <file...> [--write]\n');
+        return 2;
+    }
+    const d = parseLogs(text);
+    const n = { ubuntu: Object.keys(d.ubuntu).length, macos: Object.keys(d.macos).length };
+    process.stdout.write(`files with a duration: ubuntu ${String(n.ubuntu)} · macos ${String(n.macos)}\n`);
+    if (n.ubuntu === 0 || n.macos === 0) {
+        process.stderr.write('❌  no durations for one OS — refusing to write a manifest that would balance nothing\n');
+        return 1;
+    }
+    if (argv.includes('--write')) {
+        const manifest = { source, ubuntu: sortedRecord(d.ubuntu), macos: sortedRecord(d.macos) };
+        fs.writeFileSync(MANIFEST, `${JSON.stringify(manifest, null, 2)}\n`);
+        process.stdout.write(`wrote ${path.relative(REPO_ROOT, MANIFEST)}\n`);
+    }
+    return 0;
+}
+
+if (process.argv[1] !== undefined && pathToFileURL(fs.realpathSync(process.argv[1])).href === import.meta.url) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/pr_url_reminder_hook.ts

@@ -29,6 +29,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { readHookStdin } from "./hooks/hook_stdin.js";
+import { record_pr } from "./_lib/session_pr_watch.js";
 
 const EXIT_ALLOW = 0;
 const EXIT_WARN = 2;
@@ -150,6 +151,15 @@ export function main(): number {
   }
   const url = match[0];
 
+  // Remember it for this session, so later prompts carry its live state
+  // (`_lib/session_pr_watch.ts`) instead of the state seen here.
+  try {
+    const root = String(envelope["workspace_root"] ?? inner["cwd"] ?? process.cwd());
+    record_pr(root, String(envelope["session_id"] ?? inner["session_id"] ?? "").trim(), url);
+  } catch {
+    /* a reminder that cannot record still reminds */
+  }
+
   // `reason` (≤ 200 chars) goes to stderr; `additional_context` is what
   // surfaces back to the model on platforms that support it — so the
   // actionable instruction lives there (a stderr-only reason would not

package/src/scripts/print_required_checks.ts

@@ -88,11 +88,11 @@ const FEATURE_CHECKS = [
     'Smoke — skills',
     'skill-lint',
     'Static Checks (ESLint · typecheck · prepack)',
-    'Install Script Tests (matrix: {ubuntu,macos}-latest × shard 1-4/4)',
-    'Install Aux Tests (matrix: {ubuntu,macos}-latest)',
-    'Node Tests (matrix: {ubuntu,macos}-latest × shard 1-4/4)',
-    'Golden Tests (matrix: {ubuntu,macos}-latest)',
-    'Workspace Tests (matrix: {ubuntu,macos}-latest)',
+    'Install Script Tests (ubuntu-latest × shard 1-4/4 · macos-26 unsharded)',
+    'Install Aux Tests (matrix: {ubuntu-latest,macos-26})',
+    'Node Tests (matrix: {ubuntu-latest,macos-26} × shard 1-4/4)',
+    'Golden Tests (matrix: {ubuntu-latest,macos-26})',
+    'Workspace Tests (matrix: {ubuntu-latest,macos-26})',
     'Public Install Smoke (matrix: {ubuntu,macos,windows}-latest × node {20,22})',
     'Rule backstops',
     'no-python-in-src',