dsh-code 1.2.0 → 1.4.0

package/lib/types/runner/input-history.d.ts

@@ -0,0 +1,31 @@
+/** Global input recall: the appended prompts and their durable JSONL file.
+ *
+ * One JSONL file under the DSH home. A missing file means an empty history and
+ * unreadable or corrupt content degrades to the valid lines it could parse,
+ * silently — recall is a convenience surface, never a gate.
+ *
+ * @module @deepseek-ai/dsh-code/input-history
+ */
+/** Live recall state plus its serialized durable writes. */
+export interface InputHistoryStore {
+    /** The recall list, newest last; read live by the composer. */
+    readonly entries: () => readonly string[];
+    /** Append one submitted line and persist it; '' is ignored. */
+    readonly record: (text: string) => void;
+    /** Await the pending writes (the quit flush). */
+    readonly flush: () => Promise<void>;
+}
+/**
+ * Load the recall history and return its live store.
+ *
+ * Serialized history writes: each submission appends one JSON line at the end
+ * of the file, so concurrent terminals add entries after each other instead of
+ * overwriting snapshots they read at their own boot. A multi-line draft still
+ * occupies one physical line (JSON escapes the newline), and a regular-length
+ * line reaches the disk as one positioned write; an oversized paste may
+ * interleave mid-line, which the next parse simply drops.
+ *
+ * @param path - absolute path of the JSONL recall file.
+ * @param onFailure - receives the write failure message for a bounded notice.
+ */
+export declare function createInputHistory(path: string, onFailure: (message: string) => void): InputHistoryStore;

package/lib/types/runner/mode-cycle.d.ts

@@ -0,0 +1,44 @@
+/** Shift+Tab mode-cycle stations for the terminal runner.
+ *
+ * Pure decision over the preset table and the committed plan fold: the runner
+ * applies the returned station, so the whole cycle is testable without a
+ * session.
+ *
+ * @module @deepseek-ai/dsh-code/mode-cycle
+ */
+/** One Shift+Tab station decision for the mode cycle. */
+export type ModeCycleDecision = {
+    readonly kind: 'permission';
+    readonly preset: string;
+} | {
+    readonly kind: 'plan-on';
+} | {
+    readonly kind: 'plan-off';
+    readonly preset: string;
+};
+/**
+ * Decide the next Shift+Tab station. The cycle keeps the preset table's
+ * own order (most restrictive first) and inserts ONE plan station between
+ * the most restrictive preset and the wrap target: with the shipped three
+ * presets the user sees workspace-write → danger-full-access → read-only
+ * → plan → workspace-write. Plan IS the most restrictive preset plus the
+ * plan prompt layer — entering it switches nothing (the cycle is already
+ * parked on read-only), and leaving it lands on the next preset after the
+ * most restrictive one. Without the /plan command the cycle is exactly the
+ * preset table.
+ *
+ * `planIntent` covers the committed fold's commit lag: upstream queues a
+ * plan switch during an open turn (and the command pipeline is async even
+ * idle), so the durable plan/mode event lands AFTER the press that chose
+ * it. While an intent from an earlier press is in flight it — not the
+ * stale committed fold — decides the station, so repeated presses advance
+ * the cycle instead of re-issuing the same plan transition (the stuck
+ * plan-on/plan-off toggle). Undefined falls back to the committed fold.
+ */
+export declare function planCycleDecision(input: {
+    readonly names: readonly string[];
+    readonly current: string;
+    readonly inPlan: boolean;
+    readonly planAvailable: boolean;
+    readonly planIntent?: boolean;
+}): ModeCycleDecision | undefined;

package/lib/types/runner/preferences.d.ts

@@ -0,0 +1,40 @@
+/** User-level preference files under the DSH home.
+ *
+ * The statusline, theme, language, and animations customizations each live in
+ * one small JSON file. They share exactly two policies: a missing file is the
+ * default and stays silent while a corrupt one degrades to the default with a
+ * surfaced warning (a user-authored customization must never fail silently),
+ * and every save goes through the serialized crash-atomic writer.
+ *
+ * @module @deepseek-ai/dsh-code/preferences
+ */
+import { type UserSettingsPersistence } from '../settings-file.ts';
+/** Absolute path of one preference file under the DSH home. */
+export declare function preferencePath(fileName: string): string;
+/** Outcome of reading one preference file. */
+export interface PreferenceRead<T> {
+    /** Parsed value; undefined when the file is missing or corrupt (keep the default). */
+    readonly value?: T;
+    /** Corruption message to surface; undefined for a missing or clean file. */
+    readonly warning?: string;
+}
+/**
+ * Read one field of a preference file. A missing file is silence — the default
+ * stands and nothing is reported — while unreadable JSON or a non-object
+ * document both warn and keep the default.
+ * @param path - absolute path of the preference file.
+ * @param field - the JSON field the file carries.
+ * @param parse - narrows the raw field to the usable value.
+ * @returns the parsed value and/or the warning to surface.
+ */
+export declare function readPreference<T>(path: string, field: string, parse: (raw: unknown) => T): PreferenceRead<T>;
+/**
+ * Persist one preference field through the serialized crash-atomic writer.
+ * A failed write is reported through `onFailure` instead of rejecting.
+ * @param persistence - the shared user-settings writer.
+ * @param path - absolute path of the preference file.
+ * @param field - the JSON field the file carries.
+ * @param value - the value to store under `field`.
+ * @param onFailure - receives the failure message for a bounded notice.
+ */
+export declare function savePreference(persistence: UserSettingsPersistence, path: string, field: string, value: unknown, onFailure: (message: string) => void): void;

package/lib/types/runner/quit.d.ts

@@ -0,0 +1,27 @@
+/** Ordered terminal quit cleanup.
+ *
+ * Pure sequencing: every step rejection is contained and the exit request is
+ * always reached exactly once, so a failing flush never strands the process.
+ *
+ * @module @deepseek-ai/dsh-code/quit
+ */
+/** One ordered step of the terminal quit cleanup. */
+export interface QuitCleanupStep {
+    /** Step label used in diagnostics and tests. */
+    readonly name: string;
+    /** The step's async work; a rejection is contained by the sequence. */
+    readonly run: () => Promise<void>;
+}
+/**
+ * Run the ordered quit cleanup, then request exit. Every step rejection is
+ * contained (reported through `onError`) so a failed flush or dispose never
+ * skips the remaining cleanup; the exit request is always reached exactly
+ * once.
+ * @param steps - the cleanup steps in dependency order (settle the visible
+ * session, await the final in-flight composition, await durable recall).
+ * @param exit - the terminal exit request (code 0).
+ * @param onError - optional failure sink; called once per failing step and
+ * itself contained, so a throwing sink cannot abort the sequence.
+ * @returns the names of the steps that started, in order (for tests).
+ */
+export declare function runQuitSequence(steps: readonly QuitCleanupStep[], exit: (code: number) => void, onError?: (name: string, error: unknown) => void): Promise<readonly string[]>;

package/lib/types/runner/search-rows.d.ts

@@ -0,0 +1,38 @@
+/** Cross-session search rows for the /search panel.
+ *
+ * Owns the panel row shape and the pure mapping from a session-query hit, so
+ * the row contract does not live inside the panel component that renders it
+ * and the runner can build rows without importing the panel module.
+ *
+ * @module @deepseek-ai/dsh-code/search-rows
+ */
+import type { SessionHeader } from '@deepseek-ai/dsh-session';
+/** One cross-session full-text search hit mapped from the session-query engine. */
+export interface SearchRow {
+    /** Session id (Enter resumes it through the switch machinery). */
+    readonly id: string;
+    /** Display label: session title or the short id form. */
+    readonly label: string;
+    /** Secondary facts line (workspace · preset markers). */
+    readonly detail: string;
+    /** Bounded plain-text excerpt around the strongest match. */
+    readonly snippet: string;
+    /** Match timestamp (relative labels derive from it). */
+    readonly updatedAt: number;
+    /** Whether the hit is a delegated subagent conversation (not resumable). */
+    readonly subagent: boolean;
+    /** Whether Enter may switch into it. */
+    readonly resumable: boolean;
+}
+/**
+ * Map one cross-session full-text hit onto the /search panel's row (pure).
+ * Labels fall back to the short id form — the engine's hit carries the
+ * strongest matching event, not the title observation.
+ */
+export declare function searchHitToRow(hit: {
+    header: SessionHeader;
+    bestMatch: {
+        snippet: string;
+        time: number;
+    };
+}): SearchRow;

package/lib/types/runner/session-io.d.ts

@@ -0,0 +1,46 @@
+/** 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 { type SessionDeletionPersistence, type SessionDirectoryOptions, type SessionQueryService, type SessionRow } from '../session/session-directory.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>;
+}
+/**
+ * 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 declare function createSessionIo(services: SessionIoServices): SessionIo;

package/lib/types/runner/session-target.d.ts

@@ -0,0 +1,42 @@
+/** 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 type { SessionId, SessionEvent } from '@deepseek-ai/dsh-session';
+import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence';
+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 declare function exportSessionIdSuffix(id: string): string;
+/**
+ * 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 declare function resolveTarget(startup: TuiStartup, persistence: SessionPersistence | undefined, cwd: string): Promise<Target>;

package/lib/types/runner/startup-config.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 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 declare function resolveStartupConfig(config: {
+    readonly startup: StartupConfigRow;
+}): TuiStartup;

package/lib/types/runner/submissions.d.ts

@@ -0,0 +1,87 @@
+/** 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 { 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 declare function queueEditContent(content: readonly ContentBlock[], text: string): ContentBlock[];
+/**
+ * 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 declare function applyQueueMutation(inbox: Pick<Inbox, 'nextTurn' | 'append' | 'remove' | 'replace'>, status: AgentStatus, messageId: string, action: QueueMutation, steer: (message: UserMessage) => void): QueueMutationOutcome;
+/**
+ * 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 declare function cancelPreservingQueue(agent: Pick<Agent, 'inbox' | 'cancel' | 'followup'>): number;
+/**
+ * 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 declare function submissionBelongsToSession(origin: string | undefined, activeSessionId: string | undefined): boolean;
+/**
+ * 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 declare class StartupInputGate {
+    private readonly deliver;
+    private readonly queued;
+    private pending;
+    constructor(deliver: (submission: QueuedSubmission) => void);
+    /** Submit one line: delivered now while idle, queued behind the startup delivery otherwise. */
+    submit(submission: QueuedSubmission): void;
+    /**
+     * 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.
+     */
+    run(startup: (deliver: (submission: QueuedSubmission) => void) => Promise<void>): Promise<void>;
+}

package/lib/types/session/attach.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 { 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 declare const EMPTY_ATTACH_STORE: TranscriptStore;
+/**
+ * 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 declare function createSubagentAttachment(services: SubagentAttachmentServices, id: string, label: string): SubagentAttachment;

package/lib/types/{history.d.ts → session/history.d.ts}

@@ -78,6 +78,16 @@ export interface RecallState {
 }
 /** Fresh navigation state over one recall space. */
 export declare function beginRecall(entries: readonly string[], draft: string): RecallState;
+/**
+ * Join a panel-recalled entry onto the draft already in the composer: the
+ * draft is extended, never replaced, so picking a history row cannot discard
+ * work in progress. An empty draft takes the entry as-is; otherwise the entry
+ * starts on its own line unless the draft already ends one.
+ * @param draft - the composer text before the recall.
+ * @param entry - the sanitized text of the accepted row.
+ * @returns the text to place in the composer.
+ */
+export declare function appendRecall(draft: string, entry: string): string;
 /** The outcome of one recall step. */
 export interface RecallStep {
     state: RecallState;

package/lib/types/{session-directory.d.ts → session/session-directory.d.ts}

@@ -1,10 +1,26 @@
 /** Lightweight session-directory projection for the /resume picker. */
-import { type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session';
+import { SessionId, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session';
 export interface SessionRecord {
     readonly header: SessionHeader;
     readonly live: boolean;
     readonly persisted: boolean;
 }
+/** Minimal write handle retained while a planned deletion touches artifacts. */
+export interface SessionDeletionLease {
+    close(): Promise<void>;
+}
+/** Public persistence operation used to acquire the backend's write lease. */
+export interface SessionDeletionPersistence {
+    open(id: SessionId, access: 'write'): Promise<SessionDeletionLease>;
+}
+/**
+ * Acquire every subtree member's cross-process write lease before deleting
+ * any artifact. A partial acquisition is rolled back, so callers either hold
+ * the whole deletion boundary or touch nothing.
+ */
+export declare function acquireSessionDeletionLeases(persistence: SessionDeletionPersistence, ids: readonly string[]): Promise<readonly SessionDeletionLease[]>;
+/** Release deletion leases in reverse acquisition order. */
+export declare function releaseSessionDeletionLeases(leases: readonly SessionDeletionLease[]): Promise<void>;
 export interface TitleObservationResult {
     readonly sessionId: string;
     readonly status: 'fulfilled' | 'rejected';
@@ -78,6 +94,12 @@ export declare function isSubagentSession(header: SessionHeader): boolean;
  * @throws when nothing matches or the prefix is ambiguous.
  */
 export declare function matchSessionId(headers: readonly SessionHeader[], wanted: string): SessionHeader;
+/**
+ * Unique picker-row match by exact id, unique prefix, or unique suffix.
+ * The resume list shows `id.slice(-12)`, so `/delete` arguments are often
+ * that tail rather than a leading prefix.
+ */
+export declare function matchSessionRow(rows: readonly SessionRow[], wanted: string): SessionRow;
 /** The newest persisted ROOT session pinned to this cwd, or undefined. */
 export declare function newestRootForCwd(headers: readonly SessionHeader[], cwd: string): SessionHeader | undefined;
 /**
@@ -90,6 +112,8 @@ export declare function newestRootForCwd(headers: readonly SessionHeader[], cwd:
  * @param updated - per-session last-activity timestamps, when resolved.
  */
 export declare function projectSessionRows(records: readonly SessionRecord[], options: SessionDirectoryOptions, updated?: ReadonlyMap<string, number>): SessionRow[];
+/** True when the picker query hits id, path, preset, or the displayed title. */
+export declare function sessionRowMatchesQuery(row: Pick<SessionRow, 'id' | 'cwd' | 'workspace' | 'preset' | 'title'>, query: string): boolean;
 /** Merge page-local title observations without disturbing directory order. */
 export declare function mergeSessionTitles(rows: readonly SessionRow[], observations: readonly TitleObservationResult[]): SessionRow[];
 /**

package/lib/types/{session-switch.d.ts → session/session-switch.d.ts}

@@ -8,10 +8,18 @@ export declare class SessionSwitchQueue<T> {
     private readonly failed;
     private pending;
     private pumping;
+    private running;
     constructor(execute: (value: T) => Promise<void>, failed: (error: unknown) => void);
     /** Queue a request; a later request replaces any request still waiting. */
     request(activity: IdleActivity, value: T): 'queued' | 'started';
     /** Cancel only work that has not begun activation. */
     cancel(): boolean;
+    /**
+     * Whether a queued change is being activated right now. Between the idle
+     * wait and the handoff the old session is still installed, so a submission
+     * made in that window would start a turn the handoff then discards; callers
+     * use this to refuse one instead of losing it.
+     */
+    get activating(): boolean;
     private pump;
 }

package/lib/types/{store.d.ts → session/store.d.ts}

@@ -31,7 +31,7 @@
  */
 import type { AssistantStreamFrame } from '@deepseek-ai/dsh-agent';
 import type { SessionEvent } from '@deepseek-ai/dsh-session';
-import { type TranscriptView } from './render/projection.ts';
+import { type TranscriptView } from '../render/projection.ts';
 /** The externally readable, event-fed transcript store for one session. */
 export interface TranscriptStore {
     /** The current view; the same object identity until an event changes it. */

package/lib/types/{subagents.d.ts → session/subagents.d.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';
 /** Hard row cap: overflow evicts the oldest settled row; a fully busy feed waits. */
@@ -68,3 +68,10 @@ export declare function createSubagentFeed(): SubagentFeedView & {
     apply(sessionId: string, event: SessionEvent): void;
     reset(): void;
 };
+/**
+ * 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 declare function subagentCatalogSeed(events: readonly SessionEvent[]): readonly SessionEvent<'subagent/catalog'>[];

package/lib/types/settings-file.d.ts

@@ -39,3 +39,13 @@ export interface UserSettingsPersistence {
  * @returns the persistence handle.
  */
 export declare function createUserSettingsPersistence(): UserSettingsPersistence;
+/**
+ * Read one user-level settings file as a plain object. The callers all treat a
+ * missing file as "unset" and a corrupt one as "warn and fall back", so this
+ * helper owns the one distinction they share: readable JSON that is not an
+ * object is corruption, not an absent preference, and must not surface as a
+ * cryptic property access on `null`.
+ * @param path - absolute path of the settings file.
+ * @returns the parsed object; the caller narrows each field itself.
+ */
+export declare function readSettingsObject(path: string): Record<string, unknown>;

package/lib/types/{panel-accent.d.ts → ui/panel-accent.d.ts}

@@ -10,7 +10,7 @@
  *
  * @module @deepseek-ai/dsh-tui/panel-accent
  */
-import { type RgbTriple } from './theme.ts';
+import { type RgbTriple } from '../theme.ts';
 /** One panel's resolved accent pair (border and title share the ring color in prismatic). */
 export interface PanelAccent {
     readonly border: RgbTriple;

package/lib/types/ui/panel-gap.d.ts

@@ -0,0 +1,6 @@
+/** Shared optional spacer row used by bounded panel layouts. */
+import { type ReactElement } from 'react';
+/** Codex-style panel rhythm that still participates in the row budget. */
+export declare function PanelGap({ visible }: {
+    visible: boolean;
+}): ReactElement | undefined;

package/lib/types/ui/query-editor.d.ts

@@ -0,0 +1,10 @@
+/** Shared one-line query editor for keyboard-owned filtering panels. */
+/**
+ * Apply one keystroke to a panel search query. IME commits arrive as one
+ * multi-character chunk, so the whole printable run is appended; paste
+ * markers are stripped and control-laden chunks are ignored.
+ */
+export declare function editQuery(query: string, input: string, key: {
+    backspace?: boolean;
+    delete?: boolean;
+}): string | undefined;

package/lib/types/ui/styled-rows.d.ts

@@ -0,0 +1,8 @@
+/** Ink renderer for width-safe styled terminal rows. */
+import { type ReactElement } from 'react';
+import type { StyledLine } from '../render/lines.ts';
+/** Render width-safe rows; every child is exactly one terminal row. */
+export declare function StyledRows({ lines }: {
+    lines: readonly StyledLine[];
+}): ReactElement;
+/** File-oriented, color-coded unified diff viewport. */

package/lib/types/{terminal-title.d.ts → ui/terminal-title.d.ts}

@@ -10,7 +10,7 @@
  * an empty OSC payload and the terminal falls back to its own default; the
  * previously set title is not portable to read back and is never restored.
  *
- * @module @deepseek-ai/dsh-code/terminal-title
+ * @module @deepseek-ai/dsh-code/ui/terminal-title
  */
 /** Tab label before a session carries a name. */
 export declare const DEFAULT_TERMINAL_TITLE = "deepseek";

package/lib/types/ui/ui-contract.d.ts

@@ -0,0 +1,12 @@
+/** Shared terminal UI contracts used by the runner, App, and composer. */
+/** Visual priority for one bounded local notice. */
+export type NoticeTone = 'info' | 'warning' | 'error';
+/** One mutation the terminal may request for a pending next-turn inbox item. */
+export type QueueMutation = {
+    readonly kind: 'remove';
+} | {
+    readonly kind: 'edit';
+    readonly text: string;
+} | {
+    readonly kind: 'steer';
+};

package/lib/types/ui/use-frames.d.ts

@@ -0,0 +1,6 @@
+/** Wall-clock animation frame hook shared by independent terminal leaves. */
+/**
+ * Derive ticks from elapsed wall time so a stretched interval skips ahead
+ * instead of slowing the animation under a busy event loop or remote shell.
+ */
+export declare function useFrames(intervalMs: number, active?: boolean): number;