pi-better-harness 0.3.8 → 0.3.10

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

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

@@ -918,7 +918,7 @@ function createOverlayComponent(
           width,
           deps.truncate,
           fg,
-          { minRows: detailRows, bottomFooter: false, logTailRows },
+          { minRows: detailRows, maxRows: detailRows, bottomFooter: false, logTailRows },
         );
       } else {
         transcriptDetail = null;
@@ -1003,21 +1003,33 @@ function buildTranscriptDetailLines(
   width: number,
   truncate: (s: string, width: number) => string,
   fg: (color: string, value: string) => string,
-  options: { minRows?: number; bottomFooter?: boolean; logTailRows?: number } = {},
+  options: { minRows?: number; maxRows?: number; bottomFooter?: boolean; logTailRows?: number } = {},
 ): string[] {
   const actions = [...(detail.footerActions ?? ["x close"]), "Esc close"].join(" · ");
   const tailRows = options.logTailRows ?? DEFAULT_LOG_TAIL_ROWS;
-  const shownTranscriptLines = transcriptLines.length ? transcriptLines.slice(-tailRows) : ["   (no transcript yet)"];
+  let shownTranscriptLines = transcriptLines.length ? transcriptLines.slice(-tailRows) : ["   (no transcript yet)"];
   const lines: string[] = [
     fg("accent", rule(detail.title, width)),
     dim(`   ← main · ${actions}`, fg),
     "",
     `   status   ${fg(toneColor(detail.statusTone, detail.status), detail.status)}`,
   ];
-  if (detail.subtitle) lines.push(`   summary  ${detail.subtitle}`);
-  for (const item of detail.metadata) lines.push(`   ${item.label.padEnd(8, " ").slice(0, 8)} ${item.value}`);
-  lines.push("", dim(section(`transcript · latest ${tailRows} rows`, width), fg));
-  if (detail.transcriptDiagnostic) lines.push(`   ${dim(detail.transcriptDiagnostic, fg)}`);
+  const optionalMetadata = [
+    ...(detail.subtitle ? [`   summary  ${detail.subtitle}`] : []),
+    ...detail.metadata.map((item) => `   ${item.label.padEnd(8, " ").slice(0, 8)} ${item.value}`),
+  ];
+  const transcriptHeader = ["", dim(section(`transcript · latest ${tailRows} rows`, width), fg)];
+  if (detail.transcriptDiagnostic) transcriptHeader.push(`   ${dim(detail.transcriptDiagnostic, fg)}`);
+  if (options.maxRows !== undefined) {
+    const fixedRows = lines.length + transcriptHeader.length + 1;
+    const transcriptBudget = Math.max(1, options.maxRows - fixedRows);
+    shownTranscriptLines = shownTranscriptLines.slice(-transcriptBudget);
+    const metadataBudget = Math.max(0, options.maxRows - fixedRows - shownTranscriptLines.length);
+    lines.push(...optionalMetadata.slice(0, metadataBudget));
+  } else {
+    lines.push(...optionalMetadata);
+  }
+  lines.push(...transcriptHeader);
   lines.push(...shownTranscriptLines);
   lines.push("");
   if (options.bottomFooter === false) return lines.map((line) => safeTruncate(line, width, truncate));

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

@@ -19,6 +19,19 @@ Use `pi-better-goal` when a Pi session should keep an explicit objective visible
 - A progress-aware follow-up loop that holds after repeated identical outcomes.
 - An observable-progress stall state for active goals.
 
+## Skill-Owned Workflows
+
+Skills that own execution and their own task plan can opt in through `SKILL.md` frontmatter:
+
+```yaml
+metadata:
+  pi-better-plan-workflow: coordinator
+```
+
+Invoke the skill with Pi's `/skill:name` command. The goal extension checks Pi's skill-command provenance, persists the owner on the session branch, and restores its instructions on resumed turns. It does not infer ownership from ordinary text or skill names. A goal such as `/goal /skill:name task` is rejected; invoke `/skill:name task` directly and use `/goal` only for a plain-language objective. Legacy slash-shaped goals pause on resume rather than running without the skill. `/workflow` shows the owner; call `release_workflow` after the workflow's completion audit (or use `/workflow clear` to release it manually). Completing an active goal also releases ownership.
+
+When `pi-better-plan` is installed, it defers its prompt, checklist, and `update_plan` tool to a skill-owned task plan. Skills without this metadata retain normal goal and plan behavior. The skill itself owns its planning format and worker policy; the harness does not enumerate skills or impose a shared workflow schema.
+
 ## Install
 
 ```sh

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-goal",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Pi extension for goal tracking with background-aware continuation.",
   "license": "MIT",
   "type": "module",
@@ -67,5 +67,8 @@
   },
   "engines": {
     "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "yaml": "^2.9.1"
   }
 }

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

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import { readFileSync } from "node:fs";
 import { Type } from "typebox";
 
 import {
@@ -33,6 +34,7 @@ import {
 } from "./goal-clock.js";
 import { createRenderScheduler } from "./shared-render-scheduler.js";
 import { collectSubagentActivity } from "./subagents.js";
+import { currentWorkflowOwner, skillCommandName, workflowEntry, workflowOwnerFromSkill, WORKFLOW_ENTRY_TYPE } from "./workflow.js";
 import {
   EVENT_ACTIVITY,
   EVENT_READY,
@@ -109,13 +111,15 @@ function wasTurnAborted(messages: readonly unknown[]): boolean {
   return false;
 }
 
-function continuationPrompt(goal: GoalSnapshot): string {
+function continuationPrompt(goal: GoalSnapshot, owner: ReturnType<typeof currentWorkflowOwner> = null): string {
   return [
     "Continue working toward the active thread goal.",
     "",
     `Goal: ${goal.objective}`,
     "",
-    "Keep working through clear low-risk next steps. Do not stop at a plan. Mark the goal complete only after an evidence-backed completion audit proves no required work remains.",
+    owner
+      ? `Continue the ${owner.name} workflow as its coordinator. Its own task plan is authoritative; do not implement product code in the parent. Mark the goal complete only after the workflow's completion audit.`
+      : "Keep working through clear low-risk next steps. Do not stop at a plan. Mark the goal complete only after an evidence-backed completion audit proves no required work remains.",
   ].join("\n");
 }
 
@@ -185,6 +189,20 @@ export default function (pi: ExtensionAPI): void {
   let lastAgentEvidence: ContinuationEvidence | null = null;
 
   const getGoal = (ctx: ExtensionContext): GoalSnapshot | null => currentGoalSnapshot(ctx);
+  const getWorkflow = (ctx: ExtensionContext) => currentWorkflowOwner(ctx.sessionManager.getBranch());
+  const workflowAvailable = (owner: NonNullable<ReturnType<typeof currentWorkflowOwner>>): boolean => {
+    const command = pi.getCommands?.().find((item) => item.name === `skill:${owner.name}` && item.source === "skill");
+    if (command?.sourceInfo.path !== owner.path) return false;
+    try {
+      return workflowOwnerFromSkill(owner.name, owner.path)?.planOwner === owner.planOwner;
+    } catch {
+      return false;
+    }
+  };
+  const recordWorkflow = (owner: ReturnType<typeof currentWorkflowOwner>): void => {
+    pi.appendEntry(WORKFLOW_ENTRY_TYPE, workflowEntry(owner));
+    pi.events.emit("pi-better-workflow:changed", owner);
+  };
 
   /** Only active goals receive autonomous pokes; paused, complete, and budget-limited goals never do. */
   const isPokeable = (goal: GoalSnapshot | null): goal is GoalSnapshot => goal?.status === "active";
@@ -241,6 +259,7 @@ export default function (pi: ExtensionAPI): void {
     const current = getGoal(ctx);
     const wasVisible = current !== null && isGoalClockVisible(current);
     pi.appendEntry(EXTENSION_NAME, goalClearEntry(current?.goalId ?? null, source));
+    if (getWorkflow(ctx)) recordWorkflow(null);
     continuationQueuedFor = null;
     backgroundDrainTracker = null;
     clearIdleContinuation();
@@ -267,7 +286,7 @@ export default function (pi: ExtensionAPI): void {
     pi.sendMessage(
       {
         customType: EXTENSION_NAME,
-        content: continuationPrompt(goal),
+        content: continuationPrompt(goal, currentCtx ? getWorkflow(currentCtx) : null),
         display: false,
         details: { kind: "continuation", goalId: goal.goalId },
       },
@@ -333,8 +352,8 @@ export default function (pi: ExtensionAPI): void {
     continuationQueuedFor = goal.goalId;
     const content = kind === "background-drained"
       ? "Background activity for the active goal is no longer running. Inspect any subagent callbacks or final results, then continue the completion audit before marking the goal complete.\n\n" +
-        continuationPrompt(goal)
-      : continuationPrompt(goal);
+        continuationPrompt(goal, getWorkflow(ctx))
+      : continuationPrompt(goal, getWorkflow(ctx));
     pi.sendMessage(
       {
         customType: EXTENSION_NAME,
@@ -354,6 +373,9 @@ export default function (pi: ExtensionAPI): void {
     ctx: ExtensionContext,
     source: "command",
   ): GoalSnapshot => {
+    if (skillCommandName(objective)) {
+      throw new Error("A skill command cannot be a goal objective. Invoke /skill:name directly so Pi loads the skill, then set a plain-language goal if needed.");
+    }
     const objectiveError = validateObjective(objective);
     if (objectiveError) {
       throw new Error(objectiveError);
@@ -566,6 +588,10 @@ export default function (pi: ExtensionAPI): void {
           notifyGoal(ctx, "Only paused goals can be resumed.", "warning");
           return;
         }
+        if (skillCommandName(current.objective)) {
+          notifyGoal(ctx, "Invoke the skill directly; this legacy slash-command goal cannot resume as plain text.", "error");
+          return;
+        }
         const goal = goalWithStatus(current, "active");
         setGoal(goal, ctx, "command");
         queueGoalContinuation(goal);
@@ -585,6 +611,7 @@ export default function (pi: ExtensionAPI): void {
           return;
         }
         setGoal(goalWithStatus(current, "complete"), ctx, "command");
+        if (getWorkflow(ctx)) recordWorkflow(null);
         notifyGoal(ctx, "Goal marked complete.");
         return;
       }
@@ -662,6 +689,7 @@ export default function (pi: ExtensionAPI): void {
       }
       const goal = goalWithStatus(current, "complete");
       setGoal(goal, ctx, "tool");
+      if (getWorkflow(ctx)) recordWorkflow(null);
       return {
         content: [{ type: "text", text: "Goal marked complete." }],
         details: { ok: true, goal },
@@ -678,6 +706,32 @@ export default function (pi: ExtensionAPI): void {
     },
   });
 
+  pi.registerCommand("workflow", {
+    description: "Inspect or clear the active skill-owned workflow",
+    handler: async (args, ctx) => {
+      if (args.trim() === "clear") {
+        recordWorkflow(null);
+        notifyGoal(ctx, "Workflow ownership cleared.");
+        return;
+      }
+      const owner = getWorkflow(ctx);
+      notifyGoal(ctx, owner ? `Workflow: ${owner.name} (${owner.path}); plan owned by workflow.` : "No workflow owns this session.");
+    },
+  });
+
+  pi.registerTool({
+    name: "release_workflow",
+    label: "Release Workflow",
+    description: "Release the active skill-owned workflow after its final handoff and completion audit.",
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const owner = getWorkflow(ctx);
+      if (!owner) return { content: [{ type: "text", text: "No workflow owns this session." }], details: { released: false } };
+      recordWorkflow(null);
+      return { content: [{ type: "text", text: `Released ${owner.name} workflow ownership.` }], details: { released: true, owner: owner.name } };
+    },
+  });
+
   pi.registerTool({
     name: "get_background_activity",
     label: "Get Background Activity",
@@ -697,6 +751,11 @@ export default function (pi: ExtensionAPI): void {
   pi.on("session_start", async (_event, ctx) => {
     currentCtx = ctx;
     foregroundRunning = !ctx.isIdle();
+    const restoredGoal = getGoal(ctx);
+    if (restoredGoal?.status === "active" && skillCommandName(restoredGoal.objective)) {
+      setGoal(goalWithStatus(restoredGoal, "paused"), ctx, "runtime");
+      notifyGoal(ctx, "Goal paused: invoke its skill directly before resuming.", "error");
+    }
     pi.events.emit(EVENT_READY, { version: EXTENSION_VERSION });
     installGoalWidget(ctx);
     latestSnapshot = await publishSnapshot(ctx);
@@ -707,6 +766,19 @@ export default function (pi: ExtensionAPI): void {
     if (event.source === "extension") {
       return;
     }
+    const skillName = skillCommandName(event.text ?? "");
+    if (skillName) {
+      const command = pi.getCommands?.().find((item) => item.name === `skill:${skillName}` && item.source === "skill");
+      if (command) {
+        try {
+          const owner = workflowOwnerFromSkill(skillName, command.sourceInfo.path);
+          if (owner) recordWorkflow(owner);
+        } catch (error) {
+          notifyGoal(ctx, error instanceof Error ? error.message : String(error), "error");
+          return { action: "handled" as const };
+        }
+      }
+    }
     const goal = getGoal(ctx);
     if (goal?.status === "active") {
       resetContinuationState(goal);
@@ -716,11 +788,32 @@ export default function (pi: ExtensionAPI): void {
   pi.on("before_agent_start", async (event, ctx) => {
     currentCtx = ctx;
     const goal = currentGoalSnapshot(ctx);
+    const owner = getWorkflow(ctx);
     const snapshot = await publishSnapshot(ctx);
-    if (!isPokeable(goal)) {
+    if (!isPokeable(goal) && !owner) {
       return;
     }
 
+    if (owner) {
+      if (!workflowAvailable(owner)) {
+        if (isPokeable(goal)) setGoal(goalWithStatus(goal, "paused"), ctx, "runtime");
+        recordWorkflow(null);
+        return { systemPrompt: `${event.systemPrompt}\n\nWorkflow ${owner.name} is no longer a registered, valid skill. Stop work and ask the user to reinvoke the skill.` };
+      }
+      let instructions: string;
+      try {
+        instructions = readFileSync(owner.path, "utf8");
+      } catch {
+        if (isPokeable(goal)) setGoal(goalWithStatus(goal, "paused"), ctx, "runtime");
+        return { systemPrompt: `${event.systemPrompt}\n\nWorkflow ${owner.name} is unavailable. Stop work and ask the user to restore or reinvoke the skill.` };
+      }
+      return {
+        systemPrompt: `${event.systemPrompt}\n\nActive workflow: ${owner.name} (${owner.path}). Its task plan owns planning and the parent is a coordinator, not a product-code implementer. Follow the workflow instructions below, including on resumed turns:\n\n${instructions}` +
+          (isPokeable(goal) ? `\n\nActive objective: ${goal.objective}. Complete it only after the workflow completion audit.` : ""),
+      };
+    }
+
+    if (!isPokeable(goal)) return;
     const backgroundInstruction = snapshot.backgroundRunning
       ? ` 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.`
       : "";

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

@@ -0,0 +1,63 @@
+import { readFileSync } from "node:fs";
+import { parse } from "yaml";
+
+export const WORKFLOW_ENTRY_TYPE = "pi-better-workflow";
+
+export interface WorkflowOwner {
+  name: string;
+  path: string;
+  role: "coordinator";
+  planOwner: "workflow";
+}
+
+interface SessionEntryLike {
+  type: string;
+  customType?: string;
+  data?: unknown;
+}
+
+export function workflowOwnerFromSkill(name: string, path: string): WorkflowOwner | null {
+  const source = readFileSync(path, "utf8");
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(source);
+  if (!match) return null;
+  const frontmatter: unknown = parse(match[1]!);
+  if (!frontmatter || typeof frontmatter !== "object") return null;
+  const metadata = (frontmatter as { metadata?: unknown }).metadata;
+  if (!metadata || typeof metadata !== "object") return null;
+  const fields = metadata as Record<string, unknown>;
+  if (fields["pi-better-plan-workflow"] === undefined) {
+    if (fields["pi-better-workflow-role"] !== undefined || fields["pi-better-plan-owner"] !== undefined) {
+      throw new Error(`Outdated workflow metadata in ${path}. Use pi-better-plan-workflow: coordinator.`);
+    }
+    return null;
+  }
+  if (fields["pi-better-plan-workflow"] !== "coordinator") {
+    throw new Error(`Invalid workflow metadata in ${path}. Expected pi-better-plan-workflow: coordinator.`);
+  }
+  return { name, path, role: "coordinator", planOwner: "workflow" };
+}
+
+export function workflowEntry(owner: WorkflowOwner | null) {
+  return owner === null
+    ? { version: 1, kind: "clear" as const }
+    : { version: 1, kind: "set" as const, owner };
+}
+
+export function currentWorkflowOwner(entries: Iterable<SessionEntryLike>): WorkflowOwner | null {
+  let owner: WorkflowOwner | null = null;
+  for (const entry of entries) {
+    if (entry.type !== "custom" || entry.customType !== WORKFLOW_ENTRY_TYPE) continue;
+    const data = entry.data as { version?: unknown; kind?: unknown; owner?: Partial<WorkflowOwner> } | null;
+    if (data?.version !== 1) continue;
+    if (data.kind === "clear") owner = null;
+    else if (data.kind === "set" && typeof data.owner?.name === "string" &&
+      typeof data.owner.path === "string" && data.owner.role === "coordinator" && data.owner.planOwner === "workflow") {
+      owner = data.owner as WorkflowOwner;
+    }
+  }
+  return owner;
+}
+
+export function skillCommandName(text: string): string | null {
+  return /^\/skill:([a-z0-9]+(?:-[a-z0-9]+)*)(?:\s|$)/.exec(text.trim())?.[1] ?? null;
+}

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

@@ -5,6 +5,7 @@
 ## What It Does
 
 - Gives models `update_plan` and `get_plan` tools for atomic, explicit progress updates.
+- Supports dependency edges (`id` and `dependsOn`) so independent ready steps can run concurrently.
 - 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.
@@ -16,7 +17,13 @@ Plan progress is checklist progress, not an estimate of effort. The extension ne
 
 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.
+Before the first implementation milestone, check for an independent task that can run alongside foreground work. Launch a bounded subagent task when available; otherwise state the specific dependency or shared-worktree constraint that rules delegation out. The plan records milestones, not worker scheduling.
+
+Independent foreground and delegated milestones may both be `in_progress`. Use steps for distinct deliverables, not individual worker processes; worker tools and the background-work navigator own 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.
+
+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 `pi-better-plan-workflow: 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.
 
 ## Install
 

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

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

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

@@ -28,8 +28,10 @@ interface GetPlanDetails {
 }
 
 const PlanStepSchema = Type.Object({
+  id: Type.Optional(Type.String({ description: "Stable step id used by dependsOn (letters, digits, underscore, hyphen; max 64 characters)." })),
   step: Type.String({ description: "A concise, verifiable execution step." }),
   status: StringEnum(["pending", "in_progress", "completed", "blocked"] as const),
+  dependsOn: Type.Optional(Type.Array(Type.String(), { description: "Ids of prerequisite steps in this plan. All must be completed before this step starts." })),
 });
 
 const UpdatePlanSchema = Type.Object({
@@ -39,11 +41,31 @@ const UpdatePlanSchema = Type.Object({
 
 const LEGACY_PLAN_NAV_STATUS_KEY = "pi-better-plan-nav";
 
+function workflowPlanOwner(ctx: ExtensionContext): string | null {
+  let owner: string | null = null;
+  for (const entry of ctx.sessionManager.getBranch()) {
+    if (entry.type !== "custom" || entry.customType !== "pi-better-workflow") continue;
+    const data = entry.data as { version?: unknown; kind?: unknown; owner?: { name?: unknown; planOwner?: unknown } } | null;
+    if (data?.version !== 1) continue;
+    if (data.kind === "clear") owner = null;
+    else if (data.kind === "set" && data.owner?.planOwner === "workflow" && typeof data.owner.name === "string") {
+      owner = data.owner.name;
+    }
+  }
+  return owner;
+}
+
 export default function planExtension(pi: ExtensionAPI): void {
   let currentPlan: PlanSnapshot | null = null;
   let displayMode: PlanDisplayMode = "auto";
+  let displayedWorkflowOwner: 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;
+    refreshWidget?.(true);
+  });
 
   const refresh = (force = false): void => refreshWidget?.(force);
 
@@ -79,6 +101,7 @@ export default function planExtension(pi: ExtensionAPI): void {
     cancelCompletedPlanClear();
     const state = reconstructPlanState(ctx.sessionManager.getBranch());
     currentPlan = state.plan;
+    displayedWorkflowOwner = workflowPlanOwner(ctx);
     displayMode = state.displayMode;
     if (ctx.hasUI) ctx.ui.setStatus(LEGACY_PLAN_NAV_STATUS_KEY, undefined);
     refresh(true);
@@ -107,7 +130,7 @@ export default function planExtension(pi: ExtensionAPI): void {
         refreshWidget = localRefresh;
         return {
           render(width: number): string[] {
-            if (!currentPlan || displayMode === "hidden") return [];
+            if (!currentPlan || displayMode === "hidden" || displayedWorkflowOwner) return [];
             return renderCompactPlan(currentPlan, width, theme as never);
           },
           invalidate() {},
@@ -150,13 +173,17 @@ export default function planExtension(pi: ExtensionAPI): void {
     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.",
-      "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.",
+      "Use update_plan for work with three or more meaningful steps unless a skill owns planning; update it immediately when a step completes, becomes blocked, or scope changes.",
+      "For generic plans only, mark independent foreground and delegated milestones in_progress concurrently when work is actually underway. Do not mark a delegated step completed until its result or failure has been inspected and integrated.",
+      "For generic plans with prerequisites, give steps stable ids and dependsOn edges. Start only ready steps whose prerequisites are completed; independent ready steps may run in parallel, including in subagents.",
+      "For generic plans only, before the first implementation milestone identify independent substantial work. Launch a bounded subagent task while you continue another, or state the concrete reason delegation is unsuitable.",
+      "Use a generic plan as the foreground coordinator's milestone ledger only when no workflow owns planning. Otherwise follow the workflow's task plan and foreground role.",
+      "For generic plans, use separate steps for distinct deliverables, not one step per worker process. Before completing verification or the plan, inspect and integrate every relevant delegated result or failure.",
     ],
     parameters: UpdatePlanSchema,
-    async execute(_toolCallId, params) {
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const owner = workflowPlanOwner(ctx);
+      if (owner) throw new Error(`${owner} owns the task plan. Update its workflow plan instead of update_plan.`);
       const input = params as { explanation?: string; plan: PlanStepInput[] };
       const plan = replacePlan(currentPlan, input.plan, input.explanation);
       persistPlan(plan);
@@ -185,7 +212,12 @@ export default function planExtension(pi: ExtensionAPI): void {
     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() {
+    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 (!currentPlan) {
         return {
           content: [{ type: "text", text: "No plan is set." }],
@@ -235,7 +267,8 @@ export default function planExtension(pi: ExtensionAPI): void {
   pi.on("session_tree", async (_event, ctx) => {
     restore(ctx);
   });
-  pi.on("before_agent_start", async (event) => {
+  pi.on("before_agent_start", async (event, ctx) => {
+    if (workflowPlanOwner(ctx)) return;
     if (!currentPlan) return;
     return {
       systemPrompt: `${event.systemPrompt}\n\n${planPrompt(currentPlan)}`,
@@ -243,6 +276,7 @@ export default function planExtension(pi: ExtensionAPI): void {
   });
   pi.on("session_shutdown", async (_event, ctx) => {
     cancelCompletedPlanClear();
+    if (typeof unsubscribeWorkflow === "function") unsubscribeWorkflow();
     refreshWidget = undefined;
     try {
       ctx.ui.setStatus(LEGACY_PLAN_NAV_STATUS_KEY, undefined);
@@ -256,24 +290,37 @@ function formatProgress(plan: PlanSnapshot): string {
   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}`);
+  if (progress.inProgress > 1) status.push(`${progress.inProgress} steps in progress`);
+  else if (current) status.push(`Current step: ${current.step}`);
+  if (plan.steps.some((item) => item.dependsOn?.length)) status.push(`${progress.readyIndices.length} ready`);
   return status.join(". ") + ".";
 }
 
+function stepLine(item: PlanSnapshot["steps"][number], index: number): string {
+  return `${index + 1}. [${item.status}] ${item.step}${item.dependsOn?.length ? ` (after: ${item.dependsOn.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}`),
+    ...plan.steps.map(stepLine),
+    ...(plan.steps.some((item) => item.dependsOn?.length)
+      ? [`Ready: ${progress.readyIndices.map((index) => plan.steps[index]!.step).join(", ") || "none"}`]
+      : []),
   ].join("\n");
 }
 
 function planPrompt(plan: PlanSnapshot): string {
   return [
     "Current structured execution plan:",
-    ...plan.steps.map((item, index) => `${index + 1}. [${item.status}] ${item.step}`),
+    ...plan.steps.map(stepLine),
+    ...(plan.steps.some((item) => item.dependsOn?.length)
+      ? [`Ready pending steps: ${planProgress(plan).readyIndices.map((index) => plan.steps[index]!.step).join(", ") || "none"}. Start only steps whose prerequisites are complete.`]
+      : []),
     "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.",
+    "Before starting the first implementation milestone, identify independent substantial work. If a subagent is available, launch one bounded task early while you continue another; otherwise briefly state the concrete dependency or shared-worktree constraint that makes delegation unsuitable.",
+    "Treat the plan as the foreground coordinator's milestone ledger: delegate independent, sufficiently substantial work early, mark distinct foreground and delegated milestones in_progress concurrently, 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;
+const STEP_ID = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
 export const COMPLETED_PLAN_RETENTION_MS = 30_000;
 
 interface SessionEntryLike {
@@ -32,8 +33,8 @@ export function validatePlanInput(steps: readonly PlanStepInput[], explanation?:
     return `Plan explanation cannot exceed ${MAX_EXPLANATION_CHARS} characters.`;
   }
 
-  let inProgress = 0;
   const normalized = new Set<string>();
+  const ids = new Map<string, number>();
   for (let index = 0; index < steps.length; index += 1) {
     const item = steps[index]!;
     const text = item.step.trim();
@@ -44,9 +45,43 @@ export function validatePlanInput(steps: readonly PlanStepInput[], explanation?:
     const key = text.toLocaleLowerCase();
     if (normalized.has(key)) return `Plan step ${index + 1} duplicates an earlier step.`;
     normalized.add(key);
-    if (item.status === "in_progress") inProgress += 1;
+    if (item.id !== undefined) {
+      if (!STEP_ID.test(item.id)) return `Plan step ${index + 1} has an invalid id.`;
+      if (ids.has(item.id)) return `Plan step ${index + 1} duplicates id ${item.id}.`;
+      ids.set(item.id, index);
+    }
+  }
+
+  for (let index = 0; index < steps.length; index += 1) {
+    const item = steps[index]!;
+    const seen = new Set<string>();
+    for (const dependency of item.dependsOn ?? []) {
+      if (seen.has(dependency)) return `Plan step ${index + 1} repeats dependency ${dependency}.`;
+      seen.add(dependency);
+      const prerequisite = ids.get(dependency);
+      if (prerequisite === undefined) return `Plan step ${index + 1} references unknown dependency ${dependency}. Use explicit ids for dependencies.`;
+      if ((item.status === "in_progress" || item.status === "completed") && steps[prerequisite]!.status !== "completed") {
+        return `Plan step ${index + 1} cannot be ${item.status} until dependency ${dependency} is completed.`;
+      }
+    }
+  }
+  const visited = new Set<string>();
+  const visiting = new Set<string>();
+  const visit = (id: string): boolean => {
+    if (visiting.has(id)) return true;
+    if (visited.has(id)) return false;
+    visiting.add(id);
+    const item = steps[ids.get(id)!]!;
+    for (const dependency of item.dependsOn ?? []) {
+      if (visit(dependency)) return true;
+    }
+    visiting.delete(id);
+    visited.add(id);
+    return false;
+  };
+  for (const id of ids.keys()) {
+    if (visit(id)) return `Plan dependencies contain a cycle involving ${id}.`;
   }
-  if (inProgress > 1) return "A plan can have at most one step in progress.";
   return null;
 }
 
@@ -65,11 +100,15 @@ export function replacePlan(
   const normalizedSteps: PlanStep[] = steps.map((item, index) => {
     const step = item.step.trim();
     return {
-      id: reusableIds.get(step.toLocaleLowerCase()) ?? `step_${revision}_${index + 1}`,
+      id: item.id ?? reusableIds.get(step.toLocaleLowerCase()) ?? `step_${revision}_${index + 1}`,
       step,
       status: item.status,
+      ...(item.dependsOn?.length ? { dependsOn: [...item.dependsOn] } : {}),
     };
   });
+  if (new Set(normalizedSteps.map((item) => item.id)).size !== normalizedSteps.length) {
+    throw new Error("Plan step ids must be unique, including generated ids.");
+  }
   const isComplete = normalizedSteps.every((item) => item.status === "completed");
   const currentIsComplete = current?.steps.every((item) => item.status === "completed") === true;
 
@@ -98,14 +137,19 @@ export function planProgress(plan: PlanSnapshot): PlanProgress {
   const pending = plan.steps.filter((item) => item.status === "pending").length;
   const blocked = plan.steps.filter((item) => item.status === "blocked").length;
   const inProgress = plan.steps.filter((item) => item.status === "in_progress").length;
-  const activeIndex = plan.steps.findIndex((item) => item.status === "in_progress" || item.status === "blocked");
+  const activeIndex = plan.steps.findIndex((item) => item.status === "in_progress");
+  const blockedIndex = plan.steps.findIndex((item) => item.status === "blocked");
+  const completedIds = new Set(plan.steps.filter((item) => item.status === "completed").map((item) => item.id));
+  const readyIndices = plan.steps.flatMap((item, index) =>
+    item.status === "pending" && (item.dependsOn ?? []).every((id) => completedIds.has(id)) ? [index] : []);
   return {
     total: plan.steps.length,
     completed,
     pending,
     blocked,
     inProgress,
-    activeIndex: activeIndex >= 0 ? activeIndex : null,
+    activeIndex: activeIndex >= 0 ? activeIndex : blockedIndex >= 0 ? blockedIndex : null,
+    readyIndices,
     state:
       completed === plan.steps.length
         ? "complete"

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

@@ -4,8 +4,10 @@ export type PlanStepStatus = "pending" | "in_progress" | "completed" | "blocked"
 export type PlanDisplayMode = "auto" | "on" | "off" | "hidden";
 
 export interface PlanStepInput {
+  id?: string;
   step: string;
   status: PlanStepStatus;
+  dependsOn?: string[];
 }
 
 export interface PlanStep extends PlanStepInput {
@@ -30,6 +32,7 @@ export interface PlanProgress {
   blocked: number;
   inProgress: number;
   activeIndex: number | null;
+  readyIndices: number[];
   state: "draft" | "in_progress" | "blocked" | "complete";
 }
 

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

@@ -128,7 +128,7 @@ const SUBAGENT_TOOLS = [
 ];
 
 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.",
+    "When a structured plan is active, keep it as the parent-owned coordinator ledger: mark distinct delegated and foreground deliverables in_progress concurrently, 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.",
 ];
 

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "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-navigator.ts

@@ -918,7 +918,7 @@ function createOverlayComponent(
           width,
           deps.truncate,
           fg,
-          { minRows: detailRows, bottomFooter: false, logTailRows },
+          { minRows: detailRows, maxRows: detailRows, bottomFooter: false, logTailRows },
         );
       } else {
         transcriptDetail = null;
@@ -1003,21 +1003,33 @@ function buildTranscriptDetailLines(
   width: number,
   truncate: (s: string, width: number) => string,
   fg: (color: string, value: string) => string,
-  options: { minRows?: number; bottomFooter?: boolean; logTailRows?: number } = {},
+  options: { minRows?: number; maxRows?: number; bottomFooter?: boolean; logTailRows?: number } = {},
 ): string[] {
   const actions = [...(detail.footerActions ?? ["x close"]), "Esc close"].join(" · ");
   const tailRows = options.logTailRows ?? DEFAULT_LOG_TAIL_ROWS;
-  const shownTranscriptLines = transcriptLines.length ? transcriptLines.slice(-tailRows) : ["   (no transcript yet)"];
+  let shownTranscriptLines = transcriptLines.length ? transcriptLines.slice(-tailRows) : ["   (no transcript yet)"];
   const lines: string[] = [
     fg("accent", rule(detail.title, width)),
     dim(`   ← main · ${actions}`, fg),
     "",
     `   status   ${fg(toneColor(detail.statusTone, detail.status), detail.status)}`,
   ];
-  if (detail.subtitle) lines.push(`   summary  ${detail.subtitle}`);
-  for (const item of detail.metadata) lines.push(`   ${item.label.padEnd(8, " ").slice(0, 8)} ${item.value}`);
-  lines.push("", dim(section(`transcript · latest ${tailRows} rows`, width), fg));
-  if (detail.transcriptDiagnostic) lines.push(`   ${dim(detail.transcriptDiagnostic, fg)}`);
+  const optionalMetadata = [
+    ...(detail.subtitle ? [`   summary  ${detail.subtitle}`] : []),
+    ...detail.metadata.map((item) => `   ${item.label.padEnd(8, " ").slice(0, 8)} ${item.value}`),
+  ];
+  const transcriptHeader = ["", dim(section(`transcript · latest ${tailRows} rows`, width), fg)];
+  if (detail.transcriptDiagnostic) transcriptHeader.push(`   ${dim(detail.transcriptDiagnostic, fg)}`);
+  if (options.maxRows !== undefined) {
+    const fixedRows = lines.length + transcriptHeader.length + 1;
+    const transcriptBudget = Math.max(1, options.maxRows - fixedRows);
+    shownTranscriptLines = shownTranscriptLines.slice(-transcriptBudget);
+    const metadataBudget = Math.max(0, options.maxRows - fixedRows - shownTranscriptLines.length);
+    lines.push(...optionalMetadata.slice(0, metadataBudget));
+  } else {
+    lines.push(...optionalMetadata);
+  }
+  lines.push(...transcriptHeader);
   lines.push(...shownTranscriptLines);
   lines.push("");
   if (options.bottomFooter === false) return lines.map((line) => safeTruncate(line, width, truncate));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-harness",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "description": "Pi extension bundle for a write sandbox, subagents, background tasks, SSH, goals, and structured plans.",
   "license": "MIT",
   "type": "module",
@@ -50,12 +50,13 @@
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
-    "pi-better-background-tasks": "0.2.12",
-    "pi-better-goal": "0.2.3",
-    "pi-better-plan": "0.1.5",
+    "pi-better-background-tasks": "0.2.13",
+    "pi-better-goal": "0.3.0",
+    "pi-better-plan": "0.2.0",
     "pi-better-sandbox": "0.3.0",
     "pi-better-ssh": "0.1.1",
-    "pi-better-subagents": "0.1.27"
+    "pi-better-subagents": "0.1.29",
+    "yaml": "^2.9.1"
   },
   "bundledDependencies": [
     "pi-better-background-tasks",