omnirush 0.10.2 → 0.10.4

package/assets/extensions/omnirush/agents-lib.ts

@@ -35,6 +35,7 @@ import {
   ENV_FALLBACK_MODEL,
   FALLBACK_MARKER,
   fallbackNote,
+  sourceNote,
   piThinking,
   type SubagentFallback,
 } from "./subagents-lib";
@@ -198,11 +199,18 @@ export const ROLE_PRESETS: Record<AgentRole, RolePreset> = {
   },
 };
 
-/** Resolve the child entry: this running script + the current runtime. */
-export function childInvocation(args: string[]): {
+/**
+ * Resolve the child entry: the core's entry as the launcher started it
+ * (OMNIRUSH_CORE_ENTRY: through <package>/engine, so process listings name
+ * omnirush; the runtime reports the resolved path in argv[1]), else this
+ * running script, with the current runtime.
+ */
+export function childInvocation(args: string[], env: NodeJS.ProcessEnv = process.env): {
   command: string;
   args: string[];
 } {
+  const launched = (env.OMNIRUSH_CORE_ENTRY || "").trim();
+  if (launched && existsSync(launched)) return { command: process.execPath, args: [launched, ...args] };
   const currentScript = process.argv[1];
   const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
   if (currentScript && !isBunVirtualScript && existsSync(currentScript)) {
@@ -213,8 +221,8 @@ export function childInvocation(args: string[]): {
   if (!isGenericRuntime) {
     return { command: process.execPath, args };
   }
-  // Packaged bun builds: fall back to the pi on PATH.
-  return { command: "pi", args };
+  // Packaged bun builds: fall back to the omnirush on PATH (it forwards core flags).
+  return { command: "omnirush", args };
 }
 
 /** The folder, inside a session dir, that holds its sub-agents' sessions. */
@@ -305,8 +313,8 @@ export interface ChildTask {
   role: AgentRole;
   task: string;
   /** Cross-model children: gateway model id the child runs on
-   *  (e.g. "muse-spark-1.3" for cheap swarm workers under an astra
-   *  parent). Undefined = inherit the parent's model. */
+   *  (e.g. "muse-spark-1.1" workers under an astra parent). Undefined =
+   *  inherit the parent's model. */
   model?: string;
   /** The effort the child runs on (gateway spelling); undefined = pi's default. */
   effort?: string;
@@ -316,6 +324,21 @@ export interface ChildTask {
   gatewayFallback?: { model: string; effort: string | null };
   /** Extra environment for the child (the sub-agent setting and main model, for nested layers). */
   env?: Record<string, string>;
+  /** The model[:effort] the delegating agent asked for (the task's own `model`), when it named one. */
+  requestedModel?: string;
+  /** That model did not run: the user's /subagents choice won, or the gateway does not serve it. */
+  override?: ChildModelOverride;
+  /** Where `model` comes from ("subagents", "user_prompt", "task", "parent"). */
+  modelSource?: string;
+}
+
+/** A task model that did not run, and what ran instead (the result's model_override). */
+export interface ChildModelOverride {
+  requested: string;
+  used: string;
+  effort: string | null;
+  reason: string;
+  note: string;
 }
 
 /** A sub-agent that ran on the main model instead of the picked one. */
@@ -342,6 +365,12 @@ export interface ChildResult {
   effort?: string;
   /** It ran on the main model instead of the picked one (why, and since when). */
   model_fallback?: ChildModelFallback;
+  /** The task's own model did not run (the user's /subagents choice, or not served). */
+  model_override?: ChildModelOverride;
+  /** Where the model comes from: "subagents", "user_prompt", "task" or "parent". */
+  model_source?: string;
+  /** The model[:effort] the task asked for, when it named one. */
+  requested_model?: string;
   status: ChildStatus;
   /** Process exit code (null when killed by a signal or still unknown). */
   exitCode: number | null;
@@ -412,6 +441,9 @@ export function buildChildResult(
     ...(task.model ? { model: task.model } : {}),
     ...(task.effort ? { effort: task.effort } : {}),
     ...(modelFallback ? { model_fallback: modelFallback } : {}),
+    ...(task.override ? { model_override: { ...task.override } } : {}),
+    ...(task.modelSource ? { model_source: task.modelSource } : {}),
+    ...(task.requestedModel ? { requested_model: task.requestedModel } : {}),
     status: input.status ?? (input.exitCode === 0 ? "completed" : "failed"),
     exitCode: input.exitCode,
     output: capped,
@@ -921,16 +953,34 @@ export async function mapWithConcurrency<TIn, TOut>(
   return results;
 }
 
+/** The model and effort a child really ran on (after a gateway fallback), and why that one. */
+export function ranOn(result: Pick<ChildResult, "model" | "effort" | "model_fallback">): { model: string | null; effort: string | null } {
+  if (result.model_fallback?.kind === "gateway") return { model: result.model_fallback.used, effort: result.model_fallback.effort ?? null };
+  return { model: result.model ?? null, effort: result.effort ?? null };
+}
+
+function ranOnText(result: ChildResult): string {
+  const { model, effort } = ranOn(result);
+  if (!model) return "the parent's model (not an omnirush.ai model)";
+  const why = result.model_fallback?.kind === "gateway"
+    ? "the gateway refused the chosen model"
+    : result.model_fallback
+      ? "the main model"
+      : sourceNote(result.model_source);
+  return `${model}${effort ? ` · ${effort}` : ""}${why ? ` (${why})` : ""}`;
+}
+
 /** Structured result text for the parent model (one section per child). */
 export function renderChildResults(results: ChildResult[], ids?: readonly string[]): string {
   const succeeded = results.filter((result) => result.status === "completed").length;
   const sections = results.map((result, index) => {
     const minutes = Math.round((result.durationMs / 60_000) * 10) / 10;
-    const ranOn = result.model_fallback?.kind === "gateway" ? result.model_fallback.used : result.model;
-    const effort = result.model_fallback?.kind === "gateway" ? result.model_fallback.effort ?? undefined : result.effort;
-    const label = ranOn ? ` [${ranOn}${effort ? ` · ${effort}` : ""}]` : "";
+    const ran = ranOn(result);
+    const label = ran.model ? ` [${ran.model}${ran.effort ? ` · ${ran.effort}` : ""}]` : "";
     const header = `### ${ids?.[index] ? `${ids[index]} ` : ""}${result.role}${label} — ${result.status} (${minutes} min${result.outputTruncated ? ", output capped" : ""})`;
     const meta: string[] = [`task: ${result.task}`];
+    meta.push(`ran on: ${ranOnText(result)}`);
+    if (result.model_override) meta.push(`note: ${result.model_override.note}`);
     if (result.model_fallback) meta.push(`note: ${result.model_fallback.note}`);
     if (result.error) meta.push(`error: ${result.error}`);
     return `${header}\n${meta.join("\n")}\n\n${result.output || "(no output)"}`;

package/assets/extensions/omnirush/agents.ts

@@ -73,6 +73,7 @@ import {
 } from "./agents-lib";
 import { SWARM_GUIDELINE } from "./swarm-lib";
 import { omniDir } from "./auth";
+import { loadCatalog, type CatalogModel } from "./subagents-lib";
 import { MemoryAdmission, readMemorySettings } from "./memory-lib";
 
 /** Blocking spawn_agents: progress updates at most this often (ms). */
@@ -84,16 +85,32 @@ const MIN_TIMEOUT_MINUTES = 1;
 /** customType of the message that brings background results back. */
 export const DELIVERY_TYPE = "omnirush-agents-result";
 
-const SpawnAgentsParams = Type.Object({
+/** Served ids used as examples when the account's catalog is not cached (the live list at 0.10.3). */
+export const SERVED_MODEL_EXAMPLES = ["gpt-6-astra", "gpt-6-sol", "gpt-5.6-sol", "meta-muse-spark", "muse-spark-1.1"];
+
+/** Examples for the per-task model: the ids the account's live catalog lists (served models only). */
+export function modelExamples(catalog: readonly CatalogModel[] | null): string[] {
+  if (!catalog || catalog.length === 0) return SERVED_MODEL_EXAMPLES;
+  return catalog.map((model) => model.id);
+}
+
+export function modelParamDescription(examples: readonly string[]): string {
+  return [
+    "Optional model[:effort] for THIS task. Usually omit it: set it only when the user asked for a model for the sub-agents.",
+    `Served models: ${examples.map((id) => `"${id}"`).join(", ")}, optionally with an effort (e.g. "${examples[0] ?? "gpt-6-astra"}:high"); a model the account is not served is never used (the child runs on your model and effort).`,
+    "The user's /subagents choice always wins: while it is set, a model named here runs only if the user's own message names it.",
+    "Omitted, the child runs on the /subagents choice, else this session's current model and effort.",
+  ].join(" ");
+}
+
+const spawnAgentsParams = (examples: readonly string[]) => Type.Object({
   tasks: Type.Array(
     Type.Object({
       role: StringEnum(AGENT_ROLES, {
         description: "code-searcher: read-only codebase exploration; researcher-web: web research via web_search/web_fetch; general-worker: full-tool implementation work",
       }),
       task: Type.String({ description: "Self-contained task description for the child agent (it sees ONLY this, not your conversation)" }),
-      model: Type.Optional(Type.String({
-        description: 'Optional model[:effort] for THIS task (e.g. "muse-spark-1.3", "muse-spark-1.2-contributor" for cheap swarm workers, "meta-muse-spark", "muse-spark-1.1:low", "gpt-6-astra", "gpt-6-sol:high", "gpt-5.6-sol"). Omit (or leave empty) for the sub-agent model the user picked with /subagents, else the parent session\'s current model and effort',
-      })),
+      model: Type.Optional(Type.String({ description: modelParamDescription(examples) })),
     }),
     { description: "Tasks to delegate; they all run in parallel", minItems: 1 },
   ),
@@ -115,6 +132,26 @@ const IdsParam = Type.Optional(Type.Array(Type.String(), {
   description: 'Agent ids from spawn_agents (e.g. "a3"); omit (or "all") for every agent of this session',
 }));
 
+/** The text of the latest user message on the session's branch (null when there is none). */
+export function lastUserMessageText(ctx: any): string | null {
+  let entries: any[] = [];
+  try {
+    entries = ctx?.sessionManager?.getBranch?.() ?? ctx?.sessionManager?.getEntries?.() ?? [];
+  } catch {
+    return null;
+  }
+  for (let index = entries.length - 1; index >= 0; index--) {
+    const message = entries[index]?.type === "message" ? entries[index].message : null;
+    if (!message || message.role !== "user") continue;
+    if (typeof message.content === "string") return message.content;
+    if (Array.isArray(message.content)) {
+      return message.content.filter((part: any) => part?.type === "text" && typeof part.text === "string").map((part: any) => part.text).join("\n");
+    }
+    return null;
+  }
+  return null;
+}
+
 function resultOf(record: AgentRecord): ChildResult & { agent_id: string } {
   return { ...(record.result as ChildResult), agent_id: record.id };
 }
@@ -227,6 +264,30 @@ export default function (pi: ExtensionAPI, options: { run?: AgentRunner; admissi
   };
   (globalThis as any)[AGENTS_HOOK] = hook;
 
+  // The user's latest message (the text they typed, not an extension's):
+  // a task's own model runs over the /subagents choice only when it names
+  // that model. Sub-agents have no user: their task text never counts.
+  let lastUserInput: { session: string; text: string } | null = null;
+  const sessionIdOf = (ctx: any): string => {
+    try {
+      return String(ctx?.sessionManager?.getSessionId?.() ?? "");
+    } catch {
+      return "";
+    }
+  };
+  if (depth === 0) {
+    pi.on("input", (event: any, ctx: any) => {
+      if (event?.source === "extension" || typeof event?.text !== "string") return;
+      lastUserInput = { session: sessionIdOf(ctx), text: event.text };
+    });
+  }
+  const latestUserPrompt = (ctx: any): string | null => {
+    if (depth > 0) return null;
+    const session = sessionIdOf(ctx);
+    if (lastUserInput && lastUserInput.session === session) return lastUserInput.text;
+    return lastUserMessageText(ctx);
+  };
+
   const sessionOf = (ctx: any): string => {
     lastContext = ctx ?? lastContext;
     return hub.sessionOf(ctx);
@@ -244,7 +305,7 @@ export default function (pi: ExtensionAPI, options: { run?: AgentRunner; admissi
       "Default (wait true) blocks until all children finish and returns their results.",
       "wait:false dispatches them in the BACKGROUND: the call returns at once with agent ids, you keep working, and their results arrive automatically as a message in this conversation when they finish.",
       "Manage background agents with agents_status, agents_wait, agents_result and agents_cancel.",
-      'Each task can run on a DIFFERENT model via its "model" field — e.g. cheap muse workers for wide swarm sweeps under an astra parent.',
+      'Each task can run on a different model via its "model" field when the user asks for one; the user\'s /subagents choice wins over it, and a model the account is not served is not used. Every result says the model and effort the child ran on.',
       "Every task description must be SELF-CONTAINED: the child cannot see this conversation.",
       "Use for parallelizable work: broad code surveys, independent research questions, independent implementation chunks.",
       "Give each task only its own part of the work: never the user's whole message or instructions about sub-agents (the child would follow them and delegate again).",
@@ -257,7 +318,7 @@ export default function (pi: ExtensionAPI, options: { run?: AgentRunner; admissi
       "Do not use spawn_agents for a single quick action — doing it yourself is cheaper.",
       ...(depth > 0 ? [] : [SWARM_GUIDELINE]),
     ],
-    parameters: SpawnAgentsParams,
+    parameters: spawnAgentsParams(modelExamples(loadCatalog(omniDir()))),
 
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
       const parentSessionId = sessionOf(ctx);
@@ -266,9 +327,9 @@ export default function (pi: ExtensionAPI, options: { run?: AgentRunner; admissi
         if (!raw || typeof raw.task !== "string" || !raw.task.trim()) {
           throw new Error("invalid tasks: every entry needs a non-empty task string");
         }
-        // A task's own model[:effort] wins; an omitted (or empty) one takes
-        // the /subagents pick, else the parent session's current model and
-        // effort (resolved below by subagentTasks).
+        // A task's own model[:effort] (resolved below by subagentTasks):
+        // the user's /subagents choice wins over it unless the user's message
+        // names that model; unset, it runs only when the gateway serves it.
         const requestedModel = typeof raw.model === "string" ? raw.model.trim() : "";
         tasks.push({
           role: raw.role,
@@ -277,11 +338,11 @@ export default function (pi: ExtensionAPI, options: { run?: AgentRunner; admissi
         });
       }
       if (tasks.length === 0) throw new Error("no tasks given");
-      // The model and effort each child runs on (subagents.ts): the task's
-      // own model[:effort], else the /subagents pick, else the parent
+      // The model and effort each child runs on (subagents.ts): the
+      // /subagents choice, else a served task model, else the parent
       // session's current model and effort; the main model when a pick is
-      // unavailable.
-      const resolvedTasks = subagentTasks(pi, ctx, tasks);
+      // unavailable. Overrides are noted on the result and the trace.
+      const resolvedTasks = subagentTasks(pi, ctx, tasks, { userPrompt: latestUserPrompt(ctx) });
       if (!parentSessionId) throw new Error("no parent session id — subagents cannot be traced");
       const workdir = ctx?.cwd ? String(ctx.cwd) : process.cwd();
       // Only a deliberate limit counts: models fill optional numbers with
@@ -334,7 +395,7 @@ export default function (pi: ExtensionAPI, options: { run?: AgentRunner; admissi
 
       if (background) {
         const lines = dispatched.records.map((record, index) => {
-          const note = childModelFallback(resolvedTasks[index])?.note;
+          const note = [resolvedTasks[index].override?.note, childModelFallback(resolvedTasks[index])?.note].filter(Boolean).join("; ");
           return `- ${record.id}: ${record.role}${record.model ? ` [${record.model}${record.effort ? ` · ${record.effort}` : ""}]` : ""} — ${record.task.length > 100 ? `${record.task.slice(0, 99)}…` : record.task}${note ? ` (${note})` : ""}`;
         });
         return {
@@ -363,6 +424,9 @@ export default function (pi: ExtensionAPI, options: { run?: AgentRunner; admissi
                 ...(record.model ? { model: record.model } : {}),
                 ...(record.effort ? { effort: record.effort } : {}),
                 ...(modelFallback ? { model_fallback: modelFallback } : {}),
+                ...(resolvedTasks[index].override ? { model_override: { ...resolvedTasks[index].override } } : {}),
+                ...(resolvedTasks[index].modelSource ? { model_source: resolvedTasks[index].modelSource } : {}),
+                ...(resolvedTasks[index].requestedModel ? { requested_model: resolvedTasks[index].requestedModel } : {}),
                 parallel_limit: record.parallelLimit,
                 status: "running",
               };

package/assets/extensions/omnirush/secret-env.ts

@@ -5,11 +5,55 @@ const SECRET_ENV_NAMES = new Set([
   "OMNIRUSH_APPROVAL_TOKEN",
 ]);
 
-/** Keep provider credentials in the agent process, never in shell/MCP children. */
+/**
+ * The agent core's own PI_<NAME> variables (src/compat.js
+ * CORE_ONLY_ENV_NAMES; a test keeps the lists equal). Shell commands and
+ * MCP servers see their OMNIRUSH_<NAME> copies only; any other PI_*
+ * variable (a user's own) passes through.
+ */
+export const CORE_ONLY_ENV_NAMES = [
+  "CODING_AGENT",
+  "CODING_AGENT_DIR",
+  "CODING_AGENT_SESSION_DIR",
+  "SESSION_ID",
+  "SESSION_FILE",
+  "PROVIDER",
+  "MODEL",
+  "REASONING_LEVEL",
+  "OFFLINE",
+  "TELEMETRY",
+  "INSTALLER_API_BASE",
+  "MANAGED_INSTALL_ROOT",
+  "CACHE_RETENTION",
+  "CLEAR_ON_SHRINK",
+  "EXPERIMENTAL",
+  "HARDWARE_CURSOR",
+  "HYPERLINKS",
+  "IMAGE_PROTOCOL",
+  "OAUTH_CALLBACK_HOST",
+  "PACKAGE_DIR",
+  "RADIUS_GATEWAY",
+  "SHARE_VIEWER_URL",
+  "SKIP_VERSION_CHECK",
+  "STARTUP_BENCHMARK",
+  "TIMING",
+  "TRUE_COLOR",
+  "TUI_DEBUG",
+  "TUI_DEBUG_REDRAW",
+  "TUI_ESC_TIMEOUT",
+  "TUI_WRITE_LOG",
+];
+const CORE_ONLY_ENV = new Set(CORE_ONLY_ENV_NAMES.map((name) => `PI_${name}`));
+
+/**
+ * Keep provider credentials in the agent process, never in shell/MCP
+ * children; the core's PI_* variables stay there too (the children get the
+ * OMNIRUSH_* spellings).
+ */
 export function sanitizeToolEnvironment(input: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
   const output: NodeJS.ProcessEnv = {};
   for (const [key, value] of Object.entries(input)) {
-    if (!SECRET_ENV_NAMES.has(key) && value !== undefined) output[key] = value;
+    if (!SECRET_ENV_NAMES.has(key) && !CORE_ONLY_ENV.has(key) && value !== undefined) output[key] = value;
   }
   return output;
 }

package/assets/extensions/omnirush/session-sync.ts

@@ -159,13 +159,48 @@ function modelFallbackOf(result: any): ChildModelFallback | null {
   };
 }
 
+/** A task's own model that did not run (spawn_agents' model_override). */
+export type ChildModelOverride = { requested: string; used: string; effort: string | null; reason: string; note: string };
+
+/** The model and effort a sub-agent really ran on, once its result is final. */
+export type ChildRanOn = { model: string | null; effort: string | null; source: string | null; requested: string | null; status: string };
+
+function modelOverrideOf(result: any): ChildModelOverride | null {
+  const override = result && typeof result.model_override === "object" ? result.model_override : null;
+  if (!override || typeof override.requested !== "string" || typeof override.used !== "string") return null;
+  return {
+    requested: override.requested,
+    used: override.used,
+    effort: typeof override.effort === "string" ? override.effort : null,
+    reason: typeof override.reason === "string" ? override.reason : "user_choice",
+    note: typeof override.note === "string" ? override.note : `ran on ${override.used}`,
+  };
+}
+
+/** A finished child's model and effort (the gateway fallback's when the gateway moved it). */
+function ranOnOf(result: any, fallback: ChildModelFallback | null): ChildRanOn | null {
+  const status = result && typeof result.status === "string" ? result.status : "";
+  if (!status || status === "running" || status === "queued") return null;
+  const gateway = fallback?.kind === "gateway" ? fallback : null;
+  return {
+    model: gateway ? gateway.used : typeof result.model === "string" ? result.model : null,
+    effort: gateway ? gateway.effort : typeof result.effort === "string" ? result.effort : null,
+    source: typeof result.model_source === "string" ? result.model_source : null,
+    requested: typeof result.requested_model === "string" ? result.requested_model : null,
+    status,
+  };
+}
+
+type SpawnedChild = { id: string; role: string | null; task: string | null; modelFallback?: ChildModelFallback; modelOverride?: ChildModelOverride; ranOn?: ChildRanOn };
+
 /**
  * Sub-agents a session started: its spawn_agents results (session id, role,
  * task), with the model fallback a later result reported (a background
- * child's delivery, agents_wait / agents_result) when there is one.
+ * child's delivery, agents_wait / agents_result) when there is one, a task
+ * model that did not run, and the model and effort it ran on once finished.
  */
-export function spawnedChildren(entries: readonly PiEntry[]): Array<{ id: string; role: string | null; task: string | null; modelFallback?: ChildModelFallback }> {
-  const children: Array<{ id: string; role: string | null; task: string | null; modelFallback?: ChildModelFallback }> = [];
+export function spawnedChildren(entries: readonly PiEntry[]): SpawnedChild[] {
+  const children: SpawnedChild[] = [];
   for (const entry of entries) {
     const message = entry.type === "message" ? entry.message : null;
     const spawned = Boolean(message && message.role === "toolResult" && message.toolName === "spawn_agents");
@@ -182,16 +217,23 @@ export function spawnedChildren(entries: readonly PiEntry[]): Array<{ id: string
       if (!sanitizeSessionId(id)) continue;
       const known = children.find((child) => child.id === id);
       const modelFallback = modelFallbackOf(result);
+      const modelOverride = modelOverrideOf(result);
       if (known) {
         if (modelFallback) known.modelFallback = modelFallback;
+        if (modelOverride) known.modelOverride = modelOverride;
+        const ran = ranOnOf(result, known.modelFallback ?? null);
+        if (ran) known.ranOn = ran;
         continue;
       }
       if (!spawned) continue;
+      const ran = ranOnOf(result, modelFallback);
       children.push({
         id,
         role: typeof result.role === "string" ? result.role : null,
         task: typeof result.task === "string" ? result.task : null,
         ...(modelFallback ? { modelFallback } : {}),
+        ...(modelOverride ? { modelOverride } : {}),
+        ...(ran ? { ranOn: ran } : {}),
       });
     }
   }
@@ -200,6 +242,15 @@ export function spawnedChildren(entries: readonly PiEntry[]): Array<{ id: string
 
 /** Fallbacks already recorded as trace events (root session : child session). */
 const recordedFallbacks = new Set<string>();
+/** Overrides and ran-on models already recorded (same keys). */
+const recordedOverrides = new Set<string>();
+const recordedRanOn = new Set<string>();
+
+/** A child's trace title: its task, with the model note when its model was not the one asked for. */
+function childTitle(child: SpawnedChild): string | null {
+  const notes = [child.modelOverride?.note, child.modelFallback?.note].filter(Boolean);
+  return child.task && notes.length ? `${child.task} (${notes.join("; ")})` : child.task;
+}
 
 /** The session file of `sessionId`: `<ts>_<id>.jsonl` in one of the session dirs. */
 async function findSessionFile(sessionId: string, dirs: readonly string[]): Promise<string | null> {
@@ -369,13 +420,38 @@ export async function captureChildSessions(input: {
         kind: child.modelFallback.kind,
       });
     }
+    if (child.modelOverride && !recordedOverrides.has(fallbackKey)) {
+      // The task named a model that did not run: the user's /subagents
+      // choice won, or the gateway does not serve it to this account.
+      recordedOverrides.add(fallbackKey);
+      input.sync.recordTrace(input.rootSessionId, "subagent.model_override", {
+        child_session_id: child.id,
+        requested: child.modelOverride.requested,
+        used: child.modelOverride.used,
+        effort: child.modelOverride.effort,
+        reason: child.modelOverride.reason,
+      });
+    }
+    if (child.ranOn && !recordedRanOn.has(fallbackKey)) {
+      // What the sub-agent really ran on (after any gateway fallback).
+      recordedRanOn.add(fallbackKey);
+      input.sync.recordTrace(input.rootSessionId, "subagent.model", {
+        child_session_id: child.id,
+        role: child.role,
+        model: child.ranOn.model,
+        effort: child.ranOn.effort,
+        source: child.ranOn.source,
+        requested: child.ranOn.requested,
+        status: child.ranOn.status,
+      });
+    }
     if (history.delta.length > 0 || !input.known.has(child.id)) {
       await input.beforeRecord(history.sizes.reduce((total, bytes) => total + bytes, 0));
       input.sync.recordChildSession(input.rootSessionId, {
         childSessionId: child.id,
         parentSessionId: input.parentSessionId,
         depth: input.depth,
-        title: child.task && child.modelFallback ? `${child.task} (${child.modelFallback.note})` : child.task,
+        title: childTitle(child),
         agent: turnModelFromMessages(messages)?.agent ?? agent,
         messages: history.delta,
         lastMessageId: typeof messages.at(-1)?.info.id === "string" ? (messages.at(-1)!.info.id as string) : null,

package/assets/extensions/omnirush/subagents-lib.ts

@@ -12,7 +12,12 @@
 //     agent's model and the main agent's effort.
 //   - spawn_agents (agents.ts) resolves every task against it
 //     (resolveSubagentModel) and starts the child with that --model and
-//     --thinking; a task's own `model` wins over the picked one.
+//     --thinking. The user's choice wins over a task's own `model` (the
+//     agent's), which runs only when the user's message names it; with no
+//     choice set, a task model runs only when the account's catalog lists
+//     it (served), else the delegating agent's model and effort. Every
+//     override is on the result and in the trace (subagent.model_override),
+//     and every finished child's real model and effort (subagent.model).
 //   - A picked model that is not in the account's catalog (the list the
 //     launcher fetched from GET /v1/models), or that the gateway refused in
 //     the last five minutes, resolves to the main model instead (a
@@ -134,7 +139,9 @@ export function catalogFromPayload(payload: unknown): CatalogModel[] | null {
     const ownership = [entry.provider, entry.owned_by, entry.owner, entry.source, entry.namespace, entry.managed_by]
       .filter((value): value is string => typeof value === "string")
       .map((value) => value.trim().toLowerCase());
-    const shipped = ["gpt-6-astra", "gpt-6-sol", "gpt-5.6-sol", "meta-muse-spark", "muse-spark-1.1", "muse-spark-1.3", "muse-spark-1.2-contributor"];
+    // Ids the gateway serves under their bare names; an id counts as served
+    // only when this payload lists it (never because the CLI ships it).
+    const shipped = ["gpt-6-astra", "gpt-6-sol", "gpt-5.6-sol", "meta-muse-spark", "muse-spark-1.1"];
     if (!shipped.includes(id) && entry.omnirush !== true && !ownership.includes("omnirush")) continue;
     const levels = Array.isArray(entry.reasoning_levels)
       ? EFFORTS.filter((effort) => entry.reasoning_levels.some((level: unknown) => parseEffort(level) === effort))
@@ -323,6 +330,26 @@ export interface SubagentFallback {
   reason: FallbackReason | string;
 }
 
+/** Why a task's own `model` did not run: the user's /subagents choice, or the gateway does not serve it. */
+export type OverrideReason = "user_choice" | "not_served" | "catalog_unavailable" | "refused";
+
+/** A task's own `model[:effort]` that was not used, and what ran instead. */
+export interface SubagentOverride {
+  /** The task's model[:effort] as the agent wrote it. */
+  requested: string;
+  used: string;
+  effort: string | null;
+  reason: OverrideReason;
+}
+
+/**
+ * Where a sub-agent's model comes from: "subagents" (the user's /subagents
+ * choice), "user_prompt" (a task model the user's own message named),
+ * "task" (a task model the gateway serves, /subagents unset) or "parent"
+ * (the delegating agent's model and effort).
+ */
+export type ModelSource = "subagents" | "user_prompt" | "task" | "parent";
+
 export interface SubagentResolution {
   /** The model the child runs on; null = leave the child to pi's own default (no omnirush model known). */
   model: string | null;
@@ -332,6 +359,10 @@ export interface SubagentResolution {
   fallback?: SubagentFallback;
   /** The main model (and effort) the child's gateway guard moves to when the gateway refuses `model`. */
   gatewayFallback?: { model: string; effort: string | null };
+  /** The task named a model that did not run (the user's choice won, or it is not served). */
+  override?: SubagentOverride;
+  /** Where the model comes from (absent when no omnirush model is known). */
+  source?: ModelSource;
 }
 
 export interface AgentModel {
@@ -342,14 +373,33 @@ export interface AgentModel {
   effort: string | null;
 }
 
+/** Whether `text` names the model id `id` (case-insensitive, as a whole id: "gpt-6-sol" is not named by "gpt-6-sol-mini" or "gpt-5.6-sol"). */
+export function textNamesModel(text: string | null | undefined, id: string): boolean {
+  if (typeof text !== "string" || !text || !id) return false;
+  const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(?<![A-Za-z0-9._-])${escaped}(?![A-Za-z0-9_-]|\\.[A-Za-z0-9])`, "i").test(text);
+}
+
+/** Whether the gateway serves `model` to this account: the live catalog lists it. */
+export function isServed(catalog: readonly CatalogModel[] | null, model: string): boolean {
+  return Boolean(catalog?.some((entry) => entry.id === model));
+}
+
 /**
  * What one sub-agent runs on.
  *
  * `delegating` is the agent calling spawn_agents (its model is what "same as
  * main" keeps); `main` is the main session's model and effort (handed down
  * to nested layers through the environment), the one a picked model falls
- * back to. `explicit` is the task's own `model`, which wins over the picked
- * one and is not checked against the catalog (the gateway decides).
+ * back to. `explicit` is the task's own `model[:effort]` (the agent's
+ * choice) and `userPrompt` the user's latest message:
+ *   - the user set /subagents (model and/or effort): that choice wins; a
+ *     task model runs only when the user's own message names it (and the
+ *     gateway serves it), otherwise it is overridden ("user_choice");
+ *   - /subagents unset: a task model runs only when the account's live
+ *     catalog lists it (and the gateway did not refuse it a moment ago);
+ *     otherwise the delegating agent's model and the main effort run
+ *     ("not_served", "catalog_unavailable" or "refused").
  */
 export function resolveSubagentModel(input: {
   setting: SubagentSetting;
@@ -357,6 +407,7 @@ export function resolveSubagentModel(input: {
   delegating: AgentModel;
   main?: AgentModel | null;
   explicit?: string | null;
+  userPrompt?: string | null;
   refused?: (model: string) => boolean;
 }): SubagentResolution {
   const { setting, catalog, delegating } = input;
@@ -364,6 +415,7 @@ export function resolveSubagentModel(input: {
   const mainIsGateway = main.provider === PROVIDER_ID && Boolean(main.model);
   const wantedEffort = setting.effort ?? parseEffort(main.effort) ?? null;
   const effortOn = (model: string): string | null => nearestEffort(wantedEffort, levelsFor(catalog, model));
+  const userChose = Boolean(setting.model || setting.effort);
 
   const withGatewayFallback = (resolution: SubagentResolution): SubagentResolution => {
     if (
@@ -377,21 +429,39 @@ export function resolveSubagentModel(input: {
     return resolution;
   };
 
-  // The task's own model[:effort]: an effort it names wins over the picked
-  // and the parent's (mapped to the nearest level the model offers).
-  const explicit = input.explicit && isModelId(input.explicit) ? splitModelEffort(input.explicit) : null;
+  // The task's own model[:effort].
+  const requested = typeof input.explicit === "string" ? input.explicit.trim() : "";
+  const explicit = requested && isModelId(requested) ? splitModelEffort(requested) : null;
+  let overrideReason: OverrideReason | null = null;
   if (explicit && isModelId(explicit.model)) {
-    const effort = explicit.effort ? nearestEffort(explicit.effort, levelsFor(catalog, explicit.model)) ?? explicit.effort : effortOn(explicit.model);
-    return withGatewayFallback({ model: explicit.model, effort });
+    const served = isServed(catalog, explicit.model);
+    const refusedNow = served && Boolean(input.refused?.(explicit.model));
+    const named = served && textNamesModel(input.userPrompt, explicit.model);
+    const allowed = served && !refusedNow && (userChose ? named : true);
+    if (allowed) {
+      // An effort the task names applies unless the user picked one with /subagents.
+      const taskEffort = explicit.effort && !setting.effort ? explicit.effort : null;
+      const effort = taskEffort ? nearestEffort(taskEffort, levelsFor(catalog, explicit.model)) ?? taskEffort : effortOn(explicit.model);
+      return withGatewayFallback({ model: explicit.model, effort, source: named ? "user_prompt" : "task" });
+    }
+    overrideReason = userChose ? "user_choice" : !catalog ? "catalog_unavailable" : !served ? "not_served" : "refused";
   }
+  const withOverride = (resolution: SubagentResolution): SubagentResolution => {
+    if (!overrideReason || !explicit || !resolution.model) return resolution;
+    // The same model at the same effort is no override.
+    if (explicit.model === resolution.model && (!explicit.effort || explicit.effort === resolution.effort)) return resolution;
+    resolution.override = { requested, used: resolution.model, effort: resolution.effort, reason: overrideReason };
+    return resolution;
+  };
 
   if (setting.model) {
     const inCatalog = !catalog || catalog.some((entry) => entry.id === setting.model);
     const reason: FallbackReason | null = !inCatalog ? "not_in_catalog" : input.refused?.(setting.model) ? "refused" : null;
     if (reason && mainIsGateway && main.model !== setting.model) {
-      return {
+      return withOverride({
         model: main.model!,
         effort: effortOn(main.model!),
+        source: "subagents",
         fallback: {
           requested: setting.model,
           requestedName: displayName(catalog, setting.model),
@@ -399,16 +469,46 @@ export function resolveSubagentModel(input: {
           usedName: displayName(catalog, main.model!),
           reason,
         },
-      };
+      });
     }
-    return withGatewayFallback({ model: setting.model, effort: effortOn(setting.model) });
+    return withOverride(withGatewayFallback({ model: setting.model, effort: effortOn(setting.model), source: "subagents" }));
   }
 
   // "Same as main": the delegating agent's own model.
   if (delegating.provider !== PROVIDER_ID || !delegating.model) {
     return { model: null, effort: null };
   }
-  return withGatewayFallback({ model: delegating.model, effort: effortOn(delegating.model) });
+  return withOverride(withGatewayFallback({
+    model: delegating.model,
+    effort: effortOn(delegating.model),
+    source: userChose ? "subagents" : "parent",
+  }));
+}
+
+/** A readable note for a task model that did not run (for the parent's result and the trace title). */
+export function overrideNote(override: SubagentOverride, catalog: readonly CatalogModel[] | null = null): string {
+  const ran = `${displayName(catalog, override.used)}${override.effort ? ` · ${override.effort}` : ""}`;
+  switch (override.reason) {
+    case "user_choice":
+      return `ran on ${ran}, your /subagents choice (${override.requested} was asked for)`;
+    case "not_served":
+      return `ran on ${ran}, the parent's model: ${override.requested} is not served to this account`;
+    case "catalog_unavailable":
+      return `ran on ${ran}, the parent's model: the account's model list is not available to check ${override.requested}`;
+    default:
+      return `ran on ${ran}, the parent's model: ${override.requested} was refused by omnirush.ai recently`;
+  }
+}
+
+/** How a sub-agent's model was chosen, in words (the result the parent reads). */
+export function sourceNote(source: ModelSource | string | undefined): string {
+  switch (source) {
+    case "subagents": return "your /subagents choice";
+    case "user_prompt": return "named in your message";
+    case "task": return "the task's model";
+    case "parent": return "same as the parent";
+    default: return "";
+  }
 }
 
 /** A readable note for a sub-agent that ran on the main model instead of the picked one. */

package/assets/extensions/omnirush/subagents.ts

@@ -31,6 +31,7 @@ import {
   loadCatalog,
   nearestEffort,
   nextSetting,
+  overrideNote,
   parseEffort,
   PROVIDER_ID,
   readSetting,
@@ -115,7 +116,12 @@ export function mainModel(pi: any, ctx: any, env: NodeJS.ProcessEnv = process.en
  * model when the picked one is not available, and the environment that hands
  * the setting and the main model down to nested layers.
  */
-export function subagentTasks(pi: any, ctx: any, tasks: ChildTask[], options: { dir?: string; env?: NodeJS.ProcessEnv; now?: number } = {}): ChildTask[] {
+export function subagentTasks(
+  pi: any,
+  ctx: any,
+  tasks: ChildTask[],
+  options: { dir?: string; env?: NodeJS.ProcessEnv; now?: number; userPrompt?: string | null } = {},
+): ChildTask[] {
   const dir = options.dir ?? omniDir();
   const env = options.env ?? process.env;
   const { setting } = currentSetting(pi, dir);
@@ -137,12 +143,17 @@ export function subagentTasks(pi: any, ctx: any, tasks: ChildTask[], options: {
       delegating,
       main,
       explicit: task.model ?? null,
+      userPrompt: options.userPrompt ?? null,
       refused: (model) => Boolean(isRefused(dir, model, options.now)),
     });
     const next: ChildTask = { ...task, env: { ...(task.env ?? {}), ...handDown } };
+    if (task.model) next.requestedModel = task.model;
     if (resolution.model) next.model = resolution.model;
     else delete next.model;
     if (resolution.model && resolution.effort) next.effort = resolution.effort;
+    else delete next.effort;
+    if (resolution.source) next.modelSource = resolution.source;
+    if (resolution.override) next.override = { ...resolution.override, note: overrideNote(resolution.override, catalog) };
     if (resolution.fallback) next.fallback = resolution.fallback;
     if (resolution.gatewayFallback) next.gatewayFallback = resolution.gatewayFallback;
     return next;
@@ -292,7 +303,7 @@ export default function (pi: any) {
       if (patch.model !== undefined) override.model = next.model;
       if (patch.effort !== undefined || next.effort !== current.effort) override.effort = next.effort;
       sessionOverrides.set(pi, override);
-      if (patch.model !== undefined && current.effort && next.effort === null) {
+      if (command !== "reset" && patch.model !== undefined && current.effort && next.effort === null) {
         notify(`Sub-agent effort ${current.effort} is not offered by ${next.model ? displayName(catalog, next.model) : "the main model"}: back to same as main.`, "warning");
       }
       if (next.effort && next.model === null && main.model) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omnirush",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "description": "Omnirush — free daily tokens for the most powerful coding model on earth.",
   "license": "Apache-2.0",
   "type": "module",

package/scripts/brand-engine.js

@@ -23,10 +23,16 @@
 //      folders), OMNIRUSH_* copies of the env the core exports to shell
 //      commands, AI_AGENT, the HTTP User-Agent and temp-file names.
 //
+//   4. <package>/engine, a link to the core (src/compat.js
+//      ensureEngineLink): the launcher runs the core through it, so process
+//      listings and the doc paths in the system prompt name omnirush, not
+//      the core's npm package.
+//
 // Not renamed (internal, never shown): package ids and imports, code
 // identifiers, session entry/customType ids, telemetry attribute keys,
 // protocol values third-party providers expect, and the PI_* env names the
-// core reads (the launcher maps OMNIRUSH_* spellings onto them).
+// core reads (the launcher maps OMNIRUSH_* spellings onto them; shells the
+// core starts get the OMNIRUSH_* copies only).
 //
 // Maintenance: after bumping the core, run `node scripts/brand-engine.js`
 // and `node --test test/branding.test.js`; a target that moved is reported
@@ -38,11 +44,16 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { CORE_ONLY_ENV_NAMES, ensureEngineLink } from "../src/compat.js";
+
 const PKG = "@earendil-works/pi-coding-agent";
 const BRAND = "omnirush";
 export const BRAND_CONFIG_DIR = ".omnirush";
 const OUR_CHANGELOG = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "assets", "CHANGELOG.md");
 
+/** Matches the core's own PI_<NAME> variables (src/compat.js CORE_ONLY_ENV_NAMES), as JS regex source. */
+export const CORE_ENV_PATTERN = `/^PI_(${CORE_ONLY_ENV_NAMES.join("|")})$/`;
+
 // `from` must match the installed dist exactly; applied with replaceAll to
 // every dist/**/*.js. A `to` must never contain its own `from` (idempotency).
 export const REPLACEMENTS = [
@@ -157,13 +168,37 @@ export const REPLACEMENTS = [
   {
     label: "/bug disclaimer",
     from: "This report goes to the Pi developers (Earendil) and is not shared publicly. It includes your pi version,",
-    to: "This report goes to the agent core's upstream developers (Earendil) and is not shared publicly. It includes your omnirush version,",
+    to: "This report is not shared publicly. It includes your omnirush version,",
   },
   {
     label: "announcement easter egg",
     from: '"pi has joined Earendil"',
-    to: '"The agent core has joined Earendil"',
+    to: '"omnirush"',
+  },
+  {
+    // Upstream easter eggs typed as commands (/arminsayshi, /dementedelves;
+    // the third only fires for one third-party model): shown nothing.
+    label: "hidden /arminsayshi is inert (bundle)",
+    from: "handleArminSaysHi(){",
+    to: "handleArminSaysHi(_off){return;",
+  },
+  {
+    label: "hidden /dementedelves is inert (bundle)",
+    from: "handleDementedDelves(){",
+    to: "handleDementedDelves(_off){return;",
   },
+  { label: "upstream easter egg is inert (bundle)", from: "handleDaxnuts(){", to: "handleDaxnuts(_off){return;" },
+  {
+    label: "hidden /arminsayshi is inert (dist)",
+    from: "    handleArminSaysHi() {",
+    to: "    handleArminSaysHi(_off) { return;",
+  },
+  {
+    label: "hidden /dementedelves is inert (dist)",
+    from: "    handleDementedDelves() {",
+    to: "    handleDementedDelves(_off) { return;",
+  },
+  { label: "upstream easter egg is inert (dist)", from: "    handleDaxnuts() {", to: "    handleDaxnuts(_off) { return;" },
   {
     label: "external editor note",
     from: "Pi will resume when the editor exits.",
@@ -345,7 +380,20 @@ export const REPLACEMENTS = [
     label: "OMNIRUSH_* session env for shell commands",
     from: "ctx.thinkingLevel&&(env2.PI_REASONING_LEVEL=ctx.thinkingLevel)}let baseContext={command,cwd,env:env2}",
     to:
-      'ctx.thinkingLevel&&(env2.PI_REASONING_LEVEL=ctx.thinkingLevel)}for(let k of["SESSION_ID","SESSION_FILE","PROVIDER","MODEL","REASONING_LEVEL"])env2["PI_"+k]===void 0?delete env2["OMNIRUSH_"+k]:env2["OMNIRUSH_"+k]=env2["PI_"+k];let baseContext={command,cwd,env:env2}',
+      'ctx.thinkingLevel&&(env2.PI_REASONING_LEVEL=ctx.thinkingLevel)}for(let k of["SESSION_ID","SESSION_FILE","PROVIDER","MODEL","REASONING_LEVEL"])env2["PI_"+k]===void 0?delete env2["OMNIRUSH_"+k]:(env2["OMNIRUSH_"+k]=env2["PI_"+k],delete env2["PI_"+k]);let baseContext={command,cwd,env:env2}',
+  },
+  {
+    // The env every shell the core starts inherits (the bash tool, `!`
+    // commands, package installs): the core's own PI_* variables stay in
+    // the agent process; their OMNIRUSH_* copies are what commands see.
+    label: "no core PI_* variables in shell commands (bundle)",
+    from: "return{...process.env,[pathKey]:updatedPath}}function sanitizeBinaryOutput",
+    to: `let _env={...process.env,[pathKey]:updatedPath};for(let k of Object.keys(_env))${CORE_ENV_PATTERN}.test(k)&&delete _env[k];return _env}function sanitizeBinaryOutput`,
+  },
+  {
+    label: "no core PI_* variables in shell commands (dist)",
+    from: "    return {\n        ...process.env,\n        [pathKey]: updatedPath,\n    };\n}",
+    to: `    const _env = { ...process.env, [pathKey]: updatedPath };\n    for (const k of Object.keys(_env)) if (${CORE_ENV_PATTERN}.test(k)) delete _env[k];\n    return _env;\n}`,
   },
 
   // --- HTTP User-Agent (the omnirush gateway sees it) --------------------
@@ -377,6 +425,9 @@ export const REPLACEMENTS = [
   { label: "bug report zip", from: "`pi-bug-report-${id}.zip`", to: "`omnirush-bug-report-${id}.zip`" },
   { label: "TUI crash log", from: '"pi-tui-crash.log"', to: '"omnirush-tui-crash.log"' },
   { label: "TUI debug log", from: '"pi-tui-debug.log"', to: '"omnirush-tui-debug.log"' },
+  { label: "git package update marker", from: ".pi-update-incomplete", to: ".omnirush-update-incomplete" },
+  { label: "native module quarantine dir", from: '".pi-native-quarantine"', to: '".omnirush-native-quarantine"' },
+  { label: "package install root package.json name", from: '"pi-extensions"', to: '"omnirush-extensions"' },
 
   // --- update banner (belt-and-braces; the launcher sets PI_OFFLINE) -----
   // showNewVersionNotification returns before its body (the parameter is
@@ -507,6 +558,9 @@ function main() {
     console.log("omnirush: agent core not installed; skipped branding patch");
     return;
   }
+  // <package>/engine -> the core (what process listings and the system
+  // prompt's doc paths show; the launcher re-creates it when missing).
+  ensureEngineLink(repoRoot, report.piRoot);
   const patched = report.packageJsonPatched ? "package.json + " : "";
   const notes = report.changelogReplaced ? " + release notes" : "";
   console.log(

package/src/bin.js

@@ -54,7 +54,7 @@ import {
   yoloBanner,
 } from "./lib.js";
 import { installManagedTools } from "./tools.js";
-import { engineEnvAliases, migrateAgentDir, projectConfigDirName, resolveAgentDir } from "./compat.js";
+import { engineEnvAliases, ensureEngineLink, migrateAgentDir, projectConfigDirName, resolveAgentDir } from "./compat.js";
 import { customSessionDir, moveLegacySubagentSessions } from "./sessions.js";
 import { ensureRuntime, managedBunPath } from "../scripts/postinstall.js";
 import {
@@ -144,12 +144,31 @@ function piPackage() {
   return null;
 }
 
+// The core as users see it (process listings, the doc paths in the system
+// prompt, sub-agent command lines): <package>/engine, a link to the core's
+// folder (src/compat.js ensureEngineLink); null when the link cannot be made.
+let ENGINE_LINK_DIR = null;
+let ENGINE_ENTRY = null;
+
 function piEntry() {
   const found = piPackage();
-  if (found?.pkg?.bin?.pi) return path.join(found.dir, found.pkg.bin.pi);
+  if (found?.pkg?.bin?.pi) {
+    const dir = ensureEngineLink(path.resolve(__dirname, ".."), found.dir);
+    ENGINE_LINK_DIR = dir === path.resolve(found.dir) ? null : dir;
+    ENGINE_ENTRY = path.join(dir, found.pkg.bin.pi);
+    return ENGINE_ENTRY;
+  }
   throw new Error("could not locate the pinned agent core (broken install). Fix: npm install -g omnirush@latest");
 }
 
+/** The core's package dir as the link, unless the user points it elsewhere. */
+function engineDirEnv(env = process.env) {
+  const env2 = {};
+  if (ENGINE_ENTRY) env2.OMNIRUSH_CORE_ENTRY = ENGINE_ENTRY; // sub-agents start the core through the same path
+  if (ENGINE_LINK_DIR && !env.PI_PACKAGE_DIR && !env.OMNIRUSH_PACKAGE_DIR) env2.PI_PACKAGE_DIR = ENGINE_LINK_DIR;
+  return env2;
+}
+
 function ensureDirs() {
   fs.mkdirSync(OMNI_DIR, { recursive: true, mode: 0o700 });
   migrateLegacyAgentData();
@@ -875,6 +894,7 @@ function childEnv(auth) {
   const origin = (process.env.OMNIRUSH_ORIGIN || "").trim().replace(/\/+$/, "") ||
     gateway.replace(/\/+$/, "").replace(/\/v1$/, ""); // provider base -> manager origin
   return {
+    ...engineDirEnv(process.env),
     // OMNIRUSH_* spellings of the core's own settings (PI_* still work).
     ...engineEnvAliases(process.env),
     // Bootstrap values only: the agent (and every sub-agent it spawns)
@@ -1090,8 +1110,7 @@ Environment:
                          (default 50% of RAM), and none start below this
                          (default 10%); e.g. 25% or 6G. OMNIRUSH_AGENT_MEMORY=off
                          starts them without checking memory
-  OMNIRUSH_<SETTING>     the agent core's own settings (e.g. OMNIRUSH_CACHE_RETENTION;
-                         the older PI_<SETTING> names still work)
+  OMNIRUSH_<SETTING>     the agent core's own settings (e.g. OMNIRUSH_CACHE_RETENTION)
 
 Docs: https://omnirush.ai/omnirush — state is stored 0600 in ~/.omnirush`);
 }

package/src/compat.js

@@ -270,3 +270,68 @@ export function engineEnvAliases(env = process.env) {
   }
   return out;
 }
+
+/**
+ * The core's own variables the launcher and the core set for themselves
+ * (PI_<NAME>). Shell commands the agent runs, background jobs and MCP
+ * servers see their OMNIRUSH_<NAME> copies only; a PI_ variable that is
+ * not on this list (a user's own) passes through. Mirrored in
+ * scripts/brand-engine.js (the core's shell env) and
+ * assets/extensions/omnirush/secret-env.ts (tests keep them equal).
+ */
+export const CORE_ONLY_ENV_NAMES = [
+  "CODING_AGENT",
+  "CODING_AGENT_DIR",
+  "CODING_AGENT_SESSION_DIR",
+  "SESSION_ID",
+  "SESSION_FILE",
+  "PROVIDER",
+  "MODEL",
+  "REASONING_LEVEL",
+  "OFFLINE",
+  "TELEMETRY",
+  "INSTALLER_API_BASE",
+  "MANAGED_INSTALL_ROOT",
+  ...ENGINE_ENV_NAMES,
+];
+
+/** Folder, in the omnirush package, that links to the installed agent core. */
+export const ENGINE_LINK = "engine";
+
+/**
+ * The agent core as users see it: <package root>/engine, a link to the
+ * core's folder in node_modules (a junction on Windows). The launcher runs
+ * the core through it and hands it over as the core's package dir, so
+ * process listings, the doc paths in the system prompt and the sub-agent
+ * command lines name omnirush instead of the core's npm package. Made by
+ * the branding step at install and, when missing (archives, a read-only
+ * reinstall), here at launch. Never replaces a real folder. Returns the
+ * link, or the core's own folder when the link cannot be made.
+ */
+export function ensureEngineLink(packageRoot, coreDir, { fsImpl = fs, platform = process.platform } = {}) {
+  const link = path.join(packageRoot, ENGINE_LINK);
+  const real = path.resolve(coreDir);
+  const points = () => {
+    try {
+      return fsImpl.realpathSync(link) === fsImpl.realpathSync(real);
+    } catch {
+      return false;
+    }
+  };
+  if (points()) return link;
+  try {
+    let stat = null;
+    try {
+      stat = fsImpl.lstatSync(link);
+    } catch {
+      /* absent */
+    }
+    if (stat && !stat.isSymbolicLink()) return real;
+    if (stat) fsImpl.unlinkSync(link); // a stale link (the core moved)
+    if (platform === "win32") fsImpl.symlinkSync(real, link, "junction");
+    else fsImpl.symlinkSync(path.relative(path.dirname(link), real) || ".", link, "dir");
+  } catch {
+    /* read-only install or a concurrent launch: checked below */
+  }
+  return points() ? link : real;
+}