pi-better-subagents 0.7.0 → 0.8.0

package/README.md

@@ -43,6 +43,13 @@ uses `agents_catalog` to discover current role descriptions and delegates every
 nontrivial role-owned task, while the foreground coordinates, integrates, and
 verifies. See [usage notes](docs/usage.md#delegation-mode).
 
+`agents_catalog` shows each role's and named agent's default model and effort,
+such as `default openai/gpt-6-sol@high`. To launch on that default, omit
+`model` and `thinking` on a role or agent spawn; name one only for a stated
+reason. When a launch's model or effort differs from the default, its launch
+line says so, for example
+`model openai/gpt-6-astra@high (role default openai/gpt-6-sol@high)`.
+
 ## When To Use
 
 Use this package for independent coding, review, research, or verification work that can finish later. Do not use it for steps that need immediate foreground interaction or user clarification.

package/agent-inspection.ts

@@ -80,6 +80,23 @@ export interface OperationField {
     inherited: boolean;
 }
 
+export interface DefinitionDefaults {
+    model: string | null;
+    effort: string | null;
+    /** Compact `model@effort` form, as shown in the catalog list and launch notes. */
+    label: string;
+}
+
+/** `model@effort`, `model`, or `effort <level>` when only an effort is set. Undefined when neither is set. */
+export function formatModelEffort(model: string | null | undefined, effort: string | null | undefined): string | undefined {
+    const m = typeof model === "string" && model.trim() !== "" ? model : undefined;
+    const e = typeof effort === "string" && effort.trim() !== "" ? effort : undefined;
+    if (m && e) return `${m}@${e}`;
+    if (m) return m;
+    if (e) return `effort ${e}`;
+    return undefined;
+}
+
 export interface OperationCapabilities {
     grantedByCatalog: false;
     sameAsLegacySpawn: true;
@@ -113,6 +130,8 @@ export interface OperationView {
     instructionMode?: string;
     instructions?: string;
     fields?: { model: OperationField; effort: OperationField; tier: OperationField };
+    /** The definition's own default model and effort (role default, or the agent's override or inherited value). Null when neither is set. */
+    defaults: DefinitionDefaults | null;
     requestedModel: string | null;
     requestedEffort: string | null;
     actualModel: string | null;
@@ -311,6 +330,7 @@ export function presentCatalogEntry(snapshot: CatalogSnapshot, id: string, enric
         instructionMode: inspection.instructionMode,
         instructions: inspection.instructions,
         fields,
+        defaults: definitionDefaults(fields),
         requestedModel: enrichment?.requestedModel ?? fields?.model.value ?? null,
         requestedEffort: enrichment?.requestedEffort ?? (fields?.effort.value ?? null),
         actualModel: enrichment?.actualModel ?? null,
@@ -350,6 +370,7 @@ export function renderOperationView(view: OperationView): string {
         `definitionValid=${yesNo(view.definitionValid)}`,
         `catalogLaunchable=${yesNo(view.catalogLaunchable)}`,
         `launchable=${view.launchable === null ? "unknown" : yesNo(view.launchable)}`,
+        ...(view.defaults ? [`default ${view.defaults.label}`] : []),
     ].join(" ");
     const lines = [
         header,
@@ -397,6 +418,13 @@ export function renderOperationView(view: OperationView): string {
     return lines.join("\n");
 }
 
+function definitionDefaults(fields: OperationView["fields"]): DefinitionDefaults | null {
+    const model = fields?.model.value ?? null;
+    const effort = fields?.effort.value ?? null;
+    const label = formatModelEffort(model, effort);
+    return label ? { model, effort, label } : null;
+}
+
 function field(value: { value: string | null; source: OperationField["source"]; explicit: boolean }): OperationField {
     return {
         value: value.value,

package/agents-catalog-tool.ts

@@ -37,7 +37,7 @@ export function agentsCatalogTool(Type: TypeModule, deps: DiscoveryDeps = {}) {
     return {
         name: "agents_catalog" as const,
         label: "Agents catalog",
-        description: "List or inspect role and named-agent definitions, including inheritance, diagnostics, restrictions, and whether launchability is actually known. This tool does not create, import, or edit definitions.",
+        description: "List or inspect role and named-agent definitions, including inheritance, default model and effort, diagnostics, restrictions, and whether launchability is actually known. This tool does not create, import, or edit definitions.",
         promptSnippet: "List and inspect catalog roles and named agents, including inheritance and whether launchability is known.",
         promptGuidelines: [
             "Use agents_catalog to discover roles and named agents before subagent_spawn. It is read-only.",
@@ -46,6 +46,7 @@ export function agentsCatalogTool(Type: TypeModule, deps: DiscoveryDeps = {}) {
             "Ask the user to run /agents create or /agents import-codex for writes. Those commands confirm role, scope, and import replacement.",
             "Launch with the existing subagent_spawn or batch tool. Pass one agent or one role, not both. Two roles for one run need the user to choose one or split the work.",
             "Put an authoritative model or effort on the structured invocation. Do not rely on copying a model name into the child prompt. Explicit invocation and workflow choices override definition defaults.",
+            "Each entry shows its default model@effort when set. Omit model and thinking on the spawn to use it; name one only for a stated reason.",
         ],
         parameters: Type.Object({
             action: Type.String({ description: "list or inspect. No other action is accepted." }),

package/batch.mjs

@@ -215,8 +215,8 @@ export function formatBatchLaunchResponse({ batchId, batchName, launched, skippe
         lines.push(
             `Batch ${label} launched ${launched.length} subagent(s):`,
         );
-        for (const { name, id } of launched) {
-            lines.push(`• ${name} → ${id}`);
+        for (const { name, id, modelNote } of launched) {
+            lines.push(`• ${name} → ${id}${modelNote ? ` · ${modelNote}` : ""}`);
         }
     }
 

package/catalog-runtime.ts

@@ -4,7 +4,7 @@
  * `spawnSubagentRun`. This module does not grant tools, sandbox modes, or
  * extensions, and it does not read task prose for model choices.
  */
-import { describeDefaultLaunchCapabilities, LEGACY_CAPABILITY_CONTROLS, type LaunchEnricher, type LaunchEnrichment } from "./agent-inspection.ts";
+import { describeDefaultLaunchCapabilities, formatModelEffort, LEGACY_CAPABILITY_CONTROLS, type LaunchEnricher, type LaunchEnrichment } from "./agent-inspection.ts";
 import { resolveSelection, type EffectiveDefinition } from "./catalog-resolver.ts";
 import { defaultUserRoot, loadCatalog, type CatalogSnapshot } from "./catalog-store.ts";
 import { loadConfig, type SubagentConfig } from "./config.ts";
@@ -252,6 +252,57 @@ export async function clarifyCatalogRequest(
     return { status: "resolved", jobs: ordered.map(stripBookkeeping) };
 }
 
+/**
+ * Launch-line note for a catalog run whose effective model or effort differs
+ * from the role or agent default. The wording names the cause, so a fallback
+ * or a capped effort is not mistaken for a caller override:
+ * - override: `model openai/gpt-6-astra@high (role default openai/gpt-6-sol@high)`
+ * - fallback: `model xai/grok-4.7@high (role default openai/gpt-6-sol@high unavailable; foreground fallback)`
+ * - capped effort: `model openai/gpt-6-sol@medium (role default openai/gpt-6-sol@high; effort capped at medium by the model)`
+ * Undefined for a non-catalog run, a definition with no default, or a launch
+ * that matches the default. Only the fields the definition sets are compared.
+ */
+export function catalogDefaultNote(
+    record: Pick<CatalogRunRecord, "kind" | "effective" | "modelSelection" | "effortSelection"> | undefined,
+    model: string | undefined,
+    thinking: string | undefined,
+): string | undefined {
+    if (!record) return undefined;
+    const defaultModel = record.effective.model.value;
+    const defaultEffort = record.effective.effort.value;
+    const defaultLabel = formatModelEffort(defaultModel, defaultEffort);
+    if (!defaultLabel) return undefined;
+    const modelSource = record.modelSelection?.source;
+    const modelFallback = defaultModel !== null && modelSource !== undefined && FALLBACK_SOURCES.has(modelSource);
+    const modelDiffers = defaultModel !== null && (modelFallback || !sameModel(defaultModel, model, modelSource));
+    const effortCapped = defaultEffort !== null && record.effortSelection?.adjusted === true && (thinking ?? null) !== defaultEffort;
+    const effortDiffers = defaultEffort !== null && (thinking ?? null) !== defaultEffort;
+    if (!modelDiffers && !effortDiffers) return undefined;
+    const actual = formatModelEffort(model ?? "Pi default", thinking) ?? "Pi default";
+    const causes = [
+        modelFallback ? `${record.kind} default ${defaultLabel} unavailable; ${FALLBACK_LABELS[modelSource!] ?? modelSource} fallback` : `${record.kind} default ${defaultLabel}`,
+        ...(effortCapped ? [`effort capped at ${thinking ?? "the model default"} by the model`] : []),
+    ];
+    return `model ${actual} (${causes.join("; ")})`;
+}
+
+/** Model sources that mean the default could not be used, not that the caller chose another model. */
+const FALLBACK_SOURCES: ReadonlySet<string> = new Set(["tier-candidate", "foreground", "configured-default"]);
+const FALLBACK_LABELS: Record<string, string> = {
+    "tier-candidate": "same-tier",
+    foreground: "foreground",
+    "configured-default": "configured-default",
+};
+
+function sameModel(defaultModel: string, actual: string | undefined, source: string | undefined): boolean {
+    // The resolver launched the definition's own preference: same model, however it was spelled.
+    if (source === "role-default" || source === "agent-override") return true;
+    if (actual === undefined) return false;
+    if (defaultModel === actual) return true;
+    // A providerless default names the id; the resolved provider/id (the id may itself contain "/") still matches.
+    return !defaultModel.includes("/") ? actual.endsWith(`/${defaultModel}`) : false;
+}
+
 export async function prepareCatalogJob(snapshot: CatalogSnapshot, job: CatalogJobFields, host: CatalogHost): Promise<PreparedCatalogJob> {
     const agent = agentIdOf(job);
     const roles = roleIdsOf(job);

package/child-incidents.ts

@@ -11,9 +11,11 @@
  */
 import * as PiCodingAgent from "@earendil-works/pi-coding-agent";
 import type { BashOperations, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { emptyFailureState, reduceFailure, type FailureEvent, type FailureState } from "./shared-failure-observations.ts";
-import { DISPOSITION_TOOL, INTENT_ID_PATTERN, MAX_EXPECTED_EXIT_CODES, describeOpenTargets, foldToolEnd, foldToolStart,
-    newIncidentModel, readCommandIntent, readDispositionRequest, resolveDisposition, type IncidentModel, type IncidentSink } from "./incident-model.ts";
+// The intent validator is shared with background tasks through the vendored failure-observations module (#325).
+import { emptyFailureState, reduceFailure, INTENT_ID_PATTERN, MAX_EXPECTED_EXIT_CODES, readCommandIntent, withoutAbsentIntent,
+    type FailureEvent, type FailureState } from "./shared-failure-observations.ts";
+import { DISPOSITION_TOOL, describeOpenTargets, foldToolEnd, foldToolStart,
+    newIncidentModel, readDispositionRequest, resolveDisposition, type IncidentModel, type IncidentSink } from "./incident-model.ts";
 
 const { createBashToolDefinition } = PiCodingAgent;
 
@@ -95,7 +97,7 @@ export function intentBashDefinition(cwd: string, operations: BashOperations) {
             if (error) throw new Error(`Invalid command intent: ${error}. The command was not run.`);
             if (intent.attemptId) {
                 const reused = sessionToolCalls(ctx).some((row) => row.type === "tool_execution_start" && row.toolName === "bash" &&
-                    row.toolCallId !== toolCallId && (row.args as any)?.attemptId === intent.attemptId);
+                    row.toolCallId !== toolCallId && (withoutAbsentIntent(row.args) as any)?.attemptId === intent.attemptId);
                 if (reused) throw new Error(`Invalid command intent: attemptId ${intent.attemptId} was already used. The command was not run.`);
             }
             const { operationId: _o, attemptId: _a, expectedExitCodes: _e, ...command } = params ?? {};

package/docs/agent-catalog-operations.md

@@ -52,6 +52,8 @@ Codex applies the agent file's model and `model_reasoning_effort` ahead of the c
 
 `agents_catalog` accepts `list` and `inspect` only. It uses the same inspection view as `/agents show`. It has no write path. Launch remains `subagent_spawn` or the batch tool, with at most one `agent` or `role` selector. Those selectors are lifecycle's wiring, not this tool.
 
+Each list line and the inspect header end with the definition's default model and effort when one is set, such as `default openai/gpt-6-sol@high`: a role's own default, or a named agent's override or inherited role default. The structured view carries the same value as `defaults: { model, effort, label }`, or `null` when neither is set. A spawn that omits `model` and `thinking` uses it. When a catalog launch's model or effort differs from it, the launch line (and each batch job line) adds a note such as `model openai/gpt-6-astra@high (role default openai/gpt-6-sol@high)`. Only the fields the definition sets are compared. The note names the cause: a fallback from an unavailable default reads `(role default openai/gpt-6-sol@high unavailable; foreground fallback)` (or `same-tier` / `configured-default`), and an effort the model cannot run adds `effort capped at <level> by the model`.
+
 ## Lifecycle attachment
 
 ```ts

package/docs/failure-observations.md

@@ -47,6 +47,8 @@ Automatic recovery still requires an exact retry: the same tool name, arguments,
 
 Sandboxed children (the task runtime) get two structured additions. The parent honours them only for runs it launched on the task runtime: `meta.taskRuntime` and a parent-authored provenance record written before the child starts, outside the run directory, where the confined child cannot write. For any other run, intent-looking arguments are ordinary arguments and `failure_disposition` calls are ignored. If the metadata cannot be read for a moment, the parent waits and reads it again rather than falling back to the exact rule for the rest of the run. The wait is bounded: when the run ends, or after 30 seconds, the log is scanned under the exact-retry rule so real failures stay visible, with an `Observation incomplete` note that the metadata could not be read.
 
+Trust is decided once per scan, when the scan begins. A running trusted run whose metadata later becomes unreadable (a corrupt `meta.json`, say) keeps its trusted scan for as long as the parent keeps that scan in memory. Only after a parent restart, a `/reload`, or an eviction from the scan cache does the bounded wait apply again, and the scan after it uses the exact-retry rule with the same note. When the metadata is readable again, a later trusted scan closes the note once the incidents that the exact-rule scan left unresolved are resolved. Failures from the trusted period never hold it open, however often the scan is rebuilt.
+
 - `bash` accepts optional `operationId`, `attemptId`, and `expectedExitCodes`, validated before the command runs.
   - `operationId` names one logical operation across modified retries. A later success with the same `operationId` (a changed scope, timeout, or flag) recovers the earlier failure automatically. Without it, the exact rule applies. `attemptId` names one execution for use as evidence and never changes operation identity.
   - `expectedExitCodes` (distinct integers 1–255; a `0` is ignored, since exit 0 is already success) declares intentional non-zero exits, such as `[1]` for an `rg`/`grep` no-match or a `git diff --exit-code` probe. Only the final shell exit code is classified, taken from the tool's structured result, never from output text. Timeouts, aborts, and undeclared codes stay ordinary failures.

package/failures.ts

@@ -99,9 +99,55 @@ function settleMetadataGap(id: string, scan: Scan): void {
     }
     const held = [...intentBearing].some((incident) => findIncident(state, incident)?.status === "unresolved");
     if (held) return;
-    observeFailures(failurePath(id), [{ id: `run-metadata-readable:${gap.id}`, operation: "run-metadata", kind: "recovered", incidents: [gap.id] }]);
+    observeFailures(failurePath(id), [{ id: failureIdentity("run-metadata-readable", gap.id), operation: "run-metadata", kind: "recovered", incidents: [gap.id] }]);
     scan.gap = undefined;
 }
+/**
+ * Scan-period markers (#332). While a "run metadata could not be read" gap is open, each scan that
+ * starts under a different rule from the last marked one journals a no-op marker (a `delivered`
+ * event naming no incident) whose id records the rule: `run-metadata-scan:<rule>:<journal length>`.
+ * The ids are read back by prefix, so they are plain strings, not `failureIdentity` hashes.
+ */
+const SCAN_MARKER_PREFIX = "run-metadata-scan:";
+type ScanRule = "exact" | "trusted";
+function scanRuleAt(marker: string): ScanRule | undefined {
+    if (!marker.startsWith(SCAN_MARKER_PREFIX)) return undefined;
+    const rule = marker.slice(SCAN_MARKER_PREFIX.length).split(":")[0];
+    return rule === "exact" || rule === "trusted" ? rule : undefined;
+}
+/** Journal that a scan under `rule` begins, unless the last marked period already used it. */
+function markScanPeriod(path: string, state: FailureState, rule: ScanRule): FailureState {
+    let last: ScanRule | undefined;
+    for (let i = state.seen.length - 1; i >= 0 && !last; i -= 1) last = scanRuleAt(state.seen[i]!);
+    if (last === rule) return state;
+    return observeFailures(path, [{ id: `${SCAN_MARKER_PREFIX}${rule}:${state.seen.length}`, operation: "run-metadata", kind: "delivered", incidents: [] }]);
+}
+/**
+ * The unresolved tool incidents first journaled by an exact-rule scan, which a trusted scan cannot
+ * re-key. Each incident belongs to the period of the last marker before it, so a failure from a
+ * trusted period is never mistaken for a leftover, however often the scan is rebuilt (a parent
+ * restart, `/reload`, or cache eviction), and a later exact-rule period's failures always are. An
+ * incident before every marker is a leftover only when the journal has no exact-rule marker at all
+ * (the first trusted scan of a gap, or a journal from before the markers existed).
+ */
+function exactRuleLeftovers(path: string, prior: FailureState): Set<string> {
+    const state = markScanPeriod(path, prior, "trusted");
+    const period = new Map<string, ScanRule | undefined>();
+    let current: ScanRule | undefined;
+    let sawExact = false;
+    for (const id of state.seen) {
+        const rule = scanRuleAt(id);
+        if (rule) { current = rule; sawExact ||= rule === "exact"; continue; }
+        period.set(id, current);
+    }
+    const leftover = (id: string) => {
+        if (!period.has(id)) return false;
+        const rule = period.get(id);
+        return rule === "exact" || (rule === undefined && !sawExact);
+    };
+    return new Set(Object.values(state.observations)
+        .filter((x) => x.category === "tool" && x.status === "unresolved" && leftover(x.id)).map((x) => x.id));
+}
 /** Scan complete source records, independent of the finite progress/transcript tail. */
 export function collectRunFailures(id: string, cwd: string, terminal = false): FailureState {
     const path = failurePath(id);
@@ -151,6 +197,7 @@ export function collectRunFailures(id: string, cwd: string, terminal = false): F
                         summary: "Run metadata could not be read; tool failures are scanned under the exact-retry rule" }]);
                 }
                 if (!waited) return prior;
+                markScanPeriod(path, readRunFailures(id), "exact");
                 scan = { offset: 0, head, identity, model: newIncidentModel(false) };
             } else {
                 trustUnknownSince.delete(id);
@@ -160,8 +207,7 @@ export function collectRunFailures(id: string, cwd: string, terminal = false): F
                 // differently is still unresolved (#332).
                 const prior = readRunFailures(id);
                 const deferred = prior.observations[failureIdentity("run-metadata")];
-                if (deferred && deferred.status === "unresolved") scan.gap = { id: deferred.id,
-                    before: new Set(Object.values(prior.observations).filter((x) => x.category === "tool" && x.status === "unresolved").map((x) => x.id)) };
+                if (deferred && deferred.status === "unresolved") scan.gap = { id: deferred.id, before: exactRuleLeftovers(path, prior) };
             }
         }
         scan.head = head;

package/incident-model.ts

@@ -8,12 +8,10 @@
  * `operationId` or the exact tool/arguments/cwd hash; expected exits require a code
  * declared on the attempt before it ran and a structured exit code from the tool.
  */
-import { failureIdentity, findIncident, validateDisposition, INCIDENT_DISPOSITIONS, INTENT_ID_PATTERN, MAX_EXPECTED_EXIT_CODES,
+import { failureIdentity, findIncident, validateDisposition, INCIDENT_DISPOSITIONS,
     REJECTED_INTENT_CATEGORY, readCommandIntent, withoutAbsentIntent, type CommandIntent, type FailureEvent, type FailureState, type IncidentDisposition } from "./shared-failure-observations.ts";
 
 export const DISPOSITION_TOOL = "failure_disposition";
-// The intent validator is shared with background tasks through the vendored failure-observations module (#325).
-export { INTENT_ID_PATTERN, MAX_EXPECTED_EXIT_CODES, readCommandIntent, withoutAbsentIntent, type CommandIntent };
 
 function stable(value: unknown): unknown {
     if (Array.isArray(value)) return value.map(stable);
@@ -209,10 +207,12 @@ export function foldToolStart(model: IncidentModel, row: any, cwd: string, sink:
     }
     const parsed = toolName === "bash" ? readCommandIntent(row.args) : { intent: {} as CommandIntent };
     const intent = parsed.intent;
-    // Mirrors the child's check: any earlier bash start that named this attemptId, valid or not.
-    const rawAttemptId = toolName === "bash" && typeof row.args?.attemptId === "string" ? row.args.attemptId as string : undefined;
-    const reused = rawAttemptId !== undefined && model.namedAttempts.has(rawAttemptId);
-    if (rawAttemptId !== undefined) model.namedAttempts.add(rawAttemptId);
+    // Mirrors the child's check: any earlier bash start that named this attemptId, valid or not. The name
+    // is read after the same normalization the child applies, so `attemptId: ""` or `null` names nothing (#332).
+    const namedArgs = toolName === "bash" ? withoutAbsentIntent(row.args) : undefined;
+    const namedAttemptId = typeof namedArgs?.attemptId === "string" ? namedArgs.attemptId as string : undefined;
+    const reused = namedAttemptId !== undefined && model.namedAttempts.has(namedAttemptId);
+    if (namedAttemptId !== undefined) model.namedAttempts.add(namedAttemptId);
     const predictedRejection = parsed.error ?? (reused ? `attemptId ${intent.attemptId} was already used` : undefined);
     // A predicted refusal falls back to exact identity: if the child ran the command after all, it is
     // an ordinary failure of exactly that command, never a failure of the operation it named.

package/index.ts

@@ -151,6 +151,7 @@ import {
     loadLaunchSnapshot,
     noteCatalogHost,
     prepareCatalogJob,
+    catalogDefaultNote,
     tiersForLaunch,
     type CatalogHost,
     type CatalogJobFields,
@@ -175,6 +176,7 @@ const projectConfigDirName = typeof (PiCodingAgent as { CONFIG_DIR_NAME?: unknow
     : ".pi";
 
 const CATALOG_GUIDELINES = [
+    "With an agent or role, omit model and thinking to launch on its default model and effort, which agents_catalog shows. Name a model or effort only for a stated reason, such as a task or workflow instruction, and never copy one from another role's runs.",
     "When a task, workflow, or skill instruction names a model or effort, translate that authoritative choice into the structured model and thinking arguments before spawning. The runtime does not parse prose, quoted model names, or comparisons, and copying a model into the child prompt does not change the launch.",
     "Optional agent, role, and alias select a catalog definition. Pass one agent id or one role id. Pass an array of role ids when one run was given more than one role: that call asks to choose one or split, and without a UI choice it returns clarification-needed and starts no child. Naming both an agent and a role does the same. One job's choice does not change another job. A named agent displays its defined name. A direct role displays the label allocated from the local run registry. Calls without agent or role keep the existing name and model chain.",
     "Catalog model and effort are resolved before the child starts. An unavailable explicit model or unsupported explicit effort does not launch and does not fall back. The catalog grants no tools, sandbox modes, extensions, or permissions.",
@@ -1551,6 +1553,8 @@ export default function (pi: ExtensionAPI) {
         runtime: string;
         warn: string;
         sandboxDir?: string;
+        /** Set only when a catalog run's model or effort differs from its role or agent default. */
+        modelNote?: string;
     }> {
         assertThinkingLevel(p.thinking);
         const permissionPlan = resolveSubagentPermissions(pi, p.sandbox);
@@ -1766,7 +1770,8 @@ export default function (pi: ExtensionAPI) {
               `${resolution.unmapped.length > 1 ? "these tools" : "this tool"} will NOT exist in the child. ` +
               `Add a toolExtensions entry in config.json.\n`
             : "");
-        return { id, meta, spawned, runtime: runtime + (meta.timing ? `${formatTimingLimits(meta.timing, startedAt)}\n` : ""), warn, sandboxDir };
+        const modelNote = catalogDefaultNote(p.catalog, model, thinking);
+        return { id, meta, spawned, runtime: runtime + (meta.timing ? `${formatTimingLimits(meta.timing, startedAt)}\n` : ""), warn, sandboxDir, modelNote };
     }
 
     // ---- subagent_spawn -------------------------------------------------
@@ -1783,7 +1788,7 @@ export default function (pi: ExtensionAPI) {
             "After subagent_spawn, do NOT call subagent_output or subagent_result in a loop to wait for the result, and do NOT sleep. The run completes on its own and reports back on the next turn.",
             "Call subagent_result after a completion or attention callback, or when the user explicitly asks for the result. Use subagent_output only when the user explicitly asks how a run is progressing; never use either tool to poll.",
             ...SUBAGENT_ORCHESTRATION_GUIDELINES,
-            "The tools param is both the tool allowlist AND what determines which extensions load in the child (e.g. tools='read,bash,web_fetch' loads only the web-tools package). Ask for the tools the task needs and nothing more; clean:true gives a built-ins-only child. Pick a model with the model param (e.g. 'xai/grok-4.5@high'); providerless model patterns are resolved by Pi, while provider/model is deterministic and loads mapped provider extensions.",
+            "The tools param is both the tool allowlist AND what determines which extensions load in the child (e.g. tools='read,bash,web_fetch' loads only the web-tools package). Ask for the tools the task needs and nothing more; clean:true gives a built-ins-only child. Without an agent or role, pick a model with the model param (e.g. 'xai/grok-4.5@high'); providerless model patterns are resolved by Pi, while provider/model is deterministic and loads mapped provider extensions.",
             ...CATALOG_GUIDELINES,
             "By default the subagent is sandboxed. Human settings in /sandbox control file, credential-file, command, and network permissions; sandbox:false cannot override an enabled human profile. Without published settings, legacy write confinement applies. Set callback:false to finish quietly — then read the result on demand via subagent_result.",
             "Every run is timed by the harness: a soft deadline (default 30 min) steers the child to wrap up and wakes you once, the run is stopped after grace_minutes (reason deadline), a hard ceiling (default 90 min) stops it without grace (reason ceiling), and no progress for stuck_minutes (default 10) wakes you once (reason stuck). Set deadline_minutes/max_minutes/stuck_minutes to fit the task instead of writing a time limit into the prompt; do not stop a slow child that is still making progress.",
@@ -1795,8 +1800,8 @@ export default function (pi: ExtensionAPI) {
             agent: Type.Optional(Type.String({ description: "Named agent id (agent.<slug>). Mutually exclusive with role. The navigator shows the defined agent name." })),
             role: catalogRoleSchema("direct role launch"),
             alias: Type.Optional(Type.String({ description: "Per-run display alias for a direct role launch, such as checkout. Not a reusable agent. Colliding aliases gain a numeric suffix." })),
-            model: Type.Optional(Type.String({ description: "Pi model pattern, preferably provider/id, optionally suffixed with @effort (for example openai/gpt-5.5@high). Providerless patterns are resolved by Pi. Default: inherit foreground model. Put authoritative model choices here; do not rely on prompt text." })),
-            thinking: Type.Optional(Type.String({ description: "Reasoning effort for the child: off, minimal, low, medium, high, xhigh, or max (default: Pi/model default)." })),
+            model: Type.Optional(Type.String({ description: "Pi model pattern, preferably provider/id, optionally suffixed with @effort (for example openai/gpt-5.5@high). Providerless patterns are resolved by Pi. Omit to use the agent or role default; without one, inherit the foreground model. Put authoritative model choices here; do not rely on prompt text." })),
+            thinking: Type.Optional(Type.String({ description: "Reasoning effort for the child: off, minimal, low, medium, high, xhigh, or max. Omit to use the agent or role default; without one, the Pi/model default." })),
             tools: Type.Optional(Type.String({ description: "Tool allowlist: comma-separated names the child may use (e.g. 'read,bash,web_fetch'). This ALSO selects which extensions load — only packages backing a requested tool are loaded. Defaults to the configured safe set." })),
             exclude_tools: Type.Optional(Type.String({ description: "Comma-separated tool denylist, applied on top of the allowlist." })),
             clean: Type.Optional(Type.Boolean({ description: "Run a hermetic child with NO extensions at all (only built-ins: read, bash, edit, write). Default false — the extensions backing the requested tools load, so web_fetch and model auth (e.g. xai) work." })),
@@ -1841,21 +1846,22 @@ export default function (pi: ExtensionAPI) {
                         throw new Error(`Choosing split needs ${catalog.jobs.length} subagent slots, but only one was free. Nothing was launched.`);
                     }
                     reserved += extra;
-                    const launched: { name?: string; id: string }[] = [];
+                    const launched: { name?: string; id: string; modelNote?: string }[] = [];
                     for (const job of catalog.jobs) {
-                        const { id } = await spawnSubagentRun(ctx, job);
+                        const { id, modelNote } = await spawnSubagentRun(ctx, job);
                         gate.commit(1);
                         reserved -= 1;
-                        launched.push({ name: job.name, id });
+                        launched.push({ name: job.name, id, modelNote });
                     }
-                    return text(launched.map((item) => `Subagent launched: ${item.name ? `${item.name} ` : ""}id=${item.id}.`).join("\n"));
+                    return text(launched.map((item) => `Subagent launched: ${item.name ? `${item.name} ` : ""}id=${item.id}.${item.modelNote ? ` ${item.modelNote}.` : ""}`).join("\n"));
                 }
                 Object.assign(p, catalog.jobs[0]);
-                const { id, spawned, runtime, warn, sandboxDir } = await spawnSubagentRun(ctx, p);
+                const { id, spawned, runtime, warn, sandboxDir, modelNote } = await spawnSubagentRun(ctx, p);
                 gate.commit(1);
                 reserved = 0;
                 return text(
                     `Subagent launched: ${p.name ? `${p.name} ` : ""}id=${id} (pid ${spawned.pid}).\n` +
+                    (modelNote ? `${modelNote[0]!.toUpperCase()}${modelNote.slice(1)}.\n` : "") +
                     (p.callback === false
                         ? `Running in the background; the foreground is free. It will finish quietly — read the result with subagent_result id=${id}.\n`
                         : `Running in the background; the foreground is free. Its result will be posted back here when it finishes.\n`) +
@@ -1898,7 +1904,7 @@ export default function (pi: ExtensionAPI) {
                 agent: Type.Optional(Type.String({ description: "Named agent id applied to jobs that do not select their own agent or role." })),
                 role: catalogRoleSchema("shared role selector"),
                 alias: Type.Optional(Type.String({ description: "Direct-role alias applied when a job does not set alias." })),
-                model: Type.Optional(Type.String({ description: "Pi model pattern, preferably provider/id, optionally suffixed with @effort (default: inherit foreground model). Put authoritative model choices here; prompt text is not parsed." })),
+                model: Type.Optional(Type.String({ description: "Pi model pattern, preferably provider/id, optionally suffixed with @effort. Omit to use the agent or role default; without one, inherit the foreground model. Put authoritative model choices here; prompt text is not parsed." })),
                 thinking: Type.Optional(Type.String({ description: "Reasoning effort applied to every job: off, minimal, low, medium, high, xhigh, or max." })),
                 tools: Type.Optional(Type.String({ description: "Tool allowlist applied to every job." })),
                 exclude_tools: Type.Optional(Type.String({ description: "Comma-separated tool denylist applied to every job." })),
@@ -1997,7 +2003,7 @@ export default function (pi: ExtensionAPI) {
 
             const names = assignBatchJobNames(p.jobs);
             const batchId = nextBatchId();
-            const launched: { name: string; id: string }[] = [];
+            const launched: { name: string; id: string; modelNote?: string }[] = [];
             const failed: { name: string; reason: string }[] = [];
             const skipped: { name: string }[] = [];
             // How many reject-mode reserved slots are still held (not yet committed/released).
@@ -2035,10 +2041,10 @@ export default function (pi: ExtensionAPI) {
                             name = prepared.assign.name;
                         }
                     }
-                    const { id } = await spawnSubagentRun(ctx, { ...merged, name }, { batchId, batchName: p.batchName });
+                    const { id, modelNote } = await spawnSubagentRun(ctx, { ...merged, name }, { batchId, batchName: p.batchName });
                     gate.commit(1);
                     if (!launchAvailable) reservedRemaining -= 1;
-                    launched.push({ name, id });
+                    launched.push({ name, id, ...(modelNote ? { modelNote } : {}) });
                 } catch (err) {
                     gate.release(1);
                     if (!launchAvailable) reservedRemaining -= 1;

package/output-payload.ts

@@ -48,6 +48,7 @@ import {
 import {
     actionableFailures,
     failureJournalFingerprint,
+    fileChangeIdentity,
     failureRevision,
     formatIncidentSummary,
     formatTerminalIncidentSummary,
@@ -777,16 +778,7 @@ const LIST_INCIDENT_CACHE_MAX = 4096;
 let listIncidentComputations = 0;
 
 function listIncidentKey(id: string, terminal: boolean): string {
-    return JSON.stringify([terminal, logIdentityKey(logPathFor(id)), failureJournalFingerprint(failurePath(id))]);
-}
-
-function logIdentityKey(path: string): string {
-    try {
-        const stats = statSync(path, { bigint: true });
-        return `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeNs}:${stats.ctimeNs}`;
-    } catch (error) {
-        return `unreadable:${(error as NodeJS.ErrnoException).code ?? "error"}`;
-    }
+    return JSON.stringify([terminal, fileChangeIdentity(logPathFor(id)), failureJournalFingerprint(failurePath(id))]);
 }
 
 export function listIncidentCount(id: string, cwd: string, terminal: boolean): ListIncidentCount {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
   "license": "MIT",
   "type": "module",

package/shared-failure-observations.ts

@@ -75,7 +75,8 @@ export function failureIdentity(...parts: unknown[]): string {
   return createHash("sha256").update(JSON.stringify(parts)).digest("hex").slice(0, 32);
 }
 function text(value: string | undefined, fallback: string): string {
-  return (value || fallback).replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 400);
+  // The 400-unit cut can split a surrogate pair; a lone half would render as U+FFFD (#332).
+  return dropLoneSurrogates((value || fallback).replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 400));
 }
 
 /** Agent tool attempts: the agent handles its own tool errors, so one failure is not yet actionable. */
@@ -517,6 +518,8 @@ export interface TerminalFailureParts {
   rows: string[];
   /** Counts and separate facts: earlier-reported, unclassified, expected, closed history, correctness. */
   notes: string[];
+  /** The unclassified-count note, when it is among `notes`: a byte budget keeps it longer than the others. */
+  unclassifiedNote?: string;
 }
 /**
  * Terminal/completion facts: actionable and incomplete incidents from `incidents` as rows,
@@ -530,12 +533,14 @@ export function terminalFailureParts(state: FailureState, incidents: readonly st
   const earlier = activeFailures(state).filter((x) => !wanted.has(x.id) && reportable(x)).length;
   if (earlier) notes.push(`${earlier} actionable incident${earlier === 1 ? " was" : "s were"} reported earlier; not repeated here.`);
   const counts = failureCounts(state);
-  if (counts.unclassified) notes.push(`${counts.unclassified} earlier tool failure${counts.unclassified === 1 ? "" : "s"} remain${counts.unclassified === 1 ? "s" : ""} unclassified.`);
+  const unclassifiedNote = counts.unclassified
+    ? `${counts.unclassified} earlier tool failure${counts.unclassified === 1 ? "" : "s"} remain${counts.unclassified === 1 ? "s" : ""} unclassified.` : undefined;
+  if (unclassifiedNote) notes.push(unclassifiedNote);
   if (counts.expected) notes.push(`${counts.expected} expected failure${counts.expected === 1 ? "" : "s"} recorded.`);
   const history = closedHistoryLine(state);
   if (history) notes.push(history);
   if (counts.unclassified || counts.actionRequired) notes.push(CORRECTNESS_NOTE);
-  return { rows, notes };
+  return { rows, notes, ...(unclassifiedNote ? { unclassifiedNote } : {}) };
 }
 export function formatTerminalFailureFacts(state: FailureState, incidents: readonly string[] = []): string {
   const { rows, notes } = terminalFailureParts(state, incidents);
@@ -643,7 +648,10 @@ export interface IncidentPageRequest extends IncidentRowOptions {
  * Caller-owned incident pages. Whole rows are preferred; a row larger than the
  * page is split at a code-point boundary and resumes at that byte, so pages
  * reconstruct formatFailureLines() exactly (join with "\n" except after a page
- * that `endsPartial`). A page never exceeds `maxBytes`.
+ * that `endsPartial`). A page never exceeds `maxBytes`, so one smaller than the
+ * next code point (up to 4 bytes) returns no text, `hasMore`, and a `nextCursor`
+ * equal to `cursor`: the caller retries with a larger page, as with
+ * pageVerbatimText. Consumers never ask for fewer than 4 bytes.
  */
 export function pageFailureIncidents(state: FailureState, request: IncidentPageRequest = {}): FailureIncidentPage {
   // A cursor carries its view: following a history cursor stays in history without the flag.
@@ -761,14 +769,19 @@ export function incidentVerbatimPage(state: FailureState, request: IncidentPageR
  * it, so a cache keyed by it never serves stale incident counts.
  */
 export function failureJournalFingerprint(path: string): string {
-  let file: string;
+  return `${fileChangeIdentity(path)}|${existsSync(`${path}.observed`) ? 1 : 0}|${pendingWrites.get(path)?.length ?? 0}`;
+}
+/**
+ * A file's identity and change stamp (device, inode, size, and nanosecond mtime/ctime), or its read
+ * error. Any append, rewrite, replacement, or deletion changes it; for cache keys, never for trust.
+ */
+export function fileChangeIdentity(path: string): string {
   try {
     const stats = statSync(path, { bigint: true });
-    file = `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeNs}:${stats.ctimeNs}`;
+    return `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeNs}:${stats.ctimeNs}`;
   } catch (error) {
-    file = `unreadable:${(error as NodeJS.ErrnoException).code ?? "error"}`;
+    return `unreadable:${(error as NodeJS.ErrnoException).code ?? "error"}`;
   }
-  return `${file}|${existsSync(`${path}.observed`) ? 1 : 0}|${pendingWrites.get(path)?.length ?? 0}`;
 }
 
 export function incidentCursorAt(state: FailureState, offset: number, resource?: string, options: IncidentRowOptions = {}): string {
@@ -903,7 +916,7 @@ export function formatTerminalIncidentSummary(state: FailureState, options: Inci
   //    cursor's retrieval hint, the unclassified count, the cursor, and the count line. The
   //    correctness note goes last, and only when it alone does not fit.
   const correctness: string[] = notes.filter((x) => x === CORRECTNESS_NOTE);
-  const unclassified = notes.filter((x) => x !== CORRECTNESS_NOTE && /remains? unclassified\.$/.test(x));
+  const unclassified = notes.filter((x) => x === parts.unclassifiedNote);
   const low = notes.filter((x) => !correctness.includes(x) && !unclassified.includes(x));
   const ladder: Array<{ mode: Header | undefined; notes: string[] }> = [];
   for (let keep = low.length - 1; keep >= 0; keep -= 1) ladder.push({ mode: "full", notes: [...low.slice(0, keep), ...unclassified, ...correctness] });

package/shared-navigator.ts

@@ -95,6 +95,13 @@ type NavigatorState = {
   editorComponent?: Component;
   /** The editor Pi currently has mounted (the wrapper the factory returned last). */
   editorFocusTarget?: unknown;
+  /** How many times that wrapper has rendered, so an overlay can tell whether it is still on screen. */
+  editorRenders?: number;
+  /**
+   * Whether that wrapper rendered between the overlay's last two frames: true while it is on screen,
+   * including inside another extension's editor that wraps it. Undefined until two frames compare.
+   */
+  editorRenderedLastFrame?: boolean;
   detailOverlayRows?: number;
   dispose?: () => void;
   /** The mounted detail overlay, reused instead of stacking a second one. */
@@ -632,7 +639,7 @@ function installNavigatorEditor(ui: any, deps: HostDeps): unknown {
 
 function wrapEditor(inner: any, deps: HostDeps): unknown {
   if (inner && typeof inner.render === "function") state().editorComponent = inner as Component;
-  const proxy = new Proxy(inner, {
+  const proxy: any = new Proxy(inner, {
     get(target, prop) {
       if (prop === "handleInput") {
         return (data: string) => {
@@ -642,6 +649,13 @@ function wrapEditor(inner: any, deps: HostDeps): unknown {
           target.handleInput(data);
         };
       }
+      if (prop === "render" && typeof target.render === "function") {
+        return (...args: unknown[]) => {
+          const s = state();
+          if (s.editorFocusTarget === proxy) s.editorRenders = (s.editorRenders ?? 0) + 1;
+          return target.render(...args);
+        };
+      }
       const value = Reflect.get(target, prop);
       return typeof value === "function" ? value.bind(target) : value;
     },
@@ -709,6 +723,19 @@ function handleMainListInput(data: string, deps: HostDeps): boolean {
   return false;
 }
 
+/**
+ * Whether pi-tui has the editor our wrapper returned mounted (#332). Pi mounts whatever the factory
+ * returns, so another extension's `setEditorComponent` (a foreign factory, or `undefined` for Pi's
+ * default editor) unmounts it, and no key reaches our input handler after that. `undefined` means
+ * the host cannot say (no `isComponentMounted`), and callers keep their earlier behaviour.
+ */
+function liveEditorMounted(tui: unknown): boolean | undefined {
+  const live = state().editorFocusTarget;
+  const check = (tui as { isComponentMounted?: (component: unknown) => boolean } | undefined)?.isComponentMounted;
+  if (!live || typeof check !== "function") return undefined;
+  try { return check.call(tui, live) === true; } catch { return undefined; }
+}
+
 /** Close a detail overlay that is still mounted while the editor has focus. */
 function dismissOverlay(): void {
   const s = state();
@@ -762,6 +789,7 @@ function openNavigator(): void {
   try {
     try { s.dispose?.(); } catch { /* ignore */ }
     s.dispose = undefined;
+    s.editorRenderedLastFrame = undefined;
     let disposeToken: (() => void) | undefined;
     let overlayRef: NavigatorState["overlay"];
     let handle: { focus?(): void; unfocus?(options?: { target: unknown }): void } | undefined;
@@ -774,8 +802,12 @@ function openNavigator(): void {
         // Pi restores focus to the editor that was focused when the overlay opened. If an
         // extension re-installed the editor since, that instance is unmounted and every key
         // would be lost; hand focus to the live editor before closing.
+        // Only an editor on screen can take focus: after another extension replaced ours, Pi already
+        // focused its replacement, and handing focus to our unmounted wrapper would swallow every key.
+        // An extension that wraps ours mounts its own component, so pi-tui does not find ours, but ours
+        // still renders and handles every key through it: that is still the live editor (#332).
         const liveEditor = s.editorFocusTarget;
-        if (liveEditor) {
+        if (liveEditor && (liveEditorMounted(tui) !== false || s.editorRenderedLastFrame !== false)) {
           try { handle?.unfocus?.({ target: liveEditor }); } catch { /* ignore */ }
         }
         done(value);
@@ -952,8 +984,31 @@ function createOverlayComponent(
     requestRender();
   }
 
+  let editorRendersSeen: number | undefined;
+  /**
+   * Our editor wrapper was uninstalled: close, since no key of ours can reach this overlay again and
+   * it would cover the editor that replaced ours (#332). An extension that composes the editor inside
+   * its own non-container component still renders ours, so the wrapper also counts as live while it
+   * rendered since the previous overlay frame (Pi renders the editor before it composites overlays).
+   */
+  function closeIfEditorReplaced(): void {
+    const rendersBefore = editorRendersSeen;
+    const renders = state().editorRenders ?? 0;
+    editorRendersSeen = renders;
+    state().editorRenderedLastFrame = rendersBefore === undefined ? undefined : renders !== rendersBefore;
+    if (closed || liveEditorMounted(tui) !== false || rendersBefore === undefined || renders !== rendersBefore) return;
+    // Not from inside pi-tui's render pass: hiding an overlay there would change the stack it is drawing.
+    queueMicrotask(() => {
+      if (closed) return;
+      unfocusMainList();
+      close();
+      requestRender();
+    });
+  }
+
   return {
     render(width: number) {
+      closeIfEditorReplaced();
       refreshRows();
       const railLines = buildMainListLines(overlayState.rows, width, deps.truncate, fg, {
         selectedId: selectedRow()?.navigatorId,

package/shared-sandbox-core.ts

@@ -109,8 +109,12 @@ export type SandboxCommandArgs = SandboxTarget & {
     internalHelperExecutable?: boolean;
 };
 
-/** The wrapper command to spawn: the backend executable and its full argv. */
-export type SandboxCommand = { file: string; fileArgs: string[] };
+/**
+ * The wrapper command to spawn: the backend executable and its full argv.
+ * `notices` are lines the caller shows with the launch output, such as a
+ * placeholder the Linux backend had to leave in the user's files.
+ */
+export type SandboxCommand = { file: string; fileArgs: string[]; notices?: string[] };
 
 /** The caller's default-on / explicit-request / opt-out decision. */
 export type SandboxRequest = {
@@ -131,7 +135,11 @@ export type SandboxSeams = {
     platform?: () => string;
     /** Defaults to a PATH scan that stats and access-checks without executing. */
     lookupExecutable?: (name: string) => string | undefined;
-    /** Defaults to `fs.realpathSync`. Must throw when the path does not exist. */
+    /**
+     * Defaults to `fs.realpathSync.native`, which (unlike the JS `realpathSync`)
+     * returns the on-disk case of every existing component on a case-insensitive
+     * volume, as the kernel sees it. Must throw when the path does not exist.
+     */
     canonicalize?: (path: string) => string;
     /** Defaults to `fs.writeFileSync`. */
     writeProfile?: (path: string, contents: string) => void;
@@ -325,7 +333,7 @@ function currentPlatform(seams: SandboxSeams): string {
  * canonicalizes through its real parent chain.
  */
 export function canonicalizePath(path: string, seams: SandboxSeams = {}): string {
-    const canonicalize = seams.canonicalize ?? realpathSync;
+    const canonicalize = seams.canonicalize ?? realpathSync.native;
     const absolute = resolve(path);
     try {
         const resolved = canonicalize(absolute);
@@ -337,7 +345,7 @@ export function canonicalizePath(path: string, seams: SandboxSeams = {}): string
             try {
                 const source = statSync(resolved);
                 const alias = statSync(candidate);
-                if (source.dev === alias.dev && source.ino === alias.ino) return realpathSync(candidate);
+                if (source.dev === alias.dev && source.ino === alias.ino) return realpathSync.native(candidate);
             } catch { /* An unrelated Data-volume path keeps its original identity. */ }
         }
         return resolved;
@@ -358,7 +366,7 @@ function compile(
     // bind-mounts it; the macOS backend has always tolerated a not-yet-created
     // one. Keep both behaviors rather than unifying them here.
     const writableRoot = strictRoot
-        ? (seams.canonicalize ?? realpathSync)(policy.writableRoot)
+        ? (seams.canonicalize ?? realpathSync.native)(policy.writableRoot)
         : canonicalizePath(policy.writableRoot, seams);
 
     // The broad profile also keeps each literal entry: its removal grants would
@@ -544,6 +552,67 @@ function contains(root: string, target: string): boolean {
     return target.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
 }
 
+/** Per-device answer to "does this volume fold case?" (APFS/HFS+ default). */
+const caseFoldingByDevice = new Map<number, boolean>();
+
+/**
+ * Whether the volume holding `path` (its nearest existing ancestor) ignores
+ * case: an existing component whose case-swapped spelling names the same
+ * inode proves it. macOS only; false whenever it cannot be shown.
+ */
+function caseInsensitiveVolume(path: string): boolean {
+    if (process.platform !== "darwin") return false;
+    let current = path;
+    while (!existsSync(current) && dirname(current) !== current) current = dirname(current);
+    let device: number;
+    try { device = statSync(current).dev; } catch { return false; }
+    const known = caseFoldingByDevice.get(device);
+    if (known !== undefined) return known;
+    for (let probe = current; dirname(probe) !== probe; probe = dirname(probe)) {
+        const name = basename(probe);
+        const swapped = [...name].map((c) => c === c.toLowerCase() ? c.toUpperCase() : c.toLowerCase()).join("");
+        if (swapped === name) continue;
+        try {
+            const original = statSync(probe);
+            if (original.dev !== device) break;
+            let folded = false;
+            try {
+                const other = statSync(join(dirname(probe), swapped));
+                folded = other.dev === original.dev && other.ino === original.ino;
+            } catch { /* The swapped name is absent: case-sensitive. */ }
+            caseFoldingByDevice.set(device, folded);
+            return folded;
+        } catch { return false; }
+    }
+    return false;
+}
+
+/**
+ * Spell `path` the way the policy spells it when they differ only in case on a
+ * case-insensitive volume. `canonicalizePath` fixes the case of every existing
+ * component, but a missing tail (`~/.NPMRC` while `~/.npmrc` is absent) keeps
+ * the caller's case, and the kernel still treats it as the protected name. The
+ * longest policy path that matches case-insensitively wins, so the pre-check
+ * decides as the kernel does (#354).
+ */
+function alignCaseToPolicy(path: string, policy: CompiledSandboxWritePolicy): string {
+    const broad = policy.broad;
+    const candidates = [policy.writableRoot, ...policy.denyWrite, ...(policy.credentialPaths ?? []),
+        ...(policy.runtimeWrite ?? []), ...(policy.compatibilityWrite ?? []),
+        ...(broad ? [broad.home, ...broad.tempRoots, ...broad.deleteRoots, ...broad.codePaths] : [])];
+    const lower = path.toLowerCase();
+    if (lower.length !== path.length) return path;
+    let best: string | undefined;
+    for (const candidate of candidates) {
+        const folded = candidate.toLowerCase();
+        if (folded.length !== candidate.length || !contains(folded, lower)) continue;
+        if (!best || candidate.length > best.length) best = candidate;
+    }
+    // Already spelled as the policy spells it: nothing to probe.
+    if (!best || path.startsWith(best) || !caseInsensitiveVolume(path)) return path;
+    return `${best}${path.slice(best.length)}`;
+}
+
 function isCredential(path: string, policy: CompiledSandboxWritePolicy): boolean {
     return (policy.credentialPaths ?? []).some((credential) => contains(credential, path));
 }
@@ -558,7 +627,7 @@ export function evaluateReadAccess(
     policy: CompiledSandboxWritePolicy,
     seams: SandboxSeams = {},
 ): ReadAccessDecision {
-    const path = canonicalizePath(target, seams);
+    const path = alignCaseToPolicy(canonicalizePath(target, seams), policy);
     const permissions = policy.permissions;
     if (!permissions) return { allowed: true, path };
     if (policy.broad) {
@@ -585,7 +654,7 @@ export function evaluateWriteAccess(
     policy: CompiledSandboxWritePolicy,
     seams: SandboxSeams = {},
 ): WriteAccessDecision {
-    const path = canonicalizePath(target, seams);
+    const path = alignCaseToPolicy(canonicalizePath(target, seams), policy);
     if (policy.broad) return evaluateBroadWrite(path, policy, policy.broad, seams);
     if (!policy.permissions && !contains(policy.writableRoot, path)) {
         return { allowed: false, path, reason: "outside-writable-root" };
@@ -1370,10 +1439,28 @@ function buildLinuxBroadCommand(
     const readOnly = new Set<string>();
     const directoryLocation = (path: string) => [...DIRECTORY_LOCATIONS]
         .some((name) => canonicalizePath(join(broad.home, name), seams) === path);
+    // The literal fixed-list entry (a dangling `~/.ssh` link) or its canonical path.
+    const directoryEntry = (path: string) => directoryLocation(path) ||
+        [...DIRECTORY_LOCATIONS].some((name) => join(broad.home, name) === path);
     // Directories holding a protected symlink: read-only, so the link cannot be
     // replaced, with their existing entries bound writable again below.
     const linkParents = new Set<string>();
-    const danglingTargets = new Set(protectedPaths.flatMap((path) => walkSymlinks(path).unresolved));
+    // Where dangling links would land. Only the first missing component of each
+    // needs a guard: nothing can be created below a read-only mount or a locked
+    // parent. It is a directory when more of the path lies below it, or when the
+    // link is a directory-type entry (`~/.ssh -> ~/work/ssh`).
+    const firstMissing = new Map<string, boolean>();
+    const belowFirstMissing = new Set<string>();
+    for (const path of protectedPaths) {
+        const unresolved = walkSymlinks(path).unresolved;
+        if (!unresolved.length) continue;
+        const first = unresolved[0]!;
+        const full = unresolved.at(-1)!;
+        firstMissing.set(first, firstMissing.get(first) === true || first !== full || directoryEntry(path));
+        if (full !== first) belowFirstMissing.add(full);
+    }
+    const created: string[] = [];
+    const makeDirectory = seams.makeDirectory ?? ((target: string) => mkdirSync(target, { recursive: true, mode: 0o700 }));
     const guard = (path: string, hide: boolean) => {
         let directory: boolean | undefined;
         let link = false;
@@ -1387,21 +1474,39 @@ function buildLinuxBroadCommand(
             if (link && dirname(path) !== broad.home && writableAt(dirname(path))) linkParents.add(dirname(path));
             return;
         }
-        if (danglingTargets.has(path)) {
+        if (belowFirstMissing.has(path) && !firstMissing.has(path)) return; // Its first missing component is guarded.
+        if (firstMissing.has(path)) {
             // Where a dangling link would land: nothing may be created there.
-            // Lock its nearest existing ancestor (entries stay writable, see
-            // below) rather than plant a placeholder in the user's files. Temp
-            // and the workspace root stay open to new entries, so a placeholder
-            // is bound there instead, failing closed if it cannot be made.
+            // A missing directory gets an empty read-only placeholder directory,
+            // so only that one name is taken, not every new entry beside it
+            // (`~/.cache/<tool>/…` would otherwise lock all of `~/.cache`). A
+            // missing file is not planted in the user's files: its parent is
+            // locked instead (entries stay writable, see below), except in the
+            // workspace root and temp, which must keep accepting new entries,
+            // so the file placeholder is bound there. Each placeholder made is
+            // reported, and the workspace and temp fail closed without one.
             if (!writableAt(path)) return;
-            let ancestor = dirname(path);
-            while (!exists(ancestor) && dirname(ancestor) !== ancestor) ancestor = dirname(ancestor);
-            if (ancestor === project || broad.tempRoots.includes(ancestor)) {
-                if (!materialize(path)) throw new Error(`Cannot protect denied path: ${path}`);
-                readOnly.add(path);
-            } else if (ancestor !== broad.home) {
-                linkParents.add(ancestor);
+            const ancestor = dirname(path);
+            if (ancestor === broad.home) return; // Home is read-only already.
+            const failClosed = ancestor === project || broad.tempRoots.includes(ancestor);
+            const directory = firstMissing.get(path)!;
+            if (directory || failClosed) {
+                const existed = exists(path);
+                let made: boolean;
+                if (directory) {
+                    try { makeDirectory(path); } catch { /* Re-checked below. */ }
+                    made = exists(path);
+                } else {
+                    made = materialize(path);
+                }
+                if (made) {
+                    if (!existed) created.push(`${path}${directory ? "/" : ""}`);
+                    readOnly.add(path);
+                    return;
+                }
+                if (failClosed) throw new Error(`Cannot protect denied path: ${path}`);
             }
+            linkParents.add(ancestor);
             return;
         }
         if (!exists(path)) {
@@ -1476,6 +1581,9 @@ function buildLinuxBroadCommand(
         file: bwrap,
         fileArgs: [...fileArgs, ...(!permissions.network ? ["--unshare-net"] : []),
             "--", args.execPath, ...args.execArgs],
+        ...(created.length && { notices: [
+            `Sandbox: created an empty read-only placeholder where a protected symlink points at nothing, and left it in place: ${created.join(", ")}`,
+        ] }),
     };
 }
 

package/shared-task-files.ts

@@ -123,7 +123,7 @@ export function removeDecision(path: string, policy: CompiledSandboxWritePolicy)
     const literalLeaf: SandboxSeams = {
         canonicalize: (candidate) => {
             if (candidate === entry) throw new Error("the leaf entry is judged literally");
-            return realpathSync(candidate);
+            return realpathSync.native(candidate);
         },
     };
     return evaluateDeleteAccess(entry, policy, literalLeaf);

package/shared-task-sandbox.ts

@@ -124,6 +124,7 @@ export function createTaskBashOperations(
                     .map(([key, value]) => `${key}=${value}`), shell.shell, ...shell.args, command],
             }, { sandboxEnabled: true, explicitSandbox: true });
             if (!wrapped) throw new Error("Sandbox: no task execution backend is available.");
+            for (const line of wrapped.notices ?? []) options.onData(Buffer.from(`${line}\n`));
             if (options.signal?.aborted) throw new Error("aborted");
             if (options.timeout !== undefined && (!Number.isFinite(options.timeout) || options.timeout <= 0 || options.timeout * 1000 > 2147483647)) {
                 throw new Error("Invalid timeout: must be a positive, supported number of seconds");

package/task-policy.ts

@@ -90,7 +90,7 @@ export function prepareTaskRuntime(options: {
     }
     const support = describeSandboxSupport();
     if (!support.supported) throw new Error(`Task sandbox unavailable: ${support.reason}`);
-    const root = realpathSync(options.root);
+    const root = realpathSync.native(options.root);
     const home = homedir();
     if (root === dirname(root) || root === canonicalizePath(home)) throw new Error("Task sandbox requires a project directory, not the filesystem or home root.");
     const permissions = options.permissions ?? DEFAULT_TASK_PERMISSIONS;