kenaz 0.3.11 → 0.3.13

package/core/.formation/bifrost/exec.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * Bifrost executors for `kenaz subagent` (TASK_2422): run a dispatched card with a non-Claude model.
+ *   codex:<id>      `codex exec` in the card's worktree (id = an entry of openai/models.json; `codex:` = default)
+ *   deepseek:<m>    `claude -p` in the worktree against DeepSeek's Anthropic-compatible endpoint
+ *
+ * CLI (dispatch.js prints the exact command):
+ *   node exec.js --adapter=codex|deepseek --model=<id> --worktree <dir> --prompt-file <f> --result-file <f>
+ * The prompt goes to the child on stdin (never argv). The DeepSeek key is only in the child's env and
+ * is redacted from everything written. The worktree is never removed. Exit 0 = child ok AND new commits.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn, spawnSync } = require('child_process');
+
+const DEEPSEEK_MODELS = ['deepseek-chat', 'deepseek-reasoner'];
+const DEEPSEEK_BASE_URL = 'https://api.deepseek.com/anthropic';
+const DEEPSEEK_CONTEXT_TOKENS = 128000;
+const CLAUDE_TOOLS = ['Bash', 'Edit', 'Write', 'Read', 'Glob', 'Grep'];
+
+const codexSpec = (id) => require('./openai/relay.js').resolveCodexModelSpec(id);
+const codexIds = () => JSON.parse(fs.readFileSync(path.join(__dirname, 'openai', 'models.json'), 'utf8')).models.map((m) => m.id);
+
+/** null = not an executor id (a plain Claude id); {adapter, id} for a valid one; throws (message lists the valid ids) otherwise. */
+function parseExecutorModel(raw) {
+  const m = /^([A-Za-z][A-Za-z0-9_-]*):(.*)$/.exec(String(raw == null ? '' : raw).trim());
+  if (!m) return null;
+  const adapter = m[1].toLowerCase(); const id = m[2].trim();
+  if (adapter === 'codex') {
+    if (!codexSpec(id).matched) throw new Error(`unknown codex model '${id}'; valid: ${codexIds().map((i) => 'codex:' + i).join(', ')} (codex: alone = Codex default)`);
+    return { adapter, id };
+  }
+  if (adapter === 'deepseek') {
+    if (!DEEPSEEK_MODELS.includes(id)) throw new Error(`unknown deepseek model '${id}'; valid: ${DEEPSEEK_MODELS.map((i) => 'deepseek:' + i).join(', ')}`);
+    return { adapter, id };
+  }
+  throw new Error(`unknown executor prefix '${m[1]}:'; valid prefixes: codex:<id>, deepseek:<model>`);
+}
+
+/** DEEPSEEK_API_KEY, else deepseek_api_key in ~/.kenaz/credentials.yaml; null when neither. */
+function deepseekKey(env = process.env, home = os.homedir()) {
+  if (env.DEEPSEEK_API_KEY && env.DEEPSEEK_API_KEY.trim()) return env.DEEPSEEK_API_KEY.trim();
+  try {
+    const m = /^\s*deepseek_api_key\s*:\s*["']?([^"'\r\n#]+?)["']?\s*(?:#.*)?$/m.exec(fs.readFileSync(path.join(home, '.kenaz', 'credentials.yaml'), 'utf8'));
+    return m ? m[1].trim() : null;
+  } catch { return null; }
+}
+
+/** argv + extra env for the child; the prompt is NOT in here (stdin). */
+function buildChild({ adapter, id, worktree, lastFile, key, gitDir }) {
+  if (adapter === 'codex') {
+    const spec = codexSpec(id);
+    const args = ['exec', '-C', worktree];
+    if (spec.model) args.push('-m', spec.model);
+    args.push('-c', `model_reasoning_effort=${spec.reasoning_effort}`, '--sandbox', 'workspace-write', '-o', lastFile);
+    // A worktree's index, refs and objects live in the main repo's .git, outside -C. On Windows the sandbox still
+    // refuses those writes with --add-dir (measured 2026-10-11), so run() commits the leftovers after the agent.
+    if (gitDir) args.push('--add-dir', gitDir);
+    return { bin: 'codex', args, env: {}, unset: [] };
+  }
+  return { bin: 'claude', args: ['-p', '--allowedTools', ...CLAUDE_TOOLS], env: deepseekEnv(id, key), unset: DEEPSEEK_UNSET };
+}
+
+/** Claude Code env for DeepSeek's Anthropic-compatible endpoint (shared by exec.js and `kenaz launch --provider deepseek`).
+ *  Every model slot points at DeepSeek: background requests (small/fast = haiku) and Agent-tool subagents
+ *  (sonnet/opus aliases) would otherwise ask DeepSeek for Claude model names it does not serve. */
+function deepseekEnv(id, key) {
+  return {
+    ANTHROPIC_BASE_URL: DEEPSEEK_BASE_URL, ANTHROPIC_AUTH_TOKEN: key, ANTHROPIC_MODEL: id, ANTHROPIC_SMALL_FAST_MODEL: id,
+    ANTHROPIC_DEFAULT_HAIKU_MODEL: id, ANTHROPIC_DEFAULT_SONNET_MODEL: id, ANTHROPIC_DEFAULT_OPUS_MODEL: id, CLAUDE_CODE_SUBAGENT_MODEL: id,
+    // Claude Code does not know DeepSeek ids and assumes a 200k window; DeepSeek serves 128k, so auto-compact must start earlier.
+    CLAUDE_CODE_MAX_CONTEXT_TOKENS: String(DEEPSEEK_CONTEXT_TOKENS),
+  };
+}
+const DEEPSEEK_UNSET = ['ANTHROPIC_API_KEY']; // never send a real Anthropic key to another vendor
+
+const git = (cwd, args) => spawnSync('git', args, { cwd, encoding: 'utf8', windowsHide: true });
+// Same exclusions as the dispatch prompt's commit command (session telemetry never rides along).
+const COMMIT_EXCLUDES = [':!.kenaz/sessions', ':!.kenaz/specialist', ':!.formation/.dispatch-branch', ':!.formation/analytics', ':!.kenaz/channel_heartbeats.jsonl'];
+const EXECUTOR_NOTE = '\n\n## Executor note\nThe executor commits your changes after you finish: a sandbox may refuse git writes in this worktree. ' +
+  'If git add/commit fails, do not retry or work around it; finish the edits and report.\n';
+/** Commit what the agent left uncommitted (a sandboxed Codex cannot write the worktree's .git). @returns sha or null */
+function commitLeftovers(worktree, adapter) {
+  if (!(git(worktree, ['status', '--porcelain', '--', '.', ...COMMIT_EXCLUDES]).stdout || '').trim()) return null;
+  git(worktree, ['add', '-A', '--', '.', ...COMMIT_EXCLUDES]);
+  const branch = (git(worktree, ['rev-parse', '--abbrev-ref', 'HEAD']).stdout || '').trim();
+  if (git(worktree, ['commit', '--no-verify', '-m', `[${branch}] ${adapter} executor: agent's changes`]).status !== 0) return null;
+  return (git(worktree, ['rev-parse', '--short', 'HEAD']).stdout || '').trim();
+}
+const winQuote = (a) => (/^[\w@%+=:,./\\-]+$/.test(a) ? a : '"' + a.replace(/"/g, '\\"') + '"');
+
+/** Run the executor; resolves to the result object (also written to resultFile). Never throws for child failures. */
+async function run({ adapter, model = '', worktree, promptFile, resultFile, env = process.env, home = os.homedir() }) {
+  if (!['codex', 'deepseek'].includes(adapter)) throw new Error(`unknown adapter '${adapter}'`);
+  const started = Date.now();
+  const key = adapter === 'deepseek' ? deepseekKey(env, home) : null;
+  if (adapter === 'deepseek' && !key) throw new Error('deepseek: no API key (set DEEPSEEK_API_KEY or deepseek_api_key in ~/.kenaz/credentials.yaml)');
+  const redact = (s) => (key ? String(s).split(key).join('***') : String(s));
+  const base = (git(worktree, ['rev-parse', 'HEAD']).stdout || '').trim();
+  const lastFile = resultFile + '.last.txt';
+  const gitDir = (git(worktree, ['rev-parse', '--path-format=absolute', '--git-common-dir']).stdout || '').trim();
+  const c = buildChild({ adapter, id: model, worktree, lastFile, key, gitDir });
+  const childEnv = { ...env, ...c.env };
+  for (const k of c.unset) delete childEnv[k];
+  const win = process.platform === 'win32';
+  const child = spawn(win ? [c.bin, ...c.args].map(winQuote).join(' ') : c.bin, win ? [] : c.args, { cwd: worktree, env: childEnv, shell: win, windowsHide: true });
+  let out = '';
+  child.stdout.on('data', (d) => { out += d; }); child.stderr.on('data', (d) => { out += d; });
+  child.stdin.on('error', () => {});
+  child.stdin.end(Buffer.concat([fs.readFileSync(promptFile), Buffer.from(EXECUTOR_NOTE)]));
+  const code = await new Promise((res) => { child.on('error', (e) => { out += `spawn error: ${e.message}\n`; res(127); }); child.on('close', (n) => res(n == null ? 1 : n)); });
+  let last = '';
+  if (adapter === 'codex') { try { last = fs.readFileSync(lastFile, 'utf8'); } catch { /* none */ } } else last = out;
+  const executorCommit = commitLeftovers(worktree, adapter);
+  const commits = (git(worktree, ['log', '--format=%h %s', base + '..HEAD']).stdout || '').split('\n').filter(Boolean);
+  const ok = code === 0 && commits.length > 0;
+  const result = {
+    adapter, model, ok, exitCode: code, ...(executorCommit ? { executorCommit } : {}), durationMs: Date.now() - started, worktree,
+    ...(code === 0 && !commits.length ? { error: 'no commits' } : {}),
+    lastMessage: redact(last).slice(-8000), commits, log: redact(out).slice(-20000),
+  };
+  fs.mkdirSync(path.dirname(resultFile), { recursive: true });
+  fs.writeFileSync(resultFile, JSON.stringify(result, null, 2) + '\n');
+  return result;
+}
+
+async function main(argv) {
+  const a = {};
+  for (let i = 0; i < argv.length; i++) {
+    const m = /^--([a-z-]+)(?:=(.*))?$/.exec(argv[i]);
+    if (m) a[m[1]] = m[2] !== undefined ? m[2] : argv[++i];
+  }
+  if (!a.adapter || !a.worktree || !a['prompt-file'] || !a['result-file']) {
+    console.error('usage: exec.js --adapter=codex|deepseek --model=<id> --worktree <dir> --prompt-file <f> --result-file <f>');
+    return 2;
+  }
+  try {
+    const r = await run({ adapter: a.adapter, model: a.model || '', worktree: a.worktree, promptFile: a['prompt-file'], resultFile: a['result-file'] });
+    console.log(`${r.ok ? 'OK' : 'FAILED'} ${a.adapter} exit=${r.exitCode}${r.error ? ' ' + r.error : ''} commits=${r.commits.length} result=${a['result-file']}`);
+    return r.ok ? 0 : 1;
+  } catch (e) { console.error('exec.js: ' + e.message); return 2; }
+}
+
+if (require.main === module) main(process.argv.slice(2)).then((c) => { process.exitCode = c; });
+module.exports = { parseExecutorModel, deepseekKey, deepseekEnv, DEEPSEEK_UNSET, winQuote, buildChild, run, main, DEEPSEEK_MODELS };

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

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * `kenaz launch --provider deepseek [--model deepseek-chat|deepseek-reasoner] [claude args...]`
+ * Starts Claude Code with every model request sent to another vendor's Anthropic-compatible endpoint, so
+ * Ansuz (/kenaz:Ansuz), its subagents and background requests run on that vendor and use no Claude quota.
+ * The key is read from the env or ~/.kenaz/credentials.yaml and set only in the claude child's env: never in
+ * argv, never in ~/.claude/settings.json. Other terminals keep using Claude as usual.
+ */
+const os = require('os');
+const { spawn } = require('child_process');
+const { deepseekKey, deepseekEnv, DEEPSEEK_UNSET, DEEPSEEK_MODELS, winQuote } = require('./exec');
+
+const PROVIDERS = {
+  deepseek: {
+    models: DEEPSEEK_MODELS, key: deepseekKey, env: deepseekEnv, unset: DEEPSEEK_UNSET,
+    keyHelp: 'set DEEPSEEK_API_KEY, or add `deepseek_api_key: <key>` to ~/.kenaz/credentials.yaml',
+  },
+};
+const USAGE = 'usage: kenaz launch --provider <' + Object.keys(PROVIDERS).join('|') + '> [--model <id>] [claude args...]';
+
+/** Child process plan: { bin, args, env }. Throws with a user-facing message. */
+function plan(argv, env = process.env, home = os.homedir()) {
+  const rest = []; let provider = null; let model = null;
+  for (let i = 0; i < argv.length; i++) {
+    const m = /^--(provider|model)(?:=(.*))?$/.exec(argv[i]);
+    if (!m) { rest.push(argv[i]); continue; }
+    const v = m[2] !== undefined ? m[2] : argv[++i];
+    if (m[1] === 'provider') provider = v; else model = v;
+  }
+  const p = PROVIDERS[provider];
+  if (!p) throw new Error((provider ? `unknown provider '${provider}'. ` : '') + USAGE);
+  const id = model || p.models[0];
+  if (!p.models.includes(id)) throw new Error(`unknown ${provider} model '${id}'; valid: ${p.models.join(', ')}`);
+  const key = p.key(env, home);
+  if (!key) throw new Error(`${provider}: no API key (${p.keyHelp})`);
+  const childEnv = { ...env, ...p.env(id, key), CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1' };
+  for (const k of p.unset) delete childEnv[k];
+  return { bin: 'claude', args: rest, env: childEnv, provider, model: id };
+}
+
+/** Resolves to the child's exit code. deps: { spawn, env, home, platform } for tests. */
+function main(argv, out = console.log, deps = {}) {
+  let pl;
+  try { pl = plan(argv, deps.env || process.env, deps.home || os.homedir()); } catch (e) { out(e.message); return Promise.resolve(2); }
+  out(`kenaz launch: Claude Code on ${pl.provider} (${pl.model}); no Claude quota is used in this session`);
+  const win = (deps.platform || process.platform) === 'win32'; // claude is a .cmd shim on npm installs
+  const child = (deps.spawn || spawn)(win ? [pl.bin, ...pl.args].map(winQuote).join(' ') : pl.bin, win ? [] : pl.args,
+    { stdio: 'inherit', env: pl.env, shell: win });
+  return new Promise((res) => {
+    child.on('error', (e) => { out('kenaz launch: cannot start claude: ' + e.message); res(127); });
+    child.on('close', (n) => res(n == null ? 1 : n));
+  });
+}
+
+if (require.main === module) main(process.argv.slice(2)).then((c) => { process.exitCode = c; });
+module.exports = { plan, main, PROVIDERS };

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

@@ -0,0 +1,62 @@
+// kenaz launch --provider deepseek (provider-launch.js): fake spawn and temp homes only, never the real claude.
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { EventEmitter } = require('events');
+const { main, plan } = require('./provider-launch');
+
+const KEY = 'sk-test-deepseek-0123456789';
+const home = () => fs.mkdtempSync(path.join(os.tmpdir(), 'kenaz-launch-'));
+function fakeSpawn(calls, code = 0) {
+  return (cmd, args, opts) => { calls.push({ cmd, args, opts }); const c = new EventEmitter(); setImmediate(() => c.emit('close', code)); return c; };
+}
+
+test('deepseek: every model slot points at DeepSeek, key only in the child env, Anthropic key removed', async () => {
+  const calls = [], lines = [];
+  const rc = await main(['--provider', 'deepseek', '--resume', 'abc'], (l) => lines.push(l),
+    { spawn: fakeSpawn(calls), env: { DEEPSEEK_API_KEY: KEY, ANTHROPIC_API_KEY: 'real-anthropic', PATH: 'p' }, home: home(), platform: 'linux' });
+  assert.strictEqual(rc, 0);
+  const c = calls[0];
+  assert.strictEqual(c.cmd, 'claude');
+  assert.deepStrictEqual(c.args, ['--resume', 'abc'], 'other args pass through to claude');
+  const e = c.opts.env;
+  assert.strictEqual(e.ANTHROPIC_BASE_URL, 'https://api.deepseek.com/anthropic');
+  assert.strictEqual(e.ANTHROPIC_AUTH_TOKEN, KEY);
+  for (const k of ['ANTHROPIC_MODEL', 'ANTHROPIC_SMALL_FAST_MODEL', 'ANTHROPIC_DEFAULT_HAIKU_MODEL', 'ANTHROPIC_DEFAULT_SONNET_MODEL', 'ANTHROPIC_DEFAULT_OPUS_MODEL', 'CLAUDE_CODE_SUBAGENT_MODEL']) {
+    assert.strictEqual(e[k], 'deepseek-chat', k);
+  }
+  assert.strictEqual(e.ANTHROPIC_API_KEY, undefined);
+  assert.strictEqual(e.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, '1');
+  assert.strictEqual(e.PATH, 'p', 'the rest of the env is kept');
+  assert.ok(!JSON.stringify(c.args).includes(KEY) && !lines.join('\n').includes(KEY), 'key never in argv or output');
+});
+
+test('--model, key from ~/.kenaz/credentials.yaml, Windows goes through the shell', async () => {
+  const h = home(); fs.mkdirSync(path.join(h, '.kenaz'));
+  fs.writeFileSync(path.join(h, '.kenaz', 'credentials.yaml'), `relay: x\ndeepseek_api_key: "${KEY}"\n`);
+  const calls = [];
+  const rc = await main(['--provider=deepseek', '--model', 'deepseek-reasoner'], () => {}, { spawn: fakeSpawn(calls), env: {}, home: h, platform: 'win32' });
+  assert.strictEqual(rc, 0);
+  assert.strictEqual(calls[0].cmd, 'claude');
+  assert.strictEqual(calls[0].opts.shell, true);
+  assert.strictEqual(calls[0].opts.env.ANTHROPIC_MODEL, 'deepseek-reasoner');
+  assert.ok(!calls[0].cmd.includes(KEY));
+});
+
+test('control: no key, unknown provider or model -> exit 2 and claude is never started', async () => {
+  for (const [argv, env, re] of [
+    [['--provider', 'deepseek'], {}, /no API key/],
+    [['--provider', 'nope'], { DEEPSEEK_API_KEY: KEY }, /unknown provider 'nope'/],
+    [[], { DEEPSEEK_API_KEY: KEY }, /usage: kenaz launch --provider <deepseek>/],
+    [['--provider', 'deepseek', '--model', 'gpt-x'], { DEEPSEEK_API_KEY: KEY }, /valid: deepseek-chat, deepseek-reasoner/],
+  ]) {
+    const calls = [], lines = [];
+    const rc = await main(argv, (l) => lines.push(l), { spawn: fakeSpawn(calls), env, home: home(), platform: 'linux' });
+    assert.strictEqual(rc, 2, argv.join(' '));
+    assert.strictEqual(calls.length, 0, 'claude not started: ' + argv.join(' '));
+    assert.match(lines.join('\n'), re);
+  }
+  assert.throws(() => plan(['--provider', 'deepseek'], {}, home()), /no API key/);
+});

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

@@ -225,7 +225,7 @@ function uninstall(options = {}) {
   for (let n = 0; n < segs.length; n++) {
     const [h, body] = segs[n], nx = segs[n + 1];
     if (h && /^\s*\[\[hooks\.\w+\]\]\s*$/.test(h) && nx && nx[0] && /^\s*\[\[hooks\.\w+\.hooks\]\]/.test(nx[0]) &&
-        nx[1].join('\n').split('\\').join('/').includes(HOOK_SHIM_REL)) { n++; res.hooks = 'removed'; continue; }
+        isKenazHandler(nx)) { n++; res.hooks = 'removed'; continue; } // TASK_2418: any checkout's shim, same identity rule as missingHookEvents
     out.push(...body.filter((l) => !/^# kenaz-dashboard native hooks/.test(l)));
   }
   if (res.hooks === 'removed' && !dryRun) fs.writeFileSync(cfg, out.join('\n').replace(/\n{3,}/g, '\n\n'), 'utf8');
@@ -283,23 +283,82 @@ function getHookShimPath(_projectRoot) {
   return path.resolve(__dirname, '..', '..', HOOK_SHIM_REL);
 }
 
+// TASK_2418: what counts as a kenaz hook, and what counts as a CURRENT one.
+// A handler is kenaz's when its command runs codex-hook-shim.js (any checkout). It is current only when it
+// runs exactly this core's shim (absolute path, slashes normalized, Windows case-insensitive) and the
+// UserPromptSubmit one carries --pull (TASK_2379). Stale ones are replaced in place, never duplicated; handlers
+// that do not run our shim are never touched.
+const HOOK_SHIM_NAME = path.posix.basename(HOOK_SHIM_REL);
+const HOOK_MARKER = /^# kenaz-dashboard native hooks/;
+const HANDLER_HEADER = /^\s*\[\[hooks\.(\w+)\.hooks\]\]\s*$/;
+const GROUP_HEADER = /^\s*\[\[hooks\.(\w+)\]\]\s*$/;
+const slashes = (s) => String(s).replace(/\\/g, '/');
+const foldCase = (s) => (process.platform === 'win32' ? s.toLowerCase() : s);
+
+function parseSegments(text) { // [header line | null, body lines]
+  const segs = [];
+  for (const line of text.split(/\r?\n/)) {
+    if (/^\s*\[/.test(line) || !segs.length) segs.push([/^\s*\[/.test(line) ? line : null, [line]]);
+    else segs[segs.length - 1][1].push(line);
+  }
+  return segs;
+}
+const isKenazHandler = (seg) => slashes(seg[1].join('\n')).includes(HOOK_SHIM_NAME);
+function isCurrentHandler(ev, seg, projectRoot) {
+  const m = slashes(seg[1].join('\n')).match(/^\s*command\s*=\s*(.*)$/m);
+  if (!m) return false;
+  const cmd = foldCase(m[1]);
+  const shim = foldCase(slashes(getHookShimPath(projectRoot)));
+  const at = cmd.indexOf('"' + shim + '"');
+  if (at < 0) return false;
+  return ev !== 'UserPromptSubmit' || /(^|\s)--pull(\s|['"]|$)/.test(cmd.slice(at + shim.length + 2));
+}
+/** Per event: segment indexes of kenaz handlers, split into current / stale. */
+function scanKenazHooks(text, projectRoot) {
+  const segs = parseSegments(text), found = {};
+  segs.forEach((seg, i) => {
+    const m = seg[0] && seg[0].match(HANDLER_HEADER);
+    if (!m || !HOOK_EVENTS.includes(m[1]) || !isKenazHandler(seg)) return;
+    const f = found[m[1]] || (found[m[1]] = { current: [], stale: [] });
+    (isCurrentHandler(m[1], seg, projectRoot) ? f.current : f.stale).push(i);
+  });
+  return { segs, found };
+}
+/** config text without the kenaz handlers of `events` (and the empty group each one leaves behind). */
+function stripKenazHooks(text, events, projectRoot) {
+  const { segs, found } = scanKenazHooks(text, projectRoot);
+  const drop = new Set();
+  for (const ev of events) {
+    for (const i of [...(found[ev] ? found[ev].current : []), ...(found[ev] ? found[ev].stale : [])]) {
+      drop.add(i);
+      const prev = segs[i - 1], next = segs[i + 1];
+      const g = prev && prev[0] && prev[0].match(GROUP_HEADER);
+      if (g && g[1] === ev && !(next && next[0] && HANDLER_HEADER.test(next[0]) && next[0].includes('.' + ev + '.'))
+          && prev[1].slice(1).every((l) => !l.trim())) drop.add(i - 1);
+    }
+  }
+  const out = [];
+  segs.forEach((seg, i) => {
+    if (!drop.has(i)) { out.push(...seg[1]); return; }
+    out.push(...seg[1].slice(1).filter((l) => /^\s*#/.test(l) && !HOOK_MARKER.test(l))); // keep neighbours' comments
+  });
+  return out.join('\n');
+}
+
 function areHooksAlreadyRegistered(projectRoot) {
   const configPath = getCodexConfigPath();
   if (!fs.existsSync(configPath)) return false;
-  const content = fs.readFileSync(configPath, 'utf8');
-  const shimPath = getHookShimPath(projectRoot);
-  // Registered if config contains our shim path in any hooks entry
-  return content.includes(HOOK_SHIM_REL) || content.includes(shimPath.split('\\').join('/'));
+  // at least one CURRENT kenaz handler: a block left by an old checkout does not run this core's shim
+  const { found } = scanKenazHooks(fs.readFileSync(configPath, 'utf8'), projectRoot);
+  return Object.values(found).some((f) => f.current.length > 0);
 }
 
-// TASK_2299: HOOK_EVENTS that have no [[hooks.EV.hooks]] block pointing at our shim in config.toml.
-function missingHookEvents() {
+// TASK_2299: HOOK_EVENTS without exactly one current kenaz handler. TASK_2418: stale (old checkout path,
+// UserPromptSubmit without --pull) and duplicated ones count as missing, so registerHooks rewrites them.
+function missingHookEvents(projectRoot) {
   const configPath = getCodexConfigPath();
-  const content = fs.existsSync(configPath) ? fs.readFileSync(configPath, 'utf8').replace(/\\/g, '/') : '';
-  return HOOK_EVENTS.filter((ev) => {
-    const blocks = content.match(new RegExp('\\[\\[hooks\\.' + ev + '\\.hooks\\]\\][^\\[]*', 'g')) || [];
-    return !blocks.some((blk) => blk.includes(HOOK_SHIM_REL));
-  });
+  const { found } = scanKenazHooks(fs.existsSync(configPath) ? fs.readFileSync(configPath, 'utf8') : '', projectRoot);
+  return HOOK_EVENTS.filter((ev) => !found[ev] || found[ev].stale.length > 0 || found[ev].current.length !== 1);
 }
 
 // True when the codex CLI both supports hooks AND our shim is registered.
@@ -313,6 +372,7 @@ function nativeHooksActive(projectRoot) {
 function registerHooks(log, projectRoot, events) {
   const shimPath = getHookShimPath(projectRoot).split('\\').join('/');
   const configPath = getCodexConfigPath();
+  const evs = events || HOOK_EVENTS;
 
   // Ensure ~/.codex dir exists
   const codexDir = path.dirname(configPath);
@@ -322,8 +382,16 @@ function registerHooks(log, projectRoot, events) {
 
   // [[hooks.X]] array-of-tables entries are additive-safe TOML: appending is valid
   // even if the user already has their own [[hooks.X]] entries from other tools.
-  const lines = ['', '# kenaz-dashboard native hooks (TASK_1733) -- auto-registered by setup-codex.js'];
-  for (const ev of events || HOOK_EVENTS) {
+  // TASK_2418: kenaz handlers already present for these events (stale or not) are dropped first, so each
+  // event ends with exactly one current handler.
+  let kept = '';
+  try {
+    kept = fs.existsSync(configPath) ? stripKenazHooks(fs.readFileSync(configPath, 'utf8'), evs, projectRoot) : '';
+    if (!Object.keys(scanKenazHooks(kept, projectRoot).found).length) kept = kept.split('\n').filter((l) => !HOOK_MARKER.test(l)).join('\n');
+  } catch (err) { log('hook registration failed: ' + err.message); return { success: false, action: 'hooks_failed', error: err.message }; }
+  const lines = [''];
+  if (!kept.split('\n').some((l) => HOOK_MARKER.test(l))) lines.push('# kenaz-dashboard native hooks (TASK_1733) -- auto-registered by setup-codex.js');
+  for (const ev of evs) {
     lines.push(
       '[[hooks.' + ev + ']]',
       '',
@@ -337,8 +405,8 @@ function registerHooks(log, projectRoot, events) {
   const hookBlock = lines.join('\n');
 
   try {
-    fs.appendFileSync(configPath, hookBlock, 'utf8');
-    log('kenaz hooks appended to ' + configPath);
+    fs.writeFileSync(configPath, kept + (kept && !kept.endsWith('\n') ? '\n' : '') + hookBlock, 'utf8');
+    log('kenaz hooks written to ' + configPath);
     return { success: true, action: 'hooks_registered' };
   } catch (err) {
     log('hook registration failed: ' + err.message);

package/core/.formation/tools/__tests__/dispatch-model.test.js

@@ -1,5 +1,5 @@
 'use strict';
-// `kenaz model` (dispatch-model.js): temp project dirs only.
+// `kenaz subagent` (dispatch-model.js): temp project dirs only.
 const { test } = require('node:test');
 const assert = require('node:assert/strict');
 const fs = require('node:fs');

package/core/.formation/tools/__tests__/subagent-executor.test.js

@@ -0,0 +1,198 @@
+'use strict';
+// TASK_2422: codex:/deepseek: executors. Stub `codex` and `claude` on PATH, temp dirs only
+// (never the real ~/.codex, ~/.claude, ~/.kenaz; no real codex/claude/wscript is ever started).
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { spawnSync } = require('node:child_process');
+
+const ROOT = path.resolve(__dirname, '..', '..', '..');
+const EXEC = path.join(ROOT, '.formation', 'bifrost', 'exec.js');
+const DISPATCH = path.join(ROOT, '.formation', 'tools', 'dispatch.js');
+const TASKAPI = path.join(ROOT, '.collaboration', 'core', 'task-api.js');
+const dm = require('../dispatch-model');
+const KEY = 'sk-test-DEEPSEEK-SECRET-1234567890';
+
+const tmp = (t, p) => { const d = fs.mkdtempSync(path.join(os.tmpdir(), p)); t.after(() => fs.rmSync(d, { recursive: true, force: true })); return d; };
+const git = (cwd, args) => spawnSync('git', ['-c', 'user.name=t', '-c', 'user.email=t@t', ...args], { cwd, encoding: 'utf8', windowsHide: true });
+function repo(t) {
+  const d = tmp(t, 'exec-wt-');
+  fs.writeFileSync(path.join(d, 'README.md'), 'x'); git(d, ['init', '-q']); git(d, ['add', '-A']); git(d, ['commit', '-q', '--no-verify', '-m', 'init']);
+  return d;
+}
+
+// One stub script serves both binaries: records argv/env/stdin to STUB_OUT/<name>.json, optionally commits.
+const STUB_JS = `
+const fs = require('fs'), path = require('path'), cp = require('child_process');
+const name = path.basename(process.argv[1], '.js');
+let stdin = ''; process.stdin.on('data', (d) => { stdin += d; });
+process.stdin.on('end', () => {
+  const argv = process.argv.slice(2);
+  fs.writeFileSync(path.join(process.env.STUB_OUT, name + '.json'), JSON.stringify({ argv, cwd: process.cwd(), stdin,
+    env: { ANTHROPIC_BASE_URL: process.env.ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN: process.env.ANTHROPIC_AUTH_TOKEN, ANTHROPIC_MODEL: process.env.ANTHROPIC_MODEL, ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY } }));
+  if (process.env.STUB_WRITE_ONLY) fs.writeFileSync(path.join(process.cwd(), 'left.txt'), 'x'); // a sandboxed agent: edits, cannot commit
+  if (process.env.STUB_COMMIT) {
+    fs.writeFileSync(path.join(process.cwd(), 'out.txt'), 'x');
+    cp.spawnSync('git', ['add', '-A'], { cwd: process.cwd() });
+    cp.spawnSync('git', ['-c', 'user.name=t', '-c', 'user.email=t@t', 'commit', '-q', '--no-verify', '-m', 'stub work'], { cwd: process.cwd() });
+  }
+  const o = argv.indexOf('-o'); if (o >= 0) fs.writeFileSync(argv[o + 1], 'codex last message');
+  if (name === 'claude') console.log('claude says ' + (process.env.STUB_ECHO_KEY ? process.env.ANTHROPIC_AUTH_TOKEN : 'done'));
+  process.exit(Number(process.env.STUB_EXIT || 0));
+});`;
+function stubs(t) {
+  const bin = tmp(t, 'exec-bin-');
+  for (const n of ['codex', 'claude']) {
+    fs.writeFileSync(path.join(bin, n + '.js'), STUB_JS);
+    if (process.platform === 'win32') fs.writeFileSync(path.join(bin, n + '.cmd'), `@node "%~dp0${n}.js" %*\r\n`);
+    else { fs.writeFileSync(path.join(bin, n), `#!/bin/sh\nexec node "$(dirname "$0")/${n}.js" "$@"\n`); fs.chmodSync(path.join(bin, n), 0o755); }
+  }
+  return bin;
+}
+function runExec(t, { adapter, model, extraEnv = {}, key = KEY }) {
+  const wt = repo(t); const bin = stubs(t); const out = tmp(t, 'exec-out-'); const home = tmp(t, 'exec-home-');
+  const prompt = path.join(out, 'p.md'); fs.writeFileSync(prompt, 'DO THE CARD');
+  const result = path.join(out, 'r.json');
+  const env = { ...process.env, PATH: bin + path.delimiter + process.env.PATH, STUB_OUT: out, HOME: home, USERPROFILE: home, STUB_COMMIT: '1', ...extraEnv };
+  delete env.DEEPSEEK_API_KEY; delete env.ANTHROPIC_API_KEY; if (key) env.DEEPSEEK_API_KEY = key;
+  const r = spawnSync(process.execPath, [EXEC, `--adapter=${adapter}`, `--model=${model}`, '--worktree', wt, '--prompt-file', prompt, '--result-file', result], { env, encoding: 'utf8', windowsHide: true });
+  const read = (f) => { try { return JSON.parse(fs.readFileSync(path.join(out, f), 'utf8')); } catch { return null; } };
+  return { r, wt, out, result: fs.existsSync(result) ? JSON.parse(fs.readFileSync(result, 'utf8')) : null, resultPath: result, codex: read('codex.json'), claude: read('claude.json'), home };
+}
+
+test('codex executor: exact argv, prompt on stdin, result file with commits', (t) => {
+  const x = runExec(t, { adapter: 'codex', model: 'gpt-5.6-sol-high' });
+  assert.equal(x.r.status, 0, x.r.stdout + x.r.stderr);
+  const gitDir = require('child_process').execFileSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], { cwd: x.wt, encoding: 'utf8' }).trim();
+  assert.deepEqual(x.codex.argv, ['exec', '-C', x.wt, '-m', 'gpt-5.6-sol', '-c', 'model_reasoning_effort=high', '--sandbox', 'workspace-write', '-o', x.resultPath + '.last.txt', '--add-dir', gitDir]);
+  assert.match(x.codex.stdin, /^DO THE CARD\n\n## Executor note\n/);
+  assert.equal(fs.realpathSync(x.codex.cwd), fs.realpathSync(x.wt));
+  assert.equal(x.result.ok, true); assert.equal(x.result.exitCode, 0);
+  assert.equal(x.result.lastMessage, 'codex last message');
+  assert.match(x.result.commits[0], /stub work/);
+  assert.ok(fs.existsSync(x.wt), 'worktree is never removed');
+});
+
+test('codex default (empty id): no -m, project default effort', (t) => {
+  const x = runExec(t, { adapter: 'codex', model: '' });
+  assert.equal(x.r.status, 0, x.r.stdout + x.r.stderr);
+  assert.equal(x.codex.argv.includes('-m'), false);
+  assert.ok(x.codex.argv.includes('model_reasoning_effort=medium'));
+});
+
+test('codex without commits is reported as failure (no commits)', (t) => {
+  const x = runExec(t, { adapter: 'codex', model: '', extraEnv: { STUB_COMMIT: '' } });
+  assert.equal(x.r.status, 1);
+  assert.equal(x.result.ok, false); assert.equal(x.result.error, 'no commits');
+});
+
+test('deepseek executor: env only in the child, key absent from argv, stdout, result file', (t) => {
+  const x = runExec(t, { adapter: 'deepseek', model: 'deepseek-chat', extraEnv: { ANTHROPIC_API_KEY: 'real-anthropic-key', STUB_ECHO_KEY: '1' } });
+  assert.equal(x.r.status, 0, x.r.stdout + x.r.stderr);
+  assert.deepEqual(x.claude.argv, ['-p', '--allowedTools', 'Bash', 'Edit', 'Write', 'Read', 'Glob', 'Grep']);
+  assert.deepEqual(x.claude.env, { ANTHROPIC_BASE_URL: 'https://api.deepseek.com/anthropic', ANTHROPIC_AUTH_TOKEN: KEY, ANTHROPIC_MODEL: 'deepseek-chat' });
+  assert.match(x.claude.stdin, /^DO THE CARD\n\n## Executor note\n/);
+  assert.equal(JSON.stringify(x.claude.argv).includes(KEY), false);
+  assert.equal((x.r.stdout + x.r.stderr).includes(KEY), false);
+  const raw = fs.readFileSync(x.resultPath, 'utf8');
+  assert.equal(raw.includes(KEY), false);
+  assert.match(x.result.lastMessage, /claude says \*\*\*/); // the stub echoed the key: it was redacted
+  assert.equal(JSON.stringify(x.result).includes('real-anthropic-key'), false);
+});
+
+test('deepseek key from ~/.kenaz/credentials.yaml; missing key fails before anything starts', (t) => {
+  const none = runExec(t, { adapter: 'deepseek', model: 'deepseek-chat', key: null });
+  assert.equal(none.r.status, 2); assert.match(none.r.stderr, /no API key/);
+  assert.equal(none.claude, null); assert.equal(none.result, null);
+  // credentials file route (home is a temp dir)
+  const wt = repo(t); const bin = stubs(t); const out = tmp(t, 'exec-out-'); const home = tmp(t, 'exec-home-');
+  fs.mkdirSync(path.join(home, '.kenaz')); fs.writeFileSync(path.join(home, '.kenaz', 'credentials.yaml'), `other: 1\ndeepseek_api_key: "${KEY}"\n`);
+  const prompt = path.join(out, 'p.md'); fs.writeFileSync(prompt, 'P');
+  const env = { ...process.env, PATH: bin + path.delimiter + process.env.PATH, STUB_OUT: out, HOME: home, USERPROFILE: home, STUB_COMMIT: '1' };
+  delete env.DEEPSEEK_API_KEY;
+  const r = spawnSync(process.execPath, [EXEC, '--adapter=deepseek', '--model=deepseek-reasoner', '--worktree', wt, '--prompt-file', prompt, '--result-file', path.join(out, 'r.json')], { env, encoding: 'utf8', windowsHide: true });
+  assert.equal(r.status, 0, r.stdout + r.stderr);
+  assert.equal(JSON.parse(fs.readFileSync(path.join(out, 'claude.json'), 'utf8')).env.ANTHROPIC_AUTH_TOKEN, KEY);
+});
+
+// ---- kenaz subagent set/unset/show ----
+const dmRun = (argv, cwd) => { const out = []; const code = dm.main(argv, (l) => out.push(l), cwd); return { code, out: out.join('\n') }; };
+const modelsOf = (p) => JSON.parse(fs.readFileSync(path.join(p, '.kenaz', 'dashboard-models.json'), 'utf8'));
+
+test('subagent set/unset/show: codex:, deepseek:, codex: alone', (t) => {
+  const p = tmp(t, 'dm-');
+  assert.equal(dmRun(['set', 'codex:gpt-5.6-sol'], p).code, 0);
+  assert.equal(dmRun(['set', 'deepseek:deepseek-chat', '--rigor', 'low'], p).code, 0);
+  assert.equal(dmRun(['set', 'codex:', '--rigor', 'high'], p).code, 0);
+  assert.deepEqual(modelsOf(p), { dispatchModel: 'codex:gpt-5.6-sol', dispatchModelByRigor: { low: 'deepseek:deepseek-chat', high: 'codex:' } });
+  const shown = dmRun([], p).out;
+  assert.match(shown, /low\s+deepseek:deepseek-chat -> executor deepseek/);
+  assert.match(shown, /medium\s+codex:gpt-5.6-sol -> executor codex/);
+  assert.match(shown, /high\s+codex: -> executor codex/);
+  dmRun(['unset', '--rigor', 'low'], p); dmRun(['unset'], p);
+  assert.deepEqual(modelsOf(p), { dispatchModelByRigor: { high: 'codex:' } });
+});
+
+test('subagent set: unknown codex id and unknown prefix are refused with the valid list; nothing written', (t) => {
+  const p = tmp(t, 'dm-');
+  const a = dmRun(['set', 'codex:nope'], p);
+  assert.equal(a.code, 1); assert.match(a.out, /unknown codex model 'nope'.*codex:gpt-5\.6-sol/);
+  const b = dmRun(['set', 'deepseek:gpt'], p);
+  assert.equal(b.code, 1); assert.match(b.out, /deepseek:deepseek-chat, deepseek:deepseek-reasoner/);
+  const c = dmRun(['set', 'gemini:pro'], p);
+  assert.equal(c.code, 1); assert.match(c.out, /unknown executor prefix 'gemini:'.*codex:<id>, deepseek:<model>/);
+  assert.equal(fs.existsSync(path.join(p, '.kenaz', 'dashboard-models.json')), false);
+  assert.equal(dmRun(['set', 'opus'], p).code, 0, 'plain Claude ids keep working');
+});
+
+// ---- dispatch.js: executor block vs the unchanged Claude control ----
+test('dispatch: executor block for codex:/deepseek:, byte-for-byte agentParams for a Claude id', (t) => {
+  const sb = tmp(t, 'exec-dispatch-');
+  for (const d of ['backlog', 'active', 'done', 'blocked', 'cancel']) fs.mkdirSync(path.join(sb, '.kenaz', 'tasks', d), { recursive: true });
+  fs.mkdirSync(path.join(sb, '.kenaz', 'locks'), { recursive: true });
+  fs.writeFileSync(path.join(sb, 'README.md'), 'x'); fs.writeFileSync(path.join(sb, '.gitignore'), '.formation/worktrees/\n.kenaz/\n');
+  git(sb, ['init', '-q']); git(sb, ['add', '-A']); git(sb, ['commit', '-q', '--no-verify', '-m', 'init']);
+  const env = { ...process.env, DEEPSEEK_API_KEY: KEY }; delete env.CLAUDE_PROJECT_DIR; delete env.CODEX_SESSION_ID; delete env.CODEX_THREAD_ID;
+  const sh = (script, args) => spawnSync(process.execPath, [script, ...args], { env, encoding: 'utf8', windowsHide: true, cwd: ROOT });
+  const mk = sh(TASKAPI, ['--project-path', sb, 'create', '--title', 't2422', '--description', 'd', '--scope-paths', 'zzz/a.js', '--requirements', 'r1',
+    '--acceptance-criteria', 'a1', '--acceptance-criteria', 'a2', '--acceptance-criteria', 'a3', '--technical-notes', 't1', '--technical-notes', 't2', '--force']);
+  const id = ((mk.stdout || '').match(/TASK_\d+/) || [])[0]; assert.ok(id, mk.stdout + mk.stderr);
+  const disp = (model) => {
+    fs.writeFileSync(path.join(sb, '.kenaz', 'dashboard-models.json'), JSON.stringify({ dispatchModel: model }));
+    const r = sh(DISPATCH, ['--skill=do', `--task=${id}`, '--dispatch-mode=subagent', '--project-path', sb, '--force']);
+    return { r, j: (() => { try { return JSON.parse(r.stdout); } catch { return null; } })() };
+  };
+  const cx = disp('codex:gpt-5.6-sol');
+  assert.ok(cx.j, cx.r.stdout + cx.r.stderr);
+  assert.equal(cx.j.agentParams, undefined);
+  assert.equal(cx.j.executor.adapter, 'codex'); assert.equal(cx.j.executor.branchName, `task/${id.toLowerCase()}`);
+  assert.ok(fs.existsSync(cx.j.executor.worktreePath), 'worktree created');
+  assert.equal(fs.readFileSync(cx.j.executor.promptFile, 'utf8'), cx.j.promptText);
+  assert.match(cx.j.executor.command, /exec\.js" --adapter=codex --model="gpt-5\.6-sol" --worktree/);
+  const ds = disp('deepseek:deepseek-chat');
+  assert.equal(ds.j.executor.adapter, 'deepseek');
+  assert.equal(ds.r.stdout.includes(KEY) || ds.r.stderr.includes(KEY), false, 'key never in the dispatch JSON or logs');
+  assert.equal(fs.readFileSync(ds.j.executor.promptFile, 'utf8').includes(KEY), false);
+  // control: Claude id -> the existing agentParams output, no executor block
+  const cl = disp('claude-sonnet-5-5');
+  assert.equal(cl.j.executor, undefined);
+  assert.equal(cl.j.agentParams.model, 'sonnet'); // cross-project sandbox: Agent isolation omitted, as before
+  assert.deepEqual(Object.keys(cl.j.agentParams), ['description', 'model']);
+  // a missing DeepSeek key is refused before any worktree/side effect
+  const noKey = { ...env }; delete noKey.DEEPSEEK_API_KEY; noKey.USERPROFILE = noKey.HOME = tmp(t, 'nokey-');
+  fs.writeFileSync(path.join(sb, '.kenaz', 'dashboard-models.json'), JSON.stringify({ dispatchModel: 'deepseek:deepseek-chat' }));
+  const nk = spawnSync(process.execPath, [DISPATCH, '--skill=do', `--task=${id}`, '--dispatch-mode=subagent', '--project-path', sb, '--force'], { env: noKey, encoding: 'utf8', windowsHide: true, cwd: ROOT });
+  assert.notEqual(nk.status, 0); assert.match(nk.stderr, /no API key/);
+});
+
+test('codex that edits but cannot commit (sandbox): exec.js commits the leftovers, telemetry excluded', (t) => {
+  const id = { GIT_AUTHOR_NAME: 't', GIT_AUTHOR_EMAIL: 't@t', GIT_COMMITTER_NAME: 't', GIT_COMMITTER_EMAIL: 't@t' };
+  const x = runExec(t, { adapter: 'codex', model: '', extraEnv: { STUB_COMMIT: '', STUB_WRITE_ONLY: '1', ...id } });
+  assert.equal(x.r.status, 0, x.r.stdout + x.r.stderr);
+  assert.equal(x.result.ok, true); assert.ok(x.result.executorCommit);
+  assert.match(x.result.commits[0], /codex executor: agent's changes/);
+  const files = require('child_process').execFileSync('git', ['show', '--name-only', '--format=', 'HEAD'], { cwd: x.wt, encoding: 'utf8' }).trim();
+  assert.strictEqual(files, 'left.txt');
+});