@vellumai/assistant 0.12.2-dev.202609171418.b9a2adf → 0.12.2-dev.202609171516.2acdfd4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.2-dev.202609171418.b9a2adf",
+  "version": "0.12.2-dev.202609171516.2acdfd4",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/config-watcher.test.ts

@@ -315,6 +315,30 @@ describe("ConfigWatcher workspace file handlers", () => {
     expect(evictCallCount).toBe(1);
   });
 
+  test("config.json change reloads MCP when tools.mcpGlobalMaxTools changes", async () => {
+    watcher.initFingerprint({
+      tools: { exclude: [], mcpGlobalMaxTools: 50 },
+    } as never);
+    watcher.refreshConfigFromSources = async () => true;
+    watcher.start();
+    simulateFileChange(WORKSPACE_DIR, "config.json");
+    await new Promise((r) => setTimeout(r, WAIT_MS));
+    expect(mcpReloadCallCount).toBe(1);
+    expect(evictCallCount).toBe(1);
+  });
+
+  test("config.json change does not reload MCP when the global max is unchanged", async () => {
+    watcher.initFingerprint({
+      tools: { exclude: [] },
+    } as never);
+    watcher.refreshConfigFromSources = async () => true;
+    watcher.start();
+    simulateFileChange(WORKSPACE_DIR, "config.json");
+    await new Promise((r) => setTimeout(r, WAIT_MS));
+    expect(mcpReloadCallCount).toBe(0);
+    expect(evictCallCount).toBe(1);
+  });
+
   test("config.json change is suppressed when suppressConfigReload is true", async () => {
     let refreshCalled = false;
     watcher.refreshConfigFromSources = async () => {

package/src/__tests__/credential-execution-client.test.ts

@@ -31,8 +31,8 @@ import {
   createCesClient,
 } from "../credential-execution/client.js";
 import {
+  discoverCes,
   discoverCesWithRetry,
-  discoverManagedCes,
 } from "../credential-execution/executable-discovery.js";
 
 // ---------------------------------------------------------------------------
@@ -100,7 +100,7 @@ describe("managed CES discovery", () => {
     const bootstrapDir = mkdtempSync(join(tmpdir(), "ces-missing-"));
     const restore = withBootstrapDir(bootstrapDir);
     try {
-      const result = discoverManagedCes();
+      const result = discoverCes();
       expect(result.mode).toBe("unavailable");
       expect((result as { reason: string }).reason).toContain(
         "CES bootstrap socket not found",
@@ -115,7 +115,7 @@ describe("managed CES discovery", () => {
     const bootstrapDir = mkdtempSync(join(tmpdir(), "ces-missing-"));
     const restore = withBootstrapDir(bootstrapDir);
     try {
-      const result = discoverManagedCes();
+      const result = discoverCes();
       expect(["managed", "unavailable"]).toContain(result.mode);
     } finally {
       restore();
@@ -132,7 +132,7 @@ describe("CES bootstrap socket discovery", () => {
       const socketPath = resolveIpcEndpoint("ces", {
         workspaceDir: bootstrapDir,
       }).path;
-      const result = discoverManagedCes();
+      const result = discoverCes();
       expect(result.mode).toBe("unavailable");
       expect((result as { reason: string }).reason).toContain(socketPath);
     } finally {
@@ -145,7 +145,7 @@ describe("CES bootstrap socket discovery", () => {
     const bootstrapDir = mkdtempSync(join(tmpdir(), "ces-bootstrap-"));
     const restore = withBootstrapDir(bootstrapDir);
     try {
-      const result = discoverManagedCes();
+      const result = discoverCes();
       const workspaceDir = process.env.VELLUM_WORKSPACE_DIR;
       expect(workspaceDir).toBeDefined();
       const workspaceSocket = resolveIpcEndpoint("ces", {

package/src/config/schemas/__tests__/tools.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test } from "bun:test";
+
+import { MCP_GLOBAL_MAX_TOOLS } from "../mcp.js";
+import { ToolsConfigSchema } from "../tools.js";
+
+describe("ToolsConfigSchema.mcpGlobalMaxTools", () => {
+  test("omits the override so the shipped MCP cap remains in force", () => {
+    const parsed = ToolsConfigSchema.parse({});
+    expect(parsed.mcpGlobalMaxTools).toBeUndefined();
+    expect(parsed.exclude).toEqual([]);
+  });
+
+  test("accepts a workspace override", () => {
+    expect(
+      ToolsConfigSchema.parse({ mcpGlobalMaxTools: 80 }).mcpGlobalMaxTools,
+    ).toBe(80);
+    expect(
+      ToolsConfigSchema.parse({
+        mcpGlobalMaxTools: MCP_GLOBAL_MAX_TOOLS,
+      }).mcpGlobalMaxTools,
+    ).toBe(MCP_GLOBAL_MAX_TOOLS);
+    expect(
+      ToolsConfigSchema.parse({ mcpGlobalMaxTools: 1000 }).mcpGlobalMaxTools,
+    ).toBe(1000);
+  });
+
+  test("rejects zero and fractions", () => {
+    expect(() => ToolsConfigSchema.parse({ mcpGlobalMaxTools: 0 })).toThrow();
+    expect(() => ToolsConfigSchema.parse({ mcpGlobalMaxTools: 1.5 })).toThrow();
+  });
+});

package/src/config/schemas/mcp.ts

@@ -18,7 +18,8 @@ export const PLUGIN_MCP_RISK_LEVEL = "low" as const;
 export const MCP_MAX_TOOLS_PER_SERVER = 20;
 
 /**
- * Cap on tools registered across every MCP server. Selection is a
+ * Cap on tools registered across every MCP server when the workspace
+ * does not set `tools.mcpGlobalMaxTools` in config.json. Selection is a
  * deterministic round-robin by server id (see `mcp/tool-caps.ts`), so a
  * later server is not emptied just because earlier ones filled the budget.
  */

package/src/config/schemas/tools.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 
+import { MCP_GLOBAL_MAX_TOOLS } from "./mcp.js";
+
 export const ToolsConfigSchema = z
   .object({
     exclude: z
@@ -8,6 +10,14 @@ export const ToolsConfigSchema = z
       .describe(
         "Tool names to suppress. Excluded tools are not sent to the LLM. Names match `ToolDefinition.name` exactly (e.g. `bash`, `mcp__server__tool`).",
       ),
+    mcpGlobalMaxTools: z
+      .number({ error: "tools.mcpGlobalMaxTools must be a number" })
+      .int("tools.mcpGlobalMaxTools must be an integer")
+      .min(1, "tools.mcpGlobalMaxTools must be >= 1")
+      .optional()
+      .describe(
+        `Override the code-owned cap on MCP tools registered across every server. Omit to use the shipped default of ${MCP_GLOBAL_MAX_TOOLS}. Selection is a fair round-robin by server id.`,
+      ),
   })
   .describe("Tool visibility configuration");
 

package/src/config/skills.ts

@@ -225,10 +225,6 @@ export interface SkillToolManifestMeta {
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
-function getSkillsDir(): string {
-  return getWorkspaceSkillsDir();
-}
-
 export function getBundledSkillsDir(): string {
   const dir = import.meta.dir;
 
@@ -1114,7 +1110,7 @@ export function loadSkillCatalog(
   }
 
   // Load managed (user) skills, which take precedence over bundled skills with the same ID
-  const skillsDir = getSkillsDir();
+  const skillsDir = getWorkspaceSkillsDir();
   const directories = discoverSkillDirectories(skillsDir);
 
   for (const directory of directories) {
@@ -1354,7 +1350,7 @@ function loadSkillDefinition(skill: SkillSummary): SkillLookupResult {
   } else {
     loaded = readSkillFromDirectory(
       skill.directoryPath,
-      getSkillsDir(),
+      getWorkspaceSkillsDir(),
       skill.source,
     );
   }

package/src/credential-execution/executable-discovery.ts

@@ -53,9 +53,7 @@ export type DiscoveryResult = ManagedDiscoverySuccess | DiscoveryFailure;
  * processes can each connect. The actual connection is made later by
  * `CesProcessManager.start()`.
  */
-export function discoverManagedCes():
-  | ManagedDiscoverySuccess
-  | DiscoveryFailure {
+export function discoverCes(): DiscoveryResult {
   const socketPath = getCesSocketPath();
 
   if (!isNamedPipePath(socketPath) && !existsSync(socketPath)) {
@@ -68,14 +66,6 @@ export function discoverManagedCes():
   return { mode: "managed", socketPath };
 }
 
-/**
- * Discover CES for the current process. Local and managed topologies use
- * the same bootstrap socket path.
- */
-export function discoverCes(): DiscoveryResult {
-  return discoverManagedCes();
-}
-
 /** How long to poll for the CES socket before giving up. */
 const MANAGED_DISCOVERY_TIMEOUT_MS = 3_000;
 

package/src/daemon/config-watcher.ts

@@ -190,12 +190,22 @@ export class ConfigWatcher {
         if (this.suppressReload) {
           return;
         }
+        const prevMcpGlobalMax = this.lastConfig?.tools.mcpGlobalMaxTools;
         try {
           const changed = await this.refreshConfigFromSources();
           if (changed) {
             evictConversationsForReload();
             refreshAuthenticatedApiRateLimit();
             publishConfigChanged();
+            const nextMcpGlobalMax = getConfig().tools.mcpGlobalMaxTools;
+            if (prevMcpGlobalMax !== nextMcpGlobalMax) {
+              reloadMcpServers().catch((err: unknown) => {
+                log.error(
+                  { err },
+                  "MCP reload after tools.mcpGlobalMaxTools change failed",
+                );
+              });
+            }
           }
         } catch (err) {
           log.error(

package/src/mcp/__tests__/manager-tool-caps.test.ts

@@ -11,6 +11,13 @@ import type { ResolvedMcpConfig } from "../../config/schemas/mcp.js";
 
 const toolsByServer = new Map<string, Array<{ name: string }>>();
 const connectDelays = new Map<string, number>();
+let mcpGlobalMaxTools: number | undefined;
+
+mock.module("../../config/loader.js", () => ({
+  getConfig: () => ({
+    tools: { exclude: [], mcpGlobalMaxTools },
+  }),
+}));
 
 mock.module("../client.js", () => ({
   McpClient: class {
@@ -60,6 +67,7 @@ describe("McpServerManager tool selection", () => {
   beforeEach(() => {
     toolsByServer.clear();
     connectDelays.clear();
+    mcpGlobalMaxTools = undefined;
   });
 
   test("later servers keep tools when eight servers exceed the global cap", async () => {
@@ -108,4 +116,29 @@ describe("McpServerManager tool selection", () => {
     ).toBe(true);
     await manager.stop();
   });
+
+  test("a workspace global-max override raises how many tools are kept", async () => {
+    const ids = Array.from(
+      { length: 8 },
+      (_, i) => `server-${String(i + 1).padStart(2, "0")}`,
+    );
+    for (const id of ids) {
+      toolsByServer.set(
+        id,
+        Array.from({ length: 10 }, (_, i) => ({ name: `tool_${i}` })),
+      );
+    }
+
+    mcpGlobalMaxTools = 80;
+    const manager = new McpServerManager();
+    const started = await manager.start(configWith(ids));
+
+    expect(started.discoveredToolCount).toBe(80);
+    expect(started.keptToolCount).toBe(80);
+    expect(started.droppedToolCount).toBe(0);
+    expect(started.servers.every((server) => server.tools.length === 10)).toBe(
+      true,
+    );
+    await manager.stop();
+  });
 });

package/src/mcp/__tests__/tool-caps.test.ts

@@ -10,7 +10,7 @@ import {
   MCP_GLOBAL_MAX_TOOLS,
   MCP_MAX_TOOLS_PER_SERVER,
 } from "../../config/schemas/mcp.js";
-import { applyMcpToolCaps } from "../tool-caps.js";
+import { applyMcpToolCaps, resolveMcpGlobalMaxTools } from "../tool-caps.js";
 
 function toolsNamed(prefix: string, count: number): string[] {
   return Array.from({ length: count }, (_, i) => `${prefix}-tool-${i}`);
@@ -104,4 +104,31 @@ describe("applyMcpToolCaps", () => {
       4,
     );
   });
+
+  test("honors a workspace global-max override", () => {
+    const servers = Array.from({ length: 8 }, (_, i) => ({
+      serverId: `server-${String(i + 1).padStart(2, "0")}`,
+      tools: toolsNamed(`s${i + 1}`, 10),
+    }));
+
+    const result = applyMcpToolCaps(servers, { globalMax: 80, perServerMax: 20 });
+
+    expect(result.keptToolCount).toBe(80);
+    expect(result.droppedToolCount).toBe(0);
+    expect(result.servers.every((server) => server.tools.length === 10)).toBe(
+      true,
+    );
+  });
+});
+
+describe("resolveMcpGlobalMaxTools", () => {
+  test("uses the shipped default when the workspace omits the override", () => {
+    expect(resolveMcpGlobalMaxTools()).toBe(MCP_GLOBAL_MAX_TOOLS);
+    expect(resolveMcpGlobalMaxTools({})).toBe(MCP_GLOBAL_MAX_TOOLS);
+  });
+
+  test("uses tools.mcpGlobalMaxTools from config.json when set", () => {
+    expect(resolveMcpGlobalMaxTools({ mcpGlobalMaxTools: 80 })).toBe(80);
+    expect(resolveMcpGlobalMaxTools({ mcpGlobalMaxTools: 1 })).toBe(1);
+  });
 });

package/src/mcp/manager.ts

@@ -1,3 +1,4 @@
+import { getConfig } from "../config/loader.js";
 import type {
   ResolvedMcpConfig,
   ResolvedMcpServerConfig,
@@ -6,6 +7,7 @@ import { getLogger } from "../util/logger.js";
 import { McpClient, type McpToolInfo } from "./client.js";
 import {
   applyMcpToolCaps,
+  resolveMcpGlobalMaxTools,
   truncatedServerIdsFromCaps,
 } from "./tool-caps.js";
 
@@ -78,6 +80,7 @@ export class McpServerManager {
         serverId: result.serverId,
         tools: result.tools,
       })),
+      { globalMax: resolveMcpGlobalMaxTools(getConfig().tools) },
     );
     const keptByServer = new Map(
       capped.servers.map((server) => [server.serverId, server.tools]),

package/src/mcp/tool-caps.ts

@@ -1,10 +1,11 @@
 /**
  * Code-owned MCP tool-count caps and the selection used when they bind.
  *
- * Caps live here, not in workspace config: migration 153 strips
- * `maxTools` / `globalMaxTools` from `config.json`. The numbers are a
- * context-window budget, not a permission gate. Allowlists and risk
- * still decide what a turn may call.
+ * The shipped global cap is {@link MCP_GLOBAL_MAX_TOOLS}. A workspace may
+ * raise or lower it with `tools.mcpGlobalMaxTools` in config.json. The
+ * per-server cap stays code-owned. These numbers are a context-window
+ * budget, not a permission gate. Allowlists and risk still decide what
+ * a turn may call.
  *
  * The global cap is applied by a deterministic round-robin across
  * servers sorted by id. Insertion order must not empty a later server
@@ -15,6 +16,7 @@ import {
   MCP_GLOBAL_MAX_TOOLS,
   MCP_MAX_TOOLS_PER_SERVER,
 } from "../config/schemas/mcp.js";
+import type { ToolsConfig } from "../config/schemas/tools.js";
 
 export interface McpServerToolSet<T> {
   serverId: string;
@@ -39,6 +41,12 @@ export interface McpToolCapResult<T> {
   decisions: McpToolCapDecision[];
 }
 
+export function resolveMcpGlobalMaxTools(
+  tools?: Pick<ToolsConfig, "mcpGlobalMaxTools">,
+): number {
+  return tools?.mcpGlobalMaxTools ?? MCP_GLOBAL_MAX_TOOLS;
+}
+
 export function applyMcpToolCaps<T>(
   servers: ReadonlyArray<McpServerToolSet<T>>,
   options?: { globalMax?: number; perServerMax?: number },

package/src/monitoring/__tests__/control.test.ts

@@ -167,19 +167,26 @@ describe("spawnMonitoringWorkerProcess", () => {
     }
   });
 
-  test("reuses an already-running monitor without spawning", async () => {
+  test("spawns when the PID file names an unrelated live process", async () => {
     writeFileSync(pidPath, String(process.pid));
     let spawned = false;
     const restore = stubBunSpawn(() => {
       spawned = true;
-      return { unref: () => {}, kill: () => {}, pid: 1, exited: neverExits() };
+      writeFileSync(pidPath, "4242");
+      return {
+        unref: () => {},
+        kill: () => {},
+        pid: 4242,
+        exited: neverExits(),
+      };
     });
     try {
       const result = await spawnMonitoringWorkerProcess({
-        pidWaitTimeoutMs: 100,
+        pidWaitTimeoutMs: 1_000,
+        pidPollIntervalMs: 10,
       });
-      expect(result).toEqual({ pid: process.pid, alreadyRunning: true });
-      expect(spawned).toBe(false);
+      expect(result).toEqual({ pid: 4242, alreadyRunning: false });
+      expect(spawned).toBe(true);
     } finally {
       restore();
     }
@@ -201,6 +208,11 @@ describe("probeMonitoringWorker", () => {
     }
   });
 
+  test("reports not_running when the PID file names a live process that is not this worker", () => {
+    writeFileSync(pidPath, String(process.pid));
+    expect(probeMonitoringWorker()).toEqual({ status: "not_running" });
+  });
+
   test("reports running (not throws) when the process exists but is not signalable (EPERM)", () => {
     writeFileSync(pidPath, "4321");
     const restore = stubProcessKill(new Set(), new Set([4321]));

package/src/monitoring/control.ts

@@ -19,15 +19,21 @@ import {
   type WorkerProcessStatus,
 } from "../util/worker-process.js";
 
+const MONITORING_WORKER_ENTRY = new URL("./worker.ts", import.meta.url);
+
 const log = getLogger("monitoring-control");
 
 /**
  * Read the PID file and report liveness. A missing or malformed file reports
- * not_running; a file pointing at a dead process is cleaned up and reported as
- * not_running.
+ * not_running; a file pointing at a dead process, or at a live process that
+ * is not this worker, is cleaned up and reported as not_running.
  */
 export function probeMonitoringWorker(): WorkerProcessStatus {
-  return probeWorkerPidFile(getMonitoringPidPath());
+  return probeWorkerPidFile(
+    getMonitoringPidPath(),
+    MONITORING_WORKER_ENTRY,
+    "monitoring",
+  );
 }
 
 export class MonitoringWorkerSpawnError extends WorkerProcessSpawnError {}
@@ -44,7 +50,7 @@ export async function spawnMonitoringWorkerProcess(
   try {
     return await spawnWorkerProcess({
       pidPath: getMonitoringPidPath(),
-      entry: new URL("./worker.ts", import.meta.url),
+      entry: MONITORING_WORKER_ENTRY,
       packagedEntry: "monitoring",
       workerLabel: "Resource monitor",
       options: opts,
@@ -63,7 +69,11 @@ export async function spawnMonitoringWorkerProcess(
  * (e.g. EPERM) — a not-running monitor is a no-op.
  */
 export function stopMonitoringWorkerProcess(): WorkerProcessStatus {
-  return stopWorkerProcess(getMonitoringPidPath());
+  return stopWorkerProcess(
+    getMonitoringPidPath(),
+    MONITORING_WORKER_ENTRY,
+    "monitoring",
+  );
 }
 
 /**

package/src/plugins/defaults/memory/__tests__/worker-control.test.ts

@@ -231,18 +231,26 @@ describe("spawnMemoryWorkerProcess", () => {
     }
   });
 
-  test("reuses an already-running worker without spawning", async () => {
-    // A live PID file (this test process) makes the probe report running.
+  test("spawns when the PID file names an unrelated live process", async () => {
     writeFileSync(pidPath, String(process.pid));
     let spawned = false;
     const restore = stubBunSpawn(() => {
       spawned = true;
-      return { unref: () => {}, kill: () => {}, pid: 1, exited: neverExits() };
+      writeFileSync(pidPath, "4242");
+      return {
+        unref: () => {},
+        kill: () => {},
+        pid: 4242,
+        exited: neverExits(),
+      };
     });
     try {
-      const result = await spawnMemoryWorkerProcess({ pidWaitTimeoutMs: 100 });
-      expect(result).toEqual({ pid: process.pid, alreadyRunning: true });
-      expect(spawned).toBe(false);
+      const result = await spawnMemoryWorkerProcess({
+        pidWaitTimeoutMs: 1_000,
+        pidPollIntervalMs: 10,
+      });
+      expect(result).toEqual({ pid: 4242, alreadyRunning: false });
+      expect(spawned).toBe(true);
     } finally {
       restore();
     }
@@ -250,6 +258,11 @@ describe("spawnMemoryWorkerProcess", () => {
 });
 
 describe("probeMemoryWorker", () => {
+  test("reports not_running when the PID file names a live process that is not this worker", () => {
+    writeFileSync(pidPath, String(process.pid));
+    expect(probeMemoryWorker()).toEqual({ status: "not_running" });
+  });
+
   test("reports running (not throws) when the process exists but is not signalable (EPERM)", () => {
     writeFileSync(pidPath, "4321");
     const restore = stubProcessKill(new Set(), new Set([4321]));

package/src/plugins/defaults/memory/worker-control.ts

@@ -18,13 +18,19 @@ import {
   type WorkerProcessStatus,
 } from "../../../util/worker-process.js";
 
+const MEMORY_WORKER_ENTRY = new URL("./worker.ts", import.meta.url);
+
 /**
  * Inspect the PID file to determine whether the worker process is alive.
- * A stale PID file (pointing at a dead process) is cleaned up and reported
- * as not_running.
+ * A stale PID file (pointing at a dead process, or at a live process that
+ * is not this worker) is cleaned up and reported as not_running.
  */
 export function probeMemoryWorker(): WorkerProcessStatus {
-  return probeWorkerPidFile(getMemoryWorkerPidPath());
+  return probeWorkerPidFile(
+    getMemoryWorkerPidPath(),
+    MEMORY_WORKER_ENTRY,
+    "memory",
+  );
 }
 
 export class MemoryWorkerSpawnError extends WorkerProcessSpawnError {}
@@ -50,7 +56,7 @@ export async function spawnMemoryWorkerProcess(
   try {
     return await spawnWorkerProcess({
       pidPath: getMemoryWorkerPidPath(),
-      entry: new URL("./worker.ts", import.meta.url),
+      entry: MEMORY_WORKER_ENTRY,
       packagedEntry: "memory",
       workerLabel: "Memory worker",
       options: opts,
@@ -71,5 +77,9 @@ export async function spawnMemoryWorkerProcess(
  * (e.g. EPERM) — a not-running worker is a no-op.
  */
 export function stopMemoryWorkerProcess(): WorkerProcessStatus {
-  return stopWorkerProcess(getMemoryWorkerPidPath());
+  return stopWorkerProcess(
+    getMemoryWorkerPidPath(),
+    MEMORY_WORKER_ENTRY,
+    "memory",
+  );
 }

package/src/routes/control.ts

@@ -44,13 +44,15 @@ function routeHostPidPath(): string {
   return getProcPidPath(ROUTE_HOST_PROC_NAME);
 }
 
+const ROUTE_HOST_ENTRY = new URL("./worker.ts", import.meta.url);
+
 /**
  * Read the PID file and report liveness. A missing or malformed file reports
- * not_running; a file pointing at a dead process is cleaned up and reported as
- * not_running.
+ * not_running; a file pointing at a dead process, or at a live process that
+ * is not this worker, is cleaned up and reported as not_running.
  */
 export function probeRouteHostWorker(): WorkerProcessStatus {
-  return probeWorkerPidFile(routeHostPidPath());
+  return probeWorkerPidFile(routeHostPidPath(), ROUTE_HOST_ENTRY, "routes");
 }
 
 export class RouteHostSpawnError extends WorkerProcessSpawnError {}
@@ -67,7 +69,7 @@ export async function spawnRouteHostWorkerProcess(
   try {
     return await spawnWorkerProcess({
       pidPath: routeHostPidPath(),
-      entry: new URL("./worker.ts", import.meta.url),
+      entry: ROUTE_HOST_ENTRY,
       packagedEntry: "routes",
       workerLabel: "Route host",
       options: opts,
@@ -86,7 +88,7 @@ export async function spawnRouteHostWorkerProcess(
  * (e.g. EPERM) — a not-running host is a no-op.
  */
 export function stopRouteHostWorkerProcess(): WorkerProcessStatus {
-  return stopWorkerProcess(routeHostPidPath());
+  return stopWorkerProcess(routeHostPidPath(), ROUTE_HOST_ENTRY, "routes");
 }
 
 /**

package/src/schedule/__tests__/worker-control.test.ts

@@ -206,19 +206,26 @@ describe("spawnScheduleWorkerProcess", () => {
     }
   });
 
-  test("reuses an already-running worker without spawning", async () => {
+  test("spawns when the PID file names an unrelated live process", async () => {
     writeFileSync(pidPath, String(process.pid));
     let spawned = false;
     const restore = stubBunSpawn(() => {
       spawned = true;
-      return { unref: () => {}, kill: () => {}, pid: 1, exited: neverExits() };
+      writeFileSync(pidPath, "4242");
+      return {
+        unref: () => {},
+        kill: () => {},
+        pid: 4242,
+        exited: neverExits(),
+      };
     });
     try {
       const result = await spawnScheduleWorkerProcess({
-        pidWaitTimeoutMs: 100,
+        pidWaitTimeoutMs: 1_000,
+        pidPollIntervalMs: 10,
       });
-      expect(result).toEqual({ pid: process.pid, alreadyRunning: true });
-      expect(spawned).toBe(false);
+      expect(result).toEqual({ pid: 4242, alreadyRunning: false });
+      expect(spawned).toBe(true);
     } finally {
       restore();
     }
@@ -240,6 +247,11 @@ describe("probeScheduleWorker", () => {
     }
   });
 
+  test("reports not_running when the PID file names a live process that is not this worker", () => {
+    writeFileSync(pidPath, String(process.pid));
+    expect(probeScheduleWorker()).toEqual({ status: "not_running" });
+  });
+
   test("reports running (not throws) when the process exists but is not signalable (EPERM)", () => {
     writeFileSync(pidPath, "4321");
     const restore = stubProcessKill(new Set(), new Set([4321]));
@@ -256,6 +268,25 @@ describe("stopScheduleWorkerProcess", () => {
     expect(stopScheduleWorkerProcess()).toEqual({ status: "not_running" });
   });
 
+  test("does not signal a recycled PID that is not this worker", () => {
+    writeFileSync(pidPath, String(process.pid));
+    const signalled: Array<[number, string | number | undefined]> = [];
+    const original = process.kill.bind(process);
+    process.kill = ((pid: number, signal?: string | number) => {
+      if ((signal ?? 0) === 0) {
+        return original(pid, signal);
+      }
+      signalled.push([pid, signal]);
+      return true;
+    }) as typeof process.kill;
+    try {
+      expect(stopScheduleWorkerProcess()).toEqual({ status: "not_running" });
+      expect(signalled).toEqual([]);
+    } finally {
+      process.kill = original;
+    }
+  });
+
   test("signals a running worker and reports its prior state", () => {
     writeFileSync(pidPath, "4321");
     const signalled: Array<[number, string | number | undefined]> = [];

package/src/schedule/worker-control.ts

@@ -19,6 +19,8 @@ import {
   type WorkerProcessStatus,
 } from "../util/worker-process.js";
 
+const SCHEDULE_WORKER_ENTRY = new URL("./worker.ts", import.meta.url);
+
 const log = getLogger("schedule-worker-control");
 
 /**
@@ -42,11 +44,15 @@ export function setScheduleWorkerAdministrativelyStopped(value: boolean): void {
 
 /**
  * Inspect the PID file to determine whether the schedule worker process is
- * alive. A stale PID file (pointing at a dead process) is cleaned up and
- * reported as not_running.
+ * alive. A stale PID file (pointing at a dead process, or at a live process
+ * that is not this worker) is cleaned up and reported as not_running.
  */
 export function probeScheduleWorker(): WorkerProcessStatus {
-  return probeWorkerPidFile(getScheduleWorkerPidPath());
+  return probeWorkerPidFile(
+    getScheduleWorkerPidPath(),
+    SCHEDULE_WORKER_ENTRY,
+    "schedule",
+  );
 }
 
 export class ScheduleWorkerSpawnError extends WorkerProcessSpawnError {}
@@ -95,7 +101,7 @@ async function spawnScheduleWorkerProcessUncoalesced(
   try {
     return await spawnWorkerProcess({
       pidPath: getScheduleWorkerPidPath(),
-      entry: new URL("./worker.ts", import.meta.url),
+      entry: SCHEDULE_WORKER_ENTRY,
       packagedEntry: "schedule",
       workerLabel: "Schedule worker",
       options: opts,
@@ -114,7 +120,11 @@ async function spawnScheduleWorkerProcessUncoalesced(
  * `process.kill` itself fails (e.g. EPERM) — a not-running worker is a no-op.
  */
 export function stopScheduleWorkerProcess(): WorkerProcessStatus {
-  return stopWorkerProcess(getScheduleWorkerPidPath());
+  return stopWorkerProcess(
+    getScheduleWorkerPidPath(),
+    SCHEDULE_WORKER_ENTRY,
+    "schedule",
+  );
 }
 
 /**

package/src/skills/clawhub.ts

@@ -11,11 +11,6 @@ import {
 
 const log = getLogger("clawhub");
 
-// Managed skills directory — where installed skill folders live
-function getManagedSkillsDir(): string {
-  return getWorkspaceSkillsDir();
-}
-
 // ClaWHub project root — clawhub creates a `skills/` subdir inside its cwd,
 // so we use the parent of the managed skills dir as the project root.
 function getClawhubProjectRoot(): string {
@@ -39,7 +34,7 @@ interface IntegrityRecord {
 type IntegrityManifest = Record<string, IntegrityRecord>;
 
 function getIntegrityPath(): string {
-  return join(getManagedSkillsDir(), ".integrity.json");
+  return join(getWorkspaceSkillsDir(), ".integrity.json");
 }
 
 function loadIntegrityManifest(): IntegrityManifest {
@@ -66,7 +61,7 @@ function loadIntegrityManifest(): IntegrityManifest {
  * from skills that haven't been migrated yet.
  */
 export function verifyAndRecordSkillHash(slug: string): void {
-  const skillDir = join(getManagedSkillsDir(), slug);
+  const skillDir = join(getWorkspaceSkillsDir(), slug);
   const hash = computeSkillHash(skillDir);
   if (!hash) {
     log.warn({ slug }, "Could not compute content hash for installed skill");
@@ -232,7 +227,7 @@ function getSkillNameFromSlug(slug: string): string {
 }
 
 function getClawhubSkillsDir(projectRoot?: string): string {
-  return projectRoot ? join(projectRoot, "skills") : getManagedSkillsDir();
+  return projectRoot ? join(projectRoot, "skills") : getWorkspaceSkillsDir();
 }
 
 function hasRootSkillFile(skillDir: string): boolean {

package/src/skills/managed-store.ts

@@ -44,13 +44,9 @@ export function validateManagedSkillId(id: string): string | null {
 
 // ─── Path helpers ────────────────────────────────────────────────────────────
 
-function getManagedSkillsDir(): string {
-  return getWorkspaceSkillsDir();
-}
-
 /** Absolute path of a managed skill's directory (whether or not it exists). */
 export function getManagedSkillDir(id: string): string {
-  return join(getManagedSkillsDir(), id);
+  return join(getWorkspaceSkillsDir(), id);
 }
 
 interface ResolvedCompanionPath {

package/src/util/__tests__/worker-process-command.test.ts

@@ -205,11 +205,12 @@ describe("decideWorkerSlot", () => {
     ).toEqual({ action: "adopt", pid: WORKER });
   });
 
-  // The cases below are the ones that must never reach a kill.
+  // The cases below must never reach a kill. Unmatched command lines spawn
+  // a new worker without signalling the stranger holding the recycled PID.
   test("never signals an unrelated process on a recycled PID", () => {
     expect(
       decide({ pid: WORKER, ppid: 1, command: "/usr/bin/postgres -D /data" }),
-    ).toEqual({ action: "adopt", pid: WORKER });
+    ).toEqual({ action: "spawn" });
   });
 
   test("never signals another project's worker.ts on a recycled PID", () => {
@@ -219,7 +220,7 @@ describe("decideWorkerSlot", () => {
         ppid: 1,
         command: "bun run /home/dev/side-project/worker.ts",
       }),
-    ).toEqual({ action: "adopt", pid: WORKER });
+    ).toEqual({ action: "spawn" });
   });
 
   test("never signals a different worker kind holding this slot", () => {
@@ -229,7 +230,7 @@ describe("decideWorkerSlot", () => {
         ppid: 1,
         command: "bun --smol run /app/runtime/0.10.11/src/monitoring/worker.ts",
       }),
-    ).toEqual({ action: "adopt", pid: WORKER });
+    ).toEqual({ action: "spawn" });
   });
 
   test("never signals when the process table could not be read", () => {

package/src/util/worker-process.ts

@@ -50,13 +50,11 @@ function isEsrchError(err: unknown): boolean {
   );
 }
 
-/**
- * Read a PID file and report liveness. A missing or malformed file reports
- * not_running; a file pointing at a dead process is cleaned up and reported as
- * not_running. Intended for worker-process PID files whose PID is a normal
- * spawned child (never PID 1), so `process.kill(pid, 0)` liveness is reliable.
- */
-export function probeWorkerPidFile(path: string): WorkerProcessStatus {
+/** Kill-0 plus command-line identity for a PID file. */
+function probePidFile(
+  path: string,
+  signature: readonly string[],
+): WorkerProcessStatus {
   if (!existsSync(path)) {
     return { status: "not_running" };
   }
@@ -69,22 +67,49 @@ export function probeWorkerPidFile(path: string): WorkerProcessStatus {
 
   try {
     process.kill(pid, 0);
-    return { status: "running", pid };
   } catch (err: unknown) {
     if (isEsrchError(err)) {
-      // Stale file — clean it up.
-      try {
-        unlinkSync(path);
-      } catch {
-        // best-effort
-      }
+      unlinkPidFileIfNames(path, pid);
       return { status: "not_running" };
     }
     // Any other error (e.g. EPERM: the process exists but this caller may not
-    // signal it) means the process is alive. Report it running rather than
-    // letting the error escape a status probe.
-    return { status: "running", pid };
+    // signal it) means the process is alive. Fall through to the identity
+    // check rather than letting the error escape a status probe.
+  }
+
+  const fate = classifyOrphanAfterWait(
+    true,
+    readRawProcessCommand(pid),
+    signature,
+  );
+  if (fate === "gone") {
+    log.info(
+      { pid, pidPath: path },
+      "Worker PID file names a live process this runtime does not recognise as its worker; releasing the slot rather than treating it as running",
+    );
+    unlinkPidFileIfNames(path, pid);
+    return { status: "not_running" };
   }
+  return { status: "running", pid };
+}
+
+/**
+ * Read a PID file and report whether this worker is actually running there.
+ *
+ * Identity comes from the same `entry` / `packagedEntry` spawn uses. A missing
+ * or malformed file reports not_running. A file pointing at a dead process, or
+ * at a live process whose command line is not this worker (a recycled PID
+ * after a container restart), is cleaned up and reported as not_running. A
+ * live PID whose command line cannot be read is reported running: uncertainty
+ * must not start a second worker next to a maybe-live one, and must not be
+ * treated as a license to signal a stranger.
+ */
+export function probeWorkerPidFile(
+  pidPath: string,
+  entry: URL,
+  packagedEntry?: PackagedWorkerEntry,
+): WorkerProcessStatus {
+  return probePidFile(pidPath, workerKindSignature(entry, packagedEntry));
 }
 
 /** Thrown when a worker process fails to come up within the wait window. */
@@ -394,11 +419,13 @@ async function stopOrphanedWorker(
 /**
  * What to do about the process a worker's PID file currently names.
  *
- *   - `adopt`: reuse it. Either it is this process's own worker, or it belongs
- *     to another live owner, or it is not recognisably one of our workers at
- *     all and must never be signalled.
+ *   - `adopt`: reuse it. It is this process's own worker, it belongs to
+ *     another live owner, or its identity could not be read so a second
+ *     worker must not be started next to a maybe-live one.
  *   - `reclaim`: an orphan left by an owner that is gone. Stop it, then spawn.
- *   - `spawn`: nothing is holding the slot.
+ *   - `spawn`: nothing is holding the slot, including a live PID whose
+ *     command line is not this worker (a recycled PID). Never signal that
+ *     process.
  */
 export type WorkerSlotDecision =
   | { action: "adopt"; pid: number }
@@ -410,9 +437,12 @@ export type WorkerSlotDecision =
  *
  * `reclaim` is the only outcome that signals a process, and it requires two
  * independent things to agree: the command line marks the process as this
- * worker, and parentage says no daemon owns it. A missing row, an unreadable
- * command line, and a command line that does not match all fall back to
- * `adopt`, so an uncertain answer never costs a process its life.
+ * worker, and parentage says no daemon owns it. A missing row and an
+ * unreadable command line fall back to `adopt`, so an uncertain answer never
+ * costs a process its life and never starts a duplicate. A command line that
+ * does not match is `spawn` without a signal: the PID file is stale, and
+ * treating that PID as the worker would leave the slot occupied by a
+ * stranger forever.
  *
  * `isOwnerAlive` is the caller's definition of a legitimate owner. These
  * workers have exactly one, the daemon, so passing a plain liveness probe
@@ -435,7 +465,7 @@ export function decideWorkerSlot(
     return { action: "adopt", pid: status.pid };
   }
   if (!matchesSignature(row.command, signature)) {
-    return { action: "adopt", pid: status.pid };
+    return { action: "spawn" };
   }
   const ownership = classifyWorkerOwnership(
     row,
@@ -458,7 +488,7 @@ function inspectWorkerSlot(
   pidPath: string,
   signature: readonly string[],
 ): WorkerSlotDecision {
-  const status = probeWorkerPidFile(pidPath);
+  const status = probePidFile(pidPath, signature);
   if (status.status !== "running" || status.pid == null) {
     return { action: "spawn" };
   }
@@ -479,11 +509,11 @@ function inspectWorkerSlot(
   if (row && !matchesSignature(row.command, signature)) {
     log.info(
       { pid: row.pid, pidPath },
-      "Worker PID file names a live process this runtime does not recognise as its worker; reusing it rather than signalling it",
+      "Worker PID file names a live process this runtime does not recognise as its worker; releasing the slot rather than treating it as running",
     );
   }
 
-  return decideWorkerSlot(
+  const decision = decideWorkerSlot(
     status,
     row,
     signature,
@@ -491,6 +521,12 @@ function inspectWorkerSlot(
     (pid) => isDaemonCommand(commandOf(pid)),
     pid1OwnsWorkers(commandOf(1)),
   );
+  // A spawn decision while the PID file still names a live stranger would
+  // make waitForWorkerPidFile treat that stale file as readiness.
+  if (decision.action === "spawn") {
+    unlinkPidFileIfNames(pidPath, status.pid);
+  }
+  return decision;
 }
 
 /**
@@ -508,7 +544,7 @@ async function reclaimWorkerSlot(
     // Still running and beyond our reach. One stale worker beats two live ones.
     return pid;
   }
-  const replacement = probeWorkerPidFile(pidPath);
+  const replacement = probePidFile(pidPath, signature);
   return replacement.status === "running" && replacement.pid != null
     ? replacement.pid
     : null;
@@ -519,7 +555,8 @@ async function reclaimWorkerSlot(
  * process, and wait for it to report readiness by writing its PID file. The
  * child is `unref`'d, so the spawning process never blocks on it.
  *
- * If a worker is already running (per the PID file), returns its PID with
+ * If a worker is already running (the PID file names a live process whose
+ * command line matches this worker), returns its PID with
  * `alreadyRunning: true` rather than spawning a second one. Throws
  * {@link WorkerProcessSpawnError} if the child crashes during startup or
  * never writes its PID file within the wait window.
@@ -633,14 +670,19 @@ export async function spawnWorkerProcess(args: {
 
 /**
  * Send SIGTERM to the worker process behind `pidPath` if it is actually
- * running.
+ * this worker.
  *
  * Returns the status observed before signalling, so callers can report
- * whether anything was stopped. Only throws if `process.kill` itself fails
- * (e.g. EPERM) — a not-running worker is a no-op.
+ * whether anything was stopped. A PID file that names a dead process or a
+ * live process that is not this worker is a no-op. Only throws if
+ * `process.kill` itself fails (e.g. EPERM).
  */
-export function stopWorkerProcess(pidPath: string): WorkerProcessStatus {
-  const current = probeWorkerPidFile(pidPath);
+export function stopWorkerProcess(
+  pidPath: string,
+  entry: URL,
+  packagedEntry?: PackagedWorkerEntry,
+): WorkerProcessStatus {
+  const current = probeWorkerPidFile(pidPath, entry, packagedEntry);
   if (current.status === "running" && current.pid != null) {
     process.kill(current.pid, "SIGTERM");
   }