kenaz 0.3.21 → 0.3.23

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

@@ -0,0 +1,471 @@
+#!/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 BATTERY_PS = '$s = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -ExecutionTimeLimit ([TimeSpan]::Zero); Set-ScheduledTask -TaskName ' + TASK_NAME + ' -Settings $s';
+const linuxUser = () => { try { return os.userInfo().username; } catch (_) { return process.env.USER || ''; } };
+
+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', { windowsHide: true, encoding: 'utf8', shell: true, timeout: 15000 })
+    : spawnSync('claude', ['--version'], { windowsHide: true, 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, { windowsHide: true, 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) {
+      // Task Scheduler defaults refuse to start on battery and stop the task when going on battery:
+      // a laptop unplugged at logon never got the server (TASK_2468). Re-running install fixes an old task.
+      const b = sh('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', BATTERY_PS]);
+      if (b.status !== 0) log('WARNING: could not set the task to run on battery (exit ' + b.status + '); on a laptop the server may not start unplugged. Run in PowerShell: ' + BATTERY_PS);
+      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']); }
+    // Without linger the user service starts only at login (headless boxes: never). Best effort.
+    const u = linuxUser();
+    log('loginctl enable-linger ' + u);
+    if (!dry && sh('loginctl', ['enable-linger', u]).status !== 0) log('WARNING: could not enable linger; the server starts at boot only after you log in. Run: loginctl enable-linger ' + u + ' (may need sudo)');
+    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) {
+    const u = linuxUser();
+    const off = /Linger=no/.test(run('loginctl', ['show-user', u, '-p', 'Linger']).stdout || '');
+    return off ? { mode: 'systemd', detail: unit + '; linger is off, the server starts only after login: run loginctl enable-linger ' + u, warn: true } : { 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 };

package/core/dev/scripts/check-file-size.js

@@ -103,7 +103,7 @@ function countLines(text) {
 }
 
 function git(args, cwd) {
-  const result = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  const result = spawnSync('git', args, { windowsHide: true, cwd, encoding: 'utf8' });
   return result;
 }
 

package/core/dev/scripts/ci-feedback.js

@@ -40,7 +40,7 @@ const TASK_API = path.join(ROOT, '.collaboration', 'core', 'task-api.js');
 // ─────────────────────────────────────────
 
 function runTaskApi(...args) {
-  const result = spawnSync('node', [TASK_API, ...args], {
+  const result = spawnSync('node', [TASK_API, ...args], { windowsHide: true,
     encoding: 'utf8',
     timeout: 15000,
     cwd: ROOT,

package/core/dev/scripts/gc-agent-worktrees.js

@@ -72,11 +72,11 @@ const DRY_RUN = !process.argv.includes('--apply');
 // ─── Git helpers (GEN-008: dynamic root, never hardcoded) ────────────────────
 
 function gitRoot() {
-  return execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
+  return execSync('git rev-parse --show-toplevel', { windowsHide: true, encoding: 'utf8' }).trim();
 }
 
 function currentBranch() {
-  return execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8' }).trim();
+  return execSync('git rev-parse --abbrev-ref HEAD', { windowsHide: true, encoding: 'utf8' }).trim();
 }
 
 /**
@@ -84,7 +84,7 @@ function currentBranch() {
  * Uses exit code of `git merge-base --is-ancestor <commit> HEAD`.
  */
 function isAncestorOfHead(tipCommit) {
-  const result = spawnSync('git', ['merge-base', '--is-ancestor', tipCommit, 'HEAD'], {
+  const result = spawnSync('git', ['merge-base', '--is-ancestor', tipCommit, 'HEAD'], { windowsHide: true,
     encoding: 'utf8',
   });
   return result.status === 0;
@@ -95,7 +95,7 @@ function isAncestorOfHead(tipCommit) {
  * Each entry: { path, head, branch, locked, lockReason }
  */
 function listWorktrees() {
-  const raw = execSync('git worktree list --porcelain', { encoding: 'utf8' });
+  const raw = execSync('git worktree list --porcelain', { windowsHide: true, encoding: 'utf8' });
   const entries = [];
   let current = null;
 
@@ -199,7 +199,7 @@ function listUntrackedAgentDirs(root, trackedPaths) {
 function listDanglingAgentBranches(trackedBranches) {
   let raw = '';
   try {
-    raw = execSync('git branch --list "worktree-agent-*" --format="%(refname:short)"', { encoding: 'utf8' });
+    raw = execSync('git branch --list "worktree-agent-*" --format="%(refname:short)"', { windowsHide: true, encoding: 'utf8' });
   } catch {
     return [];
   }
@@ -209,7 +209,7 @@ function listDanglingAgentBranches(trackedBranches) {
     const b = line.trim();
     if (!b || trackedSet.has(b)) continue;
     let tip = '';
-    try { tip = execSync(`git rev-parse "${b}"`, { encoding: 'utf8' }).trim(); } catch { /* ignore */ }
+    try { tip = execSync(`git rev-parse "${b}"`, { windowsHide: true, encoding: 'utf8' }).trim(); } catch { /* ignore */ }
     out.push({ branch: b, tip, integrated: tip ? isAncestorOfHead(tip) : false });
   }
   return out;
@@ -354,7 +354,7 @@ function main() {
     // Unlock if locked (harness may have left lock even after pid is gone)
     if (wt.locked) {
       try {
-        execSync(`git worktree unlock "${wt.path}"`, { encoding: 'utf8' });
+        execSync(`git worktree unlock "${wt.path}"`, { windowsHide: true, encoding: 'utf8' });
       } catch {
         // unlock may fail if git disagrees — proceed, remove --force handles it
       }
@@ -374,7 +374,7 @@ function main() {
 
     // Remove worktree (--force bypasses remaining lock metadata)
     try {
-      execSync(`git worktree remove --force "${wt.path}"`, { encoding: 'utf8' });
+      execSync(`git worktree remove --force "${wt.path}"`, { windowsHide: true, encoding: 'utf8' });
     } catch (err) {
       console.log(` FAILED (worktree remove): ${err.message.trim()}`);
       failedCount++;
@@ -384,7 +384,7 @@ function main() {
     // Delete the branch (best-effort; branch may already be deleted or missing)
     if (wt.branch) {
       try {
-        execSync(`git branch -D "${wt.branch}"`, { encoding: 'utf8' });
+        execSync(`git branch -D "${wt.branch}"`, { windowsHide: true, encoding: 'utf8' });
       } catch {
         // Branch may already be deleted — not an error
       }
@@ -396,7 +396,7 @@ function main() {
 
   // Prune stale worktree admin dirs (idempotent, always safe)
   try {
-    execSync('git worktree prune', { encoding: 'utf8' });
+    execSync('git worktree prune', { windowsHide: true, encoding: 'utf8' });
     console.log('\n  git worktree prune  done');
   } catch (err) {
     console.log(`\n  git worktree prune  FAILED (non-fatal): ${err.message.trim()}`);
@@ -419,7 +419,7 @@ function main() {
   for (const b of danglingBranches) {
     if (!b.integrated) continue; // keep not-in-HEAD branches for salvage
     try {
-      execSync(`git branch -D "${b.branch}"`, { encoding: 'utf8' });
+      execSync(`git branch -D "${b.branch}"`, { windowsHide: true, encoding: 'utf8' });
       danglingDeleted++;
     } catch { /* already gone — not an error */ }
   }

package/core/dev/scripts/kenaz-session.js

@@ -218,7 +218,7 @@ function parseCliArgs(argv) {
 function resolveExecutableWindows(whereFn) {
   whereFn = whereFn || function runWhere() {
     try {
-      return cp.execSync('where claude', { encoding: 'utf8' });
+      return cp.execSync('where claude', { windowsHide: true, encoding: 'utf8' });
     } catch (e) {
       return '';
     }
@@ -263,13 +263,13 @@ function escapeCmdExe(exe) {
 
 function launch(exec, cwd, argv) {
   if (exec.useShell) {
-    return cp.spawn(escapeCmdExe(exec.command), argv.map(escapeCmdArg), {
+    return cp.spawn(escapeCmdExe(exec.command), argv.map(escapeCmdArg), { windowsHide: true,
       cwd,
       stdio: 'inherit',
       shell: true,
     });
   }
-  return cp.spawn(exec.command, argv, { cwd, stdio: 'inherit', shell: false });
+  return cp.spawn(exec.command, argv, { windowsHide: true, cwd, stdio: 'inherit', shell: false });
 }
 
 // ---- main ----

package/core/dev/scripts/peer-identity-e2e.js

@@ -59,12 +59,12 @@ function start(name, exe, args, env, cwd) {
 }
 async function stop(p) {
   if (!p || p.exited) return;
-  if (process.platform === 'win32') spawnSync('taskkill', ['/PID', String(p.pid), '/T', '/F'], { stdio: 'ignore' }); // our PID only
+  if (process.platform === 'win32') spawnSync('taskkill', ['/PID', String(p.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' }); // our PID only
   else p.child.kill('SIGKILL');
   await until(`${p.name} exit`, () => p.exited, 15000, 100).catch(() => {});
 }
 function sh(cmd, args, env) {
-  const r = spawnSync(cmd, args, { env: { ...process.env, ...env }, encoding: 'utf8' });
+  const r = spawnSync(cmd, args, { windowsHide: true, env: { ...process.env, ...env }, encoding: 'utf8' });
   return { code: r.status, out: `${r.stdout || ''}${r.stderr || ''}`.trim() };
 }
 function sqlite(file, readOnly = true) {
@@ -398,5 +398,5 @@ async function main() {
   return bad ? 1 : 0;
 }
 
-process.on('SIGINT', () => { for (const p of procs) if (!p.exited) { if (process.platform === 'win32') spawnSync('taskkill', ['/PID', String(p.pid), '/T', '/F'], { stdio: 'ignore' }); else p.child.kill('SIGKILL'); } process.exit(130); });
+process.on('SIGINT', () => { for (const p of procs) if (!p.exited) { if (process.platform === 'win32') spawnSync('taskkill', ['/PID', String(p.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' }); else p.child.kill('SIGKILL'); } process.exit(130); });
 main().then((c) => process.exit(c), (e) => { console.error(e); process.exit(1); });