taskforce-loop-engineering 0.10.0 → 0.12.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskforce-loop-engineering",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "private": false,
   "description": "OpenClaw-native loop engineering CLI, templates, and skill for verifiable agent work loops.",
   "type": "module",
@@ -20,7 +20,7 @@
     "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 +31,7 @@
     "MIGRATING.md",
     "README.md",
     "bin/",
+    "docs/",
     "lib/",
     "scripts/",
     "templates/",

package/scripts/action-reservation-self-test.mjs

@@ -0,0 +1,65 @@
+import assert from 'node:assert/strict';
+import { mkdtemp } from 'node:fs/promises';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import {
+  actionAdapters,
+  claimAction,
+  inspectAction,
+  markActionUnknown,
+  migrateLegacyActionArtifact,
+  reconcileAction,
+  releaseAction,
+  reserveAction,
+  settleAction
+} from '../lib/action-reservations.mjs';
+
+const root = await mkdtemp(path.join(tmpdir(), 'loop-action-reservation-'));
+const base = { idempotencyKey: 'paid:task-1:step-1', kind: 'paid_api', authorizationScope: 'approval:task-1:provider-call', request: { model: 'mock', promptHash: 'abc', cents: 4 } };
+
+const reserved = await reserveAction(root, base);
+assert.equal(reserved.created, true);
+assert.equal((await reserveAction(root, base)).duplicate, true);
+await assert.rejects(() => reserveAction(root, { ...base, request: { ...base.request, cents: 5 } }), /different request/);
+
+// Concurrent workers get one atomic lease and one fencing token.
+const claims = await Promise.all(Array.from({ length: 12 }, (_, i) => claimAction(root, { idempotencyKey: base.idempotencyKey, owner: `worker-${i}`, leaseMs: 1000 })));
+assert.equal(claims.filter((item) => item.claimed).length, 1);
+const winner = claims.find((item) => item.claimed);
+await assert.rejects(() => settleAction(root, { idempotencyKey: base.idempotencyKey, fencingToken: winner.fencingToken + 1 }), /fencing token/);
+assert.equal((await settleAction(root, { idempotencyKey: base.idempotencyKey, fencingToken: winner.fencingToken, evidence: { upstreamId: 'mock-1' } })).settled, true);
+assert.equal((await settleAction(root, { idempotencyKey: base.idempotencyKey, fencingToken: winner.fencingToken })).duplicate, true);
+assert.equal((await inspectAction(root, base.idempotencyKey)).authorization.state, 'consumed');
+await assert.rejects(() => releaseAction(root, { idempotencyKey: base.idempotencyKey, reason: 'late release' }), /cannot be released/);
+
+// Crash before send: an expired claim becomes unknown, never blindly claimable.
+const beforeSend = { ...base, idempotencyKey: 'paid:crash-before-send' };
+await reserveAction(root, beforeSend);
+await claimAction(root, { idempotencyKey: beforeSend.idempotencyKey, owner: 'crashed', leaseMs: 1 });
+await new Promise((resolve) => setTimeout(resolve, 5));
+assert.equal((await claimAction(root, { idempotencyKey: beforeSend.idempotencyKey, owner: 'recovery', leaseMs: 10 })).reason, 'reconcile_required');
+await reconcileAction(root, { idempotencyKey: beforeSend.idempotencyKey, outcome: 'not_accepted', evidence: { local: 'adapter_not_invoked' } });
+assert.equal((await claimAction(root, { idempotencyKey: beforeSend.idempotencyKey, owner: 'recovery', leaseMs: 100 })).claimed, true);
+
+// Crash after upstream acceptance: reconciliation settles without another send/charge.
+const afterAcceptance = { ...base, idempotencyKey: 'paid:crash-after-acceptance' };
+await reserveAction(root, afterAcceptance);
+const afterClaim = await claimAction(root, { idempotencyKey: afterAcceptance.idempotencyKey, owner: 'worker', leaseMs: 100 });
+await markActionUnknown(root, { idempotencyKey: afterAcceptance.idempotencyKey, fencingToken: afterClaim.fencingToken, reason: 'accepted_before_local_commit' });
+await reconcileAction(root, { idempotencyKey: afterAcceptance.idempotencyKey, outcome: 'accepted', evidence: { upstreamId: 'mock-accepted' } });
+assert.equal((await claimAction(root, { idempotencyKey: afterAcceptance.idempotencyKey, owner: 'retry' })).reason, 'settled');
+
+// Notification adapter suppresses duplicates, and an unused reservation can release authorization.
+await actionAdapters.notification.reserve(root, { idempotencyKey: 'notify:task-1:terminal', authorizationScope: 'task-1:source-chat', request: { target: 'mock-chat', digest: 'done' } });
+const notifyDuplicate = await actionAdapters.notification.reserve(root, { idempotencyKey: 'notify:task-1:terminal', authorizationScope: 'task-1:source-chat', request: { target: 'mock-chat', digest: 'done' } });
+assert.equal(notifyDuplicate.duplicate, true);
+const releasable = { ...base, idempotencyKey: 'deploy:cancelled', kind: 'deployment', authorizationScope: 'approval:deploy-staging' };
+await reserveAction(root, releasable);
+assert.equal((await releaseAction(root, { idempotencyKey: releasable.idempotencyKey, reason: 'operator_cancelled', evidence: { ticket: 'mock' } })).record.authorization.state, 'released');
+
+// Legacy artifacts are imported without changing their logical identity.
+const migrated = await migrateLegacyActionArtifact(root, { idempotency_key: 'legacy:notification:1', kind: 'notification', authorization_scope: 'legacy:chat', request: { digest: 'old' } });
+assert.equal(migrated.created, true);
+assert.equal((await migrateLegacyActionArtifact(root, { idempotency_key: 'legacy:notification:1', kind: 'notification', authorization_scope: 'legacy:chat', request: { digest: 'old' } })).duplicate, true);
+
+console.log(JSON.stringify({ status: 'ok', assertions: 'reservation, fingerprint, concurrency, fencing, crash recovery, reconciliation, authorization, release, adapters, migration' }));

package/scripts/human-gate-lifecycle-v2-self-test.mjs

@@ -0,0 +1,81 @@
+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,
+  parkQueueTask,
+  queueStatus,
+  queueSubdirFor,
+  readJson,
+  resumeParkedTask,
+  tickParkedTasks,
+  writeJson
+} from '../lib/core.mjs';
+
+const root = await mkdtemp(path.join(tmpdir(), 'loop-human-gate-v2-'));
+const queue = 'vps-fixture';
+const taskId = 'vps-down-ssh-banner-timeout';
+const taskFile = path.join(queueSubdirFor(root, queue, 'inbox'), `${taskId}.json`);
+
+try {
+  await ensureQueueDirs(root, queue);
+  await writeJson(taskFile, { version: 1, id: taskId, title: 'Recover provider VPS', status: 'queued' });
+  const parked = await parkQueueTask(root, {
+    queue,
+    taskId,
+    kind: 'external_condition',
+    reason: 'VPS is down; SSH banner timed out.',
+    now: '2026-08-13T00:00:00.000Z',
+    executionKey: 'provider-call-1',
+    authorization: { state: 'unconsumed', scope: 'provider_call' },
+    policy: { timeoutMs: 2_000, reminderIntervalMs: 1_000, escalationIntervalMs: 2_000, maxReminders: 1 }
+  });
+  assert.equal(parked.outcome, 'parked');
+  assert.equal(parked.task.parked.authorization.state, 'unconsumed');
+  assert.equal(parked.task.parked.execution_boundary.action_executed, false);
+
+  const status = await queueStatus(root, queue);
+  assert.equal(status.waitingStates.timed_out_or_escalated, 1);
+  assert.equal(status.waitingTasks[0].waitKind, 'external_condition');
+  assert.equal(status.waitingTasks[0].authorizationState, 'unconsumed');
+
+  const notifyCommand = 'node -e "process.exit(0)"';
+  const reminder = await tickParkedTasks(root, { queue, now: '2026-08-13T00:00:01.000Z', notifyCommand });
+  assert.equal(reminder.results[0].type, 'reminder');
+  const duplicateTick = await tickParkedTasks(root, { queue, now: '2026-08-13T00:00:01.000Z', notifyCommand });
+  assert.equal(duplicateTick.results[0].outcome, 'throttled');
+  const escalation = await tickParkedTasks(root, { queue, now: '2026-08-13T00:00:03.000Z', notifyCommand });
+  assert.equal(escalation.results[0].type, 'escalation');
+
+  await assert.rejects(
+    resumeParkedTask(root, { queue, taskId, recoverySignal: 'ssh banner verified' }),
+    /--verified/
+  );
+  const resumed = await resumeParkedTask(root, {
+    queue,
+    taskId,
+    verified: true,
+    recoverySignal: 'probe=vps-1;ssh_banner=verified',
+    now: '2026-08-13T00:00:04.000Z'
+  });
+  assert.equal(resumed.outcome, 'verified_and_requeued');
+  assert.equal(resumed.task.parked.state, 'runnable');
+  assert.equal(resumed.task.parked.authorization.state, 'unconsumed');
+  assert.equal(resumed.task.parked.execution_boundary.action_executed, false);
+  assert.ok(resumed.signalSha256);
+
+  const afterRestart = await resumeParkedTask(root, {
+    queue,
+    taskId,
+    verified: true,
+    recoverySignal: 'probe=vps-1;ssh_banner=verified'
+  });
+  assert.equal(afterRestart.outcome, 'already_resumed');
+  const durable = await readJson(path.join(queueSubdirFor(root, queue, 'inbox'), `${taskId}.json`));
+  assert.equal(durable.parked.execution_boundary.key, 'provider-call-1');
+  assert.equal(durable.parked.authorization.state, 'unconsumed');
+  console.log('human-gate-lifecycle-v2 self-test: ok');
+} finally {
+  await rm(root, { recursive: true, force: true });
+}

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

@@ -0,0 +1,74 @@
+import assert from 'node:assert/strict';
+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';
+
+const root = await mkdtemp(path.join(tmpdir(), 'loop-dashboard-'));
+const loops = path.join(root, 'runtime', 'loops');
+await mkdir(path.join(loops, 'control-plane'), { recursive: true });
+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 });
+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' } },
+  handoffs: { h: { id: 'h', todo_id: 'leased', from_agent_id: 'a', to_agent_id: 'b', state: 'pending', created_at: now } },
+  todos: {
+    human: { version: 2, id: 'human', title: '<img src=x onerror=alert(1)>', state: 'runnable', priority: 2, risk: 'medium', authority_class: 'local', required_capabilities: [], acceptance_contract: { checks: ['ok'] }, evidence_requirements: ['test'], cost_envelope: { quota: 'credits', amount: 2 }, parked: { state: 'waiting_for_human', gate_id: 'g1', secret_input: 'hide' }, blocked_reasons: [], claim: null, lineage: { root_todo_id: 'human' }, evidence: [], idempotency_keys: [], created_at: now, updated_at: now },
+    leased: { version: 2, id: 'leased', title: 'Lease expired', state: 'claimed', priority: 1, authority_class: 'local', required_capabilities: [], acceptance_contract: {}, evidence_requirements: ['lease'], cost_envelope: { quota: 'credits', amount: 3 }, claim: { owner: 'a', fencing_token: 7, claimed_at: '2026-08-13T15:00:00.000Z', lease_expires_at: '2026-08-13T15:01:00.000Z' }, blocked_reasons: [], lineage: {}, evidence: [], idempotency_keys: ['paid:x'], created_at: now, updated_at: now }
+  }
+};
+await writeFile(path.join(loops, 'control-plane', 'state.json'), JSON.stringify(control));
+await writeFile(path.join(loops, 'action-reservations', 'x.json'), JSON.stringify({ version: 1, idempotency_key: 'paid:x', kind: 'paid_api', state: 'unknown', request: { api_key: 'hide', prompt: '<script>x</script>' }, request_fingerprint: 'abc', authorization: { scope: 'paid', credential: 'hide' }, claim: null, reconciliation: { required: true, reason: 'stale_lease' }, created_at: now, updated_at: now }));
+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' }));
+
+const before = await stat(path.join(loops, 'control-plane', 'state.json'));
+const first = await buildOperatorProjection(root, { now });
+const second = await buildOperatorProjection(root, { now });
+const after = await stat(path.join(loops, 'control-plane', 'state.json'));
+assert.deepEqual(first, second, 'fixed-time projections are deterministic');
+assert.equal(before.mtimeMs, after.mtimeMs, 'projection does not mutate source state');
+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.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]');
+assert.equal(JSON.stringify(first).includes('never-show'), false);
+assert.equal(JSON.stringify(first).includes('hidden'), false);
+assert.equal(first.health.status, 'degraded');
+assert.equal(filterProjection(first, { state: 'waiting_for_human', query: 'img' }).todos.length, 1);
+assert.equal(dashboardHealth(first, { maxAgeSeconds: 1 }).stale, false);
+
+const output = path.join(root, 'export');
+await exportDashboard(root, output, { now });
+assert.match(await readFile(path.join(output, 'index.html'), 'utf8'), /projection\.json/);
+assert.equal(JSON.parse(await readFile(path.join(output, 'projection.json'), 'utf8')).schema_version, '1.0.0');
+await assert.rejects(() => createDashboardServer(root, { host: '0.0.0.0' }), /requires --allow-non-loopback/);
+
+const server = await createDashboardServer(root, { host: '127.0.0.1', port: 0 });
+const address = server.address(); const base = `http://127.0.0.1:${address.port}`;
+try {
+  const overview = await fetch(`${base}/api/v1/overview?state=waiting_for_human`).then((response) => response.json());
+  assert.equal(overview.todos.length, 1);
+  const detail = await fetch(`${base}/api/v1/todos/human`).then((response) => response.json());
+  assert.match(detail.title, /onerror/);
+  const page = await fetch(base).then((response) => response.text());
+  assert.doesNotMatch(page, /<img src=x/);
+  assert.equal((await fetch(`${base}/api/v1/todos/%2e%2e%2fsecret`)).status, 400);
+  assert.equal((await fetch(`${base}/api/v1/unknown`)).status, 404);
+  assert.equal((await fetch(`${base}/api/v1/overview`, { method: 'POST' })).status, 405);
+} finally { await new Promise((resolve) => server.close(resolve)); }
+
+// Large queue stays dependency-light and completes within a generous local budget.
+await mkdir(path.join(loops, 'large', 'inbox'), { recursive: true });
+await Promise.all(Array.from({ length: 500 }, (_, i) => writeFile(path.join(loops, 'large', 'inbox', `${i}.json`), JSON.stringify({ id: `bulk-${i}`, title: `Task ${i}`, state: 'runnable' }))));
+const started = performance.now(); const large = await buildOperatorProjection(root, { now });
+assert.equal(large.queues.find((queue) => queue.id === 'large').tasks.length, 500);
+assert.ok(performance.now() - started < 5000, '500 task projection should finish under 5 seconds');
+
+console.log(JSON.stringify({ status: 'ok', assertions: 'empty-compatible, legacy, malformed, deterministic, read-only, P0 gates, P1 reconciliation, P2 lease/handoff, redaction, XSS, traversal, bind safety, export, restart-safe server, large queue performance' }));

package/scripts/route-notify-self-test.mjs

@@ -57,6 +57,7 @@ assert.deepEqual(classifyLoopMessage('用 loop engineering 把现有的 growth o
 assert.equal(classifyLoopMessage('Use Loop Engineering to fix this issue.').intent, 'execute');
 assert.equal(classifyLoopMessage('Run this through Loop Engineering.').intent, 'execute');
 assert.equal(classifyLoopMessage('Continue the current loop with this amendment: add English examples.').intent, 'execute');
+assert.equal(classifyLoopMessage('我们继续开发我们的loop engineering').intent, 'execute');
 
 const routed = await routeLoopMessage(root, {
   route: true,