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

package/src/mcp.js

@@ -0,0 +1,113 @@
+import { createInterface } from 'node:readline';
+import manifest from '../package.json' with { type: 'json' };
+import { problem } from './errors.js';
+import { request, waitOperation } from './ipc.js';
+
+const id = { type: 'string' };
+const ids = { type: 'array', items: id, minItems: 1, maxItems: 32 };
+const identity = { type: 'object', properties: { pid: { type: 'integer', minimum: 2 }, birth: id, boot: id }, required: ['pid', 'birth', 'boot'] };
+const recipe = { type: 'object', properties: {
+  argv: { type: 'array', items: id, minItems: 1 }, cwd: id, instance: id, env: { type: 'array', items: id }, dependencies: ids,
+  stop: { type: 'array', items: id }, timeout: { type: 'integer', minimum: 100, maximum: 120000 },
+  ready: { type: 'object', properties: { address: { enum: ['127.0.0.1', '::1'] }, port: { type: 'integer', minimum: 1, maximum: 65535 } }, required: ['address', 'port'] },
+  restart: { enum: ['never', 'on-failure'] }, cgroup: id,
+  containers: { type: 'array', items: { type: 'object', properties: { project: id, service: id, shared: { type: 'boolean' } }, required: ['project', 'service', 'shared'] } },
+  systemd: { type: 'array', items: { type: 'object', properties: { unit: id, shared: { type: 'boolean' } }, required: ['unit', 'shared'] } },
+  supervisors: { type: 'array', maxItems: 12, items: { type: 'object', properties: {
+    kind: { enum: ['launchd', 'scm', 'task'] }, name: id, shared: { type: 'boolean' }, plist: id
+  }, required: ['kind', 'name', 'shared'], additionalProperties: false } }
+}, required: ['argv', 'cwd'], additionalProperties: false };
+const tool = (name, description, properties = {}, required = [], mutation = false) => ({
+  name, description, inputSchema: { type: 'object', properties, required, additionalProperties: false },
+  annotations: { readOnlyHint: !mutation, destructiveHint: mutation, openWorldHint: false }, mutation
+});
+const tools = [
+  tool('list', 'List projects and live resources in local authorized scope.'),
+  tool('discover', 'Find candidate identities and evidence for explicit adoption.'),
+  tool('listeners', 'List TCP listeners of locally observable processes, including unassigned listeners.'),
+  tool('ports', 'List local TCP listeners and bound UDP sockets from OS tables.'),
+  tool('services', 'List running services visible to the local service managers.'),
+  tool('inspect', 'Inspect resource identities, candidates, and recent operations.', { id }, ['id']),
+  tool('history', 'Read recent durable operations.'),
+  tool('operation', 'Read one operation and its per-resource outcomes.', { id }, ['id']),
+  tool('cancel', 'Request cancellation at the next resource boundary.', { id }, ['id'], true),
+  tool('adopt', 'Associate reviewed identities with a project. Obtain user approval for the exact set.',
+    { id, cwd: id, members: { type: 'array', items: identity, minItems: 1 }, exclude: { type: 'array', items: identity }, confirm: { const: true }, recipe }, ['cwd', 'members', 'confirm'], true),
+  tool('run', 'Launch a reviewed local executable with literal arguments.', { recipe }, ['recipe'], true),
+  tool('freeze', 'Suspend owned resources and preserve memory and bound sockets.', { ids }, ['ids'], true),
+  tool('resume', 'Release suspensions recorded by ProjectFreeze.', { ids }, ['ids'], true),
+  tool('sleep', 'Gracefully stop owned resources. Force requires specific user approval.', { ids, force: { type: 'boolean' } }, ['ids'], true),
+  tool('wake', 'Restart from durable launch recipes.', { ids }, ['ids'], true),
+  tool('checkpoint', 'Capture process state using a supported local backend.', { ids, backend: { enum: ['criu', 'docker'] } }, ['ids'], true),
+  tool('restore', 'Restore a verified local checkpoint.', { ids, checkpoint: id }, ['ids', 'checkpoint'], true),
+  tool('reconcile', 'Review durable ownership against the current host state.', { ids }, [], true)
+];
+const byName = new Map(tools.map(entry => [entry.name, entry]));
+const versions = new Set(['2024-11-05', '2025-03-26', '2025-06-18', '2025-11-25']);
+const object = value => value && typeof value === 'object' && !Array.isArray(value);
+
+export async function serve() {
+  const lines = createInterface({ input: process.stdin, crlfDelay: Infinity, terminal: false });
+  const active = new Map();
+  let initialized = false;
+  let negotiated = false;
+  const send = msg => process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', ...msg })}\n`);
+  const rpcError = (id, code, message) => send({ id, error: { code, message } });
+  lines.on('close', () => { for (const entry of active.values()) entry.abort.abort(); });
+  lines.on('line', raw => {
+    let message;
+    if (Buffer.byteLength(raw) > 128 * 1024) { rpcError(null, -32600, 'Request exceeds size limit.'); return; }
+    try { message = JSON.parse(raw); } catch { rpcError(null, -32700, 'Invalid JSON.'); return; }
+    if (!object(message) || message.jsonrpc !== '2.0' || typeof message.method !== 'string') { rpcError(null, -32600, 'Invalid request.'); return; }
+    const { id, method, params } = message;
+    if (id === undefined) {
+      if (method === 'notifications/initialized' && negotiated) initialized = true;
+      if (method === 'notifications/cancelled') {
+        const entry = active.get(params?.requestId);
+        entry?.abort.abort();
+        if (entry?.operation) void request('cancel', { id: entry.operation }).catch(() => {});
+      }
+      return;
+    }
+    if (!['number', 'string'].includes(typeof id)) { rpcError(null, -32600, 'Invalid request ID.'); return; }
+    const result = data => send({ id, result: data });
+    if (method === 'initialize') {
+      if (!params || typeof params.protocolVersion !== 'string' || negotiated) { rpcError(id, -32602, 'Invalid initialize parameters.'); return; }
+      negotiated = true;
+      result({ protocolVersion: versions.has(params.protocolVersion) ? params.protocolVersion : '2025-11-25',
+        serverInfo: { name: 'projectfreeze', version: manifest.version }, capabilities: { tools: {} },
+        instructions: 'Use discover and inspect before adopting or controlling a project. Obtain specific approval for ambiguous adoption or force termination.' });
+      return;
+    }
+    if (method === 'ping') { result({}); return; }
+    if (!initialized) { rpcError(id, -32002, 'Server has not initialized.'); return; }
+    if (method === 'tools/list') { result({ tools: tools.map(({ mutation, ...entry }) => entry) }); return; }
+    if (method !== 'tools/call') { rpcError(id, -32601, 'Unknown method.'); return; }
+    const entry = byName.get(params?.name);
+    const input = params?.arguments ?? {};
+    if (!entry || !object(input) || Object.keys(input).some(key => !Object.hasOwn(entry.inputSchema.properties, key)) ||
+        entry.inputSchema.required.some(key => !Object.hasOwn(input, key))) { rpcError(id, -32602, 'Invalid tool or arguments.'); return; }
+    if (active.has(id) || active.size >= 32) { rpcError(id, -32000, 'Too many requests or duplicate request ID.'); return; }
+    const context = { abort: new AbortController(), operation: undefined };
+    active.set(id, context);
+    void (async () => {
+      let data = await request(entry.name, input);
+      if (entry.mutation && entry.name !== 'cancel') {
+        context.operation = data.id;
+        if (context.abort.signal.aborted) await request('cancel', { id: data.id }).catch(() => {});
+        const token = params?._meta?.progressToken;
+        let progress = 0;
+        data = await waitOperation(data.id, op => {
+          if (!context.abort.signal.aborted && ['string', 'number'].includes(typeof token)) {
+            send({ method: 'notifications/progress', params: { progressToken: token, progress: ++progress, message: op.pending ?? op.status } });
+          }
+        }, context.abort.signal);
+      }
+      const payload = { schemaVersion: 1, data };
+      if (!context.abort.signal.aborted) result({ content: [{ type: 'text', text: JSON.stringify(payload) }], structuredContent: payload,
+        ...(entry.mutation && !['complete', undefined].includes(data.status) ? { isError: true } : {}) });
+    })().catch(error => {
+      if (!context.abort.signal.aborted) result({ isError: true, content: [{ type: 'text', text: JSON.stringify({ schemaVersion: 1, error: problem(error) }) }] });
+    }).finally(() => active.delete(id));
+  });
+}

package/src/platform.js

@@ -0,0 +1,320 @@
+import { execFile, spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { access, readFile, readdir, readlink, realpath, stat, writeFile } from 'node:fs/promises';
+import { constants, statSync } from 'node:fs';
+import { basename, delimiter, dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { createInterface } from 'node:readline';
+import { Fault } from './errors.js';
+
+const exec = promisify(execFile);
+export const windows = process.platform === 'win32';
+export const linux = process.platform === 'linux';
+const name = `projectfreeze-${process.platform}-${process.arch}${windows ? '.exe' : ''}`;
+export const helper = fileURLToPath(new URL(`../helpers/${name}`, import.meta.url));
+const cliPath = fileURLToPath(new URL('../bin/projectfreeze.js', import.meta.url));
+const samples = new Map();
+const knownStates = new Set(['R', 'S', 'D', 'T', 't', 'I', 'M', '?', 'P', 'Z', 'X']);
+const ignorePids = new Set([process.pid]);
+
+export function identity(p) { return { pid: p.pid, birth: p.birth, boot: p.boot }; }
+export function key(p) { return `${p.boot}/${p.pid}/${p.birth}`; }
+export function matches(a, b) { return a && b && key(a) === key(b); }
+export function ignored(pid) { return ignorePids.has(pid); }
+
+export async function command(file, args, options = {}) {
+  try {
+    return (await exec(file, args, { timeout: 12000, maxBuffer: 16 * 1024 * 1024, windowsHide: true, ...options })).stdout;
+  } catch (error) {
+    const code = ({ ENOENT: 'UNAVAILABLE', EACCES: 'DENIED', 2: 'USAGE', 3: 'NOT_FOUND', 4: 'DENIED', 5: 'UNSUPPORTED', 6: 'BUSY' })[error.code] ?? 'PARTIAL';
+    throw new Fault(code, `Execution of ${basename(file)} failed.`, { exit: error.code });
+  }
+}
+
+let checked;
+export function checkHelper() {
+  return checked ??= Promise.all([readFile(helper), readFile(`${helper}.sha256`, 'utf8')]).then(([bytes, manifest]) => {
+    if (createHash('sha256').update(bytes).digest('hex') !== manifest.split(' ')[0]) {
+      throw new Fault('DENIED', 'Native helper integrity check failed. Reinstall the package.');
+    }
+  }, () => { throw new Fault('UNAVAILABLE', `Missing native helper for ${process.platform}/${process.arch}. Install a release tarball or run npm run build:native.`); });
+}
+
+let boot;
+export function bootId() {
+  return boot ??= (linux ? readFile('/proc/sys/kernel/random/boot_id', 'utf8') : windows
+    ? command(helper, ['boot'])
+    : command('/usr/sbin/sysctl', ['-n', 'kern.bootsessionuuid'])).then(value => {
+    const id = value.trim();
+    if (!/^[a-f0-9-]{12,80}$/i.test(id)) throw new Fault('UNAVAILABLE', 'A stable boot identity could not be verified.');
+    return id;
+  });
+}
+
+let linuxUnits;
+function units() {
+  return linuxUnits ??= Promise.all([command('/usr/bin/getconf', ['CLK_TCK']), command('/usr/bin/getconf', ['PAGESIZE'])])
+    .then(values => values.map(Number));
+}
+
+async function linuxProcess(pid, boot, clock, pageSize, full) {
+  const base = `/proc/${pid}`;
+  try {
+    if ((await stat(base)).uid !== process.getuid()) return null;
+    const raw = await readFile(`${base}/stat`, 'utf8');
+    const parts = raw.slice(raw.lastIndexOf(')') + 2).trim().split(/\s+/);
+    if (!knownStates.has(parts[0]) || parts[0] === 'Z' || parts[0] === 'X') return null;
+    const row = { pid, boot, birth: parts[19], parent: +parts[1], group: +parts[2], session: +parts[3], state: parts[0],
+      cpuTime: (+parts[11] + +parts[12]) * 1e9 / clock, rss: +parts[21] * pageSize, ports: [] };
+    if (full) {
+      const [cwd, image, args] = await Promise.all([
+        readlink(`${base}/cwd`).catch(() => undefined), readlink(`${base}/exe`).catch(() => undefined),
+        readFile(`${base}/cmdline`, 'utf8').catch(() => '')
+      ]);
+      row.cwd = cwd;
+      row.image = image;
+      row.projectHint = argumentHint(args.split('\0'), cwd);
+      const current = await readFile(`${base}/stat`, 'utf8');
+      if (current.slice(current.lastIndexOf(')') + 2).split(' ')[19] !== row.birth) return null;
+    }
+    return row;
+  } catch { return null; }
+}
+
+function argumentHint(args, cwd) {
+  const path = args.slice(1, 8).find(value => /\.(?:[cm]?js|tsx?|py|rb|jar|php)$/i.test(value) &&
+    !value.startsWith('-') && (isAbsolute(value) || cwd));
+  return path ? resolve(cwd ?? '.', path) : undefined;
+}
+
+function parseAddress(hex) {
+  const bytes = Buffer.from(hex, 'hex');
+  if (bytes.length === 4) return [...bytes.reverse()].join('.');
+  if (bytes.length !== 16) return undefined;
+  for (let i = 0; i < 16; i += 4) bytes.subarray(i, i + 4).reverse();
+  return Array.from({ length: 8 }, (_, i) => bytes.readUInt16BE(i * 2).toString(16)).join(':');
+}
+
+async function procSockets(directory, protocols) {
+  const tables = await Promise.all(protocols.map(async table => {
+    const protocol = table.slice(0, 3);
+    const data = await readFile(`${directory}/${table}`, 'utf8').catch(error => {
+      if (error.code !== 'ENOENT' || table === 'tcp') throw error;
+      return '';
+    });
+    return data.trimEnd().split('\n').slice(1).flatMap(line => {
+      const fields = line.trim().split(/\s+/);
+      if (!fields[1] || (protocol === 'tcp' && fields[3] !== '0A')) return [];
+      const [host, hexPort] = fields[1].split(':');
+      const address = parseAddress(host);
+      const port = Number.parseInt(hexPort, 16);
+      return address && port ? [{ protocol, address, port, socket: `socket:[${fields[9]}]` }] : [];
+    });
+  }));
+  return tables.flat();
+}
+
+async function socketLinks(pid) {
+  const path = `/proc/${pid}/fd`;
+  const descriptors = await readdir(path).catch(() => []);
+  return new Set(await Promise.all(descriptors.map(fd => readlink(`${path}/${fd}`).catch(() => ''))));
+}
+
+async function linuxPorts(rows) {
+  const namespaces = new Map();
+  await Promise.all(rows.map(async row => {
+    const ns = await readlink(`/proc/${row.pid}/ns/net`).catch(() => undefined);
+    if (ns) namespaces.set(ns, [...(namespaces.get(ns) ?? []), row]);
+  }));
+  for (const group of namespaces.values()) {
+    const entries = await procSockets(`/proc/${group[0].pid}/net`, ['tcp', 'tcp6']).catch(() => []);
+    const sockets = new Map(entries.map(({ address, port, socket }) => [socket, { address, port }]));
+    for (const row of group) {
+      row.ports = [...await socketLinks(row.pid)].map(link => sockets.get(link)).filter(Boolean);
+    }
+  }
+}
+
+async function windowsSockets(protocol) {
+  const net = await command(helper, [protocol === 'tcp' ? 'listeners' : 'udp-sockets']);
+  return net.trimEnd().split(/\r?\n/).filter(Boolean).map(line => {
+    const [pid, address, port] = line.split('\t');
+    return { protocol, address, port: +port, pid: +pid || null };
+  });
+}
+
+export async function localPorts(rows) {
+  if (windows) return (await Promise.all(['tcp', 'udp'].map(windowsSockets))).flat();
+  if (linux) {
+    const entries = await procSockets('/proc/net', ['tcp', 'tcp6', 'udp', 'udp6']);
+    const namespace = await readlink('/proc/self/ns/net');
+    const bySocket = new Map();
+    for (const { pid } of rows) {
+      if (await readlink(`/proc/${pid}/ns/net`).catch(() => '') !== namespace) continue;
+      for (const socket of await socketLinks(pid)) {
+        if (socket.startsWith('socket:[')) bySocket.set(socket, [...(bySocket.get(socket) ?? []), pid]);
+      }
+    }
+    return entries.flatMap(({ socket, ...endpoint }) => (bySocket.get(socket) ?? [null]).map(pid => ({ ...endpoint, pid })));
+  }
+  const output = (await Promise.all(['inet', 'inet6'].map(family => command('/usr/sbin/netstat', ['-anW', '-f', family])))).join('\n');
+  return output.split('\n').flatMap(line => {
+    const [kind, , , endpoint, , state] = line.trim().split(/\s+/);
+    if (!/^(?:tcp|udp)[46]+$/.test(kind) || (kind.startsWith('tcp') && state !== 'LISTEN')) return [];
+    const parsed = endpoint?.match(/^(.+)\.(\d+)$/);
+    if (!parsed) return [];
+    const [, address, port] = parsed;
+    const protocol = kind.slice(0, 3);
+    const owners = protocol === 'tcp' ? rows.filter(row => row.ports.some(value => value.port === +port && value.address === address)) : [];
+    return (owners.length ? owners.map(row => row.pid) : [null]).map(pid => ({ protocol, address, port: +port, pid }));
+  });
+}
+
+function decode(text, encoding) { return text ? Buffer.from(text, encoding).toString('utf8') : undefined; }
+
+async function nonLinuxRows(boot, full) {
+  const result = await command(helper, [windows && full ? 'discover' : 'scan']);
+  const rows = result.split('\n').filter(Boolean).map(line => {
+    const fields = line.replace(/\r$/, '').split('\t');
+    if (windows) {
+      const [pid, parent, birth, state, cpuTime, rss, image, hint] = fields;
+      return { pid: +pid, parent: +parent, group: 0, session: 0, boot, birth, state, cpuTime: +cpuTime,
+        rss: +rss < 0 ? undefined : +rss, image: decode(image, 'base64'), projectHint: decode(hint, 'base64'), ports: [] };
+    }
+    const [pid, parent, group, session, birth, state, cpuTime, rss, image, cwd] = fields;
+    return { pid: +pid, parent: +parent, group: +group, session: +session, boot, birth, state, cpuTime: +cpuTime, rss: +rss,
+      image: decode(image, 'hex'), cwd: decode(cwd, 'hex'), ports: [] };
+  });
+  if (!full) return rows;
+  const byPid = new Map(rows.map(row => [row.pid, row]));
+  if (windows) {
+    for (const { pid, address, port } of await windowsSockets('tcp')) byPid.get(pid)?.ports.push({ address, port });
+  } else {
+    const sockets = await command('/usr/sbin/lsof', ['-nP', '-iTCP', '-sTCP:LISTEN', '-Fpn']).catch(() => '');
+    let pid = 0;
+    for (const line of sockets.split('\n')) {
+      if (line.startsWith('p')) pid = Number(line.slice(1));
+      const match = line.match(/^n(.+):(\d+)$/);
+      if (match) byPid.get(pid)?.ports.push({ address: match[1].replace(/^\[|\]$/g, ''), port: +match[2] });
+    }
+  }
+  return rows;
+}
+
+export async function scan(full = true, stagedPid) {
+  await checkHelper();
+  const boot = await bootId();
+  let rows;
+  if (linux) {
+    const [clock, page] = await units();
+    const ids = (await readdir('/proc')).filter(name => /^\d+$/.test(name)).map(Number);
+    rows = [];
+    for (let i = 0; i < ids.length; i += 48) {
+      rows.push(...(await Promise.all(ids.slice(i, i + 48).map(pid => linuxProcess(pid, boot, clock, page, full)))).filter(Boolean));
+    }
+    if (full) await linuxPorts(rows);
+  } else rows = await nonLinuxRows(boot, full);
+  rows = rows.filter(row => row.pid > 1 && !ignored(row.pid) && (row.pid === stagedPid ||
+    (row.image !== helper && !/^launcher-[a-f0-9]{64}\.exe$/i.test(basename(row.image ?? '')))) && row.projectHint !== cliPath);
+  if (full) {
+    const time = performance.now();
+    const current = new Set();
+    for (const row of rows) {
+      const id = key(row);
+      current.add(id);
+      const previous = samples.get(id);
+      if (previous && time > previous.time && row.cpuTime >= previous.cpu) {
+        row.cpuPercent = (row.cpuTime - previous.cpu) / ((time - previous.time) * 1e4);
+      }
+      samples.set(id, { time, cpu: row.cpuTime });
+    }
+    for (const id of samples.keys()) if (!current.has(id)) samples.delete(id);
+  }
+  return rows;
+}
+
+export async function control(action, target) {
+  if (target.boot !== await bootId() || ignored(target.pid)) throw new Fault('NOT_FOUND', 'The process identity is stale or protected.');
+  try { await command(helper, [action, String(target.pid), target.birth]); }
+  catch (error) { if (error.details?.exit === 10) return false; throw error; }
+  return true;
+}
+
+export async function executable(value, cwd, env) {
+  const path = env.PATH ?? env.Path ?? '';
+  const explicit = isAbsolute(value) || value.includes('/') || value.includes('\\');
+  const candidates = explicit ? [resolve(cwd, value)] : path.split(delimiter).filter(isAbsolute).map(dir => join(dir, value));
+  for (const candidate of candidates) {
+    for (const file of windows && !/\.(exe|com)$/i.test(candidate) ? [`${candidate}.exe`, `${candidate}.com`] : [candidate]) {
+      try {
+        const absolute = await realpath(file);
+        await access(absolute, constants.X_OK);
+        if (statSync(absolute).isFile()) return absolute;
+      } catch { /* A later PATH entry may be executable. */ }
+    }
+  }
+  throw new Fault('UNAVAILABLE', 'The recipe executable could not be resolved. Use an absolute executable or add it to PATH.');
+}
+
+export async function stageLaunch(argv, cwd, env, job, cgroup, statusFile) {
+  await checkHelper();
+  const file = await executable(argv[0], cwd, env);
+  const marker = windows ? job : cgroup ? join(cgroup, 'cgroup.procs') : '-';
+  let launcher = helper;
+  if (windows) {
+    const bytes = await readFile(helper);
+    const hash = createHash('sha256').update(bytes).digest('hex');
+    launcher = join(dirname(statusFile), `launcher-${hash}.exe`);
+    await writeFile(launcher, bytes, { flag: 'wx' }).catch(async error => {
+      if (error.code !== 'EEXIST' || createHash('sha256').update(await readFile(launcher)).digest('hex') !== hash) throw error;
+    });
+  }
+  const child = spawn(launcher, ['launch', marker, statusFile, file, ...argv.slice(1)], { cwd, env, windowsHide: true, detached: true,
+    stdio: ['pipe', 'pipe', 'ignore'] });
+  child.once('exit', () => { if (child.pid) ignorePids.delete(child.pid); });
+  child.stdin.on('error', () => {});
+  if (child.pid) ignorePids.add(child.pid);
+  const lines = createInterface({ input: child.stdout, terminal: false });
+  let timer;
+  try {
+    const ready = await new Promise((resolve, reject) => {
+      timer = setTimeout(() => reject(new Fault('UNAVAILABLE', 'Native launch handshake timed out.')), 6000);
+      child.once('error', () => reject(new Fault('UNAVAILABLE', 'Native launcher could not start.')));
+      lines.once('line', resolve);
+      lines.once('close', () => reject(new Fault('DENIED', 'Native launcher could not prepare the workload.')));
+    });
+    const pid = Number(ready.split('\t')[0]);
+    const root = (await scan(false, pid)).find(row => row.pid === pid);
+    if (!root || (windows && root.birth !== ready.split('\t')[1]) || (!windows && root.group !== pid)) {
+      throw new Fault('PARTIAL', 'Launch identity could not be verified.');
+    }
+    return { root: identity(root), release() { child.stdin.end('G'); child.unref(); }, abort() { child.stdin.end(); } };
+  } catch (error) {
+    child.stdin.end();
+    throw error;
+  } finally { clearTimeout(timer); lines.close(); child.stdout.destroy(); }
+}
+
+export async function containerPids(project) {
+  if (windows && project.job) {
+    return new Set((await command(helper, ['job-scan', project.job])).split('\n').filter(Boolean).map(line => {
+      const [pid, , birth] = line.split('\t');
+      return key({ pid: Number(pid), birth, boot: project.root.boot });
+    }));
+  }
+  if (linux && project.cgroup) {
+    const walk = async dir => {
+      const rows = await readFile(join(dir, 'cgroup.procs'), 'utf8');
+      const directories = (await readdir(dir, { withFileTypes: true })).filter(item => item.isDirectory());
+      return [...rows.trim().split(/\s+/).map(Number), ...(await Promise.all(directories.map(item => walk(join(dir, item.name))))).flat()];
+    };
+    return new Set(await walk(project.cgroup));
+  }
+  return null;
+}
+
+export function manifestStart(p) {
+  if (p.projectHint) return dirname(p.projectHint);
+  return p.cwd;
+}

package/src/recipe.js

@@ -0,0 +1,69 @@
+import { readFile, realpath, mkdir, statfs } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import { Fault } from './errors.js';
+import { directory } from './discovery.js';
+import { linux } from './platform.js';
+import { validSystemd } from './systemd.js';
+import { supervisorPolicies } from './supervisors.js';
+
+const envName = /^[A-Za-z_][A-Za-z_0-9]*$/;
+const projectName = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/;
+const platformEnv = new Set(['PATH', 'HOME', 'USER', 'LOGNAME', 'USERPROFILE', 'SYSTEMROOT', 'WINDIR', 'SYSTEMDRIVE',
+  'TEMP', 'TMP', 'TMPDIR', 'LANG', 'LC_ALL', 'APPDATA', 'LOCALAPPDATA', 'COMSPEC', 'PATHEXT']);
+const argv = (values) => Array.isArray(values) && values.length > 0 && values.length <= 128 &&
+  values.every(s => typeof s === 'string' && !s.includes('\0') && s.length <= 16384) && Boolean(values[0]);
+
+export async function recipe(input) {
+  if (!input || !argv(input.argv)) throw new Fault('USAGE', 'Supply an executable and literal arguments.');
+  if (input.stop !== undefined && !argv(input.stop)) throw new Fault('USAGE', 'The shutdown command must be an argument array.');
+  const cwd = await directory(input.cwd ?? '.');
+  const { instance, env = [], dependencies = [], timeout = 10000, restart = 'never', ready, stop, cgroup, containers = [], systemd = [] } = input;
+  if (instance !== undefined && (typeof instance !== 'string' || !projectName.test(instance))) {
+    throw new Fault('USAGE', 'Use a workload instance name of up to 128 letters, digits, underscores, or hyphens, starting with a letter or digit.');
+  }
+  if (!Array.isArray(env) || !env.every(s => typeof s === 'string' && envName.test(s) && !s.startsWith('PROJECTFREEZE_'))) {
+    throw new Fault('USAGE', 'Environment references must be variable names.');
+  }
+  if (!Array.isArray(dependencies) || !dependencies.every(s => typeof s === 'string' && /^p-[a-f0-9]{16}$/.test(s))) {
+    throw new Fault('USAGE', 'Dependencies must be registered project IDs.');
+  }
+  if (!Array.isArray(containers) || containers.length > 24 || !containers.every(c => c && typeof c.project === 'string' && typeof c.service === 'string' &&
+      projectName.test(c.project) && projectName.test(c.service) && typeof c.shared === 'boolean') ||
+      new Set(containers.map(c => `${c.project}/${c.service}`)).size !== containers.length) {
+    throw new Fault('USAGE', 'Containers require a Compose project, service, and explicit shared policy.');
+  }
+  if (!validSystemd(systemd) || (!linux && systemd.length)) throw new Fault('USAGE', 'Configure exact Linux user systemd unit names and explicit shared policies.');
+  if (!Number.isInteger(timeout) || timeout < 100 || timeout > 120000 || !['never', 'on-failure'].includes(restart)) {
+    throw new Fault('USAGE', 'Choose a shutdown timeout from 100 to 120000 ms and restart never or on-failure.');
+  }
+  if (ready && (!['127.0.0.1', '::1'].includes(ready.address) || !Number.isInteger(ready.port) || ready.port < 1 || ready.port > 65535)) {
+    throw new Fault('USAGE', 'Readiness requires a loopback TCP address and port.');
+  }
+  if (cgroup !== undefined && (!linux || typeof cgroup !== 'string' || !isAbsolute(cgroup))) {
+    throw new Fault('USAGE', 'A cgroup requires an absolute, delegated cgroup v2 directory on Linux.');
+  }
+  return { argv: input.argv, cwd, instance, env: [...new Set(env)], dependencies: [...new Set(dependencies)], timeout, restart, ready, stop, cgroup,
+    containers, systemd, supervisors: supervisorPolicies(input.supervisors ?? []) };
+}
+
+export function launchEnv(recipe, available) {
+  const entries = Object.entries(available).filter(([name]) => platformEnv.has(name.toUpperCase()));
+  const env = Object.fromEntries(entries);
+  for (const name of recipe.env) {
+    if (!Object.hasOwn(available, name)) throw new Fault('UNAVAILABLE', `Required environment reference is missing: ${name}.`);
+    env[name] = available[name];
+  }
+  return env;
+}
+
+export async function prepareCgroup(parent, id) {
+  if (!parent) return undefined;
+  try {
+    const canonical = await realpath(parent);
+    if ((await statfs(canonical)).type !== 0x63677270) throw new Error();
+    const child = join(canonical, id);
+    await mkdir(child);
+    if ((await readFile(join(child, 'cgroup.procs'), 'utf8')).trim()) throw new Error();
+    return child;
+  } catch { throw new Fault('DENIED', 'Could not create an empty dedicated cgroup in the delegated cgroup v2 directory.'); }
+}

package/src/store.js

@@ -0,0 +1,61 @@
+import { DatabaseSync } from 'node:sqlite';
+import { join } from 'node:path';
+import { Fault } from './errors.js';
+
+export class Store {
+  constructor(directory) {
+    this.db = new DatabaseSync(join(directory, 'state.sqlite'));
+    this.db.exec('PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; PRAGMA trusted_schema=OFF; PRAGMA busy_timeout=3000;');
+    const version = this.db.prepare('PRAGMA user_version').get().user_version;
+    if (version > 1) throw new Fault('UNSUPPORTED', 'This daemon is older than the state database. Upgrade it first.');
+    this.db.exec(`BEGIN IMMEDIATE;
+      CREATE TABLE IF NOT EXISTS projects (id TEXT PRIMARY KEY, body TEXT NOT NULL) STRICT;
+      CREATE TABLE IF NOT EXISTS operations (id TEXT PRIMARY KEY, started TEXT NOT NULL, body TEXT NOT NULL) STRICT;
+      PRAGMA user_version=1;
+      COMMIT;`);
+  }
+
+  projects() { return this.db.prepare('SELECT body FROM projects ORDER BY id').all().map(row => JSON.parse(row.body)); }
+  project(id) {
+    const row = this.db.prepare('SELECT body FROM projects WHERE id = ?').get(id);
+    if (!row) throw new Fault('NOT_FOUND', 'Unknown project ID. Run list or discover first.');
+    return JSON.parse(row.body);
+  }
+  save(project) {
+    this.db.prepare('INSERT OR REPLACE INTO projects VALUES (?, ?)').run(project.id, JSON.stringify(project));
+  }
+  journal(operation) {
+    this.db.prepare('INSERT OR REPLACE INTO operations VALUES (?, ?, ?)')
+      .run(operation.id, operation.started, JSON.stringify(operation));
+  }
+  history(limit = 100) {
+    return this.db.prepare('SELECT body FROM operations ORDER BY started DESC LIMIT ?')
+      .all(limit).map(row => JSON.parse(row.body));
+  }
+  operation(id) {
+    const row = this.db.prepare('SELECT body FROM operations WHERE id = ?').get(id);
+    if (!row) throw new Fault('NOT_FOUND', 'Unknown operation ID.');
+    return JSON.parse(row.body);
+  }
+  recover() {
+    const rows = this.db.prepare("SELECT body FROM operations WHERE json_extract(body, '$.status') = 'running'").all();
+    for (const row of rows) {
+      const op = JSON.parse(row.body);
+      op.status = 'interrupted';
+      op.ended = new Date().toISOString();
+      this.journal(op);
+    }
+  }
+  commit(project, operation) {
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      if (project) this.save(project);
+      this.journal(operation);
+      this.db.exec('COMMIT');
+    } catch (error) {
+      this.db.exec('ROLLBACK');
+      throw error;
+    }
+  }
+  close() { this.db.close(); }
+}