@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/_lib/version_order.ts

@@ -0,0 +1,146 @@
+/**
+ * Version ordering for policy decisions — SemVer 2.0.0 precedence including
+ * prereleases, and the subset of npm range syntax that `engines.node` uses.
+ *
+ * Pure: no filesystem, no network, no process state. Every function answers
+ * `null` (or `false` for the boolean helper in `update_check.ts`) on input it
+ * cannot parse, because a caller deciding whether to act must treat "cannot
+ * tell" as "do not act", never as "older" or "newer".
+ */
+
+export interface ParsedVersion {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+    readonly pre: readonly (string | number)[];
+}
+
+const NUM = '(0|[1-9]\\d*)';
+const IDENT = '[0-9A-Za-z-]+';
+const VERSION_RE = new RegExp(
+    `^v*${NUM}\\.${NUM}\\.${NUM}(?:-(${IDENT}(?:\\.${IDENT})*))?(?:\\+${IDENT}(?:\\.${IDENT})*)?$`,
+);
+
+export function parse_version(v: unknown): ParsedVersion | null {
+    if (typeof v !== 'string') return null;
+    const m = VERSION_RE.exec(v.trim());
+    if (!m) return null;
+    const pre = m[4] === undefined ? [] : m[4].split('.').map((id) => (/^\d+$/.test(id) ? Number(id) : id));
+    return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]), pre };
+}
+
+function cmp_num(a: number, b: number): number {
+    return a === b ? 0 : a < b ? -1 : 1;
+}
+
+function compare_parsed(a: ParsedVersion, b: ParsedVersion): number {
+    const core = cmp_num(a.major, b.major) || cmp_num(a.minor, b.minor) || cmp_num(a.patch, b.patch);
+    if (core !== 0) return core;
+    if (a.pre.length === 0 || b.pre.length === 0) return cmp_num(b.pre.length, a.pre.length);
+    for (let i = 0; i < Math.max(a.pre.length, b.pre.length); i += 1) {
+        const x = a.pre[i];
+        const y = b.pre[i];
+        if (x === undefined) return -1;
+        if (y === undefined) return 1;
+        if (typeof x === 'number' && typeof y === 'number') {
+            if (x !== y) return cmp_num(x, y);
+        } else if (typeof x === 'number') {
+            return -1;
+        } else if (typeof y === 'number') {
+            return 1;
+        } else if (x !== y) {
+            return x < y ? -1 : 1;
+        }
+    }
+    return 0;
+}
+
+/** -1 / 0 / 1 by SemVer precedence; `null` when either side does not parse. */
+export function compare_versions(a: unknown, b: unknown): -1 | 0 | 1 | null {
+    const pa = parse_version(a);
+    const pb = parse_version(b);
+    if (pa === null || pb === null) return null;
+    return compare_parsed(pa, pb) as -1 | 0 | 1;
+}
+
+interface Bound {
+    readonly op: '>=' | '<' | '>' | '<=' | '=';
+    readonly v: ParsedVersion;
+}
+
+const PARTIAL_RE = /^(\^|~|>=|<=|>|<|=)?v?(\d+|[xX*])(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?$/;
+
+function at(major: number, minor = 0, patch = 0): ParsedVersion {
+    return { major, minor, patch, pre: [] };
+}
+
+function bounds_for(token: string): Bound[] | null {
+    if (token === '*' || token === 'x' || token === 'X') return [];
+    const m = PARTIAL_RE.exec(token);
+    if (!m) return null;
+    const op = m[1] ?? '=';
+    const parts = [m[2], m[3], m[4]];
+    const known: number[] = [];
+    for (const p of parts) {
+        if (p === undefined || /^[xX*]$/.test(p)) break;
+        known.push(Number(p));
+    }
+    if (known.length === 0) return op === '<' || op === '>' ? null : [];
+    const [M, mi = 0, pa = 0] = known;
+    const full = known.length === 3;
+    const next = known.length === 1 ? at(M! + 1) : known.length === 2 ? at(M!, mi + 1) : at(M!, mi, pa + 1);
+    const base = at(M!, mi, pa);
+    switch (op) {
+        case '^': {
+            const upper = M! > 0 ? at(M! + 1) : known.length === 1 ? at(1) : mi > 0 ? at(0, mi + 1) : full ? at(0, 0, pa + 1) : at(0, 1);
+            return [{ op: '>=', v: base }, { op: '<', v: upper }];
+        }
+        case '~':
+            return [{ op: '>=', v: base }, { op: '<', v: known.length === 1 ? at(M! + 1) : at(M!, mi + 1) }];
+        case '>=':
+            return [{ op: '>=', v: base }];
+        case '<':
+            return [{ op: '<', v: base }];
+        case '>':
+            return [full ? { op: '>', v: base } : { op: '>=', v: next }];
+        case '<=':
+            return [full ? { op: '<=', v: base } : { op: '<', v: next }];
+        default:
+            return full ? [{ op: '=', v: base }] : [{ op: '>=', v: base }, { op: '<', v: next }];
+    }
+}
+
+function holds(b: Bound, v: ParsedVersion): boolean {
+    const c = compare_parsed(v, b.v);
+    if (b.op === '>=') return c >= 0;
+    if (b.op === '>') return c > 0;
+    if (b.op === '<') return c < 0;
+    if (b.op === '<=') return c <= 0;
+    return c === 0;
+}
+
+/**
+ * Does `runtime` (a `process.version` string) satisfy the `engines.node`
+ * range? `null` when either side cannot be parsed, and `null` for a prerelease
+ * runtime: npm's own engines check includes prereleases, whose range bounds this
+ * subset does not reproduce, so a prerelease is "cannot tell" here — the same
+ * uncertainty `classifyUpdate` records for a prerelease candidate.
+ */
+export function node_engine_satisfied(range: unknown, runtime: unknown): boolean | null {
+    const v = parse_version(runtime);
+    if (v === null || typeof range !== 'string') return null;
+    const sets: Bound[][] = [];
+    for (const alt of range.split('||')) {
+        const tokens = alt.trim().replace(/(\^|~|>=|<=|>|<|=)\s+/g, '$1').split(/\s+/).filter(Boolean);
+        if (tokens.includes('-')) return null;
+        const set: Bound[] = [];
+        for (const t of tokens) {
+            const b = bounds_for(t);
+            if (b === null) return null;
+            set.push(...b);
+        }
+        sets.push(set);
+    }
+    if (v.pre.length > 0) return null;
+    return sets.some((set) => set.every((b) => holds(b, v)));
+}

package/src/scripts/_lib/worker_reuse.ts

@@ -0,0 +1,191 @@
+/**
+ * Warm-worker reuse decision — pure, no I/O.
+ *
+ * The caller reaches this only after the in-session and lookup rungs have
+ * declined to stay in-session; it answers one question for one candidate
+ * worker: re-task it (`resume`) or spawn cold (`fresh`). Every condition is an
+ * input, so no prose sets a number and the decision object can be replayed.
+ *
+ * The register of workers is a VIEW: callers derive each {@link WorkerState}
+ * from the subagent ledger and the worker's transcript at decision time, and
+ * address the worker by its durable name. Nothing here is a store, and no
+ * field can hold the host's opaque per-run token — the ledger refuses to write
+ * one for the same reason.
+ */
+import { validateCapsule, type WorkerCapsule } from './subagent_capsule.js';
+
+export type ReuseClass = 'continuity' | 'never';
+
+/** One candidate worker as derived at decision time. */
+export interface WorkerState {
+    /** Durable name — the only address a resume uses. */
+    name: string;
+    /** Domain the durable name encodes. */
+    domain: string;
+    /** From the worker's definition; `never` for judges and reviewers. */
+    reuse: ReuseClass;
+    last_request_at_ms: number;
+    /** The worker's effective cache TTL. */
+    cache_ttl_ms: number;
+    /** Tokens currently in the worker's transcript. */
+    transcript_tokens: number;
+    /** The worker's capsule watermark (`worker_budget.watermarkForTier`). */
+    capsule_watermark_tokens: number;
+    /** A compaction boundary appears in the transcript. */
+    compacted: boolean;
+    /** Workspace facts recorded at the worker's last stop. */
+    worktree: string;
+    branch_head: string;
+    skill_set_signature: string;
+    /** Installed package version at the worker's last stop — the policy epoch. */
+    package_version: string;
+}
+
+/** The dispatch being decided, with the current workspace facts. */
+export interface ReuseContext {
+    domain: string;
+    now_ms: number;
+    /**
+     * Observed median first-call cost of a FRESH run of this definition, from
+     * the cache-realization report. `null` when none was observed; a resume is
+     * then refused rather than compared against an invented constant.
+     */
+    observed_fresh_cold_start_tokens: number | null;
+    worktree: string;
+    branch_head: string;
+    skill_set_signature: string;
+    package_version: string;
+}
+
+export const REFUSAL_REASONS = [
+    'domain_mismatch',
+    'cache_ttl_expired',
+    'transcript_over_cold_start',
+    'no_observed_cold_start',
+    'over_capsule_watermark',
+    'compacted',
+    'workspace_changed',
+    'not_continuity',
+    'policy_epoch_changed',
+] as const;
+export type RefusalReason = (typeof REFUSAL_REASONS)[number];
+
+/**
+ * Reasons that retire a worker rather than merely skip it: the task is still
+ * this worker's, but its context is no longer worth paying for, so a successor
+ * is briefed from its capsule. A domain mismatch or a `never` definition is a
+ * different task or a judge, and spawns plain fresh.
+ */
+export const RETIRING_REASONS: readonly RefusalReason[] = [
+    'cache_ttl_expired',
+    'transcript_over_cold_start',
+    'no_observed_cold_start',
+    'over_capsule_watermark',
+    'compacted',
+    'workspace_changed',
+    'policy_epoch_changed',
+];
+
+export interface WorkerReuseDecision {
+    verdict: 'resume' | 'fresh';
+    /** The worker to re-task on `resume`; `null` on `fresh`. */
+    name: string | null;
+    /** Every failing condition, in condition order; empty on `resume`. */
+    reasons: RefusalReason[];
+    inputs: { worker: WorkerState; context: ReuseContext };
+}
+
+export function decideWorkerReuse(worker: WorkerState, context: ReuseContext): WorkerReuseDecision {
+    const reasons: RefusalReason[] = [];
+    if (worker.domain !== context.domain) reasons.push('domain_mismatch');
+    if (context.now_ms - worker.last_request_at_ms >= worker.cache_ttl_ms) reasons.push('cache_ttl_expired');
+    if (context.observed_fresh_cold_start_tokens === null) reasons.push('no_observed_cold_start');
+    else if (worker.transcript_tokens >= context.observed_fresh_cold_start_tokens) reasons.push('transcript_over_cold_start');
+    if (worker.transcript_tokens >= worker.capsule_watermark_tokens) reasons.push('over_capsule_watermark');
+    if (worker.compacted) reasons.push('compacted');
+    if (
+        worker.worktree !== context.worktree ||
+        worker.branch_head !== context.branch_head ||
+        worker.skill_set_signature !== context.skill_set_signature
+    ) {
+        reasons.push('workspace_changed');
+    }
+    if (worker.reuse !== 'continuity') reasons.push('not_continuity');
+    if (worker.package_version !== context.package_version) reasons.push('policy_epoch_changed');
+
+    return {
+        verdict: reasons.length === 0 ? 'resume' : 'fresh',
+        name: reasons.length === 0 ? worker.name : null,
+        reasons,
+        inputs: { worker, context },
+    };
+}
+
+/** Names of the workers that would be re-tasked for this dispatch, in input order. */
+export function eligibleWorkers(workers: readonly WorkerState[], context: ReuseContext): string[] {
+    return workers.filter((w) => decideWorkerReuse(w, context).verdict === 'resume').map((w) => w.name);
+}
+
+/**
+ * Reasons the shadow guard can record before any worker is compared: the host
+ * offers no resume, no worker register was recorded, or the register is empty.
+ * An unrecorded register is NOT an empty one — conflating them would let a
+ * missing writer read as "no worker was ever eligible".
+ */
+export type ShadowPreconditionReason = 'host_resume_unobserved' | 'worker_register_unrecorded' | 'no_candidate';
+
+export type ShadowReuseVerdict =
+    | { verdict: 'would_resume'; name: string; reasons: [] }
+    | { verdict: 'fresh'; name: null; reasons: Array<RefusalReason | ShadowPreconditionReason> };
+
+export interface ShadowReuseInput {
+    /** The host row's `worker_resume`; false means nothing below is read. */
+    host_resume: boolean;
+    /** The register view, or null when none was recorded. */
+    workers: readonly WorkerState[] | null;
+    context: ReuseContext | null;
+}
+
+/**
+ * The verdict `spawn-guard-shadow` records for one spawn: the name of the first
+ * eligible worker in register order (the caller's order is the contract), or
+ * `fresh` with every candidate's refusal reasons, each once, in condition order.
+ */
+export function shadowReuseVerdict(input: ShadowReuseInput): ShadowReuseVerdict {
+    if (!input.host_resume) return { verdict: 'fresh', name: null, reasons: ['host_resume_unobserved'] };
+    if (input.workers === null || input.context === null) {
+        return { verdict: 'fresh', name: null, reasons: ['worker_register_unrecorded'] };
+    }
+    if (input.workers.length === 0) return { verdict: 'fresh', name: null, reasons: ['no_candidate'] };
+    const seen = new Set<RefusalReason>();
+    for (const w of input.workers) {
+        const d = decideWorkerReuse(w, input.context);
+        if (d.verdict === 'resume' && d.name !== null) return { verdict: 'would_resume', name: d.name, reasons: [] };
+        for (const r of d.reasons) seen.add(r);
+    }
+    return { verdict: 'fresh', name: null, reasons: REFUSAL_REASONS.filter((r) => seen.has(r)) };
+}
+
+export type SuccessorBrief =
+    | { kind: 'resume'; name: string }
+    | { kind: 'fresh' }
+    | { kind: 'successor'; predecessor: string; generation: number; capsule: WorkerCapsule }
+    | { kind: 'stop-loss'; predecessor: string; errors: string[] };
+
+/**
+ * What the orchestrator does with a decision. A retired worker's successor is
+ * briefed from the predecessor's `worker` capsule; a missing or invalid
+ * capsule never briefs one and falls back to the stop-loss path loudly.
+ */
+export function briefSuccessor(decision: WorkerReuseDecision, capsule: WorkerCapsule | null): SuccessorBrief {
+    if (decision.verdict === 'resume' && decision.name !== null) return { kind: 'resume', name: decision.name };
+    if (!decision.reasons.some((r) => RETIRING_REASONS.includes(r))) return { kind: 'fresh' };
+    if (decision.reasons.includes('domain_mismatch') || decision.reasons.includes('not_continuity')) {
+        return { kind: 'fresh' };
+    }
+    const predecessor = decision.inputs.worker.name;
+    if (capsule === null) return { kind: 'stop-loss', predecessor, errors: ['no capsule from the retired worker'] };
+    const errors = validateCapsule(capsule);
+    if (errors.length > 0) return { kind: 'stop-loss', predecessor, errors };
+    return { kind: 'successor', predecessor, generation: capsule.generation + 1, capsule };
+}

package/src/scripts/_lib/workspace_secrets.ts

@@ -0,0 +1,273 @@
+/**
+ * Shared secret-detection + scrub primitives for the workspace stores.
+ *
+ * Lives under `src/scripts/_lib/` because a shipped module
+ * (`cross_repo_retrieve.ts`) reads it and `src/cli/` is not in the package;
+ * `src/cli/python/workspace_secrets.ts` re-exports it for the workspace stores.
+ * The contract — the exported names, the per-call match counts, `scrub_obj`'s
+ * depth and cycle guard and the `[SECRET]` placeholder — is pinned by
+ * `tests/scripts/cli/python/workspace_secrets.test.ts`, and what it detects by
+ * `egress_legacy_superset.test.ts`.
+ *
+ * Near-leaf module — its one import is the pure rule table (no I/O) — so the
+ * hot-path analytics `emit()` and the heavier `knowledge_ingest` can both
+ * depend on it cheaply without dragging in PII redaction, chunking, or file
+ * I/O. Every workspace store that persists text or arbitrary payloads at rest
+ * routes through this module before writing (Phase 8 Step 5 secret-hygiene
+ * sweep).
+ *
+ * Two confidence tiers:
+ *
+ * - **HIGH** — structurally unambiguous credentials: the credential rows of
+ *   the one rule table (vendor keys, tokens, PEM private-key block, a
+ *   connection URI with an inline password). Near-zero false-positive rate, so
+ *   safe to scrub destructively or to refuse a write over.
+ * - **FUZZY** — the generic `key/secret/token/password = <value>` assignment.
+ *   Fires on legitimate prose ("password reset token: see attached"), so it is
+ *   warn-only on user-authored content and only scrubbed on disposable,
+ *   machine-generated telemetry (sessions / analytics).
+ *
+ * The `[SECRET]` placeholder matches the knowledge-ingestion redactor so the
+ * two surfaces stay byte-consistent.
+ */
+
+import {
+    assignmentPattern,
+    detect,
+    EGRESS_RULES,
+    type EgressRule,
+    maskingEnd,
+    prefixesOf,
+    rawKeyPrefixPattern,
+} from './egress_rules.js';
+
+export const PLACEHOLDER = '[SECRET]';
+
+// --- HIGH-confidence tier: the credential rows of the one rule table -------
+//
+// Detection lives in `src/scripts/_lib/egress_rules.ts`, the only place a
+// credential pattern is defined (road-to-one-detector-and-the-senders-we-own
+// 2.2); this module keeps its own policy — the `[SECRET]` placeholder, the
+// HIGH/FUZZY tiers and the counts. `generic-assignment` is left to the FUZZY tier
+// below, which is this module's own, looser reading of the same shape.
+
+const HIGH_RULES: readonly EgressRule[] = EGRESS_RULES.filter(
+    (r) => r.class === 'credential' && r.rule !== 'generic-assignment',
+);
+
+// The finding names this module has always reported; a row without one reports
+// its rule id.
+const LEGACY_NAME: Readonly<Record<string, string>> = {
+    'pem-private-key': 'private_key',
+    'aws-access-key': 'aws_access_key',
+    'github-pat': 'github_pat',
+    'github-app-token': 'github_pat',
+    'openai-api-key': 'openai_key',
+};
+const LEGACY_ORDER = ['private_key', 'aws_access_key', 'github_pat', 'openai_key'];
+const rank = (name: string): number => {
+    const i = LEGACY_ORDER.indexOf(name);
+    return i < 0 ? LEGACY_ORDER.length : i;
+};
+
+// This module's own, looser readings of two shapes, kept so the move to the
+// table narrows nothing: the GitHub token family at any length and an OpenAI key
+// glued to a preceding word. The prefixes are the table's.
+const OWN_SHAPES: ReadonlyArray<readonly [string, RegExp]> = [
+    [
+        'github_pat',
+        rawKeyPrefixPattern(36, [...prefixesOf('github-pat'), ...prefixesOf('github-app-token')], {
+            boundary: 'never',
+            tail: 'A-Za-z0-9',
+        }),
+    ],
+    ['openai_key', rawKeyPrefixPattern(20, prefixesOf('openai-api-key'), { boundary: 'never', tail: 'A-Za-z0-9' })],
+];
+
+type Span = { name: string; start: number; end: number };
+
+/** HIGH spans in report order, each widened to the bytes a scrub must remove. */
+function highSpans(text: string): Span[] {
+    const spans: Span[] = detect(text, HIGH_RULES).map((s) => ({
+        name: LEGACY_NAME[s.rule] ?? s.rule,
+        start: s.start,
+        end: maskingEnd(text, s),
+    }));
+    for (const [name, re] of OWN_SHAPES) {
+        for (const m of text.matchAll(re)) spans.push({ name, start: m.index, end: m.index + m[0].length });
+    }
+    // One finding per value: a span inside another span of the same name is that span.
+    const kept = spans.filter(
+        (a, i) =>
+            !spans.some(
+                (b, j) =>
+                    j !== i &&
+                    b.name === a.name &&
+                    b.start <= a.start &&
+                    b.end >= a.end &&
+                    (b.end - b.start > a.end - a.start || j < i),
+            ),
+    );
+    return kept.sort((x, y) => rank(x.name) - rank(y.name) || x.start - y.start);
+}
+
+// --- FUZZY pattern (heuristic key/value assignment) -------------------------
+// Python `(?i)` inline flag → JS `i` flag. Character class is identical.
+// The keyword shape is the table's; the 12-character value is this module's threshold.
+const _RE_KV_SECRET = assignmentPattern(
+    {
+        keywords: ['apiKey', 'secret', 'token', 'password', 'passwd', 'bearer'],
+        value: `['"]?[A-Za-z0-9_\\-+/=]{12,}['"]?`,
+    },
+    'i',
+);
+
+type PatternEntry = readonly [string, RegExp];
+
+export const FUZZY: readonly PatternEntry[] = [['kv_secret', _RE_KV_SECRET]];
+
+// Recursion guard for `scrub_obj` — deep / cyclic structures degrade to a
+// controlled return instead of a RangeError on the never-raises hot path.
+const _MAX_DEPTH = 50;
+
+/** One secret match. Carries the pattern name + tier, never the value. */
+export interface Finding {
+    /** e.g. "aws_access_key" */
+    pattern: string;
+    /** "high" | "fuzzy" */
+    confidence: string;
+}
+
+/**
+ * Build a global-flagged clone of `pat` so `matchAll` / `replace` get
+ * left-to-right non-overlapping iteration matching Python `finditer` / `subn`,
+ * without mutating the shared stateless module-level pattern.
+ */
+function _global(pat: RegExp): RegExp {
+    const flags = pat.flags.includes('g') ? pat.flags : pat.flags + 'g';
+    return new RegExp(pat.source, flags);
+}
+
+/** Count of non-overlapping matches — mirrors `len(list(pat.finditer(text)))`. */
+function _finditerCount(pat: RegExp, text: string): number {
+    let n = 0;
+    for (const _m of text.matchAll(_global(pat))) n += 1;
+    return n;
+}
+
+/** `pat.subn(repl, text)` → `[clean, count]` (non-overlapping, left-to-right). */
+function _subn(pat: RegExp, repl: string, text: string): [string, number] {
+    let count = 0;
+    const clean = text.replace(_global(pat), () => {
+        count += 1;
+        return repl;
+    });
+    return [clean, count];
+}
+
+/**
+ * Non-destructive detection: one {@link Finding} per match.
+ *
+ * Never echoes the matched secret value — only the pattern name and tier,
+ * so a caller can warn or refuse without re-leaking the secret into a log.
+ */
+export function scan(text: unknown, opts?: { include_fuzzy?: boolean }): Finding[] {
+    const include_fuzzy = opts?.include_fuzzy ?? true;
+    if (typeof text !== 'string' || !text) {
+        return [];
+    }
+    const out: Finding[] = highSpans(text).map((s) => ({ pattern: s.name, confidence: 'high' }));
+    if (include_fuzzy) {
+        for (const [name, pat] of FUZZY) {
+            const n = _finditerCount(pat, text);
+            for (let i = 0; i < n; i += 1) out.push({ pattern: name, confidence: 'fuzzy' });
+        }
+    }
+    return out;
+}
+
+/** Replace every secret match with `[SECRET]`; return `[clean, count]`. */
+export function scrub(text: unknown, opts?: { include_fuzzy?: boolean }): [string, number] {
+    const include_fuzzy = opts?.include_fuzzy ?? true;
+    if (typeof text !== 'string' || !text) {
+        return [text as string, 0];
+    }
+    const spans = highSpans(text).sort((x, y) => x.start - y.start);
+    const merged: Array<{ start: number; end: number }> = [];
+    for (const sp of spans) {
+        const last = merged[merged.length - 1];
+        if (last !== undefined && sp.start < last.end) last.end = Math.max(last.end, sp.end);
+        else merged.push({ start: sp.start, end: sp.end });
+    }
+    let out = text;
+    for (let i = merged.length - 1; i >= 0; i -= 1) {
+        const m = merged[i] as { start: number; end: number };
+        out = out.slice(0, m.start) + PLACEHOLDER + out.slice(m.end);
+    }
+    let count = merged.length;
+    if (include_fuzzy) {
+        for (const [, pat] of FUZZY) {
+            const [next, n] = _subn(pat, PLACEHOLDER, out);
+            out = next;
+            count += n;
+        }
+    }
+    return [out, count];
+}
+
+/**
+ * Recursively scrub string leaves in object / array structures.
+ *
+ * Non-string leaves (number, boolean, null) pass through untouched. Recursion
+ * is bounded by a depth cap and a cycle guard so malformed or self-referential
+ * payloads degrade to a controlled return, never a stack overflow — callers on
+ * a never-raises hot path (`workspace_analytics.emit`) rely on this. Returns
+ * `[clean, count]`.
+ *
+ * Python distinguishes `list` (→ list) from `tuple` (→ tuple); JS has only
+ * `Array`, so an array round-trips as an array, matching the Python `list`
+ * branch (the workspace stores never feed a tuple through this path).
+ */
+export function scrub_obj(
+    obj: unknown,
+    opts?: { include_fuzzy?: boolean; _depth?: number; _seen?: Set<unknown> },
+): [unknown, number] {
+    const include_fuzzy = opts?.include_fuzzy ?? true;
+    const _depth = opts?._depth ?? 0;
+    const _seen = opts?._seen ?? new Set<unknown>();
+    if (_depth > _MAX_DEPTH) {
+        return [obj, 0];
+    }
+    if (typeof obj === 'string') {
+        return scrub(obj, { include_fuzzy });
+    }
+    if (Array.isArray(obj)) {
+        if (_seen.has(obj)) {
+            return [obj, 0];
+        }
+        _seen.add(obj);
+        let total = 0;
+        const items: unknown[] = [];
+        for (const value of obj) {
+            const [cv, n] = scrub_obj(value, { include_fuzzy, _depth: _depth + 1, _seen });
+            items.push(cv);
+            total += n;
+        }
+        return [items, total];
+    }
+    if (obj !== null && typeof obj === 'object') {
+        if (_seen.has(obj)) {
+            return [obj, 0];
+        }
+        _seen.add(obj);
+        let total = 0;
+        const clean: Record<string, unknown> = {};
+        for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+            const [cv, n] = scrub_obj(value, { include_fuzzy, _depth: _depth + 1, _seen });
+            clean[key] = cv;
+            total += n;
+        }
+        return [clean, total];
+    }
+    return [obj, 0];
+}

package/src/scripts/_lib/worktree_git.ts

@@ -0,0 +1,67 @@
+/**
+ * The git and gh subprocess layer of the worktree cleanup: one deadline for a
+ * budgeted pass, and an environment that can neither refresh an index nor be
+ * redirected to another repository.
+ */
+
+import { execFileSync } from 'node:child_process';
+
+/**
+ * An absolute deadline for every git and gh subprocess while a budgeted pass
+ * runs. A budget checked only between candidates is not a budget: one slow
+ * `git status` would run past it. With a deadline set, each call gets only the
+ * time left, and a call that would start after it throws — so the pass fails
+ * closed instead of finishing late.
+ */
+let subprocessDeadline: number | null = null;
+
+export function withDeadline<T>(deadlineAt: number, fn: () => T): T {
+    const prev = subprocessDeadline;
+    subprocessDeadline = deadlineAt;
+    try {
+        return fn();
+    } finally {
+        subprocessDeadline = prev;
+    }
+}
+
+export function timeLeftMs(): number | undefined {
+    if (subprocessDeadline === null) return undefined;
+    const left = subprocessDeadline - Date.now();
+    if (left <= 0) throw new Error('budget spent');
+    return left;
+}
+
+export function git(cwd: string, args: string[], input?: string): string {
+    const timeout = timeLeftMs();
+    return execFileSync('git', ['-C', cwd, ...args], {
+        encoding: 'utf-8',
+        stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
+        ...(input === undefined ? {} : { input }),
+        ...(timeout === undefined ? {} : { timeout }),
+        // No git call made here may refresh an index: the inventory reads index
+        // mtimes as a liveness fallback, so a refresh would fake activity.
+        env: gitEnv(),
+    });
+}
+
+export function tryGit(cwd: string, args: string[], input?: string): string | null {
+    try {
+        return git(cwd, args, input);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * The caller's environment minus the variables that redirect `git -C`: a hook
+ * process inherits `GIT_DIR` / `GIT_WORK_TREE` / `GIT_INDEX_FILE`, and with any
+ * of them set every per-worktree call would read the wrong repository.
+ */
+export function gitEnv(): NodeJS.ProcessEnv {
+    const env: NodeJS.ProcessEnv = { ...process.env, GIT_OPTIONAL_LOCKS: '0' };
+    delete env.GIT_DIR;
+    delete env.GIT_WORK_TREE;
+    delete env.GIT_INDEX_FILE;
+    return env;
+}