@askdkc/dsh-cli 0.11.3

package/lib/types/dsh-adapter/channel/binding-events.d.ts

@@ -0,0 +1,67 @@
+import type { AssistantStreamFrame, ModelSelectionRef } from '@deepseek-ai/dsh-agent';
+import type { Context } from '@deepseek-ai/cordis';
+import type { InputConvergence } from './input-actions.js';
+import type { ChannelBinding } from './binding.js';
+import type { ChannelOwner } from './owner.js';
+import { type createChannelProjection } from './projection.js';
+import type { ChannelState } from './types.js';
+/**
+ * The binding event router is the sole subscriber for a foreground Agent.
+ * It captures the binding generation at every listener entry; teardown is
+ * incremental and retained callbacks check that captured Agent/session pair
+ * before touching state. Transcript presentation remains exclusively owned by
+ * ChannelProjection.
+ */
+export declare function createBindingEvents(ctx: Context, deps: {
+    owner: ChannelOwner;
+    binding: ChannelBinding;
+    state: ChannelState;
+    /** Read the activity projection's current value for a freshly bound session.
+     *  A projection value only arrives when it changes, so a resumed or
+     *  reattached session needs this read to show its line before the next event.
+     *  The line's semantics live in the working-activity plugin: this app folds
+     *  nothing itself and forwards no events. */
+    seedActivity?(session: unknown): void;
+    inputConvergence: InputConvergence;
+    selection: ModelSelectionRef;
+    modelActions: {
+        applyPreferredEffort(): Promise<void>;
+        selection: ModelSelectionRef;
+    };
+    modeActions: {
+        refreshMode(): void;
+        onSessionEvent(session: unknown, event: unknown): void;
+    };
+    projector: ReturnType<typeof createChannelProjection>;
+    subagents: {
+        onSessionEvent(session: unknown, event: unknown): boolean;
+        onStreamFrame?(agent: unknown, frame: AssistantStreamFrame): boolean;
+        onParentEvent?(event: unknown): void;
+        onStart(info: {
+            id: string;
+            runId?: string;
+            provider: string;
+            local?: boolean;
+        }): void;
+        onEnd(info: {
+            id: string;
+            runId?: string;
+            stopReason: string;
+            lastAssistantMessage?: unknown[];
+        }): void;
+    };
+    agentView: {
+        schedule(): void;
+    };
+    messageObserver?: {
+        publish(session: unknown, event: unknown): void;
+    };
+    /** Drop a pre-step attachment registered by this channel for one message id
+     *  (input-delivery's `retireAttachment`); see the discard hook below.
+     *  Optional for direct/embed constructors that never emit inbox discards;
+     *  channel.ts always wires it. */
+    retireAttachment?(messageId: string): void;
+}): {
+    bind: () => void;
+};
+//# sourceMappingURL=binding-events.d.ts.map

package/lib/types/dsh-adapter/channel/binding-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding-events.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/binding-events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AACrF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,EAAE,KAAK,uBAAuB,EAAE,MAAM,iBAAiB,CAAA;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE;IACtD,KAAK,EAAE,YAAY,CAAA;IACnB,OAAO,EAAE,cAAc,CAAA;IACvB,KAAK,EAAE,YAAY,CAAA;IACnB;;;;iDAI6C;IAC7C,YAAY,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IACrC,gBAAgB,EAAE,gBAAgB,CAAA;IAClC,SAAS,EAAE,iBAAiB,CAAA;IAC5B,YAAY,EAAE;QAAE,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QAAC,SAAS,EAAE,iBAAiB,CAAA;KAAE,CAAA;IACrF,WAAW,EAAE;QAAE,WAAW,IAAI,IAAI,CAAC;QAAC,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAA;IAC5F,SAAS,EAAE,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAA;IACrD,SAAS,EAAE;QAAE,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;QAAC,aAAa,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC;QAAC,aAAa,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;QAAC,OAAO,CAAC,IAAI,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,OAAO,CAAA;SAAE,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,IAAI,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAC;YAAC,oBAAoB,CAAC,EAAE,OAAO,EAAE,CAAA;SAAE,GAAG,IAAI,CAAA;KAAE,CAAA;IACrX,SAAS,EAAE;QAAE,QAAQ,IAAI,IAAI,CAAA;KAAE,CAAA;IAC/B,eAAe,CAAC,EAAE;QAAE,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAA;IACrE;;;sCAGkC;IAClC,gBAAgB,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAC3C;gBAYkB,IAAI;EAiItB"}

package/lib/types/dsh-adapter/channel/binding-events.js

@@ -0,0 +1,170 @@
+/**
+ * The binding event router is the sole subscriber for a foreground Agent.
+ * It captures the binding generation at every listener entry; teardown is
+ * incremental and retained callbacks check that captured Agent/session pair
+ * before touching state. Transcript presentation remains exclusively owned by
+ * ChannelProjection.
+ */
+export function createBindingEvents(ctx, deps) {
+    const reconcileRetiredProjection = (status) => {
+        if (!deps.state.working)
+            return;
+        ctx.logger.warn(`dsh-tui: agent became ${status} while the channel still projected an open turn; releasing volatile UI gates`);
+        deps.inputConvergence.cancelInFlight = false;
+        deps.state.cancelPending = false;
+        deps.state.working = false;
+        deps.state.activeToolCount = 0;
+        deps.projector.settleStreaming();
+        deps.projector.updateSpinnerMode();
+    };
+    const bind = () => {
+        try {
+            deps.state.agentBindingGeneration = deps.binding.bind();
+            deps.inputConvergence.cancelInFlight = false;
+            deps.inputConvergence.interruptSeq += 1;
+            deps.seedActivity?.(deps.binding.agent.session);
+            deps.modelActions.selection.current = undefined;
+            deps.modelActions.selection.assembled = undefined;
+            if (deps.binding.agent.options?.model === undefined && deps.state.provider !== '' && deps.state.model !== '') {
+                deps.modelActions.selection.current = { provider: deps.state.provider, model: deps.state.model };
+            }
+            void deps.modelActions.applyPreferredEffort();
+            deps.modeActions.refreshMode();
+            const capture = deps.binding.capture();
+            const session = capture.agent.session;
+            const current = () => deps.owner.current() && deps.binding.isCurrent(capture);
+            const register = (dispose) => {
+                deps.binding.subscribe(dispose);
+                return dispose;
+            };
+            const on = (...args) => register(ctx.on(...args));
+            // Keep the upstream assembly/request pairing, but own each listener as
+            // soon as it is installed. The upstream combined disposer is too late
+            // if request registration throws, and its post-await assembly write is
+            // unsafe after a rebind (including A→B→A ABA).
+            const disposeAssembly = capture.agent.ctx.on('system-prompt/assemble', async (_assembly, _context, next) => {
+                const selected = deps.selection.current;
+                const assembled = await next();
+                if (!current())
+                    return assembled;
+                deps.selection.assembled = selected;
+                if (selected === undefined)
+                    return assembled;
+                return {
+                    ...assembled,
+                    variables: {
+                        ...assembled.variables,
+                        provider: selected.provider,
+                        model: selected.model,
+                    },
+                };
+            });
+            register(disposeAssembly);
+            const disposeRequest = capture.agent.ctx.on('agent/request', async (_payload, next) => {
+                const resolved = await next();
+                if (!current())
+                    return resolved;
+                const selected = deps.selection.assembled;
+                if (selected === undefined)
+                    return resolved;
+                const { reasoningEffort: _inheritedEffort, ...withoutInheritedEffort } = resolved;
+                return {
+                    ...withoutInheritedEffort,
+                    provider: selected.provider,
+                    model: selected.model,
+                    ...(selected.reasoningEffort === undefined ? {} : { reasoningEffort: selected.reasoningEffort }),
+                };
+            });
+            register(disposeRequest);
+            on('agent/status', ({ agent: subject, status }) => {
+                if (!current() || subject !== capture.agent)
+                    return;
+                deps.state.status = status;
+                if (status === 'idle')
+                    reconcileRetiredProjection('idle');
+                deps.state.emit();
+            });
+            on('agent/disposed', ({ agent: subject }) => {
+                if (!current() || subject !== capture.agent)
+                    return;
+                deps.state.status = 'disposed';
+                reconcileRetiredProjection('disposed');
+                deps.state.emit();
+            });
+            /**
+             * The inbox removed one message. Both events retire the pending
+             * preview, but ONLY a discard retires an attached-context entry:
+             * `agent/inbox/claimed` fires while the loop claims the batch, BEFORE
+             * the resident `agent/pre-step` listener can append the attachment —
+             * retiring there would delete the context before it is ever injected
+             * (dsh-agent-loop: `inbox.claim()` → claimed event → `agent/pre-step`).
+             */
+            const retirePending = (payload, alsoRetireAttachment = false) => {
+                if (!current() || payload.agent !== capture.agent)
+                    return;
+                const messageId = payload.message?.id;
+                if (typeof messageId !== 'string')
+                    return;
+                if (alsoRetireAttachment)
+                    deps.retireAttachment?.(messageId);
+                const before = deps.state.pending.length;
+                deps.state.pending = deps.state.pending.filter(item => item.id !== messageId);
+                if (deps.state.pending.length !== before)
+                    deps.state.emit();
+            };
+            on('agent/inbox/claimed', retirePending);
+            on('agent/inbox/discarded', payload => retirePending(payload, true));
+            on('session/event', (subject, event) => {
+                if (!current())
+                    return;
+                const isMainSession = subject === session;
+                if (!isMainSession && deps.subagents.onSessionEvent(subject, event))
+                    return;
+                if (!isMainSession)
+                    return;
+                deps.messageObserver?.publish(subject, event);
+                // Parent-log discovery events (`subagent/catalog`, workflow member
+                // edges) reach the dashboard through the same firehose; they are not
+                // transcript rows and render below remains untouched by them.
+                deps.subagents.onParentEvent?.(event);
+                deps.modeActions.onSessionEvent(subject, event);
+                deps.projector.renderEvent(event);
+                if (event.type === 'assistant/chunk')
+                    deps.state.emitStream();
+                else
+                    deps.state.emit();
+            });
+            // 0.1.5 live streaming: per-token chunks are transient attempt frames
+            // on this agent-scoped channel; the durable settlement still arrives
+            // through `session/event` above. Pre-0.1.5 hosts never emit it — the
+            // subscription simply stays silent there and chunks keep arriving as
+            // `assistant/chunk` session events.
+            on('agent/assistant-stream', ({ agent: subject, frame }) => {
+                if (!current())
+                    return;
+                if (subject !== capture.agent) {
+                    deps.subagents.onStreamFrame?.(subject, frame);
+                    return;
+                }
+                deps.projector.renderStreamFrame(frame);
+                if (frame.type === 'chunk')
+                    deps.state.emitStream();
+                else if (frame.type === 'end')
+                    deps.state.emit();
+            });
+            on('subagent/start', (info) => {
+                if (current())
+                    deps.subagents.onStart(info);
+            });
+            on('subagent/end', (info) => {
+                if (current())
+                    deps.subagents.onEnd(info);
+            });
+        }
+        catch (error) {
+            deps.owner.dispose();
+            throw error;
+        }
+    };
+    return { bind };
+}

package/lib/types/dsh-adapter/channel/binding.d.ts

@@ -0,0 +1,58 @@
+import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent';
+import type { ChannelOwner } from './owner.js';
+export interface BindingCapture {
+    readonly agent: Agent;
+    readonly generation: number;
+}
+export interface BindingCommit {
+    readonly agent: Agent;
+    readonly handle: AgentHandle | undefined;
+    readonly generation: number;
+}
+type PreviousDisposition = 'dispose' | 'park';
+/**
+ * Sole writer of the attached Agent/handle identity and binding generation.
+ *
+ * A prepared handle remains owned by this cell until its synchronous adoption
+ * tail returns.  The tail is deliberately callback-shaped: it cannot leave a
+ * committed identity waiting for a microtask watchdog to infer whether setup
+ * completed, and a throw always revokes the transaction immediately.
+ */
+export declare function createChannelBinding(initial: Agent, handle: AgentHandle | undefined, owner: ChannelOwner): {
+    readonly agent: Agent;
+    readonly handle: AgentHandle | undefined;
+    readonly generation: number;
+    capture(): BindingCapture;
+    isCurrent(capture: BindingCapture): boolean;
+    /**
+     * Create a candidate without giving it authority over the live binding.
+     *
+     * When the capture went stale the candidate is closed and the rejection
+     * WAITS for that close. The caller's `abandon(handle)` can no longer see the
+     * handle — it was never in `pending` — so waiting here is the only way the
+     * handle is known to have stopped writing before the caller gives its
+     * ledger reservation back.
+     */
+    prepare(capture: BindingCapture, create: () => Promise<AgentHandle>): Promise<AgentHandle>;
+    /**
+     * Dispose an uncommitted candidate exactly once and WAIT for the close.
+     *
+     * Waiting is the point: callers use this on the path where they are about
+     * to give a cross-process ledger reservation back, and that reservation may
+     * only be released once the handle has actually stopped writing. A live
+     * handle that this cell never owned is inert here.
+     */
+    abandon(candidate: AgentHandle): Promise<void>;
+    /** A registry may retain an agent while its async handle close drains. */
+    waitForDisposal(sessionId: string): Promise<void>;
+    /** Perform one explicit synchronous prepared-handle adoption transaction. */
+    adopt: <T>(candidate: AgentHandle, capture: BindingCapture, tail: (previous: BindingCommit, disposition: (next: PreviousDisposition) => void) => T) => T;
+    /** Perform one explicit synchronous already-live-agent adoption transaction. */
+    switchTo: <T>(agent: Agent, nextHandle: AgentHandle | undefined, tail: (previous: BindingCommit, disposition: (next: PreviousDisposition) => void) => T) => T;
+    bind(): number;
+    subscribe(dispose: () => void): void;
+    clearSubscriptions: (afterEach?: () => void) => unknown;
+};
+export type ChannelBinding = ReturnType<typeof createChannelBinding>;
+export {};
+//# sourceMappingURL=binding.d.ts.map

package/lib/types/dsh-adapter/channel/binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/binding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,KAAK,mBAAmB,GAAG,SAAS,GAAG,MAAM,CAAA;AAE7C;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,KAAK,EAAE,YAAY;;;;eAsM1F,cAAc;uBACN,cAAc;IAEjC;;;;;;;;OAQG;qBACoB,cAAc,UAAU,MAAM,OAAO,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC;IAkBhG;;;;;;;OAOG;uBACsB,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD,0EAA0E;+BACzC,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvD,6EAA6E;YA7JhE,CAAC,aACH,WAAW,WACb,cAAc,QACjB,CAAC,QAAQ,EAAE,aAAa,EAAE,WAAW,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,IAAI,KAAK,CAAC,KACrF,CAAC;IA2JF,gFAAgF;eAlGhE,CAAC,SACV,KAAK,cACA,WAAW,GAAG,SAAS,QAC7B,CAAC,QAAQ,EAAE,aAAa,EAAE,WAAW,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,IAAI,KAAK,CAAC,KACrF,CAAC;;uBA4GiB,MAAM,IAAI;qCAvNS,MAAM,IAAI,KAAG,OAAO;EA0N7D;AAED,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAA"}

package/lib/types/dsh-adapter/channel/binding.js

@@ -0,0 +1,287 @@
+/**
+ * Sole writer of the attached Agent/handle identity and binding generation.
+ *
+ * A prepared handle remains owned by this cell until its synchronous adoption
+ * tail returns.  The tail is deliberately callback-shaped: it cannot leave a
+ * committed identity waiting for a microtask watchdog to infer whether setup
+ * completed, and a throw always revokes the transaction immediately.
+ */
+export function createChannelBinding(initial, handle, owner) {
+    let currentAgent = initial;
+    let currentHandle = handle;
+    let generation = 0;
+    let started = false;
+    let subscriptions = [];
+    let handoff;
+    const pending = new Map();
+    /**
+     * The in-flight (or finished) close of a handle this cell owns, keyed by the
+     * handle. A Promise rather than a "has it started" flag, because the callers
+     * that matter need to know when the handle has actually STOPPED writing: a
+     * ledger reservation is only safe to give back after that, and a second
+     * `dispose()` must not start a parallel close.
+     */
+    const closing = new WeakMap();
+    const closingSessions = new Map();
+    /** Close `candidate` exactly once; the result resolves however it ends. */
+    const dispose = (candidate) => {
+        const started = closing.get(candidate);
+        if (started !== undefined)
+            return started;
+        // Kicked off SYNCHRONOUSLY: revocation is part of a synchronous transaction
+        // boundary, and a caller that abandons a candidate may check it right away.
+        // Only the waiting is deferred, never the call.
+        let close;
+        try {
+            close = Promise.resolve(candidate.dispose()).catch(() => undefined);
+        }
+        catch {
+            close = Promise.resolve();
+        }
+        closing.set(candidate, close);
+        const id = String(candidate.agent.session.id);
+        closingSessions.set(id, close);
+        void close.then(() => {
+            if (closingSessions.get(id) === close)
+                closingSessions.delete(id);
+        });
+        return close;
+    };
+    const disposePending = (candidate) => {
+        if (pending.delete(candidate))
+            return dispose(candidate);
+        // Already un-pended (a revocation path took it out from under the caller):
+        // hand back the close that is already running, so a caller that HAS to
+        // wait — one about to give a ledger reservation back — still can.
+        return closing.get(candidate);
+    };
+    const clearSubscriptions = (afterEach) => {
+        const active = subscriptions.splice(0);
+        let failure;
+        // A bad unsubscriber must not prevent the rest of a binding's cleanup.
+        for (const unsubscribe of active) {
+            try {
+                unsubscribe();
+            }
+            catch (error) {
+                failure ??= error;
+            }
+            // Every unsubscriber is external code and can revoke the owner or try a
+            // rival handoff. Record that state before running the next cleanup.
+            try {
+                afterEach?.();
+            }
+            catch (error) {
+                failure ??= error;
+            }
+        }
+        return failure;
+    };
+    const isCaptureCurrent = (capture) => owner.current() && capture.agent === currentAgent && capture.generation === generation;
+    /**
+     * Start a close without waiting for it. The callers below are synchronous
+     * transaction boundaries — they must not turn into awaits — but the close
+     * itself stays observable through {@link dispose}, so a caller that DOES have
+     * to wait (an `abandon` handing a ledger reservation back) still can.
+     */
+    const startClose = (close) => {
+        void close;
+    };
+    const assertPrepared = (candidate, capture) => {
+        if (pending.get(candidate) !== capture || !isCaptureCurrent(capture)) {
+            startClose(disposePending(candidate));
+            throw new Error('dsh-tui: Channel binding changed before adoption');
+        }
+    };
+    const settlePrevious = (previous, disposition) => {
+        // Parking deliberately transfers ownership to the caller's background
+        // ledger. Disposal is centralised here so no adoption tail can double-call
+        // an old handle while its transaction is being revoked. Neither path waits:
+        // an ordinary session switch must not block on the handle it just left.
+        if (disposition === 'dispose' && previous.handle !== undefined && previous.handle !== currentHandle) {
+            startClose(dispose(previous.handle));
+        }
+    };
+    owner.own(clearSubscriptions);
+    owner.own(() => { for (const candidate of [...pending.keys()])
+        startClose(disposePending(candidate)); });
+    const adopt = (candidate, capture, tail) => {
+        if (handoff !== undefined) {
+            // Mark the outer transaction superseded as well as rejecting this one;
+            // letting its tail return success after a reentrant handoff attempt
+            // would publish a binding whose cleanup authority was contested.
+            handoff = undefined;
+            disposePending(candidate);
+            throw new Error('dsh-tui: Channel binding handoff is already in progress');
+        }
+        assertPrepared(candidate, capture);
+        const token = Symbol('channel-binding-handoff');
+        handoff = token;
+        const previous = { agent: currentAgent, handle: currentHandle, generation };
+        let disposition;
+        const decidePrevious = (next) => {
+            if (disposition === undefined || disposition === next) {
+                disposition = next;
+                return;
+            }
+            throw new Error('dsh-tui: Channel binding previous disposition changed');
+        };
+        let succeeded = false;
+        try {
+            const cleanupFailure = clearSubscriptions(() => {
+                if (handoff !== token || !isCaptureCurrent(capture) || pending.get(candidate) !== capture) {
+                    throw new Error('dsh-tui: Channel binding changed before adoption');
+                }
+            });
+            if (cleanupFailure !== undefined)
+                throw cleanupFailure;
+            // Unsubscription is external code: it can revoke the owner or attempt a
+            // rival adoption. Never write a candidate after either event.
+            if (handoff !== token)
+                throw new Error('dsh-tui: Channel binding handoff was superseded');
+            assertPrepared(candidate, capture);
+            pending.delete(candidate);
+            currentAgent = candidate.agent;
+            currentHandle = candidate;
+            generation += 1;
+            const result = tail(previous, decidePrevious);
+            // Tail callbacks include notifier/listener code and therefore remain a
+            // synchronous reentrancy boundary even though they contain no await.
+            if (handoff !== token || !owner.current() || currentHandle !== candidate) {
+                throw new Error('dsh-tui: Channel binding changed during adoption');
+            }
+            succeeded = true;
+            return result;
+        }
+        catch (error) {
+            // This candidate is transaction-owned, unlike the baseline live handle
+            // which ordinary UI owner teardown only unsubscribes from.
+            if (currentHandle === candidate) {
+                currentHandle = undefined;
+            }
+            startClose(dispose(candidate));
+            owner.dispose();
+            throw error;
+        }
+        finally {
+            settlePrevious(previous, succeeded ? disposition ?? 'dispose' : 'dispose');
+            if (handoff === token)
+                handoff = undefined;
+        }
+    };
+    const switchTo = (agent, nextHandle, tail) => {
+        owner.assertActive();
+        if (handoff !== undefined) {
+            handoff = undefined;
+            throw new Error('dsh-tui: Channel binding handoff is already in progress');
+        }
+        const token = Symbol('channel-binding-handoff');
+        handoff = token;
+        const previous = { agent: currentAgent, handle: currentHandle, generation };
+        let disposition;
+        const decidePrevious = (next) => {
+            if (disposition === undefined || disposition === next) {
+                disposition = next;
+                return;
+            }
+            throw new Error('dsh-tui: Channel binding previous disposition changed');
+        };
+        let succeeded = false;
+        try {
+            const cleanupFailure = clearSubscriptions(() => {
+                if (handoff !== token || !owner.current())
+                    throw new Error('dsh-tui: Channel binding changed during adoption');
+            });
+            if (cleanupFailure !== undefined)
+                throw cleanupFailure;
+            if (handoff !== token || !owner.current())
+                throw new Error('dsh-tui: Channel binding changed during adoption');
+            currentAgent = agent;
+            currentHandle = nextHandle;
+            generation += 1;
+            const result = tail(previous, decidePrevious);
+            if (handoff !== token || !owner.current() || currentAgent !== agent || currentHandle !== nextHandle) {
+                throw new Error('dsh-tui: Channel binding changed during adoption');
+            }
+            succeeded = true;
+            return result;
+        }
+        catch (error) {
+            // An already-live agent is not a prepared candidate.  Revocation leaves
+            // its owner to decide disposal, preserving the baseline teardown rule.
+            owner.dispose();
+            throw error;
+        }
+        finally {
+            settlePrevious(previous, succeeded ? disposition ?? 'dispose' : 'dispose');
+            if (handoff === token)
+                handoff = undefined;
+        }
+    };
+    return {
+        get agent() { return currentAgent; },
+        get handle() { return currentHandle; },
+        get generation() { return generation; },
+        capture() { return { agent: currentAgent, generation }; },
+        isCurrent(capture) { return isCaptureCurrent(capture); },
+        /**
+         * Create a candidate without giving it authority over the live binding.
+         *
+         * When the capture went stale the candidate is closed and the rejection
+         * WAITS for that close. The caller's `abandon(handle)` can no longer see the
+         * handle — it was never in `pending` — so waiting here is the only way the
+         * handle is known to have stopped writing before the caller gives its
+         * ledger reservation back.
+         */
+        async prepare(capture, create) {
+            owner.assertActive();
+            if (!isCaptureCurrent(capture))
+                throw new Error('dsh-tui: Channel binding changed before preparation');
+            const candidate = await create();
+            if (!isCaptureCurrent(capture)) {
+                await dispose(candidate);
+                throw new Error('dsh-tui: Channel binding changed during preparation');
+            }
+            pending.set(candidate, capture);
+            // Owner disposal may synchronously occur through embedding hooks while
+            // ownership is registered; verify the pending entry itself as well.
+            if (!isCaptureCurrent(capture) || pending.get(candidate) !== capture) {
+                await disposePending(candidate);
+                throw new Error('dsh-tui: Channel binding changed during preparation');
+            }
+            return candidate;
+        },
+        /**
+         * Dispose an uncommitted candidate exactly once and WAIT for the close.
+         *
+         * Waiting is the point: callers use this on the path where they are about
+         * to give a cross-process ledger reservation back, and that reservation may
+         * only be released once the handle has actually stopped writing. A live
+         * handle that this cell never owned is inert here.
+         */
+        async abandon(candidate) {
+            await disposePending(candidate);
+        },
+        /** A registry may retain an agent while its async handle close drains. */
+        async waitForDisposal(sessionId) {
+            await closingSessions.get(sessionId);
+        },
+        /** Perform one explicit synchronous prepared-handle adoption transaction. */
+        adopt,
+        /** Perform one explicit synchronous already-live-agent adoption transaction. */
+        switchTo,
+        // bindAgent is still responsible for constructing the typed subscriptions.
+        // Initial activation establishes generation 1; later rebinds have already
+        // advanced the generation inside their adoption transaction.
+        bind() {
+            owner.assertActive();
+            if (!started) {
+                started = true;
+                generation += 1;
+            }
+            return generation;
+        },
+        subscribe(dispose) { subscriptions.push(dispose); },
+        clearSubscriptions,
+    };
+}

package/lib/types/dsh-adapter/channel/command-completions.d.ts

@@ -0,0 +1,29 @@
+import { type CommandCompletionNode } from '../../commands.js';
+import { listThemeCatalog } from '../../themeCatalog.js';
+import type { ChannelState } from './types.js';
+/** Owns slash completion composition and cache warming; it has no lifecycle effects. */
+export declare function createCommandCompletions(deps: {
+    state: () => ChannelState;
+    themeHost: Parameters<typeof listThemeCatalog>[0];
+    commandTrees?: {
+        children(path: readonly string[]): readonly CommandCompletionNode[];
+    };
+    workspaceCommands(): readonly {
+        name: string;
+        aliases?: readonly string[];
+        description?: string;
+    }[];
+    model: {
+        warmModelNodes(): void;
+        modelNodes(): readonly CommandCompletionNode[];
+        warmPresetOptions(): void;
+        presetOptions(): readonly {
+            id: string;
+            description?: string;
+            name?: string;
+            isDefault?: boolean;
+        }[];
+        warmEffortLevels(): void;
+    };
+}): (input: string) => import("../../commands.js").CommandCompletion[];
+//# sourceMappingURL=command-completions.d.ts.map

package/lib/types/dsh-adapter/channel/command-completions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-completions.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/command-completions.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8C,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AAI1G,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,wFAAwF;AACxF,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,KAAK,EAAE,MAAM,YAAY,CAAA;IACzB,SAAS,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAA;IACjD,YAAY,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,qBAAqB,EAAE,CAAA;KAAE,CAAA;IACtF,iBAAiB,IAAI,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IACnG,KAAK,EAAE;QACL,cAAc,IAAI,IAAI,CAAA;QACtB,UAAU,IAAI,SAAS,qBAAqB,EAAE,CAAA;QAC9C,iBAAiB,IAAI,IAAI,CAAA;QACzB,aAAa,IAAI,SAAS;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,SAAS,CAAC,EAAE,OAAO,CAAA;SAAE,EAAE,CAAA;QACpG,gBAAgB,IAAI,IAAI,CAAA;KACzB,CAAA;CACF,IAES,OAAO,MAAM,qDAyEtB"}