fix: batch cancellable title reads

2026-07-24 18:13:11 +08:00
parent f5fc7ac04a
commit fec4ce52cc
23 changed files with 1152 additions and 150 deletions
--- a/packages/session-persistence/session-persistence-jsonl/src/index.ts
+++ b/packages/session-persistence/session-persistence-jsonl/src/index.ts
@@ -131,8 +131,8 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
    return this.coordinator.load(id)
  }

-  inspect(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
-    return this.coordinator.inspect(id)
+  inspect(id: SessionId, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    return this.coordinator.inspect(id, signal)
  }

  // One method serves both public `list` and the backend hook; delegating it to
@@ -142,24 +142,33 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
  // --- PersistenceBackend hooks (the file-bytes storage primitives) ---

  /** Read a stored prefix by id across all cwd buckets when cwd is unknown. */
-  async loadStored(id: SessionId): Promise<StoredPrefix<JsonlTornMarker> | undefined> {
+  async loadStored(id: SessionId, signal?: AbortSignal): Promise<StoredPrefix<JsonlTornMarker> | undefined> {
+    signal?.throwIfAborted()
    await this.ensureRootEncoding()
-    const path = await this.findLog(id)
+    signal?.throwIfAborted()
+    const path = await this.findLog(id, signal)
    if (path === undefined) return undefined
-    return this.readPrefix(path, id)
+    return this.readPrefix(path, id, signal)
  }

  /**
   * Read a stored prefix and convert torn-tail state to the opaque marker the
   * coordinator can round-trip without knowing the physical encoding.
   */
-  private async readPrefix(path: string, expectedId?: SessionId): Promise<StoredPrefix<JsonlTornMarker>> {
-    const buffer = await readFile(path)
+  private async readPrefix(
+    path: string,
+    expectedId?: SessionId,
+    signal?: AbortSignal,
+  ): Promise<StoredPrefix<JsonlTornMarker>> {
+    const buffer = await readFile(path, { signal })
+    signal?.throwIfAborted()
    let prefix: StoredPrefix<JsonlTornMarker>
    if (this.compression === 'zstd') {
-      prefix = await this.readZstdPrefix(buffer)
+      prefix = await this.readZstdPrefix(buffer, signal)
    } else {
+      signal?.throwIfAborted()
      const { meta, events, committedBytes } = scanLog(buffer)
+      signal?.throwIfAborted()
      prefix = {
        meta,
        events,
@@ -168,30 +177,45 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
          : {},
      }
    }
+    signal?.throwIfAborted()
    this.assertStoredIdentity(path, prefix.meta, expectedId)
    return prefix
  }

  /** Decode complete frames and retain complete JSONL records from a torn final frame. */
-  private async readZstdPrefix(buffer: Buffer): Promise<StoredPrefix<JsonlTornMarker>> {
+  private async readZstdPrefix(
+    buffer: Buffer,
+    signal?: AbortSignal,
+  ): Promise<StoredPrefix<JsonlTornMarker>> {
+    signal?.throwIfAborted()
    const { frames, tornStart } = scanZstdFrames(buffer)
+    signal?.throwIfAborted()
    if (frames.length === 0) throw new Error('empty or header-less Zstandard session log')

    const plaintextFrames: Buffer[] = []
    for (const frame of frames) {
+      let plaintext: Buffer
      try {
-        plaintextFrames.push(await decompressZstdFrame(buffer.subarray(frame.start, frame.end)))
+        signal?.throwIfAborted()
+        plaintext = await decompressZstdFrame(buffer.subarray(frame.start, frame.end))
      } catch (error) {
+        /* v8 ignore next -- decoder failure plus concurrent abort is timing-dependent */
+        if (signal?.aborted) signal.throwIfAborted()
        throw new Error(`corrupt Zstandard session log: frame at byte ${frame.start} failed validation`, { cause: error })
      }
+      signal?.throwIfAborted()
+      plaintextFrames.push(plaintext)
    }

    const headerFrame = plaintextFrames[0]
    if (headerFrame === undefined || headerFrame.length === 0 || headerFrame.indexOf(0x0A) !== headerFrame.length - 1) {
      throw new Error('corrupt Zstandard session log: first frame is not exactly one header line')
    }
+    signal?.throwIfAborted()
    const completePlaintext = Buffer.concat(plaintextFrames)
+    signal?.throwIfAborted()
    const completePrefix = scanLog(completePlaintext)
+    signal?.throwIfAborted()
    if (completePrefix.committedBytes !== completePlaintext.length) {
      throw new Error('corrupt Zstandard session log: complete frame contains a torn JSONL record')
    }
@@ -201,12 +225,17 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi

    let recoveredPlaintext: Buffer = Buffer.alloc(0)
    try {
+      signal?.throwIfAborted()
      recoveredPlaintext = await decompressZstdFrame(buffer.subarray(tornStart))
    } catch {
+      /* v8 ignore next -- decoder failure plus concurrent abort is timing-dependent */
+      if (signal?.aborted) signal.throwIfAborted()
      // A structurally incomplete final frame may end before Node's decoder can
      // emit any plaintext; the complete prior frames remain recoverable.
    }
+    signal?.throwIfAborted()
    const recoveredPrefix = scanLog(Buffer.concat([completePlaintext, recoveredPlaintext]))
+    signal?.throwIfAborted()
    /* v8 ignore next 3 -- appending plaintext cannot shorten the already-scanned complete prefix */
    if (recoveredPrefix.events.length < completePrefix.events.length) {
      throw new Error('corrupt Zstandard session log: recovered prefix does not extend complete frames')
@@ -247,8 +276,8 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
  }

  /** List valid unique stored sessions' metadata (header line only — no full-log parse). */
-  async list(): Promise<SessionHeader[]> {
-    return (await this.listArtifacts()).map(artifact => artifact.header)
+  async list(signal?: AbortSignal): Promise<SessionHeader[]> {
+    return (await this.listArtifacts(signal)).map(artifact => artifact.header)
  }

  /** List metadata plus a stat-derived identity for each append-only log. */
@@ -274,17 +303,21 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
    return snapshots
  }

-  private async listArtifacts(): Promise<Array<{ header: SessionHeader; path: string }>> {
+  private async listArtifacts(signal?: AbortSignal): Promise<Array<{ header: SessionHeader; path: string }>> {
+    signal?.throwIfAborted()
    await this.ensureRootEncoding()
+    signal?.throwIfAborted()
    const artifacts: Array<{ header: SessionHeader; path: string }> = []
    const ids = new Set<SessionId>()
-    for (const dir of await this.listCwdDirs()) {
-      for (const name of await this.listArtifactNames(dir)) {
+    for (const dir of await this.listCwdDirs(signal)) {
+      for (const name of await this.listArtifactNames(dir, signal)) {
+        signal?.throwIfAborted()
        const path = join(dir, name)
        // Read only headers so listing scales with session count, not log size.
        const first = this.compression === 'zstd'
-          ? await this.readFirstZstdLine(path)
-          : await this.readFirstLine(path)
+          ? await this.readFirstZstdLine(path, signal)
+          : await this.readFirstLine(path, signal)
+        signal?.throwIfAborted()
        if (first === undefined) continue // empty/half-written file
        const meta = parseHeaderMeta(first)
        if (meta === undefined) continue // not a session header
@@ -492,18 +525,23 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
   * file. Returns undefined if the file is empty or has no complete first line.
   * Reads in bounded chunks so a huge log costs only the header read.
   */
-  private async readFirstLine(path: string): Promise<string | undefined> {
+  private async readFirstLine(path: string, signal?: AbortSignal): Promise<string | undefined> {
+    signal?.throwIfAborted()
    const handle = await open(path, 'r')
    try {
+      signal?.throwIfAborted()
      const chunks: Buffer[] = []
      const buf = Buffer.alloc(8192)
      for (;;) {
+        signal?.throwIfAborted()
        const { bytesRead } = await handle.read(buf, 0, buf.length, null)
+        signal?.throwIfAborted()
        if (bytesRead === 0) return undefined // EOF with no newline → no complete line
        const slice = buf.subarray(0, bytesRead)
        const nl = slice.indexOf(0x0a)
        if (nl !== -1) {
          chunks.push(slice.subarray(0, nl))
+          signal?.throwIfAborted()
          return Buffer.concat(chunks).toString('utf8')
        }
        chunks.push(Buffer.from(slice))
@@ -514,23 +552,34 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
  }

  /** Read and validate only the independently compressed header frame. */
-  private async readFirstZstdLine(path: string): Promise<string | undefined> {
+  private async readFirstZstdLine(path: string, signal?: AbortSignal): Promise<string | undefined> {
+    signal?.throwIfAborted()
    const handle = await open(path, 'r')
    try {
+      signal?.throwIfAborted()
      let content = Buffer.alloc(0)
      const chunk = Buffer.alloc(8192)
      for (;;) {
+        signal?.throwIfAborted()
        const { bytesRead } = await handle.read(chunk, 0, chunk.length, null)
+        signal?.throwIfAborted()
        if (bytesRead === 0) return undefined
+        signal?.throwIfAborted()
        content = Buffer.concat([content, chunk.subarray(0, bytesRead)])
+        signal?.throwIfAborted()
        const first = scanZstdFrames(content, 1).frames[0]
+        signal?.throwIfAborted()
        if (first === undefined) continue
        let plaintext: Buffer
        try {
+          signal?.throwIfAborted()
          plaintext = await decompressZstdFrame(content.subarray(first.start, first.end))
        } catch (error) {
+          /* v8 ignore next -- decoder failure plus concurrent abort is timing-dependent */
+          if (signal?.aborted) signal.throwIfAborted()
          throw new Error('corrupt Zstandard session log: header frame failed validation', { cause: error })
        }
+        signal?.throwIfAborted()
        if (plaintext.length === 0 || plaintext.indexOf(0x0A) !== plaintext.length - 1) {
          throw new Error('corrupt Zstandard session log: first frame is not exactly one header line')
        }
@@ -542,11 +591,12 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
  }

  /** Find the unique physical log for an id across every cwd bucket. */
-  private async findLog(id: SessionId): Promise<string | undefined> {
+  private async findLog(id: SessionId, signal?: AbortSignal): Promise<string | undefined> {
    const target = encodeSegment(id) + logSuffix(this.compression)
    const oppositeTarget = encodeSegment(id) + logSuffix(this.oppositeCompression())
    const matches: string[] = []
-    for (const dir of await this.listCwdDirs()) {
+    for (const dir of await this.listCwdDirs(signal)) {
+      signal?.throwIfAborted()
      const path = join(dir, target)
      const opposite = join(dir, oppositeTarget)
      if (await this.exists(opposite)) throw this.encodingMismatch(opposite)
@@ -585,9 +635,11 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
  }

  /** The cwd-bucket directories under the root (absolute paths). */
-  private async listCwdDirs(): Promise<string[]> {
+  private async listCwdDirs(signal?: AbortSignal): Promise<string[]> {
    try {
+      signal?.throwIfAborted()
      const entries = await readdir(this.root, { withFileTypes: true })
+      signal?.throwIfAborted()
      return entries.filter(e => e.isDirectory()).map(e => join(this.root, e.name))
    } catch (error) {
      // Only an absent root means no sessions; rethrow every other I/O failure.
@@ -596,8 +648,10 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
    }
  }

-  private async listArtifactNames(dir: string): Promise<string[]> {
+  private async listArtifactNames(dir: string, signal?: AbortSignal): Promise<string[]> {
+    signal?.throwIfAborted()
    const entries = await readdir(dir)
+    signal?.throwIfAborted()
    const oppositeSuffix = logSuffix(this.oppositeCompression())
    const incompatible = entries.find(name => name.endsWith(oppositeSuffix))
    if (incompatible !== undefined) throw this.encodingMismatch(`${dir}/${incompatible}`)
--- a/packages/session-persistence/session-persistence-jsonl/tests/zstd.spec.ts
+++ b/packages/session-persistence/session-persistence-jsonl/tests/zstd.spec.ts
@@ -16,6 +16,18 @@ const MAGIC = Buffer.from([0x28, 0xB5, 0x2F, 0xFD])
 const roots: string[] = []
 const contexts: Context[] = []

+interface ZstdReaderInternals {
+  readZstdPrefix(buffer: Buffer, signal?: AbortSignal): Promise<unknown>
+}
+
+type HeaderRead = (
+  this: FileHandle,
+  buffer: Buffer,
+  offset: number,
+  length: number,
+  position: number | null,
+) => Promise<{ bytesRead: number; buffer: Buffer }>
+
 async function freshRoot(prefix = 'dsh-jsonl-zstd-'): Promise<string> {
  const root = await mkdtemp(join(tmpdir(), prefix))
  roots.push(root)
@@ -275,6 +287,65 @@ describe('SessionPersistenceJsonl: default Zstandard encoding', () => {
    await expect(ctx.sessionPersistence.load(header.id)).rejects.toThrow(/frame at byte .* failed validation/)
  })

+  it('stops multi-frame inspection after cancellation interrupts the active decode', async () => {
+    const root = await freshRoot()
+    const ctx = await mount(root)
+    const header = meta('cancel-zstd-frames')
+    const headerFrame = await compressZstdFrame(`${JSON.stringify(toHeaderLine(header))}\n`)
+    const eventFrame = await compressZstdFrame(`${JSON.stringify(oneTurnLog()[0])}\n`)
+    const laterFrame = await compressZstdFrame(`${JSON.stringify(oneTurnLog()[1])}\n`)
+    const stream = Buffer.concat([headerFrame, eventFrame, laterFrame])
+    expect(scanZstdFrames(stream).frames).toHaveLength(3)
+    const controller = new AbortController()
+    const reason = new Error('cancel after Zstandard decode starts')
+    const reader = ctx.sessionPersistence as unknown as ZstdReaderInternals
+    const zstdModule = await import('../src/zstd.ts')
+    const decode = vi.spyOn(zstdModule, 'decompressZstdFrame')
+
+    // readZstdPrefix reaches its first asynchronous decompression before it
+    // returns this promise. The microtask abort therefore occurs after decode
+    // starts and must prevent every later frame from reaching the decoder.
+    const pending = reader.readZstdPrefix(stream, controller.signal)
+    queueMicrotask(() => { controller.abort(reason) })
+
+    await expect(pending).rejects.toBe(reason)
+    expect(decode).toHaveBeenCalledTimes(1)
+    expect(decode).toHaveBeenCalledWith(headerFrame)
+  })
+
+  it.each(['none', 'zstd'] as const)(
+    'observes cancellation after each async %s header read during listing',
+    async (compression) => {
+      const root = await freshRoot()
+      const ctx = await mount(root, compression)
+      const header = meta(`cancel-${compression}-header-read`, '/work')
+      await ctx.sessionPersistence.create(header)
+      await ctx.sessionPersistence.append(header.id, oneTurnLog())
+      await ctx.sessionPersistence.list()
+      const path = logPath(root, header.cwd, header.id, compression)
+      const probe = await open(path, 'r')
+      const prototype = Object.getPrototypeOf(probe) as { read: HeaderRead }
+      const originalRead = prototype.read
+      await probe.close()
+      const controller = new AbortController()
+      const reason = new Error(`cancel ${compression} header read`)
+      const read = vi.spyOn(prototype, 'read').mockImplementation(async function (
+        this: FileHandle,
+        buffer: Buffer,
+        offset: number,
+        length: number,
+        position: number | null,
+      ) {
+        const result = await originalRead.call(this, buffer, offset, length, position)
+        controller.abort(reason)
+        return result
+      })
+
+      await expect(ctx.sessionPersistence.list(controller.signal)).rejects.toBe(reason)
+      expect(read).toHaveBeenCalledTimes(1)
+    },
+  )
+
  it('preserves complete records from a torn frame and re-encodes them with crash closers', async () => {
    const root = await freshRoot()
    const ctx = await mount(root)
--- a/packages/session-persistence/session-persistence-sqlite/src/index.ts
+++ b/packages/session-persistence/session-persistence-sqlite/src/index.ts
@@ -157,8 +157,8 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
    return this.coordinator.load(id)
  }

-  inspect(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
-    return this.coordinator.inspect(id)
+  inspect(id: SessionId, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    return this.coordinator.inspect(id, signal)
  }

  // One method serves both public `list` and the backend hook; delegating it to
@@ -167,8 +167,8 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
  // --- PersistenceBackend hooks (the SQLite storage primitives) ---

  /** Read a stored prefix by id (ids are globally unique — no scope to scan). */
-  loadStored(id: SessionId): Promise<StoredPrefix<number> | undefined> {
-    return this.readPrefix(id)
+  loadStored(id: SessionId, signal?: AbortSignal): Promise<StoredPrefix<number> | undefined> {
+    return this.readPrefix(id, signal)
  }

  /**
@@ -176,14 +176,17 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
   * torn-tail marker is the seq from which a never-committed tail must be deleted
   * (`scanRows` already returns it as `number | undefined`).
   */
-  private async readPrefix(id: SessionId): Promise<StoredPrefix<number> | undefined> {
+  private async readPrefix(id: SessionId, signal?: AbortSignal): Promise<StoredPrefix<number> | undefined> {
+    signal?.throwIfAborted()
    await this.ready
+    signal?.throwIfAborted()
    const row = this.rowFor(id)
    if (row === undefined) return undefined
    const meta = rowToMeta(row)
    const eventRows = this.db
      .prepare('SELECT seq, type, time, data, source_event_seqs, surface_op FROM events WHERE session_id = ? ORDER BY seq')
      .all(id) as unknown as EventRow[]
+    signal?.throwIfAborted()
    const { preserved, tornFrom } = scanRows(eventRows)
    return { meta, events: preserved, ...tornFrom !== undefined ? { tornMarker: tornFrom } : {} }
  }
@@ -251,11 +254,14 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
  }

  /** List all materialized sessions' metadata (every row is a materialized session). */
-  async list(): Promise<SessionHeader[]> {
+  async list(signal?: AbortSignal): Promise<SessionHeader[]> {
+    signal?.throwIfAborted()
    await this.ready
+    signal?.throwIfAborted()
    const rows = this.db
      .prepare('SELECT * FROM sessions')
      .all() as unknown as SessionRow[]
+    signal?.throwIfAborted()
    return rows.map(rowToMeta)
  }

--- a/packages/session-persistence/session-persistence/README.md
+++ b/packages/session-persistence/session-persistence/README.md
@@ -12,8 +12,8 @@ The persisted unit IS the existing `SessionEvent` (event-sourced model — the l
 | `create(meta): Promise<void>` | Register a new session's metadata. MAY defer the physical write until the first `append` (lazy materialization). |
 | `append(id, events): Promise<void>` | Durably persist a batch. Append-only; first event `seq` == stored next-seq after any repair; rejects non-JSON-serializable data naming the offending type. |
 | `load(id): Promise<{ meta; events }>` | Return a stored header plus a balanced contiguous log. A live load first flushes its snapshot and rejects while its turn is open; a cold load preserves an interrupted final turn and closes it with synthetic `tool/result`/`step/end?`/`turn/end {interrupted}` events. Only a torn tail fragment is dropped; committed corruption and unknown `version` reject. |
-| `inspect(id): Promise<{ meta; events }>` | Return a detached valid stored prefix without truncating a torn tail, synthesizing recovery closers, or publishing coordinator state. Serialized with same-id writes; intended for read models and other observers that must never recover a log. |
-| `list(): Promise<SessionHeader[]>` | Lightweight listing from metadata, no full-log parse. A zero-event lazily-materialized session is absent from `list`. |
+| `inspect(id, signal?): Promise<{ meta; events }>` | Return a detached valid stored prefix without truncating a torn tail, synthesizing recovery closers, or publishing coordinator state. Serialized with same-id writes; the optional signal promptly rejects a queued caller, prevents that queued backend read from starting, and cancels active backend read work. Intended for read models and other observers that must never recover a log. |
+| `list(signal?): Promise<SessionHeader[]>` | Lightweight listing from metadata, no full-log parse. The optional signal cancels backend listing work. A zero-event lazily-materialized session is absent from `list`. |
 | `listSnapshots(): Promise<SessionPersistenceSnapshot[]>` | Lightweight metadata plus an opaque branded per-log revision, without loading event logs. A revision stays equal while that log and its backing store are unchanged, changes after append or mutating load repair, and cannot collide solely because two stores use the same local counter. |

 ## Invariants every backend must honor
@@ -40,10 +40,10 @@ The `PersistenceBackend<TornMarker>` hooks (the only seam between the coordinato
 | Hook | Role |
 |---|---|
 | `name` | Backend label for the dispose-failure `AggregateError`. |
-| `loadStored(id)` | Read a stored prefix by id across every storage scope. Used by resume/load, non-mutating inspect, live adoption, and the create-collision probe. Returned metadata identifies `id`; an opaque `tornMarker` is present iff a torn tail must be truncated. |
+| `loadStored(id, signal?)` | Read a stored prefix by id across every storage scope. Used by resume/load, non-mutating inspect, live adoption, and the create-collision probe. The optional signal belongs to observation-only reads. Returned metadata identifies `id`; an opaque `tornMarker` is present iff a torn tail must be truncated. |
 | `appendBatch(meta, events, isMaterialized)` | Durably append a contiguous batch, lazily materializing ATOMICALLY when not yet materialized. |
 | `commitRepair(meta, tornMarker, closers)` | Make a crash repair durable: truncate the torn tail (iff `tornMarker !== undefined` — a marker may be falsy, e.g. seq/offset `0`) and append `closers`. NOT required to be atomic. Used by load (truncate + closers) and live-adoption (truncate only). |
-| `list()` | List all stored metadata. |
+| `list(signal?)` | List all stored metadata, observing optional cancellation. |
 | `close?()` | Optional lifecycle teardown (e.g. close a db handle), awaited after the dispose drain. |

 The coordinator asserts the stored id and compares stored/live cwd before repair or live adoption. Its `inspect()` path validates and clones the prefix without calling `commitRepair` or publishing write state. The `tornMarker` is fully OPAQUE: the coordinator only tests `!== undefined` and round-trips it to `commitRepair`, never inspecting its value (the JSONL backend uses the byte offset to truncate to, the SQLite backend the seq to delete from). A third-party backend MAY implement the abstract service directly without the coordinator, but it must provide the same non-mutating inspection and trustworthy lightweight snapshot revisions. See [the write-coordinator Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md).
--- a/packages/session-persistence/session-persistence/src/coordinator.ts
+++ b/packages/session-persistence/session-persistence/src/coordinator.ts
@@ -40,8 +40,10 @@ export interface PersistenceBackend<TornMarker = unknown> {
   * `id` before repair or state publication. Used by resume/load, live adoption,
   * and — via `!== undefined` — the create-collision probe. The returned
   * `tornMarker` is present iff there is a torn tail to truncate.
+   * @param id - persisted session id to resolve.
+   * @param signal - optional cancellation for backend read work.
   */
-  loadStored(id: SessionId): Promise<StoredPrefix<TornMarker> | undefined>
+  loadStored(id: SessionId, signal?: AbortSignal): Promise<StoredPrefix<TornMarker> | undefined>

  /**
   * Durably append a CONTIGUOUS batch, lazily materializing the session first
@@ -60,8 +62,11 @@ export interface PersistenceBackend<TornMarker = unknown> {
   */
  commitRepair(meta: SessionHeader, tornMarker: TornMarker | undefined, closers: readonly SessionEvent[]): Promise<void>

-  /** List all stored (materialized) sessions' metadata. */
-  list(): Promise<SessionHeader[]>
+  /**
+   * List all stored (materialized) sessions' metadata.
+   * @param signal - optional cancellation for backend listing work.
+   */
+  list(signal?: AbortSignal): Promise<SessionHeader[]>

  /**
   * Optional lifecycle teardown (e.g. close a database handle). Awaited by the
@@ -267,14 +272,26 @@ export class PersistenceCoordinator<TornMarker = unknown> {
   * Read a detached valid stored prefix without recovery mutations or
   * coordinator-state publication.
   * @param id - persisted session to inspect.
+   * @param signal - optional cancellation for queued and backend read work.
   * @returns stored header and events before any synthetic recovery closers.
   */
-  inspect(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
-    return this.serialize(id, () => this.inspectCore(id))
+  inspect(id: SessionId, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    return this.serialize(id, () => this.inspectCore(id, signal), signal)
  }

-  private async inspectCore(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
-    const stored = await this.backend.loadStored(id)
+  private async inspectCore(
+    id: SessionId,
+    signal?: AbortSignal,
+  ): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    signal?.throwIfAborted()
+    let stored: StoredPrefix<TornMarker> | undefined
+    try {
+      stored = await this.backend.loadStored(id, signal)
+    } catch (error: unknown) {
+      if (signal?.aborted) signal.throwIfAborted()
+      throw error
+    }
+    signal?.throwIfAborted()
    if (stored === undefined) throw new Error(`session "${id}" not found`)
    this.assertStoredId(id, stored.meta)
    this.assertVersion(stored.meta)
@@ -331,9 +348,19 @@ export class PersistenceCoordinator<TornMarker = unknown> {
   * public methods must NOT call each other (deadlock); they call the unserialized
   * `*Core` helpers instead.
   */
-  private serialize<T>(id: SessionId, op: () => Promise<T> | T): Promise<T> {
+  private serialize<T>(
+    id: SessionId,
+    op: () => Promise<T> | T,
+    signal?: AbortSignal,
+  ): Promise<T> {
    const prior = this.chains.get(id) ?? Promise.resolve()
-    const next = prior.then(op, op)
+    let started = false
+    const run = (): Promise<T> | T => {
+      signal?.throwIfAborted()
+      started = true
+      return op()
+    }
+    const next = prior.then(run, run)
    // Keep the chain alive but swallow this op's rejection for the NEXT waiter
    // (the caller still sees the real rejection via `next`).
    const tail = next.then(() => undefined, () => undefined)
@@ -343,7 +370,7 @@ export class PersistenceCoordinator<TornMarker = unknown> {
    void tail.then(() => {
      if (this.chains.get(id) === tail) this.chains.delete(id)
    })
-    return next
+    return signal === undefined ? next : observeQueuedAbort(next, signal, () => started)
  }

  /** Build a state for a session discovered in storage but not yet in memory. */
@@ -615,3 +642,50 @@ export class PersistenceCoordinator<TornMarker = unknown> {
    live.pending.splice(0, batch.length)
  }
 }
+
+/**
+ * Give an observation caller a prompt cancellation view of queued work.
+ *
+ * The serialized `operation` remains in the same-id chain and checks the signal
+ * before invoking backend work. Observing its settlement here therefore cannot
+ * detach a storage read or let a later operation overtake its predecessor.
+ */
+function observeQueuedAbort<T>(
+  operation: Promise<T>,
+  signal: AbortSignal,
+  started: () => boolean,
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    let settled = false
+    const finish = (callback: () => void): void => {
+      if (settled) return
+      settled = true
+      signal.removeEventListener('abort', onAbort)
+      callback()
+    }
+    const onAbort = (): void => {
+      if (started()) return
+      finish(() => {
+        try {
+          signal.throwIfAborted()
+        } catch (reason: unknown) {
+          rejectObservation(reject, reason)
+          return
+        }
+        /* v8 ignore next -- a native AbortSignal emits abort only after becoming aborted */
+        reject(new Error('persistence observation abort event lacked an aborted signal'))
+      })
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+    operation.then(
+      (value) => { finish(() => { resolve(value) }) },
+      (reason: unknown) => { finish(() => { rejectObservation(reject, reason) }) },
+    )
+    if (signal.aborted) onAbort()
+  })
+}
+
+/** Preserve an exact provider or AbortSignal reason, including legacy non-Error values. */
+function rejectObservation(reject: (reason?: unknown) => void, reason: unknown): void {
+  reject(reason)
+}
--- a/packages/session-persistence/session-persistence/src/index.ts
+++ b/packages/session-persistence/session-persistence/src/index.ts
@@ -103,15 +103,17 @@ export abstract class SessionPersistence extends Service {
   * This read is serialized with writes for the same id and returns detached
   * values, so observers cannot mutate backend-owned state.
   * @param id - the persisted session to inspect.
+   * @param signal - optional cancellation for queued and backend read work.
   * @returns the header and valid stored event prefix exactly as observed.
   */
-  abstract inspect(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
+  abstract inspect(id: SessionId, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }>

  /**
   * Lightweight listing from metadata, without a full-log parse.
+   * @param signal - optional cancellation for backend listing work.
   * @returns one header per materialized session.
   */
-  abstract list(): Promise<SessionHeader[]>
+  abstract list(signal?: AbortSignal): Promise<SessionHeader[]>

  /**
   * List materialized sessions with cheap per-log change tokens.
--- a/packages/session-persistence/session-persistence/tests/contract.ts
+++ b/packages/session-persistence/session-persistence/tests/contract.ts
@@ -222,6 +222,21 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
      }
    })

+    it('rejects pre-aborted observation reads with the exact cancellation reason', async () => {
+      const { persistence, dispose } = await make()
+      try {
+        const reason = new Error('persistence observation cancelled')
+        const controller = new AbortController()
+        controller.abort(reason)
+
+        await expect(persistence.list(controller.signal)).rejects.toBe(reason)
+        await expect(persistence.inspect(SessionId('cancelled-inspect'), controller.signal))
+          .rejects.toBe(reason)
+      } finally {
+        await dispose()
+      }
+    })
+
    it('lists stable lightweight revisions that change after an append', async () => {
      const { persistence, dispose } = await make()
      try {
--- a/packages/session-persistence/session-persistence/tests/persistence.spec.ts
+++ b/packages/session-persistence/session-persistence/tests/persistence.spec.ts
@@ -94,8 +94,8 @@ class MemoryPersistence extends SessionPersistence implements PersistenceBackend
    return this.coordinator.load(id)
  }

-  inspect(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
-    return this.coordinator.inspect(id)
+  inspect(id: SessionId, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    return this.coordinator.inspect(id, signal)
  }

  // --- PersistenceBackend hooks (the Map storage primitives) ---
@@ -132,7 +132,8 @@ class MemoryPersistence extends SessionPersistence implements PersistenceBackend
    if (closers.length > 0) entry.events.push(...structuredClone(closers) as SessionEvent[])
  }

-  async list(): Promise<SessionHeader[]> {
+  async list(signal?: AbortSignal): Promise<SessionHeader[]> {
+    signal?.throwIfAborted()
    return [...this.store.values()].map(e => structuredClone(e.meta))
  }

@@ -153,10 +154,10 @@ class ControlledBackend implements PersistenceBackend<never> {
  loadAttempts = 0
  repairAttempts = 0
  beforeAppend?: (attempt: number) => Promise<void>
-  beforeLoadStored?: (attempt: number) => Promise<void>
+  beforeLoadStored?: (attempt: number, signal?: AbortSignal) => Promise<void>

-  async loadStored(id: SessionId): Promise<StoredPrefix<never> | undefined> {
-    await this.beforeLoadStored?.(++this.loadAttempts)
+  async loadStored(id: SessionId, signal?: AbortSignal): Promise<StoredPrefix<never> | undefined> {
+    await this.beforeLoadStored?.(++this.loadAttempts, signal)
    const entry = this.store.get(id)
    if (entry === undefined) return undefined
    return { meta: structuredClone(entry.meta), events: structuredClone(entry.events) }
@@ -348,6 +349,109 @@ describe('PersistenceCoordinator stored identity', () => {
  })
 })

+describe('PersistenceCoordinator observation cancellation', () => {
+  it('promptly rejects a queued inspect without invoking it and keeps the same-id chain healthy', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const backend = new ControlledBackend()
+    const id = SessionId('queued-inspect-cancellation')
+    backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
+    const loadGate = Promise.withResolvers<boolean>()
+    backend.beforeLoadStored = async (attempt) => {
+      if (attempt === 1) await loadGate.promise
+    }
+    let coordinator!: PersistenceCoordinator<never>
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      coordinator = new PersistenceCoordinator(inner, backend)
+    }, { inject: ['sessions'] }))
+
+    try {
+      const prior = coordinator.inspect(id)
+      await vi.waitFor(() => { expect(backend.loadAttempts).toBe(1) })
+      const controller = new AbortController()
+      const reason = new Error('queued inspect cancelled')
+      const queued = coordinator.inspect(id, controller.signal)
+      let observedReason: unknown
+      const observedAbort = queued.catch((error: unknown) => {
+        observedReason = error
+      })
+
+      controller.abort(reason)
+
+      await vi.waitFor(() => { expect(observedReason).toBe(reason) })
+      expect(backend.loadAttempts).toBe(1)
+      const subsequent = coordinator.inspect(id)
+      expect(backend.loadAttempts).toBe(1)
+
+      loadGate.resolve(true)
+      await expect(prior).resolves.toMatchObject({ meta: { id } })
+      await observedAbort
+      await expect(subsequent).resolves.toMatchObject({ meta: { id } })
+      expect(backend.loadAttempts).toBe(2)
+      await vi.waitFor(() => {
+        expect((coordinator as unknown as CoordinatorInternals).chains.size).toBe(0)
+      })
+    } finally {
+      loadGate.resolve(true)
+      await fiber.dispose()
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('waits for active cooperative inspection cleanup before rejecting cancellation', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const backend = new ControlledBackend()
+    const id = SessionId('active-inspect-cancellation')
+    backend.store.set(id, { meta: meta(id), events: oneTurnLog() })
+    const cleanupGate = Promise.withResolvers<boolean>()
+    let cleanupComplete = false
+    backend.beforeLoadStored = async (_attempt, signal) => {
+      await new Promise<void>((resolve) => {
+        signal?.addEventListener('abort', () => {
+          void cleanupGate.promise.then(() => {
+            cleanupComplete = true
+            resolve()
+          })
+        }, { once: true })
+      })
+      throw new Error('backend cancellation after cleanup')
+    }
+    let coordinator!: PersistenceCoordinator<never>
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      coordinator = new PersistenceCoordinator(inner, backend)
+    }, { inject: ['sessions'] }))
+
+    try {
+      const controller = new AbortController()
+      const reason = new Error('active inspect cancelled')
+      const pending = coordinator.inspect(id, controller.signal)
+      let observedReason: unknown
+      const observed = pending.catch((error: unknown) => {
+        observedReason = error
+      })
+      await vi.waitFor(() => { expect(backend.loadAttempts).toBe(1) })
+
+      controller.abort(reason)
+      await Promise.resolve()
+
+      expect(observedReason).toBeUndefined()
+      expect(cleanupComplete).toBe(false)
+      cleanupGate.resolve(true)
+      await observed
+      expect(cleanupComplete).toBe(true)
+      expect(observedReason).toBe(reason)
+      const backendFailure = new Error('later inspection failure')
+      backend.beforeLoadStored = () => Promise.reject(backendFailure)
+      await expect(coordinator.inspect(id)).rejects.toBe(backendFailure)
+    } finally {
+      cleanupGate.resolve(true)
+      await fiber.dispose()
+      await ctx.fiber.dispose()
+    }
+  })
+})
+
 describe('PersistenceCoordinator retirement', () => {
  it('a retiring unmaterialized owner without buffered events releases its id', async () => {
    const ctx = new Context()