graphlin 0.1.0

package/runtime/daemon/lock.mjs

@@ -0,0 +1,137 @@
+import { mkdir, rename, rm, lstat, opendir } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { atomicJSON, privateDirectory, readPrivateJSON, runtimeError, uid, PROTOCOL } from './paths.mjs';
+import { requestIPC } from './ipc.mjs';
+
+function alive(pid) {
+  if (!Number.isSafeInteger(pid) || pid < 1) return true;
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error.code !== 'ESRCH'; }
+}
+
+const wait = ms => new Promise(resolve => setTimeout(resolve, ms));
+const CLAIM_NAME = /^([1-9]\d*)-([0-9a-f-]{36})$/;
+const busy = () => runtimeError('daemon_busy');
+const absent = error => { if (error.code !== 'ENOENT') throw error; return null; };
+
+// Bakery tickets serialize publication and removal, not the daemon lifetime.
+// A unique directory registers "choosing" before any ticket is read or written.
+// Its PID is in its name, so even a crash before writing the ticket is recoverable.
+// Unlike a fixed reaping guard, deleting a dead claim can never delete a successor.
+async function claims(directory) {
+  const result = [];
+  let scanned = 0;
+  for await (const entry of await opendir(directory)) {
+    if (++scanned > 1024) throw busy();
+    const match = CLAIM_NAME.exec(entry.name);
+    if (!match || !entry.isDirectory()) throw busy();
+    const filename = path.join(directory, entry.name), pid = Number(match[1]);
+    if (!alive(pid)) {
+      await rm(filename, { recursive: true, force: true });
+      continue;
+    }
+    const ticketPath = path.join(filename, 'ticket.json');
+    const ticket = await readPrivateJSON(ticketPath, 4096).catch(async error => {
+      // A departing peer can unlink an already-open ticket before fstat;
+      // readPrivateJSON then correctly rejects its zero link count. Treat
+      // only a now-absent ticket as a choosing/departing peer, never as ready.
+      if (error.code === 'ENOENT' || !await lstat(ticketPath).catch(absent)) return null;
+      throw busy();
+    });
+    if (ticket && (ticket.id !== entry.name || !Number.isSafeInteger(ticket.number) || ticket.number < 1)) throw busy();
+    // A peer may have finished between directory enumeration and reading.
+    if (!ticket && !await lstat(filename).catch(absent)) continue;
+    result.push({ id: entry.name, number: ticket?.number ?? null });
+    if (result.length > 64) throw busy();
+  }
+  return result;
+}
+
+export async function withPublicationGuard(paths, action) {
+  const directory = `${paths.lock}.claims`;
+  await privateDirectory(directory);
+  const id = `${process.pid}-${randomUUID()}`, claim = path.join(directory, id);
+  await mkdir(claim, { mode: 0o700 });
+  try {
+    const peers = await claims(directory);
+    const number = 1 + Math.max(0, ...peers.map(peer => peer.number ?? 0));
+    if (!Number.isSafeInteger(number)) throw busy();
+    await atomicJSON(path.join(claim, 'ticket.json'), { id, number }, 4096);
+    const deadline = Date.now() + 2000;
+    while (true) {
+      const pending = (await claims(directory)).some(peer => peer.id !== id &&
+        (peer.number === null || peer.number < number || (peer.number === number && peer.id < id)));
+      if (!pending) return await action(claim);
+      if (Date.now() >= deadline) throw busy();
+      await wait(20);
+    }
+  } finally {
+    await rm(claim, { recursive: true, force: true });
+  }
+}
+
+async function existingOwner(paths) {
+  const info = await lstat(paths.lock).catch(absent);
+  if (!info) return null;
+  if (!info.isDirectory() || info.isSymbolicLink() || (info.mode & 0o077) ||
+      (uid() !== undefined && info.uid !== uid())) throw busy();
+  const owner = await readPrivateJSON(path.join(paths.lock, 'owner.json'), 4096).catch(error => {
+    if (error.code !== 'ENOENT') throw busy();
+    return null;
+  });
+  if (owner) {
+    if (!Number.isSafeInteger(owner.pid) || owner.pid < 1 || typeof owner.instanceId !== 'string') throw busy();
+    return owner;
+  }
+  // Legacy versions could expose an empty directory before owner.json was
+  // committed. Respect any complete live owner in an interrupted temp write.
+  let scanned = 0;
+  for await (const entry of await opendir(paths.lock)) {
+    if (++scanned > 64 || !/^owner\.json\.[0-9a-f-]+\.tmp$/.test(entry.name) || !entry.isFile()) throw busy();
+    const partial = await readPrivateJSON(path.join(paths.lock, entry.name), 4096).catch(() => null);
+    if (partial && alive(partial.pid)) throw busy();
+  }
+  return null;
+}
+
+export async function health(paths) {
+  const owner = await readPrivateJSON(path.join(paths.lock, 'owner.json'), 4096);
+  if (owner.protocol !== PROTOCOL || owner.projectId !== paths.projectId) throw runtimeError('invalid_owner');
+  const result = await requestIPC(paths.socket, { op: 'health', instanceId: owner.instanceId });
+  if (!result.ok || result.instanceId !== owner.instanceId || result.projectId !== paths.projectId ||
+      result.protocol !== PROTOCOL || result.pid !== owner.pid) throw runtimeError('invalid_daemon');
+  return result;
+}
+
+export async function acquireLock(paths) {
+  const owner = { protocol: PROTOCOL, projectId: paths.projectId, pid: process.pid,
+    instanceId: randomUUID(), createdAt: Date.now() };
+  await withPublicationGuard(paths, async claim => {
+    const previous = await existingOwner(paths);
+    // Never kill or displace a live PID, including one without working IPC.
+    if (previous && alive(previous.pid)) {
+      try { await health(paths); } catch { throw busy(); }
+      throw runtimeError('already_running');
+    }
+    await rm(paths.lock, { recursive: true, force: true });
+    await rm(`${paths.lock}.reaping`, { recursive: true, force: true });
+    const publication = path.join(claim, 'publication');
+    await mkdir(publication, { mode: 0o700 });
+    await atomicJSON(path.join(publication, 'owner.json'), owner, 4096);
+    // The public lock first becomes visible with its complete owner record.
+    // A crash before this rename leaves only a uniquely named dead claim.
+    await rename(publication, paths.lock);
+  });
+  let releasing;
+  return {
+    owner,
+    release() {
+      releasing ??= withPublicationGuard(paths, async () => {
+        const current = await existingOwner(paths);
+        if (current?.instanceId === owner.instanceId) await rm(paths.lock, { recursive: true, force: true });
+      });
+      return releasing;
+    },
+  };
+}

package/runtime/daemon/manager.mjs

@@ -0,0 +1,320 @@
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { projectPaths, defaultDataDir, MAX_STATE_BYTES, runtimeError, readPrivateJSON } from './paths.mjs';
+import { health } from './lock.mjs';
+import { requestIPC } from './ipc.mjs';
+import { diagnosticArtifactId, readPersistedDiagnostics, DIAGNOSTIC_LIMITS } from './diagnostics.mjs';
+import { readSettings, resolvePolicy } from './settings.mjs';
+import { inspectInstalledPackages } from './connection-info.mjs';
+
+const worker = fileURLToPath(new URL('../../scripts/daemon.mjs', import.meta.url));
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+const safeCodes = new Set(['already_running', 'daemon_busy', 'invalid_project', 'unsupported_platform',
+  'unsafe_data_directory', 'policy_restart_required', 'port_restart_required', 'port_in_use',
+  'daemon_start_failed', 'daemon_start_timeout', 'shutdown_failed', 'shutdown_pending',
+  'restart_required', 'diagnostics_unavailable', 'invalid_log_filter', 'unsafe_settings', 'invalid_settings', 'settings_busy']);
+
+export function publicError(error) {
+  return safeCodes.has(error?.code) ? error.code : 'runtime_unavailable';
+}
+
+export async function daemonStatus({ projectRoot, dataDir } = {}) {
+  let paths;
+  try {
+    paths = await projectPaths(projectRoot, dataDir);
+    return { running: true, logPath: path.join(paths.directory, 'diagnostics.jsonl'), ...await health(paths) };
+  } catch { return { running: false, code: 'not_running',
+    ...(paths ? { logPath: path.join(paths.directory, 'diagnostics.jsonl') } : {}) }; }
+}
+
+function validateRuntime() {
+  if (Number(process.versions.node.split('.')[0]) < 22) throw runtimeError('unsupported_runtime');
+}
+
+function validateExisting(current, options) {
+  const { allowSource, persistEvidence, displayEvidence } = resolvePolicy(options, { current: current.policy });
+  const { mode = 'live', port = 0 } = options;
+  if (current.mode !== mode || current.policy.transmitSource !== Boolean(allowSource) ||
+      current.policy.persistEvidence !== Boolean(persistEvidence) ||
+      current.policy.displayEvidence !== Boolean(displayEvidence)) throw runtimeError('policy_restart_required');
+  if (port && port !== current.port) throw runtimeError('port_restart_required');
+}
+
+async function existingLaunch(paths, current, options) {
+  validateExisting(current, options);
+  const launch = await requestIPC(paths.socket, { op: 'launch', instanceId: current.instanceId });
+  if (!launch.ok || launch.instanceId !== current.instanceId) throw runtimeError('daemon_start_failed');
+  return { ...launch, reused: true };
+}
+
+async function waitForExisting(paths, options, signal) {
+  const deadline = Date.now() + 8000;
+  while (Date.now() < deadline && !signal?.aborted) {
+    const current = await daemonStatus(paths);
+    if (current.running) return existingLaunch(paths, current, options);
+    await delay(80);
+  }
+  if (!signal?.aborted) throw runtimeError('daemon_busy');
+  return null;
+}
+
+async function ownerMatches(paths, instanceId) {
+  const owner = await readPrivateJSON(path.join(paths.lock, 'owner.json'), 4096).catch(() => null);
+  if (owner?.instanceId !== instanceId) return false;
+  if (!Number.isSafeInteger(owner.pid) || owner.pid < 1) return false;
+  try { process.kill(owner.pid, 0); return true; }
+  catch (error) { return error.code !== 'ESRCH'; }
+}
+
+async function stopInstance(paths, instanceId) {
+  if (!await ownerMatches(paths, instanceId)) return { ok: true, stopped: false };
+  try {
+    const result = await requestIPC(paths.socket, { op: 'shutdown', instanceId });
+    if (!result.ok) return { ok: false, code: 'shutdown_pending' };
+  } catch {
+    if (!await ownerMatches(paths, instanceId)) return { ok: true, stopped: true };
+    return { ok: false, code: 'shutdown_pending' };
+  }
+  const deadline = Date.now() + 5000;
+  while (Date.now() < deadline) {
+    if (!await ownerMatches(paths, instanceId)) return { ok: true, stopped: true };
+    await delay(50);
+  }
+  return { ok: false, code: 'shutdown_pending' };
+}
+
+/**
+ * Own a server in this process, or attach to the existing canonical instance.
+ * onReady receives the one-use URL once; this promise stays pending until that
+ * instance closes or the caller aborts. Abort never stops a replacement owner.
+ */
+export async function runForeground({ projectRoot, dataDir = defaultDataDir(), signal,
+  allowSource, persistEvidence, displayEvidence, mode = 'live', port = 0 } = {}, onReady = () => {}) {
+  validateRuntime();
+  if (signal?.aborted) return;
+  const paths = await projectPaths(projectRoot, dataDir);
+  const options = { allowSource, persistEvidence, displayEvidence, mode, port };
+  let server, launch, interrupted;
+  const interruption = new Promise(resolve => { interrupted = resolve; });
+  const interrupt = () => interrupted();
+  signal?.addEventListener('abort', interrupt, { once: true });
+  try {
+    const current = await daemonStatus(paths);
+    if (current.running) launch = await existingLaunch(paths, current, options);
+    else if (!signal?.aborted) {
+      const settings = mode === 'demo' ? {} : await readSettings(paths);
+      const policy = resolvePolicy(options, { saved: settings.policy });
+      await projectPaths(projectRoot, dataDir, { create: true });
+      const { startServer } = await import('./server.mjs');
+      const demo = mode === 'demo' ? await import('./demo.mjs') : null;
+      try {
+        server = await startServer({ projectRoot: paths.projectRoot, dataDir: paths.dataDir, mode, port,
+          policy: { transmitSource: policy.allowSource, persistEvidence: policy.persistEvidence,
+            displayEvidence: policy.displayEvidence },
+          apiKey: policy.allowSource ? process.env.TYPESAFE_API_KEY ?? settings.apiKey : undefined,
+          decisionService: demo?.demoDecisionService() });
+      } catch (error) {
+        if (['daemon_busy', 'already_running'].includes(error.code)) launch = await waitForExisting(paths, options, signal);
+        else if (error.code === 'EADDRINUSE') throw runtimeError('port_in_use');
+        else throw error;
+      }
+      if (server && !signal?.aborted) {
+        launch = { ...await health(paths), url: server.url, reused: false };
+        if (demo) {
+          const replay = demo.replayDemo(server.pipeline, paths.projectRoot);
+          await Promise.race([replay, interruption]);
+          // Closing the pipeline cancels work; observe the replay's eventual
+          // rejection if a signal interrupted it before the ready announcement.
+          replay.catch(() => {});
+        }
+      }
+    }
+    if (!launch || signal?.aborted) return;
+    onReady({ ...launch, foreground: true });
+    if (server) {
+      const closed = await Promise.race([server.whenClosed, interruption]);
+      if (closed && !closed.ok) throw runtimeError('shutdown_failed');
+    } else {
+      while (!signal?.aborted && await ownerMatches(paths, launch.instanceId)) {
+        // Each poll settles independently; racing the same pending signal
+        // promise here would retain one callback per poll until interruption.
+        await delay(200);
+      }
+      if (signal?.aborted) {
+        const stopped = await stopInstance(paths, launch.instanceId);
+        if (!stopped.ok) throw runtimeError(stopped.code);
+      }
+    }
+  } finally {
+    signal?.removeEventListener('abort', interrupt);
+    await server?.close();
+  }
+}
+
+// Detached operation is reserved for an explicit CLI --background request or
+// MCP. The normal interactive CLI uses runForeground instead.
+export async function startDaemon({ projectRoot, dataDir = defaultDataDir(), background = true,
+  allowSource, persistEvidence, displayEvidence, mode = 'live', port = 0 } = {}) {
+  validateRuntime();
+  if (background !== true) throw runtimeError('background_required');
+  const paths = await projectPaths(projectRoot, dataDir);
+  const options = { allowSource, persistEvidence, displayEvidence, mode, port };
+  const existing = await daemonStatus({ projectRoot: paths.projectRoot, dataDir: paths.dataDir });
+  if (existing.running) return { ...await existingLaunch(paths, existing, options), foreground: false };
+  const settings = mode === 'demo' ? {} : await readSettings(paths);
+  const policy = resolvePolicy(options, { saved: settings.policy });
+  await projectPaths(projectRoot, dataDir, { create: true });
+  const args = [worker, '--project', paths.projectRoot, '--data-dir', paths.dataDir, '--mode', mode, '--port', String(port)];
+  if (policy.allowSource) args.push('--allow-source');
+  if (policy.persistEvidence) args.push('--persist-evidence');
+  if (!policy.displayEvidence) args.push('--no-display-evidence');
+  const env = { ...process.env };
+  // A metadata-only or fixture daemon does not inherit the paid-service key.
+  if (!policy.allowSource || mode !== 'live') delete env.TYPESAFE_API_KEY;
+  else if (env.TYPESAFE_API_KEY === undefined && settings.apiKey) env.TYPESAFE_API_KEY = settings.apiKey;
+  const child = spawn(process.execPath, args, {
+    detached: true, stdio: 'ignore', env, cwd: paths.projectRoot,
+  });
+  let spawnFailed = false;
+  child.on('error', () => { spawnFailed = true; });
+  child.unref();
+  const deadline = Date.now() + 8000;
+  while (Date.now() < deadline) {
+    const current = await daemonStatus({ projectRoot: paths.projectRoot, dataDir: paths.dataDir });
+    if (current.running) return { ...await existingLaunch(paths, current, options),
+      reused: current.pid !== child.pid, foreground: false };
+    if (spawnFailed) throw runtimeError('daemon_start_failed');
+    if (child.exitCode !== null || child.signalCode !== null) {
+      // Another concurrent starter may have won the lock. Wait for that owner
+      // to finish starting rather than launching a second server or failing it.
+      const owner = await readPrivateJSON(path.join(paths.lock, 'owner.json'), 4096).catch(() => null);
+      if (!owner || owner.pid === child.pid) throw runtimeError('daemon_start_failed');
+    }
+    await delay(80);
+  }
+  child.kill('SIGTERM');
+  const escalation = setTimeout(() => { child.kill('SIGKILL'); }, 250);
+  child.once('exit', () => clearTimeout(escalation));
+  throw runtimeError('daemon_start_timeout');
+}
+
+export async function stopDaemon({ projectRoot, dataDir } = {}) {
+  const paths = await projectPaths(projectRoot, dataDir);
+  const current = await daemonStatus({ projectRoot, dataDir });
+  if (!current.running) return { ok: true, stopped: false };
+  return stopInstance(paths, current.instanceId);
+}
+
+export async function exportDaemon({ projectRoot, dataDir } = {}) {
+  const paths = await projectPaths(projectRoot, dataDir);
+  const current = await health(paths);
+  const response = await requestIPC(paths.socket, { op: 'export', instanceId: current.instanceId },
+    { maxResponseBytes: MAX_STATE_BYTES + 4096 });
+  if (!response.ok) throw runtimeError('export_unavailable');
+  return response.snapshot;
+}
+
+export async function diagnosticLogs({ projectRoot, dataDir, file } = {}) {
+  const paths = await projectPaths(projectRoot, dataDir);
+  const artifactId = file === undefined ? undefined : diagnosticArtifactId(paths.projectRoot, file, projectRoot);
+  let current;
+  try { current = await health(paths); } catch { /* A stopped project can read its private retained log. */ }
+  if (!current) return readPersistedDiagnostics(paths, { artifactId });
+  const response = await requestIPC(paths.socket, { op: 'diagnostics', instanceId: current.instanceId, artifactId },
+    { maxResponseBytes: DIAGNOSTIC_LIMITS.ringBytes + 64 * 1024, timeoutMs: 1500 });
+  if (!response.ok) throw runtimeError(response.code === 'invalid_operation' ? 'restart_required' : 'diagnostics_unavailable');
+  if (response.schemaVersion !== 1 || !Array.isArray(response.records) || !response.stats) {
+    throw runtimeError('restart_required');
+  }
+  const { ok, ...envelope } = response;
+  return envelope;
+}
+
+async function version(command) {
+  return new Promise(resolve => {
+    const env = { ...process.env };
+    delete env.TYPESAFE_API_KEY;
+    const child = spawn(command, ['--version'], { stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true, env });
+    let stdout = '', bytes = 0, finished = false, terminating = false, escalation;
+    const deadline = setTimeout(terminate, 1000);
+    function finish(value) {
+      if (finished) return;
+      finished = true;
+      clearTimeout(deadline); clearTimeout(escalation);
+      child.stdout.destroy();
+      resolve(value);
+    }
+    function terminate() {
+      if (finished || terminating) return;
+      terminating = true;
+      child.kill('SIGTERM');
+      escalation = setTimeout(() => {
+        child.kill('SIGKILL');
+        // Do not wait indefinitely for an inherited stdout pipe to close.
+        finish(null);
+      }, 200);
+    }
+    child.on('error', () => finish(null));
+    child.stdout.on('error', () => terminate());
+    child.stdout.on('data', chunk => {
+      bytes += chunk.length;
+      if (bytes > 4096) { terminate(); return; }
+      stdout += chunk.toString('utf8');
+    });
+    child.on('close', code => {
+      const found = !terminating && code === 0 && stdout.match(/\b\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?/);
+      finish(found ? found[0] : null);
+    });
+  });
+}
+
+export async function doctor({ projectRoot, dataDir } = {}) {
+  const [status, claude, codex, kiro, settingsResult] = await Promise.all([
+    daemonStatus({ projectRoot, dataDir }), version('claude'), version('codex'), version('kiro'),
+    readSettings({ projectRoot, dataDir }).then(value => ({ value }), () => ({ error: 'unsafe_settings' })),
+  ]);
+  const settings = settingsResult.value ?? {};
+  const packages = settings.installation ? await inspectInstalledPackages({
+    dataDir: (await projectPaths(projectRoot, dataDir)).dataDir, version: settings.installation.version,
+  }).catch(() => ({ claude: false, codex: false })) : {};
+  const credential = (process.env.TYPESAFE_API_KEY ?? settings.apiKey) ? 'configured_not_verified' : 'missing';
+  const received = status.running ? status.observations?.hooks ?? {} : {};
+  const hosts = Object.fromEntries(Object.entries({ claude, codex }).map(([host, hostVersion]) => [host, {
+    version: hostVersion,
+    installation: settings.installation?.hosts.includes(host) ? 'recorded' : 'not_recorded',
+    setupPending: settings.installation?.pendingHosts?.includes(host) ?? false,
+    packageFiles: packages[host] ? 'verified' : 'not_verified',
+    activation: received[host] > 0 ? 'hook_observed' : 'not_verified',
+    receivedHooks: received[host] ?? 0,
+  }]));
+  const policy = resolvePolicy({}, { current: status.running ? status.policy : undefined, saved: settings.policy });
+  const nextActions = [];
+  if (settingsResult.error) nextActions.push('Settings could not be safely read. Check permissions on the Graphlin data directory.');
+  if (!settings.installation?.hosts.length) nextActions.push('Run graphlin init in this project to install an agent plugin.');
+  if (settings.installation?.pendingHosts?.length) nextActions.push('Agent setup is incomplete. Run graphlin again to resume the requested installations.');
+  else if (settings.installation?.hosts.some(host => !packages[host])) {
+    nextActions.push('Installed package files are missing or invalid. Run graphlin init to repair the installation.');
+  }
+  if (!status.running) nextActions.push('Run graphlin in this project and keep that terminal open.');
+  if (!policy.allowSource) nextActions.push('Architecture classification needs source-sharing consent. Run graphlin init to choose it.');
+  if (policy.allowSource && credential === 'missing') nextActions.push('Run graphlin init to save your TypeSafe key at its hidden prompt.');
+  if (['unavailable', 'timeout'].includes(status.status?.classifier)) {
+    nextActions.push('Run graphlin logs for the classifier failure reason. If authentication failed, run graphlin init --replace-key, then restart Graphlin.');
+  }
+  if (status.running && !Object.values(received).some(count => count > 0)) {
+    nextActions.push('Start Claude Code or Codex with Graphlin installed, review its hook permissions, and ask it to explore this project.');
+  } else if (status.running && !status.observations?.shapes) {
+    nextActions.push('Ask your agent to read the main source files. Use graphlin logs to see why observations have not produced shapes.');
+  }
+  return {
+    runtime: { node: process.versions.node, supported: Number(process.versions.node.split('.')[0]) >= 22,
+      platform: process.platform, privateIPC: process.platform !== 'win32' },
+    hosts: { ...hosts,
+      kiro: { version: kiro, activation: 'inactive_experimental' } },
+    daemon: status,
+    coverage: Object.values(received).some(count => count > 0) ? 'hook_delivery_observed' : 'host_activation_unverified',
+    credential, settings: settingsResult.error ?? 'readable', nextActions,
+    note: 'No remote credential check was sent. An observed hook confirms delivery, not every host permission or runtime connectivity.',
+  };
+}

package/runtime/daemon/paths.mjs

@@ -0,0 +1,108 @@
+import { constants } from 'node:fs';
+import { mkdir, realpath, lstat, open, rename, rm, chmod } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+export const PROTOCOL = 1;
+export const MAX_IPC_BYTES = 256 * 1024;
+export const MAX_STATE_BYTES = 2 * 1024 * 1024;
+export const uid = () => process.getuid?.();
+export const hash = (value) => createHash('sha256').update(value).digest('hex');
+export const runtimeError = (code) => Object.assign(new Error(code), { code });
+
+export function defaultDataDir() {
+  return path.resolve(process.env.GRAPHLIN_DATA_DIR || path.join(homedir(), '.local', 'state', 'graphlin'));
+}
+
+export async function canonicalProjectRoot(input) {
+  if (typeof input !== 'string' || !input || input.length > 4096) throw runtimeError('invalid_project');
+  const resolved = await realpath(path.resolve(input));
+  if (!(await lstat(resolved)).isDirectory()) throw runtimeError('invalid_project');
+  // A .git file identifies a worktree just as a .git directory identifies a checkout.
+  // No transcript discovery, repository command, or recursive source scan is needed.
+  let current = resolved;
+  while (true) {
+    try {
+      const stat = await lstat(path.join(current, '.git'));
+      if (stat.isFile() || stat.isDirectory()) return current;
+    } catch (error) { if (error.code !== 'ENOENT') throw runtimeError('project_unavailable'); }
+    const parent = path.dirname(current);
+    if (parent === current) return resolved;
+    current = parent;
+  }
+}
+
+export async function privateDirectory(directory) {
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const stat = await lstat(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || (uid() !== undefined && stat.uid !== uid())) {
+    throw runtimeError('unsafe_data_directory');
+  }
+  await chmod(directory, 0o700);
+  return realpath(directory);
+}
+
+export async function projectPaths(projectRoot, dataDir = defaultDataDir(), { create = false } = {}) {
+  if (process.platform === 'win32') throw runtimeError('unsupported_platform');
+  const root = await canonicalProjectRoot(projectRoot);
+  const requested = path.resolve(dataDir);
+  // Resolve existing parent aliases, e.g. macOS /var -> /private/var, even before
+  // the leaf exists so collector/start agree on the same socket name.
+  async function resolveFuture(value) {
+    try { return await realpath(value); }
+    catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      const parent = path.dirname(value);
+      if (parent === value) throw error;
+      return path.join(await resolveFuture(parent), path.basename(value));
+    }
+  }
+  if (create) await privateDirectory(requested);
+  const base = await resolveFuture(requested);
+  const projectId = hash(root);
+  const directory = path.join(base, projectId);
+  // Unix socket paths are short even if the project/data path contains spaces
+  // or exceeds sockaddr_un's platform limit.
+  const sockets = path.join('/tmp', `graphlin-${uid() ?? 'user'}`);
+  const socket = path.join(sockets, `${hash(`${base}\0${root}`).slice(0, 36)}.sock`);
+  if (create) {
+    await privateDirectory(directory);
+    await privateDirectory(sockets);
+  }
+  return { projectRoot: root, projectId, dataDir: base, directory, socket,
+    lock: path.join(directory, 'daemon.lock'), state: path.join(directory, 'state.json') };
+}
+
+export async function readPrivateJSON(filename, limit = MAX_STATE_BYTES) {
+  let file;
+  try {
+    file = await open(filename, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    const stat = await file.stat();
+    if (!stat.isFile() || stat.size > limit || stat.nlink !== 1 ||
+      (stat.mode & 0o077) !== 0 || (uid() !== undefined && stat.uid !== uid())) {
+      throw runtimeError('unsafe_state_file');
+    }
+    const bytes = Buffer.alloc(Math.min(limit + 1, stat.size + 1));
+    const { bytesRead } = await file.read(bytes, 0, bytes.length, 0);
+    if (bytesRead > limit) throw runtimeError('state_too_large');
+    return JSON.parse(bytes.subarray(0, bytesRead).toString('utf8'));
+  } finally { await file?.close(); }
+}
+
+export async function atomicJSON(filename, value, limit = MAX_STATE_BYTES) {
+  const body = JSON.stringify(value);
+  if (Buffer.byteLength(body) > limit) throw runtimeError('state_too_large');
+  const temporary = `${filename}.${randomUUID()}.tmp`;
+  let file;
+  try {
+    file = await open(temporary, 'wx', 0o600);
+    await file.writeFile(body);
+    await file.sync();
+    await file.close(); file = null;
+    await rename(temporary, filename);
+  } finally {
+    await file?.close();
+    await rm(temporary, { force: true }).catch(() => {});
+  }
+}

package/runtime/daemon/persistence.mjs

@@ -0,0 +1,64 @@
+import { atomicJSON, readPrivateJSON, MAX_STATE_BYTES } from './paths.mjs';
+import { rm } from 'node:fs/promises';
+
+const RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+
+export function createPersistence(filename, { maxBytes = MAX_STATE_BYTES, now = Date.now } = {}) {
+  let pending = null, timer = null, running = null, closed = false, failures = 0;
+  function envelope(snapshot) {
+    // The caller MUST pass pipeline.getState({ persistent: true }). This module
+    // never receives raw host input, candidate content, or an API key.
+    const bounded = structuredClone(snapshot);
+    const recent = item => Number.isFinite(Date.parse(item?.at)) && Date.parse(item.at) >= now() - RETENTION_MS;
+    bounded.history = Array.isArray(bounded.history) ? bounded.history.filter(recent).slice(-64) : [];
+    bounded.activity = Array.isArray(bounded.activity) ? bounded.activity.filter(recent).slice(-256) : [];
+    if (Array.isArray(bounded.sessionStates)) {
+      bounded.sessionStates = bounded.sessionStates.slice(-16).map(session => ({
+        ...session, history: Array.isArray(session.history) ? session.history.filter(recent).slice(-64) : [],
+        activity: Array.isArray(session.activity) ? session.activity.filter(recent).slice(-256) : [],
+      }));
+    }
+    const result = { schemaVersion: 1, savedAt: now(), snapshot: bounded };
+    const histories = [bounded, ...(bounded.sessionStates ?? [])];
+    while (Buffer.byteLength(JSON.stringify(result)) > maxBytes) {
+      const oldest = histories.filter(session => session.history?.length)
+        .sort((a, b) => Date.parse(a.history[0].at) - Date.parse(b.history[0].at))[0];
+      if (!oldest) break;
+      oldest.history.shift();
+    }
+    return result;
+  }
+  async function drain() {
+    if (running) return running;
+    running = (async () => {
+      while (pending) {
+        const value = pending; pending = null;
+        try { await atomicJSON(filename, value, maxBytes); } catch { failures++; }
+      }
+    })();
+    try { await running; } finally { running = null; }
+  }
+  return {
+    async load() {
+      try {
+        const value = await readPrivateJSON(filename, maxBytes);
+        if (Number.isFinite(value.savedAt) && now() - value.savedAt > RETENTION_MS) {
+          await rm(filename, { force: true });
+          return undefined;
+        }
+        if (value.schemaVersion !== 1 || !Number.isFinite(value.savedAt) ||
+            value.savedAt > now() + 60_000 || now() - value.savedAt > RETENTION_MS ||
+            value.snapshot?.schemaVersion !== 1) return undefined;
+        return value.snapshot;
+      } catch { return undefined; }
+    },
+    schedule(snapshot) {
+      if (closed) return;
+      try { pending = envelope(snapshot); } catch { failures++; return; }
+      if (!timer) timer = setTimeout(() => { timer = null; void drain(); }, 100);
+    },
+    async flush() { clearTimeout(timer); timer = null; await drain(); },
+    async close() { closed = true; clearTimeout(timer); timer = null; await drain(); },
+    stats: () => ({ persistenceFailures: failures }),
+  };
+}