@twinsearth/fang-dsh-plugin 3.3.4 → 3.3.5

package/docs/APPROVAL-DRILL.md

@@ -0,0 +1,42 @@
+# 审批 / 提升 / 回滚 drill
+
+生效版本：`v3.3.5`
+
+## 目的
+
+证明 Approver 不只是“已加载”，而是能真实执行：
+
+```text
+requestPromotion(red) → pending → decide(approved) → snapshot → 修改文件 → rollback
+```
+
+## 两种执行方式
+
+### 1. 本机隔离 drill（不碰生产）
+
+```bash
+node tools/approval-drill.mjs
+node tools/approval-drill.mjs --json
+```
+
+- 使用临时 `dataRoot`；不写生产 fang 数据目录；
+- 真实创建红票、真实 `decide`、真实 A 代快照与 digest 校验回滚；
+- 结束清理临时目录，`residue=clean`。
+
+### 2. 运行宿主上的隔离 drill（需 v3.3.5）
+
+```bash
+node tools/fangctl.mjs approvals drill --url http://127.0.0.1:<port>
+```
+
+调用 `POST /fang/api/approvals/drill`；同样在临时 `dataRoot` 执行，不影响生产审批队列。
+
+## /approvals 修复
+
+- 只聚合 `status=ready|running` 的分身；
+- 失败/停止/回收的分身归入 `skipped`，不再把整个收件箱标成 degraded；
+- 真正活跃分身 adapter 失败才记 `failed`。
+
+## 边界
+
+drill 证明的是 Approver 的审批/快照/回滚链路；生产“提升插件”仍需真实合法分身插件并走 Scorer/Router。drill 不会写入 `promoted/`，也不会改 profile。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/fang-dsh-plugin",
-  "version": "3.3.4",
+  "version": "3.3.5",
   "private": false,
   "type": "module",
   "description": "dsh-Fang (瓮城) — mother/fork plugin development environment for DeepSeek Harness: one readonly mother, a disposable child dsh-Web per task.",

package/src/kernel/types.mjs

@@ -131,7 +131,7 @@ export const AUDIT = {
   RUNTIME_ERROR: 'runtime-error',
 }
 
-export const FANG_VERSION = '3.3.4'
+export const FANG_VERSION = '3.3.5'
 
 /**
  * @typedef {object} ForkInfo

package/src/lib/approval-drill.mjs

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+//
+// approval-drill — 在隔离的临时 dataRoot 里真实执行一次“提升审批”闭环：
+//   requestPromotion(red) → pending → decide(approved) → snapshot → 改动文件 → rollback
+// 不触碰生产 dataDir、不加载真实插件、不写 profile；用于证明审批/快照/回滚链路可执行。
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import { apply as applyApprover } from '../plugins/approver.mjs'
+
+/**
+ * @returns {{
+ *   ok:boolean, request:{id:string,kind:string,risk:string,outcome:string},
+ *   pendingBefore:number, pendingAfter:number, snapshot:object, rollback:object,
+ *   restored:boolean, target:string, dataRoot:string, cleanup:boolean
+ * }}
+ */
+export async function runApprovalDrill() {
+  const dataRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'fang-approval-drill-'))
+  const target = path.join(dataRoot, 'target')
+  fs.mkdirSync(target, { recursive: true })
+  fs.writeFileSync(path.join(target, 'plugin.mjs'), 'export const version = 1\n', 'utf8')
+
+  const services = new Map()
+  const disposers = []
+  const ctx = {
+    effect(fn) {
+      const dispose = fn()
+      if (typeof dispose === 'function') disposers.push(dispose)
+      return () => { try { dispose?.() } catch { /* ignore */ } }
+    },
+    provide(key, value) { services.set(key, value); return () => services.delete(key) },
+    get(key) { return services.get(key) },
+    logger: { info() {}, warn() {}, debug() {}, error() {} },
+  }
+
+  let approver = null
+  let requestPromise = null
+  try {
+    applyApprover(ctx, {
+      dataRoot,
+      defaultTtlMs: 10000,
+      authMode: 'manual',
+      strictRedLine: true,
+      snapshotGenerations: 3,
+    })
+    approver = services.get('fangApprover')
+    if (!approver || typeof approver.requestPromotion !== 'function') {
+      return { ok: false, error: 'approver-service-missing', dataRoot, cleanup: false }
+    }
+
+    requestPromise = approver.requestPromotion({
+      pluginId: 'approval-drill',
+      taskId: 'approval-drill',
+      detail: '隔离审批 drill：验证 request→decide→snapshot→rollback',
+      ttlMs: 10000,
+    })
+    // request() 同步入队；让出一次事件循环以确保 pending 可见。
+    await new Promise((resolve) => setImmediate(resolve))
+    const pendingBefore = approver.pending()
+    if (pendingBefore.length !== 1) {
+      return { ok: false, error: 'request-not-pending', pendingBefore: pendingBefore.length, dataRoot, cleanup: false }
+    }
+    const id = String(pendingBefore[0].id)
+    const decided = approver.decide(id, 'approved', { by: 'approval-drill', note: 'isolated drill' })
+    const outcome = await requestPromise
+    const pendingAfter = approver.pending().length
+    requestPromise = null
+
+    const snapshot = await approver.snapshot({ tag: 'approval-drill', dir: target })
+    fs.writeFileSync(path.join(target, 'plugin.mjs'), 'export const version = 2\n', 'utf8')
+    const rollback = await approver.rollback({ tag: 'approval-drill', dir: target })
+    const restored = fs.readFileSync(path.join(target, 'plugin.mjs'), 'utf8') === 'export const version = 1\n'
+
+    return {
+      ok: outcome?.outcome === 'approved' && decided?.ok === true && snapshot?.ok !== false && rollback?.ok === true && restored && pendingAfter === 0,
+      request: { id, kind: 'promotion', risk: 'red', outcome: String(outcome?.outcome ?? '') },
+      decided,
+      pendingBefore: pendingBefore.length,
+      pendingAfter,
+      snapshot,
+      rollback,
+      restored,
+      target,
+      dataRoot,
+      cleanup: false,
+    }
+  } finally {
+    // 未决请求不能被遗留在计时器里：显式拒绝/超时结算。
+    if (requestPromise) {
+      const pending = approver?.pending?.() ?? []
+      for (const item of pending) {
+        try { approver.decide(item.id, 'denied', { by: 'approval-drill-cleanup' }) } catch { /* ignore */ }
+      }
+      await requestPromise.catch(() => {})
+    }
+    for (const dispose of disposers.reverse()) { try { dispose() } catch { /* ignore */ } }
+  }
+}
+
+/** 删除 drill 的临时目录；返回是否已不存在。 */
+export function cleanupApprovalDrill(result) {
+  const dir = String(result?.dataRoot ?? '')
+  if (!dir) return true
+  try { fs.rmSync(dir, { recursive: true, force: true }) } catch { /* ignore */ }
+  return !fs.existsSync(dir)
+}
+
+export const _internals = { runApprovalDrill, cleanupApprovalDrill }

package/src/lib/main-gate.mjs

@@ -36,6 +36,8 @@ const REQUIRED_SOURCE_FILES = Object.freeze([
   'src/lib/fork-supervisor.mjs',
   'src/lib/restart-contract.mjs',
   'src/lib/main-gate.mjs',
+  'src/lib/approval-drill.mjs',
+  'tools/approval-drill.mjs',
   'src/plugins/restart-guard.mjs',
   'src/plugins/scorer.mjs',
   'src/plugins/approver.mjs',
@@ -49,6 +51,7 @@ const REQUIRED_SOURCE_FILES = Object.freeze([
   'docs/DSH-ARCHITECTURE-MAP.md',
   'docs/OVERLAY-MASTER-SWITCH.md',
   'docs/PACKAGE-RENAME-v3.3.3.md',
+  'docs/APPROVAL-DRILL.md',
 ])
 
 const REQUIRED_ARTIFACT_FILES = Object.freeze([

package/src/plugins/orchestrator.mjs

@@ -22,6 +22,7 @@ import {
 import { parseWorkspaceIndex, scanSessionDirs, readBoundedEvents, extractSessionTitle, encodeWorkspaceKey } from '../lib/session-format.mjs'
 import { ensureEssenceRuntimePnpmConfig, readNodeLinker } from '../lib/pnpm-store.mjs'
 import { captureRuntimeProfileIntoEssence } from '../lib/runtime-capture.mjs'
+import { cleanupApprovalDrill, runApprovalDrill } from '../lib/approval-drill.mjs'
 import { negotiateProtocol } from '../lib/adapter-protocol.mjs'
 import { describeMotherLink, probeLink, readSharedProfileSummary } from '../lib/mother-link.mjs'
 import { MirrorManager } from '../lib/mirror.mjs'
@@ -106,6 +107,15 @@ function forkBundlePath(profileDir) {
 export const name = 'fang-orchestrator'
 export const inject = []
 
+/**
+ * v3.3.5: a fork participates in the mother's approval aggregation only while it
+ * is actually alive. Failed/stopped/reaped forks are offline state, not approval
+ * failures; they must not turn the inbox `degraded`.
+ */
+export function isLiveForkForApprovals(_task, status) {
+  return status === TASK_STATUS.READY || status === TASK_STATUS.RUNNING
+}
+
 export const Config = z.object({
   role: z.union([z.const('mother'), z.const('fork')]).default('mother')
     .description('配置层角色；环境 DSH_FANG_ROLE 优先（forker 派生的分身自动为 fork）'),
@@ -3173,8 +3183,15 @@ export function apply(ctx, config) {
           failed.push({ taskId: null, error: String(error?.message ?? error) })
         }
 
-        const forkResults = await Promise.all([...tasks.values()]
-          .filter((task) => task?.url)
+        // v3.3.5: only live forks are aggregated. A dead/stopped fork is an
+        // expected offline state, not an approval failure; keep it in `skipped`
+        // so the panel can show it without marking the whole inbox degraded.
+        const forkTasks = [...tasks.values()].filter((task) => task?.url)
+        const liveForkTasks = forkTasks.filter((task) => isLiveForkForApprovals(task, taskView(task).status))
+        const skipped = forkTasks
+          .filter((task) => !liveForkTasks.includes(task))
+          .map((task) => ({ taskId: task.taskId, status: taskView(task).status, reason: 'fork-offline' }))
+        const forkResults = await Promise.all(liveForkTasks
           .map(async (task) => {
             if (task.adapter && task.adapter.ok === false) {
               return { task, ok: false, error: task.adapter.error ?? 'adapter-unavailable' }
@@ -3212,7 +3229,31 @@ export function apply(ctx, config) {
           }
         }
         items.sort((a, b) => (Number(a.deadlineAt) || Number.MAX_SAFE_INTEGER) - (Number(b.deadlineAt) || Number.MAX_SAFE_INTEGER))
-        return json(res, 200, { ok: true, degraded: failed.length > 0, items, failed })
+        return json(res, 200, { ok: true, degraded: failed.length > 0, items, failed, skipped })
+      })
+
+      // v3.3.5: isolated approval drill. Runs the real approver request → decide →
+      // snapshot → rollback path in a temp dataRoot; never touches production data.
+      // This gives a live host a way to prove the approval chain executes.
+      route('POST', `${prefix}/api/approvals/drill`, async (req, res) => {
+        try {
+          const out = await runApprovalDrill()
+          const cleanup = cleanupApprovalDrill(out)
+          return json(res, out.ok && cleanup ? 200 : 500, {
+            ok: out.ok && cleanup,
+            drill: {
+              request: out.request ?? null,
+              pendingBefore: out.pendingBefore ?? null,
+              pendingAfter: out.pendingAfter ?? null,
+              snapshot: out.snapshot ? { ok: out.snapshot.ok !== false, tag: out.snapshot.tag ?? null } : null,
+              rollback: out.rollback ? { ok: out.rollback.ok === true, restored: out.restored === true } : null,
+              cleanup,
+            },
+            error: out.error ?? null,
+          })
+        } catch (error) {
+          return json(res, 500, { ok: false, error: 'approval-drill-failed', detail: String(error?.message ?? error) })
+        }
       })
 
       // Decide one approval by source. The response is the real adapter/approver result;

package/tools/approval-drill.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// tools/approval-drill.mjs — 隔离审批 drill：真实 request→decide→snapshot→rollback。
+// 用法：node tools/approval-drill.mjs [--json]
+import { cleanupApprovalDrill, runApprovalDrill } from '../src/lib/approval-drill.mjs'
+
+const json = process.argv.slice(2).includes('--json')
+const result = await runApprovalDrill()
+const cleanup = cleanupApprovalDrill(result)
+result.cleanup = cleanup
+if (json) console.log(JSON.stringify(result, null, 2))
+else {
+  console.log(`${result.ok ? 'GREEN' : 'RED'}  approval drill`)
+  console.log(`  request   : ${result.request?.id ?? '-'} kind=${result.request?.kind ?? '-'} risk=${result.request?.risk ?? '-'} outcome=${result.request?.outcome ?? '-'}`)
+  console.log(`  pending   : before=${result.pendingBefore ?? '-'} after=${result.pendingAfter ?? '-'}`)
+  console.log(`  snapshot  : ${result.snapshot?.ok === false ? 'FAIL' : 'ok'}`)
+  console.log(`  rollback  : ${result.rollback?.ok === true ? 'ok' : 'FAIL'} restored=${result.restored === true}`)
+  console.log(`  residue   : ${cleanup ? 'clean' : 'kept ' + (result.dataRoot ?? '')}`)
+  if (result.error) console.log(`  error     : ${result.error}`)
+}
+process.exitCode = result.ok && cleanup ? 0 : 1

package/tools/fangctl.mjs

@@ -387,7 +387,24 @@ switch (cmd) {
   case 'tail': code = cmdTail(layout, Number(args._[1] ?? 20)); break
   case 'doctor': code = cmdDoctor(layout); break
   case 'approvals': {
-    try { code = await cmdApprovals(args) } catch (error) { console.error(String(error?.message ?? error)); code = 1 }
+    try {
+      if (args._[1] === 'drill') {
+        const out = await approvalRequest(args, '/fang/api/approvals/drill', { method: 'POST', body: {} })
+        if (args.json) console.log(JSON.stringify(out.body, null, 2))
+        else if (out.status === 200 && out.body?.ok) {
+          console.log('approval drill: GREEN')
+          console.log(`  request   : ${out.body.drill?.request?.id ?? '-'} ${out.body.drill?.request?.kind ?? '-'}/${out.body.drill?.request?.risk ?? '-'} → ${out.body.drill?.request?.outcome ?? '-'}`)
+          console.log(`  pending   : ${out.body.drill?.pendingBefore ?? '-'} → ${out.body.drill?.pendingAfter ?? '-'}`)
+          console.log(`  rollback  : ${out.body.drill?.rollback?.ok === true ? 'ok' : 'FAIL'} restored=${out.body.drill?.rollback?.restored === true}`)
+          console.log(`  residue   : ${out.body.drill?.cleanup === true ? 'clean' : 'kept'}`)
+        } else {
+          console.error(`FAIL approval drill: HTTP ${out.status} ${out.text.slice(0, 300)}`)
+        }
+        code = out.status === 200 && out.body?.ok === true ? 0 : 1
+        break
+      }
+      code = await cmdApprovals(args)
+    } catch (error) { console.error(String(error?.message ?? error)); code = 1 }
     break
   }
   case 'approve':
@@ -402,7 +419,7 @@ switch (cmd) {
     break
   }
   default:
-    console.log('usage: fangctl.mjs <status|forks|verify|tail [n]|doctor|restart-status [limit]|restart-safe [status|clear]|parse-url <line>|approvals|approve <source:id>|deny <source:id>> [--profile name] [--data-root dir] [--url url] [--token token] [--note text] [--by who] [--json]')
+    console.log('usage: fangctl.mjs <status|forks|verify|tail [n]|doctor|restart-status [limit]|restart-safe [status|clear]|parse-url <line>|approvals [drill]|approve <source:id>|deny <source:id>> [--profile name] [--data-root dir] [--url url] [--token token] [--note text] [--by who] [--json]')
     code = 64
 }
 process.exitCode = code