@coulb/crux-cli 0.1.0

package/lib/spawn.js

@@ -0,0 +1,436 @@
+'use strict';
+
+/**
+ * Per-thread agent spawning (brief §6/§7) — and the mechanism that makes a worker REPORT and DIE.
+ *
+ * A spawned worker used to end its life at an idle prompt: task finished, nothing said, process
+ * still up. `WORKER-CONTRACT.md` asks the agent to report and to exit, but a contract an agent has
+ * to *remember* is not a mechanism — three workers forgot in one day. So both halves are moved into
+ * the harness, and there are two modes to move them into:
+ *
+ *   HEADLESS (the default). `claude -p --output-format json` does the work, prints ONE json object
+ *   — `{result, session_id, is_error, num_turns, total_cost_usd}` — and EXITS. The exit is the reap
+ *   (nothing to kill, no prompt to idle at) and the `result` is the report, which crux posts to the
+ *   thread on the agent's behalf. The agent no longer *chooses* to report; its final message simply
+ *   IS the report. {@see resultJson} recovers that object and {@see workerReport} turns it into what
+ *   lands on the thread — including when the agent died, which must be just as loud (silence is the
+ *   bug being killed).
+ *
+ *   LIVE (`--live`). Interactive + `--remote-control`, for a thread the human wants to open and talk
+ *   to. Headless and Remote Control are mutually exclusive — `-p --remote-control` is accepted but
+ *   silently mints no URL — so this mode keeps a real pty, and pays for it: an interactive agent
+ *   never exits on its own, so its reap is bound to its THREAD's death instead (`crux done` stops
+ *   the Solo process, hence `agent_process_id` on the item).
+ *
+ * `solo processes spawn --agent-tool-id 3` appends each `--arg` AFTER
+ * `claude --dangerously-skip-permissions`, so every flag has to ride in as its own `--arg`.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+/** Solo process statuses that mean the agent is no longer running — see `solo processes list`. */
+const SOLO_TERMINAL = new Set(['exited', 'failed', 'stopped']);
+
+/**
+ * `solo … --json`, but tolerantly: null on any failure instead of a fatal error.
+ *
+ * The counterpart to crux.js's `solo()`, and the distinction is deliberate. SPAWNING is load-bearing
+ * — if Solo cannot start the agent there is no agent, and dying loudly is right. Everything AFTER
+ * the spawn (polling the worker, reading its buffer, stopping it) is best-effort by contract: a Solo
+ * hiccup must not take down the supervisor that is the only thing left to report the worker's death,
+ * and `crux done` must still close a thread whose process is already gone.
+ */
+function soloTry(argv) {
+  try {
+    const raw = execFileSync(process.env.CRUX_SOLO_BIN || 'solo', [...argv, '--json'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const doc = JSON.parse(raw);
+    return doc.ok ? doc.data : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A worker's Solo status: `running` / `exited` / `failed` / …, or `gone` when Solo has answered and
+ * has no such process — or NULL when Solo could not be asked at all.
+ *
+ * That last distinction is the whole reason this returns a status rather than a process. "Solo has
+ * forgotten this worker" and "Solo did not pick up the phone" are the same value to any tolerant
+ * lookup, and conflating them would be the worst bug in the feature: a Solo hiccup mid-poll would
+ * read as a dead agent, and the supervisor would file the worker's obituary while it was still
+ * working. So null means *unknown*, and unknown means keep waiting.
+ *
+ * Paginated, for the reason `soloProcesses()` spells out: an unpaginated list looks complete and is
+ * not. A worker that fell off a truncated page would read as `gone` — the same false death.
+ */
+function soloStatus(procId, projectId = null) {
+  const wanted = String(procId);
+
+  for (let offset = 0; ; ) {
+    const argv = ['processes', 'list', '--limit', '200', '--offset', String(offset)];
+    if (projectId !== undefined && projectId !== null) argv.push('--project-id', String(projectId));
+
+    const page = soloTry(argv);
+    if (page === null) return null; // Could not ask. NOT an answer of "no".
+
+    const processes = page.processes || [];
+    const found = processes.find((p) => String(p.id) === wanted);
+    if (found) return found.status;
+
+    if (!page.hasMore || processes.length === 0) return 'gone';
+    offset = page.nextOffset ?? offset + processes.length;
+  }
+}
+
+/**
+ * Stop a Solo process, and be honest about which of three things happened: `stopped` (it was alive
+ * and now is not), `already-gone` (Solo has it, but it had already exited — `changed: false`), or
+ * `unknown` (Solo 404s on it, or is not there to ask).
+ *
+ * Verified against the real CLI: stopping an exited process is `{ok: true, changed: false}`, not an
+ * error. Reaping a corpse being a no-op is exactly what lets `crux done` call this unconditionally —
+ * every headless thread's worker is already dead by the time the thread closes.
+ */
+function stopSoloProcess(procId) {
+  const data = soloTry(['processes', 'stop', String(procId)]);
+  if (data === null) return 'unknown';
+  return data.changed === true ? 'stopped' : 'already-gone';
+}
+
+/**
+ * Build the argv for `solo processes spawn` (everything after the literal `solo`).
+ *
+ * HEADLESS rides in as `-p --output-format json --session-id <uuid> "<brief>"`:
+ *
+ *   -p                     print mode — do the work, print the result, exit. THE reaping mechanism.
+ *   --output-format json   the result as one machine-readable object, so the report needs no
+ *                          scraping and a failure is a field rather than a guess.
+ *   --session-id <uuid>    the session id, chosen by US rather than learned afterwards (verified:
+ *                          claude honours it and echoes it back). That is what lets the spawn store
+ *                          a working `claude --resume` handle in the same write that accepts the
+ *                          thread, instead of guessing at the newest jsonl {@see latestSessionId}.
+ *
+ * LIVE rides in as `--remote-control "<name>" -n "<name>" "<brief>"`. Two different flags take the
+ * SAME thread name, and they are not redundant:
+ *
+ *   -n <name>                names the LOCAL session (what `claude --resume` lists on this machine).
+ *   --remote-control <name>  registers the session with claude.ai under that name — this is the one
+ *                            that puts `Thread #<id>: <subject>` on the human's phone, and the one that
+ *                            mints the openable per-session URL {@see remoteControlUrl}.
+ *
+ * `--name` (Solo's process name) is a third, unrelated name. Ordering is the load-bearing part, so
+ * it is unit-tested rather than assembled inline.
+ */
+function spawnArgs({
+  projectId,
+  toolId = 3,
+  id,
+  subject,
+  brief,
+  processName,
+  live = false,
+  sessionId = null,
+  remoteControl = true,
+}) {
+  const sessionName = threadName(id, subject);
+  const claudeArgs = [];
+
+  if (live) {
+    // Remote Control first: it is the flag that makes the agent reachable off this machine.
+    if (remoteControl) claudeArgs.push('--arg', '--remote-control', '--arg', sessionName);
+    claudeArgs.push('--arg', '-n', '--arg', sessionName);
+  } else {
+    claudeArgs.push('--arg', '-p', '--arg', '--output-format', '--arg', 'json');
+    if (sessionId) claudeArgs.push('--arg', '--session-id', '--arg', sessionId);
+  }
+
+  claudeArgs.push('--arg', brief);
+
+  return [
+    'processes',
+    'spawn',
+    '--project-id',
+    String(projectId),
+    '--kind',
+    'agent',
+    '--agent-tool-id',
+    String(toolId),
+    '--name',
+    processName || `thread-${id}`,
+    // Everything below is appended after `claude --dangerously-skip-permissions`.
+    ...claudeArgs,
+  ];
+}
+
+/** Claude's Remote Control session URL, as painted into the TUI: `https://claude.ai/code/session_…`. */
+const REMOTE_CONTROL_URL = /https:\/\/claude\.ai\/code\/session_[A-Za-z0-9_-]+/;
+
+/**
+ * Pull the Remote Control URL out of a raw pty buffer (`solo processes output <id> --raw`).
+ *
+ * There is no machine-readable source for this. Claude announces the session once, as a transient
+ * toast drawn into the TUI — "Remote control is active · Continue here, on your phone, or at
+ * <url>" — and writes it nowhere on disk. So the only way to learn the URL is to read it back off
+ * the terminal the agent is drawing to, which is why this is a regex over pty bytes and not a
+ * lookup. Solo's RAW buffer is an append-only byte log and keeps the toast; its *rendered* rows are
+ * only the current screen, where the toast has long since been overwritten.
+ *
+ * The bytes are ANSI-laden and `\r`-separated, so escape sequences come out first. Returns null when
+ * the toast is not (yet) present — the caller must treat a missing URL as normal, not as failure.
+ */
+function remoteControlUrl(raw) {
+  if (typeof raw !== 'string' || raw === '') return null;
+
+  const clean = raw
+    .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '') // OSC (window titles) — before CSI, they nest.
+    .replace(/\x1b\[[0-9;?>]*[a-zA-Z]/g, '') // CSI (colour, cursor moves)
+    .replace(/\x1b[()][AB012]/g, '') // charset selection
+    .replace(/\x1b[>=]/g, ''); // keypad mode
+
+  const match = clean.match(REMOTE_CONTROL_URL);
+  return match ? match[0] : null;
+}
+
+/**
+ * The one json object `claude -p --output-format json` printed, dug back out of the raw pty buffer.
+ *
+ * Print mode writes its result to stdout and nothing else, so Solo's raw buffer (an append-only byte
+ * log — see {@see remoteControlUrl}) holds that object verbatim: no ANSI, no line-wrapping, no
+ * interleaving. Verified against a real Solo-spawned headless agent rather than assumed, because the
+ * whole report path hangs off it.
+ *
+ * Even so, this parses rather than trusts: it anchors on the object's opening bytes, brace-matches
+ * forward with an awareness of strings (the agent's own `result` text routinely contains `{`, `}`
+ * and escaped quotes), and keeps the LAST object that parses cleanly. A buffer that got truncated,
+ * or a process that died mid-write, therefore yields null — which is not an edge case to be
+ * swallowed but the very signal {@see workerReport} turns into a failure report on the thread.
+ */
+function resultJson(raw) {
+  if (typeof raw !== 'string' || raw === '') return null;
+
+  const ANCHOR = '{"type":"result"';
+  let found = null;
+
+  for (let at = raw.indexOf(ANCHOR); at !== -1; at = raw.indexOf(ANCHOR, at + 1)) {
+    const end = closingBrace(raw, at);
+    if (end === -1) continue;
+    try {
+      found = JSON.parse(raw.slice(at, end + 1));
+    } catch {
+      // Truncated or interleaved — not the object we want. Keep scanning.
+    }
+  }
+
+  return found;
+}
+
+/** The index of the `}` that closes the `{` at `start`, ignoring braces and quotes inside strings. */
+function closingBrace(text, start) {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+
+  for (let i = start; i < text.length; i++) {
+    const char = text[i];
+
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (char === '\\') escaped = true;
+      else if (char === '"') inString = false;
+      continue;
+    }
+
+    if (char === '"') inString = true;
+    else if (char === '{') depth++;
+    else if (char === '}' && --depth === 0) return i;
+  }
+
+  return -1;
+}
+
+/**
+ * What the harness posts to the thread when a headless worker's process is over — the mechanised
+ * half of `WORKER-CONTRACT.md` §1. A run ends in exactly one of three ways, and this decides which.
+ *
+ * REPORTED. A finished worker reports its `result` verbatim: that text was written as the agent's
+ * final message, which the brief told it IS its report {@see workerBrief}, so it needs no reframing.
+ *
+ * DIED. A worker that died reports just as loudly, and that is the point of the whole mechanism.
+ * Every way a run can end without a usable report is enumerated here — no json printed, `is_error`,
+ * a non-zero exit (Solo surfaces it as `failed`; it exposes no exit code, only a status), an empty
+ * result, or a run that outlived the harness's patience — because each one used to look identical
+ * from the thread: nothing. Silence is the bug. A dead worker also `notify`s, since a note nobody is
+ * told about is just a quieter silence.
+ *
+ * CANCELLED. A lead stopping a worker on purpose is INDISTINGUISHABLE from a crash by observation —
+ * process gone, buffer empty — so it is not distinguished by observation. `crux cancel` leaves a
+ * tombstone for this exact worker before it kills it, the supervisor consumes it {@see
+ * ../lib/cancel}, and passes it here as `cancelled`. Only then is silence forgiven, and only for the
+ * ways of dying that a kill actually explains: a `timedOut` run is still RUNNING (the kill never
+ * landed) and a worker that got its report out before the axe fell has genuinely reported, so
+ * neither is rewritten. No tombstone still means crash — that default is the whole #70 guarantee and
+ * is deliberately not flipped.
+ */
+function workerReport({ result, status = null, timedOut = false, cancelled = null }) {
+  const text = typeof result?.result === 'string' ? result.result.trim() : '';
+  const meta = runMeta(result, status);
+
+  let died = null;
+  if (timedOut) {
+    died = `the harness gave up waiting for it (its Solo process is still \`${status}\`)`;
+  } else if (result === null || result === undefined) {
+    died = `it printed no result at all (Solo process \`${status ?? 'unknown'}\`) — it crashed, was killed, or never started`;
+  } else if (result.is_error === true) {
+    died = 'it ended in an error';
+  } else if (status === 'failed') {
+    died = 'it exited non-zero';
+  } else if (text === '') {
+    died = 'it finished but said nothing';
+  }
+
+  if (died === null) {
+    return { ok: true, notify: false, text: `${text}\n\n—\n${meta}` };
+  }
+
+  if (cancelled && !timedOut) {
+    const why = typeof cancelled.note === 'string' && cancelled.note.trim() !== '' ? cancelled.note.trim() : null;
+    const by = typeof cancelled.actor === 'string' && cancelled.actor.trim() !== '' ? cancelled.actor.trim() : 'the lead';
+
+    return {
+      ok: true,
+      cancelled: true,
+      notify: false,
+      text:
+        `**Worker cancelled by ${by}${why ? ` — ${why}` : ''}. Not a crash.**\n\n` +
+        'It was stopped deliberately, so it printed no report; `crux cancel` said so before killing ' +
+        'it. Nothing here failed and nothing needs looking at.' +
+        `${text === '' ? '' : `\n\n${text}`}\n\n—\n${meta}`,
+    };
+  }
+
+  return {
+    ok: false,
+    notify: true,
+    text:
+      `**Worker failed — ${died}.**${text === '' ? '' : `\n\n${text}`}\n\n` +
+      'The agent reported nothing itself; `crux spawn` posted this for it, which is what a worker ' +
+      'dying quietly is supposed to look like now.\n\n' +
+      `—\n${meta}`,
+  };
+}
+
+/** The one-line provenance footer under every report: how the run went, and how to reopen it. */
+function runMeta(result, status) {
+  const bits = [`solo: ${status ?? 'unknown'}`];
+  if (typeof result?.num_turns === 'number') bits.push(`${result.num_turns} turns`);
+  if (typeof result?.total_cost_usd === 'number') bits.push(`$${result.total_cost_usd.toFixed(2)}`);
+  if (typeof result?.session_id === 'string') bits.push(`\`claude --resume ${result.session_id}\``);
+  return bits.join(' · ');
+}
+
+/**
+ * The brief actually handed to a spawned worker: the task, wrapped in the two ways a run is allowed
+ * to end (`WORKER-CONTRACT.md`).
+ *
+ * The wrapper is not a politeness. In headless the agent's final message is *mechanically* lifted
+ * onto the thread {@see workerReport}, so the agent has to know that — an agent that signs off with
+ * "done!" has technically reported and told the human nothing. And an agent that gets stuck must be
+ * told, in the mode where it is true, that there is no one on the other end of its prompt: waiting
+ * silently is not patience, it is death. `crux need` is the only thing that reaches a phone.
+ */
+function workerBrief({ id, task, live = false }) {
+  const ending = live
+    ? 'You are running INTERACTIVELY: the human may open this session and talk to you. Even so, ' +
+      'never sit idle waiting for them to notice you — they are not watching this pane.'
+    : 'You are running HEADLESS: there is no prompt to wait at, no one is watching this process, and ' +
+      'your final message is lifted onto the thread the moment you exit. Raise the block, say in ' +
+      'that final message that you are blocked on it, and exit.';
+
+  return [
+    `You are the worker for Crux thread #${id}.`,
+    '',
+    task,
+    '',
+    '---',
+    `HOW THIS RUN ENDS (enforced by the harness, not by you remembering):`,
+    '',
+    `1. DONE → your FINAL MESSAGE IS YOUR REPORT. When you exit, crux posts it to thread #${id}`,
+    '   automatically. So make the last thing you say a real report: what you did, where the output',
+    '   is (branch, paths, PR links), and what the next person needs to know. "Done!" is not a',
+    '   report. You do not need to — and should not — post it yourself.',
+    '',
+    '2. BLOCKED needing the human (a decision, an approval, a secret, scope, money, anything',
+    '   client-facing or irreversible) → raise a typed block. It is the ONLY thing that reaches their',
+    '   phone; a plain note does not:',
+    '',
+    `       crux need --item ${id} --kind decide|answer|secret|desk|world "<one-line question>"`,
+    '',
+    `   ${ending}`,
+    '',
+    'Those are the only two endings. Do not end any other way.',
+  ].join('\n');
+}
+
+/** The Claude session name for a thread — `Thread #<id>: <subject>`, subject trimmed to one line. */
+function threadName(id, subject) {
+  const oneLine = String(subject || '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 60);
+  return `Thread #${id}: ${oneLine}`.trim();
+}
+
+/**
+ * The local Claude session id created at spawn — the forward-compatible seam for a future deep link
+ * (§7). Claude writes `~/.claude/projects/<encoded-cwd>/<uuid>.jsonl`, encoding the cwd by replacing
+ * every `/` and `.` with `-`. We return the newest uuid in that directory, or null if none is found
+ * (best-effort: a missing seam must never break the spawn).
+ */
+function latestSessionId(cwd, home) {
+  const base = home || os.homedir();
+  const workdir = cwd || process.cwd();
+  const encoded = workdir.replace(/[/.]/g, '-');
+  const dir = path.join(base, '.claude', 'projects', encoded);
+
+  let entries;
+  try {
+    entries = fs.readdirSync(dir).filter((f) => f.endsWith('.jsonl'));
+  } catch {
+    return null;
+  }
+  if (entries.length === 0) return null;
+
+  let newest = null;
+  for (const file of entries) {
+    let mtime = 0;
+    try {
+      mtime = fs.statSync(path.join(dir, file)).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (newest === null || mtime > newest.mtime) {
+      newest = { id: file.replace(/\.jsonl$/, ''), mtime };
+    }
+  }
+  return newest ? newest.id : null;
+}
+
+module.exports = {
+  SOLO_TERMINAL,
+  spawnArgs,
+  threadName,
+  latestSessionId,
+  remoteControlUrl,
+  resultJson,
+  workerReport,
+  workerBrief,
+  soloTry,
+  soloStatus,
+  stopSoloProcess,
+};

package/lib/store.js

@@ -0,0 +1,119 @@
+'use strict';
+
+/**
+ * The shared shape of every small JSON file crux keeps under `~/.config/crux`: a whole-map
+ * read-modify-write, serialised under an exclusive lock and committed by rename.
+ *
+ * Both halves matter, and they were learned separately. Write-then-rename makes a *write* atomic —
+ * no reader ever sees a half-written map. It does not make the *read-modify-write* safe: several
+ * processes share each of these files (seven leads on the tail cursor; a lead and a supervisor on
+ * the cancel tombstones), each reads the whole map, edits one key, and writes it all back. Two of
+ * them interleaving that sequence lose the other's edit — last writer wins.
+ *
+ * So the sequence is serialised: `open(…, 'wx')` fails when the lock exists, which is the atomic
+ * test-and-set, and the read happens INSIDE the lock so that whatever another process committed
+ * while this one was thinking survives. Breaking a stale lock matters as much as taking a fresh
+ * one: without it a single `kill -9` mid-write would wedge every crux process on the machine
+ * forever, and a wedged fleet is the failure we started from.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** A lock older than this belonged to a process killed mid-write, and is broken rather than awaited. */
+const LOCK_STALE_MS = 10_000;
+
+/** Enough to outlast any honest holder (an fs read + write), never enough to wedge a caller. */
+const LOCK_TIMEOUT_MS = 15_000;
+
+/** Sleep without async: these paths are contended for milliseconds and every caller is synchronous. */
+function spinSleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** Run `fn` holding an exclusive lock on `file`. */
+function withFileLock(file, fn) {
+  const lock = `${file}.lock`;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+  let fd;
+  for (;;) {
+    try {
+      fd = fs.openSync(lock, 'wx');
+      break;
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+
+      let age = 0;
+      try {
+        age = Date.now() - fs.statSync(lock).mtimeMs;
+      } catch {
+        continue; // Vanished between open and stat: the holder just released it.
+      }
+
+      if (age > LOCK_STALE_MS) {
+        try {
+          fs.unlinkSync(lock);
+        } catch {
+          /* another process broke it first */
+        }
+        continue;
+      }
+
+      if (Date.now() > deadline) throw new Error(`timed out waiting for ${lock}`);
+      spinSleep(20);
+    }
+  }
+
+  try {
+    return fn();
+  } finally {
+    fs.closeSync(fd);
+    try {
+      fs.unlinkSync(lock);
+    } catch {
+      /* a stale-breaker removed it */
+    }
+  }
+}
+
+/** The file's map, or an empty one — a missing or corrupt file reads as "nothing recorded". */
+function readJson(file) {
+  try {
+    const doc = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return doc && typeof doc === 'object' && !Array.isArray(doc) ? doc : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Edit one key of `file`'s map without clobbering any other's, and return whatever `mutate` returned.
+ *
+ * `mutate` is handed the live map and edits it in place; the commit is a rename, so a crash between
+ * the write and the rename leaves the old map intact rather than a truncated one.
+ */
+function updateJson(file, mutate) {
+  return withFileLock(file, () => {
+    const map = readJson(file);
+    const result = mutate(map);
+
+    const tmp = `${file}.${process.pid}.tmp`;
+    try {
+      fs.writeFileSync(tmp, `${JSON.stringify(map, null, 2)}\n`);
+      fs.renameSync(tmp, file);
+    } catch (e) {
+      try {
+        fs.unlinkSync(tmp);
+      } catch {
+        /* never written */
+      }
+      throw e;
+    }
+
+    return result;
+  });
+}
+
+module.exports = { LOCK_STALE_MS, LOCK_TIMEOUT_MS, withFileLock, readJson, updateJson };

package/lib/swarm-state.js

@@ -0,0 +1,66 @@
+'use strict';
+
+/**
+ * What `crux swarm up` started — the record that makes `up` idempotent and `down` safe.
+ *
+ * Two things need it, and neither can be answered from the process table alone:
+ *
+ *   IDEMPOTENCE. A lead takes a few seconds to get from "process is up" to "tail is running". Inside
+ *   that window the OS says the slug is uncovered, so a second `swarm up` would start a SECOND lead
+ *   — two tails on one stream, racing the shared cursor file and delivering every item twice. A lead
+ *   crux started is therefore remembered the moment it is started, not when its tail appears.
+ *
+ *   OWNERSHIP. `swarm down` stops only what `swarm up` started. The machine may already carry a
+ *   hand-rolled fleet, and a `down` that killed every `crux tail` it could find would
+ *   take out leads crux never started, cannot restart, and was never asked to touch. The state file
+ *   is the only thing that can tell those apart — a process table cannot.
+ *
+ * Same lock + write-then-rename as the tail cursor and the cancel tombstones {@see ./store}: several
+ * crux processes share this file, and a read-modify-write that is not serialised loses edits.
+ */
+
+const os = require('os');
+const path = require('path');
+const { readJson, updateJson } = require('./store');
+
+const STATE_FILE =
+  process.env.CRUX_SWARM_STATE || path.join(os.homedir(), '.config', 'crux', 'swarm.json');
+
+/** Where a generated standing-lead brief is written. One per slug, readable and editable by a human. */
+const BRIEF_DIR =
+  process.env.CRUX_SWARM_BRIEFS || path.join(os.homedir(), '.config', 'crux', 'leads');
+
+function briefPath(slug) {
+  return path.join(BRIEF_DIR, `${slug}.md`);
+}
+
+/** Every lead crux swarm believes it started, keyed by slug. */
+function readState() {
+  return readJson(STATE_FILE);
+}
+
+/** Remember a lead we just started. `ref` is the backend's own handle — a Solo id, a pid, a name. */
+function recordLead(slug, entry) {
+  return updateJson(STATE_FILE, (map) => {
+    map[slug] = { ...entry, slug };
+    return map[slug];
+  });
+}
+
+/**
+ * Forget a lead, under the same lock that reads it.
+ *
+ * Called only after the stop actually succeeded, or after the lead was found already dead. A lead
+ * forgotten while still running would be a lead crux can never stop again — it would fall out of
+ * `down` (not ours) and out of `up` (no tail? start another one), which is the double-tail bug
+ * arriving by a different road.
+ */
+function forgetLead(slug) {
+  return updateJson(STATE_FILE, (map) => {
+    const had = Object.hasOwn(map, slug);
+    delete map[slug];
+    return had;
+  });
+}
+
+module.exports = { BRIEF_DIR, STATE_FILE, briefPath, forgetLead, readState, recordLead };