pi-better-harness 0.40.0 → 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.0",
+  "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/navigator-provider.ts

@@ -101,8 +101,12 @@ const provider: BackgroundWorkProvider = {
   },
   onVisibleChanged: (notify) => {
     const offMeta = onMetaChanged(notify);
-    const offDurable = getObservedWaitHost(piRef)?.onDurableTaskChange(notify);
+    const offDurable = getObservedWaitHost(piRef)?.onDurableTaskChange(() => {
+      invalidateDurableProjection();
+      notify();
+    });
     return () => {
+      invalidateDurableProjection();
       offMeta();
       offDurable?.();
     };
@@ -113,13 +117,30 @@ function navigatorHost() {
   return piRef ? getObservedWaitHost(piRef) : undefined;
 }
 
+/**
+ * One refresh asks for {@link provider.visibleCount} and then {@link provider.listRows},
+ * and a detail view asks again. Rebuilding the projection re-reads every durable
+ * record, so a single paint would pay for the same list up to three times. Hold
+ * one result per paint window; a durable-change notification clears it.
+ */
+const PROJECTION_MEMO_MS = 250;
+let projectionMemo: { at: number; tasks: DurableTaskProjection[] } | undefined;
+
+function invalidateDurableProjection(): void {
+  projectionMemo = undefined;
+}
+
 function visibleDurableTasks(now = Date.now()): DurableTaskProjection[] {
   const active = activeNavigatorOrigin;
   const host = navigatorHost();
   if (!active || !host) return [];
+  if (projectionMemo && now - projectionMemo.at < PROJECTION_MEMO_MS) {
+    return projectionMemo.tasks.filter((task) => !isExpiredDurableRow(task, now));
+  }
   const listed = host.listDurableTasks(active, { retentionMs: TERMINAL_NAVIGATOR_RETENTION_MS });
-  return listed
-    .filter((task) => task.dismissedAt === undefined && !isExpiredDurableRow(task, now));
+  const tasks = listed.filter((task) => task.dismissedAt === undefined);
+  projectionMemo = { at: now, tasks };
+  return tasks.filter((task) => !isExpiredDurableRow(task, now));
 }
 
 function durableTask(id: string): DurableTaskProjection | undefined {

package/node_modules/pi-better-background-tasks/src/observed-waits.ts

@@ -1366,8 +1366,10 @@ export class ObservedWaitHost {
 
   private projectDurable(operation: OperationRecord, now: number): DurableTaskProjection | undefined {
     const context = this.launchContext(operation.taskId);
+    // Projection is the rendering path: a snapshot reads the durable records
+    // without taking the cross-process fence or spawning `ps`.
     const inspection = LOCAL_DURABLE_ID.test(operation.taskId)
-      ? (() => { try { return this.supervisor.inspect(operation.taskId, { recordLost: false }); } catch { return undefined; } })()
+      ? (() => { try { return this.supervisor.snapshot(operation.taskId); } catch { return undefined; } })()
       : undefined;
     const storeStatus = operation.terminalRevision > 0 ? this.statusOf(operation.operationId) : undefined;
     const status: SupervisorTaskStatus = inspection?.terminal ? inspection.status : storeStatus ?? inspection?.status ?? "running";

package/node_modules/pi-better-background-tasks/src/process-identity.ts

@@ -1,41 +1,118 @@
 import { execFileSync } from "node:child_process";
 
-const selfStartToken = readProcessStartToken(process.pid);
+/**
+ * Process start-token reads.
+ *
+ * `ps` is a process spawn. Reading it on a rendering path — once per task, per
+ * frame, for every terminal task kept in the panel — is a measurable CPU drain
+ * on its own, and it competes with the very commands the panel is showing.
+ *
+ * Two rules keep that bounded:
+ *
+ * 1. A pid's start token is immutable for the life of that pid, so a short-lived
+ *    memo is safe. Entries expire so a recycled pid is re-read rather than
+ *    mistaking the previous owner's token for the current one, and failures are
+ *    memoized too, so a pid that cannot be read is not retried on every frame.
+ * 2. Callers that decide to *signal* a pid can ask for a fresh read. Liveness
+ *    display may use the memo; authorization may not.
+ */
 
-export function currentProcessStartToken(): string | undefined {
-  return selfStartToken;
+/** How long one pid→token answer is trusted. Short enough to bound pid reuse. */
+const TOKEN_MEMO_TTL_MS = 1_000;
+/** Bound on memo entries; the panel is small, but a long session is not. */
+const TOKEN_MEMO_MAX_ENTRIES = 512;
+
+interface TokenMemoEntry {
+    token: string | undefined;
+    readAt: number;
+}
+
+const tokenMemo = new Map<number, TokenMemoEntry>();
+
+function readTokenUncached(pid: number): string | undefined {
+    if (!Number.isInteger(pid) || pid <= 0 || process.platform === "win32") return undefined;
+    try {
+        const output = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 2_000,
+        }).trim();
+        return output || undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+function remember(pid: number, token: string | undefined, now: number): void {
+    if (tokenMemo.size >= TOKEN_MEMO_MAX_ENTRIES) {
+        // Drop expired entries first; only evict live ones if that was not enough.
+        for (const [candidate, entry] of tokenMemo) {
+            if (now - entry.readAt >= TOKEN_MEMO_TTL_MS) tokenMemo.delete(candidate);
+        }
+        if (tokenMemo.size >= TOKEN_MEMO_MAX_ENTRIES) {
+            const oldest = tokenMemo.keys().next();
+            if (!oldest.done) tokenMemo.delete(oldest.value);
+        }
+    }
+    tokenMemo.set(pid, { token, readAt: now });
 }
 
+/**
+ * Start token for `pid`, memoized for {@link TOKEN_MEMO_TTL_MS}.
+ *
+ * Suitable for liveness and display. A caller that is about to send a signal
+ * must use {@link readProcessStartTokenFresh} instead.
+ */
 export function readProcessStartToken(pid: number): string | undefined {
-  if (!Number.isInteger(pid) || pid <= 0 || process.platform === "win32") return undefined;
-  try {
-    const output = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
-      timeout: 2_000,
-    }).trim();
-    return output || undefined;
-  } catch {
-    return undefined;
-  }
+    if (!Number.isInteger(pid) || pid <= 0 || process.platform === "win32") return undefined;
+    const now = Date.now();
+    const entry = tokenMemo.get(pid);
+    if (entry && now - entry.readAt < TOKEN_MEMO_TTL_MS) return entry.token;
+    const token = readTokenUncached(pid);
+    remember(pid, token, now);
+    return token;
+}
+
+/**
+ * Start token for `pid`, always read from the OS.
+ *
+ * Used where the answer authorizes a signal, so a recycled pid cannot inherit
+ * a memoized identity.
+ */
+export function readProcessStartTokenFresh(pid: number): string | undefined {
+    if (!Number.isInteger(pid) || pid <= 0 || process.platform === "win32") return undefined;
+    const token = readTokenUncached(pid);
+    remember(pid, token, Date.now());
+    return token;
+}
+
+/** Drop every memoized identity. Tests and reloads start from a clean slate. */
+export function clearProcessIdentityMemo(): void {
+    tokenMemo.clear();
+}
+
+const selfStartToken = readTokenUncached(process.pid);
+
+export function currentProcessStartToken(): string | undefined {
+    return selfStartToken;
 }
 
 export function processIdentityAlive(
-  pid: number | undefined,
-  recordedStartToken?: string,
-  recordedAt?: number,
+    pid: number | undefined,
+    recordedStartToken?: string,
+    recordedAt?: number,
 ): boolean {
-  if (!pid || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "EPERM") return false;
-  }
-  const current = readProcessStartToken(pid);
-  if (recordedStartToken && current) return recordedStartToken === current;
-  if (!recordedStartToken && current && recordedAt !== undefined) {
-    const currentStartedAt = Date.parse(current);
-    if (Number.isFinite(currentStartedAt) && currentStartedAt > recordedAt + 2_000) return false;
-  }
-  return true;
-}
+    if (!pid || pid <= 0) return false;
+    try {
+        process.kill(pid, 0);
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EPERM") return false;
+    }
+    const current = readProcessStartToken(pid);
+    if (recordedStartToken && current) return recordedStartToken === current;
+    if (!recordedStartToken && current && recordedAt !== undefined) {
+        const currentStartedAt = Date.parse(current);
+        if (Number.isFinite(currentStartedAt) && currentStartedAt > recordedAt + 2_000) return false;
+    }
+    return true;
+}

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-background-tasks/src/supervisor/generated/process-identity.mjs

@@ -2,11 +2,28 @@
 // Do not edit: change the source and re-run the emitter (a drift test enforces this).
 
 import { execFileSync } from "node:child_process";
-const selfStartToken = readProcessStartToken(process.pid);
-export function currentProcessStartToken() {
-    return selfStartToken;
-}
-export function readProcessStartToken(pid) {
+/**
+ * Process start-token reads.
+ *
+ * `ps` is a process spawn. Reading it on a rendering path — once per task, per
+ * frame, for every terminal task kept in the panel — is a measurable CPU drain
+ * on its own, and it competes with the very commands the panel is showing.
+ *
+ * Two rules keep that bounded:
+ *
+ * 1. A pid's start token is immutable for the life of that pid, so a short-lived
+ *    memo is safe. Entries expire so a recycled pid is re-read rather than
+ *    mistaking the previous owner's token for the current one, and failures are
+ *    memoized too, so a pid that cannot be read is not retried on every frame.
+ * 2. Callers that decide to *signal* a pid can ask for a fresh read. Liveness
+ *    display may use the memo; authorization may not.
+ */
+/** How long one pid→token answer is trusted. Short enough to bound pid reuse. */
+const TOKEN_MEMO_TTL_MS = 1_000;
+/** Bound on memo entries; the panel is small, but a long session is not. */
+const TOKEN_MEMO_MAX_ENTRIES = 512;
+const tokenMemo = new Map();
+function readTokenUncached(pid) {
     if (!Number.isInteger(pid) || pid <= 0 || process.platform === "win32")
         return undefined;
     try {
@@ -21,6 +38,59 @@ export function readProcessStartToken(pid) {
         return undefined;
     }
 }
+function remember(pid, token, now) {
+    if (tokenMemo.size >= TOKEN_MEMO_MAX_ENTRIES) {
+        // Drop expired entries first; only evict live ones if that was not enough.
+        for (const [candidate, entry] of tokenMemo) {
+            if (now - entry.readAt >= TOKEN_MEMO_TTL_MS)
+                tokenMemo.delete(candidate);
+        }
+        if (tokenMemo.size >= TOKEN_MEMO_MAX_ENTRIES) {
+            const oldest = tokenMemo.keys().next();
+            if (!oldest.done)
+                tokenMemo.delete(oldest.value);
+        }
+    }
+    tokenMemo.set(pid, { token, readAt: now });
+}
+/**
+ * Start token for `pid`, memoized for {@link TOKEN_MEMO_TTL_MS}.
+ *
+ * Suitable for liveness and display. A caller that is about to send a signal
+ * must use {@link readProcessStartTokenFresh} instead.
+ */
+export function readProcessStartToken(pid) {
+    if (!Number.isInteger(pid) || pid <= 0 || process.platform === "win32")
+        return undefined;
+    const now = Date.now();
+    const entry = tokenMemo.get(pid);
+    if (entry && now - entry.readAt < TOKEN_MEMO_TTL_MS)
+        return entry.token;
+    const token = readTokenUncached(pid);
+    remember(pid, token, now);
+    return token;
+}
+/**
+ * Start token for `pid`, always read from the OS.
+ *
+ * Used where the answer authorizes a signal, so a recycled pid cannot inherit
+ * a memoized identity.
+ */
+export function readProcessStartTokenFresh(pid) {
+    if (!Number.isInteger(pid) || pid <= 0 || process.platform === "win32")
+        return undefined;
+    const token = readTokenUncached(pid);
+    remember(pid, token, Date.now());
+    return token;
+}
+/** Drop every memoized identity. Tests and reloads start from a clean slate. */
+export function clearProcessIdentityMemo() {
+    tokenMemo.clear();
+}
+const selfStartToken = readTokenUncached(process.pid);
+export function currentProcessStartToken() {
+    return selfStartToken;
+}
 export function processIdentityAlive(pid, recordedStartToken, recordedAt) {
     if (!pid || pid <= 0)
         return false;

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

@@ -376,9 +376,22 @@ class Supervisor implements LocalSupervisor {
     const command = readCommandRecord(this.directory, taskId).value;
     const stop = readStopRequest(this.directory, taskId);
     const cleanup = readCleanupRecord(this.directory, taskId);
+    // Reading a process start token spawns `ps`. A task that already published a
+    // terminal/lost record cannot change state again, so its liveness only
+    // matters to the one caller that may still act on a surviving command group
+    // (`stop`). Every other reader would pay for an answer it does not use, once
+    // per task per panel frame. Probe only when that authority is actually needed.
+    const needsLiveness = result === undefined && lostRecord === undefined
+      ? true
+      : result !== undefined && result.groupCleanup === "unproven"
+        || lostRecord !== undefined;
     // One identity source per instance: liveness and signalling agree.
-    const claimAlive = claim ? identityAlive(claim.pid, claim.pidStartTime, claim.claimedAt, this.readToken) : false;
-    const commandAlive = command ? identityAlive(command.pid, command.pidStartTime, command.startedAt, this.readToken) : false;
+    const claimAlive = needsLiveness && claim
+      ? identityAlive(claim.pid, claim.pidStartTime, claim.claimedAt, this.readToken)
+      : false;
+    const commandAlive = needsLiveness && command
+      ? identityAlive(command.pid, command.pidStartTime, command.startedAt, this.readToken)
+      : false;
 
     // A published terminal/lost record needs no fence. Anything else is decided
     // under the fence, so a `lost` attestation and a claim cannot both win.
@@ -426,6 +439,67 @@ class Supervisor implements LocalSupervisor {
     };
   }
 
+  /**
+   * Read-only projection for rendering: no fence, no lost publication, no `ps`.
+   *
+   * `inspect` is the authoritative path and pays for that authority — a
+   * cross-process SQLite fence and a process-identity probe per recorded pid.
+   * A panel asks per task per frame, so it reads what the records already say.
+   */
+  snapshot(taskId: string): SupervisorInspection | undefined {
+    const launchRead = readLaunchRecord(this.directory, taskId);
+    if (launchRead.missing) return undefined;
+    if (!launchRead.value) {
+      throw new Error(`Unreadable supervisor launch record for ${taskId}: ${launchRead.error}`);
+    }
+    const launch = launchRead.value;
+    const paths = supervisorPaths(this.directory, taskId);
+    const result = readTerminalRecord(this.directory, taskId).value;
+    const lostRecord = readLostRecord(this.directory, taskId).value;
+    const claim = readClaimRecord(this.directory, taskId).value;
+    const command = readCommandRecord(this.directory, taskId).value;
+    const stop = readStopRequest(this.directory, taskId);
+    const cleanup = readCleanupRecord(this.directory, taskId);
+    const status: SupervisorTaskStatus = result
+      ? (result.status as SupervisorTaskStatus)
+      : lostRecord
+        ? "lost"
+        : claim
+          ? "running"
+          : "starting";
+    return {
+      taskId,
+      token: launch.token,
+      kind: launch.kind,
+      status,
+      terminal: result !== undefined || lostRecord !== undefined,
+      launch: launchSummary(launch),
+      // Liveness is deliberately not asserted here: a snapshot never spawns `ps`.
+      ...(claim === undefined
+        ? {}
+        : { claim: { pid: claim.pid, pidStartTime: claim.pidStartTime, claimedAt: claim.claimedAt, alive: false } }),
+      ...(command === undefined
+        ? {}
+        : {
+          command: {
+            pid: command.pid,
+            pgid: command.pgid,
+            pidStartTime: command.pidStartTime,
+            startedAt: command.startedAt,
+            attempt: command.attempt ?? 1,
+            alive: false,
+          },
+        }),
+      ...(result === undefined ? {} : { result }),
+      ...(lostRecord === undefined ? {} : { lost: lostRecord }),
+      ...(cleanup === undefined ? {} : { cleanup }),
+      ...(stop === undefined ? {} : { stopRequestedAt: stop.requestedAt }),
+      taskDir: paths.dir,
+      logs: { stdout: paths.stdout, stderr: paths.stderr, events: paths.events },
+      observedAt: Date.now(),
+    };
+  }
+
   /**
    * Decide the state of a launch with no terminal result, under the cross-process
    * fence. This is the only place a `lost` record is published, so it can never

package/node_modules/pi-better-background-tasks/src/supervisor/types.ts

@@ -380,5 +380,15 @@ export interface LocalSupervisorOptions {
 export interface LocalSupervisor {
   start(options: SupervisorStartOptions): Promise<SupervisorStartResult>;
   inspect(taskId: string, options?: SupervisorInspectOptions): SupervisorInspection | undefined;
+  /**
+   * Read-only projection of the durable records: no state fence, no lost
+   * publication and no process-identity probe.
+   *
+   * This is the rendering path. `inspect` may take a cross-process SQLite fence
+   * and spawn `ps` per task, which must not happen once per task per frame. A
+   * snapshot reports what the records already say — `running` for a claim,
+   * `starting` before one — and leaves reconciliation to the caller's cadence.
+   */
+  snapshot(taskId: string): SupervisorInspection | undefined;
   stop(taskId: string, options?: SupervisorStopOptions): Promise<SupervisorStopResult | undefined>;
 }

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 {
@@ -28,19 +30,64 @@ export function effectiveSubagentSettings(
 }
 
 export function formatSubagentSettings(settings: EffectiveSubagentSettings): string {
+    const manual = settings.delegationMode === "manual";
+    const capacity = manual
+        ? "The limit is a ceiling, not a target. In manual mode it bounds only work the user or an active workflow explicitly delegates; no slot count is an invitation to launch work."
+        : "The limit is a ceiling, not a target. Launch ready, independent, useful work when a suitable subagent is available.";
+    // No occupancy counters here. This text is injected into the conversation and
+    // may only ever be appended to, so anything volatile would force either a
+    // rewrite of already-sent content (which invalidates the provider's cached
+    // prefix) or one more copy per change. Admission rechecks capacity at the
+    // spawn anyway; live counts stay available through the subagent_settings tool.
     return [
         `Subagent settings: revision ${settings.revision}`,
         `Delegation: ${settings.delegationMode} (${settings.sources.delegationMode})`,
         `Concurrency limit: ${settings.maxConcurrent} (${settings.sources.maxConcurrent})`,
-        `Running: ${settings.runningCount}; reserved: ${settings.pendingCount}`,
-        `Occupied slots: ${settings.occupiedSlots}`,
-        `Available slots: ${settings.availableSlots}`,
-        "The limit is a ceiling, not a target. Launch ready, independent, useful work within available capacity. " +
-            "This is a point-in-time snapshot; spawn admission rechecks capacity. Lowering the limit does not stop existing runs.",
+        // Mode first: the policy governs the settings that follow it.
         delegationPrompt(settings.delegationMode),
+        capacity + " Spawn admission rechecks capacity; lower the limit without stopping existing runs.",
     ].join("\n");
 }
 
+/**
+ * Publish the delegation policy as its own prompt section.
+ *
+ * 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 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) {
     return {
         name: "subagent_settings",
@@ -60,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 { 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,18 +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: `${appendExecutionPolicy(event.systemPrompt)}\n\nUse the latest Subagent settings context block as the authoritative delegation mode and capacity snapshot. Its delegation guidance replaces earlier mode-specific guidance, including guidance in a plan. Inspect subagent_settings when needed; never treat the concurrency limit as a target number of agents.`,
-    }));
-
-    pi.on("context", (event) => {
-        const settings = effectiveSettings();
-        return { messages: [
-            ...event.messages.filter(message => message.role !== "custom" || message.customType !== SUBAGENT_SETTINGS_CONTEXT),
-            { role: "custom" as const, customType: SUBAGENT_SETTINGS_CONTEXT,
-                content: formatSubagentSettings(settings), display: false, details: settings, timestamp: Date.now() },
-        ] };
-    });
+    // 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.0",
+  "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.0",
+  "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.0",
-    "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.0",
+    "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}`;
-}