@michelj/context-guard 0.4.3 → 0.6.1

package/scripts/workbench/access.mjs

@@ -0,0 +1,496 @@
+import fs from 'node:fs/promises';
+import { watchFile, unwatchFile } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { entries, MapError, filterNodeAccess } from '../shared/map-model.mjs';
+import { atomicWrite, encode, readJSON } from '../shared/io.mjs';
+const execFileAsync = promisify(execFile);
+export const token = () => randomBytes(32).toString('base64url');
+let nodeSqlite;
+
+function hasBuiltInSqlite(version = process.versions.node) {
+  const [major = 0, minor = 0] = String(version).split('.').map(Number);
+  return major > 22 || (major === 22 && minor >= 5);
+}
+
+async function queryWithNodeSqlite(database, sql) {
+  if (nodeSqlite === undefined) nodeSqlite = await import('node:sqlite').catch(() => null);
+  if (!nodeSqlite?.DatabaseSync) return null;
+  const connection = new nodeSqlite.DatabaseSync(database, { readOnly: true });
+  try { return connection.prepare(sql).all(); }
+  finally { connection.close(); }
+}
+
+const ACTIVE_TASK_EVENTS = new Set(['task_started', 'turn_started', 'response.started']);
+const STOPPED_TASK_EVENTS = new Set([
+  'task_complete', 'task_completed', 'turn_complete', 'turn_completed', 'response.completed',
+  'task_cancelled', 'task_canceled', 'task_failed', 'turn_aborted', 'turn_cancelled', 'turn_canceled',
+]);
+const UNKNOWN_ACTIVITY = { status: 'unknown', lastEvent: 'unknown', lastSeen: '' };
+
+function taskEvent(line) {
+  try {
+    const event = JSON.parse(line);
+    const candidates = [
+      event?.type === 'event_msg' ? event.payload?.type : null,
+      event?.type,
+      event?.payload?.event?.type,
+      event?.event?.type,
+    ].filter(type => typeof type === 'string');
+    const type = candidates.find(candidate => ACTIVE_TASK_EVENTS.has(candidate) || STOPPED_TASK_EVENTS.has(candidate));
+    if (!type) return null;
+    return {
+      status: ACTIVE_TASK_EVENTS.has(type) ? 'active' : 'stopped',
+      lastEvent: type,
+      lastSeen: event.timestamp || event.created_at || event.payload?.timestamp || '',
+    };
+  } catch { return null; }
+}
+
+export function rolloutTaskStatus(text, initial = UNKNOWN_ACTIVITY) {
+  let state = { ...initial };
+  for (const line of text.split('\n')) {
+    const event = taskEvent(line);
+    if (event) state = event;
+  }
+  return state;
+}
+
+function activityOf(item) {
+  const status = ['active', 'stopped'].includes(item?.status) ? item.status : 'unknown';
+  const statusSeen = item?.statusSeen || (status === 'unknown' ? '' : item?.lastSeen) || '';
+  return { status, statusSeen, lastEvent: item?.lastEvent || 'unknown', statusSource: item?.statusSource || item?.platform || 'unknown' };
+}
+
+function latestActivity(previous, discovered) {
+  const before = activityOf(previous), after = activityOf(discovered);
+  if (after.statusSeen > before.statusSeen) return after;
+  if (after.statusSeen < before.statusSeen) return before;
+  const rank = { unknown: 0, active: 1, stopped: 2 };
+  return rank[after.status] > rank[before.status] ? after : before;
+}
+
+function isoTime(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) return new Date(value * 1000).toISOString();
+  if (typeof value === 'string' && value) return value;
+  return new Date(0).toISOString();
+}
+
+export function hostAttestedPlatform(sessionId, env = process.env) {
+  const id = String(sessionId || '').trim();
+  if (!id) return '';
+  if (String(env.CODEX_THREAD_ID || '').trim() === id) return 'codex';
+  if (String(env.CLAUDE_SESSION_ID || '').trim() === id) return 'claude';
+  if (String(env.CURSOR_SESSION_ID || '').trim() === id) return 'cursor';
+  return '';
+}
+
+export function normalizeHostPath(value) {
+  const text = String(value || '');
+  if (!text) return '';
+  const normalized = path.normalize(text).replace(/[\\/]+$/, '');
+  return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+
+export async function recordHostAttestedSession(root, sessionId, env = process.env) {
+  const id = String(sessionId || '').trim();
+  const platform = hostAttestedPlatform(id, env);
+  if (!platform) return false;
+  const file = path.join(root, '.codex/context/sessions.jsonl');
+  const text = await fs.readFile(file, 'utf8').catch(e => e.code === 'ENOENT' ? '' : Promise.reject(e));
+  for (const line of text.split('\n').filter(Boolean)) {
+    try {
+      const event = JSON.parse(line);
+      if (typeof event.session_id === 'string' && event.session_id.trim() === id) return false;
+    } catch {}
+  }
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.appendFile(file, `${JSON.stringify({
+    at: new Date().toISOString(),
+    event: 'session-start',
+    platform,
+    session_id: id,
+    source: 'host-environment',
+    worktree_root: root,
+  })}\n`);
+  return true;
+}
+
+async function rootPathAliases(root) {
+  const values = [root];
+  const real = await fs.realpath(root).catch(() => '');
+  if (real && real !== root) values.push(real);
+  const aliases = [];
+  for (const value of values.filter(Boolean)) {
+    aliases.push(value, path.toNamespacedPath(value));
+    const stripped = value.replace(/[\\/]+$/, '');
+    if (stripped && stripped !== value) aliases.push(stripped);
+    if (!value.endsWith('/') && !value.endsWith('\\')) aliases.push(value + path.sep);
+  }
+  return [...new Set(aliases.filter(Boolean))];
+}
+
+export class Access {
+  constructor(root, options = {}) {
+    this.root = root;
+    this.ctx = path.join(root, '.codex/context');
+    this.file = options.file || path.join(this.ctx, 'sessions/workbench-access.json');
+    this.bindingsFile = options.bindingsFile || path.join(this.ctx, 'sessions/workbench-bindings.json');
+    this.sessionsFile = path.join(this.ctx, 'sessions.jsonl');
+    this.codexHome = options.codexHome || process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+    this.sqliteHome = options.sqliteHome || process.env.CODEX_SQLITE_HOME || null;
+    this.codexDb = options.codexDb || null;
+    this.sqliteCommand = options.sqliteCommand || 'sqlite3';
+    this.execFile = options.execFile || execFileAsync;
+    this.querySqlite = options.querySqlite || queryWithNodeSqlite;
+    this.allowExternalSqlite = options.allowExternalSqlite ?? !hasBuiltInSqlite(options.nodeVersion);
+    this.codexSessions = options.codexSessions || null;
+    this.codexRows = null;
+    this.codexQuery = null;
+    this.rolloutStates = new Map();
+    this.queue = Promise.resolve();
+  }
+  async init() {
+    this.data = await readJSON(this.file, { sessions: {} });
+    this.bindings = await readJSON(this.bindingsFile, { sessions: {} });
+    // Older releases represented the default full Session scope by copying the
+    // then-current node IDs. That snapshot silently locked every node created
+    // later. A non-empty mode-less record is therefore the legacy form of the
+    // dynamic default. Explicitly narrowed records written by current releases
+    // carry mode:"explicit" and remain untouched.
+    let migrated = false;
+    for (const record of Object.values(this.data.sessions || {})) {
+      if (!record?.mode && Array.isArray(record?.nodes) && record.nodes.length) {
+        record.mode = 'all';
+        record.nodes = [];
+        record.changedAt = new Date().toISOString();
+        migrated = true;
+      }
+    }
+    if (migrated) await atomicWrite(this.file, encode(this.data));
+    return this;
+  }
+  binding(sessionId) { return this.bindings.sessions[sessionId] || null; }
+  bindingRoots() { return [...new Set([this.root, ...Object.values(this.bindings.sessions).map(item => item?.worktreeRoot).filter(Boolean)])]; }
+  async hookSessionRegistry(root = this.root) {
+    const sessionsFile = path.join(root, '.codex/context/sessions.jsonl');
+    const text = await fs.readFile(sessionsFile, 'utf8').catch(e => e.code === 'ENOENT' ? '' : Promise.reject(e));
+    const sessions = new Map();
+    for (const line of text.split('\n').filter(Boolean)) {
+      try {
+        const event = JSON.parse(line);
+        const id = typeof event.session_id === 'string' ? event.session_id.trim() : '';
+        if (!id || event.event === 'maintenance' || id.startsWith('maintenance-')) continue;
+        const at = typeof event.at === 'string' && event.at ? event.at : new Date(0).toISOString();
+        const previous = sessions.get(id);
+        // A blocked Stop means governance is unfinished, not that the Agent is
+        // still generating a response. Keep those two states separate so stale
+        // bindings never render as a permanently spinning Session.
+        const stopped = ['stop', 'stop-blocked', 'subagent-stop', 'session-end', 'stop-failure'].includes(event.event);
+        const activated = ['session-start', 'subagent-start', 'user-prompt-submit'].includes(event.event);
+        const status = stopped ? 'stopped' : activated ? 'active' : previous?.status || 'unknown';
+        sessions.set(id, {
+          id,
+          name: typeof event.thread_name === 'string' && event.thread_name.trim() ? event.thread_name.trim() : previous?.name || '',
+          platform: typeof event.platform === 'string' && event.platform ? event.platform : previous?.platform || 'unknown',
+          status,
+          statusSeen: stopped || activated ? at : previous?.statusSeen || '',
+          statusSource: 'hook',
+          firstSeen: previous?.firstSeen || at,
+          lastSeen: at,
+          lastEvent: typeof event.event === 'string' ? event.event : previous?.lastEvent || 'unknown',
+          worktreeRoot: root,
+        });
+      } catch {}
+    }
+    return [...sessions.values()];
+  }
+  async stateDatabase() {
+    if (this.codexDb) return this.codexDb;
+    const homes = [...new Set([
+      this.sqliteHome,
+      this.codexHome && path.join(this.codexHome, 'sqlite'),
+      this.codexHome,
+    ].filter(Boolean).map(home => path.resolve(home)))];
+    const candidates = [];
+    for (const home of homes) {
+      const files = await fs.readdir(home, { withFileTypes: true }).catch(() => []);
+      for (const item of files) {
+        if (!item.isFile() || !/^state(?:_\d+)?\.sqlite$/.test(item.name)) continue;
+        const file = path.join(home, item.name);
+        candidates.push({ file, mtime: (await fs.stat(file).catch(() => ({ mtimeMs: 0 }))).mtimeMs });
+      }
+    }
+    candidates.sort((a, b) => b.mtime - a.mtime);
+    if (candidates[0]) this.codexDb = candidates[0].file;
+    return this.codexDb;
+  }
+  async readRange(file, start, length) {
+    if (length <= 0) return '';
+    const handle = await fs.open(file, 'r');
+    try {
+      const buffer = Buffer.allocUnsafe(length);
+      let offset = 0;
+      while (offset < length) {
+        const { bytesRead } = await handle.read(buffer, offset, length - offset, start + offset);
+        if (!bytesRead) break;
+        offset += bytesRead;
+      }
+      return buffer.subarray(0, offset).toString('utf8');
+    } finally { await handle.close(); }
+  }
+  async initialRolloutState(file, size) {
+    const block = 256 * 1024;
+    let end = size, suffix = '';
+    while (end > 0) {
+      const start = Math.max(0, end - block);
+      const text = await this.readRange(file, start, end - start) + suffix;
+      const lines = text.split('\n');
+      suffix = start > 0 ? lines.shift() : '';
+      for (let i = lines.length - 1; i >= 0; i--) {
+        const event = taskEvent(lines[i]);
+        if (event) return event;
+      }
+      end = start;
+    }
+    return { ...UNKNOWN_ACTIVITY };
+  }
+  async rolloutState(file) {
+    if (!file) return { ...UNKNOWN_ACTIVITY };
+    const stat = await fs.stat(file).catch(() => null);
+    if (!stat?.isFile()) return { ...UNKNOWN_ACTIVITY };
+    const previous = this.rolloutStates.get(file);
+    if (previous && stat.size === previous.size) return previous;
+    let state;
+    if (previous && stat.size > previous.size) {
+      const appended = await this.readRange(file, previous.size, stat.size - previous.size);
+      state = rolloutTaskStatus(appended, previous);
+    } else state = await this.initialRolloutState(file, stat.size);
+    const next = { ...state, size: stat.size };
+    this.rolloutStates.set(file, next);
+    return next;
+  }
+  async databaseSignature(database) {
+    const signatures = await Promise.all([database, `${database}-wal`].map(async file => {
+      const stat = await fs.stat(file).catch(() => null);
+      return stat ? `${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}` : '-';
+    }));
+    return `${database}:${signatures.join(':')}`;
+  }
+  async loadCodexRows(database, sql) {
+    const signature = `${await this.databaseSignature(database)}:${sql}`;
+    if (this.codexRows?.signature === signature) return this.codexRows.rows;
+    if (this.codexQuery?.signature === signature) return this.codexQuery.promise;
+    const promise = (async () => {
+      let rows = await this.querySqlite(database, sql);
+      if (rows === null) {
+        if (!this.allowExternalSqlite) throw new Error('Built-in SQLite is unavailable on a supported Node.js runtime');
+        const { stdout } = await this.execFile(this.sqliteCommand, ['-readonly', '-json', database, sql], {
+          encoding: 'utf8', timeout: 1500, maxBuffer: 4 * 1024 * 1024, windowsHide: true,
+        });
+        rows = stdout.trim() ? JSON.parse(stdout) : [];
+      }
+      this.codexRows = { signature, rows };
+      return rows;
+    })();
+    this.codexQuery = { signature, promise };
+    try { return await promise; }
+    finally { if (this.codexQuery?.promise === promise) this.codexQuery = null; }
+  }
+  mapCodexRow(row, state) {
+    return {
+      id: String(row.id),
+      name: String(row.name || row.title || '').trim(),
+      platform: 'codex',
+      status: state.status,
+      statusSeen: state.lastSeen,
+      statusSource: 'codex-rollout',
+      firstSeen: isoTime(row.created_at),
+      lastSeen: [isoTime(row.updated_at), state.lastSeen].filter(Boolean).sort().at(-1),
+      lastEvent: state.lastEvent,
+      worktreeRoot: String(row.cwd || ''),
+    };
+  }
+  async discoverCodexSessions(roots = [this.root]) {
+    if (this.codexSessions) {
+      const batches = await Promise.all(roots.map(root => this.codexSessions(root)));
+      return batches.flat();
+    }
+    const database = await this.stateDatabase();
+    if (!database) return [];
+    // Codex can persist Win32 extended-length paths, trailing slashes, or a
+    // realpath while Git bindings use the ordinary worktree spelling.
+    const aliases = [...new Set((await Promise.all(roots.map(root => rootPathAliases(root)))).flat())];
+    const escaped = aliases.map(root => `'${root.replaceAll("'", "''")}'`).join(',');
+    const sql = `select id, name, title, cwd, created_at, updated_at, rollout_path from threads where cwd in (${escaped}) and thread_source='user' and archived=0 order by updated_at desc limit 100`;
+    try {
+      const rows = await this.loadCodexRows(database, sql);
+      return await Promise.all(rows.map(async row => this.mapCodexRow(row, await this.rolloutState(row.rollout_path))));
+    } catch { return []; }
+  }
+  async discoverCodexThread(sessionId, root = this.root) {
+    const id = String(sessionId || '').trim();
+    if (!id) return null;
+    if (this.codexSessions) {
+      return (await this.codexSessions(root)).find(item => item?.id === id) || null;
+    }
+    const database = await this.stateDatabase();
+    if (!database) return null;
+    const sql = `select id, name, title, cwd, created_at, updated_at, rollout_path from threads where id='${id.replaceAll("'", "''")}' and archived=0 limit 1`;
+    try {
+      const [row] = await this.loadCodexRows(database, sql);
+      if (!row) return null;
+      const aliases = new Set((await rootPathAliases(root)).map(normalizeHostPath));
+      if (!aliases.has(normalizeHostPath(row.cwd))) {
+        const realCwd = await fs.realpath(row.cwd || '').catch(() => '');
+        if (!realCwd || !aliases.has(normalizeHostPath(realCwd))) return null;
+      }
+      return this.mapCodexRow(row, await this.rolloutState(row.rollout_path));
+    } catch { return null; }
+  }
+  async sessionExists(sessionId, root = this.root) {
+    const id = String(sessionId || '').trim();
+    if (!id) return false;
+    if ((await this.knownSessions(root)).includes(id)) return true;
+    return !!(await this.discoverCodexThread(id, root));
+  }
+  async sessionRegistry() {
+    const roots = this.bindingRoots();
+    const [hookBatches, codexSessions] = await Promise.all([Promise.all(roots.map(root => this.hookSessionRegistry(root))), this.discoverCodexSessions(roots)]);
+    const hookSessions = hookBatches.flat();
+    const sessions = new Map(Object.entries(this.bindings.sessions).filter(([id]) => !id.startsWith('maintenance-')).map(([id, binding]) => [id, {
+      id, name: '', platform: 'unknown', status: 'unknown', statusSeen: '', statusSource: 'binding', firstSeen: binding.updatedAt, lastSeen: binding.updatedAt, lastEvent: 'bound', ...binding,
+    }]));
+    for (const discovered of [...hookSessions, ...codexSessions]) {
+      if (!discovered?.id) continue;
+      if (!this.binding(discovered.id)) continue;
+      const stored = sessions.get(discovered.id);
+      const previous = stored?.lastEvent === 'bound' ? { ...stored, firstSeen: '', lastSeen: '' } : stored;
+      const activity = latestActivity(previous, discovered);
+      sessions.set(discovered.id, {
+        ...previous,
+        ...discovered,
+        name: discovered.name || previous?.name || '',
+        firstSeen: [previous?.firstSeen, discovered.firstSeen].filter(Boolean).sort()[0] || new Date(0).toISOString(),
+        lastSeen: [previous?.lastSeen, discovered.lastSeen].filter(Boolean).sort().at(-1) || new Date(0).toISOString(),
+        ...activity,
+      });
+    }
+    const validated = await Promise.all([...sessions.values()].map(async item => {
+      const binding = this.binding(item.id) || {};
+      const target = binding.worktreeRoot ? await fs.realpath(binding.worktreeRoot).catch(() => null) : null;
+      return {
+        ...item,
+        ...binding,
+        bindingState: target ? 'bound' : 'stale',
+        worktreeName: target ? path.basename(target) : path.basename(binding.worktreeRoot || ''),
+      };
+    }));
+    return validated.sort((a, b) => b.lastSeen.localeCompare(a.lastSeen));
+  }
+  async recordedSessionIds() {
+    const text = await fs.readFile(this.sessionsFile, 'utf8').catch(e => e.code === 'ENOENT' ? '' : Promise.reject(e));
+    const ids = new Set();
+    for (const line of text.split('\n').filter(Boolean)) {
+      try { const event = JSON.parse(line); if (typeof event.session_id === 'string' && event.session_id.trim()) ids.add(event.session_id.trim()); } catch {}
+    }
+    return [...ids];
+  }
+  accessRecord(sessionId) {
+    const record = this.data.sessions[sessionId];
+    if (!record) return null;
+    return { mode: record.mode === 'all' ? 'all' : 'explicit', nodes: Array.isArray(record.nodes) ? record.nodes : [] };
+  }
+  grants(sessionId, document = null, mode = 'write') {
+    const record = this.accessRecord(sessionId);
+    if (!record) return [];
+    if (!document?.root) return [...record.nodes];
+    const nodes = record.mode === 'all' ? [...entries(document.root).keys()] : [...record.nodes];
+    return filterNodeAccess(document, nodes, sessionId, mode);
+  }
+  async promoteLegacyFullGrant(sessionId, document) {
+    const record = this.data.sessions[sessionId];
+    if (!record || record.mode || !document?.root || !Array.isArray(record.nodes)) return false;
+    const current = [...entries(document.root).keys()];
+    if (record.nodes.length !== current.length || current.some(id => !record.nodes.includes(id))) return false;
+    await this.grant(sessionId, [], record.version || null, 'all');
+    return true;
+  }
+  async snapshot(document = null, currentSessionId = null) {
+    const sessions = await this.sessionRegistry();
+    const grants = {};
+    for (const session of sessions) {
+      const record = this.accessRecord(session.id) || { mode: 'all', nodes: [] };
+      grants[session.id] = { ...this.data.sessions[session.id], mode: record.mode, nodes: this.grants(session.id, document) };
+    }
+    return {
+      sessions,
+      currentSessionId: sessions.some(item => item.id === currentSessionId) ? currentSessionId : null,
+      grants,
+    };
+  }
+  async knownSessions(root = null) {
+    if (!root) return (await this.sessionRegistry()).map(item => item.id);
+    const [hook, codex] = await Promise.all([this.hookSessionRegistry(root), this.discoverCodexSessions([root])]);
+    return [...new Set([...hook, ...codex].map(item => item.id))];
+  }
+  watch(onChange) {
+    let timer, checking = false, signature;
+    const listener = () => {
+      clearTimeout(timer);
+      timer = setTimeout(onChange, 30);
+      timer.unref?.();
+    };
+    const inspect = async () => {
+      if (checking) return;
+      checking = true;
+      try {
+        const sessions = await this.sessionRegistry();
+        const next = JSON.stringify(sessions.map(({ id, name, status, lastSeen }) => [id, name, status, lastSeen]));
+        if (signature !== undefined && signature !== next) listener();
+        signature = next;
+      } finally { checking = false; }
+    };
+    watchFile(this.sessionsFile, { persistent: false, interval: 200 }, inspect);
+    void inspect();
+    const interval = setInterval(inspect, 750); interval.unref?.();
+    return () => { clearTimeout(timer); clearInterval(interval); unwatchFile(this.sessionsFile, inspect); };
+  }
+  async register(sessionId, binding = {}) {
+    if (!Object.keys(binding).length && !this.binding(sessionId)) throw new MapError('SESSION_BINDING_REQUIRED', 'Bind this Session explicitly before granting scope', 409);
+    const worktreeRoot = binding.worktreeRoot || this.binding(sessionId)?.worktreeRoot || this.root;
+    if (!(await this.sessionExists(sessionId, worktreeRoot))) throw new MapError('UNKNOWN_SESSION', 'Session must first be recorded by a lifecycle hook or discovered in this Context Guard worktree', 403);
+    const stored = {
+      ...(this.binding(sessionId) || {}),
+      ...binding,
+      sessionId,
+      worktreeRoot,
+      updatedAt: new Date().toISOString(),
+    };
+    const next = this.queue.then(async () => {
+      this.bindings.sessions[sessionId] = stored;
+      const data = structuredClone(this.data);
+      if (!data.sessions[sessionId]) data.sessions[sessionId] = { mode: 'all', nodes: [], version: null, changedAt: new Date().toISOString() };
+      await Promise.all([
+        atomicWrite(this.bindingsFile, encode(this.bindings)),
+        atomicWrite(this.file, encode(data)),
+      ]);
+      this.data = data;
+    });
+    this.queue = next.catch(() => {}); await next;
+    return { kind: 'agent', sessionId, ...(stored.projectId ? { projectId: stored.projectId } : {}), ...(stored.worktreeId ? { worktreeId: stored.worktreeId } : {}) };
+  }
+  async grant(sessionId, nodes, version, mode = 'explicit') {
+    await this.register(sessionId);
+    if (!['all', 'explicit'].includes(mode)) throw new MapError('INVALID_SCOPE', 'Use all or explicit Session scope');
+    const next = this.queue.then(async () => {
+      const data = structuredClone(this.data);
+      data.sessions[sessionId] = { mode, nodes: mode === 'all' ? [] : [...new Set(nodes)], version, changedAt: new Date().toISOString() };
+      await atomicWrite(this.file, encode(data)); this.data = data;
+    });
+    this.queue = next.catch(() => {}); await next;
+  }
+}

package/scripts/workbench/attachments.mjs

@@ -0,0 +1,92 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { MapError, entries } from '../shared/map-model.mjs';
+import { hash, atomicWrite, encode, readJSON } from '../shared/io.mjs';
+
+const limit = 8 * 1024 * 1024;
+const inside = (root, file) => file.startsWith(root + path.sep);
+
+export class Attachments {
+  constructor(root) { this.root = root; this.tail = Promise.resolve(); }
+
+  save(input, doc) {
+    const next = this.tail.then(() => this.write(input, doc));
+    this.tail = next.catch(() => {});
+    return next;
+  }
+
+  async write({ uploadId, nodeId, name, base64 }, doc) {
+    if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(uploadId || '') || typeof name !== 'string' || !name || name.length > 255 || typeof base64 !== 'string') {
+      throw new MapError('INVALID_ATTACHMENT', 'Invalid upload ID, filename or base64');
+    }
+    if (base64.length > Math.ceil(limit / 3) * 4) throw new MapError('ATTACHMENT_TOO_LARGE', '附件最大为 8 MiB', 413);
+    if (base64.length % 4 || /[^A-Za-z0-9+/=]/.test(base64)) throw new MapError('INVALID_ATTACHMENT', 'Invalid base64');
+    if (!doc?.root || !entries(doc.root).has(nodeId)) throw new MapError('NOT_FOUND', 'Attachment node no longer exists', 404);
+    const bytes = Buffer.from(base64, 'base64');
+    if (bytes.toString('base64') !== base64) throw new MapError('INVALID_ATTACHMENT', 'Invalid base64');
+    if (bytes.length > limit) throw new MapError('ATTACHMENT_TOO_LARGE', '附件最大为 8 MiB', 413);
+
+    const cleanName = path.basename(name.replace(/\\/g, '/')).replace(/[^a-zA-Z0-9._-]/g, '-').slice(-90) || 'attachment.bin';
+    const dir = path.join(this.root, 'docs/shots');
+    for (const rel of ['docs', 'docs/shots']) {
+      const target = path.join(this.root, rel);
+      try {
+        if (!inside(this.root, await fs.realpath(target))) throw new MapError('INVALID_PATH', 'Attachment directory escapes project', 403);
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+        await fs.mkdir(target);
+      }
+    }
+
+    uploadId = uploadId.toLowerCase();
+    const rel = `docs/shots/${uploadId}-${cleanName}`;
+    const dest = path.join(this.root, rel);
+    const receiptFile = path.join(this.root, '.codex/context/private/sync/uploads', `${uploadId}.json`);
+    const identity = { uploadId, nodeId, name, path: rel, digest: hash(bytes) };
+    const previous = await readJSON(receiptFile, null);
+    if (previous && JSON.stringify(previous) !== JSON.stringify(identity)) {
+      throw new MapError('UPLOAD_ID_REUSED', 'Upload ID belongs to a different attachment; existing file preserved', 409);
+    }
+    if (!previous) await atomicWrite(receiptFile, encode(identity));
+
+    const temp = path.join(dir, `.${uploadId}-${randomUUID()}.tmp`);
+    let handle;
+    try {
+      handle = await fs.open(temp, 'wx', 0o600);
+      await handle.writeFile(bytes);
+      await handle.sync();
+      await handle.close();
+      handle = null;
+      try {
+        await fs.link(temp, dest);
+      } catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+        if (!inside(this.root, await fs.realpath(dest)) || hash(await fs.readFile(dest)) !== hash(bytes)) {
+          throw new MapError('UPLOAD_ID_REUSED', 'Upload ID already has different content; existing file preserved', 409);
+        }
+        return { saved: true, duplicate: true, path: rel, name, uploadId };
+      }
+      return { saved: true, path: rel, name, uploadId };
+    } finally {
+      if (handle) await handle.close();
+      await fs.unlink(temp).catch(() => {});
+    }
+  }
+
+  async read(rel, doc) {
+    if (typeof rel !== 'string' || !rel || rel.includes('\\') || rel.includes(':') || path.isAbsolute(rel) || rel.split('/').some(part => !part || part === '.' || part === '..')) {
+      throw new MapError('INVALID_PATH', 'Use a project-relative attachment path', 403);
+    }
+    const referenced = doc?.root && [...entries(doc.root).values()].some(({ node }) =>
+      [node, ...(node.memories || []), ...(node.ideas || []), ...(node.bugs || []), ...(node.dormant || [])]
+        .some(owner => (owner.files || []).some(file => (typeof file === 'string' ? file : file.path) === rel))
+    );
+    if (!referenced) throw new MapError('NOT_FOUND', 'File is not referenced by the current map', 404);
+    const target = await fs.realpath(path.join(this.root, rel));
+    if (!inside(this.root, target)) throw new MapError('INVALID_PATH', 'Attachment escapes project', 403);
+    const stat = await fs.stat(target);
+    if (!stat.isFile() || stat.size > limit) throw new MapError('ATTACHMENT_TOO_LARGE', '附件预览最大为 8 MiB', 413);
+    return fs.readFile(target);
+  }
+}

package/scripts/workbench/browser-login.mjs

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import os from 'node:os';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { atomicWrite, encode, readJSON, withFileLock, pause } from '../shared/io.mjs';
+import { fail } from '../shared/protocol.mjs';
+
+async function request(origin, route, input, fetcher) {
+  let response;
+  try {
+    response = await fetcher(new URL(route, origin), { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(15000),
+      headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(input) });
+  } catch { fail('UNAVAILABLE', 'Cloud authorization is unavailable; retry the same connection command'); }
+  if ([404, 405, 426].includes(response.status)) fail('UPGRADE_REQUIRED', 'Cloud does not support browser authorization; upgrade Cloud or use the explicit private-input login');
+  if (!response.headers.get('content-type')?.includes('application/json')) fail('UNAVAILABLE', 'Cloud returned an invalid authorization reply');
+  let result;
+  try {
+    const chunks = []; let size = 0;
+    for await (const chunk of response.body) { size += chunk.length; if (size > 16384) fail('TOO_LARGE', 'Authorization reply is too large'); chunks.push(chunk); }
+    result = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  } catch (error) { if (error.code === 'TOO_LARGE') throw error; fail('UNAVAILABLE', 'Cloud authorization reply was interrupted'); }
+  if (!response.ok || result?.ok !== true) fail(result?.error?.code || 'UNAVAILABLE', result?.error?.message || 'Cloud authorization failed');
+  if (!result.data || typeof result.data !== 'object') fail('UNAVAILABLE', 'Cloud returned an invalid authorization reply');
+  return { data: result.data, credential: response.headers.get('x-context-guard-credential') };
+}
+
+// The model sees only the verification URL/code. The backend keeps the claim
+// secret and final credential private, including across a stopped CLI invocation.
+export async function browserLogin(device, { repository, repositoryId, wait = false, onPending = () => {}, fetcher = fetch, label = os.hostname() }) {
+  const origin = new URL(device.origin);
+  if (origin.username || origin.password || origin.pathname !== '/' || origin.search || origin.hash || origin.protocol !== 'https:' && !(device.allowLoopback && origin.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(origin.hostname))) fail('FORBIDDEN', 'Cloud authorization requires an HTTPS origin');
+  const file = path.join(device.directory, 'browser-login.json');
+  let first = true;
+  for (;;) {
+    const outcome = await withFileLock(file + '.lock', async () => {
+      const connected = await readJSON(device.file, null);
+      if (connected?.origin === device.origin && connected.repositoryId === repositoryId && connected.credential) {
+        try {
+          await device.transmit({ v: 2, id: randomUUID(), type: 'sync.heartbeat', payload: { sessions: [] } });
+          const { credential: _secret, origin: _origin, ...data } = connected;
+          return { connected: true, ...data };
+        } catch (error) {
+          if (error.code !== 'UNAUTHORIZED') throw error;
+        }
+      }
+      let pending = await readJSON(file, null);
+      if (!pending?.deviceCode || pending.origin !== device.origin || pending.repository !== repository || pending.repositoryId !== repositoryId || Date.parse(pending.expiresAt) <= Date.now()) {
+        pending = { origin: device.origin, repository, repositoryId, deviceCode: randomBytes(32).toString('base64url'), label: String(label).slice(0, 80),
+          expiresAt: new Date(Date.now() + 600000).toISOString() };
+        await atomicWrite(file, encode(pending));
+      }
+      if (!pending.verificationUrl) {
+        const identity = await device.identity();
+        const { data } = await request(device.origin, '/api/auth/device/start', { repository, clientId: identity.clientId, deviceCode: pending.deviceCode, label: pending.label }, fetcher);
+        const verification = new URL(data.verificationPath, device.origin);
+        if (verification.origin !== device.origin || verification.pathname !== '/connect' || !/^[A-F0-9]{4}-[A-F0-9]{4}$/.test(data.userCode) || verification.searchParams.get('code') !== data.userCode || !Number.isFinite(Date.parse(data.expiresAt)) || !Number.isInteger(data.expiresIn) || data.expiresIn <= 0 || data.expiresIn > 600) fail('UNAVAILABLE', 'Cloud returned an invalid authorization link');
+        pending = { ...pending, verificationUrl: verification.href, userCode: data.userCode, expiresAt: new Date(Date.now() + data.expiresIn * 1000).toISOString() };
+        await atomicWrite(file, encode(pending));
+      }
+      const safe = { connected: false, authorizationRequired: true, verificationUrl: pending.verificationUrl, userCode: pending.userCode, expiresAt: pending.expiresAt };
+      if (first) await onPending(safe);
+      let result;
+      try { result = await request(device.origin, '/api/auth/device/poll', { deviceCode: pending.deviceCode }, fetcher); }
+      catch (error) {
+        if (['UNAUTHORIZED', 'FORBIDDEN'].includes(error.code)) await atomicWrite(file, encode({ status: error.code }));
+        throw error;
+      }
+      if (result.data.status === 'pending') return safe;
+      if (!result.credential || result.credential.length < 32 || !result.data.projectId || !result.data.capabilities?.includes('device-memory')) fail('UNAVAILABLE', 'Cloud did not issue a project device connection');
+      await device.saveConnection(result.data, result.credential, { repositoryId });
+      await atomicWrite(file, encode({ status: 'connected' }));
+      return { connected: true, ...result.data };
+    });
+    if (outcome.connected || !wait) return outcome;
+    if (Date.now() >= Date.parse(outcome.expiresAt)) fail('UNAUTHORIZED', 'Browser authorization expired; retry the connection command');
+    first = false;
+    await pause(5000);
+  }
+}