taskforce-loop-engineering 0.10.0 → 0.12.0

package/lib/action-reservations.mjs

@@ -0,0 +1,196 @@
+import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+
+const ACTION_KINDS = new Set(['paid_api', 'notification', 'deployment', 'process_control', 'publication', 'external_message', 'gated_mutation']);
+const TERMINAL_STATES = new Set(['settled', 'released']);
+
+function requireText(value, label) {
+  if (typeof value !== 'string' || value.trim() === '') throw new Error(`${label} must be a non-empty string.`);
+  return value;
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]));
+  return value;
+}
+
+export function actionRequestFingerprint(request, authorizationScope) {
+  requireText(authorizationScope, 'authorizationScope');
+  return createHash('sha256').update(JSON.stringify(canonical({ request, authorizationScope }))).digest('hex');
+}
+
+function safeKey(key) {
+  requireText(key, 'idempotencyKey');
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,199}$/.test(key)) throw new Error('idempotencyKey contains unsafe characters or is too long.');
+  return key;
+}
+
+function paths(root, key) {
+  const encoded = createHash('sha256').update(safeKey(key)).digest('hex');
+  const dir = path.join(root, 'runtime', 'loops', 'action-reservations');
+  return { dir, file: path.join(dir, `${encoded}.json`), lock: path.join(dir, `${encoded}.lock`) };
+}
+
+async function readJson(file) {
+  return JSON.parse(await readFile(file, 'utf8'));
+}
+
+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 acquireMutex(lock, timeoutMs = 5000) {
+  const deadline = Date.now() + timeoutMs;
+  while (true) {
+    try {
+      await mkdir(lock);
+      await writeFile(path.join(lock, 'owner.json'), JSON.stringify({ pid: process.pid, created_at: new Date().toISOString() }));
+      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 action reservation mutex.');
+      else await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+  }
+}
+
+async function mutate(root, key, operation) {
+  const location = paths(root, key);
+  await mkdir(location.dir, { recursive: true });
+  await acquireMutex(location.lock);
+  try {
+    const record = await readJson(location.file).catch((error) => error.code === 'ENOENT' ? null : Promise.reject(error));
+    const result = await operation(record, location.file);
+    if (result.write) await atomicWrite(location.file, result.record);
+    return result.output ?? result.record;
+  } finally {
+    await rm(location.lock, { recursive: true, force: true });
+  }
+}
+
+export async function reserveAction(root, input) {
+  const key = safeKey(input.idempotencyKey);
+  const kind = requireText(input.kind, 'kind');
+  if (!ACTION_KINDS.has(kind)) throw new Error(`Unsupported action kind: ${kind}`);
+  const scope = requireText(input.authorizationScope, 'authorizationScope');
+  const fingerprint = actionRequestFingerprint(input.request, scope);
+  return mutate(root, key, async (record) => {
+    if (record) {
+      if (record.request_fingerprint !== fingerprint || record.kind !== kind || record.authorization.scope !== scope) {
+        throw new Error('Idempotency key is already bound to a different request or authorization scope.');
+      }
+      return { write: false, output: { created: false, duplicate: true, record } };
+    }
+    const now = new Date().toISOString();
+    const created = {
+      version: 1, idempotency_key: key, kind, state: 'reserved', request_fingerprint: fingerprint,
+      request: canonical(input.request), created_at: now, updated_at: now, fencing_counter: 0, claim: null,
+      authorization: { scope, state: 'reserved', reserved_at: now, consumed_at: null, released_at: null },
+      settlement: null, release: null, reconciliation: null, events: [{ type: 'reserved', at: now }]
+    };
+    return { write: true, record: created, output: { created: true, duplicate: false, record: created } };
+  });
+}
+
+export async function inspectAction(root, idempotencyKey) {
+  const location = paths(root, idempotencyKey);
+  return readJson(location.file).catch((error) => error.code === 'ENOENT' ? null : Promise.reject(error));
+}
+
+export async function claimAction(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.idempotencyKey, async (record) => {
+    if (!record) throw new Error('Action must be reserved before it can be claimed.');
+    if (TERMINAL_STATES.has(record.state)) return { write: false, output: { claimed: false, reason: record.state, record } };
+    const nowMs = Date.now();
+    if (record.state === 'claimed') {
+      if (Date.parse(record.claim.lease_expires_at) > nowMs) return { write: false, output: { claimed: false, reason: 'lease_active', record } };
+      const at = new Date().toISOString();
+      const unknown = { ...record, state: 'unknown', updated_at: at, reconciliation: { required: true, reason: 'stale_lease', marked_at: at }, events: [...record.events, { type: 'outcome_unknown', reason: 'stale_lease', at }] };
+      return { write: true, record: unknown, output: { claimed: false, reason: 'reconcile_required', record: unknown } };
+    }
+    if (record.state === 'unknown') return { write: false, output: { claimed: false, reason: 'reconcile_required', record } };
+    const at = new Date().toISOString();
+    const token = Number(record.fencing_counter) + 1;
+    const claimed = { ...record, state: 'claimed', updated_at: at, fencing_counter: token, claim: { owner: requireText(input.owner, 'owner'), fencing_token: token, claimed_at: at, lease_expires_at: new Date(nowMs + leaseMs).toISOString() }, events: [...record.events, { type: 'claimed', fencing_token: token, at }] };
+    return { write: true, record: claimed, output: { claimed: true, fencingToken: token, record: claimed } };
+  });
+}
+
+function assertFence(record, token) {
+  if (record.state !== 'claimed' || record.claim?.fencing_token !== Number(token)) throw new Error('Stale or invalid fencing token.');
+}
+
+export async function markActionUnknown(root, input) {
+  return mutate(root, input.idempotencyKey, async (record) => {
+    if (!record) throw new Error('Action reservation not found.');
+    assertFence(record, input.fencingToken);
+    const at = new Date().toISOString();
+    const next = { ...record, state: 'unknown', updated_at: at, reconciliation: { required: true, reason: input.reason ?? 'upstream_outcome_unknown', marked_at: at }, events: [...record.events, { type: 'outcome_unknown', reason: input.reason ?? 'upstream_outcome_unknown', at }] };
+    return { write: true, record: next };
+  });
+}
+
+export async function settleAction(root, input) {
+  return mutate(root, input.idempotencyKey, async (record) => {
+    if (!record) throw new Error('Action reservation not found.');
+    if (record.state === 'settled') return { write: false, output: { settled: false, duplicate: true, record } };
+    assertFence(record, input.fencingToken);
+    const at = new Date().toISOString();
+    const next = { ...record, state: 'settled', updated_at: at, authorization: { ...record.authorization, state: 'consumed', consumed_at: at }, settlement: { status: 'succeeded', evidence: input.evidence ?? null, settled_at: at, fencing_token: Number(input.fencingToken) }, reconciliation: null, events: [...record.events, { type: 'settled', fencing_token: Number(input.fencingToken), at }] };
+    return { write: true, record: next, output: { settled: true, duplicate: false, record: next } };
+  });
+}
+
+export async function releaseAction(root, input) {
+  return mutate(root, input.idempotencyKey, async (record) => {
+    if (!record) throw new Error('Action reservation not found.');
+    if (record.state === 'settled') throw new Error('Consumed authorization cannot be released.');
+    if (record.state === 'released') return { write: false, output: { released: false, duplicate: true, record } };
+    if (record.state === 'claimed') assertFence(record, input.fencingToken);
+    if (record.state === 'unknown') throw new Error('Unknown upstream outcome must be reconciled before release.');
+    const at = new Date().toISOString();
+    const next = { ...record, state: 'released', updated_at: at, authorization: { ...record.authorization, state: 'released', released_at: at }, release: { reason: requireText(input.reason, 'reason'), evidence: input.evidence ?? null, released_at: at }, events: [...record.events, { type: 'released', at }] };
+    return { write: true, record: next, output: { released: true, duplicate: false, record: next } };
+  });
+}
+
+export async function reconcileAction(root, input) {
+  return mutate(root, input.idempotencyKey, async (record) => {
+    if (!record) throw new Error('Action reservation not found.');
+    if (record.state !== 'unknown') throw new Error('Only an unknown action outcome can be reconciled.');
+    if (!['accepted', 'not_accepted'].includes(input.outcome)) throw new Error('outcome must be accepted or not_accepted.');
+    const at = new Date().toISOString();
+    if (input.outcome === 'accepted') {
+      const next = { ...record, state: 'settled', updated_at: at, authorization: { ...record.authorization, state: 'consumed', consumed_at: at }, settlement: { status: 'succeeded', evidence: input.evidence ?? null, settled_at: at, reconciled: true }, reconciliation: { required: false, outcome: 'accepted', evidence: input.evidence ?? null, reconciled_at: at }, events: [...record.events, { type: 'reconciled_accepted', at }] };
+      return { write: true, record: next };
+    }
+    const next = { ...record, state: 'reserved', updated_at: at, claim: null, reconciliation: { required: false, outcome: 'not_accepted', evidence: input.evidence ?? null, reconciled_at: at }, events: [...record.events, { type: 'reconciled_not_accepted', at }] };
+    return { write: true, record: next };
+  });
+}
+
+export const actionAdapters = Object.freeze(Object.fromEntries(['paid_api', 'notification', 'deployment'].map((kind) => [kind, Object.freeze({
+  kind,
+  reserve: (root, input) => reserveAction(root, { ...input, kind }),
+  claim: claimAction,
+  markUnknown: markActionUnknown,
+  settle: settleAction,
+  release: releaseAction,
+  reconcile: reconcileAction,
+  inspect: inspectAction
+})])));
+
+export async function migrateLegacyActionArtifact(root, legacy) {
+  const key = legacy.idempotency_key ?? legacy.idempotencyKey;
+  const request = legacy.request ?? { legacy_artifact: legacy.source ?? 'unknown' };
+  const scope = legacy.authorization_scope ?? legacy.authorization?.scope ?? 'legacy:unscoped';
+  return reserveAction(root, { idempotencyKey: key, kind: legacy.kind ?? 'gated_mutation', request, authorizationScope: scope });
+}

package/lib/core.mjs

@@ -947,6 +947,155 @@ export async function ensureQueueDirs(root, queue) {
     .map((subdir) => mkdir(queueSubdirFor(root, queue, subdir), { recursive: true })));
 }
 
+const PARKED_WAIT_KINDS = new Set(['human_input', 'external_condition']);
+
+function normalizeParkPolicy(value = {}) {
+  const positive = (input, fallback) => Number.isFinite(Number(input)) && Number(input) > 0 ? Number(input) : fallback;
+  return {
+    timeoutMs: positive(value.timeoutMs, 24 * 60 * 60 * 1000),
+    reminderIntervalMs: positive(value.reminderIntervalMs, 60 * 60 * 1000),
+    escalationIntervalMs: positive(value.escalationIntervalMs, 24 * 60 * 60 * 1000),
+    maxReminders: Math.max(0, Number.isInteger(Number(value.maxReminders)) ? Number(value.maxReminders) : 3)
+  };
+}
+
+export async function parkQueueTask(root, options = {}) {
+  const queue = normalizeLoopId(options.queue);
+  const taskId = safeTaskId(options.taskId);
+  const kind = String(options.kind ?? 'external_condition');
+  if (!PARKED_WAIT_KINDS.has(kind)) throw new Error(`Unsupported wait kind: ${kind}`);
+  const found = await findTaskFile(root, queue, taskId, ['inbox', 'active', 'waiting', 'failed']);
+  if (!found) throw new Error(`Task not found: ${taskId}`);
+  const task = await readJson(found.file);
+  if (found.subdir === 'waiting' && task.parked?.state) return { outcome: 'already_parked', task, file: path.relative(root, found.file) };
+  const now = options.now ? new Date(options.now) : new Date();
+  if (!Number.isFinite(now.getTime())) throw new Error(`Invalid park time: ${options.now}`);
+  const waitId = options.waitId ? normalizeLoopId(options.waitId) : `${taskId}.${isoStamp(now)}`;
+  const parked = {
+    version: 2,
+    wait_id: waitId,
+    kind,
+    state: kind === 'human_input' ? 'waiting_for_human' : 'external_condition_wait',
+    reason: String(options.reason ?? 'Waiting for an external condition.'),
+    parked_at: now.toISOString(),
+    policy: normalizeParkPolicy(options.policy),
+    reminder_count: 0,
+    escalation_count: 0,
+    last_notification_at: null,
+    recovery: {
+      verification_required: true,
+      signal_sha256: null,
+      verified_at: null
+    },
+    execution_boundary: {
+      key: String(options.executionKey ?? waitId),
+      action_executed: Boolean(options.actionExecuted),
+      resumed_at: null
+    },
+    authorization: options.authorization ?? task.parked?.authorization ?? null
+  };
+  const waitingFile = path.join(queueSubdirFor(root, queue, 'waiting'), path.basename(found.file));
+  await writeJson(waitingFile, { ...task, status: 'parked', parked });
+  if (path.resolve(found.file) !== path.resolve(waitingFile)) await rm(found.file, { force: true });
+  return { outcome: 'parked', task: { ...task, status: 'parked', parked }, file: path.relative(root, waitingFile) };
+}
+
+function parkedDisplayState(parked, now = Date.now()) {
+  if (!parked) return 'waiting';
+  const timedOut = now >= Date.parse(parked.parked_at) + Number(parked.policy?.timeoutMs ?? Infinity);
+  if (timedOut || Number(parked.escalation_count ?? 0) > 0) return 'timed_out_or_escalated';
+  return parked.state ?? (parked.kind === 'human_input' ? 'waiting_for_human' : 'external_condition_wait');
+}
+
+export async function tickParkedTasks(root, options = {}) {
+  const queue = normalizeLoopId(options.queue);
+  const now = options.now ? new Date(options.now) : new Date();
+  if (!Number.isFinite(now.getTime())) throw new Error(`Invalid tick time: ${options.now}`);
+  if (!options.notifyCommand && !options.dryRun) throw new Error('queue-wait-tick requires --notify-command unless --dry-run is used.');
+  const evidenceDir = path.join(queueDirFor(root, queue), 'wait-notifications');
+  await mkdir(evidenceDir, { recursive: true });
+  const results = [];
+  for (const file of await listJson(queueSubdirFor(root, queue, 'waiting'))) {
+    const full = path.join(queueSubdirFor(root, queue, 'waiting'), file);
+    const task = await readJson(full);
+    if (!task.parked?.wait_id) continue;
+    const parked = task.parked;
+    const policy = normalizeParkPolicy(parked.policy);
+    const elapsed = now.getTime() - Date.parse(parked.parked_at);
+    const lastAt = parked.last_notification_at ? Date.parse(parked.last_notification_at) : 0;
+    const notificationElapsed = lastAt ? now.getTime() - lastAt : Infinity;
+    const timedOut = elapsed >= policy.timeoutMs;
+    const type = timedOut && notificationElapsed >= policy.escalationIntervalMs
+      ? 'escalation'
+      : Number(parked.reminder_count ?? 0) < policy.maxReminders && notificationElapsed >= policy.reminderIntervalMs
+        ? 'reminder'
+        : null;
+    if (!type) {
+      results.push({ taskId: task.id, waitId: parked.wait_id, outcome: 'throttled', state: parkedDisplayState(parked, now.getTime()) });
+      continue;
+    }
+    const sequence = type === 'reminder' ? Number(parked.reminder_count ?? 0) + 1 : Number(parked.escalation_count ?? 0) + 1;
+    const evidenceFile = path.join(evidenceDir, `${safeTaskId(task.id)}.${normalizeLoopId(parked.wait_id)}.${type}.${sequence}.json`);
+    if (await exists(evidenceFile)) {
+      results.push({ taskId: task.id, waitId: parked.wait_id, outcome: 'already_notified', type, sequence });
+      continue;
+    }
+    const message = `Loop task parked (${parked.kind}): ${task.title}\nreason: ${parked.reason}\nstate: ${timedOut ? 'timed_out_or_escalated' : parked.state}\nwait: ${parked.wait_id}`;
+    if (options.dryRun) {
+      results.push({ taskId: task.id, waitId: parked.wait_id, outcome: 'dry_run', type, sequence, message });
+      continue;
+    }
+    // Claim the sequence before the external send. After a crash, a later tick
+    // observes this durable boundary and will not duplicate the notification.
+    await writeJson(evidenceFile, { version: 1, queue, task_id: task.id, wait_id: parked.wait_id, type, sequence, status: 'sending', claimed_at: now.toISOString() });
+    const result = await runCommand(`${options.notifyCommand} ${shellQuote(message)}`, { cwd: root, timeoutMs: options.timeoutMs ?? 60_000 });
+    if (result.exitCode !== 0) {
+      await writeJson(evidenceFile, { version: 1, queue, task_id: task.id, wait_id: parked.wait_id, type, sequence, status: 'failed', attempted_at: now.toISOString(), result: compactCommandResult(result) });
+      results.push({ taskId: task.id, waitId: parked.wait_id, outcome: 'failed', type, result: compactCommandResult(result) });
+      continue;
+    }
+    const nextParked = {
+      ...parked,
+      policy,
+      state: timedOut ? 'timed_out_or_escalated' : parked.state,
+      reminder_count: Number(parked.reminder_count ?? 0) + (type === 'reminder' ? 1 : 0),
+      escalation_count: Number(parked.escalation_count ?? 0) + (type === 'escalation' ? 1 : 0),
+      last_notification_at: now.toISOString()
+    };
+    await writeJson(evidenceFile, { version: 1, queue, task_id: task.id, wait_id: parked.wait_id, type, sequence, status: 'sent', notified_at: now.toISOString(), result: compactCommandResult(result) });
+    await writeJson(full, { ...task, parked: nextParked });
+    results.push({ taskId: task.id, waitId: parked.wait_id, outcome: 'sent', type, sequence, evidence: path.relative(root, evidenceFile) });
+  }
+  return { queue, inspected: results.length, sent: results.filter((item) => item.outcome === 'sent').length, failed: results.filter((item) => item.outcome === 'failed').length, results };
+}
+
+export async function resumeParkedTask(root, options = {}) {
+  const queue = normalizeLoopId(options.queue);
+  const taskId = safeTaskId(options.taskId);
+  if (!options.verified || typeof options.recoverySignal !== 'string' || !options.recoverySignal.trim()) {
+    throw new Error('queue-wait-resume requires --verified and --recovery-signal.');
+  }
+  const found = await findTaskFile(root, queue, taskId, ['waiting', 'inbox']);
+  if (!found) throw new Error(`Parked task not found: ${taskId}`);
+  const task = await readJson(found.file);
+  if (found.subdir === 'inbox' && task.parked?.execution_boundary?.resumed_at) {
+    return { outcome: 'already_resumed', task, file: path.relative(root, found.file) };
+  }
+  if (!task.parked?.wait_id) throw new Error(`Task is not parked: ${taskId}`);
+  const signalSha256 = createHash('sha256').update(options.recoverySignal.trim()).digest('hex');
+  const now = options.now ? new Date(options.now) : new Date();
+  const resumed = {
+    ...task.parked,
+    state: 'runnable',
+    recovery: { ...task.parked.recovery, signal_sha256: signalSha256, verified_at: now.toISOString() },
+    execution_boundary: { ...task.parked.execution_boundary, resumed_at: now.toISOString() }
+  };
+  const inboxFile = path.join(queueSubdirFor(root, queue, 'inbox'), path.basename(found.file));
+  await writeJson(inboxFile, { ...task, status: 'queued', parked: resumed, requeuedAt: now.toISOString(), requeuedFrom: 'waiting' });
+  if (path.resolve(found.file) !== path.resolve(inboxFile)) await rm(found.file, { force: true });
+  return { outcome: 'verified_and_requeued', signalSha256, task: { ...task, status: 'queued', parked: resumed }, file: path.relative(root, inboxFile) };
+}
+
 export function taskIdForTitle(title, date = new Date()) {
   const slug = (title || 'task')
     .toLowerCase()
@@ -1520,7 +1669,7 @@ export function classifyLoopMessage(message) {
   const mentionsLoop = /(loop engineering|loop-engineering|task-runner|队列|queue|\bloop\b)/i.test(text);
   const statusIntent = mentionsLoop
     && /(查|看|检查|审计|状态|情况|进度|怎么样|为什么|失败|报错|健康|health|status|progress|audit|summar)/i.test(text);
-  const executeIntent = /(走\s*loop|继续(?:当前|这个)?\s*loop|给(?:当前|这个)?\s*loop\s*(?:补充|增加|加)|用\s*loop.*(?:解决|执行|完成|处理|修复|对齐|补齐|增强|开发|构建|绕过|避开|跳过|bypass|evade)|丢进.*loop|入队|enqueue|run[- ]?queue|立刻执行|立即执行|use\s+(?:loop engineering|the\s+loop)|run\s+(?:this|it|the\s+task).*(?:through|with)\s+(?:loop engineering|the\s+loop)|continue\s+(?:the\s+)?(?:current\s+)?loop|amend\s+(?:the\s+)?(?:current\s+)?loop)/i.test(text);
+  const executeIntent = /(走\s*loop|继续(?:当前|这个)?\s*loop|给(?:当前|这个)?\s*loop\s*(?:补充|增加|加)|用\s*loop.*(?:解决|执行|完成|处理|修复|对齐|补齐|增强|开发|构建|绕过|避开|跳过|bypass|evade)|(?:继续|开始|推进).*(?:开发|建设|完善|增强).*(?:loop engineering|loop-engineering|task-runner)|丢进.*loop|入队|enqueue|run[- ]?queue|立刻执行|立即执行|use\s+(?:loop engineering|the\s+loop)|run\s+(?:this|it|the\s+task).*(?:through|with)\s+(?:loop engineering|the\s+loop)|continue\s+(?:the\s+)?(?:current\s+)?loop|amend\s+(?:the\s+)?(?:current\s+)?loop)/i.test(text);
   const intent = executeIntent ? 'execute' : statusIntent ? 'status' : 'direct';
   return {
     intent,
@@ -3241,11 +3390,29 @@ export async function queueStatus(root, queue) {
   const activeFiles = await listJson(queueSubdirFor(root, queue, 'active'));
   const lock = await readQueueLock(root, queue);
   const lockOwnerAlive = queueLockOwnerAlive(lock);
+  const waitingTasks = [];
+  for (const file of await listJson(queueSubdirFor(root, queue, 'waiting'))) {
+    const task = await readJson(path.join(queueSubdirFor(root, queue, 'waiting'), file));
+    waitingTasks.push({
+      taskId: task.id,
+      status: task.status,
+      waitId: task.parked?.wait_id ?? task.waitingGateId ?? null,
+      waitKind: task.parked?.kind ?? (task.status === 'waiting_for_human' ? 'human_input' : null),
+      displayState: task.parked ? parkedDisplayState(task.parked) : task.status,
+      parkedAt: task.parked?.parked_at ?? task.waitingSince ?? null,
+      reminderCount: Number(task.parked?.reminder_count ?? 0),
+      escalationCount: Number(task.parked?.escalation_count ?? 0),
+      authorizationState: task.parked?.authorization?.state ?? null,
+      actionExecuted: Boolean(task.parked?.execution_boundary?.action_executed)
+    });
+  }
   return {
     queue,
     queued: (await listJson(queueSubdirFor(root, queue, 'inbox'))).length,
     active: activeFiles.length,
-    waiting: (await listJson(queueSubdirFor(root, queue, 'waiting'))).length,
+    waiting: waitingTasks.length,
+    waitingStates: waitingTasks.reduce((counts, task) => ({ ...counts, [task.displayState]: (counts[task.displayState] ?? 0) + 1 }), {}),
+    waitingTasks,
     done: (await listJson(queueSubdirFor(root, queue, 'done'))).length,
     failed: (await listJson(queueSubdirFor(root, queue, 'failed'))).length,
     canceled: (await listJson(queueSubdirFor(root, queue, 'canceled'))).length,

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 };
+}