@event4u/agent-config 12.0.0 → 12.1.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;
@@ -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/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",

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",

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)}`);
     }