patchwarden 1.5.1 → 1.6.1

package/src/direct/directSessionStore.ts

@@ -1,8 +1,6 @@
 import {
   mkdirSync,
-  writeFileSync,
   existsSync,
-  readFileSync,
 } from "node:fs";
 import { createHash, randomBytes } from "node:crypto";
 import { resolve, join } from "node:path";
@@ -15,10 +13,16 @@ import {
 import { guardPath } from "../security/pathGuard.js";
 import { PatchWardenError } from "../errors.js";
 import { PATCHWARDEN_VERSION, TOOL_SCHEMA_EPOCH } from "../version.js";
-import { getLastToolCatalogSnapshot } from "../tools/toolCatalog.js";
+import { atomicWriteFileSync, atomicWriteJsonFileSync } from "../utils/atomicFile.js";
+import { redactSensitiveContent } from "../security/contentRedaction.js";
+import {
+  mutateLockedJsonFileSync,
+  readJsonObjectFileSync,
+  withFileLock,
+  withFileLockSync,
+} from "../utils/lockedJsonFile.js";
+import { getLastToolCatalogSnapshot } from "../tools/catalog/toolCatalog.js";
 import {
-  captureRepoSnapshot,
-  buildChangeArtifacts,
   type RepoSnapshot,
   type ChangeArtifacts,
 } from "../runner/changeCapture.js";
@@ -29,7 +33,9 @@ export interface DirectSessionOperation {
   index: number;
   timestamp: string;
   path: string;
-  before_sha256: string;
+  operation_type?: "patch" | "sync";
+  source_path?: string;
+  before_sha256: string | null;
   after_sha256: string;
   operations_applied: number;
   bytes_changed: number;
@@ -89,23 +95,52 @@ export function generateDirectSessionId(): string {
   return `direct_${timestamp}_${randomHex}`;
 }
 
+/**
+ * Direct session IDs are directory names. Keep one shared, bounded grammar so
+ * MCP tools and Control Center routes cannot disagree about traversal input.
+ */
+export function isValidDirectSessionId(sessionId: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(sessionId);
+}
+
+function guardDirectSessionId(sessionId: string): void {
+  if (!isValidDirectSessionId(sessionId)) {
+    throw new PatchWardenError(
+      "invalid_session_id",
+      `Direct session ID "${sessionId}" is invalid.`,
+      "Use the session_id returned by create_direct_session.",
+      true,
+      { session_id: sessionId }
+    );
+  }
+}
+
 // ── Directory management ───────────────────────────────────────────
 
-export function createDirectSessionDir(sessionId: string): string {
-  const config = getConfig();
+export function createDirectSessionDir(
+  sessionId: string,
+  config: PatchWardenConfig = getConfig()
+): string {
+  guardDirectSessionId(sessionId);
   const sessionsDir = getDirectSessionsDir(config);
   guardPath(sessionsDir, config.workspaceRoot, config.directSessionsDir);
   mkdirSync(sessionsDir, { recursive: true });
-  const dir = resolve(sessionsDir, sessionId);
-  guardPath(dir, config.workspaceRoot, config.directSessionsDir);
+  const dir = getDirectSessionDir(sessionId, config);
   mkdirSync(dir, { recursive: true });
   return dir;
 }
 
-export function getDirectSessionDir(sessionId: string): string {
-  const config = getConfig();
+export function getDirectSessionDir(
+  sessionId: string,
+  config: PatchWardenConfig = getConfig()
+): string {
+  guardDirectSessionId(sessionId);
   const sessionsDir = getDirectSessionsDir(config);
-  return resolve(sessionsDir, sessionId);
+  return guardPath(
+    resolve(sessionsDir, sessionId),
+    config.workspaceRoot,
+    config.directSessionsDir
+  );
 }
 
 // ── CRUD ───────────────────────────────────────────────────────────
@@ -136,7 +171,11 @@ export function createDirectSession(
 
   const record: DirectSessionRecord = {
     session_id: sessionId,
-    title: input.title || "",
+    title: redactSensitiveContent(input.title || "")
+      .content
+      .replace(/[\r\n\t]+/g, " ")
+      .trim()
+      .slice(0, 500),
     repo_path: input.repo_path,
     resolved_repo_path: input.resolved_repo_path,
     created_at: now.toISOString(),
@@ -155,21 +194,16 @@ export function createDirectSession(
     change_artifacts: null,
   };
 
-  writeFileSync(
-    join(dir, "session.json"),
-    JSON.stringify(record, null, 2),
-    "utf-8"
-  );
+  atomicWriteJsonFileSync(join(dir, "session.json"), record);
 
   return record;
 }
 
-export function readDirectSession(sessionId: string): DirectSessionRecord {
-  const config = getConfig();
-  const sessionsDir = getDirectSessionsDir(config);
-  const dir = resolve(sessionsDir, sessionId);
-  const file = join(dir, "session.json");
-  guardPath(file, config.workspaceRoot, config.directSessionsDir);
+export function readDirectSession(
+  sessionId: string,
+  config: PatchWardenConfig = getConfig()
+): DirectSessionRecord {
+  const file = getDirectSessionFile(sessionId, config);
 
   if (!existsSync(file)) {
     throw new PatchWardenError(
@@ -181,40 +215,69 @@ export function readDirectSession(sessionId: string): DirectSessionRecord {
     );
   }
 
-  return JSON.parse(readFileSync(file, "utf-8")) as DirectSessionRecord;
+  let value: unknown;
+  try {
+    value = readJsonObjectFileSync(file);
+  } catch {
+    throw invalidDirectSessionRecord(sessionId, "session.json is not valid JSON");
+  }
+  return validateDirectSessionRecord(sessionId, value);
 }
 
 export function updateDirectSession(
   sessionId: string,
   updates: Partial<DirectSessionRecord>
 ): DirectSessionRecord {
-  const session = readDirectSession(sessionId);
-  const updated: DirectSessionRecord = { ...session, ...updates };
-  const dir = getDirectSessionDir(sessionId);
-  writeFileSync(
-    join(dir, "session.json"),
-    JSON.stringify(updated, null, 2),
-    "utf-8"
-  );
-  return updated;
+  return mutateDirectSessionRecord(sessionId, (session) => ({
+    ...session,
+    ...updates,
+    session_id: session.session_id,
+  }));
 }
 
 export function appendDirectSessionOperation(
   sessionId: string,
-  operation: DirectSessionOperation
+  operation: DirectSessionOperation,
+  config: PatchWardenConfig = getConfig(),
 ): DirectSessionRecord {
-  const session = readDirectSession(sessionId);
-  const operations = [...session.operations, operation];
-  return updateDirectSession(sessionId, { operations });
+  return mutateDirectSessionRecord(sessionId, (session) => ({
+    ...session,
+    operations: [
+      ...session.operations,
+      {
+        ...operation,
+        index: session.operations.reduce((max, entry) => Math.max(max, entry.index), -1) + 1,
+      },
+    ],
+  }), config);
+}
+
+export function withDirectSessionMutationLock<R>(
+  sessionId: string,
+  action: () => R,
+  config: PatchWardenConfig = getConfig(),
+): R {
+  const lockTarget = join(getDirectSessionDir(sessionId, config), "workspace-mutation");
+  return withFileLockSync(lockTarget, action, directSessionBusyOptions(sessionId));
+}
+
+export function withDirectSessionMutationLockAsync<R>(
+  sessionId: string,
+  action: () => Promise<R>,
+  config: PatchWardenConfig = getConfig(),
+): Promise<R> {
+  const lockTarget = join(getDirectSessionDir(sessionId, config), "workspace-mutation");
+  return withFileLock(lockTarget, action, directSessionBusyOptions(sessionId));
 }
 
 export function appendDirectSessionVerificationRun(
   sessionId: string,
   run: DirectSessionVerificationRun
 ): DirectSessionRecord {
-  const session = readDirectSession(sessionId);
-  const verification_runs = [...session.verification_runs, run];
-  return updateDirectSession(sessionId, { verification_runs });
+  return mutateDirectSessionRecord(sessionId, (session) => ({
+    ...session,
+    verification_runs: [...session.verification_runs, run],
+  }));
 }
 
 // ── Validation ─────────────────────────────────────────────────────
@@ -261,32 +324,25 @@ export function validateDirectSessionFreshness(
 
 export function finalizeDirectSessionRecord(
   sessionId: string,
-  afterSnapshot: RepoSnapshot,
   changeArtifacts: ChangeArtifacts
 ): DirectSessionRecord {
   const dir = getDirectSessionDir(sessionId);
 
   // Write change artifacts to session directory
-  writeFileSync(
-    join(dir, "changed-files.json"),
-    JSON.stringify(changeArtifacts.changed_files, null, 2),
-    "utf-8"
-  );
-  writeFileSync(join(dir, "diff.patch"), changeArtifacts.diff, "utf-8");
+  atomicWriteJsonFileSync(join(dir, "changed-files.json"), changeArtifacts.changed_files);
+  atomicWriteFileSync(join(dir, "diff.patch"), changeArtifacts.diff);
 
   const summary = {
     changed_files_total: changeArtifacts.changed_files.length,
     additions: changeArtifacts.additions,
     deletions: changeArtifacts.deletions,
     patch_mode: changeArtifacts.patch_mode,
+    diff_redacted: changeArtifacts.diff_redacted === true,
+    diff_redaction_categories: changeArtifacts.diff_redaction_categories ?? [],
     artifact_hygiene: changeArtifacts.artifact_hygiene,
   };
-  writeFileSync(
-    join(dir, "summary.json"),
-    JSON.stringify(summary, null, 2),
-    "utf-8"
-  );
-  writeFileSync(join(dir, "summary.md"), formatSummaryMd(changeArtifacts), "utf-8");
+  atomicWriteJsonFileSync(join(dir, "summary.json"), summary);
+  atomicWriteFileSync(join(dir, "summary.md"), formatSummaryMd(changeArtifacts));
 
   return updateDirectSession(sessionId, {
     finalized: true,
@@ -319,6 +375,105 @@ function extractReason(error: unknown): string {
   return String(error).slice(0, 80);
 }
 
+function invalidDirectSessionRecord(
+  sessionId: string,
+  detail: string
+): PatchWardenError {
+  return new PatchWardenError(
+    "invalid_session_record",
+    `Direct session "${sessionId}" is invalid: ${detail}.`,
+    "Create a new direct session and do not modify its internal session.json file.",
+    true,
+    { session_id: sessionId }
+  );
+}
+
+function getDirectSessionFile(
+  sessionId: string,
+  config: PatchWardenConfig = getConfig()
+): string {
+  const dir = getDirectSessionDir(sessionId, config);
+  return guardPath(
+    join(dir, "session.json"),
+    config.workspaceRoot,
+    config.directSessionsDir
+  );
+}
+
+function mutateDirectSessionRecord(
+  sessionId: string,
+  mutation: (session: DirectSessionRecord) => DirectSessionRecord,
+  config: PatchWardenConfig = getConfig(),
+): DirectSessionRecord {
+  const file = getDirectSessionFile(sessionId, config);
+  if (!existsSync(file)) {
+    throw new PatchWardenError(
+      "session_not_found",
+      `Direct session "${sessionId}" not found.`,
+      "Call create_direct_session first to get a valid session_id.",
+      true,
+      { session_id: sessionId }
+    );
+  }
+  return mutateLockedJsonFileSync<DirectSessionRecord, DirectSessionRecord>(
+    file,
+    (current) => {
+      const session = validateDirectSessionRecord(sessionId, current);
+      const next = mutation(session);
+      return { next, result: next };
+    },
+    {
+      // Session-record appends are short serialized writes. Give Windows
+      // antivirus-delayed lock detachment enough time to finish instead of
+      // dropping concurrent operation or verification evidence.
+      waitMs: 10_000,
+      busyError: () => new PatchWardenError(
+        "direct_session_busy",
+        `Direct session "${sessionId}" is currently being updated.`,
+        "Retry after the current Direct operation completes.",
+        true,
+        { session_id: sessionId }
+      ),
+    }
+  );
+}
+
+function directSessionBusyOptions(sessionId: string) {
+  return {
+    waitMs: 0,
+    busyError: () => new PatchWardenError(
+      "direct_session_busy",
+      `Direct session "${sessionId}" already has a workspace operation in progress.`,
+      "Wait for the active patch, sync, verification, or finalization to finish, then retry.",
+      true,
+      { session_id: sessionId },
+    ),
+  };
+}
+
+function validateDirectSessionRecord(sessionId: string, value: unknown): DirectSessionRecord {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw invalidDirectSessionRecord(sessionId, "session.json must contain an object");
+  }
+  const record = value as Partial<DirectSessionRecord>;
+  if (record.session_id !== sessionId) {
+    throw invalidDirectSessionRecord(sessionId, "session_id does not match its directory");
+  }
+  if (typeof record.resolved_repo_path !== "string" || record.resolved_repo_path.trim() === "") {
+    throw invalidDirectSessionRecord(sessionId, "resolved_repo_path is missing");
+  }
+  if (typeof record.expires_at !== "string" || !Number.isFinite(Date.parse(record.expires_at))) {
+    throw invalidDirectSessionRecord(sessionId, "expires_at is invalid");
+  }
+  if (typeof record.finalized !== "boolean") {
+    throw invalidDirectSessionRecord(sessionId, "finalized must be a boolean");
+  }
+  if (!Array.isArray(record.operations) || !Array.isArray(record.verification_runs)) {
+    throw invalidDirectSessionRecord(sessionId, "operation or verification history is invalid");
+  }
+  return record as DirectSessionRecord;
+}
+
 function formatSummaryMd(artifacts: ChangeArtifacts): string {
   const lines: string[] = [
     "# Direct Session Change Summary",
@@ -327,6 +482,7 @@ function formatSummaryMd(artifacts: ChangeArtifacts): string {
     `**Additions:** ${artifacts.additions}`,
     `**Deletions:** ${artifacts.deletions}`,
     `**Patch mode:** ${artifacts.patch_mode}`,
+    `**Diff redacted:** ${artifacts.diff_redacted === true ? "yes" : "no"}`,
     "",
     "## Artifact Hygiene",
     "",

package/src/direct/directVerification.ts

@@ -1,11 +1,12 @@
-import { writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { getConfig } from "../config.js";
 import { guardDirectCommand } from "../security/commandGuard.js";
 import { redactSensitiveContent } from "../security/contentRedaction.js";
 import { runSimpleProcess } from "../runner/simpleProcess.js";
+import { resolveTrustedCommandLine } from "../runner/processSecurity.js";
 import { getDirectSessionDir } from "./directSessionStore.js";
 import type { DirectSessionVerificationRun } from "./directSessionStore.js";
+import { atomicWriteJsonFileSync } from "../utils/atomicFile.js";
 
 const MAX_TAIL_CHARS = 10_000;
 const DEFAULT_TIMEOUT_SECONDS = 120;
@@ -36,7 +37,7 @@ export async function runDirectVerification(
   const timeoutMs = timeoutSeconds * 1000;
 
   // Parse command into command + args
-  const parts = parseCommand(allowedCommand);
+  const parts = parseCommand(allowedCommand, input.resolvedRepoPath);
   if (!parts) {
     throw new Error(`Failed to parse command: "${allowedCommand}"`);
   }
@@ -104,11 +105,7 @@ export async function runDirectVerification(
     spawn_error: result.spawnError,
   };
 
-  writeFileSync(
-    join(sessionDir, "verification.json"),
-    JSON.stringify(verificationJson, null, 2),
-    "utf-8"
-  );
+  atomicWriteJsonFileSync(join(sessionDir, "verification.json"), verificationJson);
 
   return { run, log_path: logPath };
 }
@@ -116,26 +113,15 @@ export async function runDirectVerification(
 // ── Helpers ────────────────────────────────────────────────────────
 
 function parseCommand(
-  command: string
+  command: string,
+  cwd: string,
 ): { command: string; args: string[] } | null {
   const trimmed = command.trim();
   if (!trimmed) return null;
-
-  // Simple split by spaces - sufficient for allowlisted commands like "npm test"
-  const parts = trimmed.split(/\s+/);
-
-  // On Windows, npm/npx are batch files (.cmd) and spawn() cannot find them
-  // without shell resolution. Wrap with cmd.exe /c for those commands.
-  if (process.platform === "win32" && (parts[0] === "npm" || parts[0] === "npx")) {
-    return {
-      command: "cmd",
-      args: ["/c", ...parts],
-    };
-  }
-
+  const invocation = resolveTrustedCommandLine(trimmed, cwd);
   return {
-    command: parts[0],
-    args: parts.slice(1),
+    command: invocation.command,
+    args: invocation.argsPrefix,
   };
 }
 

package/src/doctor.ts

@@ -10,20 +10,22 @@
 
 import { existsSync, statSync, readFileSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { isAbsolute, resolve, normalize, join } from "node:path";
-import { execSync } from "node:child_process";
 import { createServer } from "node:net";
 import { getConfig, type PatchWardenConfig } from "./config.js";
 import { guardPath, guardWorkspacePath } from "./security/pathGuard.js";
 import { isSensitivePath } from "./security/sensitiveGuard.js";
 import { guardPlanContent } from "./security/planGuard.js";
-import { TASK_READ_ONLY_FILES } from "./tools/getTaskFile.js";
+import { TASK_READ_ONLY_FILES } from "./tools/tasks/getTaskFile.js";
 import { getToolDefs } from "./tools/registry.js";
-import { CHATGPT_CORE_TOOL_NAMES, CHATGPT_DIRECT_TOOL_NAMES, selectToolsForProfile } from "./tools/toolCatalog.js";
-import { buildToolRegistry } from "./tools/toolRegistry.js";
-import { runAllSchemaDriftChecks } from "./tools/schemaDriftCheck.js";
+import { CHATGPT_CORE_TOOL_NAMES, CHATGPT_DIRECT_TOOL_NAMES, selectToolsForProfile } from "./tools/catalog/toolCatalog.js";
+import { buildToolRegistry } from "./tools/catalog/toolRegistry.js";
+import { runAllSchemaDriftChecks } from "./tools/diagnostics/schemaDriftCheck.js";
 import { runReleaseGateCheck } from "./release/releaseGate.js";
 import { PATCHWARDEN_VERSION } from "./version.js";
 import { logger } from "./logging.js";
+import { unsafeWorkspaceRootLabel } from "./security/workspaceRootGuard.js";
+import { runSimpleProcessSync } from "./runner/simpleProcess.js";
+import { resolveAgentLaunch } from "./runner/agentInvocation.js";
 
 // ── Types ──────────────────────────────────────────────────────────
 
@@ -50,13 +52,18 @@ export interface DoctorContext {
 
 // ── Helpers ────────────────────────────────────────────────────────
 
-function cmd(cmdStr: string): string {
+function cmd(command: string, args: readonly string[] = []): string {
   try {
-    return execSync(cmdStr, {
-      encoding: "utf-8",
-      timeout: 5000,
-      stdio: ["ignore", "pipe", "ignore"], // suppress stdin and stderr
-    }).trim();
+    const result = runSimpleProcessSync({
+      command,
+      args: [...args],
+      cwd: process.cwd(),
+      timeoutMs: 5000,
+      maxStdoutBytes: 64 * 1024,
+      maxStderrBytes: 64 * 1024,
+    });
+    if (result.exitCode !== 0) return "";
+    return `${result.stdout}${result.stderr}`.trim();
   } catch {
     return "";
   }
@@ -109,7 +116,7 @@ const checkNpmAvailable: DoctorCheck = {
   id: "npm-available",
   description: "npm available",
   run() {
-    const npmVer = cmd("npm --version");
+    const npmVer = cmd(process.platform === "win32" ? "npm.cmd" : "npm", ["--version"]);
     return [checkResult("npm available", npmVer !== "", npmVer || "npm not found in PATH")];
   },
 };
@@ -144,7 +151,7 @@ const checkGitAvailable: DoctorCheck = {
   id: "git-available",
   description: "Git available",
   run() {
-    const gitVer = cmd("git --version");
+    const gitVer = cmd("git", ["--version"]);
     return [warnCheckResult("Git available", gitVer !== "", gitVer || "git not found — runner git.diff will not work")];
   },
 };
@@ -199,18 +206,9 @@ const checkWorkspaceRoot: DoctorCheck = {
     try { isDir = statSync(ws).isDirectory(); } catch {}
     results.push(checkResult("workspaceRoot is directory", isDir, ws));
 
-    const dangerousRoots = [
-      { pattern: /^[A-Za-z]:\\?$/, label: "drive root" },
-      { pattern: /\\Users\\[^\\]+$/, label: "user home directory" },
-      { pattern: /\\Desktop$/, label: "Desktop" },
-      { pattern: /\\Downloads$/, label: "Downloads" },
-      { pattern: /\\Documents$/, label: "Documents" },
-    ];
-
-    for (const { pattern, label } of dangerousRoots) {
-      if (pattern.test(ws)) {
-        results.push(warnResult(`workspaceRoot is ${label}: ${ws} — consider narrowing to a project directory`));
-      }
+    const unsafeLabel = unsafeWorkspaceRootLabel(ws);
+    if (unsafeLabel) {
+      results.push(warnResult(`workspaceRoot is ${unsafeLabel}: ${ws} — consider narrowing to a project directory`));
     }
     return results;
   },
@@ -312,11 +310,13 @@ const checkServerVersion: DoctorCheck = {
         packageJson.version === PATCHWARDEN_VERSION,
         `${PATCHWARDEN_VERSION} vs ${packageJson.version}`,
       ),
-      checkResult(
-        "Manifest preflight script exists",
-        existsSync(resolve(process.cwd(), "scripts/checks/mcp-manifest-check.js")),
-        "scripts/checks/mcp-manifest-check.js",
-      ),
+      process.env.PATCHWARDEN_DESKTOP_RUNTIME === "1"
+        ? okResult("Manifest preflight covered by compiled desktop runtime checks")
+        : checkResult(
+            "Manifest preflight script exists",
+            existsSync(resolve(process.cwd(), "scripts/checks/mcp-manifest-check.js")),
+            "scripts/checks/mcp-manifest-check.js",
+          ),
     ];
   },
 };
@@ -331,8 +331,8 @@ const checkToolProfiles: DoctorCheck = {
       process.env.PATCHWARDEN_TOOL_PROFILE = "full";
       const fullTools = getToolDefs();
       const coreTools = selectToolsForProfile(fullTools, "chatgpt_core", context.config?.enableDirectProfile);
-      const createSchema = coreTools.find((tool) => tool.name === "create_task")?.inputSchema as any;
-      const waitSchema = coreTools.find((tool) => tool.name === "wait_for_task")?.inputSchema as any;
+      const createSchema = coreTools.find((tool) => tool.name === "create_task")?.inputSchema;
+      const waitSchema = coreTools.find((tool) => tool.name === "wait_for_task")?.inputSchema;
       results.push(checkResult("Full tool profile exposes 66 tools", fullTools.length === 66, `${fullTools.length} tools`));
       results.push(
         checkResult(
@@ -463,23 +463,23 @@ const checkToolModules: DoctorCheck = {
   description: "Tool module checks",
   run() {
     const newTools = [
-      "listTasks",
-      "listAgents",
-      "cancelTask",
-      "killTask",
-      "retryTask",
-      "getTaskProgress",
-      "getTaskSummary",
-      "waitForTask",
-      "getTaskStdoutTail",
-      "healthCheck",
-      "auditTask",
+      { name: "listTasks", subdir: "tasks" },
+      { name: "listAgents", subdir: "workspace" },
+      { name: "cancelTask", subdir: "tasks" },
+      { name: "killTask", subdir: "tasks" },
+      { name: "retryTask", subdir: "tasks" },
+      { name: "getTaskProgress", subdir: "tasks" },
+      { name: "getTaskSummary", subdir: "tasks" },
+      { name: "waitForTask", subdir: "tasks" },
+      { name: "getTaskStdoutTail", subdir: "tasks" },
+      { name: "healthCheck", subdir: "diagnostics" },
+      { name: "auditTask", subdir: "diagnostics" },
     ];
     const results: DoctorCheckResult[] = [];
     for (const t of newTools) {
-      const compiled = resolve(process.cwd(), "dist/tools", `${t}.js`);
+      const compiled = resolve(process.cwd(), "dist/tools", t.subdir, `${t.name}.js`);
       const exists = existsSync(compiled);
-      results.push(checkResult(`Tool module: ${t}`, exists, exists ? "compiled" : "missing"));
+      results.push(checkResult(`Tool module: ${t.name}`, exists, exists ? "compiled" : "missing"));
     }
     return results;
   },
@@ -490,18 +490,18 @@ const checkDirectToolModules: DoctorCheck = {
   description: "Direct tool module checks",
   run() {
     const directToolModules = [
-      "createDirectSession",
-      "searchWorkspace",
-      "applyPatch",
-      "runVerification",
-      "finalizeDirectSession",
-      "auditSession",
+      { name: "createDirectSession", subdir: "direct" },
+      { name: "searchWorkspace", subdir: "workspace" },
+      { name: "applyPatch", subdir: "workspace" },
+      { name: "runVerification", subdir: "tasks" },
+      { name: "finalizeDirectSession", subdir: "direct" },
+      { name: "auditSession", subdir: "diagnostics" },
     ];
     const results: DoctorCheckResult[] = [];
     for (const t of directToolModules) {
-      const compiled = resolve(process.cwd(), "dist/tools", `${t}.js`);
+      const compiled = resolve(process.cwd(), "dist/tools", t.subdir, `${t.name}.js`);
       const exists = existsSync(compiled);
-      results.push(checkResult(`Direct tool module: ${t}`, exists, exists ? "compiled" : "missing"));
+      results.push(checkResult(`Direct tool module: ${t.name}`, exists, exists ? "compiled" : "missing"));
     }
     return results;
   },
@@ -612,8 +612,7 @@ const checkAgentCommands: DoctorCheck = {
   run(context) {
     if (!context.config) return [];
     const results: DoctorCheckResult[] = [];
-    const agents = context.config.agents || {};
-    for (const [name, agentCfg] of Object.entries(agents) as [string, any][]) {
+    for (const [name, agentCfg] of Object.entries(context.config.agents)) {
       const cmdName = agentCfg.command;
       const looksLikePath = isAbsolute(cmdName) || cmdName.includes("/") || cmdName.includes("\\");
       if (looksLikePath) {
@@ -621,11 +620,26 @@ const checkAgentCommands: DoctorCheck = {
         results.push(warnCheckResult(`Agent "${name}" command available`, agentExists, agentExists ? `Found: ${cmdName}` : `"${cmdName}" does not exist — agent tasks will fail`));
         continue;
       }
-      // Platform-appropriate lookup: 'where' on Windows, 'command -v' on Unix
+      // Use an argumentized lookup utility; never interpolate config into a shell.
       const isWin = process.platform === "win32";
-      const lookupCmd = isWin ? `where ${cmdName}` : `command -v ${cmdName}`;
-      const fallbackCmd = isWin ? `command -v ${cmdName}` : `which ${cmdName}`;
-      const found = cmd(lookupCmd) || cmd(fallbackCmd);
+      let found = "";
+      if (isWin) {
+        try {
+          found = resolveAgentLaunch(
+            name,
+            cmdName,
+            process.platform,
+            process.env.PATH || "",
+            existsSync,
+            context.config.workspaceRoot,
+            typeof agentCfg.adapter === "string" ? agentCfg.adapter : name,
+          ).command;
+        } catch {
+          found = "";
+        }
+      } else {
+        found = cmd("which", [cmdName]);
+      }
       results.push(warnCheckResult(`Agent "${name}" command available`, found !== "", found ? `Found: ${found.split("\n")[0]}` : `"${cmdName}" not in PATH — agent tasks will fail`));
     }
     return results;