pi-better-harness 0.39.2 → 0.40.0

package/extensions/execution-policy.ts

@@ -6,6 +6,8 @@ const EXECUTION_POLICY = [
   "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.",
   "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");
 

package/node_modules/pi-better-background-tasks/README.md

@@ -255,6 +255,39 @@ items.", and kubectl and npm print warnings), which can raise a false alarm.
 If the stderr is expected, redirect it (`2>/dev/null`) or set
 `blind_checks: 0`. Set `blind_checks` to another number to change the count.
 
+## Batches
+
+`bg_task_spawn_batch` starts 1 to 100 independent background tasks at once and
+returns immediately with a `batchId`, one task id per launched job, and any job
+that was refused. Every job is an ordinary background task with its own process,
+log, and metadata; the batch only groups them.
+
+```json
+{
+  "batchName": "local builds",
+  "shared": { "cwd": "/repo", "env": { "CI": "1" } },
+  "jobs": [
+    { "name": "api", "command": "npm run build" },
+    { "name": "web", "command": "npm run build:web" }
+  ]
+}
+```
+
+- `jobs` is required. `shared` applies launch options to every job and cannot
+  carry `name`, `command`, `argv`, `batchId`, or `batchName`: those belong to a
+  single job, and the launcher refuses a batch that puts one in `shared`.
+- A job's own value wins over `shared`. An explicit `false`, `0`, or `null`
+  overrides the shared value instead of inheriting it.
+- The whole batch is preflighted before anything starts. One invalid job refuses
+  the batch, so a partial launch never happens.
+- Each launched task records `batchId` and `batchName` in its metadata, so a
+  reloaded task still says which batch it came from.
+- The result lists `launched` and `failed` with 1-based job positions, so a
+  refused entry points at the job in the request. Stopping one task does not
+  stop the others.
+- Do not wait or poll for the batch. Inspect, log, or stop each task by its id,
+  or watch one with `bg_task_watch`.
+
 ## Install
 
 ```sh
@@ -267,6 +300,40 @@ Try it for one run:
 pi -e npm:pi-better-background-tasks
 ```
 
+## Observed operations and waits
+
+Supervised local tasks use `bgs_` identifiers and a detached runner. The runner
+keeps observing after the worker or Pi process exits. Status and logs recover
+from durable evidence; an ambiguous launch becomes `lost` and is not relaunched.
+SSH tasks and older `bg_` identifiers use the existing runtime.
+
+Stop and timeout evidence can contain `groupCleanup=unproven` when the command's
+leader exits before cleanup can be verified. Descendants may remain running;
+inspect that evidence before interpreting the result.
+
+Call `wait_for_operations` with `task_ids` and an optional `continuation_note` to
+register an all-settled wait. The parent remains responsive. A notification means
+every dependency is terminal, including failed, cancelled, timed-out or lost
+operations; it does not mean the command succeeded.
+
+Read each operation's status or log, interpret its terminal revision, then call
+`acknowledge_operation_result` with the wait identity, exact revisions, disposition
+and interpretation note. The acknowledgement releases the wait's evidence pins.
+Reading evidence or receiving a callback alone does not consume the wait.
+`bg_task_wait_list` shows owned generations. `bg_task_wait_cancel` cancels a wait;
+use `bg_task_stop` separately when the command itself should stop.
+
+`watch_delivery` registers the installed stateful Mergify delivery watcher and its
+wait. The watcher observes delivery; the model interprets its result. The tool
+does not enqueue or merge a pull request.
+
+With Subagents loaded, workers can use the guarded operation bridge and park
+while waiting. Parking requires SDK 0.82.1 or later. The worker saves its wait
+result, exits cleanly and releases its capacity slot. The same conversation can
+resume after settlement when its original parent session and branch are active
+and current capacity, Goal, workflow and permission gates allow it. Restarting Pi
+does not start an unattended model. Uncertain recovery stays held with a reason.
+
 ## Failure observations
 
 Task lifecycle and failure evidence are reported separately. A watch can remain

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
   "license": "MIT",
   "type": "module",
@@ -44,6 +44,8 @@
   },
   "files": [
     "src/**/*.ts",
+    "src/supervisor/**/*.mjs",
+    "src/supervisor/**/*.js",
     "!src/**/*.test.ts",
     "!src/test-support/**",
     "!src/shared-ssh-core/test-support/**",

package/node_modules/pi-better-background-tasks/src/adapter-contract.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getObservedWaitHost } from "./observed-waits.js";
 import { inspectMeta } from "./registry.js";
 
 /** Optional-peer contract, mirrored by pi-better-sandbox/background-admission.ts. */
@@ -22,18 +23,26 @@ export function advertiseBackgroundAdapter(pi: ExtensionAPI, schemas: ReadonlyMa
         typeof request.reply !== "function") return;
     const parameters = schemas.get(request.name);
     if (!parameters) return;
-    const admission = classify(request.name, request.input);
+    const admission = classify(pi, request.name, request.input);
     if (admission) request.reply({ version: BACKGROUND_ADAPTER_VERSION, parameters, admission, executionControls: 1 });
   });
   pi.on("session_shutdown", () => { if (typeof unsubscribe === "function") unsubscribe(); });
 }
 
-function classify(name: string, input: unknown): Admission | undefined {
+function classify(pi: ExtensionAPI, name: string, input: unknown): Admission | undefined {
   if (!input || typeof input !== "object" || Array.isArray(input)) return;
   const params = input as Record<string, unknown>;
   let action: unknown;
   switch (name) {
     case "bg_task_spawn": action = "spawn"; break;
+    case "bg_task_spawn_batch": {
+      // A batch is a local launch only when no job is remote: per-job ssh options
+      // are decided by the batch launcher, not in this trusted process.
+      const jobs = Array.isArray(params.jobs) ? params.jobs : [];
+      const remote = jobs.some((job) => job !== null && typeof job === "object" &&
+        Boolean((job as Record<string, unknown>).ssh));
+      return remote ? undefined : "local-launch";
+    }
     case "bg_task_watch": action = "watch"; break;
     case "bg_task_list": action = "list"; break;
     case "bg_task_status": action = "status"; break;
@@ -53,4 +62,9 @@ function classify(name: string, input: unknown): Admission | undefined {
   // of a local stop; a remote stop can execute SSH in the trusted Pi process.
   const meta = inspectMeta(params.id).meta;
   if (meta && !meta.ssh && !meta.remote && (meta.kind === "process" || meta.kind === "command_watch")) return "registry";
+  // A durable local task has no legacy registry meta. Only the currently active
+  // owning session/workspace may admit it as a registry operation; the exact tool
+  // source and schema are still verified by the caller before this reply is
+  // trusted. A foreign session or worker-owned id stays unauthorized.
+  if (getObservedWaitHost(pi)?.ownsDurableTask(params.id) === true) return "registry";
 }

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

@@ -0,0 +1,108 @@
+import { randomUUID } from "node:crypto";
+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 type { BackgroundTaskCallbackOrigin } from "./types.js";
+
+export interface SpawnBatchParams {
+  batchName?: string;
+  jobs: SpawnTaskParams[];
+  shared?: Omit<SpawnTaskParams, "name" | "command" | "argv" | "batchId" | "batchName">;
+}
+
+export interface SpawnBatchResult {
+  batchId: string;
+  batchName?: string;
+  launched: Array<{ job: number; id: string; name?: string }>;
+  failed: Array<{ job: number; name?: string; error: string }>;
+}
+
+/** Undefined inherits; false, zero, and explicit-null intent declarations override. */
+function mergeJob(shared: SpawnBatchParams["shared"], job: SpawnTaskParams): SpawnTaskParams {
+  return { ...shared, ...Object.fromEntries(Object.entries(job).filter(([, value]) => value !== undefined)) };
+}
+
+export function spawnTaskBatch(
+  pi: ExtensionAPI,
+  params: SpawnBatchParams,
+  defaultCwd: string,
+  callbackOrigin?: BackgroundTaskCallbackOrigin,
+  getActiveSession?: ActiveSessionProvider,
+  dependencies: TaskRuntimeDependencies = {},
+): SpawnBatchResult {
+  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.");
+  }
+  for (const field of ["name", "command", "argv", "batchId", "batchName"]) {
+    if (params.shared && Object.hasOwn(params.shared, field)) {
+      throw new Error(`Invalid batch shared field ${field}: each job must supply its own command, argv, and name; batch identity is assigned by the launcher.`);
+    }
+  }
+  // Preflight the whole batch before any process, task directory, or SSH connection exists.
+  const jobs = params.jobs.map((job, index) => {
+    try {
+      if (!job || typeof job !== "object" || Array.isArray(job)) throw new Error("job must be an object");
+      const merged = mergeJob(params.shared, job);
+      readTaskIntent(merged);
+      validateLaunchStrings({
+        command: merged.command,
+        argv: merged.argv,
+        cwd: merged.cwd ?? defaultCwd,
+        env: merged.env,
+        ssh: merged.ssh,
+        remote: merged.remote,
+      });
+      if (merged.ssh) {
+        resolveSshCommand({ command: merged.command, cwd: merged.cwd ?? defaultCwd, env: merged.env, ssh: merged.ssh });
+      } else {
+        validateCommandSpec(merged);
+      }
+      return merged;
+    } catch (error) {
+      throw new Error(`Invalid batch job ${index + 1}: ${errorMessage(error)}`);
+    }
+  });
+  const result: SpawnBatchResult = {
+    batchId: `bg_batch_${randomUUID()}`,
+    ...(params.batchName !== undefined ? { batchName: params.batchName } : {}),
+    launched: [],
+    failed: [],
+  };
+  for (const [index, job] of jobs.entries()) {
+    try {
+      const meta = spawnTask(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) });
+    }
+  }
+  return result;
+}
+
+export function formatBatchLaunch(result: SpawnBatchResult): string {
+  const label = result.batchName ? `${result.batchName} (${result.batchId})` : result.batchId;
+  return [
+    `Batch ${label}: ${result.launched.length} launched, ${result.failed.length} failed to launch.`,
+    ...result.launched.map((job) => `Job ${job.job}${job.name ? ` (${job.name})` : ""}: ${job.id}`),
+    ...result.failed.map((job) => `Job ${job.job}${job.name ? ` (${job.name})` : ""}: failed to launch: ${job.error}`),
+    "Inspect, log, or stop each task by its id. Do not wait or poll in the foreground.",
+  ].join("\n");
+}
+
+// Node rejects NULs synchronously, even when the rest of the command spec is valid.
+function validateLaunchStrings(value: unknown, path = "launch"): void {
+  if (typeof value === "string") {
+    if (value.includes("\0")) throw new Error(`${path} must not contain NUL bytes`);
+  } else if (value && typeof value === "object") {
+    for (const [key, child] of Object.entries(value)) {
+      if (key.includes("\0")) throw new Error(`${path} keys must not contain NUL bytes`);
+      validateLaunchStrings(child, `${path}.${key}`);
+    }
+  }
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/node_modules/pi-better-background-tasks/src/delivery-observer.ts

@@ -0,0 +1,42 @@
+import {existsSync,realpathSync,statSync} from 'node:fs';
+import {join} from 'node:path';
+import {homedir} from 'node:os';
+import {Type} from 'typebox';
+import type {ExtensionAPI,ExtensionContext} from '@earendil-works/pi-coding-agent';
+
+/** Domain observation uses the installed stateful watcher, never a generated polling predicate. */
+export function resolveDeliveryWatcher(agentDir=process.env.PI_CODING_AGENT_DIR??join(homedir(),'.pi','agent')): string {
+ const candidates=[
+  join(agentDir,'skills','mergify','scripts','watch-pr-delivery.mjs'),
+  join(homedir(),'.agents','skills','mergify','scripts','watch-pr-delivery.mjs'),
+  join(agentDir,'npm','node_modules','@1aboveio','skills','skills','cicd','mergify','scripts','watch-pr-delivery.mjs'),
+ ];
+ for(const candidate of candidates)if(existsSync(candidate)&&statSync(candidate).isFile())return realpathSync.native(candidate);
+ throw new Error('The installed Mergify delivery watcher is unavailable. Install the mergify skill; no replacement polling script was launched.');
+}
+
+export function deliveryObserverArguments(repo:string,pr:number,watcher:string): string[] {
+ if(!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)||!Number.isSafeInteger(pr)||pr<1)throw new Error('A repository owner/name and positive PR number are required');
+ if(!watcher.endsWith('/watch-pr-delivery.mjs'))throw new Error('Unsupported delivery observer implementation');
+ return [process.execPath,watcher,'--repo',repo,'--pr',String(pr)];
+}
+
+export interface DeliveryObserverDependencies {
+ resolveWatcher?:()=>string;
+ launch:(params:{argv:string[];shell:false;cwd:string;name:string;callback:true},ctx:ExtensionContext)=>Promise<{id:string}>|{id:string};
+ wait:(taskIds:string[],note:string,ctx:ExtensionContext)=>Promise<unknown>|unknown;
+}
+
+export function registerDeliveryObserver(pi:Pick<ExtensionAPI,'registerTool'>,dependencies:DeliveryObserverDependencies):void {
+ pi.registerTool({
+  name:'watch_delivery',label:'Watch delivery',
+  description:'Observe an already-enqueued GitHub pull request through Mergify with the installed stateful delivery watcher. Starts a supervised background task and registers its wait. This does not enqueue, merge, push, edit the PR, or delegate polling to an LLM. Inspect the terminal verdict on completion before reporting delivery.',
+  parameters:Type.Object({repo:Type.String({description:'Repository owner/name'}),pr:Type.Integer({minimum:1})}),
+  async execute(_id,params,_signal,_update,ctx){
+   const argv=deliveryObserverArguments(params.repo,params.pr,(dependencies.resolveWatcher??resolveDeliveryWatcher)());
+   const task=await dependencies.launch({argv,shell:false,cwd:ctx.cwd,name:`Mergify delivery ${params.repo}#${params.pr}`,callback:true},ctx);
+   const wait=await dependencies.wait([task.id],`Interpret the Mergify terminal verdict for ${params.repo}#${params.pr}; inspect merge/dequeue evidence before reporting delivery.`,ctx);
+   return {content:[{type:'text',text:JSON.stringify({taskId:task.id,wait,status:'observing',mutationPerformed:false})}],details:{taskId:task.id,wait}};
+  },
+ });
+}

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

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { listMetas, listMetasForOrigin, onMetaChanged } from "./registry.js";
+import { getObservedWaitHost, type DurableTaskProjection } from "./observed-waits.js";
 import type { BackgroundTaskMeta } from "./types.js";
 import { isTerminalStatus } from "./types.js";
 import { backgroundTaskProgressAt, observeBackgroundTaskStall } from "./stall.js";
@@ -31,13 +32,19 @@ export function collectBackgroundTaskGoalActivity(
   metas: BackgroundTaskMeta[] = listMetas(),
   ctx?: ExtensionContext,
   now = Date.now(),
+  durable: readonly DurableTaskProjection[] = [],
 ): GoalBackgroundProviderSnapshot {
   return {
     providerId: "background-tasks",
     label: "Background Tasks",
-    items: metas
-      .filter((meta) => isVisibleGoalActivity(meta, ctx, now))
-      .map(backgroundTaskToGoalItem),
+    items: [
+      ...metas
+        .filter((meta) => isVisibleGoalActivity(meta, ctx, now))
+        .map(backgroundTaskToGoalItem),
+      ...durable
+        .filter((task) => isVisibleDurableGoalActivity(task, ctx, now))
+        .map(durableTaskToGoalItem),
+    ],
   };
 }
 
@@ -46,8 +53,23 @@ export function registerBackgroundTasksGoalProvider(pi: ExtensionAPI): void {
     pi.events?.emit(GOAL_REGISTER_PROVIDER_EVENT, {
       id: "background-tasks",
       label: "Background Tasks",
-      getActivity: (ctx: ExtensionContext) => collectBackgroundTaskGoalActivity(listMetasForOrigin(getGoalActivityOrigin(ctx)), ctx),
-      onActivityChanged: onMetaChanged,
+      getActivity: (ctx: ExtensionContext) => {
+        const origin = getGoalActivityOrigin(ctx);
+        const durable = getObservedWaitHost(pi)?.listDurableTasks(origin, {
+          retentionMs: TERMINAL_GOAL_ACTIVITY_RETENTION_MS,
+        }) ?? [];
+        return collectBackgroundTaskGoalActivity(listMetasForOrigin(origin), ctx, Date.now(), durable);
+      },
+      // A durable operation change must refresh Goal activity even though it
+      // never writes a mutable legacy registry meta.
+      onActivityChanged: (notify: () => void) => {
+        const offMeta = onMetaChanged(notify);
+        const offDurable = getObservedWaitHost(pi)?.onDurableTaskChange(notify);
+        return () => {
+          offMeta();
+          offDurable?.();
+        };
+      },
     });
   };
 
@@ -91,6 +113,51 @@ function getGoalActivityOrigin(ctx: ExtensionContext) {
   return { cwd: ctx.cwd, sessionId };
 }
 
+function isVisibleDurableGoalActivity(
+  task: DurableTaskProjection,
+  ctx: ExtensionContext | undefined,
+  now: number,
+): boolean {
+  if (task.dismissedAt !== undefined) return false;
+  if (ctx) {
+    const active = getGoalActivityOrigin(ctx);
+    if (task.owner.workspace !== active.cwd) return false;
+    if (active.sessionId || task.owner.sessionId) {
+      if (task.owner.sessionId !== active.sessionId) return false;
+    }
+  }
+  if (!task.terminal) return true;
+  if (!ctx) return true;
+  if (task.endedAt === undefined) return true;
+  return now - task.endedAt < TERMINAL_GOAL_ACTIVITY_RETENTION_MS;
+}
+
+function durableTaskToGoalItem(task: DurableTaskProjection): GoalBackgroundWorkItem {
+  const item: GoalBackgroundWorkItem = {
+    id: task.id,
+    status: task.status,
+    active: task.active,
+    terminal: task.terminal,
+    attention: task.attention,
+    startedAt: task.startedAt,
+    details: {
+      durable: true,
+      operationId: task.operationId,
+      kind: task.kind,
+      cwd: task.cwd,
+      command: task.command,
+      argv: task.argv,
+      logPath: task.logPaths.stdout,
+      lastProgressAt: task.endedAt ?? task.startedAt,
+      waits: task.waits.map((wait) => `${wait.waitId}:${wait.phase}`),
+      ...(task.reason ? { reason: task.reason } : {}),
+    },
+  };
+  if (task.name !== undefined) item.label = task.name;
+  if (task.endedAt !== undefined) item.endedAt = task.endedAt;
+  return item;
+}
+
 function backgroundTaskToGoalItem(meta: BackgroundTaskMeta): GoalBackgroundWorkItem {
   const active = meta.status === "running";
   const terminal = isTerminalStatus(meta.status);

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

@@ -4,11 +4,37 @@ 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 { 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";
 
 export default function backgroundTasksExtension(pi: ExtensionAPI): void {
+  // 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, {
+    notifyParent: (notification, delivery) => {
+      getCallbackBatcher(pi).enqueue({
+        source: "background-task",
+        id: notification.taskId,
+        label: notification.taskId,
+        status: notification.waitId
+          ? `${notification.status}; wait ${notification.waitId} ready`
+          : notification.status,
+        detailTool: "bg_task_status",
+        outcome: notification.outcome,
+        callback: true,
+        // The batcher can hold the event across a busy turn or a session switch.
+        // Receipt is the durable outbox/sidecar acknowledgement, not enqueue.
+        getSuppressionReason: () => observedWaits.isParentOriginActive(notification.origin, notification.branchId)
+          ? undefined
+          : "the originating session or branch is no longer active",
+        onDelivered: () => delivery.delivered(),
+        onSuppressed: (reason) => delivery.defer(reason ?? "callback delivery was suppressed"),
+      });
+    },
+  });
   initializeNavigatorPanels(pi);
   pi.on("before_agent_start", (event) => ({ systemPrompt: appendExecutionPolicy(event.systemPrompt) }));
   registerBackgroundTasksGoalProvider(pi);
@@ -23,14 +49,27 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
     ensureBackgroundTasksNavigator(ctx);
   });
   pi.on("session_before_switch", async () => {
+    observedWaits.close();
     clearBackgroundTasksNavigatorSession();
     disposeBackgroundWorkNavigator();
   });
   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);
   });
   registerTools(pi);
+  // 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) => {
+    observedWaits.start(ctx);
+  });
+  // A fork or branch navigation does not restart the session, but it changes
+  // which continuation may receive a queued callback. Update the host snapshot
+  // on the same event the callback batcher uses.
+  pi.on("session_tree", async (_event, ctx) => {
+    observedWaits.noteParentContext(ctx);
+  });
 }