metheus-governance-mcp-cli 0.2.148 → 0.2.152

package/cli.mjs

@@ -16,6 +16,7 @@ import {
   auditDirectHumanReplyWithAI,
   normalizeExecutionArtifacts,
   planRoleExecutionWithAI,
+  repairRoleExecutionPlanWithAI,
   resolveLocalAIExecutionModel,
   resolveGeminiReasoningConfig,
   suggestLocalAIModelDisplayName,
@@ -129,8 +130,12 @@ import {
   printRunnerResult,
 } from "./lib/runner-helpers.mjs";
 import {
+  createProjectEvidence as createProjectEvidenceImpl,
+  createProjectWorkItem as createProjectWorkItemImpl,
   createThreadComment as createThreadCommentImpl,
+  createWorkItemThread as createWorkItemThreadImpl,
   discoverArchiveThreadForDestination as discoverArchiveThreadForDestinationImpl,
+  linkWorkItemEvidence as linkWorkItemEvidenceImpl,
   listProjectChatDestinations as listProjectChatDestinationsImpl,
   listThreadComments as listThreadCommentsImpl,
   listUserBotsForRunner as listUserBotsForRunnerImpl,
@@ -1359,7 +1364,6 @@ function loadBotRunnerWorkspaceRegistry(options = {}) {
 }
 
 function saveBotRunnerConfig(nextConfig, filePath = botRunnerConfigFilePath()) {
-  saveBotRunnerWorkspaceRegistry(safeObject(nextConfig).projectMappings);
   const payload = serializeBotRunnerConfig(nextConfig);
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   fs.writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
@@ -1520,6 +1524,9 @@ function loadBotRunnerConfig(options = {}) {
     normalized.projectMappings = mergedProjectMappings;
     normalized.workspaceRegistryFilePath = workspaceRegistry.filePath;
     if (persistIfNeeded && (normalized.migrated || !fs.existsSync(filePath) || registryChanged || legacyProjectMappingsPresent)) {
+      if (registryChanged || legacyProjectMappingsPresent) {
+        saveBotRunnerWorkspaceRegistry(mergedProjectMappings, workspaceRegistry.filePath);
+      }
       saveBotRunnerConfig(normalized, filePath);
       normalized.migrated = false;
     }
@@ -1533,6 +1540,42 @@ function loadBotRunnerConfig(options = {}) {
   }
 }
 
+function normalizeProjectWorkspaceMappingSource(rawSource) {
+  return String(rawSource || "").trim().toLowerCase();
+}
+
+function isAutomaticProjectWorkspaceMappingSource(rawSource) {
+  const source = normalizeProjectWorkspaceMappingSource(rawSource);
+  return [
+    "ctxpack_sync",
+    "ctxpack_sync_current",
+    "ctxpack_sync_write",
+    "project_tool_workspace_signal",
+  ].includes(source);
+}
+
+function resolveStableProjectWorkspaceCandidate(projectID, workspaceDir) {
+  const normalizedWorkspaceDir = sanitizeWorkspaceCandidate(workspaceDir);
+  if (!isUUID(projectID)) {
+    return normalizedWorkspaceDir;
+  }
+  const config = loadBotRunnerConfig({ persistIfNeeded: true });
+  const existing = normalizeBotRunnerProjectMapping(projectID, config.projectMappings?.[projectID]);
+  if (!existing.workspaceDir) {
+    return normalizedWorkspaceDir;
+  }
+  if (!normalizedWorkspaceDir) {
+    return existing.workspaceDir;
+  }
+  if (
+    isSameOrChildPath(normalizedWorkspaceDir, existing.workspaceDir)
+    || isSameOrChildPath(existing.workspaceDir, normalizedWorkspaceDir)
+  ) {
+    return existing.workspaceDir;
+  }
+  return existing.workspaceDir;
+}
+
 function rememberProjectWorkspaceMapping({ projectID, workspaceDir, source }) {
   if (!isUUID(projectID)) {
     return { ok: false, updated: false, reason: "invalid project_id" };
@@ -1546,6 +1589,7 @@ function rememberProjectWorkspaceMapping({ projectID, workspaceDir, source }) {
   }
   const config = loadBotRunnerConfig({ persistIfNeeded: true });
   const existing = normalizeBotRunnerProjectMapping(projectID, config.projectMappings?.[projectID]);
+  const normalizedSource = String(source || existing.source || "ctxpack_sync").trim() || "ctxpack_sync";
   if (existing.workspaceDir && isSameOrChildPath(normalizedWorkspaceDir, existing.workspaceDir)) {
     return {
       ok: true,
@@ -1570,24 +1614,38 @@ function rememberProjectWorkspaceMapping({ projectID, workspaceDir, source }) {
       workspaceDir: normalizedWorkspaceDir,
     };
   }
-  const nextConfig = {
-    ...config,
-    projectMappings: {
-      ...safeObject(config.projectMappings),
-      [projectID]: {
-        projectID,
-        workspaceDir: normalizedWorkspaceDir,
-        source: String(source || existing.source || "ctxpack_sync").trim() || "ctxpack_sync",
-        updatedAt: new Date().toISOString(),
-      },
+  if (
+    existing.workspaceDir
+    && !isSameOrChildPath(existing.workspaceDir, normalizedWorkspaceDir)
+    && !isSameOrChildPath(normalizedWorkspaceDir, existing.workspaceDir)
+    && isAutomaticProjectWorkspaceMappingSource(normalizedSource)
+  ) {
+    return {
+      ok: true,
+      updated: false,
+      filePath: config.filePath,
+      workspaceRegistryFilePath: config.workspaceRegistryFilePath,
+      projectID,
+      workspaceDir: existing.workspaceDir,
+      reason: "existing workspace mapping preserved over unrelated automatic signal",
+    };
+  }
+  const nextProjectMappings = {
+    ...safeObject(config.projectMappings),
+    [projectID]: {
+      projectID,
+      workspaceDir: normalizedWorkspaceDir,
+      source: normalizedSource,
+      updatedAt: new Date().toISOString(),
     },
   };
-  const filePath = saveBotRunnerConfig(nextConfig, config.filePath);
+  const workspaceRegistryFilePath = config.workspaceRegistryFilePath || botRunnerWorkspaceRegistryFilePath();
+  saveBotRunnerWorkspaceRegistry(nextProjectMappings, workspaceRegistryFilePath);
   return {
     ok: true,
     updated: true,
-    filePath,
-    workspaceRegistryFilePath: nextConfig.workspaceRegistryFilePath || botRunnerWorkspaceRegistryFilePath(),
+    filePath: config.filePath,
+    workspaceRegistryFilePath,
     projectID,
     workspaceDir: normalizedWorkspaceDir,
   };
@@ -1808,6 +1866,7 @@ function loadBotRunnerState() {
       return {
         filePath,
         routes: {},
+        sharedInboxes: {},
         migrated: false,
         migratedKeys: [],
         remainingAnonymousKeys: [],
@@ -1817,11 +1876,15 @@ function loadBotRunnerState() {
     const runnerConfig = loadBotRunnerConfig({ persistIfNeeded: true });
     const migratedState = migrateBotRunnerStateRoutes(safeObject(parsed?.routes), runnerConfig);
     if (migratedState.changed) {
-      saveBotRunnerState({ routes: migratedState.routes });
+      saveBotRunnerState({
+        routes: migratedState.routes,
+        sharedInboxes: safeObject(parsed?.shared_inboxes || parsed?.sharedInboxes),
+      });
     }
     return {
       filePath,
       routes: migratedState.routes,
+      sharedInboxes: safeObject(parsed?.shared_inboxes || parsed?.sharedInboxes),
       migrated: migratedState.changed,
       migratedKeys: migratedState.migratedKeys,
       remainingAnonymousKeys: migratedState.remainingAnonymousKeys,
@@ -1830,6 +1893,7 @@ function loadBotRunnerState() {
     return {
       filePath,
       routes: {},
+      sharedInboxes: {},
       migrated: false,
       migratedKeys: [],
       remainingAnonymousKeys: [],
@@ -1839,10 +1903,15 @@ function loadBotRunnerState() {
 
 function saveBotRunnerState(nextState) {
   const filePath = botRunnerStateFilePath();
+  let current = {};
+  try {
+    current = safeObject(tryJsonParse(fs.readFileSync(filePath, "utf8")));
+  } catch {}
   const payload = {
     version: 1,
     updated_at: new Date().toISOString(),
-    routes: safeObject(nextState?.routes),
+    routes: safeObject(nextState?.routes ?? current.routes),
+    shared_inboxes: safeObject(nextState?.sharedInboxes ?? nextState?.shared_inboxes ?? current.shared_inboxes ?? current.sharedInboxes),
   };
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   fs.writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
@@ -2978,6 +3047,235 @@ async function postJSONWithAuthHeaders(urlText, timeoutSeconds, token, payload,
   });
 }
 
+async function putJSONWithAuthHeaders(urlText, timeoutSeconds, token, payload, extraHeaders = {}) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(urlText);
+    const body = Buffer.from(JSON.stringify(payload));
+    const transport = url.protocol === "http:" ? http : https;
+    const req = transport.request(
+      {
+        protocol: url.protocol,
+        hostname: url.hostname,
+        port: url.port || (url.protocol === "http:" ? 80 : 443),
+        path: `${url.pathname}${url.search}`,
+        method: "PUT",
+        headers: {
+          "content-type": "application/json",
+          accept: "application/json",
+          authorization: `Bearer ${token}`,
+          "content-length": String(body.length),
+          ...extraHeaders,
+        },
+        timeout: Math.max(3, timeoutSeconds) * 1000,
+      },
+      (res) => {
+        const chunks = [];
+        res.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+        res.on("end", () => {
+          const text = Buffer.concat(chunks).toString("utf8");
+          const statusCode = Number(res.statusCode || 0);
+          if (statusCode >= 200 && statusCode < 300) {
+            resolve(text.trim());
+            return;
+          }
+          const err = new Error(text.trim() || `http ${statusCode}`);
+          err.statusCode = statusCode;
+          err.responseBody = text;
+          reject(err);
+        });
+      },
+    );
+    req.on("timeout", () => {
+      req.destroy(new Error("http timeout"));
+    });
+    req.on("error", reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+function inferCtxpackDocTypeFromPath(relativePath, artifactKind = "", existingDocType = "") {
+  const explicit = String(existingDocType || "").trim().toLowerCase();
+  if (explicit) {
+    return explicit;
+  }
+  const normalizedPath = sanitizeCtxpackRelativePath(relativePath).toLowerCase();
+  const normalizedKind = String(artifactKind || "").trim().toLowerCase();
+  if (!normalizedPath) {
+    return normalizedKind || "guide";
+  }
+  if (normalizedPath === "ctxpack.yaml") return "manifest";
+  if (normalizedPath === "readme.md") return "readme";
+  if (normalizedPath === "agenda.md" || normalizedPath.endsWith("/agenda.md")) return "agenda";
+  if (normalizedPath.startsWith("repo_map/")) return "repo_map";
+  if (normalizedPath.startsWith("evals/")) return "eval_rules";
+  if (normalizedPath.includes("invariant")) return "invariants";
+  if (normalizedPath.startsWith("rules/")) return "rule";
+  if (normalizedPath.includes("architecture")) return "architecture";
+  if (normalizedPath.includes("glossary")) return "glossary";
+  if (normalizedPath.includes("style")) return "style";
+  if (normalizedPath.includes("error") || normalizedPath.includes("logging")) return "errors_logging";
+  if (normalizedPath.includes("playbook") && normalizedPath.includes("debug")) return "playbook_debugging";
+  if (normalizedPath.includes("playbook") && normalizedPath.includes("release")) return "playbook_release";
+  if (normalizedPath.includes("playbook") && normalizedPath.includes("migration")) return "playbook_migrations";
+  if (normalizedKind === "spec") return "architecture";
+  if (normalizedKind === "plan") return "guide";
+  if (normalizedKind === "doc") return "guide";
+  return normalizedPath.endsWith(".yaml") || normalizedPath.endsWith(".yml") ? "manifest" : "guide";
+}
+
+function shouldIgnoreCtxpackArtifactPath(relativePath) {
+  const normalizedPath = sanitizeCtxpackRelativePath(relativePath).toLowerCase();
+  if (!normalizedPath) return true;
+  return (
+    normalizedPath === CTXPACK_META_FILENAME.toLowerCase()
+    || normalizedPath.startsWith(".metheus/")
+    || normalizedPath.startsWith(".claude/")
+    || normalizedPath.startsWith(".git/")
+    || normalizedPath.startsWith("node_modules/")
+  );
+}
+
+function writeWorkspaceCtxpackMeta({
+  siteBaseURL,
+  projectID,
+  workspaceDir,
+  ctxpackResponse,
+}) {
+  const resolvedWorkspaceDir = resolveWorkspaceDir(workspaceDir);
+  if (!resolvedWorkspaceDir) {
+    return;
+  }
+  const files = normalizeCtxpackFiles(safeObject(ctxpackResponse).files);
+  const payload = {
+    project_id: projectID,
+    ctxpack_id: String(ctxpackResponse?.ctxpack_id || "").trim(),
+    version_id: String(ctxpackResponse?.version_id || "").trim(),
+    version: String(ctxpackResponse?.version || "").trim(),
+    status: String(ctxpackResponse?.status || "").trim() || "draft",
+    files_count: files.length,
+    files: files.map((item) => ({
+      path: item.path,
+      doc_type: item.docType || "",
+    })),
+    source: `${String(siteBaseURL || "").replace(/\/+$/, "")}/api/v1/projects/${encodeURIComponent(projectID)}/ctxpack`,
+    synced_at: new Date().toISOString(),
+  };
+  fs.writeFileSync(
+    path.join(resolvedWorkspaceDir, CTXPACK_META_FILENAME),
+    `${JSON.stringify(payload, null, 2)}\n`,
+    "utf8",
+  );
+}
+
+async function replaceProjectCtxpackFiles({
+  siteBaseURL,
+  token,
+  timeoutSeconds,
+  actorUserID,
+  projectID,
+  workspaceDir,
+  artifacts = [],
+}) {
+  const resolvedWorkspaceDir = resolveStableProjectWorkspaceCandidate(projectID, workspaceDir) || resolveWorkspaceDir(workspaceDir);
+  if (!resolvedWorkspaceDir) {
+    throw new Error("workspace_dir is required to update project ctxpack");
+  }
+  if (!isUUID(projectID)) {
+    throw new Error("invalid project_id for ctxpack update");
+  }
+  const ctxpackURL = `${siteBaseURL}/api/v1/projects/${encodeURIComponent(projectID)}/ctxpack`;
+  const currentCtxpack = safeObject(await getJSONWithAuthHeaders(
+    ctxpackURL,
+    timeoutSeconds,
+    token,
+    { "X-Actor-User-Id": actorUserID },
+  ));
+  const versionID = firstNonEmptyString([
+    currentCtxpack.version_id,
+    loadWorkspaceMeta(resolvedWorkspaceDir).version_id,
+    loadWorkspaceMeta(resolvedWorkspaceDir).base_version_id,
+  ]);
+  if (!versionID) {
+    throw new Error("ctxpack version_id is missing; run ctxpack pull or refresh project summary first");
+  }
+  const baselineFiles = normalizeCtxpackFiles(currentCtxpack.files);
+  const fileMap = new Map();
+  baselineFiles.forEach((file) => {
+    fileMap.set(file.path, {
+      path: file.path,
+      doc_type: inferCtxpackDocTypeFromPath(file.path, "", file.docType),
+      content: String(file.content || ""),
+      is_generated: false,
+    });
+  });
+  const changedPaths = [];
+  const skippedPaths = [];
+  for (const artifactRaw of ensureArray(artifacts)) {
+    const artifact = safeObject(artifactRaw);
+    const relativePath = sanitizeCtxpackRelativePath(firstNonEmptyString([artifact.relativePath, artifact.path]));
+    if (!relativePath) {
+      continue;
+    }
+    if (shouldIgnoreCtxpackArtifactPath(relativePath)) {
+      skippedPaths.push(relativePath);
+      continue;
+    }
+    const operation = String(artifact.operation || "").trim().toLowerCase() || "update";
+    changedPaths.push(relativePath);
+    if (operation === "delete") {
+      fileMap.delete(relativePath);
+      continue;
+    }
+    const absolutePath = path.join(resolvedWorkspaceDir, relativePath);
+    if (!fs.existsSync(absolutePath)) {
+      throw new Error(`ctxpack source artifact is missing from workspace: ${absolutePath}`);
+    }
+    const content = fs.readFileSync(absolutePath, "utf8");
+    const existingDocType = String(safeObject(fileMap.get(relativePath)).doc_type || "").trim();
+    fileMap.set(relativePath, {
+      path: relativePath,
+      doc_type: inferCtxpackDocTypeFromPath(relativePath, artifact.kind, existingDocType),
+      content,
+      is_generated: true,
+    });
+  }
+  const files = Array.from(fileMap.values())
+    .filter((item) => item.path && !shouldIgnoreCtxpackArtifactPath(item.path))
+    .sort((left, right) => left.path.localeCompare(right.path));
+  if (!files.length) {
+    throw new Error("ctxpack update produced no pushable ctxpack files");
+  }
+  const responseText = await putJSONWithAuthHeaders(
+    ctxpackURL,
+    timeoutSeconds,
+    token,
+    {
+      version_id: versionID,
+      files,
+    },
+    {
+      "X-Actor-User-Id": actorUserID,
+    },
+  );
+  const parsed = safeObject(parseJSONText(responseText));
+  if (!Object.keys(parsed).length) {
+    throw new Error("invalid json response from ctxpack update");
+  }
+  writeWorkspaceCtxpackMeta({
+    siteBaseURL,
+    projectID,
+    workspaceDir: resolvedWorkspaceDir,
+    ctxpackResponse: parsed,
+  });
+  return {
+    ...parsed,
+    changed_paths: uniqueOrdered(changedPaths),
+    skipped_paths: uniqueOrdered(skippedPaths),
+    pushed_file_count: files.length,
+  };
+}
+
 async function listThreadComments(params) {
   return listThreadCommentsImpl(params, buildRunnerDataDeps());
 }
@@ -2986,6 +3284,22 @@ async function createThreadComment(params) {
   return createThreadCommentImpl(params, buildRunnerDataDeps());
 }
 
+async function createProjectWorkItem(params) {
+  return createProjectWorkItemImpl(params, buildRunnerDataDeps());
+}
+
+async function createProjectEvidence(params) {
+  return createProjectEvidenceImpl(params, buildRunnerDataDeps());
+}
+
+async function createWorkItemThread(params) {
+  return createWorkItemThreadImpl(params, buildRunnerDataDeps());
+}
+
+async function linkWorkItemEvidence(params) {
+  return linkWorkItemEvidenceImpl(params, buildRunnerDataDeps());
+}
+
 function buildRunnerDeliveryDeps() {
   return {
     listProjectChatDestinations,
@@ -3005,6 +3319,7 @@ function buildRunnerExecutionDeps() {
     auditRoleExecutionPlanWithAI,
     auditDirectHumanReplyWithAI,
     planRoleExecutionWithAI,
+    repairRoleExecutionPlanWithAI,
     normalizeRunnerRoleProfileName,
     normalizeRunnerRoleProfile,
     normalizeBotRunnerProjectMapping,
@@ -3019,12 +3334,19 @@ function buildRunnerExecutionDeps() {
     resolveRunnerExecutionPlanForRole,
     validateWorkspaceArtifacts,
     tryJsonParse,
+    createProjectEvidence,
+    createProjectWorkItem,
+    createWorkItemThread,
+    linkWorkItemEvidence,
+    replaceProjectCtxpackFiles,
   };
 }
 
 function buildRunnerRuntimeDeps() {
   return {
     loadProviderEnvConfig,
+    loadBotRunnerState,
+    saveBotRunnerState,
     getTelegramWebhookInfo,
     deleteTelegramWebhook,
     saveRunnerRouteState,
@@ -7015,7 +7337,7 @@ function syncCtxpackToLocalCache({
   const versionID = String(ctxpack?.version_id || ctxpack?.current_version_id || "").trim();
   const status = String(ctxpack?.status || "").trim() || "draft";
   const files = normalizeCtxpackFiles(ctxpack?.files);
-  const resolvedWorkspaceDir = resolveWorkspaceDir(workspaceDir);
+  const resolvedWorkspaceDir = resolveStableProjectWorkspaceCandidate(projectID, workspaceDir) || resolveWorkspaceDir(workspaceDir);
   const isHomeFallback = isHomeWorkspaceRoot(resolvedWorkspaceDir) && !allowHomeWorkspaceRoot();
   const cacheDir = path.join(
     isHomeFallback ? homeCtxpackCacheRootDir() : ctxpackCacheRootDir(resolvedWorkspaceDir),
@@ -7070,13 +7392,6 @@ function syncCtxpackToLocalCache({
     } catch {
       // Best-effort metadata refresh for workspace-root auto-detection.
     }
-    if (!isHomeFallback) {
-      rememberProjectWorkspaceMapping({
-        projectID,
-        workspaceDir: resolvedWorkspaceDir,
-        source: "ctxpack_sync_current",
-      });
-    }
     return {
       sync_status: isHomeFallback ? "home_fallback" : "current",
       sync_message: isHomeFallback
@@ -7100,14 +7415,6 @@ function syncCtxpackToLocalCache({
 
     fs.writeFileSync(metaPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
     fs.writeFileSync(workspaceMetaPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
-    if (!isHomeFallback) {
-      rememberProjectWorkspaceMapping({
-        projectID,
-        workspaceDir: resolvedWorkspaceDir,
-        source: "ctxpack_sync_write",
-      });
-    }
-
     return {
       sync_status: isHomeFallback ? "home_fallback" : (previousMeta ? "updated" : "downloaded"),
       sync_message: isHomeFallback
@@ -8083,6 +8390,8 @@ TELEGRAM_BOT_REVIEW_TOKEN=review-token
     performLocalBotDelivery,
     buildRunnerDeliveryDeps,
     parseJSONText,
+    archiveLocalTelegramMessagesForRoute,
+    buildRunnerRuntimeDeps,
   });
 
   await runSelftestWorkspaceEnvScenarios(push, {
@@ -8193,14 +8502,14 @@ TELEGRAM_BOT_REVIEW_TOKEN=review-token
       safeObject(runnerConfigAfterProjectTool.projectMappings)?.[selftestProjectID]?.workspaceDir || "";
     const projectToolWorkspaceSignalOk =
       String(safeObject(response).error || "").trim() === ""
-      && normalizedPathForCompare(storedProjectToolWorkspace) === normalizedPathForCompare(projectToolWorkspaceDir);
+      && !String(storedProjectToolWorkspace || "").trim();
     push(
-      "project_summary_workspace_signal_updates_runner_mapping",
+      "project_summary_workspace_signal_does_not_update_runner_mapping",
       projectToolWorkspaceSignalOk,
       `workspace=${storedProjectToolWorkspace || "(none)"} source=${String(safeObject(runnerConfigAfterProjectTool.projectMappings)?.[selftestProjectID]?.source || "(none)")}`,
     );
   } catch (err) {
-    push("project_summary_workspace_signal_updates_runner_mapping", false, String(err?.message || err));
+    push("project_summary_workspace_signal_does_not_update_runner_mapping", false, String(err?.message || err));
   } finally {
     if (previousProjectToolUserProfile === undefined) delete process.env.USERPROFILE;
     else process.env.USERPROFILE = previousProjectToolUserProfile;
@@ -8215,6 +8524,81 @@ TELEGRAM_BOT_REVIEW_TOKEN=review-token
     }
   }
 
+  let projectToolWorkspaceDriftTempHome = "";
+  const previousProjectToolDriftUserProfile = process.env.USERPROFILE;
+  const previousProjectToolDriftHome = process.env.HOME;
+  try {
+    projectToolWorkspaceDriftTempHome = fs.mkdtempSync(path.join(os.tmpdir(), "metheus-project-tool-drift-selftest-"));
+    const stableWorkspaceDir = path.join(projectToolWorkspaceDriftTempHome, "stable-workspace");
+    const unrelatedWorkspaceDir = path.join(projectToolWorkspaceDriftTempHome, "unrelated-workspace");
+    fs.mkdirSync(stableWorkspaceDir, { recursive: true });
+    fs.mkdirSync(unrelatedWorkspaceDir, { recursive: true });
+    process.env.USERPROFILE = projectToolWorkspaceDriftTempHome;
+    process.env.HOME = projectToolWorkspaceDriftTempHome;
+    rememberProjectWorkspaceMapping({
+      projectID: selftestProjectID,
+      workspaceDir: stableWorkspaceDir,
+      source: "manual_override",
+    });
+    await handleLocalProjectToolDispatchImpl(
+      {
+        requestObj: {
+          jsonrpc: "2.0",
+          id: 2,
+          method: "tools/call",
+          params: {
+            name: "project.summary",
+            arguments: {
+              project_id: selftestProjectID,
+            },
+          },
+        },
+        toolName: "project.summary",
+        toolArgs: {
+          project_id: selftestProjectID,
+        },
+        args: {
+          baseURL: DEFAULT_SITE_URL,
+          timeoutSeconds: 30,
+        },
+        token: "selftest-token",
+        workspaceDir: unrelatedWorkspaceDir,
+        workspaceSignalTrusted: true,
+      },
+      {
+        ...buildLocalProjectDispatchDeps(),
+        loadProjectSummaryForTool: async () => ({
+          project_id: selftestProjectID,
+          name: "Selftest Project",
+          access: "granted",
+        }),
+        buildProjectSummaryText: (summary) => `Project: ${String(summary?.name || "").trim()}`,
+      },
+    );
+    const runnerConfigAfterProjectToolDrift = loadBotRunnerConfig({ persistIfNeeded: true });
+    const storedWorkspaceAfterDrift =
+      safeObject(runnerConfigAfterProjectToolDrift.projectMappings)?.[selftestProjectID]?.workspaceDir || "";
+    push(
+      "project_summary_workspace_signal_preserves_existing_manual_mapping",
+      normalizedPathForCompare(storedWorkspaceAfterDrift) === normalizedPathForCompare(stableWorkspaceDir),
+      `stored=${storedWorkspaceAfterDrift || "(none)"} stable=${stableWorkspaceDir}`,
+    );
+  } catch (err) {
+    push("project_summary_workspace_signal_preserves_existing_manual_mapping", false, String(err?.message || err));
+  } finally {
+    if (previousProjectToolDriftUserProfile === undefined) delete process.env.USERPROFILE;
+    else process.env.USERPROFILE = previousProjectToolDriftUserProfile;
+    if (previousProjectToolDriftHome === undefined) delete process.env.HOME;
+    else process.env.HOME = previousProjectToolDriftHome;
+    if (projectToolWorkspaceDriftTempHome) {
+      try {
+        fs.rmSync(projectToolWorkspaceDriftTempHome, { recursive: true, force: true });
+      } catch {
+        // ignore selftest cleanup error
+      }
+    }
+  }
+
   await runSelftestBotCommands(push, {
     cliPath: fileURLToPath(import.meta.url),
     parseSimpleEnvText,