@nredd/pi-session-kit 0.0.0-stage → 0.4.0

package/src/goal/index.ts

@@ -0,0 +1,343 @@
+/**
+ * `/goal`: keep a session working on an objective until the model proves it is done.
+ *
+ * While a goal is active, `agent_before_settle` turns a settle into one more turn (a hidden nudge
+ * message), unless something else already continues the run or the goal must yield (Plan mode,
+ * background subagents, queued messages, budget). The model ends the goal with `goal_update`.
+ * State lives only in `session-kit:goal` session entries, rebuilt from the branch at
+ * `session_start`, so two sessions never share anything.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { isChildSession, registerChildIdentity, registerParentTool } from "../child.ts";
+import { type Clock, realClock, type TimerHandle } from "../clock.ts";
+import type { KitConfig } from "../config.ts";
+import { coordination, planModeActive, planModeEnteredSince, watchQuota, watchStops } from "../shared.ts";
+import {
+	applyUpdate,
+	chipText,
+	decideNudge,
+	describeGoal,
+	GOAL_ENTRY,
+	GOAL_NUDGE_TYPE,
+	GOAL_TOOL,
+	type Goal,
+	type GoalSnapshot,
+	kickoffPrompt,
+	newGoal,
+	nudgeText,
+	parseGoalArgs,
+	pauseGoal,
+	recordTurn,
+	restoreGoal,
+	resumeGoal,
+} from "./state.ts";
+import { SubagentTracker } from "./subagents.ts";
+
+const STATUS_KEY = "session-kit-goal";
+/** How long a goal that skipped its nudge for subagents waits for their notice before waking itself. */
+export const WAKE_MS = 4_000;
+const SUBCOMMANDS = ["status", "pause", "resume", "clear"];
+
+interface UsageLike {
+	input?: number;
+	output?: number;
+	cacheWrite?: number;
+}
+
+/** New tokens a finished assistant message consumed: input + output + cache writes (not cache reads). */
+export function turnTokens(message: unknown): number {
+	const m = message as { role?: string; usage?: UsageLike } | undefined;
+	if (m?.role !== "assistant" || !m.usage) return 0;
+	return (m.usage.input ?? 0) + (m.usage.output ?? 0) + (m.usage.cacheWrite ?? 0);
+}
+
+export function register(pi: ExtensionAPI, _config: KitConfig, clock: Clock = realClock): void {
+	registerChildIdentity(pi);
+	const shared = coordination(pi);
+	let goal: Goal | undefined;
+	let lastCtx: ExtensionContext | undefined;
+	let wakeTimer: TimerHandle | undefined;
+	let skippedForAgents = false;
+
+	const clearWake = (): void => {
+		wakeTimer?.cancel();
+		wakeTimer = undefined;
+	};
+
+	const armWake = (): void => {
+		if (wakeTimer !== undefined || goal?.status !== "active" || shared.quotaParked.size > 0) return;
+		wakeTimer = clock.setTimeout(() => {
+			wakeTimer = undefined;
+			const ctx = lastCtx;
+			if (!ctx || !goal || goal.status !== "active" || isChildSession(pi) || shared.quotaParked.size > 0) return;
+			try {
+				// Only RUNNING agents hold the wake: a notice not delivered by now is not coming.
+				if (!ctx.isIdle() || tracker.runningCount() > 0 || planModeActive(ctx)) return;
+				skippedForAgents = false;
+				pi.sendUserMessage(nudgeText(goal));
+			} catch {
+				// Stale context: the session is gone.
+			}
+		}, WAKE_MS);
+	};
+
+	const tracker = new SubagentTracker(() => {
+		if (skippedForAgents) armWake();
+	});
+
+	const ensureTool = (ctx: ExtensionContext): void => {
+		const want = goal?.status === "active" && !isChildSession(pi) && !planModeActive(ctx);
+		const active = pi.getActiveTools();
+		const has = active.includes(GOAL_TOOL);
+		if (want && !has) pi.setActiveTools([...active, GOAL_TOOL]);
+		else if (!want && has) pi.setActiveTools(active.filter((name) => name !== GOAL_TOOL));
+	};
+
+	const syncUi = (ctx: ExtensionContext): void => {
+		shared.goalActive = goal?.status === "active";
+		ctx.ui.setStatus(STATUS_KEY, goal ? chipText(goal, tracker.runningCount()) : undefined);
+		ensureTool(ctx);
+	};
+
+	const commit = (ctx: ExtensionContext, next: Goal | undefined): void => {
+		goal = next;
+		pi.appendEntry<GoalSnapshot>(GOAL_ENTRY, { version: 1, goal: next ?? null });
+		syncUi(ctx);
+	};
+
+	/**
+	 * Entering Plan mode pauses an active goal, even when Plan mode was entered AND left while the
+	 * goal sat idle (no event fires then, so the branch's `plan-mode-state` entries are replayed
+	 * back to the goal's last state entry). Returns whether Plan mode is on right now.
+	 */
+	const guardPlanMode = (ctx: ExtensionContext): boolean => {
+		const on = planModeActive(ctx);
+		const excursion =
+			!on && goal?.status === "active" && planModeEnteredSince(ctx.sessionManager.getBranch(), GOAL_ENTRY);
+		if (!on && !excursion) return false;
+		if (goal?.status === "active") {
+			commit(ctx, pauseGoal(goal, "plan mode"));
+			ctx.ui.notify("goal paused: Plan mode was entered. /goal resume after leaving it", "info");
+		}
+		return on;
+	};
+
+	shared.reconcilePlanMode = guardPlanMode;
+
+	const rebuild = (ctx: ExtensionContext): void => {
+		lastCtx = ctx;
+		clearWake();
+		skippedForAgents = false;
+		tracker.dispose();
+		goal = undefined;
+		shared.goalActive = false;
+		if (isChildSession(pi)) return;
+		tracker.attach(pi.events);
+		goal = restoreGoal(ctx.sessionManager.getBranch());
+		syncUi(ctx);
+		if (goal?.reason === "session restored") {
+			ctx.ui.notify(`goal restored paused: ${goal.objective}. /goal resume to continue`, "info");
+		}
+	};
+
+	/**
+	 * Start work right away when the session can take it. Print/JSON mode dispose the session as
+	 * soon as the command returns, killing an un-awaited run, so there the next prompt starts the goal.
+	 */
+	const kickoff = (ctx: ExtensionContext, text: string): void => {
+		if ((ctx.mode === "tui" || ctx.mode === "rpc") && ctx.isIdle()) pi.sendUserMessage(text);
+	};
+
+	pi.on("session_start", (_event, ctx) => rebuild(ctx));
+	pi.on("session_tree", (_event, ctx) => rebuild(ctx));
+	pi.on("session_shutdown", () => {
+		clearWake();
+		tracker.dispose();
+		shared.goalActive = false;
+		shared.reconcilePlanMode = undefined;
+		goal = undefined;
+	});
+
+	pi.on("before_agent_start", (_event, ctx) => {
+		if (isChildSession(pi)) return;
+		lastCtx = ctx;
+		guardPlanMode(ctx);
+		syncUi(ctx);
+	});
+
+	pi.on("agent_start", () => clearWake());
+	pi.on("input", (_event, ctx) => {
+		if (isChildSession(pi)) return undefined;
+		lastCtx = ctx;
+		guardPlanMode(ctx);
+		return undefined;
+	});
+	pi.on("turn_start", (_event, ctx) => {
+		if (isChildSession(pi)) return;
+		lastCtx = ctx;
+		guardPlanMode(ctx);
+	});
+
+	pi.on("turn_end", (event, ctx) => {
+		if (isChildSession(pi)) return;
+		lastCtx = ctx;
+		guardPlanMode(ctx);
+		if (goal?.status !== "active") return;
+		const next = recordTurn(goal, turnTokens(event.message));
+		commit(ctx, next);
+		if (next.status === "budget")
+			ctx.ui.notify(`goal stopped: ${next.reason}. /goal ${next.objective} --turns N to go on`, "warning");
+	});
+
+	pi.on("agent_before_settle", (event, ctx) => {
+		if (isChildSession(pi)) return undefined;
+		lastCtx = ctx;
+		const planMode = guardPlanMode(ctx);
+		const decision = decideNudge({
+			goal,
+			isChild: false,
+			planMode,
+			continueAlready: event.continue,
+			// A settle after an assistant message reports canContinue=false until a draft ends the
+			// context with a user-role message; our nudge is that draft. Only an empty context cannot continue.
+			canContinue: event.context.canContinue || event.context.llmMessages.some((m) => m.role !== "system"),
+			outcome: event.outcome,
+			pendingMessages: Math.max(event.context.pendingMessages.length, ctx.hasPendingMessages() ? 1 : 0),
+			subagentsBusy: tracker.busy(),
+		});
+		skippedForAgents = !decision.nudge && decision.reason === "subagents busy";
+		if (!decision.nudge || !goal) return undefined;
+		return {
+			entries: [
+				...event.entries,
+				{ type: "custom_message", customType: GOAL_NUDGE_TYPE, content: nudgeText(goal), display: false },
+			],
+			continue: true,
+		};
+	});
+
+	// A parked/refused dispatch is not a failed provider request. Pause at its
+	// admission event, before settle can nudge and before a stale wake can fire.
+	watchQuota(pi, (reason, ctx) => {
+		clearWake();
+		skippedForAgents = false;
+		if (isChildSession(pi) || goal?.status !== "active") return;
+		commit(ctx, pauseGoal(goal, reason));
+		ctx.ui.notify(`goal paused: ${reason}. /goal resume after resolving quota`, "warning");
+	});
+
+	watchStops(pi, (outcome, ctx) => {
+		if (isChildSession(pi) || goal?.status !== "active") return;
+		const reason = outcome === "aborted" ? "run aborted" : "provider error";
+		commit(ctx, pauseGoal(goal, reason));
+		ctx.ui.notify(`goal paused: ${reason}. /goal resume to continue`, "warning");
+	});
+
+	pi.on("agent_settled", () => {
+		if (skippedForAgents) armWake();
+	});
+
+	pi.on("message_end", (event) => {
+		if ((event.message as { customType?: string }).customType === "subagent-notification") tracker.announced();
+	});
+	pi.on("tool_execution_end", (event) => {
+		if (event.toolName === "get_subagent_result") tracker.announced();
+	});
+
+	registerParentTool(pi, {
+		name: GOAL_TOOL,
+		label: "Goal Update",
+		description:
+			'End the active /goal. status "complete" needs evidence: the check that proves the objective is met (command + result). status "blocked" needs the reason you cannot proceed.',
+		promptSnippet: "Finish or block the active /goal (complete needs evidence)",
+		parameters: Type.Object({
+			status: Type.Union([Type.Literal("complete"), Type.Literal("blocked")], {
+				description: "complete: objective met. blocked: cannot proceed.",
+			}),
+			evidence: Type.String({ description: "complete: what proves it. blocked: why you are stuck." }),
+		}),
+		defaultActive: false,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const result = applyUpdate(goal, params.status, params.evidence);
+			if (!result.ok) throw new Error(result.error);
+			commit(ctx, result.goal);
+			ctx.ui.notify(
+				`goal ${result.goal.status}: ${result.goal.objective}`,
+				result.goal.status === "complete" ? "info" : "warning",
+			);
+			return {
+				content: [{ type: "text", text: `Goal marked ${result.goal.status}.` }],
+				details: { status: result.goal.status },
+			};
+		},
+	});
+
+	/**
+	 * Registered from `session_start`, not at load: a child (subagent) session is only recognisable
+	 * by its name, which does not exist at factory time. pi resolves extension commands lazily, so a
+	 * late registration is executable; children never register it.
+	 */
+	const registerGoalCommand = (): void => {
+		pi.registerCommand("goal", {
+			description:
+				"Work on an objective until done: /goal <objective> [--turns N] [--tokens N] | status | pause | resume | clear",
+			getArgumentCompletions: (prefix) => {
+				const items = SUBCOMMANDS.filter((name) => name.startsWith(prefix)).map((name) => ({
+					value: name,
+					label: name,
+				}));
+				return items.length > 0 ? items : null;
+			},
+			handler: async (args, ctx) => {
+				if (isChildSession(pi)) return;
+				lastCtx = ctx;
+				guardPlanMode(ctx);
+				const command = parseGoalArgs(args);
+				if (command.kind === "error") return ctx.ui.notify(command.message, "error");
+				if (command.kind === "status") {
+					const waiting = tracker.busy() > 0 ? `\nwaiting on ${tracker.busy()} subagent(s)` : "";
+					return ctx.ui.notify(describeGoal(goal) + waiting, "info");
+				}
+				if (command.kind === "clear") {
+					if (goal) commit(ctx, undefined);
+					return ctx.ui.notify("goal cleared", "info");
+				}
+				if (command.kind === "pause") {
+					if (goal?.status !== "active") return ctx.ui.notify("no active goal to pause", "error");
+					commit(ctx, pauseGoal(goal, "paused by user"));
+					return ctx.ui.notify("goal paused. /goal resume to continue", "info");
+				}
+				if (planModeActive(ctx)) {
+					return ctx.ui.notify(
+						"refused: Plan mode is active. Leave it (/plan) before starting or resuming a goal",
+						"error",
+					);
+				}
+				if (shared.quotaParked.size > 0) {
+					return ctx.ui.notify(
+						"refused: quota dispatch is still parked. Resolve it before starting or resuming a goal",
+						"error",
+					);
+				}
+				if (command.kind === "resume") {
+					if (!goal) return ctx.ui.notify("no goal to resume", "error");
+					const result = resumeGoal(goal);
+					if (!result.ok) return ctx.ui.notify(result.error, "error");
+					commit(ctx, result.goal);
+					kickoff(ctx, kickoffPrompt(result.goal, true));
+					return;
+				}
+				if (command.kind !== "set") return;
+				const started = newGoal(command.objective, command.maxTurns, command.maxTokens);
+				commit(ctx, started);
+				kickoff(ctx, kickoffPrompt(started, false));
+			},
+		});
+	};
+
+	pi.on("session_start", () => {
+		if (!isChildSession(pi)) registerGoalCommand();
+	});
+}

package/src/goal/state.ts

@@ -0,0 +1,270 @@
+/**
+ * Pure `/goal` logic: command parsing, the goal state machine, budgets and the nudge decision.
+ * No pi imports, so everything here is unit-testable without a runtime.
+ */
+
+export const GOAL_ENTRY = "session-kit:goal";
+export const GOAL_NUDGE_TYPE = "session-kit:goal-nudge";
+export const GOAL_TOOL = "goal_update";
+export const DEFAULT_TURNS = 30;
+
+export type GoalStatus = "active" | "paused" | "complete" | "blocked" | "budget";
+
+export interface Goal {
+	objective: string;
+	status: GoalStatus;
+	/** Parent turns consumed while the goal was active. */
+	turns: number;
+	maxTurns: number;
+	/** New tokens (input + output + cache writes) consumed while active. */
+	tokens: number;
+	maxTokens?: number;
+	/** Why the goal is not active: pause cause, blocker, or budget. */
+	reason?: string;
+	/** The proof given on completion. */
+	evidence?: string;
+}
+
+/** Persisted snapshot; the last one on a branch wins. `null` means cleared. */
+export interface GoalSnapshot {
+	version: 1;
+	goal: Goal | null;
+}
+
+export type GoalCommand =
+	| { kind: "set"; objective: string; maxTurns: number; maxTokens?: number }
+	| { kind: "status" | "pause" | "resume" | "clear" }
+	| { kind: "error"; message: string };
+
+const SUBCOMMANDS = new Set(["status", "pause", "resume", "clear"]);
+const COUNT = /^(\d+)([km])?$/i;
+
+/** `30`, `200k`, `1m` -> a positive integer. */
+export function parseCount(raw: string): number | undefined {
+	const match = COUNT.exec(raw.trim());
+	if (!match) return undefined;
+	const unit = match[2]?.toLowerCase();
+	const value = Number(match[1]) * (unit === "k" ? 1_000 : unit === "m" ? 1_000_000 : 1);
+	return Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+
+/** Parse `/goal` arguments. A subcommand word only counts when it is the whole argument. */
+export function parseGoalArgs(raw: string): GoalCommand {
+	const text = raw.trim();
+	if (text === "") return { kind: "status" };
+	if (SUBCOMMANDS.has(text)) return { kind: text as "status" | "pause" | "resume" | "clear" };
+	const words: string[] = [];
+	let maxTurns = DEFAULT_TURNS;
+	let maxTokens: number | undefined;
+	const tokens = text.split(/\s+/);
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i] as string;
+		const flag = /^--(turns|tokens)(?:=(.*))?$/.exec(token);
+		if (!flag) {
+			words.push(token);
+			continue;
+		}
+		const name = flag[1] as "turns" | "tokens";
+		const value = flag[2] ?? tokens[++i] ?? "";
+		const count = parseCount(value);
+		if (count === undefined) return { kind: "error", message: `--${name} needs a positive integer (got "${value}")` };
+		if (name === "turns") maxTurns = count;
+		else maxTokens = count;
+	}
+	const objective = words.join(" ");
+	if (objective === "") return { kind: "error", message: "usage: /goal <objective> [--turns N] [--tokens N]" };
+	return { kind: "set", objective, maxTurns, ...(maxTokens === undefined ? {} : { maxTokens }) };
+}
+
+export function newGoal(objective: string, maxTurns = DEFAULT_TURNS, maxTokens?: number): Goal {
+	return {
+		objective,
+		status: "active",
+		turns: 0,
+		maxTurns,
+		tokens: 0,
+		...(maxTokens === undefined ? {} : { maxTokens }),
+	};
+}
+
+interface EntryLike {
+	type?: string;
+	customType?: string;
+	data?: unknown;
+}
+
+const STATUSES: readonly string[] = ["active", "paused", "complete", "blocked", "budget"];
+
+const isCount = (value: unknown): value is number =>
+	typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+const isCap = (value: unknown): value is number => isCount(value) && value > 0;
+
+/**
+ * Validate a persisted goal field by field; anything malformed yields `undefined` so a damaged
+ * entry can never restore a goal with a disabled budget.
+ */
+function parseGoal(value: unknown): Goal | undefined {
+	if (typeof value !== "object" || value === null) return undefined;
+	const g = value as Record<string, unknown>;
+	if (typeof g.objective !== "string" || typeof g.status !== "string" || !STATUSES.includes(g.status)) return undefined;
+	if (!isCount(g.turns) || !isCap(g.maxTurns) || !isCount(g.tokens)) return undefined;
+	if (g.maxTokens !== undefined && !isCap(g.maxTokens)) return undefined;
+	if (g.reason !== undefined && typeof g.reason !== "string") return undefined;
+	if (g.evidence !== undefined && typeof g.evidence !== "string") return undefined;
+	return {
+		objective: g.objective,
+		status: g.status as GoalStatus,
+		turns: g.turns,
+		maxTurns: g.maxTurns,
+		tokens: g.tokens,
+		...(g.maxTokens === undefined ? {} : { maxTokens: g.maxTokens }),
+		...(g.reason === undefined ? {} : { reason: g.reason }),
+		...(g.evidence === undefined ? {} : { evidence: g.evidence }),
+	};
+}
+
+/**
+ * Rebuild the goal from a session branch. A goal that was active when the session was written
+ * comes back PAUSED: nothing is running after a restart, and resuming is an explicit act.
+ */
+export function restoreGoal(entries: readonly EntryLike[]): Goal | undefined {
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		if (entry?.type !== "custom" || entry.customType !== GOAL_ENTRY) continue;
+		const snapshot = entry.data as Partial<GoalSnapshot> | undefined;
+		if (snapshot?.version !== 1 || snapshot.goal === null) return undefined;
+		const goal = parseGoal(snapshot.goal);
+		if (!goal) return undefined;
+		return goal.status === "active" ? { ...goal, status: "paused", reason: "session restored" } : goal;
+	}
+	return undefined;
+}
+
+export function budgetExhausted(goal: Goal): "turns" | "tokens" | undefined {
+	if (goal.turns >= goal.maxTurns) return "turns";
+	if (goal.maxTokens !== undefined && goal.tokens >= goal.maxTokens) return "tokens";
+	return undefined;
+}
+
+/** Charge one finished parent turn; ends the goal when a budget runs out. No-op unless active. */
+export function recordTurn(goal: Goal, tokens: number): Goal {
+	if (goal.status !== "active") return goal;
+	const next: Goal = { ...goal, turns: goal.turns + 1, tokens: goal.tokens + Math.max(0, Math.trunc(tokens)) };
+	const spent = budgetExhausted(next);
+	return spent ? { ...next, status: "budget", reason: `${spent} budget exhausted` } : next;
+}
+
+export function pauseGoal(goal: Goal, reason: string): Goal {
+	return goal.status === "active" ? { ...goal, status: "paused", reason } : goal;
+}
+
+export type ResumeResult = { ok: true; goal: Goal } | { ok: false; error: string };
+
+/** `paused` and `blocked` goals resume; finished and budget-exhausted ones need a new `/goal`. */
+export function resumeGoal(goal: Goal): ResumeResult {
+	if (goal.status === "active") return { ok: false, error: "goal is already active" };
+	if (goal.status === "complete")
+		return { ok: false, error: "goal is complete; start a new one with /goal <objective>" };
+	if (goal.status === "budget") {
+		return {
+			ok: false,
+			error: `${goal.reason ?? "budget exhausted"}; start a new one with /goal <objective> --turns N`,
+		};
+	}
+	const { reason: _reason, ...rest } = goal;
+	return budgetExhausted(rest)
+		? { ok: false, error: "budget exhausted; start a new one with /goal <objective> --turns N" }
+		: { ok: true, goal: { ...rest, status: "active" } };
+}
+
+export type UpdateResult = { ok: true; goal: Goal } | { ok: false; error: string };
+
+/** The `goal_update` tool: `complete` needs non-empty evidence, same rule as rpiv-todo. */
+export function applyUpdate(goal: Goal | undefined, status: string, evidence: string | undefined): UpdateResult {
+	if (goal?.status !== "active") return { ok: false, error: "no active goal" };
+	const proof = (evidence ?? "").trim();
+	if (status === "complete") {
+		if (proof === "") {
+			return {
+				ok: false,
+				error: "evidence required to mark the goal complete: the check that proves it (command + result)",
+			};
+		}
+		return { ok: true, goal: { ...goal, status: "complete", evidence: proof, reason: undefined } };
+	}
+	if (status === "blocked") {
+		return { ok: true, goal: { ...goal, status: "blocked", reason: proof || "no reason given" } };
+	}
+	return { ok: false, error: `status must be "complete" or "blocked" (got "${status}")` };
+}
+
+export interface NudgeInput {
+	goal: Goal | undefined;
+	isChild: boolean;
+	planMode: boolean;
+	/** `event.continue`: another handler already continued this settle. */
+	continueAlready: boolean;
+	canContinue: boolean;
+	outcome: "completed" | "aborted" | "error";
+	/** Queued messages (e.g. a subagent notice follow-up) pi will run anyway. */
+	pendingMessages: number;
+	/** Background subagents running, or finished with their notice still unannounced. */
+	subagentsBusy: number;
+}
+
+export type NudgeDecision = { nudge: true } | { nudge: false; reason: string };
+
+/** Whether a settle should be turned into one more goal turn, and if not, why. */
+export function decideNudge(input: NudgeInput): NudgeDecision {
+	const skip = (reason: string): NudgeDecision => ({ nudge: false, reason });
+	if (input.isChild) return skip("child session");
+	if (input.goal?.status !== "active") return skip("no active goal");
+	if (input.planMode) return skip("plan mode");
+	if (input.outcome !== "completed") return skip(`run ${input.outcome}`);
+	if (input.continueAlready) return skip("already continued");
+	if (!input.canContinue) return skip("cannot continue");
+	if (input.pendingMessages > 0) return skip("queued messages pending");
+	if (input.subagentsBusy > 0) return skip("subagents busy");
+	if (budgetExhausted(input.goal)) return skip("budget exhausted");
+	return { nudge: true };
+}
+
+/** The first message of a goal, and of a resume. */
+export function kickoffPrompt(goal: Goal, resumed: boolean): string {
+	const budget = `${goal.maxTurns} turns${goal.maxTokens === undefined ? "" : `, ${goal.maxTokens} tokens`}`;
+	return [
+		`${resumed ? "Resuming goal" : "Goal"}: ${goal.objective}`,
+		`Work on it until it is done (budget: ${budget}). When finished, call goal_update with status "complete" and evidence (the check that proves it). If you cannot proceed, call goal_update with status "blocked" and the reason.`,
+	].join("\n");
+}
+
+/** The hidden settle nudge. */
+export function nudgeText(goal: Goal): string {
+	return `[goal ${goal.turns}/${goal.maxTurns} turns] Not complete yet: ${goal.objective}\nKeep working. When done call goal_update status "complete" with evidence; if stuck, status "blocked" with the reason.`;
+}
+
+/** Footer chip text. */
+export function chipText(goal: Goal, waitingOnAgents = 0): string {
+	const used = compact(goal.tokens);
+	const tokens =
+		goal.maxTokens !== undefined ? ` ${used}/${compact(goal.maxTokens)} tok` : goal.tokens > 0 ? ` ${used} tok` : "";
+	const state = goal.status === "active" ? "" : ` ${goal.status}`;
+	const wait =
+		waitingOnAgents > 0 && goal.status === "active"
+			? ` (waiting on ${waitingOnAgents} agent${waitingOnAgents === 1 ? "" : "s"})`
+			: "";
+	return `goal ${goal.turns}/${goal.maxTurns}${tokens}${state}${wait}`;
+}
+
+function compact(n: number): string {
+	return n >= 1_000_000 ? `${+(n / 1_000_000).toFixed(1)}m` : n >= 1_000 ? `${+(n / 1_000).toFixed(1)}k` : String(n);
+}
+
+/** `/goal status` body. */
+export function describeGoal(goal: Goal | undefined): string {
+	if (!goal) return "no goal. /goal <objective> [--turns N] [--tokens N]";
+	const lines = [`goal (${goal.status}): ${goal.objective}`, chipText(goal)];
+	if (goal.reason) lines.push(`reason: ${goal.reason}`);
+	if (goal.evidence) lines.push(`evidence: ${goal.evidence}`);
+	return lines.join("\n");
+}

package/src/goal/subagents.ts

@@ -0,0 +1,77 @@
+/**
+ * Which background subagents a goal must wait for, from the `subagents:*` events pi-subagents
+ * emits on `pi.events` (see `~/code/pi-subagents/src/index.ts`).
+ *
+ * - `running`: between `created`/`started` and `completed`/`failed`.
+ * - `unannounced`: a background agent finished but its completion notice has not been delivered.
+ *   pi-subagents queues notices in an outbox and flushes them at `agent_end`, i.e. AFTER the
+ *   settle boundary, so a nudge sent at settle would run a turn in front of the notice.
+ *
+ * A nudge is skipped while either set is non-empty, so the notice (a `followUp` that triggers a
+ * turn) is delivered first and the goal nudges at the following settle.
+ */
+
+export interface EventBus {
+	on(event: string, handler: (data: unknown) => void): () => void;
+}
+
+function idOf(data: unknown): string | undefined {
+	const id = (data as { id?: unknown } | null)?.id;
+	return typeof id === "string" ? id : undefined;
+}
+
+export class SubagentTracker {
+	private readonly running = new Set<string>();
+	private readonly unannounced = new Set<string>();
+	private readonly background = new Set<string>();
+	private detach: (() => void)[] = [];
+
+	/** Called when the last running agent finishes, e.g. to re-arm the wake timer. */
+	constructor(private readonly onIdle: () => void = () => {}) {}
+
+	attach(events: EventBus): void {
+		this.detach.push(
+			events.on("subagents:created", (data) => {
+				const id = idOf(data);
+				if (!id) return;
+				this.running.add(id);
+				if ((data as { isBackground?: unknown }).isBackground === true) this.background.add(id);
+			}),
+			events.on("subagents:started", (data) => {
+				const id = idOf(data);
+				if (id) this.running.add(id);
+			}),
+			events.on("subagents:completed", (data) => this.finish(idOf(data))),
+			events.on("subagents:failed", (data) => this.finish(idOf(data))),
+		);
+	}
+
+	private finish(id: string | undefined): void {
+		if (!id) return;
+		this.running.delete(id);
+		if (this.background.delete(id)) this.unannounced.add(id);
+		if (this.running.size === 0) this.onIdle();
+	}
+
+	/** The notices were delivered (or the results fetched): nothing is waiting to be announced. */
+	announced(): void {
+		this.unannounced.clear();
+	}
+
+	busy(): number {
+		return this.running.size + this.unannounced.size;
+	}
+
+	runningCount(): number {
+		return this.running.size;
+	}
+
+	/** Drop every subscription and id (session shutdown). */
+	dispose(): void {
+		for (const off of this.detach) off();
+		this.detach = [];
+		this.running.clear();
+		this.unannounced.clear();
+		this.background.clear();
+	}
+}