@nklisch/pi-enhanced 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v0.2.2
+
+### Fixed
+
+- Point the bundled FFF compatibility resource at its extension entrypoint instead of its source directory, preventing Pi from trying to load the finder lifecycle helper as an extension.
+
+## v0.2.1
+
+### Fixed
+
+- Rebundle the extension reliability releases that contain stale contexts, detached promises, timers, process callbacks, UI callbacks, and cleanup failures instead of allowing them to terminate Pi.
+
 ## v0.2.0
 
 ### Changed

package/node_modules/@nklisch/pi-background-tasks/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## v0.1.7 — 2026-08-23
+
+### Fixed
+
+- Contain stale session contexts, rejected wake and persistence calls, process callbacks, and monitor failures inside each job. Session replacement now cancels owned work before Pi revokes reporting access, and diagnostics remain available through job output when the session is still active.

package/node_modules/@nklisch/pi-background-tasks/extensions/background-tasks.test.ts

@@ -233,6 +233,52 @@ describe("background tool", () => {
     expect(n).toBeTruthy();
     expect(n!.level).toBe("success");
   });
+
+  test("REGRESSION: stale Pi and UI contexts cannot escape a detached process callback", async () => {
+    // Session replacement invalidates both the extension API and prior tool
+    // contexts. The Criterion completion crash escaped from child.on("exit")
+    // when appendEntry threw on exactly this stale-context path.
+    const { pi, tools } = makeFakePi();
+    const bg = tools.get("background")!;
+    const jobs = tools.get("jobs")!;
+    const ctx = makeContext();
+    pi.appendEntry = () => { throw new Error("stale appendEntry"); };
+    pi.sendMessage = () => { throw new Error("stale sendMessage"); };
+    ctx.ui!.notify = () => { throw new Error("stale notify"); };
+    ctx.ui!.setStatus = () => { throw new Error("stale setStatus"); };
+
+    const diagnostics: string[] = [];
+    const priorConsoleError = console.error;
+    console.error = (...args: unknown[]) => diagnostics.push(args.map(String).join(" "));
+    try {
+      const started = (await bg.execute(
+        "c1",
+        { command: "echo completes-after-context-invalidates" },
+        undefined,
+        undefined,
+        ctx,
+      )) as { details: { jobId: number } };
+
+      // Do not poll through the jobs tool yet: every tool call intentionally
+      // refreshes lastUi, which would replace the simulated stale context.
+      await waitFor(() => diagnostics.some((line) => line.includes("waking the agent failed")) || undefined);
+      expect(await jobStatus(tools, makeContext(), started.details.jobId)).toBe("completed");
+      const tail = (await jobs.execute(
+        "c2",
+        { action: "tail", jobId: started.details.jobId, lines: 100 },
+        undefined,
+        undefined,
+        makeContext(),
+      )) as { content: Array<{ text: string }> };
+
+      expect(tail.content[0].text).toContain("persisting job registry failed: stale appendEntry");
+      expect(tail.content[0].text).toContain("refreshing background status failed: stale setStatus");
+      expect(tail.content[0].text).toContain("notifying the user failed: stale notify");
+      expect(tail.content[0].text).toContain("waking the agent failed: stale sendMessage");
+    } finally {
+      console.error = priorConsoleError;
+    }
+  });
 });
 
 describe("monitor tool", () => {
@@ -302,6 +348,65 @@ describe("monitor tool", () => {
     }
   });
 
+  test("turns an unexpected detached poll exception into a failed job", async () => {
+    const hostile = {
+      [Symbol.toPrimitive]() { throw new Error("hostile poll output"); },
+    };
+    const { tools, wakes } = makeFakePi(async () => ({
+      stdout: hostile as unknown as string,
+      code: 0,
+    }));
+    const mon = tools.get("monitor")!;
+    const jobs = tools.get("jobs")!;
+    const ctx = makeContext();
+    const started = (await mon.execute(
+      "c1",
+      { command: "check", satisfy_on: "exit_zero", interval_seconds: 1, timeout_seconds: 5 },
+      undefined,
+      undefined,
+      ctx,
+    )) as { details: { jobId: number } };
+
+    const wake = await waitFor(() => wakes[0]);
+    expect(wake.content).toContain("internal running monitor poll failure");
+    expect(await jobStatus(tools, ctx, started.details.jobId)).toBe("failed");
+    const tail = (await jobs.execute(
+      "c2",
+      { action: "tail", jobId: started.details.jobId, lines: 100 },
+      undefined,
+      undefined,
+      ctx,
+    )) as { content: Array<{ text: string }> };
+    expect(tail.content[0].text).toContain("running monitor poll failed: hostile poll output");
+  });
+
+  test("captures cwd before delayed polls so a replaced context is never reused", async () => {
+    let calls = 0;
+    const { tools, wakes } = makeFakePi(async () => {
+      calls += 1;
+      return calls === 1
+        ? { stdout: "pending", code: 1 }
+        : { stdout: "READY", code: 0 };
+    });
+    const mon = tools.get("monitor")!;
+    const ctx = makeContext();
+    await mon.execute(
+      "c1",
+      { command: "check", satisfy_on: "stdout_matches", pattern: "READY", interval_seconds: 1, timeout_seconds: 5 },
+      undefined,
+      undefined,
+      ctx,
+    );
+    Object.defineProperty(ctx, "cwd", {
+      configurable: true,
+      get: () => { throw new Error("stale tool context"); },
+    });
+
+    const wake = await waitFor(() => wakes[0], { timeoutMs: 5000 });
+    expect(wake.content).toContain("satisfied");
+    expect(calls).toBe(2);
+  });
+
   test("times out when the condition never holds", async () => {
     const { tools, wakes } = makeFakePi();
     const mon = tools.get("monitor")!;

package/node_modules/@nklisch/pi-background-tasks/extensions/background-tasks.ts

@@ -318,15 +318,73 @@ export default function backgroundTasksExtension(pi: PiApi): void {
   let nextId = 1;
   let shuttingDown = false;
 
-  function snapshot(): void {
-    pi.appendEntry?.("background-tasks", {
-      jobs: Array.from(jobs.values()).map((j) => ({
-        id: j.id,
-        kind: j.kind,
-        label: j.label,
-        command: j.command,
-        status: j.status,
-      })),
+  function errorText(error: unknown): string {
+    try {
+      return error instanceof Error ? error.message : String(error);
+    } catch {
+      return "unprintable error";
+    }
+  }
+
+  /**
+   * Detached callbacks have no host-owned tool/event promise boundary. Record
+   * their failures in the job output (where the agent can retrieve them) and
+   * stderr, but never let them escape into Node's EventEmitter/timer machinery.
+   */
+  function recordOperationalError(job: Job | undefined, operation: string, error: unknown): void {
+    const diagnostic = `[background-tasks] ${operation} failed: ${errorText(error)}`;
+    try {
+      if (job) appendBuffer(job, `\n${diagnostic}\n`);
+    } catch {
+      // The final containment boundary must remain total even under memory
+      // pressure or a damaged record.
+    }
+    try {
+      console.error(diagnostic);
+    } catch {
+      // stderr can itself be unavailable during process teardown.
+    }
+  }
+
+  function guarded(job: Job | undefined, operation: string, callback: () => void): void {
+    try {
+      callback();
+    } catch (error) {
+      recordOperationalError(job, operation, error);
+    }
+  }
+
+  function runDetached(job: Job | undefined, operation: string, callback: () => Promise<void>): void {
+    const fail = (error: unknown): void => {
+      recordOperationalError(job, operation, error);
+      if (!job || job.status !== "running") return;
+      job.polling = false;
+      job.status = "failed";
+      wake(
+        `[${job.kind} #${job.id} "${job.label}" stopped after an internal ${operation} failure]. Read the diagnostic with the jobs tool (action=tail, jobId=${job.id}).`,
+        {},
+        job,
+      );
+      finalize(job);
+    };
+    try {
+      void callback().catch(fail);
+    } catch (error) {
+      fail(error);
+    }
+  }
+
+  function snapshot(job?: Job): void {
+    guarded(job, "persisting job registry", () => {
+      pi.appendEntry?.("background-tasks", {
+        jobs: Array.from(jobs.values()).map((j) => ({
+          id: j.id,
+          kind: j.kind,
+          label: j.label,
+          command: j.command,
+          status: j.status,
+        })),
+      });
     });
   }
 
@@ -354,8 +412,8 @@ export default function backgroundTasksExtension(pi: PiApi): void {
   /** The last ctx.ui seen by any tool call — used to refresh visuals from async callbacks. */
   let lastUi: UiContext | undefined;
 
-  function refreshVisuals(): void {
-    updateStatus(lastUi);
+  function refreshVisuals(job?: Job): void {
+    guarded(job, "refreshing background status", () => updateStatus(lastUi));
   }
 
   /**
@@ -364,7 +422,7 @@ export default function backgroundTasksExtension(pi: PiApi): void {
    * which is attacker-controlled. The agent reads the actual output on demand
    * via the jobs tool (tail/view). Returns void; the wake is best-effort.
    */
-  function wake(message: string, details: Record<string, unknown> = {}): void {
+  function wake(message: string, details: Record<string, unknown> = {}, job?: Job): void {
     if (shuttingDown) return; // don't trigger turns during/after shutdown
     const tail = message.split("\n")[0];
     const wakeDetails = { source: "background-tasks", trusted: true, ...details };
@@ -386,28 +444,30 @@ export default function backgroundTasksExtension(pi: PiApi): void {
             },
             { triggerTurn: true, deliverAs: "steer" },
           ),
-        ).catch((err) => {
-          console.error(`[background-tasks] wake failed: ${(err as Error).message}`);
+        ).catch((error) => {
+          recordOperationalError(job, "waking the agent", error);
         });
       } else if (lastUi?.notify) {
         lastUi.notify(`${tail} (auto-wake unavailable: pi.sendMessage missing)`, "info");
       } else {
         console.error(`[background-tasks] wake (no channel): ${tail}`);
       }
-    } catch (err) {
-      console.error(`[background-tasks] wake threw: ${(err as Error).message}`);
+    } catch (error) {
+      recordOperationalError(job, "waking the agent", error);
     }
   }
 
-  function notify(level: "info" | "success" | "warning" | "error", message: string): void {
-    lastUi?.notify?.(message, level);
+  function notify(level: "info" | "success" | "warning" | "error", message: string, job?: Job): void {
+    guarded(job, "notifying the user", () => lastUi?.notify?.(message, level));
   }
 
   function finalize(job: Job): void {
     job.endedAt = Date.now();
-    snapshot();
+    // Session-bound Pi/UI objects are revoked at shutdown. Late process events
+    // may still complete plain in-memory state, but must not touch those APIs.
+    if (!shuttingDown) snapshot(job);
     pruneTerminal();
-    refreshVisuals();
+    if (!shuttingDown) refreshVisuals(job);
   }
 
   /**
@@ -546,13 +606,15 @@ export default function backgroundTasksExtension(pi: PiApi): void {
         // Trusted wake: no command output, just id + the matched fact.
         wake(
           `[background job #${job.id} "${label}" matched its wake_on_pattern — still running]. Read output with the jobs tool (action=tail, jobId=${job.id}).`,
+          {},
+          job,
         );
       }
     };
-    child.stdout?.on("data", handleChunk);
-    child.stderr?.on("data", handleChunk);
+    child.stdout?.on("data", (data) => guarded(job, "capturing stdout", () => handleChunk(data)));
+    child.stderr?.on("data", (data) => guarded(job, "capturing stderr", () => handleChunk(data)));
 
-    child.on("exit", (code, signal) => {
+    child.on("exit", (code, signal) => guarded(job, "handling process exit", () => {
       if (job.status === "cancelled" || job.status === "kill_failed") return; // cancellation owns terminal state
       if (job.status === "cancelling") {
         // Reaped during cancellation (SIGTERM or SIGKILL worked) — mark cancelled.
@@ -566,26 +628,30 @@ export default function backgroundTasksExtension(pi: PiApi): void {
       const ok = code === 0;
       job.status = ok ? "completed" : "failed";
       const reason = signal ? `signal ${signal}` : `exit ${code ?? "?"}`;
-      notify(ok ? "success" : "error", `background job #${job.id} "${label}" finished: ${reason}`);
+      notify(ok ? "success" : "error", `background job #${job.id} "${label}" finished: ${reason}`, job);
       // Trusted wake: only id, label, and the status word. NO command output.
       wake(
         `[background job #${job.id} "${label}" finished: ${reason}]. Read its output with the jobs tool (action=tail, jobId=${job.id}).`,
+        {},
+        job,
       );
       finalize(job);
-    });
-    child.on("error", (err) => {
+    }));
+    child.on("error", (error) => guarded(job, "handling process error", () => {
       if (job.status !== "running" && job.status !== "cancelling") return;
       job.status = "failed";
-      notify("error", `background job #${job.id} "${label}" failed to spawn: ${err.message}`);
+      notify("error", `background job #${job.id} "${label}" failed to spawn: ${error.message}`, job);
       wake(
-        `[background job #${job.id} "${label}" failed to spawn: ${err.message}]. No command output was produced.`,
+        `[background job #${job.id} "${label}" failed to spawn: ${error.message}]. No command output was produced.`,
+        {},
+        job,
       );
       finalize(job);
-    });
+    }));
 
     jobs.set(job.id, job);
-    snapshot();
-    refreshVisuals();
+    snapshot(job);
+    refreshVisuals(job);
 
     const patternNote = wakeOnPattern
       ? `, or earlier the first time output matches /${wakePatternRaw}/`
@@ -616,6 +682,9 @@ export default function backgroundTasksExtension(pi: PiApi): void {
       };
     }
     const label = params.label ? String(params.label) : slugify(command);
+    // Capture plain data while the tool context is current. Delayed polls must
+    // never dereference a session-bound context after replacement or reload.
+    const cwd = ctx.cwd ?? process.cwd();
     const rawInterval = Number(params.interval_seconds ?? DEFAULT_MONITOR_INTERVAL_S);
     const intervalSeconds = Number.isFinite(rawInterval) && rawInterval >= MIN_MONITOR_INTERVAL_S
       ? rawInterval
@@ -659,8 +728,8 @@ export default function backgroundTasksExtension(pi: PiApi): void {
       pattern: patternRaw,
     };
     jobs.set(job.id, job);
-    snapshot();
-    refreshVisuals();
+    snapshot(job);
+    refreshVisuals(job);
 
     const evaluate = (out: string, code: number | null | undefined): boolean => {
       switch (satisfyOn) {
@@ -693,7 +762,7 @@ export default function backgroundTasksExtension(pi: PiApi): void {
         // tool's `spawn(command, { shell: "/bin/sh" })`.
         result = await pi.exec!("/bin/sh", ["-c", command], {
           timeout: Math.max(5, intervalSeconds) * 1000,
-          cwd: ctx.cwd ?? process.cwd(),
+          cwd,
         });
       } catch (err) {
         result = { stderr: (err as Error).message, code: null };
@@ -724,9 +793,11 @@ export default function backgroundTasksExtension(pi: PiApi): void {
         job.exitCode = result.code ?? undefined;
         job.status = "timeout";
         const hint = `every poll failed to run its command (command not found in stderr). The poll command likely references a missing/typo'd binary or tool`;
-        notify("error", `monitor #${job.id} "${label}" aborting: ${hint}. Check the poll command.`);
+        notify("error", `monitor #${job.id} "${label}" aborting: ${hint}. Check the poll command.`, job);
         wake(
           `[monitor #${job.id} "${label}" aborted after ${job.pollFailures} consecutive broken polls: ${hint}. Read the last poll with the jobs tool (action=tail, jobId=${job.id}) and fix the command.`,
+          {},
+          job,
         );
         finalize(job);
         return;
@@ -735,10 +806,12 @@ export default function backgroundTasksExtension(pi: PiApi): void {
       if (evaluate(result.stdout ?? "", result.code)) {
         job.exitCode = result.code ?? undefined;
         job.status = "satisfied";
-        notify("success", `monitor #${job.id} "${label}" satisfied (${satisfyOn})`);
+        notify("success", `monitor #${job.id} "${label}" satisfied (${satisfyOn})`, job);
         // Trusted wake: no command output.
         wake(
           `[monitor #${job.id} "${label}" satisfied: ${satisfyOn}, exit ${result.code ?? "?"}]. Read the result with the jobs tool (action=tail, jobId=${job.id}).`,
+          {},
+          job,
         );
         finalize(job);
         return;
@@ -746,19 +819,25 @@ export default function backgroundTasksExtension(pi: PiApi): void {
       if (Date.now() >= (job.deadline ?? 0)) {
         job.exitCode = result.code ?? undefined;
         job.status = "timeout";
-        notify("warning", `monitor #${job.id} "${label}" timed out after ${timeoutSeconds}s`);
+        notify("warning", `monitor #${job.id} "${label}" timed out after ${timeoutSeconds}s`, job);
         wake(
           `[monitor #${job.id} "${label}" timed out after ${timeoutSeconds}s without satisfying ${satisfyOn}]. Read the last poll with the jobs tool (action=tail, jobId=${job.id}).`,
+          {},
+          job,
         );
         finalize(job);
         return;
       }
       // Schedule the NEXT poll only after this one finished -> no overlap.
-      job.timer = setTimeout(() => void tick(), intervalSeconds * 1000);
+      job.timer = setTimeout(
+        () => runDetached(job, "running monitor poll", tick),
+        intervalSeconds * 1000,
+      );
     };
 
-    // First tick immediately so short conditions resolve fast.
-    void tick();
+    // First tick immediately so short conditions resolve fast. A monitor poll
+    // runs outside Pi's awaited tool boundary, so contain every rejection here.
+    runDetached(job, "running monitor poll", tick);
 
     return {
       content: [
@@ -972,12 +1051,20 @@ export default function backgroundTasksExtension(pi: PiApi): void {
   // Await cancellations so SIGTERM/SIGKILL escalation actually completes before
   // the process tears down (a fire-and-forget timer could be killed mid-escalate).
   pi.on?.("session_shutdown", async () => {
+    // Set the fence before the first await. Any process event that arrives
+    // during teardown may finish its in-memory state, but must not start a new
+    // turn. Clear the retained UI before Pi invalidates this extension context.
     shuttingDown = true;
-    await Promise.all(
-      Array.from(jobs.values())
-        .filter((j) => j.status === "running" || j.status === "cancelling")
-        .map((j) => cancelJob(j)),
+    lastUi = undefined;
+    const active = Array.from(jobs.values()).filter(
+      (job) => job.status === "running" || job.status === "cancelling",
     );
+    const outcomes = await Promise.allSettled(active.map((job) => cancelJob(job)));
+    outcomes.forEach((outcome, index) => {
+      if (outcome.status === "rejected") {
+        recordOperationalError(active[index], "cancelling job during session shutdown", outcome.reason);
+      }
+    });
   });
 }
 

package/node_modules/@nklisch/pi-background-tasks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nklisch/pi-background-tasks",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Pi-native runtime tools — background a long command and get woken on exit, poll a command until a condition holds, and manage the job registry.",
   "author": {
     "name": "nklisch"

package/node_modules/@nklisch/pi-background-tasks/skills/background-tasks/SKILL.md

@@ -129,10 +129,9 @@ manage waiting itself. This is intentional harness-specific surface — the
 portable knowledge is the when/why above; the executable ergonomics live in the
 extension.
 
-**Known limitation — session scoping.** The job registry, wake channel, and UI
-handles are process-global within a single pi process, not per-session. If you
-switch or fork sessions while a background job is still running, that job's
-completion can still fire and wake/notify the *current* session rather than the
-one that started it. For long jobs that may outlive a session switch, prefer
-starting them in the session you intend to receive the wake, or cancel before
-switching. (Per-session scoping is a future improvement.)
+**Session lifecycle.** Jobs belong to the extension instance that started them.
+Session replacement, fork, reload, and shutdown cancel its running processes and
+monitors before Pi revokes that instance. Detached callbacks retain only plain
+job data; they never reuse an old command context, and a late process event is
+contained without waking or notifying the replacement session. Start a new job
+in the replacement session when work should continue there.

package/node_modules/@nklisch/pi-clearance/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nklisch/pi-clearance",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Configurable auto-reviewer Pi extension for parsed, structural command policy",
   "type": "module",
   "license": "MIT",

package/node_modules/@nklisch/pi-clearance/src/config/config-command-writer.ts

@@ -114,6 +114,10 @@ interface AtomicConfigWriteInput {
   ) => Promise<ConfigCommandPostWriteValidationResult>;
   readonly writeFailureReason: string;
   readonly postWriteFailureReason: string;
+  /** Test seam for deterministic failure coverage; production uses fs rename. */
+  readonly renameTempFile?: (sourcePath: string, targetPath: string) => Promise<void>;
+  /** Test seam for deterministic cleanup failure coverage. */
+  readonly cleanupTempFile?: (tempPath: string) => Promise<void>;
 }
 
 /**
@@ -208,22 +212,25 @@ export async function writeConfigTargetAndValidate(
   let tempPresent = false;
   let renamed = false;
   let backupCreated = false;
+  let result: ConfigCommandApplyResult;
 
   try {
     await mkdir(path.dirname(input.targetPath), { recursive: true });
+    // Mark the path before writing: if the write rejects after creating a
+    // partial file, the same best-effort cleanup still runs.
+    tempPresent = true;
     await writeFile(
       tempPath,
       serializeSparseConfigText(input.configKind, input.value),
       "utf8",
     );
-    tempPresent = true;
 
     if (input.hadExistingFile) {
       await copyFile(input.targetPath, backupPath);
       backupCreated = true;
     }
 
-    await rename(tempPath, input.targetPath);
+    await (input.renameTempFile ?? rename)(tempPath, input.targetPath);
     tempPresent = false;
     renamed = true;
 
@@ -235,7 +242,7 @@ export async function writeConfigTargetAndValidate(
         backupPath,
         input.hadExistingFile,
       );
-      return {
+      result = {
         ok: false,
         planId: input.planId,
         targetPath: input.targetPath,
@@ -244,17 +251,17 @@ export async function writeConfigTargetAndValidate(
         restored,
         errors: policyValidation.errors,
       };
+    } else {
+      result = {
+        ok: true,
+        planId: input.planId,
+        changed: true,
+        targetPath: input.targetPath,
+        ...(backupCreated ? { backupPath } : {}),
+        resolvedConfig,
+        warnings: policyValidation.warnings ?? [],
+      };
     }
-
-    return {
-      ok: true,
-      planId: input.planId,
-      changed: true,
-      targetPath: input.targetPath,
-      ...(backupCreated ? { backupPath } : {}),
-      resolvedConfig,
-      warnings: policyValidation.warnings ?? [],
-    };
   } catch (error) {
     const restored = renamed
       ? await restoreAfterFailedValidation(
@@ -263,7 +270,7 @@ export async function writeConfigTargetAndValidate(
           input.hadExistingFile,
         )
       : false;
-    return {
+    result = {
       ok: false,
       planId: input.planId,
       targetPath: input.targetPath,
@@ -272,11 +279,21 @@ export async function writeConfigTargetAndValidate(
       restored,
       errors: [errorMessage(error)],
     };
-  } finally {
-    if (tempPresent) {
-      await unlinkIfExists(tempPath);
+  }
+
+  if (tempPresent) {
+    try {
+      await (input.cleanupTempFile ?? unlinkIfExists)(tempPath);
+    } catch (error) {
+      const diagnostic = `temporary config file cleanup failed: ${errorMessage(error)}`;
+      console.error(`Pi Clearance ${diagnostic}`);
+      result = result.ok
+        ? { ...result, warnings: [...result.warnings, diagnostic] }
+        : { ...result, errors: [...result.errors, diagnostic] };
     }
   }
+
+  return result;
 }
 
 export function applyJsonPatchDocument(

package/node_modules/@nklisch/pi-clearance/src/index.ts

@@ -170,9 +170,17 @@ const piAutoApprove: ExtensionFactory = (pi: ExtensionAPI) => {
   });
   pi.on("session_start", handleSessionStart);
   pi.on("session_shutdown", (_event, ctx) => {
-    operatorStatus.clear(ctx);
-    packageRegistration.dispose();
-    transformStore.dispose();
+    // These resources are independent. A failed unsubscribe or status cleanup
+    // must not strand the remaining listener on a persistent Pi event bus.
+    containSessionShutdownCleanup("operator status", () => {
+      operatorStatus.clear(ctx);
+    });
+    containSessionShutdownCleanup("package registration", () => {
+      packageRegistration.dispose();
+    });
+    containSessionShutdownCleanup("command transforms", () => {
+      transformStore.dispose();
+    });
   });
 
   pi.on(
@@ -223,4 +231,27 @@ function toolMetadata(pi: ExtensionAPI): {
   }
 }
 
+function containSessionShutdownCleanup(
+  resource: string,
+  cleanup: () => void,
+): void {
+  try {
+    cleanup();
+  } catch (error) {
+    // Shutdown is an out-of-band lifecycle callback. Keep the failure visible,
+    // but continue independently through every owned resource cleanup.
+    console.error(
+      `Pi Clearance session shutdown cleanup failed for ${resource}: ${errorMessage(error)}`,
+    );
+  }
+}
+
+function errorMessage(error: unknown): string {
+  try {
+    return error instanceof Error ? error.message : String(error);
+  } catch {
+    return "unknown error";
+  }
+}
+
 export default piAutoApprove;