taskforce-loop-engineering 0.10.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## Unreleased
+
+## 0.13.0 - 2026-08-14
+
+- Add versioned OpenClaw, Hermes, and custom runtime adapter contracts with a shared conformance suite.
+- Add a checksummed, fsync-backed durable journal with replay, snapshots, migration, backup/restore, and fail-closed unknown-outcome handling.
+- Add deterministic multi-worker canary and isolated live-runtime soak tooling, a credential-free demo, and a non-destructive customized-Ironman upgrade planner.
+- Add unified production-trust acceptance and an idempotent acceptance refresh command so detached long-running evidence invalidates stale final judgements.
+
+## 0.12.0 - 2026-08-13
+
+- Add P3 read-only Operator Dashboard, normalized schema, loopback HTTP/JSON API, static export, inspect and health commands.
+- Integrate P0 gates, P1 reconciliation and P2 ownership/lease/handoff projections with legacy artifacts.
+- Add redaction, traversal/XSS/bind protections and deterministic/security/performance coverage.
+
+## 0.11.0 - 2026-08-13
+
+- Add Human-Gate Lifecycle v2 parked waits for human input and external conditions, configurable timeout/reminder/escalation policy, durable idempotent notification evidence, verified recovery signals, and exactly-once execution-boundary metadata.
+- Extend `queue-status` with operator-visible waiting states and add `queue-park`, `queue-wait-tick`, and `queue-wait-resume` commands.
+- Add a VPS-down/SSH-banner-timeout regression fixture proving throttled reminders, preserved unconsumed authorization, verified resume, and restart-safe idempotency.
+- Add the durable Action Idempotency and Reservation Contract with immutable request fingerprints, scoped authorization ledger, atomic leased claims and fencing tokens, settlement/release evidence, unknown-outcome reconciliation, paid-call/notification/deployment adapters, operator CLI commands, and backward-compatible artifact import.
+- Add concurrency and crash-restart acceptance coverage while preserving Human-Gate Lifecycle v2.
+- Add the P2 Multi-Agent Control Plane: typed todos, agent capability registration, deterministic atomic claim with lease/fencing, dependency and quota eligibility, durable handoff, orphan recovery, legacy import, ownership audit, CLI, schema, docs, and P0/P1 safety integration.
+
 ## 0.10.0 - 2026-08-11
 
 - Add OpenClaw installer language adaptation with `--language auto|en|zh`.

package/MIGRATING.md

@@ -1,4 +1,24 @@
-# Migrating to Taskforce Loop Engineering 0.7.0
+# Migrating to Taskforce Loop Engineering 0.12.0
+
+## Operator projection
+
+No runtime artifact migration is required. P3 reads P0/P1/P2 and legacy queue/project artifacts in place and emits projection schema `1.0.0`; existing writers remain authoritative. Consumers should use `schema_version`, tolerate additive fields, and treat degraded health as a refresh/investigation signal. `dashboard-serve` is loopback-only unless `--allow-non-loopback` is explicit.
+
+## Action reservation artifacts
+
+Existing queue, notification, and Human-Gate Lifecycle v2 artifacts remain
+valid. New side-effecting integrations should migrate their prior idempotency
+records through `migrateLegacyActionArtifact()` from
+`lib/action-reservations.mjs`. Import is idempotent: the legacy key, canonical
+request, action kind, and authorization scope become an immutable version 1
+reservation; importing the same artifact again is a no-op, while conflicting
+content fails closed. There is no eager workspace rewrite.
+
+The version 1 record schema includes `idempotency_key`, `kind`, `state`,
+`request_fingerprint`, immutable `request`, `fencing_counter`, `claim`,
+`authorization`, `settlement`, `release`, `reconciliation`, and `events`.
+Legacy send ledgers continue to suppress duplicates; adapters should adopt this
+contract before their next side-effecting execution boundary.
 
 ## Package rename
 
@@ -11,7 +31,7 @@ workspace scripts do not need to change.
 Upgrade the CLI normally, then run the package checks before changing an existing OpenClaw integration:
 
 ```bash
-npm install -g taskforce-loop-engineering@0.7.0
+npm install -g taskforce-loop-engineering@0.12.0
 loop-engineering-openclaw-manage --root /path/to/workspace --action upgrade-plan
 ```
 
@@ -58,3 +78,28 @@ After installation or upgrade, validate the integration:
 loop-engineering-openclaw-doctor --root /path/to/workspace --queue agent-tasks --worker-agent main
 loop-engineering-openclaw-smoke --root /path/to/workspace --queue agent-tasks --worker-agent main
 ```
+# Human-Gate Lifecycle v2
+
+Existing tasks with `status: "waiting_for_human"` remain supported and continue
+to appear in `waiting/`. New parked tasks add a versioned `parked` object while
+using the same directory, so no queue migration is required. Operators can
+adopt v2 incrementally:
+
+```bash
+loop-engineering queue-park --queue agent-tasks --task-id <id> \
+  --wait-kind external_condition --reason "VPS unavailable"
+loop-engineering queue-wait-tick --queue agent-tasks --notify-command '<sender>'
+loop-engineering queue-wait-resume --queue agent-tasks --task-id <id> \
+  --verified --recovery-signal 'probe=vps-1;ssh_banner=verified'
+```
+
+Timeout changes visibility and enables throttled escalation; it never rejects
+the task, consumes authorization, or retries a privileged action. Resume is
+fail-closed without a verified recovery signal. The original task id, wait id,
+authorization state, notification evidence, and execution-boundary key remain
+durable across restart.
+# P2 typed todo migration
+
+Run `loop-engineering todo-import-legacy --root <workspace>` to import existing `runtime/loops/*/{inbox,waiting,active}/*.json` artifacts. Import is additive and idempotent: stable ids use `legacy:<queue>:<task-id>`, source files are not modified, and waiting items retain their parked gate. Imported items receive explicit legacy acceptance/evidence defaults and can then be inspected or enriched before claim.
+
+New integrations should register agents with `agent-register`, create typed todos with `todo-create`, and use the claim fencing token for every renew, release, and handoff operation. Continue reconciling P1 `unknown` action outcomes before recovery or reassignment.

package/README.md

@@ -1,5 +1,72 @@
 # Taskforce Loop Engineering
 
+## 0.13 production trust
+
+The local production-trust contract, runtime adapter v1, durable journal,
+multi-worker canary, non-destructive Ironman upgrade planner, safe demo and
+unified acceptance are documented in
+[docs/production-trust-contract.md](docs/production-trust-contract.md). Run
+`npm run check:production-trust`; external publishing and deployment remain
+separately authorized actions.
+
+## Read-only operator dashboard (P3)
+
+Version 0.12 adds a dependency-free operator projection over projects, queues, P0 gates, P1 action reservations and P2 typed todo ownership. Use `dashboard-inspect`, `dashboard-health`, `dashboard-export`, or the loopback-only `dashboard-serve`. See [docs/operator-dashboard.md](docs/operator-dashboard.md) for API, security and schema details.
+
+The consolidated P0-P3 local release contract and evidence ledger are recorded in [docs/release-0.12-acceptance.md](docs/release-0.12-acceptance.md). Publishing, tagging, pushing, and production installation remain separate release actions.
+
+## Action idempotency and reservation
+
+Every side-effecting action must reserve a durable idempotency key before an
+adapter is invoked. The reservation binds a canonical request fingerprint to an
+authorization scope. A worker then atomically claims a lease and receives a
+monotonic fencing token; only that token can settle the action or release its
+reservation. Paid API, notification, and deployment adapters expose the same
+lifecycle from `lib/action-reservations.mjs`.
+
+```bash
+loop-engineering action-reserve --idempotency-key task:step:attempt \
+  --kind paid_api --authorization-scope approval:task:provider \
+  --request-json '{"model":"example","requestDigest":"sha256"}'
+loop-engineering action-claim --idempotency-key task:step:attempt \
+  --owner worker-1 --lease-ms 60000
+loop-engineering action-settle --idempotency-key task:step:attempt \
+  --fencing-token 1 --evidence upstream-request-id
+```
+
+An expired claim becomes `unknown`, not runnable. Operators must inspect and
+reconcile it as `accepted` (durably settle and consume authorization) or
+`not_accepted` (return to reserved) using `action-inspect` and
+`action-reconcile`. This is the crash boundary that prevents blind replay and
+double spend after an upstream acceptance whose local commit was interrupted.
+Terminal records retain settlement or release evidence and an append-only event
+history under `runtime/loops/action-reservations/`.
+
+## Human-Gate Lifecycle v2
+
+Park work without treating an external dependency as failure or repeatedly
+retrying a privileged action:
+
+```bash
+loop-engineering queue-park --queue agent-tasks --task-id <id> \
+  --wait-kind external_condition --reason "SSH banner timed out" \
+  --wait-timeout-ms 86400000 --reminder-interval-ms 3600000 \
+  --escalation-interval-ms 86400000 --max-reminders 3
+
+loop-engineering queue-wait-tick --queue agent-tasks \
+  --notify-command '<source-bound notifier>'
+
+loop-engineering queue-wait-resume --queue agent-tasks --task-id <id> \
+  --verified --recovery-signal 'probe=vps-1;ssh_banner=verified'
+```
+
+`queue-status --json` distinguishes `waiting_for_human`,
+`external_condition_wait`, `timed_out_or_escalated`, and `runnable` state.
+Reminder and escalation sends are throttled and leave durable evidence under
+`runtime/loops/<queue>/wait-notifications/`. Timeout never rejects a task,
+consumes a stored authorization, or repeats an action. Verified resume preserves
+the original task/wait identity and exactly-once execution boundary.
+
 Durable loop engineering for repeated agent work on OpenClaw and Hermes Agent. It provides a small
 Node CLI that executes JSON loop specs, records append-only run artifacts, and
 uses a circuit breaker to escalate repeated failures.
@@ -1270,3 +1337,6 @@ ClawHub:
 ```text
 https://clawhub.ai/ambitioncn/skills/taskforce-loop-engineering
 ```
+# P2 multi-agent control plane
+
+Loop Engineering includes typed executable todos with capability/authority-aware atomic claim, lease and fencing, deterministic dependency/quota scheduling, durable peer handoff, orphan recovery, and P0/P1 safety integration. See [docs/multi-agent-control-plane.md](docs/multi-agent-control-plane.md) for the data contract, CLI, and migration path.

package/bin/loop-engineering.mjs

@@ -37,7 +37,10 @@ import {
   mergeQueueOptions,
   nextState,
   notifyTerminalTasks,
+  refreshTaskAcceptance,
   notifyHumanInputRequests,
+  parkQueueTask,
+  resumeParkedTask,
   resolveHumanInput,
   enqueueTask,
   projectIntake,
@@ -56,6 +59,7 @@ import {
   queueSchedulerTick,
   queueSubdirFor,
   queueStatus,
+  tickParkedTasks,
   routeLoopMessage,
   summarizeLoopRuns,
   runCheck,
@@ -68,6 +72,34 @@ import {
   workflowTuningPlan,
   writeJson
 } from '../lib/core.mjs';
+import {
+  claimAction,
+  inspectAction,
+  reconcileAction,
+  releaseAction,
+  reserveAction,
+  settleAction
+} from '../lib/action-reservations.mjs';
+import {
+  claimTodo,
+  createTodo,
+  decideHandoff,
+  handoffTodo,
+  importLegacyTodos,
+  inspectTodo,
+  listTodos,
+  recoverTodos,
+  registerAgent,
+  releaseTodo,
+  renewTodo
+} from '../lib/todo-control-plane.mjs';
+import {
+  buildOperatorProjection,
+  createDashboardServer,
+  dashboardHealth,
+  exportDashboard,
+  filterProjection
+} from '../lib/operator-dashboard.mjs';
 
 function parseArgs(argv) {
   const args = { _: [], root: process.cwd(), json: false, force: false };
@@ -107,6 +139,13 @@ function parseArgs(argv) {
       args.checks.push(argv[++i]);
     }
     else if (a === '--task-id') args.taskId = argv[++i];
+    else if (a === '--todo-id') args.todoId = argv[++i];
+    else if (a === '--agent-id') args.agentId = argv[++i];
+    else if (a === '--target-agent-id') args.targetAgentId = argv[++i];
+    else if (a === '--handoff-id') args.handoffId = argv[++i];
+    else if (a === '--todo-json') args.todoJson = argv[++i];
+    else if (a === '--agent-json') args.agentJson = argv[++i];
+    else if (a === '--state') args.todoState = argv[++i];
     else if (a === '--run-id') args.runId = argv[++i];
     else if (a === '--output') args.output = argv[++i];
     else if (a === '--output-dir') {
@@ -147,10 +186,31 @@ function parseArgs(argv) {
     else if (a === '--stale-after') args.staleAfter = argv[++i];
     else if (a === '--until') args.until = argv[++i];
     else if (a === '--reason') args.reason = argv[++i];
+    else if (a === '--wait-kind') args.waitKind = argv[++i];
+    else if (a === '--wait-id') args.waitId = argv[++i];
+    else if (a === '--execution-key') args.executionKey = argv[++i];
+    else if (a === '--idempotency-key') args.idempotencyKey = argv[++i];
+    else if (a === '--kind') args.kind = argv[++i];
+    else if (a === '--authorization-scope') args.authorizationScope = argv[++i];
+    else if (a === '--request-json') args.requestJson = argv[++i];
+    else if (a === '--fencing-token') args.fencingToken = Number.parseInt(argv[++i], 10);
+    else if (a === '--completed') args.completed = true;
+    else if (a === '--outcome') args.outcome = argv[++i];
+    else if (a === '--evidence') args.evidence = argv[++i];
+    else if (a === '--recovery-signal') args.recoverySignal = argv[++i];
+    else if (a === '--now') args.now = argv[++i];
+    else if (a === '--reminder-interval-ms') args.reminderIntervalMs = Number.parseInt(argv[++i], 10);
+    else if (a === '--escalation-interval-ms') args.escalationIntervalMs = Number.parseInt(argv[++i], 10);
+    else if (a === '--wait-timeout-ms') args.waitTimeoutMs = Number.parseInt(argv[++i], 10);
+    else if (a === '--max-reminders') args.maxReminders = Number.parseInt(argv[++i], 10);
     else if (a === '--decision') args.decision = argv[++i];
     else if (a === '--comment') args.comment = argv[++i];
     else if (a === '--reviewer') args.reviewer = argv[++i];
     else if (a === '--limit') args.limit = Number.parseInt(argv[++i], 10);
+    else if (a === '--host') args.host = argv[++i];
+    else if (a === '--port') args.port = Number.parseInt(argv[++i], 10);
+    else if (a === '--query') args.query = argv[++i];
+    else if (a === '--max-age-seconds') args.maxAgeSeconds = Number.parseInt(argv[++i], 10);
     else if (a === '--notify-command') args.notifyCommand = argv[++i];
     else if (a === '--gate-id') args.gateId = argv[++i];
     else if (a === '--input') args.input = argv[++i];
@@ -185,8 +245,10 @@ function parseArgs(argv) {
     else if (a === '--supersede-active') args.supersedeActive = true;
     else if (a === '--amend-active') args.amendActive = true;
     else if (a === '--dry-run') args.dryRun = true;
+    else if (a === '--verified') args.verified = true;
     else if (a === '--allow-dirty') args.allowDirty = true;
     else if (a === '--include-orphans') args.includeOrphans = true;
+    else if (a === '--allow-non-loopback') args.allowNonLoopback = true;
     else if (a === '--json') args.json = true;
     else if (a === '--force') args.force = true;
     else if (a === '--help' || a === '-h') args.help = true;
@@ -1552,6 +1614,10 @@ Usage:
   loop-engineering status [--config configs/loops/name.json] [--root <workspace>]
   loop-engineering summarize [--id name | --queue name] [--limit 20] [--root <workspace>] [--json]
   loop-engineering doctor [--root <workspace>] [--json]
+  loop-engineering dashboard-inspect [--id todo-id] [--state state] [--query text] [--root <workspace>] [--json]
+  loop-engineering dashboard-health [--max-age-seconds 3600] [--root <workspace>] [--json]
+  loop-engineering dashboard-export --output-dir directory [--root <workspace>] [--json]
+  loop-engineering dashboard-serve [--host 127.0.0.1] [--port 0] [--allow-non-loopback] [--root <workspace>]
   loop-engineering repair-plan --id name [--output repair-plan.json] [--root <workspace>] [--json] [--force]
   loop-engineering project-intake --name project --brief "Project brief" [--type auto|web_app|code_project|research|content|ops|qa|knowledge_base|infra_audit|assistant_workflow] [--queue name] [--check "npm test"] [--root <workspace>] [--json]
   loop-engineering project-plan --project project [--root <workspace>] [--json] [--force]
@@ -1562,7 +1628,17 @@ Usage:
   loop-engineering run-queue --queue name --dispatcher "command" [--preflight-config configs/loops/name.json] [--root <workspace>]
   loop-engineering run-queue-drain --config configs/loops/queues/name.json [--max-tasks 100] [--root <workspace>]
   loop-engineering queue-status --queue name [--root <workspace>] [--json]
+  loop-engineering queue-park --queue name --task-id id --wait-kind human_input|external_condition --reason "..." [--wait-timeout-ms N --reminder-interval-ms N --escalation-interval-ms N --max-reminders N] [--root <workspace>] [--json]
+  loop-engineering action-reserve --idempotency-key key --kind paid_api|notification|deployment|process_control|publication|external_message|gated_mutation --authorization-scope scope --request-json '{}' [--root <workspace>]
+  loop-engineering action-claim --idempotency-key key --owner worker [--lease-ms N] [--root <workspace>]
+  loop-engineering action-inspect --idempotency-key key [--root <workspace>]
+  loop-engineering action-settle --idempotency-key key --fencing-token N [--evidence text] [--root <workspace>]
+  loop-engineering action-release --idempotency-key key [--fencing-token N] --reason text [--evidence text] [--root <workspace>]
+  loop-engineering action-reconcile --idempotency-key key --outcome accepted|not_accepted --evidence text [--root <workspace>]
+  loop-engineering queue-wait-tick --queue name (--notify-command "command" | --dry-run) [--now ISO] [--root <workspace>] [--json]
+  loop-engineering queue-wait-resume --queue name --task-id id --verified --recovery-signal "..." [--root <workspace>] [--json]
   loop-engineering queue-terminal-notify --queue name (--notify-command "command" | --dry-run) [--root <workspace>] [--json]
+  loop-engineering queue-acceptance-refresh --queue name --task-id id [--root <workspace>] [--json]
   loop-engineering queue-scheduler-tick --queue name [--config configs/loops/queues/name.json] [--plan-only] [--force-due] [--initial-interval 10m] [--min-interval 1m] [--max-interval 4h] [--jitter 30s] [--no-progress-report] [--progress-report-interval 30m] [--progress-notify-command "command"] [--root <workspace>] [--json]
   loop-engineering queue-init --queue name [--root <workspace>] [--force]
   loop-engineering code-queue-init --queue name [--root <workspace>] [--force]
@@ -1996,6 +2072,14 @@ async function queueTerminalNotifyCommand(args) {
   return result.failed > 0 ? 1 : 0;
 }
 
+async function queueAcceptanceRefreshCommand(args) {
+  if (!args.queue || !args.taskId) throw new Error('queue-acceptance-refresh requires --queue and --task-id.');
+  const result = await refreshTaskAcceptance(args.root, args);
+  if (args.json) console.log(JSON.stringify(result, null, 2));
+  else console.log(`${result.queue}: ${result.taskId} ${result.outcome}${result.status ? ` (${result.status})` : ''}`);
+  return 0;
+}
+
 async function queueHumanInputNotifyCommand(args) {
   if (!args.queue) throw new Error('queue-human-input-notify requires --queue.');
   const result = await notifyHumanInputRequests(args.root, args);
@@ -2012,6 +2096,34 @@ async function queueHumanInputResolveCommand(args) {
   return 0;
 }
 
+async function queueParkCommand(args) {
+  if (!args.queue || !args.taskId) throw new Error('queue-park requires --queue and --task-id.');
+  const result = await parkQueueTask(args.root, {
+    ...args,
+    kind: args.waitKind,
+    policy: { timeoutMs: args.waitTimeoutMs, reminderIntervalMs: args.reminderIntervalMs, escalationIntervalMs: args.escalationIntervalMs, maxReminders: args.maxReminders }
+  });
+  if (args.json) console.log(JSON.stringify(result, null, 2));
+  else console.log(`${args.taskId}: ${result.outcome}`);
+  return 0;
+}
+
+async function queueWaitTickCommand(args) {
+  if (!args.queue) throw new Error('queue-wait-tick requires --queue.');
+  const result = await tickParkedTasks(args.root, args);
+  if (args.json) console.log(JSON.stringify(result, null, 2));
+  else console.log(`${result.queue}: inspected=${result.inspected} sent=${result.sent} failed=${result.failed}`);
+  return result.failed > 0 ? 1 : 0;
+}
+
+async function queueWaitResumeCommand(args) {
+  if (!args.queue || !args.taskId) throw new Error('queue-wait-resume requires --queue and --task-id.');
+  const result = await resumeParkedTask(args.root, args);
+  if (args.json) console.log(JSON.stringify(result, null, 2));
+  else console.log(`${args.taskId}: ${result.outcome}`);
+  return 0;
+}
+
 async function queueSchedulerTickCommand(args) {
   const inferredConfig = args.queue ? `configs/loops/queues/${args.queue}.json` : undefined;
   const inferredConfigExists = inferredConfig
@@ -5501,6 +5613,9 @@ async function main() {
   if (command === 'status') return statusCommand(args);
   if (command === 'summarize') return summarizeCommand(args);
   if (command === 'doctor') return doctorCommand(args);
+  if (command.startsWith('dashboard-')) return dashboardCommand(command, args);
+  if (command === 'agent-register' || command.startsWith('todo-')) return todoControlPlaneCommand(command, args);
+  if (command.startsWith('action-')) return actionReservationCommand(command, args);
   if (command === 'repair-plan') return repairPlanCommand(args);
   if (command === 'project-intake') return projectIntakeCommand(args);
   if (command === 'project-plan') return projectPlanCommand(args);
@@ -5510,7 +5625,11 @@ async function main() {
   if (command === 'run-queue') return runQueueCommand(args);
   if (command === 'run-queue-drain') return runQueueDrainCommand(args);
   if (command === 'queue-status') return queueStatusCommand(args);
+  if (command === 'queue-park') return queueParkCommand(args);
+  if (command === 'queue-wait-tick') return queueWaitTickCommand(args);
+  if (command === 'queue-wait-resume') return queueWaitResumeCommand(args);
   if (command === 'queue-terminal-notify') return queueTerminalNotifyCommand(args);
+  if (command === 'queue-acceptance-refresh') return queueAcceptanceRefreshCommand(args);
   if (command === 'queue-human-input-notify') return queueHumanInputNotifyCommand(args);
   if (command === 'queue-human-input-resolve') return queueHumanInputResolveCommand(args);
   if (command === 'queue-scheduler-tick') return queueSchedulerTickCommand(args);
@@ -5561,6 +5680,79 @@ async function main() {
   throw new Error(`Unknown command: ${command}`);
 }
 
+async function dashboardCommand(command, args) {
+  if (command === 'dashboard-serve') {
+    const server = await createDashboardServer(args.root, { host: args.host, port: args.port, allowNonLoopback: args.allowNonLoopback });
+    const address = server.address();
+    console.log(JSON.stringify({ status: 'serving', read_only: true, address }, null, 2));
+    return new Promise((resolve) => {
+      const stop = () => server.close(() => resolve(0));
+      process.once('SIGINT', stop); process.once('SIGTERM', stop);
+    });
+  }
+  if (command === 'dashboard-export') {
+    if (!args.outputDir || args.outputDir === true) throw new Error('dashboard-export requires --output-dir.');
+    console.log(JSON.stringify(await exportDashboard(args.root, args.outputDir, { now: args.now }), null, 2));
+    return 0;
+  }
+  const projection = await buildOperatorProjection(args.root, { now: args.now });
+  if (command === 'dashboard-health') {
+    const result = dashboardHealth(projection, { maxAgeSeconds: args.maxAgeSeconds });
+    console.log(JSON.stringify(result, null, 2)); return result.status === 'ok' ? 0 : 2;
+  }
+  if (command === 'dashboard-inspect') {
+    const filtered = filterProjection(projection, { query: args.query, state: args.todoState });
+    const result = args.id ? filtered.todos.find((item) => item.id === args.id) ?? filtered.queues.flatMap((queue) => queue.tasks).find((item) => item.id === args.id) ?? null : filtered;
+    console.log(JSON.stringify(result, null, 2)); return result === null ? 1 : 0;
+  }
+  throw new Error(`Unknown command: ${command}`);
+}
+
+async function jsonInput(raw, label) {
+  if (!raw) throw new Error(`${label} is required.`);
+  if (raw.trim().startsWith('{')) return JSON.parse(raw);
+  return JSON.parse(await readFile(path.resolve(raw), 'utf8'));
+}
+
+async function todoControlPlaneCommand(command, args) {
+  let result;
+  if (command === 'agent-register') result = await registerAgent(args.root, await jsonInput(args.agentJson, '--agent-json'));
+  else if (command === 'todo-create') result = await createTodo(args.root, await jsonInput(args.todoJson, '--todo-json'));
+  else if (command === 'todo-list') result = await listTodos(args.root, { state: args.todoState });
+  else if (command === 'todo-inspect') result = await inspectTodo(args.root, args.todoId);
+  else if (command === 'todo-claim') result = await claimTodo(args.root, args);
+  else if (command === 'todo-renew') result = await renewTodo(args.root, args);
+  else if (command === 'todo-release') result = await releaseTodo(args.root, args);
+  else if (command === 'todo-handoff') result = await handoffTodo(args.root, args);
+  else if (command === 'todo-accept') result = await decideHandoff(args.root, { ...args, accept: true });
+  else if (command === 'todo-reject') result = await decideHandoff(args.root, { ...args, accept: false });
+  else if (command === 'todo-recover') result = await recoverTodos(args.root, args);
+  else if (command === 'todo-import-legacy') result = await importLegacyTodos(args.root, args);
+  else throw new Error(`Unknown command: ${command}`);
+  console.log(JSON.stringify(result, null, 2));
+  return result === null ? 1 : 0;
+}
+
+async function actionReservationCommand(command, args) {
+  if (!args.idempotencyKey) throw new Error(`${command} requires --idempotency-key.`);
+  let result;
+  if (command === 'action-reserve') {
+    result = await reserveAction(args.root, {
+      idempotencyKey: args.idempotencyKey,
+      kind: args.kind,
+      authorizationScope: args.authorizationScope,
+      request: JSON.parse(args.requestJson ?? '{}')
+    });
+  } else if (command === 'action-inspect') result = await inspectAction(args.root, args.idempotencyKey);
+  else if (command === 'action-claim') result = await claimAction(args.root, { idempotencyKey: args.idempotencyKey, owner: args.owner, leaseMs: args.leaseMs });
+  else if (command === 'action-settle') result = await settleAction(args.root, { idempotencyKey: args.idempotencyKey, fencingToken: args.fencingToken, evidence: args.evidence });
+  else if (command === 'action-release') result = await releaseAction(args.root, { idempotencyKey: args.idempotencyKey, fencingToken: args.fencingToken, reason: args.reason, evidence: args.evidence });
+  else if (command === 'action-reconcile') result = await reconcileAction(args.root, { idempotencyKey: args.idempotencyKey, outcome: args.outcome, evidence: args.evidence });
+  else throw new Error(`Unknown command: ${command}`);
+  console.log(JSON.stringify(result, null, 2));
+  return result === null ? 1 : 0;
+}
+
 main()
   .then((code) => { process.exitCode = code; })
   .catch((err) => {