@vellumai/assistant 0.12.2 → 0.12.3-staging.2

package/src/tools/terminal/shell.ts

@@ -5,13 +5,16 @@ import { z } from "zod";
 import type { BackgroundToolCompletedEvent } from "../../api/events/background-tool-completed.js";
 import { getConfig } from "../../config/loader.js";
 import { RiskLevel } from "../../permissions/types.js";
+import { applyActivePluginName } from "../../plugins/active-plugin-env.js";
 import { wakeAgentForOpportunity } from "../../runtime/agent-wake.js";
 import { broadcastMessage } from "../../runtime/assistant-event-hub.js";
 import { conversationRevealNonce } from "../../runtime/reveal-nonce.js";
 import { redactSecrets } from "../../security/secret-scanner.js";
 import {
   buildShellInvocation,
+  buildShellSpawnFlags,
   terminateProcessTree,
+  watchShellProcessStart,
 } from "../../util/host-process.js";
 import { getLogger } from "../../util/logger.js";
 import { getDataDir } from "../../util/platform.js";
@@ -288,6 +291,7 @@ export const shellTool = {
 
     const env = buildSanitizedEnv();
     env.__CONVERSATION_ID = context.conversationId;
+    applyActivePluginName(env, context.conversationId);
     // Secret binding for reveal-derived chat authority — see reveal-nonce.ts.
     env.__REVEAL_NONCE = conversationRevealNonce(context.conversationId);
     // Surface the resolving model to assistant CLI commands so they can tailor
@@ -324,9 +328,9 @@ export const shellTool = {
         cwd: context.workingDir,
         env,
         stdio: ["ignore", "pipe", "pipe"],
-        detached: true,
-        windowsHide: true,
+        ...buildShellSpawnFlags(),
       });
+      const launch = watchShellProcessStart(child);
       const collector = attachBoundedStdio(child);
 
       const killTree = buildKillTree(child, {
@@ -367,11 +371,13 @@ export const shellTool = {
           timedOut,
         });
 
-        const fmtResult = collector.format(code, timedOut, timeoutSec);
+        const fmtResult = collector.format(code, timedOut, timeoutSec, {
+          started: launch.didStart(),
+        });
 
         const status: BackgroundToolCompletedEvent["status"] = aborted
           ? "cancelled"
-          : timedOut
+          : timedOut || fmtResult.isError
             ? "failed"
             : code === 0
               ? "completed"
@@ -529,9 +535,9 @@ export const shellTool = {
         cwd: context.workingDir,
         env,
         stdio: ["ignore", "pipe", "pipe"],
-        detached: true,
-        windowsHide: true,
+        ...buildShellSpawnFlags(),
       });
+      const launch = watchShellProcessStart(child);
       const collector = attachBoundedStdio(child, {
         onOutput: context.onOutput,
       });
@@ -573,7 +579,9 @@ export const shellTool = {
           timedOut,
         });
 
-        const fmtResult = collector.format(code, timedOut, timeoutSec);
+        const fmtResult = collector.format(code, timedOut, timeoutSec, {
+          started: launch.didStart(),
+        });
 
         resolve({
           content: fmtResult.content,

package/src/tools/tool-approval-handler.ts

@@ -837,7 +837,11 @@ export class ToolApprovalHandler {
     // sandbox/host routing reflects the tool actually registered under this
     // name at execution time.
     const tool = getTool(name);
-    const executionTarget = resolveExecutionTarget(tool ?? { name });
+    const executionTarget = resolveExecutionTarget(
+      tool ?? { name },
+      input,
+      context,
+    );
 
     // Determine whether this invocation requires a scoped grant. Capture
     // the consume params now but defer the actual atomic consumption until

package/src/tools/tool-types.ts

@@ -279,9 +279,9 @@ export interface ToolContext {
   principal?: string;
   /**
    * Trust classification of the actor who initiated this tool invocation.
-   * Broadened to `string` here; the assistant narrows this back to its
-   * concrete `TrustClass` union ("guardian" | "trusted_contact" | "unknown")
-   * in `assistant/src/tools/types.ts`.
+   * Broadened to `string` here; the assistant narrows this back to
+   * `TrustClass` (declared in `@vellumai/gateway-client`) in
+   * `assistant/src/tools/types.ts`.
    */
   trustClass: string;
   /** Channel through which the tool invocation originates (e.g. 'telegram', 'phone'). Used for scoped grant consumption. */

package/src/tools/types.ts

@@ -6,6 +6,7 @@ import type {
 import { z } from "zod";
 
 import type { AnsweredQuestion } from "../api/events/question-answered.js";
+import type { ToolActivityMetadata } from "../api/events/tool-result.js";
 import {
   CLIENT_OS_VALUES,
   type ClientOs,
@@ -13,7 +14,6 @@ import {
 } from "../channels/types.js";
 import type { LLMCallSite } from "../config/schemas/llm.js";
 import { SEND_USER_MESSAGE_TOOL_NAME } from "../config/send-user-message-constants.js";
-import type { ToolActivityMetadata } from "../daemon/message-types/web-activity.js";
 import type { SecretPromptResult } from "../permissions/secret-prompt-types.js";
 import type { ContentBlock } from "../providers/types.js";
 import type { TrustClass } from "../runtime/trust-class.js";
@@ -605,7 +605,13 @@ export type ToolDefinition = z.infer<typeof ToolDefinitionSchema>;
 export type Tool = Required<
   Omit<ToolDefinition, "exclusive" | "supportedClientOs">
 > &
-  Pick<ToolDefinition, "exclusive" | "supportedClientOs">;
+  Pick<ToolDefinition, "exclusive" | "supportedClientOs"> & {
+    /** Invocation-specific boundary for trusted tool implementations. */
+    getExecutionTarget?: (
+      input: Record<string, unknown>,
+      context?: ToolContext,
+    ) => "sandbox" | "host";
+  };
 
 /**
  * The kind of entity that owns a tool. `"default"` is the built-in tool set

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/abort-reasons.ts

@@ -78,49 +78,41 @@ export function isUserInterruptAbort(reason: AbortReason | undefined): boolean {
  */
 export const CANCELLED_TOOL_RESULT_TEXT = "Cancelled by user";
 
-/**
- * The instruction both interrupt annotations end on: answer the message that
- * interrupted, then decide what happens to the work it cut off.
- *
- * Shared so the two annotations cannot drift. Resuming the work inline is the
- * trap the last clause closes: the reply the user is waiting for arrives only
- * once the resumed work finishes, so an interrupt that was meant to get their
- * question answered first buys nothing. A subagent carries the work in
- * parallel and leaves the conversation free.
- */
-const INTERRUPT_PRIORITY_INSTRUCTION =
-  "reply to it first, then decide whether to resume or abandon the work that was in progress, and if it is still wanted and too big to finish inline, hand it to a subagent so it continues in parallel instead of holding up the conversation. This is the normal way a conversation flows, not a problem: do not apologize, do not mention that anything was stopped or interrupted, and do not ask the user to wait.";
-
 /**
  * Synthetic `tool_result` text for a tool call a newly arrived user message
  * cut off.
  *
+ * States the fact about this one call and nothing else. What the model should
+ * do about the interruption belongs on the interrupting message
+ * ({@link INTERRUPTED_TURN_NOTE_TEXT}), which is read once no matter how many
+ * calls the abort stopped and which sits after the user's words rather than
+ * before them.
+ *
  * Distinct from {@link CANCELLED_TOOL_RESULT_TEXT} because the model's next
  * decision is different. A plain cancel ends the work; a preemption means a
- * message is waiting, the abandoned call may well have taken effect on the
- * outside world before the abort landed, and the model has to answer the new
- * message before it decides what to do about the work it was doing.
+ * message is waiting, and the abandoned call may well have taken effect on the
+ * outside world before the abort landed.
  */
-export const PREEMPTED_TOOL_RESULT_TEXT = `A new message from the user arrived, so this tool call was stopped early. It may still have completed; check before repeating it. Treat the new message as the priority: ${INTERRUPT_PRIORITY_INSTRUCTION}`;
+export const PREEMPTED_TOOL_RESULT_TEXT =
+  "Stopped early because the user sent a new message. This call may have completed anyway; check before repeating it.";
 
 /**
  * Annotation appended to the LLM-facing content of the user message that
- * interrupted a turn, for the interrupt that landed with no tool call in
- * flight.
+ * interrupted a turn.
  *
- * A preemption caught mid-tool tells the model what happened through the
- * synthetic {@link PREEMPTED_TOOL_RESULT_TEXT} result. An abort that lands
- * during the provider call has no `tool_use` to answer, so the history the
- * next turn reads is the abandoned turn followed by this message, with nothing
- * saying the plan behind it was cut off. Without the note the model answers
- * the new message and drops the work it had just committed to.
+ * The one place the behavior after an interrupt is spelled out, and it rides
+ * on every interrupt, whether or not a tool call was stopped. Leading with the
+ * short reply is the point: the user is waiting to learn they were heard, and
+ * a turn that opens with more reasoning or another tool call leaves them
+ * staring at silence.
  *
  * Tagged rather than written as prose so it reads as a system annotation on
  * the message instead of something the user typed. It rides on the LLM-facing
  * content only: the persisted row stays exactly what the user sent, so no
  * client renders it.
  */
-export const INTERRUPTED_TURN_NOTE_TEXT = `<interrupted_turn>This message arrived while the previous turn was still thinking, before it had made any tool call, so that turn ended here. Treat this message as the priority: ${INTERRUPT_PRIORITY_INSTRUCTION}</interrupted_turn>`;
+export const INTERRUPTED_TURN_NOTE_TEXT =
+  "<interrupted_turn>The user sent this while you were still working, so that work stopped. Reply right away, in a line or two, before any more thinking or tool calls, so the user knows you heard them. Then pick the earlier work back up only if it is still wanted. Never apologize for or mention the interruption.</interrupted_turn>";
 
 /**
  * The synthetic `tool_result` text that matches why the turn was aborted.

package/src/util/browser-human-verification.ts

@@ -0,0 +1,14 @@
+export const HUMAN_VERIFICATION_GUIDANCE =
+  "CAPTCHAs and bot-detection challenges must be completed by the user. " +
+  "This includes drag-to-verify sliders, press-and-hold checks, verification checkboxes and image puzzles. " +
+  "Stop before attempting the challenge, even when its controls look easy to automate. " +
+  "Do not click, drag, hold, script or retry the verification yourself.";
+
+export const DESKTOP_HELP_GUIDANCE =
+  HUMAN_VERIFICATION_GUIDANCE +
+  " In the virtual desktop, immediately call ask_question with " +
+  "desktopHelp: { message, doneLabel, skipLabel } in the user's language. " +
+  "Keep message to one short sentence explaining the needed human action. " +
+  "This shows an inline preview with Step In, Done and Skip. Wait for the response. " +
+  "After Done, inspect a fresh snapshot. If verification remains, request help again. " +
+  "Skip leaves the challenge unresolved. Use the same desktopHelp request for other steps that require direct user interaction.";

package/src/util/canonicalize-identity.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, test } from "bun:test";
+
+import { inboundIdentitiesMatch } from "./canonicalize-identity.js";
+
+describe("inboundIdentitiesMatch", () => {
+  test("matches ids that canonicalize to the same sender", () => {
+    expect(inboundIdentitiesMatch("slack", " U123 ", "U123")).toBe(true);
+    expect(
+      inboundIdentitiesMatch("email", "USER@example.com", "user@example.com"),
+    ).toBe(true);
+  });
+
+  test("distinct senders do not match", () => {
+    expect(inboundIdentitiesMatch("slack", "U123", "U456")).toBe(false);
+  });
+
+  test("an empty identifier matches nothing, not even another empty one", () => {
+    expect(inboundIdentitiesMatch("slack", "", "")).toBe(false);
+    expect(inboundIdentitiesMatch("slack", "  ", "U123")).toBe(false);
+  });
+});

package/src/util/canonicalize-identity.ts

@@ -55,3 +55,19 @@ export function canonicalizeInboundIdentity(
 
   return trimmed;
 }
+
+/**
+ * Whether two raw identifiers name the same sender on `channel`. An empty
+ * identifier matches nothing.
+ */
+export function inboundIdentitiesMatch(
+  channel: ChannelId,
+  left: string,
+  right: string,
+): boolean {
+  const canonicalLeft = canonicalizeInboundIdentity(channel, left);
+  return (
+    canonicalLeft !== null &&
+    canonicalLeft === canonicalizeInboundIdentity(channel, right)
+  );
+}

package/src/util/errors.ts

@@ -151,11 +151,19 @@ export class ProviderError extends AssistantError {
   public readonly apiErrorParam?: string;
   public readonly requestId?: string;
   /**
-   * Verbatim upstream non-2xx body (possibly truncated). Persisted so the
-   * inspector's Raw tab can show the actual provider error payload, not just
-   * the extracted fields.
+   * Verbatim upstream non-2xx response body (possibly truncated). This is
+   * what the provider returned after rejecting the call, not the request
+   * we sent. The inspector's Raw tab uses it when a 4xx/5xx body carries
+   * detail the extracted `apiError*` fields drop.
    */
   public readonly rawBody?: string;
+  /**
+   * Inspectable SDK/wire request payload for the call that failed. This is
+   * the outbound request, not the error response (`rawBody`). Provider
+   * `sendMessage` throws attach it so inspector rows show the same request
+   * shape as a successful `usage` row.
+   */
+  public readonly rawRequest?: unknown;
   /**
    * Tagged daemon-owned abort reason carried over from the AbortSignal that
    * triggered this error. Untyped here to avoid a daemon→util import cycle;
@@ -181,6 +189,7 @@ export class ProviderError extends AssistantError {
       apiErrorParam?: string;
       requestId?: string;
       rawBody?: string;
+      rawRequest?: unknown;
       reason?: ProviderErrorReason;
     },
   ) {
@@ -192,6 +201,7 @@ export class ProviderError extends AssistantError {
     this.apiErrorParam = options?.apiErrorParam;
     this.requestId = options?.requestId;
     this.rawBody = options?.rawBody;
+    this.rawRequest = options?.rawRequest;
     this.abortReason = options?.abortReason;
     this.reason = options?.reason;
   }

package/src/util/host-process.test.ts

@@ -1,6 +1,7 @@
+import { EventEmitter } from "node:events";
 import { expect, mock, test } from "bun:test";
 
-import { terminateProcessTree } from "./host-process.js";
+import { terminateProcessTree, watchShellProcessStart } from "./host-process.js";
 
 test("Windows process trees use taskkill and fall back to the direct child", () => {
   const kill = mock(() => true);
@@ -15,3 +16,18 @@ test("Windows process trees use taskkill and fall back to the direct child", ()
   expect(kill).toHaveBeenCalledTimes(1);
   expect(kill).toHaveBeenCalledWith();
 });
+
+test("watchShellProcessStart is false until spawn or a pid appears", () => {
+  const child = new EventEmitter() as EventEmitter & { pid?: number };
+  const launch = watchShellProcessStart(child);
+  expect(launch.didStart()).toBe(false);
+
+  child.emit("spawn");
+  expect(launch.didStart()).toBe(true);
+});
+
+test("watchShellProcessStart treats a pid assigned at construction as started", () => {
+  const child = new EventEmitter() as EventEmitter & { pid?: number };
+  child.pid = 4242;
+  expect(watchShellProcessStart(child).didStart()).toBe(true);
+});

package/src/util/host-process.ts

@@ -2,10 +2,34 @@ import { spawn } from "node:child_process";
 
 export {
   buildShellInvocation,
+  buildShellSpawnFlags,
   pathListDelimiter,
   prependUniquePathEntries,
 } from "@vellumai/environments/shell";
 
+export interface ShellProcessStartWatch {
+  didStart(): boolean;
+}
+
+/**
+ * Record whether a spawned child actually started. A `close` with exit 0 and
+ * empty stdio is not proof of execution: Windows can emit that when the
+ * process was never created. Callers must treat `didStart() === false` as a
+ * launch failure.
+ */
+export function watchShellProcessStart(child: {
+  pid?: number;
+  once(event: "spawn", listener: () => void): unknown;
+}): ShellProcessStartWatch {
+  let spawnSeen = child.pid != null;
+  child.once("spawn", () => {
+    spawnSeen = true;
+  });
+  return {
+    didStart: () => spawnSeen || child.pid != null,
+  };
+}
+
 export interface KillableProcess {
   pid?: number;
   kill: unknown;

package/src/util/provider-error-patterns.ts

@@ -33,6 +33,9 @@ export function isVisionNotSupportedError(message: string): boolean {
 export const CHAT_TEMPLATE_FAILURE_PATTERNS = [
   /appl\w* (?:the )?chat[ _-]?template/i,
   /chat[ _-]?template (?:error|render)/i,
+  // Fireworks surfaces the renderer's raw Python str.join TypeError without
+  // naming the template: "sequence item 0: expected str instance, list found".
+  /sequence item \d+: expected str instance, list found/i,
 ];
 
 /**

package/src/util/unicode.ts

@@ -67,6 +67,35 @@ export function safeStringSlice(
   return str.slice(safeStart, safeEnd);
 }
 
+/**
+ * A `[start, end)` character window of at most `maxChars` code units that
+ * never splits a surrogate pair, for paging through text by offset. A split
+ * leaves a lone half at each edge, and each encodes to U+FFFD, so the
+ * character is lost from both this window and the next one paged in after
+ * it. `charCodeAt` reads the underlying text so a caller need not hold it as
+ * one string.
+ */
+export function surrogateSafeWindow(
+  total: number,
+  charCodeAt: (index: number) => number,
+  requestedStart: number,
+  maxChars: number,
+): { start: number; end: number } {
+  let start = Math.max(0, Math.min(requestedStart, total));
+  if (start > 0 && start < total && isLowSurrogate(charCodeAt(start))) {
+    start -= 1;
+  }
+
+  let end = Math.min(total, start + maxChars);
+  if (end > start && end < total && isHighSurrogate(charCodeAt(end - 1))) {
+    // Backing off would empty a one-character window, which stalls paging on
+    // the same offset, so take the whole pair instead.
+    end = end - 1 > start ? end - 1 : Math.min(total, end + 1);
+  }
+
+  return { start, end };
+}
+
 /**
  * Replace every orphaned UTF-16 surrogate in `str` with U+FFFD
  * (REPLACEMENT CHARACTER).

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");
   }