pi-better-harness 0.43.0 → 0.45.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.45.0] - 2026-11-12
+
+### Changed
+
+- Bundle Subagents 0.32.0 for session-scoped historical wait warnings, original-session inspection, durable cancellation, and dismissal of unchanged notices. (#719)
+
+## [0.44.0] - 2026-11-12
+
+### Changed
+
+- Bundle Subagents 0.31.0, Background Tasks 0.15.0, and Goal 0.13.0 for autonomous assignment continuation, shared progress, durable outcomes, bounded recovery, and coordinator outage reconciliation. (#707)
+
 ## [0.43.0] - 2026-11-11
 
 ### Changed

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.14.4",
+  "version": "0.15.0",
   "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
   "license": "MIT",
   "type": "module",
@@ -44,6 +44,7 @@
   },
   "files": [
     "src/**/*.ts",
+    "src/shared-operation-coordinator/assignment-observation.mjs",
     "src/supervisor/**/*.mjs",
     "src/supervisor/**/*.js",
     "!src/**/*.test.ts",

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

@@ -72,7 +72,7 @@ import {
 import type { BackgroundTaskCallbackOrigin, CommandSpec, Condition, TaskSandboxProvenance } from "./types.js";
 import type { SpawnTaskParams, WatchTaskParams } from "./runtime.js";
 
-export const OBSERVED_WAITS_SERVICE_VERSION = 1 as const;
+export const OBSERVED_WAITS_SERVICE_VERSION = 2 as const;
 export const OBSERVED_WAITS_SERVICE_CHANNEL = "pi-better-background-tasks:observed-waits-service";
 export const OBSERVED_WAITS_SERVICE_REQUEST_CHANNEL = "pi-better-background-tasks:observed-waits-service-request";
 
@@ -185,6 +185,7 @@ export interface WaitView {
   readonly park: boolean;
   /** Cancellation epoch the caller must echo when claiming or cancelling. */
   readonly cancelEpoch: number;
+  readonly publishedClaimId?: string | null;
   readonly ownerKind: OwnerIdentity["kind"];
   readonly continuationNote: string;
   readonly taskIds: readonly string[];
@@ -470,6 +471,8 @@ export interface BackgroundOperationService {
   readonly serviceId: string;
   readonly available: true;
   /** True when a verified continuation adapter is registered. */
+  readonly assignmentContinuation: 1;
+  readonly outageReconciliation: 1;
   readonly continuationReady: boolean;
   ownsTask(run: WorkerRunScope, taskId: string): boolean;
   launchForWorker(run: WorkerRunScope, input: WorkerLaunchInput): Promise<DurableLaunch>;
@@ -490,6 +493,7 @@ export interface BackgroundOperationService {
    * epoch and evidence pins and invalidates the claim so nothing resumes again.
    */
   holdFailedResumeForWorker(run: WorkerRunScope, input: HoldResumedAttemptInput): HoldResumedAttemptView;
+  repairFailedResumeForWorker(run: WorkerRunScope, input: HoldResumedAttemptInput & { checkpointId: string; expectedCancelEpoch: number }): { phase: string; repaired: boolean };
   listWorkerWaits(run: WorkerRunScope, options?: { pendingOnly?: boolean }): readonly WaitView[];
   cancelWorkerWait(run: WorkerRunScope, input: { waitId: string; generation: number; reason: string }): WaitView;
   registerContinuationAdapter(adapter: ContinuationAdapter): void;
@@ -805,7 +809,7 @@ function evidenceFor(inspection: SupervisorInspection): WaitEvidenceView[] {
         operationId: "",
         terminalRevision: 0,
         kind: "log",
-        ref: `${label}.log`,
+        ref: path,
         summary: `${label} retained (${size} bytes)`,
         detailLost: false,
       });
@@ -836,6 +840,8 @@ export class ObservedWaitHost {
   private store?: Store;
   private readonly supervisor: LocalSupervisor;
   private readonly directory: string;
+  private readonly storePath: string;
+  private readonly discoveryScope: string;
   private readonly pollMs: number;
   private readonly options: ObservedWaitHostOptions;
   private timer?: NodeJS.Timeout;
@@ -884,13 +890,27 @@ export class ObservedWaitHost {
   private readonly hostStartDigest = startTokenDigest(currentProcessStartToken());
   private readonly hostId = `${process.pid}:${this.hostStartDigest}:${randomUUID()}`;
   private hostGeneration = ++HOST_INSTANCE_STATE.next;
+  private discoveryToken?: string;
+  private discoveryRole?: "holder" | "follower";
+  private reconcileInFlight?: Promise<void>;
+  private authorityPassCache?: Map<string, "live" | "dead" | "unknown">;
+  /** Running operations this follower is currently assigned to supervise. */
+  private readonly followerRunningTasks = new Set<string>();
+  private lastChangeRevision = -1;
+  private lastOwnedTerminalAt = 0;
 
   constructor(private readonly pi: ExtensionAPI, options: ObservedWaitHostOptions = {}) {
     this.options = options;
     this.directory = options.supervisorDirectory ?? defaultSupervisorDirectory();
+    this.storePath = options.storePath ?? defaultStorePath();
+    this.discoveryScope = createHash("sha256")
+      .update(`${resolve(this.storePath)}\0${resolve(this.directory)}`)
+      .digest("hex");
     this.supervisor = options.supervisor ?? createLocalSupervisor({ directory: this.directory });
     this.pollMs = options.pollMs ?? DEFAULT_POLL_MS;
     const base = {
+      assignmentContinuation: 1 as const,
+      outageReconciliation: 1 as const,
       version: OBSERVED_WAITS_SERVICE_VERSION,
       serviceId: this.serviceId,
       available: true as const,
@@ -908,6 +928,10 @@ export class ObservedWaitHost {
       publishResumeForWorker: (run: WorkerRunScope, input: PublishResumeViewInput) => this.publishResumeForWorker(run, input),
       releaseResumeForWorker: (run: WorkerRunScope, input: ReleaseResumeViewInput) => this.releaseResumeForWorker(run, input),
       holdFailedResumeForWorker: (run: WorkerRunScope, input: HoldResumedAttemptInput) => this.holdFailedResumeForWorker(run, input),
+      repairFailedResumeForWorker: (run, input) => {
+        this.ownedWait(this.workerOwner(run), input.waitId, input.generation);
+        return this.requireStore().repairFailedResume(input);
+      },
       listWorkerWaits: (run: WorkerRunScope, listOptions?: { pendingOnly?: boolean }) => this.listWorkerWaits(run, listOptions),
       cancelWorkerWait: (run: WorkerRunScope, input: { waitId: string; generation: number; reason: string }) => this.cancelWorkerWait(run, input),
       registerContinuationAdapter: (adapter: ContinuationAdapter) => this.registerContinuationAdapter(adapter),
@@ -943,7 +967,6 @@ export class ObservedWaitHost {
       // The same host instance can be activated for another session without a
       // reload. Re-evaluate pending deliveries against the new active origin.
       this.recoverAbandonedDeliveries();
-      this.discoverObservedTasks();
       void this.reconcileNow();
       this.recoverTerminalNotifications();
       this.terminalRecoveryNeeded = false;
@@ -955,7 +978,7 @@ export class ObservedWaitHost {
     this.unavailableReason = undefined;
     try {
       this.store = openStore({
-        path: this.options.storePath ?? defaultStorePath(),
+        path: this.storePath,
         ...(this.options.now ? { now: this.options.now } : {}),
       });
     } catch (error) {
@@ -971,7 +994,6 @@ export class ObservedWaitHost {
     this.announce();
     this.writeHostDebug();
     this.recoverAbandonedDeliveries();
-    this.discoverObservedTasks();
     void this.reconcileNow();
     this.recoverTerminalNotifications();
     this.terminalRecoveryNeeded = false;
@@ -987,6 +1009,8 @@ export class ObservedWaitHost {
     HOST_INSTANCE_STATE.closed.add(this.hostId);
     if (this.timer) clearInterval(this.timer);
     this.timer = undefined;
+    this.releaseDiscoveryAuthority();
+    this.releaseSupervisionAuthority();
     try { this.store?.close(); } catch { /* already closed */ }
     this.store = undefined;
     this.launches.clear();
@@ -1100,9 +1124,40 @@ export class ObservedWaitHost {
 
   /** A deterministic, awaitable reconciliation pass for tests and session activation. */
   async reconcileNow(): Promise<void> {
+    if (this.reconcileInFlight) return this.reconcileInFlight;
+    const pass = this.reconcilePass();
+    this.reconcileInFlight = pass;
+    try {
+      await pass;
+    } finally {
+      if (this.reconcileInFlight === pass) this.reconcileInFlight = undefined;
+    }
+  }
+
+  private async reconcilePass(): Promise<void> {
     if (!this.store || this.closed) return;
-    this.discoverObservedTasks();
-    const running = this.store.listOperations({ phase: "running" });
+    this.authorityPassCache = new Map();
+    try {
+      const role = this.refreshDiscoveryAuthority();
+      this.noteDiscoveryRole(role);
+      if (role === "holder") {
+        this.discoverObservedTasks();
+        this.reconcileGlobalRunning();
+      } else {
+        this.reconcileFollowerRunning();
+        this.reconcileOwnerChanges();
+      }
+      this.retryPendingTerminalCallbacks();
+      await this.dispatchOutbox();
+    } finally {
+      this.authorityPassCache = undefined;
+    }
+  }
+
+  private reconcileGlobalRunning(): void {
+    const store = this.store;
+    if (!store) return;
+    const running = store.listOperations({ phase: "running" });
     const runningIds = new Set(running.map((operation) => operation.taskId));
     let changedOwner: OwnerIdentity | undefined;
     for (const taskId of [...this.watchedRunningTasks]) {
@@ -1128,8 +1183,126 @@ export class ObservedWaitHost {
       this.watchedRunningTasks.add(operation.taskId);
       this.reconcileOperation(operation);
     }
-    this.retryPendingTerminalCallbacks();
-    await this.dispatchOutbox();
+  }
+
+  private reconcileFollowerRunning(): void {
+    const store = this.store;
+    if (!store) return;
+    const running = store.listRunningSupervisedBy(this.hostId);
+    const runningIds = new Set(running.map((operation) => operation.taskId));
+    for (const taskId of [...this.followerRunningTasks]) {
+      if (!runningIds.has(taskId)) this.followerRunningTasks.delete(taskId);
+    }
+    for (const operation of running) {
+      this.followerRunningTasks.add(operation.taskId);
+      this.reconcileOperation(operation);
+    }
+  }
+
+  /**
+   * A follower does not scan foreign operations. It refreshes the exact active
+   * owner's terminal records only when the shared change revision advances, so
+   * callback recovery stays correct without multiplying the running-set scan.
+   */
+  private reconcileOwnerChanges(): void {
+    const store = this.store;
+    const ctx = this.activeContext;
+    if (!store || !ctx) return;
+    const sessionId = this.sessionIdIfAvailable(ctx);
+    if (!sessionId) return;
+    let revision: number;
+    try {
+      revision = store.getChangeRevision();
+    } catch {
+      return;
+    }
+    if (revision === this.lastChangeRevision) return;
+    this.lastChangeRevision = revision;
+    let operations: OperationRecord[];
+    try {
+      operations = store.listOperations({
+        ownerScope: { kind: "parent-session", sessionId, workspace: ctx.cwd },
+        phase: "terminal",
+      });
+    } catch {
+      return;
+    }
+    let newest = this.lastOwnedTerminalAt;
+    let visibleOwner: OwnerIdentity | undefined;
+    for (const operation of operations) {
+      newest = Math.max(newest, operation.terminalAt ?? operation.updatedAt);
+      if (this.activeOwnerRelation(operation.owner) === "match") visibleOwner ??= operation.owner;
+      this.attemptTerminalCallback(
+        operation,
+        this.statusOf(operation.operationId),
+        operation.terminalOutcome ?? "failed",
+        [],
+        { pendingWithoutContext: true },
+      );
+    }
+    if (newest > this.lastOwnedTerminalAt) {
+      this.lastOwnedTerminalAt = newest;
+      if (visibleOwner) this.emitDurableTaskChange(visibleOwner);
+    }
+  }
+
+  private noteDiscoveryRole(role: "holder" | "follower"): void {
+    if (this.discoveryRole === role) return;
+    this.discoveryRole = role;
+    this.followerRunningTasks.clear();
+    if (role === "holder") {
+      this.watchedRunningTasks.clear();
+      this.discoveredTaskSidecars.clear();
+    }
+    this.lastChangeRevision = -1;
+  }
+
+  /**
+   * Acquire or confirm the one shared discovery claim. Process identity and
+   * explicit close evidence decide replacement; elapsed time is not a lease.
+   */
+  private refreshDiscoveryAuthority(): "holder" | "follower" {
+    const store = this.store;
+    if (!store) return "follower";
+    let claim;
+    try {
+      claim = store.readDiscoveryClaim(this.discoveryScope);
+    } catch {
+      return "follower";
+    }
+    if (claim?.hostId === this.hostId) {
+      this.discoveryToken = claim.token;
+      return "holder";
+    }
+    if (claim) {
+      const state = this.discoveryHolderState(claim.hostId);
+      if (state === "live" || state === "unknown") {
+        this.discoveryToken = undefined;
+        return "follower";
+      }
+    }
+    const token = `discovery_${randomUUID()}`;
+    try {
+      const claimed = store.tryClaimDiscovery({
+        scope: this.discoveryScope,
+        expected: claim ? { hostId: claim.hostId, token: claim.token } : null,
+        hostId: this.hostId,
+        token,
+      });
+      if (claimed) {
+        this.discoveryToken = claimed.token;
+        return "holder";
+      }
+    } catch {
+      // A busy store or a lost race defers discovery to a later pass.
+    }
+    this.discoveryToken = undefined;
+    return "follower";
+  }
+
+  private discoveryHolderState(hostId: string): "live" | "dead" | "unknown" {
+    if (hostId === this.hostId) return "live";
+    return this.supervisionHolderState(hostId);
   }
 
   isDurableTask(taskId: string): boolean {
@@ -2076,6 +2249,7 @@ export class ObservedWaitHost {
   }
 
   private rpcRegisterRun(params: JsonRecord): JsonRecord {
+    if (params.assignmentOutcomesVersion !== undefined && params.assignmentOutcomesVersion !== 1) throw new Error("Unsupported assignment outcome capability; this host supports version 1.");
     const runId = requireRpcString(params, "runId");
     const conversationId = requireRpcString(params, "conversationId");
     const workspace = requireRpcString(params, "workspace");
@@ -2112,7 +2286,7 @@ export class ObservedWaitHost {
       ...(typeof params.writerPid === "number" && params.writerPid > 0 ? { writerPid: params.writerPid } : {}),
       ...(typeof params.writerLeaseId === "string" ? { writerLeaseId: params.writerLeaseId } : {}),
     }));
-    return { runId, conversationId, workspace, attemptId, workerOperations: true };
+    return { runId, conversationId, workspace, attemptId, workerOperations: true, assignmentOutcomesVersion: 1 };
   }
 
   private rpcReleaseRun(params: JsonRecord): JsonRecord {
@@ -2652,6 +2826,27 @@ export class ObservedWaitHost {
 
   private reconcileOperation(operation: OperationRecord): void {
     if (operation.terminalRevision > 0) return;
+    const authority = this.supervisionAuthority(operation);
+    if (authority === "foreign") return;
+    let claimed = false;
+    if (authority === "replace") {
+      try {
+        this.store?.recordSupervision({
+          operationId: operation.operationId,
+          owner: operation.owner,
+          expectedHostId: operation.supervision?.hostId ?? null,
+          supervision: this.supervision(),
+          health: "active",
+        });
+        claimed = true;
+      } catch (error) {
+        // Another host can hold the write lock, or it can take over between the
+        // snapshot and this write. Leave the observed record alone and let the
+        // next reconciliation tick re-read it.
+        if (rpcCode(error) === "store-busy" || rpcCode(error) === "supervision-conflict") return;
+        throw error;
+      }
+    }
     const inspection = this.inspect(operation.taskId);
     if (!inspection) {
       const now = this.options.now?.() ?? Date.now();
@@ -2679,12 +2874,15 @@ export class ObservedWaitHost {
         return;
       }
       try {
-        this.store?.recordSupervision({
-          operationId: operation.operationId,
-          owner: operation.owner,
-          health: "unmonitored",
-          reason: "no durable supervisor record exists for this operation",
-        });
+        if (claimed || operation.health !== "unmonitored" || operation.healthReason !== "no durable supervisor record exists for this operation") {
+          this.store?.recordSupervision({
+            operationId: operation.operationId,
+            owner: operation.owner,
+            expectedHostId: this.hostId,
+            health: "unmonitored",
+            reason: "no durable supervisor record exists for this operation",
+          });
+        }
       } catch { /* the owner may have been superseded; health is observational */ }
       return;
     }
@@ -2692,24 +2890,102 @@ export class ObservedWaitHost {
       this.recordTerminal(operation, inspection);
       return;
     }
-    if (operation.health !== "active" || operation.supervision?.hostId !== this.hostId) {
+    if (!claimed && (operation.health !== "active" || operation.supervision?.hostId !== this.hostId)) {
       // Health is observational; write it only when the supervising host or the
       // reported health actually changed. A 250 ms tick must not churn SQLite.
       try {
         this.store?.recordSupervision({
           operationId: operation.operationId,
           owner: operation.owner,
+          expectedHostId: this.hostId,
           supervision: this.supervision(),
           health: "active",
         });
       } catch (error) {
-        // Another host can hold the write lock. Leave health unchanged and let
-        // the next reconciliation tick retry this observational update.
-        if (rpcCode(error) !== "store-busy") throw error;
+        // Another host can hold the write lock or have taken over. Leave health
+        // unchanged and let the next tick re-read the operation.
+        if (rpcCode(error) !== "store-busy" && rpcCode(error) !== "supervision-conflict") throw error;
+      }
+    }
+  }
+
+  /**
+   * Whether this host may inspect the operation. The recorded `supervision`
+   * identity is the cross-process authority marker: a live holder keeps it, and
+   * only a closed or dead holder is replaced. Process identity is checked before
+   * elapsed time, and an unprovable holder is never stolen from.
+   */
+  private supervisionAuthority(operation: OperationRecord): "self" | "foreign" | "replace" {
+    const hostId = operation.supervision?.hostId;
+    if (!hostId) return "replace";
+    if (hostId === this.hostId) return "self";
+    if (HOST_INSTANCE_STATE.closed.has(hostId)) return "replace";
+    const cached = this.authorityPassCache?.get(hostId);
+    const state = cached ?? this.supervisionHolderState(hostId);
+    if (cached === undefined) this.authorityPassCache?.set(hostId, state);
+    return state === "live" || state === "unknown" ? "foreign" : "replace";
+  }
+
+  /** Process-identity check for a recorded holder, cached per pass by callers. */
+  private supervisionHolderState(hostId: string): "live" | "dead" | "unknown" {
+    const { pid, startTokenDigest: claimedDigest } = parseHostIdentity(hostId);
+    if (!pid) return "unknown";
+    if (pid === process.pid) {
+      const generation = HOST_INSTANCE_STATE.generations.get(hostId);
+      // Another instance in this process still owns its record. Creation order
+      // alone is not death: a reload predecessor is marked closed above.
+      return generation === undefined ? "dead" : "live";
+    }
+    if (!processExists(pid)) return "dead";
+    if (!claimedDigest) return "unknown";
+    const current = readProcessStartToken(pid);
+    if (!current) return "unknown";
+    return startTokenDigest(current) === claimedDigest ? "live" : "dead";
+  }
+
+  /**
+   * A graceful close releases only this host's running authority. A crash leaves
+   * the same record for the next host to replace after process identity proves it
+   * dead; a newer holder is never cleared by a late close.
+   */
+  private releaseSupervisionAuthority(): void {
+    const store = this.store;
+    if (!store) return;
+    let running: OperationRecord[];
+    try {
+      running = store.listOperations({ phase: "running" });
+    } catch {
+      return;
+    }
+    for (const operation of running) {
+      if (operation.supervision?.hostId !== this.hostId) continue;
+      try {
+        store.releaseSupervision({
+          operationId: operation.operationId,
+          owner: operation.owner,
+          hostId: this.hostId,
+          reason: "the supervising host closed; another host may take over",
+        });
+      } catch {
+        // Closing must not fail on a busy or already replaced record.
       }
     }
   }
 
+  /** Release only this host's exact discovery claim; a successor keeps its own. */
+  private releaseDiscoveryAuthority(): void {
+    const store = this.store;
+    const token = this.discoveryToken;
+    this.discoveryToken = undefined;
+    this.discoveryRole = undefined;
+    if (!store || !token) return;
+    try {
+      store.releaseDiscoveryClaim({ scope: this.discoveryScope, hostId: this.hostId, token });
+    } catch {
+      // Closing must not fail on a busy or already replaced claim.
+    }
+  }
+
   private reconcileInspection(operation: OperationRecord, inspection: SupervisorInspection | undefined): void {
     if (inspection?.terminal && operation.terminalRevision === 0) this.recordTerminal(operation, inspection);
   }
@@ -3108,6 +3384,7 @@ export class ObservedWaitHost {
       let claimed: OutboxEventRecord[];
       try {
         claimed = store.claimOutbox({
+          type: "dependency-ready",
           recipient: owner,
           claimToken,
           claimedBy: this.hostId,
@@ -3295,6 +3572,7 @@ export class ObservedWaitHost {
       settled: wait.settled,
       park: wait.park !== null,
       cancelEpoch: wait.cancelEpoch,
+      publishedClaimId: store.listResumeClaims({ waitId: wait.waitId, generation: wait.generation, state: "published" })[0]?.claimId ?? null,
       ownerKind: wait.owner.kind,
       continuationNote: wait.continuationNote,
       taskIds: dependencies
@@ -3527,7 +3805,10 @@ export class ObservedWaitHost {
     // A tool call or activation for a different session/workspace must seed the
     // terminal callback journal once. Same-session calls keep the live context
     // current without rescanning historical terminal records.
-    if (!previous || previousKey !== nextKey) this.terminalRecoveryNeeded = true;
+    if (!previous || previousKey !== nextKey) {
+      this.terminalRecoveryNeeded = true;
+      this.lastChangeRevision = -1;
+    }
     this.writeHostDebug();
   }
 

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

@@ -119,12 +119,14 @@ export interface CallbackBatchHost {
   /** Older Pi shares this object; newer Pi supplies per-extension wrappers. */
   events?: object;
   sendMessage(
-    message: { customType: string; content: string; display: boolean },
+    message: { customType: string; content: string; display: boolean; details?: unknown },
     options: Record<string, unknown>,
   ): unknown;
 }
 
 export interface CallbackBatchEvent {
+  receiptId?: string;
+  inspectId?: string;
   source: CallbackSource;
   id: string;
   label: string;
@@ -332,8 +334,8 @@ function boundedStatus(value: unknown): string {
   return count < notes.length ? `${kept}${omission(notes.length - count)}` : kept;
 }
 
-function inspectFor(event: Pick<CallbackBatchEvent, "id" | "detailTool">): string {
-  const id = boundedField(event.id, MAX_ID_BYTES);
+function inspectFor(event: Pick<CallbackBatchEvent, "id" | "detailTool" | "inspectId">): string {
+  const id = boundedField(event.inspectId ?? event.id, MAX_ID_BYTES);
   return event.detailTool === "bg_task_status"
     ? `bg_task_status id=${id}`
     : `subagent_result id=${JSON.stringify(id)}`;
@@ -665,6 +667,7 @@ export function createCallbackBatcher(
     const representedItems = deliverable.filter(([, item]) => representedSet.has(item.event));
     const overflowItems = deliverable.filter(([, item]) => !representedSet.has(item.event));
 
+    const receiptDetails = { completionEventIds: representedItems.map(([, item]) => item.event.receiptId).filter((id): id is string => Boolean(id)) };
     try {
       // Pi may defer the requested run while settled handlers finish, leaving
       // isIdle() true. Permit no second handoff until a run starts.
@@ -674,12 +677,14 @@ export function createCallbackBatcher(
           customType: "background-completion-batch",
           content: packed.text,
           display: true,
+          ...(receiptDetails.completionEventIds.length ? { details: receiptDetails } : {}),
         },
         // Newer Pi requires triggerTurn for steering too; false only appends
         // a custom message at the turn boundary without continuing the agent.
         { deliverAs: mode, triggerTurn: true },
       );
     } catch {
+      receiptDetails.completionEventIds.length = 0;
       awaitingRun = false;
       for (const [key] of deliverable) inFlight.delete(key);
       const retryItems = [...deliverable, ...pending.entries()]

package/node_modules/pi-better-background-tasks/src/shared-operation-coordinator/assignment-observation.mjs

@@ -0,0 +1,43 @@
+// Generated from packages/operation-coordinator/assignment-observation.mjs. Do not edit directly.
+import { createRequire } from "node:module";
+
+/** Read-only, bounded projection input. Never creates/migrates a database. */
+export function readAssignmentWaits(path, owner) {
+    let db;
+    try {
+        const { DatabaseSync } = createRequire(import.meta.url)("node:sqlite");
+        db = new DatabaseSync(path, { readOnly: true });
+        // v4 adds repair accounting; the observed wait/outcome fields are unchanged.
+        if (!["1", "2", "3", "4"].includes(db.prepare("SELECT value FROM schema_meta WHERE key = 'schema_version'").get()?.value)) {
+            return { verified: false, waits: [], reason: "Unsupported coordinator schema; assignment state is unverified." };
+        }
+        const rows = db.prepare(`SELECT wait_id, generation, phase, phase_reason,
+            acknowledgement_json, cancel_epoch FROM waits
+            WHERE owner_kind = 'worker-conversation' AND owner_session_id = ? AND owner_workspace = ?
+            ${owner.assignmentId ? "AND json_extract(origin_json, '$.assignmentRef') = ?" : `AND (
+                EXISTS (SELECT 1 FROM json_each(?) AS attempt
+                    WHERE attempt.value = json_extract(waits.origin_json, '$.attemptId')
+                       OR attempt.value = json_extract(waits.park_json, '$.attemptId'))
+                OR EXISTS (SELECT 1 FROM resume_claims AS claim, json_each(?) AS attempt
+                    WHERE claim.wait_id = waits.wait_id AND claim.generation = waits.generation
+                      AND claim.attempt_id = attempt.value)
+                OR EXISTS (SELECT 1 FROM json_each(?) AS ref
+                    WHERE json_extract(ref.value, '$.waitId') = waits.wait_id
+                      AND json_extract(ref.value, '$.generation') = waits.generation)
+            )`}
+            ORDER BY created_at DESC, generation DESC LIMIT 100`).all(owner.sessionId, owner.workspace,
+                ...(owner.assignmentId ? [owner.assignmentId] : [JSON.stringify(owner.attemptIds ?? []), JSON.stringify(owner.attemptIds ?? []), JSON.stringify(owner.waitRefs ?? [])]));
+        const record = owner.assignmentId ? db.prepare("SELECT record_json FROM assignment_outcomes WHERE assignment_id = ?").get(owner.assignmentId) : null;
+        const outcome = record ? JSON.parse(record.record_json) : null;
+        if (outcome && (outcome.owner.sessionId !== owner.sessionId || outcome.owner.workspace !== owner.workspace)) throw new Error("Foreign assignment outcome");
+        return { verified: true, outcome, waits: rows.map((row) => ({
+            waitId: row.wait_id, generation: row.generation, phase: row.phase,
+            reason: row.phase_reason, cancelEpoch: row.cancel_epoch,
+            acknowledgement: row.acknowledgement_json ? JSON.parse(row.acknowledgement_json) : null,
+        })) };
+    } catch {
+        return { verified: false, waits: [], reason: "Coordinator state is unverified; compatible supervision is unavailable." };
+    } finally {
+        db?.close();
+    }
+}

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

@@ -45,6 +45,7 @@
  * to be durable.
  */
 export { SCHEMA_VERSION, TERMINAL_WAIT_PHASES } from "./src/types.ts";
+export type { AssignmentOutcomeInput, AssignmentOutcomeRecord } from "./src/assignment-outcomes.ts";
 export type {
     AcknowledgeDisposition,
     AcknowledgeResultInput,
@@ -53,6 +54,7 @@ export type {
     CancelWaitResult,
     ClaimOutboxInput,
     ClaimResumeInput,
+    DiscoveryClaimRecord,
     EvidenceKind,
     EvidencePinRecord,
     EvidenceReadRecord,
@@ -85,6 +87,8 @@ export type {
     RegisterOperationResult,
     RegisterWaitInput,
     RegisterWaitResult,
+    ReleaseDiscoveryClaimInput,
+    ReleaseSupervisionInput,
     ReleaseOutboxInput,
     ReleaseResumeClaimInput,
     ReleaseResumeClaimResult,
@@ -98,6 +102,7 @@ export type {
     TerminalOutcome,
     TransitionWaitPhaseInput,
     TransitionWaitPhaseResult,
+    TryClaimDiscoveryInput,
     WaitAcknowledgement,
     WaitDependencyInput,
     WaitDependencyRecord,