@twinsearth/fang-dsh-plugin 0.0.0-stage → 3.3.4

package/src/lib/ai-secret-store.mjs

@@ -0,0 +1,202 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+//
+// ai-secret-store — AI advisor 的 API Key 持久化：只走 OS 钥匙串 / DPAPI，绝不落明文。
+//
+// 支持的 backend：
+//   * win32  : DPAPI（用户级）——PowerShell 调 ProtectedData.Protect/Unprotect，secret 走 stdin
+//   * linux  : secret-tool（Secret Service / libsecret）——secret 走 stdin
+//   * darwin : 暂未实现（明确返回 unavailable，不假装成功）
+//   * 其它   : unavailable
+//
+// 磁盘上只存：
+//   <dataDir>/decision-ai-secret.json   { version, backend, provider, model, baseUrl, updatedAt }
+//   <dataDir>/decision-ai-secret.enc    backend 加密后的 blob（DPAPI 是 base64 密文；secret-tool 不落盘）
+// 若 backend 不可用 => available=false，调用方必须退回「仅内存」，绝不写明文。
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+import { ensureDir, writeJsonAtomic } from '../kernel/index.mjs'
+
+export const SECRET_META_FILE = 'decision-ai-secret.json'
+export const SECRET_BLOB_FILE = 'decision-ai-secret.enc'
+export const DEFAULT_SERVICE = 'dsh-fang-decision-ai'
+
+const PS_PROTECT = [
+  'Add-Type -AssemblyName System.Security',
+  '$b64=[Console]::In.ReadToEnd()',
+  '$bytes=[Convert]::FromBase64String($b64)',
+  '$enc=[System.Security.Cryptography.ProtectedData]::Protect($bytes,$null,[System.Security.Cryptography.DataProtectionScope]::CurrentUser)',
+  '[Console]::Out.Write([Convert]::ToBase64String($enc))',
+].join('; ')
+
+const PS_UNPROTECT = [
+  'Add-Type -AssemblyName System.Security',
+  '$b64=[Console]::In.ReadToEnd()',
+  '$bytes=[Convert]::FromBase64String($b64)',
+  '$raw=[System.Security.Cryptography.ProtectedData]::Unprotect($bytes,$null,[System.Security.Cryptography.DataProtectionScope]::CurrentUser)',
+  '[Console]::Out.Write([Convert]::ToBase64String($raw))',
+].join('; ')
+
+/** 默认 runner：同步执行，stdin 传 secret，stdout 回结果；不把 secret 放进 argv。 */
+export function defaultRunner(command, args, input = '') {
+  const result = spawnSync(command, args, { input, encoding: 'utf8', windowsHide: true, timeout: 15000 })
+  return {
+    ok: result.status === 0,
+    status: result.status ?? -1,
+    stdout: String(result.stdout ?? '').trim(),
+    stderr: String(result.stderr ?? '').trim(),
+    error: result.error ? String(result.error?.message ?? result.error) : '',
+  }
+}
+
+export function detectSecretBackend({ platform = process.platform, runner = defaultRunner } = {}) {
+  if (platform === 'win32') {
+    const probe = runner('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', 'Add-Type -AssemblyName System.Security; "ok"'])
+    return probe.ok ? { backend: 'dpapi', available: true } : { backend: 'unavailable', available: false, reason: 'dpapi-probe-failed' }
+  }
+  if (platform === 'linux') {
+    const probe = runner('secret-tool', ['--version'])
+    return probe.ok ? { backend: 'secret-service', available: true } : { backend: 'unavailable', available: false, reason: 'secret-tool-missing' }
+  }
+  return { backend: 'unavailable', available: false, reason: platform === 'darwin' ? 'keychain-not-implemented' : 'platform-unsupported' }
+}
+
+/**
+ * @param {{dataDir:string, platform?:string, runner?:Function, service?:string, logger?:object}} options
+ */
+export function createAiSecretStore(options = {}) {
+  const dataDir = String(options.dataDir ?? '')
+  if (!dataDir) throw new Error('createAiSecretStore: dataDir required')
+  const platform = options.platform ?? process.platform
+  const runner = typeof options.runner === 'function' ? options.runner : defaultRunner
+  const service = String(options.service ?? DEFAULT_SERVICE)
+  const log = (level, message) => { try { options.logger?.[level]?.(`[ai-secret-store] ${message}`) } catch { /* ignore */ } }
+  const metaFile = path.join(dataDir, SECRET_META_FILE)
+  const blobFile = path.join(dataDir, SECRET_BLOB_FILE)
+  // 懒探测：只有真正需要持久化/读取能力时才执行后端探测（测试/未配置 AI 时零开销）。
+  let detection = null
+  const ensureBackend = () => {
+    if (detection === null) detection = detectSecretBackend({ platform, runner })
+    return detection
+  }
+
+  const readJson = (file) => {
+    try { return JSON.parse(fs.readFileSync(file, 'utf8')) } catch { return null }
+  }
+  const removeIfExists = (file) => { try { if (fs.existsSync(file)) fs.unlinkSync(file) } catch { /* ignore */ } }
+
+  function encrypt(secretJson) {
+    const detection = ensureBackend()
+    const plain = Buffer.from(secretJson, 'utf8').toString('base64')
+    if (detection.backend === 'dpapi') {
+      const out = runner('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', PS_PROTECT], plain)
+      if (!out.ok || !out.stdout) return { ok: false, reason: 'dpapi-protect-failed', detail: out.stderr || out.error }
+      return { ok: true, payload: out.stdout }
+    }
+    if (detection.backend === 'secret-service') {
+      const out = runner('secret-tool', ['store', '--label', 'dsh-fang decision AI key', 'service', service, 'slot', 'api-key'], secretJson)
+      if (!out.ok) return { ok: false, reason: 'secret-tool-store-failed', detail: out.stderr || out.error }
+      return { ok: true, payload: '' }
+    }
+    return { ok: false, reason: 'secret-backend-unavailable' }
+  }
+
+  function decrypt(payload) {
+    const detection = ensureBackend()
+    if (detection.backend === 'dpapi') {
+      const out = runner('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', PS_UNPROTECT], String(payload ?? ''))
+      if (!out.ok || !out.stdout) return { ok: false, reason: 'dpapi-unprotect-failed', detail: out.stderr || out.error }
+      try { return { ok: true, secretJson: Buffer.from(out.stdout, 'base64').toString('utf8') } } catch { return { ok: false, reason: 'dpapi-decode-failed' } }
+    }
+    if (detection.backend === 'secret-service') {
+      const out = runner('secret-tool', ['lookup', 'service', service, 'slot', 'api-key'])
+      if (!out.ok || !out.stdout) return { ok: false, reason: 'secret-tool-lookup-failed', detail: out.stderr || out.error }
+      return { ok: true, secretJson: out.stdout }
+    }
+    return { ok: false, reason: 'secret-backend-unavailable' }
+  }
+
+  return {
+    get backend() { return ensureBackend().backend },
+    get available() { return ensureBackend().available === true },
+    get reason() { return ensureBackend().reason ?? null },
+    service,
+    capabilities() {
+      const detection = ensureBackend()
+      return { backend: detection.backend, available: detection.available === true, reason: detection.reason ?? null, encryptedAtRest: detection.backend === 'dpapi' ? 'dpapi-user' : detection.backend === 'secret-service' ? 'os-secret-service' : 'none' }
+    },
+    /** 保存 { provider, model, baseUrl, apiKey }；失败返回 ok:false，调用方保持仅内存。 */
+    save(config = {}) {
+      const detection = ensureBackend()
+      if (!detection.available) return { ok: false, reason: detection.reason ?? 'secret-backend-unavailable' }
+      const apiKey = String(config.apiKey ?? '').trim()
+      if (!apiKey) return { ok: false, reason: 'api-key-required' }
+      const meta = {
+        version: 1,
+        backend: detection.backend,
+        provider: String(config.provider ?? '').slice(0, 40),
+        model: String(config.model ?? '').slice(0, 120),
+        baseUrl: String(config.baseUrl ?? '').slice(0, 500),
+        updatedAt: Date.now(),
+      }
+      const encrypted = encrypt(JSON.stringify({
+        apiKey,
+        ...(Array.isArray(config.profiles) ? { profiles: config.profiles } : {}),
+        ...(config.routes && typeof config.routes === 'object' ? { routes: config.routes } : {}),
+        ...(config.modelByLevel && typeof config.modelByLevel === 'object' ? { modelByLevel: config.modelByLevel } : {}),
+      }))
+      if (!encrypted.ok) return encrypted
+      try {
+        ensureDir(dataDir)
+        if (encrypted.payload) {
+          fs.writeFileSync(blobFile, encrypted.payload, { encoding: 'utf8', mode: 0o600 })
+          try { fs.chmodSync(blobFile, 0o600) } catch { /* windows */ }
+        }
+        writeJsonAtomic(metaFile, meta)
+        return { ok: true, backend: detection.backend, meta }
+      } catch (error) {
+        log('warn', `save failed: ${String(error?.message ?? error)}`)
+        return { ok: false, reason: 'persist-failed', detail: String(error?.message ?? error) }
+      }
+    },
+    /** 读取已持久化配置；不存在/backend 不匹配/解密失败 => null（不抛）。 */
+    load() {
+      // 没有落盘元数据时不要探测 backend（避免无 AI 配置的宿主每次启动都拉起 PowerShell）。
+      if (!fs.existsSync(metaFile)) return null
+      const detection = ensureBackend()
+      if (!detection.available) return null
+      const meta = readJson(metaFile)
+      if (!meta || meta.backend !== detection.backend) return null
+      let payload = ''
+      try { payload = fs.existsSync(blobFile) ? fs.readFileSync(blobFile, 'utf8') : '' } catch { payload = '' }
+      if (detection.backend === 'dpapi' && !payload) return null
+      const decrypted = decrypt(payload)
+      if (!decrypted.ok) { log('warn', `load failed: ${decrypted.reason}`); return null }
+      let secret = null
+      try { secret = JSON.parse(decrypted.secretJson) } catch { return null }
+      const apiKey = String(secret?.apiKey ?? '').trim()
+      if (!apiKey) return null
+      return {
+        provider: String(meta.provider ?? 'custom'),
+        model: String(meta.model ?? ''),
+        baseUrl: String(meta.baseUrl ?? ''),
+        apiKey,
+        ...(Array.isArray(secret.profiles) ? { profiles: secret.profiles } : {}),
+        ...(secret.routes && typeof secret.routes === 'object' ? { routes: secret.routes } : {}),
+        ...(secret.modelByLevel && typeof secret.modelByLevel === 'object' ? { modelByLevel: secret.modelByLevel } : {}),
+        source: `os:${detection.backend}`,
+        backend: detection.backend,
+      }
+    },
+    clear() {
+      removeIfExists(metaFile)
+      removeIfExists(blobFile)
+      if (ensureBackend().backend === 'secret-service') {
+        try { runner('secret-tool', ['clear', 'service', service, 'slot', 'api-key']) } catch { /* ignore */ }
+      }
+      return { ok: true }
+    },
+  }
+}

package/src/lib/boot-guard.mjs

@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+//
+// boot-guard — 启动前/发布前插件树自检（fail-loud 之前拦住）：
+//   * 解析 fang bundle 的 cordis.patch.yml 行（id/name）；
+//   * 检查 id 重复、模块可解析、子进程 isolation import() 且导出 apply()；
+//   * 可选：把失败行 disabled:true 合并进 profile 的 cordis.patch.yml（安全模式）。
+// 原则：任何一项失败都只报告/禁用，不修改 DSH 核心文件；写 profile 前必须备份。
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { pathToFileURL } from 'node:url'
+import { createRequire } from 'node:module'
+
+import { parseYamlSubset } from './rule-registry.mjs'
+
+export const FANG_PACKAGE_NAMES = Object.freeze(['@twinsearth/fang-dsh-plugin', '@twinsearth/dsh-fang', '@twinsearth/fang-dsh-plugin'])
+export const SMOKE_TIMEOUT_MS = 8000
+
+/** 找到 profile 里已安装的 fang 包目录（发布名优先，其次本地 link 名）。 */
+export function findFangPackageDir(profileDir) {
+  for (const name of FANG_PACKAGE_NAMES) {
+    const candidate = path.join(String(profileDir ?? ''), 'node_modules', ...name.split('/'))
+    try { if (fs.statSync(candidate).isDirectory()) return candidate } catch { /* next */ }
+  }
+  return null
+}
+
+/** 解析 bundle patch → 行数组 [{id, name}]。 */
+export function readBundleRows(pkgDir) {
+  const file = path.join(String(pkgDir ?? ''), 'cordis.patch.yml')
+  let text = ''
+  try { text = fs.readFileSync(file, 'utf8') } catch { return { ok: false, error: 'patch-missing', rows: [] } }
+  const parsed = parseYamlSubset(text)
+  const value = parsed?.value
+  const insert = Array.isArray(value) ? value.flatMap((item) => Array.isArray(item?.insert) ? item.insert : []) : (Array.isArray(value?.insert) ? value.insert : [])
+  const rows = insert.filter((row) => row && typeof row === 'object' && row.id).map((row) => ({
+    id: String(row.id),
+    name: row.name === undefined ? null : String(row.name),
+    disabled: row.disabled === true,
+  }))
+  return { ok: parsed.errors.length === 0, error: parsed.errors.length ? `patch-parse:${parsed.errors[0]}` : null, rows, parseErrors: parsed.errors }
+}
+
+/** 在隔离子进程 import 模块，确认可加载且导出 apply。 */
+export function smokeModule(moduleUrl, { timeoutMs = SMOKE_TIMEOUT_MS } = {}) {
+  const script = `
+    const url = process.argv[1];
+    import(url).then((m) => {
+      process.stdout.write(JSON.stringify({ ok: typeof m.apply === 'function', hasApply: typeof m.apply === 'function', name: m.name ?? null }));
+    }).catch((e) => {
+      process.stdout.write(JSON.stringify({ ok: false, hasApply: false, error: String(e && e.message || e).slice(0, 500) }));
+    });
+  `
+  const result = spawnSync(process.execPath, ['--input-type=module', '-e', script, moduleUrl], {
+    encoding: 'utf8', timeout: timeoutMs, windowsHide: true,
+  })
+  if (result.error?.code === 'ETIMEDOUT' || result.signal) return { ok: false, error: 'timeout' }
+  const line = String(result.stdout ?? '').trim().split('\n').filter(Boolean).pop()
+  if (!line) return { ok: false, error: String(result.stderr ?? '').trim().slice(0, 500) || `exit=${result.status}` }
+  try { return JSON.parse(line) } catch { return { ok: false, error: line.slice(0, 500) } }
+}
+
+/** 读取已安装 fang 包的 package.json name（用于区分“本包行”和可选子插件行）。 */
+export function readPackageName(pkgDir) {
+  try { return String(JSON.parse(fs.readFileSync(path.join(String(pkgDir ?? ''), 'package.json'), 'utf8')).name ?? '') } catch { return '' }
+}
+
+/** 读取 package 的入口（exports["."]/main/ src/index.mjs），用于更新候选包冒烟。 */
+export function readPackageEntry(packageDir) {
+  const dir = String(packageDir ?? '')
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'))
+    const exported = pkg?.exports?.['.']
+    const candidate = typeof exported === 'string'
+      ? exported
+      : (exported && typeof exported === 'object' && typeof exported.default === 'string' ? exported.default : null)
+    const entry = candidate || pkg.main || './src/index.mjs'
+    return path.resolve(dir, entry)
+  } catch { return null }
+}
+
+/** 更新候选包冒烟：入口存在 + 隔离子进程 import + 导出 apply；失败即禁止转正。 */
+export function smokePackage(packageDir, { timeoutMs = SMOKE_TIMEOUT_MS } = {}) {
+  const dir = String(packageDir ?? '')
+  const entry = readPackageEntry(dir)
+  if (!entry) return { ok: false, error: 'package-json-missing', packageDir: dir }
+  try { if (!fs.statSync(entry).isFile()) return { ok: false, error: 'entry-missing', entry } } catch { return { ok: false, error: 'entry-missing', entry } }
+  const result = smokeModule(pathToFileURL(entry).href, { timeoutMs })
+  return { ...result, entry, packageDir: dir }
+}
+
+/**
+ * 检查行：重复 id、模块解析、隔离 import 冒烟。
+ * 本包行失败 = block；可选子插件（如 @twinsearth/dsh-fang-web-entry）缺失/失败 = warn。
+ * @returns {{ok:boolean, findings:Array<{code,level,id?,detail?}>, checked:number}}
+ */
+export function checkBundleRows(rows, { profileDir, ownPackage = '', timeoutMs = SMOKE_TIMEOUT_MS } = {}) {
+  const findings = []
+  const seen = new Set()
+  let checked = 0
+  const requireFrom = createRequire(path.join(String(profileDir ?? ''), 'package.json'))
+  const isOwnRow = (name) => {
+    const own = String(ownPackage ?? '').trim()
+    if (!own) return true
+    return name === own || name.startsWith(`${own}/`)
+  }
+  for (const row of rows) {
+    if (seen.has(row.id)) {
+      findings.push({ code: 'duplicate-id', level: 'block', id: row.id, detail: row.id })
+      continue
+    }
+    seen.add(row.id)
+    // v3.3.3：disabled 行不会加载；不因可选子插件未安装/未启用而阻塞启动。
+    if (row.disabled === true) continue
+    if (!row.name) {
+      findings.push({ code: 'row-name-missing', level: 'warn', id: row.id })
+      continue
+    }
+    checked += 1
+    const optional = !isOwnRow(row.name)
+    let resolved = null
+    try { resolved = requireFrom.resolve(row.name) } catch (error) {
+      findings.push({
+        code: 'module-unresolved', level: optional ? 'warn' : 'block', id: row.id,
+        detail: `${row.name}: ${String(error?.message ?? error).slice(0, 200)}`,
+      })
+      continue
+    }
+    const smoke = smokeModule(pathToFileURL(resolved).href, { timeoutMs })
+    if (!smoke.ok) {
+      findings.push({ code: 'module-smoke-failed', level: optional ? 'warn' : 'block', id: row.id, detail: String(smoke.error ?? 'no apply()').slice(0, 300) })
+    }
+  }
+  return { ok: findings.every((finding) => finding.level !== 'block'), findings, checked }
+}
+
+const jsonPatchEntries = (text) => {
+  const trimmed = String(text ?? '').trim()
+  if (!trimmed.startsWith('{') && !trimmed.startsWith('[')) return null
+  try {
+    const value = JSON.parse(trimmed)
+    if (Array.isArray(value)) return value
+    if (value && typeof value === 'object' && Array.isArray(value.insert)) return value.insert
+  } catch { /* yaml */ }
+  return null
+}
+
+/**
+ * 把 disabled 行合并进 profile 的 cordis.patch.yml；先写 .bak-<ts> 备份。
+ * 只接受 id（禁用行）；不会删除/改写已有行。
+ */
+export function applyDisabledRows(profileDir, ids) {
+  const dir = String(profileDir ?? '')
+  if (!dir) return { ok: false, error: 'profile-dir-required' }
+  const wanted = [...new Set((Array.isArray(ids) ? ids : []).map(String).filter(Boolean))]
+  if (!wanted.length) return { ok: false, error: 'no-ids' }
+  const file = path.join(dir, 'cordis.patch.yml')
+  let text = ''
+  try { text = fs.readFileSync(file, 'utf8') } catch { text = '' }
+  try { fs.mkdirSync(dir, { recursive: true }); if (text) fs.writeFileSync(`${file}.bak-${Date.now()}`, text, 'utf8') } catch { /* backup best-effort */ }
+  const asJson = jsonPatchEntries(text)
+  if (asJson !== null) {
+    const existing = new Set(asJson.map((entry) => entry && typeof entry === 'object' ? String(entry.id ?? '') : ''))
+    const merged = asJson.slice()
+    let added = 0
+    for (const id of wanted) {
+      if (existing.has(id)) continue
+      merged.push({ id, disabled: true })
+      added += 1
+    }
+    fs.writeFileSync(file, `${JSON.stringify(merged, null, 2)}\n`, 'utf8')
+    return { ok: true, added, file, format: 'json' }
+  }
+  const kept = String(text ?? '').replace(/^\uFEFF/, '').split(/\r?\n/).filter((line) => !/^\s*\[\s*\]\s*(#.*)?$/.test(line))
+  const body = kept.join('\n')
+  const lines = []
+  for (const id of wanted) {
+    if (new RegExp(`(^|\\n)\\s*-\\s*id:\\s*${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`, 'm').test(body)) continue
+    lines.push(`- id: ${id}`, '  disabled: true')
+  }
+  if (!lines.length) return { ok: true, added: 0, file, format: 'yaml' }
+  const prefix = body.trim().length === 0 ? '' : (body.endsWith('\n') ? body : body + '\n')
+  fs.writeFileSync(file, `${prefix}${lines.join('\n')}\n`, 'utf8')
+  return { ok: true, added: wanted.length, file, format: 'yaml' }
+}

package/src/lib/branch-store.mjs

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// v3.0.8 branch persistence: one JSON file per task under <dataDir>/tasks/<taskId>/branches.json.
+import fs from 'node:fs'
+import path from 'node:path'
+import { activateBranch, createBranch, createSession, setBranchStatus } from './branch.mjs'
+
+/** taskId is a path segment under <dataDir>/tasks; reject separators and traversal. */
+const TASK_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
+
+export class BranchStore {
+  constructor(dataDir) {
+    this.dataDir = dataDir
+  }
+
+  file(taskId) {
+    const id = String(taskId ?? '')
+    if (!TASK_ID_RE.test(id)) throw new Error('invalid-task-id')
+    return path.join(this.dataDir, 'tasks', id, 'branches.json')
+  }
+
+  load(taskId) {
+    const file = this.file(taskId) // validate outside the read fallback
+    try {
+      const raw = JSON.parse(fs.readFileSync(file, 'utf8'))
+      return {
+        sessionId: raw.sessionId,
+        activeBranchId: raw.activeBranchId,
+        branches: new Map(Object.entries(raw.branches || {})),
+      }
+    } catch {
+      return createSession(String(taskId))
+    }
+  }
+
+  save(taskId, session) {
+    const file = this.file(taskId)
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    const payload = {
+      sessionId: session.sessionId,
+      activeBranchId: session.activeBranchId,
+      branches: Object.fromEntries(session.branches),
+    }
+    const tmp = file + '.tmp'
+    fs.writeFileSync(tmp, JSON.stringify(payload, null, 2) + '\n', 'utf8')
+    fs.renameSync(tmp, file)
+    return payload
+  }
+
+  list(taskId) {
+    const session = this.load(taskId)
+    return { ok: true, sessionId: session.sessionId, activeBranchId: session.activeBranchId, branches: [...session.branches.values()] }
+  }
+
+  create(taskId, input) {
+    const session = this.load(taskId)
+    const branch = createBranch(session, input)
+    this.save(taskId, session)
+    return { ok: true, branch }
+  }
+
+  /** 把分支库的 sessionId 绑定到该分身真实会话（启动/还原时由单会话守卫调用）。 */
+  bindSession(taskId, sessionId) {
+    const session = this.load(taskId)
+    const next = String(sessionId ?? '').trim()
+    if (!next || session.sessionId === next) return { ok: true, sessionId: session.sessionId, changed: false }
+    session.sessionId = next
+    this.save(taskId, session)
+    return { ok: true, sessionId: session.sessionId, changed: true }
+  }
+
+  activate(taskId, branchId) {
+    const session = this.load(taskId)
+    const branch = activateBranch(session, branchId)
+    this.save(taskId, session)
+    return { ok: true, branch, activeBranchId: session.activeBranchId }
+  }
+
+  setStatus(taskId, branchId, status) {
+    const session = this.load(taskId)
+    const branch = setBranchStatus(session, branchId, status)
+    this.save(taskId, session)
+    return { ok: true, branch }
+  }
+}

package/src/lib/branch.mjs

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// v3.0.8 branch model: one session, many branch logs, one writer per branch, no merge.
+import fs from 'node:fs'
+import path from 'node:path'
+
+/** Branch/session ids become directory names; keep them to safe single segments. */
+export const BRANCH_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/
+export const SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
+
+function assertBranchId(branchId) {
+  const id = String(branchId ?? '')
+  if (!BRANCH_ID_RE.test(id)) throw new Error('invalid-branch-id')
+  return id
+}
+
+function assertSessionId(sessionId) {
+  const id = String(sessionId ?? '')
+  if (!SESSION_ID_RE.test(id)) throw new Error('invalid-session-id')
+  return id
+}
+
+export function createSession(sessionId) {
+  const main = { branchId: 'main', parentBranchId: null, baseTurn: 0, status: 'active', createdAt: Date.now() }
+  return { sessionId, activeBranchId: 'main', branches: new Map([['main', main]]) }
+}
+
+export function createBranch(session, { branchId, parentBranchId = session.activeBranchId, baseTurn = 0, sessionId = null }) {
+  const id = assertBranchId(branchId)
+  if (id === 'main') throw new Error('invalid-branch-id')
+  if (session.branches.has(id)) throw new Error('branch-exists')
+  if (!session.branches.has(parentBranchId)) throw new Error('parent-missing')
+  session.branches.set(id, {
+    branchId: id, parentBranchId, baseTurn, status: 'active', createdAt: Date.now(),
+    sessionId: typeof sessionId === 'string' && sessionId.trim() ? sessionId.trim() : null,
+  })
+  return session.branches.get(id)
+}
+
+export function activateBranch(session, branchId) {
+  const id = assertBranchId(branchId)
+  const branch = session.branches.get(id)
+  if (!branch) throw new Error('branch-missing')
+  if (branch.status !== 'active') throw new Error('branch-not-active')
+  session.activeBranchId = id
+  return branch
+}
+
+export function setBranchStatus(session, branchId, status) {
+  const id = assertBranchId(branchId)
+  if (!['sealed', 'archived'].includes(status)) throw new Error('invalid-status')
+  const branch = session.branches.get(id)
+  if (!branch) throw new Error('branch-missing')
+  if (id === session.activeBranchId) throw new Error('cannot-seal-active')
+  branch.status = status
+  return branch
+}
+
+export function branchPath(root, sessionId, branchId) {
+  return path.join(root, assertSessionId(sessionId), 'branches', assertBranchId(branchId))
+}
+
+export function acquireWriter(root, sessionId, branchId) {
+  const dir = branchPath(root, sessionId, branchId)
+  fs.mkdirSync(dir, { recursive: true })
+  const lock = path.join(dir, 'writer.lock')
+  try {
+    fs.writeFileSync(lock, String(process.pid), { flag: 'wx' })
+  } catch {
+    const error = new Error('branch-busy')
+    error.code = '409'
+    throw error
+  }
+  return { release() { try { fs.rmSync(lock, { force: true }) } catch { /* ignore */ } } }
+}