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

package/src/lib/fork-seed.mjs

@@ -0,0 +1,304 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+//
+// fork-seed — 派生分身的默认第三方插件种子（v3.1.12）。
+//
+// 新机器/新用户的干净分身模板只有 base + web-app + fang；这里按“安装不激活 /
+// 安装并激活”两组清单，把默认第三方插件装进**每个新分身自己的 profile**：
+//   * install  = 只写入 dependencies 并安装 node_modules，不加入 profile bundles；
+//   * activate = 额外加入 profile 的 dsh.profile.bundles，DSH 启动时就会加载。
+// 安装缓存在 <forkHomes>/.plugin-seed/seed-<fingerprint>，用 dsh 自带 pnpm 完成；
+// 模块树通过 hardlink 合并进分身 `node_modules`，不替换原有的 mother 镜像条目。
+import { spawn } from 'node:child_process'
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { ensureDir, exists, hardlinkTree, isLink, removeTree, writeJsonAtomic } from '../kernel/index.mjs'
+
+/** 用户给定的默认清单（2026-11-11）。新增/调整只改这里，再同步 docs/CHANGELOG。 */
+export const DEFAULT_FORK_SEED = Object.freeze({
+  enabled: true,
+  install: Object.freeze([
+    '@twinsearth/dsh-2xray',
+    '@michengai/dsh-agency-agents',
+    'dsh-better-sidebar',
+    'dsh-context',
+    '@liustack/modlens',
+    '@liustack/modsearch',
+  ]),
+  activate: Object.freeze([
+    'dshmarket',
+    '@twinsearth/dsh-im2a-plugin',
+    '@openviking/dsh-memory-plugin',
+    '@twinsearth/w2m-dsh-plugin',
+  ]),
+})
+
+/** npm 包名（可带 scope），防止配置把路径/参数注入 pnpm 命令。 */
+const PACKAGE_NAME_RE = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/i
+
+/** 把用户配置归一成 { enabled, install, activate, packages }（去重、过滤非法名）。 */
+export function normalizeForkSeed(input = {}) {
+  const raw = input && typeof input === 'object' ? input : {}
+  const enabled = raw.enabled !== false
+  const clean = (list) => [...new Set((Array.isArray(list) ? list : []).map((item) => String(item ?? '').trim()).filter((name) => PACKAGE_NAME_RE.test(name)))]
+  const install = clean(raw.install ?? DEFAULT_FORK_SEED.install)
+  const activate = clean(raw.activate ?? DEFAULT_FORK_SEED.activate)
+  const packages = [...install, ...activate.filter((name) => !install.includes(name))]
+  return { enabled, install, activate, packages }
+}
+
+/** 种子指纹：配置变化即换缓存目录（排序，顺序不同但集合相同不换缓存）。 */
+export function forkSeedFingerprint(seed) {
+  const norm = normalizeForkSeed(seed)
+  const canonical = { packages: [...norm.packages].sort(), activate: [...norm.activate].sort() }
+  return crypto.createHash('sha256').update(JSON.stringify(canonical)).digest('hex').slice(0, 16)
+}
+
+function readJson(file, fallback = null) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')) } catch { return fallback }
+}
+
+function packageDirName(name) {
+  return name.split('/')
+}
+
+export function seedPackageDir(modulesDir, name) {
+  return path.join(String(modulesDir ?? ''), ...packageDirName(name))
+}
+
+function readInstalledVersion(modulesDir, name) {
+  const pkg = readJson(path.join(seedPackageDir(modulesDir, name), 'package.json'), null)
+  return pkg && typeof pkg.version === 'string' ? pkg.version : ''
+}
+
+/**
+ * 把种子模块合并进分身 `node_modules`：
+ *   * 普通包：整目录 hardlink 覆盖；
+ *   * scope：把目标 scope（可能是 junction / 真实目录）先展开成真实目录，再覆盖 seed 里的子包。
+ * 不删除 seed 之外的目标条目（mother 镜像要继续可用）。
+ */
+export function mergeSeedModules(seedModulesDir, targetModulesDir) {
+  const source = String(seedModulesDir ?? '')
+  const target = String(targetModulesDir ?? '')
+  if (!source || !exists(source)) return { ok: false, error: 'seed-modules-missing' }
+  if (!target || !exists(target)) return { ok: false, error: 'target-modules-missing' }
+  const copied = []
+  const scopes = []
+  const warnings = []
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    const name = entry.name
+    if (name.startsWith('.') || !entry.isDirectory()) continue
+    const from = path.join(source, name)
+    const to = path.join(target, name)
+    try {
+      if (name.startsWith('@')) {
+        mergeScope(from, to)
+        scopes.push(name)
+      } else {
+        removeTree(to)
+        hardlinkTree(from, to)
+        copied.push(name)
+      }
+    } catch (error) {
+      warnings.push(`${name}: ${String(error?.message ?? error)}`)
+    }
+  }
+  return { ok: warnings.length === 0, copied, scopes, warnings }
+}
+
+function mergeScope(seedScope, targetScope) {
+  const staging = `${targetScope}.fang-seed-merge`
+  removeTree(staging)
+  ensureDir(staging)
+  // 1) 保留目标 scope 既有子包（可能是指向 mother 模块树的 junction）。
+  if (exists(targetScope) || isLink(targetScope)) {
+    for (const child of fs.readdirSync(targetScope, { withFileTypes: true })) {
+      const from = path.join(targetScope, child.name)
+      const to = path.join(staging, child.name)
+      try {
+        if (child.isSymbolicLink()) {
+          const resolved = fs.realpathSync(from)
+          hardlinkTree(resolved, to)
+        } else if (child.isDirectory()) hardlinkTree(from, to)
+      } catch { /* keep the rest */ }
+    }
+  }
+  // 2) seed 子包覆盖同名项。
+  for (const child of fs.readdirSync(seedScope, { withFileTypes: true })) {
+    if (!child.isDirectory()) continue
+    const from = path.join(seedScope, child.name)
+    const to = path.join(staging, child.name)
+    removeTree(to)
+    hardlinkTree(from, to)
+  }
+  // 3) 原子替换 scope 目录。
+  removeTree(targetScope)
+  try { fs.renameSync(staging, targetScope) } catch {
+    removeTree(staging)
+    hardlinkTree(seedScope, targetScope)
+  }
+}
+
+/**
+ * 把种子写进分身 profile 的 package.json：
+ *   dependencies += 所有种子包（已有 spec 不覆盖）；
+ *   dsh.profile.bundles += activate 列表（放在 fang 之后，去重）。
+ * @returns {{packageJson:object, changed:boolean, addedDependencies:string[], addedBundles:string[]}}
+ */
+export function forkSeedProfilePatch(profilePkg, seed, versions = {}) {
+  const norm = normalizeForkSeed(seed)
+  const pkg = profilePkg && typeof profilePkg === 'object' ? JSON.parse(JSON.stringify(profilePkg)) : {}
+  const dependencies = pkg.dependencies && typeof pkg.dependencies === 'object' ? pkg.dependencies : {}
+  const addedDependencies = []
+  for (const name of norm.packages) {
+    if (typeof dependencies[name] === 'string' && dependencies[name].trim()) continue
+    const version = String(versions[name] ?? '').trim()
+    dependencies[name] = version ? `^${version}` : '*'
+    addedDependencies.push(name)
+  }
+  if (Object.keys(dependencies).length > 0) pkg.dependencies = dependencies
+  pkg.dsh = pkg.dsh && typeof pkg.dsh === 'object' ? pkg.dsh : {}
+  pkg.dsh.profile = pkg.dsh.profile && typeof pkg.dsh.profile === 'object' ? pkg.dsh.profile : {}
+  const bundles = Array.isArray(pkg.dsh.profile.bundles) ? [...pkg.dsh.profile.bundles] : []
+  const addedBundles = []
+  for (const name of norm.activate) {
+    if (bundles.includes(name)) continue
+    bundles.push(name)
+    addedBundles.push(name)
+  }
+  pkg.dsh.profile.bundles = bundles
+  return { packageJson: pkg, changed: addedDependencies.length > 0 || addedBundles.length > 0, addedDependencies, addedBundles }
+}
+
+const SEED_MARKER = '.fang-fork-seed.json'
+
+/** 从 dsh CLI 路径推导 DSH 自带 pnpm 入口（.../runtime/cli/bin/dsh.cmd → .../runtime/primary-runtime/dependencies/pnpm/bin/pnpm.mjs）。 */
+export function resolvePnpmEntry(cliPath) {
+  const cli = String(cliPath ?? '').trim()
+  if (!cli) return null
+  const cliDir = path.dirname(path.resolve(cli))
+  const candidates = [
+    path.resolve(cliDir, '..', '..', 'primary-runtime', 'dependencies', 'pnpm', 'bin', 'pnpm.mjs'),
+    path.resolve(cliDir, '..', '..', '..', 'runtime', 'primary-runtime', 'dependencies', 'pnpm', 'bin', 'pnpm.mjs'),
+  ]
+  return candidates.find((candidate) => exists(candidate)) ?? null
+}
+
+/**
+ * 默认安装器：在一个**普通 pnpm 项目**里安装种子（不初始化 DSH profile，避免被默认
+ * dsh-llm 之类无法解析的基线依赖拖死）。只装插件包本身，peer 依赖交给宿主解析。
+ */
+export async function installSeedWithPnpm({ cliPath, seedHome, packages, timeoutMs = 300000 }) {
+  const pnpmEntry = resolvePnpmEntry(cliPath)
+  if (!pnpmEntry) return { ok: false, error: 'pnpm-not-found', detail: `cliPath=${cliPath}` }
+  const seedDir = path.join(seedHome, 'seed')
+  ensureDir(seedDir)
+  const dependencies = Object.fromEntries([...packages].sort().map((name) => [name, 'latest']))
+  writeJsonAtomic(path.join(seedDir, 'package.json'), { name: 'fang-fork-seed', private: true, dependencies })
+  fs.writeFileSync(path.join(seedDir, 'pnpm-workspace.yaml'), [
+    'packages:',
+    '  - .',
+    '',
+    'nodeLinker: hoisted',
+    'autoInstallPeers: false',
+    'strictPeerDependencies: false',
+    'minimumReleaseAge: 0',
+    '',
+  ].join('\n'), 'utf8')
+  const nodeBin = process.execPath
+  const args = [pnpmEntry, 'install', '--ignore-scripts', '--config.confirmModulesPurge=false']
+  const result = await new Promise((resolve) => {
+    let output = ''
+    let child = null
+    let timer = null
+    const done = (value) => { if (timer) clearTimeout(timer); resolve(value) }
+    try {
+      child = spawn(nodeBin, args, {
+        cwd: seedDir,
+        env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+    } catch (error) {
+      done({ ok: false, error: 'spawn-failed', detail: String(error?.message ?? error) })
+      return
+    }
+    const append = (chunk) => { output = (output + String(chunk)).slice(-8000) }
+    child.stdout?.on('data', append)
+    child.stderr?.on('data', append)
+    timer = setTimeout(() => { try { child.kill() } catch { /* ignore */ } done({ ok: false, error: 'seed-install-timeout', detail: output.slice(-1200) }) }, Math.max(1000, Number(timeoutMs) || 300000))
+    child.on('error', (error) => done({ ok: false, error: 'spawn-failed', detail: String(error?.message ?? error) }))
+    child.on('exit', (code) => done(code === 0 ? { ok: true, detail: output.slice(-1200) } : { ok: false, error: 'seed-install-failed', code, detail: output.slice(-2400) }))
+  })
+  return { ...result, modulesDir: path.join(seedDir, 'node_modules') }
+}
+
+/**
+ * 给一个分身 profile 装备默认插件种子。幂等：同一指纹已应用则直接返回。
+ * @returns {Promise<{ok:boolean, skipped?:boolean, cached?:boolean, packages?:string[], activate?:string[],
+ *   versions?:Record<string,string>, merged?:object, error?:string, detail?:string}>}
+ */
+export async function applyForkSeedToProfile({ seed, profileDir, profileModulesDir, seedRoot, cliPath, timeoutMs = 300000, install = installSeedWithPnpm } = {}) {
+  const norm = normalizeForkSeed(seed)
+  if (!norm.enabled || norm.packages.length === 0) return { ok: true, skipped: true }
+  const profile = String(profileDir ?? '')
+  if (!profile || !exists(path.join(profile, 'package.json'))) return { ok: false, error: 'profile-package-missing' }
+  if (!cliPath) return { ok: false, error: 'cli-path-missing' }
+  const fingerprint = forkSeedFingerprint(norm)
+  const markerFile = path.join(profile, SEED_MARKER)
+  const marker = readJson(markerFile, null)
+  const modulesDir = String(profileModulesDir ?? path.join(profile, 'node_modules'))
+  const seedHome = path.join(String(seedRoot ?? path.join(path.dirname(profile), '.plugin-seed')), `seed-${fingerprint}`)
+  const seedModules = path.join(seedHome, 'seed', 'node_modules')
+
+  const cached = marker && marker.fingerprint === fingerprint
+    ? norm.packages.every((name) => exists(seedPackageDir(seedModules, name)) && exists(seedPackageDir(modulesDir, name)))
+    : false
+  if (cached) {
+    // v3.1.12: every spawn replays the clean template over the profile config, which
+    // wipes the seeded dependencies/bundles. The seed modules and marker survive, so
+    // re-apply the cheap profile patch on the cached path (no install, no module copy).
+    const cachedPkg = readJson(path.join(profile, 'package.json'), null)
+    if (!cachedPkg) return { ok: false, error: 'profile-package-invalid' }
+    const patched = forkSeedProfilePatch(cachedPkg, norm, marker.versions ?? {})
+    if (patched.changed) writeJsonAtomic(path.join(profile, 'package.json'), patched.packageJson)
+    return {
+      ok: true, cached: true, packages: norm.packages, activate: norm.activate, versions: marker.versions ?? {},
+      patched: { addedDependencies: patched.addedDependencies, addedBundles: patched.addedBundles },
+    }
+  }
+
+  if (!norm.packages.every((name) => exists(seedPackageDir(seedModules, name)))) {
+    const installResult = await install({ cliPath, seedHome, packages: norm.packages, timeoutMs })
+    if (!installResult?.ok) return { ok: false, error: installResult?.error ?? 'seed-install-failed', detail: installResult?.detail ?? '' }
+  }
+  const unknown = norm.packages.filter((name) => !exists(seedPackageDir(seedModules, name)))
+  if (unknown.length > 0) return { ok: false, error: 'seed-packages-missing', detail: unknown.join(',') }
+  const versions = Object.fromEntries(norm.packages.map((name) => [name, readInstalledVersion(seedModules, name)]).filter(([, version]) => version))
+
+  const profilePkg = readJson(path.join(profile, 'package.json'), null)
+  if (!profilePkg) return { ok: false, error: 'profile-package-invalid' }
+  const patched = forkSeedProfilePatch(profilePkg, norm, versions)
+  if (patched.changed) writeJsonAtomic(path.join(profile, 'package.json'), patched.packageJson)
+
+  const merged = mergeSeedModules(seedModules, modulesDir)
+  if (!merged.ok) {
+    return {
+      ok: false, error: 'seed-modules-merge-failed', detail: (merged.warnings ?? []).join('; '),
+      packages: norm.packages, versions, merged,
+    }
+  }
+  writeJsonAtomic(markerFile, {
+    fingerprint,
+    packages: norm.packages,
+    activate: norm.activate,
+    versions,
+    appliedAt: Date.now(),
+    merged: { copied: merged.copied.length, scopes: merged.scopes.length },
+  })
+  return { ok: true, packages: norm.packages, activate: norm.activate, versions, merged, patched: { addedDependencies: patched.addedDependencies, addedBundles: patched.addedBundles } }
+}
+
+export { SEED_MARKER }

package/src/lib/fork-sessions.mjs

@@ -0,0 +1,183 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+//
+// v3.1.35 — 分身会话数约束（1..3）与默认空会话。
+//
+// 规格（用户 2026-11-13）：
+//   「默认一个分身 Web 端的分身会话，默认不能为 0 至少有 1 个（空会话），
+//     不超过 3 个，可以有多个分支。」
+//
+// 于是：
+//   * 下限 1：分身 Web 里永远至少有一个会话可用；空白派生时自动补一个空会话；
+//   * 上限 3：超过 3 个时把较旧的移入 quarantine-sessions/（不删除）；
+//   * 分支不受此限：分支是同一会话的不同走向，不是新的会话。
+import fs from 'node:fs'
+import path from 'node:path'
+import zlib from 'node:zlib'
+import { randomUUID } from 'node:crypto'
+import { encodeWorkspaceKey } from './session-format.mjs'
+
+// 复用并对外暴露，便于调用方与测试统一。
+export { encodeWorkspaceKey }
+
+export const FORK_SESSION_MIN = 1
+export const FORK_SESSION_MAX = 3
+
+const SESSION_FILE = 'session.v4.jsonl.zstd'
+const DEFAULT_PRESET = 'standard'
+const DEFAULT_PERMISSION = 'workspace-write'
+const DEFAULT_SANDBOX = 'workspace-write'
+const DEFAULT_APPROVAL = 'ask'
+
+/** The minimal legal DSH session log (verified against a real 397-byte empty session). */
+export function buildEmptySessionFrames({ sessionId, createdAt, cwd }) {
+  const id = String(sessionId ?? '')
+  const at = Number(createdAt) || Date.now()
+  const workspace = String(cwd ?? '')
+  return [
+    JSON.stringify({
+      type: 'session', version: 4, id, createdAt: at, cwd: workspace,
+      isSeeded: false, delegationDepth: 0, agentPreset: DEFAULT_PRESET,
+    }),
+    JSON.stringify({ type: 'permission/preset', seq: 0, time: at + 24, data: { preset: DEFAULT_PERMISSION } }),
+    JSON.stringify({ type: 'sandbox/mode', seq: 1, time: at + 40, data: { mode: DEFAULT_SANDBOX } }),
+    JSON.stringify({ type: 'approval/policy', seq: 2, time: at + 41, data: { policy: DEFAULT_APPROVAL } }),
+    JSON.stringify({ type: 'session/end-seed', seq: 3, time: at, data: {} }),
+  ]
+}
+
+export function encodeSessionLog(frames, { compress = true } = {}) {
+  const text = frames.join('\n') + '\n'
+  const buffer = Buffer.from(text, 'utf8')
+  if (!compress) return buffer
+  if (typeof zlib.zstdCompressSync !== 'function') {
+    throw new Error('zstd-unavailable: this Node build has no zlib.zstdCompressSync')
+  }
+  return zlib.zstdCompressSync(buffer)
+}
+
+/** Scan a fork home's own sessions: one entry per session directory. */
+export function scanForkSessions(homeDir) {
+  const sessionsRoot = path.join(String(homeDir), 'sessions')
+  const out = []
+  let workspaceDirs = []
+  try { workspaceDirs = fs.readdirSync(sessionsRoot, { withFileTypes: true }).filter((e) => e.isDirectory()) } catch { return out }
+  for (const workspace of workspaceDirs) {
+    const workspaceDir = path.join(sessionsRoot, workspace.name)
+    let sessionDirs = []
+    try { sessionDirs = fs.readdirSync(workspaceDir, { withFileTypes: true }).filter((e) => e.isDirectory()) } catch { continue }
+    for (const session of sessionDirs) {
+      const file = path.join(workspaceDir, session.name, SESSION_FILE)
+      let mtimeMs = 0
+      let bytes = 0
+      try {
+        const stat = fs.statSync(file)
+        mtimeMs = stat.mtimeMs
+        bytes = stat.size
+      } catch { continue }
+      out.push({ workspaceKey: workspace.name, sessionId: session.name, file, mtimeMs, bytes })
+    }
+  }
+  out.sort((a, b) => b.mtimeMs - a.mtimeMs)
+  return out
+}
+
+function readWorkspaceIndex(homeDir) {
+  const file = path.join(String(homeDir), 'storages', 'workspace.json')
+  let doc = null
+  try { doc = JSON.parse(fs.readFileSync(file, 'utf8')) } catch { doc = null }
+  if (!doc || typeof doc !== 'object') {
+    doc = {
+      unit: { name: 'workspace', version: 2 },
+      global: { initialized: true, defaultWorkspaceId: null, workspaceIds: [], archivedSessionIds: [], pinnedSessionIds: [] },
+      tables: { workspaces: {} },
+    }
+  }
+  doc.tables = doc.tables && typeof doc.tables === 'object' ? doc.tables : {}
+  doc.tables.workspaces = doc.tables.workspaces && typeof doc.tables.workspaces === 'object' ? doc.tables.workspaces : {}
+  doc.global = doc.global && typeof doc.global === 'object'
+    ? doc.global
+    : { initialized: true, defaultWorkspaceId: null, workspaceIds: [], archivedSessionIds: [], pinnedSessionIds: [] }
+  doc.global.workspaceIds = Array.isArray(doc.global.workspaceIds) ? doc.global.workspaceIds : []
+  return { file, doc }
+}
+
+function writeWorkspaceIndex(file, doc) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  const tmp = file + '.tmp'
+  fs.writeFileSync(tmp, JSON.stringify(doc, null, 2), 'utf8')
+  fs.renameSync(tmp, file)
+}
+
+/**
+ * Ensure the fork has at least FORK_SESSION_MIN sessions (default: one empty session).
+ * Returns { ok, created, sessionId, workspaceKey } — idempotent when a session already exists.
+ */
+export function ensureForkEmptySession(homeDir, { workspacePath = '', workspaceTitle = '', now = Date.now() } = {}) {
+  const existing = scanForkSessions(homeDir)
+  if (existing.length >= FORK_SESSION_MIN) {
+    return { ok: true, created: false, sessionId: existing[0].sessionId, workspaceKey: existing[0].workspaceKey }
+  }
+  const cwd = String(workspacePath ?? '').trim() || process.cwd()
+  const title = String(workspaceTitle ?? '').trim() || path.basename(cwd) || '新会话'
+  const workspaceKey = encodeWorkspaceKey(cwd)
+  const sessionId = 'session-' + randomUUID()
+  const dir = path.join(String(homeDir), 'sessions', workspaceKey, sessionId)
+  fs.mkdirSync(dir, { recursive: true })
+  const frames = buildEmptySessionFrames({ sessionId, createdAt: now, cwd })
+  fs.writeFileSync(path.join(dir, SESSION_FILE), encodeSessionLog(frames))
+
+  const { file, doc } = readWorkspaceIndex(homeDir)
+  // 与 DSH 自身一致：workspaceId 由 workspace 路径稳定派生。
+  const workspaceId = 'ws-' + Buffer.from(workspaceKey).toString('hex').slice(0, 12)
+  const previous = doc.tables.workspaces[workspaceId]
+  const sessionIds = Array.isArray(previous?.sessionIds) ? previous.sessionIds.filter((id) => typeof id === 'string') : []
+  if (!sessionIds.includes(sessionId)) sessionIds.push(sessionId)
+  doc.tables.workspaces[workspaceId] = {
+    path: cwd,
+    title,
+    sessionIds,
+    createdAt: previous?.createdAt ?? new Date(now).toISOString(),
+    updatedAt: new Date(now).toISOString(),
+  }
+  if (!doc.global.workspaceIds.includes(workspaceId)) doc.global.workspaceIds.push(workspaceId)
+  if (!doc.global.defaultWorkspaceId) doc.global.defaultWorkspaceId = workspaceId
+  doc.global.initialized = true
+  writeWorkspaceIndex(file, doc)
+
+  return { ok: true, created: true, sessionId, workspaceKey }
+}
+
+/**
+ * Enforce the upper bound: keep the newest FORK_SESSION_MAX sessions, move the rest to
+ * quarantine-sessions/<stamp>/… (never delete). Branch sessions are exempt.
+ */
+export function enforceForkSessionCap(homeDir, { keepSessionIds = [], max = FORK_SESSION_MAX, now = Date.now() } = {}) {
+  const keep = new Set((Array.isArray(keepSessionIds) ? keepSessionIds : []).map(String))
+  const sessions = scanForkSessions(homeDir).filter((session) => !keep.has(session.sessionId))
+  const overflow = sessions.slice(Math.max(0, max))
+  if (overflow.length === 0) return { ok: true, kept: Math.min(sessions.length, max), quarantined: [] }
+  const stamp = new Date(now).toISOString().replace(/[:.]/g, '-')
+  const quarantined = []
+  for (const session of overflow) {
+    const target = path.join(String(homeDir), 'quarantine-sessions', stamp, session.workspaceKey, session.sessionId)
+    try {
+      fs.mkdirSync(path.dirname(target), { recursive: true })
+      fs.renameSync(path.dirname(session.file), target)
+      quarantined.push({ workspaceKey: session.workspaceKey, sessionId: session.sessionId, movedTo: target, at: now })
+    } catch { /* 移动失败则保留原地，不删除 */ }
+  }
+  return { ok: true, kept: Math.min(sessions.length, max), quarantined }
+}
+
+/** Feedback for the panel: how many sessions, and whether the cap is violated. */
+export function summarizeForkSessions(homeDir) {
+  const list = scanForkSessions(homeDir)
+  return {
+    count: list.length,
+    min: FORK_SESSION_MIN,
+    max: FORK_SESSION_MAX,
+    belowFloor: list.length < FORK_SESSION_MIN,
+    violation: list.length > FORK_SESSION_MAX,
+  }
+}

package/src/lib/fork-supervision-settings.mjs

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+//
+// fork-supervision-settings — 分身看护的持久化开关（UI 与 watchdog 共用）。
+//   <dataDir>/fork-supervision.json
+//   { version:1, autostartForks:boolean, supervise:boolean, updatedAt:number }
+//
+// autostartForks：watchdog 启动时是否请求 /api/forks/autostart
+// supervise     ：forker 是否在分身崩溃后按退避重启（运行时可切换）
+import fs from 'node:fs'
+import path from 'node:path'
+
+const DEFAULTS = Object.freeze({ autostartForks: true, supervise: false })
+const FILE_NAME = 'fork-supervision.json'
+
+export function supervisionSettingsFile(dataDir) {
+  return path.join(String(dataDir ?? ''), FILE_NAME)
+}
+
+function normalize(raw) {
+  return {
+    version: 1,
+    autostartForks: typeof raw?.autostartForks === 'boolean' ? raw.autostartForks : DEFAULTS.autostartForks,
+    supervise: typeof raw?.supervise === 'boolean' ? raw.supervise : DEFAULTS.supervise,
+    updatedAt: Number.isFinite(Number(raw?.updatedAt)) ? Number(raw.updatedAt) : 0,
+  }
+}
+
+export function readForkSupervisionSettings(dataDir) {
+  const file = supervisionSettingsFile(dataDir)
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8'))
+    return { ...normalize(raw), file, exists: true }
+  } catch {
+    return { ...normalize(null), file, exists: false }
+  }
+}
+
+export function writeForkSupervisionSettings(dataDir, patch = {}) {
+  const dir = String(dataDir ?? '')
+  if (!dir) return { ok: false, error: 'data-dir-required' }
+  const current = readForkSupervisionSettings(dir)
+  const next = normalize({
+    autostartForks: typeof patch.autostartForks === 'boolean' ? patch.autostartForks : current.autostartForks,
+    supervise: typeof patch.supervise === 'boolean' ? patch.supervise : current.supervise,
+    updatedAt: Date.now(),
+  })
+  try {
+    fs.mkdirSync(dir, { recursive: true })
+    const file = supervisionSettingsFile(dir)
+    const tmp = `${file}.tmp-${process.pid}`
+    fs.writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, 'utf8')
+    fs.renameSync(tmp, file)
+    return { ok: true, ...next, file }
+  } catch (error) {
+    return { ok: false, error: 'write-failed', detail: String(error?.message ?? error) }
+  }
+}

package/src/lib/fork-supervisor.mjs

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+// fork-supervisor — pure/codable pieces shared by fang-forker and its tests:
+// restart backoff, orphan reconciliation, per-fork meta.json, and a loopback health probe.
+// No process spawning here; the forker keeps that responsibility.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import http from 'node:http'
+
+export const SUPERVISION_DEFAULTS = Object.freeze({
+  maxRestarts: 3,
+  baseMs: 1000,
+  maxMs: 30000,
+  jitter: 0.2,
+  healthPath: '/',
+  healthTimeoutMs: 1500,
+})
+
+export const META_FILE = 'fang-meta.json'
+export const META_VERSION = 1
+
+/** Exponential backoff with jitter; deterministic when `random` is injected. */
+export function computeBackoff(attempt, options = {}) {
+  const baseMs = Math.max(1, Number(options.baseMs ?? SUPERVISION_DEFAULTS.baseMs) || SUPERVISION_DEFAULTS.baseMs)
+  const maxMs = Math.max(baseMs, Number(options.maxMs ?? SUPERVISION_DEFAULTS.maxMs) || SUPERVISION_DEFAULTS.maxMs)
+  const jitter = Math.min(0.9, Math.max(0, Number(options.jitter ?? SUPERVISION_DEFAULTS.jitter) || 0))
+  const random = typeof options.random === 'function' ? options.random : Math.random
+  const n = Math.max(0, Math.floor(Number(attempt) || 0))
+  const exp = Math.min(maxMs, baseMs * 2 ** n)
+  const delta = exp * jitter
+  return Math.max(0, Math.floor(exp + (random() * 2 - 1) * delta))
+}
+
+/**
+ * Decide what supervision does after an exit.
+ * Only crashes of a fork that had actually become ready are restarted; a failed first
+ * spawn is reported to the orchestrator instead of loop-spawning.
+ * @returns {{action:'restart'|'give-up'|'ignore', reason:string, attempt:number, delayMs:number}}
+ */
+export function planRestart(exitInfo, record = {}, policy = {}) {
+  const intentional = record.intentionalStop === true
+  const ready = record.ready === true
+  const kind = String(exitInfo?.kind ?? 'crash')
+  if (intentional) return { action: 'ignore', reason: 'intentional-stop', attempt: 0, delayMs: 0 }
+  if (!ready) return { action: 'give-up', reason: 'never-ready', attempt: 0, delayMs: 0 }
+  if (kind === 'normal') return { action: 'ignore', reason: 'normal-exit', attempt: 0, delayMs: 0 }
+  const maxRestarts = Math.max(0, Number(policy.maxRestarts ?? SUPERVISION_DEFAULTS.maxRestarts) || 0)
+  const attempt = Math.max(0, Number(record.restartCount ?? 0) || 0)
+  if (attempt >= maxRestarts) return { action: 'give-up', reason: 'max-restarts', attempt, delayMs: 0 }
+  return {
+    action: 'restart',
+    reason: kind === 'restart-request' ? 'restart-request' : 'crash',
+    attempt,
+    delayMs: computeBackoff(attempt, policy),
+  }
+}
+
+/** Reconcile persisted records: alive pids keep running; dead ones become crashed; foreign pids are flagged. */
+export function reconcileOrphans(records = [], isAlive = () => false) {
+  const updates = []
+  for (const rec of Array.isArray(records) ? records : []) {
+    const pid = Number(rec?.pid)
+    const liveStatus = ['provisioning', 'ready', 'running', 'starting'].includes(String(rec?.status ?? ''))
+    if (!liveStatus) continue
+    if (!Number.isInteger(pid) || pid <= 0) {
+      updates.push({ forkId: rec.forkId, action: 'mark-crashed', reason: 'no-pid' })
+      continue
+    }
+    if (isAlive(pid)) updates.push({ forkId: rec.forkId, action: 'keep', reason: 'pid-alive' })
+    else updates.push({ forkId: rec.forkId, action: 'mark-crashed', reason: 'pid-dead', pid })
+  }
+  return updates
+}
+
+export function metaPath(homeDir) {
+  return path.join(String(homeDir ?? ''), META_FILE)
+}
+
+/** Atomic per-fork meta (mode 0600). Never throws on read; write returns false on failure. */
+export function writeForkMeta(homeDir, meta) {
+  if (!homeDir) return false
+  const file = metaPath(homeDir)
+  const doc = { version: META_VERSION, at: new Date().toISOString(), ...meta }
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.writeFileSync(tmp, JSON.stringify(doc, null, 2), { mode: 0o600 })
+    fs.renameSync(tmp, file)
+    return true
+  } catch {
+    try { fs.unlinkSync(tmp) } catch { /* ignore */ }
+    return false
+  }
+}
+
+export function readForkMeta(homeDir) {
+  try {
+    const doc = JSON.parse(fs.readFileSync(metaPath(homeDir), 'utf8'))
+    return doc && typeof doc === 'object' ? doc : null
+  } catch {
+    return null
+  }
+}
+
+/** Loopback probe: any HTTP response means the process is listening (connection refused means not). */
+export function probeHttpAlive(port, options = {}) {
+  const n = Math.floor(Number(port))
+  if (!Number.isInteger(n) || n < 1 || n > 65535) return Promise.resolve(false)
+  const host = options.host ?? '127.0.0.1'
+  const pathName = options.path ?? SUPERVISION_DEFAULTS.healthPath
+  const timeoutMs = Math.max(50, Number(options.timeoutMs ?? SUPERVISION_DEFAULTS.healthTimeoutMs) || SUPERVISION_DEFAULTS.healthTimeoutMs)
+  return new Promise((resolve) => {
+    const req = http.request({ host, port: n, path: pathName, method: 'GET', timeout: timeoutMs }, (res) => {
+      res.resume()
+      resolve(true)
+    })
+    req.once('error', () => resolve(false))
+    req.once('timeout', () => { req.destroy(); resolve(false) })
+    req.end()
+  })
+}