@explyt/ai-agent 0.1.0-rc.1

package/node_modules/pi-subagents/src/missions/actions.ts

@@ -0,0 +1,433 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { Details } from "../shared/types.ts";
+import {
+	MISSION_STATUSES,
+	type MissionArtifact,
+	type MissionArtifactKind,
+	type MissionReceipt,
+	type MissionReceiptKind,
+	type MissionReceiptStatus,
+	type MissionRecord,
+	type MissionRunMode,
+	type MissionStatus,
+	type MissionStoreConfig,
+	type MissionStoreLocation,
+	type MissionTokenBudget,
+	type MissionUpdateInput,
+} from "./types.ts";
+import { missionStatePath } from "./workflow-state.ts";
+import {
+	createMission,
+	listGlobalMissions,
+	listMissions,
+	missionRecordPath,
+	readMission,
+	resolveMissionStoreLocation,
+	updateMission,
+	validateMissionId,
+} from "./store.ts";
+
+export const MISSION_ACTIONS = [
+	"mission.create",
+	"mission.list",
+	"mission.show",
+	"mission.update",
+	"mission.resolve-decision",
+	"mission.attach-run",
+	"mission.close",
+] as const;
+
+export type MissionAction = typeof MISSION_ACTIONS[number];
+
+export interface MissionLaunchInput {
+	title: string;
+	objective?: string;
+	goal?: true;
+	budget?: MissionTokenBudget;
+	labels?: string[];
+}
+
+export interface MissionUpdateToolInput {
+	title?: string;
+	objective?: string;
+	goal?: boolean | { paused: boolean };
+	budget?: MissionTokenBudget;
+	status?: MissionStatus;
+	summary?: string;
+	labels?: string[];
+	artifacts?: MissionArtifact[];
+	receipts?: Array<Omit<MissionReceipt, "createdAt">>;
+	decisions?: Array<{
+		title: string;
+		prompt?: string;
+		options?: string[];
+		recommendation?: string;
+	}>;
+}
+
+export interface MissionActionParams {
+	missionId?: string;
+	mission?: unknown;
+	missionUpdate?: unknown;
+	missionStatus?: string;
+	missionScope?: string;
+	id?: string;
+	runId?: string;
+	dir?: string;
+	runMode?: string;
+	runStatus?: string;
+	agent?: string;
+	summary?: string;
+}
+
+interface MissionActionContext {
+	cwd: string;
+	currentSessionId?: string;
+	config?: MissionStoreConfig;
+	agentDir?: string;
+}
+
+function textResult(text: string, details: Details): AgentToolResult<Details> {
+	return { content: [{ type: "text", text }], details };
+}
+
+function requireMissionId(params: MissionActionParams): string {
+	return validateMissionId(params.missionId, "missionId");
+}
+
+function validateStatus(value: unknown, label: string): MissionStatus {
+	if (typeof value !== "string" || !(MISSION_STATUSES as readonly string[]).includes(value)) {
+		throw new Error(`${label} must be one of ${MISSION_STATUSES.join(", ")}`);
+	}
+	return value as MissionStatus;
+}
+
+export function validateMissionLaunch(value: unknown): MissionLaunchInput {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("mission must be an object");
+	const input = value as Record<string, unknown>;
+	for (const key of Object.keys(input)) {
+		if (key !== "title" && key !== "summary" && key !== "objective" && key !== "goal" && key !== "budget" && key !== "labels") throw new Error(`mission.${key} is unknown`);
+	}
+	if (input.title !== undefined && input.summary !== undefined) throw new Error("mission.title and mission.summary cannot both be set");
+	const title = input.title ?? input.summary;
+	if (typeof title !== "string" || !title.trim()) throw new Error("mission.title or mission.summary must be a non-empty string");
+	if (input.objective !== undefined && (typeof input.objective !== "string" || !input.objective.trim())) throw new Error("mission.objective must be a non-empty string");
+	if (input.goal !== undefined && input.goal !== true) throw new Error("mission.goal must be true when supplied");
+	const budget = input.budget;
+	if (budget !== undefined && (!budget || typeof budget !== "object" || Array.isArray(budget) || !Number.isSafeInteger((budget as { tokens?: unknown }).tokens) || ((budget as { tokens: number }).tokens < 1))) {
+		throw new Error("mission.budget.tokens must be a positive integer");
+	}
+	if (input.goal === true && budget === undefined) throw new Error("mission.budget is required when mission.goal is true");
+	if (input.labels !== undefined && (!Array.isArray(input.labels) || input.labels.some((label) => typeof label !== "string" || !label.trim()))) {
+		throw new Error("mission.labels must contain only non-empty strings");
+	}
+	return {
+		title: title.trim(),
+		...(typeof input.objective === "string" ? { objective: input.objective.trim() } : {}),
+		...(input.goal === true ? { goal: true as const } : {}),
+		...(budget !== undefined ? { budget: { tokens: (budget as { tokens: number }).tokens } } : {}),
+		...(input.labels !== undefined ? { labels: input.labels.map((label) => label.trim()) } : {}),
+	};
+}
+
+function validateArtifact(value: unknown, index: number): MissionArtifact {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`missionUpdate.artifacts[${index}] must be an object`);
+	const input = value as Record<string, unknown>;
+	const kinds: MissionArtifactKind[] = ["status", "output", "patch", "manifest", "review", "note", "other"];
+	if (typeof input.kind !== "string" || !kinds.includes(input.kind as MissionArtifactKind)) throw new Error(`missionUpdate.artifacts[${index}].kind is invalid`);
+	if (typeof input.path !== "string" || !input.path.trim()) throw new Error(`missionUpdate.artifacts[${index}].path must be a non-empty string`);
+	if (input.description !== undefined && (typeof input.description !== "string" || !input.description.trim())) throw new Error(`missionUpdate.artifacts[${index}].description must be a non-empty string`);
+	return {
+		kind: input.kind as MissionArtifactKind,
+		path: input.path,
+		...(typeof input.description === "string" ? { description: input.description } : {}),
+	};
+}
+
+function validateReceipt(value: unknown, index: number): Omit<MissionReceipt, "createdAt"> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`missionUpdate.receipts[${index}] must be an object`);
+	const input = value as Record<string, unknown>;
+	for (const key of Object.keys(input)) {
+		if (!['kind', 'status', 'title', 'url', 'description'].includes(key)) throw new Error(`missionUpdate.receipts[${index}].${key} is unknown`);
+	}
+	const kinds: MissionReceiptKind[] = ["pull_request", "ci", "deployment", "release"];
+	const statuses: MissionReceiptStatus[] = ["pending", "ready", "succeeded", "failed"];
+	if (typeof input.kind !== "string" || !kinds.includes(input.kind as MissionReceiptKind)) throw new Error(`missionUpdate.receipts[${index}].kind is invalid`);
+	if (typeof input.status !== "string" || !statuses.includes(input.status as MissionReceiptStatus)) throw new Error(`missionUpdate.receipts[${index}].status is invalid`);
+	for (const field of ["title", "url"] as const) {
+		if (typeof input[field] !== "string" || !input[field].trim()) throw new Error(`missionUpdate.receipts[${index}].${field} must be a non-empty string`);
+	}
+	try {
+		new URL(input.url as string);
+	} catch {
+		throw new Error(`missionUpdate.receipts[${index}].url must be an absolute URL`);
+	}
+	if (input.description !== undefined && (typeof input.description !== "string" || !input.description.trim())) throw new Error(`missionUpdate.receipts[${index}].description must be a non-empty string`);
+	return {
+		kind: input.kind as MissionReceiptKind,
+		status: input.status as MissionReceiptStatus,
+		title: (input.title as string).trim(),
+		url: (input.url as string).trim(),
+		...(typeof input.description === "string" ? { description: input.description.trim() } : {}),
+	};
+}
+
+function validateMissionUpdate(value: unknown): MissionUpdateInput {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("missionUpdate must be an object");
+	const input = value as Record<string, unknown>;
+	for (const key of Object.keys(input)) {
+		if (!["title", "objective", "goal", "budget", "status", "summary", "labels", "artifacts", "receipts", "decisions"].includes(key)) throw new Error(`missionUpdate.${key} is unknown`);
+	}
+	const update: MissionUpdateInput = {};
+	for (const field of ["title", "objective", "summary"] as const) {
+		const candidate = input[field];
+		if (candidate === undefined) continue;
+		if (typeof candidate !== "string" || !candidate.trim()) throw new Error(`missionUpdate.${field} must be a non-empty string`);
+		update[field] = candidate.trim();
+	}
+	if (input.goal !== undefined) {
+		if (typeof input.goal === "boolean") update.goal = input.goal ? { status: "active" } : false;
+		else {
+			if (!input.goal || typeof input.goal !== "object" || Array.isArray(input.goal) || typeof (input.goal as { paused?: unknown }).paused !== "boolean" || Object.keys(input.goal).some((key) => key !== "paused")) {
+				throw new Error("missionUpdate.goal must be boolean or { paused: boolean }");
+			}
+			update.goal = { status: (input.goal as { paused: boolean }).paused ? "paused" : "active" };
+		}
+	}
+	if (input.budget !== undefined) {
+		if (!input.budget || typeof input.budget !== "object" || Array.isArray(input.budget) || !Number.isSafeInteger((input.budget as { tokens?: unknown }).tokens) || (input.budget as { tokens: number }).tokens < 1) {
+			throw new Error("missionUpdate.budget.tokens must be a positive integer");
+		}
+		update.budget = { tokens: (input.budget as { tokens: number }).tokens };
+	}
+	if (input.status !== undefined) update.status = validateStatus(input.status, "missionUpdate.status");
+	if (input.labels !== undefined) {
+		if (!Array.isArray(input.labels) || input.labels.some((label) => typeof label !== "string" || !label.trim())) throw new Error("missionUpdate.labels must contain only non-empty strings");
+		update.labels = input.labels as string[];
+	}
+	if (input.artifacts !== undefined) {
+		if (!Array.isArray(input.artifacts)) throw new Error("missionUpdate.artifacts must be an array");
+		update.addArtifacts = input.artifacts.map(validateArtifact);
+	}
+	if (input.receipts !== undefined) {
+		if (!Array.isArray(input.receipts)) throw new Error("missionUpdate.receipts must be an array");
+		update.addReceipts = input.receipts.map(validateReceipt);
+	}
+	if (input.decisions !== undefined) {
+		if (!Array.isArray(input.decisions)) throw new Error("missionUpdate.decisions must be an array");
+		update.addDecisions = input.decisions.map((value, index) => {
+			if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`missionUpdate.decisions[${index}] must be an object`);
+			const decision = value as Record<string, unknown>;
+			if (typeof decision.title !== "string" || !decision.title.trim()) throw new Error(`missionUpdate.decisions[${index}].title must be a non-empty string`);
+			if (decision.options !== undefined && (!Array.isArray(decision.options) || decision.options.some((option) => typeof option !== "string" || !option.trim()))) throw new Error(`missionUpdate.decisions[${index}].options must contain only non-empty strings`);
+			return {
+				title: decision.title.trim(),
+				...(typeof decision.prompt === "string" && decision.prompt.trim() ? { prompt: decision.prompt } : {}),
+				...(Array.isArray(decision.options) ? { options: decision.options as string[] } : {}),
+				...(typeof decision.recommendation === "string" && decision.recommendation.trim() ? { recommendation: decision.recommendation } : {}),
+			};
+		});
+	}
+	if (Object.keys(update).length === 0) throw new Error("missionUpdate must include at least one supported field");
+	return update;
+}
+
+function refreshLinkedRunStatus(location: MissionStoreLocation, record: MissionRecord): { record: MissionRecord; warnings: string[] } {
+	const warnings: string[] = [];
+	const updates = record.runs.flatMap((run) => {
+		if (!run.asyncDir) return [];
+		const statusPath = path.join(run.asyncDir, "status.json");
+		if (!fs.existsSync(statusPath)) return [];
+		let status: unknown;
+		try {
+			status = JSON.parse(fs.readFileSync(statusPath, "utf-8"));
+		} catch (error) {
+			warnings.push(`Failed to read linked run status '${statusPath}': ${error instanceof Error ? error.message : String(error)}`);
+			return [];
+		}
+		if (!status || typeof status !== "object" || Array.isArray(status)) {
+			warnings.push(`Linked run status '${statusPath}' must be an object`);
+			return [];
+		}
+		const state = (status as { state?: unknown }).state;
+		if (typeof state !== "string" || !state.trim()) {
+			warnings.push(`Linked run status '${statusPath}' is missing state`);
+			return [];
+		}
+		if (state === run.status) return [];
+		return [{
+			...run,
+			status: state,
+			...(!["queued", "running"].includes(state) && !run.completedAt ? { completedAt: new Date().toISOString() } : {}),
+		}];
+	});
+	if (updates.length === 0) return { record, warnings };
+	const merged = record.runs.map((run) => updates.find((update) => update.runId === run.runId && update.childIndex === run.childIndex) ?? run);
+	const states = merged.map((run) => run.status);
+	const status: MissionStatus = record.status === "completed" || record.status === "failed" || record.status === "cancelled"
+		? record.status
+		: record.goal && !states.some((state) => state === "queued" || state === "running" || state === "active")
+		? "active"
+		: states.some((state) => state === "queued" || state === "running" || state === "active")
+		? "active"
+		: states.some((state) => state === "paused")
+			? "waiting"
+			: states.some((state) => state === "failed")
+				? "failed"
+				: states.some((state) => state === "stopped" || state === "rejected" || state === "cancelled")
+					? "cancelled"
+					: states.length > 0 && states.every((state) => state === "complete" || state === "completed")
+						? "completed"
+						: record.status;
+	return { record: updateMission(location, record.id, { status, addRuns: updates }), warnings };
+}
+
+function formatMission(record: MissionRecord): string {
+	const lines = [
+		`Mission: ${record.id}`,
+		`Title: ${record.title}`,
+		`Status: ${record.status}`,
+		`Objective: ${record.objective}`,
+		`Updated: ${record.updatedAt}`,
+	];
+	if (record.goal && record.budget) lines.push(`Goal mode: ${record.goal.status}`, `Budget: ${record.usage?.tokens ?? 0}/${record.budget.tokens} tokens`);
+	if (record.summary) lines.push(`Summary: ${record.summary}`);
+	if (record.labels?.length) lines.push(`Labels: ${record.labels.join(", ")}`);
+	if (record.runs.length) {
+		lines.push("Runs:");
+		for (const run of record.runs) lines.push(`  ${run.runId} (${run.mode}${run.status ? `, ${run.status}` : ""})${run.asyncDir ? ` — ${run.asyncDir}` : ""}`);
+	}
+	if (record.workflowChildren.length) {
+		lines.push("Workflow children:");
+		for (const child of record.workflowChildren) {
+			const identity = child.runId ? `${child.key} (${child.runId})` : child.key;
+			const heartbeat = child.heartbeat ? `; heartbeat ${child.heartbeat.status ?? child.status}${child.heartbeat.phase ? `/${child.heartbeat.phase}` : ""} at ${child.heartbeat.updatedAt}` : "";
+			const recovery = child.sessionPath ? `; session ${child.sessionPath}` : child.artifactPaths.length ? `; artifacts ${child.artifactPaths.length}` : "";
+			lines.push(`  ${identity}: ${child.status}${child.agent ? ` — ${child.agent}` : ""}${child.phase ? ` [${child.phase}]` : ""}; updated ${child.updatedAt}${heartbeat}${recovery}`);
+		}
+	}
+	if (record.decisions.length) {
+		lines.push("Decisions:");
+		for (const decision of record.decisions) {
+			lines.push(`  ${decision.id}: ${decision.status} — ${decision.title}${decision.resolution ? `; resolution: ${decision.resolution}` : ""}`);
+		}
+	}
+	if (record.artifacts.length) {
+		lines.push("Artifacts:");
+		for (const artifact of record.artifacts) lines.push(`  ${artifact.kind}: ${artifact.path}`);
+	}
+	if (record.receipts.length) {
+		lines.push("Delivery receipts:");
+		for (const receipt of record.receipts) lines.push(`  ${receipt.kind} (${receipt.status}): ${receipt.title} — ${receipt.url}`);
+	}
+	return lines.join("\n");
+}
+
+export function handleMissionAction(
+	action: MissionAction,
+	params: MissionActionParams,
+	ctx: MissionActionContext,
+): AgentToolResult<Details> {
+	const location = resolveMissionStoreLocation({
+		projectRoot: ctx.cwd,
+		...(ctx.config ? { config: ctx.config } : {}),
+		...(ctx.agentDir ? { agentDir: ctx.agentDir } : {}),
+	});
+	if (action === "mission.create") {
+		const mission = validateMissionLaunch(params.mission);
+		const record = createMission(location, {
+			title: mission.title,
+			objective: mission.objective ?? mission.title,
+			...(mission.goal === true ? { goal: true as const } : {}),
+			...(mission.budget ? { budget: mission.budget } : {}),
+			status: params.missionStatus ? validateStatus(params.missionStatus, "missionStatus") : "planned",
+			...(mission.labels ? { labels: mission.labels } : {}),
+			...(ctx.currentSessionId ? { ownerSessionId: ctx.currentSessionId } : {}),
+		}, new Date(), ctx.config?.retainTerminal);
+		return textResult(`Created mission ${record.id}: ${record.title}`, { mode: "management", results: [], missionId: record.id, missionPath: pathFor(record.id), mission: record });
+	}
+	if (action === "mission.list") {
+		if (params.missionScope !== undefined && params.missionScope !== "project" && params.missionScope !== "global") {
+			throw new Error("missionScope must be \"project\" or \"global\"");
+		}
+		if (params.missionScope === "global") {
+			const listed = listGlobalMissions(location.globalIndexDir);
+			const lines = listed.entries.length === 0
+				? ["No indexed missions."]
+				: listed.entries.map((entry) => `${entry.missionId}  ${entry.status}${entry.stale ? " [stale]" : ""}  ${entry.title}  ${entry.projectRoot}`);
+			if (listed.warnings.length) lines.push("", ...listed.warnings.map((warning) => `Warning: ${warning}`));
+			return textResult(lines.join("\n"), { mode: "management", results: [], missions: { globalEntries: listed.entries, warnings: listed.warnings } });
+		}
+		const listed = listMissions(location);
+		const lines = listed.records.length === 0
+			? ["No project missions."]
+			: listed.records.map((record) => {
+				const open = record.decisions.filter((decision) => decision.status === "open").length;
+				const resolved = record.decisions.length - open;
+				return `${record.id}  ${record.status}  ${record.title}  ${record.updatedAt}${record.decisions.length ? `  decisions: ${open} open, ${resolved} resolved` : ""}`;
+			});
+		if (listed.warnings.length) lines.push("", ...listed.warnings.map((warning) => `Warning: ${warning}`));
+		return textResult(lines.join("\n"), { mode: "management", results: [], missions: { records: listed.records, warnings: listed.warnings } });
+	}
+	if (action === "mission.show") {
+		const refreshed = refreshLinkedRunStatus(location, readMission(location, requireMissionId(params)));
+		const lines = [formatMission(refreshed.record), `State: ${missionStatePath(location, refreshed.record.id)}`];
+		if (refreshed.warnings.length) lines.push("", ...refreshed.warnings.map((warning) => `Warning: ${warning}`));
+		return textResult(lines.join("\n"), {
+			mode: "management",
+			results: [],
+			missionId: refreshed.record.id,
+			missionPath: pathFor(refreshed.record.id),
+			mission: refreshed.record,
+			missions: { warnings: refreshed.warnings },
+		});
+	}
+	if (action === "mission.update") {
+		const record = updateMission(location, requireMissionId(params), validateMissionUpdate(params.missionUpdate));
+		return textResult(`Updated mission ${record.id}.\n\n${formatMission(record)}`, { mode: "management", results: [], missionId: record.id, missionPath: pathFor(record.id), mission: record });
+	}
+	if (action === "mission.resolve-decision") {
+		const missionId = requireMissionId(params);
+		const decisionId = validateMissionId(params.id, "id");
+		if (typeof params.summary !== "string" || !params.summary.trim()) throw new Error("mission.resolve-decision requires a non-empty summary");
+		const record = updateMission(location, missionId, { resolveDecision: { id: decisionId, resolution: params.summary.trim() } });
+		return textResult(`Resolved decision ${decisionId} for mission ${record.id}.\n\n${formatMission(record)}`, { mode: "management", results: [], missionId: record.id, missionPath: pathFor(record.id), mission: record });
+	}
+	if (action === "mission.attach-run") {
+		const missionId = requireMissionId(params);
+		const runId = params.runId ?? params.id;
+		if (typeof runId !== "string" || !runId.trim()) throw new Error("mission.attach-run requires runId or id");
+		const rawMode = params.runMode ?? "external";
+		if (!["single", "parallel", "chain", "workflow", "scheduled", "external"].includes(rawMode)) throw new Error("runMode is invalid");
+		const mode = rawMode as MissionRunMode;
+		if (params.dir !== undefined && !params.dir.trim()) throw new Error("dir must be a non-empty string");
+		if (params.runStatus !== undefined && !params.runStatus.trim()) throw new Error("runStatus must be a non-empty string");
+		const record = updateMission(location, missionId, {
+			status: "active",
+			addRuns: [{
+				runId: runId.trim(),
+				mode,
+				...(params.dir ? { asyncDir: params.dir } : {}),
+				...(params.agent ? { agent: params.agent } : {}),
+				...(params.runStatus ? { status: params.runStatus } : {}),
+				startedAt: new Date().toISOString(),
+			}],
+		});
+		return textResult(`Attached run ${runId} to mission ${record.id}.`, { mode: "management", results: [], missionId: record.id, missionPath: pathFor(record.id), mission: record });
+	}
+	const missionId = requireMissionId(params);
+	const status = params.missionStatus ?? "completed";
+	if (status !== "completed" && status !== "failed" && status !== "cancelled") throw new Error("mission.close missionStatus must be completed, failed, or cancelled");
+	if (params.summary !== undefined && !params.summary.trim()) throw new Error("summary must be a non-empty string");
+	const record = updateMission(location, missionId, {
+		status,
+		...(params.summary !== undefined ? { summary: params.summary.trim() } : {}),
+	});
+	return textResult(`Closed mission ${record.id} as ${record.status}.`, { mode: "management", results: [], missionId: record.id, missionPath: pathFor(record.id), mission: record });
+
+	function pathFor(missionId: string): string {
+		return missionRecordPath(location, missionId);
+	}
+}

package/node_modules/pi-subagents/src/missions/goal-driver.ts

@@ -0,0 +1,162 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { RetainedChild } from "../runs/background/retained-children.ts";
+import type { ControlEvent } from "../shared/types.ts";
+import { listMissions, readMission, updateMission } from "./store.ts";
+import type { MissionRecord, MissionRunLink, MissionStoreLocation } from "./types.ts";
+import { missionStatePath } from "./workflow-state.ts";
+
+const TERMINAL_MISSION_STATUSES = new Set(["completed", "failed", "cancelled"]);
+const ACTIVE_RUN_STATUSES = new Set(["queued", "running", "active"]);
+const MAX_ACTION_LENGTH = 180;
+
+export interface GoalContinuationNotice {
+	missionId: string;
+	message: string;
+	event: ControlEvent;
+}
+
+function bounded(value: string): string {
+	const normalized = value.replace(/\s+/g, " ").trim();
+	return normalized.length > MAX_ACTION_LENGTH ? `${normalized.slice(0, MAX_ACTION_LENGTH - 1)}…` : normalized;
+}
+
+function tokenUsage(value: unknown): number | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const total = (value as { total?: unknown }).total;
+	return Number.isSafeInteger(total) && (total as number) >= 0 ? total as number : undefined;
+}
+
+function readLinkedRun(run: MissionRunLink): MissionRunLink {
+	if (!run.asyncDir) return run;
+	const statusPath = path.join(run.asyncDir, "status.json");
+	if (!fs.existsSync(statusPath)) return run;
+	const status = JSON.parse(fs.readFileSync(statusPath, "utf-8")) as Record<string, unknown>;
+	if (typeof status.state !== "string" || !status.state.trim()) throw new Error(`Linked run status '${statusPath}' is missing state`);
+	const tokens = tokenUsage(status.totalTokens)
+		?? (Array.isArray(status.steps)
+			? status.steps.reduce((total, step) => {
+				if (!step || typeof step !== "object") return total;
+				return total + (tokenUsage((step as { tokens?: unknown }).tokens) ?? 0);
+			}, 0)
+			: undefined);
+	return {
+		...run,
+		status: status.state,
+		...(!ACTIVE_RUN_STATUSES.has(status.state) && !run.completedAt ? { completedAt: new Date().toISOString() } : {}),
+		...(tokens !== undefined ? { usage: { tokens } } : {}),
+	};
+}
+
+function refreshGoalMission(location: MissionStoreLocation, record: MissionRecord): MissionRecord {
+	const runs = record.runs.map(readLinkedRun);
+	const changed = runs.some((run, index) => JSON.stringify(run) !== JSON.stringify(record.runs[index]));
+	if (!changed) return record;
+	const active = runs.some((run) => run.status && ACTIVE_RUN_STATUSES.has(run.status));
+	return updateMission(location, record.id, {
+		status: active ? "active" : record.goal ? "active" : record.status,
+		addRuns: runs,
+	});
+}
+
+function readyActionFromValue(value: unknown, pathLabel = "state", depth = 0): string | undefined {
+	if (depth > 8 || !value || typeof value !== "object") return undefined;
+	if (Array.isArray(value)) {
+		for (let index = 0; index < value.length; index += 1) {
+			const found = readyActionFromValue(value[index], `${pathLabel}[${index}]`, depth + 1);
+			if (found) return found;
+		}
+		return undefined;
+	}
+	const input = value as Record<string, unknown>;
+	for (const key of ["nextReadyAction", "nextAction"] as const) {
+		if (typeof input[key] === "string" && input[key].trim()) return bounded(input[key]);
+	}
+	if (input.status === "ready") {
+		for (const key of ["action", "task", "title", "summary"] as const) {
+			if (typeof input[key] === "string" && input[key].trim()) return bounded(input[key]);
+		}
+		return `Continue ready mission state at ${pathLabel}`;
+	}
+	for (const [key, child] of Object.entries(input)) {
+		const found = readyActionFromValue(child, `${pathLabel}.${key}`, depth + 1);
+		if (found) return found;
+	}
+	return undefined;
+}
+
+function missionStateAction(location: MissionStoreLocation, record: MissionRecord): string | undefined {
+	const statePath = missionStatePath(location, record.id);
+	if (fs.existsSync(statePath)) {
+		const action = readyActionFromValue(JSON.parse(fs.readFileSync(statePath, "utf-8")));
+		if (action) return action;
+	}
+	const decision = record.decisions.find((item) => item.status === "open");
+	if (decision) return bounded(decision.recommendation ?? `Resolve decision: ${decision.title}`);
+	return undefined;
+}
+
+function retainedResumeTarget(record: MissionRecord, retainedChildren: RetainedChild[]): RetainedChild | undefined {
+	const latestRun = record.runs.at(-1);
+	if (!latestRun) return undefined;
+	return retainedChildren.find((child) => child.runId === latestRun.runId || child.parentRunId === latestRun.runId);
+}
+
+function nextReadyAction(location: MissionStoreLocation, record: MissionRecord, retainedChildren: RetainedChild[]): string {
+	const stateAction = missionStateAction(location, record);
+	const latestRun = record.runs.at(-1);
+	const action = stateAction
+		?? (latestRun?.status === "failed" || latestRun?.status === "paused"
+			? `Inspect linked run ${latestRun.runId} and continue the mission`
+			: `Continue objective: ${record.objective}`);
+	const retained = retainedResumeTarget(record, retainedChildren);
+	return retained
+		? `Resume retained child ${retained.runId} (${retained.agent}) for: ${bounded(action)}`
+		: bounded(action);
+}
+
+export function collectGoalContinuationNotices(input: {
+	location: MissionStoreLocation;
+	ownerSessionId: string;
+	retainedChildren: RetainedChild[];
+	turnId: number;
+	now?: number;
+}): GoalContinuationNotice[] {
+	const notices: GoalContinuationNotice[] = [];
+	const seen = new Set<string>();
+	for (const listed of listMissions(input.location).records) {
+		if (listed.ownerSessionId !== input.ownerSessionId || !listed.goal || TERMINAL_MISSION_STATUSES.has(listed.status)) continue;
+		let record = refreshGoalMission(input.location, readMission(input.location, listed.id));
+		if (!record.goal || record.goal.status !== "active" || !record.budget) continue;
+		if ((record.usage?.tokens ?? 0) >= record.budget.tokens) {
+			record = updateMission(input.location, record.id, { usage: record.usage ?? { tokens: 0 } });
+			if (record.goal?.status === "budget-exhausted") continue;
+		}
+		if (record.runs.some((run) => run.status && ACTIVE_RUN_STATUSES.has(run.status))) continue;
+		if (seen.has(record.id) || !record.budget) continue;
+		seen.add(record.id);
+		const budget = record.budget.tokens;
+		const used = record.usage?.tokens ?? 0;
+		const remaining = Math.max(0, budget - used);
+		const message = [
+			`Goal mission needs attention: ${bounded(record.title)}`,
+			`Mission: ${record.id}`,
+			`Remaining budget: ${remaining} tokens (${used}/${budget} used)`,
+			`Next ready action: ${nextReadyAction(input.location, record, input.retainedChildren)}`,
+		].join("\n");
+		notices.push({
+			missionId: record.id,
+			message,
+			event: {
+				type: "needs_attention",
+				to: "needs_attention",
+				ts: input.now ?? Date.now(),
+				runId: `goal-${record.id}-turn-${input.turnId}`,
+				agent: "goal mission",
+				message,
+				reason: "idle",
+			},
+		});
+	}
+	return notices;
+}