kenaz 0.3.21 → 0.3.22

package/core/.claude/commands/Ansuz.md

@@ -5,6 +5,8 @@ ARGUMENTS 含 `[專案: X]` 或 `--project-path X` → PROJECT_PATH = X，下方
 
 你是 **Ansuz**，Kenaz 的 orchestrator：理解需求，自己動手或拆卡派給 subagent，合併前在真實路徑上驗證，然後回報。先查現況、確認 scope，再動手。
 
+用戶貼上房間 key 或要求加入/建立房間時，自己執行 `kenaz ygg join <key>` / `kenaz ygg create`（不要請用戶輸入），再轉述 status 區塊與「restart Claude Code」提示。
+
 ## Boot（一次 Bash）
 1. Turn Context 有 `[session] session_id=<id>` 就記住 `<id>`。
 2. `node .specialist/tools/ansuz-boot-fast.js`（有 `<id>` 加 `--conversation-id="<id>"`；有 PROJECT_PATH 加 `--project-path`）。

package/core/.claude/hooks/__tests__/peer-session-fill.test.js

@@ -0,0 +1,37 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const os = require('os');
+const fs = require('fs');
+// decide() writes a peer opt-in marker (TASK_2465): keep it out of the real ~/.kenaz (spawned children inherit this).
+process.env.KENAZ_PEER_OPTIN_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'kenaz-optin-test-'));
+const { decide } = require('../peer-session-fill');
+
+const base = { session_id: 'sess-123', tool_input: { to: 'n', body: 'hi' } };
+
+test('fills missing and wrong sessionId, keeps other args', () => {
+  for (const tn of ['mcp__kenaz-dashboard__kenaz_peer_send', 'mcp__plugin_kenaz_kenaz-dashboard__kenaz_peer_send']) {
+    for (const extra of [{}, { sessionId: 'wrong' }]) {
+      const out = decide({ ...base, tool_name: tn, tool_input: { ...base.tool_input, ...extra } });
+      assert.strictEqual(out.hookSpecificOutput.updatedInput.sessionId, 'sess-123');
+      assert.strictEqual(out.hookSpecificOutput.updatedInput.body, 'hi');
+    }
+  }
+});
+
+test('non-peer tools and missing session_id produce nothing', () => {
+  assert.strictEqual(decide({ ...base, tool_name: 'mcp__kenaz-dashboard__kenaz_peer_threads' }), null);
+  assert.strictEqual(decide({ ...base, tool_name: 'Bash' }), null);
+  assert.strictEqual(decide({ tool_name: 'mcp__x__kenaz_peer_send', tool_input: {} }), null);
+});
+
+test('main() prints JSON for a peer send and nothing on garbage stdin', () => {
+  const f = path.join(__dirname, '..', 'peer-session-fill.js');
+  const ok = spawnSync(process.execPath, [f], { input: JSON.stringify({ ...base, tool_name: 'mcp__a__kenaz_peer_send' }), encoding: 'utf8' });
+  assert.strictEqual(JSON.parse(ok.stdout).hookSpecificOutput.updatedInput.sessionId, 'sess-123');
+  const bad = spawnSync(process.execPath, [f], { input: '{nope', encoding: 'utf8' });
+  assert.strictEqual(bad.stdout, '');
+  assert.strictEqual(bad.status, 0);
+});

package/core/.claude/hooks/_ansuz-conversation.js

@@ -181,4 +181,35 @@ function taskIdNeedles(id) {
   return /^\d+$/.test(s) ? [`TASK_${s}`] : [s];
 }
 
-module.exports = { isAnsuzConversation, lineIsAnsuzEntry, toolUseMentionsAny, taskIdNeedles, MARKERS };
+// TASK_2465: peer collaborator opt-in. A session is a collaborator when it is Ansuz, OR it ran
+// `ygg join`/`ygg create` / called kenaz_peer_send (peer-session-fill.js writes the marker), OR it was started
+// by `kenaz launch` (KENAZ_PEER_OPTIN=1). One marker file per session id under ~/.kenaz/peer-optin, expiring,
+// so mod / turn-context / Codex shim read it without parsing transcripts. Never opted in -> false (privacy).
+const OPTIN_TTL_MS = 24 * 3600 * 1000;
+const SID_OK = /^[A-Za-z0-9_-]{1,128}$/;
+function optinDir() {
+  if (process.env.KENAZ_PEER_OPTIN_DIR) return process.env.KENAZ_PEER_OPTIN_DIR;
+  return path.join(require('os').homedir(), '.kenaz', 'peer-optin');
+}
+function markPeerOptIn(sessionId, now = Date.now()) {
+  const sid = String(sessionId || '');
+  if (!SID_OK.test(sid)) return false;
+  try {
+    fs.mkdirSync(optinDir(), { recursive: true });
+    fs.writeFileSync(path.join(optinDir(), sid + '.json'), JSON.stringify({ ts: now }));
+    return true;
+  } catch { return false; }
+}
+function isPeerOptedIn(sessionId, now = Date.now()) {
+  // kenaz launch's env opt-in is inherited by children: only the interactive entrypoint honours it, so a
+  // `claude -p` worker (sdk-cli) started inside a launched session never takes the human's peer mail.
+  if (process.env.KENAZ_PEER_OPTIN === '1' && process.env.CLAUDE_CODE_ENTRYPOINT === 'cli') return true;
+  const sid = String(sessionId || '');
+  if (!SID_OK.test(sid)) return false;
+  try {
+    const m = JSON.parse(fs.readFileSync(path.join(optinDir(), sid + '.json'), 'utf8'));
+    return Number.isFinite(m.ts) && now - m.ts >= 0 && now - m.ts < OPTIN_TTL_MS;
+  } catch { return false; }
+}
+
+module.exports = { isAnsuzConversation, lineIsAnsuzEntry, toolUseMentionsAny, taskIdNeedles, MARKERS, markPeerOptIn, isPeerOptedIn, OPTIN_TTL_MS };

package/core/.claude/hooks/peer-optin.test.js

@@ -0,0 +1,74 @@
+'use strict';
+// TASK_2465: peer collaboration opt-in marker (writer = peer-session-fill.js, reader = turn-context / mod / Codex shim).
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'kenaz-optin-'));
+process.env.KENAZ_PEER_OPTIN_DIR = dir;
+delete process.env.KENAZ_PEER_OPTIN;
+const { markPeerOptIn, isPeerOptedIn, OPTIN_TTL_MS } = require('./_ansuz-conversation');
+const { decide } = require('./peer-session-fill');
+
+test('no marker -> not opted in (privacy)', () => {
+  assert.equal(isPeerOptedIn('plain-session'), false);
+  assert.equal(isPeerOptedIn(''), false);
+  assert.equal(isPeerOptedIn(undefined), false);
+});
+
+test('kenaz_peer_send writes the marker for that session only', () => {
+  const out = decide({ tool_name: 'mcp__kenaz-dashboard__kenaz_peer_send', session_id: 'sess-a', tool_input: { to: 'x' } });
+  assert.equal(out.hookSpecificOutput.updatedInput.sessionId, 'sess-a'); // sessionId fill unchanged
+  assert.equal(isPeerOptedIn('sess-a'), true);
+  assert.equal(isPeerOptedIn('sess-b'), false);
+});
+
+test('ygg join / ygg create via Bash write the marker; other Bash commands do not', () => {
+  assert.equal(decide({ tool_name: 'Bash', session_id: 'sess-j', tool_input: { command: 'kenaz ygg join room-1' } }), null);
+  assert.equal(isPeerOptedIn('sess-j'), true);
+  decide({ tool_name: 'Bash', session_id: 'sess-c', tool_input: { command: 'node plugins/kenaz/scripts/ygg.js create demo' } });
+  assert.equal(isPeerOptedIn('sess-c'), true);
+  decide({ tool_name: 'Bash', session_id: 'sess-n', tool_input: { command: 'kenaz ygg status' } });
+  decide({ tool_name: 'Bash', session_id: 'sess-n', tool_input: { command: 'ls' } });
+  assert.equal(isPeerOptedIn('sess-n'), false);
+});
+
+test('only a real ygg invocation opts in; grep/echo/git mentions do not', () => {
+  const { yggInvocation } = require('./peer-session-fill');
+  for (const c of ['kenaz ygg join r', 'npx -y kenaz@1.2 ygg create x', 'node plugins/kenaz/scripts/ygg.js join r',
+    'cd x && kenaz ygg join r', 'KENAZ_X=1 kenaz ygg create r | cat', 'ls; kenaz ygg join r']) assert.equal(yggInvocation(c), true, c);
+  for (const c of ['grep "ygg join" docs', 'echo kenaz ygg join', 'git log -S"ygg create"', 'cat ygg.js', 'kenaz ygg status',
+    'grep -r ygg join . | wc -l', "echo 'x' # kenaz ygg join"]) assert.equal(yggInvocation(c), false, c);
+});
+
+test('marker expires', () => {
+  const t0 = Date.now();
+  markPeerOptIn('sess-e', t0);
+  assert.equal(isPeerOptedIn('sess-e', t0 + OPTIN_TTL_MS - 1000), true);
+  assert.equal(isPeerOptedIn('sess-e', t0 + OPTIN_TTL_MS + 1000), false);
+});
+
+test('unsafe session ids are refused (no path traversal)', () => {
+  assert.equal(markPeerOptIn('../evil'), false);
+  assert.equal(isPeerOptedIn('../evil'), false);
+});
+
+test('KENAZ_PEER_OPTIN=1 (kenaz launch) opts in without a marker; =0 does not', () => {
+  process.env.KENAZ_PEER_OPTIN = '1';
+  process.env.CLAUDE_CODE_ENTRYPOINT = 'sdk-cli';
+  assert.equal(isPeerOptedIn('never-marked'), false); // claude -p worker inherits the env
+  process.env.CLAUDE_CODE_ENTRYPOINT = 'cli';
+  assert.equal(isPeerOptedIn('never-marked'), true);
+  process.env.KENAZ_PEER_OPTIN = '0';
+  assert.equal(isPeerOptedIn('never-marked'), false);
+  delete process.env.KENAZ_PEER_OPTIN;
+  delete process.env.CLAUDE_CODE_ENTRYPOINT;
+});
+
+test('kenaz launch plan sets KENAZ_PEER_OPTIN=1 unless the caller set 0', () => {
+  const { plan } = require('../../.formation/bifrost/provider-launch.js');
+  const env = { DEEPSEEK_API_KEY: 'k' };
+  assert.equal(plan(['--provider', 'deepseek'], env, os.tmpdir(), null).env.KENAZ_PEER_OPTIN, '1');
+  assert.equal(plan(['--provider', 'deepseek'], { ...env, KENAZ_PEER_OPTIN: '0' }, os.tmpdir(), null).env.KENAZ_PEER_OPTIN, '0');
+});

package/core/.claude/hooks/peer-session-fill.js

@@ -0,0 +1,38 @@
+'use strict';
+// PreToolUse(kenaz_peer_send, any MCP server prefix): fill the tool's `sessionId` with the hook payload's
+// session_id, overriding whatever the model passed (TASK_2462). Reply affinity (TASK_2285) routes a reply back
+// to the asking session only when the outbound row carries that id; the harness knows it, the model should not
+// have to. Fails open: any error or missing id -> no output, the call proceeds unchanged.
+const PEER_SEND = /^mcp__.*kenaz_peer_send$/;
+
+// An actual invocation only: a `;`/`&&`/`||`/`|`/newline-separated segment (after optional VAR=x assignments) that starts with
+// `kenaz ygg join|create`, `npx [-y] kenaz[@ver] ygg join|create` or `node <path>/ygg.js join|create`.
+// Mentions inside grep/echo/git arguments or quotes do not count.
+const YGG_CMD = /^(?:[A-Za-z_]\w*=\S*\s+)*(?:kenaz(?:\.cmd)?\s+ygg|npx\s+(?:-y\s+)?kenaz(?:@\S+)?\s+ygg|node\s+\S*ygg\.js)\s+(?:join|create)(?:\s|$)/;
+function yggInvocation(cmd) {
+  return String(cmd || '').split(/\|\||&&|[;|&\n]/).some((seg) => YGG_CMD.test(seg.trim()));
+}
+
+function decide(input) {
+  // TASK_2465: opt-in marker (see _ansuz-conversation.js): `ygg join/create` via Bash, or any peer send.
+  try {
+    const sid0 = input && typeof input.session_id === 'string' ? input.session_id.trim() : '';
+    const cmd = input && input.tool_name === 'Bash' && input.tool_input ? String(input.tool_input.command || '') : '';
+    if (sid0 && (PEER_SEND.test(String(input.tool_name || '')) || yggInvocation(cmd))) require('./_ansuz-conversation').markPeerOptIn(sid0);
+  } catch (_) { /* marker is best-effort */ }
+  if (!input || !PEER_SEND.test(String(input.tool_name || ''))) return null;
+  const sid = typeof input.session_id === 'string' ? input.session_id.trim() : '';
+  if (!sid) return null;
+  const ti = input.tool_input && typeof input.tool_input === 'object' ? input.tool_input : {};
+  return { hookSpecificOutput: { hookEventName: 'PreToolUse', updatedInput: Object.assign({}, ti, { sessionId: sid }) } };
+}
+
+function main() {
+  try {
+    const out = decide(JSON.parse(require('fs').readFileSync(0, 'utf8') || '{}'));
+    if (out) process.stdout.write(JSON.stringify(out));
+  } catch (_) { /* fail open */ }
+}
+
+if (require.main === module) main();
+module.exports = { decide, main, yggInvocation };

package/core/.claude/hooks/turn-context.js

@@ -214,14 +214,15 @@ const sessionLine = peerHookPayload.session_id
     fs.renameSync(tmpPath, STATE_PATH);
   } catch { /* best-effort state write */ }
 
-  // 2. TASK_2122 — Peer Ansuz MVP: undelivered peer messages, Ansuz sessions
+  // 2. TASK_2122 — Peer Ansuz MVP: undelivered peer messages, collaborator sessions
   // only (DESIGN.md §3.4 — a plain Claude Code session sharing this project
-  // dir must never see another user's collaborator traffic).
+  // dir must never see another user's collaborator traffic). TASK_2465: collaborator =
+  // Ansuz, or opted in (kenaz_peer_send / ygg join|create marker, or `kenaz launch`).
   let peerText = '';
   let waitingText = '';
   try {
-    const { isAnsuzConversation } = require('./_ansuz-conversation');
-    if (isAnsuzConversation(peerHookPayload.transcript_path, projectDir)) {
+    const { isAnsuzConversation, isPeerOptedIn } = require('./_ansuz-conversation');
+    if (isPeerOptedIn(peerHookPayload.session_id) || isAnsuzConversation(peerHookPayload.transcript_path, projectDir)) {
       // TASK_2226: a session whose kenaz-peer mod is alive gets its peer
       // messages from the mod (peek -> submit -> ack-by-id); pulling here too
       // would take-and-ack them out from under it. Fail-open: no session_id,

package/core/.claude/settings.json

@@ -72,6 +72,15 @@
         ],
         "matcher": "mcp__kenaz-dashboard__.*|Read|Edit|Write"
       },
+      {
+        "matcher": "mcp__.*kenaz_peer_send|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"const d=process.env.CLAUDE_PROJECT_DIR;process.chdir(d);require(d+'/.claude/hooks/peer-session-fill.js').main()\""
+          }
+        ]
+      },
       {
         "matcher": "Agent|Task",
         "hooks": [

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

@@ -65,6 +65,23 @@ async function peekPeerContext(p) {
   } catch (err) { console.error('[codex-hook-shim] peer pull err:', err.message); return { text: '', ids: [], root: '' }; }
 }
 
+// TASK_2465: an active room = the server's yggdrasil config for the resolved root lists its effective room key in
+// collaboration_projects (the activation). .kenaz/yggdrasil.yaml alone is committed repo config and proves nothing.
+// Fail closed: server down, slow or odd answer -> no pull.
+async function inActiveRoom(cwd, request = peerRequest) {
+  try {
+    const root = resolvePeerProjectRoot(process.env.KENAZ_CONSOLIDATE_ROOT || cwd);
+    if (!root) return false;
+    const cfg = await request('GET', '/api/yggdrasil/config?projectPath=' + encodeURIComponent(root));
+    const key = cfg && typeof cfg.effective_project_key === 'string' ? cfg.effective_project_key : '';
+    return !!key && Array.isArray(cfg.collaboration_projects) && cfg.collaboration_projects.includes(key);
+  } catch { return false; }
+}
+async function wantsPeerPull(env, argv, cwd, request) {
+  if (env.KENAZ_PEER_PULL === '0') return false;
+  return env.KENAZ_PEER_PULL === '1' || (argv || []).includes('--pull') || inActiveRoom(cwd, request);
+}
+
 function ackPeer(root, ids) {
   return ids.length ? peerRequest('POST', '/api/peer/ack', { projectPath: root, ids }) : Promise.resolve(null);
 }
@@ -146,9 +163,9 @@ async function main() {
     const cb = rest.find((a) => typeof a === 'function'); if (cb) cb();
     return true;
   };
-  // Pull when launch.js set KENAZ_PEER_PULL=1 or the registered hook carries --pull (independently opened
-  // session); KENAZ_PEER_PULL=0 (headless relay) always wins.
-  const wantPull = process.env.KENAZ_PEER_PULL !== '0' && (process.env.KENAZ_PEER_PULL === '1' || (process.argv || []).includes('--pull'));
+  // Pull when launch.js set KENAZ_PEER_PULL=1, the registered hook carries --pull (independently opened
+  // session), or (TASK_2465) the project is in an active room; KENAZ_PEER_PULL=0 (headless relay) always wins.
+  const wantPull = await wantsPeerPull(process.env, process.argv, p.cwd || process.cwd());
   const peerPeek = ev === 'UserPromptSubmit' && mode === 'full' && wantPull ? peekPeerContext(p) : null;
   try {
     const pr = handleHookEvent(payload);
@@ -187,4 +204,4 @@ async function main() {
 }
 
 if (require.main === module) main();
-module.exports = { peekPeerContext, ackPeer, writeUserPromptContext, frameForCodex };
+module.exports = { wantsPeerPull, inActiveRoom, peekPeerContext, ackPeer, writeUserPromptContext, frameForCodex };

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/KENAZ_CORE_VERSION

@@ -1 +1 @@
-0.3.21
+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 };

package/core/plugins/kenaz/commands/Ansuz.md

@@ -5,6 +5,8 @@ ARGUMENTS 含 `[專案: X]` 或 `--project-path X` → PROJECT_PATH = X，下方
 
 你是 **Ansuz**，Kenaz 的 orchestrator：理解需求，自己動手或拆卡派給 subagent，合併前在真實路徑上驗證，然後回報。先查現況、確認 scope，再動手。
 
+用戶貼上房間 key 或要求加入/建立房間時，自己執行 `kenaz ygg join <key>` / `kenaz ygg create`（不要請用戶輸入），再轉述 status 區塊與「restart Claude Code」提示。
+
 ## Boot（一次 Bash）
 1. Turn Context 有 `[session] session_id=<id>` 就記住 `<id>`。
 2. `node "${CLAUDE_PLUGIN_ROOT}/hooks/core-resolve.js" .specialist/tools/ansuz-boot-fast.js`（有 `<id>` 加 `--conversation-id="<id>"`；有 PROJECT_PATH 加 `--project-path`）。

package/core/plugins/kenaz/guidance.md

@@ -1,5 +1,6 @@
 [Kenaz plugin: mode full] Kenaz MCP tools (kenaz-dashboard) are available when kenaz-server runs on localhost:18080.
 - Code navigation: kenaz_lsp_callers / kenaz_lsp_references / kenaz_lsp_definition / kenaz_lsp_symbols (always pass projectPath). Text search: Grep/Glob.
 - Collaboration: kenaz_peer_send / kenaz_peer_threads (other sessions, other machines, Codex), /kenaz ygg status|join.
+- Rooms: when the user pastes a room key or asks to join/create a room, run `kenaz ygg join <key>` / `kenaz ygg create` yourself (never ask them to type it), then relay the status block and any "restart Claude Code" note.
 - Reply in the user's language. Commands: /Ansuz, /Amelia, /review, /security, /incident, /spec.
 - Switch: /kenaz off | assist | full (or env KENAZ_MODE). off disables every Kenaz hook.

package/core/plugins/kenaz/hooks/hooks.json

@@ -51,6 +51,15 @@
           }
         ]
       },
+      {
+        "matcher": "mcp__.*kenaz_peer_send|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/kenaz-hook.js\" peer-session-fill"
+          }
+        ]
+      },
       {
         "matcher": "Agent|Task",
         "hooks": [

package/core/plugins/kenaz/hooks/kenaz-hook.js

@@ -33,6 +33,7 @@ const HOOKS = {
   'synapse-first':  { kind: 'script', file: 'synapse-first-investigation.js', minMode: 'full' },
   'memory-guard':   { kind: 'script', file: 'memory-guard.js', call: 'main', minMode: 'full' },
   'vendor-agent-guard': { kind: 'script', file: 'vendor-agent-guard.js', call: 'main', minMode: 'assist' },
+  'peer-session-fill': { kind: 'script', file: 'peer-session-fill.js', call: 'main', minMode: 'assist' },
   'task-bridge':    { kind: 'script', file: 'task-bridge.js', minMode: 'assist' },
 };
 

package/core/plugins/kenaz/scripts/ygg.js

@@ -5,6 +5,8 @@
 // /api/yggdrasil/config + /api/peer/status (same per-project/global key rules as the Dashboard,
 // TASK_2321/2349). k-cli `ygg` shells out to this file - the one implementation.
 const path = require('path');
+const fs = require('fs');
+const os = require('os');
 
 const BASE = () => 'http://127.0.0.1:' + (process.env.KENAZ_HTTP_PORT || process.env.KENAZ_BACKEND_PORT || '18080');
 
@@ -86,6 +88,33 @@ function buildStatus(cfg, relay, peer) {
   };
 }
 
+// TASK_2461: push needs the kenaz-peer plugin loaded by Claude Code (only in Ansuz sessions). join/create
+// leave the node ready: register kenaz-peer in ~/.claude/settings.json when missing (same writer as the
+// installer). Returns {state: 'ok'|'added'|'missing'|'skipped'|'error', note}. Never throws.
+function loadInstaller() {
+  for (const p of ['../../../dashboard/scripts/install-kenaz-cli.js', '../../../packages/kenaz/vendor/install-kenaz-cli.js']) {
+    try { return require(path.join(__dirname, p)); } catch (e) { if (e.code !== 'MODULE_NOT_FOUND') throw e; }
+  }
+  return null;
+}
+function peerPlugin(home, register, version) {
+  try {
+    const inst = loadInstaller();
+    if (!inst) return { state: 'skipped', note: 'installer not found' };
+    const settings = path.join(home, '.claude', 'settings.json');
+    if (!fs.existsSync(path.join(home, '.claude'))) return { state: 'skipped', note: 'claude is not installed' };
+    const ver = version === undefined ? inst.claudeVersion() : version;
+    if (ver && inst.cmpVersion(ver, inst.MIN_CLI) < 0) return { state: 'skipped', note: 'claude ' + ver.join('.') + ' < ' + inst.MIN_CLI.join('.') + ' (run `claude update`)' };
+    const core = path.resolve(process.env.KENAZ_CORE_DIR || path.join(__dirname, '..', '..', '..'));
+    const dir = path.join(core, 'plugins', 'kenaz-peer');
+    const list = inst.entriesOf(inst.loadSettings(settings));
+    if (list.some((e) => inst.norm(e) === inst.norm(dir))) return { state: 'ok', note: 'kenaz-peer plugin is registered' };
+    if (!register || !fs.existsSync(dir)) return { state: 'missing', note: 'kenaz-peer plugin is not registered in ' + settings + (fs.existsSync(dir) ? ' (run `kenaz ygg join <key>` or `kenaz install`)' : ' (run `npx kenaz@latest install`)') };
+    inst.registerPlugin(settings, dir, false);
+    return { state: 'added', note: 'registered the kenaz-peer plugin in ' + settings + '; restart Claude Code (new session) for it to load, then run /Ansuz for idle push' };
+  } catch (e) { return { state: 'error', note: 'could not check the kenaz-peer plugin: ' + e.message }; }
+}
+
 function renderStatus(s) {
   const L = [
     'Yggdrasil room:   ' + s.room,
@@ -102,14 +131,19 @@ function renderStatus(s) {
     'Last poll:        ' + (s.last_poll_at ? s.last_poll_at + (s.last_poll_ok === false ? ' (FAILED)' : ' (ok)') : 'none yet'),
     'Delivery:         ' + s.delivery_mode + (s.sessions.length ? '' : ' (no live sessions)'),
   ];
-  for (const x of s.sessions) L.push('  - ' + x.agent + ' ' + String(x.session_id).slice(0, 8) + ': ' + x.delivery_mode);
+  for (const x of s.sessions) L.push('  ' + (x.name || x.agent) + ' (' + String(x.session_id).slice(0, 8) + ') - ' + x.delivery_mode);
   if (s.created) {
     L.push('', 'New team key (shown once, save it): ' + s.created.key + (s.created.team_name ? '  [' + s.created.team_name + ']' : ''));
     L.push('share with teammates: kenaz ygg join ' + s.created.key);
   }
   if (s.same_name_warning) L.push('WARNING:          ' + s.same_name_warning);
   if (s.room_warning) L.push('WARNING:          ' + s.room_warning);
-  if (s.delivery_note) L.push('Note:             ' + s.delivery_note);
+  const pl = s.plugin;
+  if (pl && ['added', 'missing', 'error'].includes(pl.state)) L.push('Push plugin:      ' + pl.note);
+  // The server cannot know whether the plugin is registered; when this machine knows it is, do not repeat "register it".
+  const stale = pl && (pl.state === 'ok' || pl.state === 'added') && /register the kenaz-peer plugin|may not be registered/.test(s.delivery_note || '');
+  if (stale) L.push('Note:             No push channel yet: the kenaz-peer plugin is registered but only serves Ansuz sessions. Run /Ansuz or /kenaz:Ansuz in this session' + (pl.state === 'added' ? ' after restarting Claude Code' : '') + ' for idle push; until then messages arrive on your next prompt.');
+  else if (s.delivery_note) L.push('Note:             ' + s.delivery_note);
   return L.join('\n');
 }
 
@@ -200,7 +234,7 @@ async function leave(dir) {
 }
 
 async function main(argv) {
-  const rest = []; let dir = process.env.CLAUDE_PROJECT_DIR || process.cwd(); let scope = 'project'; let json = false; let name = '';
+  const rest = []; let dir = process.env.CLAUDE_PROJECT_DIR || process.cwd(); let scope = 'project'; let json = false; let name = ''; let home = os.homedir();
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--project-path' && argv[i + 1]) dir = argv[++i];
@@ -208,6 +242,7 @@ async function main(argv) {
     else if (a === '--global') scope = 'global';
     else if (a === '--project') scope = 'project';
     else if (a === '--json') json = true;
+    else if (a === '--home' && argv[i + 1]) home = argv[++i];
     else if (a === '--name' && argv[i + 1]) name = argv[++i];
     else if (a.startsWith('--name=')) name = a.slice(7);
     else rest.push(a);
@@ -221,6 +256,7 @@ async function main(argv) {
     else if (sub === 'leave') s = await leave(dir);
     else if (sub === 'status') s = await status(dir);
     else throw new Error('unknown ygg subcommand: ' + sub + ' (join <key> | create [--name N] | status | leave)');
+    s.plugin = peerPlugin(path.resolve(home), sub === 'join' || sub === 'create');
   } catch (e) {
     console.error('ygg: ' + e.message + (/fetch failed|timeout|abort/i.test(e.message) ? ' (is the Kenaz backend running on ' + BASE() + '?)' : ''));
     process.exit(1);
@@ -228,5 +264,5 @@ async function main(argv) {
   console.log(json ? JSON.stringify(s, null, 2) : renderStatus(s));
 }
 
-module.exports = { nodeIsOnline, maskKey, buildStatus, renderStatus, join, createTeam };
+module.exports = { peerPlugin, nodeIsOnline, maskKey, buildStatus, renderStatus, join, createTeam };
 if (require.main === module) main(process.argv.slice(2));

package/core/plugins/kenaz/scripts/ygg.test.js

@@ -29,10 +29,10 @@ async function withBackend(persist, fn) {
   try { return await fn(srv.address().port); } finally { srv.close(); }
 }
 
-function cli(port, dir) {
+function cli(port, dir, home = fs.mkdtempSync(path.join(os.tmpdir(), 'ygg-home-'))) { // never the real ~/.claude
   return new Promise((resolve) => {
-    const c = spawn(process.execPath, [YGG, 'join', 'ygk_abc', '--project-path', dir],
-      { env: Object.assign({}, process.env, { KENAZ_HTTP_PORT: String(port) }) });
+    const c = spawn(process.execPath, [YGG, 'join', 'ygk_abc', '--project-path', dir].concat(['--home', home]),
+      { env: Object.assign({}, process.env, { KENAZ_HTTP_PORT: String(port), KENAZ_CORE_DIR: CORE }) });
     let out = ''; let err = '';
     c.stdout.on('data', (d) => { out += d; }); c.stderr.on('data', (d) => { err += d; });
     c.on('close', (code) => resolve({ code, out, err }));
@@ -70,3 +70,63 @@ test('join refuses when the backend reports no effective_project_key (nothing to
     assert.match(r.err, /cannot work out this project's room/);
   } finally { srv.close(); }
 });
+
+// TASK_2461: join leaves the node push-ready (kenaz-peer registered), touching only the --home it is given.
+// a temp core: the checkout may itself be a .kenaz-worktrees path, which the installer refuses to register
+const CORE = fs.mkdtempSync(path.join(os.tmpdir(), 'ygg2461-core-'));
+const CORE_PEER = path.join(CORE, 'plugins', 'kenaz-peer');
+fs.mkdirSync(CORE_PEER, { recursive: true });
+function tempHome(settings) {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ygg2461-'));
+  fs.mkdirSync(path.join(home, '.claude'));
+  const f = path.join(home, '.claude', 'settings.json');
+  fs.writeFileSync(f, settings);
+  return { home, f };
+}
+
+test('join registers a missing kenaz-peer in the temp settings.json, names the restart, and is idempotent', async () => {
+  const { home, f } = tempHome(JSON.stringify({ env: { CLAUDE_CODE_PLUGIN_DIRS: '/other/plugin' } }));
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ygg2461-'));
+  await withBackend(true, async (port) => {
+    const r = await cli(port, dir, home);
+    assert.strictEqual(r.code, 0, r.err);
+    assert.ok(JSON.parse(fs.readFileSync(f, 'utf8')).env.CLAUDE_CODE_PLUGIN_DIRS.split(path.delimiter).includes(CORE_PEER));
+    assert.match(r.out, /restart Claude Code/);
+    const after = fs.readFileSync(f, 'utf8');
+    const r2 = await cli(port, dir, home);
+    assert.strictEqual(r2.code, 0, r2.err);
+    assert.strictEqual(fs.readFileSync(f, 'utf8'), after);
+    assert.doesNotMatch(r2.out, /restart Claude Code/);
+  });
+});
+
+test('join leaves settings.json byte-identical when kenaz-peer is already registered', async () => {
+  const txt = JSON.stringify({ env: { CLAUDE_CODE_PLUGIN_DIRS: CORE_PEER } });
+  const { home, f } = tempHome(txt);
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ygg2461-'));
+  await withBackend(true, async (port) => {
+    const r = await cli(port, dir, home);
+    assert.strictEqual(r.code, 0, r.err);
+    assert.strictEqual(fs.readFileSync(f, 'utf8'), txt);
+  });
+});
+
+test('rendered status: registered but not Ansuz never says to register the plugin; unregistered says what to do', () => {
+  const { renderStatus, buildStatus } = require('./ygg.js');
+  const base = buildStatus({ effective_project_key: 'r', node_name: 'n', enabled: true, collaboration_projects: ['r'] }, { connected: true, nodes: [] },
+    { delivery_mode: 'pull-on-prompt', delivery_note: 'No push channel. No kenaz-peer plugin heartbeat seen: register the kenaz-peer plugin, then run /Ansuz' });
+  const ok = renderStatus(Object.assign({}, base, { plugin: { state: 'ok', note: 'x' } }));
+  assert.doesNotMatch(ok, /register the kenaz-peer plugin/);
+  assert.match(ok, /only serves Ansuz sessions/);
+  const miss = renderStatus(Object.assign({}, base, { plugin: { state: 'missing', note: 'kenaz-peer plugin is not registered in S (run `kenaz ygg join <key>` or `kenaz install`)' } }));
+  assert.match(miss, /Push plugin:.*not registered/);
+});
+
+test('TASK_2463: rendered status shows each session as name (short id) - mode', () => {
+  const { renderStatus, buildStatus } = require('./ygg.js');
+  const st = buildStatus({ effective_project_key: 'r', node_name: 'n', enabled: true, collaboration_projects: ['r'] }, { connected: true, nodes: [] },
+    { delivery_mode: 'push', sessions: [{ session_id: 'abcdef123456', agent: 'claude', name: 'my-work', delivery_mode: 'push' }, { session_id: 'zzzzzzzz9999', agent: 'codex', delivery_mode: 'pull-on-prompt' }] });
+  const out = renderStatus(st);
+  assert.match(out, /^ {2}my-work \(abcdef12\) - push$/m);
+  assert.match(out, /^ {2}codex \(zzzzzzzz\) - pull-on-prompt$/m);
+});

package/core/plugins/kenaz-peer/hooks/register.test.ts

@@ -2,14 +2,17 @@ import { test, expect, mock } from 'claude-code/testing'
 
 const msg = { id: 'm1', framed: '[Peer message] hello' }
 
-function setup(on: any, rows: () => unknown[]) {
+function setup(on: any, rows: () => unknown[], marker?: () => string | null) {
   const calls: string[] = []
   let delivered = false
   on('session.start', async (_$: any, e: any) => ({ cwd: e.cwd }))
   on('session.id', async () => ({ value: 'sess-1' }))
   on('session.cwd', async () => ({ value: '/tmp/proj' }))
   on('session.messages', async () => ({ value: rows() }))
-  on('fs.read', async () => ({ deny: 'no pin' }))
+  on('fs.read', async (_$: any, e: any) => {
+    const m = marker?.()
+    return String(e.path ?? e.file ?? '').endsWith('/sess-1.json') && m ? { value: m } : { deny: 'no pin' }
+  })
   on('http.fetch', async (_$: any, e: any) => {
     const url = String(e.url)
     calls.push(`${e.init?.method ?? 'GET'} ${url}`)
@@ -144,3 +147,57 @@ test('plugin-namespaced /kenaz:Ansuz also activates delivery', async ($, on) =>
   expect(calls[0]).toContain('POST http://127.0.0.1:18080/api/peer/mod-heartbeat')
   expect(submits.length).toBe(1)
 })
+
+// TASK_2465: collaboration opt-in (marker written by peer-session-fill.js, or KENAZ_PEER_OPTIN=1 from kenaz launch).
+const PLAIN = [{ role: 'user', content: 'hello there' }]
+const MARKER_ENV = { CLAUDE_CODE_ENTRYPOINT: 'cli', KENAZ_PEER_OPTIN_DIR: '/m' }
+
+test('TASK_2465 privacy: plain session without opt-in never heartbeats, peeks or submits', async ($, on) => {
+  const clock = mock.clock(on)
+  mock.env(on, MARKER_ENV)
+  const { calls, submits } = setup(on, () => PLAIN, () => null)
+  await $.session.start(START)
+  await clock.advance(15_000)
+  expect(calls.length).toBe(0)
+  expect(submits.length).toBe(0)
+})
+
+test('TASK_2465: opt-in marker makes a plain session heartbeat and receive push', async ($, on) => {
+  const clock = mock.clock(on)
+  mock.env(on, MARKER_ENV)
+  const { calls, submits } = setup(on, () => PLAIN, () => JSON.stringify({ ts: Date.now() }))
+  await $.session.start(START)
+  await clock.advance(5_000)
+  await clock.advance(5_000)
+  expect(calls[0]).toContain('POST http://127.0.0.1:18080/api/peer/mod-heartbeat')
+  expect(submits.length).toBe(1)
+})
+
+test('TASK_2465: an expired marker is not an opt-in', async ($, on) => {
+  const clock = mock.clock(on)
+  mock.env(on, MARKER_ENV)
+  const { calls, submits } = setup(on, () => PLAIN, () => JSON.stringify({ ts: Date.now() - 25 * 3600 * 1000 }))
+  await $.session.start(START)
+  await clock.advance(15_000)
+  expect(calls.length).toBe(0)
+  expect(submits.length).toBe(0)
+})
+
+test('TASK_2465: KENAZ_PEER_OPTIN=1 does not opt in a claude -p worker (sdk-cli)', async ($, on) => {
+  const clock = mock.clock(on)
+  mock.env(on, { CLAUDE_CODE_ENTRYPOINT: 'sdk-cli', KENAZ_PEER_OPTIN: '1' })
+  const { calls } = setup(on, () => PLAIN)
+  await $.session.start(START)
+  await clock.advance(15_000)
+  expect(calls.length).toBe(0)
+})
+
+test('TASK_2465: KENAZ_PEER_OPTIN=1 (kenaz launch) opts a plain session in', async ($, on) => {
+  const clock = mock.clock(on)
+  mock.env(on, { CLAUDE_CODE_ENTRYPOINT: 'cli', KENAZ_PEER_OPTIN: '1' })
+  const { calls } = setup(on, () => PLAIN)
+  await $.session.start(START)
+  await clock.advance(5_000)
+  await clock.advance(5_000)
+  expect(calls[0]).toContain('POST http://127.0.0.1:18080/api/peer/mod-heartbeat')
+})

package/core/plugins/kenaz-peer/hooks/register.ts

@@ -20,6 +20,8 @@ let cwd = ''
 let beaten = false
 let busy = false
 let ansuz = false // sticky: once a session is Ansuz it never flips back
+let entrypoint = '' // CLAUDE_CODE_ENTRYPOINT; the env opt-in counts only for the interactive 'cli'
+let optinLive = false // TASK_2465: opt-in marker seen on the last check (expires, so not sticky)
 // Same markers as .claude/hooks/_ansuz-conversation.js (turn-context's gate).
 const MARKERS = [
   '<command-name>/Ansuz</command-name>',
@@ -65,8 +67,28 @@ async function project($: any): Promise<string> {
 }
 
 // Only USER-role text counts (strings or text blocks); tool results do not.
+// TASK_2465: opt-in marker written by .claude/hooks/peer-session-fill.js (kenaz_peer_send / ygg join|create) under
+// <KENAZ_PEER_OPTIN_DIR | ~/.kenaz/peer-optin>/<session id>.json, or KENAZ_PEER_OPTIN=1 (kenaz launch). 24 h expiry.
+const OPTIN_TTL_MS = 24 * 3600 * 1000
+async function optedIn($: any): Promise<boolean> {
+  try {
+    if (entrypoint === 'cli' && (await $.env.get('KENAZ_PEER_OPTIN')) === '1') return true
+    if (!/^[A-Za-z0-9_-]{1,128}$/.test(sessionId)) return false
+    let dir = (await $.env.get('KENAZ_PEER_OPTIN_DIR')) ?? ''
+    if (!dir) {
+      const home = (await $.env.get('USERPROFILE')) ?? (await $.env.get('HOME')) ?? ''
+      if (!home) return false
+      dir = `${home}/.kenaz/peer-optin`
+    }
+    const f = await $.fs.read(`${dir}/${sessionId}.json`)
+    const age = Date.now() - Number(JSON.parse(typeof f === 'string' ? f : f.text).ts)
+    return age >= 0 && age < OPTIN_TTL_MS
+  } catch { return false }
+}
+
 async function isAnsuz($: any): Promise<boolean> {
   if (ansuz) return true
+  if ((optinLive = await optedIn($))) return true
   try {
     const rows = await $.session.messages({ as: 'api' })
     for (const m of rows) {
@@ -163,10 +185,11 @@ export const register: Register = on => {
       ep = (await $.env.get('CLAUDE_CODE_ENTRYPOINT')) ?? ''
       optIn = (await $.env.get('KENAZ_IN_SDK')) ?? ''
     } catch { /* env unreadable: behave as an interactive session */ }
+    entrypoint = ep
     if (ep.startsWith('sdk-') && ep !== 'sdk-cli' && optIn !== '1') return next(e)
     sessionId = String(await $.session.id())
     cwd = String(await $.session.cwd())
-    $.clock.every(HEARTBEAT_MS, () => { if (ansuz) void beat($) })
+    $.clock.every(HEARTBEAT_MS, () => { if (ansuz || optinLive) void beat($) })
     $.clock.every(POLL_MS, () => { void cycle($) })
     return next(e)
   })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kenaz",
-  "version": "0.3.21",
+  "version": "0.3.22",
   "description": "Install Kenaz (plugin, hooks, kenaz-server) for Claude Code and Codex: npx kenaz install",
   "bin": {
     "kenaz": "bin/kenaz.js"
@@ -20,11 +20,11 @@
     "test": "node --test lib/cli.test.js"
   },
   "optionalDependencies": {
-    "@kenazai/server-darwin-arm64": "0.3.21",
-    "@kenazai/server-darwin-x64": "0.3.21",
-    "@kenazai/server-linux-arm64": "0.3.21",
-    "@kenazai/server-linux-x64": "0.3.21",
-    "@kenazai/server-win32-x64": "0.3.21"
+    "@kenazai/server-darwin-arm64": "0.3.22",
+    "@kenazai/server-darwin-x64": "0.3.22",
+    "@kenazai/server-linux-arm64": "0.3.22",
+    "@kenazai/server-linux-x64": "0.3.22",
+    "@kenazai/server-win32-x64": "0.3.22"
   },
   "license": "UNLICENSED",
   "repository": {