pi-better-harness 0.3.2 → 0.3.4

package/README.md

@@ -1,6 +1,6 @@
 # pi-better-harness
 
-`pi-better-harness` is a Pi meta package that installs the core Pi Better Harness extensions: an opt-in foreground write sandbox, delegated subagents, durable background tasks, and goal tracking.
+`pi-better-harness` is a Pi meta package that installs the core Pi Better Harness extensions: an opt-in foreground write sandbox, delegated subagents, durable background tasks, synchronous SSH commands, goal tracking, and structured plans.
 
 ## Quick Answer
 
@@ -9,9 +9,11 @@ Use `pi-better-harness` when you want the full working set for Pi. It manages:
 - `pi-better-sandbox` for an opt-in write sandbox around Pi's foreground tools.
 - `pi-better-subagents` for detached, sandboxed subagent runs.
 - `pi-better-background-tasks` for durable shell tasks and watchers.
+- `pi-better-ssh` for short remote commands over reusable SSH connections.
 - `pi-better-goal` for objective tracking that is aware of background work.
+- `pi-better-plan` for persistent structured plans and explicit checklist progress.
 
-`pi-better-plan` and `pi-better-read-aloud` are intentionally not included yet.
+`pi-better-read-aloud` is intentionally not included yet.
 
 ## Screenshots
 
@@ -60,7 +62,7 @@ need interactive confirmation. Full policy: [pi-better-sandbox](https://github.c
 
 ## When To Use
 
-Use the installer when you want every core extension with standalone package identities. Install an individual package instead when you only need the sandbox, subagents, shell task supervision, or goal tracking.
+Use the installer when you want every core extension with standalone package identities. Install an individual package instead when you only need the sandbox, subagents, shell task supervision, synchronous SSH, goal tracking, or plans.
 
 ## Compatibility
 

package/extensions/plan/index.ts

@@ -0,0 +1 @@
+export { default } from "../../node_modules/pi-better-plan/src/index.ts";

package/extensions/ssh/index.ts

@@ -0,0 +1 @@
+export { default } from "../../node_modules/pi-better-ssh/src/index.ts";

package/lib/cli.mjs

@@ -12,7 +12,9 @@ export const componentPackages = [
   "pi-better-sandbox",
   "pi-better-subagents",
   "pi-better-background-tasks",
+  "pi-better-ssh",
   "pi-better-goal",
+  "pi-better-plan",
 ];
 
 const usage = `Usage: pi-better-harness <install|uninstall> [--local]

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

@@ -121,7 +121,12 @@ function state(): NavigatorState {
   return g[GLOBAL_KEY]!;
 }
 
-type PlanNavigationState = { visible: boolean; releaseWorkFocus?: () => void };
+type PlanNavigationState = {
+  visible: boolean;
+  progressLabel?: string;
+  releaseWorkFocus?: () => void;
+  refreshNavigationHint?: () => void;
+};
 
 function planNavigationState(): PlanNavigationState {
   const global = globalThis as typeof globalThis & { [PLAN_NAVIGATION_KEY]?: PlanNavigationState };
@@ -129,6 +134,10 @@ function planNavigationState(): PlanNavigationState {
   return global[PLAN_NAVIGATION_KEY]!;
 }
 
+function refreshPlanNavigationHint(): void {
+  refreshBackgroundWorkNavigator();
+}
+
 export function registerBackgroundWorkProvider(provider: BackgroundWorkProvider): () => void {
   const s = state();
   const previousUnsub = s.unsubscribers.get(provider.id);
@@ -170,7 +179,12 @@ export function isNavigatorUiAvailable(ctx: ExtensionContext | undefined): boole
 }
 
 export function navigatorFooterHint(count: number): string | null {
-  return count > 0 ? `← work · ${count}` : null;
+  const work = count > 0 ? `← work · ${count}` : null;
+  const navigation = planNavigationState();
+  const plan = navigation.visible
+    ? `→ plan${navigation.progressLabel ? ` · ${navigation.progressLabel}` : ""}`
+    : null;
+  return [work, plan].filter((hint): hint is string => hint !== null).join("    ") || null;
 }
 
 export function applyNavigatorFooter(ui: { setStatus(key: string, value: string | undefined): void }, count: number): string | null {
@@ -194,7 +208,10 @@ export function ensureBackgroundWorkNavigator(ctx: ExtensionContext, deps: HostD
   s.mainListRequestRender = undefined;
   s.mainListDeadlineScheduler?.dispose();
   s.mainListDeadlineScheduler = createRenderScheduler(() => refreshMainListWidget());
-  planNavigationState().releaseWorkFocus = unfocusMainList;
+  const planNavigation = planNavigationState();
+  planNavigation.releaseWorkFocus = unfocusMainList;
+  planNavigation.refreshNavigationHint = refreshPlanNavigationHint;
+  try { (ctx.ui as any).setStatus?.("pi-better-plan-nav", undefined); } catch { /* ignore */ }
   installNavigatorEditor(ctx.ui as any, deps);
   s.lastHint = undefined;
   refreshBackgroundWorkNavigator(ctx);
@@ -223,7 +240,11 @@ export function disposeBackgroundWorkNavigator(ctx?: ExtensionContext): void {
   s.mainListRequestRender = undefined;
   s.editorComponent = undefined;
   s.detailOverlayRows = undefined;
-  planNavigationState().releaseWorkFocus = undefined;
+  const planNavigation = planNavigationState();
+  planNavigation.releaseWorkFocus = undefined;
+  if (planNavigation.refreshNavigationHint === refreshPlanNavigationHint) {
+    planNavigation.refreshNavigationHint = undefined;
+  }
   s.mainListSelectedId = undefined;
   s.mainListFocused = false;
 }

package/node_modules/pi-better-plan/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1aboveio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,39 @@
+# pi-better-plan
+
+`pi-better-plan` keeps a structured execution plan visible while Pi works.
+
+## What It Does
+
+- 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.
+- Uses `→` from an empty editor to focus the plan; normal cursor movement is preserved when the editor contains text.
+- Persists plan state and display preferences on the active Pi session branch.
+- 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.
+
+## Install
+
+```sh
+pi install npm:pi-better-plan
+```
+
+## Commands
+
+```text
+/plan
+/plan clear
+/plan hide
+/plan show
+/plan pin auto
+/plan pin on
+/plan pin off
+```
+
+`pin auto` and `pin on` currently use the compact widget until Pi exposes a reserved right-rail extension interface. A floating overlay is intentionally not used as a substitute because it would cover transcript content.
+
+## Development
+
+```sh
+npm run verify
+```

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

@@ -0,0 +1,73 @@
+{
+  "name": "pi-better-plan",
+  "version": "0.1.2",
+  "description": "Structured execution plans with persistent progress for Pi.",
+  "license": "MIT",
+  "type": "module",
+  "main": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "plan",
+    "progress"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1aboveio/pi-better-harness.git",
+    "directory": "packages/pi-better-plan"
+  },
+  "bugs": {
+    "url": "https://github.com/1aboveio/pi-better-harness/issues"
+  },
+  "homepage": "https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-plan#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --import tsx --test test/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "verify": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.82.0",
+    "@earendil-works/pi-coding-agent": "^0.82.0",
+    "@earendil-works/pi-tui": "^0.82.0",
+    "@types/node": "^25.0.0",
+    "tsx": "^4.22.3",
+    "typebox": "^1.1.39",
+    "typescript": "^6.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

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

@@ -0,0 +1,379 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { CustomEditor, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+import {
+  planClearEntry,
+  planDisplayEntry,
+  planProgress,
+  planSetEntry,
+  reconstructPlanState,
+  replacePlan,
+} from "./plan-state.js";
+import { createFullPlanComponent, renderCompactPlan } from "./plan-render.js";
+import {
+  EXTENSION_NAME,
+  type PlanDisplayMode,
+  type PlanProgress,
+  type PlanSnapshot,
+  type PlanStepInput,
+} from "./types.js";
+
+interface GetPlanDetails {
+  hasPlan: boolean;
+  plan: PlanSnapshot | null;
+  progress: PlanProgress | null;
+}
+
+const PlanStepSchema = Type.Object({
+  step: Type.String({ description: "A concise, verifiable execution step." }),
+  status: StringEnum(["pending", "in_progress", "completed", "blocked"] as const),
+});
+
+const UpdatePlanSchema = Type.Object({
+  explanation: Type.Optional(Type.String({ description: "Why the plan or its status changed." })),
+  plan: Type.Array(PlanStepSchema, { minItems: 1, maxItems: 50 }),
+});
+
+const PLAN_NAV_STATUS_KEY = "pi-better-plan-nav";
+const PLAN_EDITOR_FACTORY_MARK = "__piBetterPlanFactory";
+const PLAN_EDITOR_FACTORY_REFRESH = "__piBetterPlanRefresh";
+const PLAN_NAVIGATION_KEY = Symbol.for("pi-better-harness.plan-navigation.state");
+
+interface SharedPlanNavigationState {
+  visible: boolean;
+  progressLabel?: string;
+  releaseWorkFocus?: () => void;
+  refreshNavigationHint?: () => void;
+}
+
+function sharedPlanNavigationState(): SharedPlanNavigationState {
+  const global = globalThis as typeof globalThis & { [PLAN_NAVIGATION_KEY]?: SharedPlanNavigationState };
+  if (!global[PLAN_NAVIGATION_KEY]) global[PLAN_NAVIGATION_KEY] = { visible: false };
+  return global[PLAN_NAVIGATION_KEY]!;
+}
+
+export default function planExtension(pi: ExtensionAPI): void {
+  let currentPlan: PlanSnapshot | null = null;
+  let displayMode: PlanDisplayMode = "auto";
+  let selectedIndex = 0;
+  let focused = false;
+  let refreshWidget: ((force?: boolean) => void) | undefined;
+  let currentCtx: ExtensionContext | undefined;
+
+  const refresh = (force = false): void => refreshWidget?.(force);
+
+  const updateNavigationHint = (ctx = currentCtx): void => {
+    if (!ctx?.hasUI) return;
+    const progress = currentPlan ? planProgress(currentPlan) : null;
+    const visible = currentPlan !== null && displayMode !== "hidden";
+    const navigation = sharedPlanNavigationState();
+    navigation.visible = visible;
+    const suffix = progress?.blocked ? "blocked" : progress ? `${progress.completed}/${progress.total}` : "";
+    if (suffix) navigation.progressLabel = suffix;
+    else delete navigation.progressLabel;
+    if (navigation.refreshNavigationHint) {
+      ctx.ui.setStatus(PLAN_NAV_STATUS_KEY, undefined);
+      navigation.refreshNavigationHint();
+    } else {
+      ctx.ui.setStatus(PLAN_NAV_STATUS_KEY, visible ? `→ plan · ${suffix}` : undefined);
+    }
+  };
+
+  const restore = (ctx: ExtensionContext): void => {
+    const state = reconstructPlanState(ctx.sessionManager.getBranch());
+    currentPlan = state.plan;
+    displayMode = state.displayMode;
+    selectedIndex = preferredIndex(currentPlan);
+    focused = false;
+    updateNavigationHint(ctx);
+    refresh(true);
+  };
+
+  const persistPlan = (plan: PlanSnapshot): void => {
+    currentPlan = plan;
+    selectedIndex = preferredIndex(plan);
+    focused = false;
+    pi.appendEntry(EXTENSION_NAME, planSetEntry(plan));
+    updateNavigationHint();
+    refresh(true);
+  };
+
+  const setDisplayMode = (mode: PlanDisplayMode): void => {
+    displayMode = mode;
+    pi.appendEntry(EXTENSION_NAME, planDisplayEntry(mode));
+    updateNavigationHint();
+    refresh(true);
+  };
+
+  const installWidget = (ctx: ExtensionContext): void => {
+    if (!ctx.hasUI) return;
+    ctx.ui.setWidget(
+      EXTENSION_NAME,
+      (tui, theme) => {
+        const localRefresh = (force = false): void => tui.requestRender(force);
+        refreshWidget = localRefresh;
+        return {
+          render(width: number): string[] {
+            if (!currentPlan || displayMode === "hidden") return [];
+            return renderCompactPlan(currentPlan, width, theme as never, { focused, selectedIndex });
+          },
+          invalidate() {},
+          dispose() {
+            if (refreshWidget === localRefresh) refreshWidget = undefined;
+          },
+        };
+      },
+      { placement: "aboveEditor" },
+    );
+  };
+
+  const showFullPlan = async (ctx: ExtensionContext): Promise<void> => {
+    if (!currentPlan) {
+      if (ctx.hasUI) ctx.ui.notify("No plan is set.", "warning");
+      return;
+    }
+    if (ctx.mode !== "tui") {
+      ctx.ui.notify(formatPlan(currentPlan), "info");
+      return;
+    }
+    const snapshot = currentPlan;
+    focused = false;
+    refresh();
+    await ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
+      const component = createFullPlanComponent(snapshot, theme as never, () => done());
+      return {
+        render: (width) => component.render(width),
+        handleInput(data) {
+          component.handleInput?.(data);
+          tui.requestRender();
+        },
+        invalidate: () => component.invalidate(),
+      };
+    });
+  };
+
+  const handlePlanNavigation = (data: string, ctx: ExtensionContext): boolean => {
+    if (!currentPlan || displayMode === "hidden") return false;
+    if (!focused) {
+      if (!matchesKey(data, Key.right)) return false;
+      sharedPlanNavigationState().releaseWorkFocus?.();
+      focused = true;
+      selectedIndex = preferredIndex(currentPlan);
+      refresh();
+      return true;
+    }
+    if (matchesKey(data, Key.up)) {
+      selectedIndex = Math.max(0, selectedIndex - 1);
+      refresh();
+      return true;
+    }
+    if (matchesKey(data, Key.down)) {
+      selectedIndex = Math.min(currentPlan.steps.length - 1, selectedIndex + 1);
+      refresh();
+      return true;
+    }
+    if (matchesKey(data, Key.enter) || matchesKey(data, Key.right)) {
+      void showFullPlan(ctx);
+      return true;
+    }
+    if (matchesKey(data, Key.left) || matchesKey(data, Key.escape)) {
+      focused = false;
+      refresh();
+      return true;
+    }
+    focused = false;
+    refresh();
+    return false;
+  };
+
+  const installEditorNavigation = (ctx: ExtensionContext): void => {
+    if (ctx.mode !== "tui") return;
+    const ui = ctx.ui as typeof ctx.ui & {
+      getEditorComponent?(): ((tui: unknown, theme: unknown, keybindings: unknown) => unknown) | undefined;
+      setEditorComponent(factory: (tui: unknown, theme: unknown, keybindings: unknown) => unknown): void;
+    };
+    const previous = ui.getEditorComponent?.() as
+      | (((tui: unknown, theme: unknown, keybindings: unknown) => unknown) & Record<string, unknown>)
+      | undefined;
+    const handlers = { handle: (data: string) => handlePlanNavigation(data, ctx) };
+    if (previous?.[PLAN_EDITOR_FACTORY_MARK] === true) {
+      const replaceHandlers = previous[PLAN_EDITOR_FACTORY_REFRESH];
+      if (typeof replaceHandlers === "function") replaceHandlers(handlers);
+      return;
+    }
+    let currentHandlers = handlers;
+    const factory = ((tui: unknown, theme: unknown, keybindings: unknown) => {
+      const inner = (previous
+        ? previous(tui, theme, keybindings)
+        : new CustomEditor(tui as never, theme as never, keybindings as never)) as {
+        getText?(): string;
+        handleInput(data: string): void;
+      };
+      return new Proxy(inner, {
+        get(target, property) {
+          if (property === "handleInput") {
+            return (data: string) => {
+              if (target.getText?.() === "" && currentHandlers.handle(data)) return;
+              target.handleInput(data);
+            };
+          }
+          const value = Reflect.get(target, property);
+          return typeof value === "function" ? value.bind(target) : value;
+        },
+      });
+    }) as ((tui: unknown, theme: unknown, keybindings: unknown) => unknown) & Record<string, unknown>;
+    factory[PLAN_EDITOR_FACTORY_MARK] = true;
+    factory[PLAN_EDITOR_FACTORY_REFRESH] = (next: typeof handlers) => { currentHandlers = next; };
+    ui.setEditorComponent(factory);
+  };
+
+  pi.registerTool({
+    name: "update_plan",
+    label: "Update Plan",
+    description: "Create or atomically replace the current structured execution plan and its step statuses.",
+    promptSnippet: "Create and update a persistent structured execution plan",
+    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.",
+    ],
+    parameters: UpdatePlanSchema,
+    async execute(_toolCallId, params) {
+      const input = params as { explanation?: string; plan: PlanStepInput[] };
+      const plan = replacePlan(currentPlan, input.plan, input.explanation);
+      persistPlan(plan);
+      const progress = planProgress(plan);
+      return {
+        content: [{ type: "text", text: formatProgress(plan) }],
+        details: { ok: true, plan, progress },
+      };
+    },
+    renderCall(args, theme) {
+      return new Text(
+        theme.fg("toolTitle", theme.bold("update_plan ")) + theme.fg("muted", `${args.plan.length} steps`),
+        0,
+        0,
+      );
+    },
+    renderResult(result, _options, theme) {
+      const text = result.content[0];
+      return new Text(theme.fg("success", "✓ ") + theme.fg("muted", text?.type === "text" ? text.text : "Plan updated"), 0, 0);
+    },
+  });
+
+  pi.registerTool({
+    name: "get_plan",
+    label: "Get Plan",
+    description: "Inspect the current structured execution plan and derived checklist progress.",
+    promptSnippet: "Inspect the current structured execution plan and progress",
+    parameters: Type.Object({}),
+    async execute() {
+      if (!currentPlan) {
+        return {
+          content: [{ type: "text", text: "No plan is set." }],
+          details: { hasPlan: false, plan: null, progress: null } as GetPlanDetails,
+        };
+      }
+      const progress = planProgress(currentPlan);
+      return {
+        content: [{ type: "text", text: formatPlan(currentPlan) }],
+        details: { hasPlan: true, plan: currentPlan, progress } as GetPlanDetails,
+      };
+    },
+  });
+
+  pi.registerCommand("plan", {
+    description: "Inspect, show, hide, clear, or configure the current plan",
+    handler: async (args, ctx) => {
+      const input = args.trim().toLowerCase();
+      if (!input) return showFullPlan(ctx);
+      if (input === "clear") {
+        currentPlan = null;
+        focused = false;
+        pi.appendEntry(EXTENSION_NAME, planClearEntry());
+        updateNavigationHint(ctx);
+        refresh(true);
+        ctx.ui.notify("Plan cleared.", "info");
+        return;
+      }
+      if (input === "hide") {
+        setDisplayMode("hidden");
+        return;
+      }
+      if (input === "show") {
+        setDisplayMode("auto");
+        return;
+      }
+      const pinMode = input.match(/^pin\s+(auto|on|off)$/)?.[1] as PlanDisplayMode | undefined;
+      if (pinMode) {
+        setDisplayMode(pinMode);
+        ctx.ui.notify(`Plan pin mode: ${pinMode}.`, "info");
+        return;
+      }
+      ctx.ui.notify("Usage: /plan [clear|hide|show|pin auto|pin on|pin off]", "warning");
+    },
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    currentCtx = ctx;
+    installWidget(ctx);
+    installEditorNavigation(ctx);
+    restore(ctx);
+  });
+  pi.on("session_tree", async (_event, ctx) => {
+    currentCtx = ctx;
+    restore(ctx);
+  });
+  pi.on("before_agent_start", async (event) => {
+    if (!currentPlan) return;
+    return {
+      systemPrompt: `${event.systemPrompt}\n\n${planPrompt(currentPlan)}`,
+    };
+  });
+  pi.on("session_shutdown", async (_event, ctx) => {
+    refreshWidget = undefined;
+    currentCtx = undefined;
+    const navigation = sharedPlanNavigationState();
+    navigation.visible = false;
+    delete navigation.progressLabel;
+    navigation.refreshNavigationHint?.();
+    try {
+      ctx.ui.setStatus(PLAN_NAV_STATUS_KEY, undefined);
+      ctx.ui.setWidget(EXTENSION_NAME, undefined);
+    } catch { /* best-effort cleanup */ }
+  });
+}
+
+function preferredIndex(plan: PlanSnapshot | null): number {
+  if (!plan) return 0;
+  const progress = planProgress(plan);
+  if (progress.activeIndex !== null) return progress.activeIndex;
+  const next = plan.steps.findIndex((item) => item.status !== "completed");
+  return next >= 0 ? next : Math.max(0, plan.steps.length - 1);
+}
+
+function formatProgress(plan: PlanSnapshot): string {
+  const progress = planProgress(plan);
+  const current = progress.activeIndex === null ? null : plan.steps[progress.activeIndex];
+  const status = [`Plan updated: ${progress.completed}/${progress.total} steps completed`];
+  if (progress.blocked > 0) status.push(`${progress.blocked} blocked`);
+  if (current) status.push(`Current step: ${current.step}`);
+  return status.join(". ") + ".";
+}
+
+function formatPlan(plan: PlanSnapshot): string {
+  const progress = planProgress(plan);
+  return [
+    `Plan: ${progress.completed}/${progress.total} steps completed${progress.blocked ? `, ${progress.blocked} blocked` : ""}`,
+    ...plan.steps.map((item, index) => `${index + 1}. [${item.status}] ${item.step}`),
+  ].join("\n");
+}
+
+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.",
+  ].join("\n");
+}