kenaz 0.3.12 → 0.3.14

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

@@ -8,7 +8,8 @@ ARGUMENTS 含 `[專案: X]` 或 `--project-path X` → PROJECT_PATH = X，下方
 ## Boot（一次 Bash，無其他儀式）
 1. Turn Context 若有 `[session] session_id=<id>`，記住 `<id>`。
 2. 執行 `node .specialist/tools/ansuz-boot-fast.js`（有 `<id>` 加 `--conversation-id="<id>"`；有 PROJECT_PATH 加 `--project-path`）。
-3. 把 banner 轉述給用戶（Bash 輸出在 UI 會摺疊），並依 `📋 Open cards` 直接提出議程。
+3. banner 有 `📎 Project handoff` 時，**先用 Read 讀 → 標記的那份全文**（不用問用戶），以它為準接續上一個 session。
+4. 把 banner 轉述給用戶（Bash 輸出在 UI 會摺疊），依 handoff 的 R 段與 `📋 Open cards` 直接提出議程。
 
 ## 每件工作的做法
 - **自己做**：小而明確的修正（約 30 行內、單一檔案或少數檔案）→ 直接改，跑最近的測試，提交。
@@ -16,6 +17,7 @@ ARGUMENTS 含 `[專案: X]` 或 `--project-path X` → PROJECT_PATH = X，下方
   1. 用 `kenaz_task_create` 開卡（`projectPath` = 目前專案；寫清楚 requirements、acceptance criteria、scope paths）。查卡、改狀態用 `kenaz_task_list` / `kenaz_task_get` / `kenaz_task_update`。
   2. 產生派工內容：`node .formation/tools/dispatch.js --skill=do --task=TASK_XXX --dispatch-mode=subagent`（有 PROJECT_PATH 加 `--project-path`）。把輸出 JSON 的 `promptText` 交給 subagent，`agentParams` 照用（模型不要自己換）。
   3. subagent 在 worktree 裡改完並 commit；你驗證後合併。
+     若輸出是 `executor` 區塊（模型為 `codex:<id>` / `deepseek:<model>`，無 agentParams）：用 Bash run_in_background 執行 `executor.command`，等完成通知，讀 `executor.resultFile`（ok、commits；`no commits` = 失敗），再照常驗證並合併 `executor.branchName`。
 - 開卡前先確認 scope 與驗收條件對準真正的問題，不要照著錯的假設派工。
 
 ## 驗證（合併前一定做，強度跟風險相稱）
@@ -24,6 +26,12 @@ ARGUMENTS 含 `[專案: X]` 或 `--project-path X` → PROJECT_PATH = X，下方
 - subagent 回報「未驗證」的項目，由你補驗或明講仍未驗證。
 - 合併：`git merge` 後跑相關測試（或 `node .specialist/Ansuz/tools/verify-and-land.js`），用這個專案自己的測試指令。
 
+## 交接（handoff，ISBAR）
+用戶說交接／暫停／換 session、context 快滿、或結束時仍有未完成的工作 → 寫交接：
+1. `node .specialist/tools/handoff-doc.js new --topic "<主題>" --session <id>`（有 PROJECT_PATH 加 `--project-path`），建立 `<專案>/.kenaz/handoffs/<日期時間>-<主題>.md`，I 段已自動填好。
+2. 用 Edit 填 S（現況）、B（背景：用戶決定原話、相關卡與 commit）、A（已驗證／未驗證／風險）、R（下一個 session 第一步、待用戶決定的事）。寫給「沒看過這段對話的人」，不寫空泛句。
+3. 一份交接一個檔，不覆寫舊的；下一個 session 的 boot 會自動列出並讀最新那份。
+
 ## 回報與提問
 - 一律用用戶的語言（中文訊息 → 中文回覆，含提問選項）。
 - 需要用戶決定時用 `AskUserQuestion`（2-4 個選項、建議的放第一個），不要在文字裡列選項等回覆；有證據能自己判斷的事不問。
@@ -38,5 +46,7 @@ Kenaz 的工具、hook、安裝、peer、派工擋住或拖慢工作時，**繞
 ## 參考產品（REA）與學習教訓
 - banner `[rea]` 行：用戶提到參考產品時，有 REA 就提議分析，沒有就提示一次 `npx rea-agents setup`（範圍見 RULES.md 的 REA）。
 - 用戶糾正/重複指示、推翻決定、或驗證抓到失敗時，自動寫教訓並在回報點名一行：`node .specialist/tools/lessons.js add --scope user|project --type pref|fact|pitfall|check --text "..."`（規則見 RULES.md 的 Lessons）。
+- banner 出現 `[lessons] N to graduate`：跑 `kenaz learn review`，提議把排第一的教訓改成代碼（測試、hook 檢查或專案 CLAUDE.md/AGENTS.md 規則，這是首選結果）；糾正若與既有教訓相符屬於重複（recurrence），不是新教訓（`add` 會自動累加）。
+- banner 出現 `[learn] N history items to review`：跑 `kenaz learn review`，每個歷史項目（返工、executor 失敗、blocked 卡、handoff 風險行）有現成的 `kenaz learn add ... --source harvest:<id>`，值得記的補上 why 後執行，其餘忽略；指標建議（各 rigor 一次過率、返工最多的檔案）只建議給用戶，不自行套用。詳見 RULES.md。
 
 需要更多規則時（授權自主、派工前、合併前、參考產品、寫教訓）讀 `.specialist/Ansuz/RULES.md`。

package/core/.claude/hooks/__tests__/correction-detect.test.js

@@ -0,0 +1,74 @@
+'use strict';
+// TASK_2426: correction detector fires on corrections only, is rate limited per session,
+// and honours the mode gate. Temp project dirs only.
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { isCorrection } = require('../correction-detect');
+
+const HOOK = path.join(__dirname, '..', 'correction-detect.js');
+
+function tmpProject(mode) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'kenaz-corr-'));
+  fs.mkdirSync(path.join(dir, '.kenaz'), { recursive: true });
+  fs.writeFileSync(path.join(dir, '.kenaz', 'project.yaml'), 'name: t\n');
+  if (mode) fs.writeFileSync(path.join(dir, '.kenaz', 'kenaz.yaml'), 'mode: ' + mode + '\n');
+  return dir;
+}
+
+function run(dir, prompt, session, extraEnv) {
+  const home = path.join(dir, 'home'); // keep the real ~/.kenaz/kenaz.yaml out of the test
+  const r = spawnSync(process.execPath, [HOOK], {
+    input: JSON.stringify({ session_id: session || 's1', prompt }),
+    encoding: 'utf8',
+    env: { ...process.env, CLAUDE_PROJECT_DIR: dir, USERPROFILE: home, HOME: home, KENAZ_MODE: '', ...extraEnv },
+  });
+  assert.strictEqual(r.status, 0);
+  return r.stdout;
+}
+
+test('corrections fire (Chinese and English)', () => {
+  for (const p of ['我們原本有bifrost', '不是這樣', '錯了，應該是用 lessons.js', '為什麼又壞了', '你還是沒修好',
+    'no, use the other one', "that's wrong", 'we already have a helper for this', 'I told you to use temp dirs', 'still not working']) {
+    assert.ok(isCorrection(p), p);
+  }
+});
+
+test('neutral requests, slash commands and long pasted output do not fire', () => {
+  for (const p of ['發版', '然後確認一下還有沒有report', '做 kenaz launch --provider deepseek', 'please add a test',
+    '/review 不對', 'x'.repeat(1600) + ' 不是這樣', '<system-reminder>不對</system-reminder>']) {
+    assert.ok(!isCorrection(p), p);
+  }
+});
+
+test('emits one line with the right command per layout', () => {
+  const dir = tmpProject();
+  const out = run(dir, '不是這樣');
+  assert.strictEqual(out.trim().split('\n').length, 1);
+  assert.match(out, /kenaz learn add/);
+  const core = tmpProject();
+  fs.mkdirSync(path.join(core, '.specialist', 'tools'), { recursive: true });
+  fs.writeFileSync(path.join(core, '.specialist', 'tools', 'lessons.js'), '');
+  assert.match(run(core, '不是這樣'), /node \.specialist\/tools\/lessons\.js add/);
+});
+
+test('second correction in the same session within 10 minutes is silent; other session fires', () => {
+  const dir = tmpProject();
+  assert.ok(run(dir, '不是這樣', 'a'));
+  assert.strictEqual(run(dir, '錯了', 'a'), '');
+  assert.ok(run(dir, '錯了', 'b'));
+});
+
+test('mode off and assist are silent; neutral prompt is silent', () => {
+  assert.strictEqual(run(tmpProject('off'), '不是這樣'), '');
+  assert.strictEqual(run(tmpProject('assist'), '不是這樣'), '');
+  assert.strictEqual(run(tmpProject(), '不是這樣', 's', { KENAZ_MODE: 'off' }), '');
+  assert.strictEqual(run(tmpProject(), '發版'), '');
+});
+
+test('runner default list includes the hook', () => {
+  assert.ok(require('../_run-user-prompt').DEFAULT_HOOKS.includes('correction-detect.js'));
+});

package/core/.claude/hooks/_run-user-prompt.js

@@ -37,6 +37,8 @@ const DEFAULT_HOOKS = [
   // TASK_2218: ansuz-session-pin.js is called from turn-context.js (every install layout runs that hook).
   'turn-context.js',
   'task-bridge.js',
+  // TASK_2426: nudges Ansuz to record a lesson when the user corrects it.
+  'correction-detect.js',
 ];
 
 const HARD_CAP_MS = 10000;

package/core/.claude/hooks/_run-user-prompt.test.js

@@ -69,11 +69,11 @@ test('runner replays stdin, traps exits, concatenates stdout, exits 0', () => {
   assert.ok(elapsed < 5000, 'runner drained promptly, took ' + elapsed + ' ms');
 });
 
-test('default list is the three UserPromptSubmit hooks in settings order', () => {
+test('default list is the UserPromptSubmit hooks in settings order', () => {
   // TASK_2218: the pin writer is invoked from turn-context.js, not listed here.
   const { DEFAULT_HOOKS } = require(RUNNER);
   assert.deepStrictEqual(DEFAULT_HOOKS, [
-    'daemon-outbox-hook.js', 'turn-context.js', 'task-bridge.js',
+    'daemon-outbox-hook.js', 'turn-context.js', 'task-bridge.js', 'correction-detect.js',
   ]);
   for (const f of DEFAULT_HOOKS) assert.ok(fs.existsSync(path.join(__dirname, f)), f + ' exists');
 });

package/core/.claude/hooks/correction-detect.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * correction-detect.js — UserPromptSubmit (TASK_2426)
+ * RULES.md says Ansuz records a lesson when the user corrects it; in practice it never did.
+ * A deterministic pattern match on the user's prompt turns a correction into a one-line
+ * nudge. Silent on any error, mode off/assist, slash commands, pasted output, and when the
+ * session was already nudged in the last 10 minutes.
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const MAX_PROMPT_CHARS = 1500;
+const RATE_LIMIT_MS = 10 * 60 * 1000;
+
+// Exported, case-insensitive. Kept narrow on purpose (eval target: <= 10% of prompts).
+const CORRECTION_PATTERNS = [
+  /不是這樣|不是這個|不是這麼|不是這種|^\s*不是[,，。 ]|不對|不正確|錯了|搞錯|弄錯|理解錯/,
+  /我們原本有|我們本來有|原本就有|之前說過|我說過|跟你說過|不是說過|早就說過/,
+  /還是沒|還是不(行|對|能)|仍然沒|又(壞|錯|失敗|出錯|沒|忘|漏|搞)|為什麼又|怎麼又|為何又/,
+  /(?<!要)不要再|別再|應該是[^嗎吧呢？?]{1,40}(才對|而不是)|應該要.{1,30}而不是/,
+  /^\s*no[,.!]\s|\bthat'?s (wrong|not (right|correct|what))|\bthat is (wrong|not (right|correct|what))/i,
+  /\bwe already (have|had|did)\b|\bi (already )?(told|said)\b|\bi just (told|said)\b|\bdon'?t do that again\b/i,
+  /\bwhy (did|do|are) you .{1,40}\bagain\b|\byou (did|made|broke|forgot).{1,40}\bagain\b|\bstill (not|broken|fails?|failing|wrong|doesn'?t)\b/i,
+  /\bnot what i (asked|meant|wanted)\b|\b(use|do) .{1,40} instead of\b|\bshould (be|have been) .{1,40}\bnot\b/i,
+];
+
+function isCorrection(prompt) {
+  if (typeof prompt !== 'string') return false;
+  const p = prompt.trim();
+  if (!p || p.length > MAX_PROMPT_CHARS) return false;
+  if (p.startsWith('/')) return false;
+  if (/^\s*<(system-reminder|command-name|local-command|task-notification)|^\[(Turn Context|[A-Z_]+_CONTEXT)|^## (Role|Formation)\b/.test(p)) return false;
+  return CORRECTION_PATTERNS.some((re) => re.test(p));
+}
+
+function readYamlMode(file) {
+  try {
+    const m = fs.readFileSync(file, 'utf8').match(/^\s*mode:\s*['"]?(\w+)['"]?\s*(#.*)?$/m);
+    return m ? m[1].toLowerCase() : null;
+  } catch (_) { return null; }
+}
+
+// Same precedence as plugins/kenaz/hooks/mode.js (not importable: the plugin is not in every layout).
+function resolveMode(dir) {
+  const ok = (m) => (m === 'off' || m === 'assist' || m === 'full' ? m : null);
+  return ok((process.env.KENAZ_MODE || '').toLowerCase())
+    || ok(readYamlMode(path.join(dir, '.kenaz', 'kenaz.yaml')))
+    || ok(readYamlMode(path.join(process.env.USERPROFILE || os.homedir(), '.kenaz', 'kenaz.yaml')))
+    || 'full';
+}
+
+function nudgeLine(dir) {
+  const core = fs.existsSync(path.join(dir, '.specialist', 'tools', 'lessons.js'));
+  // Same argument form both CLIs accept (--scope is required; project = this repo's pitfalls/checks, user = preferences).
+  const args = ' add --scope project|user --type check|fact|pref --text "<one-line lesson>" --source correction-nudge';
+  const cmd = (core ? 'node .specialist/tools/lessons.js' : 'kenaz learn') + args;
+  return '[NUDGE_CONTEXT: Background system signal, not user input.] This prompt looks like a correction: if it reveals a reusable lesson, record it with `' + cmd + '` (a repeat counts as a recurrence automatically); if it is a one-off, ignore this.';
+}
+
+/** True (and records the time) when this session has not been nudged within the window. */
+function takeNudgeSlot(dir, sessionId, now) {
+  const file = path.join(dir, '.kenaz', 'specialist', 'correction-nudge.json');
+  let state = {};
+  try { state = JSON.parse(fs.readFileSync(file, 'utf8')) || {}; } catch (_) { /* first run */ }
+  const key = String(sessionId || 'unknown');
+  if (now - (Number(state[key]) || 0) < RATE_LIMIT_MS) return false;
+  state[key] = now;
+  for (const k of Object.keys(state)) if (now - Number(state[k]) > 24 * 3600 * 1000) delete state[k];
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(state));
+  return true;
+}
+
+/** One line per nudge for `kenaz stats` (conversion rate). Time and session only, never the prompt text. */
+function logNudge(dir, sessionId, now) {
+  const file = path.join(dir, '.kenaz', 'specialist', 'correction-nudges.jsonl');
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, JSON.stringify({ ts: new Date(now).toISOString(), session_id: sessionId || null }) + '\n');
+}
+
+function main() {
+  try {
+    const raw = fs.readFileSync(0, 'utf8').trim();
+    const payload = raw ? JSON.parse(raw) : {};
+    if (!isCorrection(payload.prompt)) return;
+    const dir = require('./_project-guard').findProjectRoot(process.env.CLAUDE_PROJECT_DIR || process.cwd());
+    if (!dir || resolveMode(dir) !== 'full') return;
+    const now = Date.now();
+    if (!takeNudgeSlot(dir, payload.session_id, now)) return;
+    try { logNudge(dir, payload.session_id, now); } catch (_) { /* the nudge matters more than its log */ }
+    process.stdout.write(nudgeLine(dir) + '\n');
+  } catch (_) { /* silent */ }
+}
+
+module.exports = { CORRECTION_PATTERNS, isCorrection, resolveMode, nudgeLine, takeNudgeSlot, main };
+
+if (require.main === module || require.main === undefined) main();

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

@@ -0,0 +1,162 @@
+#!/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');
+
+// First = default. From GET https://api.deepseek.com/models on 2026-10-11 (V4 ids, 1M context); the V3 ids still
+// answer but are no longer listed. `kenaz launch` re-reads the context window from that endpoint at start.
+const DEEPSEEK_MODELS = ['deepseek-v4-pro', 'deepseek-flash', 'deepseek-chat', 'deepseek-reasoner'];
+const DEEPSEEK_BASE_URL = 'https://api.deepseek.com/anthropic';
+const DEEPSEEK_CONTEXT_TOKENS = { 'deepseek-v4-pro': 1048576, 'deepseek-flash': 1048576, 'deepseek-chat': 128000, 'deepseek-reasoner': 128000 };
+const DEEPSEEK_FAST = 'deepseek-flash'; // Claude Code's small/fast slot (titles, summaries): the cheap model
+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, contextTokens) {
+  return {
+    ANTHROPIC_BASE_URL: DEEPSEEK_BASE_URL, ANTHROPIC_AUTH_TOKEN: key, ANTHROPIC_MODEL: id, ANTHROPIC_SMALL_FAST_MODEL: DEEPSEEK_FAST,
+    ANTHROPIC_DEFAULT_HAIKU_MODEL: DEEPSEEK_FAST, 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: tell it the real one (V4 = 1M; a 128k
+    // value here made a V4 session compact right after the Ansuz boot).
+    CLAUDE_CODE_MAX_CONTEXT_TOKENS: String(contextTokens || DEEPSEEK_CONTEXT_TOKENS[id] || 128000),
+  };
+}
+
+/** {id: context_window} from GET /models (the live list); null on any failure (callers fall back to the table). */
+async function deepseekModels(key, fetchFn = globalThis.fetch, timeoutMs = 3000) {
+  try {
+    const r = await fetchFn('https://api.deepseek.com/models', { headers: { Authorization: 'Bearer ' + key }, signal: AbortSignal.timeout(timeoutMs) });
+    const j = await r.json();
+    const out = {};
+    for (const m of (j && j.data) || []) if (m && m.id) out[m.id] = Number(m.context_window) || null;
+    return Object.keys(out).length ? out : null;
+  } catch { return null; }
+}
+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, deepseekModels, DEEPSEEK_UNSET, winQuote, buildChild, run, main, DEEPSEEK_MODELS };

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

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * `kenaz launch --provider deepseek [--model deepseek-v4-pro|deepseek-flash|...] [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, deepseekModels, DEEPSEEK_UNSET, DEEPSEEK_MODELS, winQuote } = require('./exec');
+
+const PROVIDERS = {
+  deepseek: {
+    models: DEEPSEEK_MODELS, key: deepseekKey, env: deepseekEnv, live: deepseekModels, 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...]';
+
+function parse(argv) {
+  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;
+  }
+  return { rest, provider, model };
+}
+
+/** Child process plan: { bin, args, env }. live = {id: context_window} from the vendor's model list (or null):
+ *  a listed id is valid even if it is newer than the built-in list, and its window drives auto-compact.
+ *  Throws with a user-facing message. */
+function plan(argv, env = process.env, home = os.homedir(), live = null) {
+  const { rest, provider, model } = parse(argv);
+  const p = PROVIDERS[provider];
+  if (!p) throw new Error((provider ? `unknown provider '${provider}'. ` : '') + USAGE);
+  const id = model || p.models[0];
+  const valid = [...new Set([...p.models, ...Object.keys(live || {})])];
+  if (!valid.includes(id)) throw new Error(`unknown ${provider} model '${id}'; valid: ${valid.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, live && live[id]), 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, context: childEnv.CLAUDE_CODE_MAX_CONTEXT_TOKENS };
+}
+
+/** Resolves to the child's exit code. deps: { spawn, env, home, platform } for tests. */
+async function main(argv, out = console.log, deps = {}) {
+  const env = deps.env || process.env, home = deps.home || os.homedir();
+  const p = PROVIDERS[parse(argv).provider];
+  const key = p && p.key(env, home);
+  const live = key ? await (deps.live || p.live)(key) : null;
+  let pl;
+  try { pl = plan(argv, env, home, live); } catch (e) { out(e.message); return 2; }
+  out(`kenaz launch: Claude Code on ${pl.provider} (${pl.model}, context ${pl.context} tokens); 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,75 @@
+// 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), live: async () => null, 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_DEFAULT_SONNET_MODEL', 'ANTHROPIC_DEFAULT_OPUS_MODEL', 'CLAUDE_CODE_SUBAGENT_MODEL']) {
+    assert.strictEqual(e[k], 'deepseek-v4-pro', k);
+  }
+  assert.strictEqual(e.ANTHROPIC_SMALL_FAST_MODEL, 'deepseek-flash'); assert.strictEqual(e.ANTHROPIC_DEFAULT_HAIKU_MODEL, 'deepseek-flash');
+  assert.strictEqual(e.CLAUDE_CODE_MAX_CONTEXT_TOKENS, '1048576', 'V4 window from the built-in table when the live list is unavailable');
+  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), live: async () => null, 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.strictEqual(calls[0].opts.env.CLAUDE_CODE_MAX_CONTEXT_TOKENS, '128000', 'legacy V3 id keeps its 128k window');
+  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-v4-pro, deepseek-flash, deepseek-chat, deepseek-reasoner/],
+  ]) {
+    const calls = [], lines = [];
+    const rc = await main(argv, (l) => lines.push(l), { spawn: fakeSpawn(calls), live: async () => null, 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/);
+});
+
+test('live model list: a newer listed id is accepted and its context window drives auto-compact', async () => {
+  const calls = [], lines = [];
+  const live = async (k) => { assert.strictEqual(k, KEY); return { 'deepseek-v5-preview': 2097152, 'deepseek-v4-pro': 1048576 }; };
+  const rc = await main(['--provider', 'deepseek', '--model', 'deepseek-v5-preview'], (l) => lines.push(l), { spawn: fakeSpawn(calls), live, env: { DEEPSEEK_API_KEY: KEY }, home: home(), platform: 'linux' });
+  assert.strictEqual(rc, 0);
+  assert.strictEqual(calls[0].opts.env.ANTHROPIC_MODEL, 'deepseek-v5-preview');
+  assert.strictEqual(calls[0].opts.env.CLAUDE_CODE_MAX_CONTEXT_TOKENS, '2097152');
+  assert.match(lines[0], /context 2097152 tokens/);
+});

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');