dsh-browser-application 0.37.0

package/src/session-deferral.ts

@@ -0,0 +1,296 @@
+/**
+ * Defer real session creation until the first prompt.
+ *
+ * The panel calls `session.create` as soon as it connects, but a session that
+ * is opened and never used should leave zero trace in the store/GUI. This
+ * wrapper answers `session.create` with a provisional id (minted locally,
+ * nothing persisted), serves `session.history` for provisional ids as empty,
+ * and materializes the real session — same id, original create payload — on
+ * the first `session.prompt` for that id. Abandoned provisional ids are
+ * pruned after {@link PROVISIONAL_TTL_MS}.
+ *
+ * Provisional sessions also answer `session.models` from the host-wide
+ * `session.modelCatalog` (via the Host API adapter, plus a pending switch)
+ * and remember `session.selectModel` until materialization, so the composer can
+ * show a model switcher before the first message.
+ *
+ * @module dsh-browser-application/src/session-deferral
+ */
+
+import type { ImageAttachmentLimits } from '@deepseek-ai/dsh-attachment'
+import type { BrowserHostApi, HostRpcCall, HostRpcResult } from './host-api.ts'
+import { isRecord } from './host-api.ts'
+
+/** Provisional entries older than this are dropped on the next create. */
+const PROVISIONAL_TTL_MS = 30 * 60_000
+
+interface ModelSelection {
+  provider: string
+  model: string
+  reasoningEffort?: string
+}
+
+interface ProvisionalEntry {
+  /** The original create payload, replayed at materialization (keeps cwd/workspaceId). */
+  payload: Record<string, unknown>
+  createdAt: number
+  /** Keep failed model selections retryable after the Host Session was created. */
+  materialized?: boolean
+  /** Composer switch chosen before the session exists on the Host. */
+  selection?: ModelSelection
+}
+
+/**
+ * Wrap the gateway sessions API so `session.create` returns a provisional id
+ * without creating anything; the real session materializes on the first
+ * `session.prompt` for that id.
+ *
+ * @param api - Gateway API implementation.
+ * @param enabled - Whether deferral is active; false returns the API untouched.
+ * @param imageLimits - actual host image capability, used for the synthetic
+ * empty history before the deferred Session exists.
+ * @returns the original API when disabled, otherwise the wrapped API.
+ */
+export function withSessionDeferral(
+  api: BrowserHostApi,
+  enabled: boolean,
+  imageLimits?: ImageAttachmentLimits,
+): BrowserHostApi {
+  if (!enabled) return api
+
+  const provisional = new Map<string, ProvisionalEntry>()
+  const materializing = new Map<string, Promise<HostRpcResult>>()
+
+  const prune = (): void => {
+    const cutoff = Date.now() - PROVISIONAL_TTL_MS
+    for (const [id, entry] of provisional) {
+      if (entry.createdAt < cutoff && !entry.materialized && !materializing.has(id)) provisional.delete(id)
+    }
+  }
+
+  const mintedId = (payload: Record<string, unknown>): string =>
+    typeof payload.sessionId === 'string' ? payload.sessionId : `session-${crypto.randomUUID()}`
+
+  async function materialize(sessionId: string, entry: ProvisionalEntry, signal: AbortSignal): Promise<HostRpcResult> {
+    if (!entry.materialized) {
+      const created = await api.call({
+        rpcId: crypto.randomUUID(),
+        method: 'session.create',
+        payload: { ...entry.payload, sessionId },
+        signal,
+      })
+      if (!created.ok) return created
+      entry.materialized = true
+    }
+    // All prompts share this barrier, including those arriving during selection.
+    // A changed choice must also succeed before any queued prompt is admitted.
+    while (entry.selection !== undefined) {
+      const selection = entry.selection
+      const selected = await api.call({
+        rpcId: crypto.randomUUID(),
+        method: 'session.selectModel',
+        payload: { sessionId, ...selection },
+        signal,
+      })
+      if (!selected.ok) return selected
+      if (entry.selection === selection) delete entry.selection
+    }
+    provisional.delete(sessionId)
+    return { ok: true, value: { sessionId } }
+  }
+
+  return {
+    async call(call: HostRpcCall): Promise<HostRpcResult> {
+      if (call.method === 'session.create') {
+        if (!isRecord(call.payload)) {
+          return { ok: false, error: { code: 'bad-request', message: 'session.create payload must be an object', details: {} } }
+        }
+        prune()
+        const sessionId = mintedId(call.payload)
+        provisional.set(sessionId, { payload: { ...call.payload }, createdAt: Date.now() })
+        return { ok: true, value: { sessionId } }
+      }
+      if (call.method === 'session.history') {
+        const sessionId = sessionIdOf(call.payload)
+        if (sessionId === undefined || !provisional.has(sessionId)
+          || provisional.get(sessionId)!.materialized) return api.call(call)
+        return {
+          ok: true,
+          value: {
+            events: [],
+            hasMore: false,
+            ...(imageLimits === undefined
+              ? {}
+              : { projections: { asOfSeq: -1, values: { imageLimits } } }),
+          },
+        }
+      }
+      if (call.method === 'session.models') {
+        const sessionId = sessionIdOf(call.payload)
+        if (sessionId === undefined || !provisional.has(sessionId)) return api.call(call)
+        return provisionalModels(api, provisional.get(sessionId)!, call.signal)
+      }
+      if (call.method === 'session.selectModel') {
+        const sessionId = sessionIdOf(call.payload)
+        if (sessionId === undefined || !provisional.has(sessionId)) return api.call(call)
+        const entry = provisional.get(sessionId)!
+        const selected = selectionOf(call.payload)
+        if (selected === undefined) {
+          return {
+            ok: false,
+            error: {
+              code: 'bad-request',
+              message: 'session.selectModel requires provider and model',
+              details: {},
+            },
+          }
+        }
+        entry.selection = selected
+        return { ok: true, value: { selected: { ...selected } } }
+      }
+      if (call.method !== 'session.prompt') return api.call(call)
+      const sessionId = sessionIdOf(call.payload)
+      if (sessionId === undefined) return api.call(call)
+      const entry = provisional.get(sessionId)
+      if (entry === undefined) return api.call(call)
+      const existing = materializing.get(sessionId)
+      const pending = existing ?? materialize(sessionId, entry, call.signal)
+      if (existing === undefined) {
+        materializing.set(sessionId, pending)
+        void pending.then(
+          () => { materializing.delete(sessionId) },
+          () => { materializing.delete(sessionId) },
+        )
+      }
+      const created = await pending
+      if (!created.ok) return created
+      return api.call(call)
+    },
+    events: signal => api.events(signal),
+    respond: (rpcId, result, signal) => api.respond(rpcId, result, signal),
+  }
+}
+
+function sessionIdOf(payload: unknown): string | undefined {
+  if (!isRecord(payload)) return undefined
+  return typeof payload.sessionId === 'string' ? payload.sessionId : undefined
+}
+
+function selectionOf(payload: unknown): ModelSelection | undefined {
+  if (!isRecord(payload)) return undefined
+  const provider = typeof payload.provider === 'string' ? payload.provider.trim() : ''
+  const model = typeof payload.model === 'string' ? payload.model.trim() : ''
+  if (provider === '' || model === '') return undefined
+  const reasoningEffort = typeof payload.reasoningEffort === 'string' && payload.reasoningEffort.trim() !== ''
+    ? payload.reasoningEffort.trim()
+    : undefined
+  return {
+    provider,
+    model,
+    ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
+  }
+}
+
+/** Build a session.models-shaped answer from the host catalog for a provisional id. */
+async function provisionalModels(
+  api: BrowserHostApi,
+  entry: ProvisionalEntry,
+  signal: AbortSignal,
+): Promise<HostRpcResult> {
+  // Inner API (not the deferral wrapper): session.models → session/modelCatalog.
+  const catalog = await api.call({
+    rpcId: crypto.randomUUID(),
+    method: 'session.models',
+    payload: {},
+    signal,
+  })
+  if (!catalog.ok) return catalog
+  const groups = isRecord(catalog.value) && Array.isArray(catalog.value.groups)
+    ? catalog.value.groups
+    : []
+  const failures = isRecord(catalog.value) && Array.isArray(catalog.value.failures)
+    ? catalog.value.failures
+    : []
+  const catalogCurrent = isRecord(catalog.value) ? modelSelectionOf(catalog.value.current) : undefined
+  const current = entry.selection
+    ?? catalogCurrent
+    ?? await defaultSelection(api, signal)
+    ?? firstCatalogSelection(groups)
+  if (current === undefined) {
+    return {
+      ok: true,
+      value: {
+        current: { provider: 'none', model: 'none' },
+        routable: false,
+        groups,
+        failures,
+      },
+    }
+  }
+  return {
+    ok: true,
+    value: {
+      current: { ...current },
+      routable: true,
+      groups,
+      failures,
+    },
+  }
+}
+
+function modelSelectionOf(value: unknown): ModelSelection | undefined {
+  if (!isRecord(value)) return undefined
+  const provider = typeof value.provider === 'string' ? value.provider.trim() : ''
+  const model = typeof value.model === 'string' ? value.model.trim() : ''
+  if (provider === '' || model === '') return undefined
+  const reasoningEffort = typeof value.reasoningEffort === 'string' && value.reasoningEffort.trim() !== ''
+    ? value.reasoningEffort.trim()
+    : undefined
+  return {
+    provider,
+    model,
+    ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
+  }
+}
+
+async function defaultSelection(
+  api: BrowserHostApi,
+  signal: AbortSignal,
+): Promise<ModelSelection | undefined> {
+  const described = await api.call({
+    rpcId: crypto.randomUUID(),
+    method: 'settings.describe',
+    payload: {},
+    signal,
+  })
+  if (!described.ok || !isRecord(described.value) || !Array.isArray(described.value.namespaces)) {
+    return undefined
+  }
+  const defaults = described.value.namespaces.find((candidate) => (
+    isRecord(candidate) && candidate.ns === 'agent-default-model'
+  ))
+  const value = isRecord(defaults) && isRecord(defaults.value) ? defaults.value : undefined
+  if (value === undefined) return undefined
+  const provider = typeof value.provider === 'string' ? value.provider.trim() : ''
+  const model = typeof value.model === 'string' ? value.model.trim() : ''
+  if (provider === '' || model === '') return undefined
+  const reasoningEffort = typeof value.reasoningEffort === 'string' && value.reasoningEffort.trim() !== ''
+    ? value.reasoningEffort.trim()
+    : undefined
+  return {
+    provider,
+    model,
+    ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
+  }
+}
+
+function firstCatalogSelection(groups: unknown[]): ModelSelection | undefined {
+  for (const group of groups) {
+    if (!isRecord(group) || typeof group.id !== 'string' || !Array.isArray(group.models)) continue
+    for (const model of group.models) {
+      if (!isRecord(model) || typeof model.id !== 'string' || model.id.trim() === '') continue
+      return { provider: group.id, model: model.id }
+    }
+  }
+  return undefined
+}

package/src/session-history.ts

@@ -0,0 +1,220 @@
+/**
+ * Session history decoding: the `session/follow` baseline, its records, and the
+ * compact chunk-row expansion older logs still use.
+ *
+ * @module dsh-browser-application/src/session-history
+ */
+
+import { openWireStream, type TypertGatewayLike } from './dsh-gateway.ts'
+import { isRecord } from './host-api.ts'
+
+export interface SessionSnapshot {
+  /** Inclusive Host log tip from session/follow; required for later session/page calls. */
+  readonly cursor: number
+  readonly records: readonly unknown[]
+  readonly hasMore: boolean
+  readonly projections?: unknown
+  readonly assistantStream?: unknown
+  readonly snapshotId?: string
+}
+
+export async function oneShotSessionSnapshot(
+  gateway: TypertGatewayLike,
+  sessionId: string,
+  outerSignal: AbortSignal,
+  maxMessages?: number,
+): Promise<SessionSnapshot> {
+  const controller = new AbortController()
+  const signal = AbortSignal.any([outerSignal, controller.signal])
+  const source = await openWireStream(gateway,
+    'session/follow',
+    {
+      args: {
+        request: {
+          address: { kind: 'session', sessionId },
+          assistantStream: true,
+          ...(maxMessages === undefined ? {} : { maxMessages }),
+        },
+      },
+    },
+    signal,
+  )
+  const iterator = source[Symbol.asyncIterator]()
+  try {
+    const first = await iterator.next()
+    if (first.done || !isSessionSnapshot(first.value)) {
+      throw new TypeError('session/follow did not begin with a snapshot')
+    }
+    return {
+      cursor: first.value.cursor,
+      records: first.value.records,
+      hasMore: first.value.hasMore,
+      ...(first.value.projections === undefined ? {} : { projections: first.value.projections }),
+      ...(first.value.assistantStream === undefined ? {} : { assistantStream: first.value.assistantStream }),
+    }
+  } finally {
+    controller.abort(new Error('Session snapshot received'))
+    await iterator.return?.()
+  }
+}
+
+export function historyValue(snapshot: SessionSnapshot): Record<string, unknown> {
+  return {
+    // V3 records remain durable events with embedded Assistant streams. Keep
+    // the legacy chunk-row decoder for older logs/Hosts, without assigning
+    // synthetic durable seqs to the new process-local assistant stream.
+    events: snapshot.records.flatMap(historyRecordEvents).map(event => ({ event })),
+    hasMore: snapshot.hasMore,
+    ...(snapshot.projections === undefined ? {} : { projections: snapshot.projections }),
+    ...(snapshot.assistantStream === undefined ? {} : { assistantStream: snapshot.assistantStream }),
+    ...(snapshot.snapshotId === undefined ? {} : { snapshotId: snapshot.snapshotId }),
+  }
+}
+
+export function historyPageValue(page: unknown): Record<string, unknown> {
+  if (!isRecord(page) || !Array.isArray(page.records) || typeof page.hasMore !== 'boolean') {
+    throw new TypeError('session/page returned an invalid history page')
+  }
+  return historyValue({
+    cursor: -1,
+    records: page.records,
+    hasMore: page.hasMore,
+    ...(page.projections === undefined ? {} : { projections: page.projections }),
+  })
+}
+
+export function optionalNonNegativeInteger(
+  payload: unknown,
+  key: string,
+): number | undefined {
+  if (!isRecord(payload) || !(key in payload) || payload[key] === undefined) return undefined
+  const value = payload[key]
+  if (!Number.isSafeInteger(value) || (value as number) < 0 || Object.is(value, -0)) {
+    throw new TypeError(`${key} must be a non-negative safe integer`)
+  }
+  return value as number
+}
+
+export function optionalPositiveInteger(
+  payload: unknown,
+  key: string,
+): number | undefined {
+  if (!isRecord(payload) || !(key in payload) || payload[key] === undefined) return undefined
+  const value = payload[key]
+  if (!Number.isSafeInteger(value) || (value as number) < 1) {
+    throw new TypeError(`${key} must be a positive safe integer`)
+  }
+  return value as number
+}
+
+function historyRecordEvents(record: unknown): Record<string, unknown>[] {
+  if (!isRecord(record)
+    || (record.type !== 'event' && record.type !== 'chunks')
+    || !isRecord(record.event)) {
+    throw new TypeError('session history carried an invalid record')
+  }
+  const event = record.event
+  if (!isChunkRowEvent(event)) {
+    if (record.type === 'chunks') {
+      throw new TypeError('session history chunks record carried a non-chunk event')
+    }
+    return [event]
+  }
+
+  const data = event.data
+  const members = event.type === 'chunkrow/tool-call-chunks' ? data.args : data.texts
+  const deltas = data.dt
+  if (!Array.isArray(members) || members.length === 0 || members.some(member => typeof member !== 'string')
+    || !Array.isArray(deltas) || deltas.length !== members.length - 1
+    || deltas.some(delta => !Number.isSafeInteger(delta))) {
+    throw new TypeError(`${event.type} carried an invalid compact run`)
+  }
+  if (members.length - 1 > Number.MAX_SAFE_INTEGER - event.seq) {
+    throw new TypeError(`${event.type} sequence range is unsafe`)
+  }
+
+  const events: Record<string, unknown>[] = []
+  let time = event.time
+  for (let index = 0; index < members.length; index += 1) {
+    if (index > 0) time += deltas[index - 1] as number
+    if (!Number.isSafeInteger(time)) throw new TypeError(`${event.type} timestamp range is unsafe`)
+    const chunk = compactChunk(event.type, data, members[index] as string)
+    events.push({
+      type: 'assistant/chunk',
+      seq: event.seq + index,
+      time,
+      data: { turn: data.turn, step: data.step, chunk },
+    })
+  }
+  return events
+}
+
+type ChunkRowEvent = {
+  readonly type: 'chunkrow/text-chunks' | 'chunkrow/reasoning-chunks' | 'chunkrow/tool-call-chunks'
+  readonly seq: number
+  readonly time: number
+  readonly data: Record<string, unknown> & {
+    readonly turn: number
+    readonly step: number
+    readonly index: number
+    readonly dt: readonly unknown[]
+    readonly texts?: readonly unknown[]
+    readonly args?: readonly unknown[]
+  }
+}
+
+function isChunkRowEvent(event: Record<string, unknown>): event is ChunkRowEvent {
+  if (event.type !== 'chunkrow/text-chunks'
+    && event.type !== 'chunkrow/reasoning-chunks'
+    && event.type !== 'chunkrow/tool-call-chunks') return false
+  if (!Number.isSafeInteger(event.seq) || (event.seq as number) < 0 || !Number.isSafeInteger(event.time)
+    || !isRecord(event.data)) {
+    throw new TypeError(`${String(event.type)} carried an invalid compact envelope`)
+  }
+  const data = event.data
+  if (typeof data.turn !== 'number' || typeof data.step !== 'number' || typeof data.index !== 'number') {
+    throw new TypeError(`${String(event.type)} carried invalid compact coordinates`)
+  }
+  if (event.type === 'chunkrow/tool-call-chunks'
+    && (typeof data.id !== 'string' || (data.name !== undefined && typeof data.name !== 'string'))) {
+    throw new TypeError(`${event.type} carried an invalid tool identity`)
+  }
+  return true
+}
+
+function compactChunk(
+  type: ChunkRowEvent['type'],
+  data: ChunkRowEvent['data'],
+  member: string,
+): Record<string, unknown> {
+  if (type === 'chunkrow/text-chunks') {
+    return { type: 'text-delta', index: data.index, text: member }
+  }
+  if (type === 'chunkrow/reasoning-chunks') {
+    return { type: 'reasoning-delta', index: data.index, text: member }
+  }
+  return {
+    type: 'tool-call-delta',
+    index: data.index,
+    id: data.id,
+    ...(data.name === undefined ? {} : { name: data.name }),
+    argumentsDelta: member,
+  }
+}
+
+export function isSessionSnapshot(value: unknown): value is {
+  readonly type: 'snapshot'
+  readonly cursor: number
+  readonly records: readonly unknown[]
+  readonly hasMore: boolean
+  readonly projections?: unknown
+  readonly assistantStream?: unknown
+} {
+  return isRecord(value)
+    && value.type === 'snapshot'
+    && Number.isSafeInteger(value.cursor)
+    && (value.cursor as number) >= -1
+    && (value.cursor as number) !== Number.MAX_SAFE_INTEGER
+    && Array.isArray(value.records)
+    && typeof value.hasMore === 'boolean'
+}

package/src/session-purge.ts

@@ -0,0 +1,154 @@
+/**
+ * File-level removal of one session's durable storage under the dsh home.
+ *
+ * The gateway exposes no session.delete, so the bridge performs the removal
+ * itself: this module archives the session under exclusive write ownership,
+ * then removes its durable data while retaining the kernel lock's pathname.
+ * Session ids are validated against the persisted shape, only data within
+ * exact-name directories two levels below the sessions root is removed, and
+ * running sessions are refused before anything touches the disk.
+ *
+ * @module dsh-browser-application/src/session-purge
+ */
+
+import { lstat, readdir, rm } from 'node:fs/promises'
+import path from 'node:path'
+
+/** Stable failure codes surfaced to the panel. Open set: callers must tolerate growth. */
+export type SessionPurgeErrorCode = 'not-found' | 'running' | 'invalid-id' | 'internal'
+
+/** Error thrown by {@link purgeSessionFiles}; the server turns it into a wire error. */
+export class SessionPurgeError extends Error {
+  constructor(
+    readonly code: SessionPurgeErrorCode,
+    message: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options)
+    this.name = 'SessionPurgeError'
+  }
+}
+
+/** Persisted session ids are `session-` plus one lowercase UUID. */
+const SESSION_ID_PATTERN = /^session-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u
+/** POSIX flock is attached to this inode; unlinking it defeats exclusion. */
+const SESSION_LOCK_FILENAME = 'session.lock'
+
+/** Dependencies purging needs from the plugin. */
+export interface SessionPurgeDeps {
+  /** The dsh sessions root (`dshHomePath('sessions')`). */
+  sessionsRoot: string
+  /** Session ids currently running; purging any of these is refused. */
+  runningSessionIds: ReadonlySet<string>
+  /**
+   * Claim the runtime's exclusive write ownership (including its kernel lock).
+   * The returned handle must remain held until removal finishes. Opening a
+   * read handle, checking for a lock file, or checking only Agent status does
+   * not provide exclusion: idle Agents and other processes can own the log.
+   */
+  acquireOwnership(sessionId: string): Promise<{ close(): Promise<void> }>
+  /** Archive while the durable session still exists and exclusive ownership is held. */
+  archiveSession(sessionId: string): Promise<void>
+}
+
+/**
+ * Validate one session id against the persisted shape. Rejects everything
+ * that could escape the sessions root (separators, dot segments) before any
+ * filesystem call sees it.
+ * @param sessionId - untrusted id from the panel.
+ * @returns the id when well-formed.
+ * @throws SessionPurgeError with code `invalid-id` otherwise.
+ */
+export function assertPurgeableSessionId(sessionId: string): string {
+  if (!SESSION_ID_PATTERN.test(sessionId)) {
+    throw new SessionPurgeError('invalid-id', `session id "${sessionId}" does not match the persisted shape`)
+  }
+  return sessionId
+}
+
+/**
+ * Permanently delete a session's data, keeping its directory and lock inode.
+ * The runtime refuses ambiguous duplicate session identities across workspaces.
+ * @param deps - root and running-set inputs.
+ * @param sessionId - validated session id.
+ * @returns nothing; throws {@link SessionPurgeError} on refusal or failure.
+ */
+export async function purgeSessionFiles(deps: SessionPurgeDeps, sessionId: string): Promise<void> {
+  assertPurgeableSessionId(sessionId)
+  if (deps.runningSessionIds.has(sessionId)) {
+    throw new SessionPurgeError('running', 'refusing to purge a running session; cancel it first')
+  }
+
+  let workspaces: string[]
+  try {
+    workspaces = await readdir(deps.sessionsRoot, { withFileTypes: true })
+      .then((entries) => entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name))
+  } catch (error: unknown) {
+    throw new SessionPurgeError('internal', `could not read the sessions root "${deps.sessionsRoot}": ${String(error)}`)
+  }
+
+  const targets: string[] = []
+  for (const workspace of workspaces) {
+    // path.join is safe here: the id pattern above excludes separators and
+    // dot segments, so the joined segment cannot escape the workspace dir.
+    const candidate = path.join(deps.sessionsRoot, workspace, sessionId)
+    try {
+      if (!(await lstat(candidate)).isDirectory()) continue
+      const entries = await readdir(candidate)
+      if (entries.some(entry => entry !== SESSION_LOCK_FILENAME)) targets.push(candidate)
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+        throw new SessionPurgeError('internal', `could not inspect "${candidate}": ${String(error)}`, { cause: error })
+      }
+    }
+  }
+
+  if (targets.length === 0) {
+    throw new SessionPurgeError('not-found', `no durable storage found for session "${sessionId}"`)
+  }
+  let ownership: { close(): Promise<void> }
+  try {
+    ownership = await deps.acquireOwnership(sessionId)
+  } catch (error: unknown) {
+    // Match the public error identity across independently loaded runtime
+    // copies without depending on a private JSONL lock implementation.
+    if (error instanceof Error && error.name === 'SessionAlreadyOwnedError') {
+      throw new SessionPurgeError(
+        'running',
+        'session is still owned by a runtime; release the session or restart that runtime, then retry deletion',
+      )
+    }
+    throw new SessionPurgeError('internal', `could not acquire exclusive session ownership: ${String(error)}`)
+  }
+  let failure: unknown
+  let archived = false
+  try {
+    // The public archive API checks existence. Calling it after deletion
+    // succeeds only accidentally when its header cache already knows this id.
+    await deps.archiveSession(sessionId)
+    archived = true
+    for (const target of targets) {
+      if (!(await lstat(target)).isDirectory()) throw new Error(`session directory changed: ${target}`)
+      // Re-scan after write-open: opening an old log may materialize V3.
+      for (const entry of await readdir(target)) {
+        if (entry === SESSION_LOCK_FILENAME) continue
+        await rm(path.join(target, entry), { recursive: true, force: true })
+      }
+    }
+  } catch (error: unknown) {
+    failure = new SessionPurgeError('internal', archived
+      ? `session was archived, but durable cleanup failed: ${String(error)}`
+      : `could not archive session; durable data was preserved: ${String(error)}`, { cause: error })
+  } finally {
+    try {
+      await ownership.close()
+    } catch (error: unknown) {
+      failure = failure === undefined
+        ? new SessionPurgeError('internal', `session was archived and cleared, but ownership release failed: ${String(error)}`, { cause: error })
+        : new SessionPurgeError('internal', `${String(failure)}; ownership release also failed: ${String(error)}`, {
+          cause: new AggregateError([failure, error], 'session purge and ownership release failed'),
+        })
+    }
+  }
+  if (failure !== undefined) throw failure
+}