pi-goal-x 0.31.3 → 0.31.4

package/README.md

@@ -115,6 +115,7 @@ Open `/goal-settings` to change these options. You can save defaults for all pro
 
 | Setting | What it controls |
 | --- | --- |
+| Autonomous run allowance (`maxAutonomousRuns`) | Positive whole number of extension-started runs per creation or `/goal-resume` period. **Unset disables automatic continuation.** Settings edits change the limit without resetting usage. |
 | Task tracking (`disableTasks`) | Turn task lists on or off. Set to `true` to disable them. |
 | Subtask depth (`subtaskDepth`) | Limit how many levels of subtasks the agent can create. |
 | Completion requirements (`disableContracts`) | Turn explicit goal and task completion requirements on or off. Set to `true` to disable them. |
@@ -122,6 +123,43 @@ Open `/goal-settings` to change these options. You can save defaults for all pro
 | Auditor provider, model, and thinking level | Choose which model reviews completed work and its reasoning effort. |
 
 
+### Explicit execution and waiting
+
+Goals no longer restart merely because they remain unfinished or a tool was used. Before yielding, the agent declares runnable work or an external wait using `update_goal`, or reports complete, paused, or blocked. A missing decision permits one repair prompt within the remaining allowance, then pauses.
+
+Set an appropriate allowance in `/goal-settings`, or in `.pi/pi-goal-x-settings.json`:
+
+```json
+{ "maxAutonomousRuns": 20 }
+```
+
+Agents may edit this setting. Changing it does not replenish consumed runs; explicit `/goal-resume` renews the period and continues now, including from a waiting goal. It requires a configured allowance. Tool calls within a run are not separate runs. Existing token budgets still apply.
+
+```js
+update_goal({ continuation: { kind: "ready", next_action: "Verify the build artifacts" } })
+update_goal({ continuation: {
+  kind: "wait", reason: "Await the remote build",
+  deadline: "2026-09-15T12:00:00Z",
+  polling: { interval_seconds: 60, max_checks: 3 }
+} })
+```
+
+Use a future deadline appropriate to the task. Omit `polling` for an event-only wait. Successful declarations terminate the execution segment. On a scheduled check, reuse the returned `wait_id` and original deadline, omitting `polling`; remaining checks cannot be reset. A ready decision ends the wait. Time spent waiting is not active execution time.
+
+The dashboard, `/goal-status`, and `get_goal` show scheduling state, timing, checks, and allowance consumption. Expired waits and exhausted checks or allowance pause without another model call. Waits survive reopening the same session, without replaying missed checks; Pi must remain open for timers to execute. Another session requires explicit resume to take ownership. An ambiguous interrupted dispatch requires resume instead of automatic replay.
+
+### Background producer integration
+
+Budget-controlled producers emit a scheduler signal instead of starting their own model turn:
+
+```js
+pi.events.emit("pi-goal:wake", { goalId, waitToken });
+```
+
+`waitToken` is returned in the wait declaration's tool-result details. Register it before the producer completes, or retain the completion until registration (for example, observe the `update_goal` tool result in the host adapter). The token changes after consumption and re-declaration. A matching signal received before agent settlement is retained; duplicate, stale and wrong-goal tokens are ignored. A signal and timer can claim only one wake.
+
+Existing producers that directly send `triggerTurn`/`followUp` messages still run as ordinary host work and supersede old pending decisions. Those independently started turns are **outside this extension's allowance**; use `pi-goal:wake` to put them through its spending gate. The allowance also does not limit Pi's own within-run tool loop or native retries. It bounds the goal extension's kickoff, continuation, check, signal, repair and recovery dispatches.
+
 ## License
 
 MIT

package/extensions/goal-commands.ts

@@ -278,6 +278,7 @@ export function registerGoalCommands(core: GoalCore): void {
 		const health = /^\s*health\b/i.test(rawArgs);
 		const ledger = readGoalLedger(ctx);
 		const text = buildGoalStatusText({
+			maxAutonomousRuns: loadGoalSettings(ctx.cwd).maxAutonomousRuns,
 			goal: view,
 			focused: view !== null && core.focusedGoalId === view.id,
 			otherOpenGoals: otherCount,
@@ -332,33 +333,10 @@ export function registerGoalCommands(core: GoalCore): void {
 		if (!core.state.goal && otherOpenGoalCount(core.goalsById, null) > 0) {
 			const selected = await chooseOpenGoal(ctx, "Resume or focus open goal");
 			if (!selected) return;
-			if (selected.status === "active") {
-				core.armFocusedContinuation(ctx);
-				ctx.ui.notify(`Goal focused: ${oneLineSummary(selected)}`, "info");
-				return;
-			}
 		}
-		const resumeGate = validateResumeGoal(core.state.goal);
-		if (!resumeGate.ok) {
-			const level = resumeGate.message.includes("already running") ? "info" : "warning";
-			ctx.ui.notify(resumeGate.message, level);
-			return;
-		}
-		if (!core.state.goal) throw new Error("Goal disappeared during resume validation.");
-		core.setGoal(
-			{
-				...mergeGoalPromptFromDisk(ctx, core.state.goal),
-				status: "active",
-				autoContinue: true,
-				stopReason: undefined,
-				pauseReason: undefined,
-				pauseSuggestedAction: undefined,
-			},
-			ctx,
-		);
-		core.beginAccounting();
-		ctx.ui.notify("Goal resumed.", "info");
-		core.queueContinuation(ctx, true);
+		if (!core.state.goal) { ctx.ui.notify("No goal is focused.", "warning"); return; }
+		if (!core.scheduler.resume(ctx)) return;
+		ctx.ui.notify("Goal resumed; autonomous allowance renewed.", "info");
 		// Append ledger event for resumption
 		try {
 			core.goalService.appendEvents(ctx, [{
@@ -392,6 +370,7 @@ export function registerGoalCommands(core: GoalCore): void {
 		{ key: "autoSelectSingleGoal", label: "autoSelectSingleGoal", section: "Goal behavior", kind: "boolean" },
 		{ key: "hideUnfocusedBanner", label: "hideUnfocusedBanner", section: "Goal behavior", kind: "boolean" },
 		{ key: "disableContracts", label: "disableContracts", section: "Goal behavior", kind: "boolean" },
+		{ key: "maxAutonomousRuns", label: "autonomous run allowance", section: "Goal behavior", kind: "positiveInteger" },
 		{ key: "stallTimeoutMinutes", label: "stall timeout (minutes)", section: "Goal behavior", kind: "positiveInteger" },
 		{ key: "objectiveMaxChars", label: "max objective length (0 = none)", section: "Goal behavior", kind: "positiveInteger" },
 		{ key: "disableTasks", label: "disableTasks", section: "Task tracking", kind: "boolean" },
@@ -414,6 +393,7 @@ export function registerGoalCommands(core: GoalCore): void {
 			return config[key] === true ? "true" : "false";
 		}
 		if (key === "subtaskDepth") return config.subtaskDepth !== undefined ? String(config.subtaskDepth) : "1";
+		if (key === "maxAutonomousRuns") return config.maxAutonomousRuns === 0 ? "0 (disabled)" : String(config.maxAutonomousRuns ?? "unlimited (default)");
 		if (key === "stallTimeoutMinutes") return config.stallTimeoutMinutes !== undefined ? String(config.stallTimeoutMinutes) : "0";
 		if (key === "objectiveMaxChars") return config.objectiveMaxChars !== undefined ? String(config.objectiveMaxChars) : "0";
 		if (key === "keybindings") return config.keybindings ? `${config.keybindings.dashboard.toggleExpand}, ${config.keybindings.dashboard.scrollUp}, ${config.keybindings.dashboard.scrollDown}` : "(default)";
@@ -564,7 +544,7 @@ export function registerGoalCommands(core: GoalCore): void {
 				}
 
 				if (row.kind === "positiveInteger") {
-					const min = row.path ? 1 : ((row.key === "stallTimeoutMinutes" || row.key === "objectiveMaxChars") ? 0 : 1);
+					const min = row.path ? 1 : ((row.key === "stallTimeoutMinutes" || row.key === "objectiveMaxChars" || row.key === "maxAutonomousRuns") ? 0 : 1);
 					const actions = [`Set ${scope} override...`];
 					if (hasLocalOverride) actions.push(inheritLabel);
 					actions.push("Cancel");
@@ -825,7 +805,7 @@ export function registerGoalCommands(core: GoalCore): void {
 		},
 	});
 	pi.registerCommand("goal-resume", {
-		description: "Resume a paused or blocked goal.",
+		description: "Continue now and renew the configured autonomous-run allowance.",
 		handler: async (_rawArgs, ctx) => {
 			await handleGoalResume(ctx);
 		},

package/extensions/goal-core-tools.ts

@@ -1,3 +1,4 @@
+import { schedulerSummary, type GoalContinuation } from "./goal-scheduler-state.ts";
 import { goalDetailPage, type GoalDetailSection } from "./goal-detail.ts";
 import { taskIndex } from "./goal-task-index.ts";
 import { StringEnum, Type } from "@earendil-works/pi-ai";
@@ -86,7 +87,7 @@ pi.registerTool(defineTool({
   }
   if (params.cursor || params.task_id) return {content: [{type: "text", text: "Use section=objective, tasks, or history for detail retrieval; task_id requires tasks."}], details: goalDetails(view)};
 		if (verbose && !params.section) {
-			const lines: string[] = [`Goal ${view.id}: ${statusLabel(view)}, ${view.sisyphus ? "sisyphus" : "regular"}`];
+			const lines: string[] = [`Goal ${view.id}: ${statusLabel(view)}, ${view.sisyphus ? "sisyphus" : "regular"}`, schedulerSummary(view.scheduler, loadGoalSettings(ctx.cwd).maxAutonomousRuns)];
 			lines.push(`Objective: ${view.objective}`, "");
 			lines.push(`Status: ${statusLabel(view)}`);
 			lines.push(`Mode: ${view.sisyphus ? "sisyphus" : "regular"}`);
@@ -129,7 +130,7 @@ pi.registerTool(defineTool({
 		}
 
 		// Compact state read; full requirements remain available through detail pages.
-		const lines: string[] = [`Goal ${view.id}: ${statusLabel(view)}, ${view.sisyphus ? "sisyphus" : "regular"}`];
+		const lines: string[] = [`Goal ${view.id}: ${statusLabel(view)}, ${view.sisyphus ? "sisyphus" : "regular"}`, schedulerSummary(view.scheduler, loadGoalSettings(ctx.cwd).maxAutonomousRuns)];
 		lines.push(`Objective: ${truncateText(view.objective, 180)}${view.objective.length > 180 ? " (full: get_goal section=objective)" : ""}`);
 		if (view.taskList) {
 			const { findCurrentTask, firstPendingTask } = conciseTaskPointers(view);
@@ -508,11 +509,15 @@ async function runGoalAgentPauseFlow(ctx: ExtensionContext, reason: string | und
 pi.registerTool(defineTool({
 	name: "update_goal",
 	label: "Update Goal",
-	description: "Report complete (independently audited), blocked (three consecutive identical blockers), or paused (immediate). reason is required for blocked/paused; completion_summary is an untrusted claim.",
-	promptSnippet: "Complete, block, or pause the focused goal.",
+	description: "End execution with status OR continuation. Wait: future ISO deadline; reuse wait_id/deadline without polling on recheck. Completion is audited.",
+	promptSnippet: "Declare the next execution disposition or complete, block, or pause.",
 	promptGuidelines: [],
 	parameters: Type.Object({
-		status: StringEnum(["complete", "blocked", "paused"] as const, { description: "Run outcome." }),
+		status: Type.Optional(StringEnum(["complete", "blocked", "paused"] as const, { description: "Exclusive with continuation." })),
+		continuation: Type.Optional(Type.Union([
+			Type.Object({ kind: Type.Literal("ready"), next_action: Type.String({ minLength: 1, maxLength: 2000 }) }, { additionalProperties: false }),
+			Type.Object({ kind: Type.Literal("wait"), reason: Type.String({ minLength: 1, maxLength: 2000 }), deadline: Type.String(), wait_id: Type.Optional(Type.String()), polling: Type.Optional(Type.Object({ interval_seconds: Type.Integer({ minimum: 1, maximum: 2147483 }), max_checks: Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }) }, { additionalProperties: false })) }, { additionalProperties: false }),
+		])),
 		reason: Type.Optional(Type.String({ description: "Required when status is paused or blocked: describe the concrete blocker." })),
 		attempted_actions: Type.Optional(Type.Array(Type.String({ maxLength: 240 }), { maxItems: 8, description: "Actions attempted against the blocker." })),
 		suggested_action: Type.Optional(Type.String({ description: "Optional suggested next step when status is paused." })),
@@ -523,6 +528,10 @@ pi.registerTool(defineTool({
 		// P1-3: persist any buffered in-turn mutations now so the auditor and
 		// status transitions observe the current task/state, not the stale disk.
 		core.flushGoalTransaction(ctx);
+		if (!!params.continuation === !!params.status || (params.continuation && (params.reason !== undefined || params.attempted_actions !== undefined || params.suggested_action !== undefined || params.completion_summary !== undefined))) {
+			return { content: [{ type: "text", text: "Provide exactly one lifecycle status or continuation, without mixing their fields." }], details: {}, terminate: false };
+		}
+		if (params.continuation) return core.scheduler.declare(ctx, params.continuation as GoalContinuation);
 		if (params.status === "blocked") {
 			const attempted = Array.isArray((params as { attempted_actions?: unknown }).attempted_actions)
 				? ((params as { attempted_actions: unknown[] }).attempted_actions.filter((a): a is string => typeof a === "string"))

package/extensions/goal-events.ts

@@ -1,3 +1,4 @@
+import { schedulerSummary } from "./goal-scheduler-state.ts";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
 	GOAL_EVENT_ENTRY,
@@ -10,7 +11,6 @@ import {
 	isAbortedAssistantMessage,
 	isErrorAssistantMessage,
 	isMeaningfulProgressToolCall,
-	isToolUseAssistantMessage,
 } from "./goal-format.ts";
 import { buildCompactionSummary, buildPostCompactionGoalDelta } from "./goal-compaction.ts";
 import { latestAuditorResultForGoal, readGoalLedger, goalRuntimeEvents, invalidateGoalLedgerCache } from "./goal-ledger.ts";
@@ -86,19 +86,28 @@ export function registerGoalEvents(core: GoalCore): void {
 	const { pi } = core;
 	let continuationAfterSettleFor: string | null = null;
 	let networkErrorRecoveryAfterSettleFor: string | null = null;
-	// Run-scoped empty-turn gate: turn_start resets the per-turn flag, so a text-only
-	// last turn after earlier work must not wipe the run. before_agent_start starts a
-	// new run. agent_settled must not auto-continue a run that did no goal work, or
-	// empty replies ("Paused. No action.") loop forever.
-	let goalWorkThisRun = false;
 
-	pi.on("context", async (event) => {
+	pi.on("context", async (event, ctx) => {
 		const filtered = filterGoalSessionContext(event.messages);
 		const messages = compactGoalCheckpointContext(filtered ?? event.messages, core.state.goal) ?? filtered;
+		if (core.scheduler.needsLiveContext() && core.state.goal) {
+			const goal = core.state.goal;
+			const settings = loadGoalSettings(ctx.cwd);
+			// Custom-message runs bypass before_agent_start. Refresh mutable scheduling
+			// state, but do not repeat policy/objective already in the inherited prompt.
+			const content = ctx.getSystemPrompt?.().includes(`[PI GOAL ACTIVE goalId=${goal.id}]`)
+				? `[CURRENT EXECUTION STATE goalId=${goal.id}]\nStatus: ${goal.status}; autoContinue: ${goal.autoContinue}.\n${schedulerSummary(goal.scheduler, settings.maxAutonomousRuns)}`
+				: goalPrompt(goal, settings);
+			const live = { role: "custom" as const, customType: "pi-goal-live-context", content, display: false, timestamp: Date.now() };
+			return { messages: [live, ...(messages ?? event.messages)] as typeof event.messages };
+		}
 		return messages === null ? undefined : { messages: messages as typeof event.messages };
 	});
 
+	pi.on("agent_start", async (_event, ctx) => { core.scheduler.begin(ctx); });
+	pi.on("message_start", async (event, ctx) => { core.scheduler.message(ctx, event.message); });
 	pi.on("turn_start", async (_event, ctx) => {
+		core.scheduler.turn(ctx);
 		// Per-turn flag resets (#4 + C9 fix).
 		core.advanceTurnSeq();
 		core.goalWorkToolCalledThisTurn = false;
@@ -111,6 +120,7 @@ export function registerGoalEvents(core: GoalCore): void {
 	// #4 + C9 fix + Phase 5 C3: gate in-turn tool calls based on lifecycle state.
 	pi.on("tool_call", async (event, ctx) => {
 		const stoppedGoalId = core.currentTurnStoppedGoalId();
+		if (core.scheduler.isDenied()) return { block: true, reason: "Stale goal dispatch; use /goal-resume." };
 		// Post-stop in-turn block: after update_goal / set_goal_tasks (or a user
 		// lifecycle command) fires in this turn, block all subsequent tool calls
 		// except read-only inspection.
@@ -133,10 +143,9 @@ export function registerGoalEvents(core: GoalCore): void {
 					`End the turn with a brief summary and yield to the user.`,
 			};
 		}
-		// Track for #4 empty-turn gate (per-turn and per-run).
+		// Track Oracle work attempts; this does not authorize scheduling.
 		if (isMeaningfulProgressToolCall(event.toolName, asRecord(event)?.args)) {
 			core.goalWorkToolCalledThisTurn = true;
-			goalWorkThisRun = true;
 			// Issue #26: record a meaningful work attempt against armed Oracle
 			// advice. get_goal / echo-only reads are excluded upstream by
 			// isMeaningfulProgressToolCall.
@@ -252,17 +261,6 @@ export function registerGoalEvents(core: GoalCore): void {
 			core.updateUI(ctx);
 		}
 
-		// If the assistant ended a turn without queuing more tool calls, push a continuation right away.
-		// #4: only queue if some real work was done this turn — otherwise the model is
-		// just chatting and we should not keep firing turns on noise.
-		if (
-			!isToolUseAssistantMessage(message)
-			&& core.state.goal?.status === "active"
-			&& core.state.goal.autoContinue
-			&& core.goalWorkToolCalledThisTurn
-		) {
-			core.queueContinuation(ctx);
-		}
 		core.goalService.endTurn(ctx); // P1-3: single flush (lock + write + ledger batch)
 	});
 
@@ -311,11 +309,11 @@ export function registerGoalEvents(core: GoalCore): void {
 			const current = core.state.goal;
 			const shouldResume = await ctx.ui.confirm("Resume paused goal?", `Goal: ${current.objective}`);
 			if (shouldResume) {
-				core.setGoal({ ...current, status: "active", autoContinue: true, stopReason: undefined, pauseReason: undefined, pauseSuggestedAction: undefined }, ctx);
+				core.scheduler.resume(ctx);
 			}
 		}
 		core.beginAccounting();
-		core.queueContinuation(ctx, true);
+		core.scheduler.restore(ctx);
 	});
 
 	pi.on("session_before_compact", async (_event, ctx) => {
@@ -341,11 +339,11 @@ export function registerGoalEvents(core: GoalCore): void {
 		rehydrateDraft(core, ctx);
 		syncTerminalInputPause(core, ctx);
 		core.beginAccounting();
-		core.queueContinuation(ctx, true);
+		core.scheduler.restore(ctx);
 	});
 
 	pi.on("before_agent_start", async (event, ctx) => {
-		goalWorkThisRun = false;
+		core.scheduler.prepare();
 		core.advanceTurnSeq();
   if (!hasActiveDraft(core)) core.installGoalToolProfile(!loadGoalSettings(ctx.cwd).disableTasks);
 		const currentSystemPrompt = () => ctx.getSystemPrompt?.() || event.systemPrompt;
@@ -531,10 +529,6 @@ export function registerGoalEvents(core: GoalCore): void {
 		core.runtime.clearNetworkErrorBackoff();
 		core.persist(ctx);
 		core.updateUI(ctx);
-		// Empty-turn gate: agent_end clears any turn_end continuation timer, then
-		// agent_settled re-queues with force=true. Without this check, a no-tool
-		// reply (chat, or "Paused. No action." after resume) loops forever.
-		if (!goalWorkThisRun) return;
 		// agent_end runs before pi finishes retries, compaction, terminating-tool
 		// settlement, and queued messages. Starting the continuation timer here
 		// can poll a stale busy context for minutes on pi 0.84. agent_settled is
@@ -549,10 +543,8 @@ export function registerGoalEvents(core: GoalCore): void {
 		continuationAfterSettleFor = null;
 		const networkErrorGoalId = networkErrorRecoveryAfterSettleFor;
 		networkErrorRecoveryAfterSettleFor = null;
-		if (goalId && core.isActionableContinuationGoal(goalId)) {
-			core.queueContinuation(ctx, true);
-			return;
-		}
+		core.scheduler.settled(ctx, !!goalId && core.isActionableContinuationGoal(goalId));
+		if (goalId && core.isActionableContinuationGoal(goalId)) return;
 		if (!networkErrorGoalId || !core.isActionableContinuationGoal(networkErrorGoalId)) return;
 		const recovery = loadGoalSettings(ctx.cwd).networkRecovery;
 		const policy = recovery
@@ -576,6 +568,7 @@ export function registerGoalEvents(core: GoalCore): void {
 
 	pi.on("session_shutdown", async (_event, ctx) => {
 		core.auditMessages.clear();
+		core.scheduler.shutdown();
 		continuationAfterSettleFor = null;
 		networkErrorRecoveryAfterSettleFor = null;
 		core.accountProgress(ctx);

package/extensions/goal-record.ts

@@ -1,3 +1,4 @@
+import { normalizeGoalScheduler, type GoalSchedulerState } from "./goal-scheduler-state.ts";
 export type GoalStatus = "active" | "paused" | "blocked" | "budget_limited" | "complete";
 export type StopReason = "user" | "agent";
 export type GoalEventKind = "checkpoint" | "stale";
@@ -56,6 +57,7 @@ export interface GoalRecord {
 	revision?: number;
 	/** Optional token budget (whole tokens). When accounted usage reaches it, the runtime marks the goal budget_limited. */
 	tokenBudget?: number;
+	scheduler?: GoalSchedulerState;
 	/**
 	 * Execution focus: the id of the task (or subtask) the agent is working on.
 	 * Optional for backward compatibility; normalized at load (only an existing
@@ -119,7 +121,13 @@ export interface GoalStaleDetails {
 }
 
 /** Everything that can appear in a persisted pi-goal-event entry's details. */
-export type GoalEventEntryDetails = GoalCheckpointDetailsV2 | LegacyGoalEventDetails | GoalStaleDetails;
+export interface GoalCheckpointDetailsV3 extends Omit<GoalCheckpointDetailsV2, "version"> {
+	version: 3;
+	generation: string;
+	dispatchId: string;
+}
+
+export type GoalEventEntryDetails = GoalCheckpointDetailsV3 | GoalCheckpointDetailsV2 | LegacyGoalEventDetails | GoalStaleDetails;
 
 /**
  * Legacy normalized renderer shape. Kept as the stable contract for
@@ -181,6 +189,7 @@ function cloneGoalTask(task: GoalTask): GoalTask {
 export function cloneGoal(goal: GoalRecord): GoalRecord {
 	return {
 		...goal,
+		...(goal.scheduler ? { scheduler: structuredClone(goal.scheduler) } : {}),
 		usage: { ...goal.usage },
 		taskList: goal.taskList
 			? { ...goal.taskList, tasks: goal.taskList.tasks.map(cloneGoalTask) }
@@ -370,6 +379,7 @@ export function normalizeGoalRecord(value: unknown): GoalRecord | null {
 		skipAuditor: raw.skipAuditor === true ? true : undefined,
 		revision: Number.isSafeInteger(raw.revision) && (raw.revision as number) >= 0 ? (raw.revision as number) : 0,
 		tokenBudget: normalizePositiveSafeInteger(raw.tokenBudget),
+		...(raw.scheduler !== undefined ? { scheduler: normalizeGoalScheduler(raw.scheduler) } : {}),
 		taskList,
 		currentTaskId,
 		verificationContract: typeof raw.verificationContract === "string" ? raw.verificationContract : undefined,

package/extensions/goal-runtime.ts

@@ -9,7 +9,7 @@
  */
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { GoalCheckpointDetailsV2, GoalRecord } from "./goal-record.ts";
+import type { GoalCheckpointDetailsV3, GoalRecord } from "./goal-record.ts";
 import { checkpointTriggerPrompt } from "./prompts/goal-prompts.ts";
 import { POST_STOP_ALLOWED_TOOLS } from "./goal-tool-names.ts";
 import { networkErrorBackoffPlan, type NetworkErrorBackoffPlan, type NetworkErrorRecoveryPolicy } from "./network-error-backoff.ts";
@@ -19,6 +19,9 @@ export const CONTINUATION_IDLE_RETRY_MS = 50;
 const POST_STOP_ALLOWED = new Set<string>(POST_STOP_ALLOWED_TOOLS);
 
 export interface GoalRuntimeHooks {
+	authorize?(ctx: ExtensionContext, goal: GoalRecord): Record<string, unknown> | null;
+	recover?(ctx: ExtensionContext): void;
+	dispatchFailed?(ctx: ExtensionContext): void;
 	/** Dispatch a hidden follow-up checkpoint message (pi.sendMessage + triggerTurn). */
 	sendFollowUp(content: string, details: Record<string, unknown>): void;
 	/** Current focused goal (state.goal). */
@@ -125,7 +128,7 @@ export class GoalRuntime {
 			if (!this.hooks.isActionable(goal.id)) return;
 			const currentGoal = this.hooks.getGoal();
 			if (!currentGoal || currentGoal.id !== goal.id) return;
-			this.queueContinuation(ctx, currentGoal, true);
+			this.hooks.recover?.(ctx);
 		}, plan.delayMs);
 		this.networkErrorRetryTimer.unref?.();
 		return plan;
@@ -172,10 +175,14 @@ export class GoalRuntime {
 			if (this.continuationQueuedFor === scheduledGoalId) this.continuationQueuedFor = null;
 			return;
 		}
+		const authorization = this.hooks.authorize?.(ctx, goal);
+		if (!authorization) return;
 		this.checkpointSeq += 1;
 		this.continuationQueuedFor = goal.id;
-		const details: GoalCheckpointDetailsV2 = {
-			version: 2,
+		const details: GoalCheckpointDetailsV3 = {
+			version: 3,
+			generation: String(authorization.generation),
+			dispatchId: String(authorization.dispatchId),
 			kind: "checkpoint",
 			goalId: goal.id,
 			status: "active",
@@ -183,7 +190,8 @@ export class GoalRuntime {
 			checkpointSeq: this.checkpointSeq,
 			timestamp: Date.now(),
 		};
-		this.hooks.sendFollowUp(checkpointTriggerPrompt(goal.id), details as unknown as Record<string, unknown>);
+		try { this.hooks.sendFollowUp(checkpointTriggerPrompt(goal.id), details as unknown as Record<string, unknown>); }
+		catch { this.hooks.dispatchFailed?.(ctx); }
 	}
 
 	// ── turn-stop guard ──────────────────────────────────────────────────

package/extensions/goal-scheduler-state.ts

@@ -0,0 +1,67 @@
+import { randomUUID } from "node:crypto";
+
+export type GoalDispatchKind = "ready" | "check" | "wake" | "repair" | "kickoff" | "recovery";
+export interface GoalWait {
+	id: string;
+	token: string;
+	reason: string;
+	deadline: number;
+	intervalMs?: number;
+	remainingChecks?: number;
+	nextCheckAt?: number;
+	signalled?: boolean;
+}
+export interface GoalSchedulerState {
+	version: 1;
+	owner: string;
+	generation: string;
+	used: number;
+	phase: "idle" | "ready" | "waiting" | "claimed" | "running" | "interrupted";
+	decision?: { kind: "ready"; nextAction: string; purpose: GoalDispatchKind } | { kind: "wait" };
+	wait?: GoalWait;
+	dispatch?: { id: string; kind: GoalDispatchKind; claimedAt: number };
+	repairUsed: boolean;
+}
+export type GoalContinuation =
+	| { kind: "ready"; next_action: string }
+	| { kind: "wait"; reason: string; deadline: string; wait_id?: string; polling?: { interval_seconds: number; max_checks: number } };
+
+export function newGoalScheduler(owner: string): GoalSchedulerState {
+	return { version: 1, owner, generation: randomUUID(), used: 0, phase: "idle", repairUsed: false };
+}
+
+/** Corrupt scheduling data must not silently reset spent allowance. */
+export function normalizeGoalScheduler(raw: unknown): GoalSchedulerState | undefined {
+	if (raw === undefined) return undefined;
+	const invalid = (): GoalSchedulerState => ({ ...newGoalScheduler("invalid"), phase: "interrupted", used: Number.MAX_SAFE_INTEGER });
+	if (!raw || typeof raw !== "object") return invalid();
+	const s = raw as GoalSchedulerState;
+	const integer = (n: unknown) => typeof n === "number" && Number.isSafeInteger(n) && n >= 0;
+	const text = (v: unknown) => typeof v === "string" && v.length > 0 && v.length <= 2000;
+	if (s.version !== 1 || !text(s.owner) || !text(s.generation) || !integer(s.used) || typeof s.repairUsed !== "boolean" || !["idle", "ready", "waiting", "claimed", "running", "interrupted"].includes(s.phase)) return invalid();
+	if (s.decision && (s.decision.kind !== "wait" && (s.decision.kind !== "ready" || !text(s.decision.nextAction) || !["ready", "repair", "kickoff", "recovery"].includes(s.decision.purpose)))) return invalid();
+	if (s.wait) {
+		const w = s.wait;
+		if (!text(w.id) || !text(w.token) || !text(w.reason) || (!integer(w.deadline) || w.deadline > 8_640_000_000_000_000)) return invalid();
+		if (w.intervalMs !== undefined && (!integer(w.intervalMs) || w.intervalMs < 1000 || !integer(w.remainingChecks) || !integer(w.nextCheckAt))) return invalid();
+		if (w.intervalMs === undefined && (w.remainingChecks !== undefined || w.nextCheckAt !== undefined)) return invalid();
+		if (w.signalled !== undefined && typeof w.signalled !== "boolean") return invalid();
+	}
+	if (s.dispatch && (!text(s.dispatch.id) || !integer(s.dispatch.claimedAt) || !["ready", "check", "wake", "repair", "kickoff", "recovery"].includes(s.dispatch.kind))) return invalid();
+	if ((s.phase === "claimed" || s.phase === "running") && !s.dispatch) return invalid();
+	if (s.phase === "ready" && s.decision?.kind !== "ready") return invalid();
+	if (s.phase === "waiting" && (!s.wait || s.decision?.kind !== "wait")) return invalid();
+	return structuredClone(s);
+}
+
+export function schedulerSummary(s: GoalSchedulerState | undefined, limit?: number): string {
+	const lines = [`Autonomous runs: ${s?.used ?? 0}/${limit ?? "unlimited"}${limit === 0 ? " (automatic continuation disabled)" : ""}.`];
+	if (!s) return lines.join("\n");
+	if (s.decision?.kind === "ready") lines.push(`Next action: ${s.decision.nextAction}`);
+	if (s.wait) {
+		lines.push(`Waiting: ${s.wait.reason}; wait_id=${s.wait.id}; deadline=${new Date(s.wait.deadline).toISOString()}.`);
+		if (s.wait.nextCheckAt !== undefined) lines.push(`Next check: ${new Date(s.wait.nextCheckAt).toISOString()}; ${s.wait.remainingChecks} checks remaining.`);
+	}
+	if (s.phase === "interrupted" || s.phase === "claimed") lines.push("Execution requires dispatch admission or explicit /goal-resume after interruption.");
+	return lines.join("\n");
+}

package/extensions/goal-scheduler.ts

@@ -0,0 +1,327 @@
+import { randomUUID } from "node:crypto";
+import type { ExtensionContext, AgentToolResult } from "@earendil-works/pi-coding-agent";
+import type { GoalCore } from "./goal-state.ts";
+import { asRecord, type GoalRecord } from "./goal-record.ts";
+import { budgetReached } from "./goal-accounting.ts";
+import { loadGoalSettings, invalidateGoalSettingsCache } from "./goal-settings.ts";
+import { newGoalScheduler, schedulerSummary, type GoalContinuation, type GoalSchedulerState } from "./goal-scheduler-state.ts";
+
+/** Scheduling intent is durable; timers only arrange an opportunity to claim it. */
+export class GoalScheduler {
+	private timer: ReturnType<typeof setTimeout> | undefined;
+	private ctx: ExtensionContext | undefined;
+	private inRun = false;
+	private prepared = false;
+	private liveContext = false;
+	private armedGeneration: string | undefined;
+	private declared = false;
+	private runGoalId: string | undefined;
+	private denied = false;
+	private unsubscribe: (() => void) | undefined;
+	private core: GoalCore;
+	constructor(core: GoalCore) { this.core = core; }
+
+	private owner(ctx: ExtensionContext): string { return ctx.sessionManager.getSessionId() || "unknown-session"; }
+	private limit(ctx: ExtensionContext): number | undefined { return loadGoalSettings(ctx.cwd).maxAutonomousRuns; }
+	private available(ctx: ExtensionContext, s: GoalSchedulerState): boolean {
+		const limit = this.limit(ctx);
+		return limit === undefined || s.used < limit;
+	}
+	private state(ctx: ExtensionContext, goal: GoalRecord): GoalSchedulerState {
+		const s = goal.scheduler ?? newGoalScheduler(this.owner(ctx));
+		if (s.owner !== this.owner(ctx) || s.phase === "interrupted") throw new Error("Goal scheduling belongs to another session or was interrupted. Use /goal-resume to take ownership.");
+		return s;
+	}
+	private write(ctx: ExtensionContext, change: (g: GoalRecord) => GoalRecord): GoalRecord {
+		const error = this.core.goalService.flushForAudit(ctx);
+		if (error || this.core.goalService.isTurnBuffered()) throw new Error(error || "Goal changes have not reached disk.");
+		const id = this.core.state.goal?.id;
+		if (!id) throw new Error("No focused goal.");
+		const result = this.core.goalService.apply(ctx, { expectedGoalId: id, mutate: change,
+			ledger: g => g.status === "paused" ? [{ type: "goal_paused", goalId: g.id, reason: g.pauseReason ?? "Scheduling paused", source: "agent", at: new Date().toISOString() }] : [],
+		});
+		if (!result.ok) throw new Error(result.message);
+		this.core.updateUI(ctx);
+		return result.goal;
+	}
+	private update(ctx: ExtensionContext, change: (s: GoalSchedulerState, g: GoalRecord) => void): GoalRecord {
+		return this.write(ctx, g => { const s = this.state(ctx, g); change(s, g); return { ...g, scheduler: s }; });
+	}
+	private safe(ctx: ExtensionContext, fn: () => void): void {
+		try { fn(); } catch (error) {
+			this.cancelTimer();
+			this.core.runtime.clearContinuationState();
+			ctx.ui.notify(`Goal scheduling stopped: ${error instanceof Error ? error.message : String(error)}`, "warning");
+		}
+	}
+	cancelTimer(): void {
+		if (this.timer !== undefined) clearTimeout(this.timer);
+		this.timer = undefined;
+		this.armedGeneration = undefined;
+	}
+	private later(ctx: ExtensionContext, delay: number, fn: () => void): void {
+		this.cancelTimer();
+		this.timer = setTimeout(() => { this.timer = undefined; this.safe(ctx, fn); }, Math.min(2_147_483_647, Math.max(0, delay)));
+		this.timer.unref?.();
+	}
+	private pause(ctx: ExtensionContext, reason: string): void {
+		this.cancelTimer();
+		this.core.runtime.clearContinuationState();
+		this.write(ctx, g => {
+			if (g.scheduler && g.scheduler.owner !== this.owner(ctx)) throw new Error("Scheduling ownership changed; no pause was applied.");
+			return { ...g, status: "paused", autoContinue: false, stopReason: "agent", pauseReason: reason,
+				scheduler: g.scheduler ? { ...g.scheduler, generation: randomUUID(), phase: "idle", decision: undefined, dispatch: undefined, wait: undefined } : undefined };
+		});
+		this.core.clearActiveAccounting();
+		ctx.ui.notify(reason, "warning");
+	}
+	private allowanceReason(ctx: ExtensionContext): string {
+		return this.limit(ctx) === 0 ? "Automatic continuation disabled by maxAutonomousRuns=0. Change the setting in /goal-settings, then use /goal-resume." : "Autonomous-run allowance exhausted. Increase or remove maxAutonomousRuns, or use /goal-resume to renew.";
+	}
+
+	/** Bind once per live session. The event is deliberately not a triggerTurn message. */
+	attach(ctx: ExtensionContext): void {
+		this.ctx = ctx;
+		this.unsubscribe?.();
+		this.unsubscribe = this.core.pi.events?.on("pi-goal:wake", (event: unknown) => {
+			const raw = asRecord(event);
+			if (raw && this.ctx) this.signal(this.ctx, raw.goalId, raw.waitToken);
+		});
+	}
+	shutdown(): void { this.cancelTimer(); this.unsubscribe?.(); this.unsubscribe = undefined; this.ctx = undefined; }
+
+	restore(ctx: ExtensionContext): void {
+		this.attach(ctx);
+		this.inRun = false; this.declared = false; this.runGoalId = undefined;
+		this.cancelTimer();
+		this.safe(ctx, () => {
+			this.core.reconcileFocusedGoalFromDisk(ctx);
+			const goal = this.core.state.goal;
+			if (!goal || goal.status !== "active" || !goal.autoContinue || !goal.scheduler) return;
+			const s = goal.scheduler;
+			if (s.owner !== this.owner(ctx)) { ctx.ui.notify("Goal owned by another session. Use /goal-resume to take ownership.", "info"); return; }
+			if (["claimed", "running", "interrupted"].includes(s.phase)) {
+				this.pause(ctx, "Previous autonomous execution was interrupted. Use /goal-resume; its dispatch will not be replayed.");
+				return;
+			}
+			this.schedule(ctx);
+		});
+	}
+
+	/** Only explicit user resume resets spent allowance, including while already active/waiting. */
+	resume(ctx: ExtensionContext): boolean {
+		invalidateGoalSettingsCache();
+		if (this.limit(ctx) === 0) { ctx.ui.notify(this.allowanceReason(ctx), "warning"); return false; }
+		try {
+			this.cancelTimer();
+			this.core.runtime.clearContinuationState();
+			this.write(ctx, g => {
+				if (g.status === "complete" || budgetReached(g)) throw new Error("A completed or token-budget-limited goal cannot resume.");
+				return { ...g, status: "active", autoContinue: true, stopReason: undefined, pauseReason: undefined, pauseSuggestedAction: undefined,
+					scheduler: { ...newGoalScheduler(this.owner(ctx)), phase: "ready", decision: { kind: "ready", nextAction: "Continue the goal at the user's request.", purpose: "kickoff" } } };
+			});
+			// A resume during host work waits for settlement; another model turn
+			// still invalidates it through turn(), just like a declaration.
+			this.declared = this.inRun;
+			this.schedule(ctx);
+			return true;
+		} catch (error) { ctx.ui.notify(String(error), "warning"); return false; }
+	}
+	kickoff(ctx: ExtensionContext): void {
+		if (this.inRun) return; // creating a goal within a user run needs no extra run
+		this.safe(ctx, () => {
+			const goal = this.core.state.goal;
+			if (!goal || goal.status !== "active" || !goal.autoContinue) return;
+			if (this.limit(ctx) === 0) { this.update(ctx, () => {}); ctx.ui.notify(this.allowanceReason(ctx), "info"); return; }
+			this.update(ctx, s => { s.phase = "ready"; s.decision = { kind: "ready", nextAction: "Begin the requested goal.", purpose: "kickoff" }; });
+			this.schedule(ctx);
+		});
+	}
+
+	declare(ctx: ExtensionContext, input: GoalContinuation): AgentToolResult<unknown> {
+		try {
+			if (!this.core.state.goal || this.core.state.goal.status !== "active" || !this.core.state.goal.autoContinue || this.denied) throw new Error("Scheduling requires an active auto-continue goal in this session.");
+			invalidateGoalSettingsCache(); // an agent may have just configured the allowance
+			const goal = this.update(ctx, s => {
+				if (!this.available(ctx, s)) throw new Error(this.allowanceReason(ctx));
+				if (input.kind === "ready") {
+					if (typeof input.next_action !== "string" || !input.next_action.trim() || input.next_action.length > 2000) throw new Error("ready requires a nonempty next_action (at most 2000 characters).");
+					s.phase = "ready"; s.decision = { kind: "ready", nextAction: input.next_action.trim(), purpose: "ready" }; s.wait = undefined;
+				} else if (input.kind === "wait") {
+					if (typeof input.reason !== "string" || !input.reason.trim() || input.reason.length > 2000) throw new Error("wait requires a nonempty reason (at most 2000 characters).");
+					const deadline = Date.parse(input.deadline);
+					if (!/T.*(?:Z|[+-]\d\d:\d\d)$/.test(input.deadline) || !Number.isSafeInteger(deadline) || deadline <= Date.now()) throw new Error("wait requires a future ISO deadline with a timezone.");
+					if (s.wait) {
+						if (input.wait_id !== s.wait.id || deadline !== s.wait.deadline) throw new Error("Re-declare the current wait_id with its original deadline; checks cannot be reset.");
+						if (input.polling && (input.polling.interval_seconds * 1000 !== s.wait.intervalMs || input.polling.max_checks !== s.wait.remainingChecks)) throw new Error("Existing wait polling cannot be reset; omit polling when re-declaring wait_id.");
+						s.wait.token = randomUUID(); s.wait.signalled = false;
+						if (s.wait.intervalMs) s.wait.nextCheckAt = Date.now() + s.wait.intervalMs;
+					} else {
+						if (input.wait_id) throw new Error("Unknown wait_id.");
+						const polling = input.polling;
+						if (polling && (!Number.isSafeInteger(polling.interval_seconds) || polling.interval_seconds < 1 || polling.interval_seconds > 2_147_483 || !Number.isSafeInteger(polling.max_checks) || polling.max_checks < 1)) throw new Error("Polling requires positive whole interval_seconds (at most 2147483) and max_checks.");
+						s.wait = { id: randomUUID(), token: randomUUID(), reason: input.reason.trim(), deadline,
+							...(polling ? { intervalMs: polling.interval_seconds * 1000, remainingChecks: polling.max_checks, nextCheckAt: Date.now() + polling.interval_seconds * 1000 } : {}) };
+					}
+					s.phase = "waiting"; s.decision = { kind: "wait" };
+				} else throw new Error("Unknown continuation kind.");
+				s.dispatch = undefined;
+				s.generation = randomUUID();
+			});
+			this.declared = true;
+			this.core.runtime.markTurnStopped(goal.id);
+			const wait = goal.scheduler?.wait;
+			return { content: [{ type: "text", text: `Scheduling decision saved. Stop this execution.\n${schedulerSummary(goal.scheduler, this.limit(ctx))}${wait ? `\nWake token: ${wait.token}. Register this token with the producer before completion; adapters must retain early results.` : ""}` }], details: { goal, ...(wait ? { wait_id: wait.id, waitToken: wait.token } : {}) }, terminate: true };
+		} catch (error) { return { content: [{ type: "text", text: `Scheduling decision NOT saved: ${error instanceof Error ? error.message : String(error)}` }], details: { error: true }, terminate: false }; }
+	}
+
+	prepare(): void { this.prepared = true; }
+	needsLiveContext(): boolean { return this.liveContext; }
+
+	/** One logical run can contain multiple agent_start events during native retry/compaction. */
+	begin(ctx: ExtensionContext): void {
+		this.ctx = ctx;
+		if (this.inRun) { this.core.runningGoalId = this.core.state.goal?.id ?? null; return; }
+		this.liveContext = !this.prepared; this.prepared = false;
+		this.inRun = true; this.declared = false; this.denied = false;
+		this.runGoalId = this.core.state.goal?.id;
+		this.cancelTimer(); this.core.runtime.clearContinuationTimer();
+		this.core.runningGoalId = this.core.state.goal?.id ?? null;
+	}
+	turn(ctx: ExtensionContext): void {
+		if (!this.declared) return;
+		this.declared = false;
+		this.safe(ctx, () => this.update(ctx, s => { s.decision = undefined; s.phase = "idle"; s.dispatch = undefined; }));
+	}
+	message(ctx: ExtensionContext, rawMessage: unknown): void {
+		const msg = asRecord(rawMessage);
+		if (!msg || !["user", "custom"].includes(String(msg.role))) return;
+		if (msg.customType === "pi-goal-audit-event") return;
+		if (msg.customType === "pi-goal-event") {
+			const d = asRecord(msg.details);
+			if (d?.kind !== "checkpoint") return;
+			try {
+				this.update(ctx, (s, g) => {
+					if (d.version !== 3 || s.phase !== "claimed" || g.id !== d.goalId || s.generation !== d.generation || s.dispatch?.id !== d.dispatchId || g.status !== "active" || !g.autoContinue) throw new Error("Stale or unclaimed goal checkpoint.");
+					// Retain the admitted action as context; phase prevents reusing its authorization.
+					s.phase = "running";
+				});
+			} catch (error) {
+				this.denied = true;
+				this.core.runtime.setCheckpoint(String(d?.goalId ?? "invalid"));
+				ctx.abort?.();
+				ctx.ui.notify(`Goal checkpoint rejected: ${String(error)}`, "warning");
+			}
+			return;
+		}
+		// Genuine host work supersedes an old scheduling claim, but never resets used.
+		this.takeover(ctx);
+	}
+	takeover(ctx: ExtensionContext): void {
+		this.cancelTimer(); this.core.runtime.clearContinuationState();
+		this.declared = false;
+		const s = this.core.state.goal?.scheduler;
+		if (!s || s.owner !== this.owner(ctx)) return;
+		this.safe(ctx, () => this.update(ctx, state => {
+			state.generation = randomUUID(); state.phase = "idle"; state.decision = undefined; state.dispatch = undefined; state.wait = undefined;
+			state.repairUsed = false;
+		}));
+	}
+	settled(ctx: ExtensionContext, successful = true): void {
+		this.inRun = false;
+		if (this.denied || (this.runGoalId && this.core.state.goal?.id !== this.runGoalId)) return;
+		this.safe(ctx, () => {
+			const goal = this.core.state.goal;
+			if (!goal || goal.status !== "active" || !goal.autoContinue || !successful) return;
+			if (this.declared && goal.scheduler?.decision) { this.schedule(ctx); return; }
+			const s = this.state(ctx, goal);
+			if (s.repairUsed || !this.available(ctx, s)) {
+				this.pause(ctx, !this.available(ctx, s) ? this.allowanceReason(ctx) : "No execution disposition after the contract-repair prompt. Use /goal-resume to continue.");
+				return;
+			}
+			this.update(ctx, state => {
+				state.phase = "ready"; state.dispatch = undefined;
+				state.decision = { kind: "ready", nextAction: "The prior execution did not declare a disposition. Declare ready with a concrete next action, wait with a deadline, or complete/pause/block. This is the only repair prompt.", purpose: "repair" };
+			});
+			this.schedule(ctx);
+		});
+	}
+	recover(ctx: ExtensionContext): void {
+		this.safe(ctx, () => {
+			this.update(ctx, s => { s.phase = "ready"; s.dispatch = undefined; s.decision = { kind: "ready", nextAction: "Retry after the provider error, then declare an execution disposition.", purpose: "recovery" }; });
+			this.schedule(ctx);
+		});
+	}
+
+	signal(ctx: ExtensionContext, goalId: unknown, token: unknown): void {
+		this.safe(ctx, () => {
+			this.core.reconcileFocusedGoalFromDisk(ctx);
+			const g = this.core.state.goal; const s = g?.scheduler;
+			if (!g || g.id !== goalId || g.status !== "active" || !g.autoContinue || s?.owner !== this.owner(ctx) || s.phase !== "waiting" || !s.wait || s.wait.token !== token || s.wait.signalled) return;
+			this.update(ctx, current => { if (current.wait?.token !== token || current.phase !== "waiting") throw new Error("Wait changed."); current.wait.signalled = true; });
+			if (!this.inRun) this.schedule(ctx);
+		});
+	}
+	schedule(ctx: ExtensionContext): void {
+		if (this.inRun) return;
+		this.safe(ctx, () => {
+			this.core.reconcileFocusedGoalFromDisk(ctx);
+			const g = this.core.state.goal;
+			if (!g || g.status !== "active" || !g.autoContinue || !g.scheduler) return;
+			const s = this.state(ctx, g);
+			if (!["ready", "waiting"].includes(s.phase)) return;
+			if (budgetReached(g)) { this.pause(ctx, "Goal token budget exhausted."); return; }
+			if (!this.available(ctx, s)) { this.pause(ctx, this.allowanceReason(ctx)); return; }
+			// Recovery and repair retain the wait while changing phase to ready.
+			if (s.wait && Date.now() >= s.wait.deadline) { this.pause(ctx, "Wait deadline reached."); return; }
+			if (s.phase === "waiting" && s.wait) {
+				this.core.clearActiveAccounting();
+				if (!s.wait.signalled && s.wait.remainingChecks === 0) { this.pause(ctx, "Wait check allowance exhausted."); return; }
+				if (!s.wait.signalled && (s.wait.nextCheckAt === undefined || s.wait.nextCheckAt > Date.now())) {
+					const due = Math.min(s.wait.deadline, s.wait.nextCheckAt ?? Infinity);
+					this.later(ctx, due - Date.now(), () => this.schedule(ctx)); return;
+				}
+			}
+			this.cancelTimer();
+			// Runtime readiness polling cannot authorize: claim() is called again at delivery.
+			this.armedGeneration = s.generation;
+			this.core.runtime.queueContinuation(ctx, g, true);
+		});
+	}
+	claim(ctx: ExtensionContext): Record<string, unknown> | null {
+		const generation = this.armedGeneration;
+		if (!generation) return null;
+		this.armedGeneration = undefined;
+		invalidateGoalSettingsCache();
+		try {
+			let result: Record<string, unknown> | null = null;
+			this.update(ctx, (s, g) => {
+				if (s.generation !== generation) throw new Error("Scheduling generation changed.");
+				if (g.status !== "active" || !g.autoContinue || budgetReached(g) || !this.available(ctx, s)) throw new Error(this.allowanceReason(ctx));
+				if (s.wait && Date.now() >= s.wait.deadline) throw new Error("Wait deadline reached.");
+				let kind = s.phase === "ready" && s.decision?.kind === "ready" ? s.decision.purpose : undefined;
+				if (s.phase === "waiting" && s.wait) {
+					if (s.wait.signalled) kind = "wake";
+					else if (s.wait.nextCheckAt !== undefined && s.wait.nextCheckAt <= Date.now() && (s.wait.remainingChecks ?? 0) > 0) { kind = "check"; s.wait.remainingChecks!--; }
+				}
+				if (!kind) throw new Error("No scheduling decision authorizes this checkpoint.");
+				s.used++; s.phase = "claimed"; s.dispatch = { id: randomUUID(), kind, claimedAt: Date.now() };
+				if (kind === "repair") s.repairUsed = true;
+				else if (kind !== "recovery") s.repairUsed = false;
+				if (s.wait) { s.wait.signalled = false; s.wait.token = randomUUID(); }
+				result = { generation: s.generation, dispatchId: s.dispatch.id };
+			});
+			return result;
+		} catch (error) {
+			const current = this.core.state.goal?.scheduler;
+			if (current && (current.owner !== this.owner(ctx) || current.generation !== generation)) return null;
+			this.safe(ctx, () => this.pause(ctx, `Goal wake stopped: ${error instanceof Error ? error.message : String(error)}`));
+			return null;
+		}
+	}
+	failedDispatch(ctx: ExtensionContext): void {
+		this.safe(ctx, () => this.pause(ctx, "Goal checkpoint delivery failed after claiming allowance. Use /goal-resume; it will not be replayed."));
+	}
+	isWaiting(): boolean { return !this.inRun && this.core.state.goal?.scheduler?.phase === "waiting"; }
+	isDenied(): boolean { return this.denied; }
+}

package/extensions/goal-session-health.ts

@@ -68,7 +68,7 @@ function accumulateCheckpointHealth(health: CheckpointHealth, entry: unknown): v
 	if (checkpoint.content.length > health.largestCheckpointChars) {
 		health.largestCheckpointChars = checkpoint.content.length;
 	}
-	const isV2 = checkpoint.version === 2 && V2_MARKER_PATTERN.test(checkpoint.content);
+	const isV2 = (checkpoint.version === 2 || checkpoint.version === 3) && V2_MARKER_PATTERN.test(checkpoint.content);
 	if (isV2) {
 		health.v2Minimal += 1;
 	} else {

package/extensions/goal-settings.ts

@@ -102,6 +102,8 @@ export interface GoalSettingsResolvedShape {
 	auditorProjectResources?: boolean;
 	/** F5: stall detector timeout in minutes (0 = off). */
 	stallTimeoutMinutes?: number;
+	/** Optional extension-run limit per creation/resume; zero disables, absent inherits (default unlimited). */
+	maxAutonomousRuns?: number;
 	/**
 	 * Maximum objective length in characters (0/unset = no limit, the
 	 * default; >0 caps objectives in create_goal, propose_goal_draft, and
@@ -328,6 +330,7 @@ const ALLOWED_SETTINGS_KEYS = new Set([
 	"autoSelectSingleGoal",
 	"auditorProjectResources",
 	"stallTimeoutMinutes",
+	"maxAutonomousRuns",
 	"objectiveMaxChars",
 	"keybindings",
 	"hideUnfocusedBanner",
@@ -397,6 +400,12 @@ export function parseSettingsLayer(
 				else layer.subtaskDepth = parsed;
 				break;
 			}
+			case "maxAutonomousRuns": {
+				const n = typeof value === "number" ? value : typeof value === "string" && /^[0-9]+$/.test(value.trim()) ? Number(value) : NaN;
+				if (!Number.isSafeInteger(n) || n < 0) diagnostics.push(diagnostic("invalid_value", "maxAutonomousRuns must be a nonnegative safe integer (0 disables automatic continuation)", key));
+				else layer.maxAutonomousRuns = n;
+				break;
+			}
 			case "stallTimeoutMinutes":
 			case "objectiveMaxChars": {
 				const parsed = asNonNegativeInt(value);
@@ -781,6 +790,11 @@ function resolvedSettingsSnapshot(cwd: string, env: NodeJS.ProcessEnv): Settings
 		globalValue: global.layer.oracle?.maxFailedAttemptsPerBlocker,
 		defaultValue: 2,
 	}));
+	const maxAutonomousRuns = track("maxAutonomousRuns", resolveLeaf<number | undefined>({
+		projectValue: project.layer.maxAutonomousRuns,
+		globalValue: global.layer.maxAutonomousRuns,
+		defaultValue: undefined,
+	}));
 	const stallTimeoutMinutes = track("stallTimeoutMinutes", resolveLeaf<number>({
 		projectValue: project.layer.stallTimeoutMinutes,
 		globalValue: global.layer.stallTimeoutMinutes,
@@ -840,6 +854,7 @@ function resolvedSettingsSnapshot(cwd: string, env: NodeJS.ProcessEnv): Settings
 		auditorProjectResources,
 		hideUnfocusedBanner,
 		stallTimeoutMinutes,
+		maxAutonomousRuns,
 		objectiveMaxChars,
 		keybindings,
 		networkRecovery: {
@@ -1189,6 +1204,7 @@ function buildPersistedLayer(settings: GoalSettings): Record<string, unknown> {
 		if (so.maxFailedAttemptsPerBlocker !== undefined) o.maxFailedAttemptsPerBlocker = so.maxFailedAttemptsPerBlocker;
 		if (Object.keys(o).length > 0) persisted.oracle = o;
 	}
+	if (settings.maxAutonomousRuns !== undefined) persisted.maxAutonomousRuns = settings.maxAutonomousRuns;
 	if (settings.stallTimeoutMinutes !== undefined) persisted.stallTimeoutMinutes = settings.stallTimeoutMinutes;
 	if (settings.objectiveMaxChars !== undefined) persisted.objectiveMaxChars = settings.objectiveMaxChars;
 	if (settings.keybindings?.dashboard) {
@@ -1232,6 +1248,7 @@ export function effectiveSettingsReport(cwd: string, env: NodeJS.ProcessEnv = pr
 		{ key: "thinkingLevel", label: "thinking_level", format: () => snapshot.value.thinkingLevel ?? "(default)" },
 		{ key: "auditorProjectResources", label: "auditor project resources", format: () => String(snapshot.value.auditorProjectResources) },
 		{ key: "hideUnfocusedBanner", label: "hide unfocused banner", format: () => String(snapshot.value.hideUnfocusedBanner) },
+		{ key: "maxAutonomousRuns", label: "autonomous run allowance", format: () => snapshot.value.maxAutonomousRuns === 0 ? "0 (disabled)" : String(snapshot.value.maxAutonomousRuns ?? "unlimited (default)") },
 		{ key: "stallTimeoutMinutes", label: "stall timeout (minutes)", format: () => String(snapshot.value.stallTimeoutMinutes) },
 		{ key: "objectiveMaxChars", label: "max objective length (0 = none)", format: () => String(snapshot.value.objectiveMaxChars) },
 		{ key: "networkRecovery", label: "network recovery attempts (0 = unbounded)", format: () => String(snapshot.value.networkRecovery?.maxAttempts ?? 0) },

package/extensions/goal-state.ts

@@ -31,6 +31,8 @@ import {
 import { GoalService } from "./goal-service.ts";
 import { goalActivityEvents } from "./goal-ledger.ts";
 import { GoalAccounting } from "./goal-accounting.ts";
+import { newGoalScheduler } from "./goal-scheduler-state.ts";
+import { GoalScheduler } from "./goal-scheduler.ts";
 import { GoalRuntime } from "./goal-runtime.ts";
 import { GoalAuditMessages } from "./goal-session-safety.ts";
 import {
@@ -79,6 +81,7 @@ export interface GoalCore {
 	goalWidgetComponentRef: { current: GoalWidgetComponent | null };
 	goalService: GoalService;
 	runtime: GoalRuntime;
+	scheduler: GoalScheduler;
 	auditMessages: GoalAuditMessages;
 	accounting: GoalAccounting;
 
@@ -262,7 +265,11 @@ export function createGoalCore(
 	// token/time accounting lives in `accounting` (extensions/goal-accounting.ts).
 	let goalWorkToolCalledThisTurn = false;
 
+	let scheduler: GoalScheduler;
 	const runtime = new GoalRuntime({
+		authorize: ctx => scheduler.claim(ctx),
+		recover: ctx => scheduler.recover(ctx),
+		dispatchFailed: ctx => scheduler.failedDispatch(ctx),
 		sendFollowUp: (content, details) => {
 			pi.sendMessage<GoalEventDetails>(
 				{
@@ -365,6 +372,7 @@ export function createGoalCore(
 	}
 
 	function clearContinuationState(resetNetworkErrorBackoff = true): void {
+		scheduler?.cancelTimer();
 		runtime.clearContinuationState(resetNetworkErrorBackoff);
 	}
 
@@ -413,6 +421,7 @@ export function createGoalCore(
 		opts: { recordLedger?: boolean } = {},
 	): void {
 		const previousGoalId = focusedGoalId;
+		if (previousGoalId !== goalId) scheduler.takeover(ctx);
 		if (previousGoalId !== goalId) goalService.flushTurn(ctx); // P1-3: persist the old buffer before switching focus
 		assignFocusedGoalId(goalId && goalsById.has(goalId) ? goalId : null);
 		if (previousGoalId !== focusedGoalId) {
@@ -455,6 +464,7 @@ export function createGoalCore(
 	}
 
 	function beginAccounting(): void {
+		if (scheduler?.isWaiting()) { clearActiveAccounting(); return; }
 		if (!state.goal || (state.goal.status !== "active")) {
 			clearActiveAccounting();
 			return;
@@ -862,8 +872,8 @@ export function createGoalCore(
 	}
 
 	function queueContinuation(ctx: ExtensionContext, force = false): void {
-		if (!state.goal) return;
-		runtime.queueContinuation(ctx, state.goal, force);
+		void force;
+		scheduler.schedule(ctx);
 	}
 
 	function enterGoalModal(): void {
@@ -876,6 +886,7 @@ export function createGoalCore(
 
 	function replaceGoal(config: GoalCreationConfig, ctx: ExtensionContext, startNow = true, verificationContract?: string, tokenBudget?: number): void {
 		const goal = createGoal(config);
+		goal.scheduler = newGoalScheduler(ctx.sessionManager.getSessionId());
 		if (verificationContract) goal.verificationContract = verificationContract;
 		if (config.taskList) goal.taskList = config.taskList;
 		if (typeof tokenBudget === "number" && tokenBudget > 0) goal.tokenBudget = Math.floor(tokenBudget);
@@ -902,10 +913,10 @@ export function createGoalCore(
 		if (result.focusChanged) appendFocusEntry(result.goalId, "created");
 		beginAccounting();
 		ctx.ui.notify(buildGoalRunningNotification(config), "info");
-		if (startNow && state.goal?.autoContinue) queueContinuation(ctx, true);
+		if (startNow && state.goal?.autoContinue) scheduler.kickoff(ctx);
 	}
 
-	return {
+	const core: GoalCore = {
 		pi,
 		dependencies,
 		state,
@@ -1002,6 +1013,7 @@ export function createGoalCore(
 		goalWidgetComponentRef,
 		goalService,
 		runtime,
+		get scheduler() { return scheduler; },
 		auditMessages: new GoalAuditMessages(),
 		accounting,
 		assignFocusedGoalId,
@@ -1049,4 +1061,6 @@ export function createGoalCore(
 		checkStall,
 		replaceGoal,
 	};
+	scheduler = new GoalScheduler(core);
+	return core;
 }

package/extensions/goal-status.ts

@@ -31,6 +31,7 @@ export const PLAIN_THEME = {
 } as never;
 
 export interface GoalStatusTextOptions {
+	maxAutonomousRuns?: number;
 	goal: GoalRecord | null;
 	focused: boolean;
 	otherOpenGoals: number;
@@ -72,6 +73,7 @@ export function buildGoalStatusText(options: GoalStatusTextOptions): string {
 	const events = options.ledgerEvents ?? [];
 	const model = deriveGoalDashboardModel(options.goal, {
 		focused: options.focused,
+		maxAutonomousRuns: options.maxAutonomousRuns,
 		otherOpenGoals: options.otherOpenGoals,
 		ledgerEvents: events,
 	});
@@ -218,6 +220,7 @@ function visibleLen(value: string): number {
 function buildVerboseStatus(goal: GoalRecord, model: ReturnType<typeof deriveGoalDashboardModel>, events: GoalLedgerEvent[], settingsReport: string[], _width: number): string {
 	const lines: string[] = [];
 	lines.push(`Goal id: ${goal.id}`);
+	lines.push(...(model?.scheduling ?? []));
 	lines.push(`Revision: ${goal.revision ?? 0}`);
 	lines.push(`Status: ${model?.status.label}${model?.focused ? " (focused)" : " (not focused)"}`);
 	lines.push(`Mode: ${goal.sisyphus ? "sisyphus" : "goal"} · auto-continue: ${goal.autoContinue ? "on" : "off"}`);

package/extensions/prompts/goal-prompts.ts

@@ -1,3 +1,4 @@
+import { schedulerSummary } from "../goal-scheduler-state.ts";
 import { taskIndex } from "../goal-task-index.ts";
 import { statusLabel, truncateText } from "../goal-core.ts";
 import { promptSafeObjective } from "../goal-contract.ts";
@@ -182,9 +183,11 @@ export function sisyphusDisciplineBlock(goal: GoalRecord): string {
 }
 
 /** Shared outcome/blocker policy for active goals (bounded). */
-function lifecyclePolicyBlock(): string {
+function lifecyclePolicyBlock(autonomous: boolean): string {
  return [
   "[OUTCOMES]",
+  '- Automatic runs default to unlimited. maxAutonomousRuns in .pi/pi-goal-x-settings.json caps runs; 0 disables (agents may set it). Only creation or user /goal-resume renews usage.',
+  ...(autonomous ? ['- End execution with update_goal: ready for runnable work, wait for an external condition, or a status below. Saved decisions terminate; further work invalidates them. Missing decisions allow one repair. Never busy-poll.'] : []),
   '- update_goal({status: "complete"}) only when every requirement is satisfied; the independent completion auditor checks actual evidence. Approval archives; rejection requires rework.',
   '- update_goal({status: "blocked"}) only after the SAME blocker recurs on three consecutive goal turns; keep trying concrete steps before then.',
   '- update_goal({status: "paused", reason: "…"}) pauses immediately. User controls: /goal-pause, /goal-resume, /goal-clear.',
@@ -204,7 +207,7 @@ let promptCacheChars = 0;
 function cachedPrompt(goal: GoalRecord, settings: GoalSettings | undefined, kind: "goal" | "continuation", build: () => string): string {
  const key = [kind, goal.id, goal.status, goal.autoContinue, goal.sisyphus, goal.objective,
   goal.verificationContract, settings?.disableTasks ? undefined : taskIndex(goal.taskList?.tasks),
-  goal.taskList?.blockCompletion, promptProfile(), goal.currentTaskId, settings?.disableTasks, settings?.disableContracts];
+  goal.taskList?.blockCompletion, promptProfile(), goal.currentTaskId, settings?.disableTasks, settings?.disableContracts, settings?.maxAutonomousRuns !== 0];
  for (let i = promptFragmentCache.length - 1; i >= 0; i--) {
   const entry = promptFragmentCache[i]!;
   if (key.every((part, j) => part === entry.key[j])) return entry.value;
@@ -227,7 +230,7 @@ function retainedTaskChars(task: GoalTask): number {
 export function goalPrompt(goal: GoalRecord, settings?: GoalSettings): string {
 	const fixed = cachedPrompt(goal, settings, "goal", () => buildGoalPrompt(goal, settings));
  const budget = budgetLine(goal);
- return `${fixed}\nUsage: ${formatUsage(goal)}${budget ? `\n${budget}` : ""}`;
+ return `${fixed}\nUsage: ${formatUsage(goal)}${budget ? `\n${budget}` : ""}\n${schedulerSummary(goal.scheduler, settings?.maxAutonomousRuns)}`;
 }
 
 function buildGoalPrompt(goal: GoalRecord, settings?: GoalSettings): string {
@@ -235,7 +238,7 @@ function buildGoalPrompt(goal: GoalRecord, settings?: GoalSettings): string {
  // Bound individual data fields so essential rules can never be sliced off.
  return [
   `[PI GOAL ACTIVE goalId=${goal.id}]`,
-  lifecyclePolicyBlock(), sisyphusDisciplineBlock(goal),
+  lifecyclePolicyBlock(settings?.maxAutonomousRuns !== 0), sisyphusDisciplineBlock(goal),
   `Status: ${statusLabel(goal)}\nMode: ${goal.sisyphus ? "sisyphus" : "regular"}`,
   untrustedObjectiveBlock(goal), taskListBlock(goal, settings), verificationContractBlock(goal, settings),
  ].filter(Boolean).join("\n\n");

package/extensions/widgets/goal-dashboard-model.ts

@@ -1,3 +1,4 @@
+import { schedulerSummary } from "../goal-scheduler-state.ts";
 import { taskIndex } from "../goal-task-index.ts";
 /**
  * Shared dashboard view model (plan §6) — the single source of truth for the
@@ -22,6 +23,7 @@ import { deriveGoalActivity, type GoalActivityItem } from "../goal-activity.ts";
 export type DashboardStatusCode = "running" | "idle" | "paused" | "blocked" | "budget_limited" | "complete";
 
 export interface GoalDashboardModel {
+	scheduling: string[];
 	goalId: string;
 	title: string;
 
@@ -100,6 +102,7 @@ export interface DashboardTaskNode {
 }
 
 export interface GoalDashboardModelOptions {
+	maxAutonomousRuns?: number;
 	focused: boolean;
 	otherOpenGoals: number;
 	ledgerEvents?: readonly GoalLedgerEvent[];
@@ -470,6 +473,7 @@ export function deriveGoalDashboardModel(
 	const { focused, otherOpenGoals, ledgerEvents = [], activityLimit, tasksDisabled = false } = options;
 
 	const status = deriveGoalStatus(goal);
+	if (goal.status === "active" && goal.scheduler?.phase === "waiting") { status.code = "idle"; status.label = "Waiting"; status.footerLabel = "waiting"; }
 	// §9.5: with tasks disabled, omit task sections entirely (status,
 	// verification, usage, path, and focus remain).
  const {taskProgress, taskTree, currentTask, taskTitles} = taskPresentation(goal, tasksDisabled);
@@ -494,6 +498,7 @@ export function deriveGoalDashboardModel(
 	if (goal.usage.tokensUsed > 0) footerUsageBits.push(formatCompactTokens(goal.usage.tokensUsed));
 
 	return {
+		scheduling: schedulerSummary(goal.scheduler, options.maxAutonomousRuns).split("\n"),
 		goalId: goal.id,
 		title: displayObjectiveTitle(goal.objective),
 		status,

package/extensions/widgets/goal-dashboard-renderer.ts

@@ -310,6 +310,8 @@ export function renderCompactDashboard(
 		lines.push(boxLine(theme, safeWidth, statusLine(theme, model)));
 	}
 
+	for (const row of model.scheduling ?? []) lines.push(boxLine(theme, safeWidth, muted(theme, fit(row, inner))));
+
 	// Budget (when configured): fuel gauge + amount, amber until the budget is
 	// exhausted, then soft red.
 	if (model.budget) {
@@ -455,6 +457,7 @@ export function renderExpandedDashboard(
 	lines.push(boxHeader(theme, safeWidth, `${accent(theme, "pi-goal-x")} ${frame(theme, `─ ${model.title}`)}`));
 
 	lines.push(boxLine(theme, safeWidth, statusLine(theme, model)));
+	for (const row of model.scheduling ?? []) lines.push(boxLine(theme, safeWidth, muted(theme, fit(row, inner))));
 
 	if (spec.showPath && model.filePath) {
 		lines.push(boxLine(theme, safeWidth, dim(theme, `File: ${model.filePath}`)));

package/extensions/widgets/goal-widget.ts

@@ -548,6 +548,7 @@ export class GoalWidgetComponent implements Component {
 			otherOpenGoals: otherCount,
 			ledgerEvents: this.getLedgerEvents(),
 			tasksDisabled: settings.disableTasks === true,
+			maxAutonomousRuns: settings.maxAutonomousRuns,
 		}) : null;
 		this.maybeReanchor(model);
 		const lines = renderGoalWidgetLines(this.getGoal(), this.theme, safeWidth, {
@@ -629,6 +630,7 @@ export class GoalWidgetComponent implements Component {
 			otherOpenGoals: Math.max(0, this.getOpenGoalCount() - 1),
 			ledgerEvents: this.getLedgerEvents(),
 			tasksDisabled: settings.disableTasks === true,
+			maxAutonomousRuns: settings.maxAutonomousRuns,
 		}) : null;
 		const list = model?.taskTree.filter((n) => n.depth === 0) ?? [];
 		const rows = compactTaskViewportRows(this.lastRenderWidth);
@@ -663,6 +665,7 @@ export class GoalWidgetComponent implements Component {
 			otherOpenGoals: Math.max(0, this.getOpenGoalCount() - 1),
 			ledgerEvents: this.getLedgerEvents(),
 			tasksDisabled: settings.disableTasks === true,
+			maxAutonomousRuns: settings.maxAutonomousRuns,
 		}) : null;
 		const list = model?.taskTree ?? [];
 		if (list.length === 0) return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-goal-x",
-  "version": "0.31.3",
+  "version": "0.31.4",
   "description": "Adds /goal to pi: conversational goal planning, flexible or ordered goals, persistent progress, and an independent completion auditor.",
   "license": "MIT",
   "author": "pi-goal-x contributors",