@awebai/oats 0.22.0

package/lib/tmux-config.mjs

@@ -0,0 +1,35 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const OATS_MOUSE_BLOCK = `# OATS: scroll agent windows normally with a mouse or trackpad.\nset -g mouse on\n`;
+
+/** Choose the tmux user config without creating a second competing config. */
+export function tmuxConfigPath(home = homedir(), env = process.env) {
+  const legacy = join(home, ".tmux.conf");
+  const xdg = join(env.XDG_CONFIG_HOME || join(home, ".config"), "tmux", "tmux.conf");
+  return existsSync(legacy) || !existsSync(xdg) ? legacy : xdg;
+}
+
+/** Whether the selected config explicitly enables tmux mouse support. */
+export function tmuxMouseEnabled(text) {
+  return text.split("\n").some((line) => {
+    const active = line.replace(/\s+#.*$/, "").trim();
+    return /^(?:set|set-option)(?:\s+-[a-zA-Z]+)*\s+mouse\s+(?:on|1)\s*$/.test(active);
+  });
+}
+
+/** Add the setting once and reload a running tmux server when possible. */
+export function enableTmuxMouse(configPath = tmuxConfigPath()) {
+  const before = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+  if (tmuxMouseEnabled(before)) return { changed: false, configPath, reloaded: false };
+
+  mkdirSync(dirname(configPath), { recursive: true });
+  const separator = before.length === 0 || before.endsWith("\n\n") ? "" : before.endsWith("\n") ? "\n" : "\n\n";
+  appendFileSync(configPath, separator + OATS_MOUSE_BLOCK);
+
+  const server = spawnSync("tmux", ["has-session"], { stdio: "ignore" });
+  const reloaded = server.status === 0 && spawnSync("tmux", ["source-file", configPath], { stdio: "ignore" }).status === 0;
+  return { changed: true, configPath, reloaded };
+}

package/package-catalog.json

@@ -0,0 +1,44 @@
+{
+  "packages": {
+    "oats.okf": {
+      "url": "https://github.com/awebai/oats-okf.git",
+      "ref": "v1.4.1",
+      "path": "oats-package"
+    },
+    "oats.aweb": {
+      "url": "https://github.com/awebai/oats-aweb.git",
+      "ref": "v1.8.0",
+      "path": "oats-package"
+    },
+    "oats.jira": {
+      "url": "https://github.com/awebai/oats-jira.git",
+      "ref": "v1.0.0",
+      "path": "oats-package"
+    },
+    "oats.linear": {
+      "url": "https://github.com/awebai/oats-linear.git",
+      "ref": "v1.0.0",
+      "path": "oats-package"
+    },
+    "oats.authoring": {
+      "url": "https://github.com/awebai/oats-authoring.git",
+      "ref": "v1.0.0",
+      "path": "oats-package"
+    },
+    "oats.dev": {
+      "url": "https://github.com/awebai/oats-dev.git",
+      "ref": "v1.0.0",
+      "path": "oats-package"
+    }
+  },
+  "capabilities": {
+    "oats.review": "oats.dev",
+    "oas.okf": { "package": "oats.okf", "capability": "oats.okf" },
+    "oas.aweb": { "package": "oats.aweb", "capability": "oats.aweb" },
+    "oas.jira": { "package": "oats.jira", "capability": "oats.jira" },
+    "oas.linear": { "package": "oats.linear", "capability": "oats.linear" },
+    "oas.authoring": { "package": "oats.authoring", "capability": "oats.authoring" },
+    "oas.dev": { "package": "oats.dev", "capability": "oats.dev" },
+    "oas.review": { "package": "oats.dev", "capability": "oats.review" }
+  }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@awebai/oats",
+  "version": "0.22.0",
+  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
+  "keywords": [
+    "agents",
+    "oats",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/awebai/oats"
+  },
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "test": "node scripts/run-tests.mjs",
+    "check": "node --check lib/core.mjs && node --check lib/packages.mjs && node --check bin/oats.mjs",
+    "check:pi": "node --experimental-strip-types --check packages/pi/extension/index.ts",
+    "validate": "node scripts/validate-project.mjs",
+    "validate:okf": "node scripts/validate-okf.mjs",
+    "pack:check": "node scripts/check-package-dry-runs.mjs",
+    "smoke:tarball": "node scripts/clean-room-smoke.mjs"
+  },
+  "exports": {
+    ".": "./lib/core.mjs",
+    "./core": "./lib/core.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/",
+    "injects/",
+    "capabilities/",
+    "docs/",
+    "README.md",
+    "package-catalog.json",
+    "packages/record/bin/",
+    "packages/record/lib/",
+    "packages/record/docs/",
+    "packages/record/test/vectors/",
+    "packages/record/README.md",
+    "packages/record/package.json"
+  ],
+  "dependencies": {
+    "@awebai/pi": "^0.2.1"
+  },
+  "bin": {
+    "oats": "./bin/oats.mjs"
+  },
+  "devDependencies": {
+    "ajv": "8.17.1"
+  }
+}

package/packages/record/README.md

@@ -0,0 +1,151 @@
+# @awebai/turn-record
+
+The turn record: an append-only, content-addressed, replicated record of
+turns, with the core tools over it — `capture` and `recall`. The normative
+contract is [`docs/turn-record-sot.md`](docs/turn-record-sot.md) in this
+package; the conformance vectors under `test/vectors/` pin the format
+(`node test/vectors/validate.mjs`, dependency-free).
+
+Everything is a signed turn in an append-only record. This package is the
+core: gathering every conversation, keeping it durably, and finding it
+again. The experimental tools that select and synthesize over the record
+(dress, spawn, segments, mind) live in `packages/experimental` of the oats
+repo and run as `oats experimental <cmd>`; they are deliberately not part
+of this package.
+
+- **`lib/canonical.mjs`** — canonical JSON (integers only in the core),
+  `t1:` content ids, did:key Ed25519 verification. Byte-compatible with awid
+  message signing.
+- **`lib/store.mjs`** — the store: `streams/<owner>~<source>/journal.jsonl`
+  (owner-only append, torn-tail tolerant), `objects/sha256/` (immutable
+  blobs), `index/` (derived, never replicated). Merge is prefix extension
+  per stream + set union by id; non-prefix copies are quarantined, never
+  silently merged. Tombstones hide, v1 authority = author or record owner.
+- **`lib/project-aweb.mjs`** — projections of aweb messages (signed rows,
+  legacy rows, client comm logs, interaction logs) into turns. Pure
+  functions of the source: the same message projected on two machines gets
+  the same id, so replicas dedupe by union.
+- **`lib/capture-cc.mjs`** — session capture (Claude Code, pi, Codex via
+  the format registry in `formats.mjs`). Every native transcript record
+  becomes ONE turn holding the verbatim line (`body.line`), in a
+  per-session stream `<owner>~<source>.<session-id>`; capture is
+  incremental by source byte offset, so a growing session appends only its
+  new events — storage is linear in conversation size by construction, and
+  the original transcript is reconstructible by concatenating `body.line`.
+  Reconciliation is the capture (hooks/watchers only decide when to run
+  it).
+- **`lib/capture-aw.mjs`** — aw client log capture into `<owner>~aw`.
+- **`lib/index-db.mjs`** — derived SQLite FTS5 index (`node:sqlite`, no
+  dependencies). `update()` is incremental; `rebuild()` is reset + update
+  from zero (same code path). Session text is extracted per event with
+  exact line provenance; tombstoned turns disappear.
+- **`lib/segments.mjs`, `lib/tags.mjs`** — parsers for the note
+  conventions (segments, spawn notes, tags, outfits) that experimental
+  tools write into the record. They live here because the index reads
+  every note in the record; the machinery that writes and uses these
+  notes is experimental.
+
+## Install and run
+
+One shipped bin, `turn-record`, with three subcommands. From a checkout use
+`node bin/turn-record.mjs ...`; from an npm install (the package has zero
+dependencies and packs clean — `test/packaging.test.mjs` proves the tarball
+runs standalone) just `turn-record ...`. Inside an oats install the same
+commands are `oats capture|recall|setup`.
+
+```bash
+turn-record setup        # install Stop/SessionEnd hooks into every
+                         # ~/.claude*/settings.json, install the background
+                         # watcher (launchd on macOS, systemd user unit on
+                         # Linux), then run the first capture pass.
+                         # Idempotent; --dry-run previews; --owner overrides
+                         # the machine name.
+
+turn-record capture                  # one reconciliation pass, then index update
+turn-record capture --watch          # pass now, on filesystem change, every 15 min
+turn-record capture --status         # stream summary
+
+turn-record recall "sqlite fts"                 # search mail + chat + sessions together
+turn-record recall --kind mail --from acme/x q  # filters
+turn-record recall --thread aweb:conv:<id>      # list a thread chronologically
+turn-record recall --show t1:<hex>              # print one turn
+turn-record recall --reindex                    # full rebuild of the derived index
+```
+
+Store root: `--root`, else `$TURN_RECORD_ROOT`, else `~/.turn-record`.
+Stream owner: `--owner`, else `$TURN_RECORD_OWNER`, else the short hostname.
+
+## Ignoring sessions and paths (privacy)
+
+`<root>/ignore` is a plain text file of glob patterns, one per line (blank
+lines and `#` comments skipped). Any capture source file that matches is
+**never captured at all** — it is skipped before being opened, so no turn
+is appended and the offset cache never learns about it.
+This is a capture-time control, stronger than not indexing: the bytes never
+enter the record.
+
+```
+# never capture this session (any format), by session id
+7fe2a1b4-9c3d-4e21-b0aa-1f2e3d4c5b6a
+
+# never capture anything from this project's transcripts
+**/-Users-juanre-private-project/**
+
+# never capture one aw account's comm log
+acme-secret
+```
+
+Matching rules (deliberately minimal; no negation, no escapes):
+
+- a pattern containing `/` matches against the source file's absolute path;
+- a pattern without `/` matches against the file's basename and against its
+  session id (transcripts) or account name (aw comm logs);
+- `*` matches within a path segment, `**` across segments, `?` one
+  character; the whole candidate must match.
+
+Name-only patterns apply across every capture source: a short or generic
+pattern meant for one aw account can also catch a session file's basename
+or id in any format. Prefer path patterns for anything short or generic.
+
+Ignored files are counted in each pass (`N ignored` in capture output;
+`capture --status` shows the active pattern count), never skipped silently.
+The file is per record root and is local policy, not record truth — the
+sync guidance below replicates only `streams/` and `objects/`, so each
+machine decides what its own capture refuses to read; sync the `ignore`
+file yourself if you want one policy everywhere. Two honest limits: an
+ignore file that exists but cannot be read fails the pass loudly (a privacy
+control must not fail open), and ignoring is **forward-looking only** —
+turns already captured stay in the record; hide those with a tombstone.
+
+## Multi-machine
+
+Replicate `streams/` and `objects/` with any dumb file sync (syncthing,
+rsync, git); never sync `index/`. Owner-only append means concurrent sync
+cannot conflict; identical projections dedupe by id; a machine that sees a
+non-prefix copy of a stream quarantines it loudly.
+
+## Durability and concurrency
+
+Appends and merges run under a per-stream lockfile
+(`streams/<id>/.lock`, exclusive-create, stale after 30 s), because the
+torn-tail repair is a read-truncate-write sequence and hooks, watchers and
+manual passes can fire concurrently for the same owner. Sync tools may copy
+a `.lock` file; that cannot corrupt data, but a synced-in stale lock can
+delay a local `mergeStreamCopy` on that stream by up to the stale threshold
+(30 s), so excluding `.lock` from sync patterns is the right configuration. Journal writes fsync;
+note that on macOS `fsync(2)` does not guarantee media durability (that
+would need `F_FULLFSYNC`, which Node's fs API does not expose) — the
+guarantee is OS-crash-level, not power-loss-level.
+
+## Upgrading
+
+The derived index self-heals across schema changes by wiping and
+rebuilding (it is cache; there is no in-place migration). After upgrading
+this package, restart any long-running `capture --watch` process — a
+daemon holding the old database file open would otherwise keep indexing
+into an orphaned inode until it restarts.
+
+## Known costs, accepted for v1
+
+- Deletion via tombstone is eventual: an offline replica retains bytes until
+  it reconnects. The SOT says this plainly; so do we.

package/packages/record/bin/capture.mjs

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+// capture — land sessions and aw client logs in the turn record.
+//
+// The flag list lives in USAGE below, once, so `--help` and this header
+// cannot drift apart.
+//
+// An unrecognized flag or a positional argument is a usage error, never a
+// silently ignored option: parsing falls through to pass(), a WRITE, so it
+// must refuse what it does not understand before anything is written.
+//
+// Privacy: `<root>/ignore` lists glob patterns (paths, session ids,
+// accounts) whose sources are never captured — see lib/ignore.mjs.
+// Reconciliation is the capture; hooks and watch only decide when to run it.
+
+import { watch } from "node:fs";
+import { homedir, hostname } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+
+import { RecordStore } from "../lib/store.mjs";
+import { captureAllSessions } from "../lib/capture-cc.mjs";
+import { SESSION_FORMATS } from "../lib/formats.mjs";
+import { captureAwLogs, defaultCommLogDir } from "../lib/capture-aw.mjs";
+import { RecordIndex } from "../lib/index-db.mjs";
+import { IgnoreError, ignoreFilePath, loadIgnore } from "../lib/ignore.mjs";
+
+// Fail closed but actionably: an unreadable ignore file must stop capture,
+// as one clear line naming the file — never an uncaught stack trace.
+function loadIgnoreOrExit(recordRoot) {
+  try {
+    return loadIgnore(recordRoot);
+  } catch (err) {
+    console.error(err instanceof IgnoreError ? err.message : String(err));
+    process.exit(1);
+  }
+}
+
+// Every flag this program understands. An unknown flag is rejected rather
+// than ignored, because the fall-through from argument parsing is pass() —
+// a WRITE. `capture --help` was once a full reconciliation pass under a
+// hostname-derived owner, which forked the whole record into a second owner
+// namespace: 571 duplicate journals from one typo. Parsing must refuse what
+// it does not understand before anything can be written.
+const VALUE_FLAGS = new Set(["root", "owner"]);
+const BOOL_FLAGS = new Set([
+  "watch",
+  "status",
+  "install-hint",
+  "help",
+  "quiet",
+  "sessions-only",
+  "aw-only",
+  "no-index",
+]);
+
+const USAGE = `capture — land sessions and aw client logs in the turn record.
+
+  capture                      one reconciliation pass (sessions + aw logs)
+  capture --sessions-only      only session transcripts (Claude Code, pi, codex)
+  capture --aw-only            only aw client comm logs
+  capture --watch              pass now, then re-pass on filesystem change
+                               (debounced) and every 15 minutes regardless
+  capture --status             show store/stream summary, capture nothing
+  capture --install-hint       print the Claude Code hook snippet
+  capture --help               this text
+  capture --quiet              suppress per-pass progress
+  capture --no-index           append turns without updating the derived index
+
+  --root <dir>                 store root (else $TURN_RECORD_ROOT, else ~/.turn-record)
+  --owner <name>               stream owner (else $TURN_RECORD_OWNER, else short hostname)
+
+Every invocation with no explicit subcommand WRITES. Reconciliation is the
+capture; hooks and watch only decide when to run it.`;
+
+class UsageError extends Error {}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    // capture takes no positional arguments. Accepting one silently is the
+    // same defect as accepting an unknown flag: `capture status`, meaning
+    // `capture --status`, would run a full write pass instead.
+    if (!a.startsWith("--")) throw new UsageError(`unexpected argument "${a}" (capture takes no positional arguments)`);
+    const name = a.slice(2);
+    if (VALUE_FLAGS.has(name)) {
+      const value = argv[++i];
+      if (value === undefined) throw new UsageError(`${a} needs a value`);
+      args[name] = value;
+    } else if (BOOL_FLAGS.has(name)) {
+      args[name] = true;
+    } else {
+      throw new UsageError(`unknown flag ${a}`);
+    }
+  }
+  return args;
+}
+
+let args;
+try {
+  args = parseArgs(process.argv.slice(2));
+} catch (err) {
+  if (!(err instanceof UsageError)) throw err;
+  console.error(`capture: ${err.message}\n\n${USAGE}`);
+  process.exit(2);
+}
+
+if (args.help) {
+  console.log(USAGE);
+  process.exit(0);
+}
+
+const root = args.root ?? process.env.TURN_RECORD_ROOT ?? join(homedir(), ".turn-record");
+const ownerExplicit = args.owner !== undefined || process.env.TURN_RECORD_OWNER !== undefined;
+const owner = args.owner ?? process.env.TURN_RECORD_OWNER ?? hostname().split(".")[0];
+const quiet = Boolean(args.quiet);
+const store = new RecordStore(root, { owner });
+
+// The owner decides the stream namespace, and turn ids hash it into the
+// canonical core — so the same conversation captured under two owners yields
+// two sets of ids for identical content, which the index cannot dedupe. When
+// the derived owner is a stranger to a record that already has streams, say
+// so. A WARNING, never a refusal: capture runs on every agent's session hooks,
+// and a guard that misjudges would stop capture everywhere — strictly worse
+// than the duplication it prevents. First run on a new machine sees an empty
+// root, no other owners, and nothing is printed.
+function warnOnStrangerOwner() {
+  if (ownerExplicit) return;
+  let others;
+  try {
+    others = new Set(
+      store
+        .listStreams()
+        .map((id) => id.slice(0, id.indexOf("~")))
+        .filter(Boolean),
+    );
+  } catch {
+    return; // unreadable or absent root: not this function's business
+  }
+  if (others.size === 0 || others.has(owner)) return;
+  console.error(
+    `capture: writing as owner "${owner}" (from hostname), but this record holds ` +
+      `streams only under ${[...others].sort().map((o) => `"${o}"`).join(", ")}. ` +
+      `Pass --owner or set TURN_RECORD_OWNER if that is not what you meant — ` +
+      `capturing under a second owner duplicates the record rather than extending it.`,
+  );
+}
+
+function log(...parts) {
+  if (!quiet) console.log(...parts);
+}
+
+function pass() {
+  const out = { appended: 0 };
+  const ignore = loadIgnoreOrExit(root);
+  if (!args["aw-only"]) {
+    for (const r of captureAllSessions(store, { owner, ignore })) {
+      out.appended += r.appended;
+      const extras = [r.ignored ? `${r.ignored} ignored` : "", r.held ? `${r.held} held` : ""]
+        .filter(Boolean)
+        .join(", ");
+      log(
+        `sessions: ${r.sessions} scanned, ${r.appended} new turns in ${r.streams} sessions${extras ? ` (${extras})` : ""} -> ${r.stream}`,
+      );
+    }
+  }
+  if (!args["sessions-only"]) {
+    let awEntries = 0;
+    let awAppended = 0;
+    let awFailed = 0;
+    let awFiles = 0;
+    let awIgnored = 0;
+    for (const r of captureAwLogs(store, { owner, ignore })) {
+      if (r.ignored) {
+        awIgnored++;
+        continue;
+      }
+      awFiles++;
+      awEntries += r.entries;
+      awAppended += r.appended;
+      awFailed += r.failed;
+      out.appended += r.appended;
+      if (r.failed) console.error(`aw-log ${r.account}: ${r.failed} entries failed to project`);
+    }
+    const ignored = awIgnored ? `, ${awIgnored} ignored` : "";
+    log(`aw-logs: ${awFiles} files, ${awEntries} entries, ${awAppended} new, ${awFailed} failed${ignored}`);
+  }
+  if (out.appended > 0 && !args["no-index"]) {
+    const index = new RecordIndex(store);
+    try {
+      index.update();
+      log(`index: updated (${JSON.stringify(index.counts())})`);
+    } finally {
+      index.close();
+    }
+  }
+  return out;
+}
+
+if (args["install-hint"]) {
+  const self = new URL(import.meta.url).pathname;
+  console.log(`Add to Claude Code settings.json to capture on session stop/end:
+
+{
+  "hooks": {
+    "Stop":       [{"hooks": [{"type": "command", "command": "node ${self} --sessions-only --quiet"}]}],
+    "SessionEnd": [{"hooks": [{"type": "command", "command": "node ${self} --sessions-only --quiet"}]}]
+  }
+}
+
+A dropped hook is recovered by any later pass (capture, or capture --watch).`);
+  process.exit(0);
+}
+
+if (args.status) {
+  console.log(`root:  ${root}\nowner: ${owner}`);
+  const ignore = loadIgnoreOrExit(root);
+  if (ignore.size > 0) {
+    console.log(`ignore: ${ignore.size} pattern${ignore.size === 1 ? "" : "s"} (${ignoreFilePath(root)})`);
+  }
+  for (const streamId of store.listStreams()) {
+    console.log(`  ${streamId}: ${store.readStream(streamId).length} turns`);
+  }
+  process.exit(0);
+}
+
+warnOnStrangerOwner();
+pass();
+
+if (args.watch) {
+  const roots = [
+    ...Object.values(SESSION_FORMATS).flatMap((f) => f.defaultRoots()),
+    defaultCommLogDir(),
+  ];
+  let timer = null;
+  const schedule = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      try {
+        pass();
+      } catch (err) {
+        console.error(`capture pass failed: ${err.message}`);
+      }
+    }, 2000);
+  };
+  for (const dir of roots) {
+    try {
+      watch(dir, { recursive: true }, schedule);
+      log(`watching ${dir}`);
+    } catch (err) {
+      console.error(`cannot watch ${dir}: ${err.message}`);
+    }
+  }
+  setInterval(schedule, 15 * 60 * 1000); // reconcile even if events were missed
+}

package/packages/record/bin/recall.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// recall — search the turn record.
+//
+//   recall <query...>                 FTS5 query over mail, chat, sessions
+//   recall --kind mail <query...>     filter by kind (mail|chat|session|note)
+//   recall --thread <thread> [query]  filter/list by thread
+//   recall --from <name> <query...>   filter by speaker
+//   recall --limit N                  max results (default 20)
+//   recall --show <turn-id>           print one turn as JSON
+//   recall --reindex                  rebuild the derived index and exit
+//
+// Store root: --root, else $TURN_RECORD_ROOT, else ~/.turn-record
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+
+import { RecordStore } from "../lib/store.mjs";
+import { RecordIndex } from "../lib/index-db.mjs";
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (["--root", "--kind", "--thread", "--from", "--role", "--limit", "--show"].includes(a)) {
+      args[a.slice(2)] = argv[++i];
+    } else if (a.startsWith("--")) args[a.slice(2)] = true;
+    else args._.push(a);
+  }
+  return args;
+}
+
+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);
+
+try {
+  if (args.reindex) {
+    index.rebuild();
+    console.log(JSON.stringify(index.counts()));
+    process.exit(0);
+  }
+
+  if (args.show) {
+    const { resolveTurn } = await import("../lib/index-db.mjs");
+    const byId = store.readAll();
+    const turn = resolveTurn(store, index, args.show, byId);
+    if (!turn) {
+      console.error(`no turn ${args.show}`);
+      process.exit(1);
+    }
+    // Tombstoned turns are hidden from tool output, id lookup included.
+    if (store.hiddenIds(byId).has(args.show)) {
+      console.error(`turn ${args.show} is tombstoned`);
+      process.exit(1);
+    }
+    console.log(JSON.stringify(turn, null, 2));
+    process.exit(0);
+  }
+
+  const query = args._.join(" ").trim();
+  if (!query && !args.thread) {
+    console.error("usage: recall [--kind k] [--thread t] [--from f] [--role r] [--limit n] <query>");
+    process.exit(2);
+  }
+
+  const limit = args.limit ? Number(args.limit) : 20;
+  let rows;
+  if (query) {
+    rows = index.search(query, {
+      kind: args.kind,
+      thread: args.thread,
+      from: args.from,
+      role: args.role,
+      limit,
+    });
+  } else {
+    // Thread listing without a text query: chronological turns of a thread.
+    rows = index.db
+      .prepare(
+        `SELECT id, ts, from_name, to_name, thread, kind, source, stream, '' AS loc, kind AS role, '' AS snip
+         FROM turns WHERE thread = ? AND hidden = 0 AND superseded = 0
+         ORDER BY ts LIMIT ?`,
+      )
+      .all(args.thread, limit);
+  }
+
+  if (rows.length === 0) {
+    console.error("no matches");
+    process.exit(1);
+  }
+  for (const r of rows) {
+    const where = r.loc ? ` @${r.loc}` : "";
+    const to = r.to_name ? ` -> ${r.to_name}` : "";
+    console.log(`${r.ts}  [${r.kind}] ${r.from_name}${to}  ${r.thread ?? ""}${where}`);
+    if (r.snip) console.log(`    ${r.snip.replaceAll("\n", " ")}`);
+    console.log(`    ${r.id}`);
+  }
+} finally {
+  index.close();
+}