pi-better-harness 0.3.13 → 0.3.14

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

@@ -23,7 +23,9 @@ Independent foreground and delegated milestones may both be `in_progress`. Use s
 
 For a DAG, assign stable ids to prerequisite steps and list those ids in dependent steps' `dependsOn`. Dependencies must exist in the same plan; cycles and starting or completing a step before its prerequisites are complete are rejected. `get_plan` reports pending steps whose prerequisites are complete as ready. Plans without edges keep their existing behavior.
 
-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 competing updates until workflow ownership is released. Rush-style workflows can use their own dependency graph without copying it into this plan.
+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 competing updates until workflow ownership is released. `/plan` never opens a stale generic checklist during workflow ownership.
+
+For `rush-issues`, call `sync_workflow_plan` with the absolute `.resolve-issues/rush/<run-id>/task-plan.json` path and its persisted `planRevision` after each checkpoint. This binds the active run to the session and displays its fleet stages and actual units in the widget, `/plan`, and `get_plan`. The view reads the file without writing to it; revision mismatches are rejected. The run binding survives Pi session resume, and ownership release restores the prior generic checklist. Other workflow-owned skills retain their own planning and have no generic plan view.
 
 ## Install
 

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-plan",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Structured execution plans with persistent progress for Pi.",
   "license": "MIT",
   "type": "module",

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

@@ -13,6 +13,10 @@ import {
   replacePlan,
 } from "./plan-state.js";
 import { createFullPlanComponent, renderCompactPlan } from "./plan-render.js";
+import {
+  createRushPlanComponent, readRushPlan, renderRushPlan, workflowBinding,
+  WORKFLOW_PLAN_ENTRY, type RushPlan, type WorkflowPlanBinding,
+} from "./workflow-plan.js";
 import {
   EXTENSION_NAME,
   type PlanDisplayMode,
@@ -59,16 +63,37 @@ export default function planExtension(pi: ExtensionAPI): void {
   let currentPlan: PlanSnapshot | null = null;
   let displayMode: PlanDisplayMode = "auto";
   let displayedWorkflowOwner: string | null = null;
+  let rushBinding: WorkflowPlanBinding | null = null;
+  let rushPlan: RushPlan | null = null;
+  let rushError: string | null = null;
   let refreshWidget: ((force?: boolean) => void) | undefined;
   let completedPlanClearTimer: ReturnType<typeof setTimeout> | undefined;
   const unsubscribeWorkflow = pi.events.on("pi-better-workflow:changed", (owner) => {
     displayedWorkflowOwner = owner && typeof owner === "object" && "name" in owner && typeof owner.name === "string"
       ? owner.name : null;
+    rushBinding = null;
+    rushPlan = null;
+    rushError = null;
     refreshWidget?.(true);
   });
 
   const refresh = (force = false): void => refreshWidget?.(force);
 
+  const loadRushPlan = (ctx: ExtensionContext): RushPlan | null => {
+    if (!rushBinding || workflowPlanOwner(ctx) !== "rush-issues") return null;
+    try {
+      const plan = readRushPlan(rushBinding.path, ctx.cwd);
+      if (plan.runId !== rushBinding.runId) throw new Error("Rush run identity changed.");
+      rushPlan = plan;
+      rushError = null;
+    } catch (error) {
+      rushPlan = null;
+      rushError = error instanceof Error ? error.message : String(error);
+    }
+    refresh(true);
+    return rushPlan;
+  };
+
   const cancelCompletedPlanClear = (): void => {
     if (completedPlanClearTimer) clearTimeout(completedPlanClearTimer);
     completedPlanClearTimer = undefined;
@@ -102,6 +127,10 @@ 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;
+    rushPlan = null;
+    rushError = null;
+    if (rushBinding) loadRushPlan(ctx);
     displayMode = state.displayMode;
     if (ctx.hasUI) ctx.ui.setStatus(LEGACY_PLAN_NAV_STATUS_KEY, undefined);
     refresh(true);
@@ -130,7 +159,14 @@ export default function planExtension(pi: ExtensionAPI): void {
         refreshWidget = localRefresh;
         return {
           render(width: number): string[] {
-            if (!currentPlan || displayMode === "hidden" || displayedWorkflowOwner) return [];
+            if (displayMode === "hidden") return [];
+            if (displayedWorkflowOwner) {
+              if (displayedWorkflowOwner !== "rush-issues") return [];
+              return rushPlan ? renderRushPlan(rushPlan, width) : [
+                `rush-issues  ${rushError ? `plan unavailable: ${rushError}` : "waiting for task plan"}`,
+              ].map((line) => line.slice(0, width));
+            }
+            if (!currentPlan) return [];
             return renderCompactPlan(currentPlan, width, theme as never);
           },
           invalidate() {},
@@ -144,6 +180,26 @@ 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;
+      if (!plan) {
+        ctx.ui.notify(owner === "rush-issues" ? `Rush plan unavailable: ${rushError ?? "not bound"}` : `${owner} owns the task plan.`, "warning");
+        return;
+      }
+      if (ctx.mode !== "tui") {
+        ctx.ui.notify(renderRushPlan(plan, 160, true).join("\n"), "info");
+        return;
+      }
+      await ctx.ui.custom<void>((tui, _theme, _keys, done) => {
+        const component = createRushPlanComponent(plan, () => done());
+        return { render: (width) => component.render(width), handleInput(data) {
+          component.handleInput?.(data);
+          tui.requestRender();
+        }, invalidate: () => component.invalidate() };
+      });
+      return;
+    }
     if (!currentPlan) {
       if (ctx.hasUI) ctx.ui.notify("No plan is set.", "warning");
       return;
@@ -167,6 +223,35 @@ export default function planExtension(pi: ExtensionAPI): void {
   };
 
 
+  pi.registerTool({
+    name: "sync_workflow_plan",
+    label: "Sync Workflow Plan",
+    description: "Display the persisted rush-issues task plan at its exact checkpoint revision. Read-only; Rush retains plan ownership.",
+    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 plan = readRushPlan(params.path, ctx.cwd);
+      if (plan.planRevision !== params.revision) {
+        rushPlan = null;
+        rushError = `revision mismatch: expected ${params.revision}, found ${plan.planRevision}`;
+        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) {
+        pi.appendEntry(WORKFLOW_PLAN_ENTRY, { version: 1, kind: "set", ...binding });
+      }
+      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 } };
+    },
+  });
+
   pi.registerTool({
     name: "update_plan",
     label: "Update Plan",
@@ -214,10 +299,15 @@ export default function planExtension(pi: ExtensionAPI): void {
     parameters: Type.Object({}),
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
       const owner = workflowPlanOwner(ctx);
-      if (owner) return {
-        content: [{ type: "text", text: `${owner} owns the task plan; consult its persisted workflow state.` }],
-        details: { hasPlan: false, plan: null, progress: null, workflowOwner: owner },
-      };
+      if (owner) {
+        const workflowPlan = owner === "rush-issues" ? loadRushPlan(ctx) : null;
+        return {
+          content: [{ type: "text", text: workflowPlan
+            ? renderRushPlan(workflowPlan, 160, true).join("\n")
+            : `${owner} owns the task plan; ${rushError ?? "consult its persisted workflow state"}.` }],
+          details: { hasPlan: !!workflowPlan, plan: workflowPlan, progress: null, workflowOwner: owner },
+        };
+      }
       if (!currentPlan) {
         return {
           content: [{ type: "text", text: "No plan is set." }],
@@ -238,6 +328,10 @@ export default function planExtension(pi: ExtensionAPI): void {
       const input = args.trim().toLowerCase();
       if (!input) return showFullPlan(ctx);
       if (input === "clear") {
+        if (workflowPlanOwner(ctx)) {
+          ctx.ui.notify("The workflow owns its plan; /plan clear cannot change it.", "warning");
+          return;
+        }
         clearPlan();
         ctx.ui.notify("Plan cleared.", "info");
         return;

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

@@ -0,0 +1,123 @@
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import type { Component } from "@earendil-works/pi-tui";
+import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+
+export const WORKFLOW_PLAN_ENTRY = "pi-better-workflow-plan";
+
+interface RushUnit {
+  id: string;
+  title: string;
+  stage: string;
+  status: string;
+  dependsOn: string[];
+  worker?: string | number | undefined;
+  note?: string | undefined;
+}
+
+export interface RushPlan {
+  runId: string;
+  planRevision: number;
+  issues: RushUnit[];
+  fleet: Record<string, { status: string }>;
+  warehouseCanaryRequired: boolean;
+  spec?: { title?: string } | undefined;
+}
+
+export interface WorkflowPlanBinding {
+  owner: "rush-issues";
+  path: string;
+  runId: string;
+}
+
+export function readRushPlan(path: string, cwd: string): RushPlan {
+  if (!isAbsolute(path) || basename(path) !== "task-plan.json") throw new Error("Expected an absolute Rush task-plan.json path.");
+  const root = realpathSync(resolve(cwd, ".resolve-issues", "rush"));
+  const file = realpathSync(path);
+  const dir = relative(root, dirname(file));
+  if (!dir || dir.startsWith(".." + sep) || dir === ".." || dir.includes(sep)) {
+    throw new Error("Rush plan must be inside this project's .resolve-issues/rush/<run-id> directory.");
+  }
+  const size = statSync(file).size;
+  if (size > 2_000_000) throw new Error("Rush plan exceeds the 2 MB display limit.");
+  const data: unknown = JSON.parse(readFileSync(file, "utf8"));
+  if (!isRecord(data) || data.runId !== dir || !Number.isSafeInteger(data.planRevision) ||
+      (data.planRevision as number) < 0 || !Array.isArray(data.issues) || !isRecord(data.fleet)) {
+    throw new Error("Invalid Rush plan identity or revision.");
+  }
+  const issues = data.issues.map((unit: unknown) => {
+    if (!isRecord(unit) || typeof unit.id !== "string" || typeof unit.title !== "string" ||
+        typeof unit.stage !== "string" || typeof unit.status !== "string") {
+      throw new Error("Invalid Rush plan unit.");
+    }
+    return {
+      id: unit.id, title: unit.title, stage: unit.stage, status: unit.status,
+      dependsOn: Array.isArray(unit.dependsOn) ? unit.dependsOn.filter((id): id is string => typeof id === "string") : [],
+      worker: typeof unit.worker === "string" || typeof unit.worker === "number" ? unit.worker : undefined,
+      note: typeof unit.note === "string" ? unit.note : undefined,
+    };
+  });
+  const fleet: RushPlan["fleet"] = {};
+  for (const [stage, value] of Object.entries(data.fleet)) {
+    if (!isRecord(value) || typeof value.status !== "string") throw new Error("Invalid Rush fleet stage.");
+    fleet[stage] = { status: value.status };
+  }
+  return {
+    runId: data.runId as string,
+    planRevision: data.planRevision as number,
+    issues,
+    fleet,
+    warehouseCanaryRequired: data.warehouseCanaryRequired === true,
+    spec: isRecord(data.spec) && typeof data.spec.title === "string" ? { title: data.spec.title } : undefined,
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export function workflowBinding(entries: Iterable<{ type: string; customType?: string; data?: unknown }>): WorkflowPlanBinding | null {
+  let binding: WorkflowPlanBinding | null = null;
+  for (const entry of entries) {
+    if (entry.type === "custom" && entry.customType === "pi-better-workflow") {
+      const data = entry.data;
+      if (isRecord(data) && data.version === 1 && (data.kind === "set" || data.kind === "clear")) binding = null;
+    }
+    if (entry.type !== "custom" || entry.customType !== WORKFLOW_PLAN_ENTRY) continue;
+    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" &&
+             typeof data.path === "string" && typeof data.runId === "string") {
+      binding = { owner: "rush-issues", path: data.path, runId: data.runId };
+    }
+  }
+  return binding;
+}
+
+export function renderRushPlan(plan: RushPlan, width: number, full = false): string[] {
+  const completed = plan.issues.filter((unit) => unit.status === "succeeded").length;
+  const lines = [`rush-issues  rev ${plan.planRevision}  ${completed}/${plan.issues.length} units${plan.spec?.title ? `  ${plan.spec.title}` : ""}`];
+  const fleet = ["explore", "combine", "canary", "review", "cicd"]
+    .map((stage) => `${stage}: ${stage === "canary" && !plan.warehouseCanaryRequired ? "n/a" : plan.fleet[stage]?.status ?? "pending"}`);
+  lines.push(`fleet  ${fleet.join("  ")}`);
+  for (const unit of plan.issues) {
+    const marker = unit.status === "succeeded" ? "✓" : unit.status === "blocked" ? "!" : unit.status === "pending" ? "○" : "●";
+    lines.push(`${marker} #${unit.id} ${unit.title}  [${unit.stage} · ${unit.status}${unit.worker !== undefined ? ` · worker ${unit.worker}` : ""}]`);
+    if (full) {
+      if (unit.dependsOn.length) lines.push(`    after: ${unit.dependsOn.map((id) => `#${id}`).join(", ")}`);
+      if (unit.note) lines.push(`    ${unit.note}`);
+    }
+  }
+  return lines.map((line) => truncateToWidth(line, Math.max(1, width)));
+}
+
+export function createRushPlanComponent(plan: RushPlan, onClose: () => void): Component {
+  return {
+    render: (width) => renderRushPlan(plan, width, true),
+    handleInput(data) {
+      if (matchesKey(data, "escape") || matchesKey(data, "left") || matchesKey(data, "ctrl+c")) onClose();
+    },
+    invalidate() {},
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-harness",
-  "version": "0.3.13",
+  "version": "0.3.14",
   "description": "Pi extension bundle for a write sandbox, subagents, background tasks, SSH, goals, and structured plans.",
   "license": "MIT",
   "type": "module",
@@ -52,7 +52,7 @@
   "dependencies": {
     "pi-better-background-tasks": "0.2.14",
     "pi-better-goal": "0.4.0",
-    "pi-better-plan": "0.2.1",
+    "pi-better-plan": "0.3.0",
     "pi-better-sandbox": "0.3.0",
     "pi-better-ssh": "0.1.1",
     "pi-better-subagents": "0.1.30",