@vellumai/assistant 0.12.2 → 0.12.3-staging.1

package/src/daemon/daemon-control.ts

@@ -43,7 +43,7 @@ function isPositiveInteger(v: unknown): v is number {
 
 /**
  * Read daemon timeout values directly from the config JSON file, bypassing
- * loadConfig() and its ensureMigratedDataDir()/ensureDataDir() side effects.
+ * loadConfig() and its ensureDataDir() side effects.
  * Falls back to hardcoded defaults on any error (missing file, malformed JSON,
  * unexpected shape) so daemon stop/start never fails due to config issues.
  */
@@ -258,15 +258,11 @@ async function getDaemonStatus(): Promise<{
   return { running: true, pid };
 }
 
-function getStartupLockPath(): string {
-  return getDaemonStartupLockPath();
-}
-
 /** Attempt to acquire a startup lock. Returns true on success. Stale locks
  *  (older than STARTUP_LOCK_STALE_MS) are forcibly removed to prevent
  *  permanent deadlocks from a crashed caller. */
 function acquireStartupLock(): boolean {
-  const lockPath = getStartupLockPath();
+  const lockPath = getDaemonStartupLockPath();
   try {
     // Ensure the root directory exists before attempting the lock file write.
     // On a first-time run, getRootDir() may not exist yet, and writeFileSync
@@ -293,7 +289,7 @@ function acquireStartupLock(): boolean {
 
 function releaseStartupLock(): void {
   try {
-    unlinkSync(getStartupLockPath());
+    unlinkSync(getDaemonStartupLockPath());
   } catch {
     /* already removed */
   }

package/src/daemon/lifecycle.ts

@@ -673,11 +673,11 @@ export async function runDaemon(): Promise<void> {
   // blocked.
   startConsentRefresh();
 
-  // Bring up the daemon's CES connection (process + handshake + reconnect
+  // Bring up the assistant's CES connection (process + handshake + reconnect
   // wiring). Blocks up to a 20s timeout so credential reads route through CES
-  // before provider init; non-fatal — falls back to the direct credential store
-  // on failure. The sidecar accepts exactly one bootstrap connection, so this
-  // happens at the process level.
+  // before provider init; non-fatal, falls back to the direct credential store
+  // on failure. CES serves a multi-connection bootstrap socket, so this
+  // happens at the process level and child processes can connect independently.
   await startCes(config);
 
   // Bring up the plugin layer: install the runtime bridge, register the

package/src/daemon/mcp-reload-service.ts

@@ -116,7 +116,7 @@ async function doReload(): Promise<McpReloadResult> {
     const servers: McpReloadServerResult[] = [];
 
     if (serverIds.length > 0) {
-      const serverToolInfos = await manager.start(mcpConfig);
+      const { servers: serverToolInfos } = await manager.start(mcpConfig);
       for (const { serverId, serverConfig, tools } of serverToolInfos) {
         const mcpTools = createMcpToolsFromServer(
           tools,

package/src/daemon/message-types/shared.ts

@@ -39,6 +39,7 @@ export interface UserMessageAttachment {
   data: string;
   /** Origin of the attachment on the daemon side, when known. */
   sourceType?: "sandbox_file" | "host_file" | "tool_block";
+  computerUseScreenshot?: boolean;
   extractedText?: string;
   /** Original file size in bytes. Present when data was omitted from history_response to reduce payload size. */
   sizeBytes?: number;

package/src/daemon/orphan-reaper.ts

@@ -1,9 +1,10 @@
 /**
  * Periodic reaper for orphaned subprocesses that reparent to the daemon.
  *
- * Tools run commands in their own process group (`detached: true`) and, on
- * timeout/abort, group-kill with `process.kill(-pgid, SIGKILL)` (the bash and
- * host_bash tools, and the skill sandbox runner). The
+ * POSIX tools run commands in their own process group (`detached: true`) and,
+ * on timeout/abort, group-kill with `process.kill(-pgid, SIGKILL)` (the bash
+ * and host_bash tools, and the skill sandbox runner). Windows piped shell
+ * children stay attached and are torn down with `taskkill /T`. The
  * immediate child is reaped by Bun/libuv, but its descendants — e.g. git's
  * transport helpers or a skill runner's `bun` process — were never spawned by
  * the daemon, so when the group dies they reparent to PID 1. When the daemon

package/src/daemon/persist-media-references.ts

@@ -29,6 +29,7 @@ import type {
   WorkspaceRefMediaSource,
 } from "../providers/types.js";
 import { getLogger } from "../util/logger.js";
+import { toolImageFilename } from "./assistant-attachments.js";
 
 const log = getLogger("persist-media-references");
 
@@ -62,6 +63,7 @@ async function referenceMediaBlock(
   messageId: string,
   block: ImageContent | FileContent,
   position: number,
+  imageFilenameOverride?: string,
 ): Promise<ContentBlock | null> {
   if (block.source.type !== "base64") {
     return block;
@@ -69,7 +71,9 @@ async function referenceMediaBlock(
   const { data, media_type } = block.source;
   const filename =
     block.source.filename ??
-    (block.type === "image" ? imageFilename(media_type) : "attachment");
+    (block.type === "image"
+      ? (imageFilenameOverride ?? imageFilename(media_type))
+      : "attachment");
 
   let stored: { id: string; sizeBytes: number };
   try {
@@ -127,11 +131,15 @@ export async function referenceMediaBlocksForPersist(
   conversationCreatedAt: number,
   messageId: string,
   blocks: ContentBlock[],
+  computerUseToolNames?: ReadonlyMap<string, string>,
 ): Promise<ContentBlock[]> {
   // A single link position counter across all attachments in the message so
   // their `message_attachments` rows keep content order.
   let position = 0;
-  const convert = async (block: ContentBlock): Promise<ContentBlock> => {
+  const convert = async (
+    block: ContentBlock,
+    imageFilenameOverride?: string,
+  ): Promise<ContentBlock> => {
     if (block.type === "image" || block.type === "file") {
       if (block.source.type !== "base64") {
         return block;
@@ -143,13 +151,22 @@ export async function referenceMediaBlocksForPersist(
           messageId,
           block,
           position++,
+          imageFilenameOverride,
         )) ?? block
       );
     }
     if (block.type === "tool_result" && block.contentBlocks?.length) {
       const contentBlocks: ContentBlock[] = [];
+      const computerUseToolName = computerUseToolNames?.get(block.tool_use_id);
       for (const cb of block.contentBlocks) {
-        contentBlocks.push(await convert(cb));
+        contentBlocks.push(
+          await convert(
+            cb,
+            cb.type === "image" && computerUseToolName
+              ? toolImageFilename(cb.source.media_type, computerUseToolName)
+              : undefined,
+          ),
+        );
       }
       return { ...block, contentBlocks };
     }

package/src/daemon/tool-setup-types.ts

@@ -59,6 +59,12 @@ export interface SubagentToolStats {
  * parity for desktop/web sources; channel-routed sources resolve every tool
  * gate identically under `hasNoClient: true` with or without them.)
  *
+ * A wake that also carries its source's recorded wire array
+ * (`Conversation.wireToolReplay`, set by `scopeWakeAllowedTools`) sends that
+ * array verbatim, so the pin then shapes only the execution-side inventory
+ * (`allowedToolNames`); the pin alone carries wire parity for a source with
+ * no recorded surface.
+ *
  * Tool-definition resolution ONLY. The executor callback and host-proxy
  * attachment paths never read the pin, so it cannot make a host tool
  * runnable: in execution gate mode every non-allowlisted call is rejected

package/src/daemon/wake-conversation-ops.ts

@@ -22,7 +22,7 @@ import {
 import { syncMessageToDisk } from "../persistence/conversation-disk-view.js";
 import { backfillMessageIdOnLogs } from "../persistence/llm-request-log-store.js";
 import { resolveMediaSourceData } from "../providers/media-resolve.js";
-import type { Message } from "../providers/types.js";
+import type { Message, ToolDefinition } from "../providers/types.js";
 import { broadcastMessage } from "../runtime/assistant-event-hub.js";
 import { publishConversationMessagesChanged } from "../runtime/sync/resource-sync-events.js";
 import type { CompletedBackgroundTool } from "../tools/background-tool-registry.js";
@@ -350,38 +350,70 @@ export async function persistWakeTriggerMessage(
   }
 }
 
+/**
+ * How a wake's tool allowlist is applied beyond the allowlist itself. Every
+ * field is set on the conversation together with the allowlist and restored
+ * with it.
+ */
+export interface WakeToolScopeOptions {
+  /** How the allowlist is enforced; see {@link SubagentToolGateMode}. */
+  gateMode?: SubagentToolGateMode;
+  /**
+   * Freezes the client-context inputs for tool-definition resolution
+   * (execution-gate-mode cache-parity wakes); see {@link WakeToolContextPin}.
+   * Its `requestOrigin`, when set, is stamped onto the conversation's per-turn
+   * origin so the permission checker's origin-scoped auto-grants fire.
+   */
+  toolContextPin?: WakeToolContextPin;
+  /**
+   * Skills whose bundled tools join the turn's active set
+   * (`allowedToolNames`) so they are callable without a prior `skill_load`.
+   */
+  preactivateSkillIds?: readonly string[];
+  /**
+   * Sent verbatim as the wake's wire tool array in place of the resolved one
+   * (the source conversation's recorded surface, replayed for provider
+   * prompt-cache parity). Changes nothing about what may execute.
+   */
+  wireToolDefinitions?: readonly ToolDefinition[];
+  /**
+   * The delegation section's rendered state recorded with the source's
+   * surface, replayed into the wake's system prompt alongside
+   * `wireToolDefinitions`. Changes nothing about what may execute.
+   */
+  delegateIndependentTasks?: boolean;
+}
+
 /**
  * Temporarily restrict the tools visible/executable during a wake by
  * reusing the conversation's subagent allowlist slot. Returns a restore
  * callback that reinstates the previous allowlist so the wake can release
  * the scope before any queued user turn is drained.
- *
- * `gateMode` controls how the allowlist is enforced — see
- * {@link SubagentToolGateMode}. `toolContextPin`, when provided
- * (execution-gate-mode cache-parity wakes), freezes the client-context
- * inputs for tool-definition resolution — see {@link WakeToolContextPin}.
- * Its `requestOrigin`, when set, is stamped onto the conversation's per-turn
- * origin so the permission checker's origin-scoped auto-grants fire for the
- * wake. `preactivateSkillIds`, when non-empty, activates those skills' bundled
- * tools in the turn's active set (`allowedToolNames`) for the wake so they are
- * callable without a prior `skill_load`. All are set and restored alongside the
- * allowlist.
  */
 export function scopeWakeAllowedTools(
   conversation: Conversation,
   tools: ReadonlySet<string>,
-  gateMode: SubagentToolGateMode = "wire",
-  toolContextPin?: WakeToolContextPin,
-  preactivateSkillIds?: readonly string[],
+  {
+    gateMode = "wire",
+    toolContextPin,
+    preactivateSkillIds,
+    wireToolDefinitions,
+    delegateIndependentTasks,
+  }: WakeToolScopeOptions = {},
 ): () => void {
   const previous = conversation.subagentAllowedTools;
   const previousGateMode = conversation.subagentToolGateMode;
   const previousToolContextPin = conversation.toolContextPin;
   const previousRequestOrigin = conversation.currentTurnRequestOrigin;
   const previousPreactivated = conversation.preactivatedSkillIds;
+  const previousWireToolReplay = conversation.wireToolReplay;
+  const previousDelegateIndependentTasksReplay =
+    conversation.delegateIndependentTasksReplay;
   conversation.setSubagentAllowedTools(new Set(tools));
   conversation.subagentToolGateMode = gateMode;
   conversation.toolContextPin = toolContextPin;
+  conversation.wireToolReplay = wireToolDefinitions;
+  conversation.delegateIndependentTasksReplay = delegateIndependentTasks;
   if (toolContextPin?.requestOrigin !== undefined) {
     conversation.currentTurnRequestOrigin = toolContextPin.requestOrigin;
   }
@@ -394,5 +426,8 @@ export function scopeWakeAllowedTools(
     conversation.toolContextPin = previousToolContextPin;
     conversation.currentTurnRequestOrigin = previousRequestOrigin;
     conversation.setPreactivatedSkillIds(previousPreactivated);
+    conversation.wireToolReplay = previousWireToolReplay;
+    conversation.delegateIndependentTasksReplay =
+      previousDelegateIndependentTasksReplay;
   };
 }

package/src/desktop/desktop-automation-lease.test.ts

@@ -35,7 +35,9 @@ function fixture() {
   const started = mock(async () => {});
   const released = mock(() => {});
   const releaseBrowser = mock(async () => {});
+  const notify = mock(async () => {});
   const lease = new DesktopAutomationLease({
+    notify,
     enabled: () => enabled,
     ready: () => ready,
     ensureReady,
@@ -50,6 +52,7 @@ function fixture() {
   cleanups.push(lease);
   return {
     lease,
+    notify,
     ensureReady,
     install,
     failSetup: () => setup.reject(new Error("download failed")),
@@ -128,6 +131,7 @@ test("cancellation stops running and queued browser commands without blocking a
   const callback = mock(operation);
   const queued = f.lease.runBrowser(context, callback);
   abort.abort();
+  expect(f.lease.isActive).toBe(false);
   expect(await running).toBeInstanceOf(Error);
   expect((await queued).isError).toBe(true);
   expect(callback).not.toHaveBeenCalled();
@@ -206,3 +210,229 @@ test("disabled, unidentified, cancelled and released browser calls cannot instal
   await expect(f.lease.runBrowser(context, operation)).rejects.toThrow();
   expect(f.ensureReady).not.toHaveBeenCalled();
 });
+
+test("activity follows the browser lease and clears before failed cleanup", async () => {
+  const f = fixture();
+  expect(f.lease.isActive).toBe(false);
+  await f.lease.runBrowser(context, operation);
+  expect(f.lease.isActive).toBe(true);
+  expect(f.notify).toHaveBeenCalledTimes(1);
+  await f.lease.runBrowser(context, operation);
+  expect(f.notify).toHaveBeenCalledTimes(1);
+  f.releaseBrowser.mockRejectedValueOnce(new Error("cleanup failed"));
+  await expect(f.lease.runBrowser(context, operation, true)).rejects.toThrow(
+    "cleanup failed",
+  );
+  expect(f.lease.isActive).toBe(false);
+  expect(f.notify).toHaveBeenCalledTimes(2);
+  await f.lease.runBrowser(context, operation, true);
+  expect(f.notify).toHaveBeenCalledTimes(2);
+});
+
+test("turn completion releases only its own desktop before cleanup finishes", async () => {
+  const f = fixture();
+  await f.lease.runBrowser(context, operation);
+  f.lease.releaseForConversation("conv-456");
+  expect(f.lease.isActive).toBe(true);
+  expect(f.notify).toHaveBeenCalledTimes(1);
+
+  const cleanup = Promise.withResolvers<void>();
+  f.releaseBrowser.mockImplementationOnce(() => cleanup.promise);
+  f.lease.releaseForConversation(context.conversationId);
+  expect(f.lease.isActive).toBe(false);
+  expect(f.notify).toHaveBeenCalledTimes(2);
+  await Bun.sleep(0);
+  expect(f.released).not.toHaveBeenCalled();
+
+  const callback = mock(operation);
+  const next = f.lease.runBrowser(context, callback);
+  await Bun.sleep(0);
+  expect(callback).not.toHaveBeenCalled();
+  cleanup.resolve();
+  expect((await next).isError).toBe(false);
+  expect(f.released).toHaveBeenCalledTimes(1);
+  expect(f.started).toHaveBeenCalledTimes(2);
+  expect(f.lease.isActive).toBe(true);
+});
+
+test("turn completion cancels running and queued desktop work", async () => {
+  const f = fixture();
+  const started = Promise.withResolvers<void>();
+  const running = f.lease
+    .runBrowser(context, async (signal) => {
+      started.resolve();
+      await new Promise<void>((_resolve, reject) => {
+        signal.addEventListener("abort", () => reject(new Error("aborted")), {
+          once: true,
+        });
+      });
+      return operation();
+    })
+    .catch((error: unknown) => error);
+  await started.promise;
+  const callback = mock(operation);
+  const queued = f.lease.runBrowser(context, callback);
+  f.lease.releaseForConversation(context.conversationId);
+  expect(f.lease.isActive).toBe(false);
+  expect(await running).toBeInstanceOf(Error);
+  expect((await queued).isError).toBe(true);
+  expect(callback).not.toHaveBeenCalled();
+  await f.lease.runBrowser(context, callback);
+  expect(callback).toHaveBeenCalledTimes(1);
+});
+
+test("turn handoff retries failed cleanup without another turn or restart", async () => {
+  const f = fixture();
+  await f.lease.runBrowser(context, operation);
+  f.releaseBrowser.mockRejectedValueOnce(new Error("Chrome cleanup timed out"));
+  f.lease.releaseForConversation(context.conversationId);
+  expect(f.lease.isActive).toBe(false);
+  await Bun.sleep(0);
+  expect(f.released).not.toHaveBeenCalled();
+  await Bun.sleep(1_100);
+  expect(f.released).toHaveBeenCalledTimes(1);
+  const nextContext = { ...context, conversationId: "conv-456" };
+  expect((await f.lease.runBrowser(nextContext, operation)).isError).toBe(
+    false,
+  );
+  await f.lease.runBrowser(nextContext, operation, true);
+});
+
+test("a delayed cleanup retry cannot release a replacement owner", async () => {
+  const f = fixture();
+  await f.lease.runBrowser(context, operation);
+  f.releaseBrowser.mockRejectedValueOnce(new Error("Chrome cleanup timed out"));
+  f.lease.releaseForConversation(context.conversationId);
+  await f.lease.runBrowser(context, operation, true);
+  const nextContext = { ...context, conversationId: "conv-456" };
+  await f.lease.runBrowser(nextContext, operation);
+  await Bun.sleep(1_100);
+  expect(f.lease.isActive).toBe(true);
+  expect(f.released).toHaveBeenCalledTimes(1);
+  await f.lease.runBrowser(nextContext, operation, true);
+});
+
+test("cleanup retries preserve commands queued behind an explicit handoff", async () => {
+  const f = fixture();
+  await f.lease.runBrowser(context, operation);
+  f.releaseBrowser.mockRejectedValueOnce(new Error("Chrome cleanup timed out"));
+  f.lease.releaseForConversation(context.conversationId);
+  await Bun.sleep(0);
+  const cleanup = Promise.withResolvers<void>();
+  f.releaseBrowser.mockImplementationOnce(() => cleanup.promise);
+  const detached = f.lease.runBrowser(context, operation, true);
+  await Bun.sleep(0);
+  const callback = mock(operation);
+  const next = f.lease.runBrowser(context, callback);
+  await Bun.sleep(1_100);
+  cleanup.resolve();
+  await detached;
+  expect((await next).isError).toBe(false);
+  expect(callback).toHaveBeenCalledTimes(1);
+  expect(f.lease.isActive).toBe(true);
+});
+
+test("turn completion cancels commands queued behind an in-progress detach", async () => {
+  const f = fixture();
+  await f.lease.runBrowser(context, operation);
+  const cleanup = Promise.withResolvers<void>();
+  f.releaseBrowser.mockImplementationOnce(() => cleanup.promise);
+  const detached = f.lease.runBrowser(context, operation, true);
+  await Bun.sleep(0);
+  const callback = mock(operation);
+  const queued = f.lease.runBrowser(context, callback);
+  f.lease.releaseForConversation(context.conversationId);
+  cleanup.resolve();
+  await detached;
+  expect((await queued).isError).toBe(true);
+  expect(callback).not.toHaveBeenCalled();
+  await f.lease.runBrowser(context, callback);
+  expect(callback).toHaveBeenCalledTimes(1);
+});
+
+test("human help releases held input while reserving the desktop, then resumes its owner", async () => {
+  const f = fixture();
+  await f.lease.runBrowser(context, operation);
+  const finish = await f.lease.reserveForHuman(context);
+  expect(f.releaseBrowser).toHaveBeenCalledTimes(2);
+  expect(f.released).not.toHaveBeenCalled();
+  expect(f.lease.isActive).toBe(false);
+  const callback = mock(operation);
+  await expect(f.lease.runBrowser(context, callback)).rejects.toThrow(
+    "reserved",
+  );
+  await expect(f.lease.runBrowser(context, callback, true)).rejects.toThrow(
+    "reserved",
+  );
+  const other = { ...context, conversationId: "conv-456" };
+  await expect(f.lease.runBrowser(other, callback)).rejects.toThrow(
+    "Another conversation",
+  );
+  expect(callback).not.toHaveBeenCalled();
+  await finish(true);
+  expect(f.lease.isActive).toBe(true);
+  await expect(f.lease.runBrowser(other, callback)).rejects.toThrow(
+    "Another conversation",
+  );
+  await f.lease.runBrowser(context, callback);
+  expect(callback).toHaveBeenCalledTimes(1);
+  expect(f.started).toHaveBeenCalledTimes(1);
+});
+
+test("closing human help releases its reservation and stale cleanup preserves the next owner", async () => {
+  const f = fixture();
+  const finish = await f.lease.reserveForHuman(context);
+  await finish(false);
+  expect(f.released).toHaveBeenCalledTimes(1);
+  const other = { ...context, conversationId: "conv-456" };
+  await f.lease.runBrowser(other, operation);
+  await finish(false);
+  expect(f.lease.isActive).toBe(true);
+  expect(f.released).toHaveBeenCalledTimes(1);
+  await f.lease.runBrowser(other, operation, true);
+});
+
+test("aborting human help releases its reservation", async () => {
+  const f = fixture();
+  const abort = new AbortController();
+  const finish = await f.lease.reserveForHuman({
+    ...context,
+    signal: abort.signal,
+  });
+  abort.abort();
+  await finish(true);
+  expect(f.lease.isActive).toBe(false);
+  expect(f.released).toHaveBeenCalledTimes(1);
+  await f.lease.runBrowser(context, operation);
+  expect(f.started).toHaveBeenCalledTimes(2);
+});
+
+test("the browser idle timeout cannot steal a pending human-help reservation", async () => {
+  const f = fixture();
+  const finish = await f.lease.reserveForHuman(context);
+  const now = Date.now;
+  const future = now() + 10 * 60_000;
+  Date.now = () => future;
+  try {
+    await Bun.sleep(1_100);
+    expect(f.released).not.toHaveBeenCalled();
+    await expect(
+      f.lease.runBrowser({ ...context, conversationId: "conv-456" }, operation),
+    ).rejects.toThrow("Another conversation");
+  } finally {
+    Date.now = now;
+    await finish(false);
+  }
+  expect(f.released).toHaveBeenCalledTimes(1);
+});
+
+test("ending human help retries failed input cleanup without another turn", async () => {
+  const f = fixture();
+  const finish = await f.lease.reserveForHuman(context);
+  f.releaseBrowser.mockRejectedValueOnce(new Error("cleanup failed"));
+  await expect(finish(false)).rejects.toThrow("cleanup failed");
+  await Bun.sleep(0);
+  expect(f.released).toHaveBeenCalledTimes(1);
+  await f.lease.runBrowser(context, operation);
+  expect(f.lease.isActive).toBe(true);
+});

package/src/desktop/desktop-automation-lease.ts

@@ -1,4 +1,4 @@
-import { getConfig } from "../config/loader.js";
+import { broadcastMessage } from "../runtime/assistant-event-hub.js";
 import type { ToolContext, ToolExecutionResult } from "../tools/types.js";
 import { getLogger } from "../util/logger.js";
 import { desktopDependencyInstaller } from "./desktop-dependencies.js";
@@ -21,6 +21,7 @@ type Owner = {
   actions: number;
   lastActivity: number;
   desktopLost: boolean;
+  humanHelp?: symbol;
 };
 
 export class DesktopAutomationLease {
@@ -35,14 +36,33 @@ export class DesktopAutomationLease {
       ready: () => boolean;
       ensureReady: (signal: AbortSignal) => Promise<void>;
       manager: () => DesktopSessionManager;
+      notify: () => Promise<unknown>;
     } = {
-      enabled: () => isVirtualDesktopEnabled(getConfig()),
+      enabled: isVirtualDesktopEnabled,
       ready: () => desktopDependencyInstaller.getStatus().state === "ready",
       ensureReady: (signal) => desktopDependencyInstaller.ensureReady(signal),
       manager: getDesktopSessionManager,
+      notify: async () =>
+        broadcastMessage({ type: "desktop_activity_changed" }),
     },
   ) {}
 
+  get isActive(): boolean {
+    return (
+      this.owner !== null &&
+      !this.owner.humanHelp &&
+      !this.owner.abort.signal.aborted
+    );
+  }
+
+  private notify(): void {
+    void this.deps
+      .notify()
+      .catch((err) =>
+        log.warn({ err }, "Desktop browser activity notification failed"),
+      );
+  }
+
   private exclusive<T>(run: () => Promise<T>): Promise<T> {
     const next = this.tail.then(run, run);
     this.tail = next.catch(() => {});
@@ -84,9 +104,25 @@ export class DesktopAutomationLease {
     }
     this.generation += 1;
     owner.abort.abort();
-    void this.exclusive(() => this.release()).catch((err) =>
-      log.warn({ err }, "Desktop browser session cleanup failed"),
-    );
+    this.releaseCancelledOwner(owner);
+  }
+
+  private releaseCancelledOwner(owner: Owner): void {
+    void this.exclusive(async () => {
+      if (this.owner === owner) {
+        await this.release();
+      }
+    }).catch((err) => {
+      log.warn({ err }, "Desktop browser session cleanup failed");
+      const retry = setTimeout(() => this.releaseCancelledOwner(owner), 1_000);
+      retry.unref?.();
+    });
+  }
+
+  releaseForConversation(conversationId: string): void {
+    if (this.owner?.conversationId === conversationId) {
+      this.cancel(this.owner);
+    }
   }
 
   private bindCancellation(owner: Owner, signal?: AbortSignal): void {
@@ -122,12 +158,17 @@ export class DesktopAutomationLease {
       throw new Error("The desktop is busy or shutting down");
     }
     this.owner = owner;
+    owner.abort.signal.addEventListener("abort", () => this.notify(), {
+      once: true,
+    });
+    this.notify();
     this.bindCancellation(owner, context.signal);
     const cancel = () => this.cancel(owner);
     this.watchdog = setInterval(() => {
       try {
         if (
-          Date.now() - owner.lastActivity > IDLE_TIMEOUT_MS ||
+          (!owner.humanHelp &&
+            Date.now() - owner.lastActivity > IDLE_TIMEOUT_MS) ||
           !this.deps.enabled() ||
           !this.deps.ready()
         ) {
@@ -156,6 +197,44 @@ export class DesktopAutomationLease {
     }
   }
 
+  async reserveForHuman(
+    context: ToolContext,
+  ): Promise<(resume: boolean) => Promise<void>> {
+    let reservedOwner: Owner | undefined;
+    const reservation = Symbol("human-help");
+    const result = await this.runBrowser(context, async () => {
+      await this.deps.manager().browser.release();
+      reservedOwner = this.owner!;
+      reservedOwner.humanHelp = reservation;
+      this.notify();
+      return { content: "", isError: false };
+    });
+    if (result.isError || !reservedOwner) {
+      throw new Error(
+        "Desktop help was interrupted before control could be handed over.",
+      );
+    }
+    const owner = reservedOwner;
+    return (resume) =>
+      this.exclusive(async () => {
+        if (this.owner !== owner || owner.humanHelp !== reservation) {
+          return;
+        }
+        if (resume && !owner.abort.signal.aborted) {
+          owner.humanHelp = undefined;
+          owner.lastActivity = Date.now();
+          this.notify();
+        } else {
+          try {
+            await this.release();
+          } catch (error) {
+            this.releaseCancelledOwner(owner);
+            throw error;
+          }
+        }
+      });
+  }
+
   runBrowser(
     context: ToolContext,
     operation: (signal: AbortSignal) => Promise<ToolExecutionResult>,
@@ -179,6 +258,11 @@ export class DesktopAutomationLease {
       ) {
         throw new Error("Another conversation is controlling the desktop");
       }
+      if (this.owner?.humanHelp) {
+        throw new Error(
+          "The desktop is reserved while the user is helping. Wait for Done or Skip.",
+        );
+      }
       if (done) {
         await this.release();
         return { content: "Desktop browser session released.", isError: false };