gaslamp 2.2.3 → 3.0.0

package/src/fleet.mjs

@@ -1,457 +0,0 @@
-// fleet.mjs — fan out a *fleet* of consults from one command.
-//
-//   gaslamp fleet codex -n 8 "review this diff"   8 fresh sessions, same prompt
-//   gaslamp fleet codex - < tasks.jsonl           one task per line (see below)
-//   gaslamp fleet claude --concurrency 4 …        bound the parallelism
-//
-// The fleet is a thin bounded-concurrency runner over the SAME single-consult
-// CLI: it shells out to `gaslamp <backend> --json …` once per task, never
-// reaching into consult.mjs. Each child is exactly today's tested consult — its
-// own job record, its own kill-group, its own resumable session — so a killed
-// fleet costs in-flight turns, not sessions: resume each child by its session.
-//
-// This keeps faith with the 2.0 principle (asynchrony is the harness's job):
-// the harness still backgrounds the whole `gaslamp fleet …` as ONE blocking
-// call and is notified when it finishes. The fleet just does the bounded
-// fan-out the harness would otherwise make you hand-roll across N background
-// tasks. It earns its place chiefly on Codex's behalf — Claude Code has the
-// Workflow tool, Codex has nothing, so `gaslamp fleet claude` is the only way
-// for Codex to fire a fleet of claudes from one command.
-//
-// Two things the fleet does that a single consult does not, both for safety at
-// N: it defaults the consults to `--sandbox read-only` (N write-capable agents
-// in one cwd is a race factory — pass --sandbox to opt into writes), and it
-// refuses a manifest that resumes the same session twice (they'd deadlock on
-// the session lock).
-//
-// Task sources (first that matches wins):
-//   stdin (`-`, or piped with no prompt arg): one task per non-empty line. A
-//     line starting with `{` is a JSON spec
-//     {prompt, model?, sandbox?, cwd?, resume?, label?} (maps 1:1 to a Workflow
-//     agent() call); any other line is a bare prompt. Fleet flags are the
-//     default; a per-task field overrides.
-//   prompt arg + -n N: replicate the prompt across N fresh sessions.
-//   prompt arg alone: a fleet of one (a slow single consult; allowed).
-
-import { spawn } from "node:child_process";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { readFileSync, writeSync } from "node:fs";
-import {
-  createFleet, liveStatus, looksLikeFleetId, newFleetId, readFleetMeta,
-  readManifest, readMeta, readReply, writeFleetMeta,
-} from "./jobs.mjs";
-import { BACKEND_NAMES, isBackend } from "./backends.mjs";
-import { readThread } from "./threads.mjs";
-import { readStdin } from "./stdin.mjs";
-
-const GASLAMP_BIN = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "gaslamp.mjs");
-// Quota-shaped, not CPU-shaped: the bottleneck is API rate limits, not cores
-// (Workflow's min(16, cores-2) is wrong here). Raise it with --concurrency.
-const DEFAULT_CONCURRENCY = 4;
-
-const die = (code, msg) => { writeSync(2, `gaslamp: ${msg}\n`); process.exit(code); };
-const note = (msg) => writeSync(2, `${msg}\n`);
-
-const num = (flag, s) => {
-  const n = Number(s);
-  if (!Number.isInteger(n)) die(2, `${flag} needs an integer, got "${s}"`);
-  return n;
-};
-
-function parseArgs(argv) {
-  const o = { json: false, count: null, concurrency: DEFAULT_CONCURRENCY, prompt: null, stdin: false };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    const val = () => { if (i + 1 >= argv.length) die(2, `${a} needs a value`); return argv[++i]; };
-    if (a === "-n" || a === "--count") o.count = num(a, val());
-    else if (a === "--concurrency" || a === "-j") o.concurrency = num(a, val());
-    else if (a === "--model" || a === "-m") o.model = val();
-    else if (a === "--sandbox" || a === "-s") o.sandbox = val();
-    else if (a === "--effort" || a === "-e") o.effort = val();
-    else if (a === "--cwd" || a === "-C") o.cwd = val();
-    else if (a === "--schema") o.schema = val();
-    else if (a === "--raw") o.raw = true;
-    else if (a === "--json") o.json = true;
-    else if (a === "--stream") o.stream = true;
-    else if (a === "-") o.stdin = true;
-    else if (a.startsWith("-") && a.length > 1) die(2, `unknown flag ${a} (see gaslamp --help)`);
-    else if (o.prompt == null) o.prompt = a;
-    else die(2, "more than one prompt argument — use -n to replicate, or a JSONL manifest on stdin");
-  }
-  if (o.concurrency < 1) die(2, "--concurrency must be >= 1");
-  if (o.count != null && o.count < 1) die(2, "-n must be >= 1");
-  return o;
-}
-
-// Flags + sources → a flat list of normalized specs, then a finalize pass that
-// stamps index + a stable label and rejects the two footguns (duplicate labels;
-// duplicate resume targets, which would deadlock on the session lock).
-function buildTasks(backend, o) {
-  // Default to read-only unless the caller opts into writes (fleet-wide or
-  // per-task). N writers in one cwd race; one consult deferring to config is
-  // fine, N is not.
-  const baseSandbox = o.sandbox ?? "read-only";
-  const norm = (spec, i) => {
-    if (typeof spec === "string") spec = { prompt: spec };
-    if (!spec || typeof spec.prompt !== "string" || !spec.prompt.trim())
-      die(2, `task ${i + 1} has no prompt`);
-    // A manifest `schema` may be an inline JSON object (the natural way to
-    // write it on a JSONL line) — normalize to the string the CLI flag takes.
-    let schema = spec.schema ?? o.schema ?? null;
-    if (schema != null && typeof schema === "object") schema = JSON.stringify(schema);
-    return {
-      prompt: spec.prompt,
-      model: spec.model ?? o.model,
-      sandbox: spec.sandbox ?? baseSandbox,
-      effort: spec.effort ?? o.effort,
-      cwd: spec.cwd ?? o.cwd,
-      resume: spec.resume ?? null,
-      thread: spec.thread ?? null,
-      label: spec.label ?? null,
-      schema,
-      raw: spec.raw ?? o.raw ?? false,
-    };
-  };
-
-  let raw;
-  const stdinRequested = o.stdin || (o.prompt == null && !process.stdin.isTTY);
-  if (stdinRequested) {
-    const lines = readStdin().split("\n").map((l) => l.trim()).filter(Boolean);
-    if (!lines.length) die(2, "no tasks on stdin");
-    raw = lines.map((line, i) => norm(line.startsWith("{") ? parseJsonLine(line, i) : line, i));
-  } else {
-    if (o.prompt == null) die(2, "no tasks — pass a prompt with -n N, or a JSONL manifest on stdin");
-    // Prompt arg + piped stdin: stdin is evidence for every replica, same
-    // <stdin> convention as a single consult (git diff | gaslamp fleet …).
-    let prompt = o.prompt;
-    if (!process.stdin.isTTY) {
-      const evidence = readStdin({ evidence: true });
-      if (evidence.trim())
-        prompt += "\n\n<stdin>\n" + (evidence.endsWith("\n") ? evidence : evidence + "\n") + "</stdin>";
-    }
-    raw = Array.from({ length: o.count ?? 1 }, () => norm({ prompt }, 0));
-  }
-
-  const width = String(raw.length).length;
-  const seenLabel = new Set(), seenResume = new Set(), seenThread = new Set();
-  raw.forEach((t, i) => {
-    t.index = i;
-    if (t.label == null) t.label = `task-${String(i + 1).padStart(width, "0")}`;
-    else if (seenLabel.has(t.label)) die(2, `duplicate task label "${t.label}" — labels must be unique`);
-    seenLabel.add(t.label);
-    if (t.thread) {
-      if (t.resume) die(2, `task ${i + 1} has both thread and resume — a thread IS a resume handle`);
-      if (seenThread.has(t.thread))
-        die(2, `two tasks use the same thread (${t.thread}) — they would deadlock on the session lock (or race to bind it); give each its own thread`);
-      seenThread.add(t.thread);
-      // a BOUND thread is a resume in disguise: feed its session into the
-      // duplicate-resume check so thread-vs-resume collisions are caught too
-      const bound = readThread(backend, t.thread)?.sessionId;
-      if (bound) t._threadSession = bound;
-    }
-    const target = t.resume ?? t._threadSession;
-    if (target) {
-      if (seenResume.has(target))
-        die(2, `two tasks resume the same session (${target}) — they would deadlock on the session lock; give each its own session`);
-      seenResume.add(target);
-    }
-  });
-  return raw;
-}
-
-function parseJsonLine(line, i) {
-  try { return JSON.parse(line); }
-  catch (e) { die(2, `task ${i + 1} is not valid JSON: ${e.message}`); }
-}
-
-// argv for one child `gaslamp <backend> --json …`. Prompt rides on stdin (no
-// argv-size or quoting traps), exactly as a hand-run consult would.
-function childArgs(backend, task) {
-  const args = [GASLAMP_BIN, backend, "--json"];
-  if (task.resume) args.push("--resume", task.resume);
-  if (task.thread) args.push("--thread", task.thread);
-  if (task.model) args.push("--model", task.model);
-  if (task.sandbox) args.push("--sandbox", task.sandbox);
-  if (task.effort) args.push("--effort", task.effort);
-  if (task.cwd) args.push("--cwd", task.cwd);
-  if (task.schema) args.push("--schema", task.schema);
-  if (task.raw) args.push("--raw");
-  // the child records the fleet's label too, so `gaslamp jobs` correlates
-  args.push("--label", task.label, "-");
-  return args;
-}
-
-const tail = (s, n = 6) => (s || "").trim().split("\n").slice(-n).join("\n");
-
-// Spawn one child consult; resolve with an enriched result. Never rejects — a
-// launch/parse failure resolves to a failed result so one bad task can't sink
-// the fleet. `onStart(jobId)` fires the moment the child reports its id (the
-// gated "started" receipt), so the parent record names in-flight children even
-// if the fleet is killed before they finish.
-function runChild(backend, task, live, onStart) {
-  return new Promise((resolve) => {
-    const child = spawn(process.execPath, childArgs(backend, task), {
-      stdio: ["pipe", "pipe", "pipe"], detached: false,
-      // GASLAMP_FLEET makes the child emit the early started receipt. It is NOT
-      // nested (a fleet sits where a hand-run consult sits), so no GASLAMP_NESTED.
-      env: { ...process.env, GASLAMP_FLEET: "1" },
-    });
-    live.add(child);
-
-    let out = "", err = "", buf = "", envelope = null, started = false;
-    child.stdout.on("data", (d) => {
-      out += d;
-      buf += d.toString();
-      let nl;
-      while ((nl = buf.indexOf("\n")) >= 0) {
-        const line = buf.slice(0, nl).trim();
-        buf = buf.slice(nl + 1);
-        if (!line) continue;
-        let j; try { j = JSON.parse(line); } catch { continue; }
-        if (j.type === "started" && !started) { started = true; onStart?.(j.jobId); }
-        else if (j.backend && j.status) envelope = j; // the final consult envelope
-      }
-    });
-    child.stderr.on("data", (d) => { err += d; });
-    child.stdin.on("error", () => {});
-    child.stdin.write(task.prompt);
-    child.stdin.end();
-
-    const fail = (extra) => resolve({
-      index: task.index, label: task.label, jobId: extra.jobId ?? null, sessionId: null,
-      status: "failed", exitCode: null, content: "", error: extra.error, stderrTail: tail(err),
-      startedAt: null, endedAt: null,
-    });
-    child.on("error", (e) => { live.delete(child); fail({ error: e.message }); });
-    child.on("close", () => {
-      live.delete(child);
-      if (!envelope) return fail({ error: tail(err) || "child produced no envelope" });
-      const m = envelope.jobId ? readMeta(envelope.jobId) : null;
-      resolve({
-        index: task.index, label: task.label,
-        jobId: envelope.jobId, sessionId: envelope.sessionId,
-        status: envelope.status, exitCode: envelope.exitCode ?? null,
-        content: envelope.content ?? "", error: envelope.status === "done" ? null : tail(err),
-        stderrTail: envelope.status === "done" ? null : tail(err),
-        startedAt: m?.startedAt ?? null, endedAt: m?.endedAt ?? null,
-        ...("data" in envelope ? { data: envelope.data } : {}),
-        ...(envelope.usage ? { usage: envelope.usage } : {}),
-      });
-    });
-  });
-}
-
-// Bounded worker pool, preserving input order in the results array.
-async function pool(items, limit, worker) {
-  const results = new Array(items.length);
-  let next = 0;
-  const run = async () => {
-    while (true) {
-      const i = next++;
-      if (i >= items.length) return;
-      results[i] = await worker(items[i], i);
-    }
-  };
-  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, run));
-  return results;
-}
-
-// A fleet of consults is still a consult: refuse if nested (a fleet OF fleets
-// is exactly the recursion we guard), and refuse a network-disabled sandbox.
-function guards() {
-  if (process.env.GASLAMP_NESTED && !process.env.GASLAMP_ALLOW_RECURSION)
-    die(3, "this agent is itself a gaslamp consult — a consult is one hop. (GASLAMP_ALLOW_RECURSION=1 opts out.)");
-  if (process.env.CODEX_SANDBOX_NETWORK_DISABLED === "1")
-    die(4, "network is disabled in this sandbox (CODEX_SANDBOX_NETWORK_DISABLED=1) — consulted agents could reach neither Anthropic nor OpenAI. Re-run with network access.");
-}
-
-const tryParse = (s) => { try { return JSON.parse(s); } catch { return null; } };
-
-// One result, machine shape (fleet --json results / --stream result lines).
-const shapeResult = (r) => ({
-  index: r.index, label: r.label, jobId: r.jobId, sessionId: r.sessionId,
-  status: r.status, exitCode: r.exitCode ?? null, content: r.content ?? "",
-  error: r.error ?? null, stderrTail: r.stderrTail ?? null,
-  startedAt: r.startedAt ?? null, endedAt: r.endedAt ?? null,
-  ...(r.replayed ? { replayed: true } : {}),
-  ...("data" in r ? { data: r.data } : {}),
-  ...(r.usage ? { usage: r.usage } : {}),
-});
-
-// One result, human block.
-function renderBlock(backend, r) {
-  const sid = r.sessionId ? ` · ${r.sessionId.slice(0, 8)}` : "";
-  const lines = [`\n━━ [${r.label}] ${r.status}${r.replayed ? " (replayed)" : ""} · ${r.jobId ?? "?"}${sid} ━━`];
-  if (r.content?.trim()) lines.push(r.content.trimEnd());
-  else {
-    lines.push(`(no reply — ${r.status})`);
-    if (r.stderrTail) lines.push(r.stderrTail);
-    if (r.sessionId) lines.push(`resume: gaslamp ${backend} --resume ${r.sessionId}`);
-  }
-  return lines.join("\n");
-}
-
-export async function runFleet(backend, argv) {
-  if (backend === "--resume") return runFleetResume(argv[0] ?? null, argv.slice(1));
-  if (!isBackend(backend))
-    die(2, `fleet needs a backend: gaslamp fleet <${BACKEND_NAMES.join("|")}|--resume fl-…> … (got "${backend ?? ""}")`);
-
-  const o = parseArgs(argv);
-  guards();
-  const tasks = buildTasks(backend, o);
-  await driveFleet(backend, tasks, [], o, null);
-}
-
-// gaslamp fleet --resume <fleet-id> — finish an interrupted fleet, Workflow-
-// resume style: done children replay their recorded replies; a killed child
-// whose session was captured is resumed with a fixed "finish and deliver"
-// nudge (the session already holds the prompt and the partial work); anything
-// else — failed, sessionless, never started — reruns fresh from the stored
-// manifest. A new fleet record is written, pointing back at the old one.
-const RESUME_NUDGE =
-  "The previous consult turn was interrupted mid-flight. Finish the task and deliver the final reply.";
-
-async function runFleetResume(oldId, argv) {
-  const o = parseArgs(argv);
-  if (o.prompt != null || o.count != null || o.stdin)
-    die(2, "fleet --resume takes no prompt or manifest — it reruns the one stored with the fleet");
-  guards();
-  if (!oldId || !looksLikeFleetId(oldId)) die(2, `fleet --resume needs a fleet id (fl-…), got "${oldId ?? ""}"`);
-  const fm = readFleetMeta(oldId);
-  if (!fm) die(2, `no fleet record ${oldId}`);
-  const manifest = readManifest(oldId);
-  if (!manifest || manifest.some((t) => typeof t.prompt !== "string"))
-    die(2, `fleet ${oldId} predates full-prompt manifests — resume its children individually (gaslamp poll ${oldId})`);
-
-  const replayed = [], tasks = [];
-  for (const t of manifest) {
-    const child = (fm.children || [])[t.index];
-    const m = child?.jobId ? readMeta(child.jobId) : null;
-    const status = m ? liveStatus(m) : "missing";
-    if (status === "running")
-      die(2, `fleet ${oldId} still has a running child (${child.jobId}) — wait for it or kill it first`);
-    if (status === "done") {
-      const reply = readReply(m.id) ?? "";
-      replayed.push({
-        index: t.index, label: t.label, jobId: m.id, sessionId: m.sessionId ?? null,
-        status: "done", exitCode: m.exitCode ?? null, content: reply,
-        error: null, stderrTail: null, startedAt: m.startedAt ?? null, endedAt: m.endedAt ?? null,
-        replayed: true,
-        ...(m.usage ? { usage: m.usage } : {}),
-        ...(m.schema ? { data: tryParse(reply) } : {}),
-      });
-    } else if ((status === "killed" || status === "stale") && (m?.sessionId || t.thread)) {
-      // the interrupted turn is lost, the session is not: nudge it to conclude
-      // (threads resume by name so the pointer keeps chasing forked ids)
-      tasks.push({ ...t, prompt: RESUME_NUDGE, resume: t.thread ? null : m.sessionId, nudged: true });
-    } else {
-      tasks.push({ ...t });
-    }
-  }
-  if (!tasks.length) note(`[gaslamp fleet] nothing left to run — all ${replayed.length} children were done; replaying`);
-  await driveFleet(fm.backend, tasks, replayed, o, oldId);
-}
-
-// The engine under both entries: spawn the live tasks, merge in replays,
-// write the new fleet record through, emit results (streamed or collected).
-async function driveFleet(backend, tasks, replayed, o, resumedFrom) {
-  const total = tasks.length + replayed.length;
-  const concurrency = Math.max(1, Math.min(o.concurrency, tasks.length));
-
-  const fleetId = newFleetId();
-  const meta = {
-    id: fleetId, kind: "fleet", backend,
-    tasks: total, concurrency, resumedFrom,
-    sandbox: o.sandbox ?? "read-only (default)",
-    children: [], // [{ index, label, jobId, status }] — filled as they start/finish
-    counts: { done: 0, failed: 0, killed: 0 },
-    status: "running", pid: process.pid,
-    startedAt: new Date().toISOString(), endedAt: null,
-  };
-  for (const r of replayed)
-    meta.children[r.index] = { index: r.index, label: r.label, jobId: r.jobId, sessionId: r.sessionId, status: "done", replayed: true };
-  createFleet(meta, tasks);
-
-  note(`[gaslamp fleet] → ${backend} · ${total} task${total === 1 ? "" : "s"} · concurrency ${concurrency} · fleet ${fleetId}` +
-    (resumedFrom ? ` · resumed from ${resumedFrom} (${replayed.length} replayed)` : ""));
-  if (!o.sandbox && tasks.length && !resumedFrom)
-    note(`[gaslamp fleet] consults run --sandbox read-only by default (N writers in one cwd race); pass --sandbox to change`);
-
-  // ---- signals: forward to live children; each kills its own backend group ----
-  // Children are NOT detached, so they share our group and a terminal SIGINT
-  // reaches them too; we also forward explicitly for a harness signal sent to
-  // our pid alone. Each child's own handler does the graceful backend teardown.
-  const live = new Set();
-  let killedBy = null;
-  const forward = (sig) => { for (const c of live) { try { c.kill(sig); } catch {} } };
-  for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
-    process.on(sig, () => {
-      if (killedBy) return forward("SIGKILL");
-      killedBy = sig;
-      note(`[gaslamp fleet] ${sig} — stopping ${live.size} in-flight consult${live.size === 1 ? "" : "s"}; each session survives, recover with --resume`);
-      forward(sig);
-      setTimeout(() => forward("SIGKILL"), 5000).unref();
-    });
-  }
-
-  // ---- run ------------------------------------------------------------------
-  // --stream prints each result the moment it lands (completion order; replays
-  // first) instead of collecting until the end — the caller's harness can peek
-  // partial output mid-run and start synthesizing early.
-  const emitStream = (r) => {
-    if (o.json) process.stdout.write(JSON.stringify({ type: "result", ...shapeResult(r) }) + "\n");
-    else process.stdout.write(renderBlock(backend, r) + "\n");
-  };
-  if (o.stream) replayed.forEach(emitStream);
-
-  let finished = 0;
-  const liveResults = await pool(tasks, concurrency, async (task) => {
-    const onStart = (jobId) => {
-      meta.children[task.index] = { index: task.index, label: task.label, jobId, status: "running" };
-      writeFleetMeta(meta); // write-through: a killed fleet's record still names its children
-    };
-    const r = await runChild(backend, task, live, onStart);
-    finished++;
-    meta.children[task.index] = { index: task.index, label: r.label, jobId: r.jobId, sessionId: r.sessionId, status: r.status };
-    writeFleetMeta(meta);
-    note(`[gaslamp fleet] ${r.status === "done" ? "✓" : "✗"} ${finished}/${tasks.length} · ${r.jobId ?? "?"} · ${r.label} · ${r.status}`);
-    if (o.stream) emitStream(r);
-    return r;
-  });
-
-  const results = [...replayed, ...liveResults].sort((a, b) => a.index - b.index);
-  for (const r of results) {
-    if (r.status === "done") meta.counts.done++;
-    else if (r.status === "killed") meta.counts.killed++;
-    else meta.counts.failed++;
-  }
-  meta.status = killedBy ? "killed" : meta.counts.done === total ? "done" : "failed";
-  meta.endedAt = new Date().toISOString();
-  writeFleetMeta(meta);
-
-  // ---- output ----------------------------------------------------------------
-  // Collected: manifest order (--json: one object; human: blocks + summary).
-  // Streamed: results already emitted; close with a summary line only
-  // (--json --stream is explicit JSONL — result lines, then fleet.done).
-  if (o.json) {
-    if (o.stream) {
-      process.stdout.write(JSON.stringify({ type: "fleet.done", fleetId, backend, tasks: total, counts: meta.counts }) + "\n");
-    } else {
-      process.stdout.write(JSON.stringify({
-        fleetId, backend, tasks: total, counts: meta.counts,
-        ...(resumedFrom ? { resumedFrom } : {}),
-        results: results.map(shapeResult),
-      }) + "\n");
-    }
-  } else {
-    const out = o.stream ? [] : results.map((r) => renderBlock(backend, r));
-    out.push(`\n[gaslamp fleet] ${fleetId} · ${meta.counts.done}/${total} done` +
-      (meta.counts.failed ? ` · ${meta.counts.failed} failed` : "") +
-      (meta.counts.killed ? ` · ${meta.counts.killed} killed` : "") +
-      ` · poll: gaslamp poll ${fleetId}`);
-    process.stdout.write(out.join("\n") + "\n");
-  }
-
-  process.exitCode = meta.status === "done" ? 0 : 1;
-}

package/src/tail.mjs

@@ -1,104 +0,0 @@
-// tail.mjs — gaslamp tail <job|--last>: render a consult's event stream as
-// uniform one-line entries, following while the job runs.
-//
-// A flashlight, not an event UI: raw events.jsonl is write-through but
-// backend-shaped (claude stream-json — which grok's streaming-messages-json
-// mirrors — vs codex --json vs agy stream-json); this normalizes them all
-// into "what is it doing right now" lines and nothing more. `poll`, `jobs`,
-// and the durable records stay the product surface.
-
-import { readFileSync, writeSync } from "node:fs";
-import { join } from "node:path";
-import { jobDir, jobsDir, listJobIds, liveStatus, looksLikeFleetId, looksLikeJobId, readMeta, renderTrailer } from "./jobs.mjs";
-
-const die = (code, msg) => { writeSync(2, `gaslamp: ${msg}\n`); process.exit(code); };
-
-const short = (s) => String(s ?? "?").slice(0, 8);
-const preview = (v, n = 100) => {
-  const s = (typeof v === "string" ? v : v == null ? "" : JSON.stringify(v)).replace(/\s+/g, " ").trim();
-  return s.length > n ? s.slice(0, n - 1) + "…" : s;
-};
-
-// One event → one line (or several, or none — noise is dropped).
-function renderEvent(backend, j) {
-  if (backend === "gemini") {
-    if (j.event === "init")
-      return [`init · conversation ${short(j.conversation_id)}${j.init?.model ? ` · ${j.init.model}` : ""}`];
-    const st = j.step_update;
-    if (st?.step_type === "tool" && st.state === "DONE")
-      return [`tool → ${st.tool_name ?? "?"} ${preview(st.tool_info?.parameters, 80)}`];
-    if (j.event === "result")
-      return [`result · ${j.result?.status ?? "?"}${j.result?.error ? ` · ${preview(j.result.error, 80)}` : ""}`];
-    return []; // text deltas, step bookkeeping
-  }
-  if (backend === "claude" || backend === "grok") {
-    if (j.type === "system" && j.subtype === "init")
-      return [`init · session ${short(j.session_id)}${j.model ? ` · ${j.model}` : ""}`];
-    if (j.type === "assistant" || j.type === "user") {
-      const lines = [];
-      for (const p of j.message?.content ?? []) {
-        if (p.type === "tool_use" || p.type === "server_tool_use") lines.push(`tool → ${p.name} ${preview(p.input, 80)}`);
-        else if (p.type === "text" && p.text?.trim()) lines.push(`text · ${preview(p.text)}`);
-        else if (p.type === "tool_result") lines.push(`tool ← ${preview(p.content, 80)}`);
-      }
-      return lines;
-    }
-    if (j.type === "result")
-      return [`result · ${j.is_error ? "error" : "ok"}${j.total_cost_usd != null ? ` · $${j.total_cost_usd.toFixed(2)}` : ""}`];
-    return []; // rate limits, hook responses, stream noise
-  }
-  // codex
-  if (j.type === "thread.started") return [`init · thread ${short(j.thread_id ?? j.threadId)}`];
-  if (j.type === "turn.completed")
-    return [`turn done${j.usage ? ` · tok ${j.usage.input_tokens ?? 0}→${j.usage.output_tokens ?? 0}` : ""}`];
-  if (j.type === "item.completed") {
-    const it = j.item ?? {};
-    const t = it.type ?? it.item_type;
-    if (t === "agent_message") return [`text · ${preview(it.text)}`];
-    if (t === "reasoning") return [`reasoning · ${preview(it.text ?? it.summary ?? "")}`];
-    if (t === "command_execution")
-      return [`tool → ${preview(it.command, 80)}${it.exit_code != null ? ` (exit ${it.exit_code})` : ""}`];
-    return t ? [String(t)] : [];
-  }
-  return [];
-}
-
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-
-export async function runTail(argv = []) {
-  let id = argv.find((a) => !a.startsWith("-"));
-  if (!id || argv.includes("--last")) id = listJobIds()[0];
-  if (!id) die(2, `tail: no jobs under ${jobsDir()}`);
-  if (looksLikeFleetId(id)) die(2, "tail follows one consult — point it at a child job id (gaslamp poll <fleet-id> lists them)");
-  if (!looksLikeJobId(id)) die(2, `tail: "${id}" is not a job id`);
-  const m0 = readMeta(id);
-  if (!m0) die(2, `tail: no job record ${id}`);
-
-  const path = join(jobDir(id), "events.jsonl");
-  let seen = 0; // chars consumed; events files are small — reread is fine
-  const drain = (backend) => {
-    let text = "";
-    try { text = readFileSync(path, "utf8"); } catch { return; }
-    const fresh = text.slice(seen);
-    const complete = fresh.lastIndexOf("\n");
-    if (complete < 0) return;
-    seen += complete + 1;
-    for (const line of fresh.slice(0, complete).split("\n")) {
-      if (!line.trim()) continue;
-      let j; try { j = JSON.parse(line); } catch { continue; }
-      for (const out of renderEvent(backend, j)) process.stdout.write(out + "\n");
-    }
-  };
-
-  let meta = m0, status = liveStatus(m0);
-  drain(meta.backend);
-  while (status === "running") {
-    await sleep(400);
-    meta = readMeta(id) ?? meta;
-    status = liveStatus(meta);
-    drain(meta.backend);
-  }
-  drain(meta.backend); // final flush after the record settled
-  process.stdout.write(renderTrailer(meta, status) + "\n");
-  process.exitCode = status === "done" ? 0 : 1;
-}