@luckychen1993/pm-mcp 0.4.0 → 0.6.0

package/dist/index.js

@@ -1,33 +1,25 @@
 #!/usr/bin/env node
+/** 入口与装配：解析项目根、创建 server、按域注册 tools/resources/prompts、启动 watcher。 */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { resolveRoot, isInitialized, ensurePmRuntimeIgnored } from "./paths.js";
+import { resolveRootWithSource, recordRootResolution, isInitialized, ensurePmRuntimeIgnored } from "./paths.js";
 import { registerAllTools } from "./tools.js";
-import { loadRoadmap, loadTasks } from "./store.js";
-import { renderRoadmap } from "./roadmap.js";
-import { buildChangelog } from "./dashboard.js";
-import { dashboardFile, pmPath } from "./paths.js";
+import { registerResources } from "./resources.js";
+import { registerPrompts } from "./prompts.js";
 import { startWatcher } from "./index-store.js";
-import { auditGovernance } from "./governance-audit.js";
-import { buildPortfolioReport, loadPortfolioProject } from "./portfolio.js";
-import fs from "node:fs";
-import path from "node:path";
-import { listAcceptanceBaselines } from "./acceptance-tools.js";
-import { AcceptanceReportSchema } from "./acceptance-report.js";
-import { runCoalescedRead } from "./idempotency.js";
-import { recordUsage } from "./tool-base.js";
 import { logRuntime } from "./usage-log.js";
 import { VERSION } from "./version.js";
-import { taskPage } from "./task-pagination.js";
-import { budgetLines } from "./tool-base.js";
-/* --root 参数 > PM_ROOT 环境变量 > 启动时工作目录 */
+/* 启动根只是默认值：--root 参数 > PM_ROOT > 适配器提示 > 已初始化的启动目录 > 客户端工作区提示 > 启动时工作目录。
+   客户端（如 Qoder）会把一个常驻子进程复用给所有窗口，真正的调用方工作区由 caller-workspace 按请求认领。 */
 const argv = process.argv.slice(2);
 let explicitRoot;
 for (let i = 0; i < argv.length; i++) {
     if (argv[i] === "--root" && argv[i + 1])
         explicitRoot = argv[i + 1];
 }
-const root = resolveRoot(explicitRoot);
+const resolution = resolveRootWithSource(explicitRoot);
+recordRootResolution(resolution);
+const root = resolution.root;
 const server = new McpServer({ name: "pm-mcp", version: VERSION }, {
     instructions: [
         `pm-mcp ${VERSION}。get_status 返回实际运行版本与项目根；配置修改后须重连核验。list_tasks 有 has_more 时保持过滤条件并使用 next_cursor 续取，不能把一页当全量。feature/fix 默认要求 tests_observed，未知计数不冒充测试通过。`,
@@ -37,195 +29,8 @@ const server = new McpServer({ name: "pm-mcp", version: VERSION }, {
     ].join(" "),
 });
 registerAllTools(server, root);
-/* -------------------------------- Resources ------------------------------- */
-function safeText(fn) {
-    try {
-        return fn();
-    }
-    catch (e) {
-        return `（不可用: ${e.message}）`;
-    }
-}
-async function resourceText(name, fn) {
-    const started = Date.now();
-    try {
-        const text = (await runCoalescedRead(root, `resource:${name}`, {}, () => safeText(fn))).text;
-        recordUsage(root, `resource:${name}`, "read", started, { ok: true, text });
-        return text;
-    }
-    catch (error) {
-        recordUsage(root, `resource:${name}`, "read", started, { ok: false, error: error.message });
-        throw error;
-    }
-}
-server.registerResource("dashboard", "pm://dashboard", { description: "项目仪表盘（与仓库根 PROJECT.md 同源），路线图/健康摘要/任务/功能清单" }, async (uri) => ({
-    contents: [
-        {
-            uri: uri.href,
-            mimeType: "text/markdown",
-            text: await resourceText("dashboard", () => fs.readFileSync(dashboardFile(root), "utf8")),
-        },
-    ],
-}));
-server.registerResource("roadmap", "pm://roadmap", { description: "路线图（里程碑进度 + 活跃里程碑任务明细）" }, async (uri) => ({
-    contents: [
-        {
-            uri: uri.href,
-            mimeType: "text/markdown",
-            text: await resourceText("roadmap", () => renderRoadmap(loadRoadmap(root).milestones, loadTasks(root).tasks, 2).join("\n")),
-        },
-    ],
-}));
-server.registerResource("tasks", "pm://tasks", { description: "任务原始数据；大列表末尾返回 continuation，可通过 list_tasks 保持 include_done:true 连续取回后续任务" }, async (uri) => ({
-    contents: [
-        {
-            uri: uri.href,
-            mimeType: "application/json",
-            text: await resourceText("tasks", () => {
-                const data = loadTasks(root);
-                const tasks = data.tasks;
-                // 资源也要守 token 预算：全量 dump 大账本会吃爆上下文（截断后仍是合法 JSON）
-                if (tasks.length <= 100)
-                    return JSON.stringify(tasks, null, 2);
-                const page = taskPage(root, { include_done: true, page_size: 100 }, budgetLines(root) - 4, data);
-                const shown = tasks.slice(0, page.returned);
-                shown.push({
-                    id: `_TRUNCATED_${tasks.length - page.returned}`,
-                    title: `…本次输出已截断，另有 ${tasks.length - page.returned} 个任务，用 continuation 连续读取`,
-                    continuation: { tool: "list_tasks", arguments: { include_done: true, cursor: page.next_cursor } },
-                });
-                return JSON.stringify(shown, null, 2);
-            }),
-        },
-    ],
-}));
-server.registerResource("changelog", "pm://changelog", { description: "变更日志（由 sessions.json 生成的人类可读版本）" }, async (uri) => ({
-    contents: [
-        {
-            uri: uri.href,
-            mimeType: "text/markdown",
-            text: await resourceText("changelog", () => buildChangelog(root)),
-        },
-    ],
-}));
-server.registerResource("architecture", "pm://architecture", { description: "跨文件/模块/语言治理审计：语义覆盖、依赖边界、接口、循环与质量矩阵" }, async (uri) => ({
-    contents: [{ uri: uri.href, mimeType: "text/markdown", text: await resourceText("architecture", () => auditGovernance(root, 150).report) }],
-}));
-server.registerResource("portfolio", "pm://portfolio", { description: "当前项目的组合视图与跨仓依赖/版本风险" }, async (uri) => ({
-    contents: [{
-            uri: uri.href,
-            mimeType: "application/json",
-            text: await resourceText("portfolio", () => JSON.stringify(buildPortfolioReport({ projects: [loadPortfolioProject(root)], projectsRequested: 1 }), null, 2)),
-        }],
-}));
-server.registerResource("acceptance", "pm://acceptance", { description: "标准化产品验收概览：版本化预批准基线与最近一次机器判定报告" }, async (uri) => ({
-    contents: [{
-            uri: uri.href,
-            mimeType: "application/json",
-            text: await resourceText("acceptance", () => {
-                const reportDir = pmPath(root, "acceptance", "reports");
-                let latestReport = null;
-                if (fs.existsSync(reportDir)) {
-                    const candidates = fs.readdirSync(reportDir, { withFileTypes: true })
-                        .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
-                        .map((entry) => ({ name: entry.name, mtime: fs.statSync(path.join(reportDir, entry.name)).mtimeMs }))
-                        .sort((a, b) => b.mtime - a.mtime || a.name.localeCompare(b.name));
-                    if (candidates[0])
-                        latestReport = AcceptanceReportSchema.parse(JSON.parse(fs.readFileSync(path.join(reportDir, candidates[0].name), "utf8")));
-                }
-                return JSON.stringify({ baselines: listAcceptanceBaselines(root), latest_report: latestReport }, null, 2);
-            }),
-        }],
-}));
-/* --------------------------------- Prompts -------------------------------- */
-server.registerPrompt("start-session", { description: "开工仪式：恢复项目上下文，从断点续做，不靠回忆。" }, () => ({
-    messages: [
-        {
-            role: "user",
-            content: {
-                type: "text",
-                text: [
-                    "按以下顺序恢复项目上下文（本项目由 pm-mcp 管理，状态以 .pm/ 为准，不要凭记忆陈述）：",
-                    "1. 调用 get_status：了解阶段、里程碑进度、进行中任务及其 checkpoint 下一步。",
-                    "2. 若要动的模块不清楚，先 search_code 定位到具体文件与行，再读文件——三段式定位，不要全量读代码。",
-                    "3. 陈述本次计划：要做哪个任务、动哪些文件、验收标准是什么。",
-                    "4. 过程纪律：走捷径就 add_task(type=debt) 登记债务；修 bug 完成后 log_debug 记根因；长任务随手 checkpoint。",
-                ].join("\n"),
-            },
-        },
-    ],
-}));
-server.registerPrompt("end-session", { description: "收工仪式：更新任务与里程碑、留断点、记会话——把本次上下文写回仓库。" }, () => ({
-    messages: [
-        {
-            role: "user",
-            content: {
-                type: "text",
-                text: [
-                    "收工前依次完成（顺序执行，缺一不可）：",
-                    "1. feature/fix 先执行适用测试，生成最新质量报告；update_task 置 done，给 result_note 与实际 files，record_session=true 可一并归档。",
-                    "2. 未完成的任务：checkpoint 保存「进展 + 下一步具体动作」。",
-                    "3. 本次落地的功能：register_feature 登记（入口文件 + 测试文件）。",
-                    "4. 修过的 bug：log_debug 记录症状/根因/修法/验证。",
-                    "5. 走过的捷径：add_task(type=debt) 登记债务，别让它在沉默中腐烂。",
-                    "6. update_task 已返回自动会话编号时，不重复 log_session；否则用 log_session 记录真实改动清单。纯问答不需要另建任务或反复写会话。",
-                    "7. 若到达里程碑节点：update_milestone 流转状态；可 snapshot_codebase 拍快照 + audit_structure 对账。",
-                ].join("\n"),
-            },
-        },
-    ],
-}));
-server.registerPrompt("onboard", { description: "入职简报工作流：引导客户端为新成员（人或 AI）生成项目现状一页纸。" }, () => ({
-    messages: [
-        {
-            role: "user",
-            content: {
-                type: "text",
-                text: [
-                    "为新加入的成员（人或 AI）生成入职简报，数据全部来自 .pm/ 状态，不要编造：",
-                    "1. 读 pm://dashboard（或 PROJECT.md）：项目是什么、路线图到哪、健康状态如何。",
-                    "2. list_decisions + 阅读最近 3 条 ADR：理解关键取舍的「为什么」。",
-                    "3. list_features：了解已有功能地图与各功能入口文件。",
-                    "4. get_status：当前焦点与断点。",
-                    "5. 读 pm://architecture 与 pm://portfolio：模块 owner、公开接口、跨语言质量矩阵和跨仓版本风险。",
-                    "输出一页纸简报：项目一句话 / 技术栈与模块 / 路线图现状 / 关键决策与红线 / 模块与接口边界 / 当前焦点与下一步 / 哪里有坑（债务、安全、语义与跨仓风险）。",
-                ].join("\n"),
-            },
-        },
-    ],
-}));
-server.registerPrompt("architecture-review", { description: "跨文件/模块/语言架构评审：先取证，再判断影响和门禁。" }, () => ({
-    messages: [{
-            role: "user",
-            content: {
-                type: "text",
-                text: [
-                    "按证据完成跨模块/跨语言架构评审：",
-                    "1. 读取 pm://architecture 或调用 audit_governance，先检查语义覆盖、unresolved、owner、私有接口、循环和边界违规。",
-                    "2. 对本次变更调用 impact_analysis，列出反向依赖文件与模块；未知文件不得忽略。",
-                    "3. 调用 plan_quality_matrix；这一步只是计划，不能声称测试通过。",
-                    "4. 只有用户明确要求执行时才调用 run_quality_matrix(confirm_execute=true)，并分别报告每种语言的真实结果。",
-                    "5. 跨仓变更读取 pm://portfolio，核对依赖目标、版本约束、加载失败与仓库循环。",
-                ].join("\n"),
-            },
-        }],
-}));
-server.registerPrompt("acceptance-review", { description: "标准化终验：冻结质量基线后执行证据核验，不能把开发者自测冒充认证。" }, () => ({
-    messages: [{
-            role: "user",
-            content: {
-                type: "text",
-                text: [
-                    "按 pm-mcp 的标准化验收闭环执行，不得事后调低阈值：",
-                    "1. list_acceptance_baselines 并读取目标基线，确认 ISO/IEC 25010 九特性适用性、量化指标、风险和测试双向追踪。",
-                    "2. 只有产品负责人审阅 draft fingerprint 后，才能 approve_acceptance_baseline；批准后的同版本不可修改。",
-                    "3. 执行基线定义的质量、治理、性能与安全测试；失败、跳过、缺工具和过期证据都不得写成通过。",
-                    "4. evaluate_acceptance 会重算项目内证据 SHA-256，并由机器生成不可覆盖的 JSON/Markdown 报告。",
-                    "5. 分开陈述：第一方范围内验收、独立评价、托管 CI、生产证据和 ISO 认证；任何一层都不能冒充另一层。",
-                ].join("\n"),
-            },
-        }],
-}));
+registerResources(server, root);
+registerPrompts(server);
 /* ---------------------------------- 启动 ---------------------------------- */
 await server.connect(new StdioServerTransport());
 // 超大项目核心：server 常驻期间用递归 watcher 持续保鲜 SQLite 索引，
@@ -238,4 +43,4 @@ if (isInitialized(root)) {
 }
 logRuntime(root, "info", "server.ready", `pid=${process.pid} node=${process.versions.node}`);
 // stdio 是协议通道，日志只能走 stderr
-console.error(`[pm-mcp] ready. project root: ${root}`);
+console.error(`[pm-mcp] ready. default project root: ${root} (source: ${resolution.source})`);

package/dist/knowledge-tools.js

@@ -10,15 +10,16 @@ import { budgetLines, toolR, toolW } from "./tool-base.js";
 import { now } from "./types.js";
 import { appendSession } from "./session-log.js";
 import { captureFileHashes } from "./git-state.js";
-export function registerFeatureTools(server, root) {
-    toolW(server, root, "register_feature", "登记功能（回答「这个项目有哪些功能」）。entry_files=入口文件（漂移对账锚点），test_files=测试文件（测试背书）。", {
+export function registerFeatureTools(server, startupRoot) {
+    toolW(server, startupRoot, "register_feature", "登记功能（回答「这个项目有哪些功能」）。entry_files=入口文件（漂移对账锚点），test_files=测试文件（测试背书）。", {
         name: z.string().min(1),
         description: z.string().optional(),
         entry_files: z.array(z.string()).optional().describe("入口/实现文件相对路径"),
         module: z.string().optional().describe("所属模块"),
         test_files: z.array(z.string()).optional().describe("对应测试文件"),
         status: z.enum(["planned", "implemented", "deprecated"]).optional().describe("默认 implemented"),
-    }, (args) => {
+    }, (args, ctx) => {
+        const root = ctx.root;
         requireInitialized(root);
         const data = loadFeatures(root);
         const id = nextId("F", data.seq);
@@ -43,7 +44,8 @@ export function registerFeatureTools(server, root) {
             : "";
         return `✅ 功能 ${id}「${args.name}」已登记${args.module ? `（${args.module}）` : ""}。audit_structure 会核对其入口文件是否真实存在（防幻觉对账）。${hint}`;
     });
-    toolR(server, root, "list_features", "列出功能清单（可按模块/状态过滤）。", { module: z.string().optional(), status: z.enum(["planned", "implemented", "deprecated"]).optional() }, (args) => {
+    toolR(server, startupRoot, "list_features", "列出功能清单（可按模块/状态过滤）。", { module: z.string().optional(), status: z.enum(["planned", "implemented", "deprecated"]).optional() }, (args, ctx) => {
+        const root = ctx.root;
         requireInitialized(root);
         let list = loadFeatures(root).features;
         if (args.module)
@@ -58,13 +60,14 @@ export function registerFeatureTools(server, root) {
         return foldLines([`共 ${list.length} 个功能:`, ...L], { maxLines: budgetLines(root), hint: "用 module/status 过滤" });
     });
 }
-export function registerDecisionTools(server, root) {
-    toolW(server, root, "record_decision", "记录架构决策（ADR）：为什么这么选、决定了什么、有什么后果。认知债务的解药——半年后还能回答「当时为什么」。", {
+export function registerDecisionTools(server, startupRoot) {
+    toolW(server, startupRoot, "record_decision", "记录架构决策（ADR）：为什么这么选、决定了什么、有什么后果。认知债务的解药——半年后还能回答「当时为什么」。", {
         title: z.string().min(1),
         context: z.string().describe("背景与约束（为什么需要做选择）"),
         decision: z.string().describe("决定与理由"),
         consequences: z.string().optional().describe("后果/代价/被放弃的方案"),
-    }, (args) => {
+    }, (args, ctx) => {
+        const root = ctx.root;
         requireInitialized(root);
         ensureDecisionDir(root);
         const existing = fs.readdirSync(decisionsDir(root)).filter((n) => n.endsWith(".md"));
@@ -97,7 +100,8 @@ export function registerDecisionTools(server, root) {
         refreshDerived(root);
         return `✅ 决策已记录: .pm/decisions/${file}（不可变编号，git 友好）。search_knowledge 可检索。`;
     });
-    toolR(server, root, "list_decisions", "列出全部架构决策（ADR）。", {}, () => {
+    toolR(server, startupRoot, "list_decisions", "列出全部架构决策（ADR）。", {}, (_args, ctx) => {
+        const root = ctx.root;
         requireInitialized(root);
         const dir = decisionsDir(root);
         const names = fs.existsSync(dir) ? fs.readdirSync(dir).filter((n) => n.endsWith(".md")).sort() : [];
@@ -109,13 +113,14 @@ export function registerDecisionTools(server, root) {
 function ensureDecisionDir(root) {
     fs.mkdirSync(decisionsDir(root), { recursive: true });
 }
-export function registerSessionTools(server, root) {
-    toolW(server, root, "log_session", "收工仪式：记录本次会话（做了什么、改了哪些文件、下一步）。files 是变更足迹（churn 账与波及面告警的数据源），务必如实列出。", {
+export function registerSessionTools(server, startupRoot) {
+    toolW(server, startupRoot, "log_session", "收工仪式：记录本次会话（做了什么、改了哪些文件、下一步）。files 是变更足迹（churn 账与波及面告警的数据源），务必如实列出。", {
         summary: z.string().min(1).describe("本次做了什么（一两句）"),
         files: z.array(z.string()).optional().describe("本次改动/新增/删除的文件（相对路径）"),
         next_steps: z.array(z.string()).optional().describe("留给下次的下一步"),
         author: z.string().optional().describe("署名：zcode / codex / human:名字"),
-    }, (args, hashes) => {
+    }, (args, ctx, hashes) => {
+        const root = ctx.root;
         requireInitialized(root);
         const project = loadProject(root);
         const id = appendSession(root, args, hashes);
@@ -125,15 +130,16 @@ export function registerSessionTools(server, root) {
             L.push(`⚠️ 本次波及 ${(args.files ?? []).length} 个文件，超过阈值 ${project.budgets.sessionBlastRadius}——波及面过大，考虑拆任务或立重构任务。`);
         }
         return L.join("\n");
-    }, (args) => { requireInitialized(root); return captureFileHashes(root, args.files ?? []); });
-    toolW(server, root, "log_debug", "记录调试过程：症状 / 根因 / 修法 / 怎么验证的。调试知识账——下次同样的错不用从零猜，search_knowledge 可查。", {
+    }, (args, ctx) => { const root = ctx.root; requireInitialized(root); return captureFileHashes(root, args.files ?? []); });
+    toolW(server, startupRoot, "log_debug", "记录调试过程：症状 / 根因 / 修法 / 怎么验证的。调试知识账——下次同样的错不用从零猜，search_knowledge 可查。", {
         symptom: z.string().describe("症状：什么现象、报什么错"),
         root_cause: z.string().describe("根因（诊断出的真正原因，不是表面现象）"),
         fix: z.string().describe("修法"),
         verified_how: z.string().optional().describe("怎么确认修好了"),
         files: z.array(z.string()).optional(),
         task_id: z.string().optional().describe("关联任务 id"),
-    }, (args) => {
+    }, (args, ctx) => {
+        const root = ctx.root;
         requireInitialized(root);
         const data = loadDebugLog(root);
         const id = nextId("D", data.seq, 4);
@@ -154,27 +160,30 @@ export function registerSessionTools(server, root) {
         return `✅ 调试记录 ${id} 已存档。这份诊断经验已进入项目知识库。`;
     });
 }
-export function registerSearchTools(server, root) {
-    toolR(server, root, "search_code", "在真实代码里检索（防幻觉事中防线）：谈某个功能/文件之前先搜实码。返回 file:line 片段而非整文件（token 经济）。默认按字面量匹配；regex=true 时按 JavaScript 正则（仅在你确需时开启）。", {
+export function registerSearchTools(server, startupRoot) {
+    toolR(server, startupRoot, "search_code", "在真实代码里检索（防幻觉事中防线）：谈某个功能/文件之前先搜实码。返回 file:line 片段而非整文件（token 经济）。默认按字面量匹配；regex=true 时按 JavaScript 正则（仅在你确需时开启）。", {
         query: z.string().min(1).describe("关键词（默认字面量匹配）"),
         glob: z.string().optional().describe("限定文件范围，如 src/**/*.ts"),
         max_results: z.number().int().min(1).max(100).optional().describe("默认 30"),
         regex: z.boolean().optional().describe("默认 false；true 时 query 按正则解释"),
-    }, (args) => {
+    }, (args, ctx) => {
+        const root = ctx.root;
         requireInitialized(root);
         const res = searchCode(root, args.query, args.glob, args.max_results ?? 30, args.regex ?? false);
         return formatCodeSearch(res, args.query);
     });
-    toolR(server, root, "search_knowledge", "检索六类项目知识源（ADR/任务/功能/会话/调试记录/文件索引）——回答「之前为什么这么做」「上次这个错怎么解的」，用历史结论代替重新推理。代码内容请用 search_code。", { query: z.string().min(1) }, (args) => {
+    toolR(server, startupRoot, "search_knowledge", "检索六类项目知识源（ADR/任务/功能/会话/调试记录/文件索引）——回答「之前为什么这么做」「上次这个错怎么解的」，用历史结论代替重新推理。代码内容请用 search_code。", { query: z.string().min(1) }, (args, ctx) => {
+        const root = ctx.root;
         requireInitialized(root);
         return searchKnowledge(root, args.query);
     });
-    toolW(server, root, "annotate_file", "给文件登记一行用途（文件用途索引）：之后任何会话靠索引定位，不用打开文件。引用外部代码时可登记 source/license（provenance）。", {
+    toolW(server, startupRoot, "annotate_file", "给文件登记一行用途（文件用途索引）：之后任何会话靠索引定位，不用打开文件。引用外部代码时可登记 source/license（provenance）。", {
         path: z.string().min(1).describe("相对路径"),
         purpose: z.string().min(1).describe("一句话用途"),
         source: z.string().optional().describe("代码来源（URL/仓库），如引用自外部"),
         license: z.string().optional().describe("该文件引用代码的许可证"),
-    }, (args) => {
+    }, (args, ctx) => {
+        const root = ctx.root;
         requireInitialized(root);
         const rel = normSep(args.path);
         if (!fs.existsSync(path.join(root, rel))) {

package/dist/paths.js

@@ -2,10 +2,68 @@ import path from "node:path";
 import fs from "node:fs";
 import os from "node:os";
 import { randomUUID } from "node:crypto";
-/** 项目根解析顺序：--root 参数 > PM_ROOT 环境变量 > 当前工作目录 */
+/** 客户端注入的工作区提示：部分客户端（如 Qoder）拉起 MCP 子进程时 cwd 是安装目录，工作区只存在于环境变量 */
+export const WORKSPACE_HINT_ENV_VARS = ["QODER_WORKER_CWD"];
+/** 启动期适配器交下来的工作区提示与它的真实来历（适配器自己解析的，不能再报成 --root） */
+export const ROOT_HINT_ENV_VAR = "PM_MCP_ROOT_HINT";
+export const ROOT_HINT_SOURCE_ENV_VAR = "PM_MCP_ROOT_HINT_SOURCE";
+/** 配置里写了 ${VAR} 但客户端没有插值时，这种字面量不能当路径用 */
+function unexpanded(value) {
+    return value.includes("${") || value.includes("}");
+}
+function isDir(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function usable(value) {
+    return !!value && value.trim().length > 0 && !unexpanded(value.trim());
+}
+function workspaceHints() {
+    const out = [];
+    for (const name of WORKSPACE_HINT_ENV_VARS) {
+        const value = process.env[name]?.trim();
+        if (value && !unexpanded(value))
+            out.push({ name, value });
+    }
+    return out;
+}
+/** 解析项目根并报告依据，供启动横幅与 get_status 核验 */
+export function resolveRootWithSource(explicit) {
+    const flag = explicit?.trim();
+    if (usable(flag))
+        return { root: path.resolve(flag), source: "--root" };
+    const pmRoot = process.env.PM_ROOT?.trim();
+    if (usable(pmRoot))
+        return { root: path.resolve(pmRoot), source: "PM_ROOT" };
+    const hint = process.env[ROOT_HINT_ENV_VAR]?.trim();
+    if (usable(hint) && isDir(hint)) {
+        const basis = process.env[ROOT_HINT_SOURCE_ENV_VAR]?.trim() || ROOT_HINT_ENV_VAR;
+        return { root: path.resolve(hint), source: `${basis}(spawn-time)` };
+    }
+    const cwd = process.cwd();
+    if (isInitialized(cwd))
+        return { root: path.resolve(cwd), source: "cwd" };
+    const hints = workspaceHints();
+    const chosen = hints.find((h) => isInitialized(h.value)) ?? hints.find((h) => isDir(h.value));
+    if (chosen)
+        return { root: path.resolve(chosen.value), source: chosen.name };
+    return { root: path.resolve(cwd), source: "cwd" };
+}
+/** 服务端启动时定格的一次解析；get_status 用它自证项目根从哪来 */
+let startupResolution = null;
+export function recordRootResolution(resolution) {
+    startupResolution = resolution;
+}
+export function rootResolution() {
+    return startupResolution;
+}
+/** 项目根解析顺序：--root 参数 > PM_ROOT > 已初始化的启动目录 > 客户端工作区提示 > 当前工作目录 */
 export function resolveRoot(explicit) {
-    const raw = explicit?.trim() || process.env.PM_ROOT?.trim() || process.cwd();
-    return path.resolve(raw);
+    return resolveRootWithSource(explicit).root;
 }
 export const PM_DIR = ".pm";
 export function pmPath(root, ...segs) {