@event4u/agent-config 9.33.0 → 9.35.0

package/docs/guidelines/agent-infra/failure-signatures.md

@@ -12,18 +12,53 @@ probability cause.
 
 ## Lookup
 
-| Signature (what you see) | Likely cause | First check |
-|---|---|---|
-| **Tool/agent loop** — same tool called >2× with near-identical args, no progress | Missing stop condition; reading without acting; ambiguous state | Stop. State the hypothesis in one line. Act or ask — do not re-read. (`context-hygiene` 15/25 rule) |
-| **HTTP 429 / "rate limit" / "quota"** | Too-frequent calls; shared quota; missing backoff | Inspect response headers (`Retry-After`, `X-RateLimit-*`); add exponential backoff; check if a loop is firing the calls |
-| **`ECONNREFUSED` / connection refused** | Service not up; wrong host/port; container not started | Is the service running? (`docker compose ps`, health endpoint); is the port right? (`lsof -i :PORT`); is it bound to `127.0.0.1` vs `0.0.0.0`? |
-| **`ENOENT` / "no such file or directory"** | Wrong cwd; path relative vs absolute; file not generated yet | Print the *resolved absolute* path; check cwd; confirm a prior step actually wrote the file |
-| **Timeout / hang** | Blocking I/O; deadlock; awaiting a condition that never holds | What is it waiting on? Add a log right before the blocking call; bound the wait; check for a missing `await`/`return` |
-| **`OOM` / killed (137) / heap out of memory** | Unbounded collection; loading all rows; leak in a loop | What grows per iteration? Stream/paginate instead of loading all; check `--max-old-space-size` only after finding the growth |
-| **`EACCES` / permission denied** | Wrong file mode; running as wrong user; read-only mount | `ls -l` the target; check the process user; is the path a read-only volume? |
-| **Flaky test (passes alone, fails in suite)** | Shared state; order dependence; real clock/random; unawaited async | Run the test in isolation vs in suite; look for shared fixtures, global state, `Date.now()`/random, missing `await` |
-| **Works locally, fails in CI** | Env/config drift; missing service; absent secret; path/case sensitivity | Diff env (`printenv`); is the service/secret present in CI? Linux is case-sensitive — check filename casing |
-| **Intermittent / "sometimes"** | Race; timing; network; non-deterministic order | Reproduce with condition-based waiting, not fixed sleeps (`systematic-debugging` § Condition-based waiting); log timestamps |
+| ID | Signature (what you see) | Likely cause | First check |
+|---|---|---|---|
+| `tool-loop` | **Tool/agent loop** — same tool called >2× with near-identical args, no progress | Missing stop condition; reading without acting; ambiguous state | Stop. State the hypothesis in one line. Act or ask — do not re-read. (`context-hygiene` 15/25 rule) |
+| `rate-limited` | **HTTP 429 / "rate limit" / "quota"** | Too-frequent calls; shared quota; missing backoff | Inspect response headers (`Retry-After`, `X-RateLimit-*`); add exponential backoff; check if a loop is firing the calls |
+| `connection-refused` | **`ECONNREFUSED` / connection refused** | Service not up; wrong host/port; container not started | Is the service running? (`docker compose ps`, health endpoint); is the port right? (`lsof -i :PORT`); is it bound to `127.0.0.1` vs `0.0.0.0`? |
+| `path-not-found` | **`ENOENT` / "no such file or directory"** | Wrong cwd; path relative vs absolute; file not generated yet | Print the *resolved absolute* path; check cwd; confirm a prior step actually wrote the file |
+| `hang` | **Timeout / hang** | Blocking I/O; deadlock; awaiting a condition that never holds | What is it waiting on? Add a log right before the blocking call; bound the wait; check for a missing `await`/`return` |
+| `out-of-memory` | **`OOM` / killed (137) / heap out of memory** | Unbounded collection; loading all rows; leak in a loop | What grows per iteration? Stream/paginate instead of loading all; check `--max-old-space-size` only after finding the growth |
+| `permission-denied` | **`EACCES` / permission denied** | Wrong file mode; running as wrong user; read-only mount | `ls -l` the target; check the process user; is the path a read-only volume? |
+| `order-dependent-test` | **Flaky test (passes alone, fails in suite)** | Shared state; order dependence; real clock/random; unawaited async | Run the test in isolation vs in suite; look for shared fixtures, global state, `Date.now()`/random, missing `await` |
+| `local-ci-drift` | **Works locally, fails in CI** | Env/config drift; missing service; absent secret; path/case sensitivity | Diff env (`printenv`); is the service/secret present in CI? Linux is case-sensitive — check filename casing |
+| `race` | **Intermittent / "sometimes"** | Race; timing; network; non-deterministic order | Reproduce with condition-based waiting, not fixed sleeps (`systematic-debugging` § Condition-based waiting); log timestamps |
+| `stale-capability-claim` | **Budget exhausted plus repeated attempts at a tool that is not available** | A capability the session claimed for itself instead of resolving — the council, a hook slot, a subagent primitive, an MCP server assumed present | Ask the live verb, not the tree: `agent-config hooks:status` for slot bindings, `agent-config routing:doctor` for per-field capability **provenance** (`registry` / `live-probe` / `default`), `agent-config council:status` for council availability. A `false` from `default` records that nobody answered, not that the host cannot |
+
+### Naming convention for IDs
+
+An id is a short kebab handle so a signature can be **cited by name** — the
+first column was prose, so nothing could reference a row.
+
+One rule governs new ids: **where a row's signature is a stable string the
+tooling already prints, the id is that string verbatim** rather than a kebab
+synonym. `skill_linter.ts` emits a closed set of `Issue` codes —
+`missing_section`, `missing_conditional_section`, `invalid_execution_handler` —
+and a row about one of those is looked up by the code the reader just saw in the
+output. No current row is of that class; the convention is stated for the next
+one, so the table does not accumulate two names for the same failure.
+
+## Discrimination drills
+
+A row's "first check" is only worth following if the documented signature is what
+actually appears. Each drill breaks the named layer and asserts the documented
+symptom — run it once when you doubt a row, or when adding one. They are text a
+human runs; nothing here is a CI gate.
+
+| ID | Drill — break this, expect that |
+|---|---|
+| `tool-loop` | Ask for a fact that is genuinely absent from the tree (a config key nothing defines). Expect repeated searches with shrinking variation and no edit — that shape, not an error message, is the signature. |
+| `rate-limited` | Fire the provider's own rate limit with a tight loop against a cheap endpoint. Expect `429` **plus** `Retry-After`; a `429` with no such header is a different failure (a gateway, not the API). |
+| `connection-refused` | Stop the service and call it (`docker compose stop <svc>`). Expect `ECONNREFUSED` immediately. If it hangs instead, the host resolves but nothing listens — that is `hang`, not this row. |
+| `path-not-found` | Run a path-taking script from a different cwd. Expect `ENOENT` naming a path that is *almost* right — the near-miss is the tell that the path is relative, not missing. |
+| `hang` | `await` a promise nothing resolves. Expect no output and no exit, distinguishable from `race` by being 100% reproducible. |
+| `out-of-memory` | Accumulate rows in an array inside a loop over a large fixture. Expect the heap message and exit 137 — and note that the reported line is where allocation failed, not where the growth is. |
+| `permission-denied` | `chmod 000` a fixture and read it. Expect `EACCES`, not `ENOENT` — confusing the two sends you looking for a missing file that is right there. |
+| `order-dependent-test` | Add a module-level mutable to two tests in one file. Expect green alone, red in suite. Reversing the file order should move the failure — if it does not, the cause is shared *external* state, not order. |
+| `local-ci-drift` | Rename a fixture's casing (`Foo.ts` → `foo.ts`) and import the old name. Expect green on macOS, red on Linux CI. The generalisation: anything the local filesystem is lenient about. |
+| `race` | Replace a condition-based wait with a fixed `sleep` shorter than the operation. Expect intermittent failure whose rate moves with machine load — load-sensitivity is what separates this from `order-dependent-test`. |
+| `stale-capability-claim` | Assert a capability without asking for it, then compare against the live verb. `agent-config routing:doctor` prints provenance per field; a field whose provenance is `default` was never established by anything — which is exactly the state a confident self-claim is indistinguishable from. |
 
 ## How to use
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "9.33.0",
+    "version": "9.35.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including \"zero runtime daemon\".",
     "license": "MIT",
     "private": false,
@@ -77,7 +77,7 @@
         "build:mcp-catalog": "./scripts-run src/scripts/build_mcp_catalog --write --strict",
         "build": "npm run build:cli && npm run build:install-bundle && npm run build:hooks && npm run build:mcp-bundle && npm run build:cli-delegate && npm run build:ui",
         "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.scripts.json",
-        "lint:ts": "eslint 'src/**/*.ts'",
+        "lint:ts": "eslint --cache 'src/**/*.ts'",
         "test:ts": "vitest run",
         "lint:publint": "publint",
         "prepack": "npm run build && npm run build:discovery && npm run build:mcp-manifest && node src/scripts/prepack-check.mjs",

package/src/agent-src/scripts/archive_completed_roadmaps.ts

@@ -128,12 +128,42 @@ function _branch_touched_paths(root: string, base: string): Set<string> | null {
     return out;
 }
 
+/**
+ * Paths where a repo-relative path is DATA, not a live reference — so
+ * rewriting it falsifies a record instead of keeping a link resolvable.
+ *
+ * Two classes, and the second is why this predicate exists at all:
+ *
+ * - `agents/evidence/**` — a committed record of what was true, or of what a
+ *   reviewer was shown, at one point in time. Retroactively editing it makes it
+ *   claim something that did not happen, which is the failure
+ *   `evaluator-independence` exists to prevent ("the prompt ships with the
+ *   verdict" is worthless if a later sweep can edit the prompt).
+ * - `*.patch` anywhere — a patch's `diff --git a/… b/…` and `+++ b/…` lines are
+ *   the payload. Rewriting them detaches the patch from the commit it records
+ *   AND makes `git apply` target a path the diff never created.
+ *
+ * Measured 2026-08-11: archiving one roadmap rewrote four frozen artefacts
+ * under `agents/evidence/reviews/`, including the `diff.patch` headers of a
+ * recorded review input. Nothing caught it — the sweep reported it as
+ * "4 ref(s) migrated", which reads like success.
+ */
+const _FROZEN_RECORD_PREFIXES: readonly string[] = ['agents/evidence/'];
+
+/** Is `rel` a frozen record whose path strings must not be rewritten? */
+export function _is_frozen_record(rel: string): boolean {
+    const norm = rel.split(path.sep).join('/');
+    return _FROZEN_RECORD_PREFIXES.some((p) => norm.startsWith(p)) || norm.endsWith('.patch');
+}
+
 /**
  * Rewrite full-path references `old_rel` → `new_rel` in tracked files.
  *
  * Only the exact repo-relative path is rewritten (bare-filename mentions are
  * left alone). The archived file's own path never matches because the search
- * string is the un-archived path.
+ * string is the un-archived path. Frozen records are skipped — see
+ * `_is_frozen_record`; a link left dangling in a historical record is correct,
+ * because the record describes a tree that no longer exists.
  */
 function _inbound_ref_rewrite(
     root: string,
@@ -165,6 +195,10 @@ function _inbound_ref_rewrite(
             // skip the roadmap file itself
             continue;
         }
+        if (_is_frozen_record(rel)) {
+            // A record of a past state — rewriting it falsifies the record.
+            continue;
+        }
         const fp = path.join(root, rel);
         let text: string;
         try {

package/src/agent-src/scripts/roadmap_gates.ts

@@ -46,6 +46,13 @@
  *   ./agent-config gates --all      # every open blocker, grouped by owner
  *   ./agent-config gates --json     # machine-readable
  *   ./agent-config gates --reply    # reply-close form; empty when none
+ *   ./agent-config gates --pending  # staged actions awaiting confirmation
+ *
+ * `--pending` reads a different source — the staged-confirmation store, not the
+ * roadmap tree — and stays out of `--reply` on purpose. ADR-222 fixes the
+ * reply-close form at exactly ONE decision rendered in full; folding a second
+ * source into it would silently change which decision "the one" is, and that
+ * contract is not this step's to move.
  */
 
 import * as path from 'node:path';
@@ -58,6 +65,8 @@ import {
     blocker_needs_user as needsUser,
     type Blocker,
 } from './update_roadmap_progress.js';
+import { listPending } from '../templates/scripts/work_engine/hooks/builtin/staged_confirmation_store.js';
+import type { StagedAction } from '../templates/scripts/work_engine/hooks/builtin/staged_confirmation.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
@@ -327,6 +336,89 @@ function renderJson(entries: readonly Entry[], all: boolean): string {
     );
 }
 
+/**
+ * `--pending`: staged actions awaiting a human confirmation.
+ *
+ * A second source under the same verb, and the reason it belongs here rather
+ * than in a new command is the verb's own definition — "open decisions that
+ * need you, as actions". A staged irreversible action IS one, and the most
+ * literal kind: the roadmap blockers above are decisions a human owes a plan,
+ * this is a decision a human owes an action that is already loaded and waiting.
+ *
+ * Expired stages are counted, never listed as actionable. An expired stage
+ * cannot execute (`stageStatus` derives that from the clock, not from a sweep
+ * having run), so rendering it beside a live one would put two rows in front of
+ * the reader where only one is a decision.
+ */
+function renderPending(root: string, now: number): string {
+    const rows = listPending(root, now);
+    const live = rows.filter((r) => r.status === 'pending');
+    const expired = rows.filter((r) => r.status === 'expired');
+    const lines: string[] = [];
+
+    if (live.length === 0) {
+        lines.push(
+            expired.length === 0
+                ? 'No staged actions awaiting confirmation.'
+                : `Nothing awaits your confirmation. ${expired.length} stage` +
+                      `${expired.length !== 1 ? 's' : ''} expired unconfirmed — the action never fired.`,
+        );
+        return lines.join('\n') + '\n';
+    }
+
+    lines.push(
+        `${live.length} staged action${live.length !== 1 ? 's' : ''} await` +
+            `${live.length === 1 ? 's' : ''} your confirmation` +
+            (expired.length > 0 ? ` · ${expired.length} expired unconfirmed` : ''),
+    );
+    let n = 0;
+    for (const { stage } of live) {
+        n += 1;
+        lines.push(...renderStage(stage, n));
+    }
+    lines.push('');
+    return lines.join('\n') + '\n';
+}
+
+function renderStage(stage: StagedAction, index: number): string[] {
+    const head = `${index} · ${stage.action}`;
+    const tail = `token: ${stage.token}`;
+    const dashes = Math.max(3, WIDTH - head.length - tail.length - 6);
+    return [
+        '',
+        `── ${head} ${'─'.repeat(dashes)} ${tail}`.trimEnd(),
+        // The object is the first field on purpose: an approval that does not
+        // name the exact object is the thing non-destructive-by-default forbids,
+        // so it is what the reader must see before anything else.
+        ...field('Object:', stage.object),
+        ...field('Staged by:', stage.source),
+        ...field('Expires:', stage.expires_at),
+    ];
+}
+
+function renderPendingJson(root: string, now: number): string {
+    const rows = listPending(root, now);
+    return (
+        JSON.stringify(
+            {
+                awaitingYou: rows.filter((r) => r.status === 'pending').length,
+                expired: rows.filter((r) => r.status === 'expired').length,
+                staged: rows.map(({ stage, status }) => ({
+                    token: stage.token,
+                    action: stage.action,
+                    object: stage.object,
+                    source: stage.source,
+                    stagedAt: stage.staged_at,
+                    expiresAt: stage.expires_at,
+                    status,
+                })),
+            },
+            null,
+            2,
+        ) + '\n'
+    );
+}
+
 function _isDir(p: string): boolean {
     try {
         return fs.statSync(p).isDirectory();
@@ -340,8 +432,8 @@ function _isDir(p: string): boolean {
  * `agents/roadmaps`, otherwise fall back to the git toplevel (monorepo
  * sub-project support).
  */
-function _resolveRepoRoot(start: string): string {
-    if (_isDir(path.join(start, 'agents', 'roadmaps'))) {
+function _resolveRepoRoot(start: string, marker = path.join('agents', 'roadmaps')): string {
+    if (_isDir(path.join(start, marker))) {
         return start;
     }
     try {
@@ -351,7 +443,7 @@ function _resolveRepoRoot(start: string): string {
             timeout: 10_000,
         });
         const top = (r.stdout || '').trim();
-        if (r.status === 0 && top !== '' && _isDir(path.join(top, 'agents', 'roadmaps'))) {
+        if (r.status === 0 && top !== '' && _isDir(path.join(top, marker))) {
             return top;
         }
     } catch {
@@ -365,6 +457,18 @@ function main(argv?: readonly string[]): number {
     const all = args.includes('--all');
     const json = args.includes('--json');
     const reply = args.includes('--reply');
+    const pending = args.includes('--pending');
+
+    // `--pending` resolves against `agents/runtime/`, not `agents/roadmaps/`,
+    // and is answered BEFORE the roadmaps-directory exit below: a staged action
+    // is independent of whether this project plans in roadmaps at all, so
+    // "no roadmaps here" is not an answer to "what awaits my confirmation".
+    if (pending) {
+        const root = _resolveRepoRoot(process.cwd(), path.join('agents', 'runtime'));
+        const now = Date.now();
+        process.stdout.write(json ? renderPendingJson(root, now) : renderPending(root, now));
+        return 0;
+    }
 
     const repoRoot = _resolveRepoRoot(process.cwd());
     const roadmapRoot = path.join(repoRoot, 'agents', 'roadmaps');
@@ -412,5 +516,16 @@ if (_isCliEntry()) {
     process.exitCode = main();
 }
 
-export { main, needsUser, regroupTodo, wrap, collectEntries, render, renderJson, renderReply };
+export {
+    main,
+    needsUser,
+    regroupTodo,
+    wrap,
+    collectEntries,
+    render,
+    renderJson,
+    renderReply,
+    renderPending,
+    renderPendingJson,
+};
 export type { Entry };

package/src/agent-src/templates/scripts/memory_lookup.ts

@@ -388,8 +388,7 @@ function* _iter_knowledge_entries(): Generator<[string, Record<string, unknown>]
 /**
  * Naive relevance score: max over keys of (glob-match | substring).
  *
- * Good enough for the `absent` path where retrieval is best-effort.
- * The `present` path returns a real score from agent-memory.
+ * Retrieval is best-effort by design — this is the only scoring path.
  */
 export function _score(entry: Record<string, unknown>, keys: string[]): number {
     if (keys.length === 0) {

package/src/agent-src/templates/scripts/memory_signal.ts

@@ -214,10 +214,8 @@ export interface SignalRecord {
 /**
  * Append a signal entry. Returns the written record, or null when skipped.
  *
- * On `present` backend, routing to the package is a no-op here today —
- * the package adapter is wired in `road-to-agent-memory-integration.md`
- * Phase 3. For now, the file path is the single source of truth so
- * merge-safety is preserved in every mode.
+ * The file path is the single source of truth: there is no external backend
+ * to route to, so merge-safety holds in every mode.
  */
 export function emit(
     entry_type: string,

package/src/agent-src/templates/scripts/work_engine/hooks/builtin/decision_gate.ts

@@ -41,6 +41,22 @@ type Any = unknown;
 
 const _BLOCK_REASON_PREFIX = 'decision_gate';
 
+/**
+ * Stage an action for confirmation and return the surface lines that name it.
+ *
+ * An injected collaborator rather than a direct import of
+ * `staged_confirmation_store.js`, for two reasons. The gate is called from a
+ * hook bus with no repo root and no clock of its own, and — the load-bearing
+ * one — an absent stager keeps the `ask` path byte-identical to what ships
+ * today. The confirmation primitive is deliberately UNBOUND until blocker
+ * `confirmation-degraded-host-semantics` is decided (5 of 8 hosts have no
+ * `pre_tool_use` slot), so reaching it has to be an explicit opt-in and not a
+ * behaviour change that arrives with an upgrade.
+ */
+export interface ConfirmationStager {
+    stage(input: { action: string; object: string; source: string }): readonly string[];
+}
+
 /**
  * Evaluate decision-engine gates on every `AFTER_STEP`.
  *
@@ -49,9 +65,11 @@ const _BLOCK_REASON_PREFIX = 'decision_gate';
  */
 export class DecisionGateHook {
     private readonly _settings: DecisionEngineSettings;
+    private readonly _stager: ConfirmationStager | null;
 
-    constructor(settings: DecisionEngineSettings) {
+    constructor(settings: DecisionEngineSettings, stager: ConfirmationStager | null = null) {
         this._settings = settings;
+        this._stager = stager;
     }
 
     /** Register the gate callback on `AFTER_STEP`. */
@@ -109,10 +127,22 @@ export class DecisionGateHook {
                 DecisionGateHook._surface(decision, 'ask_timeout'),
             );
         }
-        throw new HookHalt(
-            `${_BLOCK_REASON_PREFIX}:${decision.gate_id}`,
-            DecisionGateHook._surface(decision),
-        );
+        // `stop` and `ask` share this exit: both halt, which is the policy —
+        // ask and action are strictly sequential, so an interactive gate does
+        // not act while it asks. What `ask` adds, and only when a stager is
+        // injected, is a token on the surface so the answer can be matched to
+        // THIS question and consumed exactly once. The halt reason is
+        // deliberately unchanged: it is the identity downstream readers match on.
+        let surface = DecisionGateHook._surface(decision);
+        if (action === 'ask' && this._stager !== null) {
+            const extra = this._stager.stage({
+                action: `work_engine:advance:${decision.gate_id}`,
+                object: `phase ${decision.phase}`,
+                source: _BLOCK_REASON_PREFIX,
+            });
+            surface = [...surface, '', ...extra];
+        }
+        throw new HookHalt(`${_BLOCK_REASON_PREFIX}:${decision.gate_id}`, surface);
     }
 
     // -- formatting helpers -------------------------------------------

package/src/agent-src/templates/scripts/work_engine/hooks/builtin/staged_confirmation.ts

@@ -0,0 +1,252 @@
+/**
+ * Staged confirmation — the pure half of exactly-once confirmed execution.
+ *
+ * `src/rules/non-destructive-by-default.md` already carries the whole policy:
+ * an irreversible action is confirmed on THIS turn, ask and action are strictly
+ * sequential ("Never act while asking"), and the approval names the exact
+ * object. What the tree had no mechanism for is the *sequencing itself* — a
+ * staged action, a confirmation that matches it, and the guarantee that a
+ * second approval of the same stage does not fire the action twice.
+ *
+ * Two properties carry that guarantee, and they are split across two files on
+ * purpose:
+ *
+ *   - **Identity is derived, not invented.** {@link stageAction} hashes the
+ *     action, the exact object, and a caller-supplied nonce into a token, so a
+ *     confirmation can only match the stage it was issued for. Restaging the
+ *     same object under a fresh nonce yields a different token — an approval
+ *     never carries over to "the next one like it".
+ *   - **The claim is atomic, and it lives in the store.** Nothing here can be
+ *     exactly-once by itself: two processes reading the same `pending` record
+ *     and both deciding "execute" is a check-then-act race no pure function can
+ *     close. This module decides WHAT the outcome should be;
+ *     `staged_confirmation_store.ts` makes the transition atomic with a
+ *     directory rename, which either succeeds once or fails.
+ *
+ * Nothing binds on this yet, deliberately. `pre_tool_use` exists on 3 of 8
+ * platform rows (`hook_manifest.yaml`), so a guard that claimed to enforce
+ * confirmation would be prose on the other five while reading like a control —
+ * the failure `src/rules/ui-audit-gate.md` names about its own scope. The
+ * decision is deferred behind blocker `confirmation-degraded-host-semantics`;
+ * until it lands, callers opt in explicitly.
+ *
+ * Pure: no filesystem, no clock, no randomness. `now` and `nonce` are
+ * parameters so a test pins a whole lifecycle without faking globals.
+ */
+
+import { createHash } from 'node:crypto';
+
+/**
+ * Lifecycle of one staged action. `expired` is not a stored state — it is
+ * derived from the clock by {@link stageStatus}, so a stale pending record
+ * cannot read as awaiting-approval merely because nobody swept it.
+ */
+export type StageState = 'pending' | 'confirmed' | 'declined';
+
+/** What {@link confirmOnce} concluded. Only `execute` authorizes the action. */
+export type ConfirmOutcome =
+    | 'execute'
+    | 'already-confirmed'
+    | 'expired'
+    | 'declined'
+    | 'token-mismatch';
+
+/**
+ * The `on_block_fallback` vocabulary from
+ * `work_engine/scoring/decision_engine.ts` (`stop` / `warn`, default `stop`),
+ * reused rather than re-invented: this module extends that gate's ask path, so
+ * a second fallback vocabulary would be a second contract to keep in sync.
+ */
+export type NonInteractiveFallback = 'stop' | 'warn';
+
+/**
+ * Default staging window. A confirmation the user never gives must not sit in
+ * the store as an approval waiting to be collected: an abandoned stage that
+ * stays valid indefinitely is a pre-approved irreversible action, which is the
+ * opposite of what the policy asks for. Fifteen minutes is long enough for a
+ * human to read the surface and answer, short enough that a turn which ended
+ * hours ago cannot authorize anything.
+ */
+export const STAGE_TTL_MS = 15 * 60 * 1000;
+
+export interface StagedAction {
+    /** Confirmation token — derived, never guessable from the object alone. */
+    readonly token: string;
+    /** What would fire: a command name, a skill slug, a concern id. */
+    readonly action: string;
+    /**
+     * The exact object the approval names — a path, a URL, a recipient, an
+     * amount. The policy's "names the exact object" clause lives here, which is
+     * why it is required rather than optional: a stage with no object is a
+     * category confirmation, and the rule forbids exactly that.
+     */
+    readonly object: string;
+    /** Who staged it — the surface a `gates --pending` reader needs. */
+    readonly source: string;
+    readonly staged_at: string;
+    readonly expires_at: string;
+    readonly state: StageState;
+    /** Set on the transition out of `pending`, never rewritten afterwards. */
+    readonly resolved_at?: string;
+}
+
+/** ISO-8601 seconds, matching the runtime records already in the tree. */
+function iso(ms: number): string {
+    return new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+/**
+ * Derive the confirmation token.
+ *
+ * The nonce is a parameter and not read from a clock or an RNG here, so the
+ * derivation is reproducible in a test. It is also what makes two stages of the
+ * same object distinct: without it, approving a delete of `x` once would
+ * produce a token that matches every future delete of `x`.
+ *
+ * The separator is NUL, written as an escape sequence and never as a raw byte.
+ * NUL is the right separator — it cannot occur in an action, a path or a nonce,
+ * so no two different triples concatenate to the same string. A RAW NUL in a
+ * text source would make git, grep and file(1) treat the whole file as binary
+ * and skip it silently, which `lint_hidden_unicode` blocks on; the escape keeps
+ * the domain separation and leaves the file readable by every tool.
+ */
+export function deriveToken(action: string, object: string, nonce: string): string {
+    return createHash('sha256')
+        .update(`${action}\u0000${object}\u0000${nonce}`)
+        .digest('hex')
+        .slice(0, 16);
+}
+
+/** Stage an action. Returns the record; it is the caller's job to persist it. */
+export function stageAction(args: {
+    action: string;
+    object: string;
+    source: string;
+    nonce: string;
+    now: number;
+    ttlMs?: number;
+}): StagedAction {
+    const ttl = args.ttlMs ?? STAGE_TTL_MS;
+    return {
+        token: deriveToken(args.action, args.object, args.nonce),
+        action: args.action,
+        object: args.object,
+        source: args.source,
+        staged_at: iso(args.now),
+        expires_at: iso(args.now + ttl),
+        state: 'pending',
+    };
+}
+
+/**
+ * Effective status at `now` — `expired` is derived, not stored.
+ *
+ * A pending record past its `expires_at` reads as `expired` even though no
+ * sweep has run, so the guarantee does not depend on a pruner having been
+ * called. Prune is housekeeping; this is the decision.
+ */
+export function stageStatus(stage: StagedAction, now: number): StageState | 'expired' {
+    if (stage.state === 'pending' && Date.parse(stage.expires_at) <= now) {
+        return 'expired';
+    }
+    return stage.state;
+}
+
+export function isExpired(stage: StagedAction, now: number): boolean {
+    return stageStatus(stage, now) === 'expired';
+}
+
+/**
+ * Decide what a confirmation attempt means. `execute` — and only `execute` —
+ * authorizes the action, and it is returned at most once per stage because the
+ * caller writes the returned record back before acting.
+ *
+ * The token is compared in full: a confirmation for a different stage is
+ * `token-mismatch` rather than a silent no-op, because a mismatch is a real
+ * signal (a stale surface, a copied token) and swallowing it would hide it.
+ */
+export function confirmOnce(
+    stage: StagedAction,
+    token: string,
+    now: number,
+): { outcome: ConfirmOutcome; stage: StagedAction } {
+    if (token !== stage.token) {
+        return { outcome: 'token-mismatch', stage };
+    }
+    const status = stageStatus(stage, now);
+    if (status === 'confirmed') {
+        return { outcome: 'already-confirmed', stage };
+    }
+    if (status === 'declined') {
+        return { outcome: 'declined', stage };
+    }
+    if (status === 'expired') {
+        return { outcome: 'expired', stage };
+    }
+    return {
+        outcome: 'execute',
+        stage: { ...stage, state: 'confirmed', resolved_at: iso(now) },
+    };
+}
+
+/** Decline a stage. Idempotent for the same reason `confirmOnce` is. */
+export function declineStage(
+    stage: StagedAction,
+    token: string,
+    now: number,
+): { declined: boolean; stage: StagedAction } {
+    if (token !== stage.token || stageStatus(stage, now) !== 'pending') {
+        return { declined: false, stage };
+    }
+    return { declined: true, stage: { ...stage, state: 'declined', resolved_at: iso(now) } };
+}
+
+/**
+ * What a non-interactive context does with a stage.
+ *
+ * Both fallbacks REFUSE — `decision_engine`'s `stop` and `warn` differ in how
+ * loudly they surface, never in whether the gated thing proceeds, and a staged
+ * irreversible action is the last place to invent an auto-approve. Naming the
+ * `warn` case explicitly is the point: a reader looking for the permissive
+ * branch finds it absent on purpose.
+ */
+export function nonInteractiveDecision(fallback: NonInteractiveFallback): {
+    execute: false;
+    surface: 'halt' | 'warn';
+} {
+    return { execute: false, surface: fallback === 'warn' ? 'warn' : 'halt' };
+}
+
+/**
+ * The confirmation surface, in the numbered-options shape
+ * `src/rules/user-interaction.md` requires. Returned as lines rather than
+ * written, so the same text serves a hook halt, a CLI pane, and a chat reply.
+ *
+ * `confirmWith` / `declineWith` are the caller's channel and are NOT defaulted
+ * to a command name. Which channel confirms a staged action is precisely what
+ * blocker `confirmation-degraded-host-semantics` has not decided — a
+ * `pre_tool_use` reply on three hosts, prose on the other five — and printing
+ * an invocation that does not exist yet would put a false instruction into a
+ * shipped surface. Until a binding caller supplies one, the surface names the
+ * token and says plainly that no channel is wired.
+ */
+export function confirmationSurface(
+    stage: StagedAction,
+    channel?: { confirmWith?: string; declineWith?: string },
+): string[] {
+    const confirm = channel?.confirmWith;
+    const decline = channel?.declineWith;
+    return [
+        `Confirmation required: ${stage.action}`,
+        `Object: ${stage.object}`,
+        `Staged by: ${stage.source} · token ${stage.token} · expires ${stage.expires_at}`,
+        confirm === undefined
+            ? `1) Confirm — quote token ${stage.token} back to the caller that staged it.`
+            : `1) Confirm — ${confirm}`,
+        decline === undefined
+            ? '2) Decline — say so; the stage is resolved without firing.'
+            : `2) Decline — ${decline}`,
+        '3) Do nothing — the stage expires and the action never fires.',
+        'Pending stages: `agent-config gates --pending`.',
+    ];
+}