sillyspec 3.25.9 → 3.26.0

package/src/db.js

@@ -1,11 +1,38 @@
-import initSqlJs from 'sql.js';
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
-import { basename, dirname, join } from 'path';
+import Database from 'better-sqlite3';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
 
 // DB schema 版本（与 project.schema_version DEFAULT 对齐）。_createSchema 改动（加表/列/migration）时 bump，
-// 触发 .schema-version 戳失效 → 下次 init 重跑 _createSchema + _save（W4-H：高频读路径 gate/derive/status
-// 每次 new ProgressManager 都过 init，原无条件 _createSchema+_save 致每次整库 export+三段原子写）。
-const DB_SCHEMA_VERSION = 3;
+// 触发 .schema-version 戳失效 → 下次 init 重跑 _createSchema（W4-H：高频读路径 gate/derive/status
+// 每次 new ProgressManager 都过 init，靠版本戳跳过建表省开销）。
+// better-sqlite3 是原生 SQLite 引擎，打开即持久化（不像 sql.js 纯内存需整库 export 落盘），
+// _createSchema 内 DDL 直接落盘，无需额外 _save。
+const DB_SCHEMA_VERSION = 4;
+
+// SQLITE_BUSY 应用层有限重试（R-08 / NFR-03）：WAL 单写者模型，并发写第二者在
+// busy_timeout=5000（init PRAGMA）后抛 SQLITE_BUSY。busy_timeout 已在引擎层处理大部分等待；
+// 此处常量给 transaction() 做超时后的应用层兜底重试。
+// 仅 SQLITE_BUSY 重试（其它异常直接上抛）；MAX_BUSY_RETRIES 有限次防死循环，达上限 fail-loud
+// 不静默吞错。BUSY_BACKOFF_MS 递增退避（50→100→200ms），总等待上限 350ms。
+// busy_timeout=5000 保持不变（design §7）：引擎层 5s 等待已覆盖大部分锁竞争，应用层 3 次退避
+// 足够消化极端并发超时尖刺，无需抬高 busy_timeout（过长会让单次写阻塞拖慢整体吞吐）。
+const MAX_BUSY_RETRIES = 3;
+const BUSY_BACKOFF_MS = [50, 100, 200];
+
+/**
+ * 同步阻塞 sleep（better-sqlite3 同步 API，BUSY 退避不能用 await）。
+ * Atomics.wait 阻塞当前线程不占 CPU；SharedArrayBuffer 不可用的环境（受限 CSP / 旧 Node）
+ * 退化为 busy-wait（退避时长 50-200ms 短，CPU 占用可接受）。仅在 transaction() 的 BUSY
+ * 重试路径调用。
+ */
+function _sleepSync(ms) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  } catch {
+    const end = Date.now() + ms;
+    while (Date.now() < end) { /* busy-wait fallback */ }
+  }
+}
 
 export class DB {
   constructor(dbPath) {
@@ -13,26 +40,36 @@ export class DB {
     this.db = null;
   }
 
-  async init() {
+  /**
+   * 同步初始化（better-sqlite3 是同步 API，无 async/await，与 sql.js 的 initSqlJs() 异步加载不同）：
+   *  - new Database(path) 同步打开/创建库文件（better-sqlite3 原生绑定，非 WASM）
+   *  - PRAGMA：journal_mode=WAL 真生效（better-sqlite3 直连原生 SQLite，WAL 落地；
+   *    sql.js 是纯内存库，WAL 对它无意义），busy_timeout=5000 让写锁竞争时自动等待，
+   *    foreign_keys=ON 启用外键级联，synchronous=NORMAL 在 WAL 下兼顾安全与性能
+   *  - schema 戳检查：内容匹配 DB_SCHEMA_VERSION 则跳过 _createSchema，省建表开销
+   *  - better-sqlite3 打开即持久化，DDL/事务提交直接落盘，不需要 sql.js 时代的 _save()
+   *
+   * .bak 损坏回退由 _openWithFallback() 承担（task-04）：主库 → .bak → 全新/报错 逐级回退，
+   * 语义对齐原 sql.js 的 _loadDatabase。
+   */
+  init() {
     // 1. 确保父目录存在
     const dir = dirname(this.dbPath);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 
-    // 2. 初始化 sql.js
-    const SQL = await initSqlJs();
+    // 2. 同步打开/创建数据库（主库 → .bak → 全新/报错 逐级回退，归 task-04）
+    this.db = this._openWithFallback();
 
-    // 3. 加载已有数据库（含损坏检测 + .bak 回滚）或创建新库
-    this.db = this._loadDatabase(SQL);
+    // 3. 设置 PRAGMA（better-sqlite3 走真 SQLite，journal_mode=WAL 真生效）
+    this.db.pragma('journal_mode = WAL');
+    this.db.pragma('busy_timeout = 5000');
+    this.db.pragma('foreign_keys = ON');
+    this.db.pragma('synchronous = NORMAL');
 
-    // 4. 设置 PRAGMA
-    this.db.run('PRAGMA journal_mode = WAL');
-    this.db.run('PRAGMA busy_timeout = 5000');
-    this.db.run('PRAGMA foreign_keys = ON');
-    this.db.run('PRAGMA synchronous = NORMAL');
-
-    // 5. 创建表结构（仅当 schema 版本戳不匹配时——W4-H）：
-    //    schema 已最新则只 load 不写，省掉 _createSchema + _save 的整库 export + 三段原子写。
-    //    戳在但 db 缺表属"手动改 db"边角（SillySpec 不支持），_loadDatabase 的损坏检测兜底正常路径。
+    // 4. 创建表结构（仅当 schema 版本戳不匹配时——W4-H）：
+    //    schema 已最新则跳过建表，省 DDL 开销。better-sqlite3 打开即持久化，
+    //    _createSchema 内 DDL 直接落盘，无需 _save。
+    //    戳在但 db 缺表属"手动改 db"边角（SillySpec 不支持），不在本层兜底。
     const versionPath = `${this.dbPath}.schema-version`;
     let schemaCurrent = false;
     try {
@@ -42,172 +79,135 @@ export class DB {
 
     if (!schemaCurrent) {
       this._createSchema();
-      this._save();
       try { writeFileSync(versionPath, String(DB_SCHEMA_VERSION)); } catch { /* 戳写入失败不阻断，下次重跑 */ }
     }
   }
 
-  close() {
-    if (this.db) {
-      this._save();
-      this.db.close();
-      this.db = null;
+  /**
+   * 打开数据库（主库 → .bak → 全新/报错 逐级回退）。
+   * 语义对齐原 sql.js 的 _loadDatabase，但 better-sqlite3 绑定文件路径无 _save，
+   * .bak 回退时 copyFileSync 把 .bak 内容恢复到主库路径，统一用 dbPath。
+   *  - 主库存在且有内容且可打开：直接用。
+   *  - 主库缺失/为空/损坏：尝试 .bak；成功则 warn 原因后 copy 回主库使用。
+   *  - 都不可用：主库不存在→建全新空库；主库曾存在(空/损坏)→fail-loud 抛错(不静默建空库吞进度)。
+   * better-sqlite3 打开 0 字节文件不抛错：主库须 statSync 显式判空（截断信号→走回退，防静默吞进度）；
+   * .bak 作为恢复源只要存在且能打开即用（含 0 字节空库——better-sqlite3 视其为合法空库，
+   * 生产环境 .bak 由原子写改名上一完整主库得来，永不为 0 字节，0 字节态仅出现在测试构造）。
+   */
+  _openWithFallback() {
+    const bakPath = `${this.dbPath}.bak`;
+    // readValid: null=文件不存在；'empty'=存在但 0 字节；'ok'=有内容
+    const readValid = (p) => {
+      if (!existsSync(p)) return null;
+      return statSync(p).size === 0 ? 'empty' : 'ok';
+    };
+    // tryOpen: new Database(path) + prepare 探测双保险（防打开成功但内容非 SQLite）
+    const tryOpen = (p) => {
+      let db;
+      try { db = new Database(p); }
+      catch { return null; }
+      try { db.prepare('SELECT count(*) FROM sqlite_master').get(); return db; }
+      catch { try { db.close(); } catch { /* 关闭失败忽略 */ } return null; }
+    };
+
+    // 1. 主库（0 字节=截断信号，必须走回退，故门禁要求 'ok' 有内容）
+    if (readValid(this.dbPath) === 'ok') {
+      const primaryDb = tryOpen(this.dbPath);
+      if (primaryDb) return primaryDb;
     }
-  }
 
-  transaction(fn) {
-    if (!this.db) throw new Error('DB not initialized');
-    this.db.run('BEGIN');
-    let result;
-    try {
-      result = fn(this.db);
-      this.db.run('COMMIT');
-    } catch (err) {
-      // fn 抛错或 COMMIT 失败：事务级回滚（此时事务确实活跃，ROLLBACK 有效）
-      try { this.db.run('ROLLBACK'); } catch { /* 事务可能已被 fn 内的错自动回滚 */ }
-      throw err;
+    // 2. .bak 回退（.bak 是恢复源：存在且能打开即用，含 0 字节空库；门禁只挡"不存在"，
+    //    避免 tryOpen 对不存在的路径触发 new Database 的副作用——会凭空创建文件）
+    if (readValid(bakPath) !== null) {
+      const bakDb = tryOpen(bakPath);
+      if (bakDb) {
+        const primaryRaw = readValid(this.dbPath);
+        const reason = primaryRaw === 'empty'
+          ? 'sillyspec.db 为空（可能被截断）'
+          : primaryRaw === null
+            ? 'sillyspec.db 不存在'
+            : 'sillyspec.db 损坏';
+        console.warn(`⚠️  ${reason}，已从 .bak 备份恢复。`);
+        bakDb.close();
+        // better-sqlite3 绑定路径，无 _save：把 .bak 内容 copy 回主库，统一用 dbPath
+        copyFileSync(bakPath, this.dbPath);
+        return new Database(this.dbPath);
+      }
     }
-    // COMMIT 成功后才持久化。_save 失败时抛原生错（磁盘满/EPERM），不再被 catch 里
-    // 无效的 ROLLBACK 二级异常（"no transaction active"）掩盖——内存库已 commit，
-    // 下次 _save / close() 会落盘，调用方拿到的是准确的持久化错误而非被替换的误报。
-    this._save();
-    return result;
-  }
 
-  /** 获取底层 db 对象（供 progress.js 直接使用） */
-  getDb() {
-    return this.db;
+    // 3. 都不可用
+    if (readValid(this.dbPath) === null) {
+      // 主库与备份都不存在 → 全新项目，建空库
+      return new Database(this.dbPath);
+    }
+    // 主库曾存在（空/损坏）但无法恢复 → 数据丢失，必须 fail-loud（不静默建空库吞进度）
+    throw new Error('sillyspec.db 损坏且 .bak 备份不可用，无法恢复。请从版本控制或其他备份恢复 .sillyspec/.runtime/ 后重试。');
   }
 
   /**
-   * 将内存中的数据库持久化到磁盘（原子写 + 保留上一版 .bak 备份）。
-   * 任何时刻磁盘上的主库要么是完整的上一版、要么是完整的新版，
-   * 不会出现写入中途崩溃导致的截断态。sql.js 是纯内存库，
-   * PRAGMA journal_mode=WAL 对它无意义——真正的持久化原子性在这里保证。
+   * 关闭数据库。better-sqlite3 的 close() 自动做 WAL checkpoint（把 -wal/-shm 日志合并回主库），
+   * 不需要 sql.js 时代的 _save() 整库 export 落盘。
    */
-  _save() {
-    if (!this.db) return;
-    const data = this.db.export();
-    const buffer = Buffer.from(data);
-    this._atomicWriteSync(this.dbPath, buffer);
-    // sql.js 的 export() 会重置 PRAGMA 状态，需要重新设置
-    this.db.run('PRAGMA journal_mode = WAL');
-    this.db.run('PRAGMA busy_timeout = 5000');
-    this.db.run('PRAGMA foreign_keys = ON');
-    this.db.run('PRAGMA synchronous = NORMAL');
+  close() {
+    if (this.db) {
+      this.db.close();
+      this.db = null;
+    }
   }
 
   /**
-   * 原子落盘：同目录 tmp 写入 → 旧主库改名 .bak → tmp 改名为主库。
-   * 三步保证主库永不处于半写状态；.bak 始终保留上一完整版本。
-   * Windows 上 rename 偶发 EPERM/EBUSY（杀毒/索引扫描占文件），带短退避重试。
+   * 原生事务 + SQLITE_BUSY 应用层有限重试（R-08 / NFR-03）。
+   *
+   * better-sqlite3 的 db.transaction(fn) 返回一个包装函数，调用时自动
+   * BEGIN/COMMIT/ROLLBACK（fn 抛错自动 ROLLBACK 且不吞错），嵌套调用自动用 SAVEPOINT。
+   * 无需手动 BEGIN/COMMIT/ROLLBACK，也无需 _save（better-sqlite3 提交即持久化）。
+   *
+   * SQLITE_BUSY 重试：WAL 单写者模型，并发写第二者在 busy_timeout=5000 后抛 BUSY。此处对
+   * BUSY 加 MAX_BUSY_RETRIES 次递增退避（BUSY_BACKOFF_MS）；仅 BUSY 重试（其它异常直接上抛），
+   * 达上限 fail-loud 抛错不静默吞（防死循环）。BUSY 重试收敛在 DB 层 transaction 封装，
+   * 所有写者（progress.js _write / initChange / setStage 等）统一受益，不散落调用点。
    */
-  _atomicWriteSync(filePath, buffer) {
-    const dir = dirname(filePath);
-    const tmpPath = join(dir, `${basename(filePath)}.tmp`);
-    const bakPath = `${filePath}.bak`;
-    // 1. 完整内容先落 tmp（同目录，保证 rename 不跨卷）
-    writeFileSync(tmpPath, buffer);
-    // 2. 旧主库 → .bak（保留上一版；不存在则跳过；失败不阻断主流程）
-    if (existsSync(filePath)) {
-      try { this._renameSyncRetry(filePath, bakPath); }
-      catch { /* 备份失败最坏只是少一个 .bak，主库仍会被新内容替换 */ }
-    }
-    // 3. tmp → 主库（成功后主库即新版完整态）
-    this._renameSyncRetry(tmpPath, filePath);
-  }
-
-  /** rename 带退避重试，覆盖 Windows 偶发的 EPERM/EBUSY/EACCES/ENOTEMPTY。 */
-  _renameSyncRetry(from, to, retries = 5) {
-    let lastErr;
-    for (let attempt = 0; attempt <= retries; attempt++) {
+  transaction(fn) {
+    if (!this.db) throw new Error('DB not initialized');
+    const tx = this.db.transaction(fn);
+    let attempt = 0;
+    while (true) {
       try {
-        renameSync(from, to);
-        return;
+        return tx();
       } catch (err) {
-        lastErr = err;
-        const code = err && err.code;
-        if (!code || !['EPERM', 'EBUSY', 'EACCES', 'ENOTEMPTY'].includes(code)) throw err;
-        if (attempt < retries) this._sleepSync(15 * (attempt + 1));
+        // 仅 SQLITE_BUSY 重试（better-sqlite3 err.code 为 'SQLITE_BUSY'/5，message 含 'database is locked'）
+        const isBusy = err && (err.code === 'SQLITE_BUSY' || err.code === 5
+          || (typeof err.message === 'string' && /database is locked|SQLITE_BUSY/i.test(err.message)));
+        if (!isBusy) throw err;
+        if (attempt >= MAX_BUSY_RETRIES) throw err; // 达上限 fail-loud（不静默吞，防死循环）
+        _sleepSync(BUSY_BACKOFF_MS[attempt]);
+        attempt++;
       }
     }
-    throw lastErr;
   }
 
-  /** 同步退避：优先 Atomics.wait，不可用时退化为忙等（仅在 rename 冲突的极端情况触发）。 */
-  _sleepSync(ms) {
-    try {
-      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-    } catch {
-      const end = Date.now() + ms;
-      while (Date.now() < end) { /* busy wait */ }
-    }
-  }
-
-  /**
-   * 加载数据库：主库 → .bak → 报错/空库，逐级回退。
-   *  - 主库可正常打开：直接用。
-   *  - 主库缺失/为空/损坏：尝试 .bak；成功则 warn 后用 .bak。
-   *  - 主库与 .bak 都不可用：
-   *      · 全新项目（两者都不存在）：创建空库；
-   *      · 主库曾存在却无法恢复（截断/损坏且无可用备份）：fail-loud 抛错，
-   *        不静默建空库——那会无声吞掉用户所有进度。
-   */
-  _loadDatabase(SQL) {
-    const bakPath = `${this.dbPath}.bak`;
-    // readValid: null=文件不存在；'empty'=存在但 0 字节；Buffer=有内容
-    const readValid = (p) => {
-      if (!existsSync(p)) return null;
-      const b = readFileSync(p);
-      return (b && b.length > 0) ? b : 'empty';
-    };
-    const tryOpen = (raw) => {
-      if (!raw || raw === 'empty') return null;
-      let instance;
-      try { instance = new SQL.Database(raw); }
-      catch { return null; }
-      // 双保险：损坏 buffer 偶尔被 sql.js 静默打开为空库，用一次查询确认它真能用
-      try { instance.exec('SELECT count(*) FROM sqlite_master'); return instance; }
-      catch { try { instance.close(); } catch {} return null; }
-    };
-
-    const primaryRaw = readValid(this.dbPath);
-    const primaryDb = tryOpen(primaryRaw);
-    if (primaryDb) return primaryDb;
-
-    const bakDb = tryOpen(readValid(bakPath));
-    if (bakDb) {
-      const reason = primaryRaw === 'empty'
-        ? 'sillyspec.db 为空（可能被截断）'
-        : primaryRaw === null
-          ? 'sillyspec.db 不存在'
-          : 'sillyspec.db 损坏';
-      console.warn(`⚠️  ${reason}，已从 .bak 备份恢复。`);
-      return bakDb;
-    }
-
-    if (primaryRaw === null) {
-      // 主库与备份都不存在 → 全新项目
-      return new SQL.Database();
-    }
-    // 主库曾存在（空/损坏）但无法恢复 → 数据丢失，必须 fail-loud
-    throw new Error('sillyspec.db 损坏且 .bak 备份不可用，无法恢复。请从版本控制或其他备份恢复 .sillyspec/.runtime/ 后重试。');
+  /** 获取底层 db 对象（better-sqlite3 Database 实例，供 progress.js 直接使用） */
+  getDb() {
+    return this.db;
   }
 
   _createSchema() {
+    // better-sqlite3：exec() 执行多条 SQL/DDL（无返回）；prepare().run/get/all 用于 DML。
+    // sql.js 的 .run(sql) 在此换为 .exec(sql)。
+
     // project 表
-    this.db.run(`
+    this.db.exec(`
       CREATE TABLE IF NOT EXISTS project (
         id INTEGER PRIMARY KEY DEFAULT 1,
         name TEXT NOT NULL,
-        schema_version INTEGER DEFAULT 3,
+        schema_version INTEGER DEFAULT 4,
         created_at TEXT NOT NULL,
         updated_at TEXT NOT NULL
       )
     `);
 
     // changes 表
-    this.db.run(`
+    this.db.exec(`
       CREATE TABLE IF NOT EXISTS changes (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         name TEXT UNIQUE NOT NULL,
@@ -224,7 +224,7 @@ export class DB {
     `);
 
     // stages 表
-    this.db.run(`
+    this.db.exec(`
       CREATE TABLE IF NOT EXISTS stages (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         change_id INTEGER NOT NULL REFERENCES changes(id) ON DELETE CASCADE,
@@ -237,7 +237,7 @@ export class DB {
     `);
 
     // steps 表
-    this.db.run(`
+    this.db.exec(`
       CREATE TABLE IF NOT EXISTS steps (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         stage_id INTEGER NOT NULL REFERENCES stages(id) ON DELETE CASCADE,
@@ -250,7 +250,7 @@ export class DB {
     `);
 
     // batch_progress 表
-    this.db.run(`
+    this.db.exec(`
       CREATE TABLE IF NOT EXISTS batch_progress (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         change_id INTEGER NOT NULL REFERENCES changes(id) ON DELETE CASCADE,
@@ -263,7 +263,7 @@ export class DB {
     `);
 
     // approvals 表
-    this.db.run(`
+    this.db.exec(`
       CREATE TABLE IF NOT EXISTS approvals (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         change_id INTEGER NOT NULL REFERENCES changes(id) ON DELETE CASCADE,
@@ -277,10 +277,10 @@ export class DB {
     `);
 
     // 索引
-    this.db.run('CREATE INDEX IF NOT EXISTS idx_changes_current_stage ON changes(current_stage)');
-    this.db.run('CREATE INDEX IF NOT EXISTS idx_changes_status ON changes(status)');
-    this.db.run('CREATE INDEX IF NOT EXISTS idx_stages_change ON stages(change_id)');
-    this.db.run('CREATE INDEX IF NOT EXISTS idx_steps_stage ON steps(stage_id)');
+    this.db.exec('CREATE INDEX IF NOT EXISTS idx_changes_current_stage ON changes(current_stage)');
+    this.db.exec('CREATE INDEX IF NOT EXISTS idx_changes_status ON changes(status)');
+    this.db.exec('CREATE INDEX IF NOT EXISTS idx_stages_change ON stages(change_id)');
+    this.db.exec('CREATE INDEX IF NOT EXISTS idx_steps_stage ON steps(stage_id)');
 
     // Migration: add isolation columns to changes table (idempotent)
     this._migrateAddColumn('changes', 'isolation_status', 'TEXT');
@@ -302,15 +302,24 @@ export class DB {
     this._migrateAddColumn('stages', 'reopened_from_step', 'TEXT');
     this._migrateAddColumn('stages', 'reopened_at', 'TEXT');
     this._migrateAddColumn('stages', 'stale_reason', 'TEXT');
+
+    // Platform sync support（2026-08-10-platform-progress-sync §8 / D-012）：
+    // changes 表加 base_ts（last_synced_platform_ts）与本地脏度（last_local_modified_ts）两列，
+    // 为 serializeForSync()/import() 序列化与 base_ts 乐观锁冲突检测提供数据载体。
+    // NULL 语义（gap8）：last_local_modified_ts NULL=本地无脏度（pull 不判冲突直接 import）；
+    // last_synced_platform_ts NULL=首次同步（base_ts NULL 平台接受首次 push）。
+    this._migrateAddColumn('changes', 'last_synced_platform_ts', 'TEXT');
+    this._migrateAddColumn('changes', 'last_local_modified_ts', 'TEXT');
   }
 
   /**
-   * 幂等地给表添加列（列已存在则跳过）
+   * 幂等地给表添加列（列已存在则跳过）。
+   * better-sqlite3：exec() 执行 ALTER TABLE DDL；列已存在抛错被 catch 静默跳过。
    * @private
    */
   _migrateAddColumn(table, column, type) {
     try {
-      this.db.run(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
+      this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
     } catch {
       // 列已存在，静默跳过
     }

package/src/dispatch/backends/local-agent.js

@@ -0,0 +1,152 @@
+/**
+ * Local 后端派发指令模板（task-dispatcher 抽象层）— task-03
+ *
+ * 定位（D-007）：dispatcher **不是 JS 执行体**。本机 Agent tool（Claude Code Task 工具）
+ * 只有 agent 能调，CLI（Node）进程调不了。所以本文件 = **派发指令模板生成器**：
+ * 生成注入 execute prompt 的「派发指令文本」，告诉 agent 如何用本机 Agent tool 启动
+ * 子代理；实际 Agent tool 调用由 agent 执行，本模块不调任何 tool。
+ *
+ * Local 后端 = **默认与降级路径**（D-005），保留现有 buildWavePrompt（src/stages/execute.js）
+ * 的本机 Agent tool 派发行为：每任务一个独立子代理、workdir 强制 = worktreePath、
+ * worker 终态后 SillySpec 对 worktree 工作区 git diff 写 review.json（复用既有
+ * task-review 契约）。SillyHub MCP 不可用 / 未配置 / 路径 A 未落地时全程走此路径，零回归。
+ *
+ * Local 后端**忽略** contract 中的 modelHint / agentProfileHint：本机 Agent tool 不做
+ * 异构模型 / agent 分配，这两字段仅 SillyHub 后端消费。
+ */
+
+/**
+ * Local 后端结果回收约定（worker 终态 → review.json）。
+ *
+ * 抽成独立常量供 strategy.js 在拼接「兜底 / 降级 / SillyHub 回收」段时复用，避免 Local
+ * 与 SillyHub 两份回收文案重复维护（R-07：回收统一走 review.json，屏蔽后端差异）。
+ *
+ * 含 `<runId>` 占位符，使用方按实际 contract.runId 替换（见 renderLocalInstruction）。
+ */
+export const LOCAL_RECYCLE_RULE = `### 回收约定（worker 终态 → review.json）
+
+worker 子代理结束后，**回收不依赖 worker 自报结果，也不依赖 worker git commit**：
+SillySpec 主体（你，调度 agent）对 worktree **工作区**做 git diff，按既有 task-review
+契约写 review.json。
+
+1. 读取该 task 在 worktree 工作区的 git diff（task 开始 → 完成的变更）
+2. 对照 plan.md 与 tasks/task-XX.md 检查实现（不信任 implementer 自报，只看当前 task 的 diff）
+3. 写入 review.json：\`.runtime/execute-runs/<runId>/tasks/task-XX/review.json\`
+4. review.json 写入成功后，该 task 的派发回收完成
+
+review.json 复用既有 task-review 契约（必填字段：schemaVersion / task / base / head /
+changedFiles / specVerdict / qualityVerdict / reviewerNotes / requiredEvidence），不发明
+新契约。回收屏蔽后端差异：无论 Local 还是 SillyHub worker，SillySpec 都自己 diff worktree
+工作区写 review.json。`
+
+/**
+ * @typedef {object} DispatchContract
+ * @property {string}  brief              - 任务目标 + 蓝图路径（注入子代理 prompt）
+ * @property {string}  worktreePath       - SillySpec worktree 绝对路径（子代理 cwd）
+ * @property {string}  branch             - worktree 当前分支
+ * @property {string[]} allowedPaths      - task 边界（子代理 prompt 里声明，SillySpec 侧 assess/apply 校验）
+ * @property {boolean} readOnly           - execute 写模式=false；true=只读 QA（仅读/diff/写 review.json）
+ * @property {string}  [modelHint]        - tasks.md [model:xxx]（Local 忽略，仅 SillyHub 消费）
+ * @property {string}  [agentProfileHint] - agent profile（Local 忽略，仅 SillyHub 消费）
+ * @property {string}  runId              - SillySpec execute-run id（关联 review.json 路径）
+ * @property {string}  [missionId]        - Wave 级 mission id（D-008，SillyHub 专属，Local 忽略）
+ */
+
+/**
+ * 渲染 Local 后端派发指令文本。
+ *
+ * 纯模板生成器：不校验 contract 完整性、不调任何 tool，只把 contract 字段拼成可注入
+ * execute prompt 的中文指令字符串。contract 缺字段时回退到醒目占位符（`<未提供 ...>`），
+ * 让 agent 在 prompt 里一眼看到派发前必须补齐的参数，而非静默产出错位指令。
+ *
+ * @param {DispatchContract} [contract] - 派发契约（见 design.md DispatchContract 接口定义）
+ * @returns {string} 注入 execute prompt 的 Local 后端派发指令文本
+ */
+export function renderLocalInstruction(contract) {
+  const c = contract || {}
+  const worktreePath = c.worktreePath
+  const branch = c.branch
+  const allowedPaths = Array.isArray(c.allowedPaths) ? c.allowedPaths : null
+  const readOnly = !!c.readOnly
+  const brief = c.brief
+  const runId = c.runId
+
+  // 回收约定：替换 <runId> 占位符；runId 缺失保留占位符让 agent 警觉
+  const recycleRule = LOCAL_RECYCLE_RULE.replaceAll(
+    '<runId>',
+    runId ? String(runId) : '<未提供 runId>'
+  )
+
+  const workdirDisplay = worktreePath
+    ? String(worktreePath)
+    : '<未提供 contract.worktreePath — 派发前必须补齐，否则破坏 worktree 隔离>'
+
+  const branchLine = branch
+    ? `- worktree 当前分支：\`${branch}\``
+    : '- worktree 当前分支：未提供（沿用 worktree 检出时的既有分支）'
+
+  const allowedLine = allowedPaths && allowedPaths.length
+    ? `- 本次任务边界（allowedPaths）：${allowedPaths.map(p => `\`${p}\``).join(' / ')}`
+    : '- 本次任务边界（allowedPaths）：未提供，按蓝图 tasks/task-XX.md 的 allowed_paths 为准'
+
+  const briefLine = brief
+    ? String(brief)
+    : '<未提供 contract.brief — 派发前必须补齐任务目标与蓝图路径>'
+
+  const modeLine = readOnly
+    ? '5. **只读模式（readOnly=true）**：本子代理只读 / 审查 / 写 review.json，**不改源码**'
+    : '5. **写模式（readOnly=false）**：按蓝图实现源码（TDD：先读后写 → 写测试 → 写实现）'
+
+  return `### 派发后端：Local（本机 Agent tool）— 默认与降级路径
+
+本指令用**本机 Agent tool**（Claude Code Task 工具）启动子代理执行任务。这是默认与降级
+路径：SillyHub MCP 不可用 / 未配置 / 路径 A 未落地时全程走此路径，派发行为与既有 execute
+波次派发等价（零回归）。
+
+**你的角色是调度者 + 审查者，不要自己写代码。** 每个任务由一个独立子代理执行，同 Wave 内
+可并行启动多个子代理。
+
+### 启动子代理（必须严格遵守）
+
+调用本机 Agent tool（Task 工具）为该 task 启动一个独立子代理，参数结构范例：
+
+\`\`\`json
+{
+  "subagent_type": "general",
+  "workdir": "${workdirDisplay}",
+  "prompt": "在此编写任务描述：任务目标 + 蓝图路径 + 编码铁律（见下方要点）"
+}
+\`\`\`
+
+### workdir 强制必传 = contract.worktreePath（关键）
+
+**workdir 参数是强制必传的，值必须为 \`${workdirDisplay}\`（contract.worktreePath）。**
+
+- **不传 workdir，子代理会在主工作区（主仓库根）而非 worktree 里读写文件**，把改动写到
+  主工作区、**破坏 worktree 隔离**，后续 assess / apply / review.json 全部错位，并可能
+  撞其他并行 agent 的改动。
+${branchLine}
+- 蓝图文件（tasks.md / design.md / tasks/task-XX.md）在主工作区 \`.sillyspec/changes/<change>/\`
+  下，可能不在 worktree 中——**读蓝图用主工作区绝对路径，不要拼接到 worktree 路径下**；
+  写代码必须落在 workdir（worktree）内。
+
+### 子代理 prompt 要点
+
+在子代理 prompt 里写明：
+1. 任务目标（brief）：${briefLine}
+2. 蓝图文件路径（让子代理按需读取详情，不要内联整份蓝图污染上下文）
+3. 编码铁律：先读后写、TDD、不编造方法、只做蓝图里写的事、遵守边界处理规则、不超出 allowedPaths
+4. 如存在模块文档（\`.sillyspec/docs/*/modules/\`），按需读取涉及模块的 <module>.md 参考接口约定与数据流
+${modeLine}
+${allowedLine}
+
+### Local 后端忽略的字段（不消费）
+
+本机 Agent tool 不做异构模型 / agent 分配，故 Local 后端**忽略** contract 中的以下字段
+（仅 SillyHub 后端消费，此处列出仅为避免 agent 误把它们塞进 Agent tool 参数）：
+- \`modelHint\` → SillyHub model 映射，Local 不传给本机 Agent tool
+- \`agentProfileHint\` → SillyHub agent_profile_id 映射，Local 不传给本机 Agent tool
+- \`missionId\` → SillyHub「一 Wave 一 mission」概念（D-008），Local 无 mission
+
+${recycleRule}`
+}