openmausbot 0.1.68 → 0.1.70

package/dist-server/prepare-cloudflared.js

@@ -173,9 +173,25 @@ async function releaseBytes(asset) {
   const cached = cacheDirectory ? join(cacheDirectory, asset.name) : "";
   if (cached && existsSync(cached)) return readFileSync(cached);
   const url = `https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}/${asset.name}`;
-  const response = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(12e4) });
-  if (!response.ok) throw new Error(`could not download ${asset.name}: HTTP ${response.status}`);
-  return Buffer.from(await response.arrayBuffer());
+  const retryableStatuses = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    let failure;
+    try {
+      const response = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(12e4) });
+      if (response.ok) return Buffer.from(await response.arrayBuffer());
+      await response.body?.cancel().catch(() => {
+      });
+      failure = new Error(`could not download ${asset.name}: HTTP ${response.status}`);
+      if (!retryableStatuses.has(response.status)) throw failure;
+    } catch (error) {
+      if (!(error instanceof TypeError) && !["TimeoutError", "AbortError"].includes(error?.name)) throw error;
+      failure = error;
+    }
+    if (attempt === 3) throw failure;
+    const delay = 1e3 * 2 ** (attempt - 1);
+    console.warn(`cloudflared download attempt ${attempt}/3 failed: ${failure.message}; retrying in ${delay}ms`);
+    await new Promise((resolve) => setTimeout(resolve, delay));
+  }
 }
 async function stageTarget(root, target) {
   const asset = CLOUDFLARED_ASSETS[target];
@@ -251,6 +267,7 @@ export {
   executableTarget,
   parsePrepareCloudflaredArgs,
   prepareCloudflared,
+  releaseBytes,
   sha256,
   targetForCurrentHost,
   targetsForHost,

package/dist-server/server/avatar-image.js

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import { normalizeImageGenerationUrl } from "../shared/image-generation.js";
+import { decodeGeneratedImage } from "./generated-image.js";
 export const AVATAR_DIRECTION_MAX_CHARS = 400;
 export const AVATAR_IMAGE_TIMEOUT_MS = 120_000;
 const MAX_UPSTREAM_RESPONSE_BYTES = 15 * 1024 * 1024;
@@ -6,8 +8,34 @@ export const avatarGenerationRequestSchema = z.object({
     prompt: z.string().trim().max(AVATAR_DIRECTION_MAX_CHARS).default(""),
 });
 const generatedImageResponseSchema = z.object({
-    data: z.array(z.object({ b64_json: z.string().min(1) })).min(1),
+    data: z.array(z.object({ b64_json: z.string().min(1).optional(), url: z.string().optional() })).min(1),
 });
+/** Public settings describe availability without returning provider secrets. */
+export function avatarImageStatus(cfg) {
+    const provider = cfg.imageGen?.provider ?? "openai";
+    const openaiConfigured = Boolean(cfg.imageGen?.key?.trim());
+    const xaiConfigured = Boolean(cfg.xai?.key?.trim());
+    const customKeyConfigured = Boolean(cfg.imageGen?.customApiKey?.trim());
+    const customModel = cfg.imageGen?.customModel?.trim() ?? "";
+    let customUrl = "";
+    try {
+        if (cfg.imageGen?.customUrl?.trim())
+            customUrl = normalizeImageGenerationUrl(cfg.imageGen.customUrl);
+    }
+    catch {
+        // A manually edited invalid URL must not become an outbound request.
+    }
+    return {
+        provider,
+        configured: provider === "openai" ? openaiConfigured : provider === "xai" ? xaiConfigured : Boolean(customUrl && customModel),
+        model: provider === "openai" ? "gpt-image-2" : provider === "xai" ? "grok-imagine-image-2.0" : customModel,
+        customUrl,
+        customModel,
+        openaiConfigured,
+        xaiConfigured,
+        customKeyConfigured,
+    };
+}
 /** Copy the mutable avatar fields before an asynchronous generation starts. */
 export function snapshotAvatarGenerationState(bot) {
     return { avatarUrl: bot.avatarUrl, avatarCrop: bot.avatarCrop };
@@ -53,7 +81,14 @@ async function boundedResponseText(response) {
     let received = 0;
     try {
         for (;;) {
-            const { done, value } = await reader.read();
+            let chunk;
+            try {
+                chunk = await reader.read();
+            }
+            catch {
+                throw Object.assign(new Error("Could not read the generated avatar response"), { status: 502 });
+            }
+            const { done, value } = chunk;
             if (done)
                 break;
             received += value.byteLength;
@@ -70,31 +105,45 @@ async function boundedResponseText(response) {
         reader.releaseLock();
     }
 }
-export async function generateAvatarImage(apiKey, bot, direction, fetchImpl = fetch, timeoutMs = AVATAR_IMAGE_TIMEOUT_MS) {
-    if (!apiKey.trim())
-        throw Object.assign(new Error("Add an OpenAI image API key first"), { status: 409 });
+export async function generateAvatarImage(cfg, bot, direction, fetchImpl = fetch, timeoutMs = AVATAR_IMAGE_TIMEOUT_MS) {
+    const settings = avatarImageStatus(cfg);
+    const { provider, model } = settings;
+    if (!settings.configured) {
+        const message = provider === "openai" ? "Add an OpenAI image API key first"
+            : provider === "xai" ? "Add an xAI API key first"
+                : "Set a valid custom image API URL and model first";
+        throw Object.assign(new Error(message), { status: 409 });
+    }
+    const apiKey = (provider === "openai" ? cfg.imageGen?.key
+        : provider === "xai" ? cfg.xai?.key : cfg.imageGen?.customApiKey)?.trim();
+    const providerName = provider === "openai" ? "OpenAI" : provider === "xai" ? "xAI" : "Custom";
+    const url = provider === "openai" ? "https://api.openai.com/v1/images/generations"
+        : provider === "xai" ? "https://api.x.ai/v1/images/generations"
+            : `${settings.customUrl}/images/generations`;
+    const headers = { "content-type": "application/json" };
+    if (apiKey)
+        headers.authorization = `Bearer ${apiKey}`;
+    const body = {
+        model,
+        prompt: avatarGenerationPrompt(bot, direction),
+        ...(provider === "openai" ? { size: "1024x1024", quality: "low", output_format: "webp" }
+            : provider === "xai" ? { response_format: "b64_json", aspect_ratio: "1:1" }
+                : { response_format: "b64_json", size: "1024x1024", n: 1 }),
+    };
     const timeoutSignal = AbortSignal.timeout(timeoutMs);
     let response;
     try {
-        response = await fetchImpl("https://api.openai.com/v1/images/generations", {
+        response = await fetchImpl(url, {
             method: "POST",
-            headers: {
-                authorization: `Bearer ${apiKey.trim()}`,
-                "content-type": "application/json",
-            },
-            body: JSON.stringify({
-                model: "gpt-image-2",
-                prompt: avatarGenerationPrompt(bot, direction),
-                size: "1024x1024",
-                quality: "low",
-                output_format: "webp",
-            }),
+            headers,
+            body: JSON.stringify(body),
+            redirect: "error",
             signal: timeoutSignal,
         });
     }
     catch (error) {
         const timedOut = timeoutSignal.aborted || (error instanceof Error && error.name === "TimeoutError");
-        throw Object.assign(new Error(timedOut ? "Avatar generation timed out" : "Could not reach OpenAI image generation"), { status: 502 });
+        throw Object.assign(new Error(timedOut ? "Avatar generation timed out" : `Could not reach ${providerName} image generation`), { status: 502 });
     }
     let text;
     try {
@@ -110,15 +159,9 @@ export async function generateAvatarImage(apiKey, bot, direction, fetchImpl = fe
         throw error;
     }
     if (!response.ok) {
-        let message = `OpenAI image generation failed (HTTP ${response.status})`;
-        try {
-            const parsed = z.object({ error: z.object({ message: z.string() }) }).safeParse(JSON.parse(text));
-            if (parsed.success)
-                message = parsed.data.error.message.slice(0, 500);
-        }
-        catch {
-            // Keep the bounded status-only message for malformed upstream errors.
-        }
+        // Upstream errors can repeat authorization headers, signed URLs, or other
+        // secrets. Return only the provider and HTTP status, never its raw body.
+        const message = `${providerName} image generation failed (HTTP ${response.status})`;
         throw Object.assign(new Error(message), { status: response.status === 401 ? 401 : 502 });
     }
     let parsedJson;
@@ -126,19 +169,28 @@ export async function generateAvatarImage(apiKey, bot, direction, fetchImpl = fe
         parsedJson = JSON.parse(text);
     }
     catch {
-        throw Object.assign(new Error("OpenAI returned an invalid image response"), { status: 502 });
+        throw Object.assign(new Error(`${providerName} returned an invalid image response`), { status: 502 });
     }
     const parsed = generatedImageResponseSchema.safeParse(parsedJson);
     if (!parsed.success) {
-        throw Object.assign(new Error("OpenAI returned no generated image"), { status: 502 });
+        throw Object.assign(new Error(`${providerName} returned no generated image`), { status: 502 });
     }
     const encoded = parsed.data.data[0].b64_json;
+    if (!encoded) {
+        // Do not fetch arbitrary URLs returned by a provider. Compatible gateways
+        // must support the requested inline base64 response format.
+        throw Object.assign(new Error(`${providerName} image generation must return base64 image data (b64_json)`), { status: 502 });
+    }
     if (!/^[A-Za-z0-9+/]+={0,2}$/.test(encoded) || encoded.length % 4 !== 0) {
-        throw Object.assign(new Error("OpenAI returned invalid image data"), { status: 502 });
+        throw Object.assign(new Error(`${providerName} returned invalid image data`), { status: 502 });
     }
-    const bytes = Buffer.from(encoded, "base64");
-    if (bytes.byteLength === 0) {
-        throw Object.assign(new Error("OpenAI returned an empty image"), { status: 502 });
+    try {
+        const image = decodeGeneratedImage(encoded);
+        if (image.mime === "image/gif")
+            throw new Error("unsupported avatar format");
+        return { bytes: image.bytes, mime: image.mime };
+    }
+    catch {
+        throw Object.assign(new Error(`${providerName} returned invalid or oversized image data; expected PNG, JPEG, or WebP`), { status: 502 });
     }
-    return { bytes, mime: "image/webp" };
 }

package/dist-server/server/bot-package.js

@@ -27,6 +27,52 @@ const key = requiredText(64).regex(/^[a-z0-9][a-z0-9_-]*$/, {
     message: "may only contain lowercase letters, numbers, - and _",
 });
 const MAX_DATE_MS = 8_640_000_000_000_000;
+const CLOCK_TIME = /^([01]\d|2[0-3]):[0-5]\d$/;
+const intervalWeekdays = z.array(z.number().int().min(0).max(6)).min(1).max(7).refine((weekdays) => new Set(weekdays).size === weekdays.length, "must contain unique weekdays");
+const intervalWindow = z.object({
+    start: z.string().regex(CLOCK_TIME, { message: "must use HH:MM" }),
+    end: z.string().regex(CLOCK_TIME, { message: "must use HH:MM" }),
+}).strict().refine(({ start, end }) => start < end, {
+    message: "must end later on the same day",
+});
+const packageRoutineScheduleSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("once"), at: z.number().int() }),
+    z.object({
+        type: z.literal("daily"),
+        time: requiredText(5).regex(CLOCK_TIME, { message: "must use HH:MM" }),
+        weekdays: z.array(z.number().int().min(0).max(6)).min(1).max(7),
+    }),
+    z.object({
+        type: z.literal("interval"),
+        everyMinutes: z.number().int().min(5).max(1_440),
+        anchorAt: z.number().int().nonnegative().max(MAX_DATE_MS),
+        weekdays: intervalWeekdays.optional(),
+        window: intervalWindow.optional(),
+        endsAt: z.number().int().nonnegative().max(MAX_DATE_MS).optional(),
+    }),
+]).superRefine((schedule, context) => {
+    if (schedule.type !== "interval")
+        return;
+    if (schedule.window) {
+        const [startHour, startMinute] = schedule.window.start.split(":").map(Number);
+        const [endHour, endMinute] = schedule.window.end.split(":").map(Number);
+        const windowMinutes = endHour * 60 + endMinute - (startHour * 60 + startMinute);
+        if (windowMinutes < schedule.everyMinutes) {
+            context.addIssue({
+                code: "custom",
+                message: "must be at least as long as the interval cadence",
+                path: ["window"],
+            });
+        }
+    }
+    if (schedule.endsAt !== undefined && schedule.endsAt < schedule.anchorAt) {
+        context.addIssue({
+            code: "custom",
+            message: "must not be before the interval anchor",
+            path: ["endsAt"],
+        });
+    }
+});
 const packageSchema = z.object({
     format: z.literal(BOT_PACKAGE_FORMAT, { error: "This is not an OpenMaus package" }),
     version: z.literal(BOT_PACKAGE_VERSION, { error: "Package version is not supported" }),
@@ -86,19 +132,7 @@ const packageSchema = z.object({
             agent: key,
             prompt: requiredText(20_000),
             runOn: z.enum(["maus", "cloud"]),
-            schedule: z.discriminatedUnion("type", [
-                z.object({ type: z.literal("once"), at: z.number().int() }),
-                z.object({
-                    type: z.literal("daily"),
-                    time: requiredText(5).regex(/^([01]\d|2[0-3]):[0-5]\d$/, { message: "must use HH:MM" }),
-                    weekdays: z.array(z.number().int().min(0).max(6)).min(1).max(7),
-                }),
-                z.object({
-                    type: z.literal("interval"),
-                    everyMinutes: z.number().int().min(5).max(1_440),
-                    anchorAt: z.number().int().nonnegative().max(MAX_DATE_MS),
-                }),
-            ]),
+            schedule: packageRoutineScheduleSchema,
             durationMinutes: z.number().int().min(5).max(240),
             timeoutMinutes: z.number().int().min(5).max(240).optional(),
             enabledAfterInstall: z.literal(false),
@@ -200,6 +234,18 @@ export function parseBotPackage(value) {
     return parsed.data;
 }
 const list = (values) => values.map((value) => `- ${value}`).join("\n");
+const WEEKDAY_NAMES = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+function intervalScheduleText(schedule) {
+    const restrictions = [
+        schedule.weekdays?.length
+            ? `on ${schedule.weekdays.map((day) => WEEKDAY_NAMES[day]).join(", ")}`
+            : null,
+        schedule.window ? `during ${schedule.window.start}–${schedule.window.end}` : null,
+        schedule.endsAt !== undefined ? `until ${new Date(schedule.endsAt).toISOString()}` : null,
+    ].filter((part) => part !== null);
+    const cadence = `every ${schedule.everyMinutes} minutes from ${new Date(schedule.anchorAt).toISOString()}`;
+    return restrictions.length ? `${cadence}; ${restrictions.join("; ")}` : cadence;
+}
 /** Render the public artifact. The frontmatter enables deterministic imports;
  * the body is deliberately complete enough for any Chief-of-Staff agent to
  * run without OpenMausBot or another proprietary parser. */
@@ -226,7 +272,7 @@ export function renderBotPackageMarkdown(document) {
         `**Schedule:** ${routine.schedule.type === "daily"
             ? `${routine.schedule.time} on weekdays ${routine.schedule.weekdays.join(", ")}`
             : routine.schedule.type === "interval"
-                ? `every ${routine.schedule.everyMinutes} minutes from ${new Date(routine.schedule.anchorAt).toISOString()}`
+                ? intervalScheduleText(routine.schedule)
                 : `once at ${routine.schedule.at}`}  `,
         `**Run limit:** ${routine.timeoutMinutes === undefined ? "none" : `${routine.timeoutMinutes} minutes`}  `,
         "**Initial state:** paused — the user must enable it",

package/dist-server/server/config.js

@@ -5,6 +5,7 @@ import { readFileSync, mkdirSync, existsSync, renameSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { z } from "zod";
+import { normalizeImageGenerationUrl } from "../shared/image-generation.js";
 import { writeFileAtomic } from "./atomic.js";
 import { EFFORT_LEVELS } from "./contracts.js";
 import { parseStoredMcpServer } from "./mcp-registry.js";
@@ -247,8 +248,24 @@ const appConfigSchema = z.object({
      * engine: "elevenlabs" (default; needs a key) or "system" (the Mac's
      * built-in voices, no key). */
     tts: z.object({ key: optionalText, voice: optionalText, provider: z.enum(["elevenlabs", "system"]).optional() }).optional(),
-    /** OpenAI key used only by the in-process avatar image generator. */
-    imageGen: z.object({ key: optionalText }).optional(),
+    /** Avatar provider credentials stay separate; choosing a router never reuses a cloud key. */
+    imageGen: z.object({
+        provider: z.enum(["openai", "xai", "custom"]).optional(),
+        key: optionalText,
+        customApiKey: optionalText,
+        customUrl: z.string().trim().max(2048).transform((value, ctx) => {
+            if (!value)
+                return "";
+            try {
+                return normalizeImageGenerationUrl(value);
+            }
+            catch (error) {
+                ctx.addIssue({ code: "custom", message: error.message });
+                return z.NEVER;
+            }
+        }).optional(),
+        customModel: z.string().trim().max(200).refine((value) => !["\r", "\n", "\0"].some((character) => value.includes(character)), "Use a model ID without control characters").optional(),
+    }).optional(),
     /** Non-secret profile details shown in the sidebar. */
     profile: z.object({ name: optionalText, email: optionalText }).optional(),
     /** UI language override (BCP-47, lowercase). Empty/absent = follow the
@@ -433,6 +450,8 @@ export function loadConfig() {
     cfg.imageGen = { ...cfg.imageGen };
     if (process.env.OMB_OPENAI_IMAGE_KEY !== undefined)
         cfg.imageGen.key = process.env.OMB_OPENAI_IMAGE_KEY;
+    if (process.env.OMB_CUSTOM_IMAGE_KEY !== undefined)
+        cfg.imageGen.customApiKey = process.env.OMB_CUSTOM_IMAGE_KEY;
     // The sign-in allow-list: env is how a headless box or a container is
     // bootstrapped before anyone can reach Settings.
     const splitEmails = (value) => value.split(/[,\s]+/).map((entry) => entry.trim().toLowerCase()).filter(Boolean);
@@ -461,6 +480,7 @@ export function syncCredentialEnv(patch) {
         [patch.opencodeGo?.apiKey, "OPENCODE_API_KEY"],
         [patch.tts?.key, "OMB_TTS_KEY"],
         [patch.imageGen?.key, "OMB_OPENAI_IMAGE_KEY"],
+        [patch.imageGen?.customApiKey, "OMB_CUSTOM_IMAGE_KEY"],
     ];
     for (const [value, name] of secrets) {
         if (value === undefined)
@@ -499,6 +519,7 @@ export const WORKSPACE_CREDENTIAL_ENV = [
     "OPENCODE_API_KEY",
     "OMB_TTS_KEY",
     "OMB_OPENAI_IMAGE_KEY",
+    "OMB_CUSTOM_IMAGE_KEY",
     "COMPOSIO_API_KEY",
     "OMB_COMPOSIO_BROKER_TOKEN",
     // Harness-private filesystem hints are not credentials themselves, but

package/dist-server/server/delegations.js

@@ -86,19 +86,26 @@ export function threadsWaitingOn(toBotId) {
 }
 /** Mark a target's observed busy period as finished and return the source
  * threads that should be retried. This makes retries count distinct busy
- * periods, not unrelated drain requests on the same source thread. */
-export function releaseDelegationsWaitingOn(toBotId) {
-    const threads = threadsWaitingOn(toBotId);
-    if (!threads.length)
-        return threads;
-    for (const threadId of threads) {
-        for (const item of pendingDelegations.get(threadId) ?? []) {
-            if (item.toBotId === toBotId)
-                delete item.waitingOnBusy;
+ * periods, not unrelated drain requests on the same source thread.
+ * `only` narrows the release: a bot that is still busy in one thread has
+ * nevertheless freed a slot for the fresh-thread handoffs waiting on it,
+ * while its active-thread handoffs go on waiting for it to go idle. */
+export function releaseDelegationsWaitingOn(toBotId, only) {
+    const released = [];
+    for (const [threadId, items] of pendingDelegations) {
+        let any = false;
+        for (const item of items) {
+            if (item.toBotId !== toBotId || item.waitingOnBusy !== true || (only && !only(item)))
+                continue;
+            delete item.waitingOnBusy;
+            any = true;
         }
+        if (any)
+            released.push(threadId);
     }
-    savePending();
-    return threads;
+    if (released.length)
+        savePending();
+    return released;
 }
 function savePending() {
     try {
@@ -140,6 +147,9 @@ export function _loadPending() {
                 if (typeof item.originatingGroupId === "string" && item.originatingGroupId) {
                     loaded.originatingGroupId = item.originatingGroupId;
                 }
+                if (typeof item.targetThreadId === "string" && item.targetThreadId) {
+                    loaded.targetThreadId = item.targetThreadId;
+                }
                 return [loaded];
             });
             if (items.length)
@@ -195,6 +205,7 @@ export function pendingDelegationSnapshot() {
         sourceBotId: item.sourceBotId,
         toBotId: item.toBotId,
         ...(item.reason ? { reason: item.reason } : {}),
+        ...(item.targetThreadId ? { targetThreadId: item.targetThreadId } : {}),
     })));
 }
 /** How many handoffs one turn may queue. Small on purpose: this is the only
@@ -231,18 +242,27 @@ export function queueDelegation(bus, from, item, maxDepth, sourceThreadId = from
     list.push({ ...item, id, sourceBotId: from.id, attempts: 0, ...(groupId ? { originatingGroupId: groupId } : {}) });
     pendingDelegations.set(sourceThreadId, list);
     savePending();
-    const label = `Delegated to @${target.name}${item.reason ? `: ${item.reason}` : ""}`;
     const sourceGroup = sourceThreadId ? bus.store.groupByThread(sourceThreadId) : undefined;
-    bus.store.appendMessage(sourceThreadId, {
+    // A fresh-thread handoff is announced as the thread it opened, with a
+    // link to it; a classic one as the delegation it is.
+    const openedThread = item.targetThreadId ? bus.store.taskByThread(target.id, item.targetThreadId) : undefined;
+    const chip = {
         role: "bot",
         kind: "activity",
         // settled at birth: queueing is the whole act. Left open, the chip
         // would spin until the transcript is closed — the chat never patches it
-        tool: { name: label, ok: true },
-        ...(sourceGroup && !sourceGroup.dm
-            ? { from: { botId: from.id, name: from.name, color: from.color } }
-            : {}),
-    });
+        tool: {
+            name: openedThread
+                ? `Opened thread #${openedThread.title} on ${target.name}`
+                : `Delegated to @${target.name}${item.reason ? `: ${item.reason}` : ""}`,
+            ok: true,
+        },
+    };
+    if (openedThread)
+        chip.threadRef = { botId: target.id, threadId: openedThread.threadId, title: openedThread.title };
+    if (sourceGroup && !sourceGroup.dm)
+        chip.from = { botId: from.id, name: from.name, color: from.color };
+    bus.store.appendMessage(sourceThreadId, chip);
     return { result: "ok", id };
 }
 /** Drain queued delegations for a source thread (called on its
@@ -418,35 +438,12 @@ async function processOne(bus, approvalBus, from, sourceThreadId, item, runTarge
     if (dropIfUnreachable(bus, sender, target, sourceThreadId, item)) {
         return "settled";
     }
-    if (target.busy) {
-        if (item.waitingOnBusy)
-            return "requeued";
-        item.attempts += 1;
-        item.waitingOnBusy = true;
-        if (item.attempts < MAX_BUSY_ATTEMPTS) {
-            savePending();
-            bus.store.appendMessage(sourceThreadId, {
-                role: "bot",
-                kind: "activity",
-                tool: { name: `Delegation to @${target.name} waiting — they're busy (retry ${item.attempts}/${MAX_BUSY_ATTEMPTS} when they finish)` },
-            });
-            return "requeued";
-        }
-        recordDelegationReceipt({
-            id: item.id,
-            sourceThreadId,
-            toBotId: target.id,
-            toBotName: target.name,
-            status: "busy_gave_up",
-            result: `@${target.name} stayed busy through ${MAX_BUSY_ATTEMPTS} retries`,
-        });
-        bus.store.appendMessage(sourceThreadId, {
-            role: "bot",
-            kind: "activity",
-            tool: { name: `Delegation to @${target.name} canceled — still busy after ${MAX_BUSY_ATTEMPTS} retries`, ok: false },
-        });
+    if (dropIfThreadGone(bus, target, sourceThreadId, item)) {
         return "settled";
     }
+    const held = holdWhileTargetBusy(bus, target, sourceThreadId, item);
+    if (held)
+        return held;
     if (item.waitingOnBusy) {
         delete item.waitingOnBusy;
         savePending();
@@ -494,35 +491,12 @@ async function processOne(bus, approvalBus, from, sourceThreadId, item, runTarge
         if (dropIfUnreachable(bus, currentSender, current, sourceThreadId, item)) {
             return "settled";
         }
-        if (current.busy) {
-            if (item.waitingOnBusy)
-                return "requeued";
-            item.attempts += 1;
-            item.waitingOnBusy = true;
-            if (item.attempts < MAX_BUSY_ATTEMPTS) {
-                savePending();
-                bus.store.appendMessage(sourceThreadId, {
-                    role: "bot",
-                    kind: "activity",
-                    tool: { name: `Delegation to @${current.name} waiting — they're busy (retry ${item.attempts}/${MAX_BUSY_ATTEMPTS} when they finish)` },
-                });
-                return "requeued";
-            }
-            recordDelegationReceipt({
-                id: item.id,
-                sourceThreadId,
-                toBotId: current.id,
-                toBotName: current.name,
-                status: "busy_gave_up",
-                result: `@${current.name} stayed busy through ${MAX_BUSY_ATTEMPTS} retries`,
-            });
-            bus.store.appendMessage(sourceThreadId, {
-                role: "bot",
-                kind: "activity",
-                tool: { name: `Delegation to @${current.name} canceled — still busy after ${MAX_BUSY_ATTEMPTS} retries`, ok: false },
-            });
+        if (dropIfThreadGone(bus, current, sourceThreadId, item)) {
             return "settled";
         }
+        const heldAfterApproval = holdWhileTargetBusy(bus, current, sourceThreadId, item);
+        if (heldAfterApproval)
+            return heldAfterApproval;
         sender = currentSender;
         target = current;
     }
@@ -533,10 +507,94 @@ async function processOne(bus, approvalBus, from, sourceThreadId, item, runTarge
     const channel = getOrCreateChannel(bus.store, sender, target, originatingGroup);
     mirrorExchange(bus, sender, target, item.message, channel, sourceThreadId);
     const reasonLine = item.reason ? `\n\n[Reason: ${item.reason}]` : "";
-    const prefixed = `[Delegated by @${sender.name}, another bot in this OpenMausBot workspace. Do the work and reply directly.]\n\n${item.message}${reasonLine}`;
-    await runTarget(item.toBotId, prefixed, item.depth + 1, sourceThreadId, channel, item.id, sender.id);
+    // A fresh thread's first line gets the shared peer-provenance note from
+    // the harness (which knows whether the opener was unattended); the
+    // classic handoff keeps the prefix it has always had.
+    const prefixed = item.targetThreadId
+        ? item.message
+        : `[Delegated by @${sender.name}, another bot in this OpenMausBot workspace. Do the work and reply directly.]\n\n${item.message}${reasonLine}`;
+    await runTarget(item.toBotId, prefixed, item.depth + 1, sourceThreadId, channel, item.id, sender.id, item.targetThreadId);
     return "dispatched";
 }
+/** A busy target holds the handoff. What "busy" means depends on where the
+ * turn will run: a classic delegation lands in the target's active thread,
+ * so it waits for the bot to go idle, with bounded retries so a stuck peer
+ * cannot pin the handoff forever. A fresh-thread handoff needs only a free
+ * slot, and waits in line for one without a bound — it IS the line, the
+ * same one a person's message joins at that limit. Returns null when the
+ * target can take the turn now. */
+function holdWhileTargetBusy(bus, target, sourceThreadId, item) {
+    if (item.targetThreadId) {
+        if (bus.threadSlotFree ? bus.threadSlotFree(target.id) : !target.busy)
+            return null;
+        if (item.waitingOnBusy)
+            return "requeued";
+        item.waitingOnBusy = true;
+        savePending();
+        // one chip per wait, not one per retry: the line moves on every settle
+        if (item.attempts === 0) {
+            item.attempts = 1;
+            const title = bus.store.taskByThread(target.id, item.targetThreadId)?.title ?? "thread";
+            bus.store.appendMessage(sourceThreadId, {
+                role: "bot",
+                kind: "activity",
+                tool: { name: `Thread #${title} on @${target.name} waiting for a free slot` },
+            });
+        }
+        return "requeued";
+    }
+    if (!target.busy)
+        return null;
+    if (item.waitingOnBusy)
+        return "requeued";
+    item.attempts += 1;
+    item.waitingOnBusy = true;
+    if (item.attempts < MAX_BUSY_ATTEMPTS) {
+        savePending();
+        bus.store.appendMessage(sourceThreadId, {
+            role: "bot",
+            kind: "activity",
+            tool: { name: `Delegation to @${target.name} waiting — they're busy (retry ${item.attempts}/${MAX_BUSY_ATTEMPTS} when they finish)` },
+        });
+        return "requeued";
+    }
+    recordDelegationReceipt({
+        id: item.id,
+        sourceThreadId,
+        toBotId: target.id,
+        toBotName: target.name,
+        status: "busy_gave_up",
+        result: `@${target.name} stayed busy through ${MAX_BUSY_ATTEMPTS} retries`,
+    });
+    bus.store.appendMessage(sourceThreadId, {
+        role: "bot",
+        kind: "activity",
+        tool: { name: `Delegation to @${target.name} canceled — still busy after ${MAX_BUSY_ATTEMPTS} retries`, ok: false },
+    });
+    return "settled";
+}
+/** The thread a fresh-thread handoff was opened in may be deleted while the
+ * handoff waits. There is nowhere for the turn to run then, and running it
+ * in the target's active thread would put a bot's job in front of the
+ * person unasked. */
+function dropIfThreadGone(bus, target, sourceThreadId, item) {
+    if (!item.targetThreadId || bus.store.taskByThread(target.id, item.targetThreadId))
+        return false;
+    recordDelegationReceipt({
+        id: item.id,
+        sourceThreadId,
+        toBotId: target.id,
+        toBotName: target.name,
+        status: "dropped",
+        result: `the thread opened on @${target.name} was deleted before it could start`,
+    });
+    bus.store.appendMessage(sourceThreadId, {
+        role: "bot",
+        kind: "activity",
+        tool: { name: `Thread on @${target.name} canceled — it was deleted before it could start`, ok: false },
+    });
+    return true;
+}
 /** The source thread may be a bot's own task or a shared group where the
  * bot is a member. This is the same check the API gate uses for group turns. */
 function sourceThreadBelongsToBot(store, botId, threadId) {