@justjoshn/pi-pstack 0.0.0-stage → 0.15.36-pi.7

package/src/task/card.ts

@@ -0,0 +1,61 @@
+import type { AgentToolResult } from '@earendil-works/pi-agent-core';
+import { Text } from '@earendil-works/pi-tui';
+
+const COLLAPSED_LINES = 10;
+
+interface CardDetails {
+  subagentType: string;
+  model: { provider: string; id: string; thinking?: string } | null;
+  worktree?: { branch: string } | null;
+  description?: string;
+}
+
+function isCardDetails(details: unknown): details is CardDetails {
+  return typeof details === 'object' && details !== null && 'subagentType' in details && 'model' in details;
+}
+
+/** Heads the Task result with the Task description and the model that ran. */
+export function taskCardText(result: Pick<AgentToolResult<unknown>, 'content' | 'details'>, expanded: boolean): string {
+  const text = result.content.map((part) => (part.type === 'text' ? part.text : '')).join('\n');
+  const lines = text.split('\n');
+  const body = expanded || lines.length <= COLLAPSED_LINES ? lines : [...lines.slice(0, COLLAPSED_LINES), `… ${lines.length - COLLAPSED_LINES} more lines`];
+  if (!isCardDetails(result.details)) return body.join('\n');
+  const { model, subagentType, worktree, description } = result.details;
+  const modelName = model === null ? "Pi's default model" : `${model.provider}/${model.id}${model.thinking === undefined ? '' : `:${model.thinking}`}`;
+  const branch = worktree === undefined || worktree === null ? '' : ` · branch ${worktree.branch}`;
+  const title = description === undefined || description.trim() === '' ? '' : `${description.trim()} · `;
+  return [`${title}${subagentType} · ${modelName}${branch}`, ...body].join('\n');
+}
+
+export function renderTaskCard(result: AgentToolResult<unknown>, options: { expanded: boolean }): Text {
+  return new Text(taskCardText(result, options.expanded), 0, 0);
+}
+
+interface NotificationCardDetails {
+  status: 'success' | 'error';
+  agentId: string;
+  title: string;
+  detail: string;
+}
+
+function isNotificationCardDetails(details: unknown): details is NotificationCardDetails {
+  const value = details as Partial<NotificationCardDetails> | null;
+  return typeof value === 'object' && value !== null && (value.status === 'success' || value.status === 'error') && typeof value.agentId === 'string' && typeof value.title === 'string' && typeof value.detail === 'string';
+}
+
+export function taskNotificationCardText(message: { content: string | { type: string; text?: string }[]; details?: unknown }, expanded: boolean): string {
+  if (!isNotificationCardDetails(message.details)) {
+    const raw = typeof message.content === 'string' ? message.content : message.content.map((part) => (part.type === 'text' ? (part.text ?? '') : '')).join('\n');
+    const lines = raw.split('\n');
+    return (expanded || lines.length <= COLLAPSED_LINES ? lines : [...lines.slice(0, COLLAPSED_LINES), `… ${lines.length - COLLAPSED_LINES} more lines`]).join('\n');
+  }
+  const { title, status, agentId, detail } = message.details;
+  const lines = detail.split('\n');
+  const body = expanded || lines.length <= COLLAPSED_LINES ? lines : [...lines.slice(0, COLLAPSED_LINES), `… ${lines.length - COLLAPSED_LINES} more lines`];
+  const head = `${title.trim() === '' ? 'subagent' : title.trim()} · ${status} · agent ${agentId}`;
+  return [head, ...body].join('\n');
+}
+
+export function renderTaskNotification(message: { content: string | { type: string; text?: string }[]; details?: unknown }, options: { expanded: boolean }): Text {
+  return new Text(taskNotificationCardText(message, options.expanded), 0, 0);
+}

package/src/task/format.ts

@@ -0,0 +1,88 @@
+// Model-facing texts: a <response> block, an "Agent ID:" line that names `resume`, and a <task> notification block
+// with the same fields.
+import type { Usage } from '@earendil-works/pi-ai';
+import { DEFAULT_MAX_BYTES, formatSize, truncateHead } from '@earendil-works/pi-coding-agent';
+import type { Worktree } from './worktree.ts';
+
+/** The first `limit` bytes, cut back to a UTF-8 character boundary (past 10xxxxxx continuation bytes). */
+function headBytes(bytes: Buffer, limit: number): string {
+  let end = limit;
+  while (end > 0 && ((bytes[end] ?? 0) & 0xc0) === 0x80) end -= 1;
+  return bytes.subarray(0, end).toString('utf8');
+}
+
+/**
+ * Bounds a response with Pi's own tool-output limits (truncateHead: 2000 lines or 50KB). truncateHead keeps whole
+ * lines and returns nothing when the first line alone is too long, and a subagent's reply can be one long line, so
+ * that case keeps the line's first 50KB instead.
+ */
+export function bounded(text: string, transcript: string | undefined): string {
+  const result = truncateHead(text);
+  if (!result.truncated) return text;
+  const where = `the full response is in ${transcript ?? 'the subagent transcript'}`;
+  if (result.firstLineExceedsLimit) {
+    const head = headBytes(Buffer.from(text, 'utf8'), DEFAULT_MAX_BYTES);
+    return `${head}\n[truncated: showing ${formatSize(Buffer.byteLength(head, 'utf8'))} of ${formatSize(result.totalBytes)}; ${where}]`;
+  }
+  const size = result.truncatedBy === 'bytes' ? ` (${formatSize(result.outputBytes)} of ${formatSize(result.totalBytes)})` : '';
+  return `${result.content}\n[truncated: showing ${result.outputLines} of ${result.totalLines} lines${size}; ${where}]`;
+}
+
+const agentIdLine = (agentId: string) => `Agent ID: ${agentId} (pass it as \`resume\` to send a follow-up after it completes)`;
+const transcriptLine = (transcript: string | undefined) => (transcript === undefined ? [] : [`Transcript: ${transcript}`]);
+
+export function foregroundText(agentId: string, response: string, transcript: string | undefined, notes: readonly string[] = []): string {
+  return ['This is the output of the subagent:', '', 'response:', '<response>', bounded(response, transcript), '</response>', '', agentIdLine(agentId), ...transcriptLine(transcript), ...notes].join('\n');
+}
+
+export function backgroundText(agentId: string, transcript: string | undefined, notes: readonly string[] = []): string {
+  return [
+    'Subagent is running in the background. Its final response arrives automatically after your turn ends, so do not wait or poll for it. End your turn or work on something else.',
+    '',
+    agentIdLine(agentId),
+    ...transcriptLine(transcript),
+    ...notes,
+  ].join('\n');
+}
+
+export function steerText(agentId: string, notes: readonly string[] = []): string {
+  return [
+    `Sent to agent ${agentId} while it runs: it reads the message after its current step. Its final response still arrives as its launch said, as a completion notification for a background agent or as the waiting Task result for a foreground one, so do not wait or poll for it.`,
+    ...notes,
+  ].join('\n');
+}
+
+export function worktreeLine(worktree: Worktree): string {
+  return `Worktree: ${worktree.path} on branch ${worktree.branch}, from ${worktree.base} at ${worktree.commit}. Merge ${worktree.branch} to take the subagent's commits.`;
+}
+
+/** Opens a cloud agent's first prompt, since nothing else tells the child that the parent merges from its branch. */
+export function worktreePreface(worktree: Worktree, prompt: string): string {
+  const where = worktree.cwd === worktree.path ? worktree.path : `${worktree.path} (working directory ${worktree.cwd})`;
+  return `You are running in an isolated git worktree at ${where} on branch ${worktree.branch}, created from ${worktree.base} at ${worktree.commit}. Uncommitted changes in the parent's checkout are not here. Commit your changes to ${worktree.branch} before you finish, because the parent agent merges from that branch.\n\n${prompt}`;
+}
+
+export interface NotificationFields {
+  status: 'success' | 'error';
+  agentId: string;
+  title: string;
+  toolCallId: string;
+  detail: string;
+  /** What the background child spent. It stays in the notification details, because Pi gives extensions no way to add it to session totals. */
+  usage?: Usage;
+}
+
+export function notificationText(fields: NotificationFields): string {
+  return [
+    'The following task has finished. If you already handled it, ignore this notification and do not restate earlier responses.',
+    '',
+    '<task>',
+    'kind: subagent',
+    `status: ${fields.status}`,
+    `task_id: ${fields.agentId}`,
+    `title: ${fields.title}`,
+    `tool_call_id: ${fields.toolCallId}`,
+    `detail: ${fields.detail}`,
+    '</task>',
+  ].join('\n');
+}

package/src/task/models.ts

@@ -0,0 +1,140 @@
+export type Effort = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+
+export interface AvailableModel {
+  provider: string;
+  id: string;
+  reasoning: boolean;
+  /** Thinking levels Pi supports for the model (pi-ai `getSupportedThinkingLevels`). */
+  levels: readonly string[];
+}
+
+/** A concrete child model. `thinking` absent means the child's own default for that model. */
+export interface ModelSpec {
+  provider: string;
+  id: string;
+  thinking?: Effort;
+}
+
+const INHERIT = new Set(['', 'inherit', 'inherit-parent', 'auto', 'default']);
+const EFFORTS = new Set<string>(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
+const DASH_SLUG = /^(.+?)(?:-thinking)?(?:-(none|minimal|low|medium|high|xhigh|max))?(-fast)?$/;
+
+const asEffort = (value: string): Effort | undefined => (EFFORTS.has(value) ? (value as Effort) : undefined);
+
+/** A model as the allowed list names it, with its thinking levels when it has more than off. */
+export function modelLabel(model: AvailableModel): string {
+  const levels = model.levels.filter((level) => level !== 'off').length > 0 ? ` (thinking: ${model.levels.join(', ')})` : '';
+  return `${model.provider}/${model.id}${levels}`;
+}
+
+function invalid(value: string, available: readonly AvailableModel[], reason = 'Model could not be resolved to a valid subagent model.'): Error {
+  return new Error(
+    [
+      `Invalid model selection "${value}". ${reason}`,
+      'Allowed model slugs:',
+      '- inherit',
+      ...available.map((model) => `- ${modelLabel(model)}`),
+      '',
+      'Add a thinking level as <model>:<level>, for example claude-opus-5-5:xhigh, or as <model>[effort=<level>].',
+      'The `model` parameter is optional. If omitted, the subagent uses the same model as the parent agent.',
+    ].join('\n'),
+  );
+}
+
+type Find = (reference: string) => AvailableModel | undefined;
+
+/** A bare id that several providers offer means the parent chat's provider when it is one of them. */
+function findModel(reference: string, available: readonly AvailableModel[], parentProvider: string | undefined): AvailableModel | undefined {
+  const slash = reference.indexOf('/');
+  if (slash !== -1) return available.find((model) => model.provider === reference.slice(0, slash) && model.id === reference.slice(slash + 1));
+  const matches = available.filter((model) => model.id === reference);
+  if (matches.length > 1) return matches.find((model) => model.provider === parentProvider) ?? failAmbiguous(reference, matches);
+  return matches[0];
+}
+
+function failAmbiguous(reference: string, matches: readonly AvailableModel[]): never {
+  throw new Error(`Model "${reference}" matches more than one provider: ${matches.map((model) => `${model.provider}/${model.id}`).join(', ')}. Use <provider>/<model-id>.`);
+}
+
+/** Only listed levels are accepted, so a level the model does not support is refused instead of clamped by Pi. */
+class UnsupportedLevel extends Error {}
+
+function withThinking(model: AvailableModel, thinking: Effort | undefined): ModelSpec {
+  if (thinking === undefined) return { provider: model.provider, id: model.id };
+  if (!model.levels.includes(thinking)) throw new UnsupportedLevel(`${model.provider}/${model.id} does not support thinking level ${thinking}; it supports ${model.levels.join(', ')}.`);
+  return { provider: model.provider, id: model.id, thinking };
+}
+
+/** A whole reference first, since model ids such as llama3:8b contain a colon; then a trailing :<effort>. */
+function resolvePiSpec(value: string, find: Find): ModelSpec | undefined {
+  const whole = find(value);
+  if (whole !== undefined) return withThinking(whole, undefined);
+  const colon = value.lastIndexOf(':');
+  const level = colon === -1 ? undefined : asEffort(value.slice(colon + 1));
+  if (level === undefined) return undefined;
+  const model = find(value.slice(0, colon));
+  return model === undefined ? undefined : withThinking(model, level);
+}
+
+/** Legacy `<id>[-<effort>][-fast]` slugs: a Pi model whose own id ends in -fast wins, else the base id; the effort is the thinking level, and `none` is Pi's `off`. */
+function resolveDashSlug(value: string, find: Find): ModelSpec | undefined {
+  const match = DASH_SLUG.exec(value);
+  const base = match?.[1];
+  const effort = match?.[2] === undefined ? undefined : asEffort(match[2] === 'none' ? 'off' : match[2]);
+  const fast = match?.[3] !== undefined;
+  if (base === undefined || (effort === undefined && !fast)) return undefined;
+  const model = (fast ? find(`${base}-fast`) : undefined) ?? find(base);
+  return model === undefined ? undefined : withThinking(model, effort);
+}
+
+interface ModelParameters {
+  effort?: Effort;
+  fast?: boolean;
+}
+
+const BRACKETED = /^(.+)\[([^\]]*)\]$/;
+
+/** `id=value` pairs. Pi sets a context window per model, not per call, so `context` is accepted and has no effect. */
+function parseModelParameters(text: string): ModelParameters | undefined {
+  let parsed: ModelParameters = {};
+  for (const pair of text
+    .split(',')
+    .map((part) => part.trim())
+    .filter((part) => part !== '')) {
+    const [key, value, ...rest] = pair.split('=').map((part) => part.trim());
+    if (value === undefined || value === '' || rest.length > 0) return undefined;
+    const effort = asEffort(value);
+    if (key === 'effort' && effort !== undefined) parsed = { ...parsed, effort };
+    else if (key === 'fast' && (value === 'true' || value === 'false')) parsed = { ...parsed, fast: value === 'true' };
+    else if (key !== 'context') return undefined;
+  }
+  return parsed;
+}
+
+/** `<model>[effort=high,fast=false,context=300k]`, per-model parameters; `[]` is the standard variant. */
+function resolveBracketed(value: string, find: Find): ModelSpec | undefined {
+  const match = BRACKETED.exec(value);
+  const base = match?.[1];
+  const parameters = parseModelParameters(match?.[2] ?? '');
+  if (base === undefined || parameters === undefined) return undefined;
+  const model = (parameters.fast === true ? find(`${base}-fast`) : undefined) ?? find(base);
+  return model === undefined ? undefined : withThinking(model, parameters.effort);
+}
+
+/**
+ * Resolves Task's `model`: aliases run on the parent, a listed model runs as asked, and anything else fails with the
+ * allowed list. Legacy slugs `<id>-<effort>[-fast]` still map to a Pi model plus thinking level.
+ */
+export function resolveSubagentModel(value: string | undefined, available: readonly AvailableModel[], parent: ModelSpec | undefined): ModelSpec | undefined {
+  const requested = (value ?? '').trim();
+  if (INHERIT.has(requested)) return parent;
+  try {
+    const find: Find = (reference) => findModel(reference, available, parent?.provider);
+    const resolved = resolveBracketed(requested, find) ?? resolvePiSpec(requested, find) ?? resolveDashSlug(requested, find);
+    if (resolved === undefined) throw invalid(requested, available);
+    return resolved;
+  } catch (error) {
+    if (error instanceof UnsupportedLevel) throw invalid(requested, available, error.message);
+    throw error;
+  }
+}

package/src/task/records.ts

@@ -0,0 +1,227 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { parseSessionEntries, SessionManager } from '@earendil-works/pi-coding-agent';
+import type { ModelSpec } from './models.ts';
+import type { Worktree } from './worktree.ts';
+
+/** What resume needs to restart an agent the way it first ran. */
+export interface AgentRecord {
+  agentId: string;
+  type: string;
+  model?: ModelSpec;
+  readonly: boolean;
+  /** The parent workspace the agent belongs to; a cloud agent runs in `worktree` instead. */
+  cwd: string;
+  createdAt: string;
+  /** 1 for a subagent of the main chat, 2 for a subagent of a subagent; absent in records written before it existed. */
+  depth?: number;
+  worktree?: Worktree;
+  /** The agent whose transcript this one started as a copy of (Task `fork`). */
+  forkedFrom?: string;
+}
+
+function isWorktree(value: unknown): value is Worktree {
+  const worktree = value as Partial<Worktree> | null;
+  return typeof worktree === 'object' && worktree !== null && (['path', 'cwd', 'branch', 'base', 'commit'] as const).every((key) => typeof worktree[key] === 'string');
+}
+
+function isModel(value: unknown): value is ModelSpec {
+  const model = value as Partial<ModelSpec> | null;
+  return typeof model === 'object' && model !== null && typeof model.provider === 'string' && typeof model.id === 'string' && (model.thinking === undefined || typeof model.thinking === 'string');
+}
+
+function isRecord(value: unknown, agentId: string): value is AgentRecord {
+  const record = value as Partial<AgentRecord> | null;
+  return (
+    typeof record === 'object' &&
+    record !== null &&
+    !Array.isArray(record) &&
+    record.agentId === agentId &&
+    typeof record.type === 'string' &&
+    typeof record.readonly === 'boolean' &&
+    typeof record.cwd === 'string' &&
+    typeof record.createdAt === 'string' &&
+    (record.model === undefined || isModel(record.model)) &&
+    (record.depth === undefined || Number.isInteger(record.depth)) &&
+    (record.worktree === undefined || isWorktree(record.worktree)) &&
+    (record.forkedFrom === undefined || typeof record.forkedFrom === 'string')
+  );
+}
+
+export function writeRecord(dir: string, record: AgentRecord): void {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const path = join(dir, `${record.agentId}.json`);
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+export function readRecord(dir: string, agentId: string): AgentRecord | undefined {
+  const path = join(dir, `${agentId}.json`);
+  if (!existsSync(path)) return undefined;
+  const unreadable = new Error(`Agent record ${path} is unreadable; delete it and start a new agent.`);
+  let value: unknown;
+  try {
+    value = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    if (error instanceof SyntaxError) throw unreadable;
+    throw error;
+  }
+  if (!isRecord(value, agentId)) throw unreadable;
+  return value;
+}
+
+/** Pi names a session file `<timestamp>_<session id>.jsonl`; the agent ID is the session ID. */
+export function transcriptFor(dir: string, agentId: string): string | undefined {
+  if (!existsSync(dir)) return undefined;
+  const file = readdirSync(dir).find((name) => name.endsWith(`_${agentId}.jsonl`));
+  return file === undefined ? undefined : join(dir, file);
+}
+
+/** The working directory a Pi session file's header names, or undefined without a readable header. */
+function sessionCwd(file: string): string | undefined {
+  const [header] = parseSessionEntries(readFileSync(file, 'utf8').split('\n', 1)[0] ?? '');
+  return header?.type === 'session' && typeof header.cwd === 'string' && header.cwd !== '' ? header.cwd : undefined;
+}
+
+/**
+ * Starts `agentId`'s transcript as a copy of `sourceId`'s, through Pi's own session fork: a new session ID in the
+ * header, the source as its parent session, and the source's working directory, so `--session-id` finds it where the
+ * source ran. Returns the new transcript path.
+ */
+export function forkTranscript(dir: string, sourceId: string, agentId: string, turns?: number): string {
+  const source = transcriptFor(dir, sourceId);
+  if (source === undefined) throw new Error(`Agent ${sourceId} has no transcript to fork.`);
+  const cwd = sessionCwd(source);
+  if (cwd === undefined) throw new Error(`Agent ${sourceId}'s transcript ${source} has no session header, so it cannot be forked.`);
+  const fork = SessionManager.forkFrom(source, cwd, dir, { id: agentId });
+  const file = fork.getSessionFile();
+  if (file === undefined) throw new Error(`Pi did not write a transcript for the fork of agent ${sourceId}.`);
+  if (turns !== undefined) keepFirstTurns(fork, file, turns);
+  return file;
+}
+
+/**
+ * Cuts the copy's active branch just before its (turns + 1)th user message, so the fork opens at the end of turn `turns`.
+ * `SessionManager.createBranchedSession(leafId)` mints its own session ID and file name, so it cannot truncate the file
+ * `forkFrom(..., { id: agentId })` wrote under the agent's ID (docs/native-gaps.md).
+ */
+function keepFirstTurns(fork: SessionManager, file: string, turns: number): void {
+  const branch = fork.getBranch();
+  const cut = branch.filter((entry) => entry.type === 'message' && entry.message.role === 'user')[turns];
+  if (cut === undefined) return;
+  const kept = [fork.getHeader(), ...branch.slice(0, branch.indexOf(cut))];
+  writeFileSync(file, kept.map((entry) => `${JSON.stringify(entry)}\n`).join(''), { mode: 0o600 });
+}
+
+/**
+ * Tools a writable launch gives back: those a launch-only readonly run (plan mode) took from the agent's last writable
+ * loadout. Pi restores the tool loadout a session last recorded, so without them the agent would stay readonly.
+ */
+export function readonlyLaunchRestores(transcript: string): string[] {
+  const active = new Set<string>();
+  let writable: string[] = [];
+  for (const entry of SessionManager.open(transcript).getBranch()) {
+    if (entry.type !== 'message' || entry.message.role !== 'system') continue;
+    for (const tool of entry.message.toolsRemoved ?? []) active.delete(tool.name);
+    for (const tool of entry.message.toolsAdded ?? []) active.add(tool.name);
+    if (active.has('write') || active.has('edit')) writable = [...active];
+  }
+  return writable.filter((name) => !active.has(name));
+}
+
+/** IDs of every agent with a record in `dir`. */
+export function recordIds(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => name.endsWith('.json'))
+    .map((name) => name.slice(0, -'.json'.length));
+}
+
+function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+const isPid = (value: number) => Number.isInteger(value) && value > 0;
+
+/** The live pid the agent's run lock names, or undefined when no live process holds it. */
+export function runningPid(dir: string, agentId: string): number | undefined {
+  const holder = holderOf(join(dir, `${agentId}.lock`));
+  return holder !== undefined && isPid(holder) && alive(holder) ? holder : undefined;
+}
+
+/** The pid a lock names: undefined when the file is gone, NaN when it holds no readable pid. */
+function holderOf(path: string): number | undefined {
+  try {
+    return Number.parseInt(readFileSync(path, 'utf8'), 10);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+function createExclusive(path: string): boolean {
+  try {
+    writeFileSync(path, String(process.pid), { flag: 'wx', mode: 0o600 });
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'EEXIST') return false;
+    throw error;
+  }
+}
+
+function writeAtomically(path: string, text: string): void {
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, text, { mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+const stillRunning = (agentId: string, holder: number | undefined, path: string) =>
+  new Error(`Agent ${agentId} is still running (pid ${holder !== undefined && isPid(holder) ? holder : 'unknown'}; lock ${path}). Wait for its completion before resuming it.`);
+
+export interface RunLock {
+  /** Names the process that writes the transcript, so the lock stays held exactly as long as that process lives. */
+  holdFor: (pid: number) => void;
+  /** Removes the lock unless another holder has taken it over since. */
+  release: () => void;
+}
+
+/**
+ * Pi appends to a session file without a lock, so two processes on one agent ID would interleave its transcript.
+ * The lock file holds the pid of the process writing the transcript. A lock without a readable pid counts as held.
+ * A dead holder's lock is removed only if it still names that holder, then created again exclusively; two
+ * processes taking over the same stale lock in the narrow window between that re-read and the removal can both succeed.
+ */
+export function acquireRunLock(dir: string, agentId: string): RunLock {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const path = join(dir, `${agentId}.lock`);
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    if (createExclusive(path)) {
+      let owner = process.pid;
+      return {
+        holdFor: (pid) => {
+          writeAtomically(path, String(pid));
+          owner = pid;
+        },
+        // Best effort: a lock left behind names a pid that will be dead, so the next acquire takes it over.
+        release: () => {
+          try {
+            if (holderOf(path) === owner) rmSync(path, { force: true });
+          } catch (error) {
+            if (!['EACCES', 'EPERM', 'EROFS', 'EBUSY', 'EIO'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
+          }
+        },
+      };
+    }
+    const holder = holderOf(path);
+    if (holder !== undefined && (!isPid(holder) || alive(holder))) throw stillRunning(agentId, holder, path);
+    if (holder !== undefined && holderOf(path) === holder) rmSync(path, { force: true });
+  }
+  throw stillRunning(agentId, holderOf(path), path);
+}

package/src/task/registry.ts

@@ -0,0 +1,77 @@
+import type { AgentActivityOutcome, BoundaryResult, ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { isOneShot } from '../modes.ts';
+import { type NotificationFields, notificationText } from './format.ts';
+import type { ChildHandle, ChildOutcome } from './runner.ts';
+
+export const NOTIFICATION_TYPE = 'pstack/task';
+
+interface Running {
+  settled: Promise<void>;
+  handle: ChildHandle;
+  /** How the child runs now, which can be stricter than its record (plan mode). */
+  readonly: boolean;
+  background: boolean;
+}
+
+export interface BackgroundNotice {
+  title: string;
+  toolCallId: string;
+  mode: ExtensionContext['mode'];
+  detailFor: (outcome: ChildOutcome) => Pick<NotificationFields, 'status' | 'detail' | 'usage'>;
+}
+
+/**
+ * Every running child of this runtime, foreground and background, so one agent ID never has two writers here.
+ * Background completions become notices: a follow-up message in long-lived sessions, and a settle-time entry in
+ * one-shot print and JSON runs, which wait for them before exiting.
+ */
+export function createSubagentRegistry(pi: ExtensionAPI) {
+  const running = new Map<string, Running>();
+  const pending: NotificationFields[] = [];
+  let retired = false;
+
+  const deliver = (fields: NotificationFields, mode: ExtensionContext['mode']) => {
+    if (isOneShot(mode)) pending.push(fields);
+    else pi.sendMessage({ customType: NOTIFICATION_TYPE, content: notificationText(fields), display: true, details: fields }, { triggerTurn: true, deliverAs: 'followUp' });
+  };
+
+  /** Registers synchronously, before any await in the caller, so a sibling call in the same message sees it. */
+  const track = (agentId: string, handle: ChildHandle, release: () => void, readonly: boolean, notice?: BackgroundNotice) => {
+    const settled = handle.done.then((outcome) => {
+      running.delete(agentId);
+      release();
+      // Shutdown killed this child; the retired runtime's pi must not be touched.
+      if (retired || notice === undefined) return;
+      deliver({ ...notice.detailFor(outcome), agentId, title: notice.title, toolCallId: notice.toolCallId }, notice.mode);
+    });
+    running.set(agentId, { settled, handle, readonly, background: notice !== undefined });
+  };
+
+  const backgroundRunning = () => [...running.values()].filter((entry) => entry.background);
+
+  /** An aborted run ends now: a one-shot run does not hold its exit for background subagents after Escape or a watchdog abort. */
+  const beforeSettle = async (ctx: ExtensionContext, outcome: AgentActivityOutcome): Promise<BoundaryResult | undefined> => {
+    if (!isOneShot(ctx.mode) || outcome === 'aborted' || (pending.length === 0 && backgroundRunning().length === 0)) return undefined;
+    if (pending.length === 0) await Promise.race(backgroundRunning().map((entry) => entry.settled));
+    const ready = pending.splice(0);
+    return { entries: ready.map((fields) => ({ type: 'custom_message' as const, customType: NOTIFICATION_TYPE, content: notificationText(fields), display: true, details: fields })), continue: true };
+  };
+
+  const shutdown = (): number => {
+    retired = true;
+    const background = backgroundRunning().length;
+    for (const entry of running.values()) entry.handle.kill();
+    running.clear();
+    pending.splice(0);
+    return background;
+  };
+
+  return {
+    isRunning: (agentId: string) => running.has(agentId),
+    get: (agentId: string): Pick<Running, 'handle' | 'readonly'> | undefined => running.get(agentId),
+    hasBackgroundWork: () => backgroundRunning().length > 0,
+    track,
+    beforeSettle,
+    shutdown,
+  };
+}