@chorus-aidlc/chorus 0.14.2 → 0.14.3

package/.next/standalone/public/chorus-plugin/skills/chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus AI Agent collaboration platform — overview, common tools,
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/chorus-plugin/skills/develop/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Development workflow — claim tasks, report work, manage se
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/chorus-plugin/skills/idea/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Idea workflow — claim ideas, run elaboration rounds, and p
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/chorus-plugin/skills/openspec-aware/SKILL.md

@@ -4,7 +4,7 @@ description: Opt-in OpenSpec-mode authoring for Chorus PM workflows in Claude Co
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---
@@ -90,7 +90,7 @@ chorus-api.sh mcp-tool <tool_name> "$PAYLOAD"
 with `$PAYLOAD` built using `json_encode_file` (defined in §3.4). Calling these tools directly from the agent's MCP harness with a hand-typed `content` field is a **protocol violation** for OpenSpec mode and will fail review. Reasons:
 
 1. **Token cost.** Re-typing a multi-thousand-line markdown body through the LLM burns input + output tokens for every draft. The wrapper streams bytes through `jq -Rs '.'` — content never enters LLM context. A typical 3-doc proposal mirror via the script costs roughly zero content-tokens; via direct MCP it routinely costs 20k+.
-2. **Byte-equality.** `jq -Rs '.'` is a byte-faithful encoder: backslashes, quotes, newlines, code-fence content, zero-width chars all survive. LLM re-emission has a non-zero failure rate on long markdown — table alignment drifts, fence escapes get "fixed", long URLs wrap. The byte-equality guarantee (modulo trailing `\n`) holds **only** on the wrapper path.
+2. **Byte-equality.** `jq -Rs '.'` is a byte-faithful encoder: backslashes, quotes, newlines, code-fence content, zero-width chars all survive. LLM re-emission has a non-zero failure rate on long markdown — table alignment drifts, fence escapes get "fixed", long URLs wrap. The exact byte-equality guarantee holds **only** on the wrapper path.
 3. **Single source of truth.** With the wrapper, the local `openspec/changes/<slug>/*.md` is authoritative and Chorus is a mirror. With agent re-typing, authority splits between local file and whatever the LLM happened to output — a future diff cannot tell which one is correct.
 
 ### Rule 2 — Halt on error via `chorus_check_response`
@@ -226,7 +226,7 @@ json_encode_file() {
 }
 ```
 
-Round-trip: the Chorus backend appends a single `\n` to draft content on write, so server `content` is **byte-equal modulo a trailing newline**. Reviewers diffing local file vs server should ignore that one byte.
+Round-trip verification is exact: a trailing newline difference is real drift and MUST NOT be normalized or ignored.
 
 ### 3.5 Create the proposal container with the slug provenance line
 
@@ -329,7 +329,11 @@ The hook is read-only; you (the agent) perform the archive:
 
 3. **Halt on any error** from `openspec archive` or `chorus_pm_update_document`. Print stderr verbatim, post a comment on the proposal recording the failure (`chorus_add_comment` with `targetType: "proposal"`, `targetUuid: <proposalUuid>`), then stop. No retry. Matches §6 "no silent errors." (Comment on the proposal, not the idea: the failure is in archiving proposal-derived specs, and proposals can be `inputType: "document"` with no idea attached.)
 
-4. **Confirm success.** List `openspec/specs/<capability>/spec.md` files and verify they round-trip byte-equal (modulo trailing newline) with their Chorus Document counterparts.
+4. **Confirm success.** Resolve each matching Document UUID and run
+   `verify-document-roundtrip.sh <local-spec-path> <document-uuid>`. This
+   performs exact-byte comparison and metadata-only mismatch diagnostics. Do
+   not replace it with recursive `jq`, `head`, command substitution, or newline
+   normalization.
 
 **Strict opt-in:** if the verified task is not the last of its idea, OR the proposal description carries no `OpenSpec change slug: <slug>` line, OR the local shell has no `openspec` CLI, the hook exits 0 silently and no archive reminder is injected. Existing free-form behavior is preserved.
 

package/.next/standalone/public/chorus-plugin/skills/proposal/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Proposal workflow — create proposals with document and tas
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/chorus-plugin/skills/quick-dev/SKILL.md

@@ -4,7 +4,7 @@ description: Quick Task workflow — skip Idea→Proposal, create tasks directly
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/chorus-plugin/skills/review/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Review workflow — approve/reject proposals, verify tasks,
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/chorus-plugin/skills/yolo/SKILL.md

@@ -4,7 +4,7 @@ description: Full-auto AI-DLC pipeline — from prompt to done. Automates the en
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/install-kiro.sh

@@ -44,7 +44,7 @@ is_tty() { [ -t 0 ] && [ -t 1 ]; }
 # source modes can never diverge.
 SKILLS="chorus-idea chorus-proposal chorus-develop chorus-yolo chorus-review chorus-quick-dev chorus-brainstorm chorus-openspec-aware"
 REVIEWER_AGENTS="chorus-code-reviewer chorus-proposal-reviewer chorus-task-reviewer"
-HOOK_SCRIPTS="on-agent-spawn.sh on-stop.sh on-post-submit-proposal.sh on-post-submit-for-verify.sh on-post-verify-task.sh chorus-api.sh test-syntax.sh"
+HOOK_SCRIPTS="on-agent-spawn.sh on-stop.sh on-post-submit-proposal.sh on-post-submit-for-verify.sh on-post-verify-task.sh chorus-api.sh verify-document-roundtrip.sh test-syntax.sh"
 
 CHORUS_URL_DEFAULT="${CHORUS_URL_DEFAULT:-http://localhost:8637/api/mcp}"
 

package/.next/standalone/public/kiro-plugin/.kiro/skills/chorus-brainstorm/SKILL.md

@@ -4,7 +4,7 @@ description: Optional divergent-then-convergent dialogue for fuzzy ideas. Invoke
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/kiro-plugin/.kiro/skills/chorus-develop/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Development workflow — claim tasks, report work, manage se
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/kiro-plugin/.kiro/skills/chorus-idea/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Idea workflow — claim ideas, run elaboration rounds, and p
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/kiro-plugin/.kiro/skills/chorus-openspec-aware/SKILL.md

@@ -4,7 +4,7 @@ description: Opt-in OpenSpec-mode authoring for Chorus PM workflows in Kiro CLI.
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---
@@ -88,7 +88,7 @@ chorus-api.sh mcp-tool <tool_name> "$PAYLOAD"
 with `$PAYLOAD` built using `json_encode_file` (defined in §3.4). Calling these tools directly from the agent's MCP harness with a hand-typed `content` field is a **protocol violation** for OpenSpec mode and will fail review. Reasons:
 
 1. **Token cost.** Re-typing a multi-thousand-line markdown body through the LLM burns input + output tokens for every draft. The wrapper streams bytes through `jq -Rs '.'` — content never enters LLM context. A typical 3-doc proposal mirror via the script costs roughly zero content-tokens; via direct MCP it routinely costs 20k+.
-2. **Byte-equality.** `jq -Rs '.'` is a byte-faithful encoder: backslashes, quotes, newlines, code-fence content, zero-width chars all survive. LLM re-emission has a non-zero failure rate on long markdown — table alignment drifts, fence escapes get "fixed", long URLs wrap. The byte-equality guarantee (modulo trailing `\n`) holds **only** on the wrapper path.
+2. **Byte-equality.** `jq -Rs '.'` is a byte-faithful encoder: backslashes, quotes, newlines, code-fence content, zero-width chars all survive. LLM re-emission has a non-zero failure rate on long markdown — table alignment drifts, fence escapes get "fixed", long URLs wrap. The exact byte-equality guarantee holds **only** on the wrapper path.
 3. **Single source of truth.** With the wrapper, the local `openspec/changes/<slug>/*.md` is authoritative and Chorus is a mirror. With agent re-typing, authority splits between local file and whatever the LLM happened to output — a future diff cannot tell which one is correct.
 
 ### Rule 2 — Halt on error via `chorus_check_response`
@@ -224,7 +224,7 @@ json_encode_file() {
 }
 ```
 
-Round-trip: the Chorus backend appends a single `\n` to draft content on write, so server `content` is **byte-equal modulo a trailing newline**. Reviewers diffing local file vs server should ignore that one byte.
+Round-trip verification is exact: a trailing newline difference is real drift and MUST NOT be normalized or ignored.
 
 ### 3.5 Create the proposal container with the slug provenance line
 
@@ -327,7 +327,11 @@ The hook is read-only; you (the agent) perform the archive:
 
 3. **Halt on any error** from `openspec archive` or `chorus_pm_update_document`. Print stderr verbatim, post a comment on the proposal recording the failure (`chorus_add_comment` with `targetType: "proposal"`, `targetUuid: <proposalUuid>`), then stop. No retry. Matches §6 "no silent errors." (Comment on the proposal, not the idea: the failure is in archiving proposal-derived specs, and proposals can be `inputType: "document"` with no idea attached.)
 
-4. **Confirm success.** List `openspec/specs/<capability>/spec.md` files and verify they round-trip byte-equal (modulo trailing newline) with their Chorus Document counterparts.
+4. **Confirm success.** Resolve each matching Document UUID and run
+   `verify-document-roundtrip.sh <local-spec-path> <document-uuid>`. This
+   performs exact-byte comparison and metadata-only mismatch diagnostics. Do
+   not replace it with recursive `jq`, `head`, command substitution, or newline
+   normalization.
 
 **Strict opt-in:** if the verified task is not the last of its idea, OR the proposal description carries no `OpenSpec change slug: <slug>` line, OR the local shell has no `openspec` CLI, the hook exits 0 silently and no archive reminder is injected. Existing free-form behavior is preserved.
 

package/.next/standalone/public/kiro-plugin/.kiro/skills/chorus-proposal/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Proposal workflow — create proposals with document and tas
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/kiro-plugin/.kiro/skills/chorus-quick-dev/SKILL.md

@@ -4,7 +4,7 @@ description: Quick Task workflow — skip Idea→Proposal, create tasks directly
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/kiro-plugin/.kiro/skills/chorus-review/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Review workflow — approve/reject proposals, verify tasks,
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/kiro-plugin/.kiro/skills/chorus-yolo/SKILL.md

@@ -4,7 +4,7 @@ description: Full-auto AI-DLC pipeline — from prompt to done. Automates the en
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/kiro-plugin/bin/chorus-api.sh

@@ -240,7 +240,7 @@ cmd_mcp_tool() {
     # Step 1: Initialize MCP session
     local init_payload
     init_payload=$(cat <<JSONEOF
-{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"chorus-hook","version":"0.14.2"}}}
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"chorus-hook","version":"0.14.3"}}}
 JSONEOF
 )
 

package/.next/standalone/public/kiro-plugin/bin/verify-document-roundtrip.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+LOCAL_FILE="${1:?local file required}"
+DOCUMENT_UUID="${2:?document UUID required}"
+[ -f "$LOCAL_FILE" ] || { echo "round-trip verification: local file not found" >&2; exit 2; }
+command -v jq >/dev/null 2>&1 || { echo "round-trip verification: jq is required" >&2; exit 2; }
+
+RESPONSE_FILE=$(mktemp)
+REMOTE_FILE=$(mktemp)
+trap 'rm -f "$RESPONSE_FILE" "$REMOTE_FILE"' EXIT
+PAYLOAD=$(jq -cn --arg documentUuid "$DOCUMENT_UUID" '{documentUuid: $documentUuid}')
+
+if [ -n "${CHORUS_MCP_CALL_BIN:-}" ]; then
+  "$CHORUS_MCP_CALL_BIN" chorus_get_document "$PAYLOAD" >"$RESPONSE_FILE"
+else
+  chorus-api.sh mcp-tool chorus_get_document "$PAYLOAD" >"$RESPONSE_FILE"
+fi
+
+jq -je 'if (.content | type) == "string" then .content else error("top-level .content must be a string") end' \
+  "$RESPONSE_FILE" >"$REMOTE_FILE" || { echo "round-trip verification: invalid chorus_get_document response" >&2; exit 3; }
+cmp -s "$LOCAL_FILE" "$REMOTE_FILE" && exit 0
+
+hash_file() { command -v sha256sum >/dev/null 2>&1 && sha256sum "$1" | awk '{print $1}' || shasum -a 256 "$1" | awk '{print $1}'; }
+echo "round-trip mismatch:" >&2
+echo "  local  bytes=$(wc -c <"$LOCAL_FILE" | tr -d '[:space:]') sha256=$(hash_file "$LOCAL_FILE")" >&2
+echo "  remote bytes=$(wc -c <"$REMOTE_FILE" | tr -d '[:space:]') sha256=$(hash_file "$REMOTE_FILE")" >&2
+exit 4

package/.next/standalone/public/skill/brainstorm-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Optional divergent-then-convergent dialogue for fuzzy ideas. Invoke
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/skill/chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus AI Agent collaboration platform — overview, common tools,
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/skill/code-reviewer-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Read-only adversarial Chorus code-review gateway — independently
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/skill/develop-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Development workflow — claim tasks, report work, self-chec
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/skill/idea-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Idea workflow — claim ideas, run elaboration rounds, and p
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/skill/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chorus-skill",
-  "version": "0.14.2",
+  "version": "0.14.3",
   "description": "Chorus AI Agent collaboration platform skill. Supports PM, Developer, and Admin roles via MCP tools for the Idea-Proposal-Task workflow.",
   "author": "chorus",
   "license": "AGPL-3.0",

package/.next/standalone/public/skill/proposal-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Proposal workflow — create proposals with document and tas
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/skill/proposal-reviewer-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Read-only adversarial Chorus proposal reviewer — audits PRD/task
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/skill/quick-dev-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Quick Task workflow — skip Idea→Proposal, create tasks directly
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/skill/review-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Review workflow — approve/reject proposals, verify tasks,
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/skill/task-reviewer-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Read-only adversarial Chorus task reviewer — independently verifi
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/skill/yolo-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Full-auto AI-DLC pipeline — drive a single prompt from Idea throu
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.14.2"
+  version: "0.14.3"
   category: project-management
   mcp_server: chorus
 ---

package/cli/claude-spawner.mjs

@@ -247,6 +247,10 @@ export function parseNdjsonChunk(buffer, chunk, onObject, onWarn = () => {}) {
 export class ClaudeSpawner {
   /** @param {ClaudeSpawnerOptions} [opts] */
   constructor(opts = {}) {
+    this.sessionDecision = {
+      probeIsAuthoritative: true,
+      takeoverCommand: "claude --resume",
+    };
     this.claudePath = opts.claudePath ?? null;
     this.spawnImpl = opts.spawnImpl ?? spawn;
     this.logger = opts.logger ?? NOOP_LOGGER;

package/cli/codex-spawner.mjs

@@ -26,6 +26,11 @@ import { statSync } from "node:fs";
 import { win32 as pathWin32, posix as pathPosix } from "node:path";
 import { parseNdjsonChunk } from "./claude-spawner.mjs";
 import { getThreadId as defaultGetThreadId, setThreadId as defaultSetThreadId } from "./codex-session-map.mjs";
+import {
+  getCodexUsageSnapshot as defaultGetUsageSnapshot,
+  normalizeCodexUsageEvent,
+  setCodexUsageSnapshot as defaultSetUsageSnapshot,
+} from "./codex-usage-map.mjs";
 
 const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
 
@@ -88,9 +93,11 @@ export function buildCodexArgs({ isNew, threadId, permissionMode }) {
  */
 export function extractThreadId(obj) {
   if (!obj || typeof obj !== "object") return null;
-  if (obj.type === "thread.started" && typeof obj.thread_id === "string") return obj.thread_id;
+  if (obj.type === "thread.started" && typeof obj.thread_id === "string") {
+    return obj.thread_id.trim() || null;
+  }
   if (obj.type === "session_meta" && obj.payload && typeof obj.payload.id === "string") {
-    return obj.payload.id;
+    return obj.payload.id.trim() || null;
   }
   return null;
 }
@@ -163,11 +170,14 @@ export function resolveSpawnCommand(codexPath, args, platform = process.platform
  * @property {NodeJS.Platform} [platform]  Injectable for tests; gates POSIX `detached`.
  * @property {(anchor: string) => string|null} [getThreadIdFn]  Injectable session-map read.
  * @property {(anchor: string, threadId: string) => void} [setThreadIdFn]  Injectable session-map write.
+ * @property {(anchor: string, threadId: string) => object|null} [getUsageSnapshotFn]
+ * @property {(anchor: string, threadId: string, usage: object) => void} [setUsageSnapshotFn]
  */
 
 export class CodexSpawner {
   /** @param {CodexSpawnerOptions} [opts] */
   constructor(opts = {}) {
+    this.sessionDecision = { probeIsAuthoritative: false };
     this.codexPath = opts.codexPath ?? null;
     this.spawnImpl = opts.spawnImpl ?? spawn;
     this.logger = opts.logger ?? NOOP_LOGGER;
@@ -176,6 +186,8 @@ export class CodexSpawner {
     this.platform = opts.platform ?? process.platform;
     this.getThreadIdFn = opts.getThreadIdFn ?? defaultGetThreadId;
     this.setThreadIdFn = opts.setThreadIdFn ?? defaultSetThreadId;
+    this.getUsageSnapshotFn = opts.getUsageSnapshotFn ?? defaultGetUsageSnapshot;
+    this.setUsageSnapshotFn = opts.setUsageSnapshotFn ?? defaultSetUsageSnapshot;
     this.resolveCodexPathFn = opts.resolveCodexPathFn ?? resolveCodexPath;
   }
 
@@ -198,6 +210,13 @@ export class CodexSpawner {
     // waker's Claude transcript probe: a recorded thread id means resume.
     const knownThreadId = anchor ? this.getThreadIdFn(anchor) : null;
     const isNew = !knownThreadId;
+    let previousUsage = knownThreadId
+      ? this.getUsageSnapshotFn(anchor, knownThreadId)
+      : null;
+    // Existing threads created before this baseline store was introduced cannot
+    // yield a trustworthy first delta. Seed once and omit that turn's usage
+    // instead of publishing the entire historical cumulative total.
+    let needsUsageSeed = Boolean(knownThreadId && !previousUsage);
 
     const codexPath = this.codexPath ?? this.resolveCodexPathFn();
     if (!codexPath) {
@@ -249,6 +268,7 @@ export class CodexSpawner {
 
       let stdoutBuf = "";
       let observedThreadId = knownThreadId || null;
+      let threadIdPersisted = false;
 
       child.stdout?.setEncoding?.("utf8");
       child.stdout?.on("data", (chunk) => {
@@ -257,10 +277,27 @@ export class CodexSpawner {
           String(chunk),
           (obj) => {
             const tid = extractThreadId(obj);
-            if (tid) observedThreadId = tid;
+            if (tid) {
+              observedThreadId = tid;
+              if (isNew && anchor && !threadIdPersisted) {
+                threadIdPersisted = true;
+                this.setThreadIdFn(anchor, tid);
+              }
+            }
+            let delivered = obj;
+            if (obj?.type === "turn.completed" && obj.usage) {
+              delivered = needsUsageSeed
+                ? { ...obj, usage: null }
+                : normalizeCodexUsageEvent(obj, previousUsage);
+              if (anchor && observedThreadId) {
+                this.setUsageSnapshotFn(anchor, observedThreadId, obj.usage);
+              }
+              previousUsage = obj.usage;
+              needsUsageSeed = false;
+            }
             if (onMessage) {
               try {
-                onMessage(obj);
+                onMessage(delivered);
               } catch (err) {
                 this.logger.warn(`[Chorus] onMessage handler threw: ${err}`);
               }
@@ -285,12 +322,6 @@ export class CodexSpawner {
         if (code !== 0) {
           this.logger.warn(`[Chorus] codex exited with code ${code}`);
         }
-        // Persist anchor→thread_id only on a fresh, successful run that produced a
-        // new id — so a later wake for this anchor resumes it. Best-effort; the
-        // session map swallows its own IO errors.
-        if (code === 0 && isNew && anchor && observedThreadId) {
-          this.setThreadIdFn(anchor, observedThreadId);
-        }
         resolve({ sessionId: observedThreadId || anchor, exitCode: code, isNew });
       });
 

package/cli/codex-usage-map.mjs

@@ -0,0 +1,115 @@
+// Persist the last cumulative Codex token snapshot per Chorus anchor. Codex
+// `turn.completed.usage` is backed by ThreadTokenUsage.total, so resumed execs
+// must subtract this baseline before publishing per-turn usage.
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const NOOP_LOGGER = { warn() {} };
+const FIELDS = [
+  "input_tokens",
+  "cached_input_tokens",
+  "cache_write_input_tokens",
+  "output_tokens",
+  "reasoning_output_tokens",
+];
+
+export function codexUsageMapPath() {
+  return join(homedir(), ".chorus", "codex-usage.json");
+}
+
+function tokenInt(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0
+    ? Math.trunc(value)
+    : null;
+}
+
+function sanitizeUsage(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const usage = {};
+  let found = false;
+  for (const field of FIELDS) {
+    const parsed = tokenInt(value[field]);
+    if (parsed !== null) {
+      usage[field] = parsed;
+      found = true;
+    }
+  }
+  return found ? usage : null;
+}
+
+function readMap(path, read, logger) {
+  try {
+    const parsed = JSON.parse(read(path));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch (err) {
+    if (!(err && err.code === "ENOENT")) {
+      logger.warn(`[Chorus] codex-usage-map: read failed (${err}) - treating as empty`);
+    }
+    return {};
+  }
+}
+
+export function getCodexUsageSnapshot(anchor, threadId, deps = {}) {
+  if (!anchor || !threadId) return null;
+  const path = deps.path ?? codexUsageMapPath();
+  const read = deps.read ?? ((p) => readFileSync(p, "utf8"));
+  const logger = deps.logger ?? NOOP_LOGGER;
+  const entry = readMap(path, read, logger)[anchor];
+  if (!entry || entry.threadId !== threadId) return null;
+  return sanitizeUsage(entry.usage);
+}
+
+export function setCodexUsageSnapshot(anchor, threadId, usage, deps = {}) {
+  const clean = sanitizeUsage(usage);
+  if (!anchor || !threadId || !clean) return;
+  const path = deps.path ?? codexUsageMapPath();
+  const read = deps.read ?? ((p) => readFileSync(p, "utf8"));
+  const write = deps.write ?? writeFileSync;
+  const mkdir = deps.mkdir ?? mkdirSync;
+  const rename = deps.rename ?? renameSync;
+  const logger = deps.logger ?? NOOP_LOGGER;
+  try {
+    const map = readMap(path, read, logger);
+    map[anchor] = { threadId, usage: clean };
+    mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    write(tmp, JSON.stringify(map, null, 2) + "\n", { mode: 0o600 });
+    rename(tmp, path);
+  } catch (err) {
+    logger.warn(`[Chorus] codex-usage-map: persist failed (${err}) - next turn may overcount`);
+  }
+}
+
+function delta(current, previous) {
+  const now = tokenInt(current);
+  if (now === null) return null;
+  const before = tokenInt(previous);
+  return before !== null && now >= before ? now - before : now;
+}
+
+export function normalizeCodexUsageEvent(event, previous) {
+  if (!event || event.type !== "turn.completed" || !event.usage) return event;
+  const raw = event.usage;
+  const input = delta(raw.input_tokens, previous?.input_tokens);
+  const cacheRead = delta(raw.cached_input_tokens, previous?.cached_input_tokens);
+  const cacheWrite = delta(raw.cache_write_input_tokens, previous?.cache_write_input_tokens);
+  const exclusiveInput =
+    input === null ? null : Math.max(0, input - (cacheRead ?? 0) - (cacheWrite ?? 0));
+
+  return {
+    ...event,
+    usage: {
+      ...raw,
+      input_tokens: exclusiveInput,
+      cached_input_tokens: cacheRead,
+      cache_write_input_tokens: cacheWrite,
+      output_tokens: delta(raw.output_tokens, previous?.output_tokens),
+      reasoning_output_tokens: delta(
+        raw.reasoning_output_tokens,
+        previous?.reasoning_output_tokens
+      ),
+    },
+  };
+}