@gcunharodrigues/wrxn 0.19.0 → 0.20.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gcunharodrigues/wrxn",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "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/memory-synth-spawn.cjs

@@ -49,6 +49,91 @@ function findInstallRoot(startDir) {
   return null;
 }
 
+// ── skip-log (#104) ──────────────────────────────────────────────────────────────
+// The #45 `wx` claim blocks a re-spawn SILENTLY, so a benign dedup skip is invisible in the synth log.
+// When a fire skips because the marker is already present, append ONE row to .wrxn/continuity/.synth.log so
+// the dedup is diagnosable. The row matches memory-synth.cjs's writeSynthLog shape EXACTLY — tab-separated
+// six fields: ISO timestamp, session id, task `handoff`, engine `-`, `attempts=0`, outcome `skip`. The
+// session id is sanitized via the same idiom as memory-synth's sanitizeLogField (strip C0/C1 control chars —
+// which INCLUDES tab \x09 and newline \x0a — then length-cap) so a hostile id can't forge extra rows. `skip`
+// is a NON-failure token (the #51 staleness guard treats only no-engine/error as rot), so a dedup never
+// false-warns. Self-contained — node stdlib only, NO kernel import; sanitizeLogField is duplicated by design
+// (every install-only hook is standalone, exactly as safeId is replicated across the hooks).
+const SYNTH_LOG = '.synth.log';
+const LOG_FIELD_MAX = 64;
+
+function sanitizeLogField(v) {
+  // eslint-disable-next-line no-control-regex
+  return String(v == null ? '' : v).replace(/[\x00-\x1f\x7f-\x9f]/g, '').slice(0, LOG_FIELD_MAX);
+}
+
+// ── content-versioned claim (#105) ───────────────────────────────────────────────
+// Slice 1 (#104) released the `.spawned-<sid>` marker on SessionStart so a resumed session's later end could
+// re-synth. When that release is MISSED (e.g. a multi-terminal continuation whose new process never released
+// the claim), the existence-only marker freezes the baton with no recovery. Slice 2 makes the dedup
+// CONTENT-AWARE: stamp the marker with the session transcript's byte size (+ a timestamp) at claim time, then
+// on a marker-present end re-arm the synth when the transcript has GROWN materially since the stamp — a
+// self-heal that needs no SessionStart release. Any fault (absent/unreadable transcript path, stat fault,
+// unparseable marker) falls back to slice 1's existence-only claim and is fully fail-open (never throws,
+// never double-fires on a fault). Self-contained — node stdlib only, NO kernel import.
+//
+// GROWTH_THRESHOLD — the byte growth that counts as "did real work since the stamp". A same-end double-fire
+// appends NOTHING to the transcript (~0 bytes); a resumed session that did real work appends KB–MB of JSONL
+// (each transcript turn — uuid/parentUuid/sessionId/timestamp/message — is hundreds of bytes to several KB).
+// 1 KiB sits comfortably above zero / trailing-byte jitter and well below a single real exchange, so it
+// cleanly separates "no new work" (skip) from "genuine continuation" (re-arm). Conservative by design: the
+// re-arm fires only on a POSITIVE growth signal, so any uncertainty defaults to skip (never double-fire).
+const GROWTH_THRESHOLD = 1024;
+
+// The transcript byte size from the SessionEnd payload's transcript_path, or null on ANY fault (absent path,
+// ENOENT, EACCES, …). null = "size unknown" → the caller falls back to the existence-only claim (fail-open).
+function transcriptSize(transcriptPath) {
+  try {
+    if (!transcriptPath) return null;
+    return fs.statSync(transcriptPath).size;
+  } catch {
+    return null;
+  }
+}
+
+// The marker payload stamped at claim/re-arm time: the transcript size + an ISO timestamp. A null size
+// (unreadable transcript) is stamped as-is, so a later read yields no baseline → existence-only fallback.
+function stampContent(size) {
+  return JSON.stringify({ size: typeof size === 'number' ? size : null, at: new Date().toISOString() });
+}
+
+// The size stamped into an existing marker, or null when there is no usable baseline — a #104 zero-byte
+// marker, unparseable JSON, or a null/non-number size. null → the caller falls back to existence-only (skip),
+// so a corrupt/legacy marker can never trigger a re-arm (any uncertainty defaults to skip, never double-fire).
+function readStampedSize(markerPath) {
+  try {
+    const raw = fs.readFileSync(markerPath, 'utf8');
+    if (!raw.trim()) return null;
+    const parsed = JSON.parse(raw);
+    return typeof parsed.size === 'number' ? parsed.size : null;
+  } catch {
+    return null;
+  }
+}
+
+// Append exactly one tab-separated `skip` row for a marker-present dedup. Best-effort + FAIL-OPEN: a logging
+// fault is swallowed so it can NEVER affect the dedup (the diagnosability log must not become a failure mode).
+function appendSkipLog(dir, sessionId) {
+  try {
+    const line = [
+      new Date().toISOString(),
+      sanitizeLogField(sessionId) || '-', // untrusted stash value — strip control chars, cap length.
+      'handoff',
+      '-',
+      'attempts=0',
+      'skip',
+    ].join('\t');
+    fs.appendFileSync(path.join(dir, SYNTH_LOG), line + '\n');
+  } catch {
+    /* the skip log is best-effort — a write fault must never affect the dedup */
+  }
+}
+
 /**
  * The testable core. Given the SessionEnd payload, the install root, the env (for the recursion guard),
  * and an injectable `spawn`, it stashes the payload + writes the pending markers and launches the synth
@@ -68,14 +153,52 @@ function run({ payload, root, env = process.env, spawn: spawnFn = spawn }) {
     // Once-per-session claim (#45): the harness fires SessionEnd more than once per session, so an
     // unguarded hook launches N synths that race on one shared `.pending`. CLAIM the session ATOMICALLY
     // with an exclusive create (`wx` throws EEXIST if the marker exists) BEFORE staging markers / spawning:
-    // the FIRST fire creates the marker and proceeds; every later fire for the same session throws → the
-    // outer catch returns {} (spawns nothing, writes no markers). Race-safe across the separate hook
-    // processes (no TOCTOU). The marker is a PERSISTENT per-session file — it must OUTLIVE the synth, so it
-    // is NOT `.pending`/`.pending-handoff` (which the synth clears on exit). A missing/empty session_id
-    // cannot be deduped → preserve today's spawn-every-time behavior for that path.
+    // the FIRST fire creates+stamps the marker and proceeds; a later fire for the same session throws EEXIST,
+    // handled below by the content-aware dedup (#105: re-arm if the transcript grew, else skip). Race-safe
+    // across the separate hook processes (no TOCTOU). The marker is a PERSISTENT per-session file — it must
+    // OUTLIVE the synth, so it is NOT `.pending`/`.pending-handoff` (which the synth clears on exit). A
+    // missing/empty session_id cannot be deduped → preserve today's spawn-every-time behavior for that path.
     const sid = payload && payload.session_id;
     if (sid) {
-      fs.closeSync(fs.openSync(path.join(dir, `.spawned-${safeId(sid)}`), 'wx'));
+      const markerPath = path.join(dir, `.spawned-${safeId(sid)}`);
+      const currentSize = transcriptSize(payload && payload.transcript_path); // null on any fault → fallback
+      try {
+        // Atomic exclusive claim (wx is TOCTOU-free across the separate hook processes, #45) — and STAMP it
+        // with the transcript byte size + a timestamp (#105), so a later marker-present end can tell a genuine
+        // continuation (transcript grew) from a same-end duplicate. Write to the just-claimed fd so the create
+        // and the stamp are one operation on the file we exclusively own.
+        const fd = fs.openSync(markerPath, 'wx');
+        try {
+          fs.writeSync(fd, stampContent(currentSize));
+        } finally {
+          fs.closeSync(fd);
+        }
+      } catch (err) {
+        if (err && err.code === 'EEXIST') {
+          // The session is already claimed — a same-instance double-fire (#45) OR a resume's later end before
+          // SessionStart released the marker. Content-aware dedup (#105): re-arm ONLY on a positive growth
+          // signal — if the transcript grew past the threshold since the stamp, this is a genuine continuation
+          // (a missed release), so RE-STAMP to the new size and fall through to spawn (the baton un-freezes).
+          // Otherwise — no material growth, OR an indeterminate baseline/size from a fault — it is a same-end
+          // duplicate: log ONE benign `skip` row (#104) and no-op. Any uncertainty defaults to skip, so a
+          // stat/read fault can never double-fire the synth.
+          const stampedSize = readStampedSize(markerPath);
+          if (stampedSize != null && currentSize != null && currentSize - stampedSize > GROWTH_THRESHOLD) {
+            try {
+              fs.writeFileSync(markerPath, stampContent(currentSize)); // re-stamp the new baseline
+            } catch {
+              /* re-stamp is best-effort: a write fault must not block the re-arm — still spawn (PRD: the rare
+                 double-spawn is bounded by the in-flight .pending markers + the synth's once-per-session guard) */
+            }
+            // fall through (do NOT return) → stash the pending markers + spawn the synth.
+          } else {
+            appendSkipLog(dir, sid);
+            return {};
+          }
+        } else {
+          throw err; // any OTHER claim fault → fail-open via the outer catch (not a dedup → no skip row)
+        }
+      }
     }
 
     // Stash the payload as .pending (the synth reads it for transcript_path) and raise the handoff gate.

package/payload/.claude/hooks/session-start.cjs

@@ -93,6 +93,38 @@ function stampStartHead(root, sessionId, opts = {}) {
   }
 }
 
+// ── re-arm the SessionEnd synth on resume (#104) ─────────────────────────────────
+// The SessionEnd spawn hook (memory-synth-spawn.cjs) dedups via a PERSISTENT per-session marker
+// .wrxn/continuity/.spawned-<sid>. But SessionEnd fires once per PROCESS instance, not per session id — a
+// resume reopens the SAME id in a NEW process, so the resumed session's later (content-rich) end hits the
+// existing marker, is swallowed fail-open, and never re-synths: the baton FREEZES at the first end. The
+// fix: SessionStart releases (deletes) the marker on EVERY start, so the next SessionEnd for this id is free
+// to synth again. A fresh id (startup / clear) has no marker → no-op. The spawn hook's WITHIN-instance `wx`
+// claim (the same-process #45 guard) is untouched — only this cross-process persistent marker is released
+// between sessions. The marker name is keyed by safeId, byte-identical to the spawn hook's writer, so the
+// release deletes EXACTLY what that hook wrote.
+
+const CONTINUITY_DIR_REL = ['.wrxn', 'continuity'];
+
+/**
+ * Release (delete) the session's once-per-session synth claim marker at
+ * <root>/.wrxn/continuity/.spawned-<safeId(sessionId)>, re-arming the SessionEnd synth for a resumed
+ * session id (#104). Returns true when a marker was removed; false on any fail-open path (no root/session,
+ * absent marker, unwritable / any fault). NEVER throws — orientation must never block on the release.
+ * @param {string} root  install root
+ * @param {string} sessionId  the session id (marker key)
+ * @returns {boolean}
+ */
+function releaseSpawnClaim(root, sessionId) {
+  try {
+    if (!root || !sessionId) return false;
+    fs.unlinkSync(path.join(root, ...CONTINUITY_DIR_REL, `.spawned-${safeId(sessionId)}`));
+    return true;
+  } catch {
+    return false; // absent marker (no-op) / unwritable / any delete fault → fail-open, never blocks orientation
+  }
+}
+
 // Walk up from CLAUDE_PROJECT_DIR (or cwd) to the install root carrying wrxn.install.json.
 function findInstallRoot(startDir) {
   let dir = startDir || process.env.CLAUDE_PROJECT_DIR || process.cwd();
@@ -348,6 +380,15 @@ function main() {
     /* never block orientation on the baseline stamp */
   }
 
+  // #104: release the SessionEnd synth's once-per-session claim so a RESUMED session (same id, new process)
+  // re-synths its later, content-rich end instead of freezing the baton at the first end. A fresh id
+  // (startup / clear) has no marker → no-op. Fail-open: any fault is swallowed and orientation proceeds.
+  try {
+    if (event && event.session_id) releaseSpawnClaim(root, event.session_id);
+  } catch {
+    /* never block orientation on the claim release */
+  }
+
   // Hold for an in-flight SessionEnd synth (auto-memory-03) so a back-to-back /clear resumes on the
   // FRESH baton, bounded by the crash safety-cap. Fail-open: any fault here must not block orientation.
   try {
@@ -399,4 +440,4 @@ if (require.main === module) {
   }
 }
 
-module.exports = { holdDecision, holdForHandoff, HOLD_CAP_MS, stampStartHead, resolveGitHead, BASELINE_DIR_REL, batonStaleness, parseSynthLog, readSynthLogTail, SYNTH_LOG_TAIL_BYTES };
+module.exports = { holdDecision, holdForHandoff, HOLD_CAP_MS, stampStartHead, releaseSpawnClaim, resolveGitHead, BASELINE_DIR_REL, batonStaleness, parseSynthLog, readSynthLogTail, SYNTH_LOG_TAIL_BYTES };

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: On-demand retrieval over the Conversational log — grep an exact past moment (timestamp · session · role · snippet) across both arms: the event log AND the harness transcript (user and assistant turns). Operator- and agent-invocable; never an automatic hook.
 user-invocable: true
 ---
 
@@ -10,9 +10,22 @@ user-invocable: true
 
 > 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)
+## Scope — both arms of the Conversational log
 
-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.
+`chat-search` reads **both arms** and merges them into one recency-first result:
+
+- **Event log** — `.wrxn/events/*.jsonl`, the per-session, secret-redacted **user prompts** emit-event.cjs appends.
+- **Harness transcript** — `~/.claude/projects/<slug>/*.jsonl`, the only source of **assistant** turns and full user/assistant **message content**. The `<slug>` is the project's absolute path with every non-alphanumeric character replaced by `-` (how the harness names the dir). The transcript arm is **hygiene-cleaned** before matching (see below).
+
+A prompt that appears in **both** arms is de-duplicated — by `(session, timestamp, text)` — so it surfaces once. If the transcript dir is **missing or unreadable**, the search **degrades loudly to events-only** and says so in the output (it never crashes).
+
+Three optional flags refine a search — `--session` (scope to one session), `--since` (a time floor), and `--regex` (pattern match instead of substring). They compose with each other and with both arms. See **Scoping & match flags** below.
+
+### Transcript hygiene (so a hit is real conversation, not framework noise)
+
+- **Injected context is stripped** before matching: `<wrxn-orientation>`, `<synapse-rules>`, `<recall-surface>`, `<reference-candidate>`, and `<system-reminder>` blocks the hooks inject each turn are removed, so a term that lives **only inside** an injected block is **not** a hit.
+- **Secrets are redacted** (the same canonical secret-shape set the memory adapters use): a credential echoed into chat never appears in a snippet.
+- Only `text` content is searched — `thinking` / `tool_use` / `tool_result` blocks and unknown line `type`s (`summary`, `system`, …) are dropped.
 
 ## Invocation
 
@@ -25,15 +38,30 @@ This slice reads **one arm** of the Conversational log: the **event log** at `.w
 ### Engine (what the skill runs)
 
 ```bash
-node .wrxn/chat-search.cjs <search-term...> [--root <dir>]
+node .wrxn/chat-search.cjs <search-term...> [--root <dir>] [--session <id>] [--since <when>] [--regex]
 ```
 
-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.
+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). Flags follow the search term(s). It prints the rendered result and exits 0 — a nothing-found result is a normal outcome, never an error exit. **Invalid flag input** (a malformed/catastrophic `--regex`, an unparseable `--since`, an unsafe `--session`) fails **loud**: one clear line on stderr and a non-zero exit — never a stack trace or a hang.
 
 ### 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.
 
+## Scoping & match flags
+
+All three are optional, compose with each other, and apply across **both arms** (so scoping/filtering also covers assistant turns), preserving recency order and cross-arm dedup.
+
+- **`--session <id>`** — scope results to a single session (exact match on the session id). The id is the harness/event session id (letters, digits, `-`, `_`); a malformed id is rejected. Scoped rows render as `this session`.
+- **`--since <when>`** — keep only hits at or after a timestamp floor. `<when>` is either `today` (from 00:00 **UTC** of the current day — record stamps are UTC) or an ISO-8601 date/datetime (e.g. `2026-06-26` or `2026-06-26T12:00:00Z`). An undatable hit is excluded.
+- **`--regex`** — match the search term as a **regular expression** instead of a case-insensitive substring. Regex mode is **case-sensitive** (the universal regex default; the substring default stays case-insensitive).
+
+```bash
+node .wrxn/chat-search.cjs "gate.*decision" --regex --since today
+node .wrxn/chat-search.cjs baton echo --session 9dc65f19-65fb-43cb-81fa-0340353f1cc5
+```
+
+> **`--regex` safety (ReDoS).** The pattern is user-supplied and runs over whole transcripts, so it is bounded at compile (before any input is matched): it is **length-capped** (≤ 200 chars) and runs through a **nesting-aware static screen** that rejects a quantified group whose body repeats or alternates through **any** nesting depth — both flat shapes (`(a+)+`, `(a|a)+`, `(?:a*)*`) and nested ones a flat check misses (`((a)+)+`, `((\w)+)+$`, `((a+))+`, `(a(b+)c)+`) — plus **backreferences** (`\1`…`\9`). A rejected, malformed, or unparseable value fails loud. The screen is deliberately conservative (it also refuses the rare-but-safe `(foo|bar)+` — drop the outer quantifier), but does not over-reject ordinary grouping: `(foo|bar)`, `(ab)+`, `([a+])+`, `(?:ab)+`, `a{1,5}`, `\d{4}-\d{2}-\d{2}` are all fine. **Residual:** a static screen models structure, not match semantics, so under the no-timeout / `fs`-`os`-`path`-only constraint it refuses the known catastrophic shapes rather than proving a pattern safe; an exotic construct outside those shapes is not modelled.
+
 ## Output
 
 Hits are **most-recent-first**, one per line:
@@ -42,17 +70,18 @@ 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.
+- `role` is `user` (event log or a user transcript turn) or `assistant` (a transcript turn).
 - 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).
+- If the transcript arm is unavailable, a trailing `chat-search: transcript arm unavailable — showing event-log results only.` line is appended (loud degrade).
 
 ## 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.
+- **Pure in-process grep.** No Brain, no embeddings, no recon/serve/daemon, no network (ADR 0008). Node stdlib only (`fs` + `os` + `path`).
+- **Read-only.** It never writes a wiki page, never mutates the event log or the transcript.
 - **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.
+- Default scope is **this project's sessions** — every `.jsonl` under `.wrxn/events/` plus this project's harness transcript under `~/.claude/projects/<slug>/`. The slug is **path-bounded** (it can never escape `~/.claude/projects`). 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**.
+WRXN Kernel issues #83 (slice 1 — event-log arm) + #84 (slice 2 — harness-transcript arm + hygiene) + #85 (slice 3 — scoping + match flags), under 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/.wrxn/chat-search.cjs

@@ -1,15 +1,21 @@
 #!/usr/bin/env node
 'use strict';
 
-// WRXN chat-search engine — on-demand retrieval over the Conversational log (kernel #83, slice 1).
+// WRXN chat-search engine — on-demand retrieval over the Conversational log (kernel #83 slice 1, #84 slice 2).
 // 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).
+// It scans BOTH arms of the Conversational log:
+//   · the EVENT-LOG arm — <root>/.wrxn/events/*.jsonl, the per-session, pre-redacted user-prompt records
+//     emit-event.cjs appends (slice 1);
+//   · the HARNESS-TRANSCRIPT arm — ~/.claude/projects/<slug>/*.jsonl, the only source of ASSISTANT turns
+//     and full user/assistant message content (slice 2 / #84). Its output is injected-context-stripped +
+//     secret-redacted, and a prompt present in both arms is de-duplicated.
+// Pure in-process fs scan: no Brain, no embeddings, no recon/serve dependency, no network (ADR 0008). It
+// degrades LOUDLY to events-only if the transcript dir is absent/unreadable. 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 os = require('os'); // home-dir resolution only (the transcript arm lives under ~/.claude/projects) — NOT network/daemon/embedding.
 const path = require('path');
 
 // Only prompt records carry text in the event arm, so only they can match. role is derived from kind:
@@ -18,12 +24,13 @@ 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) {
+// A snippet is the matching line plus ±1 line of context within the message text. `matchesLine` is the
+// active matcher (case-insensitive substring by default, or the compiled --regex), so the snippet finds the
+// SAME line the scan matched on. 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, matchesLine) {
   const lines = String(text).split('\n');
-  const i = lines.findIndex((l) => l.toLowerCase().includes(needle));
+  const i = lines.findIndex((l) => matchesLine(l));
   if (i === -1) return String(text).trim();
   const from = Math.max(0, i - 1);
   const to = Math.min(lines.length - 1, i + 1);
@@ -64,16 +71,287 @@ function listEventFiles(dir) {
   }
 }
 
+// ── injected-context strip (REUSE-by-replication of memory-synth's #62 sentinel-strip) ──────────
+// REUSE > ADAPT > CREATE: this is COPIED (mirror, not import) from memory-synth.cjs's stripInjectedContext
+// (the slice-1 self-containment convention — the engine replicates findInstallRoot rather than importing,
+// and importing memory-synth would transitively pull in https + child_process, breaching the ADR-0008
+// no-network/no-daemon boundary this engine's dependency test pins). Hook-injected framework-context
+// sentinels — SessionStart's <wrxn-orientation> (which embeds the prior baton), UserPromptSubmit's
+// <synapse-rules>/<recall-surface>/<reference-candidate>, and <system-reminder> harness notes — land
+// verbatim in the transcript. They are framework noise, not conversation, so a hit inside one is NOT a real
+// hit: strip them BEFORE matching. (#62, #84)
+const INJECTED_SENTINELS = ['wrxn-orientation', 'synapse-rules', 'recall-surface', 'reference-candidate', 'system-reminder'];
+// ReDoS bound (#62): the closed-block strip is ~quadratic on a pathological part (many opens, no closes). A
+// real injected block is a few KB; this cap sits far above that yet below the multi-second regex range, so
+// the strip stays effectively linear even when the engine scans whole transcripts.
+const INJECTED_STRIP_MAX = 65536;
+
+// Strip hook-injected framework-context blocks from one text part BEFORE matching. Two phases: (1) every
+// well-delimited <tag>…</tag> block anywhere; (2) a part-LEADING unclosed <tag>… (transcript truncated
+// mid-block) to end-of-part — anchored so a sentinel merely MENTIONED mid-prose keeps its tail. PURE and
+// FAIL-OPEN: any fault returns the input unchanged. Byte-faithful copy of memory-synth.cjs (#62).
+function stripInjectedContext(text) {
+  try {
+    let out = String(text || '');
+    if (out.length > INJECTED_STRIP_MAX) return out; // far larger than any real injected block → ordinary content, nothing part-leading to strip.
+    for (const tag of INJECTED_SENTINELS) {
+      out = out.replace(new RegExp(`<${tag}>[\\s\\S]*?</${tag}>`, 'g'), '');
+    }
+    for (const tag of INJECTED_SENTINELS) {
+      out = out.replace(new RegExp(`^\\s*<${tag}>[\\s\\S]*$`), '');
+    }
+    return out;
+  } catch {
+    return String(text || ''); // a filter fault never breaks the scan
+  }
+}
+
+// ── secret redaction (REUSE-by-replication of the #39 canonical set) ────────────────────────────
+// The transcript arm derives output from RAW chat, which can echo a credential the operator/agent pasted.
+// Scrub it before any snippet leaves the engine (events are already pre-redacted upstream). The array body
+// below is the ONE canonical secret-shape set, kept BYTE-IDENTICAL to its dream/sync/harvest/memory-synth/
+// sidecar siblings. THIS copy is ENROLLED in adapter-drift-guard.test.cjs's #39 CANON_SITES, so the build
+// fails if it ever drifts from the others — copied, not imported, for the same self-containment reason as
+// stripInjectedContext above. (#39, #84)
+const SECRET_PATTERNS = [
+  /AKIA[0-9A-Z]{16}/, // AWS access key id
+  /gh[pousr]_[A-Za-z0-9]{20,}/, // GitHub token (ghp_/gho_/ghu_/ghs_/ghr_); {20,} covers the 36-char + CI forms
+  /github_pat_[A-Za-z0-9_]{22,}/, // GitHub fine-grained PAT
+  /xox[baprs]-[A-Za-z0-9-]{10,}/, // Slack token
+  /sk-[A-Za-z0-9]{20,}/, // OpenAI-style secret key
+  /sk-proj-[A-Za-z0-9_-]{20,}/, // OpenAI project-scoped key (underscore form sk-… misses)
+  /AIza[0-9A-Za-z._-]{10,}/, // Google / Gemini API key
+  /sk_(?:live|test)_[A-Za-z0-9]{20,}/, // Stripe live/test secret key
+  /npm_[A-Za-z0-9]{20,}/, // npm publish / automation token
+  /\bey[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{3,}\.[A-Za-z0-9_-]{3,}\b/, // JWT (incl. Bearer payloads); the eyJ… header gates it
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/, // PEM block (FULL — must precede the header fallback so redaction eats the body)
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----/, // PEM header (fallback: a lone/truncated header with no END)
+  /Bearer\s+[A-Za-z0-9._~+/=-]{20,}/, // opaque Bearer token (non-JWT)
+  /\b[A-Za-z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD|PWD)\b\s*[:=]\s*\S+/i, // KEY/TOKEN/SECRET/PASSWORD = value
+];
+
+// Redaction form: every shape made global so EVERY occurrence is scrubbed (each clone preserves its own
+// flags and only ADDS g, so detection and redaction never diverge). Mirrors memory-synth.cjs (#39).
+const REDACTIONS = SECRET_PATTERNS.map((re) => new RegExp(re.source, re.flags.includes('g') ? re.flags : re.flags + 'g'));
+
+// Redact common secret shapes from `text`, each match → `[REDACTED]`. PURE; ordinary prose is preserved.
+function redactSecrets(text) {
+  let out = String(text || '');
+  for (const re of REDACTIONS) out = out.replace(re, '[REDACTED]');
+  return out;
+}
+
+// ── harness-transcript arm (#84) ──────────────────────────────────────────────
+// The transcript lives OUTSIDE the install, under ~/.claude/projects/<slug>/*.jsonl, where the harness
+// derives <slug> from the project's absolute path. The base is injectable (opts.transcriptsHome) so the
+// engine is testable without touching the operator's real ~/.claude.
+function defaultTranscriptsHome() {
+  return path.join(os.homedir(), '.claude', 'projects');
+}
+
+// Map an install root to its harness transcript dir <home>/<slug>. The slug mirrors how Claude Code names
+// ~/.claude/projects/<slug>: every NON-alphanumeric char of the absolute root path → '-' (verified against
+// the live dir names). That replacement IS the path-traversal defense — no '/', '\' or '..' can survive it,
+// so a crafted root cannot escape the base. The containment check is belt-and-suspenders and ALSO refuses a
+// degenerate empty slug that would otherwise resolve to the base itself and read EVERY project's transcripts
+// (a cross-project leak). A refusal returns null → the caller degrades loudly to events-only. #84.
+function resolveTranscriptDir(root, home) {
+  if (!root || !home) return null;
+  const base = path.resolve(String(home));
+  const slug = String(root).replace(/[^A-Za-z0-9]/g, '-');
+  const dir = path.resolve(base, slug);
+  if (dir === base || !dir.startsWith(base + path.sep)) return null; // must sit STRICTLY under the base — never the base, never outside it.
+  return dir;
+}
+
+// Every <sid>.jsonl transcript in a project's harness dir. Throws on an absent/unreadable dir — the caller
+// catches it to DEGRADE LOUDLY to events-only (so it can tell "arm unavailable" from "arm present, empty").
+function listTranscriptFiles(dir) {
+  return fs
+    .readdirSync(dir)
+    .filter((n) => n.endsWith('.jsonl'))
+    .map((n) => path.join(dir, n));
+}
+
+// Flatten a transcript record's message.content to plain searchable text. Content is a STRING (a plain
+// user/assistant message) OR a text-block ARRAY (only the `text` blocks carry conversation — `thinking` /
+// `tool_use` / `tool_result` blocks are framework noise, not message content, and are dropped). Any other
+// shape → '' (nothing matchable). #84.
+function transcriptText(rec) {
+  const m = (rec && rec.message) || {};
+  const c = m.content;
+  if (typeof c === 'string') return c;
+  if (Array.isArray(c)) {
+    return c
+      .filter((p) => p && typeof p === 'object' && p.type === 'text' && typeof p.text === 'string')
+      .map((p) => p.text)
+      .join('\n');
+  }
+  return '';
+}
+
+// ── slice-3 flags (#85): validation + parsing ──────────────────────────────────
+// A user-facing input error. The `userFacing` flag lets the CLI print this message cleanly (one line, no
+// Node stack/path) and exit non-zero — the AC's "invalid flag input fails LOUD, never a crash". Bad DATA
+// stays fail-soft (skipped, never thrown); only bad INPUT (a flag value) fails loud.
+function inputError(msg) {
+  const e = new Error(msg);
+  e.userFacing = true;
+  return e;
+}
+
+// Validate a --session id. Scoping is a pure exact-match on each record's session field — the value is NEVER
+// used to build a path — so traversal/widening are structurally impossible; this charset guard makes that
+// explicit (real session ids are the harness UUIDs + event sids: alnum, hyphen, underscore) and fails LOUD
+// on a malformed id rather than silently matching nothing.
+const SESSION_ID = /^[A-Za-z0-9_-]+$/;
+function validateSession(raw) {
+  const s = String(raw);
+  if (!SESSION_ID.test(s)) {
+    throw inputError(`chat-search: --session value "${raw}" is not a valid session id (expected letters, digits, '-' or '_')`);
+  }
+  return s;
+}
+
+// Parse a --since value into a threshold epoch-ms; a hit survives when its timestamp is >= the threshold.
+// Accepts the keyword `today` (start of the current UTC day — record stamps are UTC `…Z`) or an ISO-8601
+// date/datetime (via Date.parse). An unparseable value fails LOUD (the AC's invalid-input handling).
+function parseSince(raw) {
+  const s = String(raw).trim();
+  if (s.toLowerCase() === 'today') {
+    const d = new Date();
+    d.setUTCHours(0, 0, 0, 0);
+    return d.getTime();
+  }
+  const t = Date.parse(s);
+  if (Number.isNaN(t)) {
+    throw inputError(`chat-search: --since value "${raw}" is not a date — use "today" or an ISO-8601 date (e.g. 2026-06-26)`);
+  }
+  return t;
+}
+
+// ── --regex ReDoS bound ──────────────────────────────────────────────────────
+// --regex compiles a USER-supplied pattern and runs it over whole transcripts → classic ReDoS surface. Node
+// has no native regex timeout and ADR-0008 forbids a worker/child_process to bound runtime, so the defense is
+// STATIC and applied at COMPILE (before any input is matched):
+//   (1) PATTERN-LENGTH CAP — a legitimate search pattern is short ("(deploy|ship).*gate", "\\bbaton\\b"); 200
+//       chars is generous for real use yet bounds how much quantifier nesting an adversarial pattern can pack.
+//   (2) NESTING-AWARE CATASTROPHIC-SHAPE SCREEN (isCatastrophicRegex) — reject a *quantified group* whose
+//       body, through ANY nesting depth, repeats or alternates (a quantifier + * { ? or an alternation |).
+//       This is the catastrophic-backtracking (star-height ≥ 2 / overlapping-alternation-under-a-quantifier)
+//       family — both FLAT (a+)+, (a|a)+, (?:a*)* AND the NESTED forms a flat regex screen misses because it
+//       cannot cross an inner paren: ((a)+)+ (the OWASP example), ((a+))+, ((\w)+)+$, (a(b+)c)+, (a{1,5})+.
+//       Plus backreferences (\1..\9), which can backtrack catastrophically — refused outright.
+// It is deliberately CONSERVATIVE: it also rejects the rare-but-safe outer-quantified alternation (foo|bar)+
+// (drop the outer quantifier to search it). It does NOT over-reject ordinary grouping — (foo|bar), (ab)+,
+// ([a+])+, (?:ab)+, a{1,5}, \d{4}-\d{2}-\d{2} all pass.
+// RESIDUAL (stated honestly): a STATIC screen cannot be airtight under the no-timeout/ADR-0008 constraint —
+// it models group/quantifier structure, not match semantics, so it cannot prove a pattern safe, only refuse
+// the known-dangerous shapes. The catastrophic families that actually occur (flat + nested star-height-2,
+// overlapping alternation under a quantifier, backreferences — incl. every reviewed probe) are refused at
+// compile before any input is matched; an exotic construct outside these structural shapes is not modelled.
+const REGEX_PATTERN_MAX = 200;
+
+// Linear (O(pattern length)) structural scan: does `p` contain a quantified group whose body repeats or
+// alternates at any nesting depth, or a backreference? Tracks one frame per open group; `complex` = the
+// group's body holds a quantifier/alternation (bubbled up from descendants), so a quantifier on the group's
+// `)` makes it catastrophic. Skips escapes (\w, \(, …) and char-class interiors ([a+]) where metachars are
+// literal, and the `?` of a group prefix ((?:, (?=, (?<…), which is not a quantifier.
+function isCatastrophicRegex(p) {
+  const stack = [];
+  for (let i = 0; i < p.length; i++) {
+    const c = p[i];
+    if (c === '\\') {
+      const n = p[i + 1];
+      if (n >= '1' && n <= '9') return true; // backreference → refuse
+      i++; // skip the escaped atom — never structural
+      continue;
+    }
+    if (c === '[') { // character class: every metachar inside is a literal
+      i++;
+      if (p[i] === '^') i++;
+      if (p[i] === ']') i++; // a leading ] is a literal member
+      while (i < p.length && p[i] !== ']') {
+        if (p[i] === '\\') i++;
+        i++;
+      }
+      continue;
+    }
+    if (c === '(') {
+      stack.push({ complex: false });
+      if (p[i + 1] === '?') i++; // group prefix ((?:, (?=, (?<…) — its ? is not a quantifier
+      continue;
+    }
+    if (c === ')') {
+      const f = stack.pop() || { complex: false };
+      const q = p[i + 1];
+      if ((q === '+' || q === '*' || q === '?' || q === '{') && f.complex) return true; // quantified group, repeating body
+      if (stack.length) stack[stack.length - 1].complex = stack[stack.length - 1].complex || f.complex; // bubble up any depth
+      continue;
+    }
+    if ((c === '|' || c === '+' || c === '*' || c === '?' || c === '{') && stack.length) {
+      stack[stack.length - 1].complex = true; // a quantifier/alternation token in the current group's body
+    }
+  }
+  return false;
+}
+
+// Compile a user-supplied --regex pattern. Case-sensitive, no g/y flag, so .test() is stateless across the
+// thousands of calls the scan makes. A too-long / catastrophic / malformed pattern fails LOUD (the AC's
+// invalid-input handling) — the operator sees one clean line, never a stack or a multi-second hang.
+function compileUserRegex(pattern) {
+  const p = String(pattern);
+  if (p.length > REGEX_PATTERN_MAX) {
+    throw inputError(`chat-search: --regex pattern too long (max ${REGEX_PATTERN_MAX} chars)`);
+  }
+  if (isCatastrophicRegex(p)) {
+    throw inputError('chat-search: --regex pattern rejected — a quantified group whose body repeats or alternates (or a backreference) risks catastrophic backtracking (ReDoS); simplify the pattern');
+  }
+  try {
+    return new RegExp(p);
+  } catch (err) {
+    throw inputError(`chat-search: --regex pattern is not a valid regular expression (${err.message})`);
+  }
+}
+
 // ── 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 }.
+// searchConversationalLog(query, opts, roots): scan BOTH arms across the given roots' sessions and return
+// the turns that match `query` — a case-insensitive substring by default, or (opts.regex) the compiled
+// pattern. opts also carries the slice-3 filters: opts.session scopes to one session, opts.since is a
+// timestamp floor; both are applied per-record so they compose with the arms, recency, and dedup. A bad
+// flag value (invalid/catastrophic regex, unparseable --since, unsafe --session) throws a user-facing
+// error (fail loud). 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 = [];
+  const seen = new Set(); // a prompt present in BOTH arms (same session+ts+text) must surface only once.
+  let degraded = false; // set when the transcript arm could not be consulted → loud events-only degrade (#84).
+
+  // ── slice-3 filters (#85): each is an opts field applied per-record inside consider(), so it composes
+  // automatically with BOTH arms, the recency sort, and the cross-arm dedup. --session scopes to one session. ──
+  const sessionScope = opts && opts.session != null ? validateSession(opts.session) : null;
+  const sinceThreshold = opts && opts.since != null ? parseSince(opts.since) : null; // --since: epoch-ms floor
+  const useRegex = !!(opts && opts.regex);
+  const re = useRegex ? compileUserRegex(q) : null; // --regex: compile once (throws loud on a bad/dangerous pattern)
+  // The one matcher used for BOTH the whole-text scan gate and the per-line snippet — substring or regex.
+  const lineMatches = useRegex ? (s) => re.test(String(s)) : (s) => String(s).toLowerCase().includes(needle);
+
+  // Push a hit when `text` contains the needle and this (session, timestamp, text) triple is new. `text` is
+  // the FULL message text already made surface-safe by its arm (events are pre-redacted; transcript turns are
+  // injected-stripped + secret-redacted before they reach here), so the snippet it yields is safe to render.
+  function consider(ts, session, role, text) {
+    if (sessionScope != null && session !== sessionScope) return; // --session: exact-match a single session
+    if (typeof text !== 'string' || !lineMatches(text)) return; // --regex pattern, else case-insensitive substring
+    if (sinceThreshold != null && !(Date.parse(ts) >= sinceThreshold)) return; // --since: drop hits before the floor (an undatable ts → NaN → dropped)
+    const key = `${session}${ts}${text}`; // the AC dedup key — NUL-joined so the parts can't bleed.
+    if (seen.has(key)) return;
+    seen.add(key);
+    hits.push({ ts, session, role, snippet: snippetFor(text, lineMatches) });
+  }
 
   for (const root of normalizeRoots(roots)) {
+    // ── event-log arm (slice 1): pre-redacted user prompts under <root>/.wrxn/events ──
     for (const file of listEventFiles(eventsDirOf(root))) {
       let lines;
       try {
@@ -90,8 +368,47 @@ function searchConversationalLog(query, opts, roots) {
           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) });
+        consider(rec.ts, rec.sid, roleFromKind(rec.kind), rec.text); // events are pre-redacted upstream — pass through as-is.
+      }
+    }
+
+    // ── harness-transcript arm (#84): assistant turns + full user/assistant message content ──
+    const home = (opts && opts.transcriptsHome) || defaultTranscriptsHome();
+    const tdir = resolveTranscriptDir(root, home);
+    let tfiles = null;
+    if (tdir) {
+      try {
+        tfiles = listTranscriptFiles(tdir); // a present dir yields an array (possibly empty); absent/unreadable throws.
+      } catch {
+        /* absent / unreadable transcript dir → tfiles stays null → degrade below */
+      }
+    }
+    // tfiles null ⇒ the arm could NOT be consulted (dir refused by the slug guard, or absent/unreadable) →
+    // loud events-only degrade. A present-but-empty dir yields [] (arm reachable, simply nothing) → NO degrade.
+    if (!tfiles) {
+      degraded = true;
+    } else {
+      for (const file of tfiles) {
+        let lines;
+        try {
+          lines = fs.readFileSync(file, 'utf8').split('\n');
+        } catch {
+          continue; // an unreadable transcript entry → skip it, keep scanning (never crash)
+        }
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          let rec;
+          try {
+            rec = JSON.parse(line);
+          } catch {
+            continue; // skip a malformed transcript line, never crash the scan
+          }
+          if (!rec || (rec.type !== 'user' && rec.type !== 'assistant')) continue; // only user/assistant turns; unknown line types (summary/system/…) skipped
+          // hygiene pipeline: flatten → strip injected framework context (a block holding the term is not a
+          // hit) → redact secrets (raw chat can echo a credential; scrub BEFORE it can surface in a snippet).
+          const text = redactSecrets(stripInjectedContext(transcriptText(rec)));
+          consider(rec.timestamp, rec.sessionId, rec.type, text);
+        }
       }
     }
   }
@@ -100,14 +417,19 @@ function searchConversationalLog(query, opts, roots) {
   hits.sort((a, b) => (Date.parse(b.ts) || 0) - (Date.parse(a.ts) || 0));
 
   const found = hits.length > 0;
-  const rendered = found
+  // Loud degrade (#84): when the transcript arm could not be consulted, say so on its own line so the
+  // operator knows results are EVENTS-ONLY (no assistant turns, no full message content) — never silent.
+  const head = found
     ? hits.map((h) => renderHit(h, opts)).join('\n')
-    : `chat-search: nothing found for "${q}" in the conversational log (event log).`;
+    : `chat-search: nothing found for "${q}" in the conversational log.`;
+  const rendered = degraded
+    ? `${head}\nchat-search: transcript arm unavailable — showing event-log results only.`
+    : head;
 
-  return { query: q, total: hits.length, found, hits, rendered };
+  return { query: q, total: hits.length, found, degraded, hits, rendered };
 }
 
-// ── CLI: node .wrxn/chat-search.cjs <term...> [--root <dir>] ──────────────────
+// ── CLI: node .wrxn/chat-search.cjs <term...> [--root <dir>] [--session <id>] [--since <when>] [--regex] ──
 // 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.
@@ -124,9 +446,18 @@ function findInstallRoot(start) {
   return null;
 }
 
+// Value of a --name <value> flag. A following token that is itself a --flag (or a missing value) is NOT
+// consumed as the value — so `--session --regex` can't silently swallow --regex as the session id.
 function flag(name) {
   const i = process.argv.indexOf(`--${name}`);
-  return i > -1 ? process.argv[i + 1] : undefined;
+  if (i < 0) return undefined;
+  const val = process.argv[i + 1];
+  return val == null || val.startsWith('--') ? undefined : val;
+}
+
+// Presence of a boolean --name flag (e.g. --regex), which carries no value.
+function hasFlag(name) {
+  return process.argv.includes(`--${name}`);
 }
 
 // Positional search terms: argv from index 2 up to the first --flag.
@@ -142,7 +473,7 @@ function positionals() {
 function main() {
   const terms = positionals();
   if (terms.length === 0) {
-    process.stdout.write('Usage: node .wrxn/chat-search.cjs <search-term...> [--root <dir>]\n');
+    process.stdout.write('Usage: node .wrxn/chat-search.cjs <search-term...> [--root <dir>] [--session <id>] [--since <when>] [--regex]\n');
     process.exit(2);
   }
   const root = flag('root') || findInstallRoot();
@@ -150,9 +481,27 @@ function main() {
     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);
+  // Wire the slice-3 flags (#85) into engine opts. The engine validates them (it throws a clean, user-facing
+  // error on a bad regex / unparseable --since); the CLI catch below prints that one line and exits non-zero.
+  const opts = {};
+  const session = flag('session');
+  if (session !== undefined) opts.session = session;
+  const since = flag('since');
+  if (since !== undefined) opts.since = since;
+  if (hasFlag('regex')) opts.regex = true;
+
+  let result;
+  try {
+    result = searchConversationalLog(terms.join(' '), opts, root);
+  } catch (err) {
+    if (err && err.userFacing) {
+      // invalid flag input (bad/catastrophic regex, unparseable --since): fail LOUD with the one clean line
+      // the engine already built — never a Node stack or path — and exit non-zero (usage error).
+      process.stderr.write(err.message + '\n');
+      process.exit(2);
+    }
+    throw err; // an unexpected fault → the entrypoint wrap turns it into a clean path-free diagnostic
+  }
   process.stdout.write(result.rendered + '\n');
   process.exit(0);
 }
@@ -170,4 +519,4 @@ if (require.main === module) {
   }
 }
 
-module.exports = { searchConversationalLog, renderHit };
+module.exports = { searchConversationalLog, renderHit, resolveTranscriptDir };