@yusukeshib/pi-babysit 0.4.0 → 0.5.0

package/README.md

@@ -33,7 +33,7 @@ reachable from anywhere (`~/.pi-babysit/<pi-session-id>/`). Two kinds:
 | kind | started by | completion | on completion |
 | ---- | ---------- | ---------- | ------------- |
 | **process** | `babysit_run { command }` | process **exit** | automatic notification message (`triggerTurn`), batched for all exits observed in the same poll — the agent may end its turn after starting and is resumed on exit, same contract as the old `process` tool |
-| **subagent** | `babysit_run { profile: "subagent", task }` | `agent_settled` in the RPC event stream (worker remains reusable during its idle grace) | none — the agent polls `babysit_check` or blocks on `babysit_wait`; the idle session accepts follow-up tasks until self-reap |
+| **subagent** | `babysit_run { profile: "subagent", task }` | `agent_settled` in the RPC event stream (worker remains reusable during its idle grace) | `foreground: true` returns the answer and nested usage in the same tool call; background workers must be collected with `babysit_wait` before the parent finishes, and remain reusable until self-reap |
 
 The **profile is a tool parameter, not a separate tool set**: domain knowledge
 (RPC bookkeeping, per-task byte offsets, parked-turn detection, PTY-safe
@@ -56,7 +56,7 @@ programs** (installers, wizards, REPLs): type with `babysit_send`
 
 | Tool | What it does |
 | ---- | ------------ |
-| `babysit_run` | Run any command (`command`, optional `name`/`pty`/`timeout`/`idleTimeout`/`retryOnWorkerDeath`/`notificationGroup`). Set `foreground: true` when the next step needs the result in the same tool call; use `returnPattern`/`returnLines`/`maxBytes` to keep noisy output bounded without a second check turn. Or start a named subagent (`profile: "subagent"`, `task`, optional `name`/`agent`/`model`/`tools`/`maxDepth` and budget fields). `maxDepth` defaults to 1. Quick commands return inline; longer ones notify in the background |
+| `babysit_run` | Run any command (`command`, optional `name`/`pty`/`timeout`/`idleTimeout`/`retryOnWorkerDeath`/`notificationGroup`). Set `foreground: true` for one process or subagent whose result is needed in the same tool call; use `returnPattern`/`returnLines`/`maxBytes` to keep noisy process output bounded. Or start a named background subagent (`profile: "subagent"`, `task`, optional `name`/`agent`/`model`/`tools`/`maxDepth` and budget fields), then always collect it with `babysit_wait`. `maxDepth` defaults to 1. Quick commands return inline; longer process runs notify in the background |
 | `babysit_check` | Without an id, list sessions with state/kind filters. With an id, inspect bounded output, search with `pattern`, or capture a TUI with `screen: true`; `maxBytes` overrides the 4 KB default up to 24 KB |
 | `babysit_send` | Process: type `text` / press `keys` into the PTY. Subagent: steer mid-run, or send a follow-up task when confirmed settled (`mode: auto/steer/task`); explicit task mode rejects busy, parked, or unknown state |
 | `babysit_wait` | Block until done: process exit (or `expect: "regex"` readiness marker), subagent task completion. Multi-wait: up to 32 unique `ids` + `mode: "any"\|"all"` |
@@ -117,7 +117,12 @@ Set `PI_BABYSIT_RPC_LOG_MODE=standard` only when legacy lifecycle payloads are
 needed for debugging. Live `/babysit` and attach views render either format.
 
 All shell commands, including `pwd` and Git, go through `babysit_run`. Bundle
-closely related tiny observations when doing so safely reduces tool turns.
+closely related tiny observations when doing so safely reduces tool turns. For
+parallel checks, do not issue sibling `foreground: true` calls: start them with
+`continueAfterStart: true` and collect them in one multi-session `babysit_wait`.
+During fix loops, prefer targeted checks after each edit and one full validation
+suite at the end. Background subagents must likewise be collected before the
+parent task finishes so their answer and nested usage are not lost.
 Set `PI_BABYSIT_ALLOW_BASH=1` only as an explicit emergency escape hatch.
 
 ## Unexpected worker loss
@@ -143,7 +148,10 @@ because blindly rerunning an arbitrary command can duplicate side effects.
   their exits span multiple polls.
   `babysit_kill` and an exit already reported by `babysit_wait` suppress the
   notification.
-- **Subagent**: `babysit_wait` blocks on `babysit expect '"type":"agent_settled"'`.
+- **Subagent**: `foreground: true` or `babysit_wait` blocks on
+  `babysit expect '"type":"agent_settled"'`. A background task that settles or
+  exits before it is collected emits one ready-to-collect reminder; the parent
+  must still call `babysit_wait` so the answer and nested usage are persisted.
   Unlike `agent_end`, `agent_settled` cannot precede an automatic retry,
   compaction retry, or queued continuation. A settled run containing a
   **parked** toolResult — a `babysit_run { command }` result carrying the

package/index.ts

@@ -418,6 +418,13 @@ interface Meta {
 	budgetKilled?: boolean;
 	/** Prompt offset whose nested usage has already been charged to the parent session. */
 	usageReportedOffset?: number;
+	/** Prompt offset explicitly collected by foreground mode or babysit_wait. */
+	subagentCollectedOffset?: number;
+	/** Prompt offset whose ready-to-collect reminder was sent to the parent. */
+	subagentNotifiedOffset?: number;
+	/** Current task completion first observed by the reminder poller. */
+	subagentCompletionObservedOffset?: number;
+	subagentCompletionObservedAt?: number;
 }
 
 const metaDir = () => path.join(ROOT, "meta");
@@ -731,6 +738,16 @@ export function shouldDeliverProcessCompletion(
 	return meta?.kind === "process" && !meta.notified && !meta.notificationPaused;
 }
 
+export function shouldDeliverSubagentCompletion(meta: Meta | null): meta is Meta & { kind: "subagent" } {
+	if (meta?.kind !== "subagent") return false;
+	const offset = meta.promptOffset ?? 0;
+	return (
+		meta.usageReportedOffset !== offset &&
+		meta.subagentCollectedOffset !== offset &&
+		meta.subagentNotifiedOffset !== offset
+	);
+}
+
 export function isNotificationGroupReady(
 	meta: Meta,
 	sessions: BsSession[],
@@ -752,10 +769,14 @@ export function shouldKeepPolling(
 	sessions: Array<{ id: string; state: string }>,
 	metaFor: (id: string) => Meta | null,
 ): boolean {
-	return sessions.some(
-		(session) =>
-			session.state === "running" || shouldDeliverProcessCompletion(metaFor(session.id)),
-	);
+	return sessions.some((session) => {
+		const meta = metaFor(session.id);
+		return (
+			session.state === "running" ||
+			shouldDeliverProcessCompletion(meta) ||
+			(session.state !== "running" && shouldDeliverSubagentCompletion(meta))
+		);
+	});
 }
 
 export function shouldKeepPollingAfterList(
@@ -2457,16 +2478,27 @@ async function waitForTask(
 	}
 }
 
-// Mark a process session as already-reported so the exit-notification poller
-// doesn't send a duplicate message for something the agent just observed.
+// Mark a session as already reported so completion pollers do not send a
+// duplicate message for something the agent just observed.
 function suppressNotify(id: string, reason: "observed" | "kill" = "observed"): void {
 	const meta = readMeta(id);
-	if (meta && meta.kind === "process") {
+	if (!meta) return;
+	if (meta.kind === "process") {
 		meta.notified = true;
 		if (reason === "kill") meta.killNotificationSuppressed = true;
 		delete meta.notificationPaused;
-		writeMeta(id, meta);
+	} else {
+		meta.subagentCollectedOffset = meta.promptOffset ?? 0;
 	}
+	writeMeta(id, meta);
+}
+
+function collectSubagentOutcome(outcome: WaitOutcome): void {
+	if (outcome.kind !== "done" && outcome.kind !== "exited") return;
+	const meta = readMeta(outcome.id);
+	if (!meta || meta.kind !== "subagent") return;
+	meta.subagentCollectedOffset = meta.promptOffset ?? 0;
+	writeMeta(outcome.id, meta);
 }
 
 export interface WaitReservationState {
@@ -2574,10 +2606,23 @@ async function waitForExit(
 		// one concurrent wait timing out cannot re-enable notifications underneath
 		// another wait that is still pending.
 		updateWaitReservation(id, "reserve");
-		const w = await bs(["wait", "-s", id, "--timeout", t], { signal });
-		if (signal?.aborted) {
-			updateWaitReservation(id, "abandon");
-			return { id, kind: "interrupted", ok: false, text: `wait for ${id} was interrupted.` };
+		let w: Awaited<ReturnType<typeof bs>>;
+		let attempt = 0;
+		for (;;) {
+			w = await bs(["wait", "-s", id, "--timeout", t], { signal });
+			if (signal?.aborted) {
+				updateWaitReservation(id, "abandon");
+				return { id, kind: "interrupted", ok: false, text: `wait for ${id} was interrupted.` };
+			}
+			if (w.code === 0 || w.code === 124 || w.code === 130) break;
+
+			// A freshly spawned session can be visible in `list` before the backend's
+			// wait endpoint is ready, especially when sibling foreground tools start
+			// concurrently. Retry that transient startup race instead of reporting the
+			// still-running child as "exited with code ?".
+			const retryStatus = await statusOf(id);
+			if (retryStatus?.state !== "running" || attempt++ >= 3) break;
+			await new Promise((resolve) => setTimeout(resolve, 50 * attempt));
 		}
 		if (w.code === 130) {
 			const interruptedStatus = await statusOf(id);
@@ -2619,6 +2664,18 @@ async function waitForExit(
 		if (!expectPattern) updateWaitReservation(id, "claim");
 		return { id, kind: "exited", ok: false, text: `No such session: ${id}` };
 	}
+	if (st.state === "running") {
+		if (!expectPattern) updateWaitReservation(id, "abandon");
+		return {
+			id,
+			kind: "interrupted",
+			ok: false,
+			text:
+				`The wait backend returned before process ${id} exited; the process is still running. ` +
+				`Use babysit_wait to continue waiting.\nLog: ${logPath(id)}`,
+			status: st,
+		};
+	}
 	if (expectPattern) suppressNotify(id);
 	else updateWaitReservation(id, "claim"); // the agent sees the exit here; don't notify again
 	const meta = readMeta(id);
@@ -2964,6 +3021,64 @@ export default function (pi: ExtensionAPI) {
 		);
 	}
 
+	async function notifySettledSubagents(
+		ctx: ExtensionContext,
+		snapshot?: BsSession[],
+	): Promise<void> {
+		if (shouldDeferCompletionNotification(ctx.isIdle())) return;
+		const sessions = snapshot ?? (await listSessions()).sessions;
+		const ready: Array<{ id: string; offset: number; state: string; summary: string }> = [];
+		for (const session of sessions) {
+			const meta = readMeta(session.id);
+			if (!shouldDeliverSubagentCompletion(meta)) continue;
+			let progress: Progress;
+			try {
+				progress = taskProgressOf(session.id).progress;
+			} catch {
+				progress = emptyProgress();
+			}
+			if (session.state === "running" && !progress.done) continue;
+
+			const offset = meta.promptOffset ?? 0;
+			if (meta.subagentCompletionObservedOffset !== offset) {
+				meta.subagentCompletionObservedOffset = offset;
+				meta.subagentCompletionObservedAt = Date.now();
+				writeMeta(session.id, meta);
+				continue;
+			}
+			if (Date.now() - (meta.subagentCompletionObservedAt ?? 0) < POLL_MS) continue;
+			const summary = progress.done
+				? `task settled; ${progress.turns} turns, ${progress.toolCallCount} tools, $${progress.cost.toFixed(4)}`
+				: `worker ${session.state} with exit code ${session.exit_code ?? "?"}; partial usage $${progress.cost.toFixed(4)}`;
+			ready.push({ id: session.id, offset, state: session.state, summary });
+		}
+		if (ready.length === 0 || shouldDeferCompletionNotification(ctx.isIdle())) return;
+
+		const deliverable = ready.filter(({ id, offset }) => {
+			const meta = readMeta(id);
+			return shouldDeliverSubagentCompletion(meta) && (meta.promptOffset ?? 0) === offset;
+		});
+		if (deliverable.length === 0) return;
+		pi.sendMessage(
+			{
+				customType: "pi-babysit-subagent-ready",
+				content:
+					`${deliverable.length === 1 ? "A background subagent is" : `${deliverable.length} background subagents are`} ready to collect:\n` +
+					deliverable.map(({ id, summary }) => `- ${id}: ${summary}`).join("\n") +
+					"\nCall babysit_wait now to retrieve the answer and charge nested usage before finishing the parent task.",
+				display: true,
+				details: { subagents: deliverable.map(({ id, state }) => ({ id, state })) },
+			},
+			{ triggerTurn: true, deliverAs: "steer" },
+		);
+		for (const { id, offset } of deliverable) {
+			const meta = readMeta(id);
+			if (!meta || meta.kind !== "subagent" || (meta.promptOffset ?? 0) !== offset) continue;
+			meta.subagentNotifiedOffset = offset;
+			writeMeta(id, meta);
+		}
+	}
+
 	const refreshWidget = async (ctx: ExtensionContext, snapshot?: BsSession[]) => {
 		if (!ctx.hasUI) return;
 		const active = (snapshot ?? (await listSessions()).sessions).filter(
@@ -3157,6 +3272,7 @@ export default function (pi: ExtensionAPI) {
 				await enforceSubagentBudgets(snapshot);
 				await Promise.all([
 					notifyEndedProcesses(ctx, snapshot),
+					notifySettledSubagents(ctx, snapshot),
 					refreshWidget(ctx, snapshot),
 				]);
 				pruneTerminalSessionCache(taskProgressCache, snapshot);
@@ -3228,12 +3344,13 @@ export default function (pi: ExtensionAPI) {
 			"`returnPattern`/`returnLines` bound foreground output. Sessions support check, wait, send, and kill.",
 		promptSnippet: "Run supervised commands or bounded pi subagents with context-safe logs",
 		promptGuidelines: [
-			"Use babysit_run for shell commands and give meaningful sessions a stable name; bundle tiny related observations.",
-			"Use babysit_run foreground mode when the next step needs the result; use returnPattern/returnLines for noisy commands. Do not foreground unbounded servers.",
+			"Use babysit_run for shell commands and give meaningful sessions a stable name; bundle tiny related read-only observations into one command.",
+			"Use babysit_run foreground mode for one process or subagent whose result is needed now; never issue sibling foreground runs in parallel. For parallel checks, start background runs with continueAfterStart and collect them with one multi-session babysit_wait.",
+			"Use returnPattern/returnLines for noisy commands. During edit/fix loops run targeted checks first and one full validation suite at the end instead of repeating every full gate.",
 			"After a background process starts, stop the turn for its automatic notification; never poll or sleep. Use continueAfterStart only for specific non-polling work.",
 			"Inspect large logs with a narrow babysit_check pattern and maxBytes rather than broad tails.",
 			"Use retryOnWorkerDeath only once and only for idempotent commands; retries may duplicate side effects.",
-			"Delegate independent work with bounded babysit_run subagents; set at least one cost/turn/tool/token budget and keep making progress before babysit_wait.",
+			"Delegate independent work with bounded babysit_run subagents. Prefer foreground for one result needed now; every background subagent must be collected with babysit_wait before the parent task finishes. Size budgets above the worker's initial context and expected tool count.",
 			"Subagent recursion defaults to depth 1; only a top-level caller may explicitly raise maxDepth.",
 		],
 		parameters: Type.Object({
@@ -3321,7 +3438,7 @@ export default function (pi: ExtensionAPI) {
 			),
 			foreground: Type.Optional(
 				Type.Boolean({
-					description: "Process: wait for exit and return the result now.",
+					description: "Process or subagent: wait for completion and return the result in this tool call.",
 				}),
 			),
 			returnPattern: Type.Optional(
@@ -3396,16 +3513,16 @@ export default function (pi: ExtensionAPI) {
 					details: {},
 				};
 			}
-			if (isSubagent && params.foreground) {
+			if (isSubagent && (params.returnPattern || params.returnLines != null || params.maxBytes != null)) {
 				return {
-					content: [{ type: "text", text: "`foreground` is available only in process mode; use babysit_wait for subagent task completion." }],
+					content: [{ type: "text", text: "`returnPattern`, `returnLines`, and `maxBytes` are process-output options." }],
 					isError: true,
 					details: {},
 				};
 			}
-			if (isSubagent && (params.returnPattern || params.returnLines != null || params.maxBytes != null)) {
+			if (isSubagent && params.continueAfterStart != null) {
 				return {
-					content: [{ type: "text", text: "`returnPattern`, `returnLines`, and `maxBytes` are process-output options." }],
+					content: [{ type: "text", text: "`continueAfterStart` is available only in process mode." }],
 					isError: true,
 					details: {},
 				};
@@ -3625,15 +3742,37 @@ export default function (pi: ExtensionAPI) {
 
 			pollNeeded = true;
 			await refreshWidget(ctx);
+			if (params.foreground || !ctx.hasUI) {
+				const outcome = await waitForTask(res.id, null, _signal);
+				collectSubagentOutcome(outcome);
+				const usage = claimOutcomeUsage(outcome);
+				if (ctx.hasUI) await refreshWidget(ctx);
+				return {
+					content: [{ type: "text", text: outcome.text }],
+					isError: !outcome.ok,
+					usage,
+					details: {
+						id: res.id,
+						kind: "subagent",
+						name: params.name ?? res.id,
+						agent: agent?.name,
+						model: res.model,
+						task: params.task,
+						depth: subagentNesting.childDepth,
+						maxDepth: subagentNesting.maxDepth,
+						status: outcomeStatus(outcome),
+					},
+				};
+			}
 			return {
 				content: [
 					{
 						type: "text",
 						text:
 							`Subagent started (id: ${res.id})${agent ? ` [agent: ${agent.name}]` : ""}${res.model ? ` [model: ${res.model}]` : ""} [depth: ${subagentNesting.childDepth}/${subagentNesting.maxDepth}].\n` +
-							`Task accepted — running in the background; keep working (do NOT end your turn just to wait for it).\n` +
-							`Poll:  babysit_check { id: "${res.id}" }\n` +
-							`Wait:  babysit_wait  { id: "${res.id}" }\n` +
+							`Task accepted — running in the background. You MUST collect it with babysit_wait before finishing the parent task; use foreground: true next time when no independent work is available.\n` +
+							`Progress: babysit_check { id: "${res.id}" } (only when inspection is needed)\n` +
+							`Collect:  babysit_wait  { id: "${res.id}" }\n` +
 							`Human can watch/steer: /babysit (pick ${res.id})`,
 					},
 				],
@@ -4257,6 +4396,7 @@ export default function (pi: ExtensionAPI) {
 
 			if (ids.length === 1) {
 				const r = await waitFor(ids[0], limitMs, signal, params.expect);
+				collectSubagentOutcome(r);
 				const usage = claimOutcomeUsage(r);
 				return {
 					content: [{ type: "text", text: r.text }],
@@ -4277,6 +4417,7 @@ export default function (pi: ExtensionAPI) {
 					ids.map((i) => waitFor(i, limitMs, signal, params.expect)),
 				);
 				const ok = results.every((r) => r.ok);
+				results.forEach(collectSubagentOutcome);
 				const usage = sumNestedUsage(results.map(claimOutcomeUsage));
 				return {
 					content: [
@@ -4306,6 +4447,7 @@ export default function (pi: ExtensionAPI) {
 					ids.map((i) => waitFor(i, limitMs, ctrl.signal, params.expect)),
 				);
 				const others = ids.filter((i) => i !== first.id);
+				collectSubagentOutcome(first);
 				const usage = claimOutcomeUsage(first);
 				return {
 					content: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yusukeshib/pi-babysit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Run any shell command and pi subagents under babysit, with context-safe captured output.",
   "keywords": [
     "pi-package",