@kubilaycakmak/projectfreeze 0.0.0-stage → 0.1.0-dev.2

package/src/errors.js

@@ -0,0 +1,20 @@
+export class Fault extends Error {
+  /** @param {string} code @param {string} message @param {unknown} [details] */
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+  }
+}
+
+/** @param {unknown} error */
+export function problem(error) {
+  if (error instanceof Fault) return { code: error.code, message: error.message, details: error.details };
+  return { code: 'INTERNAL', message: 'An internal operation failed. Inspect the operation journal.' };
+}
+
+/** @param {string} code */
+export function exitCode(code) {
+  return ({ USAGE: 2, NOT_FOUND: 3, DENIED: 4, UNSUPPORTED: 5, BUSY: 6, PARTIAL: 7,
+    CANCELLED: 8, UNAVAILABLE: 9, INTERNAL: 1 })[code] ?? 1;
+}

package/src/integrations.js

@@ -0,0 +1,195 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { lstat, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { arch, release } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { Fault } from './errors.js';
+import { bootId, command, executable, linux } from './platform.js';
+
+const dockerEnv = () => {
+  const env = { ...process.env };
+  for (const name of Object.keys(env)) if (/^DOCKER_(HOST|CONTEXT|TLS|TLS_VERIFY|CERT_PATH|API_VERSION)$/i.test(name)) delete env[name];
+  return env;
+};
+
+async function docker(args, options = {}) {
+  const env = dockerEnv();
+  const cli = await executable('docker', process.cwd(), env);
+  const host = process.platform === 'win32' ? 'npipe:////./pipe/docker_engine' : 'unix:///var/run/docker.sock';
+  return command(cli, ['--host', host, ...args], { env, ...options });
+}
+
+export async function composeTargets(project, all) {
+  const targets = [];
+  for (const service of project.recipe?.containers ?? []) {
+    const shared = service.shared || all.some(other => other.id !== project.id && other.recipe?.containers.some(candidate =>
+      candidate.project === service.project && candidate.service === service.service));
+    if (shared) { targets.push({ ...service, shared }); continue; }
+    const output = await docker(['ps', '-aq', '--no-trunc', '--filter', `label=com.docker.compose.project=${service.project}`,
+      '--filter', `label=com.docker.compose.service=${service.service}`]);
+    const ids = output.trim().split(/\s+/).filter(id => /^[a-f0-9]{64}$/.test(id));
+    if (!ids.length) throw new Fault('NOT_FOUND', `No existing Compose container matches ${service.project}/${service.service}.`);
+    for (const id of ids) {
+      const container = await inspectDocker(id);
+      const labels = container.Config.Labels ?? {};
+      if (container.Id !== id || labels['com.docker.compose.project'] !== service.project ||
+          labels['com.docker.compose.service'] !== service.service || labels['com.docker.compose.oneoff']?.toLowerCase() === 'true') {
+        throw new Fault('DENIED', 'Compose container identity did not match the approved policy.');
+      }
+      const configDir = labels['com.docker.compose.project.working_dir'];
+      if (!configDir || configDir !== project.cwd) throw new Fault('DENIED', 'Compose working-directory label differs from the registered project.');
+      if (container.HostConfig.RestartPolicy.Name !== 'no' && container.HostConfig.RestartPolicy.Name !== '') {
+        throw new Fault('UNSUPPORTED', 'Set the exclusive container restart policy to no before managing it.');
+      }
+      targets.push({ ...service, id, running: container.State.Running, paused: container.State.Paused });
+    }
+  }
+  return targets;
+}
+
+async function inspectDocker(id) {
+  if (!/^[a-f0-9]{64}$/.test(id)) throw new Fault('USAGE', 'Container identity is invalid.');
+  return JSON.parse(await docker(['inspect', '--type', 'container', id]))[0];
+}
+
+export async function containerAction(action, id, timeout = 10000) {
+  if (!['pause', 'unpause', 'start', 'stop'].includes(action)) throw new Fault('USAGE', 'Unknown container action.');
+  await inspectDocker(id);
+  await docker([action, ...(action === 'stop' ? ['--timeout', String(Math.ceil(timeout / 1000))] : []), id], { timeout: timeout + 5000 });
+  const { State: state } = await inspectDocker(id);
+  const verified = { pause: state.Running && state.Paused, unpause: state.Running && !state.Paused,
+    start: state.Running && !state.Paused, stop: !state.Running }[action];
+  if (!verified) throw new Fault('PARTIAL', 'The container did not reach its requested state.');
+}
+
+async function hashFiles(path) {
+  const files = {};
+  async function walk(relative) {
+    const entries = await readdir(join(path, relative));
+    for (const name of entries.sort()) {
+      if (!relative && name === 'manifest.json') continue;
+      const key = relative ? `${relative}/${name}` : name;
+      const file = join(path, key);
+      const info = await lstat(file);
+      if (!/^[a-zA-Z0-9_.-]+$/.test(name) || (!info.isDirectory() && !info.isFile())) {
+        throw new Fault('DENIED', 'Checkpoint contains an unexpected file type.');
+      }
+      if (info.isDirectory()) { await walk(key); continue; }
+      if (name.endsWith('.log')) continue;
+      const hash = createHash('sha256');
+      for await (const chunk of createReadStream(file)) hash.update(chunk);
+      Object.defineProperty(files, key, { value: hash.digest('hex'), enumerable: true });
+    }
+  }
+  await walk('');
+  if (!Object.keys(files).length) throw new Fault('PARTIAL', 'CRIU generated no images.');
+  return files;
+}
+
+async function criu() {
+  if (!linux) throw new Fault('UNSUPPORTED', 'Native checkpoint requires Linux CRIU. Use freeze/resume or sleep/wake on this host.');
+  const cli = await executable('criu', process.cwd(), process.env);
+  await command(cli, ['check', '--no-default-config'], { timeout: 30000 }).catch(error => {
+    throw new Fault(error.code === 'DENIED' ? 'DENIED' : 'UNSUPPORTED', 'CRIU preflight failed. Verify kernel support and CRIU permissions.');
+  });
+  const version = (await command(cli, ['--version'])).trim();
+  return { cli, version };
+}
+
+export async function checkpoint(state, project, root, backend, targets, mark, verify) {
+  const id = randomUUID();
+  const path = join(state, `checkpoint-${id}`);
+  const manifest = { schemaVersion: 1, id, backend, project: project.id, platform: process.platform, arch: arch(),
+    kernel: release(), boot: await bootId(), cwd: project.cwd, captured: new Date().toISOString() };
+  if (backend === 'docker') {
+    if (!linux) throw new Fault('UNSUPPORTED', 'Docker checkpoint images require a verifiable local Linux filesystem shared with the Docker engine.');
+    const eligible = targets.filter(target => !target.shared && target.running && !target.paused);
+    if (eligible.length !== 1 || targets.length !== 1 || root) throw new Fault('UNSUPPORTED', 'Docker checkpoint requires a single exclusive running container and no native workload.');
+    const version = JSON.parse(await docker(['version', '--format', '{{json .Server}}']));
+    const info = JSON.parse(await docker(['info', '--format', '{{json .}}']));
+    if (version.Os !== 'linux' || !info.ExperimentalBuild || info.KernelVersion !== release()) {
+      throw new Fault('UNSUPPORTED', 'Docker checkpoint requires a local experimental Linux Docker engine with CRIU.');
+    }
+    const container = await inspectDocker(eligible[0].id);
+    if (container.Mounts.length || container.HostConfig.Privileged || container.HostConfig.AutoRemove || container.HostConfig.NetworkMode !== 'host') {
+      throw new Fault('UNSUPPORTED', 'This Docker checkpoint backend requires an existing host-network container with no mounts, privilege escalation, or auto-removal. Use freeze or sleep for isolated-network containers.');
+    }
+    if (!isAbsolute(info.DockerRootDir)) throw new Fault('DENIED', 'Docker did not report a local checkpoint store.');
+    const imagePath = join(info.DockerRootDir, 'containers', container.Id, 'checkpoints', id);
+    const access = await lstat(join(imagePath, '..')).catch(() => null);
+    if (!access?.isDirectory()) throw new Fault('DENIED', 'The caller cannot verify the Docker engine checkpoint directory.');
+    Object.assign(manifest, { container: container.Id, image: container.Image, version: version.Version, dockerRoot: info.DockerRootDir });
+    await mkdir(path, { mode: 0o700 });
+    mark(id);
+    await docker(['checkpoint', 'create', '--leave-running', manifest.container, id], { timeout: 120000 });
+    manifest.files = await hashFiles(imagePath);
+  } else {
+    if (!root || targets.length) throw new Fault('UNSUPPORTED', 'Native checkpoint requires a live native root and no container dependencies.');
+    const { cli, version } = await criu();
+    const namespace = await verify(root);
+    Object.assign(manifest, { version, root, namespace });
+    await mkdir(path, { mode: 0o700 });
+    mark(id);
+    await verify(root);
+    await command(cli, ['dump', '--no-default-config', '--tree', String(root.pid), '--images-dir', path, '--work-dir', path,
+      '--log-file', 'dump.log', '--leave-running'], { timeout: 120000 });
+    manifest.files = await hashFiles(path);
+  }
+  await writeFile(join(path, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+  return id;
+}
+
+export async function restore(state, project, id, targets, mark) {
+  if (typeof id !== 'string' || !/^[a-f0-9-]{36}$/.test(id)) throw new Fault('USAGE', 'Supply a checkpoint ID.');
+  const path = join(state, `checkpoint-${id}`);
+  const manifest = JSON.parse(await readFile(join(path, 'manifest.json'), 'utf8').catch(() => {
+    throw new Fault('NOT_FOUND', 'A complete checkpoint manifest is missing.');
+  }));
+  if (manifest.schemaVersion !== 1 || manifest.project !== project.id || manifest.cwd !== project.cwd ||
+      manifest.platform !== process.platform || manifest.arch !== arch() || manifest.kernel !== release() || manifest.boot !== await bootId()) {
+    throw new Fault('DENIED', 'Checkpoint requires the original project, host boot, architecture, and kernel.');
+  }
+  if (manifest.backend === 'docker') {
+    const version = JSON.parse(await docker(['version', '--format', '{{json .Server}}']));
+    const info = JSON.parse(await docker(['info', '--format', '{{json .}}']));
+    const container = await inspectDocker(manifest.container);
+    if (version.Version !== manifest.version || container.Image !== manifest.image || info.DockerRootDir !== manifest.dockerRoot ||
+        !info.ExperimentalBuild || !targets.some(t => !t.shared && !t.running && t.id === manifest.container)) {
+      throw new Fault('DENIED', 'Restore requires the original stopped container and matching Docker version.');
+    }
+    const images = join(info.DockerRootDir, 'containers', container.Id, 'checkpoints', id);
+    if (JSON.stringify(await hashFiles(images)) !== JSON.stringify(manifest.files)) throw new Fault('DENIED', 'Checkpoint integrity verification failed.');
+    mark(id);
+    const collision = /^failed to upload checkpoint to containerd: commit failed: content sha256:[a-f0-9]{64}: already exists$/;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      let failure;
+      try { await docker(['start', '--checkpoint', id, manifest.container], { timeout: 120000 }); }
+      catch (error) { failure = error; }
+      const { State: state } = await inspectDocker(manifest.container);
+      if (state.Running && !state.Restarting && !state.Paused) return undefined;
+      if (!failure || !collision.test(state.Error ?? '') || attempt === 2) {
+        throw new Fault('PARTIAL', collision.test(state.Error ?? '')
+          ? 'Docker restore hit a containerd content collision. The checkpoint is retained.'
+          : 'Docker did not verify a running restored container. The checkpoint is retained. Inspect the local Docker container state.');
+      }
+      await delay(1500);
+      const current = await inspectDocker(manifest.container);
+      if (current.State.Running || current.State.Restarting || current.State.Paused || current.State.Dead || current.State.Pid) {
+        throw new Fault('PARTIAL', 'Docker container state changed after a failed restore. Inspect it before retrying.');
+      }
+      mark(id);
+    }
+  }
+  if (manifest.backend !== 'criu') throw new Fault('DENIED', 'Unknown checkpoint backend.');
+  if (JSON.stringify(await hashFiles(path)) !== JSON.stringify(manifest.files)) throw new Fault('DENIED', 'Checkpoint integrity verification failed.');
+  const { cli, version } = await criu();
+  if (manifest.version !== version || targets.length) throw new Fault('DENIED', 'Restore requires the original CRIU version and capture scope.');
+  const work = join(state, `restore-${randomUUID()}`);
+  await mkdir(work, { mode: 0o700 });
+  mark(id);
+  const pidFile = join(work, 'pid');
+  await command(cli, ['restore', '--no-default-config', '--images-dir', path, '--work-dir', work, '--log-file', 'restore.log',
+    '--restore-detached', '--pidfile', pidFile], { timeout: 120000 });
+  return Number((await readFile(pidFile, 'utf8')).trim());
+}

package/src/ipc.js

@@ -0,0 +1,258 @@
+import { spawn } from 'node:child_process';
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { chmod, lstat, mkdir, readFile, realpath, rename, unlink, writeFile } from 'node:fs/promises';
+import { createConnection, createServer } from 'node:net';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { Engine } from './engine.js';
+import { Fault, problem } from './errors.js';
+import { command, checkHelper, helper, windows } from './platform.js';
+import { Store } from './store.js';
+
+export const protocol = 1;
+const maxRequest = 192 * 1024;
+const maxResponse = 16 * 1024 * 1024;
+const nonce = () => randomBytes(32).toString('hex');
+const validHex = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const mac = (secret, ...parts) => createHmac('sha256', Buffer.from(secret, 'hex')).update(JSON.stringify(parts)).digest('hex');
+const same = (a, b) => validHex(a) && validHex(b) && timingSafeEqual(Buffer.from(a, 'hex'), Buffer.from(b, 'hex'));
+const recordPath = dir => join(dir, 'endpoint.json');
+const actions = new Set(['list', 'discover', 'inspect', 'listeners', 'history', 'operation', 'cancel', 'adopt', 'run', 'freeze', 'resume',
+  'sleep', 'wake', 'checkpoint', 'restore', 'reconcile', 'daemon-status', 'daemon-stop']);
+
+export async function stateDirectory() {
+  const dir = process.env.PROJECTFREEZE_HOME ?? (windows ? join(process.env.LOCALAPPDATA ?? homedir(), 'ProjectFreeze') : join(homedir(), '.projectfreeze'));
+  if (!isAbsolute(dir)) throw new Fault('USAGE', 'PROJECTFREEZE_HOME must be an absolute path.');
+  if (windows) {
+    await checkHelper();
+    await command(helper, ['secure-directory', dir]).catch(() => { throw new Fault('DENIED', 'ProjectFreeze state requires a private directory owned by the current Windows user.'); });
+  } else {
+    await mkdir(dir, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST') throw error; });
+    const info = await lstat(dir);
+    if (!info.isDirectory() || info.uid !== process.getuid() || (info.mode & 0o077)) {
+      throw new Fault('DENIED', 'ProjectFreeze state requires a real, user-owned 0700 directory.');
+    }
+  }
+  return realpath(dir);
+}
+
+function frames(socket, limit, callback) {
+  let buffer = Buffer.alloc(0);
+  socket.on('data', chunk => {
+    buffer = Buffer.concat([buffer, chunk]);
+    if (buffer.length > limit) { socket.destroy(); return; }
+    let end;
+    while ((end = buffer.indexOf(10)) !== -1 && !socket.destroyed) {
+      const raw = buffer.subarray(0, end).toString('utf8');
+      buffer = buffer.subarray(end + 1);
+      try { callback(JSON.parse(raw)); }
+      catch { socket.destroy(); }
+    }
+  });
+}
+
+const line = value => `${JSON.stringify(value)}\n`;
+const object = value => value && typeof value === 'object' && !Array.isArray(value);
+
+function validate(action, input) {
+  if (!actions.has(action) || !object(input)) throw new Fault('USAGE', 'Unknown action or invalid arguments.');
+  if (input.ids !== undefined && (!Array.isArray(input.ids) || input.ids.length > 32 || input.ids.some(id => typeof id !== 'string' || !/^p-[a-f0-9]{16}$/.test(id)))) {
+    throw new Fault('USAGE', 'Project IDs must be an array of registered project identifiers.');
+  }
+  if (input.id !== undefined && (typeof input.id !== 'string' || input.id.length > 64)) throw new Fault('USAGE', 'Invalid identifier.');
+  for (const name of ['members', 'exclude']) {
+    if (input[name] !== undefined && (!Array.isArray(input[name]) || input[name].length > 256 || input[name].some(value =>
+      !object(value) || !Number.isSafeInteger(value.pid) || value.pid < 2 || typeof value.birth !== 'string' ||
+      !/^[0-9.]{1,64}$/.test(value.birth) || !validBoot(value.boot)))) throw new Fault('USAGE', 'Invalid process identity.');
+  }
+  if (input.cwd !== undefined && (typeof input.cwd !== 'string' || !isAbsolute(input.cwd))) throw new Fault('USAGE', 'Supply an absolute project directory.');
+}
+
+const validBoot = value => typeof value === 'string' && /^[a-f0-9-]{12,80}$/i.test(value);
+
+function transport(record, dir) {
+  if (Number.isInteger(record.port) && record.port > 0 && record.port <= 65535) return { host: '127.0.0.1', port: record.port };
+  if (!windows && /^pf-[a-f0-9]{12}\.sock$/.test(record.socket)) return { path: join(dir, record.socket) };
+  throw new Fault('UNAVAILABLE', 'Local daemon endpoint is invalid.');
+}
+
+export async function daemon() {
+  const dir = await stateDirectory();
+  if (!windows) process.umask(0o077);
+  const lock = new DatabaseSync(join(dir, 'daemon-lock.sqlite'));
+  try { lock.exec('BEGIN EXCLUSIVE'); }
+  catch { lock.close(); throw new Fault('BUSY', 'A daemon already owns this state directory.'); }
+  const store = new Store(dir);
+  const engine = new Engine(store, dir);
+  const secret = nonce();
+  const name = `pf-${nonce().slice(0, 12)}.sock`;
+  const socketPath = join(dir, name);
+  const loopback = windows || Buffer.byteLength(socketPath) >= 100;
+  const connections = new Set();
+  let closing = false;
+  let timer;
+  const server = createServer(socket => {
+    if (connections.size >= 96 || closing) { socket.destroy(); return; }
+    connections.add(socket);
+    socket.on('close', () => connections.delete(socket));
+    socket.on('error', () => socket.destroy());
+    socket.setTimeout(5000, () => socket.destroy());
+    let greeting;
+    let handled = false;
+    frames(socket, maxRequest, message => {
+      if (!greeting) {
+        if (message?.v !== protocol || !validHex(message.client)) { socket.destroy(); return; }
+        const server = nonce();
+        greeting = { client: message.client, server };
+        socket.write(line({ server, proof: mac(secret, 'server', protocol, greeting.client, server) }));
+        return;
+      }
+      if (handled || typeof message?.request !== 'string' || !same(message.proof,
+        mac(secret, 'client', protocol, greeting.client, greeting.server, message.request))) { socket.destroy(); return; }
+      handled = true;
+      socket.setTimeout(20000, () => socket.destroy());
+      void (async () => {
+        const { action, input } = JSON.parse(message.request);
+        validate(action, input);
+        if (action === 'daemon-status') return { pid: process.pid, protocol, busy: engine.current?.op.id };
+        if (action === 'daemon-stop') {
+          if (engine.current) throw new Fault('BUSY', 'Wait for the operation to finish before stopping the daemon.');
+          closing = true;
+          engine.closing = true;
+          while (engine.tracking) await delay(25);
+          return { stopped: true };
+        }
+        return engine.dispatch(action, input);
+      })().then(data => ({ ok: true, data }), error => ({ ok: false, error: problem(error) })).then(result => {
+        const response = JSON.stringify(result);
+        if (closing && result.ok && result.data?.stopped) {
+          socket.end(line({ response, proof: mac(secret, 'response', protocol, greeting.client, greeting.server, response) }), () => void shutdown());
+        } else socket.end(line({ response, proof: mac(secret, 'response', protocol, greeting.client, greeting.server, response) }));
+      }).catch(() => socket.destroy());
+    });
+  });
+
+  let stopped = false;
+  async function shutdown() {
+    if (stopped) return;
+    stopped = true;
+    closing = true;
+    clearInterval(timer);
+    for (const socket of connections) socket.destroy();
+    await new Promise(resolve => server.close(resolve));
+    await unlink(recordPath(dir)).catch(() => {});
+    if (!loopback) await unlink(socketPath).catch(() => {});
+    while (engine.current || engine.tracking) await delay(100);
+    store.close();
+    lock.exec('ROLLBACK');
+    lock.close();
+  }
+
+  const old = await readFile(recordPath(dir), 'utf8').then(JSON.parse).catch(() => null);
+  if (!windows && old && /^pf-[a-f0-9]{12}\.sock$/.test(old.socket)) await unlink(join(dir, old.socket)).catch(() => {});
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(loopback ? { host: '127.0.0.1', port: 0, exclusive: true } : { path: socketPath, exclusive: true }, resolve);
+  });
+  if (!loopback) await chmod(socketPath, 0o600);
+  const record = { v: protocol, secret, ...(loopback ? { port: server.address().port } : { socket: name }) };
+  const staged = join(dir, `endpoint-${nonce().slice(0, 12)}.json`);
+  await writeFile(staged, line(record), { flag: 'wx', mode: 0o600 });
+  await rename(staged, recordPath(dir));
+  timer = setInterval(() => { if (!closing) void engine.poll().catch(() => {}); }, 1750);
+  timer.unref();
+  process.once('SIGINT', () => void shutdown());
+  process.once('SIGTERM', () => void shutdown());
+}
+
+async function connect(dir, action, input) {
+  const record = await readFile(recordPath(dir), 'utf8').then(JSON.parse).catch(() => null);
+  if (!record || !validHex(record.secret)) throw new Fault('UNAVAILABLE', 'Local daemon is not running.');
+  if (record.v !== protocol) throw new Fault('UNSUPPORTED', 'Local daemon protocol differs. Stop the old daemon and restart it.');
+  const address = transport(record, dir);
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(address);
+    const client = nonce();
+    const unavailable = () => reject(new Fault('UNAVAILABLE', 'Local daemon did not complete the authenticated request.'));
+    let greeting;
+    socket.setTimeout(22000, () => socket.destroy());
+    socket.on('error', unavailable);
+    socket.on('close', unavailable);
+    socket.once('connect', () => socket.write(line({ v: protocol, client })));
+    frames(socket, maxResponse, message => {
+      if (!greeting) {
+        if (!validHex(message?.server) || !same(message.proof, mac(record.secret, 'server', protocol, client, message.server))) {
+          socket.destroy(); return;
+        }
+        greeting = message.server;
+        const request = JSON.stringify({ action, input });
+        if (Buffer.byteLength(request) > maxRequest / 2) { reject(new Fault('USAGE', 'Request is too large.')); socket.destroy(); return; }
+        socket.write(line({ request, proof: mac(record.secret, 'client', protocol, client, greeting, request) }));
+        return;
+      }
+      if (typeof message?.response !== 'string' || !same(message.proof, mac(record.secret, 'response', protocol, client, greeting, message.response))) {
+        socket.destroy(); return;
+      }
+      const result = JSON.parse(message.response);
+      if (result.ok) resolve(result.data);
+      else reject(new Fault(result.error.code, result.error.message, result.error.details));
+      socket.destroy();
+    });
+  });
+}
+
+let cachedDir;
+let starting;
+async function start(dir) {
+  let running = false;
+  for (let i = 0; i < 100; i++) {
+    if (!running && i % 10 === 0) {
+      const child = spawn(process.execPath, [fileURLToPath(new URL('../bin/projectfreeze.js', import.meta.url)), '_daemon'],
+        { detached: true, stdio: 'ignore', windowsHide: true, cwd: dir, env: process.env });
+      running = true;
+      child.once('error', () => { running = false; });
+      child.once('exit', () => { running = false; });
+      child.unref();
+    }
+    await delay(120);
+    try { return await connect(dir, 'daemon-status', {}); }
+    catch (error) { if (error.code !== 'UNAVAILABLE') throw error; }
+  }
+  throw new Fault('UNAVAILABLE', 'Daemon startup timed out. Run projectfreeze daemon foreground to inspect the startup error.');
+}
+
+export async function request(action, input = {}, autoStart = true) {
+  const dir = await (cachedDir ??= stateDirectory());
+  if (action === 'daemon-start') {
+    try { return await connect(dir, 'daemon-status', {}); }
+    catch (error) { if (error.code !== 'UNAVAILABLE') throw error; }
+    return start(dir);
+  }
+  if (!autoStart) return connect(dir, action, input);
+  if (['list', 'discover', 'inspect', 'listeners', 'history', 'operation'].includes(action)) {
+    try { return await connect(dir, action, input); }
+    catch (error) { if (error.code !== 'UNAVAILABLE') throw error; }
+  }
+  try { await connect(dir, 'daemon-status', {}); }
+  catch (error) {
+    if (error.code !== 'UNAVAILABLE') throw error;
+    await (starting ??= start(dir).finally(() => { starting = undefined; }));
+  }
+  return connect(dir, action, input);
+}
+
+export async function waitOperation(id, onProgress = () => {}, signal) {
+  let last;
+  while (!signal?.aborted) {
+    const op = await request('operation', { id });
+    const stamp = `${op.status}/${op.outcomes.length}/${op.pending}`;
+    if (stamp !== last) { onProgress(op); last = stamp; }
+    if (op.status !== 'running') return op;
+    if (signal?.aborted) return op;
+    await delay(200);
+  }
+  return { id, status: 'running', outcomes: [] };
+}

package/src/line-menu.js

@@ -0,0 +1,132 @@
+import { createInterface } from 'node:readline';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { problem } from './errors.js';
+import { request, waitOperation } from './ipc.js';
+import { identity } from './platform.js';
+
+const write = line => process.stdout.write(`${line}\n`);
+const clean = value => String(value).replace(/[\p{Cc}\p{Cf}]/gu, ' ');
+const endpoints = ports => [...new Set(ports.map(({ port }) => port))].join(', ') || 'none';
+const actions = { f: 'freeze', u: 'resume', z: 'sleep', w: 'wake' };
+
+export async function lineMenu() {
+  const input = createInterface({ input: process.stdin, crlfDelay: Infinity, terminal: false });
+  let nextLine;
+  let closed = false;
+  function receive(value) {
+    const resolveLine = nextLine;
+    nextLine = undefined;
+    resolveLine?.(value);
+  }
+  input.on('line', receive);
+  input.once('close', () => { closed = true; receive(undefined); });
+  const abort = new AbortController();
+  const numbers = new Map();
+  function detach() { abort.abort(); input.close(); }
+  process.once('SIGINT', detach);
+  async function ask(prompt) {
+    if (closed) return undefined;
+    return new Promise(resolveLine => {
+      nextLine = value => resolveLine(value?.trim());
+      write(prompt);
+    });
+  }
+  async function execute(action, payload, label) {
+    if ((await ask(`${label}\nApply ${action}? [y/N]`))?.toLowerCase() !== 'y') return;
+    const started = await request(action, payload);
+    write(`Operation ${started.id}`);
+    const result = await waitOperation(started.id, () => {}, abort.signal);
+    write(`${action} ${result.status}`);
+    for (const outcome of result.outcomes.filter(item => item.status === 'failed')) write(clean(outcome.message ?? outcome.code));
+  }
+  async function showListeners() {
+    const ports = await request('listeners');
+    write('TCP listeners (read-only)');
+    if (!ports.length) write('No TCP listeners observed.');
+    for (const port of ports) write(clean(`${port.address.includes(':') ? `[${port.address}]` : port.address}:${port.port}  PID ${port.pid}  ${port.name ?? port.image ?? 'unassigned'}  (${port.scope})`));
+  }
+  async function loadRecipe(path) {
+    const recipe = JSON.parse(await readFile(resolve(path), 'utf8'));
+    recipe.cwd = resolve(recipe.cwd ?? '.');
+    return recipe;
+  }
+  async function adopt(project) {
+    if (!project.candidates.length) { write('No current candidates to review.'); return; }
+    for (const row of project.candidates) write(clean(`Candidate PID ${row.pid}  TCP ${endpoints(row.ports)}  ${row.image ?? ''}`));
+    const value = await ask('Approved PIDs, comma-separated (Enter cancels)');
+    if (!value) return;
+    const pids = new Set(value.split(',').map(value => Number(value.trim())));
+    const approved = project.candidates.filter(row => pids.has(row.pid));
+    if (approved.length !== pids.size) { write('Select only the listed candidate PIDs.'); return; }
+    const path = await ask('Optional JSON restart recipe (Enter skips)');
+    await execute('adopt', { cwd: project.cwd, confirm: true, members: approved.map(identity), recipe: path ? await loadRecipe(path) : undefined },
+      `${clean(project.name)}  PID ${approved.map(row => row.pid).join(', ')}`);
+  }
+  async function inspect(project) {
+    while (!abort.signal.aborted) {
+      const live = await request('inspect', { id: project.id });
+      write(clean(`${live.name} [${live.state}]  TCP ${endpoints(live.ports)}  ${live.id}`));
+      for (const row of live.processes) write(clean(`PID ${row.pid}  TCP ${endpoints(row.ports)}  ${row.image ?? ''}`));
+      const value = await ask('f Freeze   u Resume   z Sleep   w Wake   a Review candidates   r Refresh   b Back   q Quit');
+      if (value === 'q' || value === undefined) { detach(); return; }
+      if (value === 'b' || value === '') return;
+      if (value === 'a' || (value === 'f' && live.state === 'discovered')) { await adopt(live); continue; }
+      if (!Object.hasOwn(actions, value)) continue;
+      await execute(actions[value], { ids: [project.id] }, `${clean(live.name)}  ${live.processCount} process(es)  TCP ${endpoints(live.ports)}`);
+    }
+  }
+  function renderProjects(projects) {
+    const lines = projects.map(project => {
+      if (!numbers.has(project.id)) numbers.set(project.id, numbers.size + 1);
+      return clean(`${numbers.get(project.id)}. ${project.name} [${project.state}]  TCP ${endpoints(project.ports)}  ${project.processCount} process(es)`);
+    });
+    return lines.join('\n') || 'No projects observed. Use p to view TCP listeners.';
+  }
+  try {
+    while (!abort.signal.aborted) {
+      try {
+        const scan = () => request('list').then(rows => rows.sort((a, b) => b.processCount - a.processCount || a.name.localeCompare(b.name)));
+        const prompt = 'Project number   p Ports   l Launch recipe   Enter Refresh   q Quit';
+        let projects = await scan();
+        let rendered = renderProjects(projects);
+        write(`\nProjectFreeze\n${rendered}`);
+        let waiting = true;
+        let updating = false;
+        const timer = setInterval(async () => {
+          if (updating) return;
+          updating = true;
+          try {
+            const snapshot = await scan();
+            if (!waiting || !nextLine) return;
+            projects = snapshot;
+            const current = renderProjects(projects);
+            if (rendered !== current) {
+              rendered = current;
+              write(`\nProjectFreeze\n${rendered}\n${prompt}`);
+            }
+          } catch { /* The previous snapshot remains visible until the next scan. */ }
+          finally { updating = false; }
+        }, 2500);
+        let value;
+        try { value = await ask(prompt); }
+        finally { waiting = false; clearInterval(timer); }
+        if (value === 'q' || value === undefined) return;
+        if (value === 'p') await showListeners();
+        else if (value === 'l') {
+          const path = await ask('Path to JSON launch recipe (Enter cancels)');
+          if (path) {
+            const recipe = await loadRecipe(path);
+            await execute('run', { recipe }, clean(`${recipe.cwd}\nExecutable ${recipe.argv?.[0] ?? '(missing)'}`));
+          }
+        } else if (/^[1-9]\d*$/.test(value)) {
+          const project = projects.find(row => numbers.get(row.id) === Number(value));
+          if (project) await inspect(project);
+        }
+      } catch (error) {
+        write(clean(problem(error).message));
+        if ((await ask('Enter Retry   q Quit')) !== '') return;
+      }
+    }
+  } finally { process.off('SIGINT', detach); input.close(); }
+}