@cr1ms0n/pi-subagent 0.8.9 → 0.9.0

package/src/extension.ts

@@ -1,6 +1,5 @@
 import { Buffer } from "node:buffer";
 import * as fs from "node:fs/promises";
-import { constants as fsConstants } from "node:fs";
 import * as path from "node:path";
 import type { ExtensionAPI, ExtensionContext, Theme, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, type Component, type TUI } from "@earendil-works/pi-tui";
@@ -24,7 +23,7 @@ import { abortAsPromise } from "./maintenance.js";
 import { sweepSessionsLifecycle } from "./distill.js";
 import { runTasks } from "./orchestrator.js";
 import { OutputManager } from "./output.js";
-import { CONTEXT_MANAGEMENT_TOOLS, parseDepth, parseSpawnPolicy, SPAWNS_ENV_VAR, validateSubagentRequest, type ResolvedTask } from "./policy.js";
+import { parseDepth, parseSpawnPolicy, SPAWNS_ENV_VAR, validateSubagentRequest, type PreparedTask, type ParentContext, type PreparationOptions, type ResolvedTask } from "./policy.js";
 import type { ChildRunner } from "./runner.js";
 import { ProcessLockManager } from "./process-lock.js";
 import { SessionScopedRunRegistry, snapshotFromLiveRun } from "./registry.js";
@@ -40,13 +39,18 @@ import { BTW_ENTRY_TYPE, btwLabel, type BtwEntry } from "./btw.js";
 import { Semaphore } from "./semaphore.js";
 import type { RunSnapshot, TaskResult, TaskSpec, UsageStats } from "./types.js";
 import { emptyUsage } from "./types.js";
-import { addUsage, buildUsageLedger, formatLedger, hasBilledUsage, toPiUsage, type UsageLedger } from "./usage.js";
+import { addUsage, buildUsageLedger, formatLedger, hasBilledUsage, routingUsage, toPiUsage, type UsageLedger } from "./usage.js";
 import { resolveBackendSessionFilePath, resolveSessionFilePath } from "./transcript.js";
 import { CompletionBatcher, COMPLETION_MESSAGE_TYPE, type CompletionDetails, type CompletionDetailsRun, type CompletionDetailsTask } from "./notifications.js";
 import { describeCatalog, discoverAgents, type AgentDefinition } from "./agents.js";
 import { createSubagentsOverlay, FooterStatusModel, type SubagentAdapter } from "./ui.js";
 import { WorktreeManager } from "./worktree.js";
-import { formatModelPolicyPrompt, readModelPolicyFile, resolveModelRoute, validateModelRequest, type ModelPolicySnapshot } from "./model-policy.js";
+import { eligibleModelCandidates, formatJevRoutingPrompt, toToolCandidates } from "./routing-policy.js";
+import { JevRouter } from "./jev-router.js";
+import { routePreparedTasks, type RoutingCatalog } from "./dispatch-routing.js";
+import { runLocalPreflights } from "./dispatch-preflight.js";
+import type { RoutingReceipt } from "./routing-types.js";
+import { buildRoutingEvent, foldRoutingReceipts, MAX_ROUTING_DELIVERY_IDS, ROUTING_ENTRY_TYPE, type PersistedRoutingEvent } from "./persistence.js";
 
 interface SessionRuntime {
   key: string;
@@ -76,6 +80,11 @@ interface SessionRuntime {
   ledgerDirty: boolean;
   closed: boolean;
   depth: number;
+  routingGeneration: number;
+  routingPaused: boolean;
+  pendingRoutes: Map<AbortController, Promise<void>>;
+  pendingRoutingEvents: Map<string, PersistedRoutingEvent>;
+  reconcileRouting?: () => void;
 }
 
 function sessionKey(ctx: ExtensionContext): string {
@@ -92,6 +101,7 @@ function activeEntries(runtime: SessionRuntime): readonly unknown[] {
  * on every footer refresh or live-text tick.
  */
 function ledger(runtime: SessionRuntime): UsageLedger {
+  runtime.reconcileRouting?.();
   if (!runtime.ledgerDirty && runtime.ledgerValue) return runtime.ledgerValue;
   const entries = activeEntries(runtime);
   runtime.ledgerValue = buildUsageLedger(
@@ -101,6 +111,7 @@ function ledger(runtime: SessionRuntime): UsageLedger {
       ...runtime.registry.getSnapshots(runtime.key),
     ],
     runtime.pendingRootMessages,
+    [...runtime.pendingRoutingEvents.values()],
   );
   runtime.ledgerDirty = false;
   return runtime.ledgerValue;
@@ -293,6 +304,7 @@ function compactDetails(
   const perResultText = Math.max(256, Math.floor(maxDetailsTextBytes / Math.max(1, results.length) / 2));
   return {
     mode,
+    routingCurrency: results.some((result) => result.routing) ? "unreported" : undefined,
     state: run?.state,
     startedAt: run?.startedAt,
     endedAt: run?.endedAt,
@@ -306,6 +318,7 @@ function compactDetails(
       errorMessage: result.errorMessage?.slice(0, 1_000),
       usage: result.usage ?? emptyUsage(),
       model: result.model,
+      routing: result.routing,
       thinking: result.thinking,
       profile: result.profile,
       canWrite: result.canWrite,
@@ -380,8 +393,9 @@ function deliveredResult<TDetails>(
   text: string,
   details: TDetails,
   results: ReadonlyArray<{ usage: UsageStats }>,
+  selectorUsage: UsageStats = emptyUsage(),
 ): { content: Array<{ type: "text"; text: string }>; details: TDetails; usage?: Usage } {
-  const total = addUsage(...results.map((result) => result.usage));
+  const total = addUsage(selectorUsage, ...results.map((result) => result.usage));
   return {
     content: [{ type: "text", text }],
     details,
@@ -405,33 +419,15 @@ function resumableSessionLines(
 
 async function runPlanPreflights(
   runtime: SessionRuntime,
-  tasks: ResolvedTask[],
+  tasks: PreparedTask[],
   parentCwd: string,
+  scope: { controller: AbortController; assertOwner(): void },
 ): Promise<void> {
-  for (let index = 0; index < tasks.length; index++) {
-    const task = tasks[index]!;
-    const taskCwd = task.cwd ?? parentCwd;
-    if (task.isolation === "worktree") {
-      if (!(await runtime.worktrees.isGitRepo(taskCwd))) {
-        fail(`Task ${index + 1}: ${taskCwd} is not a git repository`);
-      }
-    }
-    if (task.contextFork) {
-      const sessionFile = task.parentSessionFile;
-      if (!sessionFile) fail(`Task ${index + 1}: context:'fork' requires a persisted parent session file`);
-      await fs.access(sessionFile).catch(() => {
-        fail(`context:'fork' failed: parent session file ${sessionFile} is not readable.`);
-      });
-    }
-    if (task.output) {
-      const parentDir = path.dirname(task.output);
-      const stat = await fs.stat(parentDir).catch(() => undefined);
-      if (!stat?.isDirectory()) fail(`Task ${index + 1}: output parent directory does not exist: ${parentDir}`);
-      await fs.access(parentDir, fsConstants.W_OK).catch(() => {
-        fail(`Task ${index + 1}: output parent directory is not writable: ${parentDir}`);
-      });
-    }
-  }
+  await runLocalPreflights(tasks, parentCwd, {
+    signal: scope.controller.signal, assertOwner: scope.assertOwner,
+    checkResumeAvailability: (items) => runtime.registry.checkResumeAvailability(items, runtime.key),
+    isGitRepo: (cwd, signal) => runtime.worktrees.isGitRepo(cwd, signal),
+  });
 }
 
 function formatPlanEntry(task: ResolvedTask, index: number) {
@@ -447,6 +443,7 @@ function formatPlanEntry(task: ResolvedTask, index: number) {
     profile: task.profile,
     access: task.canWrite ? "RW" : "RO" as const,
     tools: task.effectiveTools,
+    routing: task.routing,
     budgets: {
       timeoutMs: task.timeoutMs,
       maxTurns: task.maxTurns,
@@ -459,7 +456,7 @@ function formatPlanEntry(task: ResolvedTask, index: number) {
 }
 
 function formatPlanText(mode: "single" | "parallel", plan: ReturnType<typeof formatPlanEntry>[]): string {
-  const header = `Plan (dry-run, nothing spawned) — ${mode}, ${plan.length} task${plan.length === 1 ? "" : "s"}:`;
+  const header = `Plan (Jev selection billed; no child spawned) — ${mode}, ${plan.length} task${plan.length === 1 ? "" : "s"}:`;
   const body = plan.map((entry) => {
     const budgets = [
       `timeout_ms=${entry.budgets.timeoutMs}`,
@@ -497,14 +494,15 @@ function guidelines(catalog?: Map<string, AgentDefinition>): string[] {
     : [];
   return [
     ...agentLines,
-    "**model is REQUIRED on every spawn call (task/tasks).** Pass the exact model mapped by the current model policy; agent-file/taskDefaults/parent-session model fields never apply. Omit model only for management actions.",
+    "Omit model and fallback_models on all new work. Jev selects the execution model from the user-maintained dedicated candidate list and selects individual locally permitted tools. Explicit legacy model/fallback fields are rejected.",
+    "action:plan calls Jev and may incur selector fees, but starts no child. Later dispatch selects again. Jev failure stops new dispatch; existing-run management requires no routing config or key.",
     "Delegate independent, read-heavy exploration or clean-context review; keep tightly coupled work in the parent.",
     "Prefer agent:'<name>' when a named agent matches the task — its persona prompt is usually better than an improvised one. Compose fields manually only when no agent fits.",
     "Give every task a short description label (3-5 words) so runs are scannable in UIs and result indexes.",
-    "Profiles: explore/review are strictly read-only (safe for fanout); general inherits the parent's active tools and may write. Single tasks default to general, parallel tasks to explore.",
+    "Profiles: explore/review are strictly read-only (safe for fanout); general offers the full available locally permitted catalog to Jev and may write. Explicit tools are a ceiling; agent tool defaults do not narrow candidates. Single tasks default to general, parallel tasks to explore.",
     "Parallel writers need isolation:'worktree' (each gets an isolated checkout; changed work lands on a branch). After a worktree run finishes, use action:'diff' to inspect, then 'apply' to bring changes into the main checkout or 'discard' to drop them.",
-    "Set budgets: at max_turns/max_cost the child is steered to wrap up and given grace turns for a final answer (grace_turns tunes this); results end as 'partial' with wrappedUp:true when the child concluded. timeout_ms includes queue time; timeout results report the phase.",
-    "Transient failures (provider errors, stalls, queue timeouts) retry automatically; pass fallback_models:['…'] to escalate models across attempts. Task-quality failures never retry.",
+    "Set budgets: at max_turns/max_cost the child is steered to wrap up and given grace turns for a final answer (grace_turns tunes this); results end as 'partial' with wrappedUp:true when the child concluded. timeout_ms includes Jev selection, setup, queue and retries; max_cost excludes unreported TypeSafe currency; timeout results report the phase.",
+    "Transient child failures may retry on the already selected model/tools within the original deadline; no selector retries or fallback models. Task-quality failures never retry.",
     "context:'fork' starts a single child from a branched copy of this conversation — use it when the task depends on discussion context instead of re-explaining. Single-task only.",
     "Use async:true only when you have independent work meanwhile; then use action:'wait' with the run id (interruptible, does not cancel). action:'steer' injects mid-run guidance into a running child instead of cancel + retry.",
     "For parallel research, add synthesis:'<instruction>' to have one read-only child fold all outputs into a single brief, delivered first.",
@@ -523,8 +521,8 @@ async function runSynthesis(
   runtime: SessionRuntime,
   instruction: string,
   results: TaskResult[],
-  options: { runId: string; modelPolicy: ModelPolicySnapshot; signal: AbortSignal },
-): Promise<TaskResult | undefined> {
+  options: { runId: string; signal: AbortSignal; select(): Promise<ResolvedTask>; assertOwner(): void },
+): Promise<{ result?: TaskResult; diagnostic?: string }> {
   const sections = results.map((result, index) => {
     // Typed handoff: validated structured results feed the synthesis child
     // clean JSON instead of prose tails.
@@ -553,49 +551,35 @@ async function runSynthesis(
     ...sections,
   ].filter(Boolean).join("\n\n");
   try {
-    const { runSubagent } = await import("./runner.js");
-    const route = resolveModelRoute(options.modelPolicy);
-    // runSubagent is a trusted low-level SDK primitive. Re-validate the
-    // internally constructed request here so synthesis remains inside the
-    // Extension's modelPolicy boundary rather than becoming a bypass path.
-    const approved = validateModelRequest(options.modelPolicy, {
-      model: route.model,
-      fallbackModels: [...route.fallbackModels],
-      fallbackModelsProvided: true,
+    const selected = await options.select();
+    options.assertOwner();
+    const run = await runTasks([{ ...selected, task, label: "synthesis" }], {
+      semaphore: runtime.semaphore,
+      getPiCommand: runtime.getPiCommand,
+      sessionDir: runtime.config.sessionDir,
+      killGraceMs: runtime.config.killGraceMs,
+      locks: runtime.locks,
+      runId: `${options.runId}:synthesis`,
+      parentSessionKey: runtime.key,
+      signal: options.signal,
+      graceTurns: runtime.config.graceTurns,
+      maxRetries: runtime.config.maxRetries,
+      stallAfterMs: runtime.config.stallAfterMs,
+      stallKillAfterMs: runtime.config.stallKillAfterMs,
     });
-    if (approved.error || !approved.route) throw new Error(approved.error ?? "synthesis model policy validation failed");
-    const synth = await runSubagent(
-      {
-        task,
-        label: "synthesis",
-        profile: "review",
-        canWrite: false,
-        tools: ["read", ...CONTEXT_MANAGEMENT_TOOLS],
-        model: approved.route.model,
-        fallbackModels: [...approved.route.fallbackModels],
-        thinking: approved.route.thinking ?? "low",
-        timeoutMs: Math.min(runtime.config.defaultTimeoutMs, 5 * 60_000),
-        maxTurns: 8,
-      },
-      {
-        semaphore: runtime.semaphore,
-        getPiCommand: runtime.getPiCommand,
-        sessionDir: runtime.config.sessionDir,
-        killGraceMs: runtime.config.killGraceMs,
-        locks: runtime.locks,
-        runId: `${options.runId}:synthesis`,
-        parentSessionKey: runtime.key,
-        signal: options.signal,
-      },
-    );
-    if (synth.state !== "completed" && synth.state !== "partial") return undefined;
+    const synth = run.results[0]!;
+    // Even a failed paid synthesis is returned so its reported usage is never lost.
     synth.label = "synthesis";
-    return synth;
-  } catch {
-    return undefined;
+    return { result: synth };
+  } catch (error) {
+    return { diagnostic: `Optional synthesis blocked: ${oneLine(error instanceof Error ? error.message : "routing or startup failed", 800)}` };
   }
 }
 
+function synthesisDiagnostic(summary?: string): string | undefined {
+  return summary?.startsWith("Optional synthesis blocked:") ? summary.split("\n", 1)[0] : undefined;
+}
+
 /** Compact completion payload for notification messages (LLM + renderer facing). */
 function buildCompletionDetails(runtime: SessionRuntime, runIds: string[]): CompletionDetails {
   const runs: CompletionDetailsRun[] = [];
@@ -712,9 +696,148 @@ export default function registerSubagent(pi: ExtensionAPI): void {
   // for further nesting. Accidental-recursion guard only; not a security boundary.
   if (parseSpawnPolicy(process.env[SPAWNS_ENV_VAR]).kind === "disabled") return;
 
+  function ownsRouting(runtime: SessionRuntime, generation: number): boolean {
+    return current === runtime && !runtime.closed && runtime.routingGeneration === generation
+      && sessionKey(runtime.ctx) === runtime.key;
+  }
+
+  const MAX_PENDING_ROUTING_RECEIPTS = 1024;
+
+  function reconcileRouting(runtime: SessionRuntime): void {
+    const visible = foldRoutingReceipts(activeEntries(runtime), [], runtime.key);
+    for (const [id, pending] of runtime.pendingRoutingEvents) {
+      const entry = visible.get(id);
+      if (entry && entry.timestamp >= pending.timestamp
+        && (pending.runId === undefined || entry.runId === pending.runId)
+        && (!pending.delivered || entry.delivered)
+        && JSON.stringify(entry.receipt) === JSON.stringify(pending.receipt)) {
+        runtime.pendingRoutingEvents.delete(id);
+      }
+    }
+  }
+
+  async function flushRouting(runtime: SessionRuntime): Promise<boolean> {
+    const generation = runtime.routingGeneration;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      if (!ownsRouting(runtime, generation)) return runtime.pendingRoutingEvents.size === 0;
+      reconcileRouting(runtime);
+      if (!runtime.pendingRoutingEvents.size) return true;
+      for (const event of runtime.pendingRoutingEvents.values()) {
+        try { pi.appendEntry(ROUTING_ENTRY_TYPE, event); }
+        catch { /* A bounded persistence retry, never a repeated selector request. */ }
+      }
+      reconcileRouting(runtime);
+      if (!runtime.pendingRoutingEvents.size) return true;
+      await new Promise<void>((resolve) => { const timer = setTimeout(resolve, 20); timer.unref?.(); });
+    }
+    return false;
+  }
+
+  async function requireRoutingPersistence(runtime: SessionRuntime): Promise<void> {
+    if (!(await flushRouting(runtime))) fail("Routing receipts could not be durably confirmed on the current branch. No new child was started. Restore session persistence and retry; selector usage may already have been incurred.");
+  }
+
+  function recordRouting(runtime: SessionRuntime, generation: number, receipt: RoutingReceipt, runId?: string, delivered?: boolean): void {
+    if (!ownsRouting(runtime, generation)) fail("Routing owner changed; stale receipts cannot be appended into another session.");
+    const event = buildRoutingEvent(runtime.key, receipt, runId, delivered);
+    runtime.pendingRoutingEvents.set(receipt.requestId, event);
+    runtime.ledgerDirty = true;
+    try { pi.appendEntry(ROUTING_ENTRY_TYPE, event); }
+    catch { /* Keep the staged receipt; the bounded flush owns persistence retries. */ }
+    reconcileRouting(runtime);
+  }
+
+  async function claimRoutingUsage(runtime: SessionRuntime, options: { ids?: ReadonlySet<string>; runId?: string }): Promise<UsageStats> {
+    const generation = runtime.routingGeneration;
+    await requireRoutingPersistence(runtime);
+    if (!ownsRouting(runtime, generation)) fail("Routing delivery belongs to a previous session/branch.");
+    const folded = foldRoutingReceipts(activeEntries(runtime), [...runtime.pendingRoutingEvents.values()], runtime.key);
+    const selected = [...folded.values()].filter((entry) => !entry.delivered
+      && (!options.ids || options.ids.has(entry.requestId)) && (!options.runId || entry.runId === options.runId));
+    if (!options.runId && selected.length > MAX_ROUTING_DELIVERY_IDS) fail(`Native routing delivery exceeds ${MAX_ROUTING_DELIVERY_IDS} selector receipts. Split this plan/background request into smaller invocations; selector usage is retained in the ledger.`);
+    if (!options.runId && selected.length) {
+      // Plan and async-start have no run-delivery transaction. Commit the entire
+      // native attachment as one event, so a throwing append cannot consume a prefix.
+      const event = { schemaVersion: 1, kind: "native-delivery", sessionKey: runtime.key,
+        timestamp: Date.now(), requestIds: selected.map((entry) => entry.requestId) };
+      let persisted = false;
+      for (let attempt = 0; attempt < 3; attempt++) {
+        if (!ownsRouting(runtime, generation)) fail("Routing delivery belongs to a previous session/branch.");
+        try { pi.appendEntry(ROUTING_ENTRY_TYPE, event); persisted = true; break; }
+        catch { if (attempt < 2) await new Promise<void>((resolve) => { const timer = setTimeout(resolve, 20); timer.unref?.(); }); }
+      }
+      if (!persisted) fail("Routing usage delivery could not be persisted; run results remain collectable and selector requests were not retried.");
+      // Cover delayed getBranch visibility after a successful append. Reconciliation
+      // removes these overlays once the single batch delivery event is exposed.
+      for (const entry of selected) runtime.pendingRoutingEvents.set(entry.requestId,
+        { ...buildRoutingEvent(runtime.key, entry.receipt, entry.runId, true), timestamp: entry.timestamp });
+      runtime.ledgerDirty = true;
+      reconcileRouting(runtime);
+    }
+    // Linked run receipts are consumed by registry.markDelivered's single event.
+    // The caller performs that synchronous commit only after this await succeeds.
+    return routingUsage(selected.map((entry) => entry.receipt));
+  }
+
+  function beginRouting(runtime: SessionRuntime, signal?: AbortSignal, runId?: string) {
+    const generation = runtime.routingGeneration;
+    const controller = new AbortController();
+    const receipts = new Map<string, RoutingReceipt>();
+    const onAbort = () => controller.abort();
+    if (signal?.aborted) controller.abort();
+    else signal?.addEventListener("abort", onAbort, { once: true });
+    let done!: () => void;
+    const settled = new Promise<void>((resolve) => { done = resolve; });
+    runtime.pendingRoutes.set(controller, settled);
+    let finished = false;
+    return {
+      controller, generation, receipts,
+      assertOwner() {
+        if (!ownsRouting(runtime, generation) || runtime.routingPaused || controller.signal.aborted) {
+          fail("Subagent routing cancelled or its session/branch changed; no child was started.");
+        }
+      },
+      record(receipt: RoutingReceipt) {
+        receipts.set(receipt.requestId, receipt);
+        try { recordRouting(runtime, generation, receipt, runId); }
+        finally {
+          if (runtime.pendingRoutingEvents.size > MAX_PENDING_ROUTING_RECEIPTS) {
+            controller.abort();
+            fail("Routing receipt persistence backlog reached its local bound; further selector requests were cancelled.");
+          }
+        }
+      },
+      finish() {
+        if (finished) return;
+        finished = true;
+        signal?.removeEventListener("abort", onAbort);
+        runtime.pendingRoutes.delete(controller);
+        done();
+      },
+    };
+  }
+
+  async function stopPendingRouting(runtime: SessionRuntime): Promise<void> {
+    runtime.routingPaused = true;
+    const pending = [...runtime.pendingRoutes];
+    for (const [controller] of pending) controller.abort();
+    let timer: NodeJS.Timeout | undefined;
+    try {
+      await Promise.race([
+        Promise.allSettled(pending.map(([, done]) => done)),
+        new Promise<void>((resolve) => { timer = setTimeout(resolve, 8_000); timer.unref?.(); }),
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
   async function teardown(runtime: SessionRuntime): Promise<void> {
     if (runtime.closed) return;
+    await stopPendingRouting(runtime);
     await runtime.registry.shutdown(runtime.key, 8_000);
+    if (!(await flushRouting(runtime))) runtime.ctx.ui.notify("Subagent routing receipts could not be persisted before shutdown; selector usage may be missing from durable history.", "error");
+    runtime.routingGeneration++;
     runtime.closed = true;
     runtime.unsubscribe?.();
     runtime.unsubscribeLedger?.();
@@ -727,14 +850,8 @@ export default function registerSubagent(pi: ExtensionAPI): void {
   }
 
   pi.on("before_agent_start", async (event) => {
-    let policy: ModelPolicySnapshot | undefined;
-    let error: string | undefined;
-    try {
-      policy = await readModelPolicyFile();
-    } catch (caught) {
-      error = caught instanceof Error ? caught.message : String(caught);
-    }
-    return { systemPrompt: `${event.systemPrompt}\n\n${formatModelPolicyPrompt(policy, error)}` };
+    const config = loadConfig(await readConfigFile());
+    return { systemPrompt: `${event.systemPrompt}\n\n${formatJevRoutingPrompt(config.jevRouting, config.jevRoutingError)}` };
   });
 
   pi.on("session_start", async (_event, ctx) => {
@@ -757,6 +874,11 @@ export default function registerSubagent(pi: ExtensionAPI): void {
     runtime.agents = discoverAgents(ctx.cwd);
     runtime.agentsLoadedAt = Date.now();
     runtime.pendingRootMessages = [];
+    runtime.routingGeneration = 0;
+    runtime.routingPaused = false;
+    runtime.pendingRoutes = new Map();
+    runtime.pendingRoutingEvents = new Map();
+    runtime.reconcileRouting = () => reconcileRouting(runtime);
     runtime.ledgerDirty = true;
     runtime.closed = false;
     runtime.registry = new SessionScopedRunRegistry(runtime.config, {
@@ -857,12 +979,22 @@ export default function registerSubagent(pi: ExtensionAPI): void {
     const runtime = current;
     if (!runtime || runtime.closed) return;
     // Finish persistence on the originating leaf before Pi moves the branch pointer.
+    await stopPendingRouting(runtime);
     await runtime.registry.shutdown(runtime.key, 8_000);
+    if (!(await flushRouting(runtime))) {
+      runtime.routingPaused = false;
+      runtime.ctx.ui.notify("Branch change cancelled: routing receipts are not durably confirmed. Restore session persistence before changing branches.", "error");
+      return { cancel: true };
+    }
+    runtime.routingGeneration++;
   });
 
   pi.on("session_tree", async () => {
     const runtime = current;
     if (!runtime || runtime.closed) return;
+    runtime.routingPaused = false;
+    if (runtime.pendingRoutingEvents.size) runtime.ctx.ui.notify("Unconfirmed routing receipts remained during an unexpected branch move; they cannot be appended to the new branch. Durable selector usage may be incomplete.", "error");
+    runtime.pendingRoutingEvents.clear();
     runtime.pendingRootMessages = [];
     runtime.ledgerDirty = true;
     runtime.registry.refreshSnapshots(runtime.key);
@@ -972,28 +1104,35 @@ export default function registerSubagent(pi: ExtensionAPI): void {
         fail(`Invalid parameters: ${errors}`);
       }
 
-      // Re-read the policy on every dispatch so changes take effect without
-      // restarting the parent session; no provider catalog or credentials are
-      // loaded by this path.
-      const dispatchConfig = loadConfig(await readConfigFile());
-      const model = ctx.model;
-      const validated = validateSubagentRequest(params, {
+      const requestGeneration = runtime.routingGeneration;
+      const invocationStartedAt = Date.now();
+      const management = params.action !== undefined && params.action !== "plan";
+      const routingScope = management ? undefined : beginRouting(runtime, signal);
+      try {
+      routingScope?.assertOwner();
+      if (routingScope) { await requireRoutingPersistence(runtime); routingScope.assertOwner(); }
+      // Management does not read a config file, credential or model/tool catalog.
+      const dispatchConfig = management ? runtime.config : loadConfig(await readConfigFile());
+      routingScope?.assertOwner();
+      const parentTools = management ? [] : pi.getAllTools()
+        .filter((tool) => tool.sourceInfo?.source !== "sdk" && !tool.sourceInfo?.path?.startsWith("<sdk:"));
+      const parent: ParentContext = {
         cwd: ctx.cwd,
-        model: model ? `${model.provider}/${model.id}` : undefined,
-        thinking: pi.getThinkingLevel() as TaskSpec["thinking"],
-        availableTools: pi.getAllTools().map((tool) => tool.name),
-        activeTools: pi.getActiveTools(),
-        depth: parseDepth(),
+        thinking: management ? undefined : pi.getThinkingLevel() as TaskSpec["thinking"],
+        availableTools: parentTools.map((tool) => tool.name),
+        depth: runtime.depth,
         sessionFile: ctx.sessionManager.getSessionFile() ?? undefined,
-      }, {
+      };
+      const preparation: PreparationOptions = {
         maxDepth: runtime.config.maxDepth,
         maxTasks: runtime.config.maxTasksPerRun,
         defaultTimeoutMs: runtime.config.defaultTimeoutMs,
         taskDefaults: dispatchConfig.taskDefaults,
-        agents: agentCatalog(runtime),
-        modelPolicy: dispatchConfig.modelPolicy,
-        modelPolicyError: dispatchConfig.modelPolicyError,
-      });
+        agents: management ? undefined : agentCatalog(runtime),
+        jevRouting: dispatchConfig.jevRouting,
+        jevRoutingError: dispatchConfig.jevRoutingError,
+      };
+      const validated = validateSubagentRequest(params, parent, preparation);
       if (!validated.ok) fail(validated.error);
 
       const details = (mode: "single" | "parallel", results: Array<TaskResult | RunSnapshot["results"][number]>, run?: RunMeta) =>
@@ -1146,63 +1285,90 @@ export default function registerSubagent(pi: ExtensionAPI): void {
             };
           }
         }
+        if (!ownsRouting(runtime, requestGeneration)) fail("Wait belonged to a previous session/branch; collect the run from its originating branch.");
         const refreshed = runtime.registry.lookup(snapshot.id, runtime.key);
         const terminal = refreshed.status === "found" && refreshed.run
           ? "controller" in refreshed.run ? snapshotFromLiveRun(refreshed.run) : refreshed.run
           : snapshot;
+        const selectorUsage = await claimRoutingUsage(runtime, { runId: terminal.id });
+        if (!ownsRouting(runtime, requestGeneration)) fail("Wait belonged to a previous session/branch.");
         if (!runtime.registry.markDelivered(terminal.id, runtime.key)) {
           return { content: [{ type: "text", text: `Run ${terminal.id} was already delivered. Artifacts and sessions remain available in /subagents.` }], details: details(terminal.mode, terminal.results, terminal) };
         }
         const delivered = runtime.output.capOutputForDelivery(terminal.results);
-        const text = delivered.text || terminal.summary || "(no output)";
+        const text = [synthesisDiagnostic(terminal.summary), delivered.text || terminal.summary || "(no output)"].filter(Boolean).join("\n\n");
         // Locate runs and partial/timeout deliveries still return content; hard
         // failures and “lost with resume blocked” raise so the agent notices.
         // (Thrown deliveries cannot carry native usage; the extension ledger
         // still counts them from persisted entries.)
         if (terminal.state === "failed" || terminal.state === "lost") fail(text);
-        return deliveredResult(text, details(terminal.mode, delivered.cappedResults as any, terminal), terminal.results);
+        return deliveredResult(text, details(terminal.mode, delivered.cappedResults as any, terminal), terminal.results, selectorUsage);
       }
 
+      if (!routingScope) fail("Internal routing scope is missing.");
+      routingScope.assertOwner();
+      const catalog: RoutingCatalog = {
+        models: eligibleModelCandidates(dispatchConfig.jevRouting!, ctx.modelRegistry.getAvailable().map((model) => `${model.provider}/${model.id}`)),
+        tools: toToolCandidates(parentTools),
+      };
+      if (!catalog.models.length) fail("No configured Jev candidate is locally available. Check exact model IDs and configured provider authentication.");
+      const router = new JevRouter({ config: dispatchConfig.jevRouting!, onReceipt: routingScope.record });
+      const prepared = validated.tasks.map((task) => ({ ...task, deadline: invocationStartedAt + task.timeoutMs }));
+      await runPlanPreflights(runtime, prepared, ctx.cwd, routingScope);
+      routingScope.assertOwner();
+      const resolved = await routePreparedTasks(prepared, catalog, router, {
+        purpose: validated.planOnly ? "plan" : "dispatch",
+        signal: routingScope.controller.signal, assertOwner: routingScope.assertOwner,
+      });
+      routingScope.assertOwner();
+      const prepareSynthesis = () => {
+        const normalized = validateSubagentRequest({
+          task: `Synthesize completed worker outputs into one read-only brief. Instruction: ${validated.synthesis}`,
+          description: "synthesis", profile: "review", max_turns: 8,
+          timeout_ms: Math.min(runtime.config.defaultTimeoutMs, 5 * 60_000),
+        }, parent, preparation);
+        if (!normalized.ok) fail(normalized.error);
+        return normalized.tasks.map((task) => ({ ...task, deadline: Date.now() + task.timeoutMs }));
+      };
       if (validated.planOnly) {
-        await runPlanPreflights(runtime, validated.tasks, ctx.cwd);
-        const plan = validated.tasks.map((task, index) => formatPlanEntry(task, index));
+        let synthesis: { state: "resolved"; plan: ReturnType<typeof formatPlanEntry> } | { state: "blocked"; error: string } | undefined;
+        if (validated.synthesis && prepared.length > 1) {
+          try {
+            const synthetic = prepareSynthesis();
+            await runPlanPreflights(runtime, synthetic, ctx.cwd, routingScope);
+            const planned = await routePreparedTasks(synthetic, catalog, router, {
+              purpose: "plan", signal: routingScope.controller.signal, assertOwner: routingScope.assertOwner,
+            });
+            synthesis = { state: "resolved", plan: formatPlanEntry(planned[0]!, 0) };
+          } catch (error) {
+            routingScope.assertOwner();
+            synthesis = { state: "blocked", error: error instanceof Error ? error.message : "Optional synthesis routing failed." };
+          }
+        }
+        routingScope.assertOwner();
+        await requireRoutingPersistence(runtime);
+        routingScope.assertOwner();
+        const plan = resolved.map((task, index) => formatPlanEntry(task, index));
         const mode = validated.mode as "single" | "parallel";
-        return {
-          content: [{ type: "text", text: formatPlanText(mode, plan) }],
-          details: { mode, plan },
-        };
+        const receipts = [...routingScope.receipts.values()];
+        const selectorUsage = await claimRoutingUsage(runtime, { ids: new Set(receipts.map((receipt) => receipt.requestId)) });
+        const text = [formatPlanText(mode, plan), synthesis ? `Optional synthesis: ${synthesis.state}${synthesis.state === "blocked" ? ` — ${synthesis.error}` : ` (${synthesis.plan.model})`}` : "", "Selector tokens are reported separately; TypeSafe currency is unreported. A later dispatch selects again."].filter(Boolean).join("\n");
+        return deliveredResult(text, { mode, plan, synthesis, routingReceipts: receipts, routingCurrency: "unreported" }, [], selectorUsage);
       }
 
-      const specs: TaskSpec[] = validated.tasks.map((task: ResolvedTask) => ({
-        task: task.task,
-        label: task.label,
-        systemPrompt: task.systemPrompt,
-        model: task.model,
-        thinking: task.thinking,
-        tools: task.effectiveTools,
-        profile: task.profile,
-        canWrite: task.canWrite,
-        cwd: task.cwd,
-        timeoutMs: task.timeoutMs,
-        maxTurns: task.maxTurns,
-        maxCost: task.maxCost,
-        output: task.output,
-        outputMode: task.outputMode,
-        outputSchema: task.outputSchema,
-        resume: task.resume,
-        forkResume: task.forkResume,
-        isolation: task.isolation,
-        allowSharedWrites: task.allowSharedWrites,
-        keepBackground: task.keepBackground,
-        graceTurns: task.graceTurns,
-        fallbackModels: task.fallbackModels,
-        maxRetries: task.maxRetries,
-        contextFork: task.contextFork,
-        parentSessionFile: task.parentSessionFile,
-        spawns: task.spawns,
+      const specs: TaskSpec[] = resolved.map(({ effectiveTools, resolutionNotes: _notes, ...task }) => ({
+        ...task, tools: effectiveTools, fallbackModels: [],
       }));
+      await requireRoutingPersistence(runtime);
+      routingScope.assertOwner();
+      if (validated.async && routingScope.receipts.size > MAX_ROUTING_DELIVERY_IDS) fail(`Background routing exceeds ${MAX_ROUTING_DELIVERY_IDS} selector receipts. No child was started; split this request into smaller invocations. Selector usage is retained in the ledger.`);
+      const executionGeneration = routingScope.generation;
       const runId = runtime.registry.allocateRunId();
-      const directResumes = validated.tasks.filter((task) => task.resume && !task.forkResume).map((task) => task.resume!);
+      const workerReceiptIds = new Set(routingScope.receipts.keys());
+      for (const receipt of routingScope.receipts.values()) recordRouting(runtime, executionGeneration, receipt, runId);
+      await requireRoutingPersistence(runtime);
+      routingScope.assertOwner();
+      const directResumes = resolved.filter((task) => task.resume && !task.forkResume).map((task) => task.resume!);
       const lock = runtime.registry.acquireResumeLocks(directResumes, runId, runtime.key);
       if (!lock.ok) fail(`Child session ${lock.conflict!.sessionId} is already active in run ${lock.conflict!.runId}. Use fork_resume:true for an independent continuation.`);
 
@@ -1213,12 +1379,15 @@ export default function registerSubagent(pi: ExtensionAPI): void {
       let resolveDone!: () => void;
       const done = new Promise<void>((resolve) => { resolveDone = resolve; });
       try {
-        runtime.registry.start(runtime.key, validated.mode as "single" | "parallel", specs, controller, done, validated.tasks.map((task) => task.label), runId);
+        runtime.registry.start(runtime.key, validated.mode as "single" | "parallel", specs, controller, done, resolved.map((task) => task.label), runId);
       } catch (error) {
+        signal?.removeEventListener("abort", parentAbort);
         for (const session of directResumes) runtime.registry.releaseResumeLock(session, runtime.key, runId);
         throw error;
       }
 
+      routingScope.finish(); // Ownership transfers to the registered run/controller.
+
       // Throttle streamed tool updates with a trailing-edge flush: structural
       // changes (state transition, new session id, billed turn) emit
       // immediately; live-text ticks coalesce into at most one deferred emit
@@ -1282,7 +1451,7 @@ export default function registerSubagent(pi: ExtensionAPI): void {
               runners.set(index, runner);
             },
             onTaskProgress: (index, partial) => {
-              if (runtime.closed || current !== runtime) return;
+              if (!ownsRouting(runtime, executionGeneration)) return;
               // Keep the durable run record's childSessionId in sync the first
               // time we learn it (also used by orphan reclaim).
               if (partial.sessionId && partial.process) {
@@ -1320,22 +1489,56 @@ export default function registerSubagent(pi: ExtensionAPI): void {
           // single brief, delivered first. Failures degrade to raw results.
           if (validated.synthesis && result.results.length > 1 && !controller.signal.aborted) {
             const synthesized = await runSynthesis(runtime, validated.synthesis, result.results, {
-              runId,
-              modelPolicy: dispatchConfig.modelPolicy!,
-              signal: controller.signal,
+              runId, signal: controller.signal,
+              assertOwner() {
+                if (!ownsRouting(runtime, executionGeneration) || runtime.routingPaused || controller.signal.aborted) fail("Synthesis cancelled or its session changed.");
+              },
+              async select() {
+                const scope = beginRouting(runtime, controller.signal, runId);
+                try {
+                  scope.assertOwner();
+                  const preparedSynthesis = prepareSynthesis();
+                  await runPlanPreflights(runtime, preparedSynthesis, ctx.cwd, scope);
+                  scope.assertOwner();
+                  const selected = await routePreparedTasks(preparedSynthesis, catalog,
+                    new JevRouter({ config: dispatchConfig.jevRouting!, onReceipt: scope.record }),
+                    { purpose: "synthesis", signal: scope.controller.signal, assertOwner: scope.assertOwner });
+                  await requireRoutingPersistence(runtime);
+                  scope.assertOwner();
+                  return selected[0]!;
+                } finally { scope.finish(); }
+              },
             });
-            if (synthesized) result.results = [synthesized, ...result.results];
+            if (synthesized.result) result.results = [synthesized.result, ...result.results];
+            if (synthesized.diagnostic) result.summary = `${synthesized.diagnostic}\n\n${result.summary}`;
           }
-          runtime.registry.complete(runId, runtime.key, result.state, result.summary, result.results);
+          if (ownsRouting(runtime, executionGeneration)) runtime.registry.complete(runId, runtime.key, result.state, result.summary, result.results);
           return result;
-        } catch (error: any) {
-          const failed: TaskResult = {
-            label: "task-1", task: specs[0]?.task ?? "", state: "failed", exitCode: 1,
-            messages: [], stderr: "", usage: emptyUsage(), stopReason: "error", errorMessage: error?.message ?? String(error),
-            protocol: { headerSeen: false, assistantEndSeen: false, agentEndSeen: false, agentSettledSeen: false, validEvents: 0, parseErrors: 0 },
-          };
-          runtime.registry.complete(runId, runtime.key, "failed", failed.errorMessage, [failed]);
-          return { mode: "single" as const, results: [failed], state: "failed" as const, summary: failed.errorMessage! };
+        } catch (error: unknown) {
+          controller.abort();
+          const message = error instanceof Error ? error.message : String(error);
+          const live = runtime.registry.getLiveRuns(runtime.key).find((run) => run.id === runId);
+          // Preserve every routed task and any usage already checkpointed. Never collapse
+          // a failed fanout to a synthetic, unbilled task-1 result.
+          const results = specs.map<TaskResult>((spec, index) => {
+            const previous = live?.results[index];
+            return {
+              ...previous,
+              index, label: spec.label || `task-${index + 1}`, task: spec.task,
+              model: previous?.model ?? spec.model, routing: spec.routing,
+              thinking: spec.thinking, profile: spec.profile, backend: spec.backend ?? "pi",
+              canWrite: spec.canWrite, outputFile: previous?.outputFile ?? spec.output, outputMode: spec.outputMode,
+              state: previous && !isActiveState(previous.state) ? previous.state : "failed",
+              exitCode: previous && !isActiveState(previous.state) ? previous.exitCode : 1,
+              messages: previous?.messages ?? [], stderr: previous?.stderr ?? "",
+              usage: previous?.usage ?? emptyUsage(), stopReason: previous?.stopReason ?? "error",
+              errorMessage: [previous?.errorMessage, message].filter(Boolean).join("; "),
+              protocol: previous?.protocol ?? { headerSeen: false, assistantEndSeen: false, agentEndSeen: false, agentSettledSeen: false, validEvents: 0, parseErrors: 0 },
+            };
+          });
+          const state = results.some((result) => result.state === "completed" || result.state === "partial") ? "partial" as const : "failed" as const;
+          if (ownsRouting(runtime, executionGeneration)) runtime.registry.complete(runId, runtime.key, state, message, results);
+          return { mode: validated.mode as "single" | "parallel", results, state, summary: message };
         } finally {
           if (pendingFlush) { clearTimeout(pendingFlush); pendingFlush = undefined; }
           runtime.liveRunners.delete(runId);
@@ -1347,14 +1550,19 @@ export default function registerSubagent(pi: ExtensionAPI): void {
 
       if (validated.async) {
         runtime.asyncRuns.add(runId);
-        return { content: [{ type: "text", text: `Started run ${runId}. You will be notified on completion; use status/wait/cancel with this full id, or open /subagents.` }], details: details(validated.mode as "single" | "parallel", []) };
+        const selectorUsage = await claimRoutingUsage(runtime, { ids: workerReceiptIds });
+        return deliveredResult(`Started run ${runId}. You will be notified on completion; use status/wait/cancel with this full id, or open /subagents. Selector currency is unreported.`,
+          { ...details(validated.mode as "single" | "parallel", []), routingReceipts: [...routingScope.receipts.values()], routingCurrency: "unreported" }, [], selectorUsage);
       }
       const result = await work;
+      if (!ownsRouting(runtime, executionGeneration)) fail("Subagent execution belonged to a previous session/branch; its final state remains on the originating branch.");
       // First delivery wins the native usage attachment: a rare concurrent
       // wait/dismiss that already consumed this run must not double-bill.
+      const selectorUsage = await claimRoutingUsage(runtime, { runId });
+      if (!ownsRouting(runtime, executionGeneration)) fail("Delivery belonged to a previous session/branch.");
       const firstDelivery = runtime.registry.markDelivered(runId, runtime.key);
       const delivered = runtime.output.capOutputForDelivery(result.results);
-      const text = delivered.text || result.summary;
+      const text = [synthesisDiagnostic(result.summary), delivered.text || result.summary].filter(Boolean).join("\n\n");
       const finished = runtime.registry.lookup(runId, runtime.key);
       const meta: RunMeta | undefined = finished.status === "found" && finished.run && !("controller" in finished.run)
         ? finished.run
@@ -1363,8 +1571,11 @@ export default function registerSubagent(pi: ExtensionAPI): void {
       if (result.state === "failed") fail(text);
       const resultDetails = details(result.mode, delivered.cappedResults as any, meta);
       return firstDelivery
-        ? deliveredResult(text, resultDetails, result.results)
+        ? deliveredResult(text, resultDetails, result.results, selectorUsage)
         : { content: [{ type: "text", text }], details: resultDetails };
+      } finally {
+        routingScope?.finish();
+      }
     },
     renderCall(args, theme, context) {
       // Stable component identity: reuse the previous block and swap content.
@@ -1375,7 +1586,7 @@ export default function registerSubagent(pi: ExtensionAPI): void {
     renderResult(result, options: ToolRenderResultOptions, theme, context) {
       const block = (context.lastComponent instanceof LineBlock ? context.lastComponent : new LineBlock()) as LineBlock;
       const detailsValue = result.details as ReturnType<typeof compactDetails> | undefined;
-      if (!detailsValue?.results.length) {
+      if (!detailsValue?.results?.length) {
         const text = result.content.find((item) => item.type === "text")?.text ?? "(no output)";
         block.set((width) => String(text).split("\n").map((line) => truncateToWidth(theme.fg("toolOutput", line), width)));
         return block;
@@ -1390,6 +1601,7 @@ export default function registerSubagent(pi: ExtensionAPI): void {
           state: task.state,
           usage: task.usage,
           model: task.model,
+          routing: task.routing,
           stopReason: task.stopReason,
           timeoutPhase: task.timeoutPhase,
           errorMessage: task.errorMessage,
@@ -1478,16 +1690,12 @@ export default function registerSubagent(pi: ExtensionAPI): void {
       try {
         // Reuse the tool's own execute so /btw inherits validation, profiles,
         // budgets, semaphore + process locks, and output capping unchanged.
-        const policy = await readModelPolicyFile().catch(() => undefined);
-        const route = policy ? resolveModelRoute(policy) : undefined;
         const result = await subagentTool.execute(
           `btw-${Date.now()}`,
           {
             task: question,
             profile: "explore",
             description: label,
-            model: route?.model,
-            fallback_models: route?.fallbackModels,
           } as SubagentParams,
           undefined,
           undefined,