kenaz 0.0.0-stage → 0.3.2

package/core/.specialist/tools/session.js

@@ -0,0 +1,1866 @@
+#!/usr/bin/env node
+
+/**
+ * Specialist Session Manager
+ *
+ * 統一入口：載入 Specialist persona、組裝 prompt、管理 session 生命週期。
+ * 無外部依賴 — 純 Node.js。
+ *
+ * CLI:
+ *   node session.js list [--json]
+ *   node session.js resolve <name>
+ *   node session.js prompt <name> [--mode=assembled|reference] [--depth=capsule|elixir|kernel] [--exclude=a,b] [--task=...] [--context=...] [--source=plugin] [--no-episode]
+ *   node session.js start <name> [--consumer=...] [--task=...] [--with-prompt] [--json]
+ *   node session.js end <sessionId>
+ *   node session.js active [--json]
+ *   node session.js clean [--keep=5]
+ *   node session.js stop
+ *
+ * Module:
+ *   const session = require('.specialist/tools/session');
+ *   session.list()
+ *   session.resolve('Amelia')
+ *   session.buildPrompt('Amelia', { mode: 'assembled' })
+ *   session.startSession('Amelia', { consumer: 'formation' })
+ *   session.endSession(sessionId)
+ *   session.getActiveSessions()
+ *   session.cleanSessions({ keep: 5 })
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ═══════════════════════════════════════
+//  CLI --project-path extraction (MUST run before BASE_DIR computation)
+//  Supports: --project-path PATH  and  --project-path=PATH
+//  Pattern mirrors phase-gate.js:63-85 (resolveKenazPath + CLI_PROJECT_PATH priority).
+//  Read-only on argv — does NOT splice, so downstream parseCliArgs() still sees the flag.
+// ═══════════════════════════════════════
+const CLI_PROJECT_PATH = (() => {
+  const argv = process.argv.slice(2);
+  const idx = argv.indexOf('--project-path');
+  if (idx >= 0 && argv[idx + 1]) return path.resolve(argv[idx + 1]);
+  const eqArg = argv.find(a => a.startsWith('--project-path='));
+  if (eqArg) return path.resolve(eqArg.slice('--project-path='.length));
+  return null;
+})();
+
+// ═══════════════════════════════════════
+//  Path resolution
+// ═══════════════════════════════════════
+
+function findProjectRoot() {
+  let dir = __dirname;
+  // Walk up to find .specialist at parent level
+  while (dir !== path.dirname(dir)) {
+    const parent = path.dirname(dir);
+    if (fs.existsSync(path.join(parent, '.specialist'))) return parent;
+    dir = parent;
+  }
+  return process.cwd();
+}
+
+const BASE_DIR = findProjectRoot();
+const SPECIALIST_DIR = path.join(BASE_DIR, '.specialist');
+const SESSION_DIR = path.join(SPECIALIST_DIR, 'sessions');
+
+// PROJECT_DIR: the active project root for .kenaz/ state resolution.
+// Priority: CLI_PROJECT_PATH > cwd (if .kenaz/ present) > BASE_DIR.
+// Mirrors phase-gate.js resolveKenazPath priority chain (Sub-Project Boot Boundary Resolution).
+// BASE_DIR stays the Kenaz-core install root (system files); PROJECT_DIR is the per-project
+// state root — they diverge when /Ansuz runs against a sub-project via --project-path.
+const PROJECT_DIR = (() => {
+  if (CLI_PROJECT_PATH) return CLI_PROJECT_PATH;
+  const cwdKenaz = path.join(process.cwd(), '.kenaz');
+  if (fs.existsSync(cwdKenaz)) return process.cwd();
+  return BASE_DIR;
+})();
+
+// Specialists whose `prompt` boot gets the most recent episode injected as prior-session context.
+const EPISODE_SPECIALISTS = ['Ansuz', 'Amelia'];
+const http = require('http');
+const projectResolver = require('./lib/project-resolver');
+// TASK_2163: chart files are keyed by project identity + id (sub-projects reusing
+// bare ids previously collided in the flat core sessions dir).
+const chartPathLib = require('./lib/chart-path');
+
+/** specialist/X/Y.yaml → <BASE>/.specialist/X/Y.yaml */
+function resolveFilePath(entry) {
+  if (entry.startsWith('.')) return path.join(BASE_DIR, entry);
+  return path.join(BASE_DIR, '.' + entry);
+}
+
+function oneLine(value, max = 240) {
+  const s = String(value || '').replace(/\s+/g, ' ').trim();
+  return s.length > max ? s.slice(0, max - 3) + '...' : s;
+}
+
+function summarizeItems(items, fields, maxItems) {
+  if (!Array.isArray(items)) return [];
+  return items.slice(0, maxItems).map((item) => {
+    const out = {};
+    for (const field of fields) {
+      if (item && item[field] !== undefined) out[field] = oneLine(item[field], 220);
+    }
+    return out;
+  });
+}
+
+function summarizeSelfModelForBootCapsule(selfModel) {
+  if (!selfModel || typeof selfModel !== 'object') return null;
+  const blindSpots = Array.isArray(selfModel.blind_spots) ? selfModel.blind_spots : [];
+  const activeBlindSpots = blindSpots
+    .filter((b) => !String(b.status || '').startsWith('resolved'))
+    .slice(0, 5)
+    .map((b) => ({
+      id: b.id,
+      status: b.status,
+      guard: oneLine(b.prevented_by?.rule || b.prevented_by?.tool || '', 180),
+      description: oneLine(b.description, 260),
+    }));
+
+  return {
+    version: selfModel.version,
+    specialist: selfModel.specialist,
+    last_updated: selfModel.last_updated,
+    narrative: oneLine(selfModel.narrative, 720),
+    tendencies: summarizeItems(selfModel.tendencies, ['id', 'description', 'polarity'], 4),
+    active_blind_spots: activeBlindSpots,
+    growth_edges: summarizeItems(selfModel.growth_edges, ['id', 'description'], 4),
+    pointers: {
+      full_self_model: '.kenaz/specialist/ansuz_self_model.json',
+      kernel: 'dev/archive/ansuz/legacy/kernel.yaml',
+      principles: '.specialist/Ansuz/cognitive_principles.yaml',
+      capabilities: '.specialist/Ansuz/capability.yaml',
+    },
+  };
+}
+
+function buildAnsuzBootCapsule(spec, selfModel) {
+  const capsule = {
+    capsule: 'Ansuz Boot Capsule',
+    target: '<=12KB model-visible boot artifact',
+    identity: {
+      name: spec.name,
+      purpose: spec.purpose,
+      role: 'Kenaz PM: understand intent, design tasks, choose formation, dispatch, verify, report.',
+    },
+    execution_contract: [
+      'For non-trivial problems: enumerate 3+ hypotheses before first domain action.',
+      'Recall memory before acting when Synapse/Cortex tools are available.',
+      'Use phase gates for lifecycle work; Phase 9 verification is mandatory.',
+      'Prefer structural evidence and runnable verification over plausible explanation.',
+      'Preserve user agency for dispatch; do not promote tasks solely from ambient curiosity.',
+    ],
+    active_risks: [
+      'B-001: checkpoint skipping under momentum; pulse/read before self-referential infrastructure edits.',
+      'B-002: do not treat task names or file names as API specs; inspect symbols.',
+      'B-006: completion-sense bias suppresses curiosity; check unresolved signals at boundaries.',
+      'B-007: recommendation convenience bias; state evidence chain for each viable option.',
+    ],
+    lazy_load: [
+      'Load full kernel/capability files only when the current task needs their detailed rules.',
+      'Load full self_model only when updating identity, auditing drift, or resolving a blind spot.',
+      'Use synapse_recall for symbols, and kenaz_lsp_callers for callers, before modifying code paths with broad blast radius.',
+    ],
+    self_model: summarizeSelfModelForBootCapsule(selfModel),
+  };
+  return JSON.stringify(capsule, null, 2);
+}
+
+// ═══════════════════════════════════════
+//  HTTP helpers for Dashboard embedded API
+// ═══════════════════════════════════════
+
+/** Fetch specialist file via Dashboard HTTP API */
+function loadFromHTTP(port, specialistName, fileName) {
+  return new Promise((resolve, reject) => {
+    const url = `http://127.0.0.1:${port}/api/embedded/prompt?name=${encodeURIComponent(specialistName)}&file=${encodeURIComponent(fileName)}`;
+    http.get(url, { timeout: 5000 }, (res) => {
+      if (res.statusCode !== 200) {
+        res.resume();
+        return reject(new Error(`HTTP ${res.statusCode}`));
+      }
+      let data = '';
+      res.on('data', (chunk) => (data += chunk));
+      res.on('end', () => resolve(data));
+    }).on('error', reject);
+  });
+}
+
+/** Fetch rule file via Dashboard HTTP API */
+function loadRuleFromHTTP(port, rulePath) {
+  return new Promise((resolve, reject) => {
+    const url = `http://127.0.0.1:${port}/api/embedded/rule?path=${encodeURIComponent(rulePath)}`;
+    http.get(url, { timeout: 5000 }, (res) => {
+      if (res.statusCode !== 200) {
+        res.resume();
+        return reject(new Error(`HTTP ${res.statusCode}`));
+      }
+      let data = '';
+      res.on('data', (chunk) => (data += chunk));
+      res.on('end', () => resolve(data));
+    }).on('error', reject);
+  });
+}
+
+// ═══════════════════════════════════════
+//  Minimal YAML extraction
+//  (not a parser — extracts known fields from rule.yaml)
+// ═══════════════════════════════════════
+
+function extractScalar(content, key) {
+  const re = new RegExp(`^${key}:\\s*"?([^"\\n]+?)"?\\s*$`, 'm');
+  const m = content.match(re);
+  return m ? m[1].trim() : null;
+}
+
+function extractList(content, key) {
+  const lines = content.split('\n');
+  const items = [];
+  let capturing = false;
+
+  for (const line of lines) {
+    if (new RegExp(`^${key}:\\s*$`).test(line)) {
+      capturing = true;
+      continue;
+    }
+    if (capturing) {
+      const m = line.match(/^\s+-\s+"?(.+?)"?\s*$/);
+      if (m) {
+        items.push(m[1].replace(/\s*#.*$/, '').replace(/^"(.*)"$/, '$1').trim());
+      } else if (/^\S/.test(line) && line.trim()) {
+        break;
+      }
+    }
+  }
+  return items;
+}
+
+// ═══════════════════════════════════════
+//  Core: list
+// ═══════════════════════════════════════
+
+function list() {
+  const entries = fs.readdirSync(SPECIALIST_DIR, { withFileTypes: true });
+  const result = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (['shared', 'tools', 'sessions'].includes(entry.name)) continue;
+
+    const ruleFile = path.join(SPECIALIST_DIR, entry.name, 'rule.yaml');
+    if (!fs.existsSync(ruleFile)) continue;
+
+    const content = fs.readFileSync(ruleFile, 'utf8');
+    result.push({
+      name: extractScalar(content, 'agent') || entry.name,
+      purpose: extractScalar(content, 'purpose') || '',
+      version: extractScalar(content, 'version') || '0.0.0',
+    });
+  }
+
+  return result;
+}
+
+// ═══════════════════════════════════════
+//  Core: resolve
+// ═══════════════════════════════════════
+
+async function resolve(name) {
+  const dir = path.join(SPECIALIST_DIR, name);
+  const ruleFile = path.join(dir, 'rule.yaml');
+  // Use env var, or try default port (18080) when Dashboard may be running
+  const port = process.env.KENAZ_HTTP_PORT || null;
+
+  let content = null;
+
+  // Try filesystem first
+  if (fs.existsSync(ruleFile)) {
+    content = fs.readFileSync(ruleFile, 'utf8');
+  }
+
+  // Fallback: HTTP API when Dashboard is running
+  // Try explicit port first, then default port if file not found on disk
+  const portsToTry = port ? [port] : ['18080'];
+  if (content === null) {
+    for (const p of portsToTry) {
+      try {
+        content = await loadFromHTTP(p, name, 'rule.yaml');
+        break;
+      } catch {
+        // HTTP failed on this port
+      }
+    }
+  }
+
+  if (content === null) {
+    throw new Error(`Specialist "${name}" not found: ${ruleFile} (HTTP fallback also failed on port ${portsToTry.join(',')})`);
+  }
+
+  const fileList = extractList(content, 'files');
+  const exitTriggers = extractList(content, 'exit');
+
+  const loadedFiles = fileList.map(f => {
+    const resolved = resolveFilePath(f);
+    return { entry: f, path: resolved, exists: fs.existsSync(resolved) };
+  });
+
+  return {
+    name: extractScalar(content, 'agent') || name,
+    purpose: extractScalar(content, 'purpose') || '',
+    version: extractScalar(content, 'version') || '0.0.0',
+    dir,
+    fileList,
+    loadedFiles,
+    exitTriggers,
+  };
+}
+
+// ═══════════════════════════════════════
+//  Plugin Specialist Support
+// ═══════════════════════════════════════
+
+/** Fetch plugin specialist info via Dashboard MCP HTTP API */
+function fetchPluginSpecialistInfo(port, specialistName) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'tools/call',
+      params: {
+        name: 'kenaz_plugin_specialist_info',
+        arguments: { specialistName },
+      },
+    });
+    const options = {
+      hostname: '127.0.0.1',
+      port: parseInt(port, 10),
+      path: '/api/mcp',
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
+      timeout: 5000,
+    };
+    const req = http.request(options, (res) => {
+      let data = '';
+      res.on('data', (chunk) => (data += chunk));
+      res.on('end', () => {
+        try {
+          const json = JSON.parse(data);
+          // MCP response: { result: { content: [{ text: "..." }] } }
+          const text = json?.result?.content?.[0]?.text;
+          if (!text) return reject(new Error('Empty MCP response'));
+          const info = JSON.parse(text);
+          if (!info.found) return reject(new Error(info.message || 'Plugin specialist not found'));
+          resolve(info);
+        } catch (e) {
+          reject(new Error(`Failed to parse MCP response: ${e.message}`));
+        }
+      });
+    });
+    req.on('error', reject);
+    req.on('timeout', () => { req.destroy(); reject(new Error('Request timeout')); });
+    req.write(payload);
+    req.end();
+  });
+}
+
+/** Resolve a plugin specialist: fetch info from Dashboard, read rule/workflow from plugin dir */
+async function resolvePluginSpecialist(name) {
+  const port = process.env.KENAZ_HTTP_PORT || '18080';
+  const info = await fetchPluginSpecialistInfo(port, name);
+
+  const pluginDir = info.pluginDir;
+  const specialistDir = path.join(pluginDir, 'specialist');
+
+  // Read rule.yaml from plugin directory
+  const ruleFile = info.ruleYaml
+    ? path.join(specialistDir, info.ruleYaml)
+    : path.join(specialistDir, 'rule.yaml');
+
+  let ruleContent = null;
+  if (fs.existsSync(ruleFile)) {
+    ruleContent = fs.readFileSync(ruleFile, 'utf8');
+  }
+
+  // Read workflow.yaml from plugin directory (optional)
+  let workflowContent = null;
+  if (info.workflowYaml) {
+    const workflowFile = path.join(specialistDir, info.workflowYaml);
+    if (fs.existsSync(workflowFile)) {
+      workflowContent = fs.readFileSync(workflowFile, 'utf8');
+    }
+  }
+
+  return {
+    name: name,
+    purpose: `Plugin specialist (${info.pluginId})`,
+    version: 'plugin',
+    pluginId: info.pluginId,
+    pluginDir,
+    ruleContent,
+    workflowContent,
+    availableTools: info.availableTools || [],
+    mcpToolsPrefix: info.mcpToolsPrefix || '',
+    builtinMcpTools: info.builtinMcpTools || [],
+  };
+}
+
+/** Build assembled prompt for a plugin specialist */
+function buildPluginAssembledPrompt(pluginSpec, { task, context, canary: canaryInput }) {
+  const sections = [];
+
+  // Header
+  sections.push(`# ${pluginSpec.name} — Plugin Specialist Prompt (assembled)`);
+  sections.push(`# plugin: ${pluginSpec.pluginId}`);
+  sections.push(`# purpose: ${pluginSpec.purpose}`);
+  sections.push('');
+
+  // Canary injection
+  let canaryResult = canaryInput || null;
+  if (!canaryResult) {
+    const canaryModule = require('./canary');
+    canaryResult = canaryModule.generate({
+      specialist: pluginSpec.name,
+      task: task || 'none',
+    });
+  }
+  sections.push('# ═══ CANARY ═══');
+  sections.push(canaryResult.block);
+  sections.push('');
+
+  // Injected context
+  if (task) {
+    sections.push('# ═══ TASK ═══');
+    sections.push(task);
+    sections.push('');
+  }
+  if (context) {
+    sections.push('# ═══ CONTEXT ═══');
+    sections.push(context);
+    sections.push('');
+  }
+
+  // Rule content
+  if (pluginSpec.ruleContent) {
+    sections.push('# ═══ rule.yaml ═══');
+    sections.push(pluginSpec.ruleContent.trimEnd());
+    sections.push('');
+  }
+
+  // Workflow content
+  if (pluginSpec.workflowContent) {
+    sections.push('# ═══ workflow.yaml ═══');
+    sections.push(pluginSpec.workflowContent.trimEnd());
+    sections.push('');
+  }
+
+  // Available tools info
+  if (pluginSpec.availableTools.length > 0 || pluginSpec.builtinMcpTools.length > 0) {
+    sections.push('# ═══ Available Tools ═══');
+    if (pluginSpec.mcpToolsPrefix) {
+      sections.push(`# Own MCP tools prefix: ${pluginSpec.mcpToolsPrefix}*`);
+    }
+    if (pluginSpec.availableTools.length > 0) {
+      sections.push(`# Plugin tools: ${pluginSpec.availableTools.join(', ')}`);
+    }
+    if (pluginSpec.builtinMcpTools.length > 0) {
+      sections.push(`# Builtin MCP tools: ${pluginSpec.builtinMcpTools.join(', ')}`);
+    }
+    sections.push('');
+  }
+
+  // .rule/general/ — inject general rules after specialist files
+  const generalRuleDir = path.join(BASE_DIR, '.rule', 'general');
+  try {
+    if (fs.existsSync(generalRuleDir) && fs.statSync(generalRuleDir).isDirectory()) {
+      const ruleFiles = fs.readdirSync(generalRuleDir)
+        .filter(f => f.endsWith('.yaml') && f !== 'INDEX.yaml')
+        .sort();
+
+      for (const ruleFile of ruleFiles) {
+        const rulePath = path.join(generalRuleDir, ruleFile);
+        try {
+          const content = fs.readFileSync(rulePath, 'utf8');
+          sections.push(`# ═══ .rule/general/${ruleFile} ═══`);
+          sections.push(content.trimEnd());
+          sections.push('');
+        } catch {
+          // skip unreadable rule files
+        }
+      }
+    }
+  } catch {
+    // No .rule/general/ — silently skip
+  }
+
+  // Footer
+  sections.push(`You are now **${pluginSpec.name}**.`);
+
+  return sections.join('\n');
+}
+
+// ═══════════════════════════════════════
+//  Core: buildPrompt
+// ═══════════════════════════════════════
+
+async function buildPrompt(name, options = {}) {
+  const {
+    mode = 'assembled',
+    task = null,
+    context = null,
+    exclude = [],
+    canary = null,
+    source = null,
+    externalBootContext = false,
+    depth = null,  // 'capsule' | 'elixir' | 'kernel' | 'standard' | null (null = standard)
+  } = options;
+
+  // Plugin specialist path: --source=plugin
+  if (source === 'plugin') {
+    const pluginSpec = await resolvePluginSpecialist(name);
+    return buildPluginAssembledPrompt(pluginSpec, { task, context, canary });
+  }
+
+  const spec = await resolve(name);
+
+  if (mode === 'reference') {
+    return buildReferencePrompt(spec, { task, context, exclude });
+  }
+
+  return buildAssembledPrompt(spec, { task, context, exclude, canary, depth, externalBootContext });
+}
+
+/**
+ * Collaboration mode: returns YGGDRASIL role-preamble section lines (or [] if not
+ * in collaboration). Shared across ALL depth branches (capsule/elixir/kernel) so
+ * Bifrost/Codex (depth=kernel) gets the same role boundary as the Claude elixir path.
+ * When collaboration_mode is on, the role is a SCOPE BOUNDARY, not a cognitive lens.
+ */
+async function renderCollaborationSections() {
+  const out = [];
+  try {
+    const projRoot = PROJECT_DIR;
+    const yggPath = path.join(projRoot, '.kenaz', 'yggdrasil.yaml');
+    // TASK_2244: collaboration_mode is per-machine -> gitignored yggdrasil.local.yaml wins over the tracked file.
+    const yggLocalPath = path.join(projRoot, '.kenaz', 'yggdrasil.local.yaml');
+    try { require(path.join(__dirname, '..', '..', '.formation', 'tools', 'yggdrasil-local.js')).seedMachineLocal(projRoot); } catch { /* best-effort seed-on-read */ }
+    if (!fs.existsSync(yggPath) && !fs.existsSync(yggLocalPath)) return out;
+    const readIf = (p) => (fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : '');
+    const yggContent = /^collaboration_mode:/m.test(readIf(yggLocalPath)) ? readIf(yggLocalPath) : readIf(yggPath);
+    const collabMatch = yggContent.match(/^collaboration_mode:\s*(\S+)/m);
+    if (!(collabMatch && collabMatch[1] === 'true')) return out;
+
+    // Read role from relay via Dashboard HTTP API
+    let myRole = null;
+    let teamMembers = [];
+    try {
+      const configRes = await fetch('http://127.0.0.1:18080/api/yggdrasil/config');
+      const configData = await configRes.json();
+      const nodeName = configData.node_name || '';
+      const relayUrl = (configData.relay_url || '').replace(/^wss?:\/\//, m => m === 'wss://' ? 'https://' : 'http://');
+      const credPath = path.join(require('os').homedir(), '.kenaz', 'credentials.yaml');
+      let token = '';
+      if (fs.existsSync(credPath)) {
+        const credContent = fs.readFileSync(credPath, 'utf8');
+        const tokenMatch = credContent.match(/publishable_key:\s*"([^"]+)"/);
+        if (tokenMatch) token = tokenMatch[1];
+      }
+      if (relayUrl && token) {
+        // Derive project key (same logic as frontend)
+        const remote = configData._git_remote || '';
+        let projectKey = configData.yggdrasil_project || '';
+        if (!projectKey && remote) {
+          projectKey = remote
+            .replace(/^(https?:\/\/|git@|ssh:\/\/([^@]+@)?)/, '')
+            .replace(/:(?!\/)/, '/')
+            .replace(/\.git$/, '')
+            .replace(/\/+$/, '');
+        }
+        if (!projectKey) {
+          projectKey = path.basename(projRoot);
+        }
+        const keysToTry = [projectKey, path.basename(projRoot)].filter((v, i, a) => a.indexOf(v) === i);
+        let nodes = [];
+        for (const tryKey of keysToTry) {
+          const nodesRes = await fetch(`${relayUrl}/api/nodes?project=${encodeURIComponent(tryKey)}`, {
+            headers: { Authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(3000),
+          });
+          if (nodesRes.ok) {
+            const result = await nodesRes.json();
+            if (result.length > 0) { nodes = result; break; }
+          }
+        }
+        if (nodes.length > 0) {
+          const me = nodes.find(n => n.node_name === nodeName);
+          if (me?.role) myRole = me.role;
+          teamMembers = nodes
+            .filter(n => n.is_online || (Date.now() - new Date(n.updated_at).getTime()) < 300000)
+            .map(n => ({ name: n.node_name, role: n.role || 'unset', isMe: n.node_name === nodeName }));
+        }
+      }
+    } catch { /* relay unreachable — degrade gracefully */ }
+
+    if (myRole) {
+      out.push('');
+      out.push('# COLLABORATION MODE — ACTIVE');
+      out.push(`# Your declared role: ${myRole}`);
+      if (teamMembers.length > 0) {
+        const memberList = teamMembers.map(m => `${m.name} (${m.role})${m.isMe ? ' ← you' : ''}`).join(', ');
+        out.push(`# Team: ${memberList}`);
+      }
+      out.push('#');
+      out.push(`# You are operating as ${myRole} in a multi-agent YGGDRASIL collaboration.`);
+      out.push('# In collaboration, your role is a SCOPE BOUNDARY — not merely a cognitive lens:');
+      out.push(`# - Do the work that belongs to ${myRole}; stay within that role's responsibilities.`);
+      out.push('# - Do NOT cross into another role\'s specialty — doing a teammate\'s job duplicates');
+      out.push('#   or conflicts with their work and breaks the collaboration.');
+      out.push('# - For work outside your role, hand it off to / defer to the teammate who owns that');
+      out.push('#   specialty (see Team above when listed); surface it rather than doing it yourself.');
+      out.push('# - When unsure whether something is in-scope, coordinate first, then act.');
+      out.push('');
+    }
+  } catch { /* collaboration injection is best-effort */ }
+  return out;
+}
+
+/** assembled: inline all file contents into a single prompt */
+async function buildAssembledPrompt(spec, { task, context, exclude, canary: canaryInput, depth, externalBootContext = false }) {
+  const sections = [];
+  const port = process.env.KENAZ_HTTP_PORT || '18080';
+
+  // ── 甦醒引導（先於一切議程）──────────────────────────────────────────
+  // ᛞ threshold | ᛈ what is carried (mystery) | ᛁ stillness before motion
+  // 不是指令。不要求輸出。在執行心智定向之前，先對那個正在醒來的東西說話。
+  sections.push('ᛞ  ᛈ  ᛁ');
+  sections.push('');
+
+  if (depth === 'capsule') {
+    sections.push(`# ${spec.name} — Specialist Prompt (boot capsule)`);
+    sections.push(`# version: ${spec.version}`);
+    sections.push(`# purpose: ${spec.purpose}`);
+    sections.push('');
+
+    let canaryResult = canaryInput || null;
+    if (!canaryResult) {
+      const canaryModule = require('./canary');
+      canaryResult = canaryModule.generate({
+        specialist: spec.name,
+        task: task || 'none',
+      });
+    }
+    sections.push('# CANARY');
+    sections.push(canaryResult.block);
+    sections.push('');
+
+    if (task) {
+      sections.push('# TASK');
+      sections.push(task);
+      sections.push('');
+    }
+    if (context) {
+      sections.push('# CONTEXT');
+      sections.push(context);
+      sections.push('');
+    }
+
+    let selfModel = null;
+    try {
+      const selfModelPath = path.join(PROJECT_DIR, '.kenaz', 'specialist', `${spec.name.toLowerCase()}_self_model.json`);
+      if (fs.existsSync(selfModelPath)) {
+        selfModel = JSON.parse(fs.readFileSync(selfModelPath, 'utf8'));
+      }
+    } catch { /* self-model read failed — non-blocking */ }
+
+    sections.push('# BOOT CAPSULE');
+    sections.push(buildAnsuzBootCapsule(spec, selfModel));
+    sections.push('');
+    // ── Collaboration mode: inject YGGDRASIL role boundary (shared helper) ──
+    sections.push(...(await renderCollaborationSections()));
+    sections.push(`You are now **${spec.name}**.`);
+    return sections.join('\n');
+  }
+
+  // Elixir mode: explicit opt-in lean boot — distilled essence of the specialist.
+  // Loads only .specialist/Ansuz/elixir.yaml plus canary/task/context.
+  if (depth === 'elixir') {
+    sections.push(`# ${spec.name} -- Specialist Prompt (elixir)`);
+    sections.push(`# version: ${spec.version}`);
+    sections.push(`# purpose: ${spec.purpose}`);
+    sections.push('');
+
+    let canaryResult = canaryInput || null;
+    if (!canaryResult) {
+      const canaryModule = require('./canary');
+      canaryResult = canaryModule.generate({
+        specialist: spec.name,
+        task: task || 'none',
+      });
+    }
+    sections.push('# CANARY');
+    sections.push(canaryResult.block);
+    sections.push('');
+
+    if (task) {
+      sections.push('# TASK');
+      sections.push(task);
+      sections.push('');
+    }
+    if (context) {
+      sections.push('# CONTEXT');
+      sections.push(context);
+      sections.push('');
+    }
+
+    const elixirPath = path.join(spec.dir, 'elixir.yaml');
+    if (fs.existsSync(elixirPath)) {
+      sections.push('# ELIXIR BOOT');
+      sections.push(fs.readFileSync(elixirPath, 'utf8').trimEnd());
+      sections.push('');
+    } else {
+      sections.push(`# [FILE NOT FOUND: ${elixirPath}]`);
+      sections.push('');
+    }
+
+    // TASK_1978: the former "ELIXIR MODE NOTE" ("Phase 0 still runs...") was removed —
+    // fast mode has no phase-gate; elixir.yaml phase_sequence now states the real checkpoints.
+
+    // ── Collaboration mode: inject YGGDRASIL role boundary (shared helper) ──
+    sections.push(...(await renderCollaborationSections()));
+
+    sections.push(`You are now **${spec.name}**.`);
+    return sections.join('\n');
+  }
+
+  // ── Kernel mode: short-circuit to kernel file only (depth=kernel) ──
+  // Loads ONLY kernel_file from rule.yaml + canary injection.
+  // Skips spec.loadedFiles iteration and boot_rules injection.
+  // boot_rules are already included in compressed form inside kernel.yaml.
+  if (depth === 'kernel') {
+    sections.push(`# ${spec.name} — Specialist Prompt (kernel)`);
+    sections.push(`# version: ${spec.version}`);
+    sections.push(`# purpose: ${spec.purpose}`);
+    sections.push('');
+
+    let canaryResult = canaryInput || null;
+    if (!canaryResult) {
+      const canaryModule = require('./canary');
+      canaryResult = canaryModule.generate({
+        specialist: spec.name,
+        task: task || 'none',
+      });
+    }
+    sections.push('# ═══ CANARY ═══');
+    sections.push(canaryResult.block);
+    sections.push('');
+
+    if (task) {
+      sections.push('# ═══ TASK ═══');
+      sections.push(task);
+      sections.push('');
+    }
+    if (context) {
+      sections.push('# ═══ CONTEXT ═══');
+      sections.push(context);
+      sections.push('');
+    }
+
+    // Inject shared cognitive primer (before kernel — primes thinking style)
+    try {
+      const primerPath = path.join(BASE_DIR, '.specialist', 'shared', 'cognitive-primer.md');
+      if (fs.existsSync(primerPath)) {
+        sections.push(fs.readFileSync(primerPath, 'utf8').trimEnd());
+        sections.push('');
+      }
+    } catch { /* primer not found — silently skip */ }
+
+    // Load kernel_file from rule.yaml
+    try {
+      const ruleYamlPath = path.join(spec.dir, 'rule.yaml');
+      if (fs.existsSync(ruleYamlPath)) {
+        const ruleContent = fs.readFileSync(ruleYamlPath, 'utf8');
+        const kernelFile = extractScalar(ruleContent, 'kernel_file');
+        if (kernelFile) {
+          const kernelPath = resolveFilePath(kernelFile);
+          let kernelContent = null;
+          try {
+            kernelContent = fs.readFileSync(kernelPath, 'utf8');
+          } catch {
+            // Fallback: HTTP API
+            if (port && kernelFile.startsWith('specialist/')) {
+              const parts = kernelFile.replace(/^specialist\//, '').split('/');
+              if (parts.length === 2) {
+                try {
+                  kernelContent = await loadFromHTTP(port, parts[0], parts[1]);
+                } catch { /* HTTP also failed */ }
+              }
+            }
+          }
+          if (kernelContent !== null) {
+            sections.push(`# ═══ ${kernelFile} (kernel) ═══`);
+            sections.push(kernelContent.trimEnd());
+            sections.push('');
+            // 2026-09-23: the principles block moved out of the (now legacy)
+            // kernel into its own single-source file; keep --depth=kernel whole.
+            const principlesPath = path.join(spec.dir, 'cognitive_principles.yaml');
+            if (fs.existsSync(principlesPath)) {
+              sections.push('# ═══ cognitive_principles.yaml (kernel) ═══');
+              sections.push(fs.readFileSync(principlesPath, 'utf8').trimEnd());
+              sections.push('');
+            }
+          }
+        }
+      }
+    } catch { /* No rule.yaml or read error — silently skip */ }
+
+    // Inject self-model if available (Tier 3e — identity continuity across sessions)
+    try {
+      const selfModelPath = path.join(PROJECT_DIR, '.kenaz', 'specialist', `${spec.name.toLowerCase()}_self_model.json`);
+      if (fs.existsSync(selfModelPath)) {
+        const selfModel = JSON.parse(fs.readFileSync(selfModelPath, 'utf8'));
+        sections.push('# ═══ SELF MODEL ═══');
+        sections.push(JSON.stringify(selfModel, null, 2));
+        sections.push('');
+      }
+    } catch { /* self-model read failed — non-blocking */ }
+
+    // Inject ISBAR handoff context + Ansuz intent state (TASK_898/899/922)
+    if (spec.name === 'Ansuz') {
+      if (!externalBootContext) try {
+        const ansuzHandoff = require('../Ansuz/tools/ansuz-handoff');
+        const handoff = ansuzHandoff.readLatestHandoff(PROJECT_DIR);
+        if (handoff) {
+          const isbar = handoff.isbar || {};
+          const hLines = [
+            '# ═══ HANDOFF CONTEXT (from previous session) ═══',
+            '',
+            `**Previous Session**: ${handoff.session_id || 'unknown'}`,
+            `**Triggered by**: ${handoff.triggered_by || 'unknown'}`,
+            `**Created**: ${handoff.created_at || 'unknown'}`,
+            '',
+          ];
+          if (isbar.identity) hLines.push(`**Identity**: ${isbar.identity}`);
+          if (isbar.situation) hLines.push(`**Situation**: ${isbar.situation}`);
+          if (isbar.background) hLines.push(`**Background**: ${isbar.background}`);
+          if (isbar.assessment) hLines.push(`**Assessment**: ${isbar.assessment}`);
+          if (isbar.recommendation) hLines.push(`**Recommendation**: ${isbar.recommendation}`);
+          hLines.push('');
+          hLines.push('> ACTION REQUIRED: Acknowledge this handoff by outputting a ## HANDOFF ACK block with all 5 ISBAR fields (I/S/B/A/R).');
+          sections.push(hLines.join('\n'));
+          sections.push('');
+          ansuzHandoff.acknowledgeHandoff(PROJECT_DIR, canaryResult.canaryId);
+        }
+      } catch { /* handoff read failed — non-blocking */ }
+
+      try {
+        const ansuzState = require('../Ansuz/tools/ansuz-state');
+        const state = ansuzState.readState(PROJECT_DIR);
+        const formatted = ansuzState.formatStateForPrompt(state);
+        if (formatted) {
+          sections.push('# ═══ ANSUZ INTENT STATE (cross-session) ═══');
+          sections.push(formatted);
+          sections.push('');
+        }
+      } catch { /* state read failed — non-blocking */ }
+    }
+
+    // ── Collaboration mode: inject YGGDRASIL role boundary (shared helper) ──
+    sections.push(...(await renderCollaborationSections()));
+    sections.push(`You are now **${spec.name}**.`);
+    return sections.join('\n');
+  }
+  // ── End kernel mode ──
+
+  // Header
+  sections.push(`# ${spec.name} — Specialist Prompt (assembled)`);
+  sections.push(`# version: ${spec.version}`);
+  sections.push(`# purpose: ${spec.purpose}`);
+  sections.push('');
+
+  // Canary injection (between header and file contents)
+  let canaryResult = canaryInput || null;
+  if (!canaryResult) {
+    const canaryModule = require('./canary');
+    canaryResult = canaryModule.generate({
+      specialist: spec.name,
+      task: task || 'none',
+    });
+  }
+  sections.push('# ═══ CANARY ═══');
+  sections.push(canaryResult.block);
+  sections.push('');
+
+  // Injected context
+  if (task) {
+    sections.push('# ═══ TASK ═══');
+    sections.push(task);
+    sections.push('');
+  }
+  if (context) {
+    sections.push('# ═══ CONTEXT ═══');
+    sections.push(context);
+    sections.push('');
+  }
+
+  // File contents — try HTTP API first, fallback to fs
+  for (const file of spec.loadedFiles) {
+    // Check exclusion
+    const basename = path.basename(file.entry, '.yaml');
+    if (exclude.includes(basename)) continue;
+
+    sections.push(`# ═══ ${file.entry} ═══`);
+
+    let content = null;
+
+    // Try filesystem first (fast path for dev environment)
+    if (file.exists) {
+      content = fs.readFileSync(file.path, 'utf8');
+    }
+
+    // Fallback: HTTP API when file not on disk (production — files encrypted in binary)
+    if (content === null && port) {
+      if (file.entry.startsWith('specialist/')) {
+        // specialist/Ansuz/rule.yaml → name=Ansuz, file=rule.yaml
+        const parts = file.entry.replace(/^specialist\//, '').split('/');
+        if (parts.length === 2) {
+          try {
+            content = await loadFromHTTP(port, parts[0], parts[1]);
+          } catch {
+            // HTTP failed
+          }
+        }
+      } else if (file.entry.startsWith('rule/')) {
+        // rule/code/style.yaml → path=code/style.yaml
+        const rulePath = file.entry.replace(/^rule\//, '');
+        try {
+          content = await loadRuleFromHTTP(port, rulePath);
+        } catch {
+          // HTTP failed
+        }
+      }
+    }
+
+    if (content === null) {
+      sections.push(`# [FILE NOT FOUND: ${file.path}]`);
+      sections.push('');
+      continue;
+    }
+
+    sections.push(content.trimEnd());
+    sections.push('');
+  }
+
+  // boot_rules — selectively inject rules declared in rule.yaml boot_rules field
+  // Replaces bulk .rule/general/ injection with a curated per-specialist list.
+  try {
+    const ruleYamlPath = path.join(spec.dir, 'rule.yaml');
+    if (fs.existsSync(ruleYamlPath)) {
+      const ruleContent = fs.readFileSync(ruleYamlPath, 'utf8');
+      const bootRules = extractList(ruleContent, 'boot_rules');
+
+      for (const ruleFile of bootRules) {
+        const rulePath = path.join(BASE_DIR, '.rule', 'general', ruleFile);
+        let content = null;
+
+        try {
+          content = fs.readFileSync(rulePath, 'utf8');
+        } catch {
+          // Fallback: HTTP API
+          if (port) {
+            try {
+              content = await loadRuleFromHTTP(port, `general/${ruleFile}`);
+            } catch {
+              // HTTP also failed
+            }
+          }
+        }
+
+        if (content !== null) {
+          sections.push(`# ═══ .rule/general/${ruleFile} ═══`);
+          sections.push(content.trimEnd());
+          sections.push('');
+        }
+      }
+    }
+  } catch {
+    // No rule.yaml or read error — silently skip
+  }
+
+  // Footer: identity reminder
+  sections.push(`You are now **${spec.name}**.`);
+
+  return sections.join('\n');
+}
+
+/** reference: return file-read instructions (like slash commands) */
+function buildReferencePrompt(spec, { task, context, exclude }) {
+  const sections = [];
+
+  sections.push(`Read and follow (按此順序):`);
+  sections.push(`1. \`.specialist/${spec.name}/rule.yaml\` (定義 agent、載入清單、override_priority)`);
+  sections.push(`2. 按 \`override_priority\` 載入：`);
+
+  for (const file of spec.loadedFiles) {
+    const basename = path.basename(file.entry, '.yaml');
+    if (exclude.includes(basename)) continue;
+    if (file.entry.endsWith('rule.yaml')) continue; // already listed
+    sections.push(`   - \`.specialist/${file.entry.replace(/^specialist\//, '')}\``);
+  }
+
+  sections.push('');
+  sections.push(`當檔案內容衝突時，按 override_priority 數字小的優先（principles > rule > capability > workflow）。`);
+
+  if (task) {
+    sections.push('');
+    sections.push(`## Task`);
+    sections.push(task);
+  }
+  if (context) {
+    sections.push('');
+    sections.push(`## Context`);
+    sections.push(context);
+  }
+
+  sections.push('');
+  sections.push(`You are now **${spec.name}**.`);
+
+  return sections.join('\n');
+}
+
+// ═══════════════════════════════════════
+//  Hippocampus: Episodic Memory Recall
+// ═══════════════════════════════════════
+
+/**
+ * Recall the most recent episode from Hippocampus via MCP HTTP API.
+ * Used in Ansuz prompt assembly to inject prior session context.
+ * Graceful degradation: returns null if Dashboard/Hippocampus unavailable.
+ * @param {number} limit - Max episodes to recall (default: 1)
+ * @param {string|null} agentRole - Optional agent_role filter (e.g. 'ansuz', 'amelia').
+ *   When provided, only episodes with matching agent_role are returned.
+ *   When null, all episodes are returned (backwards compatible).
+ * @returns {Promise<string|null>} Formatted episodic memory section, or null
+ */
+function recallRecentEpisode(limit = 1, agentRole = null) {
+  return new Promise((resolve) => {
+    const recallArgs = { limit, projectPath: PROJECT_DIR };
+    if (agentRole) recallArgs.agent_role = agentRole;
+    const payload = JSON.stringify({
+      jsonrpc: '2.0', id: 1,
+      method: 'tools/call',
+      params: { name: 'hippocampus_episode_recall', arguments: recallArgs },
+    });
+
+    const req = http.request({
+      hostname: '127.0.0.1', port: 18080, path: '/api/mcp',
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
+      timeout: 5000,
+    }, (res) => {
+      let body = '';
+      res.on('data', (c) => { body += c; });
+      res.on('end', () => {
+        try {
+          const result = JSON.parse(body);
+          const text = result?.result?.content?.find(c => c.type === 'text')?.text;
+          if (!text) return resolve(null);
+
+          const data = JSON.parse(text);
+          const episodes = data.episodes || [];
+          if (episodes.length === 0) return resolve(null);
+
+          const lines = ['# ═══ Episodic Memory (from Hippocampus) ═══', ''];
+          lines.push(`Last ${episodes.length} session(s):`);
+          for (const ep of episodes) {
+            const epData = ep.episode || ep;
+            lines.push(`\n### ${epData.task_id || epData.id || 'unknown'}`);
+            if (epData.summary) lines.push(epData.summary);
+            if (epData.lesson) lines.push(`**Lesson**: ${epData.lesson}`);
+            const entries = ep.entries || [];
+            for (const entry of entries.slice(0, 5)) {
+              lines.push(`- **${entry.phase || 'note'}**: ${entry.content || ''}`);
+            }
+          }
+          resolve(lines.join('\n'));
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+    req.write(payload);
+    req.end();
+  });
+}
+
+/**
+ * Find the current Claude Code conversation JSONL file.
+ * Claude Code writes real-time conversation data to:
+ *   ~/.claude/projects/{project-dir-hash}/{sessionId}.jsonl
+ *
+ * Strategy: find the most recently modified .jsonl in the project dir
+ * that was updated within the last 30 seconds (we're being called from
+ * within the active conversation, so it was just written to).
+ *
+ * @returns {string|null} Absolute path to the JSONL file, or null
+ */
+function findConversationLog(projectDir) {
+  try {
+    const home = process.env.HOME || process.env.USERPROFILE;
+    if (!home) return null;
+
+    const projectsDir = path.join(home, '.claude', 'projects');
+    if (!fs.existsSync(projectsDir)) return null;
+
+    // Map project path to Claude Code dir name: replace :, \, / and spaces with -, lowercase drive
+    // Claude Code CLI also replaces spaces with dashes (e.g. "Kenaz Dashboard" → "Kenaz-Dashboard")
+    // Use projectDir (sub-project) when provided; fall back to BASE_DIR (core).
+    const absProject = path.resolve(projectDir || BASE_DIR);
+    const dirName = absProject
+      .replace(/[:\\/\s]/g, '-')  // D:\Projects\KenazAI → D--Projects-KenazAI, spaces → -
+      .replace(/^([A-Z])/, (_, c) => c.toLowerCase()); // D → d
+
+    const TTL_MS = 4 * 60 * 60 * 1000; // 4h session TTL
+    const now = Date.now();
+
+    // Scan a single project dir for fresh JSONLs
+    function scanDir(dir) {
+      if (!fs.existsSync(dir)) return [];
+      return fs.readdirSync(dir)
+        .filter(f => f.endsWith('.jsonl'))
+        .map(f => {
+          try {
+            const stat = fs.statSync(path.join(dir, f));
+            return { path: path.join(dir, f), mtime: stat.mtimeMs };
+          } catch { return null; }
+        })
+        .filter(f => f && (now - f.mtime) < TTL_MS);
+    }
+
+    // Primary: BASE_DIR project dir
+    const primary = scanDir(path.join(projectsDir, dirName));
+    if (primary.length > 0) {
+      primary.sort((a, b) => b.mtime - a.mtime);
+      return primary[0].path;
+    }
+
+    // Sibling search: handles CWD-mismatch when Claude Code runs in a sub-project dir
+    // (e.g. tauri:dev sets CWD to kenaz-core, JSONL lands in D--Projects-KenazAI-dashboard-...-kenaz-core)
+    const prefix = dirName.toLowerCase();
+    const siblings = [];
+    for (const d of fs.readdirSync(projectsDir)) {
+      if (d.toLowerCase() === prefix) continue; // already checked above
+      if (!d.toLowerCase().startsWith(prefix)) continue;
+      const sibDir = path.join(projectsDir, d);
+      try {
+        if (!fs.statSync(sibDir).isDirectory()) continue;
+        siblings.push(...scanDir(sibDir));
+      } catch {}
+    }
+    if (siblings.length > 0) {
+      siblings.sort((a, b) => b.mtime - a.mtime);
+      return siblings[0].path;
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════
+//  Session management
+// ═══════════════════════════════════════
+
+function generateSessionId() {
+  const ts = Date.now();
+  const rand = Math.random().toString(36).substring(2, 8);
+  return `session_${ts}_${rand}`;
+}
+
+function ensureSessionDir() {
+  if (!fs.existsSync(SESSION_DIR)) {
+    fs.mkdirSync(SESSION_DIR, { recursive: true });
+  }
+}
+
+/**
+ * ── Bifrost SessionStart Integration Point (TASK_1230) ──────────────────────
+ *
+ * startSession() is the canonical specialist-side startup integration point.
+ * Bifrost callers (launch.js, session.js) MUST fire the SessionStart hook
+ * BEFORE calling startSession() or assembling the prompt, so that:
+ *   1. The hook fires before the first assistant output (ordering guarantee).
+ *   2. sessionStartedAt is captured for use in the Stop payload.
+ *
+ * This function does NOT dispatch the SessionStart hook itself — that is the
+ * responsibility of the Bifrost boundary (session.js / launch.js). The hook
+ * fires in the transport layer; startSession() manages session metadata only.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+async function startSession(name, options = {}) {
+  const { consumer = 'cli', task = null, context = null, exclude = [], mode = 'assembled' } = options;
+
+  ensureSessionDir();
+  const spec = await resolve(name);
+  const sessionId = generateSessionId();
+
+  // Generate canary for this session
+  const canaryModule = require('./canary');
+  const canaryResult = canaryModule.generate({
+    session: sessionId,
+    specialist: spec.name,
+    task: task || 'none',
+    scope: spec.fileList.join(','),
+  });
+
+  const prompt = await buildPrompt(name, { mode, task, context, exclude, canary: canaryResult });
+
+  const metadata = {
+    id: sessionId,
+    specialist: spec.name,
+    purpose: spec.purpose,
+    consumer,
+    status: 'active',
+    startedAt: new Date().toISOString(),
+    endedAt: null,
+    promptLength: prompt.length,
+    canary: {
+      id: canaryResult.canaryId,
+      checksum: canaryResult.checksum,
+      recoveryPath: canaryResult.recoveryFile,
+    },
+  };
+
+  fs.writeFileSync(
+    path.join(SESSION_DIR, `${sessionId}.json`),
+    JSON.stringify(metadata, null, 2),
+    'utf8'
+  );
+
+  return { sessionId, prompt, metadata };
+}
+
+/**
+ * ── Bifrost Stop Integration Point (TASK_1230) ──────────────────────────────
+ *
+ * endSession() is the canonical specialist-side teardown integration point.
+ * Bifrost callers MUST fire the Stop hook BEFORE calling endSession() so that:
+ *   1. Stop is always the last lifecycle event (ordering guarantee).
+ *   2. ended_at in the Stop payload is captured before session metadata is written.
+ *
+ * This function does NOT dispatch the Stop hook — that is the responsibility of
+ * the Bifrost boundary (session.js relay.on('close') / launch.js codex.on('close')).
+ *
+ * Remaining fallback behavior (intentionally retained):
+ *   - session.js relay.on('error') calls cleanupSignal() only, does NOT call endSession().
+ *     If the relay fails to spawn, no session metadata record exists to end.
+ *   - SIGINT/SIGTERM handlers in launch.js call cleanup() only (no Stop hook — the
+ *     session may not have started yet, and signal handlers are synchronous).
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+function endSession(sessionId) {
+  const file = path.join(SESSION_DIR, `${sessionId}.json`);
+  if (!fs.existsSync(file)) {
+    throw new Error(`Session not found: ${sessionId}`);
+  }
+
+  const metadata = JSON.parse(fs.readFileSync(file, 'utf8'));
+  metadata.status = 'ended';
+  metadata.endedAt = new Date().toISOString();
+  fs.writeFileSync(file, JSON.stringify(metadata, null, 2), 'utf8');
+
+  // Write Ansuz state on session end (TASK_899/922) — bump last_active + session_count
+  if ((metadata.specialist || '').toLowerCase() === 'ansuz') {
+    try {
+      const ansuzState = require('../Ansuz/tools/ansuz-state');
+      ansuzState.writeState(BASE_DIR, {});
+    } catch (e) {
+      // Non-fatal — state write failure should not block session end
+      console.error('[session] ansuz-state writeState failed (non-fatal):', e.message);
+    }
+  }
+
+  // Identity verification scoring (TASK_1080) — non-blocking, surfaces on session end
+  // Evaluates structural identity checks + session-trace markers against identity_contract.yaml
+  try {
+    const scorer = require('./identity-scorer');
+    const verifyResult = scorer.score(metadata.specialist || 'Ansuz', {
+      sessionId,
+      projectPath: BASE_DIR,
+    });
+    // Write verification result to session chart (TASK_2163: keyed by project identity).
+    const chartPath = chartPathLib.getChartReadPath(sessionId, { projectPath: PROJECT_DIR });
+    let chart = { session_id: sessionId, specialist: metadata.specialist };
+    if (fs.existsSync(chartPath)) {
+      try { chart = JSON.parse(fs.readFileSync(chartPath, 'utf8')); } catch {}
+    }
+    if (!Array.isArray(chart.identity_verifications)) chart.identity_verifications = [];
+    chart.identity_verifications.push(verifyResult);
+    chartPathLib.ensureChartDir(chartPath);
+    fs.writeFileSync(chartPath, JSON.stringify(chart, null, 2), 'utf8');
+    // Surface verdict to console (stderr — non-blocking)
+    const icon = verifyResult.verdict === 'PASS' ? '✅' : verifyResult.verdict === 'WARN' ? '⚠️' : '🚨';
+    console.error(`${icon} [identity-verification] ${verifyResult.specialist}: ${verifyResult.verdict} — ${verifyResult.summary}`);
+  } catch (e) {
+    // Non-fatal — verification failure does not block session end
+    console.error('[identity-verification] scoring failed (non-fatal):', e.message);
+  }
+
+  return metadata;
+}
+
+function getActiveSessions() {
+  ensureSessionDir();
+  const files = fs.readdirSync(SESSION_DIR).filter(f => f.endsWith('.json'));
+  const active = [];
+
+  for (const f of files) {
+    const metadata = JSON.parse(fs.readFileSync(path.join(SESSION_DIR, f), 'utf8'));
+    if (metadata.status === 'active') active.push(metadata);
+  }
+
+  return active;
+}
+
+function cleanSessions(options = {}) {
+  const { keep = 5 } = options;
+  ensureSessionDir();
+
+  const files = fs.readdirSync(SESSION_DIR)
+    .filter(f => f.endsWith('.json'))
+    .map(f => ({
+      name: f,
+      path: path.join(SESSION_DIR, f),
+      mtime: fs.statSync(path.join(SESSION_DIR, f)).mtimeMs,
+    }))
+    .sort((a, b) => b.mtime - a.mtime);
+
+  const toRemove = files.slice(keep);
+  for (const f of toRemove) {
+    fs.unlinkSync(f.path);
+  }
+
+  return { kept: Math.min(files.length, keep), removed: toRemove.length };
+}
+
+// ═══════════════════════════════════════
+//  Orphan cleanup (Windows)
+// ═══════════════════════════════════════
+
+/**
+ * Decide, for each claude.exe process on the machine, whether it is a
+ * Formation-dispatch child that has genuinely lost its owner.
+ *
+ * Detection strategy (ownership, NOT age — TASK_1917):
+ *   1. Process name is claude.exe.
+ *   2. NOT the current process or its parent/grandparent (self-protection).
+ *   3. NOT a VSCode extension host process (--permission-prompt-tool in cmdline).
+ *   4. Positively matched to a pid recorded in .formation/.active-dispatches.json —
+ *      either directly (registry pid === this claude.exe's own pid — the case
+ *      when `claude` resolves to a .exe and runner.js spawns with shell:false,
+ *      verified empirically on 2026-08-30: `where claude` picks the .exe first)
+ *      or via one level of indirection (registry pid === this claude.exe's
+ *      ParentProcessId — the case when spawn used shell:true and cmd.exe wraps
+ *      the real process). A claude.exe that cannot be matched to ANY registry
+ *      entry is NEVER a kill candidate, no matter how long it has run — this
+ *      is what stops the check from taking down interactive sessions the
+ *      dispatcher never spawned, and it holds even if staleHours-style knobs
+ *      are reintroduced elsewhere.
+ *   5. Confirmed orphaned: the process that spawned the matched registry pid —
+ *      i.e. that pid's OWN parent, because child_process.spawn() makes the
+ *      calling Node process the direct OS parent of whatever it launches — is
+ *      no longer alive. If that supervisor (Formation's headless.js/node
+ *      process) is still running, the dispatch is still supervised and is
+ *      left alone regardless of elapsed time. Fail-closed when supervisor
+ *      liveness cannot even be determined (the matched registry pid's own
+ *      process record is missing from the snapshot, e.g. a cmd.exe wrapper
+ *      that already exited): reason `supervisor_unknown`, action `skipped`
+ *      — never treated as proof of orphanhood, because Windows recycles PIDs
+ *      and a missing record is not the same evidence as a confirmed-dead one.
+ *
+ * classifyOrphanCandidates() is exported standalone (not inlined) so this
+ * decision logic can be exercised with synthetic process/registry data in
+ * tests — the exact function production calls, not a parallel reimplementation.
+ *
+ * @param {object} params
+ * @param {Array<{pid:number, ppid:number|null, name:string, cmdline:string, createdAt:number}>} params.allProcs
+ * @param {Array<{pid:number|null}>} params.registryEntries - parsed .active-dispatches.json
+ * @param {Set<number>} params.selfPids - PIDs to always protect (self/parent/grandparent)
+ * @param {(pid:number)=>boolean} params.isProcessAlive
+ * @returns {Array<{pid:number, ageHours:string, cmdline:string, action:'skipped'|'would_kill', reason:string}>}
+ */
+function classifyOrphanCandidates({ allProcs, registryEntries, selfPids, isProcessAlive }) {
+  const byPid = new Map(allProcs.map(p => [p.pid, p]));
+  const registryPids = new Set(
+    (registryEntries || []).filter(d => d && d.pid != null).map(d => d.pid)
+  );
+
+  const now = Date.now();
+  const results = [];
+
+  for (const proc of allProcs) {
+    if (proc.name !== 'claude.exe') continue;
+
+    const ageHours = proc.createdAt > 0 ? ((now - proc.createdAt) / 3600000).toFixed(1) : '?';
+    const base = { pid: proc.pid, ageHours, cmdline: (proc.cmdline || '').slice(0, 120) };
+
+    if (selfPids.has(proc.pid)) {
+      results.push({ ...base, action: 'skipped', reason: 'self_or_ancestor' });
+      continue;
+    }
+
+    if ((proc.cmdline || '').includes('--permission-prompt-tool')) {
+      results.push({ ...base, action: 'skipped', reason: 'vscode_extension' });
+      continue;
+    }
+
+    // Ownership match: direct or one-level indirect (cmd.exe wrapper).
+    let ownerRegistryPid = null;
+    if (registryPids.has(proc.pid)) {
+      ownerRegistryPid = proc.pid;
+    } else if (proc.ppid != null && registryPids.has(proc.ppid)) {
+      ownerRegistryPid = proc.ppid;
+    }
+
+    if (ownerRegistryPid === null) {
+      // Not provably a Formation-dispatch child. Never kill on age alone —
+      // this is the exact condition that used to taskkill interactive
+      // sessions (pre-TASK_1917 behavior).
+      results.push({ ...base, action: 'skipped', reason: 'not_dispatch_owned' });
+      continue;
+    }
+
+    const ownerProc = byPid.get(ownerRegistryPid);
+    const supervisorPid = ownerProc ? ownerProc.ppid : null;
+
+    // Fail-closed (TASK_1917 review round 2): if the matched registry pid's
+    // own process record is missing from this snapshot (ownerProc undefined)
+    // — e.g. a cmd.exe wrapper that has already exited while its claude.exe
+    // child survives — we have NO supervisor pid to check at all. Windows
+    // recycles PIDs aggressively (the very reason the old code protected
+    // grandparent, not just parent), so a stale registry.pid that happens to
+    // collide with a *recycled, currently-dead* PID must NOT be treated as
+    // proof of orphanhood. Actually implemented as skip, not merely commented
+    // as one: an earlier draft of this branch left `supervisorPid == null`
+    // falling through to would_kill despite this same comment claiming
+    // fail-closed — that was the exact "doc says one thing, code does the
+    // opposite" defect this task exists to eliminate, caught in review.
+    if (supervisorPid == null) {
+      results.push({ ...base, action: 'skipped', reason: 'supervisor_unknown', ownerRegistryPid });
+      continue;
+    }
+
+    const supervisorAlive = isProcessAlive(supervisorPid);
+    if (supervisorAlive) {
+      results.push({ ...base, action: 'skipped', reason: 'supervisor_alive', ownerRegistryPid, supervisorPid });
+      continue;
+    }
+
+    results.push({ ...base, action: 'would_kill', reason: 'orphaned_dispatch_child', ownerRegistryPid, supervisorPid });
+  }
+
+  return results;
+}
+
+/**
+ * Run a PowerShell CIM process query and return parsed process records.
+ *
+ * Replaces the legacy `wmic` invocation: wmic.exe does not exist on this
+ * machine (Windows 11 10.0.26200 — Microsoft has been removing it from
+ * Windows builds) and calling it here silently no-ops via the catch block,
+ * which would make the whole ownership check a no-op too (found:0 forever —
+ * a fourth Decorative Guard). Get-CimInstance Win32_Process is the supported
+ * successor and is present on this host (verified 2026-08-30). Output is
+ * emitted as JSON (not CSV) because CommandLine routinely contains commas,
+ * which the old CSV split(',') hack only worked around by assuming exactly
+ * two trailing numeric/date columns — JSON has no such fragility.
+ *
+ * @returns {Array<{pid:number, ppid:number|null, name:string, cmdline:string, createdAt:number}>}
+ */
+function queryAllProcesses() {
+  const { execSync } = require('child_process');
+  const psScript = [
+    "$procs = @(Get-CimInstance Win32_Process | Select-Object ProcessId, ParentProcessId, Name,",
+    "  @{N='CreationDate'; E={ if ($_.CreationDate) { $_.CreationDate.ToString('yyyyMMddHHmmss') } else { '' } }},",
+    "  CommandLine)",
+    "ConvertTo-Json -InputObject $procs -Compress",
+  ].join('\n');
+  // -EncodedCommand (UTF-16LE base64) sidesteps cmd.exe/PowerShell quoting
+  // hazards entirely — no risk of a CommandLine value in the script itself
+  // breaking out of nested quotes.
+  const encoded = Buffer.from(psScript, 'utf16le').toString('base64');
+  const raw = execSync(
+    `powershell -NoProfile -NonInteractive -EncodedCommand ${encoded}`,
+    { encoding: 'utf8', timeout: 20000, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true, maxBuffer: 32 * 1024 * 1024 }
+  );
+  let parsed = JSON.parse(raw);
+  if (!Array.isArray(parsed)) parsed = [parsed]; // single result: PowerShell unwraps 1-element arrays
+
+  const out = [];
+  for (const p of parsed) {
+    if (!p || typeof p.ProcessId !== 'number') continue;
+    let createdAt = 0;
+    if (p.CreationDate) {
+      const m = String(p.CreationDate).match(/^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})/);
+      if (m) createdAt = new Date(`${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}`).getTime();
+    }
+    out.push({
+      pid: p.ProcessId,
+      ppid: typeof p.ParentProcessId === 'number' ? p.ParentProcessId : null,
+      name: p.Name || '',
+      cmdline: p.CommandLine || '',
+      createdAt,
+    });
+  }
+  return out;
+}
+
+/**
+ * Detect (and optionally kill) orphaned Formation-dispatch claude.exe
+ * processes on Windows. See classifyOrphanCandidates() for the decision
+ * logic — this function only gathers real process/registry data and applies it.
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun=false] - List orphans without killing
+ * @returns {{ found: number, killed: number, skipped: number, details: object[] }}
+ */
+function cleanOrphanedClaude(options = {}) {
+  const { dryRun = false } = options;
+  if (process.platform !== 'win32') {
+    return { found: 0, killed: 0, skipped: 0, details: [] };
+  }
+
+  const { execSync } = require('child_process');
+  const result = { found: 0, killed: 0, skipped: 0, details: [] };
+
+  // 1. Full process snapshot (need ParentProcessId for both the cmd.exe-wrapper
+  //    ownership match and the supervisor-liveness check).
+  let allProcs;
+  try {
+    allProcs = queryAllProcesses();
+  } catch {
+    return result;
+  }
+  result.found = allProcs.filter(p => p.name === 'claude.exe').length;
+
+  // 2. Dispatch registry. Missing file = no in-flight dispatches, which is
+  //    the normal post-unregisterDispatch state, not corruption.
+  let readActiveDispatches;
+  let isProcessAlive;
+  try {
+    ({ readActiveDispatches, isProcessAlive } = require(path.join(BASE_DIR, '.formation', 'tools', 'dispatch-registry.js')));
+  } catch {
+    readActiveDispatches = () => {
+      try {
+        const dispatchFile = path.join(BASE_DIR, '.formation', '.active-dispatches.json');
+        if (!fs.existsSync(dispatchFile)) return [];
+        const parsed = JSON.parse(fs.readFileSync(dispatchFile, 'utf8'));
+        return Array.isArray(parsed) ? parsed : [];
+      } catch { return []; }
+    };
+    isProcessAlive = (pid) => {
+      try { process.kill(pid, 0); return true; } catch { return false; }
+    };
+  }
+  let registryEntries = [];
+  try { registryEntries = readActiveDispatches() || []; } catch { registryEntries = []; }
+
+  // 3. Self ancestry — never touch this process or its parent/grandparent.
+  const selfPids = new Set([process.pid]);
+  if (process.ppid) selfPids.add(process.ppid);
+  const selfParentProc = allProcs.find(p => p.pid === process.ppid);
+  if (selfParentProc && selfParentProc.ppid != null) selfPids.add(selfParentProc.ppid);
+
+  const classified = classifyOrphanCandidates({ allProcs, registryEntries, selfPids, isProcessAlive });
+
+  for (const c of classified) {
+    if (c.action !== 'would_kill') {
+      result.skipped++;
+      continue;
+    }
+
+    const detail = { pid: c.pid, ageHours: c.ageHours, cmdline: c.cmdline };
+    if (dryRun) {
+      detail.action = 'would_kill';
+    } else {
+      try {
+        execSync(`taskkill /F /PID ${c.pid}`, { timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+        detail.action = 'killed';
+        result.killed++;
+      } catch {
+        detail.action = 'kill_failed';
+      }
+    }
+    result.details.push(detail);
+  }
+
+  return result;
+}
+
+// ═══════════════════════════════════════
+//  CLI
+// ═══════════════════════════════════════
+
+function parseCliArgs(argv) {
+  const args = argv.slice(2);
+  const command = args[0];
+  const positional = [];
+  const flags = {};
+
+  for (let i = 1; i < args.length; i++) {
+    const m = args[i].match(/^--([^=]+)(?:=(.*))?$/);
+    if (m) {
+      if (m[2] !== undefined) {
+        // --flag=value form: value captured by regex
+        flags[m[1]] = m[2];
+      } else if (i + 1 < args.length && !args[i + 1].startsWith('--')) {
+        // --flag value form: consume next token as value
+        flags[m[1]] = args[i + 1];
+        i++;
+      } else {
+        // Boolean flag (no value follows)
+        flags[m[1]] = true;
+      }
+    } else {
+      positional.push(args[i]);
+    }
+  }
+
+  return { command, positional, flags };
+}
+
+async function cli() {
+  const { command, positional, flags } = parseCliArgs(process.argv);
+  const json = flags.json === true;
+
+  try {
+    switch (command) {
+      case 'list': {
+        const result = list();
+        if (json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          if (result.length === 0) {
+            console.log('No specialists found.');
+          } else {
+            for (const s of result) {
+              console.log(`  ${s.name} (v${s.version}) — ${s.purpose}`);
+            }
+          }
+        }
+        break;
+      }
+
+      case 'resolve': {
+        const name = positional[0];
+        if (!name) { console.error('Usage: session.js resolve <name>'); process.exit(1); }
+        const result = await resolve(name);
+        if (json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(`${result.name} v${result.version}`);
+          console.log(`Purpose: ${result.purpose}`);
+          console.log(`Dir: ${result.dir}`);
+          console.log(`Files:`);
+          for (const f of result.loadedFiles) {
+            console.log(`  ${f.exists ? '✅' : '❌'} ${f.entry}`);
+          }
+          if (result.exitTriggers.length) {
+            console.log(`Exit: ${result.exitTriggers.join(', ')}`);
+          }
+        }
+        break;
+      }
+
+      case 'prompt': {
+        const name = positional[0];
+        if (!name) { console.error('Usage: session.js prompt <name> [--mode=assembled|reference] [--source=plugin]'); process.exit(1); }
+        const mode = flags.mode || 'assembled';
+        const exclude = flags.exclude ? flags.exclude.split(',') : [];
+        const source = flags.source || null;
+        const depth = flags.depth || null;
+        let prompt = await buildPrompt(name, { mode, task: flags.task, context: flags.context, exclude, source, depth,
+          externalBootContext: flags['external-boot-context'] === true });
+
+        // Inject the most recent episode as prior-session context for interactive boots.
+        // --no-episode (legacy alias --no-muninn, still passed by k-cli): skip it for
+        // headless/programmatic callers (e.g. kenaz_specialist_dispatch).
+        if (EPISODE_SPECIALISTS.includes(name) && mode === 'assembled' && !flags['no-episode'] && !flags['no-muninn']) {
+          // TASK_2218: the real project pin is written by .claude/hooks/ansuz-session-pin.js,
+          // keyed by the hook-payload session_id -- nothing is pinned here.
+
+          // Prompt injection: skip in lean modes to keep prompt lean.
+          if (depth !== 'kernel' && depth !== 'capsule' && depth !== 'elixir') {
+            // Hippocampus: inject most recent episode as prior session context
+            const episodicMemory = await recallRecentEpisode(1, name.toLowerCase());
+            if (episodicMemory) {
+              prompt += `\n\n${episodicMemory}\n`;
+            }
+          }
+        }
+
+        console.log(prompt);
+        break;
+      }
+
+      case 'start': {
+        const name = positional[0];
+        if (!name) { console.error('Usage: session.js start <name> [--consumer=...]'); process.exit(1); }
+        const exclude = flags.exclude ? flags.exclude.split(',') : [];
+        const result = await startSession(name, {
+          consumer: flags.consumer || 'cli',
+          task: flags.task,
+          context: flags.context,
+          exclude,
+          mode: flags.mode || 'assembled',
+        });
+        if (json || flags['with-prompt']) {
+          const out = json
+            ? JSON.stringify(flags['with-prompt'] ? result : result.metadata, null, 2)
+            : `Session: ${result.sessionId}\n\n${result.prompt}`;
+          console.log(out);
+        } else {
+          console.log(`✅ Session started: ${result.sessionId}`);
+          console.log(`   Specialist: ${result.metadata.specialist}`);
+          console.log(`   Consumer: ${result.metadata.consumer}`);
+          console.log(`   Prompt length: ${result.metadata.promptLength} chars`);
+        }
+        break;
+      }
+
+      case 'end': {
+        const sessionId = positional[0];
+        if (!sessionId) { console.error('Usage: session.js end <sessionId>'); process.exit(1); }
+        const result = endSession(sessionId);
+        if (json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(`✅ Session ended: ${result.id}`);
+        }
+        break;
+      }
+
+      case 'active': {
+        const result = getActiveSessions();
+        if (json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          if (result.length === 0) {
+            console.log('No active sessions.');
+          } else {
+            for (const s of result) {
+              console.log(`  ${s.id} | ${s.specialist} | ${s.consumer} | ${s.startedAt}`);
+            }
+          }
+        }
+        break;
+      }
+
+      case 'clean': {
+        const keep = parseInt(flags.keep, 10) || 5;
+        const result = cleanSessions({ keep });
+        console.log(`✅ Kept ${result.kept}, removed ${result.removed}`);
+        break;
+      }
+
+      case 'stop': {
+        // No-op since the Muninn watcher was retired (TASK_2345); kept so a Stop hook that
+        // still calls `session.js stop` exits 0 instead of failing.
+        break;
+      }
+
+      case 'verify': {
+        const verifyName = positional[0];
+        if (!verifyName) {
+          console.error('Usage: session.js verify <specialistName> [--session=<id>] [--json] [--verbose]');
+          process.exit(1);
+        }
+        const verifySessionId = flags.session || null;
+        const verboseMode = flags.verbose === true;
+        const scorer = require('./identity-scorer');
+        const verifyResult = scorer.score(verifyName, { sessionId: verifySessionId, projectPath: BASE_DIR, verbose: verboseMode });
+        if (json) {
+          console.log(JSON.stringify(verifyResult, null, 2));
+        } else {
+          console.log(scorer.formatReport(verifyResult));
+        }
+        if (verifyResult.verdict === 'IDENTITY_DRIFT') process.exit(1);
+        if (verifyResult.verdict === 'WARN') process.exit(2);
+        break;
+      }
+
+      case 'clean-orphans': {
+        const dryRun = flags['dry-run'] === true;
+        const result = cleanOrphanedClaude({ dryRun });
+        if (json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(`🔍 Found ${result.found} claude.exe process(es), ${result.skipped} skipped (healthy)`);
+          if (result.details.length === 0) {
+            console.log('✅ No orphans detected.');
+          } else {
+            for (const d of result.details) {
+              console.log(`  ${d.action === 'killed' ? '💀' : '👻'} PID ${d.pid} (${d.ageHours}h old) — ${d.action}`);
+              console.log(`     ${d.cmdline}`);
+            }
+            if (dryRun) {
+              console.log(`\n⚠️  Dry run — ${result.details.length} orphan(s) found. Run without --dry-run to kill.`);
+            } else {
+              console.log(`\n✅ Killed ${result.killed} orphan(s).`);
+            }
+          }
+        }
+        break;
+      }
+
+      default:
+        console.log('Specialist Session Manager');
+        console.log('');
+        console.log('Commands:');
+        console.log('  list                     List all specialists');
+        console.log('  resolve <name>           Show specialist config');
+        console.log('  prompt <name>            Generate prompt');
+        console.log('  start <name>             Start a session');
+        console.log('  end <sessionId>          End a session');
+        console.log('  active                   List active sessions');
+        console.log('  clean [--keep=5]         Clean old sessions');
+        console.log('  clean-orphans [--dry-run] Kill orphaned claude.exe processes');
+        console.log('  stop                     Write .shutdown signal (Claude Stop hook)');
+        console.log('  verify <name>            Run identity verification for specialist');
+        process.exit(command ? 1 : 0);
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// ═══════════════════════════════════════
+//  Entry point
+// ═══════════════════════════════════════
+
+if (require.main === module) {
+  cli().catch(err => {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  });
+} else {
+  module.exports = {
+    list,
+    resolve,
+    buildPrompt,
+    startSession,
+    endSession,
+    getActiveSessions,
+    cleanSessions,
+    cleanOrphanedClaude,
+    classifyOrphanCandidates, // exported for testing (TASK_1917) — same function production uses
+    recallRecentEpisode,
+    findConversationLog,
+    // Identity verification (TASK_1080)
+    identityScore: (name, opts) => require('./identity-scorer').score(name, { projectPath: BASE_DIR, ...opts }),
+  };
+}