@dtlabs/ai-toolkit 0.16.4 → 0.16.6

package/CHANGELOG.md

@@ -1,4 +1,22 @@
 ## 0.1.4 (2026-07-21)
+## [0.16.6](https://github.com/dtlab-tech/ai-toolkit/compare/v0.16.5...v0.16.6) (2026-10-06)
+
+
+### Bug Fixes
+
+* **task-executor:** drop --permission-prompts, it doesn't exist ([903dea5](https://github.com/dtlab-tech/ai-toolkit/commit/903dea58fba475e3bf5caa83a41723977f6d742e))
+* **task-executor:** drop --permission-prompts, it doesn't exist ([9c49c78](https://github.com/dtlab-tech/ai-toolkit/commit/9c49c789f385e88763d606d70bdfd9653e37a948))
+
+## [0.16.5](https://github.com/dtlab-tech/ai-toolkit/compare/v0.16.4...v0.16.5) (2026-10-05)
+
+
+### Bug Fixes
+
+* **task-executor:** implement the real executor status command ([58710aa](https://github.com/dtlab-tech/ai-toolkit/commit/58710aa5824108355076df697291a39dc8cd22f1))
+* **task-executor:** permissions, ledger finalize, review verdicts ([91fedef](https://github.com/dtlab-tech/ai-toolkit/commit/91fedef1e3adb0b8ca64114f786d324e43991d64))
+* **task-executor:** restore permission bypass and close ledger activities ([40aa1d5](https://github.com/dtlab-tech/ai-toolkit/commit/40aa1d5ba115a2438b6af66ff26a50956b9dcd3e))
+* **task-executor:** surface build/test-driven review FAIL reasons ([09c0052](https://github.com/dtlab-tech/ai-toolkit/commit/09c0052109195d2b2b2f336a7b0fa1a892512787))
+
 ## [0.16.4](https://github.com/dtlab-tech/ai-toolkit/compare/v0.16.3...v0.16.4) (2026-10-02)
 
 

package/bin/cli.js

@@ -2671,14 +2671,18 @@ function _executorCurrentBranchRef(projectDir) {
 //     METADATA_RESERVED_FIELD, METADATA_UNKNOWN_KEY, INVALID_STATUS.
 //
 //   1 (unexpected I/O) — the DEFAULT for everything else, including every
-//     *_CORRUPTED/CORRUPT_* code, every GIT_*_FAILED/*_FAILED git-command-
-//     spawn code, STATE_UNRECOVERABLE, and — explicitly, per this task's own
-//     brief — NOT_IMPLEMENTED. `status`/`diagnose` are still NOT_IMPLEMENTED
-//     stubs in lib/task-executor/index.js (attributed to US-06-TASK-BE-01/02,
-//     neither of which has actually built their real body yet); this CLI
-//     wires them through exactly like the other five commands and lets that
-//     error surface through this same mapping table honestly — it is not
-//     hidden or special-cased, it simply falls into the default bucket.
+//     *_CORRUPTED/CORRUPT_* code (LEDGER_CORRUPTED/PRICING_CORRUPTED among
+//     them — status()'s own ledger/pricing-file reads), every
+//     LEDGER_READ_FAILED/PRICING_READ_FAILED/GIT_*_FAILED/*_FAILED
+//     git-command-spawn code, STATE_UNRECOVERABLE, and — explicitly, per this
+//     task's own brief — NOT_IMPLEMENTED. `diagnose` is still a
+//     NOT_IMPLEMENTED stub in lib/task-executor/index.js (attributed to
+//     US-06-TASK-BE-02, which has not actually built its real body yet);
+//     `status` now has a real implementation (it never was actually assigned
+//     a Work Breakdown task of its own — its stub's US-06-TASK-BE-01
+//     attribution was stale, that task is resume/reconcile) and is wired
+//     through exactly like the other commands, its errors surfacing through
+//     this same mapping table honestly.
 //
 // 8 (paused awaiting human decision) has no throw site and is deliberately
 // absent from this table: execute()'s/resume()'s 'paused' run status is a
@@ -2725,6 +2729,7 @@ const EXECUTOR_EXIT_CODE_BY_ERROR_CODE = {
   // though 1 is also the default fallback below)
   STATE_CORRUPTED: 1, RECEIPT_CORRUPTED: 1, INTENT_CORRUPTED: 1, LEASE_CORRUPTED: 1,
   CORRUPT_LEDGER: 1, STATE_UNRECOVERABLE: 1, NOT_IMPLEMENTED: 1,
+  LEDGER_READ_FAILED: 1, LEDGER_CORRUPTED: 1, PRICING_READ_FAILED: 1, PRICING_CORRUPTED: 1,
   GIT_SPAWN_FAILED: 1, GIT_STATUS_FAILED: 1, GIT_ADD_FAILED: 1, GIT_WRITE_TREE_FAILED: 1,
   GIT_DIFF_FAILED: 1, GIT_COMMIT_TREE_FAILED: 1, REF_UPDATE_FAILED: 1, GIT_CAT_FILE_FAILED: 1,
   GIT_MERGE_BASE_FAILED: 1, GIT_REV_PARSE_FAILED: 1, GIT_CHERRY_PICK_FAILED: 1,
@@ -2785,13 +2790,17 @@ async function handleExecutorCommand(argv) {
   function emitSuccess(result) {
     process.stdout.write(JSON.stringify(result, null, 2) + '\n');
     // Tech-Spec section 10 exit code 8 ("paused awaiting human decision") is a
-    // SUCCESS-path outcome, not an error — only execute()'s and resume()'s
-    // result objects can legitimately carry `runStatus: 'paused'` (see the
-    // exit-code mapping comment above EXECUTOR_EXIT_CODE_BY_ERROR_CODE for why
-    // no *_ERROR code maps to 8). reconcile/stop/replan results never carry a
-    // `runStatus` field at all, and status/diagnose never reach this success
-    // path (still NOT_IMPLEMENTED) — so this check is a no-op for every other
-    // subcommand's result shape and never needs to be scoped by subcommand.
+    // SUCCESS-path outcome, not an error — execute()'s, resume()'s and now
+    // status()'s result objects can legitimately carry `runStatus: 'paused'`
+    // (see the exit-code mapping comment above EXECUTOR_EXIT_CODE_BY_ERROR_CODE
+    // for why no *_ERROR code maps to 8). A `status` call truthfully reporting
+    // a paused run surfaces the same exit 8 signal a direct execute()/resume()
+    // call would — deliberate, not a special case: the exit code reflects the
+    // run's actual state, not which subcommand observed it. reconcile/stop/
+    // replan results never carry a `runStatus` field at all, and diagnose
+    // never reaches this success path (still NOT_IMPLEMENTED) — so this check
+    // stays a no-op for those subcommands' result shapes without needing to be
+    // scoped by subcommand.
     process.exitCode = result && result.runStatus === 'paused' ? 8 : 0;
   }
 

package/docs/task-executor-bootstrap.md

@@ -57,12 +57,12 @@ conversation at all — the operator uses the read-only `status` subcommand docu
 ai-toolkit executor status --project <path> --run-id <uuid>
 ```
 
-Note, per the CLI reference, that `status` (like `diagnose`) is currently a stub that always
-throws `NOT_IMPLEMENTED` (exit 1) — the command surface and its intended read-only summary shape
-(task status counts, run status, total cost from the ledger) are defined, but the real body has
-not been built yet (attributed there to `US-06-TASK-BE-01`). Until it lands, checking on a
-running or finished executor run means reading the ledger and per-run state directly, or using
-`reconcile`/`resume`, both of which are fully implemented and report each task's classification.
+`status` returns task status counts, run status, and (when measurable) total tokens/cost from
+the run's own ledger — see `docs/task-executor-cli.md` for the exact result shape and the
+null-compatibility rules around `totalTokens`/`totalCostUsd`. `diagnose` is still a stub that
+always throws `NOT_IMPLEMENTED` (exit 1, attributed to `US-06-TASK-BE-02`); until it lands,
+deeper per-attempt evidence inspection means using `reconcile`/`resume`, both fully implemented
+and reporting each task's classification.
 
 For the full flag reference, exit-code table, and JSON result schemas of every subcommand
 (`start`, `status`, `diagnose`, `stop`, `reconcile`, `resume`, `replan`), see

package/docs/task-executor-cli.md

@@ -57,6 +57,23 @@ Only `maxConcurrency=1` is implemented — any other requested value is **reject
 on any platform other than `win32` (see "Platform qualification" below), before touching any
 other validation.
 
+**Permission bypass.** Every real implementation/review worker this loop dispatches is spawned
+with `--permission-mode auto` appended to its CLI args (`EXECUTOR_PERMISSION_BYPASS_ARGS` in
+`lib/task-executor/index.js`). A non-interactive `--print` invocation has no TTY to answer a
+permission prompt, so without this every Write/Edit/mkdir tool call is denied by default,
+regardless of task content — confirmed against a real run where every BE/FE task failed
+verification because its expected files/directories were never created. `auto` alone was then
+independently confirmed sufficient (a live dispatch created all of its task's expected
+directories and files). An earlier version of this fix also appended `--permission-prompts
+none`, citing Tech-Spec OQ-01's pre-Gate-1 spike note as having validated that exact pair —
+reproduced directly against the real, installed CLI (v2.1.220): `--permission-prompts` is not a
+recognized flag at all (`claude --help` lists no such option; passing it exits 1 with `error:
+unknown option '--permission-prompts'` before any model/API call), so that spike note is stale or
+was never run against the real executable as claimed. The mode is deliberately unscoped within
+the task's own `--project` directory — the executor's job is letting a developer agent write
+anywhere under that project, so (unlike pm-phase1/2's read-only-text workers) a narrower
+allowlist is not an option here.
+
 ### `status`
 
 ```bash
@@ -66,11 +83,40 @@ ai-toolkit executor status --project <path> --run-id <uuid>
 `--run-id` is required (usage error, exit 2, if omitted). Read-only summary of a run: task
 status counts, current run status, and total cost from the ledger.
 
-**Not implemented.** `status()` in `lib/task-executor/index.js` is currently a stub that always
-throws `NOT_IMPLEMENTED` (attributed to US-06-TASK-BE-01, which has not built its real body
-yet). Calling `ai-toolkit executor status` today always fails with exit code 1 and an error
-JSON body — it does not return the summary shape documented in its own JSDoc until that task is
-implemented.
+Backs `lib/task-executor/index.js`'s `status()`. Returns:
+
+```json
+{
+  "protocolVersion": 1,
+  "runId": "...",
+  "runStatus": "running",
+  "taskCounts": { "pending": 0, "active": 0, "checkpointed": 0, "integrated": 0, "skipped": 0, "blocked": 0 },
+  "totalTokens": null,
+  "totalCostUsd": null
+}
+```
+
+`taskCounts` is derived straight from the persisted `state.json` (`store.readState`) — never
+mutates it. `totalTokens` sums every numeric `phase_delta_tokens` entry in the run's own
+`<runId>-token-ledger.json`; `totalCostUsd` additionally requires the target project's own
+`docs/token-pricing.json` (same file and 80/20 input/output split `lib/workflow-artifacts.js`
+uses for feature Token-Estimate documents) and a non-null `model` on each ledger entry to attach
+a rate to. `dispatchTaskAttempt`/`runReview` (`lib/task-executor/index.js`) always open their
+`implementation`/`review` ledger activities with `model: null`, so `totalCostUsd` is `null` until
+that changes — this is a known gap, not a bug: **null means "unavailable", never a fabricated
+zero** (same null-compatibility convention as the Token-Estimate document). `totalTokens` does
+not share that gap: `_runTaskToResolution` now closes every `implementation`/`review` activity
+(`done` with its measured tokens on a normal return, `failed` with `tokens: null` on a genuine
+spawn-level error) immediately after each dispatch, so a completed or still-running real run
+reports real summed tokens — previously these activities were opened and never closed at all, so
+every run's `totalTokens` was unconditionally `null` regardless of outcome. If `runStatus`
+happens to be `'paused'`, the CLI exits 8, same as `execute`/`resume` reporting that status
+directly — the exit code reflects the run's actual state, not which subcommand observed it.
+
+If the run is missing or its `state.json` is corrupted, `STATE_NOT_FOUND`/`STATE_CORRUPTED`
+propagate unmodified (exit 4 / exit 1 respectively). An unreadable or unparseable ledger or
+pricing file throws `LEDGER_READ_FAILED`/`LEDGER_CORRUPTED`/`PRICING_READ_FAILED`/
+`PRICING_CORRUPTED` (exit 1) rather than silently reporting a partial or zeroed-out total.
 
 ### `diagnose`
 

package/lib/task-executor/index.js

@@ -74,6 +74,41 @@ function _buildProcessTag(runId, taskId, attemptNumber) {
 // the tagged "worker" under test, per this task's own testing constraint.
 const DEFAULT_TAGGED_PROCESS_EXE_BASENAME = 'claude.exe';
 
+// Permission-bypass flag required for every real (non-test-fixture) worker
+// spawn — implementation AND review alike. Without it, a non-interactive
+// `--print` invocation has no TTY to answer a permission prompt, so every
+// Write/Edit/mkdir tool call is denied by default: confirmed against a real
+// blocked run (INFRA-TASK-INFRA-01's own post-dispatch verification found
+// none of its expected directories had been created) before this constant
+// existed at all. `--permission-mode auto` is a real, documented choice on
+// the installed CLI (`claude --help`: "(choices: \"acceptEdits\", \"auto\",
+// \"bypassPermissions\", \"manual\", \"dontAsk\", \"plan\")") and is
+// deliberately broad (unscoped within the spawned cwd) — the executor's
+// whole job is letting a developer agent write anywhere under the task's
+// project, so a narrower scoped allowlist is not an option here the way it
+// was for pm-phase1/2's read-only-text workers (see
+// lib/workflow-control.js's own doc comment on why THAT subsystem sidesteps
+// Write entirely instead).
+//
+// CORRECTION: an earlier version of this constant also appended
+// `--permission-prompts none`, citing Tech-Spec OQ-01's pre-Gate-1 spike
+// note ("Percorso C", resolved 2026-09-18) as having validated that exact
+// pair. Reproduced directly against the real, currently-installed CLI
+// (v2.1.220): `--permission-prompts` is NOT a recognized flag at all —
+// `claude --print --permission-mode auto --permission-prompts none` fails
+// immediately with `error: unknown option '--permission-prompts'` (exit 1,
+// commander.js argv validation, before any model/API call). Every dispatch
+// would have failed closed again, just with a different symptom (an argv
+// crash instead of a denied Write) — so the historical spike note is either
+// stale against a since-changed CLI surface or was never run against the
+// real executable as literally claimed (this Tech-Spec history already
+// contains one prior instance of an overclaimed, later-audited-away result —
+// see FTR-018-Gate1-Review-Actions.md's own "Correction (2026-09-22)"). Only
+// `--permission-mode auto` is carried forward; it alone was independently
+// confirmed sufficient (a live dispatch created all of its task's expected
+// directories and files).
+const EXECUTOR_PERMISSION_BYPASS_ARGS = ['--permission-mode', 'auto'];
+
 // Real, positive-evidence-only liveness query for a tagged process, using
 // the exact E-02-qualified Win32_Process/CIM technique proven in the Gate-1
 // evidence spike, adapted from `Name='node.exe'` to the caller-supplied
@@ -255,6 +290,44 @@ function _err(code, message) {
   return e;
 }
 
+// Mirrors lib/workflow-control.js's worker() token-measurement convention
+// exactly (same four usage fields, same "only trust a whole, non-negative
+// total" rule) so this module reports token usage under the same shared
+// definition of "measured" vs "unavailable" the rest of the toolkit uses.
+// Returns null (never 0) when usage is missing, partial, or computes to a
+// non-positive total.
+function _measureTokensFromSpawnResult(spawnResult) {
+  const usage = spawnResult && spawnResult.result && spawnResult.result.usage;
+  if (!usage) return null;
+  const counts = [
+    usage.input_tokens, usage.output_tokens,
+    usage.cache_read_input_tokens || 0, usage.cache_creation_input_tokens || 0,
+  ];
+  if (!counts.every(function (n) { return Number.isInteger(n) && n >= 0; })) return null;
+  const total = counts.reduce(function (a, b) { return a + b; }, 0);
+  return Number.isSafeInteger(total) && total > 0 ? total : null;
+}
+
+// Finalizes the 'implementation' or 'review' ledger activity dispatchTaskAttempt/
+// runReview already opened for this attempt (Tech-Spec section 6 ledger-kind
+// strings) — previously left open forever by _runTaskToResolution regardless
+// of outcome (confirmed against a real run: every 'implementation'/'review'
+// entry stayed status:'running' indefinitely, even for permanently-failed
+// tasks). `kind` must be 'implementation' or 'review'; the agent key this
+// reconstructs must match, byte for byte, the literal string
+// dispatchTaskAttempt/runReview used when calling ledger.open (their own
+// 'executor:'+runId+':'+task.id+':'+kind construction) — finalizeActivity
+// requires an exact operation_id match, no name-only fallback.
+function _finalizeDispatchLedgerActivity(executionRoot, runId, taskId, attemptNumber, kind, options) {
+  return ledger.finalizeActivity(
+    store._executionPaths(executionRoot, runId).runDir,
+    runId,
+    'executor:' + runId + ':' + taskId + ':' + kind,
+    attemptNumber,
+    options
+  );
+}
+
 function _requireNonEmptyString(value, label) {
   if (typeof value !== 'string' || value.length === 0) {
     throw _err('DISPATCH_VALIDATION_ERROR', label + ' must be a non-empty string');
@@ -529,7 +602,7 @@ async function dispatchTaskAttempt(args) {
   const prompt = typeof args.prompt === 'string' ? args.prompt : _buildTaskPrompt(task);
   const baseSpawnArgs = Array.isArray(args.spawnArgs)
     ? args.spawnArgs
-    : ['--print', '--output-format', 'json', '--agent', identity.nativeName];
+    : ['--print', '--output-format', 'json', '--agent', identity.nativeName].concat(EXECUTOR_PERMISSION_BYPASS_ARGS);
   // Append the same processIdentity tag already persisted above as one extra
   // trailing argv element, so it appears verbatim in the spawned process's
   // own command line — this is what makes _findLiveTaggedProcess's later OS
@@ -625,6 +698,12 @@ function _buildReviewPrompt(task, diff) {
 // text> }. When the reply does not match the template (missing/malformed
 // envelope, or free text that doesn't follow it), `passed` is reported as
 // `null` rather than guessed — this function never fabricates a pass.
+// `criticalFindings` captures both the "CRITICAL (blocks merge):" section AND
+// any "Build:"/"Tests:" empirical-verification line carrying the template's
+// own ❌ marker — the agent's contract allows FAIL via either path ("FAIL =
+// 1+ CRITICAL findings OR build/test failure"), so a build/test-driven FAIL
+// is reported just as explainably as a findings-driven one, never as an
+// empty, unexplained list.
 // Authoritative pass/fail enforcement against the Tech-Spec's binding rule
 // ("review passed=true with no blocking finding") is intentionally left to
 // US-04-TASK-BE-03 (closing / combined verification+review outcome
@@ -655,6 +734,26 @@ function _extractReviewVerdict(spawnResult) {
     });
   }
 
+  // The agent's own contract (src/claude/agents/gaia-review-solution.md,
+  // "## Output": "FAIL = 1+ CRITICAL findings OR build/test failure") allows
+  // a FAIL verdict with zero CRITICAL findings, driven instead by its
+  // "Build: ✅/❌ ..." / "Tests: ✅/❌ ..." empirical-verification lines.
+  // Without surfacing those too, a build/test-driven FAIL was
+  // indistinguishable from an unexplained one — criticalFindings: [] either
+  // way (confirmed against a real run: a review-only task with zero code
+  // changes failed review twice with reviewPassed:false, criticalFindings:
+  // [], and no other evidence persisted anywhere to tell the two cases
+  // apart). Any Build/Tests line carrying the template's own ❌ failure
+  // marker is folded in here — it is exactly as blocking per the agent's own
+  // documented contract, so the outcome receipt now always explains a FAIL,
+  // not only a CRITICAL-findings one.
+  const empiricalMatches = text.matchAll(/^[ \t]*(Build|Tests):[ \t]*(.*)$/gim);
+  for (const m of empiricalMatches) {
+    if (m[2].indexOf('❌') !== -1) {
+      criticalFindings.push(m[1] + ': ' + m[2].trim());
+    }
+  }
+
   return { passed: passed, criticalFindings: criticalFindings };
 }
 
@@ -796,7 +895,7 @@ async function runReview(args) {
   const prompt = _buildReviewPrompt(task, diff);
   const spawnArgs = Array.isArray(args.spawnArgs)
     ? args.spawnArgs
-    : ['--print', '--output-format', 'json', '--agent', identity.nativeName];
+    : ['--print', '--output-format', 'json', '--agent', identity.nativeName].concat(EXECUTOR_PERMISSION_BYPASS_ARGS);
   const spawnResult = await claudeProcess.spawnClaudeAgent({
     claudePath: args.claudePath,
     args: spawnArgs,
@@ -1924,6 +2023,14 @@ async function _runTaskToResolution(ctx) {
         // via its own try/finally).
         throw dispatchErr;
       }
+      // Close the 'implementation' ledger activity dispatchTaskAttempt already
+      // opened before this threw — the same persist-before-invoke ordering
+      // that proves the attempt was durably recorded (the check just above)
+      // also proves ledger.open already ran for it. Otherwise this activity
+      // would stay open forever, exactly the gap the success path below also
+      // fixes.
+      _finalizeDispatchLedgerActivity(executionRoot, runId, taskId, attemptNumber, 'implementation',
+        { status: 'failed', tokens: null, reason: dispatchErr.code || 'UNKNOWN' });
       // Genuine spawn-level failure (spawnClaudeAgent itself threw) AFTER
       // the attempt was already durably recorded — this DOES consume the
       // attempt, exactly like a verification/review failure does.
@@ -1952,7 +2059,19 @@ async function _runTaskToResolution(ctx) {
       continue;
     }
 
-    void dispatchResult; // raw spawn capture only — not otherwise consulted here.
+    // Close the 'implementation' ledger activity opened by dispatchTaskAttempt
+    // — previously left open forever (confirmed against a real run: every
+    // 'implementation'/'review' entry stayed status:'running' indefinitely,
+    // even for tasks that had already reached a terminal 'failed' stage).
+    // "done" here means the subprocess ran to completion and returned a
+    // result, independent of whether verification/review later judges that
+    // result a pass or fail — that judgment is recorded separately, on the
+    // task's own outcome receipt (persistVerificationReviewOutcome below),
+    // never on this activity's ledger status. Mirrors the 'task'-kind
+    // control-only close below (finalizeTaskCheckpoint) in structure, but
+    // carries real measured tokens instead of an always-null control signal.
+    _finalizeDispatchLedgerActivity(executionRoot, runId, taskId, attemptNumber, 'implementation',
+      { status: 'done', tokens: _measureTokensFromSpawnResult(dispatchResult.spawnResult) });
 
     const verification = await runVerifications({
       executionRoot: executionRoot, runId: runId, task: task, attemptNumber: attemptNumber,
@@ -1972,6 +2091,12 @@ async function _runTaskToResolution(ctx) {
         claudePath: ctx.claudePath, projectDir: projectDir, diff: diff, taskTimeoutMs: ctx.taskTimeoutMs,
         spawnArgs: ctx.reviewSpawnArgs,
       });
+      // Close the 'review' ledger activity runReview already opened — same
+      // previously-open-forever gap the 'implementation' close above fixes,
+      // same reasoning: "done" reflects the subprocess completing, not the
+      // review's own pass/fail verdict (that lives on the outcome receipt).
+      _finalizeDispatchLedgerActivity(executionRoot, runId, taskId, attemptNumber, 'review',
+        { status: 'done', tokens: _measureTokensFromSpawnResult(review.spawnResult) });
     }
 
     const outcome = store.persistVerificationReviewOutcome(executionRoot, runId, taskId, attemptNumber, verification, review);
@@ -2792,14 +2917,121 @@ async function execute(args) {
   }
 }
 
+// Reads the run's own token ledger (<executionRoot>/runs/<runId>/<runId>-
+// token-ledger.json, written by ../execution-ledger.js's open/close/fail/
+// skip) as a flat array of entries. No activity opened yet is a normal,
+// non-error state (returns []) — a present-but-unparseable file fails closed
+// instead, since that is evidence of a corrupted run, not an empty one.
+function _readRunLedgerEntries(executionRoot, runId) {
+  const ledgerPath = path.join(executionRoot, 'runs', runId, runId + '-token-ledger.json');
+  let raw;
+  try {
+    raw = fs.readFileSync(ledgerPath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw _err('LEDGER_READ_FAILED', 'status: failed to read token ledger at ' + ledgerPath + ': ' + err.message);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw _err('LEDGER_CORRUPTED', 'status: token ledger at ' + ledgerPath + ' is not valid JSON: ' + err.message);
+  }
+  if (!Array.isArray(parsed)) {
+    throw _err('LEDGER_CORRUPTED', 'status: token ledger at ' + ledgerPath + ' must be a JSON array, got ' + typeof parsed);
+  }
+  return parsed;
+}
+
+// Loads docs/token-pricing.json from the TARGET project (args.project), not
+// this toolkit's own checkout — the same file and project-relative
+// resolution lib/workflow-artifacts.js's pricing() uses for feature
+// Token-Estimate documents (see lib/workflow-control.js). A missing file
+// means "cost unavailable", not an error: not every consuming project ships
+// pricing data, and status must still report token counts for one that
+// doesn't. A present-but-invalid file fails closed.
+function _loadTokenPricing(projectDir) {
+  const pricingPath = path.join(projectDir, 'docs', 'token-pricing.json');
+  let raw;
+  try {
+    raw = fs.readFileSync(pricingPath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw _err('PRICING_READ_FAILED', 'status: failed to read token pricing at ' + pricingPath + ': ' + err.message);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw _err('PRICING_CORRUPTED', 'status: token pricing at ' + pricingPath + ' is not valid JSON: ' + err.message);
+  }
+  if (!parsed || !parsed.models || !Number.isFinite(parsed.usd_to_eur) || parsed.usd_to_eur <= 0) {
+    throw _err('PRICING_CORRUPTED', 'status: token pricing at ' + pricingPath + ' is missing "models" or a valid "usd_to_eur" rate');
+  }
+  return parsed;
+}
+
+// USD cost for one ledger entry's measured tokens, using the estimated
+// 80/20 input/output split already established by lib/workflow-artifacts.js's
+// cost() for the same pricing file — unlike that helper, this never converts
+// to EUR (the field this feeds is totalCostUsd). Returns null (not 0) when
+// the entry's model is missing/unknown or its tokens are not a finite number
+// — an unattributable entry is excluded from the total, never coerced into a
+// zero-cost one.
+function _usdCostForLedgerEntry(tokens, model, pricing) {
+  if (!Number.isFinite(tokens) || typeof model !== 'string' || model.length === 0) return null;
+  const rate = pricing.models[model];
+  if (!rate || !Number.isFinite(rate.input_per_1m_usd) || !Number.isFinite(rate.output_per_1m_usd)) return null;
+  return tokens * (0.8 * rate.input_per_1m_usd + 0.2 * rate.output_per_1m_usd) / 1000000;
+}
+
+// Null-compatibility (mirrors the convention already established by
+// src/claude/skills/implement-feature/SKILL.md's Step 7 and
+// lib/workflow-artifacts.js's pricing/cost helpers): a token value that is
+// null/undefined/not a finite number is "not yet measured", never coerced
+// into a real, observable zero. totalTokens/totalCostUsd stay null — not 0 —
+// when nothing measurable exists yet, so a caller can tell "nothing spent"
+// apart from "nothing reported". Every executor ledger entry is currently
+// opened with model: null (see _runTaskToResolution's ledger.open calls
+// above), so totalCostUsd is null whenever no pricing file is present OR
+// every entry's model is still unattributed — both are legitimate,
+// non-error outcomes, not a bug in this function.
+function _summarizeLedgerTotals(entries, projectDir) {
+  let totalTokens = null;
+  let totalCostUsd = null;
+  let pricing;
+  let pricingLoaded = false;
+
+  entries.forEach(function (entry) {
+    const tokens = entry.phase_delta_tokens;
+    if (!Number.isFinite(tokens)) return;
+    totalTokens = (totalTokens || 0) + tokens;
+
+    if (!pricingLoaded) {
+      pricing = _loadTokenPricing(projectDir);
+      pricingLoaded = true;
+    }
+    if (!pricing) return;
+
+    const entryCost = _usdCostForLedgerEntry(tokens, entry.model, pricing);
+    if (entryCost === null) return;
+    totalCostUsd = (totalCostUsd || 0) + entryCost;
+  });
+
+  return { totalTokens: totalTokens, totalCostUsd: totalCostUsd };
+}
+
 /**
  * `status` command. Read-only summary of a run: counts of tasks per
  * status, current run status, and total cost as reported by the ledger
  * (the sole cost source). Never mutates state.
  *
- * Real implementation: US-06-TASK-BE-01 (loads persisted state/evidence and
- * classifies task status per the edge-cases table this summary is built
- * from).
+ * Built entirely from three already-implemented data sources — no new Work
+ * Breakdown task was required: store.readState (INFRA-TASK-BE-01) for task
+ * statuses/runStatus, the run's own token-ledger.json
+ * (INFRA-TASK-BE-02/../execution-ledger.js) for token counts, and the
+ * target project's docs/token-pricing.json (already read the same way by
+ * lib/workflow-artifacts.js) for USD cost attribution.
  *
  * @param {object} args
  * @param {string} args.project - Absolute or project-relative repo path.
@@ -2808,9 +3040,50 @@ async function execute(args) {
  *   { protocolVersion, runId, runStatus,
  *     taskCounts: { pending, active, checkpointed, integrated, skipped, blocked },
  *     totalTokens, totalCostUsd }.
+ *   totalTokens/totalCostUsd are null (never 0) when nothing measurable has
+ *   been recorded yet, or (totalCostUsd only) when the project ships no
+ *   docs/token-pricing.json.
+ * @throws {Error} DISPATCH_VALIDATION_ERROR for a malformed args.project/
+ *   args.runId (via _requireNonEmptyString, same as every other command in
+ *   this module); any error store.readState throws (STATE_NOT_FOUND,
+ *   STATE_CORRUPTED) propagates unmodified — a corrupted/missing run is
+ *   never silently defaulted; LEDGER_READ_FAILED/LEDGER_CORRUPTED/
+ *   PRICING_READ_FAILED/PRICING_CORRUPTED for an unreadable or unparseable
+ *   ledger or pricing file.
  */
 async function status(args) {
-  return _notImplemented('status', 'US-06-TASK-BE-01');
+  args = args || {};
+  _requireNonEmptyString(args.project, 'status: args.project');
+  _requireNonEmptyString(args.runId, 'status: args.runId');
+
+  const projectDir = args.project;
+  const runId = args.runId;
+  const commonDir = _resolveCommonGitDir(projectDir);
+  const executionRoot = path.join(commonDir, 'ai-toolkit', 'execution');
+
+  // Propagates STATE_NOT_FOUND / STATE_CORRUPTED unmodified — never
+  // fabricates an empty/default run for a corrupted/missing one.
+  const state = store.readState(executionRoot, runId);
+
+  const taskCounts = { pending: 0, active: 0, checkpointed: 0, integrated: 0, skipped: 0, blocked: 0 };
+  Object.keys(state.tasks).forEach(function (taskId) {
+    const st = state.tasks[taskId].status;
+    if (Object.prototype.hasOwnProperty.call(taskCounts, st)) {
+      taskCounts[st] += 1;
+    }
+  });
+
+  const ledgerEntries = _readRunLedgerEntries(executionRoot, runId);
+  const totals = _summarizeLedgerTotals(ledgerEntries, projectDir);
+
+  return {
+    protocolVersion: store.PROTOCOL_VERSION,
+    runId: runId,
+    runStatus: state.runStatus,
+    taskCounts: taskCounts,
+    totalTokens: totals.totalTokens,
+    totalCostUsd: totals.totalCostUsd,
+  };
 }
 
 /**
@@ -3726,4 +3999,6 @@ module.exports = {
   DEFAULT_TAGGED_PROCESS_EXE_BASENAME,
   _buildProcessTag,
   _findLiveTaggedProcess,
+  _measureTokensFromSpawnResult,
+  _finalizeDispatchLedgerActivity,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtlabs/ai-toolkit",
-  "version": "0.16.4",
+  "version": "0.16.6",
   "description": "AI Toolkit — reusable agents and procedures for developers to build AI-powered applications.",
   "files": [
     "docs/",