kenaz 0.3.11 → 0.3.13

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/.collaboration/core/task-2288-followups.test.js

@@ -9,11 +9,10 @@ const { spawnSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const cp = require('child_process');
 
 const TASKAPI = path.join(__dirname, 'task-api.js');
 const TASKJSON = path.join(__dirname, 'task-api-json.js');
-const { TaskAPI, toYAML } = require('./task-api.js');
+const { toYAML } = require('./task-api.js');
 
 const SB = fs.mkdtempSync(path.join(os.tmpdir(), 't2288_'));
 const tasksDir = path.join(SB, '.kenaz', 'tasks');
@@ -37,20 +36,6 @@ const field = (id, k) => (findCard(id).text.match(new RegExp('^' + k + ':\\s*(.*
 const mkActive = (id) => fs.writeFileSync(path.join(tasksDir, 'active', id + '_t.yaml'),
   toYAML({ id, title: 't2288 ' + id, priority: 'P2', status: 'in_progress' }));
 
-// --- spawn counting seam (same as TASK_2264) ---
-let phases = [];
-const realSpawn = cp.spawn;
-cp.spawn = function (cmd, argv, opts) {
-  const script = Array.isArray(argv) ? argv.find(a => typeof a === 'string' && a.includes('const CFG')) : null;
-  if (script) {
-    const m = script.match(/"phase":"(before|after)"/);
-    phases.push(m ? m[1] : '?');
-    return { unref() {}, on() {} };
-  }
-  return realSpawn.apply(this, arguments);
-};
-const afters = () => phases.filter(p => p === 'after').length;
-
 (async () => {
   try {
     // ---- (1) actual-hours validation (CLI, subprocess so spawn patch is irrelevant) ----
@@ -90,30 +75,10 @@ const afters = () => phases.filter(p => p === 'after').length;
       check('Z3 task-api-json emits estimated_hours 0 as 0', p2 && p2.estimated_hours === 0, JSON.stringify(p2 && p2.estimated_hours) + j2.stderr);
       check('Z4 task-api-json emits actual_hours 0 as 0', p2 && p2.actual_hours === 0, JSON.stringify(p2 && p2.actual_hours));
     }
-
-    // ---- (3) single 'after' capture ----
-    const api = new TaskAPI({ tasksDir, projectPath: SB });
-    for (const envName of ['FORMATION_HEADLESS', 'FORMATION_SCHEDULER']) {
-      const id = envName === 'FORMATION_HEADLESS' ? 'TASK_9111' : 'TASK_9112';
-      mkActive(id); phases = [];
-      process.env[envName] = '1';
-      try { await api.completeTask(id, {}); } finally { delete process.env[envName]; }
-      check(`R1 ${envName}: caller's post-complete owns 'after'; moveTask schedules none`, afters() === 0, JSON.stringify(phases));
-    }
-    mkActive('TASK_9113'); phases = [];
-    process.env.FORMATION_HEADLESS = '1';
-    try { await api.completeTask('TASK_9113', { skipPostComplete: true }); } finally { delete process.env.FORMATION_HEADLESS; }
-    check('R2 control: headless + skipPostComplete (nobody else measures) keeps exactly 1 capture', afters() === 1, JSON.stringify(phases));
-    mkActive('TASK_9114'); phases = [];
-    await api.moveTask('TASK_9114', 'done');
-    check('R3 control: bare move done captures exactly once', afters() === 1, JSON.stringify(phases));
-    mkActive('TASK_9115'); phases = [];
-    await api.completeTask('TASK_9115', { dryRun: true, skipGit: true, skipArchive: true });
-    check('R4 control: in-process complete (TASK_2264) still schedules none', afters() === 0, JSON.stringify(phases));
+    // (3) the single 'after' memory-health capture checks were removed with the capture itself (TASK_2411)
   } catch (e) {
     check('no exception', false, e && e.stack);
   } finally {
-    cp.spawn = realSpawn;
     try { fs.rmSync(SB, { recursive: true, force: true }); } catch { /* best effort */ }
   }
   console.log(`\n${pass} passed, ${fail} failed`);

package/core/.collaboration/core/task-2421-replica.test.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+/**
+ * TASK_2421 -- shared-room card replicas, unknown-id lookup, import, alias,
+ * local_fallback warning. Uses a local stub relay (never the real relay) and
+ * temp project dirs. YGGDRASIL_PUBLISHABLE_KEY is set so ~/.kenaz is never read.
+ */
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const http = require('http');
+const { execFile } = require('child_process');
+const { TaskAPI } = require('./task-api.js');
+
+process.env.YGGDRASIL_PUBLISHABLE_KEY = 'test-key';
+const CLI = path.join(__dirname, 'task-api.js');
+
+function startRelay({ failAllocate = false } = {}) {
+  const state = { rows: new Map(), nextId: 9000, posts: [], patches: [], authSeen: [] };
+  const server = http.createServer((req, res) => {
+    let body = '';
+    req.on('data', (c) => { body += c; });
+    req.on('end', () => {
+      state.authSeen.push(req.headers.authorization);
+      const url = new URL(req.url, 'http://x');
+      const json = (code, obj) => { res.writeHead(code, { 'Content-Type': 'application/json' }); res.end(JSON.stringify(obj)); };
+      if (req.method === 'POST' && url.pathname === '/api/tasks/allocate-ids') {
+        if (failAllocate) return json(500, { error: 'down' });
+        const start = state.nextId; state.nextId += 20;
+        return json(200, { start, end: start + 19 });
+      }
+      if (req.method === 'POST' && url.pathname === '/api/tasks') {
+        const b = JSON.parse(body); state.posts.push(b);
+        state.rows.set(b.task_id, { ...b, claimed_by: null, assigned_to: b.assigned_to || null });
+        return json(200, state.rows.get(b.task_id));
+      }
+      if (req.method === 'PATCH' && url.pathname.startsWith('/api/tasks/')) {
+        const id = decodeURIComponent(url.pathname.split('/').pop());
+        const b = JSON.parse(body); state.patches.push({ id, ...b });
+        const row = state.rows.get(id);
+        if (!row) return json(409, { error: 'conflict' });
+        for (const k of ['status', 'title', 'description', 'priority', 'full_yaml']) if (b[k] != null) row[k] = b[k];
+        return json(200, row);
+      }
+      if (req.method === 'GET' && url.pathname === '/api/tasks') {
+        const wanted = (url.searchParams.get('status') || 'pool').split(',');
+        return json(200, [...state.rows.values()].filter(r => wanted.includes(r.status)));
+      }
+      json(404, {});
+    });
+  });
+  return new Promise((resolve) => server.listen(0, '127.0.0.1', () => {
+    resolve({ state, server, url: `ws://127.0.0.1:${server.address().port}` });
+  }));
+}
+
+function mkProject(yamlText) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'task2421-'));
+  fs.mkdirSync(path.join(root, '.kenaz', 'tasks'), { recursive: true });
+  if (yamlText) fs.writeFileSync(path.join(root, '.kenaz', 'yggdrasil.yaml'), yamlText);
+  return { root, api: new TaskAPI({ projectPath: root, tasksDir: path.join(root, '.kenaz', 'tasks') }) };
+}
+
+const cfg = (url, extra = '') => `enabled: true\nrelay_url: "${url}"\nyggdrasil_project: room\nnode_name: node-A\n${extra}`;
+const card = (extra = {}) => ({ title: 'Replica me', description: 'desc', priority: 'P1', requirements: ['r1'], acceptance_criteria: ['a1'], force: true, ...extra });
+
+function cli(root, args) {
+  return new Promise((resolve) => {
+    execFile(process.execPath, [CLI, '--project-path', root, ...args], { env: process.env, timeout: 30000 },
+      (err, stdout, stderr) => resolve({ code: err ? (err.code || 1) : 0, stdout, stderr }));
+  });
+}
+
+const tests = [];
+const test = (n, f) => tests.push([n, f]);
+
+test('shared room: create publishes a non-pool read-only replica', async () => {
+  const relay = await startRelay();
+  const { api } = mkProject(cfg(relay.url));
+  const t = await api.createTask(card({ alias: '791-17' }));
+  assert.strictEqual(relay.state.posts.length, 1);
+  const p = relay.state.posts[0];
+  assert.strictEqual(p.task_id, t.id);
+  assert.strictEqual(p.status, 'assigned', 'must not be claimable pool work');
+  assert.ok(!p.assigned_to, 'no assigned_to so creator inbox (pool_pull) stays clean');
+  assert.strictEqual(p.created_by, 'node-A');
+  assert.ok(/replica: true/.test(p.full_yaml) && /791-17/.test(p.full_yaml) && /origin_node: node-A/.test(p.full_yaml));
+  assert.ok(relay.state.authSeen.every(a => a === 'Bearer test-key'));
+  assert.strictEqual(t.replica_published, true);
+  relay.server.close();
+});
+
+test('opted out (share_cards: false) -> no replica; ids still from relay', async () => {
+  const relay = await startRelay();
+  const { api } = mkProject(cfg(relay.url, 'share_cards: false\n'));
+  const t = await api.createTask(card());
+  assert.strictEqual(relay.state.posts.length, 0);
+  assert.ok(/^TASK_9\d{3}$/.test(t.id));
+  relay.server.close();
+});
+
+test('not a shared room (no yggdrasil config) -> no relay traffic', async () => {
+  const relay = await startRelay();
+  const { api } = mkProject(null);
+  await api.createTask(card());
+  assert.strictEqual(relay.state.posts.length, 0);
+  relay.server.close();
+});
+
+test('relay down: local create still succeeds with one replica warning', async () => {
+  const relay = await startRelay();
+  const { api } = mkProject(cfg(relay.url));
+  const first = await api.createTask(card()); // gets a lease while relay is up
+  await new Promise(r => relay.server.close(r));
+  const warns = [];
+  const orig = console.warn; console.warn = (...a) => warns.push(a.join(' '));
+  let t;
+  try { t = await api.createTask(card({ title: 'Second' })); } finally { console.warn = orig; }
+  assert.ok(t && t.id && t.id !== first.id);
+  assert.ok(fs.existsSync(t._file_path), 'local card written');
+  assert.strictEqual(t.replica_published, false);
+  assert.strictEqual(warns.filter(w => /replica not published/.test(w)).length, 1);
+});
+
+test('local_fallback in a shared room warns loudly (stderr + create output)', async () => {
+  const { api, root } = mkProject(cfg('ws://127.0.0.1:1')); // unreachable relay, no lease
+  const r = await cli(root, ['create', '--title', 'Fallback', '--force']);
+  assert.strictEqual(r.code, 0, r.stderr);
+  assert.ok(/ID COLLISION RISK/.test(r.stderr), 'stderr warning');
+  assert.ok(/⚠️.*locally because the relay is unreachable/.test(r.stdout), 'create output warning');
+  assert.ok(api);
+});
+
+test('solo project local id allocation prints no collision warning', async () => {
+  const { root } = mkProject(null);
+  const r = await cli(root, ['create', '--title', 'Solo', '--force']);
+  assert.strictEqual(r.code, 0, r.stderr);
+  assert.ok(!/COLLISION/.test(r.stderr + r.stdout));
+});
+
+test('get unknown id shows replica with owner node; mutations explain, create no local file', async () => {
+  const relay = await startRelay();
+  const a = mkProject(cfg(relay.url));
+  const t = await a.api.createTask(card());
+  // node B: same room, empty local store
+  const b = mkProject(cfg(relay.url).replace('node-A', 'node-B'));
+  const g = await cli(b.root, ['get', t.id]);
+  assert.strictEqual(g.code, 0, g.stderr);
+  const out = JSON.parse(g.stdout);
+  assert.strictEqual(out.read_only_replica, true);
+  assert.strictEqual(out.title, 'Replica me');
+  assert.ok(/read-only replica; card lives on node node-A/.test(out.replica_notice));
+  assert.ok(/task-api\.js pull /.test(out.replica_notice));
+  for (const args of [['move', t.id, 'active'], ['update', t.id, '--title', 'x'], ['complete', t.id]]) {
+    const r = await cli(b.root, args);
+    assert.notStrictEqual(r.code, 0, args.join(' '));
+    assert.ok(/read-only replica; card lives on node node-A/.test(r.stderr + r.stdout), args.join(' ') + ': ' + r.stderr);
+  }
+  const files = fs.readdirSync(path.join(b.root, '.kenaz', 'tasks'), { recursive: true }).filter(f => /TASK_/.test(String(f)));
+  assert.strictEqual(files.length, 0, 'no broken local file: ' + files.join(','));
+  // truly unknown id still says not found
+  const miss = await cli(b.root, ['get', 'TASK_424242']);
+  assert.notStrictEqual(miss.code, 0);
+  assert.ok(/任務不存在/.test(miss.stderr));
+  relay.server.close();
+});
+
+test('status changes on the owner keep the replica current', async () => {
+  const relay = await startRelay();
+  const { api } = mkProject(cfg(relay.url));
+  const t = await api.createTask(card());
+  await api.moveTask(t.id, 'active');
+  assert.strictEqual(relay.state.rows.get(t.id).status, 'in_progress');
+  await api.updateTask(t.id, { title: 'Renamed' });
+  assert.strictEqual(relay.state.rows.get(t.id).title, 'Renamed');
+  relay.server.close();
+});
+
+test('pull imports a local copy marked with origin node', async () => {
+  const relay = await startRelay();
+  const a = mkProject(cfg(relay.url));
+  const t = await a.api.createTask(card({ alias: '791-18' }));
+  const b = mkProject(cfg(relay.url).replace('node-A', 'node-B'));
+  const r = await cli(b.root, ['pull', t.id]);
+  assert.strictEqual(r.code, 0, r.stderr);
+  const local = await b.api.getTask(t.id);
+  assert.ok(local, 'local copy exists');
+  assert.strictEqual(local.origin_node, 'node-A');
+  assert.strictEqual(local.title, 'Replica me');
+  assert.strictEqual(local.alias, '791-18');
+  const again = await cli(b.root, ['pull', t.id]);
+  assert.notStrictEqual(again.code, 0);
+  relay.server.close();
+});
+
+test('alias: create/update/get/search resolve to the TASK id', async () => {
+  const { api, root } = mkProject(null);
+  const t = await api.createTask(card({ alias: '791-17' }));
+  const g = await cli(root, ['get', '791-17']);
+  assert.strictEqual(g.code, 0, g.stderr);
+  assert.strictEqual(JSON.parse(g.stdout).id, t.id);
+  const s = await cli(root, ['search', '791-17']);
+  assert.ok(s.stdout.includes(t.id));
+  const u = await cli(root, ['update', t.id, '--alias', '791-99']);
+  assert.strictEqual(u.code, 0, u.stderr);
+  const g2 = await cli(root, ['get', '791-99']);
+  assert.strictEqual(JSON.parse(g2.stdout).id, t.id);
+});
+
+test('get by alias of a replica that exists only on the relay', async () => {
+  const relay = await startRelay();
+  const a = mkProject(cfg(relay.url));
+  const t = await a.api.createTask(card({ alias: '791-20' }));
+  const b = mkProject(cfg(relay.url).replace('node-A', 'node-B'));
+  const g = await cli(b.root, ['get', '791-20']);
+  assert.strictEqual(g.code, 0, g.stderr);
+  assert.strictEqual(JSON.parse(g.stdout).id, t.id);
+  relay.server.close();
+});
+
+(async () => {
+  let failed = 0;
+  for (const [name, fn] of tests) {
+    try { await fn(); console.log(`  ok   ${name}`); }
+    catch (e) { failed++; console.log(`  FAIL ${name}\n       ${e && e.stack || e}`); }
+  }
+  console.log(`\n${tests.length - failed}/${tests.length} passed`);
+  process.exit(failed ? 1 : 0);
+})();