@awebai/oats 0.22.2 → 0.22.4

package/lib/servers.mjs

@@ -17,6 +17,7 @@
  */
 
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
@@ -112,7 +113,16 @@ export function targetOf(server) {
 /** argv for the local ssh process that runs one remote oats command. `--`
  *  ends ssh's own options so a host alias can never be read as one; the
  *  remote command is one quoted string, as ssh requires. */
-export function sshArgv(target, oatsArgs) {
+/** A stable key for a route target: two registrations may name the same
+ *  host and workspace, and a registration may change; groups and guards key
+ *  on the target, never on the registry id alone. */
+export function targetKey(target) {
+  // Host and workspace only: the binary path (like --path and --label) is how
+  // to reach the same homes, not which homes; each snapshot keeps its own.
+  return createHash("sha256").update(`${target.sshHost}\0${target.workspace}`).digest("hex").slice(0, 12);
+}
+
+export function sshArgv(target, oatsArgs, { cwd } = {}) {
   // A non-interactive ssh command runs in the login shell's minimal PATH,
   // which rarely includes user-local tool directories (~/.local/bin, where
   // claude and pi commonly live). A registration may name directories to
@@ -122,7 +132,9 @@ export function sshArgv(target, oatsArgs) {
   // one and never touches the other.
   const dirs = target.path ? target.path.split(":").filter(Boolean).map((d) => (d.startsWith("~/") ? `"$HOME"${remoteQuote(d.slice(1))}` : remoteQuote(d))) : [];
   const prefix = dirs.length ? `PATH=${dirs.join(":")}:"$PATH" ` : "";
-  const cmd = prefix + [target.oatsPath, ...oatsArgs].map(remoteQuote).join(" ");
+  // An optional working directory for commands that read their instance
+  // from cwd (oats okf harvest): a quoted cd, never a path from the caller.
+  const cmd = (cwd ? `cd ${remoteQuote(cwd)} && ` : "") + prefix + [target.oatsPath, ...oatsArgs].map(remoteQuote).join(" ");
   return ["ssh", ...SSH_OPTS, "--", target.sshHost, cmd];
 }
 
@@ -168,7 +180,7 @@ export function parseRemoteEnvelope(stdout) {
  *  refused key, unknown host) surface as E_SSH with ssh's stderr. */
 export function runRemote(target, oatsArgs, io = {}) {
   const exec = io.execFileSync || execFileSync;
-  const [bin, ...argv] = sshArgv(target, oatsArgs);
+  const [bin, ...argv] = sshArgv(target, oatsArgs, { cwd: io.cwd });
   let stdout = "";
   let stderr = "";
   let status = 0;
@@ -217,6 +229,7 @@ export function checkRemote(target, io = {}) {
     sessionBackends: list("sessionBackends", []),
     launchOptions: list("launchOptions", []),
     remote: list("remote", []),
+    features: list("features", []),
     advertised: Array.isArray(probe.runtimes),
   };
 }
@@ -316,6 +329,17 @@ export function removeSnapshot(serverId, instance) {
   rmSync(snapshotPath(serverId, instance), { force: true });
 }
 
+/** Drop a saved route on purpose: the remote instance is gone (retired on the
+ *  host, home removed, host rebuilt) and nothing routed can remove the
+ *  snapshot any more. The operator's decision, never automatic. */
+export function forgetSnapshot(serverId, instance) {
+  const p = snapshotPath(serverId, instance);
+  if (!existsSync(p)) throw serverError("E_SNAPSHOT_UNKNOWN", `no saved route for ${instance} through server ${serverId} (oats server roster --json)`);
+  const snap = readSnapshot(serverId, instance);
+  rmSync(p, { force: true });
+  return snap;
+}
+
 export function listSnapshots(serverId) {
   const dir = join(REMOTE_SNAPSHOT_DIR(), serverId);
   if (!existsSync(dir)) return [];
@@ -344,7 +368,7 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
   // A retirement may outlive its registration: the snapshot taken at spawn
   // is the route, and it is consulted before the registry is required.
   const instanceArg = oatsArgs.find((a) => !a.startsWith("--"));
-  const snap = cmd === "retire" && instanceArg ? readSnapshot(serverId, instanceArg) : undefined;
+  const snap = ["retire", "harvest"].includes(cmd) && instanceArg ? readSnapshot(serverId, instanceArg) : undefined;
   let server = io.server;
   if (!server) {
     try { server = getServer(serverId); }
@@ -355,7 +379,22 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
   const json = (args) => (args.includes("--json") ? args : [...args, "--json"]);
 
   if (cmd === "spawn") {
+    // A registration edited to another target must not overwrite the saved
+    // routes of instances spawned through the old one: the next snapshot for
+    // the same name would silently retarget them. Refuse, naming the remedy.
+    const priorTargets = listSnapshots(serverId).filter((s) => s.target && targetKey(s.target) !== targetKey(target));
+    if (priorTargets.length) {
+      const old = priorTargets[0].target;
+      throw serverError("E_ROUTE_CHANGED", `server ${serverId} now points at ${target.sshHost}:${target.workspace}, but ${priorTargets.length} saved route${priorTargets.length === 1 ? "" : "s"} for it (${priorTargets.map((s) => s.instance).join(", ")}) target ${old.sshHost}:${old.workspace}; spawning would overwrite them. Keep the old registration and add a new server id for the new target, or retire those instances first`);
+    }
     const remote = checkRemote(target, io);
+    // A saved route is keyed by name under its server id. An explicit name
+    // that already has one here would overwrite that route on success: refuse
+    // before the mutation (the roster shows the existing route; forget or
+    // retire it first).
+    const ii = oatsArgs.indexOf("--instance");
+    const explicitName = ii >= 0 && oatsArgs[ii + 1] && !oatsArgs[ii + 1].startsWith("--") ? oatsArgs[ii + 1] : undefined;
+    if (explicitName && readSnapshot(serverId, explicitName)) throw serverError("E_ROUTE_EXISTS", `a saved route for ${explicitName} through server ${serverId} already exists (${readSnapshot(serverId, explicitName).home}); retire it (oats retire ${explicitName} --server ${serverId}) or drop it (oats server forget ${serverId} --instance ${explicitName}) before spawning that name again`);
     // The remote roster: the soul's runtime default for the support check,
     // and the remote agents root for the snapshot (the kernel's spawn result
     // does not carry it, and guessing it from the workspace would be wrong
@@ -365,6 +404,18 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
     checkRemoteSupport(remote, target, oatsArgs, status.result);
     const { envelope, stderr } = runRemote(target, json(withScope(["spawn", ...oatsArgs])), io);
     if (envelope.ok && envelope.result?.instance) {
+      // A generated name can still collide with a saved route of another
+      // soul on the same host (dev --purpose foo-1 vs dev-foo --purpose 1).
+      // The existing route is never overwritten: the new instance is
+      // reported without a saved route, to be retired on the host by --home.
+      // An existing route is replaced only by a result that provably names
+      // the same home; absent data is never permission to overwrite it.
+      const prior = readSnapshot(serverId, envelope.result.instance);
+      const sameAsPrior = prior && prior.home && envelope.result.home && resolve(prior.home) === resolve(envelope.result.home);
+      if (prior && !sameAsPrior) {
+        const warnings = [...(envelope.result.warnings || []), `no saved route: ${envelope.result.instance} already names ${prior.home} through ${serverId}; this instance (${envelope.result.home}) is not managed from here, retire it on the host with oats retire ${envelope.result.instance} --home ${envelope.result.home}`];
+        return { envelope: { ...envelope, result: { ...envelope.result, server: serverId, target, snapshot: null, routeConflict: { instance: envelope.result.instance, existingHome: prior.home }, warnings } }, stderr };
+      }
       const snapshot = writeSnapshot(serverId, target, remote, { ...envelope.result, agentsRoot: envelope.result.agentsRoot || status.result.root });
       return { envelope: { ...envelope, result: { ...envelope.result, server: serverId, target, snapshot: snapshotPath(serverId, envelope.result.instance) } }, stderr, snapshot };
     }
@@ -372,8 +423,29 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
   }
   if (cmd === "retire") {
     const name = instanceArg;
-    checkRemote(target, io); // a mutation: version and envelope first, like spawn
-    const { envelope, stderr } = runRemote(target, json(withScope(["retire", ...oatsArgs])), io);
+    const remote = checkRemote(target, io); // a mutation: version and envelope first, like spawn
+    // The saved route knows WHICH home was spawned through it; a remote kernel
+    // that resolves --home retires that one, never a same-named twin. A
+    // caller's explicit --home must be that same home: anything else would
+    // retire a sibling and then drop this instance's saved route.
+    const hi = oatsArgs.indexOf("--home");
+    const explicitHome = hi >= 0 && oatsArgs[hi + 1] && !oatsArgs[hi + 1].startsWith("--") ? oatsArgs[hi + 1] : undefined;
+    if (explicitHome && snap?.home && resolve(explicitHome) !== resolve(snap.home)) throw serverError("E_HOME_MISMATCH", `--home ${explicitHome} is not the saved route of ${name} on ${serverId} (${snap.home}); retire the saved one, or retire the other instance on the host by its own name`);
+    const remoteRetiresByHome = Array.isArray(remote?.features) && remote.features.includes("retire-home");
+    const wantHome = explicitHome || snap?.home;
+    if (wantHome && !remoteRetiresByHome) {
+      // An older kernel ignores --home and retires by name, first match. It
+      // is safe only when the name is unique there and is the saved home;
+      // an explicit --home is never sent where it cannot be honoured.
+      if (explicitHome) throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost} cannot retire by home (0.22.3 or later does); upgrade it there, or retire ${name} without --home once it is the only instance of that name`);
+      const st = runRemote(target, ["status", "--json", "--dir", target.workspace], io).envelope;
+      if (!st.ok) throw serverError(st.error?.code || "E_REMOTE", `cannot check ${name} on ${serverId} before retiring by name: ${st.error?.message || "status failed"}`);
+      const twins = (st.result?.agents || []).flatMap((a) => (a.instances || []).filter((i) => i.instance === name).map((i) => ({ agent: a.name, home: i.home })));
+      if (twins.length > 1) throw serverError("E_REMOTE_INCOMPATIBLE", `${name} names ${twins.length} instances on ${serverId} (${twins.map((t) => t.agent).join(", ")}) and remote oats ${remote.version} retires by name only; upgrade it to 0.22.3 or later so the saved home is retired and not a twin`);
+      if (twins.length === 1 && twins[0].home && resolve(twins[0].home) !== resolve(wantHome)) throw serverError("E_HOME_MISMATCH", `the only ${name} on ${serverId} lives at ${twins[0].home}, not at the saved route ${wantHome}; the saved route is stale (oats server roster --json)`);
+    }
+    const homeArgs = remoteRetiresByHome && wantHome && !explicitHome ? ["--home", wantHome] : [];
+    const { envelope, stderr } = runRemote(target, json(withScope(["retire", ...oatsArgs, ...homeArgs])), io);
     // The snapshot goes only when the remote home is gone: not on incomplete
     // cleanup, and not on a deferred completion still on its way there.
     if (envelope.ok && name && envelope.result?.removedDir !== false && !envelope.result?.rollbackIncomplete && !envelope.result?.deferred) removeSnapshot(serverId, name);
@@ -381,11 +453,120 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
     // not: an incomplete cleanup is exactly when the operator needs the host.
     return { envelope: envelope.result ? { ...envelope, result: { ...envelope.result, server: serverId, target } } : envelope, stderr };
   }
+  if (cmd === "harvest") {
+    // `oats okf harvest --json` reads its instance from cwd: run it in the
+    // SAVED home of an instance spawned through this route (no path from
+    // the caller), relaying the package's own envelope.
+    const name = instanceArg;
+    if (!snap?.home) throw serverError("E_SNAPSHOT_UNKNOWN", `no remote instance ${JSON.stringify(name || "")} spawned through server ${serverId} from this machine (oats server roster --json)`);
+    // A mutation on the host (it spawns a harvester there): version and
+    // envelope first. The remote list is a kernel-version proxy (0.22.3
+    // introduced this route and the envelope boundary it relies on); an
+    // older okf package there would still answer outside the envelope, which
+    // then fails as E_REMOTE_ENVELOPE rather than as a bad harvest.
+    const remote = checkRemote(target, io);
+    if (!Array.isArray(remote.remote) || !remote.remote.includes("harvest")) throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost} does not route okf harvest (0.22.3 or later does)`);
+    const { envelope, stderr } = runRemote(target, ["okf", "harvest", "--json"], { ...io, cwd: snap.home });
+    // The package's result names the HARVESTER it spawned (instance, window);
+    // the routing context goes under its own keys.
+    return { envelope: envelope.result ? { ...envelope, result: { ...envelope.result, server: serverId, sourceInstance: name, sourceHome: snap.home } } : envelope, stderr };
+  }
   if (cmd === "status") {
     const { envelope, stderr } = runRemote(target, json(withScope(["status", ...oatsArgs])), io);
     return { envelope: envelope.ok ? { ...envelope, result: { ...envelope.result, server: serverId, target, snapshots: listSnapshots(serverId) } } : envelope, stderr };
   }
-  throw serverError("E_USAGE", `--server routes spawn, retire, status and session attach only (not ${cmd})`);
+  throw serverError("E_USAGE", `--server routes spawn, retire, status, session and okf harvest only (not ${cmd})`);
+}
+
+// ------------------------------------------------------------------- roster
+
+// The roster answers within a budget the Desktop can wait for (its adapter
+// allows 60 s): each target gets the smaller of its own allowance and what is
+// left, and targets the budget cannot reach are reported as such, never
+// dropped and never allowed to sink the healthy groups.
+export const ROSTER_BUDGET_MS = 45000;
+export const ROSTER_PER_TARGET_TIMEOUT_MS = 20000;
+
+function listSnapshotServers() {
+  const dir = REMOTE_SNAPSHOT_DIR();
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory() && ID_RE.test(e.name)).map((e) => e.name);
+}
+
+/** The remote roster, grouped by server id and saved route target: one
+ *  bounded status pull per group, registrations unioned with saved routes so
+ *  a removed or changed registration keeps its group (registrationPresent
+ *  false) and its instances from the snapshots (running null when the probe
+ *  fails). Remote state is pulled, never cached; the saved route stays the
+ *  action authority. */
+export function rosterGroups({ server, io = {} } = {}) {
+  const started = Date.now();
+  if (server && !ID_RE.test(server)) throw serverError("E_BAD_ARGS", `server id ${JSON.stringify(server)} is not a valid id`);
+  if (server && !readServers()[server] && !existsSync(join(REMOTE_SNAPSHOT_DIR(), server))) throw serverError("E_SERVER_UNKNOWN", `no server registered as ${JSON.stringify(server)} and no saved routes for it (oats server list)`);
+  const perTargetTimeoutMs = io.perTargetTimeoutMs || ROSTER_PER_TARGET_TIMEOUT_MS;
+  const budgetMs = io.budgetMs || ROSTER_BUDGET_MS;
+  let skipped = 0;
+  const servers = readServers();
+  const groups = new Map();
+  const add = (serverId, target, registrationPresent, label) => {
+    const key = `${serverId}:${targetKey(target)}`;
+    if (!groups.has(key)) groups.set(key, { id: key, server: serverId, label: label || serverId, registrationPresent, target, probe: null, agentsRoot: undefined, souls: [], instances: [], retireFailures: [], _snapshots: [] });
+    const g = groups.get(key);
+    if (registrationPresent) g.registrationPresent = true;
+    return g;
+  };
+  for (const [id, s] of Object.entries(servers)) { if (server && id !== server) continue; add(id, targetOf({ id, ...s }), true, s.label); }
+  for (const serverId of listSnapshotServers()) {
+    if (server && serverId !== server) continue;
+    for (const snap of listSnapshots(serverId)) { if (!snap.target) continue; add(serverId, snap.target, false, servers[serverId]?.label)._snapshots.push(snap); }
+  }
+  for (const g of groups.values()) {
+    let status;
+    const remaining = budgetMs - (Date.now() - started);
+    if (remaining < 1000) {
+      skipped++;
+      g.probe = { ok: false, error: { code: "E_ROSTER_BUDGET", message: `not probed: the ${budgetMs} ms roster budget was used up by earlier targets` } };
+    } else {
+      try { status = runRemote(g.target, ["status", "--json", "--dir", g.target.workspace], { ...io, timeoutMs: Math.min(perTargetTimeoutMs, remaining) }).envelope; }
+      catch (e) { g.probe = { ok: false, error: { code: e.code || "E_SSH", message: e.message } }; }
+    }
+    if (status && !status.ok) g.probe = { ok: false, error: status.error || { code: "E_REMOTE", message: "status failed" } };
+    // A saved route matches a remote row by name AND home: a same-named
+    // twin under another soul on the host is observed only, never given the
+    // route (the route's own row is appended as stale if the host no longer
+    // lists that home).
+    const bySnapshot = new Map(g._snapshots.map((s) => [s.instance, s]));
+    const routeOf = (i) => { const s = bySnapshot.get(i.instance); return s && s.home && i.home && resolve(s.home) === resolve(i.home) ? s : undefined; };
+    if (status?.ok) {
+      g.probe = { ok: true };
+      g.agentsRoot = status.result.root;
+      for (const a of status.result.agents || []) {
+        g.souls.push({ name: a.name, runtime: a.runtime, work: a.work, backend: a.backend, description: a.description, agentsRoot: status.result.root });
+        // A failed deferred self-retirement needs an operator: it rides with
+        // the group, named by agent and instance, as `oats status` prints it.
+        for (const f of a.retireFailures || []) g.retireFailures.push({ agent: a.name, ...f });
+        for (const i of a.instances || []) {
+          const snap = routeOf(i);
+          g.instances.push({
+            server: g.server, instance: i.instance, agent: a.name, home: i.home || snap?.home, agentsRoot: status.result.root,
+            runtime: i.runtime || null, backend: i.sessionTarget?.backend || (i.tmux ? "tmux" : null),
+            ...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}), ...(i.tmux ? { tmux: i.tmux } : {}),
+            running: typeof i.running === "boolean" ? i.running : null, ...(i.runtimeError ? { runtimeError: i.runtimeError } : {}),
+            retirePending: !!i.retirePending, rollbackIncomplete: !!i.rollbackIncomplete, savedRoute: !!snap, missingRemotely: false,
+          });
+          if (snap) bySnapshot.delete(i.instance);
+        }
+      }
+    }
+    // Saved routes the remote did not list: with a good probe that means the
+    // instance is gone there (retired, or its home removed) and the route is
+    // stale; with a failed probe nothing is known. Same keys as remote rows.
+    for (const snap of bySnapshot.values()) {
+      g.instances.push({ server: g.server, instance: snap.instance, agent: snap.agent, home: snap.home, agentsRoot: snap.agentsRoot, runtime: snap.runtime || null, backend: null, running: null, retirePending: false, rollbackIncomplete: false, savedRoute: true, missingRemotely: g.probe?.ok === true });
+    }
+    delete g._snapshots;
+  }
+  return { groups: [...groups.values()], bounds: { budgetMs, perTargetTimeoutMs, elapsedMs: Date.now() - started, skipped } };
 }
 
 /** argv for an INTERACTIVE remote command (a viewer attach): ssh with a PTY,
@@ -397,8 +578,14 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
  *  target with a caller-supplied absolute remote home. Nothing about the
  *  remote binary or path ever comes from the caller. */
 export function resolveRoute(serverId, { instance, home } = {}, what = "session") {
-  const snap = instance ? readSnapshot(serverId, instance) : undefined;
+  // The home is the identity (same-named twins on one host are different
+  // instances); a name alone resolves through its saved route. With a home,
+  // the saved route that owns it supplies the target (a registration edited
+  // later never re-routes a viewer); a name AND a home must agree.
+  let snap = instance ? readSnapshot(serverId, instance) : undefined;
   if (instance && !snap) throw serverError("E_SNAPSHOT_UNKNOWN", `no remote instance ${JSON.stringify(instance)} spawned through server ${serverId} from this machine (oats status --server ${serverId})`);
+  if (home && snap?.home && resolve(snap.home) !== resolve(home)) throw serverError("E_HOME_MISMATCH", `--home ${home} is not the saved route of ${instance} on ${serverId} (${snap.home})`);
+  if (home && !snap) snap = listSnapshots(serverId).find((s) => s.home && resolve(s.home) === resolve(home));
   const target = snap?.target || targetOf(getServer(serverId));
   const remoteHome = home || snap?.home;
   if (!remoteHome || !String(remoteHome).startsWith("/")) throw serverError("E_BAD_ARGS", `${what} --server needs --instance <name> (spawned from here) or --home </absolute/remote/home>`);

package/lib/session-input.mjs

@@ -6,7 +6,9 @@ import { inspectHerdr, inputHerdr, herdrCommand } from "./herdr.mjs";
 
 const shells = new Set(["sh", "bash", "zsh", "fish", "dash", "ksh", "login"]);
 function tmux(target, args, { exec = execFileSync, input } = {}) {
-  return exec("tmux", ["-S", target.socket, ...args], {
+  // launchd does not supply a UTF-8 locale. In that environment tmux replaces
+  // the tab delimiters in list-panes output with underscores unless forced.
+  return exec("tmux", ["-u", "-S", target.socket, ...args], {
     encoding: "utf8", input, timeout: 10000, maxBuffer: 1024 * 1024,
     stdio: ["pipe", "pipe", "pipe"],
   });

package/lib/session-viewer.mjs

@@ -10,7 +10,9 @@ export function prepareSessionViewer(target, { exec = execFileSync } = {}) {
     delete env.HERDR_SESSION;
     return { binary: target.binary, args: ["terminal", "attach", target.terminalId], env, cleanup() {} };
   }
-  const run = (args) => exec("tmux", ["-S", target.socket, ...args], {
+  // UTF-8 mode (-u) like the shared session helper: a service without a
+  // UTF-8 locale (launchd) otherwise mangles tmux output.
+  const run = (args) => exec("tmux", ["-u", "-S", target.socket, ...args], {
     encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "pipe"],
   }).trim();
   const viewer = `oatsview-${process.pid}-${randomUUID().slice(0, 8)}`;
@@ -28,7 +30,7 @@ export function prepareSessionViewer(target, { exec = execFileSync } = {}) {
     run(["bind-key", "-T", "oatsview-locked", "WheelUpPane", "if-shell", "-F", "#{||:#{pane_in_mode},#{mouse_any_flag}}", "send-keys -M", "copy-mode -e; send-keys -M"]);
     run(["set-option", "-t", viewer, "mouse", "on"]);
     const env = { ...process.env }; delete env.TMUX;
-    return { binary: "tmux", args: ["-S", target.socket, "attach-session", "-t", `=${viewer}`], env, cleanup };
+    return { binary: "tmux", args: ["-u", "-S", target.socket, "attach-session", "-t", `=${viewer}`], env, cleanup };
   } catch (e) { cleanup(); throw e; }
 }
 

package/package-catalog.json

@@ -7,7 +7,7 @@
     },
     "oats.aweb": {
       "url": "https://github.com/awebai/oats-aweb.git",
-      "ref": "v1.9.0",
+      "ref": "v1.10.1",
       "path": "oats-package"
     },
     "oats.jira": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.22.2",
+  "version": "0.22.4",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",

package/packages/record/bin/recall.mjs

@@ -23,7 +23,7 @@ import { join } from "node:path";
 import process from "node:process";
 
 import { RecordStore } from "../lib/store.mjs";
-import { RecordIndex } from "../lib/index-db.mjs";
+import { extractTurnText, RecordIndex } from "../lib/index-db.mjs";
 
 function parseArgs(argv) {
   const args = { _: [] };
@@ -40,16 +40,19 @@ function parseArgs(argv) {
 const args = parseArgs(process.argv.slice(2));
 const root = args.root ?? process.env.TURN_RECORD_ROOT ?? join(homedir(), ".turn-record");
 const store = new RecordStore(root, {});
-const index = new RecordIndex(store);
+let index;
+const getIndex = () => (index ??= new RecordIndex(store));
 
 try {
   if (args.reindex) {
+    const index = getIndex();
     index.rebuild();
     console.log(JSON.stringify(index.counts()));
     process.exit(0);
   }
 
   if (args.show) {
+    const index = getIndex();
     const { resolveTurn } = await import("../lib/index-db.mjs");
     const byId = store.readAll();
     const turn = resolveTurn(store, index, args.show, byId);
@@ -111,7 +114,7 @@ try {
     // A window is a bounded read: a consumer that plans one (the OKF
     // harvester) sizes it with --ids-only first, then reads exactly that.
     const out = window.map((t) => {
-      const docs = index.extractText(t);
+      const docs = extractTurnText(t);
       const base = { id: t.id, ts: t.ts, thread: t.thread, kind: t.kind, source: t.provenance?.source ?? null };
       const full = { ...base, text: docs.map((d) => ({ role: d.role, text: d.text })) };
       // bytes = what this turn occupies in the pretty-printed --json answer,
@@ -123,6 +126,7 @@ try {
     process.exit(0);
   }
 
+  const index = getIndex();
   const limit = args.limit ? Number(args.limit) : 20;
   let rows;
   if (query) {
@@ -164,5 +168,5 @@ try {
     console.log(`    ${r.id}`);
   }
 } finally {
-  index.close();
+  index?.close();
 }

package/packages/record/lib/index-db.mjs

@@ -413,20 +413,7 @@ export class RecordIndex {
   // Text documents for one turn. Mail/chat: one doc. Session: one doc per
   // conversational event extracted from the transcript blob.
   extractText(turn) {
-    if (turn.kind === "note" && turn.body?.segment) return []; // dedicated role "segment" row
-    if (turn.kind === "mail" || turn.kind === "chat" || turn.kind === "note") {
-      const subject = turn.body?.subject ?? "";
-      const text = turn.body?.text ?? "";
-      const joined = subject ? subject + "\n" + text : text;
-      return joined.trim() ? [{ loc: "", role: turn.kind, text: joined }] : [];
-    }
-    if (turn.kind === "session" && typeof turn.body?.line === "string") {
-      const loc = `line:${turn.provenance?.origin?.line ?? 0}`;
-      return extractSessionTextFor(turn.provenance?.source, Buffer.from(turn.body.line, "utf8")).map(
-        (d) => ({ ...d, loc }),
-      );
-    }
-    return [];
+    return extractTurnText(turn);
   }
 
   // FTS query with optional filters. Returns rows with turn metadata and a
@@ -502,6 +489,24 @@ export class RecordIndex {
   }
 }
 
+// Journal text extraction is independent of the derived search database.
+export function extractTurnText(turn) {
+  if (turn.kind === "note" && turn.body?.segment) return []; // dedicated role "segment" row
+  if (turn.kind === "mail" || turn.kind === "chat" || turn.kind === "note") {
+    const subject = turn.body?.subject ?? "";
+    const text = turn.body?.text ?? "";
+    const joined = subject ? subject + "\n" + text : text;
+    return joined.trim() ? [{ loc: "", role: turn.kind, text: joined }] : [];
+  }
+  if (turn.kind === "session" && typeof turn.body?.line === "string") {
+    const loc = `line:${turn.provenance?.origin?.line ?? 0}`;
+    return extractSessionTextFor(turn.provenance?.source, Buffer.from(turn.body.line, "utf8")).map(
+      (d) => ({ ...d, loc }),
+    );
+  }
+  return [];
+}
+
 // Claude Code text extraction, re-exported for compatibility; the
 // per-format extractors live in formats.mjs.
 export const extractSessionText = extractCcText;