kenaz 0.3.19 → 0.3.20

package/core/dev/scripts/relay-admin.test.js

@@ -0,0 +1,131 @@
+'use strict';
+// TASK_2451: relay-admin.js against a local fixture that mimics the relay admin endpoints
+// (same routes, X-Admin-Key check, approve-by-fingerprint semantics as node_admin.rs). Every
+// command in HELP is executed through the real CLI process.
+const test = require('node:test');
+const assert = require('node:assert');
+const http = require('http');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn, spawnSync } = require('child_process');
+const { HELP } = require('./relay-admin');
+
+const KEY = 'sekret-admin-key';
+const CLI = path.join(__dirname, 'relay-admin.js');
+let server, url, tokens, blocks = [], protect = false;
+
+test.before(async () => {
+  tokens = [
+    { team_id: 't1', node_name: 'n1', fingerprint: 'AAAA-1111', status: 'pending', created_at: '2026-10-13T00:00:00Z' },
+    { team_id: 't1', node_name: 'n1', fingerprint: 'BBBB-2222', status: 'active', created_at: '2026-10-12T00:00:00Z' },
+  ];
+  server = http.createServer((req, res) => {
+    let b = '';
+    req.on('data', (c) => (b += c));
+    req.on('end', () => {
+      const send = (s, o) => { res.statusCode = s; res.end(JSON.stringify(o || {})); };
+      if (req.headers['x-admin-key'] !== KEY) return send(401);
+      const r = req.url.replace('/api/admin/node-credentials/', '');
+      const body = b ? JSON.parse(b) : {};
+      if (r === 'pending') return send(200, { pending: tokens.filter((t) => t.status === 'pending') });
+      if (r === 'approve') {
+        const t = tokens.find((x) => x.status === 'pending' && x.team_id === body.team_id && x.node_name === body.node_name && x.fingerprint === body.fingerprint);
+        if (!t) return send(404);
+        let n = 0;
+        for (const o of tokens) if (o !== t && o.team_id === t.team_id && o.node_name === t.node_name && o.status !== 'revoked') { o.status = 'revoked'; n++; }
+        t.status = 'active';
+        return send(200, { status: 'active', revoked_others: n });
+      }
+      if (r === 'revoke') {
+        let n = 0;
+        for (const o of tokens) if (o.team_id === body.team_id && o.node_name === body.node_name && o.status !== 'revoked') { o.status = 'revoked'; n++; }
+        return send(200, { status: 'revoked', revoked: n });
+      }
+      if (r === 'ban') { blocks.push(body); return send(200, { banned: true, revoked: 1, protect_bound_names: protect }); }
+      if (r === 'unban') { blocks = []; return send(200, { unbanned: 1 }); }
+      if (r === 'blocked') return send(200, { blocked: blocks.map((b) => ({ team_id: b.team_id, kind: 'name', value: b.node_name, reason: b.reason, created_at: 'now' })) });
+      send(404);
+    });
+  });
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  url = `http://127.0.0.1:${server.address().port}`;
+});
+test.after(() => server.close());
+
+const cli = (args, env = { RELAY_ADMIN_KEY: KEY }) =>
+  new Promise((resolve) => {
+    const p = spawn(process.execPath, [CLI, '--relay', url, ...args], { env: { ...process.env, RELAY_ADMIN_KEY: '', RELAY_ADMIN_KEY_FILE: '', ...env } });
+    let out = ''; p.stdout.on('data', (d) => (out += d)); p.stderr.on('data', (d) => (out += d));
+    p.on('close', (code) => resolve({ code, out }));
+  });
+
+test('list -> wrong fingerprint refused -> approve activates and reports revoked tokens', async () => {
+  let r = await cli(['list']);
+  assert.strictEqual(r.code, 0); assert.match(r.out, /t1\tn1\tAAAA-1111/);
+  r = await cli(['approve', 't1', 'n1', 'ZZZZ-0000']);
+  assert.strictEqual(r.code, 1); assert.match(r.out, /HTTP 404/);
+  assert.strictEqual(tokens[0].status, 'pending');
+  r = await cli(['approve', 't1', 'n1', 'AAAA-1111']);
+  assert.strictEqual(r.code, 0); assert.match(r.out, /revoked 1 other token/);
+  assert.strictEqual(tokens[0].status, 'active'); assert.strictEqual(tokens[1].status, 'revoked');
+  r = await cli(['list']);
+  assert.match(r.out, /no pending/);
+});
+
+test('revoke', async () => {
+  const r = await cli(['revoke', 't1', 'n1']);
+  assert.strictEqual(r.code, 0); assert.match(r.out, /revoked 1 token/);
+  assert.strictEqual(tokens[0].status, 'revoked');
+});
+
+test('wrong admin key and key file', async () => {
+  let r = await cli(['list'], { RELAY_ADMIN_KEY: 'nope' });
+  assert.strictEqual(r.code, 1); assert.match(r.out, /wrong admin key/);
+  const f = path.join(os.tmpdir(), `relay-admin-key-${process.pid}`);
+  fs.writeFileSync(f, KEY + '\n');
+  r = await cli(['list'], { RELAY_ADMIN_KEY_FILE: f });
+  fs.unlinkSync(f);
+  assert.strictEqual(r.code, 0);
+});
+
+test('admin key on argv is refused (control: same call via env works)', async () => {
+  for (const a of [['--admin-key', KEY, 'list'], ['--key=' + KEY, 'list']]) {
+    const r = await cli(a, {});
+    assert.strictEqual(r.code, 2); assert.match(r.out, /must not be passed/);
+  }
+  assert.strictEqual((await cli(['list'])).code, 0);
+});
+
+test('missing key refused; help text commands are all executed by this suite', async () => {
+  assert.strictEqual((await cli(['list'], {})).code, 2);
+  const cmds = [...HELP.matchAll(/^ {2}(list|approve|revoke|ban|unban|blocked)\b/gm)].map((m) => m[1]);
+  assert.deepStrictEqual(cmds, ['list', 'approve', 'revoke', 'ban', 'unban', 'blocked']);
+  const argsFor = { list: ['list'], approve: ['approve', 't', 'n', 'F'], revoke: ['revoke', 't', 'n'], ban: ['ban', 't', 'n'], unban: ['unban', 't', 'n'], blocked: ['blocked'] };
+  for (const c of cmds) assert.notStrictEqual((await cli(argsFor[c])).code, 2, c);
+  assert.strictEqual(spawnSync(process.execPath, [CLI, 'bogus']).status, 2);
+});
+
+test('ban prints the tokenless-access warning when the flag is off; no warning when on; blocked/unban', async () => {
+  protect = false;
+  let r = await cli(['ban', 't1', 'evil', 'because']);
+  assert.strictEqual(r.code, 0); assert.match(r.out, /banned t1\/evil/);
+  assert.match(r.out, /WARNING: protect_bound_names is OFF.*anonymously/);
+  assert.strictEqual(blocks[0].reason, 'because');
+  protect = true;
+  r = await cli(['ban', 't1', 'evil2', '--machine', 'abc']);
+  assert.doesNotMatch(r.out, /WARNING/); assert.match(r.out, /machine abc/);
+  assert.strictEqual(blocks[1].machine_id_hash, 'abc');
+  r = await cli(['blocked']);
+  assert.match(r.out, /t1\tname\tevil\t/);
+  r = await cli(['unban', 't1', 'evil']);
+  assert.match(r.out, /unbanned 1 entry/);
+  assert.match((await cli(['blocked'])).out, /nothing blocked/);
+  assert.strictEqual((await cli(['ban', 't1'])).code, 2);
+});
+
+test('list shows self-reported machine info only when sent', async () => {
+  tokens.push({ team_id: 't1', node_name: 'm1', fingerprint: 'CCCC', status: 'pending', created_at: 'x', hostname: 'box', os: 'linux', machine_id_hash: 'abcdef0123456789' });
+  const r = await cli(['list']);
+  assert.match(r.out, /m1\tCCCC\tx\thost=box os=linux machine=abcdef012345 \(self-reported\)/);
+});

package/core/plugins/kenaz/README.md

@@ -48,8 +48,18 @@ Independent Codex sessions use **pull-on-prompt**: in `full` mode with trusted h
 
 Resolution: env `KENAZ_MODE` > `<project>/.kenaz/kenaz.yaml` > `~/.kenaz/kenaz.yaml` > `full`. Hooks fail open (backend down or core not found: no output, exit 0).
 
+## Agent SDK sessions
+
+Programs built on `claude_agent_sdk` (`CLAUDE_CODE_ENTRYPOINT` `sdk-py` / `sdk-ts`) load `~/.claude/settings.json` too, so they would get this plugin. Hooks (`hooks/sdk-gate.js`) and the kenaz-peer mod therefore do nothing for those sessions. `claude -p` (`sdk-cli`) and interactive entrypoints are unchanged. Set `KENAZ_IN_SDK=1` to opt a program in.
+
+The MCP tools cannot be gated: `.mcp.json` is a plain HTTP server entry, not a launcher that could exit, and the connection is made before any hook runs. SDK users who do not want the 34 tools pass `setting_sources=[]` (or `[]` plus the sources they need) and `strict_mcp_config` (`extra_args={"strict-mcp-config": None}`) in `ClaudeAgentOptions`.
+
 ## CLI version gate
 
 Not needed: the 2.1.287 gate (TASK_2234, `peer_mod.rs`) exists because kenaz-peer is a mod module (`hooks/register.ts`). This plugin uses only plain hooks, commands, skills and MCP, which older CLIs support. Automatic registration into `CLAUDE_CODE_PLUGIN_DIRS` (as kenaz-peer gets) is a follow-up in `peer_mod.rs`; until then use `--plugin-dir`.
 
 Tests: `node --test plugins/kenaz/scripts/kenaz.test.js`. Classification: `INVENTORY.md`.
+
+## Peer node identity
+
+kenaz-server requests a relay node token on its own; it starts pending until the relay operator approves its fingerprint. `GET http://localhost:18080/api/peer/status?projectPath=<project>` shows `node_identity` (`none` / `pending` with the fingerprint / `active`). Send the fingerprint to the operator out of band. No token or an old relay keeps today behaviour. Operator commands, the enforcement flag and the `X-Node-Token` header for non-Claude agents that call the relay directly: `yggdrasil-relay/DESIGN.md`, section "Node tokens and approval".

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

@@ -15,6 +15,7 @@ const net = require('net');
 const http = require('http');
 const { spawnSync } = require('child_process');
 const { resolveMode, allows, projectDir } = require('./mode');
+const { isSdkSession } = require('./sdk-gate');
 
 const HOST = '127.0.0.1';
 const PORT = Number(process.env.KENAZ_BACKEND_PORT) || 18080;
@@ -86,7 +87,7 @@ function run(spec, stdin, dir) {
 
 function main() {
   const spec = HOOKS[process.argv[2]];
-  if (!spec) return;
+  if (!spec || isSdkSession()) return; // TASK_2455: SDK sessions get nothing, before stdin or any write
   const dir = projectDir();
   // A project that ships the Kenaz hooks itself (the core repo) registers them in its own
   // .claude/settings.json; the plugin yields so no hook runs twice (same rule as _user-scope.js).

package/core/plugins/kenaz/hooks/sdk-gate.js

@@ -0,0 +1,9 @@
+'use strict';
+// TASK_2455: claude-agent-sdk sessions (CLAUDE_CODE_ENTRYPOINT sdk-py / sdk-ts / ...) must not get Kenaz.
+// sdk-cli is `claude -p` (Kenaz's own dispatch, headless nodes) and keeps working. KENAZ_IN_SDK=1 opts in.
+function isSdkSession(env) {
+  env = env || process.env;
+  const ep = String(env.CLAUDE_CODE_ENTRYPOINT || '');
+  return ep.startsWith('sdk-') && ep !== 'sdk-cli' && env.KENAZ_IN_SDK !== '1';
+}
+module.exports = { isSdkSession };

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

@@ -19,6 +19,18 @@ function hook(name, dir, env, input) {
   });
 }
 
+test('TASK_2455: SDK sessions get nothing; cli / sdk-cli / KENAZ_IN_SDK=1 keep today\'s output', () => {
+  const dir = proj();
+  for (const n of ['guidance', 'prompt-runner', 'memory-guard', 'flow-post', 'session-start', 'session-stop']) {
+    for (const ep of ['sdk-py', 'sdk-ts']) {
+      const r = hook(n, dir, { CLAUDE_CODE_ENTRYPOINT: ep });
+      assert.strictEqual(r.status, 0); assert.strictEqual(r.stdout, ''); assert.strictEqual(r.stderr, '');
+    }
+  }
+  for (const ep of ['cli', 'sdk-cli']) assert.match(hook('guidance', dir, { CLAUDE_CODE_ENTRYPOINT: ep }).stdout, /Kenaz plugin/);
+  assert.match(hook('guidance', dir, { CLAUDE_CODE_ENTRYPOINT: 'sdk-py', KENAZ_IN_SDK: '1' }).stdout, /Kenaz plugin/);
+});
+
 test('full prints guidance (control for off)', () => {
   const r = hook('guidance', proj());
   assert.strictEqual(r.status, 0);
@@ -102,7 +114,7 @@ test('ygg join activates the room in collaboration_projects; status explains how
   const srv = http.createServer((req, res) => {
     let b = ''; req.on('data', (d) => { b += d; });
     req.on('end', () => {
-      if (req.method === 'POST') posts.push(JSON.parse(b));
+      if (req.method === 'POST') { posts.push(JSON.parse(b)); cfg.collaboration_projects = posts[posts.length - 1].collaboration_projects; }
       res.setHeader('content-type', 'application/json');
       res.end(JSON.stringify(req.method === 'POST' ? { ok: true } : cfg));
     });
@@ -120,7 +132,7 @@ test('ygg join activates the room in collaboration_projects; status explains how
     srv.close();
   }
   const { buildStatus, renderStatus } = require('./ygg.js');
-  assert.match(renderStatus(buildStatus(cfg, { connected: false, nodes: [] }, null)), /not active in this project - run "ygg join <key>"/);
+  assert.match(renderStatus(buildStatus(Object.assign({}, cfg, { collaboration_projects: ['other'] }), { connected: false, nodes: [] }, null)), /not active in this project - run "ygg join <key>"/);
 });
 
 // TASK_2416: `ygg create` posts to the relay (config relay_url), then joins with the returned key.
@@ -139,7 +151,7 @@ async function withStub(relayReply, fn) {
       }
       if (req.url.startsWith('/api/nodes')) return res.end('[]');
       if (req.url.startsWith('/api/yggdrasil/config')) {
-        if (req.method === 'POST') { seen.config.push(JSON.parse(b)); return res.end(JSON.stringify({ ok: true })); }
+        if (req.method === 'POST') { seen.config.push(JSON.parse(b)); cfg.collaboration_projects = seen.config[seen.config.length - 1].collaboration_projects; return res.end(JSON.stringify({ ok: true })); }
         return res.end(JSON.stringify(cfg));
       }
       res.end(JSON.stringify({ success: true, created: false }));

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

@@ -149,7 +149,15 @@ function postBody(cfg, patch) {
 async function join(dir, key, scope) {
   if (!key || /\s/.test(key)) throw new Error('usage: ygg join <key> [--project|--global]');
   const cfg = await getConfig(dir);
+  // TASK_2441: no room key to activate = the POST below would save an empty list and "succeed".
+  if (!cfg.effective_project_key) throw new Error("cannot work out this project's room (" + (cfg.error || 'no effective_project_key') + '); does ' + dir + ' have a repo with a remote?');
   await postConfig(dir, postBody(cfg, { enabled: true, publishable_key: key, key_scope: scope, collaboration_projects: withCollab(cfg, true) }));
+  // Verify by reading back: a save that returned ok but did not land must not print a status that says "run join".
+  const after = await getConfig(dir);
+  if (!(after.collaboration_projects || []).includes(cfg.effective_project_key)) {
+    throw new Error('join saved the key but room "' + cfg.effective_project_key + '" is not in collaboration_projects after re-reading the config; expected in ' +
+      path.join(dir, '.kenaz', 'yggdrasil.local.yaml') + ' (collaboration_projects: "' + cfg.effective_project_key + '"); the server reports ' + JSON.stringify(after.collaboration_projects || []));
+  }
   return status(dir);
 }
 

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

@@ -0,0 +1,72 @@
+'use strict';
+// node --test plugins/kenaz/scripts/ygg.test.js
+// TASK_2441: ygg join must read the config back and fail loudly when the room did not land.
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const http = require('http');
+const { spawn } = require('child_process');
+
+const YGG = path.join(__dirname, 'ygg.js');
+const ROOM = 'github.com/o/r';
+
+async function withBackend(persist, fn) {
+  const cfg = { enabled: false, effective_project_key: ROOM, node_name: 'Alice', publishable_key: '', collaboration_projects: [], relay_url: '' };
+  const srv = http.createServer((req, res) => {
+    let b = ''; req.on('data', (d) => { b += d; });
+    req.on('end', () => {
+      res.setHeader('content-type', 'application/json');
+      if (req.url.startsWith('/api/yggdrasil/config') && req.method === 'POST') {
+        if (persist) Object.assign(cfg, JSON.parse(b));
+        return res.end(JSON.stringify({ ok: true }));
+      }
+      res.end(JSON.stringify(req.url.startsWith('/api/yggdrasil/config') ? cfg : req.url.startsWith('/api/projects') ? { success: true } : {}));
+    });
+  });
+  await new Promise((r) => srv.listen(0, '127.0.0.1', r));
+  try { return await fn(srv.address().port); } finally { srv.close(); }
+}
+
+function cli(port, dir) {
+  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) }) });
+    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 }));
+  });
+}
+
+test('join exits non-zero naming the file when the room is not in collaboration_projects after the POST', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ygg2441-'));
+  await withBackend(false, async (port) => {
+    const r = await cli(port, dir);
+    assert.notStrictEqual(r.code, 0);
+    assert.match(r.err, /yggdrasil\.local\.yaml/);
+    assert.ok(r.err.includes(ROOM), r.err);
+    assert.doesNotMatch(r.out, /not active in this project/);
+  });
+});
+
+test('control: join against a backend that persists the room prints "active in this project"', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ygg2441-'));
+  await withBackend(true, async (port) => {
+    const r = await cli(port, dir);
+    assert.strictEqual(r.code, 0, r.err);
+    assert.match(r.out, /active in this project/);
+    assert.doesNotMatch(r.out, /not active/);
+  });
+});
+
+test('join refuses when the backend reports no effective_project_key (nothing to activate)', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ygg2441-'));
+  const srv = http.createServer((req, res) => { res.setHeader('content-type', 'application/json'); res.end(JSON.stringify({ enabled: false, error: 'yggdrasil.yaml not found' })); });
+  await new Promise((r) => srv.listen(0, '127.0.0.1', r));
+  try {
+    const r = await cli(srv.address().port, dir);
+    assert.notStrictEqual(r.code, 0);
+    assert.match(r.err, /cannot work out this project's room/);
+  } finally { srv.close(); }
+});

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

@@ -103,6 +103,38 @@ test('control: non-Ansuz session gets no status and no toast', async ($, on) =>
   expect(toasts.length).toBe(0)
 })
 
+const ANSUZ = [{ role: 'user', content: '# Ansuz -- Specialist Prompt' }]
+
+test('TASK_2455: sdk-ts session is never registered as a peer (no heartbeat, no submit)', async ($, on) => {
+  const clock = mock.clock(on)
+  mock.env(on, { CLAUDE_CODE_ENTRYPOINT: 'sdk-ts' })
+  const { calls, submits } = setup(on, () => ANSUZ)
+  await $.session.start(START)
+  await clock.advance(15_000)
+  expect(calls.length).toBe(0)
+  expect(submits.length).toBe(0)
+})
+
+test('TASK_2455: cli registers (control)', async ($, on) => {
+  const clock = mock.clock(on)
+  mock.env(on, { CLAUDE_CODE_ENTRYPOINT: 'cli' })
+  const { calls } = setup(on, () => ANSUZ)
+  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')
+})
+
+test('TASK_2455: KENAZ_IN_SDK=1 opts an sdk-py session in', async ($, on) => {
+  const clock = mock.clock(on)
+  mock.env(on, { CLAUDE_CODE_ENTRYPOINT: 'sdk-py', KENAZ_IN_SDK: '1' })
+  const { calls } = setup(on, () => ANSUZ)
+  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')
+})
+
 test('plugin-namespaced /kenaz:Ansuz also activates delivery', async ($, on) => {
   const clock = mock.clock(on)
   const { calls, submits } = setup(on, () => [{ role: 'user', content: [{ type: 'text', text: '<command-name>/kenaz:Ansuz</command-name>' }] }])

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

@@ -155,6 +155,15 @@ async function cycle($: any): Promise<void> {
 
 export const register: Register = on => {
   on('session.start', async ($, e, next) => {
+    // TASK_2455: claude-agent-sdk sessions (sdk-py / sdk-ts, not `claude -p` = sdk-cli) are never peer sessions.
+    // Same rule as plugins/kenaz/hooks/sdk-gate.js; KENAZ_IN_SDK=1 opts in. sessionId stays '' so no hook acts.
+    let ep = ''
+    let optIn = ''
+    try {
+      ep = (await $.env.get('CLAUDE_CODE_ENTRYPOINT')) ?? ''
+      optIn = (await $.env.get('KENAZ_IN_SDK')) ?? ''
+    } catch { /* env unreadable: behave as an interactive session */ }
+    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($) })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kenaz",
-  "version": "0.3.19",
+  "version": "0.3.20",
   "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.19",
-    "@kenazai/server-darwin-x64": "0.3.19",
-    "@kenazai/server-linux-arm64": "0.3.19",
-    "@kenazai/server-linux-x64": "0.3.19",
-    "@kenazai/server-win32-x64": "0.3.19"
+    "@kenazai/server-darwin-arm64": "0.3.20",
+    "@kenazai/server-darwin-x64": "0.3.20",
+    "@kenazai/server-linux-arm64": "0.3.20",
+    "@kenazai/server-linux-x64": "0.3.20",
+    "@kenazai/server-win32-x64": "0.3.20"
   },
   "license": "UNLICENSED",
   "repository": {