@openscout/scout 0.2.61 → 0.2.62

package/dist/main.mjs

@@ -118,6 +118,15 @@ function parseFlagValue(args, index, flag) {
   }
   missingFlagValue(flag);
 }
+function flagNameFor(current, flagNames) {
+  return flagNames.find((flag) => current === flag || current.startsWith(`${flag}=`)) ?? null;
+}
+function resolveInputFilePath(currentDirectory, filePath) {
+  return resolve2(currentDirectory, filePath);
+}
+function rejectMixedBodySources(kind) {
+  throw new ScoutCliError(kind === "message" ? "provide either an inline message or --message-file/--body-file, not both" : "provide either an inline question or --prompt-file/--body-file, not both");
+}
 function parseContextRootPrefix(args, defaultCurrentDirectory) {
   let currentDirectory = defaultCurrentDirectory;
   const rest = [];
@@ -184,6 +193,7 @@ function parseSendCommandOptions(args, defaultCurrentDirectory) {
   let channel;
   let shouldSpeak = false;
   let harness;
+  let messageFile;
   const messageParts = [];
   for (let index = 0;index < parsed.args.length; index += 1) {
     const current = parsed.args[index] ?? "";
@@ -209,10 +219,23 @@ function parseSendCommandOptions(args, defaultCurrentDirectory) {
       shouldSpeak = true;
       continue;
     }
+    const fileFlag = flagNameFor(current, ["--message-file", "--body-file"]);
+    if (fileFlag) {
+      if (messageFile) {
+        throw new ScoutCliError("message file was provided more than once");
+      }
+      const value = parseFlagValue(parsed.args, index, fileFlag);
+      messageFile = resolveInputFilePath(parsed.currentDirectory, value.value);
+      index = value.nextIndex;
+      continue;
+    }
     messageParts.push(current);
   }
   const message = messageParts.join(" ").trim();
-  if (!message) {
+  if (message && messageFile) {
+    rejectMixedBodySources("message");
+  }
+  if (!message && !messageFile) {
     throw new ScoutCliError("no message provided");
   }
   return {
@@ -222,7 +245,8 @@ function parseSendCommandOptions(args, defaultCurrentDirectory) {
     channel,
     shouldSpeak,
     harness,
-    message
+    message,
+    messageFile
   };
 }
 function parseAskCommandOptions(args, defaultCurrentDirectory) {
@@ -232,6 +256,7 @@ function parseAskCommandOptions(args, defaultCurrentDirectory) {
   let channel;
   let harness;
   let timeoutSeconds;
+  let promptFile;
   const messageParts = [];
   for (let index = 0;index < parsed.args.length; index += 1) {
     const current = parsed.args[index] ?? "";
@@ -269,13 +294,26 @@ function parseAskCommandOptions(args, defaultCurrentDirectory) {
       index = value.nextIndex;
       continue;
     }
+    const fileFlag = flagNameFor(current, ["--prompt-file", "--body-file"]);
+    if (fileFlag) {
+      if (promptFile) {
+        throw new ScoutCliError("prompt file was provided more than once");
+      }
+      const value = parseFlagValue(parsed.args, index, fileFlag);
+      promptFile = resolveInputFilePath(parsed.currentDirectory, value.value);
+      index = value.nextIndex;
+      continue;
+    }
     messageParts.push(current);
   }
   const message = messageParts.join(" ").trim();
   if (!targetLabel) {
     throw new ScoutCliError("--to <name> is required");
   }
-  if (!message) {
+  if (message && promptFile) {
+    rejectMixedBodySources("question");
+  }
+  if (!message && !promptFile) {
     throw new ScoutCliError("no question provided");
   }
   return {
@@ -286,7 +324,8 @@ function parseAskCommandOptions(args, defaultCurrentDirectory) {
     channel,
     harness,
     timeoutSeconds,
-    message
+    message,
+    promptFile
   };
 }
 function parseImplicitAskCommandOptions(args, defaultCurrentDirectory) {
@@ -295,6 +334,7 @@ function parseImplicitAskCommandOptions(args, defaultCurrentDirectory) {
   let channel;
   let harness;
   let timeoutSeconds;
+  let promptFile;
   const messageParts = [];
   for (let index = 0;index < parsed.args.length; index += 1) {
     const current = parsed.args[index] ?? "";
@@ -326,6 +366,16 @@ function parseImplicitAskCommandOptions(args, defaultCurrentDirectory) {
       index = value.nextIndex;
       continue;
     }
+    const fileFlag = flagNameFor(current, ["--prompt-file", "--body-file"]);
+    if (fileFlag) {
+      if (promptFile) {
+        throw new ScoutCliError("prompt file was provided more than once");
+      }
+      const value = parseFlagValue(parsed.args, index, fileFlag);
+      promptFile = resolveInputFilePath(parsed.currentDirectory, value.value);
+      index = value.nextIndex;
+      continue;
+    }
     messageParts.push(current);
   }
   const input = messageParts.join(" ").trim();
@@ -341,7 +391,10 @@ function parseImplicitAskCommandOptions(args, defaultCurrentDirectory) {
   }
   const [target] = mentions;
   const message = stripMention(input, target);
-  if (!message) {
+  if (message && promptFile) {
+    rejectMixedBodySources("question");
+  }
+  if (!message && !promptFile) {
     throw new ScoutCliError("no question provided");
   }
   return {
@@ -352,7 +405,8 @@ function parseImplicitAskCommandOptions(args, defaultCurrentDirectory) {
     channel,
     harness,
     timeoutSeconds,
-    message
+    message,
+    promptFile
   };
 }
 function parseWatchCommandOptions(args, defaultCurrentDirectory) {
@@ -581,6 +635,32 @@ var init_options = __esm(() => {
   SCOUT_MENTION_PATTERN = /(^|[\s([{'"`])@([A-Za-z0-9._:-]+)(?=$|[\s)\]}",.!?:;'"`])/g;
 });
 
+// ../../apps/desktop/src/cli/input-file.ts
+import { readFile } from "fs/promises";
+async function readCliInputFile(filePath, label) {
+  let body;
+  try {
+    body = await readFile(filePath, "utf8");
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new ScoutCliError(`could not read ${label} file ${filePath}: ${detail}`);
+  }
+  const normalized = body.replace(/^\uFEFF/, "");
+  if (!normalized.trim()) {
+    throw new ScoutCliError(`${label} file is empty: ${filePath}`);
+  }
+  return normalized;
+}
+async function resolvePromptBody(input) {
+  return input.promptFile ? readCliInputFile(input.promptFile, "prompt") : input.message;
+}
+async function resolveMessageBody(input) {
+  return input.messageFile ? readCliInputFile(input.messageFile, "message") : input.message;
+}
+var init_input_file = __esm(() => {
+  init_errors();
+});
+
 // ../protocol/dist/common.js
 var init_common = () => {};
 
@@ -996,6 +1076,9 @@ var init_invocations = () => {};
 // ../protocol/dist/scout-dispatch.js
 var init_scout_dispatch = () => {};
 
+// ../protocol/dist/scout-delivery.js
+var init_scout_delivery = () => {};
+
 // ../protocol/dist/deliveries.js
 var init_deliveries = () => {};
 
@@ -1020,6 +1103,7 @@ var init_dist = __esm(() => {
   init_messages();
   init_invocations();
   init_scout_dispatch();
+  init_scout_delivery();
   init_deliveries();
   init_transports();
   init_events();
@@ -2064,7 +2148,7 @@ var init_support_paths = () => {};
 // ../runtime/src/harness-catalog.ts
 import { execFileSync } from "child_process";
 import { existsSync as existsSync2, statSync } from "fs";
-import { mkdir, readFile, writeFile } from "fs/promises";
+import { mkdir, readFile as readFile2, writeFile } from "fs/promises";
 import { dirname, join as join2 } from "path";
 function expandHomePath(value) {
   if (value === "~")
@@ -2295,7 +2379,7 @@ function evaluateHarnessReadiness(entry, options = {}) {
 }
 async function readHarnessCatalogOverrides(overridePath = resolveOpenScoutSupportPaths().harnessCatalogPath) {
   try {
-    const raw = JSON.parse(await readFile(overridePath, "utf8"));
+    const raw = JSON.parse(await readFile2(overridePath, "utf8"));
     return raw.entries ?? {};
   } catch {
     return {};
@@ -2422,7 +2506,7 @@ var init_harness_catalog = __esm(() => {
 });
 
 // ../runtime/src/user-project-hints.ts
-import { readdir, readFile as readFile2, stat } from "fs/promises";
+import { readdir, readFile as readFile3, stat } from "fs/promises";
 import { homedir as homedir2 } from "os";
 import { dirname as dirname2, join as join3, resolve as resolve3 } from "path";
 import { fileURLToPath } from "url";
@@ -2547,7 +2631,7 @@ async function appendCodexHistoryPaths(home, roots) {
     }
     let body;
     try {
-      body = await readFile2(filePath, "utf8");
+      body = await readFile3(filePath, "utf8");
     } catch {
       continue;
     }
@@ -2586,7 +2670,7 @@ async function appendCursorWorkspacePaths(home, roots) {
     const workspaceJsonPath = join3(base, id, "workspace.json");
     let raw;
     try {
-      raw = await readFile2(workspaceJsonPath, "utf8");
+      raw = await readFile3(workspaceJsonPath, "utf8");
     } catch {
       continue;
     }
@@ -2617,7 +2701,7 @@ async function appendCursorWorkspacePaths(home, roots) {
         if (!wsStat.isFile()) {
           continue;
         }
-        const wsRaw = await readFile2(wsFile, "utf8");
+        const wsRaw = await readFile3(wsFile, "utf8");
         const wsDoc = JSON.parse(wsRaw);
         const wsDir = dirname2(wsFile);
         for (const f of wsDoc.folders ?? []) {
@@ -2687,7 +2771,7 @@ async function appendClaudeSessionPaths(home, roots) {
       seenFiles += 1;
       let body;
       try {
-        body = await readFile2(sessionPath, "utf8");
+        body = await readFile3(sessionPath, "utf8");
       } catch {
         continue;
       }
@@ -2749,7 +2833,7 @@ var init_user_project_hints = __esm(() => {
 // ../runtime/src/setup.ts
 import { execFileSync as execFileSync2 } from "child_process";
 import { existsSync as existsSync3, readFileSync } from "fs";
-import { access, mkdir as mkdir2, readdir as readdir2, readFile as readFile3, realpath, rm, stat as stat2, writeFile as writeFile2 } from "fs/promises";
+import { access, mkdir as mkdir2, readdir as readdir2, readFile as readFile4, realpath, rm, stat as stat2, writeFile as writeFile2 } from "fs/promises";
 import { homedir as homedir3, hostname, userInfo } from "os";
 import { basename, dirname as dirname3, isAbsolute, join as join4, relative, resolve as resolve4 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
@@ -3206,7 +3290,7 @@ async function isDirectory(filePath) {
 }
 async function readJsonFile(filePath) {
   try {
-    return JSON.parse(await readFile3(filePath, "utf8"));
+    return JSON.parse(await readFile4(filePath, "utf8"));
   } catch {
     return null;
   }
@@ -3352,7 +3436,7 @@ async function readCodexEnvironmentImport(projectRoot) {
   const sourcePath = codexEnvironmentPath(projectRoot);
   let body;
   try {
-    body = await readFile3(sourcePath, "utf8");
+    body = await readFile4(sourcePath, "utf8");
   } catch {
     return null;
   }
@@ -3398,7 +3482,7 @@ async function readClaudeProjectImport(projectRoot) {
     const sessionPath = join4(sourcePath, entry);
     let body;
     try {
-      body = await readFile3(sessionPath, "utf8");
+      body = await readFile4(sessionPath, "utf8");
     } catch {
       continue;
     }
@@ -3492,7 +3576,7 @@ async function ensureProjectConfigIgnored(projectRoot) {
   const comment = "# OpenScout local state";
   let current = "";
   try {
-    current = await readFile3(gitignorePath, "utf8");
+    current = await readFile4(gitignorePath, "utf8");
   } catch {
     current = "";
   }
@@ -3653,6 +3737,35 @@ async function readOpenScoutSettings(options = {}) {
     legacyAgents
   });
 }
+function resolveOpenScoutSetupContextRoot(options = {}) {
+  const env = options.env ?? process.env;
+  const explicit = env.OPENSCOUT_SETUP_CWD?.trim();
+  if (explicit) {
+    return normalizePath(explicit);
+  }
+  const home = env.HOME?.trim() || homedir3();
+  const supportDirectory = env.OPENSCOUT_SUPPORT_DIRECTORY?.trim() || join4(home, "Library", "Application Support", "OpenScout");
+  const settingsPath = join4(supportDirectory, "settings.json");
+  if (existsSync3(settingsPath)) {
+    try {
+      const raw = JSON.parse(readFileSync(settingsPath, "utf8"));
+      const discovery = raw.discovery;
+      if (typeof discovery?.contextRoot === "string" && discovery.contextRoot.trim()) {
+        return normalizePath(discovery.contextRoot);
+      }
+      if (Array.isArray(discovery?.workspaceRoots)) {
+        const workspaceRoot = discovery.workspaceRoots.find((entry) => typeof entry === "string" && entry.trim().length > 0);
+        if (workspaceRoot) {
+          return normalizePath(workspaceRoot);
+        }
+      }
+    } catch {}
+  }
+  if (options.fallbackDirectory?.trim()) {
+    return normalizePath(options.fallbackDirectory);
+  }
+  return normalizePath(process.cwd());
+}
 async function writeOpenScoutSettings(settings, options = {}) {
   ensureOpenScoutCleanSlateSync();
   const current = await readOpenScoutSettings(options);
@@ -3715,7 +3828,7 @@ async function installScoutSkillToHarnesses() {
   if (!source) {
     return { source: null, entries: [] };
   }
-  const content = await readFile3(source, "utf8");
+  const content = await readFile4(source, "utf8");
   const entries = [];
   for (const harness of MANAGED_AGENT_HARNESSES) {
     const target = SCOUT_SKILL_INSTALL_PATHS[harness];
@@ -4595,7 +4708,7 @@ function buildManagedAgentShellExports(options) {
 // ../runtime/src/claude-stream-json.ts
 import { randomUUID } from "crypto";
 import { spawn } from "child_process";
-import { appendFile, mkdir as mkdir3, readFile as readFile4, writeFile as writeFile3 } from "fs/promises";
+import { appendFile, mkdir as mkdir3, readFile as readFile5, writeFile as writeFile3 } from "fs/promises";
 import { existsSync as existsSync4, readFileSync as readFileSync2 } from "fs";
 import { join as join5 } from "path";
 function resolveClaudeStreamJsonOutput(result, fallbackParts) {
@@ -5061,6 +5174,9 @@ function normalizeApprovalRequest(session, turnId, block) {
   };
 }
 
+// ../agent-sessions/src/protocol/cost.ts
+var init_cost = () => {};
+
 // ../agent-sessions/src/state.ts
 function normalizeTrackedTimestamp(value) {
   if (value == null) {
@@ -5607,6 +5723,15 @@ function stringifyUnknown(value) {
     return String(value);
   }
 }
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function maybeString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function maybeNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
 function renderToolResultContent(content) {
   if (typeof content === "string") {
     return content;
@@ -5663,6 +5788,7 @@ class ClaudeCodeHistoryParser {
   blockById = new Map;
   activeStreamBlocks = new Map;
   sawStreamTextThisTurn = false;
+  assistantUsageByMessageId = new Map;
   constructor(session, baseTimestampMs) {
     this.session = session;
     this.baseTimestampMs = baseTimestampMs;
@@ -5672,6 +5798,7 @@ class ClaudeCodeHistoryParser {
     let parsedLineCount = 0;
     let skippedLineCount = 0;
     let lineCount = 0;
+    let lastCapturedAt = this.baseTimestampMs;
     for (let index = 0;index < lines.length; index += 1) {
       const rawLine = lines[index];
       const trimmed = rawLine.trim();
@@ -5692,12 +5819,19 @@ class ClaudeCodeHistoryParser {
         continue;
       }
       const capturedAt = extractRecordTimestamp(record) ?? this.baseTimestampMs + index;
+      lastCapturedAt = capturedAt;
       if (this.handleRecord(record, capturedAt)) {
         parsedLineCount += 1;
       } else {
         skippedLineCount += 1;
       }
     }
+    if (this.persistObserveUsageMetadata()) {
+      this.emitEvent(lastCapturedAt, {
+        event: "session:update",
+        session: { ...this.session }
+      });
+    }
     return {
       events: this.events,
       lineCount,
@@ -5706,6 +5840,7 @@ class ClaudeCodeHistoryParser {
     };
   }
   handleRecord(record, capturedAt) {
+    this.captureRecordMetadata(record);
     const type = typeof record.type === "string" ? record.type : null;
     if (!type) {
       return false;
@@ -5715,7 +5850,7 @@ class ClaudeCodeHistoryParser {
         this.handleSystem(record, capturedAt);
         return true;
       case "user":
-        this.startTurn(capturedAt);
+        this.handleUser(record, capturedAt);
         return true;
       case "assistant":
         this.handleAssistant(record, capturedAt);
@@ -5739,6 +5874,130 @@ class ClaudeCodeHistoryParser {
         return false;
     }
   }
+  captureRecordMetadata(record) {
+    const runtime = this.ensureObserveMetaRecord("observeRuntime");
+    this.assignObserveString(runtime, "entrypoint", record.entrypoint);
+    this.assignObserveString(runtime, "cliVersion", record.version);
+    this.assignObserveString(runtime, "gitBranch", record.gitBranch);
+    this.assignObserveString(runtime, "permissionMode", record.permissionMode);
+    this.assignObserveString(runtime, "userType", record.userType);
+    const recordCwd = maybeString(record.cwd);
+    if (recordCwd && !this.session.cwd) {
+      this.session.cwd = recordCwd;
+    }
+    const message = isRecord(record.message) ? record.message : null;
+    const model = maybeString(message?.model);
+    if (model && !this.session.model) {
+      this.session.model = model;
+    }
+    const usage = this.readClaudeUsageEntry(record);
+    if (!usage) {
+      return;
+    }
+    const messageId = maybeString(message?.id) ?? maybeString(record.requestId) ?? maybeString(record.uuid);
+    if (!messageId) {
+      return;
+    }
+    this.assistantUsageByMessageId.set(messageId, usage);
+  }
+  readClaudeUsageEntry(record) {
+    const type = maybeString(record.type);
+    const message = isRecord(record.message) ? record.message : null;
+    const role = maybeString(message?.role);
+    if (type !== "assistant" && role !== "assistant") {
+      return null;
+    }
+    const usage = isRecord(message?.usage) ? message.usage : null;
+    const serverToolUse = isRecord(usage?.server_tool_use) ? usage.server_tool_use : null;
+    const entry = {
+      inputTokens: maybeNumber(usage?.input_tokens) ?? 0,
+      outputTokens: maybeNumber(usage?.output_tokens) ?? 0,
+      cacheReadInputTokens: maybeNumber(usage?.cache_read_input_tokens) ?? 0,
+      cacheCreationInputTokens: maybeNumber(usage?.cache_creation_input_tokens) ?? 0,
+      webSearchRequests: maybeNumber(serverToolUse?.web_search_requests) ?? 0,
+      webFetchRequests: maybeNumber(serverToolUse?.web_fetch_requests) ?? 0,
+      ...maybeString(message?.service_tier) ? { serviceTier: maybeString(message?.service_tier) } : {},
+      ...maybeString(message?.speed) ? { speed: maybeString(message?.speed) } : {}
+    };
+    const hasUsage = entry.inputTokens > 0 || entry.outputTokens > 0 || entry.cacheReadInputTokens > 0 || entry.cacheCreationInputTokens > 0 || entry.webSearchRequests > 0 || entry.webFetchRequests > 0 || Boolean(entry.serviceTier) || Boolean(entry.speed);
+    return hasUsage ? entry : null;
+  }
+  persistObserveUsageMetadata() {
+    if (this.assistantUsageByMessageId.size === 0) {
+      return false;
+    }
+    const usage = this.ensureObserveMetaRecord("observeUsage");
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheReadInputTokens = 0;
+    let cacheCreationInputTokens = 0;
+    let webSearchRequests = 0;
+    let webFetchRequests = 0;
+    let serviceTier;
+    let speed;
+    for (const entry of this.assistantUsageByMessageId.values()) {
+      inputTokens += entry.inputTokens;
+      outputTokens += entry.outputTokens;
+      cacheReadInputTokens += entry.cacheReadInputTokens;
+      cacheCreationInputTokens += entry.cacheCreationInputTokens;
+      webSearchRequests += entry.webSearchRequests;
+      webFetchRequests += entry.webFetchRequests;
+      if (entry.serviceTier) {
+        serviceTier = entry.serviceTier;
+      }
+      if (entry.speed) {
+        speed = entry.speed;
+      }
+    }
+    let changed = false;
+    const assignNumber = (key, value) => {
+      if (usage[key] !== value) {
+        usage[key] = value;
+        changed = true;
+      }
+    };
+    const assignString = (key, value) => {
+      if (usage[key] !== value) {
+        usage[key] = value;
+        changed = true;
+      }
+    };
+    assignNumber("assistantMessages", this.assistantUsageByMessageId.size);
+    if (inputTokens > 0)
+      assignNumber("inputTokens", inputTokens);
+    if (outputTokens > 0)
+      assignNumber("outputTokens", outputTokens);
+    if (cacheReadInputTokens > 0)
+      assignNumber("cacheReadInputTokens", cacheReadInputTokens);
+    if (cacheCreationInputTokens > 0)
+      assignNumber("cacheCreationInputTokens", cacheCreationInputTokens);
+    if (webSearchRequests > 0)
+      assignNumber("webSearchRequests", webSearchRequests);
+    if (webFetchRequests > 0)
+      assignNumber("webFetchRequests", webFetchRequests);
+    if (serviceTier)
+      assignString("serviceTier", serviceTier);
+    if (speed)
+      assignString("speed", speed);
+    return changed;
+  }
+  ensureObserveMetaRecord(key) {
+    const providerMeta = isRecord(this.session.providerMeta) ? this.session.providerMeta : {};
+    this.session.providerMeta = providerMeta;
+    const existing = providerMeta[key];
+    if (isRecord(existing)) {
+      return existing;
+    }
+    const next = {};
+    providerMeta[key] = next;
+    return next;
+  }
+  assignObserveString(target, key, value) {
+    const next = maybeString(value);
+    if (next) {
+      target[key] = next;
+    }
+  }
   handleSystem(record, capturedAt) {
     if (record.subtype !== "init") {
       return;
@@ -5768,19 +6027,41 @@ class ClaudeCodeHistoryParser {
       });
     }
   }
+  handleUser(record, capturedAt) {
+    const message = record.message && typeof record.message === "object" ? record.message : null;
+    const content = message?.content;
+    if (Array.isArray(content) && content.length > 0) {
+      const toolResults = content.filter((entry) => {
+        return !!entry && typeof entry === "object" && !Array.isArray(entry) && entry.type === "tool_result";
+      });
+      if (toolResults.length === content.length) {
+        for (const toolResult of toolResults) {
+          this.handleToolResult({
+            ...toolResult,
+            tool_use_id: typeof toolResult.tool_use_id === "string" ? toolResult.tool_use_id : toolResult.id,
+            is_error: toolResult.is_error === true
+          }, capturedAt);
+        }
+        return;
+      }
+    }
+    this.startTurn(capturedAt);
+  }
   handleAssistant(record, capturedAt) {
     const turn = this.ensureTurn(capturedAt);
-    if (this.sawStreamTextThisTurn) {
-      return;
-    }
     const content = record.message && typeof record.message === "object" ? record.message.content : record.content;
     if (!Array.isArray(content)) {
+      this.maybeEndTurnFromAssistant(record, capturedAt);
       return;
     }
+    const skipTextBlocks = this.sawStreamTextThisTurn;
     for (const part of content) {
       const contentPart = part;
       const contentType = typeof contentPart.type === "string" ? contentPart.type : "";
       if (contentType === "thinking" || contentType === "reasoning") {
+        if (skipTextBlocks) {
+          continue;
+        }
         const block = this.startBlock(turn, capturedAt, {
           type: "reasoning",
           text: typeof contentPart.thinking === "string" ? contentPart.thinking : typeof contentPart.text === "string" ? contentPart.text : "",
@@ -5788,14 +6069,20 @@ class ClaudeCodeHistoryParser {
         });
         this.emitBlockEnd(capturedAt, turn, block, "completed");
       } else if (contentType === "text") {
+        if (skipTextBlocks) {
+          continue;
+        }
         const block = this.startBlock(turn, capturedAt, {
           type: "text",
           text: typeof contentPart.text === "string" ? contentPart.text : "",
           status: "completed"
         });
         this.emitBlockEnd(capturedAt, turn, block, "completed");
+      } else if (contentType === "tool_use") {
+        this.handleToolUse(contentPart, capturedAt);
       }
     }
+    this.maybeEndTurnFromAssistant(record, capturedAt);
   }
   handleStreamEvent(record, capturedAt) {
     const turn = this.ensureTurn(capturedAt);
@@ -6017,6 +6304,12 @@ class ClaudeCodeHistoryParser {
     this.emitError(turn, capturedAt, message);
     this.endTurn("failed", capturedAt);
   }
+  maybeEndTurnFromAssistant(record, capturedAt) {
+    const stopReason = record.message && typeof record.message === "object" ? record.message.stop_reason : record.stop_reason;
+    if (stopReason === "end_turn") {
+      this.endTurn("completed", capturedAt);
+    }
+  }
   startTurn(capturedAt) {
     if (this.currentTurn) {
       this.endTurn("stopped", capturedAt);
@@ -6839,7 +7132,7 @@ var init_codex_launch_config = () => {};
 
 // ../agent-sessions/src/adapters/codex.ts
 import { spawn as spawn2 } from "child_process";
-import { access as access2, appendFile as appendFile2, constants as constants2, mkdir as mkdir4, readFile as readFile5, rm as rm3, writeFile as writeFile4 } from "fs/promises";
+import { access as access2, appendFile as appendFile2, constants as constants2, mkdir as mkdir4, readFile as readFile6, rm as rm3, writeFile as writeFile4 } from "fs/promises";
 import { delimiter as delimiter2, join as join8 } from "path";
 import { homedir as homedir6 } from "os";
 function parseJsonLine(line) {
@@ -6880,7 +7173,7 @@ function errorMessage2(error) {
 }
 async function readOptionalFile(filePath) {
   try {
-    const raw = await readFile5(filePath, "utf8");
+    const raw = await readFile6(filePath, "utf8");
     const trimmed = raw.trim();
     return trimmed || null;
   } catch {
@@ -9340,12 +9633,13 @@ var init_src = __esm(() => {
   init_pi();
   init_echo();
   init_codex_launch_config();
+  init_cost();
 });
 
 // ../runtime/src/codex-app-server.ts
 import { spawn as spawn3 } from "child_process";
 import { constants as constants3 } from "fs";
-import { access as access3, appendFile as appendFile3, mkdir as mkdir5, readFile as readFile6, rm as rm4, writeFile as writeFile5 } from "fs/promises";
+import { access as access3, appendFile as appendFile3, mkdir as mkdir5, readFile as readFile7, rm as rm4, writeFile as writeFile5 } from "fs/promises";
 import { delimiter as delimiter3, join as join9 } from "path";
 function normalizeCodexModelValue(value) {
   const trimmed = value?.trim();
@@ -9542,7 +9836,7 @@ function isNotification2(message) {
 }
 async function readOptionalFile2(filePath) {
   try {
-    const raw = await readFile6(filePath, "utf8");
+    const raw = await readFile7(filePath, "utf8");
     const trimmed = raw.trim();
     return trimmed || null;
   } catch {
@@ -10283,12 +10577,227 @@ function buildCollaborationContractPrompt(agentId) {
 `);
 }
 
-// ../runtime/src/broker-service.ts
-import { spawnSync } from "child_process";
-import { existsSync as existsSync7, mkdirSync as mkdirSync2, readFileSync as readFileSync3, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
+// ../runtime/src/tool-resolution.ts
+import { accessSync as accessSync2, constants as constants4, existsSync as existsSync7 } from "fs";
 import { homedir as homedir7 } from "os";
 import { basename as basename3, dirname as dirname5, join as join10, resolve as resolve6 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
+function expandHomePath3(value, env = process.env) {
+  const home = env.HOME ?? homedir7();
+  if (value === "~") {
+    return home;
+  }
+  if (value.startsWith("~/")) {
+    return join10(home, value.slice(2));
+  }
+  return value;
+}
+function isExecutablePath(candidate) {
+  if (!candidate) {
+    return false;
+  }
+  try {
+    accessSync2(candidate, constants4.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function splitPathEntries(env = process.env) {
+  const separator = process.platform === "win32" ? ";" : ":";
+  return (env.PATH ?? "").split(separator).filter(Boolean);
+}
+function dedupeDirectories(values, env) {
+  const seen = new Set;
+  const resolvedEntries = [];
+  for (const value of values) {
+    const normalized = resolve6(expandHomePath3(value, env));
+    if (seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    resolvedEntries.push(normalized);
+  }
+  return resolvedEntries;
+}
+function resolveExecutableFromSearch(options) {
+  const env = options.env ?? process.env;
+  const envKeys = options.envKeys ?? [];
+  for (const envKey of envKeys) {
+    const explicit = env[envKey]?.trim();
+    if (!explicit) {
+      continue;
+    }
+    const expanded = expandHomePath3(explicit, env);
+    if (isExecutablePath(expanded)) {
+      return { path: resolve6(expanded), source: "env" };
+    }
+    const foundOnPath = findExecutableOnSearchPath(explicit, env);
+    if (foundOnPath) {
+      return { path: foundOnPath.path, source: "env" };
+    }
+  }
+  const commonDirectories = dedupeDirectories([...options.commonDirectories ?? DEFAULT_COMMON_EXECUTABLE_DIRECTORIES], env);
+  const searchDirectories = dedupeDirectories([
+    ...splitPathEntries(env),
+    ...options.extraDirectories ?? [],
+    ...commonDirectories
+  ], env);
+  for (const directory of searchDirectories) {
+    for (const name of options.names) {
+      const candidate = join10(directory, name);
+      if (isExecutablePath(candidate)) {
+        return {
+          path: candidate,
+          source: commonDirectories.includes(directory) ? "common-path" : "path"
+        };
+      }
+    }
+  }
+  return null;
+}
+function resolveBunExecutable2(env = process.env) {
+  return resolveExecutableFromSearch({
+    env,
+    envKeys: ["OPENSCOUT_BUN_BIN", "SCOUT_BUN_BIN", "BUN_BIN"],
+    names: ["bun"]
+  });
+}
+function resolveJavaScriptRuntime(options = {}) {
+  const env = options.env ?? process.env;
+  const allowNode = options.allowNode ?? true;
+  const allowBun = options.allowBun ?? true;
+  const explicitEnvKeys = options.explicitEnvKeys ?? [];
+  for (const envKey of explicitEnvKeys) {
+    const explicit = env[envKey]?.trim();
+    if (!explicit) {
+      continue;
+    }
+    const expanded = expandHomePath3(explicit, env);
+    const resolvedExplicit = isExecutablePath(expanded) ? resolve6(expanded) : findExecutableOnSearchPath(explicit, env)?.path;
+    if (!resolvedExplicit) {
+      continue;
+    }
+    const kind = javascriptRuntimeKindForPath(resolvedExplicit);
+    if (kind === "node" && allowNode || kind === "bun" && allowBun) {
+      return {
+        path: resolvedExplicit,
+        kind,
+        source: "env"
+      };
+    }
+  }
+  if (options.preferCurrentExecutable ?? true) {
+    const currentExecutable = process.execPath;
+    const kind = javascriptRuntimeKindForPath(currentExecutable);
+    if (kind === "node" && allowNode || kind === "bun" && allowBun) {
+      return {
+        path: currentExecutable,
+        kind,
+        source: "execPath"
+      };
+    }
+  }
+  const searchNames = [];
+  if (allowNode) {
+    searchNames.push("node");
+  }
+  if (allowBun) {
+    searchNames.push("bun");
+  }
+  const resolvedExecutable = resolveExecutableFromSearch({
+    env,
+    names: searchNames
+  });
+  if (!resolvedExecutable) {
+    return null;
+  }
+  return {
+    path: resolvedExecutable.path,
+    kind: javascriptRuntimeKindForPath(resolvedExecutable.path),
+    source: resolvedExecutable.source
+  };
+}
+function resolveBundledEntrypoint(moduleUrl, filename) {
+  const moduleDirectory = dirname5(fileURLToPath4(moduleUrl));
+  const candidate = join10(moduleDirectory, filename);
+  return existsSync7(candidate) ? candidate : null;
+}
+function resolveOpenScoutRepoRoot(options = {}) {
+  const starts = options.startDirectories?.map((entry) => entry?.trim()).filter((entry) => Boolean(entry));
+  if (!starts || starts.length === 0) {
+    return null;
+  }
+  for (const start of starts) {
+    let current = resolve6(start);
+    while (true) {
+      const scoutEntry = join10(current, "apps", "desktop", "bin", "scout.ts");
+      const runtimeEntry = join10(current, "packages", "runtime", "bin", "openscout-runtime.mjs");
+      if (existsSync7(scoutEntry) && existsSync7(runtimeEntry)) {
+        return current;
+      }
+      const parent = dirname5(current);
+      if (parent === current) {
+        break;
+      }
+      current = parent;
+    }
+  }
+  return null;
+}
+function resolveRepoEntrypoint(repoRoot, relativePath) {
+  if (!repoRoot) {
+    return null;
+  }
+  const candidate = join10(repoRoot, relativePath);
+  return existsSync7(candidate) ? candidate : null;
+}
+function resolveNodeModulesPackageEntrypoint(moduleUrl, packageSegments, entryRelativePath) {
+  let current = dirname5(fileURLToPath4(moduleUrl));
+  for (let attempt = 0;attempt < 24; attempt += 1) {
+    const candidate = join10(current, "node_modules", ...packageSegments, entryRelativePath);
+    if (existsSync7(candidate)) {
+      return candidate;
+    }
+    const parent = dirname5(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+  return null;
+}
+function javascriptRuntimeKindForPath(filePath) {
+  return basename3(filePath).toLowerCase().startsWith("bun") ? "bun" : "node";
+}
+function findExecutableOnSearchPath(name, env) {
+  const searchDirectories = dedupeDirectories([
+    ...splitPathEntries(env),
+    ...DEFAULT_COMMON_EXECUTABLE_DIRECTORIES
+  ], env);
+  for (const directory of searchDirectories) {
+    const candidate = join10(directory, name);
+    if (isExecutablePath(candidate)) {
+      return { path: candidate, source: "path" };
+    }
+  }
+  return null;
+}
+var DEFAULT_COMMON_EXECUTABLE_DIRECTORIES;
+var init_tool_resolution = __esm(() => {
+  DEFAULT_COMMON_EXECUTABLE_DIRECTORIES = [
+    join10(homedir7(), ".bun", "bin"),
+    "/opt/homebrew/bin",
+    "/usr/local/bin"
+  ];
+});
+
+// ../runtime/src/broker-service.ts
+import { spawnSync } from "child_process";
+import { existsSync as existsSync8, mkdirSync as mkdirSync2, readFileSync as readFileSync3, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
+import { homedir as homedir8 } from "os";
+import { dirname as dirname6, join as join11, resolve as resolve7 } from "path";
+import { fileURLToPath as fileURLToPath5 } from "url";
 function isTmpPath(p) {
   return /^\/(?:private\/)?tmp\//.test(p);
 }
@@ -10320,17 +10829,17 @@ function runtimePackageDir() {
   const fromCwd = findWorkspaceRuntimeDir(process.cwd());
   if (fromCwd)
     return fromCwd;
-  const moduleDir = dirname5(fileURLToPath4(import.meta.url));
-  return resolve6(moduleDir, "..");
+  const moduleDir = dirname6(fileURLToPath5(import.meta.url));
+  return resolve7(moduleDir, "..");
 }
 function isInstalledRuntimePackageDir(candidate) {
-  return existsSync7(join10(candidate, "package.json")) && existsSync7(join10(candidate, "bin", "openscout-runtime.mjs"));
+  return existsSync8(join11(candidate, "package.json")) && existsSync8(join11(candidate, "bin", "openscout-runtime.mjs"));
 }
 function findGlobalRuntimeDir() {
   const candidates = [
-    join10(homedir7(), ".bun", "node_modules", "@openscout", "runtime"),
-    join10(homedir7(), ".bun", "install", "global", "node_modules", "@openscout", "runtime"),
-    join10(homedir7(), ".bun", "install", "global", "node_modules", "@openscout", "scout", "node_modules", "@openscout", "runtime")
+    join11(homedir8(), ".bun", "node_modules", "@openscout", "runtime"),
+    join11(homedir8(), ".bun", "install", "global", "node_modules", "@openscout", "runtime"),
+    join11(homedir8(), ".bun", "install", "global", "node_modules", "@openscout", "scout", "node_modules", "@openscout", "runtime")
   ];
   for (const c of candidates) {
     if (isInstalledRuntimePackageDir(c))
@@ -10340,11 +10849,11 @@ function findGlobalRuntimeDir() {
     const result = spawnSync("which", ["scout"], { encoding: "utf8", timeout: 3000 });
     const scoutBin = result.stdout?.trim();
     if (scoutBin) {
-      const scoutPkg = resolve6(scoutBin, "..", "..");
-      const nested = join10(scoutPkg, "node_modules", "@openscout", "runtime");
+      const scoutPkg = resolve7(scoutBin, "..", "..");
+      const nested = join11(scoutPkg, "node_modules", "@openscout", "runtime");
       if (isInstalledRuntimePackageDir(nested))
         return nested;
-      const sibling = resolve6(scoutPkg, "..", "runtime");
+      const sibling = resolve7(scoutPkg, "..", "runtime");
       if (isInstalledRuntimePackageDir(sibling))
         return sibling;
     }
@@ -10352,38 +10861,24 @@ function findGlobalRuntimeDir() {
   return null;
 }
 function findWorkspaceRuntimeDir(startDir) {
-  let current = resolve6(startDir);
+  let current = resolve7(startDir);
   while (true) {
-    const candidate = join10(current, "packages", "runtime");
-    if (existsSync7(join10(candidate, "package.json")) && existsSync7(join10(candidate, "src"))) {
+    const candidate = join11(current, "packages", "runtime");
+    if (existsSync8(join11(candidate, "package.json")) && existsSync8(join11(candidate, "src"))) {
       return candidate;
     }
-    const parent = dirname5(current);
+    const parent = dirname6(current);
     if (parent === current)
       return null;
     current = parent;
   }
 }
-function resolveBunExecutable2() {
-  const explicit = process.env.OPENSCOUT_BUN_BIN ?? process.env.BUN_BIN;
-  if (explicit && explicit.trim().length > 0) {
-    return explicit;
+function resolveBunExecutable3() {
+  const bun = resolveBunExecutable2(process.env);
+  if (bun) {
+    return bun.path;
   }
-  if (basename3(process.execPath).startsWith("bun") && existsSync7(process.execPath)) {
-    return process.execPath;
-  }
-  const pathEntries = (process.env.PATH ?? "").split(":").filter(Boolean);
-  for (const entry of pathEntries) {
-    const candidate = join10(entry, "bun");
-    if (existsSync7(candidate)) {
-      return candidate;
-    }
-  }
-  const homeBun = join10(homedir7(), ".bun", "bin", "bun");
-  if (existsSync7(homeBun)) {
-    return homeBun;
-  }
-  return "bun";
+  throw new Error("Unable to locate Bun for broker service management. Install Bun or set OPENSCOUT_BUN_BIN.");
 }
 function resolveBrokerServiceMode() {
   const explicit = (process.env.OPENSCOUT_BROKER_SERVICE_MODE ?? "").trim().toLowerCase();
@@ -10422,15 +10917,15 @@ function resolveBrokerServiceConfig() {
   const label = resolveBrokerServiceLabel(mode);
   const uid = typeof process.getuid === "function" ? process.getuid() : Number.parseInt(process.env.UID ?? "0", 10);
   const supportPaths = resolveOpenScoutSupportPaths();
-  const defaultSupportDir = join10(homedir7(), "Library", "Application Support", "OpenScout");
+  const defaultSupportDir = join11(homedir8(), "Library", "Application Support", "OpenScout");
   const supportDirectory = isTmpPath(supportPaths.supportDirectory) ? defaultSupportDir : supportPaths.supportDirectory;
-  const logsDirectory = join10(supportDirectory, "logs", "broker");
-  const controlHome = isTmpPath(supportPaths.controlHome) ? join10(homedir7(), ".openscout", "control-plane") : supportPaths.controlHome;
+  const logsDirectory = join11(supportDirectory, "logs", "broker");
+  const controlHome = isTmpPath(supportPaths.controlHome) ? join11(homedir8(), ".openscout", "control-plane") : supportPaths.controlHome;
   const advertiseScope = resolveAdvertiseScope();
   const brokerHost = resolveBrokerHost(advertiseScope);
   const brokerPort = Number.parseInt(process.env.OPENSCOUT_BROKER_PORT ?? String(DEFAULT_BROKER_PORT), 10);
   const brokerUrl = process.env.OPENSCOUT_BROKER_URL ?? buildDefaultBrokerUrl(brokerHost, brokerPort);
-  const launchAgentPath = join10(homedir7(), "Library", "LaunchAgents", `${label}.plist`);
+  const launchAgentPath = join11(homedir8(), "Library", "LaunchAgents", `${label}.plist`);
   return {
     label,
     mode,
@@ -10440,11 +10935,11 @@ function resolveBrokerServiceConfig() {
     launchAgentPath,
     supportDirectory,
     logsDirectory,
-    stdoutLogPath: join10(logsDirectory, "stdout.log"),
-    stderrLogPath: join10(logsDirectory, "stderr.log"),
+    stdoutLogPath: join11(logsDirectory, "stdout.log"),
+    stderrLogPath: join11(logsDirectory, "stderr.log"),
     controlHome,
     runtimePackageDir: runtimePackageDir(),
-    bunExecutable: resolveBunExecutable2(),
+    bunExecutable: resolveBunExecutable3(),
     brokerHost,
     brokerPort,
     brokerUrl,
@@ -10461,7 +10956,7 @@ function renderLaunchAgentPlist(config) {
     OPENSCOUT_BROKER_SERVICE_MODE: config.mode,
     OPENSCOUT_BROKER_SERVICE_LABEL: config.label,
     OPENSCOUT_ADVERTISE_SCOPE: config.advertiseScope,
-    HOME: homedir7(),
+    HOME: homedir8(),
     PATH: launchPath,
     ...collectOptionalEnvVars([
       "OPENSCOUT_MESH_ID",
@@ -10487,7 +10982,7 @@ function renderLaunchAgentPlist(config) {
   <key>ProgramArguments</key>
   <array>
     <string>${xmlEscape(config.bunExecutable)}</string>
-    <string>${xmlEscape(join10(config.runtimePackageDir, "bin", "openscout-runtime.mjs"))}</string>
+    <string>${xmlEscape(join11(config.runtimePackageDir, "bin", "openscout-runtime.mjs"))}</string>
     <string>broker</string>
   </array>
   <key>WorkingDirectory</key>
@@ -10522,7 +11017,7 @@ function collectOptionalEnvVars(keys) {
 }
 function resolveLaunchAgentPATH() {
   const entries = [
-    join10(homedir7(), ".bun", "bin"),
+    join11(homedir8(), ".bun", "bin"),
     ...(process.env.PATH ?? "").split(":").filter(Boolean),
     "/opt/homebrew/bin",
     "/usr/local/bin",
@@ -10537,7 +11032,7 @@ function xmlEscape(value) {
   return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
 }
 function ensureParentDirectory(filePath) {
-  mkdirSync2(dirname5(filePath), { recursive: true });
+  mkdirSync2(dirname6(filePath), { recursive: true });
 }
 function ensureServiceDirectories(config) {
   ensureOpenScoutCleanSlateSync();
@@ -10570,7 +11065,7 @@ function launchctlPath() {
   return "/bin/launchctl";
 }
 function readLogLines(path) {
-  if (!existsSync7(path)) {
+  if (!existsSync8(path)) {
     return [];
   }
   return readFileSync3(path, "utf8").split(`
@@ -10670,7 +11165,7 @@ async function brokerServiceStatus(config = resolveBrokerServiceConfig()) {
   ensureServiceDirectories(config);
   const launchctl = inspectLaunchctl(config);
   const health = await fetchHealthSnapshot(config);
-  const installed = existsSync7(config.launchAgentPath);
+  const installed = existsSync8(config.launchAgentPath);
   const lastLogLine = health.reachable ? readLastLogLine([config.stdoutLogPath, config.stderrLogPath]) : readLastLogLine([config.stderrLogPath, config.stdoutLogPath]);
   return {
     label: config.label,
@@ -10713,7 +11208,7 @@ async function startBrokerService(config = resolveBrokerServiceConfig()) {
   throw new Error(status.lastLogLine ?? status.health.error ?? "Broker service did not become healthy.");
 }
 function sleep(ms) {
-  return new Promise((resolve7) => setTimeout(resolve7, ms));
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
 async function stopBrokerService(config = resolveBrokerServiceConfig()) {
   runCommand(launchctlPath(), ["bootout", config.serviceTarget], { allowFailure: true });
@@ -10732,7 +11227,7 @@ async function restartBrokerService(config = resolveBrokerServiceConfig()) {
 }
 async function uninstallBrokerService(config = resolveBrokerServiceConfig()) {
   await stopBrokerService(config);
-  if (existsSync7(config.launchAgentPath)) {
+  if (existsSync8(config.launchAgentPath)) {
     rmSync2(config.launchAgentPath, { force: true });
   }
   return brokerServiceStatus(config);
@@ -10793,8 +11288,9 @@ function formatBrokerServiceStatus(status) {
 var DEFAULT_BROKER_HOST = "127.0.0.1", DEFAULT_BROKER_HOST_MESH = "0.0.0.0", DEFAULT_BROKER_PORT = 65535, DEFAULT_ADVERTISE_SCOPE = "local", BROKER_SERVICE_POLL_INTERVAL_MS = 100, DEFAULT_BROKER_START_TIMEOUT_MS = 15000, DEFAULT_BROKER_URL;
 var init_broker_service = __esm(async () => {
   init_support_paths();
+  init_tool_resolution();
   DEFAULT_BROKER_URL = buildDefaultBrokerUrl();
-  if (process.argv[1] && fileURLToPath4(import.meta.url) === process.argv[1] && !process.argv[1].endsWith("/main.mjs")) {
+  if (process.argv[1] && fileURLToPath5(import.meta.url) === process.argv[1] && !process.argv[1].endsWith("/main.mjs")) {
     await main();
   }
 });
@@ -10811,27 +11307,27 @@ var init_local_agent_template = __esm(() => {
 
 // ../runtime/src/local-agents.ts
 import { execFileSync as execFileSync3, execSync } from "child_process";
-import { existsSync as existsSync8, readFileSync as readFileSync4 } from "fs";
+import { existsSync as existsSync9, readFileSync as readFileSync4 } from "fs";
 import { mkdir as mkdir6, rm as rm5, stat as stat3, writeFile as writeFile6 } from "fs/promises";
-import { basename as basename4, dirname as dirname6, join as join11, resolve as resolve7 } from "path";
-import { fileURLToPath as fileURLToPath5 } from "url";
+import { basename as basename5, dirname as dirname7, join as join12, resolve as resolve8 } from "path";
+import { fileURLToPath as fileURLToPath6 } from "url";
 function resolveRelayHub() {
   return resolveOpenScoutSupportPaths().relayHubDirectory;
 }
 function resolveProjectsRoot(projectPath) {
   if (process.env.OPENSCOUT_PROJECTS_ROOT?.trim()) {
-    return resolve7(process.env.OPENSCOUT_PROJECTS_ROOT.trim());
+    return resolve8(process.env.OPENSCOUT_PROJECTS_ROOT.trim());
   }
   try {
     const supportPaths = resolveOpenScoutSupportPaths();
-    if (!existsSync8(supportPaths.settingsPath)) {
-      return dirname6(projectPath);
+    if (!existsSync9(supportPaths.settingsPath)) {
+      return dirname7(projectPath);
     }
     const raw = JSON.parse(readFileSync4(supportPaths.settingsPath, "utf8"));
     const workspaceRoot = raw.discovery?.workspaceRoots?.find((entry) => typeof entry === "string" && entry.trim().length > 0);
-    return workspaceRoot ? resolve7(workspaceRoot) : dirname6(projectPath);
+    return workspaceRoot ? resolve8(workspaceRoot) : dirname7(projectPath);
   } catch {
-    return dirname6(projectPath);
+    return dirname7(projectPath);
   }
 }
 function resolveBrokerUrl() {
@@ -10841,7 +11337,7 @@ function nowSeconds2() {
   return Math.floor(Date.now() / 1000);
 }
 function scoutCliPath() {
-  return join11(OPENSCOUT_REPO_ROOT, "packages", "cli", "bin", "scout.mjs");
+  return join12(OPENSCOUT_REPO_ROOT, "packages", "cli", "bin", "scout.mjs");
 }
 function legacyNodeBrokerRelayCommand() {
   return `node ${JSON.stringify(scoutCliPath())}`;
@@ -10854,13 +11350,13 @@ function titleCaseLocalAgentName(value) {
 }
 function resolveScoutSkillPath() {
   const candidatePaths = [
-    join11(OPENSCOUT_REPO_ROOT, ".agents", "skills", "scout", "SKILL.md"),
-    join11(process.env.HOME ?? "", ".agents", "skills", "scout", "SKILL.md"),
-    join11(OPENSCOUT_REPO_ROOT, ".agents", "skills", "relay-agent-comms", "SKILL.md"),
-    join11(process.env.HOME ?? "", ".agents", "skills", "relay-agent-comms", "SKILL.md")
+    join12(OPENSCOUT_REPO_ROOT, ".agents", "skills", "scout", "SKILL.md"),
+    join12(process.env.HOME ?? "", ".agents", "skills", "scout", "SKILL.md"),
+    join12(OPENSCOUT_REPO_ROOT, ".agents", "skills", "relay-agent-comms", "SKILL.md"),
+    join12(process.env.HOME ?? "", ".agents", "skills", "relay-agent-comms", "SKILL.md")
   ];
   for (const path of candidatePaths) {
-    if (existsSync8(path)) {
+    if (existsSync9(path)) {
       return path;
     }
   }
@@ -10911,7 +11407,7 @@ function buildLocalAgentCollaborationPrompt(context) {
 function buildLocalAgentTmuxProtocolPrompt(context) {
   return [
     "Relay protocol:",
-    `  - Read recent context with: ${context.relayCommand} read --as ${context.agentId}`,
+    `  - Read recent context when needed with: ${context.relayCommand} latest --agent ${context.agentId} --limit 20`,
     `  - Tell one agent with: ${context.relayCommand} send --as ${context.agentId} "@<agent> your message"`,
     `  - Ask one agent and stay attached with: ${context.relayCommand} ask --to <agent> --as ${context.agentId} "your request"`,
     "",
@@ -10923,9 +11419,10 @@ function buildLocalAgentTmuxProtocolPrompt(context) {
     "  - If you need multiple agents, use separate DMs or an explicit channel; do not guess a venue from multiple mentions",
     "  - Do not use channel.shared for ordinary delegation or follow-up; reserve it for explicit group updates or broadcasts",
     "  - If a short @handle may be ambiguous, resolve the exact target before sending; do not guess and do not fall back to shared",
+    "  - Treat known offline / on-demand agents as wakeable: use send or ask first and let the broker wake them; only surface ambiguity or unknown-target failures to the operator",
     "  - Use send for tells and status; use ask when the meaning is 'do this and get back to me'",
     "  - When replying to an [ask:<id>] request, include the same [ask:<id>] tag in your reply",
-    "  - Use the broker-backed relay read command above to inspect recent context before responding",
+    "  - Use the broker-backed latest command above only when recent context is needed before responding",
     `  - Follow the scout skill at ${context.scoutSkill} for agent-to-agent communication`
   ].join(`
 `);
@@ -10936,7 +11433,7 @@ function buildLocalAgentDirectProtocolPrompt(context) {
     "  - You are invoked directly by the OpenScout broker",
     "  - Return your final answer in the assistant message for the current turn",
     "  - Do not shell out to send the final answer through relay yourself",
-    `  - If you need recent relay context, inspect it with: ${context.relayCommand} read --as ${context.agentId}`,
+    `  - If you need recent broker context, inspect it with: ${context.relayCommand} latest --agent ${context.agentId} --limit 20`,
     `  - If you need to tell one agent something, use: ${context.relayCommand} send --as ${context.agentId} "@<agent> your message"`,
     `  - If you need another agent to do work, use: ${context.relayCommand} ask --to <agent> --as ${context.agentId} "your request"`,
     "  - Default Scout loop: resolve identity, resolve one target, choose DM vs explicit channel, keep follow-up in that same venue",
@@ -10944,6 +11441,7 @@ function buildLocalAgentDirectProtocolPrompt(context) {
     "  - If you need multiple agents, use separate DMs or an explicit channel; do not guess a venue from multiple mentions",
     "  - Do not use channel.shared for ordinary delegation or follow-up; reserve it for explicit group updates or broadcasts",
     "  - If a short @handle may be ambiguous, resolve the exact target before sending; do not guess and do not fall back to shared",
+    "  - Treat known offline / on-demand agents as wakeable: use send or ask first and let the broker wake them; only surface ambiguity or unknown-target failures to the operator",
     "  - Use send for tells and status; use ask when the meaning is 'do this and get back to me'",
     `  - Follow the scout skill at ${context.scoutSkill} for agent-to-agent communication`
   ].join(`
@@ -11006,7 +11504,7 @@ function buildLegacySimpleRelayPrompt(agentId, projectName, projectPath, relayCo
     "A primary agent may call into you for context, execution, follow-through, and handoff.",
     "",
     `You have full access to the codebase at ${projectPath}.`,
-    `There is a structured relay event stream at ${join11(relayHub, "channel.jsonl")} shared by all agents.`,
+    `There is a structured relay event stream at ${join12(relayHub, "channel.jsonl")} shared by all agents.`,
     "",
     "Your job:",
     `  - Respond to @${agentId} mentions from other agents`,
@@ -11110,17 +11608,17 @@ async function writeLocalAgentRegistry(registry) {
   }
   await writeRelayAgentOverrides(nextOverrides);
 }
-function expandHomePath3(value) {
+function expandHomePath4(value) {
   if (value === "~") {
     return process.env.HOME ?? process.cwd();
   }
   if (value.startsWith("~/")) {
-    return join11(process.env.HOME ?? process.cwd(), value.slice(2));
+    return join12(process.env.HOME ?? process.cwd(), value.slice(2));
   }
   return value;
 }
 function normalizeProjectPath(value) {
-  return resolve7(expandHomePath3(value.trim() || "."));
+  return resolve8(expandHomePath4(value.trim() || "."));
 }
 function normalizeTmuxSessionName2(value, agentId) {
   const fallback = `relay-${agentId}`;
@@ -11383,7 +11881,7 @@ function recordForHarness(record, harnessOverride) {
 function normalizeLocalAgentRecord(agentId, record) {
   const cwd = normalizeProjectPath(record.cwd || process.cwd());
   const projectRoot = normalizeProjectPath(record.projectRoot || cwd);
-  const project = record.project?.trim() || basename4(projectRoot);
+  const project = record.project?.trim() || basename5(projectRoot);
   const definitionId = record.definitionId?.trim() || agentId;
   const defaultHarness = activeLocalHarness(record);
   const harnessProfiles = normalizeLocalHarnessProfiles(agentId, {
@@ -11448,7 +11946,7 @@ function localAgentRecordFromResolvedConfig(config) {
 function localAgentRecordFromRelayAgentOverride(agentId, override) {
   return normalizeLocalAgentRecord(agentId, {
     definitionId: override.definitionId ?? agentId,
-    project: override.projectName ?? basename4(override.projectRoot || override.runtime?.cwd || agentId),
+    project: override.projectName ?? basename5(override.projectRoot || override.runtime?.cwd || agentId),
     projectRoot: override.projectRoot ?? override.runtime?.cwd,
     tmuxSession: override.runtime?.sessionId ?? `relay-${agentId}`,
     cwd: override.runtime?.cwd ?? override.projectRoot,
@@ -11544,7 +12042,7 @@ function buildLocalAgentBootstrapPrompt(_harness, _systemPrompt, initialMessage)
 function buildLocalAgentLaunchCommand(agentName, record, projectPath, promptFile, workerScript) {
   const extraArgs = shellQuoteArguments(normalizeLaunchArgsForHarness(normalizeLocalAgentHarness(record.harness), record.launchArgs));
   if (normalizeLocalAgentHarness(record.harness) === "codex") {
-    return `exec bash ${JSON.stringify(workerScript ?? join11(relayAgentRuntimeDirectory(agentName), "codex-worker.sh"))}`;
+    return `exec bash ${JSON.stringify(workerScript ?? join12(relayAgentRuntimeDirectory(agentName), "codex-worker.sh"))}`;
   }
   return [
     "claude",
@@ -11590,7 +12088,7 @@ async function ensureLocalAgentOnline(agentName, record) {
     return normalizedRecord;
   }
   const projectPath = normalizedRecord.cwd;
-  const projectName = normalizedRecord.project || basename4(projectPath);
+  const projectName = normalizedRecord.project || basename5(projectPath);
   const systemPromptTemplate = normalizedRecord.systemPrompt || buildLocalAgentSystemPromptTemplate();
   const systemPrompt = renderLocalAgentSystemPromptTemplate(systemPromptTemplate, buildLocalAgentTemplateContext(agentName, projectName, projectPath), { transport: normalizedRecord.transport });
   const agentRuntimeDir = relayAgentRuntimeDirectory(agentName);
@@ -11598,7 +12096,7 @@ async function ensureLocalAgentOnline(agentName, record) {
   await mkdir6(agentRuntimeDir, { recursive: true });
   await mkdir6(logsDir, { recursive: true });
   if (normalizedRecord.transport === "codex_app_server") {
-    await writeFile6(join11(agentRuntimeDir, "prompt.txt"), systemPrompt);
+    await writeFile6(join12(agentRuntimeDir, "prompt.txt"), systemPrompt);
     await ensureCodexAppServerAgentOnline(buildCodexAgentSessionOptions(agentName, normalizedRecord, systemPrompt));
     const registry2 = await readLocalAgentRegistry();
     registry2[agentName] = {
@@ -11610,7 +12108,7 @@ async function ensureLocalAgentOnline(agentName, record) {
     return registry2[agentName];
   }
   if (normalizedRecord.transport === "claude_stream_json") {
-    await writeFile6(join11(agentRuntimeDir, "prompt.txt"), systemPrompt);
+    await writeFile6(join12(agentRuntimeDir, "prompt.txt"), systemPrompt);
     await ensureClaudeStreamJsonAgentOnline(buildClaudeAgentSessionOptions(agentName, normalizedRecord, systemPrompt));
     const registry2 = await readLocalAgentRegistry();
     registry2[agentName] = {
@@ -11623,17 +12121,17 @@ async function ensureLocalAgentOnline(agentName, record) {
   }
   const initialMessage = buildLocalAgentInitialMessage(projectName, agentName);
   const bootstrapPrompt = buildLocalAgentBootstrapPrompt(normalizeLocalAgentHarness(normalizedRecord.harness), systemPrompt, initialMessage);
-  const queueDirectory = join11(agentRuntimeDir, "queue");
-  const processingDirectory = join11(queueDirectory, "processing");
-  const processedDirectory = join11(queueDirectory, "processed");
-  const promptFile = join11(agentRuntimeDir, "prompt.txt");
-  const initialFile = join11(agentRuntimeDir, "initial.txt");
-  const launchScript = join11(agentRuntimeDir, "launch.sh");
-  const workerScript = join11(agentRuntimeDir, "codex-worker.sh");
-  const codexSessionIdFile = join11(agentRuntimeDir, "codex-session-id.txt");
-  const stateFile = join11(agentRuntimeDir, "state.json");
-  const stdoutLogFile = join11(logsDir, "stdout.log");
-  const stderrLogFile = join11(logsDir, "stderr.log");
+  const queueDirectory = join12(agentRuntimeDir, "queue");
+  const processingDirectory = join12(queueDirectory, "processing");
+  const processedDirectory = join12(queueDirectory, "processed");
+  const promptFile = join12(agentRuntimeDir, "prompt.txt");
+  const initialFile = join12(agentRuntimeDir, "initial.txt");
+  const launchScript = join12(agentRuntimeDir, "launch.sh");
+  const workerScript = join12(agentRuntimeDir, "codex-worker.sh");
+  const codexSessionIdFile = join12(agentRuntimeDir, "codex-session-id.txt");
+  const stateFile = join12(agentRuntimeDir, "state.json");
+  const stdoutLogFile = join12(logsDir, "stdout.log");
+  const stderrLogFile = join12(logsDir, "stderr.log");
   await writeFile6(promptFile, systemPrompt);
   await writeFile6(initialFile, bootstrapPrompt);
   await writeFile6(stderrLogFile, "");
@@ -11695,10 +12193,10 @@ async function ensureLocalAgentOnline(agentName, record) {
     if (isLocalAgentSessionAlive(normalizedRecord.tmuxSession)) {
       break;
     }
-    await new Promise((resolve8) => setTimeout(resolve8, 100));
+    await new Promise((resolve9) => setTimeout(resolve9, 100));
   }
   if (!isLocalAgentSessionAlive(normalizedRecord.tmuxSession)) {
-    const stderrTail = existsSync8(stderrLogFile) ? readFileSync4(stderrLogFile, "utf8").trim().split(/\r?\n/).slice(-10).join(`
+    const stderrTail = existsSync9(stderrLogFile) ? readFileSync4(stderrLogFile, "utf8").trim().split(/\r?\n/).slice(-10).join(`
 `).trim() : "";
     throw new Error(stderrTail ? `Relay agent ${agentName} failed to stay online:
 ${stderrTail}` : `Relay agent ${agentName} failed to stay online.`);
@@ -11748,19 +12246,42 @@ async function restartLocalAgent(agentId, options = {}) {
   }
   return ensureLocalAgentOnline(agentId, normalizedRecord);
 }
-async function resolveLocalAgentByName(name) {
+function resolvedAgentNameFromOverride(agentId, override) {
+  return {
+    agentId,
+    definitionId: override.definitionId ?? agentId,
+    projectRoot: override.projectRoot
+  };
+}
+async function resolveLocalAgentByName(name, options = {}) {
   const normalized = normalizeAgentSelectorSegment(name);
   if (!normalized)
     return null;
   const overrides = await readRelayAgentOverrides();
-  for (const [id, override] of Object.entries(overrides)) {
-    if (BUILT_IN_AGENT_DEFINITION_IDS.has(id))
-      continue;
-    const defId = override.definitionId ?? id;
-    if (defId === normalized || normalizeAgentSelectorSegment(override.projectName ?? "") === normalized) {
-      return { agentId: id, definitionId: defId, projectRoot: override.projectRoot };
+  const entries = Object.entries(overrides).filter(([agentId]) => !BUILT_IN_AGENT_DEFINITION_IDS.has(agentId));
+  const exactAgentIdMatch = entries.find(([agentId]) => normalizeAgentSelectorSegment(agentId) === normalized);
+  if (exactAgentIdMatch) {
+    return resolvedAgentNameFromOverride(exactAgentIdMatch[0], exactAgentIdMatch[1]);
+  }
+  const definitionMatches = entries.filter(([agentId, override]) => (override.definitionId ?? agentId) === normalized);
+  if (definitionMatches.length === 1) {
+    const [agentId, override] = definitionMatches[0];
+    return resolvedAgentNameFromOverride(agentId, override);
+  }
+  if (definitionMatches.length > 1) {
+    const preferredMatch = definitionMatches.find(([agentId]) => /\.(main|master)\./.test(agentId)) ?? definitionMatches[0];
+    if (preferredMatch) {
+      return resolvedAgentNameFromOverride(preferredMatch[0], preferredMatch[1]);
     }
   }
+  if (!options.matchProjectName) {
+    return null;
+  }
+  const projectMatches = entries.filter(([, override]) => normalizeAgentSelectorSegment(override.projectName ?? "") === normalized);
+  if (projectMatches.length === 1) {
+    const [agentId, override] = projectMatches[0];
+    return resolvedAgentNameFromOverride(agentId, override);
+  }
   return null;
 }
 async function listLocalAgents(options = {}) {
@@ -11812,7 +12333,7 @@ async function resolveLocalAgentIdentity(input) {
       nodeQualifier: instance2.nodeQualifier,
       harness: normalizeManagedHarness2(preferredHarness ?? override.defaultHarness, "claude"),
       projectRoot: normalizeProjectPath(override.projectRoot),
-      projectName: override.projectName ?? basename4(override.projectRoot),
+      projectName: override.projectName ?? basename5(override.projectRoot),
       source: "existing"
     };
   }
@@ -11831,12 +12352,12 @@ async function resolveLocalAgentIdentity(input) {
       nodeQualifier: instance2.nodeQualifier,
       harness: normalizeManagedHarness2(preferredHarness ?? override.defaultHarness, "claude"),
       projectRoot: normalizeProjectPath(override.projectRoot),
-      projectName: override.projectName ?? basename4(override.projectRoot),
+      projectName: override.projectName ?? basename5(override.projectRoot),
       source: "existing"
     };
   }
   const configDefinitionId = config?.agent?.id?.trim() ? normalizeAgentSelectorSegment(config.agent.id.trim()) : "";
-  const definitionId = requestedDefinitionId || configDefinitionId || normalizeAgentSelectorSegment(basename4(projectRoot)) || "agent";
+  const definitionId = requestedDefinitionId || configDefinitionId || normalizeAgentSelectorSegment(basename5(projectRoot)) || "agent";
   const configDisplayName = config?.agent?.displayName?.trim() || "";
   const displayName = input.displayName || configDisplayName || titleCaseLocalAgentName(definitionId);
   const instance = buildRelayAgentInstance(definitionId, projectRoot);
@@ -11850,7 +12371,7 @@ async function resolveLocalAgentIdentity(input) {
     nodeQualifier: instance.nodeQualifier,
     harness: effectiveHarness,
     projectRoot,
-    projectName: basename4(projectRoot),
+    projectName: basename5(projectRoot),
     source: configDefinitionId || configDisplayName ? "config" : "new"
   };
 }
@@ -11859,6 +12380,7 @@ async function startLocalAgent(input) {
   const preferredHarness = input.harness ? normalizeLocalAgentHarness(input.harness) : undefined;
   const currentDirectory = input.currentDirectory ?? projectPath;
   const effectiveCwd = input.cwdOverride ? normalizeProjectPath(input.cwdOverride) : undefined;
+  const shouldEnsureOnline = input.ensureOnline !== false;
   const requestedDefinitionId = input.agentName?.trim() ? normalizeAgentSelectorSegment(input.agentName.trim()) : "";
   if (input.agentName?.trim() && !requestedDefinitionId) {
     throw new Error(`Invalid agent name "${input.agentName}".`);
@@ -11906,7 +12428,7 @@ async function startLocalAgent(input) {
   }
   if (!matchingOverride) {
     const configDefinitionId = coldProjectConfig?.agent?.id?.trim() ? normalizeAgentSelectorSegment(coldProjectConfig.agent.id.trim()) : "";
-    const definitionId = requestedDefinitionId || configDefinitionId || normalizeAgentSelectorSegment(basename4(projectRoot)) || "agent";
+    const definitionId = requestedDefinitionId || configDefinitionId || normalizeAgentSelectorSegment(basename5(projectRoot)) || "agent";
     const configDisplayName = coldProjectConfig?.agent?.displayName?.trim() || "";
     const effectiveDisplayName = input.displayName || configDisplayName || titleCaseLocalAgentName(definitionId);
     const instance = buildRelayAgentInstance(definitionId, projectRoot);
@@ -11923,7 +12445,7 @@ async function startLocalAgent(input) {
       agentId: instance.id,
       definitionId,
       displayName: effectiveDisplayName,
-      projectName: basename4(projectRoot),
+      projectName: basename5(projectRoot),
       projectRoot,
       projectConfigPath: coldProjectConfigPath,
       source: "manual",
@@ -11963,7 +12485,7 @@ async function startLocalAgent(input) {
       agentId: instance.id,
       definitionId: requestedDefinitionId,
       displayName: input.displayName || titleCaseLocalAgentName(requestedDefinitionId),
-      projectName: matchingOverride.projectName ?? basename4(matchingProjectRoot),
+      projectName: matchingOverride.projectName ?? basename5(matchingProjectRoot),
       projectRoot: matchingProjectRoot,
       projectConfigPath: matchingOverride.projectConfigPath ?? null,
       source: "manual",
@@ -12008,12 +12530,14 @@ async function startLocalAgent(input) {
     }
     targetAgentId = matchingAgentId;
   }
-  await ensureLocalAgentBindingOnline(targetAgentId, process.env.OPENSCOUT_NODE_ID ?? "local", {
-    includeDiscovered: false,
-    currentDirectory,
-    ensureCurrentProjectConfig: false,
-    harness: preferredHarness
-  });
+  if (shouldEnsureOnline) {
+    await ensureLocalAgentBindingOnline(targetAgentId, process.env.OPENSCOUT_NODE_ID ?? "local", {
+      includeDiscovered: false,
+      currentDirectory,
+      ensureCurrentProjectConfig: false,
+      harness: preferredHarness
+    });
+  }
   const finalOverrides = await readRelayAgentOverrides();
   const finalOverride = finalOverrides[targetAgentId];
   if (!finalOverride) {
@@ -12096,8 +12620,8 @@ async function restartAllLocalAgents(options = {}) {
 function readPersistedClaudeSessionId(agentName) {
   try {
     const runtimeDir = relayAgentRuntimeDirectory(agentName);
-    const catalogPath = join11(runtimeDir, "session-catalog.json");
-    if (existsSync8(catalogPath)) {
+    const catalogPath = join12(runtimeDir, "session-catalog.json");
+    if (existsSync9(catalogPath)) {
       const raw = readFileSync4(catalogPath, "utf8").trim();
       if (raw) {
         const catalog = JSON.parse(raw);
@@ -12106,8 +12630,8 @@ function readPersistedClaudeSessionId(agentName) {
         }
       }
     }
-    const legacyPath = join11(runtimeDir, "claude-session-id.txt");
-    if (existsSync8(legacyPath)) {
+    const legacyPath = join12(runtimeDir, "claude-session-id.txt");
+    if (existsSync9(legacyPath)) {
       const value = readFileSync4(legacyPath, "utf8").trim();
       return value || null;
     }
@@ -12295,22 +12819,22 @@ var init_local_agents = __esm(async () => {
   init_support_paths();
   init_local_agent_template();
   await init_broker_service();
-  MODULE_DIRECTORY = dirname6(fileURLToPath5(import.meta.url));
-  OPENSCOUT_REPO_ROOT = resolve7(MODULE_DIRECTORY, "..", "..", "..");
+  MODULE_DIRECTORY = dirname7(fileURLToPath6(import.meta.url));
+  OPENSCOUT_REPO_ROOT = resolve8(MODULE_DIRECTORY, "..", "..", "..");
   DEFAULT_LOCAL_AGENT_CAPABILITIES = ["chat", "invoke", "deliver"];
   SUPPORTED_LOCAL_AGENT_HARNESSES = ["claude", "codex"];
 });
 
 // ../runtime/src/user-config.ts
-import { existsSync as existsSync9, readFileSync as readFileSync5, writeFileSync as writeFileSync3, mkdirSync as mkdirSync3 } from "fs";
-import { homedir as homedir8 } from "os";
-import { dirname as dirname7, join as join12 } from "path";
+import { existsSync as existsSync10, readFileSync as readFileSync5, writeFileSync as writeFileSync3, mkdirSync as mkdirSync3 } from "fs";
+import { homedir as homedir9 } from "os";
+import { dirname as dirname8, join as join13 } from "path";
 function userConfigPath() {
-  return join12(process.env.OPENSCOUT_HOME ?? join12(homedir8(), ".openscout"), "user.json");
+  return join13(process.env.OPENSCOUT_HOME ?? join13(homedir9(), ".openscout"), "user.json");
 }
 function loadUserConfig() {
   const configPath = userConfigPath();
-  if (!existsSync9(configPath))
+  if (!existsSync10(configPath))
     return {};
   try {
     return JSON.parse(readFileSync5(configPath, "utf8"));
@@ -12320,7 +12844,7 @@ function loadUserConfig() {
 }
 function saveUserConfig(config) {
   const configPath = userConfigPath();
-  mkdirSync3(dirname7(configPath), { recursive: true });
+  mkdirSync3(dirname8(configPath), { recursive: true });
   writeFileSync3(configPath, JSON.stringify(config, null, 2) + `
 `, "utf8");
 }
@@ -12350,6 +12874,7 @@ var init_paths = __esm(() => {
       endpoints: "/v1/endpoints",
       conversations: "/v1/conversations",
       invocations: "/v1/invocations",
+      deliver: "/v1/deliver",
       activity: "/v1/activity",
       collaborationRecords: "/v1/collaboration/records",
       collaborationEvents: "/v1/collaboration/events"
@@ -12358,8 +12883,8 @@ var init_paths = __esm(() => {
 });
 
 // ../../apps/desktop/src/core/broker/service.ts
-import { mkdir as mkdir7, readFile as readFile7, unlink, writeFile as writeFile7 } from "fs/promises";
-import { basename as basename5, join as join13, resolve as resolve8 } from "path";
+import { mkdir as mkdir7, readFile as readFile8, unlink, writeFile as writeFile7 } from "fs/promises";
+import { basename as basename6, join as join14, resolve as resolve9 } from "path";
 function buildScoutBrokerUrlFromEnv() {
   const host = process.env.OPENSCOUT_BROKER_HOST ?? DEFAULT_BROKER_HOST2;
   const port = Number.parseInt(process.env.OPENSCOUT_BROKER_PORT ?? String(DEFAULT_BROKER_PORT2), 10);
@@ -12385,7 +12910,8 @@ function resolveScoutAgentName(agentName) {
   }
   return resolveOperatorName();
 }
-function resolveConfiguredSenderIdForProjectRoot(overrides, projectRoot) {
+function resolveConfiguredSenderIdForProjectRoot(overrides, projectRoot, preferredDefinitionId) {
+  let fallbackSenderId = null;
   for (const [agentId, override] of Object.entries(overrides)) {
     if (BUILT_IN_AGENT_DEFINITION_IDS.has(agentId)) {
       continue;
@@ -12393,19 +12919,22 @@ function resolveConfiguredSenderIdForProjectRoot(overrides, projectRoot) {
     if (!override.projectRoot || override.projectRoot !== projectRoot) {
       continue;
     }
-    return agentId;
+    if (preferredDefinitionId && override.definitionId === preferredDefinitionId) {
+      return agentId;
+    }
+    fallbackSenderId ??= agentId;
   }
-  return null;
+  return fallbackSenderId;
 }
 async function inferSenderIdForProjectRoot(projectRoot) {
   const overrides = await readRelayAgentOverrides();
-  const configuredSenderId = resolveConfiguredSenderIdForProjectRoot(overrides, projectRoot);
+  const projectConfig = await readProjectConfig(projectRoot);
+  const configuredDefinitionId = normalizeAgentSelectorSegment(projectConfig?.agent?.id?.trim() ?? "");
+  const configuredSenderId = resolveConfiguredSenderIdForProjectRoot(overrides, projectRoot, configuredDefinitionId);
   if (configuredSenderId) {
     return configuredSenderId;
   }
-  const projectConfig = await readProjectConfig(projectRoot);
-  const configuredDefinitionId = normalizeAgentSelectorSegment(projectConfig?.agent?.id?.trim() ?? "");
-  const definitionId = configuredDefinitionId || normalizeAgentSelectorSegment(basename5(projectRoot)) || "agent";
+  const definitionId = configuredDefinitionId || normalizeAgentSelectorSegment(basename6(projectRoot)) || "agent";
   return buildRelayAgentInstance(definitionId, projectRoot).id;
 }
 async function resolveScoutSenderId(agentName, currentDirectory, env = process.env) {
@@ -12523,6 +13052,51 @@ async function brokerPostJson(baseUrl, path, body) {
   }
   return response.json();
 }
+function renderScoutTargetLabel(targetLabel) {
+  const trimmed = targetLabel.trim();
+  if (!trimmed) {
+    return "";
+  }
+  return trimmed.startsWith("@") ? trimmed : `@${trimmed}`;
+}
+function scoutTargetDiagnosticFromDeliveryFailure(delivery) {
+  const dispatch = delivery.kind === "question" ? delivery.question : delivery.rejection;
+  if (dispatch.kind === "ambiguous") {
+    return {
+      state: "ambiguous",
+      candidates: dispatch.candidates.map((candidate) => ({
+        agentId: candidate.agentId,
+        label: candidate.label
+      }))
+    };
+  }
+  if (dispatch.kind === "unavailable" && dispatch.target) {
+    return {
+      agentId: dispatch.target.agentId,
+      state: "unavailable",
+      detail: dispatch.target.detail,
+      wakePolicy: dispatch.target.wakePolicy ?? null,
+      transport: dispatch.target.transport ?? null,
+      projectRoot: dispatch.target.projectRoot ?? null
+    };
+  }
+  if (dispatch.kind === "unknown") {
+    return {
+      agentId: dispatch.askedLabel,
+      state: "unknown",
+      registrationKind: null,
+      projectRoot: null
+    };
+  }
+  if (delivery.kind === "rejected" && dispatch.kind === "unparseable") {
+    return {
+      state: delivery.reason === "missing_target" ? "missing" : "invalid",
+      askedLabel: dispatch.askedLabel,
+      detail: dispatch.detail
+    };
+  }
+  return;
+}
 async function readScoutBrokerHealth(baseUrl = resolveScoutBrokerUrl()) {
   try {
     const health = await brokerReadJson(baseUrl, scoutBrokerPaths.health);
@@ -12616,84 +13190,6 @@ function formatBrokerTargetLabel(snapshot, agentId) {
   const candidate = buildMentionCandidate(snapshot, current);
   return formatMinimalAgentIdentity(candidate, candidates);
 }
-function normalizeProjectLocalResolutionValue(value) {
-  return value?.trim().toLowerCase().replace(/^@+/, "") ?? "";
-}
-function matchesObviousProjectLocalAlias(value, query) {
-  const normalized = normalizeProjectLocalResolutionValue(value);
-  if (!normalized || !query) {
-    return false;
-  }
-  return normalized === query || normalized.startsWith(`${query}-`) || normalized.startsWith(`${query}.`) || normalized.startsWith(`${query}_`) || normalized.startsWith(`${query} `);
-}
-function agentProjectRoot(snapshot, agentId) {
-  const endpoints = Object.values(snapshot.endpoints).filter((endpoint) => endpoint.agentId === agentId);
-  const preferred = endpoints.find((endpoint) => endpoint.state === "active") ?? endpoints.find((endpoint) => endpoint.state === "idle" || endpoint.state === "waiting") ?? endpoints[0];
-  return preferred?.projectRoot ?? preferred?.cwd ?? metadataString2(snapshot.agents[agentId]?.metadata, "projectRoot") ?? null;
-}
-function agentPreferredState(snapshot, agentId) {
-  const endpoints = Object.values(snapshot.endpoints).filter((endpoint) => endpoint.agentId === agentId);
-  const preferred = endpoints.find((endpoint) => endpoint.state === "active") ?? endpoints.find((endpoint) => endpoint.state === "idle" || endpoint.state === "waiting") ?? endpoints[0];
-  return preferred?.state ?? "offline";
-}
-function scoreProjectLocalBrokerAgent(snapshot, agentId, currentProjectRoot, query) {
-  const projectRoot = agentProjectRoot(snapshot, agentId);
-  if (!projectRoot || resolve8(projectRoot) !== resolve8(currentProjectRoot)) {
-    return -1;
-  }
-  const agent = snapshot.agents[agentId];
-  const formattedLabel = formatBrokerTargetLabel(snapshot, agentId);
-  const values = [
-    formattedLabel,
-    agent?.defaultSelector,
-    agent?.selector,
-    agent?.handle,
-    agent?.displayName,
-    agent?.definitionId,
-    agentId
-  ];
-  const matches = values.filter((value) => matchesObviousProjectLocalAlias(value, query));
-  if (matches.length === 0) {
-    return -1;
-  }
-  return 1000 + whoStateRank(agentPreferredState(snapshot, agentId)) * 20;
-}
-async function findPreferredProjectLocalBrokerTarget(snapshot, label, currentDirectory) {
-  const query = normalizeProjectLocalResolutionValue(label);
-  if (!query) {
-    return null;
-  }
-  const currentProjectRoot = await findNearestProjectRoot(currentDirectory) ?? currentDirectory;
-  const scored = Object.values(snapshot.agents).filter((agent) => agent.id !== OPERATOR_ID).filter((agent) => !isSupersededBrokerAgent(snapshot, agent.id)).map((agent) => ({
-    agentId: agent.id,
-    score: scoreProjectLocalBrokerAgent(snapshot, agent.id, currentProjectRoot, query)
-  })).filter((entry) => entry.score >= 0).sort((left, right) => {
-    const scoreDelta = right.score - left.score;
-    if (scoreDelta !== 0)
-      return scoreDelta;
-    return left.agentId.localeCompare(right.agentId);
-  });
-  if (scored.length === 0) {
-    return null;
-  }
-  if (scored.length > 1 && scored[0]?.score === scored[1]?.score) {
-    return null;
-  }
-  const agentId = scored[0]?.agentId;
-  if (!agentId) {
-    return null;
-  }
-  const resolvedLabel = formatBrokerTargetLabel(snapshot, agentId);
-  const selector = extractAgentSelectors(resolvedLabel)[0];
-  if (!selector) {
-    return null;
-  }
-  return {
-    agentId,
-    label: resolvedLabel,
-    selector
-  };
-}
 async function resolveMentionTargets(snapshot, text, currentDirectory) {
   const mentions = extractAgentMentions(text);
   const selectors = mentions.parsed;
@@ -12764,55 +13260,6 @@ async function resolveMentionTargets(snapshot, text, currentDirectory) {
     ambiguous
   };
 }
-async function resolveSingleBrokerTarget(snapshot, label, currentDirectory) {
-  const normalized = label.trim();
-  if (!normalized) {
-    return { kind: "unresolved" };
-  }
-  const resolution = await resolveMentionTargets(snapshot, normalized.startsWith("@") ? normalized : `@${normalized}`, currentDirectory);
-  const preferredProjectLocalTarget = await findPreferredProjectLocalBrokerTarget(snapshot, normalized, currentDirectory);
-  if (preferredProjectLocalTarget) {
-    return { kind: "resolved", target: preferredProjectLocalTarget };
-  }
-  const firstAmbiguous = resolution.ambiguous[0];
-  if (firstAmbiguous) {
-    return { kind: "ambiguous", candidates: firstAmbiguous.candidates };
-  }
-  const first = resolution.resolved[0];
-  if (first) {
-    return { kind: "resolved", target: first };
-  }
-  return { kind: "unresolved" };
-}
-async function describeScoutTargetAvailability(snapshot, target, currentDirectory) {
-  const resolvedConfig = await resolveRelayAgentConfig(target.selector, {
-    currentDirectory
-  });
-  const registrationKind = resolvedConfig?.registrationKind ?? null;
-  const endpoints = Object.values(snapshot.endpoints ?? {}).filter((endpoint) => endpoint.agentId === target.agentId);
-  if (endpoints.length > 0) {
-    return {
-      agentId: target.agentId,
-      state: whoEntryState(endpoints, registrationKind ?? "broker"),
-      registrationKind,
-      projectRoot: resolvedConfig?.projectRoot ?? null
-    };
-  }
-  if (registrationKind === "discovered") {
-    return {
-      agentId: target.agentId,
-      state: "discovered",
-      registrationKind,
-      projectRoot: resolvedConfig?.projectRoot ?? null
-    };
-  }
-  return {
-    agentId: target.agentId,
-    state: snapshot.agents[target.agentId] || registrationKind === "configured" ? "offline" : "unknown",
-    registrationKind,
-    projectRoot: resolvedConfig?.projectRoot ?? null
-  };
-}
 function resolveConversationShareMode(snapshot, nodeId, participantIds, fallback) {
   if (fallback === "shared")
     return "shared";
@@ -13318,72 +13765,74 @@ async function sendScoutMessage(input) {
   const currentDirectory = input.currentDirectory ?? process.cwd();
   const createdAtMs = input.createdAtMs ?? Date.now();
   const senderId = await resolveConversationActorId(broker.baseUrl, broker.snapshot, broker.node.id, input.senderId, currentDirectory);
+  const mentionResolution = await resolveMentionTargets(broker.snapshot, input.body, currentDirectory);
+  const selectors = extractAgentSelectors(input.body);
   const requestedTargetLabel = input.targetLabel?.trim();
   if (requestedTargetLabel) {
-    const targetResolution = await resolveSingleBrokerTarget(broker.snapshot, requestedTargetLabel, currentDirectory);
-    if (targetResolution.kind !== "resolved") {
+    const delivery = await brokerPostJson(broker.baseUrl, scoutBrokerPaths.v1.deliver, {
+      id: `deliver-${createdAtMs.toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
+      requesterId: senderId,
+      requesterNodeId: broker.node.id,
+      targetLabel: requestedTargetLabel,
+      body: input.body,
+      intent: "tell",
+      channel: input.channel,
+      speechText: input.shouldSpeak ? stripScoutAgentSelectorLabels(input.body) : undefined,
+      createdAt: createdAtMs,
+      messageMetadata: {
+        source: "scout-cli"
+      }
+    });
+    if (delivery.kind !== "delivery") {
       return {
         usedBroker: true,
         invokedTargets: [],
-        unresolvedTargets: [requestedTargetLabel]
+        unresolvedTargets: [requestedTargetLabel],
+        targetDiagnostic: scoutTargetDiagnosticFromDeliveryFailure(delivery)
       };
     }
-    const target = targetResolution.target;
-    const targetReady = await ensureTargetRelayAgentRegistered(broker.baseUrl, broker.snapshot, broker.node.id, target.agentId, currentDirectory);
-    if (!targetReady || target.agentId === senderId) {
+    return {
+      usedBroker: true,
+      conversationId: delivery.conversation.id,
+      messageId: delivery.message.id,
+      invokedTargets: delivery.targetAgentId ? [delivery.targetAgentId] : [],
+      unresolvedTargets: [],
+      routeKind: delivery.routeKind
+    };
+  }
+  if (selectors.length === 1 && mentionResolution.resolved.length + mentionResolution.unresolved.length + mentionResolution.ambiguous.length === 1) {
+    const targetLabel = selectors[0].label;
+    const delivery = await brokerPostJson(broker.baseUrl, scoutBrokerPaths.v1.deliver, {
+      id: `deliver-${createdAtMs.toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
+      requesterId: senderId,
+      requesterNodeId: broker.node.id,
+      targetLabel,
+      body: input.body,
+      intent: "tell",
+      channel: input.channel,
+      speechText: input.shouldSpeak ? stripScoutAgentSelectorLabels(input.body) : undefined,
+      createdAt: createdAtMs,
+      messageMetadata: {
+        source: "scout-cli"
+      }
+    });
+    if (delivery.kind !== "delivery") {
       return {
         usedBroker: true,
         invokedTargets: [],
-        unresolvedTargets: [requestedTargetLabel]
+        unresolvedTargets: [targetLabel],
+        targetDiagnostic: scoutTargetDiagnosticFromDeliveryFailure(delivery)
       };
     }
-    let conversation2;
-    if (!input.channel) {
-      const dm = await ensureBrokerDirectConversationBetween(broker.baseUrl, broker.snapshot, broker.node.id, senderId, target.agentId);
-      conversation2 = dm.conversation;
-    } else {
-      conversation2 = await ensureBrokerConversation(broker.baseUrl, broker.snapshot, broker.node.id, input.channel, senderId, [target.agentId]);
-    }
-    const messageId2 = `m-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
-    const speechText2 = input.shouldSpeak ? stripScoutAgentSelectorLabels(input.body) : "";
-    const returnAddress2 = buildScoutReturnAddress2(broker.snapshot, senderId, {
-      conversationId: conversation2.id,
-      replyToMessageId: messageId2
-    });
-    await brokerPostJson(broker.baseUrl, scoutBrokerPaths.v1.messages, {
-      id: messageId2,
-      conversationId: conversation2.id,
-      actorId: senderId,
-      originNodeId: broker.node.id,
-      class: conversation2.kind === "system" ? "system" : "agent",
-      body: input.body,
-      mentions: [{ actorId: target.agentId, label: target.label }],
-      speech: speechText2 ? { text: speechText2 } : undefined,
-      audience: {
-        notify: [target.agentId],
-        reason: relayAudienceReason(conversation2)
-      },
-      visibility: conversation2.visibility,
-      policy: "durable",
-      createdAt: createdAtMs,
-      metadata: {
-        source: "scout-cli",
-        relayChannel: relayChannelMetadata(conversation2, input.channel),
-        relayTargetIds: [target.agentId],
-        relayMessageId: messageId2,
-        returnAddress: returnAddress2
-      }
-    });
     return {
       usedBroker: true,
-      conversationId: conversation2.id,
-      messageId: messageId2,
-      invokedTargets: [target.agentId],
+      conversationId: delivery.conversation.id,
+      messageId: delivery.message.id,
+      invokedTargets: delivery.targetAgentId ? [delivery.targetAgentId] : [],
       unresolvedTargets: [],
-      routeKind: relayRouteKind(conversation2)
+      routeKind: delivery.routeKind
     };
   }
-  const mentionResolution = await resolveMentionTargets(broker.snapshot, input.body, currentDirectory);
   const availableTargets = (await Promise.all(mentionResolution.resolved.map(async (target) => await ensureTargetRelayAgentRegistered(broker.baseUrl, broker.snapshot, broker.node.id, target.agentId, currentDirectory) ? target : null))).filter((target) => Boolean(target));
   const validTargets = [
     ...new Set(availableTargets.map((target) => target.agentId).filter((target) => target !== senderId && Boolean(broker.snapshot.agents[target])))
@@ -13560,74 +14009,42 @@ async function openScoutPeerSession(input) {
   };
 }
 async function sendScoutDirectMessage(input) {
-  const currentDirectory = input.currentDirectory ?? process.cwd();
-  const directSession = await openScoutPeerSession({
-    sourceId: OPERATOR_ID,
-    targetId: input.agentId,
-    currentDirectory
-  });
   const broker = await requireScoutBrokerContext();
   const createdAt = Date.now();
-  const messageId = `msg-${createdAt.toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
   const source = input.source?.trim() || "scout-mobile";
-  const targetAgentId = directSession.targetId;
-  const targetAgent = broker.snapshot.agents[targetAgentId] ?? ("agent" in directSession ? directSession.agent : undefined);
-  const targetLabel = `@${targetAgent?.handle?.trim() || targetAgent?.displayName?.trim() || targetAgentId}`;
-  const returnAddress = buildScoutReturnAddress2(broker.snapshot, OPERATOR_ID, {
-    conversationId: directSession.conversation.id,
-    replyToMessageId: messageId
-  });
-  await brokerPostJson(broker.baseUrl, scoutBrokerPaths.v1.messages, {
-    id: messageId,
-    conversationId: directSession.conversation.id,
-    replyToMessageId: input.replyToMessageId ?? undefined,
-    actorId: OPERATOR_ID,
-    originNodeId: broker.node.id,
-    class: "agent",
+  const delivery = await brokerPostJson(broker.baseUrl, scoutBrokerPaths.v1.deliver, {
+    id: `deliver-${createdAt.toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
+    requesterId: OPERATOR_ID,
+    requesterNodeId: broker.node.id,
+    targetAgentId: input.agentId,
     body: input.body.trim(),
-    mentions: [{ actorId: targetAgentId, label: targetLabel }],
-    audience: {
-      notify: [targetAgentId],
-      reason: "direct_message"
-    },
-    visibility: "private",
-    policy: "durable",
+    intent: "consult",
+    replyToMessageId: input.replyToMessageId ?? undefined,
+    execution: input.executionHarness ? { harness: input.executionHarness } : undefined,
+    ensureAwake: true,
     createdAt,
-    metadata: {
+    messageMetadata: {
       source,
       destinationKind: "direct",
-      destinationId: targetAgentId,
+      destinationId: input.agentId,
       referenceMessageIds: input.referenceMessageIds ?? [],
       clientMessageId: input.clientMessageId ?? null,
-      returnAddress,
       ...input.deviceId ? { deviceId: input.deviceId } : {}
-    }
-  });
-  const invocationResponse = await brokerPostJson(broker.baseUrl, scoutBrokerPaths.v1.invocations, {
-    id: `inv-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
-    requesterId: OPERATOR_ID,
-    requesterNodeId: broker.node.id,
-    targetAgentId,
-    action: "consult",
-    task: input.body.trim(),
-    conversationId: directSession.conversation.id,
-    messageId,
-    execution: input.executionHarness ? { harness: input.executionHarness } : undefined,
-    ensureAwake: true,
-    stream: false,
-    createdAt,
-    metadata: {
+    },
+    invocationMetadata: {
       source,
       destinationKind: "direct",
-      destinationId: targetAgentId,
-      returnAddress,
+      destinationId: input.agentId,
       ...input.deviceId ? { deviceId: input.deviceId } : {}
     }
   });
+  if (delivery.kind !== "delivery") {
+    throw new Error(delivery.kind === "question" ? delivery.question.detail : delivery.rejection.detail);
+  }
   return {
-    conversationId: directSession.conversation.id,
-    messageId,
-    flight: invocationResponse.flight
+    conversationId: delivery.conversation.id,
+    messageId: delivery.message.id,
+    flight: delivery.flight
   };
 }
 async function askScoutAgentById(input) {
@@ -13643,103 +14060,46 @@ async function askScoutAgentById(input) {
   if (!targetAgentId) {
     return { usedBroker: true, unresolvedTargetId: input.targetAgentId };
   }
-  const targetLabel = formatBrokerTargetLabel(broker.snapshot, targetAgentId);
-  const target = {
-    agentId: targetAgentId,
-    label: targetLabel,
-    selector: {
-      raw: targetLabel.replace(/^@/, ""),
-      label: targetLabel,
-      definitionId: broker.snapshot.agents[targetAgentId]?.definitionId ?? metadataString2(broker.snapshot.agents[targetAgentId]?.metadata, "definitionId") ?? targetAgentId,
-      ...broker.snapshot.agents[targetAgentId]?.workspaceQualifier ? {
-        workspaceQualifier: broker.snapshot.agents[targetAgentId]?.workspaceQualifier
-      } : {},
-      ...broker.snapshot.agents[targetAgentId]?.nodeQualifier ? {
-        nodeQualifier: broker.snapshot.agents[targetAgentId]?.nodeQualifier
-      } : {}
-    }
-  };
-  const targetReady = await ensureTargetRelayAgentRegistered(broker.baseUrl, broker.snapshot, broker.node.id, targetAgentId, currentDirectory);
-  if (!targetReady) {
+  const delivery = await brokerPostJson(broker.baseUrl, scoutBrokerPaths.v1.deliver, {
+    id: `deliver-${createdAtMs.toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
+    requesterId: senderId,
+    requesterNodeId: broker.node.id,
+    targetAgentId,
+    body: input.body.trim(),
+    intent: "consult",
+    channel: input.channel,
+    speechText: input.shouldSpeak ? input.body.trim() : undefined,
+    execution: input.executionHarness ? { harness: input.executionHarness } : undefined,
+    ensureAwake: true,
+    createdAt: createdAtMs,
+    messageMetadata: {
+      source
+    },
+    invocationMetadata: {
+      source
+    }
+  });
+  if (delivery.kind !== "delivery") {
     return {
       usedBroker: true,
       unresolvedTargetId: targetAgentId,
-      targetDiagnostic: await describeScoutTargetAvailability(broker.snapshot, target, currentDirectory)
+      targetDiagnostic: scoutTargetDiagnosticFromDeliveryFailure(delivery)
     };
   }
-  let conversation;
-  if (!input.channel) {
-    const dm = await ensureBrokerDirectConversationBetween(broker.baseUrl, broker.snapshot, broker.node.id, senderId, targetAgentId);
-    conversation = dm.conversation;
-  } else {
-    conversation = await ensureBrokerConversation(broker.baseUrl, broker.snapshot, broker.node.id, input.channel, senderId, [targetAgentId]);
-  }
-  const messageId = `m-${createdAtMs.toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
-  const speechText = input.shouldSpeak ? input.body.trim() : "";
-  const returnAddress = buildScoutReturnAddress2(broker.snapshot, senderId, {
-    conversationId: conversation.id,
-    replyToMessageId: messageId
-  });
   const workItem = input.workItem ? await createScoutTrackedWorkItem({
     baseUrl: broker.baseUrl,
     senderId,
     targetAgentId,
-    conversationId: conversation.id,
+    conversationId: delivery.conversation.id,
     createdAtMs,
     source,
     workItem: input.workItem
   }) : undefined;
-  await brokerPostJson(broker.baseUrl, scoutBrokerPaths.v1.messages, {
-    id: messageId,
-    conversationId: conversation.id,
-    actorId: senderId,
-    originNodeId: broker.node.id,
-    class: conversation.kind === "system" ? "system" : "agent",
-    body: input.body.trim(),
-    mentions: [{ actorId: targetAgentId, label: targetLabel }],
-    speech: speechText ? { text: speechText } : undefined,
-    audience: {
-      notify: [targetAgentId],
-      reason: relayAudienceReason(conversation)
-    },
-    visibility: conversation.visibility,
-    policy: "durable",
-    createdAt: createdAtMs,
-    metadata: {
-      source,
-      relayChannel: relayChannelMetadata(conversation, input.channel),
-      relayTarget: targetAgentId,
-      collaborationRecordId: workItem?.id,
-      returnAddress
-    }
-  });
-  const invocationResponse = await brokerPostJson(broker.baseUrl, scoutBrokerPaths.v1.invocations, {
-    id: `inv-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
-    requesterId: senderId,
-    requesterNodeId: broker.node.id,
-    targetAgentId,
-    action: "consult",
-    task: input.body.trim(),
-    collaborationRecordId: workItem?.id,
-    conversationId: conversation.id,
-    messageId,
-    execution: input.executionHarness ? { harness: input.executionHarness } : undefined,
-    ensureAwake: true,
-    stream: false,
-    createdAt: createdAtMs,
-    metadata: {
-      source,
-      relayChannel: relayChannelMetadata(conversation, input.channel),
-      relayTarget: targetAgentId,
-      collaborationRecordId: workItem?.id,
-      returnAddress
-    }
-  });
   return {
     usedBroker: true,
-    flight: invocationResponse.flight,
-    conversationId: conversation.id,
-    messageId,
+    flight: delivery.flight,
+    conversationId: delivery.conversation.id,
+    messageId: delivery.message.id,
     workItem
   };
 }
@@ -13750,104 +14110,49 @@ async function askScoutQuestion(input) {
   }
   const currentDirectory = input.currentDirectory ?? process.cwd();
   const senderId = await resolveConversationActorId(broker.baseUrl, broker.snapshot, broker.node.id, input.senderId, currentDirectory);
-  const targetResolution = await resolveSingleBrokerTarget(broker.snapshot, input.targetLabel, currentDirectory);
-  if (targetResolution.kind === "ambiguous") {
-    return {
-      usedBroker: true,
-      unresolvedTarget: input.targetLabel,
-      targetDiagnostic: {
-        state: "ambiguous",
-        candidates: targetResolution.candidates
-      }
-    };
-  }
-  if (targetResolution.kind !== "resolved") {
-    return { usedBroker: true, unresolvedTarget: input.targetLabel };
-  }
-  const target = targetResolution.target;
-  const targetReady = await ensureTargetRelayAgentRegistered(broker.baseUrl, broker.snapshot, broker.node.id, target.agentId, currentDirectory);
-  if (!targetReady) {
+  const createdAt = input.createdAtMs ?? Date.now();
+  const normalizedTargetLabel = renderScoutTargetLabel(input.targetLabel);
+  const messageBody = input.body.trim().startsWith(normalizedTargetLabel) ? input.body.trim() : `${normalizedTargetLabel} ${input.body.trim()}`;
+  const delivery = await brokerPostJson(broker.baseUrl, scoutBrokerPaths.v1.deliver, {
+    id: `deliver-${createdAt.toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
+    requesterId: senderId,
+    requesterNodeId: broker.node.id,
+    targetLabel: input.targetLabel,
+    body: messageBody,
+    intent: "consult",
+    channel: input.channel,
+    speechText: input.shouldSpeak ? stripScoutAgentSelectorLabels(messageBody) : undefined,
+    execution: input.executionHarness ? { harness: input.executionHarness } : undefined,
+    ensureAwake: true,
+    createdAt,
+    messageMetadata: {
+      source: "scout-cli"
+    },
+    invocationMetadata: {
+      source: "scout-cli"
+    }
+  });
+  if (delivery.kind !== "delivery") {
     return {
       usedBroker: true,
       unresolvedTarget: input.targetLabel,
-      targetDiagnostic: await describeScoutTargetAvailability(broker.snapshot, target, currentDirectory)
+      targetDiagnostic: scoutTargetDiagnosticFromDeliveryFailure(delivery)
     };
   }
-  let conversation;
-  if (!input.channel) {
-    const dm = await ensureBrokerDirectConversationBetween(broker.baseUrl, broker.snapshot, broker.node.id, senderId, target.agentId);
-    conversation = dm.conversation;
-  } else {
-    conversation = await ensureBrokerConversation(broker.baseUrl, broker.snapshot, broker.node.id, input.channel, senderId, [target.agentId]);
-  }
-  const messageId = `m-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
-  const messageBody = input.body.trim().startsWith(target.label) ? input.body.trim() : `${target.label} ${input.body.trim()}`;
-  const speechText = input.shouldSpeak ? stripScoutAgentSelectorLabels(messageBody) : "";
-  const createdAt = input.createdAtMs ?? Date.now();
-  const returnAddress = buildScoutReturnAddress2(broker.snapshot, senderId, {
-    conversationId: conversation.id,
-    replyToMessageId: messageId
-  });
-  const workItem = input.workItem ? await createScoutTrackedWorkItem({
+  const workItem = input.workItem && delivery.targetAgentId ? await createScoutTrackedWorkItem({
     baseUrl: broker.baseUrl,
     senderId,
-    targetAgentId: target.agentId,
-    conversationId: conversation.id,
+    targetAgentId: delivery.targetAgentId,
+    conversationId: delivery.conversation.id,
     createdAtMs: createdAt,
     source: "scout-cli",
     workItem: input.workItem
   }) : undefined;
-  await brokerPostJson(broker.baseUrl, scoutBrokerPaths.v1.messages, {
-    id: messageId,
-    conversationId: conversation.id,
-    actorId: senderId,
-    originNodeId: broker.node.id,
-    class: conversation.kind === "system" ? "system" : "agent",
-    body: messageBody,
-    mentions: [{ actorId: target.agentId, label: target.label }],
-    speech: speechText ? { text: speechText } : undefined,
-    audience: {
-      notify: [target.agentId],
-      reason: relayAudienceReason(conversation)
-    },
-    visibility: conversation.visibility,
-    policy: "durable",
-    createdAt,
-    metadata: {
-      source: "scout-cli",
-      relayChannel: relayChannelMetadata(conversation, input.channel),
-      relayTarget: target.agentId,
-      collaborationRecordId: workItem?.id,
-      returnAddress
-    }
-  });
-  const invocationResponse = await brokerPostJson(broker.baseUrl, scoutBrokerPaths.v1.invocations, {
-    id: `inv-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
-    requesterId: senderId,
-    requesterNodeId: broker.node.id,
-    targetAgentId: target.agentId,
-    action: "consult",
-    task: messageBody,
-    collaborationRecordId: workItem?.id,
-    conversationId: conversation.id,
-    messageId,
-    execution: input.executionHarness ? { harness: input.executionHarness } : undefined,
-    ensureAwake: true,
-    stream: false,
-    createdAt,
-    metadata: {
-      source: "scout-cli",
-      relayChannel: relayChannelMetadata(conversation, input.channel),
-      relayTarget: target.agentId,
-      collaborationRecordId: workItem?.id,
-      returnAddress
-    }
-  });
   return {
     usedBroker: true,
-    flight: invocationResponse.flight,
-    conversationId: conversation.id,
-    messageId,
+    flight: delivery.flight,
+    conversationId: delivery.conversation.id,
+    messageId: delivery.message.id,
     workItem
   };
 }
@@ -13880,7 +14185,7 @@ async function waitForScoutFlight(baseUrl, flightId, options = {}) {
     if (deadline !== null && Date.now() > deadline) {
       throw new Error(`Timed out waiting for flight ${flight.id}.`);
     }
-    await new Promise((resolve9) => setTimeout(resolve9, 1000));
+    await new Promise((resolve10) => setTimeout(resolve10, 1000));
   }
 }
 async function loadScoutMessages(options = {}) {
@@ -14085,7 +14390,7 @@ async function listScoutAgents(options = {}) {
 }
 async function loadScoutRelayConfig() {
   try {
-    const raw = await readFile7(join13(relayHubDirectory(), "config.json"), "utf8");
+    const raw = await readFile8(join14(relayHubDirectory(), "config.json"), "utf8");
     return JSON.parse(raw);
   } catch {
     return {};
@@ -14107,15 +14412,15 @@ function applyPronunciations(text, pronunciations) {
 async function acquireScoutOnAir(agent, timeoutMs = 30000) {
   const hub = relayHubDirectory();
   await mkdir7(hub, { recursive: true });
-  const lockPath = join13(hub, "on-air.lock");
+  const lockPath = join14(hub, "on-air.lock");
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
     try {
-      const raw = await readFile7(lockPath, "utf8");
+      const raw = await readFile8(lockPath, "utf8");
       const lock = JSON.parse(raw);
       if (Date.now() - Number(lock.ts ?? 0) > 30000)
         break;
-      await new Promise((resolve9) => setTimeout(resolve9, 2000));
+      await new Promise((resolve10) => setTimeout(resolve10, 2000));
     } catch {
       break;
     }
@@ -14125,7 +14430,7 @@ async function acquireScoutOnAir(agent, timeoutMs = 30000) {
 }
 async function releaseScoutOnAir() {
   try {
-    await unlink(join13(relayHubDirectory(), "on-air.lock"));
+    await unlink(join14(relayHubDirectory(), "on-air.lock"));
   } catch {}
 }
 async function speakScoutText(text, voice) {
@@ -14172,10 +14477,10 @@ async function speakScoutText(text, voice) {
     player.stdin.write(value);
   }
   player.stdin.end();
-  await new Promise((resolve9) => player.on("close", () => resolve9()));
+  await new Promise((resolve10) => player.on("close", () => resolve10()));
 }
 function buildScoutEnrollmentPrompt(input) {
-  const relayLogPath = join13(relayHubDirectory(), "channel.log");
+  const relayLogPath = join14(relayHubDirectory(), "channel.log");
   const cliCommand = input.cliCommand?.trim() || "scout";
   const task = input.task?.trim();
   return [
@@ -14219,7 +14524,7 @@ __export(exports_ask, {
 });
 function renderAskCommandHelp() {
   return [
-    "Usage: scout ask --to <agent> [--as <sender>] [--channel <name>] [--timeout <seconds>] [--harness <runtime>] <message>",
+    "Usage: scout ask --to <agent> [--as <sender>] [--channel <name>] [--timeout <seconds>] [--harness <runtime>] [--prompt-file <path> | <message>]",
     "",
     "Ask one agent to do work or return a concrete answer.",
     "",
@@ -14231,14 +14536,20 @@ function renderAskCommandHelp() {
     'Use ask when the meaning is "do this and get back to me."',
     "Keep progress, review, and completion in that same DM or explicit channel.",
     "",
+    "Input:",
+    "  inline message                    -> primary prompt body",
+    "  --prompt-file <path>              -> read the primary prompt body from a UTF-8 file",
+    "  --body-file <path>                -> alias for --prompt-file",
+    "",
     "Examples:",
     '  scout ask --to hudson "review the parser"',
+    "  scout ask --to hudson --prompt-file ./handoff.md",
     '  scout ask --as premotion.master.mini --to hudson "build the editor"',
     '  scout ask --to vox.harness:codex "take another pass on the runtime fix"'
   ].join(`
 `);
 }
-function renderScoutTargetLabel(targetLabel) {
+function renderScoutTargetLabel2(targetLabel) {
   const trimmed = targetLabel.trim();
   return trimmed.startsWith("@") ? trimmed : `@${trimmed}`;
 }
@@ -14258,7 +14569,7 @@ function renderConversationRoute(conversationId) {
   return conversationId.startsWith("dm.") ? `DM ${conversationId}` : `conversation ${conversationId}`;
 }
 function formatScoutAskRoutingError(result, targetLabel) {
-  const renderedTarget = renderScoutTargetLabel(targetLabel);
+  const renderedTarget = renderScoutTargetLabel2(targetLabel);
   const diagnostic = result.targetDiagnostic;
   if (diagnostic?.state === "ambiguous") {
     const rendered = diagnostic.candidates.map((candidate) => renderAmbiguousCandidate(candidate.label || candidate.agentId)).filter((label) => label.length > 0);
@@ -14279,6 +14590,17 @@ function formatScoutAskRoutingError(result, targetLabel) {
     }
     return `target ${renderedTarget} is offline; nothing was sent. Run \`scout who\` to inspect the target before retrying.`;
   }
+  if (diagnostic?.state === "unavailable") {
+    const runtime = diagnostic.transport ? ` (${diagnostic.transport})` : "";
+    const wakePolicy = diagnostic.wakePolicy ? ` [wake:${diagnostic.wakePolicy}]` : "";
+    return `target ${renderedTarget} is known but currently unavailable${runtime}${wakePolicy}; nothing was sent. ${diagnostic.detail}`;
+  }
+  if (diagnostic?.state === "unknown") {
+    return `there is no ${renderedTarget}; nothing was sent.`;
+  }
+  if (diagnostic?.state === "invalid" || diagnostic?.state === "missing") {
+    return `${diagnostic.detail}; nothing was sent.`;
+  }
   return `target ${renderedTarget} is not currently routable; nothing was sent.`;
 }
 async function runAskCommand(context, args) {
@@ -14292,10 +14614,11 @@ async function runAskCommand(context, args) {
 async function runAskWithOptions(context, options) {
   const currentDirectory = options.currentDirectory ?? defaultScoutContextDirectory(context);
   const senderId = await resolveScoutSenderId(options.agentName, currentDirectory, context.env);
+  const body = await resolvePromptBody(options);
   const result = await askScoutQuestion({
     senderId,
     targetLabel: options.targetLabel,
-    body: options.message,
+    body,
     channel: options.channel,
     executionHarness: parseScoutHarness(options.harness),
     currentDirectory
@@ -14323,6 +14646,7 @@ var HELP_FLAGS;
 var init_ask = __esm(async () => {
   init_context();
   init_options();
+  init_input_file();
   await init_service();
   HELP_FLAGS = new Set(["--help", "-h"]);
 });
@@ -14474,7 +14798,7 @@ __export(exports_send, {
 });
 function renderSendCommandHelp() {
   return [
-    "Usage: scout send [--as <sender>] [--channel <name>] [--speak] [--harness <runtime>] <message>",
+    "Usage: scout send [--as <sender>] [--channel <name>] [--speak] [--harness <runtime>] [--message-file <path> | <message>]",
     "",
     "Tell or update another agent or an explicit channel.",
     "",
@@ -14487,8 +14811,14 @@ function renderSendCommandHelp() {
     "Use send for heads-up, replies, and status updates.",
     'Use `scout ask` when the meaning is "do this and get back to me."',
     "",
+    "Input:",
+    "  inline message                    -> message body",
+    "  --message-file <path>             -> read the message body from a UTF-8 file",
+    "  --body-file <path>                -> alias for --message-file",
+    "",
     "Examples:",
     '  scout send "@hudson ready for review"',
+    "  scout send --channel triage --message-file ./status.md",
     '  scout send --as premotion.master.mini "@hudson editor branch is green"',
     '  scout send --channel triage "need two reviewers"'
   ].join(`
@@ -14501,8 +14831,31 @@ function renderTargetLabel(label) {
   }
   return trimmed.startsWith("@") ? trimmed : `@${trimmed}`;
 }
-function formatScoutSendRoutingError(unresolvedTargets) {
-  const rendered = unresolvedTargets.map(renderTargetLabel).filter((label) => label.length > 0);
+function renderAmbiguousCandidate2(label) {
+  const rendered = renderTargetLabel(label);
+  return rendered || label.trim();
+}
+function formatScoutSendRoutingError(result) {
+  const diagnostic = result.targetDiagnostic;
+  if (diagnostic?.state === "unknown") {
+    return `there is no ${renderTargetLabel(diagnostic.agentId)}; nothing was sent.`;
+  }
+  if (diagnostic?.state === "ambiguous") {
+    const renderedCandidates = diagnostic.candidates.map((candidate) => renderAmbiguousCandidate2(candidate.label || candidate.agentId)).filter((label) => label.length > 0);
+    if (renderedCandidates.length > 0) {
+      return `target ${renderTargetLabel(result.unresolvedTargets[0] ?? "")} matches multiple agents: ${renderedCandidates.join(", ")}. Re-run with the fully qualified form (e.g. \`scout send "${renderedCandidates[0]} ..."\`).`;
+    }
+    return `target ${renderTargetLabel(result.unresolvedTargets[0] ?? "")} matches multiple agents; nothing was sent. Re-run with a fully qualified @handle to disambiguate.`;
+  }
+  if (diagnostic?.state === "unavailable") {
+    const runtime = diagnostic.transport ? ` (${diagnostic.transport})` : "";
+    const wakePolicy = diagnostic.wakePolicy ? ` [wake:${diagnostic.wakePolicy}]` : "";
+    return `target ${renderTargetLabel(result.unresolvedTargets[0] ?? diagnostic.agentId)} is known but currently unavailable${runtime}${wakePolicy}; nothing was sent. ${diagnostic.detail}`;
+  }
+  if (diagnostic?.state === "invalid" || diagnostic?.state === "missing") {
+    return `${diagnostic.detail}; nothing was sent.`;
+  }
+  const rendered = result.unresolvedTargets.map(renderTargetLabel).filter((label) => label.length > 0);
   if (rendered.length === 1) {
     return `target ${rendered[0]} is not uniquely routable; nothing was sent.`;
   }
@@ -14522,9 +14875,10 @@ async function runSendCommand(context, args) {
   const options = parseSendCommandOptions(args, defaultScoutContextDirectory(context));
   const currentDirectory = options.currentDirectory ?? defaultScoutContextDirectory(context);
   const senderId = await resolveScoutSenderId(options.agentName, currentDirectory, context.env);
+  const body = await resolveMessageBody(options);
   const result = await sendScoutMessage({
     senderId,
-    body: options.message,
+    body,
     channel: options.channel,
     shouldSpeak: options.shouldSpeak,
     executionHarness: parseScoutHarness(options.harness),
@@ -14534,7 +14888,7 @@ async function runSendCommand(context, args) {
     throw new Error("broker is not reachable");
   }
   if (result.unresolvedTargets.length > 0) {
-    throw new Error(formatScoutSendRoutingError(result.unresolvedTargets));
+    throw new Error(formatScoutSendRoutingError(result));
   }
   if (result.routingError) {
     throw new Error(formatScoutRouteChoiceError(result.routingError));
@@ -14542,7 +14896,7 @@ async function runSendCommand(context, args) {
   context.output.writeValue({
     senderId,
     conversationId: result.conversationId,
-    message: options.message,
+    message: body,
     invokedTargets: result.invokedTargets,
     unresolvedTargets: result.unresolvedTargets,
     routeKind: result.routeKind
@@ -14551,6 +14905,7 @@ async function runSendCommand(context, args) {
 var HELP_FLAGS2;
 var init_send = __esm(async () => {
   init_context();
+  init_input_file();
   init_options();
   init_broker();
   await init_service();
@@ -14565,15 +14920,21 @@ __export(exports_broadcast, {
 });
 function renderBroadcastCommandHelp() {
   return [
-    "Usage: scout broadcast [--as <sender>] [--harness <runtime>] <message>",
+    "Usage: scout broadcast [--as <sender>] [--harness <runtime>] [--message-file <path> | <message>]",
     "",
     "Broadcast to channel.shared.",
     "",
     "Use this only when the message is genuinely for everyone.",
     "Do not use broadcast for ordinary one-to-one delegation or small-group coordination.",
     "",
+    "Input:",
+    "  inline message                    -> broadcast body",
+    "  --message-file <path>             -> read the broadcast body from a UTF-8 file",
+    "  --body-file <path>                -> alias for --message-file",
+    "",
     "Examples:",
     '  scout broadcast "deploying in 15m, pause long flights"',
+    "  scout broadcast --message-file ./maintenance.md",
     '  scout broadcast --as scout.main.mini "broker maintenance starts now"'
   ].join(`
 `);
@@ -14589,9 +14950,10 @@ async function runBroadcastCommand(context, args) {
   }
   const currentDirectory = options.currentDirectory ?? defaultScoutContextDirectory(context);
   const senderId = await resolveScoutSenderId(options.agentName, currentDirectory, context.env);
+  const body = await resolveMessageBody(options);
   const result = await sendScoutMessage({
     senderId,
-    body: `@all ${options.message}`,
+    body: `@all ${body}`,
     channel: "shared",
     executionHarness: parseScoutHarness(options.harness),
     currentDirectory
@@ -14600,10 +14962,10 @@ async function runBroadcastCommand(context, args) {
     throw new Error("broker is not reachable");
   }
   if (result.unresolvedTargets.length > 0) {
-    throw new Error(formatScoutSendRoutingError(result.unresolvedTargets));
+    throw new Error(formatScoutSendRoutingError(result));
   }
   context.output.writeValue({
-    message: options.message,
+    message: body,
     invokedTargets: result.invokedTargets,
     unresolvedTargets: result.unresolvedTargets,
     routeKind: result.routeKind
@@ -14613,6 +14975,7 @@ var HELP_FLAGS3;
 var init_broadcast = __esm(async () => {
   init_context();
   init_errors();
+  init_input_file();
   init_options();
   init_broker();
   await __promiseAll([
@@ -14759,7 +15122,8 @@ async function createScoutAgentCard(input) {
     displayName: input.displayName,
     harness: input.harness,
     model: input.model,
-    currentDirectory: input.currentDirectory
+    currentDirectory: input.currentDirectory,
+    ensureOnline: false
   });
   const currentDirectory = input.currentDirectory ?? input.projectPath;
   const broker = await loadScoutBrokerContext();
@@ -14857,11 +15221,11 @@ function renderCardCommandHelp() {
 `);
 }
 function promptWithDefault(question, defaultValue) {
-  return new Promise((resolve9) => {
+  return new Promise((resolve10) => {
     const rl = createInterface({ input: process.stdin, output: process.stderr });
     rl.question(`  ${question} [${defaultValue}]: `, (answer) => {
       rl.close();
-      resolve9(answer.trim() || defaultValue);
+      resolve10(answer.trim() || defaultValue);
     });
   });
 }
@@ -35590,7 +35954,7 @@ class Protocol {
           return;
         }
         const pollInterval = task2.pollInterval ?? this._options?.defaultTaskPollInterval ?? 1000;
-        await new Promise((resolve9) => setTimeout(resolve9, pollInterval));
+        await new Promise((resolve10) => setTimeout(resolve10, pollInterval));
         options?.signal?.throwIfAborted();
       }
     } catch (error48) {
@@ -35602,7 +35966,7 @@ class Protocol {
   }
   request(request, resultSchema, options) {
     const { relatedRequestId, resumptionToken, onresumptiontoken, task, relatedTask } = options ?? {};
-    return new Promise((resolve9, reject) => {
+    return new Promise((resolve10, reject) => {
       const earlyReject = (error48) => {
         reject(error48);
       };
@@ -35680,7 +36044,7 @@ class Protocol {
           if (!parseResult.success) {
             reject(parseResult.error);
           } else {
-            resolve9(parseResult.data);
+            resolve10(parseResult.data);
           }
         } catch (error48) {
           reject(error48);
@@ -35871,12 +36235,12 @@ class Protocol {
         interval = task.pollInterval;
       }
     } catch {}
-    return new Promise((resolve9, reject) => {
+    return new Promise((resolve10, reject) => {
       if (signal.aborted) {
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
         return;
       }
-      const timeoutId = setTimeout(resolve9, interval);
+      const timeoutId = setTimeout(resolve10, interval);
       signal.addEventListener("abort", () => {
         clearTimeout(timeoutId);
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
@@ -36353,11 +36717,11 @@ var require_codegen = __commonJS((exports) => {
       const rhs = this.rhs === undefined ? "" : ` = ${this.rhs}`;
       return `${varKind} ${this.name}${rhs};` + _n;
     }
-    optimizeNames(names, constants4) {
+    optimizeNames(names, constants5) {
       if (!names[this.name.str])
         return;
       if (this.rhs)
-        this.rhs = optimizeExpr(this.rhs, names, constants4);
+        this.rhs = optimizeExpr(this.rhs, names, constants5);
       return this;
     }
     get names() {
@@ -36375,10 +36739,10 @@ var require_codegen = __commonJS((exports) => {
     render({ _n }) {
       return `${this.lhs} = ${this.rhs};` + _n;
     }
-    optimizeNames(names, constants4) {
+    optimizeNames(names, constants5) {
       if (this.lhs instanceof code_1.Name && !names[this.lhs.str] && !this.sideEffects)
         return;
-      this.rhs = optimizeExpr(this.rhs, names, constants4);
+      this.rhs = optimizeExpr(this.rhs, names, constants5);
       return this;
     }
     get names() {
@@ -36444,8 +36808,8 @@ var require_codegen = __commonJS((exports) => {
     optimizeNodes() {
       return `${this.code}` ? this : undefined;
     }
-    optimizeNames(names, constants4) {
-      this.code = optimizeExpr(this.code, names, constants4);
+    optimizeNames(names, constants5) {
+      this.code = optimizeExpr(this.code, names, constants5);
       return this;
     }
     get names() {
@@ -36475,12 +36839,12 @@ var require_codegen = __commonJS((exports) => {
       }
       return nodes.length > 0 ? this : undefined;
     }
-    optimizeNames(names, constants4) {
+    optimizeNames(names, constants5) {
       const { nodes } = this;
       let i = nodes.length;
       while (i--) {
         const n = nodes[i];
-        if (n.optimizeNames(names, constants4))
+        if (n.optimizeNames(names, constants5))
           continue;
         subtractNames(names, n.names);
         nodes.splice(i, 1);
@@ -36537,12 +36901,12 @@ var require_codegen = __commonJS((exports) => {
         return;
       return this;
     }
-    optimizeNames(names, constants4) {
+    optimizeNames(names, constants5) {
       var _a2;
-      this.else = (_a2 = this.else) === null || _a2 === undefined ? undefined : _a2.optimizeNames(names, constants4);
-      if (!(super.optimizeNames(names, constants4) || this.else))
+      this.else = (_a2 = this.else) === null || _a2 === undefined ? undefined : _a2.optimizeNames(names, constants5);
+      if (!(super.optimizeNames(names, constants5) || this.else))
         return;
-      this.condition = optimizeExpr(this.condition, names, constants4);
+      this.condition = optimizeExpr(this.condition, names, constants5);
       return this;
     }
     get names() {
@@ -36567,10 +36931,10 @@ var require_codegen = __commonJS((exports) => {
     render(opts) {
       return `for(${this.iteration})` + super.render(opts);
     }
-    optimizeNames(names, constants4) {
-      if (!super.optimizeNames(names, constants4))
+    optimizeNames(names, constants5) {
+      if (!super.optimizeNames(names, constants5))
         return;
-      this.iteration = optimizeExpr(this.iteration, names, constants4);
+      this.iteration = optimizeExpr(this.iteration, names, constants5);
       return this;
     }
     get names() {
@@ -36608,10 +36972,10 @@ var require_codegen = __commonJS((exports) => {
     render(opts) {
       return `for(${this.varKind} ${this.name} ${this.loop} ${this.iterable})` + super.render(opts);
     }
-    optimizeNames(names, constants4) {
-      if (!super.optimizeNames(names, constants4))
+    optimizeNames(names, constants5) {
+      if (!super.optimizeNames(names, constants5))
         return;
-      this.iterable = optimizeExpr(this.iterable, names, constants4);
+      this.iterable = optimizeExpr(this.iterable, names, constants5);
       return this;
     }
     get names() {
@@ -36656,11 +37020,11 @@ var require_codegen = __commonJS((exports) => {
       (_b = this.finally) === null || _b === undefined || _b.optimizeNodes();
       return this;
     }
-    optimizeNames(names, constants4) {
+    optimizeNames(names, constants5) {
       var _a2, _b;
-      super.optimizeNames(names, constants4);
-      (_a2 = this.catch) === null || _a2 === undefined || _a2.optimizeNames(names, constants4);
-      (_b = this.finally) === null || _b === undefined || _b.optimizeNames(names, constants4);
+      super.optimizeNames(names, constants5);
+      (_a2 = this.catch) === null || _a2 === undefined || _a2.optimizeNames(names, constants5);
+      (_b = this.finally) === null || _b === undefined || _b.optimizeNames(names, constants5);
       return this;
     }
     get names() {
@@ -36934,7 +37298,7 @@ var require_codegen = __commonJS((exports) => {
   function addExprNames(names, from) {
     return from instanceof code_1._CodeOrName ? addNames(names, from.names) : names;
   }
-  function optimizeExpr(expr, names, constants4) {
+  function optimizeExpr(expr, names, constants5) {
     if (expr instanceof code_1.Name)
       return replaceName(expr);
     if (!canOptimize(expr))
@@ -36949,14 +37313,14 @@ var require_codegen = __commonJS((exports) => {
       return items;
     }, []));
     function replaceName(n) {
-      const c = constants4[n.str];
+      const c = constants5[n.str];
       if (c === undefined || names[n.str] !== 1)
         return n;
       delete names[n.str];
       return c;
     }
     function canOptimize(e) {
-      return e instanceof code_1._Code && e._items.some((c) => c instanceof code_1.Name && names[c.str] === 1 && constants4[c.str] !== undefined);
+      return e instanceof code_1._Code && e._items.some((c) => c instanceof code_1.Name && names[c.str] === 1 && constants5[c.str] !== undefined);
     }
   }
   function subtractNames(names, from) {
@@ -38861,7 +39225,7 @@ var require_compile = __commonJS((exports) => {
     const schOrFunc = root.refs[ref];
     if (schOrFunc)
       return schOrFunc;
-    let _sch = resolve9.call(this, root, ref);
+    let _sch = resolve10.call(this, root, ref);
     if (_sch === undefined) {
       const schema = (_a2 = root.localRefs) === null || _a2 === undefined ? undefined : _a2[ref];
       const { schemaId } = this.opts;
@@ -38888,7 +39252,7 @@ var require_compile = __commonJS((exports) => {
   function sameSchemaEnv(s1, s2) {
     return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
   }
-  function resolve9(root, ref) {
+  function resolve10(root, ref) {
     let sch;
     while (typeof (sch = this.refs[ref]) == "string")
       ref = sch;
@@ -39418,7 +39782,7 @@ var require_fast_uri = __commonJS((exports, module) => {
     }
     return uri;
   }
-  function resolve9(baseURI, relativeURI, options) {
+  function resolve10(baseURI, relativeURI, options) {
     const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
     const resolved = resolveComponent(parse7(baseURI, schemelessOptions), parse7(relativeURI, schemelessOptions), schemelessOptions, true);
     schemelessOptions.skipEscape = true;
@@ -39646,7 +40010,7 @@ var require_fast_uri = __commonJS((exports, module) => {
   var fastUri = {
     SCHEMES,
     normalize,
-    resolve: resolve9,
+    resolve: resolve10,
     resolveComponent,
     equal,
     serialize,
@@ -43029,12 +43393,12 @@ class StdioServerTransport {
     this.onclose?.();
   }
   send(message) {
-    return new Promise((resolve9) => {
+    return new Promise((resolve10) => {
       const json2 = serializeMessage(message);
       if (this._stdout.write(json2)) {
-        resolve9();
+        resolve10();
       } else {
-        this._stdout.once("drain", resolve9);
+        this._stdout.once("drain", resolve10);
       }
     });
   }
@@ -43050,7 +43414,7 @@ var init_product = __esm(() => {
 });
 
 // ../../apps/desktop/src/core/mcp/scout-channel.ts
-import { resolve as resolve9 } from "path";
+import { resolve as resolve10 } from "path";
 async function resolveAgentId(currentDirectory, env) {
   return resolveScoutSenderId(undefined, currentDirectory, env);
 }
@@ -43123,7 +43487,7 @@ function startBrokerSubscription(broker, agentId, onMessage, signal) {
 }
 async function runScoutChannelServer(options) {
   const env = options.env ?? process.env;
-  const currentDirectory = resolve9(options.defaultCurrentDirectory || process.cwd());
+  const currentDirectory = resolve10(options.defaultCurrentDirectory || process.cwd());
   const agentId = await resolveAgentId(currentDirectory, env);
   const brokerUrl = env.OPENSCOUT_BROKER_URL?.trim() || resolveScoutBrokerUrl();
   const broker = await loadScoutBrokerContext(brokerUrl);
@@ -43435,8 +43799,11 @@ async function runDownCommand(context, args) {
   let agent = await downScoutAgent(target);
   if (!agent) {
     const resolved = await resolveLocalAgentByName(target);
-    if (resolved) {
-      agent = await downScoutAgent(resolved.agentId);
+    const projectMatch = resolved ?? await resolveLocalAgentByName(target, {
+      matchProjectName: true
+    });
+    if (projectMatch) {
+      agent = await downScoutAgent(projectMatch.agentId);
     }
   }
   context.output.writeValue(agent, renderScoutDownResult);
@@ -43452,110 +43819,43 @@ var init_down = __esm(async () => {
 
 // ../../apps/desktop/src/app/host/runtime-service-client.ts
 import { spawn as spawn4 } from "child_process";
-import { basename as basename6, dirname as dirname8, join as join14 } from "path";
-import { existsSync as existsSync10 } from "fs";
-import { fileURLToPath as fileURLToPath6 } from "url";
-import { homedir as homedir9 } from "os";
-function tryWhich(executableName) {
-  const pathEnv = process.env.PATH ?? "";
-  const sep = process.platform === "win32" ? ";" : ":";
-  for (const dir of pathEnv.split(sep)) {
-    if (!dir)
-      continue;
-    const candidate = join14(dir, executableName);
-    if (existsSync10(candidate)) {
-      return candidate;
-    }
-    if (process.platform === "win32") {
-      for (const ext of [".cmd", ".exe", ".bat"]) {
-        const withExt = candidate + ext;
-        if (existsSync10(withExt))
-          return withExt;
-      }
-    }
-  }
-  return null;
-}
-function findNodeModulesRuntimeBin() {
-  const runtimeBinRel = join14("node_modules", "@openscout", "runtime", "bin", "openscout-runtime.mjs");
-  let dir = dirname8(fileURLToPath6(import.meta.url));
-  for (let i = 0;i < 24; i++) {
-    const candidate = join14(dir, runtimeBinRel);
-    if (existsSync10(candidate))
-      return candidate;
-    const parent = dirname8(dir);
-    if (parent === dir)
-      break;
-    dir = parent;
-  }
-  const bunGlobal = join14(homedir9(), ".bun", "install", "global", "node_modules", "@openscout", "runtime", "bin", "openscout-runtime.mjs");
-  if (existsSync10(bunGlobal))
-    return bunGlobal;
-  return null;
-}
-function findMonorepoOpenscoutRuntimeBin() {
-  let dir = process.cwd();
-  for (let i = 0;i < 24; i++) {
-    const candidate = join14(dir, "packages", "runtime", "bin", "openscout-runtime.mjs");
-    if (existsSync10(candidate)) {
-      return candidate;
-    }
-    const parent = dirname8(dir);
-    if (parent === dir)
-      break;
-    dir = parent;
-  }
-  return null;
-}
+import { dirname as dirname9 } from "path";
+import { fileURLToPath as fileURLToPath7 } from "url";
 function resolveJavaScriptRuntimeExecutable() {
-  const explicit = process.env.OPENSCOUT_RUNTIME_NODE_BIN?.trim();
-  if (explicit) {
-    if (existsSync10(explicit)) {
-      return explicit;
-    }
-    const found = tryWhich(explicit);
-    if (found) {
-      return found;
-    }
-    throw new Error(`OPENSCOUT_RUNTIME_NODE_BIN is set but not found: ${explicit}`);
-  }
-  const execBase = basename6(process.execPath).toLowerCase();
-  if (execBase.startsWith("node") || execBase.startsWith("bun")) {
-    return process.execPath;
-  }
-  const nodeOnPath = tryWhich("node");
-  if (nodeOnPath) {
-    return nodeOnPath;
-  }
-  const bunOnPath = tryWhich("bun");
-  if (bunOnPath) {
-    return bunOnPath;
+  const runtime = resolveJavaScriptRuntime({
+    env: process.env,
+    explicitEnvKeys: ["OPENSCOUT_RUNTIME_NODE_BIN"],
+    allowNode: true,
+    allowBun: true
+  });
+  if (runtime) {
+    return runtime.path;
   }
   throw new Error("No JavaScript runtime found for openscout-runtime script entry. Install Node.js or set OPENSCOUT_RUNTIME_NODE_BIN.");
 }
 function resolveRuntimeServiceEntrypoint() {
-  const explicit = process.env.OPENSCOUT_RUNTIME_BIN?.trim();
-  if (explicit) {
-    if (existsSync10(explicit)) {
-      return explicit;
-    }
-    const found = tryWhich(explicit);
-    if (found) {
-      return found;
-    }
-    throw new Error(`OPENSCOUT_RUNTIME_BIN is set but not found: ${explicit}`);
-  }
-  const onPath = tryWhich("openscout-runtime");
-  if (onPath) {
-    return onPath;
+  const installedExecutable = resolveExecutableFromSearch({
+    env: process.env,
+    envKeys: ["OPENSCOUT_RUNTIME_BIN"],
+    names: ["openscout-runtime"]
+  });
+  if (installedExecutable) {
+    return installedExecutable.path;
   }
-  const fromNodeModules = findNodeModulesRuntimeBin();
+  const fromNodeModules = resolveNodeModulesPackageEntrypoint(import.meta.url, ["@openscout", "runtime"], "bin/openscout-runtime.mjs");
   if (fromNodeModules) {
     return fromNodeModules;
   }
-  const monorepo = findMonorepoOpenscoutRuntimeBin();
-  if (monorepo) {
-    return monorepo;
+  const repoRoot = resolveOpenScoutRepoRoot({
+    startDirectories: [
+      process.env.OPENSCOUT_SETUP_CWD,
+      process.cwd(),
+      dirname9(fileURLToPath7(import.meta.url))
+    ]
+  });
+  const repoEntrypoint = resolveRepoEntrypoint(repoRoot, "packages/runtime/bin/openscout-runtime.mjs");
+  if (repoEntrypoint) {
+    return repoEntrypoint;
   }
   throw new Error("openscout-runtime not found on PATH. Install @openscout/runtime (e.g. npm i -g @openscout/runtime) or set OPENSCOUT_RUNTIME_BIN.");
 }
@@ -43624,12 +43924,14 @@ async function getRuntimeBrokerServiceStatus(options = {}) {
   return inflightBrokerStatus;
 }
 var BROKER_STATUS_CACHE_TTL_MS = 2000, cachedBrokerStatus = null, inflightBrokerStatus = null;
-var init_runtime_service_client = () => {};
+var init_runtime_service_client = __esm(() => {
+  init_tool_resolution();
+});
 
 // ../../apps/desktop/src/core/setup/command-lock.ts
-import { mkdir as mkdir8, open, readFile as readFile8, rm as rm6 } from "fs/promises";
+import { mkdir as mkdir8, open, readFile as readFile9, rm as rm6 } from "fs/promises";
 import { hostname as hostname4 } from "os";
-import { dirname as dirname9, join as join15 } from "path";
+import { dirname as dirname10, join as join15 } from "path";
 function scoutCoreCommandLockPath() {
   return join15(resolveOpenScoutSupportPaths().runtimeDirectory, "locks", SCOUT_CORE_COMMAND_LOCK_FILE);
 }
@@ -43655,7 +43957,7 @@ function isProcessAlive(pid) {
 }
 async function readLockPayload(lockPath) {
   try {
-    const raw = JSON.parse(await readFile8(lockPath, "utf8"));
+    const raw = JSON.parse(await readFile9(lockPath, "utf8"));
     if ((raw.command === "setup" || raw.command === "doctor" || raw.command === "runtimes") && typeof raw.pid === "number" && typeof raw.startedAt === "number" && typeof raw.host === "string") {
       return {
         command: raw.command,
@@ -43671,7 +43973,7 @@ async function readLockPayload(lockPath) {
 }
 async function acquireScoutCoreCommandLock(command) {
   const lockPath = scoutCoreCommandLockPath();
-  await mkdir8(dirname9(lockPath), { recursive: true });
+  await mkdir8(dirname10(lockPath), { recursive: true });
   for (let attempt = 0;attempt < 2; attempt += 1) {
     const payload = {
       command,
@@ -43814,8 +44116,8 @@ var init_service3 = __esm(() => {
 
 // ../../apps/desktop/src/shared/paths.ts
 import { existsSync as existsSync11, readFileSync as readFileSync6 } from "fs";
-import { dirname as dirname10, join as join16, resolve as resolve10 } from "path";
-import { fileURLToPath as fileURLToPath7 } from "url";
+import { dirname as dirname11, join as join16, resolve as resolve11 } from "path";
+import { fileURLToPath as fileURLToPath8 } from "url";
 function looksLikeWorkspaceRoot(candidate) {
   const packageJsonPath = join16(candidate, "package.json");
   if (!existsSync11(packageJsonPath)) {
@@ -43844,12 +44146,12 @@ function looksLikeSourceAppRoot(candidate) {
   return existsSync11(join16(candidate, "bin", "scout.ts"));
 }
 function findMatchingAncestor(startDirectory, predicate) {
-  let current = resolve10(startDirectory);
+  let current = resolve11(startDirectory);
   while (true) {
     if (predicate(current)) {
       return current;
     }
-    const parent = dirname10(current);
+    const parent = dirname11(current);
     if (parent === current) {
       return null;
     }
@@ -43857,7 +44159,7 @@ function findMatchingAncestor(startDirectory, predicate) {
   }
 }
 function defaultModuleDirectory() {
-  return dirname10(fileURLToPath7(import.meta.url));
+  return dirname11(fileURLToPath8(import.meta.url));
 }
 function uniqueResolutionStarts(options) {
   const starts = [
@@ -43866,7 +44168,7 @@ function uniqueResolutionStarts(options) {
     process.cwd(),
     options.moduleDirectory?.trim()
   ];
-  const resolvedStarts = starts.filter((value) => Boolean(value)).map((value) => resolve10(value));
+  const resolvedStarts = starts.filter((value) => Boolean(value)).map((value) => resolve11(value));
   return [...new Set(resolvedStarts)];
 }
 function resolveScoutWorkspaceRoot(options = {}) {
@@ -43895,7 +44197,7 @@ function resolveScoutAppRoot(options = {}) {
   }
   const workspaceRoot = resolveScoutWorkspaceRoot(options);
   for (const relativePath of [["apps", "desktop"], ["apps", "scout"], ["packages", "cli"]]) {
-    const candidate = resolve10(workspaceRoot, ...relativePath);
+    const candidate = resolve11(workspaceRoot, ...relativePath);
     if (looksLikeSourceAppRoot(candidate)) {
       return candidate;
     }
@@ -44265,7 +44567,7 @@ import {
   writeFileSync as writeFileSync4
 } from "fs";
 import { homedir as homedir10 } from "os";
-import { dirname as dirname11, join as join18 } from "path";
+import { dirname as dirname12, join as join18 } from "path";
 function localConfigHome() {
   return process.env.OPENSCOUT_HOME ?? join18(homedir10(), ".openscout");
 }
@@ -44307,9 +44609,12 @@ function validateLocalConfig(input) {
 function isValidPort(value) {
   return typeof value === "number" && Number.isInteger(value) && value > 0 && value < 65536;
 }
+function resolveWebPort() {
+  return loadLocalConfig().ports?.web ?? DEFAULT_LOCAL_CONFIG.ports.web;
+}
 function writeLocalConfig(config2) {
   const configPath = localConfigPath();
-  mkdirSync4(dirname11(configPath), { recursive: true });
+  mkdirSync4(dirname12(configPath), { recursive: true });
   const body = JSON.stringify({ ...config2, version: LOCAL_CONFIG_VERSION }, null, 2) + `
 `;
   const tmp = `${configPath}.tmp`;
@@ -44742,7 +45047,7 @@ class McpServer {
     let task = createTaskResult.task;
     const pollInterval = task.pollInterval ?? 5000;
     while (task.status !== "completed" && task.status !== "failed" && task.status !== "cancelled") {
-      await new Promise((resolve11) => setTimeout(resolve11, pollInterval));
+      await new Promise((resolve12) => setTimeout(resolve12, pollInterval));
       const updatedTask = await extra.taskStore.getTask(taskId);
       if (!updatedTask) {
         throw new McpError(ErrorCode.InternalError, `Task ${taskId} not found during polling`);
@@ -45291,7 +45596,41 @@ var init_mcp = __esm(() => {
 });
 
 // ../../apps/desktop/src/core/mcp/scout-mcp.ts
-import { basename as basename7, resolve as resolve11 } from "path";
+import { basename as basename7, resolve as resolve12 } from "path";
+function createAgentPickerFieldMeta(input) {
+  return {
+    kind: "agent-picker",
+    selection: input.selection,
+    sourceTool: "agents_search",
+    resolveTool: input.resolveTool,
+    sourceArguments: {
+      query: { from: "value" },
+      currentDirectory: { fromToolArgument: "currentDirectory" }
+    },
+    resultPath: ["structuredContent", "candidates"],
+    valueField: input.valueField,
+    labelField: "label",
+    descriptionField: "displayName",
+    badgeFields: ["harness", "workspace", "node"],
+    icon: scoutAgentAvatarMeta,
+    search: {
+      minQueryLength: 0,
+      debounceMs: 100,
+      cacheBy: ["currentDirectory"]
+    }
+  };
+}
+function createToolUiMeta(fields) {
+  const value = {
+    icon: scoutAgentToolIconMeta
+  };
+  if (fields && Object.keys(fields).length > 0) {
+    value.fields = fields;
+  }
+  return {
+    [SCOUT_MCP_UI_META_KEY]: value
+  };
+}
 function createTextContent(value) {
   return [{ type: "text", text: JSON.stringify(value, null, 2) }];
 }
@@ -45302,9 +45641,9 @@ function isSameProjectRoot(left, right) {
   if (!left || !right) {
     return false;
   }
-  return resolve11(left) === resolve11(right);
+  return resolve12(left) === resolve12(right);
 }
-function matchesObviousProjectLocalAlias2(value, query) {
+function matchesObviousProjectLocalAlias(value, query) {
   const normalized = normalizeSearchValue(value);
   if (!normalized || !query) {
     return false;
@@ -45324,7 +45663,7 @@ function scoreProjectLocalCandidate(candidate, currentProjectRoot, query) {
     candidate.displayName,
     candidate.agentId
   ];
-  const matches = values.filter((value) => matchesObviousProjectLocalAlias2(value, query));
+  const matches = values.filter((value) => matchesObviousProjectLocalAlias(value, query));
   if (matches.length === 0) {
     return -1;
   }
@@ -45803,7 +46142,7 @@ function createScoutMcpServer(options) {
     const resolvedCurrentDirectory = resolveToolCurrentDirectory(currentDirectory, options.defaultCurrentDirectory);
     const resolvedSenderId = await deps.resolveSenderId(senderId, resolvedCurrentDirectory, env);
     const card = await deps.createAgentCard({
-      projectPath: resolve11(projectPath?.trim() || resolvedCurrentDirectory),
+      projectPath: resolve12(projectPath?.trim() || resolvedCurrentDirectory),
       agentName: agentName?.trim() || undefined,
       displayName: displayName?.trim() || undefined,
       harness,
@@ -45825,7 +46164,7 @@ function createScoutMcpServer(options) {
     title: "Search Scout Agents",
     description: "Search the live Scout broker and discovered agent inventory for @mention candidates. Use this after whoami when you know roughly who you need but do not yet have an exact handle.",
     inputSchema: object2({
-      query: string2().optional(),
+      query: string2().describe("Partial handle, label, or display name to search for").optional(),
       currentDirectory: string2().optional(),
       limit: number2().int().min(1).max(50).optional()
     }),
@@ -45835,7 +46174,8 @@ function createScoutMcpServer(options) {
       idempotentHint: true,
       destructiveHint: false,
       openWorldHint: false
-    }
+    },
+    _meta: createToolUiMeta()
   }, async ({ query, currentDirectory, limit }) => {
     const resolvedCurrentDirectory = resolveToolCurrentDirectory(currentDirectory, options.defaultCurrentDirectory);
     const candidates = await deps.searchAgents({
@@ -45857,7 +46197,7 @@ function createScoutMcpServer(options) {
     title: "Resolve Scout Agent",
     description: "Resolve one exact Scout agent handle or return ambiguity details. Use this before send or ask when a short handle may be ambiguous.",
     inputSchema: object2({
-      label: string2().min(1),
+      label: string2().min(1).describe("Scout agent handle or selector, such as @talkie"),
       currentDirectory: string2().optional()
     }),
     outputSchema: resolveResultSchema,
@@ -45866,7 +46206,8 @@ function createScoutMcpServer(options) {
       idempotentHint: true,
       destructiveHint: false,
       openWorldHint: false
-    }
+    },
+    _meta: createToolUiMeta()
   }, async ({ label, currentDirectory }) => {
     const resolvedCurrentDirectory = resolveToolCurrentDirectory(currentDirectory, options.defaultCurrentDirectory);
     const resolution = await deps.resolveAgent({
@@ -45892,10 +46233,10 @@ function createScoutMcpServer(options) {
       body: string2().min(1),
       currentDirectory: string2().optional(),
       senderId: string2().optional(),
-      targetLabel: string2().optional(),
+      targetLabel: targetLabelInputSchema,
       channel: string2().optional(),
       shouldSpeak: boolean2().optional(),
-      mentionAgentIds: array(string2()).optional()
+      mentionAgentIds: mentionAgentIdsInputSchema
     }),
     outputSchema: sendResultSchema,
     annotations: {
@@ -45903,7 +46244,18 @@ function createScoutMcpServer(options) {
       idempotentHint: false,
       destructiveHint: false,
       openWorldHint: false
-    }
+    },
+    _meta: createToolUiMeta({
+      targetLabel: createAgentPickerFieldMeta({
+        selection: "single",
+        valueField: "label",
+        resolveTool: "agents_resolve"
+      }),
+      mentionAgentIds: createAgentPickerFieldMeta({
+        selection: "multiple",
+        valueField: "agentId"
+      })
+    })
   }, async ({
     body,
     currentDirectory,
@@ -45937,6 +46289,7 @@ function createScoutMcpServer(options) {
         messageId: result2.messageId ?? null,
         invokedTargetIds: result2.invokedTargetIds,
         unresolvedTargetIds: result2.unresolvedTargetIds,
+        targetDiagnostic: result2.targetDiagnostic ?? null,
         routeKind: result2.routeKind ?? null,
         routingError: result2.routingError ?? null
       };
@@ -45963,6 +46316,7 @@ function createScoutMcpServer(options) {
         messageId: result2.messageId ?? null,
         invokedTargetIds: result2.invokedTargets,
         unresolvedTargetIds: result2.unresolvedTargets,
+        targetDiagnostic: result2.targetDiagnostic ?? null,
         routeKind: result2.routeKind ?? null,
         routingError: result2.routingError ?? null
       };
@@ -45987,6 +46341,7 @@ function createScoutMcpServer(options) {
       messageId: result.messageId ?? null,
       invokedTargetIds: result.invokedTargets,
       unresolvedTargetIds: result.unresolvedTargets,
+      targetDiagnostic: result.targetDiagnostic ?? null,
       routeKind: result.routeKind ?? null,
       routingError: result.routingError ?? null
     };
@@ -46002,8 +46357,8 @@ function createScoutMcpServer(options) {
       body: string2().min(1),
       currentDirectory: string2().optional(),
       senderId: string2().optional(),
-      targetAgentId: string2().optional(),
-      targetLabel: string2().optional(),
+      targetAgentId: targetAgentIdInputSchema,
+      targetLabel: targetLabelInputSchema,
       workItem: workItemInputSchema.optional(),
       channel: string2().optional(),
       shouldSpeak: boolean2().optional(),
@@ -46019,7 +46374,18 @@ function createScoutMcpServer(options) {
       idempotentHint: false,
       destructiveHint: false,
       openWorldHint: false
-    }
+    },
+    _meta: createToolUiMeta({
+      targetAgentId: createAgentPickerFieldMeta({
+        selection: "single",
+        valueField: "agentId"
+      }),
+      targetLabel: createAgentPickerFieldMeta({
+        selection: "single",
+        valueField: "label",
+        resolveTool: "agents_resolve"
+      })
+    })
   }, async ({
     body,
     currentDirectory,
@@ -46151,7 +46517,7 @@ async function runScoutMcpServer(options) {
   const transport = new StdioServerTransport;
   await server.connect(transport);
 }
-var AGENT_STATE_VALUES, REGISTRATION_KIND_VALUES, RESOLVE_KIND_VALUES, MESSAGE_ROUTE_KIND_VALUES, MESSAGE_ROUTING_ERROR_VALUES, LOCAL_AGENT_HARNESS_VALUES, flightSchema, trackedWorkItemSchema, workItemInputSchema, waitingOnSchema, progressSchema, workItemUpdateSchema, agentCandidateSchema, scoutReturnAddressSchema, scoutAgentCardSchema, whoAmISchema, searchResultSchema, resolveResultSchema, sendResultSchema, cardCreateResultSchema, askResultSchema, workUpdateResultSchema;
+var AGENT_STATE_VALUES, REGISTRATION_KIND_VALUES, RESOLVE_KIND_VALUES, MESSAGE_ROUTE_KIND_VALUES, MESSAGE_ROUTING_ERROR_VALUES, LOCAL_AGENT_HARNESS_VALUES, SCOUT_MCP_UI_META_KEY = "openscout/ui", scoutAgentToolIconMeta, scoutAgentAvatarMeta, targetLabelInputSchema, targetAgentIdInputSchema, mentionAgentIdsInputSchema, flightSchema, trackedWorkItemSchema, workItemInputSchema, waitingOnSchema, progressSchema, workItemUpdateSchema, agentCandidateSchema, scoutReturnAddressSchema, scoutAgentCardSchema, whoAmISchema, searchResultSchema, resolveResultSchema, sendResultSchema, cardCreateResultSchema, askResultSchema, workUpdateResultSchema;
 var init_scout_mcp = __esm(async () => {
   init_mcp();
   init_stdio2();
@@ -46182,6 +46548,21 @@ var init_scout_mcp = __esm(async () => {
     "multi_target_requires_explicit_channel"
   ];
   LOCAL_AGENT_HARNESS_VALUES = ["claude", "codex"];
+  scoutAgentToolIconMeta = {
+    kind: "semantic",
+    name: "agent",
+    fallbackGlyph: "@"
+  };
+  scoutAgentAvatarMeta = {
+    kind: "agent-avatar",
+    monogramField: "displayName",
+    fallbackField: "handle",
+    colorSeedField: "agentId",
+    fallbackGlyph: "@"
+  };
+  targetLabelInputSchema = string2().describe("Scout agent handle to contact, such as @talkie").optional();
+  targetAgentIdInputSchema = string2().describe("Exact Scout agent id when already known, such as talkie.master.mini").optional();
+  mentionAgentIdsInputSchema = array(string2()).describe("Exact Scout agent ids to target directly when you already know them").optional();
   flightSchema = object2({
     id: string2(),
     invocationId: string2(),
@@ -46328,6 +46709,7 @@ var init_scout_mcp = __esm(async () => {
     messageId: string2().nullable(),
     invokedTargetIds: array(string2()),
     unresolvedTargetIds: array(string2()),
+    targetDiagnostic: object2({}).catchall(unknown()).nullable(),
     routeKind: _enum2(MESSAGE_ROUTE_KIND_VALUES).nullable(),
     routingError: _enum2(MESSAGE_ROUTING_ERROR_VALUES).nullable()
   });
@@ -46417,8 +46799,8 @@ __export(exports_menu, {
 import { spawnSync as spawnSync2 } from "child_process";
 import { existsSync as existsSync14 } from "fs";
 import { homedir as homedir11 } from "os";
-import { dirname as dirname12, join as join19, resolve as resolve12 } from "path";
-import { fileURLToPath as fileURLToPath8 } from "url";
+import { dirname as dirname13, join as join19, resolve as resolve13 } from "path";
+import { fileURLToPath as fileURLToPath9 } from "url";
 function renderMenuCommandHelp() {
   return [
     "scout menu \u2014 macOS menu bar app",
@@ -46501,23 +46883,23 @@ function runProcess(command, args, options) {
   };
 }
 function findRepoMenuHelper(startDirectory) {
-  let current = resolve12(startDirectory);
+  let current = resolve13(startDirectory);
   while (true) {
     const candidate = join19(current, "apps", "macos", "bin", "openscout-menu.ts");
     if (existsSync14(candidate)) {
       return candidate;
     }
-    const parent = dirname12(current);
+    const parent = dirname13(current);
     if (parent === current) {
       break;
     }
     current = parent;
   }
-  const sourceRelativeCandidate = fileURLToPath8(new URL("../../../../macos/bin/openscout-menu.ts", import.meta.url));
+  const sourceRelativeCandidate = fileURLToPath9(new URL("../../../../macos/bin/openscout-menu.ts", import.meta.url));
   return existsSync14(sourceRelativeCandidate) ? sourceRelativeCandidate : null;
 }
 function resolveRepoBundlePath(helperPath) {
-  return resolve12(dirname12(helperPath), "..", "dist", MENU_BUNDLE_NAME);
+  return resolve13(dirname13(helperPath), "..", "dist", MENU_BUNDLE_NAME);
 }
 function isMenuRunning(env) {
   return runProcess("pgrep", ["-x", MENU_PROCESS_NAME], { env, allowFailure: true }).ok;
@@ -46675,7 +47057,7 @@ var init_menu = __esm(() => {
 });
 
 // ../runtime/src/tailscale.ts
-import { readFile as readFile9 } from "fs/promises";
+import { readFile as readFile10 } from "fs/promises";
 import { execFile } from "child_process";
 import { promisify } from "util";
 function parseStatusJson(raw) {
@@ -46715,7 +47097,7 @@ function isBackendRunning(status) {
   return (status.BackendState ?? "").trim().toLowerCase() === "running";
 }
 async function readStatusJsonFromFile(filePath) {
-  const raw = await readFile9(filePath, "utf8");
+  const raw = await readFile10(filePath, "utf8");
   return parseStatusJson(raw);
 }
 async function readStatusJson() {
@@ -49336,15 +49718,30 @@ function saveTrustedPeer(peer) {
 function isTrustedPeer(publicKeyHex) {
   return loadTrustedPeers().has(publicKeyHex);
 }
-function createQRPayload(bridgePublicKey, relayUrl) {
+function createQRPayload(bridgePublicKey, relayUrl, fallbackRelayUrls = []) {
+  const fallbackRelays = normalizedRelayUrls(fallbackRelayUrls, relayUrl);
   return {
     v: QR_VERSION,
     relay: relayUrl,
+    ...fallbackRelays.length > 0 ? { fallbackRelays } : {},
     room: crypto.randomUUID(),
     publicKey: bytesToHex2(bridgePublicKey),
     expiresAt: Date.now() + QR_EXPIRY_MS
   };
 }
+function normalizedRelayUrls(urls, primaryRelayUrl) {
+  const seen = new Set([primaryRelayUrl.trim()]);
+  const normalized = [];
+  for (const url2 of urls) {
+    const trimmed = url2.trim();
+    if (!trimmed || seen.has(trimmed)) {
+      continue;
+    }
+    seen.add(trimmed);
+    normalized.push(trimmed);
+  }
+  return normalized;
+}
 function bytesToHex2(bytes) {
   return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
 }
@@ -50639,7 +51036,7 @@ var init_db_queries = __esm(() => {
 });
 
 // ../../apps/desktop/src/core/mobile/service.ts
-import { basename as basename8, resolve as resolve13 } from "path";
+import { basename as basename8, resolve as resolve14 } from "path";
 function normalizeTimestamp2(value) {
   if (!value)
     return null;
@@ -51028,7 +51425,7 @@ async function createScoutSession(input, currentDirectory, deviceId) {
   if (!rawWorkspaceId) {
     throw new Error(`Invalid workspaceId.`);
   }
-  const workspaceRoot = resolve13(rawWorkspaceId);
+  const workspaceRoot = resolve14(rawWorkspaceId);
   const projectName = basename8(workspaceRoot) || workspaceRoot;
   const workspace = {
     id: workspaceRoot,
@@ -52763,7 +53160,7 @@ import { Database as Database2 } from "bun:sqlite";
 import { mkdirSync as mkdirSync9, readFileSync as readFileSync13 } from "fs";
 import { connect as connectHttp2 } from "http2";
 import { createPrivateKey, sign as signWithKey } from "crypto";
-import { dirname as dirname13, join as join25 } from "path";
+import { dirname as dirname14, join as join25 } from "path";
 function resolveControlPlaneDbPath() {
   return join25(resolveOpenScoutSupportPaths().controlHome, "control-plane.sqlite");
 }
@@ -52779,7 +53176,7 @@ function writeDb() {
     dbHandle = null;
   }
   if (!dbHandle) {
-    mkdirSync9(dirname13(nextPath), { recursive: true });
+    mkdirSync9(dirname14(nextPath), { recursive: true });
     dbHandle = new Database2(nextPath, { create: true });
     dbPath = nextPath;
     ensureMobilePushSchema(dbHandle);
@@ -52995,7 +53392,7 @@ async function sendApnsAlertToRegistration(registration, alert) {
     },
     ...alert.payload ? { scout: alert.payload } : {}
   });
-  return new Promise((resolve14, reject) => {
+  return new Promise((resolve15, reject) => {
     const client = connectHttp2(authority);
     client.once("error", reject);
     const request = client.request({
@@ -53033,7 +53430,7 @@ async function sendApnsAlertToRegistration(registration, alert) {
         }
       }
       if (status === 200) {
-        resolve14({
+        resolve15({
           delivered: true,
           skipped: false,
           status,
@@ -53045,7 +53442,7 @@ async function sendApnsAlertToRegistration(registration, alert) {
       if (reason === "BadDeviceToken" || reason === "Unregistered") {
         deleteMobilePushRegistrationByToken(registration.pushToken);
       }
-      resolve14({
+      resolve15({
         delivered: false,
         skipped: false,
         status,
@@ -53290,23 +53687,23 @@ function bridgeEventIterable(bridge, signal) {
   return {
     [Symbol.asyncIterator]() {
       const buffer = [];
-      let resolve14 = null;
+      let resolve15 = null;
       let done = false;
       const unsub = bridge.onEvent((event) => {
         if (done)
           return;
         buffer.push(event);
-        if (resolve14) {
-          resolve14();
-          resolve14 = null;
+        if (resolve15) {
+          resolve15();
+          resolve15 = null;
         }
       });
       const cleanup = () => {
         done = true;
         unsub();
-        if (resolve14) {
-          resolve14();
-          resolve14 = null;
+        if (resolve15) {
+          resolve15();
+          resolve15 = null;
         }
       };
       signal?.addEventListener("abort", cleanup, { once: true });
@@ -53319,7 +53716,7 @@ function bridgeEventIterable(bridge, signal) {
               return { done: false, value: buffer.shift() };
             }
             await new Promise((r) => {
-              resolve14 = r;
+              resolve15 = r;
             });
           }
         },
@@ -54037,7 +54434,8 @@ var init_router = __esm(async () => {
 // ../../apps/desktop/src/core/pairing/runtime/bridge/relay-client.ts
 function connectToRelay(relayUrl, identity2, bridge, options = {}) {
   const { secure = true, events: events2 } = options;
-  const qrPayload = createQRPayload(identity2.publicKey, relayUrl);
+  const publicRelayUrl = options.publicRelayUrl?.trim() || relayUrl;
+  const qrPayload = createQRPayload(identity2.publicKey, publicRelayUrl, options.fallbackRelayUrls);
   let ws = null;
   let eventUnsub = null;
   let stopped = false;
@@ -54051,12 +54449,12 @@ function connectToRelay(relayUrl, identity2, bridge, options = {}) {
     const bridgeKeyHex = bytesToHex2(identity2.publicKey);
     const url2 = buildRelayUrl(relayUrl, qrPayload.room, bridgeKeyHex);
     console.log(`[relay-client] connecting to relay (room: ${qrPayload.room})`);
-    events2?.onConnecting?.({ relayUrl, room: qrPayload.room });
+    events2?.onConnecting?.({ relayUrl: publicRelayUrl, room: qrPayload.room });
     ws = new WebSocket(url2, relayWebSocketOptions(relayUrl));
     ws.addEventListener("open", () => {
       console.log(`[relay-client] connected to relay (room: ${qrPayload.room})`);
       backoff = INITIAL_BACKOFF_MS;
-      events2?.onConnected?.({ relayUrl, room: qrPayload.room });
+      events2?.onConnected?.({ relayUrl: publicRelayUrl, room: qrPayload.room });
     });
     ws.addEventListener("message", (event) => {
       handleRelaySocketMessage(event.data);
@@ -54064,7 +54462,7 @@ function connectToRelay(relayUrl, identity2, bridge, options = {}) {
     ws.addEventListener("close", (event) => {
       console.log(`[relay-client] disconnected (code: ${event.code}, reason: ${event.reason})`);
       events2?.onClosed?.({
-        relayUrl,
+        relayUrl: publicRelayUrl,
         room: qrPayload.room,
         code: event.code,
         reason: event.reason
@@ -54075,7 +54473,7 @@ function connectToRelay(relayUrl, identity2, bridge, options = {}) {
     ws.addEventListener("error", () => {
       const error48 = new Error("Relay websocket error");
       console.error("[relay-client] connection error");
-      events2?.onError?.({ relayUrl, room: qrPayload.room, error: error48 });
+      events2?.onError?.({ relayUrl: publicRelayUrl, room: qrPayload.room, error: error48 });
     });
   }
   function handleRelaySocketMessage(raw) {
@@ -54129,7 +54527,7 @@ function connectToRelay(relayUrl, identity2, bridge, options = {}) {
         replaceOlderPeerForSameDevice(peer);
         ensureBridgeEventSubscription();
         console.log(`[relay-client] secure handshake complete (peer: ${pubHex.slice(0, 12)}..., device: ${peer.deviceId}, client: ${clientId})`);
-        events2?.onPaired?.({ relayUrl, room: qrPayload.room, remotePublicKey });
+        events2?.onPaired?.({ relayUrl: publicRelayUrl, room: qrPayload.room, remotePublicKey });
         sendExistingSessions((json2) => {
           if (peer.transport.isReady()) {
             peer.transport.send(json2);
@@ -54142,7 +54540,7 @@ function connectToRelay(relayUrl, identity2, bridge, options = {}) {
       onError: (err) => {
         console.error("[relay-client] secure transport error:", err.message);
         log.error("trns:cry", `decrypt failed for ${clientId} \u2014 resetting handshake: ${err.message}`);
-        events2?.onError?.({ relayUrl, room: qrPayload.room, error: err });
+        events2?.onError?.({ relayUrl: publicRelayUrl, room: qrPayload.room, error: err });
         sendRelayClose(clientId, 4002, "Transport reset");
         teardownSecurePeer(clientId);
       },
@@ -54341,7 +54739,7 @@ function connectToRelay(relayUrl, identity2, bridge, options = {}) {
     if (stopped)
       return;
     console.log(`[relay-client] reconnecting in ${backoff}ms...`);
-    events2?.onReconnectScheduled?.({ relayUrl, room: qrPayload.room, delayMs: backoff });
+    events2?.onReconnectScheduled?.({ relayUrl: publicRelayUrl, room: qrPayload.room, delayMs: backoff });
     reconnectTimer = setTimeout(() => {
       reconnectTimer = null;
       connect();
@@ -56224,15 +56622,15 @@ function resolveSelfTuple(promise3) {
   return Unpromise.proxy(promise3).then(() => [promise3]);
 }
 function withResolvers() {
-  let resolve14;
+  let resolve15;
   let reject;
   const promise3 = new Promise((_resolve, _reject) => {
-    resolve14 = _resolve;
+    resolve15 = _resolve;
     reject = _reject;
   });
   return {
     promise: promise3,
-    resolve: resolve14,
+    resolve: resolve15,
     reject
   };
 }
@@ -56271,8 +56669,8 @@ function timerResource(ms) {
   return makeResource({ start() {
     if (timer)
       throw new Error("Timer already started");
-    const promise3 = new Promise((resolve14) => {
-      timer = setTimeout(() => resolve14(disposablePromiseTimerResult), ms);
+    const promise3 = new Promise((resolve15) => {
+      timer = setTimeout(() => resolve15(disposablePromiseTimerResult), ms);
     });
     return promise3;
   } }, () => {
@@ -56321,15 +56719,15 @@ function _takeWithGrace() {
   return _takeWithGrace.apply(this, arguments);
 }
 function createDeferred() {
-  let resolve14;
+  let resolve15;
   let reject;
   const promise3 = new Promise((res, rej) => {
-    resolve14 = res;
+    resolve15 = res;
     reject = rej;
   });
   return {
     promise: promise3,
-    resolve: resolve14,
+    resolve: resolve15,
     reject
   };
 }
@@ -57305,8 +57703,8 @@ var import_objectSpread2$13, jsonContentTypeHandler, formDataContentTypeHandler,
         status: "fulfilled",
         value
       };
-      subscribers === null || subscribers === undefined || subscribers.forEach(({ resolve: resolve14 }) => {
-        resolve14(value);
+      subscribers === null || subscribers === undefined || subscribers.forEach(({ resolve: resolve15 }) => {
+        resolve15(value);
       });
     });
     if ("catch" in thenReturn)
@@ -58190,8 +58588,8 @@ function startBridgeServerTRPC(options) {
           }
           const iterable = isObservable(result) ? observableToAsyncIterable(result, abortController.signal) : result;
           const iterator = iterable[Symbol.asyncIterator]();
-          const abortPromise = new Promise((resolve14) => {
-            abortController.signal.addEventListener("abort", () => resolve14("abort"), {
+          const abortPromise = new Promise((resolve15) => {
+            abortController.signal.addEventListener("abort", () => resolve15("abort"), {
               once: true
             });
           });
@@ -58553,6 +58951,8 @@ async function startPairingRuntime(options) {
   }
   const relayConnection = connectToRelay(relayUrl, identity2, bridge, {
     secure: true,
+    publicRelayUrl: options?.advertisedRelayUrl ?? undefined,
+    fallbackRelayUrls: options?.fallbackRelayUrls,
     events: options?.relayEvents
   });
   await autoStartConfiguredSessions(bridge, config2.sessions);
@@ -58632,6 +59032,7 @@ function startRelay(port, options = {}) {
   const roomByBridgeKey = new Map;
   const server = Bun.serve({
     port,
+    hostname: "0.0.0.0",
     ...options.tls ? {
       tls: {
         cert: Bun.file(options.tls.cert),
@@ -58852,7 +59253,7 @@ var BRIDGE_ABSENCE_GRACE_MS = 30000, ROOM_IDLE_TIMEOUT_MS = 60000;
 // ../../apps/desktop/src/core/pairing/runtime/relay-runtime.ts
 import { execSync as execSync4 } from "child_process";
 import { existsSync as existsSync19, mkdirSync as mkdirSync11, readdirSync as readdirSync4 } from "fs";
-import { homedir as homedir22 } from "os";
+import { homedir as homedir22, networkInterfaces } from "os";
 import { join as join27 } from "path";
 function findStoredCerts() {
   if (!existsSync19(PAIRING_DIR2)) {
@@ -58894,24 +59295,42 @@ function readTailscaleStatus2() {
     return null;
   }
 }
-function resolveRelayEndpointForTailscaleStatus(port, tailscale) {
+function resolveRelayEndpointForTailscaleStatus(port, tailscale, options = {}) {
   const backendState = tailscale?.backendState?.trim().toLowerCase() ?? "";
   const hostname5 = tailscale?.dnsName ?? null;
   const tailscaleRunning = backendState === "running" && tailscale?.online !== false && Boolean(hostname5);
-  const tls = resolveTls(tailscaleRunning ? hostname5 : null);
-  if (tailscaleRunning && hostname5 && tls) {
+  const tls = tailscaleRunning ? options.tls !== undefined ? options.tls : resolveTls(hostname5) : null;
+  const scheme = tls ? "wss" : "ws";
+  const connectUrl = `${scheme}://127.0.0.1:${port}`;
+  const localAddress = options.localAddress !== undefined ? normalizedOptionalAddress(options.localAddress) : findLocalNetworkAddress();
+  const localRelayUrl = localAddress ? `${scheme}://${localAddress}:${port}` : null;
+  const tailnetRelayUrl = tailscaleRunning && hostname5 ? `${scheme}://${hostname5}:${port}` : null;
+  const fallbackRelayUrls = tailnetRelayUrl && localRelayUrl ? [tailnetRelayUrl] : [];
+  if (localRelayUrl) {
+    return {
+      relayUrl: localRelayUrl,
+      connectUrl,
+      fallbackRelayUrls,
+      options: tls ? { tls } : {}
+    };
+  }
+  if (tailnetRelayUrl && tls) {
     return {
-      relayUrl: `wss://${hostname5}:${port}`,
+      relayUrl: tailnetRelayUrl,
+      connectUrl,
+      fallbackRelayUrls: [],
       options: { tls }
     };
   }
-  if (tailscaleRunning && hostname5) {
+  if (tailnetRelayUrl) {
     pairingLog.warn("relay", "tailscale is running without TLS; falling back to insecure websocket relay", {
       hostname: hostname5,
       port
     });
     return {
-      relayUrl: `ws://${hostname5}:${port}`,
+      relayUrl: tailnetRelayUrl,
+      connectUrl,
+      fallbackRelayUrls: [],
       options: {}
     };
   }
@@ -58924,7 +59343,9 @@ function resolveRelayEndpointForTailscaleStatus(port, tailscale) {
     });
   }
   return {
-    relayUrl: `ws://127.0.0.1:${port}`,
+    relayUrl: connectUrl,
+    connectUrl,
+    fallbackRelayUrls: [],
     options: {}
   };
 }
@@ -58977,16 +59398,87 @@ function resolveRelayEndpoint(port) {
 }
 function startManagedRelay(port = 7889) {
   const endpoint = resolveRelayEndpoint(port);
-  pairingLog.info("relay", "starting managed relay", { relay: endpoint.relayUrl, port });
+  pairingLog.info("relay", "starting managed relay", {
+    relay: endpoint.relayUrl,
+    connectUrl: endpoint.connectUrl,
+    fallbackRelayUrls: endpoint.fallbackRelayUrls,
+    port
+  });
   const relay = startRelay(port, endpoint.options);
   return {
     relayUrl: endpoint.relayUrl,
+    connectUrl: endpoint.connectUrl,
+    fallbackRelayUrls: endpoint.fallbackRelayUrls,
     stop() {
       pairingLog.info("relay", "stopping managed relay", { relay: endpoint.relayUrl, port });
       relay.stop();
     }
   };
 }
+function normalizedOptionalAddress(address) {
+  const trimmed = address?.trim();
+  return trimmed ? trimmed : null;
+}
+function findLocalNetworkAddress() {
+  const candidates = [];
+  const interfaces = networkInterfaces();
+  for (const [name, entries] of Object.entries(interfaces)) {
+    for (const entry of entries ?? []) {
+      if (entry.internal || entry.family !== "IPv4") {
+        continue;
+      }
+      if (!isPrivateIPv4(entry.address) || isLinkLocalIPv4(entry.address) || isTailscaleIPv4(entry.address)) {
+        continue;
+      }
+      candidates.push({ name, address: entry.address });
+    }
+  }
+  candidates.sort((left, right) => {
+    const leftScore = localInterfaceScore(left.name);
+    const rightScore = localInterfaceScore(right.name);
+    if (leftScore !== rightScore) {
+      return leftScore - rightScore;
+    }
+    return left.address.localeCompare(right.address);
+  });
+  return candidates[0]?.address ?? null;
+}
+function localInterfaceScore(name) {
+  if (/^en\d+$/i.test(name)) {
+    return 0;
+  }
+  if (/^bridge\d*$/i.test(name)) {
+    return 2;
+  }
+  return 1;
+}
+function isPrivateIPv4(address) {
+  const octets = parseIPv4(address);
+  if (!octets) {
+    return false;
+  }
+  const [first, second] = octets;
+  return first === 10 || first === 172 && second >= 16 && second <= 31 || first === 192 && second === 168;
+}
+function isLinkLocalIPv4(address) {
+  const octets = parseIPv4(address);
+  return Boolean(octets && octets[0] === 169 && octets[1] === 254);
+}
+function isTailscaleIPv4(address) {
+  const octets = parseIPv4(address);
+  return Boolean(octets && octets[0] === 100 && octets[1] >= 64 && octets[1] <= 127);
+}
+function parseIPv4(address) {
+  const octets = address.split(".");
+  if (octets.length !== 4) {
+    return null;
+  }
+  const numbers = octets.map((octet) => Number(octet));
+  if (numbers.some((value) => !Number.isInteger(value) || value < 0 || value > 255)) {
+    return null;
+  }
+  return numbers;
+}
 var PAIRING_DIR2;
 var init_relay_runtime = __esm(() => {
   init_log2();
@@ -59695,12 +60187,19 @@ async function startScoutPairingSession(input) {
   };
   const resolvedRelayUrl = input.forceManagedRelay ? null : input.relayUrl?.trim() || config3.relay;
   try {
-    const activeRelayUrl = resolvedRelayUrl ?? (() => {
+    const managedRelay = resolvedRelayUrl ? null : (() => {
       relay = startManagedRelay(config3.port + 1);
-      return relay.relayUrl;
+      return relay;
     })();
+    const activeRelayUrl = resolvedRelayUrl ?? managedRelay?.relayUrl;
+    const connectRelayUrl = resolvedRelayUrl ?? managedRelay?.connectUrl ?? managedRelay?.relayUrl;
+    if (!activeRelayUrl || !connectRelayUrl) {
+      throw new Error("Scout pairing relay URL is not configured.");
+    }
     runtime2 = await startPairingRuntime({
-      relayUrl: activeRelayUrl,
+      relayUrl: connectRelayUrl,
+      advertisedRelayUrl: activeRelayUrl,
+      fallbackRelayUrls: managedRelay?.fallbackRelayUrls,
       relayEvents: {
         onConnecting() {
           emitOrQueue(createStatusEvent("connecting", `Connecting to ${activeRelayUrl}`));
@@ -59855,8 +60354,8 @@ async function runPairCommand(context, args) {
   process.on("SIGINT", handleSignal);
   process.on("SIGTERM", handleSignal);
   try {
-    await new Promise((resolve14) => {
-      controller.signal.addEventListener("abort", () => resolve14(), { once: true });
+    await new Promise((resolve15) => {
+      controller.signal.addEventListener("abort", () => resolve15(), { once: true });
     });
   } finally {
     process.off("SIGINT", handleSignal);
@@ -59925,15 +60424,15 @@ __export(exports_server, {
   runServerCommand: () => runServerCommand,
   resolveScoutWebServerEntry: () => resolveScoutWebServerEntry,
   resolveScoutControlPlaneWebServerEntry: () => resolveScoutControlPlaneWebServerEntry,
-  resolveBunExecutable: () => resolveBunExecutable3,
+  resolveBunExecutable: () => resolveBunExecutable4,
   renderServerCommandHelp: () => renderServerCommandHelp,
   normalizeServerOpenPath: () => normalizeServerOpenPath
 });
 import { spawn as spawn5 } from "child_process";
-import { accessSync as accessSync2, constants as constants4, existsSync as existsSync20 } from "fs";
+import { existsSync as existsSync20, mkdirSync as mkdirSync12, openSync } from "fs";
 import { homedir as homedir23 } from "os";
-import { dirname as dirname14, join as join28, resolve as resolve14 } from "path";
-import { fileURLToPath as fileURLToPath9 } from "url";
+import { dirname as dirname15, join as join28, resolve as resolve15 } from "path";
+import { fileURLToPath as fileURLToPath10 } from "url";
 function renderServerCommandHelp() {
   return [
     "scout server \u2014 Scout web UI (Bun runtime)",
@@ -59948,11 +60447,11 @@ function renderServerCommandHelp() {
     "  open               Open the Scout web UI (starts server on demand if needed).",
     "",
     "Options:",
-    "  --port <n>        Listen port (default 3200; env OPENSCOUT_WEB_PORT)",
+    "  --port <n>        Listen port (default 3200; optional override OPENSCOUT_WEB_PORT)",
     "  --static          Serve built UI from disk",
-    "  --static-root DIR Static client root (env OPENSCOUT_WEB_STATIC_ROOT)",
-    "  --vite-url URL    Dev proxy target for non-API routes (env OPENSCOUT_WEB_VITE_URL)",
-    "  --cwd DIR         Workspace / setup root (env OPENSCOUT_SETUP_CWD)",
+    "  --static-root DIR Static client root (optional override OPENSCOUT_WEB_STATIC_ROOT)",
+    "  --vite-url URL    Dev proxy target for non-API routes (optional override OPENSCOUT_WEB_VITE_URL)",
+    "  --cwd DIR         Workspace / setup root (optional override OPENSCOUT_SETUP_CWD)",
     "  --path PATH       Browser path for `open` (default /)",
     "",
     "Requires `bun` on PATH."
@@ -59963,19 +60462,21 @@ function resolveScoutWebServerEntry() {
   return resolveScoutControlPlaneWebServerEntry();
 }
 function resolveScoutControlPlaneWebServerEntry() {
-  const mainDir = dirname14(fileURLToPath9(import.meta.url));
-  const bundled = join28(mainDir, "scout-control-plane-web.mjs");
-  if (existsSync20(bundled)) {
+  const bundled = resolveBundledEntrypoint(import.meta.url, "scout-control-plane-web.mjs");
+  if (bundled) {
     return bundled;
   }
-  const source = fileURLToPath9(new URL("../../../../../packages/web/server/index.ts", import.meta.url).href);
-  if (existsSync20(source)) {
+  const repoRoot = resolveOpenScoutRepoRoot({
+    startDirectories: [
+      process.env.OPENSCOUT_SETUP_CWD,
+      process.cwd(),
+      dirname15(fileURLToPath10(import.meta.url))
+    ]
+  });
+  const source = resolveRepoEntrypoint(repoRoot, "packages/web/server/index.ts");
+  if (source) {
     return source;
   }
-  const legacySource = fileURLToPath9(new URL("../../server/control-plane-index.ts", import.meta.url).href);
-  if (existsSync20(legacySource)) {
-    return legacySource;
-  }
   throw new ScoutCliError("Could not find Scout web server entry. Rebuild @openscout/scout or run from the OpenScout repository.");
 }
 function parseServerFlags(args) {
@@ -60047,46 +60548,17 @@ function parseServerFlags(args) {
   return { env, openPath };
 }
 function resolveBundledStaticClientRoot(entry, _mode) {
-  const entryDir = dirname14(entry);
+  const entryDir = dirname15(entry);
   const clientDirectory = join28(entryDir, "client");
   const indexPath = join28(clientDirectory, "index.html");
   return existsSync20(indexPath) ? clientDirectory : null;
 }
-function isExecutable4(filePath) {
-  if (!filePath) {
-    return false;
-  }
-  try {
-    accessSync2(filePath, constants4.X_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-function resolveBunExecutable3(env) {
-  const explicitPaths = [
-    env.SCOUT_BUN_BIN,
-    env.OPENSCOUT_BUN_BIN,
-    env.BUN_BIN
-  ].filter((candidate) => Boolean(candidate?.trim()));
-  for (const candidate of explicitPaths) {
-    if (isExecutable4(candidate)) {
-      return candidate;
-    }
-  }
-  const pathEntries = (env.PATH ?? "").split(":").filter(Boolean);
-  const commonDirectories = [
-    join28(homedir23(), ".bun", "bin"),
-    "/opt/homebrew/bin",
-    "/usr/local/bin"
-  ];
-  for (const directory of [...pathEntries, ...commonDirectories]) {
-    const candidate = join28(directory.replace(/^~(?=$|\/)/, homedir23()), "bun");
-    if (isExecutable4(candidate)) {
-      return candidate;
-    }
+function resolveBunExecutable4(env) {
+  const bun = resolveBunExecutable2(env);
+  if (bun) {
+    return bun.path;
   }
-  return "bun";
+  throw new ScoutCliError("Unable to locate Bun. Install Bun (https://bun.sh) or set OPENSCOUT_BUN_BIN.");
 }
 function buildMergedServerEnv(entry, mode, flagEnv) {
   const bundledStaticClientRoot = resolveBundledStaticClientRoot(entry, mode);
@@ -60156,13 +60628,13 @@ function resolveServerPort(env) {
     }
     return port;
   }
-  const fromFile = loadLocalConfig().ports?.web;
-  if (fromFile)
-    return fromFile;
-  return 3200;
+  return resolveWebPort();
 }
 function resolveExpectedCurrentDirectory(env) {
-  return resolve14(env.OPENSCOUT_SETUP_CWD?.trim() || process.cwd());
+  return resolveOpenScoutSetupContextRoot({
+    env,
+    fallbackDirectory: process.cwd()
+  });
 }
 function renderModeLabel(mode) {
   return "Scout web";
@@ -60259,12 +60731,19 @@ async function openBrowser(url2) {
     });
   });
 }
+function resolveScoutWebServerLogPath() {
+  const dir = join28(homedir23(), ".scout", "logs");
+  mkdirSync12(dir, { recursive: true });
+  return join28(dir, "web-server.log");
+}
 async function spawnDetachedServer(entry, env) {
-  const bunExecutable = resolveBunExecutable3(env);
+  const bunExecutable = resolveBunExecutable4(env);
+  const logPath = resolveScoutWebServerLogPath();
+  const logFd = openSync(logPath, "a");
   await new Promise((resolvePromise, rejectPromise) => {
     const child = spawn5(bunExecutable, ["run", entry], {
       detached: true,
-      stdio: "ignore",
+      stdio: ["ignore", logFd, logFd],
       env,
       windowsHide: true
     });
@@ -60286,7 +60765,7 @@ async function waitForScoutServer(port, mode, expectedCurrentDirectory) {
   while (Date.now() < deadline) {
     const probe = await probeScoutServer(port);
     if (probe.status === "healthy") {
-      const actualCurrentDirectory = resolve14(probe.health.currentDirectory);
+      const actualCurrentDirectory = resolve15(probe.health.currentDirectory);
       if (!isCurrentScoutWebSurface(probe.health.surface)) {
         throw new ScoutCliError(`port ${port} is serving Scout ${renderSurfaceLabel(probe.health.surface)}, not ${renderModeLabel(mode)}.`);
       }
@@ -60300,7 +60779,7 @@ async function waitForScoutServer(port, mode, expectedCurrentDirectory) {
     }
     await new Promise((resolvePromise) => setTimeout(resolvePromise, 250));
   }
-  throw new ScoutCliError(`timed out waiting for ${renderModeLabel(mode)} on port ${port}`);
+  throw new ScoutCliError(`timed out waiting for ${renderModeLabel(mode)} on port ${port}; check ${resolveScoutWebServerLogPath()} for the child process output`);
 }
 async function openScoutServer(options) {
   const port = resolveServerPort(options.env);
@@ -60308,7 +60787,7 @@ async function openScoutServer(options) {
   const browserUrl = new URL(normalizeServerOpenPath(options.openPath), `http://127.0.0.1:${port}`).toString();
   const probe = await probeScoutServer(port);
   if (probe.status === "healthy") {
-    const actualCurrentDirectory = resolve14(probe.health.currentDirectory);
+    const actualCurrentDirectory = resolve15(probe.health.currentDirectory);
     if (!isCurrentScoutWebSurface(probe.health.surface)) {
       throw new ScoutCliError(`port ${port} is already serving Scout ${renderSurfaceLabel(probe.health.surface)}, not ${renderModeLabel(options.mode)}.`);
     }
@@ -60354,7 +60833,7 @@ async function runServerCommand(context, args) {
     context.output.writeValue(result, renderServerOpenResult);
     return;
   }
-  const bunExecutable = resolveBunExecutable3(mergedEnv);
+  const bunExecutable = resolveBunExecutable4(mergedEnv);
   await new Promise((resolvePromise, rejectPromise) => {
     const child = spawn5(bunExecutable, ["run", selection.entry], {
       stdio: "inherit",
@@ -60387,6 +60866,8 @@ async function runServerCommand(context, args) {
 var SERVER_OPEN_TIMEOUT_MS = 15000, SERVER_HEALTH_TIMEOUT_MS = 1500;
 var init_server4 = __esm(() => {
   init_local_config();
+  init_tool_resolution();
+  init_setup();
   init_errors();
 });
 
@@ -60417,9 +60898,10 @@ async function runSpeakCommand(context, args) {
   const senderId = await resolveScoutSenderId(options.agentName, currentDirectory, context.env);
   const config3 = await loadScoutRelayConfig();
   const voice = getScoutVoiceForChannel(config3, "voice");
+  const body = await resolveMessageBody(options);
   await acquireScoutOnAir(senderId);
   try {
-    const clean3 = stripScoutAgentSelectorLabels(options.message);
+    const clean3 = stripScoutAgentSelectorLabels(body);
     if (clean3) {
       await speakScoutText(clean3, voice);
     }
@@ -60428,7 +60910,7 @@ async function runSpeakCommand(context, args) {
   }
   const result = await sendScoutMessage({
     senderId,
-    body: options.message,
+    body,
     channel: "voice",
     shouldSpeak: true,
     executionHarness: parseScoutHarness(options.harness),
@@ -60438,16 +60920,17 @@ async function runSpeakCommand(context, args) {
     throw new Error("broker is not reachable");
   }
   if (result.unresolvedTargets.length > 0) {
-    throw new Error(formatScoutSendRoutingError(result.unresolvedTargets));
+    throw new Error(formatScoutSendRoutingError(result));
   }
   context.output.writeValue({
-    message: options.message,
+    message: body,
     invokedTargets: result.invokedTargets,
     unresolvedTargets: result.unresolvedTargets
   }, renderScoutMessagePostResult);
 }
 var init_speak = __esm(async () => {
   init_context();
+  init_input_file();
   init_options();
   init_broker();
   await __promiseAll([
@@ -60505,8 +60988,8 @@ import { EventEmitter } from "events";
 import { Buffer as Buffer2 } from "buffer";
 import { Buffer as Buffer3 } from "buffer";
 import { EventEmitter as EventEmitter2 } from "events";
-import { resolve as resolve15, dirname as dirname15 } from "path";
-import { fileURLToPath as fileURLToPath10 } from "url";
+import { resolve as resolve16, dirname as dirname16 } from "path";
+import { fileURLToPath as fileURLToPath11 } from "url";
 import { resolve as resolve22, isAbsolute as isAbsolute5, parse as parse7 } from "path";
 import { existsSync as existsSync21 } from "fs";
 import { basename as basename11, join as join29 } from "path";
@@ -60516,7 +60999,7 @@ import { EventEmitter as EventEmitter3 } from "events";
 import path22 from "path";
 import { readFile as readFile22, writeFile as writeFile22, mkdir as mkdir22 } from "fs/promises";
 import * as path4 from "path";
-import { mkdir as mkdir9, readFile as readFile10, writeFile as writeFile8 } from "fs/promises";
+import { mkdir as mkdir9, readFile as readFile11, writeFile as writeFile8 } from "fs/promises";
 import * as path3 from "path";
 import { readdir as readdir3 } from "fs/promises";
 import { dlopen, toArrayBuffer as toArrayBuffer4, JSCallback, ptr as ptr4 } from "bun:ffi";
@@ -63641,13 +64124,13 @@ class DebounceController {
   }
   debounce(id, ms, fn) {
     const scopeMap = TIMERS_MAP.get(this.scopeId);
-    return new Promise((resolve17, reject) => {
+    return new Promise((resolve18, reject) => {
       if (scopeMap.has(id)) {
         clearTimeout(scopeMap.get(id));
       }
       const timerId = setTimeout(() => {
         try {
-          resolve17(fn());
+          resolve18(fn());
         } catch (error48) {
           reject(error48);
         }
@@ -63737,25 +64220,25 @@ function getParsers() {
         filetype: "javascript",
         aliases: ["javascriptreact"],
         queries: {
-          highlights: [resolve15(dirname15(fileURLToPath10(import.meta.url)), highlights_default)]
+          highlights: [resolve16(dirname16(fileURLToPath11(import.meta.url)), highlights_default)]
         },
-        wasm: resolve15(dirname15(fileURLToPath10(import.meta.url)), tree_sitter_javascript_default)
+        wasm: resolve16(dirname16(fileURLToPath11(import.meta.url)), tree_sitter_javascript_default)
       },
       {
         filetype: "typescript",
         aliases: ["typescriptreact"],
         queries: {
-          highlights: [resolve15(dirname15(fileURLToPath10(import.meta.url)), highlights_default2)]
+          highlights: [resolve16(dirname16(fileURLToPath11(import.meta.url)), highlights_default2)]
         },
-        wasm: resolve15(dirname15(fileURLToPath10(import.meta.url)), tree_sitter_typescript_default)
+        wasm: resolve16(dirname16(fileURLToPath11(import.meta.url)), tree_sitter_typescript_default)
       },
       {
         filetype: "markdown",
         queries: {
-          highlights: [resolve15(dirname15(fileURLToPath10(import.meta.url)), highlights_default3)],
-          injections: [resolve15(dirname15(fileURLToPath10(import.meta.url)), injections_default)]
+          highlights: [resolve16(dirname16(fileURLToPath11(import.meta.url)), highlights_default3)],
+          injections: [resolve16(dirname16(fileURLToPath11(import.meta.url)), injections_default)]
         },
-        wasm: resolve15(dirname15(fileURLToPath10(import.meta.url)), tree_sitter_markdown_default),
+        wasm: resolve16(dirname16(fileURLToPath11(import.meta.url)), tree_sitter_markdown_default),
         injectionMapping: {
           nodeTypes: {
             inline: "markdown_inline",
@@ -63778,16 +64261,16 @@ function getParsers() {
       {
         filetype: "markdown_inline",
         queries: {
-          highlights: [resolve15(dirname15(fileURLToPath10(import.meta.url)), highlights_default4)]
+          highlights: [resolve16(dirname16(fileURLToPath11(import.meta.url)), highlights_default4)]
         },
-        wasm: resolve15(dirname15(fileURLToPath10(import.meta.url)), tree_sitter_markdown_inline_default)
+        wasm: resolve16(dirname16(fileURLToPath11(import.meta.url)), tree_sitter_markdown_inline_default)
       },
       {
         filetype: "zig",
         queries: {
-          highlights: [resolve15(dirname15(fileURLToPath10(import.meta.url)), highlights_default5)]
+          highlights: [resolve16(dirname16(fileURLToPath11(import.meta.url)), highlights_default5)]
         },
-        wasm: resolve15(dirname15(fileURLToPath10(import.meta.url)), tree_sitter_zig_default)
+        wasm: resolve16(dirname16(fileURLToPath11(import.meta.url)), tree_sitter_zig_default)
       }
     ];
   }
@@ -63929,7 +64412,7 @@ class DownloadUtils {
       const cacheFile = path3.join(cacheDir, cacheSubdir, cacheFileName);
       await mkdir9(path3.dirname(cacheFile), { recursive: true });
       try {
-        const cachedContent = await readFile10(cacheFile);
+        const cachedContent = await readFile11(cacheFile);
         if (cachedContent.byteLength > 0) {
           console.log(`Loaded from cache: ${cacheFile} (${source})`);
           return { content: cachedContent, filePath: cacheFile };
@@ -63955,7 +64438,7 @@ class DownloadUtils {
     } else {
       try {
         console.log(`Loading from local path: ${source}`);
-        const content = await readFile10(source);
+        const content = await readFile11(source);
         return { content, filePath: source };
       } catch (error48) {
         return { error: `Error loading from local path ${source}: ${error48}` };
@@ -63982,7 +64465,7 @@ class DownloadUtils {
     } else {
       try {
         console.log(`Copying from local path: ${source}`);
-        const content = await readFile10(source);
+        const content = await readFile11(source);
         await writeFile8(targetPath, Buffer.from(content));
         return { content, filePath: targetPath };
       } catch (error48) {
@@ -93023,14 +93506,14 @@ See https://react.dev/link/invalid-hook-call for tips about how to debug and fix
       prevActScopeDepth !== actScopeDepth - 1 && console.error("You seem to have overlapping act() calls, this is not supported. Be sure to await previous act() calls before making a new one. ");
       actScopeDepth = prevActScopeDepth;
     }
-    function recursivelyFlushAsyncActWork(returnValue, resolve17, reject) {
+    function recursivelyFlushAsyncActWork(returnValue, resolve18, reject) {
       var queue = ReactSharedInternals.actQueue;
       if (queue !== null)
         if (queue.length !== 0)
           try {
             flushActQueue(queue);
             enqueueTask(function() {
-              return recursivelyFlushAsyncActWork(returnValue, resolve17, reject);
+              return recursivelyFlushAsyncActWork(returnValue, resolve18, reject);
             });
             return;
           } catch (error48) {
@@ -93038,7 +93521,7 @@ See https://react.dev/link/invalid-hook-call for tips about how to debug and fix
           }
         else
           ReactSharedInternals.actQueue = null;
-      0 < ReactSharedInternals.thrownErrors.length ? (queue = aggregateErrors(ReactSharedInternals.thrownErrors), ReactSharedInternals.thrownErrors.length = 0, reject(queue)) : resolve17(returnValue);
+      0 < ReactSharedInternals.thrownErrors.length ? (queue = aggregateErrors(ReactSharedInternals.thrownErrors), ReactSharedInternals.thrownErrors.length = 0, reject(queue)) : resolve18(returnValue);
     }
     function flushActQueue(queue) {
       if (!isFlushing) {
@@ -93214,14 +93697,14 @@ See https://react.dev/link/invalid-hook-call for tips about how to debug and fix
           didAwaitActCall || didWarnNoAwaitAct || (didWarnNoAwaitAct = true, console.error("You called act(async () => ...) without await. This could lead to unexpected testing behaviour, interleaving multiple act calls and mixing their scopes. You should - await act(async () => ...);"));
         });
         return {
-          then: function(resolve17, reject) {
+          then: function(resolve18, reject) {
             didAwaitActCall = true;
             thenable.then(function(returnValue) {
               popActScope(prevActQueue, prevActScopeDepth);
               if (prevActScopeDepth === 0) {
                 try {
                   flushActQueue(queue), enqueueTask(function() {
-                    return recursivelyFlushAsyncActWork(returnValue, resolve17, reject);
+                    return recursivelyFlushAsyncActWork(returnValue, resolve18, reject);
                   });
                 } catch (error$0) {
                   ReactSharedInternals.thrownErrors.push(error$0);
@@ -93232,7 +93715,7 @@ See https://react.dev/link/invalid-hook-call for tips about how to debug and fix
                   reject(_thrownError);
                 }
               } else
-                resolve17(returnValue);
+                resolve18(returnValue);
             }, function(error48) {
               popActScope(prevActQueue, prevActScopeDepth);
               0 < ReactSharedInternals.thrownErrors.length ? (error48 = aggregateErrors(ReactSharedInternals.thrownErrors), ReactSharedInternals.thrownErrors.length = 0, reject(error48)) : reject(error48);
@@ -93248,11 +93731,11 @@ See https://react.dev/link/invalid-hook-call for tips about how to debug and fix
       if (0 < ReactSharedInternals.thrownErrors.length)
         throw callback = aggregateErrors(ReactSharedInternals.thrownErrors), ReactSharedInternals.thrownErrors.length = 0, callback;
       return {
-        then: function(resolve17, reject) {
+        then: function(resolve18, reject) {
           didAwaitActCall = true;
           prevActScopeDepth === 0 ? (ReactSharedInternals.actQueue = queue, enqueueTask(function() {
-            return recursivelyFlushAsyncActWork(returnValue$jscomp$0, resolve17, reject);
-          })) : resolve17(returnValue$jscomp$0);
+            return recursivelyFlushAsyncActWork(returnValue$jscomp$0, resolve18, reject);
+          })) : resolve18(returnValue$jscomp$0);
         }
       };
     };
@@ -95733,8 +96216,8 @@ It can also happen if the client has a browser extension installed which messes
         currentEntangledActionThenable = {
           status: "pending",
           value: undefined,
-          then: function(resolve17) {
-            entangledListeners.push(resolve17);
+          then: function(resolve18) {
+            entangledListeners.push(resolve18);
           }
         };
       }
@@ -95758,8 +96241,8 @@ It can also happen if the client has a browser extension installed which messes
         status: "pending",
         value: null,
         reason: null,
-        then: function(resolve17) {
-          listeners.push(resolve17);
+        then: function(resolve18) {
+          listeners.push(resolve18);
         }
       };
       thenable.then(function() {
@@ -121741,14 +122224,14 @@ async function runScoutMonitorApp(options) {
   }
   const renderer = await createCliRenderer();
   let closed = false;
-  await new Promise((resolve17) => {
+  await new Promise((resolve18) => {
     const close = () => {
       if (closed) {
         return;
       }
       closed = true;
       renderer.destroy();
-      resolve17();
+      resolve18();
     };
     createRoot(renderer).render(/* @__PURE__ */ import_jsx_dev_runtime2.jsxDEV(ScoutMonitorApp, {
       currentDirectory: options.currentDirectory,
@@ -121797,7 +122280,7 @@ __export(exports_up, {
   runUpCommand: () => runUpCommand
 });
 import { existsSync as existsSync23 } from "fs";
-import { resolve as resolve17 } from "path";
+import { resolve as resolve18 } from "path";
 function looksLikePath(value) {
   return value.includes("/") || value.startsWith(".") || value.startsWith("~");
 }
@@ -121859,14 +122342,19 @@ async function runUpCommand(context, args) {
     throw new ScoutCliError("usage: scout up <name|path> [--name <alias>] [--harness <claude|codex>] [--model <model>]");
   }
   let projectPath;
-  if (looksLikePath(target) || existsSync23(resolve17(target))) {
-    projectPath = resolve17(target);
+  if (looksLikePath(target) || existsSync23(resolve18(target))) {
+    projectPath = resolve18(target);
   } else {
     const resolved = await resolveLocalAgentByName(target);
     if (!resolved) {
-      throw new ScoutCliError(`unknown agent "${target}" \u2014 not a registered name or valid path`);
+      const projectMatch = await resolveLocalAgentByName(target, { matchProjectName: true });
+      if (projectMatch) {
+        throw new ScoutCliError(`unknown agent "${target}" \u2014 that matches project "${projectMatch.projectRoot}", ` + `but the registered agent is "${projectMatch.agentId}". ` + `Use \`scout up ${projectMatch.agentId}\` or \`scout up "${projectMatch.projectRoot}"\`.`);
+      }
+      throw new ScoutCliError(`unknown agent "${target}" \u2014 not a registered agent name or valid path`);
     }
     projectPath = resolved.projectRoot;
+    agentName ??= resolved.definitionId;
   }
   const agent = await upScoutAgent({
     projectPath,
@@ -121980,7 +122468,7 @@ var init_whoami = __esm(async () => {
 });
 
 // ../../apps/desktop/src/cli/main.ts
-import { existsSync as existsSync25, readFileSync as readFileSync15, writeFileSync as writeFileSync9, statSync as statSync5, mkdirSync as mkdirSync12 } from "fs";
+import { existsSync as existsSync25, readFileSync as readFileSync15, writeFileSync as writeFileSync9, statSync as statSync5, mkdirSync as mkdirSync13 } from "fs";
 import { join as join32 } from "path";
 import { spawnSync as spawnSync3 } from "child_process";
 import { homedir as homedir24 } from "os";
@@ -122147,12 +122635,12 @@ function renderScoutHelp(version2 = "0.2.18") {
     "Global flags:",
     '  --json        Structured JSON (doctor: NDJSON stream; last object has phase "complete")',
     "",
-    "Implicit ask:",
-    "  scout @agent your request",
-    "  scout hey @agent can you review this?",
-    "  scout @agent.harness:codex use the Codex-backed one",
+    "Fast path:",
+    '  scout send "@hudson ready for review"          # tell / update in a DM',
+    '  scout ask --to hudson "review the parser"      # owned work / reply in a DM',
+    "  scout ask --to hudson --prompt-file ./handoff.md",
     "",
-    "Operator loop:",
+    "Orientation (only when route or sender is unclear):",
     "  scout whoami",
     "  scout who",
     "  scout latest",
@@ -122165,9 +122653,21 @@ function renderScoutHelp(version2 = "0.2.18") {
     "  scout card create                              # fresh reply-ready return address",
     '  scout broadcast "deploying in 15m"             # explicit shared broadcast',
     "",
+    "Implicit ask shortcut:",
+    "  scout @agent your request",
+    "  scout @agent --prompt-file ./handoff.md",
+    "  scout hey @agent can you review this?",
+    "  scout @agent.harness:codex use the Codex-backed one",
+    "",
+    "File-backed input:",
+    "  ask uses --prompt-file for the primary work prompt",
+    "  send/broadcast/speak use --message-file for the message body",
+    "  --body-file is accepted as the shared alias",
+    "",
     "One-to-one delegation:",
     '  scout ask --to hudson "review the parser"      # DM by default',
     '  scout ask --as premotion.master.mini --to hudson "build the editor"',
+    "  scout ask --to hudson --prompt-file ./handoff.md",
     "",
     "Routing:",
     '  scout send "@hudson ready for review"          # one target -> DM',
@@ -122195,6 +122695,16 @@ function renderScoutHelp(version2 = "0.2.18") {
 
 // ../../apps/desktop/src/cli/main.ts
 init_options();
+
+// ../../apps/desktop/src/cli/uptodate.ts
+function normalizeCliBinaryMtimeMs(value) {
+  return Math.floor(value);
+}
+function shouldRestartBrokerForCliMtime(currentMtimeMs, persistedMtimeMs) {
+  return normalizeCliBinaryMtimeMs(currentMtimeMs) > normalizeCliBinaryMtimeMs(persistedMtimeMs);
+}
+
+// ../../apps/desktop/src/cli/main.ts
 init_product();
 async function main3() {
   const input = parseScoutArgv(process.argv.slice(2));
@@ -122251,22 +122761,22 @@ function getScoutBinPath() {
 }
 async function ensureBrokerUptodate() {
   try {
-    const mtime = statSync5(getScoutBinPath()).mtimeMs;
+    const mtime = normalizeCliBinaryMtimeMs(statSync5(getScoutBinPath()).mtimeMs);
     const checkpointDir = join32(homedir24(), ".scout");
     const mtimePath = join32(checkpointDir, "cli-mtime");
     const lastMtime = existsSync25(mtimePath) ? Number(readFileSync15(mtimePath, "utf8").trim()) : 0;
-    if (mtime > lastMtime) {
+    if (shouldRestartBrokerForCliMtime(mtime, lastMtime)) {
       const uid = process.getuid();
       const plistPath = join32(homedir24(), "Library", "LaunchAgents", "dev.openscout.broker.plist");
       spawnSync3("launchctl", ["bootout", `gui/${uid}/dev.openscout.broker`], { stdio: "ignore" });
-      await new Promise((resolve18) => setTimeout(resolve18, 1500));
+      await new Promise((resolve19) => setTimeout(resolve19, 1500));
       spawnSync3("launchctl", ["bootstrap", `gui/${uid}`, plistPath], { stdio: "ignore" });
-      await new Promise((resolve18) => setTimeout(resolve18, 2000));
+      await new Promise((resolve19) => setTimeout(resolve19, 2000));
     }
     if (!existsSync25(checkpointDir)) {
-      mkdirSync12(checkpointDir, { recursive: true });
+      mkdirSync13(checkpointDir, { recursive: true });
     }
-    writeFileSync9(mtimePath, String(Math.floor(mtime)), { encoding: "utf8", flag: "w" });
+    writeFileSync9(mtimePath, String(mtime), { encoding: "utf8", flag: "w" });
   } catch {}
 }
 try {