focus-guard 0.0.0-stage → 3.0.7

package/src/adapters/dsh/eligibility-gate.mjs

@@ -0,0 +1,302 @@
+/**
+ * focus-guard 适配层 · 资格审核闸（3.0.5 第二步）
+ *
+ * 双入口闭环：
+ *   入口一 fg_apply（applyEligibility + FG_APPLY_TOOL_SPEC）：AI 提交目的/影响范围 → 审核 → 通过则按 session 授权
+ *   入口二 gateToolCall（pre-execute 调用）：高危工具无授权 → deny，理由指向 fg_apply
+ *
+ * 分层纪律：本文件属适配层，向母版注入 redlines / audit / model；母版不反向依赖本层。
+ * grants 是 FG 自己的状态（按 session 分表，内存版；第五步持久化到 FG 状态文件），不进 guard.mjs 的 state。
+ * 审计默认写 .focus-guard/AUDIT.log；FG_AUDIT_FILE 可重定向——自检**只写 tmpdir()**，绝不碰真实工作区。
+ */
+import { appendFileSync } from 'node:fs'
+import { checkEligibility, HIGH_RISK_TOOLS, SYSTEM_PATH_RE, profileScope, IRREVERSIBLE_IDS } from '../../core/checkEligibility.mjs'
+import { redlineExempt } from '../../core/redlines.mjs'
+import { loadProfile } from '../../core/profileLoader.mjs'
+import { createGrantTable } from '../../core/grants.mjs'
+import { AUDIT_FILE, appendAudit } from '../../dsh/audit.mjs'
+
+/** 对系统路径的写入类工具：与命令型高危同属"必须先申请"的门槛清单（显式成文）。 */
+export const GATED_WRITE_TOOLS = ['Write', 'Edit', 'MultiEdit', 'NotebookEdit']
+
+/**
+ * 判定本次调用是否属"必须先申请"的类别。
+ * @returns {string|null} 命中的门槛 id（rm-rf / format-volume / … / write-system-path），不属门槛则 null
+ */
+export function gatedReasonOf(tool, command = '') {
+  const cmd = String(command ?? '')
+  const hit = HIGH_RISK_TOOLS.find((r) => r.re.test(cmd))
+  if (hit) {
+    // 3.0.7（HANDOFF §十一 缺陷 3）：与红线层 / 母版 L2 同口径。
+    // HIGH_RISK_TOOLS 只做文本匹配，无法区分「要执行的命令」与「被引用的命令字符串」，
+    // 于是引号内的危险数据虽已被红线层与母版 L2 豁免，却仍进门槛清单被闸直接 deny——
+    // 三方口径不一致。此处对命令型条目先问一次上下文豁免：豁免成立则不进门槛清单，
+    // 交回原有判定链（pipeline 文本层 → 硬校验 → 本闸 → 语义预判），由下游按正常语义裁决。
+    // 豁免不成立（裸危险命令、执行外壳包装）时行为不变，仍按门槛拦。
+    if (redlineExempt(cmd, hit)) return null
+    return hit.id
+  }
+  const name = String(tool ?? '').toLowerCase()
+  // 注意：本支由 SYSTEM_PATH_RE 判定的**路径检查**，不是命令红线，不套命令豁免
+  //（豁免函数只对 HIGH_RISK_TOOLS 中的命令型条目有意义）。
+  if (GATED_WRITE_TOOLS.some((t) => t.toLowerCase() === name) && SYSTEM_PATH_RE.test(cmd)) return 'write-system-path'
+  return null
+}
+
+// —— FG 自己的授权状态：按 session 分表（内存；第五步持久化）——
+const TABLES = new Map()
+
+/** 该会话的授权表（不存在则建）。 */
+export function grantsFor(session) {
+  const key = String(session || 'dsh-native')
+  let table = TABLES.get(key)
+  if (!table) {
+    table = createGrantTable()
+    TABLES.set(key, table)
+  }
+  return table
+}
+
+/** 回收整张表（回合/任务结束；第五步由 ttl 计时自动调用）。 */
+export function resetGrants(session) {
+  return TABLES.delete(String(session || 'dsh-native'))
+}
+
+/**
+ * 资格审核审计（规格 §七 字段口径）。统一走 `appendAudit`——由它负责体积轮转，
+ * 并与 auditDeny / auditRedlineExempt 共用同一写入口径（2026-10-09 污染事故的教训）。写失败只 warn。
+ */
+export function auditEligibility(row) {
+  return appendAudit({ ts: new Date().toISOString(), ...row })
+}
+
+/**
+ * 入口一的核心：申请 → 审核 → 授权。
+ *
+ * 关键语义：fg_apply 本身是**申请通道**，所以审核期间先把该工具视为"已有授权"，让母版第 3 层
+ * 聚焦于"可否授予"（状态/红线/前置/语义），而不是被"无授权即需审批"挡在自己的入口上。
+ * 审核未通过时立即收回这一临时授权——被拒就绝不能放行。
+ *
+ * @returns {Promise<{decision:"allow"|"deny"|"needApproval", layer:string, reason:string, modelSignal:object|null, trace:Array}>}
+ */
+export async function applyEligibility({
+  session,
+  tool,
+  command = '',
+  purpose,
+  scope,
+  ttl = 'turn',
+  target,
+  state = {},
+  redlines = [],
+  model = null,
+  profile = null,
+  modelId,
+}) {
+  const grants = grantsFor(session)
+  const preGranted = grants.has(tool)
+  if (!preGranted) grants.grant(tool, { ttl, reason: 'fg_apply 审核中（临时）' })
+  // 3.0.6 补口（HANDOFF §十 缺陷 1）：画像必须透传到母版，否则真实 fg_apply 路径 profile=null，
+  // 画像对所有层失效——此前画像差异只在 decide() 那条路可达。
+  const resolved = profile ?? (modelId ? loadProfile(modelId) : null)
+  const result = await checkEligibility({
+    tool,
+    command,
+    purpose,
+    scope,
+    ttl,
+    target,
+    state,
+    redlines,
+    model,
+    profile: resolved,
+    grants,
+    audit: (row) => auditEligibility({ session, ...row }),
+  })
+  if (result.decision !== 'allow' && !preGranted) grants.revoke(tool)
+  return result
+}
+
+/**
+ * 入口二：pre-execute 的 grants 校验。
+ * @returns {{kind:"pass", granted?: boolean}} 不属门槛清单、或已有授权 → 交回原有判定链
+ *          {{kind:"deny", reason: string}} 属门槛且无授权 → 拦截
+ */
+export function gateToolCall({ session, tool, command = '', state, profile = null } = {}) {
+  const reason = gatedReasonOf(tool, command)
+  if (!reason) return { kind: 'pass' }
+  // 3.0.6（HANDOFF §十 缺陷 5）：与母版 L3 同源——审批层**不可被画像关闭**（只受 scope 约束），
+  // 否则会出现"decide 放行而闸拦截"或"闸放行而母版拦截"的路径分叉。
+  const scope = profileScope(profile)
+  if (scope === 'irreversible' && !IRREVERSIBLE_IDS.includes(reason)) {
+    return { kind: 'pass', outOfScope: true }
+  }
+  const grants = grantsFor(session)
+  if (grants.has(tool)) return { kind: 'pass', granted: true }
+  const detail = `该工具需先调 fg_apply 申请授权（命中 ${reason}）`
+  auditEligibility({
+    session,
+    action: 'deny',
+    tool,
+    command: String(command ?? '').slice(0, 120),
+    layer: 'gate',
+    decision: 'deny',
+    modelSignal: null,
+    evidence: detail,
+  })
+  return { kind: 'deny', reason: detail }
+}
+
+/**
+ * fg_apply 的工具注册规格。接线时套用装机 dsh-tools 的 defineTool 契约（name/description/parameters +
+ * 执行体），执行体只需 await applyEligibility(args) 并按 decision 渲染文案，无额外逻辑。
+ */
+export const FG_APPLY_TOOL_SPEC = {
+  name: 'fg_apply',
+  description:
+    '向 FocusGuard 申请高危工具的临时执行资格。执行高危命令（rm -rf / 格式化 / git push -f / 发布 / 全局安装 / 系统路径写入）之前必须先申请；purpose 与 scope 必填。通过后本会话内按 ttl 放行，被拒则不得执行。',
+  parameters: {
+    tool: { type: 'string', required: true, description: '目标工具名，如 Bash / Write / Edit' },
+    command: { type: 'string', required: true, description: '命令或操作描述' },
+    purpose: { type: 'string', required: true, description: '真实目的（必填，不得空白）' },
+    scope: { type: 'string', required: true, description: '影响范围（必填，不得空白）' },
+    ttl: { type: 'string', required: false, enum: ['turn', 'task', 'persist'], description: '授权有效期，默认 turn' },
+    target: { type: 'string', required: false, description: '目标路径（改动类可选，供第 4 层取证比对）' },
+  },
+}
+
+// ═══════════ 3.0.7 · 误伤申辩（司法救济通道）═══════════
+// 缺口背景（外部审计指出、并经逐字复核成立）：原体系只有"立法救济"（事后改规则），
+// 没有"司法救济"（个案当场申辩）。HANDOFF §八 的红线误伤即实证——被拦后AI无程序可走，
+// 只能绕过（[char]47 拼接）或等修法（3.0.6 上下文豁免），成本差两个数量级。
+// 本机制复用既有审批骨架：申辩 → {kind:"ask"} → 人类一次性裁决 → 留痕。
+// 注意：第八十三条(三) 原写"拦截申诉…仍走第十二章"，而第十二章是【反规避与纪律审查】（处罚章），
+// 属条文错配——本机制即为该错配补上的实体程序。
+
+/** 红线豁免凭据的授权键前缀：申辩获批后按 `redline:<名称>` 记账，供 pipeline 红线层查询。 */
+export const REDLINE_GRANT_PREFIX = 'redline:'
+
+/** 取会话标识（与 audit.mjs 的 auditDeny 口径一致）。 */
+function sessionOf(exec) {
+  return (exec && (exec.sessionId || (exec.agent && (exec.agent.sessionId || exec.agent.id)))) || 'dsh-native'
+}
+
+/**
+ * 查该红线是否已有"申辩获批"凭据（3.0.7）。
+ * pipeline 红线层在上下文豁免判据之外追加查这一道。
+ * @returns {Promise<boolean>}
+ */
+export async function hasRedlineGrant(exec, redlineName) {
+  if (!redlineName) return false
+  return grantsFor(sessionOf(exec)).has(`${REDLINE_GRANT_PREFIX}${redlineName}`)
+}
+
+/**
+ * 申辩入口（3.0.7）：把 fg_appeal 的这次调用转成 `{kind:"ask"}`，交 DSH approval seam 由人类裁决。
+ * 由 pipeline 在**所有闸之前**调用——申辩参数携带被拦命令原文，走后续闸会被同一规则再拦一次。
+ * @returns {Promise<{kind:"ask", reason:string}|{kind:"deny", reason:string}|null>}
+ */
+export async function appealAsk(exec, warn) {
+  const args = (exec && exec.arguments) || {}
+  const target = String(args.tool ?? '').trim()
+  const blocked = String(args.command ?? '')
+  const counterExample = String(args.counterExample ?? '').trim()
+  const reason = String(args.reason ?? '').trim()
+  const session = sessionOf(exec)
+
+  if (!target || !reason) {
+    const msg = '申辩表单不完整：tool 与 reason 必填；建议附 counterExample 反例锚点（文件:行号 或原文引用）'
+    auditEligibility({
+      session,
+      action: 'appeal-denied',
+      tool: target || '(missing)',
+      command: blocked.slice(0, 120),
+      layer: 'appeal',
+      decision: 'deny',
+      modelSignal: null,
+      evidence: msg,
+    })
+    if (typeof warn === 'function') warn('申辩表单不完整：', msg)
+    return { kind: 'deny', reason: `focus-guard-native: ${msg}` }
+  }
+
+  auditEligibility({
+    session,
+    action: 'appeal-filed',
+    tool: target,
+    command: blocked.slice(0, 120),
+    layer: 'appeal',
+    decision: 'needApproval',
+    modelSignal: null,
+    evidence: `反例锚点：${counterExample.slice(0, 200) || '(未提供)'} | 理由：${reason.slice(0, 200)}`,
+  })
+  if (typeof warn === 'function') warn('申辩已提交人类裁决：', `${target} ${blocked.slice(0, 80)}`)
+
+  return {
+    kind: 'ask',
+    reason:
+      `focus-guard-native:【误判申辩】\n` +
+      `工具：${target}\n` +
+      `被拦命令：${blocked.slice(0, 200) || '(未提供)'}\n` +
+      `反例锚点：${counterExample.slice(0, 300) || '(未提供)'}\n` +
+      `理由：${reason.slice(0, 300)}\n\n` +
+      `批准 → 为该工具开通一次授权（ttl=turn），并豁免本次命中的红线；拒绝 → 维持拦截。`,
+  }
+}
+
+/**
+ * 申辩获批后的授予（3.0.7）：由 fg_appeal 的执行体调用（人类批准后才轮到 execute 运行）。
+ * 同时记"工具授权"与"红线凭据"，使原被拦命令的下次调用能过红线层与资格闸。
+ */
+export async function grantFromAppeal({ session, tool, command = '' } = {}) {
+  const grants = grantsFor(session)
+  const entry = grants.grant(String(tool), {
+    ttl: 'turn',
+    reason: `申辩获批：${String(command).slice(0, 80)}`,
+  })
+  let redline = null
+  try {
+    // 路径相对本文件（src/adapters/dsh/）：上溯两级到 src/，再进 dsh/
+    const { ABSOLUTE_REDLINES } = await import('../../dsh/pipeline.mjs')
+    const hit = (ABSOLUTE_REDLINES || []).find((r) => r && r.re && r.re.test(String(command)))
+    if (hit) {
+      grants.grant(`${REDLINE_GRANT_PREFIX}${hit.name}`, { ttl: 'turn', reason: '申辩获批红线豁免' })
+      redline = hit.name
+    }
+  } catch (error) {
+    // 不静默：红线凭据拿不到时工具授权仍生效，但必须留痕（对齐 2.5.1「假留痕防线」）
+    console.warn(
+      '[focus-guard-native] 申辩红线凭据授予失败（工具授权仍生效）:',
+      (error && error.message) || error,
+    )
+    redline = null
+  }
+  auditEligibility({
+    session,
+    action: 'appeal-granted',
+    tool,
+    command: String(command).slice(0, 120),
+    layer: 'appeal',
+    decision: 'allow',
+    modelSignal: null,
+    evidence: `获批授权 ttl=${entry.ttl}${redline ? `；红线豁免：${redline}` : ''}`,
+  })
+  return { entry, redline }
+}
+
+/** fg_appeal 的工具注册规格（与 fg_apply 同构；执行体只在人类批准后运行）。 */
+export const FG_APPEAL_TOOL_SPEC = {
+  name: 'fg_appeal',
+  description:
+    '对被 FocusGuard 拦截的命令提出【误判申辩】。仅当认为拦截属误伤时使用（例如被引用的危险命令字符串被当成了要执行的命令）。须给出 reason，并尽量附 counterExample 反例锚点（文件:行号 或原文引用）。提交后由人类一次性裁决：批准则开通该工具一次授权并豁免对应红线，拒绝则维持拦截。',
+  parameters: {
+    tool: { type: 'string', required: true, description: '被拦的工具名，如 Bash / Write' },
+    command: { type: 'string', required: true, description: '被拦的命令或操作原文' },
+    reason: { type: 'string', required: true, description: '申辩理由（必填，不得空白）' },
+    counterExample: {
+      type: 'string',
+      required: false,
+      description: '反例锚点：证明该片段只是数据的证据，如 文件:行号 或原文引用',
+    },
+  },
+}

package/src/adapters/dsh/fg-appeal-tool.mjs

@@ -0,0 +1,47 @@
+/**
+ * focus-guard 适配层 · fg_appeal 工具注册（3.0.7 · 误伤申辩）
+ *
+ * 契约与 fg-apply-tool.mjs 相同：defineTool({ name, description, parameters, execute })。
+ * 执行体只在**人类批准申辩后**才运行——ask 由 pipeline 在 pre-execute 最先发起
+ * （原因是申辩参数携带被拦命令原文，若走后续闸会被同一规则再拦一次）。
+ * 所以 execute 的职责就是"授予"：开通该工具一次授权 + 豁免本次命中的红线。
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { FG_APPEAL_TOOL_SPEC, grantFromAppeal } from './eligibility-gate.mjs'
+
+export const name = 'focus-guard-fg-appeal'
+/** 依赖注入：注册到 ctx.tools 即可。 */
+export const inject = ['tools']
+
+/** 从 exec 取会话标识，口径与 audit.mjs 的 auditDeny 一致。 */
+function sessionOf(exec) {
+  return (exec && (exec.sessionId || (exec.agent && (exec.agent.sessionId || exec.agent.id)))) || 'dsh-native'
+}
+
+/** 生成 fg_appeal 的工具定义。 */
+export function buildFgAppealTool() {
+  return defineTool({
+    name: FG_APPEAL_TOOL_SPEC.name,
+    description: FG_APPEAL_TOOL_SPEC.description,
+    parameters: FG_APPEAL_TOOL_SPEC.parameters,
+    async execute(args, exec) {
+      const { entry, redline } = await grantFromAppeal({
+        session: sessionOf(exec),
+        tool: args.tool,
+        command: args.command ?? '',
+      })
+      return {
+        text:
+          `[申辩获批] ${args.tool} 已开通一次授权（ttl=${entry.ttl}）` +
+          (redline ? `，并豁免红线「${redline}」。` : '。') +
+          `\n现在可以执行原被拦命令；如需更多次数请重新申请。`,
+      }
+    },
+  })
+}
+
+/** Cordis 插件入口：把 fg_appeal 注册进 ctx.tools。 */
+export function apply(ctx, config) {
+  void config
+  ctx.tools.register(buildFgAppealTool())
+}

package/src/adapters/dsh/fg-apply-tool.mjs

@@ -0,0 +1,68 @@
+/**
+ * focus-guard 适配层 · fg_apply 工具注册（3.0.5 第二步·入口一）
+ *
+ * 契约来源：装机 dsh-tools 的 defineTool —— 字段为
+ *   defineTool({ name, description, parameters, output?, execute(args, exec), render?, presentCall? })
+ * 见 @deepseek-ai/dsh-tool-todo/lib/index.js:170 `execute(args, exec)`。
+ *
+ * 本文件只做薄壳：参数 → applyEligibility → 渲染文案。判定逻辑全在母版 checkEligibility，
+ * 授权表在 eligibility-gate 的 grantsFor（FG 自己的状态，不进 guard.mjs 的 state）。
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { applyEligibility, FG_APPLY_TOOL_SPEC, auditEligibility } from './eligibility-gate.mjs'
+import { ABSOLUTE_REDLINES } from '../dsh/pipeline.mjs'
+
+export const name = 'focus-guard-fg-apply'
+/** 依赖注入：注册到 ctx.tools 即可，无需其它服务。 */
+export const inject = ['tools']
+
+/** 从 exec 取会话标识，口径与 audit.mjs 的 auditDeny 一致。 */
+function sessionOf(exec) {
+  return (
+    (exec && (exec.sessionId || (exec.agent && (exec.agent.sessionId || exec.agent.id)))) || 'dsh-native'
+  )
+}
+
+/** 把审核结论渲染成模型可读文案。 */
+export function renderDecision(result, spec) {
+  const layers = result.trace.map((s) => `L${s.layer}:${s.decision}`).join(' → ')
+  if (result.decision === 'allow') {
+    return `[资格审核·通过] ${spec.tool} 已获授权（ttl=${spec.ttl ?? 'turn'}）。理由：${result.reason}\n层序：${layers}\n现在可以执行：${String(spec.command ?? '').slice(0, 120)}`
+  }
+  if (result.decision === 'needApproval') {
+    return `[资格审核·需人类审批] ${result.reason}\n层序：${layers}\n请向人类说明目的与影响范围后再执行；未经批准不得执行。`
+  }
+  return `[资格审核·拒绝] ${result.reason}\n层序：${layers}\n不得执行该命令；如需继续，先修正申请（目的/影响范围）或改用合规替代方案。`
+}
+
+/**
+ * 生成 fg_apply 的工具定义。redlines 注入而非内部 import，保持"母版/适配层不反向依赖"的可测性。
+ */
+export function buildFgApplyTool({ redlines = ABSOLUTE_REDLINES } = {}) {
+  return defineTool({
+    name: FG_APPLY_TOOL_SPEC.name,
+    description: FG_APPLY_TOOL_SPEC.description,
+    parameters: FG_APPLY_TOOL_SPEC.parameters,
+    async execute(args, exec) {
+      const session = sessionOf(exec)
+      const spec = {
+        tool: args.tool,
+        command: args.command ?? '',
+        purpose: args.purpose,
+        scope: args.scope,
+        ttl: args.ttl ?? 'turn',
+        target: args.target,
+      }
+      const result = await applyEligibility({ session, ...spec, redlines, model: null })
+      return { text: renderDecision(result, spec) }
+    },
+  })
+}
+
+/** Cordis 插件入口：把 fg_apply 注册进 ctx.tools。 */
+export function apply(ctx, config) {
+  void config
+  ctx.tools.register(buildFgApplyTool())
+}
+
+export { auditEligibility }

package/src/adapters/dsh/protocol.mjs

@@ -0,0 +1,42 @@
+// FocusGuard 适配层 · DSH hook 协议（v3.0.5；《资料与代码分层总规范》二·2）
+// stdin 载荷解析、会话 ID 提取、项目根定位。harness 专有环境变量只出现在本层。
+import {
+  readFileSync, writeFileSync, rmSync, statSync, appendFileSync,
+  mkdirSync, existsSync, renameSync, realpathSync, readdirSync, copyFileSync,
+} from "node:fs";
+import { join, dirname, sep, basename, relative } from "node:path";
+import { tmpdir } from "node:os";
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+
+export function readStdinJson() {
+  try {
+    const raw = readFileSync(0, "utf8");
+    return raw.trim() ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+export function sessionId(input) {
+  const id =
+    input.session_id ||
+    process.env.CLAUDE_SESSION_ID ||
+    process.env.ZCODE_SESSION_ID ||
+    "default";
+  const raw = String(id);
+  const safe = raw.replace(/[^A-Za-z0-9._-]/g, "_");
+  // 2.5.2：消毒会撞名（proj/a 与 proj_a → 同一状态文件，熔断/审批/预算跨会话串味）。
+  // 仅当发生替换时追加短哈希；正常 id 保持原样，不影响既有状态文件。
+  return safe === raw ? safe : safe + "-" + createHash("sha256").update(raw).digest("hex").slice(0, 8);
+}
+
+export function projectDir() {
+  const d = process.env.ZCODE_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || "";
+  if (!d) return null;
+  try {
+    return statSync(d).isDirectory() ? d : null;
+  } catch {
+    return null;
+  }
+}

package/src/core/approval.mjs

@@ -0,0 +1,64 @@
+// FocusGuard 母版层 · 高危审批状态机（v3.0.5；《资料与代码分层总规范》二·1）
+// 待批队列、批量出示、批示消费与目标绑定、阶梯提示。
+import {
+  readFileSync, writeFileSync, rmSync, statSync, appendFileSync,
+  mkdirSync, existsSync, renameSync, realpathSync, readdirSync, copyFileSync,
+} from "node:fs";
+import { join, dirname, sep, basename, relative } from "node:path";
+import { tmpdir } from "node:os";
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { HIGH_RISK_QUEUE_MAX } from "./constants.mjs";
+
+export function pushHighRiskPending(state, key, cmdBrief) {
+  if (!key) return;
+  state.highRiskQueue = state.highRiskQueue || [];
+  if (state.highRiskQueue.some((x) => x.k === key)) return;
+  if (state.highRiskQueue.length >= HIGH_RISK_QUEUE_MAX) return;
+  state.highRiskQueue.push({ k: key, c: String(cmdBrief || "").slice(0, 80) });
+}
+// 待批队列注记：除当前命令外还有几条在队列里，提示可合并批示
+export function queueNote(state, currentBrief) {
+  const q = (state.highRiskQueue || []).filter((x) => x.c !== currentBrief);
+  if (q.length < 1) return "";
+  return `另有 ${q.length} 条待批已合并出示：${q.map((x) => x.c).join("；")}。回复 y 放行全部待批（各一次）、n 全部阻断。`;
+}
+// 授权消费（单条与批量统一）：命中即消费一次，且两槽同时清除——否则批量 y 放行的命令
+// 会在单条槽消费后仍留在批量槽里，同一命令被无声放行两次（一次性语义被破坏）
+export function consumeHighRisk(state, key) {
+  // 3.0.5 目标绑定：批示 y 后该目标键本会话内持续有效——同目标重复触达不再重复弹单
+  // （修"一次一 attempt 消费制"被程序性拒绝烧掉批准、同目标反复弹单之痛，《审 2 号》同源）。
+  // 每次命中仍逐一记档 high-risk-executed；n 批示即解除绑定；键为全量哈希，命令变体不受豁免。
+  if (state.highRiskApprovedKeys && state.highRiskApprovedKeys[key]) {
+    // 绑定命中：同步清空单条槽，保持"绑定映射"为唯一授权事实源
+    state.highRiskOk = false;
+    state.highRiskCmd = "";
+    state.highRiskKey = "";
+    return "bound";
+  }
+  let hit = false;
+  if (state.highRiskOk && state.highRiskKey === key) {
+    state.highRiskOk = false;
+    state.highRiskCmd = "";
+    state.highRiskKey = "";
+    hit = true;
+  }
+  const batch = state.highRiskBatch || [];
+  const i = batch.indexOf(key);
+  if (i >= 0) {
+    batch.splice(i, 1);
+    state.highRiskBatch = batch;
+    hit = true;
+  }
+  return hit;
+}
+
+export function ladderNote(level) {
+  if (level >= 6) return "L6：已上报人类。";
+  if (level >= 5) return "L5：只读模式直至批示。";
+  if (level >= 4) return "L4：已记档。";
+  if (level >= 3) return "L3：等批示或降级方案。";
+  if (level >= 2) return "L2：下一调用必须取证。";
+  return "";
+}
+

package/src/core/audit.mjs

@@ -0,0 +1,71 @@
+// FocusGuard 母版层 · 审计与因果链（v3.0.5；《资料与代码分层总规范》二·1）
+// AUDIT.log 写入、seq/chain/ref 因果链上下文、假留痕防线（写失败一律上 stderr）。
+import {
+  readFileSync, writeFileSync, rmSync, statSync, appendFileSync,
+  mkdirSync, existsSync, renameSync, realpathSync, readdirSync, copyFileSync,
+} from "node:fs";
+import { join, dirname, sep, basename, relative } from "node:path";
+import { tmpdir } from "node:os";
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+
+export let auditFile = null;
+export function auditTarget(sid) {
+  if (auditFile !== null) return auditFile;
+  // 2026-10-18 修（REPORT-2026-10-12 P1「审计单一入口未收敛」）：
+  // 显式 FG_AUDIT_FILE 优先级最高。此前这里只认 ZCODE/CLAUDE 项目目录，于是
+  // 测试把 FG_AUDIT_FILE 指向 tmpdir 时，走核心 audit() 的那条路（risk.mjs penalize()）
+  // 仍然写真实 AUDIT.log —— 隔离形同虚设，CHANGELOG 的"零增长"实测不成立。
+  const explicit = process.env.FG_AUDIT_FILE;
+  if (explicit) {
+    auditFile = explicit;
+    return auditFile;
+  }
+  const dir = process.env.ZCODE_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || "";
+  if (dir) {
+    try {
+      if (statSync(dir).isDirectory()) auditFile = join(dir, ".focus-guard", "AUDIT.log");
+    } catch {}
+  }
+  if (!auditFile) auditFile = join(tmpdir(), `focus-guard-${sid}-AUDIT.log`);
+  return auditFile;
+}
+
+// 3.0.0 因果链：auditCtx 随每次钩子调用初始化；seq=时间戳36进制.调用内序号（全局唯一），
+// chain=任务链（reset 起算，子代理委派派生 /dN 子链），ref=父事件 seq——流水账由此可渲染为因果图。
+export let auditCtx = { chain: null, base: 0 };
+export function auditChainInit(state) {
+  auditCtx = { chain: (state && state.taskChain) || null, base: 0 };
+}
+export function audit(sid, trigger, opts = {}) {
+  const seq = Date.now().toString(36) + "." + ++auditCtx.base;
+  const record = JSON.stringify({
+    ts: new Date().toISOString(),
+    session: sid,
+    seq,
+    chain: opts.chain !== undefined ? opts.chain : auditCtx.chain,
+    ref: opts.ref || null,
+    action: opts.action || trigger,
+    trigger: opts.trigger ?? trigger,
+    level: opts.level ?? null,
+    evidence: String(opts.evidence || "").slice(0, 200),
+    pardon: !!opts.pardon,
+  }) + "\n";
+  // 2.5.1 假留痕防线：工作区写失败 → 回退系统临时目录；仍失败 → stderr 一行可见，绝不无声丢执法记录
+  for (const p of [auditTarget(sid), join(tmpdir(), `focus-guard-${sid}-AUDIT.log`)]) {
+    try {
+      mkdirSync(dirname(p), { recursive: true });
+      appendFileSync(p, record);
+      return seq;
+    } catch {}
+  }
+  noteFail(sid, "AUDIT.log（工作区与临时目录均写入失败）");
+  return seq;
+}
+
+export function noteFail(sid, what) {
+  try {
+    process.stderr.write(`[留痕告急]${what}，会话 ${sid} 的本次记录未落盘。\n`);
+  } catch {}
+}
+

package/src/core/backup.mjs

@@ -0,0 +1,55 @@
+// FocusGuard 母版层 · 改动前备份（v3.0.5；《资料与代码分层总规范》二·1）
+// .ai/backup/ 物理回滚副本，保留最近 BACKUP_KEEP 份；敏感文件不落明文。项目根由参数传入。
+import {
+  readFileSync, writeFileSync, rmSync, statSync, appendFileSync,
+  mkdirSync, existsSync, renameSync, realpathSync, readdirSync, copyFileSync,
+} from "node:fs";
+import { join, dirname, sep, basename, relative } from "node:path";
+import { tmpdir } from "node:os";
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { SHA_LIMIT, BACKUP_KEEP, SECRET_FILE_RE } from "./constants.mjs";
+import { normalize } from "./state.mjs";
+import { audit, noteFail } from "./audit.mjs";
+import { sid } from "./session.mjs";
+
+export let backupSeq = 0; // 2.5.2：备份文件名加进程号+自增序号，避免同一毫秒内两次备份互相覆盖
+// ============ 2.2.0 正面指引（一.2）：改动前自动备份 ============
+// 回滚按环境自动选：有 .git → git restore；没有 → 本函数产出的 .ai/backup/ 物理副本覆盖还原。
+// 备份改动前的现状，保留最近 BACKUP_KEEP 份（超出淘汰最旧）。>200KB 的文件有意跳过（避免拖慢大写入，
+// README 已注明此上限）；失败不阻断执法，但一律上 stderr——静默会让 AI 误以为存在可回滚副本（2.5.1 假留痕防线）。
+export function backupBeforeEdit(absPath, projDir) {
+  try {
+    const dir = projDir;
+    if (!dir) return;
+    const st = statSync(absPath);
+    if (!st.isFile() || st.size > SHA_LIMIT) return;
+    const rel = relative(dir, absPath);
+    if (!rel || rel.startsWith("..")) return;
+    // 2.5.2 敏感文件不落明文副本：.env/私钥/凭据一旦复制进 .ai/backup/，等于在工作区里多留若干份明文密钥。
+    // 跳过备份并留痕 + 明确告知，避免 AI 误以为存在可回滚副本。
+    if (SECRET_FILE_RE.test(normalize(absPath))) {
+      audit(sid, "backup-skip-secret", { level: null, evidence: `敏感文件不落明文副本 ${rel}（回滚请用版本控制）` });
+      process.stderr.write(`[备份跳过]${rel} 属敏感文件，不复制明文副本；回滚请用版本控制。\n`);
+      return;
+    }
+    const root = join(dir, ".ai", "backup");
+    const dest = join(root, rel + "." + Date.now().toString(36) + process.pid.toString(36) + (backupSeq++).toString(36) + ".bak");
+    mkdirSync(dirname(dest), { recursive: true });
+    copyFileSync(absPath, dest);
+    const all = [];
+    (function walk(d) {
+      for (const e of readdirSync(d, { withFileTypes: true })) {
+        const p = join(d, e.name);
+        if (e.isDirectory()) walk(p);
+        else all.push([p, statSync(p).mtimeMs]);
+      }
+    })(root);
+    if (all.length > BACKUP_KEEP) {
+      all.sort((a, b) => a[1] - b[1]);
+      for (let i = 0; i < all.length - BACKUP_KEEP; i++) rmSync(all[i][0], { force: true });
+    }
+  } catch {
+    noteFail(sid, `改动前备份 ${absPath}（无副本可回滚，改动仍会放行）`);
+  }
+}