taskforce-loop-engineering 0.12.0 → 0.14.0

package/lib/execution-ledger.mjs

@@ -0,0 +1,41 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export const EXECUTION_LEDGER_VERSION = 2;
+const KINDS = new Set(['llm', 'tool', 'effect']);
+const TERMINAL = new Set(['succeeded', 'failed', 'cancelled']);
+const SENSITIVE = /(^|_)(secret|token|password|credential|api[_-]?key|private[_-]?key)(_|$)/i;
+const canonicalValue = (value) => Array.isArray(value) ? value.map(canonicalValue) : value && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalValue(value[key])])) : value;
+const hash = (value) => createHash('sha256').update(typeof value === 'string' ? value : JSON.stringify(canonicalValue(value))).digest('hex');
+export const stepInputFingerprint = (input) => hash(input);
+function text(value, name) { if (typeof value !== 'string' || !value.trim()) throw new Error(`${name} must be a non-empty string.`); return value; }
+function safeId(value, name = 'stepId') { text(value, name); if (!/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,299}$/.test(value)) throw new Error(`${name} contains unsafe characters or is too long.`); return value; }
+function redact(value, key = '') { if (SENSITIVE.test(key)) return '[REDACTED]'; if (Array.isArray(value)) return value.map((item) => redact(item)); if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((name) => [name, redact(value[name], name)])); return value; }
+function locations(root, stepId) { const directory = path.join(path.resolve(root), 'runtime', 'loops', 'execution-ledger'); const key = hash(safeId(stepId)); return { file: path.join(directory, 'steps', `${key}.json`), lock: path.join(directory, 'locks', key) }; }
+async function atomicWrite(file, value) { await mkdir(path.dirname(file), { recursive: true }); const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`; await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx', mode: 0o600 }); await rename(temporary, file); }
+async function mutex(lock) { await mkdir(path.dirname(lock), { recursive: true }); const deadline = Date.now() + 5000; while (true) { try { await mkdir(lock); return; } catch (error) { if (error.code !== 'EEXIST') throw error; const info = await stat(lock).catch(() => null); if (info && Date.now() - info.mtimeMs > 30_000) await rm(lock, { recursive: true, force: true }); else if (Date.now() >= deadline) throw new Error('Timed out acquiring execution ledger mutex.'); else await new Promise((resolve) => setTimeout(resolve, 10)); } } }
+async function mutate(root, stepId, operation) { const loc = locations(root, stepId); await mkdir(path.dirname(loc.file), { recursive: true }); await mutex(loc.lock); try { const record = await readFile(loc.file, 'utf8').then(JSON.parse).catch((error) => error.code === 'ENOENT' ? null : Promise.reject(error)); const result = await operation(record); if (result.write) await atomicWrite(loc.file, result.record); return result.output ?? result.record; } finally { await rm(loc.lock, { recursive: true, force: true }); } }
+function event(record, type, data = {}) { const entry = { sequence: record.events.length + 1, type, at: new Date().toISOString(), ...redact(data), previous: record.events.at(-1)?.checksum ?? null }; entry.checksum = hash(entry); return entry; }
+function assertFence(record, token) { if (record.status !== 'running' || record.lease?.fencing_token !== Number(token)) throw new Error('Stale or invalid fencing token.'); }
+
+export async function registerStep(root, input) {
+  const stepId = safeId(input.stepId); const kind = text(input.kind, 'kind'); if (!KINDS.has(kind)) throw new Error(`Unsupported step kind: ${kind}`); const fingerprint = stepInputFingerprint(input.input);
+  return mutate(root, stepId, async (record) => {
+    if (record) { if (record.kind !== kind || record.input_fingerprint !== fingerprint) throw new Error('Replay divergence: step identity is bound to a different kind or input fingerprint.'); return { write: false, output: { created: false, reusable: record.status === 'succeeded' && record.policy.reusable, record } }; }
+    const now = new Date().toISOString(); const created = { schema: 'loop.execution_step', version: 2, step_id: stepId, kind, status: 'pending', input_fingerprint: fingerprint, input: redact(input.input), lineage: { run_id: input.runId ?? null, task_id: input.taskId ?? null, parent_step_id: input.parentStepId ?? null, replaces_step_id: input.replacesStepId ?? null }, policy: { reusable: input.reusable !== false, effect_key: kind === 'effect' ? safeId(input.effectKey ?? stepId, 'effectKey') : null, authorization_scope: input.authorizationScope ?? null }, attempt: 0, fencing_counter: 0, lease: null, checkpoints: [], outcome: null, evidence: [], reconciliation: null, created_at: now, updated_at: now, events: [] }; created.events.push(event(created, 'registered', { input_fingerprint: fingerprint })); return { write: true, record: created, output: { created: true, reusable: false, record: created } };
+  });
+}
+export async function inspectStep(root, stepId) { const loc = locations(root, stepId); return readFile(loc.file, 'utf8').then(JSON.parse).catch((error) => error.code === 'ENOENT' ? null : Promise.reject(error)); }
+export async function claimStep(root, input) {
+  const leaseMs = Number(input.leaseMs ?? 60_000); if (!Number.isInteger(leaseMs) || leaseMs <= 0) throw new Error('leaseMs must be a positive integer.');
+  return mutate(root, input.stepId, async (record) => { if (!record) throw new Error('Step must be registered before claim.'); if (record.status === 'succeeded') return { write: false, output: { claimed: false, reason: record.policy.reusable ? 'reusable_outcome' : 'terminal', record } }; if (TERMINAL.has(record.status)) return { write: false, output: { claimed: false, reason: 'terminal', record } }; if (record.status === 'unknown') return { write: false, output: { claimed: false, reason: 'reconcile_required', record } }; const nowMs = Date.now(); if (record.status === 'running' && Date.parse(record.lease.expires_at) > nowMs) return { write: false, output: { claimed: false, reason: 'lease_active', record } }; if (record.status === 'running') { const at = new Date().toISOString(); const next = { ...record, status: 'unknown', lease: null, reconciliation: { required: true, reason: 'lease_expired_after_claim', at }, updated_at: at }; next.events = [...record.events, event(record, 'outcome_unknown', { reason: 'lease_expired_after_claim' })]; return { write: true, record: next, output: { claimed: false, reason: 'reconcile_required', record: next } }; } const token = record.fencing_counter + 1; const at = new Date().toISOString(); const next = { ...record, status: 'running', attempt: record.attempt + 1, fencing_counter: token, lease: { owner: text(input.owner, 'owner'), fencing_token: token, claimed_at: at, expires_at: new Date(nowMs + leaseMs).toISOString() }, updated_at: at }; next.events = [...record.events, event(record, 'claimed', { attempt: next.attempt, fencing_token: token, owner: input.owner })]; return { write: true, record: next, output: { claimed: true, fencingToken: token, attempt: next.attempt, record: next } }; });
+}
+export async function checkpointStep(root, input) { return mutate(root, input.stepId, async (record) => { assertFence(record, input.fencingToken); const checkpoint = { sequence: record.checkpoints.length + 1, at: new Date().toISOString(), fingerprint: stepInputFingerprint(input.state), state: redact(input.state), evidence: redact(input.evidence ?? null) }; const next = { ...record, checkpoints: [...record.checkpoints, checkpoint], updated_at: checkpoint.at }; next.events = [...record.events, event(record, 'checkpointed', { sequence: checkpoint.sequence, fingerprint: checkpoint.fingerprint })]; return { write: true, record: next, output: checkpoint }; }); }
+export async function completeStep(root, input) { return mutate(root, input.stepId, async (record) => { if (record?.status === 'succeeded') return { write: false, output: { completed: false, duplicate: true, record } }; assertFence(record, input.fencingToken); const at = new Date().toISOString(); const outcome = { status: 'succeeded', output_fingerprint: stepInputFingerprint(input.output), output: redact(input.output), at }; const next = { ...record, status: 'succeeded', lease: null, outcome, evidence: [...record.evidence, redact(input.evidence ?? {})], reconciliation: null, updated_at: at }; next.events = [...record.events, event(record, 'succeeded', { output_fingerprint: outcome.output_fingerprint })]; return { write: true, record: next, output: { completed: true, duplicate: false, record: next } }; }); }
+export async function markStepUnknown(root, input) { return mutate(root, input.stepId, async (record) => { assertFence(record, input.fencingToken); const at = new Date().toISOString(); const next = { ...record, status: 'unknown', lease: null, reconciliation: { required: true, reason: input.reason ?? 'submit_outcome_unknown', at }, evidence: [...record.evidence, redact(input.evidence ?? {})], updated_at: at }; next.events = [...record.events, event(record, 'outcome_unknown', { reason: next.reconciliation.reason })]; return { write: true, record: next }; }); }
+export async function reconcileStep(root, input) { return mutate(root, input.stepId, async (record) => { if (!record || record.status !== 'unknown') throw new Error('Only an unknown step can be reconciled.'); if (!['accepted', 'not_accepted'].includes(input.outcome)) throw new Error('Reconciliation outcome must be accepted or not_accepted.'); if (!input.evidence) throw new Error('Reconciliation requires evidence.'); const at = new Date().toISOString(); const evidence = redact(input.evidence); if (input.outcome === 'accepted') { const outcome = { status: 'succeeded', output_fingerprint: stepInputFingerprint(input.output), output: redact(input.output), reconciled: true, at }; const next = { ...record, status: 'succeeded', outcome, evidence: [...record.evidence, evidence], reconciliation: { required: false, outcome: 'accepted', at }, updated_at: at }; next.events = [...record.events, event(record, 'reconciled_accepted', { output_fingerprint: outcome.output_fingerprint })]; return { write: true, record: next }; } const next = { ...record, status: 'pending', lease: null, evidence: [...record.evidence, evidence], reconciliation: { required: false, outcome: 'not_accepted', at }, updated_at: at }; next.events = [...record.events, event(record, 'reconciled_not_accepted')]; return { write: true, record: next }; }); }
+export async function replayDecision(root, input) { const record = await inspectStep(root, input.stepId); if (!record) return { action: 'register_and_execute', record: null }; if (record.kind !== input.kind || record.input_fingerprint !== stepInputFingerprint(input.input)) return { action: 'divergence', reason: 'input_fingerprint_mismatch', record }; if (record.status === 'succeeded' && record.policy.reusable) return { action: 'reuse', output: record.outcome.output, evidence: record.evidence, record }; if (record.status === 'unknown' || record.status === 'running') return { action: 'reconcile', record }; if (record.status === 'pending') return { action: 'execute', checkpoint: record.checkpoints.at(-1) ?? null, record }; return { action: 'terminal', record }; }
+export async function listSteps(root) { const dir = path.join(path.resolve(root), 'runtime', 'loops', 'execution-ledger', 'steps'); const result = []; for (const name of (await readdir(dir).catch(() => [])).filter((name) => name.endsWith('.json')).sort()) result.push(JSON.parse(await readFile(path.join(dir, name), 'utf8'))); return result.sort((a, b) => a.step_id.localeCompare(b.step_id)); }
+export async function migrateLegacyJournalStep(root, legacy) { return registerStep(root, { stepId: legacy.step_id ?? legacy.stepId ?? `legacy:${legacy.transactionId ?? hash(legacy).slice(0, 24)}`, kind: KINDS.has(legacy.kind) ? legacy.kind : 'tool', input: legacy.input ?? legacy.payload ?? legacy, taskId: legacy.task_id, runId: legacy.run_id, reusable: legacy.reusable !== false }); }
+export async function migrateActionReservation(root, reservation) { const registered = await registerStep(root, { stepId: `effect:${reservation.idempotency_key}`, kind: 'effect', effectKey: reservation.idempotency_key, input: reservation.request, authorizationScope: reservation.authorization?.scope, reusable: true }); return { ...registered, legacy_state: reservation.state, migration: 'action_reservation_to_effect_protocol_v2' }; }

package/lib/operator-dashboard.mjs

@@ -102,9 +102,23 @@ async function actions(root, warnings, nowMs) {
   return result.sort((a, b) => String(a.idempotency_key).localeCompare(String(b.idempotency_key)));
 }
 
+async function executionSteps(root, warnings, nowMs) {
+  const result = [];
+  for (const file of await files(path.join(root, 'runtime', 'loops', 'execution-ledger', 'steps'))) {
+    const item = await json(file, warnings, root); if (!item) continue;
+    result.push(clean({ step_id: item.step_id, kind: item.kind, state: normalizedState(item, null, nowMs), status: item.status, input_fingerprint: item.input_fingerprint, attempt: item.attempt, lineage: item.lineage, lease: item.lease, checkpoint_count: item.checkpoints?.length ?? 0, outcome: item.outcome, evidence: item.evidence, reconciliation: item.reconciliation, updated_at: item.updated_at }));
+  }
+  return result.sort((a, b) => a.step_id.localeCompare(b.step_id));
+}
+
+async function productionEvidence(root, warnings) {
+  const file = path.join(root, '.production-evidence', 'public-summary.json');
+  try { return clean(await json(file, warnings, root)); } catch { return null; }
+}
+
 async function legacyQueues(root, warnings, nowMs) {
   const loops = path.join(root, 'runtime', 'loops');
-  const excluded = new Set(['control-plane', 'action-reservations', 'projects']);
+  const excluded = new Set(['control-plane', 'action-reservations', 'execution-ledger', 'projects']);
   const queues = [];
   for (const name of (await dirs(loops)).filter((item) => !excluded.has(item))) {
     const base = path.join(loops, name); const counts = Object.fromEntries([...STATES].map((state) => [state, 0])); const tasks = [];
@@ -138,13 +152,13 @@ export async function buildOperatorProjection(root, options = {}) {
   const resolved = path.resolve(root); const now = options.now ? new Date(options.now) : new Date();
   if (Number.isNaN(now.getTime())) throw new Error('Invalid projection time.');
   const warnings = []; const before = await stat(path.join(resolved, 'runtime', 'loops')).catch(() => null);
-  const [control, reservations, queueList, projectList] = await Promise.all([controlPlane(resolved, warnings, now.getTime()), actions(resolved, warnings, now.getTime()), legacyQueues(resolved, warnings, now.getTime()), projects(resolved, warnings)]);
-  const newest = [control.updated_at, ...control.todos.map((item) => item.updated_at), ...reservations.map((item) => item.updated_at), ...queueList.flatMap((queue) => queue.tasks.map((item) => item.updated_at))].filter(Boolean).sort().at(-1) ?? null;
+  const [control, reservations, steps, queueList, projectList, trustEvidence] = await Promise.all([controlPlane(resolved, warnings, now.getTime()), actions(resolved, warnings, now.getTime()), executionSteps(resolved, warnings, now.getTime()), legacyQueues(resolved, warnings, now.getTime()), projects(resolved, warnings), productionEvidence(resolved, warnings)]);
+  const newest = [control.updated_at, ...control.todos.map((item) => item.updated_at), ...reservations.map((item) => item.updated_at), ...steps.map((item) => item.updated_at), ...queueList.flatMap((queue) => queue.tasks.map((item) => item.updated_at))].filter(Boolean).sort().at(-1) ?? null;
   const counts = Object.fromEntries([...STATES].map((state) => [state, 0]));
   for (const item of [...control.todos, ...queueList.flatMap((queue) => queue.tasks)]) counts[item.state] += 1;
   const after = await stat(path.join(resolved, 'runtime', 'loops')).catch(() => null);
   if (before && after && before.mtimeMs !== after.mtimeMs) warnings.push({ code: 'concurrent_update', artifact: 'runtime/loops', message: 'Artifacts changed while the projection was read; refresh recommended.' });
-  return clean({ schema_version: DASHBOARD_SCHEMA_VERSION, generated_at: now.toISOString(), source: { root: resolved, read_only: true, newest_artifact_at: newest, freshness_seconds: newest ? Math.max(0, Math.floor((now.getTime() - Date.parse(newest)) / 1000)) : null }, health: { status: warnings.length ? 'degraded' : 'ok', warnings }, overview: { counts, queue_count: queueList.length, project_count: projectList.length, todo_count: control.todos.length, action_count: reservations.length }, projects: projectList, queues: queueList, todos: control.todos, agents: control.agents, handoffs: control.handoffs, gates: control.todos.filter((item) => ['parked', 'waiting_for_human', 'waiting_for_external_condition', 'timed_out_or_escalated'].includes(item.state)).map((item) => ({ todo_id: item.id, state: item.state, gate: item.gate, next_action: item.next_action })), actions: reservations, cost: { quotas: control.quotas, requested_total: control.todos.reduce((sum, item) => sum + Number(item.cost?.amount ?? 0), 0) } });
+  return clean({ schema_version: DASHBOARD_SCHEMA_VERSION, generated_at: now.toISOString(), source: { root: resolved, read_only: true, newest_artifact_at: newest, freshness_seconds: newest ? Math.max(0, Math.floor((now.getTime() - Date.parse(newest)) / 1000)) : null }, health: { status: warnings.length ? 'degraded' : 'ok', warnings }, overview: { counts, queue_count: queueList.length, project_count: projectList.length, todo_count: control.todos.length, action_count: reservations.length, step_count: steps.length, reconciliation_required_steps: steps.filter((item) => item.state === 'reconciliation_required').length, production_trust: trustEvidence?.passed ? 'passed' : trustEvidence ? 'failed' : 'not_generated' }, projects: projectList, queues: queueList, todos: control.todos, agents: control.agents, handoffs: control.handoffs, gates: control.todos.filter((item) => ['parked', 'waiting_for_human', 'waiting_for_external_condition', 'timed_out_or_escalated'].includes(item.state)).map((item) => ({ todo_id: item.id, state: item.state, gate: item.gate, next_action: item.next_action })), actions: reservations, execution_steps: steps, production_evidence: trustEvidence, cost: { quotas: control.quotas, requested_total: control.todos.reduce((sum, item) => sum + Number(item.cost?.amount ?? 0), 0) } });
 }
 
 export function filterProjection(projection, options = {}) {

package/lib/production-evidence.mjs

@@ -0,0 +1,54 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export const PRODUCTION_EVIDENCE_VERSION = 1;
+const SECRET = /(^|_)(secret|token|password|credential|api[_-]?key|private[_-]?key)(_|$)/i;
+const canonical = (value) => Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])])) : value;
+const digest = (value) => createHash('sha256').update(JSON.stringify(canonical(value))).digest('hex');
+export const redactEvidence = (value, key = '') => SECRET.test(key) ? '[REDACTED]' : Array.isArray(value) ? value.map((item) => redactEvidence(item)) : value && typeof value === 'object' ? Object.fromEntries(Object.entries(value).map(([name, item]) => [name, redactEvidence(item, name)])) : value;
+export const evidenceDigest = (value) => digest(value);
+
+export function evaluateEvidence(report, baseline = null) {
+  const thresholds = report.thresholds ?? {};
+  const metrics = report.metrics ?? {};
+  const checks = Object.entries(thresholds).map(([metric, rule]) => {
+    const actual = Number(metrics[metric]);
+    const passed = Number.isFinite(actual) && (rule.max === undefined || actual <= rule.max) && (rule.min === undefined || actual >= rule.min);
+    return { metric, actual, ...rule, passed, attribution: passed ? null : rule.attribution ?? 'unattributed_threshold_failure' };
+  });
+  const previous = baseline?.metrics ?? {};
+  const trend = Object.fromEntries(Object.keys(metrics).sort().filter((key) => Number.isFinite(Number(metrics[key])) && Number.isFinite(Number(previous[key]))).map((key) => [key, { baseline: Number(previous[key]), current: Number(metrics[key]), delta: Number(metrics[key]) - Number(previous[key]) }]));
+  return { checks, trend, passed: checks.every((item) => item.passed) && report.scenarios.every((item) => item.status === 'passed') && report.compatibility.every((item) => item.status === 'passed') };
+}
+
+export function sealEvidence(input) {
+  const report = redactEvidence({ ...input, schema: 'loop.production_trust_evidence', schema_version: PRODUCTION_EVIDENCE_VERSION });
+  const unsigned = { ...report, integrity: undefined };
+  delete unsigned.integrity;
+  return { ...report, integrity: { algorithm: 'sha256', digest: digest(unsigned) } };
+}
+
+export function verifyEvidence(report) {
+  if (report?.schema !== 'loop.production_trust_evidence' || report.schema_version !== PRODUCTION_EVIDENCE_VERSION) return { valid: false, reason: 'unsupported_schema' };
+  const unsigned = { ...report }; delete unsigned.integrity;
+  const actual = digest(unsigned); const expected = report.integrity?.digest;
+  return { valid: actual === expected, reason: actual === expected ? null : 'digest_mismatch', expected, actual };
+}
+
+export function publicEvidenceSummary(report) {
+  const verification = verifyEvidence(report);
+  return redactEvidence({ schema: 'loop.production_trust_public_summary', schema_version: 1, evidence_digest: report.integrity?.digest, generated_at: report.generated_at, passed: report.passed && verification.valid, fixtures: report.compatibility.map(({ runtime, contract_version, status }) => ({ runtime, contract_version, status })), metrics: report.metrics, thresholds: report.thresholds, failures: report.evaluation.checks.filter((item) => !item.passed).map(({ metric, attribution }) => ({ metric, attribution })), limitations: report.limitations });
+}
+
+export async function writeEvidenceBundle(directory, report) {
+  const sealed = sealEvidence(report); const summary = publicEvidenceSummary(sealed);
+  await mkdir(directory, { recursive: true });
+  for (const [name, value] of [['evidence.json', sealed], ['public-summary.json', summary]]) {
+    const file = path.join(directory, name); const temporary = `${file}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 }); await rename(temporary, file);
+  }
+  return { report: sealed, summary };
+}
+
+export async function readAndVerifyEvidence(file) { const report = JSON.parse(await readFile(file, 'utf8')); return { report, verification: verifyEvidence(report) }; }

package/lib/runtime-adapter-sdk.mjs

@@ -0,0 +1,115 @@
+import { createHash, randomUUID } from 'node:crypto';
+
+export const RUNTIME_ADAPTER_CONTRACT = 'loop.runtime-adapter';
+export const RUNTIME_ADAPTER_VERSION = '1.0.0';
+export const RUNTIME_ADAPTER_MAJOR = 1;
+export const RUNTIMES = Object.freeze(['openclaw', 'hermes', 'codex-cli', 'claude-code']);
+export const EFFECT_STATES = Object.freeze(['prepared', 'authorized', 'submitted', 'settled', 'unknown', 'rejected']);
+
+export class AdapterError extends Error {
+  constructor(code, message, { retryable = false, cause, details } = {}) {
+    super(message, { cause });
+    this.name = 'AdapterError'; this.code = code; this.retryable = retryable;
+    this.details = redact(details ?? null);
+  }
+  toJSON() { return { name: this.name, code: this.code, message: this.message, retryable: this.retryable, details: this.details }; }
+}
+
+export function redact(value) {
+  if (Array.isArray(value)) return value.map(redact);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.entries(value).map(([key, item]) =>
+    /token|secret|password|credential|authorization|cookie|api[-_]?key/i.test(key)
+      ? [key, '[REDACTED]'] : [key, redact(item)]));
+}
+
+const required = (value, label) => {
+  if (typeof value !== 'string' || !value.trim()) throw new AdapterError('INVALID_INPUT', `${label} is required`);
+  return value.trim();
+};
+const stableId = (prefix, value) => `${prefix}_${createHash('sha256').update(JSON.stringify(value)).digest('hex').slice(0, 20)}`;
+
+export function validateAdapter(adapter) {
+  if (adapter?.contract !== RUNTIME_ADAPTER_CONTRACT) throw new AdapterError('UNSUPPORTED_CONTRACT', 'unsupported adapter contract');
+  const major = Number.parseInt(String(adapter.version).split('.')[0], 10);
+  if (major !== RUNTIME_ADAPTER_MAJOR) throw new AdapterError('UNSUPPORTED_VERSION', `unsupported adapter version: ${adapter?.version}`);
+  if (!RUNTIMES.includes(adapter.runtime)) throw new AdapterError('UNSUPPORTED_RUNTIME', `unsupported runtime: ${adapter?.runtime}`);
+  for (const method of ['createSession', 'startRun', 'recordStep', 'prepareEffect', 'resolveGate', 'heartbeat', 'continueRun']) {
+    if (typeof adapter[method] !== 'function') throw new AdapterError('INVALID_ADAPTER', `adapter.${method} must be a function`);
+  }
+  return adapter;
+}
+
+export function defineRuntimeAdapter({ runtime, capabilities = [], transport }) {
+  if (!transport || typeof transport.invoke !== 'function') throw new AdapterError('INVALID_ADAPTER', 'transport.invoke must be a function');
+  const events = [];
+  const emit = (type, payload) => {
+    const event = redact({ contract: 'loop.telemetry', version: 1, type, runtime, at: new Date().toISOString(), ...payload });
+    events.push(event); transport.telemetry?.(event); return event;
+  };
+  const invoke = async (operation, payload) => {
+    try { return redact(await transport.invoke(operation, redact(payload))); }
+    catch (cause) {
+      if (cause instanceof AdapterError) throw cause;
+      throw new AdapterError('TRANSPORT_FAILURE', `${runtime} ${operation} failed`, { retryable: true, cause });
+    }
+  };
+  const adapter = {
+    contract: RUNTIME_ADAPTER_CONTRACT, version: RUNTIME_ADAPTER_VERSION, runtime,
+    capabilities: Object.freeze([...new Set(capabilities)].sort()),
+    telemetry: events,
+    async createSession(input = {}) {
+      const sessionId = input.sessionId ?? stableId('ses', { runtime, key: required(input.key, 'session key') });
+      const out = { sessionId, runtime, metadata: redact(input.metadata ?? {}) }; emit('session.created', out); return out;
+    },
+    async startRun(input = {}) {
+      const sessionId = required(input.sessionId, 'sessionId');
+      const runId = input.runId ?? stableId('run', { sessionId, requestId: input.requestId ?? randomUUID() });
+      const result = await invoke('run.start', { sessionId, runId, input: input.input ?? null });
+      const out = { sessionId, runId, status: result?.status ?? 'running' }; emit('run.started', out); return out;
+    },
+    async recordStep(input = {}) {
+      const runId = required(input.runId, 'runId'); const stepId = required(input.stepId, 'stepId');
+      const state = input.state ?? 'completed';
+      if (!['pending', 'running', 'completed', 'failed', 'waiting'].includes(state)) throw new AdapterError('INVALID_STEP_STATE', `invalid step state: ${state}`);
+      const evidence = redact(input.evidence ?? []); emit('step.recorded', { runId, stepId, state, evidence }); return { runId, stepId, state, evidence };
+    },
+    async prepareEffect(input = {}) {
+      const runId = required(input.runId, 'runId'); const effectId = required(input.effectId, 'effectId');
+      if (!input.idempotencyKey) throw new AdapterError('EFFECT_KEY_REQUIRED', 'effect idempotencyKey is required');
+      if (input.authorized !== true) throw new AdapterError('EFFECT_NOT_AUTHORIZED', 'effect is fail-closed until explicitly authorized');
+      const out = { runId, effectId, idempotencyKey: input.idempotencyKey, state: 'authorized', payload: redact(input.payload ?? null) };
+      emit('effect.authorized', out); return out;
+    },
+    async resolveGate(input = {}) {
+      const gateId = required(input.gateId, 'gateId');
+      if (!['approved', 'rejected'].includes(input.decision)) throw new AdapterError('INVALID_GATE_DECISION', 'gate decision must be approved or rejected');
+      const out = { gateId, decision: input.decision, responseRef: input.responseRef ?? null }; emit('gate.resolved', out); return out;
+    },
+    async heartbeat(input = {}) {
+      const runId = required(input.runId, 'runId'); const result = await invoke('run.heartbeat', { runId });
+      const out = { runId, alive: result?.alive !== false, continuationToken: result?.continuationToken ?? null };
+      emit('run.heartbeat', out); return out;
+    },
+    async continueRun(input = {}) {
+      const runId = required(input.runId, 'runId'); const continuationToken = required(input.continuationToken, 'continuationToken');
+      const result = await invoke('run.continue', { runId, continuationToken });
+      const out = { runId, status: result?.status ?? 'running' }; emit('run.continued', out); return out;
+    }
+  };
+  return validateAdapter(adapter);
+}
+
+export function createMemoryTransport() {
+  const calls = [];
+  return { calls, async invoke(operation, payload) {
+    calls.push({ operation, payload });
+    if (operation === 'run.heartbeat') return { alive: true, continuationToken: `continue_${payload.runId}` };
+    return { status: 'running' };
+  } };
+}
+
+export const createOpenClawAdapter = (transport) => defineRuntimeAdapter({ runtime: 'openclaw', capabilities: ['sessions', 'effects', 'human-gates', 'continuation'], transport });
+export const createHermesAdapter = (transport) => defineRuntimeAdapter({ runtime: 'hermes', capabilities: ['sessions', 'effects', 'human-gates', 'continuation'], transport });
+export const createCodexCliAdapter = (transport) => defineRuntimeAdapter({ runtime: 'codex-cli', capabilities: ['sessions', 'effects', 'human-gates', 'continuation'], transport });
+export const createClaudeCodeAdapter = (transport) => defineRuntimeAdapter({ runtime: 'claude-code', capabilities: ['sessions', 'effects', 'human-gates', 'continuation'], transport });

package/lib/runtime-adapter-v1.mjs

@@ -0,0 +1,36 @@
+export const ADAPTER_CONTRACT = 'loop.runtime-adapter';
+export const ADAPTER_MAJOR = 1;
+
+function requiredFunction(adapter, name) {
+  if (typeof adapter?.[name] !== 'function') throw new Error(`adapter.${name} must be a function`);
+}
+
+export function validateRuntimeAdapter(adapter) {
+  if (adapter?.contract !== ADAPTER_CONTRACT || adapter?.version !== ADAPTER_MAJOR) {
+    throw new Error(`unsupported runtime adapter contract: ${adapter?.contract}@${adapter?.version}`);
+  }
+  if (!['openclaw', 'hermes', 'custom'].includes(adapter.runtime)) throw new Error('unsupported adapter runtime');
+  for (const name of ['dispatch', 'heartbeat', 'reconcile']) requiredFunction(adapter, name);
+  return adapter;
+}
+
+export function defineRuntimeAdapter({ runtime, dispatch, heartbeat, reconcile, capabilities = [] }) {
+  return validateRuntimeAdapter({ contract: ADAPTER_CONTRACT, version: ADAPTER_MAJOR, runtime, capabilities: [...new Set(capabilities)].sort(), dispatch, heartbeat, reconcile });
+}
+
+export const openClawAdapter = defineRuntimeAdapter({
+  runtime: 'openclaw', capabilities: ['dispatch', 'heartbeat', 'reconcile'],
+  dispatch: async (request, io) => io.invoke('openclaw', ['agent', '--agent', request.worker, '--message', request.prompt]),
+  heartbeat: async (_request, io) => io.now(), reconcile: async (request, io) => io.lookup(request.idempotencyKey)
+});
+export const hermesAdapter = defineRuntimeAdapter({
+  runtime: 'hermes', capabilities: ['dispatch', 'heartbeat', 'reconcile'],
+  dispatch: async (request, io) => io.invoke('hermes', ['-z', request.prompt]),
+  heartbeat: async (_request, io) => io.now(), reconcile: async (request, io) => io.lookup(request.idempotencyKey)
+});
+
+export const customAdapterExample = defineRuntimeAdapter({
+  runtime: 'custom', capabilities: ['dispatch', 'heartbeat', 'reconcile'],
+  dispatch: async (request, io) => io.invoke('example-runtime', [request.prompt]),
+  heartbeat: async (_request, io) => io.now(), reconcile: async (request, io) => io.lookup(request.idempotencyKey)
+});

package/lib/upgrade-planner.mjs

@@ -0,0 +1,24 @@
+import { access, readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+async function exists(file) { try { await access(file); return true; } catch { return false; } }
+
+export async function planIronmanUpgrade(root, desired = []) {
+  const manifestFile = path.join(root, 'runtime', 'loop-engineering-openclaw-install.json');
+  const manifest = await exists(manifestFile) ? JSON.parse(await readFile(manifestFile, 'utf8')) : null;
+  const known = new Map((manifest?.managedFiles ?? []).map((item) => [item.path, item.sha256]));
+  const entries = [];
+  for (const item of desired) {
+    const target = path.join(root, item.path); const present = await exists(target);
+    const current = present ? await readFile(target, 'utf8') : null;
+    const managedClean = present && known.has(item.path) && known.get(item.path) === sha256(current);
+    const customized = present && !managedClean;
+    entries.push({ path: item.path, present, customized, action: !present ? 'create' : managedClean ? 'replace_managed' : 'preserve_customized', desiredSha256: sha256(item.content), currentSha256: present ? sha256(current) : null });
+  }
+  return {
+    version: 1, layout: manifest ? 'managed' : desired.some((item) => item.path.includes('ironman')) ? 'custom_ironman' : 'unmanaged',
+    readOnly: true, entries, destructive: false, readyToApply: entries.every((item) => !item.customized),
+    backupRequired: entries.some((item) => item.present), rollback: { strategy: 'restore_byte_exact_backup', requiredBeforeApply: true }
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskforce-loop-engineering",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "private": false,
   "description": "OpenClaw-native loop engineering CLI, templates, and skill for verifiable agent work loops.",
   "type": "module",
@@ -17,6 +17,9 @@
     "run-loop-cron.sh": "scripts/run-loop-cron.sh"
   },
   "scripts": {
+    "check:adapters": "node --check lib/runtime-adapter-sdk.mjs && node scripts/runtime-adapter-conformance.mjs",
+    "demo:adapter": "node examples/adapter-sdk-demo.mjs",
+    "check:production-trust": "node --check lib/runtime-adapter-v1.mjs && node --check lib/durable-journal.mjs && node --check lib/execution-ledger.mjs && node --check lib/production-evidence.mjs && node --check lib/upgrade-planner.mjs && node scripts/production-acceptance.mjs",
     "check:config-drift": "node --check scripts/config-drift-self-test.mjs && node scripts/config-drift-self-test.mjs",
     "check:openclaw-install": "node --check scripts/openclaw-install.mjs && node --check scripts/openclaw-doctor.mjs && node --check scripts/openclaw-smoke.mjs && node --check scripts/openclaw-manage.mjs && node scripts/openclaw-install-self-test.mjs",
     "check:hermes-install": "node --check scripts/hermes-install.mjs && node --check scripts/hermes-doctor.mjs && node --check scripts/hermes-smoke.mjs && node scripts/hermes-install-self-test.mjs",
@@ -32,6 +35,7 @@
     "README.md",
     "bin/",
     "docs/",
+    "examples/",
     "lib/",
     "scripts/",
     "templates/",

package/scripts/async-acceptance-refresh-self-test.mjs

@@ -0,0 +1,46 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { ensureQueueDirs, queueSubdirFor, readJson, refreshTaskAcceptance, writeJson } from '../lib/core.mjs';
+
+const root = await mkdtemp(path.join(tmpdir(), 'loop-async-acceptance-'));
+const queue = 'async-refresh';
+const taskId = 'detached-soak';
+const runtimeDir = path.join(root, 'runtime', 'loops', queue, 'tasks', taskId);
+
+try {
+  await ensureQueueDirs(root, queue);
+  await writeJson(path.join(queueSubdirFor(root, queue, 'failed'), `${taskId}.json`), {
+    version: 1, id: taskId, title: 'Detached soak', status: 'blocked'
+  });
+  await writeJson(path.join(runtimeDir, 'task_contract.json'), {
+    version: 1, task_id: taskId, task_scope: 'project', risk_level: 'L1', requires_human_gate: false,
+    constraints: { blocked_actions: [] }
+  });
+  await writeJson(path.join(runtimeDir, 'acceptance_plan.json'), {
+    version: 1, functional_checks: [], regression_checks: [], negative_tests: [], manual_review: [], automation: [], rubric: []
+  });
+  await writeJson(path.join(runtimeDir, 'dev_plan.json'), { version: 1, checkpoints: [{ id: 'cp1' }] });
+  await writeJson(path.join(runtimeDir, 'checkpoints', 'cp1.json'), {
+    version: 1, task_id: taskId, checkpoint_id: 'cp1', milestone_id: 'cp1', sequence: 1,
+    status: 'blocked', summary: 'Soak still running.', files_changed: ['soak.json'], verification: ['pending'], blockers: ['pending'], risks: [], project_completion: { status: 'in_progress' }
+  });
+  await writeJson(path.join(runtimeDir, 'final_judgement.json'), { version: 1, task_id: taskId, outcome: 'blocked' });
+  assert.equal((await refreshTaskAcceptance(root, { queue, taskId })).outcome, 'already_current');
+
+  await new Promise((resolve) => setTimeout(resolve, 20));
+  await writeJson(path.join(runtimeDir, 'checkpoints', 'cp2.json'), {
+    version: 1, task_id: taskId, checkpoint_id: 'cp2', milestone_id: 'cp1', revises_checkpoint_id: 'cp1', sequence: 2,
+    status: 'ready_for_acceptance', summary: 'Detached soak completed.', files_changed: ['soak.json'], verification: ['passed=true'], blockers: [], risks: [], project_completion: { status: 'accepted' }
+  });
+  const refreshed = await refreshTaskAcceptance(root, { queue, taskId });
+  assert.equal(refreshed.outcome, 'refreshed');
+  assert.equal(refreshed.status, 'completed');
+  assert.equal((await readJson(path.join(runtimeDir, 'final_judgement.json'))).outcome, 'ready_to_apply');
+  assert.equal((await refreshTaskAcceptance(root, { queue, taskId })).outcome, 'already_current');
+  assert.equal((await readJson(path.join(queueSubdirFor(root, queue, 'done'), `${taskId}.json`))).status, 'completed');
+  console.log('async acceptance refresh self-test passed');
+} finally {
+  await rm(root, { recursive: true, force: true });
+}

package/scripts/durable-journal-self-test.mjs

@@ -0,0 +1,24 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os'; import path from 'node:path';
+import { DurableJournal, externalEffectBoundary } from '../lib/durable-journal.mjs';
+
+const root = await mkdtemp(path.join(tmpdir(), 'loop-journal-'));
+try {
+  const journal = new DurableJournal(path.join(root, 'state'));
+  await journal.append('step_checkpointed', { step: 1 }, 'tx-1');
+  await journal.append('step_checkpointed', { step: 2 }, 'tx-2');
+  const replay = await journal.replay((state, event) => ({ step: event.payload.step }), {});
+  assert.deepEqual(replay.state, { step: 2 }); assert.equal(replay.count, 2);
+  await journal.checkpoint(replay.state);
+  await writeFile(journal.logFile, `${await readFile(journal.logFile, 'utf8')}{"torn":`);
+  assert.equal((await journal.replay()).count, 2);
+  const backup = path.join(root, 'backup'); await journal.backup(backup);
+  const restored = path.join(root, 'restored'); assert.equal((await DurableJournal.restore(backup, restored)).count, 2);
+  const legacy = path.join(root, 'state.json'); await writeFile(legacy, '{"version":1,"runs":7}\n');
+  const migrated = await DurableJournal.migrateV1(legacy, path.join(root, 'migrated'));
+  assert.equal((await migrated.replay()).count, 1); await DurableJournal.migrateV1(legacy, path.join(root, 'migrated')); assert.equal((await migrated.replay()).count, 1);
+  assert.equal(externalEffectBoundary({ status: 'unknown', idempotencyKey: 'task:step' }).replayable, false);
+  assert.throws(() => externalEffectBoundary({ status: 'accepted', idempotencyKey: 'k' }), /upstreamEvidence/);
+  console.log('durable journal self-test passed');
+} finally { await rm(root, { recursive: true, force: true }); }

package/scripts/execution-ledger-self-test.mjs

@@ -0,0 +1,10 @@
+import assert from 'node:assert/strict';
+import { mkdtemp } from 'node:fs/promises'; import { tmpdir } from 'node:os'; import path from 'node:path';
+import { checkpointStep, claimStep, completeStep, inspectStep, listSteps, markStepUnknown, migrateActionReservation, reconcileStep, registerStep, replayDecision, stepInputFingerprint } from '../lib/execution-ledger.mjs';
+const root = await mkdtemp(path.join(tmpdir(), 'loop-ledger-')); const base = { stepId: 'run:1:llm:plan', kind: 'llm', input: { model: 'mock', prompt: 'plan', api_key: 'secret' }, runId: 'run:1', taskId: 'task:1' };
+assert.equal((await registerStep(root, base)).created, true); assert.equal((await registerStep(root, base)).created, false); await assert.rejects(() => registerStep(root, { ...base, input: { prompt: 'changed' } }), /Replay divergence/); assert.equal((await inspectStep(root, base.stepId)).input.api_key, '[REDACTED]');
+const claims = await Promise.all(Array.from({ length: 16 }, (_, i) => claimStep(root, { stepId: base.stepId, owner: `w${i}`, leaseMs: 1000 }))); assert.equal(claims.filter((item) => item.claimed).length, 1); const winner = claims.find((item) => item.claimed); await checkpointStep(root, { stepId: base.stepId, fencingToken: winner.fencingToken, state: { cursor: 7 } }); await assert.rejects(() => completeStep(root, { stepId: base.stepId, fencingToken: winner.fencingToken + 1, output: 'bad' }), /fencing token/); await completeStep(root, { stepId: base.stepId, fencingToken: winner.fencingToken, output: { answer: 42 }, evidence: { fixture: 'mock' } }); assert.equal((await replayDecision(root, base)).action, 'reuse');
+await registerStep(root, { stepId: 'tool:crash-before', kind: 'tool', input: { command: 'mock' } }); await claimStep(root, { stepId: 'tool:crash-before', owner: 'dead', leaseMs: 1 }); await new Promise((resolve) => setTimeout(resolve, 5)); assert.equal((await claimStep(root, { stepId: 'tool:crash-before', owner: 'recover' })).reason, 'reconcile_required'); await reconcileStep(root, { stepId: 'tool:crash-before', outcome: 'not_accepted', evidence: { local: 'adapter_not_called' } }); assert.equal((await claimStep(root, { stepId: 'tool:crash-before', owner: 'recover' })).claimed, true);
+await registerStep(root, { stepId: 'effect:charge:1', kind: 'effect', effectKey: 'charge:1', input: { cents: 4 }, authorizationScope: 'test' }); const effect = await claimStep(root, { stepId: 'effect:charge:1', owner: 'worker' }); await markStepUnknown(root, { stepId: 'effect:charge:1', fencingToken: effect.fencingToken, reason: 'accepted_before_local_settle' }); assert.equal((await replayDecision(root, { stepId: 'effect:charge:1', kind: 'effect', input: { cents: 4 } })).action, 'reconcile'); await reconcileStep(root, { stepId: 'effect:charge:1', outcome: 'accepted', output: { upstream_id: 'mock-1' }, evidence: { upstream_lookup: 'mock-1' } }); assert.equal((await claimStep(root, { stepId: 'effect:charge:1', owner: 'retry' })).reason, 'reusable_outcome');
+const migrated = await migrateActionReservation(root, { idempotency_key: 'legacy:notify:1', state: 'reserved', request: { body: 'hello' }, authorization: { scope: 'chat' } }); assert.equal(migrated.record.policy.effect_key, 'legacy:notify:1'); assert.equal((await listSteps(root)).length, 4); assert.equal(stepInputFingerprint({ b: 2, a: 1 }), stepInputFingerprint({ a: 1, b: 2 }));
+console.log(JSON.stringify({ status: 'ok', assertions: ['identity', 'divergence', 'redaction', 'claim', 'lease', 'fencing', 'checkpoint', 'reuse', 'reconciliation', 'effect migration'] }));

package/scripts/live-runtime-soak.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { mkdir, rm, writeFile, rename } from 'node:fs/promises';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+
+const value = (name, fallback) => { const i = process.argv.indexOf(name); return i >= 0 ? process.argv[i + 1] : fallback; };
+const durationMs = Number(value('--duration-ms', 7_200_000));
+const output = path.resolve(value('--output', 'live-runtime-soak-report.json'));
+const openclawBin = value('--openclaw-bin', 'openclaw');
+const agent = value('--agent', 'ironman');
+const openclawProfile = value('--openclaw-profile', '');
+const hermesBin = value('--hermes-bin', '');
+const maxCalls = Number(value('--max-model-calls', 3));
+const dryRun = process.argv.includes('--dry-run');
+const runtimeOnly = process.argv.includes('--runtime-only');
+if (!Number.isFinite(durationMs) || durationMs < 60_000) throw new Error('duration must be at least 60 seconds');
+if (!Number.isInteger(maxCalls) || maxCalls < 1 || maxCalls > 6) throw new Error('max model calls must be 1..6');
+
+const runId = randomUUID();
+const workDir = path.join(tmpdir(), `loop-live-soak-${runId}`);
+await mkdir(workDir, { recursive: true }); await mkdir(path.dirname(output), { recursive: true });
+const startedAt = new Date(); const deadline = startedAt.getTime() + durationMs;
+const report = { version: 1, kind: hermesBin ? 'live-openclaw-hermes-multi-agent-runtime-soak' : 'live-openclaw-multi-session-soak', runId, dryRun, runtimeOnly, startedAt: startedAt.toISOString(), deadlineAt: new Date(deadline).toISOString(), agent, sessions: 3, modelCallsCap: dryRun || runtimeOnly ? 0 : maxCalls, modelCallsAttempted: 0, consecutiveRuntimeErrors: 0, stoppedByCircuitBreaker: false, externalWrites: false, productionProcessesControlled: false, events: [], metrics: { runtimeProbeFailures: 0, heartbeats: 0, claims: 0, handoffs: 0, injectedCrashes: 0, restarts: 0, staleFencesAccepted: 0, duplicateEffects: 0, unknownReconciled: 0 } };
+const statusOutput = `${output}.status.json`;
+const writeStatus = async (state, extra = {}) => {
+  const temporary = `${statusOutput}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify({ version: 1, state, runId, pid: process.pid, startedAt: report.startedAt, deadlineAt: report.deadlineAt, updatedAt: new Date().toISOString(), modelCallsAttempted: report.modelCallsAttempted, consecutiveRuntimeErrors: report.consecutiveRuntimeErrors, metrics: report.metrics, ...extra }, null, 2)}\n`);
+  await rename(temporary, statusOutput);
+};
+await writeStatus('starting');
+const sanitize = (text) => String(text).replace(/[A-Za-z0-9_=-]{24,}/g, '[redacted]').slice(0, 240);
+const record = (type, fields = {}) => report.events.push({ at: new Date().toISOString(), type, ...fields });
+const invoke = (worker) => new Promise((resolve) => {
+  report.modelCallsAttempted++;
+  const session = `agent:${agent}:loop-production-soak-${runId}-${worker}`;
+  const child = spawn(openclawBin, ['agent', '--agent', agent, '--session-key', session, '--message', 'Read-only local soak probe. Reply exactly SOAK_OK. Do not use tools, change files, send messages, or perform external actions.', '--json', '--timeout', '120'], { cwd: workDir, stdio: ['ignore', 'pipe', 'pipe'] });
+  let stdout = ''; let stderr = ''; child.stdout.on('data', (c) => { stdout += c; }); child.stderr.on('data', (c) => { stderr += c; });
+  child.on('close', (code, signal) => resolve({ code: code ?? (signal ? 128 : 1), evidence: sanitize(stdout || stderr) }));
+  child.on('error', (error) => resolve({ code: 127, evidence: sanitize(error.message) }));
+});
+const probe = (command, args, runtime) => new Promise((resolve) => {
+  const child = spawn(command, args, { cwd: workDir, stdio: ['ignore', 'pipe', 'pipe'] }); let stdout = ''; let stderr = '';
+  child.stdout.on('data', (c) => { stdout += c; }); child.stderr.on('data', (c) => { stderr += c; });
+  let settled = false; const finish = (ok, evidence) => { if (settled) return; settled = true; if (!ok) report.metrics.runtimeProbeFailures++; record('runtime_cli_probe', { runtime, ok, evidence: sanitize(evidence) }); resolve(ok); };
+  child.on('close', (code) => finish(code === 0, stdout || stderr)); child.on('error', (error) => finish(false, error.message));
+});
+
+const leases = { owner: null, until: 0, fence: 0, quotaUsed: 0, parked: false, effect: 'reserved' };
+const claim = (owner, now) => { if (leases.parked || leases.quotaUsed >= 2 || (leases.owner && leases.until > now)) return null; leases.owner = owner; leases.until = now + 90_000; leases.fence++; leases.quotaUsed++; report.metrics.claims++; return leases.fence; };
+const heartbeatChildren = new Map();
+let interruptedSignal = null;
+for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(signal, () => { interruptedSignal = signal; });
+const startHeartbeat = (worker) => {
+  const source = `setInterval(()=>process.stdout.write('h\\n'),1000)`;
+  const child = spawn(process.execPath, ['-e', source], { cwd: workDir, stdio: ['ignore', 'pipe', 'pipe'] });
+  child.stdout.on('data', (chunk) => { report.metrics.heartbeats += String(chunk).split('\n').filter(Boolean).length; });
+  heartbeatChildren.set(worker, child); return child;
+};
+
+try {
+  if (!dryRun) {
+    if (!await probe(openclawBin, [...(openclawProfile ? ['--profile', openclawProfile] : []), 'agents', 'list', '--json'], 'openclaw')) report.consecutiveRuntimeErrors++;
+    if (hermesBin && !await probe(hermesBin, ['--version'], 'hermes')) report.consecutiveRuntimeErrors++;
+    if (report.consecutiveRuntimeErrors >= 2) report.stoppedByCircuitBreaker = true;
+  }
+  for (let worker = 1; !dryRun && !runtimeOnly && worker <= 3 && report.modelCallsAttempted < maxCalls; worker++) {
+    const result = await invoke(`w${worker}`); record('runtime_probe', { worker: `w${worker}`, ok: result.code === 0, evidence: result.evidence });
+    report.consecutiveRuntimeErrors = result.code === 0 ? 0 : report.consecutiveRuntimeErrors + 1;
+    if (report.consecutiveRuntimeErrors >= 2) { report.stoppedByCircuitBreaker = true; break; }
+  }
+  if (!report.stoppedByCircuitBreaker) {
+    for (const worker of ['w1', 'w2', 'w3']) startHeartbeat(worker);
+    const first = claim('w1', Date.now()); record('claim', { worker: 'w1', fence: first });
+    leases.effect = 'unknown'; record('unknown_outcome', { replaySuppressed: true }); leases.effect = 'not_accepted'; report.metrics.unknownReconciled++;
+    await new Promise((resolve) => setTimeout(resolve, Math.min(65_000, Math.max(5_000, durationMs / 4))));
+    const crashed = heartbeatChildren.get('w1'); crashed.kill('SIGTERM'); report.metrics.injectedCrashes++; record('dedicated_worker_crash', { worker: 'w1' });
+    leases.until = Date.now() - 1; leases.quotaUsed = 0; const second = claim('w2', Date.now()); report.metrics.handoffs++; record('lease_handoff', { from: 'w1', to: 'w2', fence: second, staleFenceRejected: first !== second });
+    if (first === second) report.metrics.staleFencesAccepted++;
+    startHeartbeat('w1-restarted'); report.metrics.restarts++; record('dedicated_worker_restart', { worker: 'w1-restarted' });
+    leases.parked = true; record('parked_gate', { claimRejected: claim('w3', Date.now()) === null }); leases.parked = false;
+    await writeStatus('running');
+    while (Date.now() < deadline && !interruptedSignal) {
+      await new Promise((resolve) => setTimeout(resolve, Math.min(30_000, deadline - Date.now())));
+      await writeStatus(interruptedSignal ? 'stopping' : 'running');
+    }
+  }
+} finally {
+  for (const child of heartbeatChildren.values()) if (!child.killed) child.kill('SIGTERM');
+  report.completedAt = new Date().toISOString(); report.durationMs = Date.parse(report.completedAt) - startedAt.getTime();
+  report.interruptedSignal = interruptedSignal;
+  report.passed = !interruptedSignal && !report.stoppedByCircuitBreaker && report.metrics.runtimeProbeFailures === 0 && report.durationMs >= durationMs && report.metrics.heartbeats > 0 && report.metrics.handoffs === 1 && report.metrics.restarts === 1 && report.metrics.staleFencesAccepted === 0 && report.metrics.duplicateEffects === 0 && report.metrics.unknownReconciled === 1;
+  const temporary = `${output}.${process.pid}.tmp`; await writeFile(temporary, `${JSON.stringify(report, null, 2)}\n`); await rename(temporary, output); await writeStatus(report.passed ? 'passed' : 'failed', { completedAt: report.completedAt, passed: report.passed, interruptedSignal }); await rm(workDir, { recursive: true, force: true });
+}
+console.log(JSON.stringify({ runId, passed: report.passed, output, durationMs: report.durationMs, modelCallsAttempted: report.modelCallsAttempted }, null, 2));
+if (!report.passed) process.exitCode = 1;

package/scripts/operator-dashboard-self-test.mjs

@@ -3,6 +3,7 @@ import { mkdtemp, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { buildOperatorProjection, createDashboardServer, dashboardHealth, exportDashboard, filterProjection } from '../lib/operator-dashboard.mjs';
+import { claimStep, markStepUnknown, registerStep } from '../lib/execution-ledger.mjs';
 
 const root = await mkdtemp(path.join(tmpdir(), 'loop-dashboard-'));
 const loops = path.join(root, 'runtime', 'loops');
@@ -11,6 +12,7 @@ await mkdir(path.join(loops, 'action-reservations'), { recursive: true });
 await mkdir(path.join(loops, 'legacy', 'waiting'), { recursive: true });
 await mkdir(path.join(loops, 'legacy', 'active'), { recursive: true });
 await mkdir(path.join(loops, 'projects', 'p3', 'intake'), { recursive: true });
+await mkdir(path.join(root, '.production-evidence'), { recursive: true });
 const now = '2026-08-13T16:00:00.000Z';
 const control = {
   version: 2, updated_at: now, quotas: { credits: 9 }, agents: { a: { id: 'a', capabilities: ['code'], authority_grants: ['local'], provider_token: 'never-show' } },
@@ -25,6 +27,10 @@ await writeFile(path.join(loops, 'action-reservations', 'x.json'), JSON.stringif
 await writeFile(path.join(loops, 'legacy', 'waiting', 'vps.json'), JSON.stringify({ id: 'vps', title: 'VPS down', parked: { kind: 'external_condition', next_check_at: '2026-08-13T17:00:00.000Z' }, provider: 'hidden' }));
 await writeFile(path.join(loops, 'legacy', 'active', 'bad.json'), '{broken');
 await writeFile(path.join(loops, 'projects', 'p3', 'intake', 'latest.json'), JSON.stringify({ version: 1, goal: 'Operator dashboard', token: 'hidden' }));
+await writeFile(path.join(root, '.production-evidence', 'public-summary.json'), JSON.stringify({ schema: 'loop.production_trust_public_summary', schema_version: 1, passed: true, evidence_digest: 'fixture', metrics: { duplicate_settled_effects: 0 } }));
+await registerStep(root, { stepId: 'run:1:effect:send', kind: 'effect', effectKey: 'send:1', input: { api_key: 'hidden', body: 'hello' } });
+const ledgerClaim = await claimStep(root, { stepId: 'run:1:effect:send', owner: 'a' });
+await markStepUnknown(root, { stepId: 'run:1:effect:send', fencingToken: ledgerClaim.fencingToken, reason: 'accepted_before_local_settle' });
 
 const before = await stat(path.join(loops, 'control-plane', 'state.json'));
 const first = await buildOperatorProjection(root, { now });
@@ -35,6 +41,10 @@ assert.equal(before.mtimeMs, after.mtimeMs, 'projection does not mutate source s
 assert.equal(first.todos.find((item) => item.id === 'human').state, 'waiting_for_human');
 assert.equal(first.todos.find((item) => item.id === 'leased').state, 'reconciliation_required');
 assert.equal(first.actions[0].state, 'reconciliation_required');
+assert.equal(first.execution_steps[0].state, 'reconciliation_required');
+assert.equal(first.overview.reconciliation_required_steps, 1);
+assert.equal(first.overview.production_trust, 'passed');
+assert.equal(first.production_evidence.metrics.duplicate_settled_effects, 0);
 assert.equal(first.queues[0].tasks[0].state, 'waiting_for_external_condition');
 assert.equal(first.agents[0].provider_token, '[REDACTED]');
 assert.equal(first.todos[0].gate.secret_input, '[REDACTED]');

package/scripts/production-acceptance.mjs

@@ -0,0 +1,10 @@
+import { spawn } from 'node:child_process';
+const commands = [
+  ['node', ['scripts/runtime-adapter-contract-self-test.mjs']], ['node', ['scripts/durable-journal-self-test.mjs']],
+  ['node', ['scripts/execution-ledger-self-test.mjs']],
+  ['node', ['scripts/production-evidence-self-test.mjs']],
+  ['node', ['scripts/upgrade-planner-self-test.mjs']], ['node', ['scripts/production-soak.mjs']],
+  ['node', ['scripts/async-acceptance-refresh-self-test.mjs']], ['node', ['examples/safe-canary.mjs']]
+];
+for (const [command, args] of commands) await new Promise((resolve, reject) => { const child = spawn(command, args, { stdio: 'inherit' }); child.on('close', (code) => code === 0 ? resolve() : reject(new Error(`${command} ${args.join(' ')} exited ${code}`))); });
+console.log('production trust acceptance passed');