pi-better-harness 0.28.1 → 0.29.0

package/extensions/execution-policy.ts

@@ -0,0 +1,18 @@
+/** Harness-wide scheduling guidance, vendored so standalone extensions share it. */
+const EXECUTION_POLICY = [
+  "Harness execution policy: concurrency is separate from subagent delegation.",
+  "Before multi-unit work, identify ready, authorized, independent units, actual prerequisites, shared mutable resources, and capacity or availability constraints. Represent independently verifiable deliverables (such as each host migration) separately in the plan; do not hide them in one serial rollout step or create dependencies merely from list order.",
+  "Start all ready, authorized, non-conflicting units concurrently within known resource limits before waiting for any one to finish. Reassess ready work after launches and results; continue unblocked foreground work instead of polling running tasks. Do not equate one background launch with scheduling all ready work.",
+  "Serialize only for a concrete dependency, conflicting writes or ownership, resource or concurrency limit, documented rollout gate, or explicit availability requirement. Record the reason in the plan or explain it to the user. Do not invent a canary or host-by-host availability requirement.",
+  "If concurrency raises an unresolved material operational trade-off (for example, draining all hosts could leave no available runners), ask the user once before the affected operations. Continue independent preparation meanwhile. Existing authorization, safety checks, workflow prerequisites, and human-approved rollout constraints remain binding; urgency does not waive them.",
+  "Choose the execution mechanism after deciding what can run together: foreground tools for small, tightly coupled, or interactive work; subagents for bounded independent reasoning or implementation when the active delegation mode permits; background tasks for independent long-running commands or waits. Manual delegation forbids proactive subagents, not concurrent foreground tools or background commands. Use available batch or parallel tool interfaces where appropriate and inspect every launch receipt for failures or skipped work.",
+  "A unit waiting or failing does not block other ready independent units unless the evidence shows a shared blocker. Preserve each unit's guards and rollback boundary. Before completing verification, the plan, or the goal, inspect and integrate every relevant terminal result or failure; launch is not completion.",
+].join("\n");
+
+export function appendExecutionPolicy(systemPrompt: string): string {
+  // Inspect the prompt, not module-global state: vendored copies have separate
+  // module identities, and every fresh turn or reload needs the policy again.
+  return systemPrompt.includes(EXECUTION_POLICY)
+    ? systemPrompt
+    : `${systemPrompt}\n\n${EXECUTION_POLICY}`;
+}

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

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

@@ -5,8 +5,10 @@ import { clearBackgroundTasksNavigatorSession, ensureBackgroundTasksNavigator, e
 import { resumeScheduledWork, suspendScheduledWork } from "./runtime.js";
 import { observeForegroundSandboxPolicy } from "./sandbox.js";
 import { registerTools } from "./tools.js";
+import { appendExecutionPolicy } from "./shared-execution-policy.js";
 
 export default function backgroundTasksExtension(pi: ExtensionAPI): void {
+  pi.on("before_agent_start", (event) => ({ systemPrompt: appendExecutionPolicy(event.systemPrompt) }));
   registerBackgroundTasksGoalProvider(pi);
   ensureBackgroundTasksNavigatorProvider(pi);
   // Subscribed at load so a sandbox extension that publishes later is heard, and

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

@@ -0,0 +1,19 @@
+// Generated from packages/pi-better-harness/extensions/execution-policy.ts. Do not edit directly.
+/** Harness-wide scheduling guidance, vendored so standalone extensions share it. */
+const EXECUTION_POLICY = [
+  "Harness execution policy: concurrency is separate from subagent delegation.",
+  "Before multi-unit work, identify ready, authorized, independent units, actual prerequisites, shared mutable resources, and capacity or availability constraints. Represent independently verifiable deliverables (such as each host migration) separately in the plan; do not hide them in one serial rollout step or create dependencies merely from list order.",
+  "Start all ready, authorized, non-conflicting units concurrently within known resource limits before waiting for any one to finish. Reassess ready work after launches and results; continue unblocked foreground work instead of polling running tasks. Do not equate one background launch with scheduling all ready work.",
+  "Serialize only for a concrete dependency, conflicting writes or ownership, resource or concurrency limit, documented rollout gate, or explicit availability requirement. Record the reason in the plan or explain it to the user. Do not invent a canary or host-by-host availability requirement.",
+  "If concurrency raises an unresolved material operational trade-off (for example, draining all hosts could leave no available runners), ask the user once before the affected operations. Continue independent preparation meanwhile. Existing authorization, safety checks, workflow prerequisites, and human-approved rollout constraints remain binding; urgency does not waive them.",
+  "Choose the execution mechanism after deciding what can run together: foreground tools for small, tightly coupled, or interactive work; subagents for bounded independent reasoning or implementation when the active delegation mode permits; background tasks for independent long-running commands or waits. Manual delegation forbids proactive subagents, not concurrent foreground tools or background commands. Use available batch or parallel tool interfaces where appropriate and inspect every launch receipt for failures or skipped work.",
+  "A unit waiting or failing does not block other ready independent units unless the evidence shows a shared blocker. Preserve each unit's guards and rollback boundary. Before completing verification, the plan, or the goal, inspect and integrate every relevant terminal result or failure; launch is not completion.",
+].join("\n");
+
+export function appendExecutionPolicy(systemPrompt: string): string {
+  // Inspect the prompt, not module-global state: vendored copies have separate
+  // module identities, and every fresh turn or reload needs the policy again.
+  return systemPrompt.includes(EXECUTION_POLICY)
+    ? systemPrompt
+    : `${systemPrompt}\n\n${EXECUTION_POLICY}`;
+}

package/node_modules/pi-better-background-tasks/src/tools.ts

@@ -184,6 +184,7 @@ const StatusActionParams = Type.Object({
 });
 
 const BACKGROUND_ORCHESTRATION_GUIDELINES = [
+  "Follow the Harness execution policy when scheduling independent background operations; subagent delegation mode does not require background commands to run serially.",
   "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.",

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

@@ -44,7 +44,7 @@ metadata:
   workflow-role: coordinator
 ```
 
-Invoke the skill with Pi's `/skill:name` command, or supervise it with `/goal /skill:name task`. The goal extension resolves the command against Pi's registry, persists its source, and expands the skill on kickoff and continuation (including after session resume). A bound command that disappears or changes source pauses the goal. `/goal /template task` also re-expands prompt templates on continuation; `/goal /extension-command task` dispatches the extension command once, then continues with ordinary goal supervision to avoid repeating side effects. Plain-language goals work as before. This command binding requires Pi 0.84.4 or later. Legacy slash-shaped goals without a binding pause on resume rather than running without the skill. `/workflow` shows a coordinator skill owner; call `release_workflow` after the workflow's completion audit, or use `/workflow clear` to release ownership manually. `release_workflow` also pauses an active Goal bound to that coordinator, preserving its objective and incomplete status. Reinvoke the skill explicitly before `/goal resume`; automatic continuation cannot reacquire ownership. Unrelated ordinary Goals are unchanged. Completing an active goal also releases ownership.
+Invoke the skill with Pi's `/skill:name` command, or supervise it with `/goal /skill:name task`. The goal extension resolves the command against Pi's registry, persists its source, and expands the skill on kickoff and continuation (including after session resume). A bound command that disappears or changes source pauses the goal. `/goal /template task` also re-expands prompt templates on continuation; `/goal /extension-command task` dispatches the extension command once, then continues with ordinary goal supervision to avoid repeating side effects. Plain-language goals work as before. This command binding requires Pi 0.84.4 or later. Legacy slash-shaped goals without a binding pause on resume rather than running without the skill. `/workflow` shows a coordinator skill owner. When the workflow is done, complete the goal (`update_goal`), which also releases ownership. When it hands back unfinished work, call `release_workflow`, or use `/workflow clear` to release ownership manually. `release_workflow` also pauses an active Goal bound to that coordinator as a handback, preserving its objective and incomplete status. Resuming that Goal (`/goal resume`, `alt+g`, or, with conversational resume on, the user's go-ahead such as "continue") rebinds the coordinator it was created with, provided the skill is still registered at its original source; automatic continuation and synthetic input never reacquire ownership. Unrelated ordinary Goals are unchanged.
 
 A skill that is only an alias of a coordinator declares the target instead of a role:
 

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

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

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

@@ -66,7 +66,7 @@ function isGoalStatus(value: unknown): value is GoalStatus {
 }
 
 function isPauseReason(value: unknown): value is GoalPauseReason {
-  return value === "interrupt" || value === "permission-blocker";
+  return value === "interrupt" || value === "permission-blocker" || value === "handback";
 }
 
 function isGoalLike(value: unknown): value is GoalLike {

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

@@ -87,7 +87,8 @@ const GOAL_RESUME_RULE =
 
 /** True when the agent may resume this goal with `goal_resume`. */
 export function agentResumable(goal: GoalSnapshot | null, conversationalResume = true): boolean {
-  return conversationalResume && goal?.status === "paused" && goal.pauseReason === "interrupt";
+  return conversationalResume && goal?.status === "paused" &&
+    (goal.pauseReason === "interrupt" || goal.pauseReason === "handback");
 }
 
 /** Footer status for a paused goal, telling the user how to resume it. */
@@ -98,7 +99,9 @@ export function pausedGoalStatus(goal: GoalSnapshot, conversationalResume = true
 
 function pausedGoalPrompt(goal: GoalSnapshot, conversationalResume: boolean): string {
   return [
-    `Pi Better Goal is paused because the user pressed escape. Goal: ${goal.objective}`,
+    goal.pauseReason === "handback"
+      ? `Pi Better Goal is paused because its workflow handed back unfinished work for the user's answer. Goal: ${goal.objective}`
+      : `Pi Better Goal is paused because the user pressed escape. Goal: ${goal.objective}`,
     "Treat the user's messages as ordinary conversation: answer them, but do not continue the goal's work until it is resumed.",
     conversationalResume ? GOAL_RESUME_RULE : "Only the user can resume this goal, with /goal resume or alt+g. A conversational go-ahead does not resume it.",
   ].join("\n");
@@ -456,15 +459,21 @@ export default function (pi: ExtensionAPI): void {
       return `Cannot resume: /${goal.command.name} is no longer registered at its original source.`;
     }
     if (goal.command?.source === "skill") {
-      const owner = workflowOwnerFromSkill(goal.command.name.slice("skill:".length), goal.command.path, registeredSkillPath);
-      const activeOwner = getWorkflow(ctx);
-      if (owner && (activeOwner?.name !== owner.name || activeOwner.path !== owner.path)) {
-        return `Reinvoke /${goal.command.name} before resuming its workflow goal.`;
+      try {
+        goalWorkflowOwner(goal);
+      } catch (error) {
+        return `Cannot resume: ${error instanceof Error ? error.message : String(error)} Reinvoke /${goal.command.name}.`;
       }
     }
     return null;
   };
 
+  /** The workflow a skill-bound goal owns, re-resolved from its registered skill; null for other goals. */
+  const goalWorkflowOwner = (goal: GoalSnapshot): ReturnType<typeof currentWorkflowOwner> =>
+    goal.command?.source === "skill"
+      ? workflowOwnerFromSkill(goal.command.name.slice("skill:".length), goal.command.path, registeredSkillPath)
+      : null;
+
   /**
    * The one resume path shared by `/goal resume`, the hotkey, and `goal_resume`:
    * reactivate a paused goal or reopen an active no-progress hold.
@@ -498,6 +507,11 @@ export default function (pi: ExtensionAPI): void {
       }
       pi.appendEntry(EXTENSION_NAME, permissionRecord(current.goalId, "permission-release"));
     }
+    // Resuming a skill-bound goal is explicit re-entry into its workflow: rebind the owner the
+    // goal was created with (released by a handback) before the continuation runs.
+    const owner = goalWorkflowOwner(current);
+    const activeOwner = getWorkflow(ctx);
+    if (owner && (activeOwner?.name !== owner.name || activeOwner.path !== owner.path)) recordWorkflow(owner);
     setGoal(goal, ctx, source);
     queueGoalContinuation(goal, ctx);
     return { ok: true, goal };
@@ -1049,8 +1063,8 @@ export default function (pi: ExtensionAPI): void {
     name: GOAL_RESUME_TOOL,
     label: "Resume Goal",
     description:
-      "Resume the goal the user paused with escape, exactly like /goal resume. " + GOAL_RESUME_RULE,
-    promptSnippet: "Resume the escape-paused goal, only on the user's clear go-ahead.",
+      "Resume the goal the user paused with escape, or one its workflow handed back, exactly like /goal resume. " + GOAL_RESUME_RULE,
+    promptSnippet: "Resume the escape-paused or handed-back goal, only on the user's clear go-ahead.",
     parameters: Type.Object({
       reason: Type.Optional(Type.String({ description: "Short quote or summary of the user's go-ahead." })),
     }),
@@ -1115,7 +1129,7 @@ export default function (pi: ExtensionAPI): void {
   pi.registerTool({
     name: "release_workflow",
     label: "Release Workflow",
-    description: "Release the active skill-owned workflow after its final handoff and completion audit. Its bound active Goal pauses; explicitly reinvoke the skill before resuming that Goal.",
+    description: "Release the active skill-owned workflow when it hands back unfinished work (a blocked unit awaiting the human). Its bound active Goal pauses; /goal resume rebinds the workflow. When the workflow is done, call update_goal complete instead, which also releases it.",
     parameters: Type.Object({}),
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
       const owner = getWorkflow(ctx);
@@ -1125,13 +1139,13 @@ export default function (pi: ExtensionAPI): void {
       if (goal?.status === "active" && goal.command?.source === "skill") {
         const boundOwner = workflowOwnerFromSkill(goal.command.name.slice("skill:".length), goal.command.path, registeredSkillPath);
         if (boundOwner?.name === owner.name && boundOwner.path === owner.path) {
-          setGoal(goalWithStatus(goal, "paused"), ctx, "tool");
+          setGoal(goalWithStatus(goal, "paused", undefined, "handback"), ctx, "tool");
           resumeCommand = goal.command.name;
         }
       }
       recordWorkflow(null);
       return {
-        content: [{ type: "text", text: `Released ${owner.name} workflow ownership.${resumeCommand ? ` Its Goal is paused, not complete. Reinvoke /${resumeCommand} before /goal resume.` : ""}` }],
+        content: [{ type: "text", text: `Released ${owner.name} workflow ownership.${resumeCommand ? ` Its Goal is paused, not complete; the user's go-ahead or /goal resume rebinds /${resumeCommand}.` : ""}` }],
         details: { released: true, owner: owner.name, goalPaused: resumeCommand !== undefined },
       };
     },
@@ -1261,7 +1275,7 @@ export default function (pi: ExtensionAPI): void {
     if (permissionPrompt && goal?.status === "paused") {
       return { systemPrompt: `${event.systemPrompt}\n\n${permissionPrompt}` };
     }
-    const pausedInstruction = permissionPrompt || (goal?.status === "paused" && goal.pauseReason === "interrupt"
+    const pausedInstruction = permissionPrompt || (goal?.status === "paused" && (goal.pauseReason === "interrupt" || goal.pauseReason === "handback")
       ? pausedGoalPrompt(goal, preferences.conversationalResume) : "");
     if (!isPokeable(goal) && !owner) {
       return pausedInstruction ? { systemPrompt: `${event.systemPrompt}\n\n${pausedInstruction}` } : undefined;

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

@@ -75,7 +75,8 @@ export type GoalStatus = "active" | "paused" | "budgetLimited" | "complete";
  * requires those human controls, and releases just one same-scope retry while
  * keeping its separate blocker/release history.
  */
-export type GoalPauseReason = "interrupt" | "permission-blocker";
+/** Why a goal paused: escape, a permission hold, or a workflow handing back unfinished work for the user's answer. */
+export type GoalPauseReason = "interrupt" | "permission-blocker" | "handback";
 
 export interface GoalUsage {
   tokensUsed: number;

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

@@ -4,22 +4,36 @@ Technical details for workflow authors and contributors. For installation, scree
 
 ## 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.
-
-Before the first implementation milestone, check for independent work and follow
-the active subagent delegation mode. Without `pi-better-subagents`, the plan uses
-adaptive guidance. Manual keeps planned work in the foreground unless the user or
-an active workflow explicitly requires delegation. Adaptive delegates substantial
-independent work when useful. Coordinator consults current catalog roles and
-delegates nontrivial role-owned work while retaining integration and final
-verification in the foreground.
-
-Independent foreground and delegated milestones may both be `in_progress` only
-when both are actually underway. Use steps for distinct deliverables, not
+Use the plan as the foreground coordinator's milestone ledger. Before the first
+implementation milestone, identify ready, authorized independent units, including
+separate per-host migrations, and start them concurrently within resource
+constraints before waiting. Serialize only for real dependencies, shared writes,
+resource or capacity limits, or explicit rollout or availability requirements;
+record the reason in the plan.
+
+Execution concurrency is separate from subagent delegation. Use foreground tools
+for small, tightly coupled, or interactive work, and background tasks for
+independent long-running commands or waits. Follow the active subagent delegation
+mode; without `pi-better-subagents`, the plan uses adaptive guidance. Manual
+forbids proactive subagents, not parallel foreground or background execution;
+an explicit user request or active workflow requirement may still authorize
+delegation. Adaptive delegates substantial independent work when useful.
+Coordinator consults current catalog roles and delegates nontrivial role-owned
+work while retaining integration and final verification in the foreground.
+Continue unblocked foreground work after launch; do not poll workers.
+
+Ask once about an unresolved material operational availability tradeoff while
+independent preparation continues. A host-local failure does not block other
+independent hosts unless there is evidence of a shared cause. Safety,
+authorization, and workflow prerequisites remain unchanged. This policy adds no
+auto-launcher, scheduler, or reminder loops.
+
+Distinct ready milestones may be `in_progress` concurrently only when their work
+is actually underway. Use separate steps for per-host 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.
+run status. Complete verification, the plan, or the active goal only after every
+relevant subagent and background 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.
 

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

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

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

@@ -2,6 +2,7 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Text, type AutocompleteItem } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
+import { appendExecutionPolicy } from "./shared-execution-policy.js";
 
 import {
   completedPlanClearDelay,
@@ -342,8 +343,8 @@ export default function planExtension(pi: ExtensionAPI): void {
     promptGuidelines: [
       "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 distinct milestones in_progress 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 when the active delegation mode permits it.",
-      "For generic plans, follow the active delegation mode. Manual forbids proactive delegation even in plan mode; adaptive favors substantial independent work; coordinator delegates nontrivial role-owned tasks after agents_catalog discovery.",
+      "For generic plans with prerequisites, give steps stable ids and dependsOn edges for actual dependencies, not list order. Start ready independent steps concurrently under the Harness execution policy; subagent delegation mode controls subagents, not background-command concurrency.",
+      "For generic plans, follow the active delegation mode for subagents. Manual forbids proactive subagent delegation even in plan mode; adaptive favors substantial independent work; coordinator delegates nontrivial role-owned tasks after agents_catalog discovery.",
       "Use a generic plan as a 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.",
       "While a workflow owns planning, bind its persisted task plan with update_plan({workflow:{path,revision}}). Then record every transition with update_plan's workflow event and changes instead of editing task-plan.json or its profiling log; it saves the rows, the next planRevision, and the matching profiling event together. Path and revision can accompany the first transition to bind and update in one call.",
@@ -510,10 +511,12 @@ export default function planExtension(pi: ExtensionAPI): void {
     restore(ctx);
   });
   pi.on("before_agent_start", async (event, ctx) => {
-    if (workflowPlanOwner(ctx) || workflowBinding(ctx.sessionManager.getBranch())) return;
-    if (!currentPlan) return;
+    const systemPrompt = appendExecutionPolicy(event.systemPrompt);
+    if (workflowPlanOwner(ctx) || workflowBinding(ctx.sessionManager.getBranch()) || !currentPlan) {
+      return systemPrompt === event.systemPrompt ? undefined : { systemPrompt };
+    }
     return {
-      systemPrompt: `${event.systemPrompt}\n\n${planPrompt(currentPlan, activeDelegationMode(pi))}`,
+      systemPrompt: `${systemPrompt}\n\n${planPrompt(currentPlan, activeDelegationMode(pi))}`,
     };
   });
   pi.on("session_shutdown", async (_event, ctx) => {
@@ -555,7 +558,7 @@ function formatPlan(plan: PlanSnapshot): string {
 
 function planPrompt(plan: PlanSnapshot, mode: DelegationMode): string {
   const delegation = mode === "manual"
-    ? "Manual delegation mode: a plan does not authorize proactive delegation. Work in the foreground unless the user explicitly asks or an active workflow explicitly requires delegation."
+    ? "Manual delegation mode: a plan does not authorize proactive delegation to subagents. Independent foreground and background operations still follow the Harness execution policy. Use subagents only when the user explicitly asks or an active workflow explicitly requires delegation."
     : mode === "coordinator"
       ? "Coordinator delegation mode: consult agents_catalog and delegate nontrivial role-owned milestones according to current role descriptions. Keep orchestration, cross-role decisions, unowned or ambiguous work, integration, and final verification in the foreground."
       : "Adaptive delegation mode: identify substantial independent work before implementation. Delegate a bounded task when useful and available while continuing unblocked foreground work; keep tightly coupled work in the foreground.";

package/node_modules/pi-better-plan/src/shared-execution-policy.ts

@@ -0,0 +1,19 @@
+// Generated from packages/pi-better-harness/extensions/execution-policy.ts. Do not edit directly.
+/** Harness-wide scheduling guidance, vendored so standalone extensions share it. */
+const EXECUTION_POLICY = [
+  "Harness execution policy: concurrency is separate from subagent delegation.",
+  "Before multi-unit work, identify ready, authorized, independent units, actual prerequisites, shared mutable resources, and capacity or availability constraints. Represent independently verifiable deliverables (such as each host migration) separately in the plan; do not hide them in one serial rollout step or create dependencies merely from list order.",
+  "Start all ready, authorized, non-conflicting units concurrently within known resource limits before waiting for any one to finish. Reassess ready work after launches and results; continue unblocked foreground work instead of polling running tasks. Do not equate one background launch with scheduling all ready work.",
+  "Serialize only for a concrete dependency, conflicting writes or ownership, resource or concurrency limit, documented rollout gate, or explicit availability requirement. Record the reason in the plan or explain it to the user. Do not invent a canary or host-by-host availability requirement.",
+  "If concurrency raises an unresolved material operational trade-off (for example, draining all hosts could leave no available runners), ask the user once before the affected operations. Continue independent preparation meanwhile. Existing authorization, safety checks, workflow prerequisites, and human-approved rollout constraints remain binding; urgency does not waive them.",
+  "Choose the execution mechanism after deciding what can run together: foreground tools for small, tightly coupled, or interactive work; subagents for bounded independent reasoning or implementation when the active delegation mode permits; background tasks for independent long-running commands or waits. Manual delegation forbids proactive subagents, not concurrent foreground tools or background commands. Use available batch or parallel tool interfaces where appropriate and inspect every launch receipt for failures or skipped work.",
+  "A unit waiting or failing does not block other ready independent units unless the evidence shows a shared blocker. Preserve each unit's guards and rollback boundary. Before completing verification, the plan, or the goal, inspect and integrate every relevant terminal result or failure; launch is not completion.",
+].join("\n");
+
+export function appendExecutionPolicy(systemPrompt: string): string {
+  // Inspect the prompt, not module-global state: vendored copies have separate
+  // module identities, and every fresh turn or reload needs the policy again.
+  return systemPrompt.includes(EXECUTION_POLICY)
+    ? systemPrompt
+    : `${systemPrompt}\n\n${EXECUTION_POLICY}`;
+}

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

@@ -15,7 +15,7 @@ export function normalizeDelegationMode(value: unknown): DelegationMode {
 export function delegationPrompt(mode: DelegationMode): string {
     switch (mode) {
         case "manual":
-            return "Delegation mode: manual. Do not proactively delegate work. Use subagents only when the user explicitly asks for delegation or an active workflow explicitly requires it. A structured plan or plan mode does not override this restriction; perform planned work in the foreground unless explicitly required otherwise.";
+            return "Delegation mode: manual. Do not proactively delegate work to subagents. Use subagents only when the user explicitly asks for delegation or an active workflow explicitly requires it. A structured plan or plan mode does not override this restriction. This restricts subagent delegation, not execution concurrency: independent foreground tools and background tasks still follow the Harness execution policy.";
         case "coordinator":
             return "Delegation mode: coordinator. The foreground coordinates, integrates, and verifies. Call agents_catalog to discover current available roles and inspect their descriptions. Pass a role to subagent_spawn by its short name, as listed (role: \"developer\"). Delegate every nontrivial task covered by an available role according to its current description; do not assume bundled roles are unchanged. Keep orchestration, cross-role decisions, unowned or ambiguous work, integration, and final verification in the foreground. Inspect results and failures before concluding; do not poll for running children.";
         case "adaptive":

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

@@ -54,6 +54,7 @@ import {
 } from "./timing.ts";
 import { readAppendedLines, type LogCursor } from "./log-cursor.ts";
 import { DELEGATION_MODES, DELEGATION_MODE_REQUEST, delegationPrompt, isDelegationMode, normalizeDelegationMode, type DelegationMode } from "./delegation.ts";
+import { appendExecutionPolicy } from "./shared-execution-policy.ts";
 import { resolveExtensions, extensionArgs } from "./extensions.ts";
 import { prepareTaskRuntime } from "./task-policy.ts";
 import { canonicalizePath, takeRecoverySnapshot } from "./shared-sandbox-core.ts";
@@ -203,6 +204,7 @@ const CATALOG_GUIDELINES = [
 ];
 
 const SUBAGENT_ORCHESTRATION_GUIDELINES = [
+    "Follow the Harness execution policy for concurrency; the active delegation mode determines whether to use subagents, not whether independent background commands can overlap.",
     "When a structured plan is active, follow the current delegation mode. Track delegated and foreground deliverables only when delegation is permitted and actually underway; continue unblocked foreground work and integrate results before marking work complete.",
     "Do not treat launching a subagent as completion of the parent milestone; relevant terminal results must be inspected and integrated before verification or completion.",
 ];
@@ -2352,7 +2354,7 @@ export default function (pi: ExtensionAPI) {
     pi.registerTool(discoveryTool as Parameters<ExtensionAPI["registerTool"]>[0]);
 
     pi.on("before_agent_start", (event) => ({
-        systemPrompt: `${event.systemPrompt}\n\n${delegationPrompt(activeDelegationMode())}`,
+        systemPrompt: `${appendExecutionPolicy(event.systemPrompt)}\n\n${delegationPrompt(activeDelegationMode())}`,
     }));
 
     // ---- live-status lifecycle -----------------------------------------

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "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-execution-policy.ts

@@ -0,0 +1,19 @@
+// Generated from packages/pi-better-harness/extensions/execution-policy.ts. Do not edit directly.
+/** Harness-wide scheduling guidance, vendored so standalone extensions share it. */
+const EXECUTION_POLICY = [
+  "Harness execution policy: concurrency is separate from subagent delegation.",
+  "Before multi-unit work, identify ready, authorized, independent units, actual prerequisites, shared mutable resources, and capacity or availability constraints. Represent independently verifiable deliverables (such as each host migration) separately in the plan; do not hide them in one serial rollout step or create dependencies merely from list order.",
+  "Start all ready, authorized, non-conflicting units concurrently within known resource limits before waiting for any one to finish. Reassess ready work after launches and results; continue unblocked foreground work instead of polling running tasks. Do not equate one background launch with scheduling all ready work.",
+  "Serialize only for a concrete dependency, conflicting writes or ownership, resource or concurrency limit, documented rollout gate, or explicit availability requirement. Record the reason in the plan or explain it to the user. Do not invent a canary or host-by-host availability requirement.",
+  "If concurrency raises an unresolved material operational trade-off (for example, draining all hosts could leave no available runners), ask the user once before the affected operations. Continue independent preparation meanwhile. Existing authorization, safety checks, workflow prerequisites, and human-approved rollout constraints remain binding; urgency does not waive them.",
+  "Choose the execution mechanism after deciding what can run together: foreground tools for small, tightly coupled, or interactive work; subagents for bounded independent reasoning or implementation when the active delegation mode permits; background tasks for independent long-running commands or waits. Manual delegation forbids proactive subagents, not concurrent foreground tools or background commands. Use available batch or parallel tool interfaces where appropriate and inspect every launch receipt for failures or skipped work.",
+  "A unit waiting or failing does not block other ready independent units unless the evidence shows a shared blocker. Preserve each unit's guards and rollback boundary. Before completing verification, the plan, or the goal, inspect and integrate every relevant terminal result or failure; launch is not completion.",
+].join("\n");
+
+export function appendExecutionPolicy(systemPrompt: string): string {
+  // Inspect the prompt, not module-global state: vendored copies have separate
+  // module identities, and every fresh turn or reload needs the policy again.
+  return systemPrompt.includes(EXECUTION_POLICY)
+    ? systemPrompt
+    : `${systemPrompt}\n\n${EXECUTION_POLICY}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-harness",
-  "version": "0.28.1",
+  "version": "0.29.0",
   "description": "Pi extension bundle for a write sandbox, subagents, background tasks, SSH, goals, and structured plans.",
   "license": "MIT",
   "type": "module",
@@ -49,16 +49,16 @@
   ],
   "scripts": {
     "prepack": "node ../../scripts/sync-shared-log-utils.mjs && node ../../scripts/stage-harness-dependencies.mjs",
-    "typecheck": "tsc --noEmit --allowImportingTsExtensions --module NodeNext --moduleResolution NodeNext --target ES2022 --strict --skipLibCheck --types node extensions/minimal-output/index.ts extensions/minimal-output/hook.ts extensions/settings/index.ts",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions --module NodeNext --moduleResolution NodeNext --target ES2022 --strict --skipLibCheck --types node extensions/minimal-output/index.ts extensions/minimal-output/hook.ts extensions/settings/index.ts extensions/execution-policy.ts",
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
-    "pi-better-background-tasks": "0.8.0",
-    "pi-better-goal": "0.8.3",
-    "pi-better-plan": "0.8.0",
+    "pi-better-background-tasks": "0.9.0",
+    "pi-better-goal": "0.8.4",
+    "pi-better-plan": "0.9.0",
     "pi-better-sandbox": "0.12.0",
     "pi-better-ssh": "0.1.2",
-    "pi-better-subagents": "0.17.0",
+    "pi-better-subagents": "0.18.0",
     "proper-lockfile": "^4.1.2",
     "smol-toml": "1.9.0",
     "yaml": "^2.9.1"