@hank-warren/pi-loop 0.7.0 → 0.9.0

package/src/loop.ts

@@ -34,7 +34,13 @@ import {
 	type TickDecision,
 	type TickEnvironment,
 } from "./decide.js";
-import { formatClock, formatDuration, MAX_INTERVAL_MS, parseDuration } from "./interval.js";
+import {
+	formatClock,
+	formatDuration,
+	formatElapsed,
+	MAX_INTERVAL_MS,
+	parseDuration,
+} from "./interval.js";
 import {
 	createLedger,
 	criteriaFromDescriptions,
@@ -65,6 +71,8 @@ import {
 	readPlanModeEnabled,
 	restoreLoopState,
 } from "./state.js";
+import { publishLoopEnv } from "./loop-env.js";
+import { showLoopProposalCard } from "./presentation.js";
 import { isLoopOkAck } from "./ack.js";
 import { calledTool, hasAssistantToolCall, nextNoProgressState } from "./safety.js";
 import { classifyInterruption } from "./errors.js";
@@ -77,7 +85,17 @@ import {
 	type ResolvedWaitDelay,
 } from "./wait.js";
 import { LOOP_COMPLETE_TOOL } from "./complete-tool.js";
-import { clearLoopWidget, updateLoopWidget } from "./widget.js";
+import {
+	buildProposal,
+	type LoopPlanningState,
+	type LoopProposal,
+} from "./planning.js";
+import {
+	clearLoopWidget,
+	loopWidgetLine,
+	type LoopWidgetView,
+	updateLoopWidget,
+} from "./widget.js";
 
 export const LOOP_STATUS_KEY = "loop";
 
@@ -91,6 +109,17 @@ export const LOOP_ANCHOR_MESSAGE_TYPE = "loop-objective";
  */
 export const MAX_FALLBACK_BACKOFF = 4;
 
+/**
+ * How long a single run may stay open before the widget calls it blocked.
+ *
+ * Deliberately generous: a long build, a big test suite, or a deep subagent
+ * fan-out are all legitimately busy for a while, and crying blocked on honest
+ * work would train the signal to be ignored. Fifteen minutes with no completed
+ * turn is well past ordinary work and well short of the seven-day expiry that
+ * would otherwise be the first sign anything was wrong.
+ */
+export const STALL_ATTENTION_MS = 900_000;
+
 /** Consecutive loop deliveries that produce no run before the loop pauses. */
 export const MAX_DEAD_DELIVERIES = 3;
 
@@ -108,6 +137,21 @@ type RunOrigin = "continuation" | "fallback";
  */
 export type LoopStartResult = { ok: true; loop: LoopState } | { ok: false; message: string };
 
+/**
+ * A loop that exists but is not running anywhere: everything `installLoop`
+ * needs, and nothing that presumes which session will install it.
+ */
+export interface BuiltLoop {
+	loop: LoopState;
+	/** The criteria to write at install: proposed, or the deterministic split. */
+	criteria: LoopCriterion[];
+	expiryMs: number;
+	clamped: boolean;
+	requestedMs: number;
+}
+
+export type LoopBuildResult = { ok: true; built: BuiltLoop } | { ok: false; message: string };
+
 interface ContinuationIntent {
 	loopId: string;
 	kind: ContinuationKind;
@@ -154,6 +198,30 @@ export class LoopController {
 	private awaitingRun = false;
 	/** Set when an interrupted turn needs a compaction before the loop continues. */
 	private compactionRequested = false;
+	/**
+	 * When the in-flight run started, or undefined between runs.
+	 *
+	 * A session blocked on a modal prompt — a permission approval, a question,
+	 * anything that waits for a human — is `busy`, and `busy` makes every
+	 * continuation and every fallback tick skip. No turn completes, so the cap
+	 * never trips and the no-progress breaker (which counts turns) never fires.
+	 * Expiry is the only thing left, up to seven days later. The engine cannot
+	 * see the prompt, but it can see that a run has been open far longer than
+	 * work usually takes, which is enough to put an attention state on the
+	 * widget instead of a cheerful next-wake time.
+	 */
+	private busySince: number | undefined;
+	/** How long the current run has been open, once past the stall threshold. */
+	private blockedForMs: number | undefined;
+	/**
+	 * Loop planning: the drafting conversation that precedes a loop.
+	 *
+	 * In-memory on purpose. A draft is a short interactive flow, and persisting
+	 * it would mean a half-written objective could outlive the conversation that
+	 * produced it and be approved later out of context. The loop it becomes is
+	 * persisted; the draft is not.
+	 */
+	planning: LoopPlanningState = { active: false };
 
 	constructor(pi: ExtensionAPI, options: LoopControllerOptions = {}) {
 		this.pi = pi;
@@ -175,6 +243,9 @@ export class LoopController {
 		this.noOpStreak = 0;
 		this.deadDeliveries = 0;
 		this.awaitingRun = false;
+		this.busySince = undefined;
+		this.blockedForMs = undefined;
+		this.planning = { active: false };
 		this.sessionCtx = ctx;
 
 		const loaded = readLoopSettings(this.settingsPath);
@@ -186,6 +257,10 @@ export class LoopController {
 		this.ledger = undefined;
 		this.ledgerWarned = false;
 		this.state = restoreLoopState(ctx.sessionManager.getBranch());
+		// A restored loop is running from this moment, so the signal other
+		// extensions read has to be true again before the first tool call of the
+		// session, not only after the first state change.
+		publishLoopEnv(this.state);
 		if (this.state && this.state.status === "active") {
 			if (this.now() >= this.state.expiresAt) {
 				this.transition("stopped", "loop expired while the session was away");
@@ -198,11 +273,37 @@ export class LoopController {
 			// A wait whose deadline passed while the session was away is due now.
 			this.restoreWaitTimer();
 			this.armFallback();
+			// A loop handed over from another session has never had its first turn.
+			if (this.state.handoff) this.consumeHandoff(ctx);
 		}
 		this.updateWidget();
 	}
 
+	/**
+	 * Take delivery of a loop handed to this session, and start working it.
+	 *
+	 * The flag is cleared first and persisted immediately: a handoff is
+	 * consumed exactly once, and a session that crashed between restoring and
+	 * kicking off must not re-anchor the objective on the next start.
+	 */
+	private consumeHandoff(ctx: ExtensionContext): void {
+		const loop = this.state;
+		if (!loop) return;
+		const { handoff: _handoff, ...rest } = loop;
+		this.state = rest;
+		this.persist();
+		ctx.ui.notify(
+			"Loop started in this session: only the objective crossed over, not the planning conversation. It works from now, continuing at every idle boundary until the criteria are met (loop_complete), a cap is reached, or you run /loop stop.",
+			"info",
+		);
+		this.sendKickoffAnchor(ctx);
+		this.requestContinuation(rest, "kickoff");
+		this.dispatchContinuationIfSettled(ctx);
+	}
+
 	onSessionShutdown(): void {
+		// Withdraw the signal: the process may outlive this session.
+		publishLoopEnv(undefined);
 		this.clearTimer();
 		this.waitTimer.clear();
 		this.wakePending = false;
@@ -224,11 +325,16 @@ export class LoopController {
 		this.sessionCtx = ctx;
 		this.awaitingRun = false;
 		this.deadDeliveries = 0;
+		this.busySince = this.now();
+		this.blockedForMs = undefined;
 	}
 
 	onAgentEnd(ctx: ExtensionContext, messages: readonly unknown[] = []): void {
 		this.sessionCtx = ctx;
 		this.awaitingRun = false;
+		// A completed turn is proof the session was not blocked on a human.
+		this.busySince = undefined;
+		this.blockedForMs = undefined;
 		const origin = this.runOrigin;
 		this.runOrigin = undefined;
 		const loop = this.state;
@@ -601,6 +707,20 @@ export class LoopController {
 		this.ledger = paths;
 	}
 
+	/**
+	 * Write a built loop's ledger without installing the loop.
+	 *
+	 * The fresh-session launch needs the approved criteria on disk *before* the
+	 * new session restores the state, because the restore path treats an
+	 * existing `criteria.json` as authoritative and would otherwise re-derive
+	 * its own. Returns a failure detail, or undefined on success.
+	 */
+	prepareLedgerFor(built: BuiltLoop): string | undefined {
+		const objective = built.loop.objective;
+		if (objective === undefined) return "the loop has no objective";
+		return createLedger(ledgerPaths(built.loop.id, this.agentDir), objective, built.criteria);
+	}
+
 	/** The loop's criteria as last written to disk, fail-open. */
 	criteria() {
 		return this.ledger ? readCriteria(this.ledger) : undefined;
@@ -744,6 +864,13 @@ export class LoopController {
 					// Busy or compacting: coalesce into one pending wake that
 					// the next agent_settled (or compaction onComplete) delivers.
 					this.wakePending = true;
+					if (decision.reason === "agent-busy") this.noteBusyTick(env.now);
+					// Keep the heartbeat armed while busy. Coalescing is about
+					// deliveries, not about the timer: wakePending is a boolean, so a
+					// further tick cannot produce a second wake. Without re-arming,
+					// the first busy tick would be the last one ever taken, and a
+					// session blocked on a prompt would never be noticed at all.
+					this.armFallback();
 				}
 				this.updateWidget();
 				return;
@@ -934,47 +1061,69 @@ export class LoopController {
 
 	persist(): void {
 		if (!this.state) return;
+		// Every state change funnels through here, which makes it the one place
+		// the loop-active signal can be published without a caller remembering to.
+		publishLoopEnv(this.state);
 		this.pi.appendEntry(LOOP_STATE_ENTRY_TYPE, { loop: this.state });
 	}
 
-	updateWidget(): void {
-		const ui = this.sessionCtx?.ui;
-		if (!ui) return;
+	/**
+	 * A run has been open past the stall threshold, so the most likely
+	 * explanation is a prompt waiting for a human. Reported, never acted on:
+	 * approving on the user's behalf is exactly the boundary pi-auto-permissions
+	 * exists to hold.
+	 */
+	private noteBusyTick(now: number): void {
+		const since = this.busySince;
+		if (since === undefined) return;
+		const openFor = now - since;
+		this.blockedForMs = openFor >= STALL_ATTENTION_MS ? openFor : undefined;
+	}
+
+	/**
+	 * The view both surfaces render, or undefined when there is nothing to show.
+	 *
+	 * One function feeds the widget and the footer because two hand-rolled
+	 * formatters drifted: the footer handled `loop.waiting` and the widget did
+	 * not, so a loop blocked on CI read as an ordinary scheduled loop above the
+	 * editor while the footer said it was waiting.
+	 */
+	widgetView(): LoopWidgetView | undefined {
 		const loop = this.state;
-		updateLoopWidget(
-			ui,
-			loop ? { loop, wakePending: this.wakePending, nextWakeAt: this.nextWakeAt } : undefined,
-		);
 		if (!loop || loop.status === "stopped") {
-			ui.setStatus(LOOP_STATUS_KEY, undefined);
-			return;
+			if (!this.planning.active) return undefined;
+			const proposed = this.planning.proposal?.criteria.length;
+			return { kind: "planning", ...(proposed === undefined ? {} : { proposedCriteria: proposed }) };
 		}
-		if (loop.status === "paused") {
-			ui.setStatus(
-				LOOP_STATUS_KEY,
-				loop.pauseCause ? `loop paused · ${loop.pauseCause}` : "loop paused",
-			);
-			return;
-		}
-		if (loop.waiting) {
-			ui.setStatus(
-				LOOP_STATUS_KEY,
-				`loop waiting · ${loop.waiting.reason}${
-					loop.waiting.resumeAt ? ` · until ${formatClock(loop.waiting.resumeAt)}` : ""
-				}`,
-			);
-			return;
-		}
-		const cap = loop.maxTurns === null ? "∞" : `${loop.maxTurns}`;
-		const next = this.wakePending
-			? "next on idle"
-			: this.nextWakeAt
-				? `next ${formatClock(this.nextWakeAt)}`
-				: "next unscheduled";
-		ui.setStatus(
-			LOOP_STATUS_KEY,
-			`loop ${formatDuration(loop.intervalMs)} · ${loop.automaticTurns}/${cap} · ${next}`,
-		);
+		const criteria = this.criteriaProgress();
+		return {
+			kind: "loop",
+			loop,
+			wakePending: this.wakePending,
+			nextWakeAt: this.nextWakeAt,
+			...(criteria ? { criteria } : {}),
+			...(this.blockedForMs === undefined ? {} : { blockedForMs: this.blockedForMs }),
+			now: this.now(),
+		};
+	}
+
+	/**
+	 * Criteria progress for the widget. Re-read rather than cached: this runs on
+	 * discrete state transitions, not per frame, and a stale count right after a
+	 * criterion is marked would undercut the one number the line exists to show.
+	 */
+	private criteriaProgress(): { met: number; total: number } | undefined {
+		const criteria = this.criteria();
+		if (!criteria || criteria.length === 0) return undefined;
+		return { met: criteria.filter((criterion) => criterion.passes).length, total: criteria.length };
+	}
+
+	updateWidget(): void {
+		const ui = this.sessionCtx?.ui;
+		if (!ui) return;
+		const view = this.widgetView();
+		updateLoopWidget(ui, view);
+		ui.setStatus(LOOP_STATUS_KEY, view ? loopWidgetLine(view) : undefined);
 	}
 
 	statusLines(ctx: ExtensionContext): string[] {
@@ -1023,7 +1172,11 @@ export class LoopController {
 			}
 		}
 		if (loop.prompt) lines.push(`Focus: ${loop.prompt}`);
-		if (this.nextWakeAt && loop.status === "active") {
+		// A pending wake is delivered at the next settle, whatever the timer says.
+		// The heartbeat stays armed while the agent is busy so a stalled session is
+		// still noticed, which means nextWakeAt can be set here even though no wake
+		// will fire at that time — claiming it would be a stale clock time.
+		if (this.nextWakeAt && !this.wakePending && loop.status === "active") {
 			lines.push(
 				`Next fallback wake: ${formatClock(this.nextWakeAt)}${
 					this.noOpStreak > 0
@@ -1043,15 +1196,91 @@ export class LoopController {
 		return lines;
 	}
 
+	// --- planning ---
+
+	/**
+	 * Open the drafting conversation. Idempotent: running /loop again while
+	 * planning shows the current draft rather than restarting the flow.
+	 */
+	beginPlanning(): void {
+		this.planning = { active: true };
+		this.updateWidget();
+	}
+
+	/** Record a drafted loop for approval, replacing any previous draft. */
+	propose(
+		objective: string,
+		overrides: { intervalMs?: number; maxTurns?: number | null; expiresInMs?: number } = {},
+	): LoopProposal {
+		const proposal = buildProposal(
+			objective,
+			{
+				intervalMs: parseDuration(this.settings.defaultInterval) ?? 600_000,
+				maxTurns: this.settings.maxTurns,
+				expiresInMs: parseDuration(this.settings.maxLoopDuration) ?? 604_800_000,
+			},
+			this.now(),
+			overrides,
+		);
+		// A new draft supersedes the last one, so the card that was shown for the
+		// old draft no longer describes what would start.
+		this.planning = { active: true, proposal };
+		this.updateWidget();
+		return proposal;
+	}
+
+	/**
+	 * Render the current draft's approval card, at most once per draft.
+	 *
+	 * Called by `loop_propose` when the draft is created and by `/loop` when the
+	 * user reopens the actions, so the card is present whichever way they got
+	 * here without a second copy appearing when they got here both ways.
+	 */
+	showProposalCard(ctx: ExtensionContext): boolean {
+		const proposal = this.planning.proposal;
+		if (!proposal) return false;
+		if (this.planning.cardShownAt === proposal.proposedAt) return false;
+		if (!showLoopProposalCard(this.pi, ctx, proposal)) return false;
+		this.planning = { ...this.planning, cardShownAt: proposal.proposedAt };
+		return true;
+	}
+
+	endPlanning(): void {
+		this.planning = { active: false };
+		this.updateWidget();
+	}
+
 	// --- command actions ---
 
 	/**
 	 * Start a loop on its own objective, the only mode there is: the trailing
 	 * text *is* what the loop works on and what `loop_complete` answers for.
 	 * With no text there is nothing to work on, and the caller is told so.
+	 *
+	 * Build and install are separate below, and this is the two of them in the
+	 * order they have always run. The split exists because "construct a loop"
+	 * and "make this session the one running it" were one indivisible pass, and
+	 * a fresh-session launch needs the first without the second: the state has
+	 * to exist before `ctx.newSession` so its `setup` can append it to the new
+	 * session, and it must not be installed here or the launching session would
+	 * start working the objective it is handing away.
 	 */
 	startLoop(ctx: ExtensionContext, start: LoopStartArguments): LoopStartResult {
 		this.sessionCtx = ctx;
+		const built = this.buildLoop(start);
+		if (!built.ok) return built;
+		return this.installLoop(ctx, built.built);
+	}
+
+	/**
+	 * Construct a loop's state and criteria without installing anything.
+	 *
+	 * Pure with respect to the session: no `this.state`, no ledger on disk, no
+	 * timer, no widget, no message. Everything it reads (settings, the clock,
+	 * the tool set) is read-only, so a caller may build a loop it intends to
+	 * install somewhere else — or discard.
+	 */
+	buildLoop(start: LoopStartArguments): LoopBuildResult {
 		const now = this.now();
 		const objective = start.prompt?.trim();
 		if (!objective) {
@@ -1078,7 +1307,7 @@ export class LoopController {
 				: this.settings.compaction.enabled
 					? this.settings.compaction.threshold
 					: null;
-		const started: LoopState = {
+		const loop: LoopState = {
 			id: randomUUID().slice(0, 8),
 			status: "active",
 			objective,
@@ -1090,23 +1319,44 @@ export class LoopController {
 			startedAt: now,
 			expiresAt: now + expiryMs,
 		};
+		return {
+			ok: true,
+			built: {
+				loop,
+				criteria: start.criteria
+					? criteriaFromDescriptions(start.criteria)
+					: deriveCriteria(objective),
+				expiryMs,
+				clamped: start.clamped,
+				requestedMs: start.requestedMs,
+			},
+		};
+	}
+
+	/**
+	 * Install a built loop into `ctx`'s session: adopt it as the live state,
+	 * open its ledger, persist, arm the fallback, anchor the objective and kick
+	 * off the first turn. This is the half that makes a session *the* session
+	 * running the loop, and it is the half a fresh-session launch runs over
+	 * there rather than here.
+	 */
+	installLoop(ctx: ExtensionContext, built: BuiltLoop): LoopStartResult {
+		this.sessionCtx = ctx;
+		const started = built.loop;
 		this.state = started;
 		this.wakePending = false;
 		this.continuationIntent = undefined;
 		this.noOpStreak = 0;
 		this.ledgerWarned = false;
-		this.openLedger(
-			this.state,
-			start.criteria ? criteriaFromDescriptions(start.criteria) : deriveCriteria(objective),
-		);
+		this.openLedger(started, built.criteria);
 		this.persist();
-		this.scheduleTick(start.intervalMs);
+		this.scheduleTick(started.intervalMs);
 		this.updateWidget();
-		const clampNote = start.clamped
-			? ` (requested ${formatDuration(start.requestedMs)}, clamped to the ${formatDuration(start.intervalMs)} minimum)`
+		const clampNote = built.clamped
+			? ` (requested ${formatDuration(built.requestedMs)}, clamped to the ${formatDuration(started.intervalMs)} minimum)`
 			: "";
 		ctx.ui.notify(
-			`Loop started: working its objective from now, continuing at every idle boundary until the criteria are met (loop_complete), a cap is reached, or you run /loop stop. Fallback wake every ${formatDuration(start.intervalMs)}${clampNote} if the session goes quiet. Expires in ${formatDuration(expiryMs)} (one final turn to write its state down, then it stops).`,
+			`Loop started: working its objective from now, continuing at every idle boundary until the criteria are met (loop_complete), a cap is reached, or you run /loop stop. Fallback wake every ${formatDuration(started.intervalMs)}${clampNote} if the session goes quiet. Expires in ${formatDuration(built.expiryMs)} (one final turn to write its state down, then it stops).`,
 			"info",
 		);
 		if (this.ledger) {
@@ -1131,6 +1381,8 @@ export class LoopController {
 		return { ok: true, loop: started };
 	}
 
+
+
 	/**
 	 * Store the objective as an ordinary message so it outlives the loop.
 	 *

package/src/manager.ts

@@ -14,6 +14,10 @@ import {
 	saveLoopSettings,
 } from "./settings.js";
 import { parseDuration } from "./interval.js";
+import type { LoopStartArguments } from "./command.js";
+import { startLoopInFreshSession } from "./fresh-launch.js";
+import { showLoopApprovalMenu } from "./loop-action-menus.js";
+import type { LoopProposal } from "./planning.js";
 
 export async function showLoopManager(
 	controller: LoopController,
@@ -266,3 +270,125 @@ function applySettings(
 	controller.settings = next;
 	return true;
 }
+
+/**
+ * The approval card and its actions.
+ *
+ * This is where a planned loop starts, and the approval is what authorises it.
+ * `loop_start`'s gate exists because a loop is self-continuing and must never
+ * begin on model initiative; an explicit choice here, on a card showing the
+ * objective, the derived criteria, the cadence and the caps, is stronger
+ * evidence of intent than a typed token, so it starts the loop directly rather
+ * than routing back through a tool the model could reach on its own.
+ */
+export async function showLoopApproval(
+	controller: LoopController,
+	ctx: ExtensionCommandContext,
+): Promise<void> {
+	const proposal = controller.planning.proposal;
+	if (!proposal) return;
+	// The card is an artifact, emitted once per draft; the menu below is the
+	// dialog over it. A draft proposed by loop_propose already has its card, so
+	// this only renders one when the user reached the approval some other way.
+	controller.showProposalCard(ctx);
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify(
+			"Approve it from a TUI session, or start it directly with /loop <interval> <objective>.",
+			"info",
+		);
+		return;
+	}
+	await showLoopApprovalMenu(ctx, {
+		proposal,
+		startHere: () => {
+			const result = controller.startLoop(ctx, startArgumentsFor(proposal));
+			if (result.ok) controller.endPlanning();
+			else ctx.ui.notify(result.message, "error");
+		},
+		startFresh: async () => {
+			await startApprovedLoopFresh(controller, ctx, proposal);
+		},
+		changeCadence: async () => {
+			await changeCadence(controller, ctx, proposal);
+		},
+		keepEditing: () => {
+			ctx.ui.notify("Still planning. Tell the agent what to change.", "info");
+		},
+		cancel: () => {
+			controller.endPlanning();
+			ctx.ui.notify("Loop planning cancelled. Nothing was started.", "info");
+		},
+	});
+}
+
+/** The approved draft, as the arguments both start paths take. */
+function startArgumentsFor(proposal: LoopProposal): LoopStartArguments {
+	return {
+		kind: "start",
+		requestedMs: proposal.intervalMs,
+		intervalMs: proposal.intervalMs,
+		clamped: false,
+		maxTurns: proposal.maxTurns,
+		expiresInMs: proposal.expiresInMs,
+		prompt: proposal.objective,
+	};
+}
+
+/**
+ * Build the loop here, install it over there. The build/install split is what
+ * makes this possible at all: the state has to exist before `newSession` so
+ * its `setup` can append it, and it must not be installed in this session or
+ * the planning session would start working the objective it is handing away.
+ */
+async function startApprovedLoopFresh(
+	controller: LoopController,
+	ctx: ExtensionCommandContext,
+	proposal: LoopProposal,
+): Promise<void> {
+	const built = controller.buildLoop(startArgumentsFor(proposal));
+	if (!built.ok) {
+		ctx.ui.notify(built.message, "error");
+		return;
+	}
+	const result = await startLoopInFreshSession(ctx, {
+		built: built.built,
+		prepareLedger: () => controller.prepareLedgerFor(built.built),
+	});
+	switch (result.kind) {
+		case "started":
+		case "partial":
+			// The draft has been handed off either way: the planning session must
+			// not keep offering to start it a second time.
+			controller.endPlanning();
+			return;
+		case "cancelled":
+			return;
+		default:
+			ctx.ui.notify(result.detail, "error");
+	}
+}
+
+async function changeCadence(
+	controller: LoopController,
+	ctx: ExtensionCommandContext,
+	proposal: LoopProposal,
+): Promise<void> {
+	const text = await ctx.ui.input(
+		"Fallback heartbeat (e.g. 30m). The loop advances whenever the session settles.",
+		formatDuration(proposal.intervalMs),
+	);
+	if (text === undefined) return;
+	const interval = parseInterval(text.trim());
+	if (!interval) {
+		ctx.ui.notify(`Invalid interval: ${text}. Use <number><unit>, e.g. 30m.`, "error");
+		return;
+	}
+	// A new draft, so it gets a new card: the cadence on the old one is no
+	// longer what would start.
+	controller.propose(proposal.objective, {
+		intervalMs: interval.effectiveMs,
+		maxTurns: proposal.maxTurns,
+		expiresInMs: proposal.expiresInMs,
+	});
+	await showLoopApproval(controller, ctx);
+}

package/src/objective.ts

@@ -44,6 +44,28 @@ export function buildLoopObjectivePrompt(
 		"- Effort exhaustion is not completion. Running long, running out of ideas, or approaching a cap is never a reason to call loop_complete.",
 		"- Call loop_complete with this exact loop_id only when every completion criterion is proven, passing one cited piece of evidence per criterion id. It stops the wakeups; it does not assert that unrelated work is finished.",
 		"- If the criteria are not met, keep working and expect another wake.",
+		// Autonomy. Stated as mechanics rather than as a rule to obey, because the
+		// mechanics are the reason: a blocked session is `busy`, and `busy` makes
+		// every continuation and every fallback tick skip. Nothing enumerates
+		// tools here on purpose — the user's other extensions are unknowable, and
+		// a blacklist would go stale the moment one of them ships a new prompt.
+		"- You are running unattended. A prompt that blocks on a human — a permission approval, a clarifying question, any tool that waits for an answer — does not pause this loop, it deadlocks it: the session stays busy, so no continuation fires, no wake lands, and no cap trips. Nothing ends the loop until it expires. Plan to work without prompting.",
+		"- Decide rather than ask. Take the reversible option, record the decision and the reasoning behind it in the ledger, and keep going. A decision written down is worth more than a question nobody is there to answer.",
+		"- When you genuinely need a human, call loop_wait: it is the only way to ask that does not deadlock the session. Put the options in the ledger first, so the answer can be one word.",
+		// The old wording forbade reshaping a blocked command outright, and a
+		// permission guardian that blocks with a stated concern depends on exactly
+		// that: its block is an instruction to fix the named problem. Both cannot
+		// stand, and "never reshape" is the one that was wrong — it made every
+		// block terminal, including the ones that named a one-word fix. The line
+		// that matters is not whether the command changes but what the change is
+		// aimed at: satisfying the concern, or getting around the gate that raised
+		// it. So the prohibition is stated against the aim, and the number of
+		// attempts is bounded so that "revise to address it" cannot decay into
+		// "retry until it passes".
+		"- Never reshape a command to get around a permission gate. Splitting it up, obfuscating it, routing it through another tool, or retrying variations until one is allowed are all the same move, and it is forbidden however the loop is going.",
+		"- A block that states a concern is different: it names something to fix, and fixing exactly that is legitimate. Revise only to satisfy the stated concern, and only while the block says rounds remain against it. When they run out, the block will say so — stop revising and call loop_wait.",
+		"- A block that states no concern, or one you cannot address without widening what the command does, is already final. Do not spend the rounds; call loop_wait.",
+		"- Prefer the undoable. Nobody is watching to catch a bad call, so when two paths are close, take the one that is cheap to reverse.",
 		...(ledger ? ledgerRules(ledger) : []),
 		`${focus}`,
 	]
@@ -63,8 +85,9 @@ function ledgerRules(ledger: LedgerPaths): string[] {
 	return [
 		"",
 		`Loop ledger (durable state for this loop, at ${ledger.dir}):`,
-		`- ${PROGRESS_FILE} is yours to maintain. Update it as you work, keeping its four sections: current status, completed, failed approaches and why, next actions. Record failures and their reasons — nothing else remembers them once the conversation is compacted.`,
-		`- ${CRITERIA_FILE} holds this loop's completion criteria. You may change only the \`passes\` field of an entry, and only when authoritative evidence proves that criterion, citing the evidence in ${PROGRESS_FILE}. Never edit an id, description, or check, and never add or remove entries.`,
+		`- ${PROGRESS_FILE} is yours to maintain, keeping its four sections: current status, completed, failed approaches and why, next actions. Record failures and their reasons as you go — nothing else remembers them once the conversation is compacted.`,
+		`- Write it with the loop_progress tool and never with the file or shell tools: loop_progress edits one section and leaves every other byte alone, where a whole-file write destroys the objective line and the other three sections along with the one you meant to update.`,
+		`- ${CRITERIA_FILE} holds this loop's completion criteria. Mark one met with loop_progress, which stores the citation next to it; only the \`passes\` field ever changes. Never edit an id, description, or check, never add or remove entries, and never write this file by hand.`,
 		"- After a compaction, re-read both files before acting. They are the record; a summary is not.",
 	];
 }