@gcunharodrigues/wrxn 0.18.2 → 0.19.0

package/manifest.json

@@ -208,6 +208,11 @@
       "class": "managed",
       "profile": "project"
     },
+    {
+      "path": ".claude/skills/chat-search/SKILL.md",
+      "class": "managed",
+      "profile": "project"
+    },
     {
       "path": ".claude/skills/memory/SKILL.md",
       "class": "managed",
@@ -548,6 +553,11 @@
       "class": "state",
       "profile": "project"
     },
+    {
+      "path": ".wrxn/chat-search.cjs",
+      "class": "managed",
+      "profile": "project"
+    },
     {
       "path": ".wrxn/wiki.cjs",
       "class": "managed",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gcunharodrigues/wrxn",
-  "version": "0.18.2",
+  "version": "0.19.0",
   "description": "WRXN Kernel — installable AI operating system. Two profiles (project | workspace), pull-based updates, managed/seeded/state file classes.",
   "bin": {
     "wrxn": "bin/wrxn.cjs"

package/payload/.claude/hooks/enforce-pipeline-adherence.cjs

@@ -8,6 +8,12 @@
 // and skipped anyway — so this is the hard speedbump that points the orchestrator back to the
 // right main-thread skill.
 //
+// SLICE #90 adds a second arm: a PreToolUse:Bash guard that catches a MAIN-THREAD skip — a
+// pipeline-bypassing shell command (gh issue/pr create, gh pr merge, trunk git push) run directly
+// in the main thread — and warns (default) or blocks (env knob) with the same redirect-to-skill
+// intent. Caller context (the `agent_id` stdin field) separates a skip from the identical command
+// run legitimately inside a typed-executor subagent. (ADR 0009.)
+//
 // AC-1 — HOOK EVENT DETERMINATION: PreToolUse:Task.
 //   Claude Code matches PreToolUse matchers against the TOOL NAME, and `Task` (the subagent-spawn
 //   tool) is a matchable tool name, so a `PreToolUse` entry with matcher `Task` fires BEFORE a
@@ -19,10 +25,13 @@
 // Self-contained: ships into installs, MUST NOT import the kernel lib (node stdlib only).
 // Fail-open: any parse error / missing field emits {} — the hook NEVER wedges a session.
 //
-// Contract: PreToolUse event JSON on stdin -> decision JSON on stdout (exit 0).
-//   allow -> {}        block -> { "decision": "block", "reason": "..." }
+// Contract: PreToolUse event JSON on stdin -> decision JSON on stdout (exit 0). main() dispatches on
+// tool_name:
+//   Task (delegation skip): allow -> {}   block -> { "decision": "block", "reason": "..." }  (legacy)
+//   Bash (main-thread skip): allow -> {}   warn/block -> { "hookSpecificOutput": { ... } }    (modern)
 
 const fs = require('fs');
+const { execFileSync } = require('child_process');
 
 // The six typed executors (mirrors lib/executor.cjs EXECUTORS keys — hardcoded here because the hook
 // is self-contained and cannot import the kernel lib). These ARE the pipeline; they are always allowed
@@ -80,6 +89,134 @@ function decide({ subagent_type, prompt } = {}) {
   return { block: true, reason: reasonFor(skills) };
 }
 
+// ── Bash arm (slice #90) — main-thread pipeline-skip detection ─────────────────────────
+// The Task arm above catches a DELEGATION skip (a HITL step handed to a non-typed agent).
+// This arm catches a MAIN-THREAD skip: the operator/assistant running a pipeline-bypassing
+// command directly (no Task spawn to intercept). The discriminator is CALLER CONTEXT, not the
+// command text: every legitimate pipeline mechanic (devops -> `wrxn ship`; all AFK executors)
+// runs inside a typed-executor SUBAGENT and so carries `agent_id` on the PreToolUse stdin —
+// auto-allowed. Only main-thread ops (`agent_id` absent) are candidates. (ADR 0009.)
+
+const SKILL_SPEC = 'to-prd / to-issues'; // the issue-filing pipeline skills
+const SKILL_SHIP = 'wrxn ship / the devops executor'; // the promotion pipeline path
+
+function bashMessage(verb, skill) {
+  return (
+    `Pipeline guard: running \`${verb}\` directly in the main thread bypasses the build pipeline. ` +
+    `Use ${skill} instead — the pipeline (and the server-side CI ruleset) is the gate, ` +
+    `not a manual main-thread command.`
+  );
+}
+
+function isTrunk(name) {
+  return name === 'main' || name === 'master';
+}
+
+// Normalize a `git push` target to a bare branch name before the trunk compare. Handles the refspec
+// forms that would otherwise evade the catch: a colon refspec (local:remote) targets the REMOTE side
+// (after the last ':'); a leading `+` is the force marker; `refs/heads/` is the fully-qualified prefix.
+// So `+main`, `refs/heads/main`, `+refs/heads/main`, `HEAD:main` all normalize to `main`. (security S2.)
+function normalizeRef(token) {
+  let ref = token.includes(':') ? token.split(':').pop() : token;
+  ref = ref.replace(/^\+/, ''); // strip a leading force marker
+  ref = ref.replace(/^refs\/heads\//, ''); // strip a fully-qualified branch prefix
+  return ref;
+}
+
+// Guarded, READ-ONLY shell-out: resolve the current branch for an argless / remote-only `git push`.
+// Any failure -> null, and the caller fails open to allow. This is the only side-effecting path; it
+// is injected into `decideBash` (default below) so every unit test drives it without spawning git.
+function currentBranch() {
+  try {
+    const out = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return out.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// Does this `git push` land on the trunk? Only a trunk push is a skip; feature-branch work is normal.
+function pushesToTrunk(cmd, resolveBranch) {
+  // Bounded ranges (not unbounded `[\s\S]*?`) keep this linear on the hot path. (security S1.)
+  const m = cmd.match(/\bgit\b[\s\S]{0,80}\bpush\b([\s\S]*)/);
+  const rest = m ? m[1] : '';
+  const positionals = rest.split(/\s+/).filter((t) => t && !t.startsWith('-'));
+  const refs = positionals.map(normalizeRef); // normalize force / fully-qualified / colon refspecs
+  if (refs.some(isTrunk)) return true; // an explicit main/master ref (any refspec form)
+  if (positionals.length >= 2) return false; // an explicit non-trunk branch was named
+  // no branch named (argless or remote-only) -> resolve the current branch
+  let branch = null;
+  try {
+    branch = resolveBranch();
+  } catch {
+    branch = null;
+  }
+  return branch ? isTrunk(branch) : false; // unresolvable -> fail open (allow)
+}
+
+// PURE: { command, agentId, level } -> { action: 'allow'|'warn'|'block', skill?, message? }.
+// Unit-tested apart from stdin (mirrors the Task arm's `decide()` seam). `resolveBranch` is an
+// injected boundary (defaults to a guarded `git rev-parse`) so the argless-push path stays testable.
+function decideBash({ command, agentId, level, resolveBranch = currentBranch } = {}) {
+  const cmd = typeof command === 'string' ? command : '';
+  if (!cmd.trim()) return { action: 'allow' }; // missing command -> fail open
+
+  if (agentId) return { action: 'allow' }; // spine: present = subagent = the pipeline -> allow
+
+  // Posture knob (default/unknown -> warn). `off` disables the Bash arm entirely (kill switch);
+  // the Task arm is never gated by the knob.
+  const raw = typeof level === 'string' ? level.trim().toLowerCase() : '';
+  const lvl = raw === 'block' || raw === 'off' ? raw : 'warn';
+  if (lvl === 'off') return { action: 'allow' };
+
+  // A catch command's action: `block` only under the block posture, else `warn`.
+  const catchAction = (verb, skill) => ({
+    action: lvl === 'block' ? 'block' : 'warn',
+    skill,
+    message: bashMessage(verb, skill),
+  });
+
+  // `gh issue create` is LOCKED to warn under every level (incl. block): to-prd/to-issues/triage
+  // run it themselves in the main thread, so a block would wedge the redirect skills. (ADR 0009 §4.)
+  if (/\bgh\b[\s\S]{0,80}\bissue\b[\s\S]{0,80}\bcreate\b/.test(cmd)) {
+    return { action: 'warn', skill: SKILL_SPEC, message: bashMessage('gh issue create', SKILL_SPEC) };
+  }
+
+  if (/\bgh\b[\s\S]{0,80}\bpr\b[\s\S]{0,80}\bcreate\b/.test(cmd)) {
+    return catchAction('gh pr create', SKILL_SHIP);
+  }
+
+  // A PR merges into its base (the trunk); promotion is a `wrxn ship` PR gated by CI, not a manual merge.
+  if (/\bgh\b[\s\S]{0,80}\bpr\b[\s\S]{0,80}\bmerge\b/.test(cmd)) {
+    return catchAction('gh pr merge', SKILL_SHIP);
+  }
+
+  // Only a TRUNK push is a skip — promotion is a `wrxn ship` PR, not a direct push to main/master.
+  if (/\bgit\b[\s\S]{0,80}\bpush\b/.test(cmd) && pushesToTrunk(cmd, resolveBranch)) {
+    return catchAction('git push', SKILL_SHIP);
+  }
+
+  return { action: 'allow' };
+}
+
+// Modern PreToolUse output (AC#0-confirmed): a warn lets the tool run while nudging both the
+// assistant (additionalContext) and the operator (systemMessage); a block denies with a reason.
+function warnOutput(message) {
+  return {
+    hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', additionalContext: message },
+    systemMessage: message,
+  };
+}
+
+function blockOutput(message) {
+  return {
+    hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: message },
+  };
+}
+
 function emit(decision) {
   process.stdout.write(JSON.stringify(decision));
   process.exit(0);
@@ -98,6 +235,20 @@ function main() {
   // reach event.tool_name and throw uncaught past the try. Guard it -> fail open. (gate-07 INFO)
   if (!event || typeof event !== 'object') return emit({});
 
+  // Bash arm (slice #90): catch a MAIN-THREAD pipeline skip. The discriminator is the snake_case
+  // `agent_id` stdin field (present only inside a subagent); the posture comes from process.env.
+  if (event.tool_name === 'Bash') {
+    const ti = event.tool_input || {};
+    const d = decideBash({
+      command: ti.command,
+      agentId: event.agent_id, // presence = subagent = the pipeline -> allow
+      level: process.env.WRXN_PIPELINE_GUARD,
+    });
+    if (d.action === 'warn') return emit(warnOutput(d.message));
+    if (d.action === 'block') return emit(blockOutput(d.message));
+    return emit({}); // allow
+  }
+
   // Only gate the Task (subagent-spawn) tool; anything else -> allow.
   if (event.tool_name && event.tool_name !== 'Task') return emit({});
 
@@ -113,4 +264,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { decide };
+module.exports = { decide, decideBash };

package/payload/.claude/hooks/wiki-lint.cjs

@@ -95,7 +95,11 @@ function wikilinkTargets(body) {
   const out = new Set();
   const re = /\[\[([^\]\[]+)\]\]/g;
   let m;
-  const scannable = stripFencedCode(body); // code-block [[slug]] is illustrative, not navigable (#28)
+  // Strip fenced regions, THEN inline code spans (`…`): a [[slug]] in either is illustrative example syntax,
+  // not a navigable link, so it must not be checked for a dead target (#28). The inline pass uses disjoint
+  // adjacent classes (`+ / [^`\n] / `+) so it stays linear — no backtracking, per this file's ReDoS discipline;
+  // `\n` in the class keeps a span single-line so a stray backtick can't swallow real prose links below it.
+  const scannable = stripFencedCode(body).replace(/`+[^`\n]*`+/g, '');
   while ((m = re.exec(scannable))) {
     const slug = m[1].split('|')[0].split('#')[0].trim();
     if (slug) out.add(slug);

package/payload/.claude/settings.json

@@ -35,7 +35,8 @@
       {
         "matcher": "Bash",
         "hooks": [
-          { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-managed-precommit.cjs\"" }
+          { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-managed-precommit.cjs\"" },
+          { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-pipeline-adherence.cjs\"" }
         ]
       },
       {

package/payload/.claude/skills/chat-search/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: chat-search
+description: On-demand retrieval over the Conversational log — grep an exact past moment (timestamp · session · role · snippet) from this project's event log. Operator- and agent-invocable; never an automatic hook.
+user-invocable: true
+---
+
+# chat-search — on-demand retrieval over the Conversational log
+
+`chat-search` retrieves an **exact past conversational moment** on demand — "what did I say about X", "you decided Y earlier". It greps the **Conversational log** (raw, machine-local scrollback), not the Brain: no embeddings, no recon/serve dependency, no index step (ADR 0008). It is **deliberate-only** — the operator types it or the agent reaches for it mid-reasoning (like `recon_find`). It is **never** wired as a `UserPromptSubmit` (or any automatic) hook — Recall's prose-only auto-surface stays the only per-prompt surface (ADR 0002 boundary).
+
+> Scrollback, not memory. The Conversational log is ephemeral and pruned (~90d). Durable, portable memory remains the committed wiki — use the `memory` skill for that.
+
+## Scope (slice 1 — event-log arm)
+
+This slice reads **one arm** of the Conversational log: the **event log** at `.wrxn/events/*.jsonl` — the per-session, secret-redacted **user prompts** emit-event.cjs appends. The harness-transcript arm (the only source of **assistant** turns and full message content) and the `--session` / `--since` / `--regex` flags are follow-on slices; this slice establishes the engine seam.
+
+## Invocation
+
+### Operator
+
+```
+/chat-search baton echo
+```
+
+### Engine (what the skill runs)
+
+```bash
+node .wrxn/chat-search.cjs <search-term...> [--root <dir>]
+```
+
+The engine resolves the install root by walking up to the `wrxn.install.json` receipt, so it runs from anywhere inside an install. Pass `--root <dir>` to override (mainly for tests). It prints the rendered result and exits 0 — a nothing-found result is a normal outcome, never an error exit.
+
+### Agent (self-invocation)
+
+When the operator references an earlier moment ("like we discussed", "the decision from this morning") and you need the **exact** wording rather than a guess, run the engine and ground on what was actually said. Reach for it the same way you reach for `recon_find` — deliberately, when a past moment is needed.
+
+## Output
+
+Hits are **most-recent-first**, one per line:
+
+```
+<timestamp> · <session (or "this session")> · <role> · <snippet (±1 line context)>
+```
+
+- `role` is `user` for a prompt record.
+- The session column collapses to `this session` for hits from the active session.
+- No match → an explicit `chat-search: nothing found for "<term>" ...` line (never silence, never a crash).
+
+## Boundaries
+
+- **Pure in-process grep.** No Brain, no embeddings, no recon/serve/daemon, no network (ADR 0008).
+- **Read-only.** It never writes a wiki page, never mutates the event log.
+- **Never an automatic hook.** Invoked only by the operator or the agent, deliberately (ADR 0002).
+- Default scope is **this project's sessions** — every `.jsonl` under `.wrxn/events/`. Cross-project search is out of scope.
+
+## Source
+
+WRXN Kernel issue #83 (slice 1 of PRD #82). Engine: `.wrxn/chat-search.cjs`. Grounded by `docs/adr/0008-chat-search-ondemand-grep-outside-brain.md` and the `CONTEXT.md` terms **Conversational log** / **chat-search**.

package/payload/.claude/skills/compass/SKILL.md

@@ -84,7 +84,7 @@ build-time guard.
 
 ```buckets
 dev-pipeline: grill-me, grill-with-docs, tech-search, prototype, to-prd, to-issues, triage, tdd, qa-walk, diagnose, resolving-merge-conflicts, improve-codebase-architecture
-knowledge: dream, harvest, sync, ingest, memory
+knowledge: dream, harvest, sync, ingest, memory, chat-search
 setup-health: onboard, audit, level-up, setup-matt-pocock-skills, synapse
 meta: write-a-skill, write-an-agent, skill-creator, compass
 cross-session: handoff
@@ -93,7 +93,7 @@ cross-session: handoff
 - **dev-pipeline** — the four-phase build flow and its engineering activities (grill → research →
   prototype → PRD → issues → verticality → tdd → review → security → qa-walk → diagnose / refactor).
 - **knowledge** — the Brain / wiki memory lifecycle: consolidate (dream), curate (harvest), drift (sync),
-  distill sources (ingest), the wiki adapter (memory).
+  distill sources (ingest), the wiki adapter (memory), on-demand conversational-log retrieval (chat-search).
 - **setup-health** — install setup, configuration, and health: onboard, audit, level-up, the
   issue-tracker/domain block (setup-matt-pocock-skills), the SYNAPSE engine (synapse).
 - **meta** — authoring the OS's own extensions: skills (write-a-skill), agents (write-an-agent), the

package/payload/.wrxn/chat-search.cjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+'use strict';
+
+// WRXN chat-search engine — on-demand retrieval over the Conversational log (kernel #83, slice 1).
+// Self-contained: this ships INTO an install and MUST NOT import the kernel lib (node stdlib only).
+//
+// This slice scans the EVENT-LOG arm only — <root>/.wrxn/events/*.jsonl, the per-session, pre-redacted
+// user-prompt records emit-event.cjs appends. (The harness-transcript arm + flags are #84/#85.) Pure
+// in-process fs scan: no Brain, no embeddings, no recon/serve dependency (ADR 0008). Never wired as a
+// per-prompt hook — it is invoked deliberately, by the operator or the agent (ADR 0002 boundary).
+
+const fs = require('fs');
+const path = require('path');
+
+// Only prompt records carry text in the event arm, so only they can match. role is derived from kind:
+// a user prompt is kind 'prompt' → role 'user'.
+function roleFromKind(kind) {
+  return kind === 'prompt' ? 'user' : String(kind || '');
+}
+
+// A snippet is the matching line plus ±1 line of context within the message text (`needle` is already
+// lowercased). A single-line prompt collapses to just that line. A match that only spans a line boundary
+// has no single matching line → fall back to the trimmed whole text (defensive; rare).
+function snippetFor(text, needle) {
+  const lines = String(text).split('\n');
+  const i = lines.findIndex((l) => l.toLowerCase().includes(needle));
+  if (i === -1) return String(text).trim();
+  const from = Math.max(0, i - 1);
+  const to = Math.min(lines.length - 1, i + 1);
+  return lines.slice(from, to + 1).join('\n').trim();
+}
+
+// ── render: one hit → "timestamp · session (or 'this session') · role · snippet" ──
+// The session column collapses to "this session" when the hit is from the caller's active session
+// (opts.session), so a result set reads as scrollback relative to where the operator stands now.
+function renderHit(hit, opts) {
+  const active = opts && opts.session;
+  const sessionLabel = active && hit.session === active ? 'this session' : hit.session;
+  return `${hit.ts} · ${sessionLabel} · ${hit.role} · ${hit.snippet}`;
+}
+
+// ── locations (injectable — tests pass a temp root) ───────────────────────────
+// The events dir for an install root, mirroring emit-event.cjs's eventsDir(root).
+function eventsDirOf(root) {
+  return path.join(root, '.wrxn', 'events');
+}
+
+// Normalize the roots arg to a list of install roots. A string is one root; an array is many. The seam
+// stays pure/injectable — it never resolves cwd itself; the CLI passes the resolved root in.
+function normalizeRoots(roots) {
+  if (!roots) return [];
+  return Array.isArray(roots) ? roots : [roots];
+}
+
+// Every <sid>.jsonl session log in an events dir. Absent dir → [] (no crash), mirroring wiki.cjs.
+function listEventFiles(dir) {
+  try {
+    return fs
+      .readdirSync(dir)
+      .filter((n) => n.endsWith('.jsonl'))
+      .map((n) => path.join(dir, n));
+  } catch {
+    return [];
+  }
+}
+
+// ── the engine seam ───────────────────────────────────────────────────────────
+// searchConversationalLog(query, opts, roots): scan the event-log arm across the given roots' sessions
+// and return the prompts whose text contains `query` (case-insensitive substring). Each hit is a
+// structured record { ts, session, role, snippet }.
+function searchConversationalLog(query, opts, roots) {
+  const q = String(query == null ? '' : query);
+  const needle = q.toLowerCase();
+  const hits = [];
+
+  for (const root of normalizeRoots(roots)) {
+    for (const file of listEventFiles(eventsDirOf(root))) {
+      let lines;
+      try {
+        lines = fs.readFileSync(file, 'utf8').split('\n');
+      } catch {
+        continue; // an unreadable entry (EISDIR dir, EACCES, ENOENT/TOCTOU, broken symlink) → skip it, keep scanning
+      }
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        let rec;
+        try {
+          rec = JSON.parse(line);
+        } catch {
+          continue; // skip a malformed line, never crash the scan
+        }
+        if (!rec || rec.kind !== 'prompt' || typeof rec.text !== 'string') continue; // ONLY prompt records match — a non-prompt (e.g. tool) record is skipped even if it carries a stray text field (#87)
+        if (!rec.text.toLowerCase().includes(needle)) continue;
+        hits.push({ ts: rec.ts, session: rec.sid, role: roleFromKind(rec.kind), snippet: snippetFor(rec.text, needle) });
+      }
+    }
+  }
+
+  // Recency-first: newest timestamp on top. ISO-8601 stamps parse cleanly; an unparseable ts sorts last.
+  hits.sort((a, b) => (Date.parse(b.ts) || 0) - (Date.parse(a.ts) || 0));
+
+  const found = hits.length > 0;
+  const rendered = found
+    ? hits.map((h) => renderHit(h, opts)).join('\n')
+    : `chat-search: nothing found for "${q}" in the conversational log (event log).`;
+
+  return { query: q, total: hits.length, found, hits, rendered };
+}
+
+// ── CLI: node .wrxn/chat-search.cjs <term...> [--root <dir>] ──────────────────
+// The operator-invocable surface (/chat-search <term>). Resolves the install root by walking up to the
+// wrxn.install.json receipt (mirrors wiki.cjs), or honors a --root override (tests). Prints the rendered
+// result and exits 0 — a nothing-found result is a normal outcome, never an error exit.
+
+// Mirrors wiki.cjs / emit-event.cjs findInstallRoot (no kernel-lib import in a shipped file).
+function findInstallRoot(start) {
+  let dir = start || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  for (let i = 0; i < 12; i++) {
+    if (fs.existsSync(path.join(dir, 'wrxn.install.json'))) return dir;
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+function flag(name) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i > -1 ? process.argv[i + 1] : undefined;
+}
+
+// Positional search terms: argv from index 2 up to the first --flag.
+function positionals() {
+  const out = [];
+  for (let i = 2; i < process.argv.length; i++) {
+    if (process.argv[i].startsWith('--')) break;
+    out.push(process.argv[i]);
+  }
+  return out;
+}
+
+function main() {
+  const terms = positionals();
+  if (terms.length === 0) {
+    process.stdout.write('Usage: node .wrxn/chat-search.cjs <search-term...> [--root <dir>]\n');
+    process.exit(2);
+  }
+  const root = flag('root') || findInstallRoot();
+  if (!root) {
+    process.stderr.write('chat-search: cannot resolve the install root — run inside a wrxn install or pass --root <dir>\n');
+    process.exit(2);
+  }
+  // opts is empty here: the live current-session id (which the renderer collapses to "this session") has
+  // no CLI source yet — it arrives with the transcript arm (#84). Not wired in this slice.
+  const result = searchConversationalLog(terms.join(' '), {}, root);
+  process.stdout.write(result.rendered + '\n');
+  process.exit(0);
+}
+
+// Belt-and-suspenders fail-loud (mirrors emit-event.cjs's entrypoint wrap): the per-file read and root
+// resolution are already guarded, so main() should not throw — but if any residual fault escapes, exit
+// with a clean ONE-LINE diagnostic (a path-free error code only — never a Node stack or absolute path).
+if (require.main === module) {
+  try {
+    main();
+  } catch (err) {
+    const code = err && err.code ? ` (${err.code})` : '';
+    process.stderr.write(`chat-search: search failed unexpectedly${code}\n`);
+    process.exit(1);
+  }
+}
+
+module.exports = { searchConversationalLog, renderHit };