@nredd/pi-subagents 0.22.0-nredd.6 → 0.22.0-nredd.8

package/src/resource-loader.ts

@@ -0,0 +1,51 @@
+/** Normalize explicit settings paths before Pi's real package manager resolves them. */
+import { DefaultResourceLoader, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { normalizeHomePath } from "./home-paths.js";
+
+type ResourceLoaderOptions = ConstructorParameters<typeof DefaultResourceLoader>[0];
+type ResourceSettings = ReturnType<SettingsManager["getGlobalSettings"]>;
+
+const RESOURCE_FIELDS = ["extensions", "skills", "prompts", "themes"] as const;
+
+/** Keep filter modifiers and non-home paths intact; only replace leading home references. */
+function expandSetting(entry: string, homeDir: string, modifiers = true): string {
+  const prefix = modifiers && /^[!+-]/.test(entry) ? entry[0] : "";
+  const path = entry.slice(prefix.length);
+  const trimmed = path.trim();
+  if (trimmed !== "~" && !trimmed.startsWith("~/") && !(process.platform === "win32" && trimmed.startsWith("~\\"))) return entry;
+  return prefix + normalizeHomePath(trimmed, homeDir);
+}
+
+/** Return copies so loading resources never changes persisted settings or their source objects. */
+export function normalizeResourceSettings(settings: ResourceSettings, homeDir: string): ResourceSettings {
+  const normalized = { ...settings };
+  for (const field of RESOURCE_FIELDS) {
+    if (settings[field]) normalized[field] = settings[field].map(entry => expandSetting(entry, homeDir));
+  }
+  if (settings.packages) {
+    normalized.packages = settings.packages.map(pkg => {
+      if (typeof pkg === "string") return expandSetting(pkg, homeDir, false);
+      const copy = { ...pkg, source: expandSetting(pkg.source, homeDir, false) };
+      for (const field of RESOURCE_FIELDS) {
+        if (pkg[field]) copy[field] = pkg[field].map(entry => expandSetting(entry, homeDir));
+      }
+      return copy;
+    });
+  }
+  return normalized;
+}
+
+/** Use the real loader/manager while preventing ambient-home expansion of explicit settings. */
+export function createHomeResourceLoader(options: ResourceLoaderOptions, homeDir?: string): DefaultResourceLoader {
+  if (homeDir === undefined) return new DefaultResourceLoader(options);
+  const settingsManager = options.settingsManager ?? SettingsManager.create(options.cwd, options.agentDir);
+  const globalSettings = settingsManager.getGlobalSettings.bind(settingsManager);
+  const projectSettings = settingsManager.getProjectSettings.bind(settingsManager);
+  // Wrap the public readers, not a cached snapshot: reload and project-trust
+  // decisions continue to be owned by Pi, and every read receives fresh copies.
+  Object.assign(settingsManager, {
+    getGlobalSettings: () => normalizeResourceSettings(globalSettings(), homeDir),
+    getProjectSettings: () => normalizeResourceSettings(projectSettings(), homeDir),
+  });
+  return new DefaultResourceLoader({ ...options, settingsManager });
+}

package/src/schedule.ts

@@ -15,15 +15,14 @@
  *     `subagent-notification` path. No new delivery code.
  */
 
-import type { Model } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Cron } from "croner";
 import { nanoid } from "nanoid";
 import type { AgentManager } from "./agent-manager.js";
 import { normalizeMaxTurns } from "./agent-runner.js";
-import { resolveSpawnType } from "./agent-types.js";
+import { getAgentConfig, resolveSpawnType } from "./agent-types.js";
 import { type Clock, realClock, type TimerHandle } from "./clock.js";
-import { resolveModel } from "./model-resolver.js";
+import { admitModelSelection, type ModelSelection, selectModel } from "./model-selection.js";
 import { checkAdmission, describeBlock, mayPark, modelRef, PARKED_RESUME_DELAY_MS, QUOTA_RESTART_GRACE_MS } from "./quota-admission.js";
 import type { ScheduleStore } from "./schedule-store.js";
 import type { IsolationMode, ScheduledSubagent, SubagentType, ThinkingLevel } from "./types.js";
@@ -54,6 +53,7 @@ export interface NewJobInput {
 
 /** Optional in-process scheduling dependencies; omitted clock uses native time. */
 export interface SubagentSchedulerOptions {
+  homeDir?: string;
   clock?: Clock;
 }
 
@@ -66,7 +66,7 @@ export class SubagentScheduler {
   private ctx: ExtensionContext | undefined;
   private manager: AgentManager | undefined;
 
-  constructor(options: SubagentSchedulerOptions = {}) {
+  constructor(private readonly options: SubagentSchedulerOptions = {}) {
     this.clock = options.clock ?? realClock;
   }
 
@@ -247,22 +247,34 @@ export class SubagentScheduler {
 
     store.update(id, { lastStatus: "running" });
 
-    // Resolve model at fire time — registry contents may have changed since the
-    // job was created (auth added/removed). Fall back silently to spawn-default
-    // if resolution fails; the spawn path handles undefined model gracefully.
-    let resolvedModel: Model<any> | undefined;
-    if (job.model) {
-      const r = resolveModel(job.model, ctx.modelRegistry);
-      if (typeof r !== "string") resolvedModel = r;
+    // Resolve the original request at fire time, using the same type and model
+    // policy as a manual dispatch. Never drop a failed explicit override.
+    const dispatch = resolveSpawnType(job.subagent_type);
+    const config = dispatch.ok ? getAgentConfig(dispatch.type) : undefined;
+    const selection = dispatch.ok ? selectModel({
+      homeDir: this.options.homeDir,
+      agentType: dispatch.type, definitionModel: config?.model, agentLabel: config?.displayName,
+      paramModel: job.model, parentModel: ctx.model, registry: ctx.modelRegistry, cwd: ctx.cwd,
+    }) : dispatch.message;
+    if (typeof selection === "string") {
+      store.update(id, { lastRun: new Date(this.clock.now()).toISOString(), lastStatus: "error" });
+      this.emit({ type: "error", jobId: id, error: selection });
+      return;
     }
 
+    if (selection.scopeWarning) ctx.ui.notify(selection.scopeWarning, "warning");
+
     // A quota-parked job re-asks the router before starting: the window it
     // waited for may have refilled while another is still exhausted.
-    const admissionModel = resolvedModel ?? ctx.model;
-    if (job.quotaParked && admissionModel) {
-      void checkAdmission(pi.events, modelRef(admissionModel)).then(block => {
+    const admissionModel = selection.model;
+    if ((job.quotaParked || selection.tierBinding) && admissionModel) {
+      const admission = selection.tierBinding
+        ? admitModelSelection(selection, ctx.modelRegistry, pi.events)
+        : checkAdmission(pi.events, modelRef(admissionModel));
+      void admission.then(block => {
+        if (this.store !== store || this.ctx !== ctx) return;
         if (!block) {
-          this.spawnJob(id, resolvedModel);
+          this.spawnJob(id, selection);
         } else if (mayPark(block) && block.resetAt > this.clock.now()) {
           this.repark(id, block.resetAt);
         } else {
@@ -272,10 +284,14 @@ export class SubagentScheduler {
           this.store?.update(id, { lastRun: new Date(this.clock.now()).toISOString(), lastStatus: "error" });
           this.emit({ type: "error", jobId: id, error: `${describeBlock(block)} The agent was not started.` });
         }
+      }).catch(error => {
+        if (this.store !== store) return;
+        store.update(id, { lastStatus: "error" });
+        this.emit({ type: "error", jobId: id, error: error instanceof Error ? error.message : String(error) });
       });
       return;
     }
-    this.spawnJob(id, resolvedModel);
+    this.spawnJob(id, selection);
   }
 
   /** Re-arm a quota-parked one-shot at a later reset instead of starting it. */
@@ -285,11 +301,12 @@ export class SubagentScheduler {
       enabled: true,
       schedule: new Date(resetAt + QUOTA_RESTART_GRACE_MS).toISOString(),
       lastStatus: undefined,
+      quotaParked: true,
     });
   }
 
   /** Spawn a fired job (bypassing the concurrency queue) and persist its outcome. */
-  private spawnJob(id: string, resolvedModel: Model<any> | undefined): void {
+  private spawnJob(id: string, selection: ModelSelection): void {
     const store = this.store;
     const pi = this.pi;
     const ctx = this.ctx;
@@ -312,7 +329,8 @@ export class SubagentScheduler {
         description: job.description,
         isBackground: true,
         bypassQueue: true,
-        model: resolvedModel,
+        model: selection.model,
+        modelSelection: selection,
         maxTurns: job.max_turns,
         isolated: job.isolated,
         thinkingLevel: job.thinking,
@@ -357,7 +375,11 @@ export class SubagentScheduler {
     // Terminal states: completed/steered = success; error/aborted/stopped = error.
     // awaitStartup first: with isolation: "worktree" the run promise only exists
     // once the repo copy is made, and a failed copy rejects here.
-    manager.awaitStartup(agentId)
+    // The start gate comes first: `bypassQueue` skips the pool but not the
+    // process budget (`maxActiveSubagents`), so a fired job can sit "queued"
+    // with no startup and no promise yet, and would otherwise finalize at once.
+    Promise.resolve(manager.getRecord(agentId)?.startGate)
+      .then(() => manager.awaitStartup(agentId))
       .then(() => manager.getRecord(agentId)?.promise)
       .then(() => {
         const r = manager.getRecord(agentId);

package/src/settings.ts

@@ -4,9 +4,11 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { NO_FALLBACK } from "./agent-types.js";
 import { readEnterpriseLocalManifest } from "./enterprise-local.js";
+import { resolveAgentDir } from "./home-paths.js";
+import { type ModelResolution, parseTierBinding, setModelTiers } from "./model-tiers.js";
+import { type BudgetPolicy, DEFAULT_BUDGET_POLICY } from "./process-budget.js";
 import type { AgentMentionMode, JoinMode, ViewerMarkdownMode, WidgetMode } from "./types.js";
 
 export interface SubagentsSettings {
@@ -33,6 +35,30 @@ export interface SubagentsSettings {
    * several blocking resumes in one message can still exceed the limit.
    */
   maxConcurrentForeground?: number;
+  /**
+   * Process-wide ceiling on running subagents, across every manager in this pi
+   * process: top-level, nested, workflow, scheduled, RPC and mention spawns,
+   * and resumes, in the root session and in sessions a `/new`, `/resume`,
+   * `/fork` or `/reload` left running. `0` = off, the default. The process,
+   * not the machine: two pi processes each get their own. See
+   * `process-budget.ts`.
+   *
+   * Global configuration only, like `modelAliases`: a project file's value is
+   * ignored with a warning. Shared by every activation in the process, so the
+   * last one to apply its settings wins. A change that tightens it waits until
+   * no subagent in the process holds a slot (`setBudgetPolicy`).
+   */
+  maxActiveSubagents?: number;
+  /**
+   * Slots of `maxActiveSubagents` held back per nesting level below a run, so
+   * parents that keep their slot while they wait can never starve their own
+   * children. Defaults to `2`; with the global `maxSubagentDepth: 2` that
+   * leaves `maxActiveSubagents - 2` for top-level runs. With nesting on it
+   * must be at least `1`, and `maxActiveSubagents` at least
+   * `nestedSubagentReserve * (maxSubagentDepth - 1) + 1`; a budget that
+   * breaks either is ignored with a warning, since it could deadlock.
+   */
+  nestedSubagentReserve?: number;
   /**
    * 0 = unlimited — the extension's single source of truth for that convention:
    * `normalizeMaxTurns()` in agent-runner.ts treats 0 → `undefined`, and the
@@ -243,6 +269,10 @@ export interface SubagentsSettings {
   fallbackSubagent?: string;
   /** Trusted-global logical name -> ordered canonical provider/model candidates. */
   modelAliases?: Record<string, string[]>;
+  /** Trusted global/enterprise exact model bindings; never read from a project. */
+  modelTiers?: Record<string, string[]>;
+  /** Missing/unavailable tier policy. Both default to inherit with disclosure. */
+  modelResolution?: ModelResolution;
   /**
    * Trusted-global map of agent `type` (or `"*"` for every type) -> model, in
    * any form `Agent({ model })` accepts. Precedence, highest first: the Agent
@@ -357,6 +387,8 @@ export type ToolDescriptionMode = "full" | "compact" | "custom";
 export interface SettingsAppliers {
   setMaxConcurrent: (n: number) => void;
   setMaxConcurrentForeground: (n: number) => void;
+  /** The process budget, from `loadBudgetPolicy`: global configuration only. */
+  setBudgetPolicy: (policy: BudgetPolicy) => void;
   setDefaultMaxTurns: (n: number) => void;
   setGraceTurns: (n: number) => void;
   setDefaultJoinMode: (mode: JoinMode) => void;
@@ -442,6 +474,20 @@ function sanitize(raw: unknown): SubagentsSettings {
   ) {
     out.maxConcurrentForeground = r.maxConcurrentForeground as number;
   }
+  if (
+    Number.isInteger(r.maxActiveSubagents) &&
+    (r.maxActiveSubagents as number) >= 0 &&
+    (r.maxActiveSubagents as number) <= MAX_CONCURRENT_CEILING
+  ) {
+    out.maxActiveSubagents = r.maxActiveSubagents as number;
+  }
+  if (
+    Number.isInteger(r.nestedSubagentReserve) &&
+    (r.nestedSubagentReserve as number) >= 0 &&
+    (r.nestedSubagentReserve as number) <= MAX_CONCURRENT_CEILING
+  ) {
+    out.nestedSubagentReserve = r.nestedSubagentReserve as number;
+  }
   if (
     Number.isInteger(r.defaultMaxTurns) &&
     (r.defaultMaxTurns as number) >= 0 &&
@@ -535,6 +581,24 @@ function sanitize(raw: unknown): SubagentsSettings {
   } else if (typeof r.fallbackSubagent === "string" && r.fallbackSubagent.trim()) {
     out.fallbackSubagent = r.fallbackSubagent.trim();
   }
+  if (r.modelTiers !== undefined) {
+    out.modelTiers = {};
+    if (r.modelTiers && typeof r.modelTiers === "object" && !Array.isArray(r.modelTiers)) {
+      for (const [tier, members] of Object.entries(r.modelTiers)) {
+        const binding = parseTierBinding(tier, members);
+        if (binding) out.modelTiers[tier] = binding.kind === "routed" ? [binding.profile] : binding.members;
+        else console.warn(`[pi-subagents] Ignoring invalid modelTiers entry "${tier}".`);
+      }
+    } else console.warn("[pi-subagents] Ignoring modelTiers: expected an object of tier -> model list.");
+  }
+  if (r.modelResolution && typeof r.modelResolution === "object" && !Array.isArray(r.modelResolution)) {
+    out.modelResolution = {};
+    for (const key of ["onUnmapped", "onUnavailable"] as const) {
+      const mode = (r.modelResolution as Record<string, unknown>)[key];
+      if (mode === "error" || mode === "inherit") out.modelResolution[key] = mode;
+      else if (mode !== undefined) console.warn(`[pi-subagents] Ignoring invalid modelResolution.${key}.`);
+    }
+  }
   if (r.modelAliases !== undefined) {
     const aliases = sanitizeModelAliases(r.modelAliases);
     if (aliases) out.modelAliases = aliases;
@@ -589,8 +653,8 @@ function sanitizeModelAliases(raw: unknown): Record<string, string[]> | undefine
   return aliases;
 }
 
-function globalPath(): string {
-  return join(getAgentDir(), "subagents.json");
+function globalPath(homeDir?: string): string {
+  return join(resolveAgentDir(homeDir), "subagents.json");
 }
 
 function projectPath(cwd: string): string {
@@ -614,19 +678,55 @@ function readSettingsFile(path: string): SubagentsSettings {
 }
 
 /** Load merged settings: global provides defaults, project overrides. */
-export function loadSettings(cwd: string = process.cwd()): SubagentsSettings {
+export function loadSettings(cwd: string = process.cwd(), homeDir?: string): SubagentsSettings {
   // Aliases pick the provider a subagent runs on, so they are machine
   // configuration: a cloned repo's project file must not redirect them.
-  const { modelAliases: projectModelAliases, agentModels: projectAgentModels, ...project } = readSettingsFile(projectPath(cwd));
+  const {
+    modelAliases: projectModelAliases,
+    modelTiers: projectModelTiers,
+    modelResolution: projectModelResolution,
+    agentModels: projectAgentModels,
+    maxActiveSubagents: projectMaxActive,
+    nestedSubagentReserve: projectReserve,
+    ...project
+  } = readSettingsFile(projectPath(cwd));
+  if (projectModelTiers !== undefined || projectModelResolution !== undefined) {
+    console.warn("[pi-subagents] Ignoring modelTiers/modelResolution in project .pi/subagents.json: model policy is read from trusted global configuration only.");
+  }
   if (projectModelAliases !== undefined) {
     console.warn("[pi-subagents] Ignoring modelAliases in project .pi/subagents.json: aliases are read from trusted global configuration only.");
   }
   if (projectAgentModels !== undefined) {
     console.warn("[pi-subagents] Ignoring agentModels in project .pi/subagents.json: per-agent models are read from trusted global configuration only.");
   }
-  const enterprise = readEnterpriseLocalManifest()?.subagents;
+  // The process budget spans every session in the process, so no one
+  // project's file may set it, least of all a cloned one lifting the cap.
+  if (projectMaxActive !== undefined || projectReserve !== undefined) {
+    console.warn("[pi-subagents] Ignoring maxActiveSubagents/nestedSubagentReserve in project .pi/subagents.json: the process-wide budget is read from global configuration only.");
+  }
+  return { ...trustedSettings(homeDir), ...project };
+}
+
+/** Global settings with the enterprise manifest over them: the layer a project file cannot touch. */
+function trustedSettings(homeDir?: string): SubagentsSettings {
+  const enterprise = readEnterpriseLocalManifest(homeDir)?.subagents;
   const enterpriseSettings = enterprise === undefined ? {} : sanitize(enterprise);
-  return { ...readSettingsFile(globalPath()), ...enterpriseSettings, ...project };
+  return { ...readSettingsFile(globalPath(homeDir)), ...enterpriseSettings };
+}
+
+/**
+ * The process budget's policy, from trusted configuration only -- including
+ * its depth, the GLOBAL `maxSubagentDepth`: a project file may still change
+ * how deep its own sessions nest, but not what the process-wide reserve
+ * covers. A missing key means its default, so removing the cap turns it off.
+ */
+export function loadBudgetPolicy(homeDir?: string): BudgetPolicy {
+  const trusted = trustedSettings(homeDir);
+  return {
+    maxActive: trusted.maxActiveSubagents ?? DEFAULT_BUDGET_POLICY.maxActive,
+    nestedReserve: trusted.nestedSubagentReserve ?? DEFAULT_BUDGET_POLICY.nestedReserve,
+    maxDepth: trusted.maxSubagentDepth ?? DEFAULT_BUDGET_POLICY.maxDepth,
+  };
 }
 
 /**
@@ -656,6 +756,7 @@ export function applySettings(s: SubagentsSettings, appliers: SettingsAppliers):
   if (typeof s.maxSubagentDepth === "number") appliers.setMaxSubagentDepth(s.maxSubagentDepth);
   if (typeof s.fallbackSubagent === "string") appliers.setFallbackSubagent(s.fallbackSubagent);
   // Module state: reset when a session omits it, or the previous activation's aliases leak.
+  setModelTiers(s.modelTiers, s.modelResolution);
   appliers.setModelAliases(s.modelAliases);
   appliers.setAgentModels(s.agentModels);
   if (s.defaultJoinMode) appliers.setDefaultJoinMode(s.defaultJoinMode);
@@ -703,9 +804,11 @@ export function applyAndEmitLoaded(
   appliers: SettingsAppliers,
   emit: SettingsEmit,
   cwd: string = process.cwd(),
+  homeDir?: string,
 ): SubagentsSettings {
-  const settings = loadSettings(cwd);
+  const settings = loadSettings(cwd, homeDir);
   applySettings(settings, appliers);
+  appliers.setBudgetPolicy(loadBudgetPolicy(homeDir));
   emit("subagents:settings_loaded", { settings });
   return settings;
 }

package/src/skill-loader.ts

@@ -25,7 +25,7 @@ import type { Dirent } from "node:fs";
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { resolveAgentDir } from "./home-paths.js";
 import { isSymlink, isUnsafeName, safeReadFile } from "./memory.js";
 
 export interface PreloadedSkill {
@@ -33,21 +33,22 @@ export interface PreloadedSkill {
   content: string;
 }
 
-export function preloadSkills(skillNames: string[], cwd: string): PreloadedSkill[] {
-  return skillNames.map((name) => ({ name, content: loadSkillContent(name, cwd) }));
+export function preloadSkills(skillNames: string[], cwd: string, homeDir = homedir()): PreloadedSkill[] {
+  return skillNames.map((name) => ({ name, content: loadSkillContent(name, cwd, homeDir) }));
 }
 
-function loadSkillContent(name: string, cwd: string): string {
+function loadSkillContent(name: string, cwd: string, homeDir: string): string {
   if (isUnsafeName(name)) {
     return `(Skill "${name}" skipped: name contains path traversal characters)`;
   }
   // `trusted`: user-owned root, symlinks followed. Project roots stay strict.
+  const agentDir = resolveAgentDir(homeDir);
   const roots = [
     { path: join(cwd, ".pi", "skills"), trusted: false }, // project — Pi standard
     { path: join(cwd, ".agents", "skills"), trusted: false }, // project — Agent Skills spec
-    { path: join(getAgentDir(), "skills"), trusted: true }, // user — Pi standard
-    { path: join(homedir(), ".agents", "skills"), trusted: true }, // user — Agent Skills spec
-    { path: join(homedir(), ".pi", "skills"), trusted: true }, // legacy global, pre-Pi
+    { path: join(agentDir, "skills"), trusted: true }, // user — Pi standard
+    { path: join(homeDir, ".agents", "skills"), trusted: true }, // user — Agent Skills spec
+    { path: join(homeDir, ".pi", "skills"), trusted: true }, // legacy global, pre-Pi
   ];
   for (const root of roots) {
     const content = findInRoot(root.path, name, root.trusted);

package/src/stale-ctx.ts

@@ -0,0 +1,16 @@
+/**
+ * stale-ctx.ts -- recognising pi's "extension ctx is stale" failure.
+ *
+ * pi invalidates an extension runner on reload and on session replacement
+ * (/new, /fork, /resume). Anything that still reaches the old runner or its
+ * `pi` throws this message (#145).
+ */
+
+/** Matched on the stable prefix of core's message. */
+export const STALE_CTX_RE = /extension ctx is stale after session replacement or reload/i;
+
+/** Whether `error` (an `Error` or a message string) is the stale-ctx failure. */
+export function isStaleCtxError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+  return STALE_CTX_RE.test(message);
+}

package/src/types.ts

@@ -4,6 +4,10 @@
 
 import type { ThinkingLevel } from "@earendil-works/pi-ai";
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { ModelFallback } from "./model-resolver.js";
+import type { ModelSelection } from "./model-selection.js";
+import type { TierDisclosure } from "./model-tiers.js";
+import type { BudgetLease } from "./process-budget.js";
 import type { LifetimeUsage } from "./usage.js";
 
 export type { ThinkingLevel };
@@ -146,6 +150,9 @@ export interface AgentTombstone {
   description: string;
   /** Always set — a record with no session file is never tombstoned. */
   sessionFile: string;
+  /** The evicted run's tier and fallback, handed back when `@handle` reopens it. */
+  modelTier?: TierDisclosure;
+  modelFallback?: ModelFallback;
   completedAt: number;
 }
 
@@ -204,6 +211,11 @@ export interface AgentRecord {
    * thing that moves it, together with the counters.
    */
   chargedPool?: Pool;
+  /**
+   * This run's process-wide budget lease (`process-budget.ts`), held from
+   * admission until the run settles. Spawns and resumes alike; cleared on release.
+   */
+  budgetLease?: BudgetLease;
   /**
    * Removes the listener that stops this run when its caller's signal aborts.
    * At most one is armed at a time — queueing arms one, starting replaces it.
@@ -264,6 +276,24 @@ export interface AgentRecord {
   isBackground?: boolean;
   /** Resolved spawn params, captured for UI display. Fixed at spawn time. */
   invocation?: AgentInvocation;
+  /**
+   * Set when a configured model did not resolve and the agent runs on the parent
+   * model. The single source for every disclosure surface; a resume reuses it
+   * as is, never recomputes it from the resuming call's config.
+   */
+  modelFallback?: ModelFallback;
+  /**
+   * This record's selection, retained across live resumes and physical relabelling.
+   * An evicted-session reopen selects anew; current fallback disclosure always
+   * comes from that selection.
+   */
+  modelSelection?: ModelSelection;
+  /** Actual run's tier provenance, preserved through eviction and replay. */
+  modelTier?: TierDisclosure;
+  /** Prior evicted run's outcome, never the continuation's selection or disclosure. */
+  previousModelTier?: TierDisclosure;
+  /** Prior evicted run's fallback, retained separately from the continuation's current disclosure. */
+  previousModelFallback?: ModelFallback;
   /** Nesting depth: top-level subagent = 1. */
   depth?: number;
   /**
@@ -344,6 +374,9 @@ export interface NotificationDetails {
   durationMs: number;
   outputFile?: string;
   error?: string;
+  /** The `Note:` line when the agent ran on the parent model because its configured one did not resolve. */
+  modelNote?: string;
+  modelTier?: TierDisclosure;
   resultPreview: string;
   /** Additional agents in a group notification. */
   others?: NotificationDetails[];

package/src/ui/agent-row.ts

@@ -14,6 +14,7 @@ import { pathToFileURL } from "node:url";
 import { type Component, hyperlink, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { type Clock, realClock, type TimerHandle } from "../clock.js";
 import { formatClock } from "../model-call.js";
+import { modelSelectionNote } from "../model-selection.js";
 import type { AgentRecord } from "../types.js";
 import { getLifetimeCost, getLifetimeTotal } from "../usage.js";
 import {
@@ -26,6 +27,7 @@ import {
   SPINNER,
   type Theme,
 } from "./agent-widget.js";
+import { fallbackFlag, withLeadingFlag } from "./fallback-flag.js";
 
 /** Lines of the result shown when expanded; the rest is one `get_subagent_result` away. */
 const EXPANDED_RESULT_LINES = 50;
@@ -89,6 +91,7 @@ export function agentRowSummary(
   live: AgentRowLive,
   theme: Theme,
   now: number = Date.now(),
+  width?: number,
 ): string {
   const record = details.agentId ? live.getRecord(details.agentId) : undefined;
   const activity = details.agentId ? live.getActivity(details.agentId) : undefined;
@@ -106,7 +109,10 @@ export function agentRowSummary(
   if (tokenText) parts.push(tokenText);
   if (cost) parts.push(cost);
   if (!finished && details.backgroundHint && elapsed >= 2000) parts.push("(ctrl+b to run in background)");
-  return `${icon} ${parts.map(p => fgPreservingNestedStyles(theme, "dim", p)).join(` ${theme.fg("dim", "·")} `)}`;
+  // Leading, ahead of the status text, which may carry a 300-char error.
+  const flag = fallbackFlag(theme, record?.modelFallback || record?.modelTier ? record : details);
+  const body = parts.map(p => fgPreservingNestedStyles(theme, "dim", p)).join(` ${theme.fg("dim", "·")} `);
+  return width === undefined ? `${icon} ${flag ? `${flag} ` : ""}${body}` : withLeadingFlag(`${icon} `, flag, body, width);
 }
 
 /**
@@ -116,7 +122,9 @@ export function agentRowSummary(
  */
 function tagsLine(details: AgentDetails, theme: Theme): string | undefined {
   const parts = [...(details.modelName ? [details.modelName] : []), ...(details.tags ?? [])];
-  return parts.length > 0 ? theme.fg("dim", `↳ ${parts.join(" · ")}`) : undefined;
+  const flag = fallbackFlag(theme, details);
+  if (parts.length === 0 && !flag) return undefined;
+  return `${theme.fg("dim", "↳")} ${flag ? `${flag} ` : ""}${theme.fg("dim", parts.join(" · "))}`;
 }
 
 /** The transcript as an OSC 8 hyperlink, so a click opens it. */
@@ -189,12 +197,14 @@ export class AgentResultView implements Component {
   ) {}
 
   render(width: number): string[] {
-    const lines = [truncateToWidth(agentRowSummary(this.details, this.live, this.theme, this.clock.now()), width)];
+    const lines = [agentRowSummary(this.details, this.live, this.theme, this.clock.now(), width)];
     if (!this.expanded) return lines;
 
     const record = this.details.agentId ? this.live.getRecord(this.details.agentId) : undefined;
     const tags = tagsLine(this.details, this.theme);
     if (tags) lines.push(truncateToWidth(tags, width));
+    const note = modelSelectionNote(record) || this.details.modelNote;
+    if (note) lines.push(...wrapTextWithAnsi(this.theme.fg("warning", note), width));
     const transcript = record?.outputFile ?? this.details.outputFile;
     if (transcript) lines.push(truncateToWidth(transcriptLink(transcript, this.theme), width));
 

package/src/ui/agent-widget.ts

@@ -11,8 +11,11 @@ import { type AgentManager, isTopLevelAgent } from "../agent-manager.js";
 import { getConfig } from "../agent-types.js";
 import { type Clock, realClock, type TimerHandle } from "../clock.js";
 import { describeModelCall, type ModelCallState } from "../model-call.js";
+import type { ModelFallback } from "../model-resolver.js";
+import type { TierDisclosure } from "../model-tiers.js";
 import type { AgentInvocation, SubagentType, WidgetMode } from "../types.js";
 import { getLifetimeCost, getLifetimeTotal, getSessionContextPercent, type LifetimeUsage, type SessionLike } from "../usage.js";
+import { fallbackFlag } from "./fallback-flag.js";
 
 // ---- Constants ----
 
@@ -83,6 +86,11 @@ export interface AgentDetails {
   backgroundHint?: boolean;
   /** Short label for the model the run used, e.g. "haiku 4.5". */
   modelName?: string;
+  /** Set when a configured model did not resolve and the run fell back to the parent model. */
+  modelNote?: string;
+  /** The structured form of {@link modelNote}, for the one-line label. */
+  modelFallback?: ModelFallback;
+  modelTier?: TierDisclosure;
   /** Notable config tags (e.g. ["thinking: high", "isolated"]). */
   tags?: string[];
   /** Current turn count. */
@@ -389,7 +397,7 @@ export class AgentWidget {
   }
 
   /** Render a finished agent line. */
-  private renderFinishedLine(a: { id: string; type: SubagentType; status: string; description: string; toolUses: number; startedAt: number; completedAt?: number; error?: string; lifetimeUsage?: LifetimeUsage }, theme: Theme): string {
+  private renderFinishedLine(a: { id: string; type: SubagentType; status: string; description: string; toolUses: number; startedAt: number; completedAt?: number; error?: string; lifetimeUsage?: LifetimeUsage; modelFallback?: ModelFallback; modelTier?: TierDisclosure }, theme: Theme): string {
     const modeLabel = getPromptModeLabel(a.type);
     const duration = formatMs((a.completedAt ?? this.clock.now()) - a.startedAt);
 
@@ -418,6 +426,7 @@ export class AgentWidget {
     const activity = this.agentActivity.get(a.id);
     if (activity) parts.push(formatTurns(activity.turnCount, activity.maxTurns));
     if (a.toolUses > 0) parts.push(`${a.toolUses} tool use${a.toolUses === 1 ? "" : "s"}`);
+    // Not gated by `showModel`: a substituted model is never a cosmetic detail.
     // From the record, not the activity tracker: that entry is deleted the
     // moment an agent finishes, and "what did it cost" is a question asked
     // about finished agents.
@@ -426,7 +435,8 @@ export class AgentWidget {
     parts.push(duration);
 
     const modeTag = modeLabel ? ` ${theme.fg("dim", `(${modeLabel})`)}` : "";
-    return `${icon} ${renderAgentName(a.type, theme, { fallbackColor: "dim" })}${modeTag}  ${theme.fg("dim", a.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", parts.join(" · "))}${statusText}`;
+    const flag = fallbackFlag(theme, a) ? `${fallbackFlag(theme, a)} ` : "";
+    return `${icon} ${flag}${renderAgentName(a.type, theme, { fallbackColor: "dim" })}${modeTag}  ${theme.fg("dim", a.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", parts.join(" · "))}${statusText}`;
   }
 
   /**
@@ -466,6 +476,7 @@ export class AgentWidget {
     for (const a of running) {
       const modeLabel = getPromptModeLabel(a.type);
       const modeTag = modeLabel ? ` ${theme.fg("dim", `(${modeLabel})`)}` : "";
+    const flag = fallbackFlag(theme, a) ? `${fallbackFlag(theme, a)} ` : "";
       const elapsed = formatMs(this.clock.now() - a.startedAt);
 
       const bg = this.agentActivity.get(a.id);
@@ -489,7 +500,7 @@ export class AgentWidget {
         const thinkingTag = tags.find(tag => tag.startsWith("thinking: "));
         if (thinkingTag) parts.push(thinkingTag);
       }
-      if (bg) parts.push(formatTurns(bg.turnCount, bg.maxTurns));
+        if (bg) parts.push(formatTurns(bg.turnCount, bg.maxTurns));
       if (toolUses > 0) parts.push(`${toolUses} tool use${toolUses === 1 ? "" : "s"}`);
       if (tokenText) parts.push(tokenText);
       if (costText) parts.push(costText);
@@ -499,7 +510,7 @@ export class AgentWidget {
       const activity = bg ? describeActivity(bg.activeTools, bg.responseText, bg.modelCall, this.clock.now()) : "thinking…";
 
       runningLines.push([
-        truncate(theme.fg("dim", "├─") + ` ${theme.fg("accent", frame)} ${renderAgentName(a.type, theme, { bold: true })}${modeTag}  ${theme.fg("muted", a.description)} ${theme.fg("dim", "·")} ${fgPreservingNestedStyles(theme, "dim", statsText)}`),
+        truncate(theme.fg("dim", "├─") + ` ${theme.fg("accent", frame)} ${flag}${renderAgentName(a.type, theme, { bold: true })}${modeTag}  ${theme.fg("muted", a.description)} ${theme.fg("dim", "·")} ${fgPreservingNestedStyles(theme, "dim", statsText)}`),
         truncate(theme.fg("dim", "│  ") + theme.fg("dim", `  ⎿  ${activity}`)),
       ]);
     }