pi-better-harness 0.3.5 → 0.3.7

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "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/tools.ts

@@ -103,6 +103,12 @@ const StatusActionParams = Type.Object({
   verbose: Type.Optional(Type.Boolean()),
 });
 
+const BACKGROUND_ORCHESTRATION_GUIDELINES = [
+  "Use background tasks for genuinely long-running processes or repeated checks. Run short commands in the foreground.",
+  "When a structured plan is active, keep it as the coordinator ledger: launch relevant background work early, continue unblocked foreground work without polling, and update the plan after inspecting each terminal result or failure.",
+  "Do not treat launch as completion of the parent milestone; relevant background work must be terminal, inspected, and integrated before verification or completion.",
+];
+
 export function registerTools(pi: ExtensionAPI): void {
   let activeSession: BackgroundTaskCallbackOrigin | undefined;
   const getActiveSession = () => activeSession;
@@ -125,6 +131,7 @@ export function registerTools(pi: ExtensionAPI): void {
     name: "bg_task_spawn",
     label: "BG Spawn",
     description: "Start a long-running background process and return immediately with its task id. For remote work, prefer structured ssh: pass ssh:{host,user} and put the remote command in command; spawn defaults to a remote tmux session with durable local logs and real remote stop. For short synchronous remote commands that should return output now, use remote_bash from pi-better-ssh. If tmux is missing, the preset attempts to install tmux non-interactively and fails closed with operator guidance when setup cannot proceed. Explicit remote.session=direct skips tmux, but direct mode has weaker stop semantics and may leave the remote process running. Never wait or poll in the foreground.",
+    promptGuidelines: BACKGROUND_ORCHESTRATION_GUIDELINES,
     parameters: SpawnParams,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       activeSession = getCallbackOrigin(ctx);
@@ -138,6 +145,7 @@ export function registerTools(pi: ExtensionAPI): void {
     name: "bg_task_watch",
     label: "BG Watch",
     description: "Poll a command in the background until success_when, failure_when, or timeout matches. For remote work, prefer structured ssh: pass ssh:{host,user} and provide the remote command in command; each interval opens a direct one-shot SSH poll without tmux installation. For short synchronous remote commands that should return output now, use remote_bash from pi-better-ssh. Returns immediately with its task id. Default timeout 900 seconds; pass timeout_seconds:0 to disable.",
+    promptGuidelines: BACKGROUND_ORCHESTRATION_GUIDELINES,
     parameters: WatchParams,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       activeSession = getCallbackOrigin(ctx);
@@ -198,6 +206,7 @@ export function registerTools(pi: ExtensionAPI): void {
     name: "bg_task",
     label: "BG Task",
     description: "Action wrapper for background tasks: spawn, watch, list, status, log, stop, or clear. For remote work, prefer structured ssh: pass ssh:{host,user} and provide the remote command in command. For short synchronous remote commands that should return output now, use remote_bash from pi-better-ssh. SSH spawn defaults to durable tmux; SSH watches use direct one-shot polls without tmux installation; remote.session=direct is a weaker-stop spawn escape hatch. Spawn/watch return immediately; do not poll in foreground. For action:status, default compact output and use verbose:true only for full metadata. For action:log, default compact tail and use tail_lines:0 only for explicit full logs.",
+    promptGuidelines: BACKGROUND_ORCHESTRATION_GUIDELINES,
     parameters: ActionParams,
     renderResult(result: unknown, options: unknown, theme: unknown) {
       return renderBackgroundTaskLogDisplay(result, options, theme);

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

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

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

@@ -713,7 +713,7 @@ export default function (pi: ExtensionAPI): void {
     }
 
     const backgroundInstruction = snapshot.backgroundRunning
-      ? ` The goal still has delegated background work running (${summarizeActiveBackground(snapshot)}). Foreground idleness alone is not goal completion; do not mark the goal complete until delegated background work reaches a terminal state and its result or failure has been inspected.`
+      ? ` The goal still has delegated background work running (${summarizeActiveBackground(snapshot)}). Foreground idleness alone is not goal completion; keep any structured plan current and do not mark verification, the plan, or the goal complete until every relevant delegated task reaches a terminal state and its result or failure has been inspected and integrated.`
       : "";
     return {
       systemPrompt:

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

@@ -7,10 +7,17 @@
 - Gives models `update_plan` and `get_plan` tools for atomic, explicit progress updates.
 - Shows the complete checklist of completed, active, pending, and blocked steps above the editor.
 - Persists plan state and display preferences on the active Pi session branch.
+- Keeps a completed plan visible for 30 seconds, then clears it automatically.
 - Opens the complete plan with `/plan`.
 
 Plan progress is checklist progress, not an estimate of effort. The extension never infers completion from prose or successful tool calls.
 
+## Coordinating Delegated Work
+
+Use the plan as the foreground coordinator's milestone ledger. Delegate independent, sufficiently substantial work early with subagents, and use background tasks for long-running processes or repeated checks. Keep doing unblocked foreground work after launch; do not poll workers.
+
+Concurrent workers belong under one `in_progress` coordinator step rather than one active plan step per worker. Worker tools and the background-work navigator own individual run status. Complete verification and the plan only after every relevant delegated task is terminal and its result or failure has been inspected and integrated.
+
 ## Install
 
 ```sh

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-plan",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Structured execution plans with persistent progress for Pi.",
   "license": "MIT",
   "type": "module",
@@ -70,4 +70,4 @@
   "engines": {
     "node": ">=22.0.0"
   }
-}
+}

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

@@ -4,6 +4,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 import {
+  completedPlanClearDelay,
   planClearEntry,
   planDisplayEntry,
   planProgress,
@@ -42,21 +43,53 @@ export default function planExtension(pi: ExtensionAPI): void {
   let currentPlan: PlanSnapshot | null = null;
   let displayMode: PlanDisplayMode = "auto";
   let refreshWidget: ((force?: boolean) => void) | undefined;
+  let completedPlanClearTimer: ReturnType<typeof setTimeout> | undefined;
 
   const refresh = (force = false): void => refreshWidget?.(force);
 
+  const cancelCompletedPlanClear = (): void => {
+    if (completedPlanClearTimer) clearTimeout(completedPlanClearTimer);
+    completedPlanClearTimer = undefined;
+  };
+
+  const clearPlan = (): void => {
+    cancelCompletedPlanClear();
+    currentPlan = null;
+    pi.appendEntry(EXTENSION_NAME, planClearEntry());
+    refresh(true);
+  };
+
+  const scheduleCompletedPlanClear = (): void => {
+    cancelCompletedPlanClear();
+    if (!currentPlan) return;
+    const delay = completedPlanClearDelay(currentPlan);
+    if (delay === null) return;
+    const completedPlan = currentPlan;
+    const timer = setTimeout(() => {
+      if (completedPlanClearTimer !== timer) return;
+      completedPlanClearTimer = undefined;
+      if (currentPlan?.planId !== completedPlan.planId || currentPlan.revision !== completedPlan.revision) return;
+      clearPlan();
+    }, delay);
+    completedPlanClearTimer = timer;
+    timer.unref?.();
+  };
+
   const restore = (ctx: ExtensionContext): void => {
+    cancelCompletedPlanClear();
     const state = reconstructPlanState(ctx.sessionManager.getBranch());
     currentPlan = state.plan;
     displayMode = state.displayMode;
     if (ctx.hasUI) ctx.ui.setStatus(LEGACY_PLAN_NAV_STATUS_KEY, undefined);
     refresh(true);
+    scheduleCompletedPlanClear();
   };
 
   const persistPlan = (plan: PlanSnapshot): void => {
     currentPlan = plan;
     pi.appendEntry(EXTENSION_NAME, planSetEntry(plan));
     refresh(true);
+    scheduleCompletedPlanClear();
   };
 
   const setDisplayMode = (mode: PlanDisplayMode): void => {
@@ -119,6 +152,8 @@ export default function planExtension(pi: ExtensionAPI): void {
     promptGuidelines: [
       "Use update_plan for work with three or more meaningful steps, and update it immediately when a step completes, becomes blocked, or scope changes.",
       "Keep at most one update_plan step in_progress and do not mark a step completed until its required verification succeeds.",
+      "Use the plan as the foreground coordinator's milestone ledger. Delegate independent, sufficiently substantial work early when subagent or background-task tools are available, and continue unblocked foreground work instead of waiting or polling.",
+      "Represent concurrent delegated work under one in_progress coordinator step. Before completing verification or the plan, ensure every relevant delegated task is terminal, then inspect and integrate its result or failure.",
     ],
     parameters: UpdatePlanSchema,
     async execute(_toolCallId, params) {
@@ -171,9 +206,7 @@ export default function planExtension(pi: ExtensionAPI): void {
       const input = args.trim().toLowerCase();
       if (!input) return showFullPlan(ctx);
       if (input === "clear") {
-        currentPlan = null;
-        pi.appendEntry(EXTENSION_NAME, planClearEntry());
-        refresh(true);
+        clearPlan();
         ctx.ui.notify("Plan cleared.", "info");
         return;
       }
@@ -209,6 +242,7 @@ export default function planExtension(pi: ExtensionAPI): void {
     };
   });
   pi.on("session_shutdown", async (_event, ctx) => {
+    cancelCompletedPlanClear();
     refreshWidget = undefined;
     try {
       ctx.ui.setStatus(LEGACY_PLAN_NAV_STATUS_KEY, undefined);
@@ -238,6 +272,8 @@ function planPrompt(plan: PlanSnapshot): string {
   return [
     "Current structured execution plan:",
     ...plan.steps.map((item, index) => `${index + 1}. [${item.status}] ${item.step}`),
-    "Use update_plan immediately when a step completes, becomes blocked, or the scope changes. Completion must be explicit and evidence-backed.",
+    "Use update_plan immediately when a step completes, becomes blocked, or the scope changes.",
+    "Treat the plan as the foreground coordinator's milestone ledger: delegate independent, sufficiently substantial work early, keep one coordinator step in_progress across concurrent workers, and continue unblocked foreground work instead of waiting or polling.",
+    "Do not complete verification or the plan until relevant delegated work is terminal, its results or failures have been inspected and integrated, and the outcome is evidence-backed.",
   ].join("\n");
 }

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

@@ -4,6 +4,7 @@ import { EXTENSION_NAME } from "./types.js";
 const MAX_STEPS = 50;
 const MAX_STEP_CHARS = 500;
 const MAX_EXPLANATION_CHARS = 2_000;
+export const COMPLETED_PLAN_RETENTION_MS = 30_000;
 
 interface SessionEntryLike {
   type: string;
@@ -54,6 +55,7 @@ export function replacePlan(
   steps: readonly PlanStepInput[],
   explanation?: string,
   now = nowSeconds(),
+  completedAtMs = Date.now(),
 ): PlanSnapshot {
   const error = validatePlanInput(steps, explanation);
   if (error) throw new Error(error);
@@ -68,6 +70,8 @@ export function replacePlan(
       status: item.status,
     };
   });
+  const isComplete = normalizedSteps.every((item) => item.status === "completed");
+  const currentIsComplete = current?.steps.every((item) => item.status === "completed") === true;
 
   return {
     version: 1,
@@ -77,9 +81,18 @@ export function replacePlan(
     steps: normalizedSteps,
     createdAt: current?.createdAt ?? now,
     updatedAt: now,
+    ...(isComplete
+      ? { completedAtMs: currentIsComplete ? current.completedAtMs ?? current.updatedAt * 1_000 : completedAtMs }
+      : {}),
   };
 }
 
+export function completedPlanClearDelay(plan: PlanSnapshot, now = Date.now()): number | null {
+  if (planProgress(plan).state !== "complete") return null;
+  const completedAtMs = plan.completedAtMs ?? plan.updatedAt * 1_000;
+  return Math.max(0, completedAtMs + COMPLETED_PLAN_RETENTION_MS - now);
+}
+
 export function planProgress(plan: PlanSnapshot): PlanProgress {
   const completed = plan.steps.filter((item) => item.status === "completed").length;
   const pending = plan.steps.filter((item) => item.status === "pending").length;
@@ -149,6 +162,7 @@ function isPlanSnapshot(value: unknown): value is PlanSnapshot {
     typeof candidate.revision === "number" &&
     Array.isArray(candidate.steps) &&
     typeof candidate.createdAt === "number" &&
-    typeof candidate.updatedAt === "number"
+    typeof candidate.updatedAt === "number" &&
+    (candidate.completedAtMs === undefined || typeof candidate.completedAtMs === "number")
   );
 }

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

@@ -20,6 +20,7 @@ export interface PlanSnapshot {
   steps: PlanStep[];
   createdAt: number;
   updatedAt: number;
+  completedAtMs?: number;
 }
 
 export interface PlanProgress {

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

@@ -127,6 +127,11 @@ const SUBAGENT_TOOLS = [
     "subagent_result",
 ];
 
+const SUBAGENT_ORCHESTRATION_GUIDELINES = [
+    "When a structured plan is active, keep it as the parent-owned coordinator ledger: delegate bounded independent work, continue unblocked foreground work, and update the plan after integrating each result or failure.",
+    "Do not treat launching a subagent as completion of the parent milestone; relevant terminal results must be inspected and integrated before verification or completion.",
+];
+
 const GOAL_READY_EVENT = "pi-better-goal:ready";
 const GOAL_REGISTER_PROVIDER_EVENT = "pi-better-goal:register-provider";
 const goalReadySubscriptions = new WeakSet<ExtensionAPI>();
@@ -1267,7 +1272,8 @@ export default function (pi: ExtensionAPI) {
         promptGuidelines: [
             "Use subagent_spawn for independent work the user should not have to wait on. It returns at once with a run id; that return IS the deliverable — report the id to the user and continue.",
             "After subagent_spawn, do NOT call subagent_output or subagent_result in a loop to wait for the result, and do NOT sleep. The run completes on its own and reports back on the next turn.",
-            "Only call subagent_result / subagent_output when the user explicitly asks how a run is going or for its result.",
+            "Call subagent_result after a completion or attention callback, or when the user explicitly asks for the result. Use subagent_output only when the user explicitly asks how a run is progressing; never use either tool to poll.",
+            ...SUBAGENT_ORCHESTRATION_GUIDELINES,
             "The tools param is both the tool allowlist AND what determines which extensions load in the child (e.g. tools='read,bash,web_fetch' loads only the web-tools package). Ask for the tools the task needs and nothing more; clean:true gives a built-ins-only child. Pick a model with the model param (e.g. 'xai/grok-4.5@high'); providerless model patterns are resolved by Pi, while provider/model is deterministic and loads mapped provider extensions.",
             "By default the subagent is sandboxed (writes confined to its working dir, reads and network open) and triggers completion here on finish. Set callback:false to finish quietly — then read the result on demand via subagent_result.",
             "Use git_clone_workspace:true when the subagent will mutate Git in a sandbox. The parent prepares a disposable, self-contained clone with a real .git/ directory inside the sandbox root, so linked-worktree metadata outside the sandbox cannot stall the child.",
@@ -1336,6 +1342,7 @@ export default function (pi: ExtensionAPI) {
             "Use subagent_spawn_batch when you have several independent tasks to delegate. It returns immediately with a batch id and one run id per launched job.",
             "Each job is a normal subagent run; use subagent_result / subagent_output / subagent_stop with the individual run ids just like subagent_spawn.",
             "Do NOT poll for results. Each job reports back on its own when it finishes.",
+            ...SUBAGENT_ORCHESTRATION_GUIDELINES,
             "By default the whole batch is rejected if there is not enough capacity. Set onCapacity to 'launch-available' to launch as many as fit and report the rest as skipped.",
         ],
         parameters: Type.Object({

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-harness",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Pi extension bundle for a write sandbox, subagents, background tasks, SSH, goals, and structured plans.",
   "license": "MIT",
   "type": "module",
@@ -50,12 +50,12 @@
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
-    "pi-better-background-tasks": "0.2.11",
-    "pi-better-goal": "0.2.1",
-    "pi-better-plan": "0.1.3",
+    "pi-better-background-tasks": "0.2.12",
+    "pi-better-goal": "0.2.2",
+    "pi-better-plan": "0.1.5",
     "pi-better-sandbox": "0.3.0",
     "pi-better-ssh": "0.1.1",
-    "pi-better-subagents": "0.1.26"
+    "pi-better-subagents": "0.1.27"
   },
   "bundledDependencies": [
     "pi-better-background-tasks",