@michelj/context-guard 0.4.4 → 0.6.1

package/scripts/workbench/server.mjs

@@ -0,0 +1,1171 @@
+import http from 'node:http';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { ClaudeRuntime } from './claude-runtime.mjs';
+import { MapStore } from './store.mjs';
+import { Access, token } from './access.mjs';
+import { atomicWrite, encode, readJSON, pause, hash } from '../shared/io.mjs';
+import { generateProjections } from './projections.mjs';
+import { resolveProject, ensureProjectBinding, refreshMain, sessionBinding, sessionBindingsPath } from './project.mjs';
+import { memoryRequest, sessionMemoryDir, memoryConfigPath } from './memory.mjs';
+import { MemorySyncCoordinator } from './sync-coordinator.mjs';
+import { inspectRetiredSync } from './sync.mjs';
+import { runtimeIdentity } from './runtime.mjs';
+import { Attachments } from './attachments.mjs';
+import { ProtocolStore } from '../shared/protocol-store.mjs';
+import { ProtocolBlobs, serveBlob } from '../shared/protocol-blobs.mjs';
+import { workflowTypes } from '../shared/protocol-workflow.mjs';
+import { ProtocolDelivery, controlReport, executionNotifications, executionPrompt } from './protocol-delivery.mjs';
+import { DeviceConnection } from './protocol-device.mjs';
+import { ensureNamedProxy } from './named.mjs';
+import { defaultDirectoryAvailability, registeredProject, rememberProject } from './registry.mjs';
+import { WorkbenchSnapshots } from '../shared/protocol-snapshots.mjs';
+import { ProtocolMap, verifyChangeReferences } from '../shared/protocol-map.mjs';
+import { lookupRepository } from './protocol-repository.mjs';
+import { messageHandler, sendMessage } from './protocol-client.mjs';
+import { fail as protocolFail, validateMessage } from '../shared/protocol.mjs';
+import { MapError, entries, validate, diffTrees, restoreSessionWorkItemOperations, scopeChangesToSession, scopeDocumentToSession } from '../shared/map-model.mjs';
+export const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+export const statePath = root => path.join(root, '.codex/context/private/workbench.json');
+export const projectStatePath = project => project.kind === 'git' ? path.join(project.sharedDir, 'workbench.json') : statePath(project.worktreeRoot);
+export const projectLockPath = project => project.kind === 'git' ? path.join(project.sharedDir, 'node-workbench.lock') : path.join(project.worktreeRoot, '.codex/context/private/node-workbench.lock');
+const execFileAsync = promisify(execFile);
+
+export async function reportVerifiedControl(store, principal, send, message) {
+  const execution = await store.activeExecution(principal, message.session);
+  const alreadyApplied = await store.controlReportApplied(principal, message);
+  if ((!alreadyApplied && execution?.taskId !== message.payload.taskId) ||
+      (message.payload.action === 'resume' && execution?.closed)) protocolFail('CONFLICT', 'Control does not match the current task');
+  const report = controlReport(message);
+  await send(report);
+  await store.receiveNotification(principal, report);
+  return report;
+}
+
+function missingCommitFields(input) {
+  const missing = [];
+  if (typeof input?.baseVersion !== 'string' || !input.baseVersion) missing.push('baseVersion');
+  if (!Array.isArray(input?.operations)) missing.push('operations');
+  return missing;
+}
+
+export async function prepareSessionCommit(store, input, actor, sessionId) {
+  if (!sessionId || !input?.recoveryOf) {
+    const missing = missingCommitFields(input);
+    if (missing.length) throw new MapError('INVALID_ARGUMENT', `Missing required field${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}`);
+    return { input: sessionId ? { ...input, operations: restoreSessionWorkItemOperations(store.doc, input.operations, sessionId) } : input, actor };
+  }
+  const operation = Array.isArray(input.operations) && input.operations.length === 1 ? input.operations[0] : null;
+  const bugId = ['attach-bug', 'update-bug'].includes(operation?.type) ? operation.bug?.id || '' : '';
+  const expected = bugId ? `bug:${sessionId}:${bugId}` : '';
+  const prior = expected && input.recoveryOf === expected ? await store.operation(expected) : null;
+  const original = prior?.event;
+  const originalOperation = original?.operations?.find(item => item?.type === 'attach-bug' && item?.bug?.id === bugId);
+  const sameTarget = operation?.type === 'update-bug' || originalOperation?.id === operation?.id;
+  if (!prior?.result?.committed || original?.actor?.sessionId !== sessionId || !originalOperation || !sameTarget) {
+    throw new MapError('FORBIDDEN_RECOVERY', 'Bug recovery requires this Session\'s committed original attachment receipt', 403);
+  }
+  return {
+    input: { ...input, operations: [{ type: 'recover-bug', id: originalOperation.id, bug: { ...originalOperation.bug, ...operation.bug } }] },
+    actor: { kind: 'recovery', sessionId, projectId: actor.projectId, worktreeId: actor.worktreeId },
+  };
+}
+
+export async function queueCodexMessage({ sessionId, message, root }, { run = execFileAsync, platform = process.platform } = {}) {
+  if (platform === 'darwin') {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(sessionId)) throw Object.assign(new Error('Desktop delivery requires a Session UUID'), { code: 'INVALID_SESSION' });
+    try {
+      await run('/usr/bin/open', ['-g', `codex://threads/${sessionId}`], { cwd: root, timeout: 15000, maxBuffer: 65536 });
+    } catch {
+      // No task has been queued yet: opening can be retried safely, including
+      // after an opener timeout. Never turn this into uncertain task acceptance.
+      throw Object.assign(new Error('Could not request the existing desktop Session; no task was queued'), { code: 'DESKTOP_OPEN_FAILED' });
+    }
+  }
+  // Opening requests a load; only the Session's started report proves execution.
+  // The durable native queue also covers loading that finishes after this call.
+  await run(process.env.CONTEXT_GUARD_CODEX_COMMAND || 'codex', ['queue', '--thread', sessionId, '--message', message], {
+    cwd: root,
+    encoding: 'utf8',
+    windowsHide: true,
+    timeout: 15000,
+    maxBuffer: 1024 * 1024,
+  });
+}
+
+// A native Claude turn can be terminated by its timeout without emitting the
+// Claude Interrupt hook. Keep the workflow authoritative by deriving one
+// stable interruption report from the persisted delivery and current local
+// execution. The DeviceConnection outbox makes retries idempotent.
+export function interruptedTaskReport(session, execution, native) {
+  if (native?.status !== 'interrupted' || !native.deliveryId || !native.at || !execution?.taskId || !session?.id || !Number.isSafeInteger(session.generation)) return null;
+  return { v: 2, id: `interrupt:${session.id}:${native.deliveryId}`, type: 'task.report', session,
+    payload: { taskId: execution.taskId, stage: 'interrupted', data: { reason: native.error || 'Local Claude execution interrupted', occurredAt: native.at } } };
+}
+function loopbackJSON(target, { method = 'GET', headers = {}, body, timeout = 600, maxBytes = 1024 * 1024 } = {}) {
+  return new Promise(resolve => {
+    let settled = false;
+    const finish = value => { if (!settled) { settled = true; resolve(value); } };
+    let req;
+    try {
+      req = http.request(target, { method, headers: { Connection: 'close', ...headers }, agent: false }, res => {
+        const chunks = [];
+        let size = 0;
+        res.on('data', chunk => {
+          size += chunk.length;
+          if (size > maxBytes) {
+            finish({ ok: false, status: 502, value: { error: { code: 'RESPONSE_TOO_LARGE', message: 'Workbench response exceeds the client size limit' } } });
+            req.destroy();
+          }
+          else chunks.push(chunk);
+        });
+        res.on('end', () => {
+          try { finish({ ok: res.statusCode >= 200 && res.statusCode < 300, status: res.statusCode, value: JSON.parse(Buffer.concat(chunks).toString('utf8')) }); }
+          catch { finish(null); }
+        });
+        res.on('error', () => finish(null));
+      });
+      req.setTimeout(timeout, () => { req.destroy(); finish(null); });
+      req.on('error', () => finish(null));
+      if (body !== undefined) req.write(body);
+      req.end();
+    } catch { req?.destroy(); finish(null); }
+  });
+}
+export async function health(state) {
+  // A service may disappear between repeated migration probes. Node 24's
+  // pooled fetch/undici path can throw setTypeOfService EINVAL outside the
+  // request promise on macOS, so lifecycle control uses an unpooled socket.
+  const result = await loopbackJSON(new URL('/__context_guard/health', state.url));
+  return result?.ok ? result.value : null;
+}
+export { loopbackJSON };
+export async function startServer({ root, port = 8877, host = '127.0.0.1', fault, messageQueue = queueCodexMessage, repositoryLookup = lookupRepository } = {}) {
+  if (!['127.0.0.1', 'localhost'].includes(host)) throw new MapError('INVALID_HOST', 'Workbench only listens on loopback');
+  const directory = await defaultDirectoryAvailability();
+  if (directory.unavailable) {
+    const which = directory.overridden ? 'configured directory' : 'default directory';
+    throw new MapError('START_FAILED', `The ${which} ${directory.path} is unavailable (${directory.code})`, 503);
+  }
+  root = await fs.realpath(path.resolve(root));
+  let project = await resolveProject(root);
+  await inspectRetiredSync(project);
+  project = await ensureProjectBinding(project);
+  const claudeRuntime = new ClaudeRuntime(path.join(project.sharedDir, 'claude-runtime'));
+  const ctx = path.join(root, '.codex/context'), lock = projectLockPath(project), sharedState = projectStatePath(project);
+  const namedFile = project.kind === 'git' ? path.join(project.sharedDir, 'named-entry.json') : path.join(ctx, 'private/named-entry.json');
+  let namedEntry = await readJSON(namedFile, null), openClaimed = false;
+  const validNamedOrigin = value => /^http:\/\/[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.localhost:[1-9][0-9]{0,4}$/.test(value || '') && Number(new URL(value).port) > 0 && Number(new URL(value).port) <= 65535;
+  if (namedEntry && (!validNamedOrigin(namedEntry.origin) || typeof namedEntry.proxyToken !== 'string' || namedEntry.proxyToken.length < 32)) throw new MapError('INVALID_ORIGIN', 'Invalid saved named entry; configuration preserved');
+  await fs.mkdir(path.dirname(lock), { recursive: true });
+  const instance = token();
+  for (let i = 0; i < 2; i++) {
+    try { const h = await fs.open(lock, 'wx', 0o600); await h.writeFile(encode({ pid: process.pid, instance })); await h.close(); break; }
+    catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      const owner = await readJSON(lock, null);
+      if (!owner?.pid) throw new MapError('STARTING', 'Another instance is starting; retry shortly', 409);
+      let alive = true; try { process.kill(owner.pid, 0); } catch (err) { if (err.code === 'ESRCH') alive = false; }
+      if (alive) throw new MapError('ALREADY_RUNNING', 'Project already has a Node service', 409);
+      await fs.unlink(lock);
+    }
+  }
+  const adminToken = token(), humanToken = token(), agentTokens = new Map(), peers = new Map();
+  const protocolStore = new ProtocolStore(path.join(project.sharedDir, 'interface-v2'));
+  const protocolBlobs = new ProtocolBlobs(path.join(project.sharedDir, 'interface-v2', 'blobs'));
+  const protocolSnapshots = new WorkbenchSnapshots(path.join(project.sharedDir, 'interface-v2', 'snapshots'));
+  const protocolMap = new ProtocolMap(path.join(project.sharedDir, 'interface-v2', 'map-intents'));
+  const backendPrincipal = { repositoryId: project.projectId, deviceId: project.projectId, agentId: project.projectId, role: 'device' };
+  let device;
+  let deviceHeartbeatTimer = null, deviceHeartbeatRunning = null, deviceHeartbeatStopping = false;
+  const ciConnections = new Map();
+  const ciRetries = new Map();
+  const taskDelivery = new ProtocolDelivery(path.join(project.sharedDir, 'interface-v2', 'task-deliveries'), {
+    codex: input => messageQueue({ sessionId: input.sessionId, message: input.message, root: input.root }),
+    claude: { deliver: input => claudeRuntime.deliverGuidance(input), received: input => claudeRuntime.receivedGuidance(input) },
+  });
+  const reportControl = message => reportVerifiedControl(protocolStore, backendPrincipal, report => device.send(report), message);
+  const resumeAcceptedByHost = async message => {
+    const recovery = await readJSON(claudeRuntime.jobFile(message.session.id, `recovery:cloud-${hash(message.id)}`), null);
+    if (recovery && recovery.state !== 'failed') return true;
+    const delivery = await readJSON(path.join(taskDelivery.directory,
+      `${hash(`${message.session.generation}:${message.id}:resume`)}.json`), null);
+    return delivery?.state === 'received';
+  };
+  const acceptResumeControl = async (message, session) => {
+    if (await protocolStore.resumeControlApplied(backendPrincipal, message)) return true;
+    if (!await resumeAcceptedByHost(message)) {
+      const taskPrompt = await executionPrompt(message, (ref, version) => device.send({ v: 2, id: randomUUID(), type: 'object.read', session: message.session, payload: { ref, version } }));
+      const prompt = `${taskPrompt}\n宿主绑定的当前工作树：${session.worktreeRoot || root}\n所有 Context Guard 命令的 --root 使用这个工作树，不使用模板或主仓库目录。mainVersion 是记忆版本，不是 Git SHA。`;
+      const native = await claudeRuntime.status(session.id);
+      if (native.status === 'interrupted' && native.deliveryId) {
+        await claudeRuntime.recover(session.id, { operationId: `cloud-${hash(message.id)}`, deliveryId: native.deliveryId, message: prompt }, session.worktreeRoot || root);
+      } else if (native.status === 'stopped') {
+        await taskDelivery.deliver({ id: `${message.session.generation}:${message.id}:resume`, platform: 'claude', sessionId: session.id,
+          root: session.worktreeRoot || root, message: prompt });
+      } else return false;
+    }
+    await reportControl(message);
+    return true;
+  };
+  let taskDeliveryRetry = null;
+  const ciChannel = (sessionId, connection) => {
+    if (!ciConnections.has(sessionId) || ciConnections.get(sessionId).origin !== connection.origin) {
+      const channel = new DeviceConnection({ directory: path.join(project.sharedDir, 'interface-v2', 'ci', sessionId), origin: connection.origin, allowLoopback: true,
+        transport: (origin, credential, message, options) => sendMessage(origin, credential, message, { ...options, ciSessionId: sessionId }) });
+      channel.file = connection.file; // Device login is shared; this is not another heartbeat service.
+      ciConnections.set(sessionId, channel);
+    }
+    return ciConnections.get(sessionId);
+  };
+  let deviceServiceCheck = null, deviceServiceCheckedAt = 0;
+  const ensureDeviceService = async () => {
+    if (deviceServiceCheck) return deviceServiceCheck;
+    if (Date.now() - deviceServiceCheckedAt < 10000) return;
+    deviceServiceCheck = (async () => {
+      const state = await readJSON(sharedState, null);
+      if (state?.instance !== instance || !await device?.connected()) return;
+      if ((await registeredProject(project))?.runtime?.instance !== instance) await rememberProject(project, { state });
+      await ensureNamedProxy();
+      deviceServiceCheckedAt = Date.now();
+    })().finally(() => { deviceServiceCheck = null; });
+    return deviceServiceCheck;
+  };
+  const projectDevice = async () => {
+    const config = await readJSON(memoryConfigPath(project), null);
+    if (!config?.url) return null;
+    if (!device || device.origin !== config.url) {
+      clearInterval(deviceHeartbeatTimer); deviceHeartbeatTimer = null;
+      await deviceHeartbeatRunning;
+      await device?.close();
+      device = new DeviceConnection({ directory: path.join(project.sharedDir, 'interface-v2'), origin: config.url, allowLoopback: true });
+    }
+    if (await device.connected()) device.start({
+      onSessionCreations: async requests => {
+        if (!Array.isArray(requests) || requests.length > 20) protocolFail('INVALID_ARGUMENT', 'Bounded Session creation batch required');
+        for (const request of requests) {
+          try {
+            if (!access.binding(request.templateSessionId)) protocolFail('FORBIDDEN', 'The template is no longer bound to this backend');
+            const created = await claudeRuntime.provision(request, { baseRef: project.mainRef, start: false });
+            await registerSession({ sessionId: request.sessionId, worktreeRoot: created.root }, { connection: device });
+          } catch (error) {
+            device.lastError = error.code || 'SESSION_CREATION_FAILED';
+            await device.recordCreationFailure(request.id, error.code);
+          }
+        }
+      },
+      sessions: async () => {
+        if (!taskDeliveryRetry) taskDeliveryRetry = taskDelivery.retryBusy(async input => {
+          if (input.platform !== 'claude' || !access.binding(input.sessionId)) return false;
+          const plan = /^Context Guard：Plan (\S+)@(\S+) 审核/.exec(input.message);
+          if (!plan && input.deliveryType !== 'task.message') return false;
+          const binding = await protocolStore.registeredBinding(backendPrincipal, input.sessionId);
+          const execution = binding && await protocolStore.activeExecution(backendPrincipal, { id: input.sessionId, generation: binding.generation });
+          if (input.deliveryType === 'task.message') {
+            if (execution?.closed || execution?.taskId !== input.taskId ||
+                input.planRef && (execution.plan?.ref !== input.planRef || execution.plan.version !== input.planVersion)) return false;
+          } else if (execution?.closed || execution?.plan?.ref !== plan[1] || execution.plan.version !== plan[2]) return false;
+          const status = (await claudeRuntime.status(input.sessionId)).status;
+          return status === 'stopped' || input.deliveryType === 'task.message' && status === 'interrupted';
+        }).catch(error => { device.lastError = error.code || 'TASK_DELIVERY_RETRY_FAILED'; })
+          .finally(() => { taskDeliveryRetry = null; });
+        const registered = [], identities = new Map((await access.sessionRegistry()).map(item => [item.id, item]));
+        const heads = await protocolStore.queueHeads(backendPrincipal), queued = new Set(heads.map(head => head.session.id));
+        // A freshly provisioned Session has no queued task yet: Cloud waits for
+        // its stopped heartbeat before dispatching. Include every registered
+        // binding so direct registration cannot deadlock on an empty queue.
+        for (const identity of identities.values()) {
+          if (queued.has(identity.id) || !access.binding(identity.id)) continue;
+          const binding = await protocolStore.registeredBinding(backendPrincipal, identity.id).catch(() => null);
+          if (binding) heads.push({ session: { id: identity.id, generation: binding.generation } });
+        }
+        for (const head of heads) {
+          if (!access.binding(head.session.id)) continue;
+          try {
+            if (await device.bindingReady(await protocolStore.registeredBinding(backendPrincipal, head.session.id))) {
+              const identity = identities.get(head.session.id), heartbeat = { ...head.session, ackedSeq: 0 };
+              if (identity?.name) heartbeat.name = identity.name;
+              if (identity?.platform && identity.platform !== 'unknown') heartbeat.platform = identity.platform;
+              const native = identity?.platform === 'claude' ? await claudeRuntime.status(head.session.id) : null;
+              if (native?.role === 'ci') ciChannel(head.session.id, device);
+              if (native?.name) heartbeat.name = native.name;
+              const execution = await protocolStore.activeExecution(backendPrincipal, head.session).catch(() => null);
+              for (const control of await protocolStore.pendingControls(backendPrincipal, head.session, 'complete')) {
+                if (execution?.taskId !== control.payload.taskId) continue;
+                await reportControl(control).catch(error => { device.lastError = error.code || 'CLOSE_REPORT_FAILED'; });
+              }
+              let resumed = false;
+              if (native?.role === 'executor' && execution && !execution.closed) {
+                for (const control of await protocolStore.pendingControls(backendPrincipal, head.session, 'resume')) {
+                  if (control.payload.taskId !== execution.taskId) continue;
+                  resumed = await acceptResumeControl(control, identity).catch(error => {
+                    device.lastError = error.code || 'RESUME_REPORT_FAILED'; return false;
+                  });
+                }
+              }
+              if (native?.role === 'executor' && native.status === 'interrupted' && !resumed) {
+                const report = interruptedTaskReport(head.session, execution, native);
+                if (report) await device.send(report).catch(error => { device.lastError = error.code || 'INTERRUPTION_REPORT_FAILED'; });
+              }
+              heartbeat.execution = native?.configured && Date.parse(native.at) >= (Date.parse(identity?.statusSeen) || 0)
+                ? { status: native.status, at: native.at }
+                : { status: ['active', 'stopped'].includes(identity?.status) ? identity.status : 'unknown', at: identity?.statusSeen || '' };
+              registered.push(heartbeat);
+            }
+          } catch (error) { device.lastError = error.code || 'UNAVAILABLE'; }
+        }
+        return registered;
+      },
+      apply: async message => {
+        if (!access.binding(message.session.id)) protocolFail('FORBIDDEN', 'Session registration was revoked');
+        const result = (await protocolStore.receiveNotification(backendPrincipal, message)).data;
+        // A confirmed resumed report is stronger than a lost native acceptance
+        // receipt. Replayed controls must not start another model turn.
+        if (await protocolStore.resumeControlApplied(backendPrincipal, message)) return { ...result, deliveryState: 'stored', reason: 'Resume control was already applied' };
+        if (executionNotifications.has(message.type) || message.type === 'review.result' && message.payload.kind === 'plan') {
+          const session = (await access.sessionRegistry()).find(item => item.id === message.session.id);
+          if (!session) protocolFail('FORBIDDEN', 'Host Session is unavailable');
+          if (!['codex', 'claude'].includes(session.platform)) return result;
+          const target = await storeFor(project.kind === 'git' ? `session:${session.id}` : 'main');
+          if (message.type === 'task.assign' && message.payload.nodeIds.some(id => !access.grants(session.id, target.doc, 'read').includes(id))) protocolFail('FORBIDDEN', 'Assigned node access was revoked');
+          try {
+            if (message.type === 'task.control' && message.payload.action === 'complete') {
+              await reportControl(message);
+              return { ...result, deliveryState: 'received' };
+            }
+            if (session.platform === 'claude' && message.type === 'task.control' && message.payload.action === 'resume') {
+              const execution = await protocolStore.activeExecution(backendPrincipal, message.session);
+              if (execution?.taskId !== message.payload.taskId || execution.closed) protocolFail('CONFLICT', 'Resume control does not match an active task');
+              return await acceptResumeControl(message, session)
+                ? { ...result, deliveryState: 'received' }
+                : { ...result, deliveryState: 'stored', reason: 'Native turn is busy; resume control is queued' };
+            }
+            const taskPrompt = await executionPrompt(message, (ref, version) => device.send({ v: 2, id: randomUUID(), type: 'object.read', session: message.session, payload: { ref, version } }));
+            const prompt = `${taskPrompt}\n宿主绑定的当前工作树：${session.worktreeRoot || root}\n所有 Context Guard 命令的 --root 使用这个工作树，不使用模板或主仓库目录。mainVersion 是记忆版本，不是 Git SHA。`;
+            const ci = message.type === 'ci.request' ? await claudeRuntime.ciReceiver(session.id) : null;
+            if (ci && (!access.binding(ci.sessionId) || access.binding(ci.sessionId).worktreeRoot !== ci.root || ci.root === session.worktreeRoot)) protocolFail('FORBIDDEN', 'CI receiver binding is not independent');
+            await taskDelivery.deliver({ id: `${message.session.generation}:${message.id}`, platform: ci ? 'claude' : session.platform, sessionId: ci?.sessionId || session.id, root: ci?.root || session.worktreeRoot || root, message: prompt,
+              ...(message.type === 'task.message' ? { deliveryType: 'task.message', taskId: message.payload.taskId,
+                ...(message.payload.planRef ? { planRef: message.payload.planRef, planVersion: message.payload.planVersion } : {}) } : {}),
+              ...(ci ? { execution: { session: message.session, taskId: message.payload.taskId, sourceSha: message.payload.sourceSha, ciTodoRef: message.payload.ciTodoRef, references: message.payload.references || {} } } : {}) });
+            return { ...result, deliveryState: 'received' };
+          } catch (error) {
+            if (error?.details?.deliveryState === 'uncertain') return { ...result, deliveryState: 'uncertain', reason: 'Native host acceptance could not be confirmed' };
+            if (error?.details?.deliveryState === 'failed') {
+              // The notification is already durable in the local protocol
+              // journal. A busy/interrupted native model must not head-of-line
+              // block later Plan, handoff or CI messages for the whole project.
+              return { ...result, deliveryState: 'stored', reason: 'Native host is unavailable; continue protocol synchronization' };
+            }
+            throw error;
+          }
+        }
+        return { ...result, deliveryState: 'stored' };
+      },
+      onSession: head => {
+        syncCoordinators.get(`session:${head.id}`)?.projectHeartbeat(head);
+        const ci = ciConnections.get(head.id);
+        if (ci && !ciRetries.has(head.id)) ciRetries.set(head.id, ci.retryPending().catch(error => { device.lastError = error.code || 'CI_RETRY_FAILED'; }).finally(() => ciRetries.delete(head.id)));
+      },
+      onError: (error, source) => {
+        device.lastError = error.code || 'UNAVAILABLE';
+        if (source === 'heartbeat' && !(error instanceof AggregateError)) for (const [view, coordinator] of syncCoordinators) if ((!error.details?.sessionId || view === `session:${error.details.sessionId}`) && coordinator.managed && !coordinator.status.conflict) {
+          coordinator.update({ status: error.code === 'UNAUTHORIZED' ? 'error' : 'offline', error: device.lastError });
+        }
+      },
+    });
+    if (await device.connected() && !deviceHeartbeatTimer) {
+      const beat = () => {
+        if (deviceHeartbeatRunning || deviceHeartbeatStopping) return;
+        deviceHeartbeatRunning = (async () => {
+          const request = await device.runtime.prepare();
+          const response = await fetch(new URL('/api/v2/heartbeat', request.origin), {
+            method: 'POST', redirect: 'error', signal: AbortSignal.timeout(10_000),
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify([{ credential: request.credential, message: request.message }]),
+          });
+          if (!response.ok || !response.headers.get('content-type')?.includes('application/json')) protocolFail('UNAVAILABLE', 'Device heartbeat endpoint unavailable');
+          const replies = await response.json(), reply = Array.isArray(replies) && replies.find(item => item?.id === request.message.id);
+          if (!reply || typeof reply.ok !== 'boolean') protocolFail('UNAVAILABLE', 'Device heartbeat receipt is invalid');
+          device.runtime.accept(reply);
+          device.lastError = null;
+        })().catch(error => { device.lastError = error.code || 'UNAVAILABLE'; })
+          .finally(() => { deviceHeartbeatRunning = null; });
+      };
+      deviceHeartbeatTimer = setInterval(beat, 5000); deviceHeartbeatTimer.unref(); beat();
+    }
+    await ensureDeviceService();
+    return device;
+  };
+  const access = await new Access(root, project.kind === 'git' ? {
+    file: path.join(project.sharedDir, 'workbench-access.json'),
+    bindingsFile: sessionBindingsPath(project),
+  } : {}).init();
+  let stopAccessWatch = () => {};
+  const stores = new Map(), projectionQueues = new Map(), storeViews = new WeakMap(), syncCoordinators = new Map(), attachmentStores = new WeakMap();
+  let mainStore, mainSource = null;
+  const attachmentsFor = store => {
+    let attachments = attachmentStores.get(store);
+    if (!attachments) {
+      attachments = new Attachments(store.root);
+      attachmentStores.set(store, attachments);
+    }
+    return attachments;
+  };
+  const sourceFile = path.join(project.sharedDir, 'main-source.json');
+  let server, base;
+  async function updateMainBaseline(source, { force = false } = {}) {
+    if (project.kind !== 'git') return source;
+    const mainDir = path.join(project.sharedDir, 'main');
+    const mainFile = path.join(mainDir, 'map.json');
+    await fs.mkdir(mainDir, { recursive: true });
+    if (project.bindingRequired) {
+      if (!await readJSON(mainFile, null)) await atomicWrite(mainFile, encode({ v: 1, project: path.basename(project.worktreeRoot), bootstrap: 'pending', flows: [], root: null }));
+      return { ...source, status: 'binding-required', needsReconcile: true };
+    }
+    try {
+      const { snapshot } = await memoryRequest(project, 'main');
+      if (!snapshot) throw new MapError('BASELINE_PENDING', 'No main baseline has been published', 409);
+      validate(snapshot.memory.map);
+      await atomicWrite(mainFile, encode(snapshot.memory.map));
+      return { ...source, status: snapshot.mainSha === source.sha ? 'ready' : 'stale', memoryVersion: snapshot.version, baselineSha: snapshot.mainSha, needsReconcile: snapshot.mainSha !== source.sha };
+    } catch (error) {
+      // Keep a previously verified baseline; never replace it with an empty map on disconnect.
+      if (!await readJSON(mainFile, null)) await atomicWrite(mainFile, encode({ v: 1, project: path.basename(project.worktreeRoot), bootstrap: 'pending', flows: [], root: null }));
+      return { ...source, status: error.code || 'memory-unavailable', needsReconcile: true };
+    }
+  }
+  const send = (res, code, data) => { res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' }); res.end(JSON.stringify(data)); };
+  function broadcast(type, data, viewId = null) {
+    for (const peer of peers.values()) if (peer.res && !peer.res.destroyed) {
+      if (viewId && peer.viewId !== viewId) continue;
+      if (peer.res.writableLength > 2 * 1024 * 1024) { peer.res.destroy(); continue; }
+      peer.res.write(`event: ${type}\ndata: ${JSON.stringify(data)}\n\n`);
+    }
+  }
+  async function createStore(viewId, storeRoot, options = {}) {
+    let target;
+    const { syncDirectory, sessionId, ...storeOptions } = options;
+    if (sessionId && syncDirectory) await inspectRetiredSync(await resolveProject(storeRoot));
+    const projectionRoot = options.projectionRoot || storeRoot;
+    const projectMap = project.kind === 'git' && viewId === 'main'
+      ? async () => true
+      : (doc, version) => {
+          const previous = projectionQueues.get(viewId) || Promise.resolve();
+          const projectionDoc = sessionId ? scopeDocumentToSession(doc, sessionId) : doc;
+          const job = previous.then(() => target.version === version ? generateProjections(projectionRoot, projectionDoc, version, () => target.version === version, { sessionId }) : false);
+          projectionQueues.set(viewId, job.catch(() => {})); return job;
+        };
+    // In Cloud mode the local journal is an observation cache, not the Map or
+    // the pending write queue. Preserve its raw backup and mark a history gap;
+    // never erase a pending commit, operation receipt, or unsent edit.
+    const recoverJournal = !!sessionId && !!syncDirectory && !!await readJSON(memoryConfigPath(project), null);
+    target = new MapStore(storeRoot, { fault, project: projectMap, ...storeOptions, recoverJournal });
+    await target.init();
+    storeViews.set(target, new Set([viewId]));
+    target.on('change', state => {
+      for (const targetView of storeViews.get(target) || []) broadcast('state', { ...state, viewId: targetView, source: sourceFor(targetView) }, targetView);
+    });
+    stores.set(viewId, target);
+    if (sessionId && syncDirectory) {
+      const sessionProject = await resolveProject(storeRoot);
+      const connection = await projectDevice();
+      const coordinator = new MemorySyncCoordinator({ project: sessionProject, sessionId, store: target, directory: syncDirectory,
+        managed: !!connection && await connection.supports('private-map-heads'),
+        display: async () => {
+          const identity = (await access.sessionRegistry()).find(item => item.id === sessionId);
+          return identity?.name ? { name: identity.name, platform: identity.platform } : null;
+        } });
+      coordinator.on('change', status => broadcast('cloud-sync', status, viewId));
+      syncCoordinators.set(viewId, coordinator);
+      await coordinator.start();
+    }
+    return target;
+  }
+  function viewFor(actor, url) {
+    if (actor.kind === 'agent') return project.kind === 'git' ? `session:${actor.sessionId}` : 'main';
+    const requested = String(url.searchParams.get('view') || 'main');
+    if (requested === 'main') return requested;
+    if (!requested.startsWith('session:') || !access.binding(requested.slice('session:'.length))) throw new MapError('UNKNOWN_VIEW', 'Select a registered Session view', 404);
+    return requested;
+  }
+  async function ensureSessionMap(sessionProject, sessionId) {
+    const dir = sessionMemoryDir(sessionProject, sessionId), file = path.join(dir, 'map.json');
+    const baseFile = path.join(dir, 'base-main.json');
+    const [existing, baseline] = await Promise.all([readJSON(file, null), readJSON(baseFile, null)]);
+    let main = null, remoteSession = null;
+    try {
+      [main, remoteSession] = await Promise.all([
+        memoryRequest(project, 'main').then(result => result.snapshot),
+        memoryRequest(sessionProject, `sessions/${encodeURIComponent(sessionId)}`).then(result => result.snapshot),
+      ]);
+    }
+    catch (error) { if (error.code !== 'MEMORY_NOT_CONFIGURED') throw error; }
+    if (!existing) {
+      const seed = remoteSession?.memory?.map || main?.memory?.map || await readJSON(path.join(sessionProject.worktreeRoot, '.codex/context/map.json'));
+      if (main) await atomicWrite(baseFile, encode({ version: main.version, map: main.memory.map }));
+      await atomicWrite(file, encode(seed));
+    } else if (main && !baseline?.map) {
+      const legacySeed = await readJSON(path.join(sessionProject.worktreeRoot, '.codex/context/map.json'), null);
+      if (hash(encode(existing)) === hash(encode(main.memory.map))) {
+        await atomicWrite(baseFile, encode({ version: main.version, map: main.memory.map }));
+      } else if (legacySeed && hash(encode(existing)) === hash(encode(legacySeed))) {
+        await atomicWrite(path.join(dir, 'before-main-baseline.json'), encode(existing));
+        await atomicWrite(file, encode(main.memory.map));
+        await atomicWrite(baseFile, encode({ version: main.version, map: main.memory.map }));
+      } else {
+        throw new MapError('SESSION_BASELINE_REQUIRED', 'Session cache predates the confirmed main baseline and contains changes; preserve it and reconcile explicitly', 409);
+      }
+    }
+    return { dir, file };
+  }
+  async function storeFor(viewId) {
+    if (viewId === 'main') return stores.get(viewId);
+    const sessionId = viewId.startsWith('session:') ? viewId.slice('session:'.length) : '';
+    const binding = access.binding(sessionId);
+    if (!binding?.worktreeRoot) throw new MapError('UNKNOWN_SESSION', 'Session is not bound to a worktree', 404);
+    const sessionProject = await resolveProject(binding.worktreeRoot);
+    if (sessionProject.projectId !== project.projectId) throw new MapError('PROJECT_MISMATCH', 'Session worktree belongs to another project', 403);
+    if (stores.has(viewId)) return stores.get(viewId);
+    const { dir, file } = await ensureSessionMap(sessionProject, sessionId);
+    return createStore(viewId, sessionProject.worktreeRoot, { file, runtime: path.join(dir, 'sync'), eventsFile: path.join(dir, 'changes.jsonl'), projectionRoot: dir, sessionId, syncDirectory: dir });
+  }
+  function sourceFor(viewId) {
+    if (viewId === 'main') return mainSource;
+    const binding = access.binding(viewId.slice('session:'.length));
+    return binding ? { status: 'worktree', branch: binding.branch || '', sha: binding.head || '', worktreeRoot: binding.worktreeRoot, baseMainSha: binding.baseMainSha || '' } : null;
+  }
+  const stateFor = (viewId, target, full = true) => ({ ...target.state(full), viewId, source: sourceFor(viewId) });
+  let refreshing = null;
+  function refreshProject() {
+    if (refreshing) return refreshing;
+    refreshing = (async () => {
+      project = await resolveProject(root);
+      const refreshed = await refreshMain(project);
+      mainSource = await updateMainBaseline({ ...mainSource, ...refreshed });
+      await mainStore.serial(() => mainStore.refresh());
+      await atomicWrite(sourceFile, encode(mainSource));
+      broadcast('state', stateFor('main', mainStore, false), 'main');
+      return { projectId: project.projectId, source: mainSource };
+    })().finally(() => { refreshing = null; });
+    return refreshing;
+  }
+  async function cloudSyncStatus(viewId = 'main') {
+    if (syncCoordinators.has(viewId)) return syncCoordinators.get(viewId).snapshot();
+    return { configured: false, status: 'disabled', cursor: 0, receivedCursor: 0, conflict: null, serviceAlive: false };
+  }
+  function viewPeers(viewId) { return [...peers.values()].filter(peer => !viewId || peer.viewId === viewId); }
+  function pendingPeers(viewId) { return viewPeers(viewId).filter(p => p.dirty || !p.res || p.res.destroyed).map(p => p.id); }
+  function evictPeer(peer) {
+    if (!peer) return;
+    peer.res?.end();
+    peers.delete(`${peer.viewId}:${peer.id}`);
+    if (!peers.size) openClaimed = false;
+  }
+  async function registerSession(input, { connection } = {}) {
+    const prepared = await preparedSessionBinding(input);
+    if (prepared.previous && !prepared.sameWorktree) {
+      const view = `session:${prepared.sessionId}`;
+      await fence(view);
+      for (const [credential, actor] of agentTokens) if (actor.sessionId === prepared.sessionId) agentTokens.delete(credential);
+      if (syncCoordinators.has(view)) { await syncCoordinators.get(view).close(); syncCoordinators.delete(view); }
+      if (stores.has(view)) { await stores.get(view).close(); stores.delete(view); }
+      for (const peer of viewPeers(view)) peer.res?.end();
+    }
+    if (!(await access.sessionExists(prepared.sessionId, prepared.sessionProject.worktreeRoot))) throw new MapError('UNKNOWN_SESSION', 'Session must exist in the local host before registration', 403);
+    const identity = { repositoryId: project.projectId, deviceId: project.projectId, agentId: prepared.sessionId, role: 'executor' };
+    const previousProtocolBinding = await protocolStore.registeredBinding(backendPrincipal, prepared.sessionId);
+    const bindMessage = { v: 2, id: randomUUID(), type: 'session.bind', payload: { sessionId: prepared.sessionId, agentId: prepared.sessionId,
+      worktreeId: prepared.binding.worktreeId, expectedBindingVersion: previousProtocolBinding?.version || '' } };
+    const unchanged = previousProtocolBinding?.worktreeId === prepared.binding.worktreeId && previousProtocolBinding?.agentId === prepared.sessionId;
+    const protocolBinding = unchanged ? { session: { id: prepared.sessionId, generation: previousProtocolBinding.generation }, bindingVersion: previousProtocolBinding.version } : (await protocolStore.handle(identity, bindMessage, {
+      allowMigration: true, verifyBinding: (_p, payload) => payload.sessionId === prepared.sessionId && payload.worktreeId === prepared.binding.worktreeId,
+    })).data;
+    if (connection === undefined) connection = await projectDevice();
+    let cloudBinding = { status: 'disconnected' };
+    if (connection && await connection.connected()) {
+      try {
+        if (unchanged) await connection.ensureBinding(previousProtocolBinding);
+        else await connection.bind(bindMessage, protocolBinding);
+        cloudBinding = { status: 'ready' };
+      }
+      catch (error) { cloudBinding = { status: 'pending', code: error.code || 'UNAVAILABLE' }; }
+    }
+    const lazyCloudMap = connection && await connection.supports('private-map-heads');
+    const sessionFiles = project.kind === 'git' && !lazyCloudMap && !stores.has(`session:${prepared.sessionId}`) ? await ensureSessionMap(prepared.sessionProject, prepared.sessionId) : null;
+    const actor = await access.register(prepared.sessionId, prepared.binding);
+    if (sessionFiles) {
+      const sessionDocument = await readJSON(sessionFiles.file, null);
+      await access.promoteLegacyFullGrant(prepared.sessionId, sessionDocument);
+    }
+    if (sessionFiles && !stores.has(`session:${prepared.sessionId}`)) {
+      await createStore(`session:${prepared.sessionId}`, prepared.sessionProject.worktreeRoot, {
+        file: sessionFiles.file,
+        runtime: path.join(sessionFiles.dir, 'sync'),
+        eventsFile: path.join(sessionFiles.dir, 'changes.jsonl'),
+        projectionRoot: sessionFiles.dir,
+        sessionId: prepared.sessionId,
+        syncDirectory: sessionFiles.dir,
+      });
+    }
+    const credential = token(); agentTokens.set(credential, actor);
+    return { token: credential, actor, protocolBinding, cloudBinding };
+  }
+  const checkpoints = new Map();
+  const fenceDeadlineMs = Number(process.env.CONTEXT_GUARD_FENCE_MS) > 0 ? Number(process.env.CONTEXT_GUARD_FENCE_MS) : 8000;
+  async function fence(viewId, { stopping = false } = {}) {
+    const checkpoint = randomUUID();
+    const pending = new Set(viewPeers(viewId));
+    checkpoints.set(checkpoint, pending);
+    try {
+      broadcast('checkpoint', { checkpoint }, viewId);
+      // Allow a background browser to resume and flush through the named proxy.
+      // Remain below the client's 10-second request timeout and fail closed.
+      const deadline = Date.now() + (stopping ? Math.min(fenceDeadlineMs, 2000) : fenceDeadlineMs);
+      while (pending.size) {
+        const live = new Set(viewPeers(viewId));
+        for (const peer of pending) if (!live.has(peer) || !peer.res || peer.res.destroyed) pending.delete(peer);
+        if (!pending.size) break;
+        if (Date.now() >= deadline) {
+          // A hung SSE connection is not a live page. Evict it like a closed tab
+          // so Agent reads and CLI stop are not blocked indefinitely.
+          for (const peer of pending) evictPeer(peer);
+          pending.clear();
+          break;
+        }
+        await pause(15);
+      }
+      if (!stopping && pendingPeers(viewId).length) throw new MapError('UI_PENDING', 'A page has unsaved edits', 409, { peers: pendingPeers(viewId) });
+    } finally {
+      checkpoints.delete(checkpoint);
+    }
+  }
+  async function body(req) {
+    if (!String(req.headers['content-type'] || '').startsWith('application/json')) throw new MapError('CONTENT_TYPE', 'Use application/json', 415);
+    let size = 0, chunks = [];
+    for await (const chunk of req) { size += chunk.length; if (size > 16 * 1024 * 1024) throw new MapError('BODY_TOO_LARGE', 'Request exceeds 16 MiB', 413); chunks.push(chunk); }
+    try { return JSON.parse(Buffer.concat(chunks)); } catch { throw new MapError('INVALID_JSON', 'Malformed JSON'); }
+  }
+  function auth(req, url) {
+    const credential = req.headers.authorization?.replace(/^Bearer /, '') || (url.pathname === '/api/events' ? url.searchParams.get('token') : null);
+    if (credential === humanToken) return { kind: 'human', sessionId: 'workbench' };
+    const actor = agentTokens.get(credential);
+    if (!actor) throw new MapError('UNAUTHORIZED', 'Missing or expired capability', 401);
+    return actor;
+  }
+  async function preparedSessionBinding(input) {
+    const sessionId = typeof input?.sessionId === 'string' ? input.sessionId.trim() : '';
+    if (!sessionId) throw new MapError('SESSION_REQUIRED', 'A real lifecycle Session ID is required', 400);
+    const sessionProject = await resolveProject(input.worktreeRoot || root);
+    if (sessionProject.projectId !== project.projectId) throw new MapError('PROJECT_MISMATCH', 'Session worktree belongs to another project', 403);
+    const previous = access.binding(sessionId);
+    const role = input.role === undefined ? previous?.role || 'executor' : input.role;
+    if (!['executor', 'coordinator'].includes(role)) throw new MapError('INVALID_ROLE', 'Use executor or coordinator for Session context', 400);
+    const sameWorktree = previous && (previous.worktreeId === sessionProject.worktreeId
+      || !previous.gitDir && previous.worktreeRoot === sessionProject.worktreeRoot);
+    if (previous && !sameWorktree) {
+      if (!input.allowRebind) throw new MapError('SESSION_ALREADY_BOUND', 'Session is already bound to another worktree; require explicit user confirmation and --rebind', 409, {
+        worktreeRoot: previous.worktreeRoot,
+        bindingState: await fs.realpath(previous.worktreeRoot || '').then(() => 'other-worktree').catch(() => 'stale'),
+      });
+    }
+    let workbenchUrl = previous?.workbenchUrl || null;
+    if (input.workbenchUrl) {
+      const candidate = new URL(String(input.workbenchUrl));
+      candidate.search = ''; candidate.hash = '';
+      const allowedOrigin = candidate.origin === base || candidate.origin === namedEntry?.origin;
+      if (!allowedOrigin || candidate.pathname !== '/prototype/workbench.html') throw new MapError('INVALID_WORKBENCH_URL', 'Binding URL must be this project workbench page', 400);
+      workbenchUrl = candidate.href;
+    }
+    return { sessionId, sessionProject, previous, sameWorktree, binding: await sessionBinding(sessionProject, sessionId, { workbenchUrl, role }) };
+  }
+  const isHuman = actor => { if (actor.kind !== 'human') throw new MapError('FORBIDDEN', 'Requires the workbench capability', 403); };
+  try {
+    const previousSource = await readJSON(sourceFile, null);
+    const baselineSha = previousSource?.baselineSha || previousSource?.sha || project.mainSha || '';
+    mainSource = {
+      status: project.bindingRequired ? 'binding-required' : project.kind === 'git' ? 'ready' : 'local-folder',
+      branch: project.mainBranch || '', ref: project.mainRef || '', sha: project.mainSha || '', github: project.github,
+      baselineSha,
+      checkedAt: new Date().toISOString(),
+      needsReconcile: !!(baselineSha && project.mainSha && baselineSha !== project.mainSha),
+    };
+    if (project.kind === 'git') {
+      const mainDir = path.join(project.sharedDir, 'main');
+      const mainFile = path.join(mainDir, 'map.json');
+      mainSource = await updateMainBaseline(mainSource, { force: true });
+      await atomicWrite(sourceFile, encode(mainSource));
+      mainStore = await createStore('main', project.worktreeRoot, {
+        file: mainFile,
+        runtime: path.join(mainDir, 'sync'),
+        eventsFile: path.join(mainDir, 'workbench-changes.jsonl'),
+      });
+    } else {
+      await atomicWrite(sourceFile, encode(mainSource));
+      mainStore = await createStore('main', root);
+    }
+    server = http.createServer(async (req, res) => {
+      try {
+        const direct = req.headers.host === new URL(base).host;
+        const named = namedEntry && req.headers.host === new URL(namedEntry.origin).host && req.headers['x-context-guard-proxy'] === namedEntry.proxyToken;
+        if (!direct && !named) throw new MapError('HOST_REJECTED', 'Invalid Host', 403);
+        const requestOrigin = direct ? base : namedEntry.origin;
+        if (req.headers.origin && req.headers.origin !== requestOrigin) throw new MapError('ORIGIN_REJECTED', 'Cross-origin requests are not allowed', 403);
+        const url = new URL(req.url, base), route = url.pathname;
+        if (route === '/api/claude-runtime' && req.method === 'POST') {
+          if (!direct || req.headers.origin || req.headers.authorization !== `Bearer ${adminToken}`) throw new MapError('UNAUTHORIZED', 'Requires local CLI credential', 401);
+          const input = await body(req), binding = access.binding(input.sessionId);
+          if (input.recovery) {
+            if (input.config || !binding) throw new MapError('WORKTREE_MISMATCH', 'Recover only a registered Claude worktree', 409);
+            return send(res, 200, await claudeRuntime.recover(input.sessionId, input.recovery, binding.worktreeRoot));
+          }
+          if (!binding || await fs.realpath(input.config?.root || '') !== binding.worktreeRoot) throw new MapError('WORKTREE_MISMATCH', 'Configure only the bound Claude worktree', 409);
+          if (input.config.role === 'ci') {
+            const executor = access.binding(input.config.executorSessionId);
+            if (!executor || executor.worktreeRoot === binding.worktreeRoot) protocolFail('FORBIDDEN', 'CI needs an independent registered worktree');
+          }
+          return send(res, 200, await claudeRuntime.configure(input.sessionId, input.config));
+        }
+        if (route === '/api/device-heartbeat') {
+          if (!direct || req.headers.origin || req.headers.authorization !== `Bearer ${adminToken}`) throw new MapError('UNAUTHORIZED', 'Requires device service credential', 401);
+          const connected = await projectDevice();
+          if (!connected?.runtime?.prepare) throw new MapError('UNAVAILABLE', 'Cloud connection unavailable', 503);
+          if (req.method === 'GET') return send(res, 200, { ...await connected.runtime.prepare(), lastError: connected.lastError || null });
+          if (req.method === 'POST') { connected.runtime.accept(await body(req)); return send(res, 200, { accepted: true }); }
+          throw new MapError('INVALID_ARGUMENT', 'Use GET or POST', 400);
+        }
+        if (route === '/__context_guard/health' && req.method === 'GET') return send(res, 200, { ok: true, ...runtimeIdentity(), root, projectId: project.projectId, worktreeRoot: project.worktreeRoot, worktreeId: project.worktreeId, pid: process.pid, instance, namedEntry: true, namedRoot: project.kind === 'git' ? project.sharedDir : root, recovery: mainStore.blocked, rss: process.memoryUsage().rss });
+        if (route === '/__context_guard/bootstrap' && req.method === 'GET') return send(res, 200, { token: humanToken, root: `project:${project.projectId}`, projectId: project.projectId, bindingRequired: project.bindingRequired, instance, interfaceCapabilities: { deviceLogin: true }, ...runtimeIdentity() });
+        if (route === '/api/v2/coordinator-tools' && req.method === 'POST') {
+          const actor = auth(req, url);
+          if (actor.kind !== 'agent') throw new MapError('FORBIDDEN', 'Coordinator tools require a coordinator Session', 403);
+          if (access.binding(actor.sessionId)?.role !== 'coordinator') throw new MapError('FORBIDDEN', 'This Session is not a Coordinator', 403);
+          const connection = await projectDevice();
+          if (!connection || !await connection.connected()) throw new MapError('UNAVAILABLE', 'Cloud connection unavailable', 503);
+          try {
+            return send(res, 200, await connection.callCoordinatorTool(await body(req)));
+          } catch (error) {
+            throw new MapError(error.code || 'UNAVAILABLE', error.message || 'Coordinator tool failed', error.status || 503);
+          }
+        }
+        if (route === '/api/v2/messages') return messageHandler({
+          allowedOrigin: requestOrigin,
+          authenticate: request => {
+            let actor;
+            try { actor = auth(request, url); } catch { return null; }
+            return { repositoryId: project.projectId, deviceId: project.projectId, agentId: actor.sessionId, actor, role: actor.kind === 'human' ? 'human' : 'executor' };
+          },
+          handle: async (principal, input) => {
+            const connection = await projectDevice();
+            if (input.type.startsWith('auth.')) {
+              if (principal.role !== 'human') protocolFail('FORBIDDEN', 'Only the local human workbench can authorize the backend');
+              if (!connection) protocolFail('INVALID_ARGUMENT', 'Configure the project Cloud origin first');
+              let data;
+              if (input.type === 'auth.open') {
+                const current = await resolveProject(root);
+                if (!current.github || current.bindingRequired) protocolFail('INVALID_ARGUMENT', 'A verified GitHub Main remote is required');
+                const identity = await repositoryLookup(current.github.slug);
+                data = await connection.connect({ ...input, payload: { ...input.payload, repository: `https://github.com/${current.github.slug}` } }, identity);
+                await projectDevice();
+              } else data = await connection.disconnect(input);
+              return { id: input.id, ok: true, data };
+            }
+            const human = principal.role === 'human';
+            if (human && !['workbench.read', 'workbench.patch'].includes(input.type)) protocolFail('FORBIDDEN', 'This message requires an Agent Session');
+            const connected = connection && await connection.connected();
+            if (input.type === 'workbench.patch') {
+              await protocolStore.authorizeSession(principal, input.session);
+              const sessionId = input.session.id;
+              const viewId = project.kind === 'git' ? `session:${sessionId}` : 'main';
+              const target = await storeFor(viewId);
+              const actor = human ? { ...principal.actor, sessionId } : principal.actor;
+              const data = await protocolMap.patch(principal, input, { store: target, actor,
+                references: () => verifyChangeReferences(input.payload.changes, {
+                  object: async (ref, version) => {
+                    const read = { v: 2, id: randomUUID(), type: 'object.read', session: input.session, payload: { ref, version } };
+                    return connected ? connection.send(read) : (await protocolStore.handle(principal, read)).data;
+                  },
+                  blob: blobId => connected ? connection.send({ v: 2, id: randomUUID(), type: 'blob.get', session: input.session, payload: { blobId } }) : protocolBlobs.metadata(principal, input.session, blobId),
+                }),
+                grants: () => human ? [...entries(target.doc.root).keys()] : access.grants(principal.agentId, target.doc),
+                prepare: request => prepareSessionCommit(target, request, actor, sessionId),
+                authorize: async () => {
+                  const binding = access.binding(sessionId);
+                  if (!binding || !human && binding.worktreeId !== principal.actor.worktreeId) protocolFail('FORBIDDEN', 'Agent binding changed');
+                  await protocolStore.authorizeSession(principal, input.session);
+                  if (pendingPeers(viewId).length) protocolFail('CONFLICT', 'Page edits are pending');
+                },
+              });
+              return { id: input.id, ok: true, data };
+            }
+            if (input.type === 'workbench.read') {
+              await protocolStore.authorizeSession(principal, input.session);
+              const sessionId = input.session.id, binding = access.binding(sessionId);
+              if (!binding || !human && binding.worktreeId !== principal.actor.worktreeId) protocolFail('FORBIDDEN', 'Agent binding is no longer active');
+              const target = await storeFor(project.kind === 'git' ? `session:${sessionId}` : 'main');
+              let source;
+              const load = async () => {
+                  if (source) return source;
+                  if (input.payload.scope === 'main') {
+                    let snapshot;
+                    try { ({ snapshot } = await memoryRequest(project, 'main')); }
+                    catch (error) { protocolFail(error.code === 'MEMORY_NOT_CONFIGURED' ? 'NOT_FOUND' : 'UNAVAILABLE', 'A confirmed Main snapshot is unavailable'); }
+                    if (!snapshot?.memory?.map) protocolFail('NOT_FOUND', 'Published Main snapshot is unavailable');
+                    return source = { doc: scopeDocumentToSession(snapshot.memory.map, sessionId), version: snapshot.version };
+                  }
+                  await target.serial(() => target.refresh());
+                  if (target.error || target.blocked) protocolFail('UNAVAILABLE', 'Session Map requires recovery');
+                  return source = { doc: scopeDocumentToSession(target.doc, sessionId), version: target.version };
+              };
+              const data = await protocolSnapshots.read(principal, input, {
+                load,
+                capture: () => protocolStore.recoverySnapshot(principal, input.session, load),
+                grants: async () => {
+                  const doc = (await load()).doc;
+                  return human ? [...entries(doc.root).keys()] : access.grants(principal.agentId, doc, 'read');
+                },
+              });
+              return { id: input.id, ok: true, data };
+            }
+            if (connected && (/^(object\.(put|read)|blob\.(put|get))$/.test(input.type) || workflowTypes.has(input.type))) {
+              const binding = access.binding(principal.actor.sessionId);
+              if (!binding || binding.worktreeId !== principal.actor.worktreeId) protocolFail('FORBIDDEN', 'Agent binding is no longer active');
+              if (input.session) await protocolStore.authorizeSession(principal, input.session);
+              for (const session of input.payload.sessions || []) await protocolStore.authorizeSession(principal, session);
+              return { id: input.id, ok: true, data: await connection.send(input) };
+            }
+            const reply = await protocolStore.handle(principal, input, {
+            blobs: protocolBlobs,
+            verifyBinding: (identity, payload) => {
+              const binding = access.binding(identity.agentId);
+              return payload.sessionId === identity.agentId && binding && payload.worktreeId === binding.worktreeId;
+            },
+            authorize: () => {
+              const binding = access.binding(principal.actor.sessionId);
+              if (!binding || binding.worktreeId !== principal.actor.worktreeId) protocolFail('FORBIDDEN', 'Agent binding is no longer active');
+            },
+            });
+            if (connected && input.type === 'session.bind') {
+              await connection.bind(input, reply.data);
+              return reply;
+            }
+            return reply;
+          },
+        })(req, res);
+        if (route === '/api/v2/execution' && req.method === 'GET') {
+          const actor = auth(req, url);
+          if (actor.kind !== 'agent') protocolFail('FORBIDDEN', 'A registered Agent is required');
+          if ((await claudeRuntime.status(actor.sessionId).catch(() => null))?.role === 'ci') {
+            try { return send(res, 200, { active: await claudeRuntime.ciContext(actor.sessionId) }); }
+            catch (error) { if (error.code === 'CI_NOT_ACTIVE') return send(res, 200, { active: null, ci: true }); throw error; }
+          }
+          const principal = { repositoryId: project.projectId, deviceId: project.projectId, agentId: actor.sessionId, role: 'executor' };
+          const binding = await protocolStore.registeredBinding(principal, actor.sessionId);
+          if (!binding || access.binding(actor.sessionId)?.worktreeId !== actor.worktreeId) protocolFail('FORBIDDEN', 'Session binding changed');
+          const session = { id: actor.sessionId, generation: binding.generation };
+          const active = await protocolStore.activeExecution(principal, session);
+          let plan = null;
+          if (active?.mode === 'reviewed' && active.approval && active.plan) {
+            const connection = await projectDevice();
+            if (!connection) protocolFail('UNAVAILABLE', 'Cloud is required to verify the approved Plan');
+            plan = await connection.send({ v: 2, id: randomUUID(), type: 'object.read', session, payload: { ref: active.plan.ref, version: active.plan.version } });
+          }
+          return send(res, 200, { session, active, plan });
+        }
+        if (route === '/api/v2/ci' && req.method === 'POST') {
+          const actor = auth(req, url);
+          if (actor.kind !== 'agent' || access.binding(actor.sessionId)?.worktreeId !== actor.worktreeId) protocolFail('FORBIDDEN', 'A current CI Session binding is required');
+          const input = await body(req), context = await claudeRuntime.ciContext(actor.sessionId, { verifySource: input.type === 'ci.result' });
+          if (!context || input.session && JSON.stringify(input.session) !== JSON.stringify(context.session)) protocolFail('FORBIDDEN', 'CI message targets a different developer Session');
+          const message = validateMessage({ ...input, session: context.session });
+          if (!['object.read', 'object.put', 'ci.result'].includes(message.type) || message.type === 'object.put' &&
+              (message.payload.kind !== 'evidence' || !message.payload.ref.startsWith(`ci:${actor.sessionId}:`)) || message.type === 'ci.result' &&
+              (message.payload.taskId !== context.taskId || message.payload.sourceSha !== context.sourceSha)) protocolFail('FORBIDDEN', 'CI message exceeds its assigned test scope');
+          const connection = await projectDevice();
+          if (!connection) protocolFail('UNAVAILABLE', 'Cloud connection is unavailable');
+          return send(res, 200, { id: message.id, ok: true, data: await ciChannel(actor.sessionId, connection).send(message) });
+        }
+        if (route === '/api/v2/task-report' && req.method === 'POST') {
+          const actor = auth(req, url);
+          if (actor.kind !== 'agent') protocolFail('FORBIDDEN', 'A registered Agent is required');
+          const principal = { repositoryId: project.projectId, deviceId: project.projectId, agentId: actor.sessionId, role: 'executor' };
+          const binding = await protocolStore.registeredBinding(principal, actor.sessionId);
+          if (!binding || access.binding(actor.sessionId)?.worktreeId !== actor.worktreeId) protocolFail('FORBIDDEN', 'Session binding changed');
+          const message = await protocolStore.executionReport(principal, { id: actor.sessionId, generation: binding.generation }, await body(req));
+          const connection = await projectDevice();
+          if (!connection) protocolFail('UNAVAILABLE', 'Cloud connection is unavailable; retry the same command');
+          return send(res, 200, { id: message.id, ok: true, data: await connection.send(message) });
+        }
+        if (route === '/api/v2/interrupt' && req.method === 'POST') {
+          const actor = auth(req, url);
+          if (actor.kind !== 'agent') protocolFail('FORBIDDEN', 'A registered Agent is required');
+          const principal = { repositoryId: project.projectId, deviceId: project.projectId, agentId: actor.sessionId, role: 'executor' };
+          const binding = await protocolStore.registeredBinding(principal, actor.sessionId);
+          if (!binding || access.binding(actor.sessionId)?.worktreeId !== actor.worktreeId) protocolFail('FORBIDDEN', 'Session binding changed');
+          const session = { id: actor.sessionId, generation: binding.generation };
+          const input = await body(req), active = await protocolStore.activeExecution(principal, session);
+          let message = validateMessage({ v: 2, id: input.id, type: 'task.report', session,
+            payload: { taskId: active?.taskId || 'no-cloud-task', stage: 'interrupted', data: { reason: input.reason, occurredAt: input.occurredAt } } });
+          const connection = await projectDevice();
+          const prior = await connection?.savedMessage(input.id);
+          if (prior) {
+            if (prior.session?.id !== session.id || prior.session.generation !== session.generation || prior.type !== 'task.report' || prior.payload.stage !== 'interrupted' || prior.payload.data.occurredAt !== input.occurredAt || prior.payload.data.reason !== input.reason) protocolFail('ID_REUSED', 'Interruption ID was already used');
+            message = prior;
+          } else if (!active || Date.parse(input.occurredAt) < Date.parse(active.assignedAt)) return send(res, 200, { queued: false, reason: 'No matching active Cloud task' });
+          if (!connection) protocolFail('UNAVAILABLE', 'Cloud connection is not configured; keep the hook event for retry');
+          const data = await connection.send(message);
+          return send(res, 200, { queued: true, synchronized: true, taskId: message.payload.taskId, receipt: data });
+        }
+        const binaryRoute = route.match(/^\/api\/v2\/blobs\/([a-f0-9]{64})$/);
+        if (binaryRoute) {
+          const actor = auth(req, url);
+          if (actor.kind !== 'agent') protocolFail('FORBIDDEN', 'A registered Agent credential is required');
+          const principal = { repositoryId: project.projectId, deviceId: project.projectId, agentId: actor.sessionId };
+          const session = { id: req.headers['x-context-guard-session'], generation: Number(req.headers['x-context-guard-generation']) };
+          await protocolStore.authorizeSession(principal, session);
+          const binding = access.binding(actor.sessionId);
+          if (!binding || binding.worktreeId !== actor.worktreeId) protocolFail('FORBIDDEN', 'Agent binding is no longer active');
+          const connection = await projectDevice();
+          if (connection && await connection.connected()) return await connection.proxyBlob(req, res, session, binaryRoute[1]);
+          return await serveBlob(req, res, { blobs: protocolBlobs, principal, session, blobId: binaryRoute[1] });
+        }
+        if (['/api/named-entry', '/api/open-claim'].includes(route) && req.method === 'POST') {
+          if (!direct || req.headers.authorization !== `Bearer ${adminToken}`) throw new MapError('UNAUTHORIZED', 'Requires local CLI credential', 401);
+          const input = await body(req);
+          if (route === '/api/open-claim') {
+            const shouldOpen = !peers.size && (!openClaimed || input.retry === true);
+            if (shouldOpen) openClaimed = true;
+            return send(res, 200, { shouldOpen });
+          }
+          if (!validNamedOrigin(input.origin) || typeof input.proxyToken !== 'string' || input.proxyToken.length < 32) throw new MapError('INVALID_ORIGIN', 'Expected an exact local project HTTP origin');
+          namedEntry = { name: new URL(input.origin).hostname.slice(0, -10), origin: input.origin, proxyToken: namedEntry?.proxyToken || input.proxyToken };
+          await atomicWrite(namedFile, encode(namedEntry));
+          return send(res, 200, { proxyToken: namedEntry.proxyToken });
+        }
+        if (['/api/session-prepare', '/api/session'].includes(route) && req.method === 'POST') {
+          if (req.headers.authorization !== `Bearer ${adminToken}`) throw new MapError('UNAUTHORIZED', 'Requires local CLI credential', 401);
+          const input = await body(req);
+          const prepared = await preparedSessionBinding(input);
+          if (route === '/api/session-prepare') return send(res, 200, { prepared: true, binding: prepared.binding, previous: prepared.previous || null });
+          return send(res, 200, await registerSession(input));
+        }
+        if (route === '/api/stop' && req.method === 'POST') {
+          if (req.headers.authorization !== `Bearer ${adminToken}`) throw new MapError('UNAUTHORIZED', 'Requires local CLI credential', 401);
+          for (const viewId of stores.keys()) await fence(viewId, { stopping: true });
+          send(res, 202, { stopping: true }); setImmediate(() => close()); return;
+        }
+        if (route === '/api/project-refresh' && req.method === 'POST') {
+          if (req.headers.authorization !== `Bearer ${adminToken}`) throw new MapError('UNAUTHORIZED', 'Requires local CLI credential', 401);
+          return send(res, 200, await refreshProject());
+        }
+        if (route.startsWith('/api/')) {
+          const actor = auth(req, url);
+          const viewId = viewFor(actor, url);
+          const activeStore = await storeFor(viewId);
+          if (route === '/api/cloud-sync' && req.method === 'GET') { isHuman(actor); return send(res, 200, await cloudSyncStatus(viewId)); }
+          if (route === '/api/events' && req.method === 'GET') {
+            isHuman(actor); const id = url.searchParams.get('clientId');
+            if (!id || id.length > 100) throw new MapError('INVALID_CLIENT', 'Invalid clientId');
+            const peerId = `${viewId}:${id}`;
+            let peer = peers.get(peerId) || { id, viewId, dirty: false, version: null };
+            peer.res?.end(); peer.res = res; peers.set(peerId, peer);
+            res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-store', Connection: 'keep-alive' });
+            res.write(`retry: 500\nevent: state\ndata: ${JSON.stringify(stateFor(viewId, activeStore, false))}\n\n`);
+            req.on('close', () => {
+              if (peer.res !== res) return;
+              // The synchronization fence only represents live pages. Dirty browser
+              // state is already captured by the page recovery layer; retaining a
+              // disconnected peer would make a closed tab block every later Agent.
+              peers.delete(peerId);
+              if (!peers.size) openClaimed = false;
+            }); return;
+          }
+          if (route === '/api/presence' && req.method === 'POST') {
+            isHuman(actor); const input = await body(req), peerId = `${viewId}:${input.clientId}`, peer = peers.get(peerId);
+            if (peer) { peer.dirty = !!input.dirty; peer.version = input.version; checkpoints.get(input.checkpoint)?.delete(peer); if (input.closing && !peer.dirty) { peer.res?.end(); peers.delete(peerId); } }
+            return send(res, 200, { version: activeStore.version, viewId, source: sourceFor(viewId), synchronized: input.version === activeStore.version && !input.dirty && !activeStore.error && !activeStore.blocked, error: activeStore.error, recovery: activeStore.blocked });
+          }
+          if (route === '/api/state' && req.method === 'GET') {
+            if (actor.kind === 'agent') await fence(viewId);
+            await activeStore.serial(() => activeStore.refresh());
+            const sessionId = actor.kind === 'agent' ? actor.sessionId : viewId.startsWith('session:') ? viewId.slice('session:'.length) : '';
+            const state = stateFor(viewId, activeStore);
+            if (sessionId && state.doc) state.doc = scopeDocumentToSession(state.doc, sessionId);
+            if (url.searchParams.has('node')) { const entry = state.doc && entries(state.doc.root).get(url.searchParams.get('node')); if (!entry) throw new MapError('NOT_FOUND', 'Node missing', 404); delete state.doc; state.node = entry.node; state.parentId = entry.parent?.id || null; }
+            return send(res, 200, { ...state, viewId, actor, grants: access.grants(actor.sessionId, activeStore.doc), peers: viewPeers(viewId).map(({ id, dirty, version }) => ({ id, dirty, version })) });
+          }
+          if (route === '/api/changes' && req.method === 'GET') {
+            await activeStore.serial(() => activeStore.refresh());
+            const changes = activeStore.changes(url.searchParams.get('cursor'));
+            const sessionId = actor.kind === 'agent' ? actor.sessionId : viewId.startsWith('session:') ? viewId.slice('session:'.length) : '';
+            return send(res, 200, sessionId ? scopeChangesToSession(changes, activeStore.doc, sessionId) : changes);
+          }
+          if (route === '/api/operation' && req.method === 'GET') { const record = await activeStore.operation(url.searchParams.get('id') || ''); return send(res, 200, { found: !!record, result: record?.result, recovery: activeStore.blocked }); }
+          if (route === '/api/commit' && req.method === 'POST') {
+            const input = await body(req);
+            if (project.kind === 'git' && viewId === 'main') throw new MapError('READ_ONLY_MAIN', 'All Sessions follows the committed main branch and is read-only', 403);
+            if (actor.kind === 'agent') await fence(viewId);
+            const sessionId = actor.kind === 'agent' ? actor.sessionId : viewId.startsWith('session:') ? viewId.slice('session:'.length) : '';
+            const prepared = await prepareSessionCommit(activeStore, input, actor, sessionId);
+            const result = await activeStore.commit(prepared.input, prepared.actor, () => access.grants(actor.sessionId, activeStore.doc), async () => { if (actor.kind === 'agent' && pendingPeers(viewId).length) throw new MapError('UI_PENDING', 'Page edits are still pending', 409); });
+            return send(res, 200, result);
+          }
+          if (route === '/api/recover' && req.method === 'POST') {
+            isHuman(actor);
+            return send(res, 200, await activeStore.repair(await body(req)));
+          }
+          if (route === '/api/attachments' && req.method === 'POST') {
+            isHuman(actor);
+            if (project.kind === 'git' && viewId === 'main') throw new MapError('READ_ONLY_MAIN', 'All Sessions follows the committed main branch and is read-only', 403);
+            if (activeStore.blocked || activeStore.error) throw new MapError('RECOVERY_REQUIRED', 'Resolve map recovery before uploading', 409);
+            return send(res, 200, await attachmentsFor(activeStore).save(await body(req), activeStore.doc));
+          }
+          if (route === '/api/attachments' && req.method === 'GET') {
+            isHuman(actor);
+            const content = await attachmentsFor(activeStore).read(url.searchParams.get('path'), activeStore.doc);
+            res.writeHead(200, {
+              'Content-Type': 'application/octet-stream',
+              'Content-Disposition': 'attachment',
+              'X-Content-Type-Options': 'nosniff',
+              'Cache-Control': 'no-store',
+            });
+            return res.end(content);
+          }
+          if (route === '/api/access' && req.method === 'GET') {
+            isHuman(actor);
+            const currentSessionId = viewId.startsWith('session:') ? viewId.slice('session:'.length) : null;
+            const snapshot = await access.snapshot(activeStore.doc, currentSessionId);
+            const scopedSnapshot = currentSessionId ? {
+              ...snapshot,
+              sessions: snapshot.sessions.filter(item => item.id === currentSessionId),
+              grants: snapshot.grants[currentSessionId] ? { [currentSessionId]: snapshot.grants[currentSessionId] } : {},
+            } : snapshot;
+            return send(res, 200, { ...scopedSnapshot, project: { id: project.projectId, kind: project.kind, github: project.github, bindingRequired: project.bindingRequired, main: mainSource } });
+          }
+          if (route === '/api/access' && req.method === 'POST') {
+            isHuman(actor); const input = await body(req);
+            await activeStore.serial(async () => {
+              await activeStore.refresh(); const ids = entries(activeStore.doc.root);
+              const current = access.accessRecord(input.sessionId);
+              const mode = input.mode === 'all' || Array.isArray(input.addNodes) && current?.mode === 'all' ? 'all' : 'explicit';
+              const requested = mode === 'all' ? [] : Array.isArray(input.addNodes)
+                ? [...new Set([...access.grants(input.sessionId, activeStore.doc), ...input.addNodes])]
+                : input.nodes;
+              if (!['all', undefined].includes(input.mode) || !Array.isArray(requested) || requested.some(id => !ids.has(id))) throw new MapError('INVALID_SCOPE', 'Unknown node or access mode in scope');
+              await access.grant(input.sessionId, requested, activeStore.version, mode);
+              const effective = access.grants(input.sessionId, activeStore.doc);
+              await activeStore.recordEvent({ operationId: randomUUID(), fromVersion: activeStore.version, version: activeStore.version, actor, actions: ['grant'], nodeIds: effective, sessionId: input.sessionId, mode });
+            });
+            broadcast('access', {}); return send(res, 200, { saved: true });
+          }
+          if (route === '/api/migration-preview' && req.method === 'POST') {
+            isHuman(actor); const input = await body(req); validate(input.doc);
+            if (input.doc.project !== activeStore.doc.project) throw new MapError('PROJECT_MISMATCH', 'Cache belongs to a different project');
+            await activeStore.serial(() => activeStore.refresh());
+            const backup = path.join(activeStore.runtime, 'migration-' + hash(encode(input.doc)) + '.json');
+            await atomicWrite(backup, encode({ imported: input.doc, disk: activeStore.doc, baseVersion: activeStore.version }));
+            return send(res, 200, { baseVersion: activeStore.version, operations: diffTrees(activeStore.doc.root, input.doc.root), backup, warning: 'Review every replacement and deletion; timestamps do not resolve conflicts.' });
+          }
+          if (route === '/api/projections' && req.method === 'POST') {
+            const input = await body(req); await activeStore.serial(() => activeStore.refresh());
+            if (input.wait) {
+              const version = activeStore.version;
+              const ready = await activeStore.project(activeStore.doc, version);
+              if (!ready) throw new MapError('VERSION_CONFLICT', 'Map changed during index generation', 409);
+              activeStore.projection = { status: 'ready', sourceVersion: version };
+              return send(res, 200, activeStore.projection);
+            }
+            activeStore.scheduleProjection(); return send(res, 202, { status: 'pending' });
+          }
+          throw new MapError('NOT_FOUND', 'Unknown API route', 404);
+        }
+        if (req.method !== 'GET') throw new MapError('METHOD', 'GET required', 405);
+        let file, contentType;
+        if (route === '/' || route === '/prototype/workbench.html') {
+          const html = await fs.readFile(path.join(skillRoot, 'prototype/workbench.html'), 'utf8');
+          const boot = JSON.stringify({ token: humanToken, root: `project:${project.projectId}`, projectId: project.projectId, bindingRequired: project.bindingRequired, instance, interfaceCapabilities: { deviceLogin: true }, ...runtimeIdentity() }).replace(/</g, '\\u003c');
+          const nonce = token();
+          res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store', 'Referrer-Policy': 'no-referrer', 'X-Frame-Options': 'DENY', 'Content-Security-Policy': `default-src 'self'; script-src 'nonce-${nonce}' 'strict-dynamic'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: https:; connect-src 'self'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'` });
+          return res.end(html.replace('<!-- CG_SERVER_BOOT -->', `<script>window.__CG_SERVER=${boot};</script>`).replace(/<script(?=[\s>])/g, `<script nonce="${nonce}"`));
+        }
+        if (route === '/prototype/map-model.mjs') { file = path.join(skillRoot, 'scripts/shared/map-model.mjs'); contentType = 'text/javascript; charset=utf-8'; }
+        else if (['/scripts/shared/map-model.mjs', '/prototype/workbench-sync.mjs', '/prototype/attachments.mjs', '/prototype/coordinator-markdown.mjs', '/prototype/coordinator-working-blot.mjs', '/prototype/vendor/marked.mjs'].includes(route)) { file = path.join(skillRoot, route.slice(1)); contentType = 'text/javascript; charset=utf-8'; }
+        else if (['/prototype/workbench-app.js', '/prototype/workbench-data.js'].includes(route)) { file = path.join(skillRoot, route.slice(1)); contentType = 'text/javascript; charset=utf-8'; }
+        else if (route === '/prototype/workbench.css') { file = path.join(skillRoot, route.slice(1)); contentType = 'text/css; charset=utf-8'; }
+        else if (route === '/prototype/working-blot-atlas.png') { file = path.join(skillRoot, route.slice(1)); contentType = 'image/png'; }
+        else if (route === '/.codex/context/map.json') { file = mainStore.file; contentType = 'application/json; charset=utf-8'; }
+        else if (['/.codex/context/preferences.json', '/.codex/context/candidates.json', '/.codex/context/l1-candidates.json'].includes(route)) { file = path.join(root, route.slice(1)); contentType = 'application/json; charset=utf-8'; }
+        else throw new MapError('NOT_FOUND', 'File not exposed', 404);
+        const content = await fs.readFile(file); res.writeHead(200, { 'Content-Type': contentType, 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' }); res.end(content);
+      } catch (e) {
+        if (!res.headersSent) send(res, e.status || (e.code === 'ENOENT' ? 404 : 500), { error: { code: e.code || 'INTERNAL_ERROR', message: e.message, ...e.details } });
+        else res.end();
+      }
+    });
+    server.requestTimeout = 10000; server.headersTimeout = 10000;
+    for (let attempt = 0; ; attempt++) {
+      try { await new Promise((resolve, reject) => { const onError = e => reject(e); server.once('error', onError); server.listen(port === 0 ? 0 : port + attempt, '127.0.0.1', () => { server.off('error', onError); resolve(); }); }); break; }
+      catch (e) { if (e.code !== 'EADDRINUSE' || attempt >= 20 || port === 0) throw e; }
+    }
+    base = `http://127.0.0.1:${server.address().port}`;
+    const state = { ...runtimeIdentity(), root, projectId: project.projectId, worktreeRoot: project.worktreeRoot, worktreeId: project.worktreeId, sharedDir: project.sharedDir, pid: process.pid, instance, url: base + '/prototype/workbench.html', adminToken };
+    await atomicWrite(sharedState, encode(state));
+    if (sharedState !== statePath(root)) await atomicWrite(statePath(root), encode(state));
+    stopAccessWatch = access.watch(() => broadcast('access', {}));
+    await projectDevice();
+    const heartbeat = setInterval(() => broadcast('ping', {}), 10000); heartbeat.unref();
+    const mainRefresh = setInterval(() => { if (project.kind === 'git') refreshProject().catch(() => {}); }, 30000); mainRefresh.unref();
+    let ownershipChecks = 0, ownershipCheckRunning = false;
+    const ownershipWatch = setInterval(async () => {
+      if (close.promise || ownershipCheckRunning) return;
+      ownershipCheckRunning = true;
+      try {
+        const owner = await readJSON(sharedState, null);
+        if (owner?.instance === instance) ownershipChecks = 0;
+        else if (++ownershipChecks >= 2) await close();
+        if (owner?.instance === instance) await ensureDeviceService();
+      } catch {
+        // A transient unreadable state file must not terminate a healthy server.
+        ownershipChecks = 0;
+      } finally { ownershipCheckRunning = false; }
+    }, 500);
+    ownershipWatch.unref();
+    function close() {
+      if (close.promise) return close.promise;
+      close.promise = (async () => {
+        clearInterval(heartbeat);
+        clearInterval(mainRefresh);
+        clearInterval(ownershipWatch);
+        await refreshing?.catch(() => {});
+        stopAccessWatch();
+        clearInterval(deviceHeartbeatTimer); deviceHeartbeatTimer = null;
+        deviceHeartbeatStopping = true;
+        await deviceHeartbeatRunning; await device?.close();
+        // Stop accepting reconnects before draining events or slow projections.
+        const disconnected = new Promise((resolve, reject) => {
+          server.close(error => error ? reject(error) : resolve());
+        });
+        for (const p of peers.values()) p.res?.end();
+        // A CLI stop owns this loopback server and must not leave undici/Node 24
+        // keep-alive connections holding the project lock after the response.
+        server.closeIdleConnections?.();
+        server.closeAllConnections?.();
+        await disconnected;
+        await Promise.all([...syncCoordinators.values()].map(coordinator => coordinator.close()));
+        await Promise.all([...new Set(stores.values())].map(store => store.close()));
+        await Promise.all([...projectionQueues.values()]);
+        if ((await readJSON(sharedState, null))?.instance === instance) await fs.unlink(sharedState);
+        if (sharedState !== statePath(root) && (await readJSON(statePath(root), null))?.instance === instance) await fs.unlink(statePath(root));
+        if ((await readJSON(lock, null))?.instance === instance) await fs.unlink(lock);
+      })();
+      return close.promise;
+    }
+    // Handler needs the shutdown closure after initialization.
+    server.cgClose = close;
+    return { state, project, store: mainStore, stores, access, server, close, humanToken };
+  } catch (e) { stopAccessWatch(); await Promise.all([...syncCoordinators.values()].map(coordinator => coordinator.close())); await Promise.all([...new Set(stores.values())].map(store => store.close())); server?.close(); if ((await readJSON(lock, null))?.instance === instance) await fs.unlink(lock); throw e; }
+}