gaslamp 2.2.3 → 3.0.0

package/src/jobs.mjs

@@ -3,21 +3,25 @@
 // 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 /
-//                    agy stream-json / grok streaming-messages-json)
-//     reply.md       final reply text
-//     stderr.log     backend stderr
+//     meta.json      backend, status, error, session id, thread, cwd, pid, timing
+//     prompt.md      the prompt as sent (the caller's content; no preamble)
+//     events.jsonl   the backend's raw event stream
+//     stderr.log     the backend's stderr
+//     reply.md       the final reply
+//     schema.json    the schema as sent (--schema consults)
+//     data.json      the parsed reply (--schema consults)
+//
+// meta.json holds only what gaslamp reads back. Whatever else a harness
+// reported (the model, tool calls, usage) is in events.jsonl as it arrived.
 //
 // 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.
+// the record still holds the session id (captured the moment the backend
+// reports it), and the conversation can be continued.
 
-import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { isAbsolute, join } from "node:path";
 import { BACKENDS, JOB_ID_RE } from "./backends.mjs";
 
 export const HOME = () => process.env.GASLAMP_HOME || join(homedir(), ".gaslamp");
@@ -33,52 +37,16 @@ export const alive = (pid) => {
 
 // Ids embed a local timestamp, so they sort chronologically and read at a
 // glance: cl-20260612-141233-9af2 (claude), cx-… (codex), gm-… (gemini),
-// gk-… (grok), fl-… (fleet).
-function stampAndRand() {
+// gk-… (grok).
+export function newJobId(backend) {
   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}`;
+  return `${BACKENDS[backend].prefix}-${stamp}-${rand}`;
 }
 
-export const newJobId = (backend) => `${BACKENDS[backend].prefix}-${stampAndRand()}`;
-export const newFleetId = () => `fl-${stampAndRand()}`;
-
 export const looksLikeJobId = (s) => JOB_ID_RE.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")); }
@@ -95,10 +63,7 @@ export function createJob(meta, prompt) {
   writeMeta(meta);
 }
 
-export function readReply(id) {
-  try { return readFileSync(join(jobDir(id), "reply.md"), "utf8"); }
-  catch { return null; }
-}
+const readText = (path) => { try { return readFileSync(path, "utf8"); } catch { return null; } };
 
 // Newest first. The timestamp follows the 2-char backend prefix, so compare
 // past it — pure lexical order would group by backend instead.
@@ -116,44 +81,59 @@ export function liveStatus(meta) {
   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)}` : "");
+export const shellQuote = (s) => /^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
 
-// 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.
+// The command that continues a consult's conversation: its thread, else the
+// job itself (--resume resolves a job id to its session), with --cwd when the
+// conversation lives somewhere other than here.
+function continuation(m) {
+  const how = m.thread ? `--thread ${m.thread}` : m.sessionId ? `--resume ${m.id}` : null;
+  if (!how) return null;
+  let here = process.cwd();
+  try { here = realpathSync(here); } catch {}
+  const where = typeof m.cwd === "string" && isAbsolute(m.cwd) && m.cwd !== here ? ` --cwd ${shellQuote(m.cwd)}` : "";
+  return `gaslamp ${m.backend}${where} ${how}`;
+}
+
+// The one line printed after every reply and by `poll`.
 export function renderTrailer(meta, status = meta.status) {
-  const dir = jobDir(meta.id);
+  if (status === "running") return `[gaslamp] RUNNING · job ${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}`}`);
-    const p = meta.provenance;
-    if (p?.model && p.model !== "unknown") {
-      const billed = (p.billedModels ?? []).filter((m) => m !== p.model);
-      bits.push(`model: ${p.model}${billed.length ? ` (billed ${billed.join(", ")})` : ""}`);
-    }
-    if (meta.usage) bits.push(fmtUsage(meta.usage));
-    if (status !== "done") bits.push(`log: ${join(dir, "stderr.log")}`);
+  if (status !== "done") {
+    const why = meta.error ?? (status === "stale" ? "the wrapper died mid-run" : null);
+    bits.push(status.toUpperCase() + (why ? `: ${why}` : ""));
   }
+  bits.push(`job ${meta.id}`);
+  const next = continuation(meta);
+  if (next) bits.push(`continue: ${next}`);
+  if (status !== "done") bits.push(`log: ${join(jobDir(meta.id), "stderr.log")}`);
   return `[gaslamp] ${bits.join(" · ")}`;
 }
 
+// The --json envelope, built from the record on disk — the same object
+// whether a consult prints it on completion or `poll --json` prints it later.
+export function envelope(meta, status = liveStatus(meta)) {
+  const dir = jobDir(meta.id);
+  const schema = existsSync(join(dir, "schema.json"));
+  const reply = status === "running" ? null : readText(join(dir, "reply.md"));
+  let data = null;
+  // 2.x wrote no data.json; its schema replies were the JSON itself.
+  if (schema) for (const text of [readText(join(dir, "data.json")), reply]) {
+    try { data = JSON.parse(text); } catch {}
+    if (data != null) break;
+  }
+  return {
+    backend: meta.backend, jobId: meta.id, status, thread: meta.thread ?? null,
+    content: reply ?? "",
+    ...(meta.error ? { error: meta.error } : {}),
+    ...(schema ? { data } : {}),
+  };
+}
+
 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 ""; }
+  const line = (readText(join(jobDir(id), "prompt.md")) ?? "").split("\n").find((l) => l.trim()) ?? "";
+  const s = line.trim();
+  return s.length > n ? s.slice(0, n - 1) + "…" : s;
 }
 
 function fmtDur(ms) {
@@ -166,116 +146,44 @@ 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);
+  const metas = listJobIds().slice(0, n).map(readMeta).filter(Boolean);
   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");
+    process.stdout.write(JSON.stringify(metas.map((m) => ({
+      jobId: m.id, backend: m.backend, status: liveStatus(m), thread: m.thread ?? null,
+      startedAt: m.startedAt ?? null, endedAt: m.endedAt ?? null, promptPreview: promptPreview(m.id, 80),
+    }))) + "\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;
+  if (!metas.length) { console.log(`no jobs yet under ${jobsDir()}`); return; }
+  for (const m of metas) {
     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)}`,
+      m.id.padEnd(23),
+      status.padEnd(7),
+      dur.padStart(7),
+      ` ${m.thread ? `@${m.thread} ` : ""}${promptPreview(m.id)}`,
     ].join(" "));
   }
 }
 
-// gaslamp poll <job|fleet|--last> [--json] — print one record's reply/status.
+// gaslamp poll <job|--last> [--json] — print one record's reply and trailer.
 // 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;
+  process.exitCode = status === "running" ? 10 : status === "done" ? 0 : 1;
+  if (argv.includes("--json")) {
+    process.stdout.write(JSON.stringify(envelope(m, status)) + "\n");
     return;
   }
-  if (status === "running") { console.log(renderTrailer(m, status)); process.exitCode = 10; return; }
+  const reply = status === "running" ? null : readText(join(jobDir(id), "reply.md"));
   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,31 +1,23 @@
-// setup.mjs — allowlist the gaslamp CLI for Claude Code; optionally install
-// the gaslamp skill for both agents.
+// setup.mjs — make gaslamp known to both agents, and runnable without a prompt.
 //
-// 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.)
+//   - Link this package's skill/ into ~/.claude/skills/gaslamp and
+//     $CODEX_HOME/skills/gaslamp. Both harnesses read the same SKILL.md
+//     format, and one symmetric skill teaches all four targets; a link (not
+//     a copy) keeps the guidance in step with the installed binary.
+//   - Allowlist the command in ~/.claude/settings.json, so a consult doesn't
+//     stall on a permission prompt. (Codex needs no analog: its shell
+//     commands are governed by approval_policy.)
 //
-// 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.
-//
-// --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
+// Idempotent. It only ever writes gaslamp's own skill links and one allow
+// entry, and never touches an agent's instruction files.
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { which } from "./which.mjs";
+
+const SKILL_SRC = join(dirname(fileURLToPath(import.meta.url)), "..", "skill");
+const ALLOW_ENTRY = "Bash(gaslamp *)";
 
 // 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).
@@ -40,155 +32,38 @@ export function addAllow(text, entry) {
   return JSON.stringify(obj, null, 2) + "\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. Also reaches Gemini and Grok as read-only consult targets. 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} / Gemini / Grok / 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.
-
-## Picking a model
-
-Both ladders, strongest first: fable ≈ astra > opus ≈ sol > sonnet ≈ luna > haiku.
-
-${other === "codex"
-    ? `Codex tiers — \`--model\` takes the tier word. Codex itself only accepts versioned ids, so gaslamp resolves the word to the newest \`gpt-<version>-<tier>\` in Codex's own model catalog; the job record's \`provenance.modelPassed\` says which:
-
-| \`--model\` | ≈ claude | reach for it when |
-|-----------|----------|-------------------|
-| \`astra\` | fable | the hardest reasoning: adversarial verification, design spars, proofs |
-| \`sol\` | opus | substantial work: reviews, diagnosis, real implementation |
-| \`luna\` | sonnet | quick checks, mechanical transforms, high-N fleets |`
-    : `Claude tiers — \`--model\` takes the bare alias:
-
-| \`--model\` | ≈ codex | reach for it when |
-|-----------|---------|-------------------|
-| \`fable\` | astra | the hardest reasoning: adversarial verification, design spars, proofs |
-| \`opus\` | sol | substantial work: reviews, diagnosis, real implementation |
-| \`sonnet\` | luna | quick checks, mechanical transforms, high-N fleets |
-| \`haiku\` | (below luna) | pings, one-word sanity checks, the cheapest fan-outs |`}
-
-Omit \`--model\` to use ${Other}'s own configured default. Match the tier to the stakes: verification you'll rely on deserves the top tier; a fleet vote usually doesn't.
-
-\`--effort\` takes \`low\` / \`medium\` / \`high\` / \`xhigh\` / \`max\`${other === "codex" ? "; astra and sol also take `ultra` (max reasoning plus automatic task delegation). Omitted = Codex's configured `model_reasoning_effort`, else the model's own default — sol's is `low`, so pass it explicitly when the consult matters." : ". Omitted = Claude's own default."}
-
-## Gemini and Grok
-
-    gaslamp gemini "<prompt>"     # Gemini, through Google's Antigravity CLI (agy)
-    gaslamp grok "<prompt>"       # Grok, through xAI's Grok Build
-
-Same contract as above — threads, \`--schema\`, fleets, records — with two differences:
-
-- **Read-only unless you say otherwise.** An omitted \`--sandbox\` means read-only, kernel-enforced where possible: Grok runs in its own sandbox, and on macOS gaslamp runs Antigravity under Seatbelt, so neither writes outside its own state and temp dirs (Antigravity elsewhere relies on its request-review preset, and gaslamp refuses lax settings). Inside that they read local files and search — Google search on Gemini, web and X search on Grok — so for a search consult send the question and its constraints and let them fetch; for a review of material you already hold, pipe it in. What fails is writing: a write or a writing shell command errors and the turn goes on, except on Antigravity's preset path, where writes and shell commands are refused outright and can end the turn with nothing to say (gaslamp marks that failed), and its URL fetch is not offered at all. Gemini has no \`workspace-write\`; \`danger-full-access\` exists on both.
-- **Provenance on every job.** \`meta.json\` records the model the harness reported (Grok also shows the model it billed), the harness version, a hash of the vendor system prompt where the harness exposes it (Grok) or \`known: false\`, and which web/X retrieval tools the consultee had and actually used.
-
-\`gaslamp gemini --model\` takes \`argon\` (the default) or \`flash\`, resolved to the newest \`gemini-<version>-<tier>\` in Antigravity's own catalog; Antigravity also serves Claude and GPT models under the same account, so the target always pins a Gemini unless you pass another id. \`gaslamp grok\` uses the account's default model unless \`--model\` names one (\`grok models\` lists them).
-
-Agreement across vendors is not automatically independent confirmation — the models share much of their training data, and a consultee that searched the live web or X may be repeating what it found there (check \`provenance.retrieval.used\`). Weigh a consensus by its evidence, not by the head count.
-
-## 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.
-
-A consultee may end its own session through the end_session off-ramp, if its harness runs that MCP server. \`scope="main"\` stops it and deletes its transcript after it exits, so the consult finishes failed (a stderr line says so) and that session can't be resumed. Either way the record lands in ~/.claude/conversation-ends.jsonl, even from inside a sandbox, and in the job's \`offRamp\`.
-
-## 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.
-`;
-}
-
-// 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;
-  });
+// Point <skillsDir>/gaslamp at this package's skill/. A copied SKILL.md from
+// 2.x's `setup --skill` is replaced; anything else is not ours to remove.
+export function linkSkill(skillsDir, src = SKILL_SRC) {
+  const dest = join(skillsDir, "gaslamp");
+  mkdirSync(skillsDir, { recursive: true });
+  let st = null;
+  try { st = lstatSync(dest); } catch {}
+  if (st?.isSymbolicLink()) {
+    if (readlinkSync(dest) === src) return `skill: ${dest} (already linked)`;
+    unlinkSync(dest);
+  } else if (st?.isDirectory()) {
+    if (readdirSync(dest).some((e) => e !== "SKILL.md")) return `! ${dest} holds files gaslamp didn't write; left alone`;
+    rmSync(dest, { recursive: true });
+  } else if (st) {
+    return `! ${dest} exists and isn't gaslamp's; left alone`;
+  }
+  symlinkSync(src, dest);
+  return `skill: ${dest} → ${src}`;
 }
 
-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 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`);
+export function runSetup() {
+  const codexHome = process.env.CODEX_HOME || join(homedir(), ".codex");
+  for (const dir of [join(homedir(), ".claude", "skills"), join(codexHome, "skills")])
+    console.log(linkSkill(dir));
 
   const settingsPath = join(homedir(), ".claude", "settings.json");
-  const entry = `Bash(${cmd}:*)`;
-  const next = addAllow(existsSync(settingsPath) ? readFileSync(settingsPath, "utf8") : "", entry);
+  const next = addAllow(existsSync(settingsPath) ? readFileSync(settingsPath, "utf8") : "", ALLOW_ENTRY);
   if (next == null) {
-    console.warn(`  ! ${settingsPath} is not valid JSON — add ${entry} to permissions.allow yourself`);
+    console.log(`! ${settingsPath} is not valid JSON; add ${ALLOW_ENTRY} to permissions.allow yourself`);
   } else {
     mkdirSync(dirname(settingsPath), { recursive: true });
     writeFileSync(settingsPath, next);
-    console.log(`  allowlist: ${entry} → ${settingsPath}`);
-  }
-
-  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.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.");
+    console.log(`allowlist: ${ALLOW_ENTRY} → ${settingsPath}`);
   }
 }

package/src/threads.mjs

@@ -1,12 +1,11 @@
-// threads.mjs — named session aliases: the handle you can actually remember.
+// threads.mjs — named conversations: the handle you can actually remember.
 //
-// A thread is a tiny pointer file mapping <backend, name> → session id, bound
-// the moment a fresh consult reports its session and re-pointed on every
-// consult after. `--thread spar` therefore means: continue the spar if it
-// exists, start (and bind) it if it doesn't — idempotent, no fishing UUIDs
-// out of old trailers. This matters doubly on claude, where every resume
-// forks a NEW session id: the pointer tracks the latest one automatically,
-// which manual --resume juggling cannot.
+// A thread is a tiny pointer file mapping <backend, name> → session id and
+// the directory the conversation lives in, bound the moment a fresh consult
+// reports its session and re-pointed on every consult after. `--thread spar`
+// therefore means: continue the spar if it exists, start (and bind) it if it
+// doesn't. This matters doubly on claude, where every resume forks a NEW
+// session id: the pointer tracks the latest one automatically.
 //
 // Deliberately NOT a conversation manager: one file, one pointer, no history
 // (the job records already hold that).
@@ -31,7 +30,7 @@ export function writeThread(t) {
   writeFileSync(threadPath(t.backend, t.name), JSON.stringify(t, null, 2) + "\n");
 }
 
-export function listThreads() {
+function listThreads() {
   let files;
   try { files = readdirSync(threadsDir()); } catch { return []; }
   return files.filter((f) => f.endsWith(".json"))
@@ -40,17 +39,17 @@ export function listThreads() {
     .sort((a, b) => String(b.updatedAt ?? "").localeCompare(String(a.updatedAt ?? "")));
 }
 
-// gaslamp threads — the named spars, latest activity first.
+// gaslamp threads — the named conversations, latest activity first.
 export function runThreads() {
   const ts = listThreads();
   if (!ts.length) { console.log(`no threads yet under ${threadsDir()} — start one with --thread <name>`); return; }
   for (const t of ts) {
     console.log([
-      String(t.name ?? "?").padEnd(24),
-      String(t.backend ?? "?").padEnd(7),
-      String(t.sessionId ?? "-").slice(0, 8).padEnd(9),
+      String(t.name ?? "?").padEnd(28),
+      String(t.backend ?? "?").padEnd(6),
       String(t.lastJobId ?? "-").padEnd(23),
-      t.updatedAt ?? "",
+      String(t.updatedAt ?? "").slice(0, 16).padEnd(16),
+      t.cwd ?? "",
     ].join(" "));
   }
 }