pi-better-background-tasks 0.4.0 → 0.5.0

package/README.md

@@ -99,9 +99,11 @@ After `/new`, `/resume`, fork, or switching to another session, the previous
 session's tasks keep running but are paused from Pi's side: watches do not poll,
 remote tmux output is not collected, and `timeout_seconds` deadlines are not
 enforced until that session is active again. An overdue deadline is enforced as
-soon as the session resumes, so a timeout can land late but is never skipped. A
-local process that exits in the meantime is recorded as finished, and its
-callback is delivered when its session resumes.
+soon as the session resumes, so a timeout can land late but is never skipped.
+While the same Pi process stays open, a local process that exits in the meantime
+is recorded as finished, and its callback is delivered when its session resumes.
+If you quit Pi first, nothing records that exit: when the session is resumed in a
+new Pi process, a task whose process is gone is marked lost.
 
 ## Watch conditions
 
@@ -151,7 +153,7 @@ evidence is reported as **observation incomplete**.
 Pass `operation_id` and `expected_exit_codes` on `bg_task_spawn`, `bg_task_watch`,
 or `bg_task` to declare intent before launch; a malformed declaration starts
 nothing. An exit code in `expected_exit_codes` (distinct integers 1-255, such as
-`[1]` for a no-match probe) is recorded as an **Expected failure** that needs no
+`[1]` for a no-match probe; a `0` is ignored) is recorded as an **Expected failure** that needs no
 action; signals and timeouts never are. When a task with an `operation_id`
 succeeds, earlier failed tasks with the same `operation_id`, kind, cwd, SSH
 target, and owner (the same session id, or for sessionless tasks the same Pi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
   "license": "MIT",
   "type": "module",

package/src/failures.ts

@@ -1,7 +1,7 @@
 import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
-  activeFailures, failureAttentionHandled, failureIdentity, formatFailureSummary, markFailureAttentionDelivered,
+  actionableFailures, activeFailures, failureAttentionHandled, failureIdentity, formatFailureSummary, markFailureAttentionDelivered,
   observeFailures, pendingAttentionNote, pendingAttentionRows, pendingFailureAttention, readCommandIntent, readFailureState,
   type FailureEvent, type FailureState,
 } from "./shared-failure-observations.js";
@@ -12,6 +12,14 @@ import type { BackgroundTaskMeta } from "./types.js";
 
 export const failurePath = (id: string): string => join(taskDir(id), "failures.jsonl");
 export const failureSummary = (id: string): string => formatFailureSummary(readFailureState(failurePath(id)));
+/**
+ * The failure summary plus whether anything needs action. A navigator row leads with failure text
+ * only when something does; the quiet history line never displaces the command (#332).
+ */
+export function failureView(id: string): { text: string; actionable: boolean } {
+  const state = readFailureState(failurePath(id));
+  return { text: formatFailureSummary(state), actionable: actionableFailures(state).length > 0 };
+}
 
 export function recordFailure(meta: BackgroundTaskMeta, operation: string, summary: string, eventKey: unknown,
   options: { category?: string; expected?: boolean; incomplete?: boolean; evidence?: string; at?: number } = {}): void {

package/src/navigator-provider.ts

@@ -10,8 +10,8 @@ import {
 } from "./shared-navigator.ts";
 import { CustomEditor } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
-import { activeFailures, failureLabel, readFailureState } from "./shared-failure-observations.js";
-import { failurePath, failureSummary } from "./failures.js";
+import { actionableFailures, failureLabel, readFailureState } from "./shared-failure-observations.js";
+import { failurePath, failureView } from "./failures.js";
 import { readLog } from "./logs.js";
 import { listMetasForOrigin, onMetaChanged, readMeta, writeMeta } from "./registry.js";
 import { stopTask } from "./runtime.js";
@@ -105,7 +105,9 @@ function isExpiredTerminalNavigatorRow(meta: BackgroundTaskMeta, now: number): b
 }
 
 function rowFromMeta(meta: BackgroundTaskMeta, now: number): BackgroundWorkRow {
-  const failure = failureSummary(meta.id);
+  // Only a failure that needs action replaces the row's command; history stays in the detail view (#332).
+  const view = failureView(meta.id);
+  const failure = view.actionable ? view.text : "";
   const elapsed = formatDuration((meta.endedAt ?? now) - meta.startedAt);
   return {
     providerId: "background-tasks",
@@ -129,7 +131,8 @@ function rowFromMeta(meta: BackgroundTaskMeta, now: number): BackgroundWorkRow {
 
 function detailFromMeta(meta: BackgroundTaskMeta | undefined, now: number, options?: { logTailLines?: number }): BackgroundWorkDetail | null {
   if (!meta) return null;
-  const failure = failureSummary(meta.id);
+  const view = failureView(meta.id);
+  const failure = view.text;
   const log = readLog(meta.logPath, options?.logTailLines ?? NAVIGATOR_DETAIL_ROWS);
   const command = commandLabel(meta);
   const metadata = [
@@ -164,7 +167,7 @@ function detailFromMeta(meta: BackgroundTaskMeta | undefined, now: number, optio
     title: meta.name || meta.id,
     status: meta.status,
     statusTone: toneForStatus(meta.status),
-    subtitle: failure ? failure.split("\n")[0]! : compactCommandLabel(meta),
+    subtitle: view.actionable ? failure.split("\n")[0]! : compactCommandLabel(meta),
     metadata,
     foldedSections: [{
       id: "command",
@@ -217,7 +220,7 @@ function secondaryLabel(meta: BackgroundTaskMeta): string | undefined {
 
 function factsForMeta(meta: BackgroundTaskMeta, now: number): string[] {
   const facts: string[] = [];
-  const incident = activeFailures(readFailureState(failurePath(meta.id)))[0];
+  const incident = actionableFailures(readFailureState(failurePath(meta.id)))[0];
   if (incident) facts.push(`${failureLabel(incident)}: ${incident.summary}`);
   if (meta.status === "running") {
     const stall = observeBackgroundTaskStall(meta, now);

package/src/output.ts

@@ -548,13 +548,16 @@ export function formatStatus(
   if (pageKind === "f") return formatLog(meta.id, { ...options, raw: true });
   if (pageKind === "t") return formatVerbose(meta, options);
   if (options.verbose) return formatVerbose(meta, options);
+  // A bg_task_list page cursor pages the list, not this task: say so rather than report it as a
+  // stale status cursor (#332).
+  const listCursor = pageKind === "l";
   const state = failureStateFor(meta.id);
   const resource = `status:${scopeKey(options)}:${meta.id}`;
   const revision = inspectStatusRevision({
     resource,
     contentRevision: contentRevision(meta),
     failureRevision: failureRevision(state),
-    cursor: options.cursor,
+    cursor: listCursor ? undefined : options.cursor,
   });
   if (options.cursor && revision.change === "none") {
     return assembleBackgroundContent({
@@ -574,6 +577,7 @@ export function formatStatus(
   // Change/reset and read-gap facts are short and decision-relevant: they are
   // budgeted with the decision section, ahead of long incident rows.
   const changeFacts = [
+    ...(listCursor ? ["cursor ignored: it is a bg_task_list page cursor; pass it to bg_task_list, or pass this status's statusCursor here."] : []),
     ...(revision.change === "failure" ? ["change=failure"] : []),
     ...(revision.reset ? [`reset=${revision.reset}`] : []),
     ...(log.error ? [`log unreadable: ${oneLine(log.error, 200)}; cannot treat this as an empty healthy log.`] : []),

package/src/runtime.ts

@@ -34,8 +34,11 @@ const remoteSessionStarts = new Map<string, Promise<CommandResult>>();
 const activePolls = new Set<string>();
 const logRetentionTimers = new Map<string, ReturnType<typeof setInterval>>();
 const LOG_RETENTION_CHECK_MS = 1000;
-const handoffTimers = new Map<string, ReturnType<typeof setInterval>>();
+const handoffTimers = new Map<string, ReturnType<typeof setTimeout>>();
+// The handoff check backs off from 250 ms to 4 s while the task keeps running,
+// and returns to 250 ms once its process is gone so the grace period is timed closely.
 const HANDOFF_CHECK_MS = 250;
+const HANDOFF_MAX_CHECK_MS = 4_000;
 const HANDOFF_LOST_GRACE_MS = 5_000;
 let scheduledWorkSuspended = false;
 const REMOTE_SESSION_POLL_MS = 100;
@@ -62,8 +65,9 @@ export const DEFAULT_WATCH_TIMEOUT_SECONDS = 15 * 60;
  * tasks keep running, but their watches do not poll, remote tmux output is not
  * collected, and their `timeout_seconds` deadlines are not enforced until that
  * session is active again; an overdue deadline is enforced immediately on resume.
- * A local process that exits meanwhile is recorded as terminal and its callback
- * is delivered when its session resumes.
+ * A local process that exits meanwhile, while this Pi process is still running,
+ * is recorded as terminal and its callback is delivered when its session resumes;
+ * after Pi quits, a resumed task whose process is gone is marked lost instead.
  */
 export function suspendScheduledWork(): void {
   scheduledWorkSuspended = true;
@@ -71,7 +75,7 @@ export function suspendScheduledWork(): void {
   for (const timer of remoteSessionTimers.values()) clearTimeout(timer);
   for (const timer of processTimeoutTimers.values()) clearTimeout(timer);
   for (const timer of logRetentionTimers.values()) clearInterval(timer);
-  for (const timer of handoffTimers.values()) clearInterval(timer);
+  for (const timer of handoffTimers.values()) clearTimeout(timer);
   handoffTimers.clear();
   watcherTimers.clear();
   remoteSessionTimers.clear();
@@ -528,7 +532,9 @@ function scheduleHandoff(
   stopHandoff(id);
   if (scheduledWorkSuspended) return;
   let deadSince: number | undefined;
-  const timer = setInterval(() => {
+  let delayMs = HANDOFF_CHECK_MS;
+  const check = () => {
+    handoffTimers.delete(id);
     const meta = readMeta(id);
     if (!meta) {
       stopHandoff(id);
@@ -554,16 +560,26 @@ function scheduleHandoff(
         clearProcessTimeout(id);
         stopLogRetention(id);
         markProcessLost(pi, meta, getActiveSession);
+        return;
       }
+      delayMs = HANDOFF_CHECK_MS;
+    } else {
+      delayMs = Math.min(HANDOFF_MAX_CHECK_MS, delayMs * 2);
     }
-  }, HANDOFF_CHECK_MS);
-  timer.unref();
-  handoffTimers.set(id, timer);
+    arm();
+  };
+  const arm = () => {
+    if (scheduledWorkSuspended) return;
+    const timer = setTimeout(check, delayMs);
+    timer.unref();
+    handoffTimers.set(id, timer);
+  };
+  arm();
 }
 
 function stopHandoff(id: string): void {
   const timer = handoffTimers.get(id);
-  if (timer) clearInterval(timer);
+  if (timer) clearTimeout(timer);
   handoffTimers.delete(id);
 }
 

package/src/shared-failure-observations.ts

@@ -104,24 +104,60 @@ export interface CommandIntent {
 export type CommandIntentField = keyof CommandIntent;
 const INTENT_FIELDS: readonly CommandIntentField[] = ["operationId", "attemptId", "expectedExitCodes"];
 /**
- * The one normalization of intent-bearing arguments: an explicit `null` intent field means
- * "not declared", exactly like an omitted one. Models routinely send optional fields as null, and
- * Pi's argument validation (0.87+) drops optional nulls before a tool runs, while the process log
- * and session record keep the raw arguments. Every reader of intent, the executing tool and the
- * replay alike, goes through this so both sides see the same declaration from the same input.
+ * Pi's own argument coercion for the intent fields (pi-ai `validateToolArguments` against the confined
+ * bash schema, where each field is `anyOf: [field schema, null]`). Pi applies it before execute, but the
+ * process log and session record keep the raw arguments; mirroring it lets the parent's replay read
+ * the declaration the child executed with (#332).
+ * - ids: a number or boolean becomes its string; `""` fails the pattern and falls through to null.
+ * - exit codes: array items that read as integers become integers (null -> 0, true -> 1);
+ *   a scalar `0`, `""`, or `false` falls through to null.
+ */
+function coerceInteger(value: unknown): unknown {
+  if (value === null) return 0;
+  if (typeof value === "string" && value.trim() !== "" && Number.isInteger(Number(value))) return Number(value);
+  if (typeof value === "boolean") return value ? 1 : 0;
+  return value;
+}
+function normalizeIntentField(key: CommandIntentField, value: unknown): unknown {
+  if (value == null) return undefined;
+  if (key === "expectedExitCodes") {
+    if (value === 0 || value === "" || value === false) return undefined;
+    if (!Array.isArray(value)) return value;
+    // 0 is a no-op declaration: exit 0 is already success. A list of only zeros declares nothing.
+    const codes = value.map(coerceInteger).filter((code) => code !== 0);
+    if (codes.length === 0 && value.length > 0) return undefined;
+    return codes.length === value.length && codes.every((code, index) => code === value[index]) ? value : codes;
+  }
+  if (value === "") return undefined;
+  return typeof value === "number" || typeof value === "boolean" ? String(value) : value;
+}
+/**
+ * The one normalization of intent-bearing arguments. An explicit `null` intent field means "not
+ * declared", exactly like an omitted one: models routinely send optional fields as null, and Pi's
+ * argument validation drops or nulls them before a tool runs, while the process log and session
+ * record keep the raw arguments. Values Pi would coerce are coerced the same way, and `0` is dropped
+ * from `expectedExitCodes`. Every reader of intent, the executing tool and the replay alike, and the
+ * exact operation identity go through this, so all see the same declaration from the same input.
+ * Malformed values are kept as they are for the validator to refuse.
  */
 export function withoutAbsentIntent<T>(args: T): T {
   if (!args || typeof args !== "object" || Array.isArray(args)) return args;
   const input = args as Record<string, unknown>;
-  if (!INTENT_FIELDS.some((key) => key in input && input[key] == null)) return args;
-  const out = { ...input };
-  for (const key of INTENT_FIELDS) if (key in out && out[key] == null) delete out[key];
-  return out as T;
+  let out: Record<string, unknown> | undefined;
+  for (const key of INTENT_FIELDS) {
+    if (!(key in input)) continue;
+    const value = normalizeIntentField(key, input[key]);
+    if (value === input[key]) continue;
+    out ??= { ...input };
+    if (value === undefined) delete out[key];
+    else out[key] = value;
+  }
+  return (out ?? args) as T;
 }
 /**
- * Validate structured intent fields. Absent fields (omitted, undefined, or null) are fine; malformed
+ * Validate structured intent fields after `withoutAbsentIntent`. Absent fields are fine; malformed
  * ones are an error, and the caller must not run the command. `names` renames fields in the error
- * (e.g. snake_case parameters).
+ * (e.g. snake_case parameters). `0` in `expectedExitCodes` is accepted and dropped (#332).
  */
 export function readCommandIntent(args: unknown, names: Partial<Record<CommandIntentField, string>> = {}): { intent: CommandIntent; error?: string } {
   const input = withoutAbsentIntent((args && typeof args === "object" ? args : {}) as Record<string, unknown>);
@@ -138,7 +174,7 @@ export function readCommandIntent(args: unknown, names: Partial<Record<CommandIn
   if (codes !== undefined) {
     if (!Array.isArray(codes) || codes.length === 0 || codes.length > MAX_EXPECTED_EXIT_CODES ||
       !codes.every((code) => Number.isInteger(code) && code >= 1 && code <= 255) || new Set(codes).size !== codes.length) {
-      return { intent: {}, error: `${names.expectedExitCodes ?? "expectedExitCodes"} must be 1-${MAX_EXPECTED_EXIT_CODES} distinct integers from 1 to 255` };
+      return { intent: {}, error: `${names.expectedExitCodes ?? "expectedExitCodes"} must be 1-${MAX_EXPECTED_EXIT_CODES} distinct integers from 1 to 255 (0 is allowed and ignored)` };
     }
     intent.expectedExitCodes = [...codes] as number[];
   }

package/src/shared-log-utils.ts

@@ -819,29 +819,22 @@ export interface OutputControls {
   maxBytes?: unknown;
   /** Raw requested line count (canonical `lines`, else deprecated `tail_lines`). */
   lines?: unknown;
-  /** Deprecated alias names the caller used (whether or not the canonical name won). */
-  deprecated: string[];
 }
 
 /**
  * Resolve output-control parameters. Both spellings work; when both are given
- * the canonical name wins. Values are returned unvalidated so each surface
- * keeps its own defaults and hard caps.
+ * the canonical name wins. An explicit `null` is "not given", so a null
+ * canonical value never hides an alias value (#332). Values are returned
+ * unvalidated so each surface keeps its own defaults and hard caps.
  */
 export function readOutputControls(params: unknown): OutputControls {
   const p = (params && typeof params === "object" ? params : {}) as Record<string, unknown>;
-  const deprecated: string[] = [];
-  const pick = (canonical: keyof typeof OUTPUT_CONTROL_ALIASES): unknown => {
-    const alias = OUTPUT_CONTROL_ALIASES[canonical];
-    if (p[alias] !== undefined) deprecated.push(alias);
-    return p[canonical] !== undefined ? p[canonical] : p[alias];
-  };
+  const pick = (canonical: keyof typeof OUTPUT_CONTROL_ALIASES): unknown => p[canonical] ?? p[OUTPUT_CONTROL_ALIASES[canonical]] ?? undefined;
   const maxBytes = pick("max_bytes");
   const lines = pick("lines");
   return {
     ...(maxBytes !== undefined ? { maxBytes } : {}),
     ...(lines !== undefined ? { lines } : {}),
-    deprecated,
   };
 }
 
@@ -851,7 +844,8 @@ export type OutputInclude = (typeof OUTPUT_INCLUDE_VALUES)[number];
 
 /** Parse an `include` request into known values and unknown ones (both deduplicated). */
 export function readOutputInclude(value: unknown): { include: Set<OutputInclude>; unknown: string[] } {
-  const raw = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
+  // Any other non-null value (a number, boolean, or object) is one unknown entry, never silently nothing (#332).
+  const raw = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : value == null ? [] : [value];
   const include = new Set<OutputInclude>();
   const unknown: string[] = [];
   for (const entry of raw) {

package/src/shared-navigator.ts

@@ -93,8 +93,12 @@ type NavigatorState = {
   mainListCloseArmTimer?: ReturnType<typeof setTimeout>;
   mainListDeadlineScheduler?: RenderScheduler;
   editorComponent?: Component;
+  /** The editor Pi currently has mounted (the wrapper the factory returned last). */
+  editorFocusTarget?: unknown;
   detailOverlayRows?: number;
   dispose?: () => void;
+  /** The mounted detail overlay, reused instead of stacking a second one. */
+  overlay?: { showDetail(navigatorId: string): void; focus(): void };
 };
 
 const GLOBAL_KEY = Symbol.for("pi-better-harness.navigator.state");
@@ -199,6 +203,7 @@ export function disposeBackgroundWorkNavigator(ctx?: ExtensionContext): void {
   const s = state();
   try { s.dispose?.(); } catch { /* ignore */ }
   s.dispose = undefined;
+  s.overlay = undefined;
   stopMainListWidget();
   const activeCtx = ctx ?? s.uiCtx;
   s.uiCtx = undefined;
@@ -627,7 +632,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;
-  return new Proxy(inner, {
+  const proxy = new Proxy(inner, {
     get(target, prop) {
       if (prop === "handleInput") {
         return (data: string) => {
@@ -644,12 +649,24 @@ function wrapEditor(inner: any, deps: HostDeps): unknown {
       return Reflect.set(target, prop, value);
     },
   });
+  // Pi mounts and focuses whatever the factory returns; an extension that
+  // re-installs the editor replaces it, so this always names the live one.
+  state().editorFocusTarget = proxy;
+  return proxy;
 }
 
 function handleMainListInput(data: string, deps: HostDeps): boolean {
   const s = state();
   const rows = listRows();
-  if (rows.length === 0) return false;
+  if (rows.length === 0) {
+    // Every row is gone, but an overlay that lost focus may still be mounted: Esc still closes it.
+    if (s.overlay && deps.matchKey(data, "escape")) {
+      unfocusMainList();
+      dismissOverlay();
+      return true;
+    }
+    return false;
+  }
   if (!s.mainListFocused) {
     if (!deps.isOpenTrigger(data)) return false;
     focusMainList();
@@ -673,7 +690,10 @@ function handleMainListInput(data: string, deps: HostDeps): boolean {
   }
   if (deps.matchKey(data, "enter")) {
     const selected = selectedMainListRow();
-    if (selected?.parentRow) unfocusMainList();
+    if (selected?.parentRow) {
+      unfocusMainList();
+      dismissOverlay();
+    }
     else openNavigator();
     return true;
   }
@@ -683,11 +703,19 @@ function handleMainListInput(data: string, deps: HostDeps): boolean {
   }
   if (deps.matchKey(data, "escape") || deps.isOpenTrigger(data)) {
     unfocusMainList();
+    dismissOverlay();
     return true;
   }
   return false;
 }
 
+/** Close a detail overlay that is still mounted while the editor has focus. */
+function dismissOverlay(): void {
+  const s = state();
+  if (!s.overlay) return;
+  try { s.dispose?.(); } catch { /* ignore */ }
+}
+
 function handleMainListCloseKey(): void {
   const row = selectedMainListRow();
   if (!row || row.parentRow) return;
@@ -721,20 +749,54 @@ function openNavigator(): void {
   const rows = listRows();
   if (rows.length === 0) return;
   const selectedId = selectedMainListRow()?.navigatorId ?? rows[0]!.navigatorId;
+  // An overlay that lost focus (another UI took it and handed it to the editor)
+  // is still mounted: switch its detail and focus it rather than stacking a
+  // second overlay over it, whose Esc would only reveal the stale one below.
+  const mounted = s.overlay;
+  if (mounted) {
+    // showDetail may close the overlay (and clear s.overlay); focus() is then a no-op.
+    mounted.showDetail(selectedId);
+    mounted.focus();
+    return;
+  }
   try {
     try { s.dispose?.(); } catch { /* ignore */ }
     s.dispose = undefined;
     let disposeToken: (() => void) | undefined;
+    let overlayRef: NavigatorState["overlay"];
+    let handle: { focus?(): void; unfocus?(options?: { target: unknown }): void } | undefined;
+    const release = () => {
+      if (overlayRef && s.overlay === overlayRef) s.overlay = undefined;
+    };
     const opened = (ctx.ui as any).custom((tui: any, theme: any, _keybindings: any, done: (v: null) => void) => {
-      const component = createOverlayComponent(rows, deps, tui, theme, done, () => {
+      const component = createOverlayComponent(rows, deps, tui, theme, (value) => {
+        release();
+        // 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.
+        const liveEditor = s.editorFocusTarget;
+        if (liveEditor) {
+          try { handle?.unfocus?.({ target: liveEditor }); } catch { /* ignore */ }
+        }
+        done(value);
+      }, () => {
         s.lastHint = undefined;
         refreshBackgroundWorkNavigator(ctx);
       }, selectedId);
-      disposeToken = () => component.dispose();
+      overlayRef = {
+        showDetail: (navigatorId) => component.showDetail(navigatorId),
+        focus: () => {
+        if (s.overlay !== overlayRef) return;
+        try { handle?.focus?.(); } catch { /* ignore */ }
+      },
+      };
+      s.overlay = overlayRef;
+      disposeToken = () => component.dismiss();
       s.dispose = disposeToken;
       return component;
-    }, { overlay: true, overlayOptions: detailOverlayOptions });
+    }, { overlay: true, overlayOptions: detailOverlayOptions, onHandle: (h: typeof handle) => { handle = h; } });
     const clear = () => {
+      release();
       if (s.dispose === disposeToken) s.dispose = undefined;
     };
     void Promise.resolve(opened).then(clear, clear);
@@ -750,16 +812,16 @@ function createOverlayComponent(
   theme: { fg?(color: string, value: string): string } | undefined,
   done: (v: null) => void,
   onClosed: () => void,
-  initialDetailId?: string,
+  initialDetailId: string,
 ) {
+  // The overlay only ever shows one row's detail; the rail below it is the list.
   const overlayState: OverlayState = { rows: initialRows, selected: 0 };
-  let mode: "list" | "detail" = initialDetailId ? "detail" : "list";
   let logTailRows: number = DEFAULT_LOG_TAIL_ROWS;
   const expandedSections = new Set<string>();
-  let detailId: string | null = initialDetailId ?? null;
-  let detail: BackgroundWorkDetail | null = detailId ? (detailFor(detailId, Date.now(), { logTailLines: logTailRows }) ?? null) : null;
+  let detailId: string = initialDetailId;
+  let detail: BackgroundWorkDetail | null = detailFor(detailId, Date.now(), { logTailLines: logTailRows }) ?? null;
   applyDefaultExpandedSections(detail, expandedSections);
-  if (detailId) {
+  {
     const idx = overlayState.rows.findIndex((row) => row.navigatorId === detailId);
     if (idx >= 0) overlayState.selected = idx;
   }
@@ -776,7 +838,7 @@ function createOverlayComponent(
   }
 
   const detailScheduler = createRenderScheduler(() => {
-    if (!detailId || mode !== "detail" || closed) return;
+    if (closed) return;
     detail = detailFor(detailId, Date.now(), { logTailLines: logTailRows }) ?? detail;
     requestRender();
     startDetailTimer();
@@ -837,29 +899,11 @@ function createOverlayComponent(
     expandedSections.clear();
     detail = detailFor(row.navigatorId, Date.now(), { logTailLines: logTailRows }) ?? fallbackDetail(row);
     applyDefaultExpandedSections(detail, expandedSections);
-    mode = "detail";
     startDetailTimer();
     requestRender();
   }
 
-  if (detailId) startDetailTimer();
-
-  function leaveDetail(): void {
-    if (mode !== "detail") return;
-    const viewedId = detailId;
-    clearCloseArm();
-    stopDetailTimer();
-    mode = "list";
-    detail = null;
-    detailId = null;
-    expandedSections.clear();
-    refreshRows();
-    if (viewedId) {
-      const idx = overlayState.rows.findIndex((row) => row.navigatorId === viewedId);
-      if (idx >= 0) overlayState.selected = idx;
-    }
-    requestRender();
-  }
+  startDetailTimer();
 
   function close(): void {
     if (closed) return;
@@ -871,20 +915,28 @@ function createOverlayComponent(
 
   function handleCloseKey(): void {
     const row = selectedRow();
-    if (!row) return;
+    if (!row || row.parentRow) return;
     const now = Date.now();
     if (closeArm?.id === row.navigatorId && now >= closeArm.armedAt && now < closeArm.armedAt + CLOSE_ARM_MS) {
       clearCloseArm();
+      const before = overlayState.rows;
+      const closedIdx = overlayState.selected;
       closeFor(row);
-      if (mode === "detail") {
-        stopDetailTimer();
-        mode = "list";
-        detail = null;
-        detailId = null;
-      }
-      refreshRows();
+      stopDetailTimer();
+      const after = listRows();
+      const nextId = neighbourCloseTarget(before, closedIdx, row.navigatorId, after);
       onClosed();
-      requestRender();
+      if (!nextId) {
+        // Nothing left to show: hand the keyboard back to the editor.
+        unfocusMainList();
+        close();
+        return;
+      }
+      state().mainListSelectedId = nextId;
+      overlayState.rows = after;
+      overlayState.selected = Math.max(0, after.findIndex((candidate) => candidate.navigatorId === nextId));
+      refreshMainListWidget();
+      openDetail();
       return;
     }
     clearCloseArm();
@@ -903,18 +955,16 @@ function createOverlayComponent(
   return {
     render(width: number) {
       refreshRows();
-      const railLines = mode === "detail"
-        ? buildMainListLines(overlayState.rows, width, deps.truncate, fg, {
-            selectedId: selectedRow()?.navigatorId,
-            focused: true,
-          })
-        : [];
-      const editorLines = mode === "detail" ? renderEditorLines(width) : [];
+      const railLines = buildMainListLines(overlayState.rows, width, deps.truncate, fg, {
+        selectedId: selectedRow()?.navigatorId,
+        focused: true,
+      });
+      const editorLines = renderEditorLines(width);
       const bottomLines = [...railLines, ...editorLines];
       const overlayRows = state().detailOverlayRows;
       const detailRows = overlayRows === undefined ? undefined : Math.max(1, overlayRows - bottomLines.length);
       let contentLines: string[];
-      if (mode === "detail" && detail?.transcript && deps.createTranscriptComponent) {
+      if (detail?.transcript && deps.createTranscriptComponent) {
         if (transcriptDetail !== detail || !transcriptComponent) {
           transcriptDetail = detail;
           transcriptComponent = deps.createTranscriptComponent(detail, theme);
@@ -930,15 +980,13 @@ function createOverlayComponent(
       } else {
         transcriptDetail = null;
         transcriptComponent = null;
-        contentLines = mode === "detail"
-          ? buildDetailLines(detail, width, deps.truncate, fg, { expandedSections, logTailRows, minRows: detailRows, maxRows: detailRows, bottomFooter: false })
-          : buildListLines(overlayState, width, deps.truncate, fg);
+        contentLines = buildDetailLines(detail, width, deps.truncate, fg, { expandedSections, logTailRows, minRows: detailRows, maxRows: detailRows, bottomFooter: false });
       }
-      if (mode !== "detail") return contentLines;
-      if (detailRows === undefined) return [...contentLines, ...bottomLines];
+      if (overlayRows === undefined || detailRows === undefined) return [...contentLines, ...bottomLines];
       const fittedContent = contentLines.slice(0, detailRows);
       while (fittedContent.length < detailRows) fittedContent.push("");
-      return [...fittedContent, ...bottomLines];
+      // A terminal shorter than rail + editor keeps the bottom rows (the input frame) and drops the top.
+      return [...fittedContent, ...bottomLines].slice(-Math.max(1, overlayRows));
     },
     handleInput(data: string) {
       if (closed) return;
@@ -946,56 +994,53 @@ function createOverlayComponent(
         handleCloseKey();
         return;
       }
-      if (mode === "detail") {
-        if (deps.matchKey(data, "up")) {
-          selectOverlayRow(overlayState.selected - 1);
-          activateSelectedRow();
-        }
-        else if (deps.matchKey(data, "down")) {
-          selectOverlayRow(overlayState.selected + 1);
-          activateSelectedRow();
-        }
-        else if (deps.matchKey(data, "left")) {
-          const mainIdx = overlayState.rows.findIndex((row) => row.parentRow && row.id === "main");
-          if (mainIdx >= 0) selectOverlayRow(mainIdx);
-          close();
-        }
-        else if (deps.matchKey(data, "enter")) {
-          const row = selectedRow();
-          if (row?.parentRow || row?.navigatorId !== detailId) openDetail();
-          else {
-            const sectionId = firstToggleableSectionId(detail);
-            if (!sectionId) return;
-            if (expandedSections.has(sectionId)) expandedSections.delete(sectionId);
-            else expandedSections.add(sectionId);
-            requestRender();
-          }
-        }
-        else if (data === "l" || data === "L") {
-          logTailRows = cycleLogTailRows(logTailRows);
-          if (detailId) detail = detailFor(detailId, Date.now(), { logTailLines: logTailRows }) ?? detail;
+      if (deps.matchKey(data, "up")) {
+        selectOverlayRow(overlayState.selected - 1);
+        activateSelectedRow();
+      }
+      else if (deps.matchKey(data, "down")) {
+        selectOverlayRow(overlayState.selected + 1);
+        activateSelectedRow();
+      }
+      else if (deps.matchKey(data, "left")) {
+        const mainIdx = overlayState.rows.findIndex((row) => row.parentRow && row.id === "main");
+        if (mainIdx >= 0) selectOverlayRow(mainIdx);
+        close();
+      }
+      else if (deps.matchKey(data, "enter")) {
+        const row = selectedRow();
+        if (row?.parentRow || row?.navigatorId !== detailId) openDetail();
+        else {
+          const sectionId = firstToggleableSectionId(detail);
+          if (!sectionId) return;
+          if (expandedSections.has(sectionId)) expandedSections.delete(sectionId);
+          else expandedSections.add(sectionId);
           requestRender();
         }
-        else if (deps.matchKey(data, "escape")) {
-          unfocusMainList();
-          close();
-        }
-        return;
       }
-      if (deps.matchKey(data, "up")) {
-        overlayState.selected = Math.max(0, overlayState.selected - 1);
-        clearCloseArm();
+      else if (data === "l" || data === "L") {
+        logTailRows = cycleLogTailRows(logTailRows);
+        if (detailId) detail = detailFor(detailId, Date.now(), { logTailLines: logTailRows }) ?? detail;
         requestRender();
-      } else if (deps.matchKey(data, "down")) {
-        overlayState.selected = Math.min(Math.max(0, overlayState.rows.length - 1), overlayState.selected + 1);
-        clearCloseArm();
-        requestRender();
-      } else if (deps.matchKey(data, "enter")) {
-        openDetail();
-      } else if (deps.matchKey(data, "escape")) {
+      }
+      else if (deps.matchKey(data, "escape")) {
+        unfocusMainList();
         close();
       }
     },
+    /** Show another row's detail in this overlay (the main list moved while it was unfocused). */
+    showDetail(navigatorId: string) {
+      if (closed) return;
+      refreshRows();
+      const idx = overlayState.rows.findIndex((row) => row.navigatorId === navigatorId);
+      if (idx < 0) return;
+      overlayState.selected = idx;
+      state().mainListSelectedId = navigatorId;
+      if (overlayState.rows[idx]!.parentRow) close();
+      else openDetail();
+    },
+    /** Close the overlay (done), e.g. when the navigator is disposed. */
+    dismiss() { close(); },
     invalidate() { transcriptComponent?.invalidate(); },
     dispose() {
       clearCloseArm();
@@ -1004,6 +1049,30 @@ function createOverlayComponent(
   };
 }
 
+/**
+ * After a confirmed close, the row whose detail the overlay shows next: the
+ * nearest closable row below the closed one in the pre-close order, else the
+ * nearest above it. `undefined` means nothing closable remains.
+ */
+function neighbourCloseTarget(
+  before: ReadonlyArray<{ navigatorId: string; parentRow?: boolean }>,
+  closedIdx: number,
+  closedId: string,
+  after: ReadonlyArray<{ navigatorId: string; parentRow?: boolean }>,
+): string | undefined {
+  const remaining = new Set(after.filter((row) => !row.parentRow && row.navigatorId !== closedId).map((row) => row.navigatorId));
+  for (let i = closedIdx + 1; i < before.length; i += 1) {
+    const id = before[i]?.navigatorId;
+    if (id && remaining.has(id)) return id;
+  }
+  for (let i = Math.min(closedIdx, before.length) - 1; i >= 0; i -= 1) {
+    const id = before[i]?.navigatorId;
+    if (id && remaining.has(id)) return id;
+  }
+  // Rows that appeared since the last render.
+  return after.find((row) => remaining.has(row.navigatorId))?.navigatorId;
+}
+
 function buildTranscriptDetailLines(
   detail: BackgroundWorkDetail,
   transcriptLines: string[],
@@ -1088,33 +1157,6 @@ function fallbackDetail(row: InternalRow): BackgroundWorkDetail {
   };
 }
 
-function buildListLines(nav: OverlayState, width: number, truncate: (s: string, width: number) => string, fg: (color: string, value: string) => string): string[] {
-  const lines: string[] = [];
-  lines.push(rule(`Work · ${nav.rows.length}`, width));
-  const selected = nav.rows[nav.selected];
-  const closeAction = selected ? "x close" : null;
-  lines.push(dim(`   ${["↑↓ select", "Enter view", closeAction, "Esc close"].filter(Boolean).join(" · ")}`, fg));
-  lines.push("");
-  if (nav.rows.length === 0) lines.push("   (no work)");
-  let lastProvider = "";
-  for (let i = 0; i < nav.rows.length; i += 1) {
-    const row = nav.rows[i]!;
-    if (row.providerLabel !== lastProvider) {
-      lines.push(dim(section(row.providerLabel, width), fg));
-      lastProvider = row.providerLabel;
-    }
-    const prefix = i === nav.selected ? fg("accent", "›  ") : "   ";
-    const status = fg(toneColor(row.statusTone, row.status), row.status);
-    const facts = (row.facts ?? []).filter(Boolean).slice(0, 2);
-    const suffix = facts.length ? ` · ${facts.join(" · ")}` : "";
-    lines.push(`${prefix}${row.name || row.id} · ${row.kind} · ${row.elapsed} · ${row.primary} · ${status}${suffix}`);
-    if (row.secondary) lines.push(`      ${row.secondary}`);
-  }
-  lines.push("");
-  lines.push(dim(rule("", width), fg));
-  return lines.map((line) => safeTruncate(line, width, truncate));
-}
-
 function buildDetailLines(
   detail: BackgroundWorkDetail | null,
   width: number,
@@ -1173,7 +1215,9 @@ function buildDetailLines(
       lines.push(`   ${preview} ${folded}`);
     } else {
       const wrapped = wrapEvidenceText(body, width - 6);
-      const shown = wrapped.slice(0, tailRows);
+      let shown = wrapped.slice(0, tailRows);
+      // Same budget as the tail branch: the header row and the trailing blank come out of maxRows too.
+      if (options.maxRows !== undefined) shown = shown.slice(0, Math.max(1, options.maxRows - lines.length - 2));
       lines.push(dim(section(`${detail.evidence.label} · showing ${shown.length}/${wrapped.length} rows`, width), fg));
       for (const raw of shown) lines.push(raw ? `   ${raw}` : "   ");
     }

package/src/shared-sandbox-core.ts

@@ -414,13 +414,22 @@ function lexicalAndCanonical(home: string, name: string, seams: SandboxSeams): s
 
 /**
  * Every symlink directory entry met while resolving `path`, component by
- * component (as `readlink` would follow them). A chain such as
+ * component (as `readlink` would follow them), plus where a dangling chain
+ * would land. A chain such as
  * `~/.zshrc -> ~/.dotfiles/zshrc -> ~/dotfiles/zshrc` has an intermediate link
  * in a removable directory; replacing it would retarget the protected entry, so
- * each hop the user could replace is protected too. Bounded: a loop or more
- * than 40 hops stops the walk (such a path resolves to nothing).
+ * each hop the user could replace is protected too. When a followed link
+ * points at something missing, creating it would give the entry content, so
+ * the first missing component (which covers every missing directory below it)
+ * and the full path it would resolve to are protected as well. Bounded: a loop
+ * or more than 40 hops stops the walk (such a path resolves to nothing).
  */
 function symlinkHops(path: string): string[] {
+    const { hops, unresolved } = walkSymlinks(path);
+    return [...hops, ...unresolved];
+}
+
+function walkSymlinks(path: string): { hops: string[]; unresolved: string[] } {
     const hops: string[] = [];
     const seen = new Set<string>();
     let followed = 0;
@@ -433,7 +442,13 @@ function symlinkHops(path: string): string[] {
         if (component === "..") { current = dirname(current); continue; }
         const entry = join(current, component);
         let link: boolean;
-        try { link = lstatSync(entry).isSymbolicLink(); } catch { break; }
+        try {
+            link = lstatSync(entry).isSymbolicLink();
+        } catch {
+            // Missing. Only a followed link makes this a dangling target; a
+            // plain absent path is guarded as it is.
+            return { hops, unresolved: followed ? [...new Set([entry, resolve(entry, ...pending)])] : [] };
+        }
         if (!link) { current = entry; continue; }
         if (++followed > 40 || seen.has(entry)) break;
         seen.add(entry);
@@ -448,7 +463,12 @@ function symlinkHops(path: string): string[] {
             pending = [...target.split(sep), ...pending];
         }
     }
-    return hops;
+    return { hops, unresolved: [] };
+}
+
+/** Whether a symlink resolves to nothing: dangling (ENOENT), or looping or over 40 hops (ELOOP). */
+function unresolvable(path: string): boolean {
+    try { statSync(path); return false; } catch { return true; }
 }
 
 function broadCredentialPaths(home: string, seams: SandboxSeams): string[] {
@@ -1296,7 +1316,10 @@ function maskSources(profilePath: string): { directory: string; file: string } {
  * home itself stay read-only, so sibling repositories cannot even be edited in
  * place there. Credentials are masked by empty mode-000 mounts; code that runs
  * later and caller-denied paths are read-only binds. Every writable bind and
- * protected leaf is a mount point, which Linux refuses to rename.
+ * protected leaf is a mount point, which Linux refuses to rename. A protected
+ * symlink inside a writable directory (a stow link in `~/.config`) makes that
+ * directory read-only with each existing entry bound writable again, so only
+ * new top-level entries there are refused.
  */
 function buildLinuxBroadCommand(
     bwrap: string,
@@ -1347,15 +1370,38 @@ function buildLinuxBroadCommand(
     const readOnly = new Set<string>();
     const directoryLocation = (path: string) => [...DIRECTORY_LOCATIONS]
         .some((name) => canonicalizePath(join(broad.home, name), seams) === 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));
     const guard = (path: string, hide: boolean) => {
         let directory: boolean | undefined;
-        if (canonicalizePath(path, seams) !== path) {
+        let link = false;
+        try { link = lstatSync(path).isSymbolicLink(); } catch { /* absent or intermediate link */ }
+        if (canonicalizePath(path, seams) !== path || (link && unresolvable(path))) {
             // A literal twin of a canonical deny entry: its target is guarded on
-            // its own. A symlink leaf inside a writable root could be replaced,
-            // so its directory becomes read-only; home itself already is.
-            let link = false;
-            try { link = lstatSync(path).isSymbolicLink(); } catch { /* absent or intermediate link */ }
-            if (link && dirname(path) !== broad.home && writableAt(dirname(path))) readOnly.add(dirname(path));
+            // its own. A looping link resolves to nothing (ELOOP), and a dangling
+            // one's missing target is guarded below, so only the link itself
+            // needs guarding here. A symlink leaf inside a writable root could be
+            // replaced, so its directory is protected; home already is.
+            if (link && dirname(path) !== broad.home && writableAt(dirname(path))) linkParents.add(dirname(path));
+            return;
+        }
+        if (danglingTargets.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.
+            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);
+            }
             return;
         }
         if (!exists(path)) {
@@ -1384,19 +1430,37 @@ function buildLinuxBroadCommand(
     for (const path of writeDenied) guard(path, false);
     if (permissions.projectFiles === "read") readOnly.add(project);
 
+    // A read-only link parent keeps its existing entries writable: each one is
+    // bound back read-write (a mount point, so it cannot be renamed away either).
+    // Only new top-level entries in that directory are lost. Protected entries
+    // keep their own mounts, and a symlink entry is never bound: a bind follows
+    // it, and writes through it already meet its target's own mounts.
+    const rebound = new Set<string>();
+    for (const parent of linkParents) readOnly.add(parent);
+    for (const parent of linkParents) {
+        for (const entry of list(parent)) {
+            if (entry.symlink) continue;
+            const path = join(parent, entry.name);
+            if (insideProtected(path) || readOnly.has(path) || writable.has(path)) continue;
+            rebound.add(path);
+        }
+    }
+
     // Intermediate directories between a writable root and anything bound
     // inside it become mount points too, so none of them can be renamed away.
     const anchors = new Set<string>();
     for (const target of [...writableRoots, ...readOnly, ...hidden.map((entry) => entry.path)]) {
         for (const parent of protectedAncestors([target])) {
             if (writableRoots.some((root) => root !== parent && contains(root, parent)) &&
-                !readOnly.has(parent) && !writable.has(parent)) anchors.add(parent);
+                !readOnly.has(parent) && !writable.has(parent) && !rebound.has(parent)) anchors.add(parent);
         }
     }
-    type Mount = { option: "--bind" | "--ro-bind"; source: string; path: string; rank: number };
+    type Mount = { option: "--bind" | "--bind-try" | "--ro-bind"; source: string; path: string; rank: number };
     const mounts: Mount[] = [
         ...[...anchors].map((path) => ({ option: "--bind" as const, source: path, path, rank: 0 })),
         ...writableRoots.map((path) => ({ option: "--bind" as const, source: path, path, rank: 1 })),
+        // `-try`: an entry removed before a resumed launch stays read-only instead of failing it.
+        ...[...rebound].map((path) => ({ option: "--bind-try" as const, source: path, path, rank: 1 })),
         ...[...readOnly].map((path) => ({ option: "--ro-bind" as const, source: path, path, rank: 2 })),
         ...hidden.map(({ path, source }) => ({ option: "--ro-bind" as const, source, path, rank: 3 })),
     ].sort((a, b) => a.path.length - b.path.length || a.rank - b.rank);

package/src/tools.ts

@@ -71,7 +71,7 @@ const RemoteSchema = Type.Object({
 // TypeBox union, and a Null-first union reports a malformed array as "must be null".
 const IntentFields = {
   operation_id: Type.Optional(Type.Unsafe<string | null>({ anyOf: [{ type: "null" }, { type: "string" }], description: "Optional stable id (letters, digits, . _ : / -; up to 64) for one logical operation. Reuse it when you retry with a changed command, scope, or timeout: when a later task with the same operation_id succeeds, earlier failures of that operation in this session are recovered." })),
-  expected_exit_codes: Type.Optional(Type.Unsafe<number[] | null>({ anyOf: [{ type: "array", items: { type: "integer", minimum: 1, maximum: 255 }, minItems: 1, maxItems: 16 }, { type: "null" }], description: "Optional distinct non-zero exit codes that are intentional for this command (e.g. [1] for a no-match probe). Declared before launch; recorded as expected failures, not incidents needing action. Signals and timeouts are never expected." })),
+  expected_exit_codes: Type.Optional(Type.Unsafe<number[] | null>({ anyOf: [{ type: "array", items: { type: "integer", minimum: 0, maximum: 255 }, minItems: 1, maxItems: 16 }, { type: "null" }], description: "Optional distinct non-zero exit codes that are intentional for this command (e.g. [1] for a no-match probe). 0 is allowed and ignored: exit 0 is already success. Declared before launch; recorded as expected failures, not incidents needing action. Signals and timeouts are never expected." })),
 };
 
 const CommandFields = {