@nredd/pi-subagents 0.22.0-nredd.7 → 0.22.0-nredd.9

package/src/skill-loader.ts

@@ -1,137 +1,288 @@
-/**
- * skill-loader.ts — Preload named skills.
- *
- * Roots, in precedence order:
- *   - <cwd>/.pi/skills           (project, Pi's standard)
- *   - <cwd>/.agents/skills       (project, cross-tool Agent Skills spec — https://agentskills.io)
- *   - getAgentDir()/skills       (user, default ~/.pi/agent/skills — Pi's standard)
- *   - ~/.agents/skills           (user, cross-tool Agent Skills spec)
- *   - ~/.pi/skills               (legacy global, pre-Pi)
- *
- * Layout per root:
- *   - <root>/<name>.md            (flat file at the top level)
- *   - <root>/.../<name>/SKILL.md  (directory skill, may be nested — Pi's standard)
- *
- * Recursion skips dotfile entries and node_modules. A directory that itself contains
- * SKILL.md is a skill — we don't descend into it (Pi: skills don't nest).
- *
- * Project roots reject symlinks at every layer: a cloned repository must not be able to
- * point a skill at files outside it (deviation from Pi). User roots belong to the user and
- * follow symlinks like Pi does — that is how skill installers and dotfile managers link
- * skills in — skipping broken links and directory cycles.
- */
+/** Resolve named preloaded skills through Pi's configured resource discovery. */
 
-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 { type Dirent, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, symlinkSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { loadSkills, type ResolvedResource, SettingsManager, type SettingsManager as SettingsManagerType } from "@earendil-works/pi-coding-agent";
 import { isSymlink, isUnsafeName, safeReadFile } from "./memory.js";
+import { createHomePackageManager } from "./resource-loader.js";
+
+/** Discovery is inspect-only: missing sources are never installed or activated. */
+const skipMissingSource = async (): Promise<"skip"> => "skip";
 
 export interface PreloadedSkill {
   name: string;
   content: string;
 }
 
-export function preloadSkills(skillNames: string[], cwd: string): PreloadedSkill[] {
-  return skillNames.map((name) => ({ name, content: loadSkillContent(name, cwd) }));
+export interface SkillPreloadOptions {
+  agentDir: string;
+  settingsManager: SettingsManagerType;
+  homeDir?: string;
+}
+
+/**
+ * Load named skills through Pi, retaining the preloader's legacy user roots.
+ *
+ * Pi owns configured package discovery, parsing, trust, and missing-package
+ * handling. A second untrusted manager exposes the user/package candidates
+ * which Pi's realpath collapse can hide behind a rejected project symlink.
+ */
+export async function preloadSkills(
+  skillNames: string[],
+  cwd: string,
+  options: SkillPreloadOptions,
+): Promise<PreloadedSkill[]> {
+  if (skillNames.length === 0) return [];
+  const primary = createHomePackageManager({ cwd, agentDir: options.agentDir, settingsManager: options.settingsManager }, options.homeDir);
+  const primaryResources = await primary.resolve(skipMissingSource);
+  const fallbackSettings = SettingsManager.create(cwd, options.agentDir, { projectTrusted: false });
+  const fallback = createHomePackageManager({ cwd, agentDir: options.agentDir, settingsManager: fallbackSettings }, options.homeDir);
+  const fallbackResources = await fallback.resolve(skipMissingSource);
+
+  const rejectedProjectPaths = new Set(primaryResources.skills
+    .filter(resource => isTier(resource, "project") && isSymlinkedProjectSkill(resource, cwd))
+    .map(resource => canonicalPath(resource.path)));
+  // A path that cannot be canonicalized never matches, so it is never restored.
+  const isBehindRejectedAlias = (resource: ResolvedResource): boolean => {
+    const canonical = canonicalPath(resource.path);
+    return canonical !== undefined && rejectedProjectPaths.has(canonical);
+  };
+  // Package candidates collapsed behind a rejected project alias, resolved with
+  // Pi's own project package filters applied.
+  const aliasFreeSkills = rejectedProjectPaths.size === 0 ? [] : await resolveAliasFreePackageSkills(cwd, options);
+  const recoveredPackages = aliasFreeSkills.filter(isBehindRejectedAlias);
+
+  // Resolve native disabled paths through Pi's parser, preserving every filter form it supports.
+  const disabledNames = new Set(loadTier(
+    [...primaryResources.skills, ...fallbackResources.skills, ...recoveredPackages].filter(resource => !resource.enabled),
+    cwd,
+    options.agentDir,
+  ).map(skill => skill.name));
+  const project = discoveredSkills(
+    primaryResources.skills.filter(resource => resource.enabled && isTier(resource, "project") && !isSymlinkedProjectSkill(resource, cwd)),
+    cwd,
+    options.agentDir,
+  );
+  const user = discoveredSkills(
+    [
+      ...primaryResources.skills,
+      // Only restore a user candidate Pi collapsed behind a rejected project alias.
+      // Other fallback user resources could bypass Pi's project filters.
+      ...fallbackResources.skills.filter(isBehindRejectedAlias),
+    ].filter(resource => resource.enabled && isTier(resource, "user") && !isAmbientUserAgentsSkill(resource, options.homeDir)),
+    cwd,
+    options.agentDir,
+  );
+  const packages = discoveredSkills(
+    [
+      ...primaryResources.skills,
+      // Only restore a package candidate Pi collapsed behind a rejected project alias.
+      ...recoveredPackages,
+    ].filter(resource => resource.enabled && isTier(resource, "package") && !isAmbientUserAgentsSkill(resource, options.homeDir)),
+    cwd,
+    options.agentDir,
+  );
+
+  // Historical user roots, including their raw top-level `<name>.md` lookup.
+  const home = resolve(options.homeDir ?? homedir());
+  const legacyUserRoots = [join(options.agentDir, "skills"), join(home, ".agents", "skills"), join(home, ".pi", "skills")];
+  return skillNames.map(name => {
+    const native = project.get(name) ?? user.get(name) ?? packages.get(name);
+    const content = native
+      ?? (disabledNames.has(name)
+        ? undefined
+        : (options.settingsManager.isProjectTrusted() ? findInRoots(projectSkillRoots(cwd).map(root => join(root, "skills")), name, false) : undefined)
+          ?? findInRoots(legacyUserRoots, name, true));
+    return { name, content: content ?? `(Skill "${name}" not found in Pi's configured skill resources)` };
+  });
+}
+
+/** Precedence tier of a resolved skill: top-level project or user resources, or package resources. */
+function isTier(resource: ResolvedResource, tier: "project" | "user" | "package"): boolean {
+  return tier === "package" ? resource.metadata.origin === "package" : resource.metadata.origin === "top-level" && resource.metadata.scope === tier;
 }
 
-function loadSkillContent(name: string, cwd: string): string {
-  if (isUnsafeName(name)) {
-    return `(Skill "${name}" skipped: name contains path traversal characters)`;
+/** Absolutize an existing local project package source, which Pi resolves against `<cwd>/.pi`. */
+function absolutizeProjectSource(source: string, cwd: string): string {
+  const local = resolve(cwd, ".pi", source);
+  return !source.startsWith("npm:") && existsSync(local) ? local : source;
+}
+
+/**
+ * Resolve package skills as Pi would, minus the project's top-level skill dirs.
+ *
+ * Pi collapses resources by realpath, so a rejected project symlink can hide a
+ * package skill together with the project package filter that applies to it.
+ * Resolving from an empty scratch cwd, with the real project settings and
+ * npm/git install roots carried over, keeps Pi as the owner of those filters.
+ */
+async function resolveAliasFreePackageSkills(cwd: string, options: SkillPreloadOptions): Promise<ResolvedResource[]> {
+  const scratch = mkdtempSync(join(tmpdir(), "skill-preload-"));
+  try {
+    for (const dir of ["npm", "git"]) {
+      const real = join(cwd, ".pi", dir);
+      if (!existsSync(real)) continue;
+      mkdirSync(join(scratch, ".pi"), { recursive: true });
+      symlinkSync(real, join(scratch, ".pi", dir), "dir");
+    }
+    const project = options.settingsManager.getProjectSettings();
+    const settings = {
+      global: options.settingsManager.getGlobalSettings(),
+      project: { ...project, packages: project.packages?.map(pkg => typeof pkg === "string"
+        ? absolutizeProjectSource(pkg, cwd)
+        : { ...pkg, source: absolutizeProjectSource(pkg.source, cwd) }) },
+    };
+    // Pi's public storage seam replaces the scratch cwd's settings with the real
+    // ones. `normalizeHomeResourceSettings` cannot: it only rewrites a manager's
+    // own settings, and `createHomePackageManager` still applies it on top.
+    const settingsManager = SettingsManager.fromStorage(
+      { withLock: (scope, read) => void read(JSON.stringify(settings[scope])) },
+      { projectTrusted: options.settingsManager.isProjectTrusted() },
+    );
+    const manager = createHomePackageManager({ cwd: scratch, agentDir: options.agentDir, settingsManager }, options.homeDir);
+    return (await manager.resolve(skipMissingSource)).skills.filter(resource => resource.metadata.origin === "package");
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
   }
-  // `trusted`: user-owned root, symlinks followed. Project roots stay strict.
-  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
-  ];
+}
+
+/** Parse resolved skill paths with Pi's own loader and validation. */
+function loadTier(resources: ResolvedResource[], cwd: string, agentDir: string): ReturnType<typeof loadSkills>["skills"] {
+  return loadSkills({ cwd, agentDir, skillPaths: resources.map(resource => resource.path), includeDefaults: false }).skills;
+}
+
+/** Load Pi-valid skills from a precedence tier, retaining the first declared name. */
+function discoveredSkills(resources: ResolvedResource[], cwd: string, agentDir: string): Map<string, string> {
+  return new Map(loadTier(resources, cwd, agentDir).map(skill => [skill.name, readFileSync(skill.filePath, "utf-8").trim()]));
+}
+
+/** Find a named legacy skill under roots in order without broadening Pi discovery. */
+function findInRoots(roots: string[], name: string, trusted: boolean): string | undefined {
+  if (isUnsafeName(name)) return undefined;
   for (const root of roots) {
-    const content = findInRoot(root.path, name, root.trusted);
+    const content = findInRoot(root, name, trusted);
     if (content !== undefined) return content;
   }
-  return `(Skill "${name}" not found in .pi/skills/, .agents/skills/, or global skill locations)`;
+  return undefined;
 }
 
+/** Match the former preloader's flat-file and recursive Agent Skills lookup. */
 function findInRoot(root: string, name: string, trusted: boolean): string | undefined {
-  // Reject a project root that is, or sits in, a link: `<cwd>/.pi -> /elsewhere` counts too.
-  if (!trusted && (isSymlink(root) || isSymlink(dirname(root)))) return undefined;
+  if (!trusted && isPathThroughSymlink(dirname(root), root)) return undefined;
   const flat = readSkillFile(join(root, `${name}.md`), trusted)?.trim();
   if (flat !== undefined) return flat;
-  return findSkillDirectory(root, name, trusted);
-}
-
-/** A regular file's text; `trusted` also follows a symlink to one, else symlinks are refused. */
-function readSkillFile(path: string, trusted: boolean): string | undefined {
-  if (!trusted) return safeReadFile(path);
-  try {
-    return statSync(path).isFile() ? readFileSync(path, "utf-8") : undefined;
-  } catch {
-    return undefined; // missing or broken link
-  }
-}
-
-/** BFS under `root` for a directory named `name` containing `SKILL.md`. Pi-conforming filters. */
-function findSkillDirectory(root: string, name: string, trusted: boolean): string | undefined {
   if (!existsSync(root)) return undefined;
-  const queue: string[] = [root];
-  // Canonical paths already queued: a followed link back to an ancestor cannot loop.
-  const seen = new Set<string>();
 
-  while (queue.length > 0) {
-    const current = queue.shift();
-    if (current === undefined) continue;
+  const queue = [root];
+  const seen = new Set<string>();
+  // `root` passed the symlink check above and every queued directory passed it before it was
+  // pushed, so `current` needs no second check. Iteration visits entries pushed meanwhile, in order.
+  for (const current of queue) {
     if (trusted) {
-      let real: string;
-      try {
-        real = realpathSync(current);
-      } catch {
-        continue;
-      }
-      if (seen.has(real)) continue;
-      seen.add(real);
+      const canonical = canonicalPath(current);
+      // A directory raced away since it was queued has nothing left to read.
+      if (canonical === undefined || seen.has(canonical)) continue;
+      seen.add(canonical);
     }
-
     let entries: Dirent<string>[];
     try {
-      entries = readdirSync(current, { withFileTypes: true });
+      entries = readdirSync(current, { withFileTypes: true }).sort((left, right) => Number(left.name > right.name) - Number(left.name < right.name));
     } catch {
       continue;
     }
-
-    // Deterministic byte-order traversal — locale-independent.
-    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
-
     for (const entry of entries) {
       if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
       const path = join(current, entry.name);
-      // Dirent uses lstat semantics, so a symlinked dir is not `isDirectory()`: refused unless trusted.
-      if (!entry.isDirectory() && !(trusted && entry.isSymbolicLink() && isDirectoryTarget(path))) continue;
-
-      const skillMd = join(path, "SKILL.md");
-      const isSkillDir = existsSync(skillMd);
-
-      if (isSkillDir) {
-        if (entry.name === name) {
-          const content = readSkillFile(skillMd, trusted)?.trim();
-          if (content !== undefined) return content;
-        }
-        continue; // Pi rule: skills don't nest — don't descend into a skill dir
+      if (!trusted && isPathThroughSymlink(dirname(root), path)) continue;
+      const isDirectory = entry.isDirectory() || (trusted && entry.isSymbolicLink() && isDirectoryTarget(path));
+      if (!isDirectory) continue;
+      const skillFile = join(path, "SKILL.md");
+      if (existsSync(skillFile)) {
+        const content = entry.name === name ? readSkillFile(skillFile, trusted)?.trim() : undefined;
+        if (content !== undefined) return content;
+        continue;
       }
-
       queue.push(path);
     }
   }
   return undefined;
 }
 
+function readSkillFile(path: string, trusted: boolean): string | undefined {
+  if (!trusted) return safeReadFile(path);
+  try {
+    return statSync(path).isFile() ? readFileSync(path, "utf-8") : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function isDirectoryTarget(path: string): boolean {
   try {
     return statSync(path).isDirectory();
   } catch {
-    return false; // broken link
+    return false;
+  }
+}
+
+/**
+ * Match Pi's realpath identity without importing its private path utility.
+ *
+ * Unlike Pi, an uncanonicalizable path (raced away, EACCES) yields undefined
+ * rather than the raw path, so it can never match a rejected alias. That is
+ * also why `realOrSelf` in `package-resources.ts` is not reused: it falls back
+ * to the realpath of the nearest existing parent.
+ */
+function canonicalPath(path: string): string | undefined {
+  try {
+    return realpathSync(path);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Exclude Pi's ambient user root when a caller supplies a distinct injected home. */
+export function isAmbientUserAgentsSkill(resource: ResolvedResource, homeDir?: string, runtimeHome = homedir()): boolean {
+  if (homeDir === undefined || resource.metadata.scope !== "user" || resource.metadata.source !== "auto") return false;
+  const injectedRoot = join(resolve(homeDir), ".agents", "skills");
+  return !isPathWithin(injectedRoot, resource.path) && isPathWithin(join(runtimeHome, ".agents", "skills"), resource.path);
+}
+
+/** Reject project symlinks before accepting their resources or resolving collisions. Callers pass project-tier resources only. */
+function isSymlinkedProjectSkill(resource: ResolvedResource, cwd: string): boolean {
+  return projectSkillRoots(cwd).some(root => isPathThroughSymlink(root, resource.path));
+}
+
+/** Match Pi's project skill roots while checking their parent directories too. */
+function projectSkillRoots(cwd: string): string[] {
+  const roots = [join(cwd, ".pi")];
+  let directory = resolve(cwd);
+  while (true) {
+    roots.push(join(directory, ".agents"));
+    if (existsSync(join(directory, ".git"))) break;
+    const parent = dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+  return roots;
+}
+
+/** Textual containment. Unlike `isInside` in `package-resources.ts`, it must not canonicalize: that would erase the symlinks callers look for. */
+function isPathWithin(root: string, path: string): boolean {
+  const relativePath = relative(resolve(root), resolve(path));
+  return relativePath === "" || (!relativePath.startsWith(`..${sep}`) && relativePath !== ".." && !isAbsolute(relativePath));
+}
+
+function isPathThroughSymlink(root: string, path: string): boolean {
+  const absoluteRoot = resolve(root);
+  if (!isPathWithin(absoluteRoot, path)) return false;
+  const relativePath = relative(absoluteRoot, resolve(path));
+  let current = absoluteRoot;
+  if (isSymlink(current)) return true;
+  for (const segment of relativePath.split(sep)) {
+    current = join(current, segment);
+    if (isSymlink(current)) return true;
   }
+  return false;
 }

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/status-note.ts

@@ -10,6 +10,9 @@
 
 import type { AgentRecord } from "./types.js";
 
+/** Who stopped a `stopped` record: the spawning agent, or (unset) a human. */
+type StoppedBy = AgentRecord["stoppedBy"];
+
 /**
  * Explicit parenthetical note for a non-normal terminal outcome, so the parent
  * agent can't mistake partial output for a completed result. Empty string for a
@@ -17,12 +20,16 @@ import type { AgentRecord } from "./types.js";
  *
  * `stopped` (a human aborted it) is deliberately distinct from `aborted` (the
  * turn limit was hit) — the parent should treat human intervention differently
- * from a budget cutoff.
+ * from a budget cutoff. A stop the parent itself made with `stop_subagent`
+ * (`stoppedBy: "parent"`) is stated plainly instead: shouting a human
+ * intervention that never happened would misreport its own decision back to it.
  */
-export function getStatusNote(status: string): string {
+export function getStatusNote(status: string, stoppedBy?: StoppedBy): string {
   switch (status) {
     case "stopped":
-      return " (STOPPED BY THE USER before completion — output is partial; the task was NOT finished)";
+      return stoppedBy === "parent"
+        ? " (stopped by the parent with stop_subagent before completion — output is partial; the task was NOT finished)"
+        : " (STOPPED BY THE USER before completion — output is partial; the task was NOT finished)";
     case "aborted":
       return " (aborted — hit the turn limit before completion; output may be incomplete)";
     case "steered":
@@ -66,10 +73,12 @@ export function getStatusNote(status: string): string {
  * behavior) and adding an instruction (which can) are not equally safe bets.
  * Don't add either back without a way to measure it.
  */
-export function getForegroundOutcomeNote(status: string): string {
+export function getForegroundOutcomeNote(status: string, stoppedBy?: StoppedBy): string {
   switch (status) {
     case "stopped":
-      return " (STOPPED BY THE USER — everything the agent produced is above; the task is unfinished)";
+      return stoppedBy === "parent"
+        ? " (stopped by the parent with stop_subagent — everything the agent produced is above; the task is unfinished)"
+        : " (STOPPED BY THE USER — everything the agent produced is above; the task is unfinished)";
     case "aborted":
       return " (aborted at the turn limit — everything the agent produced is above; the task is unfinished)";
     case "steered":
@@ -79,6 +88,20 @@ export function getForegroundOutcomeNote(status: string): string {
   }
 }
 
+/**
+ * For an `error` run whose session survived, the hint that resuming it
+ * continues the work, naming the agent; "" otherwise. A provider or auth
+ * failure (e.g. a credential helper that failed transiently, #456) ends the
+ * turn but keeps the whole transcript, so the parent should resume the agent
+ * rather than re-spawn it and repay its context. A run that never got a
+ * session has nothing to resume.
+ */
+export function resumeHint(record: Pick<AgentRecord, "id" | "status" | "session">): string {
+  return record.status === "error" && record.session
+    ? `transcript intact; resume agent ${record.id} to continue`
+    : "";
+}
+
 /**
  * Salvaged partial output of a failed run, as a labeled suffix for the error
  * surfaces (or "" if the run produced nothing). `record.result` is bounded to

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 { PlanGate, PlanToolPolicy } from "./plan-mode-children.js";
 import type { BudgetLease } from "./process-budget.js";
 import type { LifetimeUsage } from "./usage.js";
 
@@ -147,6 +151,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;
 }
 
@@ -178,8 +185,21 @@ export interface AgentRecord {
    * by its type and `@explore` never comes to mean "start another one".
    */
   alias?: string;
+  /**
+   * `handleBase(name)` before collision numbering: `auth-audit` for an alias of
+   * `auth-audit-2`. Announced as `nameBase` so a listener matching the spawner's
+   * `name` finds a retry rather than the failed first try still holding the name.
+   */
+  nameBase?: string;
   description: string;
   status: "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
+  /**
+   * Set when the agent that spawned this one stopped it with `stop_subagent`
+   * (#443). Unset on a `stopped` record means a human stopped it (a viewer's
+   * `x`, the stop-all chord, `/agents`, or the RPC), which the status notes
+   * word differently.
+   */
+  stoppedBy?: "parent";
   result?: string;
   error?: string;
   toolUses: number;
@@ -227,14 +247,34 @@ export interface AgentRecord {
   joinMode?: JoinMode;
   /** Set when result was already consumed via get_subagent_result — suppresses completion notification. */
   resultConsumed?: boolean;
+  /**
+   * Set when the completion notice was sent to the parent, whole or clipped, failures
+   * included. Unlike `resultConsumed` it does not mean FleetView acknowledged it; the
+   * reap notice only asks "did the parent ever see this?".
+   */
+  noticeDelivered?: boolean;
+  /**
+   * The latest run actually began executing (the runner was started on a live signal).
+   * Positive evidence the reap notice requires: a record that was stopped in the queue,
+   * refused, or failed before the runner started never ran, so evicting it loses nothing.
+   * Reset on every resume.
+   */
+  ranThisRun?: boolean;
   /** When `resultConsumed` was set; the GC keeps a consumed record for a short window from here. */
   consumedAt?: number;
   /** Steering messages queued before the session was ready. */
   pendingSteers?: string[];
+  /**
+   * The Plan restriction its runs are under (#437): set at spawn, re-decided at
+   * each resume, read by the child's tool hooks on every call.
+   */
+  planGate?: PlanGate;
+  /** Asks the parent's pi-plan-mode again, for a resume. */
+  planQuery?: () => PlanToolPolicy | undefined;
   /** Worktree info if the agent is running in an isolated worktree. */
   worktree?: { path: string; branch: string; baseSha: string; repoRoot: string; workPath: string };
   /** Worktree cleanup result after agent completion. */
-  worktreeResult?: { hasChanges: boolean; branch?: string };
+  worktreeResult?: { hasChanges: boolean; branch?: string; path?: string; error?: string };
   /** The tool_use_id from the original Agent tool call. */
   toolCallId?: string;
   /** Path to the streaming output transcript file. */
@@ -270,8 +310,38 @@ 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;
+  /**
+   * The evicted id this record reopened (#330), announced as `previousId` on its
+   * lifecycle events so a listener keyed by the old id follows the conversation.
+   */
+  previousId?: string;
+  /**
+   * Order of this record's spawn among the manager's spawns and settles, set once at
+   * creation (before any queueing) and announced as `spawnSeq` on lifecycle events.
+   */
+  spawnSeq?: number;
+  /** Order of this record's latest settle on the same counter, announced as `settleSeq`. */
+  settleSeq?: number;
   /** Nesting depth: top-level subagent = 1. */
-  depth?: number;
+  depth: number;
   /**
    * The validated `StructuredOutput` payload, as canonical JSON.
    *
@@ -330,6 +400,8 @@ export interface AgentInvocation {
   inheritContext?: boolean;
   runInBackground?: boolean;
   isolation?: IsolationMode;
+  /** The run is under Plan mode's policy because its parent was planning (#437). */
+  planMode?: boolean;
 }
 
 /** Details attached to custom notification messages for visual rendering. */
@@ -350,6 +422,11 @@ export interface NotificationDetails {
   durationMs: number;
   outputFile?: string;
   error?: string;
+  /** Set for a failed agent whose transcript survived: `resume agent <id> to continue` (status-note.ts `resumeHint`). */
+  resumeHint?: 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-mention.ts

@@ -87,9 +87,12 @@ export function mentionRoster(
   // only — both names resolve, but showing two rows for one agent reads as two
   // agents. The type handle stays addressable whether or not it is listed.
   for (const record of records) {
-    const handle = record.alias ?? record.handle!;
+    // The filter above kept only records with a handle, and `handleBase` never
+    // derives an empty one.
+    const own = record.handle!;
+    const handle = record.alias ?? own;
     taken.add(handle.toLowerCase());
-    if (record.handle) taken.add(record.handle.toLowerCase());
+    taken.add(own.toLowerCase());
     targets.push({ kind: "record", handle, record, typeLabel: displayNameOf(record.type) });
   }