chainlesschain 0.163.6 → 0.163.8

package/src/commands/team.js

@@ -57,6 +57,7 @@ import {
 } from "../lib/agent-team/team-control-store.js";
 import { TeamProcessCheckpointBroker } from "../lib/agent-team/team-process-checkpoint.js";
 import { registerTeamDistributedCommands } from "./team-distributed.js";
+import { registerTeamMergeReviewCommands } from "./team-merge-review.js";
 import {
   sameFileStatIdentity,
   samePathHandleFileIdentity,
@@ -1451,6 +1452,7 @@ export function registerTeamCommand(program, { logger } = {}) {
     agentExecutor: spawnAgent,
     buildAgentPrompt: buildTeamAgentPrompt,
   });
+  registerTeamMergeReviewCommands(team, { logger: log });
 
   team
     .command("control-bindings")

package/src/data/changelog.json

@@ -1,6 +1,32 @@
 {
   "source": "CHANGELOG.md",
   "releases": [
+    {
+      "productVersion": null,
+      "cliVersion": "0.163.8",
+      "cliVersions": ["0.163.7", "0.163.8"],
+      "date": "2026-08-14",
+      "title": "",
+      "sections": [
+        {
+          "heading": "Added — cc CLI 0.163.8: governed recovery, merge review, and MCP resource templates",
+          "body": "> `chainlesschain` **0.163.7 → 0.163.8** (candidate; not yet published,\n> 2026-08-14).\n> CLI-only candidate; `@chainlesschain/personal-data-hub` remains **0.4.57**\n> and `@chainlesschain/agent-sdk` remains **0.1.7**.\n\n- **Crash-safe scheduler source persistence**: Agenda and Cowork authoritative\n  stores now reject unreadable, malformed, and non-object records instead of\n  treating them as empty state. Generation replacement uses private exclusive\n  temporary files, complete short-write loops, file fsync, atomic rename, and\n  POSIX directory fsync, while distinguishing pre-rename `not-committed`\n  failures from post-rename durability-unknown outcomes.\n- **Deterministic scheduler disk-fault closure**: fault injection covers ENOSPC,\n  partial writes, file and directory fsync failures, rename failures, corrupted\n  source stores, native SQLite `SQLITE_FULL` transaction rollback, Automation\n  source rollback atomicity, database truncation, and clean reopen behavior.\n  Routine and Loop retain their existing durable-store and append/CAS\n  protections.\n- **Governed Automation runtime recovery**: scheduler-backed Automation work can\n  expose exact-fence, control-revision, capability-bound pause and resume safe\n  points. Revisioned incidents support bounded retry or cancellation; retry\n  revalidates the exact dead-letter occurrence, run identity, fence, and error\n  evidence, while manual incidents are not silently replayed.\n- **Governed multi-agent merge review**: `cc team merge-review` subcommands\n  `preview|show|apply|rollback` provide stable file and hunk selection,\n  digest-bound decisions, durable conflict evidence, guarded cross-branch batch\n  publication, and retained-history rollback. Git hooks, repository-local\n  configuration, inherited environment, stale revisions, oversized selections,\n  and changed branch identities fail closed.\n- **Read-only MCP resource templates**: templates-only MCP servers can now\n  register the existing resource surface. The new\n  `list_mcp_resource_templates {server?}` tool reads the bounded discovery\n  cache, supports explicit server filtering, and lets the model instantiate a\n  concrete URI before using the existing `read_mcp_resource` boundary. It does\n  not add an implicit network request, subscription, or automatic URI\n  expansion.\n- **Explicit optional-protocol decisions**: resource templates enter the\n  production read-only surface; resource subscriptions, peer-controlled\n  logging, and completion remain deferred pending bounded consumers and\n  cancellation/recovery UX. MCP sampling remains undeclared and server\n  `createMessage` requests continue to return JSON-RPC `-32601`.\n- **Transaction-time scheduler fencing**: claim, renewal, and settlement paths\n  now read their lease clock inside the write transaction, preventing queue\n  wait time from turning a pre-transaction timestamp into a stale lease or\n  settlement decision.\n- **Formal scheduler soak evidence gate**: Linux, Windows, and macOS workflows\n  now exercise two-worker contention, lease/fence recovery, heartbeat renewal,\n  stale settlement rejection, outcome-unknown no-replay, DST/backlog behavior,\n  SQLite integrity, descendant cleanup, and bounded resource trends. The\n  campaign verifier requires at least four identity-bound formal segments whose\n  authoritative starts span at least 72 natural hours, with no gap above\n  30 hours.\n- **Release boundary**: the scheduler soak implementation and smoke matrices are\n  present, but the required 72-hour formal campaign has not completed; P2-4\n  therefore remains partially complete. Signed native distribution,\n  representative alias-removal telemetry, and the entire unmerged P2-2 native\n  clipboard-image host work remain outside this candidate.\n- **Release status**: final tag, source SHA, workflow run IDs, package digests,\n  provenance, and registry readback are intentionally omitted until the exact\n  `0.163.8` release merge commit passes complete `CLI CI` and\n  `CLI Strict Sandbox` matrices on Linux, Windows, and macOS, followed by the\n  dedicated npm release and independent public readback workflows."
+        }
+      ]
+    },
+    {
+      "productVersion": null,
+      "cliVersion": "0.163.7",
+      "cliVersions": ["0.163.6", "0.163.7"],
+      "date": "2026-08-14",
+      "title": "",
+      "sections": [
+        {
+          "heading": "Added — cc CLI 0.163.7: governed scheduler migration and causal observability",
+          "body": "> `chainlesschain` **0.163.6 → 0.163.7** (published from exact SHA\n> `3e997168621c53708a1682868c6cc4edc9baf15b`, 2026-08-14).\n> CLI-only release; `@chainlesschain/personal-data-hub` remains **0.4.57**\n> and `@chainlesschain/agent-sdk` remains **0.1.7**.\n\n- **Five-domain migration journal**: Agenda, Cowork Cron, Routine, Automation,\n  and Loop migrations use the scheduler store schema-v5 journal with\n  domain-typed source locators, immutable source/target digest bindings,\n  idempotent recovery, and fail-closed rejection of conflicting or ambiguous\n  legacy entries.\n- **Governed rollback controls**: the new scheduler migration `list`, `show`,\n  and `rollback` commands expose redacted migration status and blockers.\n  Rollback requires the latest evidence digest, an interactive TTY, and the\n  exact typed challenge before reopening any legacy source.\n- **Target-first recovery and CAS fencing**: rollback stops or restores the\n  scheduler target before restoring the legacy source, validates target\n  revision, definition and execution evidence, and makes terminal source\n  restoration retry-safe across process crashes. This is not a claim of one\n  atomic transaction across independent stores or filesystems.\n- **Fail-closed source identity**: Windows drive and UNC paths are canonicalized\n  while relative, incomplete and device-namespace paths are rejected.\n  Automation migration requires an existing native SQLite database and refuses\n  the non-durable sql.js fallback; Loop restoration remains bound to its durable\n  retirement fence, marker and original source digest.\n- **Windows persistence hardening**: team adjudication atomic replacement\n  retries only transient Windows `EACCES`, `EBUSY`, and `EPERM` sharing\n  failures with bounded backoff and authority-path revalidation. Exhausted,\n  non-transient, and non-Windows replacement failures continue to fail closed.\n- **Cross-platform CI hardening**: migration fixtures verify retirement fences\n  and canonical source identities consistently across operating systems, while\n  distributed-queue and authority test workers use bounded lifetimes and attach\n  result observers before short-lived children can exit. Terminal Skill\n  authority fixtures now use an explicit parent acknowledgement before clean\n  exit, removing Windows IPC exit-before-message ordering ambiguity without\n  weakening concurrent revocation assertions.\n- **Verified causal delivery reports**: scoped sessions can be bound by exact\n  transcript head and event count to digest-protected delivery states. The new\n  session observability commands export a redacted session-to-delivery graph\n  spanning diffs, gates, artifacts, pull requests, and merges, with exact\n  workspace, team, and policy filters.\n- **Fail-closed call-ledger budgets**: `call-ledger@1` brackets model, retry,\n  compaction, subagent, isolated-skill, and tool calls with known or unknown\n  settlements. Strict budget mode rejects exceeded and unevaluable results\n  instead of treating missing token, cost, retry, or tool-latency evidence as\n  zero.\n- **Background recovery authority hardening**: verified transcript CAS,\n  delegated recovery leases, IPC sender/nonce binding, bootstrap guards, exact\n  process-group termination checks, and terminal cleanup prevent uncertain or\n  still-live descendants from authorizing recovery or worktree deletion.\n- **Causal evidence boundary**: report bindings prove exact verified revisions,\n  not that a model call semantically caused a source hunk. Scope labels are not\n  identity or membership proofs, digests are not signatures, anti-rollback is\n  machine-local, and incomplete or legacy ledgers remain partial or unknown.\n- **Release boundary**: deterministic scheduler disk-fault closure landed after\n  this immutable release and is not attributed to its tarball. The\n  three-platform long-soak campaign, signed native distribution, and\n  representative alias-removal telemetry remained outside this release.\n- **Published release evidence**: immutable tag `v-npm-0-163-7` resolves to\n  exact source commit `3e997168621c53708a1682868c6cc4edc9baf15b`. Its Linux,\n  Windows, and macOS `CLI CI` (`31745391661`, attempt 2) and\n  `CLI Strict Sandbox` (`31745391321`) matrices passed; the dedicated npm\n  release (`31748153519`) completed its exact-SHA gate, immutable package,\n  Trusted Publishing, and signed provenance, and the independent public\n  readback (`31749404980`) succeeded. npm reports `latest=0.163.7`; the public\n  tarball SHA-1 is `5bfb7471643cfe4d4cd0b0a382b31c63fc1efdff` and SHA-256 is\n  `d7ca295e6cdb4e442ee7ad6bb9cc0b9d923f40de4eae395974d91b4dfab83a9d`."
+        }
+      ]
+    },
     {
       "productVersion": null,
       "cliVersion": "0.163.6",
@@ -10,7 +36,7 @@
       "sections": [
         {
           "heading": "Added — cc CLI 0.163.6: unified scheduler authority and automation control",
-          "body": "> `chainlesschain` **0.163.5 → 0.163.6** (candidate; not yet published,\n> 2026-08-12).\n> CLI-only candidate; `@chainlesschain/personal-data-hub` remains **0.4.57**\n> and `@chainlesschain/agent-sdk` remains **0.1.7**.\n\n- **Complete scheduler adapter migration**: Agenda monitors, Loop iterations,\n  Automation cron flows, Routine GitHub polling, channel automation events,\n  and the standalone daemon now execute through the shared scheduler service\n  with durable claims, definition snapshots, recovery fences, and bounded\n  retry/dead-letter behavior.\n- **Timezone and missed-run consistency**: Agenda and Cowork cron definitions\n  persist canonical IANA timezones, handle DST gaps and repeated civil times,\n  and collapse downtime to one latest due occurrence without replay storms.\n- **Shared scheduler permission and budget authority**: Agenda, Routine,\n  Cowork, Automation, and Loop bind exact capability policies to durable\n  revisions and use one transactional reservation/settlement path. Missing,\n  stale, disabled, exhausted, or inconsistent policy state fails closed;\n  retries reuse the original reservation instead of charging twice.\n- **Layered Automation enforcement**: the shared scheduler authority composes\n  with Automation's creator identity, connector permissions, live revocation,\n  and per-flow run/action budgets. Domain evidence and the scheduler policy\n  revision remain independently validated.\n- **Governed management surfaces**: scheduler policy inspection/update commands\n  require exact capabilities and revision CAS, while the Automation Center\n  exposes governed flow and Routine controls without bypassing backend\n  permission or budget checks.\n- **Known residuals**: durable outcome-unknown adjudication, complete mixed-\n  version migration/rollback, scheduler disk-fault closure, and the three-OS\n  long-soak matrix remain open. Signed native distribution and representative\n  alias-removal telemetry also remain outside this release.\n- **Release status**: final tag, source SHA, workflow run IDs, package digest,\n  provenance, and registry readback are intentionally omitted until the exact\n  `0.163.6` release commit passes the complete `CLI CI` and `CLI Strict Sandbox`\n  Linux, Windows, and macOS matrices, followed by the dedicated npm release and\n  independent public readback workflows."
+          "body": "> `chainlesschain` **0.163.5 → 0.163.6** (published from exact SHA\n> `85c3577c887003fea98d0a159603cd359506f09b`, 2026-08-12).\n> CLI-only release; `@chainlesschain/personal-data-hub` remains **0.4.57**\n> and `@chainlesschain/agent-sdk` remains **0.1.7**.\n\n- **Complete scheduler adapter migration**: Agenda monitors, Loop iterations,\n  Automation cron flows, Routine GitHub polling, channel automation events,\n  and the standalone daemon now execute through the shared scheduler service\n  with durable claims, definition snapshots, recovery fences, and bounded\n  retry/dead-letter behavior.\n- **Timezone and missed-run consistency**: Agenda and Cowork cron definitions\n  persist canonical IANA timezones, handle DST gaps and repeated civil times,\n  and collapse downtime to one latest due occurrence without replay storms.\n- **Shared scheduler permission and budget authority**: Agenda, Routine,\n  Cowork, Automation, and Loop bind exact capability policies to durable\n  revisions and use one transactional reservation/settlement path. Missing,\n  stale, disabled, exhausted, or inconsistent policy state fails closed;\n  retries reuse the original reservation instead of charging twice.\n- **Layered Automation enforcement**: the shared scheduler authority composes\n  with Automation's creator identity, connector permissions, live revocation,\n  and per-flow run/action budgets. Domain evidence and the scheduler policy\n  revision remain independently validated.\n- **Governed management surfaces**: scheduler policy inspection/update commands\n  require exact capabilities and revision CAS, while the Automation Center\n  exposes governed flow and Routine controls without bypassing backend\n  permission or budget checks.\n- **Known residuals**: durable outcome-unknown adjudication, complete mixed-\n  version migration/rollback, scheduler disk-fault closure, and the three-OS\n  long-soak matrix remain open. Signed native distribution and representative\n  alias-removal telemetry also remain outside this release.\n- **Published release evidence**: immutable tag `v-npm-0-163-6` resolves to\n  exact source commit `85c3577c887003fea98d0a159603cd359506f09b`. Its Linux,\n  Windows, and macOS `CLI CI` (`31595865423`) and `CLI Strict Sandbox`\n  (`31595865206`) matrices passed; the dedicated npm release (`31595865181`)\n  completed its exact-SHA gate, immutable package, Trusted Publishing, and\n  signed provenance, and the independent public readback (`31597577056`)\n  succeeded. npm reports `latest=0.163.6`; the public tarball SHA-1 is\n  `18bb9d807a4a35a36cf9049dcc15f67eb47bbfa6`."
         }
       ]
     },

package/src/gateways/ws/ws-agent-handler.js

@@ -11,6 +11,7 @@
  * adapter.
  */
 
+import { randomUUID } from "node:crypto";
 import { agentLoop, formatToolArgs } from "../../runtime/agent-core.js";
 import { classifyToolSideEffect } from "../../lib/side-effect-ledger.js";
 import { DiffReviewFollowUpTracker } from "../../lib/diff-review-follow-up.js";
@@ -37,12 +38,25 @@ import { createMcpHostRecoveryRuntime } from "../../lib/mcp-host-recovery-runtim
 import { compactConversationWithProvider } from "../../harness/provider-backed-compaction.js";
 import { projectCanonicalResumeMessages } from "../../lib/session-message-provenance.js";
 import { feature } from "../../lib/feature-flags.js";
+import { classifyStreamRetryReason } from "../../lib/stream-retry.js";
+import {
+  markRuntimeLedgerPersistenceError,
+  projectRuntimeTokenUsage,
+  projectRuntimeUsageBoundary,
+  runtimeToolCallId,
+  runtimeUsageEventType,
+} from "../../lib/runtime-usage-ledger.js";
 import {
   appendCompactEventIfMessagesMatch,
+  appendEvent,
+  appendLlmRetryCompact,
+  appendTokenUsage,
+  appendToolCallCompact,
   claimWsTurnIfHead,
   computeWsTurnInputDigest,
   createWsTurnClaimId,
   normalizeWsTurnRequestId,
+  readVerifiedProjection,
   readVerifiedWsTurnState,
   readVerifiedMessages,
   settleWsTurnClaim,
@@ -50,6 +64,59 @@ import {
 
 const CANONICAL_WS_TURN_QUEUES = new Map();
 const CANONICAL_WS_CLAIM_CAS_ATTEMPTS = 4;
+const CALL_LEDGER_PROTOCOL = "call-ledger";
+const CALL_LEDGER_VERSION = 1;
+const USAGE_LEDGER_PERSISTENCE_CODE = "CC_USAGE_LEDGER_PERSISTENCE_FAILED";
+const USAGE_LEDGER_PERSISTENCE_MESSAGE =
+  "Canonical usage ledger persistence failed; model and tool execution is blocked";
+
+function usageProtocolError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function classifyCanonicalUsageProtocol(data = {}) {
+  const record =
+    data && typeof data === "object" && !Array.isArray(data) ? data : {};
+  const hasScope = Object.hasOwn(record, "observabilityScope");
+  const hasProtocol = Object.hasOwn(record, "usageTelemetryProtocol");
+  const hasVersion = Object.hasOwn(record, "usageTelemetryVersion");
+  if (!hasScope && !hasProtocol && !hasVersion) return "legacy";
+  if (!hasProtocol || !hasVersion) {
+    throw usageProtocolError(
+      "CC_USAGE_LEDGER_PROTOCOL_REQUIRED",
+      "Canonical scoped sessions require call-ledger usage telemetry before model or tool execution",
+    );
+  }
+  if (
+    record.usageTelemetryProtocol !== CALL_LEDGER_PROTOCOL ||
+    record.usageTelemetryVersion !== CALL_LEDGER_VERSION
+  ) {
+    throw usageProtocolError(
+      "CC_USAGE_LEDGER_PROTOCOL_UNSUPPORTED",
+      "Canonical session usage telemetry protocol is unsupported",
+    );
+  }
+  return "call-ledger";
+}
+
+export function readCanonicalUsageProtocol(sessionId, projectionReader) {
+  if (typeof projectionReader !== "function") return "legacy";
+  return projectionReader(sessionId, () => {
+    let sessionStart = null;
+    return {
+      accept(event) {
+        if (event?.type === "session_start" && sessionStart === null) {
+          sessionStart = event.data || {};
+        }
+      },
+      finish() {
+        return classifyCanonicalUsageProtocol(sessionStart || {});
+      },
+    };
+  });
+}
 
 function runCanonicalWsTurnExclusive(sessionId, task) {
   const previous = CANONICAL_WS_TURN_QUEUES.get(sessionId) || Promise.resolve();
@@ -137,17 +204,33 @@ export class WSAgentHandler {
         const { chatWithTools } = await import("../../runtime/agent-core.js");
         return chatWithTools(...args);
       });
+    const injectedCanonicalStore = canonicalSessionStore || null;
     this._canonicalSessionStore = {
       appendCompactEventIfMessagesMatch,
+      appendEvent,
+      appendLlmRetryCompact,
+      appendTokenUsage,
+      appendToolCallCompact,
       claimWsTurnIfHead,
       computeWsTurnInputDigest,
       createWsTurnClaimId,
       normalizeWsTurnRequestId,
+      readVerifiedProjection,
       readVerifiedWsTurnState,
       readVerifiedMessages,
       settleWsTurnClaim,
       ...(canonicalSessionStore || {}),
     };
+    // Test/embedding stores historically injected only WS-turn CAS methods.
+    // Preserve that compatibility as legacy unless they explicitly provide a
+    // verified projection reader. The production store always supplies one.
+    this._canonicalUsageProjectionReader =
+      injectedCanonicalStore &&
+      typeof injectedCanonicalStore.readVerifiedProjection !== "function"
+        ? null
+        : this._canonicalSessionStore.readVerifiedProjection;
+    this._canonicalUsageProtocol = null;
+    this._usageLedgerFailure = null;
     const explicitHostPrefix = Array.isArray(
       session?._canonicalHostSystemPrefix,
     )
@@ -188,6 +271,159 @@ export class WSAgentHandler {
     return this.session.messages;
   }
 
+  _resolveCanonicalUsageProtocol() {
+    if (this.session.canonicalJsonlSession !== true) return "legacy";
+    if (this._canonicalUsageProtocol) return this._canonicalUsageProtocol;
+
+    // An embedding may attach the immutable session-start declaration directly
+    // while supplying a partial canonical store. Never ignore such a marker.
+    const attachedDeclaration = {};
+    for (const field of [
+      "observabilityScope",
+      "usageTelemetryProtocol",
+      "usageTelemetryVersion",
+    ]) {
+      if (Object.hasOwn(this.session, field)) {
+        attachedDeclaration[field] = this.session[field];
+      }
+    }
+    const attachedMode = classifyCanonicalUsageProtocol(attachedDeclaration);
+    if (attachedMode !== "legacy") {
+      this._canonicalUsageProtocol = attachedMode;
+      return attachedMode;
+    }
+
+    this._canonicalUsageProtocol = readCanonicalUsageProtocol(
+      this.session.id,
+      this._canonicalUsageProjectionReader,
+    );
+    return this._canonicalUsageProtocol;
+  }
+
+  _usageLedgerTerminalError(cause = null) {
+    const error = new Error(USAGE_LEDGER_PERSISTENCE_MESSAGE, {
+      ...(cause ? { cause } : {}),
+    });
+    error.code = USAGE_LEDGER_PERSISTENCE_CODE;
+    error.runtimeLedgerPersistence = true;
+    return error;
+  }
+
+  _latchUsageLedgerFailure(error) {
+    const marked = markRuntimeLedgerPersistenceError(error);
+    this._usageLedgerFailure ||= Object.freeze({
+      code: USAGE_LEDGER_PERSISTENCE_CODE,
+      reason: "canonical_usage_ledger_persistence_failed",
+    });
+    return this._usageLedgerTerminalError(marked);
+  }
+
+  _assertUsageLedgerWritable() {
+    if (this._usageLedgerFailure) throw this._usageLedgerTerminalError();
+  }
+
+  _callCanonicalLedgerStore(method, ...args) {
+    this._assertUsageLedgerWritable();
+    try {
+      const result = this._canonicalSessionStore[method](...args);
+      if (result && typeof result.then === "function") {
+        void Promise.resolve(result).catch(() => {});
+        throw new TypeError(
+          `Canonical usage ledger ${method} must be synchronous`,
+        );
+      }
+      return result;
+    } catch (error) {
+      throw this._latchUsageLedgerFailure(error);
+    }
+  }
+
+  _persistCanonicalUsageBoundary(event, outcome) {
+    let projected;
+    try {
+      projected = projectRuntimeUsageBoundary(event, outcome);
+    } catch (error) {
+      throw this._latchUsageLedgerFailure(error);
+    }
+    this._callCanonicalLedgerStore(
+      "appendEvent",
+      this.session.id,
+      runtimeUsageEventType(outcome),
+      projected,
+    );
+  }
+
+  _persistCanonicalTokenUsage(event) {
+    let projected;
+    try {
+      projected = projectRuntimeTokenUsage(event);
+    } catch (error) {
+      throw this._latchUsageLedgerFailure(error);
+    }
+    this._callCanonicalLedgerStore(
+      "appendTokenUsage",
+      this.session.id,
+      projected,
+    );
+  }
+
+  _persistCanonicalUsageSettlement(event) {
+    if (event?.type === "token-usage") {
+      this._persistCanonicalTokenUsage(event);
+      return;
+    }
+    this._persistCanonicalUsageBoundary(event, "unknown");
+  }
+
+  _beginCanonicalCompactionUsage() {
+    const call = Object.freeze({
+      callId: `ws-cmp-${randomUUID()}`,
+      provider: this.session.provider || null,
+      model: this.session.model || null,
+      source: "semantic-compaction",
+    });
+    this._persistCanonicalUsageBoundary(call, "started");
+    return call;
+  }
+
+  _settleCanonicalCompactionUsage(call, result) {
+    if (!call) return;
+    const unknown = result?.usageUnknownEvent || null;
+    if (unknown) {
+      const reason = unknown.reason || "provider_transport_outcome_unknown";
+      this._persistCanonicalUsageBoundary(
+        {
+          ...call,
+          code:
+            reason === "provider_usage_not_reported"
+              ? "provider_usage_missing"
+              : unknown.code || "provider_call_failed",
+        },
+        "unknown",
+      );
+      return;
+    }
+    if (result?.usageEvent?.usage) {
+      this._persistCanonicalTokenUsage({
+        ...call,
+        usage: result.usageEvent.usage,
+      });
+      return;
+    }
+    this._persistCanonicalUsageBoundary(
+      { ...call, code: "provider_usage_missing" },
+      "unknown",
+    );
+  }
+
+  _settleCanonicalCompactionFailure(call) {
+    if (!call) return;
+    this._persistCanonicalUsageBoundary(
+      { ...call, code: "provider_call_failed" },
+      "unknown",
+    );
+  }
+
   _latchCompactionSettlement({
     code,
     reason,
@@ -286,6 +522,10 @@ export class WSAgentHandler {
 
     const before = session.messages.length;
     const expectedMessages = [...session.messages];
+    const strictUsageTelemetry =
+      this._resolveCanonicalUsageProtocol() === "call-ledger";
+    let compactionUsageCall = null;
+    let compactionUsageSettled = false;
     let result;
     try {
       this._sessionHostLease?.assert?.();
@@ -303,13 +543,35 @@ export class WSAgentHandler {
           cwd: session.projectRoot,
           sessionId: session.id,
         },
+        ...(strictUsageTelemetry
+          ? {
+              onProviderCallStart: () => {
+                const call = this._beginCanonicalCompactionUsage();
+                compactionUsageCall = call;
+                return call.callId;
+              },
+            }
+          : {}),
         maxMessages: session.compactionMaxMessages,
         maxTokens: session.compactionMaxTokens,
         maxOutputTokens: session.compactionMaxOutputTokens,
         summaryInputMaxChars: session.compactionInputMaxChars,
       });
+      if (compactionUsageCall) {
+        this._settleCanonicalCompactionUsage(compactionUsageCall, result);
+        compactionUsageSettled = true;
+      }
       this._sessionHostLease?.assert?.();
     } catch (error) {
+      if (
+        compactionUsageCall &&
+        !compactionUsageSettled &&
+        error?.runtimeLedgerPersistence !== true
+      ) {
+        this._settleCanonicalCompactionFailure(compactionUsageCall);
+        compactionUsageSettled = true;
+      }
+      if (error?.runtimeLedgerPersistence === true) throw error;
       if (isAbortError(error) || this._sessionHostLease?.signal?.aborted) {
         throw error;
       }
@@ -755,6 +1017,7 @@ export class WSAgentHandler {
     let diffReviewFollowUps = null;
     let runRecorded = false;
     let canonicalTurn = null;
+    let strictUsageTelemetry = false;
 
     try {
       const { session } = this;
@@ -776,6 +1039,9 @@ export class WSAgentHandler {
           inputDigest,
         );
         if (!canonicalTurn) {
+          strictUsageTelemetry =
+            this._resolveCanonicalUsageProtocol() === "call-ledger";
+          if (strictUsageTelemetry) this._assertUsageLedgerWritable();
           const compacted =
             await this._compactCanonicalHistoryBeforeClaim(requestId);
           if (!compacted) return;
@@ -886,6 +1152,27 @@ export class WSAgentHandler {
         ...(session.canonicalJsonlSession === true
           ? { autoCompact: false }
           : {}),
+        ...(strictUsageTelemetry
+          ? {
+              strictUsageTelemetry: true,
+              onUsageBoundary: (event) =>
+                this._persistCanonicalUsageBoundary(event, "started"),
+              onUsageSettlement: (event) =>
+                this._persistCanonicalUsageSettlement(event),
+              onStreamRetry: (attempt, error, telemetry = {}) =>
+                this._callCanonicalLedgerStore(
+                  "appendLlmRetryCompact",
+                  session.id,
+                  {
+                    attempt,
+                    durationMs: telemetry.durationMs,
+                    provider: telemetry.provider || session.provider,
+                    model: telemetry.model || activeModel,
+                    reason: classifyStreamRetryReason(error),
+                  },
+                ),
+            }
+          : {}),
       };
 
       // P0-2: crash-safe side-effect ledger for the IDE/bridge path — mirrors
@@ -897,6 +1184,68 @@ export class WSAgentHandler {
       diffReviewFollowUps = new DiffReviewFollowUpTracker(sideEffectLedger);
       let currentSideEffectOpId = null;
       let currentTodoWrite = null;
+      const activeToolCalls = new Map();
+      const activeToolCallOrder = [];
+      const boundedToolUseId = (value) =>
+        typeof value === "string" &&
+        value.trim() &&
+        value.length <= 128 &&
+        !/\p{Cc}/u.test(value)
+          ? value.trim()
+          : null;
+      const boundedToolName = (value) => {
+        if (typeof value !== "string") return "?";
+        const clean = value.replace(/\p{Cc}/gu, "").trim();
+        return clean ? clean.slice(0, 160) : "?";
+      };
+      const beginToolUsage = (event) => {
+        const providerId = boundedToolUseId(event.tool_use_id);
+        const record = {
+          id: runtimeToolCallId(providerId || undefined),
+          providerId,
+          tool: boundedToolName(event.tool),
+          startedAt: Date.now(),
+        };
+        this._callCanonicalLedgerStore(
+          "appendEvent",
+          session.id,
+          "tool_call_started",
+          { id: record.id, tool: record.tool },
+        );
+        activeToolCallOrder.push(record);
+        if (providerId) activeToolCalls.set(providerId, record);
+      };
+      const settleToolUsage = (event) => {
+        const providerId = boundedToolUseId(event.tool_use_id);
+        const record =
+          (providerId ? activeToolCalls.get(providerId) : null) ||
+          activeToolCallOrder.find(
+            (entry) => entry.tool === boundedToolName(event.tool),
+          ) ||
+          null;
+        if (!record) return;
+        const durationMs =
+          event.result?.toolTelemetryRecord?.durationMs ??
+          Math.max(0, Date.now() - record.startedAt);
+        this._callCanonicalLedgerStore("appendToolCallCompact", session.id, {
+          id: record.id,
+          tool: record.tool,
+          isError: Boolean(event.error || event.result?.error),
+          skill:
+            event?.attribution?.skill ||
+            (record.tool === "run_skill"
+              ? event.result?.skill || event.result?.skill_name || undefined
+              : undefined),
+          durationMs,
+        });
+        if (record.providerId) activeToolCalls.delete(record.providerId);
+        const index = activeToolCallOrder.indexOf(record);
+        if (index >= 0) activeToolCallOrder.splice(index, 1);
+      };
+      if (strictUsageTelemetry) {
+        loopOptions.onToolCallBoundary = beginToolUsage;
+        loopOptions.onToolCallSettlement = settleToolUsage;
+      }
 
       const executeAgentTurn = async () => {
         for await (const event of this._agentLoop(
@@ -913,6 +1262,7 @@ export class WSAgentHandler {
               break;
 
             case "tool-executing":
+              if (strictUsageTelemetry) beginToolUsage(event);
               this.interaction.emit("tool-executing", {
                 requestId,
                 tool: event.tool,
@@ -953,6 +1303,7 @@ export class WSAgentHandler {
               break;
 
             case "tool-result":
+              if (strictUsageTelemetry) settleToolUsage(event);
               this.interaction.emit("tool-result", {
                 requestId,
                 tool: event.tool,
@@ -1007,9 +1358,24 @@ export class WSAgentHandler {
               break;
 
             case "compaction-usage-unknown":
+              if (strictUsageTelemetry && event.ledgerPersisted !== true) {
+                this._persistCanonicalUsageBoundary(event, "unknown");
+              }
               this._emitCompactionUsageUnknown(requestId, event);
               break;
 
+            case "model-usage-started":
+              if (strictUsageTelemetry && event.ledgerPersisted !== true) {
+                this._persistCanonicalUsageBoundary(event, "started");
+              }
+              break;
+
+            case "model-usage-unknown":
+              if (strictUsageTelemetry && event.ledgerPersisted !== true) {
+                this._persistCanonicalUsageBoundary(event, "unknown");
+              }
+              break;
+
             case "compaction":
               this.interaction.emit("compaction", {
                 requestId,
@@ -1018,6 +1384,9 @@ export class WSAgentHandler {
               break;
 
             case "token-usage":
+              if (strictUsageTelemetry && event.ledgerPersisted !== true) {
+                this._persistCanonicalTokenUsage(event);
+              }
               this.interaction.emit("token-usage", {
                 requestId,
                 provider: event.provider,
@@ -1122,6 +1491,12 @@ export class WSAgentHandler {
         );
         surfacedError.code = "CC_WS_TURN_SETTLEMENT_UNKNOWN";
       }
+      if (
+        surfacedError?.runtimeLedgerPersistence === true &&
+        surfacedError?.code !== "CC_WS_TURN_SETTLEMENT_UNKNOWN"
+      ) {
+        surfacedError = this._usageLedgerTerminalError(surfacedError);
+      }
       if (canonicalTurn?.baseMessages && canonicalTurn.status !== "completed") {
         this.session.messages = [...canonicalTurn.baseMessages];
       }
@@ -1312,10 +1687,41 @@ export class WSAgentHandler {
           break;
         }
 
+        let strictUsageTelemetry = false;
+        if (session.canonicalJsonlSession === true) {
+          try {
+            strictUsageTelemetry =
+              this._resolveCanonicalUsageProtocol() === "call-ledger";
+            if (strictUsageTelemetry) this._assertUsageLedgerWritable();
+          } catch (error) {
+            const admission = {
+              code: error?.code || "CC_USAGE_LEDGER_ADMISSION_FAILED",
+              reason: "canonical_usage_telemetry_admission_failed",
+            };
+            this.interaction.emit("compaction-degraded", {
+              requestId,
+              reason: admission.reason,
+              summaryMode: "none",
+              code: admission.code,
+            });
+            this.interaction.emit("command-response", {
+              requestId,
+              command: cmd,
+              result: {
+                messageCount: session.messages.length,
+                error: admission,
+              },
+            });
+            break;
+          }
+        }
+
         const before = session.messages.length;
         const expectedMessages = [...session.messages];
         let result = null;
         let commandError = null;
+        let compactionUsageCall = null;
+        let compactionUsageSettled = false;
         try {
           this._sessionHostLease?.assert?.();
           result = await compactConversationWithProvider(session.messages, {
@@ -1332,19 +1738,47 @@ export class WSAgentHandler {
               cwd: session.projectRoot,
               sessionId: session.id,
             },
+            ...(strictUsageTelemetry
+              ? {
+                  onProviderCallStart: () => {
+                    const call = this._beginCanonicalCompactionUsage();
+                    compactionUsageCall = call;
+                    return call.callId;
+                  },
+                }
+              : {}),
             maxOutputTokens: session.compactionMaxOutputTokens,
             summaryInputMaxChars: session.compactionInputMaxChars,
           });
+          if (compactionUsageCall) {
+            this._settleCanonicalCompactionUsage(compactionUsageCall, result);
+            compactionUsageSettled = true;
+          }
           this._sessionHostLease?.assert?.();
         } catch (error) {
+          if (
+            compactionUsageCall &&
+            !compactionUsageSettled &&
+            error?.runtimeLedgerPersistence !== true
+          ) {
+            this._settleCanonicalCompactionFailure(compactionUsageCall);
+            compactionUsageSettled = true;
+          }
           if (isAbortError(error) || this._sessionHostLease?.signal?.aborted) {
             throw error;
           }
-          commandError = this._latchCompactionSettlement({
-            code: error?.code || "CC_COMPACTION_FAILED",
-            reason: `compaction_failed:${String(error?.message || error).slice(0, 240)}`,
-            commitState: "provider-outcome-unknown",
-          });
+          commandError =
+            error?.runtimeLedgerPersistence === true
+              ? {
+                  code: USAGE_LEDGER_PERSISTENCE_CODE,
+                  reason: "canonical_usage_ledger_persistence_failed",
+                  commitState: "usage-ledger-failed",
+                }
+              : this._latchCompactionSettlement({
+                  code: error?.code || "CC_COMPACTION_FAILED",
+                  reason: `compaction_failed:${String(error?.message || error).slice(0, 240)}`,
+                  commitState: "provider-outcome-unknown",
+                });
           this.interaction.emit("compaction-degraded", {
             requestId,
             reason: commandError.reason,