comisai 1.0.45 → 1.0.46

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

@@ -151,12 +151,12 @@ function classifyUnreachableTool(toolName, activeGroups) {
         `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
+ * 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 (load-bearing evidence must not be visible only at
+ * DEBUG level). 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`
@@ -216,7 +216,7 @@ export function extractWebResultMetadata(toolName, result) {
  * - error (from turn_end with stopReason) -> circuit breaker failure
  */
 /**
- * Tool self-grade convention (PD-OUTCOME-1, codex package-delivery live-test).
+ * Tool self-grade convention.
  *
  * A tool may report its own SEMANTIC outcome via an explicit
  * `{ graded: true, outcome: "success" | "failure" }` envelope, so an action that
@@ -231,7 +231,7 @@ export function extractWebResultMetadata(toolName, result) {
  *     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:
+ * result is NEVER false-flagged (the 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`.
  */
@@ -247,7 +247,7 @@ export function extractSelfGradedOutcome(result) {
     //    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 bare case (verified against the live wire shape: the preamble/markers carry no braces, so
     //    the first-'{'…last-'}' slice is the JSON payload).
     const content = result.content;
     if (!Array.isArray(content))
@@ -324,7 +324,7 @@ export function createPiEventBridge(deps) {
                         }
                         if (deps.onDelta && typeof ame.delta === "string") {
                             try {
-                                // SA1: forward the SDK's typed delta kind so the consumer can gate
+                                // 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)
@@ -393,7 +393,7 @@ export function createPiEventBridge(deps) {
                         channelId: deps.channelId ?? "",
                         agentId: deps.agentId,
                         traceIds: [deps.executionId],
-                        source: "runtime", // D9 provenance stamp (production rows)
+                        source: "runtime", // provenance stamp (production rows)
                     });
                     // Emit the trace.metadata lifecycle envelope directly via the
                     // recorder — no bus event source.
@@ -495,7 +495,7 @@ export function createPiEventBridge(deps) {
                     // The SDK only sets isError on thrown exceptions, so we also inspect the result.
                     let toolSuccess = !endEvent.isError;
                     let toolErrorKind;
-                    // D1 failure-classification provenance (P1): assigned AT each
+                    // Failure-classification provenance: 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 ⇒
@@ -510,9 +510,9 @@ export function createPiEventBridge(deps) {
                     // 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
+                    // structured field, the transport was fine". (Derived from
                     // the flip source, NOT the refined classifiedFailureBy label, so the
-                    // A1 MCP-refinement of an SDK-isError failure stays transportOk:false.)
+                    // 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)
@@ -524,7 +524,7 @@ export function createPiEventBridge(deps) {
                     // 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
+                    // Skip flagged tools (observed live: 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;
@@ -536,7 +536,7 @@ export function createPiEventBridge(deps) {
                             classifiedFailureBy = "exit_code"; // exec non-zero exit — call returned, content failed
                         }
                     }
-                    // §16.10: run the tool's failureDetector hook BEFORE the
+                    // 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
@@ -550,8 +550,8 @@ export function createPiEventBridge(deps) {
                             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
+                                    // Single-chokepoint no-false-flag guard: the no-false-flag
+                                    // 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.
@@ -581,7 +581,7 @@ export function createPiEventBridge(deps) {
                                                 : undefined) ?? toolErrorKind ?? "internal";
                                         classifiedFailureBy = "failure_detector";
                                         if (typeof detected === "object" && detected !== null) {
-                                            // matchedRule/matchedToken are verdict provenance (P2).
+                                            // matchedRule/matchedToken are verdict provenance.
                                             // matchedToken is free-text untrusted tool output — it is
                                             // sanitized+bounded at BOTH sinks (WARN + emit), never here.
                                             matchedRule = detected.matchedRule;
@@ -606,12 +606,12 @@ export function createPiEventBridge(deps) {
                             }
                         }
                     }
-                    // PD-OUTCOME-1: honor an explicit tool self-grade. A tool that reports
+                    // 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
+                    // marker ⇒ never a false-flag. Runs only while
                     // still success, so an SDK/exit-code/detector failure already classified wins.
                     if (toolSuccess && extractSelfGradedOutcome(endEvent.result) === "failure") {
                         toolSuccess = false;
@@ -629,7 +629,7 @@ export function createPiEventBridge(deps) {
                     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
+                    // non-reversible 12-hex digest on the failure path — the
                     // body itself never crosses into the event/log.
                     let resultBytes;
                     let resultDigest;
@@ -665,7 +665,7 @@ export function createPiEventBridge(deps) {
                                     : (mcpKind === "connection" || mcpKind === "transport")
                                         ? "dependency"
                                         : classifyToolError(endEvent.toolName, errorText);
-                                // A1 precedence: the MCP classifier refines the sdk_iserror
+                                // Classifier 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.
@@ -696,7 +696,7 @@ export function createPiEventBridge(deps) {
                                     errorText = classifyUnreachableTool(missingTool, deps.activeToolGroups);
                                     toolErrorKind = "validation";
                                 }
-                                // F-13: "did you mean <closest>?" for a hallucinated tool name. Fires
+                                // "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`.
@@ -725,20 +725,20 @@ export function createPiEventBridge(deps) {
                             errorKind: toolErrorKind ?? "dependency",
                             // 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).
+                            // "check errorText" — the hint must name the exact knob (AGENTS.md §2.7).
                             hint: toolFailureHint(errorText),
-                            // D1 provenance — assigned at the mutation points above.
+                            // Failure-classification 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
+                            // even when the 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
+                            // that flips the MCP-refined case to transportOk:true and reopens
+                            // the MCP-transport-failure misclassification (see the
                             // const above).
                             ...(classifiedFailureBy !== undefined && { classifiedFailureBy }),
                             transportOk,
@@ -751,17 +751,17 @@ export function createPiEventBridge(deps) {
                     }
                     // 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).
+                    // tool-wide counter-crossing edges (the breaker itself stays
+                    // emitter-free) — 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.
                     if (deps.toolRetryBreaker) {
                         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).
+                            // per-execution seq the breakerTimeline is ordered on.
                             // Pushed at the m.toolExecResults.push below, so this is the
                             // pre-push count (0 for the first tool).
                             const seq = m.toolExecResults.length;
@@ -774,7 +774,7 @@ export function createPiEventBridge(deps) {
                                     seq,
                                     timestamp: systemNowMs(),
                                 });
-                                // Count the trip for the session-health rollup (D5/F1). Only the
+                                // Count the trip for the session-health rollup. Only the
                                 // opened transition increments — a reset must not (the rollup
                                 // wants total trips this execution, not net breaker state).
                                 m.breakerTripCount++;
@@ -795,8 +795,8 @@ 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.
+                        // Carry the closed-union errorKind (set on the failure path only)
+                        // for the rollup's bounded topErrorKinds.
                         ...(toolErrorKind !== undefined && { errorKind: toolErrorKind }),
                     });
                     // Capture outbound deliveries. The post-execution silent-sentinel
@@ -862,7 +862,7 @@ export function createPiEventBridge(deps) {
                     // 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 +
+                    // 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
@@ -878,13 +878,24 @@ export function createPiEventBridge(deps) {
                         sessionKey: formatSessionKey(deps.sessionKey),
                         traceId: tryGetContext()?.traceId ?? deps.executionId,
                         ...(executedRedactedParams !== undefined && { params: executedRedactedParams }),
+                        // On FAILURE, carry the bounded+redacted argument shape so the
+                        // trajectory tool.result record — and `comis explain`'s failures[] —
+                        // can answer "what did the failed call attempt?" without a raw
+                        // conversation-store dive. redactValue (executedRedactedParams)
+                        // masks secrets/PII/paths; sanitizeToolArgs then caps each value
+                        // (large values → "[N chars]"). Success omits it — the input is
+                        // only diagnostically load-bearing on a failure, and gating keeps
+                        // the trajectory lean.
+                        ...(!toolSuccess && executedRedactedParams !== undefined && {
+                            argsPreview: sanitizeToolArgs(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.
+                        // Failure-classification provenance — 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
+                        // trajectory + cache-trace translators, 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/
@@ -899,7 +910,7 @@ export function createPiEventBridge(deps) {
                         ...(webResultMeta?.resultCount !== undefined && { resultCount: webResultMeta.resultCount }),
                         ...(webResultMeta?.domains !== undefined && { domains: webResultMeta.domains }),
                     });
-                    // ATTR-01: skill-use attribution. A `read` whose path equals a frozen
+                    // 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
@@ -952,10 +963,10 @@ export function createPiEventBridge(deps) {
                             emitStepLimitAbort(deps);
                         }
                     }
-                    // Safety: break a runaway repeating-tool loop early (FIX #2) — fires
+                    // Safety: break a runaway repeating-tool loop early — 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.
+                    // mapAbortToTurnOutcome for a truthful status.
                     if (deps.turnLoopDetector) {
                         const loopCheck = checkLoopLimit(deps.turnLoopDetector, m.aborted);
                         if (loopCheck.shouldAbort) {
@@ -1414,8 +1425,8 @@ export function createPiEventBridge(deps) {
                             deps.onTurnCacheSavings(savedVsUncached);
                         }
                         // Accumulate session-cumulative costs alongside per-turn values
-                        m.sessionCumulativeCostUsd += cost.total;
-                        m.sessionCumulativeCacheSavedUsd += savedVsUncached;
+                        m.executionCostUsd += cost.total;
+                        m.executionCacheSavedUsd += savedVsUncached;
                         // Track thinking tokens from SDK usage object.
                         // The pi-ai SDK Usage type does not have a dedicated thinking/reasoning field,
                         // but future versions or raw API responses may include `reasoningTokens`.
@@ -1449,11 +1460,11 @@ export function createPiEventBridge(deps) {
                                 },
                             }
                             : {};
-                        // COST-01: tag this turn with the DISTINCT tools that fired (from the
-                        // already-tracked m.toolCallHistory at :557 — NOT a new accumulator).
+                        // Tag this turn with the DISTINCT tools that fired (from the
+                        // already-tracked m.toolCallHistory — 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);
+                        // split a consumer renders is best-effort/labeled — an even split
+                        // across these distinct tools that conserves cost.total;
                         // 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;
@@ -1491,23 +1502,23 @@ export function createPiEventBridge(deps) {
                             warmupTurn,
                             pendingCacheInvestmentUsd,
                             ...costCorrectionField,
-                            // COST-01: the distinct tool tag (best-effort, labeled). Spread so
+                            // 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.
+                            // SDK per-turn stop signal. RELIABLE — m.lastStopReason is
+                            // captured earlier 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
+                            // Execution-level finish disposition. m.finishReason settles
+                            // LATER than turn_end (the safety guards set it),
+                            // 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
+                            // looking "stop" on every normal turn — 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.
+                            // is the flight-recorder rollup (effectiveFinishReason); the reliable
+                            // per-turn field at this emit is stopReason above.
                             ...(m.finishReason !== "stop" && { finishReason: m.finishReason }),
                         });
                         // Append turn_completed to the session index. Co-located with
@@ -1524,16 +1535,16 @@ export function createPiEventBridge(deps) {
                             durationMs: llmLatencyMs ?? 0,
                             inputTokens: usage.input,
                             outputTokens: usage.output,
-                            // W7 (obs-llm-troubleshooting): make degraded turns greppable from
+                            // 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).
+                            // (captured in this same turn_end); finishReason mirrors
+                            // the model.completed guard — forwarded only once it has
+                            // settled away from the init default "stop" (the context-exhaustion
+                            // 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)
+                            lastError: null, // error paths do not write this append site; always null here
+                            source: "runtime", // provenance stamp (production rows)
                         });
                         // Safety: check budget after recording (delegated to bridge-safety-controls)
                         {
@@ -1545,7 +1556,7 @@ export function createPiEventBridge(deps) {
                                 emitBudgetAbort(deps, m.totalTokens);
                             }
                         }
-                        // Safety: the dollars kill-switch (Phase 177). ADMISSION-BOUNDED +
+                        // Safety: the dollars kill-switch. 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
@@ -1573,12 +1584,12 @@ export function createPiEventBridge(deps) {
                             let spendBreachCurrentUsd = 0;
                             let spendBreachCapUsd = 0;
                             const spendEmit = {
-                                // WR-1 (177-obs-loop): emit the breaching warn DIMENSION the
+                                // 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).
+                                // the one that crossed).
                                 spendWarning: (warn) => deps.eventBus.emit("observability:spend_warning", {
                                     timestamp: systemNowMs(),
                                     agentId: deps.agentId,
@@ -1634,12 +1645,12 @@ export function createPiEventBridge(deps) {
                                 }
                             }
                         }
-                        // Phase 213-08 (BUDGET-01/02): the PER-ROOT budget reserve — a SIBLING
-                        // to the Phase-177 checkSpendCeiling above. Where that ceiling is
+                        // The PER-ROOT budget reserve — a SIBLING
+                        // to the 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).
+                        // native-provider model where the $-cap can never bite.
                         //
                         // ADDITIVE + gated on the holder ALONE (NOT spendAccumulator): a
                         // zero-price loop runs with the $-ceiling off yet must still trip the
@@ -1651,37 +1662,44 @@ export function createPiEventBridge(deps) {
                         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
+                            // 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
+                            // aborting a turn after wallClockMs of wall-clock AGE (observed
+                            // live). 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).
+                            // (the 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.
+                            // and the turn's true totalTokens. The $ figure is the ACTUAL corrected
+                            // cost of THIS call (`cost.total`), NOT the perTurnMax admission
+                            // estimate: the sibling ceiling releases its estimate at the billing
+                            // point (`reconcile` to $0, actuals recorded by the daemon-wide
+                            // token_usage subscriber), but the per-root accumulator has NO separate
+                            // actual-adder — whatever is reserved here IS its accrual. Reserving
+                            // the estimate made the $-limb a calls-counter (perTurnMax × N), which
+                            // consumed a $2 cap in 4 calls and wedged live sessions at pennies of
+                            // real spend. This reserve runs post-record, so the actual is known.
                             const perRootModel = deps.getCurrentModel?.() ?? deps.model;
-                            const perRootEstUsd = deps.spendConfig?.perTurnMax ?? 0;
+                            const perRootEstUsd = cost.total;
                             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
+                                // 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
+                                // 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).
+                                // exceeded" log line. The WARN stays content-free.
                                 emitSpendAbort(deps, "per_root", rootGate.error.limb !== undefined
                                     ? {
                                         limb: rootGate.error.limb,
@@ -1961,7 +1979,7 @@ export function createPiEventBridge(deps) {
                 const turnMsg = event.message;
                 if (turnMsg && "stopReason" in turnMsg && turnMsg.stopReason === "error") {
                     m.lastLlmErrorMessage = turnMsg.errorMessage ?? "Unknown LLM error";
-                    // HR-01 (v2.19): a ContextExhaustionError thrown by the context-engine
+                    // 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
@@ -2151,10 +2169,10 @@ export function createPiEventBridge(deps) {
     const getDrainState = () => ({
         drainInflightByKey: m.drainInflightByKey,
     });
-    // ATTR-01: ReadonlySet view of the per-turn attributed skill ids. The
+    // 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)
+    // Reuse-attribution UNION: the explicit-`read` attributions (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.

package/node_modules/@comis/agent/dist/bridge/tool-failure-hint.d.ts

@@ -9,9 +9,9 @@
  * inside `.content[].text` rather than at the very start — search anywhere for
  * the first snake_case bracketed token.
  *
- * Surfacing that code in the hint names the failure CATEGORY (the §2.7
- * "name which knob" rule) instead of the generic "check errorText" — which, in
- * the 2026-06-20 live run (UC-C2), pointed a tmux/macOS dependency diagnosis at
+ * Surfacing that code in the hint names the failure CATEGORY (the AGENTS.md
+ * §2.7 "name which knob" rule) instead of the generic "check errorText" — which,
+ * in a 2026-06-20 live run, pointed a tmux/macOS dependency diagnosis at
  * what was actually a command-allowlist policy block. `errorKind` is left
  * unchanged (this is an advisory hint enrichment — no obs-classifier ripple).
  *

package/node_modules/@comis/agent/dist/bridge/tool-failure-hint.js

@@ -10,9 +10,9 @@
  * inside `.content[].text` rather than at the very start — search anywhere for
  * the first snake_case bracketed token.
  *
- * Surfacing that code in the hint names the failure CATEGORY (the §2.7
- * "name which knob" rule) instead of the generic "check errorText" — which, in
- * the 2026-06-20 live run (UC-C2), pointed a tmux/macOS dependency diagnosis at
+ * Surfacing that code in the hint names the failure CATEGORY (the AGENTS.md
+ * §2.7 "name which knob" rule) instead of the generic "check errorText" — which,
+ * in a 2026-06-20 live run, pointed a tmux/macOS dependency diagnosis at
  * what was actually a command-allowlist policy block. `errorKind` is left
  * unchanged (this is an advisory hint enrichment — no obs-classifier ripple).
  *

package/node_modules/@comis/agent/dist/bridge/tool-name-suggest.d.ts

@@ -1,5 +1,5 @@
 /**
- * Recover a hallucinated tool name to the closest REAL tool (F-13, live 2026-06-12).
+ * Recover a hallucinated tool name to the closest REAL tool (live incident 2026-06-12).
  *
  * Small models routinely guess a wrong tool name — most often by mimicking the MCP
  * naming convention (`mcp__<server>--<verb>`) for a BUILTIN tool, e.g. emitting

package/node_modules/@comis/agent/dist/bridge/tool-name-suggest.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Recover a hallucinated tool name to the closest REAL tool (F-13, live 2026-06-12).
+ * Recover a hallucinated tool name to the closest REAL tool (live incident 2026-06-12).
  *
  * Small models routinely guess a wrong tool name — most often by mimicking the MCP
  * naming convention (`mcp__<server>--<verb>`) for a BUILTIN tool, e.g. emitting

package/node_modules/@comis/agent/dist/budget/budget-guard.d.ts

@@ -28,7 +28,7 @@ export interface BudgetSnapshot {
 /**
  * Execution-local view of a budget guard returned by {@link BudgetGuard.resetExecution}.
  *
- * CR-01: the per-execution dimension (the running `total` and the effective cap)
+ * The per-execution dimension (the running `total` and the effective cap)
  * is owned by THIS handle, not by the shared per-agent guard. Two concurrent
  * executions of the same agentId therefore get two independent windows and can
  * never clobber each other's cap or accrued spend. The per-hour/per-day rolling
@@ -62,8 +62,8 @@ export interface BudgetGuard {
      * execution-local {@link ExecutionBudgetWindow} that OWNS this run's running
      * total + effective cap — the caller threads it into checkBudget/recordUsage
      * so concurrent executions of the same agent never share the per-execution
-     * dimension (CR-01). checkBudget enforces min(config.perExecution, cap): a
-     * child can only TIGHTEN, never RAISE, its per-execution budget (BUDGET-01).
+     * dimension. checkBudget enforces min(config.perExecution, cap): a
+     * child can only TIGHTEN, never RAISE, its per-execution budget.
      *
      * Calling resetExecution also re-points the guard's OWN checkBudget/recordUsage/
      * getSnapshot at the freshly-created window, preserving the legacy single-execution
@@ -92,7 +92,7 @@ export declare function createBudgetGuard(config: BudgetConfig, logger?: {
  *  - `free`        — a local/gateway-`free` model: NEVER trips a ceiling
  *                    (no false-DoS of local-first deployments).
  *  - `unpriceable` — a native-provider `unknown`-priced model that burned tokens
- *                    (the ffe11736 danger): the bridge ALWAYS emits
+ *                    (real spend with no price to meter it): the bridge ALWAYS emits
  *                    `observability:spend_unpriceable` (fail LOUD); whether it
  *                    aborts is gated on `onUnknownPricing`+`action` at the bridge.
  *  - `exceeded`    — a ceiling breach: the bridge routes it through the single

package/node_modules/@comis/agent/dist/budget/budget-guard.js

@@ -50,7 +50,7 @@ const ONE_DAY_MS = 24 * 60 * 60 * 1000;
 export function createBudgetGuard(config, logger) {
     // SHARED per-agent state: the rolling per-hour/per-day windows and the
     // last-estimate latch. These legitimately stay shared across every execution
-    // of this agent (CR-01: only the per-EXECUTION dimension must be local).
+    // of this agent (only the per-EXECUTION dimension must be local).
     let lastEstimate = 0;
     const entries = [];
     function prune() {
@@ -83,7 +83,7 @@ export function createBudgetGuard(config, logger) {
         return totalEstimate;
     }
     /**
-     * Create an execution-local window. CR-01: `executionTotal` and
+     * Create an execution-local window. `executionTotal` and
      * `effectiveExecutionCap` are closed over by THIS window only — never shared
      * across concurrent executions — while the rolling-window reads/writes
      * (`entries`/`sumWindow`) and the estimate latch stay on the shared guard.
@@ -158,7 +158,7 @@ export function createBudgetGuard(config, logger) {
             currentWindow.recordUsage(tokens);
         },
         resetExecution(cap) {
-            // CR-01: a FRESH execution-local window each reset. The returned handle
+            // A FRESH execution-local window each reset. The returned handle
             // is what concurrent callers thread through checkBudget/recordUsage so
             // they never share the per-execution total/cap. The guard's own legacy
             // methods follow the most-recent window (sequential-caller compatibility).
@@ -213,7 +213,8 @@ export function checkSpendCeiling(accumulator, scope, provider, model, estUsd, c
     //    entirely so a local-first deployment can never be falsely DoSed.
     if (state === "free")
         return ok({ kind: "free" });
-    // 3. Native-provider unknown + actually burned tokens → the ffe11736 danger.
+    // 3. Native-provider unknown + actually burned tokens → real spend that no
+    //    ceiling can meter.
     //    Surface the unpriceable signal ALWAYS (fail LOUD — the bridge emits
     //    observability:spend_unpriceable regardless of action); the bridge gates
     //    the abort on onUnknownPricing+action. NOT fail-open: we surface, we do