pi-subagents 0.42.0 → 0.43.0

package/src/missions/actions.ts

@@ -14,8 +14,10 @@ import {
 	type MissionStatus,
 	type MissionStoreConfig,
 	type MissionStoreLocation,
+	type MissionTokenBudget,
 	type MissionUpdateInput,
 } from "./types.ts";
+import { missionStatePath } from "./workflow-state.ts";
 import {
 	createMission,
 	listGlobalMissions,
@@ -40,13 +42,17 @@ export type MissionAction = typeof MISSION_ACTIONS[number];
 
 export interface MissionLaunchInput {
 	title: string;
-	goal?: string;
+	objective?: string;
+	goal?: true;
+	budget?: MissionTokenBudget;
 	labels?: string[];
 }
 
 export interface MissionUpdateToolInput {
 	title?: string;
-	goal?: string;
+	objective?: string;
+	goal?: boolean | { paused: boolean };
+	budget?: MissionTokenBudget;
 	status?: MissionStatus;
 	summary?: string;
 	labels?: string[];
@@ -101,18 +107,26 @@ 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 !== "goal" && key !== "labels") throw new Error(`mission.${key} is unknown`);
+		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.goal !== undefined && (typeof input.goal !== "string" || !input.goal.trim())) throw new Error("mission.goal 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(),
-		...(input.goal !== undefined ? { goal: input.goal.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()) } : {}),
 	};
 }
@@ -163,15 +177,30 @@ 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", "goal", "status", "summary", "labels", "artifacts", "receipts", "decisions"].includes(key)) throw new Error(`missionUpdate.${key} is unknown`);
+		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", "goal", "summary"] as const) {
+	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");
@@ -236,7 +265,11 @@ function refreshLinkedRunStatus(location: MissionStoreLocation, record: MissionR
 	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 = states.some((state) => state === "queued" || state === "running" || state === "active")
+	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"
@@ -255,9 +288,10 @@ function formatMission(record: MissionRecord): string {
 		`Mission: ${record.id}`,
 		`Title: ${record.title}`,
 		`Status: ${record.status}`,
-		`Goal: ${record.goal}`,
+		`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) {
@@ -293,7 +327,9 @@ export function handleMissionAction(
 		const mission = validateMissionLaunch(params.mission);
 		const record = createMission(location, {
 			title: mission.title,
-			goal: mission.goal ?? 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 } : {}),
@@ -321,7 +357,7 @@ export function handleMissionAction(
 	}
 	if (action === "mission.show") {
 		const refreshed = refreshLinkedRunStatus(location, readMission(location, requireMissionId(params)));
-		const lines = [formatMission(refreshed.record)];
+		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",

package/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;
+}

package/src/missions/lifecycle.ts

@@ -34,14 +34,21 @@ interface PersistedMissionBinding {
 	retainTerminal?: number;
 }
 
-function workflowGoal(params: MissionLaunchParams): string | undefined {
-	return params.task?.trim()
+function workflowObjective(params: MissionLaunchParams): string | undefined {
+	const objective = params.task?.trim()
 		|| params.tasks?.find((task) => task.task?.trim())?.task?.trim()
 		|| params.chain?.find((step) => step.task?.trim())?.task?.trim();
+	if (objective) return objective;
+	for (const step of params.chain ?? []) {
+		const parallel = Array.isArray(step.parallel) ? step.parallel : step.parallel ? [step.parallel] : [];
+		const task = parallel.find((child) => child.task?.trim())?.task?.trim();
+		if (task) return task;
+	}
+	return undefined;
 }
 
-function conciseTitle(goal: string): string {
-	const firstLine = goal.split(/\r?\n/, 1)[0]?.trim() || goal.trim();
+function conciseTitle(objective: string): string {
+	const firstLine = objective.split(/\r?\n/, 1)[0]?.trim() || objective.trim();
 	return firstLine.length > 100 ? `${firstLine.slice(0, 97)}...` : firstLine;
 }
 
@@ -51,24 +58,27 @@ export function prepareMissionLaunch(input: {
 	config?: MissionStoreConfig;
 	ownerSessionId?: string;
 }): MissionLaunchBinding | undefined {
-	if (input.params.missionId && input.params.mission !== undefined) throw new Error("Use missionId or mission, not both");
+	const hasMissionId = input.params.missionId !== undefined;
+	if (hasMissionId && input.params.mission !== undefined) throw new Error("Use missionId or mission, not both");
 	if (input.params.mission === false) return undefined;
-	const goal = workflowGoal(input.params);
+	const objective = workflowObjective(input.params);
 	const missionsEnabled = input.config?.enabled !== false;
-	const shouldCreate = input.params.mission !== undefined || (missionsEnabled && goal !== undefined);
-	if (!input.params.missionId && !shouldCreate) return undefined;
+	const shouldCreate = input.params.mission !== undefined || (missionsEnabled && objective !== undefined);
+	if (!hasMissionId && !shouldCreate) return undefined;
 	const location = resolveMissionStoreLocation({ projectRoot: input.projectRoot, ...(input.config ? { config: input.config } : {}) });
-	if (input.params.missionId) {
+	if (hasMissionId) {
 		const missionId = validateMissionId(input.params.missionId);
 		readMission(location, missionId);
 		updateMission(location, missionId, { status: "active" });
 		return { missionId, location, autoCreated: false, announceInContent: true };
 	}
 	const mission = input.params.mission !== undefined ? validateMissionLaunch(input.params.mission) : undefined;
-	const title = mission?.title || conciseTitle(goal!);
+	const title = mission?.title || conciseTitle(objective!);
 	const record = createMission(location, {
 		title,
-		goal: mission?.goal || goal || title,
+		objective: mission?.objective || objective || title,
+		...(mission?.goal === true ? { goal: true as const } : {}),
+		...(mission?.budget ? { budget: mission.budget } : {}),
 		status: "active",
 		...(mission?.labels ? { labels: mission.labels } : {}),
 		...(input.ownerSessionId ? { ownerSessionId: input.ownerSessionId } : {}),
@@ -92,7 +102,9 @@ function runStatusForResult(result: AgentToolResult<Details>): string {
 }
 
 function missionStatusForRun(record: MissionRecord, runId: string, runStatus: string): MissionStatus {
+	if (record.status === "completed" || record.status === "failed" || record.status === "cancelled") return record.status;
 	if (runStatus === "active" || runStatus === "queued" || runStatus === "running") return "active";
+	if (record.goal) return "active";
 	if (runStatus === "paused") return "waiting";
 	const otherActive = record.runs.some((run) => run.runId !== runId && (run.status === "active" || run.status === "queued" || run.status === "running"));
 	if (otherActive) return "active";
@@ -101,6 +113,17 @@ function missionStatusForRun(record: MissionRecord, runId: string, runStatus: st
 	return "failed";
 }
 
+function usageForResult(result: AgentToolResult<Details>): { tokens: number } | undefined {
+	const tokens = result.details.results.reduce((total, child) => total + child.usage.input + child.usage.output, 0);
+	return tokens > 0 ? { tokens } : undefined;
+}
+
+function usageFromUnknown(value: unknown): { tokens: 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 ? { tokens: total as number } : undefined;
+}
+
 function artifactsForResult(result: AgentToolResult<Details>): MissionArtifact[] {
 	const artifacts: MissionArtifact[] = [];
 	if (result.details.asyncDir) {
@@ -168,6 +191,7 @@ export function attachMissionToLaunchResult(input: {
 	const runStatus = runStatusForResult(input.result);
 	const current = readMission(input.binding.location, input.binding.missionId);
 	const startedAt = new Date().toISOString();
+	const usage = usageForResult(input.result);
 	const run: MissionRunLink = {
 		runId,
 		mode: missionRunModeForResult(input.result.details.mode),
@@ -176,6 +200,7 @@ export function attachMissionToLaunchResult(input: {
 		...(input.result.details.asyncDir ? { asyncDir: input.result.details.asyncDir } : {}),
 		...(input.result.details.results.length === 1 && input.result.details.results[0]?.agent ? { agent: input.result.details.results[0].agent } : {}),
 		...(runStatus !== "active" ? { completedAt: startedAt } : {}),
+		...(usage ? { usage } : {}),
 	};
 	let mission = updateMission(input.binding.location, input.binding.missionId, {
 		status: missionStatusForRun(current, runId, runStatus),
@@ -305,9 +330,16 @@ export function syncMissionFromAsyncCompletion(value: unknown): MissionRecord |
 		}
 	}
 	const summary = typeof event.summary === "string" && event.summary.trim() ? event.summary.slice(0, 2000) : undefined;
+	const usage = usageFromUnknown(event.totalTokens)
+		?? (Array.isArray(event.results)
+			? { tokens: event.results.reduce((total, result) => {
+				if (!result || typeof result !== "object") return total;
+				return total + (usageFromUnknown((result as { tokens?: unknown }).tokens)?.tokens ?? 0);
+			}, 0) }
+			: undefined);
 	return updateMission(binding.location, binding.missionId, {
 		status: missionStatusForRun(current, runId, runStatus),
-		addRuns: [{ runId, mode: typeof event.mode === "string" && ["single", "parallel", "chain"].includes(event.mode) ? event.mode as SubagentRunMode : "external", asyncDir: event.asyncDir, status: runStatus, completedAt }],
+		addRuns: [{ runId, mode: typeof event.mode === "string" && ["single", "parallel", "chain"].includes(event.mode) ? event.mode as SubagentRunMode : "external", asyncDir: event.asyncDir, status: runStatus, completedAt, ...(usage && usage.tokens > 0 ? { usage } : {}) }],
 		addArtifacts: artifacts,
 		...(summary ? { summary } : {}),
 	});

package/src/missions/store.ts

@@ -12,6 +12,7 @@ import {
 	type MissionArtifactKind,
 	type MissionCreateInput,
 	type MissionDecision,
+	type MissionGoal,
 	type MissionIndexEntry,
 	type MissionListResult,
 	type MissionReceipt,
@@ -23,6 +24,8 @@ import {
 	type MissionStatus,
 	type MissionStoreConfig,
 	type MissionStoreLocation,
+	type MissionTokenBudget,
+	type MissionTokenUsage,
 	type MissionUpdateInput,
 } from "./types.ts";
 
@@ -63,6 +66,37 @@ function missionStatus(value: unknown, label: string): MissionStatus {
 	return value as MissionStatus;
 }
 
+function positiveTokenCount(value: unknown, label: string): number {
+	if (!Number.isSafeInteger(value) || (value as number) < 1) throw new Error(`${label} must be a positive integer`);
+	return value as number;
+}
+
+function nonNegativeTokenCount(value: unknown, label: string): number {
+	if (!Number.isSafeInteger(value) || (value as number) < 0) throw new Error(`${label} must be a non-negative integer`);
+	return value as number;
+}
+
+function parseStoredGoal(value: unknown, label: string): { goal?: MissionGoal; legacyObjective?: string } {
+	if (typeof value === "string") return { legacyObjective: requiredString(value, label).trim() };
+	return { goal: parseGoal(value, label) };
+}
+
+function parseGoal(value: unknown, label: string): MissionGoal {
+	const input = asObject(value, label);
+	if (input.status !== "active" && input.status !== "paused" && input.status !== "budget-exhausted") throw new Error(`${label}.status is invalid`);
+	return { status: input.status };
+}
+
+function parseBudget(value: unknown, label: string): MissionTokenBudget {
+	const input = asObject(value, label);
+	return { tokens: positiveTokenCount(input.tokens, `${label}.tokens`) };
+}
+
+function parseUsage(value: unknown, label: string): MissionTokenUsage {
+	const input = asObject(value, label);
+	return { tokens: nonNegativeTokenCount(input.tokens, `${label}.tokens`) };
+}
+
 function stringArray(value: unknown, label: string): string[] {
 	if (!Array.isArray(value)) throw new Error(`${label} must be an array of non-empty strings`);
 	const result = value.map((item, index) => requiredString(item, `${label}[${index}]`).trim());
@@ -94,6 +128,7 @@ function parseRunLink(value: unknown, label: string): MissionRunLink {
 		...(optionalString(input.status, `${label}.status`) ? { status: input.status as string } : {}),
 		...(input.startedAt !== undefined ? { startedAt: timestamp(input.startedAt, `${label}.startedAt`) } : {}),
 		...(input.completedAt !== undefined ? { completedAt: timestamp(input.completedAt, `${label}.completedAt`) } : {}),
+		...(input.usage !== undefined ? { usage: parseUsage(input.usage, `${label}.usage`) } : {}),
 	};
 }
 
@@ -158,11 +193,20 @@ export function parseMissionRecord(value: unknown, source = "mission record"): M
 	const decisions = input.decisions as unknown[];
 	const artifacts = input.artifacts as unknown[];
 	const receipts = (input.receipts ?? []) as unknown[];
+	const parsedGoal = input.goal !== undefined ? parseStoredGoal(input.goal, `${source}.goal`) : {};
+	const budget = input.budget !== undefined ? parseBudget(input.budget, `${source}.budget`) : undefined;
+	const usage = input.usage !== undefined ? parseUsage(input.usage, `${source}.usage`) : undefined;
+	const objective = optionalString(input.objective, `${source}.objective`)?.trim() ?? parsedGoal.legacyObjective;
+	if (!objective) throw new Error(`${source}.objective must be a non-empty string`);
+	if (parsedGoal.goal && !budget) throw new Error(`${source}.budget is required for a goal mission`);
 	return {
 		schemaVersion: 1,
 		id: validateMissionId(input.id, `${source}.id`),
 		title: requiredString(input.title, `${source}.title`),
-		goal: requiredString(input.goal, `${source}.goal`),
+		objective,
+		...(parsedGoal.goal ? { goal: parsedGoal.goal } : {}),
+		...(budget ? { budget } : {}),
+		...(usage ? { usage } : {}),
 		status: missionStatus(input.status, `${source}.status`),
 		createdAt: timestamp(input.createdAt, `${source}.createdAt`),
 		updatedAt: timestamp(input.updatedAt, `${source}.updatedAt`),
@@ -279,6 +323,7 @@ function pruneTerminalMissions(location: MissionStoreLocation, maxTerminal: numb
 	for (const record of terminal.slice(maxTerminal)) {
 		try {
 			fs.rmSync(missionRecordPath(location, record.id), { force: true });
+			fs.rmSync(path.join(location.missionDir, record.id), { recursive: true, force: true });
 			if (location.writeGlobalIndex) fs.rmSync(indexPath(location, record), { force: true });
 		} catch {
 			// Retention is best-effort and must never block a launch.
@@ -292,7 +337,10 @@ export function createMission(location: MissionStoreLocation, input: MissionCrea
 		schemaVersion: 1,
 		id: randomUUID(),
 		title: requiredString(input.title, "mission.title").trim(),
-		goal: requiredString(input.goal, "mission.goal").trim(),
+		objective: requiredString(input.objective, "mission.objective").trim(),
+		...(input.goal === true ? { goal: { status: "active" as const } } : {}),
+		...(input.budget ? { budget: parseBudget(input.budget, "mission.budget") } : {}),
+		...(input.goal === true ? { usage: { tokens: 0 } } : {}),
 		status: input.status ?? "planned",
 		createdAt,
 		updatedAt: createdAt,
@@ -304,6 +352,7 @@ export function createMission(location: MissionStoreLocation, input: MissionCrea
 		...(input.ownerSessionId ? { ownerSessionId: requiredString(input.ownerSessionId, "mission.ownerSessionId") } : {}),
 		...(input.labels ? { labels: stringArray(input.labels, "mission.labels") } : {}),
 	};
+	if (input.goal === true && !input.budget) throw new Error("mission.budget is required when mission.goal is true");
 	const created = writeMission(location, record);
 	pruneTerminalMissions(location, retainTerminal);
 	return created;
@@ -390,6 +439,19 @@ export function updateMission(location: MissionStoreLocation, missionId: string,
 			...(decision.recommendation ? { recommendation: requiredString(decision.recommendation, "mission.update.addDecisions[].recommendation") } : {}),
 		})),
 	];
+	const budget = update.budget !== undefined ? parseBudget(update.budget, "mission.update.budget") : current.budget;
+	const usage = update.usage !== undefined
+		? parseUsage(update.usage, "mission.update.usage")
+		: { tokens: runs.reduce((total, run) => total + (run.usage?.tokens ?? 0), 0) };
+	let goal = update.goal === false ? undefined : update.goal !== undefined ? parseGoal(update.goal, "mission.update.goal") : current.goal;
+	if (goal && !budget) throw new Error("mission.update.budget is required when enabling a goal mission");
+	if (goal && budget) {
+		goal = usage.tokens >= budget.tokens
+			? { status: "budget-exhausted" }
+			: goal.status === "budget-exhausted"
+				? { status: "active" }
+				: goal;
+	}
 	const next: MissionRecord = {
 		...current,
 		updatedAt: createdAt,
@@ -398,12 +460,15 @@ export function updateMission(location: MissionStoreLocation, missionId: string,
 		receipts,
 		decisions,
 		...(update.title !== undefined ? { title: requiredString(update.title, "mission.update.title").trim() } : {}),
-		...(update.goal !== undefined ? { goal: requiredString(update.goal, "mission.update.goal").trim() } : {}),
+		...(update.objective !== undefined ? { objective: requiredString(update.objective, "mission.update.objective").trim() } : {}),
+		...(budget ? { budget } : {}),
+		...(goal ? { goal, usage } : {}),
 		...(update.status !== undefined ? { status: missionStatus(update.status, "mission.update.status") } : {}),
 		...(update.summary !== undefined ? { summary: requiredString(update.summary, "mission.update.summary") } : {}),
 		...(update.labels !== undefined ? { labels: stringArray(update.labels, "mission.update.labels") } : {}),
 		...(update.acceptance !== undefined ? { acceptance: update.acceptance } : {}),
 	};
+	if (!goal) delete next.goal;
 	const updated = writeMission(location, next);
 	if (TERMINAL_MISSION_STATUSES.has(updated.status)) pruneTerminalMissions(location, retainTerminal);
 	return updated;

package/src/missions/types.ts

@@ -13,6 +13,19 @@ export type MissionRunMode = "single" | "parallel" | "chain" | "workflow" | "sch
 export type MissionArtifactKind = "status" | "output" | "patch" | "manifest" | "review" | "note" | "other";
 export type MissionReceiptKind = "pull_request" | "ci" | "deployment" | "release";
 export type MissionReceiptStatus = "pending" | "ready" | "succeeded" | "failed";
+export type MissionGoalStatus = "active" | "paused" | "budget-exhausted";
+
+export interface MissionGoal {
+	status: MissionGoalStatus;
+}
+
+export interface MissionTokenBudget {
+	tokens: number;
+}
+
+export interface MissionTokenUsage {
+	tokens: number;
+}
 
 export interface MissionRunLink {
 	runId: string;
@@ -23,6 +36,7 @@ export interface MissionRunLink {
 	status?: string;
 	startedAt?: string;
 	completedAt?: string;
+	usage?: MissionTokenUsage;
 }
 
 export interface MissionDecision {
@@ -56,7 +70,10 @@ export interface MissionRecord {
 	schemaVersion: 1;
 	id: string;
 	title: string;
-	goal: string;
+	objective: string;
+	goal?: MissionGoal;
+	budget?: MissionTokenBudget;
+	usage?: MissionTokenUsage;
 	status: MissionStatus;
 	createdAt: string;
 	updatedAt: string;
@@ -115,7 +132,9 @@ export interface GlobalMissionListResult {
 
 export interface MissionCreateInput {
 	title: string;
-	goal: string;
+	objective: string;
+	goal?: boolean;
+	budget?: MissionTokenBudget;
 	status?: MissionStatus;
 	labels?: string[];
 	ownerSessionId?: string;
@@ -123,7 +142,10 @@ export interface MissionCreateInput {
 
 export interface MissionUpdateInput {
 	title?: string;
-	goal?: string;
+	objective?: string;
+	goal?: MissionGoal | false;
+	budget?: MissionTokenBudget;
+	usage?: MissionTokenUsage;
 	status?: MissionStatus;
 	summary?: string;
 	labels?: string[];