pi-pier 0.2.6 → 0.3.0

package/src/subagent-poll-loop.ts

@@ -8,22 +8,25 @@ import { appendFileSync } from 'node:fs';
 import type { Context } from '@deepseek-ai/cordis';
 import type { HerdrClientLike, HerdrAgentState } from './herdr-client.ts';
 import { applyReportedSessionFile } from './history-store.ts';
-import { runtimePolicy } from './runtime-policy.ts';
+import { runtimePolicy, type RuntimePolicy } from './runtime-policy.ts';
 import { mountSubagentScope } from './subagent-scope.ts';
 import {
   OBSERVATION_TICK_MS,
   TAKEOVER_RECHECK_MS,
+  buildSettlementNoticeText,
+  formatObservationTimeoutNotice,
+  formatPaneClosedNotice,
+  isSettlementCandidate,
   planBlockedGate,
   planObservationTick,
   planTakeoverTick,
   planVacuumTick,
 } from './subagent-poller.ts';
 import { buildBlockedGateNotice, type SubEntry } from './subagent-core.ts';
-import { formatSettlementNotice } from './vocab.ts';
 import type { SessionIo } from './subagent-session-io.ts';
 import type { GitIo } from './subagent-git-io.ts';
 
-function sleep(ms: number): Promise<void> {
+export function sleep(ms: number): Promise<void> {
   const wait = Promise.withResolvers<void>();
   setTimeout(wait.resolve, ms);
   return wait.promise;
@@ -43,20 +46,29 @@ export interface PollerHost {
   reconcileOnSettlement(description: string, outcome: 'settled' | 'failed'): string[];
   withReconcileNotes(base: string, notes: readonly string[]): string;
   claimSettleNotice(key: string): boolean;
+  /** Optional sleep seam for timing control without real delays */
+  sleep?: (ms: number) => Promise<void>;
+  /** Optional clock seam for deterministic virtual timestamps */
+  now?: () => number;
+  /** Optional runtime policy overrides for testing */
+  policy?: Partial<RuntimePolicy>;
 }
 
 export interface Poller {
-  startPoller(paneId: string, cwd: string, spawnedAt: number, injectTs: number, description: string, requestId: string): void;
+  startPoller(paneId: string, cwd: string, spawnedAt: number, injectTs: number, description: string, requestId: string): Promise<void>;
   readonly pollers: Set<string>;
 }
 
 export function createPoller(h: PollerHost): Poller {
   const pollers = new Set<string>();
   const subScopes = new Map<string, { dispose: () => Promise<void> }>();
-  const observeWindowMs = runtimePolicy.observationWindowMs;
-  const machineInjectGraceMs = runtimePolicy.settlementWindowMs;
-  const takeoverIdleMs = runtimePolicy.settlementWindowMs;
-  const timeoutMs = runtimePolicy.subagentTimeoutMs;
+  const doSleep = h.sleep ?? sleep;
+  const now = h.now ?? Date.now;
+  const observeWindowMs = h.policy?.observationWindowMs ?? runtimePolicy.observationWindowMs;
+  const machineInjectGraceMs = h.policy?.settlementWindowMs ?? runtimePolicy.settlementWindowMs;
+  const takeoverIdleMs = h.policy?.settlementWindowMs ?? runtimePolicy.settlementWindowMs;
+  const timeoutMs = h.policy?.subagentTimeoutMs ?? runtimePolicy.subagentTimeoutMs;
+  const pollIntervalMs = h.policy?.pollIntervalMs ?? runtimePolicy.pollIntervalMs;
 
   async function pollLoop(
     paneId: string,
@@ -67,10 +79,10 @@ export function createPoller(h: PollerHost): Poller {
     requestId: string,
   ): Promise<void> {
     void spawnedAt;
-    const startedAt = Date.now();
-    let lastActivityAt = Date.now();
+    const startedAt = now();
+    let lastActivityAt = now();
     const pollTrace = process.env.PI_HERDR_TRACE
-      ? (msg: string) => { try { appendFileSync(process.env.PI_HERDR_TRACE!, `d98poll ${Date.now()} ${paneId} ${msg}\n`); } catch { /* best-effort */ } }
+      ? (msg: string) => { try { appendFileSync(process.env.PI_HERDR_TRACE!, `d98poll ${now()} ${paneId} ${msg}\n`); } catch { /* best-effort */ } }
       : null;
     try {
       while (true) {
@@ -85,11 +97,11 @@ export function createPoller(h: PollerHost): Poller {
               currentStatus: agent?.status ?? null,
               previousStatus: entry.lastAgentStatus,
               idleStartedAt: entry.observationStartedAt,
-              now: Date.now(),
+              now: now(),
               idleMs: takeoverIdleMs,
             });
             if (tick.kind === 'start-idle') {
-              entry.observationStartedAt = Date.now();
+              entry.observationStartedAt = now();
               entry.lastAgentStatus = 'idle';
               h.persistSubs();
             } else if (tick.kind === 'return-control') {
@@ -106,14 +118,14 @@ export function createPoller(h: PollerHost): Poller {
             /* status probe failure must not stop the poller */
           }
           if (entry.userTakeover) {
-            await sleep(TAKEOVER_RECHECK_MS);
+            await doSleep(TAKEOVER_RECHECK_MS);
             continue;
           }
         }
 
         let state: HerdrAgentState | null;
         try {
-          state = await h.client.waitAgent(paneId, ['idle', 'done', 'blocked'], runtimePolicy.pollIntervalMs);
+          state = await h.client.waitAgent(paneId, ['idle', 'done', 'blocked'], pollIntervalMs);
         } catch {
           state = null;
         }
@@ -133,22 +145,22 @@ export function createPoller(h: PollerHost): Poller {
         if (gate.kind === 'clear-gate') h.blockedGateNotified.delete(paneId);
         if (state === 'idle' || state === 'done') {
           const s = await h.session.subSessionState(paneId, cwd, injectTs);
-          pollTrace?.(`state=${state} text=${s.text ? s.text.length : 'null'} pend=${s.pendingTool} act=${s.activity} obs=${String(entry.observationStartedAt ?? null)} takeover=${String(entry.userTakeover === true)}`);
-          if (s.text || (!s.pendingTool && s.activity)) {
+          pollTrace?.(`state=${state} text=${s.text ? s.text.length : 'null'} pend=${s.pendingTool} act=${s.activity} obs=${String(entry.observationStartedAt ?? null)} takeover=${String(Boolean(entry.userTakeover))}`);
+          if (isSettlementCandidate(s)) {
             const closing = s.text;
             const obs = planObservationTick({
               observationStartedAt: entry.observationStartedAt,
-              now: Date.now(),
+              now: now(),
               windowMs: observeWindowMs,
               agentStatus: null,
-              machineInjectAgoMs: Date.now() - (h.lastMachineInjectAt.get(paneId) ?? 0),
+              machineInjectAgoMs: now() - (h.lastMachineInjectAt.get(paneId) ?? 0),
               machineInjectGraceMs,
             });
             if (obs.kind === 'start-observation') {
-              entry.observationStartedAt = Date.now();
+              entry.observationStartedAt = now();
               entry.lastAgentStatus = 'idle';
               h.persistSubs();
-              await sleep(OBSERVATION_TICK_MS);
+              await doSleep(OBSERVATION_TICK_MS);
               continue;
             }
             let agentStatus: string | null = null;
@@ -160,27 +172,27 @@ export function createPoller(h: PollerHost): Poller {
             }
             const obs2 = planObservationTick({
               observationStartedAt: entry.observationStartedAt,
-              now: Date.now(),
+              now: now(),
               windowMs: observeWindowMs,
               agentStatus,
-              machineInjectAgoMs: Date.now() - (h.lastMachineInjectAt.get(paneId) ?? 0),
+              machineInjectAgoMs: now() - (h.lastMachineInjectAt.get(paneId) ?? 0),
               machineInjectGraceMs,
             });
             if (obs2.kind === 'user-takeover') {
               entry.userTakeover = true;
-              entry.observationStartedAt = Date.now();
+              entry.observationStartedAt = now();
               entry.lastAgentStatus = 'working';
               h.persistSubs();
               continue;
             }
             if (obs2.kind === 'machine-inject-reset') {
-              entry.observationStartedAt = Date.now();
+              entry.observationStartedAt = now();
               h.persistSubs();
-              await sleep(OBSERVATION_TICK_MS);
+              await doSleep(OBSERVATION_TICK_MS);
               continue;
             }
             if (obs2.kind === 'wait') {
-              await sleep(OBSERVATION_TICK_MS);
+              await doSleep(OBSERVATION_TICK_MS);
               continue;
             }
             entry.observationStartedAt = null;
@@ -191,12 +203,15 @@ export function createPoller(h: PollerHost): Poller {
               );
             }
             entry.status = 'consumed';
-            entry.consumedAt = Date.now();
+            entry.consumedAt = now();
+            // A3: this path consumed the sub too - persist, or the session snapshot keeps it
+            // "running" and a restart replays a ghost subagent into list/settle-wake/zombie sweep.
+            h.persistSubs();
             h.writeHistory(entry, { outcome: closing }, 'poll-settle');
             const notes = h.reconcileOnSettlement(description, 'settled');
             const statLine = await h.git.worktreeStatLine(entry);
             const notice = h.withReconcileNotes(
-              formatSettlementNotice(`${paneId} (${description})`, closing) + (statLine ? `\n${statLine}` : ''),
+              buildSettlementNoticeText(`${paneId} (${description})`, closing, statLine),
               notes,
             );
             if (h.claimSettleNotice(`${paneId}:${requestId}`)) {
@@ -211,26 +226,26 @@ export function createPoller(h: PollerHost): Poller {
         }
         let alive = false;
         try {
-          alive = (await h.client.listAgents()).some((a) => a.paneId === paneId);
+          alive = (await h.client.listPanes()).some((p) => p.paneId === paneId);
         } catch {
           alive = true;
         }
         const vacuum = planVacuumTick({
           waitState: state,
           paneAlive: alive,
-          now: Date.now(),
+          now: now(),
           lastActivityAt,
           timeoutMs,
         });
-        if (vacuum.refreshActivity) lastActivityAt = Date.now();
+        if (vacuum.refreshActivity) lastActivityAt = now();
         if (vacuum.action === 'pane-closed') {
           entry.status = 'consumed';
-          entry.consumedAt = Date.now();
+          entry.consumedAt = now();
           h.persistSubs();
           h.writeHistory(entry, { outcome: 'pane closed before settling' }, 'poll-pane-closed');
           const notes = h.reconcileOnSettlement(description, 'failed');
           const notice = h.withReconcileNotes(
-            `Background subagent ${paneId} (${description}) stopped before settling (its pane closed).`,
+            formatPaneClosedNotice(paneId, description),
             notes,
           );
           try {
@@ -240,12 +255,17 @@ export function createPoller(h: PollerHost): Poller {
         }
         if (vacuum.action === 'timeout') {
           entry.status = 'consumed';
-          entry.consumedAt = Date.now();
+          entry.consumedAt = now();
           h.persistSubs();
           h.writeHistory(entry, { outcome: 'observation timeout' }, 'poll-timeout');
           const notes = h.reconcileOnSettlement(description, 'failed');
           const notice = h.withReconcileNotes(
-            `Background subagent ${paneId} (${description}) has shown no progress for ${Math.round((Date.now() - lastActivityAt) / 1000)}s (observed since ${new Date(startedAt).toISOString()}). Run subagent(action: "list") to check its live state; if it is working, let it run — its settlement notice will arrive automatically. Do not sleep-wait.`,
+            formatObservationTimeoutNotice({
+              paneId,
+              description,
+              idleSeconds: Math.round((now() - lastActivityAt) / 1000),
+              startedAtIso: new Date(startedAt).toISOString(),
+            }),
             notes,
           );
           try {
@@ -259,10 +279,10 @@ export function createPoller(h: PollerHost): Poller {
     }
   }
 
-  function startPoller(paneId: string, cwd: string, spawnedAt: number, injectTs: number, description: string, requestId: string): void {
-    if (pollers.has(paneId)) return;
+  function startPoller(paneId: string, cwd: string, spawnedAt: number, injectTs: number, description: string, requestId: string): Promise<void> {
+    if (pollers.has(paneId)) return Promise.resolve();
     pollers.add(paneId);
-    void (async () => {
+    return (async () => {
       try {
         if (!subScopes.has(paneId)) {
           const fiber = await mountSubagentScope(h.sessionRoot, paneId, {

package/src/subagent-poller.ts

@@ -6,6 +6,8 @@
  * window explicit and unit-testable without a live pane.
  */
 
+import { formatSettlementNotice } from './vocab.ts';
+
 export const TAKEOVER_RECHECK_MS = 5_000;
 export const OBSERVATION_TICK_MS = 1_000;
 
@@ -88,3 +90,47 @@ export function planVacuumTick(input: {
   if (input.now - lastActivityAt > input.timeoutMs) return { refreshActivity, action: 'timeout' };
   return { refreshActivity, action: 'continue' };
 }
+
+/**
+ * Determine whether subSessionState qualifies as an observation candidate.
+ *
+ * A16: closing text (only produced by a terminal assistant message) OR an ENDED turn settles.
+ * Merely having an assistant message — the state a worker is in between tool calls, while the next
+ * assistant message streams — must NOT qualify: on 2026-09-13 three live workers were announced as
+ * "finished … left no closing message" and one was closed mid-task by GC afterwards.
+ */
+export function isSettlementCandidate(input: {
+  text: string | null;
+  pendingTool: boolean;
+  activity: boolean;
+  turnEnded?: boolean;
+}): boolean {
+  if (input.text) return true;
+  return !input.pendingTool && input.turnEnded === true;
+}
+
+/** Formats the combined settlement notice with optional git worktree stat. */
+export function buildSettlementNoticeText(
+  agentLabel: string,
+  closing: string | null,
+  statLine: string | null,
+): string {
+  const base = formatSettlementNotice(agentLabel, closing);
+  return statLine ? `${base}\n${statLine}` : base;
+}
+
+/** Formats notice when background subagent pane was closed prematurely. */
+export function formatPaneClosedNotice(paneId: string, description: string): string {
+  return `Background subagent ${paneId} (${description}) stopped before settling (its pane closed).`;
+}
+
+/** Formats notice when background subagent exceeded observation timeout. */
+export function formatObservationTimeoutNotice(input: {
+  paneId: string;
+  description: string;
+  idleSeconds: number;
+  startedAtIso: string;
+}): string {
+  return `Background subagent ${input.paneId} (${input.description}) has shown no progress for ${input.idleSeconds}s (observed since ${input.startedAtIso}). Run subagent(action: "list") to check its live state; if it is working, let it run — its settlement notice will arrive automatically. Do not sleep-wait.`;
+}
+

package/src/subagent-ready.ts

@@ -0,0 +1,89 @@
+/**
+ * A14: spawn readiness had a single 30 s ping window and reported failures as one bare line
+ * ("subagent pane wD:pJ pipe not ready within 30000ms"), even when the child process had already
+ * died with a stack trace on its screen. With 3–4 concurrent isolated workers (each running heavy
+ * commands) that window was hit repeatedly, and the diagnosis cost far more than the retry would.
+ *
+ * This module is the pure half: how long to wait, how to back off, when to give up early
+ * (the pane is gone — no point in waiting for a pipe that cannot appear) and how to word the
+ * failure so the model and the human can act on it.
+ */
+
+/** Ping cadence: quick first probes, then exponential backoff capped at `READY_MAX_INTERVAL_MS`. */
+export const READY_BASE_INTERVAL_MS = 500;
+export const READY_MAX_INTERVAL_MS = 4000;
+
+/** Wait this long between two samples of the child pane's liveness (pane.list + pane read). */
+export const READY_LIVENESS_SAMPLE_MS = 2500;
+
+export interface ReadyProbe {
+  /** The pane still exists in pane.list (unknown shells count as alive). */
+  readonly paneAlive: boolean;
+  /** Tail of the pane's screen, used only to explain a failure. */
+  readonly tail?: string | null;
+}
+
+export type ReadyAttemptPlan =
+  | { readonly kind: 'ready' }
+  | { readonly kind: 'retry'; readonly delayMs: number }
+  | { readonly kind: 'give-up'; readonly reason: 'pane-gone' | 'timeout' };
+
+/**
+ * Decide one readiness attempt.
+ * `alive` is tri-state on purpose: an unavailable liveness probe (`null`) must not be read as death,
+ * otherwise a slow herdr socket would fail spawns that are merely slow to boot.
+ */
+export function planReadyAttempt(opts: {
+  elapsedMs: number;
+  attempt: number;
+  timeoutMs: number;
+  alive: boolean | null;
+  ready: boolean;
+}): ReadyAttemptPlan {
+  if (opts.ready) return { kind: 'ready' };
+  if (opts.alive === false) return { kind: 'give-up', reason: 'pane-gone' };
+  if (opts.elapsedMs >= opts.timeoutMs) return { kind: 'give-up', reason: 'timeout' };
+  return { kind: 'retry', delayMs: readyBackoffMs(opts.attempt) };
+}
+
+/** Exponential backoff with a cap: 500ms, 1s, 2s, 4s, 4s, … */
+export function readyBackoffMs(attempt: number, baseMs = READY_BASE_INTERVAL_MS, capMs = READY_MAX_INTERVAL_MS): number {
+  const n = Math.max(0, Math.floor(attempt));
+  return Math.min(capMs, baseMs * 2 ** n);
+}
+
+/** How many characters of pane tail to attach to a failure (enough for a stack trace head). */
+export const READY_TAIL_CHARS = 1200;
+
+export interface ReadyFailure {
+  readonly paneId: string;
+  readonly reason: 'pane-gone' | 'timeout';
+  readonly elapsedMs: number;
+  readonly timeoutMs: number;
+  /** Some agent states the wait observed (working/idle/…), for the "agent never reported" case. */
+  readonly lastStatus?: string | null;
+  readonly tail?: string | null;
+  /** True when the child process exited (pane gone) rather than never starting to report. */
+  readonly hint?: string | null;
+}
+
+/**
+ * Failure text for the model. The three cases it must distinguish:
+ *  1. the pane died (usually the child crashed — the tail carries the reason, cf. A13's stack trace);
+ *  2. the pane is alive but never opened its pipe (extension failed to load, wrong pane env);
+ *  3. the pane is alive and its agent is working, just slower than the timeout (retry is safe).
+ */
+export function readyFailureText(failure: ReadyFailure): string {
+  const seconds = Math.round(failure.elapsedMs / 1000);
+  const head = failure.reason === 'pane-gone'
+    ? `subagent pane ${failure.paneId} exited before its pipe became ready (waited ${seconds}s)`
+    : `subagent pane ${failure.paneId} pipe not ready within ${seconds}s (limit ${Math.round(failure.timeoutMs / 1000)}s)`;
+  const why = failure.reason === 'pane-gone'
+    ? 'The child process is gone — its last output below usually carries the reason.'
+    : failure.lastStatus === 'working'
+      ? 'The pane is alive and working, so the prompt may simply be slow to boot; retrying the same call is safe.'
+      : 'The pane is alive but never registered its pipe — the child pi process may still be starting, or it failed to load the pier extension.';
+  const tail = failure.tail ? `\nlast output of ${failure.paneId}:\n${failure.tail}` : '';
+  const hint = failure.hint ? `\n${failure.hint}` : '';
+  return `${head}\n${why}${hint}${tail}`;
+}

package/src/subagent-registry.ts

@@ -0,0 +1,70 @@
+import type { HerdrClientLike } from './herdr-client.ts';
+import { foldSubsRegistry, makeRegistry, SUBS_CUSTOM_TYPE, type SubEntry } from './subagent-core.ts';
+import { swallow } from './swallow.ts';
+
+export interface SubagentRegistryHost {
+  pi: { appendEntry?: (customType: string, data: unknown) => void };
+  client: HerdrClientLike;
+  subs: Map<string, SubEntry>;
+  writeHistory: (entry: SubEntry, patch?: { status?: SubEntry['status']; closedAt?: number }, via?: string) => void;
+}
+
+export interface SubagentRegistry {
+  /** Append the registry snapshot to the session branch; duplicate snapshots are skipped (O1). */
+  persist(): void;
+  /** Replay `pi-herdr.subs` entries from the session branch into the live map. */
+  rebuild(eventCtx: unknown): void;
+  /** B6: close running rows whose pane herdr no longer lists. */
+  sweepZombieRunning(): Promise<void>;
+}
+
+/** Owns durable registry projection and startup recovery, separate from tool actions. */
+export function createSubagentRegistry(host: SubagentRegistryHost): SubagentRegistry {
+  let lastSnapshot = '';
+
+  function persist(): void {
+    try {
+      const registry = makeRegistry([...host.subs.values()]);
+      const snapshot = JSON.stringify(registry);
+      if (snapshot === lastSnapshot) return;
+      lastSnapshot = snapshot;
+      host.pi.appendEntry?.(SUBS_CUSTOM_TYPE, registry);
+    } catch (err) {
+      // Best-effort: session logging must not break delegation, but a ghost running subagent is the
+      // symptom when this fails silently, so keep the reason queryable (B9).
+      swallow('subagent.persist-subs', err);
+    }
+  }
+
+  function rebuild(eventCtx: unknown): void {
+    try {
+      const entries = (eventCtx as { sessionManager?: { getBranch?: () => readonly unknown[] } })
+        ?.sessionManager?.getBranch?.() ?? [];
+      const registry = foldSubsRegistry(entries as Parameters<typeof foldSubsRegistry>[0]);
+      for (const entry of registry.subs) host.subs.set(entry.paneId, entry);
+      lastSnapshot = ''; // Branch replay replaced live state; force the next persist.
+    } catch {
+      /* Registry recovery failure must not block the live session. */
+    }
+  }
+
+  async function sweepZombieRunning(): Promise<void> {
+    if (!host.client.available || host.subs.size === 0) return;
+    let livePaneIds: ReadonlySet<string>;
+    try {
+      livePaneIds = new Set((await host.client.listPanes()).map((pane) => pane.paneId));
+    } catch {
+      return; // Do not close agents when the liveness lookup itself failed.
+    }
+    let changed = false;
+    for (const [paneId, entry] of host.subs) {
+      if (entry.status !== 'running' || livePaneIds.has(paneId)) continue;
+      entry.status = 'closed';
+      host.writeHistory(entry, { status: 'closed', closedAt: Date.now() }, 'zombie-sweep');
+      changed = true;
+    }
+    if (changed) persist();
+  }
+
+  return { persist, rebuild, sweepZombieRunning };
+}

package/src/subagent-resolution.ts

@@ -0,0 +1,41 @@
+/**
+ * Subagent task-id lookup rules.
+ *
+ * Kept separate from the Cordis plugin so prefix resolution remains usable without mounting the
+ * master tree and can be verified independently from pane lifecycle code.
+ */
+
+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 against known candidates.
+ *
+ * Exact matches are accepted regardless of length. Prefix matching requires four characters and
+ * rejects ambiguity with a sorted candidate list.
+ */
+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 };
+}

package/src/subagent-scope.ts

@@ -22,12 +22,14 @@ export async function mountSubagentScope(
   paneId: string,
   hooks: ScopeHooks = {},
 ) {
+  // Why no second argument: the pinned cordis version takes only the plugin object here; the pane id
+  // already identifies the scope through the plugin name and the effect label.
   return root.plugin({
     name: `subagent:${paneId}`,
     apply(ctx: Context) {
       ctx.effect(() => () => { hooks.onDispose?.(); }, `subagent:${paneId}`);
     },
-  }, { paneId });
+  });
 }
 
 export async function disposeSessionRoot(root: Context): Promise<void> {