taskchef 7.19.0 → 7.20.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.19.0",
+  "version": "7.20.0",
   "description": "Dispatch work from a data-only workspace to visible Codex project tasks.",
   "author": {
     "name": "Favo Yang",

package/README.md

@@ -25,6 +25,12 @@ request -> recorded TaskChef task -> Codex executor -> request/result turn timel
 TaskChef requires Node.js 18 or newer, Git, Codex desktop, and local access to
 the projects that will receive work.
 
+Install [`ccusage`](https://github.com/ccusage/ccusage) separately when you want
+the optional dashboard token and API-equivalent cost estimates. TaskChef calls
+its structured offline Codex report and does not parse Codex rollout files
+itself. Lifecycle reporting and the dashboard continue to work when `ccusage`
+is absent or incompatible.
+
 ```sh
 codex plugin marketplace add favoyang/codex-plugins
 codex plugin add taskchef@favoyang-plugins
@@ -50,6 +56,7 @@ The canonical workspace is `~/.agents/taskchef`. TaskChef owns only:
 AGENTS.md       managed dispatcher instructions plus user additions
 taskchef.json   schema-2 Codex project index, dashboard preference, and delegation metadata
 tasks.jsonl     one task snapshot per line (schema 9; schema 4-8 migration supported)
+.taskchef-usage.json   optional mode-0600 ccusage snapshot and turn-boundary cache
 ```
 
 Index or inspect Codex projects conversationally:
@@ -269,8 +276,23 @@ Codex CLI at the canonical ChatGPT or Codex desktop app location under
 `/Applications`, to archive the exact thread UUID. The Codex chat leaves active chat lists while the TaskChef record
 and its activity timeline remain unchanged. If the bundled CLI is unavailable,
 the dashboard does not fall back to another `codex` executable from `PATH`.
+
+Task details also show whole-task and per-turn token usage when `ccusage` can
+map the linked Codex thread. A completed turn briefly shows “Tokens:
+calculating…” while TaskChef performs bounded deferred reconciliation, because
+the terminal lifecycle callback precedes Codex's final output write. Historical
+tasks may show a trustworthy task total while older turns remain “Tokens
+unavailable” when no cumulative turn boundaries were recorded. Input, cached
+input, output, reasoning, and total counts retain ccusage's categories. Dollar
+figures are labeled API-equivalent estimates; zero-priced unknown models show
+cost unavailable rather than a misleading `$0.00`.
 The header shows the running TaskChef package version reported by the same
 bounded health identity used for compatible-listener checks.
+The canonical port is owned by a dashboard initialized in the TaskChef MCP host
+before its tool transport connects. Health identity records an `mcp` launcher,
+and MCP recovery reuses only another exact-compatible MCP-launched dashboard;
+a foreground `taskchef dashboard` process is intentionally standalone so its
+child commands cannot silently inherit an agent-shell sandbox.
 Task and result times are relative through 29 days (with minute detail for the
 first six hours), then use a locale-aware calendar date. Each time is a keyboard-
 accessible toggle for its full locale-aware date and time, and one shared
@@ -281,16 +303,17 @@ revision, so reconnects and non-semantic rewrites do not replay a notice and a
 later task state cannot rewrite an older notice. A notice remains readable if
 its task disappears; selecting it then explains that current details are no
 longer available.
-It does not mutate TaskChef data and prints its local URL.
-When a compatible foreground dashboard already owns port 3210,
-`ensure_dashboard` reuses it but does not take ownership. If an unknown,
-different-workspace, or stale-version process owns the port, TaskChef reports a
-concise conflict and never kills or replaces that process. The foreground CLI
-similarly asks you to stop the listener or choose another `--port`.
+It does not mutate TaskChef data and prints its local URL. A foreground
+dashboard identifies itself as standalone and is never reused on the canonical
+MCP port. If a standalone, unknown, different-workspace, or stale-version
+process owns port 3210, TaskChef reports a concise conflict and never kills or
+replaces that process. The foreground CLI similarly asks you to stop the
+listener or choose another `--port`.
 
 The health endpoint contains only a fixed service marker, health schema,
-TaskChef version, dashboard-server version, and canonical workspace. It exposes
-no task data, credentials, environment variables, process control, or secrets.
+TaskChef version, dashboard-server version, canonical workspace, and launcher.
+It exposes no task data, credentials, environment variables, process control,
+or secrets.
 
 ![TaskChef dashboard identity and version](docs/images/dashboard-identity.jpg)
 
@@ -298,6 +321,8 @@ no task data, credentials, environment variables, process control, or secrets.
 
 ![Task detail activity timeline](docs/images/result-history-dashboard.jpg)
 
+![Deferred ccusage token consumption in task details](docs/images/ccusage-token-consumption.png)
+
 ![Interrupted turn followed by active recovery](docs/images/interrupted-turn-recovery.jpg)
 
 ## Common recovery
@@ -351,13 +376,15 @@ does not necessarily reload Codex. Then run `$taskchef-dashboard` (or call
 
 - the expected released TaskChef version;
 - the expected dashboard protocol `serverVersion`;
+- the `mcp` dashboard launcher;
 - the canonical TaskChef workspace path;
 - the canonical `http://127.0.0.1:3210/` URL.
 
 The release-install sequence is therefore: install plugin, activate or reload
 the new MCP process, ensure the dashboard, then verify TaskChef version,
-protocol `serverVersion`, canonical workspace, and URL. Exact-compatible
-servers may be reused; unknown listeners remain untouched.
+protocol `serverVersion`, `mcp` launcher, canonical workspace, and URL.
+Exact-compatible MCP servers may be reused; standalone and unknown listeners
+remain untouched.
 
 ## Development
 

package/docs/spec.md

@@ -28,7 +28,7 @@ is dated research, not contract.
 | **Last semantic result** | The final result-history entry, exposed through the derived `lastResult` compatibility alias. |
 | **Turn reference** | Required lifecycle identity for one executor prompt. It is the native Codex turn ID when available, otherwise a retained client-generated UUID. |
 | **Current turn ID** | Optional Codex metadata for the reported prompt; null when native turn reading is unavailable. |
-| **Dashboard** | The loopback, read-only UI derived from validated workspace snapshots and bounded native actions. |
+| **Dashboard** | The loopback, read-only UI derived from validated workspace snapshots, optional local usage projections, and bounded native actions. |
 | **Skill** | One packaged agent procedure: `taskchef-bootstrap`, `taskchef-dashboard`, `taskchef-delegate`, `taskchef-executor`, or `taskchef-copilot`. |
 
 ## Components and ownership
@@ -56,7 +56,8 @@ is dated research, not contract.
 
 ## Workspace contract
 
-TaskChef MUST manage only `AGENTS.md`, `taskchef.json`, and `tasks.jsonl`
+TaskChef MUST manage only `AGENTS.md`, `taskchef.json`, `tasks.jsonl`, and the
+optional `.taskchef-usage.json` cache
 inside the dispatcher workspace. It MUST preserve unrelated paths.
 
 `taskchef.json` MUST have schema version 2, the following required fields, and
@@ -116,18 +117,63 @@ from the final derived semantic result. Interrupted outcomes MUST be excluded.
 These projections MUST NOT be persisted in schema 9 and remain compatibility
 aliases for existing callers.
 
+## Optional usage projection
+
+TaskChef MAY invoke an installed `ccusage` executable as an optional local
+adapter using `ccusage codex session --json --offline`. TaskChef MUST NOT parse,
+store, or serve raw Codex rollout files, prompts, responses, transcripts, or
+reasoning. Analyzer absence, timeout, malformed output, unknown pricing, or an
+unresolved thread MUST NOT block lifecycle tools or dashboard loading.
+
+The mode-0600 `.taskchef-usage.json` cache stores only normalized cumulative
+token boundaries, per-turn deltas, model names, estimated cost, source version,
+and freshness. It is independent of schema-9 task records so legacy logs remain
+readable. Writes MUST use the workspace lock and atomic replacement. Symlinked
+or unsupported cache files MUST be rejected. Writes MUST compact the derived
+cache to recent task projections, recent per-turn results, and the latest
+cumulative boundary. An oversized legacy cache MUST be treated as rebuildable
+derived data so it cannot permanently disable usage reporting.
+
+A linked Codex thread MAY map to multiple ccusage session segments. TaskChef
+MUST aggregate only records whose primary durable thread UUID is that exact
+identity; a UUID appearing only as a nested suffix MUST NOT be attributed to
+the parent or child TaskChef task. It MUST retain input, cached-input, output,
+reasoning-output, and total fields without adding cached or reasoning subsets
+into totals a second time.
+
+After a terminal report, TaskChef MUST mark the turn `calculating` and perform
+bounded deferred reconciliation without delaying the lifecycle response.
+Per-turn usage MUST be a non-negative delta between adjacent reliable cumulative
+boundaries. A first recorded turn MAY use zero as its baseline. Historical
+turns without boundaries and decreasing or ambiguous snapshots MUST be labeled
+`unavailable`, never zero or estimated. A historical task MAY still show its
+resolvable cumulative total. A boundary is reliable only after two consecutive
+samples agree. Exhausted unstable sampling and a newer turn beginning before
+stabilization MUST leave that turn unavailable and MUST NOT establish a delta
+baseline. Zero is valid for the first turn only when TaskChef observed that turn
+in progress before its terminal report; a first historical terminal turn MUST
+remain unavailable even when its cumulative task total is resolvable.
+
+Every available projection MUST identify ccusage, its version when available,
+and freshness. Dollar values MUST be labeled API-equivalent estimates. Positive
+token usage with a zero or missing analyzer cost MUST display cost unavailable,
+not `$0.00`.
+
 Task IDs and non-null thread identities MUST be unique. The immutable intent
 fields MUST NOT change after recording.
 
 ## Required lifecycle
 
-When the canonical TaskChef MCP server finishes connecting, it MUST invoke the
-same serialized dashboard ensure path once by default. It MUST read the
+Before the canonical TaskChef MCP server connects and exposes its transport, it
+MUST invoke the same serialized dashboard ensure path once by default. It MUST read the
 canonical configuration and skip this only for explicit
 `dashboard.autostart: false`. Initialization failures, invalid workspace state,
 port conflicts, and dashboard errors MUST NOT prevent tool registration or MCP
 availability. They MUST emit only a bounded non-sensitive diagnostic through
 the MCP process logging channel. MCP initialization MUST NOT open a browser.
+If transport connection fails after dashboard startup, the MCP server MUST
+best-effort close both its owned dashboard and partially attached transport,
+then propagate the original connection failure even when cleanup also fails.
 
 At the start of every dispatcher turn, the dispatcher SHOULD call
 `ensure_dashboard` best-effort. Failure MUST NOT block direct TaskChef answers,
@@ -228,6 +274,7 @@ HTTP server; it does not mutate dispatcher workspace files.
 ```text
 { dashboard: {
   action: "started" | "reused",
+  launcher: "mcp",
   url: "http://127.0.0.1:3210/",
   workspace: string,
   taskchefVersion: string,
@@ -235,20 +282,22 @@ HTTP server; it does not mutate dispatcher workspace files.
 } }
 ```
 
-Calls MUST serialize within one MCP process. The first call starts an owned
-dashboard or reuses an exact compatible listener; later and concurrent calls
-are idempotent and report reuse after the single start. The stable default MUST
+MCP initialization MUST complete its best-effort dashboard start before exposing
+the MCP transport. Calls MUST serialize within one MCP process. The first call
+starts an owned dashboard or reuses an exact compatible MCP-launched listener;
+later and concurrent calls are idempotent and report reuse after the single start. The stable default MUST
 bind only to `127.0.0.1:3210` and MUST NOT accept a model-supplied workspace,
 host, or port.
 
 Before reuse, TaskChef MUST query a bounded loopback identity endpoint and
 require the exact fixed service/schema, TaskChef version, dashboard-server
-version, and canonical workspace. An unknown, malformed, different-workspace,
-or stale-version listener MUST produce a concise actionable conflict. TaskChef
+version, canonical workspace, and `mcp` launcher identity. A standalone,
+unknown, malformed, different-workspace, or stale-version listener MUST produce a concise actionable conflict. TaskChef
 MUST NOT kill, replace, signal, or otherwise control that listener. A startup
 failure MUST leave no owned listener. The MCP server MUST close its owned
-dashboard when its transport or process shuts down; it MUST NOT close a reused
-external foreground server.
+dashboard when its transport or process shuts down. This keeps dashboard child
+operations in the MCP host environment and prevents an agent-shell or foreground
+CLI dashboard from being mistaken for the canonical MCP-owned runtime.
 
 The packaged `$taskchef-dashboard` skill MUST call this tool, report `started`
 or `reused`, and return the canonical clickable URL. It MAY use an available
@@ -510,6 +559,6 @@ closed.
 Installing or replacing plugin files MUST NOT be described as activating the
 new MCP code. Release verification MUST install the plugin, activate or reload
 the new MCP process, ensure the dashboard, and verify the expected TaskChef
-version, dashboard protocol `serverVersion`, canonical workspace, and canonical
-URL. Exact-compatible listener reuse remains valid; installation MUST NOT be
+version, dashboard protocol `serverVersion`, `mcp` launcher, canonical workspace,
+and canonical URL. Exact-compatible MCP-listener reuse remains valid; installation MUST NOT be
 claimed to reload Codex automatically.

package/docs/workflows.md

@@ -21,6 +21,8 @@ research.
 | `src/cli.js` | Administration, normalized cached briefs, inspection, diagnostics, and dashboard startup. |
 | `src/dashboard.js` | Versioned health identity, validated compact snapshots, SSE fan-out, on-demand details, and bounded open actions. |
 | `src/dashboard-manager.js` | Concurrent singleton ensure, exact listener reuse, conflicts, and owned shutdown. |
+| `src/usage.js` | Optional bounded ccusage execution, exact primary-thread mapping, normalized aggregation, and the private usage cache. |
+| `src/usage-tracker.js` | Deferred sampling, cumulative boundaries, historical availability, and per-turn deltas. |
 
 The MCP process resolves `TASKCHEF_WORKSPACE` once and never accepts a model
 supplied path. The CLI resolves `--workspace`, then the environment, then the
@@ -40,11 +42,11 @@ sequenceDiagram
   participant H as Loopback health
   participant S as Dashboard server
   M->>M: Read dashboard.autostart (absent means true)
-  M->>M: Best-effort ensure after MCP connect
+  M->>M: Best-effort ensure before MCP transport connects
   D->>M: ensure_dashboard()
   M->>M: Serialize concurrent ensure calls
   M->>H: GET 127.0.0.1:3210/api/health
-  alt Exact service, versions, and canonical workspace
+  alt Exact service, versions, canonical workspace, and MCP launcher
     H-->>M: Bounded compatible identity
     M-->>D: reused, URL, workspace, versions
   else No listener
@@ -52,7 +54,7 @@ sequenceDiagram
     M->>S: Start in this MCP process on 127.0.0.1:3210
     S-->>M: Owned server
     M-->>D: started, URL, workspace, versions
-  else Unknown, stale, or different workspace
+  else Standalone, unknown, stale, or different workspace
     H-->>M: Missing or incompatible identity
     M-->>D: Actionable conflict, listener untouched
   end
@@ -62,9 +64,10 @@ sequenceDiagram
 ```
 
 When the MCP transport or plugin process closes, it closes only the server it
-started. A compatible foreground `taskchef dashboard` listener may be reused
-but remains owned by that CLI process. No TaskChef path terminates an unknown
-listener or installs OS persistence.
+started. A foreground `taskchef dashboard` listener identifies itself as
+standalone and is never reused as the canonical MCP dashboard, because its
+archive child process may inherit a different host environment. No TaskChef
+path terminates an incompatible listener or installs OS persistence.
 
 Autostart and explicit ensures share the same manager promise, so concurrent
 initialization and recovery calls produce at most one owned listener. An
@@ -79,13 +82,13 @@ The practical release handoff ends in this order:
 1. Install the released plugin.
 2. Activate or reload its new TaskChef MCP process.
 3. Run `$taskchef-dashboard` or call `ensure_dashboard`.
-4. Verify the expected TaskChef version, protocol `serverVersion`, canonical
-   workspace, and canonical URL returned by the dashboard identity.
+4. Verify the expected TaskChef version, protocol `serverVersion`, `mcp`
+   launcher, canonical workspace, and canonical URL returned by the dashboard identity.
 
 Replacing plugin files alone cannot execute autostart because old code remains
 in the already-running MCP process. Installation does not necessarily reload
-Codex. An exact-compatible dashboard may be reused; an unknown listener is
-never terminated or replaced.
+Codex. An exact-compatible MCP dashboard may be reused; a standalone or unknown
+listener is never terminated or replaced.
 
 ## Normal delegation and self-linking
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.19.0",
+  "version": "7.20.0",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",
@@ -27,6 +27,7 @@
     "docs/workflows.md",
     "docs/firstmate-taskchef-comparison.md",
     "docs/images/dashboard-identity.jpg",
+    "docs/images/ccusage-token-consumption.png",
     "docs/images/notification-event-snapshots.jpg",
     "docs/images/result-history-dashboard.jpg",
     "docs/images/interrupted-turn-recovery.jpg",

package/src/dashboard/app.js

@@ -25,6 +25,9 @@ import {
 } from "./github-links.js";
 import { formatRelativeTime, RelativeTimeController, parsedTimestamp } from "./time.js";
 
+const USAGE_POLL_INTERVAL_MS = 1_500;
+const MAX_USAGE_POLL_ATTEMPTS = 40;
+
 const state = {
   archivedThreadIds: new Set(),
   tasks: [],
@@ -57,6 +60,7 @@ const elements = {
   dialogRelatedLinks: document.querySelector("#dialog-related-links"),
   dialogResults: document.querySelector("#dialog-results"),
   dialogTitle: document.querySelector("#dialog-title"),
+  dialogUsage: document.querySelector("#dialog-usage"),
   dismissDashboardMessage: document.querySelector("#dismiss-dashboard-message"),
   emptyState: document.querySelector("#empty-state"),
   notifications: document.querySelector("#notifications"),
@@ -347,6 +351,58 @@ function detailRow(term, value) {
   return [dt, dd];
 }
 
+const tokenFormatter = new Intl.NumberFormat();
+
+function formatEstimatedCost(value) {
+  if (typeof value !== "number") return "cost unavailable";
+  if (value === 0) return "estimated $0.00";
+  return `estimated $${value < 0.01 ? value.toFixed(4) : value.toFixed(2)}`;
+}
+
+function usageBreakdownText(usage) {
+  return [
+    `${tokenFormatter.format(usage.inputTokens)} input`,
+    `${tokenFormatter.format(usage.cachedInputTokens)} cached input`,
+    `${tokenFormatter.format(usage.outputTokens)} output`,
+    `${tokenFormatter.format(usage.reasoningOutputTokens)} reasoning`,
+  ].join(" · ");
+}
+
+function usagePresentation(usage, { wholeTask = false } = {}) {
+  const container = document.createElement("div");
+  container.className = `usage-summary usage-${usage?.status ?? "calculating"}`;
+  if (!usage || usage.status === "calculating") {
+    const indicator = document.createElement("span");
+    indicator.className = "usage-spinner";
+    indicator.setAttribute("aria-hidden", "true");
+    const text = document.createElement("span");
+    text.textContent = "Tokens: calculating…";
+    container.replaceChildren(indicator, text);
+    return container;
+  }
+  if (usage.status !== "available") {
+    container.textContent = `Tokens unavailable${usage.reason ? ` — ${usage.reason}` : "."}`;
+    return container;
+  }
+  const headline = document.createElement("strong");
+  headline.textContent = `${tokenFormatter.format(usage.totalTokens)} tokens · ${formatEstimatedCost(usage.estimatedCostUsd)}`;
+  const breakdown = document.createElement("span");
+  breakdown.textContent = usageBreakdownText(usage);
+  container.append(headline, breakdown);
+  const provenance = document.createElement("span");
+  const version = usage.provenance?.version ? ` ${usage.provenance.version}` : "";
+  const freshness = usage.sourceUpdatedAt ?? usage.sampledAt;
+  provenance.textContent = `Source: ccusage${version}${freshness ? ` · updated ${formatRelativeTime(freshness)}` : ""}. Dollar cost is an API-equivalent estimate${wholeTask ? " for the task" : " for this turn"}.`;
+  container.append(provenance);
+  return container;
+}
+
+function usageStillCalculating(task) {
+  return task.usage?.status === "calculating"
+    || (task.status !== "working" && Object.values(task.usage?.turns ?? {})
+      .some((turn) => turn.status === "calculating"));
+}
+
 function turnTimeline(task) {
   if (task.turns.length === 0) {
     const empty = document.createElement("p");
@@ -387,7 +443,20 @@ function turnTimeline(task) {
     const turnMetadata = document.createElement("p");
     turnMetadata.className = "result-history-turn";
     turnMetadata.textContent = `Turn ref ${turn.turnRef ?? "not recorded"}; Codex turn ${turn.turnId ?? "unavailable"}`;
-    item.append(header, requestLabel, request, resultLabel, result, turnMetadata);
+    const turnUsage = task.usage?.turns?.[turn.turnRef ?? turn.turnId] ?? (
+      turn.result === null
+        ? { status: "calculating" }
+        : { status: "unavailable", reason: "No reliable turn boundary is available." }
+    );
+    item.append(
+      header,
+      requestLabel,
+      request,
+      resultLabel,
+      result,
+      usagePresentation(turnUsage),
+      turnMetadata,
+    );
     return item;
   });
 }
@@ -418,6 +487,12 @@ function renderDialog(task) {
     (task.relatedGitHubLinks?.length ?? 0) === 0 && !task.relatedGitHubLinksTruncated
   );
   elements.dialogResults.replaceChildren(...turnTimeline(detailedTask));
+  elements.dialogUsage.replaceChildren(usagePresentation(
+    task.usage?.status === "available" && task.usage.task
+      ? { status: "available", ...task.usage.task }
+      : task.usage ?? { status: task.threadId ? "calculating" : "unavailable" },
+    { wholeTask: true },
+  ));
   elements.dialogInstruction.textContent = task.instruction;
   elements.copyTaskId.disabled = !task.id;
   setCopyTaskIdLabel("Copy Task ID");
@@ -464,22 +539,28 @@ async function openDialog(task) {
   const requestGeneration = ++detailRequestGeneration;
   renderDialog(task);
   if (!elements.dialog.open) elements.dialog.showModal();
-  try {
-    const response = await fetch(`/api/tasks/${encodeURIComponent(task.id)}`);
-    if (!response.ok) throw new Error("Task details are unavailable.");
-    const detail = await response.json();
-    if (
-      requestGeneration === detailRequestGeneration
-      && state.selectedTask?.id === task.id
-      && elements.dialog.open
-    ) {
-      renderDialog(detail.task);
-    }
-  } catch {
-    if (state.selectedTask?.id === task.id) {
-      showMessage("Task activity timeline is temporarily unavailable.");
+  const load = async (attempt = 0) => {
+    try {
+      const response = await fetch(`/api/tasks/${encodeURIComponent(task.id)}`);
+      if (!response.ok) throw new Error("Task details are unavailable.");
+      const detail = await response.json();
+      if (
+        requestGeneration === detailRequestGeneration
+        && state.selectedTask?.id === task.id
+        && elements.dialog.open
+      ) {
+        renderDialog(detail.task);
+        if (usageStillCalculating(detail.task) && attempt < MAX_USAGE_POLL_ATTEMPTS) {
+          setTimeout(() => load(attempt + 1), USAGE_POLL_INTERVAL_MS);
+        }
+      }
+    } catch {
+      if (state.selectedTask?.id === task.id) {
+        showMessage("Task activity timeline is temporarily unavailable.");
+      }
     }
-  }
+  };
+  await load();
 }
 
 function taskCard(task) {

package/src/dashboard/index.html

@@ -116,6 +116,10 @@
         <button id="archive-codex" class="danger-button" type="button" aria-label="Archive this chat in Codex" hidden>Archive chat</button>
       </div>
       <nav id="dialog-related-links" class="github-links" aria-label="Related GitHub links" hidden></nav>
+      <section>
+        <h3>Usage</h3>
+        <div id="dialog-usage" class="usage-panel" aria-live="polite"></div>
+      </section>
       <section>
         <h3>Activity timeline</h3>
         <div id="dialog-results" class="result-history"></div>

package/src/dashboard/styles.css

@@ -165,6 +165,13 @@ dialog section + section { margin-top: 24px; }
 .result-history-item h4 { margin: 10px 0 3px; color: var(--muted); font-size: 0.72rem; letter-spacing: 0.04em; text-transform: uppercase; }
 .result-history-turn, .result-history-empty { color: var(--muted); font-size: 0.78rem; overflow-wrap: anywhere; }
 .result-history-empty { margin: 0; }
+.usage-panel { margin-top: 8px; }
+.usage-summary { display: grid; gap: 3px; margin: 10px 0 4px; color: var(--muted); font-size: 0.8rem; }
+.usage-summary strong { color: var(--text); font-size: 0.9rem; }
+.usage-calculating { display: flex; align-items: center; gap: 7px; }
+.usage-spinner { width: 12px; height: 12px; border: 2px solid var(--border); border-top-color: var(--accent); border-radius: 50%; animation: usage-spin 0.8s linear infinite; }
+@keyframes usage-spin { to { transform: rotate(360deg); } }
+@media (prefers-reduced-motion: reduce) { .usage-spinner { animation: none; border-top-color: var(--border); background: var(--accent); } }
 pre { max-height: 280px; margin: 0; padding: 14px; overflow: auto; border-radius: 7px; background: var(--surface-muted); white-space: pre-wrap; overflow-wrap: anywhere; font: 0.86rem/1.55 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
 .metadata { display: grid; grid-template-columns: minmax(100px, 150px) 1fr; margin: 0; font-size: 0.88rem; }
 .metadata dt, .metadata dd { padding: 7px 0; border-bottom: 1px solid var(--border); overflow-wrap: anywhere; }

package/src/dashboard-manager.js

@@ -14,13 +14,14 @@ const DEFAULT_HOST = "127.0.0.1";
 const DEFAULT_PORT = 3210;
 const HEALTH_TIMEOUT_MS = 750;
 
-function expectedIdentity(workspace, taskchefVersion, serverVersion) {
+function expectedIdentity(workspace, taskchefVersion, serverVersion, launcher) {
   return {
     schemaVersion: 1,
     service: "taskchef-dashboard",
     taskchefVersion,
     serverVersion,
     workspace,
+    launcher,
   };
 }
 
@@ -107,6 +108,7 @@ export function createDashboardManager({
   port = DEFAULT_PORT,
   taskchefVersion = TASKCHEF_VERSION,
   serverVersion = DASHBOARD_SERVER_VERSION,
+  launcher = "mcp",
   createServer = createDashboardServer,
   readIdentity = readDashboardIdentity,
 } = {}) {
@@ -117,6 +119,7 @@ export function createDashboardManager({
 
   const publicResult = (action) => ({
     action,
+    launcher,
     url: `http://${dashboardAuthority(host, ownedServer?.port ?? port)}/`,
     workspace: canonicalWorkspace,
     taskchefVersion,
@@ -132,9 +135,12 @@ export function createDashboardManager({
       if (listenerAbsent(error)) return false;
       throw listenerConflict(url, `is occupied but did not return a compatible identity (${error.message}).`);
     }
-    const expected = expectedIdentity(canonicalWorkspace, taskchefVersion, serverVersion);
+    const expected = expectedIdentity(canonicalWorkspace, taskchefVersion, serverVersion, launcher);
     if (!isExactIdentity(identity, expected)) {
-      throw listenerConflict(url, "belongs to an unknown, stale, or different-workspace service.");
+      throw listenerConflict(
+        url,
+        "belongs to an unknown, stale, different-workspace, or differently launched service.",
+      );
     }
     return true;
   };
@@ -150,6 +156,7 @@ export function createDashboardManager({
         port,
         taskchefVersion,
         serverVersion,
+        launcher,
       });
       return publicResult("started");
     } catch (error) {

package/src/dashboard.js

@@ -22,6 +22,7 @@ import {
 } from "./workspace.js";
 import { DASHBOARD_SERVER_VERSION, TASKCHEF_VERSION } from "./version.js";
 import { taskGitHubProjection } from "./dashboard/github-links.js";
+import { createUsageTracker } from "./usage-tracker.js";
 
 const TASKS_FILE_NAME = "tasks.jsonl";
 const STATIC_ROOT = fileURLToPath(new URL("./dashboard/", import.meta.url));
@@ -452,8 +453,10 @@ export async function createDashboardServer({
   monitorOptions = {},
   openProject = null,
   openThread = null,
+  launcher = "standalone",
   taskchefVersion = TASKCHEF_VERSION,
   serverVersion = DASHBOARD_SERVER_VERSION,
+  usageTracker = null,
 } = {}) {
   if (!LOOPBACK_HOSTS.has(host)) {
     throw new Error("dashboard host must be a loopback address");
@@ -464,14 +467,19 @@ export async function createDashboardServer({
   if (!Number.isInteger(maxEventClients) || maxEventClients < 0) {
     throw new Error("dashboard event-client limit must be a non-negative integer");
   }
+  if (!new Set(["mcp", "standalone"]).has(launcher)) {
+    throw new Error("dashboard launcher must be mcp or standalone");
+  }
   const monitor = new DashboardMonitor(workspace, monitorOptions);
   await monitor.start();
+  const taskUsageTracker = usageTracker ?? createUsageTracker({ workspace: monitor.workspace });
   const identity = Object.freeze({
     schemaVersion: 1,
     service: "taskchef-dashboard",
     taskchefVersion,
     serverVersion,
     workspace: monitor.workspace,
+    launcher,
   });
   if (Buffer.byteLength(`${JSON.stringify(identity)}\n`) > DASHBOARD_HEALTH_MAX_BYTES) {
     monitor.close();
@@ -569,7 +577,16 @@ export async function createDashboardServer({
         response.writeHead(200, securityHeaders("application/json; charset=utf-8"));
         response.end();
       } else {
-        sendJson(response, 200, { schemaVersion: 1, task: taskDetailProjection(task) });
+        const usage = await taskUsageTracker.get(task).catch(() => ({
+          status: "unavailable",
+          reason: "Task usage is temporarily unavailable.",
+          task: null,
+          turns: {},
+        }));
+        sendJson(response, 200, {
+          schemaVersion: 1,
+          task: { ...taskDetailProjection(task), usage },
+        });
       }
       return;
     }