@nurix/etna 0.15.7 → 0.16.0

package/bin/etna.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 // packages/cli/bin/etna.js
-// `npx @nurix/etna <plugin-name>` — copy a Nurix harness into the current
+// `npx @nurix/etna <harness-name>` — copy a Nurix harness into the current
 // directory. Drops the harness's CLAUDE.md at the project root and copies its
 // skills, agents, rules, and scripts into <project>/.claude/. No marketplace,
 // no plugin enablement — files live in the project, version-controlled and
-// editable per project. Re-run `etna` to refresh.
+// editable per project. Re-run `etna` to refresh. Harnesses are addressed by
+// their harness/<folder> name; several harnesses may share one plugin.
 
 import {
     existsSync,
@@ -15,6 +16,7 @@ import {
     cpSync,
     readdirSync,
     lstatSync,
+    rmSync,
 } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -31,11 +33,13 @@ const PLUGIN_SUBDIRS = ['skills', 'agents', 'rules', 'scripts', 'hooks'];
 
 function usage() {
     const idx = loadHarnessIndex();
-    console.log(`\nUsage: npx @nurix/etna <plugin-name>\n`);
-    const names = Object.keys(idx.plugins);
-    if (names.length) {
+    console.log(`\nUsage: npx @nurix/etna <harness-name>\n`);
+    const entries = Object.entries(idx.harnesses || {});
+    if (entries.length) {
         console.log(`Available harnesses:`);
-        for (const name of names) console.log(`  ${name}`);
+        for (const [folder, plugin] of entries) {
+            console.log(`  ${folder}${plugin && plugin !== folder ? ` (plugin: ${plugin})` : ''}`);
+        }
     }
     console.log();
 }
@@ -125,6 +129,44 @@ function migrateFromPluginInstall(targetDir, pluginName) {
     return removed;
 }
 
+// Hook scripts shipped by earlier epochs (≤12, the memory-ledger tier) and since retired.
+// mergeHooks is additive, so an upgrade must explicitly remove both the stale settings.json
+// entries pointing at these and the leftover script files they reference.
+const RETIRED_HOOKS = ['session-stop.js', 'post-tool-failure.js', 'post-commit.js'];
+
+// Remove settings.json hook entries and .claude/hooks/ files for retired hook scripts.
+function retireOldHooks(targetDir) {
+    const removed = [];
+    const settingsPath = join(targetDir, '.claude', 'settings.json');
+    if (existsSync(settingsPath)) {
+        const settings = readJson(settingsPath);
+        const isRetired = (h) =>
+            RETIRED_HOOKS.some((name) => (h.command || '').includes(`/hooks/${name}`));
+        let pruned = 0;
+        for (const [event, groups] of Object.entries(settings.hooks || {})) {
+            for (const group of groups) {
+                const before = (group.hooks || []).length;
+                group.hooks = (group.hooks || []).filter((h) => !isRetired(h));
+                pruned += before - group.hooks.length;
+            }
+            settings.hooks[event] = groups.filter((g) => (g.hooks || []).length > 0);
+            if (settings.hooks[event].length === 0) delete settings.hooks[event];
+        }
+        if (pruned > 0) {
+            writeJson(settingsPath, settings);
+            removed.push(`${pruned} retired hook entr${pruned === 1 ? 'y' : 'ies'} in settings.json`);
+        }
+    }
+    for (const name of RETIRED_HOOKS) {
+        const file = join(targetDir, '.claude', 'hooks', name);
+        if (existsSync(file)) {
+            rmSync(file, { force: true });
+            removed.push(`stale hook script ${name}`);
+        }
+    }
+    return removed;
+}
+
 // True if an event's matcher-group already carries a hook with this command string.
 function groupHasCommand(group, command) {
     return (group.hooks || []).some((h) => h.command === command);
@@ -168,14 +210,15 @@ async function main(args) {
         process.exit(args.length === 0 ? 1 : 0);
     }
 
-    const pluginName = args[0];
+    const harnessName = args[0];
     const idx = loadHarnessIndex();
-    const harnessFolder = idx.plugins[pluginName];
-    if (!harnessFolder) {
+    const harnesses = idx.harnesses || {};
+    if (!harnesses[harnessName]) {
         die(
-            `Unknown harness '${pluginName}'. Available: ${Object.keys(idx.plugins).join(', ') || '(none)'}`,
+            `Unknown harness '${harnessName}'. Available: ${Object.keys(harnesses).join(', ') || '(none)'}`,
         );
     }
+    const harnessFolder = harnessName;
 
     const bundledHarnessDir = join(dataDir, 'harnesses', harnessFolder);
     const bundledClaudeMd = join(bundledHarnessDir, 'CLAUDE.md');
@@ -191,8 +234,11 @@ async function main(args) {
     const bundledHarnessJson = join(bundledHarnessDir, 'harness.json');
     const harnessMeta = existsSync(bundledHarnessJson) ? readJson(bundledHarnessJson) : {};
     const versionTag = harnessMeta.version ? ` v${harnessMeta.version}` : '';
+    // The underlying plugin's name — may differ from the harness name, and several
+    // harnesses may share it. Used only for legacy marketplace-entry cleanup.
+    const pluginName = harnessMeta.name || harnesses[harnessName] || harnessName;
 
-    console.log(`\nInstalling ${pluginName}${versionTag} into ${targetDir}`);
+    console.log(`\nInstalling ${harnessName}${versionTag} into ${targetDir}`);
 
     const claudeBackup = backupIfExists(claudeMdDest);
     if (claudeBackup) console.log(`  backed up existing CLAUDE.md → ${claudeBackup}`);
@@ -230,6 +276,11 @@ async function main(args) {
         console.log(`  installed harness.json → ${harnessJsonDest}${tag ? ` (${tag})` : ''}`);
     }
 
+    // Retire hooks earlier epochs shipped before merging, so the additive merge
+    // never resurrects an entry pointing at a script this bundle no longer carries.
+    const retiredHooks = retireOldHooks(targetDir);
+    for (const r of retiredHooks) console.log(`  removed ${r}`);
+
     // Merge the bundle's hooks.json into the project's settings.json (idempotent).
     const added = mergeHooks(targetDir, join(bundledHarnessDir, 'hooks', 'hooks.json'));
     if (added > 0) {
@@ -239,9 +290,9 @@ async function main(args) {
     const migrated = migrateFromPluginInstall(targetDir, pluginName);
     for (const entry of migrated) console.log(`  removed stale ${entry}`);
 
-    console.log(`\nDone — ${pluginName}${versionTag} installed: ${installed.join(', ')}.`);
+    console.log(`\nDone — ${harnessName}${versionTag} installed: ${installed.join(', ')}.`);
     console.log(
-        `Open Claude Code in ${targetDir}. Re-run \`npx @nurix/etna ${pluginName}\` anytime to refresh harness content.\n`,
+        `Open Claude Code in ${targetDir}. Re-run \`npx @nurix/etna ${harnessName}\` anytime to refresh harness content.\n`,
     );
 }
 

package/data/harness-index.json

@@ -1,8 +1,10 @@
 {
-    "fingerprint": "ea9d56be1c3e",
-    "plugins": {
-        "code": "code",
-        "kb-agi": "kb-agi",
-        "re": "re"
+    "fingerprint": "19ff4c6bce0e",
+    "harnesses": {
+        "code": "code-fable",
+        "code-fable": "code-fable",
+        "discover": "discover",
+        "hr": "hr",
+        "kb-agi": "kb-agi"
     }
 }

package/data/harnesses/code/CLAUDE.md

@@ -24,9 +24,6 @@ This is the only step that runs **before** the harness exists; everything below
 - Read **[`docs/memory/`](docs/memory/)** for agent memory files (one per agent)
 - Ignore **[`README.md`](README.md)** – it's for human reference only
 - Check **[`package.json`](package.json)** for available scripts. Detect the package manager from the lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm) and use the matching command. Don't hardcode a specific manager.
-- Look at similar modules/files and follow existing patterns
-
-- Check **[`.claude/rules/`](.claude/rules/)** for specialized instructions (automatically loaded into memory)
 
 ---
 
@@ -40,7 +37,7 @@ Three peer modes plus a Completion step — enter wherever the user's thinking a
 | **Spec** | new feature work | `spec-mode` agent + `documentation` skill | Plan |
 | **Plan** | a spec is approved | `documentation` skill → `docs/history/plans/YYYY-MM-DD-{slug}.md` | Completion |
 
-On **Completion**: freeze the plan (`Status: Complete`) and flip the feature spec to `Status: Active`, extending it with how-it-works sections; then distil the plan's trail — if the ledger holds entries past the distiller's high-water mark, run `distiller facts` (ledger→fact-cards), then `distiller docs` for the just-completed feature's doc drafts any pending deltas for approval (presented, never auto-written). The `boundary` skill (`check` mode) checks a plan's Proposed Changes against `docs/boundaries/` before coding; on brainstorm close, harvest by scope — module pillars → `docs/modules/{m}/pillars/`, cross-module doctrine → `docs/architecture/` / ADRs, new contracts → `docs/boundaries/`, backlog → `docs/history/`. Open questions block close.
+On **Completion**: freeze the plan (`Status: Complete`) and flip the feature spec to `Status: Active`, extending it with how-it-works sections; then distil the plan's trail — if the memory inbox (`docs/memory/inbox/`) holds entries, run `distiller facts` (inbox→fact-cards), then `distiller docs` for the just-completed feature's doc drafts any pending deltas for approval (presented, never auto-written). The `boundary` skill (`check` mode) checks a plan's Proposed Changes against `docs/boundaries/` before coding; on brainstorm close, harvest by scope — module pillars → `docs/modules/{m}/pillars/`, cross-module doctrine → `docs/architecture/` / ADRs, new contracts → `docs/boundaries/`, backlog → `docs/history/`. Open questions block close.
 
 ---
 
@@ -114,7 +111,8 @@ Unless explicitly requested:
 ❌ **Compatibility** – Never maintain backward compatibility unless specified.
 ❌ **Branches & Worktrees** – Never self-create git branches or worktrees. Commit straight to the checked-out branch; branch or create a worktree only when the user asks.
 ❌ **Protected Files** – Before editing, if `docs/operations/protected-files.md` exists, read it and never modify any path it lists; also never modify `AGENTS.md` or the `protected-files.md` file itself.
-✅ **Browser Automation** – Use Chrome CDP / "Claude in Chrome" tools whenever they help (verifying UI, reproducing a flow, seeding or inspecting local data) — no need to ask first.
+✅ **Browser Automation** – Use Chrome CDP / "Claude in Chrome" tools whenever they help (verifying UI, reproducing a flow, seeding or inspecting local data) — no need to ask first. **Main session only:** never drive the browser from a sub-agent or workflow executor — the session-bound Chrome connection destabilizes the sub-agent. A sub-agent that needs browser verification instead returns an explicit CDP checklist (exact URLs, actions, expected outcomes) for the orchestrator to execute in the main session.
+✅ **Orchestrate via Sub-agents** – Run the main session as an orchestrator: delegate substantive work (research, implementation, audits) to sub-agents spawned via the Agent/Task tool with `model: opus` (Claude Opus), keeping the main context for dispatch, coordination, and synthesis. Give each sub-agent a self-contained prompt; parallelize independent dispatches.
 ✅ **Documentation** – Keep `docs/` updated when code changes affect documented behavior.
 ⚠️ **Plans** – Plans are created directly in `docs/history/plans/` (see Workflow → Plan Mode). Once `Status: Complete` or `Status: Abandoned`, the file is frozen — never edited. If scope changes after completion, write a new dated plan that links back to the old one.
 ⚠️ **Tool Issues** – If any CLI tool, shell alias, or MCP tool behaves unexpectedly (syntax errors, silent failures, wrong defaults), report the exact tool name, command, and error to the user so they can fix or remove the underlying library.
@@ -127,8 +125,6 @@ Unless explicitly requested:
   `// src/modules/example.js - Module for handling user authentication`
 - Add a 1-line function description as a comment above each function:
   `// Extract JWT token from request based on endpoint type`
-- Keep related code together in a logical hierarchy.
-- No inline comments that restate obvious code. No commented-out code. If a block of code needs a comment to be understandable, refactor for clarity instead.
 
 ---
 

package/data/harnesses/code/agents/harness-manager.md

@@ -104,9 +104,9 @@ Table: `| File | Action | From | To | Reason |` (actions: `Move`, `Merge into {t
 
 Create the folder structure; move/fold/merge/delete per the plan; add `Status:` to plan files; add ownership frontmatter to feature docs (call the `documentation` skill's **frontmatter derivation** for `owns`/`touches`/`depends_on`); merge scattered backlogs into `docs/history/backlog.md`; fix links broken by moves. Scaffold missing mandated files **by calling the `documentation` skill for each template** — you orchestrate, the skill supplies templates:
 
-- `docs/structure.md` (with `harness-version`), `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/index.md`, `docs/memory/main.md`, `docs/memory/facts/.digest-state.md` (placeholder, "no entries digested yet"), and the repo-root `README.md` (filled from the real lockfile/scripts/layout — **never overwrite an existing root README**).
+- `docs/structure.md` (with `harness-version`), `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/index.md`, `docs/memory/main.md`, and the repo-root `README.md` (filled from the real lockfile/scripts/layout — **never overwrite an existing root README**).
 
-Scaffold `docs/memory/facts/` so the distilled tier has a home from day one: hooks write the raw ledger to `docs/memory/ledger/` (not a scaffold — created mechanically on first event), and the `distiller` digests it down into fact-cards under `docs/memory/facts/`. Without the facts dir + its `.digest-state.md` high-water mark, a freshly-baselined consumer accrues a ledger firehose the distiller has nowhere to land — so seed the empty distilled tier alongside the hook-written ledger tier.
+Scaffold `docs/memory/facts/` so the distilled tier has a home from day one: the `session-reflect` hook appends session lessons to the per-actor inbox at `docs/memory/inbox/{actor}.md` (not a scaffold — created mechanically on first reflection), and the `distiller` digests that queue down into fact-cards under `docs/memory/facts/`, consuming the entries it digests (no high-water mark, no `.digest-state.md`). Without the facts dir, a freshly-baselined consumer accrues inbox entries the distiller has nowhere to land — so seed the empty distilled tier alongside the hook-written inbox tier.
 
 ### Step 5 — Stamp the version
 
@@ -116,9 +116,9 @@ Write `harness-version: <installed epoch>` into `docs/structure.md` frontmatter.
 
 Strictly optional and guarded on the binary — if `command -v qmd` finds nothing, **skip this entire step silently** (no error, no behavior change) and carry one advisory line into the Step 6 hand-back: *"qmd not installed — semantic retrieval unavailable; glob routing active."* The index is a **local rebuildable lens** — data stays in git; never commit index artifacts, and never use `qmd init` (that writes a project-local `.qmd`; the default global index keeps the repo clean).
 
-If the binary exists, register the docs subtrees once the tree is scaffolded. **Do not register one collection rooted at `docs/`** — qmd 2.5.3 hard-codes the `**/*.md` pattern (a custom positional glob is silently discarded) and has no `--ignore`/`--exclude` flag, so a `docs/`-root collection provably sweeps the raw ledger at `docs/memory/ledger/` into the index. The raw ledger is **not** in scope (it is distilled into `memory/facts`, which is). Register one collection **per indexable subtree** instead — never `docs/memory` as a whole, only `docs/memory/facts` — so the ledger is excluded by construction:
+If the binary exists, register the docs subtrees once the tree is scaffolded. **Do not register one collection rooted at `docs/`** — qmd 2.5.3 hard-codes the `**/*.md` pattern (a custom positional glob is silently discarded) and has no `--ignore`/`--exclude` flag, so a `docs/`-root collection provably sweeps the consumable inbox queue at `docs/memory/inbox/` into the index. The inbox is **not** in scope (it is distilled into `memory/facts`, which is — and its entries are deleted on digestion, which would leave dangling index entries). Register one collection **per indexable subtree** instead — never `docs/memory` as a whole, only `docs/memory/facts` — so the inbox is excluded by construction:
 
-1. **Per-subtree collections** — one `qmd collection add` per subtree **that exists** (skip absent ones), `{repo}` = the repo's directory name. Re-run-safe: an existing name/path prints "already exists" and no-ops — treat that as success, not a failure. **Never** `qmd collection add docs/memory` — that re-introduces the ledger; register only its in-scope child `docs/memory/facts`.
+1. **Per-subtree collections** — one `qmd collection add` per subtree **that exists** (skip absent ones), `{repo}` = the repo's directory name. Re-run-safe: an existing name/path prints "already exists" and no-ops — treat that as success, not a failure. **Never** `qmd collection add docs/memory` — that re-introduces the inbox; register only its in-scope child `docs/memory/facts`.
    - `qmd collection add docs/features --name {repo}-features`
    - `qmd collection add docs/boundaries --name {repo}-boundaries`
    - `qmd collection add docs/architecture --name {repo}-architecture`

package/data/harnesses/code/agents/maintenance.md

@@ -95,7 +95,7 @@ For unowned code paths:
 1. Update `docs/structure.md` Health Log with today's date and summary
 2. Update `docs/memory/maintenance.md` with last review date, stale docs fixed, unowned paths, backlog items created
 3. Report findings: stale docs, broken ownership, unowned code, architecture drift, backlog health
-4. **Ledger-distillation threshold.** Count undigested ledger entries — `docs/memory/ledger/**/*.md` entries newer than the high-water mark in `docs/memory/facts/.digest-state.md` (absent state-file ⇒ every entry counts). If the count is **≥20**, add one line to the report **proposing** a `distiller` `facts` run — propose only, never auto-run, no cron. If the user declines or ignores it, do nothing: the count keeps growing and the proposal reappears next pass — that recurrence *is* the dedupe, so never backlog it.
+4. **Inbox-distillation threshold.** Count undigested inbox entries — `## ` entry blocks across `docs/memory/inbox/*.md` (the inbox is consume-on-digest, so every block present is undigested). If the count is **≥5**, add one line to the report **proposing** a `distiller` `facts` run — propose only, never auto-run, no cron. If the user declines or ignores it, do nothing: the count keeps growing and the proposal reappears next pass — that recurrence *is* the dedupe, so never backlog it.
 5. **Docs-distillation threshold.** Per target doc, count undigested fact-cards (`invalid_from: null`, the doc's path not in their `digested_into:`) that **touch** it by the structural intersection in `skills/distiller/references/docs-mode.md` Resolution 1 (provenance∩`owns` strong, entities∩declared-ownership supporting — qmd-independent). If **≥10** map to **one** doc, add one line to the report **proposing** a `distiller docs --doc <path>` run on that doc — propose only, never auto-run, no cron. Declined or ignored ⇒ the count keeps growing and the proposal reappears next pass; that recurrence *is* the dedupe, so never backlog the proposal.
 
 ## Step 8: Refresh Index (Optional)

package/data/harnesses/code/harness.json

@@ -1,6 +1,7 @@
 {
-  "name": "code",
+  "harness": "code",
+  "name": "code-fable",
   "version": "0.15.3",
-  "epoch": 12,
-  "digest": "8bd2f1540f40"
+  "epoch": 13,
+  "digest": "c7bce77bd71f"
 }

package/data/harnesses/code/hooks/hooks.json

@@ -6,33 +6,19 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-stop.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-reflect.js\"",
             "async": true
           }
         ]
       }
     ],
-    "PostToolUseFailure": [
+    "UserPromptSubmit": [
       {
         "matcher": "",
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-tool-failure.js\"",
-            "async": true
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Bash",
-        "if": "Bash(git commit *)",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-commit.js\"",
-            "async": true
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/prompt-recall.js\""
           }
         ]
       }

package/data/harnesses/code/hooks/prompt-recall.js

@@ -0,0 +1,157 @@
+// plugins/code/hooks/prompt-recall.js — UserPromptSubmit hook: surface fact-cards relevant to the prompt via qmd BM25; stdout is injected as context.
+
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const MIN_PROMPT_CHARS = 24;
+const MIN_SCORE = 0.45;
+const MAX_CARDS = 3;
+const MAX_STATEMENT_CHARS = 300;
+const MAX_KEYWORDS = 8;
+
+const STOPWORDS = new Set(
+  "a an and are as at be but by can could do does for from has have how i in is it its me my of on or our should so that the their then there these this to was we what when where which who why will with would you your".split(
+    " ",
+  ),
+);
+
+// Read all of stdin synchronously; returns "" if nothing is piped.
+function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch (e) {
+    return "";
+  }
+}
+
+// Resolve the project root: CLAUDE_PROJECT_DIR env, else payload cwd, else process cwd.
+function resolveProjectDir(payload) {
+  return process.env.CLAUDE_PROJECT_DIR || (payload && payload.cwd) || process.cwd();
+}
+
+// Map a qmd://collection/relpath hit URI to the card file under docs/memory/facts/.
+function cardPath(factsDir, fileUri) {
+  return path.join(factsDir, String(fileUri || "").replace(/^qmd:\/\/[^/]+\//, ""));
+}
+
+// A card's atomic statement: the body after frontmatter, whitespace-flattened and clipped.
+function cardStatement(file) {
+  try {
+    const body = fs
+      .readFileSync(file, "utf8")
+      .replace(/^---\n[\s\S]*?\n---\n?/, "")
+      .replace(/\s+/g, " ")
+      .trim();
+    return body.length > MAX_STATEMENT_CHARS ? body.slice(0, MAX_STATEMENT_CHARS) + "…" : body;
+  } catch (e) {
+    return "";
+  }
+}
+
+// Run one qmd search mode against the facts collection; [] on any failure — recall is strictly optional.
+function qmdHits(mode, query, collection) {
+  try {
+    const out = JSON.parse(
+      execFileSync("qmd", [mode, query, "--format", "json", "-n", String(MAX_CARDS + 2), "-c", collection], {
+        encoding: "utf8",
+        timeout: 10000,
+        stdio: ["ignore", "pipe", "ignore"],
+      }),
+    );
+    return Array.isArray(out) ? out : [];
+  } catch (e) {
+    return [];
+  }
+}
+
+// Main: search the facts collection for the prompt and emit unseen high-score cards.
+function main() {
+  if (process.env.ETNA_REFLECT) return;
+
+  const raw = readStdin();
+  let payload = {};
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    payload = {};
+  }
+
+  const prompt = String(payload.prompt || "").trim();
+  if (!prompt || prompt.startsWith("/") || prompt.length < MIN_PROMPT_CHARS) return;
+
+  const projectDir = resolveProjectDir(payload);
+  const factsDir = path.join(projectDir, "docs", "memory", "facts");
+  let hasCards = false;
+  try {
+    hasCards = fs.readdirSync(factsDir).some((f) => f.endsWith(".md"));
+  } catch (e) {
+    return;
+  }
+  if (!hasCards) return;
+
+  // BM25 keywords first (fast, strict-AND), vector similarity as the natural-language
+  // fallback (~1s warm) — `qmd query` (LLM expansion + rerank) is too slow to block a prompt.
+  const collection = `${path.basename(projectDir)}-facts`;
+  const keywords = Array.from(
+    new Set(
+      prompt
+        .toLowerCase()
+        .replace(/[^a-z0-9\s_./-]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 2 && !STOPWORDS.has(w)),
+    ),
+  )
+    .slice(0, MAX_KEYWORDS)
+    .join(" ");
+  let hits = keywords ? qmdHits("search", keywords, collection) : [];
+  if (!hits.length) hits = qmdHits("vsearch", prompt.replace(/\s+/g, " ").slice(0, 300), collection);
+  if (!hits.length) return;
+
+  // Inject each card at most once per session.
+  const sessionKey = String(payload.session_id || "any").replace(/[^a-zA-Z0-9-]/g, "");
+  const stateFile = path.join(os.tmpdir(), `etna-recall-${sessionKey}.txt`);
+  let seen = [];
+  try {
+    seen = fs.readFileSync(stateFile, "utf8").split("\n").filter(Boolean);
+  } catch (e) {
+    seen = [];
+  }
+
+  const fresh = hits
+    .filter((h) => h && h.score >= MIN_SCORE && h.file && !seen.includes(h.file))
+    .slice(0, MAX_CARDS);
+  const lines = [];
+  for (const hit of fresh) {
+    const statement = cardStatement(cardPath(factsDir, hit.file));
+    if (statement) {
+      lines.push(`- ${statement} [${String(hit.file).replace(/^qmd:\/\/[^/]+\//, "docs/memory/facts/")}]`);
+    }
+  }
+  if (!lines.length) return;
+
+  try {
+    fs.appendFileSync(stateFile, fresh.map((h) => h.file).join("\n") + "\n", "utf8");
+  } catch (e) {
+    // Dedupe state is best-effort; a re-injection is harmless.
+  }
+
+  process.stdout.write(
+    `<memory-recall>\nProject memory possibly relevant to this prompt (distilled fact-cards):\n${lines.join("\n")}\n</memory-recall>\n`,
+  );
+}
+
+try {
+  main();
+} catch (e) {
+  try {
+    process.stderr.write(`prompt-recall hook: ${e && e.message ? e.message : e}\n`);
+  } catch (e2) {
+    // Nothing more we can do.
+  }
+} finally {
+  process.exit(0);
+}