@hank-warren/pi-loop 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @hank-warren/pi-loop
 
+## 0.9.0
+
+### Minor Changes
+
+- 897739d: Framed approval card, fresh-session launch, and a loop-safe permission posture.
+
+  **pi-loop**
+
+  - The approval card is now a framed `customType` transcript block, emitted once per draft, with its choices in an action menu. It used to go out twice and neither copy was a card: `loop_propose` returned it as tool-result markdown (re-spending the objective's tokens in the model's own context) and `/loop` re-printed it as a toast.
+  - `startLoop` is split into `buildLoop` and `installLoop`, and the menu gains **Start loop in a fresh session** — the loop is built in the planning session and installed in a new one, so only the objective crosses and the drafting conversation does not.
+  - A loop publishes `PI_LOOP_ACTIVE=1` and `PI_LOOP_ID` on the process while active. This is a contract for other extensions, mirroring `PI_SUBAGENT_CHILD`: no import, no dependency, no RPC.
+  - The autonomy posture is reconciled with it. Reshaping a command to get _around_ a permission gate stays forbidden; revising it to satisfy a concern a guardian actually stated is legitimate and bounded. The `⚠ loop blocked` detector is unchanged.
+
+  **pi-auto-permissions**
+
+  - While `PI_LOOP_ACTIVE=1`, an `ask_user` verdict returns the guardian's concern to the agent as a non-blocking block instead of opening a modal. A session waiting on a modal is busy, and a busy session starves a loop's continuation path — the prompt would not be answered, it would deadlock the loop until it expired. **The verdict is unchanged; only its delivery is.** The absence of a user is never authorization.
+  - Revision is bounded — per concern, per gate, and by consecutive blocked attempts — after which the block names `loop_wait` instead of inviting another try. The bounds survive a compaction and a session restore.
+
+  Detection is fail-open in both directions: with the environment variables absent, behaviour is exactly as before, and neither package requires the other.
+
 ## 0.8.0
 
 ### Minor Changes

package/README.md

@@ -128,6 +128,23 @@ The turn a wake delivers for an elapsed wait **counts against `maxTurns`** like
 
 There is deliberately **no cancel tool**. The events that legitimately cancel a wait (you typing, an earlier wake arriving) are not the model's to report — so when one of them ends a wait, its reason rides along once on the next loop message as `Previous wait (cancelled): …` and is then dropped.
 
+## Working unattended, and the `PI_LOOP_ACTIVE` contract
+
+The posture in the system append is stated as mechanics rather than as rules to obey, because the mechanics are the reason: a session waiting on a modal is *busy*, and busy makes every continuation and every fallback tick skip. Nothing ends the loop until it expires. So: decide rather than ask, take the reversible path, record the decision in the ledger, and use `loop_wait` — the one way to ask that does not deadlock the session.
+
+The subtle half is what to do with a *blocked* command. Reshaping one to get **around** a permission gate — splitting it up, obfuscating it, routing it through another tool, retrying variations until one is allowed — is forbidden outright, and it is the dangerous failure precisely because it *looks like progress*. But a guardian that blocks with a specific objection is naming something to fix, and fixing exactly that is the response it asked for. Treating every block as terminal would have made the loop stop at objections that named a one-word remedy.
+
+What separates the two is a bound, which is why pi-loop publishes its state to the process while a loop is active:
+
+| Variable | Meaning |
+| --- | --- |
+| `PI_LOOP_ACTIVE` | `1` while a loop is active; absent otherwise (a paused or stopped loop withdraws it) |
+| `PI_LOOP_ID` | the loop's id, so a reader can tell one loop from the next |
+
+This is a contract for other extensions, deliberately the same mechanism `pi-subagents` established with `PI_SUBAGENT_CHILD=1` — an environment variable, not an import, not a dependency, not an RPC. [pi-auto-permissions](https://github.com/hank-warren/pi-extensions/tree/main/packages/pi-auto-permissions) is the first consumer: while it is set, a guardian verdict that would have opened a modal instead returns the concern to the agent as a block, carrying a bounded number of revision rounds and then naming `loop_wait`. Nothing is approved that would not have been approved with a user present; only the delivery changes. Neither package needs the other installed, in either direction.
+
+The `⚠ loop blocked` widget state remains, unchanged, as the backstop: it catches prompts from extensions pi-loop cannot influence, where there is no contract to read.
+
 ## Breakers
 
 - **No progress.** The characteristic failure of an autonomous loop is not crashing, it is *restating*: the same paragraph of "here is what I would do next", turn after turn, calling no tools. pi-loop fingerprints the visible assistant text (SHA-256 over NFKC-normalised, case- and whitespace-folded text) of every tool-free loop-caused turn; `noProgressTurns` consecutive repeats (default 3, settings-tunable, `null` disables) **pause** the loop rather than stopping it — it stays configured, the widget says why, and `/loop resume` or your next message continues it with a fresh safety epoch. A turn that called **any** tool, including `loop_wait`, is progress by definition and resets the counter; counting a declared wait is the false positive that made this class of breaker infamous.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-loop",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Long-running work for Pi: settle-paced loops with a durable ledger, adaptive waits, no-progress breakers, evidence-gated completion, and a task scheduler.",
   "type": "module",
   "keywords": [
@@ -47,5 +47,8 @@
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
+  },
+  "dependencies": {
+    "@narumitw/pi-tui-kit": "^0.49.3"
   }
 }

package/skills/pi-loop/SKILL.md

@@ -98,10 +98,19 @@ The rule follows from the mechanics instead:
    that does not deadlock: continuations stop, the reason shows in the widget and `/loop status`,
    and any wake resumes it. Use it exactly where you would otherwise open a modal, and put the
    options in the ledger first so the answer can be one word.
-3. **Never reshape a command to get past a permission prompt.** This is the dangerous one. An
+3. **Never reshape a command to get *around* a permission gate.** This is the dangerous one. An
    agent under a turn cap has real incentive to rewrite a blocked command into something the
-   guardian waves through, and that failure *looks like progress*. A blocked command means stop
-   and ask through `loop_wait` — never find another way around it.
+   guardian waves through, and that failure *looks like progress*. Splitting the command up,
+   obfuscating it, routing it through a different tool, or simply retrying variations until one
+   is allowed are all the same move, whatever the loop's state.
+
+   Addressing a stated concern is not that move. A guardian that blocks with a specific
+   objection — pi-auto-permissions does exactly this while `PI_LOOP_ACTIVE=1`, because a modal
+   would deadlock the loop — is naming something to fix, and fixing precisely that is the
+   response it asked for. The bound is what keeps the two apart: the block tells you how many
+   revision rounds remain against that concern, and when they run out it stops offering the
+   option and names `loop_wait` instead. A block that states no concern you can address is
+   already final; do not spend the rounds on it.
 4. **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: a worktree over the clone, additive over destructive, a
    draft pull request over a merge.

package/src/fresh-launch.ts

@@ -0,0 +1,128 @@
+/**
+ * Starting an approved loop in a fresh session.
+ *
+ * A loop started interactively owns the session it was planned in, and the
+ * planning conversation is the worst possible context for it: every turn of
+ * drafting is carried, re-read and re-billed for the whole run, and none of it
+ * is the objective. The card is where that gets fixed, because the card is
+ * where the user is already deciding how the loop should run.
+ *
+ * Modelled on `packages/pi-plan-mode/src/fresh-implementation.ts`, which
+ * solves the same problem for a plan. The difference is what crosses: a plan
+ * hands over a file path, while a loop hands over its state, appended to the
+ * new session in `setup` exactly as `persist` would have appended it here.
+ * Only the objective and the caps cross; the drafting conversation does not.
+ *
+ * The ledger is written before the handoff, from this session. It is a
+ * filesystem artifact keyed by loop id, not session state, and writing it here
+ * is what makes the approved criteria authoritative: the restoring session
+ * treats whatever is already on disk as the truth, so criteria written after
+ * it restores would arrive too late to be the ones it is held to.
+ */
+
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { BuiltLoop } from "./loop.js";
+import { LOOP_STATE_ENTRY_TYPE } from "./state.js";
+
+type NewSessionOptions = Exclude<Parameters<ExtensionCommandContext["newSession"]>[0], undefined>;
+type SessionManagerLike = Parameters<NonNullable<NewSessionOptions["setup"]>>[0];
+
+export type FreshLoopResult =
+	| { kind: "started" }
+	| { kind: "cancelled" }
+	/** The session exists and holds the loop, but it could not be kicked off. */
+	| { kind: "partial"; detail: string }
+	| { kind: "rejected"; detail: string };
+
+export interface FreshLoopRequest {
+	built: BuiltLoop;
+	/** Write the ledger for `built` before the handoff; returns a failure detail. */
+	prepareLedger(): string | undefined;
+}
+
+export async function startLoopInFreshSession(
+	ctx: ExtensionContext,
+	request: FreshLoopRequest,
+): Promise<FreshLoopResult> {
+	if (!isCommandContext(ctx)) {
+		return {
+			kind: "rejected",
+			detail:
+				"Starting a loop in a fresh session needs the interactive /loop command. Run /loop again and choose it from the menu.",
+		};
+	}
+	if (ctx.mode === "print" || ctx.mode === "json") {
+		return {
+			kind: "rejected",
+			detail: "A fresh session is unavailable in print/JSON mode. Start the loop in this session.",
+		};
+	}
+
+	const ledgerFailure = request.prepareLedger();
+	if (ledgerFailure) {
+		// Not fatal to the loop — a loop runs without a ledger — but it is fatal
+		// to *this* path: the new session would derive its own criteria from the
+		// objective and could be held to a different gate than the one approved.
+		return {
+			kind: "rejected",
+			detail: `The loop's ledger could not be written (${ledgerFailure}), so the approved criteria could not be handed to a new session. Start the loop in this session instead.`,
+		};
+	}
+
+	await ctx.waitForIdle();
+
+	const parentSession = ctx.sessionManager.getSessionFile();
+	let setupError: string | undefined;
+
+	let result: Awaited<ReturnType<ExtensionCommandContext["newSession"]>>;
+	try {
+		result = await ctx.newSession({
+			...(parentSession ? { parentSession } : {}),
+			setup: async (sessionManager: SessionManagerLike) => {
+				try {
+					// The same entry `persist` writes, so the new session's ordinary
+					// restore path picks it up with no special case — plus the handoff
+					// flag, which is what tells that session it owns the first turn.
+					// The kickoff cannot be driven from here: Pi builds a new extension
+					// instance for the new session, so this session's controller is not
+					// the one that ends up holding the loop.
+					sessionManager.appendCustomEntry(LOOP_STATE_ENTRY_TYPE, {
+						loop: { ...request.built.loop, handoff: true },
+					});
+				} catch (error: unknown) {
+					setupError = errorDetail(error);
+				}
+			},
+			withSession: async (replacementCtx: ExtensionContext) => {
+				if (setupError) {
+					replacementCtx.ui.notify(
+						`Fresh session created, but the loop could not be handed to it: ${setupError}. Nothing is running; start the loop from /loop in either session.`,
+						"error",
+					);
+				}
+			},
+		});
+	} catch (error: unknown) {
+		return {
+			kind: "rejected",
+			detail: `Unable to start a fresh session: ${errorDetail(error)}. The draft is unchanged; start the loop in this session instead.`,
+		};
+	}
+
+	if (result.cancelled) return { kind: "cancelled" };
+	return setupError ? { kind: "partial", detail: setupError } : { kind: "started" };
+}
+
+function isCommandContext(ctx: ExtensionContext): ctx is ExtensionCommandContext {
+	return typeof (ctx as Partial<ExtensionCommandContext>).newSession === "function";
+}
+
+function errorDetail(error: unknown) {
+	const detail = error instanceof Error ? error.message : String(error);
+	const normalized =
+		detail
+			.replace(/[\u0000-\u001f\u007f-\u009f]/gu, " ")
+			.replace(/\s+/gu, " ")
+			.trim() || "unknown error";
+	return normalized.length > 500 ? `${normalized.slice(0, 499)}…` : normalized;
+}

package/src/loop-action-menus.ts

@@ -0,0 +1,129 @@
+/**
+ * The approval card's actions, as a menu.
+ *
+ * Presentation and choices are separate surfaces on purpose, the way
+ * pi-plan-mode splits `presentation.ts` from `plan-action-menus.ts`: the card
+ * is a durable artifact in the transcript that the user can scroll back to,
+ * and the menu is a transient dialog over it. A plain `ui.select` of label
+ * strings could not say what "start in a fresh session" means, and that is
+ * exactly the entry that needs explaining.
+ *
+ * The screen is built by a pure function so a test can assert what the menu
+ * offers without a terminal.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
+import type { ActionsScreen } from "@narumitw/pi-tui-kit";
+import { formatDuration } from "./interval.js";
+import type { LoopProposal } from "./planning.js";
+
+export type LoopApprovalAction =
+	| "start-here"
+	| "start-fresh"
+	| "change-cadence"
+	| "keep-editing"
+	| "cancel";
+
+type Screen = "approval";
+
+export interface LoopApprovalMenuOptions {
+	proposal: LoopProposal;
+	signal?: AbortSignal;
+	isCurrent?(): boolean;
+	startHere(): void | Promise<void>;
+	startFresh(signal: AbortSignal): void | Promise<void>;
+	changeCadence(): void | Promise<void>;
+	keepEditing(): void;
+	cancel(): void;
+}
+
+/**
+ * The approval screen. Pure and exported for tests: the set of actions on
+ * offer is the contract, and it is cheaper to pin here than through a TUI.
+ */
+export function loopApprovalScreen(
+	proposal: LoopProposal,
+): ActionsScreen<Screen, LoopApprovalAction> {
+	const criteria = `${proposal.criteria.length} ${proposal.criteria.length === 1 ? "criterion" : "criteria"}`;
+	return {
+		kind: "actions",
+		title: "Start this loop?",
+		lines: [
+			`${criteria} · fallback wake every ${formatDuration(proposal.intervalMs)} · turn cap ${proposal.maxTurns === null ? "unlimited" : proposal.maxTurns} · expires in ${formatDuration(proposal.expiresInMs)}`,
+			"The card above shows exactly what loop_complete will be held to.",
+		],
+		items: [
+			{
+				id: "start-here",
+				label: "Start loop here",
+				description: "Run it in this session, keeping the planning conversation.",
+				action: "start-here",
+			},
+			{
+				id: "start-fresh",
+				label: "Start loop in a fresh session",
+				description:
+					"Open a new session that runs the loop with only the objective — no planning history.",
+				action: "start-fresh",
+				busyLabel: "Starting the loop in a fresh session…",
+			},
+			{
+				id: "change-cadence",
+				label: "Change cadence…",
+				description: "Edit the fallback heartbeat before starting.",
+				action: "change-cadence",
+			},
+			{
+				id: "keep-editing",
+				label: "Keep editing",
+				description: "Go back to drafting; tell the agent what to change.",
+				action: "keep-editing",
+			},
+			{
+				id: "cancel",
+				label: "Cancel",
+				description: "Discard the draft. Nothing is started.",
+				action: "cancel",
+			},
+		],
+		hint: "close",
+	};
+}
+
+export async function showLoopApprovalMenu(
+	ctx: ExtensionContext,
+	options: LoopApprovalMenuOptions,
+) {
+	const menu = defineMenu<undefined, Screen, LoopApprovalAction, ExtensionContext>({
+		start: "approval",
+		screens: { approval: () => loopApprovalScreen(options.proposal) },
+		actions: {
+			"start-here": async () => {
+				await options.startHere();
+				return { kind: "close" };
+			},
+			"start-fresh": async ({ signal }) => {
+				await options.startFresh(signal);
+				return { kind: "close" };
+			},
+			"change-cadence": async () => {
+				await options.changeCadence();
+				return { kind: "close" };
+			},
+			"keep-editing": async () => {
+				options.keepEditing();
+				return { kind: "close" };
+			},
+			cancel: async () => {
+				options.cancel();
+				return { kind: "close" };
+			},
+		},
+	});
+	return runMenu(ctx, menu, {
+		getState: () => undefined,
+		...(options.signal ? { signal: options.signal } : {}),
+		...(options.isCurrent ? { isCurrent: options.isCurrent } : {}),
+	});
+}

package/src/loop-env.ts

@@ -0,0 +1,50 @@
+/**
+ * The loop-active environment contract.
+ *
+ * pi-loop publishes two variables into its own process environment while a
+ * loop is active, and removes them the moment it is not:
+ *
+ * - `PI_LOOP_ACTIVE=1` — an unattended loop is running in this session.
+ * - `PI_LOOP_ID=<id>` — the loop's id, so a reader can tell one loop from the
+ *   next without asking pi-loop anything.
+ *
+ * It exists for other extensions, and pi-auto-permissions is the first
+ * consumer: a modal permission prompt does not pause a loop, it deadlocks it,
+ * so a guardian that would have asked a human needs to know there is no human
+ * to ask. The mechanism is deliberately the one `pi-subagents` already
+ * established with `PI_SUBAGENT_CHILD=1` and `detectSubagentContext` reads —
+ * an environment variable, not a package dependency, not an import, not an
+ * RPC. Neither extension needs the other installed, in either direction, and
+ * a reader that never sees the variable behaves exactly as it does today.
+ *
+ * Both variables are set on the process, so they are visible to every
+ * extension in the session and inherited by anything it spawns. That is the
+ * point: a subagent launched by a looping session is running unattended for
+ * the same reason its parent is.
+ */
+
+import type { LoopState } from "./state.js";
+
+export const LOOP_ACTIVE_ENV = "PI_LOOP_ACTIVE";
+export const LOOP_ID_ENV = "PI_LOOP_ID";
+
+/**
+ * Publish (or withdraw) the loop-active signal for `loop`.
+ *
+ * Only an `active` loop publishes. A paused loop is not working unattended —
+ * the user paused it and is, by construction, present — and a stopped loop is
+ * not working at all, so both withdraw the signal rather than leaving a stale
+ * one behind for the rest of the session.
+ */
+export function publishLoopEnv(
+	loop: LoopState | undefined,
+	env: Record<string, string | undefined> = process.env,
+): void {
+	if (loop?.status === "active") {
+		env[LOOP_ACTIVE_ENV] = "1";
+		env[LOOP_ID_ENV] = loop.id;
+		return;
+	}
+	delete env[LOOP_ACTIVE_ENV];
+	delete env[LOOP_ID_ENV];
+}

package/src/loop.ts

@@ -71,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";
@@ -135,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;
@@ -240,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");
@@ -252,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;
@@ -660,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;
@@ -1000,6 +1061,9 @@ 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 });
 	}
 
@@ -1158,11 +1222,29 @@ export class LoopController {
 			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();
@@ -1174,9 +1256,31 @@ export class LoopController {
 	 * 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) {
@@ -1203,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,
@@ -1215,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) {
@@ -1256,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,7 +14,10 @@ import {
 	saveLoopSettings,
 } from "./settings.js";
 import { parseDuration } from "./interval.js";
-import { renderProposalCard } from "./planning.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,
@@ -284,7 +287,10 @@ export async function showLoopApproval(
 ): Promise<void> {
 	const proposal = controller.planning.proposal;
 	if (!proposal) return;
-	ctx.ui.notify(renderProposalCard(proposal).join("\n"), "info");
+	// 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>.",
@@ -292,51 +298,97 @@ export async function showLoopApproval(
 		);
 		return;
 	}
-	const choice = await ctx.ui.select("Start this loop?", [
-		"Start loop",
-		"Change cadence",
-		"Keep editing",
-		"Cancel",
-	]);
-	switch (choice) {
-		case "Start loop": {
-			const result = controller.startLoop(ctx, {
-				kind: "start",
-				requestedMs: proposal.intervalMs,
-				intervalMs: proposal.intervalMs,
-				clamped: false,
-				maxTurns: proposal.maxTurns,
-				expiresInMs: proposal.expiresInMs,
-				prompt: proposal.objective,
-			});
+	await showLoopApprovalMenu(ctx, {
+		proposal,
+		startHere: () => {
+			const result = controller.startLoop(ctx, startArgumentsFor(proposal));
 			if (result.ok) controller.endPlanning();
 			else ctx.ui.notify(result.message, "error");
-			return;
-		}
-		case "Change cadence": {
-			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;
-			}
-			controller.propose(proposal.objective, {
-				intervalMs: interval.effectiveMs,
-				maxTurns: proposal.maxTurns,
-				expiresInMs: proposal.expiresInMs,
-			});
-			await showLoopApproval(controller, ctx);
-			return;
-		}
-		case "Keep editing":
+		},
+		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");
-			return;
-		default:
+		},
+		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

@@ -52,7 +52,19 @@ export function buildLoopObjectivePrompt(
 		"- 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.",
-		"- Never reshape a command to get past a permission prompt. A blocked command means stop and ask through loop_wait, never find another way around it.",
+		// 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}`,

package/src/planning.ts

@@ -38,6 +38,16 @@ export interface LoopPlanningState {
 	active: boolean;
 	/** The current draft awaiting approval, when one has been proposed. */
 	proposal?: LoopProposal;
+	/**
+	 * `proposedAt` of the draft whose card has already been rendered.
+	 *
+	 * The card is an artifact in the transcript, not a status line, so re-running
+	 * `/loop` to reopen the menu must not emit a second copy of the same card.
+	 * A new draft — a reworded objective, a changed cadence — has a new
+	 * `proposedAt` and does get its own card, because it is a different thing to
+	 * approve.
+	 */
+	cardShownAt?: number;
 }
 
 export function buildProposal(
@@ -72,7 +82,7 @@ export function renderProposalCard(proposal: LoopProposal): string[] {
 		`**Cadence** every ${formatDuration(proposal.intervalMs)} — a fallback heartbeat; the loop advances whenever the session settles.`,
 		`**Turn cap** ${proposal.maxTurns === null ? "unlimited" : proposal.maxTurns} · **Expires** ${formatDuration(proposal.expiresInMs)}`,
 		"",
-		"Run `/loop` to approve and start, keep editing, or cancel.",
+		"Run `/loop` for the actions: start here, start in a fresh session, change the cadence, keep editing, or cancel.",
 	];
 }
 

package/src/presentation.ts

@@ -0,0 +1,50 @@
+/**
+ * The approval card, as a framed transcript block.
+ *
+ * It used to go out twice and neither copy was a card: `loop_propose`
+ * returned it as tool-result text, and `/loop` re-printed it through
+ * `ctx.ui.notify`. Tool text is rendered as a wall of markdown inside a tool
+ * result, and a toast is a transient line that scrolls away — so the one
+ * artifact the whole planning flow exists to produce was the least legible
+ * thing on the screen, and duplicated.
+ *
+ * A custom-type message with `display: true` is what Pi frames, and
+ * `triggerTurn: false` is what keeps it an artifact rather than a prompt: the
+ * card appears, the model is not asked to respond to it, and the user's
+ * approval remains the only thing that starts a loop. This is exactly how
+ * pi-plan-mode renders a proposed plan (`packages/pi-plan-mode/src/
+ * presentation.ts`), for the same reason.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type LoopProposal, renderProposalCard } from "./planning.js";
+
+export const LOOP_PROPOSAL_MESSAGE_TYPE = "loop-proposal";
+
+/**
+ * Emit the card. Returns false when Pi refused it, in which case the caller
+ * still has a working flow — the menu carries the actions, and the criteria
+ * are on disk the moment the loop starts.
+ */
+export function showLoopProposalCard(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	proposal: LoopProposal,
+): boolean {
+	try {
+		pi.sendMessage(
+			{
+				customType: LOOP_PROPOSAL_MESSAGE_TYPE,
+				content: renderProposalCard(proposal).join("\n"),
+				display: true,
+				details: { criteria: proposal.criteria.length, proposedAt: proposal.proposedAt },
+			},
+			{ triggerTurn: false },
+		);
+		return true;
+	} catch (error) {
+		const detail = error instanceof Error ? error.message : String(error);
+		ctx.ui.notify(`Unable to show the loop proposal: ${detail}`, "error");
+		return false;
+	}
+}

package/src/propose-tool.ts

@@ -14,9 +14,9 @@
 
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { MAX_INTERVAL_MS, parseDuration } from "./interval.js";
+import { formatDuration, MAX_INTERVAL_MS, parseDuration } from "./interval.js";
 import type { LoopController } from "./loop.js";
-import { renderProposalCard } from "./planning.js";
+import { showLoopProposalCard } from "./presentation.js";
 
 export const LOOP_PROPOSE_TOOL = "loop_propose";
 
@@ -59,7 +59,7 @@ export function registerLoopProposeTool(pi: ExtensionAPI, controller: LoopContro
 					}),
 				),
 			}),
-			async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 				if (!controller.planning.active) {
 					return failure(
 						"Loop planning is not open, so there is nothing to propose. The user opens it by running /loop with no loop running.",
@@ -101,8 +101,19 @@ export function registerLoopProposeTool(pi: ExtensionAPI, controller: LoopContro
 				}
 
 				const proposal = controller.propose(objective, overrides);
+				// The card goes to the transcript as a framed block, not back through
+				// this tool result. Returning it here too would render the same
+				// artifact twice, once framed and once as a wall of markdown, and
+				// spend the objective's tokens a second time in the model's own
+				// context for no reader that does not already have it.
+				controller.showProposalCard(ctx);
 				return {
-					content: [{ type: "text" as const, text: renderProposalCard(proposal).join("\n") }],
+					content: [
+						{
+							type: "text" as const,
+							text: `Approval card rendered: ${proposal.criteria.length} ${proposal.criteria.length === 1 ? "criterion" : "criteria"}, waking every ${formatDuration(proposal.intervalMs)}, cap ${proposal.maxTurns === null ? "unlimited" : proposal.maxTurns}, expires in ${formatDuration(proposal.expiresInMs)}. The user starts it from /loop; nothing is running yet.`,
+						},
+					],
 					details: {
 						criteria: proposal.criteria.length,
 						intervalMs: proposal.intervalMs,

package/src/state.ts

@@ -63,6 +63,19 @@ export interface LoopState {
 	 * while it writes its state down; the next settle stops it.
 	 */
 	expiring?: true;
+	/**
+	 * Set on a loop handed to a fresh session and cleared the moment that
+	 * session restores it.
+	 *
+	 * The launching session cannot kick the loop off itself: Pi builds a new
+	 * extension instance for the new session, so the controller that ran the
+	 * approval menu is not the controller that ends up holding the loop —
+	 * observed live, where the loop crossed correctly and then sat idle waiting
+	 * for its first fallback wake. Carrying the intent in the state instead
+	 * means whichever instance restores it does the kickoff, which is true for
+	 * every lifecycle the host might have.
+	 */
+	handoff?: true;
 }
 
 const MAX_PROMPT_LENGTH = 100_000;
@@ -135,6 +148,7 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 	const lastFingerprint = optionalText(record.lastFingerprint);
 	if (lastFingerprint === false) return undefined;
 	if (record.expiring !== undefined && record.expiring !== true) return undefined;
+	if (record.handoff !== undefined && record.handoff !== true) return undefined;
 	return {
 		id,
 		status: status as LoopStatus,
@@ -154,6 +168,7 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 		...(lastFingerprint === undefined ? {} : { lastFingerprint }),
 		...(pauseCause === undefined ? {} : { pauseCause }),
 		...(record.expiring === true ? { expiring: true as const } : {}),
+		...(record.handoff === true ? { handoff: true as const } : {}),
 	};
 }