@signalridge/pi-goal 1.4.7 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @signalridge/pi-goal
 
+## 1.5.0
+### Minor Changes
+
+- 4697441: Add `experimental.notices`, a setting beside `experimental.goals` that silences the session-start notice announcing the experimental ordered-goal queue. It defaults to `true`, so existing sessions report exactly as before, and it suppresses only that announcement: validation failures, settings-load warnings, and recovery notices still report because they describe a problem rather than restate a choice the user already made. The queue, its subcommands, and `queue off` freezing are unaffected, and the Settings menu exposes the new control directly under **Ordered goal queue**.
+
+## 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
 

package/README.md

@@ -61,7 +61,8 @@ built-in defaults without creating the file:
 {
   "toolVisibility": "after-first-goal",
   "experimental": {
-    "goals": false
+    "goals": false,
+    "notices": true
   },
   "rpc": {
     "enabled": false
@@ -74,13 +75,14 @@ built-in defaults without creating the file:
 ```
 
 Use `/goal` → **Settings…** in the TUI to create or update the file interactively, or create
-and edit it directly. The standard Settings screen keeps all five controls on one level in task
+and edit it directly. The standard Settings screen keeps all six controls on one level in task
 order; the two safety limits open standard choice screens:
 
 - **Automatic-work limit** shows the exact response limit or **Unlimited**. Choose **Set response limit…** to edit the current finite value (or the built-in default of 25 when switching from Unlimited), or choose **Unlimited…**. Unlimited requires confirmation that tool loops may continue consuming tokens and provider cost without a response-count cap.
 - **No-progress guard** shows **_N_ runs** or **Off**. Choose the default threshold, **Off**, or **Set threshold…** and enter a safe whole number greater than zero.
 - **Goal tools** controls whether terminal Goal tools are always visible or appear after the first goal.
 - **Ordered goal queue** controls the experimental ordered-goal workflows.
+- **Experimental notice** controls whether a session reports once that experimental behavior and persisted state may change. It defaults to **On** and suppresses only that announcement; the queue itself is unaffected.
 - **Managed run RPC** controls whether trusted installed extensions may start and cancel managed Goal runs. It defaults to **Off** and is a cooperation setting, not an extension security sandbox.
 
 Custom number inputs reject zero, negative numbers, decimals, text, and unsafe integers without saving; use the explicit **Unlimited** or **Off** choice instead. Interactive changes are serialized, written atomically, preserve unknown fields, and apply to the current runtime. A successful change updates the visible state immediately. A failed save restores the prior value and reports the settings path so it can be retried. Tool-visibility changes that would alter the active tool schema are rejected while Pi is busy; retry after Pi settles. Escape returns to the previous screen without reverting changes that were already saved.
@@ -92,6 +94,8 @@ Custom number inputs reject zero, negative numbers, decimals, text, and unsafe i
 
 `experimental.goals` accepts a boolean and defaults to `false`. Set it to `true` to enable the ordered-goal subcommands and automatic queue advancement described below. Enabled sessions show one warning because command behavior and persisted queue state remain experimental.
 
+`experimental.notices` accepts a boolean and defaults to `true`. It controls that single experimental-goals announcement: with `notices: false` a session starts without it, while the queue, its subcommands, and queue freezing behave exactly as they do with `notices: true`. Nothing else routes through this setting — validation failures, settings-load warnings, and recovery notices always report, because those describe a problem rather than restate a choice the user has already made. Use it when the experiment is a standing configuration rather than a trial, so the warning level keeps meaning something.
+
 `rpc.enabled` accepts a boolean and defaults to `false`. When disabled, a valid managed-run start receives `RPC_DISABLED`; manual and restored Goals remain unchanged. A Settings-menu change applies immediately after its atomic save. Disabling rejects new starts but lets an already accepted run continue publishing its exact state and accept its exact cancellation until terminal, avoiding stranded work. Reload, replacement, and shutdown clear that in-memory ownership.
 
 `continuationLimits` controls the runaway guards:
@@ -167,7 +171,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.7",
+  "version": "1.5.0",
   "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 =
@@ -104,7 +106,7 @@ export function registerGoalLifecycle(
     if (settingsResult.kind === "invalid") {
       notifyTerminal(ctx.ui, `pi-goal settings ignored: ${settingsResult.reason}. Using default settings.`, "warning");
     }
-    if (runtime.settings.experimental.goals) {
+    if (runtime.settings.experimental.goals && runtime.settings.experimental.notices) {
       notifyTerminal(ctx.ui, EXPERIMENTAL_GOALS_WARNING, "warning");
     }
     try {
@@ -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/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/settings-ui.ts

@@ -43,6 +43,7 @@ export async function showGoalSettings(
     | "choose-no-progress"
     | "set-visibility"
     | "set-queue"
+    | "set-notices"
     | "set-rpc";
   const menu = defineMenu<undefined, Screen, Action, ExtensionCommandContext>({
     start: invalid ? "invalid" : (options.initialScreen ?? "settings"),
@@ -82,6 +83,14 @@ export async function showGoalSettings(
             values: ["Off", "Experimental"],
             action: "set-queue",
           },
+          {
+            id: "experimentalNotices",
+            label: "Experimental notice",
+            description: "Say once per session that experimental behavior and persisted state may change.",
+            currentValue: runtime.settings.experimental.notices ? "On" : "Off",
+            values: ["On", "Off"],
+            action: "set-notices",
+          },
           {
             id: "rpcEnabled",
             label: "Managed run RPC",
@@ -104,6 +113,7 @@ export async function showGoalSettings(
           `No-progress guard: ${formatNoProgressProtection(runtime.settings.continuationLimits.noProgressTurns)}`,
           `Goal tools: ${visibilityLabel(runtime.settings.toolVisibility)}`,
           `Ordered goal queue: ${runtime.settings.experimental.goals ? "Experimental" : "Off"}`,
+          `Experimental notice: ${runtime.settings.experimental.notices ? "On" : "Off"}`,
           `Managed run RPC: ${runtime.settings.rpc.enabled ? "On" : "Off"}`,
         ],
         hint: "back",
@@ -186,6 +196,24 @@ export async function showGoalSettings(
           return { kind: "rejected" };
         }
       },
+      "set-notices": async ({ value }) => {
+        const enabled = value === "On";
+        if (enabled === runtime.settings.experimental.notices) return { kind: "stay" };
+        try {
+          const next = {
+            ...structuredClone(runtime.settings),
+            experimental: { ...runtime.settings.experimental, notices: enabled },
+          } satisfies GoalSettings;
+          applyGoalSettings(runtime, next, ctx, {
+            save: (settings) => (options.save ?? saveGoalSettings)(settings, settingsPath),
+          });
+          notifyTerminal(ctx.ui, `Experimental notice: ${enabled ? "On" : "Off"}.`, "info");
+          return { kind: "stay" };
+        } catch (error) {
+          notifySettingsFailure(ctx, settingsPath, error);
+          return { kind: "rejected" };
+        }
+      },
       "set-rpc": async ({ value }) => {
         const enabled = value === "On";
         if (enabled === runtime.settings.rpc.enabled) return { kind: "stay" };
@@ -459,7 +487,7 @@ async function nextQueueSettings(runtime: GoalRuntime, ctx: ExtensionCommandCont
   }
   return {
     ...structuredClone(runtime.settings),
-    experimental: { goals: enabled },
+    experimental: { ...runtime.settings.experimental, goals: enabled },
   } satisfies GoalSettings;
 }
 

package/src/settings.ts

@@ -13,6 +13,7 @@ export interface GoalSettings {
   toolVisibility: GoalToolVisibility;
   experimental: {
     goals: boolean;
+    notices: boolean;
   };
   rpc: {
     enabled: boolean;
@@ -32,7 +33,12 @@ export const DEFAULT_GOAL_SETTINGS: GoalSettings = {
   // unfinished goal reveals them at startup. Set `"always"` to keep them
   // resident.
   toolVisibility: "after-first-goal",
-  experimental: { goals: false },
+  // `notices` is on by default: a user who enabled an experiment should be told
+  // once per session that its persisted state may change. It exists so that
+  // acknowledgement is a setting rather than a repeated prompt — a warning the
+  // reader cannot accept stops carrying information, and the same notification
+  // level carries failures worth reading.
+  experimental: { goals: false, notices: true },
   rpc: { enabled: false },
   continuationLimits: { automaticTurns: 25, noProgressTurns: 3 },
 };
@@ -70,6 +76,11 @@ export function normalizeGoalSettings(value: unknown): GoalSettings | undefined
       ? Reflect.get(experimentalValue, "goals")
       : DEFAULT_GOAL_SETTINGS.experimental.goals;
   if (typeof goals !== "boolean") return undefined;
+  const notices =
+    experimentalValue && Object.hasOwn(experimentalValue, "notices")
+      ? Reflect.get(experimentalValue, "notices")
+      : DEFAULT_GOAL_SETTINGS.experimental.notices;
+  if (typeof notices !== "boolean") return undefined;
 
   const rpcValue = Object.hasOwn(value, "rpc") ? Reflect.get(value, "rpc") : undefined;
   if (rpcValue !== undefined && (typeof rpcValue !== "object" || rpcValue === null || Array.isArray(rpcValue))) {
@@ -108,7 +119,7 @@ export function normalizeGoalSettings(value: unknown): GoalSettings | undefined
 
   return {
     toolVisibility: toolVisibility as GoalToolVisibility,
-    experimental: { goals },
+    experimental: { goals, notices },
     rpc: { enabled: rpcEnabled },
     continuationLimits: { automaticTurns, noProgressTurns },
   };
@@ -149,7 +160,11 @@ export function saveGoalSettings(
     {
       ...raw,
       toolVisibility: normalized.toolVisibility,
-      experimental: { ...experimental, goals: normalized.experimental.goals },
+      experimental: {
+        ...experimental,
+        goals: normalized.experimental.goals,
+        notices: normalized.experimental.notices,
+      },
       rpc: { ...rpc, enabled: normalized.rpc.enabled },
       continuationLimits: {
         ...continuationLimits,

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);