@humwick/runner 0.0.0-stage → 0.130.0

package/src/outbox.ts

@@ -0,0 +1,453 @@
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { sanitizeFsName } from "@humwick/sdk/fs-name";
+import { errMessage } from "@humwick/sdk";
+import { logger } from "./logger";
+import { runnerOutboxDirFromEnv } from "./config";
+import { isDeterministicClientError, isTransientDeliveryError } from "./runner-helpers";
+
+// Phase 2 (#196) — the "nothing is ever lost" half. Runner→server events that used to be
+// fire-and-forget over HTTP (session turns, reasoning/tool traces, prompt echoes, insights,
+// hook-fatal reports) were silently dropped whenever the server was momentarily down. This
+// is a durable, FIFO, disk-backed queue that:
+//   - survives Runner/server restart (bun:sqlite file in the runtime dir),
+//   - stamps true event time (`occurredAt`) once at enqueue and preserves it through retries,
+//   - retries with capped exponential backoff, strictly in order (an append log must not
+//     reorder turns),
+//   - poisons a DETERMINISTICALLY-failing head immediately and an unknown-failure head after
+//     maxAttempts so it can't block the queue — but NEVER poisons on attempt count for
+//     TRANSIENT (connection-class / 5xx / 429) failures (#2433): report-up chat rides this
+//     queue, so a poisoned row is real message loss. A transient head instead parks onto a
+//     slow periodic re-drive after a long CONTINUOUS-failure wall-clock budget, so an ordinary
+//     relay-restart window can't drop anything no matter how hard flush() hammers,
+//   - is bounded with a logged drop policy (never silently truncates).
+//
+// Status deliberately does NOT go through here: it rides the WebSocket bus, which is
+// last-wins and self-heals on reconnect (so it already satisfies "coalesce, don't replay
+// stale busyes"). The coalesce mode below exists so a future state event could migrate here.
+
+type OutboxMode = "append" | "coalesce";
+
+interface OutboxEventInput {
+  kind: string;
+  payload: unknown;
+  mode?: OutboxMode;
+  // Required for coalesce mode: prior un-poisoned rows with the same dedupeKey are replaced.
+  dedupeKey?: string;
+  // Defaults to now. Set explicitly only to backdate (e.g. replaying a captured timestamp).
+  occurredAt?: number;
+  // Defaults to a stable derived key so server-side dedup makes retries exactly-once.
+  idempotencyKey?: string;
+}
+
+export interface OutboxRecord {
+  seq: number;
+  kind: string;
+  mode: OutboxMode;
+  occurredAt: number;
+  idempotencyKey: string;
+  payload: unknown;
+  attempts: number;
+}
+
+// The transport. Resolve = delivered (row deleted). Reject = failed (retried with backoff).
+type OutboxSend = (record: OutboxRecord) => Promise<void>;
+
+interface OutboxOptions {
+  agentId: string;
+  send: OutboxSend;
+  // Storage directory. Defaults to AGENT_RELAY_RUNNER_OUTBOX_DIR, else a per-host temp dir.
+  dir?: string;
+  maxRows?: number;
+  maxAttempts?: number;
+  baseBackoffMs?: number;
+  maxBackoffMs?: number;
+  pollMs?: number;
+  // #2433 — transient (connection-class / 5xx / 429) failures NEVER poison on attempt count.
+  // After this much CONTINUOUS wall-clock failure on a row, park it onto a slow periodic
+  // re-drive (every transientRedriveMs) instead of hot-looping, so a long relay outage still
+  // recovers every frame once the relay returns. Sized to outlast any ordinary restart/deploy
+  // window (~11s) many times over.
+  transientParkAfterMs?: number;
+  transientRedriveMs?: number;
+  // Observability seam: called when a row is actually POISONED (permanently dropped). Only
+  // deterministic client rejections and unknown-class failures past maxAttempts get here —
+  // never transient ones. The session outbox uses it to surface mirror/report-up loss
+  // in-session (#2433) rather than only in a FATAL host log.
+  onPoison?: (record: OutboxRecord, reason: string) => void | Promise<void>;
+}
+
+const DEFAULTS = {
+  maxRows: 5000,
+  maxAttempts: 12,
+  baseBackoffMs: 1_000,
+  maxBackoffMs: 60_000,
+  pollMs: 5_000,
+  // ~5 minutes of CONTINUOUS transient failure before parking (a CD relay restart is ~11s;
+  // even a bad deploy clears well inside this), then one re-drive attempt per minute.
+  transientParkAfterMs: 300_000,
+  transientRedriveMs: 60_000,
+};
+
+// Pause between forced delivery attempts during flush() — keeps a brief server outage
+// from hot-looping while still retrying fast enough to land within the flush deadline.
+const FLUSH_RETRY_PAUSE_MS = 150;
+
+interface Row {
+  seq: number;
+  kind: string;
+  mode: string;
+  occurred_at: number;
+  idempotency_key: string;
+  payload: string;
+  attempts: number;
+  next_attempt_at: number;
+  first_failed_at: number;
+  poisoned: number;
+}
+
+export class Outbox {
+  private readonly db: Database;
+  private readonly agentId: string;
+  private readonly send: OutboxSend;
+  private readonly maxRows: number;
+  private readonly maxAttempts: number;
+  private readonly baseBackoffMs: number;
+  private readonly maxBackoffMs: number;
+  private readonly pollMs: number;
+  private readonly transientParkAfterMs: number;
+  private readonly transientRedriveMs: number;
+  private readonly onPoison?: (record: OutboxRecord, reason: string) => void | Promise<void>;
+  readonly path: string;
+
+  private draining = false;
+  private rerun = false;
+  // Set by flush() to make the next drain pass ignore per-row backoff (deliver NOW).
+  private forceDue = false;
+  private pollTimer?: ReturnType<typeof setInterval>;
+  private dueTimer?: ReturnType<typeof setTimeout>;
+  private stopped = false;
+
+  constructor(options: OutboxOptions) {
+    this.agentId = options.agentId;
+    this.send = options.send;
+    this.maxRows = options.maxRows ?? DEFAULTS.maxRows;
+    this.maxAttempts = options.maxAttempts ?? DEFAULTS.maxAttempts;
+    this.baseBackoffMs = options.baseBackoffMs ?? DEFAULTS.baseBackoffMs;
+    this.maxBackoffMs = options.maxBackoffMs ?? DEFAULTS.maxBackoffMs;
+    this.pollMs = options.pollMs ?? DEFAULTS.pollMs;
+    this.transientParkAfterMs = options.transientParkAfterMs ?? DEFAULTS.transientParkAfterMs;
+    this.transientRedriveMs = options.transientRedriveMs ?? DEFAULTS.transientRedriveMs;
+    this.onPoison = options.onPoison;
+
+    const dir = options.dir ?? runnerOutboxDirFromEnv() ?? join(tmpdir(), "agent-relay-outbox");
+    this.path = options.dir === ":memory:" ? ":memory:" : join(dir, `outbox-${safeName(this.agentId)}.sqlite`);
+    if (this.path !== ":memory:") mkdirSync(dirname(this.path), { recursive: true });
+
+    this.db = new Database(this.path, { create: true });
+    this.db.exec("PRAGMA journal_mode = WAL");
+    this.db.exec("PRAGMA busy_timeout = 2000");
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS outbox (
+        seq INTEGER PRIMARY KEY AUTOINCREMENT,
+        kind TEXT NOT NULL,
+        mode TEXT NOT NULL DEFAULT 'append',
+        dedupe_key TEXT,
+        occurred_at INTEGER NOT NULL,
+        idempotency_key TEXT NOT NULL,
+        payload TEXT NOT NULL,
+        attempts INTEGER NOT NULL DEFAULT 0,
+        next_attempt_at INTEGER NOT NULL DEFAULT 0,
+        first_failed_at INTEGER NOT NULL DEFAULT 0,
+        poisoned INTEGER NOT NULL DEFAULT 0,
+        created_at INTEGER NOT NULL
+      )
+    `);
+    // Pre-#2433 databases lack the transient-park bookkeeping column (fresh CREATEs include it).
+    const columns = this.db.query("PRAGMA table_info(outbox)").all() as Array<{ name: string }>;
+    if (!columns.some((column) => column.name === "first_failed_at")) {
+      this.db.exec("ALTER TABLE outbox ADD COLUMN first_failed_at INTEGER NOT NULL DEFAULT 0");
+    }
+    // A restart is a fresh start: clear any backoff/park timers left by the prior process so
+    // pending events get an immediate retry (the down server may now be back). `attempts`
+    // is kept so the deterministic/unknown poison thresholds still count cumulative failures;
+    // `first_failed_at` restarts the CONTINUOUS-failure clock, since whatever the prior
+    // generation was failing against may be fixed by the restart itself.
+    this.db.exec("UPDATE outbox SET next_attempt_at = 0, first_failed_at = 0 WHERE next_attempt_at > 0 OR first_failed_at > 0");
+  }
+
+  // Persist an event. Returns the assigned seq. Triggers a drain.
+  enqueue(input: OutboxEventInput): number {
+    if (this.stopped) throw new Error("outbox is stopped");
+    const mode: OutboxMode = input.mode ?? "append";
+    const occurredAt = input.occurredAt ?? Date.now();
+    const payloadJson = JSON.stringify(input.payload ?? null);
+    const idempotencyKey = input.idempotencyKey ?? `${this.agentId}:${input.kind}:${occurredAt}:${shortHash(payloadJson)}`;
+
+    if (mode === "coalesce") {
+      if (!input.dedupeKey) throw new Error("coalesce mode requires a dedupeKey");
+      this.db.query("DELETE FROM outbox WHERE dedupe_key = ? AND poisoned = 0").run(input.dedupeKey);
+    }
+
+    const info = this.db
+      .query(`INSERT INTO outbox (kind, mode, dedupe_key, occurred_at, idempotency_key, payload, created_at)
+              VALUES (?, ?, ?, ?, ?, ?, ?)`)
+      .run(input.kind, mode, input.dedupeKey ?? null, occurredAt, idempotencyKey, payloadJson, Date.now());
+    const seq = Number(info.lastInsertRowid);
+
+    this.enforceBound();
+    // Defer the drain to a microtask so a synchronous burst of enqueues (e.g. several
+    // coalesce updates) all land — and coalesce — before the pump pulls the head.
+    queueMicrotask(() => this.pump());
+    return seq;
+  }
+
+  // Bounded ring buffer: if over capacity, drop the oldest rows (defined overflow policy).
+  // Logged, never silent. Prefers dropping already-poisoned rows first, then oldest by seq.
+  private enforceBound(): void {
+    const { n } = this.db.query("SELECT count(*) AS n FROM outbox").get() as { n: number };
+    if (n <= this.maxRows) return;
+    const overflow = n - this.maxRows;
+    // Oldest poisoned first, then oldest live — both by seq.
+    const victims = this.db
+      .query("SELECT seq FROM outbox ORDER BY poisoned DESC, seq ASC LIMIT ?")
+      .all(overflow) as Array<{ seq: number }>;
+    const ids = victims.map((v) => v.seq);
+    if (ids.length === 0) return;
+    const placeholders = ids.map(() => "?").join(",");
+    this.db.query(`DELETE FROM outbox WHERE seq IN (${placeholders})`).run(...ids);
+    logger.warn("outbox", `bound exceeded (${n}/${this.maxRows}) — dropped ${ids.length} oldest event(s)`);
+  }
+
+  // Begin the background pump: an initial drain plus a poll timer as a backstop.
+  start(): void {
+    if (this.pollTimer || this.stopped) return;
+    this.pump();
+    this.pollTimer = setInterval(() => this.pump(), this.pollMs);
+    this.pollTimer.unref?.();
+  }
+
+  // (#1617) — the ONE way a background caller starts a drain. `drain()` is a bare try/finally with
+  // no catch, and drainOnce() touches SQLite outside the send() try/catch (the head SELECT, and the
+  // attempt/poison UPDATEs in the failure path), so a closed or erroring database rejects it. Every
+  // pump site is fire-and-forget — an enqueue microtask, start()'s initial pump and poll timer, the
+  // scheduleDue wake-up — with nobody to await the promise, and Bun exits(1) on an unhandled
+  // rejection with no handler installed anywhere in the runner (#1614). That crashed the whole
+  // agent over a queue error, on a runner nothing respawns (#1618).
+  //
+  // Reported through this module's own existing channel (logger, same as the bound-exceeded warn
+  // and the poison fatal) rather than swallowed: a pump that stops pumping is its own bug, and
+  // it's the only reason the durable queue exists. `drain()` itself keeps its rejecting contract
+  // for flush(), which awaits it directly and is bounded by its own deadline.
+  private pump(): void {
+    void this.drain().catch((error) => {
+      logger.error("outbox", `drain failed: ${errMessage(error)}`);
+    });
+  }
+
+  // Drain everything we can before the process exits, ignoring per-row backoff. Used on
+  // shutdown/kill/crash (#183): the capture seam durably enqueues the end-of-session
+  // Insights datapoint, but the per-agent outbox is never reopened once the agent is gone,
+  // so a row that hasn't been POSTed yet is stranded forever. flush() blocks (bounded) on
+  // delivery — the opposite intent of the polite, backoff-respecting steady-state drain.
+  // Returns true if the queue fully drained within the deadline.
+  //
+  // #2433: the forced 150ms retry loop here used to consume the per-row attempt/poison
+  // budget, so <2s of relay downtime at a flush boundary poisoned frames. Force-drain
+  // failures no longer burn the TRANSIENT poison budget (see drainOnce) — flush() can
+  // hammer as hard as it likes during an outage without ever pushing a row toward poison.
+  async flush(timeoutMs: number): Promise<boolean> {
+    const deadline = Date.now() + Math.max(0, timeoutMs);
+    for (;;) {
+      if (this.stopped) return this.pendingCount() === 0;
+      if (this.pendingCount() === 0) return true;
+      await this.drain(true);
+      if (this.pendingCount() === 0) return true;
+      if (Date.now() >= deadline) return false;
+      await new Promise<void>((resolve) => setTimeout(resolve, FLUSH_RETRY_PAUSE_MS));
+    }
+  }
+
+  // Process the queue strictly oldest-first. Coalesces concurrent calls; if a drain is
+  // requested while one is running, it re-runs once at the end (so an enqueue during a
+  // send isn't missed). `force` (from flush) makes this pass ignore per-row backoff.
+  async drain(force = false): Promise<void> {
+    if (this.stopped) return;
+    if (force) this.forceDue = true;
+    if (this.draining) { this.rerun = true; return; }
+    this.draining = true;
+    try {
+      do {
+        this.rerun = false;
+        const due = this.forceDue;
+        this.forceDue = false;
+        await this.drainOnce(due);
+      } while ((this.rerun || this.forceDue) && !this.stopped);
+    } finally {
+      this.draining = false;
+    }
+  }
+
+  private async drainOnce(force = false): Promise<void> {
+    for (;;) {
+      if (this.stopped) return;
+      const row = this.db
+        .query("SELECT * FROM outbox WHERE poisoned = 0 ORDER BY seq ASC LIMIT 1")
+        .get() as Row | null;
+      if (!row) return;
+
+      const now = Date.now();
+      if (!force && row.next_attempt_at > now) {
+        // Head isn't due yet. Don't reorder past it (FIFO) — schedule a wake-up and stop.
+        this.scheduleDue(row.next_attempt_at - now);
+        return;
+      }
+
+      const record = this.toRecord(row);
+
+      try {
+        await this.send(record);
+        this.db.query("DELETE FROM outbox WHERE seq = ?").run(row.seq);
+      } catch (error) {
+        const reason = errMessage(error);
+        const transient = isTransientDeliveryError(error);
+        const deterministic = !transient && isDeterministicClientError(error);
+        // #2433: flush()'s forced loop hammers every 150ms while ignoring backoff; letting
+        // those passes consume the TRANSIENT attempt budget is what let a <2s relay restart
+        // window poison frames at a flush boundary. Forced drains of transient failures
+        // therefore burn NO attempt budget — classification still applies, counting does
+        // not (deterministic/unknown classes keep counting, preserving their poison paths).
+        const attempts = transient && force ? row.attempts : row.attempts + 1;
+
+        if (deterministic || (!transient && attempts >= this.maxAttempts)) {
+          await this.poisonRow(row, attempts, reason, deterministic);
+          // Move on — the next iteration picks the new head (poison no longer blocks).
+          continue;
+        }
+
+        if (transient) {
+          // Never poisoned on attempt count (#2433): retry under backoff until either the
+          // relay returns (the row delivers) or the CONTINUOUS-failure wall-clock budget
+          // runs out and the row parks onto a slow periodic re-drive cadence.
+          const firstFailedAt = row.first_failed_at > 0 ? row.first_failed_at : now;
+          if (now - firstFailedAt >= this.transientParkAfterMs) {
+            this.db.query("UPDATE outbox SET attempts = ?, next_attempt_at = ?, first_failed_at = ? WHERE seq = ?")
+              .run(attempts, now + this.transientRedriveMs, firstFailedAt, row.seq);
+            logger.error("outbox", `event seq=${row.seq} kind=${row.kind} parked after ${Math.round((now - firstFailedAt) / 1000)}s of continuous transient failures — re-driving every ${Math.round(this.transientRedriveMs / 1000)}s until the relay returns (last error: ${reason})`);
+            this.scheduleDue(this.transientRedriveMs);
+            return;
+          }
+          const delay = this.backoff(attempts);
+          this.db.query("UPDATE outbox SET attempts = ?, next_attempt_at = ?, first_failed_at = ? WHERE seq = ?")
+            .run(attempts, now + delay, firstFailedAt, row.seq);
+          logger.debug("outbox", `event seq=${row.seq} kind=${row.kind} transient retry ${attempts} (no poison cap) in ${delay}ms: ${reason}`);
+          this.scheduleDue(delay);
+          return; // head is now scheduled; stop until it's due (preserve order)
+        }
+
+        const delay = this.backoff(attempts);
+        this.db.query("UPDATE outbox SET attempts = ?, next_attempt_at = ? WHERE seq = ?").run(attempts, now + delay, row.seq);
+        logger.debug("outbox", `event seq=${row.seq} kind=${row.kind} retry ${attempts}/${this.maxAttempts} in ${delay}ms: ${reason}`);
+        this.scheduleDue(delay);
+        return; // head is now scheduled; stop until it's due (preserve order)
+      }
+    }
+  }
+
+  private toRecord(row: Row): OutboxRecord {
+    return {
+      seq: row.seq,
+      kind: row.kind,
+      mode: row.mode as OutboxMode,
+      occurredAt: row.occurred_at,
+      idempotencyKey: row.idempotency_key,
+      payload: safeParse(row.payload),
+      attempts: row.attempts,
+    };
+  }
+
+  // Permanently drop a row. Only reachable for deterministic client rejections (immediately)
+  // or unknown-class failures past maxAttempts — NEVER for transient ones (#2433). The
+  // onPoison seam lets the session outbox surface the loss in-session instead of only in
+  // this FATAL host log.
+  private async poisonRow(row: Row, attempts: number, reason: string, immediate: boolean): Promise<void> {
+    this.db.query("UPDATE outbox SET attempts = ?, poisoned = 1 WHERE seq = ?").run(attempts, row.seq);
+    logger.fatal("outbox", immediate
+      ? `event seq=${row.seq} kind=${row.kind} poisoned immediately on a deterministic client rejection (${attempts} attempt(s)): ${reason}`
+      : `event seq=${row.seq} kind=${row.kind} poisoned after ${attempts} attempts: ${reason}`);
+    if (!this.onPoison) return;
+    try {
+      const record = this.toRecord(row);
+      record.attempts = attempts;
+      await this.onPoison(record, reason);
+    } catch (error) {
+      logger.error("outbox", `onPoison handler failed for seq=${row.seq}: ${errMessage(error)}`);
+    }
+  }
+
+  // Pure per-row delay calc: the attempt count lives in SQLite (one outbox row
+  // at a time may be due), so this stays a stateless function rather than the
+  // stateful SDK ReconnectionManager (single in-memory counter) used for the
+  // orchestrator/voice reconnect loops — different model, deliberately not shared.
+  private backoff(attempts: number): number {
+    const exp = Math.min(this.maxBackoffMs, this.baseBackoffMs * 2 ** (attempts - 1));
+    return Math.round(exp / 2 + Math.random() * (exp / 2)); // full-ish jitter, never below half
+  }
+
+  private scheduleDue(delayMs: number): void {
+    if (this.stopped || this.dueTimer) return;
+    this.dueTimer = setTimeout(() => {
+      this.dueTimer = undefined;
+      this.pump();
+    }, Math.max(0, delayMs));
+    this.dueTimer.unref?.();
+  }
+
+  // Observability / tests.
+  pendingCount(): number {
+    return (this.db.query("SELECT count(*) AS n FROM outbox WHERE poisoned = 0").get() as { n: number }).n;
+  }
+
+  updatePayload(seq: number, payload: unknown): void {
+    const payloadJson = JSON.stringify(payload ?? null);
+    this.db.query("UPDATE outbox SET payload = ? WHERE seq = ? AND poisoned = 0").run(payloadJson, seq);
+  }
+
+  poisonedCount(): number {
+    return (this.db.query("SELECT count(*) AS n FROM outbox WHERE poisoned = 1").get() as { n: number }).n;
+  }
+
+  stop(): void {
+    this.stopped = true;
+    if (this.pollTimer) clearInterval(this.pollTimer);
+    this.pollTimer = undefined;
+    if (this.dueTimer) clearTimeout(this.dueTimer);
+    this.dueTimer = undefined;
+  }
+
+  close(): void {
+    this.stop();
+    try { this.db.close(); } catch { /* already closed */ }
+  }
+}
+
+function safeName(value: string): string {
+  return sanitizeFsName(value, { replacement: "_", maxLen: 180, fallback: "agent" });
+}
+
+function safeParse(json: string): unknown {
+  try { return JSON.parse(json); } catch { return null; }
+}
+
+// Small, fast, stable string hash (FNV-1a, 32-bit) — enough to disambiguate identical
+// kind+timestamp payloads in the idempotency key. Not security-sensitive.
+function shortHash(value: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < value.length; i++) {
+    h ^= value.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(36);
+}

package/src/park-post.ts

@@ -0,0 +1,17 @@
+import { errMessage } from "@humwick/sdk";
+import { logger } from "./logger";
+
+const PARK_PERSIST_ATTEMPTS = 3;
+
+/** A parked prompt's self-post, retried with backoff; undefined once every attempt failed. */
+export async function retryParkPost<T>(what: string, post: () => Promise<T>): Promise<T | undefined> {
+  for (let attempt = 0; attempt < PARK_PERSIST_ATTEMPTS; attempt++) {
+    if (attempt > 0) await new Promise((resolve) => setTimeout(resolve, 500 * 2 ** (attempt - 1)));
+    try {
+      return await post();
+    } catch (error) {
+      logger.warn("runner", `${what} failed (attempt ${attempt + 1}/${PARK_PERSIST_ATTEMPTS}): ${errMessage(error)}`);
+    }
+  }
+  return undefined;
+}

package/src/pending-permission-store.ts

@@ -0,0 +1,148 @@
+import { Database } from "bun:sqlite";
+import type { InteractivePrompt } from "@humwick/sdk";
+import { mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { sanitizeFsName } from "@humwick/sdk/fs-name";
+import { runnerOutboxDirFromEnv } from "./config";
+import { logger } from "./logger";
+import { errMessage } from "@humwick/sdk";
+
+export interface PendingPermissionRequestRecord {
+  approvalId: string;
+  view: InteractivePrompt;
+  hookDeadlineAt: number;
+  ownerInstanceId: string;
+  occurredAt: number;
+}
+
+interface PendingPermissionRow {
+  approval_id: string;
+  view: string;
+  hook_deadline_at: number;
+  owner_instance_id: string;
+  occurred_at: number;
+}
+
+export class PendingPermissionStore {
+  private db?: Database;
+  readonly path: string;
+
+  constructor(options: { agentId: string; dir?: string }) {
+    const dir = options.dir ?? runnerOutboxDirFromEnv() ?? join(tmpdir(), "agent-relay-outbox");
+    this.path = options.dir === ":memory:" ? ":memory:" : join(dir, `pending-permissions-${safeName(options.agentId)}.sqlite`);
+    try {
+      if (this.path !== ":memory:") mkdirSync(dirname(this.path), { recursive: true });
+      const db = new Database(this.path, { create: true });
+      db.exec("PRAGMA journal_mode = WAL");
+      db.exec("PRAGMA busy_timeout = 2000");
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS pending_permission_requests (
+          approval_id TEXT PRIMARY KEY,
+          view TEXT NOT NULL,
+          hook_deadline_at INTEGER NOT NULL,
+          owner_instance_id TEXT NOT NULL,
+          occurred_at INTEGER NOT NULL,
+          created_at INTEGER NOT NULL
+        )
+      `);
+      this.db = db;
+    } catch (error) {
+      logger.error("pending-permission-store", `disabled after open failed path=${this.path}: ${errMessage(error)}`);
+      this.db = undefined;
+    }
+  }
+
+  upsert(record: PendingPermissionRequestRecord): void {
+    if (!this.db) return;
+    try {
+      this.db.query(`
+        INSERT INTO pending_permission_requests (approval_id, view, hook_deadline_at, owner_instance_id, occurred_at, created_at)
+        VALUES (?, ?, ?, ?, ?, ?)
+        ON CONFLICT(approval_id) DO UPDATE SET
+          view = excluded.view,
+          hook_deadline_at = excluded.hook_deadline_at,
+          owner_instance_id = excluded.owner_instance_id,
+          occurred_at = excluded.occurred_at
+      `).run(record.approvalId, JSON.stringify(record.view), record.hookDeadlineAt, record.ownerInstanceId, record.occurredAt, Date.now());
+    } catch (error) {
+      logger.error("pending-permission-store", `upsert failed approvalId=${record.approvalId}; continuing in-memory only: ${errMessage(error)}`);
+    }
+  }
+
+  delete(approvalId: string): void {
+    if (!this.db) return;
+    try {
+      this.db.query("DELETE FROM pending_permission_requests WHERE approval_id = ?").run(approvalId);
+    } catch (error) {
+      logger.error("pending-permission-store", `delete failed approvalId=${approvalId}; continuing in-memory only: ${errMessage(error)}`);
+    }
+  }
+
+  list(): PendingPermissionRequestRecord[] {
+    if (!this.db) return [];
+    try {
+      const rows = this.db.query("SELECT * FROM pending_permission_requests ORDER BY occurred_at ASC").all() as PendingPermissionRow[];
+      return rows.map((row) => ({
+        approvalId: row.approval_id,
+        view: safeParseView(row.view),
+        hookDeadlineAt: row.hook_deadline_at,
+        ownerInstanceId: row.owner_instance_id,
+        occurredAt: row.occurred_at,
+      }));
+    } catch (error) {
+      logger.error("pending-permission-store", `list failed; continuing without persisted approvals: ${errMessage(error)}`);
+      return [];
+    }
+  }
+
+  close(): void {
+    try { this.db?.close(); } catch { /* already closed */ }
+  }
+}
+
+export function bestEffortListPendingPermissionRequests(store: PendingPermissionStore | undefined): PendingPermissionRequestRecord[] {
+  try {
+    return store?.list() ?? [];
+  } catch (error) {
+    logger.error("pending-permission-store", `list failed; continuing without persisted approvals: ${errMessage(error)}`);
+    return [];
+  }
+}
+
+export function bestEffortUpsertPendingPermissionRequest(store: PendingPermissionStore | undefined, record: PendingPermissionRequestRecord): void {
+  try {
+    store?.upsert(record);
+  } catch (error) {
+    logger.error("pending-permission-store", `upsert failed approvalId=${record.approvalId}; continuing in-memory only: ${errMessage(error)}`);
+  }
+}
+
+export function bestEffortDeletePendingPermissionRequest(store: PendingPermissionStore | undefined, approvalId: string): void {
+  try {
+    store?.delete(approvalId);
+  } catch (error) {
+    logger.error("pending-permission-store", `delete failed approvalId=${approvalId}; continuing in-memory only: ${errMessage(error)}`);
+  }
+}
+
+function safeName(value: string): string {
+  return sanitizeFsName(value, { replacement: "_", maxLen: 180, fallback: "agent" });
+}
+
+function safeParseView(json: string): InteractivePrompt {
+  try {
+    const parsed = JSON.parse(json);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed as InteractivePrompt;
+  } catch {
+    // Fall through to a valid placeholder so recovery can still emit a notice and clear the row.
+  }
+  return {
+    id: "unknown",
+    kind: "tool",
+    title: "Recovered permission request",
+    body: "The original permission request could not be decoded.",
+    choices: [],
+    reasoningSettled: false,
+  };
+}

package/src/process-meta.ts

@@ -0,0 +1,9 @@
+import type { ManagedProcess } from "./adapter";
+
+export function providerTerminalSession(process?: ManagedProcess): string | undefined {
+  return typeof process?.meta?.tmuxSession === "string" ? process.meta.tmuxSession : undefined;
+}
+
+export function providerTerminalSocket(process?: ManagedProcess): string | undefined {
+  return typeof process?.meta?.tmuxSocket === "string" ? process.meta.tmuxSocket : undefined;
+}