taskforce-loop-engineering 0.15.12 → 0.15.14

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## 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.
+- Couple the Dashboard service to OpenClaw and Hermes gateway startup and verify the wiring in platform doctors and installer self-tests.
+- Support fail-closed `localhost` and Tailnet-only Dashboard listening modes without binding all network interfaces.
+
 ## 0.15.12 - 2026-08-28
 
 - Fix public CI setup on repositories that intentionally do not commit an npm lockfile.

package/README.md

@@ -39,7 +39,7 @@ when publication is separately approved.
 
 ## Read-only operator dashboard (P3)
 
-Version 0.12 adds a dependency-free operator projection over projects, queues, P0 gates, P1 action reservations and P2 typed todo ownership. Use `dashboard-inspect`, `dashboard-health`, `dashboard-export`, or the loopback-only `dashboard-serve`. See [docs/operator-dashboard.md](docs/operator-dashboard.md) for API, security and schema details.
+Version 0.12 adds a dependency-free operator projection over projects, queues, P0 gates, P1 action reservations and P2 typed todo ownership. Use `dashboard-inspect`, `dashboard-health`, `dashboard-export`, or `dashboard-serve`. Gateway autostart installation supports local-only and Tailnet-only listening without binding all interfaces. See [docs/operator-dashboard.md](docs/operator-dashboard.md) for API, security and schema details.
 
 The consolidated P0-P3 local release contract and evidence ledger are recorded in [docs/release-0.12-acceptance.md](docs/release-0.12-acceptance.md). Publishing, tagging, pushing, and production installation remain separate release actions.
 

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/operator-dashboard.md

@@ -12,9 +12,32 @@ loop-engineering dashboard-export --output-dir /tmp/loop-dashboard --root /path/
 loop-engineering dashboard-serve --root /path/to/workspace
 ```
 
-`dashboard-serve` binds to `127.0.0.1` and an ephemeral port by default. A wider bind is rejected unless `--allow-non-loopback` is explicit. The server has no authentication and is intended for trusted local use. The CLI never starts it during checks or installation.
+`dashboard-serve` binds to `127.0.0.1` and an ephemeral port by default. A wider bind is rejected unless `--allow-non-loopback` is explicit. The server has no authentication and is intended for trusted local use.
 
-Endpoints are `GET /api/v1/overview`, `/api/v1/health`, `/api/v1/todos`, `/api/v1/todos/:id`, and `/api/v1/actions`. Overview and todo lists support `q` and `state` filters. Private raw files are not served.
+The OpenClaw and Hermes integration installers also install a Dashboard service on port `4174` and systemd gateway drop-ins. Starting `openclaw-gateway.service` or `hermes-gateway.service` therefore starts the read-only Dashboard. The default `localhost` mode binds only `127.0.0.1`. Optional `tailscale` mode resolves `tailscale ip -4` at install time and binds only that Tailnet address; it never binds `0.0.0.0`. Tailnet access is governed by Tailscale ACLs/Grants, while the Dashboard itself remains read-only and has no application-level login.
+
+```bash
+loop-engineering-dashboard-autostart-install --root /path/to/workspace
+loop-engineering-dashboard-autostart-install --root /path/to/workspace --confirm-install
+loop-engineering-dashboard-autostart-install --root /path/to/workspace --listen tailscale --confirm-install
+```
+
+To make the workspace follow either the OpenClaw or Hermes user gateway lifecycle, install the loopback-only systemd integration:
+
+```sh
+loop-engineering-dashboard-autostart-install --root /path/to/workspace
+loop-engineering-dashboard-autostart-install --root /path/to/workspace --confirm-install
+```
+
+This creates `loop-engineering-dashboard.service` on fixed port `4174` and systemd drop-ins for `openclaw-gateway.service` and `hermes-gateway.service`. Starting either gateway pulls in the same idempotent dashboard service. Use `--listen localhost` (the default) for local-only access or `--listen tailscale` for Tailnet access. The Tailscale mode fails closed if it cannot resolve exactly one `100.x` IPv4 address. Restrict port `4174` with Tailnet ACLs/Grants when the Tailnet contains users or devices that should not see project metadata.
+
+The platform installers expose the same choice as `--dashboard-listen localhost|tailscale` and accept `--tailscale-bin` when the CLI is outside `PATH`.
+
+Endpoints are `GET /api/v1/overview`, `/api/v1/health`, `/api/v1/projects`, `/api/v1/projects/:id`, `/api/v1/todos`, `/api/v1/todos/:id`, and `/api/v1/actions`. Overview and todo lists support `q` and `state` filters. Private raw files are not served.
+
+The browser workspace leads with projects rather than queue rows. A project card keeps milestone progress separate from terminal acceptance; project detail exposes the terminal outcome/rules, milestone acceptance, checkpoint revision lineage, human gates, reservations, acceptance reviews, and the independent final-judge event. Task workspaces are linked to a project only by explicit `checkpoint.project_id`, so the projection does not guess ownership from names. Unlinked tasks remain available in `task_workspaces` and the operational queue.
+
+The interface is responsive down to a narrow phone viewport, keyboard-operable for project selection, dependency-free, and safe for static export. It remains deliberately read-only: there are no approve, retry, settle, resume, or mutation controls.
 
 ## Projection and security rules
 

package/docs/operator-workspace-project.md

@@ -0,0 +1,30 @@
+# Operator workspace project contract
+
+## Terminal outcome
+
+An operator can use a local browser workspace every day to understand a Loop Engineering project's terminal contract, milestone progress and total-project status; trace checkpoint revisions, human gates, external-action reservations, acceptance reviews, and the independent final judge; and do so without granting the UI mutation authority or exposing raw/private artifacts.
+
+No single page, milestone, checkpoint, or passing test subset completes this project. Completion requires every milestone below, the release checks, and an independent final judgement to pass together.
+
+## Milestones
+
+1. **Project projection and information architecture** — project-first projection, terminal/milestone separation, task linkage, revision and acceptance timeline, project detail API, responsive read-only workspace, security regression coverage, and operator documentation. Status: implemented and independently accepted.
+2. **Daily interaction experience** — persistent URL filters and selection, accessible navigation/focus states, useful empty/error states, gate/reservation inspection, and responsive/accessibility assertions. Status: implemented and accepted.
+3. **Release hardening** — schema compatibility, realistic large-workspace benchmark, live/static export tests, documentation, package dry run, full regression, and independent final judge. Status: implemented and accepted.
+
+## Acceptance mapping
+
+- Terminal contract, milestone and project status: milestone 1 projection/API/UI tests.
+- Revision lineage and acceptance/final-judge timeline: milestone 1 task workspace fixtures.
+- Human gates and external-action reservations: milestones 1–2 projection and inspection views.
+- Safe read-only boundary: no mutation endpoints or controls; loopback default, explicit non-loopback override, redaction, XSS/path traversal checks.
+- Information architecture, interaction and responsive UI: milestones 1–2.
+- Tests, documentation and release-level acceptance: milestones 1–3.
+
+## Explicit boundaries
+
+The workspace does not approve gates, resume tasks, settle reservations, modify contracts, repair artifacts, or serve arbitrary evidence files. Those actions remain in governed CLI/control-plane workflows. A future authenticated mutation product would require a separate authority model and project contract.
+
+## Project completion rule
+
+The project reached its terminal acceptance candidate after all three milestones passed, all required checks were recorded, no required item remained unmet, and the independent 25-check final judgement returned `accept`. Milestone 1 acceptance was recorded only as a stage completion; project completion is based on the combined terminal evidence.

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