pi-pier 0.3.0 → 0.4.1

package/src/subagent-core.ts

@@ -1,30 +1,138 @@
-/** Why: Preserve the established compatibility and safety behavior (D10). */
+/**
+ * Subagent domain: registry rows, launch lines, liveness notices, tab/worktree planning, isolate
+ * decisions, task-id resolution, and the outbound port types. Pure: planners decide, adapters do I/O.
+ */
 import { normalizeEntryKind } from './history-store.ts';
+import { Type } from 'typebox';
+
+export function sleep(ms: number): Promise<void> {
+  const { promise, resolve } = Promise.withResolvers<void>();
+  setTimeout(resolve, ms);
+  return promise;
+}
 
 export interface SubagentSpec {
   description: string;
   prompt: string;
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
-export function psQuote(s: string): string {
-  return `'${String(s).replace(/'/g, "''")}'`;
-}
-
-/** Why: Preserve the established compatibility and safety behavior. */
-export function shQuote(s: string): string {
-  return `'${String(s).replace(/'/g, `'\\''`)}'`;
-}
-
-/** Why: Preserve the established compatibility and safety behavior. */
+/** POSIX single-quote escape; win32 PowerShell doubles the quote instead. */
 export function buildLaunchLine(parts: readonly string[], platform: NodeJS.Platform = process.platform): string {
-  const quoted = platform === 'win32'
-    ? parts.map((s) => psQuote(s))
-    : parts.map((s) => shQuote(s));
-  return (platform === 'win32' ? '& ' : '') + quoted.join(' ');
-}
-
-/** Why: Preserve the established compatibility and safety behavior. */
+  const win = platform === 'win32';
+  const quoted = parts.map((s) => (win
+    ? `'${String(s).replace(/'/g, "''")}'`
+    : `'${String(s).replace(/'/g, `'\\''`)}'`));
+  return (win ? '& ' : '') + quoted.join(' ');
+}
+
+/** Shells that mean a freshly split pane is at its prompt and can accept a launch line. */
+const SHELL_PROCESS_NAMES: ReadonlySet<string> = new Set([
+  'sh', 'bash', 'zsh', 'fish', 'dash', 'ksh', 'mksh', 'tcsh', 'csh', 'nu', 'login',
+  'pwsh', 'powershell', 'cmd',
+]);
+
+/** Normalize `name` / `argv0` (`/bin/zsh`, `C:\\Windows\\System32\\cmd.exe`, `-zsh`) to a shell key. */
+export function shellProcessName(value: string | null | undefined): string {
+  const base = String(value ?? '').replace(/\\/g, '/').split('/').pop()?.toLowerCase() ?? '';
+  const stripped = base.replace(/^-/, '').replace(/\.exe$/, '');
+  return stripped;
+}
+
+/**
+ * Decide whether a pane's foreground set means its shell is ready for input. `null`/`undefined`
+ * means the probe was unavailable: return ready so an older herdr never adds spawn latency.
+ * An empty set is not proof (the shell may still be starting), so callers wait for the timeout.
+ */
+export function planShellReady(
+  foreground: ReadonlyArray<{ name?: string | null; argv0?: string | null }> | null | undefined,
+): 'ready' | 'wait' {
+  if (foreground == null) return 'ready';
+  if (foreground.length === 0) return 'wait';
+  return foreground.some((p) => SHELL_PROCESS_NAMES.has(shellProcessName(p.name)) || SHELL_PROCESS_NAMES.has(shellProcessName(p.argv0)))
+    ? 'ready'
+    : 'wait';
+}
+
+/** Flags pier passes at spawn (buildLaunchParts) that a herdr 0.9.2+ resume command must replay. */
+const RESUME_FLAG_ARITY: Record<string, number> = {
+  '-a': 0,
+  '-e': 1,
+  '--extension': 1,
+  '--tui-mode': 1,
+  '--provider': 1,
+  '--model': 1,
+  '--session': 1,
+};
+
+const RESUME_MAX_ARGS = 64;
+const RESUME_MAX_BYTES = 8 * 1024;
+
+/**
+ * herdr 0.9.2 self-report (docs "Add Herdr support to your agent"): rebuild this worker's launch
+ * line as a `resume_argv` herdr runs after a server restart. The worker's own process.argv is the
+ * source of truth — interpreter and cli.js paths are dropped, whitelisted spawn flags are mirrored
+ * (`--flag=value` splits), argv[0] becomes a plain PATH command name. herdr rules: argv[0] plain,
+ * no apostrophes/control characters, ≤64 args, ≤8 KiB; violations (or a missing `-e`, which could
+ * not restore the extension) return null and the caller skips the report — restore stays best-effort.
+ */
+export function buildResumeArgv(workerArgv: readonly string[], piBin = 'pi'): string[] | null {
+  if (!/^[A-Za-z0-9._-]+$/.test(piBin)) return null;
+  const collected: string[] = [];
+  let index = 0;
+  // Skip interpreter + cli script (everything before the first flag).
+  while (index < workerArgv.length && !workerArgv[index]!.startsWith('-')) index++;
+  for (; index < workerArgv.length; index++) {
+    const raw = workerArgv[index]!;
+    if (!raw.startsWith('-')) continue; // positional (unknown flag's value) — not pier spawn shape
+    const eq = raw.indexOf('=');
+    const flag = eq > 0 ? raw.slice(0, eq) : raw;
+    const inlineValue = eq > 0 ? raw.slice(eq + 1) : null;
+    const arity = RESUME_FLAG_ARITY[flag];
+    if (arity === undefined) continue; // pi-internal flags are not replayed
+    if (arity === 0) {
+      collected.push(flag);
+    } else if (inlineValue !== null) {
+      collected.push(flag, inlineValue);
+    } else if (index + 1 < workerArgv.length) {
+      collected.push(flag, workerArgv[++index]!);
+    }
+  }
+  if (!collected.some((f, i) => (f === '-e' || f === '--extension') && i + 1 < collected.length)) return null;
+  const argv = [piBin, ...collected];
+  if (argv.length > RESUME_MAX_ARGS) return null;
+  if (argv.some((a) => /['\u0000-\u001f\u007f]/.test(a))) return null;
+  if (argv.reduce((sum, a) => sum + a.length + 1, 0) > RESUME_MAX_BYTES) return null;
+  return argv;
+}
+
+/**
+ * pi ≥ 0.99 outputSchema for the subagent tool: the `details` each action already produces, stamped
+ * with the normalized action. Codemode scripts (and any structured consumer) read this instead of
+ * parsing the prose reply; the text content stays authoritative for the transcript. Hard failures
+ * throw (toolError), so every returned value is a success and always carries structuredContent.
+ */
+export const SUBAGENT_OUTPUT_SCHEMA = Type.Object({
+  action: Type.Union([
+    Type.Literal('spawn'), Type.Literal('resume'), Type.Literal('list'),
+    Type.Literal('send'), Type.Literal('interrupt'), Type.Literal('output'), Type.Literal('role'),
+  ]),
+  paneId: Type.Optional(Type.String()),
+  taskId: Type.Optional(Type.String()),
+  role: Type.Optional(Type.String()),
+  background: Type.Optional(Type.Boolean()),
+  alreadyRunning: Type.Optional(Type.Boolean()),
+}, { additionalProperties: true });
+
+export function attachSubagentStructuredContent(action: string, result: unknown): unknown {
+  if (result === null || typeof result !== 'object' || Array.isArray(result)) return result;
+  const record = result as Record<string, unknown>;
+  const details = record.details !== null && typeof record.details === 'object' && !Array.isArray(record.details)
+    ? record.details as Record<string, unknown>
+    : {};
+  return { ...record, structuredContent: { action, ...details } };
+}
+
+/** Bounds concurrent delegation spawns (SUBAGENT_CONCURRENCY). */
 export class Semaphore {
   private active = 0;
   private queue: Array<() => void> = [];
@@ -44,12 +152,12 @@ export class Semaphore {
       this.active++;
       return Promise.resolve(this.release.bind(this));
     }
-    return new Promise((resolve) => {
-      this.queue.push(() => {
-        this.active++;
-        resolve(this.release.bind(this));
-      });
+    const { promise, resolve } = Promise.withResolvers<() => void>();
+    this.queue.push(() => {
+      this.active++;
+      resolve(this.release.bind(this));
     });
+    return promise;
   }
 
   private release(): void {
@@ -59,19 +167,15 @@ export class Semaphore {
   }
 }
 
-export interface SubagentOutcome {
+interface SubagentOutcome {
   kind: 'completed' | 'timeout' | 'no-output' | 'blocked' | 'spawn-failed';
-  /** Why: Preserve the established compatibility and safety behavior. */
   text: string;
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
 export function formatSubagentResult(outcome: SubagentOutcome, description: string): string {
   switch (outcome.kind) {
-    case 'completed': {
-      const text = outcome.text;
-      return text ? text : 'Subagent finished but produced no output.';
-    }
+    case 'completed':
+      return outcome.text ? outcome.text : 'Subagent finished but produced no output.';
     case 'timeout':
       return `Error: subagent "${description}" timed out. Partial output:\n${outcome.text || '(none)'}`;
     case 'blocked':
@@ -83,27 +187,25 @@ export function formatSubagentResult(outcome: SubagentOutcome, description: stri
   }
 }
 
-/** Why: Preserve the established compatibility and safety behavior (A2, B1). */
-
-/** Why: Preserve the established compatibility and safety behavior. */
 export interface AliveProbe {
   paneExists: boolean;
   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. */
+/**
+ * A subagent outlives its "no output" result: a working/blocked agent is alive regardless of session
+ * age, otherwise recent session writes decide. `paneExists: false` is death — an unavailable probe is
+ * the caller's to report, not guessed here.
+ */
 export function isAlive(probe: AliveProbe, nowMs: number, staleAfterMs = 120_000): boolean {
   if (!probe.paneExists) return false;
   if (probe.agentStatus === 'working' || probe.agentStatus === 'blocked') return true;
-  // Why: Preserve the established compatibility and safety behavior.
   return probe.lastActivityMs != null && nowMs - probe.lastActivityMs < staleAfterMs;
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
 export function agoText(ms: number, nowMs: number): string {
   const s = Math.max(0, Math.round((nowMs - ms) / 1000));
   if (s < 60) return `${s}s ago`;
@@ -111,7 +213,6 @@ export function agoText(ms: number, nowMs: number): string {
   return `${Math.floor(s / 3600)}h ago`;
 }
 
-/** Why: Preserve the established compatibility and safety behavior (A2, B1). */
 export function buildAliveNotice(
   opts: { paneId: string; description: string; scenario: 'moved-to-bg' | 'error-alive'; probe: AliveProbe },
   nowMs: number,
@@ -134,7 +235,7 @@ export function buildAliveNotice(
   ].join(' ');
 }
 
-/** Why: Preserve the established compatibility and safety behavior (E1, E2). */
+/** A pane blocked on a human decision keeps running: the master must not take the work over. */
 export function buildBlockedGateNotice(opts: { paneId: string; description: string; question: string | null }): string {
   const { paneId, description, question } = opts;
   const q = question ? ` (question: "${question}")` : '';
@@ -147,35 +248,33 @@ export function buildBlockedGateNotice(opts: { paneId: string; description: stri
   ].join(' ');
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
-
 export const SUBS_CUSTOM_TYPE = 'pi-herdr.subs';
 
 export interface SubEntry {
   taskId: string;
-  /** Why: Preserve the established compatibility and safety behavior. */
+  /** 'task' or a role name; only a display label for GC. */
   kind: string;
   paneId: string;
+  /** Phase 2 task slug (kebab-case of description; RFC rfc-delegation-identity §3.1): tool args
+   * accept `slug@paneId` or the bare slug; allocated once at spawn and stable across revives. */
+  slug?: string;
   tabId: string;
-  /** Why: Preserve the established compatibility and safety behavior (D25, D26). */
   tabName: string;
   cwd: string;
   description: string;
   background: boolean;
   status: 'running' | 'settled' | 'consumed' | 'closed';
-  /** Why: Preserve the established compatibility and safety behavior. */
+  /** GC grace basis (durable); closed rows keep the original value. */
   consumedAt?: number | null;
   sessionFile: string | null;
   launchCommand: string[];
   createdAt: number;
   revivedFrom?: string | null;
-  /** Why: Preserve the established compatibility and safety behavior (D94). */
+  /** D94: the human took the pane over; observation window judges when to hand control back. */
   userTakeover?: boolean;
-  /** Why: Preserve the established compatibility and safety behavior (D94). */
   observationStartedAt?: number | null;
-  /** Why: Preserve the established compatibility and safety behavior (D94). */
   lastAgentStatus?: string | null;
-  /** Why: Preserve the established compatibility and safety behavior (D98). */
+  /** D98: isolate worktree metadata; `releasedAt` set once the worktree is removed. */
   isolate?: {
     worktreePath: string;
     branch: string;
@@ -185,6 +284,41 @@ export interface SubEntry {
   };
 }
 
+/* ── task slugs (RFC rfc-delegation-identity §3.1) ───────────────── */
+
+/** Slug cap: short enough for tool args and list rows, long enough to stay distinctive. */
+const SLUG_MAX = 24;
+
+/** Kebab-case a task description; non-ASCII (CJK descriptions) sanitizes to '' — the allocator
+ * then falls back to a taskId-derived ascii slug, because tool args must stay typeable. */
+export function slugifyTask(description: string): string {
+  return description
+    .toLowerCase()
+    .replace(/[''']/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, SLUG_MAX)
+    .replace(/-+$/g, '');
+}
+
+/** Allocate a unique slug among live rows: base, then base-2, base-3, …; a description that
+ * sanitizes to nothing (CJK, emoji-only) falls back to `task-<taskId prefix>`. */
+export function allocateSubSlug(description: string, taskId: string, taken: ReadonlySet<string>): string {
+  const base = slugifyTask(description) || `task-${taskId.slice(0, 6)}`;
+  if (!taken.has(base)) return base;
+  for (let n = 2; ; n++) {
+    const next = `${base}-${n}`;
+    if (!taken.has(next)) return next;
+  }
+}
+
+/** Stable display/argument form for a subagent row: `slug@paneId` when a slug exists. */
+export function subRef(sub: { paneId: string; slug?: string }): string {
+  return sub.slug ? `${sub.slug}@${sub.paneId}` : sub.paneId;
+}
+
+export const PROGRESS_CUSTOM_TYPE = 'pi-herdr.progress';
+
 export interface SubsRegistry {
   version: 2;
   subs: SubEntry[];
@@ -194,14 +328,15 @@ export function makeRegistry(subs: SubEntry[] = []): SubsRegistry {
   return { version: 2, subs };
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
-export function foldSubsRegistry(entries: readonly BranchEntryLike2[]): SubsRegistry {
+const SUB_STATUSES: Record<string, true> = { running: true, settled: true, consumed: true, closed: true };
+
+/** Replay `pi-herdr.subs` custom branch entries into a registry; last snapshot wins. Tolerant of
+ *  v1 rows (missing taskId/kind/tabName) and unknown future fields. */
+export function foldSubsRegistry(entries: ReadonlyArray<{ type?: string; customType?: string; data?: unknown }>): SubsRegistry {
   let found = makeRegistry();
   for (const entry of entries) {
     if (entry.type !== 'custom' || entry.customType !== SUBS_CUSTOM_TYPE) continue;
-    const data = entry.data as {
-      subs?: Array<Partial<SubEntry> & { paneId: string }>;
-    } | undefined;
+    const data = entry.data as { subs?: Array<Partial<SubEntry> & { paneId: string }> } | undefined;
     if (!data || !Array.isArray(data.subs)) continue;
     const subs: SubEntry[] = data.subs
       .filter((s) => typeof s?.paneId === 'string')
@@ -209,12 +344,15 @@ export function foldSubsRegistry(entries: readonly BranchEntryLike2[]): SubsRegi
         taskId: typeof s.taskId === 'string' ? s.taskId : s.paneId,
         kind: normalizeEntryKind(typeof s.kind === 'string' ? s.kind : undefined),
         paneId: s.paneId,
+        slug: typeof s.slug === 'string' && s.slug ? s.slug : undefined,
         tabId: typeof s.tabId === 'string' ? s.tabId : '',
         tabName: typeof s.tabName === 'string' ? s.tabName : '',
         cwd: typeof s.cwd === 'string' ? s.cwd : '',
         description: typeof s.description === 'string' ? s.description : '',
         background: s.background === true,
-        status: s.status === 'closed' ? 'closed' : s.status === 'consumed' ? 'consumed' : s.status === 'settled' ? 'settled' : 'running',
+        status: typeof s.status === 'string' && SUB_STATUSES[s.status] === true
+          ? (s.status as SubEntry['status'])
+          : 'running',
         consumedAt: typeof s.consumedAt === 'number' ? s.consumedAt : null,
         sessionFile: typeof s.sessionFile === 'string' ? s.sessionFile : null,
         launchCommand: Array.isArray(s.launchCommand) ? s.launchCommand : [],
@@ -240,36 +378,75 @@ export function foldSubsRegistry(entries: readonly BranchEntryLike2[]): SubsRegi
   return found;
 }
 
-export interface BranchEntryLike2 {
-  type?: string;
-  customType?: string;
-  data?: unknown;
+/** Latest row per taskId (same taskId rows are generations); newest createdAt wins. */
+export function newestPerTaskId(entries: Iterable<SubEntry>): Map<string, SubEntry> {
+  const byTask = new Map<string, SubEntry>();
+  for (const sub of entries) {
+    const prev = byTask.get(sub.taskId);
+    if (!prev || sub.createdAt >= prev.createdAt) byTask.set(sub.taskId, sub);
+  }
+  return byTask;
+}
+
+/** Re-key a revived entry under its new pane id; the dead id must go, or a later zombie sweep closes the live row. */
+export function rekeySub(subs: Map<string, SubEntry>, previousPaneId: string, entry: SubEntry): void {
+  if (previousPaneId !== entry.paneId && subs.get(previousPaneId) === entry) subs.delete(previousPaneId);
+  subs.set(entry.paneId, entry);
+}
+
+/** Split `provider/model` on the first '/' only: model ids such as `moonshotai/kimi-k2` carry their own. */
+export function splitRoleModel(roleModel: string): { provider: string | null; model: string } {
+  const slash = roleModel.indexOf('/');
+  if (slash <= 0 || slash === roleModel.length - 1) return { provider: null, model: roleModel };
+  return { provider: roleModel.slice(0, slash), model: roleModel.slice(slash + 1) };
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
+/** pi's AgentToolResult shape — a bare string crashes the interactive TUI's getTextOutput. */
+export function makeProgressUpdate(msg: string) {
+  return { content: [{ type: 'text' as const, text: msg }], details: {} as Record<string, never> };
+}
 
-export interface ProgressUpdate {
-  content: Array<{ type: 'text'; text: string }>;
-  details: Record<string, never>;
+/**
+ * Models sometimes wrap fields in a `parameters` object (JSON-schema habit). Top-level wins;
+ * only missing keys are filled from the nested bag so a real field is never overwritten.
+ */
+export function flattenToolParams(params: Record<string, unknown> | undefined): Record<string, unknown> | undefined {
+  if (!params) return params;
+  const nested = params.parameters;
+  if (nested === null || typeof nested !== 'object' || Array.isArray(nested)) return params;
+  const out: Record<string, unknown> = { ...params };
+  for (const [key, value] of Object.entries(nested as Record<string, unknown>)) {
+    if (key === 'parameters') continue;
+    const current = out[key];
+    if (current == null || current === '') out[key] = value;
+  }
+  return out;
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
-export function makeProgressUpdate(msg: string): ProgressUpdate {
-  return { content: [{ type: 'text', text: msg }], details: {} };
+
+export function idParam(params: Record<string, unknown> | undefined, ...keys: string[]): string {
+  const flat = flattenToolParams(params);
+  for (const key of keys) {
+    const v = flat?.[key];
+    if (v != null && String(v).trim() !== '') return String(v).trim();
+  }
+  return '';
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D25, D26). */
+export function ambiguousIdError(label: 'task id' | 'subagent id', query: string, candidates: readonly string[]): string {
+  const head = candidates.slice(0, 5).join(', ');
+  const more = candidates.length > 5 ? `, ... (+${candidates.length - 5} more)` : '';
+  return `Error: ambiguous ${label} "${query}" matches ${candidates.length} tasks: ${head}${more}`;
+}
 
 export const TAB_NAME_MAX = 20;
 
-/** Why: Preserve the established compatibility and safety behavior. */
 export function tabNameForTask(description: string): string {
   const cleaned = String(description ?? '').replace(/\s+/g, ' ').trim();
   const truncated = cleaned.slice(0, TAB_NAME_MAX).trim();
   return truncated || 'task';
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D26). */
 export function nextTaskTabName(base: string, existingNames: ReadonlySet<string>): string {
   let name = base;
   let n = 2;
@@ -282,16 +459,12 @@ export function nextTaskTabName(base: string, existingNames: ReadonlySet<string>
 }
 
 export interface TabPlacementPlan {
-  /** Why: Preserve the established compatibility and safety behavior. */
   mode: 'append' | 'new';
   tabName: string;
-  /** Why: Preserve the established compatibility and safety behavior. */
   tabId: string | null;
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D86). */
-
-/** Why: Preserve the established compatibility and safety behavior (D86). */
+/** Case/slash-insensitive containment; `/repo-x` is NOT under `/repo`. */
 export function isPathUnder(cwd: string, wt: string): boolean {
   const n = (p: string) => p.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
   const a = n(cwd);
@@ -300,13 +473,11 @@ export function isPathUnder(cwd: string, wt: string): boolean {
 }
 
 export interface WorktreeZone {
-  /** Why: Preserve the established compatibility and safety behavior. */
   zone: 'main' | 'worktree';
-  /** Why: Preserve the established compatibility and safety behavior. */
   tabName: string | null;
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D86). */
+/** D86: subagents working in the master's checkout share its tab; another worktree gets its own. */
 export function classifyWorktreeZone(opts: {
   cwd: string;
   masterCwd: string;
@@ -314,21 +485,19 @@ export function classifyWorktreeZone(opts: {
 }): WorktreeZone {
   for (const wt of opts.worktrees) {
     if (!isPathUnder(opts.cwd, wt)) continue;
-    if (isPathUnder(opts.masterCwd, wt)) return { zone: 'main', tabName: null }; // Why: Preserve the established compatibility and safety behavior.
+    if (isPathUnder(opts.masterCwd, wt)) return { zone: 'main', tabName: null };
     const base = wt.replace(/\\/g, '/').split('/').filter(Boolean).pop() ?? 'worktree';
     return { zone: 'worktree', tabName: base };
   }
   return { zone: 'main', tabName: null };
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D26, D86). */
+/** Explicit `tab` wins; otherwise D86 zone decides, and an unknown zone falls back to the description. */
 export function planTabPlacement(opts: {
   desiredTab?: string | null;
   description: string;
   knownTabs: ReadonlyArray<{ tabName: string; tabId: string }>;
-  /** Why: Preserve the established compatibility and safety behavior (D86). */
   zone?: WorktreeZone;
-  /** Why: Preserve the established compatibility and safety behavior (D86). */
   mainTabId?: string | null;
 }): TabPlacementPlan {
   const known = new Map<string, string>();
@@ -340,35 +509,21 @@ export function planTabPlacement(opts: {
   }
   const zone = opts.zone;
   if (zone?.zone === 'main' && opts.mainTabId) {
-    // Why: Preserve the established compatibility and safety behavior (D86, R1).
     return { mode: 'append', tabName: 'main', tabId: opts.mainTabId };
   }
   if (zone?.zone === 'worktree' && zone.tabName) {
-    // Why: Preserve the established compatibility and safety behavior (D86, R1).
     const base = zone.tabName;
     const existing = [...known.keys()].find((k) => k.toLowerCase() === base.toLowerCase());
     if (existing) return { mode: 'append', tabName: existing, tabId: known.get(existing)! };
-    const tabName = nextTaskTabName(base, new Set(known.keys()));
-    return { mode: 'new', tabName, tabId: null };
+    return { mode: 'new', tabName: nextTaskTabName(base, new Set(known.keys())), tabId: null };
   }
-  // Why: Preserve the established compatibility and safety behavior.
   const base = tabNameForTask(opts.description);
-  const tabName = nextTaskTabName(base, new Set(known.keys()));
-  return { mode: 'new', tabName, tabId: null };
+  return { mode: 'new', tabName: nextTaskTabName(base, new Set(known.keys())), tabId: null };
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D97). */
-
-/** Why: Preserve the established compatibility and safety behavior. */
-export interface LaunchRuntime {
-  nodePath: string;
-  cliPath: string;
-  extPath: string;
-}
-
-/** Why: Preserve the established compatibility and safety behavior (D97). */
+/** D97: fullscreen is what makes the pane a static frame the master can read. */
 export function buildLaunchParts(
-  runtime: LaunchRuntime,
+  runtime: { nodePath: string; cliPath: string; extPath: string },
   opts: { resumeFile?: string | null; roleModel?: string | null; approve?: boolean } = {},
   env: { PI_HERDR_TUI?: string | undefined } = process.env,
 ): string[] {
@@ -376,29 +531,28 @@ export function buildLaunchParts(
   if (opts.approve) parts.push('-a');
   parts.push('-e', runtime.extPath);
   if (env.PI_HERDR_TUI !== 'regular') parts.push('--tui-mode', 'fullscreen');
-  if (opts.roleModel) parts.push('--provider', opts.roleModel.split('/')[0], '--model', opts.roleModel.split('/')[1] ?? opts.roleModel);
+  if (opts.roleModel) {
+    const { provider, model } = splitRoleModel(opts.roleModel);
+    if (provider) parts.push('--provider', provider);
+    parts.push('--model', model);
+  }
   if (opts.resumeFile) parts.push('--session', opts.resumeFile);
   return parts;
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D98). */
+const ISOLATE_SLUG_MAX = 40;
 
-/** Why: Preserve the established compatibility and safety behavior. */
-export interface IsolatePlan {
-  branch: string;
-  slug: string;
-  worktreeDirName: string;
-}
-
-/** Why: Preserve the established compatibility and safety behavior. */
-export const ISOLATE_SLUG_MAX = 40;
-
-/** Why: Preserve the established compatibility and safety behavior (D98). */
+/**
+ * D-3 (verified 2026-10-20): herdr 0.9.5 `worktree create --workspace <parent>` still opens a new
+ * top-level workspace, not a tab inside the parent workspace, so it cannot replace pier's isolate
+ * placement. Keep `git worktree add` + the master-workspace tab; native worktree management remains
+ * an option only for workflows that accept a separate workspace.
+ */
 export function planIsolateWorktree(opts: {
   description: string;
   taskHex: string;
   existingPierBranches: ReadonlySet<string>;
-}): IsolatePlan {
+}) {
   const folded = String(opts.description ?? '')
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, '-')
@@ -415,7 +569,7 @@ export function planIsolateWorktree(opts: {
   return { branch: `pier/${name}`, slug: name, worktreeDirName: `pier-${name}` };
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D98). */
+/** Commit discipline is injected into the prompt: the worktree has no other protection. */
 export function buildIsolatePreamble(opts: { worktreePath: string; branch: string; baseShort: string }): string {
   return [
     `You are working in an isolated git worktree: ${opts.worktreePath} (branch ${opts.branch}, base ${opts.baseShort}).`,
@@ -426,7 +580,6 @@ export function buildIsolatePreamble(opts: { worktreePath: string; branch: strin
   ].join('\n');
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D98). */
 export function formatWorktreeStat(opts: {
   branch: string | null;
   commits: number | null;
@@ -445,17 +598,16 @@ export function formatWorktreeStat(opts: {
   return `git: ${opts.statLine}; uncommitted: ${opts.dirtyCount} file(s)`;
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D98). */
-export type ReleaseDecision = { action: 'release' } | { action: 'retain'; reason: 'unmerged' | 'dirty' | 'unknown' };
-
-export function evaluateRelease(opts: { merged: boolean | null; dirtyCount: number | null }): ReleaseDecision {
+/** D98: only a merged, clean, known worktree may be removed automatically. */
+export function evaluateRelease(opts: { merged: boolean | null; dirtyCount: number | null }):
+  { action: 'release' } | { action: 'retain'; reason: 'unmerged' | 'dirty' | 'unknown' } {
   if (opts.merged === null || opts.dirtyCount === null) return { action: 'retain', reason: 'unknown' };
   if (!opts.merged) return { action: 'retain', reason: 'unmerged' };
   if (opts.dirtyCount > 0) return { action: 'retain', reason: 'dirty' };
   return { action: 'release' };
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D98). */
+/** `git worktree list --porcelain` → branch (refs/heads/ stripped) → path. */
 export function parseWorktreePorcelain(out: string): Map<string, string> {
   const byBranch = new Map<string, string>();
   let curPath: string | null = null;
@@ -467,3 +619,154 @@ export function parseWorktreePorcelain(out: string): Map<string, string> {
   }
   return byBranch;
 }
+
+/* ── execute planners ───────────────────────────────────────────── */
+
+export const FOREGROUND_POLL_MS = 2_000;
+
+type LaunchValidation =
+  | { kind: 'error'; text: string }
+  | {
+    kind: 'ok';
+    spec: SubagentSpec;
+    background: boolean;
+    isolate: boolean;
+    cwdParam: string | null;
+    roleKind: string;
+    suggested: string[];
+    manifestRole: string | null;
+    tab: string | null;
+  };
+
+/** Validate spawn parameters. `role` doubles as the pane label and (when it names a profile) the
+ *  manifest to compose; unknown names stay labels. `isolate` and `cwd` are mutually exclusive. */
+export function planLaunchValidation(
+  params: {
+    description?: unknown;
+    prompt?: unknown;
+    run_in_background?: unknown;
+    cwd?: unknown;
+    isolate?: unknown;
+    role?: unknown;
+    allowed_tools?: unknown;
+    tab?: unknown;
+  } | null | undefined,
+  herdrAvailable: boolean,
+): LaunchValidation {
+  if (!herdrAvailable) {
+    return { kind: 'error', text: 'Error: subagent requires pi to run inside a herdr-managed pane (HERDR_ENV not set).' };
+  }
+  const spec: SubagentSpec = {
+    description: String(params?.description ?? 'subagent'),
+    prompt: String(params?.prompt ?? ''),
+  };
+  if (!spec.prompt.trim()) return { kind: 'error', text: 'Error: `prompt` must be a non-empty string' };
+  const cwdParam = typeof params?.cwd === 'string' && params.cwd.trim() ? params.cwd.trim() : null;
+  const isolate = params?.isolate === true;
+  if (isolate && cwdParam) {
+    return {
+      kind: 'error',
+      text: 'Error: `isolate` and `cwd` are mutually exclusive — isolate creates a new worktree, cwd delegates into an existing one',
+    };
+  }
+  const role = typeof params?.role === 'string' ? params.role.trim() : undefined;
+  return {
+    kind: 'ok',
+    spec,
+    background: params?.run_in_background === true,
+    isolate,
+    cwdParam,
+    roleKind: normalizeEntryKind(role),
+    suggested: Array.isArray(params?.allowed_tools)
+      ? params.allowed_tools.filter((t): t is string => typeof t === 'string' && t.trim() !== '')
+      : [],
+    manifestRole: role || 'worker-default',
+    tab: typeof params?.tab === 'string' ? params.tab : null,
+  };
+}
+
+export type ForegroundTickPlan =
+  | { kind: 'blocked' }
+  | { kind: 'settled'; text: string }
+  | { kind: 'wait'; delayMs: number }
+  | { kind: 'collect-final' }
+  | { kind: 'continue' };
+
+/** One foreground-wait iteration: only a human gate or finalized text ends the wait. */
+export function planForegroundTick(input: {
+  state: string | null;
+  session: { text: string | null; pendingTool: boolean; activity: boolean };
+}): ForegroundTickPlan {
+  if (input.state === 'blocked') return { kind: 'blocked' };
+  if (input.state !== 'idle' && input.state !== 'done') return { kind: 'continue' };
+  if (input.session.text) return { kind: 'settled', text: input.session.text };
+  if (input.session.pendingTool || !input.session.activity) return { kind: 'wait', delayMs: FOREGROUND_POLL_MS };
+  return { kind: 'collect-final' };
+}
+
+/* ── task-id resolution ─────────────────────────────────────────── */
+
+export type TaskIdResolutionResult =
+  | { kind: 'resolved'; taskId: string }
+  | { kind: 'ambiguous'; query: string; candidates: string[] }
+  | { kind: 'too_short'; query: string }
+  | { kind: 'not_found'; query: string };
+
+/** Resolve a full or short task ID: exact matches at any length, prefix matches need four characters. */
+export function resolveTaskIdPrefix(
+  query: string,
+  candidates: Iterable<string>,
+): TaskIdResolutionResult {
+  const trimmed = query.trim();
+  if (!trimmed) return { kind: 'not_found', query: trimmed };
+
+  const unique = Array.from(new Set(candidates));
+  const exact = unique.find((candidate) => candidate === trimmed);
+  if (exact) return { kind: 'resolved', taskId: exact };
+
+  if (trimmed.length < 4) return { kind: 'too_short', query: trimmed };
+
+  const lower = trimmed.toLowerCase();
+  const matches = unique.filter((candidate) => candidate.toLowerCase().startsWith(lower));
+  if (matches.length === 1) return { kind: 'resolved', taskId: matches[0]! };
+  if (matches.length > 1) {
+    matches.sort();
+    return { kind: 'ambiguous', query: trimmed, candidates: matches };
+  }
+  return { kind: 'not_found', query: trimmed };
+}
+
+/** Error text for a non-resolved `resolveTaskIdPrefix` outcome; null for `resolved` (each caller owns
+ * its success path) and `not_found` (each caller words its own unknown-id hint). `rawQuery` keeps
+ * the caller's original string in the message even though matching works on the trimmed form. */
+export function taskIdResolutionError(
+  res: TaskIdResolutionResult,
+  label: 'task id' | 'subagent id',
+  rawQuery: string,
+): string | null {
+  if (res.kind === 'too_short') return `Error: ${label} prefix "${rawQuery}" is too short (minimum 4 characters).`;
+  if (res.kind === 'ambiguous') return ambiguousIdError(label, rawQuery, res.candidates);
+  return null;
+}
+
+/* ── outbound port (composition root → plugin) ──────────────────── */
+
+/** Bound atomically at session_start: consumers read `current` and must tolerate null. */
+export interface SubagentPort {
+  applyReplySession(paneId: string, sessionFile: string | null): void;
+  reconcileOnReply(paneId: string): string[];
+  listRunningSubs(): Array<{ paneId: string; slug?: string; description: string; kind: string }>;
+  /** D113: non-closed rows for the /pier-tree view (settled nodes carry their settle time). */
+  listRows(): Array<{ paneId: string; slug?: string; description: string; kind: string; status: SubEntry['status']; settledAt: number | null }>;
+  settleStatLine(paneId: string): Promise<string | null>;
+  /** Pipe settlement: drop the row out of listRunningSubs before the finish notice wakes the master. */
+  consumeReply(paneId: string, outcome: string | null): void;
+}
+
+export interface SubagentPortBox {
+  current: SubagentPort | null;
+}
+
+export function emptySubagentPortBox(): SubagentPortBox {
+  return { current: null };
+}