@nurix/etna 0.18.10 → 0.18.12

package/data/harnesses/etna/hooks/generate-ownership-index.mjs

@@ -0,0 +1,148 @@
+// plugins/code/hooks/generate-ownership-index.mjs — SessionStart hook: scan docs/features/**/*.md,
+// extract the focal frontmatter (owns / module / keywords / status), and inject a compact
+// code-path → owning-doc index via additionalContext. Fires on startup/resume/clear/compact so the
+// map survives /clear and /compact and is regenerated fresh every time. Writes no file.
+
+import fs from "node:fs";
+import path from "node:path";
+
+// 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();
+}
+
+// Recursively collect every .md file under dir (returns [] if the dir is absent).
+function listMarkdown(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (e) {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listMarkdown(full));
+    else if (entry.isFile() && entry.name.endsWith(".md")) out.push(full);
+  }
+  return out;
+}
+
+// Pull the leading `--- … ---` frontmatter block; "" if the file has none.
+function frontmatter(text) {
+  const m = /^?---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  return m ? m[1] : "";
+}
+
+// Trim surrounding whitespace, then strip one layer of matching quotes.
+function unquote(s) {
+  return String(s).trim().replace(/^["']|["']$/g, "").trim();
+}
+
+// Read one frontmatter key: scalar (`k: v`), inline array (`k: [a, b]`), or a following `- item` block.
+// Returns a string for scalars, an array for lists, or undefined when the key is absent.
+function field(block, key) {
+  const lines = block.split(/\r?\n/);
+  const head = new RegExp(`^${key}\\s*:\\s*(.*)$`);
+  for (let i = 0; i < lines.length; i++) {
+    const m = head.exec(lines[i]);
+    if (!m) continue;
+    const raw = m[1].trim();
+    if (raw === "") {
+      const items = [];
+      for (let j = i + 1; j < lines.length; j++) {
+        const li = /^\s*-\s+(.*)$/.exec(lines[j]);
+        if (!li) break;
+        items.push(unquote(li[1]));
+      }
+      return items;
+    }
+    if (raw.startsWith("[")) {
+      return raw.replace(/^\[|\]$/g, "").split(",").map((s) => unquote(s)).filter(Boolean);
+    }
+    return unquote(raw);
+  }
+  return undefined;
+}
+
+// Coerce a field that may be scalar/array/undefined into a clean string array.
+function asList(v) {
+  if (v == null) return [];
+  return (Array.isArray(v) ? v : [v]).map((s) => String(s).trim()).filter(Boolean);
+}
+
+// Build the ownership index text from every feature doc's frontmatter.
+function buildIndex(projectDir) {
+  const featuresDir = path.join(projectDir, "docs", "features");
+  const files = listMarkdown(featuresDir);
+  const lines = [];
+  let deprecated = 0;
+  for (const file of files) {
+    let text;
+    try {
+      text = fs.readFileSync(file, "utf8");
+    } catch (e) {
+      continue;
+    }
+    const block = frontmatter(text);
+    if (!block) continue;
+    const owns = asList(field(block, "owns"));
+    if (owns.length === 0) continue;
+    const status = (field(block, "status") || "active").toString().toLowerCase();
+    if (status === "deprecated") {
+      deprecated += 1;
+      continue; // keep deprecated docs out of the routing lines
+    }
+    const moduleLabel = (field(block, "module") || "—").toString();
+    const keywords = asList(field(block, "keywords"));
+    const doc = path.relative(projectDir, file).split(path.sep).join("/");
+    const kw = keywords.length ? `[${keywords.join(", ")}]` : "[]";
+    for (const glob of owns) {
+      lines.push(`${glob} → ${doc} · ${moduleLabel} · ${kw} · ${status}`);
+    }
+  }
+  if (lines.length === 0) return "";
+  lines.sort();
+  const header =
+    "# Ownership index (generated) — code-path glob → owning feature doc · module · keywords · status\n" +
+    "# Match the file or topic you're about to touch, then read the owning doc before changing it.\n";
+  const footer = deprecated > 0 ? `\n# (${deprecated} deprecated feature doc(s) omitted)` : "";
+  return header + lines.join("\n") + footer;
+}
+
+function main() {
+  const raw = readStdin();
+  let payload = {};
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    payload = {};
+  }
+  const index = buildIndex(resolveProjectDir(payload));
+  if (!index) return; // no feature docs yet → inject nothing
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: index,
+      },
+    })
+  );
+}
+
+try {
+  main();
+} catch (e) {
+  // Best-effort: a routing index is a convenience, never a gate. Inject nothing on failure.
+} finally {
+  process.exit(0);
+}

package/data/harnesses/etna/hooks/hooks.json

@@ -0,0 +1,39 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/generate-ownership-index.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-reflect.mjs\"",
+            "async": true
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/prompt-recall.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/data/harnesses/etna/hooks/lib/redact.mjs

@@ -0,0 +1,35 @@
+// harness/code/hooks/lib/redact.mjs — shared privacy filter: redacts secret shapes before ledger append.
+
+// Patterns ordered most-specific first; each replaces a match with [redacted:{kind}].
+const RULES = [
+  // PEM private/public key blocks (multiline).
+  { kind: "pem", re: /-----BEGIN[\s\S]*?-----END[^-]*-----/g },
+  // OpenAI / Anthropic-style keys (sk-..., sk-ant-...).
+  { kind: "api-key", re: /\bsk-(?:ant-)?[A-Za-z0-9_-]{8,}\b/g },
+  // AWS access key IDs.
+  { kind: "aws-key", re: /\bAKIA[0-9A-Z]{16}\b/g },
+  // Bearer tokens in Authorization context.
+  { kind: "bearer", re: /\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi },
+  // password= / passwd= / secret= / token= / api_key= style assignments (= or :).
+  {
+    kind: "credential",
+    re: /\b(?:password|passwd|pwd|secret|token|api[_-]?key|access[_-]?key|client[_-]?secret)\b\s*[:=]\s*["']?[^\s"'&)\]},;[]{3,}/gi,
+  },
+  // Generic long hex/base64 token ONLY in a key-value credential context.
+  {
+    kind: "credential",
+    re: /\b(?:key|auth|cred|credential|signature|sig)\b\s*[:=]\s*["']?[A-Za-z0-9+/=_-]{32,}/gi,
+  },
+];
+
+// Redact secret shapes in arbitrary text; returns a string with placeholders.
+function redact(text) {
+  if (text == null) return "";
+  let out = String(text);
+  for (const rule of RULES) {
+    out = out.replace(rule.re, `[redacted:${rule.kind}]`);
+  }
+  return out;
+}
+
+export { redact };

package/data/harnesses/etna/hooks/prompt-recall.mjs

@@ -0,0 +1,155 @@
+// plugins/code/hooks/prompt-recall.mjs — UserPromptSubmit hook: surface fact-cards relevant to the prompt via qmd BM25; stdout is injected as context.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node: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);
+}

package/data/harnesses/etna/hooks/session-reflect.mjs

@@ -0,0 +1,285 @@
+// plugins/code/hooks/session-reflect.mjs — SessionEnd hook: reflect the session into durable lessons (headless haiku pass) appended to the actor's memory inbox.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync, spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { redact } from "./lib/redact.mjs";
+
+// ESM has no __filename; derive it from this module's URL for the detached worker re-spawn.
+const __filename = fileURLToPath(import.meta.url);
+
+// A session below all three thresholds carries no lesson worth a model call.
+const MIN_TURNS = 8;
+const MAX_MESSAGE_CHARS = 1500;
+const MAX_DIGEST_CHARS = 80000;
+const MAX_LESSONS = 6;
+
+// 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();
+}
+
+// Run a git command in projectDir; returns trimmed stdout or fallback on any error.
+function git(projectDir, args, fallback) {
+  try {
+    return execFileSync("git", ["-C", projectDir, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim() || fallback;
+  } catch (e) {
+    return fallback;
+  }
+}
+
+// Slug a raw actor name into kebab-case ASCII.
+function slugActor(name) {
+  return String(name || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+// Determine the actor: git user.name (slugged) → $USER → "agent".
+function resolveActor(projectDir) {
+  const fromGit = slugActor(git(projectDir, ["config", "user.name"], ""));
+  if (fromGit) return fromGit;
+  const fromEnv = slugActor(process.env.USER || "");
+  if (fromEnv) return fromEnv;
+  return "agent";
+}
+
+// Truncate a single line to n chars with an ellipsis marker.
+function clip(text, n) {
+  const clean = String(text || "").replace(/\s+/g, " ").trim();
+  return clean.length > n ? clean.slice(0, n) + "…" : clean;
+}
+
+// Extract plain text from a message whose content is a string or content-block array.
+function extractText(msg) {
+  if (!msg || !msg.content) return "";
+  if (typeof msg.content === "string") return msg.content;
+  if (Array.isArray(msg.content)) {
+    return msg.content
+      .filter((b) => b && b.type === "text" && typeof b.text === "string")
+      .map((b) => b.text)
+      .join(" ");
+  }
+  return "";
+}
+
+// Strip harness-injected wrappers so only what the user actually typed survives.
+function stripInjected(text) {
+  return String(text || "")
+    .replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, "")
+    .replace(/<(local-command-caveat|local-command-stdout|local-command-stderr|command-name|command-message|command-args|command-contents)>[\s\S]*?<\/\1>/g, "")
+    .trim();
+}
+
+// Scan an assistant message's tool_use blocks for edited files and git commits.
+function collectToolUse(msg, summary) {
+  if (!msg || !Array.isArray(msg.content)) return;
+  for (const block of msg.content) {
+    if (!block || block.type !== "tool_use") continue;
+    const name = block.name || "";
+    const input = block.input || {};
+    if (/^(Edit|Write|MultiEdit|NotebookEdit)$/.test(name) && input.file_path) {
+      summary.files.add(input.file_path);
+    }
+    if (name === "Bash" && typeof input.command === "string" && /\bgit\s+commit\b/.test(input.command)) {
+      summary.sawCommit = true;
+    }
+  }
+}
+
+// Walk the JSONL transcript once: turn/edit/commit counts plus a USER/ASSISTANT text digest.
+function digestTranscript(transcriptPath) {
+  const out = { turns: 0, files: new Set(), sawCommit: false, lines: [] };
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) return out;
+  for (const line of fs.readFileSync(transcriptPath, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch (e) {
+      continue;
+    }
+    if (row.isSidechain) continue;
+    const msg = row && row.message ? row.message : row;
+    const role = (msg && msg.role) || row.type;
+    if (role === "user") {
+      const text = stripInjected(extractText(msg));
+      if (!text || text.startsWith("Caveat: The messages below")) continue;
+      out.lines.push("USER: " + clip(text, MAX_MESSAGE_CHARS));
+    } else if (role === "assistant") {
+      out.turns += 1;
+      collectToolUse(msg, out);
+      const text = extractText(msg);
+      if (text) out.lines.push("ASSISTANT: " + clip(text, MAX_MESSAGE_CHARS));
+    }
+  }
+  return out;
+}
+
+// Compute the per-actor inbox file path.
+function inboxPath(projectDir, actor) {
+  const dir = path.join(projectDir, "docs", "memory", "inbox");
+  return { dir, file: path.join(dir, `${actor}.md`) };
+}
+
+// True when this session already wrote an inbox entry (SessionEnd re-fires on resume).
+function alreadyReflected(file, sessionId) {
+  try {
+    return Boolean(sessionId) && fs.existsSync(file) && fs.readFileSync(file, "utf8").includes(`session ${sessionId}`);
+  } catch (e) {
+    return false;
+  }
+}
+
+// Build the inbox file header block.
+function inboxHeader(actor) {
+  return `# Memory inbox — ${actor}\nSession lessons awaiting distillation — appended by the session-reflect hook, consumed by \`distiller facts\`.\n`;
+}
+
+// The full output contract sits AFTER the transcript — with it only up front, the model
+// continues the conversation in the transcript instead of reflecting on it.
+const PROMPT_HEADER = [
+  "You are a memory reflector. Below is the transcript of a FINISHED coding session,",
+  "delimited by <transcript> tags. Do not reply to it or continue it — you will be asked",
+  "to extract durable lessons from it after the closing tag.",
+  "",
+  "<transcript>",
+  "",
+].join("\n");
+
+const PROMPT_FOOTER = [
+  "",
+  "</transcript>",
+  "",
+  "The session above is over. Extract ONLY durable lessons a future session in this",
+  "repository would benefit from knowing:",
+  "- corrections or preferences the user stated",
+  "- failures whose root cause was found, with the fix",
+  "- decisions made, with their rationale",
+  "- discovered constraints or non-obvious facts about the project or its tooling",
+  "Rules:",
+  "- Most sessions contain none. If nothing qualifies, output exactly: NONE",
+  `- Otherwise output at most ${MAX_LESSONS} bullets and nothing else — no preamble, no headers.`,
+  '- Each bullet starts with "- [project]" (true of this repo or its tooling) or "- [user]" (true of this user).',
+  "- Each bullet is one complete, self-contained sentence with names and identifiers spelled out.",
+  "- Routine work (commits made, files edited, tasks completed) is NOT a lesson. Never include secrets.",
+].join("\n");
+
+// Hook mode: stash the payload and hand off to a detached worker so session exit is never delayed.
+function hook() {
+  const raw = readStdin();
+  let payload = {};
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    payload = {};
+  }
+  if (!payload.transcript_path) return;
+
+  const stash = {
+    projectDir: resolveProjectDir(payload),
+    transcriptPath: payload.transcript_path,
+    sessionId: payload.session_id || "",
+  };
+  const stashFile = path.join(os.tmpdir(), `etna-reflect-${stash.sessionId || process.pid}.json`);
+  fs.writeFileSync(stashFile, JSON.stringify(stash), "utf8");
+  spawn(process.execPath, [__filename, "--worker", stashFile], { detached: true, stdio: "ignore" }).unref();
+}
+
+// Worker mode: filter, digest, run the reflection model, append surviving lessons to the inbox.
+function worker(stashFile) {
+  let stash;
+  try {
+    stash = JSON.parse(fs.readFileSync(stashFile, "utf8"));
+  } finally {
+    try {
+      fs.rmSync(stashFile, { force: true });
+    } catch (e) {
+      // Stale stash files are harmless.
+    }
+  }
+
+  const { projectDir, transcriptPath, sessionId } = stash;
+  const digest = digestTranscript(transcriptPath);
+  if (digest.turns < MIN_TURNS && digest.files.size === 0 && !digest.sawCommit) return;
+
+  const actor = resolveActor(projectDir);
+  const { dir, file } = inboxPath(projectDir, actor);
+  if (alreadyReflected(file, sessionId)) return;
+
+  let text = redact(digest.lines.join("\n"));
+  if (text.length > MAX_DIGEST_CHARS) {
+    text = text.slice(0, 8000) + "\n[... middle of session elided ...]\n" + text.slice(-(MAX_DIGEST_CHARS - 8000));
+  }
+
+  const output = execFileSync("claude", ["-p", "--model", "haiku"], {
+    input: PROMPT_HEADER + text + PROMPT_FOOTER,
+    encoding: "utf8",
+    cwd: os.tmpdir(),
+    env: Object.assign({}, process.env, { ETNA_REFLECT: "1" }),
+    timeout: 240000,
+    maxBuffer: 4 * 1024 * 1024,
+    stdio: ["pipe", "pipe", "ignore"],
+  });
+
+  const lessons = output
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => /^- \[(project|user)\]\s+\S/.test(l))
+    .slice(0, MAX_LESSONS)
+    .map((l) => redact(l));
+  if (!lessons.length) return;
+
+  const repo = path.basename(projectDir);
+  const branch = git(projectDir, ["rev-parse", "--abbrev-ref", "HEAD"], "-");
+  const now = new Date();
+  const pad = (n) => String(n).padStart(2, "0");
+  const stamp = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}`;
+
+  fs.mkdirSync(dir, { recursive: true });
+  if (alreadyReflected(file, sessionId)) return;
+  const exists = fs.existsSync(file);
+  const block =
+    (exists ? "\n" : inboxHeader(actor) + "\n") +
+    `## ${stamp} · session ${sessionId || "unknown"} · ${repo}@${branch}\n` +
+    lessons.join("\n") +
+    "\n";
+  fs.appendFileSync(file, block, "utf8");
+}
+
+function main() {
+  if (process.env.ETNA_REFLECT) return;
+  const workerIdx = process.argv.indexOf("--worker");
+  if (workerIdx !== -1) {
+    worker(process.argv[workerIdx + 1]);
+  } else {
+    hook();
+  }
+}
+
+try {
+  main();
+} catch (e) {
+  try {
+    process.stderr.write(`session-reflect hook: ${e && e.message ? e.message : e}\n`);
+  } catch (e2) {
+    // Nothing more we can do.
+  }
+} finally {
+  process.exit(0);
+}