@deepseek-harness-tui/dsh-tui 0.10.0 → 0.10.1

package/lib/types/dsh-adapter/channel/local-actions.js

@@ -0,0 +1,108 @@
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { markChannelReadDirty } from '../../adapter/channel/read-view.js';
+import { writeActivityFrames } from '../../activityPrefs.js';
+import { isPresetName, normalizeActivityPreset } from '../../components/activityFrames.js';
+import { t } from '../../i18n.js';
+import { snapshotLiveSessionEvents } from '../compat/liveSession.js';
+import { LOCAL_OUTPUT_LIMIT, preview } from './transcript.js';
+/** Owns local-only transcript mutations, shell output, and live subagent queries. */
+export function createLocalActions(deps) {
+    const { ctx, owner, binding, state, rowIds, projector, subagents, jobs, foldBack, workspace, shell, notify } = deps;
+    const current = (capture) => owner.current() && binding.isCurrent(capture);
+    return {
+        loadOlder() {
+            const restored = foldBack(state.rows, snapshotLiveSessionEvents(binding.agent.session), { call: projector.presentCallView, result: projector.presentResultView });
+            if (restored > 0)
+                state.emit();
+            return restored;
+        },
+        clear() {
+            state.rows.length = 0;
+            markChannelReadDirty(state.rows);
+            rowIds.value = 0;
+            projector.reset();
+            subagents.dropRows();
+            jobs.dropRows();
+            state.activeToolCount = 0;
+            state.responseChars = 0;
+            state.rows.push({ id: rowIds.value++, kind: 'notice', text: 'Session cleared' });
+            state.emit();
+        },
+        pushLocal(title, lines) {
+            state.rows.push({ id: rowIds.value++, kind: 'local', text: title });
+            for (const line of lines)
+                state.rows.push({ id: rowIds.value++, kind: 'local-output', text: preview(line, LOCAL_OUTPUT_LIMIT) });
+            state.emit();
+        },
+        setActivityFrames(name) {
+            // A retired preset id normalizes to the current default, so the
+            // in-memory state, the persisted preference and the toast agree instead
+            // of diverging until restart.
+            const preset = normalizeActivityPreset(name) ?? name;
+            if (!isPresetName(preset)) {
+                notify(t('unknown-activity-preset', { name }), { color: 'error' });
+                return false;
+            }
+            if (preset === state.activityFrames) {
+                notify(t('activity-indicator-already', { name: preset }), { color: 'success' });
+                return true;
+            }
+            if (!writeActivityFrames(preset)) {
+                notify(t('activity-pref-write-failed'), { color: 'error' });
+                return false;
+            }
+            state.activityFrames = preset;
+            state.emit();
+            notify(t('activity-indicator-switched', { name: preset }));
+            return true;
+        },
+        async listSubagents() {
+            const service = ctx.get('subagents');
+            if (!service)
+                return [t('subagent-not-mounted')];
+            const capture = binding.capture();
+            try {
+                const children = await service.listChildren(binding.agent.session.id);
+                if (!current(capture))
+                    throw new Error('dsh-tui: Channel lifetime has ended');
+                if (children.length === 0)
+                    return [t('subagent-none')];
+                return children.map(child => {
+                    const id = typeof child.id === 'string' ? child.id : (child.id.value ?? '');
+                    return t('subagent-row', { mode: child.mode === 'continuable' ? t('subagent-resumable') : t('subagent-oneshot'), label: child.label ? `「${child.label}」` : '', activity: child.activity === 'running' ? t('subagent-running') : t('subagent-archived'), id: id.slice(0, 8) });
+                });
+            }
+            catch (error) {
+                if (!current(capture))
+                    throw error;
+                return [t('subagent-query-failed', { err: error instanceof Error ? error.message : String(error) })];
+            }
+        },
+        async runLocalCommand(command, includeInContext) {
+            const capture = binding.capture();
+            const cwd = state.cwd;
+            const target = workspace.describe(cwd);
+            state.rows.push({ id: rowIds.value++, kind: 'local', text: command, executionTarget: target.kind === 'local' ? target.badge : `${target.badge} · ${target.label}` });
+            state.emit();
+            let output = '(no output)';
+            const executor = await workspace.commandShell(cwd) ?? shell;
+            if (!current(capture))
+                return;
+            if (executor) {
+                try {
+                    const result = await executor.run(executor.resolve({ command, workdir: cwd, timeoutMs: 30000 }));
+                    output = result.stdout.text.trim() || result.stderr.text.trim() || (result.timedOut ? '(timed out)' : '(no output)');
+                }
+                catch (error) {
+                    output = error instanceof Error ? error.message : String(error);
+                }
+            }
+            if (!current(capture))
+                return;
+            state.rows.push({ id: rowIds.value++, kind: 'local-output', text: preview(output, LOCAL_OUTPUT_LIMIT) });
+            state.emit();
+            if (includeInContext)
+                binding.agent.followup(createUserMessage({ content: [{ type: 'text', text: `<bash-stdout>\n${output}\n</bash-stdout>` }], source: { kind: 'user' } }));
+        },
+    };
+}

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

@@ -0,0 +1,29 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { MentionAttachments, MentionExpansion, MentionFs, MentionImageBlock, MentionImageMediaType, ResolvedMention } from './types.js';
+/** One attached file's contribution is capped so an absent-minded `@` of a
+ *  huge file cannot blow the context window. */
+export declare const MENTION_MAX_FILE_CHARS = 50000;
+/** Total budget across all attachments in one message. */
+export declare const MENTION_MAX_TOTAL_CHARS = 200000;
+/** A directory mention contributes a shallow listing, capped at this many
+ *  entries. */
+export declare const MENTION_MAX_DIR_ENTRIES = 200;
+/** The leaf's fs service in the shape mention expansion needs; undefined
+ *  when the plugin is not mounted (mentions then stay literal text). */
+export declare function mentionFs(ctx: Context): MentionFs | undefined;
+export declare function mentionAttachments(ctx: Context): MentionAttachments | undefined;
+export declare const MENTION_IMAGE_MEDIA_TYPES: Readonly<Record<string, MentionImageMediaType>>;
+export declare function mentionImageMediaType(path: string): MentionImageMediaType | undefined;
+/** Resolve+stat one candidate path; undefined when it throws OR stats
+ * absent — both are a miss for strip-first mention resolution (issue #359). */
+export declare function tryResolveMention(fs: MentionFs, absolute: string): Promise<ResolvedMention | undefined>;
+/**
+ * Expand a submitted text's `@` mentions (issue #15) into model-facing
+ * attachment blocks: supported image files become durable image blocks,
+ * other files contribute capped text, and directories contribute a shallow
+ * listing. Reads always go through the active fs service, so provider-owned
+ * workspaces keep their routing semantics. The typed text stays first and
+ * verbatim. Best-effort failures degrade to `missing`, never a failed send.
+ */
+export declare function expandMentions(fs: MentionFs | undefined, cwd: string, text: string, attachments?: MentionAttachments, stagedImages?: ReadonlyMap<string, MentionImageBlock['attachment']>): Promise<MentionExpansion>;
+//# sourceMappingURL=mentions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mentions.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/mentions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,SAAS,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAE5I;gDACgD;AAChD,eAAO,MAAM,sBAAsB,QAAS,CAAA;AAE5C,0DAA0D;AAC1D,eAAO,MAAM,uBAAuB,SAAU,CAAA;AAE9C;eACe;AACf,eAAO,MAAM,uBAAuB,MAAM,CAAA;AAE1C;wEACwE;AACxE,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAE7D;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,GAAG,SAAS,CAE/E;AAED,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAMrF,CAAA;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAErF;AAED;+EAC+E;AAC/E,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAS7G;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,SAAS,GAAG,SAAS,EACzB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,kBAAkB,EAChC,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAC,GAClE,OAAO,CAAC,gBAAgB,CAAC,CAqL3B"}

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

@@ -0,0 +1,235 @@
+import { extname, isAbsolute, join } from 'node:path';
+import { extractMentions } from '../../utils/mentions.js';
+import { basename } from './paths.js';
+import { COMPOSER_IMAGE_TOKEN } from './composer-images.js';
+/** One attached file's contribution is capped so an absent-minded `@` of a
+ *  huge file cannot blow the context window. */
+export const MENTION_MAX_FILE_CHARS = 50_000;
+/** Total budget across all attachments in one message. */
+export const MENTION_MAX_TOTAL_CHARS = 200_000;
+/** A directory mention contributes a shallow listing, capped at this many
+ *  entries. */
+export const MENTION_MAX_DIR_ENTRIES = 200;
+/** The leaf's fs service in the shape mention expansion needs; undefined
+ *  when the plugin is not mounted (mentions then stay literal text). */
+export function mentionFs(ctx) {
+    return ctx.get('fs');
+}
+export function mentionAttachments(ctx) {
+    return ctx.get('attachments');
+}
+export const MENTION_IMAGE_MEDIA_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+    '.gif': 'image/gif',
+};
+export function mentionImageMediaType(path) {
+    return MENTION_IMAGE_MEDIA_TYPES[extname(path).toLowerCase()];
+}
+/** Resolve+stat one candidate path; undefined when it throws OR stats
+ * absent — both are a miss for strip-first mention resolution (issue #359). */
+export async function tryResolveMention(fs, absolute) {
+    try {
+        const target = await fs.resolve(absolute);
+        const info = await fs.stat(target);
+        if (info === undefined)
+            return undefined;
+        return { target, info };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Expand a submitted text's `@` mentions (issue #15) into model-facing
+ * attachment blocks: supported image files become durable image blocks,
+ * other files contribute capped text, and directories contribute a shallow
+ * listing. Reads always go through the active fs service, so provider-owned
+ * workspaces keep their routing semantics. The typed text stays first and
+ * verbatim. Best-effort failures degrade to `missing`, never a failed send.
+ */
+export async function expandMentions(fs, cwd, text, attachments, stagedImages) {
+    const blocks = [{ type: 'text', text }];
+    const attached = [];
+    const missing = [];
+    const mentions = extractMentions(text);
+    let budget = MENTION_MAX_TOTAL_CHARS;
+    let imageCount = 0;
+    let imageBytes = 0;
+    const references = fs === undefined
+        ? []
+        : mentions.map(mention => ({ kind: 'mention', start: mention.start, mention }));
+    if (stagedImages !== undefined) {
+        const seen = new Set();
+        for (const match of text.matchAll(COMPOSER_IMAGE_TOKEN)) {
+            const token = match[0];
+            if (seen.has(token))
+                continue;
+            seen.add(token);
+            const attachment = stagedImages.get(token);
+            if (attachment === undefined)
+                continue;
+            references.push({
+                kind: 'staged-image',
+                start: match.index,
+                token,
+                attachment,
+            });
+        }
+    }
+    references.sort((a, b) => a.start - b.start);
+    // `@image` files and staged `[Image #N]` capabilities share one admission
+    // queue. The earliest reference in the user's text wins both the per-
+    // message count and byte budgets, and image blocks preserve that order.
+    for (const reference of references) {
+        if (reference.kind === 'staged-image') {
+            const { attachment, token } = reference;
+            // A referenced-but-dropped staged image must be loud: silently sending
+            // the bare token would leave the user believing the image reached the
+            // model. Reuse the missing-mention warning channel.
+            if (attachments === undefined) {
+                missing.push(token);
+                continue;
+            }
+            const limits = attachments.imageLimits;
+            if (imageCount >= limits.maxImagesPerMessage
+                || imageBytes + attachment.bytes > limits.maxMessageImageBytes
+                || !limits.mediaTypes.includes(attachment.mediaType)) {
+                missing.push(token);
+                continue;
+            }
+            blocks.push({ type: 'image', attachment });
+            imageCount += 1;
+            imageBytes += attachment.bytes;
+            continue;
+        }
+        if (fs === undefined)
+            continue;
+        const { mention } = reference;
+        const display = mention.literal ?? mention.path;
+        const imageMediaType = mentionImageMediaType(mention.path);
+        // A depleted text budget must not hide a later image reference: image
+        // admission has independent limits and still follows source order.
+        if (budget <= 0 && imageMediaType === undefined)
+            continue;
+        // Mentions resolve against the session cwd, same as the model-facing fs
+        // tools; absolute paths pass through untouched. A `#L12-14` line suffix
+        // (issue #359) is stripped before resolution; when the stripped path
+        // misses, the typed literal (suffix intact) gets ONE fallback try so
+        // filenames genuinely containing `#L…` still resolve as whole files.
+        const absolute = isAbsolute(mention.path) ? mention.path : join(cwd, mention.path);
+        let resolved = await tryResolveMention(fs, absolute);
+        let literalFallback = false;
+        if (resolved === undefined && mention.literal !== undefined) {
+            const literalPath = isAbsolute(mention.literal) ? mention.literal : join(cwd, mention.literal);
+            resolved = await tryResolveMention(fs, literalPath);
+            literalFallback = resolved !== undefined;
+        }
+        if (resolved === undefined) {
+            missing.push(display);
+            continue;
+        }
+        const { target, info } = resolved;
+        // On a literal-fallback hit the attached file IS the typed name — the
+        // model must see that path, not the suffix-stripped one.
+        const shownPath = literalFallback ? display : mention.path;
+        // …and judge image-ness by the typed extension in that case too.
+        const imageType = literalFallback && mention.literal !== undefined
+            ? mentionImageMediaType(mention.literal)
+            : imageMediaType;
+        if (info?.type === 'file') {
+            if (imageType !== undefined && attachments !== undefined && fs.readBytes !== undefined) {
+                const limits = attachments.imageLimits;
+                if (!limits.mediaTypes.includes(imageType) || imageCount >= limits.maxImagesPerMessage) {
+                    missing.push(display);
+                    continue;
+                }
+                try {
+                    const data = await fs.readBytes(target, undefined, limits.maxImageBytes);
+                    if (imageBytes + data.byteLength > limits.maxMessageImageBytes) {
+                        missing.push(display);
+                        continue;
+                    }
+                    const attachment = await attachments.saveImage({
+                        data,
+                        mediaType: imageType,
+                        name: basename(target.displayPath),
+                    });
+                    blocks.push({ type: 'image', attachment });
+                    imageCount += 1;
+                    imageBytes += data.byteLength;
+                    attached.push(display);
+                }
+                catch {
+                    missing.push(display);
+                }
+                continue;
+            }
+            try {
+                const cap = Math.min(MENTION_MAX_FILE_CHARS, budget);
+                const content = await fs.readText(target);
+                let body = content;
+                let truncated = false;
+                let header = `<attached-file path="${shownPath}">`;
+                if (mention.startLine !== undefined && !literalFallback) {
+                    // Line-range slice (issue #359): 1-based inclusive. An endLine
+                    // past EOF clamps to the file; a startLine past EOF falls back
+                    // to the whole file with an in-band note — never a silent
+                    // empty attach. Line ranges never apply to literal-fallback
+                    // hits (those files really are named `…#L…`, no suffix typed).
+                    const lines = content.split('\n');
+                    if (mention.startLine > lines.length) {
+                        header = `<attached-file path="${shownPath}" lines="${mention.startLine}-${mention.endLine}" note="requested lines beyond EOF (file has ${lines.length} line${lines.length === 1 ? '' : 's'}); whole file attached">`;
+                    }
+                    else {
+                        const endLine = Math.min(mention.endLine ?? mention.startLine, lines.length);
+                        header = `<attached-file path="${shownPath}" lines="${mention.startLine}${endLine === mention.startLine ? '' : `-${endLine}`}">`;
+                        body = lines.slice(mention.startLine - 1, endLine).join('\n');
+                    }
+                }
+                if (body.length > cap) {
+                    body = body.slice(0, cap);
+                    truncated = true;
+                }
+                budget -= body.length;
+                blocks.push({
+                    type: 'text',
+                    text: `${header}\n${body}${truncated ? '\n[… truncated]' : ''}\n</attached-file>`,
+                });
+                attached.push(display);
+            }
+            catch {
+                // Binary/undecodable or unreadable — report it like a miss.
+                missing.push(display);
+            }
+            continue;
+        }
+        if (info?.type === 'directory') {
+            try {
+                const entries = await fs.listDir(target);
+                const listing = entries
+                    .slice(0, MENTION_MAX_DIR_ENTRIES)
+                    .map(entry => (entry.type === 'directory' ? `${entry.name}/` : entry.name));
+                if (entries.length > MENTION_MAX_DIR_ENTRIES) {
+                    listing.push(`… (${entries.length - MENTION_MAX_DIR_ENTRIES} more)`);
+                }
+                const body = listing.join('\n');
+                budget -= body.length;
+                blocks.push({
+                    type: 'text',
+                    text: `<attached-directory path="${shownPath}">\n${body}\n</attached-directory>`,
+                });
+                attached.push(display);
+            }
+            catch {
+                missing.push(display);
+            }
+            continue;
+        }
+        // Absent (stat → undefined) or a special file.
+        missing.push(display);
+    }
+    return { blocks, attached, missing };
+}

package/lib/types/dsh-adapter/channel/mode-actions.d.ts

@@ -0,0 +1,30 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import { type SessionModeSpec } from '../../sessionModes.js';
+import { type AdapterRuntimeOptions } from '../../adapter/kernel/runtime.js';
+import type { ChannelState } from './types.js';
+import type { createChannelBinding } from './binding.js';
+type Binding = ReturnType<typeof createChannelBinding>;
+type ModeState = Pick<ChannelState, 'mode' | 'modeIndex' | 'emit'>;
+/** Durable session-mode folds and transitions. Construction is inert; root wires it after state construction. */
+export declare function createModeActions(ctx: Context, state: ModeState, deps: {
+    owner: {
+        current(): boolean;
+    };
+    runtime: AdapterRuntimeOptions;
+    binding: Pick<Binding, 'agent' | 'capture' | 'isCurrent'>;
+    sessionModes: readonly SessionModeSpec[];
+    commandService?: {
+        find(agent: Agent, name: string): unknown;
+    };
+    executeRegistryCommand(name: string, input: string): Promise<string | undefined>;
+    notify: ChannelState['notify'];
+}): {
+    refreshMode: () => void;
+    cycleMode: () => Promise<void>;
+    applyMode: (spec: SessionModeSpec, capture?: import("./binding.js").BindingCapture) => Promise<void>;
+    onSessionEvent: (session: Agent["session"], event: SessionEvent) => void;
+};
+export {};
+//# sourceMappingURL=mode-actions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mode-actions.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/mode-actions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAE5D,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC7E,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,iCAAiC,CAAA;AAChG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAExD,KAAK,OAAO,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAA;AACtD,KAAK,SAAS,GAAG,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC,CAAA;AAElE,iHAAiH;AACjH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE;IACJ,KAAK,EAAE;QAAE,OAAO,IAAI,OAAO,CAAA;KAAE,CAAA;IAC7B,OAAO,EAAE,qBAAqB,CAAA;IAC9B,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,WAAW,CAAC,CAAA;IACzD,YAAY,EAAE,SAAS,eAAe,EAAE,CAAA;IACxC,cAAc,CAAC,EAAE;QAAE,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAA;IAC9D,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;IAChF,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAA;CAC/B;uBAyDqB,IAAI;qBAkJE,OAAO,CAAC,IAAI,CAAC;sBAlEV,eAAe,sDAAgC,OAAO,CAAC,IAAI,CAAC;8BAyE1D,KAAK,CAAC,SAAS,CAAC,SAAS,YAAY,KAAG,IAAI;EA4B9E"}

package/lib/types/dsh-adapter/channel/mode-actions.js

@@ -0,0 +1,247 @@
+import { t } from '../../i18n.js';
+import { modeDisplayName } from '../../sessionModes.js';
+import { assertShadowPolicy } from '../../adapter/kernel/runtime.js';
+import { snapshotLiveSessionEvents } from '../compat/liveSession.js';
+/** Durable session-mode folds and transitions. Construction is inert; root wires it after state construction. */
+export function createModeActions(ctx, state, deps) {
+    const { owner, runtime, binding, sessionModes, commandService, executeRegistryCommand, notify } = deps;
+    const current = (capture) => owner.current() && binding.isCurrent(capture);
+    const capturedSession = (capture) => capture.agent.session;
+    // Session-mode folds: last-wins projections over the session log. The
+    // event types are registered by dsh-plan-mode / dsh-sandbox-policy /
+    // dsh-user-approval and are NOT in this package's typed SessionEvent
+    // union, so they are matched by name through casts — the same pattern as
+    // `agent-preset/selected` in renderEvent and the goal projection above.
+    const foldPlanActive = (events) => {
+        let active = false;
+        for (const event of events) {
+            if (event.type === 'plan/mode') {
+                active = event.data.active === true;
+            }
+        }
+        return active;
+    };
+    const foldSandboxMode = (events) => {
+        let mode;
+        for (const event of events) {
+            if (event.type === 'sandbox/mode') {
+                const value = event.data.mode;
+                if (typeof value === 'string')
+                    mode = value;
+            }
+        }
+        return mode;
+    };
+    const foldApprovalPolicy = (events) => {
+        let policy;
+        for (const event of events) {
+            if (event.type === 'approval/policy') {
+                const value = event.data.policy;
+                if (typeof value === 'string')
+                    policy = value;
+            }
+        }
+        return policy;
+    };
+    /** First configured mode whose declared atoms all match the folds;
+     *  undeclared atoms are wildcards; no match → index 0 (the base mode).
+     *  Matching is exact: a fresh session has no `approval/policy` event, so
+     *  a mode declaring `approval: 'ask'` never falsely matches it. */
+    const deriveModeIndex = (events) => {
+        const index = sessionModes.findIndex(spec => (spec.plan === undefined || foldPlanActive(events) === spec.plan) &&
+            (spec.sandbox === undefined || foldSandboxMode(events) === spec.sandbox) &&
+            (spec.approval === undefined || foldApprovalPolicy(events) === spec.approval));
+        return index >= 0 ? index : 0;
+    };
+    /** Re-derive the current mode from the live session log (boot, every
+     *  agent re-bind, and after mode-affecting session events). */
+    const refreshMode = () => {
+        state.modeIndex = deriveModeIndex(snapshotLiveSessionEvents(binding.agent.session));
+        state.mode = sessionModes[state.modeIndex];
+    };
+    // Session.append rejects observer reentry; restore after publication
+    // unwinds. These are channel-scoped so a disposed/recreated Channel cannot
+    // inherit deferred work from a former owner.
+    const pendingPlanExitRestores = new Map();
+    const prePlanModes = new WeakMap();
+    // An in-turn /plan off commits at pre-step, after the command has returned.
+    const explicitPlanExits = new WeakSet();
+    const modePermissions = (events) => {
+        const sandbox = foldSandboxMode(events);
+        const approval = foldApprovalPolicy(events);
+        return {
+            id: 'restore',
+            ...(sandbox === 'read-only' || sandbox === 'workspace-write' || sandbox === 'danger-full-access'
+                ? { sandbox } : {}),
+            ...(approval === 'ask' || approval === 'never' ? { approval } : {}),
+        };
+    };
+    /** Recover a resumed plan's snapshot before /plan ran, not before its
+     *  deferred plan/mode event. Unknown historical atoms stay untouched. */
+    const prePlanModeSpec = (log) => {
+        let active = false;
+        let start = -1;
+        let command;
+        for (let index = 0; index < log.length - 1; index += 1) {
+            const event = log[index];
+            const type = event.type;
+            const data = event.data;
+            if (!active && type === 'command/run' && data.name === 'plan' && typeof data.args === 'string') {
+                if (data.args.trim() === 'off')
+                    command = undefined;
+                else
+                    command ??= { index, id: data.commandId };
+            }
+            if (type === 'command/done' && data.commandId === command?.id && data.kind !== 'success') {
+                command = undefined;
+            }
+            if (type === 'plan/mode') {
+                if (data.active === true && !active)
+                    start = command?.index ?? index;
+                active = data.active === true;
+                command = undefined;
+            }
+        }
+        return active && start >= 0 ? modePermissions(log.slice(0, start)) : undefined;
+    };
+    const applyModeAtoms = (spec, capture) => {
+        if (!current(capture))
+            return;
+        const agent = capture.agent;
+        const session = capturedSession(capture);
+        // The durable sandbox override is one session event (dsh-sandbox-policy's
+        // own write path); the session/event arm picks it up immediately.
+        if (spec.sandbox !== undefined && foldSandboxMode(snapshotLiveSessionEvents(session)) !== spec.sandbox) {
+            ;
+            session.append('sandbox/mode', { mode: spec.sandbox });
+        }
+        if (!current(capture))
+            return;
+        // Prefer the approval service (it narrates the switch to the model);
+        // the raw durable event is the fallback when it is unmounted.
+        if (spec.approval !== undefined && foldApprovalPolicy(snapshotLiveSessionEvents(session)) !== spec.approval) {
+            const approval = ctx.get('approval');
+            approval?.setPolicy(agent, spec.approval);
+            if (!current(capture))
+                return;
+            // The service may no-op when its configured default already matches.
+            if (foldApprovalPolicy(snapshotLiveSessionEvents(session)) !== spec.approval) {
+                ;
+                session.append('approval/policy', { policy: spec.approval });
+            }
+        }
+    };
+    /** Apply the configured atoms; an explicit exit owns its target mode. */
+    const applyMode = async (spec, capture = binding.capture()) => {
+        if (!current(capture))
+            return;
+        // This action writes durable session policy. The runtime snapshot comes
+        // from composition and is immutable for this Channel lifetime, so an
+        // observed plan exit cannot bypass the renderer/Port shadow guard.
+        assertShadowPolicy('mutate', runtime.mode);
+        const agent = capture.agent;
+        const session = capturedSession(capture);
+        pendingPlanExitRestores.delete(session);
+        const planMode = ctx.get('planMode');
+        const planActive = foldPlanActive(snapshotLiveSessionEvents(session));
+        // Reconcile a stale explicit-exit marker before acting. The marker only
+        // legitimately survives while a deferred exit awaits its plan/mode:false
+        // (foldPlanActive && pending === false). If plan is still logged active
+        // with no pending intent, that awaited event was abandoned (e.g. an
+        // aborted pre-step) — drop the orphan so it cannot suppress a later restore
+        // such as an approved exit_plan_mode.
+        if (planActive && planMode?.get?.(agent).pending === undefined) {
+            explicitPlanExits.delete(session);
+        }
+        if (spec.plan !== undefined && (planMode?.get?.(agent).pending ?? planActive) !== spec.plan) {
+            if (commandService?.find(agent, 'plan') === undefined) {
+                notify(t('mode-plan-unavailable'), { color: 'warning' });
+                return;
+            }
+            if (spec.plan && !planActive && !prePlanModes.has(session)) {
+                const previous = modePermissions(snapshotLiveSessionEvents(session));
+                const sandbox = ctx.get('sandboxPolicy');
+                const approval = ctx.get('approval');
+                const base = previous.sandbox === undefined && previous.approval === undefined ? sessionModes[0] : undefined;
+                previous.sandbox ??= sandbox?.defaultMode ?? base?.sandbox;
+                previous.approval ??= approval?.effectivePolicy?.(session) ?? base?.approval;
+                prePlanModes.set(session, previous);
+                // Persist missing defaults before /plan, so resume can recover them.
+                applyModeAtoms(previous, capture);
+            }
+            if (!spec.plan)
+                explicitPlanExits.add(session);
+            try {
+                const text = await executeRegistryCommand('plan', spec.plan ? '' : ' off');
+                if (!current(capture) || session !== capturedSession(capture))
+                    return;
+                if (text === undefined) {
+                    notify(t('mode-plan-unavailable'), { color: 'warning' });
+                    return;
+                }
+            }
+            finally {
+                if (current(capture) && session === capturedSession(capture)) {
+                    const pending = planMode?.get?.(agent).pending;
+                    if (!foldPlanActive(snapshotLiveSessionEvents(session)) || pending !== false)
+                        explicitPlanExits.delete(session);
+                    if (!foldPlanActive(snapshotLiveSessionEvents(session)) && pending !== true)
+                        prePlanModes.delete(session);
+                }
+            }
+        }
+        if (!current(capture))
+            return;
+        applyModeAtoms(spec, capture);
+        if (!current(capture))
+            return;
+        refreshMode();
+        if (!current(capture))
+            return;
+        notify(t('mode-switched', { name: modeDisplayName(state.mode) }));
+        state.emit();
+    };
+    /** Shift+Tab: advance to the next configured session mode. Cycling starts
+     *  from the mode DERIVED from the session log (never a stored index), so
+     *  manual `/plan` use can never desync the cycle. */
+    const cycleMode = async () => {
+        const capture = binding.capture();
+        if (!current(capture))
+            return;
+        const index = deriveModeIndex(snapshotLiveSessionEvents(capturedSession(capture)));
+        await applyMode(sessionModes[(index + 1) % sessionModes.length], capture);
+    };
+    const onSessionEvent = (session, event) => {
+        const capture = binding.capture();
+        if (!current(capture) || session !== capturedSession(capture))
+            return;
+        const eventType = event.type;
+        if (eventType === 'plan/mode' || eventType === 'sandbox/mode' || eventType === 'approval/policy') {
+            refreshMode();
+        }
+        if (eventType !== 'plan/mode' || event.data.active !== false)
+            return;
+        const target = prePlanModes.get(session) ?? prePlanModeSpec(snapshotLiveSessionEvents(session));
+        prePlanModes.delete(session);
+        if (explicitPlanExits.delete(session) || target === undefined)
+            return;
+        const queued = pendingPlanExitRestores.has(session);
+        pendingPlanExitRestores.set(session, { capture, target });
+        if (queued)
+            return;
+        queueMicrotask(() => {
+            const restore = pendingPlanExitRestores.get(session);
+            pendingPlanExitRestores.delete(session);
+            if (restore === undefined || !current(restore.capture) || session !== capturedSession(restore.capture) || foldPlanActive(snapshotLiveSessionEvents(session)))
+                return;
+            // Shadow still projects the observed plan/mode event above, but never
+            // schedules a compensating sandbox/approval write into the real log.
+            if (runtime.mode === 'passive-shadow' || runtime.mode === 'replay-shadow')
+                return;
+            applyMode(restore.target, restore.capture).catch(error => {
+                ctx.logger.warn(`dsh-tui: plan-exit mode restore failed: ${error instanceof Error ? error.message : String(error)}`);
+            });
+        });
+    };
+    return { refreshMode, cycleMode, applyMode, onSessionEvent };
+}