@gcunharodrigues/wrxn 0.1.0

package/payload/.claude/hooks/enforce-managed-guard.cjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+'use strict';
+
+// WRXN managed hook — protect MANAGED kernel files inside an install (the ring-0 reshape).
+// PreToolUse:Edit|Write. Blocks an agent edit/write to a file classified `managed` in the
+// install receipt unless WRXN_MANAGED_CONFIRM is set. Seeded + state files (and anything outside
+// the install) edit freely. Self-contained: hooks ship into installs and cannot import the kernel lib.
+//
+// Contract: PreToolUse event JSON on stdin → decision JSON on stdout (exit 0).
+//   allow → {}        block → { "decision": "block", "reason": "..." }
+
+const fs = require('fs');
+const path = require('path');
+
+function emit(decision) {
+  process.stdout.write(JSON.stringify(decision));
+  process.exit(0);
+}
+
+// Walk up from CLAUDE_PROJECT_DIR (or cwd) to the install root carrying wrxn.install.json.
+function findInstallRoot() {
+  let dir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  for (let i = 0; i < 8; i++) {
+    if (fs.existsSync(path.join(dir, 'wrxn.install.json'))) return dir;
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+function managedPaths(root) {
+  try {
+    const receipt = JSON.parse(fs.readFileSync(path.join(root, 'wrxn.install.json'), 'utf8'));
+    return (receipt.files || []).filter((f) => f.class === 'managed').map((f) => f.path);
+  } catch {
+    return [];
+  }
+}
+
+function main() {
+  let event;
+  try {
+    event = JSON.parse(fs.readFileSync(0, 'utf8') || '{}');
+  } catch {
+    return emit({}); // unparseable → fail open
+  }
+
+  const filePath = event.tool_input && event.tool_input.file_path;
+  if (!filePath) return emit({}); // not a file write
+
+  const root = findInstallRoot();
+  if (!root) return emit({}); // not inside a wrxn install → nothing to guard
+
+  const rel = path.relative(root, path.resolve(filePath));
+  if (rel.startsWith('..') || path.isAbsolute(rel)) return emit({}); // outside the install
+
+  if (!managedPaths(root).includes(rel)) return emit({}); // seeded/state/other → free
+
+  if (process.env.WRXN_MANAGED_CONFIRM) return emit({}); // explicit confirm → allowed
+
+  return emit({
+    decision: 'block',
+    reason: `"${rel}" is a MANAGED kernel file — kernel-owned, overwritten on \`wrxn update\`. To change it intentionally, set WRXN_MANAGED_CONFIRM. (Seeded + state files edit freely.)`,
+  });
+}
+
+main();

package/payload/.claude/hooks/enforce-managed-precommit.cjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+'use strict';
+
+// WRXN managed hook — the commit-side half of the managed-files guard.
+// PreToolUse:Bash. Blocks a `git commit` that stages any MANAGED kernel file unless
+// WRXN_MANAGED_CONFIRM is set. Seeded + state files commit freely. Self-contained.
+//
+// Contract: PreToolUse event JSON on stdin → decision JSON on stdout (exit 0).
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+function emit(decision) {
+  process.stdout.write(JSON.stringify(decision));
+  process.exit(0);
+}
+
+function findInstallRoot() {
+  let dir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  for (let i = 0; i < 8; i++) {
+    if (fs.existsSync(path.join(dir, 'wrxn.install.json'))) return dir;
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+function managedSet(root) {
+  try {
+    const receipt = JSON.parse(fs.readFileSync(path.join(root, 'wrxn.install.json'), 'utf8'));
+    return new Set((receipt.files || []).filter((f) => f.class === 'managed').map((f) => f.path));
+  } catch {
+    return new Set();
+  }
+}
+
+function main() {
+  let event;
+  try {
+    event = JSON.parse(fs.readFileSync(0, 'utf8') || '{}');
+  } catch {
+    return emit({});
+  }
+
+  const command = (event.tool_input && event.tool_input.command) || '';
+  if (!/\bgit\s+commit\b/.test(command)) return emit({}); // not a commit
+
+  const root = findInstallRoot();
+  if (!root) return emit({});
+
+  let staged = [];
+  try {
+    staged = execFileSync('git', ['diff', '--cached', '--name-only'], { cwd: root, encoding: 'utf8' })
+      .split('\n')
+      .filter(Boolean);
+  } catch {
+    return emit({}); // not a git repo / git unavailable → fail open
+  }
+
+  const managed = managedSet(root);
+  const hits = staged.filter((f) => managed.has(f));
+  if (hits.length === 0) return emit({});
+
+  if (process.env.WRXN_MANAGED_CONFIRM) return emit({});
+
+  return emit({
+    decision: 'block',
+    reason: `Commit stages MANAGED kernel file(s): ${hits.join(', ')}. Set WRXN_MANAGED_CONFIRM to confirm an intentional kernel change.`,
+  });
+}
+
+main();

package/payload/.claude/hooks/enforce-push-authority.cjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+'use strict';
+
+// WRXN managed hook — Constitution Article I (Agent Authority).
+// PreToolUse:Bash gate: a remote git op (push / PR / tag push) is allowed only when
+// the session declares the devops role via WRXN_ACTIVE_AGENT=devops. A bare push runs
+// as @unknown and is denied. Fails OPEN on any internal error (never over-blocks).
+//
+// Contract: reads a PreToolUse hook event as JSON on stdin, writes a decision to stdout.
+//   allow → {} (exit 0)
+//   deny  → { "decision": "block", "reason": "..." } (exit 0; the harness blocks the call)
+
+const REMOTE_OP = /\bgit\s+push\b|\bgh\s+pr\s+(create|merge)\b|\bgit\s+push\s+.*--tags\b/;
+
+function main() {
+  let input = '';
+  try {
+    input = require('fs').readFileSync(0, 'utf8');
+  } catch {
+    return emit({}); // no stdin → nothing to gate
+  }
+
+  let event;
+  try {
+    event = JSON.parse(input || '{}');
+  } catch {
+    return emit({}); // unparseable → fail open
+  }
+
+  const command = (event.tool_input && event.tool_input.command) || '';
+  if (!REMOTE_OP.test(command)) {
+    return emit({}); // not a remote op
+  }
+
+  if (process.env.WRXN_ACTIVE_AGENT === 'devops') {
+    return emit({}); // authorized
+  }
+
+  return emit({
+    decision: 'block',
+    reason:
+      'Remote git op is devops-exclusive (Constitution Art. I). Re-run with WRXN_ACTIVE_AGENT=devops, or delegate to the devops role.',
+  });
+}
+
+function emit(decision) {
+  process.stdout.write(JSON.stringify(decision));
+  process.exit(0);
+}
+
+main();

package/payload/.claude/hooks/enforce-review-marker.cjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+'use strict';
+
+// WRXN managed hook — the review-gate: a push referencing an unreviewed issue BLOCKS.
+// PreToolUse:Bash. On a `git push`, scans the pushed commit messages for bracketed issue ids
+// `[id]` and requires a review marker `review-<id>.md` in the markers dir for each. Missing → block.
+// Self-contained; shell-free git via execFileSync.
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+function emit(decision) {
+  process.stdout.write(JSON.stringify(decision));
+  process.exit(0);
+}
+
+function pushedMessages(cwd) {
+  // Prefer an explicit range, then the upstream range, then the last commit as a floor.
+  const ranges = [process.env.WRXN_PUSH_RANGE, '@{u}..HEAD'].filter(Boolean);
+  for (const r of ranges) {
+    try {
+      return execFileSync('git', ['log', r, '--format=%B'], { cwd, encoding: 'utf8' });
+    } catch {
+      /* try next */
+    }
+  }
+  try {
+    return execFileSync('git', ['log', '-1', '--format=%B'], { cwd, encoding: 'utf8' });
+  } catch {
+    return '';
+  }
+}
+
+function main() {
+  let event;
+  try {
+    event = JSON.parse(fs.readFileSync(0, 'utf8') || '{}');
+  } catch {
+    return emit({});
+  }
+
+  const command = (event.tool_input && event.tool_input.command) || '';
+  if (!/\bgit\s+push\b/.test(command)) return emit({});
+
+  const cwd = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const messages = pushedMessages(cwd);
+  const ids = [...new Set((messages.match(/\[([a-z0-9][a-z0-9._-]*)\]/gi) || []).map((s) => s.slice(1, -1)))];
+  if (ids.length === 0) return emit({}); // no issue referenced → nothing to gate
+
+  const markersRel = process.env.WRXN_REVIEW_MARKERS_DIR || '.claude/ai/output';
+  const dir = path.join(cwd, markersRel);
+  const missing = ids.filter((id) => !fs.existsSync(path.join(dir, `review-${id}.md`)));
+  if (missing.length === 0) return emit({});
+
+  return emit({
+    decision: 'block',
+    reason: `Push blocked: issue id(s) ${missing.join(', ')} in the pushed commits have no review marker (expected review-<id>.md in ${markersRel}). Run the review and write the marker first.`,
+  });
+}
+
+main();

package/payload/.claude/hooks/enforce-tests-on-push.cjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+'use strict';
+
+// WRXN managed hook — Quality-First (Art. III): a red suite blocks a push.
+// PreToolUse:Bash. On a `git push`, runs the configured test command in the install root and
+// blocks on a non-zero exit. WRXN_TEST_CMD (default "npm test") is OPERATOR config, not event
+// data — it is intentionally a shell command line, so a shell is appropriate here.
+
+const fs = require('fs');
+const { execSync } = require('child_process');
+
+function emit(decision) {
+  process.stdout.write(JSON.stringify(decision));
+  process.exit(0);
+}
+
+function main() {
+  let event;
+  try {
+    event = JSON.parse(fs.readFileSync(0, 'utf8') || '{}');
+  } catch {
+    return emit({});
+  }
+
+  const command = (event.tool_input && event.tool_input.command) || '';
+  if (!/\bgit\s+push\b/.test(command)) return emit({});
+
+  const testCmd = process.env.WRXN_TEST_CMD || 'npm test';
+  try {
+    execSync(testCmd, { cwd: process.env.CLAUDE_PROJECT_DIR || process.cwd(), stdio: 'ignore' });
+    return emit({});
+  } catch {
+    return emit({
+      decision: 'block',
+      reason: `Push blocked: the test suite is red (\`${testCmd}\` exited non-zero). Green it first (Constitution Art. III, Quality-First).`,
+    });
+  }
+}
+
+main();

package/payload/.claude/hooks/recall-surface.cjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+'use strict';
+
+// WRXN recall-surface hook — per-prompt recall nudge (wrxn-kernel-11).
+// UserPromptSubmit. The symmetric RECALL half of reference-detect's CAPTURE: on each prompt it
+// matches the prompt's SALIENT terms against the wiki knowledge tiers (concepts/decisions/gotchas)
+// and, ONLY when a page matches, injects a <recall-surface> nudge — "you already have a page on X,
+// recall it before re-deriving / re-asking the operator". Gated → silent on non-matching prompts.
+//
+// Self-contained: ships into installs, MUST NOT import the kernel lib (node stdlib only). The kernel
+// wiki engine is substring (not BM25) — recall here is a deliberately simple distinct-salient-term
+// count, ranked, top-N. Fail-open: any fault emits {} — the hook NEVER blocks a prompt.
+//
+// Contract: UserPromptSubmit event JSON on stdin → envelope JSON on stdout (exit 0).
+
+const fs = require('fs');
+const path = require('path');
+
+const TIERS = ['concepts', 'decisions', 'gotchas']; // knowledge tiers; sessions (episodic) excluded
+const TOP_N = 2;
+const MIN_PROMPT_LEN = 8; // skip trivial prompts ("ok", "yes")
+// A page must share >=2 DISTINCT salient terms with the prompt to surface — the substring engine has
+// no BM25 score, so a single shared common word is too weak a signal (anti-noise). Tradeoff: a genuine
+// single-strong-term recall is silenced (fail-silent — a missed nudge is safer than a false one).
+const MIN_DISTINCT = 2;
+const MAX_BLOCK_CHARS = 600;
+
+// Drop stopwords + short tokens so common words don't match common page words (anti-noise).
+const STOPWORDS = new Set(['about', 'after', 'again', 'against', 'because', 'before', 'being', 'between',
+  'could', 'does', 'doing', 'down', 'during', 'each', 'from', 'further', 'have', 'having', 'here', 'how',
+  'into', 'just', 'like', 'more', 'most', 'only', 'other', 'over', 'same', 'should', 'some', 'such',
+  'than', 'that', 'their', 'them', 'then', 'there', 'these', 'they', 'this', 'those', 'through', 'under',
+  'until', 'very', 'want', 'what', 'when', 'where', 'which', 'while', 'with', 'would', 'your', 'today',
+  'tell', 'show', 'give', 'make', 'need', 'know', 'help', 'please', 'thing', 'stuff', 'really', 'going']);
+
+function emit(envelope) {
+  process.stdout.write(JSON.stringify(envelope));
+  process.exit(0);
+}
+
+function findInstallRoot(startDir) {
+  let dir = startDir || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  for (let i = 0; i < 12; i++) {
+    if (fs.existsSync(path.join(dir, 'wrxn.install.json'))) return dir;
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+// De-duped salient content tokens (lowercased, >=4 chars, non-stopword).
+function salientTerms(prompt) {
+  const seen = new Set();
+  for (const tok of (String(prompt || '').toLowerCase().match(/[a-z][a-z0-9]{3,}/g) || [])) {
+    if (!STOPWORDS.has(tok)) seen.add(tok);
+  }
+  return [...seen];
+}
+
+// Score each wiki page by the count of DISTINCT salient terms it contains; keep pages with >=1.
+function recall(root, terms) {
+  const hits = [];
+  for (const tier of TIERS) {
+    const dir = path.join(root, '.wrxn', 'wiki', tier);
+    let names;
+    try {
+      names = fs.readdirSync(dir).filter((n) => n.endsWith('.md'));
+    } catch {
+      continue; // tier absent → skip
+    }
+    for (const name of names) {
+      let text;
+      try {
+        text = fs.readFileSync(path.join(dir, name), 'utf8').toLowerCase();
+      } catch {
+        continue;
+      }
+      const matched = terms.filter((t) => text.includes(t)).length;
+      if (matched >= MIN_DISTINCT) hits.push({ slug: name.replace(/\.md$/, ''), tier, score: matched });
+    }
+  }
+  // Highest distinct-term count first; ties broken by slug for determinism.
+  hits.sort((a, b) => b.score - a.score || a.slug.localeCompare(b.slug));
+  return hits.slice(0, TOP_N);
+}
+
+function block(hits) {
+  const lines = [
+    '<recall-surface>',
+    'You already have captured page(s) on this topic — READ before answering (do not re-derive, do',
+    'not ask the operator to re-explain). Recall with: node .wrxn/wiki.cjs recall "<slug>"',
+    ...hits.map((h) => `- ${h.slug} (${h.tier})`),
+    '</recall-surface>',
+  ].join('\n');
+  return lines.length <= MAX_BLOCK_CHARS ? lines : `${lines.slice(0, MAX_BLOCK_CHARS - 18)}\n</recall-surface>`;
+}
+
+function main() {
+  let event = {};
+  try {
+    const stdin = fs.readFileSync(0, 'utf8');
+    if (stdin.trim()) event = JSON.parse(stdin);
+  } catch {
+    emit({});
+  }
+
+  const root = findInstallRoot();
+  if (!root) emit({});
+
+  const prompt = typeof event.prompt === 'string' ? event.prompt : '';
+  if (prompt.trim().length < MIN_PROMPT_LEN) emit({});
+
+  const terms = salientTerms(prompt);
+  if (!terms.length) emit({});
+
+  const hits = recall(root, terms);
+  if (!hits.length) emit({}); // no captured page matched → silent (the gate)
+
+  emit({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: block(hits) } });
+}
+
+try {
+  main();
+} catch {
+  emit({});
+}

package/payload/.claude/hooks/reference-detect.cjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+'use strict';
+
+// WRXN reference-detect hook — the capture-nudge (wrxn-kernel-11).
+// UserPromptSubmit. Scans the prompt for reference SIGNALS (URLs + explicit source markers) and,
+// ONLY when one is present, injects a <reference-candidate> nudge telling the agent to OFFER to
+// capture the reference into the wiki WITH provenance. PROPOSE-then-CONFIRM — it never ingests
+// anything itself (the operator's chosen mode). Gated → silent on the vast majority of prompts.
+//
+// Self-contained: ships into installs, MUST NOT import the kernel lib (node stdlib only).
+// Fail-open: any fault emits {} — the hook NEVER blocks a prompt.
+//
+// Contract: UserPromptSubmit event JSON on stdin → envelope JSON on stdout (exit 0).
+
+const fs = require('fs');
+const path = require('path');
+
+const URL_RE = /\bhttps?:\/\/[^\s<>()[\]]+/gi;
+// Single-word markers are colon-anchored so "open source" / "for reference" do NOT trigger.
+const MARKER_RE = /(?:\b(?:source|reference|cite)\s*:|\b(?:per the|according to|this is from|based on)\b)/i;
+const MAX_URLS = 5;
+const MAX_BLOCK_CHARS = 500;
+
+function emit(envelope) {
+  process.stdout.write(JSON.stringify(envelope));
+  process.exit(0);
+}
+
+function findInstallRoot(startDir) {
+  let dir = startDir || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  for (let i = 0; i < 12; i++) {
+    if (fs.existsSync(path.join(dir, 'wrxn.install.json'))) return dir;
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+function detect(prompt) {
+  const text = String(prompt || '');
+  const urls = (text.match(URL_RE) || []).map((u) => u.replace(/[.,;:!?"']+$/, ''));
+  return { urls: [...new Set(urls)].slice(0, MAX_URLS), hasMarker: MARKER_RE.test(text) };
+}
+
+function nudge(sig) {
+  const parts = [];
+  if (sig.urls.length) parts.push(`URL(s): ${sig.urls.join(', ')}`);
+  if (sig.hasMarker) parts.push('an explicit source/reference marker');
+  const block = [
+    '<reference-candidate>',
+    `Detected ${parts.join(' + ')} in this prompt.`,
+    'If the operator means these as references to KEEP, OFFER to capture them into the wiki WITH',
+    'provenance (propose-then-confirm — NEVER auto-ingest). On confirmation:',
+    '  node .wrxn/wiki.cjs write-page concepts <slug> --description "<what>" --body "source: <url-or-origin>"',
+    '</reference-candidate>',
+  ].join('\n');
+  return block.length <= MAX_BLOCK_CHARS ? block : `${block.slice(0, MAX_BLOCK_CHARS - 24)}\n…\n</reference-candidate>`;
+}
+
+function main() {
+  let event = {};
+  try {
+    const stdin = fs.readFileSync(0, 'utf8');
+    if (stdin.trim()) event = JSON.parse(stdin);
+  } catch {
+    emit({});
+  }
+
+  if (!findInstallRoot()) emit({}); // install-scoped — silent outside an install
+
+  const prompt = typeof event.prompt === 'string' ? event.prompt : '';
+  const sig = detect(prompt);
+  if (!sig.urls.length && !sig.hasMarker) emit({}); // no signal → silent (the gate)
+
+  emit({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: nudge(sig) } });
+}
+
+try {
+  main();
+} catch {
+  emit({});
+}

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

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+'use strict';
+
+// WRXN session-end hook — the episodic writer (wrxn-kernel-10).
+// SessionEnd. Writes a dated session page into the install's own wiki sessions tier from the
+// captured turn trail, then clears the trail. CONTINUITY DOCTRINE: this writer touches ONLY
+// dated session pages — it NEVER writes the continuity baton (.wrxn/continuity/latest.md).
+// That slot has a single writer (the handoff skill); keeping the paths disjoint is the
+// structural fix for the clobber observed live 2026-06-12.
+//
+// Self-contained: ships into installs, MUST NOT import the kernel lib (node stdlib only).
+// Fail-open + side-effect-only: emits nothing useful, never blocks; any fault exits 0 silently.
+//
+// Contract: SessionEnd event JSON on stdin → exit 0. Side effect: a sessions/<date>-<sid>.md page.
+
+const fs = require('fs');
+const path = require('path');
+
+function done() {
+  process.exit(0);
+}
+
+function findInstallRoot(startDir) {
+  let dir = startDir || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  for (let i = 0; i < 12; i++) {
+    if (fs.existsSync(path.join(dir, 'wrxn.install.json'))) return dir;
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+function nowISO() {
+  return process.env.WRXN_NOW || new Date().toISOString();
+}
+
+// Sanitize a session id into a kebab slug fragment (the page + trail FILE name).
+function safeId(sid) {
+  return String(sid || 'session')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48) || 'session';
+}
+
+// Collapse any whitespace run (incl. newlines/tabs) to a single space — keeps a value safe to
+// embed on a single frontmatter line (the wiki adapter + synapse engine PARSE these pages, so
+// a stray newline would corrupt the frontmatter and break wiki query).
+function oneLine(s) {
+  return String(s == null ? '' : s).replace(/\s+/g, ' ').trim().slice(0, 120);
+}
+
+// Read + consume the captured turn trail for this session (one `<iso>\t<line>` per turn).
+function readTrail(root, sid) {
+  const trail = path.join(root, '.wrxn', 'history', `${safeId(sid)}.trail`);
+  let raw;
+  try {
+    raw = fs.readFileSync(trail, 'utf8');
+  } catch {
+    return { turns: [], trail };
+  }
+  const turns = raw.split('\n').map((l) => l.trim()).filter(Boolean);
+  return { turns, trail };
+}
+
+function main() {
+  let event = {};
+  try {
+    const stdin = fs.readFileSync(0, 'utf8');
+    if (stdin.trim()) event = JSON.parse(stdin);
+  } catch {
+    /* no/garbled stdin → write a minimal page anyway */
+  }
+
+  const root = findInstallRoot();
+  if (!root) done();
+
+  const sid = oneLine(event.session_id || 'session');
+  const reason = oneLine(event.reason || 'unknown');
+  const date = nowISO().slice(0, 10); // YYYY-MM-DD
+  const slug = `${date}-${safeId(event.session_id)}`;
+
+  const { turns, trail } = readTrail(root, event.session_id);
+  const trailLines = turns.length
+    ? turns.map((t, i) => {
+        const tab = t.indexOf('\t');
+        const line = tab > -1 ? t.slice(tab + 1) : t;
+        return `${i + 1}. ${line}`;
+      })
+    : ['_(no turns captured)_'];
+
+  const page = [
+    '---',
+    `name: ${slug}`,
+    `description: Session ${sid} — ${turns.length} turn(s), ended ${reason}`,
+    'tier: sessions',
+    'source: session-end-hook',
+    '---',
+    '',
+    `# Session ${date} (${sid})`,
+    '',
+    `- Ended: ${reason}`,
+    `- Turns: ${turns.length}`,
+    '',
+    '## Turn trail',
+    ...trailLines,
+    '',
+  ].join('\n');
+
+  const dir = path.join(root, '.wrxn', 'wiki', 'sessions');
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, `${slug}.md`), page);
+    // Consume the trail so the next session starts clean.
+    try {
+      fs.rmSync(trail, { force: true });
+    } catch {
+      /* trail cleanup is best-effort */
+    }
+  } catch {
+    /* page write failed → fail-open, never block session close */
+  }
+
+  done();
+}
+
+try {
+  main();
+} catch {
+  done();
+}