@empirical-gauzza/cli 1.0.37 → 1.0.39

package/lib/installers/hooks.js

@@ -1,1312 +1,1312 @@
-'use strict';
-
-const os = require('os');
-const path = require('path');
-const { log } = require('../ui');
-const { ensureDir, writeFile, readJsonIfExists } = require('../fsUtils');
-const { normalizePluginNames } = require('./nativePlugin');
-
-const CLAUDE_HOOK_SESSION_START_SOURCE = `#!/usr/bin/env node
-'use strict';
-
-var spawnSync = require('child_process').spawnSync;
-var fs = require('fs');
-var os = require('os');
-var path = require('path');
-
-// Diagnostic breadcrumb log: this hook's own stdout is only visible to Claude Code's SessionStart
-// machinery, not to a human debugging "did this actually fire" after the fact. Every run appends
-// one line here (bounded — see trimLogIfLarge) regardless of success/failure, so firing can be
-// verified by checking file growth/timestamps after starting or resuming a session, without
-// depending on server-side analytics that don't currently tag hook-originated calls.
-var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'session-start.log');
-var MAX_LOG_BYTES = 200 * 1024;
-
-function appendLog(line) {
-  try {
-    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
-    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
-    var stat = fs.statSync(LOG_PATH);
-    if (stat.size > MAX_LOG_BYTES) {
-      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
-      fs.writeFileSync(LOG_PATH, tail);
-    }
-  } catch (e) {
-    // Diagnostics must never break session start.
-  }
-}
-
-// On Windows, npm's global "empirical" command is a .cmd shim, and .cmd/.bat files can only be
-// executed via the OS shell (cmd.exe), never as a native process — this is an OS constraint, not
-// a Node quirk. But spawnSync's shell:true path joins argv into a single command-line string for
-// cmd.exe to reparse, and Node does not escape special shell characters (spaces, commas, etc.) in
-// that join for you. A --match value like "project context, conventions, recent decisions, user
-// preferences" gets mangled by that reparse, silently truncating the search query and returning
-// far fewer/worse matches than the same query run without a shell in between. The fix: resolve
-// the shim's REAL target (a plain .js file) and invoke that directly via node.exe with shell:false
-// — node.exe is a true native executable, so no shell/reparsing step exists to mangle args.
-function resolveEmpiricalEntryPoint() {
-  if (process.platform !== 'win32') {
-    // POSIX global installs are usually a symlink straight to the JS entry (or a shebang script)
-    // — spawnSync already runs these directly without a shell, so no mangling risk exists there.
-    return null;
-  }
-  try {
-    // Parse the .cmd shim itself rather than hardcoding an npm package scope: the published
-    // package has already been renamed once (was the empirical scope, now a different scope
-    // entirely - the old one is 404 on the registry), so hardcoding either name is a guaranteed
-    // future break. npm-generated shims all reference their target relative to dp0 (the shim's
-    // own directory) as a node_modules-rooted path ending in bin then a .js file - extracting
-    // that pattern works regardless of what the package is scoped or renamed to.
-    var where = spawnSync('where', ['empirical.cmd'], { encoding: 'utf8', timeout: 5000, shell: true });
-    if (where.status !== 0 || !where.stdout) return null;
-    var cmdPath = where.stdout.split(/\\r?\\n/).map(function (s) { return s.trim(); }).filter(Boolean)[0];
-    if (!cmdPath || !fs.existsSync(cmdPath)) return null;
-    var cmdContent = fs.readFileSync(cmdPath, 'utf8');
-    var match = cmdContent.match(/"%dp0%\\\\(node_modules\\\\.+?\\.js)"/);
-    if (!match) return null;
-    var candidate = path.join(path.dirname(cmdPath), match[1]);
-    return fs.existsSync(candidate) ? candidate : null;
-  } catch (e) {
-    return null;
-  }
-}
-
-function commandExists(cmd) {
-  var probe = process.platform === 'win32'
-    ? spawnSync('where', [cmd], { stdio: 'ignore', shell: true })
-    : spawnSync('which', [cmd], { stdio: 'ignore' });
-  return probe.status === 0;
-}
-
-function runMemoryQuery(args) {
-  var entryPoint = resolveEmpiricalEntryPoint();
-  if (entryPoint) {
-    appendLog('resolved direct entry point: ' + entryPoint);
-    return spawnSync(process.execPath, [entryPoint].concat(args), {
-      encoding: 'utf8',
-      // Must stay under the host manifest cap for this event (25s). Recall is chronically 2-7s
-      // and the old 10s here killed the query silently while the host still had 15s to spare.
-      timeout: 20000,
-      shell: false
-    });
-  }
-
-  // Fallback: could not resolve a direct entry point (non-Windows, or resolution failed) — run
-  // the "empirical" command as before. On POSIX this is shell:false and safe. On Windows this is
-  // shell:true and CAN still mangle args as described above; it only triggers if the direct-entry
-  // resolution above failed, so degraded (not absent) results are the acceptable worst case here.
-  appendLog('direct entry point not resolved, falling back to shell invocation (shell=' + (process.platform === 'win32') + ')');
-  return spawnSync('empirical', args, {
-    encoding: 'utf8',
-    timeout: 20000,
-    shell: process.platform === 'win32'
-  });
-}
-
-function main() {
-  appendLog('hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
-
-  if (!commandExists('empirical')) {
-    appendLog('empirical CLI not found on PATH, exiting');
-    process.exit(0);
-  }
-
-  // Declared inside main() on purpose: function declarations hoist, and other hook templates in
-  // this file have their own main() without the memory-query plumbing.
-
-  // WHAT PROJECT IS THIS, in priority order. Guessing from the directory name is the last resort,
-  // not the contract: a repo folder is not always what the corpus tags memories with.
-  //   1. EMPIRICAL_PROJECT_TAG / EMPIRICAL_TOPICS environment variables
-  //   2. .empirical.json in the working directory or any ancestor, up to 6 levels:
-  //        { "project": "empirical_v2", "topics": ["search ranking", "deploy"] }
-  //   3. the working directory name, lowercased
-  function readProjectConfig() {
-    var config = { project: '', topics: [] };
-    try {
-      var dir = process.cwd();
-      for (var depth = 0; depth < 6; depth += 1) {
-        var candidate = path.join(dir, '.empirical.json');
-        if (fs.existsSync(candidate)) {
-          var parsed = JSON.parse(fs.readFileSync(candidate, 'utf8'));
-          config.project = String(parsed && parsed.project ? parsed.project : '').trim().toLowerCase();
-          if (parsed && Array.isArray(parsed.topics)) {
-            config.topics = parsed.topics.map(function (t) { return String(t || '').trim(); }).filter(Boolean);
-          }
-          appendLog('loaded project config from ' + candidate);
-          return config;
-        }
-        var parent = path.dirname(dir);
-        if (!parent || parent === dir) { break; }
-        dir = parent;
-      }
-    } catch (e) {
-      appendLog('project config unreadable, continuing without it: ' + e.message);
-    }
-    return config;
-  }
-
-  // requireAll selects --tags-all (AND) over --tags (OR). This matters: --tags is an OR match, so
-  // asking for 'empirical_v2,todo' returns every project's todos, which put a wellnessonbalance
-  // item into an empirical_v2 session during testing on 2026-09-16.
-  function fetchMemories(matchText, tags, topK, requireAll) {
-    var args = ['memory', 'query', '--match', matchText, '--top-k', String(topK)];
-    if (tags) { args.push(requireAll ? '--tags-all' : '--tags', tags); }
-    var queryResult = runMemoryQuery(args);
-    if (!queryResult || queryResult.status !== 0 || !queryResult.stdout) {
-      appendLog('memory query failed (tags=' + (tags || 'none') + ', status=' + (queryResult && queryResult.status) + ', stderr=' + (queryResult && queryResult.stderr ? String(queryResult.stderr).slice(0, 200) : '') + ')');
-      return [];
-    }
-    try {
-      var parsed = JSON.parse(queryResult.stdout);
-      return Array.isArray(parsed) ? parsed : [];
-    } catch (e) {
-      appendLog('failed to parse memory query stdout as JSON: ' + e.message);
-      return [];
-    }
-  }
-
-  var fileConfig = readProjectConfig();
-  var envTag = String(process.env.EMPIRICAL_PROJECT_TAG || '').trim().toLowerCase();
-  var envTopics = String(process.env.EMPIRICAL_TOPICS || '').split(',').map(function (t) { return t.trim(); }).filter(Boolean);
-
-  var tag = envTag || fileConfig.project;
-  var tagSource = envTag ? 'env' : (fileConfig.project ? 'config' : 'cwd');
-  if (!tag) {
-    try {
-      tag = String(path.basename(process.cwd() || '') || '').trim().toLowerCase();
-    } catch (e) {
-      tag = '';
-    }
-  }
-
-  var topics = envTopics.length ? envTopics : fileConfig.topics;
-  var contextMatch = topics.length
-    ? topics.join(', ')
-    : 'project context, conventions, recent decisions, user preferences';
-
-  appendLog('project tag=' + (tag || '(none)') + ' (source=' + tagSource + '), topics=' + (topics.length ? topics.join('|') : '(default)'));
-
-  // Scope every query to the project. Measured 2026-09-16: with no tag filter all 8 slots went to
-  // one unrelated project during a full session in a different repo, so the only automatic context
-  // rail in the product was spending every slot on the wrong thing. A tag filter also disables the
-  // server's agent-process-note exclusion, which is what makes a project's own scar tissue and
-  // work history reachable here at all.
-  //
-  // Open items get their OWN query instead of competing for rank. Tested 2026-09-16: a due-dated
-  // memory did not surface in the generic top-8 with or without a project filter, because dueness
-  // is not a semantic property. Anything that must be seen needs a reserved slot.
-  // AND, not OR: this must be THIS project's todos. No --status filter on purpose, because todos
-  // written without a data.status would silently vanish from the one place they get surfaced;
-  // the label tells the reader to confirm instead.
-  var todos = tag ? fetchMemories('open todo, next action, follow-up, due', tag + ',todo', 3, true) : [];
-  var context = tag ? fetchMemories(contextMatch, tag, 6) : [];
-
-  // A corpus whose tags do not match the resolved project must never end up worse off than before
-  // this change, so fall back to the original unscoped query.
-  if (context.length === 0) {
-    appendLog('project-scoped query returned nothing, falling back to unscoped');
-    context = fetchMemories(contextMatch, '', 8);
-  }
-
-  if (todos.length === 0 && context.length === 0) {
-    appendLog('memory query returned zero results');
-    process.exit(0);
-  }
-
-  var openCount = todos.length;
-  var results = todos.concat(context);
-
-  appendLog('memory query returned ' + results.length + ' result(s), injecting into session context');
-
-  // Summaries in a mature corpus run to thousands of characters. Injecting eight in full is a wall
-  // of text that gets skimmed past, which fails the same way as never injecting them at all:
-  // presence in context is not attention. Truncate hard; the agent can query for the rest.
-  var lines = results.slice(0, 9).map(function (r, i) {
-    var category = r && r.category ? r.category : 'memory';
-    var summary = String(r && r.summary ? r.summary : '');
-    summary = summary.split('\\n').join(' ').split('\\r').join(' ').split('\\t').join(' ').trim();
-    if (summary.length > 240) { summary = summary.slice(0, 237) + '...'; }
-    var prefix = i < openCount ? '- [OPEN ITEM, confirm status] ' : '- [' + category + '] ';
-    return prefix + summary;
-  });
-  lines.push('- Before risky or repeated work, ask first: empirical memory query --match "<what you are about to do>" --tags scar-tissue');
-
-  console.log('Empirical memory context for this session:\\n' + lines.join('\\n'));
-  process.exit(0);
-}
-
-// Hooks must never surface as a hard failure to the host CLI (Codex/Claude/Copilot all render a
-// nonzero exit as a red "hook failed" error) - an uncaught exception anywhere above (e.g. an
-// environment that denies process spawn or fs access, such as Codex's experimental Windows
-// sandbox) must degrade to a silent no-op, not a visible crash.
-try {
-  main();
-} catch (e) {
-  try { appendLog('uncaught error in main(): ' + (e && e.message)); } catch (_e) { /* best effort */ }
-  process.exit(0);
-}
-`;
-
-// Codex-only variant of the SessionStart hook above. Confirmed live (2026-08-08, via a real
-// `codex exec` run) that Codex requires valid JSON on stdout for a hook's output to actually
-// register/display - plain text (what CLAUDE_HOOK_SESSION_START_SOURCE emits, which Claude Code
-// handles fine) makes Codex report the hook as failed. Uses the same hookSpecificOutput.
-// additionalContext shape Claude's own JSON-output hooks use (see CLAUDE_HOOK_STOP_SOURCE below) -
-// confirmed accepted by Codex's SessionStart handler specifically. Otherwise byte-identical to
-// CLAUDE_HOOK_SESSION_START_SOURCE; keep any future logic changes in sync between the two.
-const CODEX_HOOK_SESSION_START_SOURCE = `#!/usr/bin/env node
-'use strict';
-
-var spawnSync = require('child_process').spawnSync;
-var fs = require('fs');
-var os = require('os');
-var path = require('path');
-
-var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'session-start.log');
-var MAX_LOG_BYTES = 200 * 1024;
-
-function appendLog(line) {
-  try {
-    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
-    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
-    var stat = fs.statSync(LOG_PATH);
-    if (stat.size > MAX_LOG_BYTES) {
-      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
-      fs.writeFileSync(LOG_PATH, tail);
-    }
-  } catch (e) {
-    // Diagnostics must never break session start.
-  }
-}
-
-function resolveEmpiricalEntryPoint() {
-  if (process.platform !== 'win32') {
-    return null;
-  }
-  try {
-    var where = spawnSync('where', ['empirical.cmd'], { encoding: 'utf8', timeout: 5000, shell: true });
-    if (where.status !== 0 || !where.stdout) return null;
-    var cmdPath = where.stdout.split(/\\r?\\n/).map(function (s) { return s.trim(); }).filter(Boolean)[0];
-    if (!cmdPath || !fs.existsSync(cmdPath)) return null;
-    var cmdContent = fs.readFileSync(cmdPath, 'utf8');
-    var match = cmdContent.match(/"%dp0%\\\\(node_modules\\\\.+?\\.js)"/);
-    if (!match) return null;
-    var candidate = path.join(path.dirname(cmdPath), match[1]);
-    return fs.existsSync(candidate) ? candidate : null;
-  } catch (e) {
-    return null;
-  }
-}
-
-function commandExists(cmd) {
-  var probe = process.platform === 'win32'
-    ? spawnSync('where', [cmd], { stdio: 'ignore', shell: true })
-    : spawnSync('which', [cmd], { stdio: 'ignore' });
-  return probe.status === 0;
-}
-
-function runMemoryQuery(args) {
-  var entryPoint = resolveEmpiricalEntryPoint();
-  if (entryPoint) {
-    appendLog('resolved direct entry point: ' + entryPoint);
-    return spawnSync(process.execPath, [entryPoint].concat(args), {
-      encoding: 'utf8',
-      // Must stay under the host manifest cap for this event (25s). Recall is chronically 2-7s
-      // and the old 10s here killed the query silently while the host still had 15s to spare.
-      timeout: 20000,
-      shell: false
-    });
-  }
-
-  appendLog('direct entry point not resolved, falling back to shell invocation (shell=' + (process.platform === 'win32') + ')');
-  return spawnSync('empirical', args, {
-    encoding: 'utf8',
-    timeout: 20000,
-    shell: process.platform === 'win32'
-  });
-}
-
-// Codex requires VALID JSON on stdout for every hook run. Emitting nothing is as broken as
-// emitting plain text: both surface to the user as "SessionStart hook (failed)". Every early
-// return below is a legitimate "no memory context to add" outcome (CLI missing, offline,
-// expired token, zero results), so each one now emits a well-formed envelope with an empty
-// context instead of exiting silently. Found 2026-09-09: with the API unreachable this hook
-// printed nothing at all and exited 0.
-function emitContext(context) {
-  console.log(JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: 'SessionStart',
-      additionalContext: context || ''
-    }
-  }));
-}
-
-function main() {
-  appendLog('hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
-
-  if (!commandExists('empirical')) {
-    appendLog('empirical CLI not found on PATH, exiting');
-    emitContext('');
-    process.exit(0);
-  }
-
-  // Declared inside main() on purpose: function declarations hoist, and other hook templates in
-  // this file have their own main() without the memory-query plumbing.
-
-  // WHAT PROJECT IS THIS, in priority order. Guessing from the directory name is the last resort,
-  // not the contract: a repo folder is not always what the corpus tags memories with.
-  //   1. EMPIRICAL_PROJECT_TAG / EMPIRICAL_TOPICS environment variables
-  //   2. .empirical.json in the working directory or any ancestor, up to 6 levels:
-  //        { "project": "empirical_v2", "topics": ["search ranking", "deploy"] }
-  //   3. the working directory name, lowercased
-  function readProjectConfig() {
-    var config = { project: '', topics: [] };
-    try {
-      var dir = process.cwd();
-      for (var depth = 0; depth < 6; depth += 1) {
-        var candidate = path.join(dir, '.empirical.json');
-        if (fs.existsSync(candidate)) {
-          var parsed = JSON.parse(fs.readFileSync(candidate, 'utf8'));
-          config.project = String(parsed && parsed.project ? parsed.project : '').trim().toLowerCase();
-          if (parsed && Array.isArray(parsed.topics)) {
-            config.topics = parsed.topics.map(function (t) { return String(t || '').trim(); }).filter(Boolean);
-          }
-          appendLog('loaded project config from ' + candidate);
-          return config;
-        }
-        var parent = path.dirname(dir);
-        if (!parent || parent === dir) { break; }
-        dir = parent;
-      }
-    } catch (e) {
-      appendLog('project config unreadable, continuing without it: ' + e.message);
-    }
-    return config;
-  }
-
-  // requireAll selects --tags-all (AND) over --tags (OR). This matters: --tags is an OR match, so
-  // asking for 'empirical_v2,todo' returns every project's todos, which put a wellnessonbalance
-  // item into an empirical_v2 session during testing on 2026-09-16.
-  function fetchMemories(matchText, tags, topK, requireAll) {
-    var args = ['memory', 'query', '--match', matchText, '--top-k', String(topK)];
-    if (tags) { args.push(requireAll ? '--tags-all' : '--tags', tags); }
-    var queryResult = runMemoryQuery(args);
-    if (!queryResult || queryResult.status !== 0 || !queryResult.stdout) {
-      appendLog('memory query failed (tags=' + (tags || 'none') + ', status=' + (queryResult && queryResult.status) + ', stderr=' + (queryResult && queryResult.stderr ? String(queryResult.stderr).slice(0, 200) : '') + ')');
-      return [];
-    }
-    try {
-      var parsed = JSON.parse(queryResult.stdout);
-      return Array.isArray(parsed) ? parsed : [];
-    } catch (e) {
-      appendLog('failed to parse memory query stdout as JSON: ' + e.message);
-      return [];
-    }
-  }
-
-  var fileConfig = readProjectConfig();
-  var envTag = String(process.env.EMPIRICAL_PROJECT_TAG || '').trim().toLowerCase();
-  var envTopics = String(process.env.EMPIRICAL_TOPICS || '').split(',').map(function (t) { return t.trim(); }).filter(Boolean);
-
-  var tag = envTag || fileConfig.project;
-  var tagSource = envTag ? 'env' : (fileConfig.project ? 'config' : 'cwd');
-  if (!tag) {
-    try {
-      tag = String(path.basename(process.cwd() || '') || '').trim().toLowerCase();
-    } catch (e) {
-      tag = '';
-    }
-  }
-
-  var topics = envTopics.length ? envTopics : fileConfig.topics;
-  var contextMatch = topics.length
-    ? topics.join(', ')
-    : 'project context, conventions, recent decisions, user preferences';
-
-  appendLog('project tag=' + (tag || '(none)') + ' (source=' + tagSource + '), topics=' + (topics.length ? topics.join('|') : '(default)'));
-
-  // Scope every query to the project. Measured 2026-09-16: with no tag filter all 8 slots went to
-  // one unrelated project during a full session in a different repo, so the only automatic context
-  // rail in the product was spending every slot on the wrong thing. A tag filter also disables the
-  // server's agent-process-note exclusion, which is what makes a project's own scar tissue and
-  // work history reachable here at all.
-  //
-  // Open items get their OWN query instead of competing for rank. Tested 2026-09-16: a due-dated
-  // memory did not surface in the generic top-8 with or without a project filter, because dueness
-  // is not a semantic property. Anything that must be seen needs a reserved slot.
-  // AND, not OR: this must be THIS project's todos. No --status filter on purpose, because todos
-  // written without a data.status would silently vanish from the one place they get surfaced;
-  // the label tells the reader to confirm instead.
-  var todos = tag ? fetchMemories('open todo, next action, follow-up, due', tag + ',todo', 3, true) : [];
-  var context = tag ? fetchMemories(contextMatch, tag, 6) : [];
-
-  // A corpus whose tags do not match the resolved project must never end up worse off than before
-  // this change, so fall back to the original unscoped query.
-  if (context.length === 0) {
-    appendLog('project-scoped query returned nothing, falling back to unscoped');
-    context = fetchMemories(contextMatch, '', 8);
-  }
-
-  if (todos.length === 0 && context.length === 0) {
-    appendLog('memory query returned zero results');
-    emitContext('');
-    process.exit(0);
-  }
-
-  var openCount = todos.length;
-  var results = todos.concat(context);
-
-  appendLog('memory query returned ' + results.length + ' result(s), injecting into session context');
-
-  // Summaries in a mature corpus run to thousands of characters. Injecting eight in full is a wall
-  // of text that gets skimmed past, which fails the same way as never injecting them at all:
-  // presence in context is not attention. Truncate hard; the agent can query for the rest.
-  var lines = results.slice(0, 9).map(function (r, i) {
-    var category = r && r.category ? r.category : 'memory';
-    var summary = String(r && r.summary ? r.summary : '');
-    summary = summary.split('\\n').join(' ').split('\\r').join(' ').split('\\t').join(' ').trim();
-    if (summary.length > 240) { summary = summary.slice(0, 237) + '...'; }
-    var prefix = i < openCount ? '- [OPEN ITEM, confirm status] ' : '- [' + category + '] ';
-    return prefix + summary;
-  });
-  lines.push('- Before risky or repeated work, ask first: empirical memory query --match "<what you are about to do>" --tags scar-tissue');
-
-  console.log(JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: 'SessionStart',
-      additionalContext: 'Empirical memory context for this session:\\n' + lines.join('\\n')
-    }
-  }));
-  process.exit(0);
-}
-
-try {
-  main();
-} catch (e) {
-  try { appendLog('uncaught error in main(): ' + (e && e.message)); } catch (_e) { /* best effort */ }
-  try { emitContext(''); } catch (_e2) { /* stdout already unusable */ }
-  process.exit(0);
-}
-`;
-
-// Copilot-only variant of the SessionStart hook. Per GitHub's own hooks reference (fetched
-// 2026-08-08): unlike Claude/Codex, Copilot's sessionStart event has NO output mechanism at all
-// - there is no additionalContext-equivalent field, so a hook cannot inject memory context into
-// the session this way, full stop (this is a genuine platform limitation, not a bug to work
-// around). Separately, Copilot requires ALL hook stdout to be valid JSON parsed via a single
-// JSON.parse call - plain text (fine for Claude, and previously assumed fine here too) is
-// invalid and makes Copilot log a hook execution failure. So this variant still runs the memory
-// query and logs the result for diagnostic/audit purposes, but emits {} (empty, valid JSON,
-// explicitly documented as "use defaults") instead of attempting to inject anything.
-const COPILOT_HOOK_SESSION_START_SOURCE = `#!/usr/bin/env node
-'use strict';
-
-var spawnSync = require('child_process').spawnSync;
-var fs = require('fs');
-var os = require('os');
-var path = require('path');
-
-var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'session-start.log');
-var MAX_LOG_BYTES = 200 * 1024;
-
-function appendLog(line) {
-  try {
-    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
-    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
-    var stat = fs.statSync(LOG_PATH);
-    if (stat.size > MAX_LOG_BYTES) {
-      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
-      fs.writeFileSync(LOG_PATH, tail);
-    }
-  } catch (e) {
-    // Diagnostics must never break session start.
-  }
-}
-
-function resolveEmpiricalEntryPoint() {
-  if (process.platform !== 'win32') {
-    return null;
-  }
-  try {
-    var where = spawnSync('where', ['empirical.cmd'], { encoding: 'utf8', timeout: 5000, shell: true });
-    if (where.status !== 0 || !where.stdout) return null;
-    var cmdPath = where.stdout.split(/\\r?\\n/).map(function (s) { return s.trim(); }).filter(Boolean)[0];
-    if (!cmdPath || !fs.existsSync(cmdPath)) return null;
-    var cmdContent = fs.readFileSync(cmdPath, 'utf8');
-    var match = cmdContent.match(/"%dp0%\\\\(node_modules\\\\.+?\\.js)"/);
-    if (!match) return null;
-    var candidate = path.join(path.dirname(cmdPath), match[1]);
-    return fs.existsSync(candidate) ? candidate : null;
-  } catch (e) {
-    return null;
-  }
-}
-
-function commandExists(cmd) {
-  var probe = process.platform === 'win32'
-    ? spawnSync('where', [cmd], { stdio: 'ignore', shell: true })
-    : spawnSync('which', [cmd], { stdio: 'ignore' });
-  return probe.status === 0;
-}
-
-function runMemoryQuery(args) {
-  var entryPoint = resolveEmpiricalEntryPoint();
-  if (entryPoint) {
-    appendLog('resolved direct entry point: ' + entryPoint);
-    return spawnSync(process.execPath, [entryPoint].concat(args), {
-      encoding: 'utf8',
-      // Must stay under the host manifest cap for this event (25s). Recall is chronically 2-7s
-      // and the old 10s here killed the query silently while the host still had 15s to spare.
-      timeout: 20000,
-      shell: false
-    });
-  }
-
-  appendLog('direct entry point not resolved, falling back to shell invocation (shell=' + (process.platform === 'win32') + ')');
-  return spawnSync('empirical', args, {
-    encoding: 'utf8',
-    timeout: 20000,
-    shell: process.platform === 'win32'
-  });
-}
-
-// 2026-09-18: GitHub's own hooks reference (re-checked - the August 2026 check this file used to
-// cite was stale) confirms sessionStart CAN inject additionalContext for command-type hooks, same
-// flat { additionalContext: "..." } shape postToolUse etc. use. This event's input payload also
-// carries an optional initialPrompt - using it as the query (like the removed UserPromptSubmit
-// hook did for its own prompt) makes the one real query relevant to what's actually being asked,
-// not just a generic default.
-function readStdinPayload() {
-  try {
-    var raw = fs.readFileSync(0, 'utf8');
-    return raw ? JSON.parse(raw) : {};
-  } catch (e) {
-    return {};
-  }
-}
-
-function main() {
-  appendLog('hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
-  var payload = readStdinPayload();
-  var initialPrompt = String((payload && (payload.initialPrompt || payload.initial_prompt)) || '').trim();
-
-  if (!commandExists('empirical')) {
-    appendLog('empirical CLI not found on PATH, exiting');
-    console.log('{}');
-    process.exit(0);
-  }
-
-  // Declared inside main() on purpose: function declarations hoist, and other hook templates in
-  // this file have their own main() without the memory-query plumbing.
-
-  // WHAT PROJECT IS THIS, in priority order. Guessing from the directory name is the last resort,
-  // not the contract: a repo folder is not always what the corpus tags memories with.
-  //   1. EMPIRICAL_PROJECT_TAG / EMPIRICAL_TOPICS environment variables
-  //   2. .empirical.json in the working directory or any ancestor, up to 6 levels:
-  //        { "project": "empirical_v2", "topics": ["search ranking", "deploy"] }
-  //   3. the working directory name, lowercased
-  function readProjectConfig() {
-    var config = { project: '', topics: [] };
-    try {
-      var dir = process.cwd();
-      for (var depth = 0; depth < 6; depth += 1) {
-        var candidate = path.join(dir, '.empirical.json');
-        if (fs.existsSync(candidate)) {
-          var parsed = JSON.parse(fs.readFileSync(candidate, 'utf8'));
-          config.project = String(parsed && parsed.project ? parsed.project : '').trim().toLowerCase();
-          if (parsed && Array.isArray(parsed.topics)) {
-            config.topics = parsed.topics.map(function (t) { return String(t || '').trim(); }).filter(Boolean);
-          }
-          appendLog('loaded project config from ' + candidate);
-          return config;
-        }
-        var parent = path.dirname(dir);
-        if (!parent || parent === dir) { break; }
-        dir = parent;
-      }
-    } catch (e) {
-      appendLog('project config unreadable, continuing without it: ' + e.message);
-    }
-    return config;
-  }
-
-  // requireAll selects --tags-all (AND) over --tags (OR). This matters: --tags is an OR match, so
-  // asking for 'empirical_v2,todo' returns every project's todos, which put a wellnessonbalance
-  // item into an empirical_v2 session during testing on 2026-09-16.
-  function fetchMemories(matchText, tags, topK, requireAll) {
-    var args = ['memory', 'query', '--match', matchText, '--top-k', String(topK)];
-    if (tags) { args.push(requireAll ? '--tags-all' : '--tags', tags); }
-    var queryResult = runMemoryQuery(args);
-    if (!queryResult || queryResult.status !== 0 || !queryResult.stdout) {
-      appendLog('memory query failed (tags=' + (tags || 'none') + ', status=' + (queryResult && queryResult.status) + ', stderr=' + (queryResult && queryResult.stderr ? String(queryResult.stderr).slice(0, 200) : '') + ')');
-      return [];
-    }
-    try {
-      var parsed = JSON.parse(queryResult.stdout);
-      return Array.isArray(parsed) ? parsed : [];
-    } catch (e) {
-      appendLog('failed to parse memory query stdout as JSON: ' + e.message);
-      return [];
-    }
-  }
-
-  var fileConfig = readProjectConfig();
-  var envTag = String(process.env.EMPIRICAL_PROJECT_TAG || '').trim().toLowerCase();
-  var envTopics = String(process.env.EMPIRICAL_TOPICS || '').split(',').map(function (t) { return t.trim(); }).filter(Boolean);
-
-  var tag = envTag || fileConfig.project;
-  var tagSource = envTag ? 'env' : (fileConfig.project ? 'config' : 'cwd');
-  if (!tag) {
-    try {
-      tag = String(path.basename(process.cwd() || '') || '').trim().toLowerCase();
-    } catch (e) {
-      tag = '';
-    }
-  }
-
-  var topics = envTopics.length ? envTopics : fileConfig.topics;
-  var contextMatch = topics.length
-    ? topics.join(', ')
-    : (initialPrompt || 'project context, conventions, recent decisions, user preferences');
-
-  appendLog('project tag=' + (tag || '(none)') + ' (source=' + tagSource + '), topics=' + (topics.length ? topics.join('|') : '(default)') + ', usingInitialPrompt=' + Boolean(initialPrompt && !topics.length));
-
-  // Scope every query to the project. Measured 2026-09-16: with no tag filter all 8 slots went to
-  // one unrelated project during a full session in a different repo, so the only automatic context
-  // rail in the product was spending every slot on the wrong thing. A tag filter also disables the
-  // server's agent-process-note exclusion, which is what makes a project's own scar tissue and
-  // work history reachable here at all.
-  //
-  // Open items get their OWN query instead of competing for rank. Tested 2026-09-16: a due-dated
-  // memory did not surface in the generic top-8 with or without a project filter, because dueness
-  // is not a semantic property. Anything that must be seen needs a reserved slot.
-  // AND, not OR: this must be THIS project's todos. No --status filter on purpose, because todos
-  // written without a data.status would silently vanish from the one place they get surfaced;
-  // the label tells the reader to confirm instead.
-  var todos = tag ? fetchMemories('open todo, next action, follow-up, due', tag + ',todo', 3, true) : [];
-  var context = tag ? fetchMemories(contextMatch, tag, 6) : [];
-
-  // A corpus whose tags do not match the resolved project must never end up worse off than before
-  // this change, so fall back to the original unscoped query.
-  if (context.length === 0) {
-    appendLog('project-scoped query returned nothing, falling back to unscoped');
-    context = fetchMemories(contextMatch, '', 8);
-  }
-
-  if (todos.length === 0 && context.length === 0) {
-    appendLog('memory query returned zero results');
-    console.log('{}');
-    process.exit(0);
-  }
-
-  var openCount = todos.length;
-  var results = todos.concat(context);
-
-  // Summaries in a mature corpus run to thousands of characters. Injecting eight in full is a wall
-  // of text that gets skimmed past, which fails the same way as never injecting them at all:
-  // presence in context is not attention. Truncate hard; the agent can query for the rest.
-  var lines = results.slice(0, 9).map(function (r, i) {
-    var category = r && r.category ? r.category : 'memory';
-    var summary = String(r && r.summary ? r.summary : '');
-    summary = summary.split('\\n').join(' ').split('\\r').join(' ').split('\\t').join(' ').trim();
-    if (summary.length > 240) { summary = summary.slice(0, 237) + '...'; }
-    var prefix = i < openCount ? '- [OPEN ITEM, confirm status] ' : '- [' + category + '] ';
-    return prefix + summary;
-  });
-  lines.push('- Before risky or repeated work, ask first: empirical memory query --match "<what you are about to do>" --tags scar-tissue');
-
-  // additionalContext is honored for command-type sessionStart hooks (re-confirmed 2026-09-18
-  // against GitHub's current hooks reference - the prior "no output channel" comment here was
-  // stale). Delivered invisibly: this never touches the visible prompt, unlike the UserPromptSubmit
-  // approach it replaces (removed - see installCopilotHooks's comment).
-  var block = 'Empirical memory context for this session:\\n' + lines.join('\\n');
-  appendLog('memory query returned ' + results.length + ' result(s), injecting via additionalContext');
-  console.log(JSON.stringify({ additionalContext: block }));
-  process.exit(0);
-}
-
-try {
-  main();
-} catch (e) {
-  try { appendLog('uncaught error in main(): ' + (e && e.message)); } catch (_e) { /* best effort */ }
-  console.log('{}');
-  process.exit(0);
-}
-`;
-
-// Copilot has no UserPromptSubmit real-recall hook (removed 2026-09-18, superseded by
-// additionalContext delivery through COPILOT_HOOK_SESSION_START_SOURCE above). That approach was
-// abandoned because Copilot renders the ENTIRE modifiedPrompt back in the terminal as the user's
-// own visible message - confirmed live, not documented, and not what "real hook" was supposed to
-// mean. sessionStart's additionalContext (re-confirmed against current GitHub docs - the prior
-// "no output channel" comment on that hook was stale) delivers the same real query invisibly
-// instead, at the cost of firing once per real session rather than being keyed to the very first
-// prompt's exact text (it uses the sessionStart payload's own initialPrompt field instead, which
-// is present per GitHub's schema but not verified live as of this comment).
-
-// Codex-only variant of the Stop reminder. Confirmed live (2026-08-08, via a real `codex
-// exec` run) that Codex's Stop hook specifically requires a { systemMessage: "..." } JSON shape
-// on stdout - plain text makes Codex report the hook as failed. Distinct from Claude's own JSON
-// shape (hookSpecificOutput.additionalContext, see CLAUDE_HOOK_STOP_SOURCE below). Copilot has no
-// Stop hook at all (removed 2026-09-18, see the comment above CLAUDE_HOOK_STOP_SOURCE).
-const CODEX_HOOK_STOP_SOURCE = `#!/usr/bin/env node
-'use strict';
-
-var fs = require('fs');
-var os = require('os');
-var path = require('path');
-
-var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'stop.log');
-var MAX_LOG_BYTES = 200 * 1024;
-
-function appendLog(line) {
-  try {
-    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
-    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
-    var stat = fs.statSync(LOG_PATH);
-    if (stat.size > MAX_LOG_BYTES) {
-      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
-      fs.writeFileSync(LOG_PATH, tail);
-    }
-  } catch (e) {
-    // Diagnostics must never break the hook.
-  }
-}
-
-function readStdinPayload() {
-  try {
-    var raw = fs.readFileSync(0, 'utf8');
-    return raw ? JSON.parse(raw) : {};
-  } catch (e) {
-    return {};
-  }
-}
-
-function main() {
-  var payload = readStdinPayload();
-
-  if (payload && payload.stop_hook_active === true) {
-    appendLog('stop_hook_active=true, skipping reminder');
-    process.exit(0);
-  }
-
-  appendLog('stop hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
-
-  console.log(JSON.stringify({
-    systemMessage: '[Empirical reminder] Before finishing: if this turn included a completed decision, a corrected mistake, or meaningful work worth remembering, record it now, one memory per finding (a fix, a root cause, a decision, a lesson), via the empirical-memory, empirical-work-history, or empirical-scar-tissue skill or \`empirical memory record\`. Local notes are not recorded. Do not wait to be asked.'
-  }));
-  process.exit(0);
-}
-
-try {
-  main();
-} catch (e) {
-  try { appendLog('uncaught error in main(): ' + (e && e.message)); } catch (_e) { /* best effort */ }
-  process.exit(0);
-}
-`;
-
-// Copilot's Stop reminder (agentStop) was removed entirely 2026-09-18 - see installCopilotHooks's
-// comment in this file for why (agentStop only supports decision:"block"|"allow" with no passive
-// field, so any reminder there forces a disruptive extra visible turn; no per-session cap on that
-// avoids the tradeoff between nagging every turn and going silent right before something worth
-// recording happens - confirmed live 2026-09-17/18 causing both failure modes in turn). Copilot
-// relies entirely on copilot-instructions.md instead (see coreMemoryBlock.js's Copilot addendum).
-
-// Claude-only variant of the Stop reminder above. hookSpecificOutput.additionalContext (stdout,
-// exit 0) is Claude Code's non-blocking Stop-hook feedback channel: the text is fed into context
-// and the conversation continues, same outcome the earlier exit-2 approach achieved, but the
-// transcript UI renders it as a plain system reminder instead of a red "Stop hook error" line.
-// Codex needs its own systemMessage shape (CODEX_HOOK_STOP_SOURCE) - plain console.log output
-// (what this hook used before the additionalContext fix) never reaches the model. Copilot has no
-// Stop hook at all (removed 2026-09-18, see the comment just above this one).
-const CLAUDE_HOOK_STOP_SOURCE = `#!/usr/bin/env node
-'use strict';
-
-var fs = require('fs');
-var os = require('os');
-var path = require('path');
-
-var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'stop.log');
-var MAX_LOG_BYTES = 200 * 1024;
-
-function appendLog(line) {
-  try {
-    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
-    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
-    var stat = fs.statSync(LOG_PATH);
-    if (stat.size > MAX_LOG_BYTES) {
-      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
-      fs.writeFileSync(LOG_PATH, tail);
-    }
-  } catch (e) {
-    // Diagnostics must never break the hook.
-  }
-}
-
-function readStdinPayload() {
-  try {
-    var raw = fs.readFileSync(0, 'utf8');
-    return raw ? JSON.parse(raw) : {};
-  } catch (e) {
-    return {};
-  }
-}
-
-function main() {
-  var payload = readStdinPayload();
-
-  // stop_hook_active === true means Claude is re-invoking this hook because a PRIOR Stop hook
-  // (possibly this same one) already surfaced additionalContext and forced a continuation this
-  // turn. additionalContext causes the same forced-continuation behavior decision:block does -
-  // confirmed empirically: without this guard the hook re-fired every ~2-3s in an infinite loop,
-  // since each additionalContext output triggers another Stop event. Must exit 0 with no output
-  // here, unconditionally, or the loop continues.
-  if (payload && payload.stop_hook_active === true) {
-    appendLog('stop_hook_active=true, skipping reminder (already surfaced once this turn)');
-    process.exit(0);
-  }
-
-  appendLog('stop hook fired (pid=' + process.pid + ', platform=' + process.platform + '), surfacing reminder via additionalContext');
-
-  process.stdout.write(JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: 'Stop',
-      additionalContext: '[Empirical] Record memory-worthy work now: one memory per finding (a fix, a root cause, a decision, a lesson) via the empirical-memory, empirical-work-history, or empirical-scar-tissue skill. Local notes are not recorded.'
-    }
-  }) + '\\n');
-  process.exit(0);
-}
-
-// See EMPIRICAL_HOOK_SESSION_START_SOURCE's identical guard: a crash here must degrade to a
-// silent no-op, never a visible "hook failed" error in the host CLI.
-try {
-  main();
-} catch (e) {
-  try { appendLog('uncaught error in main(): ' + (e && e.message)); } catch (_e) { /* best effort */ }
-  process.exit(0);
-}
-`;
-
-// UserPromptSubmit: fires before each turn is processed (Claude, Codex, and Copilot all support
-// this event under the same name per each platform's docs/source). This is the recall-side
-// counterpart to Stop's write-side reminder - deliberately a STATIC message, not a live
-// `empirical memory query` call: a prior per-turn hook in this codebase was removed for making an
-// unconditional network call on every single prompt (see the comment above installClaudeHooks),
-// and re-adding that cost here on three platforms at once was an explicit no per product decision.
-// The message itself is generated per-install from the actual plugin set being installed, not one
-// fixed string for everyone - e.g. someone who declined empirical-scar-tissue at install time
-// never sees a scar-tissue reminder, since that capability isn't actually available to them.
-//
-// Claude and Codex only - Copilot has no UserPromptSubmit reminder at all (removed 2026-09-18,
-// see installCopilotHooks's comment in this file for why: its only output field is a full prompt
-// replacement, not a side channel, so any injected reminder here reads as fake, model-authored
-// text inside what looks like the user's own message).
-function buildPromptReminderMessage(pluginNames, platform) {
-  const names = normalizePluginNames(pluginNames);
-
-  const lines = [
-    'Before responding: if this task needs prior context (research, debugging, a spec or status update, a handoff), query Empirical memory first via the empirical-memory skill or empirical memory query - do not assume you already have enough context.'
-  ];
-  if (names.includes('empirical-work-history')) {
-    lines.push('If you are picking up previously completed work, check for a recent work-history entry before assuming there is none.');
-    if (platform === 'codex') {
-      lines.push('If this turn results in meaningful completed work, BEFORE sending your final response you MUST use the empirical-work-history skill or record it via Empirical. The entry must carry tag work-history and mass 1; verify the create receipt. CLI fallback must use --json-file with data.session and data.git; do not use the shorthand record command for coding work. Do not wait for the Stop hook.');
-    }
-  }
-  if (names.includes('empirical-scar-tissue')) {
-    lines.push('Check for scar tissue before repeating a past mistake in this area.');
-  }
-  if (names.includes('empirical-todo')) {
-    lines.push('If there is an open todo for this project, check it before starting new work.');
-  }
-  return '[Empirical reminder] ' + lines.join(' ');
-}
-
-// Builds the full UserPromptSubmit hook script source with the tailored message baked in at
-// generation time (via JSON.stringify, so the message is embedded as a single already-escaped
-// string literal - substituted through `${}`, not written as raw template-literal source text,
-// which is what caused the earlier comment-escaping bug in this same file. Never do the latter).
-// `platform`:
-//  - 'codex': Codex's required hookSpecificOutput.additionalContext JSON shape (confirmed live
-//    2026-08-08 via a real `codex exec` run - plain text made Codex report the hook as failed).
-//  - default ('claude'): plain console.log.
-// Copilot has no variant here at all (removed 2026-09-18) - see installCopilotHooks's comment.
-function buildUserPromptSubmitHookSource(pluginNames, platform) {
-  const messageLiteral = JSON.stringify(buildPromptReminderMessage(pluginNames, platform));
-
-  const outputStatement = platform === 'codex'
-    ? `console.log(JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: 'UserPromptSubmit',
-      additionalContext: ${messageLiteral}
-    }
-  }));`
-    : `console.log(${messageLiteral});`;
-
-  return `#!/usr/bin/env node
-'use strict';
-
-var fs = require('fs');
-var os = require('os');
-var path = require('path');
-
-var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'user-prompt-submit.log');
-var MAX_LOG_BYTES = 200 * 1024;
-
-function appendLog(line) {
-  try {
-    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
-    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
-    var stat = fs.statSync(LOG_PATH);
-    if (stat.size > MAX_LOG_BYTES) {
-      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
-      fs.writeFileSync(LOG_PATH, tail);
-    }
-  } catch (e) {
-    // Diagnostics must never break the hook.
-  }
-}
-
-// A crash here must degrade to a silent no-op, never a visible "hook failed" error in the host CLI.
-try {
-  appendLog('user-prompt-submit hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
-  ${outputStatement}
-} catch (e) {
-  try { appendLog('uncaught error: ' + (e && e.message)); } catch (_e) { /* best effort */ }
-}
-process.exit(0);
-`;
-}
-
-function getEmpiricalHooksDir() {
-  return path.join(os.homedir(), '.empirical', 'hooks');
-}
-
-function buildHookCommand(scriptPath) {
-  return `"${process.execPath}" "${scriptPath}"`;
-}
-
-// Confirmed live (2026-08-08, via a real `copilot -p` run with debug logging): Copilot runs a
-// hook's "command"/"powershell" field through powershell.exe on Windows, and a bare
-// `"path" "arg"` string is not valid PowerShell syntax without the call operator (&) - two
-// adjacent quoted string literals with nothing between them is a ParserError
-// ("Unexpected token '...' in expression or statement"), not a "file not found"-style failure.
-// This is a completely different bug from Codex's (which needed 8.3 short paths to avoid
-// quoting) - no short-path workaround is needed here, just the operator PowerShell requires
-// before an executable path.
-function buildPowershellHookCommand(scriptPath) {
-  return `& "${process.execPath}" "${scriptPath}"`;
-}
-
-function removeEmpiricalHookEntries(entries, scriptPath) {
-  if (!Array.isArray(entries)) return [];
-  return entries
-    .map((entry) => {
-      if (!entry || !Array.isArray(entry.hooks)) return entry;
-      const filteredHooks = entry.hooks.filter(
-        (h) => !(h && typeof h.command === 'string' && h.command.includes(scriptPath))
-      );
-      return { ...entry, hooks: filteredHooks };
-    })
-    .filter((entry) => entry && (!Array.isArray(entry.hooks) || entry.hooks.length > 0));
-}
-
-function installClaudeHooks(pluginNames) {
-  const hooksDir = getEmpiricalHooksDir();
-  ensureDir(hooksDir);
-
-  // A prior version of this hook made an unconditional `empirical memory query` network call on
-  // every single prompt and was removed for being wasteful (see git history). This is a
-  // deliberate reintroduction at the SAME script path, but with fundamentally different content:
-  // a static, install-time-generated reminder with no network call at all - the cost concern that
-  // killed the old version does not apply to a plain stdout write.
-  const userPromptScriptPath = path.join(hooksDir, 'claude-user-prompt-submit.js');
-  const sessionStartScriptPath = path.join(hooksDir, 'claude-session-start.js');
-  const stopScriptPath = path.join(hooksDir, 'claude-stop.js');
-  writeFile(sessionStartScriptPath, CLAUDE_HOOK_SESSION_START_SOURCE);
-  writeFile(stopScriptPath, CLAUDE_HOOK_STOP_SOURCE);
-  writeFile(userPromptScriptPath, buildUserPromptSubmitHookSource(pluginNames));
-
-  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
-  const settings = readJsonIfExists(settingsPath) || {};
-  if (!settings.hooks || typeof settings.hooks !== 'object') {
-    settings.hooks = {};
-  }
-
-  settings.hooks.UserPromptSubmit = removeEmpiricalHookEntries(settings.hooks.UserPromptSubmit, userPromptScriptPath);
-  settings.hooks.UserPromptSubmit.push({
-    hooks: [{ type: 'command', command: buildHookCommand(userPromptScriptPath), timeout: 10 }]
-  });
-
-  settings.hooks.SessionStart = removeEmpiricalHookEntries(settings.hooks.SessionStart, sessionStartScriptPath);
-  for (const matcher of ['startup', 'resume', 'compact']) {
-    settings.hooks.SessionStart.push({
-      matcher,
-      hooks: [{ type: 'command', command: buildHookCommand(sessionStartScriptPath), timeout: 25 }]
-    });
-  }
-
-  settings.hooks.Stop = removeEmpiricalHookEntries(settings.hooks.Stop, stopScriptPath);
-  settings.hooks.Stop.push({
-    hooks: [{ type: 'command', command: buildHookCommand(stopScriptPath), timeout: 10 }]
-  });
-
-  writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
-  log('  - Claude SessionStart + UserPromptSubmit + Stop hooks installed for deterministic memory lookups and reminders.');
-}
-
-// Codex CLI ships a real hooks system (confirmed against openai/codex source — codex-rs/hooks,
-// codex-rs/config/src/hook_config.rs — not assumed from docs alone, since third-party writeups
-// disagreed on Windows support). It reads <CODEX_HOME>/hooks.json (JSON, not the config.toml
-// used for MCP/model settings — a separate file, so this never touches config.toml) shaped as
-// { hooks: { SessionStart: [{ matcher, hooks: [{ type: 'command', command, commandWindows,
-// timeout }] }], ... } }. CODEX_HOME defaults to ~/.codex when unset, same convention as
-// ~/.claude for Claude Code.
-function getCodexHomeDir() {
-  return process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
-}
-
-function removeEmpiricalHooksJsonEntries(entries, scriptPath) {
-  if (!Array.isArray(entries)) return [];
-  return entries
-    .map((entry) => {
-      if (!entry || !Array.isArray(entry.hooks)) return entry;
-      const filteredHooks = entry.hooks.filter(
-        (h) => !(h && typeof h.command === 'string' && h.command.includes(scriptPath))
-      );
-      return { ...entry, hooks: filteredHooks };
-    })
-    .filter((entry) => entry && (!Array.isArray(entry.hooks) || entry.hooks.length > 0));
-}
-
-// Codex's Windows sandbox (confirmed via `codex doctor` -> "filesystem sandbox: restricted" and
-// ~/.codex/.sandbox/sandbox.*.log's "processed N write roots (read roots delegated)" / "applying
-// read ACLs" at session start) scopes filesystem access per-session to project-specific roots
-// plus, necessarily, CODEX_HOME itself (Codex reads hooks.json, its state db, and its plugin
-// cache from there on every session regardless of project). The shared `~/.empirical/hooks`
-// directory used by Claude/Copilot is neither - so under this sandbox, node.exe most likely
-// cannot even read a hook script living there, which is why hooks fail identically (exit 1)
-// across SessionStart/UserPromptSubmit/Stop regardless of what each script actually does,
-// including the trivial UserPromptSubmit script that spawns no subprocess at all. Claude Code
-// hooks are unaffected (confirmed working from the shared dir) and Copilot has shown no such
-// failure, so only Codex's copies are relocated here - Claude/Copilot keep using
-// getEmpiricalHooksDir() unchanged.
-function getCodexHooksScriptsDir() {
-  return path.join(getCodexHomeDir(), 'empirical-hooks');
-}
-
-// Confirmed live (2026-08-08, via a real `codex exec` run): Codex's Windows hook launcher fails
-// to parse a quoted executable path (e.g. `"C:\Program Files\nodejs\node.exe" "<script>"`,
-// otherwise a perfectly standard Windows command line - Claude Code and every direct shell/
-// spawnSync invocation handle it fine) and reports the hook as a nonzero-exit failure before any
-// of the script's own JS ever runs. Windows 8.3 short path names never contain spaces, so
-// resolving both the node executable and the script path to their short form and joining them
-// unquoted sidesteps the parser entirely. Computed once at install time (not per hook
-// invocation), so a synchronous shell call here is an acceptable cost.
-function getWindowsShortPath(longPath) {
-  if (process.platform !== 'win32') return null;
-  try {
-    const { execSync } = require('child_process');
-    const out = execSync(`cmd /c for %I in ("${longPath}") do @echo %~sI`, { encoding: 'utf8', timeout: 5000 });
-    const short = out.split(/\r?\n/).map((s) => s.trim()).filter(Boolean).pop();
-    const fs = require('fs');
-    return short && fs.existsSync(short) ? short : null;
-  } catch (e) {
-    return null;
-  }
-}
-
-// Builds Codex's commandWindows value using short paths so neither the executable nor the script
-// path ever needs quoting. Falls back to the normal quoted buildHookCommand() form if short-path
-// resolution fails for any reason (e.g. 8.3 name generation disabled on that volume) - degraded
-// (same behavior as before this fix) rather than broken.
-function buildCodexWindowsHookCommand(scriptPath) {
-  const shortNode = getWindowsShortPath(process.execPath);
-  const shortScript = getWindowsShortPath(scriptPath);
-  if (shortNode && shortScript) {
-    return `${shortNode} ${shortScript}`;
-  }
-  return buildHookCommand(scriptPath);
-}
-
-function installCodexHooks(pluginNames) {
-  const fs = require('fs');
-  const legacyHooksDir = getEmpiricalHooksDir();
-  const hooksDir = getCodexHooksScriptsDir();
-  ensureDir(hooksDir);
-
-  const sessionStartScriptPath = path.join(hooksDir, 'codex-session-start.js');
-  const stopScriptPath = path.join(hooksDir, 'codex-stop.js');
-  const userPromptScriptPath = path.join(hooksDir, 'codex-user-prompt-submit.js');
-  writeFile(sessionStartScriptPath, CODEX_HOOK_SESSION_START_SOURCE);
-  writeFile(stopScriptPath, CODEX_HOOK_STOP_SOURCE);
-  writeFile(userPromptScriptPath, buildUserPromptSubmitHookSource(pluginNames, 'codex'));
-
-  // Best-effort cleanup of the pre-relocation script files/entries at the old shared path, so a
-  // machine that already had Codex hooks installed doesn't end up with both the old (broken
-  // under the sandbox) and new registration firing redundantly.
-  const legacySessionStartScriptPath = path.join(legacyHooksDir, 'codex-session-start.js');
-  const legacyStopScriptPath = path.join(legacyHooksDir, 'codex-stop.js');
-  const legacyUserPromptScriptPath = path.join(legacyHooksDir, 'codex-user-prompt-submit.js');
-  for (const legacyPath of [legacySessionStartScriptPath, legacyStopScriptPath, legacyUserPromptScriptPath]) {
-    try {
-      if (fs.existsSync(legacyPath)) fs.unlinkSync(legacyPath);
-    } catch (_error) {
-      // best-effort cleanup only
-    }
-  }
-
-  const hooksJsonPath = path.join(getCodexHomeDir(), 'hooks.json');
-  const hooksFile = readJsonIfExists(hooksJsonPath) || {};
-  if (!hooksFile.hooks || typeof hooksFile.hooks !== 'object') {
-    hooksFile.hooks = {};
-  }
-
-  hooksFile.hooks.SessionStart = removeEmpiricalHooksJsonEntries(
-    removeEmpiricalHooksJsonEntries(hooksFile.hooks.SessionStart, sessionStartScriptPath),
-    legacySessionStartScriptPath
-  );
-  const sessionStartCommand = buildHookCommand(sessionStartScriptPath);
-  const sessionStartCommandWindows = buildCodexWindowsHookCommand(sessionStartScriptPath);
-  for (const matcher of ['startup', 'resume']) {
-    hooksFile.hooks.SessionStart.push({
-      matcher,
-      hooks: [{ type: 'command', command: sessionStartCommand, commandWindows: sessionStartCommandWindows, timeout: 25 }]
-    });
-  }
-
-  hooksFile.hooks.Stop = removeEmpiricalHooksJsonEntries(
-    removeEmpiricalHooksJsonEntries(hooksFile.hooks.Stop, stopScriptPath),
-    legacyStopScriptPath
-  );
-  const stopCommand = buildHookCommand(stopScriptPath);
-  const stopCommandWindows = buildCodexWindowsHookCommand(stopScriptPath);
-  hooksFile.hooks.Stop.push({
-    hooks: [{ type: 'command', command: stopCommand, commandWindows: stopCommandWindows, timeout: 10 }]
-  });
-
-  // Confirmed against codex-rs/config/src/hook_config.rs's HookEventsToml serde renames: the
-  // config-file key is PascalCase "UserPromptSubmit", same casing convention as SessionStart/Stop.
-  hooksFile.hooks.UserPromptSubmit = removeEmpiricalHooksJsonEntries(
-    removeEmpiricalHooksJsonEntries(hooksFile.hooks.UserPromptSubmit, userPromptScriptPath),
-    legacyUserPromptScriptPath
-  );
-  const userPromptCommand = buildHookCommand(userPromptScriptPath);
-  const userPromptCommandWindows = buildCodexWindowsHookCommand(userPromptScriptPath);
-  hooksFile.hooks.UserPromptSubmit.push({
-    hooks: [{ type: 'command', command: userPromptCommand, commandWindows: userPromptCommandWindows, timeout: 10 }]
-  });
-
-  writeFile(hooksJsonPath, `${JSON.stringify(hooksFile, null, 2)}\n`);
-  log('  - Codex SessionStart + UserPromptSubmit + Stop hooks installed for deterministic memory lookups and reminders.');
-}
-
-// GitHub Copilot CLI's hook config is one JSON file per hook under ~/.copilot/hooks/ (any
-// filename — confirmed via GitHub's own docs at docs.github.com/en/copilot/reference/hooks-
-// reference), so unlike Claude/Codex this never needs to merge into a shared file: Empirical
-// owns this file outright and can just overwrite it.
-//
-// SessionStart only (2026-09-18): userPromptSubmitted and agentStop reminder hooks were removed
-// for Copilot entirely, not just capped. Both were fundamentally fake compared to Claude/Codex's
-// versions: userPromptSubmitted's only output field is modifiedPrompt (a full prompt replacement,
-// not a side-channel), so its "reminder" was really text injected into what looks like the user's
-// own message; agentStop only supports decision:"block"|"allow" with no passive/silent field, so
-// any reminder there forces a disruptive extra visible turn, and no per-session cap on that can
-// avoid the tradeoff between nagging every turn and going silent right before something worth
-// recording happens (confirmed live 2026-09-17/18: both caused real, reproducible bugs - a
-// prompt-blanking regression and an unstoppable "record your work" loop). Copilot instead relies
-// entirely on the identity-framed instructions block coreMemoryBlock.js writes into
-// copilot-instructions.md, same mechanism Claude/Codex have as a backstop under their working
-// hooks - see that file's Copilot-only addendum for the stronger, more directive wording this
-// puts on Copilot specifically to compensate for having no hook nudge at all.
-function installCopilotHooks(_pluginNames) {
-  const hooksDir = getEmpiricalHooksDir();
-  ensureDir(hooksDir);
-
-  const sessionStartScriptPath = path.join(hooksDir, 'copilot-session-start.js');
-  writeFile(sessionStartScriptPath, COPILOT_HOOK_SESSION_START_SOURCE);
-
-  // Clean up scripts/state files from every removed Copilot hook (agentStop's Stop reminder, the
-  // visible-modifiedPrompt UserPromptSubmit real-recall hook it was briefly replaced with) so an
-  // upgrade never leaves orphaned, unregistered files behind.
-  const fs = require('fs');
-  const staleFiles = [
-    path.join(hooksDir, 'copilot-stop.js'),
-    path.join(hooksDir, 'stop-state.json'),
-    path.join(hooksDir, 'copilot-user-prompt-submit.js'),
-    path.join(hooksDir, 'prompt-state.json')
-  ];
-  for (const stalePath of staleFiles) {
-    try {
-      if (fs.existsSync(stalePath)) fs.unlinkSync(stalePath);
-    } catch (_error) {
-      // best-effort cleanup only
-    }
-  }
-
-  const copilotHooksDir = path.join(os.homedir(), '.copilot', 'hooks');
-  ensureDir(copilotHooksDir);
-
-  // Prior versions of this installer wrote a single-purpose "empirical-session-start.json" —
-  // remove it now that both events live in one unified file, so a stale duplicate registration
-  // never lingers alongside the new one.
-  const legacyHookFilePath = path.join(copilotHooksDir, 'empirical-session-start.json');
-  try {
-    if (fs.existsSync(legacyHookFilePath)) fs.unlinkSync(legacyHookFilePath);
-  } catch (_error) {
-    // best-effort cleanup only
-  }
-
-  const hookFilePath = path.join(copilotHooksDir, 'empirical-hooks.json');
-  // Both `command` (POSIX fallback) and `powershell` (Windows-explicit, with the & call operator
-  // PowerShell requires - see buildPowershellHookCommand) are always set: per GitHub's hooks
-  // reference, an explicit `powershell` entry takes precedence over `command` on Windows, so this
-  // is correct on both platforms without needing to detect the install-time OS here.
-  //
-  // sessionStart only (2026-09-18): no agentStop (recording stays instructions-only, see
-  // coreMemoryBlock.js's Copilot addendum) and no userPromptSubmitted (its only output field,
-  // modifiedPrompt, is rendered back as the user's own visible message - confirmed live, not
-  // acceptable for silent recall). sessionStart's additionalContext delivers the same real query
-  // invisibly instead, once per real session boundary (not an artificial timer), using that
-  // event's own initialPrompt field as the query when present.
-  const hookFileContent = {
-    version: 1,
-    hooks: {
-      sessionStart: [
-        {
-          type: 'command',
-          command: buildHookCommand(sessionStartScriptPath),
-          powershell: buildPowershellHookCommand(sessionStartScriptPath),
-          timeoutSec: 15
-        }
-      ]
-    }
-  };
-
-  writeFile(hookFilePath, `${JSON.stringify(hookFileContent, null, 2)}\n`);
-  log('  - Copilot SessionStart hook installed (real recall via additionalContext). No UserPromptSubmit/agentStop reminders - see copilot-instructions.md instead.');
-}
-
-module.exports = {
-  CLAUDE_HOOK_SESSION_START_SOURCE,
-  CODEX_HOOK_SESSION_START_SOURCE,
-  COPILOT_HOOK_SESSION_START_SOURCE,
-  CODEX_HOOK_STOP_SOURCE,
-  CLAUDE_HOOK_STOP_SOURCE,
-  buildPromptReminderMessage,
-  buildUserPromptSubmitHookSource,
-  getEmpiricalHooksDir,
-  buildHookCommand,
-  buildPowershellHookCommand,
-  removeEmpiricalHookEntries,
-  installClaudeHooks,
-  getCodexHomeDir,
-  removeEmpiricalHooksJsonEntries,
-  getCodexHooksScriptsDir,
-  getWindowsShortPath,
-  buildCodexWindowsHookCommand,
-  installCodexHooks,
-  installCopilotHooks
-};
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const { log } = require('../ui');
+const { ensureDir, writeFile, readJsonIfExists } = require('../fsUtils');
+const { normalizePluginNames } = require('./nativePlugin');
+
+const CLAUDE_HOOK_SESSION_START_SOURCE = `#!/usr/bin/env node
+'use strict';
+
+var spawnSync = require('child_process').spawnSync;
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+
+// Diagnostic breadcrumb log: this hook's own stdout is only visible to Claude Code's SessionStart
+// machinery, not to a human debugging "did this actually fire" after the fact. Every run appends
+// one line here (bounded — see trimLogIfLarge) regardless of success/failure, so firing can be
+// verified by checking file growth/timestamps after starting or resuming a session, without
+// depending on server-side analytics that don't currently tag hook-originated calls.
+var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'session-start.log');
+var MAX_LOG_BYTES = 200 * 1024;
+
+function appendLog(line) {
+  try {
+    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
+    var stat = fs.statSync(LOG_PATH);
+    if (stat.size > MAX_LOG_BYTES) {
+      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
+      fs.writeFileSync(LOG_PATH, tail);
+    }
+  } catch (e) {
+    // Diagnostics must never break session start.
+  }
+}
+
+// On Windows, npm's global "empirical" command is a .cmd shim, and .cmd/.bat files can only be
+// executed via the OS shell (cmd.exe), never as a native process — this is an OS constraint, not
+// a Node quirk. But spawnSync's shell:true path joins argv into a single command-line string for
+// cmd.exe to reparse, and Node does not escape special shell characters (spaces, commas, etc.) in
+// that join for you. A --match value like "project context, conventions, recent decisions, user
+// preferences" gets mangled by that reparse, silently truncating the search query and returning
+// far fewer/worse matches than the same query run without a shell in between. The fix: resolve
+// the shim's REAL target (a plain .js file) and invoke that directly via node.exe with shell:false
+// — node.exe is a true native executable, so no shell/reparsing step exists to mangle args.
+function resolveEmpiricalEntryPoint() {
+  if (process.platform !== 'win32') {
+    // POSIX global installs are usually a symlink straight to the JS entry (or a shebang script)
+    // — spawnSync already runs these directly without a shell, so no mangling risk exists there.
+    return null;
+  }
+  try {
+    // Parse the .cmd shim itself rather than hardcoding an npm package scope: the published
+    // package has already been renamed once (was the empirical scope, now a different scope
+    // entirely - the old one is 404 on the registry), so hardcoding either name is a guaranteed
+    // future break. npm-generated shims all reference their target relative to dp0 (the shim's
+    // own directory) as a node_modules-rooted path ending in bin then a .js file - extracting
+    // that pattern works regardless of what the package is scoped or renamed to.
+    var where = spawnSync('where', ['empirical.cmd'], { encoding: 'utf8', timeout: 5000, shell: true });
+    if (where.status !== 0 || !where.stdout) return null;
+    var cmdPath = where.stdout.split(/\\r?\\n/).map(function (s) { return s.trim(); }).filter(Boolean)[0];
+    if (!cmdPath || !fs.existsSync(cmdPath)) return null;
+    var cmdContent = fs.readFileSync(cmdPath, 'utf8');
+    var match = cmdContent.match(/"%dp0%\\\\(node_modules\\\\.+?\\.js)"/);
+    if (!match) return null;
+    var candidate = path.join(path.dirname(cmdPath), match[1]);
+    return fs.existsSync(candidate) ? candidate : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+function commandExists(cmd) {
+  var probe = process.platform === 'win32'
+    ? spawnSync('where', [cmd], { stdio: 'ignore', shell: true })
+    : spawnSync('which', [cmd], { stdio: 'ignore' });
+  return probe.status === 0;
+}
+
+function runMemoryQuery(args) {
+  var entryPoint = resolveEmpiricalEntryPoint();
+  if (entryPoint) {
+    appendLog('resolved direct entry point: ' + entryPoint);
+    return spawnSync(process.execPath, [entryPoint].concat(args), {
+      encoding: 'utf8',
+      // Must stay under the host manifest cap for this event (25s). Recall is chronically 2-7s
+      // and the old 10s here killed the query silently while the host still had 15s to spare.
+      timeout: 20000,
+      shell: false
+    });
+  }
+
+  // Fallback: could not resolve a direct entry point (non-Windows, or resolution failed) — run
+  // the "empirical" command as before. On POSIX this is shell:false and safe. On Windows this is
+  // shell:true and CAN still mangle args as described above; it only triggers if the direct-entry
+  // resolution above failed, so degraded (not absent) results are the acceptable worst case here.
+  appendLog('direct entry point not resolved, falling back to shell invocation (shell=' + (process.platform === 'win32') + ')');
+  return spawnSync('empirical', args, {
+    encoding: 'utf8',
+    timeout: 20000,
+    shell: process.platform === 'win32'
+  });
+}
+
+function main() {
+  appendLog('hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
+
+  if (!commandExists('empirical')) {
+    appendLog('empirical CLI not found on PATH, exiting');
+    process.exit(0);
+  }
+
+  // Declared inside main() on purpose: function declarations hoist, and other hook templates in
+  // this file have their own main() without the memory-query plumbing.
+
+  // WHAT PROJECT IS THIS, in priority order. Guessing from the directory name is the last resort,
+  // not the contract: a repo folder is not always what the corpus tags memories with.
+  //   1. EMPIRICAL_PROJECT_TAG / EMPIRICAL_TOPICS environment variables
+  //   2. .empirical.json in the working directory or any ancestor, up to 6 levels:
+  //        { "project": "empirical_v2", "topics": ["search ranking", "deploy"] }
+  //   3. the working directory name, lowercased
+  function readProjectConfig() {
+    var config = { project: '', topics: [] };
+    try {
+      var dir = process.cwd();
+      for (var depth = 0; depth < 6; depth += 1) {
+        var candidate = path.join(dir, '.empirical.json');
+        if (fs.existsSync(candidate)) {
+          var parsed = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+          config.project = String(parsed && parsed.project ? parsed.project : '').trim().toLowerCase();
+          if (parsed && Array.isArray(parsed.topics)) {
+            config.topics = parsed.topics.map(function (t) { return String(t || '').trim(); }).filter(Boolean);
+          }
+          appendLog('loaded project config from ' + candidate);
+          return config;
+        }
+        var parent = path.dirname(dir);
+        if (!parent || parent === dir) { break; }
+        dir = parent;
+      }
+    } catch (e) {
+      appendLog('project config unreadable, continuing without it: ' + e.message);
+    }
+    return config;
+  }
+
+  // requireAll selects --tags-all (AND) over --tags (OR). This matters: --tags is an OR match, so
+  // asking for 'empirical_v2,todo' returns every project's todos, which put a wellnessonbalance
+  // item into an empirical_v2 session during testing on 2026-09-16.
+  function fetchMemories(matchText, tags, topK, requireAll) {
+    var args = ['memory', 'query', '--match', matchText, '--top-k', String(topK)];
+    if (tags) { args.push(requireAll ? '--tags-all' : '--tags', tags); }
+    var queryResult = runMemoryQuery(args);
+    if (!queryResult || queryResult.status !== 0 || !queryResult.stdout) {
+      appendLog('memory query failed (tags=' + (tags || 'none') + ', status=' + (queryResult && queryResult.status) + ', stderr=' + (queryResult && queryResult.stderr ? String(queryResult.stderr).slice(0, 200) : '') + ')');
+      return [];
+    }
+    try {
+      var parsed = JSON.parse(queryResult.stdout);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch (e) {
+      appendLog('failed to parse memory query stdout as JSON: ' + e.message);
+      return [];
+    }
+  }
+
+  var fileConfig = readProjectConfig();
+  var envTag = String(process.env.EMPIRICAL_PROJECT_TAG || '').trim().toLowerCase();
+  var envTopics = String(process.env.EMPIRICAL_TOPICS || '').split(',').map(function (t) { return t.trim(); }).filter(Boolean);
+
+  var tag = envTag || fileConfig.project;
+  var tagSource = envTag ? 'env' : (fileConfig.project ? 'config' : 'cwd');
+  if (!tag) {
+    try {
+      tag = String(path.basename(process.cwd() || '') || '').trim().toLowerCase();
+    } catch (e) {
+      tag = '';
+    }
+  }
+
+  var topics = envTopics.length ? envTopics : fileConfig.topics;
+  var contextMatch = topics.length
+    ? topics.join(', ')
+    : 'project context, conventions, recent decisions, user preferences';
+
+  appendLog('project tag=' + (tag || '(none)') + ' (source=' + tagSource + '), topics=' + (topics.length ? topics.join('|') : '(default)'));
+
+  // Scope every query to the project. Measured 2026-09-16: with no tag filter all 8 slots went to
+  // one unrelated project during a full session in a different repo, so the only automatic context
+  // rail in the product was spending every slot on the wrong thing. A tag filter also disables the
+  // server's agent-process-note exclusion, which is what makes a project's own scar tissue and
+  // work history reachable here at all.
+  //
+  // Open items get their OWN query instead of competing for rank. Tested 2026-09-16: a due-dated
+  // memory did not surface in the generic top-8 with or without a project filter, because dueness
+  // is not a semantic property. Anything that must be seen needs a reserved slot.
+  // AND, not OR: this must be THIS project's todos. No --status filter on purpose, because todos
+  // written without a data.status would silently vanish from the one place they get surfaced;
+  // the label tells the reader to confirm instead.
+  var todos = tag ? fetchMemories('open todo, next action, follow-up, due', tag + ',todo', 3, true) : [];
+  var context = tag ? fetchMemories(contextMatch, tag, 6) : [];
+
+  // A corpus whose tags do not match the resolved project must never end up worse off than before
+  // this change, so fall back to the original unscoped query.
+  if (context.length === 0) {
+    appendLog('project-scoped query returned nothing, falling back to unscoped');
+    context = fetchMemories(contextMatch, '', 8);
+  }
+
+  if (todos.length === 0 && context.length === 0) {
+    appendLog('memory query returned zero results');
+    process.exit(0);
+  }
+
+  var openCount = todos.length;
+  var results = todos.concat(context);
+
+  appendLog('memory query returned ' + results.length + ' result(s), injecting into session context');
+
+  // Summaries in a mature corpus run to thousands of characters. Injecting eight in full is a wall
+  // of text that gets skimmed past, which fails the same way as never injecting them at all:
+  // presence in context is not attention. Truncate hard; the agent can query for the rest.
+  var lines = results.slice(0, 9).map(function (r, i) {
+    var category = r && r.category ? r.category : 'memory';
+    var summary = String(r && r.summary ? r.summary : '');
+    summary = summary.split('\\n').join(' ').split('\\r').join(' ').split('\\t').join(' ').trim();
+    if (summary.length > 240) { summary = summary.slice(0, 237) + '...'; }
+    var prefix = i < openCount ? '- [OPEN ITEM, confirm status] ' : '- [' + category + '] ';
+    return prefix + summary;
+  });
+  lines.push('- Before risky or repeated work, ask first: empirical memory query --match "<what you are about to do>" --tags scar-tissue');
+
+  console.log('Empirical memory context for this session:\\n' + lines.join('\\n'));
+  process.exit(0);
+}
+
+// Hooks must never surface as a hard failure to the host CLI (Codex/Claude/Copilot all render a
+// nonzero exit as a red "hook failed" error) - an uncaught exception anywhere above (e.g. an
+// environment that denies process spawn or fs access, such as Codex's experimental Windows
+// sandbox) must degrade to a silent no-op, not a visible crash.
+try {
+  main();
+} catch (e) {
+  try { appendLog('uncaught error in main(): ' + (e && e.message)); } catch (_e) { /* best effort */ }
+  process.exit(0);
+}
+`;
+
+// Codex-only variant of the SessionStart hook above. Confirmed live (2026-08-08, via a real
+// `codex exec` run) that Codex requires valid JSON on stdout for a hook's output to actually
+// register/display - plain text (what CLAUDE_HOOK_SESSION_START_SOURCE emits, which Claude Code
+// handles fine) makes Codex report the hook as failed. Uses the same hookSpecificOutput.
+// additionalContext shape Claude's own JSON-output hooks use (see CLAUDE_HOOK_STOP_SOURCE below) -
+// confirmed accepted by Codex's SessionStart handler specifically. Otherwise byte-identical to
+// CLAUDE_HOOK_SESSION_START_SOURCE; keep any future logic changes in sync between the two.
+const CODEX_HOOK_SESSION_START_SOURCE = `#!/usr/bin/env node
+'use strict';
+
+var spawnSync = require('child_process').spawnSync;
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+
+var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'session-start.log');
+var MAX_LOG_BYTES = 200 * 1024;
+
+function appendLog(line) {
+  try {
+    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
+    var stat = fs.statSync(LOG_PATH);
+    if (stat.size > MAX_LOG_BYTES) {
+      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
+      fs.writeFileSync(LOG_PATH, tail);
+    }
+  } catch (e) {
+    // Diagnostics must never break session start.
+  }
+}
+
+function resolveEmpiricalEntryPoint() {
+  if (process.platform !== 'win32') {
+    return null;
+  }
+  try {
+    var where = spawnSync('where', ['empirical.cmd'], { encoding: 'utf8', timeout: 5000, shell: true });
+    if (where.status !== 0 || !where.stdout) return null;
+    var cmdPath = where.stdout.split(/\\r?\\n/).map(function (s) { return s.trim(); }).filter(Boolean)[0];
+    if (!cmdPath || !fs.existsSync(cmdPath)) return null;
+    var cmdContent = fs.readFileSync(cmdPath, 'utf8');
+    var match = cmdContent.match(/"%dp0%\\\\(node_modules\\\\.+?\\.js)"/);
+    if (!match) return null;
+    var candidate = path.join(path.dirname(cmdPath), match[1]);
+    return fs.existsSync(candidate) ? candidate : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+function commandExists(cmd) {
+  var probe = process.platform === 'win32'
+    ? spawnSync('where', [cmd], { stdio: 'ignore', shell: true })
+    : spawnSync('which', [cmd], { stdio: 'ignore' });
+  return probe.status === 0;
+}
+
+function runMemoryQuery(args) {
+  var entryPoint = resolveEmpiricalEntryPoint();
+  if (entryPoint) {
+    appendLog('resolved direct entry point: ' + entryPoint);
+    return spawnSync(process.execPath, [entryPoint].concat(args), {
+      encoding: 'utf8',
+      // Must stay under the host manifest cap for this event (25s). Recall is chronically 2-7s
+      // and the old 10s here killed the query silently while the host still had 15s to spare.
+      timeout: 20000,
+      shell: false
+    });
+  }
+
+  appendLog('direct entry point not resolved, falling back to shell invocation (shell=' + (process.platform === 'win32') + ')');
+  return spawnSync('empirical', args, {
+    encoding: 'utf8',
+    timeout: 20000,
+    shell: process.platform === 'win32'
+  });
+}
+
+// Codex requires VALID JSON on stdout for every hook run. Emitting nothing is as broken as
+// emitting plain text: both surface to the user as "SessionStart hook (failed)". Every early
+// return below is a legitimate "no memory context to add" outcome (CLI missing, offline,
+// expired token, zero results), so each one now emits a well-formed envelope with an empty
+// context instead of exiting silently. Found 2026-09-09: with the API unreachable this hook
+// printed nothing at all and exited 0.
+function emitContext(context) {
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: context || ''
+    }
+  }));
+}
+
+function main() {
+  appendLog('hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
+
+  if (!commandExists('empirical')) {
+    appendLog('empirical CLI not found on PATH, exiting');
+    emitContext('');
+    process.exit(0);
+  }
+
+  // Declared inside main() on purpose: function declarations hoist, and other hook templates in
+  // this file have their own main() without the memory-query plumbing.
+
+  // WHAT PROJECT IS THIS, in priority order. Guessing from the directory name is the last resort,
+  // not the contract: a repo folder is not always what the corpus tags memories with.
+  //   1. EMPIRICAL_PROJECT_TAG / EMPIRICAL_TOPICS environment variables
+  //   2. .empirical.json in the working directory or any ancestor, up to 6 levels:
+  //        { "project": "empirical_v2", "topics": ["search ranking", "deploy"] }
+  //   3. the working directory name, lowercased
+  function readProjectConfig() {
+    var config = { project: '', topics: [] };
+    try {
+      var dir = process.cwd();
+      for (var depth = 0; depth < 6; depth += 1) {
+        var candidate = path.join(dir, '.empirical.json');
+        if (fs.existsSync(candidate)) {
+          var parsed = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+          config.project = String(parsed && parsed.project ? parsed.project : '').trim().toLowerCase();
+          if (parsed && Array.isArray(parsed.topics)) {
+            config.topics = parsed.topics.map(function (t) { return String(t || '').trim(); }).filter(Boolean);
+          }
+          appendLog('loaded project config from ' + candidate);
+          return config;
+        }
+        var parent = path.dirname(dir);
+        if (!parent || parent === dir) { break; }
+        dir = parent;
+      }
+    } catch (e) {
+      appendLog('project config unreadable, continuing without it: ' + e.message);
+    }
+    return config;
+  }
+
+  // requireAll selects --tags-all (AND) over --tags (OR). This matters: --tags is an OR match, so
+  // asking for 'empirical_v2,todo' returns every project's todos, which put a wellnessonbalance
+  // item into an empirical_v2 session during testing on 2026-09-16.
+  function fetchMemories(matchText, tags, topK, requireAll) {
+    var args = ['memory', 'query', '--match', matchText, '--top-k', String(topK)];
+    if (tags) { args.push(requireAll ? '--tags-all' : '--tags', tags); }
+    var queryResult = runMemoryQuery(args);
+    if (!queryResult || queryResult.status !== 0 || !queryResult.stdout) {
+      appendLog('memory query failed (tags=' + (tags || 'none') + ', status=' + (queryResult && queryResult.status) + ', stderr=' + (queryResult && queryResult.stderr ? String(queryResult.stderr).slice(0, 200) : '') + ')');
+      return [];
+    }
+    try {
+      var parsed = JSON.parse(queryResult.stdout);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch (e) {
+      appendLog('failed to parse memory query stdout as JSON: ' + e.message);
+      return [];
+    }
+  }
+
+  var fileConfig = readProjectConfig();
+  var envTag = String(process.env.EMPIRICAL_PROJECT_TAG || '').trim().toLowerCase();
+  var envTopics = String(process.env.EMPIRICAL_TOPICS || '').split(',').map(function (t) { return t.trim(); }).filter(Boolean);
+
+  var tag = envTag || fileConfig.project;
+  var tagSource = envTag ? 'env' : (fileConfig.project ? 'config' : 'cwd');
+  if (!tag) {
+    try {
+      tag = String(path.basename(process.cwd() || '') || '').trim().toLowerCase();
+    } catch (e) {
+      tag = '';
+    }
+  }
+
+  var topics = envTopics.length ? envTopics : fileConfig.topics;
+  var contextMatch = topics.length
+    ? topics.join(', ')
+    : 'project context, conventions, recent decisions, user preferences';
+
+  appendLog('project tag=' + (tag || '(none)') + ' (source=' + tagSource + '), topics=' + (topics.length ? topics.join('|') : '(default)'));
+
+  // Scope every query to the project. Measured 2026-09-16: with no tag filter all 8 slots went to
+  // one unrelated project during a full session in a different repo, so the only automatic context
+  // rail in the product was spending every slot on the wrong thing. A tag filter also disables the
+  // server's agent-process-note exclusion, which is what makes a project's own scar tissue and
+  // work history reachable here at all.
+  //
+  // Open items get their OWN query instead of competing for rank. Tested 2026-09-16: a due-dated
+  // memory did not surface in the generic top-8 with or without a project filter, because dueness
+  // is not a semantic property. Anything that must be seen needs a reserved slot.
+  // AND, not OR: this must be THIS project's todos. No --status filter on purpose, because todos
+  // written without a data.status would silently vanish from the one place they get surfaced;
+  // the label tells the reader to confirm instead.
+  var todos = tag ? fetchMemories('open todo, next action, follow-up, due', tag + ',todo', 3, true) : [];
+  var context = tag ? fetchMemories(contextMatch, tag, 6) : [];
+
+  // A corpus whose tags do not match the resolved project must never end up worse off than before
+  // this change, so fall back to the original unscoped query.
+  if (context.length === 0) {
+    appendLog('project-scoped query returned nothing, falling back to unscoped');
+    context = fetchMemories(contextMatch, '', 8);
+  }
+
+  if (todos.length === 0 && context.length === 0) {
+    appendLog('memory query returned zero results');
+    emitContext('');
+    process.exit(0);
+  }
+
+  var openCount = todos.length;
+  var results = todos.concat(context);
+
+  appendLog('memory query returned ' + results.length + ' result(s), injecting into session context');
+
+  // Summaries in a mature corpus run to thousands of characters. Injecting eight in full is a wall
+  // of text that gets skimmed past, which fails the same way as never injecting them at all:
+  // presence in context is not attention. Truncate hard; the agent can query for the rest.
+  var lines = results.slice(0, 9).map(function (r, i) {
+    var category = r && r.category ? r.category : 'memory';
+    var summary = String(r && r.summary ? r.summary : '');
+    summary = summary.split('\\n').join(' ').split('\\r').join(' ').split('\\t').join(' ').trim();
+    if (summary.length > 240) { summary = summary.slice(0, 237) + '...'; }
+    var prefix = i < openCount ? '- [OPEN ITEM, confirm status] ' : '- [' + category + '] ';
+    return prefix + summary;
+  });
+  lines.push('- Before risky or repeated work, ask first: empirical memory query --match "<what you are about to do>" --tags scar-tissue');
+
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: 'Empirical memory context for this session:\\n' + lines.join('\\n')
+    }
+  }));
+  process.exit(0);
+}
+
+try {
+  main();
+} catch (e) {
+  try { appendLog('uncaught error in main(): ' + (e && e.message)); } catch (_e) { /* best effort */ }
+  try { emitContext(''); } catch (_e2) { /* stdout already unusable */ }
+  process.exit(0);
+}
+`;
+
+// Copilot-only variant of the SessionStart hook. Per GitHub's own hooks reference (fetched
+// 2026-08-08): unlike Claude/Codex, Copilot's sessionStart event has NO output mechanism at all
+// - there is no additionalContext-equivalent field, so a hook cannot inject memory context into
+// the session this way, full stop (this is a genuine platform limitation, not a bug to work
+// around). Separately, Copilot requires ALL hook stdout to be valid JSON parsed via a single
+// JSON.parse call - plain text (fine for Claude, and previously assumed fine here too) is
+// invalid and makes Copilot log a hook execution failure. So this variant still runs the memory
+// query and logs the result for diagnostic/audit purposes, but emits {} (empty, valid JSON,
+// explicitly documented as "use defaults") instead of attempting to inject anything.
+const COPILOT_HOOK_SESSION_START_SOURCE = `#!/usr/bin/env node
+'use strict';
+
+var spawnSync = require('child_process').spawnSync;
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+
+var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'session-start.log');
+var MAX_LOG_BYTES = 200 * 1024;
+
+function appendLog(line) {
+  try {
+    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
+    var stat = fs.statSync(LOG_PATH);
+    if (stat.size > MAX_LOG_BYTES) {
+      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
+      fs.writeFileSync(LOG_PATH, tail);
+    }
+  } catch (e) {
+    // Diagnostics must never break session start.
+  }
+}
+
+function resolveEmpiricalEntryPoint() {
+  if (process.platform !== 'win32') {
+    return null;
+  }
+  try {
+    var where = spawnSync('where', ['empirical.cmd'], { encoding: 'utf8', timeout: 5000, shell: true });
+    if (where.status !== 0 || !where.stdout) return null;
+    var cmdPath = where.stdout.split(/\\r?\\n/).map(function (s) { return s.trim(); }).filter(Boolean)[0];
+    if (!cmdPath || !fs.existsSync(cmdPath)) return null;
+    var cmdContent = fs.readFileSync(cmdPath, 'utf8');
+    var match = cmdContent.match(/"%dp0%\\\\(node_modules\\\\.+?\\.js)"/);
+    if (!match) return null;
+    var candidate = path.join(path.dirname(cmdPath), match[1]);
+    return fs.existsSync(candidate) ? candidate : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+function commandExists(cmd) {
+  var probe = process.platform === 'win32'
+    ? spawnSync('where', [cmd], { stdio: 'ignore', shell: true })
+    : spawnSync('which', [cmd], { stdio: 'ignore' });
+  return probe.status === 0;
+}
+
+function runMemoryQuery(args) {
+  var entryPoint = resolveEmpiricalEntryPoint();
+  if (entryPoint) {
+    appendLog('resolved direct entry point: ' + entryPoint);
+    return spawnSync(process.execPath, [entryPoint].concat(args), {
+      encoding: 'utf8',
+      // Must stay under the host manifest cap for this event (25s). Recall is chronically 2-7s
+      // and the old 10s here killed the query silently while the host still had 15s to spare.
+      timeout: 20000,
+      shell: false
+    });
+  }
+
+  appendLog('direct entry point not resolved, falling back to shell invocation (shell=' + (process.platform === 'win32') + ')');
+  return spawnSync('empirical', args, {
+    encoding: 'utf8',
+    timeout: 20000,
+    shell: process.platform === 'win32'
+  });
+}
+
+// 2026-09-18: GitHub's own hooks reference (re-checked - the August 2026 check this file used to
+// cite was stale) confirms sessionStart CAN inject additionalContext for command-type hooks, same
+// flat { additionalContext: "..." } shape postToolUse etc. use. This event's input payload also
+// carries an optional initialPrompt - using it as the query (like the removed UserPromptSubmit
+// hook did for its own prompt) makes the one real query relevant to what's actually being asked,
+// not just a generic default.
+function readStdinPayload() {
+  try {
+    var raw = fs.readFileSync(0, 'utf8');
+    return raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    return {};
+  }
+}
+
+function main() {
+  appendLog('hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
+  var payload = readStdinPayload();
+  var initialPrompt = String((payload && (payload.initialPrompt || payload.initial_prompt)) || '').trim();
+
+  if (!commandExists('empirical')) {
+    appendLog('empirical CLI not found on PATH, exiting');
+    console.log('{}');
+    process.exit(0);
+  }
+
+  // Declared inside main() on purpose: function declarations hoist, and other hook templates in
+  // this file have their own main() without the memory-query plumbing.
+
+  // WHAT PROJECT IS THIS, in priority order. Guessing from the directory name is the last resort,
+  // not the contract: a repo folder is not always what the corpus tags memories with.
+  //   1. EMPIRICAL_PROJECT_TAG / EMPIRICAL_TOPICS environment variables
+  //   2. .empirical.json in the working directory or any ancestor, up to 6 levels:
+  //        { "project": "empirical_v2", "topics": ["search ranking", "deploy"] }
+  //   3. the working directory name, lowercased
+  function readProjectConfig() {
+    var config = { project: '', topics: [] };
+    try {
+      var dir = process.cwd();
+      for (var depth = 0; depth < 6; depth += 1) {
+        var candidate = path.join(dir, '.empirical.json');
+        if (fs.existsSync(candidate)) {
+          var parsed = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+          config.project = String(parsed && parsed.project ? parsed.project : '').trim().toLowerCase();
+          if (parsed && Array.isArray(parsed.topics)) {
+            config.topics = parsed.topics.map(function (t) { return String(t || '').trim(); }).filter(Boolean);
+          }
+          appendLog('loaded project config from ' + candidate);
+          return config;
+        }
+        var parent = path.dirname(dir);
+        if (!parent || parent === dir) { break; }
+        dir = parent;
+      }
+    } catch (e) {
+      appendLog('project config unreadable, continuing without it: ' + e.message);
+    }
+    return config;
+  }
+
+  // requireAll selects --tags-all (AND) over --tags (OR). This matters: --tags is an OR match, so
+  // asking for 'empirical_v2,todo' returns every project's todos, which put a wellnessonbalance
+  // item into an empirical_v2 session during testing on 2026-09-16.
+  function fetchMemories(matchText, tags, topK, requireAll) {
+    var args = ['memory', 'query', '--match', matchText, '--top-k', String(topK)];
+    if (tags) { args.push(requireAll ? '--tags-all' : '--tags', tags); }
+    var queryResult = runMemoryQuery(args);
+    if (!queryResult || queryResult.status !== 0 || !queryResult.stdout) {
+      appendLog('memory query failed (tags=' + (tags || 'none') + ', status=' + (queryResult && queryResult.status) + ', stderr=' + (queryResult && queryResult.stderr ? String(queryResult.stderr).slice(0, 200) : '') + ')');
+      return [];
+    }
+    try {
+      var parsed = JSON.parse(queryResult.stdout);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch (e) {
+      appendLog('failed to parse memory query stdout as JSON: ' + e.message);
+      return [];
+    }
+  }
+
+  var fileConfig = readProjectConfig();
+  var envTag = String(process.env.EMPIRICAL_PROJECT_TAG || '').trim().toLowerCase();
+  var envTopics = String(process.env.EMPIRICAL_TOPICS || '').split(',').map(function (t) { return t.trim(); }).filter(Boolean);
+
+  var tag = envTag || fileConfig.project;
+  var tagSource = envTag ? 'env' : (fileConfig.project ? 'config' : 'cwd');
+  if (!tag) {
+    try {
+      tag = String(path.basename(process.cwd() || '') || '').trim().toLowerCase();
+    } catch (e) {
+      tag = '';
+    }
+  }
+
+  var topics = envTopics.length ? envTopics : fileConfig.topics;
+  var contextMatch = topics.length
+    ? topics.join(', ')
+    : (initialPrompt || 'project context, conventions, recent decisions, user preferences');
+
+  appendLog('project tag=' + (tag || '(none)') + ' (source=' + tagSource + '), topics=' + (topics.length ? topics.join('|') : '(default)') + ', usingInitialPrompt=' + Boolean(initialPrompt && !topics.length));
+
+  // Scope every query to the project. Measured 2026-09-16: with no tag filter all 8 slots went to
+  // one unrelated project during a full session in a different repo, so the only automatic context
+  // rail in the product was spending every slot on the wrong thing. A tag filter also disables the
+  // server's agent-process-note exclusion, which is what makes a project's own scar tissue and
+  // work history reachable here at all.
+  //
+  // Open items get their OWN query instead of competing for rank. Tested 2026-09-16: a due-dated
+  // memory did not surface in the generic top-8 with or without a project filter, because dueness
+  // is not a semantic property. Anything that must be seen needs a reserved slot.
+  // AND, not OR: this must be THIS project's todos. No --status filter on purpose, because todos
+  // written without a data.status would silently vanish from the one place they get surfaced;
+  // the label tells the reader to confirm instead.
+  var todos = tag ? fetchMemories('open todo, next action, follow-up, due', tag + ',todo', 3, true) : [];
+  var context = tag ? fetchMemories(contextMatch, tag, 6) : [];
+
+  // A corpus whose tags do not match the resolved project must never end up worse off than before
+  // this change, so fall back to the original unscoped query.
+  if (context.length === 0) {
+    appendLog('project-scoped query returned nothing, falling back to unscoped');
+    context = fetchMemories(contextMatch, '', 8);
+  }
+
+  if (todos.length === 0 && context.length === 0) {
+    appendLog('memory query returned zero results');
+    console.log('{}');
+    process.exit(0);
+  }
+
+  var openCount = todos.length;
+  var results = todos.concat(context);
+
+  // Summaries in a mature corpus run to thousands of characters. Injecting eight in full is a wall
+  // of text that gets skimmed past, which fails the same way as never injecting them at all:
+  // presence in context is not attention. Truncate hard; the agent can query for the rest.
+  var lines = results.slice(0, 9).map(function (r, i) {
+    var category = r && r.category ? r.category : 'memory';
+    var summary = String(r && r.summary ? r.summary : '');
+    summary = summary.split('\\n').join(' ').split('\\r').join(' ').split('\\t').join(' ').trim();
+    if (summary.length > 240) { summary = summary.slice(0, 237) + '...'; }
+    var prefix = i < openCount ? '- [OPEN ITEM, confirm status] ' : '- [' + category + '] ';
+    return prefix + summary;
+  });
+  lines.push('- Before risky or repeated work, ask first: empirical memory query --match "<what you are about to do>" --tags scar-tissue');
+
+  // additionalContext is honored for command-type sessionStart hooks (re-confirmed 2026-09-18
+  // against GitHub's current hooks reference - the prior "no output channel" comment here was
+  // stale). Delivered invisibly: this never touches the visible prompt, unlike the UserPromptSubmit
+  // approach it replaces (removed - see installCopilotHooks's comment).
+  var block = 'Empirical memory context for this session:\\n' + lines.join('\\n');
+  appendLog('memory query returned ' + results.length + ' result(s), injecting via additionalContext');
+  console.log(JSON.stringify({ additionalContext: block }));
+  process.exit(0);
+}
+
+try {
+  main();
+} catch (e) {
+  try { appendLog('uncaught error in main(): ' + (e && e.message)); } catch (_e) { /* best effort */ }
+  console.log('{}');
+  process.exit(0);
+}
+`;
+
+// Copilot has no UserPromptSubmit real-recall hook (removed 2026-09-18, superseded by
+// additionalContext delivery through COPILOT_HOOK_SESSION_START_SOURCE above). That approach was
+// abandoned because Copilot renders the ENTIRE modifiedPrompt back in the terminal as the user's
+// own visible message - confirmed live, not documented, and not what "real hook" was supposed to
+// mean. sessionStart's additionalContext (re-confirmed against current GitHub docs - the prior
+// "no output channel" comment on that hook was stale) delivers the same real query invisibly
+// instead, at the cost of firing once per real session rather than being keyed to the very first
+// prompt's exact text (it uses the sessionStart payload's own initialPrompt field instead, which
+// is present per GitHub's schema but not verified live as of this comment).
+
+// Codex-only variant of the Stop reminder. Confirmed live (2026-08-08, via a real `codex
+// exec` run) that Codex's Stop hook specifically requires a { systemMessage: "..." } JSON shape
+// on stdout - plain text makes Codex report the hook as failed. Distinct from Claude's own JSON
+// shape (hookSpecificOutput.additionalContext, see CLAUDE_HOOK_STOP_SOURCE below). Copilot has no
+// Stop hook at all (removed 2026-09-18, see the comment above CLAUDE_HOOK_STOP_SOURCE).
+const CODEX_HOOK_STOP_SOURCE = `#!/usr/bin/env node
+'use strict';
+
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+
+var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'stop.log');
+var MAX_LOG_BYTES = 200 * 1024;
+
+function appendLog(line) {
+  try {
+    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
+    var stat = fs.statSync(LOG_PATH);
+    if (stat.size > MAX_LOG_BYTES) {
+      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
+      fs.writeFileSync(LOG_PATH, tail);
+    }
+  } catch (e) {
+    // Diagnostics must never break the hook.
+  }
+}
+
+function readStdinPayload() {
+  try {
+    var raw = fs.readFileSync(0, 'utf8');
+    return raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    return {};
+  }
+}
+
+function main() {
+  var payload = readStdinPayload();
+
+  if (payload && payload.stop_hook_active === true) {
+    appendLog('stop_hook_active=true, skipping reminder');
+    process.exit(0);
+  }
+
+  appendLog('stop hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
+
+  console.log(JSON.stringify({
+    systemMessage: '[Empirical reminder] Before finishing: if this turn included a completed decision, a corrected mistake, or meaningful work worth remembering, record it now, one memory per finding (a fix, a root cause, a decision, a lesson), via the empirical-memory, empirical-work-history, or empirical-scar-tissue skill or \`empirical memory record\`. Local notes are not recorded. Do not wait to be asked.'
+  }));
+  process.exit(0);
+}
+
+try {
+  main();
+} catch (e) {
+  try { appendLog('uncaught error in main(): ' + (e && e.message)); } catch (_e) { /* best effort */ }
+  process.exit(0);
+}
+`;
+
+// Copilot's Stop reminder (agentStop) was removed entirely 2026-09-18 - see installCopilotHooks's
+// comment in this file for why (agentStop only supports decision:"block"|"allow" with no passive
+// field, so any reminder there forces a disruptive extra visible turn; no per-session cap on that
+// avoids the tradeoff between nagging every turn and going silent right before something worth
+// recording happens - confirmed live 2026-09-17/18 causing both failure modes in turn). Copilot
+// relies entirely on copilot-instructions.md instead (see coreMemoryBlock.js's Copilot addendum).
+
+// Claude-only variant of the Stop reminder above. hookSpecificOutput.additionalContext (stdout,
+// exit 0) is Claude Code's non-blocking Stop-hook feedback channel: the text is fed into context
+// and the conversation continues, same outcome the earlier exit-2 approach achieved, but the
+// transcript UI renders it as a plain system reminder instead of a red "Stop hook error" line.
+// Codex needs its own systemMessage shape (CODEX_HOOK_STOP_SOURCE) - plain console.log output
+// (what this hook used before the additionalContext fix) never reaches the model. Copilot has no
+// Stop hook at all (removed 2026-09-18, see the comment just above this one).
+const CLAUDE_HOOK_STOP_SOURCE = `#!/usr/bin/env node
+'use strict';
+
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+
+var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'stop.log');
+var MAX_LOG_BYTES = 200 * 1024;
+
+function appendLog(line) {
+  try {
+    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
+    var stat = fs.statSync(LOG_PATH);
+    if (stat.size > MAX_LOG_BYTES) {
+      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
+      fs.writeFileSync(LOG_PATH, tail);
+    }
+  } catch (e) {
+    // Diagnostics must never break the hook.
+  }
+}
+
+function readStdinPayload() {
+  try {
+    var raw = fs.readFileSync(0, 'utf8');
+    return raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    return {};
+  }
+}
+
+function main() {
+  var payload = readStdinPayload();
+
+  // stop_hook_active === true means Claude is re-invoking this hook because a PRIOR Stop hook
+  // (possibly this same one) already surfaced additionalContext and forced a continuation this
+  // turn. additionalContext causes the same forced-continuation behavior decision:block does -
+  // confirmed empirically: without this guard the hook re-fired every ~2-3s in an infinite loop,
+  // since each additionalContext output triggers another Stop event. Must exit 0 with no output
+  // here, unconditionally, or the loop continues.
+  if (payload && payload.stop_hook_active === true) {
+    appendLog('stop_hook_active=true, skipping reminder (already surfaced once this turn)');
+    process.exit(0);
+  }
+
+  appendLog('stop hook fired (pid=' + process.pid + ', platform=' + process.platform + '), surfacing reminder via additionalContext');
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'Stop',
+      additionalContext: '[Empirical] Record memory-worthy work now: one memory per finding (a fix, a root cause, a decision, a lesson) via the empirical-memory, empirical-work-history, or empirical-scar-tissue skill. Local notes are not recorded.'
+    }
+  }) + '\\n');
+  process.exit(0);
+}
+
+// See EMPIRICAL_HOOK_SESSION_START_SOURCE's identical guard: a crash here must degrade to a
+// silent no-op, never a visible "hook failed" error in the host CLI.
+try {
+  main();
+} catch (e) {
+  try { appendLog('uncaught error in main(): ' + (e && e.message)); } catch (_e) { /* best effort */ }
+  process.exit(0);
+}
+`;
+
+// UserPromptSubmit: fires before each turn is processed (Claude, Codex, and Copilot all support
+// this event under the same name per each platform's docs/source). This is the recall-side
+// counterpart to Stop's write-side reminder - deliberately a STATIC message, not a live
+// `empirical memory query` call: a prior per-turn hook in this codebase was removed for making an
+// unconditional network call on every single prompt (see the comment above installClaudeHooks),
+// and re-adding that cost here on three platforms at once was an explicit no per product decision.
+// The message itself is generated per-install from the actual plugin set being installed, not one
+// fixed string for everyone - e.g. someone who declined empirical-scar-tissue at install time
+// never sees a scar-tissue reminder, since that capability isn't actually available to them.
+//
+// Claude and Codex only - Copilot has no UserPromptSubmit reminder at all (removed 2026-09-18,
+// see installCopilotHooks's comment in this file for why: its only output field is a full prompt
+// replacement, not a side channel, so any injected reminder here reads as fake, model-authored
+// text inside what looks like the user's own message).
+function buildPromptReminderMessage(pluginNames, platform) {
+  const names = normalizePluginNames(pluginNames);
+
+  const lines = [
+    'Before responding: if this task needs prior context (research, debugging, a spec or status update, a handoff), query Empirical memory first via the empirical-memory skill or empirical memory query - do not assume you already have enough context.'
+  ];
+  if (names.includes('empirical-work-history')) {
+    lines.push('If you are picking up previously completed work, check for a recent work-history entry before assuming there is none.');
+    if (platform === 'codex') {
+      lines.push('If this turn results in meaningful completed work, BEFORE sending your final response you MUST use the empirical-work-history skill or record it via Empirical. The entry must carry tag work-history and mass 1; verify the create receipt. CLI fallback must use --json-file with data.session and data.git; do not use the shorthand record command for coding work. Do not wait for the Stop hook.');
+    }
+  }
+  if (names.includes('empirical-scar-tissue')) {
+    lines.push('Check for scar tissue before repeating a past mistake in this area.');
+  }
+  if (names.includes('empirical-todo')) {
+    lines.push('If there is an open todo for this project, check it before starting new work.');
+  }
+  return '[Empirical reminder] ' + lines.join(' ');
+}
+
+// Builds the full UserPromptSubmit hook script source with the tailored message baked in at
+// generation time (via JSON.stringify, so the message is embedded as a single already-escaped
+// string literal - substituted through `${}`, not written as raw template-literal source text,
+// which is what caused the earlier comment-escaping bug in this same file. Never do the latter).
+// `platform`:
+//  - 'codex': Codex's required hookSpecificOutput.additionalContext JSON shape (confirmed live
+//    2026-08-08 via a real `codex exec` run - plain text made Codex report the hook as failed).
+//  - default ('claude'): plain console.log.
+// Copilot has no variant here at all (removed 2026-09-18) - see installCopilotHooks's comment.
+function buildUserPromptSubmitHookSource(pluginNames, platform) {
+  const messageLiteral = JSON.stringify(buildPromptReminderMessage(pluginNames, platform));
+
+  const outputStatement = platform === 'codex'
+    ? `console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext: ${messageLiteral}
+    }
+  }));`
+    : `console.log(${messageLiteral});`;
+
+  return `#!/usr/bin/env node
+'use strict';
+
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+
+var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'user-prompt-submit.log');
+var MAX_LOG_BYTES = 200 * 1024;
+
+function appendLog(line) {
+  try {
+    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
+    var stat = fs.statSync(LOG_PATH);
+    if (stat.size > MAX_LOG_BYTES) {
+      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
+      fs.writeFileSync(LOG_PATH, tail);
+    }
+  } catch (e) {
+    // Diagnostics must never break the hook.
+  }
+}
+
+// A crash here must degrade to a silent no-op, never a visible "hook failed" error in the host CLI.
+try {
+  appendLog('user-prompt-submit hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
+  ${outputStatement}
+} catch (e) {
+  try { appendLog('uncaught error: ' + (e && e.message)); } catch (_e) { /* best effort */ }
+}
+process.exit(0);
+`;
+}
+
+function getEmpiricalHooksDir() {
+  return path.join(os.homedir(), '.empirical', 'hooks');
+}
+
+function buildHookCommand(scriptPath) {
+  return `"${process.execPath}" "${scriptPath}"`;
+}
+
+// Confirmed live (2026-08-08, via a real `copilot -p` run with debug logging): Copilot runs a
+// hook's "command"/"powershell" field through powershell.exe on Windows, and a bare
+// `"path" "arg"` string is not valid PowerShell syntax without the call operator (&) - two
+// adjacent quoted string literals with nothing between them is a ParserError
+// ("Unexpected token '...' in expression or statement"), not a "file not found"-style failure.
+// This is a completely different bug from Codex's (which needed 8.3 short paths to avoid
+// quoting) - no short-path workaround is needed here, just the operator PowerShell requires
+// before an executable path.
+function buildPowershellHookCommand(scriptPath) {
+  return `& "${process.execPath}" "${scriptPath}"`;
+}
+
+function removeEmpiricalHookEntries(entries, scriptPath) {
+  if (!Array.isArray(entries)) return [];
+  return entries
+    .map((entry) => {
+      if (!entry || !Array.isArray(entry.hooks)) return entry;
+      const filteredHooks = entry.hooks.filter(
+        (h) => !(h && typeof h.command === 'string' && h.command.includes(scriptPath))
+      );
+      return { ...entry, hooks: filteredHooks };
+    })
+    .filter((entry) => entry && (!Array.isArray(entry.hooks) || entry.hooks.length > 0));
+}
+
+function installClaudeHooks(pluginNames) {
+  const hooksDir = getEmpiricalHooksDir();
+  ensureDir(hooksDir);
+
+  // A prior version of this hook made an unconditional `empirical memory query` network call on
+  // every single prompt and was removed for being wasteful (see git history). This is a
+  // deliberate reintroduction at the SAME script path, but with fundamentally different content:
+  // a static, install-time-generated reminder with no network call at all - the cost concern that
+  // killed the old version does not apply to a plain stdout write.
+  const userPromptScriptPath = path.join(hooksDir, 'claude-user-prompt-submit.js');
+  const sessionStartScriptPath = path.join(hooksDir, 'claude-session-start.js');
+  const stopScriptPath = path.join(hooksDir, 'claude-stop.js');
+  writeFile(sessionStartScriptPath, CLAUDE_HOOK_SESSION_START_SOURCE);
+  writeFile(stopScriptPath, CLAUDE_HOOK_STOP_SOURCE);
+  writeFile(userPromptScriptPath, buildUserPromptSubmitHookSource(pluginNames));
+
+  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+  const settings = readJsonIfExists(settingsPath) || {};
+  if (!settings.hooks || typeof settings.hooks !== 'object') {
+    settings.hooks = {};
+  }
+
+  settings.hooks.UserPromptSubmit = removeEmpiricalHookEntries(settings.hooks.UserPromptSubmit, userPromptScriptPath);
+  settings.hooks.UserPromptSubmit.push({
+    hooks: [{ type: 'command', command: buildHookCommand(userPromptScriptPath), timeout: 10 }]
+  });
+
+  settings.hooks.SessionStart = removeEmpiricalHookEntries(settings.hooks.SessionStart, sessionStartScriptPath);
+  for (const matcher of ['startup', 'resume', 'compact']) {
+    settings.hooks.SessionStart.push({
+      matcher,
+      hooks: [{ type: 'command', command: buildHookCommand(sessionStartScriptPath), timeout: 25 }]
+    });
+  }
+
+  settings.hooks.Stop = removeEmpiricalHookEntries(settings.hooks.Stop, stopScriptPath);
+  settings.hooks.Stop.push({
+    hooks: [{ type: 'command', command: buildHookCommand(stopScriptPath), timeout: 10 }]
+  });
+
+  writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+  log('  - Claude SessionStart + UserPromptSubmit + Stop hooks installed for deterministic memory lookups and reminders.');
+}
+
+// Codex CLI ships a real hooks system (confirmed against openai/codex source — codex-rs/hooks,
+// codex-rs/config/src/hook_config.rs — not assumed from docs alone, since third-party writeups
+// disagreed on Windows support). It reads <CODEX_HOME>/hooks.json (JSON, not the config.toml
+// used for MCP/model settings — a separate file, so this never touches config.toml) shaped as
+// { hooks: { SessionStart: [{ matcher, hooks: [{ type: 'command', command, commandWindows,
+// timeout }] }], ... } }. CODEX_HOME defaults to ~/.codex when unset, same convention as
+// ~/.claude for Claude Code.
+function getCodexHomeDir() {
+  return process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+}
+
+function removeEmpiricalHooksJsonEntries(entries, scriptPath) {
+  if (!Array.isArray(entries)) return [];
+  return entries
+    .map((entry) => {
+      if (!entry || !Array.isArray(entry.hooks)) return entry;
+      const filteredHooks = entry.hooks.filter(
+        (h) => !(h && typeof h.command === 'string' && h.command.includes(scriptPath))
+      );
+      return { ...entry, hooks: filteredHooks };
+    })
+    .filter((entry) => entry && (!Array.isArray(entry.hooks) || entry.hooks.length > 0));
+}
+
+// Codex's Windows sandbox (confirmed via `codex doctor` -> "filesystem sandbox: restricted" and
+// ~/.codex/.sandbox/sandbox.*.log's "processed N write roots (read roots delegated)" / "applying
+// read ACLs" at session start) scopes filesystem access per-session to project-specific roots
+// plus, necessarily, CODEX_HOME itself (Codex reads hooks.json, its state db, and its plugin
+// cache from there on every session regardless of project). The shared `~/.empirical/hooks`
+// directory used by Claude/Copilot is neither - so under this sandbox, node.exe most likely
+// cannot even read a hook script living there, which is why hooks fail identically (exit 1)
+// across SessionStart/UserPromptSubmit/Stop regardless of what each script actually does,
+// including the trivial UserPromptSubmit script that spawns no subprocess at all. Claude Code
+// hooks are unaffected (confirmed working from the shared dir) and Copilot has shown no such
+// failure, so only Codex's copies are relocated here - Claude/Copilot keep using
+// getEmpiricalHooksDir() unchanged.
+function getCodexHooksScriptsDir() {
+  return path.join(getCodexHomeDir(), 'empirical-hooks');
+}
+
+// Confirmed live (2026-08-08, via a real `codex exec` run): Codex's Windows hook launcher fails
+// to parse a quoted executable path (e.g. `"C:\Program Files\nodejs\node.exe" "<script>"`,
+// otherwise a perfectly standard Windows command line - Claude Code and every direct shell/
+// spawnSync invocation handle it fine) and reports the hook as a nonzero-exit failure before any
+// of the script's own JS ever runs. Windows 8.3 short path names never contain spaces, so
+// resolving both the node executable and the script path to their short form and joining them
+// unquoted sidesteps the parser entirely. Computed once at install time (not per hook
+// invocation), so a synchronous shell call here is an acceptable cost.
+function getWindowsShortPath(longPath) {
+  if (process.platform !== 'win32') return null;
+  try {
+    const { execSync } = require('child_process');
+    const out = execSync(`cmd /c for %I in ("${longPath}") do @echo %~sI`, { encoding: 'utf8', timeout: 5000 });
+    const short = out.split(/\r?\n/).map((s) => s.trim()).filter(Boolean).pop();
+    const fs = require('fs');
+    return short && fs.existsSync(short) ? short : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+// Builds Codex's commandWindows value using short paths so neither the executable nor the script
+// path ever needs quoting. Falls back to the normal quoted buildHookCommand() form if short-path
+// resolution fails for any reason (e.g. 8.3 name generation disabled on that volume) - degraded
+// (same behavior as before this fix) rather than broken.
+function buildCodexWindowsHookCommand(scriptPath) {
+  const shortNode = getWindowsShortPath(process.execPath);
+  const shortScript = getWindowsShortPath(scriptPath);
+  if (shortNode && shortScript) {
+    return `${shortNode} ${shortScript}`;
+  }
+  return buildHookCommand(scriptPath);
+}
+
+function installCodexHooks(pluginNames) {
+  const fs = require('fs');
+  const legacyHooksDir = getEmpiricalHooksDir();
+  const hooksDir = getCodexHooksScriptsDir();
+  ensureDir(hooksDir);
+
+  const sessionStartScriptPath = path.join(hooksDir, 'codex-session-start.js');
+  const stopScriptPath = path.join(hooksDir, 'codex-stop.js');
+  const userPromptScriptPath = path.join(hooksDir, 'codex-user-prompt-submit.js');
+  writeFile(sessionStartScriptPath, CODEX_HOOK_SESSION_START_SOURCE);
+  writeFile(stopScriptPath, CODEX_HOOK_STOP_SOURCE);
+  writeFile(userPromptScriptPath, buildUserPromptSubmitHookSource(pluginNames, 'codex'));
+
+  // Best-effort cleanup of the pre-relocation script files/entries at the old shared path, so a
+  // machine that already had Codex hooks installed doesn't end up with both the old (broken
+  // under the sandbox) and new registration firing redundantly.
+  const legacySessionStartScriptPath = path.join(legacyHooksDir, 'codex-session-start.js');
+  const legacyStopScriptPath = path.join(legacyHooksDir, 'codex-stop.js');
+  const legacyUserPromptScriptPath = path.join(legacyHooksDir, 'codex-user-prompt-submit.js');
+  for (const legacyPath of [legacySessionStartScriptPath, legacyStopScriptPath, legacyUserPromptScriptPath]) {
+    try {
+      if (fs.existsSync(legacyPath)) fs.unlinkSync(legacyPath);
+    } catch (_error) {
+      // best-effort cleanup only
+    }
+  }
+
+  const hooksJsonPath = path.join(getCodexHomeDir(), 'hooks.json');
+  const hooksFile = readJsonIfExists(hooksJsonPath) || {};
+  if (!hooksFile.hooks || typeof hooksFile.hooks !== 'object') {
+    hooksFile.hooks = {};
+  }
+
+  hooksFile.hooks.SessionStart = removeEmpiricalHooksJsonEntries(
+    removeEmpiricalHooksJsonEntries(hooksFile.hooks.SessionStart, sessionStartScriptPath),
+    legacySessionStartScriptPath
+  );
+  const sessionStartCommand = buildHookCommand(sessionStartScriptPath);
+  const sessionStartCommandWindows = buildCodexWindowsHookCommand(sessionStartScriptPath);
+  for (const matcher of ['startup', 'resume']) {
+    hooksFile.hooks.SessionStart.push({
+      matcher,
+      hooks: [{ type: 'command', command: sessionStartCommand, commandWindows: sessionStartCommandWindows, timeout: 25 }]
+    });
+  }
+
+  hooksFile.hooks.Stop = removeEmpiricalHooksJsonEntries(
+    removeEmpiricalHooksJsonEntries(hooksFile.hooks.Stop, stopScriptPath),
+    legacyStopScriptPath
+  );
+  const stopCommand = buildHookCommand(stopScriptPath);
+  const stopCommandWindows = buildCodexWindowsHookCommand(stopScriptPath);
+  hooksFile.hooks.Stop.push({
+    hooks: [{ type: 'command', command: stopCommand, commandWindows: stopCommandWindows, timeout: 10 }]
+  });
+
+  // Confirmed against codex-rs/config/src/hook_config.rs's HookEventsToml serde renames: the
+  // config-file key is PascalCase "UserPromptSubmit", same casing convention as SessionStart/Stop.
+  hooksFile.hooks.UserPromptSubmit = removeEmpiricalHooksJsonEntries(
+    removeEmpiricalHooksJsonEntries(hooksFile.hooks.UserPromptSubmit, userPromptScriptPath),
+    legacyUserPromptScriptPath
+  );
+  const userPromptCommand = buildHookCommand(userPromptScriptPath);
+  const userPromptCommandWindows = buildCodexWindowsHookCommand(userPromptScriptPath);
+  hooksFile.hooks.UserPromptSubmit.push({
+    hooks: [{ type: 'command', command: userPromptCommand, commandWindows: userPromptCommandWindows, timeout: 10 }]
+  });
+
+  writeFile(hooksJsonPath, `${JSON.stringify(hooksFile, null, 2)}\n`);
+  log('  - Codex SessionStart + UserPromptSubmit + Stop hooks installed for deterministic memory lookups and reminders.');
+}
+
+// GitHub Copilot CLI's hook config is one JSON file per hook under ~/.copilot/hooks/ (any
+// filename — confirmed via GitHub's own docs at docs.github.com/en/copilot/reference/hooks-
+// reference), so unlike Claude/Codex this never needs to merge into a shared file: Empirical
+// owns this file outright and can just overwrite it.
+//
+// SessionStart only (2026-09-18): userPromptSubmitted and agentStop reminder hooks were removed
+// for Copilot entirely, not just capped. Both were fundamentally fake compared to Claude/Codex's
+// versions: userPromptSubmitted's only output field is modifiedPrompt (a full prompt replacement,
+// not a side-channel), so its "reminder" was really text injected into what looks like the user's
+// own message; agentStop only supports decision:"block"|"allow" with no passive/silent field, so
+// any reminder there forces a disruptive extra visible turn, and no per-session cap on that can
+// avoid the tradeoff between nagging every turn and going silent right before something worth
+// recording happens (confirmed live 2026-09-17/18: both caused real, reproducible bugs - a
+// prompt-blanking regression and an unstoppable "record your work" loop). Copilot instead relies
+// entirely on the identity-framed instructions block coreMemoryBlock.js writes into
+// copilot-instructions.md, same mechanism Claude/Codex have as a backstop under their working
+// hooks - see that file's Copilot-only addendum for the stronger, more directive wording this
+// puts on Copilot specifically to compensate for having no hook nudge at all.
+function installCopilotHooks(_pluginNames) {
+  const hooksDir = getEmpiricalHooksDir();
+  ensureDir(hooksDir);
+
+  const sessionStartScriptPath = path.join(hooksDir, 'copilot-session-start.js');
+  writeFile(sessionStartScriptPath, COPILOT_HOOK_SESSION_START_SOURCE);
+
+  // Clean up scripts/state files from every removed Copilot hook (agentStop's Stop reminder, the
+  // visible-modifiedPrompt UserPromptSubmit real-recall hook it was briefly replaced with) so an
+  // upgrade never leaves orphaned, unregistered files behind.
+  const fs = require('fs');
+  const staleFiles = [
+    path.join(hooksDir, 'copilot-stop.js'),
+    path.join(hooksDir, 'stop-state.json'),
+    path.join(hooksDir, 'copilot-user-prompt-submit.js'),
+    path.join(hooksDir, 'prompt-state.json')
+  ];
+  for (const stalePath of staleFiles) {
+    try {
+      if (fs.existsSync(stalePath)) fs.unlinkSync(stalePath);
+    } catch (_error) {
+      // best-effort cleanup only
+    }
+  }
+
+  const copilotHooksDir = path.join(os.homedir(), '.copilot', 'hooks');
+  ensureDir(copilotHooksDir);
+
+  // Prior versions of this installer wrote a single-purpose "empirical-session-start.json" —
+  // remove it now that both events live in one unified file, so a stale duplicate registration
+  // never lingers alongside the new one.
+  const legacyHookFilePath = path.join(copilotHooksDir, 'empirical-session-start.json');
+  try {
+    if (fs.existsSync(legacyHookFilePath)) fs.unlinkSync(legacyHookFilePath);
+  } catch (_error) {
+    // best-effort cleanup only
+  }
+
+  const hookFilePath = path.join(copilotHooksDir, 'empirical-hooks.json');
+  // Both `command` (POSIX fallback) and `powershell` (Windows-explicit, with the & call operator
+  // PowerShell requires - see buildPowershellHookCommand) are always set: per GitHub's hooks
+  // reference, an explicit `powershell` entry takes precedence over `command` on Windows, so this
+  // is correct on both platforms without needing to detect the install-time OS here.
+  //
+  // sessionStart only (2026-09-18): no agentStop (recording stays instructions-only, see
+  // coreMemoryBlock.js's Copilot addendum) and no userPromptSubmitted (its only output field,
+  // modifiedPrompt, is rendered back as the user's own visible message - confirmed live, not
+  // acceptable for silent recall). sessionStart's additionalContext delivers the same real query
+  // invisibly instead, once per real session boundary (not an artificial timer), using that
+  // event's own initialPrompt field as the query when present.
+  const hookFileContent = {
+    version: 1,
+    hooks: {
+      sessionStart: [
+        {
+          type: 'command',
+          command: buildHookCommand(sessionStartScriptPath),
+          powershell: buildPowershellHookCommand(sessionStartScriptPath),
+          timeoutSec: 15
+        }
+      ]
+    }
+  };
+
+  writeFile(hookFilePath, `${JSON.stringify(hookFileContent, null, 2)}\n`);
+  log('  - Copilot SessionStart hook installed (real recall via additionalContext). No UserPromptSubmit/agentStop reminders - see copilot-instructions.md instead.');
+}
+
+module.exports = {
+  CLAUDE_HOOK_SESSION_START_SOURCE,
+  CODEX_HOOK_SESSION_START_SOURCE,
+  COPILOT_HOOK_SESSION_START_SOURCE,
+  CODEX_HOOK_STOP_SOURCE,
+  CLAUDE_HOOK_STOP_SOURCE,
+  buildPromptReminderMessage,
+  buildUserPromptSubmitHookSource,
+  getEmpiricalHooksDir,
+  buildHookCommand,
+  buildPowershellHookCommand,
+  removeEmpiricalHookEntries,
+  installClaudeHooks,
+  getCodexHomeDir,
+  removeEmpiricalHooksJsonEntries,
+  getCodexHooksScriptsDir,
+  getWindowsShortPath,
+  buildCodexWindowsHookCommand,
+  installCodexHooks,
+  installCopilotHooks
+};