taskforce-loop-engineering 0.10.0 → 0.13.0

package/lib/operator-dashboard.mjs

@@ -0,0 +1,198 @@
+import { createServer } from 'node:http';
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export const DASHBOARD_SCHEMA_VERSION = '1.0.0';
+const SENSITIVE = /(^|_)(secret|token|password|credential|api[_-]?key|private[_-]?key|provider)(_|$)/i;
+const STATES = new Set(['runnable', 'active', 'parked', 'waiting_for_human', 'waiting_for_external_condition', 'timed_out_or_escalated', 'reconciliation_required', 'blocked', 'completed', 'failed']);
+
+function clean(value, key = '') {
+  if (SENSITIVE.test(key)) return '[REDACTED]';
+  if (Array.isArray(value)) return value.map((item) => clean(item));
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((name) => [name, clean(value[name], name)]));
+  return value;
+}
+
+function safeId(value) {
+  const result = String(value ?? '');
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,299}$/.test(result)) throw new Error('Unsafe dashboard identifier.');
+  return result;
+}
+
+function relativeLink(root, file) {
+  const relative = path.relative(root, file);
+  return relative && !relative.startsWith('..') && !path.isAbsolute(relative) ? relative.split(path.sep).join('/') : null;
+}
+
+async function json(file, warnings, root) {
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try { return JSON.parse(await readFile(file, 'utf8')); }
+    catch (error) {
+      if (error.code === 'ENOENT') return null;
+      if (attempt === 0) continue;
+      warnings.push({ code: 'malformed_artifact', artifact: relativeLink(root, file), message: String(error.message).split('\n')[0] });
+      return null;
+    }
+  }
+}
+
+async function dirs(dir) {
+  return (await readdir(dir, { withFileTypes: true }).catch(() => [])).filter((item) => item.isDirectory()).map((item) => item.name).sort();
+}
+
+async function files(dir, suffix = '.json') {
+  return (await readdir(dir, { withFileTypes: true }).catch(() => [])).filter((item) => item.isFile() && item.name.endsWith(suffix)).map((item) => path.join(dir, item.name)).sort();
+}
+
+function normalizedState(item, location, nowMs) {
+  const raw = String(item.state ?? item.status ?? '').toLowerCase();
+  if (raw === 'unknown' || item.reconciliation?.required) return 'reconciliation_required';
+  if (raw === 'claimed' || raw === 'running' || raw === 'active' || location === 'active') {
+    if (item.claim?.lease_expires_at && Date.parse(item.claim.lease_expires_at) <= nowMs) return 'reconciliation_required';
+    return 'active';
+  }
+  if (['completed', 'accepted', 'settled', 'released', 'success', 'succeeded'].includes(raw) || location === 'completed') return 'completed';
+  if (['failed', 'error', 'cancelled', 'goal_unreachable'].includes(raw) || location === 'failed') return 'failed';
+  if (raw.includes('timeout') || raw.includes('escalat')) return 'timed_out_or_escalated';
+  const parked = item.parked ?? item.wait ?? (location === 'waiting' ? item : null);
+  const wait = String(parked?.state ?? parked?.kind ?? raw).toLowerCase();
+  if (wait.includes('human')) return 'waiting_for_human';
+  if (wait.includes('external') || wait.includes('condition')) return 'waiting_for_external_condition';
+  if (parked || location === 'waiting' || raw === 'parked') return 'parked';
+  if (raw === 'blocked' || item.blocked_reasons?.length) return 'blocked';
+  if (raw === 'handoff_pending') return 'active';
+  return 'runnable';
+}
+
+function todoProjection(todo, nowMs) {
+  const state = normalizedState(todo, null, nowMs);
+  return clean({
+    id: String(todo.id), title: todo.title ?? todo.goal ?? String(todo.id), project_id: todo.project_id ?? todo.projectId ?? null,
+    state, source_version: todo.version ?? 1, priority: Number(todo.priority ?? 0), risk: todo.risk ?? null,
+    authority: todo.authority_class ?? todo.authorization?.scope ?? null, required_capabilities: todo.required_capabilities ?? [],
+    owner: todo.claim?.owner ?? null, lease: todo.claim ? { fencing_token: todo.claim.fencing_token ?? null, claimed_at: todo.claim.claimed_at ?? null, expires_at: todo.claim.lease_expires_at ?? null, expired: Date.parse(todo.claim.lease_expires_at ?? '') <= nowMs } : null,
+    gate: todo.parked ?? null, blocked_reasons: todo.blocked_reasons ?? [], lineage: todo.lineage ?? null,
+    acceptance: todo.acceptance_contract ?? null, evidence: todo.evidence ?? [], evidence_requirements: todo.evidence_requirements ?? [],
+    cost: todo.cost_envelope ?? null, idempotency_keys: todo.idempotency_keys ?? [], next_action: state === 'reconciliation_required' ? 'reconcile_unknown_action_or_expired_lease' : state === 'waiting_for_human' ? 'await_human_response' : state === 'waiting_for_external_condition' ? 'verify_external_condition' : state === 'runnable' ? 'claim_todo' : null,
+    created_at: todo.created_at ?? null, updated_at: todo.updated_at ?? null
+  });
+}
+
+async function controlPlane(root, warnings, nowMs) {
+  const file = path.join(root, 'runtime', 'loops', 'control-plane', 'state.json');
+  const state = await json(file, warnings, root);
+  if (!state) return { todos: [], agents: [], handoffs: [], quotas: {} };
+  return {
+    todos: Object.values(state.todos ?? {}).map((todo) => todoProjection(todo, nowMs)).sort((a, b) => b.priority - a.priority || a.id.localeCompare(b.id)),
+    agents: Object.values(state.agents ?? {}).map(clean).sort((a, b) => String(a.id).localeCompare(String(b.id))),
+    handoffs: Object.values(state.handoffs ?? {}).map(clean).sort((a, b) => String(a.created_at ?? '').localeCompare(String(b.created_at ?? '')) || String(a.id).localeCompare(String(b.id))),
+    quotas: clean(state.quotas ?? {}), updated_at: state.updated_at ?? null, source_version: state.version ?? 1
+  };
+}
+
+async function actions(root, warnings, nowMs) {
+  const dir = path.join(root, 'runtime', 'loops', 'action-reservations');
+  const result = [];
+  for (const file of await files(dir)) {
+    const item = await json(file, warnings, root);
+    if (!item) continue;
+    const state = normalizedState(item, null, nowMs);
+    result.push(clean({ idempotency_key: item.idempotency_key, kind: item.kind, state, reservation_state: item.state, request_fingerprint: item.request_fingerprint, authorization: item.authorization, owner: item.claim?.owner ?? null, lease: item.claim ? { fencing_token: item.claim.fencing_token, expires_at: item.claim.lease_expires_at, expired: Date.parse(item.claim.lease_expires_at ?? '') <= nowMs } : null, reconciliation: item.reconciliation, settlement: item.settlement, release: item.release, created_at: item.created_at, updated_at: item.updated_at }));
+  }
+  return result.sort((a, b) => String(a.idempotency_key).localeCompare(String(b.idempotency_key)));
+}
+
+async function legacyQueues(root, warnings, nowMs) {
+  const loops = path.join(root, 'runtime', 'loops');
+  const excluded = new Set(['control-plane', 'action-reservations', '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 = [];
+    for (const location of ['inbox', 'active', 'waiting', 'completed', 'failed']) {
+      for (const file of await files(path.join(base, location))) {
+        const item = await json(file, warnings, root); if (!item) continue;
+        const state = normalizedState(item, location, nowMs); counts[state] += 1;
+        tasks.push(clean({ id: String(item.id ?? path.basename(file, '.json')), title: item.title ?? item.goal ?? item.task ?? path.basename(file, '.json'), state, queue: name, location, project_id: item.project_id ?? item.projectId ?? null, owner: item.owner ?? item.claim?.owner ?? null, gate: item.parked ?? item.wait ?? null, next_wake: item.next_wake_at ?? item.nextWakeAt ?? item.parked?.next_check_at ?? null, next_action: item.next_action ?? item.nextAction ?? null, risk: item.risk ?? null, evidence_links: [relativeLink(root, file)].filter(Boolean), updated_at: item.updated_at ?? item.created_at ?? null }));
+      }
+    }
+    const stateFile = path.join(base, 'state.json'); const state = await json(stateFile, warnings, root);
+    queues.push({ id: name, counts, tasks: tasks.sort((a, b) => a.id.localeCompare(b.id)), scheduler: clean(state), source_version: state?.version ?? 1 });
+  }
+  return queues;
+}
+
+async function projects(root, warnings) {
+  const result = [];
+  const runtime = path.join(root, 'runtime', 'loops', 'projects');
+  for (const id of await dirs(runtime)) {
+    const base = path.join(runtime, id);
+    const intake = await json(path.join(base, 'intake', 'latest.json'), warnings, root);
+    const backlog = await json(path.join(base, 'backlog', 'initial.json'), warnings, root);
+    const completion = await json(path.join(base, 'completion', 'latest.json'), warnings, root);
+    result.push(clean({ id, goal: intake?.goal ?? intake?.brief ?? null, queue: intake?.queue ?? null, status: completion?.status ?? (completion ? 'completed' : 'active'), acceptance: intake?.acceptance ?? null, backlog: backlog?.tasks ?? backlog?.items ?? backlog ?? null, evidence_links: [intake && relativeLink(root, path.join(base, 'intake', 'latest.json')), backlog && relativeLink(root, path.join(base, 'backlog', 'initial.json')), completion && relativeLink(root, path.join(base, 'completion', 'latest.json'))].filter(Boolean) }));
+  }
+  return result.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+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 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) } });
+}
+
+export function filterProjection(projection, options = {}) {
+  const query = String(options.query ?? '').toLowerCase(); const state = options.state;
+  const match = (item) => (!state || item.state === state) && (!query || JSON.stringify(item).toLowerCase().includes(query));
+  return { ...projection, todos: projection.todos.filter(match), queues: projection.queues.map((queue) => ({ ...queue, tasks: queue.tasks.filter(match) })), actions: projection.actions.filter(match) };
+}
+
+export function dashboardHealth(projection, options = {}) {
+  const maxAge = Number(options.maxAgeSeconds ?? 3600);
+  const stale = projection.source.freshness_seconds !== null && projection.source.freshness_seconds > maxAge;
+  return { schema_version: DASHBOARD_SCHEMA_VERSION, status: projection.health.status === 'ok' && !stale ? 'ok' : 'degraded', read_only: true, stale, freshness_seconds: projection.source.freshness_seconds, warnings: projection.health.warnings };
+}
+
+function html() {
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Loop Engineering Operator Dashboard</title><style>body{font:14px system-ui;margin:2rem;background:#10151c;color:#e8edf2}input,select{padding:.55rem;background:#18222e;color:inherit;border:1px solid #445}table{width:100%;border-collapse:collapse;margin-top:1rem}th,td{text-align:left;padding:.55rem;border-bottom:1px solid #344}.pill{padding:.2rem .5rem;border-radius:1rem;background:#25364a}a{color:#78b7ff}</style></head><body><h1>Loop Engineering</h1><p id="health">Loading read-only projection…</p><input id="q" placeholder="Search"><select id="s"><option value="">All states</option></select><table><thead><tr><th>State</th><th>Task</th><th>Owner</th><th>Next action</th></tr></thead><tbody id="rows"></tbody></table><script>const states=['runnable','active','parked','waiting_for_human','waiting_for_external_condition','timed_out_or_escalated','reconciliation_required','blocked','completed','failed'];s.innerHTML+=states.map(x=>'<option>'+x+'</option>').join('');async function draw(){const p=new URLSearchParams({q:q.value,state:s.value});const d=await fetch('/api/v1/overview?'+p).then(r=>r.json());health.textContent=d.health.status+' · '+d.overview.todo_count+' typed todos · '+d.overview.queue_count+' queues';const all=[...d.todos,...d.queues.flatMap(x=>x.tasks)];rows.replaceChildren(...all.map(x=>{const tr=document.createElement('tr');for(const v of [x.state,x.title,x.owner??'—',x.next_action??'—']){const td=document.createElement('td');td.textContent=String(v);tr.append(td)}return tr}))}q.oninput=draw;s.onchange=draw;draw()</script></body></html>`;
+}
+
+function loopback(host) { return host === '127.0.0.1' || host === '::1' || host === 'localhost'; }
+
+export async function createDashboardServer(root, options = {}) {
+  const host = options.host ?? '127.0.0.1'; const port = Number(options.port ?? 0);
+  if (!loopback(host) && options.allowNonLoopback !== true) throw new Error('Non-loopback dashboard bind requires --allow-non-loopback.');
+  const server = createServer(async (request, response) => {
+    try {
+      const url = new URL(request.url, 'http://localhost');
+      if (request.method !== 'GET' && request.method !== 'HEAD') { response.writeHead(405, { Allow: 'GET, HEAD' }); return response.end(); }
+      if (url.pathname.includes('..') || /%2e/i.test(request.url)) { response.writeHead(400); return response.end('unsafe path'); }
+      if (url.pathname === '/') { response.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'content-security-policy': "default-src 'self'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self'; object-src 'none'; base-uri 'none'", 'x-content-type-options': 'nosniff' }); return response.end(request.method === 'HEAD' ? '' : html()); }
+      const projection = await buildOperatorProjection(root);
+      let body;
+      if (url.pathname === '/api/v1/overview') body = filterProjection(projection, { query: url.searchParams.get('q'), state: url.searchParams.get('state') });
+      else if (url.pathname === '/api/v1/health') body = dashboardHealth(projection, { maxAgeSeconds: url.searchParams.get('max_age_seconds') ?? 3600 });
+      else if (url.pathname === '/api/v1/todos') body = filterProjection(projection, { query: url.searchParams.get('q'), state: url.searchParams.get('state') }).todos;
+      else if (url.pathname.startsWith('/api/v1/todos/')) body = projection.todos.find((item) => item.id === safeId(decodeURIComponent(url.pathname.slice('/api/v1/todos/'.length)))) ?? null;
+      else if (url.pathname === '/api/v1/actions') body = projection.actions;
+      else { response.writeHead(404); return response.end('not found'); }
+      response.writeHead(body === null ? 404 : 200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' }); response.end(request.method === 'HEAD' ? '' : `${JSON.stringify(body)}\n`);
+    } catch (error) { response.writeHead(500, { 'content-type': 'application/json; charset=utf-8' }); response.end(`${JSON.stringify({ error: 'projection_failed', message: String(error.message) })}\n`); }
+  });
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, host, resolve); });
+  return server;
+}
+
+export async function exportDashboard(root, outputDir, options = {}) {
+  const target = path.resolve(outputDir); const projection = await buildOperatorProjection(root, options);
+  await mkdir(target, { recursive: true });
+  await writeFile(path.join(target, 'projection.json'), `${JSON.stringify(projection, null, 2)}\n`);
+  await writeFile(path.join(target, 'index.html'), html().replace("fetch('/api/v1/overview?'+p)", "fetch('./projection.json')"));
+  return { schema_version: DASHBOARD_SCHEMA_VERSION, output_dir: target, files: ['index.html', 'projection.json'], read_only_source: true };
+}

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/todo-control-plane.mjs

@@ -0,0 +1,287 @@
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { inspectAction } from './action-reservations.mjs';
+
+const TODO_STATES = new Set(['runnable', 'blocked', 'claimed', 'handoff_pending', 'completed']);
+const RISK = new Set(['low', 'medium', 'high', 'critical']);
+
+function text(value, label) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${label} must be a non-empty string.`);
+  return value.trim();
+}
+
+function id(value, label) {
+  const result = text(value, label);
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,199}$/.test(result)) throw new Error(`${label} contains unsafe characters.`);
+  return result;
+}
+
+function strings(value, label) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || !item.trim())) throw new Error(`${label} must be an array of strings.`);
+  return [...new Set(value.map((item) => item.trim()))].sort();
+}
+
+function location(root) {
+  const dir = path.join(root, 'runtime', 'loops', 'control-plane');
+  return { dir, file: path.join(dir, 'state.json'), lock: path.join(dir, 'state.lock'), audit: path.join(dir, 'audit.jsonl') };
+}
+
+function emptyState() {
+  return { version: 2, fencing_counter: 0, agents: {}, todos: {}, handoffs: {}, quotas: {}, updated_at: null };
+}
+
+async function readState(file) {
+  try { return JSON.parse(await readFile(file, 'utf8')); } catch (error) { if (error.code === 'ENOENT') return emptyState(); throw error; }
+}
+
+async function atomicWrite(file, value) {
+  const temp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  await writeFile(temp, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx' });
+  await rename(temp, file);
+}
+
+async function acquire(lock, timeoutMs = 5000) {
+  const deadline = Date.now() + timeoutMs;
+  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 control-plane mutex.');
+      else await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+  }
+}
+
+async function transaction(root, operation) {
+  const place = location(root);
+  await mkdir(place.dir, { recursive: true });
+  await acquire(place.lock);
+  try {
+    const state = await readState(place.file);
+    const result = await operation(state);
+    if (result.changed) {
+      state.updated_at = new Date().toISOString();
+      await atomicWrite(place.file, state);
+      if (result.event) await writeFile(place.audit, `${JSON.stringify(result.event)}\n`, { flag: 'a' });
+    }
+    return result.output;
+  } finally { await rm(place.lock, { recursive: true, force: true }); }
+}
+
+function event(type, todo, extra = {}) {
+  return { version: 1, event_id: randomUUID(), type, todo_id: todo.id, at: new Date().toISOString(), owner: todo.claim?.owner ?? null, fencing_token: todo.claim?.fencing_token ?? null, ...extra };
+}
+
+function normalizeAgent(input) {
+  const authority = strings(input.authority_grants ?? input.authorityGrants, 'authority_grants');
+  return { id: id(input.id ?? input.agent_id, 'agent id'), capabilities: strings(input.capabilities, 'capabilities'), authority_grants: authority, quota_grants: { ...(input.quota_grants ?? input.quotaGrants ?? {}) }, registered_at: new Date().toISOString() };
+}
+
+export async function registerAgent(root, input) {
+  const agent = normalizeAgent(input);
+  return transaction(root, async (state) => {
+    const previous = state.agents[agent.id];
+    state.agents[agent.id] = { ...agent, registered_at: previous?.registered_at ?? agent.registered_at, updated_at: new Date().toISOString() };
+    return { changed: true, output: state.agents[agent.id], event: { version: 1, event_id: randomUUID(), type: previous ? 'agent_updated' : 'agent_registered', agent_id: agent.id, at: new Date().toISOString() } };
+  });
+}
+
+function normalizeTodo(input) {
+  const todoId = id(input.id, 'todo id');
+  const risk = input.risk ?? 'low';
+  if (!RISK.has(risk)) throw new Error(`Unsupported risk: ${risk}`);
+  const priority = Number(input.priority ?? 0);
+  const cost = Number(input.cost ?? input.cost_envelope?.amount ?? 0);
+  if (!Number.isFinite(priority) || !Number.isFinite(cost) || cost < 0) throw new Error('priority and cost must be valid numbers.');
+  const acceptance = input.acceptance_contract ?? input.acceptanceContract;
+  if (!acceptance || typeof acceptance !== 'object') throw new Error('acceptance_contract is required.');
+  const evidence = strings(input.evidence_requirements ?? input.evidenceRequirements, 'evidence_requirements');
+  if (!evidence.length) throw new Error('evidence_requirements must not be empty.');
+  const created = new Date().toISOString();
+  return {
+    version: 2, id: todoId, title: text(input.title, 'title'), project_id: input.project_id ?? input.projectId ?? null,
+    dependencies: strings(input.dependencies, 'dependencies'), priority, risk, authority_class: text(input.authority_class ?? input.authorityClass ?? 'local', 'authority_class'),
+    required_capabilities: strings(input.required_capabilities ?? input.requiredCapabilities, 'required_capabilities'), acceptance_contract: acceptance,
+    evidence_requirements: evidence, cost_envelope: { quota: input.quota ?? input.cost_envelope?.quota ?? 'default', amount: cost },
+    state: 'runnable', blocked_reasons: [], claim: null, handoff_id: null, parked: input.parked ?? null,
+    authorization: input.authorization ?? null, idempotency_keys: strings(input.idempotency_keys ?? input.idempotencyKeys, 'idempotency_keys'),
+    lineage: input.lineage ?? { root_todo_id: todoId, parent_todo_id: null }, context: input.context ?? {}, evidence: input.evidence ?? [],
+    created_at: created, updated_at: created
+  };
+}
+
+export async function createTodo(root, input) {
+  const todo = normalizeTodo(input);
+  return transaction(root, async (state) => {
+    if (state.todos[todo.id]) throw new Error(`Todo already exists: ${todo.id}`);
+    for (const dependency of todo.dependencies) if (dependency === todo.id) throw new Error('A todo cannot depend on itself.');
+    state.todos[todo.id] = todo;
+    return { changed: true, output: todo, event: event('todo_created', todo) };
+  });
+}
+
+function capabilityEligible(agent, todo) { return todo.required_capabilities.every((item) => agent.capabilities.includes(item)); }
+function authorityEligible(agent, todo) { return agent.authority_grants.includes('*') || agent.authority_grants.includes(todo.authority_class); }
+
+async function eligibility(root, state, todo, agent, now = Date.now()) {
+  const reasons = [];
+  if (!['runnable', 'blocked'].includes(todo.state)) reasons.push(`state:${todo.state}`);
+  if (todo.parked && !['runnable', 'resumed'].includes(todo.parked.state)) reasons.push('parked_human_gate');
+  const missing = todo.dependencies.filter((dep) => state.todos[dep]?.state !== 'completed');
+  if (missing.length) reasons.push(`dependencies:${missing.join(',')}`);
+  if (!capabilityEligible(agent, todo)) reasons.push('capability_mismatch');
+  if (!authorityEligible(agent, todo)) reasons.push('authority_mismatch');
+  const quota = todo.cost_envelope.quota;
+  const available = Number(agent.quota_grants?.[quota] ?? state.quotas?.[quota] ?? 0);
+  if (todo.cost_envelope.amount > available) reasons.push('quota_exhausted');
+  for (const key of todo.idempotency_keys) {
+    const action = await inspectAction(root, key);
+    if (action?.state === 'unknown') reasons.push(`action_reconciliation:${key}`);
+    if (action?.state === 'claimed' && Date.parse(action.claim?.lease_expires_at ?? '') <= now) reasons.push(`action_reconciliation:${key}`);
+  }
+  return { eligible: reasons.length === 0, reasons };
+}
+
+export async function listTodos(root, options = {}) {
+  const state = await readState(location(root).file);
+  return Object.values(state.todos).filter((todo) => !options.state || todo.state === options.state).sort((a, b) => b.priority - a.priority || a.created_at.localeCompare(b.created_at) || a.id.localeCompare(b.id));
+}
+
+export async function inspectTodo(root, todoId) { return (await readState(location(root).file)).todos[id(todoId, 'todo id')] ?? null; }
+
+export async function claimTodo(root, input) {
+  const agentId = id(input.agent_id ?? input.agentId, 'agent id');
+  const leaseMs = Number(input.lease_ms ?? input.leaseMs ?? 60_000);
+  if (!Number.isInteger(leaseMs) || leaseMs <= 0) throw new Error('lease_ms must be a positive integer.');
+  return transaction(root, async (state) => {
+    const agent = state.agents[agentId];
+    if (!agent) throw new Error(`Agent not registered: ${agentId}`);
+    const candidates = input.todo_id ?? input.todoId ? [state.todos[id(input.todo_id ?? input.todoId, 'todo id')]].filter(Boolean) : Object.values(state.todos);
+    candidates.sort((a, b) => b.priority - a.priority || a.created_at.localeCompare(b.created_at) || a.id.localeCompare(b.id));
+    const rejected = [];
+    for (const todo of candidates) {
+      const check = await eligibility(root, state, todo, agent);
+      if (!check.eligible) { rejected.push({ todo_id: todo.id, reasons: check.reasons }); continue; }
+      const now = new Date();
+      const token = ++state.fencing_counter;
+      todo.state = 'claimed'; todo.blocked_reasons = []; todo.updated_at = now.toISOString();
+      todo.claim = { owner: agentId, fencing_token: token, claimed_at: now.toISOString(), lease_expires_at: new Date(now.getTime() + leaseMs).toISOString() };
+      const audit = event('todo_claimed', todo, { agent_id: agentId });
+      todo.ownership_events = [...(todo.ownership_events ?? []), audit];
+      return { changed: true, output: { claimed: true, todo, fencing_token: token }, event: audit };
+    }
+    return { changed: false, output: { claimed: false, reason: rejected[0]?.reasons?.[0] ?? 'no_eligible_todo', rejected } };
+  });
+}
+
+function assertClaim(todo, agentId, token) {
+  if (!todo || todo.state !== 'claimed' || todo.claim?.owner !== agentId || todo.claim?.fencing_token !== Number(token)) throw new Error('Stale or invalid todo fencing token.');
+  if (Date.parse(todo.claim.lease_expires_at) <= Date.now()) throw new Error('Todo lease has expired.');
+}
+
+export async function renewTodo(root, input) {
+  return transaction(root, async (state) => {
+    const todo = state.todos[id(input.todo_id ?? input.todoId, 'todo id')];
+    assertClaim(todo, id(input.agent_id ?? input.agentId, 'agent id'), input.fencing_token ?? input.fencingToken);
+    const leaseMs = Number(input.lease_ms ?? input.leaseMs ?? 60_000);
+    if (!Number.isInteger(leaseMs) || leaseMs <= 0) throw new Error('lease_ms must be a positive integer.');
+    todo.claim.lease_expires_at = new Date(Date.now() + leaseMs).toISOString(); todo.updated_at = new Date().toISOString();
+    const audit = event('todo_lease_renewed', todo);
+    todo.ownership_events.push(audit);
+    return { changed: true, output: todo, event: audit };
+  });
+}
+
+export async function releaseTodo(root, input) {
+  return transaction(root, async (state) => {
+    const todo = state.todos[id(input.todo_id ?? input.todoId, 'todo id')];
+    assertClaim(todo, id(input.agent_id ?? input.agentId, 'agent id'), input.fencing_token ?? input.fencingToken);
+    const previous = todo.claim; todo.state = input.completed ? 'completed' : 'runnable'; todo.claim = null; todo.updated_at = new Date().toISOString();
+    if (input.evidence) todo.evidence = [...todo.evidence, input.evidence];
+    const audit = event(input.completed ? 'todo_completed' : 'todo_released', todo, { previous_owner: previous.owner, previous_fencing_token: previous.fencing_token, reason: input.reason ?? null });
+    todo.ownership_events.push(audit);
+    return { changed: true, output: todo, event: audit };
+  });
+}
+
+export async function handoffTodo(root, input) {
+  return transaction(root, async (state) => {
+    const todo = state.todos[id(input.todo_id ?? input.todoId, 'todo id')];
+    const source = id(input.agent_id ?? input.agentId, 'agent id');
+    assertClaim(todo, source, input.fencing_token ?? input.fencingToken);
+    const target = id(input.target_agent_id ?? input.targetAgentId, 'target agent id');
+    if (!state.agents[target]) throw new Error(`Agent not registered: ${target}`);
+    const targetCheck = await eligibility(root, { ...state, todos: { ...state.todos, [todo.id]: { ...todo, state: 'runnable' } } }, { ...todo, state: 'runnable' }, state.agents[target]);
+    if (!targetCheck.eligible) throw new Error(`Target agent is ineligible: ${targetCheck.reasons.join(', ')}`);
+    const handoffId = id(input.handoff_id ?? input.handoffId ?? `handoff:${todo.id}:${state.fencing_counter + 1}`, 'handoff id');
+    const packet = { version: 1, id: handoffId, todo_id: todo.id, from_agent_id: source, to_agent_id: target, state: 'pending', created_at: new Date().toISOString(), lineage: todo.lineage, context: todo.context, evidence: todo.evidence, authorization: todo.authorization, idempotency_keys: todo.idempotency_keys, source_fencing_token: todo.claim.fencing_token };
+    state.handoffs[handoffId] = packet; todo.state = 'handoff_pending'; todo.handoff_id = handoffId;
+    const audit = event('handoff_created', todo, { handoff_id: handoffId, from_agent_id: source, to_agent_id: target }); todo.ownership_events.push(audit);
+    return { changed: true, output: packet, event: audit };
+  });
+}
+
+export async function decideHandoff(root, input) {
+  return transaction(root, async (state) => {
+    const packet = state.handoffs[id(input.handoff_id ?? input.handoffId, 'handoff id')];
+    if (!packet || packet.state !== 'pending') throw new Error('Pending handoff not found.');
+    const target = id(input.agent_id ?? input.agentId, 'agent id');
+    if (packet.to_agent_id !== target) throw new Error('Only the target agent can decide a handoff.');
+    const todo = state.todos[packet.todo_id];
+    if (input.accept) {
+      const check = await eligibility(root, { ...state, todos: { ...state.todos, [todo.id]: { ...todo, state: 'runnable' } } }, { ...todo, state: 'runnable' }, state.agents[target]);
+      if (!check.eligible) throw new Error(`Target agent is no longer eligible: ${check.reasons.join(', ')}`);
+      const token = ++state.fencing_counter; const now = new Date();
+      todo.state = 'claimed'; todo.claim = { owner: target, fencing_token: token, claimed_at: now.toISOString(), lease_expires_at: new Date(now.getTime() + Number(input.lease_ms ?? input.leaseMs ?? 60_000)).toISOString() };
+      packet.state = 'accepted'; packet.decided_at = now.toISOString(); packet.target_fencing_token = token;
+    } else {
+      packet.state = 'rejected'; packet.decided_at = new Date().toISOString(); packet.reason = input.reason ?? null;
+      if (todo.claim && Date.parse(todo.claim.lease_expires_at) > Date.now()) todo.state = 'claimed'; else { todo.state = 'runnable'; todo.claim = null; }
+    }
+    todo.handoff_id = null; todo.updated_at = new Date().toISOString();
+    const audit = event(input.accept ? 'handoff_accepted' : 'handoff_rejected', todo, { handoff_id: packet.id, from_agent_id: packet.from_agent_id, to_agent_id: target }); todo.ownership_events.push(audit);
+    return { changed: true, output: { packet, todo }, event: audit };
+  });
+}
+
+export async function recoverTodos(root, input = {}) {
+  return transaction(root, async (state) => {
+    const results = []; const now = Number(input.now ?? Date.now()); const audits = [];
+    for (const todo of Object.values(state.todos)) {
+      if (!['claimed', 'handoff_pending'].includes(todo.state) || !todo.claim || Date.parse(todo.claim.lease_expires_at) > now) continue;
+      if (todo.parked && !['runnable', 'resumed'].includes(todo.parked.state)) { results.push({ todo_id: todo.id, outcome: 'parked_not_recovered' }); continue; }
+      const actionBlocks = [];
+      for (const key of todo.idempotency_keys) { const action = await inspectAction(root, key); if (['claimed', 'unknown'].includes(action?.state)) actionBlocks.push(key); }
+      const previous = todo.claim;
+      if (actionBlocks.length) { todo.state = 'blocked'; todo.blocked_reasons = actionBlocks.map((key) => `action_reconciliation:${key}`); }
+      else { todo.state = 'runnable'; todo.blocked_reasons = []; }
+      todo.claim = null; todo.handoff_id = null; todo.updated_at = new Date(now).toISOString();
+      const audit = event('todo_orphan_recovered', todo, { previous_owner: previous.owner, previous_fencing_token: previous.fencing_token, outcome: todo.state }); todo.ownership_events.push(audit); audits.push(audit);
+      results.push({ todo_id: todo.id, outcome: todo.state, blocked_reasons: todo.blocked_reasons });
+    }
+    return { changed: results.length > 0, output: { recovered: results.length, results }, event: audits.length ? { version: 1, event_id: randomUUID(), type: 'recovery_batch', at: new Date().toISOString(), transitions: audits } : null };
+  });
+}
+
+export async function importLegacyTodos(root, input = {}) {
+  const queueRoot = path.join(root, 'runtime', 'loops'); const imported = [];
+  for (const queue of await readdir(queueRoot, { withFileTypes: true }).catch(() => [])) {
+    if (!queue.isDirectory() || queue.name === 'control-plane' || queue.name === 'action-reservations') continue;
+    for (const subdir of ['inbox', 'waiting', 'active']) {
+      const dir = path.join(queueRoot, queue.name, subdir);
+      for (const file of await readdir(dir).catch(() => [])) {
+        if (!file.endsWith('.json')) continue;
+        const legacy = JSON.parse(await readFile(path.join(dir, file), 'utf8'));
+        const legacyId = legacy.id ?? path.basename(file, '.json');
+        try {
+          const todo = await createTodo(root, { id: `legacy:${queue.name}:${legacyId}`, title: legacy.title ?? legacy.goal ?? legacyId, project_id: legacy.projectId ?? null, priority: legacy.priority ?? 0, risk: legacy.risk ?? 'medium', authority_class: legacy.authorityClass ?? 'local', required_capabilities: legacy.requiredCapabilities ?? ['loop-task'], dependencies: legacy.dependencies ?? [], acceptance_contract: legacy.acceptance_contract ?? { source: 'legacy', checks: legacy.checks ?? [] }, evidence_requirements: legacy.evidence_requirements ?? ['legacy-task-result'], quota: 'default', cost: 0, parked: subdir === 'waiting' ? (legacy.parked ?? { state: 'waiting_for_human' }) : null, context: { legacy_queue: queue.name, legacy_file: path.relative(root, path.join(dir, file)) }, lineage: legacy.lineage });
+          imported.push(todo.id);
+        } catch (error) { if (!String(error.message).startsWith('Todo already exists:')) throw error; }
+      }
+    }
+  }
+  return { imported: imported.length, todo_ids: imported };
+}

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.10.0",
+  "version": "0.13.0",
   "private": false,
   "description": "OpenClaw-native loop engineering CLI, templates, and skill for verifiable agent work loops.",
   "type": "module",
@@ -17,10 +17,11 @@
     "run-loop-cron.sh": "scripts/run-loop-cron.sh"
   },
   "scripts": {
+    "check:production-trust": "node --check lib/runtime-adapter-v1.mjs && node --check lib/durable-journal.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",
-    "check": "npm run check:config-drift && npm run check:openclaw-install && npm run check:hermes-install && node --check bin/loop-engineering.mjs && node --check lib/core.mjs && node scripts/final-judgement-self-test.mjs && node scripts/route-notify-self-test.mjs && node scripts/scheduler-heartbeat-self-test.mjs && node bin/loop-engineering.mjs verify --config templates/workspace-health.json --root . && node bin/loop-engineering.mjs queue-status --queue smoke --root . --json >/dev/null && node bin/loop-engineering.mjs project-intake --root /tmp/loop-engineering-check --name smoke-project --brief \"Build a small website project\" --type auto --check \"npm test\" --json >/dev/null && node bin/loop-engineering.mjs project-plan --root /tmp/loop-engineering-check --project smoke-project --force --json >/dev/null && node bin/loop-engineering.mjs project-status --root /tmp/loop-engineering-check --project smoke-project --json >/dev/null && node bin/loop-engineering.mjs queue-scheduler-tick --queue smoke --root /tmp/loop-engineering-check --plan-only --force-due --json >/dev/null && node bin/loop-engineering.mjs queue-scheduler-tick --queue smoke-progress --root /tmp/loop-engineering-check --plan-only --force-due --progress-report --progress-report-when-not-due --json >/dev/null && node bin/loop-engineering.mjs workflow-metrics --queue smoke --root . --json >/dev/null && node bin/loop-engineering.mjs workflow-tune-plan --queue smoke --root . --json >/dev/null && node bin/loop-engineering.mjs code-queue-init --queue smoke-code --root /tmp/loop-engineering-check --force >/dev/null && node bin/loop-engineering.mjs code-worktree-list --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-task-status --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-task-dashboard --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-worktree-cleanup-plan --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-worktree-cleanup --queue smoke-code --root /tmp/loop-engineering-check --confirm-cleanup --json >/dev/null && node bin/loop-engineering.mjs code-patch-verify --patch README.md --root . --json >/dev/null && node bin/loop-engineering.mjs code-patch-apply-plan --patch README.md --json >/dev/null && node bin/loop-engineering.mjs queue-revision-ci-self-test --queue smoke-ci --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs summarize --root . --json >/dev/null && node bin/loop-engineering.mjs doctor --root . --json >/dev/null",
+    "check": "npm run check:config-drift && npm run check:openclaw-install && npm run check:hermes-install && node --check bin/loop-engineering.mjs && node --check lib/core.mjs && node --check lib/action-reservations.mjs && node --check lib/todo-control-plane.mjs && node --check lib/operator-dashboard.mjs && node scripts/action-reservation-self-test.mjs && node scripts/todo-control-plane-self-test.mjs && node scripts/operator-dashboard-self-test.mjs && node scripts/final-judgement-self-test.mjs && node scripts/route-notify-self-test.mjs && node scripts/scheduler-heartbeat-self-test.mjs && node scripts/human-gate-lifecycle-v2-self-test.mjs && node bin/loop-engineering.mjs verify --config templates/workspace-health.json --root . && node bin/loop-engineering.mjs queue-status --queue smoke --root . --json >/dev/null && node bin/loop-engineering.mjs project-intake --root /tmp/loop-engineering-check --name smoke-project --brief \"Build a small website project\" --type auto --check \"npm test\" --json >/dev/null && node bin/loop-engineering.mjs project-plan --root /tmp/loop-engineering-check --project smoke-project --force --json >/dev/null && node bin/loop-engineering.mjs project-status --root /tmp/loop-engineering-check --project smoke-project --json >/dev/null && node bin/loop-engineering.mjs queue-scheduler-tick --queue smoke --root /tmp/loop-engineering-check --plan-only --force-due --json >/dev/null && node bin/loop-engineering.mjs queue-scheduler-tick --queue smoke-progress --root /tmp/loop-engineering-check --plan-only --force-due --progress-report --progress-report-when-not-due --json >/dev/null && node bin/loop-engineering.mjs workflow-metrics --queue smoke --root . --json >/dev/null && node bin/loop-engineering.mjs workflow-tune-plan --queue smoke --root . --json >/dev/null && node bin/loop-engineering.mjs code-queue-init --queue smoke-code --root /tmp/loop-engineering-check --force >/dev/null && node bin/loop-engineering.mjs code-worktree-list --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-task-status --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-task-dashboard --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-worktree-cleanup-plan --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-worktree-cleanup --queue smoke-code --root /tmp/loop-engineering-check --confirm-cleanup --json >/dev/null && node bin/loop-engineering.mjs code-patch-verify --patch README.md --root . --json >/dev/null && node bin/loop-engineering.mjs code-patch-apply-plan --patch README.md --json >/dev/null && node bin/loop-engineering.mjs queue-revision-ci-self-test --queue smoke-ci --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs summarize --root . --json >/dev/null && node bin/loop-engineering.mjs dashboard-health --root . --max-age-seconds 999999999 --json >/dev/null && node bin/loop-engineering.mjs doctor --root . --json >/dev/null",
     "pack:dry": "npm pack --dry-run"
   },
   "engines": {
@@ -31,6 +32,7 @@
     "MIGRATING.md",
     "README.md",
     "bin/",
+    "docs/",
     "lib/",
     "scripts/",
     "templates/",