@michelj/context-guard 0.4.3 → 0.6.1

package/scripts/workbench/named-proxy.mjs

@@ -0,0 +1,108 @@
+import http from 'node:http';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomBytes } from 'node:crypto';
+import { atomicWrite, encode, readJSON } from '../shared/io.mjs';
+import { RouteStore } from './portless-routes.mjs';
+import { compatibleRuntime } from './runtime.mjs';
+import { DeviceHeartbeat } from './device-heartbeat.mjs';
+
+const secret = () => randomBytes(32).toString('base64url');
+const PROXY_RUNTIME_SCHEMA = 4;
+export async function backendIdentity(route) {
+  try {
+    const response = await fetch(`http://127.0.0.1:${route.port}/__context_guard/health`, { signal: AbortSignal.timeout(1000), redirect: 'error' });
+    const value = await response.json();
+    return response.ok && compatibleRuntime(value) && value.instance === route.instance
+      && (value.namedRoot || value.root) === route.root
+      && (!route.runtimeSchema || value.runtimeSchema === route.runtimeSchema)
+      && (!route.projectKey || value.projectId === route.projectKey);
+  } catch { return false; }
+}
+function headers(input) {
+  const omitted = new Set(['connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade', ...String(input.connection || '').toLowerCase().split(',').map(s => s.trim())]);
+  return Object.fromEntries(Object.entries(input).filter(([key]) => !omitted.has(key) && !key.startsWith('x-context-guard-')));
+}
+export async function startNamedProxy({ dir, port = 1355 } = {}) {
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  const routes = new RouteStore(dir), instance = secret(), adminToken = secret();
+  const deviceHeartbeat = new DeviceHeartbeat({ dir, onTick: async () => {
+    if ((await readJSON(path.join(dir, 'proxy.json'), null))?.instance !== instance) setImmediate(() => close());
+  } });
+  routes.loadRoutes(); // Fail closed on corrupted persisted state, without overwriting it.
+  let base, ready = false;
+  const sockets = new Set();
+  const send = (res, status, body) => { res.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' }); res.end(JSON.stringify(body)); };
+  const server = http.createServer(async (req, res) => {
+    try {
+      // The state rename precedes its directory fsync. A launcher can discover
+      // this listener during that await, before initialization has completed.
+      if (!ready) return send(res, 503, { error: 'Proxy initializing' });
+      if (req.headers.host === new URL(base).host) {
+        if (req.headers.origin && req.headers.origin !== base) return send(res, 403, { error: 'Origin rejected' });
+        if (req.url === '/__cg_proxy/health' && req.method === 'GET') return send(res, 200, { kind: 'context-guard-named', version: 1, runtimeSchema: PROXY_RUNTIME_SCHEMA, capabilities: ['project-key-routes', 'device-heartbeat'], instance,
+          heartbeat: { batches: deviceHeartbeat.batches, errors: deviceHeartbeat.errors, lastSentAt: deviceHeartbeat.lastSentAt } });
+        if (req.headers.authorization !== `Bearer ${adminToken}`) return send(res, 401, { error: 'Local proxy capability required' });
+        if (req.url === '/__cg_proxy/stop' && req.method === 'POST') {
+          send(res, 202, { stopping: true }); setImmediate(() => close()); return;
+        }
+        if (req.url === '/__cg_proxy/routes' && req.method === 'POST') {
+          let text = ''; for await (const chunk of req) { text += chunk; if (text.length > 16384) return send(res, 413, { error: 'Body too large' }); }
+          const input = JSON.parse(text);
+          const { replace = null, ...route } = input;
+          // Validate before probing; do not let the management endpoint probe arbitrary hosts.
+          const { validRoute } = await import('./portless-routes.mjs');
+          if (!validRoute(route)) return send(res, 400, { error: 'Invalid route' });
+          if (!await backendIdentity(route)) return send(res, 409, { error: 'Backend identity changed' });
+          routes.addRoute(route, { replace });
+          return send(res, 200, { registered: true });
+        }
+        return send(res, 404, { error: 'Unknown proxy endpoint' });
+      }
+      const route = routes.loadRoutes().find(r => req.headers.host === `${r.hostname}:${server.address().port}`);
+      if (!route) return send(res, 404, { error: 'Unknown project hostname' });
+      const origin = `http://${req.headers.host}`;
+      if (req.headers.origin && req.headers.origin !== origin) return send(res, 403, { error: 'Origin rejected' });
+      if (!req.url.startsWith('/') || req.url.startsWith('//')) return send(res, 400, { error: 'Origin-form URL required' });
+      if (!await backendIdentity(route)) return send(res, 502, { error: 'Project backend unavailable or replaced; run context-guard workbench again' });
+      if (req.destroyed || res.destroyed) return;
+      const outgoing = http.request({ hostname: '127.0.0.1', port: route.port, method: req.method, path: req.url,
+        headers: { ...headers(req.headers), host: req.headers.host, 'x-context-guard-proxy': route.proxyToken } }, upstream => {
+        res.writeHead(upstream.statusCode, headers(upstream.headers)); upstream.pipe(res);
+        upstream.on('error', () => res.destroy());
+      });
+      outgoing.on('error', () => { if (!res.headersSent) send(res, 502, { error: 'Backend connection failed' }); else res.destroy(); });
+      req.on('aborted', () => outgoing.destroy()); res.on('close', () => outgoing.destroy());
+      req.pipe(outgoing);
+    } catch { if (!res.headersSent) send(res, 409, { error: 'Route rejected or route store invalid; inspect local configuration' }); else res.destroy(); }
+  });
+  server.on('connection', socket => { sockets.add(socket); socket.on('close', () => sockets.delete(socket)); });
+  server.on('upgrade', (_req, socket) => socket.destroy()); // Workbench uses SSE, not WebSockets.
+  server.requestTimeout = 15000; server.headersTimeout = 10000;
+  for (let attempt = 0; ; attempt++) {
+    try { await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port ? port + attempt : 0, '127.0.0.1', () => { server.removeListener('error', reject); resolve(); }); }); break; }
+    catch (e) { server.removeAllListeners('error'); if (e.code !== 'EADDRINUSE' || !port || attempt >= 20) throw e; }
+  }
+  base = `http://127.0.0.1:${server.address().port}`;
+  const state = { version: 1, runtimeSchema: PROXY_RUNTIME_SCHEMA, instance, pid: process.pid, base, adminToken };
+  const stateFile = path.join(dir, 'proxy.json');
+  try { await atomicWrite(stateFile, encode(state)); } catch (e) { server.close(); throw e; }
+  let closing;
+  const close = () => closing ||= (async () => {
+    ready = false;
+    await deviceHeartbeat.close();
+    const stopped = new Promise(resolve => server.close(resolve));
+    for (const socket of sockets) socket.destroy(); await stopped;
+    if ((await readJSON(stateFile, null))?.instance === instance) await fs.unlink(stateFile);
+  })();
+  ready = true;
+  deviceHeartbeat.start();
+  return { state, server, close };
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const running = await startNamedProxy({ dir: process.argv[2], port: Number(process.argv[3] || 1355) });
+    process.on('SIGTERM', () => running.close()); process.on('SIGINT', () => running.close());
+  } catch (e) { console.error(e.message); process.exitCode = 1; }
+}

package/scripts/workbench/named.mjs

@@ -0,0 +1,152 @@
+import fs from 'node:fs/promises';
+import http from 'node:http';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { randomUUID, createHash } from 'node:crypto';
+import { readJSON, pause } from '../shared/io.mjs';
+import { projectId, projectName, resolveProject } from './project.mjs';
+import { compatibleRuntime, WORKBENCH_RUNTIME_SCHEMA } from './runtime.mjs';
+import { globalWorkbenchDirectory, registeredProject, rememberProject } from './registry.mjs';
+import { RouteStore } from './portless-routes.mjs';
+
+export const namedDirectory = globalWorkbenchDirectory;
+const PROXY_RUNTIME_SCHEMA = 4;
+function alive(pid) { if (!Number.isInteger(pid) || pid < 1) return false; try { process.kill(pid, 0); return true; } catch (e) { return e.code !== 'ESRCH'; } }
+async function proxyProbe(state) {
+  if (!state || state.version !== 1 || !/^http:\/\/127\.0\.0\.1:\d+$/.test(state.base) || !state.adminToken) return false;
+  try { const res = await fetch(state.base + '/__cg_proxy/health', { signal: AbortSignal.timeout(700), redirect: 'error' }); const value = await res.json(); return res.ok && value.kind === 'context-guard-named' && value.instance === state.instance ? value : null; } catch { return null; }
+}
+const compatibleProxy = value => value?.runtimeSchema === PROXY_RUNTIME_SCHEMA && value.capabilities?.includes('project-key-routes');
+function stopProxy(state) {
+  return new Promise((resolve, reject) => {
+    const target = new URL('/__cg_proxy/stop', state.base);
+    const req = http.request(target, { method: 'POST', agent: false, headers: { Authorization: `Bearer ${state.adminToken}`, Connection: 'close' } }, res => {
+      res.resume(); res.on('end', () => res.statusCode === 202 ? resolve() : reject(new Error(`Proxy upgrade rejected with HTTP ${res.statusCode}`)));
+    });
+    req.setTimeout(1500, () => req.destroy(new Error('Proxy upgrade timed out')));
+    req.on('error', reject); req.end();
+  });
+}
+export async function ensureNamedProxy({ dir = namedDirectory(), port = Number(process.env.CONTEXT_GUARD_NAMED_PORT || 1355) } = {}) {
+  if (!Number.isInteger(port) || port < 0 || port > 65515) throw new Error('Invalid named proxy port');
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  const file = path.join(dir, 'proxy.json'), lock = path.join(dir, 'startup.lock');
+  const identity = randomUUID(), deadline = Date.now() + 15000;
+  let held = false;
+  while (!held) {
+    const state = await readJSON(file, null);
+    if (compatibleProxy(await proxyProbe(state))) return state;
+    if (Date.now() > deadline) throw new Error('Named proxy startup busy; no process was replaced');
+    try { const h = await fs.open(lock, 'wx', 0o600); try { await h.writeFile(JSON.stringify({ pid: process.pid, identity })); } finally { await h.close(); } held = true; }
+    catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      const owner = await readJSON(lock, null).catch(() => null);
+      if (owner?.pid && !alive(owner.pid)) {
+        // Serialize stale-lock reclamation: a second waiter must not unlink a
+        // new live owner's lock after the first waiter has already reclaimed it.
+        const reap = lock + '.reap';
+        try {
+          await fs.mkdir(reap);
+          try { const current = await readJSON(lock, null).catch(() => null); if (current?.pid && !alive(current.pid)) await fs.unlink(lock).catch(e => { if (e.code !== 'ENOENT') throw e; }); }
+          finally { await fs.rmdir(reap); }
+        } catch (e) { if (e.code !== 'EEXIST') throw e; await pause(50); }
+      }
+      else await pause(50);
+    }
+  }
+  try {
+    let state = await readJSON(file, null);
+    let probe = await proxyProbe(state);
+    if (compatibleProxy(probe)) return state;
+    if (probe && state?.adminToken && alive(state.pid)) {
+      await stopProxy(state);
+      while (Date.now() < deadline && alive(state.pid) && (await readJSON(file, null))?.instance === state.instance) await pause(25);
+      if (alive(state.pid) && (await readJSON(file, null))?.instance === state.instance) throw new Error('Older named proxy did not stop safely; no replacement was started');
+      state = await readJSON(file, null);
+      probe = await proxyProbe(state);
+      if (compatibleProxy(probe)) return state;
+    }
+    if (state && alive(state.pid)) throw new Error('Existing proxy process is not healthy; inspect it before restarting');
+    const log = await fs.open(path.join(dir, 'proxy.log'), 'a', 0o600);
+    const child = spawn(process.execPath, [fileURLToPath(new URL('./named-proxy.mjs', import.meta.url)), dir, String(port)], { detached: true, windowsHide: true, stdio: ['ignore', log.fd, log.fd] });
+    child.unref(); await log.close();
+    while (Date.now() < deadline) { await pause(60); state = await readJSON(file, null); if (compatibleProxy(await proxyProbe(state))) return state; }
+    throw new Error('Named proxy failed to start; inspect its private proxy.log');
+  } finally { if ((await readJSON(lock, null))?.identity === identity) await fs.unlink(lock); }
+}
+export async function namedWorkbench(state, request, { name, dir, port } = {}) {
+  const project = await resolveProject(state.root);
+  const registryDir = dir || namedDirectory();
+  const registered = await registeredProject(project, { dir: registryDir });
+  const saved = await readJSON(project.kind === 'git' ? path.join(project.sharedDir, 'named-entry.json') : path.join(state.root, '.codex/context/private/named-entry.json'), null);
+  const doc = await readJSON(path.join(state.root, '.codex/context/map.json'), {});
+  const chosen = name || saved?.name || registered?.name || projectName(doc.project || path.basename(state.root), state.root);
+  if (!/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(chosen)) throw new Error('Use a lowercase DNS name (letters, digits, hyphens; 1–63 characters)');
+  const capabilities = await fetch(new URL('/__context_guard/health', state.url), { signal: AbortSignal.timeout(1000) }).then(r => r.json());
+  if (!capabilities.namedEntry || !compatibleRuntime(capabilities)) throw new Error('The running workbench needs an upgrade for verified named URLs. Save drafts and use the explicit migration flow; it was not restarted');
+  const proxy = await ensureNamedProxy({ dir: registryDir, port });
+  const hostname = `${chosen}.localhost`, origin = `http://${hostname}:${new URL(proxy.base).port}`;
+  // Stable, domain-separated capability for concurrent first registration.
+  const proxyToken = saved?.proxyToken || createHash('sha256').update(`named-forwarding:${state.adminToken}`).digest('base64url');
+  const identityRoot = capabilities.namedRoot || state.root;
+  const route = { hostname, root: identityRoot, projectId: projectId(identityRoot), projectKey: project.projectId, instance: state.instance, runtimeSchema: WORKBENCH_RUNTIME_SCHEMA, port: Number(new URL(state.url).port), proxyToken };
+  const previous = new RouteStore(registryDir).loadRoutes().find(item => item.hostname === hostname) || null;
+  let replace = null;
+  if (previous && (previous.root !== route.root || previous.projectId !== route.projectId)) {
+    const knownRoot = registered?.roots?.includes(previous.root);
+    const sameGitProject = await resolveProject(previous.root).then(item => item.projectId === project.projectId).catch(() => false);
+    if (previous.projectKey === project.projectId || knownRoot || sameGitProject) {
+      replace = { hostname: previous.hostname, root: previous.root, projectId: previous.projectId, instance: previous.instance };
+    }
+  }
+  const response = await fetch(proxy.base + '/__cg_proxy/routes', { method: 'POST', headers: { Authorization: `Bearer ${proxy.adminToken}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ ...route, ...(replace ? { replace } : {}) }), signal: AbortSignal.timeout(5000), redirect: 'error' });
+  if (!response.ok) throw new Error('Project name registration failed; name may belong to another project');
+  // Claim the name before changing the backend's accepted origin. A collision
+  // must not break the project's previously working URL.
+  await request(state, '/api/named-entry', { method: 'POST', body: { origin, name: chosen, proxyToken } });
+  const result = { url: origin + '/prototype/workbench.html', projectRoot: state.root, proxyPort: Number(new URL(proxy.base).port) };
+  await verifyWorkbenchUrl(result.url, { projectId: state.projectId, instance: state.instance });
+  await rememberProject(project, { dir: registryDir, name: chosen, origin, state: { ...state, ...capabilities } });
+  return result;
+}
+
+export async function readWorkbenchHealth(url) {
+  let response, value;
+  try {
+    const target = new URL('/__context_guard/health', url);
+    // Node 18 delegates *.localhost to DNS on some platforms even though the
+    // browser-facing name is required to resolve to loopback. Probe the local
+    // proxy directly while preserving its host-based project routing.
+    if (target.protocol === 'http:' && target.hostname.endsWith('.localhost')) {
+      const result = await new Promise((resolve, reject) => {
+        const request = http.get({ hostname: '127.0.0.1', port: target.port, path: target.pathname + target.search, headers: { host: target.host } }, incoming => {
+          let text = '';
+          incoming.on('data', chunk => text += chunk);
+          incoming.on('end', () => {
+            try { resolve({ ok: incoming.statusCode >= 200 && incoming.statusCode < 300, value: JSON.parse(text) }); }
+            catch (error) { reject(error); }
+          });
+        });
+        request.setTimeout(1500, () => request.destroy(new Error('timeout')));
+        request.on('error', reject);
+      });
+      response = result;
+      value = result.value;
+    } else {
+      response = await fetch(target, { signal: AbortSignal.timeout(1500), redirect: 'error' });
+      value = await response.json();
+    }
+  } catch (cause) {
+    throw new Error(`Workbench URL verification failed: ${cause.message}`);
+  }
+  return { response, value };
+}
+
+export async function verifyWorkbenchUrl(url, expected) {
+  const { response, value } = await readWorkbenchHealth(url);
+  if (!response.ok || !compatibleRuntime(value) || value.projectId !== expected.projectId || value.instance !== expected.instance) {
+    throw new Error('Workbench URL resolves to a different project, instance, or runtime');
+  }
+  return value;
+}

package/scripts/workbench/portless-routes.mjs

@@ -0,0 +1,51 @@
+// Derived from Portless 0.15.6 src/routes.ts, Copyright 2025 Vercel Inc.
+// SPDX-License-Identifier: Apache-2.0
+// Modified for Context Guard: HTTP-only route schema, single daemon writer,
+// atomic private storage, strict validation; no force/kill, tunnels or PID pruning.
+// See THIRD_PARTY_NOTICES.md and licenses/Portless-Apache-2.0.txt.
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export function validRoute(r) {
+  return r && /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.localhost$/.test(r.hostname)
+    && Number.isInteger(r.port) && r.port > 0 && r.port < 65536
+    && typeof r.root === 'string' && path.isAbsolute(r.root)
+    && /^[a-f0-9]{24}$/.test(r.projectId) && typeof r.instance === 'string' && r.instance.length >= 20
+    && (r.runtimeSchema === undefined || Number.isInteger(r.runtimeSchema) && r.runtimeSchema > 0)
+    && typeof r.proxyToken === 'string' && r.proxyToken.length >= 32
+    && (r.projectKey === undefined || /^(?:git|folder)-[a-f0-9]{20}$/.test(r.projectKey));
+}
+
+function sameIdentity(left, right) {
+  return left && right && left.hostname === right.hostname && left.root === right.root
+    && left.projectId === right.projectId && left.instance === right.instance;
+}
+export class RouteStore {
+  constructor(dir) { this.routesPath = path.join(dir, 'routes.json'); }
+  loadRoutes() {
+    let text;
+    try { text = fs.readFileSync(this.routesPath, 'utf8'); } catch (e) { if (e.code === 'ENOENT') return []; throw e; }
+    const routes = JSON.parse(text);
+    if (!Array.isArray(routes) || !routes.every(validRoute) || new Set(routes.map(r => r.hostname)).size !== routes.length) throw new Error('Invalid named-workbench route store; restore the file before registering routes');
+    return routes;
+  }
+  saveRoutes(routes) {
+    const temp = `${this.routesPath}.${randomUUID()}.tmp`;
+    try {
+      const fd = fs.openSync(temp, 'wx', 0o600);
+      try { fs.writeFileSync(fd, JSON.stringify(routes)); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+      fs.renameSync(temp, this.routesPath);
+    } finally { try { fs.unlinkSync(temp); } catch (e) { if (e.code !== 'ENOENT') throw e; } }
+  }
+  addRoute(route, { replace = null } = {}) {
+    if (!validRoute(route)) throw new Error('Invalid named-workbench route');
+    const routes = this.loadRoutes(), previous = routes.find(r => r.hostname === route.hostname);
+    // Project identity, not PID reuse, controls name ownership. Never kill an owner.
+    const sameProject = previous?.projectKey && route.projectKey && previous.projectKey === route.projectKey;
+    if (previous && (previous.projectId !== route.projectId || previous.root !== route.root) && !sameProject && !sameIdentity(previous, replace)) {
+      throw new Error('Name belongs to another project; choose a different --name');
+    }
+    this.saveRoutes([...routes.filter(r => r.hostname !== route.hostname), route]);
+  }
+}

package/scripts/workbench/project.mjs

@@ -0,0 +1,327 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { atomicWrite, encode, readJSON, withFileLock, hash } from '../shared/io.mjs';
+import { MapError } from '../shared/map-model.mjs';
+
+const execFileAsync = promisify(execFile);
+const digest = value => createHash('sha256').update(String(value)).digest('hex');
+export const nonInteractiveGitEnvironment = (parent = process.env) => ({ ...parent, GIT_TERMINAL_PROMPT: '0' });
+export const optionalGitMiss = error => Number.isInteger(error?.code) && error.code !== 0 && !error.killed && error.signal == null;
+
+async function git(root, args, { optional = false } = {}) {
+  try {
+    const { stdout } = await execFileAsync('git', args, {
+      cwd: root,
+      env: nonInteractiveGitEnvironment(),
+      encoding: 'utf8',
+      windowsHide: true,
+      timeout: 10000,
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    return stdout.trim();
+  } catch (error) {
+    if (optional && optionalGitMiss(error)) return '';
+    throw error;
+  }
+}
+
+export async function refreshMain(project) {
+  if (project.kind !== 'git' || project.bindingRequired) {
+    return { status: project.kind === 'git' ? 'binding-required' : 'local-folder', branch: project.mainBranch || '', sha: project.mainSha || '', checkedAt: new Date().toISOString() };
+  }
+  let status = 'ready', error = '';
+  if (project.binding?.main?.mode === 'remote') {
+    try { await git(project.worktreeRoot, ['fetch', '--quiet', project.binding.main.remote, project.mainBranch]); }
+    catch (cause) { status = 'offline'; error = cause.code || 'FETCH_FAILED'; }
+  }
+  const current = await resolveProject(project.worktreeRoot);
+  return {
+    status,
+    branch: current.mainBranch,
+    ref: current.mainRef,
+    sha: current.mainSha,
+    github: current.github,
+    checkedAt: new Date().toISOString(),
+    ...(error ? { error } : {}),
+  };
+}
+
+function githubRepository(remote) {
+  const value = String(remote || '').trim();
+  const match = value.match(/^(?:https?:\/\/|ssh:\/\/git@|git@)github\.com(?::|\/)([^/]+)\/([^/]+?)(?:\.git)?$/i);
+  if (!match) return null;
+  return { owner: match[1], repo: match[2], slug: `${match[1]}/${match[2]}` };
+}
+
+async function defaultBranch(root, remote = 'origin') {
+  const symbolic = await git(root, ['symbolic-ref', '--quiet', '--short', `refs/remotes/${remote}/HEAD`], { optional: true });
+  if (symbolic.startsWith(`${remote}/`)) return symbolic.slice(remote.length + 1);
+  return '';
+}
+
+async function worktreeMetadata(root, main = null) {
+  const mainBranch = main?.branch || '';
+  const mainRef = main?.ref || '';
+  const [head, currentBranch, rawGitDir, mainSha] = await Promise.all([
+    git(root, ['rev-parse', 'HEAD'], { optional: true }),
+    git(root, ['branch', '--show-current'], { optional: true }),
+    git(root, ['rev-parse', '--path-format=absolute', '--git-dir'], { optional: true }),
+    mainRef ? git(root, ['rev-parse', '--verify', '--quiet', `${mainRef}^{commit}`], { optional: true }) : '',
+  ]);
+  const gitDir = rawGitDir ? await fs.realpath(rawGitDir).catch(() => path.resolve(root, rawGitDir)) : '';
+  return { branch: currentBranch, head, gitDir, mainBranch, mainRef, mainSha };
+}
+
+export const projectBindingPath = project => path.join(project.sharedDir, 'project-binding.json');
+export const sessionBindingsPath = project => project.kind === 'git'
+  ? path.join(project.sharedDir, 'workbench-bindings.json')
+  : path.join(project.worktreeRoot, '.codex/context/sessions/workbench-bindings.json');
+
+function mainTarget({ mode = 'remote', remote = 'origin', branch } = {}) {
+  const name = String(branch || '').trim();
+  if (!name) throw new Error('A main branch is required');
+  if (mode === 'local') return { mode, remote: '', branch: name, ref: `refs/heads/${name}` };
+  const remoteName = String(remote || 'origin').trim();
+  if (!/^[A-Za-z0-9._-]+$/.test(remoteName)) throw new Error('Invalid Git remote name');
+  return { mode: 'remote', remote: remoteName, branch: name, ref: `refs/remotes/${remoteName}/${name}` };
+}
+
+export async function resolveProject(openedRoot) {
+  const requestedRoot = await fs.realpath(path.resolve(openedRoot));
+  const topLevel = await git(requestedRoot, ['rev-parse', '--show-toplevel'], { optional: true });
+  if (!topLevel) {
+    const projectId = `folder-${digest(requestedRoot).slice(0, 20)}`;
+    return {
+      projectId,
+      kind: 'folder',
+      openedRoot: requestedRoot,
+      worktreeRoot: requestedRoot,
+      worktreeId: `worktree-${digest(requestedRoot).slice(0, 20)}`,
+      commonDir: null,
+      sharedDir: path.join(requestedRoot, '.codex/context/private/project-workbench'),
+      remote: '',
+      github: null,
+      bindingRequired: false,
+      binding: { source: 'folder', main: null },
+      // Once Git has rejected this directory, three more Git processes cannot
+      // provide repository metadata. Keep the same empty folder contract.
+      branch: '', head: '', gitDir: '', mainBranch: '', mainRef: '', mainSha: '',
+    };
+  }
+  const worktreeRoot = await fs.realpath(topLevel);
+  let commonDir = await git(worktreeRoot, ['rev-parse', '--path-format=absolute', '--git-common-dir'], { optional: true });
+  if (!commonDir) {
+    const relative = await git(worktreeRoot, ['rev-parse', '--git-common-dir']);
+    commonDir = path.resolve(worktreeRoot, relative);
+  }
+  commonDir = await fs.realpath(commonDir);
+  const projectId = `git-${digest(commonDir).slice(0, 20)}`;
+  const sharedDir = path.join(commonDir, 'context-guard');
+  const stored = await readJSON(path.join(sharedDir, 'project-binding.json'), null);
+  if (stored && (stored.projectId !== projectId || !stored.main?.branch)) throw new Error('Invalid project binding; repair it explicitly, do not recreate it');
+  const originUrl = await git(worktreeRoot, ['config', '--get', 'remote.origin.url'], { optional: true });
+  const originGithub = githubRepository(originUrl);
+  const automaticBranch = originGithub ? await defaultBranch(worktreeRoot) : '';
+  const automatic = automaticBranch ? mainTarget({ remote: 'origin', branch: automaticBranch }) : null;
+  const selected = stored?.projectId === projectId && stored?.main?.branch ? mainTarget(stored.main) : automatic;
+  const remote = selected?.mode === 'remote'
+    ? await git(worktreeRoot, ['config', '--get', `remote.${selected.remote}.url`], { optional: true })
+    : '';
+  const github = githubRepository(remote);
+  const metadata = await worktreeMetadata(worktreeRoot, selected);
+  return {
+    projectId,
+    kind: 'git',
+    openedRoot: requestedRoot,
+    worktreeRoot,
+    // The Git administration directory survives a supported `git worktree move`
+    // and changes when a different worktree is later created at the same path.
+    // An absolute checkout path has the opposite behaviour and caused stale
+    // bindings to look current after path reuse.
+    worktreeId: `worktree-${digest(metadata.gitDir || worktreeRoot).slice(0, 20)}`,
+    commonDir,
+    sharedDir,
+    remote,
+    github,
+    bindingRequired: !selected || !metadata.mainSha,
+    binding: selected ? { source: stored?.projectId === projectId ? 'explicit' : 'github-default', main: selected } : null,
+    ...metadata,
+  };
+}
+
+export async function ensureProjectBinding(project) {
+  if (project.kind !== 'git' || !project.binding || project.binding.source === 'explicit') return project;
+  await atomicWrite(projectBindingPath(project), encode({ v: 1, projectId: project.projectId, main: project.binding.main, source: project.binding.source, updatedAt: new Date().toISOString() }));
+  return { ...project, binding: { ...project.binding, source: 'explicit' } };
+}
+
+export async function saveMainBinding(openedRoot, options) {
+  const project = await resolveProject(openedRoot);
+  if (project.kind !== 'git') throw new Error('Main branch binding requires a Git project');
+  const target = mainTarget(options);
+  const valid = await git(project.worktreeRoot, ['check-ref-format', '--branch', target.branch], { optional: true });
+  if (valid !== target.branch) throw new Error('Invalid main branch name');
+  if (target.mode === 'remote') {
+    const remoteUrl = await git(project.worktreeRoot, ['remote', 'get-url', target.remote], { optional: true });
+    if (!remoteUrl) throw new Error(`Unknown Git remote: ${target.remote}`);
+    if (!await git(project.worktreeRoot, ['rev-parse', '--verify', '--quiet', `${target.ref}^{commit}`], { optional: true })) {
+      await git(project.worktreeRoot, ['fetch', '--quiet', target.remote, target.branch]);
+    }
+  }
+  if (!await git(project.worktreeRoot, ['rev-parse', '--verify', '--quiet', `${target.ref}^{commit}`], { optional: true })) throw new Error(`Main ref does not resolve: ${target.ref}`);
+  await atomicWrite(projectBindingPath(project), encode({ v: 1, projectId: project.projectId, main: target, source: 'user', updatedAt: new Date().toISOString() }));
+  return resolveProject(openedRoot);
+}
+
+export async function bindingStatus(project, sessionId = '') {
+  const bindings = await readJSON(sessionBindingsPath(project), { sessions: {} });
+  const session = sessionId ? bindings?.sessions?.[sessionId] || null : null;
+  let state = 'unbound';
+  if (session) {
+    if (session.projectId !== project.projectId) state = 'project-mismatch';
+    else if (session.worktreeId === project.worktreeId) state = session.worktreeRoot === project.worktreeRoot ? 'current' : 'moved';
+    else if (!session.gitDir && session.worktreeRoot === project.worktreeRoot) state = 'current-legacy';
+    else {
+      const target = await fs.realpath(session.worktreeRoot || '').catch(() => null);
+      state = target ? 'other-worktree' : 'stale';
+    }
+  }
+  return {
+    projectId: project.projectId,
+    kind: project.kind,
+    main: project.binding?.main || null,
+    bindingRequired: project.bindingRequired,
+    workbenchState: project.kind === 'git' ? path.join(project.sharedDir, 'workbench.json') : path.join(project.worktreeRoot, '.codex/context/private/workbench.json'),
+    session: session
+      ? { ...session, state, bound: ['current', 'current-legacy', 'moved'].includes(state), pathChanged: state === 'moved', migrationNeeded: state === 'current-legacy' }
+      : { bound: false, state, sessionId },
+  };
+}
+
+export async function projectPreferences(project, language) {
+  const file = path.join(project.sharedDir, 'preferences.json');
+  return withFileLock(file + '.lock', async () => {
+    const stored = await readJSON(file, null);
+    if (await readJSON(path.join(project.sharedDir, 'memory-client.json'), null)) {
+      const { memoryRequest } = await import('./memory.mjs');
+      const remote = (await memoryRequest(project, 'preferences')).preferences;
+      const chosen = language === undefined ? remote?.language || stored?.record_language : language;
+      if (!chosen) return { record_language: 'unset', display_language: 'auto' };
+      if (!['zh', 'en'].includes(chosen)) throw new Error('Language must be zh or en');
+      const result = remote?.language === chosen ? remote : (await memoryRequest(project, 'preferences', { operationId: `language:${remote?.version || 'initial'}:${chosen}`, baseVersion: remote?.version || null, language: chosen })).snapshot;
+      const value = { record_language: result.language, display_language: result.language, serverVersion: result.version };
+      await atomicWrite(file, encode(value)); return value;
+    }
+    if (language !== undefined) {
+      if (!['zh', 'en'].includes(language)) throw new Error('Language must be zh or en');
+      const next = { ...stored, record_language: language, display_language: language, updatedAt: new Date().toISOString() };
+      await atomicWrite(file, encode(next));
+      const verified = await readJSON(file);
+      if (verified.record_language !== language) throw new Error('Language persistence verification failed');
+      return verified;
+    }
+    if (stored) {
+      if (!['zh', 'en'].includes(stored.record_language)) throw new Error('Invalid shared language configuration');
+      return stored;
+    }
+    const values = new Set();
+    for (const root of await listWorktrees(project)) {
+      const value = await readJSON(path.join(root, '.codex/context/preferences.json'), null);
+      if (['zh', 'en'].includes(value?.record_language)) values.add(value.record_language);
+    }
+    if (values.size > 1) throw Object.assign(new Error('Confirmed language settings conflict; ask which project language to retain'), { code: 'LANGUAGE_CONFLICT' });
+    if (!values.size) return { record_language: 'unset', display_language: 'auto' };
+    const value = { record_language: [...values][0], display_language: [...values][0], migrated: true };
+    await atomicWrite(file, encode(value));
+    return readJSON(file);
+  });
+}
+
+export async function sameProject(leftRoot, rightRoot) {
+  const [left, right] = await Promise.all([resolveProject(leftRoot), resolveProject(rightRoot)]);
+  return left.projectId === right.projectId;
+}
+
+export async function listWorktrees(project) {
+  if (project.kind !== 'git') return [project.worktreeRoot];
+  const text = await git(project.worktreeRoot, ['worktree', 'list', '--porcelain']);
+  const roots = [];
+  for (const line of text.split(/\r?\n/)) {
+    if (!line.startsWith('worktree ')) continue;
+    const root = await fs.realpath(line.slice('worktree '.length)).catch(() => null);
+    if (root) roots.push(root);
+  }
+  return [...new Set(roots)];
+}
+
+export async function mainWorktree(project) {
+  if (project.kind !== 'git' || !project.mainBranch) return null;
+  const text = await git(project.worktreeRoot, ['worktree', 'list', '--porcelain']);
+  let candidate = null;
+  for (const line of `${text}\n`.split(/\r?\n/)) {
+    if (line.startsWith('worktree ')) candidate = line.slice('worktree '.length);
+    else if (line === `branch refs/heads/${project.mainBranch}` && candidate) {
+      return fs.realpath(candidate).catch(() => null);
+    } else if (!line && candidate) candidate = null;
+  }
+  return null;
+}
+
+export async function sessionBinding(project, sessionId, { workbenchUrl = null, role = 'executor' } = {}) {
+  return {
+    sessionId,
+    role,
+    projectId: project.projectId,
+    worktreeId: project.worktreeId,
+    gitDir: project.gitDir || null,
+    worktreeRoot: project.worktreeRoot,
+    branch: project.branch,
+    head: project.head,
+    mainBranch: project.mainBranch,
+    baseMainSha: project.mainSha,
+    workbenchState: project.kind === 'git' ? path.join(project.sharedDir, 'workbench.json') : path.join(project.worktreeRoot, '.codex/context/private/workbench.json'),
+    ...(workbenchUrl ? { workbenchUrl } : {}),
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+export const bindingPath = root => path.join(root, '.codex/context/private/project-binding.json');
+async function commonDir(root) {
+  const { stdout } = await execFileAsync('git', ['rev-parse', '--git-common-dir'], { cwd: root, env: nonInteractiveGitEnvironment(), windowsHide: true, timeout: 5000 });
+  return fs.realpath(path.resolve(root, stdout.trim()));
+}
+export async function resolveProjectRoot(root) {
+  root = await fs.realpath(path.resolve(root));
+  const binding = await readJSON(bindingPath(root), null);
+  if (!binding) return root;
+  if (binding.version !== 1 || !path.isAbsolute(binding.projectRoot || '')) throw new MapError('INVALID_BINDING', 'Invalid workbench project binding');
+  const target = await fs.realpath(binding.projectRoot);
+  if (target === root || await readJSON(bindingPath(target), null)) throw new MapError('INVALID_BINDING', 'Workbench binding chains are not supported');
+  if (await commonDir(root) !== await commonDir(target)) throw new MapError('INVALID_BINDING', 'Bound worktrees must belong to the same local Git repository');
+  await fs.access(path.join(target, '.codex/context/map.json'));
+  return target;
+}
+export async function bindProject(root, target, { keepLocal = false } = {}) {
+  root = await fs.realpath(root); target = await fs.realpath(target);
+  if (root === target || await resolveProjectRoot(target) !== target) throw new MapError('INVALID_BINDING', 'Select an unbound, different project worktree');
+  if (await commonDir(root) !== await commonDir(target)) throw new MapError('INVALID_BINDING', 'Different Git projects cannot share this binding');
+  await fs.access(path.join(target, '.codex/context/map.json'));
+  const existing = await readJSON(bindingPath(root), null);
+  if (existing && existing.projectRoot !== target) throw new MapError('BINDING_EXISTS', 'An existing binding cannot be silently replaced');
+  const localMap = await fs.stat(path.join(root, '.codex/context/map.json')).catch(e => e.code === 'ENOENT' ? null : Promise.reject(e));
+  if (localMap && !keepLocal) throw new MapError('LOCAL_MAP_EXISTS', 'Local Map is preserved. Pass --keep-local to confirm keeping its Session seed; no Map is merged or deleted');
+  // Do not change an active worktree's data source under its service or pages.
+  const state = await readJSON(path.join(root, '.codex/context/private/workbench.json'), null);
+  if (state?.pid) { let alive = true; try { process.kill(state.pid, 0); } catch (e) { if (e.code === 'ESRCH') alive = false; }
+    if (alive) throw new MapError('WORKBENCH_ACTIVE', 'Stop this worktree workbench before binding it'); }
+  await atomicWrite(bindingPath(root), encode({ version: 1, projectRoot: target, boundAt: new Date().toISOString() }));
+  return { root, projectRoot: target, localMapPreserved: !!localMap };
+}
+export const projectId = root => hash(root).slice(0, 24);
+export function projectName(value, root) {
+  const name = String(value || '').toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 63).replace(/-+$/g, '');
+  return name || `project-${projectId(root).slice(0, 12)}`;
+}