pi-better-harness 0.40.1 → 0.40.2

package/extensions/execution-policy.ts

@@ -1,20 +1,60 @@
-/** Harness-wide scheduling guidance, vendored so standalone extensions share it. */
-const EXECUTION_POLICY = [
+/**
+ * Harness-wide scheduling guidance, vendored so standalone extensions share it.
+ *
+ * Published as a named system-prompt section, never as appended text. A
+ * `before_agent_start` handler that returns `systemPrompt` sets
+ * `forceSystemPrompt`, and a forced prompt is opaque to pi: `buildSystemPromptState`
+ * returns `{ content }` with no sections while `diffSystemPromptSections` keeps
+ * diffing the sections the request therefore never shows. The request carries a
+ * rendered snapshot, so any section published after that snapshot never reaches
+ * it, so every package that speaks here publishes a section.
+ */
+export const EXECUTION_POLICY_SECTION = "harness_execution_policy";
+
+/**
+ * The minimum shape this module needs. `sections` stays optional because this
+ * repo typechecks against older pi typings whose event options predate sections;
+ * the shipped runtime always supplies the map.
+ */
+export interface PromptSectionTarget {
+  sections?: Record<string, string>;
+}
+
+export const EXECUTION_POLICY_TEXT: string = [
   "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.",
+  "Before multi-unit work, identify ready, authorized, independent units, actual prerequisites, shared mutable resources, and capacity or availability constraints. Represent each independently verifiable deliverable as its own plan step; do not create dependencies 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.",
-  "Established command-only jobs and external waits belong to background operations, including in coordinator mode. Use bg_task_spawn for a long command and bg_task_watch for a repeated check; use watch_delivery for supported merge delivery so a stateful domain watcher observes the queue. A subagent assignment must require reasoning or implementation beyond launching and waiting. Workers retain their assigned validation: use supervised background tools and wait_for_operations to park, then resume the same conversation to interpret and acknowledge the terminal result. A linked external wait must have a registered observer and an execution owner. Continue independent work while it runs; a task launch or a completed parked attempt is not completion of the assignment.",
-  "If a worker hands back a command, the coordinator launches it through background tools with the supplied cwd and inspects its terminal result before claiming verification. Workers may run focused implementation checks; moving a command to a worker does not make it a background task.",
+  "If concurrency raises an unresolved material operational trade-off, ask the user once before the affected operations and 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. Inspect every launch receipt for failures or skipped work.",
+  "Established command-only jobs and external waits belong to background operations, including in coordinator mode. Use bg_task_spawn for a long command, bg_task_watch for a repeated check, and watch_delivery for supported merge delivery. A subagent assignment must require reasoning or implementation beyond launching and waiting. Workers retain their assigned validation: launch or watch, continue independent work, then park with wait_for_operations and inspect the terminal evidence on continuation. Continue independent work while it runs; a task launch is not completion of the assignment.",
+  "If a worker hands back a command, launch it through bg_task_spawn or bg_task_watch with the supplied cwd, and inspect its terminal result before claiming verification.",
   "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}`;
-}
+/**
+ * True when this pi runtime renders custom prompt sections.
+ *
+ * pi gained `systemPromptOptions.sections` after 0.84.4, and the packages here
+ * declare support back to 0.84.4. A section-only publisher is a silent no-op on
+ * an older host: the handler runs, the map is populated, and the prompt the model
+ * receives is unchanged. Callers must fall back to appending text instead.
+ */
+export function supportsPromptSections(options: unknown): boolean {
+  const sections = (options as { sections?: unknown } | undefined)?.sections;
+  return typeof sections === "object" && sections !== null;
+}
+
+/**
+ * Publish the policy into `options.sections`.
+ *
+ * Assignment, not concatenation: two packages publishing the same section write
+ * identical text, so load order cannot duplicate or drop it, and a repeated turn
+ * rewrites the same value so pi's section diff reports no change.
+ */
+export function publishExecutionPolicy<T extends object>(options: T): T {
+  const target = options as PromptSectionTarget;
+  const sections = (target.sections ??= {});
+  sections[EXECUTION_POLICY_SECTION] = EXECUTION_POLICY_TEXT;
+  return options;
+}

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "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

@@ -8,7 +8,7 @@ import { createObservedWaitHost } from "./observed-waits.js";
 import { getCallbackBatcher } from "./shared-callback-batcher.js";
 import { observeForegroundSandboxPolicy } from "./sandbox.js";
 import { registerTools } from "./tools.js";
-import { appendExecutionPolicy } from "./shared-execution-policy.js";
+import { deliverBackgroundTasksPrompt } from "./prompt.js";
 
 export default function backgroundTasksExtension(pi: ExtensionAPI): void {
   // Created before registerTools so the tools can resolve it lazily; the durable
@@ -36,7 +36,10 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
     },
   });
   initializeNavigatorPanels(pi);
-  pi.on("before_agent_start", (event) => ({ systemPrompt: appendExecutionPolicy(event.systemPrompt) }));
+  // Sections on a host that renders them; text only where it renders none.
+  // Returning a prompt on modern pi would set forceSystemPrompt, and the request
+  // would then carry a snapshot, so sections published after it never arrive.
+  pi.on("before_agent_start", (event) => deliverBackgroundTasksPrompt(event));
   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/prompt.ts

@@ -0,0 +1,72 @@
+/**
+ * The operational prompt this package owns: how to wait, and how to launch.
+ *
+ * Published as a named section so pi can diff it. It exists because the tool
+ * descriptions cannot carry it: a description explains one call, while the
+ * failure this prevents is choosing `sleep` over a watcher in the first place.
+ *
+ * Instructions only. No rationale, no worked examples, and no defaults that the
+ * tool schemas already state: the model has every schema in context, and repeated
+ * reference just spends prefix tokens on text it can already read.
+ */
+export const BACKGROUND_TASKS_SECTION = "background_tasks";
+
+import { EXECUTION_POLICY_TEXT, publishExecutionPolicy, supportsPromptSections } from "./shared-execution-policy.js";
+
+/** `sections` is optional because the repo typechecks against older pi typings. */
+export interface PromptSectionTarget {
+  sections?: Record<string, string>;
+}
+
+export const BACKGROUND_TASKS_PROMPT: string = [
+  "Background tasks: never wait in the foreground.",
+  "",
+  "- Never use foreground `sleep` to wait or poll, whether alone, before another command, or inside a loop. The sole permitted foreground sleep is at most 3 s immediately after `pkill`, `kill`, or `systemctl stop`, while the process exits.",
+  "- Use `bg_task_spawn` and `bg_task_watch` instead of `nohup`, `&`, or `disown`.",
+  "- Treat the wait, not the check, as the long part. Waiting for `gh pr checks` to pass is a `bg_task_watch`, not `sleep 300; gh pr checks`.",
+  "- Waiting on an external system (`gh run view`, `gh pr checks`, `mergify queue show`, a redeploy, a dev server, `cloud-init`): `bg_task_watch` with the check command and `success_when`. For a PR you just enqueued, `watch_delivery`.",
+  "- Waiting on your own long command (tests, build, migration): `bg_task_spawn`, then `wait_for_operations`. Do not sleep and re-read the log.",
+  "- Waiting for a server you just started: `bg_task_spawn` the server, then `bg_task_watch` on a readiness check (`curl -fsS ...`).",
+  "- Retry until a condition with one `bg_task_watch`, never `for i in ...; do ...; sleep N; done`.",
+  "- If a dependency is pending and no watcher is running, start `bg_task_watch`; do not loop short sleeps.",
+  "- Nothing here automatically diverts a foreground command. A sleep or monitor loop submitted through foreground `bash` blocks the turn.",
+  "- Omit `timeout_seconds` on `bg_task_spawn` unless you need a bound. Raise it on `bg_task_watch` for a wait longer than 15 minutes, and leave `callback` alone: do not poll.",
+  "- Write the check so a broken check is visible; do not end it with `exit 0` or `|| true`.",
+  "- Stop tasks you started for a turn-scoped purpose before finishing the turn.",
+].join("\n");
+
+/** Publish the guidance into `options.sections`; assignment keeps it idempotent across turns. */
+export function publishBackgroundTasksGuidance<T extends object>(options: T): T {
+  const target = options as PromptSectionTarget;
+  const sections = (target.sections ??= {});
+  sections[BACKGROUND_TASKS_SECTION] = BACKGROUND_TASKS_PROMPT;
+  return options;
+}
+
+/** What a handler receives; only these two fields are used. */
+export interface BeforeAgentStartEvent {
+  systemPrompt: string;
+  systemPromptOptions?: unknown;
+}
+
+/**
+ * Deliver this package's guidance on both kinds of host.
+ *
+ * Modern pi renders custom sections, so publishing keeps the prompt structured
+ * and lets pi diff it. Older pi (the packages declare support back to 0.84.4)
+ * renders no sections at all, so publishing there would silently deliver nothing;
+ * returning the text is the behaviour those hosts already had.
+ */
+export function deliverBackgroundTasksPrompt(event: BeforeAgentStartEvent): { systemPrompt: string } | undefined {
+  if (!supportsPromptSections(event.systemPromptOptions)) {
+    // Several packages carry the same policy, so appending blindly would print it
+    // once per publisher. The text path stays idempotent exactly as it used to be.
+    const policy = event.systemPrompt.includes(EXECUTION_POLICY_TEXT) ? "" : `${EXECUTION_POLICY_TEXT}\n\n`;
+    const guidance = event.systemPrompt.includes(BACKGROUND_TASKS_PROMPT) ? "" : BACKGROUND_TASKS_PROMPT;
+    return { systemPrompt: `${event.systemPrompt}\n\n${policy}${guidance}` };
+  }
+  const options = event.systemPromptOptions as { sections?: Record<string, string> };
+  publishExecutionPolicy(options);
+  publishBackgroundTasksGuidance(options);
+  return undefined;
+}

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

@@ -1,21 +1,61 @@
 // 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-wide scheduling guidance, vendored so standalone extensions share it.
+ *
+ * Published as a named system-prompt section, never as appended text. A
+ * `before_agent_start` handler that returns `systemPrompt` sets
+ * `forceSystemPrompt`, and a forced prompt is opaque to pi: `buildSystemPromptState`
+ * returns `{ content }` with no sections while `diffSystemPromptSections` keeps
+ * diffing the sections the request therefore never shows. The request carries a
+ * rendered snapshot, so any section published after that snapshot never reaches
+ * it, so every package that speaks here publishes a section.
+ */
+export const EXECUTION_POLICY_SECTION = "harness_execution_policy";
+
+/**
+ * The minimum shape this module needs. `sections` stays optional because this
+ * repo typechecks against older pi typings whose event options predate sections;
+ * the shipped runtime always supplies the map.
+ */
+export interface PromptSectionTarget {
+  sections?: Record<string, string>;
+}
+
+export const EXECUTION_POLICY_TEXT: string = [
   "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.",
+  "Before multi-unit work, identify ready, authorized, independent units, actual prerequisites, shared mutable resources, and capacity or availability constraints. Represent each independently verifiable deliverable as its own plan step; do not create dependencies 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.",
-  "Established command-only jobs and external waits belong to background operations, including in coordinator mode. Use bg_task_spawn for a long command and bg_task_watch for a repeated check; use watch_delivery for supported merge delivery so a stateful domain watcher observes the queue. A subagent assignment must require reasoning or implementation beyond launching and waiting. Workers retain their assigned validation: use supervised background tools and wait_for_operations to park, then resume the same conversation to interpret and acknowledge the terminal result. A linked external wait must have a registered observer and an execution owner. Continue independent work while it runs; a task launch or a completed parked attempt is not completion of the assignment.",
-  "If a worker hands back a command, the coordinator launches it through background tools with the supplied cwd and inspects its terminal result before claiming verification. Workers may run focused implementation checks; moving a command to a worker does not make it a background task.",
+  "If concurrency raises an unresolved material operational trade-off, ask the user once before the affected operations and 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. Inspect every launch receipt for failures or skipped work.",
+  "Established command-only jobs and external waits belong to background operations, including in coordinator mode. Use bg_task_spawn for a long command, bg_task_watch for a repeated check, and watch_delivery for supported merge delivery. A subagent assignment must require reasoning or implementation beyond launching and waiting. Workers retain their assigned validation: launch or watch, continue independent work, then park with wait_for_operations and inspect the terminal evidence on continuation. Continue independent work while it runs; a task launch is not completion of the assignment.",
+  "If a worker hands back a command, launch it through bg_task_spawn or bg_task_watch with the supplied cwd, and inspect its terminal result before claiming verification.",
   "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}`;
-}
+/**
+ * True when this pi runtime renders custom prompt sections.
+ *
+ * pi gained `systemPromptOptions.sections` after 0.84.4, and the packages here
+ * declare support back to 0.84.4. A section-only publisher is a silent no-op on
+ * an older host: the handler runs, the map is populated, and the prompt the model
+ * receives is unchanged. Callers must fall back to appending text instead.
+ */
+export function supportsPromptSections(options: unknown): boolean {
+  const sections = (options as { sections?: unknown } | undefined)?.sections;
+  return typeof sections === "object" && sections !== null;
+}
+
+/**
+ * Publish the policy into `options.sections`.
+ *
+ * Assignment, not concatenation: two packages publishing the same section write
+ * identical text, so load order cannot duplicate or drop it, and a repeated turn
+ * rewrites the same value so pi's section diff reports no change.
+ */
+export function publishExecutionPolicy<T extends object>(options: T): T {
+  const target = options as PromptSectionTarget;
+  const sections = (target.sections ??= {});
+  sections[EXECUTION_POLICY_SECTION] = EXECUTION_POLICY_TEXT;
+  return options;
+}

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

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

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

@@ -30,6 +30,7 @@ import {
 } from "./goal-state.js";
 import { continuationEvidence, type ContinuationEvidence } from "./continuation.js";
 import { currentPermissionHold, logicalPermissionBlockerKey, MAX_PERMISSION_BLOCKERS, MAX_PERMISSION_RECORDS, permissionHoldRecord, permissionInstruction, permissionRecord, reportedPermissionBlockers, reportedPermissionGap, type PermissionHold } from "./permission-hold.js";
+import { publishGoalGuidance } from "./prompt.js";
 import { observeGoalStall } from "./stall.js";
 import {
   flattenObjectiveForRail,
@@ -1360,12 +1361,12 @@ export default function (pi: ExtensionAPI): void {
         (permissions.blockers.length === 0 ? "\nBlocker evidence is unavailable. Stay held; do not invent a retry scope." : "") : "";
     // A held goal overrides workflow ownership without invoking or invalidating that workflow.
     if (permissionPrompt && goal?.status === "paused") {
-      return { systemPrompt: `${event.systemPrompt}\n\n${permissionPrompt}` };
+      return publishGoalGuidance(event, permissionPrompt);
     }
     const pausedInstruction = permissionPrompt || (goal?.status === "paused" && (goal.pauseReason === "interrupt" || goal.pauseReason === "handback")
       ? pausedGoalPrompt(goal, preferences.conversationalResume, !harnessPresent) : "");
     if (!isPokeable(goal) && !owner) {
-      return pausedInstruction ? { systemPrompt: `${event.systemPrompt}\n\n${pausedInstruction}` } : undefined;
+      return publishGoalGuidance(event, pausedInstruction);
     }
 
     const questionInstruction = snapshot.backgroundRunning
@@ -1379,31 +1380,28 @@ export default function (pi: ExtensionAPI): void {
       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.` };
+        return publishGoalGuidance(event, `Workflow ${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 publishGoalGuidance(event, `Workflow ${owner.name} is unavailable. Stop work and ask the user to restore or reinvoke the skill.`);
       }
-      return {
-        systemPrompt: `${event.systemPrompt}\n\n` +
-          (pausedInstruction
-            ? `${pausedInstruction}\n` + (permissionPrompt
-              ? "These permission constraints override the workflow instructions below.\n\n"
-              : "While the goal is paused, this overrides the workflow instructions below: do not advance the workflow until the goal is resumed.\n\n")
-            : "") +
-          `Active 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)
-            ? harnessPresent
-              ? "\n\nComplete the goal only after the workflow completion audit."
-              : `\n\nActive objective: ${goal.objective}. Complete it only after the workflow completion audit.`
-            : "") +
-          (questionInstruction ? `\n\n${questionInstruction.trim()}` : "") +
-          (heldInstruction ? `\n\n${heldInstruction}` : ""),
-      };
+      return publishGoalGuidance(
+        event,
+        pausedInstruction &&
+          `${pausedInstruction}\n` + (permissionPrompt
+            ? "These permission constraints override the workflow instructions below.\n\n"
+            : "While the goal is paused, this overrides the workflow instructions below: do not advance the workflow until the goal is resumed.\n\n"),
+        `Active 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) && (harnessPresent
+          ? "Complete the goal only after the workflow completion audit."
+          : `Active objective: ${goal.objective}. Complete it only after the workflow completion audit.`),
+        questionInstruction && questionInstruction.trim(),
+        heldInstruction,
+      );
     }
 
     if (!isPokeable(goal)) return;
@@ -1413,18 +1411,19 @@ export default function (pi: ExtensionAPI): void {
     if (harnessPresent) {
       // Harness owns the outcome text. Retain only the Goal-specific guidance
       // that the Outcome & Todo prompt cannot replace.
-      const retained = [heldInstruction, backgroundInstruction.trim(), questionInstruction.trim(), permissionPrompt]
-        .filter((part) => part.length > 0);
-      return retained.length > 0
-        ? { systemPrompt: `${event.systemPrompt}\n\n${retained.join("\n\n")}` }
-        : undefined;
-    }
-    return {
-      systemPrompt:
-        `${event.systemPrompt}\n\n` +
-        `Pi Better Goal active objective: ${goal.objective}. ${heldInstruction || "Keep working through clear low-risk next steps, and mark complete only after an evidence-backed completion audit."}${backgroundInstruction}${questionInstruction}` +
-        (permissionPrompt ? `\n\n${permissionPrompt}` : ""),
-    };
+      return publishGoalGuidance(
+        event,
+        heldInstruction,
+        backgroundInstruction.trim(),
+        questionInstruction.trim(),
+        permissionPrompt,
+      );
+    }
+    return publishGoalGuidance(
+      event,
+      `Pi Better Goal active objective: ${goal.objective}. ${heldInstruction || "Keep working through clear low-risk next steps, and mark complete only after an evidence-backed completion audit."}${backgroundInstruction}${questionInstruction}`,
+      permissionPrompt,
+    );
   });
 
   pi.on("agent_start", async (_event, ctx) => {

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

@@ -0,0 +1,53 @@
+/**
+ * Goal-owned system-prompt guidance.
+ *
+ * Published as a named section on hosts that render sections, never as a returned
+ * `systemPrompt` there: returning text sets `forceSystemPrompt`, and the request
+ * then carries an opaque rendered snapshot, so a section published afterwards
+ * never reaches the model.
+ *
+ * On older hosts (this package declares support back to pi 0.84.4) custom sections
+ * do not render at all, so the same text is appended instead. Publishing alone
+ * would silently deliver nothing on those versions.
+ */
+export const GOAL_SECTION = "goal";
+
+/** The minimum shape this module needs; both the event options and a test double satisfy it. */
+export interface PromptSectionTarget {
+  sections?: Record<string, string>;
+}
+
+/** What a handler receives; only these two fields are used. */
+export interface BeforeAgentStartEvent {
+  systemPrompt: string;
+  systemPromptOptions?: unknown;
+}
+
+/** Mirrors `supportsPromptSections` in the vendored execution policy. */
+function rendersSections(options: unknown): boolean {
+  const sections = (options as { sections?: unknown } | undefined)?.sections;
+  return typeof sections === "object" && sections !== null;
+}
+
+/**
+ * Deliver guidance, choosing the channel this host understands.
+ *
+ * Appending within one turn is safe: pi normalizes a fresh options object for
+ * every `before_agent_start`, so this never accumulates between requests, and
+ * within a turn the parts belong together and keep their order.
+ */
+export function publishGoalGuidance(
+  event: BeforeAgentStartEvent,
+  ...parts: Array<string | undefined | false>
+): { systemPrompt: string } | undefined {
+  const text = parts.filter((part): part is string => typeof part === "string" && part.trim().length > 0).join("\n\n");
+  if (!text) return undefined;
+  if (!rendersSections(event.systemPromptOptions)) {
+    return { systemPrompt: `${event.systemPrompt}\n\n${text}` };
+  }
+  const target = event.systemPromptOptions as PromptSectionTarget;
+  const sections = (target.sections ??= {});
+  const existing = sections[GOAL_SECTION];
+  sections[GOAL_SECTION] = existing ? `${existing}\n\n${text}` : text;
+  return undefined;
+}

package/node_modules/pi-better-subagents/child-ownership.ts

@@ -1,8 +1,10 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { parse } from "shell-quote";
 import { STEER_FILE_ENV } from "./child-steer.ts";
+import { supportsPromptSections } from "./shared-execution-policy.ts";
 
 export const WORKER_HANDOFF = "Worker ownership: complete your assigned implementation or diagnosis, run focused checks, push only when authorized, write the requested result, then return. Pending CI is a handoff, not a failed implementation or a CI pass. The coordinator owns CI/PR monitoring, review scheduling, readiness, enqueueing and merge. Do not start external delivery watchers or background monitoring. Short status reads and failed-log retrieval for diagnosis are allowed. Legitimate local tests and builds may run to completion within their command limits. Use Bash for short diagnostic commands and focused checks needed to implement the change. When supervised background tools are available, retain ownership of assigned validation: launch a known long command with bg_task_spawn or repeated observation with bg_task_watch, continue independent work, then call wait_for_operations to park when no independent work remains. On continuation, inspect the operation's terminal evidence and acknowledge its interpretation before continuing the assignment. Parking is a saved-conversation dependency, not a request for the parent model to relay commands or results. An explicit restricted tool loadout may omit background support; return the exact command, cwd, required environment variable names (never secret values), current evidence and remaining validation to the coordinator. Do not emulate background execution with polling, sleep loops, nohup or shell detachment. Established command-only operations and external delivery monitoring belong to the coordinator's background tools.";
+export const WORKER_HANDOFF_SECTION = "worker_handoff";
 const REFUSAL = "Worker ownership: CI/PR monitoring belongs to the coordinator. Return the PR/run ID, pushed HEAD and current evidence with CI pending; do not retry the watcher through another tool or script. Local tests/builds and short diagnostic status/log reads remain allowed.";
 const WATCH_SCRIPTS = new Set(["watch-pr-delivery.mjs", "watch-delivery.mjs", "watch-candidate-delivery.mjs"]);
 const nameOf = (value: string) => value.replaceAll("\\", "/").split("/").at(-1)!.replace(/\.exe$/i, "");
@@ -133,7 +135,18 @@ export function workerMonitoringRefusal(toolName: string, input: unknown): strin
 export default function childOwnership(pi: Pick<ExtensionAPI, "on">, env: NodeJS.ProcessEnv = process.env): void {
     // This marker is supplied by the parent on every child launch, including clean/unsandboxed runs.
     if (!env[STEER_FILE_ENV]) return;
-    pi.on("before_agent_start", (event) => ({ systemPrompt: `${event.systemPrompt}\n\n${WORKER_HANDOFF}` }));
+    // A section on hosts that render them; appended text on hosts that do not.
+    // Returning a prompt on a modern host would set forceSystemPrompt, and the
+    // request would carry a snapshot, so later sections never arrive.
+    pi.on("before_agent_start", (event) => {
+        if (!supportsPromptSections(event.systemPromptOptions)) {
+            return { systemPrompt: `${event.systemPrompt}\n\n${WORKER_HANDOFF}` };
+        }
+        const options = event.systemPromptOptions as { sections?: Record<string, string> };
+        const sections = (options.sections ??= {});
+        sections[WORKER_HANDOFF_SECTION] = WORKER_HANDOFF;
+        return undefined;
+    });
     pi.on("tool_call", (event) => {
         const reason = workerMonitoringRefusal(event.toolName, event.input);
         if (reason) return { block: true, reason };

package/node_modules/pi-better-subagents/effective-settings.ts

@@ -1,6 +1,8 @@
 import { createHash } from "node:crypto";
 import { delegationPrompt, type DelegationMode } from "./delegation.ts";
 
+import { EXECUTION_POLICY_TEXT, publishExecutionPolicy, supportsPromptSections } from "./shared-execution-policy.ts";
+
 export const SUBAGENT_SETTINGS_CONTEXT = "pi-better-subagents-settings";
 
 export interface EffectiveSubagentSettings {
@@ -48,18 +50,42 @@ export function formatSubagentSettings(settings: EffectiveSubagentSettings): str
 }
 
 /**
- * Append the delegation policy to the end of the system prompt.
+ * Publish the delegation policy as its own prompt section.
  *
- * The system prompt is not part of the compaction window, so the policy survives
- * a summary that rewrites the conversation. It is also part of the cached
- * prefix, so it costs nothing per request while it stays unchanged.
+ * A section survives a summary that rewrites the conversation without being
+ * appended text, and it is part of the cached prefix, so it costs nothing per
+ * request while it stays unchanged. Assignment is idempotent: a repeated turn
+ * rewrites the same value and pi's section diff reports no change.
  *
  * Nothing volatile goes in here: live occupancy would rewrite the cached prefix
  * on every run, and admission rechecks capacity at spawn anyway.
  */
-export function appendSubagentSettings(systemPrompt: string, settings: EffectiveSubagentSettings): string {
-    const policy = formatSubagentSettings(settings);
-    return systemPrompt.includes(policy) ? systemPrompt : `${systemPrompt}\n\n${policy}`;
+export const SUBAGENT_SETTINGS_SECTION = "subagents";
+
+/** `sections` is optional because the repo typechecks against older pi typings. */
+export interface PromptSectionTarget {
+    sections?: Record<string, string>;
+}
+
+/**
+ * Published with the settings block: the block is the authority on delegation, so
+ * the sentence that says so has to sit beside it rather than in a separate section
+ * whose position would depend on package load order.
+ *
+ * The note must not say the block is at the end of the prompt. Custom sections
+ * render in publication order, so Background Tasks and Goal publish after this one;
+ * naming its own section keeps the sentence true whatever the load order.
+ */
+const SUBAGENT_DELEGATION_NOTE = "Treat the Subagent settings block in this section as the authoritative delegation mode and cap. Its delegation guidance replaces earlier mode-specific guidance, including guidance in a plan. Live occupancy is not pushed into context: inspect subagent_settings when it matters, and never treat the concurrency limit as a target number of agents.";
+
+export function publishSubagentSettings<T extends object>(options: T, settings: EffectiveSubagentSettings): T {
+    // Note first, block last inside the section: the note introduces the block it
+    // describes. Section order in the prompt is a separate concern, decided by
+    // publication order, so the note never claims a position in the whole prompt.
+    const target = options as PromptSectionTarget;
+    const sections = (target.sections ??= {});
+    sections[SUBAGENT_SETTINGS_SECTION] = `${SUBAGENT_DELEGATION_NOTE}\n\n${formatSubagentSettings(settings)}`;
+    return options;
 }
 
 export function subagentSettingsTool(Type: any, read: () => EffectiveSubagentSettings) {
@@ -81,4 +107,31 @@ export function subagentSettingsTool(Type: any, read: () => EffectiveSubagentSet
                 details: settings, structuredContent: settings };
         },
     };
-}
+}
+/** What a handler receives; only these two fields are used. */
+export interface BeforeAgentStartEvent {
+    systemPrompt: string;
+    systemPromptOptions?: unknown;
+}
+
+/**
+ * Deliver the policy and the settings on both kinds of host.
+ *
+ * pi before 0.84.4+ renders no custom sections, so publishing alone would
+ * deliver nothing on a host this package still declares support for. There the
+ * guidance is appended as text, which is what those hosts did before sections.
+ */
+export function deliverSubagentPrompt(event: BeforeAgentStartEvent, settings: EffectiveSubagentSettings): { systemPrompt: string } | undefined {
+    if (!supportsPromptSections(event.systemPromptOptions)) {
+        // Both packages carry this policy, so appending blindly would print it
+        // once per publisher; keep the text path idempotent as it used to be.
+        const policy = event.systemPrompt.includes(EXECUTION_POLICY_TEXT) ? "" : `${EXECUTION_POLICY_TEXT}\n\n`;
+        const block = `${SUBAGENT_DELEGATION_NOTE}\n\n${formatSubagentSettings(settings)}`;
+        const guidance = event.systemPrompt.includes(block) ? "" : block;
+        return { systemPrompt: `${event.systemPrompt}\n\n${policy}${guidance}` };
+    }
+    const options = event.systemPromptOptions as PromptSectionTarget;
+    publishExecutionPolicy(options);
+    publishSubagentSettings(options, settings);
+    return undefined;
+}

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

@@ -38,7 +38,7 @@ import { selectSessionByName } from "./session-selection.ts";
 import { isWithinWorkspace } from "./workspace-scope.ts";
 import { loadConfig, writeDelegationMode, writeSubagentSettings, isConcurrencyCap, normalizeConcurrencyCap, normalizeTools, resolveExtensionPath, configPath, selfDir, SAFE_DEFAULT_TOOLS, SAFE_CLEAN_TOOLS } from "./config.ts";
 import { createSubagentSettingsPage } from "./settings-page.ts";
-import { appendSubagentSettings, effectiveSubagentSettings, formatSubagentSettings, subagentSettingsTool, SUBAGENT_SETTINGS_CONTEXT } from "./effective-settings.ts";
+import { deliverSubagentPrompt, effectiveSubagentSettings, formatSubagentSettings, subagentSettingsTool, SUBAGENT_SETTINGS_CONTEXT } from "./effective-settings.ts";
 import { STEER_FILE_ENV, readSteerReceipt } from "./child-steer.ts";
 import {
     decideTiming,
@@ -56,7 +56,6 @@ import {
 } from "./timing.ts";
 import { readAppendedLines, type LogCursor } from "./log-cursor.ts";
 import { DELEGATION_MODES, DELEGATION_MODE_REQUEST, isDelegationMode, normalizeDelegationMode, type DelegationMode } from "./delegation.ts";
-import { appendExecutionPolicy } from "./shared-execution-policy.ts";
 import { resolveChildClosure, resolveChildLaunch, configSnapshot } from "./child-dependencies.mjs";
 import { PREFLIGHT_ENV } from "./child-preflight.mjs";
 import { resolveExtensions, extensionArgs } from "./extensions.ts";
@@ -3602,12 +3601,10 @@ export default function (pi: ExtensionAPI) {
     const discoveryTool = agentOperations.createDiscoveryTool(Type as never);
     pi.registerTool(discoveryTool as Parameters<ExtensionAPI["registerTool"]>[0]);
 
-    pi.on("before_agent_start", (event) => ({
-        systemPrompt: appendSubagentSettings(
-            `${appendExecutionPolicy(event.systemPrompt)}\n\nTreat the Subagent settings block at the end of this prompt as the authoritative delegation mode and cap. Its delegation guidance replaces earlier mode-specific guidance, including guidance in a plan. Live occupancy is not pushed into context: inspect subagent_settings when it matters, and never treat the concurrency limit as a target number of agents.`,
-            effectiveSettings(),
-        ),
-    }));
+    // Sections on a host that renders them; text only where it renders none.
+    // Returning a prompt on modern pi would set forceSystemPrompt, and the request
+    // would then carry a snapshot, so sections published after it never arrive.
+    pi.on("before_agent_start", (event) => deliverSubagentPrompt(event, effectiveSettings()));
 
     // ---- live-status lifecycle -----------------------------------------
     pi.on("agent_start", async (_event, ctx) => {

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.27.1",
+  "version": "0.27.2",
   "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

@@ -1,21 +1,61 @@
 // 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-wide scheduling guidance, vendored so standalone extensions share it.
+ *
+ * Published as a named system-prompt section, never as appended text. A
+ * `before_agent_start` handler that returns `systemPrompt` sets
+ * `forceSystemPrompt`, and a forced prompt is opaque to pi: `buildSystemPromptState`
+ * returns `{ content }` with no sections while `diffSystemPromptSections` keeps
+ * diffing the sections the request therefore never shows. The request carries a
+ * rendered snapshot, so any section published after that snapshot never reaches
+ * it, so every package that speaks here publishes a section.
+ */
+export const EXECUTION_POLICY_SECTION = "harness_execution_policy";
+
+/**
+ * The minimum shape this module needs. `sections` stays optional because this
+ * repo typechecks against older pi typings whose event options predate sections;
+ * the shipped runtime always supplies the map.
+ */
+export interface PromptSectionTarget {
+  sections?: Record<string, string>;
+}
+
+export const EXECUTION_POLICY_TEXT: string = [
   "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.",
+  "Before multi-unit work, identify ready, authorized, independent units, actual prerequisites, shared mutable resources, and capacity or availability constraints. Represent each independently verifiable deliverable as its own plan step; do not create dependencies 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.",
-  "Established command-only jobs and external waits belong to background operations, including in coordinator mode. Use bg_task_spawn for a long command and bg_task_watch for a repeated check; use watch_delivery for supported merge delivery so a stateful domain watcher observes the queue. A subagent assignment must require reasoning or implementation beyond launching and waiting. Workers retain their assigned validation: use supervised background tools and wait_for_operations to park, then resume the same conversation to interpret and acknowledge the terminal result. A linked external wait must have a registered observer and an execution owner. Continue independent work while it runs; a task launch or a completed parked attempt is not completion of the assignment.",
-  "If a worker hands back a command, the coordinator launches it through background tools with the supplied cwd and inspects its terminal result before claiming verification. Workers may run focused implementation checks; moving a command to a worker does not make it a background task.",
+  "If concurrency raises an unresolved material operational trade-off, ask the user once before the affected operations and 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. Inspect every launch receipt for failures or skipped work.",
+  "Established command-only jobs and external waits belong to background operations, including in coordinator mode. Use bg_task_spawn for a long command, bg_task_watch for a repeated check, and watch_delivery for supported merge delivery. A subagent assignment must require reasoning or implementation beyond launching and waiting. Workers retain their assigned validation: launch or watch, continue independent work, then park with wait_for_operations and inspect the terminal evidence on continuation. Continue independent work while it runs; a task launch is not completion of the assignment.",
+  "If a worker hands back a command, launch it through bg_task_spawn or bg_task_watch with the supplied cwd, and inspect its terminal result before claiming verification.",
   "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}`;
-}
+/**
+ * True when this pi runtime renders custom prompt sections.
+ *
+ * pi gained `systemPromptOptions.sections` after 0.84.4, and the packages here
+ * declare support back to 0.84.4. A section-only publisher is a silent no-op on
+ * an older host: the handler runs, the map is populated, and the prompt the model
+ * receives is unchanged. Callers must fall back to appending text instead.
+ */
+export function supportsPromptSections(options: unknown): boolean {
+  const sections = (options as { sections?: unknown } | undefined)?.sections;
+  return typeof sections === "object" && sections !== null;
+}
+
+/**
+ * Publish the policy into `options.sections`.
+ *
+ * Assignment, not concatenation: two packages publishing the same section write
+ * identical text, so load order cannot duplicate or drop it, and a repeated turn
+ * rewrites the same value so pi's section diff reports no change.
+ */
+export function publishExecutionPolicy<T extends object>(options: T): T {
+  const target = options as PromptSectionTarget;
+  const sections = (target.sections ??= {});
+  sections[EXECUTION_POLICY_SECTION] = EXECUTION_POLICY_TEXT;
+  return options;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-harness",
-  "version": "0.40.1",
+  "version": "0.40.2",
   "description": "Pi extension bundle for a write sandbox, subagents, background tasks, SSH, goals, model routing, and Outcome & Todo.",
   "license": "MIT",
   "type": "module",
@@ -55,13 +55,13 @@
     "test": "node --import tsx --import ../../scripts/isolate-registry.mjs --test test/*.test.mjs test/*.test.ts test/task-context/*.test.ts"
   },
   "dependencies": {
-    "pi-better-background-tasks": "0.14.1",
-    "pi-better-goal": "0.12.0",
+    "pi-better-background-tasks": "0.14.2",
+    "pi-better-goal": "0.12.1",
     "pi-better-model-router": "0.1.2",
     "pi-ollama-cloud": "0.13.1",
     "pi-better-sandbox": "0.14.1",
     "pi-better-ssh": "0.1.4",
-    "pi-better-subagents": "0.27.1",
+    "pi-better-subagents": "0.27.2",
     "proper-lockfile": "^4.1.2",
     "shell-quote": "1.12.0",
     "smol-toml": "1.9.0",

package/extensions/task-context/shared-execution-policy.ts

@@ -1,19 +0,0 @@
-// 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}`;
-}