dsh-code 1.3.0 → 1.5.0

package/src/runner/session-io.ts

@@ -0,0 +1,245 @@
+/** Session directory IO exposed to the picker, /delete, and /export.
+ *
+ * The kernel persistence seam has NO deletion API by design — logs accumulate
+ * "until removed externally" — so removal is planned, layout-checked, and
+ * lease-guarded here before any file is touched. Every read goes through the
+ * in-process session-query engine, so this module stays free of `app.ts` and
+ * of the Ink tree.
+ *
+ * @module @deepseek-ai/dsh-code/runner/session-io
+ */
+
+import { readdir, rm, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import { SessionAlreadyOwnedError } from '@deepseek-ai/dsh-session-persistence'
+import { buildExportMarkdown } from '../render/export.ts'
+import {
+  acquireSessionDeletionLeases,
+  isSessionArtifactName,
+  jsonlSessionRoot,
+  mergeSessionTitles,
+  planSessionDeletion,
+  projectSessionRows,
+  releaseSessionDeletionLeases,
+  sessionArtifactDirectory,
+  sessionDirectoryFor,
+  sessionRowMatchesQuery,
+  type SessionDeletionPersistence,
+  type SessionDirectoryOptions,
+  type SessionQueryService,
+  type SessionRow,
+} from '../session/session-directory.ts'
+import { createTranscriptStore } from '../session/store.ts'
+
+/**
+ * The persistence surface this module needs: the JSONL backend's public
+ * session root plus its per-session write handles. Typing the narrow shape
+ * instead of the upstream service keeps the IO injectable from a test double.
+ */
+export interface SessionIoPersistence extends SessionDeletionPersistence {
+  /** JSONL backend plugin config carrying the session root, when exposed. */
+  readonly config?: { readonly root?: unknown }
+}
+
+/** Services the session IO closes over. */
+export interface SessionIoServices {
+  /** In-process session-query engine; absent in profiles without one. */
+  readonly sessionQuery?: SessionQueryService
+  /** The durable persistence service; absent in profiles without one. */
+  readonly persistence?: SessionIoPersistence
+  /** The session currently visible in the UI (self-deletion guard). */
+  readonly activeSessionId: () => string | undefined
+}
+
+/** Session directory reads and the guarded /delete operation. */
+export interface SessionIo {
+  /** Project the session directory for the picker (query-filtered). */
+  readonly loadSessions: (options: SessionDirectoryOptions, signal?: AbortSignal) => Promise<readonly SessionRow[]>
+  /** Delete one session subtree, returning the outcome line. */
+  readonly deleteSession: (id: string) => Promise<string>
+  /** Render one session's whole transcript as export Markdown. */
+  readonly loadSessionTranscript: (id: string, signal?: AbortSignal) => Promise<string>
+}
+
+/** Maximum session artifact directories inspected at once by the picker. */
+export const SESSION_ARTIFACT_READ_CONCURRENCY = 16
+
+/**
+ * Map a collection with a fixed worker count while preserving input order.
+ * The picker may own thousands of persisted sessions; an unbounded
+ * `Promise.all` turns those into one filesystem burst and can exhaust handles
+ * on Windows or remote filesystems.
+ *
+ * @internal Exported for the deterministic concurrency regression.
+ */
+export async function mapConcurrent<T, R>(
+  items: readonly T[],
+  concurrency: number,
+  mapper: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  if (!Number.isSafeInteger(concurrency) || concurrency < 1) throw new RangeError('concurrency must be a positive safe integer')
+  const results = new Array<R>(items.length)
+  let next = 0
+  const worker = async (): Promise<void> => {
+    for (;;) {
+      const index = next
+      if (index >= items.length) return
+      next += 1
+      results[index] = await mapper(items[index], index)
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker))
+  return results
+}
+
+/**
+ * Bind the session IO to one runner's services.
+ * @param services - the query engine, persistence, and the live-session probe.
+ * @returns the picker/delete/export reads used by the app bridge.
+ */
+export function createSessionIo(services: SessionIoServices): SessionIo {
+  const { sessionQuery, persistence } = services
+
+  const loadSessions = async (options: SessionDirectoryOptions, signal?: AbortSignal): Promise<readonly SessionRow[]> => {
+    if (sessionQuery === undefined) throw new Error('session query is unavailable in this profile')
+    const records = await sessionQuery.listSessions(signal)
+    // Last-activity timestamps for sorting (codex UpdatedAt default): the
+    // newest generation artifact's mtime under the JSONL layout. 0.1.5 dropped
+    // the persistence `locate()` query, so paths are derived from the
+    // backend's public config root. Backends without a JSONL config (or
+    // vanished directories) fall back to createdAt inside the projection.
+    const root = jsonlSessionRoot(persistence)
+    const updated = new Map<string, number>()
+    if (root !== undefined) {
+      const mtimes = await mapConcurrent(records, SESSION_ARTIFACT_READ_CONCURRENCY, async record => {
+        signal?.throwIfAborted()
+        try {
+          const dir = sessionDirectoryFor(root, record.header.cwd, record.header.id)
+          const entries = await readdir(dir, { withFileTypes: true })
+          const stats = await Promise.all(
+            entries.filter(entry => entry.isFile() && isSessionArtifactName(entry.name))
+              .map(entry => stat(join(dir, entry.name))),
+          )
+          signal?.throwIfAborted()
+          const newest = Math.max(...stats.map(info => info.mtimeMs))
+          return Number.isFinite(newest) ? [record.header.id, newest] as const : undefined
+        } catch {
+          // Cancellation must stop the picker; only a missing/unreadable
+          // artifact degrades to createdAt.
+          signal?.throwIfAborted()
+          return undefined
+        }
+      })
+      for (const pair of mtimes) {
+        if (pair !== undefined) updated.set(...pair)
+      }
+    }
+    const projected = projectSessionRows(records, { ...options, query: '' }, updated)
+    // Titles are the expensive fold. Fetch the first picker page when idle;
+    // a non-empty query loads more so the displayed title can match.
+    const titleBudget = options.query.trim() === '' ? 32 : Math.min(projected.length, 128)
+    const page = projected.slice(0, titleBudget)
+    if (page.length === 0) return projected
+    const observations = await sessionQuery.readTitleSnapshots(page.map(row => row.id), signal)
+    const titled = mergeSessionTitles(projected, observations)
+    return titled.filter(row => sessionRowMatchesQuery(row, options.query))
+  }
+
+  /**
+   * Delete one session subtree (/delete, codex semantics: subagent threads go
+   * with their root). The kernel persistence seam has NO deletion API by
+   * design — logs accumulate "until removed externally" — so this is the
+   * controlled external removal, in three phases with a hard boundary
+   * between planning and touching the filesystem:
+   *
+   * 1. `planSessionDeletion` collects the subtree and refuses when the root
+   *    or ANY member is live (a live child would outlive its deleted
+   *    parent), ordering the plan children-first.
+   * 2. Every plan node must derive to a guarded artifact directory
+   *    (`encodeSegment(id)` layout beneath the backend's config root).
+   *    Backends without a derivable artifact (non-JSONL) refuse the WHOLE
+   *    deletion here — no file has been touched yet, so a backend or layout
+   *    surprise can never strand a half-deleted subtree.
+   * 3. Acquire every node's public persistence write handle before touching
+   *    files. The JSONL backend holds its cross-process kernel lease for each
+   *    handle, so another terminal's live session refuses the whole deletion.
+   * 4. Artifacts are removed children-first while every lease remains held:
+   *    only an I/O error mid-delete can stop it short (reported with
+   *    removed/total counts), leaving the shallowest lineage intact.
+   *
+   * @param id - the root session id to delete.
+   * @returns the outcome line for the panel/notice.
+   */
+  const deleteSession = async (id: string): Promise<string> => {
+    if (sessionQuery === undefined) return 'session query is unavailable in this profile'
+    const activeId = services.activeSessionId()
+    if (activeId !== undefined && activeId === id) return 'cannot delete the session you are using — switch or /new first'
+    const records = await sessionQuery.listSessions()
+    const plan = planSessionDeletion(records, id)
+    if (!plan.ok) return plan.reason
+    // Phase 2 completes the plan before the first rm: derive and
+    // layout-check every node up front, so a refusal never leaves a
+    // partially removed subtree behind.
+    const root = jsonlSessionRoot(persistence)
+    if (root === undefined || persistence === undefined) {
+      return 'session backend exposes no deletable artifact (deletion is unsupported on this backend)'
+    }
+    const byId = new Map<string, (typeof records)[number]>(records.map(record => [record.header.id, record]))
+    const dirs = new Map<string, string>()
+    for (const node of plan.nodes) {
+      const record = byId.get(node.id)
+      if (record === undefined) return `no persisted session matches "${node.id}"`
+      const dir = sessionArtifactDirectory(sessionDirectoryFor(root, record.header.cwd, node.id), node.id)
+      if (dir === undefined) {
+        return `refusing to delete: unexpected artifact layout for ${node.id.slice(-12)}`
+      }
+      dirs.set(node.id, dir)
+    }
+    let leases
+    try {
+      leases = await acquireSessionDeletionLeases(persistence, plan.nodes.map(node => node.id))
+    } catch (error: unknown) {
+      if (error instanceof SessionAlreadyOwnedError) {
+        return `cannot delete ${error.sessionId.slice(-12)} — it is open in this or another process`
+      }
+      return `cannot safely lock sessions for deletion: ${error instanceof Error ? error.message : String(error)}`
+    }
+
+    let removed = 0
+    let outcome: string | undefined
+    for (const node of plan.nodes) {
+      const dir = dirs.get(node.id)!
+      try {
+        // Remove every canonical generation artifact this build knows; other
+        // sibling files are never ours to delete. The POSIX session.lock file
+        // deliberately remains because unlinking a held flock inode would
+        // forfeit the backend's exclusion guarantee.
+        const entries = await readdir(dir, { withFileTypes: true })
+        for (const entry of entries) {
+          if (entry.isFile() && isSessionArtifactName(entry.name)) {
+            await rm(join(dir, entry.name), { force: true })
+          }
+        }
+        await rm(dir, { force: true, recursive: false }).catch(() => {})
+        removed += 1
+      } catch (error: unknown) {
+        outcome = `delete failed for ${node.id.slice(-12)} after ${removed} of ${plan.nodes.length}: ${error instanceof Error ? error.message : String(error)}`
+        break
+      }
+    }
+    outcome ??= `deleted ${removed} session${removed === 1 ? '' : 's'}`
+    try {
+      await releaseSessionDeletionLeases(leases)
+    } catch (error: unknown) {
+      return `${outcome}; failed to release deletion locks: ${error instanceof Error ? error.message : String(error)}`
+    }
+    return outcome
+  }
+
+  const loadSessionTranscript = async (id: string, signal?: AbortSignal): Promise<string> => {
+    if (sessionQuery === undefined) throw new Error('session query is unavailable in this profile')
+    const snapshot = await sessionQuery.readSession(id, signal)
+    return buildExportMarkdown(createTranscriptStore(snapshot.events).getView(), snapshot.session.id)
+  }
+  return { loadSessions, deleteSession, loadSessionTranscript }
+}

package/src/runner/session-target.ts

@@ -0,0 +1,81 @@
+/** Session identity resolution for one terminal runner invocation.
+ *
+ * Turns parsed startup flags into the session this process will run, and maps
+ * a session id onto a filename-safe export default. Resolution reads persisted
+ * headers, so it is the runner's only pre-composition persistence IO; the
+ * remaining helpers are pure.
+ *
+ * @module @deepseek-ai/dsh-code/session-target
+ */
+
+import { randomUUID } from 'node:crypto'
+import type { SessionId, SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
+import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
+import { isSubagentSession, matchSessionId, newestRootForCwd } from '../session/session-directory.ts'
+import type { TuiStartup } from '../startup.ts'
+
+/** The session identity this invocation will run, plus whether it is resumed. */
+export interface Target {
+  sessionId: string
+  resume: boolean
+  mode?: string
+  cwd?: string
+  seed?: readonly SessionEvent[]
+  parentSession?: SessionId
+  /** Marks the session as a subagent conversation in the durable header. */
+  origin?: 'subagent'
+  seedLength?: number
+}
+
+/**
+ * Reduce a session id to a filename-safe /export default-name suffix. Session
+ * ids are normally minted `session-<uuid>`, but `--session` accepts arbitrary
+ * user text: path separators must never leak into the default export filename
+ * (which would escape the session cwd).
+ * @param id - the session id.
+ * @returns at most the last 8 filename-safe characters.
+ */
+export function exportSessionIdSuffix(id: string): string {
+  return id.replace(/[^a-zA-Z0-9._-]/gu, '_').slice(-8)
+}
+
+/**
+ * Resolve the invocation's target session against the persisted headers.
+ * @param startup - the parsed startup flags.
+ * @param persistence - the persistence service; required for resume/latest.
+ * @param cwd - the working directory `--continue` filters by.
+ * @returns the target identity.
+ * @throws with a user-facing message when the flags name nothing resolvable.
+ */
+export async function resolveTarget(startup: TuiStartup, persistence: SessionPersistence | undefined, cwd: string): Promise<Target> {
+  if (startup.kind === 'fresh') return { sessionId: `session-${randomUUID()}`, resume: false, mode: startup.mode }
+  if (startup.kind === 'named') {
+    // The id must not exist yet: reject before any Agent composition when the
+    // backend can tell us (a live collision is still caught by the session
+    // store at create time).
+    if (persistence !== undefined) {
+      const headers: readonly SessionHeader[] = (await persistence.list()).map(snapshot => snapshot.header)
+      if (headers.some(header => header.id === startup.sessionId)) {
+        throw new Error(`session "${startup.sessionId}" already exists; use --resume to continue it`)
+      }
+    }
+    return { sessionId: startup.sessionId, resume: false, mode: startup.mode }
+  }
+  if (persistence === undefined) {
+    throw new Error('cannot resolve the requested session: session persistence is not configured')
+  }
+  const headers: readonly SessionHeader[] = (await persistence.list()).map(snapshot => snapshot.header)
+  if (startup.kind === 'resume') {
+    const matched = matchSessionId(headers, startup.sessionId)
+    // Subagent conversations are read-only everywhere else; the CLI must not
+    // be a back door into appending root turns to a child's durable log.
+    if (isSubagentSession(matched)) {
+      throw new Error('subagent conversations are read-only; resume a root session')
+    }
+    return { sessionId: matched.id, resume: true }
+  }
+  // --continue: the newest persisted ROOT session whose header pins this cwd.
+  const newest = newestRootForCwd(headers, cwd)
+  if (newest === undefined) throw new Error(`no persisted session for this directory (${cwd}); start one without --continue`)
+  return { sessionId: newest.id, resume: true }
+}

package/src/runner/startup-config.ts

@@ -0,0 +1,54 @@
+/**
+ * Resolve the runner's startup flags from the loose plugin config.
+ *
+ * The Cordis config schema is deliberately loose (`kind` is an unvalidated
+ * string, narrowed here), so this is the single place that maps a config row
+ * onto the `TuiStartup` the runner consumes — pure, and unit-testable without
+ * a plugin context.
+ *
+ * @module @deepseek-ai/dsh-code/runner/startup-config
+ */
+
+import { parseThemeName } from '../theme.ts'
+import type { TuiStartup } from '../startup.ts'
+
+/** The config row shape this resolver narrows; satisfied by the plugin schema. */
+export interface StartupConfigRow {
+  /** How this invocation obtains its session identity. */
+  readonly kind: string
+  readonly sessionId?: string
+  readonly mode?: string
+  readonly theme?: string
+  readonly prompt?: string
+  readonly images?: readonly string[]
+}
+
+/**
+ * Narrow one config row to a startup.
+ *
+ * `resume`/`named` without a session id degrade to a fresh launch, an invalid
+ * theme string narrows to the dark default (and is therefore still present),
+ * and `mode` only survives on the kinds that can pre-compose a session.
+ * @param config - the validated plugin config.
+ * @returns the startup the runner will resolve a target from.
+ */
+export function resolveStartupConfig(config: { readonly startup: StartupConfigRow }): TuiStartup {
+  const row = config.startup
+  // The CLI validated --theme at parse time; the loose config schema falls
+  // back to dark for anything unexpected.
+  const theme = row.theme === undefined ? undefined : parseThemeName(row.theme)
+  const input = {
+    ...(theme === undefined ? {} : { theme }),
+    ...(row.prompt === undefined ? {} : { prompt: row.prompt }),
+    ...(row.images === undefined ? {} : { images: [...row.images] }),
+  }
+  if (row.kind === 'resume' && row.sessionId !== undefined) {
+    return { kind: 'resume', sessionId: row.sessionId, ...input }
+  }
+  if (row.kind === 'latest') return { kind: 'latest', ...input }
+  const mode = row.mode === undefined ? {} : { mode: row.mode }
+  if (row.kind === 'named' && row.sessionId !== undefined) {
+    return { kind: 'named', sessionId: row.sessionId, ...mode, ...input }
+  }
+  return { kind: 'fresh', ...mode, ...input }
+}

package/src/runner/submissions.ts

@@ -0,0 +1,157 @@
+/** Submission vocabulary and the startup input gate for the terminal runner.
+ *
+ * Pure over the handles they are given: the queue mutations and the session
+ * guard are decisions the runner applies, and the gate only orders deliveries,
+ * so every branch is testable without composing an Agent.
+ *
+ * @module @deepseek-ai/dsh-code/submissions
+ */
+
+import { createUserMessage, MessageId, type ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { Agent, AgentStatus, Inbox } from '@deepseek-ai/dsh-agent'
+import type { UserMessage } from '@deepseek-ai/dsh-session'
+import type { QueueMutation } from '../ui/ui-contract.ts'
+
+/** One composer submission waiting behind the startup delivery. */
+export interface QueuedSubmission {
+  readonly text: string
+  /** `steer` inserts into the running turn; `followup` waits for the next one. */
+  readonly mode: 'followup' | 'steer'
+  readonly images: readonly ContentBlock[]
+}
+
+/** What one requested queue mutation did; the runner maps it to one notice. */
+export type QueueMutationOutcome =
+  | 'removed'
+  | 'edited'
+  | 'steered'
+  | 'unavailable'
+  | 'empty'
+  | 'steerUnavailable'
+
+/**
+ * Replace one queued message's text while keeping its attachments. A queue
+ * edit rewrites what the user typed, not what they attached: image and file
+ * blocks ride through in delivery order (text first, then attachments, the
+ * shape {@link deliverLine} submits). Dropping them here would silently strip
+ * an attachment the user already confirmed, so this is the edit's single
+ * definition and the panel's read-only marker only mirrors it.
+ */
+export function queueEditContent(content: readonly ContentBlock[], text: string): ContentBlock[] {
+  const attachments = content.filter(block => block.type !== 'text')
+  return [{ type: 'text', text }, ...attachments]
+}
+
+/**
+ * Apply one terminal queue mutation to the live inbox. The decision and the
+ * inbox change are pure over the supplied handles so every branch is testable
+ * without an agent; steering itself is injected because it wakes the driver
+ * rather than mutating the inbox. The durable inbox splices remain the UI's
+ * single source of truth — this helper never reports a state the inbox did not
+ * actually reach.
+ * @param inbox - the live agent inbox (pending lists plus its mutators).
+ * @param status - the agent's lifecycle status; steering needs `running`.
+ * @param messageId - identity of the queued message to mutate.
+ * @param action - the requested mutation.
+ * @param steer - submits the removed message as next-step steering.
+ * @returns the outcome the caller reports.
+ */
+export function applyQueueMutation(
+  inbox: Pick<Inbox, 'nextTurn' | 'append' | 'remove' | 'replace'>,
+  status: AgentStatus,
+  messageId: string,
+  action: QueueMutation,
+  steer: (message: UserMessage) => void,
+): QueueMutationOutcome {
+  const id = MessageId(messageId)
+  const message = inbox.nextTurn.find(candidate => candidate.id === id)
+  if (message === undefined) return 'unavailable'
+  switch (action.kind) {
+    case 'remove':
+      return inbox.remove(id) ? 'removed' : 'unavailable'
+    case 'edit':
+      if (action.text.trim() === '') return 'empty'
+      inbox.replace(id, createUserMessage({
+        content: queueEditContent(message.content, action.text),
+        source: message.source,
+      }))
+      return 'edited'
+    case 'steer':
+      if (status !== 'running') return 'steerUnavailable'
+      // Steer promotes the message out of next-turn, so a failing submit must
+      // put it back: the row the user was looking at never just disappears.
+      if (!inbox.remove(id)) return 'unavailable'
+      try {
+        steer(message)
+      } catch (error: unknown) {
+        inbox.append('next-turn', message)
+        throw error
+      }
+      return 'steered'
+  }
+}
+
+/**
+ * Cancel the active turn while keeping the next-turn queue, then wake the
+ * driver again so the preserved messages actually run. `cancel` clears
+ * pending work by default and never wakes the driver on its own, so the queue
+ * is captured first and re-submitted afterwards: a waking submission latches
+ * the wake while the aborted activity converges to idle, which is what turns
+ * "preserved" into "sent next" instead of "parked forever". Next-step
+ * steering is deliberately dropped — it belonged to the cancelled turn.
+ * @param agent - the live agent handle.
+ * @returns how many queued messages were preserved across the abort.
+ */
+export function cancelPreservingQueue(agent: Pick<Agent, 'inbox' | 'cancel' | 'followup'>): number {
+  const queued = [...agent.inbox.nextTurn]
+  agent.cancel({ kind: 'user' })
+  for (const message of queued) agent.followup(message)
+  return queued.length
+}
+
+/**
+ * Whether a tagged submission still belongs to the active session. Attachment
+ * prepares resolve on the microtask timeline, while a queued session switch
+ * remounts the app asynchronously — the composing instance's unmount cleanup
+ * runs too late to abort, so the delivery itself carries the composing
+ * session's full id and the runner drops it here when the world moved on.
+ * An untagged (synchronous) or pending-session ('') submission always passes.
+ */
+export function submissionBelongsToSession(origin: string | undefined, activeSessionId: string | undefined): boolean {
+  return origin === undefined || origin === '' || origin === activeSessionId
+}
+
+/**
+ * Order-preserving gate for composer input while the startup prompt/images
+ * are still preparing. Anything submitted before the startup delivery settles
+ * queues and flushes afterwards in submit order, so the initial request can
+ * never be overtaken by typing that raced a slow image preparation. The flush
+ * also runs when the startup delivery fails: user input is never stranded.
+ */
+export class StartupInputGate {
+  private readonly queued: QueuedSubmission[] = []
+  private pending = false
+  constructor(private readonly deliver: (submission: QueuedSubmission) => void) {}
+
+  /** Submit one line: delivered now while idle, queued behind the startup delivery otherwise. */
+  submit(submission: QueuedSubmission): void {
+    if (this.pending) this.queued.push(submission)
+    else this.deliver(submission)
+  }
+
+  /**
+   * Run the startup delivery — the callback receives the direct-delivery sink
+   * for the startup prompt itself — then flush everything that queued behind
+   * it, in order, even when the callback rejects.
+   */
+  async run(startup: (deliver: (submission: QueuedSubmission) => void) => Promise<void>): Promise<void> {
+    this.pending = true
+    try {
+      await startup(submission => this.deliver(submission))
+    } finally {
+      this.pending = false
+      const queued = this.queued.splice(0)
+      for (const submission of queued) this.deliver(submission)
+    }
+  }
+}

package/src/session/attach.ts

@@ -0,0 +1,87 @@
+/**
+ * One live attachment to a subagent conversation: a transcript store seeded
+ * from the child's durable log and then fed by the process-local event and
+ * stream buses in real time. The parent's own store is never touched.
+ *
+ * @module @deepseek-ai/dsh-code/session/attach
+ */
+
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { createTranscriptStore, type TranscriptStore } from './store.ts'
+
+/** The bus surfaces one attachment reads; the runner wires these to ctx. */
+export interface SubagentAttachmentServices {
+  /** Seed: the child's full durable event log, oldest first. */
+  load(id: string, signal?: AbortSignal): Promise<readonly SessionEvent[]>
+  /** Durable events for exactly this child session, live. */
+  subscribeEvents(id: string, onEvent: (event: SessionEvent) => void): () => void
+  /** Token stream frames for exactly this child agent, live. */
+  subscribeStream(id: string, onFrame: (frame: Parameters<TranscriptStore['applyStreamFrame']>[0]) => void): () => void
+}
+
+/** A live child view handed to the App while attached. */
+export interface SubagentAttachment {
+  readonly id: string
+  readonly label: string
+  readonly store: TranscriptStore
+  /** Whether the durable seed has landed (frames are held back until then). */
+  seeded(): boolean
+  /** Drop the bus subscriptions; the store freezes at its last state. */
+  dispose(): void
+}
+
+/** An inert empty store keeps the App's external-store hook unconditional. */
+export const EMPTY_ATTACH_STORE: TranscriptStore = createTranscriptStore()
+
+/**
+ * Attach to one subagent conversation.
+ *
+ * Ordering contract: durable events carry a per-session sequence, so the seed
+ * sets a watermark and live events at or below it are dropped as duplicates;
+ * stream frames are held until the seed lands so a frame whose settlement
+ * already arrived cannot resurrect a stale tail.
+ */
+export function createSubagentAttachment(services: SubagentAttachmentServices, id: string, label: string): SubagentAttachment {
+  const store = createTranscriptStore()
+  const controller = new AbortController()
+  let watermark = -1
+  let seeded = false
+  const pending: SessionEvent[] = []
+  const applyDurable = (event: SessionEvent): void => {
+    const seq = Number(event.seq ?? -1)
+    if (seq >= 0 && seq <= watermark) return
+    if (seq >= 0) watermark = seq
+    store.apply(event)
+  }
+  const offEvents = services.subscribeEvents(id, event => {
+    if (!seeded) pending.push(event)
+    else applyDurable(event)
+  })
+  const offFrames = services.subscribeStream(id, frame => {
+    if (seeded) store.applyStreamFrame(frame)
+  })
+  services.load(id, controller.signal).then(events => {
+    if (controller.signal.aborted) return
+    for (const event of events) applyDurable(event)
+    seeded = true
+    for (const event of pending) applyDurable(event)
+    pending.length = 0
+  }, () => {
+    // The live buses still feed the view; a failed seed leaves the watermark
+    // unset so nothing durable is skipped, and the store shows what arrives.
+    seeded = true
+    for (const event of pending) applyDurable(event)
+    pending.length = 0
+  })
+  return {
+    id,
+    label,
+    store,
+    seeded: () => seeded,
+    dispose: () => {
+      controller.abort()
+      offEvents()
+      offFrames()
+    },
+  }
+}

package/src/{session-directory.ts → session/session-directory.ts}

@@ -3,7 +3,7 @@
 import { basename, dirname, resolve } from 'node:path'
 import { realpathSync } from 'node:fs'
 import { SESSION_FORMAT_VERSION, SessionId, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session'
-import { t } from './i18n.ts'
+import { t } from '../i18n.ts'
 
 export interface SessionRecord {
   readonly header: SessionHeader

package/src/{store.ts → session/store.ts}

@@ -39,7 +39,7 @@ import {
   replayProjectEvent,
   snapshotReplayView,
   type TranscriptView,
-} from './render/projection.ts'
+} from '../render/projection.ts'
 
 /** Render frame budget: the notification cadence's upper bound. */
 const NOTIFY_FRAME_MS = 16

package/src/{subagents.ts → session/subagents.ts}

@@ -18,7 +18,7 @@
  * microtask notify chained SyncLane rerenders past React's nested update
  * limit; a bare macrotask merge repaints a whole turn's bursts at once).
  *
- * @module @deepseek-ai/dsh-code/subagents
+ * @module @deepseek-ai/dsh-code/session/subagents
  */
 
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
@@ -227,3 +227,14 @@ export function createSubagentFeed(): SubagentFeedView & {
     },
   }
 }
+
+/**
+ * Root-log catalog facts a resumed session must replay into the subagent
+ * feed: constructor seeds never fire on the live bus, so without this the
+ * children of a resumed session vanish behind a restart. The empty-child
+ * placeholder row (childId '') is a placeholder, not a child, and stays out.
+ */
+export function subagentCatalogSeed(events: readonly SessionEvent[]): readonly SessionEvent<'subagent/catalog'>[] {
+  return events.filter((event): event is SessionEvent<'subagent/catalog'> =>
+    event.type === 'subagent/catalog' && event.data.childId !== '')
+}