@pugi/cli 0.1.0-beta.10 → 0.1.0-beta.100

package/dist/core/engine/native-pugi.js

@@ -1,25 +1,56 @@
 import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { resolve } from 'node:path';
-import { defaultEngineBudgets, runEngineLoop, } from '@pugi/sdk';
+import { AsyncEventQueue, EngineEventEmitter, modelSupportsThinking, runEngineLoop, splitThinkingBlocks, } from '@pugi/sdk';
 import { FileReadCache } from '../file-cache.js';
 import { loadSettings } from '../settings.js';
 import { openSession, recordToolCall, recordToolResult } from '../session.js';
+import { REGRESSION_DISPUTE_PHRASES } from './verification-patterns.js';
+import { prewarmRealDispatch } from '../subagents/dispatcher.js';
+import { resolveAutoCompactConfig, resolveBudget } from './budgets.js';
+import { maybeCompactAsync } from './auto-compact.js';
+import { writeAuditEvent } from '../audit/audit-trail.js';
+import { recordSessionNotes } from '../notes/notes-recorder.js';
 import { buildExecutor, buildToolsSchema } from './tool-bridge.js';
 import { personaSlugFor, systemPromptFor } from './prompts.js';
+import { CancellationToken } from '../repl/cancellation.js';
+import { fireTaskCompletedChain } from '../hook-chains.js';
+// β5a R5+R6 + P1 : per-turn `<context>` prefix + intent
+// classifier marker. Both pure functions, no fs cost at adapter init.
+// Per-dir markdown traverse fires once per `run()`; budget capped so
+// it never dominates the prompt budget.
+import { buildContextPrefix, spliceContextPrefix } from './context-prefix.js';
+import { applyIntentMarker, classifyIntent } from './intent.js';
+import { loadTraversedMarkdown } from '../context/markdown-traverse.js';
+import { isBareMode } from '../bare-mode/index.js';
+import { walkUpPugiMd } from '../pugi-md/walk-up.js';
+import { renderAmbientContext } from '../pugi-md/context-injector.js';
+// Backlog : `@import` + `paths:` glob loader.
+// Runs over each `HierarchyFile` the walker returns to expand imports
+// (capped + cycle-safe) and capture per-rule `paths:` frontmatter. The
+// loader is pure-fs so it cannot break the engine loop — any failure
+// degrades to "no expansion for this file" and the un-expanded walker
+// body is used as the rule body.
+import { loadRulesFile } from '../pugi-md/cc-compat-rules.js';
+import { homedir as osHomedir } from 'node:os';
+// L11 : per-session DenialTrackingState. One instance
+// per `run()` so denials cluster by (tool, args) within the same
+// command but do NOT leak across CLI invocations.
+import { DenialTrackingState } from '../denial-tracking/state.js';
 /**
  * Real `NativePugiEngineAdapter`. Drives the Pugi CLI's tool-use loop:
  *
- *   1. Pick a system prompt + persona based on the task kind
- *      (code/explain/fix/plan/build).
- *   2. Build an OpenAI-shaped tools schema from the local tool registry,
- *      gated by plan-mode (read-only).
- *   3. Open a workspace tool context (settings, session, read cache).
- *   4. Drive `runEngineLoop` against an `EngineLoopClient` until the
- *      model returns a final text answer or the per-command budget is
- *      exhausted.
- *   5. Surface every turn / tool call into both the engine event stream
- *      (consumer-visible status events) and the existing session log
- *      (`.pugi/events.jsonl`) so audit replay sees every step.
+ *  1. Pick a system prompt + persona based on the task kind
+ *     (code/explain/fix/plan/build).
+ *  2. Build an OpenAI-shaped tools schema from the local tool registry,
+ *     gated by plan-mode (read-only).
+ *  3. Open a workspace tool context (settings, session, read cache).
+ *  4. Drive `runEngineLoop` against an `EngineLoopClient` until the
+ *     model returns a final text answer or the per-command budget is
+ *     exhausted.
+ *  5. Surface every turn / tool call into both the engine event stream
+ *     (consumer-visible status events) and the existing session log
+ *     (`.pugi/events.jsonl`) so audit replay sees every step.
  *
  * The adapter is intentionally transport-agnostic. `client` is required
  * at construction; the CLI builds an `AnvilEngineLoopClient` from the
@@ -28,12 +59,12 @@ import { personaSlugFor, systemPromptFor } from './prompts.js';
  * up so unit tests can construct the adapter with an in-memory client.
  *
  * The engine task → loop mapping:
- *   - `task.kind === 'build_task'` is mapped to the `build` command.
- *   - `task.prompt` is the user message.
- *   - `task.workspaceRoot` pins the workspace root for tool execution.
- *   - `task.permissionMode` is read by the existing permission module;
- *     the adapter itself only enforces the plan-mode tool gate which is
- *     keyed on `kind`, not on permissionMode.
+ *  - `task.kind === 'build_task'` is mapped to the `build` command.
+ *  - `task.prompt` is the user message.
+ *  - `task.workspaceRoot` pins the workspace root for tool execution.
+ *  - `task.permissionMode` is read by the existing permission module;
+ *    the adapter itself only enforces the plan-mode tool gate which is
+ *    keyed on `kind`, not on permissionMode.
  */
 export class NativePugiEngineAdapter {
     options;
@@ -41,7 +72,7 @@ export class NativePugiEngineAdapter {
     /**
      * Per-adapter scratch map: links the loop's tool_call id to the
      * audit record id returned by `recordToolCall`. Code Reviewer P2
-     * retro 2026-05-23 moved this off the module scope — two adapters
+     * retro moved this off the module scope — two adapters
      * driven concurrently (cabinet UI + CLI on the same process) would
      * otherwise share the same Map and a fast turn from adapter A
      * could `.delete()` an entry that belonged to adapter B before its
@@ -50,8 +81,30 @@ export class NativePugiEngineAdapter {
      * to a single `run()` invocation.
      */
     engineToolCallIds = new Map();
+    /**
+     * β3 streaming additive: optional typed event emitter that mirrors
+     * every async-queue event so external consumers (admin-api SSE
+     * controller, future cabinet WebSocket relay) can attach without
+     * holding the async iterator. The CLI itself only consumes the
+     * `AsyncIterable<EngineEvent>` returned by `run()`; the emitter is
+     * a fan-out point for additional subscribers.
+     */
+    streamEmitter = new EngineEventEmitter();
     constructor(options) {
         this.options = options;
+        // β2a r1 (Backend Architect P1): kick off the real
+        // dispatcher's module import at adapter init so the first
+        // `agent` tool call does not pay 50-200ms cold-start. We fire
+        // the promise without awaiting — by the time the engine loop
+        // runs and the model issues an `agent` call, the import has
+        // resolved. The promise is swallowed because a failed prewarm
+        // would surface again at dispatch time with the real error.
+        void prewarmRealDispatch().catch(() => {
+            // Intentional no-op: the actual dispatch call will surface
+            // the import failure (if any) with the right call stack. A
+            // prewarm-time failure is just a missed optimization, not a
+            // correctness issue.
+        });
     }
     async capabilities() {
         return {
@@ -59,7 +112,13 @@ export class NativePugiEngineAdapter {
             supportsFileEdits: true,
             supportsShell: true,
             supportsLsp: false,
-            supportsSubagents: false,
+            // β2 S2 : real subagent dispatch shipped via the
+            // `agent` tool (apps/pugi-cli/src/tools/agent-tool.ts) plus the
+            // genuine `runEngineLoop`-backed dispatcher
+            // (apps/pugi-cli/src/core/subagents/dispatcher-real.ts). The
+            // capability flag flips after S1 + S3 + S4 land so cabinet UI +
+            // remote orchestrators can rely on the advertised contract.
+            supportsSubagents: true,
         };
     }
     async *run(task, ctx) {
@@ -67,235 +126,1077 @@ export class NativePugiEngineAdapter {
         const root = task.workspaceRoot;
         const session = this.options.session ?? openSession(root);
         const settings = loadSettings(root);
-        const toolCtx = {
-            root,
-            settings,
-            session,
-            readCache: new FileReadCache(),
-        };
-        const budget = task.budget?.tokens
-            ? {
-                maxTokens: task.budget.tokens,
-                // The task-level budget only carries tokens; tool calls keep
-                // the per-command default so a careless caller cannot disable
-                // the call-count guard by overriding usd/tokens.
-                maxToolCalls: defaultEngineBudgets[kind].maxToolCalls,
+        // P1 fix (deep audit): wire ctx.signal (AbortSignal) into
+        // a CancellationToken so the tool-bridge cancellation gate
+        // (`ctx.cancellation?.isAborted` check at tool-bridge.ts:656 +
+        // file-tools `gateOnCancellation` calls) fires when the operator
+        // aborts mid-tool. Before this fix `toolCtx` carried no cancellation
+        // field — only the next runEngineLoop iteration via `ctx.signal`
+        // aborted at the turn boundary, so a long-running tool (a sleeping
+        // bash command, a slow grep across the repo) could not be cancelled
+        // mid-call.
+        //
+        // The token is wired one-way: ctx.signal -> token. Aborting the
+        // token directly does NOT propagate back to the AbortSignal; the
+        // engine's own cancellation already lives upstream via the signal
+        // so the back-edge is unnecessary.
+        //
+        // r2 fix (triple-review P1): the abort listener was
+        // registered with `{ once: true }` — on actual abort it auto-detaches
+        // and disappears, but on the (common) NON-abort path where `run()`
+        // completes cleanly the listener stays attached to `ctx.signal`
+        // forever. Over a long REPL session (one shared AbortController per
+        // session, many run() invocations) listeners accumulate one per
+        // run, leaking memory and CPU on `dispatchEvent`. We now track the
+        // detach handle and call it unconditionally in the run()'s finally
+        // block so cleanup happens on both the success and abort paths.
+        const cancellation = new CancellationToken();
+        let detachAbortListener;
+        if (ctx.signal) {
+            if (ctx.signal.aborted) {
+                cancellation.abort();
+            }
+            else {
+                const handler = () => cancellation.abort();
+                ctx.signal.addEventListener('abort', handler, { once: true });
+                detachAbortListener = () => {
+                    ctx.signal.removeEventListener('abort', handler);
+                };
+            }
+        }
+        // r2 (triple-review P1): everything below runs inside a
+        // try/finally so the AbortSignal listener detaches on BOTH the
+        // success and abort paths. Without this wrap a long REPL session
+        // (one persistent AbortController, many run() invocations) leaked
+        // one abort listener per non-aborted run.
+        //
+        // #24 (CEO P1) — TaskCompleted chain. We
+        // capture `taskStartedAt` BEFORE the try block so the duration
+        // measured by the chain payload covers the full dispatch wall
+        // time (including the abort-listener wiring above). The
+        // `fireTaskCompletedOnce` guard ensures the chain fires at most
+        // once per `run()` invocation even when multiple `yield result`
+        // sites are reached (defensive — the existing flow yields exactly
+        // one result, but a future code path that yields twice would
+        // double-fire otherwise).
+        const taskStartedAt = Date.now();
+        let taskCompletedFired = false;
+        const fireTaskCompletedOnce = async (exitCode, toolCalls, filesChangedList) => {
+            if (taskCompletedFired)
+                return;
+            taskCompletedFired = true;
+            try {
+                await fireTaskCompletedChain(root, {
+                    command: kind,
+                    exitCode,
+                    durationMs: Date.now() - taskStartedAt,
+                    toolCalls,
+                    filesChanged: [...filesChangedList],
+                });
+            }
+            catch (chainError) {
+                process.stderr.write(`[pugi hook-chains] TaskCompleted chain crashed: ${chainError.message}\n`);
             }
-            : defaultEngineBudgets[kind];
-        yield {
-            type: 'status',
-            message: `Pugi engine starting: kind=${kind} budget=${budget.maxToolCalls} calls / ${budget.maxTokens} tokens`,
         };
-        // Buffer status events emitted from inside the loop hooks. Async
-        // generators cannot yield from synchronous callbacks, so we collect
-        // them in a queue and drain after the loop call completes. The loop
-        // is short enough (≤ ~30 turns) that latency-to-stdout is acceptable
-        // — a follow-up PR can switch to an event emitter for true streaming.
-        const buffer = [];
-        // Track files mutated by the loop. We extract the path from the JSON
-        // arguments of every successful write/edit tool call; `bash` is left
-        // out because its filesystem footprint is opaque (a single command
-        // can touch dozens of paths via `make`, `pnpm build`, etc). The
-        // per-session events.jsonl already carries every file_mutation event
-        // for replay; this set is only the headline summary the CLI prints.
-        const filesChanged = new Set();
-        // Pending lookup: call.id → path extracted from arguments. We only
-        // commit to `filesChanged` when the corresponding onToolResult fires
-        // with `ok: true`, so a refused or failed edit does not surface as
-        // a phantom change in the operator summary.
-        const pendingMutations = new Map();
-        // Per-session events mirror — `.pugi/sessions/<id>/events.jsonl`.
-        // The existing global log at `.pugi/events.jsonl` is preserved as
-        // the audit-replay source of truth; this mirror is the easy-to-find
-        // per-run log for operators and the cabinet UI (Sprint 2B).
-        const sessionEventsPath = openSessionMirror(root, session.id);
-        const hooks = {
-            onTurnStart: (turnIndex, messageCount) => {
-                const msg = `turn ${turnIndex + 1}: requesting model (transcript=${messageCount} messages)`;
-                buffer.push({ type: 'status', message: msg });
-                appendSessionMirror(sessionEventsPath, { type: 'turn_start', turn: turnIndex + 1, transcript: messageCount });
-            },
-            onTurnComplete: (turnIndex, response) => {
-                if (response.stop === 'tool_use') {
-                    const calls = response.assistantMessage.toolCalls ?? [];
-                    buffer.push({
-                        type: 'status',
-                        message: `turn ${turnIndex + 1}: model requested ${calls.length} tool call(s)`,
-                    });
-                    appendSessionMirror(sessionEventsPath, {
-                        type: 'turn_complete',
-                        turn: turnIndex + 1,
-                        stop: 'tool_use',
-                        toolCalls: calls.length,
-                        tokensUsed: response.tokensUsed,
-                    });
+        try {
+            const toolCtx = {
+                root,
+                settings,
+                session,
+                readCache: new FileReadCache(),
+                cancellation,
+            };
+            // L11 : instantiate per-`run()` denial tracker. The
+            // executor records every refusal (PLAN_MODE_REFUSED, HOOK_BLOCKED,
+            // OPERATOR_ABORTED, STALE_READ, unknown-tool, plan-mode agent) and
+            // the user-prompt assembler below splices a compact reminder when
+            // the same (tool, args) pair has been denied twice or more. The
+            // tracker is in-memory only — the audit ledger at
+            // `.pugi/events.jsonl` already captures the full per-event log for
+            // forensic replay; this surface is the model-facing aggregate.
+            const denialTracking = new DenialTrackingState();
+            // β1a r1 (budget wiring): swap the legacy SDK per-
+            // command budget lookup for the Pl9 `resolveBudget()` pipeline so
+            // `.pugi/settings.json::budgets.<command>` overrides actually take
+            // effect at runtime + the HARD_MAX_* caps guard misconfigured
+            // envelopes pre-flight. Before this fix the β1 Pl9 module
+            // (`core/engine/budgets.ts`) was dead code — the adapter still
+            // read the per-command defaults from the SDK, so operators who
+            // set `budgets.code.maxTokens = 50000` in settings.json got the
+            // legacy 30k anyway and `assertBudgetWithinTier` never ran.
+            //
+            // Task-level token override (e.g. CLI `--max-tokens`) keeps
+            // precedence; tool-call ceiling falls through to the resolved
+            // budget so a careless caller cannot disable the call-count
+            // guard by setting only token count.
+            //
+            // Triple-review P1 follow-up : forward `task.budget.turns`
+            // through the resolver so `EngineBudget.maxTurns` actually lands on
+            // the SDK's `runEngineLoop`. The CLI seam packs both `--max-turns`
+            // (explicit operator override) and the intensity profile's per-tier
+            // cap into this field with explicit-flag-wins precedence.
+            const taskBudgetOverride = {};
+            if (task.budget?.tokens)
+                taskBudgetOverride.maxTokens = task.budget.tokens;
+            if (task.budget?.turns !== undefined)
+                taskBudgetOverride.maxTurns = task.budget.turns;
+            const budget = resolveBudget(kind, settings, Object.keys(taskBudgetOverride).length > 0 ? taskBudgetOverride : undefined);
+            // CEO P1 #14 (auto-compact): resolve the per-workspace
+            // override of the 75% threshold gate. Default is `{ enabled: true,
+            // thresholdRatio: 0.75 }`; operators kill it via
+            // `.pugi/settings.json::autoCompact.enabled = false` или retune the
+            // ratio. The resolved config is captured by the closure that
+            // `runEngineLoop` invokes pre-send on every turn.
+            //
+            // PR E (2026-06-05): `summaryMode` defaults to `'llm'` so the
+            // sentinel is a narrative produced by Gemini Flash via Anvil rather
+            // than a deterministic counts line. The summarizer below is bound
+            // to the same engine client the loop uses for tool turns, so the
+            // summary call shares auth + transport with the rest of the loop.
+            const autoCompactConfig = resolveAutoCompactConfig(settings);
+            const summaryLlmCall = autoCompactConfig.summaryMode === 'llm'
+                ? buildSummarizerCall(this.options.client, personaSlugFor(kind))
+                : null;
+            // β3 streaming: pre-build the typed stream event queue so the hook
+            // callbacks below can push live events that this async generator
+            // yields IMMEDIATELY (instead of buffering until `runEngineLoop`
+            // completes). Operator now sees the first `tool.start` within
+            // ~tens of ms of the model emitting it, not 30+ s after the loop
+            // settles.
+            const streamQueue = new AsyncEventQueue();
+            const emitter = this.streamEmitter;
+            const supportsThinking = modelSupportsThinking(this.options.model);
+            /**
+             * Push one typed stream event into BOTH the per-run async queue
+             * (the CLI's iterator) and the long-lived emitter (the multiplex
+             * fan-out for admin-api SSE / cabinet WebSocket subscribers).
+             * The function stamps `timestamp` once so both consumers see the
+             * same wall clock.
+             */
+            const emitStream = (event) => {
+                const stamped = {
+                    ...event,
+                    timestamp: new Date().toISOString(),
+                };
+                streamQueue.push(stamped);
+                emitter.emit('event', stamped);
+            };
+            // r1 fix per triple-review Backend Architect P1: unify yield path via
+            // emitStream + streamQueue drain so the iterator consumer does NOT
+            // see this status frame twice. Pre-fix did both bare yield + emitStream
+            // → iterator got 2 copies, emitter got 1.
+            emitStream({
+                type: 'status',
+                message: `Pugi engine starting: kind=${kind} budget=${budget.maxToolCalls} calls / ${budget.maxTokens} tokens`,
+            });
+            // #21 : emit `dispatch_start` to the
+            // tenant-wide audit trail at `~/.pugi/audit/<tenant>/<slug>-<hash>
+            // .jsonl`. Append-only, never throws — a misconfigured audit
+            // surface must not block a dispatch. The per-session mirror under
+            // `.pugi/sessions/<id>/events.jsonl` remains as a redundant copy.
+            // PR F (2026-06-05): capture dispatch start wall-clock so the
+            // notes recorder can compute durationSeconds at dispatch end.
+            const dispatchStartedAt = new Date().toISOString();
+            writeAuditEvent({
+                event: 'dispatch_start',
+                sessionId: session.id,
+                workspaceRoot: root,
+                data: {
+                    kind,
+                    promptLength: task.prompt.length,
+                    maxToolCalls: budget.maxToolCalls,
+                    maxTokens: budget.maxTokens,
+                    model: this.options.model ?? null,
+                },
+            });
+            // β5a R1+R4+R5+R6+P1 : build the per-turn `<context>`
+            // prefix and apply the intent marker so the model sees:
+            //  1. cwd + open-files + per-dir-conventions block (R5+R6)
+            //  2. a `<intent kind="definitional">` wrapper when the operator
+            //     asked a knowledge question (P1) — fixes the "What is grep?
+            //     → bash man grep" loss mode flagged by the .X eval.
+            //
+            // All caps enforced inside the builders (5 KB block + 50 entries
+            // + top-3 markdown). Worst-case prompt growth is ~5 KB, well
+            // inside any per-command token budget.
+            //
+            // cwd is sourced from `process.cwd()` — the operator's shell pwd
+            // when they invoked `pugi`. For non-REPL CLI paths this is
+            // accurate; the REPL session retains the launch cwd for the
+            // lifetime of the session which is what the operator expects.
+            const cwdForTraverse = process.cwd();
+            // cwd → homedir walk-up that picks up every
+            // ambient `PUGI.md` (or `CLAUDE.md` as a fallback) the operator
+            // has placed above their workspace. This is the cross-project
+            // hierarchy walk — distinct from the workspace-bounded
+            // `loadTraversedMarkdown` below which only sees files INSIDE the
+            // workspace root. Render the concatenation once at session boot
+            // and prepend to the system prompt so the model treats the
+            // operator's personal guidance as ambient context for the whole
+            // session. `--bare` () skips this walk entirely.
+            let ambientContextBlock = '';
+            if (!isBareMode()) {
+                try {
+                    const hierarchy = walkUpPugiMd(cwdForTraverse);
+                    // Backlog : expand `@import` directives and
+                    // capture `paths:` frontmatter for each ambient file. The
+                    // walker already returned the raw bodies; the loader replaces
+                    // each body with its `@import`-expanded variant + appends any
+                    // imported children at the same hierarchy level. Failures are
+                    // localised per-file so one malformed `~/CLAUDE.md` cannot
+                    // break the rest of the chain.
+                    const expanded = await expandHierarchyWithImports(hierarchy, cwdForTraverse);
+                    ambientContextBlock = renderAmbientContext(expanded);
                 }
-                else if (response.stop === 'text') {
-                    buffer.push({
-                        type: 'status',
-                        message: `turn ${turnIndex + 1}: model returned final text (${response.content.length} chars)`,
+                catch {
+                    // Pure FS surface — if it throws (programmer error in the
+                    // walker, not a per-file fs error which is already swallowed
+                    // inside) we drop ambient context for this session rather
+                    // than crashing the engine loop. Doctor probe still surfaces
+                    // the hierarchy state for operator triage.
+                    ambientContextBlock = '';
+                }
+            }
+            // AST-light repo-map injection. We build a
+            // compact `## Repo map` block (capped at the formatter's default
+            // 8 KB ≈ 2K tokens) from the workspace source tree + splice it
+            // onto the system prompt alongside the ambient PUGI.md block.
+            // `--bare` skips this exactly like the PUGI.md walk — the engine
+            // sees nothing the operator did not explicitly hand it. The build
+            // is deferred к `setImmediate` semantics by being a sync call
+            // AFTER the boot probes; the cost is one stat per source file
+            // (the cache catches mtime-unchanged files и skips re-extraction).
+            // Failures are swallowed: repo-map is enrichment, never a gate.
+            let repoMapBlock = '';
+            if (!isBareMode()) {
+                try {
+                    const { buildAndFormatRepoMap } = await import('../repo-map/build.js');
+                    const verdict = buildAndFormatRepoMap({
+                        root,
+                        // Boot path is best-effort: never refresh during engine boot
+                        // (the operator can `pugi repo-map --refresh` manually). The
+                        // cache freshness check catches every realistic edit pattern
+                        // and avoids walking the tree on every engine invocation.
+                        refresh: false,
+                        // Persist the cache so the next boot reuses extracts. Engine
+                        // boot runs on every command, so missing the persist would
+                        // hot-loop the extractor on each invocation.
+                        writeCache: true,
+                        // Omit the formatter's section header — the system prompt
+                        // already structures the ambient blocks, и a second `##`
+                        // would fragment the prompt cache на a model-by-model basis.
+                        omitHeader: false,
                     });
-                    appendSessionMirror(sessionEventsPath, {
-                        type: 'turn_complete',
-                        turn: turnIndex + 1,
-                        stop: 'text',
-                        contentLength: response.content.length,
-                        tokensUsed: response.tokensUsed,
+                    if (verdict.build.ok && verdict.format && verdict.format.bytes > 0) {
+                        repoMapBlock = verdict.format.text;
+                    }
+                }
+                catch {
+                    // Any failure in the repo-map pipeline drops the block. The
+                    // engine continues without enrichment — the failure mode is
+                    // identical to the cold-boot path before L28 landed.
+                    repoMapBlock = '';
+                }
+            }
+            let traverseResult;
+            // `--bare` skips the parent-dir PUGI.md /
+            // AGENTS.md / CLAUDE.md / GEMINI.md walk-up. The engine sees only
+            // the operator's prompt + working-set + intent marker, with no
+            // ambient project context injection. Mirrors the standard tool's
+            // --bare semantics.
+            if (isBareMode()) {
+                traverseResult = { loaded: [], warnings: [], totalBytes: 0 };
+            }
+            else {
+                try {
+                    traverseResult = await loadTraversedMarkdown({
+                        cwd: cwdForTraverse,
+                        workspaceRoot: root,
                     });
                 }
-            },
-            onToolCall: (call) => {
-                // Record under an `engine_tool` prefix so the audit log can
-                // distinguish loop-driven calls from direct CLI tool calls.
-                const id = recordToolCall(session, `engine:${call.name}`, call.arguments.slice(0, 200));
-                // Stash the audit id on the call for `onToolResult` to close.
-                this.engineToolCallIds.set(call.id, id);
-                // Extract a candidate path for write/edit so we can build the
-                // filesChanged summary if (and only if) the call succeeds. Bad
-                // JSON is harmless here — we ignore it and the executor surfaces
-                // the actual parse error to the model.
-                if (call.name === 'write' || call.name === 'edit') {
-                    const path = extractPathArg(call.arguments);
-                    if (path)
-                        pendingMutations.set(call.id, path);
+                catch {
+                    // Per-dir markdown is a NICE-TO-HAVE; a fs error here must
+                    // never break the engine loop. Fall back to an empty result
+                    // so the prefix block still surfaces cwd + working set.
+                    traverseResult = { loaded: [], warnings: [], totalBytes: 0 };
                 }
-                buffer.push({
+            }
+            const intentClassification = classifyIntent(task.prompt);
+            const intentHint = intentClassification.intent !== 'ambiguous' ? intentClassification.intent : undefined;
+            const cwdRelative = relativeOrAbsolute(root, cwdForTraverse);
+            const prefix = buildContextPrefix({
+                cwdRelative,
+                // β5a defers wiring the live WorkingSet snapshot to the REPL
+                // session integration (R5+R6 here only covers the engine-side
+                // builder). When the REPL passes its working set down, the
+                // engine surface fills in. For now the prefix carries cwd +
+                // per-dir conventions + intent which are the two biggest
+                // win-rate moves per the .X eval.
+                traversedMarkdown: traverseResult.loaded,
+                intentHint,
+            });
+            if (prefix.bytes > 0 || intentClassification.intent === 'definitional') {
+                emitStream({
                     type: 'status',
-                    message: `tool_call: ${call.name}(${call.arguments.slice(0, 80)}${call.arguments.length > 80 ? '...' : ''})`,
-                });
-                appendSessionMirror(sessionEventsPath, {
-                    type: 'tool_call',
-                    tool: call.name,
-                    callId: call.id,
-                    argsPreview: call.arguments.slice(0, 200),
+                    message: `context: cwd=${cwdRelative} per-dir-md=${prefix.counts.markdownIncluded}/${prefix.counts.markdownTotal} intent=${intentClassification.intent}`,
                 });
-            },
-            onToolResult: (call, result) => {
-                const auditId = this.engineToolCallIds.get(call.id);
-                if (auditId) {
-                    if (result.ok) {
-                        recordToolResult(session, auditId, 'success', result.content.slice(0, 200));
+            }
+            const decoratedPrompt = applyIntentMarker(task.prompt, intentClassification.intent);
+            const finalUserPrompt = spliceContextPrefix(prefix.block, decoratedPrompt);
+            // Track files mutated by the loop. We extract the path from the JSON
+            // arguments of every successful write/edit tool call; `bash` is left
+            // out because its filesystem footprint is opaque (a single command
+            // can touch dozens of paths via `make`, `pnpm build`, etc). The
+            // per-session events.jsonl already carries every file_mutation event
+            // for replay; this set is only the headline summary the CLI prints.
+            const filesChanged = new Set();
+            // Pending lookup: call.id → path extracted from arguments. We only
+            // commit to `filesChanged` when the corresponding onToolResult fires
+            // with `ok: true`, so a refused or failed edit does not surface as
+            // a phantom change in the operator summary.
+            const pendingMutations = new Map();
+            // Per-session events mirror — `.pugi/sessions/<id>/events.jsonl`.
+            // The existing global log at `.pugi/events.jsonl` is preserved as
+            // the audit-replay source of truth; this mirror is the easy-to-find
+            // per-run log for operators and the cabinet UI (Sprint 2B).
+            const sessionEventsPath = openSessionMirror(root, session.id);
+            const hooks = {
+                // CEO P1 #14 (auto-compact): single operator-visible
+                // line on stderr — keep parity with the upstream tool's
+                // `Compacted N turns into Y tokens; continuing.` message. We mirror
+                // the event into the session log + stream emitter as a `status`
+                // frame так that admin-api SSE consumers + the cabinet UI render
+                // it without a schema change.
+                onAutoCompact: (event) => {
+                    const pct = Math.round((event.preUsedTokens / Math.max(1, event.maxTokens)) * 100);
+                    const line = `engine: auto-compacted ${event.droppedCount} turns at ${event.preUsedTokens}/${event.maxTokens} (${pct}%)`;
+                    // Single-line stderr write — operator-visible per spec.
+                    process.stderr.write(`${line}\n`);
+                    emitStream({ type: 'status', message: line });
+                    appendSessionMirror(sessionEventsPath, {
+                        type: 'auto_compact',
+                        droppedCount: event.droppedCount,
+                        preUsedTokens: event.preUsedTokens,
+                        postUsedTokens: event.postUsedTokens,
+                        maxTokens: event.maxTokens,
+                        gist: event.gist,
+                    });
+                    // #21: tenant-wide audit trail mirror.
+                    writeAuditEvent({
+                        event: 'auto_compact',
+                        sessionId: session.id,
+                        workspaceRoot: root,
+                        data: {
+                            droppedCount: event.droppedCount,
+                            preUsedTokens: event.preUsedTokens,
+                            postUsedTokens: event.postUsedTokens,
+                            maxTokens: event.maxTokens,
+                        },
+                    });
+                },
+                onTurnStart: (turnIndex, messageCount) => {
+                    const msg = `turn ${turnIndex + 1}: requesting model (transcript=${messageCount} messages)`;
+                    emitStream({ type: 'status', message: msg });
+                    appendSessionMirror(sessionEventsPath, { type: 'turn_start', turn: turnIndex + 1, transcript: messageCount });
+                },
+                onTurnComplete: (turnIndex, response) => {
+                    if (response.stop === 'tool_use') {
+                        const calls = response.assistantMessage.toolCalls ?? [];
+                        emitStream({
+                            type: 'status',
+                            message: `turn ${turnIndex + 1}: model requested ${calls.length} tool call(s)`,
+                        });
+                        appendSessionMirror(sessionEventsPath, {
+                            type: 'turn_complete',
+                            turn: turnIndex + 1,
+                            stop: 'tool_use',
+                            toolCalls: calls.length,
+                            tokensUsed: response.tokensUsed,
+                        });
+                    }
+                    else if (response.stop === 'text') {
+                        emitStream({
+                            type: 'status',
+                            message: `turn ${turnIndex + 1}: model returned final text (${response.content.length} chars)`,
+                        });
+                        appendSessionMirror(sessionEventsPath, {
+                            type: 'turn_complete',
+                            turn: turnIndex + 1,
+                            stop: 'text',
+                            contentLength: response.content.length,
+                            tokensUsed: response.tokensUsed,
+                        });
+                        // β3 E4 thinking-block surface: only Claude / Gemini families
+                        // advertise structured thinking today. The model resolver may
+                        // return a slug we don't recognise; in that case we skip the
+                        // split silently. When we DO recognise it, every `<thinking>`
+                        // / `<thought>` block becomes a separate `thinking.start`/
+                        // `thinking.delta`/`thinking.end` triplet so the TUI can
+                        // render one collapsed pane row per block. The visible text
+                        // (post-strip) flows to the regular `text.delta` channel so
+                        // the conversation pane never shows raw <thinking> markup.
+                        if (supportsThinking && response.content.length > 0) {
+                            const split = splitThinkingBlocks(response.content);
+                            for (const block of split.thinkingBlocks) {
+                                const blockId = `think-${randomUUID().slice(0, 8)}`;
+                                emitStream({ type: 'thinking.start', blockId });
+                                emitStream({ type: 'thinking.delta', blockId, chunk: block });
+                                emitStream({ type: 'thinking.end', blockId });
+                            }
+                            if (split.visibleText.length > 0) {
+                                emitStream({ type: 'text.delta', chunk: split.visibleText });
+                            }
+                        }
+                        else if (response.content.length > 0) {
+                            emitStream({ type: 'text.delta', chunk: response.content });
+                        }
+                    }
+                },
+                onToolCall: (call) => {
+                    // Record under an `engine_tool` prefix so the audit log can
+                    // distinguish loop-driven calls from direct CLI tool calls.
+                    const id = recordToolCall(session, `engine:${call.name}`, call.arguments.slice(0, 200));
+                    // Stash the audit id on the call for `onToolResult` to close.
+                    this.engineToolCallIds.set(call.id, id);
+                    // Extract a candidate path for write/edit so we can build the
+                    // filesChanged summary if (and only if) the call succeeds. Bad
+                    // JSON is harmless here — we ignore it and the executor surfaces
+                    // the actual parse error to the model.
+                    if (call.name === 'write' || call.name === 'edit') {
+                        const path = extractPathArg(call.arguments);
+                        if (path)
+                            pendingMutations.set(call.id, path);
+                    }
+                    emitStream({
+                        type: 'tool.start',
+                        callId: call.id,
+                        name: call.name,
+                        arguments: call.arguments,
+                    });
+                    emitStream({
+                        type: 'status',
+                        message: `tool_call: ${call.name}(${call.arguments.slice(0, 80)}${call.arguments.length > 80 ? '...' : ''})`,
+                    });
+                    appendSessionMirror(sessionEventsPath, {
+                        type: 'tool_call',
+                        tool: call.name,
+                        callId: call.id,
+                        argsPreview: call.arguments.slice(0, 200),
+                    });
+                    // #21: tenant-wide audit trail mirror. Same payload
+                    // shape as the session mirror but flattened so a `jq` query
+                    // across all sessions for one (tenant, workspace) reads
+                    // cleanly.
+                    writeAuditEvent({
+                        event: 'tool_call',
+                        sessionId: session.id,
+                        workspaceRoot: root,
+                        data: {
+                            tool: call.name,
+                            callId: call.id,
+                            argsPreview: call.arguments.slice(0, 200),
+                        },
+                    });
+                },
+                onToolResult: (call, result) => {
+                    const auditId = this.engineToolCallIds.get(call.id);
+                    if (auditId) {
+                        if (result.ok) {
+                            recordToolResult(session, auditId, 'success', result.content.slice(0, 200));
+                        }
+                        else {
+                            recordToolResult(session, auditId, 'error', result.error.slice(0, 200));
+                        }
+                        this.engineToolCallIds.delete(call.id);
                     }
-                    else {
-                        recordToolResult(session, auditId, 'error', result.error.slice(0, 200));
+                    const pendingPath = pendingMutations.get(call.id);
+                    if (pendingPath) {
+                        if (result.ok)
+                            filesChanged.add(pendingPath);
+                        pendingMutations.delete(call.id);
                     }
-                    this.engineToolCallIds.delete(call.id);
+                    emitStream({
+                        type: 'tool.end',
+                        callId: call.id,
+                        ok: result.ok,
+                        summary: result.ok
+                            ? result.content.slice(0, 200)
+                            : result.error.slice(0, 200),
+                    });
+                    emitStream({
+                        type: 'status',
+                        message: result.ok
+                            ? `tool_result: ${call.name} ok`
+                            : `tool_result: ${call.name} error: ${result.error.slice(0, 120)}`,
+                    });
+                    appendSessionMirror(sessionEventsPath, {
+                        type: 'tool_result',
+                        tool: call.name,
+                        callId: call.id,
+                        ok: result.ok,
+                        summary: result.ok ? result.content.slice(0, 200) : result.error.slice(0, 200),
+                    });
+                    // #21: tenant-wide audit trail mirror.
+                    writeAuditEvent({
+                        event: 'tool_result',
+                        sessionId: session.id,
+                        workspaceRoot: root,
+                        data: {
+                            tool: call.name,
+                            callId: call.id,
+                            ok: result.ok,
+                            summary: result.ok ? result.content.slice(0, 200) : result.error.slice(0, 200),
+                        },
+                    });
+                },
+            };
+            // β1b r1 (--allow-fetch / --allow-search wiring):
+            // compute the effective gate as OR of (a) the persisted
+            // settings.json opt-in and (b) the runtime CLI flag passed via
+            // the constructor. Before this fix the adapter only honored (a),
+            // so `pugi code --allow-fetch` against a default-privacy workspace
+            // silently fell back to "tool not advertised" even though the
+            // operator opted in for one invocation. The CLI flag was wired
+            // through to the legacy `pugi web` sub-command but not to the
+            // engine adapter — Backend Architect review (PR r1) caught
+            // the gap.
+            const allowFetchEffective = this.options.allowFetch === true || settings.web?.fetch?.enabled === true;
+            const allowSearchEffective = this.options.allowSearch === true || settings.web?.search?.enabled === true;
+            // β2 S3 → β2a r1 (Backend Architect P1):
+            // expose the `agent` tool to the parent loop ONLY for non-plan
+            // commands. `buildToolsSchema` also strips the agent tool from
+            // plan-mode schemas, but a model that fabricates an `agent` call
+            // would still hit the executor with `agentDispatch` wired and
+            // could spawn a coder that mutates the workspace — breaking the
+            // plan-mode read-only contract. Hard-gate `allowAgent` on the
+            // command kind so plan mode never wires the dispatch block in
+            // the first place; tool-bridge.ts also throws ToolRefused on a
+            // fabricated `agent` call in plan mode as defense in depth.
+            //
+            // Why only the top-level parent and not children: the dispatcher-
+            // real.ts module builds the CHILD's executor without an
+            // `agentDispatch` block so children cannot recursively spawn
+            // grandchildren. The isolation-matrix capability set then refuses
+            // the `agent` tool for every non-orchestrator role anyway, but
+            // the executor-level gate is the load-bearing chokepoint.
+            // Pugi backlog — intensity dial gates the `agent` tool surface.
+            // Plan-mode hard gate keeps its precedence (read-only contract);
+            // the intensity layer OR-s on top so `--intensity quick|standard`
+            // suppresses the dispatch block even on non-plan kinds.
+            const intensityAllowsAgent = this.options.intensityProfile?.allowParallelAgents ?? true;
+            const allowAgent = kind !== 'plan' && intensityAllowsAgent;
+            // Pugi backlog — resolve the effective model hint. Operator-
+            // pinned `model` option wins outright. Otherwise the intensity
+            // profile's `modelTag` resolves to a concrete slug via the
+            // `PUGI_INTENSITY_MODEL_<TAG>` env (LIGHT / STANDARD / HEAVY) so
+            // ops can pin "what does 'standard' mean on this machine" without
+            // a code change. Absent profile + absent env => undefined (legacy
+            // per-persona resolution path).
+            const effectiveModel = resolveIntensityModel(this.options.model, this.options.intensityProfile);
+            // β3 streaming: kick off `runEngineLoop` IN PARALLEL with the queue
+            // drain. The loop's hook callbacks push events onto `streamQueue`
+            // synchronously; this generator yields them live by awaiting the
+            // queue's iterator. When the loop settles (success or crash) we
+            // close the queue, which lets the iterator return cleanly and the
+            // generator falls through to the terminal `result` frame.
+            //
+            // Why concurrent instead of serial:
+            //
+            //  The β1 adapter awaited `runEngineLoop` to completion, then
+            //  drained an in-memory `EngineEvent[]` buffer. Operator saw
+            //  nothing for 30+ seconds (the full LLM round-trip + tool exec
+            //  wall time), then the entire log dumped at once. The TUI tool-
+            //  stream pane was a no-op because no event ever reached it
+            //  before the loop completed.
+            //
+            //  `Promise.race`-based interleaving lets us yield the next queue
+            //  event OR detect loop settlement on each tick. The settlement
+            //  flag (`loopSettled`) gates the final drain so we never miss
+            //  tail events that the hooks pushed in the same microtask as
+            //  the loop's terminal `return`.
+            // Boxed via single-element tuple so TypeScript does not narrow the
+            // outer `outcome` binding to `null` after the closure mutation.
+            // Async-closure mutations are invisible to TS control-flow analysis;
+            // wrapping in a tuple defeats the narrowing without an unsafe cast.
+            const outcomeBox = [null];
+            let loopError = null;
+            const loopPromise = (async () => {
+                try {
+                    outcomeBox[0] = await runEngineLoop({
+                        client: this.options.client,
+                        executor: buildExecutor({
+                            kind,
+                            ctx: toolCtx,
+                            sessionId: session.id,
+                            workspaceRoot: root,
+                            // P1 fix (deep audit): forward optional REPL
+                            // ask-modal bridge. Default `interactive: false` preserves
+                            // backward compat — non-TTY callers (CI, pipes, scripted
+                            // CLI runs) keep the `[user_input_required]` envelope path.
+                            // The REPL layer passes `interactive: true` + a real
+                            // `askUserBridge` so model-initiated `ask_user_question`
+                            // calls round-trip to the ink modal and return the
+                            // operator's choice as a tool result.
+                            interactive: this.options.interactive === true,
+                            ...(this.options.askUserBridge
+                                ? { askUserBridge: this.options.askUserBridge }
+                                : {}),
+                            // P1 fix (deep audit): forward the workspace
+                            // HookRegistry so `.pugi/hooks/` lifecycle hooks fire for
+                            // model-initiated tool calls. SECURITY: a `PreToolUse
+                            // onFailure: 'block'` hook that refuses bash containing
+                            // `rm` now applies to model dispatch — before this fix
+                            // such a hook only applied to direct CLI tool calls.
+                            ...(this.options.hooks ? { hooks: this.options.hooks } : {}),
+                            // β1a r1 (web_fetch gating) + β1b r1 (--allow-fetch wiring):
+                            // executor allowFetch matches the schema-advertise gate so a
+                            // settings.json opt-in OR a --allow-fetch flag enables the
+                            // call. Without this the model would not even see the
+                            // `web_fetch` tool. `allowSearch` covers the new T4
+                            // `web_search` tool with the same OR semantics.
+                            allowFetch: allowFetchEffective,
+                            allowSearch: allowSearchEffective,
+                            // β2 S3 → β2a r1 : parent-level agentDispatch
+                            // wiring. When the model emits a `tool_call: agent(role,
+                            // brief)`, the executor forwards it to dispatcher-real.ts
+                            // which spawns a child engine loop against the same Anvil
+                            // client. Gated by `allowAgent` so plan mode does not even
+                            // wire the dispatch block — defense in depth on top of the
+                            // schema-filter and the tool-bridge plan-mode refusal.
+                            ...(allowAgent
+                                ? {
+                                    agentDispatch: {
+                                        parentSession: session,
+                                        engineClient: this.options.client,
+                                    },
+                                }
+                                : {}),
+                            // β4 M1/M3/M5: pass the loaded MCP registry through so the
+                            // executor can route `mcp__server__tool` calls + run the
+                            // first-call permission prompt before dispatching upstream.
+                            ...(this.options.mcpRegistry ? { mcpRegistry: this.options.mcpRegistry } : {}),
+                            ...(this.options.mcpPrompt ? { mcpPrompt: this.options.mcpPrompt } : {}),
+                            // L11 : per-`run()` denial tracker. Every
+                            // refusal sentinel (PLAN_MODE_REFUSED, HOOK_BLOCKED,
+                            // OPERATOR_ABORTED, STALE_READ, unknown-tool, plan-mode
+                            // agent) is fingerprinted by (toolName, sha256(canonical
+                            // args)) so the model's next-turn reminder surfaces the
+                            // pattern instead of re-issuing the same refused call.
+                            denialTracking,
+                        }),
+                        // ambient `PUGI.md` hierarchy block
+                        // prepended once at session boot. When the walk found
+                        // nothing OR bare mode is on, `ambientContextBlock === ''`
+                        // and the system prompt is unchanged — no leading blank
+                        // line, no empty wrapper tag.
+                        //
+                        // task #19 : static / dynamic
+                        // split via `__PUGI_DYNAMIC_BOUNDARY__` sentinel. The persona
+                        // prompt (`systemPromptFor(kind)`) is byte-stable across
+                        // sessions of the same command kind — it goes BEFORE the
+                        // boundary so Anvil's prefix cache hits on the common
+                        // prefix. Per-workspace blocks (PUGI.md hierarchy, repo
+                        // map) live AFTER the boundary because they change with
+                        // the user's checkout state.
+                        //
+                        // ORDERING CHANGE — pre-#19 the model saw
+                        //  ambient → repoMap → persona
+                        // post-#19 the model sees
+                        //  persona → ambient → repoMap
+                        // This is INTENTIONAL — the cache prefix MUST be byte-stable
+                        // and the persona is the only byte-stable block. Operators
+                        // who relied on ambient guidance "fronting" the persona prompt
+                        // () should now place that guidance inside
+                        // the persona via `systemPromptFor(kind)` instead of PUGI.md.
+                        // The empirical impact on model behaviour is bounded: persona
+                        // prompts are tight directives; ambient PUGI.md is operator
+                        // context. Either order is interpretable; the cache hit
+                        // outweighs the front-loading.
+                        systemPrompt: composeSystemPromptWithBoundary([systemPromptFor(kind)], [ambientContextBlock, repoMapBlock]),
+                        // β5a R5+R6+P1: per-turn `<context>` prefix + intent marker
+                        // applied above. Falls back to verbatim `task.prompt` when
+                        // both the prefix block is empty AND the intent classifier
+                        // returned ambiguous (the splice + apply functions handle
+                        // that case as identity).
+                        userPrompt: finalUserPrompt,
+                        // β1a r1 (web_fetch gating) + β1b r1 (--allow-fetch wiring):
+                        // pass the OR of `.pugi/settings.json::web.fetch.enabled` and
+                        // the runtime `--allow-fetch` flag. When neither is true the
+                        // `web_fetch` tool is not advertised to the model at all.
+                        // `allowSearch` does the same for the new `web_search` tool.
+                        // β2 S3: allowAgent surfaces the `agent` tool in the schema
+                        // so the model sees it as a valid tool call option; the
+                        // capability-matrix layer (S4) still gates which roles can
+                        // actually USE it. Plan mode strips it via β2a r1 gate.
+                        tools: buildToolsSchema(kind, {
+                            allowFetch: allowFetchEffective,
+                            allowSearch: allowSearchEffective,
+                            allowAgent,
+                            // β4 M1/M3: same registry the executor saw. Schema +
+                            // dispatcher must agree on which MCP names are advertised
+                            // and which are dispatchable; passing identical references
+                            // makes that invariant impossible to break.
+                            ...(this.options.mcpRegistry ? { mcpRegistry: this.options.mcpRegistry } : {}),
+                        }),
+                        budget,
+                        personaSlug: personaSlugFor(kind),
+                        hooks,
+                        temperature: this.options.temperature ?? 0.2,
+                        signal: ctx.signal,
+                        // β1 (audit E2): forward CLI sub-command + routing tag +
+                        // operator-pinned model so the runtime controller's DTO sees
+                        // all three. `tag` derives 1:1 from `command` for now
+                        // (`code → code`, `build → build_task`, etc.); future routing
+                        // changes flip the mapping table without touching the call
+                        // site. `model` is left undefined here — operator-pinned model
+                        // pinning ships in β6 with persona routing.
+                        command: kind,
+                        tag: dispatchTagFor(kind),
+                        model: effectiveModel,
+                        // Task — 1M context tier opt-in. Forwarded к the SDK
+                        // driver which threads it through every `client.send` call to
+                        // the runtime gate. `undefined` (the default) preserves
+                        // legacy routing.
+                        contextTier: this.options.contextTier,
+                        // CEO P1 #14 (auto-compact): pluggable compactor
+                        // hook. The SDK driver invokes this pre-`client.send` on every
+                        // turn. `maybeCompactAsync` returns `null` below the 75%
+                        // threshold или when the transcript is too short to drop
+                        // history — the loop continues unchanged on the cold path.
+                        // When it returns a result, the driver swaps the transcript +
+                        // fires the `onAutoCompact` hook above which emits the stderr
+                        // line.
+                        //
+                        // PR E (2026-06-05): the async variant dispatches between
+                        // the legacy stats sentinel and an LLM-produced narrative.
+                        // The SDK driver awaits the Promise — see engine-loop.ts.
+                        autoCompact: ({ transcript, maxTokens }) => maybeCompactAsync(transcript, maxTokens, autoCompactConfig, summaryLlmCall, { signal: ctx.signal }),
+                    });
                 }
-                const pendingPath = pendingMutations.get(call.id);
-                if (pendingPath) {
-                    if (result.ok)
-                        filesChanged.add(pendingPath);
-                    pendingMutations.delete(call.id);
+                catch (err) {
+                    loopError = err;
                 }
-                buffer.push({
-                    type: 'status',
-                    message: result.ok
-                        ? `tool_result: ${call.name} ok`
-                        : `tool_result: ${call.name} error: ${result.error.slice(0, 120)}`,
+                finally {
+                    // Close the queue so the iterator below returns `done: true`.
+                    // Any tail events the hooks pushed in the same microtask still
+                    // drain because `AsyncEventQueue.close()` only resolves
+                    // PENDING awaiters — buffered items stay readable.
+                    streamQueue.close();
+                }
+            })();
+            // Drain the queue live. Each iteration yields one EngineEvent the
+            // moment its hook fired. Operator sees `tool.start` within tens of
+            // ms of the model emitting it.
+            for await (const event of streamQueue) {
+                yield streamEventToEngineEvent(event);
+            }
+            // Loop has settled (queue closed). Surface its outcome — either an
+            // unhandled crash from the (rare) executor exception path or the
+            // structured EngineLoopOutcome.
+            await loopPromise;
+            if (loopError !== null) {
+                const message = loopError instanceof Error ? loopError.message : String(loopError);
+                // #21: surface the crash to the audit trail before
+                // returning. Mirrors the `failed` arm of the structured path
+                // below so a SOC pipeline sees one `dispatch_end` per dispatch
+                // regardless of which code path produced it.
+                writeAuditEvent({
+                    event: 'dispatch_end',
+                    sessionId: session.id,
+                    workspaceRoot: root,
+                    data: {
+                        status: 'crashed',
+                        error: message,
+                    },
                 });
-                appendSessionMirror(sessionEventsPath, {
-                    type: 'tool_result',
-                    tool: call.name,
-                    callId: call.id,
-                    ok: result.ok,
-                    summary: result.ok ? result.content.slice(0, 200) : result.error.slice(0, 200),
+                // #24 (CEO P1): TaskCompleted chain fires
+                // even on engine-loop crash so an operator hook can surface the
+                // failure to Slack / a dashboard. Best-effort — chain crashes
+                // never propagate.
+                await fireTaskCompletedOnce(1, 0, []);
+                yield {
+                    type: 'result',
+                    result: {
+                        status: 'failed',
+                        summary: `engine loop crashed: ${message}`,
+                        filesChanged: [],
+                        patchRefs: [],
+                        testsRun: [],
+                        risks: [`unhandled error in engine adapter: ${message}`],
+                        eventRefs: [],
+                    },
+                };
+                return;
+            }
+            const finalOutcome = outcomeBox[0];
+            if (finalOutcome === null) {
+                // Defensive — should never hit. `runEngineLoop` always either
+                // resolves with an outcome or throws (and we catch that above).
+                writeAuditEvent({
+                    event: 'dispatch_end',
+                    sessionId: session.id,
+                    workspaceRoot: root,
+                    data: { status: 'no_outcome' },
                 });
-            },
-        };
-        let outcome;
-        try {
-            outcome = await runEngineLoop({
-                client: this.options.client,
-                executor: buildExecutor({ kind, ctx: toolCtx }),
-                systemPrompt: systemPromptFor(kind),
-                userPrompt: task.prompt,
-                tools: buildToolsSchema(kind),
-                budget,
-                personaSlug: personaSlugFor(kind),
-                hooks,
-                temperature: this.options.temperature ?? 0.2,
-                signal: ctx.signal,
+                // #24: fire TaskCompleted chain on the defensive path too.
+                await fireTaskCompletedOnce(1, 0, []);
+                yield {
+                    type: 'result',
+                    result: {
+                        status: 'failed',
+                        summary: 'engine loop returned no outcome',
+                        filesChanged: [],
+                        patchRefs: [],
+                        testsRun: [],
+                        risks: ['runEngineLoop resolved without an outcome value'],
+                        eventRefs: [],
+                    },
+                };
+                return;
+            }
+            // Translate the loop outcome into an EngineResult.
+            // `aborted` maps to `blocked` because the operator chose the
+            // outcome, same shape as budget_exhausted / tool_refused.
+            //
+            // PUGI-VERIFY-GATE: the verification gate runs AFTER this
+            // base mapping. When the agent ran verification commands and
+            // any exited non-zero, the loop's `completed` collapses to
+            // `failed` (the agent's claim of "done" is unverified). When
+            // the loop `completed` but no verification command ever ran,
+            // we surface `needs_verification` (CLI exit 2) so the operator
+            // sees the missing signal instead of false confidence. The
+            // gate is non-negotiable per the contract: `done` is reserved
+            // for `verified: true` outcomes.
+            const baseStatus = finalOutcome.status === 'completed'
+                ? 'done'
+                : finalOutcome.status === 'failed'
+                    ? 'failed'
+                    : 'blocked';
+            const filesChangedList = Array.from(filesChanged).sort();
+            const verification = computeVerificationOutcome({
+                ledger: session.verificationLedger,
+                baseStatus,
+                finalText: finalOutcome.finalText,
+                filesChanged: filesChangedList,
             });
-        }
-        catch (error) {
-            // Defensive — runEngineLoop wraps errors into status: failed, so
-            // this branch is only hit if the executor or hooks themselves
-            // throw uncaught. Surface as a failed result so the CLI exits
-            // non-zero rather than hanging.
-            const message = error instanceof Error ? error.message : String(error);
+            const status = verification.status;
+            const summaryPrefix = status === 'done'
+                ? ''
+                : finalOutcome.status === 'budget_exhausted'
+                    ? '[budget_exhausted] '
+                    : finalOutcome.status === 'tool_refused'
+                        ? '[plan_mode_refused] '
+                        : finalOutcome.status === 'aborted'
+                            ? '[operator_aborted] '
+                            : status === 'needs_verification'
+                                ? '[needs_verification] '
+                                : verification.unverifiedReason === 'verification_command_failed'
+                                    ? '[verification_failed] '
+                                    : '[failed] ';
+            appendSessionMirror(sessionEventsPath, {
+                type: 'outcome',
+                status: finalOutcome.status,
+                toolCallCount: finalOutcome.toolCallCount,
+                turnsUsed: finalOutcome.turnsUsed,
+                tokensUsed: finalOutcome.tokensUsed,
+                filesChanged: filesChangedList,
+                reason: finalOutcome.reason,
+            });
+            // #21: emit `dispatch_end` to the tenant-wide audit trail.
+            // When the loop tripped the per-command budget we ALSO emit a
+            // dedicated `budget_exhausted` row so a SOC query can filter on
+            // event type alone without parsing the `data.status` payload.
+            if (finalOutcome.status === 'budget_exhausted') {
+                writeAuditEvent({
+                    event: 'budget_exhausted',
+                    sessionId: session.id,
+                    workspaceRoot: root,
+                    data: {
+                        toolCallCount: finalOutcome.toolCallCount,
+                        turnsUsed: finalOutcome.turnsUsed,
+                        tokensUsed: finalOutcome.tokensUsed,
+                        reason: finalOutcome.reason ?? null,
+                    },
+                });
+            }
+            writeAuditEvent({
+                event: 'dispatch_end',
+                sessionId: session.id,
+                workspaceRoot: root,
+                data: {
+                    status: finalOutcome.status,
+                    toolCallCount: finalOutcome.toolCallCount,
+                    turnsUsed: finalOutcome.turnsUsed,
+                    tokensUsed: finalOutcome.tokensUsed,
+                    filesChangedCount: filesChangedList.length,
+                    reason: finalOutcome.reason ?? null,
+                },
+            });
+            // PR F (2026-06-05): Obsidian-style notes recorder. Writes three
+            // markdown surfaces (session journal, file concept notes, daily
+            // journal). Wrapped in its own try/catch internally — never
+            // throws, never blocks dispatch. Operator opt-out via
+            // `.pugi/settings.json::notes.enabled = false` or
+            // `PUGI_NOTES_DISABLE=1`.
+            recordSessionNotes({
+                workspaceRoot: root,
+                sessionId: session.id,
+                command: kind,
+                persona: personaSlugFor(kind),
+                brief: task.prompt,
+                status: finalOutcome.status,
+                toolCallCount: finalOutcome.toolCallCount,
+                turnsUsed: finalOutcome.turnsUsed,
+                tokensUsed: finalOutcome.tokensUsed,
+                filesChanged: filesChangedList,
+                startedAt: dispatchStartedAt,
+                endedAt: new Date().toISOString(),
+                reason: finalOutcome.reason ?? null,
+                config: { enabled: settings?.notes?.enabled !== false },
+            });
+            // #24 (CEO P1): TaskCompleted chain on the
+            // primary success path. `exitCode` maps to 0 for `completed`,
+            // 1 otherwise so chain hooks can branch on success vs blocked /
+            // failed / aborted via a single integer test.
+            await fireTaskCompletedOnce(finalOutcome.status === 'completed' ? 0 : 1, finalOutcome.toolCallCount, filesChangedList);
+            // PUGI-467: when the model finishes с tool_use-only turns (common
+            // на OSS coder models that emit no final assistant text after the
+            // last edit), `finalText` is empty even though work landed. Fall
+            // back к a synthesised summary derived from `filesChangedList` so
+            // the CLI never reports "no answer returned" when files were
+            // demonstrably modified.
+            //
+            // Order: finalText → reason → file-list synthesis → literal placeholder.
+            // Reason precedes synthesis so failure modes (budget_exhausted,
+            // tool_refused, aborted) preserve their explanation when files were
+            // also touched — operator must see WHY the loop terminated before
+            // the "what landed" hint. Synthesis only kicks in when there is no
+            // reason at all (pure tool_use-only completed turn).
+            const synthesisedFromFiles = finalOutcome.finalText.trim() === '' && filesChangedList.length > 0
+                ? `Updated ${filesChangedList.length} file(s): ${filesChangedList.slice(0, 5).join(', ')}${filesChangedList.length > 5 ? ` (+${filesChangedList.length - 5} more)` : ''}`
+                : '';
+            // PUGI-VERIFY-GATE: thread verification state into the risks
+            // array so a consumer reading only the legacy fields still
+            // gets a human-readable summary of what was not verified.
+            const baseRisks = finalOutcome.status === 'completed' && status === 'done'
+                ? []
+                : [finalOutcome.reason ?? `outcome=${finalOutcome.status}`];
+            if (verification.unverifiedReason && status !== 'done') {
+                baseRisks.push(`unverified: ${verification.unverifiedReason}`);
+            }
+            if (verification.regressionOwnershipDispute) {
+                baseRisks.push('regression_ownership_dispute: agent disclaimed ownership of failing verification');
+            }
             yield {
                 type: 'result',
                 result: {
-                    status: 'failed',
-                    summary: `engine loop crashed: ${message}`,
-                    filesChanged: [],
+                    status,
+                    summary: `${summaryPrefix}${finalOutcome.finalText || finalOutcome.reason || synthesisedFromFiles || 'no answer returned'}`,
+                    filesChanged: filesChangedList,
                     patchRefs: [],
                     testsRun: [],
-                    risks: [`unhandled error in engine adapter: ${message}`],
-                    eventRefs: [],
+                    risks: baseRisks,
+                    eventRefs: [
+                        `tool_calls=${finalOutcome.toolCallCount}`,
+                        `turns=${finalOutcome.turnsUsed}`,
+                        `tokens=${finalOutcome.tokensUsed}`,
+                        // `outcome=<status>` is a machine-readable echo so callers
+                        // (cli.ts plan exit code, cabinet UI) can distinguish
+                        // `budget_exhausted` from `tool_refused` without parsing
+                        // the human-readable summary prefix. Code Reviewer P2
+                        // retro: plan exit code previously collapsed
+                        // both blocked reasons into 0, which masked budget hits.
+                        `outcome=${finalOutcome.status}`,
+                        `session=${session.id}`,
+                        `ctx=${ctx.sessionId}`,
+                        `mirror=${sessionEventsPath}`,
+                        // PUGI-VERIFY-GATE: machine-readable verification echo so
+                        // downstream consumers (MCP wrapper, cabinet UI, audit
+                        // pipeline) can branch on the gate state without parsing
+                        // the new structured fields.
+                        `verified=${verification.verified}`,
+                        `verification_count=${verification.verificationCommands.length}`,
+                    ],
+                    verified: verification.verified,
+                    verificationCommands: verification.verificationCommands,
+                    verificationFailures: verification.verificationFailures,
+                    ...(verification.unverifiedReason !== undefined
+                        ? { unverifiedReason: verification.unverifiedReason }
+                        : {}),
+                    ...(verification.regressionOwnershipDispute
+                        ? { regressionOwnershipDispute: true }
+                        : {}),
                 },
             };
-            return;
         }
-        // Drain status buffer first so consumers see the chronological order.
-        for (const event of buffer)
-            yield event;
-        // Translate the loop outcome into an EngineResult.
-        // `aborted` (α6.9: operator cancelled mid-tool) maps to `blocked`
-        // because the operator chose the outcome, same shape as
-        // budget_exhausted / tool_refused.
-        const status = outcome.status === 'completed'
-            ? 'done'
-            : outcome.status === 'failed'
-                ? 'failed'
-                : 'blocked';
-        const summaryPrefix = outcome.status === 'completed'
-            ? ''
-            : outcome.status === 'budget_exhausted'
-                ? '[budget_exhausted] '
-                : outcome.status === 'tool_refused'
-                    ? '[plan_mode_refused] '
-                    : outcome.status === 'aborted'
-                        ? '[operator_aborted] '
-                        : '[failed] ';
-        const filesChangedList = Array.from(filesChanged).sort();
-        appendSessionMirror(sessionEventsPath, {
-            type: 'outcome',
-            status: outcome.status,
-            toolCallCount: outcome.toolCallCount,
-            turnsUsed: outcome.turnsUsed,
-            tokensUsed: outcome.tokensUsed,
-            filesChanged: filesChangedList,
-            reason: outcome.reason,
-        });
-        yield {
-            type: 'result',
-            result: {
-                status,
-                summary: `${summaryPrefix}${outcome.finalText || outcome.reason || 'no answer returned'}`,
-                filesChanged: filesChangedList,
-                patchRefs: [],
-                testsRun: [],
-                risks: outcome.status === 'completed'
-                    ? []
-                    : [outcome.reason ?? `outcome=${outcome.status}`],
-                eventRefs: [
-                    `tool_calls=${outcome.toolCallCount}`,
-                    `turns=${outcome.turnsUsed}`,
-                    `tokens=${outcome.tokensUsed}`,
-                    // `outcome=<status>` is a machine-readable echo so callers
-                    // (cli.ts plan exit code, cabinet UI) can distinguish
-                    // `budget_exhausted` from `tool_refused` without parsing
-                    // the human-readable summary prefix. Code Reviewer P2
-                    // retro 2026-05-23: plan exit code previously collapsed
-                    // both blocked reasons into 0, which masked budget hits.
-                    `outcome=${outcome.status}`,
-                    `session=${session.id}`,
-                    `ctx=${ctx.sessionId}`,
-                    `mirror=${sessionEventsPath}`,
-                ],
-            },
-        };
+        finally {
+            // r2 (triple-review P1): detach the abort listener so
+            // long REPL sessions sharing one AbortController across many
+            // run() invocations do not accumulate one listener per run on
+            // `ctx.signal`. Called on success, abort, and uncaught throw.
+            detachAbortListener?.();
+            // #24 (CEO P1): safety net — if `run()` threw
+            // BEFORE reaching any yield-result site, the chain still fires.
+            // `fireTaskCompletedOnce` is idempotent so the happy-path fire
+            // above wins. Exit code 1 because the throw path is by
+            // definition non-clean.
+            await fireTaskCompletedOnce(1, 0, []);
+        }
+    }
+}
+/**
+ * β3 streaming: translate one typed `EngineStreamEvent` from the
+ * adapter's internal queue into the SDK's lossier `EngineEvent` shape
+ * the public adapter contract exposes. The SDK contract only declares
+ * `status | result` today; richer events (`tool.start`, `thinking.delta`,
+ * etc.) collapse to a structured `status` message until the SDK widens
+ * the discriminated union (β3b — paired with an admin-api SSE schema
+ * bump so the wire format stays stable).
+ *
+ * The full typed payload is still available to richer consumers via
+ * `adapter.streamEmitter.on('event', ...)`. The CLI's TUI tool-stream
+ * pane consumes that emitter directly; this function is the safe
+ * bridge for legacy SDK consumers that only know `EngineEvent`.
+ */
+function streamEventToEngineEvent(stream) {
+    switch (stream.type) {
+        case 'status':
+            return { type: 'status', message: stream.message };
+        case 'tool.start':
+            return {
+                type: 'status',
+                message: `tool.start ${stream.name} call=${stream.callId} args=${stream.arguments.slice(0, 80)}${stream.arguments.length > 80 ? '...' : ''}`,
+            };
+        case 'tool.delta':
+            return {
+                type: 'status',
+                message: `tool.delta call=${stream.callId} chunk=${stream.chunk.slice(0, 120)}`,
+            };
+        case 'tool.end':
+            return {
+                type: 'status',
+                message: `tool.end call=${stream.callId} ok=${stream.ok} summary=${stream.summary.slice(0, 120)}`,
+            };
+        case 'thinking.start':
+            return { type: 'status', message: `thinking.start block=${stream.blockId}` };
+        case 'thinking.delta':
+            return {
+                type: 'status',
+                message: `thinking.delta block=${stream.blockId} chunk=${stream.chunk.slice(0, 120)}`,
+            };
+        case 'thinking.end':
+            return { type: 'status', message: `thinking.end block=${stream.blockId}` };
+        case 'text.delta':
+            return {
+                type: 'status',
+                message: `text.delta chunk=${stream.chunk.slice(0, 200)}`,
+            };
+        default: {
+            // Exhaustiveness — TS catches a missing variant at compile time.
+            const exhaustive = stream;
+            void exhaustive;
+            return { type: 'status', message: 'unknown stream event' };
+        }
     }
 }
 /**
@@ -311,7 +1212,14 @@ function extractPathArg(raw) {
     try {
         const parsed = JSON.parse(raw);
         if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-            const path = parsed.path;
+            const obj = parsed;
+            // Accept canonical `path` OR the peer-CLI-trained `filePath`
+            // alias so the filesChanged summary captures writes regardless of
+            // which key the model emitted. Without the alias the operator
+            // sees "Files modified: none" even when a write actually landed,
+            // because the dispatcher accepted the alias but the tracker did
+            // not (CEO live smoke).
+            const path = obj['path'] ?? obj['filePath'];
             if (typeof path === 'string' && path.length > 0)
                 return path;
         }
@@ -367,8 +1275,432 @@ function toCommandKind(kind) {
         return 'build';
     return kind;
 }
+/**
+ * β1 (audit E2) → β1a r1 (engine tag contract fix): map a
+ * CLI command kind to its dispatch tag.
+ *
+ * The admin-api controller (`pugi-engine.controller.ts`) routes per-tag
+ * to a model/persona pair via
+ * `apps/admin-api/src/pugi/routing/dispatch-tag.ts::DISPATCH_TAGS`. The
+ * closed `EngineChatTag` vocabulary is
+ * `classify | reason | codegen | summarize | vision` — note that
+ * `code`, `fix`, `plan`, `build`, `explain` (CLI command names) are NOT
+ * in this set.
+ *
+ * Before this fix `dispatchTagFor()` returned the CLI command names
+ * as-is and the runtime DTO rejected the payload with HTTP 400
+ * (`tag must be one of: classify, reason, codegen, summarize, vision`)
+ * before ever reaching the routing layer. Every `pugi code/fix/plan/
+ * build/explain` against the live runtime returned `failed: HTTP 400`.
+ *
+ * Mapping rationale (each row keeps the most informative `tag` value
+ * for cost telemetry / model selection):
+ *
+ *  - `code`, `fix`      → `codegen` (edits / diffs / patches)
+ *  - `build_task`/`build` → `codegen` + `budget_hint: 'max'`
+ *    (scaffolding hits the 30-call / 80k-token ceiling — give the
+ *    router permission to pick the largest model in the tier)
+ *  - `plan`             → `reason` (no mutations, long-form thought)
+ *  - `explain`          → `summarize` (read-only walkthrough)
+ *
+ * `priority: 'realtime'` for every command — Pugi is an interactive
+ * CLI; background dispatch is reserved for the cabinet's RAG ingest
+ * cron path. `budget_hint: 'std'` is the default for the cost-balanced
+ * router row; only `build_task` opts up to `'max'`.
+ */
+export function dispatchTagFor(kind) {
+    switch (kind) {
+        case 'code':
+        case 'fix':
+            return { tag: 'codegen', priority: 'realtime', budget_hint: 'std' };
+        case 'build':
+            // `build_task` on the engine task kind side is the heavy
+            // scaffolding lane — biggest budget envelope, biggest model
+            // permitted via `budget_hint: 'max'`.
+            return { tag: 'codegen', priority: 'realtime', budget_hint: 'max' };
+        case 'plan':
+            return { tag: 'reason', priority: 'realtime', budget_hint: 'std' };
+        case 'explain':
+            return { tag: 'summarize', priority: 'realtime', budget_hint: 'std' };
+        default: {
+            // Exhaustiveness check — `EngineCommandKind` is a closed union,
+            // so the switch above covers every case. If a new command kind
+            // is added the compiler flags this branch and the map must be
+            // extended. Fall back to `reason` as the most conservative
+            // routing choice so a future kind addition cannot accidentally
+            // unlock a write-heavy model lane.
+            const exhaustive = kind;
+            void exhaustive;
+            return { tag: 'reason', priority: 'realtime', budget_hint: 'std' };
+        }
+    }
+}
+/**
+ * PR E (2026-06-05): bind the engine client to a `CompactLlmCall`
+ * adapter so the auto-compact summarizer can issue one Anvil request
+ * per fire-threshold crossing. The adapter:
+ *
+ *   - packs the summarizer's system + user messages into the
+ *     `EngineLoopMessage` shape the SDK driver expects;
+ *   - forwards the operator-resolved model slug
+ *     (`autoCompact.summaryModel`, default `gemini-2.5-flash`);
+ *   - caps tokens at 500 + temperature 0.3 per the summarizer
+ *     contract — both passed in via `input` so the adapter stays
+ *     side-effect-free;
+ *   - swallows `client.send` errors and empty replies as `null` so
+ *     the upstream caller falls back to the deterministic stats
+ *     sentinel rather than wedging the engine loop on a transient
+ *     network blip.
+ *
+ * Abort signals re-throw via `client.send` propagation; the catch
+ * here only swallows non-abort errors so operator cancellation is
+ * still honoured.
+ */
+function buildSummarizerCall(client, personaSlug) {
+    return async (input) => {
+        const messages = [
+            { role: 'system', content: input.systemPrompt },
+            { role: 'user', content: input.userMessage },
+        ];
+        try {
+            const response = await client.send(messages, [], {
+                personaSlug,
+                model: input.model,
+                maxTokens: input.maxTokens,
+                temperature: input.temperature,
+                ...(input.signal ? { signal: input.signal } : {}),
+            });
+            // Summarizer call passes empty tools, so the model should
+            // always return `stop: 'text'`. Defensive: tool_use / error
+            // frames fall back to stats sentinel via null.
+            const content = response.stop === 'text' ? response.content.trim() : '';
+            return content.length > 0 ? content : null;
+        }
+        catch (err) {
+            if (err instanceof Error &&
+                (err.name === 'AbortError' || err.message.includes('aborted'))) {
+                throw err;
+            }
+            return null;
+        }
+    };
+}
 // The per-adapter `engineToolCallIds` Map lives on the
 // `NativePugiEngineAdapter` instance above — Code Reviewer P2 retro
-// 2026-05-23 lifted it off the module scope to prevent collisions
+// lifted it off the module scope to prevent collisions
 // under parallel adapter runs (cabinet UI + CLI sharing one process).
+/**
+ * β5a R5+R6: render a cwd path as either a workspace-root-relative
+ * string (when cwd is inside the workspace) or a `.` token (when cwd
+ * equals workspaceRoot). Falls back to the absolute cwd if it lives
+ * outside the workspace — the traverse loader already refuses to
+ * read off-tree files so the abs path is purely a breadcrumb for
+ * the SSE status line.
+ */
+function relativeOrAbsolute(workspaceRoot, cwd) {
+    const absRoot = resolve(workspaceRoot);
+    const absCwd = resolve(cwd);
+    if (absCwd === absRoot)
+        return '.';
+    const rel = absCwd.startsWith(absRoot + '/') ? absCwd.slice(absRoot.length + 1) : null;
+    return rel ?? absCwd;
+}
+/**
+ * helper — splice multiple ambient blocks onto a persona
+ * system prompt, dropping empty entries cleanly. The join character
+ * is `\n\n` so each block renders as a discrete paragraph the model
+ * can attend к without bleeding into its neighbour.
+ *
+ * Empty blocks return the base prompt unchanged — no leading
+ * separators, no trailing whitespace. Mirrors the original
+ * `ambientContextBlock ? ... : ...` shape so the single-block path
+ * before L28 stays byte-identical (prompt cache friendliness).
+ */
+export function composeSystemPrompt(blocks) {
+    const nonEmpty = blocks.map((b) => b.trim()).filter((b) => b.length > 0);
+    return nonEmpty.join('\n\n');
+}
+/**
+ * task #19 — boundary marker between cache-friendly
+ * static blocks (persona, capability matrix, tool schema) and dynamic
+ * per-session blocks (ambient PUGI.md, repo map, recent turns). The
+ * marker is a literal sentinel string the Anvil prefix-cache layer
+ * can locate to find the split point without parsing prompt semantics.
+ *
+ * Why: Anthropic's prompt cache works by hashing prefix bytes. Static
+ * content placed BEFORE dynamic content guarantees the cache hits on
+ * the common prefix even when the per-session tail varies. CC's
+ * proven pattern uses a single sentinel; Pugi adopts the same shape
+ * so cache infra is trivially interoperable.
+ *
+ * Output shape:
+ *  <staticBlock1>
+ *  <staticBlock2>
+ *  __PUGI_DYNAMIC_BOUNDARY__
+ *  <dynamicBlock1>
+ *  <dynamicBlock2>
+ *
+ * Empty blocks drop cleanly. If EITHER side ends up empty after the
+ * filter, the marker is omitted so the prompt has no orphan sentinel
+ * — caches treat "no boundary" as "everything is static / dynamic"
+ * with deterministic behaviour.
+ */
+export const PUGI_DYNAMIC_BOUNDARY = '__PUGI_DYNAMIC_BOUNDARY__';
+/**
+ * Sentinel-injection guard. The Anvil cache layer locates the split
+ * via grep на the literal `__PUGI_DYNAMIC_BOUNDARY__`. If either half
+ * already contains the sentinel — most likely via a PUGI.md fragment
+ * that documents the boundary mechanism itself, or через operator
+ * @import-pulled content — the grep would mis-split and corrupt the
+ * cache key. Hard-fail loud rather than silently emit a poisoned
+ * prompt. Operators who legitimately need the literal string in
+ * prompt context can rename their copy (e.g. `PUGI_DYNAMIC_BOUNDARY_LITERAL`)
+ * or use the runtime constant export directly via code.
+ */
+export class SentinelInjectionError extends Error {
+    side;
+    constructor(side) {
+        super(`Refusing to compose system prompt: ${side} side contains the ` +
+            `literal sentinel "${PUGI_DYNAMIC_BOUNDARY}". This would corrupt ` +
+            `the Anvil prefix-cache split. Rename the offending occurrence ` +
+            `или strip it before composing.`);
+        this.side = side;
+        this.name = 'SentinelInjectionError';
+    }
+}
+export function composeSystemPromptWithBoundary(staticBlocks, dynamicBlocks) {
+    const staticPart = composeSystemPrompt(staticBlocks);
+    const dynamicPart = composeSystemPrompt(dynamicBlocks);
+    // Sentinel-injection guard — refuse loud rather than mis-split cache.
+    if (staticPart.includes(PUGI_DYNAMIC_BOUNDARY)) {
+        throw new SentinelInjectionError('static');
+    }
+    if (dynamicPart.includes(PUGI_DYNAMIC_BOUNDARY)) {
+        throw new SentinelInjectionError('dynamic');
+    }
+    if (staticPart.length === 0)
+        return dynamicPart;
+    if (dynamicPart.length === 0)
+        return staticPart;
+    return `${staticPart}\n\n${PUGI_DYNAMIC_BOUNDARY}\n\n${dynamicPart}`;
+}
+/**
+ * Pugi backlog — resolve the effective model hint forwarded to
+ * the runtime. Precedence:
+ *
+ *  1. Operator-pinned `model` option (constructor arg) wins outright.
+ *     `pugi code --model foo` always takes precedence over the dial.
+ *  2. Intensity profile's `modelTag` resolves via
+ *     `PUGI_INTENSITY_MODEL_<TAG>` env (LIGHT / STANDARD / HEAVY).
+ *     Operators pin "what does 'standard' mean on this machine" via
+ *     env so the dial stays portable across providers.
+ *  3. Absent both => undefined; the admin-api falls back to the
+ *     persona's default model (the legacy pre-#163 path).
+ *
+ * Returns undefined when no hint is available so the runtime sees the
+ * absence of the field rather than an empty string — matches the
+ * `engineLoopServerRequestSchema.model.optional()` contract.
+ */
+export function resolveIntensityModel(operatorPin, profile) {
+    if (operatorPin !== undefined && operatorPin !== '')
+        return operatorPin;
+    if (!profile)
+        return undefined;
+    const envKey = `PUGI_INTENSITY_MODEL_${profile.modelTag.toUpperCase()}`;
+    const fromEnv = process.env[envKey];
+    if (fromEnv !== undefined && fromEnv !== '')
+        return fromEnv;
+    return undefined;
+}
+/**
+ * Backlog : expand `@import` directives across every
+ * file the `walkUpPugiMd` walker discovered. Each parent file's body
+ * is replaced with its post-import body (frontmatter stripped, import
+ * lines removed); imported children are appended to the hierarchy at
+ * the same `level` as their parent so the existing render order
+ * (shallow-to-deep) stays intact and the model sees the operator's
+ * `@import`-pulled rules in source order.
+ *
+ * Failures are localised: if a single file's load throws (cycle, hop
+ * cap, byte cap, etc.) we keep the walker's original body for that
+ * level and move on. Ambient context is enrichment, not a gate — one
+ * malformed CLAUDE.md must never break the engine boot.
+ */
+async function expandHierarchyWithImports(hierarchy, cwd) {
+    const out = [];
+    const home = osHomedir();
+    for (const file of hierarchy) {
+        try {
+            const rules = await loadRulesFile(file.path, {
+                cwd,
+                homedir: home,
+            });
+            // First rule is always the entry file itself. Replace the body
+            // with the post-expansion body so the rendered ambient block
+            // omits the `@import` directives but keeps everything else.
+            const head = rules[0];
+            if (head) {
+                out.push({
+                    ...file,
+                    content: head.body,
+                });
+            }
+            else {
+                out.push(file);
+            }
+            // Append imported children at the same level. They are not on
+            // disk in the parent dir, but the operator authored the link so
+            // surfacing them at the parent's specificity matches the
+            // ambient-context render contract.
+            for (let i = 1; i < rules.length; i += 1) {
+                const child = rules[i];
+                if (!child)
+                    continue;
+                out.push({
+                    path: child.path,
+                    content: child.body,
+                    level: file.level,
+                    source: file.source,
+                    truncated: false,
+                    rawBytes: Buffer.byteLength(child.body, 'utf8'),
+                });
+            }
+        }
+        catch {
+            // Localised failure: keep the walker's original body for this
+            // file and skip its imports. The next file in the hierarchy is
+            // tried independently.
+            out.push(file);
+        }
+    }
+    return out;
+}
+export function computeVerificationOutcome(input) {
+    const { ledger, baseStatus, finalText, filesChanged } = input;
+    const verificationCommands = ledger.map((entry) => entry.command);
+    const failures = ledger
+        .filter((entry) => entry.exitCode !== 0)
+        .map((entry) => ({
+        command: entry.command,
+        exitCode: entry.exitCode,
+        tailStderr: entry.tailStderr,
+    }));
+    // Verification PASS only when at least one verification call ran AND
+    // the most recent (chronologically last) verification exited zero.
+    // The "most recent" rule lets the agent intentionally retry a failed
+    // verification — only the final state matters.
+    const lastCall = ledger.length > 0 ? ledger[ledger.length - 1] : undefined;
+    const ranAny = ledger.length > 0;
+    const lastPassed = lastCall !== undefined && lastCall.exitCode === 0;
+    const anyFailed = failures.length > 0;
+    const verified = ranAny && lastPassed && !anyFailed;
+    // Status precedence:
+    //   verification_command_failed > base failure modes > needs_verification > done
+    // Override `baseStatus` ONLY when verification failed (the
+    // agent's loop may have ended `completed` while a test failed) OR
+    // when `baseStatus === 'done'` and no verification ran (the
+    // engine completed but produced no signal of correctness).
+    let status;
+    let unverifiedReason;
+    if (anyFailed) {
+        status = 'failed';
+        unverifiedReason = 'verification_command_failed';
+    }
+    else if (!ranAny && baseStatus === 'done') {
+        status = 'needs_verification';
+        unverifiedReason = 'no_verification_command_run';
+    }
+    else if (baseStatus !== 'done') {
+        status = baseStatus;
+        if (!verified)
+            unverifiedReason = 'verification_inconclusive';
+    }
+    else {
+        status = 'done';
+    }
+    // Regression ownership dispute heuristic. Only meaningful when a
+    // verification command failed; keep the predicate simple and
+    // documented so a future reviewer can audit the false-positive
+    // surface.
+    let regressionOwnershipDispute = false;
+    if (anyFailed && filesChanged.length > 0 && finalText !== '') {
+        const lower = finalText.toLowerCase();
+        const disputed = REGRESSION_DISPUTE_PHRASES.some((phrase) => lower.includes(phrase));
+        if (disputed && agentTouchedFailingModule(filesChanged, failures)) {
+            regressionOwnershipDispute = true;
+        }
+    }
+    return {
+        status,
+        verified,
+        verificationCommands,
+        verificationFailures: failures,
+        ...(unverifiedReason !== undefined ? { unverifiedReason } : {}),
+        regressionOwnershipDispute,
+    };
+}
+/**
+ * Predicate: at least one mutated file shares a top-level module
+ * directory with a path referenced in any verification failure's
+ * stderr tail. The rule is intentionally loose ("same dir + same
+ * basename without extension or .test./.spec. infix") so it
+ * catches the typical `src/foo.ts` ↔ `src/foo.test.ts` pairing
+ * without overfitting to one test runner's stack-trace format.
+ *
+ * Implementation: extract every `src/...`-shaped path mention from
+ * each failure's stderr tail, then check whether ANY mutated file
+ * shares a module key with ANY mentioned path. The module key
+ * strips the trailing filename's extension AND any `.test.` /
+ * `.spec.` infix so the pair resolves to the same key.
+ */
+function agentTouchedFailingModule(filesChanged, failures) {
+    const stderrJoined = failures.map((f) => f.tailStderr).join('\n');
+    if (stderrJoined === '')
+        return false;
+    // Match common test-runner path shapes: `src/foo/bar.ts`,
+    // `apps/x/test/y.spec.ts`, `packages/z/baz.test.ts`. Not
+    // exhaustive — false negatives are acceptable here because the
+    // predicate's job is to FLAG dispute, not enforce it.
+    const pathMentions = new Set();
+    const pathRegex = /(?:^|[\s(])((?:src|app|apps|test|tests|lib|packages)\/[\w./-]+\.[a-zA-Z]+)/g;
+    for (const match of stderrJoined.matchAll(pathRegex)) {
+        const captured = match[1];
+        if (typeof captured === 'string' && captured.length > 0) {
+            pathMentions.add(captured);
+        }
+    }
+    if (pathMentions.size === 0)
+        return false;
+    // Module key strips the trailing filename's extension (and any
+    // `.test.` / `.spec.` infix) so `src/existing.ts` and
+    // `src/existing.test.ts` resolve to the same key. Keep the full
+    // directory path plus the bare basename (no ext) — this catches
+    // the typical `foo.ts` ↔ `foo.test.ts` pairing in the same dir
+    // without overfitting to one test-runner convention.
+    const moduleKey = (p) => {
+        const segments = p.split('/').filter(Boolean);
+        if (segments.length === 0)
+            return '';
+        const lastIndex = segments.length - 1;
+        const bareLast = segments[lastIndex]
+            .replace(/\.(spec|test)\./, '.')
+            .replace(/\.[a-zA-Z][a-zA-Z0-9]*$/, '');
+        const dir = segments.slice(0, lastIndex).join('/');
+        return dir === '' ? bareLast : `${dir}/${bareLast}`;
+    };
+    const failingModuleKeys = new Set();
+    for (const mention of pathMentions) {
+        const key = moduleKey(mention);
+        if (key !== '')
+            failingModuleKeys.add(key);
+    }
+    if (failingModuleKeys.size === 0)
+        return false;
+    for (const file of filesChanged) {
+        const key = moduleKey(file);
+        if (failingModuleKeys.has(key))
+            return true;
+    }
+    return false;
+}
 //# sourceMappingURL=native-pugi.js.map