kenaz 0.3.21 → 0.3.23

package/core/dev/scripts/run-rust-tests.js

@@ -142,7 +142,7 @@ function main() {
   const build = spawnSync(
     'cargo',
     ['test', '--lib', '--no-run', '--message-format=json'],
-    { cwd: crateDir, encoding: 'utf8', shell: false, maxBuffer: 256 * 1024 * 1024, env }
+    { windowsHide: true, cwd: crateDir, encoding: 'utf8', shell: false, maxBuffer: 256 * 1024 * 1024, env }
   );
   if (build.status !== 0) {
     const compilerErrors = renderCompilerErrors(build.stdout);
@@ -180,7 +180,7 @@ function main() {
   }
 
   // 3. Run the artifact directly.
-  const run = spawnSync(testExe, exeArgs, { stdio: 'inherit' });
+  const run = spawnSync(testExe, exeArgs, { windowsHide: true, stdio: 'inherit' });
   process.exit(run.status ?? 1);
 }
 

package/core/dev/scripts/skill-routing-replay.js

@@ -36,7 +36,7 @@ function evaluate(streamText, expected) {
 }
 
 function copyRepo(dest) {
-  const files = execFileSync('git', ['ls-files', '-z'], { cwd: REPO, encoding: 'utf8', maxBuffer: 1 << 28 }).split('\0').filter(Boolean);
+  const files = execFileSync('git', ['ls-files', '-z'], { windowsHide: true, cwd: REPO, encoding: 'utf8', maxBuffer: 1 << 28 }).split('\0').filter(Boolean);
   for (const f of files) {
     const from = path.join(REPO, f);
     if (!fs.existsSync(from)) continue;
@@ -49,11 +49,11 @@ function runScenario(sc, opts) {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'skill-replay-'));
   try {
     copyRepo(dir);
-    execFileSync('git', ['init', '-q'], { cwd: dir });
+    execFileSync('git', ['init', '-q'], { windowsHide: true, cwd: dir });
     const prompt = (sc.prefix === undefined ? '/Ansuz ' : sc.prefix) + sc.message;
     // Prompt goes on stdin: with shell:true (needed on Windows) argv is concatenated unquoted, which split the message.
     const r = spawnSync('claude', ['-p', '--output-format', 'stream-json', '--verbose', '--max-turns', String(opts.maxTurns)],
-      { cwd: dir, input: prompt, encoding: 'utf8', maxBuffer: 1 << 28, timeout: opts.timeoutMs, shell: process.platform === 'win32' });
+      { windowsHide: true, cwd: dir, input: prompt, encoding: 'utf8', maxBuffer: 1 << 28, timeout: opts.timeoutMs, shell: process.platform === 'win32' });
     const ev = evaluate(r.stdout || '', sc.expected);
     return { id: sc.id, expected: sc.expected, hit: ev.hit, calls: ev.calls, exit: r.status, error: r.error && r.error.message };
   } finally {

package/core/dev/scripts/task1961/selftest.js

@@ -120,7 +120,7 @@ async function testSlowServe() {
     KENAZ_FIXTURE_SLOW_PHASE_MS: '4000',
   });
   const spawnedAt = Date.now();
-  const child = spawn(process.execPath, [SLOW_SERVE], { env, stdio: ['ignore', 'pipe', 'pipe'] });
+  const child = spawn(process.execPath, [SLOW_SERVE], { windowsHide: true, env, stdio: ['ignore', 'pipe', 'pipe'] });
   spawnedPids.push(child.pid);
   let out = '';
   child.stdout.on('data', (d) => (out += d.toString()));
@@ -166,7 +166,7 @@ async function testSlowServe() {
 
 async function testNeverListens() {
   console.log('\n[selftest] never-listens.server.js');
-  const child = spawn(process.execPath, [NEVER_LISTENS], { stdio: ['ignore', 'pipe', 'pipe'] });
+  const child = spawn(process.execPath, [NEVER_LISTENS], { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
   spawnedPids.push(child.pid);
   let exited = false;
   child.on('exit', () => {

package/core/dev/scripts/windows-hide-guard.test.js

@@ -0,0 +1,97 @@
+'use strict';
+// TASK_2474 guard: every child process Kenaz starts must be hidden on Windows.
+//  - Node: spawn/exec* calls in shipped JS must pass windowsHide (inline in the call, or on an options
+//    object defined in the same file). JS_ALLOW = intentionally visible terminals, with reasons.
+//  - Rust: Command::new in non-test Rust files outside common/process.rs must be hidden_command.
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const JS_DIRS = ['.specialist/tools', '.formation', '.claude/hooks', 'plugins/kenaz/hooks', 'plugins/kenaz/scripts',
+  '.collaboration/core', 'packages/kenaz/lib', 'packages/kenaz/bin', 'dashboard/scripts', 'dev/scripts'];
+const RS_DIR = 'dashboard/src-tauri/src';
+
+// "relative/path.js:line" -> reason. Intentionally visible terminals only.
+const JS_ALLOW = {
+  'dev/scripts/task1961/selftest.js:132': 'false positive: "spawn (took ..." inside a template-string message, not a call',
+};
+// "relative/path.rs" -> reason (whole file may use raw Command::new outside #[cfg(test)]).
+const RS_ALLOW = {
+  'dashboard/src-tauri/src/common/process.rs': 'the hidden_command constructors themselves',
+};
+
+function walk(dir, exts, out = []) {
+  const abs = path.join(ROOT, dir);
+  if (!fs.existsSync(abs)) return out;
+  for (const e of fs.readdirSync(abs, { withFileTypes: true })) {
+    if (['node_modules', '.git', 'target', 'dist', 'fixtures'].includes(e.name)) continue;
+    const rel = dir + '/' + e.name;
+    if (e.isDirectory()) walk(rel, exts, out);
+    else if (exts.some((x) => e.name.endsWith(x)) && !/\.test\.[cm]?js$/.test(e.name)) out.push(rel);
+  }
+  return out;
+}
+
+// plugins/kenaz/hooks/core-resolve.js is generated (gitignored) from .claude/hooks/core-resolve.js
+const isGenerated = (rel) => rel === 'plugins/kenaz/hooks/core-resolve.js';
+
+function matchParen(src, open) {
+  let depth = 0, q = null;
+  for (let i = open; i < src.length; i++) {
+    const c = src[i];
+    if (q) { if (c === '\\') i++; else if (c === q) q = null; continue; }
+    if (c === '"' || c === "'" || c === '`') { q = c; continue; }
+    if (c === '(') depth++;
+    else if (c === ')' && --depth === 0) return i;
+  }
+  return src.length;
+}
+
+function scanJs(rel, src) {
+  if (!/child_process/.test(src)) return [];
+  const bad = [];
+  // blank block comments and whole-line // comments (offsets and line numbers preserved)
+  src = src.replace(/\/\*[\s\S]*?\*\//g, (c) => c.replace(/[^\n]/g, ' ')).replace(/^[ \t]*\/\/.*$/gm, (c) => ' '.repeat(c.length));
+  const re = /(?<![\w$.])(?:(?:cp|child_process|childProcess|proc)\.)?(spawn|spawnSync|exec|execSync|execFile|execFileSync)\s*\(/g;
+  let m;
+  while ((m = re.exec(src))) {
+    const open = m.index + m[0].length - 1;
+    const args = src.slice(open, matchParen(src, open) + 1);
+    if (/windowsHide/.test(args)) continue;
+    // options passed as a bare identifier: accept when that identifier is defined with windowsHide in the file
+    const last = args.slice(1, -1).split(',').pop().trim();
+    if (/^[A-Za-z_$][\w$]*$/.test(last) && new RegExp(`${last}\\s*=\\s*\\{[^;]*windowsHide`).test(src)) continue;
+    const line = src.slice(0, m.index).split('\n').length;
+    if (JS_ALLOW[`${rel}:${line}`]) continue;
+    bad.push(`${rel}:${line} ${m[1]}`);
+  }
+  return bad;
+}
+
+function scanRs(rel, src) {
+  if (RS_ALLOW[rel]) return [];
+  const cut = src.search(/#\[cfg\(test\)\]/);
+  const body = cut >= 0 ? src.slice(0, cut) : src;
+  const bad = [];
+  body.split('\n').forEach((ln, i) => {
+    if (/^\s*\/\//.test(ln)) return;
+    if (/Command::new\s*\(/.test(ln) && !/hidden_/.test(ln)) bad.push(`${rel}:${i + 1}`);
+  });
+  return bad;
+}
+
+test('Node: every child_process call passes windowsHide', () => {
+  const files = JS_DIRS.flatMap((d) => walk(d, ['.js', '.cjs', '.mjs'])).filter((f) => !isGenerated(f));
+  const bad = files.flatMap((f) => scanJs(f, fs.readFileSync(path.join(ROOT, f), 'utf8')));
+  console.log(`node violations: ${bad.length}`);
+  assert.deepStrictEqual(bad, []);
+});
+
+test('Rust: no raw Command::new in production code outside common/process.rs', () => {
+  const files = walk(RS_DIR, ['.rs']).filter((f) => !/(^|\/)tests?\.rs$|_tests?\.rs$|\/tests\//.test(f));
+  const bad = files.flatMap((f) => scanRs(f, fs.readFileSync(path.join(ROOT, f), 'utf8')));
+  console.log(`rust violations: ${bad.length}`);
+  assert.deepStrictEqual(bad, []);
+});

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,7 @@
 [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.
+- Reporting a Kenaz problem or idea: call kenaz_wish_create (scope kenaz) yourself; it uploads to the Kenaz mother (Alaya) automatically, no user step. Claude Code's SendFeedback tool and /feedback go to Anthropic, never to Kenaz.
 - 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/core-resolve.js

@@ -221,7 +221,7 @@ if (require.main === module) {
   if (!result) process.exit(0); // silent -- non-blocking hook
 
   try {
-    execFileSync("node", [result.resolved, ...result.args], { stdio: "inherit" });
+    execFileSync("node", [result.resolved, ...result.args], { stdio: "inherit", windowsHide: true });
   } catch {
     // Hook errors should not block
   }

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

@@ -13,7 +13,8 @@ const fs = require('fs');
 const path = require('path');
 const net = require('net');
 const http = require('http');
-const { spawnSync } = require('child_process');
+const os = require('os');
+const { spawn, spawnSync } = require('child_process');
 const { resolveMode, allows, projectDir } = require('./mode');
 const { isSdkSession } = require('./sdk-gate');
 
@@ -33,6 +34,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' },
 };
 
@@ -48,6 +50,42 @@ function backendUp(cb) {
   s.on('error', () => done(false));
 }
 
+// TASK_2468: after a reboot nothing has started kenaz-server yet (the plugin MCP is a static http URL).
+// Start the installed binary detached, the way the installer does; never by process name, and only
+// called after the port probe failed (a second server is never started over an answering one).
+function startServer(dir) {
+  try {
+    const home = os.homedir();
+    const meta = JSON.parse(fs.readFileSync(path.join(home, '.kenaz', 'install.json'), 'utf8'));
+    const bin = meta && meta.serverBin;
+    if (!bin || !fs.existsSync(bin)) return false;
+    const vbs = path.join(home, '.kenaz', 'kenaz-server.vbs');
+    const core = coreDir(dir);
+    const env = Object.assign({}, process.env, core ? { KENAZ_SOURCE_DIR: core } : {});
+    const opts = { env, detached: true, stdio: 'ignore', windowsHide: true };
+    const viaNode = /\.js$/.test(bin); // a script (tests) runs under node; the real server is a binary
+    let child;
+    if (process.platform === 'win32') {
+      child = fs.existsSync(vbs) ? spawn('wscript.exe', [vbs], opts) : viaNode ? spawn(process.execPath, [bin], opts) : spawn(bin, [], opts);
+    } else {
+      const log = path.join(home, '.kenaz', 'kenaz-server.log');
+      const sq = (v) => "'" + String(v).replace(/'/g, "'\\''") + "'";
+      const cmd = 'if command -v setsid >/dev/null 2>&1; then S=setsid; else S=; fi; $S nohup ' +
+        (viaNode ? sq(process.execPath) + ' ' : '') + sq(bin) + ' >> ' + sq(log) + ' 2>&1 < /dev/null &';
+      child = spawn('sh', ['-c', cmd], opts);
+    }
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch (_) { return false; }
+}
+
+function waitForBackend(ms, cb) {
+  const end = Date.now() + ms;
+  const tick = () => backendUp((ok) => { if (ok || Date.now() >= end) return cb(ok); setTimeout(tick, 150); });
+  tick();
+}
+
 function post(body, cb) {
   const r = http.request({ hostname: HOST, port: PORT, path: '/api/rust/agent-flow/hook', method: 'POST',
     headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) }, timeout: 3000 },
@@ -74,7 +112,7 @@ function run(spec, stdin, dir) {
   const stdio = ['pipe', 'inherit', 'ignore'];
   if (spec.kind === 'core-script') {
     const target = path.join(core, spec.rel);
-    if (fs.existsSync(target)) spawnSync(process.execPath, [target, ...(spec.args || [])], { cwd: dir, env, input: stdin, stdio, timeout: 10000 });
+    if (fs.existsSync(target)) spawnSync(process.execPath, [target, ...(spec.args || [])], { cwd: dir, env, input: stdin, stdio, timeout: 10000, windowsHide: true });
     return;
   }
   const file = path.join(core, '.claude', 'hooks', spec.file);
@@ -82,7 +120,7 @@ function run(spec, stdin, dir) {
   // Same shape as the core's own `node -e "chdir; require(hook)"` wrappers (require.main stays undefined).
   const code = 'process.chdir(process.env.CLAUDE_PROJECT_DIR);const m=require(process.argv[1]);' +
     (spec.call ? 'm[process.argv[2]]();' : '');
-  spawnSync(process.execPath, ['-e', code, file, spec.call || ''], { cwd: dir, env, input: stdin, stdio, timeout: 10000 });
+  spawnSync(process.execPath, ['-e', code, file, spec.call || ''], { cwd: dir, env, input: stdin, stdio, timeout: 10000, windowsHide: true });
 }
 
 function main() {
@@ -104,7 +142,18 @@ function main() {
     }
     run(spec, stdin, dir);
   };
-  if (spec.backend) backendUp((ok) => { if (ok) go(); }); else go();
+  if (!spec.backend) return go();
+  backendUp((ok) => {
+    if (ok) return go();
+    if (spec.kind !== 'session-start') return;
+    const finish = (up) => {
+      if (up) go();
+      process.stdout.write(up
+        ? 'kenaz-server was not running; the Kenaz hook started it on ' + HOST + ':' + PORT + '. If the kenaz MCP tools (kenaz-dashboard) show as failed, ask the user to run /mcp to reconnect them (they connected before the server was up).\n'
+        : 'kenaz-server is not running on ' + HOST + ':' + PORT + ', so the kenaz MCP tools are unavailable. Ask the user to run `! npx kenaz install` (registers the boot service and starts it), then /mcp to reconnect kenaz-dashboard.\n');
+    };
+    if (startServer(dir)) waitForBackend(3000, finish); else finish(false);
+  });
 }
 
 process.on('uncaughtException', () => process.exit(0));

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

@@ -58,11 +58,14 @@ test('kenaz.yaml switch is honoured; env wins', () => {
 });
 
 test('backend down: no output, no stderr, exit 0', () => {
-  for (const n of ['flow-post', 'session-start']) {
-    const r = hook(n, proj(), { KENAZ_BACKEND_PORT: '1' });
-    assert.strictEqual(r.status, 0);
-    assert.strictEqual(r.stdout + r.stderr, '');
-  }
+  const home = proj(); // temp HOME: session-start would otherwise start the real installed server (TASK_2468)
+  const env = { KENAZ_BACKEND_PORT: '1', HOME: home, USERPROFILE: home };
+  const r = hook('flow-post', proj(), env);
+  assert.strictEqual(r.status, 0);
+  assert.strictEqual(r.stdout + r.stderr, '');
+  const s = hook('session-start', proj(), env); // only session-start speaks: one line naming the fix
+  assert.strictEqual(s.stderr, '');
+  assert.match(s.stdout, /npx kenaz install/);
 });
 
 test('ygg status fixture: masked key, room, peers, mail (TASK_2366)', () => {
@@ -202,3 +205,67 @@ test('ygg create explains 429, 503, missing relay_url and unreachable relay (TAS
     await assert.rejects(createTeam(dir, '', 'project'), /cannot reach the relay at http:\/\/127\.0\.0\.1:1/);
   });
 });
+
+// TASK_2468: SessionStart starts the installed server when the port is closed (temp HOME, free port, fake server script).
+async function freePort() {
+  const srv = require('net').createServer();
+  await new Promise((r) => srv.listen(0, '127.0.0.1', r));
+  const p = srv.address().port;
+  await new Promise((r) => srv.close(r));
+  return p;
+}
+function fakeHome(withBin) {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'kz-home-'));
+  fs.mkdirSync(path.join(home, '.kenaz'));
+  const bin = path.join(home, 'fake-server.js');
+  fs.writeFileSync(bin, "const http=require('http');require('fs').writeFileSync(process.env.PIDFILE,String(process.pid));" +
+    "http.createServer((q,r)=>{r.end('{}')}).listen(Number(process.env.KENAZ_BACKEND_PORT),'127.0.0.1');setTimeout(()=>process.exit(0),15000);");
+  if (withBin) fs.writeFileSync(path.join(home, '.kenaz', 'install.json'), JSON.stringify({ serverBin: bin }));
+  return { home, pidfile: path.join(home, 'pid') };
+}
+const isUp = (port) => new Promise((r) => { const s = require('net').connect({ host: '127.0.0.1', port }); s.on('connect', () => { s.destroy(); r(true); }); s.on('error', () => r(false)); });
+const killPid = (f) => { try { process.kill(Number(fs.readFileSync(f, 'utf8'))); } catch (_) { /* never started */ } };
+const hookAsync = (env) => new Promise((resolve) => {
+  const c = require('child_process').spawn(process.execPath, [HOOK, 'session-start'], { env: Object.assign({}, process.env, { CLAUDE_PROJECT_DIR: proj(), KENAZ_MODE: '', KENAZ_SOURCE_DIR: CORE }, env) });
+  let out = ''; c.stdout.on('data', (d) => { out += d; }); c.on('close', () => resolve(out)); c.stdin.end('{}');
+});
+
+test('TASK_2468: session-start with the port closed starts the installed server and says so', async () => {
+  const port = await freePort(); const f = fakeHome(true);
+  const env = { HOME: f.home, USERPROFILE: f.home, KENAZ_BACKEND_PORT: String(port), PIDFILE: f.pidfile };
+  try {
+    const out = await hookAsync(env);
+    assert.ok(await isUp(port), 'server came up');
+    assert.match(out, /started it/); assert.match(out, /\/mcp/);
+  } finally { killPid(f.pidfile); }
+});
+
+test('TASK_2468: no install.json -> one line naming `npx kenaz install` and /mcp; nothing spawned', async () => {
+  const port = await freePort(); const f = fakeHome(false);
+  const env = { HOME: f.home, USERPROFILE: f.home, KENAZ_BACKEND_PORT: String(port), PIDFILE: f.pidfile };
+  const out = await hookAsync(env);
+  assert.match(out, /npx kenaz install/); assert.match(out, /\/mcp/);
+  assert.strictEqual(out.trim().split('\n').length, 1);
+  assert.ok(!(await isUp(port)));
+});
+
+test('TASK_2468: KENAZ_MODE=off and sdk entrypoint -> no output, nothing spawned', async () => {
+  for (const extra of [{ KENAZ_MODE: 'off' }, { CLAUDE_CODE_ENTRYPOINT: 'sdk-ts' }]) {
+    const port = await freePort(); const f = fakeHome(true);
+    const env = Object.assign({ HOME: f.home, USERPROFILE: f.home, KENAZ_BACKEND_PORT: String(port), PIDFILE: f.pidfile }, extra);
+    try {
+      assert.strictEqual(await hookAsync(env), '');
+      assert.ok(!(await isUp(port)) && !fs.existsSync(f.pidfile));
+    } finally { killPid(f.pidfile); }
+  }
+});
+
+test('TASK_2468: port already answering -> nothing spawned, no extra line', async () => {
+  const port = await freePort(); const f = fakeHome(true);
+  const srv = require('http').createServer((q, r) => r.end('{}'));
+  await new Promise((r) => srv.listen(port, '127.0.0.1', r));
+  try {
+    const out = await hookAsync({ HOME: f.home, USERPROFILE: f.home, KENAZ_BACKEND_PORT: String(port), PIDFILE: f.pidfile });
+    assert.strictEqual(out, ''); assert.ok(!fs.existsSync(f.pidfile));
+  } finally { srv.close(); }
+});

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')
+})