@brettinternet/pi-loop 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
 # pi-loop
 
-Run a prompt repeatedly, with a fresh session for every iteration.
+Run a prompt repeatedly, with a fresh session for every iteration. Each new session uses the model selected in the preceding session (including a custom non-default model); changing models mid-loop takes effect on the next iteration. If that model is unavailable, the loop pauses rather than falling back to the default.
 
 ```bash
 pi install npm:@brettinternet/pi-loop
@@ -12,19 +12,21 @@ pi install npm:@brettinternet/pi-loop
 /loop <count>
 /loop +<count>
 /loop -<count>
+/loop time <duration>
 /loop delay <duration>
 /loop prompt <text>
 /loop append <text>
 /loop status
 /loop
+/loop pause
 /loop end
 /loop resume
 /loop next
 ```
 
-Durations use `ms`, `s`, `m`, `h`, or `d`. Delays range from 1 second to 24 hours. Timed loops run for at most 30 days.
+Durations use `ms`, `s`, `m`, `h`, or `d`. Delays range from 1 second to 24 hours. Timed loops run for at most 30 days. During a loop, `/loop time <duration>` switches to a deadline from now or resets the current deadline; timed mode requires a non-zero delay. `/loop <count>` switches back to a count of future iterations.
 
-Errors retry after 30 seconds, 1 minute, and 2 minutes, then pause. Aborting pauses the loop. A `loop_pause` request pauses for human blockers. Recovery preserves the loop so you can resume or advance it.
+Errors retry after 30 seconds, 1 minute, and 2 minutes, then pause. Aborting pauses the loop. `/loop pause` pauses after the active iteration settles; if the loop is between iterations, it pauses immediately. Resuming then starts the next iteration. An agent `loop_pause` request pauses mid-iteration for human blockers, and resuming continues that iteration. Recovery preserves the loop so you can resume or advance it.
 
 Chain commands in the prompt:
 
@@ -33,3 +35,11 @@ Chain commands in the prompt:
 ```
 
 Built-in interactive commands cannot be chained.
+
+While a loop is active, every child command receives its stable run ID as `PI_LOOP_RUN_ID`:
+
+```text
+PI_LOOP_RUN_ID=3992f183-e054-4068-a13e-11281d1747e2
+```
+
+The value is always the full UUID, remains unchanged across every iteration and replacement session in that loop, and differs between independent loops. When the loop ends or its session closes, pi-loop restores the previous value or removes the variable if it was previously unset.

package/index.ts

@@ -11,8 +11,9 @@ import { Type } from "typebox";
 
 export const LOOP_STATE_ENTRY = "pi-loop-state-v1";
 export const LOOP_WIDGET_KEY = "pi-loop";
+export const LOOP_RUN_ID_ENV = "PI_LOOP_RUN_ID";
 export const LOOP_USAGE =
-  "usage: /loop <positive-count> [--delay <duration>] <prompt> | /loop for <duration> --delay <duration> <prompt> | /loop <positive-count> | /loop <+|-><count> | /loop delay <duration> | /loop prompt <text> | /loop append <text> | /loop status | /loop resume | /loop next | /loop end";
+  "usage: /loop <positive-count> [--delay <duration>] <prompt> | /loop for <duration> --delay <duration> <prompt> | /loop <positive-count> | /loop <+|-><count> | /loop time <duration> | /loop delay <duration> | /loop prompt <text> | /loop append <text> | /loop status | /loop pause | /loop resume | /loop next | /loop end";
 
 export const MIN_LOOP_DELAY_MS = 1_000;
 export const MAX_LOOP_DELAY_MS = 24 * 60 * 60 * 1_000;
@@ -26,7 +27,7 @@ const LOOP_AGENT_GUIDANCE = `## Active Loop
 
 This session is part of an active unattended loop. If no useful work can continue without human input, credentials, permissions, or another non-transient external dependency, call loop_pause with the blocker. Do not pause for a temporary condition expected to resolve in a later iteration.`;
 
-export type LoopStatus = "active" | "stopping" | "paused" | "completed" | "stopped" | "inactive";
+export type LoopStatus = "active" | "pausing" | "stopping" | "paused" | "completed" | "stopped" | "inactive";
 export type LoopPhase = "running" | "waiting" | "retrying";
 
 export interface LoopState {
@@ -47,6 +48,7 @@ export interface LoopState {
   pausedAt?: number;
   ownerSessionId?: string;
   ownerSessionFile?: string;
+  model?: { provider: string; id: string };
 }
 
 export type ParsedLoopCommand =
@@ -54,20 +56,51 @@ export type ParsedLoopCommand =
   | { kind: "startTimed"; duration: number; delay: number; prompt: string }
   | { kind: "retune"; count: number }
   | { kind: "adjust"; delta: number }
+  | { kind: "time"; duration: number }
   | { kind: "delay"; delay: number }
   | { kind: "replacePrompt"; prompt: string }
   | { kind: "appendPrompt"; prompt: string }
   | { kind: "status" }
+  | { kind: "pauseAtBoundary" }
   | { kind: "resume" }
   | { kind: "next" }
   | { kind: "end" }
   | { kind: "continue"; runId: string; iteration: number }
-  | { kind: "pause"; runId: string; iteration: number };
+  | { kind: "pause"; runId: string; iteration: number }
+  | { kind: "restoreModel"; runId: string; iteration: number };
 
-const ACTIVE_STATUSES = new Set<LoopStatus>(["active", "stopping"]);
-const VISIBLE_STATUSES = new Set<LoopStatus>(["active", "stopping", "paused"]);
+const ACTIVE_STATUSES = new Set<LoopStatus>(["active", "pausing", "stopping"]);
+const VISIBLE_STATUSES = new Set<LoopStatus>(["active", "pausing", "stopping", "paused"]);
 const TERMINAL_STATUSES = new Set<LoopStatus>(["completed", "stopped", "inactive"]);
 
+const LOOP_ENVIRONMENT_STATE_KEY = "__piLoopRunEnvironmentV1";
+type LoopEnvironmentState = { runId: string; originalValue: string | undefined };
+
+function environmentState(): LoopEnvironmentState | undefined {
+  return (globalThis as Record<string, unknown>)[LOOP_ENVIRONMENT_STATE_KEY] as LoopEnvironmentState | undefined;
+}
+
+function exposeLoopRunId(runId: string): void {
+  const active = environmentState();
+  if (active) {
+    active.runId = runId;
+  } else {
+    (globalThis as Record<string, unknown>)[LOOP_ENVIRONMENT_STATE_KEY] = {
+      runId,
+      originalValue: process.env[LOOP_RUN_ID_ENV],
+    } satisfies LoopEnvironmentState;
+  }
+  process.env[LOOP_RUN_ID_ENV] = runId;
+}
+
+function restoreLoopRunId(expectedRunId?: string): void {
+  const active = environmentState();
+  if (!active || (expectedRunId !== undefined && active.runId !== expectedRunId)) return;
+  if (active.originalValue === undefined) delete process.env[LOOP_RUN_ID_ENV];
+  else process.env[LOOP_RUN_ID_ENV] = active.originalValue;
+  delete (globalThis as Record<string, unknown>)[LOOP_ENVIRONMENT_STATE_KEY];
+}
+
 type ArgumentCompletion = { value: string; label: string; description?: string };
 
 function completeArguments(
@@ -100,6 +133,15 @@ function completeLoopArguments(prefix: string): ArgumentCompletion[] | null {
   const delayCommand = /^(delay|--delay)(?:\s+(.*))?$/.exec(input);
   if (delayCommand?.[2] !== undefined) return delayCompletions(prefix, delayCommand[1]);
 
+  const timeCommand = /^time(?:\s+(.*))?$/.exec(input);
+  if (timeCommand?.[1] !== undefined) {
+    return completeArguments(timeCommand[1], COMMON_LOOP_TIMEFRAMES.map((value) => ({
+      value: `time ${value}`,
+      label: `time ${value}`,
+      description: "Switch to timed mode or reset the remaining time",
+    })));
+  }
+
   const timedDelay = /^for\s+(\S+)\s+--delay(=|\s+)?(.*)$/.exec(input);
   if (timedDelay) {
     if (timedDelay[2] !== undefined) {
@@ -164,9 +206,11 @@ function completeLoopArguments(prefix: string): ArgumentCompletion[] | null {
 
   return completeArguments(prefix, [
     { value: "status", label: "status", description: "Show the current loop state" },
-    { value: "resume", label: "resume", description: "Retry a paused iteration" },
+    { value: "pause", label: "pause", description: "Pause after the active iteration settles" },
+    { value: "resume", label: "resume", description: "Resume a paused loop" },
     { value: "next", label: "next", description: "Skip a paused iteration and start the next one" },
     { value: "end", label: "end", description: "End the loop gracefully" },
+    { value: "time ", label: "time <duration>", description: "Switch to timed mode or reset the remaining time" },
     { value: "delay ", label: "delay <duration>", description: "Set the delay between settled iterations" },
     { value: "prompt ", label: "prompt <text>", description: "Replace the future loop prompt" },
     { value: "append ", label: "append <text>", description: "Append to the future loop prompt" },
@@ -255,6 +299,10 @@ export function parseLoopCommand(args: string): ParsedLoopCommand {
     if (rest) throw new Error(`end does not accept arguments; ${LOOP_USAGE}`);
     return { kind: "end" };
   }
+  if (first === "pause") {
+    if (rest) throw new Error(`pause does not accept arguments; ${LOOP_USAGE}`);
+    return { kind: "pauseAtBoundary" };
+  }
   if (first === "resume") {
     if (rest) throw new Error(`resume does not accept arguments; ${LOOP_USAGE}`);
     return { kind: "resume" };
@@ -263,6 +311,11 @@ export function parseLoopCommand(args: string): ParsedLoopCommand {
     if (rest) throw new Error(`next does not accept arguments; ${LOOP_USAGE}`);
     return { kind: "next" };
   }
+  if (first === "time") {
+    const fields = rest.split(/\s+/).filter(Boolean);
+    if (fields.length !== 1) throw new Error(`time requires one duration; ${LOOP_USAGE}`);
+    return { kind: "time", duration: parseLoopTimeframe(fields[0]) };
+  }
   if (first === "delay") {
     const fields = rest.split(/\s+/).filter(Boolean);
     if (fields.length !== 1) throw new Error(`delay requires one duration; ${LOOP_USAGE}`);
@@ -290,7 +343,7 @@ export function parseLoopCommand(args: string): ParsedLoopCommand {
   // These commands are only emitted by the extension itself. Keeping them in
   // the same dispatcher gives boundary transitions command-only session APIs
   // while preventing user input from accidentally looking like one.
-  if (first === "__continue" || first === "__pause") {
+  if (first === "__continue" || first === "__pause" || first === "__restore_model") {
     const fields = rest.split(/\s+/).filter(Boolean);
     if (fields.length !== 2 || !/^[A-Za-z0-9_-]+$/.test(fields[0])) {
       throw new Error("invalid internal loop command");
@@ -301,7 +354,9 @@ export function parseLoopCommand(args: string): ParsedLoopCommand {
     }
     return first === "__continue"
       ? { kind: "continue", runId: fields[0], iteration }
-      : { kind: "pause", runId: fields[0], iteration };
+      : first === "__pause"
+        ? { kind: "pause", runId: fields[0], iteration }
+        : { kind: "restoreModel", runId: fields[0], iteration };
   }
 
   if (/^[+\-]\d/.test(first)) {
@@ -352,6 +407,7 @@ export function parseLoopState(value: unknown): LoopState | undefined {
   const status = value.status;
   if (
     status !== "active" &&
+    status !== "pausing" &&
     status !== "stopping" &&
     status !== "paused" &&
     status !== "completed" &&
@@ -388,6 +444,12 @@ export function parseLoopState(value: unknown): LoopState | undefined {
   if (value.pausedAt !== undefined && !isNonNegativeInteger(value.pausedAt)) return undefined;
   if (value.ownerSessionId !== undefined && typeof value.ownerSessionId !== "string") return undefined;
   if (value.ownerSessionFile !== undefined && typeof value.ownerSessionFile !== "string") return undefined;
+  const model = value.model;
+  if (
+    model !== undefined &&
+    (!isRecord(model) || typeof model.provider !== "string" || !model.provider ||
+      typeof model.id !== "string" || !model.id)
+  ) return undefined;
 
   return {
     version: 1,
@@ -407,6 +469,9 @@ export function parseLoopState(value: unknown): LoopState | undefined {
     ...(value.pausedAt !== undefined ? { pausedAt: value.pausedAt } : {}),
     ...(value.ownerSessionId ? { ownerSessionId: value.ownerSessionId } : {}),
     ...(value.ownerSessionFile ? { ownerSessionFile: value.ownerSessionFile } : {}),
+    ...(isRecord(model) && typeof model.provider === "string" && typeof model.id === "string"
+      ? { model: { provider: model.provider, id: model.id } }
+      : {}),
   };
 }
 
@@ -523,12 +588,13 @@ export function formatLoopWidget(state: LoopState, width: number, now = Date.now
   const retries = (state.retryCount ?? 0) > 0
     ? ` · retry ${state.retryCount}/${DEFAULT_LOOP_RETRIES}`
     : "";
-  if (state.status === "stopping") {
-    return truncateToWidth(`loop stopping${timeframe}${delay}${retries} · ${prompt}`, width, "…");
+  const iteration = state.endsAt === undefined ? "" : ` · #${state.currentIteration}`;
+  if (state.status === "pausing" || state.status === "stopping") {
+    return truncateToWidth(`loop ${state.status}${iteration}${timeframe}${delay}${retries} · ${prompt}`, width, "…");
   }
   if (state.endsAt !== undefined) {
     return truncateToWidth(
-      `loop ${state.status}${timeframe}${delay}${retries} · ${prompt}`,
+      `loop ${state.status}${iteration}${timeframe}${delay}${retries} · ${prompt}`,
       width,
       "…",
     );
@@ -572,15 +638,36 @@ export default function loopExtension(pi: ExtensionAPI): void {
   let commandInterruptedKey: string | undefined;
   let pendingFailure: PendingFailure | undefined;
   let currentSessionManagerRef: unknown;
+  let herdrBlocked = false;
+
+  function reportHerdrBlocked(state: LoopState | undefined): void {
+    const blocked = state?.status === "paused";
+    if (blocked === herdrBlocked) return;
+    herdrBlocked = blocked;
+    pi.events.emit("herdr:blocked", blocked
+      ? { active: true, label: `Loop paused: ${state.pauseReason ?? "human input required"}`, scope: "root" }
+      : { active: false, scope: "root" });
+  }
 
   function stateFrom(ctx: ContextWithSession): LoopState | undefined {
     runState = latestStateFromContext(ctx);
     return runState;
   }
 
+  function syncLoopEnvironment(state: LoopState | undefined): void {
+    const runId = state?.runId;
+    if (state && statusIsVisible(state)) {
+      exposeLoopRunId(state.runId);
+      return;
+    }
+    if (!transitionInFlight) restoreLoopRunId(runId);
+  }
+
   function persist(ctx: Pick<ExtensionAPI, "appendEntry">, state: LoopState): void {
     ctx.appendEntry(LOOP_STATE_ENTRY, state);
     runState = state;
+    syncLoopEnvironment(state);
+    reportHerdrBlocked(state);
   }
 
   function notify(ctx: ExtensionContext, message: string, type: "info" | "warning" | "error" = "info"): void {
@@ -602,6 +689,8 @@ export default function loopExtension(pi: ExtensionAPI): void {
       ctx.ui.setWidget(LOOP_WIDGET_KEY, [formatLoopWidget(state, Number.MAX_SAFE_INTEGER)], { placement: "belowEditor" });
       return;
     }
+    // Replacing the widget invalidates Pi's parent layout caches. Requesting a
+    // render alone can leave the previous line visible until another UI event.
     ctx.ui.setWidget(LOOP_WIDGET_KEY, (_tui, _theme) => ({
       render: (width) => [formatLoopWidget(state, width)],
       invalidate: () => {},
@@ -625,8 +714,11 @@ export default function loopExtension(pi: ExtensionAPI): void {
     }
     if (currentSessionManagerRef !== undefined && sessionManager !== currentSessionManagerRef) return undefined;
     const loaded = stateFrom(ctx);
-    if (!loaded) return undefined;
-    if (!stateBelongsToContext(loaded, ctx)) return undefined;
+    if (!loaded || !stateBelongsToContext(loaded, ctx)) {
+      reportHerdrBlocked(undefined);
+      return undefined;
+    }
+    reportHerdrBlocked(loaded);
     return loaded;
   }
 
@@ -679,7 +771,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
   ): void {
     if (!statusIsActive(state) || transitionInFlight) return;
     const nextBudget = state.pendingRetune ?? state.remainingBudget;
-    if (state.status === "stopping" || (state.endsAt === undefined && nextBudget <= 0) || state.delay === 0) {
+    if (state.status === "pausing" || state.status === "stopping" || (state.endsAt === undefined && nextBudget <= 0) || state.delay === 0) {
       clearContinuationWait();
       dispatchContinuation(ctx, state);
       return;
@@ -845,6 +937,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
 
   function transferState(state: LoopState, manager: SessionManager): LoopState {
     const transferred = stateForSession({ ...state, status: "active" }, sessionIdentity(manager));
+    exposeLoopRunId(transferred.runId);
     manager.appendCustomEntry(LOOP_STATE_ENTRY, transferred);
     return transferred;
   }
@@ -853,9 +946,17 @@ export default function loopExtension(pi: ExtensionAPI): void {
     replacement: ReplacementContext,
     state: LoopState,
   ): Promise<void> {
-    // The new extension instance restores this entry in before_agent_start.
-    // This callback still owns the command context, so it is the safe place to
-    // start the turn after the replacement is complete.
+    // The replacement owns the new extension runtime. Restore its model before
+    // starting a turn, rather than using the invalidated previous runtime.
+    if (state.model) {
+      await replacement.sendUserMessage(
+        `/loop __restore_model ${state.runId} ${state.currentIteration}`,
+        { expandPromptTemplates: true },
+      );
+      if (replacement.model?.provider !== state.model.provider || replacement.model.id !== state.model.id) {
+        throw new Error(`loop model unavailable: ${state.model.provider}/${state.model.id}`);
+      }
+    }
     if (replacement.hasUI) showWidget(replacement, state);
     if (state.endsAt !== undefined && Date.now() >= state.endsAt) {
       await replacement.sendUserMessage(
@@ -868,6 +969,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
   }
 
   async function replaceForIteration(ctx: ExtensionCommandContext, next: LoopState): Promise<void> {
+    exposeLoopRunId(next.runId);
     clearContinuationWait();
     clearRetryWait();
     clearRecoveryTimer();
@@ -971,6 +1073,27 @@ export default function loopExtension(pi: ExtensionAPI): void {
     clearContinuationWait();
     clearRetryWait();
 
+    if (state.status === "pausing") {
+      const {
+        nextActionAt: _nextActionAt,
+        pauseReason: _pauseReason,
+        ...withoutSchedule
+      } = state;
+      const paused: LoopState = {
+        ...withoutSchedule,
+        status: "paused",
+        phase: "waiting",
+        settledAt: Date.now(),
+        pauseReason: "paused by user",
+        pausedAt: Date.now(),
+      };
+      persist(pi, paused);
+      renderWidget(ctx, paused);
+      runState = paused;
+      notify(ctx, "loop paused", "info");
+      return;
+    }
+
     if (state.status === "stopping") {
       const stopped = { ...state, status: "stopped" as const };
       persist(pi, stopped);
@@ -1007,6 +1130,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
     } = state;
     const next: LoopState = {
       ...withoutPause,
+      ...(ctx.model ? { model: { provider: ctx.model.provider, id: ctx.model.id } } : {}),
       currentIteration: state.currentIteration + 1,
       remainingBudget: state.endsAt === undefined ? nextBudget - 1 : 0,
       pendingRetune: null,
@@ -1058,6 +1182,16 @@ export default function loopExtension(pi: ExtensionAPI): void {
       return;
     }
 
+    if (parsed.kind === "restoreModel") {
+      const state = currentState(ctx);
+      if (!state || state.runId !== parsed.runId || state.currentIteration !== parsed.iteration || !state.model) return;
+      const model = ctx.modelRegistry.find(state.model.provider, state.model.id);
+      if (!model || !(await pi.setModel(model))) {
+        throw new Error(`loop model unavailable: ${state.model.provider}/${state.model.id}`);
+      }
+      return;
+    }
+
     if (parsed.kind === "pause") {
       const state = currentState(ctx);
       if (!state || state.runId !== parsed.runId || state.currentIteration !== parsed.iteration || !statusIsActive(state)) return;
@@ -1075,6 +1209,41 @@ export default function loopExtension(pi: ExtensionAPI): void {
       return;
     }
 
+    if (parsed.kind === "time") {
+      if (!state || isTerminal(state)) {
+        notify(ctx, "a loop must be active, stopping, or paused to update its remaining time", "error");
+        return;
+      }
+      if (state.delay === 0) {
+        notify(ctx, "timed loops require a non-zero delay; set /loop delay <duration> first", "error");
+        return;
+      }
+      const switchingModes = state.endsAt === undefined;
+      const endsAt = Date.now() + parsed.duration;
+      const nextActionAt = state.phase === "waiting" && state.nextActionAt !== undefined
+        ? Math.min((state.settledAt ?? state.nextActionAt - state.delay) + state.delay, endsAt)
+        : state.nextActionAt;
+      const updated = {
+        ...state,
+        remainingBudget: 0,
+        pendingRetune: null,
+        endsAt,
+        ...(nextActionAt !== undefined ? { nextActionAt } : {}),
+      };
+      persist(pi, updated);
+      renderWidget(ctx, updated);
+      if (state.status === "active") rescheduleContinuation(ctx, updated);
+      const duration = formatLoopDelay(parsed.duration);
+      if (state.status === "paused") {
+        notify(ctx, `loop ${switchingModes ? `changed to timed mode with ${duration} left` : `time left set to ${duration}`}; resume will use it`, "info");
+      } else if (state.status === "stopping") {
+        notify(ctx, `loop ${switchingModes ? `changed to timed mode with ${duration} left` : `time left set to ${duration}`}; loop is still stopping`, "info");
+      } else {
+        notify(ctx, switchingModes ? `loop changed to timed mode with ${duration} left` : `loop time left set to ${duration}`, "info");
+      }
+      return;
+    }
+
     if (parsed.kind === "delay") {
       if (!state || isTerminal(state)) {
         notify(ctx, "a loop must be active, stopping, or paused to update its delay", "error");
@@ -1108,6 +1277,35 @@ export default function loopExtension(pi: ExtensionAPI): void {
       return;
     }
 
+    if (parsed.kind === "pauseAtBoundary") {
+      if (!state || isTerminal(state)) {
+        notify(ctx, "a loop must be active to pause", "error");
+        return;
+      }
+      if (state.status === "paused") {
+        notify(ctx, "loop is already paused", "info");
+        return;
+      }
+      if (state.status === "pausing") {
+        notify(ctx, "loop will pause after the active iteration", "info");
+        return;
+      }
+      if (state.phase === "retrying") {
+        pauseLoop(ctx, state, "paused by user");
+        notify(ctx, "loop paused", "info");
+        return;
+      }
+      const pausing: LoopState = { ...state, status: "pausing" };
+      persist(pi, pausing);
+      renderWidget(ctx, pausing);
+      if (state.phase === "waiting") {
+        await advanceAtBoundary(ctx, pausing.runId, pausing.currentIteration);
+        return;
+      }
+      notify(ctx, "loop will pause after the active iteration", "info");
+      return;
+    }
+
     if (parsed.kind === "end") {
       if (!state || state.status === "inactive" || state.status === "completed" || state.status === "stopped") {
         notify(ctx, "loop: no active run", "info");
@@ -1145,7 +1343,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
     }
 
     if (parsed.kind === "resume") {
-      if (state?.status === "stopping") {
+      if (state?.status === "pausing" || state?.status === "stopping") {
         const resumed = { ...state, status: "active" as const };
         persist(pi, resumed);
         renderWidget(ctx, resumed);
@@ -1160,6 +1358,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
         await advanceAtBoundary(ctx, state.runId, state.currentIteration, true);
         return;
       }
+      const pausedAtBoundary = state.phase === "waiting";
       const {
         pauseReason: _pauseReason,
         pausedAt: _pausedAt,
@@ -1176,7 +1375,11 @@ export default function loopExtension(pi: ExtensionAPI): void {
       persist(pi, resumed);
       renderWidget(ctx, resumed);
       handledSettlementKey = undefined;
-      continueCurrentIteration(ctx, resumed);
+      if (pausedAtBoundary) {
+        await advanceAtBoundary(ctx, resumed.runId, resumed.currentIteration);
+      } else {
+        continueCurrentIteration(ctx, resumed);
+      }
       return;
     }
 
@@ -1214,12 +1417,18 @@ export default function loopExtension(pi: ExtensionAPI): void {
     }
 
     if (parsed.kind === "retune" || parsed.kind === "adjust") {
-      if (!state || (state.status !== "active" && state.status !== "stopping")) {
-        notify(ctx, "a loop must be active to retune its remaining budget", "error");
+      const canRetune = state && (
+        state.status === "active" ||
+        state.status === "stopping" ||
+        (parsed.kind === "retune" && state.status === "paused")
+      );
+      if (!canRetune) {
+        notify(ctx, "a loop must be active, stopping, or paused to retune its remaining budget", "error");
         return;
       }
-      if (state.endsAt !== undefined) {
-        notify(ctx, "a timed loop has no iteration budget to retune", "error");
+      const switchingModes = state.endsAt !== undefined;
+      if (switchingModes && parsed.kind === "adjust") {
+        notify(ctx, "a timed loop has no iteration budget to adjust; use /loop <positive-count> to switch modes", "error");
         return;
       }
       const currentBudget = state.pendingRetune ?? state.remainingBudget;
@@ -1228,11 +1437,20 @@ export default function loopExtension(pi: ExtensionAPI): void {
         notify(ctx, `cannot subtract more than the ${currentBudget} future iteration${currentBudget === 1 ? "" : "s"}`, "error");
         return;
       }
-      const retuned = { ...state, pendingRetune: nextBudget, status: "active" as const };
+      const { endsAt: _endsAt, ...withoutDeadline } = state;
+      const retuned = {
+        ...withoutDeadline,
+        pendingRetune: nextBudget,
+        status: state.status === "paused" ? "paused" as const : "active" as const,
+      };
       persist(pi, retuned);
       renderWidget(ctx, retuned);
-      if (nextBudget <= 0) rescheduleContinuation(ctx, retuned);
-      notify(ctx, `loop will run ${nextBudget} future iteration${nextBudget === 1 ? "" : "s"}`, "info");
+      if (switchingModes || nextBudget <= 0) rescheduleContinuation(ctx, retuned);
+      if (state.status === "paused") {
+        notify(ctx, `loop ${switchingModes ? "changed to" : "set to"} ${nextBudget} future iteration${nextBudget === 1 ? "" : "s"}; resume will use it`, "info");
+      } else {
+        notify(ctx, `loop ${switchingModes ? "changed to" : "will run"} ${nextBudget} future iteration${nextBudget === 1 ? "" : "s"}`, "info");
+      }
       return;
     }
 
@@ -1257,6 +1475,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
       status: "active",
       retryCount: 0,
       phase: "running",
+      ...(ctx.model ? { model: { provider: ctx.model.provider, id: ctx.model.id } } : {}),
       ...(timed ? { endsAt: Date.now() + parsed.duration } : {}),
       ...(contextIdentity(ctx).id ? { ownerSessionId: contextIdentity(ctx).id } : {}),
       ...(contextIdentity(ctx).file ? { ownerSessionFile: contextIdentity(ctx).file } : {}),
@@ -1309,6 +1528,8 @@ export default function loopExtension(pi: ExtensionAPI): void {
     const loaded = latestStateFromContext(ctx);
     const owned = loaded && stateBelongsToContext(loaded, ctx) ? loaded : undefined;
     runState = owned;
+    syncLoopEnvironment(owned);
+    reportHerdrBlocked(owned);
     if (!owned || owned.status === "inactive") clearWidget(ctx);
     else renderWidget(ctx, owned);
     // New-session setup writes transferred state after this event and starts
@@ -1387,6 +1608,8 @@ export default function loopExtension(pi: ExtensionAPI): void {
     const loaded = latestStateFromContext(ctx);
     const owned = loaded && stateBelongsToContext(loaded, ctx) ? loaded : undefined;
     runState = owned;
+    syncLoopEnvironment(owned);
+    reportHerdrBlocked(owned);
     if (!owned || owned.status === "inactive") clearWidget(ctx);
     else renderWidget(ctx, owned);
     if (owned && statusIsActive(owned)) scheduleStartupRecovery(ctx, owned);
@@ -1406,6 +1629,8 @@ export default function loopExtension(pi: ExtensionAPI): void {
         // Shutdown may already have detached the runtime's append action.
       }
     }
+    if (event.reason !== "reload" && !transitionInFlight) restoreLoopRunId(loaded?.runId);
+    reportHerdrBlocked(undefined);
     clearWidget(ctx);
     currentSessionManagerRef = undefined;
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brettinternet/pi-loop",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Run a prompt repeatedly in fresh Pi sessions",
   "type": "module",
   "license": "MIT",