@event4u/agent-config 12.0.0 → 13.0.0

package/src/scripts/release.ts

@@ -536,7 +536,7 @@ function die(msg: string, code = 2): never {
     throw new SystemExitError(code);
 }
 
-interface RunResult {
+export interface RunResult {
     returncode: number;
     stdout: string;
     stderr: string;
@@ -879,14 +879,14 @@ function watch_pr_checks(branch: string): void {
  *
  * git's wording for this is stable across versions: the hint is `fetch first`
  * / `Updates were rejected`, and the ref line carries `[rejected]` with
- * `non-fast-forward` or `fetch first`.
+ * `non-fast-forward` or `fetch first`. A stale lease is a SECOND wording —
+ * `[remote rejected]` + `cannot lock ref … but expected`; pinned in the tests.
  */
 export function _is_non_fast_forward(stderr: string, stdout: string): boolean {
     const text = `${stderr}\n${stdout}`;
-    return (
-        /\[rejected\]/i.test(text) &&
-        /(non-fast-forward|fetch first|behind its remote counterpart)/i.test(text)
-    );
+    if (!/\[(?:remote )?rejected\]/i.test(text)) return false;
+    if (/cannot lock ref[^\n]*but expected/i.test(text)) return true;
+    return /(non-fast-forward|fetch first|behind its remote counterpart)/i.test(text);
 }
 
 function push_release_branch(branch: string): void {
@@ -1623,6 +1623,93 @@ function set_template_pin(p: string, version: string): void {
     fs.writeFileSync(p, lines.join('\n'), 'utf-8');
 }
 
+/**
+ * Refuse a MAJOR cut that carries a scheduled deprecation due at or before it.
+ *
+ * **The trigger is the shape of the TARGET, not a comparison with the current
+ * version.** A major target is `X.0.0` — and that one predicate covers every
+ * path to a major: the `--as major` flag, an explicit `--version 13.0.0`,
+ * auto-detection from a `feat!:` commit, AND `--resume`, where
+ * `_detect_in_flight_target()` returns the already-bumped `package.json`
+ * version so `target === current` and any current-vs-target comparison
+ * silently returns. Resume was the fourth path an earlier version of this
+ * guard missed while its own comment claimed three paths converged.
+ *
+ * Refusing a resumed release can strand a partially-completed one, and that is
+ * the deliberate trade: a stranded release is recoverable by fixing the table
+ * and resuming again, whereas a major shipped over a missed commitment is the
+ * failure this whole surface exists to prevent.
+ *
+ * The target version is PASSED to the gate. Without it the gate falls back to
+ * `package.json`, which at the cut to N still reads N-1 — so a row committed
+ * to N reads as one major early and passes, and only rows already a major late
+ * could ever be refused. That is the lateness being prevented, so measuring
+ * against the shipped version would have made the refusal fire exactly one
+ * major too late, forever.
+ *
+ * Runs under `--dry-run` too, unlike the rest of preflight: this check is one
+ * subprocess reading two files, so the "keep a preview fast" rationale that
+ * excludes the ~15s test-trend collection does not apply — and a preview that
+ * reports green for the single condition that will refuse the real run is the
+ * case an operator runs a preview to discover. It REPORTS there rather than
+ * dying: `--dry-run` exiting 0 before `execute()` and before `preflight()` is a
+ * contract this file's own tests assert, and an earlier revision of this guard
+ * broke it by sitting above the dry-run branch with no preview mode.
+ *
+ * @param runner Seam for the gate invocation. Production passes nothing and
+ * gets the real `run`; tests inject a stub, because the alternative — reaching
+ * this branch only by mutating `docs/MIGRATION.md` — would make the refusal
+ * path testable exclusively through a tracked-file edit.
+ */
+export function assert_scheduled_deprecations_clear(
+    target: string,
+    runner: (args: readonly string[]) => RunResult = (args) => run(args, { check: false, capture: true }),
+    opts: { previewOnly?: boolean } = {},
+): void {
+    const [, minor, patch] = parse_version(target);
+    if (minor !== 0 || patch !== 0) {
+        return;
+    }
+    const res = runner([
+        './scripts-run',
+        'src/scripts/lint_scheduled_deprecations',
+        '--cutting',
+        target,
+    ]);
+    if (res.returncode === 0) {
+        return;
+    }
+    process.stderr.write(res.stdout);
+    process.stderr.write(res.stderr);
+    if (res.returncode !== 1) {
+        // The gate reserves 1 for a finding and 2 for a usage/environment
+        // failure. Diagnosing the latter as "the table has an overdue row"
+        // sends the releaser to edit a file that is not the problem.
+        die(
+            `refusing the ${target} cut: the scheduled-deprecations check could not run ` +
+                `(exit ${String(res.returncode)}). That is an environment or usage failure, not a ` +
+                'finding in docs/MIGRATION.md — fix the invocation or the checkout, then re-run.',
+        );
+    }
+    if (opts.previewOnly === true) {
+        // The preview's job is to SHOW what the real run will refuse. Dying
+        // here would break the `--dry-run exits 0` contract asserted elsewhere
+        // in this file's tests — trading a documented exit code for a message
+        // that has already been printed above.
+        process.stderr.write(
+            `\n(dry-run) the ${target} cut WOULD BE REFUSED for the reason above. ` +
+                'Previewing only; exit code unchanged.\n',
+        );
+        return;
+    }
+    die(
+        `refusing the ${target} cut: the scheduled-deprecations table in docs/MIGRATION.md ` +
+            'has a row due at or before this major, or one that cannot be resolved. Act on ' +
+            "it — perform the removal in its own change, or revise the row's commitment and " +
+            'record why the surface stays — then re-run.',
+    );
+}
+
 // ─── preflight ────────────────────────────────────────────────────────────────
 
 /**
@@ -2578,6 +2665,13 @@ function main(argv: readonly string[] | null = null): number {
     }
     parse_version(target);
 
+    // Runs in dry-run too — a preview that hides the one condition which will
+    // refuse the real run is the case previews are for — but REPORTS there
+    // instead of dying: `--dry-run returns 0` is a contract this file's tests
+    // assert, and breaking it to surface a warning would trade a documented
+    // exit code for a message.
+    assert_scheduled_deprecations_clear(target, undefined, { previewOnly: args.dry_run });
+
     if (!args.dry_run) {
         preflight(target, { resume: args.resume, ci: args.ci });
     }

package/src/scripts/routing_doctor.ts

@@ -63,7 +63,7 @@ import {
   classifyTask,
   type ActivationInputs,
 } from "./_lib/auto_dispatch.js";
-import { TIER_ORDER, readCooldowns } from "./_lib/tier_budget_routing.js";
+import { COOLDOWN_FILE, TIER_ORDER, readCooldowns } from "./_lib/tier_budget_routing.js";
 import {
   instructionsLoadedRecord,
   measureStandingDelivery,
@@ -111,6 +111,13 @@ export interface OrchestrationReport {
   downshift: boolean;
   /** cost.budgets.per_tier ceilings + live cool-down state per tier. */
   tier_budgets: Record<string, { ceiling_usd: number | null; cooldown_until_ms: number }>;
+  /**
+   * Whether the cool-down store exists on disk. `readCooldowns` returns all
+   * zeros both when no tier is cooling AND when nothing has ever written the
+   * file, so a bare zero cannot distinguish "measured: live" from "no reading
+   * exists". This flag is what separates them.
+   */
+  cooldown_store_present: boolean;
   host_manifest: HostCapabilityManifest;
   /**
    * The host identifier the capability registry was keyed on, and whether it
@@ -158,14 +165,23 @@ export interface OrchestrationReport {
 }
 
 /**
- * Adherence ≠ delivery: budget-aware tier routing has no on/off setting any
- * more (always-on orchestration removed `subagents.budget_routing`), so the
- * doctor always checks the DELIVERY evidence — orchestration audit lines
- * that carry a tier decision. Dispatches recorded with ZERO tier-carrying
- * lines → WARN with the exact reason. Read-only over
- * agents/runtime/state/audit/*.jsonl; no new state. This closes the same
- * blind-spot class the session-canary incident exposed (policy present,
- * delivery silently absent).
+ * Tier-decision coverage in the orchestration record.
+ *
+ * REPOINTED 2026-08-16. This used to check "delivery evidence" for budget-aware
+ * tier routing, on the reasoning that policy can be present while delivery is
+ * silently absent — the session-canary blind-spot class. That layer is now
+ * ARCHIVED (`docs/contracts/budget-routing.md`), so the old rationale no longer
+ * holds and the old warning would have been permanently true and un-actionable:
+ * nothing dispatches through a tier decision by design, so telling the operator
+ * "the relation may not be running" is a dead advisory of exactly the shape this
+ * repository keeps removing elsewhere.
+ *
+ * What it measures now is narrower and still worth having: how many recorded
+ * dispatches carry a `tier` at all. That is the SAME field the archived layer's
+ * revisit-if depends on — a saving can only be computed once both the chosen and
+ * the realized tier are recorded — so this is the instrument that would show the
+ * reopen condition arriving. It reports coverage rather than warning about it.
+ * Read-only over agents/runtime/state/audit/*.jsonl; no new state.
  */
 export function check_budget_delivery(
   workspace_root: string,
@@ -202,9 +218,10 @@ export function check_budget_delivery(
   }
   if (out.eligible_dispatches > 0 && out.budget_evidence_lines === 0) {
     out.warning =
-      `budget-aware tier routing shows no delivery evidence: ` +
-      `${out.eligible_dispatches} orchestration dispatch(es) recorded, 0 carry a tier decision — ` +
-      `the relation may not be running (adherence != delivery)`;
+      `tier-decision coverage is 0 of ${out.eligible_dispatches} recorded dispatch(es) — ` +
+      `expected while budget routing stays archived (docs/contracts/budget-routing.md). ` +
+      `This is the counter its revisit-if reads: a non-zero value here is the signal ` +
+      `that per-tier dispatch has reappeared and the decision can be reopened`;
   }
   return out;
 }
@@ -356,6 +373,7 @@ export function collect_orchestration(
   const ledger_present = fs.existsSync(path.join(tracking_dir, "sessions.jsonl"));
   const per_tier = (cost_budgets["per_tier"] ?? {}) as Record<string, unknown>;
   const cooldowns = readCooldowns(tracking_dir);
+  const cooldown_store_present = fs.existsSync(path.join(tracking_dir, COOLDOWN_FILE));
   const tier_budgets: OrchestrationReport["tier_budgets"] = {};
   for (const t of TIER_ORDER) {
     const v = per_tier[t];
@@ -382,6 +400,7 @@ export function collect_orchestration(
     halted,
     downshift,
     tier_budgets,
+    cooldown_store_present,
     host_manifest,
     host_platform: platform,
     host_platform_assumed: platform_assumed,
@@ -636,10 +655,28 @@ function _render(report: DoctorReport): string {
   );
   const tierBits = Object.entries(o.tier_budgets).map(([t, s]) => {
     const cap = s.ceiling_usd === null ? "no cap" : `$${s.ceiling_usd}`;
-    const cool = s.cooldown_until_ms > 0 ? " COOLING" : "";
+    // `> Date.now()`, not `> 0`. The purger went with the archived permit
+    // lifecycle (`tripCooldown` rewrote the map on every write), so a stale
+    // entry now has nothing to clear it and `> 0` would render COOLING for
+    // ever. Latent rather than live — there is no writer either — but the
+    // comparison should be the one that stays correct if a writer returns.
+    const cool = s.cooldown_until_ms > Date.now() ? " COOLING" : "";
     return `${t}=${cap}${cool}`;
   });
   lines.push(`  tier budgets (rolling-24h): ${tierBits.join(" · ")}`);
+  // `readCooldowns` returns all zeros both when no tier is cooling and when
+  // nothing has ever written the store, so a missing COOLING marker alone
+  // cannot be read as a measured "this tier is live". Report which of the two
+  // it is — the same unavailable-vs-false distinction the capability-
+  // provenance line above makes two lines earlier. Derived from the store's
+  // existence rather than from a caller count, so it stays true if the
+  // cool-down producer is ever wired.
+  if (!o.cooldown_store_present) {
+    lines.push(
+      `  cool-down state: no reading on disk (${COOLDOWN_FILE} absent) — ` +
+        `absence of COOLING above is not evidence of a live tier`,
+    );
+  }
   if (o.delivery.warning) {
     lines.push(`  ⚠️ ${o.delivery.warning}`);
   } else if (o.delivery.eligible_dispatches > 0) {

package/src/scripts/schemas/command.schema.json

@@ -158,8 +158,8 @@
     },
     "model_tier": {
       "type": "string",
-      "enum": ["lite", "medium", "high", "inherit"],
-      "description": "Vendor-neutral capability band the command needs (ADR-035). Commands project as Claude skills, so high/medium/lite produce a native Claude `model:` (high→opus, medium→sonnet, lite→haiku) when model.auto_switch=auto; the generator owns that mapping. inherit keeps the session model. Non-Claude agents are suggestion-only. No vendor model names here."
+      "enum": ["lite", "medium", "high", "frontier", "inherit"],
+      "description": "Vendor-neutral capability band the command needs (ADR-035, amended by ADR-232). Commands project as Claude skills, so frontier/high/medium/lite produce a native Claude `model:` when model.auto_switch=auto; the generator owns that mapping. inherit keeps the session model. `frontier` is the band above the strongest generally-recommended one - opt-in and expected to stay rare. Non-Claude agents are suggestion-only. No vendor model names here."
     },
     "context": {
       "type": "string",
@@ -254,7 +254,7 @@
     },
     "requires_confirmation": {
       "type": "boolean",
-      "description": "Optional, additive: the command's action STAGES rather than executes, so an irreversible step waits for an explicit human confirmation naming the exact object (non-destructive-by-default § Never act while asking). Twin of the same key in skill.schema.json's execution block; commands carry no execution block, so it sits top-level. A declaration only — it names the action class, never the object, which exists at stage time and not in frontmatter. Mechanism: stageAction/confirmOnce in work_engine/hooks/builtin/staged_confirmation.ts; enumerate with `agent-config gates --pending`. Nothing BINDS on it yet (blocker confirmation-degraded-host-semantics: 5 of 8 hosts have no pre_tool_use slot)."
+      "description": "Optional, additive: the command's action STAGES rather than executes, so an irreversible step waits for an explicit human confirmation naming the exact object (non-destructive-by-default § Never act while asking). Twin of the same key in skill.schema.json's execution block; commands carry no execution block, so it sits top-level. A declaration only — it names the action class, never the object, which exists at stage time and not in frontmatter. Mechanism: stageAction/confirmOnce in work_engine/hooks/builtin/staged_confirmation.ts; enumerate with `agent-config gates --pending`. Nothing BINDS on it yet (blocker confirmation-degraded-host-semantics: only claude both binds pre_tool_use and honours a deny — docs/contracts/hook-architecture-v1.md, section Which hosts carry pre_tool_use)."
     },
     "auto_detect": {
       "type": "boolean",

package/src/scripts/schemas/skill.schema.json

@@ -168,9 +168,10 @@
         "lite",
         "medium",
         "high",
+        "frontier",
         "inherit"
       ],
-      "description": "Vendor-neutral capability band the skill needs (ADR-035). high/medium/lite project to a native Claude `model:` (high→opus, medium→sonnet, lite→haiku) when model.auto_switch=auto; the generator owns that mapping exclusively. inherit keeps the session model. Non-Claude agents are suggestion-only — the model-recommendation rule names the tier and the agent resolves its own model. No vendor model names here."
+      "description": "Vendor-neutral capability band the skill needs (ADR-035, amended by ADR-232). frontier/high/medium/lite project to a native Claude `model:` when model.auto_switch=auto; the generator owns that mapping exclusively. inherit keeps the session model. `frontier` means reasoning capability above the strongest generally-recommended band - opt-in and expected to stay rare, so work that genuinely needs it says so instead of inheriting it silently. Non-Claude agents are suggestion-only - the model-recommendation rule names the tier and the agent resolves its own model. No vendor model names here."
     },
     "context": {
       "type": "string",
@@ -275,7 +276,7 @@
         },
         "requires_confirmation": {
           "type": "boolean",
-          "description": "Optional, additive: the skill's action STAGES rather than executes, so an irreversible step waits for an explicit human confirmation naming the exact object (non-destructive-by-default § Never act while asking). A declaration only — it names the action class, never the object, which exists at stage time and not in frontmatter. The mechanism is stageAction/confirmOnce in work_engine/hooks/builtin/staged_confirmation.ts; enumerate what is pending with `agent-config gates --pending`. Nothing BINDS on this flag yet: on 5 of 8 hosts there is no pre_tool_use slot, so a guard would degrade to prose while the flag reads like a control — that decision is deferred behind blocker confirmation-degraded-host-semantics."
+          "description": "Optional, additive: the skill's action STAGES rather than executes, so an irreversible step waits for an explicit human confirmation naming the exact object (non-destructive-by-default § Never act while asking). A declaration only — it names the action class, never the object, which exists at stage time and not in frontmatter. The mechanism is stageAction/confirmOnce in work_engine/hooks/builtin/staged_confirmation.ts; enumerate what is pending with `agent-config gates --pending`. Nothing BINDS on this flag yet: only claude both binds pre_tool_use and honours a deny (docs/contracts/hook-architecture-v1.md, section Which hosts carry pre_tool_use — 2 further hosts bind it and ignore the verdict, 3 alias it unbound, 2 have no pre-tool surface), so a guard would degrade to prose on 7 of 8 hosts while the flag reads like a control — that decision is deferred behind blocker confirmation-degraded-host-semantics."
         },
         "command": {
           "type": "array",
@@ -286,6 +287,23 @@
         }
       }
     },
+    "triggers": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "keyword": {"type": "string", "minLength": 1},
+          "phrase": {"type": "string", "minLength": 1},
+          "file_pattern": {"type": "string", "minLength": 1},
+          "path_prefix": {"type": "string", "minLength": 1},
+          "command": {"type": "string", "minLength": 1},
+          "reason": {"type": "string"}
+        }
+      },
+      "description": "Activation triggers for the SKILL catalogue, shaped after the rule-side field so the two stay legible together — same five match keys (keyword, phrase, file_pattern, path_prefix, command), same additionalProperties:false, and deliberately no `intent` key, which was removed rule-side for giving authors false confidence that an activation path existed. OPTIONAL and empty of adopters on the day it ships: the capability becomes declarable before anything declares it, so a seeded tranche is measurable against the router corpus before it is written. Read by scripts/trigger_coverage.ts --scope skill through the same router_match.ts matcher the rule scope uses — not a fork. Schema: docs/contracts/rule-router.md."
+    },
     "workspaces": {
       "type": "array",
       "minItems": 1,

package/src/scripts/schemas/subagent.schema.json

@@ -34,8 +34,8 @@
     },
     "model_tier": {
       "type": "string",
-      "enum": ["lite", "medium", "high", "inherit"],
-      "description": "Vendor-neutral capability band (ADR-034/035). high/medium/lite project to a native Claude `model:` (high→opus, medium→sonnet, lite→haiku) via model_tier.ts; `inherit` is a documented passthrough sentinel (→ CC `model: inherit`), not a new mapping."
+      "enum": ["lite", "medium", "high", "frontier", "inherit"],
+      "description": "Vendor-neutral capability band (ADR-034/035, amended by ADR-232). frontier/high/medium/lite project to a native Claude `model:` via model_tier.ts; `inherit` is a documented passthrough sentinel (→ CC `model: inherit`), not a new mapping. `frontier` is the band above the strongest generally-recommended one - opt-in, expected to stay rare, and never the resolution of `inherit`."
     },
     "effort": {
       "type": "string",

package/src/scripts/session_eol_report.ts

@@ -61,6 +61,33 @@ export interface EolReport {
         compact_summary_records: number;
         marker_drift: boolean;
     };
+    /**
+     * State-destroyed vs state-captured, as ONE reading
+     * (road-to-inbox-harvest-2026-08-d-context-ledger Step 2.2).
+     *
+     * Before this, a compaction count and an advisory count sat in two places
+     * and nobody correlated them, so "how often was state destroyed with no
+     * capture in front of it" had no answer at all.
+     *
+     * HONEST LIMIT, stated in the shape rather than in prose only: the two
+     * sides come from different corpora — compactions are scanned out of
+     * transcripts, the advisory stamps live in per-session state files under a
+     * hashed key — and no field joins a transcript to its state file. So this
+     * is an AGGREGATE comparison over the same store, not a per-session join,
+     * and `join_basis` says so on every emitted report. A reader may compare
+     * the totals; a reader may NOT conclude that a specific compaction lacked
+     * a capture.
+     */
+    capture: {
+        /** Session-eol state files found. `null` ⇒ the directory is absent. */
+        state_files: number | null;
+        /** State files carrying an `advisory_fired_at` stamp. */
+        advisory_fired: number;
+        /** State files that additionally recorded "advised, but no envelope". */
+        advised_without_envelope: number;
+        /** Always `"aggregate"` today. See the doc comment. */
+        join_basis: 'aggregate';
+    };
     /** Pearson r of file bytes vs final context tokens over the readable set. */
     bytes_tokens_pearson_r: number | null;
     threshold_crossings: Record<string, number>;
@@ -130,6 +157,47 @@ export function scanSessionFile(file: string): SessionSummary | null {
     return { file, bytes, counters, last_ts };
 }
 
+/** Where `session_eol_hook` persists its per-session state (gitignored). */
+export const SESSION_EOL_STATE_REL = path.join('agents', 'runtime', 'state', 'session-eol');
+
+/**
+ * The capture side of the Step-2.2 reading.
+ *
+ * `state_files: null` distinguishes "the directory is not there" from "it is
+ * there and empty" — an instrument that reports 0 for both cannot tell a quiet
+ * estate from one it cannot see, which is the failure the sibling ledger fixed
+ * for its own open-record set.
+ */
+export function scanCaptureState(root: string): EolReport['capture'] {
+    const dir = path.join(root, SESSION_EOL_STATE_REL);
+    let names: string[];
+    try {
+        names = fs.readdirSync(dir).filter((n) => n.endsWith('.json'));
+    } catch {
+        return { state_files: null, advisory_fired: 0, advised_without_envelope: 0, join_basis: 'aggregate' };
+    }
+
+    let advisoryFired = 0;
+    let advisedWithoutEnvelope = 0;
+    for (const name of names) {
+        try {
+            const parsed: unknown = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf-8'));
+            if (typeof parsed !== 'object' || parsed === null) continue;
+            const rec = parsed as Record<string, unknown>;
+            if (typeof rec['advisory_fired_at'] === 'string') advisoryFired++;
+            if (typeof rec['missing_envelope_warned_at'] === 'string') advisedWithoutEnvelope++;
+        } catch {
+            // A torn or hand-edited state file is data we do not have.
+        }
+    }
+    return {
+        state_files: names.length,
+        advisory_fired: advisoryFired,
+        advised_without_envelope: advisedWithoutEnvelope,
+        join_basis: 'aggregate',
+    };
+}
+
 export function buildReport(root: string, now: Date = new Date()): EolReport {
     const files = listTranscriptFiles({ root });
     const sessions: SessionSummary[] = [];
@@ -176,6 +244,7 @@ export function buildReport(root: string, now: Date = new Date()): EolReport {
             compact_summary_records: summaryRecords,
             marker_drift: summaryRecords !== allEvents.length,
         },
+        capture: scanCaptureState(root),
         bytes_tokens_pearson_r: pearson(
             withUsage
                 .filter((s) => (s.counters.final_context_tokens as number) > 1_000)
@@ -216,6 +285,18 @@ export function renderText(r: EolReport): string {
             `  trigger pre-tokens: min=${fmt(c.pre_tokens.min)} median=${fmt(c.pre_tokens.median)} max=${fmt(c.pre_tokens.max)}`,
         );
     }
+    // Step 2.2: the capture side, printed directly under the destruction side
+    // so the two are read together. `join_basis` is printed every time — a
+    // reader must not mistake an aggregate comparison for a per-session join.
+    const cap = r.capture;
+    if (cap.state_files === null) {
+        lines.push(`  capture: no session-eol state directory — capture side UNOBSERVED (not zero)`);
+    } else {
+        lines.push(
+            `  capture: ${cap.advisory_fired} of ${cap.state_files} state file(s) advised, ` +
+                `${cap.advised_without_envelope} advised with no envelope [join: ${cap.join_basis}]`,
+        );
+    }
     if (c.post_tokens) {
         lines.push(`  post-tokens median=${fmt(c.post_tokens.median)}`);
     }