pi-pier 0.3.0 → 0.3.1

package/src/subagent-poll-loop.ts

@@ -1,305 +0,0 @@
-/**
- * Background settlement poller (takeover, blocked gate, observation, vacuum).
- *
- * Why: planners already live in subagent-poller.ts; this adapter owns the
- * herdr/session I/O loop and pane-scope lifecycle so the plugin only starts it.
- */
-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, 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 type { SessionIo } from './subagent-session-io.ts';
-import type { GitIo } from './subagent-git-io.ts';
-
-export function sleep(ms: number): Promise<void> {
-  const wait = Promise.withResolvers<void>();
-  setTimeout(wait.resolve, ms);
-  return wait.promise;
-}
-
-export interface PollerHost {
-  client: HerdrClientLike;
-  sessionRoot: Context;
-  subs: Map<string, SubEntry>;
-  persistSubs(): void;
-  writeHistory(e: SubEntry, patch?: { outcome?: string | null; status?: SubEntry['status']; closedAt?: number }, via?: string): void;
-  blockedGateNotified: Set<string>;
-  lastMachineInjectAt: Map<string, number>;
-  session: SessionIo;
-  git: GitIo;
-  injectNotice(content: string): Promise<void>;
-  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): 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 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,
-    cwd: string,
-    spawnedAt: number,
-    injectTs: number,
-    description: string,
-    requestId: string,
-  ): Promise<void> {
-    void spawnedAt;
-    const startedAt = now();
-    let lastActivityAt = now();
-    const pollTrace = process.env.PI_HERDR_TRACE
-      ? (msg: string) => { try { appendFileSync(process.env.PI_HERDR_TRACE!, `d98poll ${now()} ${paneId} ${msg}\n`); } catch { /* best-effort */ } }
-      : null;
-    try {
-      while (true) {
-        const entry = h.subs.get(paneId);
-        if (!entry || entry.status === 'settled') return;
-
-        if (entry.userTakeover) {
-          try {
-            const agents = await h.client.listAgents();
-            const agent = agents.find((a) => a.paneId === paneId);
-            const tick = planTakeoverTick({
-              currentStatus: agent?.status ?? null,
-              previousStatus: entry.lastAgentStatus,
-              idleStartedAt: entry.observationStartedAt,
-              now: now(),
-              idleMs: takeoverIdleMs,
-            });
-            if (tick.kind === 'start-idle') {
-              entry.observationStartedAt = now();
-              entry.lastAgentStatus = 'idle';
-              h.persistSubs();
-            } else if (tick.kind === 'return-control') {
-              entry.userTakeover = false;
-              entry.observationStartedAt = null;
-              entry.lastAgentStatus = null;
-              h.persistSubs();
-            } else if (tick.kind === 'hold' && tick.clearIdleTimer) {
-              entry.lastAgentStatus = tick.lastAgentStatus;
-              entry.observationStartedAt = null;
-              h.persistSubs();
-            }
-          } catch {
-            /* status probe failure must not stop the poller */
-          }
-          if (entry.userTakeover) {
-            await doSleep(TAKEOVER_RECHECK_MS);
-            continue;
-          }
-        }
-
-        let state: HerdrAgentState | null;
-        try {
-          state = await h.client.waitAgent(paneId, ['idle', 'done', 'blocked'], pollIntervalMs);
-        } catch {
-          state = null;
-        }
-        const gate = planBlockedGate(state, h.blockedGateNotified.has(paneId));
-        if (gate.kind === 'stay-blocked') {
-          if (gate.notify) {
-            h.blockedGateNotified.add(paneId);
-            const question = await h.session.readAskFlag(paneId);
-            try {
-              await h.injectNotice(buildBlockedGateNotice({ paneId, description, question }));
-            } catch {
-              /* list_agents can recover a missed notice */
-            }
-          }
-          continue;
-        }
-        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(Boolean(entry.userTakeover))}`);
-          if (isSettlementCandidate(s)) {
-            const closing = s.text;
-            const obs = planObservationTick({
-              observationStartedAt: entry.observationStartedAt,
-              now: now(),
-              windowMs: observeWindowMs,
-              agentStatus: null,
-              machineInjectAgoMs: now() - (h.lastMachineInjectAt.get(paneId) ?? 0),
-              machineInjectGraceMs,
-            });
-            if (obs.kind === 'start-observation') {
-              entry.observationStartedAt = now();
-              entry.lastAgentStatus = 'idle';
-              h.persistSubs();
-              await doSleep(OBSERVATION_TICK_MS);
-              continue;
-            }
-            let agentStatus: string | null = null;
-            try {
-              const agents = await h.client.listAgents();
-              agentStatus = agents.find((a) => a.paneId === paneId)?.status ?? null;
-            } catch {
-              /* observation continues */
-            }
-            const obs2 = planObservationTick({
-              observationStartedAt: entry.observationStartedAt,
-              now: now(),
-              windowMs: observeWindowMs,
-              agentStatus,
-              machineInjectAgoMs: now() - (h.lastMachineInjectAt.get(paneId) ?? 0),
-              machineInjectGraceMs,
-            });
-            if (obs2.kind === 'user-takeover') {
-              entry.userTakeover = true;
-              entry.observationStartedAt = now();
-              entry.lastAgentStatus = 'working';
-              h.persistSubs();
-              continue;
-            }
-            if (obs2.kind === 'machine-inject-reset') {
-              entry.observationStartedAt = now();
-              h.persistSubs();
-              await doSleep(OBSERVATION_TICK_MS);
-              continue;
-            }
-            if (obs2.kind === 'wait') {
-              await doSleep(OBSERVATION_TICK_MS);
-              continue;
-            }
-            entry.observationStartedAt = null;
-            if (!entry.sessionFile) {
-              entry.sessionFile = applyReportedSessionFile(
-                entry.sessionFile,
-                await h.session.resolveSessionFile(paneId, cwd),
-              );
-            }
-            entry.status = 'consumed';
-            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(
-              buildSettlementNoticeText(`${paneId} (${description})`, closing, statLine),
-              notes,
-            );
-            if (h.claimSettleNotice(`${paneId}:${requestId}`)) {
-              try {
-                await h.injectNotice(notice);
-              } catch {
-                /* list_agents can recover */
-              }
-            }
-            return;
-          }
-        }
-        let alive = false;
-        try {
-          alive = (await h.client.listPanes()).some((p) => p.paneId === paneId);
-        } catch {
-          alive = true;
-        }
-        const vacuum = planVacuumTick({
-          waitState: state,
-          paneAlive: alive,
-          now: now(),
-          lastActivityAt,
-          timeoutMs,
-        });
-        if (vacuum.refreshActivity) lastActivityAt = now();
-        if (vacuum.action === 'pane-closed') {
-          entry.status = 'consumed';
-          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(
-            formatPaneClosedNotice(paneId, description),
-            notes,
-          );
-          try {
-            await h.injectNotice(notice);
-          } catch { /* non-fatal */ }
-          return;
-        }
-        if (vacuum.action === 'timeout') {
-          entry.status = 'consumed';
-          entry.consumedAt = now();
-          h.persistSubs();
-          h.writeHistory(entry, { outcome: 'observation timeout' }, 'poll-timeout');
-          const notes = h.reconcileOnSettlement(description, 'failed');
-          const notice = h.withReconcileNotes(
-            formatObservationTimeoutNotice({
-              paneId,
-              description,
-              idleSeconds: Math.round((now() - lastActivityAt) / 1000),
-              startedAtIso: new Date(startedAt).toISOString(),
-            }),
-            notes,
-          );
-          try {
-            await h.injectNotice(notice);
-          } catch { /* non-fatal */ }
-          return;
-        }
-      }
-    } finally {
-      pollers.delete(paneId);
-    }
-  }
-
-  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);
-    return (async () => {
-      try {
-        if (!subScopes.has(paneId)) {
-          const fiber = await mountSubagentScope(h.sessionRoot, paneId, {
-            onDispose: () => { pollers.delete(paneId); },
-          });
-          subScopes.set(paneId, fiber);
-        }
-        await pollLoop(paneId, cwd, spawnedAt, injectTs, description, requestId);
-        const fiber = subScopes.get(paneId);
-        subScopes.delete(paneId);
-        try { await fiber?.dispose(); } catch { /* already gone */ }
-      } catch (err) {
-        pollers.delete(paneId);
-        console.error(`pier: subagent poller ${paneId} crashed: ${(err as Error)?.message ?? err}`);
-      }
-    })();
-  }
-
-  return { startPoller, pollers };
-}

package/src/subagent-port.ts

@@ -1,27 +0,0 @@
-/**
- * Subagent outbound port (composition root → plugin).
- *
- * Why: index used to pass a bag of independently-nullable callbacks that the
- * plugin mutated field-by-field. A missing bag crashed at mount
- * (`Cannot set properties of undefined (setting 'applyReplySession')`).
- * Binding one `current` object is atomic: all methods or none.
- */
-export interface RunningSub {
-  paneId: string;
-  description: string;
-}
-
-export interface SubagentPort {
-  applyReplySession(paneId: string, sessionFile: string | null): void;
-  reconcileOnReply(paneId: string): string[];
-  listRunningSubs(): RunningSub[];
-  settleStatLine(paneId: string): Promise<string | null>;
-}
-
-export interface SubagentPortBox {
-  current: SubagentPort | null;
-}
-
-export function emptySubagentPortBox(): SubagentPortBox {
-  return { current: null };
-}

package/src/subagent-ready.ts

@@ -1,89 +0,0 @@
-/**
- * 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

@@ -1,70 +0,0 @@
-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

@@ -1,41 +0,0 @@
-/**
- * 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

@@ -1,41 +0,0 @@
-/**
- * One Cordis fiber per subagent in the master process.
- * pipe / poller / history cleanup uses ctx.effect (LIFO dispose).
- * C3: workers must not import this module.
- */
-import { Context } from '@deepseek-ai/cordis';
-
-export interface ScopeHooks {
-  onDispose?: () => void;
-}
-
-export function createSessionRoot(hooks: ScopeHooks = {}): Context {
-  const root = new Context();
-  if (hooks.onDispose) {
-    root.effect(() => () => { hooks.onDispose?.(); }, 'session-root');
-  }
-  return root;
-}
-
-export async function mountSubagentScope(
-  root: Context,
-  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}`);
-    },
-  });
-}
-
-export async function disposeSessionRoot(root: Context): Promise<void> {
-  try {
-    await root.fiber.dispose();
-  } catch {
-    /* second dispose is a no-op */
-  }
-}