taskforce-loop-engineering 0.15.13 → 0.15.14

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.15.14 - 2026-08-30
+
+- Add one authoritative cross-interface Human Gate command core for Dashboard and trusted chat adapters, with strict source binding, generation fencing, idempotency receipts, confirmation escalation, and fail-closed handling of ordinary chat.
+- Upgrade quota checks into a runtime decision engine covering token, time, cost, and turn budgets, verified-only spend, idle-free accounting, scheduler hints, and audited safe fallback work.
+- Productize the durable multi-agent control plane with agent registration, explainable matching, targeted wakeups, peer collaboration, fenced handoffs, conflict/orphan governance, and cross-runtime conformance evidence.
+- Extend the operator workspace, OpenClaw installer, doctor, smoke, and bundled skill to expose and verify the new gate, quota, team, and project-control capabilities.
+
 ## 0.15.13 - 2026-08-28
 
 - Add the project-first read-only operator workspace with terminal contracts, milestone/project status separation, revision lineage, human gates, external-action reservations, and acceptance/final-judge timelines.

package/bin/loop-engineering.mjs

@@ -81,6 +81,7 @@ import {
   settleAction
 } from '../lib/action-reservations.mjs';
 import {
+  acknowledgeWake,
   claimTodo,
   createTodo,
   decideHandoff,
@@ -88,10 +89,15 @@ import {
   importLegacyTodos,
   inspectTodo,
   listTodos,
+  matchTodo,
   recoverTodos,
   registerAgent,
+  resolveOwnershipConflict,
   releaseTodo,
-  renewTodo
+  renewTodo,
+  sendPeerMessage,
+  teamWorkbench,
+  wakeAgent
 } from '../lib/todo-control-plane.mjs';
 import {
   buildOperatorProjection,
@@ -146,6 +152,7 @@ function parseArgs(argv) {
     else if (a === '--handoff-id') args.handoffId = argv[++i];
     else if (a === '--todo-json') args.todoJson = argv[++i];
     else if (a === '--agent-json') args.agentJson = argv[++i];
+    else if (a === '--payload-json') args.payloadJson = argv[++i];
     else if (a === '--state') args.todoState = argv[++i];
     else if (a === '--run-id') args.runId = argv[++i];
     else if (a === '--output') args.output = argv[++i];
@@ -5653,7 +5660,7 @@ async function main() {
   if (command === 'summarize') return summarizeCommand(args);
   if (command === 'doctor') return doctorCommand(args);
   if (command.startsWith('dashboard-')) return dashboardCommand(command, args);
-  if (command === 'agent-register' || command.startsWith('todo-')) return todoControlPlaneCommand(command, args);
+  if (['agent-register', 'agent-wake', 'agent-wake-ack', 'peer-message', 'team-workbench'].includes(command) || command.startsWith('todo-')) return todoControlPlaneCommand(command, args);
   if (command.startsWith('action-')) return actionReservationCommand(command, args);
   if (command === 'repair-plan') return repairPlanCommand(args);
   if (command === 'project-intake') return projectIntakeCommand(args);
@@ -5767,6 +5774,12 @@ async function todoControlPlaneCommand(command, args) {
   else if (command === 'todo-reject') result = await decideHandoff(args.root, { ...args, accept: false });
   else if (command === 'todo-recover') result = await recoverTodos(args.root, args);
   else if (command === 'todo-import-legacy') result = await importLegacyTodos(args.root, args);
+  else if (command === 'todo-match') result = await matchTodo(args.root, args);
+  else if (command === 'agent-wake') result = await wakeAgent(args.root, await jsonInput(args.payloadJson, '--payload-json'));
+  else if (command === 'agent-wake-ack') result = await acknowledgeWake(args.root, await jsonInput(args.payloadJson, '--payload-json'));
+  else if (command === 'peer-message') result = await sendPeerMessage(args.root, await jsonInput(args.payloadJson, '--payload-json'));
+  else if (command === 'todo-conflict-resolve') result = await resolveOwnershipConflict(args.root, await jsonInput(args.payloadJson, '--payload-json'));
+  else if (command === 'team-workbench') result = await teamWorkbench(args.root, args);
   else throw new Error(`Unknown command: ${command}`);
   console.log(JSON.stringify(result, null, 2));
   return result === null ? 1 : 0;

package/docs/agent-team-backlog.json

@@ -0,0 +1 @@
+{"version":1,"project":"agent-team-control-plane","items":[{"id":"AT-1","status":"done","depends_on":[]},{"id":"AT-2","status":"done","depends_on":["AT-1"]},{"id":"AT-3","status":"done","depends_on":["AT-1","AT-2"]},{"id":"AT-4","status":"done","depends_on":["AT-1"]},{"id":"AT-5","status":"done","depends_on":["AT-2","AT-4"]},{"id":"AT-6","status":"done","depends_on":["AT-1","AT-3","AT-4","AT-5"]},{"id":"AT-7","status":"done","depends_on":["AT-6"],"evidence":"live-runtime-conformance.json"},{"id":"AT-8","status":"done","depends_on":["AT-7"],"evidence":"npm test, clean package smoke, agent-team-final-judgement.json"}]}

package/docs/agent-team-terminal-contract.json

@@ -0,0 +1 @@
+{"version":1,"project":"agent-team-control-plane","status":"complete","terminal_user_visible_outcome":"A fresh Loop Engineering workspace can register heterogeneous agents and operate them as one durable team through the existing todo control plane.","constraints":["extend runtime/loops/control-plane; do not create a second orchestrator","all ownership mutations remain fenced and audited","external effects remain capability and authorization gated"],"requirements":[{"id":"AT-1","title":"product agent registry","status":"done","evidence":"lib/todo-control-plane.mjs"},{"id":"AT-2","title":"explainable capability budget dependency load matching","status":"done","evidence":"matchTodo and agent-team-control-plane-self-test.mjs"},{"id":"AT-3","title":"durable targeted wake","status":"done","evidence":"wakeAgent/acknowledgeWake"},{"id":"AT-4","title":"role-independent peer collaboration and durable handoff","status":"done","evidence":"sendPeerMessage plus fenced handoff"},{"id":"AT-5","title":"conflict and orphan governance","status":"done","evidence":"resolveOwnershipConflict/recoverTodos/teamWorkbench"},{"id":"AT-6","title":"team workbench and CLI","status":"done","evidence":"teamWorkbench and CLI commands"},{"id":"AT-7","title":"Codex OpenClaw Claude cross-runtime conformance","status":"done","evidence":"runtime-adapter-conformance.mjs, agent-team-control-plane-self-test.mjs and live-runtime-conformance.json"},{"id":"AT-8","title":"full regression packaged install final judgement","status":"done","evidence":"npm test, clean npm pack/install/export smoke and agent-team-final-judgement.json"}],"acceptance":["all requirements done","targeted and full tests pass","clean package install passes","live runtime probes use actual installed executables","P0/P1/P2 safety remains intact"],"milestone_rule":"A milestone or simulated runtime test is not project completion.","completion_rule":"Every requirement and check must pass with durable evidence and no unmet blocker."}

package/docs/human-gate-command.md

@@ -0,0 +1,17 @@
+# Cross-interface Human Gate command core
+
+`lib/human-gate-command.mjs` is the sole mutation boundary for governed Human Gates. Dashboard POST actions and channel callbacks must call `executeGateCommand`; projections and adapters must not write gate files directly.
+
+Each gate records project, task, Gate ID, action, reason, impact, risk, cost/budget, evidence, Dashboard URL, expiry, generation, allowed actors and one or more exact source bindings. Commands require `gate_id`, `expected_generation`, actor identity, channel/message binding, reply binding for reply commands, and an idempotency key. Successful commands produce durable receipts. Per-gate exclusive creation plus the generation fence makes only the first valid cross-interface command commit.
+
+Allowed mutations are card-button callbacks and replies matching `/approve gate_<id>`, `/reject gate_<id>`, or `/request_revision gate_<id> <reason>` where the reply is bound to the registered card. Ordinary language, ordinal references, quotes, forwards and screenshots are ignored or rejected.
+
+High/critical risk, production, external publication, irreversible work, or cost at/above the configured threshold enters `awaiting_confirmation` and increments generation. A second command against the new generation is required. `request_revision` writes a revision artifact, increments generation, and invalidates old cards. Clients refresh from `/api/v1/gates`; processed cards render disabled.
+
+The Feishu adapter is deliberately transport-neutral. The HTTP/plugin transport must verify the official Feishu callback signature or encrypted-event envelope before normalization, then call `normalizeFeishuGateEvent(payload, { signatureVerified: true })`. Missing or failed verification throws `feishu_signature_unverified`; the adapter does not accept a raw callback on trust. Secret lookup, timestamp/nonce freshness and cryptographic verification belong to the transport boundary and must never be inferred from payload fields. The adapter performs no network I/O.
+
+Delivery/update code should render `gateCard`, send it through the platform transport, register the returned message ID as a source binding, and refresh or disable the card after every durable receipt. Ordinary chat is fail-closed: only an exact card button, an exact command reply bound to the registered card, or the display-only `/show_gate gate_<id>` route is recognized. Natural language, quotes, forwards and screenshots never call the command core.
+
+OpenClaw installation creates `scripts/loops/openclaw-loop-gate.mjs`, a stdin/stdout Gate Command bridge. A trusted callback/plugin handler verifies the Feishu envelope first and invokes the bridge with `LOOP_GATE_CHANNEL=feishu` and `LOOP_FEISHU_SIGNATURE_VERIFIED=1`; other channels must supply an already normalized event. The bridge calls the same `executeGateCommand` path used by Dashboard. Dashboard and chat therefore share generation fencing, actor/source binding, receipts, idempotency and synchronized-card state; neither interface owns separate approval state.
+
+After installation run `loop-engineering-openclaw-doctor`, then `loop-engineering-openclaw-smoke`; both remain local/dry-run and verify the installed Gate Command bridge. Run `npm run check:human-gates` for unit, adapter, Dashboard HTTP integration, concurrency, replay, expiry, authorization, signature-boundary and misrecognition coverage. Tests use temporary local artifacts and make no external calls.

package/docs/multi-agent-control-plane.md

@@ -1,5 +1,7 @@
 # Multi-Agent Control Plane (P2)
 
+The product team layer extends this same control-plane state—never a second orchestrator—with runtime-aware registry records, capacity/load-aware explainable matching, targeted wake events, role-independent peer messages, conflict records, and a unified workbench.
+
 P2 stores typed todos, registered agents, leases, handoffs, and ownership history in `runtime/loops/control-plane/state.json`. Every mutation is serialized by an atomic filesystem mutex and committed with rename. `audit.jsonl` records each ownership transition.
 
 ## Todo contract
@@ -26,6 +28,12 @@ todo-handoff --todo-id ID --agent-id AGENT --target-agent-id AGENT --fencing-tok
 todo-accept|todo-reject --handoff-id ID --agent-id AGENT
 todo-recover [--now EPOCH_MS]
 todo-import-legacy
+todo-match [--todo-id ID]
+agent-wake --payload-json JSON
+agent-wake-ack --payload-json JSON
+peer-message --payload-json JSON
+todo-conflict-resolve --payload-json JSON
+team-workbench
 ```
 
 `--todo-json` and `--agent-json` accept either an inline JSON object or a file path. All commands accept `--root` and emit JSON.

package/docs/quota-runtime-decision.md

@@ -0,0 +1,9 @@
+# Quota runtime decision engine
+
+Quota is a runtime policy decision, not only a static credit check. Import `decideQuota` from `taskforce-loop-engineering/quota` and provide `limits`, already-recorded `spend`, the next slice `request`, work/error/external state, and optional lanes.
+
+The result always chooses one of `execute`, `wait`, `ask`, `self-repair`, or `silent` and includes a scheduler hint. Budget vectors use `tokens`, `time_ms`, `money_minor`, and `rounds`.
+
+`recordVerifiedSliceSpend` records spend only when a slice is both `completed` and `verified`. Idle, waiting, failed, or partially completed attempts record nothing. `slice_id` makes recording idempotent.
+
+A lane waiting for a human may fall back only to a different lane marked both `safe_fallback: true` and `audited: true`; otherwise the decision is `ask`.

package/lib/human-gate-channel-adapter.mjs

@@ -0,0 +1,37 @@
+import { executeGateCommand, gateCard, getHumanGate, parseBoundReply } from './human-gate-command.mjs';
+
+export async function renderGateForChannel(root, gateId) { return gateCard(await getHumanGate(root, gateId)); }
+
+export async function handleChannelGateEvent(root, event, options = {}) {
+  if (event.kind === 'card_button') {
+    const receipt = await executeGateCommand(root, {
+      gate_id: event.action?.gate_id, decision: event.action?.decision,
+      expected_generation: event.action?.expected_generation, actor_id: event.actor_id,
+      source_channel: event.channel, source_message_id: event.message_id, reply_to: event.reply_to ?? null,
+      event_type: 'card_button', idempotency_key: event.event_id, reason: event.action?.reason
+    }, options);
+    return { ...receipt, synchronized_card: await renderGateForChannel(root, event.action?.gate_id) };
+  }
+  if (event.kind === 'message_reply' && event.reply_to) {
+    const parsed = parseBoundReply(event.text); if (!parsed) return { outcome: 'ignored_untrusted_chat' };
+    const receipt = await executeGateCommand(root, {
+      ...parsed, expected_generation: event.expected_generation, actor_id: event.actor_id,
+      source_channel: event.channel, source_message_id: event.card_message_id,
+      reply_to: event.reply_to, event_type: 'bound_reply', idempotency_key: event.event_id
+    }, options);
+    return { ...receipt, synchronized_card: await renderGateForChannel(root, parsed.gate_id) };
+  }
+  const show = String(event.text ?? '').trim().match(/^\/show_gate\s+(gate_[a-zA-Z0-9._:-]+)$/);
+  if (show) return { outcome: 'display_only', card: await renderGateForChannel(root, show[1]) };
+  return { outcome: 'ignored_untrusted_chat' };
+}
+
+// Feishu callback feasibility mapping. It performs no network I/O.
+export function normalizeFeishuGateEvent(payload, options = {}) {
+  if (options.signatureVerified !== true) throw new Error('feishu_signature_unverified');
+  if (payload?.event?.action?.value?.gate_id) return { kind: 'card_button', event_id: payload.header?.event_id, actor_id: payload.event.operator?.operator_id?.open_id, channel: 'feishu', message_id: payload.event.context?.open_message_id, action: payload.event.action.value };
+  const message = payload?.event?.message;
+  let text = message?.content;
+  try { const parsed = JSON.parse(text); text = typeof parsed?.text === 'string' ? parsed.text : ''; } catch {}
+  return { kind: message?.parent_id ? 'message_reply' : 'ordinary_message', event_id: payload.header?.event_id, actor_id: payload.event?.sender?.sender_id?.open_id, channel: 'feishu', card_message_id: message?.root_id, reply_to: message?.parent_id, text, expected_generation: payload.expected_generation };
+}

package/lib/human-gate-command.mjs

@@ -0,0 +1,161 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const DECISIONS = new Set(['approve', 'reject', 'request_revision']);
+const SOURCES = new Set(['card_button', 'bound_reply']);
+
+function required(value, name) {
+  if (value === undefined || value === null || value === '') throw new Error(`missing_${name}`);
+  return String(value);
+}
+
+function safe(value, name) {
+  const text = required(value, name);
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,299}$/.test(text)) throw new Error(`invalid_${name}`);
+  return text;
+}
+
+function digest(value) { return createHash('sha256').update(JSON.stringify(value)).digest('hex'); }
+function gateDir(root) { return path.join(root, 'runtime', 'loops', 'human-gates'); }
+function gateFile(root, gateId) { return path.join(gateDir(root), 'gates', `${safe(gateId, 'gate_id')}.json`); }
+function receiptFile(root, key) { return path.join(gateDir(root), 'receipts', `${digest(key)}.json`); }
+
+async function readJson(file) { return JSON.parse(await readFile(file, 'utf8')); }
+async function atomicJson(file, value) {
+  await mkdir(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  await rename(temporary, file);
+}
+
+async function lock(root, gateId, callback) {
+  const lockFile = path.join(gateDir(root), 'locks', `${safe(gateId, 'gate_id')}.lock`);
+  await mkdir(path.dirname(lockFile), { recursive: true });
+  let handle;
+  try { handle = await open(lockFile, 'wx', 0o600); }
+  catch (error) { if (error.code === 'EEXIST') throw new Error('gate_conflict_retry'); throw error; }
+  try { return await callback(); }
+  finally { await handle.close(); await rm(lockFile, { force: true }); }
+}
+
+function publicGate(gate) {
+  return {
+    gate_id: gate.gate_id, project: gate.project, task: gate.task, action: gate.action,
+    reason: gate.reason, impact: gate.impact, risk: gate.risk, cost: gate.cost,
+    evidence: gate.evidence, dashboard_url: gate.dashboard_url, expiry: gate.expiry,
+    generation: gate.generation, status: gate.status, decisions: [...DECISIONS],
+    confirmation_required: gate.confirmation_required,
+    source_binding: gate.source_binding, source_bindings: gate.source_bindings,
+    processed: gate.processed ?? null
+  };
+}
+
+export async function createHumanGate(root, input, options = {}) {
+  const gateId = safe(input.gate_id ?? `gate_${randomUUID()}`, 'gate_id');
+  const now = options.now ?? new Date().toISOString();
+  const risk = input.risk ?? { level: 'low', reasons: [] };
+  const highRisk = input.confirmation_required ?? (
+    ['high', 'critical'].includes(String(risk.level).toLowerCase()) ||
+    Boolean(input.production || input.external_publish || input.irreversible || Number(input.cost?.amount ?? 0) >= Number(input.cost?.confirmation_threshold ?? Infinity))
+  );
+  const bindingsInput = input.source_bindings ?? [input.source_binding];
+  const sourceBindings = bindingsInput.map((binding) => ({
+    channel: required(binding?.channel, 'source_channel'), message_id: required(binding?.message_id, 'source_message_id'),
+    reply_to: binding?.reply_to ? String(binding.reply_to) : String(binding?.message_id), adapter: binding?.adapter ?? null
+  }));
+  const gate = {
+    version: 1, gate_id: gateId, project: required(input.project, 'project'), task: required(input.task, 'task'),
+    action: required(input.action, 'action'), reason: required(input.reason, 'reason'), impact: required(input.impact, 'impact'),
+    risk, cost: input.cost ?? { amount: 0, currency: 'CNY', budget: null }, evidence: input.evidence ?? [],
+    dashboard_url: input.dashboard_url ?? null, expiry: required(input.expiry, 'expiry'), generation: Number(input.generation ?? 1),
+    status: 'pending', confirmation_required: highRisk, confirmation: null,
+    allowed_actors: (input.allowed_actors ?? []).map(String),
+    source_binding: sourceBindings[0], source_bindings: sourceBindings,
+    revision_history: [], created_at: now, updated_at: now
+  };
+  if (!Number.isInteger(gate.generation) || gate.generation < 1 || Number.isNaN(Date.parse(gate.expiry))) throw new Error('invalid_gate_generation_or_expiry');
+  const file = gateFile(root, gateId);
+  await mkdir(path.dirname(file), { recursive: true });
+  try { const handle = await open(file, 'wx', 0o600); await handle.writeFile(`${JSON.stringify(gate, null, 2)}\n`); await handle.close(); }
+  catch (error) { if (error.code === 'EEXIST') throw new Error('gate_already_exists'); throw error; }
+  return publicGate(gate);
+}
+
+export async function getHumanGate(root, gateId) { return publicGate(await readJson(gateFile(root, gateId))); }
+
+function validateBinding(gate, command, now) {
+  if (!DECISIONS.has(command.decision)) throw new Error('invalid_decision');
+  if (!SOURCES.has(command.event_type)) throw new Error('untrusted_event_type');
+  if (Number(command.expected_generation) !== gate.generation) throw new Error('stale_generation');
+  if (gate.status !== 'pending' && gate.status !== 'awaiting_confirmation') throw new Error('gate_already_processed');
+  if (Date.parse(gate.expiry) <= Date.parse(now)) throw new Error('gate_expired');
+  const actor = required(command.actor_id, 'actor_id');
+  if (gate.allowed_actors.length && !gate.allowed_actors.includes(actor)) throw new Error('actor_unauthorized');
+  const channel = required(command.source_channel, 'source_channel'); const messageId = required(command.source_message_id, 'source_message_id');
+  const binding = (gate.source_bindings ?? [gate.source_binding]).find((item) => item.channel === channel && item.message_id === messageId);
+  if (!binding) throw new Error((gate.source_bindings ?? [gate.source_binding]).some((item) => item.channel === channel) ? 'source_message_mismatch' : 'source_channel_mismatch');
+  if (command.event_type === 'bound_reply' && required(command.reply_to, 'reply_to') !== binding.reply_to) throw new Error('reply_binding_mismatch');
+  if (command.event_type === 'bound_reply' && required(command.gate_id, 'gate_id') !== gate.gate_id) throw new Error('reply_gate_id_required');
+}
+
+export async function executeGateCommand(root, command, options = {}) {
+  const gateId = safe(command.gate_id, 'gate_id');
+  const idempotencyKey = required(command.idempotency_key, 'idempotency_key');
+  const priorFile = receiptFile(root, idempotencyKey);
+  try { const prior = await readJson(priorFile); if (prior.command_fingerprint !== digest(command)) throw new Error('idempotency_key_reused'); return { ...prior, replayed: true }; }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  return lock(root, gateId, async () => {
+    try { const prior = await readJson(priorFile); if (prior.command_fingerprint !== digest(command)) throw new Error('idempotency_key_reused'); return { ...prior, replayed: true }; }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    const file = gateFile(root, gateId); const gate = await readJson(file); const now = options.now ?? new Date().toISOString();
+    validateBinding(gate, command, now);
+    const before = gate.generation; let outcome;
+    if (command.decision === 'approve' && gate.confirmation_required && gate.status !== 'awaiting_confirmation') {
+      gate.status = 'awaiting_confirmation'; gate.generation += 1;
+      gate.confirmation = { first_actor_id: command.actor_id, first_receipt_at: now };
+      outcome = 'confirmation_required';
+    } else if (command.decision === 'request_revision') {
+      gate.revision_history.push({ generation: gate.generation, reason: required(command.reason, 'revision_reason'), actor_id: command.actor_id, at: now });
+      gate.generation += 1; gate.status = 'pending'; gate.reason = command.reason;
+      gate.processed = { decision: 'request_revision', actor_id: command.actor_id, at: now, superseded_generation: before };
+      outcome = 'revision_created';
+    } else {
+      gate.status = command.decision === 'approve' ? 'approved' : 'rejected';
+      gate.processed = { decision: command.decision, actor_id: command.actor_id, at: now, generation: before };
+      outcome = gate.status;
+    }
+    gate.updated_at = now;
+    const receipt = {
+      version: 1, receipt_id: `receipt_${randomUUID()}`, gate_id: gateId, decision: command.decision, outcome,
+      actor_id: command.actor_id, event_type: command.event_type, source_channel: command.source_channel,
+      source_message_id: command.source_message_id, reply_to: command.reply_to ?? null,
+      expected_generation: Number(command.expected_generation), resulting_generation: gate.generation,
+      idempotency_key: idempotencyKey, command_fingerprint: digest(command), created_at: now, replayed: false
+    };
+    await atomicJson(file, gate);
+    if (outcome === 'revision_created') await atomicJson(path.join(gateDir(root), 'revisions', `${gateId}.generation-${gate.generation}.json`), {
+      version: 1, gate_id: gateId, amendment_type: 'request_revision', supersedes_generation: before,
+      generation: gate.generation, reason: command.reason, actor_id: command.actor_id, source_receipt_id: receipt.receipt_id, created_at: now
+    });
+    await atomicJson(priorFile, receipt);
+    return receipt;
+  });
+}
+
+export function parseBoundReply(text) {
+  const match = String(text ?? '').trim().match(/^\/(approve|reject|request_revision)\s+(gate_[a-zA-Z0-9._:-]+)(?:\s+(.+))?$/);
+  if (!match) return null;
+  return { decision: match[1], gate_id: match[2], reason: match[3] ?? null };
+}
+
+export function gateCard(gate) {
+  const g = publicGate(gate);
+  return { type: 'human_gate_card', title: `${g.project} · Human Gate`, fields: g, buttons: [...DECISIONS].map((decision) => ({ decision, gate_id: g.gate_id, expected_generation: g.generation, disabled: !['pending', 'awaiting_confirmation'].includes(g.status) })) };
+}
+
+export async function listHumanGates(root) {
+  const dir = path.join(gateDir(root), 'gates');
+  const names = (await import('node:fs/promises')).readdir(dir).catch(() => []);
+  return Promise.all((await names).filter((name) => name.endsWith('.json')).sort().map(async (name) => publicGate(await readJson(path.join(dir, name)))));
+}

package/lib/operator-dashboard.mjs

@@ -1,6 +1,7 @@
 import { createServer } from 'node:http';
 import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { executeGateCommand, listHumanGates } from './human-gate-command.mjs';
 
 export const DASHBOARD_SCHEMA_VERSION = '1.0.0';
 const SENSITIVE = /(^|_)(secret|token|password|credential|api[_-]?key|private[_-]?key|provider)(_|$)/i;
@@ -217,10 +218,22 @@ export function dashboardHealth(projection, options = {}) {
   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(dataUrl = '/api/v1/overview?') {
+function legacyHtml(dataUrl = '/api/v1/overview?') {
   return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Loop Engineering Workspace</title><style>:root{color-scheme:dark;--bg:#091018;--panel:#111c28;--line:#26384b;--muted:#91a5b8;--accent:#77d6c9}*{box-sizing:border-box}body{font:14px/1.5 ui-sans-serif,system-ui;margin:0;background:var(--bg);color:#eef6fb}header{position:sticky;top:0;z-index:2;padding:1rem clamp(1rem,4vw,3rem);background:#091018ee;border-bottom:1px solid var(--line);backdrop-filter:blur(12px)}h1,h2,h3,p{margin:.2rem 0}.eyebrow,.muted{color:var(--muted)}main{padding:1.25rem clamp(1rem,4vw,3rem);display:grid;gap:1rem}.stats,.projects,.split{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:.8rem}.card{background:linear-gradient(150deg,#142230,#0d1822);border:1px solid var(--line);border-radius:14px;padding:1rem;min-width:0}.stat strong{font-size:1.65rem}.bar{height:7px;background:#223141;border-radius:9px;overflow:hidden;margin:.75rem 0}.bar i{display:block;height:100%;background:var(--accent)}.pill{display:inline-block;padding:.15rem .5rem;border-radius:1rem;background:#24384a;color:#d9edf8}.ok{color:#7ee2a8}.warn{color:#ffcf70}button,input,select{padding:.65rem;background:#111d29;color:inherit;border:1px solid #3a5268;border-radius:8px}button.project{width:100%;text-align:left;font:inherit}button.project[aria-pressed=true]{border-color:var(--accent)}table{width:100%;border-collapse:collapse}th,td{text-align:left;padding:.6rem;border-bottom:1px solid var(--line);vertical-align:top}.scroll{overflow:auto}.timeline{border-left:2px solid var(--line);padding-left:1rem}.event{margin:.65rem 0}.project{cursor:pointer}.project:focus-visible,input:focus-visible,select:focus-visible{outline:3px solid var(--accent);outline-offset:2px}#detail:empty{display:none}.empty{padding:1rem;text-align:center;color:var(--muted)}@media(max-width:640px){header{position:static}.desktop{display:none}td,th{min-width:120px}.split{grid-template-columns:1fr}input,select{width:100%;margin-top:.4rem}}</style></head><body><header><div class="eyebrow">READ-ONLY OPERATOR WORKSPACE</div><h1>Loop Engineering</h1><p id="health" role="status" aria-live="polite">Loading durable artifacts…</p></header><main><section class="stats" id="stats" aria-label="Workspace summary"></section><section aria-labelledby="projects-title"><h2 id="projects-title">Projects</h2><p class="muted">Project completion is separate from milestone completion.</p><div class="projects" id="projects"></div></section><section class="card" id="detail" tabindex="-1" aria-live="polite"></section><section class="card"><div class="split"><div><h2>Operational queue</h2><p class="muted">Human gates, reservations and reconciliation remain visible and immutable here.</p></div><div><label>Search <input id="q" placeholder="Task, owner or action"></label><label>State <select id="s"><option value="">All states</option></select></label></div></div><div class="scroll"><table><thead><tr><th>State</th><th>Task</th><th class="desktop">Owner</th><th>Next action</th></tr></thead><tbody id="rows"></tbody></table></div></section></main><script>const dataUrl=${JSON.stringify(dataUrl)},initial=new URLSearchParams(location.search);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('');q.value=initial.get('q')??'';s.value=initial.get('state')??'';let selected=initial.get('project'),model=null;const el=(tag,text,cls)=>{const n=document.createElement(tag);n.textContent=text??'';if(cls)n.className=cls;return n};function syncUrl(){if(dataUrl.startsWith('./'))return;const p=new URLSearchParams();if(q.value)p.set('q',q.value);if(s.value)p.set('state',s.value);if(selected)p.set('project',selected);history.replaceState(null,'','?'+p)}function projectDetail(p,focus=false){selected=p.id;detail.replaceChildren();detail.append(el('h2',p.id),el('p',p.goal,'muted'));const c=p.terminal_contract;if(c){detail.append(el('h3','Terminal contract'),el('p',c.terminal_state?.userVisibleOutcome??'No user-visible outcome recorded'),el('p',c.milestone_rule??'','warn'))}detail.append(el('h3','Milestones'));const list=el('div');for(const m of p.milestones??[])list.append(el('p',(m.status??'pending')+' · '+m.title));detail.append(list,el('h3','Gates & reservations'));const operational=el('div');const gates=(p.tasks??[]).flatMap(x=>x.gates??[]);operational.append(el('p',(gates.length?gates.length+' human/external gate(s)':'No project gates')+' · '+model.actions.length+' workspace reservation(s)','muted'));detail.append(operational,el('h3','Acceptance & final judge timeline'));const tl=el('div',null,'timeline');const events=(p.tasks??[]).flatMap(x=>x.timeline??[]);if(!events.length)tl.append(el('p','No acceptance events yet.','empty'));for(const t of events)tl.append(el('div',(t.at??'undated')+' · '+t.type+' · '+t.status+' — '+(t.summary??''),'event'));detail.append(tl);syncUrl();drawProjects();if(focus)detail.focus()}function drawProjects(){projects.replaceChildren(...model.projects.map(p=>{const n=el('button',null,'card project');n.type='button';n.setAttribute('aria-pressed',String(selected===p.id));const done=p.project_summary?.completed_milestones??0,total=p.project_summary?.total_milestones??0;n.append(el('span',p.terminal_accepted?'PROJECT ACCEPTED':String(p.status).toUpperCase(),p.terminal_accepted?'pill ok':'pill'),el('h3',p.id),el('p',p.goal,'muted'));const b=el('div',null,'bar'),i=el('i');i.style.width=(total?done/total*100:0)+'%';b.append(i);n.append(b,el('p',done+' / '+total+' milestones'));n.onclick=()=>projectDetail(p,true);return n}));if(!model.projects.length)projects.append(el('p','No project artifacts found.','card empty'))}async function draw(){try{const params=new URLSearchParams({q:q.value,state:s.value});const response=await fetch(dataUrl+(dataUrl.includes('?')?params:''));if(!response.ok)throw new Error('HTTP '+response.status);model=await response.json();health.textContent=model.health.status+' · generated '+new Date(model.generated_at).toLocaleString()+' · source is read-only';stats.replaceChildren(...[['Projects',model.overview.project_count],['Task workspaces',model.overview.task_workspace_count],['Human gates',model.gates.length],['Reservations',model.overview.action_count]].map(([k,v])=>{const n=el('div',null,'card stat');n.append(el('div',k,'muted'),el('strong',v));return n}));drawProjects();const all=[...model.todos,...model.queues.flatMap(x=>x.tasks)];rows.replaceChildren(...all.map(x=>{const tr=el('tr');for(const [v,c] of [[x.state,''],[x.title,''],[x.owner??'—','desktop'],[x.next_action??'—','']])tr.append(el('td',String(v),c));return tr}));if(!all.length){const td=el('td','No matching operational work.','empty');td.colSpan=4;const tr=el('tr');tr.append(td);rows.append(tr)}const chosen=model.projects.find(p=>p.id===selected);if(chosen)projectDetail(chosen)}catch(error){health.textContent='Unable to load workspace · '+error.message;health.className='warn'}}q.oninput=()=>{syncUrl();draw()};s.onchange=()=>{syncUrl();draw()};addEventListener('popstate',()=>location.reload());draw()</script></body></html>`;
 }
 
+function gateHtml(dataUrl = '/api/v1/overview?') {
+  if (dataUrl.startsWith('./')) return legacyHtml(dataUrl);
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Loop Engineering Human Gates</title><style>:root{color-scheme:dark}body{font:14px system-ui;max-width:1100px;margin:auto;padding:24px;background:#091018;color:#eef6fb}.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(300px,1fr));gap:14px}.card{background:#111c28;border:1px solid #30465b;border-radius:14px;padding:16px}.meta{color:#9db0c2;white-space:pre-wrap}button,input{padding:9px;margin:4px;border-radius:8px;border:1px solid #4c657b;background:#162737;color:inherit}button:disabled{opacity:.45}.approve{border-color:#55bd82}.reject{border-color:#db6e74}.revision{border-color:#d8ad55}</style></head><body><h1>Loop Engineering</h1><p id="health">Loading authoritative artifacts…</p><label>Verified actor identity <input id="actor" autocomplete="username" placeholder="actor id"></label><h2>Human Gates</h2><div id="gates" class="grid"></div><h2>Workspace</h2><div id="workspace" class="grid"></div><script>const node=(tag,text,cls)=>{const n=document.createElement(tag);n.textContent=text;if(cls)n.className=cls;return n};async function decide(g,d){const binding=(g.source_bindings||[]).find(x=>x.channel==='dashboard');if(!binding)return alert('This gate has no registered Dashboard binding.');if(!actor.value)return alert('Actor identity is required.');const reason=d==='request_revision'?prompt('Revision reason (required)'):null;if(d==='request_revision'&&!reason)return;const body={gate_id:g.gate_id,decision:d,expected_generation:g.generation,actor_id:actor.value,source_message_id:binding.message_id,reply_to:binding.reply_to,idempotency_key:crypto.randomUUID(),reason};const r=await fetch('/api/v1/gate-commands',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify(body)});const out=await r.json();if(!r.ok)return alert(out.message||out.error);alert(out.outcome+(out.outcome==='confirmation_required'?' — confirm again on generation '+out.resulting_generation:''));await draw()}async function draw(){const [overview,gs]=await Promise.all([fetch('/api/v1/overview').then(r=>r.json()),fetch('/api/v1/gates').then(r=>r.json())]);health.textContent=overview.health.status+' · Loop artifacts remain the only source of truth';workspace.replaceChildren(...[['Projects',overview.overview.project_count],['Tasks',overview.overview.task_workspace_count],['Reservations',overview.overview.action_count]].map(([k,v])=>{const n=node('div','', 'card');n.append(node('h3',k),node('strong',String(v)));return n}));gates.replaceChildren(...gs.map(g=>{const n=node('article','', 'card'),active=['pending','awaiting_confirmation'].includes(g.status);n.append(node('h3',g.project+' · '+g.task),node('p','Gate ID: '+g.gate_id+' · generation '+g.generation+' · '+g.status,'meta'),node('p','Action: '+g.action+'\nReason: '+g.reason+'\nImpact: '+g.impact+'\nRisk: '+JSON.stringify(g.risk)+'\nCost/budget: '+JSON.stringify(g.cost)+'\nEvidence: '+JSON.stringify(g.evidence)+'\nDashboard: '+(g.dashboard_url||location.href)+'\nExpiry: '+g.expiry,'meta'));for(const d of ['approve','reject','request_revision']){const b=node('button',d,d==='request_revision'?'revision':d);b.disabled=!active;b.onclick=()=>decide(g,d);n.append(b)}return n}));if(!gs.length)gates.append(node('p','No Human Gates.','card'))}draw()</script></body></html>`;
+}
+
+function html(dataUrl = '/api/v1/overview?') {
+  if (dataUrl.startsWith('./')) return legacyHtml(dataUrl);
+  const panel = `<section aria-labelledby="human-gates-title"><h2 id="human-gates-title">Human Gates</h2><p class="muted">Only exact card actions or card-bound commands can decide a gate.</p><label>Verified actor identity <input id="gateactor" autocomplete="username" placeholder="actor id"></label><div class="projects" id="gatecards"></div></section>`;
+  const behavior = `<script>async function gateDecision(g,d){const binding=(g.source_bindings||[]).find(x=>x.channel==='dashboard');if(!binding)return alert('No registered Dashboard binding.');if(!gateactor.value)return alert('Actor identity is required.');const reason=d==='request_revision'?prompt('Revision reason (required)'):null;if(d==='request_revision'&&!reason)return;const r=await fetch('/api/v1/gate-commands',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({gate_id:g.gate_id,decision:d,expected_generation:g.generation,actor_id:gateactor.value,source_message_id:binding.message_id,reply_to:binding.reply_to,idempotency_key:crypto.randomUUID(),reason})}),out=await r.json();if(!r.ok)return alert(out.message||out.error);await drawHumanGates()}async function drawHumanGates(){const gs=await fetch('/api/v1/gates').then(r=>r.json());gatecards.replaceChildren(...gs.map(g=>{const n=el('article',null,'card'),active=['pending','awaiting_confirmation'].includes(g.status);n.append(el('h3',g.project+' · '+g.task),el('p','Gate ID: '+g.gate_id+' · generation '+g.generation+' · '+g.status,'muted'),el('p','Action: '+g.action+' | Reason: '+g.reason+' | Impact: '+g.impact+' | Risk: '+JSON.stringify(g.risk)+' | Cost/budget: '+JSON.stringify(g.cost)+' | Evidence: '+JSON.stringify(g.evidence)+' | Dashboard: '+(g.dashboard_url||location.href)+' | Expiry: '+g.expiry,'muted'));for(const d of ['approve','reject','request_revision']){const b=el('button',d);b.type='button';b.setAttribute('aria-pressed','false');b.disabled=!active;b.onclick=()=>gateDecision(g,d);n.append(b)}return n}));if(!gs.length)gatecards.append(el('p','No pending gates.','card empty'))}drawHumanGates()</script>`;
+  return legacyHtml(dataUrl).replace('READ-ONLY OPERATOR WORKSPACE', 'GOVERNED OPERATOR WORKSPACE').replace('</main>', `${panel}</main>`).replace('</body>', `${behavior}</body>`);
+}
+
 function loopback(host) { return host === '127.0.0.1' || host === '::1' || host === 'localhost'; }
 
 export async function createDashboardServer(root, options = {}) {
@@ -229,9 +242,16 @@ export async function createDashboardServer(root, options = {}) {
   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()); }
+      if (request.method === 'POST' && url.pathname === '/api/v1/gate-commands') {
+        let raw = ''; for await (const chunk of request) { raw += chunk; if (raw.length > 65536) throw new Error('request_too_large'); }
+        const command = JSON.parse(raw || '{}');
+        const receipt = await executeGateCommand(root, { ...command, event_type: 'card_button', source_channel: 'dashboard' });
+        response.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' });
+        return response.end(`${JSON.stringify(receipt)}\n`);
+      }
+      if (request.method !== 'GET' && request.method !== 'HEAD') { response.writeHead(405, { Allow: 'GET, HEAD, POST' }); return response.end(); }
+      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().replace('<p id="health">', '<p id="health" role="status" aria-live="polite">')); }
       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') });
@@ -240,6 +260,7 @@ export async function createDashboardServer(root, options = {}) {
       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 if (url.pathname === '/api/v1/projects') body = projection.projects;
+      else if (url.pathname === '/api/v1/gates') body = await listHumanGates(root);
       else if (url.pathname.startsWith('/api/v1/projects/')) body = projection.projects.find((item) => item.id === safeId(decodeURIComponent(url.pathname.slice('/api/v1/projects/'.length)))) ?? null;
       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`);

package/lib/quota-runtime-decision.mjs

@@ -0,0 +1,62 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export const QUOTA_DECISIONS = Object.freeze(['execute', 'wait', 'ask', 'self-repair', 'silent']);
+export const BUDGET_DIMENSIONS = Object.freeze(['tokens', 'time_ms', 'money_minor', 'rounds']);
+
+const finite = (value, fallback = 0) => Number.isFinite(Number(value)) ? Number(value) : fallback;
+const vector = (value = {}) => Object.fromEntries(BUDGET_DIMENSIONS.map((key) => [key, Math.max(0, finite(value[key]))]));
+const plus = (left, right) => Object.fromEntries(BUDGET_DIMENSIONS.map((key) => [key, left[key] + right[key]]));
+const remaining = (limits, spend) => Object.fromEntries(BUDGET_DIMENSIONS.map((key) => [key, Math.max(0, limits[key] - spend[key])]));
+const exceeds = (request, available) => BUDGET_DIMENSIONS.filter((key) => request[key] > available[key]);
+
+function schedulerHint(decision, input = {}) {
+  const delays = { execute: 0, 'self-repair': 0, ask: null, silent: null, wait: Math.max(1_000, finite(input.retry_after_ms, 30_000)) };
+  return {
+    action: decision,
+    eligible_at: delays[decision] === null ? null : new Date(Date.now() + delays[decision]).toISOString(),
+    retry_after_ms: delays[decision],
+    wake_on: decision === 'ask' ? ['human_gate_resolved'] : decision === 'silent' ? ['new_work', 'budget_reset'] : decision === 'wait' ? ['timer', 'budget_reset', 'lane_change'] : []
+  };
+}
+
+export function decideQuota(input = {}) {
+  const limits = vector(input.limits);
+  const spend = vector(input.spend);
+  const request = vector(input.request);
+  const available = remaining(limits, spend);
+  const exhausted = exceeds(request, available);
+  const lanes = Array.isArray(input.lanes) ? input.lanes : [];
+  const selected = input.lane_id ? lanes.find((lane) => lane.id === input.lane_id) : lanes[0];
+  const fallback = lanes.find((lane) => lane.id !== selected?.id && lane.safe_fallback === true && lane.audited === true && lane.state === 'runnable');
+  let decision = 'execute'; let reason = 'budget_available'; let lane = selected?.id ?? null;
+
+  if (!input.has_work) { decision = 'silent'; reason = 'no_work'; }
+  else if (input.repairable_error) { decision = 'self-repair'; reason = 'repairable_runtime_error'; }
+  else if (selected?.state === 'waiting_for_human' && fallback) { decision = 'execute'; reason = 'audited_safe_fallback'; lane = fallback.id; }
+  else if (selected?.state === 'waiting_for_human') { decision = 'ask'; reason = 'human_gate_required'; }
+  else if (input.external_condition_pending) { decision = 'wait'; reason = 'external_condition_pending'; }
+  else if (exhausted.length) { decision = input.can_wait_for_reset === false ? 'ask' : 'wait'; reason = `budget_exhausted:${exhausted.join(',')}`; }
+
+  return { version: 1, decision, reason, lane_id: lane, limits, spend, request, remaining: available, scheduler_hint: schedulerHint(decision, input) };
+}
+
+function ledgerPath(root) { return path.join(root, 'runtime', 'loops', 'quota', 'ledger.json'); }
+async function readLedger(root) { try { return JSON.parse(await readFile(ledgerPath(root), 'utf8')); } catch (error) { if (error.code === 'ENOENT') return { version: 1, spend: vector(), entries: [] }; throw error; } }
+
+export async function readQuotaLedger(root) { return readLedger(root); }
+
+export async function recordVerifiedSliceSpend(root, input = {}) {
+  if (input.status !== 'completed' || input.verified !== true) return { recorded: false, reason: 'slice_not_completed_and_verified' };
+  const amount = vector(input.spend);
+  const ledger = await readLedger(root);
+  const sliceId = String(input.slice_id ?? '').trim();
+  if (!sliceId) throw new Error('slice_id is required.');
+  if (ledger.entries.some((entry) => entry.slice_id === sliceId)) return { recorded: false, reason: 'slice_already_recorded', ledger };
+  const entry = { id: randomUUID(), slice_id: sliceId, spend: amount, completed_at: input.completed_at ?? new Date().toISOString(), evidence: input.evidence ?? null };
+  ledger.spend = plus(vector(ledger.spend), amount); ledger.entries.push(entry);
+  const file = ledgerPath(root); await mkdir(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.${randomUUID()}.tmp`; await writeFile(temp, `${JSON.stringify(ledger, null, 2)}\n`, { flag: 'wx' }); await rename(temp, file);
+  return { recorded: true, entry, ledger };
+}