@nothumanwork/pi-memory 0.2.0 → 0.2.1

package/README.md

@@ -42,6 +42,8 @@ PI_MEMORY_CAPTURE=0 pi -e ./pi-memory/index.ts --memory-dir /tmp/pi-memory-trial
 
 Automatic capture uses the editable `AGENT.md` policy plus a code-owned validation contract. It skips small, ordinary turns, redacts common credential shapes, ignores credential-file reads, requires source entry IDs, and rejects unsupported candidates with diagnostics. Reconciliation is validated before committing. Corrections supersede old items and retain their evidence in the archive. A pending capture can resume after interruption. Memory is historical evidence; current instructions and verified files take precedence.
 
+With `capture.onCompact` (default on), each compaction is followed by a capture of the branch it compacted. It runs as a durable [pi-durable](https://www.npmjs.com/package/@earendil-works/pi-durable) job, so neither compaction nor the next prompt waits for it. A compaction that another extension cancels or defers captures nothing. `capture.timeoutMs` (120000) bounds each attempt; a failed attempt is retried `capture.retries` times (2), first after `capture.retryDelayMs` (30000) and then doubling. A job that Pi's exit interrupts resumes when the session next opens. If every attempt fails, the evidence stays uncaptured for a later pass, with a notice.
+
 An invalid edit proposal can receive one corrective curator call per capture pass. Failed output is diagnosed and skipped instead of retried indefinitely; transport failures remain retryable. Unchanged facts in a bundled record are preserved when a correction edits one part.
 
 ## Settings
@@ -53,7 +55,7 @@ Add a `memory` object to Pi's `settings.json`:
   "memory": {
     "enabled": true,
     "mode": "inject",
-    "capture": { "enabled": true, "model": "openai/gpt-6.1-sol", "onCompact": true },
+    "capture": { "enabled": true, "model": "openai/gpt-6.1-sol", "onCompact": true, "timeoutMs": 120000, "retries": 2, "retryDelayMs": 30000 },
     "retrieval": { "maxItems": 8, "budgetTokens": 1200, "sessionBudgetTokens": 0, "timeoutMs": 2500 },
     "digest": { "budgetTokens": 1200, "scope": "decisions" },
     "consolidation": { "everyCaptures": 20 },

package/index.ts

@@ -1,5 +1,6 @@
 import { appendFile, readFile, writeFile, rename } from "node:fs/promises";
-import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { getAgentDir, SessionManager, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
@@ -7,7 +8,8 @@ import { readConfig, model as validateModel, type MemoryConfig } from "./src/con
 import { MemoryStore, serializeMemory, evidenceHash } from "./src/store.ts";
 import { resolveProjectKey } from "./src/project.ts";
 import { estimateTokens, isExpired, renderMemories, selectMemories } from "./src/retrieve.ts";
-import { CapturePipeline } from "./src/capture.ts";
+import { CapturePipeline, type CaptureResult } from "./src/capture.ts";
+import { JobQueue } from "./src/jobs.ts";
 import { DreamPipeline } from "./src/dream.ts";
 import { IdleScheduler } from "./src/scheduler.ts";
 import { ProposalManager, type ProposalKind, type Proposal } from "./src/maintenance.ts";
@@ -21,11 +23,20 @@ const GUIDANCE = "Use relevant remembered facts and user-confirmed decisions to
 
 const CAPTURE_DISABLED = "Capture is disabled. Set memory.capture.model to an explicit provider/modelId (or --memory-model / PI_MEMORY_MODEL) to enable it.";
 const DREAM_DISABLED = "Dreaming is disabled. Set memory.dream.model to an explicit provider/modelId to enable it.";
+// Longest a session switch or shutdown waits for capture jobs to stop; unfinished jobs resume next time.
+const CLOSE_MS = 2000;
+
+/** A capture of the branch as it was when Pi compacted, run as a durable background job. */
+interface CaptureJob { sessionFile?: string; leafId?: string; injectedIds: string[] }
 
 export default function memoryExtension(pi: ExtensionAPI): void {
   let config: MemoryConfig | undefined, store: MemoryStore | undefined, pipeline: CapturePipeline | undefined, proposals: ProposalManager | undefined, dream: DreamPipeline | undefined;
   let digest = "", modal = false, pending: Promise<void> | undefined, controller: AbortController | undefined, captures = 0;
   let background: IdleScheduler<ExtensionContext> | undefined, dreamWanted = false;
+  // Compaction captures run as jobs that retry and survive restarts; `session` is the context they run in.
+  let jobs: Promise<JobQueue<CaptureJob, CaptureResult>> | undefined, session: ExtensionContext | undefined;
+  // Compaction captures share the pipeline, so they run one at a time; an aborted attempt makes way at once.
+  let jobTurn: Promise<void> = Promise.resolve();
   const injected = new Map<string, string | undefined>();
   const retired = new Set<string>(), digestVersions = new Map<string, string>();
   // Recall tokens already injected into the current session branch; enforces retrieval.sessionBudgetTokens across process restarts.
@@ -76,42 +87,115 @@ export default function memoryExtension(pi: ExtensionAPI): void {
     }
   };
 
+  /** One capture pass: resume a pending delta, capture the branch, then record the outcome. Rejects on failure. */
+  async function capturePass(current: CapturePipeline, ctx: ExtensionContext, signal: AbortSignal, injectedIds: () => string[], force: boolean): Promise<CaptureResult> {
+    const resumed = await current.resumePending(ctx, signal);
+    const captured = await current.capture(ctx, signal, injectedIds(), force);
+    const rejected = [...(resumed.rejected ?? []), ...(captured.rejected ?? [])];
+    const outcome = { saved: resumed.saved + captured.saved, skipped: resumed.skipped && captured.skipped, ...(rejected.length ? { rejected } : {}) };
+    await trace({ event: "capture", ...outcome });
+    const rejection = outcome.rejected?.find(item => !item.reason.startsWith("Temporary evidence lacks") && !item.reason.startsWith("Already documented"));
+    if (rejection) notify(ctx, `Memory capture rejected output: ${rejection.reason}. Original session evidence retained.`, "error");
+    if (outcome.saved) {
+      const items = store!.list({ scope: "project" });
+      const activeBytes = items.reduce((total, item) => total + Buffer.byteLength(serializeMemory(item)), 0);
+      let schedule = { sourceCount: 0, at: Date.now(), dreamPending: false }, newSchedule = false;
+      try { schedule = JSON.parse(await readFile(maintenancePath(), "utf8")); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; newSchedule = true; }
+      const sources = items.filter(item => item.source.origin !== "consolidation").length;
+      const due = ++captures >= config!.consolidation.everyCaptures || sources - schedule.sourceCount >= config!.consolidation.everyCaptures || (sources >= 2 && Date.now() - schedule.at >= 86400000) || activeBytes >= config!.dream.softActiveBytes;
+      if (due) {
+        await store!.consolidate(); await proposals!.proposeEarned(); captures = 0;
+        dreamWanted = config!.dream.enabled;
+        await saveMaintenance({ sourceCount: sources, at: Date.now(), dreamPending: dreamWanted });
+      } else if (newSchedule) await saveMaintenance(schedule);
+    }
+    return { ...outcome, ...(captured.busy ? { busy: true } : {}) };
+  }
+
   function capture(ctx: ExtensionContext, force = false): Promise<void> | undefined {
     if (!active() || !config!.capture.enabled || !pipeline || pending) return pending;
     if (!force && (!ctx.isIdle() || ctx.hasPendingMessages() || modal || (ctx.mode === "tui" && ctx.ui.getEditorText().trim()))) return;
     controller = new AbortController();
     const signal = controller.signal;
-    const timeout = setTimeout(() => controller?.abort(), 120000);
-    const current = pipeline;
-    pending = (async () => {
-      const resumed = await current.resumePending(ctx, signal);
-      const captured = await current.capture(ctx, signal, [...injected.keys()], force);
-      const rejected = [...(resumed.rejected ?? []), ...(captured.rejected ?? [])];
-      return { saved: resumed.saved + captured.saved, skipped: resumed.skipped && captured.skipped, ...(rejected.length ? { rejected } : {}) };
-    })().then(async outcome => {
-      await trace({ event: "capture", ...outcome });
-      const rejection = outcome.rejected?.find(item => !item.reason.startsWith("Temporary evidence lacks") && !item.reason.startsWith("Already documented"));
-      if (rejection) notify(ctx, `Memory capture rejected output: ${rejection.reason}. Original session evidence retained.`, "error");
-      if (outcome.saved) {
-        const items = store!.list({ scope: "project" });
-        const activeBytes = items.reduce((total, item) => total + Buffer.byteLength(serializeMemory(item)), 0);
-        let schedule = { sourceCount: 0, at: Date.now(), dreamPending: false }, newSchedule = false;
-        try { schedule = JSON.parse(await readFile(maintenancePath(), "utf8")); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; newSchedule = true; }
-        const sources = items.filter(item => item.source.origin !== "consolidation").length;
-        const due = ++captures >= config!.consolidation.everyCaptures || sources - schedule.sourceCount >= config!.consolidation.everyCaptures || (sources >= 2 && Date.now() - schedule.at >= 86400000) || activeBytes >= config!.dream.softActiveBytes;
-        if (due) {
-          await store!.consolidate(); await proposals!.proposeEarned(); captures = 0;
-          dreamWanted = config!.dream.enabled;
-          await saveMaintenance({ sourceCount: sources, at: Date.now(), dreamPending: dreamWanted });
-        } else if (newSchedule) await saveMaintenance(schedule);
-      }
-    }).catch(error => { if (!signal.aborted) notify(ctx, `Background memory work failed; committed evidence retained: ${(error as Error).message}`, "error"); })
+    const timeout = setTimeout(() => controller?.abort(), config!.capture.timeoutMs);
+    pending = capturePass(pipeline, ctx, signal, () => [...injected.keys()], force)
+      .then(() => undefined, error => { if (!signal.aborted) notify(ctx, `Background memory work failed; committed evidence retained: ${(error as Error).message}`, "error"); })
       .finally(() => { clearTimeout(timeout); pending = undefined; controller = undefined; });
     return pending;
   }
 
+  /** One attempt of a compaction capture. It runs beside the agent, so it never holds up a prompt the way `pending` does. */
+  async function captureJob(job: CaptureJob, signal: AbortSignal): Promise<CaptureResult> {
+    const previous = jobTurn;
+    let release!: () => void;
+    jobTurn = new Promise(resolve => { release = resolve; });
+    const stopped = new Promise<never>((_resolve, reject) => signal.addEventListener("abort", () => { release(); reject(signal.reason); }, { once: true }));
+    stopped.catch(() => undefined);
+    try {
+      await Promise.race([previous, stopped]);
+      return await captureTurn(job, signal);
+    } finally { release(); }
+  }
+
+  async function captureTurn(job: CaptureJob, signal: AbortSignal): Promise<CaptureResult> {
+    const ctx = session, current = pipeline;
+    if (!ctx || !current || !active() || !config!.capture.enabled) throw new Error("Memory capture is off");
+    // The idle capture shares the pipeline; wait for it rather than be skipped as busy.
+    while (pending) await pending;
+    const live = job.sessionFile === undefined || job.sessionFile === ctx.sessionManager.getSessionFile();
+    const manager = live ? ctx.sessionManager : SessionManager.open(job.sessionFile!);
+    // Capture the branch Pi compacted, even after the session moved on or switched branches.
+    const pinned = new Proxy(manager, { get(target, property) {
+      if (property === "getBranch") return () => target.getBranch(job.leafId);
+      if (property === "getLeafId") return () => job.leafId ?? target.getLeafId();
+      const value = Reflect.get(target, property);
+      return typeof value === "function" ? value.bind(target) : value;
+    } });
+    const outcome = await capturePass(current, { ...ctx, sessionManager: pinned } as ExtensionContext, signal, () => job.injectedIds, true);
+    if (outcome.busy) throw new Error("Another memory capture was running");
+    await trace({ event: "capture-job", status: "completed", saved: outcome.saved }).catch(() => undefined);
+    return outcome;
+  }
+
+  const jobsFile = (sessionFile: string) => join(config!.dir, "capture", `${createHash("sha256").update(sessionFile).digest("hex")}.jobs.db`);
+
+  /** This session's capture jobs, opened on first use. Opening resumes the jobs an earlier process left. */
+  function captureJobs(ctx: ExtensionContext): Promise<JobQueue<CaptureJob, CaptureResult>> {
+    if (jobs) return jobs;
+    const sessionFile = ctx.sessionManager.getSessionFile();
+    const opened = JobQueue.open<CaptureJob, CaptureResult>({
+      kind: "pi-memory.capture",
+      file: sessionFile ? jobsFile(sessionFile) : undefined,
+      policy: () => ({ attempts: config!.capture.retries + 1, backoffMs: config!.capture.retryDelayMs, maxBackoffMs: 8 * config!.capture.retryDelayMs, timeoutMs: config!.capture.timeoutMs }),
+      run: captureJob,
+      failed: (error, attempt, retryAt) => {
+        void trace({ event: "capture-job", status: retryAt === undefined ? "failed" : "retrying", attempt, error: (error as Error).message, retryAt }).catch(() => undefined);
+        if (retryAt === undefined && session) notify(session, `Memory capture after compaction failed: ${(error as Error).message}. Session evidence retained for a later capture.`, "error");
+      },
+      report: error => void trace({ event: "capture-jobs", error: String(error) }).catch(() => undefined),
+    });
+    jobs = opened;
+    opened.catch(() => { if (jobs === opened) jobs = undefined; });
+    return opened;
+  }
+
+  /** Stop capture jobs: `abort` drops them, otherwise they stay stored and resume when the session opens again. */
+  async function closeJobs(abort = false): Promise<void> {
+    const opened = jobs;
+    jobs = undefined;
+    if (!opened) return;
+    const closed = opened.then(async queue => {
+      if (abort) for (const job of await queue.live()) await queue.abort(job.id);
+      await queue.close({ discard: true });
+    }).catch(() => undefined);
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    await Promise.race([closed, new Promise(resolve => { timer = setTimeout(resolve, CLOSE_MS); })]);
+    clearTimeout(timer);
+  }
+
   pi.on("session_start", async (_event, ctx) => {
     await background?.dispose(); background = undefined; dreamWanted = false;
+    await closeJobs(); session = ctx;
     controller?.abort(); await pending; store?.close(); store = undefined; pipeline = undefined; proposals = undefined; dream = undefined;
     injected.clear(); retired.clear(); digestVersions.clear(); digest = ""; captures = 0; recallTokensUsed = 0;
     try {
@@ -143,6 +227,9 @@ export default function memoryExtension(pi: ExtensionAPI): void {
         if (item) digestVersions.set(item.id, evidenceHash(item));
       }
       restoreInjected(ctx);
+      // Resume compaction captures an earlier process left; without stored jobs, pi-durable is not loaded.
+      const sessionFile = ctx.sessionManager.getSessionFile();
+      if (config.capture.enabled && sessionFile && existsSync(jobsFile(sessionFile))) void captureJobs(ctx).catch(() => undefined);
       registerMemoryTools(pi, state, config.mode);
       if (ctx.mode === "tui") { ctx.ui.addAutocompleteProvider(current => autocomplete(current, () => active() ? store : undefined)); ctx.ui.setStatus("memory", `Memory: ${store.list().length}`); }
       for (const warning of store.warnings) notify(ctx, warning, "error");
@@ -182,11 +269,21 @@ export default function memoryExtension(pi: ExtensionAPI): void {
   pi.on("agent_settled", (_event, ctx) => { const scheduler = background; void (capture(ctx) ?? Promise.resolve()).then(() => scheduler?.schedule(ctx)).catch(error => notify(ctx, String(error), "error")); });
   pi.on("ui_prompt_start", async () => { modal = true; controller?.abort(); await background?.cancel(); });
   pi.on("ui_prompt_end", () => { modal = false; });
-  pi.on("session_before_compact", async (_event, ctx) => { await background?.cancel(); if (config?.capture.onCompact) { await pending; await capture(ctx, true); } });
-  pi.on("session_compact", () => { injected.clear(); retired.clear(); });
+  // Capture once Pi has compacted, as a background job: compaction itself never waits for memory, and a
+  // compaction another extension cancels or defers captures nothing. The compacted entries stay in the session.
+  pi.on("session_compact", (event, ctx) => {
+    void background?.cancel();
+    if (active() && config!.capture.enabled && config!.capture.onCompact && pipeline) {
+      session = ctx;
+      const job: CaptureJob = { sessionFile: ctx.sessionManager.getSessionFile(), leafId: event.compactionEntry?.id ?? ctx.sessionManager.getLeafId() ?? undefined, injectedIds: [...injected.keys()] };
+      void captureJobs(ctx).then(queue => queue.enqueue(job)).catch(error => notify(ctx, `Memory capture after compaction was not started: ${(error as Error).message}`, "error"));
+    }
+    injected.clear(); retired.clear();
+  });
   pi.on("session_tree", async (_event, ctx) => { controller?.abort(); await background?.cancel(); restoreInjected(ctx); });
   pi.on("session_shutdown", async (_event, ctx) => {
     await background?.dispose();
+    await closeJobs();
     // Print/JSON runs need to finish their final capture before the process exits.
     await (pending ?? capture(ctx)); store?.close(); store = undefined;
   });
@@ -239,7 +336,7 @@ export default function memoryExtension(pi: ExtensionAPI): void {
         if (command === "on" || command === "off" || command === "mode") {
           if (command === "mode" && !["inject", "agent", "both"].includes(argument)) throw new Error("Use /memory mode inject|agent|both");
           await saveSettings(getAgentDir(), command === "mode" ? { mode: argument } : { enabled: command === "on" });
-          if (command === "off" && config) { config.enabled = false; controller?.abort(); await background?.cancel(); await pending; }
+          if (command === "off" && config) { config.enabled = false; controller?.abort(); await background?.cancel(); await closeJobs(true); await pending; }
           notify(ctx, `Saved. ${command === "off" ? "Memory is off." : "Use /reload to activate; command-line and project settings retain precedence."}`); return;
         }
         if (command === "model") {
@@ -342,7 +439,7 @@ export default function memoryExtension(pi: ExtensionAPI): void {
           if (rest.some(v => v.startsWith("--") && !["--yes", "--archive-only", "--including-codified"].includes(v))) throw new Error("Unsupported clear option; no changes made");
           const confirmed = ctx.hasUI ? await ctx.ui.confirm("Clear memory", `Remove ${scope} memory files and derived artifacts?`) : rest.includes("--yes");
           if (!confirmed) { notify(ctx, "No changes. Non-interactive clearing requires --yes."); return; }
-          controller?.abort(); await background?.cancel(); await pending; dreamWanted = false;
+          controller?.abort(); await background?.cancel(); await closeJobs(true); await pending; dreamWanted = false;
           const cleanup = await proposals!.cleanup(scope, rest.includes("--including-codified"));
           // Checkpoint current evidence without re-extracting it at shutdown after an explicit clear.
           await pipeline!.discardCurrent(ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nothumanwork/pi-memory",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Scoped, evidence-backed memory for Pi with automatic capture and evaluated recall",
   "keywords": [
@@ -33,6 +33,10 @@
     "test": "tsx --test test/*.test.ts && node --test eval/*.test.mjs",
     "eval": "node --import tsx eval/run.mjs"
   },
+  "dependencies": {
+    "@earendil-works/chord": "1.4.0",
+    "@earendil-works/pi-durable": "1.4.0"
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-ai": "*",

package/src/capture.ts

@@ -8,7 +8,8 @@ import { MEMORY_TYPES, type MemoryInput, type MemoryItem, type FeedbackVerdict }
 import { redactSecrets, redactObject, isSuspiciousMemory } from './secrets.ts';
 
 export interface CaptureOptions { root: string; projectKey: string; model?: string; minTokens?: number }
-export interface CaptureResult { saved: number; skipped: boolean; rejected?: Array<{ candidate: number; reason: string }> }
+/** busy: skipped because another capture was running, so nothing was processed. */
+export interface CaptureResult { saved: number; skipped: boolean; busy?: boolean; rejected?: Array<{ candidate: number; reason: string }> }
 interface Evidence { id: string; role: string; text: string; timestamp?: string; isError?: boolean }
 interface CaptureState { processed: string[]; pending?: { entries: string[]; sessionFile?: string; projectKey: string; leafId?: string } }
 class InvalidCaptureOutput extends Error {}
@@ -192,7 +193,7 @@ export class CapturePipeline {
     catch (error) { if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error; }
   }
   async capture(ctx: ExtensionContext, signal: AbortSignal, injectedIds: string[] = [], force = false): Promise<CaptureResult> {
-    if (this.busy) return { saved: 0, skipped: true };
+    if (this.busy) return { saved: 0, skipped: true, busy: true };
     this.busy = true;
     try { return await this.run(ctx, signal, injectedIds, force); } finally { this.busy = false; }
   }

package/src/config.ts

@@ -5,7 +5,8 @@ export interface MemoryConfig {
   enabled: boolean;
   mode: "inject" | "agent" | "both";
   dir: string;
-  capture: { enabled: boolean; model?: string; onCompact: boolean };
+  /** onCompact captures as a background job: timeoutMs bounds each attempt, retries follow after retryDelayMs, doubling. */
+  capture: { enabled: boolean; model?: string; onCompact: boolean; timeoutMs: number; retries: number; retryDelayMs: number };
   /** sessionBudgetTokens: cumulative ceiling on recall tokens injected into one session branch; 0 means no ceiling. */
   retrieval: { model?: string; maxItems: number; budgetTokens: number; sessionBudgetTokens: number; timeoutMs: number; strategy: "baseline" | "improved" };
   /** scope "rules": compiled standing feedback/preference rules only. "decisions": also user-stated durable project decisions, selected live when no compiled digest exists. */
@@ -59,7 +60,7 @@ export function readConfig(settings: unknown, agentDir: string, flags: Record<st
   return {
     enabled: flags["no-memory"] !== true && !/^(1|true|yes)$/i.test(env.PI_MEMORY_DISABLED ?? "") && bool(m.enabled, true),
     mode, dir: resolve(dir.replace(/^~(?=\/|$)/, homedir())),
-    capture: { enabled: env.PI_MEMORY_CAPTURE !== "0" && captureModel !== undefined && bool(capture.enabled, true), model: captureModel, onCompact: bool(capture.onCompact, true) },
+    capture: { enabled: env.PI_MEMORY_CAPTURE !== "0" && captureModel !== undefined && bool(capture.enabled, true), model: captureModel, onCompact: bool(capture.onCompact, true), timeoutMs: number(capture.timeoutMs, 120000, 1000, 600000), retries: number(capture.retries, 2, 0, 10), retryDelayMs: number(capture.retryDelayMs, 30000, 10, 3600000) },
     retrieval: { model: model(env.PI_MEMORY_RETRIEVAL_MODEL ?? retrieval.model), maxItems: number(retrieval.maxItems, 8, 1, 32), budgetTokens: number(env.PI_MEMORY_TOKEN_BUDGET === undefined ? retrieval.budgetTokens : Number(env.PI_MEMORY_TOKEN_BUDGET), 1200, 128, 8000), sessionBudgetTokens: number(env.PI_MEMORY_SESSION_BUDGET === undefined ? retrieval.sessionBudgetTokens : Number(env.PI_MEMORY_SESSION_BUDGET), 0, 0, 200000), timeoutMs: number(retrieval.timeoutMs, 2500, 100, 30000), strategy: strategy === "baseline" ? "baseline" : "improved" },
     digest: { budgetTokens: number(env.PI_MEMORY_DIGEST_BUDGET === undefined ? digest.budgetTokens : Number(env.PI_MEMORY_DIGEST_BUDGET), 1200, 0, 8000), scope: digestScope },
     scope: { projectLocation: location },

package/src/jobs.ts

@@ -0,0 +1,313 @@
+// Vendored in pi-background-compaction and pi-memory, which publish separately: keep both copies identical.
+import { mkdir, rm } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { Context } from "@earendil-works/chord/context";
+import type { Conversation, Harness, SessionDocToken, SetTimer, Storage, Task, TaskId } from "@earendil-works/pi-durable";
+
+/** How a job is retried. */
+export interface RetryPolicy {
+	/** Attempts per job, including the first. */
+	attempts: number;
+	/** Wait before the second attempt; it doubles for each later one, up to `maxBackoffMs`. */
+	backoffMs: number;
+	maxBackoffMs: number;
+	/** Each attempt is aborted after this long. */
+	timeoutMs: number;
+}
+
+/** A failure that another attempt cannot fix, such as a missing model: the job fails at once. */
+export class PermanentError extends Error {}
+
+export type JobOutcome<R> = { status: "completed"; result: R } | { status: "failed"; error: string } | { status: "aborted" };
+
+export interface JobOptions<I, R> {
+	/** Durable task name, unique to the extension. */
+	kind: string;
+	/** SQLite file for the jobs. Without one, or while another process holds it, jobs are kept in memory. */
+	file?: string;
+	policy(): RetryPolicy;
+	/** One attempt. Input and result are JSON; an attempt may run again after a restart, so it must be safe to repeat. */
+	run(input: I, signal: AbortSignal, attempt: number): Promise<R>;
+	/** An attempt failed: `retryAt` is when the next one starts, or undefined when the job has failed. */
+	failed?(error: unknown, attempt: number, retryAt: number | undefined): void;
+	/**
+	 * Called once on opening, before any job runs, with what an earlier process left: its unsettled jobs
+	 * and its last completed one. Abort the jobs that are no longer wanted; the rest resume.
+	 */
+	recover?(queue: JobQueue<I, R>, found: Recovered<I, R>): Promise<void> | void;
+	/** Failures outside a job's own attempts, such as storage errors. */
+	report?(error: unknown): void;
+	now?: () => number;
+	setTimer?: SetTimer;
+}
+
+export interface Recovered<I, R> {
+	live: { id: number; input: I; status: string }[];
+	latest?: { id: number; input: I; result: R };
+}
+
+type Checkpoint = { phase: "run"; attempt: number } | { phase: "backoff"; attempt: number; until: number };
+
+interface Runtime {
+	durable: typeof import("@earendil-works/pi-durable");
+	createModels: typeof import("@earendil-works/pi-ai").createModels;
+	openSqlite: typeof import("@earendil-works/pi-durable/storage/sqlite/node").openNodeSqliteStorage;
+	context: Context;
+}
+
+// Shared by every extension in the process that uses this pinned pi-durable version.
+const RUNTIME = Symbol.for("@nothumanwork/pi-durable-runtime@1.4.0");
+// Files still being closed, across reloads of the extension: a file opens only once its last close is done.
+const CLOSING = Symbol.for("@nothumanwork/pi-durable-closing");
+
+function closing(): Map<string, Promise<void>> {
+	const shared = globalThis as { [CLOSING]?: Map<string, Promise<void>> };
+	shared[CLOSING] ??= new Map();
+	return shared[CLOSING];
+}
+
+/**
+ * pi-durable, loaded once per process and shared by every extension that vendors this file. A cold
+ * load holds the event loop for about 0.2 s, so it never runs on a caller's stack: hooks that start a
+ * job return first.
+ */
+function runtime(): Promise<Runtime> {
+	const shared = globalThis as { [RUNTIME]?: Promise<Runtime> };
+	shared[RUNTIME] ??= (async () => {
+		await new Promise((resolve) => setImmediate(resolve));
+		const [durable, ai, sqlite, chord] = await Promise.all([
+			import("@earendil-works/pi-durable"),
+			import("@earendil-works/pi-ai"),
+			import("@earendil-works/pi-durable/storage/sqlite/node"),
+			import("@earendil-works/chord/context"),
+		]);
+		return { durable, createModels: ai.createModels, openSqlite: sqlite.openNodeSqliteStorage, context: chord.BACKGROUND_CONTEXT };
+	})().catch((error: unknown) => {
+		delete shared[RUNTIME];
+		throw error;
+	});
+	return shared[RUNTIME];
+}
+
+const message = (error: unknown) => (error instanceof Error ? error.message : String(error));
+
+/** Timers that never keep the process alive: a pending retry must not delay Pi's exit. */
+const unrefTimer: SetTimer = (callback, delayMs) => {
+	const timer = setTimeout(callback, delayMs);
+	timer.unref?.();
+	return () => clearTimeout(timer);
+};
+
+/** Holds `file` for this process until released; undefined when another process holds it. */
+async function claim(file: string): Promise<(() => void) | undefined> {
+	const { DatabaseSync } = await import("node:sqlite");
+	const owner = new DatabaseSync(`${file}.owner`);
+	try {
+		owner.exec("PRAGMA busy_timeout=0; PRAGMA locking_mode=EXCLUSIVE; BEGIN EXCLUSIVE; CREATE TABLE IF NOT EXISTS owner (id INTEGER)");
+	} catch (error) {
+		owner.close();
+		if ((error as { errcode?: number }).errcode === 5) return undefined;
+		throw error;
+	}
+	return () => owner.close();
+}
+
+/**
+ * Background jobs on pi-durable. Each attempt runs off the caller's path, failures are retried
+ * with backoff, and with a file the jobs and their results survive a restart.
+ */
+export class JobQueue<I, R> {
+	private readonly attempts = new Set<Promise<unknown>>();
+	private closing?: Promise<void>;
+
+	private constructor(
+		private readonly harness: Harness,
+		private readonly root: Conversation,
+		private readonly task: Task<I, Checkpoint, R, object>,
+		private readonly last: SessionDocToken<{ last: number | null }>,
+		private readonly context: Context,
+		private readonly options: JobOptions<I, R>,
+		private readonly release: (() => void) | undefined,
+		/** The SQLite file, when the jobs survive a restart. */
+		readonly file: string | undefined,
+	) {}
+
+	static async open<I, R>(options: JobOptions<I, R>): Promise<JobQueue<I, R>> {
+		const { durable, createModels, openSqlite, context } = await runtime();
+		let storage: Storage | undefined;
+		let release: (() => void) | undefined;
+		if (options.file) {
+			try {
+				await closing().get(options.file);
+				await mkdir(dirname(options.file), { recursive: true, mode: 0o700 });
+				release = await claim(options.file);
+				if (release) storage = await openSqlite(options.file);
+			} catch (error) {
+				release?.();
+				release = undefined;
+				options.report?.(error);
+			}
+		}
+		const last = durable.defineDoc<{ last: number | null }>({
+			kind: `${options.kind}.last`,
+			version: 1,
+			scope: "session",
+			initial: () => ({ last: null }),
+			checkpointWhen: () => true,
+		});
+		let queue: JobQueue<I, R> | undefined;
+		const task = durable.defineTask<I, Checkpoint, R>({
+			name: options.kind,
+			version: 1,
+			initial: () => ({ phase: "run", attempt: 1 }),
+			phases: {
+				backoff: (job, runtime, ctx) =>
+					runtime.sleepUntil(job.state.checkpoint.until, { phase: "run", attempt: job.state.checkpoint.attempt }, ctx),
+				run: async (job, runtime, ctx) => {
+					const { attempt } = job.state.checkpoint;
+					const policy = options.policy();
+					const timeout = new AbortController();
+					const disarm = runtime.setTimer(() => timeout.abort(new Error(`timed out after ${policy.timeoutMs} ms`)), policy.timeoutMs);
+					const signal = AbortSignal.any([runtime.signal, timeout.signal]);
+					// An attempt that ignores its signal still ends at an abort or its timeout; its late result is dropped.
+					const stopped = new Promise<never>((_resolve, reject) => {
+						if (signal.aborted) reject(signal.reason);
+						else signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+					});
+					const work = Promise.race([Promise.resolve().then(() => options.run(job.input, signal, attempt)), stopped]);
+					const tracked = work.catch(() => undefined);
+					queue?.attempts.add(tracked);
+					try {
+						const result = await work;
+						await runtime.commit(async (tx) => {
+							(await tx.doc(last)).last = Number(job.id);
+							return { status: "terminal", outcome: { status: "completed", result } };
+						}, ctx);
+					} catch (error) {
+						// Closing or an explicit abort: the abort phase, or the next process, takes over.
+						if (runtime.signal.aborted) throw error;
+						const retry = !(error instanceof PermanentError) && attempt < policy.attempts;
+						const until = retry ? runtime.now() + Math.min(policy.backoffMs * 2 ** (attempt - 1), policy.maxBackoffMs) : undefined;
+						options.failed?.(error, attempt, until);
+						await runtime.commit(
+							() =>
+								until === undefined
+									? { status: "terminal", outcome: { status: "failed", error: { message: message(error) } } }
+									: { status: "running", checkpoint: { phase: "backoff", attempt: attempt + 1, until } },
+							ctx,
+						);
+					} finally {
+						disarm();
+						queue?.attempts.delete(tracked);
+					}
+				},
+			},
+			abort: (_job, runtime, ctx) => runtime.commit(() => ({ status: "terminal", outcome: { status: "aborted" } }), ctx),
+		});
+		const registry = durable.createRegistry();
+		registry.install(durable.defineExtension({ name: options.kind, tasks: [task] }));
+		let harness: Harness | undefined;
+		harness = await durable.Harness.open(
+			storage ?? new durable.MemoryStorage(),
+			{
+				models: createModels(),
+				registry,
+				now: options.now,
+				setTimer: options.setTimer ?? unrefTimer,
+				onReport: (error, info) => {
+					// A job interrupted by too many restarts is given up rather than left parked.
+					if (info.type === "task_parked") void harness?.abortTask(info.task.id, context).catch(() => undefined);
+					options.report?.(error);
+				},
+			},
+			context,
+		);
+		const root = await harness.root(context);
+		queue = new JobQueue<I, R>(harness, root, task, last, context, options, release, storage ? options.file : undefined);
+		if (options.recover) {
+			try {
+				await options.recover(queue, { live: await queue.live(), latest: await queue.latest() });
+			} catch (error) {
+				options.report?.(error);
+			}
+		}
+		harness.resume();
+		return queue;
+	}
+
+	/** Start a job; it runs in the background. */
+	async enqueue(input: I): Promise<number> {
+		// Stored input is JSON: drop undefined fields rather than fail the commit.
+		const json = JSON.parse(JSON.stringify(input)) as I;
+		const id = await this.root.commit((tx) => tx.createTask(this.task, json, { ownership: { kind: "conversation" }, background: true }), this.context);
+		this.harness.resume();
+		return Number(id);
+	}
+
+	/** The job's outcome once it settles. A job left unsettled by closing the queue reports aborted. */
+	async wait(id: number): Promise<JobOutcome<R>> {
+		try {
+			const settled = await this.harness.waitForTask(id as TaskId<R>, this.context);
+			const outcome = settled.state.outcome;
+			if (outcome.status === "completed") return { status: "completed", result: outcome.result };
+			if (outcome.status === "failed" || outcome.status === "faulted") return { status: "failed", error: outcome.error.message };
+			return { status: "aborted" };
+		} catch {
+			return { status: "aborted" };
+		}
+	}
+
+	/** Stop a job: a running attempt is aborted and no retry follows. */
+	async abort(id: number): Promise<void> {
+		await this.harness.abortTask(id as TaskId, this.context).catch(() => undefined);
+	}
+
+	/** Jobs not yet settled, including those an earlier process left. */
+	async live(): Promise<{ id: number; input: I; status: string }[]> {
+		const { tasks } = await this.harness.inspect(this.context);
+		return tasks
+			.filter((item) => item.record.kind === this.options.kind && !item.record.abortRequested)
+			.map((item) => ({ id: Number(item.record.id), input: item.record.input as I, status: item.record.state.status }));
+	}
+
+	/** The most recently completed job, with its result. */
+	async latest(): Promise<{ id: number; input: I; result: R } | undefined> {
+		const id = (await this.harness.snapshot(this.last, this.context))?.last;
+		if (id === null || id === undefined) return undefined;
+		const record = await this.harness.getTask(id as TaskId<R>, this.context);
+		if (record?.state.status !== "terminal" || record.state.outcome.status !== "completed") return undefined;
+		return { id, input: record.input as I, result: record.state.outcome.result };
+	}
+
+	/** Resolves when no attempt is running in this process; jobs waiting to retry do not count. */
+	async idle(): Promise<void> {
+		while (this.attempts.size) await Promise.all([...this.attempts]);
+	}
+
+	/**
+	 * Stop running attempts. Unsettled jobs stay stored and resume when the file is opened again;
+	 * `discard` deletes the file when none is left.
+	 */
+	close(options: { discard?: boolean } = {}): Promise<void> {
+		if (this.closing) return this.closing;
+		const file = this.file;
+		const done = (async () => {
+			let live = 1;
+			try {
+				live = (await this.live()).length;
+			} catch (error) {
+				this.options.report?.(error);
+			}
+			await this.harness.close(this.context).catch((error: unknown) => this.options.report?.(error));
+			this.release?.();
+			if (!options.discard || !file || live > 0) return;
+			for (const suffix of ["", "-wal", "-shm", "-journal", ".owner"]) await rm(file + suffix, { force: true });
+		})();
+		const closed = done.finally(() => {
+			if (file && closing().get(file) === closed) closing().delete(file);
+		});
+		this.closing = closed;
+		if (file) closing().set(file, closed);
+		return closed;
+	}
+}