gaslamp 1.1.0 → 2.1.0

package/src/jobs.mjs

@@ -0,0 +1,273 @@
+// jobs.mjs — durable consult records, plus the `jobs` / `poll` readers.
+//
+// Every consult writes through to a job dir as it runs:
+//
+//   $GASLAMP_HOME/jobs/<id>/
+//     meta.json      backend, status, sessionId, pids, timing, exit
+//     prompt.md      the prompt as sent
+//     events.jsonl   raw backend event stream (claude stream-json / codex --json)
+//     reply.md       final reply text
+//     stderr.log     backend stderr
+//
+// The record is passive durability, not a daemon: the blocking `gaslamp
+// <backend>` process is the only process. If the caller's harness kills it,
+// the record still holds the session id (captured early, the moment the
+// backend reports it) — recovery is `--resume`, not orphaned children.
+
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const HOME = () => process.env.GASLAMP_HOME || join(homedir(), ".gaslamp");
+export const jobsDir = () => join(HOME(), "jobs");
+export const locksDir = () => join(HOME(), "locks");
+export const jobDir = (id) => join(jobsDir(), id);
+
+// `kill(pid, 0)` probes liveness without signaling; EPERM means alive-but-not-ours.
+export const alive = (pid) => {
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return e.code === "EPERM"; }
+};
+
+// Ids embed a local timestamp, so they sort chronologically and read at a
+// glance: cl-20260612-141233-9af2 (claude), cx-… (codex), fl-… (fleet).
+function stampAndRand() {
+  const d = new Date();
+  const p = (n) => String(n).padStart(2, "0");
+  const stamp = `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+  const rand = Math.random().toString(16).slice(2, 6).padEnd(4, "0");
+  return `${stamp}-${rand}`;
+}
+
+export const newJobId = (backend) => `${backend === "claude" ? "cl" : "cx"}-${stampAndRand()}`;
+export const newFleetId = () => `fl-${stampAndRand()}`;
+
+export const looksLikeJobId = (s) => /^(cl|cx)-\d{8}-\d{6}-[0-9a-f]{4}$/.test(String(s));
+export const looksLikeFleetId = (s) => /^fl-\d{8}-\d{6}-[0-9a-f]{4}$/.test(String(s));
+
+// A fleet record lives alongside the consult records under jobs/, but it is
+// grouping metadata only — never the authority on a child's state (a killed
+// parent leaves it stale). `poll <fleet-id>` recomputes from the child records.
+export const fleetDir = (id) => join(jobsDir(), id);
+export function writeFleetMeta(meta) {
+  writeFileSync(join(fleetDir(meta.id), "meta.json"), JSON.stringify(meta, null, 2) + "\n");
+}
+export function readFleetMeta(id) {
+  try { return JSON.parse(readFileSync(join(fleetDir(id), "meta.json"), "utf8")); }
+  catch { return null; }
+}
+// The manifest stores each task IN FULL (prompt included): it is what makes a
+// fleet resumable — a never-started child can only rerun from the record.
+export function createFleet(meta, tasks) {
+  mkdirSync(fleetDir(meta.id), { recursive: true });
+  writeFileSync(join(fleetDir(meta.id), "manifest.jsonl"),
+    tasks.map((t) => JSON.stringify({
+      index: t.index, label: t.label, prompt: t.prompt,
+      model: t.model ?? null, sandbox: t.sandbox ?? null, cwd: t.cwd ?? null,
+      resume: t.resume ?? null, thread: t.thread ?? null, effort: t.effort ?? null,
+      schema: t.schema ?? null, raw: t.raw ?? false,
+    })).join("\n") + (tasks.length ? "\n" : ""));
+  writeFleetMeta(meta);
+}
+
+export function readManifest(id) {
+  try {
+    return readFileSync(join(fleetDir(id), "manifest.jsonl"), "utf8")
+      .split("\n").filter(Boolean).map((l) => JSON.parse(l));
+  } catch { return null; }
+}
+
+export function readMeta(id) {
+  try { return JSON.parse(readFileSync(join(jobDir(id), "meta.json"), "utf8")); }
+  catch { return null; }
+}
+
+export function writeMeta(meta) {
+  writeFileSync(join(jobDir(meta.id), "meta.json"), JSON.stringify(meta, null, 2) + "\n");
+}
+
+export function createJob(meta, prompt) {
+  mkdirSync(jobDir(meta.id), { recursive: true });
+  writeFileSync(join(jobDir(meta.id), "prompt.md"), prompt);
+  writeMeta(meta);
+}
+
+export function readReply(id) {
+  try { return readFileSync(join(jobDir(id), "reply.md"), "utf8"); }
+  catch { return null; }
+}
+
+// Newest first. The timestamp follows the 2-char backend prefix, so compare
+// past it — pure lexical order would interleave cl-/cx- wrongly.
+export function listJobIds() {
+  let ids;
+  try { ids = readdirSync(jobsDir()); } catch { return []; }
+  return ids.filter(looksLikeJobId).sort((a, b) => b.slice(3).localeCompare(a.slice(3)));
+}
+
+// A meta that says "running" is only as honest as its pid: if the wrapper was
+// SIGKILLed (harness teardown), nothing finalized the record. Report `stale`
+// rather than lying about liveness.
+export function liveStatus(meta) {
+  if (meta.status !== "running") return meta.status;
+  return meta.pid && alive(meta.pid) ? "running" : "stale";
+}
+
+const fmtTok = (n) => n >= 10000 ? `${Math.round(n / 1000)}k` : n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n);
+const fmtUsage = (u) =>
+  `tok: ${fmtTok(u.inputTokens ?? 0)}→${fmtTok(u.outputTokens ?? 0)}` +
+  (u.costUsd != null ? ` · $${u.costUsd.toFixed(2)}` : "");
+
+// The one-line, greppable record of a consult — printed after every reply and
+// by `poll`. Always carries the two handles that matter: job id and session id.
+export function renderTrailer(meta, status = meta.status) {
+  const dir = jobDir(meta.id);
+  const bits = [];
+  if (status === "running") {
+    bits.push("RUNNING", `job: ${meta.id}`, `watch: tail -f ${join(dir, "events.jsonl")}`);
+  } else {
+    if (status === "failed") bits.push(`FAILED${meta.exitCode != null ? ` (exit ${meta.exitCode})` : ""}`);
+    if (status === "killed") bits.push(`KILLED${meta.signal ? ` (${meta.signal})` : ""}`);
+    if (status === "stale") bits.push("STALE (wrapper died mid-run)");
+    bits.push(`job: ${meta.id}`, `session: ${meta.sessionId ?? "?"}`);
+    if (meta.thread) bits.push(`thread: ${meta.thread}`);
+    // a thread pointer chases the freshest session id; prefer it as the handle
+    if (meta.sessionId) bits.push(`resume: gaslamp ${meta.backend} ${meta.thread ? `--thread ${meta.thread}` : `--resume ${meta.sessionId}`}`);
+    if (meta.usage) bits.push(fmtUsage(meta.usage));
+    if (status !== "done") bits.push(`log: ${join(dir, "stderr.log")}`);
+  }
+  return `[gaslamp] ${bits.join(" · ")}`;
+}
+
+function promptPreview(id, n = 44) {
+  try {
+    const line = readFileSync(join(jobDir(id), "prompt.md"), "utf8")
+      .split("\n").find((l) => l.trim()) || "";
+    const s = line.trim();
+    return s.length > n ? s.slice(0, n - 1) + "…" : s;
+  } catch { return ""; }
+}
+
+function fmtDur(ms) {
+  const s = Math.max(0, Math.round(ms / 1000));
+  return s < 100 ? `${s}s` : `${Math.floor(s / 60)}m${String(s % 60).padStart(2, "0")}s`;
+}
+
+// gaslamp jobs [-n N] [--json] — newest first, one line per consult.
+export function runJobs(argv = []) {
+  let n = 20;
+  const i = argv.indexOf("-n");
+  if (i >= 0) n = Number(argv[i + 1]) || n;
+  const ids = listJobIds().slice(0, n);
+  if (argv.includes("--json")) {
+    const list = ids.map((id) => {
+      const m = readMeta(id);
+      return m && {
+        jobId: m.id, backend: m.backend, status: liveStatus(m), sessionId: m.sessionId ?? null,
+        label: m.label ?? null, thread: m.thread ?? null,
+        startedAt: m.startedAt ?? null, endedAt: m.endedAt ?? null,
+        usage: m.usage ?? null, promptPreview: promptPreview(id, 80),
+      };
+    }).filter(Boolean);
+    process.stdout.write(JSON.stringify(list) + "\n");
+    return;
+  }
+  if (!ids.length) { console.log(`no jobs yet under ${jobsDir()}`); return; }
+  for (const id of ids) {
+    const m = readMeta(id);
+    if (!m) continue;
+    const status = liveStatus(m);
+    const dur = m.endedAt
+      ? fmtDur(new Date(m.endedAt) - new Date(m.startedAt))
+      : fmtDur(Date.now() - new Date(m.startedAt)) + (status === "running" ? "…" : "");
+    const tags = (m.label ? `[${m.label}] ` : "") + (m.thread ? `@${m.thread} ` : "");
+    console.log([
+      id.padEnd(23),
+      status.padEnd(8),
+      (m.sessionId ?? "-").slice(0, 8).padEnd(9),
+      dur.padStart(8),
+      ` ${tags}${promptPreview(id)}`,
+    ].join(" "));
+  }
+}
+
+// gaslamp poll <job|fleet|--last> [--json] — print one record's reply/status.
+// Exit: 0 done · 1 failed/killed/stale · 2 usage · 10 still running.
+export function runPoll(argv = []) {
+  const json = argv.includes("--json");
+  let id = argv.find((a) => !a.startsWith("-"));
+  if (!id || argv.includes("--last")) id = listJobIds()[0];
+  if (!id) { console.error(`gaslamp poll: no jobs under ${jobsDir()}`); process.exitCode = 2; return; }
+  if (looksLikeFleetId(id)) return pollFleet(id, json);
+  const m = readMeta(id);
+  if (!m) { console.error(`gaslamp poll: no job record ${id}`); process.exitCode = 2; return; }
+  const status = liveStatus(m);
+  const reply = status === "running" ? null : readReply(id);
+  if (json) {
+    // The consult envelope shape, recomputed from the record.
+    let data = null;
+    if (m.schema && reply != null) { try { data = JSON.parse(reply); } catch {} }
+    process.stdout.write(JSON.stringify({
+      backend: m.backend, jobId: m.id, sessionId: m.sessionId ?? null, status,
+      exitCode: m.exitCode ?? null, content: reply ?? "",
+      ...(m.label ? { label: m.label } : {}),
+      ...(m.thread ? { thread: m.thread } : {}),
+      ...(m.usage ? { usage: m.usage } : {}),
+      ...(m.schema ? { data } : {}),
+    }) + "\n");
+    process.exitCode = status === "running" ? 10 : status === "done" ? 0 : 1;
+    return;
+  }
+  if (status === "running") { console.log(renderTrailer(m, status)); process.exitCode = 10; return; }
+  if (reply) process.stdout.write(reply.endsWith("\n") ? reply : reply + "\n");
+  console.log(renderTrailer(m, status));
+  process.exitCode = status === "done" ? 0 : 1;
+}
+
+// gaslamp poll <fleet-id> — recompute every child's state from its own record
+// (the fleet meta is grouping, not authority) and print each reply.
+// Exit: 0 all done · 1 some failed/killed · 2 usage · 10 some still running.
+function pollFleet(id, json = false) {
+  const fm = readFleetMeta(id);
+  if (!fm) { console.error(`gaslamp poll: no fleet record ${id} under ${jobsDir()}`); process.exitCode = 2; return; }
+  const children = (fm.children || []).filter((c) => c && c.jobId);
+  let running = 0, done = 0, other = 0;
+  const out = [], results = [];
+  for (const c of children) {
+    const m = readMeta(c.jobId);
+    const status = m ? liveStatus(m) : "missing";
+    if (status === "running") running++;
+    else if (status === "done") done++;
+    else other++;
+    const reply = status === "done" ? readReply(c.jobId) : null;
+    if (json) {
+      let data = null;
+      if (m?.schema && reply != null) { try { data = JSON.parse(reply); } catch {} }
+      results.push({
+        index: c.index, label: c.label ?? null, jobId: c.jobId,
+        sessionId: m?.sessionId ?? null, status, content: reply ?? "",
+        ...(m?.usage ? { usage: m.usage } : {}),
+        ...(m?.schema ? { data } : {}),
+      });
+      continue;
+    }
+    const sid = m?.sessionId ? ` · ${m.sessionId.slice(0, 8)}` : "";
+    out.push(`\n━━ [${c.label ?? c.index}] ${status} · ${c.jobId}${sid} ━━`);
+    if (reply?.trim()) out.push(reply.trimEnd());
+    else if (status !== "running") {
+      out.push(`(no reply — ${status})`);
+      if (m?.sessionId) out.push(`resume: gaslamp ${m.backend} --resume ${m.sessionId}`);
+    }
+  }
+  if (json) {
+    process.stdout.write(JSON.stringify({
+      fleetId: id, backend: fm.backend,
+      counts: { done, running, other }, results,
+    }) + "\n");
+  } else {
+    if (out.length) process.stdout.write(out.join("\n") + "\n");
+    console.log(`[gaslamp fleet] ${id} · ${fm.backend} · ${done}/${children.length} done` +
+      (running ? ` · ${running} running` : "") + (other ? ` · ${other} failed/killed` : ""));
+  }
+  process.exitCode = running ? 10 : (children.length && done === children.length) ? 0 : 1;
+}

package/src/setup.mjs

@@ -1,128 +1,153 @@
-// setup.mjs — register both consultation channels under the name `gaslamp`.
+// setup.mjs — allowlist the gaslamp CLI for Claude Code; optionally install
+// the gaslamp skill for both agents.
 //
-// Two directions:
-//   Codex → Claude : Codex gets a `gaslamp` tool that hands off to this server.
-//   Claude → Codex : Claude gets Codex's native `codex mcp-server` (its `codex`
-//                    / `codex-reply` tools), registered as `gaslamp`.
+// gaslamp has no MCP servers and nothing to register. Base setup does one
+// thing: allowlist the command in ~/.claude/settings.json so a consult doesn't
+// stall on a permission prompt mid-call. (Codex needs no analog — shell
+// commands are governed by approval_policy.)
 //
-// Idempotent: removes prior registrations (including the legacy `claude` /
-// `codex` names) before re-adding.
+// It does NOT touch your agent instructions. A CLI can't self-advertise the way
+// MCP tools did, so each agent needs a one-line note in its instructions to know
+// gaslamp exists — but appending to your personal CLAUDE.md / AGENTS.md is yours
+// to do (the README has the text to paste), not a surprise setup springs.
 //
-//   gaslamp setup            register the published package (Codex spawns
-//                            `npx -y gaslamp serve`). Survives node upgrades —
-//                            no absolute, version-pinned paths.
-//   gaslamp setup --local    register THIS checkout (Codex spawns
-//                            `<node> <abs>/bin/gaslamp.mjs serve`). Use before
-//                            the package is published, or for from-source dev.
-
-import { spawnSync } from "node:child_process";
-import { readFileSync, writeFileSync } from "node:fs";
+// --skill is the opt-in richer alternative: both CLIs speak the same SKILL.md
+// standard (~/.claude/skills/, $CODEX_HOME/skills/), so one flag installs a
+// direction-aware skill on each side — Claude's copy teaches consulting Codex,
+// Codex's copy teaches consulting Claude. It only ever writes gaslamp's OWN
+// skill directory, so reruns are idempotent overwrites of our own file.
+//
+//   gaslamp setup            published install (`gaslamp` on PATH)
+//   gaslamp setup --local    THIS checkout (absolute bin path; from-source dev)
+//   gaslamp setup --skill    also install the gaslamp skill for both agents
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { which } from "./which.mjs";
 
-function run(label, cmd, args) {
-  process.stdout.write(`  ${label}: ${cmd} ${args.join(" ")}\n`);
-  const r = spawnSync(cmd, args, { stdio: "inherit" });
-  return r.status === 0;
+// Add an entry to permissions.allow in a settings.json text. Returns the new
+// text, or null if the existing text isn't valid JSON (never clobber).
+export function addAllow(text, entry) {
+  let obj = {};
+  if (text && text.trim()) {
+    try { obj = JSON.parse(text); } catch { return null; }
+  }
+  obj.permissions ??= {};
+  obj.permissions.allow ??= [];
+  if (!obj.permissions.allow.includes(entry)) obj.permissions.allow.push(entry);
+  return JSON.stringify(obj, null, 2) + "\n";
 }
 
-// `codex mcp add` cannot persist per-server timeouts (its `-c` flag is a runtime
-// override that never lands in the block), so we patch ~/.codex/config.toml
-// directly. Without this, Codex's MCP client kills any tools/call that runs past
-// its default tool_timeout_sec — a substantial consult (30-45 min) dies with
-// `timed out awaiting tools/call after 120s` while the gaslamp child keeps
-// working, orphaned. The server itself has no timeout; this is the client side.
-// Idempotent: sets the keys in-place if present, inserts them if not.
-function patchCodexTimeouts() {
-  const tool = process.env.GASLAMP_TOOL_TIMEOUT_SEC || "100000"; // ~27.8h — matches Claude Code's own default MCP tool timeout (1e8 ms), so both directions are symmetric
-  const startup = process.env.GASLAMP_STARTUP_TIMEOUT_SEC || "30"; // headroom for npx cold-start
-  const cfgPath = join(process.env.CODEX_HOME || join(homedir(), ".codex"), "config.toml");
-
-  let text;
-  try { text = readFileSync(cfgPath, "utf8"); }
-  catch { console.warn(`  (could not read ${cfgPath}; skipped timeout patch)`); return; }
-
-  const lines = text.split("\n");
-  const header = lines.findIndex((l) => l.trim() === "[mcp_servers.gaslamp]");
-  if (header < 0) { console.warn("  (no [mcp_servers.gaslamp] block found; skipped timeout patch)"); return; }
-
-  // Block runs from the header to the next table header (line starting with `[`).
-  let end = lines.length;
-  for (let i = header + 1; i < lines.length; i++) { if (/^\s*\[/.test(lines[i])) { end = i; break; } }
-  const block = lines.slice(header, end);
-
-  const setKey = (key, val) => {
-    const i = block.findIndex((l) => new RegExp(`^\\s*${key}\\s*=`).test(l));
-    if (i >= 0) { block[i] = `${key} = ${val}`; return; }
-    let at = block.length;                       // insert before trailing blank lines
-    while (at > 1 && block[at - 1].trim() === "") at--;
-    block.splice(at, 0, `${key} = ${val}`);
-  };
-  setKey("tool_timeout_sec", tool);
-  setKey("startup_timeout_sec", startup);
-
-  writeFileSync(cfgPath, [...lines.slice(0, header), ...block, ...lines.slice(end)].join("\n"));
-  process.stdout.write(`  timeouts: tool_timeout_sec=${tool}s startup_timeout_sec=${startup}s in ${cfgPath}\n`);
+// The skill text, parameterized by which agent is reading it: `other` is the
+// backend this copy teaches its reader to consult.
+export function skillMd(other) {
+  const Other = other === "codex" ? "Codex" : "Claude";
+  const backgroundHint = other === "codex"
+    ? "Run a consult as a background shell task (`run_in_background`) and keep working — the reply lands when it finishes, and several can run in parallel."
+    : "Run a consult in your background terminal and check back between steps — several can run in parallel.";
+  return `---
+name: gaslamp
+description: Consult ${Other} (the other coding agent) from the shell for a second pair of eyes — verify a fix or proof, spar on a design, review a diff, diagnose with fresh context — or fan out a fleet of parallel consults. Use when work would benefit from an independent take, when a claim deserves adversarial checking before you rely on it, or when explicitly asked to consult ${Other} / get a second opinion / hand work off.
+---
+
+# Consulting ${Other} via gaslamp
+
+One blocking consult:
+
+    gaslamp ${other} "<prompt>"
+    gaslamp ${other} - < notes.md                       # whole prompt from a file
+    git diff | gaslamp ${other} "review for races:"     # prompt + piped evidence
+
+${backgroundHint} A consult is one hop — the consulted agent cannot consult back — so you own the synthesis.
+
+## Evidence beats framing
+
+Send raw evidence: errors, diffs, failing output, actual constraints — not just your reading of them. Piped stdin rides along as a \`<stdin>\` block. Framing-only prompts make ${Other} inherit your blind spots; the fresh-context advantage works on facts.
+
+## Multi-turn: threads
+
+    gaslamp ${other} --thread api-spar "opening take: ..."
+    gaslamp ${other} --thread api-spar "counterpoint: ..."   # same session, continued
+    gaslamp threads                                          # list named threads
+
+A thread is continue-if-exists-else-start. Prefer threads over raw \`--resume\` for any conversation you might come back to — the name stays valid even as session ids churn.
+
+## Typed replies: --schema
+
+    gaslamp ${other} --json --schema '{"type":"object","properties":{"verdict":{"type":"string","enum":["correct","broken","unsure"]},"reasons":{"type":"array","items":{"type":"string"}}},"required":["verdict","reasons"]}' "Is this fix correct? ..."
+
+The \`--json\` envelope then carries \`data\` (the parsed object). A reply that fails to parse marks the consult failed — trust the exit code. \`--schema\` also takes a file path.
+
+## Fleets: parallel fan-out
+
+    gaslamp fleet ${other} -n 5 "spot the worst bug: ..."    # 5 independent takes; you vote
+    gaslamp fleet ${other} - < tasks.jsonl                   # per line: {"prompt", model?, sandbox?, effort?, schema?, thread?, label?, raw?}
+    gaslamp fleet ${other} -n 4 --stream --json "..."        # JSONL, replies as they land
+    gaslamp fleet --resume <fleet-id>                        # finish an interrupted fleet
+
+Fleets default to \`--sandbox read-only\` (N writers in one cwd race) — pass \`--sandbox\` to opt into writes. Duplicate resume/thread targets are refused up front.
+
+## Reading the records
+
+    gaslamp jobs [--json]                 # recent consults: status, label, thread, tokens
+    gaslamp poll <job|--last> [--json]    # one reply; exit 10 = still running
+    gaslamp tail <job|--last>             # follow a running consult's events live
+
+Every consult writes through to ~/.gaslamp/jobs/<id>/ and its session is recorded within seconds — a killed consult costs the in-flight turn, not the session. Recover with \`--resume <session|job>\` or the thread name.
+
+## Knobs
+
+\`--model\`, \`--effort\`, \`--sandbox\` (omit to use ${Other}'s own config), \`--label\` (tags the job record), \`--raw\` (drop the consult preamble), \`--cwd\`. Exit codes: 0 ok, 1 failed/killed, 2 usage, 3 nested (one-hop), 4 no network, 5 session busy.
+`;
 }
 
-// Quietly remove an existing registration (ignore "not found" noise).
-function remove(cli, name, scopeArgs = []) {
-  spawnSync(cli, ["mcp", "remove", name, ...scopeArgs], { stdio: "ignore" });
+// Install the skill for both agents. Both CLIs read the same SKILL.md format;
+// each side gets the copy pointing at the OTHER backend.
+export function installSkills() {
+  const targets = [
+    { dir: join(homedir(), ".claude", "skills", "gaslamp"), other: "codex" },
+    { dir: join(process.env.CODEX_HOME || join(homedir(), ".codex"), "skills", "gaslamp"), other: "claude" },
+  ];
+  return targets.map(({ dir, other }) => {
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, "SKILL.md");
+    writeFileSync(path, skillMd(other));
+    return path;
+  });
 }
 
 export function runSetup(argv = []) {
   const local = argv.includes("--local") || argv.includes("-l");
+  const skill = argv.includes("--skill");
+  if (!which("claude")) console.warn("setup: `claude` not on PATH — `gaslamp claude` consults will fail until it is (or set CLAUDE_BIN).");
+  if (!which("codex")) console.warn("setup: `codex` not on PATH — `gaslamp codex` consults will fail until it is (or set CODEX_BIN).");
 
-  const codex = which("codex");
-  const claude = which("claude");
-  if (!codex) { console.error("setup: `codex` not found on PATH. Install Codex first."); process.exitCode = 1; return; }
-  if (!claude) { console.error("setup: `claude` not found on PATH. Install Claude Code first."); process.exitCode = 1; return; }
-  if (!local && !which("npx")) {
-    console.error("setup: `npx` not found on PATH — the published registration spawns `npx -y gaslamp serve`.");
-    console.error("       Install Node's npm/npx, or use `gaslamp setup --local` to register this checkout instead.");
-    process.exitCode = 1; return;
-  }
+  const cmd = local
+    ? resolve(join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "gaslamp.mjs"))
+    : "gaslamp";
+  console.log(`mode: ${local ? `local checkout (${cmd})` : "published (`gaslamp` on PATH)"}\n`);
 
-  console.log(`codex: ${codex}`);
-  console.log(`claude: ${claude}`);
-  console.log(`mode:  ${local ? "local checkout" : "published (npx)"}\n`);
-
-  // --- Codex -> Claude: codex gets a `gaslamp` tool that hands off to Claude ---
-  remove("codex", "gaslamp");
-  remove("codex", "claude"); // legacy name
-  let serveCmd;
-  if (local) {
-    const node = which("node") || process.execPath;
-    const shim = resolve(join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "gaslamp.mjs"));
-    serveCmd = ["mcp", "add", "gaslamp", "--", node, shim, "serve"];
+  const settingsPath = join(homedir(), ".claude", "settings.json");
+  const entry = `Bash(${cmd}:*)`;
+  const next = addAllow(existsSync(settingsPath) ? readFileSync(settingsPath, "utf8") : "", entry);
+  if (next == null) {
+    console.warn(`  ! ${settingsPath} is not valid JSON — add ${entry} to permissions.allow yourself`);
   } else {
-    // Bare `npx` (not an absolute path) so whatever node is active resolves the
-    // latest published gaslamp at spawn time — survives nvm/node upgrades.
-    serveCmd = ["mcp", "add", "gaslamp", "--", "npx", "-y", "gaslamp", "serve"];
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, next);
+    console.log(`  allowlist: ${entry} → ${settingsPath}`);
   }
-  const okCodex = run("codex -> claude", "codex", serveCmd);
-  if (okCodex) patchCodexTimeouts(); // codex mcp add can't persist these; do it ourselves
-
-  // --- Claude -> Codex: claude gets gaslamp's codex tools (user scope) --------
-  // `--env GASLAMP_NESTED=1` tags every Codex spawned as a Claude consult as
-  // nested, so gaslamp's server.mjs refuses if that consulted Codex tries to
-  // hand work back to Claude — a consult is one hop (GASLAMP_ALLOW_RECURSION=1
-  // opts back in). Placement is safe: the server name `gaslamp` precedes --env
-  // and `--` follows it, so the name is never misread as a KEY=VALUE pair.
-  remove("claude", "gaslamp", ["-s", "user"]);
-  remove("claude", "codex", ["-s", "user"]); // legacy name
-  const okClaude = run("claude -> codex", "claude",
-    ["mcp", "add", "gaslamp", "-s", "user", "--env", "GASLAMP_NESTED=1", "--", "codex", "mcp-server"]);
-
-  console.log();
-  if (okCodex && okClaude) {
-    console.log("registered both directions as `gaslamp`.");
-    console.log("→ restart Claude Code so it loads the server.");
-    console.log("  verify:  codex mcp list   and   claude mcp list");
+
+  if (skill) {
+    for (const path of installSkills()) console.log(`  skill: ${path}`);
+    console.log("\ndone. both agents now discover gaslamp through the skill; a CLAUDE.md /");
+    console.log("AGENTS.md note is optional on top (the README has the text).");
   } else {
-    console.error("setup: one or both registrations failed (see above).");
-    process.exitCode = 1;
+    console.log("\ndone. one thing left, yours to do: add a short consult note to your");
+    console.log("agent instructions (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md) so each agent");
+    console.log("knows the command exists — see the README for the text to paste. Or run");
+    console.log("`gaslamp setup --skill` to install the gaslamp skill for both agents instead.");
   }
 }

package/src/tail.mjs

@@ -0,0 +1,93 @@
+// 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 vs codex --json); this normalizes both
+// 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 === "claude") {
+    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") 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;
+}