pi-pier 0.2.6 → 0.3.0

package/src/subagent-gc.ts

@@ -10,6 +10,9 @@ import type { HerdrClientLike } from './herdr-client.ts';
 import { shouldClosePane, shouldCloseTaskTab } from './gc-core.ts';
 import { runtimePolicy } from './runtime-policy.ts';
 import { evaluateRelease, parseWorktreePorcelain, type SubEntry } from './subagent-core.ts';
+import { planIsolateSweep, isPathInside } from './gc-core.ts';
+
+interface Cand { branch: string; wtPath: string; entry: SubEntry | null }
 import type { GitIo } from './subagent-git-io.ts';
 import type { TerminalStateSlot } from './core/terminal.ts';
 
@@ -140,21 +143,35 @@ export function createGcController(h: GcHost): GcController {
     const wtPorcelain = await h.git.runGit(masterCwd, ['worktree', 'list', '--porcelain']);
     if (wtPorcelain === null) return;
     const wtByBranch = parseWorktreePorcelain(wtPorcelain);
-    const pierBranchOut = await h.git.runGit(masterCwd, ['for-each-ref', '--format=%(refname:short)', 'refs/heads/pier/']);
-    const pierBranches = (pierBranchOut ?? '').split('\n').map((l) => l.trim()).filter(Boolean);
-    type Cand = { branch: string; wtPath: string; entry: SubEntry | null };
-    const byBranch = new Map<string, Cand>();
-    for (const branch of pierBranches) {
-      if (registeredBranches.has(branch) || h.pendingIsolateBranches.has(branch)) continue;
-      const wtPath = wtByBranch.get(branch);
-      if (wtPath) byBranch.set(branch, { branch, wtPath, entry: null });
-    }
+    // Session-owned isolates: settled or consumed entries whose worktree was not released yet.
+    const sessionOwned = [...h.subs.values()]
+      .filter((e) => e.isolate && e.isolate.releasedAt == null && e.status !== 'running')
+      .map((e) => ({ branch: e.isolate!.branch, worktreePath: e.isolate!.worktreePath }));
+    // Untracked `pier/*` branches are only swept on explicit request: they may belong to
+    // another session (whose process may even be running inside them).
+    const sweepOrphans = process.env.PIER_ISOLATE_SWEEP_ORPHANS === '1';
+    const branches = sweepOrphans
+      ? (await h.git.runGit(masterCwd, ['for-each-ref', '--format=%(refname:short)', 'refs/heads/pier/']))
+        ?.split('\n').map((l) => l.trim()).filter(Boolean) ?? []
+      : [];
+    const plan = planIsolateSweep({
+      branches,
+      worktreesByBranch: wtByBranch,
+      registeredBranches,
+      pendingBranches: h.pendingIsolateBranches,
+      sessionOwned,
+      cwd: masterCwd,
+      sweepOrphans,
+    });
+    const entryByBranch = new Map<string, SubEntry>();
     for (const e of h.subs.values()) {
-      if (!e.isolate || e.isolate.releasedAt != null || e.status === 'running') continue;
-      const prev = byBranch.get(e.isolate.branch);
-      byBranch.set(e.isolate.branch, { branch: e.isolate.branch, wtPath: prev?.wtPath ?? e.isolate.worktreePath, entry: e });
+      if (e.isolate && e.isolate.releasedAt == null && e.status !== 'running') entryByBranch.set(e.isolate.branch, e);
+    }
+    const byBranch = new Map<string, Cand>();
+    for (const cand of plan.candidates) {
+      byBranch.set(cand.branch, { branch: cand.branch, wtPath: cand.worktreePath, entry: entryByBranch.get(cand.branch) ?? null });
     }
-    trace?.(`cands=${[...byBranch.keys()].join(',') || 'none'} subs=${[...h.subs.values()].map((s) => `${s.status}${s.isolate ? '/iso' : ''}`).join(',') || 'none'}`);
+    trace?.(`cands=${[...byBranch.keys()].join(',') || 'none'} skipped=${plan.skipped.map((s) => `${s.branch}:${s.reason}`).join(',') || 'none'} subs=${[...h.subs.values()].map((s) => `${s.status}${s.isolate ? '/iso' : ''}`).join(',') || 'none'}`);
     let persisted = false;
     for (const cand of byBranch.values()) {
       const { branch, wtPath, entry } = cand;
@@ -179,6 +196,9 @@ export function createGcController(h: GcHost): GcController {
       const dirtyCount = dirtyOut === null ? null : dirtyOut.split('\n').filter((l) => l.trim() !== '').length;
       const decision = evaluateRelease({ merged: mergedFinal, dirtyCount });
       if (decision.action === 'release') {
+        // Defense in depth: planner already refuses the current worktree, but a removal here
+        // must never be able to delete the directory this process is running in.
+        if (isPathInside(masterCwd, wtPath)) continue;
         const removed = await h.git.runGit(masterCwd, ['worktree', 'remove', wtPath]);
         let ok = removed !== null;
         if (!ok) {

package/src/subagent-launch.ts

@@ -19,6 +19,8 @@ export type LaunchParams = {
   tab?: unknown;
 };
 
+import type { SubagentSpec } from './subagent-core.ts';
+
 export type LaunchValidation =
   | { kind: 'error'; text: string }
   | {
@@ -30,6 +32,8 @@ export type LaunchValidation =
       roleKind: string;
       suggested: string[];
       tab: string | null;
+      /** Role manifest supplied by the caller (drives tool gating); null when unset. */
+      manifestRole: string | null;
     };
 
 export function planLaunchValidation(

package/src/subagent-list-action.ts

@@ -0,0 +1,69 @@
+import { basename } from 'node:path';
+import { agoText, type AliveProbe, type SubEntry } from './subagent-core.ts';
+
+export interface ListActionResult {
+  content: Array<{ type: 'text'; text: string }>;
+  details: Record<string, unknown>;
+}
+
+export interface ListActionDeps {
+  subs: () => Iterable<SubEntry>;
+  probeAlive: (paneId: string, cwd: string) => Promise<AliveProbe>;
+  readAskFlag: (paneId: string) => Promise<string | null>;
+  now?: () => number;
+}
+
+/** Render the live background registry without coupling it to Cordis or the tool registration. */
+export async function executeSubagentList(deps: ListActionDeps): Promise<ListActionResult> {
+  const listed = [...deps.subs()].filter((sub) => sub.background);
+  if (listed.length === 0) {
+    return {
+      content: [{ type: 'text', text: 'No background subagents started (from this session branch).' }],
+      details: {},
+    };
+  }
+
+  const byTask = new Map<string, SubEntry>();
+  for (const sub of listed) {
+    const previous = byTask.get(sub.taskId);
+    if (!previous || sub.createdAt >= previous.createdAt) byTask.set(sub.taskId, sub);
+  }
+
+  const probes = new Map<string, AliveProbe>();
+  await Promise.all([...byTask.values()].map(async (sub) => {
+    if (sub.status === 'closed') return;
+    try {
+      probes.set(sub.paneId, await deps.probeAlive(sub.paneId, sub.cwd));
+    } catch {
+      /* Best effort for display. */
+    }
+  }));
+
+  const now = deps.now ?? Date.now;
+  const lines: string[] = [];
+  for (const sub of byTask.values()) {
+    const tabTag = sub.tabName ? ` [tab: ${sub.tabName}]` : '';
+    const wtTag = sub.isolate ? ` [wt: ${sub.isolate.branch}]` : '';
+    if (sub.status === 'closed') {
+      lines.push(`${sub.taskId.slice(0, 8)} [idle] (${sub.kind}, closed; action send revives)${tabTag}${wtTag} ${sub.description}`);
+      continue;
+    }
+
+    const state = sub.status === 'settled' ? 'idle' : 'running';
+    const takeoverMark = sub.userTakeover ? ', user-controlled' : '';
+    const probe = probes.get(sub.paneId);
+    const statusTag = probe?.agentStatus ? ` ${probe.agentStatus}` : '';
+    const activityTag = probe?.lastActivityMs != null ? `, active ${agoText(probe.lastActivityMs, now())}` : '';
+    let gateTag = '';
+    if (probe?.agentStatus === 'blocked') {
+      const question = await deps.readAskFlag(sub.paneId);
+      gateTag = question ? ` — AWAITING HUMAN: "${question}"` : ' — AWAITING HUMAN decision';
+    }
+    const cwdTag = probe?.foregroundCwd && probe.foregroundCwd !== sub.cwd
+      ? ` [cwd: ${basename(probe.foregroundCwd) || probe.foregroundCwd}]`
+      : '';
+    lines.push(`${sub.paneId} [${state}${takeoverMark}${statusTag}${activityTag}${gateTag}] (${sub.kind})${tabTag}${wtTag}${cwdTag} ${sub.description}`);
+  }
+
+  return { content: [{ type: 'text', text: lines.join('\n') }], details: {} };
+}

package/src/subagent-output-action.ts

@@ -0,0 +1,104 @@
+import type { HerdrAgentState, HerdrClientLike } from './herdr-client.ts';
+import type { SubEntry } from './subagent-core.ts';
+import {
+  computeSubagentOutputDelta,
+  formatSubagentOutput,
+  resolveSubagentStatus,
+  type SubagentOutputCursor,
+} from './subagent-output-core.ts';
+import { readSubagentOutput } from './subagent-output-adapter.ts';
+import { toolError } from './tool-error.ts';
+
+export interface OutputActionParams {
+  agentId?: unknown;
+  taskId?: unknown;
+  max_chars?: unknown;
+  maxChars?: unknown;
+}
+
+export interface OutputActionResult {
+  content: Array<{ type: 'text'; text: string }>;
+  details: Record<string, unknown>;
+}
+
+export interface OutputActionDeps {
+  client: HerdrClientLike;
+  resolveEntry: (rawId: string, cwd: string) => { entry: SubEntry } | { error: string };
+  readAskFlag: (paneId: string) => Promise<string | null>;
+  outputCursors: Map<string, SubagentOutputCursor>;
+  getCwd: (toolCtx: unknown) => string;
+}
+
+export async function executeSubagentOutput(
+  params: OutputActionParams | undefined,
+  toolCtx: unknown,
+  deps: OutputActionDeps,
+): Promise<OutputActionResult> {
+  const rawId = String(params?.agentId ?? params?.taskId ?? '').trim();
+  if (!rawId) return toolError('Error: missing agentId for output (see action list)') as OutputActionResult;
+
+  const cwd = deps.getCwd(toolCtx);
+  const resolved = deps.resolveEntry(rawId, cwd);
+  if ('error' in resolved) return toolError(resolved.error) as OutputActionResult;
+
+  const entry = resolved.entry;
+  let agentState: HerdrAgentState | null = null;
+  let askFlag: string | null = null;
+  try {
+    const agents = await deps.client.listAgents();
+    const agent = agents.find((candidate) => candidate.paneId === entry.paneId);
+    agentState = agent?.status ?? null;
+    askFlag = agent?.tokens?.['pi-ask'] ?? null;
+  } catch {
+    /* Best effort: output remains useful without live status. */
+  }
+  if (!askFlag && agentState === 'blocked') {
+    try {
+      askFlag = await deps.readAskFlag(entry.paneId);
+    } catch {
+      /* Best effort. */
+    }
+  }
+
+  const status = resolveSubagentStatus({
+    localStatus: entry.status,
+    herdrStatus: agentState,
+    hasAskFlag: Boolean(askFlag),
+  });
+
+  let rawRead: { text: string; revision: number; truncated: boolean };
+  try {
+    rawRead = await readSubagentOutput(deps.client, entry.paneId);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return toolError(`Error: failed to read output for subagent ${entry.paneId}: ${message}`) as OutputActionResult;
+  }
+
+  const prevCursor = deps.outputCursors.get(entry.paneId);
+  const maxChars = typeof params?.max_chars === 'number'
+    ? params.max_chars
+    : typeof params?.maxChars === 'number' ? params.maxChars : undefined;
+  const deltaResult = computeSubagentOutputDelta(prevCursor, rawRead.text, { maxChars });
+  deps.outputCursors.set(entry.paneId, deltaResult.nextCursor);
+
+  const formatted = formatSubagentOutput({
+    paneId: entry.paneId,
+    status,
+    revision: rawRead.revision,
+    bufferTruncated: rawRead.truncated,
+    deltaResult,
+    askQuestion: askFlag,
+  });
+
+  return {
+    content: [{ type: 'text', text: formatted }],
+    details: {
+      paneId: entry.paneId,
+      status,
+      revision: rawRead.revision,
+      truncated: rawRead.truncated || deltaResult.truncated,
+      restart: deltaResult.restart,
+      deltaLength: deltaResult.delta.length,
+    },
+  };
+}

package/src/subagent-output-adapter.ts

@@ -0,0 +1,27 @@
+/**
+ * Herdr output-read adapter for subagents.
+ *
+ * Newer herdr exposes agent.read; older versions only expose pane.read. Prefer the semantic agent
+ * endpoint and fall back to the pane endpoint so output observation stays version-compatible.
+ */
+import type { HerdrClientLike } from './herdr-client.ts';
+
+export interface SubagentOutputRead {
+  text: string;
+  revision: number;
+  truncated: boolean;
+}
+
+export async function readSubagentOutput(
+  client: HerdrClientLike,
+  paneId: string,
+): Promise<SubagentOutputRead> {
+  if (typeof client.readAgent === 'function') {
+    try {
+      return await client.readAgent(paneId, { source: 'recent', stripAnsi: true });
+    } catch {
+      return await client.readPane(paneId, { source: 'recent', stripAnsi: true });
+    }
+  }
+  return await client.readPane(paneId, { source: 'recent', stripAnsi: true });
+}

package/src/subagent-output-core.ts

@@ -0,0 +1,263 @@
+/**
+ * subagent-output-core.ts
+ *
+ * Pure functions for subagent incremental output extraction:
+ *  - Cursor management (in-memory per-pane tail tracking)
+ *  - Longest common suffix/prefix delta computation
+ *  - Boundary handling for scrolling, clear-screen, repeated text (graceful degradation with restart: true)
+ *  - Bounded character budgeting and metadata formatting
+ */
+import type { HerdrAgentState } from './herdr-client.ts';
+import type { SubEntry } from './subagent-core.ts';
+
+export const OUTPUT_DEFAULT_MAX_CHARS = 6000;
+export const OUTPUT_HARD_CAP_CHARS = 16000;
+export const OUTPUT_MIN_OVERLAP = 16;
+export const OUTPUT_TAIL_CHARS = 500;
+
+export type SubagentStatus = 'running' | 'idle' | 'blocked' | 'settled';
+
+export interface SubagentOutputCursor {
+  /** Suffix of previous full text used for boundary matching */
+  tail: string;
+  /** Length of previous full text */
+  fullLength: number;
+}
+
+export interface SubagentOutputDeltaOptions {
+  /** Max characters of delta to return (default: 6000) */
+  maxChars?: number;
+  /** Minimum overlap length required for partial scroll matching (default: 16) */
+  minOverlap?: number;
+  /** Length of tail to retain in cursor (default: 500) */
+  tailChars?: number;
+}
+
+export interface SubagentOutputDeltaResult {
+  /** The new output text (or full bounded text on initial/restart) */
+  delta: string;
+  /** Whether the increment could not be determined reliably (scrolled away, cleared, ambiguous repeat) */
+  restart: boolean;
+  /** Whether delta was truncated to maxChars */
+  truncated: boolean;
+  /** New cursor to save for next call */
+  nextCursor: SubagentOutputCursor;
+}
+
+/**
+ * Extract tail characters from a text buffer for cursor matching.
+ */
+export function extractTail(text: string, tailChars = OUTPUT_TAIL_CHARS): string {
+  if (text.length <= tailChars) return text;
+  return text.slice(text.length - tailChars);
+}
+
+/**
+ * Bound text to a maximum character budget, retaining the tail (most recent output).
+ */
+export function boundText(text: string, maxChars: number): { text: string; truncated: boolean } {
+  if (text.length <= maxChars) {
+    return { text, truncated: false };
+  }
+  return {
+    text: text.slice(text.length - maxChars),
+    truncated: true,
+  };
+}
+
+/**
+ * Pure function: Given previous cursor (tail + fullLength) and current full buffer text,
+ * compute the incremental delta since last read.
+ *
+ * Boundary handling:
+ *  1. Initial read (prevCursor is null/empty): returns full bounded text, restart=false.
+ *  2. No change: fullLength and tail match, delta is empty, restart=false.
+ *  3. Normal append: prevTail appears uniquely in currText -> delta is text after prevTail.
+ *  4. Repeated text: prevTail appears multiple times -> ambiguous, returns full bounded text with restart=true.
+ *  5. Partial buffer scroll: prevTail partially scrolled off top -> longest suffix of prevTail
+ *     matching prefix of currText (>= minOverlap) identifies boundary.
+ *  6. Full scroll / clear screen: no valid overlap found -> returns full bounded text with restart=true.
+ */
+export function computeSubagentOutputDelta(
+  prevCursor: SubagentOutputCursor | null | undefined,
+  currText: string,
+  options?: SubagentOutputDeltaOptions,
+): SubagentOutputDeltaResult {
+  const rawMaxChars = options?.maxChars ?? OUTPUT_DEFAULT_MAX_CHARS;
+  const maxChars = Math.max(1, Math.min(rawMaxChars, OUTPUT_HARD_CAP_CHARS));
+  const minOverlap = options?.minOverlap ?? OUTPUT_MIN_OVERLAP;
+  const tailChars = options?.tailChars ?? OUTPUT_TAIL_CHARS;
+
+  // Case 1: First call (no previous cursor)
+  if (!prevCursor || !prevCursor.tail) {
+    const bounded = boundText(currText, maxChars);
+    return {
+      delta: bounded.text,
+      restart: false,
+      truncated: bounded.truncated,
+      nextCursor: {
+        tail: extractTail(currText, tailChars),
+        fullLength: currText.length,
+      },
+    };
+  }
+
+  const prevTail = prevCursor.tail;
+
+  // Case 2: Exact same content (no new output)
+  if (currText.length === prevCursor.fullLength && currText.endsWith(prevTail)) {
+    return {
+      delta: '',
+      restart: false,
+      truncated: false,
+      nextCursor: prevCursor,
+    };
+  }
+
+  // Case 3: prevTail appears in currText
+  const firstIdx = currText.indexOf(prevTail);
+  const lastIdx = currText.lastIndexOf(prevTail);
+
+  if (firstIdx !== -1) {
+    // 3a: Ambiguous duplicate occurrences in current text
+    if (firstIdx !== lastIdx) {
+      const bounded = boundText(currText, maxChars);
+      return {
+        delta: bounded.text,
+        restart: true,
+        truncated: bounded.truncated,
+        nextCursor: {
+          tail: extractTail(currText, tailChars),
+          fullLength: currText.length,
+        },
+      };
+    }
+
+    // 3b: Unique match
+    const rawDelta = currText.slice(firstIdx + prevTail.length);
+    if (rawDelta.length === 0) {
+      return {
+        delta: '',
+        restart: false,
+        truncated: false,
+        nextCursor: prevCursor,
+      };
+    }
+
+    const bounded = boundText(rawDelta, maxChars);
+    return {
+      delta: bounded.text,
+      restart: false,
+      truncated: bounded.truncated,
+      nextCursor: {
+        tail: extractTail(currText, tailChars),
+        fullLength: currText.length,
+      },
+    };
+  }
+
+  // Case 4: prevTail is not found in full. Check if a suffix of prevTail matches a prefix of currText
+  // (terminal buffer scrolled lines off the top).
+  let longestOverlap = 0;
+  const maxPossibleOverlap = Math.min(prevTail.length - 1, currText.length);
+  const effectiveMinOverlap = Math.min(minOverlap, prevTail.length);
+
+  for (let k = maxPossibleOverlap; k >= effectiveMinOverlap; k--) {
+    const suffix = prevTail.slice(prevTail.length - k);
+    if (currText.startsWith(suffix)) {
+      longestOverlap = k;
+      break;
+    }
+  }
+
+  if (longestOverlap >= effectiveMinOverlap) {
+    const rawDelta = currText.slice(longestOverlap);
+    const bounded = boundText(rawDelta, maxChars);
+    return {
+      delta: bounded.text,
+      restart: false,
+      truncated: bounded.truncated,
+      nextCursor: {
+        tail: extractTail(currText, tailChars),
+        fullLength: currText.length,
+      },
+    };
+  }
+
+  // Case 5: Clear screen or full scroll out -> degraded reset
+  const bounded = boundText(currText, maxChars);
+  return {
+    delta: bounded.text,
+    restart: true,
+    truncated: bounded.truncated,
+    nextCursor: {
+      tail: extractTail(currText, tailChars),
+      fullLength: currText.length,
+    },
+  };
+}
+
+/**
+ * Resolve subagent semantic status from local subs registry and herdr agent state.
+ */
+export function resolveSubagentStatus(opts: {
+  localStatus: SubEntry['status'];
+  herdrStatus?: HerdrAgentState | null;
+  hasAskFlag?: boolean;
+}): SubagentStatus {
+  if (opts.hasAskFlag || opts.herdrStatus === 'blocked') {
+    return 'blocked';
+  }
+  if (opts.herdrStatus === 'working') {
+    return 'running';
+  }
+  if (opts.localStatus === 'settled' || opts.localStatus === 'closed' || opts.herdrStatus === 'done') {
+    return 'settled';
+  }
+  if (opts.herdrStatus === 'idle') {
+    return 'idle';
+  }
+  if (opts.localStatus === 'running') {
+    return 'running';
+  }
+  return 'running';
+}
+
+export interface FormatSubagentOutputOpts {
+  paneId: string;
+  status: SubagentStatus;
+  revision: number;
+  bufferTruncated: boolean;
+  deltaResult: SubagentOutputDeltaResult;
+  askQuestion?: string | null;
+}
+
+/**
+ * Format subagent output for display to the master model.
+ */
+export function formatSubagentOutput(opts: FormatSubagentOutputOpts): string {
+  const parts: string[] = [];
+  const metaItems: string[] = [
+    `pane: ${opts.paneId}`,
+    `status: ${opts.status}${opts.status === 'blocked' && opts.askQuestion ? ` (question: "${opts.askQuestion}")` : ''}`,
+    `revision: ${opts.revision}`,
+  ];
+
+  if (opts.deltaResult.restart) {
+    metaItems.push('restart: true (buffer reset or scrolled)');
+  }
+  if (opts.bufferTruncated || opts.deltaResult.truncated) {
+    metaItems.push('truncated: true');
+  }
+
+  const header = `[Subagent Output | ${metaItems.join(' | ')}]`;
+  parts.push(header);
+
+  if (opts.deltaResult.delta.length === 0) {
+    parts.push('(no new output since last read)');
+  } else {
+    parts.push(opts.deltaResult.delta);
+  }
+
+  return parts.join('\n');
+}