@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/_lib/verification_command.ts

@@ -271,6 +271,28 @@ function segmentVerifies(rawWords: readonly string[]): boolean {
             // the old token-anywhere regex accepted it by accident and neither
             // explicit list named it, so the union seeding missed it too.
             return rest.some((a) => a === 'test' || a.startsWith('--test'));
+        case 'agent-config':
+            // NEITHER `ui:render` NOR `xmllint` verifies here, and the first
+            // half of that was true, then false, and is true again.
+            //
+            // Step 3.5 of `road-to-svg-with-a-witness` taught this predicate
+            // `ui:render --profile asset`, reasoning that it is the one
+            // subcommand which opens the delivered file in a real engine. Step
+            // 2.1(b) of `road-to-svg-review-followups` removed it again on
+            // review claim C2, which is narrower than the first argument and
+            // refutes it: the turn-end gate's TRANSCRIPT path matches a command
+            // and never sees an exit code, so a call that rendered nothing —
+            // the ordinary case on a machine with no Playwright, where the
+            // command also exited 0 until the same day — discharged the
+            // obligation from its text alone.
+            //
+            // What replaces it reads the RENDER instead of the call:
+            // `hooks/svg_obligation.ts` matches a manifest to the file's own
+            // digest, and accepts a renderer-absent manifest only together with
+            // a clean static witness on those same bytes. `xmllint --noout`
+            // stays out for its original reason (S6): a file can parse and
+            // still be the wrong picture.
+            return false;
         case 'scripts-run': {
             // `./scripts-run src/scripts/lint_x` verifies; `…/rule_activation_census`
             // writes a report and asserts nothing, which is why this keys on the
@@ -322,3 +344,40 @@ const _WIDE_CANDIDATE_RE =
 export function mightBeVerification(command: string): boolean {
     return _WIDE_CANDIDATE_RE.test(command);
 }
+
+/**
+ * `agent-config ui:render … --profile asset`, by shape.
+ *
+ * Moved here from `hooks/svg_obligation.ts` by finding 3 of this change's
+ * SECOND completion review: two detectors need it and one of them is in
+ * `_lib`, so a hook module was the wrong home. Re-exported there, so no
+ * caller moved.
+ */
+export function isAssetRenderCommand(command: string): boolean {
+    return /\bui:render\b/.test(command) && /--profile[= ]\s*asset\b/.test(command);
+}
+
+/**
+ * Did this command ATTEMPT to verify something — as opposed to: did it produce
+ * a verdict this gate may read?
+ *
+ * The distinction is the whole point, and the first review round and the
+ * second each saw one half of it. Round one (claim C2) was right that
+ * `isVerificationCommand` must NOT learn the asset render: the transcript path
+ * never sees an exit code, so the command's TEXT would have discharged the SVG
+ * obligation on a machine where the render produced nothing. Round two
+ * (finding 3) was right that removing it left detector C — "did any
+ * verification command follow the last edit" — unable to see the one command
+ * this package PRESCRIBES for an `.svg`, so the prescribed turn was refused.
+ *
+ * Both hold because they are about different detectors. Detector C asks
+ * whether the author tried; it is satisfied by `eslint` and must be satisfied
+ * by a render too. The SVG obligation asks what the render FOUND, and still
+ * reads the manifest and the file's digest — an attempt that produced nothing
+ * discharges nothing there, with a far better reason than detector C's.
+ *
+ * So: one predicate per question, and `isVerificationCommand` is unchanged.
+ */
+export function isVerificationAttempt(command: string): boolean {
+    return isVerificationCommand(command) || isAssetRenderCommand(command);
+}

package/src/scripts/_lib/verify_clause.ts

@@ -39,7 +39,9 @@
  * `closure_scan` report the unfalsifiable share as a number rather than an
  * impression.
  *
- * WHY ONE PARSER. Two importers read this grammar — the run-continuation hook
+ * WHY ONE PARSER. Three importers read this grammar — `roadmap_verify_share`,
+ * `check_verify_expectation_delta` and `closure_scan`. A fourth, the
+ * run-continuation hook
  * (which names the next step and its verify line) and `closure_scan` (which
  * reports the share that cannot fail). A second copy of the arrow regex is how
  * those two drift, and a drifted grammar fails silently: an expectation simply
@@ -126,25 +128,35 @@ function lastMatch(re: RegExp, text: string): RegExpExecArray | null {
  * carries `(?!`)`: a label followed by a backtick is the delimited form, which
  * branch one already owns.
  *
- * The tail is capped at a single non-space token on purpose. A caller may hand
- * this parser a whole step BLOCK already joined into one line, so "the rest of
- * the line" can mean "the rest of the step" — and a step that continues after
- * its verify clause would then push the expectation away from the end anchor
- * and lose it silently. The cost is that a regex expectation here may not
- * contain a space; `/[1-9]/` and `/unfalsifiable-verify/` are the shapes in
- * use, and a space-bearing expectation loses its arrow loudly (it parses as no
- * expectation) rather than half-matching.
+ * The tail is bounded by the EXPECTATION'S OWN DELIMITERS, not by the end of
+ * the line. A caller may hand this parser a whole step BLOCK already joined
+ * into one line, so "the rest of the line" can mean "the rest of the step": an
+ * end-anchored tail would lose the expectation of any step that carries prose
+ * after its clause. A slash-delimited regex therefore runs to the first
+ * UNESCAPED closing `/` — one not preceded by an odd number of backslashes —
+ * that is followed by whitespace or the end of the text, and an exit code is
+ * one non-space token; both self-terminating, so the step may continue and
+ * `-> /[1-9]/ and then note the result` still yields `[1-9]`.
  *
- * THE CAP IS THIS FORM'S, NOT THE GRAMMAR'S — said plainly because an earlier
- * revision of this comment implied otherwise. The annotation form is
- * `$`-anchored through {@link VERIFY_ARROW_SOURCE} and DOES keep `-> /a b/`;
- * this form does not. The two agree on every space-free expectation, which is
- * every expectation in the tree. Both directions are pinned by test, so closing
- * the gap is a deliberate act against a failing assertion rather than a silent
- * drift — which is the failure the WHY ONE PARSER note above exists to prevent,
- * and it applies to this module's own two readers first.
+ * The word UNESCAPED is load-bearing and was added on 2026-10-11 (step 1.1 of
+ * `road-to-svg-review-followups`, review claim C4). The tail used to be a lazy
+ * `\/.*?\/(?=\s|$)`, which stops at ANY `/` followed by a space — so a clause
+ * ending in ``-> /a\/ b/`` was cut at the escaped slash and parsed to the
+ * regex source `a\`. A pattern that deliberately matches a path separator is
+ * exactly the case that spells it `\/`, and the truncation was silent: a
+ * shorter regex is still a regex, so nothing reported the loss.
+ *
+ * It was capped at a single non-space token until 2026-10-11, which cost this
+ * form every expectation containing a space: `-> /Icon-only button/` parsed as
+ * a clause with NO expectation, and nothing reported the loss — the step simply
+ * read as unfalsifiable. The two forms now agree on every expectation rather
+ * than only the space-free ones; {@link VERIFY_ARROW_SOURCE} stays the single
+ * `$`-anchored decision about what an expectation IS, and this regex decides
+ * only where the tail ENDS. A bare word stays refused by the constant, so
+ * widening the boundary widened no grammar.
  */
-const BACKTICKED_RE = /(?:`verify:`|verify:(?!`))\s*`([^`]+)`[ \t]*((?:->|→)[ \t]*\S+)?/g;
+const BACKTICKED_RE =
+    /(?:`verify:`|verify:(?!`))\s*`([^`]+)`[ \t]*((?:->|→)[ \t]*(?:\/(?:[^\\/]|\\.)*\/(?=\s|$)|\S+))?/g;
 
 /** Prose after the label. The MANUAL form; the body is bounded separately. */
 const PROSE_RE = /(?:`verify:`|verify:(?!`))[ \t]*/g;
@@ -246,7 +258,7 @@ export function parseVerifyClause(stepText: string): VerifyClause | null {
 /**
  * The clause's command half only — `null` where the clause is prose or absent.
  *
- * The narrowing the run-continuation hook wants: it renders a command for the
+ * The narrowing the withdrawn run-continuation hook wanted: it rendered a command for the
  * next step, and a prose clause is not one. Kept here rather than at the call
  * site so the hook imports a decision rather than re-deriving it.
  */

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 };
+}