@dtlabs/ai-toolkit 0.13.0 → 0.14.0

package/docs/task-executor-cli.md

@@ -0,0 +1,319 @@
+# Task Executor CLI
+
+> Documents the **real, currently-implemented** behavior of `ai-toolkit executor <subcommand>`
+> (`bin/cli.js`'s `handleExecutorCommand`, wired to `lib/task-executor/index.js`), part of
+> FTR-018 (deterministic task execution, checkpoints and resume).
+>
+> This file describes what the code actually does today, not the aspirational CLI contract in
+> `FTR-018-Tech-Spec.md` section 10. Every discrepancy between the two is called out explicitly
+> below rather than silently reconciled.
+
+---
+
+## Invocation
+
+```bash
+ai-toolkit executor <subcommand> [flags]
+# or, inside this repo:
+node bin/cli.js executor <subcommand> [flags]
+```
+
+`--project <path>` is accepted by every subcommand and defaults to `process.cwd()` when omitted.
+All other flags are per-subcommand (see below). Any flag not explicitly recognized for a
+subcommand is silently ignored — there is no generic flag-forwarding path, so nothing reaches a
+filesystem path or lock primitive except the whitelisted flags read via `getFlag()`/`hasFlag()`.
+
+**Discrepancy vs. Tech-Spec:** section 10 documents `--format json or text (default)` as a
+common flag. The real CLI has no `--format` flag at all — `handleExecutorCommand` always emits
+JSON (`JSON.stringify(result, null, 2)`) on success and always emits JSON on error. There is no
+text-mode output in the current implementation.
+
+---
+
+## Commands
+
+### `start`
+
+```bash
+ai-toolkit executor start --project <path> --feature <path> [--max-concurrency N] [--claude-path <path>] [--task-timeout-ms <ms>] [--agent-budget-usd <amount>]
+```
+
+| Flag | Required | Default | Notes |
+|---|---|---|---|
+| `--project` | no | `process.cwd()` | Repo root; also resolves the common Git directory |
+| `--feature` | **yes** | — | Path to the feature's `feature.md`; the CLI usage-errors (exit 2, no JSON) if omitted |
+| `--max-concurrency` | no | `1` | Forwarded to `execute()` as a Number; only `1` is currently supported (see below) |
+| `--claude-path` | no | — | Absolute path to the qualified Claude CLI executable |
+| `--task-timeout-ms` | no | — | Forwarded as a Number |
+| `--agent-budget-usd` | no | — | Forwarded as a Number; persisted into run config, not itself enforced |
+
+Backs `lib/task-executor/index.js`'s `execute()`. Validates gates/config, acquires the
+repo-wide execution lease for a brand-new run, builds an immutable plan snapshot from the
+feature's own `{PREFIX}-Work-Breakdown.md/.csv`, and drives a sequential (slot count 1)
+dispatch → verify → review → checkpoint loop to completion or block.
+
+Only `maxConcurrency=1` is implemented — any other requested value is **rejected**
+(`UNSUPPORTED_CONCURRENCY`), never silently downgraded. `execute()` also refuses to run at all
+on any platform other than `win32` (see "Platform qualification" below), before touching any
+other validation.
+
+### `status`
+
+```bash
+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.
+
+### `diagnose`
+
+```bash
+ai-toolkit executor diagnose --project <path> --run-id <uuid>
+```
+
+`--run-id` is required. Intended as a read-only detailed evidence dump (per-task/attempt
+evidence, ownership/lease state, repair suggestions).
+
+**Not implemented.** Same situation as `status`: `diagnose()` is a stub that always throws
+`NOT_IMPLEMENTED` (attributed to US-06-TASK-BE-02). Calling it today always exits 1 with an
+error JSON body.
+
+### `stop`
+
+```bash
+ai-toolkit executor stop --project <path> --run-id <uuid> [--mode graceful|immediate]
+```
+
+| Flag | Required | Default | Notes |
+|---|---|---|---|
+| `--run-id` | **yes** | — | |
+| `--mode` | no | `'graceful'` | Only `'graceful'` or `'immediate'` are accepted; anything else throws `STOP_VALIDATION_ERROR` |
+
+Persists a stop request and acknowledges receipt only — it never itself claims the run has
+stopped.
+
+- `graceful` (default): persists the request; the already-running `execute()` loop is the only
+  thing that actually enforces the block, at its next natural iteration boundary.
+- `immediate`: additionally attempts real termination of every in-flight attempt (stage
+  `dispatching`/`running` with a recorded process tag), via the same Windows-only tagged-process
+  tree-kill technique used elsewhere in this module, then polls for confirmed termination.
+
+Idempotent: if the run's current status is already `stopping` or settled
+(`completed`/`blocked`/`superseded`/`paused`), this call is a pure no-op and reports the
+originally-recorded mode.
+
+### `reconcile`
+
+```bash
+ai-toolkit executor reconcile --run-id <uuid> [--project <path>]
+```
+
+`--run-id` is required. `--project` resolves the execution root and the current-branch task ref
+automatically (via `git rev-parse --abbrev-ref HEAD` in the given `--project`, or its default,
+the current directory) — there is no separate flag for these; the CLI derives them itself.
+
+Reconciles persisted state and evidence for a run and classifies every task's current attempt.
+**Only repairs proven gaps — it never dispatches new work and never creates new integrations.**
+The only two repairs it can apply are: registering a commit SHA when a checkpoint-prepared
+attempt's tip exactly matches its own persisted checkpoint intent, and finalizing a task
+checkpoint when a committed attempt's registered SHA is confirmed reachable but the task's
+status was not yet advanced. Refuses to proceed (`COMPETING_COORDINATOR_LIVE` /
+`COMPETING_COORDINATOR_LIVENESS_UNKNOWN`) if a different, live-or-unknown-liveness coordinator
+holds the repo-wide execution lease.
+
+### `resume`
+
+```bash
+ai-toolkit executor resume --run-id <uuid> [--project <path>]
+```
+
+Same flags/derivation as `reconcile` (in fact the CLI dispatches both `reconcile` and `resume`
+through the identical flag-parsing branch, selecting the target function by subcommand name).
+Enforces the same "no live competing coordinator" precondition, then calls `reconcile()` to
+apply its repairs, then reports each task's current status plus the next-safe-action
+classification `reconcile()` already computed. Does **not** dispatch new work itself — there is
+no run loop wired into `resume()` yet (the real dispatch loop lives in `execute()`); its scope
+ends at "reconcile, then report what is safe to continue."
+
+### `replan`
+
+```bash
+ai-toolkit executor replan --run-id <uuid> --feature <path> [--project <path>] [--task-mapping-json '<json>']
+```
+
+| Flag | Required | Default | Notes |
+|---|---|---|---|
+| `--run-id` | **yes** | — | The original run being replanned |
+| `--feature` | **yes** | — | Path to the **successor** feature's `feature.md` (the approved successor plan) |
+| `--project` | no | `process.cwd()` | Resolves execution root + current-branch task ref, same as `reconcile`/`resume` |
+| `--task-mapping-json` | no | `'[]'` (empty array) | JSON array of `{oldTaskId, newTaskId}` objects |
+
+**Discrepancy vs. Tech-Spec:** the table in section 10 lists only `--run-id`/`--feature` for
+`replan`. The real `replan()` in `lib/task-executor/index.js` requires `args.taskMapping` to be
+an array (throwing `DISPATCH_VALIDATION_ERROR` otherwise) and never invents one itself. The CLI
+therefore added `--task-mapping-json` as a necessary extension beyond the literal table, using
+the same `--*-json` structured-input convention the `ledger` subcommand already established
+(`--metadata-json`). This is documented here as an intentional, flagged gap — not silently
+papered over — per the implementing agent's own note at the flag's parse site in `bin/cli.js`.
+Omitting the flag defaults to an empty mapping (a valid "no task carries forward" array), never
+a rejection.
+
+Grants **no approval itself** — the successor's Gate 2 approval must already exist on disk
+(`## Gate 2` heading in its `Approvals.md`, produced entirely outside the executor by the normal
+`implement-feature` gate protocol). Does not dispatch, start, or touch the successor run in any
+way. Validates the caller-supplied old→new task mapping against both the original run's recorded
+tasks and the successor's plan snapshot, computes carry-completion eligibility per pair
+(read-only), refuses if any original-run attempt's worker liveness is not confirmed dead
+(`LIVE_WORKER_BLOCKS_REPLAN`), then records the mapping as a durable intent and marks the
+original run `superseded`. Never deletes or rewrites any task/attempt evidence.
+
+---
+
+## Exit codes
+
+| Exit code | Meaning |
+|---|---|
+| 0 | Successful operation/request |
+| 1 | Unexpected I/O (also the default for any unmapped/unknown error code) |
+| 2 | Invalid config/input |
+| 3 | Ownership/live worker conflict |
+| 4 | Evidence/plan/approval mismatch |
+| 5 | Worker/verification/review failure |
+| 6 | Integration conflict |
+| 7 | Runtime not qualified |
+| 8 | Paused awaiting human decision |
+
+This table matches `bin/cli.js`'s `EXECUTOR_EXIT_CODE_BY_ERROR_CODE` mapping (plus a
+suffix-based catch-all: any error code ending in `_VALIDATION_ERROR` maps to exit 2). A few
+notable groupings from that mapping:
+
+- **3** — every lease/ownership code: `LEASE_HELD`, `LEASE_NOT_OWNER`, `LEASE_STILL_LIVE`,
+  `LEASE_LIVENESS_UNKNOWN`, `LEASE_NOT_FOUND`, `GUARD_HELD`, `NO_LOCK_HELD`,
+  `COMPETING_COORDINATOR_LIVE`, `COMPETING_COORDINATOR_LIVENESS_UNKNOWN`,
+  `LIVE_WORKER_BLOCKS_REPLAN`.
+- **4** — every "plan/evidence/approval doesn't match" code, including
+  `SUCCESSOR_NOT_APPROVED`, `PLAN_NOT_FOUND`, `PLAN_PARSE_ERROR`, `REPLAN_UNKNOWN_TASK_MAPPING`,
+  `STATE_NOT_FOUND`/`STATE_TASK_NOT_FOUND`/`STATE_ATTEMPT_NOT_FOUND`, `TREE_MISMATCH`,
+  `RECEIPT_CONFLICT`, `INTENT_CONFLICT`, and many more (see the source comment for the full
+  list).
+- **5** — `CLAUDE_SPAWN_FAILED`, `AGENT_NOT_VERIFIED`, `RESOLUTION_FAILED`.
+- **6** — `INTEGRATION_CONFLICT`.
+- **7** — `PLATFORM_NOT_QUALIFIED` (see "Platform qualification" below).
+- **1 (default)** — includes `NOT_IMPLEMENTED` explicitly, so `status`/`diagnose` calls exit 1
+  today, not some special code.
+
+**Exit code 8 is a success-path outcome, never a thrown error** — unlike every other code
+above, which is assigned only on the error path via `mapExecutorErrorToExitCode`. Per the
+Tech-Spec, 8 means "paused awaiting human decision": `execute()`'s and `resume()`'s result
+objects can both legitimately carry `runStatus: 'paused'` (set when a `stop()` request — either
+mode — was observed at a loop boundary; `resume()` simply passes through whatever `runStatus`
+was last persisted, including `'paused'`). `handleExecutorCommand`'s shared `emitSuccess()`
+inspects `result.runStatus` and sets exit code **8** when it is `'paused'`, else **0** — this is
+a no-op check for `reconcile`/`stop`/`replan` (their result shapes never carry a `runStatus`
+field at all) and never applies to `status`/`diagnose` (still `NOT_IMPLEMENTED`, so they never
+reach the success path).
+
+---
+
+## JSON result schema
+
+### Success (stdout, exit matches the table above)
+
+Every command that has a real implementation returns a **versioned result object** —
+`{ protocolVersion, ... }` — written to stdout as pretty-printed JSON. Per
+`lib/task-executor/index.js`'s own JSDoc/return statements:
+
+**`start` (`execute()`) and `resume`:**
+```json
+{
+  "protocolVersion": 1,
+  "runId": "<uuid>",
+  "runStatus": "completed | blocked | paused",
+  "tasks": [ { "taskId": "US-01-T01", "status": "checkpointed" } ]
+}
+```
+`resume`'s object additionally carries `tasks[].nextAction` (the next-safe-action classification
+from `reconcile()`) and a top-level `repairsApplied` array — both additive beyond the minimum
+shape above.
+
+**`stop`:**
+```json
+{
+  "protocolVersion": 1,
+  "runId": "<uuid>",
+  "requestAccepted": true,
+  "mode": "graceful | immediate",
+  "idempotent": true,
+  "terminationConfirmed": true,
+  "killAttempts": [
+    { "taskId": "US-01-T01", "attemptNumber": 1, "processIdentity": "ai-toolkit-task:...", "confirmed": true }
+  ]
+}
+```
+`idempotent` is present only on an idempotent replay. `terminationConfirmed`/`killAttempts` are
+present only for a newly-accepted `immediate` request — never for `graceful`, never for an
+idempotent replay.
+
+**`reconcile`:**
+```json
+{
+  "protocolVersion": 1,
+  "runId": "<uuid>",
+  "repairsApplied": [ { "taskId": "US-01-T01", "action": "registerCommitSHA" } ],
+  "classifications": [ { "taskId": "US-01-T01", "classification": "...", "action": "..." } ]
+}
+```
+
+**`replan`:**
+```json
+{
+  "protocolVersion": 1,
+  "originalRunId": "<uuid>",
+  "successorPlanDigest": "<digest>",
+  "taskMapping": [
+    { "oldTaskId": "US-01-T01", "newTaskId": "US-01-T01", "carriesCompletion": true }
+  ]
+}
+```
+
+**`status`/`diagnose`:** no success shape exists yet — both are `NOT_IMPLEMENTED` stubs (see
+above); every call surfaces the error shape below with `code: "NOT_IMPLEMENTED"`.
+
+### Error (stderr, exit per the table above)
+
+```json
+{
+  "status": "error",
+  "code": "NO_LOCK_HELD",
+  "message": "dispatchTaskAttempt: no repo-wide execution lease held by runId \"...\" at ..."
+}
+```
+
+This is `bin/cli.js`'s real `emitError()` shape: `code` falls back to `'UNKNOWN'` if the thrown
+error carries no `.code`; `message` falls back to `String(err)` if the error carries no
+`.message`.
+
+A malformed CLI invocation (e.g. missing a required flag) is a **usage error**, not one of the
+JSON error shapes above: it writes a plain `Error: <message>` line to stderr and sets exit code 2
+directly, without going through `mapExecutorErrorToExitCode`.
+
+---
+
+## Platform qualification
+
+`execute()` checks `process.platform !== 'win32'` as its very first validation step — before any
+other argument validation, before deriving the execution root, before touching the plan
+snapshot, and before acquiring the ownership lease — and throws `PLATFORM_NOT_QUALIFIED` (exit
+7) on any non-Windows platform. This reflects FTR-018's Gate-1 binding constraint: the E-02
+process-supervision evidence (tree-kill via `taskkill`, tag-based liveness scanning via
+`Win32_Process` CIM queries) that the executor's crash-recovery/stop/worker-liveness machinery
+depends on is qualified for Windows only (US-08-TASK-BE-05). There is no implicit
+cross-platform guarantee — other platforms require their own dedicated qualification proof
+before `start` will run on them at all.

package/docs/workflow-control-plane.md

@@ -0,0 +1,95 @@
+# Deterministic workflow control plane
+
+The toolkit owns workflow execution in Node. An LLM is used only for document
+generation, review, and assessment. A workflow script is not a registered worker
+agent: never pass `pm-phase1`, `pm-phase2`, `pm-phase3`, `am-phase1`, or `am-phase2`
+to `agentType`, `subagent_type`, or Claude's `--agent`.
+
+## Invocation
+
+Reinstall the toolkit runtime assets after upgrading the package. The host rejects
+older installed workflows without `controlPlaneVersion: 1`, even if their old
+manifest hashes match. Use one installation scope (local or global); ambiguous or
+unverified agent installations fail closed.
+
+```text
+ai-toolkit workflow run pm-phase1 --project . --claude-path "C:\path\claude.exe" -- "internal_docs/features/FTR-123-example/feature.md"
+ai-toolkit workflow run pm-phase2 --project . --claude-path "C:\path\claude.exe" -- "internal_docs/features/FTR-123-example/feature.md"
+ai-toolkit workflow run am-phase1 --project . --claude-path "C:\path\claude.exe" -- . --scope=security,devops --prefix ASSESS-123
+ai-toolkit workflow run am-phase2 --project . -- --prefix ASSESS-123 --flagged INT-001 --ack "Reviewed by the user"
+```
+
+Resolve the actual Claude executable as described in `task-executor-bootstrap.md`.
+`--home DIR` is available for explicit installation-scope resolution. Paths are
+individual argv elements, never interpolated shell commands. Raw string arguments
+in the JavaScript API support quoted paths and preserve Windows backslashes.
+
+Exit 0 returns a JSON payload on stdout. A nonzero exit stops the pipeline; do not
+present the next approval gate. Gate 1/Gate 2 and Findings Gate decisions remain in
+the main loop. `am-phase2` requires explicit acknowledgement and a validated
+intervention selection; it does not invent approval.
+
+`pm-phase3` is a retired compatibility entry point and refuses execution. Since
+FTR-018, implementation belongs to `ai-toolkit tasks start/run`, with its task
+ownership, checkpoints, verification, review and resume protocol. The old workflow
+must not provide a fallback execution path. No JobScheduler feature is involved
+in this migration.
+
+## Audit and replacements
+
+| Original location | Deterministic operation formerly delegated to `agent()` | Replacement |
+|---|---|---|
+| pm-phase1 | agent resolution; self/worker ledger open/close | Verified host dispatch and owned activity lifecycle |
+| pm-phase1 | feature discovery, prefix, existence/mtime checks, ledger creation | Direct filesystem operations; freshness includes upstream documents; corrupt ledgers are preserved and rejected |
+| pm-phase1 | validation report existence/fabrication, process log writes | Require a nonempty fresh report from the validator; append log directly; structured validation verdict |
+| pm-phase2 | resolution and ledger operations | Same host lifecycle; unsuccessful results cannot close the owner as done |
+| pm-phase2 | validator/renderer execution, exit/output parsing and file checks | Toolkit CLI subprocess, `shell: false`, argv arrays, actual exit status, JSON parsing and disk reads |
+| pm-phase2 | raw pricing read, WB metrics, Token/Effort estimates, process log | Direct JSON reads and deterministic templates; unavailable usage/cost stays unavailable |
+| pm-phase3 | resolution, all ledger mutations, raw CSV/ledger/pricing reads, issue counts, test/git/PR commands, actuals writes | Legacy execution removed; implementation and CSV parsing already belong to the FTR-018 executor |
+| am-phase1 | discovery CLI, catalog/file reads, scope filtering, estimates/index counts | Canonical assessor map, verified resolution, strict scope filtering and deterministic Markdown parsing/templates |
+| am-phase2 | approval file, intervention selection, registry read/write/counts | Deterministic recorder with explicit input and readback |
+| FTR-018 process helper | worker identity cache and dispatch identity | Reject orchestrators; require requested canonical ID/native name agreement; cache by project + home + ID |
+
+Architecture, concurrency and quality have dedicated assessors. Security, DevOps,
+domain-model and dependencies use the generic assessor with explicit scope
+instructions. Multiple generic scopes are combined into one dispatch to avoid
+parallel writers overwriting the same report. Remediation agents are recommendations
+in intervention documents only; they are never used as assessors.
+
+## Identity, state and ownership
+
+Worker resolution checks the canonical catalog ID, verified status, exact native
+name, current definition hash, agent frontmatter name/model, and worker kind.
+Workflow resolution is separate and can never authorize worker dispatch.
+
+Every invocation has a unique owner and activity IDs. A per-prefix lock prevents
+two workflow runs from writing the same feature/assessment concurrently. The owner
+opens before work, drains parallel workers, validates outputs and serializes the
+result before its terminal transition. Worker usage and provenance are persisted.
+Legacy `open/close/fail/skip/finalizeActivity` calls cannot mutate owned entries;
+owned finalization requires the matching owner and a running entry. No name-only
+fallback is used for owned transitions. Later invocations cannot reopen an old run.
+
+The ownership token prevents accidental cross-finalization, not hostile filesystem
+access: workers and the host still run under the user's OS account. This is not a
+security sandbox.
+
+A caught failure produces `failed`. A hard OS/process kill can leave `running`,
+never a speculative `done`; workflow automatic resume/reconciliation is not added
+by this change. Retrying uses a new owner and preserves the interrupted record.
+If persistence itself fails, the error propagates rather than reporting success.
+
+## Verification and limits
+
+Regression tests execute the installed workflow source through the real host,
+resolver, filesystem and ledger. Integration tests invoke the actual structural
+validator/renderer and workflow CLI; LLM workers are deterministic test doubles.
+Coverage includes worker failure, missing outputs, corrupt ledger, late terminal
+calls, parallel rejection/drain, identity mismatch, cross-project cache leakage,
+negative semantic verdict, unknown scopes, paths with spaces and explicit approval.
+
+The live paid Claude model/permission flow has not been exercised by these tests.
+The subprocess adapter reuses FTR-018's existing qualification; no new cross-platform
+process-supervision guarantee is claimed. On Windows, the full executor test suite
+requires Git Bash ahead of the WSL launcher in PATH. User-level installations are
+not modified by running the isolated test fixtures.

package/lib/execution-ledger.js

@@ -33,7 +33,8 @@ function _readLedger(ledgerPath) {
     }
     throw parseErr;
   }
-  return { entries: Array.isArray(parsed) ? parsed : [] };
+  if (!Array.isArray(parsed)) throw new Error('Invalid ledger: expected JSON array');
+  return { entries: parsed };
 }
 
 function _writeLedger(ledgerPath, entries) {
@@ -340,6 +341,7 @@ function open(dir, prefix, agent, phase, model, attempt, metadata) {
     });
 
     if (existingIndex !== -1) {
+      _assertUnowned(entries[existingIndex]);
       // Idempotent re-open: check metadata conflict BEFORE writing anything.
       if (metadata != null) {
         if (!_metadataEqual(entries[existingIndex], metadata)) {
@@ -422,7 +424,8 @@ function close(dir, prefix, agent, tokens, attempt) {
       idx = agentIndexes[0];
     }
 
-    const existing     = entries[idx];
+    const existing = entries[idx];
+    _assertUnowned(existing);
     const completed_at = new Date().toISOString();
 
     // Token preservation (AC-10):
@@ -496,7 +499,8 @@ function fail(dir, prefix, agent, error, attempt) {
       idx = agentIndexes[0];
     }
 
-    const existing     = entries[idx];
+    const existing = entries[idx];
+    _assertUnowned(existing);
     const completed_at = new Date().toISOString();
 
     const update = {
@@ -572,7 +576,8 @@ function skip(dir, prefix, agent, phase, model, attempt) {
     }
 
     // Case 2: EXACTLY ONE match — update in place, preserving started_at and all other fields.
-    const existing     = entries[idx];
+    const existing = entries[idx];
+    _assertUnowned(existing);
     const completed_at = new Date().toISOString();
 
     entries[idx] = Object.assign({}, existing, {
@@ -589,11 +594,188 @@ function skip(dir, prefix, agent, phase, model, attempt) {
   }
 }
 
+// ── finalizeActivity (INFRA-TASK-BE-02) ──────────────────────────────────────
+//
+// Additive terminal-state API used by the executor. Unlike close()/fail()/skip(),
+// it requires an exact operation_id match (no name-only agent fallback), can
+// record tokens on ANY terminal status (including 'failed'), accepts an optional
+// usage_reason (additive ledger field, NOT an open() metadata whitelist key),
+// and is replay-safe: finalizing an already-terminal entry with identical data
+// is a no-op that returns the existing entry unchanged, while conflicting data
+// fails closed without writing. It does not introduce a second ledger file or
+// a duplicate token counter — it reuses phase_delta_tokens like close()/fail().
+
+const FINALIZE_STATUSES = new Set(['done', 'failed', 'skipped']);
+const TERMINAL_STATUSES = new Set(['done', 'failed', 'skipped']);
+
+function finalizeActivity(dir, prefix, agent, attempt, options) {
+  if (attempt == null) attempt = 1;
+  options = options || {};
+
+  const status        = options.status;
+  const tokens         = (options.tokens === undefined) ? null : options.tokens;
+  const reason         = options.reason;
+  const completedAtArg = options.completedAt;
+
+  if (!FINALIZE_STATUSES.has(status)) {
+    const err = new Error(
+      'finalizeActivity: status must be one of "done", "failed", "skipped"; got ' +
+      JSON.stringify(status)
+    );
+    err.code = 'INVALID_STATUS';
+    throw err;
+  }
+
+  const ledgerPath = path.join(dir, prefix + '-token-ledger.json');
+  const lockPath   = ledgerPath + '.lock';
+
+  const lockHandle = _acquireLock(lockPath);
+  try {
+    const { entries }  = _readLedger(ledgerPath);
+    const operation_id = computeOperationId(prefix, agent, attempt);
+
+    // Exact-ID lookup only — no name-only agent fallback (unlike close/fail/skip).
+    const idx = entries.findIndex(function (e) {
+      return e.operation_id === operation_id;
+    });
+
+    if (idx === -1) {
+      const err = new Error(
+        'finalizeActivity: no entry found for operation_id ' + operation_id +
+        ' in ' + ledgerPath + ' — exact operation_id match required, ' +
+        'no name-only fallback; operation was never opened'
+      );
+      err.code = 'ACTIVITY_NOT_FOUND';
+      err.operation_id = operation_id;
+      throw err;
+    }
+
+    const existing = entries[idx];
+    _assertUnowned(existing);
+
+    const suppliedTokens = (tokens === undefined) ? null : tokens;
+    const suppliedReason = (reason === undefined) ? null : reason;
+
+    if (TERMINAL_STATUSES.has(existing.status)) {
+      // Already finalized: this is either an idempotent replay of identical
+      // data (return unchanged, no write) or conflicting data (fail closed).
+      const existingTokens = (existing.phase_delta_tokens === undefined)
+        ? null : existing.phase_delta_tokens;
+      const existingReason = (existing.usage_reason === undefined)
+        ? null : existing.usage_reason;
+      const effectiveCompletedAt = (completedAtArg != null)
+        ? completedAtArg : existing.completed_at;
+
+      const isIdentical =
+        existing.status === status &&
+        existingTokens === suppliedTokens &&
+        existingReason === suppliedReason &&
+        existing.completed_at === effectiveCompletedAt;
+
+      if (isIdentical) {
+        return { status: 'ok', operation_id: operation_id, entry: existing, replay: true };
+      }
+
+      const err = new Error(
+        'finalizeActivity: conflicting terminal data for operation_id ' + operation_id +
+        ' in ' + ledgerPath + ' — existing terminal entry differs from the supplied ' +
+        'status/tokens/reason/completedAt; refusing to overwrite (fail-closed)'
+      );
+      err.code = 'TERMINAL_CONFLICT';
+      err.operation_id = operation_id;
+      throw err;
+    }
+
+    // Not yet terminal: finalize it. Tokens are recorded even when status is
+    // 'failed' — first finalization records known tokens, or null plus an
+    // optional usage_reason explaining why usage is unavailable. Matching the
+    // close() token-preservation invariant: a null/undefined supplied value
+    // never clobbers an already-stored positive phase_delta_tokens.
+    const completed_at = (completedAtArg != null) ? completedAtArg : new Date().toISOString();
+
+    let phase_delta_tokens = existing.phase_delta_tokens;
+    if (suppliedTokens !== null) {
+      phase_delta_tokens = suppliedTokens;
+    }
+
+    const update = {
+      status:             status,
+      completed_at:       completed_at,
+      phase_delta_tokens: phase_delta_tokens,
+    };
+    if (reason !== undefined) {
+      update.usage_reason = reason;
+    }
+
+    // Merge update: Object.assign preserves unknown/legacy fields and metadata verbatim.
+    entries[idx] = Object.assign({}, existing, update);
+
+    _writeLedger(ledgerPath, entries);
+
+    return { status: 'ok', operation_id: operation_id, entry: entries[idx] };
+  } finally {
+    _releaseLock(lockPath, lockHandle);
+  }
+}
+
+// Workflow-owned entries cannot be finalized by worker/legacy CLI calls.
+function _assertUnowned(entry) {
+  if (entry && entry.workflow_owner) {
+    const error = new Error('Workflow entry requires its owner capability');
+    error.code = 'LEDGER_OWNER_REQUIRED';
+    throw error;
+  }
+}
+
+function openOwned(dir, prefix, agent, phase, model, owner, metadata) {
+  if (typeof owner !== 'string' || !owner) throw new Error('Workflow owner required');
+  if (metadata) _validateMetadata(metadata);
+  const ledgerPath = path.join(dir, prefix + '-token-ledger.json');
+  const lockPath = ledgerPath + '.lock';
+  const handle = _acquireLock(lockPath);
+  try {
+    const { entries } = _readLedger(ledgerPath);
+    const operation_id = computeOperationId(prefix, agent, 1);
+    if (entries.some(e => e.operation_id === operation_id)) throw new Error('Owned operation already opened');
+    const entry = { operation_id, agent, phase, model, workflow_owner: owner,
+      status: 'running', started_at: new Date().toISOString(), completed_at: null, phase_delta_tokens: null };
+    if (metadata) Object.assign(entry, metadata);
+    entries.push(entry);
+    _writeLedger(ledgerPath, entries);
+    return entry;
+  } finally { _releaseLock(lockPath, handle); }
+}
+
+function finalizeOwned(dir, prefix, agent, owner, status, error, tokens) {
+  if (!['done', 'failed', 'skipped'].includes(status)) throw new Error('Invalid owned terminal status');
+  const ledgerPath = path.join(dir, prefix + '-token-ledger.json');
+  const lockPath = ledgerPath + '.lock';
+  const handle = _acquireLock(lockPath);
+  try {
+    const { entries } = _readLedger(ledgerPath);
+    const id = computeOperationId(prefix, agent, 1);
+    const entry = entries.find(e => e.operation_id === id);
+    if (!entry || !owner || entry.workflow_owner !== owner) throw new Error('Ledger ownership mismatch');
+    if (entry.status !== 'running') throw new Error('Owned terminal transition conflict');
+    if (tokens != null && (!Number.isInteger(tokens) || tokens <= 0)) throw new Error('Invalid owned token measurement');
+    if (tokens != null) entry.phase_delta_tokens = tokens;
+    entry.status = status;
+    entry.completed_at = new Date().toISOString();
+    if (error) entry.error = _sanitizeError(error);
+    _writeLedger(ledgerPath, entries);
+    return entry;
+  } finally { _releaseLock(lockPath, handle); }
+}
+
+
 module.exports = {
+  openOwned,
+  finalizeOwned,
   open,
   close,
   fail,
   skip,
+  finalizeActivity,
   computeOperationId,
   _readLedger,
   _writeLedger,