@uchibeke/gallivant 0.0.0-stage → 0.2.1

package/lib/run.mjs

@@ -0,0 +1,385 @@
+// Detached runs, adapted from command-center's lib/run.mjs so its log viewer can read a Gallivant run unchanged.
+//
+// A run is a child process whose stdout is a file. Nothing about it lives only in this process: the pid is on disk,
+// liveness is asked of the operating system, and a daemon restarted mid-run picks it up from the folder. Each entry
+// gets its own root, so one run per entry is the natural lock and entries never block each other.
+import { spawn, execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync, openSync, closeSync, readSync, statSync, rmSync, existsSync, realpathSync } from "node:fs";
+import { join, basename, resolve, sep } from "node:path";
+import { ensureDir } from "./fs.mjs";
+import { stamp } from "./time.mjs";
+import { toPrdId } from "./prd.mjs";
+import { readJson, writeJsonAtomic } from "./fs.mjs";
+import { journalFor } from "./execution_journal.mjs";
+import { LOG_LIMITS } from "./run_log.mjs";
+import { claudeRuntimeSettings, prepareRuntimeCache, RUNTIME_SETTINGS_FILE } from "./runtime-environment.mjs";
+
+/** Signal 0 says whether a pid exists; EPERM means it exists but belongs to someone else, which still counts. */
+export const alive = pid => { try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; } };
+
+/** A signal request is not confirmation: descendants may still own the run. */
+export function requestRunCancellation(runner, id) {
+  runner.kill(id);
+  const job = runner.current();
+  return { confirmed: job?.id === id && job.running === false };
+}
+
+const sameProcess = (a, b) => a.pid === b.pid && a.started === b.started;
+const ownedGroups = (pid, members) => new Set([pid, ...members.filter(m => m.pid === m.group).map(m => m.group)]);
+
+/** Live descendants, including tool helpers that create their own process groups. */
+export function runProcesses(pid, known = [], exec = execFileSync) {
+  try {
+    const text = exec("ps", ["-axo", "pid=,ppid=,pgid=,stat=,lstart="], {
+      encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"],
+      env: { ...process.env, LC_ALL: "C", LANG: "C", TZ: "UTC" },
+    });
+    const rows = text.split("\n").filter(row => row.trim()).map(row => {
+      const m = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.+?)\s*$/.exec(row);
+      if (!m) throw new Error("unreadable process row");
+      return { pid: Number(m[1]), parent: Number(m[2]), group: Number(m[3]), zombie: m[4].includes("Z"), started: m[5] };
+    });
+    // Recorded group leaders keep orphaned tools discoverable after a daemon restart.
+    // A tool in a shared outside group never grants ownership of that entire group.
+    const groups = ownedGroups(pid, known);
+    const ids = new Set(rows.filter(m => groups.has(m.group) || known.some(old => sameProcess(m, old))).map(m => m.pid));
+    let count;
+    do {
+      count = ids.size;
+      for (const m of rows) if (ids.has(m.parent)) ids.add(m.pid);
+    } while (ids.size !== count);
+    return rows.filter(m => ids.has(m.pid) && !m.zombie).map(({ pid, group, started }) => ({ pid, group, started }));
+  } catch { return null; } // Unknown must not authorize another writer or a signal.
+}
+
+/**
+ * Liveness that survives pid reuse: after a daemon crash the exit is never recorded, and days later the same pid
+ * can belong to a stranger. A run is ours only if the process's command still names the harness binary.
+ */
+export function isOurProcess(pid, cmd) {
+  if (!alive(pid)) return false;
+  try {
+    const comm = execFileSync("ps", ["-o", "command=", "-p", String(pid)], { encoding: "utf8" }).trim();
+    return comm.includes(basename(cmd)) || comm.includes(cmd);
+  } catch { return false; }
+}
+
+// The run folder name. One shape with the brief's id, capped because this is a path segment.
+const slug = s => toPrdId(s, { max: 40 }) || "run";
+export const LOCAL_OUTPUT_LIMITS = Object.freeze({ records: 100, bytes: LOG_LIMITS.windowBytes, pages: 2 });
+const PRIVATE_OUTPUT_RETENTION_MS = 86_400_000;
+
+export function makeRunner(root, { clock = Date, probe = isOurProcess, processes = runProcesses, signal = (pid, sig) => process.kill(pid, sig) } = {}) {
+  const pendingKills = new Map();
+  const pointer = join(root, "latest-run");
+  const projectionQueue = join(root, "local-output-queue.json");
+  const dirOf = id => {
+    if (!/^[A-Za-z0-9_-]+$/.test(id)) throw new Error(`invalid run id ${id}`);
+    return join(root, id);
+  };
+  const currentId = () => { try { return readFileSync(pointer, "utf8").trim() || null; } catch { return null; } };
+  const read = id => { try { return JSON.parse(readFileSync(join(dirOf(id), "job.json"), "utf8")); } catch { return null; } };
+  const write = (id, job) => writeFileSync(join(dirOf(id), "job.json"), JSON.stringify(job, null, 1), { mode: 0o600, flush: true });
+  const lines = id => { try { return readFileSync(join(dirOf(id), read(id)?.privateOutput ? "provider.log" : "job.log"), "utf8").split("\n").filter(Boolean); } catch { return []; } };
+  const outputQueue = () => {
+    const saved = readJson(projectionQueue, { version: 1, runs: [] });
+    if (!saved || saved.version !== 1 || !Array.isArray(saved.runs) || saved.runs.some(id => typeof id !== "string" || !/^[A-Za-z0-9_-]+$/.test(id)) || new Set(saved.runs).size !== saved.runs.length) {
+      throw Object.assign(new Error("unsupported local output queue; preserve the run tree and restore a compatible package/queue backup before dispatch"), { code: "RUN_OUTPUT_VERSION" });
+    }
+    return saved;
+  };
+  const outputCheckpoint = id => {
+    const checkpoint = readJson(join(dirOf(id), "local-output.json"), { offset: 0 });
+    if (!checkpoint || !Number.isSafeInteger(checkpoint.offset) || checkpoint.offset < 0 || (checkpoint.discarding !== undefined && typeof checkpoint.discarding !== "boolean")) throw new Error("invalid local output cursor; preserve diagnostics and restore its matching checkpoint before dispatch or replay");
+    return checkpoint;
+  };
+  const privateFiles = id => ["provider.log", "sensitive-redactions.json"].map(name => join(dirOf(id), name));
+  // Fixed run-owned filename, never a cleanup path supplied by the harness.
+  // Unknown process ownership or surviving tools retain the snapshot. Recovery
+  // calls this again after restart; cleanup does not depend on an exit callback.
+  const cleanupRuntime = job => {
+    if (!job?.runtimeSettings) return;
+    const file = join(dirOf(job.id), RUNTIME_SETTINGS_FILE);
+    if (!existsSync(file)) return;
+    if (job.pid) {
+      const members = processes(job.pid, job.stopMembers ?? []);
+      if (members === null || members.length) return;
+    }
+    rmSync(file, { force: true });
+  };
+  // Register projection and cleanup before replacing latest-run. Called before the
+  // execution boundary saves a paid intent, and again by standalone start.
+  function prepareStart() {
+    const job = current(), queue = outputQueue();
+    if (job?.running) throw Object.assign(new Error(`run in progress: ${job.id}`), { code: "BUSY" });
+    cleanupRuntime(job);
+    if (!job?.privateOutput) return;
+    const checkpoint = outputCheckpoint(job.id);
+    if ((checkpoint.pending || privateFiles(job.id).some(file => existsSync(file))) && !queue.runs.includes(job.id)) {
+      writeJsonAtomic(projectionQueue, { version: 1, runs: [...queue.runs, job.id] });
+    }
+  }
+  // Only coordinator calls observe. Public readers never ingest raw diagnostics.
+  function observeRun(job, meter) {
+    if (!job?.privateOutput) return false;
+    const dir = dirOf(job.id), [file, redactionsFile] = privateFiles(job.id);
+    const redactions = readJson(redactionsFile);
+    const checkpointFile = join(dir, "local-output.json"), checkpoint = outputCheckpoint(job.id);
+    const present = existsSync(file), size = present ? statSync(file).size : 0;
+    const retained = present || existsSync(redactionsFile);
+    const journal = () => journalFor(dir, { ...job.privateOutput, secrets: redactions?.secrets || [] });
+    const gap = reason => {
+      journal().append({ eventId: `gap-${checkpoint.offset}-${reason}`, type: "gap", provenance: "coordinator", timestamp: clock.now(), data: `[gap: ${reason}; remaining local diagnostic history is unavailable]` });
+      writeJsonAtomic(checkpointFile, { offset: size, pending: false, gap: reason });
+      meter.records = (meter.records || 0) + 1;
+    };
+    const expiresAt = redactions?.expiresAt ?? job.startedAt + PRIVATE_OUTPUT_RETENTION_MS;
+    if (expiresAt <= clock.now() && existsSync(join(dir, "result.json"))) {
+      if (checkpoint.pending || size > checkpoint.offset) gap("diagnostic retention expired");
+      rmSync(file, { force: true }); rmSync(redactionsFile, { force: true }); return false;
+    }
+    if (!present) { if (checkpoint.pending) gap("diagnostic file missing"); return retained; }
+    if (size < checkpoint.offset) { gap("diagnostic file truncated"); return retained; }
+    if (!redactions && size > checkpoint.offset) { gap("redaction metadata missing"); return retained; }
+    // Drained runs still need expiry checks, but no diagnostic read or journal write.
+    if (checkpoint.pending === false && size === checkpoint.offset) return retained;
+    const fd = openSync(file, "r");
+    try {
+      let discarding = checkpoint.discarding === true, prefixBytes = 0;
+      // Older cursors advanced a window into an omitted record without saving
+      // discard state. A bounded lookbehind repairs that mid-record cursor.
+      if (!discarding && checkpoint.pending && checkpoint.offset > 0) {
+        const previous = Buffer.alloc(1);
+        prefixBytes = readSync(fd, previous, 0, 1, checkpoint.offset - 1);
+        discarding = prefixBytes === 1 && previous[0] !== 10;
+      }
+      const pageBytes = LOCAL_OUTPUT_LIMITS.bytes - prefixBytes;
+      const length = Math.min(pageBytes, Math.max(0, size - checkpoint.offset));
+      const buffer = Buffer.alloc(length), n = readSync(fd, buffer, 0, length, checkpoint.offset), data = buffer.subarray(0, n);
+      meter.pages = (meter.pages || 0) + 1; meter.bytesRead = (meter.bytesRead || 0) + n + prefixBytes;
+      meter.maxBufferBytes = Math.max(meter.maxBufferBytes || 0, length);
+      const log = journal();
+      let consumed = 0;
+      let records = 0;
+      if (discarding) {
+        const newline = data.indexOf(10);
+        consumed = newline < 0 ? n : newline + 1;
+        discarding = newline < 0 && (job.running || checkpoint.offset + n < size);
+      }
+      while (consumed < n && records < LOCAL_OUTPUT_LIMITS.records) {
+        const newline = data.indexOf(10, consumed);
+        if (newline < 0) break;
+        const part = data.subarray(consumed, newline).toString("utf8");
+        log.append({ eventId: `byte-${checkpoint.offset + consumed}`, type: "output", timestamp: clock.now(), provenance: "local-cli", data: part });
+        consumed = newline + 1;
+        records++;
+      }
+      if (!consumed && n === pageBytes) {
+        log.append({ eventId: `byte-${checkpoint.offset}`, type: "gap", data: "oversized local record omitted", timestamp: clock.now() });
+        consumed = n; records++;
+        discarding = job.running || checkpoint.offset + n < size;
+      }
+      // An exit can leave a final line without newline. Preserve it once.
+      if (!discarding && !job.running && records < LOCAL_OUTPUT_LIMITS.records && n && consumed < n && checkpoint.offset + n === size) {
+        log.append({ eventId: `byte-${checkpoint.offset + consumed}`, type: "output", data: data.subarray(consumed).toString("utf8"), timestamp: clock.now(), provenance: "local-cli" });
+        consumed = n; records++;
+      }
+      meter.records = (meter.records || 0) + records;
+      const pending = discarding || checkpoint.offset + consumed < size;
+      writeJsonAtomic(checkpointFile, { offset: checkpoint.offset + consumed, pending, discarding });
+      return pending || retained;
+    } finally { closeSync(fd); }
+  }
+  function observe({ meter = {} } = {}) {
+    const queue = outputQueue(), job = current(), old = queue.runs[0], remaining = queue.runs.slice(1);
+    cleanupRuntime(job);
+    if (old && old !== job?.id) {
+      const previous = read(old);
+      cleanupRuntime(previous);
+      if (!previous?.privateOutput) throw new Error(`queued output ${old} lacks its owned job metadata; preserve the queue and restore job.json before replay`);
+      if (observeRun({ ...previous, running: running(previous) }, meter)) remaining.push(old);
+    }
+    const retained = job ? observeRun(job, meter) : false;
+    if (old === job?.id && retained) remaining.push(old);
+    if (old) writeJsonAtomic(projectionQueue, { version: 1, runs: remaining });
+    return meter;
+  }
+  // A terminated leader can leave tool subprocesses behind. Do not start a second
+  // writer until its tool processes are gone, even though cancellation recorded an exit.
+  const running = job => {
+    if (!job?.pid) return false;
+    if (!job.killed) return job.exit === null && probe(job.pid, job.bin);
+    const members = processes(job.pid, job.stopMembers ?? []);
+    return members === null || members.length > 0;
+  };
+  const signalRun = (job, members, sig) => {
+    const fail = () => { throw Object.assign(new Error("Cannot verify the interrupted process tree. Inspect its remaining processes before retrying; no replacement was started."), { code: "RUN_STOP_UNVERIFIED" }); };
+    if (members === null) fail();
+    const groups = ownedGroups(job.pid, job.stopMembers ?? []), targets = new Set();
+    for (const m of members) {
+      if (groups.has(m.group)) {
+        if (!members.some(peer => peer.group === m.group && job.stopMembers?.some(old => sameProcess(peer, old)))) fail();
+        targets.add(-m.group);
+      } else {
+        if (!job.stopMembers?.some(old => sameProcess(m, old))) fail();
+        targets.add(m.pid);
+      }
+    }
+    // Stop tools first, then their owner. Validate every target before signalling any.
+    for (const target of [...targets].sort((a, b) => (a === -job.pid) - (b === -job.pid))) {
+      try { signal(target, sig); } catch (e) { if (e.code !== "ESRCH") throw e; }
+    }
+  };
+  const finishKill = job => {
+    if (job?.killed) signalRun(job, processes(job.pid, job.stopMembers ?? []), "SIGKILL");
+  };
+
+  /** Spawn durably. inheritEnv=false uses only the caller's env plus run-directory metadata. */
+  async function start(name, cmd, args, { cwd, env = {}, inheritEnv = true, runId = null, privateOutput = null, runtimeSettings = null }) {
+    prepareStart();
+    prepareRuntimeCache(cwd, env);
+    const id = runId || `${stamp(clock)}-${slug(name)}`;
+    ensureDir(dirOf(id), 0o700);
+    if (privateOutput) {
+      const redactions = Object.entries(env).filter(([key]) => /token|password|secret|api_key/i.test(key)).map(([, value]) => value).filter(Boolean);
+      writeJsonAtomic(join(dirOf(id), "sensitive-redactions.json"), { expiresAt: clock.now() + PRIVATE_OUTPUT_RETENTION_MS, secrets: redactions });
+      writeFileSync(join(dirOf(id), "job.log"), "", { mode: 0o600 });
+    }
+    const out = openSync(join(dirOf(id), privateOutput ? "provider.log" : "job.log"), "w", 0o600);
+    let ownedSettings = false, spawnedJob = null;
+    try {
+      if (runtimeSettings) {
+        const index = args.indexOf("--settings");
+        if (index < 0 || args[index + 1] !== runtimeSettings.settings) throw new Error("runtime settings do not match the launch arguments");
+        const directory = realpathSync(dirOf(id)), checkout = realpathSync(cwd || process.cwd());
+        if (directory === checkout || directory.startsWith(checkout + sep)) throw new Error("runtime settings must be outside the agent checkout");
+        const destination = join(dirOf(id), RUNTIME_SETTINGS_FILE);
+        const settings = claudeRuntimeSettings(runtimeSettings.settings, destination, runtimeSettings.node);
+        ownedSettings = settings === destination;
+        args = [...args]; args[index + 1] = settings;
+      }
+      writeFileSync(join(dirOf(id), "cmd.json"), JSON.stringify({ cmd, args, cwd }, null, 1), { mode: 0o600 });
+      // spawn changes the OS directory but inherits PWD. OpenCode 1.18.31 prefers PWD for its tool root;
+      // leaving the daemon's value here can send edits and Git writes to the wrong checkout.
+      const p = spawn(cmd, args, { cwd, env: { ...(inheritEnv ? process.env : {}), ...env, PWD: resolve(cwd || process.cwd()), CP_RUN_DIR: dirOf(id) }, detached: true, stdio: ["ignore", out, out] });
+      const job = { id, name, pid: p.pid ?? null, bin: cmd, startedAt: clock.now(), exit: null, cmd: `${cmd} ${args.slice(0, 4).join(" ")}`, ...(privateOutput ? { privateOutput } : {}), ...(ownedSettings ? { runtimeSettings: true } : {}) };
+      spawnedJob = job;
+      let startupFailed = false;
+      p.on("error", err => {
+        if (startupFailed) return;
+        const j = read(id) || job;
+        write(id, { ...j, exit: 127, endedAt: clock.now(), error: err.message });
+        cleanupRuntime(job);
+      });
+      // A death by signal has no exit code; record the signal so it is never mistaken for success.
+      p.on("exit", (code, signal) => {
+        const j = read(id);
+        // kill owns the terminal record while its fallback is pending. If that write
+        // failed, retrying it here could throw out of band before descendants are killed.
+        if (!startupFailed && j && j.pid === p.pid && j.exit === null && !pendingKills.has(id)) write(id, { ...j, exit: code ?? 128, signal: signal ?? null, endedAt: clock.now() });
+        cleanupRuntime(j || job);
+      });
+      p.unref();
+      try {
+        write(id, job);
+        writeFileSync(pointer, id);
+        return job;
+      } catch (error) {
+        startupFailed = true;
+        // This PID belongs to the child just spawned. Do not depend on job.json or
+        // latest-run: either may be missing, truncated, or still point to an older run.
+        if (job.pid) {
+          terminate(job);
+          await waitForKill(id);
+        }
+        throw error;
+      }
+    } catch (error) {
+      if (ownedSettings) cleanupRuntime(spawnedJob || { id, runtimeSettings: true });
+      throw error;
+    } finally {
+      // spawn duplicates this descriptor for the child. Close the parent's copy
+      // on successful startup and on pre/post-spawn failures alike.
+      try { closeSync(out); } catch { /* closed */ }
+    }
+  }
+
+  /** The newest run with liveness resolved: { ...job, running }. Null when nothing has run. */
+  function current() {
+    const id = currentId();
+    const job = id && read(id);
+    return job ? { ...job, running: running(job) } : null;
+  }
+
+  /**
+   * Record the outcome of a run whose process is gone but whose exit was never written (the daemon was not there
+   * when it ended). `inferExit` decides from the log lines the caller already read.
+   */
+  function settle(id, inferExit = () => 1) {
+    const job = read(id);
+    cleanupRuntime(job);
+    if (!job || job.exit !== null) return job;
+    if (running(job)) return { ...job, running: true };
+    const settled = { ...job, exit: inferExit(), endedAt: clock.now(), inferred: true };
+    write(id, settled);
+    return settled;
+  }
+
+  // A persisted, ownership-checked job or a child just created by start owns this PID.
+  function terminate(job) {
+    if (pendingKills.has(job.id)) return;
+    try { process.kill(-job.pid, "SIGTERM"); } catch { try { process.kill(job.pid, "SIGTERM"); } catch { /* gone */ } }
+    scheduleKill(job.id, () => {
+      // A leader may exit on TERM while its descendants keep the group alive.
+      // Do not signal a reused leader PID now belonging to another command.
+      if (!alive(job.pid) || probe(job.pid, job.bin)) {
+        try { process.kill(-job.pid, "SIGKILL"); }
+        catch { if (probe(job.pid, job.bin)) { try { process.kill(job.pid, "SIGKILL"); } catch { /* gone */ } } }
+      }
+    });
+  }
+
+  function scheduleKill(id, fallback) {
+    if (pendingKills.has(id)) return;
+    let finish;
+    const done = new Promise(resolve => { finish = resolve; });
+    const timer = setTimeout(() => {
+      let error = null;
+      try { fallback(); } catch (e) { error = e; }
+      finally { pendingKills.delete(id); finish(error); }
+    }, 5000);
+    timer.unref();
+    pendingKills.set(id, { timer, done });
+  }
+
+  /** SIGTERM the process group, then SIGKILL if it is still there. Only a process that is still ours. */
+  function kill(id) {
+    const job = read(id);
+    if (job?.killed) {
+      // Recovery is based on surviving process identities, not an arbitrary deadline.
+      // Reads (including tracker GETs) never signal.
+      if (clock.now() >= job.killAfter) finishKill(job);
+      return false;
+    }
+    if (!job || !running(job)) return false;
+    const stopMembers = processes(job.pid);
+    if (stopMembers === null) throw Object.assign(new Error("Cannot inspect the active process group; nothing was stopped."), { code: "RUN_STOP_UNVERIFIED" });
+    const stopped = { ...job, exit: 137, endedAt: clock.now(), killed: true, stopMembers, killAfter: clock.now() + 5000 };
+    // Own the fallback before writing evidence: a full disk must not leave the
+    // child alive or let an exit callback throw before its tools are stopped.
+    scheduleKill(id, () => finishKill(stopped));
+    try { write(id, stopped); }
+    finally { signalRun(stopped, stopMembers, "SIGTERM"); }
+    return true;
+  }
+
+  /** Keep a short-lived caller alive until its requested process-group fallback has run. */
+  function waitForKill(id) {
+    const pending = pendingKills.get(id);
+    if (!pending) return Promise.resolve();
+    pending.timer.ref();
+    return pending.done.then(error => { if (error) throw error; });
+  }
+
+  return { root, start, prepareStart, current, read, lines, observe, settle, kill, waitForKill, dirOf, annotate: (id, patch) => { const job = read(id); if (job) write(id, { ...job, ...patch }); } };
+}

package/lib/run_log.mjs

@@ -0,0 +1,94 @@
+// Public log projection with fixed-width offsets. Reads are capped independently
+// of file size; legacy files without an index use a bounded suffix with a gap.
+import { openSync, closeSync, readSync, writeSync, statSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { redact } from "./execution_io.mjs";
+import { readJson, writeJsonAtomic } from "./fs.mjs";
+export const LOG_LIMITS = Object.freeze({ windowBytes: 262_144, lineBytes: 65_536, lines: 400, bufferedBytes: 327_680 });
+const stat = file => { try { return statSync(file); } catch { return { size: 0, ino: 0 }; } };
+const boundedItems = items => {
+  let bytes = 2;
+  const bounded = items.map(item => {
+    const line = Buffer.byteLength(JSON.stringify(item.line)) > LOG_LIMITS.lineBytes ? "[gap: record exceeds encoded response limit]" : item.line;
+    bytes += Buffer.byteLength(JSON.stringify(line)) + 1;
+    return { ...item, line };
+  });
+  while (bytes > LOG_LIMITS.windowBytes && bounded.length) bytes -= Buffer.byteLength(JSON.stringify(bounded.shift().line)) + 1;
+  return bounded;
+};
+export function appendProjection(dir, line, { sequence = null } = {}) {
+  const file = join(dir, "job.log"), index = join(dir, "job.idx");
+  const text = redact(String(line)).replace(/\n/g, "\\n");
+  const data = Buffer.from(text + "\n");
+  if (data.length > LOG_LIMITS.lineBytes) throw new Error("projection line exceeds limit; journal a gap instead");
+  const offset = stat(file).size, previous = readJson(join(dir, "log-meta.json"), { version: 2, firstSequence: 1, lastSequence: 0, size: 0, ino: stat(file).ino });
+  const id = sequence ?? previous.lastSequence + 1;
+  if (previous.ino && (previous.ino !== stat(file).ino || offset < previous.size)) previous.firstSequence = id;
+  const fd = openSync(file, "a", 0o600), ix = openSync(index, existsSync(index) ? "r+" : "w+", 0o600);
+  try {
+    writeSync(fd, data);
+    const pointer = Buffer.alloc(8); pointer.writeBigUInt64LE(BigInt(offset + 1)); // zero means a retained-history gap.
+    writeSync(ix, pointer, 0, 8, (id - 1) * 8);
+    writeJsonAtomic(join(dir, "log-meta.json"), { ...previous, version: 2, lastSequence: Math.max(previous.lastSequence, id), ino: stat(file).ino, size: offset + data.length });
+  } finally { closeSync(fd); closeSync(ix); }
+}
+const readRange = (file, start, length, meter) => {
+  if (length <= 0) return Buffer.alloc(0);
+  const fd = openSync(file, "r");
+  try { const buf = Buffer.alloc(length); const n = readSync(fd, buf, 0, length, start); meter.bytesRead += n; return buf.subarray(0, n); }
+  finally { closeSync(fd); }
+};
+export function logWindow(dir, { before = null, after = null, count = LOG_LIMITS.lines, meter = { bytesRead: 0 } } = {}) {
+  const file = join(dir, "job.log"), index = join(dir, "job.idx");
+  const size = stat(file).size;
+  const n = Math.min(LOG_LIMITS.lines, Math.max(1, Math.trunc(Number(count)) || LOG_LIMITS.lines));
+  if (existsSync(index)) {
+    const meta = readJson(join(dir, "log-meta.json"));
+    const total = Math.floor(stat(index).size / 8);
+    const to = after !== null ? Math.min(total, Math.max(0, Number(after)) + n) : before === null ? total : Math.min(total, Math.max(0, Number(before) - 1));
+    const requestedFrom = after !== null ? Math.min(total, Math.max(0, Number(after))) : Math.max(0, to - n);
+    const from = Math.min(to, Math.max(requestedFrom, (meta?.firstSequence || 1) - 1));
+    if (to <= from) return { total, from: from + 1, to, before: from, lines: [], ids: [], ...(to > 0 && meta?.firstSequence > 1 ? { gap: "rotation/retention removed earlier history" } : {}), generation: stat(file).ino };
+    const offsets = readRange(index, from * 8, (to - from + (to < total ? 1 : 0)) * 8, meter);
+    if (!offsets.length) return { total, from: from + 1, to, before: from, lines: [], ids: [], generation: stat(file).ino };
+    const position = i => Number(offsets.readBigUInt64LE(i * 8)) - (meta?.version === 2 ? 1 : 0);
+    let availableFrom = from;
+    while (availableFrom < to && position(availableFrom - from) < 0) availableFrom++;
+    if (availableFrom === to) return { total, from: to + 1, to, before: from, lines: [], ids: [], gap: "history retained as an explicit gap", generation: stat(file).ino };
+    const start = position(availableFrom - from);
+    const end = to < total ? position(to - from) : size;
+    if (start > size || end > size || end < start) return { total, from: from + 1, to, before: from, lines: [], ids: [], gap: "log rotated or index recovery required", generation: stat(file).ino };
+    // Prefer the newest complete lines within the response byte budget.
+    let first = availableFrom;
+    while (end - position(first - from) > LOG_LIMITS.windowBytes && first < to - 1) first++;
+    const pos = position(first - from);
+    const data = readRange(file, pos, Math.min(end - pos, LOG_LIMITS.windowBytes), meter).toString("utf8");
+    const parsed = data.split("\n").filter(Boolean).map(redactLine);
+    const items = boundedItems(parsed.map((line, i) => ({ line, id: first + i + 1 })));
+    const actualFirst = items[0]?.id || first + 1;
+    return { total, from: actualFirst, to: items.at(-1)?.id || first, before: actualFirst - 1, lines: items.map(x => x.line), ids: items.map(x => x.id), ...(actualFirst - 1 > requestedFrom ? { gap: actualFirst - 1 > from ? "window byte limit or interrupted projection; request an older page" : "rotation/retention removed earlier history" } : {}), generation: stat(file).ino };
+  }
+  const missingIndex = readJson(join(dir, "log-meta.json"));
+  if (missingIndex) return { total: missingIndex.lastSequence, from: missingIndex.lastSequence + 1, to: missingIndex.lastSequence, before: 0, lines: [], ids: [], gap: "projection index unavailable; restore it from the journal before replay", generation: stat(file).ino };
+  if (!size) return { total: 0, from: 1, to: 0, before: 0, lines: [], ids: [], generation: stat(file).ino };
+  // Small legacy logs keep exact line-number contracts. Large legacy histories
+  // use stable byte positions until a coordinator has built their projection.
+  const byteMode = size > LOG_LIMITS.windowBytes;
+  const end = byteMode && before !== null ? Math.min(size, Math.max(0, Number(before) - 1)) : size;
+  const start = Math.max(0, end - LOG_LIMITS.windowBytes);
+  const data = readRange(file, start, end - start, meter);
+  let pos = 0, items = [];
+  while (pos < data.length) {
+    const newline = data.indexOf(10, pos), endOfLine = newline < 0 ? data.length : newline;
+    const part = data.subarray(pos, endOfLine).toString("utf8");
+    if (part && !(start > 0 && pos === 0)) items.push({ line: redactLine(part), id: byteMode ? start + pos + 1 : items.length + 1 });
+    pos = endOfLine + 1;
+  }
+  const total = byteMode ? size : items.length;
+  if (!byteMode && before !== null) items = items.slice(0, Math.min(items.length, Math.max(0, Number(before) - 1)));
+  if (after !== null) items = items.filter(item => item.id > after).slice(0, n);
+  else items = items.slice(-n);
+  items = boundedItems(items);
+  return { total, from: items[0]?.id ?? 1, to: items.at(-1)?.id ?? 0, before: Math.max(0, (items[0]?.id ?? 1) - 1), lines: items.map(x => x.line), ids: items.map(x => x.id), ...(byteMode ? { gap: "legacy log has no line index; replay IDs use byte positions", byteMode: true } : {}), generation: stat(file).ino };
+}
+const redactLine = line => Buffer.byteLength(line) > LOG_LIMITS.lineBytes ? "[gap: oversized log record]" : redact(line);

package/lib/runtime-environment.mjs

@@ -0,0 +1,87 @@
+import { dirname, delimiter, join } from "node:path";
+import { readFileSync, writeFileSync, realpathSync, openSync, closeSync, rmSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { repositoryPath } from "./repository_files.mjs";
+
+export const shellQuote = value => `'${value.replaceAll("'", "'\\''")}'`;
+
+// Use the interpreter that successfully started Gallivant, not a second Node
+// selected by a harness shell snapshot (which may have a different ABI/arch).
+export function runtimeEnvironment(env = process.env, node = process.execPath, cwd) {
+  const bin = dirname(node);
+  const cache = cwd ? join(cwd, ".cache", "gallivant", "npm") : null;
+  return {
+    PATH: [bin, ...(env.PATH || "/usr/bin:/bin").split(delimiter).filter(p => p && p !== bin)].join(delimiter),
+    ...(cache ? { NPM_CONFIG_CACHE: cache, npm_config_cache: cache } : {}),
+  };
+}
+
+// Materialize only at dispatch, never while describing/speculating a launch.
+// Keep npm ci's cache outside node_modules and ignored without changing a
+// repository's tracked ignore rules or granting access to the operator's cache.
+export function prepareRuntimeCache(cwd, env) {
+  if (!cwd || env.NPM_CONFIG_CACHE !== runtimeEnvironment({}, process.execPath, cwd).NPM_CONFIG_CACHE) return;
+  const ignore = repositoryPath(cwd, ".cache/gallivant/npm/.gitignore", { createParents: true });
+  try { writeFileSync(ignore, "*\n", { flag: "wx", mode: 0o600 }); }
+  catch (error) {
+    if (error.code !== "EEXIST" || readFileSync(ignore, "utf8") !== "*\n") throw error;
+  }
+}
+
+export function sessionExports(node = process.execPath, cwd) {
+  const env = runtimeEnvironment({}, node, cwd);
+  return `export PATH=${shellQuote(dirname(node))}:"$PATH"\n` +
+    Object.entries(env).filter(([key]) => key !== "PATH").map(([key, value]) => `export ${key}=${shellQuote(value)}\n`).join("");
+}
+
+export function runtimeReadPaths(node = process.execPath) {
+  const paths = [realpathSync(node)];
+  for (const name of ["npm", "npx", "pnpm", "corepack"]) {
+    let target;
+    try { target = realpathSync(join(dirname(node), name)); } catch { continue; }
+    let directory = dirname(target);
+    for (let depth = 0; depth < 5; depth++) {
+      try {
+        const pkg = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
+        if (["npm", "pnpm", "corepack"].includes(pkg.name)) { paths.push(directory); break; }
+      } catch {}
+      const parent = dirname(directory);
+      if (parent === directory) break;
+      directory = parent;
+    }
+  }
+  return [...new Set(paths)];
+}
+
+export const RUNTIME_SETTINGS_FILE = "runtime-settings.json";
+
+export function claudeRuntimeSettings(settings, destination, node = process.execPath) {
+  if (!settings) return settings;
+  // Leave missing settings to the native client's existing error handling.
+  let source;
+  try { source = readFileSync(settings, "utf8"); }
+  catch (error) { if (error.code === "ENOENT") return settings; throw error; }
+  const original = JSON.parse(source);
+  const command = `${shellQuote(node)} ${shellQuote(fileURLToPath(new URL("../bin/session-runtime.mjs", import.meta.url)))}`;
+  const merged = {
+    ...original,
+    sandbox: {
+      ...original.sandbox,
+      filesystem: {
+        ...original.sandbox?.filesystem,
+        allowRead: [...new Set([...(original.sandbox?.filesystem?.allowRead || []), ...runtimeReadPaths(node)])],
+      },
+    },
+    hooks: {
+      ...original.hooks,
+      SessionStart: [...(original.hooks?.SessionStart || []), { hooks: [{ type: "command", command }] }],
+    },
+  };
+  // The actual launcher owns this private file, outside the checkout. Exclusive
+  // creation refuses symlinks/existing snapshots and never edits source settings.
+  const content = JSON.stringify(merged), fd = openSync(destination, "wx", 0o600);
+  try { writeFileSync(fd, content); }
+  catch (error) { rmSync(destination, { force: true }); throw error; }
+  finally { closeSync(fd); }
+  return destination;
+}

package/lib/runtime_dependencies.mjs

@@ -0,0 +1,15 @@
+// Stable dependency constructors for Node adapter integrations and conformance.
+export { makeState, newEntry, STATES, idSlug } from "./state.mjs";
+export { DEFAULTS, DEFAULT_DELIVERABLE } from "./config.mjs";
+export { silentLog, makeLog } from "./log.mjs";
+export { NO_IDENTITY } from "./identity.mjs";
+export { MIN_VERSIONS, PREPARATION_BOUNDARY } from "./harness.mjs";
+export { readJson, writeJsonAtomic, writeText } from "./fs.mjs";
+export { collectCommands } from "./task_contract.mjs";
+export { logWindow, appendProjection } from "./run_log.mjs";
+export { makeTick } from "./tick.mjs";
+export { requestControl, controlAvailability } from "./control.mjs";
+export { ready } from "./commands/ready.mjs";
+export { normalizePublicBody } from "./block.mjs";
+export { criteriaFromPrd } from "./deliverable.mjs";
+export { parsePrd } from "./prd.mjs";