pi-better-harness 0.17.0 → 0.18.0

package/node_modules/pi-better-background-tasks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
   "license": "MIT",
   "type": "module",

package/node_modules/pi-better-background-tasks/src/shared-callback-batcher.ts

@@ -3,6 +3,8 @@ export type CallbackSource = "subagent" | "background-task";
 export type CallbackDetailTool = "subagent_result" | "bg_task_status";
 
 export interface CallbackBatchHost {
+  /** Older Pi shares this object; newer Pi supplies per-extension wrappers. */
+  events?: object;
   sendMessage(
     message: { customType: string; content: string; display: boolean },
     options: Record<string, unknown>,
@@ -66,6 +68,8 @@ export interface UrgentCallbackEvent {
 export interface CallbackBatcherOptions {
   windowMs?: number;
   retryMs?: number;
+  /** Ordinary callbacks stay here, not in Pi's follow-up queue, while unavailable. */
+  isAvailable?: () => boolean;
   /** UTF-8 byte cap for one sendMessage payload. Defaults to 2 KiB. */
   maxBytes?: number;
 }
@@ -73,6 +77,10 @@ export interface CallbackBatcherOptions {
 export interface CallbackBatcher {
   enqueue(event: CallbackBatchEvent): boolean;
   flush(): Promise<boolean>;
+  /** Refresh the API wrapper after reload without losing handoff receipts. */
+  setHost(host: CallbackBatchHost): void;
+  /** Update the session predicate and schedule an asynchronous drain when available. */
+  setAvailability(isAvailable: () => boolean): void;
   deliverUrgent(event: UrgentCallbackEvent): boolean | Promise<boolean>;
   cancel(): void;
   pendingCount(): number;
@@ -95,6 +103,7 @@ interface PendingEvent {
 
 interface SharedCallbackBatcherState {
   byHost: WeakMap<object, CallbackBatcher>;
+  bySession?: WeakMap<object, CallbackBatcher>;
 }
 
 const GLOBAL_STATE_KEY = Symbol.for("@1aboveio/pi-better-harness/callback-batcher");
@@ -435,6 +444,19 @@ export function createCallbackBatcher(
   let sequence = 0;
   let timer: ReturnType<typeof setTimeout> | undefined;
   let flushPromise: Promise<boolean> | undefined;
+  let isAvailable = options.isAvailable ?? (() => true);
+  let gated = options.isAvailable !== undefined;
+  let awaitingRun = false;
+
+  const available = (): boolean => {
+    try {
+      if (!isAvailable()) {
+        awaitingRun = false;
+        return false;
+      }
+      return !awaitingRun;
+    } catch { return false; }
+  };
 
   const cancelTimer = (): void => {
     if (timer) clearTimeout(timer);
@@ -443,10 +465,12 @@ export function createCallbackBatcher(
 
   const schedule = (delayMs: number): void => {
     if (timer || pending.size === 0) return;
+    // Some idle transitions (manual compaction) have no agent_settled event.
+    const delay = available() ? delayMs : retryMs;
     timer = setTimeout(() => {
       timer = undefined;
       void api.flush();
-    }, Math.max(0, delayMs));
+    }, Math.max(1, delay));
     timer.unref?.();
   };
 
@@ -461,6 +485,10 @@ export function createCallbackBatcher(
 
   const performFlush = async (): Promise<boolean> => {
     cancelTimer();
+    if (!available()) {
+      schedule(retryMs);
+      return false;
+    }
     const snapshot = [...pending.entries()]
       .sort((a, b) => a[1].sequence - b[1].sequence);
     pending.clear();
@@ -509,6 +537,9 @@ export function createCallbackBatcher(
     const overflowItems = deliverable.filter(([, item]) => !representedSet.has(item.event));
 
     try {
+      // Pi may defer the requested run while settled handlers finish, leaving
+      // isIdle() true. Permit no second handoff until a run starts.
+      awaitingRun = gated;
       await host.sendMessage(
         {
           customType: "background-completion-batch",
@@ -518,6 +549,7 @@ export function createCallbackBatcher(
         { deliverAs: "followUp", triggerTurn: true },
       );
     } catch {
+      awaitingRun = false;
       for (const [key] of deliverable) inFlight.delete(key);
       const retryItems = [...deliverable, ...pending.entries()]
         .sort((a, b) => a[1].sequence - b[1].sequence);
@@ -596,10 +628,19 @@ export function createCallbackBatcher(
   const api: CallbackBatcher = {
     enqueue,
     flush,
+    setHost(next) { host = next; },
+    setAvailability(check) {
+      gated = true;
+      isAvailable = check;
+      available();
+      cancelTimer();
+      schedule(windowMs);
+    },
     deliverUrgent,
     cancel() {
       cancelTimer();
       pending.clear();
+      awaitingRun = false;
     },
     pendingCount() {
       return pending.size;
@@ -613,16 +654,38 @@ export function getCallbackBatcher(
   options: CallbackBatcherOptions = {},
 ): CallbackBatcher {
   const state = globalState();
-  const key = host as object;
+  const key = host.events ?? host;
   const existing = state.byHost.get(key);
-  if (existing) return existing;
+  if (existing) {
+    existing.setHost(host);
+    return existing;
+  }
   const created = createCallbackBatcher(host, options);
   state.byHost.set(key, created);
   return created;
 }
 
 export function cancelCallbackBatch(host: CallbackBatchHost): void {
-  globalState().byHost.get(host as object)?.cancel();
+  const batcher = globalState().byHost.get(host.events ?? host);
+  batcher?.setAvailability(() => false);
+  batcher?.cancel();
+}
+
+/** Called on session_start, agent_start and agent_settled by both extensions. */
+export function setCallbackBatchContext(
+  host: CallbackBatchHost,
+  ctx: { isIdle(): boolean; sessionManager?: object },
+): void {
+  const state = globalState();
+  const bySession = state.bySession ??= new WeakMap<object, CallbackBatcher>();
+  const shared = ctx.sessionManager ? bySession.get(ctx.sessionManager) : undefined;
+  const batcher = shared ?? getCallbackBatcher(host);
+  if (ctx.sessionManager) bySession.set(ctx.sessionManager, batcher);
+  state.byHost.set(host.events ?? host, batcher);
+  batcher.setHost(host);
+  // Schedule rather than await delivery inside agent_settled: its handlers are
+  // still settling the previous run, and sendMessage may start a new one.
+  batcher.setAvailability(() => ctx.isIdle());
 }
 
 function globalState(): SharedCallbackBatcherState {

package/node_modules/pi-better-background-tasks/src/tools.ts

@@ -13,7 +13,7 @@ import {
   type OutputOptions,
 } from "./output.js";
 import { readOutputControls } from "./shared-log-utils.js";
-import { cancelCallbackBatch } from "./shared-callback-batcher.js";
+import { cancelCallbackBatch, setCallbackBatchContext } from "./shared-callback-batcher.js";
 import { inspectMeta, listMetasForOrigin, readMeta, writeMeta } from "./registry.js";
 import { awaitFirstWatchCheck, FIRST_WATCH_CHECK_WAIT_MS, resumeRunningTask, spawnTask, startWatchTask, stopTask, type WatchTaskParams } from "./runtime.js";
 import { runTaskMaintenance } from "./maintenance.js";
@@ -194,6 +194,7 @@ export function registerTools(pi: ExtensionAPI): void {
   const getActiveSession = () => activeSession;
 
   pi.on("session_start", async (_event, ctx) => {
+    setCallbackBatchContext(pi, ctx);
     activeSession = getCallbackOrigin(ctx);
     for (const meta of listMetasForOrigin(activeSession)) {
       if (meta.status === "running" || (meta.callback !== false && !meta.callbackSentAt && !meta.callbackSuppressedAt)) {
@@ -202,6 +203,8 @@ export function registerTools(pi: ExtensionAPI): void {
     }
     runTaskMaintenance({ activeOrigin: activeSession });
   });
+  pi.on("agent_start", (_event, ctx) => { setCallbackBatchContext(pi, ctx); });
+  pi.on("agent_settled", (_event, ctx) => { setCallbackBatchContext(pi, ctx); });
   pi.on("session_before_switch", () => {
     activeSession = undefined;
     cancelCallbackBatch(pi);

package/node_modules/pi-better-goal/README.md

@@ -13,7 +13,8 @@ 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 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.
+- `/goal settings` opens an interactive settings page in the TUI. Select a row with Up/Down and toggle with Space/Enter; changes save immediately, and Escape closes the page. Both controls default to `on`. Automatic continuation controls idle and background-drain wakes; conversational resume controls the agent's Escape-pause resume tool. Goal kickoff, `/goal resume`, and `alt+g` remain available with either control off. For scripts or non-interactive sessions, use `/goal settings auto-continue on|off` and `/goal settings conversational-resume on|off`; bare `/goal settings` prints the saved values outside the TUI.
+- `escape` pauses the active goal, and it stays paused while you talk to the agent. With conversational resume enabled, 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 the available resume path, 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.

package/node_modules/pi-better-goal/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-goal",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Pi extension for goal tracking with background-aware continuation.",
   "license": "MIT",
   "type": "module",

package/node_modules/pi-better-goal/src/index.ts

@@ -3,6 +3,8 @@ import type { AutocompleteItem } from "@earendil-works/pi-tui";
 import { readFileSync } from "node:fs";
 import { Type } from "typebox";
 import { commandAvailable, commandInvocation, resolveGoalCommand } from "./command-binding.js";
+import { goalPreferencesPath, readGoalPreferences, writeGoalPreference, type GoalPreferences } from "./preferences.js";
+import { createGoalSettingsPage } from "./settings-page.js";
 
 import {
   collectActivitySnapshot,
@@ -82,20 +84,20 @@ const GOAL_RESUME_RULE =
   "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";
+export function agentResumable(goal: GoalSnapshot | null, conversationalResume = true): boolean {
+  return conversationalResume && 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";
+export function pausedGoalStatus(goal: GoalSnapshot, conversationalResume = true): string {
+  return agentResumable(goal, conversationalResume) ? 'goal paused · say "go" or /goal resume' : "goal paused · /goal resume";
 }
 
-function pausedGoalPrompt(goal: GoalSnapshot): string {
+function pausedGoalPrompt(goal: GoalSnapshot, conversationalResume: boolean): 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,
+    conversationalResume ? GOAL_RESUME_RULE : "Only the user can resume this goal, with /goal resume or alt+g. A conversational go-ahead does not resume it.",
   ].join("\n");
 }
 
@@ -106,10 +108,21 @@ const GOAL_ACTIONS: readonly AutocompleteItem[] = [
   { value: "resume", label: "resume", description: "Resume the paused goal" },
   { value: "clear", label: "clear", description: "Remove the current goal" },
   { value: "complete", label: "complete", description: "Mark the current goal complete" },
+  { value: "settings", label: "settings", description: "Inspect or persist goal continuation and conversational resume controls" },
 ];
 
+const GOAL_SETTINGS = ["auto-continue", "conversational-resume"] as const;
+
 export function goalArgumentCompletions(argumentPrefix: string): AutocompleteItem[] | null {
   const prefix = argumentPrefix.trimStart().toLowerCase();
+  if (prefix.startsWith("settings ")) {
+    const settingPrefix = prefix.slice("settings ".length);
+    const choices = GOAL_SETTINGS.flatMap((setting) => settingPrefix.startsWith(`${setting} `)
+      ? ["on", "off"].map((mode) => `settings ${setting} ${mode}`)
+      : [`settings ${setting}`]);
+    const matches = choices.filter((value) => value.startsWith(prefix)).map((value) => ({ value, label: value }));
+    return matches.length > 0 ? matches : null;
+  }
   const matches = GOAL_ACTIONS.filter((action) => action.value.startsWith(prefix));
   return matches.length > 0 ? [...matches] : null;
 }
@@ -214,9 +227,11 @@ function formatGoal(
   goal: GoalSnapshot | null,
   continuation: ReturnType<typeof currentContinuationState> = null,
   stall = observeGoalStall(goal, continuation),
+  preferences: GoalPreferences = { autoContinue: true, conversationalResume: true },
 ): string {
+  const settings = formatPreferences(preferences);
   if (!goal) {
-    return "No goal is set.";
+    return `No goal is set.\n${settings}`;
   }
   const budget = goal.tokenBudget === null ? "none" : String(goal.tokenBudget);
   const timing = goalTiming(goal);
@@ -232,14 +247,22 @@ function formatGoal(
     `Elapsed time: ${timing.elapsedSeconds}s`,
     `Observable progress: ${stall?.state ?? "unknown"}`,
     continuationStatus,
+    settings,
     ...(goal.status === "paused"
-      ? [agentResumable(goal)
+      ? [agentResumable(goal, preferences.conversationalResume)
         ? 'Resume: say "go" (the agent calls goal_resume), /goal resume, or alt+g'
         : "Resume: /goal resume or alt+g"]
       : []),
   ].join("\n");
 }
 
+function formatPreferences(preferences: GoalPreferences): string {
+  return [
+    `Automatic continuation setting: ${preferences.autoContinue ? "on" : "off"}${WAKE_DISABLED ? " (disabled by environment)" : ""}`,
+    `Conversational resume setting: ${preferences.conversationalResume ? "on" : "off"}`,
+  ].join("\n");
+}
+
 function formatSnapshot(snapshot: ActivitySnapshot): string {
   const providers = snapshot.providers.map((provider) => {
     const active = provider.items.filter((item) => item.active).length;
@@ -284,6 +307,7 @@ export default function (pi: ExtensionAPI): void {
   let idleContinuationSignature = "";
   let refreshGoalWidget: ((force?: boolean) => void) | undefined;
   let lastAgentEvidence: ContinuationEvidence | null = null;
+  let preferences: GoalPreferences = { autoContinue: true, conversationalResume: true };
   /** Background items active when each pending blocking question started, keyed by tool call id. */
   const pendingQuestions = new Map<string, Map<string, BackgroundWorkItem>>();
 
@@ -387,7 +411,9 @@ export default function (pi: ExtensionAPI): void {
       return;
     }
     setGoal(goalWithStatus(goal, "paused", undefined, "interrupt"), ctx, "runtime");
-    notifyGoal(ctx, 'Goal paused. Say "go" to resume it, or use /goal resume.');
+    notifyGoal(ctx, preferences.conversationalResume
+      ? 'Goal paused. Say "go" to resume it, or use /goal resume.'
+      : "Goal paused. Use /goal resume or alt+g to resume it.");
   };
 
   /** Why a paused goal cannot become active again, or null when it can. */
@@ -470,7 +496,7 @@ export default function (pi: ExtensionAPI): void {
     kind: "continuation" | "background-drained",
     snapshot?: ActivitySnapshot,
   ): void => {
-    if (WAKE_DISABLED || !isPokeable(goal) || continuationQueuedFor === goal.goalId) {
+    if (WAKE_DISABLED || !preferences.autoContinue || !isPokeable(goal) || continuationQueuedFor === goal.goalId) {
       return;
     }
     if (kind === "continuation" && currentContinuationState(ctx, goal.goalId)?.blocked) {
@@ -500,7 +526,7 @@ export default function (pi: ExtensionAPI): void {
     const execution = executionGeneration;
     const wake = wakeGeneration;
     const auditIsCurrent = (): boolean => {
-      if (execution !== executionGeneration || wake !== wakeGeneration) return false;
+      if (WAKE_DISABLED || !preferences.autoContinue || execution !== executionGeneration || wake !== wakeGeneration) return false;
       const current = currentGoalSnapshot(ctx);
       return isPokeable(current) && current.goalId === goalId &&
         continuationQueuedFor !== goalId && !isForegroundBusy(ctx);
@@ -603,7 +629,7 @@ export default function (pi: ExtensionAPI): void {
     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 (goal?.status === "paused") return background ? `${pausedGoalStatus(goal, preferences.conversationalResume)} · ${background}` : pausedGoalStatus(goal, preferences.conversationalResume);
     if (background) return background;
     const continuation = goal ? currentContinuationState(ctx, goal.goalId) : null;
     if (continuation?.blocked) return "waiting: no progress";
@@ -633,7 +659,7 @@ export default function (pi: ExtensionAPI): void {
     if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
     try {
       const active = pi.getActiveTools();
-      const wanted = agentResumable(goal);
+      const wanted = agentResumable(goal, preferences.conversationalResume);
       if (active.includes(GOAL_RESUME_TOOL) === wanted) return;
       pi.setActiveTools(wanted ? [...active, GOAL_RESUME_TOOL] : active.filter((name) => name !== GOAL_RESUME_TOOL));
     } catch {
@@ -760,17 +786,57 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("goal", {
-    description: "Create, inspect, pause, resume, clear, or complete the active goal",
+    description: "Create, inspect, pause, resume, clear, or complete the active goal; configure persistent goal settings",
     getArgumentCompletions: goalArgumentCompletions,
     handler: async (args, ctx) => {
       currentCtx = ctx;
       const trimmed = args.trim();
       const current = getGoal(ctx);
 
+      if (trimmed === "settings" || trimmed.startsWith("settings ")) {
+        const changePreference = async (key: keyof GoalPreferences, enabled: boolean): Promise<void> => {
+          const previous = preferences;
+          preferences = writeGoalPreference(key, enabled);
+          if (previous.autoContinue !== preferences.autoContinue) clearIdleContinuation();
+          syncResumeTool(getGoal(ctx));
+          applyStatus(ctx);
+          if (!previous.autoContinue && preferences.autoContinue) {
+            const snapshot = await publishSnapshot(ctx);
+            const goal = getGoal(ctx);
+            if (snapshot && isPokeable(goal) && !isForegroundBusy(ctx) && !snapshot.backgroundRunning) {
+              scheduleIdleContinuation(goal, ctx, "continuation", snapshot);
+            }
+          }
+        };
+        if (trimmed === "settings" && ctx.hasUI && ctx.mode !== "rpc" && typeof ctx.ui.custom === "function") {
+          await ctx.ui.custom<void>((tui, theme, _kb, done) => createGoalSettingsPage(theme, {
+            get: () => ({ ...preferences }),
+            change: changePreference,
+          }, () => tui.requestRender(), () => done()));
+          return;
+        }
+        const [, setting, mode, ...extra] = trimmed.split(/\s+/);
+        if (setting !== undefined && (!GOAL_SETTINGS.includes(setting as typeof GOAL_SETTINGS[number]) ||
+            (mode !== "on" && mode !== "off") || extra.length > 0)) {
+          notifyGoal(ctx, "Usage: /goal settings [auto-continue|conversational-resume on|off]", "warning");
+          return;
+        }
+        if (setting !== undefined) {
+          try {
+            await changePreference(setting === "auto-continue" ? "autoContinue" : "conversationalResume", mode === "on");
+          } catch (error) {
+            notifyGoal(ctx, error instanceof Error ? error.message : String(error), "error");
+            return;
+          }
+        }
+        ctx.ui.notify(`${formatPreferences(preferences)}\nPreferences: ${goalPreferencesPath()}`, "info");
+        return;
+      }
+
       if (!trimmed) {
         const continuation = current ? currentContinuationState(ctx, current.goalId) : null;
         // Inspection is always explicit user intent; show the full summary even while busy.
-        ctx.ui.notify(formatGoal(current, continuation, observeGoalStall(current, continuation, { foregroundRunning })), "info");
+        ctx.ui.notify(formatGoal(current, continuation, observeGoalStall(current, continuation, { foregroundRunning }), preferences), "info");
         return;
       }
 
@@ -847,8 +913,8 @@ export default function (pi: ExtensionAPI): void {
         backgroundRunning: latestSnapshot?.backgroundRunning ?? false,
       });
       return {
-        content: [{ type: "text", text: formatGoal(goal, continuation, stall) }],
-        details: { goal, continuation, stall, timing: goal ? goalTiming(goal) : null, hasGoal: goal !== null },
+        content: [{ type: "text", text: formatGoal(goal, continuation, stall, preferences) }],
+        details: { goal, continuation, stall, preferences: { ...preferences }, timing: goal ? goalTiming(goal) : null, hasGoal: goal !== null },
       };
     },
   });
@@ -904,7 +970,13 @@ export default function (pi: ExtensionAPI): void {
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const reason = (params as { reason?: string }).reason;
       const current = getGoal(ctx);
-      if (!agentResumable(current)) {
+      if (!preferences.conversationalResume) {
+        return {
+          content: [{ type: "text", text: "Conversational goal resume is disabled. Only the user can resume with /goal resume or alt+g." }],
+          details: { ok: false, goal: current },
+        };
+      }
+      if (!agentResumable(current, preferences.conversationalResume)) {
         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.";
@@ -996,6 +1068,11 @@ export default function (pi: ExtensionAPI): void {
     collectionPending = false;
     currentCtx = ctx;
     foregroundRunning = !ctx.isIdle();
+    try {
+      preferences = readGoalPreferences();
+    } catch (error) {
+      notifyGoal(ctx, error instanceof Error ? error.message : String(error), "error");
+    }
     const restoredGoal = getGoal(ctx);
     if (restoredGoal?.status === "active" && !restoredGoal.command && skillCommandName(restoredGoal.objective)) {
       setGoal(goalWithStatus(restoredGoal, "paused"), ctx, "runtime");
@@ -1046,7 +1123,8 @@ export default function (pi: ExtensionAPI): void {
     const owner = getWorkflow(ctx);
     const snapshot = await publishSnapshot(ctx);
     if (!snapshot) return;
-    const pausedInstruction = agentResumable(goal) ? pausedGoalPrompt(goal!) : "";
+    const pausedInstruction = goal?.status === "paused" && goal.pauseReason === "interrupt"
+      ? pausedGoalPrompt(goal, preferences.conversationalResume) : "";
     if (!isPokeable(goal) && !owner) {
       return pausedInstruction ? { systemPrompt: `${event.systemPrompt}\n\n${pausedInstruction}` } : undefined;
     }

package/node_modules/pi-better-goal/src/preferences.ts

@@ -0,0 +1,70 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export interface GoalPreferences {
+  autoContinue: boolean;
+  conversationalResume: boolean;
+}
+
+export interface GoalPreferenceSeams {
+  agentDir?: () => string;
+}
+
+export function goalPreferencesPath(seams: GoalPreferenceSeams = {}): string {
+  return join((seams.agentDir ?? getAgentDir)(), "extensions", "pi-better-goal-preferences.json");
+}
+
+export function readGoalPreferences(seams: GoalPreferenceSeams = {}): GoalPreferences {
+  const path = goalPreferencesPath(seams);
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { autoContinue: true, conversationalResume: true };
+    }
+    throw new Error(`Goal preferences at ${path} could not be read: ${messageOf(error)}`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`Goal preferences at ${path} are not valid JSON: ${messageOf(error)}`);
+  }
+  const value = parsed as Partial<GoalPreferences> & { version?: unknown } | null;
+  if (value?.version !== 1 ||
+      (value.autoContinue !== undefined && typeof value.autoContinue !== "boolean") ||
+      (value.conversationalResume !== undefined && typeof value.conversationalResume !== "boolean")) {
+    throw new Error(`Goal preferences at ${path} must contain version 1 and boolean autoContinue/conversationalResume settings.`);
+  }
+  return {
+    autoContinue: value.autoContinue ?? true,
+    conversationalResume: value.conversationalResume ?? true,
+  };
+}
+
+/** Persist one control without replacing the other session's saved choice. */
+export function writeGoalPreference(
+  key: keyof GoalPreferences,
+  enabled: boolean,
+  seams: GoalPreferenceSeams = {},
+): GoalPreferences {
+  const preferences = { ...readGoalPreferences(seams), [key]: enabled };
+  const path = goalPreferencesPath(seams);
+  const pending = `${path}.${process.pid}.tmp`;
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(pending, `${JSON.stringify({ version: 1, ...preferences }, null, 2)}\n`, "utf8");
+    renameSync(pending, path);
+  } catch (error) {
+    throw new Error(`Goal preferences at ${path} could not be written: ${messageOf(error)}`);
+  } finally {
+    rmSync(pending, { force: true });
+  }
+  return preferences;
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/node_modules/pi-better-goal/src/settings-page.ts

@@ -0,0 +1,67 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth, visibleWidth, type Component, type Focusable } from "@earendil-works/pi-tui";
+import type { GoalPreferences } from "./preferences.js";
+
+const rows: { key: keyof GoalPreferences; label: string }[] = [
+  { key: "autoContinue", label: "Automatic continuation" },
+  { key: "conversationalResume", label: "Conversational resume" },
+];
+
+export function createGoalSettingsPage(
+  theme: Theme,
+  handlers: { get(): GoalPreferences; change(key: keyof GoalPreferences, enabled: boolean): Promise<void> },
+  requestRender: () => void,
+  close: () => void,
+): Component & Focusable {
+  let row = 0;
+  let busy = false;
+  let message = "";
+  let error = false;
+  function change(): void {
+    const selected = rows[row]!;
+    busy = true;
+    message = "Saving...";
+    error = false;
+    void Promise.resolve().then(() => handlers.change(selected.key, !handlers.get()[selected.key])).then(() => {
+      message = "Saved.";
+    }, (cause: unknown) => {
+      message = cause instanceof Error ? cause.message : String(cause);
+      error = true;
+    }).finally(() => {
+      busy = false;
+      requestRender();
+    });
+  }
+  return {
+    focused: false,
+    invalidate() {},
+    handleInput(data: string) {
+      if (matchesKey(data, Key.escape)) { close(); return; }
+      if (busy) return;
+      if (matchesKey(data, Key.up)) row = Math.max(0, row - 1);
+      else if (matchesKey(data, Key.down)) row = Math.min(rows.length - 1, row + 1);
+      else if (matchesKey(data, Key.enter) || data === " ") change();
+      requestRender();
+    },
+    render(width: number) {
+      const w = Math.max(1, Math.floor(width));
+      const preferences = handlers.get();
+      const lines = [theme.fg("accent", theme.bold("  Goal settings")), ""];
+      rows.forEach(({ key, label }, index) => {
+        const selected = row === index;
+        const title = theme.fg(selected ? "accent" : "text", (selected ? "> " : "  ") + label);
+        const value = preferences[key] ? "On" : "Off";
+        const active = selected ? theme.inverse(value) : theme.fg("text", value);
+        if (w < 40) {
+          lines.push(title, "  " + active);
+        } else {
+          const line = title + " ".repeat(Math.max(1, 30 - visibleWidth(title))) + active;
+          lines.push(selected ? theme.bg("selectedBg", theme.bold(line)) : line);
+        }
+      });
+      if (message) lines.push("", theme.fg(error ? "error" : "muted", message));
+      lines.push("", theme.fg("dim", "Up/Down Select · Space/Enter Toggle · Esc Back"));
+      return lines.map((line) => truncateToWidth(line, w, ""));
+    },
+  };
+}

package/node_modules/pi-better-plan/README.md

@@ -2,6 +2,8 @@
 
 `pi-better-plan` keeps a structured execution plan visible while Pi works.
 
+![Pi Better Plan package preview](https://raw.githubusercontent.com/1aboveio/pi-better-harness/main/docs/images/package-gallery/pi-better-plan.png)
+
 ## What It Does
 
 - Gives models `update_plan` and `get_plan` tools for atomic, explicit progress updates.
@@ -36,7 +38,7 @@ For a DAG, assign stable ids to prerequisite steps and list those ids in depende
 
 When an explicitly invoked skill declares `workflow-role: coordinator` in its metadata, that skill's task plan takes precedence. The generic checklist stays persisted but is hidden, and `update_plan` refuses generic checklist updates until workflow ownership is released. `/plan` never opens a stale generic checklist during workflow ownership.
 
-For `rush-issues`, call `sync_workflow_plan` once with the absolute `.resolve-issues/rush/<run-id>/task-plan.json` path and its persisted `planRevision`. This binds the run to the session and shows its fleet stages and units in the widget, `/plan`, and `get_plan`; the binding survives Pi session resume, and ownership release restores the prior generic checklist. After that, record every transition with `update_plan` and a `workflow` object instead of editing `task-plan.json` or the profiling log by hand:
+For any workflow using the shared task-plan contract (including `resolve-issues` and `rush-issues`), call `sync_workflow_plan` once with the absolute `.resolve-issues/rush/<run-id>/task-plan.json` path and its persisted `planRevision`. This binds the run to the session and shows its fleet stages and units in the widget, `/plan`, and `get_plan`; the binding survives Pi session resume, and ownership release restores the prior generic checklist. After that, record every transition with `update_plan` and a `workflow` object instead of editing `task-plan.json` or the profiling log by hand:
 
 ```json
 { "workflow": {
@@ -50,7 +52,9 @@ For `rush-issues`, call `sync_workflow_plan` once with the absolute `.resolve-is
 } }
 ```
 
-`changes` addresses units, components, and fleet stages by id (a change without an id sets run-level fields); all changes in one call are one transition. For a scope change, a change with `target` `unit` or `component` and an `add` row appends a new row; existing rows cannot be removed or renamed. The tool checks ids, dependencies (including cycles), worker slots, and status/stage values against the Rush contract (a fleet status of `n/a` is saved as `not-applicable`), refuses a stale `revision`, appends an optional `decision`, then saves the plan atomically with `planRevision + 1` and a new `updatedAt`, and appends one profiling event with the same revision to the log the run already uses (`profiling/run.jsonl` or `profiling.jsonl`). A rejected update changes nothing. The event is appended before the plan is renamed into place, so a crash between the two can leave the log one revision ahead; the next update notices, reuses that revision, and marks its event with `logAheadRevision`. Other workflow-owned skills retain their own planning and have no generic plan view.
+`changes` addresses units, components, and fleet stages by id (a change without an id sets run-level fields); all changes in one call are one transition. For a scope change, a change with `target` `unit` or `component` and an `add` row appends a new row; existing rows cannot be removed or renamed. The tool checks ids, dependencies (including cycles), worker slots, and status/stage values against the shared issue-resolution contract (a fleet status of `n/a` is saved as `not-applicable`), refuses a stale `revision`, appends an optional `decision`, then saves the plan atomically with `planRevision + 1` and a new `updatedAt`, and appends one profiling event with the same revision to the log the run already uses (`profiling/run.jsonl` or `profiling.jsonl`). A rejected update changes nothing. The event is appended before the plan is renamed into place, so a crash between the two can leave the log one revision ahead; the next update notices, reuses that revision, and marks its event with `logAheadRevision`.
+
+The binding records the active workflow's name, which is shown in the plan view. A different workflow cannot read or update that binding; a new invocation or ownership release invalidates it. The skill name is not an allowlist: explicit binding opts a workflow into the shared schema and transition rules, while path confinement to `.resolve-issues/rush/<run-id>/task-plan.json`, run identity, size limits, and revision checks still apply. Workflows using other schemas or storage locations retain their own planning and must not bind incompatible state.
 
 ## Plan Display
 

package/node_modules/pi-better-plan/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-plan",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Structured execution plans with persistent progress for Pi.",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,8 @@
   "pi": {
     "extensions": [
       "./src/index.ts"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/1aboveio/pi-better-harness/main/docs/images/package-gallery/pi-better-plan.png"
   },
   "scripts": {
     "test": "node --import tsx --test test/*.test.ts",

package/node_modules/pi-better-plan/src/index.ts

@@ -134,7 +134,7 @@ export default function planExtension(pi: ExtensionAPI): void {
   const refresh = (force = false): void => refreshWidget?.(force);
 
   const loadRushPlan = (ctx: ExtensionContext): RushPlan | null => {
-    if (!rushBinding || workflowPlanOwner(ctx) !== "rush-issues") return null;
+    if (!rushBinding || workflowPlanOwner(ctx) !== rushBinding.owner) return null;
     try {
       const plan = readRushPlan(rushBinding.path, ctx.cwd);
       if (plan.runId !== rushBinding.runId) throw new Error("Rush run identity changed.");
@@ -181,7 +181,8 @@ export default function planExtension(pi: ExtensionAPI): void {
     const state = reconstructPlanState(ctx.sessionManager.getBranch());
     currentPlan = state.plan;
     displayedWorkflowOwner = workflowPlanOwner(ctx);
-    rushBinding = displayedWorkflowOwner === "rush-issues" ? workflowBinding(ctx.sessionManager.getBranch()) : null;
+    const binding = workflowBinding(ctx.sessionManager.getBranch());
+    rushBinding = binding?.owner === displayedWorkflowOwner ? binding : null;
     rushPlan = null;
     rushError = null;
     if (rushBinding) loadRushPlan(ctx);
@@ -213,13 +214,13 @@ export default function planExtension(pi: ExtensionAPI): void {
         refreshWidget = localRefresh;
         return {
           render(width: number): string[] {
-            if (displayMode === "hidden") return [];
+            if (displayMode === "hidden" || displayedWorkflowOwner !== workflowPlanOwner(ctx)) return [];
             if (displayedWorkflowOwner) {
-              if (displayedWorkflowOwner !== "rush-issues") return [];
+              if (rushBinding?.owner !== displayedWorkflowOwner) return [];
               const fg = typeof theme?.fg === "function"
                 ? (color: string, value: string) => theme.fg(color as never, value)
                 : undefined;
-              return rushPlan ? ["", ...renderRushPlan(rushPlan, width, false, fg)] : [];
+              return rushPlan ? ["", ...renderRushPlan(rushPlan, width, false, fg, displayedWorkflowOwner)] : [];
             }
             if (!currentPlan) return [];
             return ["", ...renderCompactPlan(currentPlan, width, theme as never)];
@@ -237,20 +238,20 @@ export default function planExtension(pi: ExtensionAPI): void {
   const showFullPlan = async (ctx: ExtensionContext): Promise<void> => {
     const owner = workflowPlanOwner(ctx);
     if (owner) {
-      const plan = owner === "rush-issues" ? loadRushPlan(ctx) : null;
+      const plan = loadRushPlan(ctx);
       if (!plan) {
-        ctx.ui.notify(owner === "rush-issues" ? `Rush plan unavailable: ${rushError ?? "not bound"}` : `${owner} owns the task plan.`, "warning");
+        ctx.ui.notify(`${owner} plan unavailable: ${rushError ?? "not bound"}`, "warning");
         return;
       }
       if (ctx.mode !== "tui") {
-        ctx.ui.notify(renderRushPlan(plan, 160, true).join("\n"), "info");
+        ctx.ui.notify(renderRushPlan(plan, 160, true, undefined, owner).join("\n"), "info");
         return;
       }
       await ctx.ui.custom<void>((tui, theme, _keys, done) => {
         const fg = typeof theme?.fg === "function"
           ? (color: string, value: string) => theme.fg(color as never, value)
           : undefined;
-        const component = createRushPlanComponent(plan, () => done(), fg);
+        const component = createRushPlanComponent(plan, () => done(), fg, owner);
         return { render: (width) => component.render(width), handleInput(data) {
           component.handleInput?.(data);
           tui.requestRender();
@@ -284,13 +285,14 @@ export default function planExtension(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "sync_workflow_plan",
     label: "Sync Workflow Plan",
-    description: "Bind and display the persisted rush-issues task plan at its exact checkpoint revision. Record later transitions with update_plan's workflow field.",
+    description: "Bind and display an active workflow's compatible persisted task plan at its exact checkpoint revision. Record later transitions with update_plan's workflow field.",
     parameters: Type.Object({
       path: Type.String({ description: "Absolute path to .resolve-issues/rush/<run-id>/task-plan.json" }),
       revision: Type.Integer({ minimum: 0, description: "Persisted planRevision to display" }),
     }),
     async execute(_id, params, _signal, _onUpdate, ctx) {
-      if (workflowPlanOwner(ctx) !== "rush-issues") throw new Error("Only an active rush-issues workflow can sync its plan.");
+      const owner = workflowPlanOwner(ctx);
+      if (!owner) throw new Error("Only an active workflow can sync its plan.");
       const plan = readRushPlan(params.path, ctx.cwd);
       if (plan.planRevision !== params.revision) {
         rushPlan = null;
@@ -298,22 +300,23 @@ export default function planExtension(pi: ExtensionAPI): void {
         refresh(true);
         throw new Error(`Rush plan ${rushError}.`);
       }
-      const binding: WorkflowPlanBinding = { owner: "rush-issues", path: params.path, runId: plan.runId };
-      if (!rushBinding || rushBinding.path !== binding.path || rushBinding.runId !== binding.runId) {
+      const binding: WorkflowPlanBinding = { owner, path: params.path, runId: plan.runId };
+      if (!rushBinding || rushBinding.owner !== owner || rushBinding.path !== binding.path || rushBinding.runId !== binding.runId) {
         pi.appendEntry(WORKFLOW_PLAN_ENTRY, { version: 1, kind: "set", ...binding });
       }
+      displayedWorkflowOwner = owner;
       rushBinding = binding;
       rushPlan = plan;
       rushError = null;
       refresh(true);
-      return { content: [{ type: "text", text: `Showing rush-issues rev ${plan.planRevision}: ${plan.issues.length} units.` }], details: { runId: plan.runId, revision: plan.planRevision } };
+      return { content: [{ type: "text", text: `Showing ${owner} rev ${plan.planRevision}: ${plan.issues.length} units.` }], details: { runId: plan.runId, revision: plan.planRevision } };
     },
   });
 
   pi.registerTool({
     name: "update_plan",
     label: "Update Plan",
-    description: "Create or atomically replace the current structured execution plan and its step statuses. While rush-issues owns a bound plan, send workflow instead of plan to save one task-plan transition.",
+    description: "Create or atomically replace the current structured execution plan and its step statuses. While a workflow owns a bound plan, send workflow instead of plan to save one task-plan transition.",
     promptSnippet: "Create and update a persistent structured execution plan",
     promptGuidelines: [
       "Use update_plan for work with three or more meaningful steps unless a skill owns planning; update it immediately when a step completes, becomes blocked, or scope changes.",
@@ -322,7 +325,7 @@ export default function planExtension(pi: ExtensionAPI): void {
       "For generic plans, follow the active delegation mode. Manual forbids proactive delegation even in plan mode; adaptive favors substantial independent work; coordinator delegates nontrivial role-owned tasks after agents_catalog discovery.",
       "Use a generic plan as a milestone ledger only when no workflow owns planning. Otherwise follow the workflow's task plan and foreground role.",
       "For generic plans, use separate steps for distinct deliverables, not one step per worker process. Before completing verification or the plan, inspect and integrate every relevant delegated result or failure.",
-      "While rush-issues owns the plan and it is bound with sync_workflow_plan, record every transition with update_plan's workflow field instead of editing task-plan.json or its profiling log; it saves the rows, the next planRevision, and the matching profiling event together.",
+      "While a workflow owns the plan and it is bound with sync_workflow_plan, record every transition with update_plan's workflow field instead of editing task-plan.json or its profiling log; it saves the rows, the next planRevision, and the matching profiling event together.",
     ],
     parameters: UpdatePlanSchema,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -330,9 +333,8 @@ export default function planExtension(pi: ExtensionAPI): void {
       const input = params as { explanation?: string; plan?: PlanStepInput[]; workflow?: RushPlanUpdate };
       if (input.workflow !== undefined) {
         if (!owner) throw new Error("No workflow owns the task plan; send plan instead of workflow.");
-        if (owner !== "rush-issues") throw new Error(`${owner} owns the task plan and does not accept update_plan workflow changes.`);
         if (input.plan !== undefined) throw new Error("Send either plan or workflow, not both.");
-        if (!rushBinding) throw new Error("No rush-issues plan is bound; call sync_workflow_plan with the task-plan.json path first.");
+        if (!rushBinding || rushBinding.owner !== owner) throw new Error(`No ${owner} plan is bound; call sync_workflow_plan with the task-plan.json path first.`);
         const result = applyRushPlanUpdate(rushBinding.path, ctx.cwd, rushBinding.runId, input.workflow);
         rushPlan = result.plan;
         rushError = null;
@@ -342,7 +344,7 @@ export default function planExtension(pi: ExtensionAPI): void {
         const logNote = result.logAheadRevision === undefined ? ""
           : ` The profiling log already held rev ${result.logAheadRevision} (an earlier write stopped after logging); this event supersedes it.`;
         return {
-          content: [{ type: "text", text: `Saved rush-issues rev ${result.revision} (${input.workflow.event.trim()})${rows.length ? `: ${rows.join(", ")}` : ""}${input.workflow.decision ? `${rows.length ? ";" : ":"} decision ${input.workflow.decision.id}` : ""}. Profiling: ${result.profilingPath}.${logNote}` }],
+          content: [{ type: "text", text: `Saved ${owner} rev ${result.revision} (${input.workflow.event.trim()})${rows.length ? `: ${rows.join(", ")}` : ""}${input.workflow.decision ? `${rows.length ? ";" : ":"} decision ${input.workflow.decision.id}` : ""}. Profiling: ${result.profilingPath}.${logNote}` }],
           details: {
             ok: true, runId: result.plan.runId, revision: result.revision, changed: result.changed, profilingPath: result.profilingPath,
             ...(result.logAheadRevision === undefined ? {} : { logAheadRevision: result.logAheadRevision }),
@@ -350,9 +352,7 @@ export default function planExtension(pi: ExtensionAPI): void {
         };
       }
       if (owner) {
-        throw new Error(owner === "rush-issues"
-          ? "rush-issues owns the task plan. Send workflow (bound with sync_workflow_plan) instead of plan."
-          : `${owner} owns the task plan. Update its workflow plan instead of update_plan.`);
+        throw new Error(`${owner} owns the task plan. Send workflow (bound with sync_workflow_plan) instead of plan.`);
       }
       if (input.plan === undefined) throw new Error("plan is required: send the full list of steps.");
       const plan = replacePlan(currentPlan, input.plan, input.explanation);
@@ -387,10 +387,10 @@ export default function planExtension(pi: ExtensionAPI): void {
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
       const owner = workflowPlanOwner(ctx);
       if (owner) {
-        const workflowPlan = owner === "rush-issues" ? loadRushPlan(ctx) : null;
+        const workflowPlan = loadRushPlan(ctx);
         return {
           content: [{ type: "text", text: workflowPlan
-            ? renderRushPlan(workflowPlan, 160, true).join("\n")
+            ? renderRushPlan(workflowPlan, 160, true, undefined, owner).join("\n")
             : `${owner} owns the task plan; ${rushError ?? "consult its persisted workflow state"}.` }],
           details: { hasPlan: !!workflowPlan, plan: workflowPlan, progress: null, workflowOwner: owner },
         };

package/node_modules/pi-better-plan/src/workflow-plan.ts

@@ -28,7 +28,7 @@ export interface RushPlan {
 }
 
 export interface WorkflowPlanBinding {
-  owner: "rush-issues";
+  owner: string;
   path: string;
   runId: string;
 }
@@ -113,9 +113,9 @@ export function workflowBinding(entries: Iterable<{ type: string; customType?: s
     const data = entry.data;
     if (!isRecord(data) || data.version !== 1) continue;
     if (data.kind === "clear") binding = null;
-    else if (data.kind === "set" && data.owner === "rush-issues" &&
+    else if (data.kind === "set" && typeof data.owner === "string" && data.owner.length > 0 &&
              typeof data.path === "string" && typeof data.runId === "string") {
-      binding = { owner: "rush-issues", path: data.path, runId: data.runId };
+      binding = { owner: data.owner, path: data.path, runId: data.runId };
     }
   }
   return binding;
@@ -133,7 +133,7 @@ function workflowStatus(status: string): DisplayStatus {
   }
 }
 
-function presentRushPlan(plan: RushPlan): PlanPresentation {
+function presentRushPlan(plan: RushPlan, owner: string): PlanPresentation {
   // The warehouse canary only applies to data work; hide it otherwise.
   const stages = ["explore", "implement", "review", "ci", ...(plan.warehouseCanaryRequired ? ["canary"] : [])];
   const fleet = stages.map((stage) => {
@@ -142,7 +142,7 @@ function presentRushPlan(plan: RushPlan): PlanPresentation {
     const style = statusStyle(display);
     return { color: style.color, text: `  ${stage} ${style.glyph}${display === "unknown" ? ` ${planText(status)}` : ""}` };
   });
-  const metadata = [[{ color: "dim", text: `rush-issues · rev ${plan.planRevision}  ·` }, ...fleet]];
+  const metadata = [[{ color: "dim", text: `${planText(owner)} · rev ${plan.planRevision}  ·` }, ...fleet]];
   if (plan.spec?.title) metadata.push([{ color: "dim", text: plan.spec.title }]);
   return {
     metadata,
@@ -164,16 +164,18 @@ export function renderRushPlan(
   width: number,
   full = false,
   fg?: (color: string, value: string) => string,
+  owner = "rush-issues",
 ): string[] {
   const theme = fg ? { fg } : plainPlanTheme;
-  return renderPlanPresentation(presentRushPlan(plan), width, theme, full);
+  return renderPlanPresentation(presentRushPlan(plan, owner), width, theme, full);
 }
 
 export function createRushPlanComponent(
   plan: RushPlan,
   onClose: () => void,
   fg?: (color: string, value: string) => string,
+  owner = "rush-issues",
 ): Component {
   const theme = fg ? { fg } : plainPlanTheme;
-  return createPlanPresentationComponent(presentRushPlan(plan), theme, onClose);
+  return createPlanPresentationComponent(presentRushPlan(plan, owner), theme, onClose);
 }

package/node_modules/pi-better-sandbox/README.md

@@ -2,6 +2,8 @@
 
 Sandbox permissions for Pi's foreground tools and detached subagents.
 
+![Pi Better Sandbox package preview](https://raw.githubusercontent.com/1aboveio/pi-better-harness/main/docs/images/package-gallery/pi-better-sandbox.png)
+
 It is installed by default with [`pi-better-harness`](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-harness#readme), and can be installed on its own:
 
 ```sh
@@ -386,6 +388,41 @@ credential stores under a read-only outside root, a writable outside root
 The macOS permission combinations are covered by real-kernel tests; Linux
 mount behavior requires a Linux runner with Bubblewrap and user namespaces.
 
+### macOS setuid executable limitation
+
+Seatbelt-sandboxed processes cannot execute setuid/setgid binaries, even with
+an `(allow default)` profile. On the verified host, `/bin/ps` and `/usr/bin/top`
+are setuid-root binaries. A shell attempting to run `/bin/ps` reports
+`Operation not permitted` and exits 126. This is an OS-level execution
+restriction, not a harness command deny rule, a filesystem permission failure,
+or evidence that Run commands & applications is Off.
+
+Read-only reproduction (verified on 2026-10-04):
+
+```sh
+ls -l /bin/ps /usr/bin/top
+/usr/bin/sandbox-exec -p '(version 1) (allow default)' \
+  /bin/bash -c '/bin/ps -p $$ -o pid,ppid,comm'
+```
+
+The second command fails with `/bin/bash: /bin/ps: Operation not permitted`
+and exit 126; the same `ps` query outside Seatbelt succeeds. Launching `ps`
+directly through `sandbox-exec` instead reports `execvp()` failure and exit 71.
+Changing the requested output fields or adding a profile allowance for `ps`
+does not remove this limitation.
+
+When process inspection is a prerequisite for safe work, do not interpret the
+denial as an empty process list. Hold the dependent operation until an
+authorized coordinator or environment custodian supplies a fresh snapshot
+and explicit ownership handoff from outside the task sandbox. Prefer
+`pid,ppid,pgid,lstart,comm` over full command arguments, which may expose
+secrets. Do not disable the sandbox or modify/copy privileged executables to
+work around the denial. A trusted process-inspection adapter would require
+separate implementation; this package does not currently provide one.
+
+See the [session evidence](../../docs/sandbox-session-validation.md#macos-process-inspection-follow-up)
+and [documented setuid/setgid limitation](https://github.com/navikt/cplt/blob/main/docs/known-impacts.md).
+
 ## For other extensions
 
 The effective policy is published as a frozen snapshot on Pi's extension event

package/node_modules/pi-better-sandbox/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-sandbox",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Pi extension with independent Main and Subagents permission profiles, file guards, and OS sandbox enforcement.",
   "license": "MIT",
   "type": "module",
@@ -16,7 +16,8 @@
   "pi": {
     "extensions": [
       "./index.ts"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/1aboveio/pi-better-harness/main/docs/images/package-gallery/pi-better-sandbox.png"
   },
   "repository": {
     "type": "git",

package/node_modules/pi-better-ssh/README.md

@@ -2,6 +2,8 @@
 
 `pi-better-ssh` runs short synchronous remote commands over safe, reusable SSH connections. It adds explicit remote tools; Pi's built-in `bash` remains local and is never overridden.
 
+![Pi Better SSH package preview](https://raw.githubusercontent.com/1aboveio/pi-better-harness/main/docs/images/package-gallery/pi-better-ssh.png)
+
 ## Install
 
 ```sh

package/node_modules/pi-better-ssh/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-ssh",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Pi extension for safe synchronous remote bash commands over reusable SSH connections.",
   "license": "MIT",
   "type": "module",
@@ -14,7 +14,8 @@
   "pi": {
     "extensions": [
       "./src/index.ts"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/1aboveio/pi-better-harness/main/docs/images/package-gallery/pi-better-ssh.png"
   },
   "repository": {
     "type": "git",

package/node_modules/pi-better-subagents/docs/usage.md

@@ -246,13 +246,17 @@ given.
   Its context can't clog the parent, its crash can't corrupt parent state, and
   its output is durable in a log file.
 - **Completions trigger one batched turn that fetches durable results.** Ordinary
-  terminal callbacks accumulate for 100 ms and share one
+  terminal callbacks stay in the harness queue while the foreground agent is
+  busy. Once Pi is idle, they accumulate for 100 ms and share one
   `pi.sendMessage(..., { deliverAs: "followUp", triggerTurn: true })` notification
   with background-task completions from the same Pi host. Each row contains only
   source, id, label, terminal status, and the `subagent_result` lookup. Full
   results and logs stay in durable tools and are never embedded in the callback.
   Set `PI_BETTER_CALLBACK_BATCH_MS` to `0` through `5000` milliseconds to tune
-  the accumulation window; invalid values use 100 ms. A failed handoff keeps the
+  the accumulation window; invalid values use 100 ms. `agent_settled` schedules
+  the aggregate without starting a model run inside the lifecycle handler.
+  Completions arriving during that model run, including bounded overflow,
+  stay queued for the next available boundary. A failed handoff keeps the
   pending records retryable, and `/reload` recovers records explicitly marked
   pending. `callback:false` sends no model message; read the durable result later
   with `subagent_result`.
@@ -649,10 +653,11 @@ only after a successful handoff and dedupe across reloads and repeated health ti
 Persisted unmarked orphaned/lost states are recovered on the health ticker after
 `/reload` even when process evidence does not produce a fresh transition.
 
-Pi's optional `followUpMode: all` remains useful when completion groups arrive
-after an earlier 100 ms batch has already flushed: Pi can consume those queued
-follow-ups in one later agent turn. This extension does not change Pi core or
-Pi's default follow-up mode.
+Ordinary completion batching does not depend on Pi's `followUpMode`: events
+stay in the harness until availability rather than becoming separate queued
+follow-ups during the foreground run. Urgent health/failure alerts retain their
+existing immediate follow-up behavior. This extension does not change Pi core
+or Pi's default follow-up mode.
 
 ### Surfacing health (tools + passive widget)
 

package/node_modules/pi-better-subagents/index.ts

@@ -116,7 +116,7 @@ import {
     getSharedCapacityGate,
 } from "./capacity.mjs";
 import { buildHealthCallbackDelivery } from "./completion.ts";
-import { cancelCallbackBatch, getCallbackBatcher } from "./shared-callback-batcher.ts";
+import { cancelCallbackBatch, getCallbackBatcher, setCallbackBatchContext } from "./shared-callback-batcher.ts";
 import { completionCallbackFields, failureAttentionFields, healthCallbackFields } from "./callback-fields.ts";
 import { collectRunFailures, failurePath, markFailureAttentionDelivered, pendingFailureAttention } from "./failures.ts";
 import { failureAttentionHandled, observeFailures } from "./shared-failure-observations.ts";
@@ -2340,6 +2340,7 @@ export default function (pi: ExtensionAPI) {
 
     // ---- live-status lifecycle -----------------------------------------
     pi.on("agent_start", async (_event, ctx) => {
+        setCallbackBatchContext(pi, ctx);
         uiCtx = ctx;
         mainAgentStartedAt = Date.now();
         mainAgentTools.clear();
@@ -2372,6 +2373,7 @@ export default function (pi: ExtensionAPI) {
     });
 
     pi.on("agent_settled", async (_event, ctx) => {
+        setCallbackBatchContext(pi, ctx);
         mainAgentStartedAt = undefined;
         mainAgentTools.clear();
         refreshBackgroundWorkNavigator(ctx);
@@ -2387,6 +2389,7 @@ export default function (pi: ExtensionAPI) {
     // alive, resume the ticking widget. Deferred out of the factory per pi's
     // "no background resources at load" rule.
     pi.on("session_start", async (_event, ctx) => {
+        setCallbackBatchContext(pi, ctx);
         agentSessionSettings.restore(ctx);
         restoreDelegationMode(ctx);
         uiCtx = ctx;

package/node_modules/pi-better-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
   "license": "MIT",
   "type": "module",

package/node_modules/pi-better-subagents/shared-callback-batcher.ts

@@ -3,6 +3,8 @@ export type CallbackSource = "subagent" | "background-task";
 export type CallbackDetailTool = "subagent_result" | "bg_task_status";
 
 export interface CallbackBatchHost {
+  /** Older Pi shares this object; newer Pi supplies per-extension wrappers. */
+  events?: object;
   sendMessage(
     message: { customType: string; content: string; display: boolean },
     options: Record<string, unknown>,
@@ -66,6 +68,8 @@ export interface UrgentCallbackEvent {
 export interface CallbackBatcherOptions {
   windowMs?: number;
   retryMs?: number;
+  /** Ordinary callbacks stay here, not in Pi's follow-up queue, while unavailable. */
+  isAvailable?: () => boolean;
   /** UTF-8 byte cap for one sendMessage payload. Defaults to 2 KiB. */
   maxBytes?: number;
 }
@@ -73,6 +77,10 @@ export interface CallbackBatcherOptions {
 export interface CallbackBatcher {
   enqueue(event: CallbackBatchEvent): boolean;
   flush(): Promise<boolean>;
+  /** Refresh the API wrapper after reload without losing handoff receipts. */
+  setHost(host: CallbackBatchHost): void;
+  /** Update the session predicate and schedule an asynchronous drain when available. */
+  setAvailability(isAvailable: () => boolean): void;
   deliverUrgent(event: UrgentCallbackEvent): boolean | Promise<boolean>;
   cancel(): void;
   pendingCount(): number;
@@ -95,6 +103,7 @@ interface PendingEvent {
 
 interface SharedCallbackBatcherState {
   byHost: WeakMap<object, CallbackBatcher>;
+  bySession?: WeakMap<object, CallbackBatcher>;
 }
 
 const GLOBAL_STATE_KEY = Symbol.for("@1aboveio/pi-better-harness/callback-batcher");
@@ -435,6 +444,19 @@ export function createCallbackBatcher(
   let sequence = 0;
   let timer: ReturnType<typeof setTimeout> | undefined;
   let flushPromise: Promise<boolean> | undefined;
+  let isAvailable = options.isAvailable ?? (() => true);
+  let gated = options.isAvailable !== undefined;
+  let awaitingRun = false;
+
+  const available = (): boolean => {
+    try {
+      if (!isAvailable()) {
+        awaitingRun = false;
+        return false;
+      }
+      return !awaitingRun;
+    } catch { return false; }
+  };
 
   const cancelTimer = (): void => {
     if (timer) clearTimeout(timer);
@@ -443,10 +465,12 @@ export function createCallbackBatcher(
 
   const schedule = (delayMs: number): void => {
     if (timer || pending.size === 0) return;
+    // Some idle transitions (manual compaction) have no agent_settled event.
+    const delay = available() ? delayMs : retryMs;
     timer = setTimeout(() => {
       timer = undefined;
       void api.flush();
-    }, Math.max(0, delayMs));
+    }, Math.max(1, delay));
     timer.unref?.();
   };
 
@@ -461,6 +485,10 @@ export function createCallbackBatcher(
 
   const performFlush = async (): Promise<boolean> => {
     cancelTimer();
+    if (!available()) {
+      schedule(retryMs);
+      return false;
+    }
     const snapshot = [...pending.entries()]
       .sort((a, b) => a[1].sequence - b[1].sequence);
     pending.clear();
@@ -509,6 +537,9 @@ export function createCallbackBatcher(
     const overflowItems = deliverable.filter(([, item]) => !representedSet.has(item.event));
 
     try {
+      // Pi may defer the requested run while settled handlers finish, leaving
+      // isIdle() true. Permit no second handoff until a run starts.
+      awaitingRun = gated;
       await host.sendMessage(
         {
           customType: "background-completion-batch",
@@ -518,6 +549,7 @@ export function createCallbackBatcher(
         { deliverAs: "followUp", triggerTurn: true },
       );
     } catch {
+      awaitingRun = false;
       for (const [key] of deliverable) inFlight.delete(key);
       const retryItems = [...deliverable, ...pending.entries()]
         .sort((a, b) => a[1].sequence - b[1].sequence);
@@ -596,10 +628,19 @@ export function createCallbackBatcher(
   const api: CallbackBatcher = {
     enqueue,
     flush,
+    setHost(next) { host = next; },
+    setAvailability(check) {
+      gated = true;
+      isAvailable = check;
+      available();
+      cancelTimer();
+      schedule(windowMs);
+    },
     deliverUrgent,
     cancel() {
       cancelTimer();
       pending.clear();
+      awaitingRun = false;
     },
     pendingCount() {
       return pending.size;
@@ -613,16 +654,38 @@ export function getCallbackBatcher(
   options: CallbackBatcherOptions = {},
 ): CallbackBatcher {
   const state = globalState();
-  const key = host as object;
+  const key = host.events ?? host;
   const existing = state.byHost.get(key);
-  if (existing) return existing;
+  if (existing) {
+    existing.setHost(host);
+    return existing;
+  }
   const created = createCallbackBatcher(host, options);
   state.byHost.set(key, created);
   return created;
 }
 
 export function cancelCallbackBatch(host: CallbackBatchHost): void {
-  globalState().byHost.get(host as object)?.cancel();
+  const batcher = globalState().byHost.get(host.events ?? host);
+  batcher?.setAvailability(() => false);
+  batcher?.cancel();
+}
+
+/** Called on session_start, agent_start and agent_settled by both extensions. */
+export function setCallbackBatchContext(
+  host: CallbackBatchHost,
+  ctx: { isIdle(): boolean; sessionManager?: object },
+): void {
+  const state = globalState();
+  const bySession = state.bySession ??= new WeakMap<object, CallbackBatcher>();
+  const shared = ctx.sessionManager ? bySession.get(ctx.sessionManager) : undefined;
+  const batcher = shared ?? getCallbackBatcher(host);
+  if (ctx.sessionManager) bySession.set(ctx.sessionManager, batcher);
+  state.byHost.set(host.events ?? host, batcher);
+  batcher.setHost(host);
+  // Schedule rather than await delivery inside agent_settled: its handlers are
+  // still settling the previous run, and sendMessage may start a new one.
+  batcher.setAvailability(() => ctx.isIdle());
 }
 
 function globalState(): SharedCallbackBatcherState {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-harness",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Pi extension bundle for a write sandbox, subagents, background tasks, SSH, goals, and structured plans.",
   "license": "MIT",
   "type": "module",
@@ -52,12 +52,12 @@
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
-    "pi-better-background-tasks": "0.6.3",
-    "pi-better-goal": "0.6.1",
-    "pi-better-plan": "0.5.2",
-    "pi-better-sandbox": "0.9.0",
-    "pi-better-ssh": "0.1.1",
-    "pi-better-subagents": "0.13.0",
+    "pi-better-background-tasks": "0.6.4",
+    "pi-better-goal": "0.7.0",
+    "pi-better-plan": "0.5.4",
+    "pi-better-sandbox": "0.9.1",
+    "pi-better-ssh": "0.1.2",
+    "pi-better-subagents": "0.13.1",
     "smol-toml": "1.9.0",
     "yaml": "^2.9.1"
   },