focus-guard 0.0.0-stage → 3.0.7

package/src/core/state.mjs

@@ -0,0 +1,265 @@
+// FocusGuard 母版层 · 状态与卷宗（v3.0.5；《资料与代码分层自规范》二·1）
+// 会话状态读写与陈旧清扫；卷宗【三】取证记录与 TTL 自适应；文件指纹与 git 脏检。
+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 { BUDGET_DEFAULT, INV_POOL_DEFAULT, SHA_LIMIT, CASE_MAX_ROWS, TTL_FIRST, TTL_RECENT, TTL_WEEK, TTL_STABLE, DELEGATE_DEFAULT, CASE_TEMPLATE } from "./constants.mjs";
+import { noteFail, audit } from "./audit.mjs";
+import { sid } from "./session.mjs";
+
+export function statePath(id) {
+  return join(tmpdir(), `focus-guard-${id}.json`);
+}
+
+export function loadState(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    // 2.5.2：文件在但解析失败 = 熔断/已否决命令/审批标记全部清零，属"状态层面的假留痕"，
+    // 必须让人类看见（与 2.5.1 的留痕防线同源）。首次运行无文件属正常，不告警。
+    if (existsSync(path)) noteFail(sid, "会话状态损坏（已按默认值继续：熔断、已否决命令、审批标记全部丢失）");
+    return {
+      turnCount: 0,
+      fused: false,
+      stopBlocked: false,
+      dumpCount: 0,
+      mercy: false,
+      violations: 0,
+      forcedInvestigate: false,
+      probation: false,
+      writeOps: 0,
+      readSet: {},
+      turnPrompt: "",
+      taskBudget: BUDGET_DEFAULT,
+      declaredBudget: 0,
+      effectiveCalls: 0,
+      ineffCalls: 0,
+      stalledStreak: 0,
+      lastSig: "",
+      lastInput: "",
+      invCalls: 0,
+      invCap: INV_POOL_DEFAULT,
+      invWarned: false,
+      envCache: null, // 环境检测结果即"已检测"的单一事实源（原 envChecked 布尔只写不读且可能与缓存不一致，2.5.1 删除）
+      caseCache: {},
+      taskInitial: BUDGET_DEFAULT,
+      pollutionFlagged: false,
+      goalPush: false, // 2.4.0：目标预授权（仅记录，不解锁执行）
+      highRiskOk: false, // 2.4.0：执行级授权（仅当回合人类短指令 y/同意 可设置）
+      highRiskCmd: "", // 2.4.0：待批/已批的高危命令原文（显示与审计用，>300 字符截断展示）
+      highRiskKey: "", // 2.5.2：待批/已批命令的全量哈希（比对与"已否决"登记用，不受截断影响）
+      highRiskDeniedThisTurn: false, // 2.4.0：本回合发生过高危拒绝（收尾须带审批单）
+      rejectedCmds: {}, // 2.4.0：被人类 n 否决的命令（彻底阻断）
+      scriptFiles: {}, // 2.4.0：写入过的脚本文件 → 内容是否含高危命令（绕行检测）
+      delegateBudget: DELEGATE_DEFAULT, // 2.3.0：委托池 granted 上限（只升不降）
+      delegateUsed: 0, // 2.3.0：委托池累计消耗
+      delegated: false, // 2.3.0：本任务是否已委派过
+      kpi: 0, // 2.3.0：委派 KPI 累计分
+      kpiLowReported: false, // 2.5.1：KPI 跌破 -10 只提醒一次（回升后再跌破可再次提醒）
+      kpiScolded: {}, // 2.3.0：每场景每任务只提醒一次
+      kpiDelegatedAwarded: false, // 2.3.0：+5 每任务一次
+      editedFiles: {}, // 2.3.0：本任务改过的文件集合（批量场景判定）
+    };
+  }
+}
+
+export function saveState(path, state) {
+  // 2.5.2 原子落盘：先写同目录临时文件再 rename 覆盖。原直接 writeFileSync 在进程被中断时
+  // 会留下半截 JSON（loadState 只能静默降级为默认值，等于整个会话状态凭空消失）。
+  const tmp = path + "." + process.pid + ".tmp";
+  try {
+    writeFileSync(tmp, JSON.stringify(state));
+    renameSync(tmp, path);
+  } catch {
+    try {
+      rmSync(tmp, { force: true });
+    } catch {}
+    noteFail(sid, "会话状态落盘（本次状态未保存，熔断/预算计数可能回退）");
+  }
+}
+
+// 2.5.3（61条落地）：清理系统临时目录中 30 天未动的 focus-guard 状态/回退档案。
+// 实测残留曾达 8376 个（测试与运行残留无限累积）；30 天未触碰即视为陈旧，会话启动时清扫。
+export function cleanStaleTemp(sid) {
+  try {
+    const cutoff = Date.now() - 30 * 86400e3;
+    let cleaned = 0;
+    for (const f of readdirSync(tmpdir())) {
+      if (!/^focus-guard-.*(\.json|-AUDIT\.log)$/.test(f)) continue;
+      const fp = join(tmpdir(), f);
+      try {
+        if (statSync(fp).mtimeMs < cutoff) {
+          rmSync(fp, { force: true });
+          cleaned++;
+        }
+      } catch {}
+    }
+    if (cleaned) audit(sid, "stale-cleaned", { level: null, evidence: `61条 清理 ${cleaned} 个 30 天未动的临时状态/档案文件` });
+  } catch {}
+}
+
+export function normalize(p) {
+  return String(p || "").replace(/\\/g, "/");
+}
+
+// ============ 2.0 环境检测（总纲三：会话级一次，全程复用） ============
+
+export function casePath(projDir) {
+  return join(projDir, ".ai", "CASE_FILE.md");
+}
+
+export function ensureCaseFile(projDir) {
+  const p = casePath(projDir);
+  if (!existsSync(p)) {
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, CASE_TEMPLATE);
+  }
+  return p;
+}
+
+export function sectionOf(text, marker) {
+  const re = new RegExp("### " + marker + "[\\s\\S]*?(?=\\n### |\\n## |$)");
+  return (text.match(re) || [""])[0];
+}
+
+export function parseDur(s) {
+  const m = String(s || "").trim().match(/^(\d+(?:\.\d+)?)\s*(分钟|小时|天|h|d|H|D)?$/);
+  if (!m) return null;
+  const n = parseFloat(m[1]);
+  const u = m[2] || "小时";
+  if (u === "分钟") return n * 60e3;
+  if (u === "天" || u === "d" || u === "D") return n * 86400e3;
+  return n * 3600e3;
+}
+
+export function loadCaseRecords(p) {
+  const out = {};
+  try {
+    const t = readFileSync(p, "utf8");
+    for (const line of sectionOf(t, "【三】").split("\n")) {
+      if (!line.startsWith("|")) continue;
+      const c = line.split("|").map((x) => x.trim());
+      if (c.length < 9) continue;
+      const [, f, readAt, mtime, size, sha, hist, ttl, via] = c;
+      if (!f || f === "文件名" || /^-+$/.test(f)) continue;
+      const hm = String(hist || "").match(/n=(\d+);?\s*last=(\S+)/);
+      out[normalize(f)] = {
+        path: f,
+        readAt: Date.parse(readAt) || 0,
+        mtime: parseFloat(mtime) || 0,
+        size: parseInt(size, 10) || 0,
+        sha: sha && sha !== "-" ? sha : "",
+        changes: hm ? parseInt(hm[1], 10) || 0 : 0,
+        lastChange: hm && hm[2] && hm[2] !== "-" ? Date.parse(hm[2]) || 0 : 0,
+        ttlOverride: ttl || "",
+        via: via || "mtime+size",
+      };
+    }
+  } catch {}
+  return out;
+}
+
+export function saveCaseRecords(projDir, records) {
+  let tmp = null;
+  try {
+    const p = ensureCaseFile(projDir);
+    tmp = p + "." + process.pid + ".tmp";
+    let t = readFileSync(p, "utf8");
+    const rows = Object.values(records)
+      .sort((a, b) => (b.readAt || 0) - (a.readAt || 0))
+      .slice(0, CASE_MAX_ROWS);
+    const table = ["| 文件名 | 读取时间 | mtime | size | SHA-256 | 变更历史 | TTL | 验证方式 |", "|---|---|---|---|---|---|---|---|"]
+      .concat(
+        rows.map(
+          (r) =>
+            `| ${r.path} | ${new Date(r.readAt || Date.now()).toISOString()} | ${r.mtime} | ${r.size} | ${r.sha || "-"} | n=${r.changes || 0}; last=${r.lastChange ? new Date(r.lastChange).toISOString() : "-"} | ${r.ttlOverride || ""} | ${r.via || "mtime+size"} |`
+        )
+      )
+      .join("\n");
+    t = t.replace(/(### 【三】[\s\S]*?\n)\| 文件名 \|[\s\S]*?(?=\n### |\n## |$)/, (_m, head) => head + table + "\n");
+    writeFileSync(tmp, t);
+    renameSync(tmp, p);
+  } catch {
+    // FG-D3：rename 失败清理 .tmp 残片（对齐 saveState 防线，防 .ai/ 积累孤片）
+    try { if (tmp) rmSync(tmp, { force: true }); } catch {}
+    noteFail(sid, "卷宗【三】侦查记录");
+  }
+}
+
+export function saveLedger(projDir, state) {
+  let tmp = null;
+  try {
+    const p = ensureCaseFile(projDir);
+    tmp = p + "." + process.pid + ".tmp";
+    let t = readFileSync(p, "utf8");
+    const eff = state.effectiveCalls || 0;
+    const inv = state.invCalls || 0;
+    const used = eff + inv;
+    const row = `| ${new Date().toISOString().slice(0, 16)} | ${state.taskInitial ?? state.taskBudget ?? BUDGET_DEFAULT} | ${used} | ${Math.max(0, (state.taskBudget || BUDGET_DEFAULT) - used)} | ${eff} | ${state.ineffCalls || 0} | ${new Date().toISOString()} | KPI ${state.kpi || 0} |`;
+    const table = ["| 任务 | 初始额度 | 已用额度 | 剩余额度 | 有效调用 | 无效调用 | 更新时间 | KPI |", "|---|---|---|---|---|---|---|---|", row].join("\n");
+    t = t.replace(/### 【四】[\s\S]*?(?=\n### |\n## |$)/, () => "### 【四】工作额度台账\n\n" + table + "\n");
+    writeFileSync(tmp, t);
+    renameSync(tmp, p);
+  } catch {
+    // FG-D3：同上
+    try { if (tmp) rmSync(tmp, { force: true }); } catch {}
+    noteFail(sid, "卷宗【四】额度台账");
+  }
+}
+
+export function fingerprint(absPath) {
+  const st = statSync(absPath);
+  const fp = { mtime: st.mtimeMs, size: st.size, sha: "" };
+  if (st.size <= SHA_LIMIT) fp.sha = createHash("sha256").update(readFileSync(absPath)).digest("hex").slice(0, 16);
+  return fp;
+}
+
+export function gitDirty(projDir, absPath) {
+  try {
+    if (!projDir) return null;
+    const rel = normalize(absPath).replace(normalize(projDir) + "/", "");
+    const out = execFileSync("git", ["-C", projDir, "status", "--porcelain", "--", rel], {
+      encoding: "utf8",
+      timeout: 4000,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return out.trim() ? 1 : 0;
+  } catch {
+    return null;
+  }
+}
+
+// 总纲五：优先级 依赖声明 > 人工标注 > 自适应
+export function resolveTTL(projDir, rec, filePath) {
+  if (projDir) {
+    try {
+      const t = readFileSync(casePath(projDir), "utf8");
+      for (const line of sectionOf(t, "【二】").split("\n")) {
+        if (!line.startsWith("|")) continue;
+        const c = line.split("|").map((x) => x.trim());
+        if (c.length < 7) continue;
+        const [, name, , ipath, , ttl] = c;
+        const d = parseDur(ttl);
+        if (!d || !ipath || ipath === "安装路径") continue;
+        if (filePath.startsWith(normalize(ipath))) return { ms: d, src: `依赖声明:${name}` };
+      }
+    } catch {}
+  }
+  if (rec && rec.ttlOverride) {
+    const d = parseDur(rec.ttlOverride);
+    if (d) return { ms: d, src: "人工标注" };
+  }
+  if (!rec || !rec.lastChange) return { ms: TTL_FIRST, src: "自适应:首次4h" };
+  const age = Date.now() - rec.lastChange;
+  if (age >= 30 * 86400e3) return { ms: TTL_STABLE, src: "自适应:30天未变" };
+  if (age >= 7 * 86400e3) return { ms: TTL_WEEK, src: "自适应:7-30天未变" };
+  return { ms: TTL_RECENT, src: "自适应:7天内有变" };
+}
+
+// ============ 2.0 平台命令规则（总纲六：按检出 shell 适配） ============
+

package/src/dsh/audit.mjs

@@ -0,0 +1,192 @@
+/**
+ * focus-guard 原生插件 · 审计接入（3.0.5）
+ *
+ * 卷宗写入口：AUDIT.log（拦截留痕）与 CASE_FILE.md（成本台账）。
+ * 一切写入独立 try/catch：留痕失败只 warn，绝不阻断宿主主流程；
+ * 也绝不因写失败把拦截降级成放行（见 pipeline.mjs 调用次序）。
+ */
+import { appendFileSync, readFileSync, statSync, renameSync, mkdirSync, rmSync, readdirSync, existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join, dirname, basename } from 'node:path'
+import { calcCost } from '../peak-cost.mjs'
+
+// 插件文件位于 <仓库根>/packages/core/src/dsh/ → 上溯 4 级到仓库根
+export const AUDIT_FILE = fileURLToPath(new URL('../../../../.focus-guard/AUDIT.log', import.meta.url))
+
+/** 审计日志体积上限（字节）；`FG_AUDIT_MAX_BYTES` 可覆盖。默认 5 MB ≈ 2 万条记录。 */
+export const AUDIT_MAX_BYTES = Number(process.env.FG_AUDIT_MAX_BYTES) || 5 * 1024 * 1024
+
+/** 归档保留份数；超出则删最旧。`FG_AUDIT_ARCHIVE_KEEP` 可覆盖。 */
+export const AUDIT_ARCHIVE_KEEP = Number(process.env.FG_AUDIT_ARCHIVE_KEEP) || 10
+
+/**
+ * 当前审计目标路径。
+ * `FG_AUDIT_FILE` 可重定向——**测试必须**用它指向 tmpdir，否则会写进真实工作区
+ *（2026-10-09 事故：污染 2630 行 / 746 个测试 session）。与 `caseFilePath` 的 `FG_CASE_FILE` 同思路。
+ */
+export function auditFilePath() {
+  return process.env.FG_AUDIT_FILE || AUDIT_FILE
+}
+
+/**
+ * 体积轮转（2026-10-09）：超出上限则把当前日志移入同目录 `archive/`，并立刻重建空文件。
+ * 纪律三条：
+ *   ① 只归档、不删除（执法记录不得丢）——超保留份数才清理最旧存档；
+ *   ② 任何失败只 warn，绝不阻断写入方（与全文件 fail-open 口径一致）；
+ *   ③ 轮转失败时**继续追加原文件**——宁可文件变大，不可丢记录。
+ * 注意：封存的 `hooks/guard.mjs`（ZCode 层）不经此处写入，它的日志不受本机制管辖。
+ * @returns {string|null} 归档目标路径；未轮转或失败返回 null
+ */
+export function rotateAuditIfNeeded(file = auditFilePath(), max = AUDIT_MAX_BYTES) {
+  try {
+    // 文件尚不存在 = 首次写入，属正常情况，静默放过。
+    // （不先判存在会走 statSync 抛 ENOENT，每次首写都刷一条"轮转失败"warn，噪音掩盖真问题。）
+    if (!existsSync(file)) return null
+    const size = statSync(file).size
+    if (size < max) return null
+    const dir = join(dirname(file), 'archive')
+    mkdirSync(dir, { recursive: true })
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+    const dest = join(dir, `${basename(file)}.${stamp}`)
+    renameSync(file, dest)
+    appendFileSync(file, '') // 立刻重建空文件，保持 append-only 语义
+    const prefix = `${basename(file)}.`
+    const olds = readdirSync(dir)
+      .filter((n) => n.startsWith(prefix))
+      .sort()
+    for (const n of olds.slice(0, Math.max(0, olds.length - AUDIT_ARCHIVE_KEEP))) {
+      try {
+        rmSync(join(dir, n), { force: true })
+      } catch {
+        /* 清理旧存档失败可忽略，不影响本次轮转 */
+      }
+    }
+    console.warn(`[focus-guard-native] 审计日志已轮转：${dest}（原 ${size} 字节）`)
+    return dest
+  } catch (error) {
+    console.warn(
+      '[focus-guard-native] 审计轮转失败（继续追加原文件，不丢记录）:',
+      (error && error.message) || error,
+    )
+    return null
+  }
+}
+
+/**
+ * 统一审计写入入口（3.0.7）：三处写点（auditDeny / auditRedlineExempt / auditEligibility）共用，
+ * 避免"同一文件两种口径"复发（2026-10-09 事故的根因之一），并让轮转只在一处生效。
+ * @returns {boolean} 是否写入成功
+ */
+export function appendAudit(row, file = auditFilePath()) {
+  try {
+    rotateAuditIfNeeded(file)
+    // 2026-10-18：先确保目录存在再追加。原先若 `.focus-guard/` 尚未创建，
+    // 首写会 ENOENT 被 catch 吞成一条 warn —— 而 FG 现在**第一条**写入是启动自证
+    // `compaction-watch-ready`（进程一启动就写，早于任何会话活动）。它要是丢了，
+    // "自证清白"就成了自证不了。mkdir 失败仍在同一 try 内，降级口径不变。
+    mkdirSync(dirname(file), { recursive: true })
+    appendFileSync(file, JSON.stringify(row) + '\n')
+    return true
+  } catch (error) {
+    console.warn('[focus-guard-native] AUDIT 留痕失败（不阻断）:', (error && error.message) || error)
+    return false
+  }
+}
+
+/** 从 exec 取会话标识（三处写入共用的口径）。 */
+function sessionOf(exec) {
+  // ⚠ 取值口径必须与官方桥一致（lib/index.js:349-354）——真实会话 id 在 agent.session.header.id。
+  // 2026-10-10 实测：只认 exec.sessionId / agent.sessionId / agent.id 会全部取空，
+  // 于是所有会话退化成同一个 'dsh-native'（真实 AUDIT.log 里 439 条记录都记在 dsh-native 名下，
+  // 而取值正确的 seams 写的是 sess_<uuid>）——这会造成跨会话状态与审计互相污染。
+  return (
+    (exec &&
+      ((exec.agent && exec.agent.session && exec.agent.session.header && exec.agent.session.header.id) ||
+        exec.sessionId ||
+        (exec.agent && (exec.agent.sessionId || exec.agent.id)))) ||
+    'dsh-native'
+  )
+}
+
+/**
+ * 拦截写入一条审计记录（JSONL 追加，字段与 hooks/guard.mjs 口径一致）。
+ * 2026-10-18 修（REPORT-2026-10-12 P2）：trigger/level 原为常量 'high-risk-rm'/3，
+ * 与真实拦截规则无关 —— `ls -la` 也被记成 "high-risk-rm"，审计无法回答"为什么被拦"。
+ * 现由调用点传 detail.trigger（规则名），缺省才退回 'unspecified'。
+ * @param {unknown} exec
+ * @param {unknown} cmd
+ * @param {{ trigger?: string, level?: number|null }} [detail]
+ */
+export function auditDeny(exec, cmd, detail = {}) {
+  return appendAudit({
+    ts: new Date().toISOString(),
+    session: sessionOf(exec),
+    action: 'deny',
+    trigger: detail.trigger || 'unspecified',
+    level: detail.level ?? 3,
+    evidence: String(cmd).slice(0, 120),
+    pardon: false,
+  })
+}
+
+/**
+ * 红线上下文豁免留痕（3.0.6 P0，HANDOFF §八）。
+ * 命中绝对红线但被判为"被引用的命令字符串"而豁免时调用——豁免不是静默放行，必须可审计。
+ */
+export function auditRedlineExempt(exec, cmd, detail = {}) {
+  return appendAudit({
+    ts: new Date().toISOString(),
+    session: sessionOf(exec),
+    action: 'redline-exempt',
+    trigger: detail.redline || 'absolute-redline',
+    level: null,
+    basis: detail.basis || null,
+    evidence: `${detail.detail || ''} | ${String(cmd).slice(0, 120)}`.slice(0, 300),
+    pardon: false,
+  })
+}
+
+/**
+ * 成本台账落卷目标。
+ * 默认 = 仓库根 `.ai/CASE_FILE.md`；`FG_CASE_FILE` 可覆盖——测试**必须**用它重定向到临时目录，
+ * 否则自检会写进人类真实卷宗（2026-10-07 事故）。落盘前另有一道守卫，见 appendCostRow。
+ */
+export function caseFilePath() {
+  return process.env.FG_CASE_FILE || fileURLToPath(new URL('../../../../.ai/CASE_FILE.md', import.meta.url))
+}
+
+const COST_MARK = '【五】成本台账'
+
+/** 成本台账落卷：卷宗无该章节则先补表头，再逐行追加；失败只 warn 不阻塞 */
+export function appendCostRow(ts, model, inPeak, usage) {
+  try {
+    let header = ''
+    try {
+      if (!readFileSync(caseFilePath(), 'utf8').includes(COST_MARK)) {
+        header =
+          '\n### 【五】成本台账（DSH 原生插件自动追加；tokens / USD）\n\n' +
+          '| 时间 | 模型 | 时段 | 输入未缓存 | 缓存读 | 输出 | 成本USD |\n' +
+          '|---|---|---|---|---|---|---|\n'
+      }
+    } catch (error) {
+      console.warn(
+        '[focus-guard-native] 读卷宗失败，按无表头处理（写入仍尝试）:',
+        (error && error.message) || error,
+      )
+    }
+    const usd = calcCost(model, usage, inPeak)
+    const target = caseFilePath()
+    // 写守卫：目标必须是默认卷宗路径，或调用方显式用 FG_CASE_FILE 重定向（测试用）。
+    // 其余一律拒写——防止任何代码路径把台账写到意料之外的位置。
+    const DEFAULT_CASE_FILE = fileURLToPath(new URL('../../../../.ai/CASE_FILE.md', import.meta.url))
+    if (target !== DEFAULT_CASE_FILE && !process.env.FG_CASE_FILE) {
+      throw new Error(`成本台账目标异常，拒绝写入：${target}`)
+    }
+    appendFileSync(
+      target,
+      `${header}| ${ts} | ${model} | ${inPeak ? '峰' : '谷'} | ${usage.input} | ${usage.cacheRead} | ${usage.output} | ${usd === null ? '未知价目' : usd.toFixed(6)} |\n`,
+    )
+  } catch (error) {
+    console.warn('[focus-guard-native] 成本台账写入失败（不阻塞）:', (error && error.message) || error)
+  }
+}