@codedology/code-forge 0.1.0

package/src/state/run.mjs

@@ -0,0 +1,266 @@
+/**
+ * The run record (plan §4.9, §4.8, C4): created by `run start`, pinned OUTSIDE the workspace at
+ * `~/.code-forge/runs/<run>.json` (authoritative) and mirrored to `<workspace>/.code-forge/runs/`
+ * without the `worker` pin (informational only — nothing reads the mirror back).
+ *
+ * The worker pin is `{pid, started_at}` where `started_at` is `ps -o lstart= -p <pid>` — the
+ * process START time, so a recycled pid or a coder-started replacement worker does not match.
+ * The worker itself is B11's: `startRun` takes the pid of a worker the orchestrator started (or
+ * none), and `reattachWorker` re-pins after a restart.
+ *
+ * Ledger rows are written through the `writeRow` parameter (C17 seam: the B6 writer arrives as a
+ * parameter; the CLI verb does the static import) and are SIGNED with the run key first.
+ */
+
+import { mkdir, readFile, rename, rmdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { exec } from '../util/exec.mjs';
+import { StateError, assertRunId, assertWorkspaceOutsideRuns, mirrorPath, newRunId, runRecordPath, runsDir } from './paths.mjs';
+import { generateKey, loadKey, signRow } from './signer.mjs';
+
+/** @typedef {(row: Record<string, any>) => Promise<unknown>} WriteRow */
+/** @typedef {(pid: number) => Promise<string | null>} StartTimeProbe */
+
+const LOCK_TIMEOUT_MS = 5000;
+const LOCK_POLL_MS = 25;
+
+/**
+ * The process start time of `pid` (`ps -o lstart=`), or null when no such process exists.
+ * @type {StartTimeProbe}
+ */
+export async function processStartTime(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  const res = await exec(['ps', '-o', 'lstart=', '-p', String(pid)], {
+    env: { ...process.env, LC_ALL: 'C' },
+    okExitCodes: [0, 1],
+    timeoutMs: 10000,
+  });
+  const text = res.stdout.trim();
+  return res.result === 'ok' && res.code === 0 && text.length > 0 ? text : null;
+}
+
+/** @param {unknown} value @returns {string} */
+const serialize = (value) => `${JSON.stringify(value, null, 2)}\n`;
+
+/**
+ * @param {string} runId
+ * @returns {Promise<Record<string, any>>}
+ */
+export async function readRun(runId) {
+  let text;
+  try {
+    text = await readFile(runRecordPath(runId), 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') throw new StateError('no-run', `no run record for ${runId}`);
+    throw err;
+  }
+  return JSON.parse(text);
+}
+
+/**
+ * Atomically write the authoritative record (0600) and the workspace mirror (minus `worker`).
+ * @param {Record<string, any>} record
+ */
+export async function saveRun(record) {
+  await mkdir(runsDir(), { recursive: true, mode: 0o700 });
+  const file = runRecordPath(record.run_id);
+  const tmp = `${file}.${process.pid}.tmp`;
+  await writeFile(tmp, serialize(record), { mode: 0o600 });
+  await rename(tmp, file);
+  const { worker, ...mirror } = record;
+  const mirrorFile = mirrorPath(record.workspace, record.run_id);
+  await mkdir(path.dirname(mirrorFile), { recursive: true });
+  await writeFile(`${mirrorFile}.tmp`, serialize(mirror));
+  await rename(`${mirrorFile}.tmp`, mirrorFile);
+}
+
+/**
+ * Serialize read-modify-write of one run record across processes (a `mkdir` lock next to it).
+ * @template T
+ * @param {string} runId @param {() => Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+export async function withRunLock(runId, fn) {
+  await mkdir(runsDir(), { recursive: true, mode: 0o700 });
+  const lock = path.join(runsDir(), `${assertRunId(runId)}.lock`);
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+  for (;;) {
+    try {
+      await mkdir(lock);
+      break;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      if (Date.now() > deadline) throw new StateError('locked', `run ${runId} is locked (${lock}); remove it if no forge verb is running`);
+      await new Promise((resolve) => setTimeout(resolve, LOCK_POLL_MS));
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    await rmdir(lock);
+  }
+}
+
+/**
+ * Sign `row` with the run key and hand it to the ledger writer.
+ * @param {string} runId @param {WriteRow} writeRow @param {Record<string, any>} row
+ */
+export async function writeSigned(runId, writeRow, row) {
+  const key = await loadKey(runId);
+  return writeRow(signRow({ run: runId, ...row }, key));
+}
+
+
+/**
+ * A pid this package may ever signal: an integer > 1. `kill(0)` signals the caller's whole
+ * process group, `kill(-1)` every process the user owns, pid 1 is init/launchd.
+ * @param {unknown} pid
+ * @returns {pid is number}
+ */
+export const isSignalablePid = (pid) => Number.isInteger(pid) && /** @type {number} */ (pid) > 1;
+
+/**
+ * @param {number | undefined} workerPid @param {StartTimeProbe} probe
+ * @returns {Promise<{pid: number, started_at: string} | null>}
+ */
+async function pinWorker(workerPid, probe) {
+  if (workerPid === undefined) return null;
+  if (!isSignalablePid(workerPid)) throw new StateError('bad-worker-pid', 'worker pid must be an integer > 1');
+  const startedAt = await probe(workerPid);
+  if (startedAt === null) throw new StateError('worker-not-running', `worker pid ${workerPid} is not running`);
+  return { pid: workerPid, started_at: startedAt };
+}
+
+/**
+ * `run start`: record + key + worker pin + ledger `run.start`, all under the run lock. An
+ * existing run id is refused before anything is written (its key and record stay untouched).
+ * @param {{
+ *   workspace: string, project: string, config?: Record<string, any>, engine?: string,
+ *   runId?: string, workerPid?: number, orchestratorPid?: number, soloPid?: string | null,
+ *   writeRow: WriteRow, probe?: StartTimeProbe, now?: Date,
+ * }} opts
+ * @returns {Promise<Record<string, any>>} the record
+ */
+export async function startRun(opts) {
+  const { project, config = {}, writeRow, probe = processStartTime, now = new Date() } = opts;
+  const runId = assertRunId(opts.runId ?? newRunId(now));
+  if (typeof project !== 'string' || !/^[a-z0-9][a-z0-9-]*$/.test(project)) {
+    throw new StateError('bad-project', 'project slug must match /^[a-z0-9][a-z0-9-]*$/ (config key project.slug)');
+  }
+  const workspace = assertWorkspaceOutsideRuns(opts.workspace);
+  const worker = await pinWorker(opts.workerPid, probe);
+  const record = {
+    version: 1,
+    run_id: runId,
+    project,
+    workspace,
+    engine: opts.engine ?? config.engine ?? 'auto',
+    provider: config.provider ?? null,
+    levels: config.levels ?? null,
+    fallback_mode: config.system1?.fallback ?? 'rules',
+    started_at: now.toISOString(),
+    orchestrator_pid: opts.orchestratorPid ?? process.pid,
+    solo_pid: opts.soloPid ?? null,
+    worker,
+    status: 'active',
+    blocks: {},
+    orphans: [],
+  };
+  return withRunLock(runId, async () => {
+    const exists = await readRun(runId).then(
+      () => true,
+      (err) => (err.code === 'no-run' ? false : Promise.reject(err)),
+    );
+    if (exists) throw new StateError('run-exists', `run ${runId} already exists`);
+    await generateKey(runId);
+    await saveRun(record);
+    await writeSigned(runId, writeRow, { event: 'run.start', engine: record.engine, worker_pinned: worker !== null });
+    return record;
+  });
+}
+
+/**
+ * `run start --reattach`: re-pin a restarted worker (the orchestrator only — §4.8).
+ * @param {{runId: string, workerPid: number, writeRow: WriteRow, probe?: StartTimeProbe}} opts
+ */
+export async function reattachWorker({ runId, workerPid, writeRow, probe = processStartTime }) {
+  if (!isSignalablePid(workerPid)) throw new StateError('bad-worker-pid', 'worker pid must be an integer > 1');
+  return withRunLock(runId, async () => {
+    const current = await readRun(runId);
+    if (current.status !== 'active') throw new StateError('run-ended', `run ${runId} has ended`);
+    current.worker = await pinWorker(workerPid, probe);
+    await writeSigned(runId, writeRow, { event: 'worker.reattach', pid: workerPid });
+    await saveRun(current);
+    return current;
+  });
+}
+
+/**
+ * Does the live worker match the pin? `livePid` is the pid the caller sees serving the queue
+ * (B11's worker pid file); the pinned pid's start time is re-read in every case.
+ * @param {Record<string, any>} record
+ * @param {{livePid?: number, probe?: StartTimeProbe}} [opts]
+ * @returns {Promise<{ok: boolean, event?: 'worker.replaced' | 'worker.down', reason?: string}>}
+ */
+export async function checkWorkerPin(record, { livePid, probe = processStartTime } = {}) {
+  const pin = record.worker;
+  if (!pin) return { ok: false, event: 'worker.down', reason: 'no worker is pinned for this run' };
+  if (!isSignalablePid(pin.pid)) return { ok: false, event: 'worker.replaced', reason: 'the pinned worker pid is not an integer > 1' };
+  if (livePid !== undefined && livePid !== pin.pid) {
+    return { ok: false, event: 'worker.replaced', reason: `live worker pid ${livePid} is not the pinned pid ${pin.pid}` };
+  }
+  const startedAt = await probe(pin.pid);
+  if (startedAt === null) return { ok: false, event: 'worker.down', reason: `pinned worker pid ${pin.pid} is not running` };
+  if (startedAt !== pin.started_at) {
+    return { ok: false, event: 'worker.replaced', reason: `pid ${pin.pid} was restarted (start time differs from the pin)` };
+  }
+  return { ok: true };
+}
+
+/**
+ * The default worker stopper: SIGTERM the pinned pid ONLY when it is an integer > 1 AND its start
+ * time, re-read right before the signal, still equals the pin (a recycled pid is never signalled).
+ * A worker that already exited (ESRCH) counts as not stopped, never as an error.
+ * @param {{pid: number, started_at: string} | null} pin
+ * @param {{probe?: StartTimeProbe, kill?: (pid: number, signal: NodeJS.Signals) => unknown}} [opts]
+ * @returns {Promise<{stopped: boolean, reason?: string}>}
+ */
+export async function stopPinnedWorker(pin, { probe = processStartTime, kill = (pid, signal) => process.kill(pid, signal) } = {}) {
+  if (!pin || !isSignalablePid(pin.pid)) return { stopped: false, reason: 'invalid pid' };
+  const startedAt = await probe(pin.pid);
+  if (startedAt === null) return { stopped: false, reason: 'not running' };
+  if (startedAt !== pin.started_at) return { stopped: false, reason: 'pid reused' };
+  try {
+    kill(pin.pid, 'SIGTERM');
+  } catch (err) {
+    if (err.code === 'ESRCH') return { stopped: false, reason: 'already exited' };
+    throw err;
+  }
+  return { stopped: true };
+}
+
+/**
+ * `run end`, entirely under the run lock: refuse an ended run or open blocks; check the pin (a
+ * failed check is written as its own signed `worker.replaced`/`worker.down` row); stop the
+ * worker only when the pin verifies; mark ended and write `run.end`.
+ * @param {{
+ *   runId: string, writeRow: WriteRow, probe?: StartTimeProbe,
+ *   stopWorker?: (pin: {pid: number, started_at: string}, opts: {probe?: StartTimeProbe}) => Promise<{stopped: boolean}>,
+ * }} opts
+ */
+export async function endRun({ runId, writeRow, stopWorker = stopPinnedWorker, probe = processStartTime }) {
+  return withRunLock(runId, async () => {
+    const current = await readRun(runId);
+    if (current.status !== 'active') throw new StateError('run-ended', `run ${runId} has already ended`);
+    const open = Object.keys(current.blocks).filter((id) => current.blocks[id].status === 'open');
+    if (open.length > 0) throw new StateError('open-blocks', `run ${runId} still has open blocks: ${open.join(', ')}`);
+    const pin = await checkWorkerPin(current, { probe });
+    if (!pin.ok) await writeSigned(runId, writeRow, { event: pin.event, reason: pin.reason });
+    const stop = pin.ok ? await stopWorker(current.worker, { probe }) : { stopped: false };
+    current.status = 'ended';
+    current.ended_at = new Date().toISOString();
+    await writeSigned(runId, writeRow, { event: 'run.end', worker_check: pin.ok ? 'ok' : pin.event, worker_stopped: stop.stopped });
+    await saveRun(current);
+    return current;
+  });
+}

package/src/state/signer.mjs

@@ -0,0 +1,132 @@
+/**
+ * Signed ledger rows (plan §4.8, §8.6, C4) — `mac = HMAC-SHA256(run key, canonical row)`.
+ *
+ * What this proves, stated as the plan states it: TAMPER EVIDENCE within a coder's ordinary tool
+ * use (T1 a row the worker never wrote, T2 a result edited after signing, T3 — with the row keyed
+ * by content hash upstream — a stale approval). It is NOT a same-user boundary: the key is a 0600
+ * file the same OS user can read, so a coder that deliberately `cat`s it can mint a valid MAC. The
+ * forbidden list (`code-forge-runs-access`) and the transcript grep make that a named rule-break;
+ * the real boundary (a second OS user or a container) is the consumer's choice.
+ *
+ * Canonical form: the row minus `UNSIGNED_FIELDS`, keys sorted recursively, `JSON.stringify`
+ * value encoding. `tokens_source`/`cost_source` are excluded because the ledger writer (B6
+ * `appendRow`) fills them in AFTER signing — they are labels, never gate inputs. `ts` IS signed,
+ * so `signRow` stamps it first (the writer keeps an existing `ts`).
+ */
+
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { chmod, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { registerSecret } from '../util/redact.mjs';
+import { StateError, runKeyPath, runsDir } from './paths.mjs';
+
+export const KEY_BYTES = 32;
+
+/** Fields the MAC does not cover (see the module doc). */
+export const UNSIGNED_FIELDS = Object.freeze(['mac', 'tokens_source', 'cost_source']);
+
+/**
+ * Create the run's key: 32 random bytes, mode 0600, in `~/.code-forge/runs/` (0700). Refuses to
+ * overwrite an existing key — key rotation is a new run.
+ * @param {string} runId
+ * @returns {Promise<Buffer>}
+ */
+export async function generateKey(runId) {
+  await mkdir(runsDir(), { recursive: true, mode: 0o700 });
+  await chmod(runsDir(), 0o700); // `mode` only applies to a directory mkdir creates
+  const key = randomBytes(KEY_BYTES);
+  const file = runKeyPath(runId);
+  try {
+    await writeFile(file, key, { mode: 0o600, flag: 'wx' });
+  } catch (err) {
+    if (err.code === 'EEXIST') throw new StateError('key-exists', `run ${runId} already has a key`);
+    throw err;
+  }
+  await chmod(file, 0o600);
+  registerSecret(key.toString('hex'));
+  return key;
+}
+
+/**
+ * @param {string} runId
+ * @returns {Promise<Buffer>}
+ * @throws {StateError} `no-key` / `bad-key` / `bad-key-mode` (group- or world-accessible)
+ */
+export async function loadKey(runId) {
+  let key;
+  try {
+    const { mode } = await stat(runKeyPath(runId));
+    if ((mode & 0o077) !== 0) throw new StateError('bad-key-mode', `run ${runId} signer key is accessible to other users (mode ${(mode & 0o777).toString(8)}); expected 600`);
+    key = await readFile(runKeyPath(runId));
+  } catch (err) {
+    if (err.code === 'ENOENT') throw new StateError('no-key', `run ${runId} has no signer key`);
+    throw err;
+  }
+  if (key.length !== KEY_BYTES) throw new StateError('bad-key', `run ${runId} signer key is not ${KEY_BYTES} bytes`);
+  registerSecret(key.toString('hex'));
+  return key;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string} JSON with object keys sorted at every depth.
+ */
+export function canonicalJSON(value) {
+  if (Array.isArray(value)) return `[${value.map((v) => (v === undefined ? 'null' : canonicalJSON(v))).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    const entries = Object.keys(value)
+      .sort()
+      .filter((k) => value[k] !== undefined)
+      .map((k) => `${JSON.stringify(k)}:${canonicalJSON(value[k])}`);
+    return `{${entries.join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/**
+ * @param {Record<string, any>} row @param {Buffer} key
+ * @returns {string} hex MAC
+ */
+export function macFor(row, key) {
+  // The JSON round trip is what the ledger stores: Date → ISO string, functions/undefined dropped;
+  // a BigInt throws (a row that cannot be written must not be signed).
+  const covered = JSON.parse(JSON.stringify(row));
+  for (const field of UNSIGNED_FIELDS) delete covered[field];
+  return createHmac('sha256', key).update(canonicalJSON(covered)).digest('hex');
+}
+
+/**
+ * @param {Record<string, any>} row @param {Buffer} key
+ * @returns {Record<string, any>} the row with `ts` stamped (when absent) and `mac` set.
+ */
+export function signRow(row, key) {
+  /** @type {Record<string, any>} */
+  const stamped = { ...row, ts: row.ts ?? new Date().toISOString() };
+  delete stamped.mac;
+  return { ...stamped, mac: macFor(stamped, key) };
+}
+
+/**
+ * @param {Record<string, any>} row @param {Buffer} key
+ * @returns {{ok: boolean, reason?: 'unsigned' | 'mismatch'}}
+ */
+export function verifyRow(row, key) {
+  if (typeof row?.mac !== 'string' || row.mac.length === 0) return { ok: false, reason: 'unsigned' };
+  if (!/^[0-9a-f]{64}$/.test(row.mac)) return { ok: false, reason: 'mismatch' };
+  const expected = Buffer.from(macFor(row, key), 'hex');
+  const given = Buffer.from(row.mac, 'hex');
+  if (given.length !== expected.length || !timingSafeEqual(given, expected)) return { ok: false, reason: 'mismatch' };
+  return { ok: true };
+}
+
+/**
+ * @param {Record<string, any>[]} rows @param {Buffer} key
+ * @returns {{ok: boolean, failures: {index: number, event: string, reason: string}[]}}
+ */
+export function verifyRows(rows, key) {
+  const failures = [];
+  rows.forEach((row, index) => {
+    const result = verifyRow(row, key);
+    if (!result.ok) failures.push({ index, event: String(row?.event), reason: result.reason });
+  });
+  return { ok: failures.length === 0, failures };
+}