@xmoon76/dsh-pi-tui 0.4.8 → 0.5.0

package/dist/extensions.mjs

@@ -1,2 +1,2 @@
-import { B as PI_TUI_EXTENSIONS_SERVICE, H as describeKey, L as apply, R as inject, V as API_VERSION, z as name } from "./src-R8SVGB-L.mjs";
+import { a as API_VERSION, i as PI_TUI_EXTENSIONS_SERVICE, n as inject, o as describeKey, r as name, t as apply } from "./extensions-Dg1qhjUi.mjs";
 export { API_VERSION, PI_TUI_EXTENSIONS_SERVICE, apply, describeKey, inject, name };

package/dist/index.d.mts

@@ -1,89 +1,9 @@
 import { H as TuiAction } from "./public-types-YbB5Rhku.mjs";
-import z from "@deepseek-ai/schemastery";
-import { Agent, ModelSelectionRef } from "@deepseek-ai/dsh-agent";
-import { ContentBlock } from "@deepseek-ai/dsh-llm";
 import { SessionId } from "@deepseek-ai/dsh-session";
+import { ContentBlock } from "@deepseek-ai/dsh-llm";
 import { Context, Volatile } from "@deepseek-ai/cordis";
-//#region src/image/admission.d.ts
-/** Structural subset of `ImageAttachmentRef`. */
-interface ImageAttachmentRefLike {
-  readonly attachmentId: string;
-  readonly mediaType: ImageMediaType;
-  readonly bytes: number;
-  readonly width: number;
-  readonly height: number;
-  readonly name?: string;
-}
-//#endregion
-//#region src/image/types.d.ts
-/**
- * Image draft vocabulary for the TUI input pipeline (plan M1).
- *
- * The draft layer is TUI-owned: it stages clipboard/file bytes until a
- * submission turns them into durable `ImageAttachmentRef`s through the dsh
- * attachment service. Nothing in this module persists; the durable boundary
- * is the harness's `ctx.attachments.saveImages()`.
- *
- * The media-type union mirrors `@deepseek-ai/dsh-attachment`'s
- * `ImageMediaType` structurally, so drafts flow into the harness without a
- * runtime dependency on the attachment package (AGENTS.md decision 7:
- * structural typing for dsh services).
- * @module @xmoon76/dsh-pi-tui/image/types
- */
-/** Raster media types accepted by the TUI image intake. */
-type ImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
-/** Per-TUI draft image identity; only meaningful inside one TUI run. */
-type DraftImageId = number;
-/** Where a staged image's bytes came from. */
-type DraftImageSource = {
-  readonly type: 'clipboard';
-} | {
-  readonly type: 'path';
-  readonly path: string;
-}
-/** The image was pulled back from a queued message: its bytes are ALREADY
- * durable with the harness (the recalled ref) — the draft holds no local
- * copy and re-submitting reuses the ref instead of re-uploading. */
-| {
-  readonly type: 'recalled';
-};
-/**
- * One image staged in the editor draft. The draft holds the raw bytes so
- * clipboard and path entries share one shape and a submit never depends on
- * the source file still existing (plan §5.1). A RECALLED draft (pulled
- * back from the queue) instead carries the durable `ImageAttachmentRef`
- * and NO local bytes — the bytes stay in harness storage and re-submitting
- * reuses the ref.
- */
-interface DraftImage {
-  /** Per-TUI draft identity (the `#N` of the placeholder). */
-  readonly id: DraftImageId;
-  readonly kind: 'image';
-  readonly source: DraftImageSource;
-  /** Exact encoded bytes, held only for the draft lifetime. Empty for a
-   * recalled draft (its bytes live in harness storage). */
-  readonly bytes: Uint8Array;
-  readonly mediaType: ImageMediaType;
-  /** Intrinsic encoded width in pixels. */
-  readonly width: number;
-  /** Intrinsic encoded height in pixels. */
-  readonly height: number;
-  /** Exact encoded byte length (`bytes.byteLength` for local drafts; the
-   * durable ref's recorded `bytes` for recalled drafts). */
-  readonly byteLength: number;
-  /** Optional display name (basename for path sources), never a path. */
-  readonly name?: string;
-  /** The canonical editor placeholder text for this draft. */
-  readonly placeholder: string;
-  /** The durable ref this draft reuses on submit; present ONLY for
-   * recalled drafts (already-durable images are never re-uploaded). */
-  readonly recalledRef?: ImageAttachmentRefLike;
-}
-/** The store surface the placeholder expansion needs (structural). */
-interface DraftImageStoreLike {
-  values(): readonly DraftImage[];
-}
-//#endregion
+import { Agent, ModelSelectionRef } from "@deepseek-ai/dsh-agent";
+import z from "@deepseek-ai/schemastery";
 //#region src/display-preset.d.ts
 /**
  * Canonical transcript display presets and their layered disclosure policy.
@@ -160,36 +80,10 @@ interface HumanSkillCatalog {
   readonly complete: boolean;
 }
 //#endregion
-//#region src/tui-app.d.ts
-/** The compaction lifecycle phase the working row advertises: idle (no
- * compaction), summarizing (compaction/start seen, the summary is being
- * generated), or applying (the summary landed, the compacted surface is
- * being committed). Derived by the runner from compaction/start →
- * compaction/summary → compaction/end (foldCompactionEvent). */
-type CompactionPhase = 'idle' | 'summarizing' | 'applying';
-/**
- * The WEB composer submit gestures (DSH `ComposerSubmitGesture`): plain
- * Enter, or the Cmd/Ctrl-accelerated chord. The busy-Enter policy resolves
- * each to a delivery mode — plain Enter to the preferred mode, the
- * accelerated chord to its OPPOSITE — so the chord is never a fixed mode.
- */
-type ComposerSubmitGesture = 'enter' | 'accelerated';
-/** One semantic queued pending-input row for the queue pane. */
-interface QueueItem {
-  /** The pending message id (agent inbox identity), or a local request id. */
-  id: string;
-  /** The message text, single-line display form. */
-  text: string;
-  /** next-turn followup vs next-step steer. */
-  mode: 'followup' | 'steer';
-  /** The correlation identity (authoritative rpc id or local request id). */
-  rpcId?: string;
-  /** A client-local echo not yet backed by an authoritative occurrence. */
-  local?: boolean;
-}
-//#endregion
 //#region src/surface-catalog.d.ts
-/** Minimal live-agent face consumed by the effective catalog readers. */
+/** Minimal live-agent face consumed by the effective catalog readers — and by
+ * {@link ResolveInitialCatalogOptions}, so the published option type stays
+ * structural instead of inlining the Host Agent. */
 interface SurfaceCatalogAgent {
   readonly ctx: object;
   readonly session: {
@@ -256,42 +150,16 @@ interface SurfaceCommandsService {
 interface SurfaceCatalogContext {
   get(name: 'commands'): SurfaceCommandsService | undefined;
 }
+interface InitialCatalogResolution {
+  /** The resume prefetch snapshot to install at mount. */
+  readonly snapshot?: SurfaceCatalogSnapshot;
+  /** The cold standing-scope human skill catalog (deferred start). */
+  readonly skills?: HumanSkillCatalog;
+  /** A user-facing notice when the prefetch/standing read degraded. */
+  readonly notice?: string;
+}
 //#endregion
-//#region src/commands.d.ts
-/**
- * The effective mode ONE submission resolved at the submit boundary: whether
- * an agent-facing delivery steers into the running turn or queues behind it
- * (web `ComposerSubmissionPolicy` parity — an idle agent queues, plain Enter
- * takes the preference, and the accelerated chord takes its OPPOSITE).
- *
- * It is a property of the GESTURE, not of the persisted settings: a one-shot
- * gesture exists only inside the dispatch that resolved it, so every
- * downstream consumer (the TUI skill delivery) accepts this value instead of
- * re-deriving the mode from `busyEnter`.
- */
-type SubmitDelivery = 'steer' | 'queue';
-/**
- * The CURRENT host catalog's view of ONE parsed line (the DSH client
- * `CommandUiRuntime.matchEnter` decision table): whether the host CLAIMS the
- * line, and — for a claimed line — the claiming descriptor's attachment
- * declaration, so the dispatch can never consult two different catalog views
- * for the claim and the declaration.
- */
-type HostCommandClaim = {
-  readonly claimed: true;
-  /** The claiming descriptor's `input.attachments`
-   * (DSH `CommandInputDescriptor.attachments`): only a declaring command
-   * may be invoked with composer attachments. */
-  readonly attachments: boolean;
-} | {
-  readonly claimed: false;
-};
-//#endregion
-//#region src/index.d.ts
-/** Stable Cordis plugin name. */
-declare const name = "tui-runner";
-/** Core services required before the TUI can mount. */
-declare const inject: string[];
+//#region src/tui-config.d.ts
 /** Plugin config: the session to resume, resolved from the startup service,
  * plus the DSH 0.1.7 profile-owned live TUI preferences. Every preference
  * field is a schemastery `.volatile()` reference (PR A): the `tui-app`
@@ -365,6 +233,161 @@ interface Config {
   readonly legacySettingsMigrationVersion: Volatile<number>;
 }
 declare const Config: z<Config>;
+//#endregion
+//#region src/image/admission.d.ts
+/** Structural subset of `ImageAttachmentRef`. */
+interface ImageAttachmentRefLike {
+  readonly attachmentId: string;
+  readonly mediaType: ImageMediaType;
+  readonly bytes: number;
+  readonly width: number;
+  readonly height: number;
+  readonly name?: string;
+}
+//#endregion
+//#region src/image/types.d.ts
+/**
+ * Image draft vocabulary for the TUI input pipeline (plan M1).
+ *
+ * The draft layer is TUI-owned: it stages clipboard/file bytes until a
+ * submission turns them into durable `ImageAttachmentRef`s through the dsh
+ * attachment service. Nothing in this module persists; the durable boundary
+ * is the harness's `ctx.attachments.saveImages()`.
+ *
+ * The media-type union mirrors `@deepseek-ai/dsh-attachment`'s
+ * `ImageMediaType` structurally, so drafts flow into the harness without a
+ * runtime dependency on the attachment package (AGENTS.md decision 7:
+ * structural typing for dsh services).
+ * @module @xmoon76/dsh-pi-tui/image/types
+ */
+/** Raster media types accepted by the TUI image intake. */
+type ImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
+/** Per-TUI draft image identity; only meaningful inside one TUI run. */
+type DraftImageId = number;
+/** Where a staged image's bytes came from. */
+type DraftImageSource = {
+  readonly type: 'clipboard';
+} | {
+  readonly type: 'path';
+  readonly path: string;
+}
+/** The image was pulled back from a queued message: its bytes are ALREADY
+ * durable with the harness (the recalled ref) — the draft holds no local
+ * copy and re-submitting reuses the ref instead of re-uploading. */
+| {
+  readonly type: 'recalled';
+};
+/**
+ * One image staged in the editor draft. The draft holds the raw bytes so
+ * clipboard and path entries share one shape and a submit never depends on
+ * the source file still existing (plan §5.1). A RECALLED draft (pulled
+ * back from the queue) instead carries the durable `ImageAttachmentRef`
+ * and NO local bytes — the bytes stay in harness storage and re-submitting
+ * reuses the ref.
+ */
+interface DraftImage {
+  /** Per-TUI draft identity (the `#N` of the placeholder). */
+  readonly id: DraftImageId;
+  readonly kind: 'image';
+  readonly source: DraftImageSource;
+  /** Exact encoded bytes, held only for the draft lifetime. Empty for a
+   * recalled draft (its bytes live in harness storage). */
+  readonly bytes: Uint8Array;
+  readonly mediaType: ImageMediaType;
+  /** Intrinsic encoded width in pixels. */
+  readonly width: number;
+  /** Intrinsic encoded height in pixels. */
+  readonly height: number;
+  /** Exact encoded byte length (`bytes.byteLength` for local drafts; the
+   * durable ref's recorded `bytes` for recalled drafts). */
+  readonly byteLength: number;
+  /** Optional display name (basename for path sources), never a path. */
+  readonly name?: string;
+  /** The canonical editor placeholder text for this draft. */
+  readonly placeholder: string;
+  /** The durable ref this draft reuses on submit; present ONLY for
+   * recalled drafts (already-durable images are never re-uploaded). */
+  readonly recalledRef?: ImageAttachmentRefLike;
+}
+/** The store surface the placeholder expansion needs (structural). */
+interface DraftImageStoreLike {
+  values(): readonly DraftImage[];
+}
+//#endregion
+//#region src/task-presentation.d.ts
+declare function subagentJobTranscriptId(snapshot: unknown): string | undefined;
+/**
+ * The Task Center row-selection disposition (plan §4.3/§4.4). A subagent
+ * transcript opens a session/viewer surface that REPLACES the browser; a
+ * Job row's detail keeps it mounted (the caller passes {@link openJobView}'s
+ * disposition). An UNKNOWN row — a stale panel selection after a live
+ * re-projection — also keeps the parent usable instead of dismissing it.
+ */
+declare function taskRowSelectionDisposition(row: {
+  readonly kind: 'job' | 'subagent';
+} | undefined, jobDetail: 'close' | 'keep-open'): 'close' | 'keep-open';
+/** Viewer body for a subagent job with no uniquely matched child. */
+declare function subagentJobViewHint(status: string, detail: string | undefined): string;
+//#endregion
+//#region src/tui-app.d.ts
+/** The compaction lifecycle phase the working row advertises: idle (no
+ * compaction), summarizing (compaction/start seen, the summary is being
+ * generated), or applying (the summary landed, the compacted surface is
+ * being committed). Derived by the runner from compaction/start →
+ * compaction/summary → compaction/end (foldCompactionEvent). */
+type CompactionPhase = 'idle' | 'summarizing' | 'applying';
+/**
+ * The WEB composer submit gestures (DSH `ComposerSubmitGesture`): plain
+ * Enter, or the Cmd/Ctrl-accelerated chord. The busy-Enter policy resolves
+ * each to a delivery mode — plain Enter to the preferred mode, the
+ * accelerated chord to its OPPOSITE — so the chord is never a fixed mode.
+ */
+type ComposerSubmitGesture = 'enter' | 'accelerated';
+/** One semantic queued pending-input row for the queue pane. */
+interface QueueItem {
+  /** The pending message id (agent inbox identity), or a local request id. */
+  id: string;
+  /** The message text, single-line display form. */
+  text: string;
+  /** next-turn followup vs next-step steer. */
+  mode: 'followup' | 'steer';
+  /** The correlation identity (authoritative rpc id or local request id). */
+  rpcId?: string;
+  /** A client-local echo not yet backed by an authoritative occurrence. */
+  local?: boolean;
+}
+//#endregion
+//#region src/commands.d.ts
+/**
+ * The effective mode ONE submission resolved at the submit boundary: whether
+ * an agent-facing delivery steers into the running turn or queues behind it
+ * (web `ComposerSubmissionPolicy` parity — an idle agent queues, plain Enter
+ * takes the preference, and the accelerated chord takes its OPPOSITE).
+ *
+ * It is a property of the GESTURE, not of the persisted settings: a one-shot
+ * gesture exists only inside the dispatch that resolved it, so every
+ * downstream consumer (the TUI skill delivery) accepts this value instead of
+ * re-deriving the mode from `busyEnter`.
+ */
+type SubmitDelivery = 'steer' | 'queue';
+/**
+ * The CURRENT host catalog's view of ONE parsed line (the DSH client
+ * `CommandUiRuntime.matchEnter` decision table): whether the host CLAIMS the
+ * line, and — for a claimed line — the claiming descriptor's attachment
+ * declaration, so the dispatch can never consult two different catalog views
+ * for the claim and the declaration.
+ */
+type HostCommandClaim = {
+  readonly claimed: true;
+  /** The claiming descriptor's `input.attachments`
+   * (DSH `CommandInputDescriptor.attachments`): only a declaring command
+   * may be invoked with composer attachments. */
+  readonly attachments: boolean;
+} | {
+  readonly claimed: false;
+};
+//#endregion
+//#region src/command-policy.d.ts
 /**
  * Slash commands that need no session: before the first user message
  * (deferred start) they run locally without creating one. Everything else
@@ -529,6 +552,29 @@ declare function normalizeSkillInvocation(text: string): string | undefined;
 declare function shouldConsumeAdvertisedMiss(execution: {
   readonly result: unknown;
 } | undefined, wasAdvertised: boolean): boolean;
+/**
+ * Whether a plain submitted draft is the quit word: exactly `exit` (trimmed,
+ * lowercase). The runner intercepts this BEFORE any session creation or
+ * submission (shell muscle memory); anything else — `exit!`, `Exit`, or a
+ * draft with a recalled entry still in it — is an ordinary message.
+ * @param text - the submitted draft.
+ */
+declare function isPlainExitPrompt(text: string): boolean;
+/**
+ * Whether a shell command matches a destructive pattern. `rm` is treated
+ * specially: any spelling of recursive + force flags (`rm -rf`, `rm -r -f`,
+ * `rm -rf /`) is dangerous; the remaining patterns are verbatim matches.
+ */
+declare function dangerCommand(command: string): boolean;
+//#endregion
+//#region src/interrupt.d.ts
+/**
+ * The live-turn interrupt helper (web Stop parity): abort the current
+ * turn/tool run while PRESERVING the pending queue. Kept out of the
+ * composition root so the rule is testable headless, and its structural
+ * faces keep the internal runtime port module out of the published entry.
+ * @module @xmoon76/dsh-pi-tui/interrupt
+ */
 /** Public settlement shape for the interrupt helper. Kept local so the
  * entry-point declaration does not expose the internal runtime port module. */
 type InterruptWriteOutcome = {
@@ -593,6 +639,8 @@ interface InterruptWriterLike {
  * agreed web-parity behavior until upstream lands the capability.
  */
 declare function interruptAgent(agent: InterruptAgentLike | undefined, writer: InterruptWriterLike): Promise<InterruptWriteOutcome>;
+//#endregion
+//#region src/subagent-viewer.d.ts
 /** One unsettled subagent delegation, in tool/call order. */
 interface PendingSubagentCall {
   readonly callId: string;
@@ -664,79 +712,8 @@ declare function viewerActionCapability(action: TuiAction, viewer: {
  * @returns the matched call, or undefined when nothing matches.
  */
 declare function matchPendingSubagentCall(pending: PendingSubagentCall[], label: string | undefined): PendingSubagentCall | undefined;
-/**
- * The pre-mount surface catalog resolution:
- * - an explicit `--session` start PREFETCHES the resumed agent's effective
- *   catalog (a live read emits no session events);
- * - the deferred start (no `--session`) reads the cold HUMAN SKILL catalog
- *   through the preset's STANDING SCOPE — no Agent, no session, no turn —
- *   so the first input sees human-invocable skills without any durable
- *   side effect (the mechanism that avoids the probe dead end: host
- *   `session/created` observers write durable knob events into every fresh
- *   session).
- *
- * The snapshot (resume) or the skill catalog (cold) installs synchronously
- * after mount (the ready barrier).
- *
- * Failure taxonomy (plan appendix B):
- * - lifecycle cancellation: nothing installed, no notice;
- * - a prefetch/standing read failure degrades to a one-shot notice (the
- *   TUI mounts with the global view and built-in commands);
- * - a missing/unknown preset or a broken standing mount degrades the cold
- *   target to the global layer with a one-shot notice — never a probe
- *   Agent, never a startup failure;
- * - an ordinary provider read failure never rejects here: it becomes an
- *   empty field + detached issue inside the catalog.
- * @param options - injected dependencies (see {@link ResolveInitialCatalogOptions}).
- * @returns the snapshot / skill catalog to install and an optional notice.
- */
-interface InitialCatalogResolution {
-  /** The resume prefetch snapshot to install at mount. */
-  readonly snapshot?: SurfaceCatalogSnapshot;
-  /** The cold standing-scope human skill catalog (deferred start). */
-  readonly skills?: HumanSkillCatalog;
-  /** A user-facing notice when the prefetch/standing read degraded. */
-  readonly notice?: string;
-}
-/** Options for {@link resolveInitialCatalog}. */
-interface ResolveInitialCatalogOptions {
-  /** The resumed live agent, if any (prefetch path). */
-  readonly liveAgent?: Agent;
-  /** The effective preset id for the cold standing read (undefined = the
-   * deployment default; only consulted for the deferred start). */
-  readonly presetId?: string;
-  readonly signal: AbortSignal;
-  /** The context surface the collectors read services from. */
-  readonly ctx: SurfaceCatalogContext;
-  readonly diag: Diag;
-  /** Suspend the pre-mount startup status before an ordinary log write
-   * (the status owns the current terminal line; a TTY shares one cursor
-   * between stdout and stderr). Called right before every diag.warn this
-   * function may emit. */
-  readonly onLog?: () => void;
-}
-declare function resolveInitialCatalog(options: ResolveInitialCatalogOptions): Promise<InitialCatalogResolution>;
-declare function subagentJobTranscriptId(snapshot: unknown): string | undefined;
-/**
- * The Task Center row-selection disposition (plan §4.3/§4.4). A subagent
- * transcript opens a session/viewer surface that REPLACES the browser; a
- * Job row's detail keeps it mounted (the caller passes {@link openJobView}'s
- * disposition). An UNKNOWN row — a stale panel selection after a live
- * re-projection — also keeps the parent usable instead of dismissing it.
- */
-declare function taskRowSelectionDisposition(row: {
-  readonly kind: 'job' | 'subagent';
-} | undefined, jobDetail: 'close' | 'keep-open'): 'close' | 'keep-open';
-/** Viewer body for a subagent job with no uniquely matched child. */
-declare function subagentJobViewHint(status: string, detail: string | undefined): string;
-/**
- * Whether a plain submitted draft is the quit word: exactly `exit` (trimmed,
- * lowercase). The runner intercepts this BEFORE any session creation or
- * submission (shell muscle memory); anything else — `exit!`, `Exit`, or a
- * draft with a recalled entry still in it — is an ordinary message.
- * @param text - the submitted draft.
- */
-declare function isPlainExitPrompt(text: string): boolean;
+//#endregion
+//#region src/pending-presentation.d.ts
 /** One semantic pending-input item as the queue mirror sees it. */
 interface QueueInboxMessage {
   readonly id: string;
@@ -749,35 +726,11 @@ interface QueueFoldResult {
 /** Build queue-pane rows from semantic pending-input occurrences, preserving
  * their order and content without inspecting backend-specific metadata. */
 declare function foldQueueRows(messages: readonly QueueInboxMessage[], mode: 'followup' | 'steer'): QueueFoldResult;
-/**
- * Whether a shell command matches a destructive pattern. `rm` is treated
- * specially: any spelling of recursive + force flags (`rm -rf`, `rm -r -f`,
- * `rm -rf /`) is dangerous; the remaining patterns are verbatim matches.
- */
-declare function dangerCommand(command: string): boolean;
-/**
- * The dsh profile this process was launched with (the `--profile` flag),
- * so the exit-time resume hint names the profile the TUI actually runs
- * under. Falls back to `pi-tui` when the flag is absent (the TUI bundle
- * cannot load without a profile, so this is defensive only).
- * @param argv - the process argument vector.
- * @param fallback - the default profile.
- */
-declare function runningProfile(argv?: readonly string[], fallback?: string): string;
-/**
- * The interactive-quit resume hint (pi parity): `dsh --profile <p>
- * --session <id>`, printed after the terminal restores so the user can
- * re-enter the session later. Returns undefined when there is no session
- * to resume (deferred start never created one).
- * @param profile - the running profile ({@link runningProfile}).
- * @param sessionId - the live session id.
- * @returns the resume command line, or undefined without a session.
- */
-declare function resumeCommand(profile: string, sessionId: string): string | undefined;
-/** One fold of a compaction lifecycle event over the runner's in-flight
- * compaction state. Pure (the firehose applies the returned surface
- * effects): dsh-compaction is not a peer, so the event is read
- * structurally. */
+//#endregion
+//#region src/compaction-presentation.d.ts
+/** One fold of a compaction lifecycle event over the in-flight compaction
+ * state. Pure (the routing applies the returned surface effects):
+ * dsh-compaction is not a peer, so the event is read structurally. */
 interface CompactionFold {
   /** The updated in-flight compaction id (the newest start wins). */
   id: string | undefined;
@@ -808,7 +761,7 @@ declare function foldCompactionEvent(state: {
     error?: unknown;
   };
 }): CompactionFold;
-/** The minimal compaction-settle surface the runner passes in — STRUCTURAL
+/** The minimal compaction-settle surface the routing passes in — STRUCTURAL
  * on purpose: referencing the full {@link TuiApp} class from a public
  * export would inline the whole surface (and its internal registry/
  * presentation dependencies) into the published declaration bundle. The
@@ -854,6 +807,101 @@ declare function compactingFromLog(events: readonly {
   active: boolean;
   id: string | undefined;
 };
+//#endregion
+//#region src/dsh-profile.d.ts
+/**
+ * The DSH launcher PROFILE identity and the resume hint (plan §27).
+ *
+ * Deliberately NOT part of `src/startup.ts`: the startup row is a
+ * zero-dependency island that must not share a bundle chunk with the runner,
+ * so these runner-side helpers live in their own module and the entry
+ * re-exports them unchanged.
+ * @module @xmoon76/dsh-pi-tui/dsh-profile
+ */
+/**
+ * The dsh profile named by the `--profile` flag in `argv`, in both spellings.
+ * This is the ARGV-ONLY fallback: it cannot see the positional `dsh <name>`
+ * launch form, because the launcher consumes that bare name by synthesizing
+ * `['--profile', ...argv]` for its OWN commander parse and leaves
+ * `process.argv` untouched. Prefer {@link hostRunningProfile}, which reads the
+ * Host's profile identity instead of scraping the command line.
+ * @param argv - the process argument vector.
+ * @param fallback - the default profile.
+ */
+declare function runningProfile(argv?: readonly string[], fallback?: string): string;
+/** The one context read {@link hostRunningProfile} needs (a cordis Context satisfies it). */
+interface ProfileContextReadLike {
+  get(name: string): unknown;
+}
+/**
+ * The profile this process actually runs — the official Host
+ * `profileContext.name` when it is composed, else {@link runningProfile}'s
+ * argv scrape.
+ *
+ * `profileContext.name` is the launcher's own profile identity, so it is
+ * correct for EVERY launch form: `--profile <name>`, `--profile=<name>`, the
+ * positional `dsh <name>`, and `--from-default-profile <name>`. The argv
+ * scrape only knows the flag form, which is why it is the fallback for a
+ * profile-less mount (tests, an embedded surface) rather than the primary
+ * source.
+ * @param ctx - the plugin context (or any structural `get`-only stand-in).
+ * @param argv - the process argument vector for the fallback path.
+ * @param fallback - the default profile for the fallback path.
+ * @returns the running profile name.
+ */
+declare function hostRunningProfile(ctx: ProfileContextReadLike, argv?: readonly string[], fallback?: string): string;
+/**
+ * The interactive-quit resume hint (pi parity): `dsh --profile <p>
+ * --session <id>`, printed after the terminal restores so the user can
+ * re-enter the session later. Returns undefined when there is no session
+ * to resume (deferred start never created one).
+ * @param profile - the running profile ({@link hostRunningProfile}).
+ * @param sessionId - the live session id.
+ * @returns the resume command line, or undefined without a session.
+ */
+declare function resumeCommand(profile: string, sessionId: string): string | undefined;
+//#endregion
+//#region src/index.d.ts
+/** Stable Cordis plugin name. */
+declare const name = "tui-runner";
+/** Core services required before the TUI can mount. */
+declare const inject: string[];
+/**
+ * Options for {@link resolveInitialCatalog}.
+ *
+ * The public declaration stays here (A5a review P1): `liveAgent` keeps the Host
+ * `Agent` type it has always had, so consumers that READ the property keep
+ * compiling. The implementation consumes the structural
+ * `SurfaceCatalogResolutionOptions` in `surface-catalog.ts`.
+ */
+interface ResolveInitialCatalogOptions {
+  /** The resumed live agent, if any (prefetch path). */
+  readonly liveAgent?: Agent;
+  /** The effective preset id for the cold standing read (undefined = the
+   * deployment default; only consulted for the deferred start). */
+  readonly presetId?: string;
+  readonly signal: AbortSignal;
+  /** The context surface the collectors read services from. */
+  readonly ctx: SurfaceCatalogContext;
+  readonly diag: Diag;
+  /** Suspend the pre-mount startup status before an ordinary log write
+   * (the status owns the current terminal line; a TTY shares one cursor
+   * between stdout and stderr). Called right before every diag.warn this
+   * function may emit. */
+  readonly onLog?: () => void;
+}
+/**
+ * The pre-mount surface catalog resolution (plan §27): the published entry for
+ * {@link ResolveInitialCatalogOptions}. An explicit `--session` start
+ * prefetches the resumed agent's effective catalog; the deferred start reads the
+ * cold HUMAN SKILL catalog through the preset's STANDING SCOPE — no Agent, no
+ * session, no turn — so the first input sees human-invocable skills without any
+ * durable side effect. The implementation and its failure taxonomy live in
+ * `surface-catalog.ts`.
+ * @param options - injected dependencies (see {@link ResolveInitialCatalogOptions}).
+ * @returns the snapshot / skill catalog to install and an optional notice.
+ */
+declare function resolveInitialCatalog(options: ResolveInitialCatalogOptions): Promise<InitialCatalogResolution>;
 /** One agent's preset composition: the id to record and the setup that installs it. */
 interface AgentComposition {
   /** Preset id for the session header, absent when the deployment composes no roster. */
@@ -922,4 +970,4 @@ declare function recordedPreset(ctx: Context, sessionId: string): Promise<string
  */
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { AgentComposition, CompactionFold, CompactionSettleSurface, Config, HOST_COMMAND_CATALOG, InitialCatalogResolution, InterruptAgentLike, InterruptWriteOutcome, InterruptWriterLike, LOCAL_COMMANDS, PendingSubagentCall, QueueFoldResult, QueueInboxMessage, ResolveInitialCatalogOptions, SESSIONLESS_COMMANDS, ViewerOpenToken, apply, busyAfterTurnBoundary, commandIsLocalForAttachments, commandRejectsImages, compactingFromLog, composeAgent, contextRefreshKind, createViewerOpenToken, dangerCommand, foldCompactionEvent, foldQueueRows, inject, interruptAgent, isBareCommandLine, isLocalCommandLine, isPlainExitPrompt, matchPendingSubagentCall, name, normalizeSkillInvocation, recordedPreset, resolveInitialCatalog, resolveSubmitDelivery, resumeCommand, runningProfile, settleCompactionSurface, shouldConsumeAdvertisedMiss, subagentJobTranscriptId, subagentJobViewHint, taskRowSelectionDisposition, teardownViewerForSessionSwap, viewerActionCapability };
+export { AgentComposition, type CompactionFold, type CompactionSettleSurface, Config, HOST_COMMAND_CATALOG, type InitialCatalogResolution, type InterruptAgentLike, type InterruptWriteOutcome, type InterruptWriterLike, LOCAL_COMMANDS, type PendingSubagentCall, type ProfileContextReadLike, type QueueFoldResult, type QueueInboxMessage, ResolveInitialCatalogOptions, SESSIONLESS_COMMANDS, type ViewerOpenToken, apply, busyAfterTurnBoundary, commandIsLocalForAttachments, commandRejectsImages, compactingFromLog, composeAgent, contextRefreshKind, createViewerOpenToken, dangerCommand, foldCompactionEvent, foldQueueRows, hostRunningProfile, inject, interruptAgent, isBareCommandLine, isLocalCommandLine, isPlainExitPrompt, matchPendingSubagentCall, name, normalizeSkillInvocation, recordedPreset, resolveInitialCatalog, resolveSubmitDelivery, resumeCommand, runningProfile, settleCompactionSurface, shouldConsumeAdvertisedMiss, subagentJobTranscriptId, subagentJobViewHint, taskRowSelectionDisposition, teardownViewerForSessionSwap, viewerActionCapability };