pi-better-harness 0.41.1 → 0.41.3

package/README.md

@@ -45,8 +45,9 @@ existing saved labels remain unchanged until deliberately updated.
 Use `newTask: true` with a new
 outcome for unrelated work; a correction to the current task keeps its binding.
 Hooks enable `update_todo`, `get_todo`, capture, matching Goal lifecycle bridge
-writes, reminders, and automated cleanup. While hooks are enabled and the outcome is active, Harness
-includes a short reminder before each model call. Turning hooks off stops those
+writes, outcome updates, and automated cleanup. With hooks enabled, Harness records
+a hidden, persistent outcome update at the next agent start only when its content
+changes. It does not rebuild reminders before each model call. Turning hooks off stops those
 hooks without deleting saved state or starting a turn. `/goal` and skills never
 enable them.
 

package/extensions/task-context/index.ts

@@ -677,13 +677,14 @@ export default function taskContextExtension(pi: ExtensionAPI): void {
   pi.on("session_tree", async (_event, ctx) => {
     restore(ctx);
   });
-  pi.on("context", (event) => {
-    const messages = event.messages.filter(message => message.role !== "custom" || message.customType !== "pi-better-harness:outcome-reminder");
-    if (!enabled || outcome?.status !== "active") return messages.length === event.messages.length ? undefined : { messages };
-    const unit = rushPlan?.issues.find(item => item.status === "in-flight") ?? rushPlan?.issues.find(item => item.status === "pending");
-    const step = currentPlan?.steps.find(item => item.status === "in_progress") ?? currentPlan?.steps.find(item => item.status === "pending");
-    const focus = rushBinding ? (unit ? `${unit.id}: ${unit.title}` : undefined) : step?.step;
-    return { messages: [...messages, { role: "custom" as const, customType: "pi-better-harness:outcome-reminder", content: `${formatOutcome(outcome, true)}${focus ? `\nTodo focus: ${focus.slice(0, 300)}` : ""}\nChoose work that advances this outcome or meets a binding requirement. Report unrelated debt without fixing it. Latest user instructions win; questions are not permission to execute. Stop when the agreed outcome and required checks are done.`, display: false, timestamp: Date.now() }] };
+  pi.on("before_agent_start", (_event, ctx) => {
+    if (!enabled || !outcome) return;
+    const content = formatOutcome(outcome);
+    // These messages are persisted by Pi. Never rebuild or remove them in context.
+    const previous = [...ctx.sessionManager.getBranch()].reverse().find(entry =>
+      entry.type === "custom_message" && entry.customType === "pi-better-harness:outcome-update");
+    if (previous?.type === "custom_message" && previous.content === content) return;
+    return { message: { customType: "pi-better-harness:outcome-update", content, display: false } };
   });
   pi.on("session_shutdown", async (_event, ctx) => {
     cancelCompletedPlanClear();

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

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

@@ -3,7 +3,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { readTaskIntent } from "./failures.js";
 import { validateCommandSpec } from "./process.js";
 import { resolveSshCommand } from "./shared-ssh-core/index.js";
-import { spawnTask, type ActiveSessionProvider, type SpawnTaskParams, type TaskRuntimeDependencies } from "./runtime.js";
+import { spawnTask, type ActiveSessionProvider, type BackgroundTaskRuntime, type SpawnTaskParams, type TaskRuntimeDependencies } from "./runtime.js";
 import type { BackgroundTaskCallbackOrigin } from "./types.js";
 
 export interface SpawnBatchParams {
@@ -31,7 +31,10 @@ export function spawnTaskBatch(
   callbackOrigin?: BackgroundTaskCallbackOrigin,
   getActiveSession?: ActiveSessionProvider,
   dependencies: TaskRuntimeDependencies = {},
+  runtime: Pick<BackgroundTaskRuntime, "spawnTask"> = { spawnTask },
 ): SpawnBatchResult {
+  // Jobs launch through the owning factory's runtime, never the default singleton.
+  const spawnOne = runtime.spawnTask;
   if (!Array.isArray(params.jobs) || params.jobs.length < 1 || params.jobs.length > 100) {
     throw new Error("jobs must contain between 1 and 100 background tasks.");
   }
@@ -72,7 +75,7 @@ export function spawnTaskBatch(
   };
   for (const [index, job] of jobs.entries()) {
     try {
-      const meta = spawnTask(pi, { ...job, batchId: result.batchId, batchName: result.batchName }, defaultCwd, callbackOrigin, getActiveSession, dependencies);
+      const meta = spawnOne(pi, { ...job, batchId: result.batchId, batchName: result.batchName }, defaultCwd, callbackOrigin, getActiveSession, dependencies);
       result.launched.push({ job: index + 1, id: meta.id, ...(meta.name !== undefined ? { name: meta.name } : {}) });
     } catch (error) {
       result.failed.push({ job: index + 1, ...(job.name !== undefined ? { name: job.name } : {}), error: errorMessage(error) });

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

@@ -103,18 +103,19 @@ export function recoverDeclaredOperation(meta: BackgroundTaskMeta, at = Date.now
   }
 }
 
+export function createFailureAttention() {
 const attentionTimers = new Map<string, ReturnType<typeof setTimeout>>();
 let attentionSuspended = false;
 /** Session shutdown: stop this instance's attention timers; the next session_start reschedules (#324). */
-export function suspendFailureAttention(): void {
+function suspendFailureAttention(): void {
   attentionSuspended = true;
   for (const timer of attentionTimers.values()) clearTimeout(timer);
   attentionTimers.clear();
 }
-export function resumeFailureAttention(): void {
+function resumeFailureAttention(): void {
   attentionSuspended = false;
 }
-export function stopFailureAttention(id: string): void {
+function stopFailureAttention(id: string): void {
   const timer = attentionTimers.get(id);
   if (timer) clearTimeout(timer);
   attentionTimers.delete(id);
@@ -125,7 +126,7 @@ export function stopFailureAttention(id: string): void {
  * identity is per incident set; the inspect target is the real task id.
  * Only the pending incidents are rows; earlier deliveries are counted, never repeated (#315).
  */
-export function failureAttentionFields(meta: BackgroundTaskMeta, state: FailureState, pending: { key: string; incidents: string[] }) {
+function failureAttentionFields(meta: BackgroundTaskMeta, state: FailureState, pending: { key: string; incidents: string[] }) {
   const rows = pendingAttentionRows(state, pending.incidents);
   const note = pendingAttentionNote(state, pending.incidents);
   const due = pending.incidents.length;
@@ -144,7 +145,7 @@ export function failureAttentionFields(meta: BackgroundTaskMeta, state: FailureS
 }
 
 /** Running incidents get one grace wake. Terminal incidents ride the completion callback. */
-export function scheduleFailureAttention(pi: ExtensionAPI, id: string, getActiveSession?: ActiveSessionProvider): void {
+function scheduleFailureAttention(pi: ExtensionAPI, id: string, getActiveSession?: ActiveSessionProvider): void {
   stopFailureAttention(id);
   if (attentionSuspended) return;
   const meta = readMeta(id);
@@ -167,6 +168,7 @@ export function scheduleFailureAttention(pi: ExtensionAPI, id: string, getActive
         return current.status !== "running" || failureAttentionHandled(now, pending.incidents);
       },
       getSuppressionReason: () => {
+        if (attentionSuspended) throw new Error("Failure attention instance is suspended; defer notification");
         const current = readMeta(id);
         if (!current) throw new Error("Task metadata is unavailable; defer failure notification");
         if (current.status !== "running" || current.callback === false || current.stopRequestedAt) return "task is no longer running";
@@ -179,7 +181,7 @@ export function scheduleFailureAttention(pi: ExtensionAPI, id: string, getActive
       onDelivered: (at) => { markFailureAttentionDelivered(failurePath(id), pending, at); },
     });
     void Promise.resolve(delivery).then((sent) => {
-      if (!sent && (!readMeta(id) || readMeta(id)?.status === "running")) {
+      if (!sent && !attentionSuspended && (!readMeta(id) || readMeta(id)?.status === "running")) {
         const timer = setTimeout(() => scheduleFailureAttention(pi, id, getActiveSession), 1_000);
         timer.unref();
         attentionTimers.set(id, timer);
@@ -197,6 +199,12 @@ export function scheduleFailureAttention(pi: ExtensionAPI, id: string, getActive
   }
 }
 
+return { suspendFailureAttention, resumeFailureAttention, stopFailureAttention, scheduleFailureAttention, failureAttentionFields };
+}
+/** Shared by the compatibility exports here and the legacy background runtime. */
+export const defaultAttention = createFailureAttention();
+export const { suspendFailureAttention, resumeFailureAttention, stopFailureAttention, scheduleFailureAttention, failureAttentionFields } = defaultAttention;
+
 export function terminalFailureAttention(id: string) {
   return pendingFailureAttention(readFailureState(failurePath(id)), Date.now(), { terminal: true });
 }

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

@@ -1,9 +1,8 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { disposeBackgroundWorkNavigator } from "./shared-navigator.ts";
 import { initializeNavigatorPanels } from "./shared-navigator-panels.ts";
 import { registerBackgroundTasksGoalProvider } from "./goal-provider.js";
-import { clearBackgroundTasksNavigatorSession, ensureBackgroundTasksNavigator, ensureBackgroundTasksNavigatorProvider } from "./navigator-provider.js";
-import { resumeScheduledWork, suspendScheduledWork } from "./runtime.js";
+import { createBackgroundTasksNavigator } from "./navigator-provider.js";
+import { createBackgroundTaskRuntime } from "./runtime.js";
 import { createObservedWaitHost } from "./observed-waits.js";
 import { getCallbackBatcher } from "./shared-callback-batcher.js";
 import { observeForegroundSandboxPolicy } from "./sandbox.js";
@@ -11,6 +10,10 @@ import { registerTools } from "./tools.js";
 import { deliverBackgroundTasksPrompt } from "./prompt.js";
 
 export default function backgroundTasksExtension(pi: ExtensionAPI): void {
+  // Each cached factory invocation owns its runtime, failure timers, navigator
+  // projection, and durable host. Nothing here is shared module state (#460).
+  const runtime = createBackgroundTaskRuntime();
+  const navigator = createBackgroundTasksNavigator(runtime);
   // Created before registerTools so the tools can resolve it lazily; the durable
   // store opens on session activation and closes on switch/unload.
   const observedWaits = createObservedWaitHost(pi, {
@@ -41,29 +44,27 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
   // would then carry a snapshot, so sections published after it never arrive.
   pi.on("before_agent_start", (event) => deliverBackgroundTasksPrompt(event));
   registerBackgroundTasksGoalProvider(pi);
-  ensureBackgroundTasksNavigatorProvider(pi);
+  navigator.ensureBackgroundTasksNavigatorProvider(pi);
   // Subscribed at load so a sandbox extension that publishes later is heard, and
   // asked for a snapshot in case one published before this extension existed.
   observeForegroundSandboxPolicy(pi);
   // Registered before registerTools(pi), so this runs before running tasks are resumed.
   pi.on("session_start", async (_event, ctx) => {
-    resumeScheduledWork();
+    runtime.resumeScheduledWork();
     registerBackgroundTasksGoalProvider(pi);
-    ensureBackgroundTasksNavigator(ctx);
+    navigator.ensureBackgroundTasksNavigator(ctx);
   });
   pi.on("session_before_switch", async () => {
     observedWaits.close();
-    clearBackgroundTasksNavigatorSession();
-    disposeBackgroundWorkNavigator();
+    navigator.clearBackgroundTasksNavigatorSession();
   });
   pi.on("session_shutdown", async (_event, ctx) => {
     // /reload, session replacement, and quit load a fresh instance; stop this one's timers (#324).
     observedWaits.close();
-    suspendScheduledWork();
-    clearBackgroundTasksNavigatorSession();
-    disposeBackgroundWorkNavigator(ctx);
+    runtime.suspendScheduledWork();
+    navigator.clearBackgroundTasksNavigatorSession();
   });
-  registerTools(pi);
+  registerTools(pi, runtime, navigator.refreshBackgroundTasksNavigator);
   // Registered after registerTools so the callback batcher has its session
   // context before a reconciled delivery can enqueue a parent notification.
   pi.on("session_start", async (_event, ctx) => {
@@ -75,4 +76,4 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
   pi.on("session_tree", async (_event, ctx) => {
     observedWaits.noteParentContext(ctx);
   });
-}
+}

package/node_modules/pi-better-background-tasks/src/navigator-provider.ts

@@ -1,6 +1,8 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
   DEFAULT_LOG_TAIL_ROWS as NAVIGATOR_DETAIL_ROWS,
+  disposeBackgroundWorkNavigator,
+  isNavigatorUiAvailable,
   ensureBackgroundWorkNavigator,
   refreshBackgroundWorkNavigator,
   registerBackgroundWorkProvider,
@@ -15,16 +17,25 @@ import { failurePath, failureView } from "./failures.js";
 import { readLog } from "./logs.js";
 import { listMetasForOrigin, onMetaChanged, readMeta, writeMeta } from "./registry.js";
 import { getObservedWaitHost, type DurableTaskProjection } from "./observed-waits.js";
-import { stopTask } from "./runtime.js";
+import { stopTask, type BackgroundTaskRuntime } from "./runtime.js";
 import { formatBackgroundTaskStall, observeBackgroundTaskStall } from "./stall.js";
 import type { BackgroundTaskCallbackOrigin, BackgroundTaskMeta, BackgroundTaskStatus } from "./types.js";
 
+const TERMINAL_NAVIGATOR_RETENTION_MS = 30_000;
+
+export function createBackgroundTasksNavigator(runtime: Pick<BackgroundTaskRuntime, "stopTask"> = { stopTask }) {
+const owner = Symbol("background-tasks navigator factory");
 let unregister: (() => void) | undefined;
+let navigatorContext: ExtensionContext | undefined;
 let piRef: ExtensionAPI | undefined;
 let activeNavigatorOrigin: BackgroundTaskCallbackOrigin | undefined;
-const TERMINAL_NAVIGATOR_RETENTION_MS = 30_000;
-
-export function ensureBackgroundTasksNavigatorProvider(pi: ExtensionAPI): void {
+function ensureBackgroundTasksNavigatorProvider(pi: ExtensionAPI): void {
+  // Provider registration is deferred until an actual TUI session owns it, so a
+  // headless child sharing the cached module cannot replace the parent's provider.
+  if (!navigatorContext) {
+    piRef = pi;
+    return;
+  }
   // A reloaded or replaced extension instance gets a fresh host. Re-register so
   // the provider's durable-change subscription targets that host, not the one
   // captured by the previous instance.
@@ -37,22 +48,33 @@ export function ensureBackgroundTasksNavigatorProvider(pi: ExtensionAPI): void {
   unregister = registerBackgroundWorkProvider(provider);
 }
 
-export function ensureBackgroundTasksNavigator(ctx: ExtensionContext): void {
+function ensureBackgroundTasksNavigator(ctx: ExtensionContext): void {
+  if (!isNavigatorUiAvailable(ctx)) return;
+  navigatorContext = ctx;
+  if (piRef) ensureBackgroundTasksNavigatorProvider(piRef);
   activeNavigatorOrigin = getNavigatorOrigin(ctx);
   ensureBackgroundWorkNavigator(ctx, {
     createDefaultEditor: (tui, theme, keybindings) => new CustomEditor(tui as never, theme as never, keybindings as never),
     isOpenTrigger: (data) => matchesKey(data, Key.left),
     matchKey: (data, keyId) => matchesKey(data, keyId as Parameters<typeof matchesKey>[1]),
     truncate: truncateToWidth,
-  });
+  }, owner);
 }
 
-export function clearBackgroundTasksNavigatorSession(): void {
+function clearBackgroundTasksNavigatorSession(): void {
   activeNavigatorOrigin = undefined;
+  unregister?.();
+  unregister = undefined;
+  if (navigatorContext) disposeBackgroundWorkNavigator(navigatorContext, owner);
+  navigatorContext = undefined;
 }
 
-export function refreshBackgroundTasksNavigator(ctx?: ExtensionContext): void {
-  refreshBackgroundWorkNavigator(ctx);
+function refreshBackgroundTasksNavigator(ctx?: ExtensionContext): void {
+  // This factory owns no navigator until a TUI session installs it; a refresh from
+  // a non-TUI tool context then repaints the stored owner context (main #332).
+  const ownerCtx = navigatorContext;
+  if (!ownerCtx) return;
+  refreshBackgroundWorkNavigator(ctx && isNavigatorUiAvailable(ctx) ? ctx : ownerCtx);
 }
 
 const provider: BackgroundWorkProvider = {
@@ -92,7 +114,7 @@ const provider: BackgroundWorkProvider = {
     const meta = readMeta(id);
     if (!meta) return { action: "missing", providerId: "background-tasks", id };
     if (meta.status === "running") {
-      void stopTask(piRef as ExtensionAPI, id);
+      void runtime.stopTask(piRef as ExtensionAPI, id);
       return { action: "stopped", providerId: "background-tasks", id, status: "stopping" };
     }
     meta.dismissedAt = Date.now();
@@ -288,6 +310,11 @@ function belongsToActiveNavigatorSession(meta: BackgroundTaskMeta): boolean {
   return meta.cwd === active.cwd;
 }
 
+return { ensureBackgroundTasksNavigatorProvider, ensureBackgroundTasksNavigator, clearBackgroundTasksNavigatorSession, refreshBackgroundTasksNavigator };
+}
+const defaultNavigator = createBackgroundTasksNavigator();
+export const { ensureBackgroundTasksNavigatorProvider, ensureBackgroundTasksNavigator, clearBackgroundTasksNavigatorSession, refreshBackgroundTasksNavigator } = defaultNavigator;
+
 function isExpiredTerminalNavigatorRow(meta: BackgroundTaskMeta, now: number): boolean {
   if (meta.status === "running") return false;
   const endedAt = meta.endedAt;

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

@@ -10,7 +10,7 @@ import type { RemoteRunner, ResolvedSshRemoteTask } from "./remote-task-preset.j
 import { ensureTaskDir, logPathFor, nextTaskId, readMeta, sandboxProfilePathFor, writeMeta } from "./registry.js";
 import { assertBackgroundExecutionAllowed, backgroundExecutionLimits, confineCommandSpec, isCommandTimeoutSeconds, resolveForegroundSandboxPlan, sandboxProvenance } from "./sandbox.js";
 import { takeRecoverySnapshot } from "./shared-sandbox-core.js";
-import { failurePath, readTaskIntent, recordExitFailure, recordFailure, recoverDeclaredOperation, recoverFailure, resumeFailureAttention, scheduleFailureAttention, stopFailureAttention, suspendFailureAttention, terminalFailureAttention } from "./failures.js";
+import { failurePath, readTaskIntent, recordExitFailure, recordFailure, recoverDeclaredOperation, recoverFailure, createFailureAttention, defaultAttention, terminalFailureAttention } from "./failures.js";
 import { markFailureAttentionDelivered } from "./shared-failure-observations.js";
 import { getCallbackBatcher } from "./shared-callback-batcher.js";
 import { formatCallbackFacts } from "./output.js";
@@ -29,6 +29,89 @@ import type {
 import { observeTaskStallAttention } from "./stall-attention.js";
 import { isTerminalStatus } from "./types.js";
 
+export type ActiveSessionProvider = () => BackgroundTaskCallbackOrigin | undefined;
+
+/** Structured intent (#325), declared by the launching agent and shared by spawns and watchers. */
+export interface TaskIntentParams {
+  /** Stable id shared by modified retries of one operation. */
+  operation_id?: string | null;
+  /** Non-zero exit codes declared intentional before launch. */
+  expected_exit_codes?: number[] | null;
+}
+
+export interface SpawnTaskParams extends CommandSpec, TaskIntentParams {
+  name?: string;
+  /**
+   * Batch identity assigned by the batch launcher, never declared by a caller.
+   * Absent for a single spawn; carried into the persisted metadata so batch
+   * membership survives a reload instead of living only in the launch result.
+   */
+  batchId?: string;
+  /** Batch label from the same launch, when the operator gave one. */
+  batchName?: string;
+  callback?: boolean;
+  timeout_seconds?: number;
+  max_log_bytes?: number;
+  /**
+   * Opt-in step gate (#619): run the command under bash errexit, so the first
+   * unhandled failing step ends the task with that step's exit code and a later
+   * command cannot mask it.
+   */
+  require_successful_steps?: boolean;
+  ssh?: SshConnectionParams;
+  remote?: RemoteTaskParams;
+}
+
+export interface WatchTaskParams extends CommandSpec, TaskIntentParams {
+  name?: string;
+  callback?: boolean;
+  interval_seconds?: number;
+  timeout_seconds?: number;
+  max_log_bytes?: number;
+  success_when: Condition;
+  failure_when?: Condition;
+  /**
+   * Rejected (#619): a watch check is one polled command whose own exit code is the
+   * outcome, so the step gate cannot apply. Accepted in the shared schema only where
+   * the same wrapper also spawns.
+   */
+  require_successful_steps?: boolean;
+  /** Consecutive blind checks before the watch is flagged (#359). Default 3; 0 turns it off. */
+  blind_checks?: number;
+  ssh?: SshConnectionParams;
+  remote?: RemoteTaskParams;
+}
+
+type WatchPollRunner = (timeoutMs?: number) => Promise<CommandResult>;
+
+export interface TaskRuntimeDependencies {
+  remoteRunner?: RemoteRunner;
+  /**
+   * Embedding/test seam for a local watch's poll command. Production polls run
+   * the persisted command through `runCommandOnce`; a remote watch keeps using
+   * its SSH runner instead.
+   */
+  watchPollRunner?: WatchPollRunner;
+}
+
+export const DEFAULT_WATCH_TIMEOUT_SECONDS = 15 * 60;
+/** Consecutive blind checks (exit 0, stderr, no condition matched) before a watch is flagged (#359). */
+export const DEFAULT_BLIND_CHECKS = 3;
+/** How long bg_task_watch waits for the first check before returning (#359). */
+export const FIRST_WATCH_CHECK_WAIT_MS = 15_000;
+/** How to fix a false alarm: some tools write progress or warnings to stderr on success. */
+export const BLIND_CHECK_HINT = "If the stderr is expected (progress or warnings), redirect it (2>/dev/null) or set blind_checks:0.";
+/**
+ * Why the launch stopped waiting before the first check finished (#359): the bounded wait
+ * ran out, the tool call was aborted (Esc), or the session shut down.
+ */
+export type FirstCheckWaitEnd = "timeout" | "aborted" | "suspended";
+/** A first check's outcome, or why it is not known yet; undefined when the watch ended without one. */
+export type FirstCheckOutcome = FirstWatchCheck | { pending: FirstCheckWaitEnd; waitedMs: number } | undefined;
+
+/** Each cached extension factory owns its scheduling and suspension state. */
+export function createBackgroundTaskRuntime(attention = createFailureAttention()) {
+const { resumeFailureAttention, scheduleFailureAttention, stopFailureAttention, suspendFailureAttention } = attention;
 const watcherTimers = new Map<string, ReturnType<typeof setTimeout>>();
 const remoteSessionTimers = new Map<string, ReturnType<typeof setTimeout>>();
 const processTimeoutTimers = new Map<string, ReturnType<typeof setTimeout>>();
@@ -49,22 +132,7 @@ const HANDOFF_LOST_GRACE_MS = 5_000;
 let scheduledWorkSuspended = false;
 const REMOTE_SESSION_POLL_MS = 100;
 
-export const DEFAULT_WATCH_TIMEOUT_SECONDS = 15 * 60;
-/** Consecutive blind checks (exit 0, stderr, no condition matched) before a watch is flagged (#359). */
-export const DEFAULT_BLIND_CHECKS = 3;
-/** How long bg_task_watch waits for the first check before returning (#359). */
-export const FIRST_WATCH_CHECK_WAIT_MS = 15_000;
 const BLIND_OPERATION = "watch-blind";
-/** How to fix a false alarm: some tools write progress or warnings to stderr on success. */
-export const BLIND_CHECK_HINT = "If the stderr is expected (progress or warnings), redirect it (2>/dev/null) or set blind_checks:0.";
-
-/**
- * Why the launch stopped waiting before the first check finished (#359): the bounded wait
- * ran out, the tool call was aborted (Esc), or the session shut down.
- */
-export type FirstCheckWaitEnd = "timeout" | "aborted" | "suspended";
-/** A first check's outcome, or why it is not known yet; undefined when the watch ended without one. */
-export type FirstCheckOutcome = FirstWatchCheck | { pending: FirstCheckWaitEnd; waitedMs: number } | undefined;
 
 /** In-flight first checks of watches launched by this instance, keyed by task id. */
 const firstCheckWaiters = new Map<string, { promise: Promise<FirstWatchCheck | "suspended" | undefined>; resolve: (check: FirstWatchCheck | "suspended" | undefined) => void }>();
@@ -74,7 +142,7 @@ const firstCheckWaiters = new Map<string, { promise: Promise<FirstWatchCheck | "
  * outcome when the wait ends first, and undefined when this instance did not launch the watch
  * or the watch ended without a check.
  */
-export async function awaitFirstWatchCheck(id: string, timeoutMs = FIRST_WATCH_CHECK_WAIT_MS, signal?: AbortSignal): Promise<FirstCheckOutcome> {
+async function awaitFirstWatchCheck(id: string, timeoutMs = FIRST_WATCH_CHECK_WAIT_MS, signal?: AbortSignal): Promise<FirstCheckOutcome> {
   const waiter = firstCheckWaiters.get(id);
   if (!waiter) return undefined;
   const started = Date.now();
@@ -132,7 +200,7 @@ function settleFirstCheck(id: string, check: FirstWatchCheck | "suspended" | und
  * is recorded as terminal and its callback is delivered when its session resumes;
  * after Pi quits, a resumed task whose process is gone is marked lost instead.
  */
-export function suspendScheduledWork(): void {
+function suspendScheduledWork(): void {
   scheduledWorkSuspended = true;
   for (const timer of watcherTimers.values()) clearTimeout(timer);
   for (const timer of remoteSessionTimers.values()) clearTimeout(timer);
@@ -150,76 +218,12 @@ export function suspendScheduledWork(): void {
 }
 
 /** Allow scheduling again; called at session_start before running tasks are resumed. */
-export function resumeScheduledWork(): void {
+function resumeScheduledWork(): void {
   scheduledWorkSuspended = false;
   resumeFailureAttention();
 }
 
 
-
-export type ActiveSessionProvider = () => BackgroundTaskCallbackOrigin | undefined;
-
-/** Structured intent (#325), declared by the launching agent and shared by spawns and watchers. */
-export interface TaskIntentParams {
-  /** Stable id shared by modified retries of one operation. */
-  operation_id?: string | null;
-  /** Non-zero exit codes declared intentional before launch. */
-  expected_exit_codes?: number[] | null;
-}
-
-export interface SpawnTaskParams extends CommandSpec, TaskIntentParams {
-  name?: string;
-  /**
-   * Batch identity assigned by the batch launcher, never declared by a caller.
-   * Absent for a single spawn; carried into the persisted metadata so batch
-   * membership survives a reload instead of living only in the launch result.
-   */
-  batchId?: string;
-  /** Batch label from the same launch, when the operator gave one. */
-  batchName?: string;
-  callback?: boolean;
-  timeout_seconds?: number;
-  max_log_bytes?: number;
-  /**
-   * Opt-in step gate (#619): run the command under bash errexit, so the first
-   * unhandled failing step ends the task with that step's exit code and a later
-   * command cannot mask it.
-   */
-  require_successful_steps?: boolean;
-  ssh?: SshConnectionParams;
-  remote?: RemoteTaskParams;
-}
-
-export interface WatchTaskParams extends CommandSpec, TaskIntentParams {
-  name?: string;
-  callback?: boolean;
-  interval_seconds?: number;
-  timeout_seconds?: number;
-  max_log_bytes?: number;
-  success_when: Condition;
-  failure_when?: Condition;
-  /**
-   * Rejected (#619): a watch check is one polled command whose own exit code is the
-   * outcome, so the step gate cannot apply. Accepted in the shared schema only where
-   * the same wrapper also spawns.
-   */
-  require_successful_steps?: boolean;
-  /** Consecutive blind checks before the watch is flagged (#359). Default 3; 0 turns it off. */
-  blind_checks?: number;
-  ssh?: SshConnectionParams;
-  remote?: RemoteTaskParams;
-}
-
-export interface TaskRuntimeDependencies {
-  remoteRunner?: RemoteRunner;
-  /**
-   * Embedding/test seam for a local watch's poll command. Production polls run
-   * the persisted command through `runCommandOnce`; a remote watch keeps using
-   * its SSH runner instead.
-   */
-  watchPollRunner?: WatchPollRunner;
-}
-
 /**
  * Persist the launch-time per-command cap with the task metadata. Reload and
  * resume go through `readMeta`, so the value travels as ordinary JSON and the
@@ -286,9 +290,7 @@ function invalidPersistedCommandCap(meta: BackgroundTaskMeta): string | undefine
   return `Persisted command time limit ${JSON.stringify(meta.commandTimeoutSeconds)} is invalid; the task was not resumed with an unlimited command.`;
 }
 
-type WatchPollRunner = (timeoutMs?: number) => Promise<CommandResult>;
-
-export function spawnTask(
+function spawnTask(
   pi: ExtensionAPI,
   params: SpawnTaskParams,
   defaultCwd: string,
@@ -601,7 +603,7 @@ function failRemoteTask(
   finalize(meta, { status: "failed", reason }, pi, getActiveSession);
 }
 
-export function startWatchTask(
+function startWatchTask(
   pi: ExtensionAPI,
   params: WatchTaskParams,
   defaultCwd: string,
@@ -698,7 +700,7 @@ function resolveWatchTimeoutSeconds(timeoutSeconds: number | undefined): number
   return timeoutSeconds;
 }
 
-export function resumeRunningTask(
+function resumeRunningTask(
   pi: ExtensionAPI,
   meta: BackgroundTaskMeta,
   getActiveSession?: ActiveSessionProvider,
@@ -859,7 +861,7 @@ function resolvePersistedRemoteTask(
   }, remoteRunner);
 }
 
-export async function stopTask(
+async function stopTask(
   pi: ExtensionAPI,
   id: string,
   getActiveSession?: ActiveSessionProvider,
@@ -1608,3 +1610,11 @@ function observeWatchOutcome(meta: BackgroundTaskMeta, result: CommandResult): v
   }
   if (prior !== fingerprint) meta.lastProgressAt = meta.lastCheckedAt ?? Date.now();
 }
+
+return { awaitFirstWatchCheck, suspendScheduledWork, resumeScheduledWork, spawnTask, startWatchTask, resumeRunningTask, stopTask };
+}
+
+export type BackgroundTaskRuntime = ReturnType<typeof createBackgroundTaskRuntime>;
+const defaultRuntime = createBackgroundTaskRuntime(defaultAttention);
+/** Compatibility for callers using the original singleton API. */
+export const { awaitFirstWatchCheck, suspendScheduledWork, resumeScheduledWork, spawnTask, startWatchTask, resumeRunningTask, stopTask } = defaultRuntime;

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

@@ -82,8 +82,10 @@ type HostDeps = {
 
 type NavigatorState = {
   providers: Map<string, BackgroundWorkProvider>;
+  registrationTokens?: Map<string, symbol>;
   unsubscribers: Map<string, () => void>;
   uiCtx?: ExtensionContext;
+  uiOwner?: symbol;
   deps?: HostDeps;
   lastHint?: string | null;
   lastMainListLines?: string[];
@@ -137,6 +139,8 @@ function state(): NavigatorState {
 
 export function registerBackgroundWorkProvider(provider: BackgroundWorkProvider): () => void {
   const s = state();
+  const token = Symbol(provider.id);
+  (s.registrationTokens ??= new Map()).set(provider.id, token);
   const previousUnsub = s.unsubscribers.get(provider.id);
   if (previousUnsub) {
     try { previousUnsub(); } catch { /* ignore */ }
@@ -152,7 +156,10 @@ export function registerBackgroundWorkProvider(provider: BackgroundWorkProvider)
     s.unsubscribers.delete(provider.id);
   }
   refreshBackgroundWorkNavigator();
-  return () => unregisterBackgroundWorkProvider(provider.id);
+  // A stale factory must not unregister its replacement from another cached module.
+  return () => {
+    if (state().registrationTokens?.get(provider.id) === token) unregisterBackgroundWorkProvider(provider.id);
+  };
 }
 
 export function unregisterBackgroundWorkProvider(id: string): void {
@@ -163,6 +170,7 @@ export function unregisterBackgroundWorkProvider(id: string): void {
   }
   s.unsubscribers.delete(id);
   s.providers.delete(id);
+  s.registrationTokens?.delete(id);
   refreshBackgroundWorkNavigator();
 }
 
@@ -188,10 +196,11 @@ export function applyCloseConfirmFooter(ui: { setStatus(key: string, value: stri
   return hint ?? null;
 }
 
-export function ensureBackgroundWorkNavigator(ctx: ExtensionContext, deps: HostDeps): void {
+export function ensureBackgroundWorkNavigator(ctx: ExtensionContext, deps: HostDeps, owner?: symbol): void {
   if (!isNavigatorUiAvailable(ctx)) return;
   const s = state();
   s.uiCtx = ctx;
+  s.uiOwner = owner;
   s.deps = {
     ...deps,
     createTranscriptComponent: deps.createTranscriptComponent ?? s.deps?.createTranscriptComponent,
@@ -207,14 +216,26 @@ export function ensureBackgroundWorkNavigator(ctx: ExtensionContext, deps: HostD
   refreshMainListWidget();
 }
 
-export function disposeBackgroundWorkNavigator(ctx?: ExtensionContext): void {
+export function disposeBackgroundWorkNavigator(ctx?: ExtensionContext, owner?: symbol): void {
   const s = state();
+  if (owner !== undefined) {
+    // Only the factory that installed the current navigator may dispose it.
+    if (s.uiOwner !== owner) return;
+  } else if (s.uiOwner !== undefined) {
+    // Ownership is never inferred: an omitted owner must not clear a navigator
+    // another cached factory (or a headless child) owns.
+    return;
+  } else if (ctx !== undefined) {
+    // Unowned navigators stay releasable by a live, matching UI context.
+    if (!isNavigatorUiAvailable(ctx) || (s.uiCtx && ctx.ui !== s.uiCtx.ui)) return;
+  }
   try { s.dispose?.(); } catch { /* ignore */ }
   s.dispose = undefined;
   s.overlay = undefined;
   stopMainListWidget();
   const activeCtx = ctx ?? s.uiCtx;
   s.uiCtx = undefined;
+  s.uiOwner = undefined;
   if (activeCtx && isNavigatorUiAvailable(activeCtx)) {
     try { setNavigatorPanel(activeCtx, MAIN_LIST_WIDGET_KEY, undefined); } catch { /* ignore */ }
   }