@vellumai/assistant 0.12.2 → 0.12.3-staging.1

package/src/tools/ask-question/ask-question-tool.test.ts

@@ -15,6 +15,13 @@ import type { ToolContext } from "../types.js";
 // `mock.module` is hoisted by bun before any static import of the tool
 // runs, so the import below sees the stubbed prompter even though
 // `askQuestionTool` captures the symbol at module-eval time.
+const finishDesktopHelp = mock(async (_resume: boolean) => {});
+const prepareDesktopHelp = mock(
+  async (_context: ToolContext) => finishDesktopHelp,
+);
+let promptError: Error | undefined;
+mock.module("../../desktop/desktop-help.js", () => ({ prepareDesktopHelp }));
+
 const calls: QuestionPromptParams[] = [];
 let nextResult: QuestionPromptResult = {
   entries: [{ questionId: "q1", decision: "skipped" }],
@@ -28,6 +35,9 @@ mock.module("../../permissions/question-prompter.js", () => ({
   QuestionPrompter: class {
     async prompt(params: QuestionPromptParams): Promise<QuestionPromptOutcome> {
       calls.push(params);
+      if (promptError) {
+        throw promptError;
+      }
       // Mirror the real prompter: it mints the request id and assigns the
       // per-question `q1..qN` ids, then returns them alongside the resolution.
       return {
@@ -61,6 +71,9 @@ function makeContext(overrides: Partial<ToolContext> = {}): ToolContext {
 // `setNextResult()` before invoking `askQuestionTool.execute(...)`.
 beforeEach(() => {
   calls.length = 0;
+  prepareDesktopHelp.mockClear();
+  finishDesktopHelp.mockClear();
+  promptError = undefined;
   nextResult = {
     entries: [{ questionId: "q1", decision: "skipped" }],
     overall: "completed",
@@ -100,7 +113,7 @@ describe("askQuestionTool definition", () => {
     expect(def.description).toContain("up to 5");
     expect(def.description).toContain("Skip button");
 
-    const schema = def.input_schema as {
+    const schema = def.input_schema as unknown as {
       properties: Record<
         string,
         {
@@ -670,7 +683,7 @@ describe("AskQuestionTool batched input", () => {
 });
 
 describe("askQuestionTool definition (batched schema)", () => {
-  test("exposes `questions[]` shape, requires it, and drops the flat fields", () => {
+  test("exposes batched questions and a desktop help alternative", () => {
     const def = askQuestionTool;
     const schema = def.input_schema as unknown as {
       properties: Record<
@@ -708,9 +721,7 @@ describe("askQuestionTool definition (batched schema)", () => {
 
     expect(questions?.items?.required).toEqual(["question", "options"]);
 
-    // `questions` is the only top-level input now.
-    expect(schema.required).toEqual(["questions"]);
-    expect(Object.keys(schema.properties)).toEqual(["questions"]);
+    expect(schema.properties.desktopHelp?.type).toBe("object");
 
     // The legacy flat fields are gone.
     expect(schema.properties.question).toBeUndefined();
@@ -825,3 +836,154 @@ describe("answered-question record", () => {
     ).toBeUndefined();
   });
 });
+
+describe("virtual desktop help", () => {
+  test("reserves the desktop before waiting and resumes control after Done", async () => {
+    setNextResult(singleCompleted({ decision: "option", optionId: "done" }));
+    const result = await askQuestionTool.execute(
+      {
+        desktopHelp: {
+          message: "Please complete the CAPTCHA.",
+          doneLabel: "Done",
+          skipLabel: "Skip",
+        },
+      },
+      makeContext(),
+    );
+    expect(prepareDesktopHelp).toHaveBeenCalledTimes(1);
+    expect(finishDesktopHelp).toHaveBeenCalledWith(true);
+    expect(calls[0]?.questions[0]?.presentation).toBe("virtual_desktop");
+    expect(result.content).toContain("fresh browser snapshot");
+    expect(result.answeredQuestion?.responses[0]).toEqual({
+      questionId: "q1",
+      decision: "option",
+      optionId: "done",
+    });
+  });
+
+  test.each([
+    { decision: "skipped" as const },
+    { decision: "option" as const, optionId: "skip" },
+  ])("does not claim the obstacle was solved after Skip: %j", async (entry) => {
+    setNextResult(singleCompleted(entry));
+    const result = await askQuestionTool.execute(
+      {
+        desktopHelp: {
+          message: "Please complete the CAPTCHA.",
+          doneLabel: "Done",
+          skipLabel: "Skip",
+        },
+      },
+      makeContext(),
+    );
+    expect(finishDesktopHelp).toHaveBeenCalledWith(false);
+    expect(result.content).toContain("obstacle may still be present");
+    expect(result.isError).toBe(false);
+  });
+
+  test("does not wait for a user in a background turn", async () => {
+    await askQuestionTool.execute(
+      {
+        desktopHelp: {
+          message: "Please complete the CAPTCHA.",
+          doneLabel: "Done",
+          skipLabel: "Skip",
+        },
+      },
+      makeContext({ isInteractive: false }),
+    );
+    expect(prepareDesktopHelp).not.toHaveBeenCalled();
+    expect(calls).toHaveLength(0);
+  });
+
+  test("rejects mixing desktop help with a question batch", async () => {
+    const result = await askQuestionTool.execute(
+      {
+        ...validInput,
+        desktopHelp: {
+          message: "Please complete the CAPTCHA.",
+          doneLabel: "Done",
+          skipLabel: "Skip",
+        },
+      },
+      makeContext(),
+    );
+    expect(result.isError).toBe(true);
+    expect(calls).toHaveLength(0);
+  });
+});
+
+test("desktop help preserves model-localized fallback labels in history", async () => {
+  setNextResult(singleCompleted({ decision: "option", optionId: "done" }));
+  const result = await askQuestionTool.execute(
+    {
+      desktopHelp: {
+        message: "Completa la verificación.",
+        doneLabel: "Listo",
+        skipLabel: "Omitir",
+      },
+    },
+    makeContext(),
+  );
+  expect(calls[0]?.questions[0]?.options).toEqual([
+    { id: "done", label: "Listo" },
+    { id: "skip", label: "Omitir" },
+  ]);
+  expect(result.answeredQuestion?.questions[0]?.options).toEqual(
+    calls[0]?.questions[0]?.options,
+  );
+});
+
+test("desktop help does not park on a guardian channel without desktop controls", async () => {
+  const result = await askQuestionTool.execute(
+    {
+      desktopHelp: {
+        message: "Please sign in.",
+        doneLabel: "Done",
+        skipLabel: "Skip",
+      },
+    },
+    makeContext({
+      supportsDynamicUi: false,
+      supportsGuardianQuestionCards: true,
+    }),
+  );
+  expect(result.isError).toBe(true);
+  expect(result.content).toContain("continue in the Vellum app");
+  expect(prepareDesktopHelp).not.toHaveBeenCalled();
+  expect(calls).toHaveLength(0);
+});
+
+for (const overall of ["closed", "timed_out", "aborted"] as const) {
+  test(`desktop reservation ends when the question is ${overall}`, async () => {
+    setNextResult({ overall, entries: [] });
+    await askQuestionTool.execute(
+      {
+        desktopHelp: {
+          message: "Complete verification.",
+          doneLabel: "Done",
+          skipLabel: "Skip",
+        },
+      },
+      makeContext(),
+    );
+    expect(finishDesktopHelp).toHaveBeenCalledWith(false);
+  });
+}
+
+test("desktop reservation ends when presenting the question throws", async () => {
+  promptError = new Error("delivery failed");
+  await expect(
+    askQuestionTool.execute(
+      {
+        desktopHelp: {
+          message: "Complete verification.",
+          doneLabel: "Done",
+          skipLabel: "Skip",
+        },
+      },
+      makeContext(),
+    ),
+  ).rejects.toThrow("delivery failed");
+  expect(finishDesktopHelp).toHaveBeenCalledWith(false);
+});

package/src/tools/ask-question/ask-question-tool.ts

@@ -7,8 +7,10 @@ import type {
 import {
   QuestionPrompter,
   type QuestionPromptOutcome,
+  type QuestionPromptParamsEntry,
 } from "../../permissions/question-prompter.js";
 import { RiskLevel } from "../../permissions/types.js";
+import { DESKTOP_HELP_GUIDANCE } from "../../util/browser-human-verification.js";
 import {
   invalidToolInputResult,
   toToolInputSchema,
@@ -74,17 +76,43 @@ const MAX_QUESTIONS_PER_BATCH = 5;
 // Callers pass a (possibly single-element) batch of questions. `execute()`
 // forwards them straight to the prompter. Loose so injected fields (e.g.
 // `activity`) never fail validation.
-export const askQuestionInputSchema = z.looseObject({
-  questions: z
-    .array(SingleQuestionSchema)
-    .min(1)
-    .max(MAX_QUESTIONS_PER_BATCH, {
-      message: `At most ${MAX_QUESTIONS_PER_BATCH} questions per batch; split into multiple turns if you need more.`,
-    })
-    .describe(
-      `1–${MAX_QUESTIONS_PER_BATCH} clarifying questions to ask in a single turn. Use a batch when several independent ambiguities block progress; ask one at a time when they're sequentially dependent. Past ${MAX_QUESTIONS_PER_BATCH} questions you should be implementing, not asking.`,
-    ),
-});
+export const askQuestionInputSchema = z
+  .looseObject({
+    desktopHelp: z
+      .object({
+        message: z
+          .string()
+          .min(1)
+          .describe(
+            "Use one short sentence to explain the needed human action, in the user's language.",
+          ),
+        doneLabel: z
+          .string()
+          .min(1)
+          .describe("The label for Done in the user's language."),
+        skipLabel: z
+          .string()
+          .min(1)
+          .describe("The label for Skip in the user's language."),
+      })
+      .describe(
+        "Immediately request human interaction for any CAPTCHA or bot-detection challenge, including sliders and press-and-hold checks. Also use for native dialogs requiring user interaction. For logins, use saved credentials or securely prompt for missing credentials first. Explain what the user should do. Shows a live preview with Step In, Done and Skip. Pass this instead of questions.",
+      )
+      .optional(),
+    questions: z
+      .array(SingleQuestionSchema)
+      .min(1)
+      .max(MAX_QUESTIONS_PER_BATCH, {
+        message: `At most ${MAX_QUESTIONS_PER_BATCH} questions per batch; split into multiple turns if you need more.`,
+      })
+      .describe(
+        `1–${MAX_QUESTIONS_PER_BATCH} clarifying questions to ask in a single turn. Use a batch when several independent ambiguities block progress; ask one at a time when they're sequentially dependent. Past ${MAX_QUESTIONS_PER_BATCH} questions you should be implementing, not asking.`,
+      )
+      .optional(),
+  })
+  .refine((input) => Boolean(input.questions) !== Boolean(input.desktopHelp), {
+    message: "Provide either questions or desktopHelp, not both.",
+  });
 
 export type SingleQuestion = z.infer<typeof SingleQuestionSchema>;
 export type AskQuestionInput = z.infer<typeof askQuestionInputSchema>;
@@ -92,6 +120,10 @@ export type AskQuestionInput = z.infer<typeof askQuestionInputSchema>;
 // ── Tool description ────────────────────────────────────────────────
 
 const DESCRIPTION = [
+  DESKTOP_HELP_GUIDANCE,
+  "For logins, use saved credentials first. Securely collect missing credentials",
+  "with assistant credentials prompt, then fill the login form yourself.",
+  "",
   "Use this tool whenever a request is ambiguous and can be resolved",
   "by 2–4 plausible interpretations or discrete choices. Prefer it over",
   "plain-text clarification — structured options are faster to answer and",
@@ -223,7 +255,10 @@ export const askQuestionTool = {
   category: "interaction",
   executionTarget: "sandbox",
   defaultRiskLevel: RiskLevel.Low,
-  input_schema: toToolInputSchema(askQuestionInputSchema),
+  input_schema: {
+    ...toToolInputSchema(askQuestionInputSchema),
+    oneOf: [{ required: ["questions"] }, { required: ["desktopHelp"] }],
+  },
 
   async execute(
     input: Record<string, unknown>,
@@ -234,7 +269,19 @@ export const askQuestionTool = {
       return invalidToolInputResult("ask_question", parsed.error);
     }
 
-    const questions: SingleQuestion[] = parsed.data.questions;
+    const { desktopHelp } = parsed.data;
+    const questions: QuestionPromptParamsEntry[] = desktopHelp
+      ? [
+          {
+            question: desktopHelp.message,
+            options: [
+              { id: "done", label: desktopHelp.doneLabel },
+              { id: "skip", label: desktopHelp.skipLabel },
+            ],
+            presentation: "virtual_desktop",
+          },
+        ]
+      : parsed.data.questions!;
 
     // No interactive user is present to answer (scheduled/headless/background
     // turn). Don't park the turn on a prompt no one can resolve — proceed with
@@ -243,12 +290,21 @@ export const askQuestionTool = {
     // model asks anyway, so it doesn't wait out the full response timeout.
     if (context.isInteractive === false) {
       return {
-        content:
-          "No interactive user is present to answer; proceeding with reasonable defaults.",
+        content: desktopHelp
+          ? "No interactive user is present to help in the virtual desktop. The obstacle remains unresolved."
+          : "No interactive user is present to answer; proceeding with reasonable defaults.",
         isError: false,
       };
     }
 
+    if (desktopHelp && context.supportsDynamicUi === false) {
+      return {
+        content:
+          "This channel cannot show the virtual desktop preview or Step In. Ask the user to continue in the Vellum app to complete this step. The obstacle remains unresolved.",
+        isError: true,
+      };
+    }
+
     // Channel turns (no dynamic UI) park only when the question can reach the
     // user as a guardian-request card with tappable options: a single-question
     // batch, asked by the guardian, on a channel whose notification adapter
@@ -277,13 +333,35 @@ export const askQuestionTool = {
       };
     }
 
+    let finishDesktopHelp: ((resume: boolean) => Promise<void>) | undefined;
+    if (desktopHelp) {
+      const { prepareDesktopHelp } =
+        await import("../../desktop/desktop-help.js");
+      const prepared = await prepareDesktopHelp(context);
+      if (typeof prepared !== "function") {
+        return prepared;
+      }
+      finishDesktopHelp = prepared;
+    }
+
     const prompter = new QuestionPrompter();
-    const result = await prompter.prompt({
-      conversationId: context.conversationId,
-      questions,
-      toolUseId: context.toolUseId,
-      signal: context.signal,
-    });
+    let result: QuestionPromptOutcome;
+    let resumeDesktop = false;
+    try {
+      result = await prompter.prompt({
+        conversationId: context.conversationId,
+        questions,
+        toolUseId: context.toolUseId,
+        signal: context.signal,
+      });
+      const answer = result.entries[0];
+      resumeDesktop =
+        result.overall === "completed" &&
+        (answer?.decision === "free_text" ||
+          (answer?.decision === "option" && answer.optionId === "done"));
+    } finally {
+      await finishDesktopHelp?.(resumeDesktop);
+    }
 
     // Format the aggregated transcript. Each line is keyed by the original
     // question text (not the daemon-assigned id) — the LLM never sees those
@@ -308,8 +386,26 @@ export const askQuestionTool = {
     const answeredQuestion = toAnsweredQuestion(result);
 
     switch (result.overall) {
-      case "completed":
-        return { content: lines.join("\n"), isError: false, answeredQuestion };
+      case "completed": {
+        let content = lines.join("\n");
+        if (desktopHelp) {
+          const entry = result.entries[0];
+          if (entry?.decision === "free_text") {
+            content +=
+              "\nTake a fresh browser snapshot before continuing; do not assume the obstacle was resolved.";
+          } else if (
+            entry?.decision === "option" &&
+            entry.optionId === "done"
+          ) {
+            content =
+              "The user finished interacting with the virtual desktop. Take a fresh browser snapshot and verify the result before continuing.";
+          } else {
+            content =
+              "The user skipped helping in the virtual desktop. The obstacle may still be present. Use another approach or explain what remains blocked.";
+          }
+        }
+        return { content, isError: false, answeredQuestion };
+      }
       case "closed": {
         const summary =
           "User closed the question card without answering. All questions skipped.";

package/src/tools/browser/browser-execution.ts

@@ -4,6 +4,10 @@ import { getConfig } from "../../config/loader.js";
 import { HostBrowserProxy } from "../../daemon/host-browser-proxy.js";
 import type { ImageContent } from "../../providers/types.js";
 import { wrapUntrustedContent } from "../../security/untrusted-content.js";
+import {
+  DESKTOP_HELP_GUIDANCE,
+  HUMAN_VERIFICATION_GUIDANCE,
+} from "../../util/browser-human-verification.js";
 import { getLogger } from "../../util/logger.js";
 import { truncate } from "../../util/truncate.js";
 import { safeStringSlice } from "../../util/unicode.js";
@@ -1319,7 +1323,9 @@ export async function executeBrowserNavigate(
               "⚠️ CAPTCHA/Cloudflare verification detected on this page.",
             );
             lines.push(
-              "This challenge requires human verification. Surface this clearly: the page cannot be accessed until the verification is solved manually.",
+              context.cdpClient
+                ? DESKTOP_HELP_GUIDANCE
+                : HUMAN_VERIFICATION_GUIDANCE,
             );
             if (cdp.kind === "local") {
               lines.push("");

package/src/tools/host-terminal/host-shell.ts

@@ -23,8 +23,10 @@ import { conversationRevealNonce } from "../../runtime/reveal-nonce.js";
 import { redactSecrets } from "../../security/secret-scanner.js";
 import {
   buildShellInvocation,
+  buildShellSpawnFlags,
   prependUniquePathEntries,
   terminateProcessTree,
+  watchShellProcessStart,
 } from "../../util/host-process.js";
 import { getLogger } from "../../util/logger.js";
 import type { CompletedBackgroundTool } from "../background-tool-registry.js";
@@ -455,9 +457,9 @@ export const hostShellTool = {
         cwd: workingDir,
         env: hostEnv,
         stdio: ["ignore", "pipe", "pipe"],
-        detached: true,
-        windowsHide: true,
+        ...buildShellSpawnFlags(),
       });
+      const launch = watchShellProcessStart(child);
 
       const collector = attachBoundedStdio(child);
       let timedOut = false;
@@ -483,7 +485,9 @@ export const hostShellTool = {
         }
         completed = true;
         clearTimeout(timer);
-        const result = collector.format(code, timedOut, timeoutSec);
+        const result = collector.format(code, timedOut, timeoutSec, {
+          started: launch.didStart(),
+        });
         // Cancel takes precedence over the SIGKILL-induced error result.
         const status = aborted
           ? "cancelled"
@@ -629,9 +633,9 @@ export const hostShellTool = {
         cwd: workingDir,
         env: hostEnv,
         stdio: ["ignore", "pipe", "pipe"],
-        detached: true,
-        windowsHide: true,
+        ...buildShellSpawnFlags(),
       });
+      const launch = watchShellProcessStart(child);
       const collector = attachBoundedStdio(child, {
         onOutput: context.onOutput,
       });
@@ -657,7 +661,9 @@ export const hostShellTool = {
         clearTimeout(timer);
         context.signal?.removeEventListener("abort", onAbort);
 
-        const result = collector.format(code, timedOut, timeoutSec);
+        const result = collector.format(code, timedOut, timeoutSec, {
+          started: launch.didStart(),
+        });
 
         resolve({
           content: result.content,

package/src/tools/shared/filesystem/file-ops-service.ts

@@ -4,6 +4,7 @@ import { dirname, join } from "node:path";
 import { minimatch } from "minimatch";
 
 import { ensureDir, pathExists } from "../../../util/fs.js";
+import { surrogateSafeWindow } from "../../../util/unicode.js";
 import { isAbortLikeError } from "../abort.js";
 import { applyEdit } from "./edit-engine.js";
 import * as Err from "./errors.js";
@@ -102,37 +103,6 @@ function truncationNotice(
   return `\n\n[Truncated: characters ${start}-${end} of ${totalChars}. Read on with start_index=${end}.]`;
 }
 
-const isHighSurrogate = (code: number): boolean =>
-  code >= 0xd800 && code <= 0xdbff;
-const isLowSurrogate = (code: number): boolean =>
-  code >= 0xdc00 && code <= 0xdfff;
-
-/**
- * Character window that never splits a surrogate pair. 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.
- */
-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 };
-}
-
 export class FileSystemOps {
   private policy: PathPolicy;
   private sizeLimit: number | undefined;

package/src/tools/shared/shell-output.test.ts

@@ -7,6 +7,7 @@ import {
   formatShellOutput,
   MAX_OUTPUT_LENGTH,
   OUTPUT_TRUNCATED_TAG,
+  SHELL_DID_NOT_START_MESSAGE,
 } from "./shell-output.js";
 
 describe("BoundedStdioCollector", () => {
@@ -85,6 +86,15 @@ describe("attachBoundedStdio", () => {
   });
 });
 
+describe("formatShellOutput launch start", () => {
+  test("does not report command_completed when the process never started", () => {
+    const result = formatShellOutput("", "", 0, false, 120, { started: false });
+    expect(result.isError).toBe(true);
+    expect(result.content).toBe(SHELL_DID_NOT_START_MESSAGE);
+    expect(result.content).not.toContain("<command_completed />");
+  });
+});
+
 describe("formatShellOutput truncation", () => {
   test("truncates an already-materialized oversized string without a file path", () => {
     const longOutput = "x".repeat(30_000);

package/src/tools/shared/shell-output.ts

@@ -4,6 +4,9 @@ export const MAX_OUTPUT_LENGTH = 20_000;
 
 export const OUTPUT_TRUNCATED_TAG = `<output_truncated limit="20K" />`;
 
+export const SHELL_DID_NOT_START_MESSAGE =
+  "Error: the shell command did not start. No process was created, so the command did not run.";
+
 export interface ShellOutputResult {
   content: string;
   status: string | undefined;
@@ -31,8 +34,16 @@ export function formatShellOutput(
   code: number | null,
   timedOut: boolean,
   timeoutSec: number,
-  options?: { truncated?: boolean },
+  options?: { truncated?: boolean; started?: boolean },
 ): ShellOutputResult {
+  if (options?.started === false) {
+    return {
+      content: SHELL_DID_NOT_START_MESSAGE,
+      status: undefined,
+      isError: true,
+    };
+  }
+
   let output = stdout;
   if (stderr) {
     output += (output ? "\n" : "") + stderr;
@@ -137,6 +148,7 @@ export class BoundedStdioCollector {
     code: number | null,
     timedOut: boolean,
     timeoutSec: number,
+    options?: { started?: boolean },
   ): ShellOutputResult {
     return formatShellOutput(
       Buffer.concat(this.stdoutParts).toString(),
@@ -144,7 +156,7 @@ export class BoundedStdioCollector {
       code,
       timedOut,
       timeoutSec,
-      { truncated: this.truncated },
+      { truncated: this.truncated, started: options?.started },
     );
   }
 }

package/src/tools/skills/sandbox-runner.ts

@@ -7,9 +7,12 @@ import { conversationRevealNonce } from "../../runtime/reveal-nonce.js";
 import { computeSkillVersionHash } from "../../skills/version-hash.js";
 import {
   buildShellInvocation,
+  buildShellSpawnFlags,
   terminateProcessTree,
+  watchShellProcessStart,
 } from "../../util/host-process.js";
 import { safeStringSlice } from "../../util/unicode.js";
+import { SHELL_DID_NOT_START_MESSAGE } from "../shared/shell-output.js";
 import { buildSanitizedEnv } from "../terminal/safe-env.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
@@ -160,9 +163,9 @@ function spawnRunner(
       cwd: runDir,
       env,
       stdio: ["ignore", "pipe", "pipe"],
-      detached: true,
-      windowsHide: true,
+      ...buildShellSpawnFlags(),
     });
+    const launch = watchShellProcessStart(child);
 
     const timer = setTimeout(() => {
       timedOut = true;
@@ -188,6 +191,14 @@ function spawnRunner(
       clearTimeout(timer);
       context.signal?.removeEventListener("abort", onAbort);
 
+      if (!launch.didStart()) {
+        resolve({
+          content: `Failed to spawn skill tool script "${executorPath}": ${SHELL_DID_NOT_START_MESSAGE}`,
+          isError: true,
+        });
+        return;
+      }
+
       if (timedOut) {
         resolve({
           content: `Skill tool script "${executorPath}" timed out after ${timeoutMs}ms`,

package/src/tools/skills/scaffold-managed.ts

@@ -134,7 +134,8 @@ function notifyBackgroundSkillUpdate(args: {
     sourceEventName: "activity.complete",
     dedupeKey: `skill-updated:${args.skillId}:${day}`,
     contextPayload: {
-      // `summary` feeds the copy composer; `title`/`body` are the home feed's
+      // `summary` feeds the copy composer and `title` is the headline both
+      // it and the home feed keep; `title`/`body` are also the feed's
       // fallback when no channel copy was rendered. Without them a fully
       // suppressed delivery (the intended shape for this signal: low urgency,
       // background, no interruption) leaves the feed writer with no summary