kenaz 0.3.20 → 0.3.22

package/core/.formation/bifrost/openai/codex-hook-shim.test.js

@@ -2,6 +2,7 @@
 const test = require('node:test');
 const assert = require('node:assert/strict');
 const fs = require('node:fs');
+const realCrypto = require('node:crypto');
 const path = require('node:path');
 const vm = require('node:vm');
 
@@ -46,6 +47,7 @@ async function fixture({ project, cwd = path.resolve('hook-cwd'), reject = false
       } };
       if (id.endsWith('_peer-project-root.js')) return { resolvePeerProjectRoot: dir => dir };
       if (id === 'child_process') return { execFileSync: () => assert.fail('unexpected child') };
+      if (id === 'crypto') return realCrypto;
       effects.modules.push(id);
       if (id.endsWith('task-bridge.js')) return { handleHookEvent: async payload => {
         effects.hooks.push(payload);

package/core/.formation/bifrost/openai/codex-peer-pull.test.js

@@ -0,0 +1,42 @@
+'use strict';
+// TASK_2465: Codex pulls peer mail by default when the server says the project's room is activated.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { wantsPeerPull } = require('./codex-hook-shim.js');
+
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'kenaz-codex-room-'));
+fs.mkdirSync(path.join(dir, '.kenaz'), { recursive: true });
+fs.writeFileSync(path.join(dir, '.kenaz', 'project.yaml'), 'name: t\n');
+// Committed repo config naming a room is NOT the activation.
+fs.writeFileSync(path.join(dir, '.kenaz', 'yggdrasil.yaml'), 'yggdrasil_project: "room-a"\n');
+
+const server = (cfg) => async (method, p) => { assert.equal(method, 'GET'); assert.ok(p.startsWith('/api/yggdrasil/config?projectPath=')); return cfg; };
+const active = server({ effective_project_key: 'room-a', collaboration_projects: ['room-a'] });
+
+test('activated room -> pulls without the flag', async () => {
+  assert.equal(await wantsPeerPull({}, ['node', 'shim'], dir, active), true);
+});
+
+test('room key present in repo config but not activated -> no pull', async () => {
+  assert.equal(await wantsPeerPull({}, [], dir, server({ effective_project_key: 'room-a', collaboration_projects: [] })), false);
+  assert.equal(await wantsPeerPull({}, [], dir, server({ effective_project_key: 'room-a', collaboration_projects: ['other'] })), false);
+});
+
+test('server down or odd answer fails closed', async () => {
+  assert.equal(await wantsPeerPull({}, [], dir, async () => null), false);
+  assert.equal(await wantsPeerPull({}, [], dir, async () => { throw new Error('x'); }), false);
+  assert.equal(await wantsPeerPull({}, [], dir, server({})), false);
+});
+
+test('KENAZ_PEER_PULL=0 wins over an activated room and --pull', async () => {
+  assert.equal(await wantsPeerPull({ KENAZ_PEER_PULL: '0' }, ['--pull'], dir, active), false);
+});
+
+test('KENAZ_PEER_PULL=1 and --pull still pull without a room', async () => {
+  const none = server({});
+  assert.equal(await wantsPeerPull({ KENAZ_PEER_PULL: '1' }, [], dir, none), true);
+  assert.equal(await wantsPeerPull({}, ['--pull'], dir, none), true);
+});

package/core/.formation/bifrost/provider-launch.js

@@ -45,7 +45,8 @@ function plan(argv, env = process.env, home = os.homedir(), live = null) {
   const key = p.key(env, home);
   if (!key) throw new Error(`${provider}: no API key (${p.keyHelp})`);
   const childEnv = { ...env, ...p.env(id, key, live && live[id]), CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1',
-    KENAZ_PROVIDER: provider }; // tools (dispatch.js) tell the session runs on another vendor
+    KENAZ_PROVIDER: provider, // tools (dispatch.js) tell the session runs on another vendor
+    KENAZ_PEER_OPTIN: env.KENAZ_PEER_OPTIN || '1' }; // TASK_2465: launched sessions are peer collaborators; =0 opts out
   for (const k of p.unset) delete childEnv[k];
   return { bin: 'claude', args: rest, env: childEnv, provider, model: id, context: childEnv.CLAUDE_CODE_MAX_CONTEXT_TOKENS };
 }

package/core/.formation/bifrost/setup-codex.js

@@ -138,6 +138,8 @@ function setup(options = {}) {
     const missingEv = missingHookEvents();
     log('dry-run: MCP ' + MCP_NAME + ' ' + (isMcpAlreadyRegistered() ? 'already registered' : 'would run codex mcp add ' + MCP_NAME + ' --url ' + MCP_URL));
     log('dry-run: native hooks ' + (missingEv.length === 0 ? 'already registered' : 'would append [[hooks.*]] for ' + missingEv.join(', ') + ' to ' + getCodexConfigPath()));
+    const stale = require('./codex-hooks-repair').describe(require('./codex-hooks-repair').scan(getCodexHome()));
+    if (stale) log('dry-run: ' + stale);
     log('dry-run: /kenaz prompt would be written to ' + path.join(getCodexHome(), 'prompts', 'kenaz.md'));
     return { success: true, action: 'dry_run' };
   }
@@ -173,6 +175,12 @@ function setup(options = {}) {
   }
 
 
+  // TASK_2460: drop Kenaz hook entries whose script is gone (hooks.json, config.toml) before the current ones are registered.
+  try {
+    const repairer = require('./codex-hooks-repair'), r = repairer.repair(getCodexHome());
+    if (r.json.length + r.toml.length) log('removed ' + (r.json.length + r.toml.length) + ' Kenaz hook entries pointing at missing files (backup: *.bak-<time>)');
+  } catch (err) { log('hook repair skipped: ' + err.message); }
+
   // TASK_1733: register native hooks when codex CLI supports them.
   // Graceful: if feature probe fails or hooks already registered, logs advisory and continues.
   const projectRoot = options.projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
@@ -324,18 +332,15 @@ function scanKenazHooks(text, projectRoot) {
   });
   return { segs, found };
 }
-/** config text without the kenaz handlers of `events` (and the empty group each one leaves behind). */
-function stripKenazHooks(text, events, projectRoot) {
-  const { segs, found } = scanKenazHooks(text, projectRoot);
+/** config text of `segs` without the handler segments `indexes` (and the empty group each one leaves behind). */
+function dropHandlerSegments(segs, indexes) {
   const drop = new Set();
-  for (const ev of events) {
-    for (const i of [...(found[ev] ? found[ev].current : []), ...(found[ev] ? found[ev].stale : [])]) {
-      drop.add(i);
-      const prev = segs[i - 1], next = segs[i + 1];
-      const g = prev && prev[0] && prev[0].match(GROUP_HEADER);
-      if (g && g[1] === ev && !(next && next[0] && HANDLER_HEADER.test(next[0]) && next[0].includes('.' + ev + '.'))
-          && prev[1].slice(1).every((l) => !l.trim())) drop.add(i - 1);
-    }
+  for (const i of indexes) {
+    drop.add(i);
+    const ev = segs[i][0].match(HANDLER_HEADER)[1], prev = segs[i - 1], next = segs[i + 1];
+    const g = prev && prev[0] && prev[0].match(GROUP_HEADER);
+    if (g && g[1] === ev && !(next && next[0] && HANDLER_HEADER.test(next[0]) && next[0].includes('.' + ev + '.'))
+        && prev[1].slice(1).every((l) => !l.trim())) drop.add(i - 1);
   }
   const out = [];
   segs.forEach((seg, i) => {
@@ -344,6 +349,11 @@ function stripKenazHooks(text, events, projectRoot) {
   });
   return out.join('\n');
 }
+/** config text without the kenaz handlers of `events`. */
+function stripKenazHooks(text, events, projectRoot) {
+  const { segs, found } = scanKenazHooks(text, projectRoot);
+  return dropHandlerSegments(segs, events.flatMap((ev) => (found[ev] ? [...found[ev].current, ...found[ev].stale] : [])));
+}
 
 function areHooksAlreadyRegistered(projectRoot) {
   const configPath = getCodexConfigPath();
@@ -743,7 +753,7 @@ function probeHttpMcp(urlStr) {
 module.exports = {
   setup, uninstall, isCodexInstalled, isMcpAlreadyRegistered, getRegisteredMcpUrl, registerMcp,
   probeNativeHooksSupported, areHooksAlreadyRegistered, missingHookEvents, registerHooks, getHookShimPath,
-  nativeHooksActive,
+  nativeHooksActive, parseSegments, dropHandlerSegments, HANDLER_HEADER,
   // TASK_1780 — project-declared MCP servers
   getCodexHome, getCodexConfigPath, resolveProjectManifest, parseProjectMcpServers,
   parseRegisteredMcpServers, ensureProjectMcpServers, probeProjectMcpServers,

package/core/.specialist/Ansuz/RULES.md

@@ -82,6 +82,13 @@ the real defect BEFORE carding or dispatching.
 - Worktree subagents must commit; cleanup deletes uncommitted edits. Remove Kenaz worktrees only
   via .formation/tools/worktree-reclaim.js (it unlinks node_modules junctions first).
 
+## Skill moments (TASK_2375)
+Call these with the Skill tool yourself (name may carry the `kenaz:` prefix in a plugin session); nobody types them. Transcript audit: dev/research/skill-routing/AUDIT.md.
+- Before merging a branch that changes logic (FAST/FULL): `code_reviewer` on `git diff main...<branch>`; a Blocker goes back to the subagent. Skip for docs-only or DIRECT trivial edits.
+- Change touches auth, tokens, identity, relay or peer-message handling, or reads untrusted input (field reports, wishes, peer mail), or the user asks if something resists attack: `security_agent` before carding and before merge.
+- Another repo, paper or feature offered as a reference or "is this useful / similar to ours": `assessment_agent`.
+- Multi-module work or subsystem replacement, before carding: `architect_agent`. "What is unused / can go": `spec_optimizer`. Released software broken for users: `incident_response`.
+
 ## Verify and land
 - Verification policy: .specialist/Ansuz/VERIFY.md.
 - Landing: .specialist/Ansuz/tools/verify-and-land.js (branch check -> suites -> merge ->

package/core/KENAZ_CORE_VERSION

@@ -1 +1 @@
-0.3.20
+0.3.22

package/core/dashboard/scripts/install-kenaz-cli.js

@@ -0,0 +1,456 @@
+#!/usr/bin/env node
+'use strict';
+// TASK_2367: CLI-first install. node install-kenaz-cli.js <install|uninstall|status> [flags]
+//   --dry-run          print the plan, change nothing
+//   --home <dir>       user home (default os.homedir(); tests use a temp dir)
+//   --core-dir <dir>   kenaz-core root holding plugins/kenaz (default KENAZ_CORE_DIR or repo root)
+//   --server-bin <p>   kenaz-server binary (default: first existing candidate)
+//   --no-service       register the plugin only
+//   --no-plugin        install the service only
+// Plugin registration mirrors dashboard/src-tauri/src/features/project/peer_mod.rs (same env var,
+// merge-never-replace, one-time backup, atomic write, CLI >= 2.1.287 gate, KENAZ_SKIP_CLAUDE_PROVISION opt-out).
+// thrift: duplicate of the Rust logic until it is unified (see dev/plans/CLI_FIRST_INSTALL_FLOW.md).
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const http = require('http');
+const { spawnSync } = require('child_process');
+
+const ENV_KEY = 'CLAUDE_CODE_PLUGIN_DIRS';
+const BACKUP = 'settings.json.bak-kenaz-peer'; // shared with the Rust path on purpose: one backup of the pristine file
+const MIN_CLI = [2, 1, 287];
+const SEP = process.platform === 'win32' ? ';' : ':';
+const TASK_NAME = 'KenazServer';
+const LABEL = 'ai.kenaz.server';
+
+const norm = (e) => {
+  const s = String(e).trim().replace(/\\/g, '/').replace(/\/+$/, '');
+  return process.platform === 'win32' ? s.toLowerCase() : s;
+};
+const parseVersion = (s) => { const m = /(\d+)\.(\d+)\.(\d+)/.exec(s || ''); return m ? m.slice(1, 4).map(Number) : null; };
+const cmpVersion = (a, b) => { for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] - b[i]; return 0; };
+
+function loadSettings(file) {
+  let txt;
+  try { txt = fs.readFileSync(file, 'utf8'); } catch (e) { if (e.code === 'ENOENT') return {}; throw new Error('cannot read settings.json: ' + e.message); }
+  if (!txt.trim()) return {};
+  let v;
+  try { v = JSON.parse(txt); } catch (e) { throw new Error('settings.json is not valid JSON (' + e.message + '); left untouched'); }
+  if (!v || typeof v !== 'object' || Array.isArray(v)) throw new Error('settings.json is not a JSON object; left untouched');
+  return v;
+}
+function entriesOf(v) {
+  if (v.env === undefined) return [];
+  if (!v.env || typeof v.env !== 'object' || Array.isArray(v.env)) throw new Error('settings.json `env` is not an object; left untouched');
+  const s = v.env[ENV_KEY];
+  if (s === undefined) return [];
+  if (typeof s !== 'string') throw new Error('env.' + ENV_KEY + ' is not a string; left untouched');
+  return s.split(SEP).map((x) => x.trim()).filter(Boolean);
+}
+function saveSettings(file, v) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const bak = path.join(path.dirname(file), BACKUP);
+  if (fs.existsSync(file) && !fs.existsSync(bak)) fs.copyFileSync(file, bak);
+  const tmp = file + '.kenaz-tmp';
+  fs.writeFileSync(tmp, JSON.stringify(v, null, 2));
+  fs.renameSync(tmp, file);
+}
+function setEntries(v, list) {
+  v.env = v.env || {};
+  if (list.length) v.env[ENV_KEY] = list.join(SEP); else delete v.env[ENV_KEY];
+}
+const isWorktreePath = (d) => /(^|\/)\.kenaz-worktrees(\/|$)/.test(norm(d));
+// TASK_2384: a stale copy is another checkout of the same plugin (.../plugins/<name>): release core, worktree.
+const staleCopy = (e, dir) => norm(e) !== norm(dir) && norm(e).endsWith('/plugins/' + norm(dir).split('/').pop());
+/** One path per Kenaz plugin: older copies are replaced in place, never appended. A worktree checkout is
+ *  never registered in user settings. @returns 'added'|'already'|'replaced' */
+function registerPlugin(file, dir, dry) {
+  if (isWorktreePath(dir)) throw new Error('refusing to register a .kenaz-worktrees path in user settings: ' + dir);
+  const v = loadSettings(file), list = entriesOf(v);
+  const mine = (e) => norm(e) === norm(dir) || staleCopy(e, dir);
+  const has = list.some((e) => norm(e) === norm(dir));
+  if (has && list.filter(mine).length === 1) return 'already';
+  const first = list.findIndex(mine);
+  if (first < 0) { if (!dry) { list.push(dir); setEntries(v, list); saveSettings(file, v); } return 'added'; }
+  const next = list.map((e, i) => (i === first ? dir : e)).filter((e, i) => i === first || !mine(e));
+  if (!dry) { setEntries(v, next); saveSettings(file, v); }
+  return 'replaced';
+}
+/** @returns 'removed'|'absent' */
+function unregisterPlugin(file, dir, dry) {
+  if (!fs.existsSync(file)) return 'absent';
+  const v = loadSettings(file), list = entriesOf(v);
+  const kept = list.filter((e) => norm(e) !== norm(dir));
+  if (kept.length === list.length) return 'absent';
+  if (!dry) { setEntries(v, kept); saveSettings(file, v); }
+  return 'removed';
+}
+
+// Status line with the project's task counts (plugins/kenaz/scripts/statusline.js). Set only when the user has no
+// statusLine; a user's own is never replaced. Ours is recognised by the script path, so a moved core is updated.
+const STATUSLINE_TAIL = 'plugins/kenaz/scripts/statusline.js';
+const isOurStatusline = (s) => !!(s && typeof s.command === 'string' && norm(s.command).includes(STATUSLINE_TAIL));
+/** @returns 'added'|'already'|'replaced'|'kept-user' */
+function registerStatusline(file, core, dry) {
+  const v = loadSettings(file);
+  const command = 'node "' + path.join(core, ...STATUSLINE_TAIL.split('/')) + '"';
+  if (v.statusLine && !isOurStatusline(v.statusLine)) return 'kept-user';
+  if (v.statusLine && norm(v.statusLine.command) === norm(command)) return 'already';
+  const r = v.statusLine ? 'replaced' : 'added';
+  if (!dry) { v.statusLine = { type: 'command', command }; saveSettings(file, v); }
+  return r;
+}
+/** @returns 'removed'|'absent' */
+function unregisterStatusline(file, dry) {
+  if (!fs.existsSync(file)) return 'absent';
+  const v = loadSettings(file);
+  if (!isOurStatusline(v.statusLine)) return 'absent';
+  if (!dry) { delete v.statusLine; saveSettings(file, v); }
+  return 'removed';
+}
+
+// TASK_2384: Dashboard-era user-level hooks (wrapped by .claude/hooks/_user-scope.js, direct .claude/hooks/*.js, or the
+// agent-flow curl/node posts) duplicate what plugins/kenaz/hooks/hooks.json now runs. Single owner = the plugin, so
+// once it is registered these are removed (first write backs up the pristine file to settings.json.bak-kenaz-peer).
+const DASH_HOOK = /_user-scope\.js|[\\/]\.claude[\\/]hooks[\\/][\w.-]+\.js|\/api\/rust\/agent-flow\/hook/;
+/** @returns number of hook commands retired */
+function retireDashboardHooks(file, dry) {
+  if (!fs.existsSync(file)) return 0;
+  const v = loadSettings(file);
+  if (!v.hooks || typeof v.hooks !== 'object' || Array.isArray(v.hooks)) return 0;
+  let n = 0;
+  for (const ev of Object.keys(v.hooks)) {
+    if (!Array.isArray(v.hooks[ev])) continue;
+    const groups = [];
+    for (const g of v.hooks[ev]) {
+      if (!g || !Array.isArray(g.hooks)) { groups.push(g); continue; }
+      const kept = g.hooks.filter((h) => !(h && typeof h.command === 'string' && DASH_HOOK.test(h.command)));
+      n += g.hooks.length - kept.length;
+      if (kept.length) groups.push(kept.length === g.hooks.length ? g : { ...g, hooks: kept });
+    }
+    if (groups.length) v.hooks[ev] = groups; else delete v.hooks[ev];
+  }
+  if (n && !dry) { if (!Object.keys(v.hooks).length) delete v.hooks; saveSettings(file, v); }
+  return n;
+}
+
+function claudeVersion() {
+  const r = process.platform === 'win32' // one string with shell (.cmd shim): args + shell:true is deprecated (DEP0190)
+    ? spawnSync('claude --version', { encoding: 'utf8', shell: true, timeout: 15000 })
+    : spawnSync('claude', ['--version'], { encoding: 'utf8', timeout: 15000 });
+  return r.status === 0 ? parseVersion(r.stdout) : null;
+}
+
+// ---- service definitions (pure; the OS calls are in service* below) ----
+function launcherPaths(home) {
+  const d = path.join(home, '.kenaz');
+  return { dir: d, vbs: path.join(d, 'kenaz-server.vbs'), log: path.join(d, 'kenaz-server.log') };
+}
+const q = (s) => '"' + s + '"';
+function winVbs(bin, core) { // hidden window, env for task tools; server binds loopback by default
+  return 'Set sh = WScript.CreateObject("WScript.Shell")\r\nsh.Environment("Process")("KENAZ_SOURCE_DIR") = "' + core + '"\r\n' +
+    'sh.Run """' + bin + '""", 0, False\r\n';
+}
+// launchd and systemd start the server with a bare PATH (/usr/bin:/bin...), so `node` from Homebrew,
+// nvm or /usr/local was not found and every MCP tool that runs a node script failed with
+// "No such file or directory" (field report, macOS 0.3.1). Put the node running this install first.
+function servicePath(nodeExe = process.execPath) {
+  return [path.dirname(nodeExe), '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin']
+    .filter((d, i, a) => a.indexOf(d) === i).join(':');
+}
+function launchdPlist(bin, core, log, nodeExe) {
+  return '<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict>\n' +
+    '  <key>Label</key><string>' + LABEL + '</string>\n  <key>ProgramArguments</key><array><string>' + bin + '</string></array>\n' +
+    '  <key>EnvironmentVariables</key><dict><key>KENAZ_SOURCE_DIR</key><string>' + core + '</string><key>PATH</key><string>' + servicePath(nodeExe) + '</string></dict>\n' +
+    '  <key>RunAtLoad</key><true/>\n  <key>KeepAlive</key><true/>\n  <key>StandardOutPath</key><string>' + log + '</string>\n  <key>StandardErrorPath</key><string>' + log + '</string>\n</dict></plist>\n';
+}
+function systemdUnit(bin, core, nodeExe) {
+  return '[Unit]\nDescription=Kenaz server (headless backend)\nAfter=network.target\n\n[Service]\nExecStart=' + bin + '\nEnvironment=KENAZ_SOURCE_DIR=' + core + '\nEnvironment=PATH=' + servicePath(nodeExe) + '\nRestart=on-failure\n\n[Install]\nWantedBy=default.target\n';
+}
+
+// TASK_2413: no usable systemd user session (containers, WSL1, minimal servers) -> `systemctl --user enable --now`
+// silently does nothing. Fall back to an @reboot crontab entry ('cron') or, without crontab, a manual start ('manual').
+const CRON_MARK = '# kenaz-server (managed by kenaz install)';
+const shq = (v) => "'" + String(v).replace(/'/g, "'\\''") + "'";
+function cronStartCmd(bin, core, log, nodeExe) {
+  return 'KENAZ_SOURCE_DIR=' + shq(core) + ' PATH=' + shq(servicePath(nodeExe)) + ' ' + shq(bin) + ' >> ' + shq(log) + ' 2>&1';
+}
+function cronLine(bin, core, log, nodeExe) { // % is special in crontab
+  return '@reboot ' + cronStartCmd(bin, core, log, nodeExe).replace(/%/g, '\\%') + ' ' + CRON_MARK;
+}
+// stop exactly this binary (never by process name: another install's kenaz-server must survive). An upgraded
+// process still runs the unlinked inode, which /proc reports as "<path> (deleted)".
+function stopCmd(plan) {
+  const b = shq(plan.bin);
+  return 'for p in $(pgrep -x kenaz-server); do e=$(readlink /proc/$p/exe); ' +
+    '[ "$e" = ' + b + ' ] || [ "$e" = ' + shq(plan.bin + ' (deleted)') + ' ] && kill $p; done; true';
+}
+// start now, detached from the installer (new session when setsid exists), output to the log
+function detachedStartCmd(plan) {
+  return 'if command -v setsid >/dev/null 2>&1; then S=setsid; else S=; fi; ' +
+    'KENAZ_SOURCE_DIR=' + shq(plan.core) + ' PATH=' + shq(servicePath()) + ' $S nohup ' + shq(plan.bin) + ' >> ' + shq(plan.log) + ' 2>&1 < /dev/null &';
+}
+
+function servicePlan(home, bin, core, platform = process.platform, caps = { systemd: true }) {
+  const L = launcherPaths(home);
+  if (platform === 'win32') {
+    const roaming = home === os.homedir() && process.env.APPDATA ? process.env.APPDATA : path.join(home, 'AppData', 'Roaming');
+    const startup = path.join(roaming, 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup', 'KenazServer.vbs');
+    return { kind: 'windows', files: [[L.vbs, winVbs(bin, core)]], fallbackFile: startup };
+  }
+  if (platform === 'darwin') {
+    const p = path.join(home, 'Library', 'LaunchAgents', LABEL + '.plist');
+    return { kind: 'launchd', files: [[p, launchdPlist(bin, core, L.log)]], unit: p };
+  }
+  if (caps.systemd === false) {
+    return { kind: caps.crontab ? 'cron' : 'manual', files: [], bin, core, log: L.log, cronLine: cronLine(bin, core, L.log) };
+  }
+  const p = path.join(home, '.config', 'systemd', 'user', 'kenaz-server.service');
+  return { kind: 'systemd', files: [[p, systemdUnit(bin, core)]], unit: p };
+}
+const sh = (cmd, args, opts) => spawnSync(cmd, args, { encoding: 'utf8', ...(opts || {}) });
+
+// crontab -l: null = no crontab binary; '' = binary present, no crontab yet. All through the injected `run`.
+function readCron(run) {
+  const r = run('crontab', ['-l']);
+  if (!r || r.error || r.status === 127) return null;
+  return r.status === 0 ? String(r.stdout || '') : '';
+}
+function probeLinux(run) {
+  const r = run('systemctl', ['--user', 'show-environment']);
+  const systemd = !!r && !r.error && r.status === 0;
+  return { systemd, crontab: systemd ? undefined : readCron(run) !== null };
+}
+function writeCron(run, current, line) { // line null = remove our entry; keeps every other line; idempotent
+  const keep = current.split('\n').filter((l) => l.trim() && !l.includes(CRON_MARK));
+  const next = line ? keep.concat(line) : keep;
+  const text = next.length ? next.join('\n') + '\n' : '';
+  if (text === current) return false;
+  if (text) run('crontab', ['-'], { input: text }); else run('crontab', ['-r']);
+  return true;
+}
+
+// TASK_2418: loading/enabling a unit that is already loaded/active is a no-op, so an upgrade must restart it
+// explicitly, after the new binary is in place. launchd KeepAlive respawns the OLD file in the window between
+// stopOwnServer() and the copy (the process then keeps the unlinked inode); systemd `enable --now` does not
+// restart an active unit. restartHint is also the command printed when the version check fails.
+const defaultUid = () => (typeof process.getuid === 'function' ? process.getuid() : 501);
+function restartHint(plan, uid = defaultUid()) {
+  if (plan.kind === 'launchd') return 'launchctl kickstart -k gui/' + uid + '/' + LABEL;
+  if (plan.kind === 'systemd') return 'systemctl --user restart kenaz-server';
+  if (plan.kind === 'cron' || plan.kind === 'manual') return stopCmd(plan) + '; ' + detachedStartCmd(plan);
+  // the launcher works for both the scheduled task and the Startup-folder fallback (no admin rights needed)
+  return 'end kenaz-server.exe in Task Manager, then run: wscript.exe ' + q(plan.files && plan.files[0] ? plan.files[0][0] : 'kenaz-server.vbs');
+}
+function serviceRestart(plan, dry, log, run = sh, uid = defaultUid()) {
+  if (plan.kind === 'cron' || plan.kind === 'manual') { // no supervisor: start it (stopOwnServer freed the old one)
+    log('start now (detached, log ' + plan.log + ')');
+    if (!dry) { fs.mkdirSync(path.dirname(plan.log), { recursive: true }); run('sh', ['-c', detachedStartCmd(plan)]); }
+    return;
+  }
+  if (plan.kind === 'windows') return; // /Create + /Run above start the just-copied exe (stopOwnServer freed it)
+  log(restartHint(plan, uid));
+  if (dry) return;
+  if (plan.kind === 'launchd') {
+    const r = run('launchctl', ['kickstart', '-k', 'gui/' + uid + '/' + LABEL]);
+    if (r && r.status !== 0) { // old macOS / no GUI session domain: unload + load restarts it the long way
+      log('kickstart failed (exit ' + r.status + '), falling back to launchctl unload + load');
+      run('launchctl', ['unload', plan.unit]); run('launchctl', ['load', '-w', plan.unit]);
+    }
+  } else run('systemctl', ['--user', 'restart', 'kenaz-server']);
+}
+
+/** One GET /api/health; resolves { ok, version }. */
+function healthOnce(port, getFn = http.get) {
+  return new Promise((resolve) => {
+    const req = getFn({ host: '127.0.0.1', port, path: '/api/health', timeout: 2000 }, (res) => {
+      let b = ''; res.on('data', (d) => { b += d; });
+      res.on('end', () => { let v = null; try { v = JSON.parse(b).version || null; } catch (_) { /* body optional */ } resolve({ ok: res.statusCode < 500, version: v }); });
+    });
+    req.on('timeout', () => { req.destroy(); resolve({ ok: false, version: null }); });
+    req.on('error', () => resolve({ ok: false, version: null }));
+  });
+}
+/**
+ * TASK_2418: after the service (re)start, ask the running server for its version and compare with the one just
+ * installed. Retries (the server needs a moment to bind). Returns 'ok' | 'mismatch' | 'unreachable'; the last two
+ * print a warning with the exact restart command and do not fail the install.
+ */
+async function verifyRuntime(plan, expected, log, opts = {}) {
+  const port = opts.port || process.env.KENAZ_HTTP_PORT || '18080';
+  const tries = opts.tries || 6, delay = opts.delayMs === undefined ? 1000 : opts.delayMs;
+  const probe = opts.health || ((p) => healthOnce(p));
+  let last = { ok: false, version: null };
+  for (let i = 0; i < tries; i++) {
+    last = await probe(port);
+    if (last.ok && last.version === expected) { log('server: running version ' + expected + ' on :' + port); return 'ok'; }
+    if (i < tries - 1 && delay) await new Promise((r) => setTimeout(r, delay));
+  }
+  const hint = restartHint(plan, opts.uid);
+  if (last.ok && last.version) {
+    log('WARNING: the server on :' + port + ' still reports version ' + last.version + ' but ' + expected + ' was just installed. Restart it: ' + hint);
+    return 'mismatch';
+  }
+  log('WARNING: could not confirm the new server (' + expected + ') on 127.0.0.1:' + port + (last.ok ? ' (no version in /api/health)' : ' (no answer)') + '. If it is not running: ' + hint);
+  return 'unreachable';
+}
+
+function serviceInstall(plan, dry, log, run = sh, uid) {
+  const sh = run; // injectable for tests; shadows the module-level spawnSync wrapper inside this function
+  for (const [f, body] of plan.files) { log('write ' + f); if (!dry) { fs.mkdirSync(path.dirname(f), { recursive: true }); fs.writeFileSync(f, body); } }
+  if (plan.kind === 'windows') {
+    const tr = 'wscript.exe ' + q(plan.files[0][0]);
+    log('schtasks /Create /TN ' + TASK_NAME + ' /SC ONLOGON /TR ' + tr + ' /F  (fallback: ' + plan.fallbackFile + ')');
+    if (dry) return;
+    const r = sh('schtasks', ['/Create', '/TN', TASK_NAME, '/SC', 'ONLOGON', '/TR', tr, '/F']);
+    if (r.status === 0) sh('schtasks', ['/Run', '/TN', TASK_NAME]);
+    else { // ONLOGON tasks can need elevation: a Startup-folder launcher is the per-user equivalent
+      fs.mkdirSync(path.dirname(plan.fallbackFile), { recursive: true });
+      fs.copyFileSync(plan.files[0][0], plan.fallbackFile);
+      sh('wscript.exe', [plan.files[0][0]]);
+      // schtasks' stderr is in the console's OEM code page (garbled when echoed); the usual cause is
+      // missing admin rights for /SC ONLOGON. The Startup-folder launcher starts at logon the same way.
+      log('schtasks needs administrator rights here (exit ' + r.status + '); installed the Startup-folder launcher instead (also starts at logon)');
+    }
+  } else if (plan.kind === 'launchd') {
+    log('launchctl load -w ' + plan.unit); if (!dry) sh('launchctl', ['load', '-w', plan.unit]);
+    serviceRestart(plan, dry, log, sh, uid);
+  } else if (plan.kind === 'cron' || plan.kind === 'manual') {
+    if (plan.kind === 'cron') {
+      log('crontab: @reboot entry  ' + plan.cronLine);
+      if (!dry) { const cur = readCron(sh); if (cur !== null) writeCron(sh, cur, plan.cronLine); }
+    } else {
+      log('WARNING: no systemd user session and no crontab here. Add this to your own init/boot script to start the server at boot: ' + cronStartCmd(plan.bin, plan.core, plan.log));
+    }
+    serviceRestart(plan, dry, log, sh, uid);
+  } else {
+    log('systemctl --user enable --now kenaz-server');
+    if (!dry) { sh('systemctl', ['--user', 'daemon-reload']); sh('systemctl', ['--user', 'enable', '--now', 'kenaz-server']); }
+    serviceRestart(plan, dry, log, sh, uid);
+  }
+}
+function serviceUninstall(plan, dry, log, run = sh) {
+  if (plan.kind === 'windows') {
+    log('schtasks /End + /Delete /TN ' + TASK_NAME);
+    if (!dry) { run('schtasks', ['/End', '/TN', TASK_NAME]); run('schtasks', ['/Delete', '/TN', TASK_NAME, '/F']); }
+    if (fs.existsSync(plan.fallbackFile)) { log('remove ' + plan.fallbackFile); if (!dry) fs.rmSync(plan.fallbackFile, { force: true }); }
+  } else if (plan.kind === 'launchd') {
+    log('launchctl unload ' + plan.unit); if (!dry) run('launchctl', ['unload', '-w', plan.unit]);
+  } else if (plan.kind === 'cron' || plan.kind === 'manual') {
+    if (plan.kind === 'cron') { log('crontab: remove the kenaz-server @reboot entry'); if (!dry) { const cur = readCron(run); if (cur !== null) writeCron(run, cur, null); } }
+    log('stop ' + plan.bin); if (!dry) run('sh', ['-c', stopCmd(plan)]);
+  } else {
+    log('systemctl --user disable --now kenaz-server'); if (!dry) run('systemctl', ['--user', 'disable', '--now', 'kenaz-server']);
+  }
+  for (const [f] of plan.files) if (fs.existsSync(f)) { log('remove ' + f); if (!dry) fs.rmSync(f, { force: true }); }
+}
+function serviceStatus(plan, run = sh) {
+  if (plan.kind === 'cron') { const c = readCron(run); return c && c.includes(CRON_MARK) ? 'cron @reboot entry present' : 'not installed'; }
+  if (plan.kind === 'manual') return 'manual (no systemd user session, no crontab)';
+  if (plan.kind === 'windows') return run('schtasks', ['/Query', '/TN', TASK_NAME]).status === 0 ? 'scheduled task present' : (fs.existsSync(plan.fallbackFile) ? 'startup launcher present' : 'not installed');
+  if (plan.kind === 'systemd') return run('systemctl', ['--user', 'is-active', 'kenaz-server']).stdout.trim() || 'not installed';
+  return fs.existsSync(plan.unit) ? 'plist present' : 'not installed';
+}
+
+/** Which mechanism keeps the server running on this machine (for `kenaz doctor`). Read-only, all via `run`. */
+function detectServiceMode(home, core, run = sh, platform = process.platform) {
+  if (platform === 'win32') {
+    const plan = servicePlan(home, '', core, 'win32');
+    if (run('schtasks', ['/Query', '/TN', TASK_NAME]).status === 0) return { mode: 'windows task', detail: 'scheduled task ' + TASK_NAME };
+    if (fs.existsSync(plan.fallbackFile)) return { mode: 'startup launcher', detail: plan.fallbackFile };
+    return { mode: 'manual', detail: 'no scheduled task or Startup launcher; run `kenaz install`' };
+  }
+  if (platform === 'darwin') {
+    const p = servicePlan(home, '', core, 'darwin').unit;
+    return fs.existsSync(p) ? { mode: 'launchd', detail: p } : { mode: 'manual', detail: 'no launchd agent; run `kenaz install`' };
+  }
+  const unit = servicePlan(home, '', core, 'linux').unit;
+  if (fs.existsSync(unit) && probeLinux(run).systemd) return { mode: 'systemd', detail: unit };
+  const c = readCron(run);
+  if (c && c.includes(CRON_MARK)) return { mode: 'cron', detail: '@reboot crontab entry (no systemd user session)' };
+  return { mode: 'manual', detail: 'no systemd unit or cron entry; run `kenaz install`' };
+}
+
+function parseArgs(argv) {
+  const o = { cmd: argv[0], flags: {} };
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) continue;
+    const k = a.slice(2);
+    if (['home', 'core-dir', 'server-bin'].includes(k)) o.flags[k] = argv[++i]; else o.flags[k] = true;
+  }
+  return o;
+}
+function findServerBin(core, home) {
+  const exe = process.platform === 'win32' ? 'kenaz-server.exe' : 'kenaz-server';
+  const c = [path.join(core, '..', exe), path.join(core, 'bin', exe), path.join(core, 'dashboard', 'src-tauri', 'target', 'release', exe), path.join(home, '.kenaz', 'bin', exe)];
+  return c.map((p) => path.resolve(p)).find((p) => fs.existsSync(p)) || null;
+}
+
+function main(argv, out = console.log, getVersion = claudeVersion, deps = {}) { // getVersion, deps {sh, platform, uid, onPlan}: injectable for tests
+  const { cmd, flags } = parseArgs(argv);
+  if (!['install', 'uninstall', 'status'].includes(cmd)) {
+    out('usage: install-kenaz-cli.js <install|uninstall|status> [--dry-run] [--home d] [--core-dir d] [--server-bin p] [--no-service] [--no-plugin]');
+    return 2;
+  }
+  const dry = !!flags['dry-run'];
+  const home = path.resolve(flags.home || os.homedir());
+  const core = path.resolve(flags['core-dir'] || process.env.KENAZ_CORE_DIR || path.join(__dirname, '..', '..'));
+  // TASK_2380: kenaz-peer (idle push) rides along; same gate and merge rules as plugins/kenaz.
+  const pluginDirs = ['kenaz', 'kenaz-peer'].map((n) => path.join(core, 'plugins', n));
+  const settings = path.join(home, '.claude', 'settings.json');
+  const log = (m) => out((dry ? '[dry-run] ' : '') + m);
+  let rc = 0;
+
+  if (!flags['no-plugin']) {
+    try {
+      let ver;
+      for (const pluginDir of pluginDirs) {
+        const name = path.basename(pluginDir);
+        if (cmd === 'status') {
+          const list = entriesOf(loadSettings(settings));
+          out(name + ': ' + (list.some((e) => norm(e) === norm(pluginDir)) ? 'registered' : 'not registered') + ' (' + pluginDir + ')');
+        } else if (cmd === 'uninstall') {
+          log(name + ': ' + unregisterPlugin(settings, pluginDir, dry) + ' (' + settings + ')');
+          if (name === 'kenaz') log('statusline: ' + unregisterStatusline(settings, dry));
+        } else if (process.env.KENAZ_SKIP_CLAUDE_PROVISION === '1') {
+          log(name + ': skipped (KENAZ_SKIP_CLAUDE_PROVISION=1)');
+        } else if (!fs.existsSync(path.join(pluginDir, 'hooks', 'hooks.json'))) {
+          log(name + ': skipped, ' + pluginDir + ' has no hooks/hooks.json'); rc = 1;
+        } else {
+          if (ver === undefined) ver = getVersion();
+          if (!ver) log(name + ': skipped, claude CLI not found (install it, then rerun install)');
+          else if (cmpVersion(ver, MIN_CLI) < 0) log(name + ': skipped, claude ' + ver.join('.') + ' < ' + MIN_CLI.join('.') + ' (run `claude update`, then rerun install)');
+          else {
+            log(name + ': ' + registerPlugin(settings, pluginDir, dry) + ' (' + settings + ')');
+            if (name === 'kenaz') {
+              const sl = registerStatusline(settings, core, dry);
+              log('statusline: ' + (sl === 'kept-user' ? 'kept your own statusLine; to show Kenaz task counts, append the output of: node "' + path.join(core, ...STATUSLINE_TAIL.split('/')) + '"' : sl));
+              const n = retireDashboardHooks(settings, dry);
+              if (n) log('kenaz: retired ' + n + ' Dashboard-era user-level hook(s), now owned by the plugin (backup: ' + path.join(path.dirname(settings), BACKUP) + ')');
+            }
+          }
+        }
+      }
+    } catch (e) { out('plugin: ERROR ' + e.message); rc = 1; }
+  }
+
+  if (!flags['no-service']) {
+    const bin = flags['server-bin'] ? path.resolve(flags['server-bin']) : findServerBin(core, home);
+    const run = deps.sh || sh, platform = deps.platform || process.platform;
+    // the probe is read-only but still a system call: skipped on --dry-run (assumes systemd, as before)
+    const caps = platform === 'linux' && !dry ? probeLinux(run) : undefined;
+    const plan = servicePlan(home, bin || '<kenaz-server not found>', core, platform, caps);
+    if (deps.onPlan) deps.onPlan(plan);
+    if (cmd === 'status') out('service: ' + (dry ? 'skipped (dry-run)' : serviceStatus(plan, run)));
+    else if (cmd === 'uninstall') serviceUninstall(plan, dry, log, run);
+    else if (!bin) { out('service: skipped, kenaz-server binary not found (pass --server-bin)'); rc = 1; }
+    else serviceInstall(plan, dry, log, run, deps.uid);
+  }
+  if (cmd === 'install' && rc === 0) out('Next: cd <your project>; claude; /kenaz:kenaz init; /kenaz:Ansuz   (Codex: run /hooks once to trust the kenaz hooks, then $kenaz status)');
+  if (cmd === 'uninstall') out('Project .kenaz/ data was left untouched.');
+  return rc;
+}
+
+if (require.main === module) process.exit(main(process.argv.slice(2)));
+module.exports = { main, verifyRuntime, healthOnce, serviceInstall, serviceRestart, restartHint, claudeVersion, loadSettings, entriesOf, norm, MIN_CLI, registerPlugin, unregisterPlugin, registerStatusline, unregisterStatusline, retireDashboardHooks, servicePlan, detectServiceMode, probeLinux, cronLine, CRON_MARK, winVbs, launchdPlist, systemdUnit, parseVersion, cmpVersion };