@hank-warren/pi-loop 0.5.0 → 0.6.0

package/src/manager.ts

@@ -7,7 +7,6 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { formatDuration, parseInterval } from "./interval.js";
 import type { LoopController } from "./loop.js";
-import { readGoalSnapshot } from "./state.js";
 import {
 	DEFAULT_LOOP_SETTINGS,
 	type LoopSettings,
@@ -79,39 +78,35 @@ async function startFromMenu(
 		ctx.ui.notify(`Invalid interval: ${intervalText}. Use <number><unit>, e.g. 5m.`, "error");
 		return;
 	}
-	// With an active goal the loop binds to it and the text is an optional
-	// per-wake focus. Without one the loop owns its objective, so the text is
-	// required — asking for it here is what replaces the old dead-end refusal.
-	const goal = readGoalSnapshot(ctx.sessionManager.getBranch());
-	const goalBound = goal?.status === "active";
+	// The loop owns its objective, so the text is required — asking for it here
+	// is what replaces the old dead-end refusal.
 	const promptText = await ctx.ui.input(
-		goalBound
-			? "Loop focus (optional, added to every goal poke)"
-			: "Objective, including how the loop knows it is done",
-		goalBound ? undefined : "e.g. get CI green on main, verified by a passing run",
+		"Objective, including how the loop knows it is done",
+		"e.g. get CI green on main, verified by a passing run",
 	);
 	if (promptText === undefined) return;
 	const prompt = promptText.trim();
-	if (!goalBound && !prompt) {
-		ctx.ui.notify(
-			"A loop with no active goal needs its own objective, so no loop was started.",
-			"warning",
-		);
+	if (!prompt) {
+		ctx.ui.notify("A loop needs an objective, so no loop was started.", "warning");
 		return;
 	}
-	controller.startLoop(ctx, {
+	const result = controller.startLoop(ctx, {
 		kind: "start",
 		requestedMs: interval.requestedMs,
 		intervalMs: interval.effectiveMs,
 		clamped: interval.clamped,
 		...(prompt ? { prompt } : {}),
 	});
+	if (!result.ok) ctx.ui.notify(result.message, "error");
 }
 
 async function editPrompt(controller: LoopController, ctx: ExtensionCommandContext): Promise<void> {
 	const loop = controller.state;
 	if (!loop || loop.status === "stopped") return;
-	const next = await ctx.ui.input("Loop focus (optional, added to every goal poke)", loop.prompt ?? "");
+	const next = await ctx.ui.input(
+		"Loop focus (optional, restated on every loop message)",
+		loop.prompt ?? "",
+	);
 	if (next === undefined) return;
 	const prompt = next.trim();
 	if (prompt) controller.state = { ...loop, prompt };

package/src/messages.ts

@@ -10,7 +10,7 @@ import { LOOP_OK_TOKEN } from "./ack.js";
 import { formatDuration } from "./interval.js";
 import { CRITERIA_FILE, type LedgerPaths, PROGRESS_FILE } from "./ledger.js";
 import { appendContinuationMarker, appendPokeMarker } from "./markers.js";
-import type { GoalSnapshot, LoopState } from "./state.js";
+import type { LoopState } from "./state.js";
 
 /** Why the loop is talking: the first turn, an ordinary turn, or after a compaction. */
 export type ContinuationKind = "kickoff" | "continue" | "reanchor";
@@ -21,30 +21,10 @@ function formatIteration(loop: LoopState): string {
 }
 
 /**
- * The goal-bound poke: wake the session and point at the goal without
- * restating it. Loops require an active pi-goal goal, so every poke turn
- * already carries the objective, goal_id, and goal-mode rules through
- * pi-goal's system prompt append; restating them here would store duplicate
- * tokens in the conversation on every wake (see README: cross-extension
- * assumption). Only the dynamic per-wake state (iteration, reason) belongs in
- * this tail message.
- */
-export function buildGoalPoke(loop: LoopState, reason: "goal-stalled" | "goal-waiting"): string {
-	const lines = [
-		`Scheduled loop wakeup ${formatIteration(loop)} (every ${formatDuration(loop.intervalMs)}).`,
-		reason === "goal-waiting"
-			? "This is the external wake for your waiting goal. Re-check whatever the goal was waiting on and continue."
-			: "The session went idle but the active goal is not complete. Continue working toward it — the objective and goal-mode rules are in the system prompt.",
-	];
-	if (loop.prompt) lines.push("", `Loop focus: ${loop.prompt}`);
-	return appendPokeMarker(lines.join("\n"), loop.id, loop.iteration + 1);
-}
-
-/**
- * The standalone poke. Slim for the same reason the goal-bound one is: this
- * loop's own objective injection puts the objective and loop-mode rules in
- * the system prompt of every turn, so restating them here would store a
- * duplicate copy on every wake.
+ * The poke. Deliberately slim: the loop's own objective injection puts the
+ * objective and loop-mode rules in the system prompt of every turn, so
+ * restating them here would store a duplicate copy on every wake. Only the
+ * dynamic per-wake state (iteration, reason) belongs in this tail message.
  */
 export function buildObjectivePoke(
 	loop: LoopState,
@@ -81,8 +61,8 @@ function addCancelledWaitHint(lines: string[], loop: LoopState): void {
 }
 
 /**
- * The settle-driven continuation: the message that actually paces a
- * standalone loop now. Pointer-sized for the same reason the pokes are — it
+ * The settle-driven continuation: the message that actually paces a loop.
+ * Pointer-sized for the same reason the pokes are — it
  * only ever fires while the loop is active, so the byte-stable system append
  * carrying the objective and loop-mode rules is guaranteed present on that
  * turn.
@@ -207,20 +187,16 @@ export function extractNextActions(summary: string, maxLength = 240): string | u
  */
 export function buildCompactionInstructions(
 	loop: LoopState,
-	/** The goal only when it is still active; a finished goal is not the objective. */
-	goal: GoalSnapshot | undefined,
 	override: string | null,
 	/** The loop's ledger, when it has one. */
 	ledger?: LedgerPaths,
 ): string {
 	if (override) return override;
-	const objective = goal
-		? `The session is working toward this goal: ${goal.text}`
-		: loop.objective
-			? `The session is working toward this loop objective: ${loop.objective}`
-			: loop.prompt
-				? `The session is running a recurring loop focused on: ${loop.prompt}`
-				: "The session is running a recurring loop.";
+	const objective = loop.objective
+		? `The session is working toward this loop objective: ${loop.objective}`
+		: loop.prompt
+			? `The session is running a recurring loop focused on: ${loop.prompt}`
+			: "The session is running a recurring loop.";
 	return [
 		`${objective}`,
 		"This summary must let that work continue seamlessly. Preserve verbatim:",

package/src/objective.ts

@@ -1,12 +1,10 @@
 /**
- * The standalone loop's objective injection.
+ * The loop's objective injection.
  *
- * A goal-bound loop gets the objective in front of the model for free:
- * pi-goal appends it to the system prompt on every active goal turn, which is
- * why pokes do not restate it. A standalone loop has no such provider, so it
- * has to carry its own — and it does so under the same cache-stability
- * discipline, because the alternative (restating the objective in every poke)
- * is exactly the per-wake duplication that discipline exists to remove.
+ * The loop carries its own objective to the model on every active turn, which
+ * is what lets the pokes and continuations stay pointer-sized. The
+ * alternative — restating the objective in every poke — is exactly the
+ * per-wake duplication the cache-stability discipline below exists to remove.
  *
  * Cache-stability contract: this append lands inside the provider's cached
  * system block (Anthropic caches tools -> system -> messages as one prefix),

package/src/render.ts

@@ -5,8 +5,8 @@
  * text plus a provenance marker comment. This transformer collapses each into
  * a one-line themed chip in the transcript. Display-only by Pi contract: the
  * stored message and model context are untouched, and pokes keep being
- * delivered through sendUserMessage so pi-goal's before_agent_start hook
- * (which appends the goal system prompt) still fires for every poke turn.
+ * delivered through sendUserMessage so the loop's own before_agent_start hook
+ * (which appends the objective) still fires for every poke turn.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -29,11 +29,7 @@ export function compactPokeMessage(markdown: string) {
 	if (!extractPokeMarker(markdown)) return undefined;
 	const head = POKE_HEAD_PATTERN.exec(markdown);
 	if (!head) return undefined;
-	const reason = markdown.includes("external wake")
-		? "waiting"
-		: markdown.includes("completion criteria are not met")
-			? "objective"
-			: "stalled";
+	const reason = markdown.includes("wait you asked for has elapsed") ? "wait elapsed" : "stalled";
 	const focus = POKE_FOCUS_PATTERN.exec(markdown)?.[1];
 	return `*⏰ loop wake ${head[1]} · ${reason}${focus ? ` · ${focus}` : ""}*`;
 }

package/src/settings.ts

@@ -1,6 +1,6 @@
 /**
  * Global pi-loop settings: `~/.pi/agent/pi-loop.json`. Follows the sibling
- * convention (pi-goal, pi-plan-mode): an absent file means defaults and is
+ * convention (pi-plan-mode): an absent file means defaults and is
  * never created implicitly, saves are atomic and preserve unknown fields, and
  * an invalid file warns and falls back to defaults without being overwritten.
  */
@@ -37,6 +37,19 @@ export interface LoopSettings {
 	noProgressTurns: number | null;
 	/** Wall-clock expiry for a loop, e.g. "7d" (research: bound forgotten loops). */
 	maxLoopDuration: string;
+	/**
+	 * Detect an inline `/loop` token or a `loop:` prefixed line mid-prompt and
+	 * point the model at the `loop_start` tool. Pi only dispatches `/loop` from
+	 * position 0, so without this a mid-prompt invocation is silently prose.
+	 */
+	inlineInvocation: boolean;
+	/**
+	 * Fallback heartbeat used by an inline invocation that names no interval.
+	 * In a settle-paced loop the interval is only a fallback — the settle
+	 * boundary is the pacemaker — so this value is far less consequential than
+	 * it looks; it is still clamped to MIN_INTERVAL_MS.
+	 */
+	defaultInterval: string;
 	compaction: LoopCompactionSettings;
 }
 
@@ -45,6 +58,8 @@ export const DEFAULT_LOOP_SETTINGS: LoopSettings = {
 	automaticTurns: 25,
 	noProgressTurns: 3,
 	maxLoopDuration: "7d",
+	inlineInvocation: true,
+	defaultInterval: "10m",
 	compaction: {
 		enabled: true,
 		threshold: 0.7,
@@ -80,12 +95,24 @@ export function normalizeLoopSettings(value: unknown): LoopSettings | undefined
 		return undefined;
 	}
 
+	const inlineInvocation = Object.hasOwn(record, "inlineInvocation")
+		? record.inlineInvocation
+		: DEFAULT_LOOP_SETTINGS.inlineInvocation;
+	if (typeof inlineInvocation !== "boolean") return undefined;
+
+	const defaultInterval = Object.hasOwn(record, "defaultInterval")
+		? record.defaultInterval
+		: DEFAULT_LOOP_SETTINGS.defaultInterval;
+	if (typeof defaultInterval !== "string" || parseDuration(defaultInterval) === undefined) {
+		return undefined;
+	}
+
 	const compactionValue = Object.hasOwn(record, "compaction") ? record.compaction : undefined;
 	if (compactionValue !== undefined && !ownRecord(compactionValue)) return undefined;
 	const compactionRecord = ownRecord(compactionValue) ?? {};
-	// `postCompactContinuation` was removed in favour of pi-goal owning the
-	// post-compaction re-prompt; a file still carrying it is preserved as an
-	// unknown field and ignored, never rejected.
+	// `postCompactContinuation` was removed in favour of the loop's own
+	// re-anchor; a file still carrying it is preserved as an unknown field and
+	// ignored, never rejected.
 	const enabled = readBoolean(compactionRecord, "enabled", DEFAULT_LOOP_SETTINGS.compaction.enabled);
 	const threshold = Object.hasOwn(compactionRecord, "threshold")
 		? compactionRecord.threshold
@@ -111,6 +138,8 @@ export function normalizeLoopSettings(value: unknown): LoopSettings | undefined
 		automaticTurns,
 		noProgressTurns,
 		maxLoopDuration,
+		inlineInvocation,
+		defaultInterval,
 		compaction: { enabled, threshold, instructions },
 	};
 }
@@ -199,6 +228,8 @@ export function saveLoopSettings(settings: LoopSettings, settingsPath = loopSett
 			automaticTurns: normalized.automaticTurns,
 			noProgressTurns: normalized.noProgressTurns,
 			maxLoopDuration: normalized.maxLoopDuration,
+			inlineInvocation: normalized.inlineInvocation,
+			defaultInterval: normalized.defaultInterval,
 			compaction: { ...compaction, ...normalized.compaction },
 		},
 		null,

package/src/start-tool.ts

@@ -0,0 +1,145 @@
+/**
+ * `loop_start`: the model-invoked way into a loop.
+ *
+ * Pi only dispatches `/loop` when it starts the message, so a mid-prompt
+ * `quick check /loop 10m get CI green` arrives as ordinary prose. The
+ * inline-invocation hooks append a one-turn reminder to the system prompt for
+ * exactly that message, and this tool is what the reminder points at. It
+ * reuses `LoopController.startLoop`, the same path the `/loop` command takes,
+ * so replacement rules, the loop_complete availability guard, the ledger, the
+ * kickoff anchor, and persistence all behave identically.
+ *
+ * The hard armed-gate is the deliberate divergence from pi-goal's equivalent
+ * tool, which relied on prompt guidelines alone. A loop is *self-continuing*:
+ * a spurious start does not produce one unwanted answer, it produces turns
+ * until a cap. So the tool refuses outright unless the inline hint armed for
+ * the turn that is calling it.
+ *
+ * Registered unconditionally, like the other loop tools: the tool set is part
+ * of the cached request prefix, so it never changes with loop state.
+ */
+
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { LOOP_COMPLETE_TOOL } from "./complete-tool.js";
+import { formatDuration, parseDuration, parseInterval } from "./interval.js";
+import type { InlineInvocationState } from "./inline-invocation.js";
+import type { LoopController } from "./loop.js";
+
+export const LOOP_START_TOOL = "loop_start";
+
+/** Long enough for a real objective, short enough to reject a pasted file. */
+const MAX_OBJECTIVE_LENGTH = 4_000;
+
+export function registerLoopStartTool(
+	pi: ExtensionAPI,
+	controller: LoopController,
+	invocation: InlineInvocationState,
+) {
+	pi.registerTool(
+		defineTool({
+			name: LOOP_START_TOOL,
+			label: "Loop Start",
+			description:
+				"Start a /loop for an objective the user explicitly invoked with an inline /loop or loop: token in their message. Only for explicit invocations: never start a loop from general conversation, your own initiative, or an instruction that merely sounds loop-like. The objective is the text following the token.",
+			promptSnippet:
+				"Start a /loop when the user's message contains an explicit inline /loop or loop: invocation",
+			promptGuidelines: [
+				"Call loop_start only when the user's message contains an explicit `/loop <objective>` or `loop: <objective>` token. Never start a loop without that token, no matter how loop-like the request sounds; the tool refuses when the turn carries no inline invocation.",
+				"If the user is discussing, quoting, or documenting the /loop command rather than invoking it — asking how it works, pasting a transcript, or editing text that mentions it — do not call loop_start.",
+				"Pass the objective text that follows the token, without the token itself. A leading interval (`10m`, `2h`) and flags like `--max 5` or `--expires 3d` become the interval, max, and expires parameters, not part of the objective.",
+				"Call loop_start before doing any of the objective's work, then continue working toward it in the same turn.",
+				"Never call loop_complete in the same turn as loop_start: the starting turn has not done the work, and completion needs cited evidence per criterion.",
+			],
+			parameters: Type.Object({
+				objective: Type.String({
+					minLength: 1,
+					maxLength: MAX_OBJECTIVE_LENGTH,
+					description:
+						"The loop objective, including how the loop knows it is done: the user's text following the /loop or loop: token, verbatim, without the token, the interval, or flags.",
+				}),
+				interval: Type.Optional(
+					Type.String({
+						description:
+							"Fallback wake interval from the invocation, e.g. '10m' or '2h'. Omit when the user named none.",
+					}),
+				),
+				max: Type.Optional(
+					Type.Integer({
+						minimum: 1,
+						description: "Wake cap from a --max flag in the invocation.",
+					}),
+				),
+				expires: Type.Optional(
+					Type.String({
+						description: "Loop lifetime from an --expires flag in the invocation, e.g. '3d'.",
+					}),
+				),
+			}),
+			async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+				// The gate. Everything below is ordinary validation; this is the
+				// one check that makes a self-continuing tool safe to expose.
+				if (!invocation.invokedThisTurn) {
+					return refusal(
+						`${LOOP_START_TOOL} is only available on a turn whose user message contains an explicit inline /loop or loop: invocation. This turn has none, so no loop was started. If the user wants one, they can type /loop <interval> <objective>.`,
+						{},
+					);
+				}
+				const objective = params.objective.trim();
+				if (!objective) {
+					return refusal("Loop not started: the objective is empty.", {});
+				}
+				const existing = controller.state;
+				if (existing && existing.status !== "stopped") {
+					return refusal(
+						`Loop not started: a loop already exists in this session (${existing.status}). The user can replace it with /loop, or stop it with /loop stop.`,
+						{ existingLoopId: existing.id },
+					);
+				}
+				const intervalToken = params.interval?.trim() || controller.settings.defaultInterval;
+				const interval = parseInterval(intervalToken);
+				if (!interval) {
+					return refusal(
+						`Loop not started: invalid interval ${intervalToken}. Use <number><unit> with unit s, m, h, or d, e.g. 10m.`,
+						{ objective },
+					);
+				}
+				let expiresInMs: number | undefined;
+				if (params.expires !== undefined) {
+					expiresInMs = parseDuration(params.expires.trim());
+					if (expiresInMs === undefined) {
+						return refusal(
+							`Loop not started: invalid expiry ${params.expires}. Use <number><unit> with unit s, m, h, or d, e.g. 3d.`,
+							{ objective },
+						);
+					}
+				}
+				const result = controller.startLoop(ctx, {
+					kind: "start",
+					requestedMs: interval.requestedMs,
+					intervalMs: interval.effectiveMs,
+					clamped: interval.clamped,
+					...(params.max === undefined ? {} : { maxIterations: params.max }),
+					...(expiresInMs === undefined ? {} : { expiresInMs }),
+					prompt: objective,
+				});
+				if (!result.ok) return refusal(`Loop not started: ${result.message}`, { objective });
+				const loop = result.loop;
+				return {
+					content: toolContent(
+						`Loop started (loop_id ${loop.id}): ${objective}. Fallback wake every ${formatDuration(loop.intervalMs)}. Keep working the objective this turn; the loop continues at every idle boundary until you call ${LOOP_COMPLETE_TOOL} with this loop_id and cited evidence for every criterion, a cap is reached, or the user stops it. Do not call ${LOOP_COMPLETE_TOOL} in this turn.`,
+					),
+					details: { loopId: loop.id, objective, intervalMs: loop.intervalMs },
+				};
+			},
+		}),
+	);
+}
+
+function refusal(text: string, details: Record<string, unknown>) {
+	return { content: toolContent(text), details, isError: true };
+}
+
+function toolContent(text: string) {
+	return [{ type: "text" as const, text }];
+}

package/src/state.ts

@@ -1,14 +1,12 @@
 /**
- * Loop state persisted as `loop-state` custom session entries, plus read-only
- * fail-open readers for the sibling extensions' entries: pi-goal's
- * `goal-state` and pi-plan-mode's `plan-mode-state`. The coupling is
- * deliberately loose — no package dependency, no RPC; an absent or
- * unrecognizable entry degrades pi-loop to standalone behavior, never crashes
- * it.
+ * Loop state persisted as `loop-state` custom session entries, plus one
+ * read-only fail-open reader for a sibling extension's entries:
+ * pi-plan-mode's `plan-mode-state`. The coupling is deliberately loose — no
+ * package dependency, no RPC; an absent or unrecognizable entry degrades
+ * pi-loop to "not planning", never crashes it.
  */
 
 export const LOOP_STATE_ENTRY_TYPE = "loop-state";
-export const GOAL_STATE_ENTRY_TYPE = "goal-state";
 export const PLAN_MODE_STATE_ENTRY_TYPE = "plan-mode-state";
 
 import { type LoopWait, normalizeLoopWait } from "./wait.js";
@@ -19,13 +17,16 @@ export type LoopStatus = (typeof LOOP_STATUSES)[number];
 export interface LoopState {
 	id: string;
 	status: LoopStatus;
-	/** The recurring prompt; undefined for a goal-bound loop started bare. */
+	/**
+	 * An optional recurring focus, restated on every loop message. Also the
+	 * only field a loop persisted before 0.6.0 may carry instead of an
+	 * objective; the restore shim adopts it as one.
+	 */
 	prompt?: string;
 	/**
-	 * The loop's own objective and completion criteria. Its presence *is* the
-	 * loop's mode: set means standalone (this loop owns when the work is done,
-	 * ended by the `loop_complete` tool or a cap), absent means goal-bound (an
-	 * active pi-goal goal owns it, exactly as before).
+	 * The loop's objective and completion criteria: what it works on, and what
+	 * `loop_complete` answers for. Optional only because a loop persisted
+	 * before 0.6.0 may predate it — every loop started now has one.
 	 */
 	objective?: string;
 	intervalMs: number;
@@ -172,17 +173,11 @@ interface SessionEntryLike {
 }
 
 function lastCustomEntryData(entries: unknown[], customType: string): unknown {
-	return lastCustomEntryDatas(entries, customType, 1)[0];
-}
-
-/** Newest-first data of the last `limit` custom entries of `customType`. */
-function lastCustomEntryDatas(entries: unknown[], customType: string, limit: number): unknown[] {
-	const datas: unknown[] = [];
-	for (let index = entries.length - 1; index >= 0 && datas.length < limit; index -= 1) {
+	for (let index = entries.length - 1; index >= 0; index -= 1) {
 		const entry = entries[index] as SessionEntryLike | undefined;
-		if (entry?.type === "custom" && entry.customType === customType) datas.push(entry.data);
+		if (entry?.type === "custom" && entry.customType === customType) return entry.data;
 	}
-	return datas;
+	return undefined;
 }
 
 /** Restore the persisted loop state from a session branch, fail-open. */
@@ -193,77 +188,6 @@ export function restoreLoopState(entries: unknown[]): LoopState | undefined {
 	return normalizeLoopState(record.loop);
 }
 
-/**
- * A standalone loop owns its own completion criteria; a goal-bound loop
- * delegates that to pi-goal. Presence of `objective` is the discriminator.
- */
-export function isStandaloneLoop(loop: LoopState): boolean {
-	return loop.objective !== undefined;
-}
-
-export const GOAL_SAFETY_STATUSES = ["paused", "blocked", "usage_limited", "budget_limited"] as const;
-
-/** How many `goal-state` entries a clear may be scanned back through. */
-const GOAL_CLEAR_SCAN_LIMIT = 8;
-
-export interface GoalSnapshot {
-	status: string;
-	text: string;
-	/** Present while the goal is in a goal_wait external-event wait. */
-	waiting: boolean;
-	iteration?: number;
-	tokensUsed?: number;
-	tokenBudget?: number;
-	automaticModelTurns?: number;
-}
-
-/**
- * Read pi-goal's persisted goal, fail-open: undefined when absent or when the
- * entry shape is not recognizably a goal. Only fields pi-loop consumes are
- * extracted; unknown statuses are preserved verbatim so the caller can treat
- * anything outside its known sets conservatively.
- *
- * Completion race: pi-goal persists the finished goal (status "complete") and
- * then clears the entry (goal: null), so by the loop's next tick the last
- * entry is the clear. When the newest entry is a clear (or unreadable), scan
- * back over the consecutive run of clears for the goal they cleared: a
- * complete goal is reported, so the loop stops with "goal completed" instead
- * of pausing as goal-missing. A clear over any other status (user /goal clear
- * mid-flight) still reads as no goal. The scan is bounded so a long history of
- * clears cannot make the read walk the branch.
- */
-export function readGoalSnapshot(entries: unknown[]): GoalSnapshot | undefined {
-	const datas = lastCustomEntryDatas(entries, GOAL_STATE_ENTRY_TYPE, GOAL_CLEAR_SCAN_LIMIT);
-	const newest = parseGoalSnapshot(ownRecord(datas[0])?.goal);
-	if (newest) return newest;
-	for (let index = 1; index < datas.length; index += 1) {
-		const cleared = parseGoalSnapshot(ownRecord(datas[index])?.goal);
-		// Another clear or an unreadable entry: keep scanning back.
-		if (!cleared) continue;
-		return cleared.status === "complete" ? cleared : undefined;
-	}
-	return undefined;
-}
-
-function parseGoalSnapshot(value: unknown): GoalSnapshot | undefined {
-	const goal = ownRecord(value);
-	if (!goal) return undefined;
-	const status = typeof goal.status === "string" ? goal.status : undefined;
-	const text = typeof goal.text === "string" ? goal.text.trim() : "";
-	if (!status || !text) return undefined;
-	return {
-		status,
-		text,
-		waiting: ownRecord(goal.waiting) !== undefined,
-		...(isNonNegativeNumber(goal.iteration) ? { iteration: goal.iteration } : {}),
-		...(isNonNegativeNumber(goal.tokensUsed) ? { tokensUsed: goal.tokensUsed } : {}),
-		...(isNonNegativeNumber(goal.tokenBudget) ? { tokenBudget: goal.tokenBudget } : {}),
-		...(isNonNegativeNumber(goal.automaticModelTurns)
-			? { automaticModelTurns: goal.automaticModelTurns }
-			: {}),
-	};
-}
-
 /** Read pi-plan-mode's persisted state, fail-open: absent or malformed = not planning. */
 export function readPlanModeEnabled(entries: unknown[]): boolean {
 	const data = ownRecord(lastCustomEntryData(entries, PLAN_MODE_STATE_ENTRY_TYPE));
@@ -288,10 +212,6 @@ function isPositiveSafeInteger(value: unknown): value is number {
 	return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
 }
 
-function isNonNegativeNumber(value: unknown): value is number {
-	return typeof value === "number" && Number.isFinite(value) && value >= 0;
-}
-
 function isTimestamp(value: unknown): value is number {
 	return (
 		typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= MAX_TIMESTAMP

package/src/wait-tool.ts

@@ -10,7 +10,7 @@
  * Registered unconditionally, like `loop_complete`, and for the same reason:
  * tools are part of the cached request prefix, so adding or removing one
  * mid-session invalidates the whole conversation cache. It refuses when no
- * standalone loop is active.
+ * loop is active.
  */
 
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -59,7 +59,7 @@ export function registerLoopWaitTool(pi: ExtensionAPI, controller: LoopControlle
 				if (!loop || loop.objective === undefined) {
 					return {
 						content: toolContent(
-							"No standalone /loop is active. loop_wait only applies to a loop that carries its own objective; a goal-bound loop waits through pi-goal.",
+							"No /loop with an objective is active, so there is nothing to wait on. Start one with /loop <interval> <objective>.",
 						),
 						details: {},
 						isError: true,