@signalridge/pi-goal 1.4.6 → 1.4.8

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @signalridge/pi-goal
 
+## 1.4.8
+### Patch Changes
+
+- 0b24158: Report safety-pause causes and current count/limit before ambiguous ownership errors in Goal tools, and include an authoritative request-local pause notice when background notifications trigger ordinary conversation. Keep ownership, stale-ID, and abort guards intact: notifications never reset counters or bypass a safety pause, and only explicit resume restarts the Goal.
+
+## 1.4.7
+### Patch Changes
+
+- 4d37546: Point package documentation to the maintained compatibility guide instead of removed historical review snapshots.
+- 4d37546: Detach serialized Goal state from mutable runtime objects before appending native session metadata. Goal accounting, status, safety counters, queued objectives, wait records, and pending queue actions must not retroactively modify earlier session entries through shared references. This prevents false ancestry and ownership failures in observers such as Todo without relaxing their integrity checks, changing persisted shapes, resetting budgets, or automatically resuming stopped work. Already affected in-memory sessions should be safely closed and resumed from persisted history after updating; reloading extension code alone does not reconstruct old native entries.
+
 ## 1.4.6
 ### Patch Changes
 

package/README.md

@@ -38,7 +38,7 @@ Goal mode uses Codex-like persistence instructions and sends guarded continuatio
 
 ## Install
 
-The current tested host is Pi `1.0.4`. Host-provided dependencies use `"*"` peers to identify module ownership, not to guarantee compatibility with every Pi version. See the [compatibility review](https://github.com/signalridge/pi-extensions/blob/main/docs/pi-1.0-compatibility.md) for verification details. The `agent_settled` lifecycle event this extension depends on landed in `0.80.6`.
+The current tested host is Pi `1.0.4`. Host-provided dependencies use `"*"` peers to identify module ownership, not to guarantee compatibility with every Pi version. See the [compatibility guide](https://github.com/signalridge/pi-extensions/blob/main/docs/compatibility.md) for verification details. The `agent_settled` lifecycle event this extension depends on landed in `0.80.6`.
 
 ```bash
 pi install npm:@signalridge/pi-goal
@@ -167,7 +167,7 @@ Goal state is stored as Pi session state, similar to Codex's thread-owned goals.
 
 A `goal_wait` pause stores its reason and optional absolute wake deadline in the same session entry. On reload or session resume, a future deadline is re-armed; an overdue deadline gets one resume attempt after Pi is idle and pending messages have drained. No timer runs while Pi is closed. A wait without a deadline stays quiet until real interactive or RPC input is accepted for delivery, or `/goal resume` is used. Input consumed by another extension or rejected before the turn starts leaves the wait intact. Accepted real input resumes only a recorded wait and supplies the turn itself, without an extra resume prompt. A queued follow-up wakes the wait when delivered, not when queued. If delivery stays inside an existing agent run, the context hook supplies the rotated goal ID before its next response; it does not add another user turn. Extension-generated input and `/goal` commands do not count as real-input wake triggers. When Pi cannot distinguish real and extension input at delivery (for example, identical queued text or cross-transformed messages), the goal stays waiting rather than accepting a possible extension wake. That ambiguity remains attached to the waiting goal, including its deadline, until explicit `/goal resume` or reload; later input is not used to guess which earlier message was delivered. Automatic wakes do not override a restrictive active-tool policy; an overdue deadline rechecks readiness at most once per minute until Goal tools are available, while a settled boundary may wake sooner. An input whose delivery has not been confirmed also defers the deadline rather than racing a second prompt; if that input was rejected, resolve the failure and use `/goal resume` explicitly.
 
-Ordinary pauses, safety pauses, blockers, usage limits, exhausted budgets, and frozen queues do not auto-resume. Older paused entries without wait metadata remain paused; the extension does not infer a wait from transcript text. `/goal pause`, edit, clear, and replacement cancel the old wait. A synchronous deadline prompt-submission failure restores the stopped goal and wait metadata without a timer retry loop; use `/goal resume` or reload after resolving the problem. Pi's extension API does not acknowledge asynchronous prompt acceptance, so a later authentication or model failure cannot be rolled back by the extension; if no turn starts, inspect `/goal status` and explicitly pause/resume or reload after fixing the failure. Objective, cumulative usage, and the configured finite or Unlimited automatic-work setting are retained.
+Ordinary pauses, safety pauses, blockers, usage limits, exhausted budgets, and frozen queues do not auto-resume. Background completion notifications can trigger ordinary conversation while a Goal is safety-paused; they do not resume Goal execution, rotate its ID, or reset its counters. Each model request during a safety pause receives a request-local authoritative state notice with the cause, current count/limit, and explicit-resume requirement, superseding earlier active Goal instructions. Goal tools report that safety-pause cause before ownership or stale-ID diagnostics; those guards still apply once the Goal is active. Use `/goal resume` (or the manager's Continue action) to restart. Older paused entries without wait metadata remain paused; the extension does not infer a wait from transcript text. `/goal pause`, edit, clear, and replacement cancel the old wait. A synchronous deadline prompt-submission failure restores the stopped goal and wait metadata without a timer retry loop; use `/goal resume` or reload after resolving the problem. Pi's extension API does not acknowledge asynchronous prompt acceptance, so a later authentication or model failure cannot be rolled back by the extension; if no turn starts, inspect `/goal status` and explicitly pause/resume or reload after fixing the failure. Objective, cumulative usage, and the configured finite or Unlimited automatic-work setting are retained.
 
 Ordered queues use the same canonical `goal-state` session entry as single goals. Every item owns independent usage and safety state. Shelving, priority displacement, automatic advancement, and later reactivation preserve that item's epoch rather than granting more automatic work. The legacy `{ goal }` shape remains valid, and missing safety fields normalize to zero/defaults. Queue fields are written only when needed. Sessions created by the former standalone `pi-goals` experiment can migrate their last `goals-state` array and pending `unshift` intent when the branch has never written a canonical `goal-state`; any canonical entry, including an explicit clear, takes precedence so old plural state cannot be resurrected.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-goal",
-  "version": "1.4.6",
+  "version": "1.4.8",
   "description": "Pi extension for autonomous /goal completion with opt-in experimental ordered queues.",
   "type": "module",
   "license": "MIT",

package/src/lifecycle.ts

@@ -6,8 +6,10 @@ import { type ActiveGoal, loadGoalStateFromSession } from "./persistence.js";
 import {
   buildGoalBindingUpdate,
   buildGoalPrompt,
+  buildGoalSafetyPauseNotice,
   buildGoalSystemPrompt,
   GOAL_BINDING_UPDATE_HEADER,
+  GOAL_SAFETY_PAUSE_CONTEXT_TYPE,
 } from "./prompts.js";
 import { activateQueuedGoal } from "./queue.js";
 import type { GoalRunController } from "./run-protocol.js";
@@ -28,7 +30,7 @@ import {
   type StatusContext,
   truncateNotification,
 } from "./runtime.js";
-import { hasAssistantToolCall } from "./safety.js";
+import { formatGoalSafetyPause, hasAssistantToolCall } from "./safety.js";
 import { DEFAULT_GOAL_SETTINGS, readGoalSettings } from "./settings.js";
 
 const EXPERIMENTAL_GOALS_WARNING =
@@ -533,13 +535,31 @@ export function registerGoalLifecycle(
   });
 
   pi.on("context", (event, ctx) => {
-    const messages = event.messages.filter((message) => runtime.keepBudgetWrapUpMessage(message));
+    const messages = event.messages.filter(
+      (message) =>
+        runtime.keepBudgetWrapUpMessage(message) &&
+        !(message.role === "custom" && message.customType === GOAL_SAFETY_PAUSE_CONTEXT_TYPE),
+    );
     if (runtime.activeGoal?.status === "paused" && runtime.guardAbortGoalId === runtime.activeGoal.id) {
       // A current custom follow-up clears the guard at message_start. Otherwise,
       // context transformation aborts before the provider adapter receives the signal.
       abortCurrentTurn(ctx);
     }
     const goal = runtime.activeGoal;
+    const safetyPause =
+      !runtime.queueFrozen && goal ? buildGoalSafetyPauseNotice(goal, runtime.settings.continuationLimits) : undefined;
+    if (safetyPause) {
+      // Request-local, so queued custom notifications (which can skip
+      // before_agent_start) also see current state without persisting stale notices.
+      messages.push({
+        role: "custom",
+        customType: GOAL_SAFETY_PAUSE_CONTEXT_TYPE,
+        content: safetyPause,
+        display: false,
+        timestamp: Date.now(),
+      });
+      return { messages };
+    }
     if (!runtime.queueFrozen && goal?.status === "active" && runtime.inputWakeGoalId === goal.id) {
       // Native queued input reaches message_start without before_agent_start.
       // Keep the rotated guard visible for every remaining response in this run,
@@ -595,7 +615,9 @@ export function registerGoalLifecycle(
     abortCurrentTurn(ctx);
     return {
       block: true,
-      reason: "Blocked stale /goal tool call after the goal stopped or was interrupted.",
+      reason:
+        formatGoalSafetyPause(runtime.activeGoal, runtime.settings.continuationLimits) ??
+        "Blocked stale /goal tool call after the goal stopped or was interrupted.",
     };
   });
 

package/src/persistence.ts

@@ -82,11 +82,13 @@ export function serializeGoalState(
   queue: readonly ActiveGoal[],
   pendingAction: PendingQueueAction | undefined,
 ): GoalStateEntryData {
-  return {
+  // Native session entries retain data references; later runtime updates must
+  // not rewrite historical metadata or invalidate another extension's ancestry.
+  return structuredClone({
     goal: goal ?? null,
     ...(queue.length > 0 ? { queue: [...queue] } : {}),
     ...(pendingAction ? { pendingAction } : {}),
-  };
+  });
 }
 
 export function loadGoalStateFromSession(ctx: SessionContext): LoadedGoalState {

package/src/prompts.ts

@@ -1,4 +1,22 @@
 import { formatTokenCount } from "./accounting.js";
+import type { ActiveGoal } from "./persistence.js";
+import { formatGoalSafetyPause } from "./safety.js";
+import type { GoalSettings } from "./settings.js";
+
+export const GOAL_SAFETY_PAUSE_CONTEXT_TYPE = "goal-safety-pause-state";
+
+export function buildGoalSafetyPauseNotice(goal: ActiveGoal, limits: GoalSettings["continuationLimits"]) {
+  const pause = formatGoalSafetyPause(goal, limits);
+  if (!pause) return undefined;
+  return [
+    "Goal runtime state (authoritative for this request):",
+    `goal_id: ${escapeXmlText(goal.id)}`,
+    pause,
+    "This state supersedes earlier active Goal instructions. This response is ordinary conversation or notification handling, not Goal automatic execution.",
+    "Do not claim the Goal is running or continuing automatically. Do not call goal_complete, goal_blocked, or goal_wait while it is paused.",
+    "Background completion notifications and ordinary messages do not resume this safety pause or reset its counters. Only explicit user resume can restart Goal execution.",
+  ].join("\n");
+}
 
 export type GoalStatus = "active" | "queued" | "paused" | "blocked" | "usage_limited" | "budget_limited" | "complete";
 
@@ -67,6 +85,7 @@ function goalCompletionGuardBlock(goal: GoalPromptContext) {
 function goalModeRules(goalLabel: string) {
   return [
     "Goal-mode rules:",
+    "- Automatic continuation requires active Goal runtime state. A later authoritative Goal runtime state notice supersedes earlier active instructions; never treat notification handling as proof that Goal execution resumed.",
     "- Preserve the full objective across turns; do not redefine success around a narrower, safer, smaller, merely compatible, or easier-to-test result.",
     "- Derive concrete requirements from the objective and any referenced files, plans, specifications, issues, or user instructions.",
     "- Treat the current worktree, command output, tests, runtime behavior, PR state, rendered artifacts, and external state as authoritative. Previous conversation, plans, and summaries are context, not proof; inspect the current state before relying on them.",

package/src/safety.ts

@@ -1,5 +1,14 @@
 import { createHash } from "node:crypto";
 import type { ActiveGoal } from "./persistence.js";
+import type { GoalSettings } from "./settings.js";
+
+export function formatGoalSafetyPause(goal: ActiveGoal, limits: GoalSettings["continuationLimits"]) {
+  if (goal.status !== "paused" || !goal.safetyPauseCause) return undefined;
+  const automatic = goal.safetyPauseCause === "continuation_limit";
+  const used = automatic ? goal.automaticModelTurns : goal.toolFreeRepeatCount;
+  const limit = automatic ? limits.automaticTurns : limits.noProgressTurns;
+  return `Goal paused: ${goal.safetyPauseCause} (${used}/${limit ?? "Unlimited"}). Explicit resume required: run /goal resume.`;
+}
 
 export interface ToolFreeRepeatState {
   toolFreeRepeatCount: number;

package/src/tools.ts

@@ -20,6 +20,7 @@ import {
   transitionGoal,
   truncateNotification,
 } from "./runtime.js";
+import { formatGoalSafetyPause } from "./safety.js";
 import {
   createGoalWait,
   MAX_GOAL_WAIT_REASON_LENGTH,
@@ -101,6 +102,15 @@ export function registerGoalTools(pi: ExtensionAPI, runtime: GoalRuntime) {
         };
       }
       const completingDuringBudgetWrapUp = runtime.hasActiveBudgetWrapUp();
+      const safetyPause = formatGoalSafetyPause(completedGoal, runtime.settings.continuationLimits);
+      if (safetyPause) {
+        const rejection = `Goal completion rejected: ${safetyPause}`;
+        notifyTerminal(ctx.ui, rejection, "warning");
+        return {
+          content: toolContent(rejection),
+          details: completionDetails(goal, requestedGoalId, summary),
+        };
+      }
       if (!runtime.canRecordGoalUsage() && !completingDuringBudgetWrapUp) {
         const rejection = "Goal completion rejected: current run does not own the active goal.";
         notifyTerminal(ctx.ui, rejection, "warning");
@@ -257,7 +267,7 @@ export function registerGoalTools(pi: ExtensionAPI, runtime: GoalRuntime) {
       const evidence = typeof params.evidence === "string" ? params.evidence.trim() : "";
       const repeatedTurns = typeof params.repeated_turns === "number" ? params.repeated_turns : Number.NaN;
       const reject = (rejectionReason: string, terminate = false) => {
-        const rejection = `goal_blocked rejected: ${rejectionReason}.`;
+        const rejection = `goal_blocked rejected: ${rejectionReason}${rejectionReason.endsWith(".") ? "" : "."}`;
         notifyTerminal(ctx.ui, rejection, "warning");
         return {
           content: toolContent(rejection),
@@ -267,6 +277,8 @@ export function registerGoalTools(pi: ExtensionAPI, runtime: GoalRuntime) {
       };
 
       if (!blockedGoal) return reject("no active goal");
+      const safetyPause = formatGoalSafetyPause(blockedGoal, runtime.settings.continuationLimits);
+      if (safetyPause) return reject(safetyPause);
       if (!runtime.canRecordGoalUsage()) {
         return reject("current run does not own the active goal");
       }
@@ -363,6 +375,8 @@ export function registerGoalTools(pi: ExtensionAPI, runtime: GoalRuntime) {
       };
 
       if (!goal) return reject("no active goal");
+      const safetyPause = formatGoalSafetyPause(goal, runtime.settings.continuationLimits);
+      if (safetyPause) return reject(safetyPause);
       if (!runtime.canRecordGoalUsage()) return reject("current run does not own the active goal");
       if (hasPendingSkipForGoal(runtime, goal.id)) {
         runtime.recordGoalUsage(goal, ctx);