@event4u/agent-config 14.17.0 → 14.19.0

package/src/scripts/_lib/release_material.ts

@@ -288,3 +288,132 @@ function _first_diff(a: string, b: string): string {
     }
     return 'surfaces differ only in normalization-invisible content';
 }
+
+/**
+ * The marker the governance-versus-product response line carries.
+ *
+ * Relocated here on 2026-09-05 from `check_release_highlights.ts`, where it was
+ * defined next to the refusal that reads it. That placement is why 14.17.0
+ * failed: the gate owned the marker, so the **generator** could not write the
+ * line without importing a gate, and therefore did not write it at all. The
+ * obligation was then discoverable only after `gh pr create` had already spent
+ * a branch, a PR and a CI run — the exact cost `guard_release_branch_push` was
+ * added to avoid for the sibling obligation two releases earlier.
+ *
+ * This module has no imports on purpose (see `CURATED_HEAD_INSTRUCTION`), which
+ * is what lets the writer, the local push guard and the CI gate all reach one
+ * definition instead of three copies.
+ */
+export const MIX_RESPONSE_MARKER = '**Governance mix:**';
+
+/**
+ * The sentinel that marks an EMITTED-BUT-UNANSWERED response.
+ *
+ * A generator that emits the measured level alone would satisfy the gate's
+ * length floor (`MIX_RESPONSE_MIN_CHARS`, 40) with a number the machine
+ * produced, turning a written-answer obligation into a formality the tool
+ * discharges for itself. That is a smuggled auto-approval, not a fix.
+ *
+ * So the writer emits the level AND this sentinel, and every gate refuses the
+ * sentinel — the same discipline `CURATED_HEAD_INSTRUCTION` and
+ * `DERIVED_MARKER` already follow. The net effect is only that the obligation
+ * moves from CI to the moment the section is written, where the fix is an edit
+ * to a file already open in the working tree.
+ */
+export const MIX_RESPONSE_PLACEHOLDER = '<the consumer work>';
+
+/**
+ * Every placeholder token the writer emits, so none of them can ship.
+ *
+ * The block carries two, and refusing only the first would leave
+ * `<roadmap or issue>` publishable — `CHANGELOG.md` is in `package.json`
+ * `files`, so that is the same "the generator's own scaffolding reached npm"
+ * failure `CURATED_HEAD_INSTRUCTION` exists for, one token to the right.
+ *
+ * A named list rather than a shape match over angle brackets, for the reason
+ * that constant already states: a pattern such as `/<[a-z ]+>/` rejects
+ * unrelated legitimate prose and misses a reworded placeholder. Adding a token
+ * to `render_mix_response` means adding it here.
+ */
+export const MIX_RESPONSE_PLACEHOLDERS: readonly string[] = [
+    MIX_RESPONSE_PLACEHOLDER,
+    '<roadmap or issue>',
+];
+
+/**
+ * Render the response block the writer emits when the obligation triggers.
+ *
+ * Two blockquote lines, immediately under the curated head and outside it, per
+ * `docs/contracts/CHANGELOG-conventions.md` § Governance-versus-product
+ * response — the head's ten-line cap is for product lines, and a sixth label
+ * would make every historical section retroactively incomplete.
+ */
+export function render_mix_response(level: string): string[] {
+    return [
+        `> ${MIX_RESPONSE_MARKER} ${level}.`,
+        `> ${PROMISE_PHRASE} ${MIX_RESPONSE_PLACEHOLDER}, tracked in <roadmap or issue>.`,
+    ];
+}
+
+/**
+ * The words that turn a governance response into a PROMISE about a later cycle.
+ *
+ * Named rather than inlined because two sides now read it: the writer emits it,
+ * and the next release reads the previous section for it to decide whether a
+ * read-back is owed. A promise nothing reads back costs nothing to restate, so
+ * it can be restated for as many cycles as there are cycles — the defect this
+ * constant exists to make addressable.
+ */
+export const PROMISE_PHRASE = 'Next cycle ships';
+
+/**
+ * The marker under which a release head answers the PREVIOUS head's promise.
+ *
+ * A named sentinel, on the same discipline as `MIX_RESPONSE_MARKER` and
+ * `DERIVED_MARKER`: a shape match over prose would accept a sentence that
+ * happens to mention last cycle and reject a reworded answer.
+ */
+export const PROMISE_READBACK_MARKER = '**Previous cycle:**';
+
+/**
+ * The three outcomes a read-back may report, and the reason there are exactly
+ * three.
+ *
+ * `shipped` and `did not ship` are the honest halves of the fact. `withdrawn`
+ * exists because a promise the project decided not to keep is a legitimate
+ * third state — but only WITH a reason, which is why the answer also has to
+ * clear a written-length floor rather than being one of these three words on
+ * its own. Without the third state the mechanism would push an author toward
+ * restating a dead promise as still-outstanding, which is the failure it is
+ * built to stop.
+ */
+export const PROMISE_OUTCOMES: readonly string[] = ['shipped', 'did not ship', 'withdrawn'];
+
+/** Every `## X.Y.Z` release version in the file, in document order (newest first). */
+export function changelog_versions(text: string): string[] {
+    const out: string[] = [];
+    for (const m of text.matchAll(/^##\s+\[?(\d+\.\d+\.\d+)\b/gmu)) {
+        out.push(m[1] as string);
+    }
+    return out;
+}
+
+/**
+ * The release published immediately before `version`, or null when there is none.
+ *
+ * Read from the CHANGELOG rather than from git tags on purpose: the promise
+ * being read back is a property of the SECTION, and a tag can exist for a
+ * version whose section was archived into `docs/archive/` under an era split —
+ * in which case there is no previous promise reachable in this file and the
+ * honest answer is that none is owed.
+ *
+ * `version` itself need not be present: a section still under authoring is
+ * named `[Unreleased]`, so the caller passes the version it is releasing and
+ * gets the newest RELEASED version that is not it.
+ */
+export function previous_changelog_version(text: string, version: string): string | null {
+    const versions = changelog_versions(text);
+    const idx = versions.indexOf(version);
+    if (idx !== -1) return versions[idx + 1] ?? null;
+    return versions[0] ?? null;
+}

package/src/scripts/_lib/repeated_run.ts

@@ -0,0 +1,77 @@
+/**
+ * The repeated-run evidence mode and the `flaky` outcome.
+ *
+ * `docs/contracts/evidence-artifact-types.md` § The second axis is the
+ * contract; this is the executable half, so "a run that passes 4 of 5 times is
+ * recorded as flaky rather than as passing" is a thing a test can assert rather
+ * than a sentence in a document.
+ *
+ * Two rules carry the whole design, both from the AI council of 2026-09-04
+ * (2/2 convergent):
+ *
+ *   1. **`n >= 2`.** `repeated:1` is `single-run` wearing extra syntax, and
+ *      admitting it would let one run be presented as a repeat.
+ *   2. **Unanimity, no threshold.** All pass → pass. All fail → fail. Anything
+ *      else → flaky. A 4-of-5 pass is precisely the case this exists to stop
+ *      being called a pass, so a majority rule would defeat the purpose.
+ */
+
+export type ExecutionMode = { kind: 'single-run' } | { kind: 'repeated'; n: number };
+
+export type RepeatedOutcome = 'pass' | 'fail' | 'flaky';
+
+/** The marker, when an artifact declares one. `single-run` is never written. */
+export const EVIDENCE_MODE_RE = /<!--\s*evidence-mode:\s*(single-run|repeated:(\d+))\s*-->/;
+
+/**
+ * Read the mode an artifact declares.
+ *
+ * Absent → `single-run`, which is the default that keeps this axis from being
+ * a migration. A malformed `repeated:<n>` with `n < 2` is rejected rather than
+ * rounded to `single-run`: a declaration that does not parse must not read to
+ * its author as accepted.
+ */
+export function parseExecutionMode(text: string): ExecutionMode | { kind: 'invalid'; reason: string } {
+    const m = EVIDENCE_MODE_RE.exec(text);
+    if (m === null) return { kind: 'single-run' };
+    if (m[1] === 'single-run') return { kind: 'single-run' };
+    const n = Number(m[2]);
+    if (!Number.isInteger(n) || n < 2) {
+        return {
+            kind: 'invalid',
+            reason: `repeated:${String(n)} declares fewer than 2 runs; repeated:1 is single-run with extra syntax`,
+        };
+    }
+    return { kind: 'repeated', n };
+}
+
+/**
+ * Aggregate `n` retained per-run verdicts.
+ *
+ * Takes the RUNS, never a summary count — an artifact that kept only
+ * "3 of 5 passed" has recorded a number, not evidence, and this signature is
+ * where that requirement is enforced rather than requested.
+ */
+export function aggregateRepeatedRuns(runs: readonly boolean[]): RepeatedOutcome {
+    if (runs.length < 2) {
+        throw new Error(
+            `aggregateRepeatedRuns needs at least 2 retained runs, got ${String(runs.length)}; ` +
+                'a single run is `single-run`, not a repeat',
+        );
+    }
+    if (runs.every((r) => r)) return 'pass';
+    if (runs.every((r) => !r)) return 'fail';
+    return 'flaky';
+}
+
+/** One line for the artifact, so `flaky` is reported as itself. */
+export function describeRepeatedRun(runs: readonly boolean[]): string {
+    const outcome = aggregateRepeatedRuns(runs);
+    const passed = runs.filter((r) => r).length;
+    const line = `evidence-mode: repeated:${String(runs.length)} · outcome: ${outcome} · ${String(passed)}/${String(runs.length)} passed`;
+    if (outcome !== 'flaky') return line;
+    return (
+        `${line} — the runs did not agree, so this is neither a pass nor a fail. ` +
+        'Recording it as either would be the silent green or the silent red this outcome exists to prevent.'
+    );
+}

package/src/scripts/_lib/runtime_journal.ts

@@ -174,6 +174,8 @@ import type { DatabaseSync } from 'node:sqlite';
 import { current_branch, git_common_dir, git_dir } from './git_common_dir.js';
 import type { TerminalState } from './outcome_envelope.js';
 import { readRunTerminalState, RUN_TERMINAL_STATES } from './outcome_vocabularies.js';
+import { addColumnIfMissing } from './sqlite_schema.js';
+import { readSurface, type Surface } from './surface.js';
 import {
     isSqliteAvailableSync,
     loadSqliteSync,
@@ -408,6 +410,14 @@ export interface JournalEvent {
     at: string;
     /** Bounded identifier: the hook or command name. Never free text. */
     capability: string;
+    /**
+     * IDE / CLI / cloud dimension of the dispatch. Closed vocabulary, and
+     * almost always `unknown`: no host observed here sends a distinguishing
+     * marker and the detector refuses to infer one. Recorded anyway because
+     * "did this come from the surface the lattice assumed" has no answer at
+     * all while the field is absent.
+     */
+    surface: Surface;
     /** Imported from `outcome_envelope.ts`; null until an episode terminates. */
     terminal_state: TerminalState | null;
     /** Repo-relative locator for the return. Never an absolute path. */
@@ -447,6 +457,7 @@ export const JOURNAL_RECORD_KEYS = Object.freeze([
     'worktree_id',
     'at',
     'capability',
+    'surface',
     'terminal_state',
     'return_ref',
     'verification_ref',
@@ -759,6 +770,7 @@ function createSchema(db: DatabaseSync): void {
             worktree_id TEXT NOT NULL,
             at TEXT NOT NULL,
             capability TEXT NOT NULL,
+            surface TEXT NOT NULL DEFAULT 'unknown',
             terminal_state TEXT,
             return_ref TEXT,
             verification_ref TEXT,
@@ -767,6 +779,9 @@ function createSchema(db: DatabaseSync): void {
             amends_seq INTEGER
         )`,
     );
+    // A pre-existing row takes the default, which is the honest value: that
+    // dispatch was never asked what surface it came from.
+    addColumnIfMissing(db, 'journal_event', 'surface', "TEXT NOT NULL DEFAULT 'unknown'");
     db.exec('CREATE INDEX IF NOT EXISTS idx_event_episode ON journal_event(repository_id, episode_id, seq)');
     db.exec('CREATE INDEX IF NOT EXISTS idx_event_session ON journal_event(repository_id, session_id, seq)');
     db.exec('CREATE INDEX IF NOT EXISTS idx_event_task ON journal_event(repository_id, task_id)');
@@ -984,6 +999,8 @@ export interface RecordEventInput {
     prompt_id?: string | null;
     episode_id?: string | null;
     terminal_state?: TerminalState | null;
+    /** Closed vocabulary; anything else (including absent) records `unknown`. */
+    surface?: Surface | null;
     return_ref?: string | null;
     verification_ref?: string | null;
     consumption?: Consumption | null;
@@ -1057,6 +1074,10 @@ export function recordEvent(h: JournalHandle, input: RecordEventInput): JournalE
         worktree_id,
         at,
         capability: input.capability,
+        // Tolerant by design: a surface this build cannot place is `unknown`,
+        // never a throw. The field answers "which surface" and must not be able
+        // to fail a write that would otherwise have succeeded.
+        surface: readSurface(input.surface),
         terminal_state: input.terminal_state ?? null,
         return_ref: requireRef('return_ref', input.return_ref),
         verification_ref: requireRef('verification_ref', input.verification_ref),
@@ -1070,9 +1091,9 @@ export function recordEvent(h: JournalHandle, input: RecordEventInput): JournalE
             `INSERT INTO journal_event
              (event, episode_id, session_id, task_id, prompt_id, boundary_status,
               boundary_rule_version, repository_id, worktree_id, at, capability,
-              terminal_state, return_ref, verification_ref, consumption, retain_until,
-              amends_seq)
-             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+              surface, terminal_state, return_ref, verification_ref, consumption,
+              retain_until, amends_seq)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
         )
         .run(
             row.event,
@@ -1086,6 +1107,7 @@ export function recordEvent(h: JournalHandle, input: RecordEventInput): JournalE
             row.worktree_id,
             row.at,
             row.capability,
+            row.surface,
             row.terminal_state,
             row.return_ref,
             row.verification_ref,
@@ -1111,6 +1133,7 @@ function toEvent(r: Record<string, unknown>): JournalEvent {
         worktree_id: String(r['worktree_id']),
         at: String(r['at']),
         capability: String(r['capability']),
+        surface: readSurface(r['surface']),
         // Tolerant, not a cast: a value this build cannot place reads as null.
         terminal_state: readRunTerminalState(r['terminal_state']),
         return_ref: (r['return_ref'] as string | null) ?? null,

package/src/scripts/_lib/runtime_wiring_checks.ts

@@ -28,6 +28,10 @@ import process from 'node:process';
 import { parse as parseYaml } from 'yaml';
 
 import { inheritedGitOverrides } from './repo_root.js';
+import {
+    checkHostPermissionSettings,
+    defaultHostPermissionDeps,
+} from './host_permission_checks.js';
 
 /** The verdict shape `cmd_doctor` renders. Mirrors its internal `Dict` rows. */
 export interface WiringCheck {
@@ -291,7 +295,7 @@ export function checkInheritedGitEnv(env: NodeJS.ProcessEnv = process.env): Wiri
  * two spreads.
  */
 /** The four ids, in render order. Spread into `cmd_doctor`'s two id registries. */
-export const WIRING_CHECK_IDS = ['settings-resolution', 'router-artifact', 'hook-resolution', 'inherited-git-env', 'hooks-kill-switch'] as const;
+export const WIRING_CHECK_IDS = ['settings-resolution', 'router-artifact', 'hook-resolution', 'inherited-git-env', 'hooks-kill-switch', 'host-permission-settings'] as const;
 
 
 /**
@@ -333,6 +337,7 @@ export function checkHooksDisabled(env: NodeJS.ProcessEnv = process.env): Wiring
 
 export function wiringRunners(opts: {
     packageRoot: string;
+    projectRoot: string;
     iterOverrides: () => Iterable<[string, unknown, string]>;
 }): Record<string, () => WiringCheck> {
     return {
@@ -344,6 +349,12 @@ export function wiringRunners(opts: {
         'hook-resolution': () => checkHookResolution(opts.packageRoot).check,
         'inherited-git-env': () => checkInheritedGitEnv(),
         'hooks-kill-switch': () => checkHooksDisabled(),
+        // The host's own permission settings, which decide how often a call is
+        // confirmed. It lives with this family rather than its own because
+        // `checkHookWiring` below already reads the same `~/.claude/settings.json`
+        // for the same host — the question is the same surface, one key over.
+        'host-permission-settings': () =>
+            checkHostPermissionSettings(defaultHostPermissionDeps(opts.projectRoot)),
     };
 }
 

package/src/scripts/_lib/session_register.ts

@@ -175,14 +175,19 @@ export function stop_means_session_end(platform: string | null | undefined): boo
  * Deliberately **not** derived from the frequency lattice. That instrument
  * models *slot presence*, and two hosts have a slot that never fires:
  *
- * - `cursor` — `user_prompt_submit` and `stop` are **IDE-only**; the CLI fires
- *   only shell-execution hooks (`hook_manifest.yaml:365-366`,
- *   `chat-history-platform-hooks.md:214`). The lattice has no IDE/CLI dimension,
- *   so it reports cursor covered.
+ * - `cursor` — excluded because reachability there is UNESTABLISHED, not
+ *   because it is known absent. The earlier wording asserted the CLI fires only
+ *   shell-execution hooks, sourced to a 2026-01 reading that carried no expiry
+ *   and could not be re-verified in either direction. The safe direction is the
+ *   one taken: an unverified slot must not read as covered. The lattice has no
+ *   IDE/CLI dimension of its own, so it would report cursor covered; the
+ *   envelope now carries a `surface` field (`_lib/surface.ts`) that records
+ *   which surface a dispatch came from, and it answers `unknown` on cursor
+ *   because no marker distinguishes the two.
  * - `cowork` — slots are structurally wired but lifecycle events do not fire
  *   (`hook_manifest.yaml:346-351`).
- * - `copilot` — no hook surface at all (`hook_manifest.yaml:428-429`), excluded
- *   from the join by declaration.
+ * - `copilot` — nothing bound by this package (`fallback_only: true` in the
+ *   manifest), excluded from the join by declaration.
  *
  * A session on an excluded host still *registers* if a `session_start` reaches
  * it, and simply stops being visible after its TTL. It is never reported as

package/src/scripts/_lib/sqlite_schema.ts

@@ -0,0 +1,22 @@
+/**
+ * Schema helpers for the `node:sqlite` stores in this tree.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+
+/**
+ * Add a column to an existing table when it is absent.
+ *
+ * `CREATE TABLE IF NOT EXISTS` is a no-op on a database that predates a
+ * column, so a store created by an earlier build needs the explicit add or the
+ * field is silently missing from every read.
+ *
+ * `PRAGMA table_info` rather than a catch around `ALTER TABLE`: swallowing the
+ * error would also swallow a genuine schema failure, and a store that silently
+ * fails to migrate reads exactly like one that never needed to.
+ */
+export function addColumnIfMissing(db: DatabaseSync, table: string, column: string, decl: string): void {
+    const cols = db.prepare(`PRAGMA table_info(${table})`).all() as { name: string }[];
+    if (cols.length === 0) return;
+    if (cols.some((c) => c.name === column)) return;
+    db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${decl}`);
+}

package/src/scripts/_lib/surface.ts

@@ -0,0 +1,86 @@
+/**
+ * surface — the IDE / CLI / cloud dimension of a dispatch, as an ENVELOPE
+ * field rather than a platform key.
+ *
+ * WHY A FIELD AND NOT A PLATFORM. `_lib/session_register.ts` records that the
+ * capability lattice has no IDE/CLI dimension, which is why it reports cursor
+ * covered whether or not its per-turn slots fire there. Splitting `cursor`
+ * into `cursor-ide` / `cursor-cli` would change `--platform`, the eight
+ * platform identifiers, and every manifest row keyed on them. A field changes
+ * none of those and is still the thing `host_lowering.yaml`'s `(host, surface,
+ * slot)` key needs.
+ *
+ * WHAT THIS CAN AND CANNOT DECIDE — the honest half.
+ *
+ * `unknown` is the default and, today, very nearly the only answer. Nothing in
+ * this tree distinguishes an IDE session from a CLI one on any host: no host
+ * payload observed here carries such a marker, and inferring it from a TTY or
+ * a terminal name would be a guess wearing a function's authority — the exact
+ * move the surrounding roadmap exists to remove. So there is no `ide` or `cli`
+ * branch. When a host is observed to send a distinguishing marker, it is added
+ * to {@link CLOUD_PAYLOAD_MARKERS}'s sibling with a dated citation, and the
+ * branch arrives with the evidence rather than ahead of it.
+ *
+ * The `cloud` branch is a DECLARED VOCABULARY, not an observation. This package
+ * will honour these payload keys if a host sends one; none has been observed
+ * sending one. That distinction is the point: the mechanism is real and tested,
+ * the host claim is absent and says so.
+ */
+
+/** The closed surface vocabulary. `unknown` is the safe default. */
+export const SURFACES = ['ide', 'cli', 'cloud', 'unknown'] as const;
+export type Surface = (typeof SURFACES)[number];
+
+/**
+ * Payload keys whose truthy presence declares a background / cloud agent.
+ *
+ * Declared, not observed — see the module header. Kept as a list so a host that
+ * starts sending one needs no code change, only a citation in this comment.
+ */
+export const CLOUD_PAYLOAD_MARKERS: readonly string[] = [
+    'background_agent',
+    'is_background',
+    'isBackgroundAgent',
+];
+
+/** Explicit override, for a caller that already knows the surface. */
+export const SURFACE_ENV_VAR = 'AGENT_CONFIG_SURFACE';
+
+function _isSurface(v: unknown): v is Surface {
+    return typeof v === 'string' && (SURFACES as readonly string[]).includes(v);
+}
+
+/**
+ * Resolve the surface for one dispatch.
+ *
+ * Precedence: an explicit environment override, then a declared payload
+ * marker, then `unknown`. An unrecognised override value is ignored rather
+ * than trusted — a typo must not become a capability claim.
+ */
+export function detectSurface(
+    payload: unknown,
+    env: Record<string, string | undefined> = process.env,
+): Surface {
+    const override = env[SURFACE_ENV_VAR];
+    if (_isSurface(override)) return override;
+
+    if (typeof payload === 'object' && payload !== null && !Array.isArray(payload)) {
+        const obj = payload as Record<string, unknown>;
+        for (const key of CLOUD_PAYLOAD_MARKERS) {
+            if (obj[key]) return 'cloud';
+        }
+    }
+    return 'unknown';
+}
+
+/**
+ * Read a persisted or caller-supplied surface value.
+ *
+ * Tolerant, not a cast: an unrecognised value — a row written by a newer build,
+ * a typo, an absent field — reads as `unknown`. Same posture as
+ * `readRunTerminalState`, and for the same reason: a value this build cannot
+ * place must not fail a write or a read.
+ */
+export function readSurface(v: unknown): Surface {
+    return _isSurface(v) ? v : 'unknown';
+}