comisai 1.0.41 → 1.0.44

package/node_modules/@comis/agent/dist/bridge/pi-event-bridge.js

@@ -10,20 +10,195 @@
  * @module
  */
 import { shouldCompact } from "@earendil-works/pi-coding-agent";
-import { formatSessionKey, sanitizeLogString, systemNowMs, } from "@comis/core";
+import { formatSessionKey, sanitizeLogString, fingerprint, systemNowMs, systemDateFrom, tryGetContext, redactValue, getToolMetadata, 
+// Classification data for "Tool X not found" enrichment.
+// @comis/agent has no @comis/skills edge in the architecture graph
+// (agent = [shared, core, observability, scheduler]). Import ONLY from @comis/core.
+SUB_AGENT_TOOL_DENYLIST, toolReachableGroups, } from "@comis/core";
+import { buildTraceMetadata } from "@comis/observability";
 import { suppressError } from "@comis/shared";
 import { randomUUID } from "node:crypto";
 import { resolveModelPricing } from "@comis/core";
 import { getCacheProviderInfo } from "../executor/cache-usage-helpers.js";
 import { sanitizeMcpToolNameForAnalytics } from "../executor/cache-detection/index.js";
 import { classifyError } from "../executor/error-classifier.js";
+import { getSessionPromptSkillLocations, getSessionPromptTopicMatchedSkills } from "../executor/prompt-assembly.js";
+import { suggestClosestTool } from "./tool-name-suggest.js";
+import { toolFailureHint } from "./tool-failure-hint.js";
+import { checkSpendCeiling } from "../budget/budget-guard.js";
 import { extractPlanFromResponse } from "../planner/plan-extractor.js";
 import { extractMcpServerName } from "@comis/shared";
 import { classifyMcpErrorType, sanitizeToolArgs, extractErrorText } from "./bridge-event-handlers.js";
+/**
+ * Bracketed `[error_code]` prefixes that mean the tool's OWN IO failed (disk,
+ * parse) — the tool, not the model, is at fault → `internal`. Every other
+ * structured `[code]` is the model's input/policy rejection → `validation`.
+ */
+const TOOL_ERROR_INTERNAL_CODES = new Set([
+    "read_error",
+    "write_error",
+    "grep_error",
+    "dir_create_failed",
+    "pdf_error",
+]);
+/**
+ * First snake_case bracketed code ANYWHERE in errorText. The errorText we log is
+ * the JSON-stringified tool RESULT, so the code sits inside `.content[].text`,
+ * NOT at offset 0 — search anywhere (mirrors {@link toolFailureHint}). The
+ * `≥ one underscore` requirement avoids matching `[i]` / `[error]` / array
+ * indices.
+ */
+const BRACKETED_TOOL_ERROR_CODE = /\[([a-z]+(?:_[a-z]+)+)\]/;
+/**
+ * Raw Node errno prefixes (no bracketed `[code]`) that can ONLY be a wrong-path-
+ * TYPE usage error: the model gave a DIRECTORY to a file op (`EISDIR`) or a file
+ * where a dir was expected (`ENOTDIR`). These are unambiguously the model's bad
+ * input → `validation`, NOT a `dependency` outage. Deliberately EXCLUDES the
+ * context-dependent errnos `ENOENT`/`EACCES` — an exec `ENOENT` (spawning an
+ * uninstalled `claude`) is a genuine missing-binary dependency, so those stay on
+ * the dependency fallback. (Live r3terse 2026-06-30: the agent `read` a directory
+ * → `EISDIR: illegal operation on a directory, read` surfaced as
+ * errorKind:"dependency", misdirecting an operator at a missing package.)
+ */
+const NODE_PATH_TYPE_USAGE_ERRNO = /\b(?:EISDIR|ENOTDIR):/;
+/**
+ * Classify a tool failure's errorKind when the SDK reported `isError: true`
+ * from the start (i.e., `toolSuccess === false` BEFORE the exitCode branch
+ * flips it), so the `tool:executed` event carries an actionable errorKind for
+ * trajectory + alerting + the channel activity label.
+ *
+ * A structured bracketed `[code]` means the call REACHED the tool and the tool
+ * rejected it — that is `validation` (the model's input/policy) or, for the IO
+ * codes above, `internal` (the tool's own failure). It is NEVER a `dependency`:
+ * "dependency" is reserved for a genuinely external/MCP/transport failure, which
+ * is exactly the no-structured-code fallback.
+ *
+ * Pre-fix this returned "dependency" for everything except an `^`-anchored
+ * `[invalid_value]` — and since errorText is JSON-wrapped, that anchor never
+ * matched. A built-in `edit` returning `[text_not_found]` therefore surfaced to
+ * a chat channel as "❌ dependency" (live-UAT Telegram onboarding, 2026-06-21).
+ */
+export function classifyToolError(_toolName, errorText) {
+    const code = errorText ? BRACKETED_TOOL_ERROR_CODE.exec(errorText)?.[1] : undefined;
+    if (code !== undefined) {
+        return TOOL_ERROR_INTERNAL_CODES.has(code) ? "internal" : "validation";
+    }
+    // A raw Node wrong-path-type errno (EISDIR/ENOTDIR) is the model's bad input,
+    // not an external dependency — classify as validation (the bad-argument family).
+    if (errorText !== undefined && NODE_PATH_TYPE_USAGE_ERRNO.test(errorText)) {
+        return "validation";
+    }
+    // No structured code → a genuinely external (MCP / transport / unknown) failure.
+    return "dependency";
+}
+import * as os from "node:os";
+import * as pathModule from "node:path";
+import { appendSessionIndexEntry } from "@comis/observability";
 import { createBridgeMetrics, buildBridgeResult } from "./bridge-metrics.js";
 import { drainAt } from "../executor/drain-helper.js";
-import { checkStepLimit, emitStepLimitAbort, checkBudgetLimit, emitBudgetAbort, checkBudgetTrajectory, checkContextWindow, emitContextAbort, checkCircuitBreaker, emitCircuitBreakerAbort } from "./bridge-safety-controls.js";
+import { checkStepLimit, emitStepLimitAbort, checkLoopLimit, emitLoopAbort, checkBudgetLimit, emitBudgetAbort, checkBudgetTrajectory, checkContextWindow, emitContextAbort, checkCircuitBreaker, emitCircuitBreakerAbort, buildAbortRedirectMessage, checkSpendLimit, emitSpendAbort } from "./bridge-safety-controls.js";
 import { computeThinkingBlockHashes, diffThinkingBlocksAgainstPersisted, WIRE_DIFF_HINT_FILE_MISSING, WIRE_DIFF_HINT_NOT_FOUND, } from "./thinking-block-hash-invariant.js";
+import { isContextExhaustionErrorMessage } from "../context-engine/errors.js";
+// ---------------------------------------------------------------------------
+// Module-level one-shot latches
+// ---------------------------------------------------------------------------
+/**
+ * One-shot latch gating the SDK-breakdown notice. The notice
+ * states that pi-ai does NOT expose `usage.cacheCreation.{shortTtl,longTtl}`
+ * and that Comis estimates the per-TTL split via marker counting. Previously
+ * the bridge logged this fact at DEBUG on every turn that wrote
+ * cache tokens, stacking thousands of identical lines under normal load.
+ *
+ * The notice now fires exactly once per daemon process (at the first
+ * `createPiEventBridge` construction) at INFO. The flag is module-scoped
+ * so multiple bridge constructions across the daemon's lifetime share it.
+ */
+let _sdkBreakdownNoticeEmitted = false;
+/**
+ * Test-only hook to reset the one-shot SDK-breakdown notice flag. Used
+ * by pi-event-bridge.test.ts to assert "fires exactly once" across
+ * multiple bridge constructions within a single test. NOT a public API —
+ * production code MUST NOT call this.
+ */
+export function __resetSdkBreakdownNoticeForTest() {
+    _sdkBreakdownNoticeEmitted = false;
+}
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Tool-not-found enrichment helpers
+// ---------------------------------------------------------------------------
+/** Matches the SDK's exact "Tool not found" error format (agent-loop.js:356):
+ *  `Tool ${toolCall.name} not found` */
+const NOT_FOUND_RE = /^Tool (\S+) not found$/;
+/**
+ * Classify a tool that was not found during sub-agent execution.
+ * Uses SUB_AGENT_TOOL_DENYLIST and toolReachableGroups from @comis/core.
+ * Returns enriched hint text that replaces the opaque SDK error.
+ *
+ * @comis/agent has no @comis/skills edge — do NOT import TOOL_PROFILES from @comis/skills.
+ */
+function classifyUnreachableTool(toolName, activeGroups) {
+    if (SUB_AGENT_TOOL_DENYLIST.has(toolName)) {
+        return `Tool '${toolName}' is denied to ALL sub-agents — the parent must perform this step.`;
+    }
+    const broader = toolReachableGroups(toolName).filter((p) => !activeGroups.includes(p));
+    // When no profile contains the tool, suggest only 'full' — 'supervisor' does not
+    // contain generic tools like web_fetch/browser/sessions_spawn, so it would fail again.
+    const suggestion = broader.length > 0 ? broader.join("' | '") : "full";
+    return (`Tool '${toolName}' is outside this sub-agent's profile. ` +
+        `Re-spawn with tool_groups:['${suggestion}'].`);
+}
+/**
+ * F-OBS-2 (30uc-20260624): a CONTENT-FREE grounding summary of a web_search /
+ * web_fetch result for the trajectory `tool.result` — result count + source
+ * HOSTS only. NEVER titles, snippets, full URLs (path/query), or bodies. Lets a
+ * "grounded in fetched results" predicate be verified from `comis explain` /
+ * trajectory without a DEBUG daemon-log grep (the load-bearing-evidence-was-
+ * DEBUG-only obs-loop trigger). Returns `undefined` for any other tool or an
+ * unparseable result, so the `tool:executed` emit is unchanged for everything else.
+ *
+ * The tool return is an `AgentToolResult`; the structured payload rides `.details`
+ * (the same field the success classifier reads at the call site), with a direct-
+ * shape fallback. Only `host` is taken from each URL (`new URL(...).host`), never
+ * the path or query — so no fetched-content identifiers leak onto the trajectory.
+ */
+export function extractWebResultMetadata(toolName, result) {
+    if (toolName !== "web_search" && toolName !== "web_fetch")
+        return undefined;
+    if (typeof result !== "object" || result === null)
+        return undefined;
+    const top = result;
+    const payload = (top.details && typeof top.details === "object" ? top.details : top);
+    const hostOf = (u) => {
+        if (typeof u !== "string" || u.length === 0)
+            return undefined;
+        try {
+            return new URL(u).host;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    if (toolName === "web_search") {
+        const results = Array.isArray(payload.results) ? payload.results : undefined;
+        if (results === undefined)
+            return undefined;
+        const domains = new Set();
+        for (const item of results) {
+            const h = hostOf(item?.url);
+            if (h !== undefined)
+                domains.add(h);
+        }
+        return { resultCount: results.length, domains: [...domains].sort() };
+    }
+    // web_fetch: a single page → resultCount 1 + the fetched host (final wins).
+    const host = hostOf(payload.finalUrl) ?? hostOf(payload.url);
+    if (host === undefined)
+        return undefined;
+    return { resultCount: 1, domains: [host] };
+}
 // ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------
@@ -40,9 +215,98 @@ import { computeThinkingBlockHashes, diffThinkingBlocksAgainstPersisted, WIRE_DI
  * - compaction_end -> INFO/WARN log + compaction:flush event
  * - error (from turn_end with stopReason) -> circuit breaker failure
  */
+/**
+ * Tool self-grade convention (PD-OUTCOME-1, codex package-delivery live-test).
+ *
+ * A tool may report its own SEMANTIC outcome via an explicit
+ * `{ graded: true, outcome: "success" | "failure" }` envelope, so an action that
+ * logically FAILED while the CALL returned cleanly (no SDK `isError` — e.g. an MCP
+ * delivery to a non-existent recipient, a search that found nothing, a rejected write)
+ * is recorded as a failure rather than a transport success. The learning loop then
+ * credits/promotes a skill on the real task outcome, not on "the tool returned".
+ *
+ * The envelope is read from BOTH shapes a result can arrive in:
+ *  1. a top-level structured object `{ graded, outcome }`, and
+ *  2. the MCP wire shape `{ content: [{ type:"text", text:"<json>" }], isError }` — the
+ *     JSON-stringified result sits inside `content[].text` (see the :79 note above).
+ *
+ * OPT-IN by design: only an explicit `graded:true` result is honored, so an arbitrary
+ * result is NEVER false-flagged (the c53ab0f no-false-flag invariant). Total + bounded:
+ * only text blocks are parsed, length-capped, with a cheap `"graded"` pre-filter before
+ * `JSON.parse`, and a non-JSON / non-object / unknown-`outcome` input returns `undefined`.
+ */
+export function extractSelfGradedOutcome(result) {
+    if (result === null || typeof result !== "object")
+        return undefined;
+    const readEnvelope = (o) => o.graded === true && (o.outcome === "success" || o.outcome === "failure") ? o.outcome : undefined;
+    // 1. Top-level structured envelope.
+    const top = readEnvelope(result);
+    if (top !== undefined)
+        return top;
+    // 2. MCP shape: the result text sits in content[].text. Comis SECURITY-WRAPS untrusted
+    //    MCP content (wrapExternalContent: a "SECURITY NOTICE…" preamble + <<<UNTRUSTED_…>>>
+    //    markers around the payload), so a whole-text JSON.parse FAILS — the envelope is
+    //    EMBEDDED after the preamble. parseEmbeddedJsonObject handles both the wrapped and
+    //    the bare case (verified live, PD-OUTCOME-1: the preamble/markers carry no braces, so
+    //    the first-'{'…last-'}' slice is the JSON payload).
+    const content = result.content;
+    if (!Array.isArray(content))
+        return undefined;
+    for (const block of content) {
+        if (block === null || typeof block !== "object")
+            continue;
+        const text = block.text;
+        // Cheap guards: only a bounded text block that even mentions the marker is parsed.
+        if (typeof text !== "string" || text.length === 0 || text.length > 16384)
+            continue;
+        if (!text.includes('"graded"'))
+            continue;
+        const parsed = parseEmbeddedJsonObject(text);
+        if (parsed !== undefined) {
+            const r = readEnvelope(parsed);
+            if (r !== undefined)
+                return r;
+        }
+    }
+    return undefined;
+}
+/**
+ * Parse a JSON OBJECT out of `text`: the whole string first (a bare result), else the
+ * `{`…`}` slice (a security-wrapped payload whose preamble + markers carry no braces).
+ * Returns the parsed object or `undefined` (non-JSON / array / scalar). Total + bounded.
+ */
+function parseEmbeddedJsonObject(text) {
+    const tryParse = (s) => {
+        try {
+            const p = JSON.parse(s);
+            return p !== null && typeof p === "object" && !Array.isArray(p) ? p : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const whole = tryParse(text);
+    if (whole !== undefined)
+        return whole;
+    const lb = text.indexOf("{");
+    const rb = text.lastIndexOf("}");
+    return lb >= 0 && rb > lb ? tryParse(text.slice(lb, rb + 1)) : undefined;
+}
 export function createPiEventBridge(deps) {
     // Internal accumulation state (managed by bridge-metrics module)
     const m = createBridgeMetrics();
+    // One-shot SDK-breakdown notice. Fires exactly once per
+    // daemon process — the latch is module-scoped so multiple bridge
+    // constructions (per-execution / test harnesses) share it. The notice
+    // is INFO because it's a one-time operator-relevant fact, not a
+    // recurring DEBUG signal.
+    if (!_sdkBreakdownNoticeEmitted) {
+        _sdkBreakdownNoticeEmitted = true;
+        deps.logger.info({
+            errorKind: "dependency",
+            hint: "pi-ai SDK does not expose usage.cacheCreation per-TTL breakdown; Comis estimates the 5m/1h split via marker counting. Estimate accuracy may drift if cache-write composition skews from the marker-count assumption.",
+        }, "pi-ai SDK does not expose cacheCreation per-TTL breakdown; Comis estimates via marker counting");
+    }
     const listener = (event) => {
         try {
             switch (event.type) {
@@ -60,7 +324,12 @@ export function createPiEventBridge(deps) {
                         }
                         if (deps.onDelta && typeof ame.delta === "string") {
                             try {
-                                deps.onDelta(ame.delta);
+                                // SA1: forward the SDK's typed delta kind so the consumer can gate
+                                // accumulation to kind==='text' only. thinking_delta is forwarded
+                                // with kind='thinking' so the consumer can still refresh the typing
+                                // TTL (proves the agent is alive during extended reasoning phases)
+                                // without the chain-of-thought reaching the channel.
+                                deps.onDelta(ame.delta, ame.type === "text_delta" ? "text" : "thinking");
                             }
                             catch {
                                 // Never abort agent due to streaming callback error
@@ -70,6 +339,90 @@ export function createPiEventBridge(deps) {
                     break;
                 }
                 // -----------------------------------------------------------------
+                // Agent run lifecycle
+                //
+                // pi-mono emits `agent_start` at the top of each AgentSession.send()
+                // and `agent_end` after the entire agentic loop completes. The
+                // trajectory writer subscribes to the corresponding EventMap
+                // events to bracket every run. session.started is the FIRST
+                // trajectory record; session.ended is the LAST (plus the
+                // trace.truncated sentinel from flushAndClose if dropped events
+                // accumulated).
+                // -----------------------------------------------------------------
+                case "agent_start": {
+                    if (m.agentStartMs === undefined) {
+                        m.agentStartMs = systemNowMs();
+                    }
+                    // Suppress per-turn re-emits: session.started fires ONCE per
+                    // session (not per pi-mono turn). The bridge is
+                    // per-turn, so consult the session-scoped trajectoryRegistry
+                    // latch — it survives across turns and resets only when the
+                    // session is destroyed (or the daemon restarts and rebuilds
+                    // the registry fresh). When the registry is absent
+                    // (legacy/test callers), fall through to the legacy
+                    // unconditional emit so existing harnesses keep working.
+                    const formattedKey = formatSessionKey(deps.sessionKey);
+                    if (deps.trajectoryRegistry?.hasSessionStartedBeenEmitted(formattedKey) === true) {
+                        break;
+                    }
+                    // channelType lives on RequestContext (AsyncLocalStorage); fall
+                    // back to "" when running outside a scope (e.g., direct test
+                    // invocation). Trajectory consumers tolerate the empty case.
+                    const channelType = tryGetContext()?.channelType ?? "";
+                    deps.eventBus.emit("session:started", {
+                        agentId: deps.agentId,
+                        sessionKey: formattedKey,
+                        traceId: tryGetContext()?.traceId ?? deps.executionId,
+                        channelType,
+                        channelId: deps.channelId,
+                        timestamp: systemNowMs(),
+                    });
+                    deps.trajectoryRegistry?.markSessionStarted(formattedKey);
+                    // Append session_started to the date-rolled session index JSONL.
+                    // Co-located with the session:started bus emit + trajectoryRegistry
+                    // latch so session_started fires exactly once per session (same
+                    // guard).
+                    appendSessionIndexEntry(deps.dataDir ?? pathModule.join(os.homedir(), ".comis"), {
+                        traceSchema: "comis-session-index",
+                        schemaVersion: 1,
+                        event: "session_started",
+                        ts: systemDateFrom(systemNowMs()).toISOString(),
+                        sessionId: formattedKey,
+                        sessionKey: formattedKey,
+                        channelType,
+                        channelId: deps.channelId ?? "",
+                        agentId: deps.agentId,
+                        traceIds: [deps.executionId],
+                        source: "runtime", // D9 provenance stamp (production rows)
+                    });
+                    // Emit the trace.metadata lifecycle envelope directly via the
+                    // recorder — no bus event source.
+                    if (deps.runtimeSnapshot !== undefined) {
+                        const recorder = deps.trajectoryRegistry?.getRecorder?.(formattedKey);
+                        if (recorder != null) {
+                            recorder.recordEvent("trace.metadata", buildTraceMetadata(deps.runtimeSnapshot));
+                        }
+                    }
+                    break;
+                }
+                case "agent_end": {
+                    // session:ended is NO LONGER emitted from agent_end —
+                    // "(session) ended" is a session-destroy semantic, not
+                    // per-turn. The emit moved to
+                    // ComisSessionManager.destroySession. Per-turn duration metrics
+                    // are surfaced via observability:token_usage → model.completed,
+                    // which already carries durationMs.
+                    //
+                    // We preserve the m.agentStartMs / m.lastStopReason reads since
+                    // other accumulators may rely on these — only the eventBus
+                    // emit is removed.
+                    const startMs = m.agentStartMs ?? systemNowMs();
+                    const durationMs = systemNowMs() - startMs;
+                    void durationMs;
+                    void (m.lastStopReason ?? "end");
+                    break;
+                }
+                // -----------------------------------------------------------------
                 // Tool execution lifecycle
                 // -----------------------------------------------------------------
                 case "tool_execution_start": {
@@ -98,13 +451,29 @@ export function createPiEventBridge(deps) {
                             // Never fail execution due to arg snapshot error
                         }
                     }
+                    // Stash the RAW args so the paired tool:executed emit can forward
+                    // redacted params. Redaction happens at the emit, not here.
+                    if (toolEvent.args !== undefined) {
+                        m.toolRawArgs.set(toolEvent.toolCallId, toolEvent.args);
+                    }
+                    // Thread redacted params + an `action` field onto tool:started.
+                    // redactValue is the only sanctioned path — secrets/PII/absolute paths
+                    // are masked BEFORE the emit crosses the bus. homeDir (when wired)
+                    // compacts $HOME→~ for all consumers, not just the re-redacting
+                    // activity renderer.
+                    const startedRedactedParams = redactValue(toolEvent.args, { homeDir: deps.homeDir }).value;
+                    const startedAction = startedRedactedParams && typeof startedRedactedParams.action === "string"
+                        ? startedRedactedParams.action
+                        : undefined;
                     deps.eventBus.emit("tool:started", {
                         toolName: toolEvent.toolName,
                         toolCallId: toolEvent.toolCallId,
                         timestamp: systemNowMs(),
                         agentId: deps.agentId,
                         sessionKey: formatSessionKey(deps.sessionKey),
-                        traceId: deps.executionId,
+                        traceId: tryGetContext()?.traceId ?? deps.executionId,
+                        ...(startedRedactedParams !== undefined && { params: startedRedactedParams }),
+                        ...(startedAction !== undefined && { action: startedAction }),
                     });
                     deps.logger.debug({ toolName: toolEvent.toolName, ...(argsPreview && { argsPreview }) }, argsPreview ? `Tool execution started: ${toolEvent.toolName}(${argsPreview})` : "Tool execution started");
                     break;
@@ -126,23 +495,220 @@ export function createPiEventBridge(deps) {
                     // The SDK only sets isError on thrown exceptions, so we also inspect the result.
                     let toolSuccess = !endEvent.isError;
                     let toolErrorKind;
-                    if (toolSuccess && endEvent.result != null) {
+                    // D1 failure-classification provenance (P1): assigned AT each
+                    // mutation point (never a post-hoc switch — by the WARN site
+                    // toolSuccess is just `false` and the source is lost). transportOk
+                    // is derived from classifiedFailureBy at the sinks (sdk_iserror ⇒
+                    // transport failed ⇒ false; exit-code/detector/mcp-content ⇒ true).
+                    let classifiedFailureBy;
+                    let matchedRule;
+                    let matchedToken;
+                    let httpStatus;
+                    // transportOk tracks the SDK/transport signal itself: false ONLY when
+                    // the SDK reported isError (the call/transport failed). An exit-code,
+                    // detector, or MCP-content failure means the call RETURNED and the
+                    // content was a failure → transportOk stays true. This is the
+                    // self-evident-misclassification tell: a transportOk:true failure
+                    // with classifiedFailureBy:'failure_detector' means "we matched a
+                    // structured field, the transport was fine". (OQ A3 — derived from
+                    // the flip source, NOT the refined classifiedFailureBy label, so the
+                    // A1 MCP-refinement of an SDK-isError failure stays transportOk:false.)
+                    const transportOk = !endEvent.isError;
+                    // :591 — SDK isError flip (the transport/call itself errored).
+                    if (!toolSuccess)
+                        classifiedFailureBy = "sdk_iserror";
+                    // Tool metadata, read ONCE — gates the exit-code heuristic AND the failureDetector hook.
+                    const toolMeta = getToolMetadata(endEvent.toolName);
+                    // The exit-code heuristic flags a non-zero `details.exitCode` as a tool failure — but
+                    // ONLY when the exit code is the TOOL's own outcome (exec/process). The terminal
+                    // driver's perception tools (status/read/wait) surface the DRIVEN SESSION's exit code
+                    // as an informational datum (`exitCodeIsDrivenSession`); a driven program exiting
+                    // non-zero there does NOT mean the tool failed — the tool SUCCEEDED in reporting it.
+                    // Skip flagged tools (real-VPS 2026-06-16: a bash `exit 1` misclassified a perfectly
+                    // successful terminal_session_status as success:false / classifiedFailureBy:exit_code).
+                    if (toolSuccess && endEvent.result != null && toolMeta?.exitCodeIsDrivenSession !== true) {
                         const details = endEvent.result?.details;
                         if (details != null &&
                             typeof details.exitCode === "number" &&
                             details.exitCode !== 0) {
                             toolSuccess = false;
                             toolErrorKind = "dependency";
+                            classifiedFailureBy = "exit_code"; // exec non-zero exit — call returned, content failed
                         }
                     }
+                    // §16.10: run the tool's failureDetector hook BEFORE the
+                    // tool:executed emit, so observability never sees the raw result.
+                    // The detector is pure + synchronous; it lets a tool flag a
+                    // logically-failed result the SDK reported as success. A THROWING
+                    // detector is caught — the original success is preserved and a WARN
+                    // is logged with errorKind:"internal" (the result is never leaked).
+                    // NOTE: this wires the hook SEAM; per-tool detector bodies are
+                    // authored separately.
+                    {
+                        const detector = toolMeta?.failureDetector;
+                        if (detector !== undefined) {
+                            try {
+                                const detected = detector(endEvent.result, endEvent.isError);
+                                if (detected !== false && detected !== undefined) {
+                                    // D2 single-chokepoint no-false-flag guard (P2): the codified
+                                    // c53ab0f invariant, generalized to ALL detectors here at the
+                                    // ONE consumption site (not per-detector, so it also covers
+                                    // future detectors). A status:200 + no-string-error result is
+                                    // a structural success and must NEVER be flagged a failure.
+                                    const r = endEvent.result;
+                                    const looksLikeSuccess = r !== null &&
+                                        typeof r === "object" &&
+                                        r.status === 200 &&
+                                        typeof r.error !== "string";
+                                    if (looksLikeSuccess) {
+                                        // Refuse the flag (preserve success) + observable WARN.
+                                        // The guard NEVER aborts the turn — it mirrors the
+                                        // catch below, which also preserves the success outcome.
+                                        deps.logger.warn({
+                                            submodule: "bridge.failure-detector",
+                                            toolName: endEvent.toolName,
+                                            toolCallId: endEvent.toolCallId,
+                                            errorKind: "internal",
+                                            hint: "failureDetector flagged a status:200/no-error result; refusing the flag (c53ab0f invariant). Fix the detector — it must classify off structured failure fields only.",
+                                        }, "failureDetector no-false-flag guard tripped");
+                                        // Do NOT flip toolSuccess; do NOT set classifiedFailureBy.
+                                    }
+                                    else {
+                                        toolSuccess = false;
+                                        toolErrorKind =
+                                            (typeof detected === "object" && detected !== null
+                                                ? detected.errorKind
+                                                : undefined) ?? toolErrorKind ?? "internal";
+                                        classifiedFailureBy = "failure_detector";
+                                        if (typeof detected === "object" && detected !== null) {
+                                            // matchedRule/matchedToken are verdict provenance (P2).
+                                            // matchedToken is free-text untrusted tool output — it is
+                                            // sanitized+bounded at BOTH sinks (WARN + emit), never here.
+                                            matchedRule = detected.matchedRule;
+                                            matchedToken = detected.matchedToken;
+                                        }
+                                        const status = r?.status;
+                                        if (typeof status === "number")
+                                            httpStatus = status;
+                                    }
+                                }
+                            }
+                            catch (detectorError) {
+                                deps.logger.warn({
+                                    submodule: "bridge.failure-detector",
+                                    toolName: endEvent.toolName,
+                                    toolCallId: endEvent.toolCallId,
+                                    err: detectorError,
+                                    errorKind: "internal",
+                                    hint: "failureDetector threw; preserving the SDK-reported tool outcome. Fix the detector — it must be pure and never throw.",
+                                }, "Tool failureDetector threw");
+                                // Original success preserved (no mutation of toolSuccess).
+                            }
+                        }
+                    }
+                    // PD-OUTCOME-1: honor an explicit tool self-grade. A tool that reports
+                    // { graded:true, outcome:"failure" } while returning cleanly (no SDK isError)
+                    // is a LOGICAL failure — flip the transport-success so the learning loop credits
+                    // the real task outcome (not "the tool returned"). transportOk stays true (the
+                    // call returned; the CONTENT failed — the failure_detector semantics). Opt-in
+                    // marker ⇒ never a false-flag (mirrors the c53ab0f invariant). Runs only while
+                    // still success, so an SDK/exit-code/detector failure already classified wins.
+                    if (toolSuccess && extractSelfGradedOutcome(endEvent.result) === "failure") {
+                        toolSuccess = false;
+                        toolErrorKind = toolErrorKind ?? "validation";
+                        classifiedFailureBy = "failure_detector";
+                        matchedRule = matchedRule ?? "self_grade";
+                        matchedToken = matchedToken ?? "failure";
+                    }
                     // Retrieve stored args and extract error text for failure diagnostics
                     const sanitizedArgs = m.toolArgSnapshots.get(endEvent.toolCallId);
                     m.toolArgSnapshots.delete(endEvent.toolCallId); // Cleanup regardless of success/failure
+                    // Retrieve + clear the raw args stashed at tool_execution_start; redact
+                    // them into the tool:executed `params` field below.
+                    const rawArgsForParams = m.toolRawArgs.get(endEvent.toolCallId);
+                    m.toolRawArgs.delete(endEvent.toolCallId);
                     let errorText;
+                    // resultBytes/resultDigest replace the raw body with a count + a
+                    // non-reversible 12-hex digest on the failure path (D1+D4) — the
+                    // body itself never crosses into the event/log.
+                    let resultBytes;
+                    let resultDigest;
                     // Extract MCP server name for attribution
                     const mcpServer = extractMcpServerName(endEvent.toolName);
                     if (!toolSuccess) {
                         errorText = extractErrorText(endEvent.result);
+                        const serialized = typeof endEvent.result === "string"
+                            ? endEvent.result
+                            : (() => {
+                                try {
+                                    return JSON.stringify(endEvent.result) ?? "";
+                                }
+                                catch {
+                                    return "";
+                                }
+                            })();
+                        resultBytes = serialized.length;
+                        resultDigest = fingerprint(serialized);
+                        // When toolSuccess was already false from the SDK's isError
+                        // flag (not flipped by an exitCode check), toolErrorKind is
+                        // still undefined here. Classify it so the downstream
+                        // tool:executed event carries an actionable errorKind for
+                        // trajectory + alerting consumers. For MCP tools, mirror the
+                        // dedicated MCP classifier into the closed ErrorKind union
+                        // (timeout → timeout, connection/transport → dependency,
+                        // everything else → classifyToolError fallback).
+                        if (toolErrorKind === undefined) {
+                            if (mcpServer !== undefined) {
+                                const mcpKind = classifyMcpErrorType(errorText);
+                                toolErrorKind = mcpKind === "timeout"
+                                    ? "timeout"
+                                    : (mcpKind === "connection" || mcpKind === "transport")
+                                        ? "dependency"
+                                        : classifyToolError(endEvent.toolName, errorText);
+                                // A1 precedence: the MCP classifier refines the sdk_iserror
+                                // flip when this is an MCP-namespaced tool. The flip source
+                                // is primary; the classifier that produced the errorKind wins
+                                // the label here.
+                                classifiedFailureBy = "mcp_classifier";
+                            }
+                            else {
+                                toolErrorKind = classifyToolError(endEvent.toolName, errorText);
+                                // Keep the flip source (sdk_iserror) — no MCP refinement.
+                                classifiedFailureBy ??= "sdk_iserror";
+                            }
+                        }
+                        // Enrich "Tool X not found" errors with delegation routing hints.
+                        // Only applied when activeToolGroups is provided (sub-agent context).
+                        // NOT_FOUND_RE is anchored (^…$) — only the exact SDK format triggers.
+                        // Skip enrichment for MCP-namespaced tools (mcp__<server>--<tool>) —
+                        // MCP tool reachability is governed by subAgentMcpTools policy, not by tool
+                        // profiles. Profile-widening hints are misleading for MCP tools. Preserve the
+                        // MCP-classified errorKind (dependency/timeout) rather than overwriting with "validation".
+                        if (errorText) {
+                            const notFoundMatch = NOT_FOUND_RE.exec(errorText);
+                            if (notFoundMatch) {
+                                const missingTool = notFoundMatch[1];
+                                // Sub-agent profile-widening hint (unchanged): only non-MCP names, only
+                                // when an activeToolGroups ceiling is in force.
+                                if (deps.activeToolGroups &&
+                                    deps.activeToolGroups.length > 0 &&
+                                    extractMcpServerName(missingTool) === undefined) {
+                                    errorText = classifyUnreachableTool(missingTool, deps.activeToolGroups);
+                                    toolErrorKind = "validation";
+                                }
+                                // F-13: "did you mean <closest>?" for a hallucinated tool name. Fires
+                                // for top-level AND sub-agents whenever a confident match exists — this is
+                                // exactly the path a small model needs when it guessed e.g.
+                                // `mcp__memory_manage--delete` for the builtin `memory_manage`.
+                                const suggestion = deps.allToolNames
+                                    ? suggestClosestTool(missingTool, deps.allToolNames)
+                                    : undefined;
+                                if (suggestion && suggestion !== missingTool) {
+                                    errorText = `${errorText} Did you mean "${suggestion}"? Call it by that exact name (builtin tools have no "mcp__" prefix).`;
+                                    toolErrorKind = "validation";
+                                }
+                            }
+                        }
                         m.failedToolCount++;
                         if (!m.failedToolNames.includes(endEvent.toolName)) {
                             m.failedToolNames.push(endEvent.toolName);
@@ -157,12 +723,71 @@ export function createPiEventBridge(deps) {
                             ...(sanitizedArgs && { toolArgs: sanitizedArgs }),
                             ...(mcpServer !== undefined && { mcpServer, mcpErrorType: classifyMcpErrorType(errorText) }),
                             errorKind: toolErrorKind ?? "dependency",
-                            hint: "Tool execution failed; check errorText and toolArgs for root cause",
+                            // Name the bracketed `[error_code]` the errorText carries
+                            // (permission_denied / invalid_value / …) instead of a generic
+                            // "check errorText" — §2.7 name-which-knob (UC-C2, 2026-06-20).
+                            hint: toolFailureHint(errorText),
+                            // D1 provenance — assigned at the mutation points above.
+                            // matchedToken is untrusted tool output → sanitize+bound it
+                            // exactly like errorText; the rest are enum-like/digest/number.
+                            // transportOk = !endEvent.isError — it reflects whether the
+                            // transport DELIVERED a response, not which classifier labeled
+                            // the failure. It is false ONLY when the SDK reported a
+                            // transport/spawn failure (endEvent.isError), and STAYS false
+                            // even when the A1 MCP classifier later refines that isError
+                            // failure (relabeling classifiedFailureBy → "mcp_classifier").
+                            // Do NOT rewrite as (classifiedFailureBy !== "sdk_iserror") —
+                            // that flips the A1 case to transportOk:true and reopens the
+                            // c53ab0f MCP-transport-failure misclassification (see the
+                            // const above).
+                            ...(classifiedFailureBy !== undefined && { classifiedFailureBy }),
+                            transportOk,
+                            ...(httpStatus !== undefined && { httpStatus }),
+                            ...(matchedRule !== undefined && { matchedRule }),
+                            ...(matchedToken !== undefined && { matchedToken: sanitizeLogString(matchedToken).slice(0, 1500) }),
+                            ...(resultBytes !== undefined && { resultBytes }),
+                            ...(resultDigest !== undefined && { resultDigest }),
                         }, "Tool execution failed");
                     }
-                    // Record tool result in retry breaker for consecutive failure tracking
+                    // Record tool result in retry breaker for consecutive failure
+                    // tracking. recordResult returns a transition verdict at the
+                    // tool-wide counter-crossing edges (the breaker stays emitter-free,
+                    // D3) — capture it and emit the breaker event here, the bridge being
+                    // the sole holder of the event bus. Emit the two events as SEPARATE
+                    // string-literal calls in an if/else (NOT a ternary) so the
+                    // trajectory-event-types-known arch gate's EMIT_REGEX sees both names
+                    // and verifies their mappings (Pitfall 7).
                     if (deps.toolRetryBreaker) {
-                        deps.toolRetryBreaker.recordResult(endEvent.toolName, (sanitizedArgs ?? {}), toolSuccess, errorText);
+                        const transition = deps.toolRetryBreaker.recordResult(endEvent.toolName, (sanitizedArgs ?? {}), toolSuccess, errorText);
+                        if (transition) {
+                            // Count of tools executed so far this execution — the monotonic
+                            // per-execution seq Phase 153 orders the breakerTimeline on (A3).
+                            // Pushed at the m.toolExecResults.push below, so this is the
+                            // pre-push count (0 for the first tool).
+                            const seq = m.toolExecResults.length;
+                            if (transition.transition === "opened") {
+                                deps.eventBus.emit("tool:breaker_opened", {
+                                    toolName: transition.toolName,
+                                    consecutiveFailures: transition.consecutiveFailures,
+                                    errorTag: transition.errorTag,
+                                    reason: transition.reason,
+                                    seq,
+                                    timestamp: systemNowMs(),
+                                });
+                                // Count the trip for the session-health rollup (D5/F1). Only the
+                                // opened transition increments — a reset must not (the rollup
+                                // wants total trips this execution, not net breaker state).
+                                m.breakerTripCount++;
+                            }
+                            else {
+                                deps.eventBus.emit("tool:breaker_reset", {
+                                    toolName: transition.toolName,
+                                    reason: transition.reason,
+                                    seq,
+                                    timestamp: systemNowMs(),
+                                });
+                            }
+                        }
                     }
                     // Track all tool execution results
                     m.toolExecResults.push({
@@ -170,6 +795,9 @@ export function createPiEventBridge(deps) {
                         success: toolSuccess,
                         durationMs,
                         ...(errorText && { errorText }),
+                        // Carry the closed-union errorKind (Phase 150 classification, set on
+                        // the failure path only) for the rollup's bounded topErrorKinds.
+                        ...(toolErrorKind !== undefined && { errorKind: toolErrorKind }),
                     });
                     // Capture outbound deliveries. The post-execution silent-sentinel
                     // gate reads this per-turn log to make sentinel-aware decisions
@@ -229,18 +857,88 @@ export function createPiEventBridge(deps) {
                     }
                     // Look up truncation metadata from stream wrapper registry
                     const truncMeta = deps.getTruncationMeta?.(endEvent.toolCallId);
+                    // Forward redacted params (from the raw args stashed at
+                    // tool_execution_start). redactValue masks secrets/PII/absolute paths
+                    // before the emit crosses the bus. homeDir (when wired) compacts
+                    // $HOME→~ for all consumers, not just the activity renderer.
+                    const executedRedactedParams = redactValue(rawArgsForParams, { homeDir: deps.homeDir }).value;
+                    // F-OBS-2: content-free web_search/web_fetch grounding summary (count +
+                    // source hosts only) — computed on the SUCCESS path so the trajectory
+                    // tool.result reconstructs grounding without a DEBUG daemon-log grep.
+                    const webResultMeta = toolSuccess
+                        ? extractWebResultMetadata(endEvent.toolName, endEvent.result)
+                        : undefined;
                     deps.eventBus.emit("tool:executed", {
                         toolName: endEvent.toolName,
+                        toolCallId: endEvent.toolCallId,
                         durationMs,
                         success: toolSuccess,
                         timestamp: systemNowMs(),
                         agentId: deps.agentId,
                         sessionKey: formatSessionKey(deps.sessionKey),
+                        traceId: tryGetContext()?.traceId ?? deps.executionId,
+                        ...(executedRedactedParams !== undefined && { params: executedRedactedParams }),
                         ...(toolErrorKind !== undefined && { errorKind: toolErrorKind }),
                         ...(errorText && { errorMessage: sanitizeLogString(errorText).slice(0, 1500) }),
                         ...(!toolSuccess && mcpServer !== undefined && { mcpServer, mcpErrorType: classifyMcpErrorType(errorText) }),
                         ...(truncMeta && { truncated: truncMeta.truncated, fullChars: truncMeta.fullChars, returnedChars: truncMeta.returnedChars }),
+                        // D1 provenance (P1) — assigned at the mutation points above.
+                        // matchedToken is untrusted tool output and the payload feeds the
+                        // trajectory + cache-trace translators (Plan 06), so it MUST be
+                        // sanitized+bounded HERE TOO (identical to the WARN) — a raw token
+                        // would leak into the event stream. resultDigest/resultBytes/
+                        // httpStatus/classifiedFailureBy/matchedRule are digest/number/
+                        // closed-union → emitted as-is.
+                        ...(classifiedFailureBy !== undefined && { classifiedFailureBy }),
+                        ...(!toolSuccess && { transportOk }),
+                        ...(httpStatus !== undefined && { httpStatus }),
+                        ...(matchedRule !== undefined && { matchedRule }),
+                        ...(matchedToken !== undefined && { matchedToken: sanitizeLogString(matchedToken).slice(0, 1500) }),
+                        ...(resultBytes !== undefined && { resultBytes }),
+                        ...(resultDigest !== undefined && { resultDigest }),
+                        ...(webResultMeta?.resultCount !== undefined && { resultCount: webResultMeta.resultCount }),
+                        ...(webResultMeta?.domains !== undefined && { domains: webResultMeta.domains }),
                     });
+                    // ATTR-01: skill-use attribution. A `read` whose path equals a frozen
+                    // learned-skill `<location>` means the model invoked that skill. Map
+                    // the read path → skillName via the per-session location index
+                    // (parsed once at prompt-assembly freeze time), emit the EXISTING
+                    // observable `skill:prompt_invoked` (model-invoked), and record the
+                    // skillName in the named per-turn carrier (m.turnUsedSkillIds) which
+                    // the executor reads back into the `memory:skill_used` write-back.
+                    // No match (the default — no learned-skill locations) → no-op.
+                    if (endEvent.toolName === "read") {
+                        const readPath = rawArgsForParams?.path;
+                        if (typeof readPath === "string" && readPath !== "") {
+                            const skillName = getSessionPromptSkillLocations(formatSessionKey(deps.sessionKey))?.get(readPath);
+                            if (skillName !== undefined) {
+                                m.turnUsedSkillIds.add(skillName);
+                                deps.eventBus.emit("skill:prompt_invoked", {
+                                    skillName,
+                                    invokedBy: "model",
+                                    args: "",
+                                    timestamp: systemNowMs(),
+                                });
+                            }
+                        }
+                    }
+                    // Explicit tool:timeout emit when the tool was classified as
+                    // timed-out. Fires alongside tool:executed for the same
+                    // physical timeout — both share toolCallId, so the trajectory
+                    // writer + downstream consumers dedupe by that key (see
+                    // TRAJECTORY_BRIDGE_MAPPING JSDoc + events-agent.ts
+                    // tool:timeout declaration for the dedup contract).
+                    if (toolErrorKind === "timeout") {
+                        deps.eventBus.emit("tool:timeout", {
+                            agentId: deps.agentId,
+                            sessionKey: formatSessionKey(deps.sessionKey),
+                            traceId: tryGetContext()?.traceId ?? deps.executionId,
+                            toolName: endEvent.toolName,
+                            toolCallId: endEvent.toolCallId,
+                            timeoutMs: durationMs,
+                            timestamp: systemNowMs(),
+                        });
+                    }
                     // Reset prompt timeout after each tool completion so slow tools
                     // do not starve subsequent LLM turns.
                     deps.onToolExecutionEnd?.();
@@ -249,10 +947,24 @@ export function createPiEventBridge(deps) {
                         const stepCheck = checkStepLimit(deps.stepCounter, m.aborted);
                         if (stepCheck.shouldAbort) {
                             m.finishReason = stepCheck.finishReason;
+                            m.abortResponse = buildAbortRedirectMessage(deps.executionPlan?.current, m.finishReason);
                             m.aborted = true;
                             emitStepLimitAbort(deps);
                         }
                     }
+                    // Safety: break a runaway repeating-tool loop early (FIX #2) — fires
+                    // at the detector's no-progress threshold, well before the step limit.
+                    // finishReason "loop_detected" flows to the orchestrator's
+                    // mapAbortToTurnOutcome (FIX #3) for a truthful status.
+                    if (deps.turnLoopDetector) {
+                        const loopCheck = checkLoopLimit(deps.turnLoopDetector, m.aborted);
+                        if (loopCheck.shouldAbort) {
+                            m.finishReason = loopCheck.finishReason;
+                            m.abortResponse = buildAbortRedirectMessage(deps.executionPlan?.current, m.finishReason);
+                            m.aborted = true;
+                            emitLoopAbort(deps);
+                        }
+                    }
                     // SEP: Track step progress on tool completion
                     {
                         const plan = deps.executionPlan?.current;
@@ -373,6 +1085,70 @@ export function createPiEventBridge(deps) {
                     break;
                 }
                 // -----------------------------------------------------------------
+                // Assistant message stream closed (BEFORE tools fire)
+                //
+                // pi-mono emits `message_end` when the assistant message stream
+                // resolves (agent-loop.js:214,227) — strictly before any
+                // `tool_execution_start` for tool_calls in that same message
+                // (agent-loop.js:245-249). Eager-extract the SEP plan here so
+                // plan-stream paints the checkbox header DURING the turn rather
+                // than ~3 ms before scaffold deletion at turn_end.
+                //
+                // The shared `!deps.executionPlan.current` guard makes the
+                // existing `case "turn_end"` SEP-extract block (below) a
+                // self-disabling no-op once we extract at message_end. The
+                // turn_end block is preserved as a defensive fallback for
+                // pi-mono shape variants where text appears only at turn_end.
+                // -----------------------------------------------------------------
+                case "message_end": {
+                    const msgEvent = event;
+                    // pi-mono emits message_end for EVERY message (user prompts, pending
+                    // tool-result messages, AND assistant responses — agent-loop.js:52, 96,
+                    // 198, 214, 227). The eager SEP extraction only makes sense for the
+                    // assistant's response; scanning a user prompt produces phantom plans
+                    // from numbered/bulleted content in the injected memory/system context.
+                    // Discriminate on role to ensure only assistant messages reach the extractor.
+                    const candidate = msgEvent.message;
+                    if (candidate?.role !== "assistant")
+                        break;
+                    const assistantMsg = candidate;
+                    if (deps.executionPlan && deps.sepConfig && !deps.executionPlan.current) {
+                        const assistantTextForPlan = Array.isArray(assistantMsg?.content)
+                            ? assistantMsg.content
+                                .filter((c) => c?.type === "text")
+                                .map((c) => c.text ?? "")
+                                .join(" ")
+                            : "";
+                        if (assistantTextForPlan.length > 0) {
+                            const steps = extractPlanFromResponse(assistantTextForPlan, deps.sepConfig.maxSteps);
+                            if (steps && steps.length >= deps.sepConfig.minSteps) {
+                                const plan = {
+                                    active: true,
+                                    request: (deps.sepMessageText ?? "").slice(0, 200),
+                                    steps,
+                                    completedCount: 0,
+                                    createdAtMs: systemNowMs(),
+                                };
+                                deps.executionPlan.current = plan;
+                                deps.logger.info({
+                                    agentId: deps.agentId,
+                                    stepCount: steps.length,
+                                    durationMs: deps.sepExecutionStartMs
+                                        ? systemNowMs() - deps.sepExecutionStartMs
+                                        : undefined,
+                                }, "SEP plan extracted (message_end, eager)");
+                                deps.eventBus.emit("sep:plan_extracted", {
+                                    agentId: deps.agentId ?? "default",
+                                    sessionKey: formatSessionKey(deps.sessionKey),
+                                    stepCount: steps.length,
+                                    timestamp: systemNowMs(),
+                                });
+                            }
+                        }
+                    }
+                    break;
+                }
+                // -----------------------------------------------------------------
                 // LLM turn completed
                 // -----------------------------------------------------------------
                 case "turn_end": {
@@ -465,7 +1241,7 @@ export function createPiEventBridge(deps) {
                         deps.onTurnUsage?.(usage.input);
                         m.totalOutputTokens += usage.output;
                         m.totalTokens += usage.totalTokens;
-                        // NOTE: m.totalCost accumulation deferred until after cost correction (see COST-FIX below)
+                        // NOTE: m.totalCost accumulation deferred until after cost correction (see below)
                         m.totalCacheReadTokens += usage.cacheRead ?? 0;
                         m.totalCacheWriteTokens += usage.cacheWrite ?? 0;
                         // Hoist cache token locals for use in savings formula
@@ -529,22 +1305,15 @@ export function createPiEventBridge(deps) {
                             // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK interop boundary
                             ? { shortTtl: rawUsage.cacheCreation.shortTtl ?? 0, longTtl: rawUsage.cacheCreation.longTtl ?? 0 }
                             : undefined;
-                        if (cacheWriteTokens > 0) {
-                            deps.logger.debug({
-                                cacheWriteTokens,
-                                // Whether the pi-ai SDK exposes the per-TTL cache_creation breakdown
-                                // (usage.cacheCreation.shortTtl/longTtl). Expected: false -- pi-ai does
-                                // not surface this field. Per-TTL split is only visible on the Anthropic
-                                // dashboard. This does NOT mean cache writes are failing; cacheWriteTokens
-                                // above confirms writes are happening normally.
-                                sdkTtlBreakdownAvailable: cacheCreation !== undefined,
-                                shortTtl: cacheCreation?.shortTtl,
-                                longTtl: cacheCreation?.longTtl,
-                            }, "Cache write TTL breakdown (pi-ai SDK does not expose per-TTL split; see Anthropic dashboard)");
-                        }
+                        // Per-call DEBUG breakdown log removed. The fact
+                        // that pi-ai does not expose the per-TTL split is now stated
+                        // once at construction time via the module-level
+                        // _sdkBreakdownNoticeEmitted latch above. cacheCreation
+                        // (when present) still flows downstream into the
+                        // observability:token_usage event payload below.
                         // Record usage in budget guard (token-based, not cost-based -- stays before correction)
                         deps.budgetGuard.recordUsage(usage.totalTokens);
-                        // COST-FIX ordering: Normalize TTL split estimates BEFORE cost correction.
+                        // Ordering: Normalize TTL split estimates BEFORE cost correction.
                         // The injector provides raw per-TTL estimates; normalize so they sum to the
                         // SDK-reported total (eliminates the 28% estimation error).
                         // Mutate in-place so per-TTL cost and accumulation use normalized values.
@@ -558,7 +1327,7 @@ export function createPiEventBridge(deps) {
                                 deps.ttlSplit.cacheWrite1hTokens = cacheWriteTokens - norm5m; // remainder ensures exact sum
                             }
                         }
-                        // COST-FIX: Compute cost correction for 1h tokens the SDK underpriced at the 5m rate.
+                        // Compute cost correction for 1h tokens the SDK underpriced at the 5m rate.
                         // The SDK prices ALL cacheWrite tokens at pricing.cacheWrite (5m rate).
                         // When TTL split is available, 1h tokens should be priced at pricing.cacheWrite1h.
                         // Delta = cacheWrite1hTokens * (cacheWrite1h - cacheWrite) -- the underpayment per 1h token.
@@ -573,16 +1342,21 @@ export function createPiEventBridge(deps) {
                             : sdkCost;
                         // Accumulate corrected cost
                         m.totalCost += cost.total;
+                        // Accumulate per-turn cost-correction delta (>0
+                        // only — matches the invariant that negative
+                        // correction is suppressed; see costCorrectionField gate at
+                        // line ~1106). Surfaced via buildBridgeResult on the
+                        // "Execution complete" log.
                         if (costCorrectionDelta > 0) {
-                            deps.logger.debug({
-                                costCorrectionDelta,
-                                sdkCostTotal: sdkCost.total,
-                                correctedCostTotal: cost.total,
-                                cacheWrite1hTokens: deps.ttlSplit.cacheWrite1hTokens,
-                                rate5m: pricing.cacheWrite,
-                                rate1h: pricing.cacheWrite1h,
-                            }, "Cost correction applied: SDK underpriced 1h cache writes at 5m rate");
+                            m.totalCostCorrectionDeltaUsd += costCorrectionDelta;
                         }
+                        // Per-call DEBUG cost-correction log removed. The
+                        // costCorrection breadcrumb now rides on the
+                        // observability:token_usage event payload below — operators
+                        // already query that event for cost forensics, so moving the
+                        // signal there preserves observability without inflating
+                        // DEBUG volume. The field is included only when delta !== 0;
+                        // a turn with no correction emits nothing extra.
                         // Record in cost tracker (uses corrected cost)
                         deps.costTracker.record(deps.agentId, deps.channelId, deps.executionId, {
                             input: usage.input,
@@ -619,6 +1393,22 @@ export function createPiEventBridge(deps) {
                         }
                         // Accumulate cache savings across turns
                         m.totalCacheSaved += savedVsUncached;
+                        // Warmup-turn signal. Identifies the first
+                        // cache-write turn in a session (writes-without-prior-reads).
+                        // Per-call cache math is correct, but reporting cacheSavedUsd
+                        // as a negative dollar value on this turn is misleading
+                        // because the "loss" is a deferred investment recouped by
+                        // subsequent cached reads, not a cost regression. The
+                        // positive-signed `pendingCacheInvestmentUsd` is the
+                        // dashboard-friendly framing of the same magnitude; the
+                        // original `savedVsUncached` keeps its negative value (math
+                        // preserved).
+                        const warmupTurn = cacheReadTokens === 0 && cacheWriteTokens > 0;
+                        const pendingCacheInvestmentUsd = warmupTurn && savedVsUncached < 0 ? -savedVsUncached : 0;
+                        if (warmupTurn) {
+                            m.warmupTurnCount += 1;
+                            m.totalPendingCacheInvestmentUsd += pendingCacheInvestmentUsd;
+                        }
                         // Record per-turn cache savings for cost gate evaluation.
                         if (deps.onTurnCacheSavings) {
                             deps.onTurnCacheSavings(savedVsUncached);
@@ -646,9 +1436,30 @@ export function createPiEventBridge(deps) {
                             ? { shortTtl: m.totalCacheWrite5mTokens, longTtl: m.totalCacheWrite1hTokens }
                             : undefined);
                         // Emit observability event
+                        // Include costCorrection breadcrumb when the SDK
+                        // total was bumped to cover 1h-rate underpricing. Omitted
+                        // when delta === 0 — operators can filter on
+                        // `costCorrection != null` to surface only corrected turns.
+                        const costCorrectionField = costCorrectionDelta !== 0
+                            ? {
+                                costCorrection: {
+                                    delta: cost.total - sdkCost.total, // = costCorrectionDelta when > 0
+                                    sdkRaw: sdkCost.total,
+                                    corrected: cost.total,
+                                },
+                            }
+                            : {};
+                        // COST-01: tag this turn with the DISTINCT tools that fired (from the
+                        // already-tracked m.toolCallHistory at :557 — NOT a new accumulator).
+                        // Content-free: tool NAMES/ids only, never args/output. The per-tool $
+                        // split a consumer renders is best-effort/labeled (N3) — an even split
+                        // across these distinct tools that conserves cost.total (locked A5);
+                        // exact per-tool accounting is out of scope. undefined ⇒ the spread
+                        // vanishes and the emit is byte-for-byte unchanged on a no-tool turn.
+                        const toolTag = m.toolCallHistory.length > 0 ? Array.from(new Set(m.toolCallHistory)) : undefined;
                         deps.eventBus.emit("observability:token_usage", {
                             timestamp: systemNowMs(),
-                            traceId: deps.executionId,
+                            traceId: tryGetContext()?.traceId ?? deps.executionId,
                             agentId: deps.agentId,
                             channelId: deps.channelId,
                             executionId: deps.executionId,
@@ -674,16 +1485,213 @@ export function createPiEventBridge(deps) {
                             cacheEligible: getCacheProviderInfo(deps.provider, deps.getCurrentModel?.() ?? deps.model).cacheEligible,
                             responseId,
                             cacheCreation: effectiveCacheCreation,
+                            // Warmup-turn flag + deferred investment
+                            // dollar value. Both included unconditionally so consumers
+                            // can pivot/filter without conditional schemas.
+                            warmupTurn,
+                            pendingCacheInvestmentUsd,
+                            ...costCorrectionField,
+                            // COST-01: the distinct tool tag (best-effort, labeled). Spread so
+                            // a no-tool turn keeps the payload byte-for-byte unchanged (no shim).
+                            ...(toolTag && { toolTag }),
+                            // B3 (D8): SDK per-turn stop signal. RELIABLE — m.lastStopReason is
+                            // captured at :1231 in this same turn_end case, BEFORE this emit.
+                            ...(m.lastStopReason !== undefined && { stopReason: m.lastStopReason }),
+                            // B3 (D8): execution-level finish disposition. m.finishReason settles
+                            // LATER than turn_end (the safety guards set it at
+                            // :1005/:1018/:1625/:1672/:2113), so on a normal turn it is still the
+                            // init default "stop". Forward it ONLY once it has diverged from that
+                            // default, so model.completed does not carry a stale, authoritative-
+                            // looking "stop" on every normal turn (WR-151-01) — the translator's
+                            // presence-conditional guard then correctly omits it. A genuinely
+                            // settled value (a guard-set "max_steps"/"loop_detected"/etc. from this
+                            // or a prior turn) IS forwarded. The authoritative settled finishReason
+                            // is Phase 152's flight-recorder (effectiveFinishReason); the reliable
+                            // D8 field at this per-turn emit is stopReason above.
+                            ...(m.finishReason !== "stop" && { finishReason: m.finishReason }),
+                        });
+                        // Append turn_completed to the session index. Co-located with
+                        // observability:token_usage emit (the only site that carries
+                        // BOTH input AND output tokens per turn — onTurnUsage only
+                        // has input tokens).
+                        appendSessionIndexEntry(deps.dataDir ?? pathModule.join(os.homedir(), ".comis"), {
+                            traceSchema: "comis-session-index",
+                            schemaVersion: 1,
+                            event: "turn_completed",
+                            ts: systemDateFrom(systemNowMs()).toISOString(),
+                            sessionId: formatSessionKey(deps.sessionKey),
+                            traceId: tryGetContext()?.traceId ?? deps.executionId,
+                            durationMs: llmLatencyMs ?? 0,
+                            inputTokens: usage.input,
+                            outputTokens: usage.output,
+                            // W7 (obs-llm-troubleshooting): make degraded turns greppable from
+                            // the index alone. stopReason is the RELIABLE per-turn signal
+                            // (captured at :1231 in this same turn_end); finishReason mirrors
+                            // the model.completed WR-151-01 guard — forwarded only once it has
+                            // settled away from the init default "stop" (the HR-01 mapping for
+                            // THIS turn runs after this append, so it lands on later rows).
+                            ...(m.lastStopReason !== undefined && { stopReason: m.lastStopReason }),
+                            ...(m.finishReason !== "stop" && { finishReason: m.finishReason }),
+                            lastError: null, // populated by error paths in a follow-up plan; null here
+                            source: "runtime", // D9 provenance stamp (production rows)
                         });
                         // Safety: check budget after recording (delegated to bridge-safety-controls)
                         {
                             const budgetCheck = checkBudgetLimit(deps.budgetGuard, m.aborted);
                             if (budgetCheck.shouldAbort) {
                                 m.finishReason = budgetCheck.finishReason;
+                                m.abortResponse = buildAbortRedirectMessage(deps.executionPlan?.current, m.finishReason);
                                 m.aborted = true;
                                 emitBudgetAbort(deps, m.totalTokens);
                             }
                         }
+                        // Safety: the dollars kill-switch (Phase 177). ADMISSION-BOUNDED +
+                        // COOPERATIVE-ABORT. The bridge has NO pre-flight cost estimate at this
+                        // post-record point, so it reserves a conservative perTurnMax through
+                        // the SYNCHRONOUS atomic accumulator (which serializes concurrent
+                        // admissions), runs the 3-state pricing gate, and routes a breach
+                        // through the single execution:aborted{reason:"spend_exceeded"} path.
+                        //
+                        // No double-count: the granted reservation is reconciled to $0 below —
+                        // a PURE admission hold released at the billing point. The actual
+                        // cost.total already landed via the daemon-wide observability:token_usage
+                        // subscriber (emitted just above, ~:1671), which is the SOLE permanent
+                        // actual-adder. The reservation only bounds concurrent admissions to a
+                        // single turn's perTurnMax overshoot; it never permanently consumes the
+                        // ceiling itself.
+                        //
+                        // When spendAccumulator is absent (flags off / not wired) this whole
+                        // block is skipped — the healthy path is byte-identical.
+                        if (deps.spendAccumulator && deps.spendScope && deps.spendConfig) {
+                            const spendAcc = deps.spendAccumulator;
+                            const spendCfg = deps.spendConfig;
+                            const spendScope = deps.spendScope;
+                            const spendModel = deps.getCurrentModel?.() ?? deps.model;
+                            // Breach detail for the content-free spend_exceeded event, captured
+                            // from the gate outcome before checkSpendLimit fires the emit hook.
+                            let spendBreachScope = "global";
+                            let spendBreachCurrentUsd = 0;
+                            let spendBreachCapUsd = 0;
+                            const spendEmit = {
+                                // WR-1 (177-obs-loop): emit the breaching warn DIMENSION the
+                                // accumulator reported (the crossed scope + THAT dimension's
+                                // post-reserve total + cap) — NOT a hard-coded scope:"agent" + the
+                                // session-local cumulative cost + a first-non-null cap (an
+                                // internally-inconsistent event when the tenant/global ceiling is
+                                // the one that crossed — the security-review WR-1 finding).
+                                spendWarning: (warn) => deps.eventBus.emit("observability:spend_warning", {
+                                    timestamp: systemNowMs(),
+                                    agentId: deps.agentId,
+                                    sessionKey: formatSessionKey(deps.sessionKey),
+                                    scope: warn.scope,
+                                    spentUsd: warn.totalUsd,
+                                    capUsd: warn.capUsd,
+                                    fraction: spendCfg.warnAtFraction,
+                                }),
+                                spendExceeded: () => deps.eventBus.emit("observability:spend_exceeded", {
+                                    timestamp: systemNowMs(),
+                                    agentId: deps.agentId,
+                                    sessionKey: formatSessionKey(deps.sessionKey),
+                                    scope: spendBreachScope,
+                                    spentUsd: spendBreachCurrentUsd,
+                                    capUsd: spendBreachCapUsd,
+                                    estUsd: spendCfg.perTurnMax,
+                                }),
+                                spendUnpriceable: () => deps.eventBus.emit("observability:spend_unpriceable", {
+                                    timestamp: systemNowMs(),
+                                    agentId: deps.agentId,
+                                    sessionKey: formatSessionKey(deps.sessionKey),
+                                    provider: deps.provider,
+                                    model: spendModel,
+                                }),
+                            };
+                            // Atomic reserve of the conservative perTurnMax + the 3-state gate.
+                            const gate = checkSpendCeiling(spendAcc, spendScope, deps.provider, spendModel, spendCfg.perTurnMax, { onUnknownPricing: spendCfg.onUnknownPricing, pricingFallback: spendCfg.pricingFallback }, usage.totalTokens > 0);
+                            // checkSpendCeiling is Result-returning; an err here is unexpected
+                            // (the gate maps a breach to an `exceeded` outcome, not an err), but
+                            // be defensive: a defensive err means "do not abort" (fail-safe).
+                            if (gate.ok) {
+                                const outcome = gate.value;
+                                // Surface the breach scope/amounts for the content-free event.
+                                if (outcome.kind === "exceeded") {
+                                    spendBreachScope = outcome.error.scope;
+                                    spendBreachCurrentUsd = outcome.error.currentUsd;
+                                    spendBreachCapUsd = outcome.error.capUsd;
+                                }
+                                const spendCheck = checkSpendLimit(outcome, spendCfg.action, spendCfg.onUnknownPricing, m.aborted, spendEmit);
+                                if (spendCheck.shouldAbort) {
+                                    m.finishReason = spendCheck.finishReason;
+                                    m.abortResponse = buildAbortRedirectMessage(deps.executionPlan?.current, m.finishReason);
+                                    m.aborted = true;
+                                    emitSpendAbort(deps);
+                                }
+                                // COOPERATIVE: release the admission hold to $0. The actual
+                                // cost.total is recorded by the live token_usage subscriber, so
+                                // reconciling to 0 (delta = 0 - perTurnMax) nets the reservation
+                                // out of the counters and avoids double-counting.
+                                if (outcome.kind === "ok") {
+                                    spendAcc.reconcile(outcome.reservation, 0);
+                                }
+                            }
+                        }
+                        // Phase 213-08 (BUDGET-01/02): the PER-ROOT budget reserve — a SIBLING
+                        // to the Phase-177 checkSpendCeiling above. Where that ceiling is
+                        // per-(tenant,agent), this reserves a self-spawning loop's LIVE LLM
+                        // spend per tree-ROOT (keyed on the run's rootRunId), so the token +
+                        // wall-clock limbs fire on a reasoning loop — INCLUDING a zero-price
+                        // native-provider model where the $-cap can never bite (criterion #2).
+                        //
+                        // ADDITIVE + gated on the holder ALONE (NOT spendAccumulator): a
+                        // zero-price loop runs with the $-ceiling off yet must still trip the
+                        // token/wall-clock limbs. When the holder is absent / its `current` is
+                        // not yet populated the whole block is skipped — byte-identical to today.
+                        // The wall-clock + token state lives INSIDE the injected meter (its own
+                        // ClockPort) — no Date.now here; the bridge just calls reserveBudget and
+                        // routes an `exceeded` outcome through the SAME m.aborted spend-abort path.
+                        const perRoot = deps.boundedAutonomyBudget?.current;
+                        if (perRoot && deps.resolveRootRunId && !m.aborted) {
+                            const rootRunId = deps.resolveRootRunId(deps.sessionKey);
+                            // KEYING-01: re-anchor the per-root wall-clock + token limbs ONCE per
+                            // turn (this metrics state is per-turn, so the flag fires on the turn's
+                            // FIRST per-root reserve). An interactive session root (`root-session-*`)
+                            // acquires no spawn slot, so `releaseSpawn` never evicts it and its
+                            // anchor would accumulate across the WHOLE conversation — falsely
+                            // aborting a turn after wallClockMs of wall-clock AGE (live finding
+                            // 2026-06-24). evictRootIfIdle is a NO-OP when a live spawn shares the
+                            // root (the runaway-tree backstop holds) and preserves the $ aggregate;
+                            // the reserveBudget below then re-anchors THIS turn from its own start
+                            // (the IN-02 first-reserve write in per-root-budget.ts).
+                            if (!m.perRootReanchored) {
+                                perRoot.evictRootIfIdle?.(rootRunId);
+                                m.perRootReanchored = true;
+                            }
+                            // The SAME real per-call locals the sibling ceiling consumes: the live
+                            // model (a manual /model switch updates getCurrentModel), the provider,
+                            // the conservative perTurnMax est $ (0 when spend is unconfigured — the
+                            // token/wall-clock limbs still gate), and the turn's true totalTokens.
+                            const perRootModel = deps.getCurrentModel?.() ?? deps.model;
+                            const perRootEstUsd = deps.spendConfig?.perTurnMax ?? 0;
+                            const rootGate = perRoot.reserveBudget(rootRunId, deps.provider, perRootModel, perRootEstUsd, usage.totalTokens);
+                            if (rootGate.kind === "exceeded") {
+                                m.finishReason = "spend_exceeded"; // reuse the single spend finishReason
+                                m.abortResponse = buildAbortRedirectMessage(deps.executionPlan?.current, m.finishReason);
+                                m.aborted = true;
+                                // SPEND-ABORT-OBS: this is the per-ROOT autonomy.budget meter, NOT the
+                                // observability.spend ceiling — steer the operator hint at the right knob.
+                                // OBS-3: carry the tripped limb + its numbers (token/wall-clock/$ in
+                                // their own unit) onto the abort event so `explain` names the exact
+                                // knob instead of the operator grepping the "Per-root … budget
+                                // exceeded" log line. The WARN stays content-free (§2.7).
+                                emitSpendAbort(deps, "per_root", rootGate.error.limb !== undefined
+                                    ? {
+                                        limb: rootGate.error.limb,
+                                        spent: rootGate.error.currentUsd,
+                                        cap: rootGate.error.capUsd,
+                                        unit: rootGate.error.unit ?? "usd",
+                                    }
+                                    : undefined);
+                            }
+                        }
                         // Budget trajectory warning: detect approaching exhaustion before hard abort
                         if (!m.budgetWarningEmitted) {
                             const trajectory = checkBudgetTrajectory(m, deps.perExecutionBudgetCap);
@@ -723,6 +1731,7 @@ export function createPiEventBridge(deps) {
                             const contextCheck = checkContextWindow(deps.contextGuard, contextUsage, m.aborted, deps.logger);
                             if (contextCheck.shouldAbort) {
                                 m.finishReason = contextCheck.finishReason;
+                                m.abortResponse = buildAbortRedirectMessage(deps.executionPlan?.current, m.finishReason);
                                 m.aborted = true;
                                 emitContextAbort(deps, contextUsage);
                             }
@@ -853,7 +1862,7 @@ export function createPiEventBridge(deps) {
                 // -----------------------------------------------------------------
                 case "compaction_start": {
                     m.compactionStartMs = systemNowMs();
-                    deps.logger.info({ sessionKey: formatSessionKey(deps.sessionKey) }, "Auto-compaction started");
+                    deps.logger.info({ step: "compaction", sessionKey: formatSessionKey(deps.sessionKey) }, "Auto-compaction started");
                     deps.eventBus.emit("compaction:started", {
                         agentId: deps.agentId,
                         sessionKey: deps.sessionKey,
@@ -907,6 +1916,7 @@ export function createPiEventBridge(deps) {
                     else {
                         // INFO for successful completion
                         deps.logger.info({
+                            step: "compaction",
                             durationMs,
                             aborted: false,
                             hasSummary: !!compactionEvent.result?.summary,
@@ -951,11 +1961,32 @@ export function createPiEventBridge(deps) {
                 const turnMsg = event.message;
                 if (turnMsg && "stopReason" in turnMsg && turnMsg.stopReason === "error") {
                     m.lastLlmErrorMessage = turnMsg.errorMessage ?? "Unknown LLM error";
-                    deps.logger.warn({
-                        err: m.lastLlmErrorMessage,
-                        hint: "Check LLM provider status",
-                        errorKind: "dependency",
-                    }, "LLM call returned error");
+                    // HR-01 (v2.19): a ContextExhaustionError thrown by the context-engine
+                    // pre-flight during a MID-TURN continuation surfaces here as a turn_end
+                    // error with its message preserved (the SDK strips the `instanceof`, so
+                    // the top-level handleEnvelopeException mapping never runs). Recover the
+                    // signal and map it to finishReason:"context_exhausted" — this makes
+                    // postExecution deliver the honest buildContextExhaustedReply() instead
+                    // of letting the empty-turn recovery synthesize a false "the work was
+                    // done" summary. The provider is healthy; this is a local fit failure,
+                    // so it is a resource condition, not a dependency error. The wire-diff
+                    // diagnostic below is a no-op for this message (its regex needs
+                    // thinking-block-replay tokens), so we let it fall through.
+                    if (isContextExhaustionErrorMessage(m.lastLlmErrorMessage)) {
+                        m.finishReason = "context_exhausted";
+                        deps.logger.warn({
+                            err: m.lastLlmErrorMessage,
+                            hint: "Context window exhausted mid-turn (pre-flight) — mapped to context_exhausted so the honest degraded reply is delivered; raise the agent's context window or narrow the ask",
+                            errorKind: "resource",
+                        }, "Context exhausted mid-turn — mapped to finishReason");
+                    }
+                    else {
+                        deps.logger.warn({
+                            err: m.lastLlmErrorMessage,
+                            hint: "Check LLM provider status",
+                            errorKind: "dependency",
+                        }, "LLM call returned error");
+                    }
                     // Wire-edge diagnostic: when the LLM error matches the Anthropic
                     // signed-replay rejection signature ("thinking blocks ... cannot
                     // be modified"), diff the in-memory content against the persisted
@@ -1080,6 +2111,7 @@ export function createPiEventBridge(deps) {
                         const cbCheck = checkCircuitBreaker(deps.circuitBreaker, m.aborted);
                         if (cbCheck.shouldAbort) {
                             m.finishReason = cbCheck.finishReason;
+                            m.abortResponse = buildAbortRedirectMessage(deps.executionPlan?.current, m.finishReason);
                             m.aborted = true;
                             emitCircuitBreakerAbort(deps);
                         }
@@ -1119,5 +2151,18 @@ export function createPiEventBridge(deps) {
     const getDrainState = () => ({
         drainInflightByKey: m.drainInflightByKey,
     });
-    return { listener, getResult, addGhostCost, getThinkingBlockStores, getDrainState };
+    // ATTR-01: ReadonlySet view of the per-turn attributed skill ids. The
+    // executor reads this back at the postExecution call site (carrier → the
+    // memory:skill_used write-back). Read-only — `m` is never exported.
+    // Reuse-attribution UNION: the explicit-`read` attributions (ATTR-01, m.turnUsedSkillIds)
+    // with the per-turn TOPIC-MATCHED surfaced skills (prompt-assembly computed which surfaced
+    // skills THIS turn's request instantiates) — so a skill applied without opening its SKILL.md
+    // still promotes. Empty/no-match ⇒ byte-identical to before.
+    const getUsedSkillIds = () => {
+        const topicMatched = getSessionPromptTopicMatchedSkills(formatSessionKey(deps.sessionKey));
+        if (!topicMatched || topicMatched.length === 0)
+            return m.turnUsedSkillIds;
+        return new Set([...m.turnUsedSkillIds, ...topicMatched]);
+    };
+    return { listener, getResult, addGhostCost, getThinkingBlockStores, getDrainState, getUsedSkillIds };
 }