ennodia 0.2.0 → 0.3.0-rc.2

package/src/compositional.ts

@@ -5,7 +5,7 @@ import {
   type BudgetCheck,
   type BudgetLimits,
 } from "./budget";
-import type { HarnessDiscovery } from "./harnesses";
+import type { HarnessAdapter, HarnessDiscovery } from "./harnesses";
 import type { RoutePlan } from "./planner";
 import type { RouteCategory } from "./priority";
 import type { TaskView } from "./tasks";
@@ -216,6 +216,7 @@ export function estimateCompositionalBudget(
   includeCompareEstimate: boolean,
   maxOutputChars: number | undefined,
   budget: BudgetLimits | undefined,
+  findAdapter?: (id: string) => HarnessAdapter | undefined,
 ): BudgetCheck {
   return checkBudgetLimits(
     estimateTaskBatchBudget({
@@ -225,7 +226,7 @@ export function estimateCompositionalBudget(
       })),
       comparePlanned: includeCompareEstimate,
       maxOutputChars,
-    }),
+    }, findAdapter),
     budget,
   );
 }
@@ -248,7 +249,7 @@ export function summarizeCompositionalTasks(input: {
     !knownIds.has(taskId)
   );
   const readyTaskIds = tasks
-    .filter((task) => task.status === "succeeded" && task.stdoutChars > 0)
+    .filter((task) => task.status === "succeeded" && hasTaskEvidence(task))
     .map((task) => task.id);
   const runningTaskIds = tasks
     .filter((task) => task.status === "running")
@@ -260,7 +261,7 @@ export function summarizeCompositionalTasks(input: {
     .filter((task) => task.status === "cancelled")
     .map((task) => task.id);
   const emptySucceededTaskIds = tasks
-    .filter((task) => task.status === "succeeded" && task.stdoutChars === 0)
+    .filter((task) => task.status === "succeeded" && !hasTaskEvidence(task))
     .map((task) => task.id);
   const compareReady = readyTaskIds.length >=
     (input.minSuccessfulTasksForCompare ?? 2);
@@ -329,3 +330,8 @@ function compositionalPrompt(
 
   return lines.join("\n");
 }
+
+function hasTaskEvidence(task: TaskView): boolean {
+  return task.hasOutput ?? Boolean(task.finalMessage?.trim() ||
+    task.finalMessageChars || task.stdoutChars || task.stderrChars);
+}

package/src/core.ts

@@ -1,3 +1,4 @@
+import { preparePragmaticRun, type PragmaticOptions } from "./pragmatic";
 import { createHash } from "node:crypto";
 import type {
   AdvisorExecutionPlan,
@@ -109,6 +110,8 @@ export type EnnodiaCoreOptions = {
 export type EnnodiaCoreShutdownOptions = TaskManagerShutdownOptions;
 
 export type RunEstimateInput = {
+  pragmatic?: PragmaticOptions;
+  model?: string;
   prompt: string;
   category?: RouteCategory;
   harnessId?: string;
@@ -360,6 +363,7 @@ export class EnnodiaCore {
       advisorModel: input.advisorModel,
       timeoutMs: input.timeoutMs,
       budget: input.budget,
+      findHarnessAdapter: this.findHarnessAdapter,
     });
   }
 
@@ -428,7 +432,7 @@ export class EnnodiaCore {
               harnessId: slice.harnessId,
             })),
             comparePlanned: false,
-          }),
+          }, this.findHarnessAdapter),
           input.budget,
         );
         assertBudgetWithinLimits(budget);
@@ -550,6 +554,7 @@ export class EnnodiaCore {
   }
 
   async estimateRun(input: RunEstimateInput): Promise<RunEstimate> {
+    input = preparePragmaticRun(input);
     const harnesses = await this.discoverHarnesses({ refresh: input.refresh });
     const plan = this.planRoute(input.prompt, harnesses, {
       category: input.category,
@@ -575,7 +580,7 @@ export class EnnodiaCore {
             selectedHarnessIds.length,
           ),
           maxOutputChars: input.maxOutputChars,
-        }),
+        }, this.findHarnessAdapter),
         input.budget,
       ),
     };
@@ -602,7 +607,7 @@ export class EnnodiaCore {
         prompt: input.prompt,
         selectedHarnessIds,
         comparePlanned: false,
-      }),
+      }, this.findHarnessAdapter),
       input.budget,
     );
     assertBudgetWithinLimits(budget);
@@ -612,25 +617,24 @@ export class EnnodiaCore {
       input.skillIds,
       input.cwd,
     );
-    const tasks = selectedHarnessIds.map((harnessId) => {
-      const { adapter, discovery } = this.requireRunnableHarness(
-        harnessId,
-        harnesses,
-      );
-
-      return this.taskManager.start(adapter, discovery, {
-        prompt: input.prompt,
-        cwd: input.cwd,
-        isolateCwd: input.isolateCwd,
-        model: input.model,
-        timeoutMs: input.timeoutMs,
-        skills,
-      }).task;
-    });
-    const unrequestedSkillsPresent = await this.findUnrequestedSkills(
-      input.cwd,
-      skills,
-    );
+    const unrequestedSkillsPresent = await this.findUnrequestedSkills(input.cwd, skills);
+    const tasks: TaskView[] = [];
+    try {
+      for (const harnessId of selectedHarnessIds) {
+        const { adapter, discovery } = this.requireRunnableHarness(harnessId, harnesses);
+        tasks.push(this.taskManager.start(adapter, discovery, {
+          prompt: input.prompt,
+          cwd: input.cwd,
+          isolateCwd: input.isolateCwd,
+          model: input.model,
+          timeoutMs: input.timeoutMs,
+          skills,
+        }).task);
+      }
+    } catch (error) {
+      for (const task of tasks) this.taskManager.cancel(task.id);
+      throw error;
+    }
 
     return { plan, tasks, budget, unrequestedSkillsPresent };
   }
@@ -649,6 +653,7 @@ export class EnnodiaCore {
         input.includeCompareEstimate ?? true,
         input.maxOutputChars,
         input.budget,
+        this.findHarnessAdapter,
       ),
     };
   }
@@ -663,34 +668,34 @@ export class EnnodiaCore {
       input.includeCompareEstimate ?? true,
       input.maxOutputChars,
       input.budget,
+      this.findHarnessAdapter,
     );
     assertBudgetWithinLimits(budget);
 
-    const tasks = resolvedSlices.map((slice, index) => {
-      const { adapter, discovery } = this.requireRunnableHarness(
-        slice.harnessId,
-        harnesses,
-      );
-
-      return {
-        sliceId: slice.id,
-        sliceTitle: slice.title,
-        harnessId: slice.harnessId,
-        routeCategory: slice.plan.category,
-        task: this.taskManager.start(adapter, discovery, {
-          prompt: slice.prompt,
-          cwd: input.cwd,
-          isolateCwd: input.isolateCwd,
-          model: slice.model,
-          timeoutMs: input.timeoutMs,
-          skills: sliceSkills[index] ?? [],
-        }).task,
-      };
-    });
-    const unrequestedSkillsPresent = await this.findUnrequestedSkills(
-      input.cwd,
-      requestedSkills,
-    );
+    const unrequestedSkillsPresent = await this.findUnrequestedSkills(input.cwd, requestedSkills);
+    const tasks: CompositionalStart["tasks"] = [];
+    try {
+      for (const [index, slice] of resolvedSlices.entries()) {
+        const { adapter, discovery } = this.requireRunnableHarness(slice.harnessId, harnesses);
+        tasks.push({
+          sliceId: slice.id,
+          sliceTitle: slice.title,
+          harnessId: slice.harnessId,
+          routeCategory: slice.plan.category,
+          task: this.taskManager.start(adapter, discovery, {
+            prompt: slice.prompt,
+            cwd: input.cwd,
+            isolateCwd: input.isolateCwd,
+            model: slice.model,
+            timeoutMs: input.timeoutMs,
+            skills: sliceSkills[index] ?? [],
+          }).task,
+        });
+      }
+    } catch (error) {
+      for (const started of tasks) this.taskManager.cancel(started.task.id);
+      throw error;
+    }
 
     return {
       tasks,
@@ -902,6 +907,7 @@ export class EnnodiaCore {
       name: discovery.name,
       runnable: true,
       capabilities: [...new Set(discovery.capabilities)].sort(),
+      ...(discovery.inputGuidance ? { inputGuidance: [...discovery.inputGuidance] } : {}),
       allowedModelIds: [
         ...new Set(input.allowedModels?.[discovery.id] ?? []),
       ].sort(),

package/src/diagnosis.ts

@@ -42,9 +42,12 @@ export function diagnoseTasks(tasks: TaskView[]): TaskDiagnosis | undefined {
 }
 
 function likelyCause(tasks: TaskView[]): string {
+  if (tasks.every(hasAuthenticationError)) {
+    return "Agent authentication failed. This attempt did not establish how the selected model would handle the task.";
+  }
   if (tasks.every((task) => task.timedOut)) {
     if (tasks.some(outputChars) && tasks.some(hasRecentOutput)) {
-      return "Task needed more time; at least one provider was still producing output before the deadline.";
+      return "The task produced output near its deadline but did not return a completed result.";
     }
 
     if (tasks.some(outputChars)) {
@@ -75,8 +78,12 @@ function suggestions(
 ): string[] {
   const result = new Set<string>();
 
+  if (tasks.some(hasAuthenticationError)) {
+    result.add("Sign in through the affected agent's supported CLI, then retry the same task.");
+  }
+
   if (tasks.some((task) => task.timedOut)) {
-    result.add("Retry the timed-out provider with a longer timeoutMs.");
+    result.add("Inspect the attempt before retrying. Narrow the task, adjust its execution settings, or allow more time if justified.");
   }
 
   if (hasPartialOutput) {
@@ -85,7 +92,9 @@ function suggestions(
 
   if (tasks.some((task) => task.exitCode !== undefined && task.exitCode !== 0)) {
     result.add("Inspect stderr and task events with ennodia_get_task.");
-    result.add("Retry with a different harness if the provider command looks broken.");
+    if (!tasks.every(hasAuthenticationError)) {
+      result.add("Check the requested model and command configuration before retrying.");
+    }
   }
 
   if (tasks.some((task) => task.drainTimedOut)) {
@@ -99,6 +108,11 @@ function suggestions(
   return [...result];
 }
 
+function hasAuthenticationError(task: TaskView): boolean {
+  return !task.timedOut && /^(?:Error: )?(?:Failed to authenticate:|OAuth session expired|Authentication failed:|Not logged in\b)/im
+    .test(`${task.stdout}\n${task.stderr}`);
+}
+
 function summaryLine(task: TaskView): string {
   const status = task.timedOut ? "timed out" : task.status;
   const facts = [

package/src/harnesses.ts

@@ -1,4 +1,5 @@
 import { existsSync } from "node:fs";
+import { signalOwnedProcess } from "./process";
 import { type Skill } from "./skills";
 
 export type HarnessKind = "cli" | "app";
@@ -43,9 +44,13 @@ export type HarnessAdapter = {
   versionArgs?: string[];
   capabilities: string[];
   notes?: string[];
+  /** Input preparation guidance, not a guarantee of model or tool access. */
+  inputGuidance?: string[];
   buildCommand?: (commandPath: string, input: HarnessRunInput) => CommandSpec;
   /** Best-effort usage extraction from a finished task's captured output. */
   extractUsage?: (stdout: string, stderr: string) => HarnessUsage | undefined;
+  /** Some public CLIs report a semantic failure with exit code zero. */
+  failureReason?: (stdout: string, stderr: string) => string | undefined;
 };
 
 export type HarnessDiscovery = {
@@ -59,6 +64,7 @@ export type HarnessDiscovery = {
   version?: string;
   capabilities: string[];
   notes: string[];
+  inputGuidance?: string[];
 };
 
 export type DiscoverHarnessesOptions = {
@@ -81,6 +87,29 @@ let cachedDiscovery:
   | undefined;
 let inFlightDiscovery: Promise<HarnessDiscovery[]> | undefined;
 
+export const MULTIMODAL_INPUT_GUIDANCE = [
+  "Ennodia passes text prompts and local file paths, not media attachments. Native input depends on the selected harness, model, file tools, permissions, and format. Missing guidance means unverified access.",
+  "When native listening or viewing is required, first load one small sample with native file tools. Report the file, inspected range, tool, and content-specific evidence, or the exact blocking error. A transcript, DSP score, or extracted frame is not equivalent evidence.",
+  "For media comparisons, use matching excerpts and an original reference. Separate cleanup quality from voice or image fidelity. Report conversions and limitations; a successful process exit does not establish successful media inspection.",
+];
+
+export function hasMultimodalInput(prompt: string): boolean {
+  return /\b(audio|video|image|multimodal|listen|listening|sound|speech|voice|recordings?|footage)\b|\.(mp3|wav|flac|m4a|aac|opus|ogg|ogv|mp4|mov|webm|png|jpe?g|webp)\b/i.test(prompt);
+}
+
+/** Keep preparation instructions out of unrelated work and internal text judges. */
+export function withInputGuidance(
+  prompt: string,
+  adapter?: Pick<HarnessAdapter, "inputGuidance">,
+): string {
+  if (!hasMultimodalInput(prompt) || /^ENNODIA_(?:COMPARE|PLAN_ADVISOR)/.test(prompt)) {
+    return prompt;
+  }
+  return `${prompt}\n\nEnnodia media input guidance (applies when native media inspection is required):\n${
+    (adapter?.inputGuidance ?? MULTIMODAL_INPUT_GUIDANCE).map((note) => `- ${note}`).join("\n")
+  }`;
+}
+
 export const harnessAdapters: HarnessAdapter[] = [
   {
     id: "claude-code",
@@ -102,7 +131,7 @@ export const harnessAdapters: HarnessAdapter[] = [
         args.push("--model", input.model);
       }
 
-      args.push(input.prompt);
+      args.push("--", input.prompt);
       return { command: commandPath, args, cwd: input.cwd };
     },
   },
@@ -137,7 +166,7 @@ export const harnessAdapters: HarnessAdapter[] = [
         args.push("-o", input.finalMessagePath);
       }
 
-      args.push(input.prompt);
+      args.push("--", input.prompt);
       return { command: commandPath, args, cwd: input.cwd };
     },
     extractUsage: (stdout) => {
@@ -169,7 +198,7 @@ export const harnessAdapters: HarnessAdapter[] = [
         args.push("--model", input.model);
       }
 
-      args.push(input.prompt);
+      args.push("--", input.prompt);
       return { command: commandPath, args, cwd: input.cwd };
     },
   },
@@ -201,7 +230,7 @@ export const harnessAdapters: HarnessAdapter[] = [
         args.push("--model", input.model);
       }
 
-      args.push(input.prompt);
+      args.push("--", input.prompt);
       return { command: commandPath, args, cwd: input.cwd };
     },
   },
@@ -256,7 +285,7 @@ export const harnessAdapters: HarnessAdapter[] = [
         args.push("--model", input.model);
       }
 
-      args.push(input.prompt);
+      args.push("--", input.prompt);
       return { command: commandPath, args, cwd: input.cwd };
     },
   },
@@ -281,7 +310,7 @@ export const harnessAdapters: HarnessAdapter[] = [
         args.push("--model", input.model);
       }
 
-      args.push(input.prompt);
+      args.push("--", input.prompt);
       return { command: commandPath, args, cwd: input.cwd };
     },
   },
@@ -296,11 +325,22 @@ export const harnessAdapters: HarnessAdapter[] = [
       "/Applications/Antigravity IDE.app",
     ],
     capabilities: ["ide", "browser-automation", "agents", "non-interactive-cli"],
+    inputGuidance: [
+      ...MULTIMODAL_INPUT_GUIDANCE,
+      "Antigravity headless input is text-only, including stream-json content blocks. Put local paths in the prompt and use the worker's native view_file tool when available; do not send Gemini API attachment blocks to agy. https://antigravity.google/docs/cli/headless/",
+      "Observed 2026-09-10 with agy 1.2.0 and gemini-3.8-flash-medium: an eight-second MP3 loaded through view_file and returned spoken words absent from the prompt. Start with a short MP3 probe for this route, then compare matched samples after confirming native access.",
+      "In that same case, FLAC was rejected as unsupported MIME audio/x-flac; four WAV samples timed out without output. These are scoped observations, not a universal FLAC/WAV support rule. CLI release notes list broader audio support: https://antigravity.google/changelog",
+      "Use native file tools first. Headless command permission denials cannot be approved interactively; report the blocked operation and keep normal permission settings. Do not keep guessing formats or repeat an unchanged failed request.",
+    ],
     notes: [
       "Runs through the supported `agy` CLI surface.",
       "Defaults to Antigravity sandbox mode for Ennodia-launched tasks.",
       "Passes the prompt as the value of Antigravity's non-interactive `--print` option.",
     ],
+    failureReason: (stdout, stderr) => !stdout.trim() &&
+      /^jetski: no output produced\b/m.test(stderr)
+      ? "Antigravity returned no answer. Check the required tool access in its normal permission settings."
+      : undefined,
     buildCommand: (commandPath, input) => {
       const args = [
         "--sandbox",
@@ -367,7 +407,15 @@ async function discoverHarness(
     .find((match): match is string => Boolean(match));
 
   const appPath = adapter.appPaths?.find((path) => existsSync(path));
-  const version = commandPath ? await readVersion(commandPath, adapter) : undefined;
+  let version: string | undefined;
+  const notes = [...(adapter.notes ?? [])];
+  if (commandPath) {
+    try {
+      version = await readVersion(commandPath, adapter);
+    } catch (error) {
+      notes.push(`Version check failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
   const available = Boolean(commandPath || appPath);
   const runnable = Boolean(commandPath && adapter.buildCommand);
 
@@ -381,7 +429,8 @@ async function discoverHarness(
     appPath,
     version,
     capabilities: adapter.capabilities,
-    notes: adapter.notes ?? [],
+    notes,
+    ...(adapter.inputGuidance ? { inputGuidance: [...adapter.inputGuidance] } : {}),
   };
 }
 
@@ -396,6 +445,8 @@ async function readVersion(
   const result = await capture(commandPath, adapter.versionArgs, {
     timeoutMs: DEFAULT_VERSION_TIMEOUT_MS,
   });
+  if (result.timedOut) throw new Error("Version probe timed out.");
+  if (result.exitCode !== 0) throw new Error(`Version probe exited with code ${result.exitCode}.`);
 
   const text = `${result.stdout}\n${result.stderr}`.trim();
   return text.split(/\r?\n/).find((line) => line.trim())?.trim();
@@ -406,41 +457,49 @@ async function capture(
   args: string[],
   options: { timeoutMs: number },
 ): Promise<CaptureResult> {
-  const process = Bun.spawn({
+  const child = Bun.spawn({
     cmd: [command, ...args],
     stdout: "pipe",
     stderr: "pipe",
+    detached: process.platform !== "win32",
   });
 
   let timedOut = false;
-  const timeout = setTimeout(() => {
-    timedOut = true;
-    process.kill();
-  }, options.timeoutMs);
+  let timeout: Timer | undefined;
+  const readers = [child.stdout.getReader(), child.stderr.getReader()];
+  const output = ["", ""];
+  const drained = Promise.all(readers.map(async (reader, index) => {
+    const decoder = new TextDecoder();
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        output[index] = (output[index] + decoder.decode(value, { stream: true })).slice(0, 8_000);
+      }
+      output[index] += decoder.decode();
+    } catch { /* cancellation closes a stalled pipe */ }
+    finally { reader.releaseLock(); }
+  }));
 
   try {
-    const [stdout, stderr, exitCode] = await Promise.all([
-      streamToText(process.stdout),
-      streamToText(process.stderr),
-      process.exited,
+    const exitCode = await Promise.race([
+      Promise.all([drained, child.exited]).then(([, code]) => code),
+      new Promise<null>((resolve) => {
+        timeout = setTimeout(() => {
+          timedOut = true;
+          signalOwnedProcess(child, "SIGKILL");
+          for (const reader of readers) void reader.cancel().catch(() => undefined);
+          resolve(null);
+        }, options.timeoutMs);
+      }),
     ]);
-
-    return { stdout, stderr, exitCode, timedOut };
+    return { stdout: output[0], stderr: output[1], exitCode, timedOut };
   } finally {
     clearTimeout(timeout);
+    if (!timedOut) signalOwnedProcess(child, "SIGKILL");
   }
 }
 
-async function streamToText(
-  stream: ReadableStream<Uint8Array> | null,
-): Promise<string> {
-  if (!stream) {
-    return "";
-  }
-
-  return await new Response(stream).text();
-}
-
 function toGoDuration(timeoutMs = 5 * 60 * 1000): string {
   const seconds = Math.max(1, Math.ceil(timeoutMs / 1000));
   return `${seconds}s`;

package/src/history.ts

@@ -60,10 +60,13 @@ export class FileHistorySink implements HistorySink {
 
   async recordRun(snapshot: RunHistorySnapshot): Promise<void> {
     await mkdir(this.dir, { recursive: true, mode: 0o700 });
+    // Frame each append with a leading newline so a previous truncated record
+    // cannot swallow the next receipt. Keep the delimiter and record in one
+    // append; never read/truncate the shared file to repair it.
     // Append-only hot path: an interrupted write can lose at most this
     // snapshot, and concurrent writers (MCP and IO processes share the
     // default directory) cannot clobber each other's lines.
-    await appendFile(this.path, `${serialize(snapshot)}\n`, { mode: 0o600 });
+    await appendFile(this.path, `\n${serialize(snapshot)}\n`, { mode: 0o600 });
     await this.compactIfNeeded();
   }
 

package/src/index.ts

@@ -1,3 +1,4 @@
+export { pragmaticSchema, type PragmaticOptions } from "./pragmatic";
 export {
   createEnnodiaServer,
   shutdownEnnodia,

package/src/plan-advice.ts

@@ -97,6 +97,7 @@ export type PlanAdviceManagerStartInput = {
   advisorModel?: string;
   timeoutMs?: number;
   budget?: BudgetLimits;
+  findHarnessAdapter?: (id: string) => HarnessAdapter | undefined;
 };
 
 export type PlanAdviceRevalidationContext = {
@@ -117,6 +118,7 @@ type InternalPlanAdvice = {
   advisorModel?: string;
   advisorTimeoutMs: number;
   budgetLimits?: BudgetLimits;
+  findHarnessAdapter?: PlanAdviceManagerStartInput["findHarnessAdapter"];
   advisorBudget: BudgetCheck;
   executionBudget?: BudgetCheck;
   proposal?: AdvisorPlanProposal;
@@ -167,7 +169,7 @@ export class PlanAdviceManager {
           harnessId: input.advisor.adapter.id,
         }],
         comparePlanned: false,
-      }),
+      }, () => input.advisor.adapter),
       input.budget,
     );
     assertBudgetWithinLimits(advisorBudget);
@@ -208,6 +210,7 @@ export class PlanAdviceManager {
       advisorTimeoutMs: advisorTask.timeoutMs ??
         input.timeoutMs ?? DEFAULT_ADVISOR_TIMEOUT_MS,
       budgetLimits: input.budget ? { ...input.budget } : undefined,
+      findHarnessAdapter: input.findHarnessAdapter,
       advisorBudget,
       issues: [],
       createdAtMs: now,
@@ -386,7 +389,7 @@ export class PlanAdviceManager {
             harnessId: slice.harnessId,
           })),
           comparePlanned: false,
-        }),
+        }, record.findHarnessAdapter),
         record.budgetLimits,
       );
       record.executionBudget = executionBudget;

package/src/planner.ts

@@ -1,4 +1,5 @@
 import type { HarnessDiscovery } from "./harnesses";
+import { hasMultimodalInput, MULTIMODAL_INPUT_GUIDANCE } from "./harnesses";
 import {
   CATEGORY_HARNESS_PRIORITIES,
   type RouteCategory,
@@ -11,6 +12,7 @@ export type RoutePlan = {
   selected?: string;
   parallelSuggested: boolean;
   compareSuggested: boolean;
+  inputGuidance?: string[];
 };
 
 export type PlanRouteOptions = {
@@ -26,6 +28,10 @@ export function planRoute(
   const runnable = harnesses.filter((harness) => harness.runnable);
   const runnableIds = new Set(runnable.map((harness) => harness.id));
   const reasons: string[] = [];
+  const audioInspectionSignals = /\bnative audio\b|\baudio listening\b|\blistening comparison\b|\blisten to\b[^.!?\n]{0,80}\b(audio|recordings?|files?|samples?)\b|\b(compare|assess|judge)\b[^.!?\n]{0,60}\b(audio|recordings?|voice|sound)\b/.test(lower);
+  const requestedAction = lower.replace(/^\s*(?:please\s+)?(?:(?:can|could|would|will)\s+you\s+|i\s+(?:want|need)\s+you\s+to\s+)?(?:please\s+)?/, "");
+  const softwareMaintenance = /^(fix|implement|refactor|debug)\b|^write\b[^.!?\n]{0,40}\b(script|function|tests?)\b|^review (?:the )?(code|implementation)\b/.test(requestedAction);
+  const nativeAudioProbe = !options.category && audioInspectionSignals && !softwareMaintenance;
 
   let category: RouteCategory = "general";
   const strongBrowserSignals =
@@ -48,6 +54,9 @@ export function planRoute(
   if (options.category) {
     category = options.category;
     reasons.push("Caller-provided category.");
+  } else if (nativeAudioProbe) {
+    category = "general";
+    reasons.push("The task needs native audio inspection. Start with one capability probe; compare after native access is confirmed.");
   } else if (browserSignals) {
     category = "browser";
     reasons.push("The prompt mentions a website, UI, or rendered page.");
@@ -70,11 +79,16 @@ export function planRoute(
       (id) => !CATEGORY_HARNESS_PRIORITIES[category].includes(id),
     ),
   ];
+  if (nativeAudioProbe && runnableIds.has("antigravity")) {
+    candidates.splice(candidates.indexOf("antigravity"), 1);
+    candidates.unshift("antigravity");
+    reasons.push("Antigravity has an observed native-audio probe path. This is a probe candidate, not verified model access.");
+  }
 
   const complexSignals = /\b(audit|assess|compare|critique|evaluate|inspect|judge|multiple|parallel|review|several|tradeoff|best)\b/.test(
     lower,
   );
-  const parallelSuggested = candidates.length > 1 && complexSignals;
+  const parallelSuggested = !nativeAudioProbe && candidates.length > 1 && complexSignals;
   const compareSuggested = parallelSuggested;
 
   return {
@@ -84,6 +98,15 @@ export function planRoute(
     selected: candidates[0],
     parallelSuggested,
     compareSuggested,
+    ...(hasMultimodalInput(prompt) ? {
+      inputGuidance: [
+        ...MULTIMODAL_INPUT_GUIDANCE,
+        "Keyword routing does not verify native media access. Inspect the chosen harness inputGuidance and select a harness/model explicitly for the initial probe.",
+        ...runnable.flatMap((harness) => (harness.inputGuidance ?? [])
+          .filter((note) => !MULTIMODAL_INPUT_GUIDANCE.includes(note))
+          .map((note) => `${harness.id}: ${note}`)),
+      ],
+    } : {}),
   };
 }