@codedology/code-forge 0.1.0

package/src/cli/review-file.mjs

@@ -0,0 +1,152 @@
+/**
+ * `code-forge review-file` (plan §4.1, §4.8, V4; block B11) — the coder's side of async review.
+ *
+ *   review-file <path> --block <id> [--run <id>]   enqueue; prints {ticket, status: queued|done, file}
+ *   review-file --wait <ticket> [--max <90s>]      poll; prints {ticket, status: done, result} or
+ *                                                  {ticket, status: pending} when --max elapses
+ *
+ * The same content enqueued again after an `unavailable` result is a fresh attempt (`retry: true`),
+ * not the old result.
+ * A done result that is not approved and carries open findings adds `fix_list` (what the coder
+ * fixes before re-running `review-file <path>`, which is then a round-2 recheck of the fix hunks,
+ * §4.11); a result the loop stopped adds `stop` with the reason (`review_cap`, …) — the coder
+ * stops and reports; only the orchestrator and the human act on it.
+ *
+ * Everything is a file read/write inside the workspace (a sandboxed coder has no network). The
+ * path is given relative to the current directory and stored relative to the REPOSITORY ROOT
+ * (V4); an absolute path or a `..` segment is refused with `bad-path`. With no live worker the
+ * answer is `worker_down` — never approval — and nothing is enqueued; the coder must then print
+ * `===BLOCK <id> FAILED: worker down===`. Output is one JSON line on stdout.
+ * Exit codes: 0 queued/done/pending, 1 bad-path or another refusal, 2 usage, 3 worker_down.
+ */
+
+import { readFileSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import { enqueue, isDone, liveWorker, queueDir } from '../worker/queue.mjs';
+import { assertBlockId, assertTicketId, normalizeRequestPath, repoRootOf, WorkerError } from '../worker/ticket.mjs';
+import { parseFlags } from '../state/cli-args.mjs';
+import { writeSafe } from '../util/redact.mjs';
+
+const USAGE = 'usage: code-forge review-file <path> --block <id> [--run <id>] | review-file --wait <ticket> [--max <seconds>s]\n';
+
+export const DEFAULT_WAIT_MS = 90_000;
+const POLL_MS = 200;
+
+/**
+ * `90s`, `90`, `1500ms` → milliseconds.
+ * @param {unknown} raw @returns {number}
+ */
+export function parseMax(raw) {
+  const m = typeof raw === 'string' ? /^(\d{1,7})(ms|s)?$/.exec(raw) : null;
+  if (!m) throw new WorkerError('usage', '--max must look like 90s or 1500ms');
+  const n = Number(m[1]);
+  return m[2] === 'ms' ? n : n * 1000;
+}
+
+/**
+ * @param {string} repoRoot @param {string} ticket
+ * @returns {Record<string, any> | null} the worker's result named by the done marker.
+ */
+function doneResult(repoRoot, ticket) {
+  try {
+    const marker = JSON.parse(readFileSync(path.join(queueDir(repoRoot), `${ticket}.done`), 'utf8'));
+    const rel = typeof marker.result === 'string' ? marker.result : '';
+    if (!rel.startsWith(`.code-forge${path.sep}reviews${path.sep}`) || rel.split(path.sep).includes('..')) return null;
+    return JSON.parse(readFileSync(path.join(repoRoot, rel), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The coder-facing summary of a done result: the fix list and the stop reason, when any.
+ * @param {Record<string, any> | null} result
+ * @returns {Record<string, any>}
+ */
+export function fixList(result) {
+  if (!result || result.approved === true) return {};
+  /** @type {Record<string, any>} */
+  const out = {};
+  if (Array.isArray(result.findings) && result.findings.length > 0) {
+    out.fix_list = result.findings.map((/** @type {Record<string, any>} */ f) => ({
+      id: f?.id ?? null,
+      severity: f?.severity ?? null,
+      lines: `${f?.line_start ?? '?'}-${f?.line_end ?? '?'}`,
+      claim: f?.claim ?? '',
+      fix: f?.fix ?? '',
+    }));
+  }
+  if (typeof result.stopped === 'string') out.stop = result.stopped;
+  return out;
+}
+
+/**
+ * @param {string[]} args
+ * @param {{stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown}, cwd?: string, pollMs?: number}} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runReviewFile(args, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const say = (/** @type {Record<string, any>} */ obj) => writeSafe(stdout, `${JSON.stringify(obj)}\n`);
+  const cwd = deps.cwd ?? process.cwd();
+  try {
+    const { flags, positionals } = parseFlags(args, { values: ['block', 'run', 'wait', 'max'] });
+    const repoRoot = await repoRootOf(cwd);
+
+    if (typeof flags.wait === 'string') {
+      if (positionals.length > 0 || flags.block !== undefined) throw new WorkerError('usage', '--wait takes only a ticket and --max');
+      const ticket = assertTicketId(flags.wait);
+      const maxMs = flags.max === undefined ? DEFAULT_WAIT_MS : parseMax(flags.max);
+      const deadline = Date.now() + maxMs;
+      for (;;) {
+        if (isDone(repoRoot, ticket)) {
+          const result = doneResult(repoRoot, ticket);
+          say({ ticket, status: 'done', result, ...fixList(result) });
+          return 0;
+        }
+        if (!liveWorker(repoRoot)) {
+          say({ ticket, status: 'worker_down' });
+          return 3;
+        }
+        if (Date.now() >= deadline) {
+          say({ ticket, status: 'pending' });
+          return 0;
+        }
+        await new Promise((resolve) => setTimeout(resolve, deps.pollMs ?? POLL_MS));
+      }
+    }
+
+    if (positionals.length !== 1 || typeof flags.block !== 'string' || flags.max !== undefined) throw new WorkerError('usage', 'give one path and --block');
+    const block = assertBlockId(flags.block);
+    const file = normalizeRequestPath(positionals[0], cwd, repoRoot);
+    const worker = liveWorker(repoRoot);
+    if (!worker || (typeof flags.run === 'string' && flags.run !== worker.run)) {
+      say({ status: 'worker_down', file });
+      return 3;
+    }
+    const queued = enqueue({ repoRoot, run: worker.run, block, file });
+    if (queued.status === 'done' && doneResult(repoRoot, queued.ticket)?.status === 'unavailable') {
+      // `unavailable` is never approval AND never final: drop the done marker so the worker runs
+      // the ticket again (the fix loop re-runs its pending round); the signed result is replaced.
+      rmSync(path.join(queueDir(repoRoot), `${queued.ticket}.done`), { force: true });
+      say({ ...enqueue({ repoRoot, run: worker.run, block, file }), retry: true });
+      return 0;
+    }
+    say(queued);
+    return 0;
+  } catch (err) {
+    const code = err instanceof WorkerError || err?.name === 'StateError' ? err.code : 'error';
+    if (code === 'usage') {
+      writeSafe(stderr, `review-file: ${err.message}\n${USAGE}`);
+      return 2;
+    }
+    say({ status: 'refused', reason: code, message: err?.message ?? String(err) });
+    return 1;
+  }
+}
+
+/** @param {string[]} args @returns {Promise<number>} */
+export default async function run(args) {
+  return runReviewFile(args);
+}

package/src/cli/run.mjs

@@ -0,0 +1,159 @@
+/**
+ * `code-forge run start|status|end` (plan §4.9). The orchestrator runs these; a coder never does
+ * (`run start` is on the forbidden list, ★ `code-forge-worker-from-coder`).
+ *
+ *   run start [--cwd <dir>] [--run <id>] [--engine <e>] [--worker-pid <pid>]
+ *   run start --reattach --run <id> [--worker-pid <pid>]
+ *   run status --run <id>
+ *   run end --run <id>
+ *
+ * B11: from the CLI (the default export), `run start` without `--worker-pid` sweeps dead run
+ * roots, launches `code-forge worker --run <id>` detached, waits until it announces itself in the
+ * queue and pins it; `run start --reattach` without `--worker-pid` re-pins the live worker the
+ * queue announces (`repinWorker`). Called as `runRun(args, deps)` without `deps.startWorker` (the
+ * state tests), no worker is launched and none is pinned unless `--worker-pid` is given.
+ */
+
+import path from 'node:path';
+import { loadProjectConfig } from '../config/load.mjs';
+import { appendRow } from '../ledger/write.mjs';
+import { intFlag, parseFlags } from '../state/cli-args.mjs';
+import { StateError } from '../state/paths.mjs';
+import { endRun, processStartTime, readRun, reattachWorker, startRun, stopPinnedWorker } from '../state/run.mjs';
+import { writeSafe } from '../util/redact.mjs';
+import { sweepRoots, tmpBase } from '../util/tmp.mjs';
+import { launchWorker, repinWorker } from '../worker/loop.mjs';
+import { repoRootOf } from '../worker/ticket.mjs';
+
+/**
+ * `project.slug` from config, else the workspace directory name as a ledger slug. The configured
+ * value is NOT trusted here: `startRun` refuses any slug outside `/^[a-z0-9][a-z0-9-]*$/`
+ * (`bad-project`) before anything is written, so `../x` never reaches the ledger path. Run ids
+ * are checked the same way by the state layer (`assertRunId`, `bad-run-id`).
+ * @param {Record<string, any>} cfg @param {string} workspace
+ * @returns {string}
+ */
+export function slugFor(cfg, workspace) {
+  const configured = cfg?.project?.slug;
+  if (typeof configured === 'string' && configured.length > 0) return configured;
+  const derived = path.basename(workspace).toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
+  return derived || 'project';
+}
+
+/** @param {string} slug */
+const ledgerWriter = (slug) => (/** @type {Record<string, any>} */ row) => appendRow(row, { slug });
+
+/** @typedef {(pin: {pid: number, started_at: string}, opts: {probe?: import('../state/run.mjs').StartTimeProbe}) => Promise<{stopped: boolean, reason?: string}>} StopWorker */
+
+/**
+ * A worker that `run start` launched but could not pin must not outlive the command as an orphan:
+ * stop it through the pinned-worker stopper (pid > 1, start time re-checked right before the
+ * signal, so a recycled pid is never signalled) and name the pid on stderr. `startedAt` is the
+ * start time read right after the launch; null means the process was already gone.
+ * @param {{pid: number, startedAt: string | null}} launched
+ * @param {{stopWorker: StopWorker, probe?: import('../state/run.mjs').StartTimeProbe, err: (s: string) => void}} deps
+ */
+async function stopLaunched({ pid, startedAt }, { stopWorker, probe, err }) {
+  /** @type {{stopped: boolean, reason?: string}} */
+  let outcome;
+  try {
+    outcome = startedAt === null ? { stopped: false, reason: 'not running' } : await stopWorker({ pid, started_at: startedAt }, { ...(probe ? { probe } : {}) });
+  } catch (thrown) {
+    outcome = { stopped: false, reason: thrown?.message ?? String(thrown) };
+  }
+  err(`run start: launched worker pid ${pid} was not pinned; ${outcome.stopped ? 'stopped it' : `not stopped (${outcome.reason ?? 'unknown'})`}\n`);
+}
+
+/**
+ * @param {string[]} args
+ * @param {{
+ *   stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown},
+ *   probe?: import('../state/run.mjs').StartTimeProbe,
+ *   stopWorker?: StopWorker,
+ *   startWorker?: (opts: {runId: string, workspace: string}) => Promise<{pid: number, repoRoot: string}>,
+ * }} [deps] - `startWorker` (the CLI passes B11's `launchWorker`) launches the worker on a plain
+ *   `run start`; `stopWorker` defaults to the state layer's `stopPinnedWorker` (pid > 1 and a
+ *   re-verified start time before any signal) — `run end` uses it, and so does a `run start` whose
+ *   launched worker could not be pinned.
+ * @returns {Promise<number>}
+ */
+export async function runRun(args, deps = {}) {
+  const { stdout = process.stdout, stderr = process.stderr, probe, stopWorker, startWorker } = deps;
+  const out = (/** @type {string} */ s) => writeSafe(stdout, s);
+  const err = (/** @type {string} */ s) => writeSafe(stderr, s);
+  const [sub, ...rest] = args;
+  if (!['start', 'status', 'end'].includes(sub)) {
+    err(USAGE);
+    return 2;
+  }
+  try {
+    const { flags } = parseFlags(rest, { values: ['run', 'cwd', 'engine', 'worker-pid'], booleans: ['reattach'] });
+    const runId = typeof flags.run === 'string' ? flags.run : undefined;
+    const workerPid = intFlag(flags['worker-pid'], 'worker-pid');
+
+    if (sub === 'start' && flags.reattach) {
+      if (!runId) throw new StateError('usage', 'run start --reattach needs --run');
+      const { project, workspace } = await readRun(runId);
+      if (workerPid !== undefined) {
+        await reattachWorker({ runId, workerPid, writeRow: ledgerWriter(project), probe });
+        out(`run ${runId}: worker re-pinned to pid ${workerPid}\n`);
+        return 0;
+      }
+      const repinned = await repinWorker({ runId, repoRoot: await repoRootOf(workspace), writeRow: ledgerWriter(project), ...(probe ? { probe } : {}) });
+      out(`run ${runId}: worker re-pinned to pid ${repinned.worker.pid}\n`);
+      return 0;
+    }
+    if (sub === 'start') {
+      const workspace = path.resolve(typeof flags.cwd === 'string' ? flags.cwd : process.cwd());
+      const loaded = await loadProjectConfig(workspace);
+      if (!loaded.ok) {
+        err(`run start: ${loaded.message}\n`);
+        return 2;
+      }
+      const project = slugFor(loaded.config, workspace);
+      const engine = typeof flags.engine === 'string' ? flags.engine : undefined;
+      const tmpRoot = typeof loaded.config?.tmp?.root === 'string' ? loaded.config.tmp.root : undefined;
+      await sweepRoots({ root: tmpBase(tmpRoot) }); // dead runs' temp roots and orphans (§9.6, V12)
+      let record = await startRun({ workspace, project, config: loaded.config, engine, runId, workerPid, writeRow: ledgerWriter(project), probe });
+      if (!record.worker && startWorker) {
+        const launched = await startWorker({ runId: record.run_id, workspace });
+        const startedAt = await (probe ?? processStartTime)(launched.pid); // what the stop below re-checks against
+        try {
+          // pin ONLY the pid we launched: an older announced worker must not be pinned over it
+          record = await repinWorker({ runId: record.run_id, repoRoot: launched.repoRoot, writeRow: ledgerWriter(project), expectPid: launched.pid, ...(probe ? { probe } : {}) });
+        } catch (thrown) {
+          await stopLaunched({ pid: launched.pid, startedAt }, { stopWorker: stopWorker ?? stopPinnedWorker, probe, err });
+          throw thrown;
+        }
+      }
+      out(`run ${record.run_id} started · engine ${record.engine} · worker ${record.worker ? `pid ${record.worker.pid}` : 'not pinned'}\n`);
+      if (!record.worker) err('run start: no worker pinned — start the worker, then `run start --reattach --run <id> --worker-pid <pid>`\n');
+      return 0;
+    }
+    if (sub === 'status' && runId) {
+      const record = await readRun(runId);
+      const { run_id, status, engine, blocks, orphans } = record;
+      out(`${JSON.stringify({ run_id, status, engine, worker_pinned: Boolean(record.worker), blocks, orphans }, null, 2)}\n`);
+      return 0;
+    }
+    if (sub === 'end' && runId) {
+      const { project } = await readRun(runId);
+      const record = await endRun({ runId, writeRow: ledgerWriter(project), stopWorker, probe });
+      out(`run ${record.run_id} ended\n`);
+      return 0;
+    }
+  } catch (thrown) {
+    err(`run ${sub ?? ''}: ${thrown?.message ?? String(thrown)}\n`);
+    return thrown instanceof StateError && thrown.code === 'usage' ? 2 : 1;
+  }
+  err(USAGE);
+  return 2;
+}
+
+const USAGE =
+  'usage: code-forge run start [--cwd <dir>] [--run <id>] [--engine <e>] [--worker-pid <pid>] | start --reattach --run <id> [--worker-pid <pid>] | status --run <id> | end --run <id>\n';
+
+/** @param {string[]} args @returns {Promise<number>} */
+export default async function run(args) {
+  return runRun(args, { startWorker: launchWorker });
+}

package/src/cli/s2.mjs

@@ -0,0 +1,93 @@
+/**
+ * `code-forge s2 --packet <file.json> [--run <id>] [--block <id>] [--timeout <s>]` (plan §3.4;
+ * block B9a). The packet file is `{question, context?, options?, s1?}`; the verb prints the S2
+ * answer `{decision, confidence, reason, overrule, ask_human, human_question}` as one JSON line.
+ * Exit codes: 0 answered, 1 failed or invalid answer, 2 usage, 3 L3 and every fallback
+ * unavailable (S2 ⇒ stop and ask the human, §5.6).
+ */
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { loadProjectConfig } from '../config/load.mjs';
+import { runS2 } from '../session/s2.mjs';
+import { runRootFor, SessionError } from '../session/spawn.mjs';
+import { intFlag, parseFlags } from '../state/cli-args.mjs';
+import { StateError } from '../state/paths.mjs';
+import { writeSafe } from '../util/redact.mjs';
+import { slugFor } from './run.mjs';
+import { exitCodeFor } from './spawn.mjs';
+
+/**
+ * @param {string} file @param {string} flag
+ * @returns {Promise<any>}
+ * @throws {SessionError} `usage` naming the flag only — never the file's content.
+ */
+async function readJSONFlag(file, flag) {
+  let text;
+  try {
+    text = await readFile(path.resolve(file), 'utf8');
+  } catch {
+    throw new SessionError('usage', `--${flag} cannot be read`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new SessionError('usage', `--${flag} is not a valid JSON file`);
+  }
+}
+
+const USAGE = 'usage: code-forge s2 --packet <file.json> [--run <id>] [--block <id>] [--timeout <seconds>]\n';
+
+/**
+ * @param {string[]} args
+ * @param {import('../session/spawn.mjs').SessionDeps & {stdout?: {write: (s: string) => unknown}}} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runS2Verb(args, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  try {
+    const { flags, positionals } = parseFlags(args, { values: ['packet', 'run', 'block', 'timeout'] });
+    if (positionals.length > 0 || typeof flags.packet !== 'string') {
+      writeSafe(stderr, USAGE);
+      return 2;
+    }
+    const loaded = await loadProjectConfig(process.cwd());
+    if (!loaded.ok) {
+      writeSafe(stderr, `s2: ${loaded.message}\n`);
+      return 2;
+    }
+    const cfg = loaded.config;
+    const timeout = intFlag(flags.timeout, 'timeout');
+    const packet = await readJSONFlag(flags.packet, 'packet');
+    const result = await runS2(
+      {
+        cfg,
+        packet,
+        run: typeof flags.run === 'string' ? flags.run : undefined,
+        block: typeof flags.block === 'string' ? flags.block : undefined,
+        runRoot: typeof flags.run === 'string' ? runRootFor(flags.run, cfg?.tmp?.root) : undefined,
+        slug: slugFor(cfg, process.cwd()),
+        timeoutMs: timeout === undefined ? undefined : timeout * 1000,
+      },
+      { ...deps, stderr },
+    );
+    if (result.status === 'ok') {
+      writeSafe(stdout, `${JSON.stringify(result.answer)}\n`);
+    } else {
+      writeSafe(stderr, `s2: ${result.status}${result.reason ? ` (${result.reason})` : ''}\n`);
+    }
+    return exitCodeFor(result);
+  } catch (err) {
+    if (err instanceof StateError || err instanceof SessionError) {
+      writeSafe(stderr, `s2: ${/** @type {Error} */ (err).message}\n`);
+      return 2;
+    }
+    throw err;
+  }
+}
+
+/** @param {string[]} args */
+export default async function s2Verb(args) {
+  return runS2Verb(args);
+}

package/src/cli/spawn.mjs

@@ -0,0 +1,104 @@
+/**
+ * `code-forge spawn --level L<n> --role <role> --brief <file> [--schema <file>] [--cwd <dir>]
+ *   [--run <id>] [--block <id>] [--timeout <s>] [--background]` (plan §5.2; block B9a).
+ *
+ * Runs one isolated session through `src/session/spawn.mjs` and prints its result as one JSON line
+ * on stdout; the `level=… provider=… model=… effort=… fallback_step=…` line goes to stderr.
+ * Exit codes: 0 ok / started, 1 failed (timeout, bad output, refused), 2 usage, 3 unavailable
+ * (every step of the ladder reported unavailability).
+ */
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { loadProjectConfig } from '../config/load.mjs';
+import { ROLES, runRootFor, SessionError, spawnSession } from '../session/spawn.mjs';
+import { intFlag, parseFlags } from '../state/cli-args.mjs';
+import { StateError } from '../state/paths.mjs';
+import { writeSafe } from '../util/redact.mjs';
+import { slugFor } from './run.mjs';
+
+/**
+ * @param {string} file @param {string} flag
+ * @returns {Promise<any>}
+ * @throws {SessionError} `usage` naming the flag only — never the file's content.
+ */
+async function readJSONFlag(file, flag) {
+  let text;
+  try {
+    text = await readFile(path.resolve(file), 'utf8');
+  } catch {
+    throw new SessionError('usage', `--${flag} cannot be read`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new SessionError('usage', `--${flag} is not a valid JSON file`);
+  }
+}
+
+const USAGE = `usage: code-forge spawn --level L0|L1|L2|L3 --role ${ROLES.join('|')} --brief <file> [--schema <file>] [--cwd <dir>] [--run <id>] [--block <id>] [--timeout <seconds>] [--background]\n`;
+
+/**
+ * @param {{status: string}} result
+ * @returns {number}
+ */
+export function exitCodeFor(result) {
+  if (result.status === 'ok' || result.status === 'started') return 0;
+  return result.status === 'unavailable' ? 3 : 1;
+}
+
+/**
+ * @param {string[]} args
+ * @param {import('../session/spawn.mjs').SessionDeps & {stdout?: {write: (s: string) => unknown}}} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runSpawn(args, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  try {
+    const { flags, positionals } = parseFlags(args, { values: ['level', 'role', 'brief', 'schema', 'cwd', 'run', 'block', 'timeout'], booleans: ['background'] });
+    if (positionals.length > 0 || typeof flags.level !== 'string' || typeof flags.role !== 'string' || typeof flags.brief !== 'string') {
+      writeSafe(stderr, USAGE);
+      return 2;
+    }
+    const loaded = await loadProjectConfig(process.cwd());
+    if (!loaded.ok) {
+      writeSafe(stderr, `spawn: ${loaded.message}\n`);
+      return 2;
+    }
+    const cfg = loaded.config;
+    const timeout = intFlag(flags.timeout, 'timeout');
+    const schema = typeof flags.schema === 'string' ? await readJSONFlag(flags.schema, 'schema') : undefined;
+    const result = await spawnSession(
+      {
+        cfg,
+        level: /** @type {any} */ (flags.level),
+        role: /** @type {any} */ (flags.role),
+        promptPath: path.resolve(flags.brief),
+        cwd: typeof flags.cwd === 'string' ? path.resolve(flags.cwd) : undefined,
+        schema,
+        timeoutMs: timeout === undefined ? undefined : timeout * 1000,
+        background: flags.background === true,
+        runRoot: typeof flags.run === 'string' ? runRootFor(flags.run, cfg?.tmp?.root) : undefined,
+        run: typeof flags.run === 'string' ? flags.run : undefined,
+        block: typeof flags.block === 'string' ? flags.block : undefined,
+        slug: slugFor(cfg, process.cwd()),
+      },
+      { ...deps, stderr },
+    );
+    const { text: _text, ...shown } = /** @type {Record<string, any>} */ (result);
+    writeSafe(stdout, `${JSON.stringify(shown)}\n`);
+    return exitCodeFor(result);
+  } catch (err) {
+    if (err instanceof StateError || err instanceof SessionError) {
+      writeSafe(stderr, `spawn: ${/** @type {Error} */ (err).message}\n`);
+      return err instanceof SessionError && err.code === 'forbidden' ? 1 : 2;
+    }
+    throw err;
+  }
+}
+
+/** @param {string[]} args */
+export default async function spawnVerb(args) {
+  return runSpawn(args);
+}

package/src/cli/upgrade.mjs

@@ -0,0 +1,103 @@
+/**
+ * `code-forge upgrade [--source <path>]` — re-points every recorded install at a skill source
+ * (plan §10.3 acceptance: "`upgrade` re-points all 3 recorded links"; research/installer-patterns.md
+ * point 8, "a self `upgrade` command"). A symlink record is re-created to point at the new
+ * source; a copy record is re-copied from it. With no `--source`, defaults to this running
+ * package's own `skill/` directory (the normal case: `npm update` moved the package, `upgrade`
+ * re-syncs every harness to it) — `--source` exists for pointing at an explicit path instead
+ * (tests, or a power user working from a git checkout of the skill).
+ */
+
+import { stat } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { writeSafe } from '../util/redact.mjs';
+import { installsPath, upgradeAll } from '../install/link.mjs';
+
+const USAGE = 'usage: code-forge upgrade [--source <path>]\n';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/** This package's own skill directory: `<package root>/skill`, i.e. two levels above `src/cli/`. */
+export const DEFAULT_SKILL_SOURCE = path.join(__dirname, '..', '..', 'skill');
+
+/**
+ * Strict parse: `[--source <path>]` only.
+ * @param {string[]} args
+ * @returns {{source?: string} | null}
+ */
+export function parseUpgradeArgs(args) {
+  if (args.length === 0) {
+    return {};
+  }
+  const [flag, value, ...extra] = args;
+  if (flag !== '--source' || typeof value !== 'string' || value.length === 0 || extra.length > 0) {
+    return null;
+  }
+  return { source: value };
+}
+
+/**
+ * @param {string[]} args
+ * @param {object} deps
+ * @param {{write: (s: string) => unknown}} [deps.stdout]
+ * @param {{write: (s: string) => unknown}} [deps.stderr]
+ * @param {string} [deps.home]
+ * @param {string} [deps.defaultSource]
+ * @param {string} [deps.cwd] - a relative `--source` is resolved against this, never against the
+ *   link's own directory (which `symlink()` would otherwise silently use).
+ * @returns {Promise<number>}
+ */
+export async function runUpgrade(
+  args,
+  {
+    stdout = process.stdout,
+    stderr = process.stderr,
+    home = os.homedir(),
+    defaultSource = DEFAULT_SKILL_SOURCE,
+    cwd = process.cwd(),
+  } = {},
+) {
+  const out = (/** @type {string} */ s) => writeSafe(stdout, s);
+  const err = (/** @type {string} */ s) => writeSafe(stderr, s);
+
+  const parsed = parseUpgradeArgs(args);
+  if (!parsed) {
+    err(USAGE);
+    return 2;
+  }
+
+  // Resolved BEFORE use: a relative --source (e.g. "./skill") must mean "relative to where the
+  // user ran this command", never get stored/symlinked as a relative string (which `readlink`
+  // would then resolve against the LINK's own directory, not the user's cwd).
+  const resolvedSource = path.resolve(cwd, parsed.source ?? defaultSource);
+
+  let sourceStat;
+  try {
+    sourceStat = await stat(resolvedSource);
+  } catch {
+    err(`upgrade: source "${resolvedSource}" does not exist\n`);
+    return 1;
+  }
+  if (!sourceStat.isDirectory()) {
+    err(`upgrade: source "${resolvedSource}" is not a directory\n`);
+    return 1;
+  }
+
+  const updated = await upgradeAll({ installsFile: installsPath(home), source: resolvedSource });
+  for (const record of updated) {
+    out(`upgraded ${record.harness} (${record.scope}) -> ${record.source}\n`);
+  }
+  if (updated.length === 0) {
+    out('nothing to upgrade\n');
+  }
+  return 0;
+}
+
+/**
+ * @param {string[]} args
+ * @returns {Promise<number>}
+ */
+export default async function upgrade(args) {
+  return runUpgrade(args, {});
+}