pi-better-harness 0.17.1 → 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.

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-plan",
-  "version": "0.5.3",
+  "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-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.1",
+  "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.3",
-    "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"
   },