@xmoon76/dsh-pi-tui 0.4.1 → 0.4.5

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { H as TuiAction } from "./public-types-_pe9ZH00.mjs";
+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";
@@ -86,36 +86,6 @@ interface DraftImageStoreLike {
   values(): readonly DraftImage[];
 }
 //#endregion
-//#region src/diag.d.ts
-interface Diag {
-  debug(message: string, fields?: Record<string, unknown>): void;
-  info(message: string, fields?: Record<string, unknown>): void;
-  warn(message: string, fields?: Record<string, unknown>): void;
-  error(message: string, fields?: Record<string, unknown>): void;
-  /** Release the file handle, if one is open. */
-  dispose(): void;
-}
-//#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';
-/** One queued inbox row for the queue pane (mirrors the agent Inbox's lists). */
-interface QueueItem {
-  /** The pending message id (agent inbox identity). */
-  id: string;
-  /** The message text, single-line display form. */
-  text: string;
-  /** next-turn followup vs next-step steer. */
-  mode: 'followup' | 'steer';
-  /** Plugin notice (e.g. a background-job completion): NOT steerable — it
-   * renders with its own marker and the hint drops the steer verbs. */
-  notice?: boolean;
-}
-//#endregion
 //#region src/skill-catalog.d.ts
 /**
  * The standing-scope skill catalog adapter: the SINGLE narrow seam between
@@ -153,6 +123,43 @@ interface HumanSkillCatalog {
   readonly complete: boolean;
 }
 //#endregion
+//#region src/diag.d.ts
+interface Diag {
+  debug(message: string, fields?: Record<string, unknown>): void;
+  info(message: string, fields?: Record<string, unknown>): void;
+  warn(message: string, fields?: Record<string, unknown>): void;
+  error(message: string, fields?: Record<string, unknown>): void;
+  /** Release the file handle, if one is open. */
+  dispose(): void;
+}
+//#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 queued inbox row for the queue pane (mirrors the agent Inbox's lists). */
+interface QueueItem {
+  /** The pending message id (agent inbox identity). */
+  id: string;
+  /** The message text, single-line display form. */
+  text: string;
+  /** next-turn followup vs next-step steer. */
+  mode: 'followup' | 'steer';
+  /** Plugin notice (e.g. a background-job completion): NOT steerable — it
+   * renders with its own marker and the hint drops the steer verbs. */
+  notice?: boolean;
+}
+//#endregion
 //#region src/surface-catalog.d.ts
 /** One effective command's discovery metadata (the official descriptor's
  * display fields; never a handler or a definition). */
@@ -161,6 +168,11 @@ interface SurfaceCommandSummary {
   readonly description: string;
   readonly input?: {
     readonly hint: string;
+    /** The descriptor's attachment declaration (DSH
+     * `CommandInputDescriptor.attachments`): ONLY a command declaring it may
+     * be invoked with composer attachments (the composer-side half of the
+     * contract — the host executor enforces the other half at admission). */
+    readonly attachments?: boolean;
   };
 }
 /** One provider's detached failure text (never the thrown value itself). */
@@ -201,6 +213,34 @@ interface SurfaceCatalogContext {
  * @returns the fork seed events, or undefined.
  */
 declare function forkSeed(events: readonly SessionEvent[]): readonly SessionEvent[] | undefined;
+/**
+ * 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. */
@@ -258,38 +298,103 @@ declare const LOCAL_COMMANDS: Set<string>;
  * @param parsed - the parsed slash command, undefined for a plain prompt.
  * @param text - the submission text.
  * @param store - the live draft store.
- * @param isLocal - whether the command name is a LOCAL (TUI-owned/UI)
- *   command; skill names answer false.
+ * @param isLocal - whether THIS LINE is a LOCAL (TUI-owned/UI) command; skill
+ *   names answer false. Never derived from the name alone: a host command's
+ *   input KIND decides which line it claims (see
+ *   {@link commandIsLocalForAttachments}).
  */
 declare function commandRejectsImages(parsed: {
   name: string;
-} | undefined, text: string, store: DraftImageStoreLike, isLocal: (name: string) => boolean): boolean;
+  rawInput?: string;
+} | undefined, text: string, store: DraftImageStoreLike, isLocal: boolean): boolean;
 /**
- * The AUTHORITATIVE host-owned command catalog (P1-04): every command name
- * the TUI registers itself (registerTuiCommands in commands.ts) plus the
- * ownership sets (LOCAL_COMMANDS and SESSIONLESS_COMMANDS — /kill and
- * other core commands the TUI does not register but dispatches locally).
- * A plugin command contribution is validated against this catalog at
- * register time: an exact or near-synonym collision is rejected loudly,
- * so a plugin can never shadow a built-in command.
+ * The STATIC host-owned command catalog (P1-04): the ownership sets
+ * (LOCAL_COMMANDS and SESSIONLESS_COMMANDS — the TUI's own local/UI command
+ * names, including the ones `registerTuiCommands` registers, plus core
+ * commands such as /kill that the TUI does not register but dispatches
+ * locally) and `/plan`. A plugin command contribution is validated against
+ * this fixed catalog at register time: an exact or near-synonym collision is
+ * rejected loudly, so a plugin can never shadow a built-in command. Names
+ * that only the CURRENT host catalog owns (session-scoped or dynamically
+ * registered commands) are not in this set — those collisions surface at
+ * candidate synthesis time instead.
  */
 declare const HOST_COMMAND_CATALOG: ReadonlySet<string>;
 /**
- * Whether one submission steers under the busy-Enter preference: NOT a
- * force-queued chord, NOT a TUI-owned local command, and the agent is
- * running with the preference set to 'steer'. Pure so the dispatch gate
- * (inside the runner closure) is testable headless.
+ * The TUI-local classification the attachment gate uses: a TUI/core local
+ * command or a live client command contribution is LOCAL (its line is a UI
+ * control — attachments are refused), while a LIVE skill wrapper is
+ * AGENT-FACING input (multimodal) even when a client contribution shares its
+ * name: the wrapper route outranks the contribution everywhere.
+ * @param name - the slash name.
+ * @param isSkillWrapper - the live skill-wrapper test (absent = none).
+ * @param isDynamicLocal - the live client-contribution test (absent = none).
+ * @param hostView - the host catalog's view of THIS LINE (`undefined` = the
+ *   catalog does not resolve the name at all; see {@link HostCommandClaim}).
+ *   A name the catalog RESOLVES is never a client-local line: when the
+ *   catalog claims the line the host's own `input.attachments` declaration
+ *   decides, and when it does not (an argued line of an execute-kind
+ *   command) the line is an ordinary submission — never a same-named client
+ *   contribution's.
+ */
+declare function isLocalCommandLine(name: string, isSkillWrapper: ((name: string) => boolean) | undefined, isDynamicLocal: ((name: string) => boolean) | undefined, hostView?: HostCommandClaim | undefined): boolean;
+/**
+ * Whether one parsed line is the BARE slash token (DSH `matchEnter`'s `bare`:
+ * no input follows the name — trailing whitespace is not input). It is the
+ * whole difference between a command invocation and an ordinary submission
+ * for the NAME-keyed client routes: a client command contribution claims the
+ * bare token only, exactly like an execute-kind host command.
+ * @param parsed - the parsed slash command.
+ * @returns whether the line carries no input after the command name.
+ */
+declare function isBareCommandLine(parsed: {
+  name: string;
+  rawInput?: string;
+}): boolean;
+/**
+ * The attachment gate's local-command classification for ONE parsed line —
+ * the SINGLE classification the dispatch and its regression tests share, and
+ * the DSH client namespace order applied to a LINE:
+ * - a TUI/core local command is local;
+ * - `/skill <name> ...` and a LIVE skill wrapper are agent-facing
+ *   (multimodal) even when a client contribution shares the name;
+ * - a name the HOST catalog RESOLVES is never local: when the catalog claims
+ *   the line, the claiming descriptor's `input.attachments` declaration
+ *   decides (`/goal <objective>` is claimed), and when it does not (an argued
+ *   line of an execute-kind command, `/compact extra`) the line is an
+ *   ordinary submission — never a command and never a same-named client
+ *   contribution's;
+ * - everything else follows the live client contribution of that name — for
+ *   the BARE token only: a contribution claims `/name`, so an argued line
+ *   (`/deploy explain`) is an ordinary multimodal submission that keeps its
+ *   attachments.
+ * @param parsed - the parsed slash command (undefined = plain prompt).
+ * @param isSkillWrapper - the live skill-wrapper test (absent = none).
+ * @param isDynamicLocal - the live client-contribution test (absent = none).
+ * @param hostClaim - the live HOST-catalog view of THIS LINE (absent = none).
+ * @returns whether the line is a local command line.
+ */
+declare function commandIsLocalForAttachments(parsed: {
+  name: string;
+  rawInput?: string;
+} | undefined, isSkillWrapper: ((name: string) => boolean) | undefined, isDynamicLocal: ((name: string) => boolean) | undefined, hostClaim?: ((parsed: {
+  name: string;
+  rawInput?: string;
+}) => HostCommandClaim | undefined) | undefined): boolean;
+/**
+ * The TUI dispatch boundary's delivery resolution: the WEB composer policy
+ * ({@link resolveComposerDelivery}) applied to agent-facing input, with the
+ * TUI's own ownership terms on top. Pure so the dispatch gate (inside the
+ * runner closure) is testable headless.
  * @param parsed - the parsed slash command, undefined for a plain prompt.
  * @param running - whether the live agent reports running.
+ * @param gesture - the composer gesture that raised the submission.
  * @param busyEnter - the persisted preference value (''/undefined = queue).
- * @param forceQueue - the Ctrl+Enter chord: always queue, never steer.
- * @param isDynamicLocal - M5: the CommandBridge's effective-local check for
- *   plugin-declared local commands (absent = static set only).
  */
-declare function shouldSteerOnEnter(parsed: {
+declare function resolveSubmitDelivery(parsed: {
   name: string;
   rawInput?: string;
-} | undefined, running: boolean, busyEnter: string | undefined, forceQueue: boolean, isDynamicLocal?: (name: string) => boolean): boolean;
+} | undefined, running: boolean, gesture: ComposerSubmitGesture, busyEnter: string | undefined): SubmitDelivery;
 /**
  * Normalize an explicit `/skill <name> <args>` invocation to the skill's
  * own slash line `/<name> <args>` (review finding 2). The harness's
@@ -313,7 +418,10 @@ declare function normalizeSkillInvocation(text: string): string | undefined;
  * unadvertised miss keeps the existing plain-input fallback (the user may
  * deliberately send slash text to the model).
  * @param execution - the settled `commands.execute` outcome.
- * @param wasAdvertised - the claim captured BEFORE session creation.
+ * @param wasAdvertised - whether the submission was an advertised command
+ *   INVOCATION: the submit-time name claim AND the command plane's final
+ *   ownership of the line (an argued line of an execute-kind command never
+ *   reached the plane, so it is an ordinary submission).
  * @returns whether the miss must be consumed as an advertised miss.
  */
 declare function shouldConsumeAdvertisedMiss(execution: {
@@ -584,17 +692,6 @@ declare function runningProfile(argv?: readonly string[], fallback?: string): st
  * @returns the resume command line, or undefined without a session.
  */
 declare function resumeCommand(profile: string, sessionId: string): string | undefined;
-/**
- * A launch-time open-lock refusal: the requested session is held by another
- * live dsh process (or its lock cannot be verified). Unlike a stale/missing
- * session id, this is NOT recoverable by falling back to a fresh session —
- * the user asked for a specific session and must resolve the holder first.
- * Thrown from the resume path and re-thrown past the resume catch so the
- * runner exits with the refusal as the error message.
- */
-declare class SessionLockRefusedError extends Error {
-  constructor(message: string);
-}
 /** 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
@@ -680,6 +777,16 @@ interface AgentComposition {
   /** Preset id for the session header, absent when the deployment composes no roster. */
   agentPreset?: string;
   /** Agent-factory setup: model selection, then the preset mount when composed. */
+  setup: (agentCtx: Context, agent: Agent) => Promise<void> | void;
+}
+/**
+ * Source-compatible composition returned for standalone callers that provide
+ * their own ModelSelectionRef instead of an Agent-local installer.
+ */
+interface LegacyAgentComposition {
+  /** Preset id for the session header, absent when the deployment composes no roster. */
+  agentPreset?: string;
+  /** Standalone setup installs the caller-owned model selection ref. */
   setup: (agentCtx: Context) => Promise<void> | void;
 }
 /**
@@ -696,9 +803,10 @@ interface AgentComposition {
  * host composition, which is the behavior before presets existed.
  * @param ctx - the runner context (services read through `ctx.get`).
  * @param installSelection - installs a fresh Agent-local model selection ref
- *   during setup. A ModelSelectionRef is still accepted for source
- *   compatibility with standalone composition callers; the runner always
- *   supplies the Agent-local installer.
+ *   during setup using the explicit Agent identity supplied by DSH. A
+ *   ModelSelectionRef is also accepted for source compatibility with
+ *   standalone composition callers; that branch installs the caller-owned ref
+ *   and does not require an Agent.
  * @param presetId - the requested preset, or `undefined` for the default.
  * @param focusState - the shared Focus runtime state (STRUCTURAL on
  *   purpose: the public declaration bundle must not inline src/focus.ts —
@@ -711,12 +819,15 @@ interface AgentComposition {
  * @returns the id to record on the header (absent without a roster) and the setup callback.
  * @throws when the roster supplies no such preset.
  */
-declare function composeAgent(ctx: Context, installSelection: ((agentCtx: Context) => void) | ModelSelectionRef, presetId?: string, focusState?: {
+declare function composeAgent(ctx: Context, installSelection: ModelSelectionRef, presetId?: string, focusState?: {
+  enabled: boolean;
+}, diag?: Diag): Promise<LegacyAgentComposition>;
+declare function composeAgent(ctx: Context, installSelection: (agentCtx: Context, agent: Agent) => void, presetId?: string, focusState?: {
   enabled: boolean;
 }, diag?: Diag): Promise<AgentComposition>;
 /**
- * The preset a persisted session actually runs, resolved by the DSH 0.1.2+
- * session projection (header initialization plus the latest selection event).
+ * The preset a persisted session actually runs, read from DSH 0.1.5-rc.1's
+ * V3 session projection (header initialization plus the latest selection event).
  * @param ctx - the runner context.
  * @param sessionId - the persisted session id.
  * @returns the recorded preset id, or undefined to compose the default.
@@ -762,4 +873,4 @@ declare function recomposeBlank(ctx: Context, agent: {
  */
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { AgentComposition, CompactionFold, CompactionSettleSurface, Config, HOST_COMMAND_CATALOG, InitialCatalogResolution, InterruptAgentLike, InterruptWriterLike, LOCAL_COMMANDS, PendingSubagentCall, QueueFoldResult, QueueInboxMessage, QueueNoticeSource, RecomposableSession, RecomposeOutcome, ResolveInitialCatalogOptions, SESSIONLESS_COMMANDS, SessionLockRefusedError, ViewerOpenToken, apply, busyAfterTurnBoundary, commandRejectsImages, compactingFromLog, composeAgent, contextRefreshKind, createViewerOpenToken, dangerCommand, foldCompactionEvent, foldQueueRows, forkSeed, inject, interruptAgent, isPlainExitPrompt, isSubagentSettlementNotice, isUserQueueInput, matchPendingSubagentCall, name, normalizeSkillInvocation, recomposeBlank, recordedPreset, resolveInitialCatalog, resumeCommand, runningProfile, settleCompactionSurface, shouldConsumeAdvertisedMiss, shouldSteerOnEnter, subagentJobTranscriptId, subagentJobViewHint, subagentNoticeIsFailure, teardownViewerForSessionSwap, viewerActionCapability };
+export { AgentComposition, CompactionFold, CompactionSettleSurface, Config, HOST_COMMAND_CATALOG, InitialCatalogResolution, InterruptAgentLike, InterruptWriterLike, LOCAL_COMMANDS, PendingSubagentCall, QueueFoldResult, QueueInboxMessage, QueueNoticeSource, RecomposableSession, RecomposeOutcome, ResolveInitialCatalogOptions, SESSIONLESS_COMMANDS, ViewerOpenToken, apply, busyAfterTurnBoundary, commandIsLocalForAttachments, commandRejectsImages, compactingFromLog, composeAgent, contextRefreshKind, createViewerOpenToken, dangerCommand, foldCompactionEvent, foldQueueRows, forkSeed, inject, interruptAgent, isBareCommandLine, isLocalCommandLine, isPlainExitPrompt, isSubagentSettlementNotice, isUserQueueInput, matchPendingSubagentCall, name, normalizeSkillInvocation, recomposeBlank, recordedPreset, resolveInitialCatalog, resolveSubmitDelivery, resumeCommand, runningProfile, settleCompactionSurface, shouldConsumeAdvertisedMiss, subagentJobTranscriptId, subagentJobViewHint, subagentNoticeIsFailure, teardownViewerForSessionSwap, viewerActionCapability };

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { A as shouldConsumeAdvertisedMiss, C as normalizeSkillInvocation, D as resumeCommand, E as resolveInitialCatalog, F as teardownViewerForSessionSwap, I as viewerActionCapability, M as subagentJobTranscriptId, N as subagentJobViewHint, O as runningProfile, P as subagentNoticeIsFailure, R as forkSeed, S as name, T as recordedPreset, _ as interruptAgent, a as SessionLockRefusedError, b as isUserQueueInput, c as commandRejectsImages, d as contextRefreshKind, f as createViewerOpenToken, g as inject, h as foldQueueRows, i as SESSIONLESS_COMMANDS, j as shouldSteerOnEnter, k as settleCompactionSurface, l as compactingFromLog, m as foldCompactionEvent, n as HOST_COMMAND_CATALOG, o as apply, p as dangerCommand, r as LOCAL_COMMANDS, s as busyAfterTurnBoundary, t as Config, u as composeAgent, v as isPlainExitPrompt, w as recomposeBlank, x as matchPendingSubagentCall, y as isSubagentSettlementNotice } from "./src-CeGK2mHo.mjs";
+import { A as resumeCommand, B as forkSeed, C as matchPendingSubagentCall, D as recordedPreset, E as recomposeBlank, F as subagentJobViewHint, I as subagentNoticeIsFailure, L as teardownViewerForSessionSwap, M as settleCompactionSurface, N as shouldConsumeAdvertisedMiss, O as resolveInitialCatalog, P as subagentJobTranscriptId, R as viewerActionCapability, S as isUserQueueInput, T as normalizeSkillInvocation, _ as interruptAgent, a as apply, b as isPlainExitPrompt, c as commandRejectsImages, d as contextRefreshKind, f as createViewerOpenToken, g as inject, h as foldQueueRows, i as SESSIONLESS_COMMANDS, j as runningProfile, k as resolveSubmitDelivery, l as compactingFromLog, m as foldCompactionEvent, n as HOST_COMMAND_CATALOG, o as busyAfterTurnBoundary, p as dangerCommand, r as LOCAL_COMMANDS, s as commandIsLocalForAttachments, t as Config, u as composeAgent, v as isBareCommandLine, w as name, x as isSubagentSettlementNotice, y as isLocalCommandLine } from "./src-B65x1oP2.mjs";
 import "./startup.mjs";
-export { Config, HOST_COMMAND_CATALOG, LOCAL_COMMANDS, SESSIONLESS_COMMANDS, SessionLockRefusedError, apply, busyAfterTurnBoundary, commandRejectsImages, compactingFromLog, composeAgent, contextRefreshKind, createViewerOpenToken, dangerCommand, foldCompactionEvent, foldQueueRows, forkSeed, inject, interruptAgent, isPlainExitPrompt, isSubagentSettlementNotice, isUserQueueInput, matchPendingSubagentCall, name, normalizeSkillInvocation, recomposeBlank, recordedPreset, resolveInitialCatalog, resumeCommand, runningProfile, settleCompactionSurface, shouldConsumeAdvertisedMiss, shouldSteerOnEnter, subagentJobTranscriptId, subagentJobViewHint, subagentNoticeIsFailure, teardownViewerForSessionSwap, viewerActionCapability };
+export { Config, HOST_COMMAND_CATALOG, LOCAL_COMMANDS, SESSIONLESS_COMMANDS, apply, busyAfterTurnBoundary, commandIsLocalForAttachments, commandRejectsImages, compactingFromLog, composeAgent, contextRefreshKind, createViewerOpenToken, dangerCommand, foldCompactionEvent, foldQueueRows, forkSeed, inject, interruptAgent, isBareCommandLine, isLocalCommandLine, isPlainExitPrompt, isSubagentSettlementNotice, isUserQueueInput, matchPendingSubagentCall, name, normalizeSkillInvocation, recomposeBlank, recordedPreset, resolveInitialCatalog, resolveSubmitDelivery, resumeCommand, runningProfile, settleCompactionSurface, shouldConsumeAdvertisedMiss, subagentJobTranscriptId, subagentJobViewHint, subagentNoticeIsFailure, teardownViewerForSessionSwap, viewerActionCapability };

package/dist/{public-types-_pe9ZH00.d.mts → public-types-YbB5Rhku.d.mts}

@@ -67,8 +67,16 @@ interface TuiAutocompleteQuery {
 interface TuiAutocompleteProvider {
   getSuggestions(query: TuiAutocompleteQuery): Promise<TuiAutocompleteSuggestions | null>;
 }
-/** API version of the extension surface (bumped only on breaking changes). */
-declare const API_VERSION: 1;
+/**
+ * API version of the extension surface (bumped only on breaking changes).
+ * `2` is the client-command contribution contract: `execution` and the
+ * never-wired `argumentProvider` are REMOVED, `handler` is required, and a
+ * stale plugin still declaring the removed ownership shape is rejected at
+ * registration. `1` was the M0–M3 foundation. A plugin branching on
+ * `api().apiVersion` can tell the two schemas apart — the host never reports
+ * a version it does not implement.
+ */
+declare const API_VERSION: 2;
 /** Capability identifiers, feature-detected via {@link PiTuiApiInfo}. */
 type PiTuiCapability = 'slot.chrome.header.badge' | 'slot.input.dock.item' | 'slot.chrome.footer.status' | 'slot.chrome.footer.item' | 'slot.input.widget' | 'surface.snapshot' | 'advanced.input.capture' | 'advanced.ui.interactive' | 'advanced.editor.control' | 'unstable.input.raw' | 'unstable.surface.handle';
 /** Slot identities this bundle knows; unknown names are rejected at registration. */
@@ -79,7 +87,8 @@ type PiTuiSlotSemantic = 'list' | 'single';
 type ExtensionTier = 'stable' | 'advanced' | 'unstable';
 /** What a plugin may know about the host (M1: version + capabilities only). */
 interface PiTuiApiInfo {
-  /** The extension API version; 1 for the M0–M3 foundation. */
+  /** The extension API version: 2 for the client-command contribution
+   * contract, 1 for the M0–M3 foundation (see {@link API_VERSION}). */
   readonly apiVersion: typeof API_VERSION;
   /** The `@xmoon76/dsh-pi-tui` bundle version (semver string). */
   readonly hostVersion: string;
@@ -335,29 +344,40 @@ interface InputWidget {
   /** Preferred max rows (budget); the host may grant fewer. */
   readonly maxHeight?: number;
 }
-/** One command contribution (plan §10): ownership metadata over an
- * existing command. The bridge does NOT execute — the commands service
- * does. `/name args...` ALWAYS keeps `invocation.rawInput` verbatim. */
+/** One CLIENT-OWNED command contribution (plan §10) — the DSH client
+ * command contribution shape: a slash name whose behavior lives entirely on
+ * the client (no host descriptor). It appears in the `/` menu merged with
+ * the host catalog and executes through its own `handler`, never steered.
+ * A contribution whose name is a host command FAILS LOUD at candidate
+ * synthesis and never shadows it (the host command keeps its claim).
+ * A contribution is a slash-MENU entry, so it claims the BARE `/name` token
+ * only (DSH `matchEnter`): `/name args...` is NOT an invocation — it is an
+ * ordinary submission that reaches the model, and `handler` never runs for
+ * it. */
 interface TuiCommandContribution {
   readonly id: string;
   /** The slash-command name WITHOUT the leading slash. */
   readonly name: string;
   readonly description: string;
-  /** Execution ownership: local (never steered) vs submission (session
-   * policy). Busy Enter classifies by the EFFECTIVE ownership. */
-  readonly execution: 'local' | 'submission';
-  /** Whether the command may run without a live session. */
+  /** Whether the command may run BEFORE a live session exists (default
+   * false). A sessionless contribution executes immediately; every other
+   * contribution resolves/creates the session first, then executes — the
+   * host command surface is session-keyed upstream, so this is an explicit
+   * TUI extension for pure client commands (an overlay toggle, a picker). */
   readonly sessionless?: boolean;
-  /** Optional autocomplete provider for this command's arguments
-   * (the structural {@link TuiAutocompleteProvider}). */
-  readonly argumentProvider?: TuiAutocompleteProvider;
-  /** Optional local handler; absent = metadata-only ownership (the
-   * commands service handler runs). */
-  readonly handler?: TuiLocalCommandHandler;
+  /** The command's client behavior (required): the TUI runs it locally for the
+   * BARE `/name` line, passing `invocation.rawInput` verbatim (it carries no
+   * non-whitespace input, since an argued line is never an invocation, though
+   * trailing whitespace may be preserved), with or without a live session
+   * according to {@link sessionless}. */
+  readonly handler: TuiLocalCommandHandler;
 }
 /** The local command handler signature (invocation carries the VERBATIM
- * raw input — never re-parsed or rewritten). Returns the commands
- * service's result shape (`{ kind: 'success' }` / `{ kind: 'error',
+ * raw input — never re-parsed or rewritten). A client command CONTRIBUTION is
+ * invoked by its bare token alone, so its `rawInput` never carries
+ * non-whitespace input (trailing whitespace is preserved verbatim); TUI-owned
+ * local commands (`/export json`) still receive their arguments here. Returns the
+ * commands service's result shape (`{ kind: 'success' }` / `{ kind: 'error',
  * text }`) so the runner's notify path is shared. */
 interface TuiLocalCommandHandler {
   (invocation: {
@@ -380,9 +400,13 @@ interface TuiLocalCommandHandler {
     readonly text: string;
   }>;
 }
-/** A live handle on one command contribution. */
+/** A live handle on ONE command contribution REGISTRATION. */
 interface TuiCommandHandle {
   readonly id: string;
+  /** Dispose THIS registration (idempotent). A repeated or late call — e.g.
+   * a fiber disposer running after an HMR reload re-registered the same id —
+   * never removes a NEWER registration: the handle names one generation, not
+   * the id. */
   dispose(): void;
 }
 /** The command bridge's observable snapshot. */
@@ -391,9 +415,12 @@ interface TuiCommandBridgeSnapshot {
     readonly id: string;
     readonly name: string;
     readonly description: string;
-    readonly execution: 'local' | 'submission';
     readonly sessionless: boolean;
     readonly owner: string;
+    /** Monotonic per-registration generation (diagnostics + the notice
+     * identity): a dispose + re-register under the same id/owner is a NEW
+     * generation, even when both happen inside one coalesced flush. */
+    readonly generation: number;
   }[];
   readonly revision: number;
 }