@luckychen1993/pm-mcp 0.1.5 → 0.4.0

package/dist/project-fingerprint.js

@@ -1,11 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
-const DEFAULT_IGNORED_DIRECTORIES = new Set([
-    ".git", ".pm", ".cache", ".gradle", ".idea", ".next", ".nuxt", ".output", ".turbo", ".venv", ".vscode", ".zcode",
-    "__pycache__", "build", "coverage", "dist", "env", "node_modules", "out", "target", "venv",
-]);
-function hashRegularFile(file) {
+import { SCAN_IGNORE_DIRS, ignoreMatcher, projectScanIgnores } from "./scan-policy.js";
+const DEFAULT_IGNORED_DIRECTORIES = SCAN_IGNORE_DIRS;
+export function hashRegularFile(file) {
     const handle = fs.openSync(file, "r");
     const digest = createHash("sha256");
     const buffer = Buffer.allocUnsafe(1024 * 1024);
@@ -43,6 +41,10 @@ export function fingerprintProject(root) {
         throw new Error(`项目根必须是普通目录: ${absolute}`);
     const rootReal = fs.realpathSync.native(absolute);
     const tree = createHash("sha256");
+    const ignores = projectScanIgnores(root);
+    const excluded = ignoreMatcher(ignores);
+    if (ignores.length)
+        tree.update(`scan-ignore\0${JSON.stringify(ignores)}\0`);
     let files = 0;
     let bytes = 0;
     const visit = (directory, relativeDirectory) => {
@@ -52,6 +54,8 @@ export function fingerprintProject(root) {
                 continue;
             const absoluteEntry = path.join(directory, entry.name);
             const relative = path.posix.join(relativeDirectory.replace(/\\/g, "/"), entry.name);
+            if (excluded(relative, entry.isDirectory()))
+                continue;
             if (relative === "PROJECT.md")
                 continue; // generated dashboard; authoritative inputs live in .pm and source files
             const stat = fs.lstatSync(absoluteEntry);

package/dist/project-tools.js

@@ -9,6 +9,9 @@ import { loadProject, loadRoadmap, loadSecurity, loadSessions, loadTasks, savePr
 import { now } from "./types.js";
 import { budgetLines, toolI, toolR, toolW } from "./tool-base.js";
 import { renderRuntimeLogLines, renderUsageLogLines } from "./usage-log.js";
+import { ScanIgnoreSchema } from "./scan-policy.js";
+import { VERSION, RUNTIME_CONTRACT } from "./version.js";
+import { CompletionEvidenceSchema } from "./quality-evidence.js";
 function taskLine(t, withNext = false) {
     const parts = [`[${t.status}]`, t.id, t.title, `(${t.type}${t.milestone ? `,${t.milestone}` : ""})`];
     if (withNext && t.checkpoint) {
@@ -46,6 +49,7 @@ export function registerProjectTools(server, root) {
         const security = loadSecurity(root);
         const L = [];
         L.push(`# ${project.name}${project.phase ? ` — ${project.phase}` : ""}`);
+        L.push(`运行版本: pm-mcp ${VERSION} · 项目根: ${root}`);
         if (project.description)
             L.push(project.description);
         L.push("");
@@ -96,8 +100,9 @@ export function registerProjectTools(server, root) {
         }
         L.push("");
         L.push("> 三段式定位：本状态 → search_code 精确到行 → 才读具体文件。别全量读代码。");
-        return foldLines(L, { maxLines: budgetLines(root) });
-    });
+        return JSON.stringify({ text: foldLines(L, { maxLines: budgetLines(root) }), runtime: { version: VERSION, root, contract: RUNTIME_CONTRACT } });
+    }, { cacheVersion: `runtime:${VERSION}`, outputSchema: { runtime: z.object({ version: z.string(), root: z.string(), contract: z.string() }) },
+        decode: (value) => { const result = JSON.parse(value); return { text: result.text, data: { runtime: result.runtime } }; } });
     toolR(server, root, "get_usage_log", "使用日志：pm-mcp 被用了哪些工具、成败、耗时，以及输出 token 估算与「折叠省下的 token」——回答“用它到底省不省 token”。只记工具名与计量，不记参数内容。日志滚动保留约 2MB。", {
         last: z.number().int().min(1).max(200).optional().describe("返回最近 N 条明细（默认 20；汇总始终覆盖全部保留日志）"),
         tool: z.string().optional().describe("只看某工具，如 get_status"),
@@ -124,6 +129,8 @@ export function registerProjectTools(server, root) {
         license: z.string().optional(),
         exposure: z.enum(["local", "network", "public"]).optional(),
         modules: z.array(z.string()).optional().describe("模块登记（用于未登记目录检测）"),
+        scan_ignore: ScanIgnoreSchema.optional().describe("本项目产物/缓存的相对排除 glob，例如 release/**；传 [] 清除；不应排除真实源码"),
+        completion_evidence: CompletionEvidenceSchema.optional().describe("默认要求tests_observed；兼容无计数运行器时显式选择execution_only并记录原因"),
         max_file_loc: z.number().int().min(10).optional().describe("单文件行数预算"),
         refactor_quota_pct: z.number().min(0).max(100).optional().describe("里程碑重构类任务最低占比%"),
         session_blast_radius: z.number().int().min(1).optional().describe("单会话波及文件阈值"),
@@ -145,6 +152,10 @@ export function registerProjectTools(server, root) {
             project.exposure = args.exposure;
         if (args.modules !== undefined)
             project.modules = args.modules;
+        if (args.scan_ignore !== undefined)
+            project.scan_ignore = args.scan_ignore;
+        if (args.completion_evidence !== undefined)
+            project.completion_evidence = CompletionEvidenceSchema.parse(args.completion_evidence);
         if (args.max_file_loc !== undefined)
             project.budgets.maxFileLoc = args.max_file_loc;
         if (args.refactor_quota_pct !== undefined)

package/dist/quality-evidence.js

@@ -0,0 +1,56 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+export const CompletionEvidenceSchema = z.object({
+    minimum: z.enum(["tests_observed", "execution_only"]),
+    reason: z.string().trim().min(8).max(1000),
+});
+const ranks = { unverified: 0, execution_only: 1, tests_observed: 2, coverage_observed: 3 };
+/** 等级描述观测强度，不代表测试充分、结果通过或来源不可伪造。 */
+export function evidenceLevel(kind, summary, truncated = false) {
+    if (truncated || !["test", "coverage"].includes(kind))
+        return "execution_only";
+    const counters = [summary.failed, summary.skipped, summary.cancelled, summary.todo];
+    if (summary.tests === null || !Number.isSafeInteger(summary.tests) || summary.tests <= 0 ||
+        counters.some((n) => n === null || !Number.isSafeInteger(n) || n < 0) ||
+        counters.reduce((total, n) => total + (n ?? 0), 0) > summary.tests)
+        return "execution_only";
+    if (summary.passed != null && summary.passed + counters.reduce((total, n) => total + (n ?? 0), 0) !== summary.tests)
+        return "execution_only";
+    const coverage = z.object({ lines_pct: z.number().min(0).max(100), branches_pct: z.number().min(0).max(100), functions_pct: z.number().min(0).max(100) }).safeParse(summary.coverage);
+    return coverage.success ? "coverage_observed" : "tests_observed";
+}
+export function weakestEvidence(levels) {
+    return levels.length ? levels.reduce((a, b) => ranks[a] < ranks[b] ? a : b) : "execution_only";
+}
+export function evidenceLabel(level) {
+    return { unverified: "无可用验证证据", execution_only: "仅执行记录，未确认测试数量", tests_observed: "已观察测试结果", coverage_observed: "已观察测试与覆盖率" }[level ?? ""] ?? "旧报告未标等级";
+}
+export function qualityResultSummary(item) {
+    const summary = qualityOutputSummary(item.command.kind, item.stdout, item.stderr, item.truncated);
+    return { ...summary, evidence_level: item.exitCode === null ? "unverified" : summary.evidence_level };
+}
+export function qualityOutputSummary(kind, stdout, stderr, truncated = false) {
+    const output = `${stdout}\n${stderr}`.replace(/\u001b\[[0-9;]*m/g, "");
+    const diagnostic = (label) => {
+        const matches = [...output.matchAll(new RegExp(`^[ \\t]*(?:ℹ|#)?[ \\t]*${label}[ \\t]+(\\d+)[ \\t]*\\r?$`, "gmi"))];
+        return matches.length ? Number(matches.at(-1)[1]) : null;
+    };
+    let counts = { tests: diagnostic("tests"), passed: diagnostic("pass"), failed: diagnostic("fail"), cancelled: diagnostic("cancelled"), skipped: diagnostic("skipped"), todo: diagnostic("todo") };
+    let counterSource = counts.tests === null ? "unknown" : "node_test_summary";
+    const jest = [...output.matchAll(/^\s*Tests:\s*(.+?)(\d+)\s+total\s*$/gm)].at(-1);
+    const vitest = [...output.matchAll(/^\s*Tests\s+(.+?)\s*\((\d+)\)\s*$/gm)].at(-1);
+    const pytest = [...output.matchAll(/^=+\s+((?:\d+\s+(?:passed|failed|skipped|xfailed|xpassed|deselected|errors?|warnings?)[,\s]*)+)\s+in\s+[\d.]+s.*?=+\s*$/gm)].at(-1);
+    if (counts.tests === null && (jest || vitest || pytest)) {
+        const text = (jest ?? vitest ?? pytest)[1];
+        const number = (label) => Number(new RegExp(`(\\d+)\\s+${label}\\b`).exec(text)?.[1] ?? 0);
+        const passed = number("passed"), failed = number("failed") + number("errors?") + number("xpassed");
+        const skipped = number("skipped") + number("xfailed") + number("deselected"), todo = number("todo");
+        counts = { tests: jest ? Number(jest[2]) : vitest ? Number(vitest[2]) : passed + failed + skipped + todo, passed, failed, skipped, todo, cancelled: 0 };
+        counterSource = jest ? "jest_summary" : vitest ? "vitest_summary" : "pytest_summary";
+    }
+    const coverage = output.match(/(?:^|\n)(?:ℹ|#)?\s*all files\s*\|\s*([\d.]+)\s*\|\s*([\d.]+)\s*\|\s*([\d.]+)(?:\s*\|\s*([\d.]+))?/i);
+    counts.coverage = coverage ? { lines_pct: Number(coverage[4] ?? coverage[1]), branches_pct: Number(coverage[2]), functions_pct: Number(coverage[3]) } : null;
+    return { stdout_bytes: Buffer.byteLength(stdout), stderr_bytes: Buffer.byteLength(stderr),
+        output_sha256: createHash("sha256").update(stdout).update("\0").update(stderr).digest("hex"),
+        ...counts, counter_source: counterSource, evidence_level: evidenceLevel(kind, counts, truncated) };
+}

package/dist/quality-store.js

@@ -1,48 +1,28 @@
 import fs from "node:fs";
 import path from "node:path";
-import { createHash } from "node:crypto";
 import { atomicWrite, withLedgerLock } from "./store.js";
 import { refreshDerived } from "./dashboard.js";
-function numericDiagnostic(output, label) {
-    const match = output.match(new RegExp(`(?:^|\\n)(?:ℹ|#)?\\s*${label}\\s+(\\d+)(?:\\s|$)`, "i"));
-    return match ? Number(match[1]) : null;
-}
-function outputSummary(stdout, stderr) {
-    const combined = `${stdout}\n${stderr}`;
-    // Node's test reporter exposes line|branch|function, while Istanbul/c8 uses
-    // statement|branch|function|line. Preserve one normalized three-metric shape.
-    const coverage = combined.match(/(?:^|\n)(?:ℹ|#)?\s*all files\s*\|\s*([\d.]+)\s*\|\s*([\d.]+)\s*\|\s*([\d.]+)(?:\s*\|\s*([\d.]+))?/i);
-    return {
-        stdout_bytes: Buffer.byteLength(stdout),
-        stderr_bytes: Buffer.byteLength(stderr),
-        output_sha256: createHash("sha256").update(stdout, "utf8").update("\0", "utf8").update(stderr, "utf8").digest("hex"),
-        tests: numericDiagnostic(combined, "tests"),
-        passed: numericDiagnostic(combined, "pass"),
-        failed: numericDiagnostic(combined, "fail"),
-        cancelled: numericDiagnostic(combined, "cancelled"),
-        skipped: numericDiagnostic(combined, "skipped"),
-        todo: numericDiagnostic(combined, "todo"),
-        coverage: coverage ? { lines_pct: Number(coverage[4] ?? coverage[1]), branches_pct: Number(coverage[2]), functions_pct: Number(coverage[3]) } : null,
-    };
-}
+import { qualityResultSummary, weakestEvidence } from "./quality-evidence.js";
 /** Persist a secret-minimised quality summary; raw stdout/stderr never enter the ledger. */
 export function saveQualityRun(root, result, provenance) {
     const runAt = new Date();
     const stamp = runAt.toISOString().replace(/[-:]/g, "").replace("T", "-").replace(".", "-").replace(/Z$/, "");
     const effectiveOk = result.ok && result.execute && result.results.length > 0 && result.results.every((item) => item.status === "passed" && item.exitCode === 0 && item.signal === null);
+    const summaries = result.results.map(qualityResultSummary);
     const payload = JSON.stringify({
         schema_version: 2,
         run_at: runAt.toISOString(),
         ok: effectiveOk,
         reported_ok: result.ok,
         execute: result.execute,
+        evidence_level: result.execute && result.results.some((item) => item.exitCode !== null) ? weakestEvidence(summaries.filter((_item, i) => ["test", "coverage"].includes(result.results[i].command.kind)).map((item) => item.evidence_level)) : "unverified",
         environment: { platform: process.platform, arch: process.arch, node: process.version },
         source: provenance ? {
             before: provenance.source_before,
             after: provenance.source_after,
             stable: provenance.source_before.sha256 === provenance.source_after.sha256,
         } : null,
-        results: result.results.map((item) => ({
+        results: result.results.map((item, index) => ({
             unit_root: item.command.cwd,
             kind: item.command.kind,
             command: item.command.command,
@@ -52,7 +32,7 @@ export function saveQualityRun(root, result, provenance) {
             signal: item.signal,
             duration_ms: item.durationMs,
             output_truncated: item.truncated,
-            output_summary: outputSummary(item.stdout, item.stderr),
+            output_summary: summaries[index],
             error: item.error ?? "",
         })),
     }, null, 2) + "\n";

package/dist/registry.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { RegistrySchema, now } from "./types.js";
 import { registryFile } from "./paths.js";
@@ -23,9 +24,18 @@ export function saveRegistry(data) {
 }
 /** 登记/刷新一个项目（init 与每次写操作都会 touch） */
 export function touchRegistry(root, name) {
-    const data = loadRegistry();
     const abs = path.resolve(root);
-    const idx = data.projects.findIndex((p) => path.resolve(p.root) === abs);
+    // 防污染（T-034 根因）：临时目录里的"项目"从不进入真实注册表——
+    // 测试若未设 PM_MCP_HOME 沙箱，写入会被这里拦下而不是污染 ~/.pm-mcp。
+    // 沙箱化测试（显式设了 PM_MCP_HOME）不受影响，仍写沙箱注册表。
+    if (!process.env.PM_MCP_HOME?.trim() && isUnderTemp(abs)) {
+        console.error(`[pm-mcp] 跳过注册临时目录项目（如需管理请移出临时目录）: ${abs}`);
+        return;
+    }
+    const data = loadRegistry();
+    // Windows 路径大小写不敏感：按小写比较去重（e:/E: 重复注册缺陷）
+    const key = abs.toLowerCase();
+    const idx = data.projects.findIndex((p) => path.resolve(p.root).toLowerCase() === key);
     const entry = { name, root: abs, last_seen: now() };
     if (idx >= 0)
         data.projects[idx] = entry;
@@ -33,6 +43,22 @@ export function touchRegistry(root, name) {
         data.projects.push(entry);
     saveRegistry(data);
 }
+function isUnderTemp(abs) {
+    const normalized = abs.toLowerCase();
+    // tmpdir 可能以 8.3 短名返回（ADMINI~1），与注册表里的长名不一致——两种形态都比对
+    let tmpLong = os.tmpdir().toLowerCase();
+    try {
+        tmpLong = fs.realpathSync.native(os.tmpdir()).toLowerCase();
+    }
+    catch {
+        /* keep default */
+    }
+    for (const tmp of new Set([tmpLong, os.tmpdir().toLowerCase()])) {
+        if (normalized === tmp || normalized.startsWith(tmp.replace(/\$/, "") + path.sep))
+            return true;
+    }
+    return false;
+}
 export function listRegistry() {
     return loadRegistry().projects.sort((a, b) => b.last_seen.localeCompare(a.last_seen));
 }

package/dist/scan-policy.js

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { globToRegExp, normSep } from "./budget.js";
+export const SCAN_IGNORE_DIRS = new Set([
+    "node_modules", ".git", "dist", "build", "out", ".next", ".nuxt", ".output", ".turbo", "coverage",
+    "__pycache__", ".venv", "venv", "env", ".pm", ".idea", ".vscode", "target", ".cache", ".gradle",
+    ".zcode", ".runtime", "EBWebView",
+    // 包管理器缓存 / 运行时数据 / 临时与上下文目录：属于环境而非项目源码（T-045）
+    ".pnpm-cache", ".pnpm-store", ".npm-cache", ".yarn-cache", ".data", ".tmp", ".temp",
+    ".codex-context", "userdata", "logs",
+]);
+export const ScanIgnoreSchema = z.array(z.string().trim().min(1).max(512).transform(normSep).refine((glob) => !glob.startsWith("/") && !glob.startsWith("!") && !/^[a-z]:/i.test(glob) && !glob.split("/").includes(".."), "扫描排除必须是项目内的正向相对 glob")).max(100);
+export function projectScanIgnores(root) {
+    const file = path.join(root, ".pm", "project.json");
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    return [...new Set(ScanIgnoreSchema.parse(JSON.parse(raw).scan_ignore ?? []))].sort();
+}
+export function ignoreMatcher(globs) {
+    const patterns = globs.map(globToRegExp);
+    return (rel, directory = false) => patterns.some((pattern) => pattern.test(rel) || (directory && pattern.test(`${rel}/`)));
+}
+export function scanExclusionNote(root) {
+    const ignores = projectScanIgnores(root);
+    return ignores.length ? [`扫描范围排除：${ignores.join(", ")}；排除内容不属于本次检查结论。`] : [];
+}

package/dist/scan.js

@@ -2,33 +2,13 @@ import fs from "node:fs";
 import path from "node:path";
 import { globToRegExp, normSep } from "./budget.js";
 import { aggregates, getIndex, walkRefresh } from "./index-store.js";
+import { SCAN_IGNORE_DIRS, ignoreMatcher, projectScanIgnores } from "./scan-policy.js";
 /**
  * 代码树扫描：低层走查（生成器，内存恒定）+ scanProject 聚合入口。
  * 内容级结果存 SQLite 索引（index-store），未变更文件永不重读。
  * 超大项目保护：>10 万文件不物化 files 数组（聚合与点名走 SQL）。
  */
-export const DEFAULT_IGNORE_DIRS = new Set([
-    "node_modules",
-    ".git",
-    "dist",
-    "build",
-    "out",
-    ".next",
-    ".nuxt",
-    ".output",
-    ".turbo",
-    "coverage",
-    "__pycache__",
-    ".venv",
-    "venv",
-    "env",
-    ".pm",
-    ".idea",
-    ".vscode",
-    "target",
-    ".cache",
-    ".gradle",
-]);
+export const DEFAULT_IGNORE_DIRS = SCAN_IGNORE_DIRS;
 /** 真实目录树不太可能超过 64 层；超限的计数上报，绝不静默丢失 */
 export const DEPTH_LIMIT = 64;
 export const BINARY_EXTS = new Set([
@@ -112,7 +92,7 @@ export function needsSkipCount(rel, isTest) {
  * onSkippedDeep 在超深路径被跳过时回调（计数上报用）。
  */
 export function* walkStatEntries(root, opts = {}, onSkippedDeep) {
-    const extraRe = (opts.extraIgnores ?? []).map(globToRegExp);
+    const excluded = ignoreMatcher([...projectScanIgnores(root), ...(opts.extraIgnores ?? [])]);
     const includeRe = opts.include?.map(globToRegExp);
     const maxBytes = opts.maxFileBytes ?? 2 * 1024 * 1024;
     void maxBytes;
@@ -134,12 +114,12 @@ export function* walkStatEntries(root, opts = {}, onSkippedDeep) {
             if (entry.isDirectory()) {
                 if (DEFAULT_IGNORE_DIRS.has(entry.name))
                     continue;
-                if (extraRe.some((re) => re.test(rel)))
+                if (excluded(rel, true))
                     continue;
                 yield* walk(abs, depth + 1);
             }
             else if (entry.isFile()) {
-                if (extraRe.some((re) => re.test(rel)))
+                if (excluded(rel))
                     continue;
                 if (includeRe && !includeRe.some((re) => re.test(rel)))
                     continue;

package/dist/search.js

@@ -6,6 +6,7 @@ import { decisionsDir } from "./paths.js";
 import { loadGovernance } from "./governance-model.js";
 import { listFiles, DEFAULT_IGNORE_DIRS } from "./scan.js";
 import { foldLines, normSep } from "./budget.js";
+import { projectScanIgnores } from "./scan-policy.js";
 /**
  * 求证与检索：search_code（锚定真实代码）+ search_knowledge（历史结论）。
  * token 经济的一部分：返回 file:line 片段而非整文件。
@@ -36,6 +37,7 @@ export function rgSearch(root, query, glob, maxResults, regex) {
             args.push("-g", "!.pm/**");
         else
             args.push("-g", `!${dir}/**`);
+        args.push("-g", `!**/${dir}/**`);
     }
     args.push("--max-count", String(maxResults * 3));
     if (regex)
@@ -44,6 +46,8 @@ export function rgSearch(root, query, glob, maxResults, regex) {
         args.push("-F", "-e", query);
     if (glob)
         args.push("--glob", glob);
+    for (const excluded of projectScanIgnores(root))
+        args.push("--glob", `!${excluded}`);
     args.push(".");
     const r = spawnSync("rg", args, { cwd: root, encoding: "utf8", timeout: 120_000, maxBuffer: 64 * 1024 * 1024 });
     if (process.env.PM_RG_DEBUG)

package/dist/security.js

@@ -7,6 +7,7 @@ import { readDirectDeps } from "./scan.js";
 import { ensureFresh, getIndex, iterateFileRows, walkRefresh } from "./index-store.js";
 import { readText } from "./search.js";
 import { now } from "./types.js";
+import { scanExclusionNote } from "./scan-policy.js";
 const SECRET_PATTERNS = [
     { id: "secret.aws-access-key", severity: "high", pattern: /AKIA[0-9A-Z]{16}/, message: "疑似 AWS Access Key" },
     { id: "secret.github-token", severity: "high", pattern: /gh[pousr]_[A-Za-z0-9]{20,}/, message: "疑似 GitHub Token" },
@@ -265,6 +266,7 @@ export function auditSecurity(root, prepared) {
     const high = open.filter((f) => f.severity === "high");
     const L = [];
     L.push(`## 安全体检报告（exposure=${project.exposure}）`);
+    L.push(...scanExclusionNote(root));
     // exposure 兑现：不同暴露面使用不同处置口径
     if (project.exposure === "public") {
         const mustFix = open.filter((f) => f.severity === "high" || f.severity === "medium");

package/dist/semantic-evidence-store.js

@@ -102,6 +102,28 @@ export function saveSemanticEvidence(root, id, input) {
         return parsed.data;
     });
 }
+/** Atomically replace the evidence set for one repository-relative source file under the ledger lock. */
+export function replaceSemanticEvidenceForFile(root, id, input) {
+    const safeId = validateSemanticEvidenceId(id);
+    const parsed = SemanticEvidenceDocumentSchema.safeParse(input);
+    if (!parsed.success) {
+        throw new Error(`语义证据 schema 校验失败: ${parsed.error.issues.map((issue) => `${issue.path.join(".") || "document"}: ${issue.message}`).join("; ")}`);
+    }
+    const absoluteRoot = path.resolve(root);
+    const directory = semanticEvidenceDir(absoluteRoot);
+    assertRealDirectoryWithinRoot(absoluteRoot, directory, true);
+    return withLedgerLock(absoluteRoot, () => {
+        assertRealDirectoryWithinRoot(absoluteRoot, directory, false);
+        const oldIds = evidenceIdsUnlocked(absoluteRoot)
+            .filter((candidate) => candidate !== safeId)
+            .filter((candidate) => loadUnlocked(absoluteRoot, candidate).file === parsed.data.file);
+        atomicWrite(semanticEvidencePath(absoluteRoot, safeId), `${JSON.stringify(parsed.data, null, 2)}
+`);
+        for (const oldId of oldIds)
+            fs.rmSync(semanticEvidencePath(absoluteRoot, oldId), { force: false });
+        return parsed.data;
+    });
+}
 export function loadSemanticEvidence(root, id) {
     return loadUnlocked(path.resolve(root), validateSemanticEvidenceId(id));
 }

package/dist/semantic-graph.js

@@ -363,6 +363,8 @@ export function buildSemanticGraph(root, governance, options = {}) {
             limitations: [...analysisLimitations],
         },
         files, fileEdges, moduleEdges, exports: exportedSymbols, contracts, unresolved, cycles: findModuleCycles(moduleEdges), violations,
+        // Tarjan 对 {from,to} 边同构，文件内边与模块边共用同一实现。
+        fileCycles: findModuleCycles(fileEdges.flatMap((edge) => (edge.to !== null && edge.resolution === "file" ? [{ from: edge.from, to: edge.to }] : []))),
         coverage: {
             totalFiles: files.length,
             sourceCandidateFiles,

package/dist/semantic-parsers.js

@@ -298,6 +298,24 @@ export function candidates(from, specifier, language, ownerRoots = []) {
         if (base === ".." || base.startsWith("../"))
             continue;
         out.add(base);
+        // TypeScript ESM convention: source specifiers ending in .js/.jsx/.mjs/.cjs often
+        // refer to .ts/.tsx/.mts/.cts files on disk (tsc rewriteRelativeImportExtensions
+        // and Node type stripping both map them this way). Candidates are appended after
+        // the literal path, so an existing .js file still wins resolution.
+        const specExt = path.posix.extname(base);
+        if (specExt === ".js" || specExt === ".jsx" || specExt === ".mjs" || specExt === ".cjs") {
+            const stem = base.slice(0, base.length - specExt.length);
+            if (specExt === ".js") {
+                out.add(`${stem}.ts`);
+                out.add(`${stem}.tsx`);
+            }
+            else if (specExt === ".jsx")
+                out.add(`${stem}.tsx`);
+            else if (specExt === ".mjs")
+                out.add(`${stem}.mts`);
+            else
+                out.add(`${stem}.cts`);
+        }
         if (!path.posix.extname(base)) {
             for (const ext of RESOLVE_EXTS)
                 out.add(base + ext);

package/dist/session-log.js

@@ -0,0 +1,14 @@
+import { loadSessions, nextId, saveSessions } from "./store.js";
+import { now } from "./types.js";
+import { captureFileHashes, projectFilePath } from "./git-state.js";
+/** 调用方持有账本锁；共享显式会话与任务自动会话的同一记录方式。 */
+export function appendSession(root, input, hashes) {
+    const files = (input.files ?? []).map(projectFilePath);
+    const fileHashes = hashes ?? captureFileHashes(root, files);
+    const data = loadSessions(root);
+    const id = nextId("S", data.seq, 4);
+    data.seq += 1;
+    data.sessions.push({ id, date: now(), author: input.author ?? "", summary: input.summary, files, next_steps: input.next_steps ?? [], file_hashes: fileHashes });
+    saveSessions(root, data);
+    return id;
+}

package/dist/setup-project.js

@@ -0,0 +1,146 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { atomicWrite } from "./store.js";
+import { PACKAGE_SPEC, SERVER_NAME } from "./version.js";
+export function canonicalProjectRoot(root) {
+    const absolute = path.resolve(root);
+    let real;
+    try {
+        real = fs.realpathSync.native(absolute);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        real = absolute;
+    }
+    return process.platform === "win32" ? real.toLowerCase() : real;
+}
+export function codexProjectServerKey(root) {
+    const canonical = canonicalProjectRoot(root);
+    const slug = path.basename(canonical).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "project";
+    return `${SERVER_NAME}-${slug}-${createHash("sha256").update(canonical).digest("hex").slice(0, 12)}`;
+}
+function stringValue(value) {
+    return value.startsWith("'") ? value.slice(1, -1) : JSON.parse(value);
+}
+/** 仅处理本安装器的单行参数形式；复杂 TOML 明确拒绝，不猜测或输出配置原文。 */
+export function findCodexProjectEntry(text, root) {
+    if (text.includes('"""') || text.includes("'''"))
+        throw new Error("配置包含多行字符串，自动升级无法安全确认段落边界；未修改配置。");
+    const canonical = canonicalProjectRoot(root), expected = codexProjectServerKey(root);
+    const matches = [];
+    const headers = [...text.matchAll(/^(?:\uFEFF)?[ \t]*\[mcp_servers\.(?:([A-Za-z0-9_-]+)|"([^"\r\n]+)"|'([^'\r\n]+)')\][ \t]*(?:#.*)?\r?$/gm)];
+    for (const header of headers) {
+        const name = header[1] ?? header[2] ?? header[3];
+        if (name !== SERVER_NAME && !name.startsWith(SERVER_NAME + "-"))
+            continue;
+        const start = header.index + header[0].length;
+        const next = text.slice(start).search(/^[ \t]*\[/m);
+        const end = next < 0 ? text.length : start + next;
+        const section = text.slice(start, end);
+        const commands = [...section.matchAll(/^[ \t]*command[ \t]*=[ \t]*("[^\r\n]*"|'[^\r\n]*')[ \t]*(?:#.*)?\r?$/gm)];
+        const arrays = [...section.matchAll(/^[ \t]*args[ \t]*=[ \t]*(\[[^\r\n]*\])[ \t]*(?:#.*)?\r?$/gm)];
+        let entry;
+        try {
+            if (commands.length !== 1 || arrays.length !== 1)
+                throw new Error();
+            const command = stringValue(commands[0][1]), args = JSON.parse(arrays[0][1]);
+            if (typeof command !== "string" || !Array.isArray(args) || !args.every((value) => typeof value === "string"))
+                throw new Error();
+            const positions = args.flatMap((value, index) => value === "--root" ? [index] : []);
+            if (positions.length !== 1 || !path.isAbsolute(args[positions[0] + 1] ?? ""))
+                throw new Error();
+            const filters = [...section.matchAll(/^[ \t]*(enabled_tools|disabled_tools)[ \t]*=[ \t]*(\[[^\r\n]*\])/gm)];
+            entry = { name, command, args, root: canonicalProjectRoot(args[positions[0] + 1]), start, end,
+                enabled: !/^[ \t]*enabled[ \t]*=[ \t]*false\b/m.test(section),
+                toolFilters: [...section.matchAll(/^[ \t]*(?:enabled_tools|disabled_tools)[ \t]*=/gm)].length !== filters.length || filters.some((filter) => filter[1] === "enabled_tools" || JSON.parse(filter[2]).length > 0) };
+        }
+        catch { /* 无法识别的条目不会被覆盖 */ }
+        if (name === expected && entry?.root !== canonical)
+            throw new Error(`已有 [mcp_servers.${name}] 指向不同项目或无法确认 --root；未修改配置。`);
+        if (!entry && (name === SERVER_NAME || name === expected.slice(0, -13)))
+            throw new Error("旧 pm-mcp 条目的项目根无法确认，拒绝创建可能重复的启动项。");
+        if (entry?.root === canonical)
+            matches.push(entry);
+    }
+    if (matches.length > 1)
+        throw new Error("多个 pm-mcp 条目指向同一项目，需先明确保留哪个；未修改配置。");
+    return matches[0];
+}
+export function readCodexConfig(file) {
+    if (!fs.existsSync(file))
+        return "";
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 2 * 1024 * 1024)
+        throw new Error("Codex 配置必须为有界普通文件，禁止链接。");
+    return fs.readFileSync(file, "utf8");
+}
+export function isPackageLaunch(entry) {
+    return /^npx(?:\.(?:cmd|exe))?$/i.test(path.basename(entry.command)) && entry.args.length === 4 && entry.args[0] === "-y" &&
+        /^@luckychen1993\/pm-mcp(?:@[^\s]+)?$/.test(entry.args[1]) && entry.args[2] === "--root";
+}
+/**
+ * 校验启动项指向本包已构建的本地入口（`dist/index.js` 或 `src/index.ts`）。
+ *
+ * 与 `isLocalLaunch` 的区别：**不要求 `--root`**。WorkBuddy 等多项目宿主
+ * 以会话工作区作为子进程 cwd，服务端按 cwd 解析项目根，此时参数里没有 `--root`。
+ */
+export function isLocalServerEntry(entry) {
+    if (!/^node(?:\.exe)?$/i.test(path.basename(entry.command)) || entry.args.length < 1 || !path.isAbsolute(entry.args[0]))
+        return false;
+    const file = path.resolve(entry.args[0]);
+    if (!/^(?:index|cli)\.(?:js|ts)$/.test(path.basename(file)))
+        return false;
+    try {
+        const stat = fs.lstatSync(file);
+        return stat.isFile() && !stat.isSymbolicLink() && JSON.parse(fs.readFileSync(path.join(path.dirname(file), "..", "package.json"), "utf8")).name === "@luckychen1993/pm-mcp";
+    }
+    catch {
+        return false;
+    }
+}
+export function isLocalLaunch(entry) {
+    return entry.args.length === 3 && entry.args[1] === "--root" && isLocalServerEntry(entry);
+}
+export function appendCodexProjectConfig(file, root, force, dryRun, log, local) {
+    const absolute = path.resolve(file), existing = readCodexConfig(absolute);
+    const entry = findCodexProjectEntry(existing, root);
+    const desired = local ?? { command: "npx", args: ["-y", PACKAGE_SPEC, "--root", path.resolve(root).replace(/\\/g, "/")] };
+    let updated;
+    if (entry) {
+        if (!force) {
+            log(`[skip] Codex already has [mcp_servers.${entry.name}] for this project; --force 可升级，现有配置保留。`);
+            return;
+        }
+        if (!isPackageLaunch(entry) && !isLocalLaunch(entry))
+            throw new Error("当前启动项不是可识别的 pm-mcp npx/node 形式；未修改配置。");
+        if (entry.command === desired.command && JSON.stringify(entry.args) === JSON.stringify(desired.args)) {
+            log("[skip] 启动配置已是目标版本；仍需通过 doctor 核验连接。");
+            return;
+        }
+        const section = existing.slice(entry.start, entry.end);
+        const replace = (name, value, input) => input.replace(new RegExp(`^([ \\t]*${name}[ \\t]*=[ \\t]*)(?:\\[[^\\r\\n]*\\]|"[^\\r\\n]*"|'[^\\r\\n]*')([ \\t]*(?:#.*)?)(\\r?)$`, "m"), (_all, prefix, suffix, cr) => prefix + value + suffix + cr);
+        const patched = replace("args", JSON.stringify(desired.args), replace("command", JSON.stringify(desired.command), section));
+        updated = existing.slice(0, entry.start) + patched + existing.slice(entry.end);
+        const checked = findCodexProjectEntry(updated, root);
+        if (!checked || checked.command !== desired.command || JSON.stringify(checked.args) !== JSON.stringify(desired.args))
+            throw new Error("启动配置替换验证失败，未写入。");
+        log(`[${dryRun ? "plan" : "upgrade"}] Codex [mcp_servers.${entry.name}]；仅替换 command/args，保留其余设置。`);
+    }
+    else {
+        const separator = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+        const name = codexProjectServerKey(root);
+        updated = existing + `${separator}\n[mcp_servers.${name}]\ncommand = ${JSON.stringify(desired.command)}\nargs = ${JSON.stringify(desired.args)}\n`;
+        log(`[${dryRun ? "plan" : "write"}] Codex: ${absolute}`);
+        log(`[entry] [mcp_servers.${name}] → --root ${path.resolve(root)}`);
+    }
+    if (dryRun)
+        return;
+    fs.mkdirSync(path.dirname(absolute), { recursive: true });
+    if (readCodexConfig(absolute) !== existing)
+        throw new Error("配置在准备期间发生变化；未写入，请重新预览。");
+    if (fs.existsSync(absolute))
+        fs.copyFileSync(absolute, `${absolute}.backup-${Date.now()}-${randomUUID()}`, fs.constants.COPYFILE_EXCL);
+    atomicWrite(absolute, updated);
+}