pi-better-goal 0.4.1 → 0.6.0

package/README.md

@@ -13,11 +13,11 @@ Use `pi-better-goal` when a Pi session should keep an explicit objective visible
 ## Core Features
 
 - `/goal` runtime for starting, pausing, resuming, completing, and clearing the current objective.
-- `escape` pauses the active goal and your next message resumes it; `/goal pause` stays paused until `/goal resume`. Paused goals are never poked.
+- `escape` pauses the active goal, and it stays paused while you talk to the agent. Say "go" (the agent then calls `goal_resume`), or use `/goal resume` or `alt+g`. `/goal pause` resumes only through `/goal resume` or `alt+g`. The status line shows `goal paused · say "go" or /goal resume`, and paused goals are never poked. On a macOS terminal without Option-as-Meta, `alt+g` types `©`; use `/goal resume` there.
 - Background work that finishes while an `ask_user_question` is pending is handed to the agent right after the answer.
 - A compact goal widget that does not replace Pi's footer.
 - Background activity tracking for subagents and other registered providers.
-- A progress-aware follow-up loop that holds after repeated identical outcomes.
+- A progress-aware follow-up loop with ten identical no-progress retries and linear backoff (30s through 300s by default), followed by a hold recoverable with `/goal resume`. Delays saturate at Node's timer limit, and observed background drains reset progress before callback turns can cancel the wake. Pi's network retry policy remains independent.
 - An observable-progress stall state for active goals.
 
 ## Skill-Owned Workflows

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-goal",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Pi extension for goal tracking with background-aware continuation.",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,7 @@
   "scripts": {
     "pretest": "node ../../scripts/sync-shared-log-utils.mjs",
     "prepack": "node ../../scripts/sync-shared-log-utils.mjs",
-    "test": "node --import tsx --test test/*.test.ts",
+    "test": "node --import tsx --import ../../scripts/isolate-registry.mjs --test test/*.test.ts",
     "typecheck": "tsc --noEmit",
     "verify": "npm run typecheck && npm test"
   },

package/src/index.ts

@@ -51,7 +51,8 @@ import {
 
 const POLL_INTERVAL_MS = 2_000;
 const DEFAULT_IDLE_CONTINUATION_DELAY_MS = 30_000;
-const DEFAULT_MAX_NO_PROGRESS_RETRIES = 3;
+const DEFAULT_MAX_NO_PROGRESS_RETRIES = 10;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
 const WAKE_DISABLED =
   process.env.PI_BETTER_GOAL_DISABLE_WAKE === "1" ||
   process.env.PI_BETTER_EXTENSION_DISABLE_WAKE === "1";
@@ -70,6 +71,34 @@ const MAX_NO_PROGRESS_RETRIES = parseRetryLimit(
  * steering after the whole tool batch, and callback batches are follow-ups
  * that wait for the entire run), so the goal harvests them explicitly.
  */
+/** Model-callable resume, active only while an escape-paused goal waits. */
+export const GOAL_RESUME_TOOL = "goal_resume";
+/** Hotkey that resumes any paused goal, like `/goal resume`. */
+export const GOAL_RESUME_SHORTCUT = "alt+g";
+
+/** When the agent may call `goal_resume`; shared by the tool description and the paused prompt. */
+const GOAL_RESUME_RULE =
+  "Call goal_resume only when the user's latest message clearly says to proceed (for example \"go\", \"continue\", \"ok do it\", \"approved, proceed\"), " +
+  "or answers a decision you explicitly asked for in your previous message with a choice that means proceed. Never call it for questions, \"why...\", \"what about...\", \"let me think\", or discussion.";
+
+/** True when the agent may resume this goal with `goal_resume`. */
+export function agentResumable(goal: GoalSnapshot | null): boolean {
+  return goal?.status === "paused" && goal.pauseReason === "interrupt";
+}
+
+/** Footer status for a paused goal, telling the user how to resume it. */
+export function pausedGoalStatus(goal: GoalSnapshot): string {
+  return agentResumable(goal) ? 'goal paused · say "go" or /goal resume' : "goal paused · /goal resume";
+}
+
+function pausedGoalPrompt(goal: GoalSnapshot): string {
+  return [
+    `Pi Better Goal is paused because the user pressed escape. Goal: ${goal.objective}`,
+    "Treat the user's messages as ordinary conversation: answer them, but do not continue the goal's work until it is resumed.",
+    GOAL_RESUME_RULE,
+  ].join("\n");
+}
+
 const BLOCKING_QUESTION_TOOLS: ReadonlySet<string> = new Set(["ask_user_question"]);
 
 const GOAL_ACTIONS: readonly AutocompleteItem[] = [
@@ -93,6 +122,14 @@ function parseDurationEnv(raw: string | undefined, fallback: number): number {
   return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
 }
 
+/**
+ * Linear backoff for no-progress retries: each identical outcome waits one more
+ * grace period than the last (30s, 60s, 90s, ... by default).
+ */
+export function idleContinuationDelay(noProgressRetries: number, baseMs = IDLE_CONTINUATION_DELAY_MS): number {
+  return Math.min(MAX_TIMER_DELAY_MS, baseMs * (1 + Math.max(0, noProgressRetries)));
+}
+
 function parseRetryLimit(raw: string | undefined, fallback: number): number {
   if (raw === undefined || raw.trim() === "") {
     return fallback;
@@ -195,6 +232,11 @@ function formatGoal(
     `Elapsed time: ${timing.elapsedSeconds}s`,
     `Observable progress: ${stall?.state ?? "unknown"}`,
     continuationStatus,
+    ...(goal.status === "paused"
+      ? [agentResumable(goal)
+        ? 'Resume: say "go" (the agent calls goal_resume), /goal resume, or alt+g'
+        : "Resume: /goal resume or alt+g"]
+      : []),
   ].join("\n");
 }
 
@@ -224,13 +266,18 @@ export default function (pi: ExtensionAPI): void {
   });
 
   let currentCtx: ExtensionContext | undefined;
+  let executionGeneration = 0;
+  let agentGeneration = -1;
+  let sessionGeneration = 0;
+  let wakeGeneration = 0;
+  let snapshotSequence = 0;
+  let lastAppliedSnapshotSequence = 0;
   let foregroundRunning = false;
   let pollTimer: ReturnType<typeof setInterval> | undefined;
   let collecting = false;
   let collectionPending = false;
   let latestSnapshot: ActivitySnapshot | null = null;
   let backgroundDrainTracker: BackgroundDrainTracker | null = null;
-  let lastWakeSignature = "";
   let lastAttentionSignature = "";
   let continuationQueuedFor: string | null = null;
   let idleContinuationTimer: ReturnType<typeof setTimeout> | undefined;
@@ -297,6 +344,8 @@ export default function (pi: ExtensionAPI): void {
   };
 
   const setGoal = (goal: GoalSnapshot, ctx: ExtensionContext, source: GoalEntrySource): void => {
+    executionGeneration += 1;
+    lastAgentEvidence = null;
     const previous = getGoal(ctx);
     const wasVisible = previous !== null && isGoalClockVisible(previous);
     pi.appendEntry(EXTENSION_NAME, goalSetEntry(goal, source));
@@ -304,11 +353,15 @@ export default function (pi: ExtensionAPI): void {
     backgroundDrainTracker = null;
     clearIdleContinuation();
     syncPollingState();
+    syncResumeTool(goal);
+    applyStatus(ctx);
     // Force a full redraw when the dock height changes (absent ↔ visible clock).
     refreshGoalWidget?.(!wasVisible || !isGoalClockVisible(goal));
   };
 
   const clearGoal = (ctx: ExtensionContext, source: GoalEntrySource): void => {
+    executionGeneration += 1;
+    lastAgentEvidence = null;
     const current = getGoal(ctx);
     const wasVisible = current !== null && isGoalClockVisible(current);
     pi.appendEntry(EXTENSION_NAME, goalClearEntry(current?.goalId ?? null, source));
@@ -317,14 +370,16 @@ export default function (pi: ExtensionAPI): void {
     backgroundDrainTracker = null;
     clearIdleContinuation();
     syncPollingState();
+    syncResumeTool(null);
+    applyStatus(ctx);
     refreshGoalWidget?.(wasVisible);
   };
 
   /**
-   * An interrupt (escape, or anything else that aborts the running turn) is a
-   * soft pause: it stops autonomous continuation now, and the user's next
-   * conversational message resumes the goal once that exchange settles. Only
-   * `/goal pause` (or an unavailable command/workflow) is a sticky pause.
+   * An interrupt (escape, or anything else that aborts the running turn) pauses
+   * the goal. It stays paused while the user talks: messages are ordinary
+   * conversation. It resumes through `/goal resume`, the hotkey, or the agent's
+   * `goal_resume` once the user clearly says to proceed.
    */
   const pauseGoalOnInterrupt = (ctx: ExtensionContext): void => {
     const goal = getGoal(ctx);
@@ -332,7 +387,7 @@ export default function (pi: ExtensionAPI): void {
       return;
     }
     setGoal(goalWithStatus(goal, "paused", undefined, "interrupt"), ctx, "runtime");
-    notifyGoal(ctx, "Goal paused (interrupted). Send a message to resume it after that exchange, or use /goal pause to keep it paused.");
+    notifyGoal(ctx, 'Goal paused. Say "go" to resume it, or use /goal resume.');
   };
 
   /** Why a paused goal cannot become active again, or null when it can. */
@@ -346,6 +401,29 @@ export default function (pi: ExtensionAPI): void {
     return null;
   };
 
+  /**
+   * The one resume path shared by `/goal resume`, the hotkey, and `goal_resume`:
+   * reactivate a paused goal or reopen an active no-progress hold.
+   */
+  const resumeGoal = (
+    ctx: ExtensionContext,
+    source: GoalEntrySource,
+  ): { ok: true; goal: GoalSnapshot } | { ok: false; message: string } => {
+    const current = getGoal(ctx);
+    const held = current?.status === "active" && currentContinuationState(ctx, current.goalId)?.blocked === true;
+    if (!current || (current.status !== "paused" && !held)) {
+      return { ok: false, message: "Only paused or no-progress-held goals can be resumed." };
+    }
+    const blocker = resumeBlocker(current);
+    if (blocker) {
+      return { ok: false, message: blocker };
+    }
+    const goal = held ? current : goalWithStatus(current, "active");
+    setGoal(goal, ctx, source);
+    queueGoalContinuation(goal, ctx);
+    return { ok: true, goal };
+  };
+
   const boundCommandReady = (goal: GoalSnapshot, ctx: ExtensionContext): boolean => {
     if (!goal.command || commandAvailable(pi, goal.command)) return true;
     setGoal(goalWithStatus(goal, "paused"), ctx, "runtime");
@@ -378,6 +456,7 @@ export default function (pi: ExtensionAPI): void {
   };
 
   function clearIdleContinuation(): void {
+    wakeGeneration += 1;
     if (idleContinuationTimer) {
       clearTimeout(idleContinuationTimer);
       idleContinuationTimer = undefined;
@@ -398,7 +477,8 @@ export default function (pi: ExtensionAPI): void {
       return;
     }
     const signature = `${goal.goalId}:${kind}`;
-    if (idleContinuationTimer && idleContinuationSignature === signature) {
+    if (idleContinuationTimer && (idleContinuationSignature === signature ||
+        (kind === "continuation" && idleContinuationSignature === `${goal.goalId}:background-drained`))) {
       return;
     }
     clearIdleContinuation();
@@ -407,7 +487,7 @@ export default function (pi: ExtensionAPI): void {
       idleContinuationTimer = undefined;
       idleContinuationSignature = "";
       void sendIdleContinuationAfterAudit(goal.goalId, ctx, kind, snapshot);
-    }, IDLE_CONTINUATION_DELAY_MS);
+    }, idleContinuationDelay(kind === "continuation" ? currentContinuationState(ctx, goal.goalId)?.noProgressRetries ?? 0 : 0));
     idleContinuationTimer.unref?.();
   };
 
@@ -417,22 +497,20 @@ export default function (pi: ExtensionAPI): void {
     kind: "continuation" | "background-drained",
     priorSnapshot?: ActivitySnapshot,
   ): Promise<void> => {
+    const execution = executionGeneration;
+    const wake = wakeGeneration;
+    const auditIsCurrent = (): boolean => {
+      if (execution !== executionGeneration || wake !== wakeGeneration) return false;
+      const current = currentGoalSnapshot(ctx);
+      return isPokeable(current) && current.goalId === goalId &&
+        continuationQueuedFor !== goalId && !isForegroundBusy(ctx);
+    };
     const goal = currentGoalSnapshot(ctx);
-    if (!isPokeable(goal) || goal.goalId !== goalId || continuationQueuedFor === goal.goalId || foregroundRunning) {
-      return;
-    }
+    if (!auditIsCurrent() || !isPokeable(goal)) return;
     if (!boundCommandReady(goal, ctx)) return;
-    const snapshot = await collectActivitySnapshot(ctx, providers.values(), foregroundRunning);
-    latestSnapshot = snapshot;
-    pi.events.emit(EVENT_ACTIVITY, snapshot);
-    if (snapshot.foregroundRunning || snapshot.backgroundRunning) {
-      return;
-    }
+    const snapshot = await publishSnapshot(ctx);
+    if (!snapshot || !auditIsCurrent() || snapshot.foregroundRunning || snapshot.backgroundRunning) return;
 
-    // A background drain is a meaningful external state transition and reopens a held goal.
-    if (kind === "background-drained") {
-      resetContinuationState(goal);
-    }
     continuationQueuedFor = goal.goalId;
     const content = kind === "background-drained"
       ? "Background activity for the active goal is no longer running. Inspect any subagent callbacks or final results, then continue the completion audit before marking the goal complete.\n\n" +
@@ -475,64 +553,94 @@ export default function (pi: ExtensionAPI): void {
     return goal;
   };
 
-  const publishSnapshot = async (ctx: ExtensionContext): Promise<ActivitySnapshot> => {
+  const publishSnapshot = async (ctx: ExtensionContext): Promise<ActivitySnapshot | null> => {
+    const execution = executionGeneration;
+    const sequence = ++snapshotSequence;
     const snapshot = await collectActivitySnapshot(ctx, providers.values(), foregroundRunning);
+    if (execution !== executionGeneration) return null;
+    if (sequence < lastAppliedSnapshotSequence) return latestSnapshot;
+    lastAppliedSnapshotSequence = sequence;
     latestSnapshot = snapshot;
-    pi.events.emit(EVENT_ACTIVITY, snapshot);
 
+    const goal = currentGoalSnapshot(ctx);
+    const wakePlan = planBackgroundDrainWake(backgroundDrainTracker, goal, snapshot);
+    backgroundDrainTracker = wakePlan.nextTracker;
+    if (isPokeable(goal) && wakePlan.wakeSignature) {
+      // Persist external progress now: a foreground/callback turn may cancel its delayed wake.
+      clearIdleContinuation();
+      resetContinuationState(goal);
+      lastAgentEvidence = null;
+      scheduleIdleContinuation(goal, ctx, "background-drained", snapshot);
+    }
+
+    if (snapshot.foregroundRunning || snapshot.backgroundRunning) {
+      clearIdleContinuation();
+    }
+
+    pi.events.emit(EVENT_ACTIVITY, snapshot);
+    if (execution !== executionGeneration) return null;
     const attention = terminalAttentionSignature(snapshot);
     if (attention && attention !== lastAttentionSignature) {
       lastAttentionSignature = attention;
       pi.events.emit(EVENT_TERMINAL_ATTENTION, snapshot);
+      if (execution !== executionGeneration) return null;
     }
+    applyStatus(ctx);
 
-    if (!WAKE_DISABLED) {
-      const goal = currentGoalSnapshot(ctx);
-      const wakePlan = planBackgroundDrainWake(backgroundDrainTracker, goal, snapshot);
-      backgroundDrainTracker = wakePlan.nextTracker;
-      if (isPokeable(goal) && wakePlan.wakeSignature) {
-        const wakeSignature = wakePlan.wakeSignature;
-        if (wakeSignature !== lastWakeSignature) {
-          lastWakeSignature = wakeSignature;
-          scheduleIdleContinuation(goal, ctx, "background-drained", snapshot);
-        }
-      }
-    }
-
-    if (snapshot.foregroundRunning || snapshot.backgroundRunning) {
-      clearIdleContinuation();
-    }
+    return snapshot;
+  };
 
-    if (ctx.hasUI) {
-      const goal = getGoal(ctx);
-      const continuation = goal ? currentContinuationState(ctx, goal.goalId) : null;
-      const goalStall = observeGoalStall(goal, continuation, {
-        foregroundRunning,
-        backgroundRunning: latestSnapshot?.backgroundRunning ?? false,
-      });
-      let waitingOnAnswer = 0;
+  /** Footer status from the goal state and the latest activity snapshot. */
+  const statusText = (ctx: ExtensionContext, snapshot: ActivitySnapshot | null): string | undefined => {
+    const goal = getGoal(ctx);
+    let waitingOnAnswer = 0;
+    if (snapshot) {
       for (const activeAtStart of pendingQuestions.values()) {
         waitingOnAnswer += finishedSinceQuestion(activeAtStart, snapshot).length;
       }
-      const status = waitingOnAnswer > 0
-        ? `${waitingOnAnswer} background done; waiting on your answer`
-        : snapshot.backgroundRunning
-        ? `bg ${snapshot.activeBackgroundCount}${snapshot.unhealthyBackgroundCount ? `, ${snapshot.unhealthyBackgroundCount} unhealthy` : ""}`
-        : continuation?.blocked
-          ? "waiting: no progress"
-          : goalStall?.state === "stalled"
-            ? "goal stalled"
-          : undefined;
-      try {
-        ctx.ui.setStatus(EXTENSION_NAME, status);
-      } catch {
-        // UI status is best-effort only.
-      }
     }
-
-    return snapshot;
+    if (waitingOnAnswer > 0) return `${waitingOnAnswer} background done; waiting on your answer`;
+    const background = snapshot?.backgroundRunning
+      ? `bg ${snapshot.activeBackgroundCount}${snapshot.unhealthyBackgroundCount ? `, ${snapshot.unhealthyBackgroundCount} unhealthy` : ""}`
+      : undefined;
+    if (goal?.status === "paused") return background ? `${pausedGoalStatus(goal)} · ${background}` : pausedGoalStatus(goal);
+    if (background) return background;
+    const continuation = goal ? currentContinuationState(ctx, goal.goalId) : null;
+    if (continuation?.blocked) return "waiting: no progress";
+    const goalStall = observeGoalStall(goal, continuation, {
+      foregroundRunning,
+      backgroundRunning: snapshot?.backgroundRunning ?? false,
+    });
+    return goalStall?.state === "stalled" ? "goal stalled" : undefined;
   };
 
+  function applyStatus(ctx: ExtensionContext): void {
+    if (!ctx.hasUI) return;
+    try {
+      ctx.ui.setStatus(EXTENSION_NAME, statusText(ctx, latestSnapshot));
+    } catch {
+      // UI status is best-effort only.
+    }
+  }
+
+  /**
+   * `goal_resume` is in the model's tool list only while an escape-paused goal
+   * waits. Pi activates newly registered tools by default, so this also removes
+   * it at session start. Only this one tool is toggled; other extensions' tool
+   * choices are left as they are.
+   */
+  function syncResumeTool(goal: GoalSnapshot | null): void {
+    if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
+    try {
+      const active = pi.getActiveTools();
+      const wanted = agentResumable(goal);
+      if (active.includes(GOAL_RESUME_TOOL) === wanted) return;
+      pi.setActiveTools(wanted ? [...active, GOAL_RESUME_TOOL] : active.filter((name) => name !== GOAL_RESUME_TOOL));
+    } catch {
+      // Tool activation is unavailable before Pi binds the session; the tool also refuses on its own.
+    }
+  }
+
   const collectIfPossible = (): void => {
     const ctx = currentCtx;
     if (!ctx) {
@@ -543,7 +651,9 @@ export default function (pi: ExtensionAPI): void {
       return;
     }
     collecting = true;
+    const session = sessionGeneration;
     void publishSnapshot(ctx).finally(() => {
+      if (session !== sessionGeneration) return;
       collecting = false;
       if (collectionPending) {
         collectionPending = false;
@@ -675,18 +785,11 @@ export default function (pi: ExtensionAPI): void {
       }
 
       if (trimmed === "resume") {
-        if (!current || current.status !== "paused") {
-          notifyGoal(ctx, "Only paused goals can be resumed.", "warning");
-          return;
-        }
-        const blocker = resumeBlocker(current);
-        if (blocker) {
-          notifyGoal(ctx, blocker, "error");
+        const result = resumeGoal(ctx, "command");
+        if (!result.ok) {
+          notifyGoal(ctx, result.message, current?.status === "paused" ? "error" : "warning");
           return;
         }
-        const goal = goalWithStatus(current, "active");
-        setGoal(goal, ctx, "command");
-        queueGoalContinuation(goal, ctx);
         notifyGoal(ctx, "Goal resumed.");
         return;
       }
@@ -789,12 +892,51 @@ export default function (pi: ExtensionAPI): void {
     },
   });
 
+  pi.registerTool({
+    name: GOAL_RESUME_TOOL,
+    label: "Resume Goal",
+    description:
+      "Resume the goal the user paused with escape, exactly like /goal resume. " + GOAL_RESUME_RULE,
+    promptSnippet: "Resume the escape-paused goal, only on the user's clear go-ahead.",
+    parameters: Type.Object({
+      reason: Type.Optional(Type.String({ description: "Short quote or summary of the user's go-ahead." })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const reason = (params as { reason?: string }).reason;
+      const current = getGoal(ctx);
+      if (!agentResumable(current)) {
+        const text = current?.status === "paused"
+          ? "This goal was paused with /goal pause or by the runtime. Only the user can resume it, with /goal resume."
+          : "No goal is paused, so there is nothing to resume.";
+        return { content: [{ type: "text", text }], details: { ok: false, goal: current } };
+      }
+      const result = resumeGoal(ctx, "tool");
+      if (!result.ok) {
+        return { content: [{ type: "text", text: `Goal stays paused. ${result.message}` }], details: { ok: false, goal: getGoal(ctx) } };
+      }
+      return {
+        content: [{ type: "text", text: "Goal resumed. Its continuation runs after this turn." }],
+        details: { ok: true, goal: result.goal, ...(reason ? { reason } : {}) },
+      };
+    },
+  });
+
+  pi.registerShortcut?.(GOAL_RESUME_SHORTCUT, {
+    description: "Resume the paused goal",
+    handler: (ctx) => {
+      currentCtx = ctx;
+      const result = resumeGoal(ctx, "command");
+      notifyGoal(ctx, result.ok ? "Goal resumed." : result.message, result.ok ? "info" : "warning");
+    },
+  });
+
   pi.registerCommand("better-activity", {
     description: "Show foreground/background activity known to pi-better-goal",
     handler: async (_args, ctx) => {
       currentCtx = ctx;
       const snapshot = await publishSnapshot(ctx);
-      ctx.ui.notify(formatSnapshot(snapshot), snapshot.backgroundRunning ? "info" : "info");
+      if (!snapshot) return;
+      ctx.ui.notify(formatSnapshot(snapshot), "info");
     },
   });
 
@@ -833,6 +975,9 @@ export default function (pi: ExtensionAPI): void {
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
       currentCtx = ctx;
       const snapshot = await publishSnapshot(ctx);
+      if (!snapshot) {
+        return { content: [{ type: "text", text: "Activity changed during collection; inspect again." }], details: { stale: true } };
+      }
       return {
         content: [{ type: "text", text: formatSnapshot(snapshot) }],
         details: snapshot,
@@ -841,6 +986,14 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.on("session_start", async (_event, ctx) => {
+    executionGeneration += 1;
+    sessionGeneration += 1;
+    clearIdleContinuation();
+    continuationQueuedFor = null;
+    backgroundDrainTracker = null;
+    lastAgentEvidence = null;
+    collecting = false;
+    collectionPending = false;
     currentCtx = ctx;
     foregroundRunning = !ctx.isIdle();
     const restoredGoal = getGoal(ctx);
@@ -849,10 +1002,12 @@ export default function (pi: ExtensionAPI): void {
       notifyGoal(ctx, "Goal paused: invoke its skill directly before resuming.", "error");
     }
     pi.events.emit(EVENT_READY, { version: EXTENSION_VERSION });
+    syncResumeTool(getGoal(ctx));
     installGoalWidget(ctx);
-    latestSnapshot = await publishSnapshot(ctx);
+    const snapshot = await publishSnapshot(ctx);
+    if (!snapshot) return;
     syncPollingState();
-    if (restoredGoal?.status === "active" && restoredGoal.command && boundCommandReady(restoredGoal, ctx) && !foregroundRunning && !latestSnapshot.backgroundRunning) {
+    if (restoredGoal?.status === "active" && restoredGoal.command && boundCommandReady(restoredGoal, ctx) && !foregroundRunning && !snapshot.backgroundRunning) {
       scheduleIdleContinuation(restoredGoal, ctx, "continuation");
     }
   });
@@ -874,24 +1029,13 @@ export default function (pi: ExtensionAPI): void {
         }
       }
     }
+    // A paused goal stays paused while the user talks: the message is ordinary
+    // conversation. Only /goal resume, the hotkey, or goal_resume resume it.
     const goal = getGoal(ctx);
-    if (goal?.status === "paused" && goal.pauseReason === "interrupt") {
-      // Conversational input after an interrupt means the user has taken the
-      // wheel, not stopped the goal: reactivate it so continuation resumes once
-      // this exchange settles. Pi's built-in commands (/settings, /model, ...)
-      // and extension commands never reach this handler.
-      const blocker = resumeBlocker(goal);
-      if (blocker) {
-        notifyGoal(ctx, `Goal stays paused. ${blocker}`, "warning");
-        return;
-      }
-      const resumed = goalWithStatus(goal, "active");
-      setGoal(resumed, ctx, "runtime");
-      resetContinuationState(resumed);
-      notifyGoal(ctx, "Goal resumed; it continues after this exchange.");
-      return;
-    }
     if (goal?.status === "active") {
+      executionGeneration += 1;
+      clearIdleContinuation();
+      lastAgentEvidence = null;
       resetContinuationState(goal);
     }
   });
@@ -901,8 +1045,10 @@ export default function (pi: ExtensionAPI): void {
     const goal = currentGoalSnapshot(ctx);
     const owner = getWorkflow(ctx);
     const snapshot = await publishSnapshot(ctx);
+    if (!snapshot) return;
+    const pausedInstruction = agentResumable(goal) ? pausedGoalPrompt(goal!) : "";
     if (!isPokeable(goal) && !owner) {
-      return;
+      return pausedInstruction ? { systemPrompt: `${event.systemPrompt}\n\n${pausedInstruction}` } : undefined;
     }
 
     const questionInstruction = snapshot.backgroundRunning
@@ -923,7 +1069,11 @@ export default function (pi: ExtensionAPI): void {
         return { systemPrompt: `${event.systemPrompt}\n\nWorkflow ${owner.name} is unavailable. Stop work and ask the user to restore or reinvoke the skill.` };
       }
       return {
-        systemPrompt: `${event.systemPrompt}\n\nActive workflow: ${owner.name} (${owner.path}). Its task plan owns planning and the parent is a coordinator, not a product-code implementer. Follow the workflow instructions below, including on resumed turns:\n\n${instructions}` +
+        systemPrompt: `${event.systemPrompt}\n\n` +
+          (pausedInstruction
+            ? `${pausedInstruction}\nWhile the goal is paused, this overrides the workflow instructions below: do not advance the workflow until the goal is resumed.\n\n`
+            : "") +
+          `Active workflow: ${owner.name} (${owner.path}). Its task plan owns planning and the parent is a coordinator, not a product-code implementer. Follow the workflow instructions below, including on resumed turns:\n\n${instructions}` +
           (isPokeable(goal) ? `\n\nActive objective: ${goal.objective}. Complete it only after the workflow completion audit.` : "") +
           (questionInstruction ? `\n\n${questionInstruction.trim()}` : ""),
       };
@@ -941,6 +1091,8 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.on("agent_start", async (_event, ctx) => {
+    executionGeneration += 1;
+    agentGeneration = executionGeneration;
     currentCtx = ctx;
     foregroundRunning = true;
     clearIdleContinuation();
@@ -958,7 +1110,7 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.on("agent_end", async (event, ctx) => {
-    lastAgentEvidence = continuationEvidence(event.messages);
+    lastAgentEvidence = agentGeneration === executionGeneration ? continuationEvidence(event.messages) : null;
     // `escape` is a pi-reserved built-in shortcut (`app.interrupt`), so extensions
     // cannot register it. Observe the interrupt instead: when a running turn is
     // aborted (escape / ctrl+c while streaming), pause the active goal so it does
@@ -972,6 +1124,7 @@ export default function (pi: ExtensionAPI): void {
     if (!BLOCKING_QUESTION_TOOLS.has(event.toolName)) return;
     currentCtx = ctx;
     const snapshot = await publishSnapshot(ctx);
+    if (!snapshot) return;
     const active = activeItemsByKey(snapshot);
     if (active.size > 0) pendingQuestions.set(event.toolCallId, active);
   });
@@ -982,6 +1135,7 @@ export default function (pi: ExtensionAPI): void {
     pendingQuestions.delete(event.toolCallId);
     currentCtx = ctx;
     const snapshot = await publishSnapshot(ctx);
+    if (!snapshot) return;
     const finished = finishedSinceQuestion(activeAtStart, snapshot);
     if (finished.length === 0) return;
     // Steering is drained right after this tool batch, so the model sees the
@@ -995,15 +1149,21 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.on("agent_settled", async (_event, ctx) => {
+    executionGeneration += 1;
     currentCtx = ctx;
     foregroundRunning = false;
     const snapshot = await publishSnapshot(ctx);
+    if (!snapshot) return;
     const goal = getGoal(ctx);
     if (!isPokeable(goal) || snapshot.backgroundRunning) {
       return;
     }
+    const evidence = lastAgentEvidence;
+    if (!evidence) {
+      scheduleIdleContinuation(goal, ctx, "continuation", snapshot);
+      return;
+    }
     const previous = currentContinuationState(ctx, goal.goalId) ?? createContinuationState(goal.goalId);
-    const evidence = lastAgentEvidence ?? continuationEvidence([]);
     const repeated = previous.lastEvidenceSignature === evidence.signature;
     const noProgressRetries = repeated ? previous.noProgressRetries + 1 : 0;
     const blocked = repeated && noProgressRetries >= MAX_NO_PROGRESS_RETRIES;
@@ -1034,6 +1194,8 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.on("session_shutdown", async (_event, ctx) => {
+    executionGeneration += 1;
+    sessionGeneration += 1;
     stopPolling();
     foregroundRunning = false;
     pendingQuestions.clear();

package/src/types.ts

@@ -66,10 +66,12 @@ export interface ActivitySnapshot {
 export type GoalStatus = "active" | "paused" | "budgetLimited" | "complete";
 
 /**
- * Why a paused goal is paused. `interrupt` marks a soft pause from escape (or
- * any other abort of the running turn): the user's next conversational message
- * resumes it. A paused goal without a reason (`/goal pause`, an unavailable
- * command or workflow) stays paused until `/goal resume`.
+ * Why a paused goal is paused. `interrupt` marks a pause from escape (or any
+ * other abort of the running turn). Every pause is sticky: user messages never
+ * resume a goal on their own. An `interrupt` pause may be resumed by the agent
+ * with `goal_resume` when the user clearly says to proceed. A paused goal
+ * without a reason (`/goal pause`, an unavailable command or workflow) resumes
+ * only through `/goal resume` or the resume hotkey.
  */
 export type GoalPauseReason = "interrupt";