pi-better-subagents 0.7.0 → 0.7.1

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/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/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.7.1",
   "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;