pi-pier 0.2.6 → 0.3.0

package/src/session-tail.ts

@@ -9,7 +9,7 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { sessionDirCandidates, sessionDirName } from './storage-layout.ts';
+import { piSessionDirCandidates, sessionDirName } from './storage-layout.ts';
 
 export { sessionDirName };
 
@@ -90,6 +90,34 @@ export function hasAssistantAfter(
     return !!m && m.role === 'assistant' && (typeof m.timestamp === 'number' ? m.timestamp : 0) >= sinceTs;
   });
 }
+/**
+ * Return whether the NEWEST assistant message after `sinceTs` ended its turn.
+ *
+ * Why (A16): a worker sitting between tool calls (tool result already written, next assistant
+ * message still streaming) has "an assistant message" but has NOT finished. Treating any assistant
+ * message as activity made the poller announce such workers as finished — three real workers were
+ * declared settled while still working on 2026-09-13 and one was later closed mid-task by GC.
+ *
+ * `stopReason === 'toolUse'` means the model requested tools, so the turn continues; a non-string
+ * stopReason (message still streaming / older shapes) is treated as "not ended" on purpose — the
+ * cost of waiting is small, the cost of a false settlement is losing supervision of live work.
+ */
+export function lastAssistantTurnEnded(
+  entries: readonly SessionEntryLike[],
+  sinceTs: number,
+): boolean {
+  let newest: { ts: number; stopReason: unknown } | null = null;
+  for (const entry of entries) {
+    const m = messageOf(entry);
+    if (!m || m.role !== 'assistant') continue;
+    const ts = typeof m.timestamp === 'number' ? m.timestamp : 0;
+    if (ts < sinceTs) continue;
+    if (!newest || ts >= newest.ts) newest = { ts, stopReason: m.stopReason };
+  }
+  if (!newest) return false;
+  const sr = newest.stopReason;
+  return typeof sr === 'string' && sr !== 'toolUse' && sr !== 'pending';
+}
 /**
  * Return whether an initiated toolCall still lacks a result after injection (for example,
  * ask_user_question waiting on human input), meaning settlement has not actually completed
@@ -115,10 +143,37 @@ export function hasPendingToolCall(entries: readonly SessionEntryLike[], sinceTs
 
 
 
-/** Newest `limit` session files under cwd's session dir (new encoding, then legacy). */
+/** Derived settlement state of one child session, from the inject point onward. */
+export interface SubSessionState {
+  text: string | null;
+  pendingTool: boolean;
+  activity: boolean;
+  turnEnded: boolean;
+}
+
+/**
+ * Derive the settlement state from already-parsed entries.
+ *
+ * Closing text is by construction terminal (lastAssistantText requires stopReason 'stop').
+ * A16: an assistant message alone is not a settlement; the turn must have ENDED.
+ */
+export function deriveSubSessionState(
+  entries: readonly SessionEntryLike[],
+  sinceTs: number,
+): SubSessionState {
+  const r = lastAssistantText(entries, { sinceTs });
+  if (r?.text) return { text: r.text, pendingTool: false, activity: true, turnEnded: true };
+  if (hasPendingToolCall(entries, sinceTs)) return { text: null, pendingTool: true, activity: true, turnEnded: false };
+  if (hasAssistantAfter(entries, sinceTs)) {
+    return { text: null, pendingTool: false, activity: true, turnEnded: lastAssistantTurnEnded(entries, sinceTs) };
+  }
+  return { text: null, pendingTool: false, activity: false, turnEnded: false };
+}
+
+/** Newest `limit` session files under cwd's session dir (pi core's name first, then pier's old encodings). */
 export function listSessionFiles(cwd: string, agentDir: string, limit = 4): string[] {
   const files: Array<{ file: string; mtime: number }> = [];
-  for (const name of sessionDirCandidates(cwd)) {
+  for (const name of piSessionDirCandidates(cwd)) {
     const dir = path.join(agentDir, name);
     let names: string[];
     try {
@@ -142,11 +197,11 @@ export function listSessionFiles(cwd: string, agentDir: string, limit = 4): stri
 
 /**
  * Locate a session file by id (`<ts>_<id>.jsonl`).
- * Searches the new encoding dir first, then the legacy flattened dir.
+ * Searches pi core's own directory name first, then pier's legacy flattened dirs.
  */
 export function sessionFileById(cwd: string, agentDir: string, id: string): string | null {
   const suffix = `_${id}.jsonl`;
-  for (const name of sessionDirCandidates(cwd)) {
+  for (const name of piSessionDirCandidates(cwd)) {
     const dir = path.join(agentDir, name);
     let names: string[];
     try {

package/src/settle-wake-core.ts

@@ -21,6 +21,8 @@ export const D96_REPEAT_NOTICE_MS = 10 * 60_000;
 export interface SettleWakeInput {
   /** stopReason of the last assistant turn before this settlement (unknown = null, treated as natural completion). */
   lastStopReason: string | null;
+  /** True when abort was triggered intentionally by internal mechanisms like OCC. */
+  intentionalAbort?: boolean;
   /** Background subagents still running (empty means none). */
   running: ReadonlyArray<{ paneId: string }>;
   /** Set key recorded for the previous D96 notice (none = null). */
@@ -41,7 +43,7 @@ export interface SettleWakePlan {
 }
 
 export function planSettleWake(input: SettleWakeInput): SettleWakePlan {
-  if (input.lastStopReason === ABORT_STOP_REASON) {
+  if (input.intentionalAbort || input.lastStopReason === ABORT_STOP_REASON) {
     return { wake: false, notice: false, noticeKey: input.lastNoticeKey, noticeAt: input.lastNoticeAt };
   }
   const key = input.running.length === 0 ? null : input.running.map((s) => s.paneId).sort().join(',');

package/src/slim-frame.ts

@@ -21,11 +21,16 @@
  * (done() is never called, leaving the Promise pending, swallowing rejection, and never awaiting it). If switching
  * pi sessions removes the overlay (resetExtensionUI), the static frame naturally exits without affecting the main
  * flow. PI_HERDR_SLIM_FRAME=0 is the escape hatch.
+ * Resize watchdog (D98): the component owns a SIGWINCH listener plus a 1s size poll that call tui.requestRender() on
+ * any PTY size change. Why: long-running sessions stop re-rendering on resize (observed in herdr — an idle master
+ * shrunk by heat reflow froze on a stale clipped frame: no todo, no title), so pi's own resize wiring cannot be relied
+ * on; columns/rows are read live per render, so one render is the whole fix. Stopped in dispose().
  */
 
 import { isArchived } from './stale-core.ts';
 import type { TodoItem } from './vocab.ts';
 import { anchorTodoRange, formatTodoSummary, renderTodoGroups } from './todo-window.ts';
+import { pierOption } from './pier-options.ts';
 
 /** Minimum usable TUI dimensions (pi interactive-mode layout: editor 3 rows + footer 1 + transcript ≥3 + spacing).
  * Below either threshold the pane cannot display a readable TUI, so the overlay covers it. */
@@ -38,6 +43,8 @@ export const SLIM_TODO_MIN_ROWS = 3;
 export const SLIM_TODO_MIN_COLS = 16;
 /** Empty-list copy: the pane is alive but has no plan yet (replaces a lone ·). */
 export const SLIM_EMPTY_COPY = 'no todos yet';
+/** D98: watchdog poll period — SIGWINCH covers the delivered signal; the poll covers lost ones (e.g. after suspend). */
+export const RESIZE_WATCHDOG_MS = 1_000;
 
 /** Visibility predicate (overlayOptions.visible invokes it on every render frame). */
 export function isSlimFrame(cols: number, rows: number): boolean {
@@ -227,6 +234,11 @@ class SlimFrameComponent {
   private cache: { width: number; lines: string[] } | null = null;
   private readonly tui: FrameTui;
   private readonly colorize: (s: string) => string;
+  /** D98 watchdog: last PTY size seen by onMaybeResized (re-seeded at watchdog start). */
+  private seenCols = 0;
+  private seenRows = 0;
+  private sigwinch: (() => void) | null = null;
+  private poll: NodeJS.Timeout | null = null;
 
   constructor(tui: FrameTui, colorize: (s: string) => string) {
     this.tui = tui;
@@ -271,13 +283,56 @@ class SlimFrameComponent {
 
   /** Reclaim the module singleton when pi tears down the overlay (session switch/exit), allowing re-registration. */
   dispose(): void {
+    this.stopResizeWatchdog();
     if (active === this) active = null;
   }
+
+  /** Live PTY size (pi-tui reads the same source on every render; an instance method so tests can stub it). */
+  viewportSize(): { cols: number; rows: number } {
+    return { cols: process.stdout.columns ?? 0, rows: process.stdout.rows ?? 0 };
+  }
+
+  /** D98: SIGWINCH handler and poll tick — exactly one requestRender per actual size change; the next render reads live sizes. */
+  readonly onMaybeResized = (): void => {
+    const { cols, rows } = this.viewportSize();
+    if (cols === this.seenCols && rows === this.seenRows) return;
+    this.seenCols = cols;
+    this.seenRows = rows;
+    this.tui.requestRender();
+  };
+
+  /** Start the D98 watchdog (idempotent). SIGWINCH covers the delivered signal; the poll covers lost ones. */
+  startResizeWatchdog(): void {
+    if (this.poll) return;
+    const size = this.viewportSize();
+    this.seenCols = size.cols;
+    this.seenRows = size.rows;
+    try {
+      process.on('SIGWINCH', this.onMaybeResized);
+      this.sigwinch = this.onMaybeResized;
+    } catch {
+      /* Platforms without a SIGWINCH mapping keep the poll only. */
+    }
+    this.poll = setInterval(this.onMaybeResized, RESIZE_WATCHDOG_MS);
+    this.poll.unref?.();
+  }
+
+  private stopResizeWatchdog(): void {
+    if (this.sigwinch) {
+      process.removeListener('SIGWINCH', this.sigwinch);
+      this.sigwinch = null;
+    }
+    if (this.poll) {
+      clearInterval(this.poll);
+      this.poll = null;
+    }
+  }
 }
 
 
-/** Test injection point (reset module state). */
+/** Test injection point (reset module state); dispose first so an undisposed component's watchdog cannot leak. */
 export function resetForTest(): void {
+  active?.dispose();
   active = null;
 }
 
@@ -289,7 +344,7 @@ let active: SlimFrameComponent | null = null;
  */
 export function registerSlimFrame(eventCtx: unknown): void {
   if (active) return;
-  if (process.env.PI_HERDR_SLIM_FRAME === '0') return;
+  if (pierOption('PIER_SLIM_FRAME') === '0') return;
   const ui = eventCtx !== null && typeof eventCtx === 'object' && 'ui' in eventCtx
     ? eventCtx.ui
     : null;
@@ -299,9 +354,11 @@ export function registerSlimFrame(eventCtx: unknown): void {
   try {
     // overlay: true keeps the floating layer from clearing the screen (pi ctx.ui.custom replaces the editor area by default, so cover it explicitly);
     // nonCapturing leaves the keyboard with the editor (typing in a focused narrow pane remains possible, and the expanded heat view hides the frame).
+    if (!custom) throw new Error('pi ui.custom unavailable');
     const pending = custom(
-      (tui, theme) => {
+      (tui: FrameTui, theme: { fg(color: string, text: string): string }) => {
         const comp = new SlimFrameComponent(tui, (s) => theme.fg('accent', s));
+        comp.startResizeWatchdog();
         active = comp;
         return comp;
       },

package/src/storage-layout.ts

@@ -43,6 +43,29 @@ export function sessionDirCandidates(cwd: string): readonly string[] {
   return next === prev ? [next] : [next, prev];
 }
 
+/**
+ * pi core's own session-directory encoding, byte-for-byte.
+ *
+ * Why: `<agentDir>/sessions/` is owned by pi core, which names it
+ * `--${cwd.replace(/^[/\\]/, '').replace(/[/\\:]/g, '-')}--` (strip ONE leading separator,
+ * then flatten `/` `\` `:` — note it does NOT escape `%` like `sessionDirName` does).
+ * Verified on this machine: `/Users/yehaoyu/Documents/pier` →
+ * `--Users-yehaoyu-Documents-pier--` (pier's own encodings produce `---Users-…--` and
+ * `--%2FUsers…--`, neither of which exists on disk).
+ */
+export function piCoreSessionDirName(cwd: string): string {
+  return `--${cwd.replace(/^[/\\]/, '').replace(/[/\\:]/g, '-')}--`;
+}
+
+/**
+ * Candidates for reading pi core's session dirs: pi core's exact name first, then pier's
+ * own historical encodings (they may hold stray dirs from earlier versions).
+ * Read-only on purpose: writes to `<agentDir>/sessions/` are pi core's business.
+ */
+export function piSessionDirCandidates(cwd: string): readonly string[] {
+  return [...new Set([piCoreSessionDirName(cwd), ...sessionDirCandidates(cwd)])];
+}
+
 /**
  * Directory to read/write under `parent`.
  * Existing legacy dirs win over a missing new dir so history is not split.

package/src/subagent-core.ts

@@ -91,6 +91,8 @@ export interface AliveProbe {
   agentStatus: string | null;
   /** Why: Preserve the established compatibility and safety behavior. */
   lastActivityMs: number | null;
+  /** Herdr 0.9.1: foreground working directory of the PTY process. */
+  foregroundCwd?: string | null;
 }
 
 /** Why: Preserve the established compatibility and safety behavior. */
@@ -368,7 +370,7 @@ export interface LaunchRuntime {
 export function buildLaunchParts(
   runtime: LaunchRuntime,
   opts: { resumeFile?: string | null; roleModel?: string | null; approve?: boolean } = {},
-  env: Pick<NodeJS.ProcessEnv, 'PI_HERDR_TUI'> = process.env,
+  env: { PI_HERDR_TUI?: string | undefined } = process.env,
 ): string[] {
   const parts = [runtime.nodePath, runtime.cliPath];
   if (opts.approve) parts.push('-a');

package/src/subagent-execute.ts

@@ -0,0 +1,328 @@
+/**
+ * Subagent `spawn` action (isolate worktree, pane launch, prompt injection, foreground wait).
+ *
+ * Why: the plugin entry keeps tool registration and lifecycle wiring; the spawn path is the one
+ * action with git, placement, injection, and settle branches, so it lives here as a unit.
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, stat as statCb } from 'node:fs';
+import { basename, dirname, join, resolve as pathResolve } from 'node:path';
+import { promisify } from 'node:util';
+import type { HerdrClientLike } from './herdr-client.ts';
+import { composeForRole } from './manifest-compose.ts';
+import { pipeNameFor, pipeRequestTo } from './pipe-channel.ts';
+import { platformPaths } from './platform-paths.ts';
+import { runtimePolicy } from './runtime-policy.ts';
+import {
+  FOREGROUND_POLL_MS,
+  planForegroundTick,
+  planIsolateRepoGuard,
+  planLaunchValidation,
+  planPatienceExpiry,
+} from './subagent-launch.ts';
+import {
+  Semaphore,
+  buildAliveNotice,
+  buildBlockedGateNotice,
+  buildIsolatePreamble,
+  classifyWorktreeZone,
+  formatSubagentResult,
+  isAlive,
+  isPathUnder,
+  makeProgressUpdate,
+  planIsolateWorktree,
+  type SubEntry,
+} from './subagent-core.ts';
+import type { HistoryEntry } from './history-store.ts';
+import type { GitIo } from './subagent-git-io.ts';
+import { sleep, type Poller } from './subagent-poll-loop.ts';
+import type { SessionIo } from './subagent-session-io.ts';
+import type { SpawnEnv, Spawner } from './subagent-spawn.ts';
+import { toolError } from './tool-error.ts';
+
+const statAsync = promisify(statCb);
+
+export interface SpawnActionHost {
+  client: HerdrClientLike;
+  env: SpawnEnv | null;
+  subSemaphore: Semaphore;
+  subs: Map<string, SubEntry>;
+  persistSubs(): void;
+  writeHistory(entry: SubEntry, patch?: Partial<HistoryEntry>, via?: string): void;
+  pendingIsolateBranches: Set<string>;
+  lastMachineInjectAt: Map<string, number>;
+  lastRequestIdByPane: Map<string, string>;
+  git: GitIo;
+  session: SessionIo;
+  spawn: Spawner;
+  poller: Poller;
+}
+
+export type SpawnAction = (
+  params: Record<string, unknown> | undefined,
+  toolCtx: unknown,
+  onUpdate?: (update: unknown) => void,
+) => Promise<unknown>;
+
+export function createSpawnAction(h: SpawnActionHost): SpawnAction {
+  const { client, env, git, subs } = h;
+  const { resolveSessionFile, collectFinalText, readAskFlag, probeAlive, subSessionState } = h.session;
+  const { spawnPaneInTaskTab, launchLine, waitSubReady } = h.spawn;
+  const { startPoller } = h.poller;
+
+  return async function executeSubagentSpawn(params, toolCtx, onUpdate) {
+    const launch = planLaunchValidation(params, client.available);
+    if (launch.kind === 'error') {
+      return toolError(launch.text);
+    }
+    const { spec, background, isolate, cwdParam, roleKind: kind, suggested, manifestRole, tab } = launch;
+    const masterCwd = (toolCtx as { cwd?: string }).cwd ?? process.cwd();
+    // Move taskId generation above the original spawn section because isolate planning needs taskHex; this is behavior-neutral.
+    const taskId = randomUUID();
+    // D98 2c: Create the isolate through pier's execFile git path (decision 1), not herdr's
+    // socket worktree.create, which has bootstrap races, missing root-pane env, worker/master
+    // workspace separation, and linked_worktree_source rejection. The model makes the decision; do not infer it.
+    let isolateMeta: SubEntry['isolate'] | null = null;
+    let cwd = masterCwd;
+    if (isolate) {
+      const baseSha = await git.runGit(masterCwd, ['rev-parse', 'HEAD']);
+      const isoGuard = planIsolateRepoGuard(baseSha);
+      if (isoGuard.kind === 'error') {
+        return toolError(isoGuard.text);
+      }
+      const sha = isoGuard.sha.trim();
+      const pierBranches = new Set(
+        ((await git.runGit(masterCwd, ['for-each-ref', '--format=%(refname:short)', 'refs/heads/pier/'])) ?? '')
+          .split('\n').filter(Boolean),
+      );
+      const worktrees = await git.listWorktrees(masterCwd);
+      const repoName = basename(worktrees[0] ?? masterCwd);
+      const plan = planIsolateWorktree({
+        description: spec.description,
+        taskHex: taskId.slice(0, 6),
+        existingPierBranches: pierBranches,
+      });
+      const wtPath = join(platformPaths.worktreeBaseDir, repoName, plan.worktreeDirName);
+      try {
+        mkdirSync(dirname(wtPath), { recursive: true }); // git worktree add does not create its parent directory, so a first run would fail.
+      } catch { /* Existing directory or permissions failure is handled by worktree add. */ }
+      // Keep the branch pending between worktree add and subs.set: the 2–3s readiness wait lets the ticker
+      // scan, and without this guard it could reclaim a new clean =HEAD-ancestor worktree as an orphan.
+      h.pendingIsolateBranches.add(plan.branch);
+      const added = await git.runGit(masterCwd, ['worktree', 'add', '-b', plan.branch, wtPath, sha]);
+      if (added === null) {
+        h.pendingIsolateBranches.delete(plan.branch);
+        return toolError(`Error: failed to create worktree ${wtPath} (branch ${plan.branch}) — run \`git worktree prune\` and retry if it reports stale entries`);
+      }
+      git.invalidateWorktreesCache(); // Invalidate the 5s cache so the zone classifier sees the new worktree immediately.
+      cwd = wtPath;
+      isolateMeta = { worktreePath: wtPath, branch: plan.branch, baseSha: sha, releasedAt: null, retainNotified: false };
+      spec.prompt = `${buildIsolatePreamble({ worktreePath: wtPath, branch: plan.branch, baseShort: sha.slice(0, 7) })}\n\n${spec.prompt}`;
+    } else if (cwdParam) {
+      cwd = pathResolve(masterCwd, cwdParam);
+      try {
+        const st = await statAsync(cwd);
+        if (!st.isDirectory()) throw new Error('not a directory');
+      } catch {
+        return toolError(`Error: \`cwd\` is not an existing directory: ${cwdParam}`);
+      }
+    }
+    // D86 R1: Group by the git worktree containing cwd (main checkout → main tab; other worktree → directory-named tab).
+    const zone = classifyWorktreeZone({
+      cwd,
+      masterCwd,
+      worktrees: await git.listWorktrees(masterCwd),
+    });
+    // D86 trust: pass -a only for the master's checkout/worktrees; external directories remain behind pi's Trust dialog.
+    const approve = isPathUnder(cwd, masterCwd) || zone.zone === 'worktree';
+    let roleManifestEnv: Record<string, string> = {};
+    let roleModel: string | null = null;
+    try {
+      // planLaunchValidation always names a role ('worker-default' by default); keep the same fallback
+      // here for callers that build a launch spec directly.
+      const roleName = manifestRole ?? 'worker-default';
+      const { role, manifest } = composeForRole(roleName, suggested, { loadRoleOpts: { baseDir: masterCwd } });
+      roleManifestEnv = {
+        PI_HERDR_ROLE_MANIFEST: JSON.stringify({
+          role: role.role,
+          version: role.version,
+          tools: manifest.tools,
+          permissions: manifest.permissions,
+          unknownTools: manifest.unknownTools,
+          services: role.services ?? {},
+        }),
+      };
+      // WS-D10: Route the model by role; omission intentionally uses the process default.
+      if (typeof role.model === 'string' && role.model.trim()) roleModel = role.model.trim();
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return toolError(`Error: role "${manifestRole}" manifest invalid — ${msg}`);
+    }
+    const release = await h.subSemaphore.acquire();
+    let paneId = '';
+    try {
+      const spawnedAt = Date.now();
+      const spawned = await spawnPaneInTaskTab(
+        { desiredTab: tab, description: spec.description, zone },
+        cwd,
+        { PI_HERDR_SUBAGENT: '1', ...roleManifestEnv },
+        launchLine(null, roleModel, approve),
+      );
+      paneId = spawned.paneId;
+      const entry: SubEntry = {
+        taskId,
+        kind,
+        paneId,
+        tabId: spawned.tabId,
+        tabName: spawned.tabName,
+        cwd,
+        description: spec.description,
+        background,
+        status: 'running',
+        sessionFile: null,
+        launchCommand: [launchLine(null, roleModel, approve)],
+        createdAt: Date.now(),
+        revivedFrom: null,
+        ...(isolateMeta ? { isolate: isolateMeta } : {}),
+      };
+      const ready = await waitSubReady(cwd, paneId);
+      if (!ready.ok) throw new Error(ready.message);
+      entry.sessionFile = await resolveSessionFile(paneId, cwd);
+      subs.set(paneId, entry);
+      h.persistSubs();
+      onUpdate?.(makeProgressUpdate(`subagent ready in pane ${paneId}; injecting prompt via pipe…`));
+      // M11 (D45/D46): Inject through the extension pipe to the child extension's sendUserMessage(followUp);
+      // reserve the PTY keyboard channel entirely for the person, with no soft-lock window or mixed input.
+      // Regression evidence (session 01a03bf0): ecc0bc4's foreground-wait rewrite once removed this block,
+      // leaving the prompt uninjected and injectTs undefined (ReferenceError → spawn-failed, with a ghost
+      // running ledger entry). Keep injection and injectTs together in future refactors.
+      const injectTs = Date.now();
+      const injected = await pipeRequestTo(cwd, paneId, {
+        type: 'prompt',
+        id: `prompt-${taskId}`,
+        text: spec.prompt,
+        from: pipeNameFor(cwd, env?.paneId ?? ''),
+        push: background,
+      });
+      if (injected.type !== 'ok') {
+        throw new Error(`pipe prompt rejected: ${injected.type === 'error' ? injected.message : 'unknown response'}`);
+      }
+      h.lastMachineInjectAt.set(paneId, injectTs); // B4: attribute working state during the observation window.
+
+      // A7: run_in_background returns immediately after successful injection instead of blocking in foreground wait.
+      if (background) {
+        entry.background = true;
+        h.lastRequestIdByPane.set(paneId, `prompt-${taskId}`);
+        void startPoller(paneId, cwd, spawnedAt, injectTs, spec.description, `prompt-${taskId}`);
+        h.persistSubs();
+        h.writeHistory(entry, undefined, 'to-background');
+        return {
+          content: [{ type: 'text', text: `started subagent ${paneId} (task ${taskId})` }],
+          details: { paneId, taskId, background: true, role: kind },
+        };
+      }
+
+      // A1+A2 (user-verified fix): foreground waiting uses a content gate plus a patience threshold before backgrounding.
+      // Treating idle as settled with a hard 90s window misclassified real 4–6 minute working periods as no-output;
+      // three healthy subagents were observed becoming consumed at 101s while producing results four minutes later.
+      const patienceDeadline = Date.now() + runtimePolicy.foregroundPatienceMs;
+      let text: string | null = null;
+      let settledKind: 'settled' | 'timeout' = 'timeout';
+      while (Date.now() < Math.min(patienceDeadline, spawnedAt + runtimePolicy.subagentTimeoutMs)) {
+        const state = await client.waitAgent(paneId, ['idle', 'done', 'blocked'], 30_000);
+        const session = (state === 'idle' || state === 'done')
+          ? await subSessionState(paneId, cwd, injectTs)
+          : { text: null, pendingTool: false, activity: false };
+        const tick = planForegroundTick({ state, session });
+        if (tick.kind === 'blocked') {
+          const question = await readAskFlag(paneId);
+          entry.background = true;
+          h.lastRequestIdByPane.set(paneId, `prompt-${taskId}`);
+          void startPoller(paneId, cwd, spawnedAt, injectTs, spec.description, `prompt-${taskId}`);
+          h.persistSubs();
+          h.writeHistory(entry, undefined, 'to-background');
+          return {
+            content: [{ type: 'text', text: buildBlockedGateNotice({ paneId, description: spec.description, question }) }],
+            details: { paneId, taskId, background: true, blocked: true, role: kind },
+          };
+        }
+        if (tick.kind === 'settled') {
+          text = tick.text;
+          settledKind = 'settled';
+          break;
+        }
+        if (tick.kind === 'wait') {
+          await sleep(tick.delayMs);
+          continue;
+        }
+        if (tick.kind === 'collect-final') {
+          text = await collectFinalText(paneId, cwd, injectTs, 6);
+          if (text) { settledKind = 'settled'; break; }
+          await sleep(FOREGROUND_POLL_MS);
+          continue;
+        }
+      }
+      if (!text) {
+        const probe = await probeAlive(paneId, cwd);
+        if (planPatienceExpiry(isAlive(probe, Date.now())) === 'move-to-background') {
+          entry.background = true;
+          h.lastRequestIdByPane.set(paneId, `prompt-${taskId}`);
+          void startPoller(paneId, cwd, spawnedAt, injectTs, spec.description, `prompt-${taskId}`);
+          h.persistSubs();
+          const notice = buildAliveNotice(
+            { paneId, description: spec.description, scenario: 'moved-to-bg', probe },
+            Date.now(),
+          );
+          return {
+            content: [{ type: 'text', text: notice }],
+            details: { paneId, taskId, background: true, movedToBackground: true, role: kind },
+          };
+        }
+        settledKind = 'timeout';
+      }
+      const outcome =
+        settledKind === 'timeout' ? { kind: 'timeout' as const, text: text ?? '' }
+        : text ? { kind: 'completed' as const, text }
+        : { kind: 'no-output' as const, text: '' };
+      entry.status = 'consumed';
+      entry.consumedAt = Date.now();
+      h.persistSubs();
+      h.writeHistory(entry, { outcome: outcome.kind === 'completed' ? text : null }, 'fg-settle');
+      return {
+        content: [{ type: 'text', text: formatSubagentResult(outcome, spec.description) }],
+        details: { paneId, taskId, background, role: kind },
+      };
+    } catch (err) {
+      // Regression fix (session 01a03bf0): a mid-spawn failure must remove the ledger entry and close its pane,
+      // otherwise a ghost running entry never settles, causing D96 reminder storms and send_message calls
+      // to land in an empty session with no task context. Pane closure is best effort; GC covers board exceptions.
+      if (paneId) {
+        subs.delete(paneId);
+        h.persistSubs();
+        void client.closePane(paneId).catch(() => { /* Best effort only. */ });
+      }
+      // D98 2d: If isolate startup never becomes ready, best-effort remove the new worktree and branch (no work
+      // exists to preserve); failure stays silent because the branch is harmless and remains visible to git worktree list.
+      if (isolateMeta) {
+        const branch = isolateMeta.branch;
+        const worktreePath = isolateMeta.worktreePath;
+        void git.runGit(masterCwd, ['worktree', 'remove', '--force', worktreePath])
+          .then(() => git.runGit(masterCwd, ['branch', '-D', branch]))
+          .catch(() => { /* Best effort only. */ });
+      }
+      return {
+        content: [{
+          type: 'text',
+          text: formatSubagentResult(
+            { kind: 'spawn-failed', text: String((err as Error)?.message ?? err) },
+            spec.description,
+          ),
+        }],
+        details: {},
+      };
+    } finally {
+      release();
+      if (isolateMeta) h.pendingIsolateBranches.delete(isolateMeta.branch); // D98: release the creation-window guard on every success/failure path.
+    }
+  };
+}