piher 0.0.0-stage → 0.2.0

package/src/delegation-core.ts

@@ -0,0 +1,94 @@
+/**
+ * Delegation identity (RFC docs/rfc-delegation-identity.md Phase 1): a worker pane knows who
+ * delegated it, and for what task, on every surface it already touches — the system prompt section
+ * and the session custom entry (first-frame card).
+ * Pure builders only; the composition root owns the side effects.
+ */
+
+import type { Lifecycle } from './role-manifest.ts';
+
+/** Contract env handed to the worker process by the master (PIHER_ prefix per naming rule). */
+export const DELEGATION_ENV = 'PIHER_DELEGATION';
+/** Worker-session custom entry written once at first boot; replayed on resume. */
+export const DELEGATION_CUSTOM_TYPE = 'piher.delegation';
+
+export interface DelegationContext {
+  /** Master pane that spawned this worker; '' when the master pane is unknown (tests, RPC). */
+  readonly parentPaneId: string;
+  /** Master pi session id (cross-locate the parent transcript via /resume). */
+  readonly parentSessionId: string;
+  /** TaskRow.taskId — stable across revives. */
+  readonly taskId: string;
+  /** Task short label (TaskRow.description). */
+  readonly description: string;
+  /** Role manifest name active at spawn. */
+  readonly role: string;
+  /** Role-declared lifetime (S9/S54): `one-shot` settles, reports and then exits; default `persistent`. */
+  readonly lifecycle: Lifecycle;
+}
+
+function str(v: unknown): string | null {
+  return typeof v === 'string' ? v : null;
+}
+
+/** Validate a parsed delegation record (env JSON, marker JSON or custom-entry data); null when malformed. */
+export function delegationFromRecord(parsed: unknown): DelegationContext | null {
+  if (!parsed || typeof parsed !== 'object') return null;
+  const rec = parsed as Record<string, unknown>; // shape-checked field by field below
+  const taskId = str(rec.taskId);
+  const description = str(rec.description);
+  if (!taskId || !description) return null;
+  return {
+    parentPaneId: str(rec.parentPaneId) ?? '',
+    parentSessionId: str(rec.parentSessionId) ?? '',
+    taskId,
+    description,
+    role: str(rec.role) ?? 'worker-default',
+    lifecycle: rec.lifecycle === 'one-shot' ? 'one-shot' : 'persistent',
+  };
+}
+
+/** Parse the spawn env; null when absent or structurally invalid (taskId/description mandatory). */
+export function parseDelegationContext(raw: string | undefined | null): DelegationContext | null {
+  if (!raw || typeof raw !== 'string') return null;
+  try {
+    return delegationFromRecord(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+}
+
+/** env map for spawnPaneInTaskTab/createTab; JSON like the role manifest next to it. */
+export function delegationEnv(ctx: DelegationContext): Record<string, string> {
+  return { [DELEGATION_ENV]: JSON.stringify(ctx) };
+}
+
+/** Fold `piher.delegation` branch entries (last one wins) — the /resume replay source. */
+export function foldDelegation(
+  entries: ReadonlyArray<{ type?: string; customType?: string; data?: unknown }>,
+): DelegationContext | null {
+  let found: DelegationContext | null = null;
+  for (const entry of entries) {
+    if (entry.type !== 'custom' || entry.customType !== DELEGATION_CUSTOM_TYPE) continue;
+    const next = delegationFromRecord(entry.data);
+    if (next) found = next;
+  }
+  return found;
+}
+
+/**
+ * System-prompt section text: identity + delivery contract in one stable wording, so the master
+ * model does not have to restate it in every spawn prompt (pi-subagent-manager idea A+F).
+ */
+export function buildDelegationSection(ctx: DelegationContext, ownPaneId: string): string {
+  const parent = ctx.parentPaneId || 'unknown pane';
+  const session = ctx.parentSessionId || 'unknown session';
+  const self = ownPaneId ? ` You are pane ${ownPaneId} (agentId "${ownPaneId}") — cite it when asking questions or reporting errors.`
+    : '';
+  return [
+    `You are a delegated subagent of the master pane ${parent} (session ${session}); you were not started by a human.`,
+    `Task: ${ctx.description}. Role: ${ctx.role}.${self}`,
+    'Contract: the master collects your answer from this pane\'s settlement, so end the turn in one of two ways — state the answer plainly, or, if you cannot finish, stop and make the first line `BLOCKED: <the decision or resource you need>`. Do not ask who requested the work and do not guess silently.',
+  ].join('\n');
+}
+

package/src/gc-core.ts

@@ -0,0 +1,150 @@
+/** Task-tab GC decisions (D29 rules as a pure function; no I/O, no pi/herdr). */
+export type GcEntryKind = string;
+
+export interface GcEntryLike {
+  /** 'task' or a role name; legacy short/resident is a label only. */
+  kind: GcEntryKind;
+  /** Report-delivered time (GC grace); null while the turn is still the master's business. */
+  consumedAt?: number | null;
+  /** Close decision time; a closed task is finished whatever else it says. */
+  closedAt?: number | null;
+}
+
+/** A row is finished for its tab when the master ended it, or its report was delivered long
+ *  enough ago that the grace TTL elapsed. An undelivered report is still the master's business. */
+function isTabFinished(e: GcEntryLike, now: number, ttlMs: number): boolean {
+  if (e.closedAt != null) return true;
+  const consumedAt = e.consumedAt ?? 0;
+  return consumedAt > 0 && consumedAt < now - ttlMs;
+}
+
+/** Close a task tab only when every work pane finished, the grace TTL elapsed (`ttlMs=0` means never
+ *  auto-close), no terminal is blocked and the rest are idle/done/error (unknown = never reported). */
+export function shouldCloseTaskTab(opts: {
+  entries: readonly GcEntryLike[];
+  paneStatuses: readonly string[];
+  ttlMs: number;
+  now: number;
+}): boolean {
+  if (opts.entries.length === 0) return false;
+  if (!opts.entries.every((e) => isTabFinished(e, opts.now, opts.ttlMs))) return false;
+  if (opts.paneStatuses.some((s) => s === 'blocked')) return false;
+  if (!opts.paneStatuses.every((s) => s === 'idle' || s === 'done' || s === 'error' || s === 'unknown')) return false;
+  return true;
+}
+
+/** Pane-level collection (orphan / compat path): consumed before the previous turn (grace so the
+ *  settlement notice is still visible); a missing terminal is skipped by the caller, never closed.
+ */
+export function shouldClosePane(opts: {
+  consumedAt: number | null;
+  status: string | undefined;
+  prevTurnStart: number;
+  /** Only a one-shot spends itself; a persistent worker is the master's to close. */
+  lifecycle?: 'one-shot' | 'persistent';
+}): boolean {
+  // A terminal the snapshot does not list is not this planner's to close: there is no pane to
+  // reclaim, and blessing the close would retire a terminal that may simply be unlisted.
+  if (opts.status === undefined) return false;
+  // Killing a persistent worker's process buys nothing: it has no pane to reclaim, and the next
+  // `send` would pay a cold start and revive a conversation that was never over.
+  if (opts.lifecycle !== 'one-shot') return false;
+  if (opts.status !== 'idle' && opts.status !== 'done' && opts.status !== 'error') return false;
+  return (opts.consumedAt ?? 0) > 0 && opts.consumedAt! < opts.prevTurnStart;
+}
+
+/** A subagent row as the checkout sweep sees it: which checkout it works in, and whether it is done. */
+export interface CheckoutRowLike extends GcEntryLike {
+  worktreePath?: string | null;
+}
+
+export interface CheckoutSweep {
+  /** Checkouts whose space closes: every row there is `closed`, so nothing is alive inside. */
+  close: string[];
+  /** Checkouts to remind the master about once, with the consume time the reminder is about. */
+  remind: Array<{ path: string; since: number }>;
+}
+
+/**
+ * A checkout's app space outlives the workers that used it, and nothing else sweeps it: a one-shot's
+ * reclaim closes the space only for one-shots, so a persistent worker leaves its window behind. Two
+ * decisions, and neither ends a task:
+ *   - close the space when every row of that checkout is `closed` — an empty window is cleanup;
+ *   - remind the master, once per settlement, when every row there finished but one is not closed.
+ *     That window stays: `space.close` ends the terminals inside it, and an idle worker is still
+ *     the master's to send more work to.
+ */
+export function decideCheckoutSpaces(opts: {
+  rows: readonly CheckoutRowLike[];
+  ttlMs: number;
+  now: number;
+  /** Path → the `since` a reminder was already delivered for; nothing new settled since. */
+  remindedAt?: ReadonlyMap<string, number>;
+}): CheckoutSweep {
+  const byPath = new Map<string, CheckoutRowLike[]>();
+  for (const row of opts.rows) {
+    const path = row.worktreePath;
+    if (!path) continue;
+    const arr = byPath.get(path) ?? [];
+    arr.push(row);
+    byPath.set(path, arr);
+  }
+  const close: string[] = [];
+  const remind: Array<{ path: string; since: number }> = [];
+  for (const [path, rows] of byPath) {
+    if (rows.every((r) => r.closedAt != null)) {
+      close.push(path);
+      continue;
+    }
+    if (opts.ttlMs <= 0) continue;
+    if (!rows.every((r) => r.closedAt != null || r.consumedAt != null)) continue;
+    const since = Math.max(...rows.map((r) => r.consumedAt ?? 0));
+    if (since <= 0 || since >= opts.now - opts.ttlMs) continue;
+    if (since <= (opts.remindedAt?.get(path) ?? 0)) continue;
+    remind.push({ path, since });
+  }
+  return { close, remind };
+}
+
+/** One line the master can act on. It names the decision, never a countdown: nothing closes by
+ *  itself, and housekeeping never ends a window that still holds an idle worker. */
+/** Whether the channel heartbeat should ping this row at all. Only a worker with a turn in flight
+ *  has a channel to lose: a delivered report means the turn is over, and `unknown` means pi has
+ *  not reported a state yet — the process is still booting and its pipe is seconds away. Announcing
+ *  a loss in either case is noise the master has to read and act on. */
+export function planChannelCheck(input: {
+  /** The master's decision stands: a closed task has no channel to lose. */
+  closed: boolean;
+  /** A delivered report means no turn is in flight, so there is no channel to lose either. */
+  consumed: boolean;
+  /** What core reports for the pane; `undefined` when it does not list the terminal at all. */
+  terminalStatus: string | undefined;
+}): 'skip' | 'ping' {
+  if (input.closed || input.consumed) return 'skip';
+  if (input.terminalStatus === undefined) return 'skip';
+  if (input.terminalStatus === 'unknown') return 'skip';
+  return 'ping';
+}
+
+/** A worker whose pane is alive but whose channel is gone can never receive a follow-up: say it once,
+ *  with the two ways out, so the master does not discover it on the next `send`. */
+export function formatDeadChannelNotice(opts: {
+  paneId: string;
+  taskId: string;
+  status: string;
+}): string {
+  return `Note: subagent ${opts.paneId} is alive (${opts.status}) but its message channel is gone — a ` +
+    'follow-up sent to it would not arrive. Nothing was lost: the row is untouched. Restart it with ' +
+    `subagent action:"resume" taskId ${opts.taskId}, or retire it with action:"close".`;
+}
+
+export function formatIdleCheckoutNotice(opts: {
+  name: string;
+  minutes: number;
+  panes: readonly string[];
+}): string {
+  const who = opts.panes.length > 0 ? ` (${opts.panes.join(', ')})` : '';
+  return `Note: the checkout ${opts.name} has had no running subagent for ${opts.minutes} min${who}. ` +
+    'Its app space stays open: housekeeping never closes a window with an idle worker in it. ' +
+    'Close what you no longer need with subagent action:"close"; the checkout itself is never removed.';
+}

package/src/guards.ts

@@ -0,0 +1,6 @@
+/** Shared structural guards used by the *-core validators. */
+
+/** Plain JSON object: not null, not an array. */
+export function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}

package/src/hc-templates.ts

@@ -0,0 +1,134 @@
+/**
+ * hc templates generated from role manifests (S75): one contract, two doors.
+ *
+ * A role manifest is the source of truth — it carries the model, the thinking level, the tool set and
+ * the rules a template cannot express. `hc run <role> "task"` needs the same role as a Markdown
+ * template, and generating it removes the drift that let `subagent spawn {role:"reviewer"}` and
+ * `hc run reviewer` launch different models from the same name.
+ *
+ * Placement is hc's, not ours: frontmatter carries `name`, `description` and `command`, and the body
+ * is delivered as the first message together with the task (see `hc --skill`). The body therefore
+ * holds the standing instructions, while the rules that must be enforced (`rules`, `unknownTools`,
+ * `lifecycle`) stay in the manifest, where a tool gate applies them.
+ */
+import { join } from 'node:path';
+import { listRoleNames, loadRoleConfig, RESERVED_ROLE_NAMES } from './role-loader.ts';
+import type { RoleManifest } from './role-manifest.ts';
+
+/** `~/.config/herdr-core/templates`, where core looks for templates. */
+export function hcTemplatesDir(homeDir: string): string {
+  return join(homeDir, '.config', 'herdr-core', 'templates');
+}
+
+export interface HcTemplatePlan {
+  /** Role name, which is also the template name `hc run <name>` resolves. */
+  name: string;
+  /** File name inside the templates directory. */
+  fileName: string;
+  /** Template command line: the launch command with model, thinking and tools. */
+  command: string;
+  /** The frontmatter description line, kept so a merge can restore a missing one. */
+  descriptionLine: string;
+  /** Full Markdown file: frontmatter plus standing instructions. */
+  markdown: string;
+}
+
+/** YAML frontmatter values stay on one line: a newline or a stray quote breaks the file. */
+function oneLine(text: string): string {
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+/** `pi --model … --thinking … --tools …`: the argv a template launches. */
+export function templateCommand(manifest: RoleManifest): string {
+  const parts = ['pi'];
+  if (manifest.model) parts.push('--model', manifest.model);
+  if (manifest.thinking) parts.push('--thinking', manifest.thinking);
+  // `*` is a wildcard, not a tool: the manifest already covers unknown tools through `unknownTools`.
+  const tools = manifest.manifest.tools.filter((tool) => tool !== '*');
+  if (tools.length > 0) parts.push('--tools', tools.join(','));
+  return parts.join(' ');
+}
+
+/**
+ * One template from one manifest, or null when the role is not meant to be launched by name:
+ * `master` and `worker-default` are the harness's own roles, and `modelInvocable: false` marks a
+ * role that exists but must not appear as a launchable profile.
+ */
+export function planHcTemplate(manifest: RoleManifest): HcTemplatePlan | null {
+  if (manifest.modelInvocable === false) return null;
+  if (RESERVED_ROLE_NAMES.includes(manifest.role)) return null;
+  const command = templateCommand(manifest);
+  const description = oneLine(manifest.description ?? `Role ${manifest.role}`);
+  const body: string[] = [`# ${manifest.role}`, ''];
+  if (manifest.guidelines && manifest.guidelines.length > 0) {
+    body.push('Rules for this role:', '');
+    for (const line of manifest.guidelines) body.push(`- ${oneLine(line)}`);
+    body.push('');
+  }
+  if (manifest.instructions) body.push(manifest.instructions.trim(), '');
+  body.push(
+    'These instructions and the task that follows are one message: do the task under these rules,',
+    'not instead of them. Report the result as the last message of your turn.',
+  );
+  const markdown = [
+    '---',
+    `name: ${manifest.role}`,
+    `description: ${description}`,
+    `command: ${command}`,
+    '---',
+    '',
+    ...body,
+    '',
+  ].join('\n');
+  return {
+    name: manifest.role,
+    fileName: `${manifest.role}.md`,
+    command,
+    descriptionLine: `description: ${description}`,
+    markdown,
+  };
+}
+
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+
+/**
+ * Sync a template that already exists: the frontmatter fields this generator owns (`name`,
+ * `description`, `command`) are replaced, every other key and **the whole body** stay untouched. A
+ * hand-written brief is worth more than a regenerated one, so syncing never clobbers prose.
+ */
+export function mergeHcTemplate(existing: string, plan: HcTemplatePlan): string {
+  const match = FRONTMATTER.exec(existing);
+  if (match === null) return plan.markdown;
+  const kept = match[1]!
+    .split(/\r?\n/)
+    .filter((line) => line.trim() !== '')
+    .filter((line) => !/^(name|description|command)\s*:/.test(line));
+  const front = [
+    '---',
+    `name: ${plan.name}`,
+    plan.descriptionLine,
+    ...kept,
+    `command: ${plan.command}`,
+    '---',
+    '',
+    '',
+  ].join('\n');
+  return `${front}${existing.slice(match[0].length).replace(/^\n+/, '')}`;
+}
+
+/** Every launchable role of the loaded catalog, in name order, as a template plan. */
+export function planHcTemplates(opts: { baseDir?: string; userDir?: string } = {}): HcTemplatePlan[] {
+  const plans: HcTemplatePlan[] = [];
+  for (const name of listRoleNames(opts.baseDir, opts.userDir)) {
+    let manifest: RoleManifest;
+    try {
+      manifest = loadRoleConfig(name, opts);
+    } catch {
+      // A role that does not validate is reported by the catalog, not by this generator.
+      continue;
+    }
+    const plan = planHcTemplate(manifest);
+    if (plan !== null) plans.push(plan);
+  }
+  return plans.sort((left, right) => left.name.localeCompare(right.name));
+}

package/src/index-locks.ts

@@ -0,0 +1,118 @@
+/** M18 file write-lock installer (soft veto / hard block): owns the three pi hooks and the
+ *  held-lock set; fail-open on terminal.list is the collaboration policy. */
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import {
+  acquireTokensFor,
+  isLockTokenKey,
+  parseLockTokenValue,
+  planWriteGuard,
+  releaseTokensFor,
+  type LockAgentView,
+} from './lock-core.ts';
+import type { CoreClientLike, CoreEnv } from './core-client.ts';
+
+export interface WriteLocksHandle {
+  getHeldLocks: () => readonly string[];
+}
+
+export function installWriteLocks(
+  pi: ExtensionAPI,
+  opts: {
+    client: CoreClientLike;
+    env: CoreEnv | null;
+    hard: boolean;
+  },
+): WriteLocksHandle {
+  const { client, env, hard } = opts;
+  const heldLocks = new Set<string>();
+  const lockWarnByToolCall = new Map<string, string>();
+
+  if (!client.available || !env) {
+    return { getHeldLocks: () => [] };
+  }
+
+  async function acquireLocks(paths: readonly string[]): Promise<void> {
+    for (const p of paths) heldLocks.add(p);
+    await client.setLabels(acquireTokensFor(paths, env?.terminalId ?? ''));
+  }
+
+  pi.on('tool_call', async (event: { toolName?: string; toolCallId?: string; input?: unknown }, ctx: { cwd?: string }) => {
+    if (!client.available || !env) return;
+    const cwd = ctx?.cwd ?? process.cwd();
+    let agents: LockAgentView[];
+    let ownForegroundCwd: string | null = null;
+    try {
+      const live = await client.listTerminals();
+      agents = live.map((t) => ({ paneId: t.id, tokens: t.labels }));
+      const me = live.find((t) => t.id === env.terminalId);
+      if (me?.foreground?.cwd) {
+        ownForegroundCwd = me.foreground.cwd;
+      }
+    } catch {
+      return;
+    }
+    const effectiveCwd = ownForegroundCwd ?? cwd;
+    const plan = planWriteGuard({
+      toolName: event.toolName ?? '',
+      input: event.input,
+      agents,
+      ownPaneId: env.terminalId,
+      cwd: effectiveCwd,
+      hard,
+    });
+    if (plan.kind === 'skip') return;
+    if (plan.kind === 'block') {
+      return { block: true, reason: plan.reason };
+    }
+    if (plan.kind === 'warn' && typeof event.toolCallId === 'string') {
+      lockWarnByToolCall.set(event.toolCallId, plan.warning);
+    }
+    await acquireLocks(plan.paths);
+  });
+
+  pi.on('tool_result', async (event: unknown) => {
+    const rec = (event ?? {}) as { toolCallId?: unknown; content?: unknown };
+    if (typeof rec.toolCallId !== 'string') return;
+    const warning = lockWarnByToolCall.get(rec.toolCallId);
+    if (!warning) return;
+    lockWarnByToolCall.delete(rec.toolCallId);
+    const content = Array.isArray(rec.content) ? rec.content as Array<{ type: 'text'; text: string }> : [];
+    return { content: [...content, { type: 'text' as const, text: warning }] };
+  });
+
+  pi.on('agent_settled', async () => {
+    if (heldLocks.size === 0) return;
+    const paths = [...heldLocks];
+    heldLocks.clear();
+    await client.setLabels(releaseTokensFor(paths));
+  });
+
+  pi.registerCommand('piher-locks', {
+    description: 'Show write locks held by this pane and all live panes (M18)',
+    handler: async (_args, ctx) => {
+      const ui = (ctx as { ui?: { notify?: (text: string, level?: string) => void } }).ui;
+      const mine = [...heldLocks];
+      const lines = [`held by this pane (${mine.length}):`];
+      lines.push(...(mine.length ? mine.map((p) => `  ${p}`) : ['  (none)']));
+      lines.push('all live locks:');
+      let any = false;
+      try {
+        for (const t of await client.listTerminals()) {
+          for (const [k, v] of Object.entries(t.labels)) {
+            if (!isLockTokenKey(k) || typeof v !== 'string' || !v) continue;
+            const parsed = parseLockTokenValue(v);
+            if (!parsed) continue;
+            any = true;
+            lines.push(`  ${parsed.path} → pane ${parsed.holderPaneId}`);
+          }
+        }
+      } catch {
+        lines.push('  (terminal.list failed)');
+      }
+      if (!any && lines[lines.length - 1] !== '  (terminal.list failed)') lines.push('  (none)');
+      ui?.notify?.(lines.join('\n'), 'info');
+    },
+  });
+
+  return { getHeldLocks: () => [...heldLocks] };
+}

package/src/index-master.ts

@@ -0,0 +1,92 @@
+/** Master-process plugin mount (cordis loader + terminal/subagent), dynamically imported from
+ *  the master branch of index.ts only: a worker must never load bootstrap/subagent-poller (C3). */
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { Context } from '@deepseek-ai/cordis';
+import type { Server } from 'node:net';
+import { PiSurface } from './pi-surface.ts';
+import { createCordisApp } from './bootstrap.ts';
+import { cordisProvide } from './cordis-services.ts';
+import { disposeSessionRoot } from './subagent-poller.ts';
+import bgJobPlugin from './plugins/bg-job.ts';
+import subagentPlugin from './plugins/subagent.ts';
+import type { CoreClientLike, CoreEnv } from './core-client.ts';
+import type { SubagentPortBox } from './subagent-core.ts';
+import type { SettlementCard } from './settlement-card.ts';
+
+export interface MasterPluginMount {
+  pi: ExtensionAPI;
+  client: CoreClientLike;
+  env: CoreEnv | null;
+  extPath: string;
+  port: SubagentPortBox;
+  pipeServerBox: { current: Server | null };
+  deliverNotice: (content: string, paneId?: string, card?: SettlementCard | null) => Promise<void>;
+  noticePending: () => ReadonlySet<string>;
+  getSessionId: () => string;
+  /** This session's transcript path; the subagent registry is stored beside it. */
+  getSessionFile: () => string | null;
+  claimSettleNotice: (key: string) => boolean;
+}
+
+async function loadEntry(
+  sessionRoot: Context,
+  useLoader: boolean,
+  name: string,
+  plugin: (ctx: Context) => void,
+): Promise<void> {
+  if (useLoader) {
+    const withLoader = sessionRoot as typeof sessionRoot & {
+      loader?: { create: (o: { name: string }) => Promise<unknown> };
+    };
+    await withLoader.loader?.create({ name });
+    return;
+  }
+  await sessionRoot.plugin(plugin);
+}
+
+export async function mountMasterPlugins(m: MasterPluginMount): Promise<void> {
+  const cordisApp = await createCordisApp();
+  const sessionRoot = cordisApp.root;
+  // loader.create re-imports .ts via Node ESM — fails under node_modules (npm:piher
+  // strip-types) and misses pi's typebox alias. HMR-only; production uses plugin().
+  const useLoader = cordisApp.loaderReady && cordisApp.hmrActive;
+
+  // Pipe server is created in the common segment; closing it from a core plugin would kill it on hmr reload (d87).
+  sessionRoot.effect(() => () => {
+    if (m.pipeServerBox.current) {
+      try { m.pipeServerBox.current.close(); } catch { /* already closed */ }
+      m.pipeServerBox.current = null;
+    }
+  }, 'pipe-server');
+
+  const surface = new PiSurface(m.pi as unknown as object, cordisApp.ledger);
+  cordisProvide(sessionRoot, 'piher.surface', surface);
+  const jobDeps = {
+    client: m.client,
+    env: m.env,
+    state: { activePaneIds: (): Set<string> => new Set() },
+  };
+  cordisProvide(sessionRoot, 'piher.bg-job-deps', jobDeps);
+
+  await loadEntry(sessionRoot, useLoader, './plugins/bg-job.ts', bgJobPlugin);
+
+  // Dropped keys fail here: cordisProvide checks the bag against PiherCordisServices (fe99252).
+  cordisProvide(sessionRoot, 'piher.subagent-deps', {
+    client: m.client,
+    env: m.env,
+    extPath: m.extPath,
+    sessionRoot,
+    port: m.port,
+    deliverNotice: m.deliverNotice,
+    noticePending: m.noticePending,
+    getSessionId: m.getSessionId,
+    getSessionFile: m.getSessionFile,
+    claimSettleNotice: m.claimSettleNotice,
+    terminalState: jobDeps.state,
+  });
+  await loadEntry(sessionRoot, useLoader, './plugins/subagent.ts', subagentPlugin);
+
+  m.pi.on('session_shutdown', () => {
+    void disposeSessionRoot(sessionRoot);
+  });
+}

package/src/index-notices.ts

@@ -0,0 +1,79 @@
+/**
+ * D92 settlement-notice buffer: `sendUserMessage(followUp)` only delivers when the agent has no
+ * more tool calls, so a long master run would queue every settlement and flood at the end. Buffer
+ * while busy; flush at turn_end (steer) / agent_settled (followUp), collapsing large batches. */
+
+import type { SettlementCard } from './settlement-card.ts';
+
+export type NoticeSendMode = 'steer' | 'followUp';
+
+export const NOTICE_MAX_SHOWN = 3;
+
+/** Collapse a batch into one message body: empty → null; above the cap, the first max originals plus
+ *  a tail pointing at history / subagent list. A single-item batch stays byte-identical to the
+ *  direct-send format. */
+export function collapseNotices(contents: readonly string[], max = NOTICE_MAX_SHOWN): string | null {
+  if (contents.length === 0) return null;
+  if (contents.length <= max) return contents.join('\n\n');
+  const hidden = contents.length - max;
+  const tail = `…${hidden} more settlement(s) not shown individually. Read each worker's own transcript `
+    + 'for the full result; use subagent list for running agents.';
+  return [...contents.slice(0, max), tail].join('\n\n');
+}
+
+export interface NoticeBuffer {
+  deliverNotice(content: string, paneId?: string, card?: SettlementCard | null): Promise<void>;
+  noticePending(): ReadonlySet<string>;
+  flush(mode: NoticeSendMode): Promise<void>;
+}
+
+export function createNoticeBuffer(opts: {
+  /** True while the agent is in a turn, or after an abort that must not wake a new run. */
+  isBusy: () => boolean;
+  /** One collapsed body; the card describes a single settlement and is omitted for a batch. */
+  send: (content: string, mode: NoticeSendMode, card?: SettlementCard) => Promise<void>;
+}): NoticeBuffer {
+  const pending: Array<{ content: string; paneId?: string; card?: SettlementCard }> = [];
+  const pendingPaneIds = new Set<string>();
+  /** A refused send is not a delivered settlement: keep the batch and its panes for the next flush. */
+  const requeue = (notices: readonly { content: string; paneId?: string; card?: SettlementCard }[]): void => {
+    pending.unshift(...notices);
+  };
+  return {
+    async deliverNotice(content, paneId, card) {
+      if (content !== '' && paneId !== undefined) pendingPaneIds.add(paneId);
+      if (opts.isBusy()) {
+        pending.push({ content, paneId, ...(card ? { card } : {}) });
+        return;
+      }
+      try {
+        await opts.send(content, 'followUp', card ?? undefined);
+      } catch (err) {
+        // pi drops prompts while the agent is mid-turn; holding the notice keeps it (and keeps its
+        // pane GC-exempt) until a flush can deliver it, instead of losing the settlement here.
+        requeue([{ content, paneId, ...(card ? { card } : {}) }]);
+        return;
+      }
+      if (content !== '' && paneId !== undefined) pendingPaneIds.delete(paneId);
+    },
+    noticePending: () => pendingPaneIds,
+    async flush(mode) {
+      if (pending.length === 0) return;
+      const flushed = pending.splice(0);
+      const collapsed = collapseNotices(flushed.map((n) => n.content));
+      if (collapsed) {
+        try {
+          await opts.send(collapsed, mode, flushed.length === 1 ? flushed[0]!.card : undefined);
+        } catch {
+          requeue(flushed);
+          return;
+        }
+      }
+      // Release only this batch's panes, and only once it is delivered: a notice buffered during the
+      // send await, or a batch a refused send put back, is still undelivered and its pane must stay.
+      for (const { paneId } of flushed) {
+        if (paneId !== undefined && !pending.some((n) => n.paneId === paneId)) pendingPaneIds.delete(paneId);
+      }
+    },
+  };
+}