taskforce-loop-engineering 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.14.0 - 2026-08-14
+
+- Add the platform-neutral runtime adapter SDK v1 with OpenClaw, Hermes, Codex CLI, and Claude Code factories, shared conformance tests, fail-closed effects, redacted telemetry, migration guidance, and a credential-free demo.
+
+## 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.

package/README.md

@@ -1,5 +1,28 @@
 # Taskforce Loop Engineering
 
+[![production trust](https://github.com/ambitioncn/taskforce-loop-engineering/actions/workflows/production-trust.yml/badge.svg)](https://github.com/ambitioncn/taskforce-loop-engineering/actions/workflows/production-trust.yml)
+
+## Platform-neutral adapter SDK
+
+OpenClaw, Hermes, Codex CLI, and Claude Code share the versioned runtime
+contract in `lib/runtime-adapter-sdk.mjs`. Start without credentials or network
+access with `npm run demo:adapter`, then verify every runtime using
+`npm run check:adapters`. See [docs/runtime-adapter-sdk.md](docs/runtime-adapter-sdk.md)
+for the contract, compatibility matrix, migration, and extension guide.
+
+## 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. The command writes integrity-sealed evidence and
+a redacted public summary to `.production-evidence/`. The default canary is
+offline and fixture-only: it performs no model call or external side effect.
+Copy `templates/github-production-trust.yml` into `.github/workflows/` only
+when publication is separately approved.
+
 ## 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.

package/bin/loop-engineering.mjs

@@ -37,6 +37,7 @@ import {
   mergeQueueOptions,
   nextState,
   notifyTerminalTasks,
+  refreshTaskAcceptance,
   notifyHumanInputRequests,
   parkQueueTask,
   resumeParkedTask,
@@ -1637,6 +1638,7 @@ Usage:
   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]
@@ -2070,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);
@@ -5619,6 +5629,7 @@ async function main() {
   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);

package/docs/adapter-sdk-terminal-contract.json

@@ -0,0 +1,19 @@
+{
+  "version": 1,
+  "project": "P2 platform-neutral runtime adapter SDK",
+  "terminal_acceptance": [
+    "versioned platform-neutral contract",
+    "OpenClaw Hermes Codex CLI and Claude Code reproducible paths",
+    "unified capability session run step effect gate continuation telemetry and errors",
+    "compatibility matrix conformance migration and extension docs",
+    "credential-free demo and read-only dashboard path",
+    "redaction fail-closed 0.13 P0 P1 regression package and clean-install evidence"
+  ],
+  "backlog": [
+    {"id":"P2-1","status":"done","evidence":"lib/runtime-adapter-sdk.mjs"},
+    {"id":"P2-2","status":"done","evidence":"scripts/runtime-adapter-conformance.mjs"},
+    {"id":"P2-3","status":"done","evidence":"docs/runtime-adapter-sdk.md"},
+    {"id":"P2-4","status":"done","evidence":"examples/adapter-sdk-demo.mjs"},
+    {"id":"P2-5","status":"done","evidence":"npm run check; npm pack --pack-destination; clean npm install and packaged conformance"}
+  ]
+}

package/docs/production-operations.md

@@ -0,0 +1,29 @@
+# Production Trust Operations
+
+Run `npm run check:production-trust` before release review. The safe demo is
+`node examples/safe-canary.mjs`; it uses an in-memory I/O boundary, contains no
+credential, makes no paid call, and performs no external write. The soak command
+writes a local audit report when passed `--output <file>`.
+
+Back up both `events.jsonl` and `snapshot.json` before migration or upgrade.
+Restore into a new directory, replay it, compare event count/checksum and only
+then switch the configured path. Never truncate a checksum error; a malformed
+final partial line may be ignored as a torn write, while corruption elsewhere
+fails closed. Reconcile every `unknown` external outcome against the upstream
+provider before permitting a retry.
+
+Upgrade plans are read-only. A customized dispatcher/config receives
+`preserve_customized`, which is not apply-ready. Review a byte-exact backup and
+merge plan; do not use force overwrite. Publishing, real canary traffic,
+production deployment, credentials, process control and paid services require
+separate operator authorization.
+
+Support boundaries are listed in `production-trust-contract.md`. In particular,
+the custom adapter is an example/contract surface, not an operated runtime, and
+the local journal is not a distributed consensus database.
+
+When detached verification finishes after a task was judged, first write a
+successor checkpoint that revises the blocked checkpoint, then run
+`loop-engineering queue-acceptance-refresh --queue <queue> --task-id <task>`.
+The refresh runs only when a checkpoint is newer than the final judgement;
+repeated calls return `already_current` and do not re-run acceptance.

package/docs/production-trust-backlog.json

@@ -0,0 +1,18 @@
+{
+  "version": 3,
+  "project": "p1-production-trust-evidence",
+  "terminal_contract": "production-trust-contract.md",
+  "milestone_completion_is_project_completion": false,
+  "items": [
+    {"id":"P1-1","outcome":"schema-versioned evidence, public summary, integrity and redaction","evidence":["lib/production-evidence.mjs","templates/production-evidence.schema.json","scripts/production-evidence-self-test.mjs"],"required":true},
+    {"id":"P1-2","outcome":"ledger-backed multi-agent soak and kill/restart chaos","evidence":["scripts/production-soak.mjs","lib/execution-ledger.mjs"],"required":true},
+    {"id":"P1-3","outcome":"claim lease handoff parked gate and stale-fence rejection","evidence":["scripts/production-soak.mjs",".production-evidence/evidence.json"],"required":true},
+    {"id":"P1-4","outcome":"unknown outcome crash boundaries and accepted-before-settle reconciliation","evidence":["scripts/production-soak.mjs","lib/execution-ledger.mjs"],"required":true},
+    {"id":"P1-5","outcome":"step replay resume divergence and zero duplicate effects","evidence":["scripts/production-soak.mjs","scripts/execution-ledger-self-test.mjs"],"required":true},
+    {"id":"P1-6","outcome":"baseline trend threshold attribution recovery cost and error metrics","evidence":["lib/production-evidence.mjs","scripts/production-evidence-self-test.mjs"],"required":true},
+    {"id":"P1-7","outcome":"OpenClaw Hermes and custom adapter compatibility matrix","evidence":["lib/runtime-adapter-v1.mjs","scripts/production-soak.mjs"],"required":true},
+    {"id":"P1-8","outcome":"GitHub CI candidate badge doctor and dashboard projection","evidence":["templates/github-production-trust.yml","README.md","lib/core.mjs","lib/operator-dashboard.mjs"],"required":true},
+    {"id":"P1-9","outcome":"offline determinism privacy and tamper negative tests","evidence":["scripts/production-evidence-self-test.mjs","scripts/production-soak.mjs"],"required":true},
+    {"id":"P1-10","outcome":"full regression package content and clean-install acceptance","evidence":["package.json","scripts/production-acceptance.mjs"],"required":true}
+  ]
+}

package/docs/production-trust-contract.md

@@ -0,0 +1,53 @@
+# P1 Production-Trust Evidence Terminal Contract
+
+Status: local release candidate. Project completion requires every required P1
+backlog item to have repeatable evidence; a scenario or milestone alone is not
+project completion. Push, publication, deployment, production credentials,
+real paid calls, production process control, and external effects are excluded.
+
+## Terminal outcome
+
+P1 turns the P0 schema-v2 execution ledger and effect protocol into a sustainable
+production-trust evidence system. CI/canary runs emit schema-versioned,
+integrity-sealed evidence plus a secret-redacted public summary. Baselines,
+trends, explicit thresholds, failure attribution, runtime compatibility, cost,
+error rate, and recovery time remain independently reviewable.
+
+## Required acceptance
+
+1. The deterministic multi-agent canary exercises long soak, exclusive claim,
+   lease expiry, kill/restart handoff, stale fencing, parked gate, crash before
+   and after submit, accepted-before-local-settle, reconciliation, checkpoint
+   resume, reusable replay, and replay divergence through the P0 ledger/effect
+   protocol. It does not maintain a second execution state store.
+2. Duplicate settled effects and accepted stale fences are exactly zero;
+   unreconciled unknown outcomes are zero at terminal acceptance. Recovery time,
+   error rate, model calls, and paid-call cost meet recorded thresholds.
+3. OpenClaw, Hermes, and custom runtime-adapter fixtures pass contract v1 using
+   simulated I/O. The boundary is explicit: fixtures prove adapter compatibility,
+   not availability of a real gateway or provider.
+4. Evidence schema v1 supports baselines and metric deltas, threshold failures
+   with attribution, SHA-256 tamper detection, credential-shaped field redaction,
+   and a minimized public summary. Offline reruns require no network or secret.
+5. GitHub CI template/artifact upload and badge markup are release candidates;
+   no workflow is published in this local task. Doctor and dashboard project the
+   latest evidence state without mutating it.
+6. Full regression, package dry-run, package content inspection, and clean local
+   install pass. The packaged candidate includes schema, CI template, library,
+   canary, tests, docs, and backlog.
+
+## Real/simulated boundary and deferred canary
+
+`production-soak.mjs` is the authoritative offline CI canary. The separate
+`live-runtime-soak.mjs` may perform runtime probes and is not invoked by release
+acceptance. A real long-duration OpenClaw/Hermes run, production credentials,
+paid inference, or external side effect needs a separate human authorization and
+must produce a successor evidence artifact clearly labeled `real_runtime`.
+
+## Trust limits
+
+SHA-256 detects later artifact changes but is not an external timestamp or
+signature. Local filesystem leases provide single-host coordination, not
+distributed consensus or Byzantine-worker protection. Exactly-once effects still
+depend on an upstream idempotency/reconciliation API. Unknown outcomes lacking
+authoritative evidence fail closed and remain reconciliation debt.

package/docs/runtime-adapter-sdk.md

@@ -0,0 +1,50 @@
+# Runtime Adapter SDK v1
+
+`lib/runtime-adapter-sdk.mjs` is the platform-neutral contract. Contract id is
+`loop.runtime-adapter`, semantic version `1.0.0`; consumers must reject unknown
+major versions. The SDK normalizes capabilities, session/run identity, step
+ledger events, authorized effects, human gates, heartbeat/continuation,
+redacted evidence/telemetry, and stable `AdapterError` codes.
+
+## Ten-minute, credential-free path
+
+From this package, run `npm run demo:adapter`, `npm run check:adapters`, then
+`npm run check`. All four paths use the same in-memory transport and make no
+network calls. The existing dashboard remains a read-only projection; the demo
+prints the command for opening it against a local workspace.
+
+## Runtime paths
+
+| Runtime | Factory | Integration transport |
+| --- | --- | --- |
+| OpenClaw | `createOpenClawAdapter` | map invoke to trusted session/task tools |
+| Hermes | `createHermesAdapter` | map invoke to Hermes run lifecycle |
+| Codex CLI | `createCodexCliAdapter` | map invoke to local Codex exec/resume |
+| Claude Code | `createClaudeCodeAdapter` | map invoke to local Claude session/resume |
+
+Each transport implements `invoke(operation, payload)`. Operations are
+`run.start`, `run.heartbeat`, and `run.continue`. Side effects never pass through
+that generic transport: call `prepareEffect` first, persist its idempotency key
+in the P0/P1 ledger, obtain explicit authorization, then submit through the
+product-specific effect adapter. Missing authorization fails closed.
+
+## Compatibility and migration
+
+| Surface | Status |
+| --- | --- |
+| package 0.13 / P0 / P1 ledgers | compatible; unchanged |
+| `runtime-adapter-v1.mjs` OpenClaw/Hermes/custom fixtures | retained |
+| SDK v1 four-runtime contract | additive and preferred |
+| future SDK major | rejected until explicitly supported |
+
+Migrate by replacing fixture imports with a `create*Adapter(transport)` factory,
+creating a session then run, recording every step, and routing effects through
+`prepareEffect`. Convert caught errors using `AdapterError.toJSON()`; never log
+raw credentials. To extend, add a runtime to `RUNTIMES`, a thin factory, and run
+the exported conformance function with an offline transport before connecting a
+real runtime.
+
+Error codes are `INVALID_INPUT`, `UNSUPPORTED_CONTRACT`,
+`UNSUPPORTED_VERSION`, `UNSUPPORTED_RUNTIME`, `INVALID_ADAPTER`,
+`INVALID_STEP_STATE`, `EFFECT_KEY_REQUIRED`, `EFFECT_NOT_AUTHORIZED`,
+`INVALID_GATE_DECISION`, and retryable `TRANSPORT_FAILURE`.

package/examples/adapter-sdk-demo.mjs

@@ -0,0 +1,9 @@
+import { createMemoryTransport, createOpenClawAdapter } from '../lib/runtime-adapter-sdk.mjs';
+
+const adapter = createOpenClawAdapter(createMemoryTransport());
+const session = await adapter.createSession({ key: 'ten-minute-demo' });
+const run = await adapter.startRun({ sessionId: session.sessionId, requestId: 'demo', input: { prompt: 'credential-free' } });
+await adapter.recordStep({ runId: run.runId, stepId: 'hello', evidence: [{ kind: 'local-demo' }] });
+const heartbeat = await adapter.heartbeat({ runId: run.runId });
+await adapter.continueRun({ runId: run.runId, continuationToken: heartbeat.continuationToken });
+console.log(JSON.stringify({ session, run, heartbeat, dashboard: 'run `loop-engineering dashboard --root .` for the existing read-only projection', telemetry: adapter.telemetry }, null, 2));

package/examples/code-worktree-queue.json

@@ -0,0 +1,35 @@
+{
+  "queue": "code-tasks",
+  "description": "L2 assisted code task queue. Each task runs in an isolated git worktree and records verification plus diff summaries. It never pushes, merges, or deletes worktrees.",
+  "dispatcher": "node scripts/dispatch-code-task.mjs",
+  "preflightConfig": "configs/loops/workspace-health.json",
+  "timeoutMs": 1800000,
+  "leaseMs": 1860000,
+  "staleActiveMs": 3600000,
+  "retry": {
+    "maxAttempts": 1,
+    "retryDelayMs": 0,
+    "retryExitCodes": [
+      1
+    ],
+    "requiresHumanActionPatterns": [
+      "INSTALL_FAILED_USER_RESTRICTED",
+      "device unauthorized",
+      "no devices/emulators found",
+      "Permission denied",
+      "Operation not permitted",
+      "requires human",
+      "需要人工",
+      "权限未开"
+    ]
+  },
+  "worktree": {
+    "enabled": true,
+    "baseDir": "runtime/loops/code-tasks/worktrees",
+    "branchPrefix": "loop/code-tasks",
+    "verifyCommands": [
+      "npm test"
+    ],
+    "keepOnSuccess": true
+  }
+}

package/examples/queue-runner.json

@@ -0,0 +1,37 @@
+{
+  "queue": "agent-tasks",
+  "description": "Generic queue runner config. Keep dispatcher local to the target workspace.",
+  "dispatcher": "node scripts/dispatch-task.mjs",
+  "preflightConfig": "configs/loops/workspace-health.json",
+  "timeoutMs": 1800000,
+  "leaseMs": 1860000,
+  "staleActiveMs": 3600000,
+  "scheduler": {
+    "initialInterval": "10m",
+    "minInterval": "1m",
+    "maxInterval": "4h",
+    "speedupFactor": 0.5,
+    "backoffFactor": 2,
+    "idleBackoffFactor": 2,
+    "humanGateBackoffFactor": 3,
+    "longRunHeadroomFactor": 1.25,
+    "jitter": "30s"
+  },
+  "retry": {
+    "maxAttempts": 1,
+    "retryDelayMs": 0,
+    "retryExitCodes": [
+      1
+    ],
+    "requiresHumanActionPatterns": [
+      "INSTALL_FAILED_USER_RESTRICTED",
+      "device unauthorized",
+      "no devices/emulators found",
+      "Permission denied",
+      "Operation not permitted",
+      "requires human",
+      "需要人工",
+      "权限未开"
+    ]
+  }
+}

package/examples/safe-canary.mjs

@@ -0,0 +1,5 @@
+import { customAdapterExample } from '../lib/runtime-adapter-v1.mjs';
+const audit = [];
+const io = { invoke: async (binary, args) => (audit.push({ binary, args, externalWrite: false, paid: false }), { accepted: true }), now: () => new Date().toISOString(), lookup: async () => ({ status: 'not_accepted' }) };
+await customAdapterExample.dispatch({ prompt: 'credential-free local canary', worker: 'demo' }, io);
+console.log(JSON.stringify({ support: 'example-contract-only', credentialsUsed: false, externalWrites: false, paidCalls: false, audit }, null, 2));

package/examples/workspace-health.json

@@ -0,0 +1,35 @@
+{
+  "id": "workspace-health",
+  "goal": "Keep this workspace loop-ready and detect obvious drift.",
+  "level": "L1",
+  "mode": "report-only",
+  "maxRuntimeMs": 120000,
+  "description": "A safe first loop: local read-only checks plus durable run ledger.",
+  "humanGates": [
+    "source edits",
+    "external messages",
+    "destructive commands",
+    "production config changes"
+  ],
+  "breaker": {
+    "maxConsecutiveFailures": 3,
+    "sameFailureThreshold": 2
+  },
+  "checks": [
+    {
+      "id": "git-status",
+      "type": "command",
+      "cmd": "git status --short",
+      "expectExitCode": 0,
+      "timeoutMs": 10000,
+      "allowNonEmptyOutput": true
+    },
+    {
+      "id": "loop-config-dir",
+      "type": "files",
+      "paths": [
+        "configs/loops"
+      ]
+    }
+  ]
+}

package/lib/action-reservations.mjs

@@ -1,6 +1,7 @@
 import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
+import { migrateActionReservation } from './execution-ledger.mjs';
 
 const ACTION_KINDS = new Set(['paid_api', 'notification', 'deployment', 'process_control', 'publication', 'external_message', 'gated_mutation']);
 const TERMINAL_STATES = new Set(['settled', 'released']);
@@ -194,3 +195,9 @@ export async function migrateLegacyActionArtifact(root, legacy) {
   const scope = legacy.authorization_scope ?? legacy.authorization?.scope ?? 'legacy:unscoped';
   return reserveAction(root, { idempotencyKey: key, kind: legacy.kind ?? 'gated_mutation', request, authorizationScope: scope });
 }
+
+export async function projectActionToEffectProtocol(root, idempotencyKey) {
+  const reservation = await inspectAction(root, idempotencyKey);
+  if (!reservation) throw new Error('Action reservation not found.');
+  return migrateActionReservation(root, reservation);
+}

package/lib/core.mjs

@@ -4,6 +4,8 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { tmpdir } from 'node:os';
 import { createHash } from 'node:crypto';
+import { listSteps } from './execution-ledger.mjs';
+import { readAndVerifyEvidence } from './production-evidence.mjs';
 
 export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -747,6 +749,20 @@ export async function doctorReport(root, options = {}) {
   add('configs-dir', 'warn', await exists(configsDir), path.relative(root, configsDir));
   const runtimeDir = path.join(root, 'runtime', 'loops');
   add('runtime-dir', 'warn', await exists(runtimeDir), path.relative(root, runtimeDir));
+  try {
+    const steps = await listSteps(root);
+    const invalid = steps.filter((step) => step.version !== 2 || !step.step_id || !step.input_fingerprint || !['llm', 'tool', 'effect'].includes(step.kind));
+    const reconciliation = steps.filter((step) => step.status === 'unknown' || step.reconciliation?.required);
+    add('execution-ledger', 'fail', invalid.length === 0, { schema_version: 2, steps: steps.length, invalid: invalid.map((step) => step.step_id), reconciliation_required: reconciliation.map((step) => step.step_id) });
+    if (reconciliation.length) add('execution-ledger:reconciliation', 'warn', false, `${reconciliation.length} step(s) require evidence-backed reconciliation`);
+  } catch (error) {
+    add('execution-ledger', 'fail', false, error instanceof Error ? error.message : String(error));
+  }
+  const evidenceFile = path.join(root, '.production-evidence', 'evidence.json');
+  if (await exists(evidenceFile)) {
+    try { const evidence = await readAndVerifyEvidence(evidenceFile); add('production-evidence', 'fail', evidence.verification.valid && evidence.report.passed, { schema_version: evidence.report.schema_version, integrity: evidence.verification.valid, passed: evidence.report.passed, digest: evidence.report.integrity?.digest }); }
+    catch (error) { add('production-evidence', 'fail', false, error instanceof Error ? error.message : String(error)); }
+  } else add('production-evidence', 'warn', false, '.production-evidence/evidence.json not generated');
 
   const loopConfigs = await configFilesFromArgs(root, []);
   add('loop-configs-found', 'warn', loopConfigs.length > 0, `${loopConfigs.length} loop config(s)`);
@@ -1956,6 +1972,56 @@ export async function notifyTerminalTasks(root, options = {}) {
   };
 }
 
+export async function refreshTaskAcceptance(root, options = {}) {
+  const queue = normalizeLoopId(options.queue);
+  if (!options.taskId) throw new Error('queue-acceptance-refresh requires --task-id.');
+  await ensureQueueDirs(root, queue);
+  const located = await findTaskFile(root, queue, options.taskId);
+  if (!located) throw new Error(`Queue task not found: ${options.taskId}`);
+  const task = await readJson(located.file);
+  const dir = taskRuntimeDirFor(root, queue, task.id);
+  const checkpointsDir = path.join(dir, 'checkpoints');
+  const checkpointFiles = await listJson(checkpointsDir);
+  if (checkpointFiles.length === 0) return { queue, taskId: task.id, outcome: 'no_checkpoints' };
+  const judgementFile = path.join(dir, 'final_judgement.json');
+  const newestCheckpointMs = Math.max(...await Promise.all(checkpointFiles.map(async (file) => (await stat(path.join(checkpointsDir, file))).mtimeMs)));
+  if (await exists(judgementFile) && (await stat(judgementFile)).mtimeMs >= newestCheckpointMs) {
+    return { queue, taskId: task.id, outcome: 'already_current', judgement: path.relative(root, judgementFile) };
+  }
+
+  const contractFile = path.join(dir, 'task_contract.json');
+  const acceptanceFile = path.join(dir, 'acceptance_plan.json');
+  const devFile = path.join(dir, 'dev_plan.json');
+  const taskContract = { contract: await readJson(contractFile), file: path.relative(root, contractFile) };
+  const acceptancePlan = { plan: await readJson(acceptanceFile), file: path.relative(root, acceptanceFile) };
+  const devPlan = {
+    plan: await readJson(devFile),
+    file: path.relative(root, devFile),
+    checkpointsDir: path.relative(root, checkpointsDir),
+    reviewsDir: path.relative(root, path.join(dir, 'reviews'))
+  };
+  const checkpoints = await checkpointSummary(root, devPlan);
+  const acceptanceReviews = await writeAcceptanceReviews(root, queue, task, taskContract, acceptancePlan, devPlan);
+  const finalJudgement = await writeFinalJudgement(root, queue, task, taskContract, acceptancePlan, devPlan, checkpoints, acceptanceReviews, {
+    dispatchStatus: 'completed'
+  });
+  const status = queueStatusFromFinalJudgement('completed', finalJudgement);
+  const destinationName = status === 'completed' ? 'done' : status === 'project_in_progress' ? 'inbox' : 'failed';
+  const destination = path.join(queueSubdirFor(root, queue, destinationName), path.basename(located.file));
+  await writeJson(destination, { ...task, status: status === 'project_in_progress' ? 'queued' : status, acceptanceRefreshedAt: new Date().toISOString() });
+  if (destination !== located.file) await rm(located.file, { force: true });
+  return {
+    queue,
+    taskId: task.id,
+    outcome: 'refreshed',
+    status,
+    checkpointCount: checkpoints.count,
+    accepted: acceptanceReviews.accepted,
+    judgement: finalJudgement.file,
+    task: path.relative(root, destination)
+  };
+}
+
 function humanInputMessage(queue, task, checkpoint, gateId, language = 'en') {
   const blockers = Array.isArray(checkpoint.blockers) ? checkpoint.blockers : [];
   const blockerText = blockers.length

package/lib/durable-journal.mjs

@@ -0,0 +1,90 @@
+import { appendFile, copyFile, mkdir, open, readFile, rename, writeFile } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import path from 'node:path';
+
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+const canonical = (value) => JSON.stringify(sortValue(value));
+function sortValue(value) {
+  if (Array.isArray(value)) return value.map(sortValue);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortValue(value[key])]));
+  return value;
+}
+
+export class DurableJournal {
+  constructor(directory) {
+    this.directory = directory;
+    this.logFile = path.join(directory, 'events.jsonl');
+    this.snapshotFile = path.join(directory, 'snapshot.json');
+  }
+
+  async append(type, payload, transactionId = randomUUID()) {
+    await mkdir(this.directory, { recursive: true });
+    const previous = (await this.replay()).lastChecksum ?? null;
+    const event = { version: 1, transactionId, type, payload, previous };
+    event.checksum = digest(canonical(event));
+    const handle = await open(this.logFile, 'a');
+    try { await handle.write(`${JSON.stringify(event)}\n`); await handle.sync(); } finally { await handle.close(); }
+    return event;
+  }
+
+  async replay(reducer = (state, event) => ({ ...state, [event.type]: event.payload }), initial = {}) {
+    let raw = '';
+    try { raw = await readFile(this.logFile, 'utf8'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    let state = initial; let lastChecksum = null; let count = 0;
+    const lines = raw.split('\n');
+    for (let index = 0; index < lines.length; index++) {
+      const line = lines[index];
+      if (!line) continue;
+      let event;
+      try { event = JSON.parse(line); } catch (error) {
+        if (index === lines.length - 1) break;
+        throw new Error(`journal corruption at line ${index + 1}: ${error.message}`);
+      }
+      const checksum = event.checksum; const unsigned = { ...event }; delete unsigned.checksum;
+      if (digest(canonical(unsigned)) !== checksum || event.previous !== lastChecksum) throw new Error(`journal checksum chain invalid at line ${index + 1}`);
+      state = reducer(state, event); lastChecksum = checksum; count++;
+    }
+    return { state, count, lastChecksum };
+  }
+
+  async checkpoint(state) {
+    await mkdir(this.directory, { recursive: true });
+    const replay = await this.replay();
+    const snapshot = { version: 1, eventCount: replay.count, lastChecksum: replay.lastChecksum, state };
+    const temporary = `${this.snapshotFile}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(snapshot, null, 2)}\n`);
+    const handle = await open(temporary, 'r'); try { await handle.sync(); } finally { await handle.close(); }
+    await rename(temporary, this.snapshotFile);
+    return snapshot;
+  }
+
+  async backup(destination) {
+    await mkdir(destination, { recursive: true });
+    for (const name of ['events.jsonl', 'snapshot.json']) {
+      try { await copyFile(path.join(this.directory, name), path.join(destination, name)); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    }
+  }
+
+  static async restore(backup, destination) {
+    await mkdir(destination, { recursive: true });
+    for (const name of ['events.jsonl', 'snapshot.json']) {
+      try { await copyFile(path.join(backup, name), path.join(destination, name)); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    }
+    return new DurableJournal(destination).replay();
+  }
+
+  static async migrateV1(stateFile, directory) {
+    const journal = new DurableJournal(directory);
+    if ((await journal.replay()).count) return journal;
+    const state = JSON.parse(await readFile(stateFile, 'utf8'));
+    await journal.append('legacy_state_imported', { sourceVersion: state.version, state }, 'migration-v1');
+    await journal.checkpoint(state); return journal;
+  }
+}
+
+export function externalEffectBoundary({ status, idempotencyKey, upstreamEvidence }) {
+  if (!idempotencyKey) throw new Error('external side effect requires idempotencyKey');
+  if (status === 'accepted' && !upstreamEvidence) throw new Error('accepted side effect requires upstreamEvidence');
+  if (!['reserved', 'in_flight', 'unknown', 'accepted', 'not_accepted'].includes(status)) throw new Error('invalid side effect status');
+  return { status, idempotencyKey, upstreamEvidence: upstreamEvidence ?? null, replayable: ['reserved', 'not_accepted'].includes(status) };
+}