@deepseek-harness-tui/dsh-tui 0.12.0 → 0.14.0

package/lib/types/dsh-adapter/panels.js

@@ -0,0 +1,407 @@
+/**
+ * ctx.tuiPanels — 插件侧栏 Panel 服务（设计文档 §8/§18，v2.1 修订，Phase 6）。
+ *
+ * 与 tuiStatus/tuiScenes 同一接缝家族：一份 Cordis-free 的进程级 store
+ * （components/sidePanel/PanelStore，注册/badge/错误隔离）+ 一层薄的
+ * Cordis 服务做准入（requirePluginCaller → activationFiber owner →
+ * bindCallerEffect 撤下 → 能力 shadow policy → 重复 id
+ * DUPLICATE_CONTRIBUTION_ID → Object.freeze descriptor）。
+ *
+ * 本阶段范围（§18.2 简化版）：
+ * - register：宿主自动加 '<pluginId>:' 前缀；mountPolicy 强制 'active'；
+ *   minColumns 默认 28；预算 = 每插件 ≤4 个 / 全局 ≤32 个。
+ * - list：只读摘要（id/title/source，不含组件）。
+ * - open/close：仅自己注册的 id；open 为 mutate 且限速（每插件每 5s 至多
+ *   1 次，超过丢弃并记 ledger）；UI 触达经 panelBridge（useSidePanel 订阅）。
+ * - badge：仅自己注册的 id → panelStore.setBadge。
+ * - subscribe：仅涉及自己 Panel 的事件（本阶段 registered/unregistered/
+ *   badge/error/disabled；opened/closed/focused/blurred/sidebar-toggled 事件
+ *   源在 useSidePanel 侧，留 TODO）。
+ * - compact：descriptor 校验 + 存档，渲染槽不挂载（TODO §18.1）。
+ */
+import { Service } from '@deepseek-ai/cordis';
+import { cleanScalarText } from './sanitize.js';
+import { activationFiber, assertCallerContext, bindCallerEffect, compositionRoot, concreteService, requirePluginCaller } from './host-access.js';
+import { componentIdentityOf } from './component-identity.js';
+import { assertCapabilityShadowPolicy, } from '../adapter/kernel/runtime.js';
+import { adapterRuntimeFor } from '../adapter/kernel/runtime-context.js';
+import { panelStore } from '../components/sidePanel/PanelStore.js';
+import { makePluginPanelComponent } from '../components/sidePanel/pluginPanelAdapter.js';
+import { panelBridgeRequests } from '../components/sidePanel/panelBridge.js';
+import { applySidePanelPanels, getSidePanelPanels, parseSidePanelIds } from '../tuiDisplayPrefs.js';
+import { stringWidth } from '../ink/stringWidth.js';
+import { countPanelsOwnedBy, countPluginPanels, deletePanelOwnerRecord, getPanelOwnerRecord, setPanelOwnerRecord, } from './panel-runtime-registry.js';
+/** 插件 Panel API 版本（§18.2）：descriptor.apiVersion 必须精确匹配。 */
+export const TUI_PANEL_API_VERSION = 1;
+// 单段小写 slug（宿主自动加 '<pluginId>:' 前缀形成最终 panel id）。
+const SUB_ID_PATTERN = /^[a-z][a-z0-9_-]*$/u;
+const TITLE_CELLS = 80;
+const MIN_COLUMNS_FLOOR = 12;
+const MIN_COLUMNS_CEIL = 64;
+const DEFAULT_MIN_COLUMNS = 28;
+/** 每插件 Panel 预算（§18.4）。 */
+export const MAX_PANELS_PER_PLUGIN = 4;
+/** 全局插件 Panel 注册预算（§18.4）。 */
+export const MAX_PLUGIN_PANELS_TOTAL = 32;
+/** open() 限速窗口：每插件每窗口至多 1 次。 */
+export const PANEL_OPEN_RATE_LIMIT_MS = 5_000;
+export const name = 'dsh-tui-panels';
+const panelStates = new WeakMap();
+function panelStateFor(runtime) {
+    const state = panelStates.get(concreteService(runtime));
+    if (state === undefined)
+        throw new Error('tuiPanels host state is unavailable');
+    return state;
+}
+/** 无 Component identity 的裸挂载（测试夹具）需要一个稳定命名空间：
+ * 按 activation fiber 发号。 */
+const fallbackPluginIds = new WeakMap();
+let fallbackSeq = 0;
+function pluginIdFor(caller, owner) {
+    const identity = componentIdentityOf(caller);
+    if (identity !== undefined && /^[a-z][a-z0-9_-]*$/u.test(identity.componentId)) {
+        return identity.componentId;
+    }
+    let fallback = fallbackPluginIds.get(owner);
+    if (fallback === undefined) {
+        fallbackSeq += 1;
+        fallback = 'act' + String(fallbackSeq);
+        fallbackPluginIds.set(owner, fallback);
+    }
+    return fallback;
+}
+/**
+ * ctx.tuiPanels —— 插件侧栏 Panel 准入服务。拒绝一律 warn + 返回
+ * undefined/false（与 tuiStatus.registerView 同语义），绝不抛给插件。
+ */
+export class TuiPanelRuntime extends Service {
+    constructor(ctx) {
+        super(ctx, 'tuiPanels');
+        compositionRoot(ctx);
+        const state = {
+            runtime: adapterRuntimeFor(ctx),
+            host: undefined,
+        };
+        state.host = Object.freeze({
+            register(descriptor) {
+                const finalId = String(descriptor.id ?? '');
+                if (!finalId.includes(':') || panelStore.get(finalId) !== undefined) {
+                    throw new Error('invalid or duplicate host panel id: ' + finalId);
+                }
+                const definition = {
+                    id: finalId,
+                    title: String(descriptor.title ?? finalId),
+                    source: 'plugin',
+                    pluginId: 'dsh-tui-host',
+                    mountPolicy: 'active',
+                    minColumns: DEFAULT_MIN_COLUMNS,
+                    component: () => null,
+                };
+                return panelStore.register(definition, 'builtin');
+            },
+            list() {
+                return panelStore.list()
+                    .filter(entry => entry.definition.source === 'plugin')
+                    .map(entry => Object.freeze({ id: entry.definition.id, title: entry.definition.title ?? entry.definition.id, source: 'plugin' }));
+            },
+            open(id) {
+                return panelBridgeRequests.request('open', id);
+            },
+            close(id) {
+                return panelBridgeRequests.request('close', id);
+            },
+            subscribe(listener) {
+                return panelStore.subscribe(event => {
+                    const entry = panelStore.get(event.id);
+                    if (entry?.definition.source === 'plugin')
+                        listener(event);
+                });
+            },
+        });
+        panelStates.set(this, state);
+    }
+    /**
+     * 注册一个侧栏 Panel。成功返回 cleanup-aware disposer；拒绝 warn 并
+     * 返回 undefined（feature-detect 可辨）。identity 语义与 tuiStatus
+     * 相同（只喂 effect ledger 的 pluginId）。
+     */
+    register(descriptor, identity) {
+        assertCapabilityShadowPolicy('host.panels.register', panelStateFor(this).runtime.mode, panelStateFor(this).runtime.slices);
+        let caller;
+        try {
+            caller = requirePluginCaller(this.ctx, 'tuiPanels.register', this);
+        }
+        catch {
+            this.ctx.logger.warn('dsh-tui: tuiPanels.register requires a live non-root plugin activation');
+            return undefined;
+        }
+        if (identity !== undefined) {
+            try {
+                assertCallerContext(caller, identity, 'tuiPanels.register');
+            }
+            catch {
+                caller.logger.warn('dsh-tui: tuiPanels.register rejected an identity belonging to another activation');
+                return undefined;
+            }
+        }
+        const owner = activationFiber(caller);
+        if (owner === undefined) {
+            caller.logger.warn('dsh-tui: tuiPanels.register requires a live activation owner');
+            return undefined;
+        }
+        const ledger = caller.get('tuiEffectLedger');
+        const raw = descriptor;
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+            caller.logger.warn('dsh-tui: tuiPanels.register rejected an invalid descriptor');
+            return undefined;
+        }
+        const d = raw;
+        if (d.apiVersion !== TUI_PANEL_API_VERSION) {
+            caller.logger.warn('dsh-tui: tuiPanels.register rejected a descriptor with apiVersion ' + String(d.apiVersion) + ' (expected ' + TUI_PANEL_API_VERSION + ')');
+            return undefined;
+        }
+        if (typeof d.id !== 'string' || !SUB_ID_PATTERN.test(d.id)) {
+            caller.logger.warn('dsh-tui: tuiPanels.register rejected an invalid panel id');
+            return undefined;
+        }
+        if (typeof d.title !== 'string' || cleanScalarText(d.title, TITLE_CELLS).length === 0) {
+            caller.logger.warn('dsh-tui: tuiPanels.register rejected "' + d.id + '" — title must be a non-empty string');
+            return undefined;
+        }
+        if (d.icon !== undefined && (typeof d.icon !== 'string' || stringWidth(d.icon) !== 1)) {
+            caller.logger.warn('dsh-tui: tuiPanels.register rejected "' + d.id + '" — icon display width must be 1');
+            return undefined;
+        }
+        if (d.component !== undefined && typeof d.component !== 'function') {
+            caller.logger.warn('dsh-tui: tuiPanels.register rejected "' + d.id + '" — component must be a function');
+            return undefined;
+        }
+        let compactMaxRows;
+        let compactComponent;
+        if (d.compact !== undefined) {
+            if (typeof d.compact !== 'object' || d.compact === null) {
+                caller.logger.warn('dsh-tui: tuiPanels.register rejected "' + d.id + '" — invalid compact descriptor');
+                return undefined;
+            }
+            const rows = d.compact.maxRows;
+            if (typeof rows !== 'number' || !Number.isInteger(rows) || rows < 1 || rows > 3) {
+                caller.logger.warn('dsh-tui: tuiPanels.register rejected "' + d.id + '" — compact.maxRows must be an integer from 1 to 3');
+                return undefined;
+            }
+            compactComponent = d.compact.component;
+            if (typeof compactComponent !== 'function') {
+                caller.logger.warn('dsh-tui: tuiPanels.register rejected "' + d.id + '" — compact.component must be a function');
+                return undefined;
+            }
+            compactMaxRows = rows;
+        }
+        if (d.component === undefined && d.compact === undefined) {
+            caller.logger.warn('dsh-tui: tuiPanels.register rejected "' + d.id + '" — at least one of component/compact is required');
+            return undefined;
+        }
+        if (d.minColumns !== undefined
+            && (typeof d.minColumns !== 'number' || !Number.isInteger(d.minColumns) || d.minColumns < MIN_COLUMNS_FLOOR || d.minColumns > MIN_COLUMNS_CEIL)) {
+            caller.logger.warn('dsh-tui: tuiPanels.register rejected "' + d.id + '" — minColumns must be an integer from ' + MIN_COLUMNS_FLOOR + ' to ' + MIN_COLUMNS_CEIL);
+            return undefined;
+        }
+        if (d.order !== undefined && (typeof d.order !== 'number' || !Number.isFinite(d.order))) {
+            caller.logger.warn('dsh-tui: tuiPanels.register rejected "' + d.id + '" — order must be a finite number');
+            return undefined;
+        }
+        const pluginId = pluginIdFor(caller, owner);
+        const finalId = pluginId + ':' + d.id;
+        if (panelStore.get(finalId) !== undefined) {
+            caller.logger.warn('dsh-tui: tuiPanels.register rejected "' + finalId + '" — already registered');
+            ledger?.record({ operation: 'bind', resource: { kind: 'panel', id: finalId }, result: 'failed', errorCode: 'DUPLICATE_CONTRIBUTION_ID' }, identity);
+            return undefined;
+        }
+        if (countPanelsOwnedBy(owner) >= MAX_PANELS_PER_PLUGIN) {
+            caller.logger.warn('dsh-tui: tuiPanels.register rejected "' + finalId + '" — a plugin may register at most ' + MAX_PANELS_PER_PLUGIN + ' panels');
+            ledger?.record({ operation: 'bind', resource: { kind: 'panel', id: finalId }, result: 'failed', errorCode: 'PANEL_BUDGET_EXCEEDED' }, identity);
+            return undefined;
+        }
+        if (countPluginPanels() >= MAX_PLUGIN_PANELS_TOTAL) {
+            caller.logger.warn('dsh-tui: tuiPanels.register rejected "' + finalId + '" — ' + MAX_PLUGIN_PANELS_TOTAL + ' plugin panels are already registered');
+            ledger?.record({ operation: 'bind', resource: { kind: 'panel', id: finalId }, result: 'failed', errorCode: 'PANEL_BUDGET_EXCEEDED' }, identity);
+            return undefined;
+        }
+        const title = cleanScalarText(d.title, TITLE_CELLS);
+        const definition = Object.freeze({
+            id: finalId,
+            title,
+            icon: d.icon,
+            order: d.order,
+            minColumns: d.minColumns ?? DEFAULT_MIN_COLUMNS,
+            source: 'plugin',
+            pluginId,
+            // v2.1：插件 Panel 强制 active 挂载（防常驻面板烧资源）。
+            mountPolicy: 'active',
+            component: makePluginPanelComponent(finalId, (d.component ?? (() => null))),
+            // compact 本阶段只校验不挂载（渲染槽 TODO §18.1）。
+            compact: compactMaxRows === undefined ? undefined : { maxRows: compactMaxRows, component: () => null },
+        });
+        const ownerTag = { pluginId, activation: owner };
+        const unregister = panelStore.register(definition, ownerTag);
+        setPanelOwnerRecord(finalId, { caller, owner, pluginId, lastOpenAt: 0 });
+        // 注册即入侧栏启用列表（PanelBar 可见；/panel 与 /settings 仍可移除）。
+        enablePanelIdInStore(finalId);
+        let disposed = false;
+        let ownerCleanup;
+        const dispose = () => {
+            if (disposed)
+                return;
+            disposed = true;
+            // 先撤 store（unregistered 事件还需 owner record 做订阅过滤），再清
+            // owner 数据与启用列表。
+            unregister();
+            deletePanelOwnerRecord(finalId);
+            disablePanelIdInStore(finalId);
+            caller.get('tuiEffectLedger')?.record({ operation: 'release', resource: { kind: 'panel', id: finalId }, result: 'applied' }, identity);
+            const cleanup = ownerCleanup;
+            ownerCleanup = undefined;
+            cleanup?.();
+        };
+        const bound = bindCallerEffect(caller, dispose, cleanup => {
+            ownerCleanup = cleanup;
+        });
+        if (!bound)
+            return undefined;
+        ledger?.record({ operation: 'bind', resource: { kind: 'panel', id: finalId }, result: 'applied' }, identity);
+        return dispose;
+    }
+    /** 只读摘要（仅自己注册的 Panel；不含组件）。 */
+    list() {
+        assertCapabilityShadowPolicy('host.panels.list', panelStateFor(this).runtime.mode, panelStateFor(this).runtime.slices);
+        const caller = requirePluginCaller(this.ctx, 'tuiPanels.list', this);
+        const owner = activationFiber(caller);
+        if (owner === undefined)
+            return [];
+        return panelStore.list()
+            .filter(entry => entry.definition.source === 'plugin' && getPanelOwnerRecord(entry.definition.id)?.owner === owner)
+            .map(entry => Object.freeze({
+            id: entry.definition.id,
+            title: entry.definition.title ?? entry.definition.id,
+            source: 'plugin',
+        }));
+    }
+    /**
+     * 打开自己注册的 Panel（展开侧栏并聚焦）。mutate + 限速：每插件每
+     * 5s 至多 1 次，超限丢弃并记 ledger。返回 false = 未注册/不属于自己的
+     * id、超限、或没有活的 Chat 控制器消费请求。
+     */
+    open(id) {
+        assertCapabilityShadowPolicy('host.panels.open', panelStateFor(this).runtime.mode, panelStateFor(this).runtime.slices);
+        const caller = requirePluginCaller(this.ctx, 'tuiPanels.open', this);
+        const owner = activationFiber(caller);
+        if (owner === undefined)
+            return false;
+        const record = getPanelOwnerRecord(String(id ?? ''));
+        if (record === undefined || record.owner !== owner) {
+            caller.logger.warn('dsh-tui: tuiPanels.open rejected "' + String(id) + '" — not registered by this activation');
+            return false;
+        }
+        // 无 Chat 消费者：直接 false，不消耗限速窗口（请求从未送达）。
+        if (!panelBridgeRequests.hasConsumer())
+            return false;
+        const now = Date.now();
+        if (now - record.lastOpenAt < PANEL_OPEN_RATE_LIMIT_MS) {
+            caller.logger.warn('dsh-tui: tuiPanels.open dropped "' + String(id) + '" — rate limited to one open per ' + PANEL_OPEN_RATE_LIMIT_MS + 'ms');
+            caller.get('tuiEffectLedger')?.record({ operation: 'bind', resource: { kind: 'panel', id: String(id) }, result: 'failed', errorCode: 'RATE_LIMITED' });
+            return false;
+        }
+        if (!panelBridgeRequests.request('open', String(id)))
+            return false;
+        record.lastOpenAt = now;
+        return true;
+    }
+    /** 关闭自己注册的 Panel：若它是当前 active Panel，则收起侧栏。 */
+    close(id) {
+        assertCapabilityShadowPolicy('host.panels.close', panelStateFor(this).runtime.mode, panelStateFor(this).runtime.slices);
+        const caller = requirePluginCaller(this.ctx, 'tuiPanels.close', this);
+        const owner = activationFiber(caller);
+        if (owner === undefined)
+            return false;
+        const record = getPanelOwnerRecord(String(id ?? ''));
+        if (record === undefined || record.owner !== owner) {
+            caller.logger.warn('dsh-tui: tuiPanels.close rejected "' + String(id) + '" — not registered by this activation');
+            return false;
+        }
+        return panelBridgeRequests.request('close', String(id));
+    }
+    /** 设置/清除自己 Panel 的 badge。 */
+    badge(id, badge) {
+        assertCapabilityShadowPolicy('host.panels.badge', panelStateFor(this).runtime.mode, panelStateFor(this).runtime.slices);
+        const caller = requirePluginCaller(this.ctx, 'tuiPanels.badge', this);
+        const owner = activationFiber(caller);
+        if (owner === undefined)
+            return false;
+        const record = getPanelOwnerRecord(String(id ?? ''));
+        if (record === undefined || record.owner !== owner) {
+            caller.logger.warn('dsh-tui: tuiPanels.badge rejected "' + String(id) + '" — not registered by this activation');
+            return false;
+        }
+        if (badge === null) {
+            panelStore.clearBadge(String(id));
+            return true;
+        }
+        if (typeof badge !== 'object' || !['info', 'warning', 'error'].includes(String(badge.level))
+            || typeof badge.unread !== 'number') {
+            caller.logger.warn('dsh-tui: tuiPanels.badge rejected an invalid badge');
+            return false;
+        }
+        panelStore.setBadge(String(id), {
+            level: badge.level,
+            unread: badge.unread,
+        });
+        return true;
+    }
+    /** 订阅涉及自己 Panel 的事件（本阶段 registered/unregistered/badge/
+     * error/disabled；opened/closed/focused/blurred/sidebar-toggled TODO）。 */
+    subscribe(listener) {
+        assertCapabilityShadowPolicy('host.panels.subscribe', panelStateFor(this).runtime.mode, panelStateFor(this).runtime.slices);
+        const caller = requirePluginCaller(this.ctx, 'tuiPanels.subscribe', this);
+        const owner = activationFiber(caller);
+        if (owner === undefined || typeof listener !== 'function')
+            return () => { };
+        const wrapped = (event) => {
+            const record = getPanelOwnerRecord(event.id);
+            if (record === undefined || record.owner !== owner)
+                return;
+            try {
+                listener(event);
+            }
+            catch (error) {
+                caller.logger.warn('dsh-tui: tuiPanels listener failed: ' + (error instanceof Error ? error.message : String(error)));
+            }
+        };
+        const dispose = panelStore.subscribe(wrapped);
+        bindCallerEffect(caller, dispose);
+        return dispose;
+    }
+}
+// ── 启用列表接线（tuiDisplayPrefs 的 panels CSV；无环的 module store）──
+/** 注册成功后把最终 id 追加进侧栏启用 CSV（已存在则不动）——注册即
+ * 可见：PanelBar 出胶囊、open()/1-9/z 生效；/panel 与 /settings 仍可移除。 */
+function enablePanelIdInStore(id) {
+    const ids = [...parseSidePanelIds(getSidePanelPanels())];
+    if (!ids.includes(id))
+        ids.push(id);
+    applySidePanelPanels(ids.join(','));
+}
+/** 撤下时把最终 id 从启用 CSV 摘掉（PanelHost 对缺失的 active 自动回
+ * 退到第一个已启用 Panel）。 */
+function disablePanelIdInStore(id) {
+    const ids = parseSidePanelIds(getSidePanelPanels()).filter(candidate => candidate !== id);
+    applySidePanelPanels(ids.join(','));
+}
+export function getHostPanelRuntime(runtime) {
+    if (runtime === undefined)
+        return undefined;
+    try {
+        return panelStateFor(runtime).host ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export default TuiPanelRuntime;

package/lib/types/dsh-adapter/plugin-host.js

@@ -613,7 +613,7 @@ export class TuiPluginHostRuntime extends Service {
         this.assertEffect('host.diagnostics');
         const data = loadSpecData();
         if (data === undefined)
-            return ['vendored spec data unavailable (dsh-ecosystem-spec/)'];
+            return ['vendored spec data unavailable (tui-profile/)'];
         return [...verifyRegistry(data), ...verifyContractProfiles(data)];
     }
 }

package/lib/types/dsh-adapter/plugin.d.ts

@@ -2,14 +2,31 @@ import type { Agent } from '@deepseek-ai/dsh-agent';
 import type { Context } from '@deepseek-ai/cordis';
 import { Config } from './index.js';
 import { type RuntimeConfig } from './compat/settings.js';
+import { type CrashDetail } from '../utils/crashDetail.js';
+import { initialPromptFromCmdlineArgs } from './startup-args.js';
 import { render } from '../ui.js';
+export { initialPromptFromCmdlineArgs };
 /**
  * Extract the startup prompt from raw app argv, excluding session selectors
  * and Web startup flag values. `--trusted-host` consumes multiple authorities
  * up to the next flag; none of them are prompt text (issue #882). An app-level
  * `--` ends flag parsing; all following tokens are literal prompt text.
  */
-export declare function initialPromptFromCmdlineArgs(args: readonly string[] | undefined): string;
+/**
+ * 落地页 / 首启引导该不该在这次启动出现。
+ *
+ * 只看「用户有没有说要回到哪儿」：`--resume` 目标与首句都算他知道自己要去哪。
+ * **工作区目标不算**——`dst` 默认把 cwd 当工作区目标喂进来，算进去就等于在本机
+ * 最主流的启动方式下把这两个屏永久关掉（实测事故，见调用点的口径注释）。
+ *
+ * @param input.launchSessionId - 本次要恢复的会话（--resume / DSH_TUI_RESUME_SESSION）。
+ * @param input.initialPrompt - 命令行里带的首句提示词（无则空串）。
+ * @returns true 表示这次是「普通启动」。
+ */
+export declare function isLandingLaunch(input: {
+    launchSessionId?: string;
+    initialPrompt: string;
+}): boolean;
 /**
  * How this process should treat the TUI frontend, given the terminal it runs on.
  *
@@ -53,6 +70,37 @@ export declare function createExitFunnel(deps: {
     handleExit: (error?: unknown) => boolean;
     markTeardown: () => void;
 };
+/**
+ * The exit funnel's crash tail, separate so scripts/verify-shutdown-fallback
+ * can drive it with failing sinks:
+ *
+ *  - Diagnostics (serialization and every log sink) may fail: a throwing
+ *    getter or Proxy trap on the error, or a sink that throws, falls back to
+ *    unserializableCrashDetail and one more logging attempt. The funnel latch
+ *    is already set here, so an exception escaping would skip the rest.
+ *  - The resume markers (and the last-run record, via writeResumeMarkers)
+ *    and the terminal cleanup (finish, then disposeRootAndExit(1)) always
+ *    run, whatever happened to the diagnostics.
+ */
+export interface CrashExitDeps {
+    /** The crash value itself (may be hostile: throwing getters, Proxy traps). */
+    readonly error: unknown;
+    /** Serializer override (verify fault injection); default serializeCrashDetail. */
+    readonly serialize?: (error: unknown) => CrashDetail;
+    /** One-line error log (ctx.logger.error). */
+    readonly logError: (message: string) => void;
+    /** crash.log append (appendCrashLog). */
+    readonly appendLog: (detail: CrashDetail) => void;
+    /** restart.log one-line event (logRestartEvent). */
+    readonly logRestart: (event: string, data?: Record<string, unknown>) => void;
+    /** Debug log (logForDebugging). */
+    readonly logDebug: (message: string, data?: Record<string, unknown>) => void;
+    /** Resume markers; best effort, isolated from the diagnostics' fate. */
+    readonly writeResumeMarkers: () => void;
+    /** MUST-RUN terminal cleanup + exit(1) handoff (finishExit + dispose). */
+    readonly finish: (crashLine: string) => void;
+}
+export declare function runCrashExit(deps: CrashExitDeps): void;
 /**
  * Whether a user exit should leave the resume marker (and print the resume
  * hint). Must be judged against the LIVE session behind the channel, not the
@@ -67,13 +115,17 @@ export declare function createExitFunnel(deps: {
 export declare function isExitResumable(deps: {
     pendingCount: number;
     liveAgent: Agent | undefined;
-    startupAgent: Agent;
+    /** Undefined when the session runs on a non-DSH backend: its id is never
+     *  a DSH resume target. */
+    startupAgent: Agent | undefined;
 }): boolean;
 /**
  * Finish terminal I/O before handing control to a process-level exit action.
  * Exported for scripts/verify-shutdown-fallback.
  */
-export declare function finishExit(ctx: Context, instance: Awaited<ReturnType<typeof render>> | undefined, fullscreen: boolean, notice: string | undefined, stderrNotice: string | undefined, done: () => void): Promise<void>;
+export declare function finishExit(ctx: Context, instance: Awaited<ReturnType<typeof render>> | undefined, fullscreen: boolean, notice: string | undefined, stderrNotice: string | undefined, done: () => void, options?: {
+    keepAltScreen?: boolean;
+}): Promise<void>;
 /** Deferred runtime failures must restore the terminal and fail the process. */
 export declare function handleStartupError(ctx: Context, error: unknown): void;
 //# sourceMappingURL=plugin.d.ts.map

package/lib/types/dsh-adapter/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/plugin.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAe,MAAM,wBAAwB,CAAA;AAGhE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAGlD,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AACnC,OAAO,EAA+D,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAyDtH,OAAO,EAAE,MAAM,EAAkC,MAAM,UAAU,CAAA;AAmCjE;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,CAsBxF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,yBAAyB,GAAG,eAAe,CAAA;AAErF,wBAAgB,kBAAkB,CAChC,WAAW,UAAgC,EAC3C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,WAAW,CASb;AAED,wBAAsB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,EAAE,WAAW,GAAE,OAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAw8CzH;AAmMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IAAE,UAAU,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;CAAE,GAAG;IACjF;;;;;;OAMG;IACH,UAAU,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,OAAO,CAAA;IACxC,YAAY,EAAE,MAAM,IAAI,CAAA;CACzB,CAeA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,KAAK,GAAG,SAAS,CAAA;IAC5B,YAAY,EAAE,KAAK,CAAA;CACpB,GAAG,OAAO,CAQV;AAgBD;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC,GAAG,SAAS,EACxD,UAAU,EAAE,OAAO,EACnB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,IAAI,EAAE,MAAM,IAAI,GACf,OAAO,CAAC,IAAI,CAAC,CAmFf;AA4HD,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAIrE"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/plugin.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAe,MAAM,wBAAwB,CAAA;AAGhE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAGlD,OAAO,EAAE,MAAM,EAA0B,MAAM,YAAY,CAAA;AAC3D,OAAO,EAA+D,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAatH,OAAO,EAAmE,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAqB3H,OAAO,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAA;AAoChE,OAAO,EAAE,MAAM,EAAkC,MAAM,UAAU,CAAA;AAsCjE,OAAO,EAAE,4BAA4B,EAAE,CAAA;AAEvC;;;;;GAKG;AACH;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IAAE,eAAe,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAEnG;AAGD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,yBAAyB,GAAG,eAAe,CAAA;AAErF,wBAAgB,kBAAkB,CAChC,WAAW,UAAgC,EAC3C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,WAAW,CASb;AAED,wBAAsB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,EAAE,WAAW,GAAE,OAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CA89DzH;AAoMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IAAE,UAAU,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;CAAE,GAAG;IACjF;;;;;;OAMG;IACH,UAAU,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,OAAO,CAAA;IACxC,YAAY,EAAE,MAAM,IAAI,CAAA;CACzB,CAeA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,kFAAkF;IAClF,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,WAAW,CAAA;IACpD,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IAC5C,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAA;IACjD,oDAAoD;IACpD,QAAQ,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IAC5E,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IAC5E,wEAAwE;IACxE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,IAAI,CAAA;IACvC,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAA;CAC7C;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CA0BtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,KAAK,GAAG,SAAS,CAAA;IAC5B;+BAC2B;IAC3B,YAAY,EAAE,KAAK,GAAG,SAAS,CAAA;CAChC,GAAG,OAAO,CASV;AAgBD;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC,GAAG,SAAS,EACxD,UAAU,EAAE,OAAO,EACnB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,IAAI,EAAE,MAAM,IAAI,EAChB,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GACxC,OAAO,CAAC,IAAI,CAAC,CA0Ff;AAmID,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAIrE"}