@deepseek-harness-tui/dsh-tui 0.6.1 → 0.7.1

package/lib/types/{channel.js → dsh-adapter/channel.js}

@@ -1,25 +1,36 @@
 import { randomUUID } from 'node:crypto';
 import { assembleContextFor, installModelSelection } from '@deepseek-ai/dsh-agent';
+import { isUserInvocable, renderSkillContent } from '@deepseek-ai/dsh-skill';
 import { createUserMessage, isTokenDelta, MessageId, ReasoningEffortId, } from '@deepseek-ai/dsh-llm';
+import { runSideQuestion, wrapSideQuestion } from './sideQuestion.js';
 import { SessionId } from '@deepseek-ai/dsh-session';
 import { renderContextSections, renderPrompt } from '@deepseek-ai/dsh-system-prompt';
-import { discoverBaselineInstructionFiles } from '@deepseek-ai/dsh-agent-instructions';
-import { isAbsolute, join } from 'node:path';
-import { LOCAL_COMMANDS } from './commands.js';
-import { clearResumeTarget, readLastUsed, touchSession, writeResumeTarget } from './sessionHistory.js';
-import { prepareSessionForResume, readSessionTitleFromLog } from './compat/index.js';
-import { writeActivityFrames } from './activityPrefs.js';
-import { readEffortPref, writeEffortPref } from './effortPrefs.js';
-import { readModelPref, writeModelPref } from './modelPrefs.js';
-import { explicitModelRoute, recordedModelRoute, resolveModelRoute, validateModelRoute } from './modelRoute.js';
-import { readPresetPref, writePresetPref } from './presetPrefs.js';
+import { loadBaselineInstructions } from '@deepseek-ai/dsh-agent-instructions';
+import { extname, isAbsolute, join } from 'node:path';
+import { completeCommands, isLocalCommandName, LOCAL_COMMANDS, parseCommandName } from '../commands.js';
+import { clearResumeTarget, forgetSession, readLastUsed, readResumeTarget, touchSession, writeResumeTarget } from '../sessionHistory.js';
+import { appendSessionTitle, deleteSessionLog, ensureLegacySessionEventTypes, readSessionTitleFromLog, sessionsRoots } from './compat/index.js';
+import { writeActivityFrames } from '../activityPrefs.js';
+import { readEffortPref, writeEffortPref } from '../effortPrefs.js';
+import { readModelPref, writeModelPref } from '../modelPrefs.js';
+import { explicitModelRoute, recordedModelRoute, resolveModelRoute, validateModelRoute } from '../modelRoute.js';
+import { readPresetPref, writePresetPref } from '../presetPrefs.js';
 import { composePreset, resolvePersistedPreset, rosterOf, runningPresetOf, serviceForAgent } from './presets.js';
-import { isPresetName } from './components/activityFrames.js';
-import { existsSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { logForDebugging } from './utils/debug.js';
-import { extractMentions } from './utils/mentions.js';
-import { t } from './i18n.js';
+import { isPresetName } from '../components/activityFrames.js';
+import { existsSync, statSync, writeFileSync } from 'node:fs';
+import { logForDebugging } from '../utils/debug.js';
+import { homeDir, LEGACY_DATA_DIR } from '../utils/paths.js';
+import { extractMentions } from '../utils/mentions.js';
+import { t } from '../i18n.js';
+import { modeDisplayName, resolveSessionModes } from '../sessionModes.js';
+import { ActivityTracker } from 'dsh-working-activity/status';
+import { attachSessionToWorkspace } from './workspace.js';
+import { createLocalWorkspaceRuntime } from './workspaces.js';
+/**
+ * Delay before re-reading a skill catalog that reported an incomplete
+ * observation (a provider whose directory watcher is still warming).
+ */
+const SKILL_COMMAND_RETRY_MS = 800;
 const ARGS_PREVIEW_LIMIT = 160;
 const RESULT_PREVIEW_LIMIT = 240;
 /** Local `!`-command output cap (mirrors the result preview limit). */
@@ -172,6 +183,21 @@ function restoreRowFromEvent(row, event) {
             break;
     }
 }
+/** Render the durable tool-result payload, including provider error details. */
+function toolResultText(event) {
+    const block = event.data.message.content[0];
+    if (block === undefined || block.type !== 'tool-result')
+        return '';
+    return block.content.map(item => item.type === 'text' ? item.text : '').join('').trim();
+}
+function toolErrorText(event) {
+    const failure = event.data.error;
+    if (failure === undefined)
+        return '';
+    const identity = `${failure.name}: ${failure.code}`;
+    const detail = toolResultText(event);
+    return detail === '' || detail === identity ? identity : `${identity} — ${detail}`;
+}
 /** Restore a folded tool row's result text from its tool/result event. */
 function restoreToolResult(row, event) {
     if (row.tool === undefined)
@@ -179,12 +205,11 @@ function restoreToolResult(row, event) {
     const failure = event.data.error;
     if (failure !== undefined) {
         row.tool.status = 'error';
-        row.tool.errorText = `${failure.name}: ${failure.code}`;
+        row.tool.errorText = toolErrorText(event);
         return;
     }
     row.tool.status = 'ok';
-    const block = event.data.message.content[0];
-    const result = block.content.map(b => b.type === 'text' ? b.text : '').join('').trim();
+    const result = toolResultText(event);
     row.tool.resultFull = result || undefined;
 }
 /**
@@ -278,6 +303,14 @@ export function createChannel(ctx, initialAgent, options) {
     // command/run + command/done records). Absent the service, only the
     // built-in local commands exist.
     const commandService = ctx.get('commands');
+    const workspaceService = ctx.tuiWorkspaces ?? createLocalWorkspaceRuntime();
+    const commandTrees = ctx.get('tuiCommandTrees');
+    // Shift+Tab session-mode cycle: cordis.yml `modes` wins; absent/empty/
+    // atom-less → the built-in default/plan/full cycle (sessionModes.ts).
+    const { modes: sessionModes, dropped: droppedModeIds } = resolveSessionModes(options.modes);
+    if (droppedModeIds.length > 0) {
+        ctx.logger.warn(`dsh-tui: session modes ${droppedModeIds.map(id => `"${id}"`).join(', ')} declare no plan/sandbox/approval atom; dropped from the Shift+Tab cycle`);
+    }
     const listeners = new Set();
     /** True while a frame-aligned stream notification is pending (emitStream). */
     let streamNotifyScheduled = false;
@@ -292,7 +325,7 @@ export function createChannel(ctx, initialAgent, options) {
             return;
         contextWarned = true;
         const percentLeft = Math.max(0, Math.round((remaining / state.contextWindow) * 100));
-        state.notify(`Context low (${percentLeft}% remaining) · Run /clear or start a new session`, { color: 'warning', timeoutMs: 8000 });
+        state.notify(t('context-low-warning', { percent: percentLeft }), { color: 'warning', timeoutMs: 8000 });
     };
     /**
      * Register a submitted message as pending and notify the UI. The inbox
@@ -316,6 +349,12 @@ export function createChannel(ctx, initialAgent, options) {
      * through this chain to keep the send order FIFO.
      */
     let sendChain = Promise.resolve();
+    let stagedImageSequence = 0;
+    const stagedImages = new Map();
+    const clearStagedImages = () => {
+        stagedImages.clear();
+        stagedImageSequence = 0;
+    };
     /**
      * Expand the text's `@` mentions and deliver ONE user message: the typed
      * text stays the first content block (the transcript bubble renders it —
@@ -324,7 +363,7 @@ export function createChannel(ctx, initialAgent, options) {
      */
     const deliverUserText = (text, placement) => {
         sendChain = sendChain.then(async () => {
-            const expansion = await expandMentions(mentionFs(ctx), state.cwd, text);
+            const expansion = await expandMentions(mentionFs(ctx), state.cwd, text, mentionAttachments(ctx), stagedImages);
             const message = createUserMessage({
                 content: expansion.blocks,
                 source: { kind: 'user' },
@@ -393,51 +432,191 @@ export function createChannel(ctx, initialAgent, options) {
             // provider default in effect.
         }
     };
-    /** Shift+Tab: cycle the live route's adapter-owned reasoning efforts in
-     *  the adapter's own display order (dsh parity — deepseek: Off→High→Max).
-     *  The choice persists to ~/.dsh-cc/effort.json and follows future agents
-     *  on this channel (resume/model switch re-validate it per route). */
-    const cycleEffort = async () => {
-        if (llmRuntime === undefined) {
-            state.notify(t('effort-unavailable'), { color: 'error' });
-            return;
-        }
-        let efforts;
-        let defaultEffort;
+    /** Resolve the live route's effort levels + adapter default through the
+     *  llm runtime; 'unavailable' when the service is unmounted, 'error' when
+     *  resolution throws (notified here). */
+    const resolveEfforts = async () => {
+        if (llmRuntime === undefined)
+            return 'unavailable';
         try {
             const info = await llmRuntime.resolveModelInfo(state.provider, state.model);
-            efforts = info.reasoning?.efforts ?? [];
-            defaultEffort = info.reasoning?.defaultEffort;
+            return {
+                efforts: info.reasoning?.efforts ?? [],
+                defaultEffort: info.reasoning?.defaultEffort,
+            };
         }
         catch (error) {
             state.notify(t('effort-read-failed', { error: error instanceof Error ? error.message : String(error) }), {
                 color: 'error',
                 timeoutMs: 8000,
             });
-            return;
-        }
-        if (efforts.length <= 1) {
-            state.notify(efforts.length === 1
-                ? t('effort-single-tier', { name: efforts[0].name })
-                : t('effort-unsupported'), { color: 'warning' });
-            return;
+            return 'error';
         }
-        // No explicit level yet = the adapter's materialized default is in
-        // effect; cycle from THERE, not from the top of the list.
-        const currentId = state.reasoningEffort ?? defaultEffort;
-        const currentIndex = efforts.findIndex(effort => effort.id === currentId);
-        const next = efforts[(currentIndex + 1) % efforts.length];
+    };
+    /** Pin one validated effort level on the live route: reroutes the next
+     *  request, persists the choice, and refreshes the StatusLine segment. */
+    const applyEffort = (effort) => {
         selection.current = {
             provider: state.provider,
             model: state.model,
-            reasoningEffort: ReasoningEffortId(next.id),
+            reasoningEffort: ReasoningEffortId(effort.id),
         };
-        preferredEffort = next.id;
-        state.reasoningEffort = next.id;
-        writeEffortPref(next.id);
-        state.notify(t('effort-switched', { name: next.name }));
+        preferredEffort = effort.id;
+        state.reasoningEffort = effort.id;
+        writeEffortPref(effort.id);
+        state.notify(t('effort-switched', { name: effort.name }));
+        state.emit();
+    };
+    /** The live route's effort levels for the `/effort` slider; empty after
+     *  notifying when the route is unsupported/unavailable/single-tier. */
+    const listEfforts = async () => {
+        const resolved = await resolveEfforts();
+        if (resolved === 'unavailable') {
+            state.notify(t('effort-unavailable'), { color: 'error' });
+            return { efforts: [], defaultEffort: undefined };
+        }
+        if (resolved === 'error')
+            return { efforts: [], defaultEffort: undefined };
+        if (resolved.efforts.length === 0) {
+            state.notify(t('effort-unsupported'), { color: 'warning' });
+        }
+        else if (resolved.efforts.length === 1) {
+            state.notify(t('effort-single-tier', { name: resolved.efforts[0].name }), { color: 'warning' });
+        }
+        return resolved;
+    };
+    /** Set one effort level by id (`/effort <id>` and the slider's live
+     *  apply); false + a notify when the id is not offered by the route. */
+    const setEffort = async (id) => {
+        const resolved = await resolveEfforts();
+        if (resolved === 'unavailable') {
+            state.notify(t('effort-unavailable'), { color: 'error' });
+            return false;
+        }
+        if (resolved === 'error')
+            return false;
+        if (resolved.efforts.length === 0) {
+            state.notify(t('effort-unsupported'), { color: 'warning' });
+            return false;
+        }
+        const found = resolved.efforts.find(effort => effort.id === id);
+        if (!found) {
+            state.notify(t('effort-invalid', { id, ids: resolved.efforts.map(effort => effort.id).join(', ') }), { color: 'warning' });
+            return false;
+        }
+        applyEffort(found);
+        return true;
+    };
+    /** Run one DSH registry command (`/plan`, …) on the live agent; the text
+     *  of its result, '' when the result is textless, undefined when the
+     *  command is not registered, and the error message when it throws. */
+    const executeRegistryCommand = async (name, rawInput) => {
+        if (!commandService)
+            return undefined;
+        try {
+            const execution = await commandService.execute(agent, `/${name}${rawInput}`, new AbortController().signal);
+            // `undefined` = not registered; a handler error surfaces as its
+            // message so the user sees why the command failed.
+            return execution?.result.text ?? '';
+        }
+        catch (error) {
+            return error instanceof Error ? error.message : String(error);
+        }
+    };
+    // 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(agent.session.events);
+        state.mode = sessionModes[state.modeIndex];
+    };
+    /** Apply one configured mode: each declared atom switches independently
+     *  (plan via the registry `/plan` command; sandbox/approval via their
+     *  durable session-log override events). A failing plan toggle aborts the
+     *  whole switch so the session never lands in a half-applied mode. */
+    const applyMode = async (spec) => {
+        if (spec.plan !== undefined && foldPlanActive(agent.session.events) !== spec.plan) {
+            const text = await executeRegistryCommand('plan', spec.plan ? '' : ' off');
+            if (text === undefined) {
+                // The active preset registers no /plan.
+                state.notify(t('mode-plan-unavailable'), { color: 'warning' });
+                return;
+            }
+        }
+        // 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(agent.session.events) !== spec.sandbox) {
+            ;
+            agent.session.append('sandbox/mode', { mode: spec.sandbox });
+        }
+        // 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(agent.session.events) !== spec.approval) {
+            const approval = ctx.get('approval');
+            if (approval) {
+                approval.setPolicy(agent, spec.approval);
+            }
+            else {
+                ;
+                agent.session.append('approval/policy', { policy: spec.approval });
+            }
+        }
+        refreshMode();
+        state.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 index = deriveModeIndex(agent.session.events);
+        await applyMode(sessionModes[(index + 1) % sessionModes.length]);
+    };
     const state = {
         version: 0,
         rows: [],
@@ -448,6 +627,7 @@ export function createChannel(ctx, initialAgent, options) {
         provider: options.provider,
         tokens: { input: 0, output: 0 },
         cwd: options.cwd,
+        displayCwd: workspaceService.describe(options.cwd).description ?? options.cwd,
         gitBranch: undefined,
         working: false,
         spinnerMode: 'requesting',
@@ -457,9 +637,13 @@ export function createChannel(ctx, initialAgent, options) {
         lastUserText: '',
         notifications: [],
         contextWindow: undefined,
-        // Explicit cordis.yml `effort` wins; otherwise the persisted Shift+Tab
+        // Explicit cordis.yml `effort` wins; otherwise the persisted /effort
         // choice; the first request/header event re-asserts the adapter's truth.
         reasoningEffort: options.effort ?? readEffortPref(),
+        // Session-mode seed; the first refreshMode() (bindAgent) re-derives it
+        // from the session log, so a resumed session lands on its recorded mode.
+        mode: sessionModes[0],
+        modeIndex: 0,
         workingActivity: undefined,
         activityFrames: options.activityFrames,
         activityEnabled: options.activity !== false,
@@ -470,6 +654,29 @@ export function createChannel(ctx, initialAgent, options) {
         loadedContext: undefined,
         pending: [],
         commandList: LOCAL_COMMANDS,
+        commandCompletions(input) {
+            return completeCommands(input, state.commandList, (path) => {
+                if (path.length === 1 && path[0] === 'workspace') {
+                    const builtins = [
+                        { name: 'resume', description: 'Switch to another workspace', descriptionKey: 'cmd-desc-workspace-resume' },
+                        { name: 'rename', description: 'Rename the current workspace', descriptionKey: 'cmd-desc-workspace-rename' },
+                        { name: 'open', description: 'Open a path or workspace URI', descriptionKey: 'cmd-desc-workspace-open' },
+                    ];
+                    const reserved = new Set(builtins.map(command => command.name));
+                    return [
+                        ...builtins,
+                        ...workspaceService.commands()
+                            .filter(command => !reserved.has(command.name.toLowerCase()))
+                            .map(command => ({
+                            name: command.name,
+                            aliases: command.aliases,
+                            description: command.description,
+                        })),
+                    ];
+                }
+                return commandTrees?.children(path) ?? [];
+            });
+        },
         lastUsage: undefined,
         tps: undefined,
         tpsSamples: [],
@@ -522,6 +729,30 @@ export function createChannel(ctx, initialAgent, options) {
                 state.emit();
             return restored;
         },
+        async stageImage(input) {
+            const attachments = mentionAttachments(ctx);
+            if (attachments === undefined)
+                throw new Error('image attachments are unavailable in this profile');
+            if (!attachments.imageLimits.mediaTypes.includes(input.mediaType)) {
+                throw new Error(`${input.mediaType} images are not accepted by this profile`);
+            }
+            if (input.data.byteLength > attachments.imageLimits.maxImageBytes) {
+                throw new Error(`image exceeds this profile's per-image size limit`);
+            }
+            const attachment = await attachments.saveImage(input);
+            stagedImageSequence += 1;
+            const token = `[Image #${stagedImageSequence}]`;
+            stagedImages.set(token, attachment);
+            // References are content-addressed and durable. This map only connects
+            // editable prompt placeholders to them; cap it to bound a long TUI run.
+            while (stagedImages.size > 128) {
+                const oldest = stagedImages.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                stagedImages.delete(oldest);
+            }
+            return token;
+        },
         submit(text) {
             const trimmed = text.trim();
             if (!trimmed)
@@ -619,7 +850,7 @@ export function createChannel(ctx, initialAgent, options) {
             const sessions = ctx.get('sessions');
             const agents = ctx.get('agents');
             if (!sessions || !agents) {
-                state.notify('Rewind unavailable — session services not loaded', { color: 'error' });
+                state.notify(t('rewind-unavailable'), { color: 'error' });
                 return null;
             }
             // Stop a running turn first and WAIT for its turn/end to land — fork
@@ -632,7 +863,7 @@ export function createChannel(ctx, initialAgent, options) {
             if (wasWorking) {
                 const turnSettled = await waitForTurnEnd(agent.session, cancelSeq, 30000);
                 if (!turnSettled) {
-                    state.notify('Cannot rewind — the turn is still settling, try again in a moment', { color: 'error' });
+                    state.notify(t('rewind-settling'), { color: 'error' });
                     return null;
                 }
             }
@@ -669,7 +900,7 @@ export function createChannel(ctx, initialAgent, options) {
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
-                state.notify(`Cannot rewind to this point · ${message}`, { color: 'error' });
+                state.notify(t('rewind-fork-failed', { err: message }), { color: 'error' });
                 return null;
             }
             let handle;
@@ -684,7 +915,7 @@ export function createChannel(ctx, initialAgent, options) {
                     sessionId: childId,
                     seed,
                     meta: {
-                        cwd: options.cwd,
+                        cwd: state.cwd,
                         parentSession: agent.session.id,
                         seedLength: seed.length,
                         ...(rewindComposed.agentPreset === undefined
@@ -696,9 +927,15 @@ export function createChannel(ctx, initialAgent, options) {
                 });
             }
             catch {
-                state.notify('Rewind failed — could not create the replacement session', { color: 'error' });
+                state.notify(t('rewind-create-failed'), { color: 'error' });
                 return null;
             }
+            try {
+                await attachSessionToWorkspace(ctx, state.cwd, childId);
+            }
+            catch (error) {
+                state.notify(t('rewind-attach-failed', { err: error instanceof Error ? error.message : String(error) }), { color: 'warning', timeoutMs: 8000 });
+            }
             // Replay the forked history into a fresh transcript (tokens/spinner
             // counters land back at the rewind point, matching the fork).
             streaming = undefined;
@@ -709,6 +946,11 @@ export function createChannel(ctx, initialAgent, options) {
             // Goal/todo/title are session-scoped; the replay re-derives them for
             // the session being entered (or leaves them empty).
             state.todos = [];
+            // Queued-but-undelivered messages live in the OLD agent's inbox; the
+            // swap must drop their previews or they linger forever (unretirable —
+            // retire events are filtered to the new agent, unwithdrawable — the
+            // new inbox never heard of them).
+            state.pending = [];
             state.goal = undefined;
             state.sessionTitle = '';
             state.tokens = { input: 0, output: 0 };
@@ -740,6 +982,7 @@ export function createChannel(ctx, initialAgent, options) {
             bindAgent();
             refreshCommandList();
             void refreshLoadedContext();
+            void refreshSkillCommands();
             // The forked session (rewind) becomes the most recently used.
             touchSession(childId);
             state.emit();
@@ -749,17 +992,24 @@ export function createChannel(ctx, initialAgent, options) {
         async resumeTo(sessionId) {
             // Switch the live agent to a persisted session: /resume picker Enter
             // loads the history immediately (the `--resume` launcher path keeps
-            // resolving through DSH_CC_RESUME_SESSION at boot).
+            // resolving through DSH_TUI_RESUME_SESSION at boot).
             if (state.working) {
-                state.notify('Cannot resume while a turn is running', { color: 'warning' });
+                state.notify(t('resume-while-working'), { color: 'warning' });
                 return false;
             }
             const agents = ctx.get('agents');
             if (!agents) {
-                state.notify('Resume unavailable — agents service not loaded', { color: 'error' });
+                state.notify(t('resume-unavailable'), { color: 'error' });
                 return false;
             }
             let handle;
+            // Compat boundary: register vouched-for legacy event types (e.g.
+            // activity/status from pre-#143 logs) in every reachable dsh-session
+            // copy before ANY strict read path (preset lookup below, then the
+            // harness seed validation) loads the target — the plugin's #119
+            // registration never ran in processes where it is unmounted (issue
+            // #153). In-process only: the shared log is never rewritten.
+            ensureLegacySessionEventTypes();
             // The target session's own preset (from its persisted log) — never the
             // current preference: a resume re-enters the composition its history
             // was produced under. Same rule for the route: only an explicit
@@ -773,9 +1023,6 @@ export function createChannel(ctx, initialAgent, options) {
                 model: options.configuredModel,
             });
             try {
-                // Compat boundary: mark third-party event types in the target log
-                // ignorable before the harness seed-validates it (src/compat/).
-                await prepareSessionForResume(sessionId);
                 handle = await agents.resume({
                     resumeSessionId: SessionId(sessionId),
                     agentOptions: { provider: resumeRoute?.provider, model: resumeRoute?.model },
@@ -784,9 +1031,18 @@ export function createChannel(ctx, initialAgent, options) {
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
-                state.notify(`Resume failed · ${message}`, { color: 'error', timeoutMs: 8000 });
+                state.notify(t('resume-failed', { err: message }), { color: 'error', timeoutMs: 8000 });
                 return false;
             }
+            try {
+                // `/resume` is an explicit adoption of this persisted conversation.
+                // This also repairs sessions created by TUI versions that predate the
+                // separate workspace ownership ledger.
+                await attachSessionToWorkspace(ctx, handle.agent.session.header.cwd ?? state.cwd, SessionId(sessionId));
+            }
+            catch (error) {
+                state.notify(t('resume-attach-failed', { err: error instanceof Error ? error.message : String(error) }), { color: 'warning', timeoutMs: 8000 });
+            }
             // Replay the persisted history into a fresh transcript (same reset as
             // rewindTo, plus the context window which the replay re-derives).
             streaming = undefined;
@@ -797,6 +1053,11 @@ export function createChannel(ctx, initialAgent, options) {
             // Goal/todo/title are session-scoped; the replay re-derives them for
             // the session being entered (or leaves them empty).
             state.todos = [];
+            // Queued-but-undelivered messages live in the OLD agent's inbox; the
+            // swap must drop their previews or they linger forever (unretirable —
+            // retire events are filtered to the new agent, unwithdrawable — the
+            // new inbox never heard of them).
+            state.pending = [];
             state.goal = undefined;
             state.sessionTitle = '';
             state.tokens = { input: 0, output: 0 };
@@ -807,6 +1068,15 @@ export function createChannel(ctx, initialAgent, options) {
             state.spinnerMode = 'requesting';
             state.status = handle.agent.status;
             state.agentId = handle.agent.id;
+            // Adopt the resumed session's persisted cwd (issue #96): pre-upgrade
+            // sessions recorded the LAUNCH directory (often a repo subdirectory),
+            // so keeping the freshly resolved root would split @ expansion / file
+            // completion (state.cwd) from the agent's own workspace record — and
+            // drop the session back out of the /resume filter. The branch
+            // breadcrumb follows the adopted cwd.
+            state.cwd = handle.agent.session.header.cwd ?? state.cwd;
+            state.displayCwd = workspaceService.describe(state.cwd).description ?? state.cwd;
+            refreshGitBranch();
             state.agentPreset = resumeComposed.agentPreset;
             // Status-line route follows the resumed session (review feedback): the
             // route it actually continues on — a complete cordis.yml pin, else the
@@ -839,12 +1109,14 @@ export function createChannel(ctx, initialAgent, options) {
             bindAgent();
             refreshCommandList();
             void refreshLoadedContext();
+            void refreshSkillCommands();
             // Keep the `--resume` launcher contract pointing at the same session.
             writeResumeTarget(sessionId);
             // The resumed session is now the most recently used.
             touchSession(sessionId);
             state.emit();
             void oldHandle?.dispose().catch(() => { });
+            clearStagedImages();
             return true;
         },
         async newSession() {
@@ -852,14 +1124,14 @@ export function createChannel(ctx, initialAgent, options) {
             // transcript reset, the `--resume` marker forgotten (the old session
             // stays persisted for /resume). Same reset shape as rewindTo/resumeTo.
             if (state.working) {
-                state.notify('Cannot start a new session while a turn is running', {
+                state.notify(t('new-session-while-working'), {
                     color: 'warning',
                 });
                 return false;
             }
             const agents = ctx.get('agents');
             if (!agents) {
-                state.notify('New session unavailable — agents service not loaded', {
+                state.notify(t('new-session-unavailable'), {
                     color: 'error',
                 });
                 return false;
@@ -893,7 +1165,7 @@ export function createChannel(ctx, initialAgent, options) {
                 handle = await agents.create({
                     sessionId,
                     meta: {
-                        cwd: options.cwd,
+                        cwd: state.cwd,
                         ...(newComposed.agentPreset === undefined
                             ? {}
                             : { agentPreset: newComposed.agentPreset }),
@@ -904,12 +1176,18 @@ export function createChannel(ctx, initialAgent, options) {
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
-                state.notify(`New session failed · ${message}`, {
+                state.notify(t('new-session-failed', { err: message }), {
                     color: 'error',
                     timeoutMs: 8000,
                 });
                 return false;
             }
+            try {
+                await attachSessionToWorkspace(ctx, state.cwd, sessionId);
+            }
+            catch (error) {
+                state.notify(t('new-session-attach-failed', { err: error instanceof Error ? error.message : String(error) }), { color: 'warning', timeoutMs: 8000 });
+            }
             streaming = undefined;
             reasoning = undefined;
             toolCards.clear();
@@ -918,6 +1196,11 @@ export function createChannel(ctx, initialAgent, options) {
             // Goal/todo/title are session-scoped; the replay re-derives them for
             // the session being entered (or leaves them empty).
             state.todos = [];
+            // Queued-but-undelivered messages live in the OLD agent's inbox; the
+            // swap must drop their previews or they linger forever (unretirable —
+            // retire events are filtered to the new agent, unwithdrawable — the
+            // new inbox never heard of them).
+            state.pending = [];
             state.goal = undefined;
             state.sessionTitle = '';
             state.tokens = { input: 0, output: 0 };
@@ -949,20 +1232,79 @@ export function createChannel(ctx, initialAgent, options) {
             bindAgent();
             refreshCommandList();
             void refreshLoadedContext();
+            void refreshSkillCommands();
             clearResumeTarget();
             // The brand-new session becomes the most recently used.
             touchSession(handle.agent.id);
-            state.emit();
             void oldHandle?.dispose().catch(() => { });
+            clearStagedImages();
+            return true;
+        },
+        listWorkspaces() {
+            return workspaceService.list(state.cwd);
+        },
+        resolveWorkspace(uri) {
+            return workspaceService.resolve(uri, state.cwd);
+        },
+        async switchWorkspace(target) {
+            if (state.working) {
+                state.notify(t('workspace-switch-working'), { color: 'warning' });
+                return false;
+            }
+            // Local targets must exist and be directories — creating a session in
+            // a typo'd cwd "succeeds" and then every file tool errors per call.
+            if (target.kind === 'local') {
+                try {
+                    if (!statSync(target.cwd).isDirectory())
+                        throw new Error('not a directory');
+                }
+                catch {
+                    state.notify(t('workspace-open-invalid', { target: target.label }), { color: 'error', timeoutMs: 8000 });
+                    return false;
+                }
+            }
+            const previousCwd = state.cwd;
+            const previousDisplay = state.displayCwd;
+            state.cwd = target.cwd;
+            state.displayCwd = target.description ?? target.uri;
+            const switched = await state.newSession();
+            if (!switched) {
+                state.cwd = previousCwd;
+                state.displayCwd = previousDisplay;
+                return false;
+            }
+            // The breadcrumb follows the adopted cwd, same as /resume (#96).
+            refreshGitBranch();
+            state.notify(t('workspace-switched', { target: target.label }));
+            state.emit();
             return true;
         },
+        async renameWorkspace(title) {
+            try {
+                const renamed = await workspaceService.rename(state.cwd, title);
+                state.displayCwd = renamed.description ?? renamed.uri;
+                state.notify(t('workspace-renamed', { title: renamed.label }));
+                state.emit();
+                return true;
+            }
+            catch (error) {
+                state.notify(t('workspace-rename-failed', { err: error instanceof Error ? error.message : String(error) }), { color: 'error', timeoutMs: 8000 });
+                return false;
+            }
+        },
+        workspaceCommands() {
+            return workspaceService.commands();
+        },
+        runWorkspaceCommand(name, input) {
+            return workspaceService.runCommand(name, input, state.cwd);
+        },
         async switchModel(provider, model) {
             // `/model` picker Enter — switch the live model by forking the
             // conversation at its current end and continuing with a new agent
             // routed to the chosen model. Same reset shape as rewindTo/resumeTo;
             // the history replays unchanged, only the request model changes.
             if (state.working) {
-                state.notify('Cannot switch models while a turn is running', {
+                state.notify(t('model-switch-while-working'), {
                     color: 'warning',
                 });
                 return false;
@@ -970,7 +1312,7 @@ export function createChannel(ctx, initialAgent, options) {
             const sessions = ctx.get('sessions');
             const agents = ctx.get('agents');
             if (!sessions || !agents) {
-                state.notify('Model switch unavailable — session services not loaded', {
+                state.notify(t('model-switch-unavailable'), {
                     color: 'error',
                 });
                 return false;
@@ -982,7 +1324,7 @@ export function createChannel(ctx, initialAgent, options) {
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
-                state.notify(`Cannot switch models · ${message}`, { color: 'error' });
+                state.notify(t('model-switch-fork-failed', { err: message }), { color: 'error' });
                 return false;
             }
             const childId = SessionId(randomUUID());
@@ -995,7 +1337,7 @@ export function createChannel(ctx, initialAgent, options) {
                     sessionId: childId,
                     seed,
                     meta: {
-                        cwd: options.cwd,
+                        cwd: state.cwd,
                         parentSession: agent.session.id,
                         seedLength: seed.length,
                         ...(modelComposed.agentPreset === undefined
@@ -1008,9 +1350,15 @@ export function createChannel(ctx, initialAgent, options) {
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
-                state.notify(`Model switch failed · ${message}`, { color: 'error', timeoutMs: 8000 });
+                state.notify(t('model-switch-failed', { err: message }), { color: 'error', timeoutMs: 8000 });
                 return false;
             }
+            try {
+                await attachSessionToWorkspace(ctx, state.cwd, childId);
+            }
+            catch (error) {
+                state.notify(t('model-switch-attach-failed', { err: error instanceof Error ? error.message : String(error) }), { color: 'warning', timeoutMs: 8000 });
+            }
             streaming = undefined;
             reasoning = undefined;
             toolCards.clear();
@@ -1019,6 +1367,11 @@ export function createChannel(ctx, initialAgent, options) {
             // Goal/todo/title are session-scoped; the replay re-derives them for
             // the session being entered (or leaves them empty).
             state.todos = [];
+            // Queued-but-undelivered messages live in the OLD agent's inbox; the
+            // swap must drop their previews or they linger forever (unretirable —
+            // retire events are filtered to the new agent, unwithdrawable — the
+            // new inbox never heard of them).
+            state.pending = [];
             state.goal = undefined;
             state.sessionTitle = '';
             state.tokens = { input: 0, output: 0 };
@@ -1053,12 +1406,13 @@ export function createChannel(ctx, initialAgent, options) {
             bindAgent();
             refreshCommandList();
             void refreshLoadedContext();
+            void refreshSkillCommands();
             // The model-switched fork becomes the most recently used.
             touchSession(childId);
             state.emit();
             void oldHandle?.dispose().catch(() => { });
             // Persist the choice so the next boot and `/new` start on it (same
-            // contract as /preset and Shift+Tab effort; issues #14/#30). A failed
+            // contract as /preset and /effort; issues #14/#30). A failed
             // write keeps the live switch but warns it will not survive a restart.
             if (!writeModelPref(provider, model)) {
                 state.notify(t('model-pref-write-failed'), {
@@ -1067,7 +1421,9 @@ export function createChannel(ctx, initialAgent, options) {
             }
             return true;
         },
-        cycleEffort,
+        listEfforts,
+        setEffort,
+        cycleMode,
         clear() {
             state.rows.length = 0;
             nextRowId = 0;
@@ -1210,6 +1566,105 @@ export function createChannel(ctx, initialAgent, options) {
             return Promise.all(providers.map(provider => llm.listModels(provider.id).catch(() => [])))
                 .then(lists => lists.flat());
         },
+        providerSetup() {
+            // The `/provider` wizard's runtime surface, over the dsh-base seams:
+            // settings (profile persistence), credentials (key storage) and the
+            // llm runtime's configurable-provider directory + model discovery.
+            // Structurally typed like the other optional seams in this file.
+            const llm = ctx.get('llm');
+            const settings = ctx.get('settings');
+            const credentials = ctx.get('credentials');
+            // Without dsh-llm-pi-ai there is no adapter watching the settings
+            // section, so a written profile would never activate a route. The
+            // adapter registers its `llm-pi-ai` settings namespace at mount, which
+            // is the rc.6-observable mount signal (the newer
+            // `listModelDiscoveryNamespaces()` does not exist in rc.6).
+            if (!llm || !settings || !credentials
+                || !settings.describe().some(descriptor => descriptor.ns === 'llm-pi-ai')) {
+                return undefined;
+            }
+            const revision = () => settings.describe().find(descriptor => descriptor.ns === 'llm-pi-ai')?.revision;
+            return {
+                listCatalogProviders() {
+                    // declared === true marks routes the adapter knows only because a
+                    // stored profile names them (user-added); the rest are activatable
+                    // catalog routes.
+                    return llm.listConfigurableProviders()
+                        .filter(entry => entry.settingsNs === 'llm-pi-ai' && entry.declared !== true)
+                        .map(entry => ({ provider: entry.provider, displayName: entry.displayName }));
+                },
+                routeExists(route) {
+                    const section = settings.get('llm-pi-ai');
+                    return section?.providers !== undefined && route in section.providers;
+                },
+                discoverModels(request) {
+                    return llm.discoverModels('llm-pi-ai', request);
+                },
+                envShadows(ref) {
+                    return process.env[ref] !== undefined;
+                },
+                async readCredential(ref) {
+                    const resolved = await credentials.resolve(ref);
+                    return resolved?.value;
+                },
+                writeCredential(ref, value) {
+                    return credentials.set(ref, value);
+                },
+                removeCredential(ref) {
+                    return credentials.unset(ref);
+                },
+                async writeProfile(route, profile) {
+                    const ops = [{ op: 'set', path: ['providers', route], value: profile }];
+                    try {
+                        await settings.mutate('llm-pi-ai', ops, revision());
+                    }
+                    catch (error) {
+                        // One retry on a stale-revision conflict (a concurrent write
+                        // landed between describe and mutate); anything else propagates
+                        // so the wizard can report and roll back the credential.
+                        const code = error?.code;
+                        if (code !== 'SETTINGS_CONFLICT')
+                            throw error;
+                        await settings.mutate('llm-pi-ai', ops, revision());
+                    }
+                },
+            };
+        },
+        async sideQuestion(question, options) {
+            // CC /btw：无工具单轮辅助调用，重放 deriveMessages() 前缀 + 一条
+            // 包装问题。tools 永不传（侧问无工具是核心语义）；usage 不回收
+            // （skipCacheWrite 同义——答案不进主上下文也不进 token 计数）。
+            const llm = ctx.get('llm');
+            if (!llm)
+                return { answer: null, error: t('btw-llm-unavailable') };
+            const header = agent.session.requestHeader();
+            const config = header?.config;
+            const messages = [
+                ...agent.session.deriveMessages(),
+                createUserMessage({
+                    content: [{ type: 'text', text: wrapSideQuestion(question) }],
+                    source: { kind: 'plugin', plugin: 'dsh-tui/btw' },
+                }),
+            ];
+            const request = {
+                provider: config?.provider ?? state.provider,
+                model: config?.model ?? state.model,
+                messages,
+                ...(header?.system !== undefined && { system: header.system }),
+                ...(config?.reasoningEffort !== undefined && { reasoningEffort: config.reasoningEffort }),
+                ...(config?.temperature !== undefined && { temperature: config.temperature }),
+                ...(config?.maxTokens !== undefined && { maxTokens: config.maxTokens }),
+                ...(config?.stop !== undefined && { stop: [...config.stop] }),
+                sessionId: agent.session.id,
+                ...(options?.signal && { signal: options.signal }),
+            };
+            return runSideQuestion({
+                stream: llm.stream.bind(llm),
+                options: request,
+                onText: options?.onText,
+                signal: options?.signal,
+            });
+        },
         listFiles() {
             const fs = ctx.get('fs');
             return listFilesDeep(fs, state.cwd);
@@ -1224,8 +1679,7 @@ export function createChannel(ctx, initialAgent, options) {
                 const headers = await persistence.list();
                 // 按工作目录隔离（Claude Code 的项目维度）：/resume 只列出本会话
                 // 目录启动的会话，别的项目的会话不出现在选择器里。
-                const cwd = state.cwd.replace(/\/+$/, '');
-                const local = headers.filter(header => (header.cwd ?? '').replace(/\/+$/, '') === cwd);
+                const local = headers.filter(header => sessionCwdMatches(state.cwd, header.cwd ?? ''));
                 // MRU ordering: DSH headers carry only createdAt, so dsh-tui keeps its
                 // own last-used timestamps (touchSession on resume/submit/new) and
                 // falls back to createdAt for sessions never touched in this install.
@@ -1247,8 +1701,8 @@ export function createChannel(ctx, initialAgent, options) {
                 // useful label. Read via the tolerant compat log reader instead of
                 // persistence.load: the backend validates every event against
                 // KNOWN_SESSION_EVENT_TYPES and throws the whole load on an unmarked
-                // third-party type (activity/status before resume-repair), which used
-                // to leave every working-activity session titled with the cwd
+                // an unregistered third-party type, which would otherwise leave the
+                // affected session titled with the cwd
                 // basename. An unreadable log keeps the basename fallback.
                 const empty = new Set();
                 for (const record of records.slice(0, SESSION_TITLE_DEPTH)) {
@@ -1284,6 +1738,41 @@ export function createChannel(ctx, initialAgent, options) {
             state.sessionTitle = title;
             state.emit();
         },
+        async deleteSession(sessionId) {
+            // The live session's log is still being appended by this process —
+            // deleting it from under the writer is never offered in the picker
+            // (the current session is filtered out), so refuse it here too.
+            if (sessionId === agent.session.id)
+                return false;
+            if (deleteSessionLog(sessionId) !== 'deleted')
+                return false;
+            forgetSession(sessionId);
+            // A resume marker naming the deleted session would make the next
+            // `dsh-tui --resume` launch target a log that no longer exists.
+            if (readResumeTarget() === sessionId)
+                clearResumeTarget();
+            return true;
+        },
+        async renameSessionTo(sessionId, title) {
+            if (sessionId === agent.session.id) {
+                // The live session renames through session.append so the firehose
+                // updates the status line right away (same as /rename).
+                agent.session.append('session/title', { title });
+                state.sessionTitle = title;
+                state.emit();
+                return true;
+            }
+            if (appendSessionTitle(sessionId, title) !== 'appended')
+                return false;
+            // listSessions resolves persisted titles only for the MRU top
+            // SESSION_TITLE_DEPTH; a rename does not change MRU by itself, so a
+            // session beyond the window would keep showing the cwd-basename
+            // fallback (in the next picker AND after restart) even though the
+            // title event is durable. A rename IS user interaction with the
+            // session — touching it pulls it into the title window.
+            touchSession(sessionId);
+            return true;
+        },
         compact() {
             // DSH compaction service key: `ctx.compaction` (dsh-compaction's
             // CompactionEngine; dsh-compaction-basic provides it in the example
@@ -1292,38 +1781,28 @@ export function createChannel(ctx, initialAgent, options) {
             // scope chain first (minimal composes NO compaction: stays unavailable).
             const compactService = serviceForAgent(ctx, agent, 'compaction');
             if (!compactService) {
-                state.notify('Compaction unavailable · no compaction service in this leaf', {
+                state.notify(t('compact-unavailable'), {
                     color: 'warning',
                 });
                 return;
             }
             if (state.working) {
-                state.notify('Cannot compact while a turn is running', { color: 'warning' });
+                state.notify(t('compact-while-working'), { color: 'warning' });
                 return;
             }
             const signal = new AbortController().signal;
-            state.notify('Compacting conversation…');
+            state.notify(t('compact-working'));
             void compactService
                 .compactNow(agent, signal)
                 .then((result) => {
-                state.notify(result ? 'Conversation compacted' : 'Nothing to compact');
+                state.notify(result ? t('compact-done') : t('compact-nothing'));
             })
                 .catch((error) => {
-                state.notify(`Compaction failed · ${error instanceof Error ? error.message : String(error)}`, { color: 'error', timeoutMs: 8000 });
+                state.notify(t('compact-failed', { err: error instanceof Error ? error.message : String(error) }), { color: 'error', timeoutMs: 8000 });
             });
         },
-        async runExternalCommand(name, rawInput) {
-            if (!commandService)
-                return undefined;
-            try {
-                const execution = await commandService.execute(agent, `/${name}${rawInput}`, new AbortController().signal);
-                // `undefined` = not registered; a handler error surfaces as its
-                // message so the user sees why the command failed.
-                return execution?.result.text ?? '';
-            }
-            catch (error) {
-                return error instanceof Error ? error.message : String(error);
-            }
+        runExternalCommand(name, rawInput) {
+            return executeRegistryCommand(name, rawInput);
         },
         pushLocal(title, lines) {
             state.rows.push({ id: nextRowId++, kind: 'local', text: title });
@@ -1464,16 +1943,24 @@ export function createChannel(ctx, initialAgent, options) {
             lines.push(t('doctor-cwd', { cwd: state.cwd }));
             lines.push(t('doctor-context-window', { window: state.contextWindow ?? t('doctor-unknown') }));
             lines.push(`${t('doctor-session', { id: state.agentId })}${state.sessionTitle ? ' · ' + state.sessionTitle : ''}`);
-            const userHome = process.env.USERPROFILE ?? homedir();
+            const userHome = homeDir();
             const configCandidates = [
-                join(userHome, '.dsh-cc/cordis.yml'),
+                join(userHome, '.dsh-tui/cordis.yml'),
                 join(userHome, '.dsh/profiles/dsh-tui/cordis.patch.yml'),
             ];
             for (const candidate of configCandidates) {
                 lines.push(`${t('doctor-config', { candidate, state: existsSync(candidate) ? '✓' : t('doctor-config-missing') })}`);
             }
-            const sessionsDir = join(userHome, '.dsh-cc/sessions');
-            lines.push(`${t('doctor-storage', { dir: sessionsDir, state: existsSync(sessionsDir) ? '✓' : t('doctor-storage-uninit') })}`);
+            // Session store candidates mirror the compat layer (sessionsRoots):
+            // the active root depends on the composition (bare cordis.yml →
+            // legacy ~/.dsh-tui, profile → $DSH_HOME/sessions), so list every
+            // candidate with its own state instead of hardcoding one.
+            for (const dir of sessionsRoots()) {
+                lines.push(`${t('doctor-storage', { dir, state: existsSync(dir) ? '✓' : t('doctor-storage-uninit') })}`);
+            }
+            if (existsSync(LEGACY_DATA_DIR)) {
+                lines.push(t('doctor-legacy-dir'));
+            }
             return lines;
         },
         async listSubagents() {
@@ -1495,6 +1982,14 @@ export function createChannel(ctx, initialAgent, options) {
                 return [t('subagent-query-failed', { err: error instanceof Error ? error.message : String(error) })];
             }
         },
+        releaseContributions() {
+            releaseSkillCommands();
+        },
+        traceEvents() {
+            // Immutable per-append snapshot (dsh-session caches the frozen array);
+            // reads follow agent swaps (/resume /rewind /new) automatically.
+            return agent.session.events;
+        },
     };
     /**
      * Assemble the context a fresh conversation for the live agent will load,
@@ -1536,10 +2031,20 @@ export function createChannel(ctx, initialAgent, options) {
                     tools.push({ name: tool.name, description: tool.description ?? '' });
                 }
             }
-            const discovered = await discoverBaselineInstructionFiles({ cwd: options.cwd });
+            const renderedInstructions = await loadBaselineInstructions({
+                cwd: state.cwd,
+                maxBytes: 1024 * 1024,
+                maxSourceBytes: 1024 * 1024,
+            }, ctx.get('fs'));
             if (target !== agent)
                 return;
-            files.push(...discovered.map(file => ({ displayPath: file.displayPath })));
+            const instructionSources = renderedInstructions;
+            const instructionPaths = new Set([
+                ...(instructionSources?.represented ?? []).map(file => file.displayPath),
+                ...(renderedInstructions?.omitted ?? []).map(file => file.displayPath),
+                ...(renderedInstructions?.truncated ?? []).map(file => file.displayPath),
+            ]);
+            files.push(...[...instructionPaths].map(displayPath => ({ displayPath })));
             // The skills registry is host-plane but scope-layered: preset rows
             // (skill-filesystem) register into the preset's layer, so the catalog
             // must be read through the agent's scope chain (serviceForAgent falls
@@ -1563,51 +2068,289 @@ export function createChannel(ctx, initialAgent, options) {
         state.emit();
     };
     /**
-     * Rebuild the merged slash-command list from the registry. Registry
-     * registrations are global or agent-scoped, so this runs on
-     * `commands/change` and again whenever the live agent is swapped
-     * (rewind/resume).
+     * Rebuild the merged slash-command list: built-in locals, then registry
+     * commands (plan/goal/…), then user-invocable skills from the DSH skill
+     * registry (issue #86 — filesystem-discovered skills must appear in the
+     * `/` menu and Tab completion, like /audit and /review). Skill entries
+     * are completion-only: dispatch falls through to the model as plain text,
+     * where dsh-tool-skill's pre-step hook injects the skill body — the same
+     * path a hand-typed `/skill-name` takes. Registry and skill reads are
+     * scoped to the LIVE agent, so this runs on `commands/change` +
+     * `skills/change` and again whenever the live agent is swapped
+     * (rewind/resume/new/model). A failed skill read restores the last
+     * successfully merged skill set for the same agent (last-good), so a
+     * transient provider failure never makes known skills vanish.
      */
+    let commandListSeq = 0;
+    /**
+     * The last successfully merged skill entries, tagged with the agent whose
+     * scope produced them. A failed catalog read restores these instead of
+     * dropping skill entries from the menu until the next successful refresh
+     * (last-good); the agent tag refuses cross-agent restores — a different
+     * scope's skills may not exist for the live agent at all.
+     */
+    let lastGoodSkills;
     const refreshCommandList = () => {
+        const target = agent;
+        const token = ++commandListSeq;
         const merged = [...LOCAL_COMMANDS];
         if (commandService) {
-            for (const descriptor of commandService.list(agent)) {
+            for (const descriptor of commandService.list(target)) {
                 if (merged.some(command => command.name === descriptor.name))
                     continue;
+                const descriptions = commandTrees?.descriptions(descriptor.name);
                 merged.push({
                     name: descriptor.name,
                     description: descriptor.description,
+                    ...(descriptions === undefined ? {} : { descriptions }),
                     tag: descriptor.input?.hint,
                     external: true,
+                    // Skills reach the registry as ordinary commands, so the menu would
+                    // lose the marker HelpMenu uses to keep them out of the chrome list.
+                    // This channel registered them and is the authority on which names
+                    // are skills.
+                    ...(skillCommands.has(descriptor.name) ? { skill: true } : {}),
                 });
             }
         }
         state.commandList = merged;
         state.emit();
+        // The skill catalog resolves asynchronously (filesystem providers scan
+        // their roots), so skills append in a continuation; a newer refresh or
+        // an agent swap supersedes this run (token/identity check, same rule as
+        // refreshLoadedContext). Locals and registry commands win name
+        // collisions — a skill named `plan` must not shadow the registry's.
+        const skillsService = serviceForAgent(ctx, target, 'skills');
+        if (skillsService === undefined)
+            return;
+        /** Last-good restore shared by the failed-read and incomplete-read
+         *  paths; the caller holds the staleness check. */
+        const restoreLastGood = () => {
+            const fallback = lastGoodSkills?.agent === target ? lastGoodSkills.commands : [];
+            const restored = fallback.filter(entry => !merged.some(command => command.name === entry.name));
+            if (restored.length === 0)
+                return;
+            state.commandList = [...merged, ...restored];
+            state.emit();
+        };
+        // snapshot() over list(): only a COMPLETE observation is authoritative
+        // — list() discards `complete`, so a provider failure or a rescan still
+        // in flight would resolve as a partial/empty catalog and wrongly clear
+        // the last-good set (dsh-skill's own consumer contract).
+        void skillsService.snapshot({
+            scope: target,
+            cwd: target.session.header?.cwd ?? state.cwd,
+        }).then((observation) => {
+            if (token !== commandListSeq || target !== agent)
+                return;
+            if (!observation.complete) {
+                // Incomplete (provider failure/rescan mid-flight): NOT authoritative
+                // — never clear last-good or repopulate from the partial catalog.
+                // The provider's next invalidate fires skills/change for the retry.
+                ctx.logger.warn('skill command merge: incomplete catalog observation, keeping last-good skills');
+                restoreLastGood();
+                return;
+            }
+            const withSkills = [...merged];
+            for (const skill of observation.skills) {
+                if (!isUserInvocable(skill))
+                    continue;
+                if (withSkills.some(command => command.name === skill.name))
+                    continue;
+                withSkills.push({ name: skill.name, description: skill.description, skill: true });
+            }
+            const added = withSkills.slice(merged.length);
+            lastGoodSkills = { agent: target, commands: added };
+            // The sync phase already assigned `merged`; a complete read that adds
+            // nothing leaves the state as-is (and authoritatively clears the
+            // last-good set above).
+            if (added.length === 0)
+                return;
+            state.commandList = withSkills;
+            state.emit();
+        }).catch((error) => {
+            // A superseded read (a newer refresh or an agent swap beat it) says
+            // nothing about the live menu: stay silent instead of logging a
+            // misleading failure warning.
+            if (token !== commandListSeq || target !== agent)
+                return;
+            ctx.logger.warn('skill command merge failed: %o', error);
+            // Last-good: a transient provider failure (rescan error, permission
+            // hiccup) must not make known skills vanish from completion.
+            restoreLastGood();
+        });
     };
     ctx.on('commands/change', refreshCommandList);
+    ctx.on('skills/change', refreshCommandList);
+    /**
+     * The view a skill-catalog read must be taken through, as ONE value.
+     *
+     * The registry is host-plane but scope-LAYERED: a provider mounted by an
+     * agent preset's standing composition files into that preset's layer, and a
+     * read taken without the scope sees only the host layer. Passing the pair
+     * together keeps a read from being taken half-scoped.
+     *
+     * @param target - the agent whose view is wanted.
+     */
+    const skillViewOptions = (target) => ({
+        scope: target,
+        cwd: state.cwd,
+    });
+    /** The skill registry as the given agent sees it, or undefined when a boot
+     *  mounts none. `serviceForAgent` resolves through the agent's mount and
+     *  falls back to the host context. */
+    const skillRegistryFor = (target) => serviceForAgent(ctx, target, 'skills');
+    /**
+     * Skill commands this channel owns, by skill name. The value keeps the
+     * description the command was registered with so an edited SKILL.md
+     * re-registers instead of leaving a stale menu entry.
+     */
+    const skillCommands = new Map();
+    /** Skill names the registry refused (name taken, or invalid) — warn once. */
+    const skillCommandsRefused = new Set();
+    /** Pending re-read after an incomplete catalog observation. */
+    let skillCommandsRetry;
+    /**
+     * Publish every user-invocable skill as a slash command (issue #86).
+     *
+     * The completion menu already lists these skills, but a menu entry is not a
+     * command: nothing dispatches it, so typing the name and pressing Enter does
+     * nothing. Registering through the host command registry is what makes them
+     * runnable, and buys three things the TUI would otherwise reimplement:
+     * `register` emits `commands/change`, so the menu merge folds the entry in
+     * on its own; Enter dispatches through the normal command path, so the
+     * invocation is logged as a paired `command/run`/`command/done` like every
+     * other command; and the handler runs host-side, so invoking a skill is
+     * DETERMINISTIC — the body is injected here, instead of sending `/name` to
+     * the model and depending on it to recognize the text and reach for its
+     * skill loader.
+     *
+     * `userInvocable` covers "human-facing command catalogs AND loaders", so
+     * discovery alone would honor half the flag.
+     */
+    const refreshSkillCommands = async () => {
+        if (commandService === undefined)
+            return;
+        const target = agent;
+        const registry = skillRegistryFor(target);
+        if (registry === undefined)
+            return;
+        let observation;
+        try {
+            observation = await registry.snapshot(skillViewOptions(target));
+        }
+        catch (error) {
+            ctx.logger.warn('skill commands: catalog read failed: %o', error);
+            return;
+        }
+        if (target !== agent)
+            return;
+        // A provider still warming its watcher reports an incomplete observation;
+        // re-read once so a cold start cannot leave the menu permanently short.
+        if (!observation.complete && skillCommandsRetry === undefined) {
+            skillCommandsRetry = setTimeout(() => {
+                skillCommandsRetry = undefined;
+                void refreshSkillCommands();
+            }, SKILL_COMMAND_RETRY_MS);
+        }
+        const wanted = new Map(observation.skills
+            .filter(skill => isUserInvocable(skill))
+            // A name the TUI's own command grammar cannot parse would show in the
+            // menu and then fail to dispatch when typed; ask the real parser
+            // instead of restating its pattern here.
+            .filter(skill => parseCommandName(`/${skill.name}`)?.name === skill.name)
+            // Built-in locals win a name collision, exactly as they do over
+            // plugin-registered commands in refreshCommandList.
+            .filter(skill => !isLocalCommandName(skill.name))
+            .map(skill => [skill.name, skill.description]));
+        for (const [name, entry] of skillCommands) {
+            if (wanted.get(name) === entry.description)
+                continue;
+            entry.dispose();
+            skillCommands.delete(name);
+        }
+        for (const [name, description] of wanted) {
+            if (skillCommands.has(name) || skillCommandsRefused.has(name))
+                continue;
+            // Another plugin already owns this name (plan/goal/…): leave it alone.
+            if (commandService.find(target, name) !== undefined)
+                continue;
+            try {
+                const dispose = commandService.register({
+                    name,
+                    description,
+                    // The injected body is the payload; recording the (empty) raw input
+                    // would only duplicate the command name into the session log.
+                    recordInput: false,
+                    handler: async ({ agent: invoker, signal }) => {
+                        const view = { ...skillViewOptions(invoker), signal };
+                        const skill = await skillRegistryFor(invoker)?.get(name, view);
+                        if (skill === undefined || !isUserInvocable(skill)) {
+                            return { kind: 'error', text: t('skill-unavailable', { name }) };
+                        }
+                        // The official user-explicit invocation shape (dsh-skill's
+                        // SkillInvocationSource): the rendered body rides as instructions
+                        // the model follows, and transcript consumers present it from the
+                        // source metadata instead of re-parsing model-facing text.
+                        invoker.followup(createUserMessage({
+                            content: [{ type: 'text', text: renderSkillContent(skill) }],
+                            source: { kind: 'skill-invocation', name, form: 'instructions' },
+                        }));
+                        // Silent success: the agent visibly starts working on the skill,
+                        // which is the feedback (CC shows no banner either).
+                        return { kind: 'success' };
+                    },
+                });
+                skillCommands.set(name, { dispose, description });
+            }
+            catch (error) {
+                skillCommandsRefused.add(name);
+                ctx.logger.warn(`skill commands: "${name}" not registrable: %o`, error);
+            }
+        }
+    };
+    ctx.on('skills/change', () => {
+        void refreshSkillCommands();
+    });
+    /** See {@link Channel.releaseContributions}. */
+    const releaseSkillCommands = () => {
+        if (skillCommandsRetry !== undefined)
+            clearTimeout(skillCommandsRetry);
+        skillCommandsRetry = undefined;
+        for (const entry of skillCommands.values())
+            entry.dispose();
+        skillCommands.clear();
+    };
     refreshCommandList();
     void refreshLoadedContext();
+    void refreshSkillCommands();
     let nextRowId = 0;
     /** The leaf's bash executor (dsh-bash-local in the example leaf) — the DSH
    *  execution seam for local `!` commands and the git status breadcrumb. The
    *  service registers under `ctx.shell` (ShellExecutor; dsh-bash-local and
    *  dsh-pwsh-local are the providers). */
     const bash = ctx.get('shell');
-    /** Claude Code's `!` mode: run a command on the user's machine and render its
-   *  output in the transcript as local rows (never sent to the model). */
+    /** Claude Code's `!` mode: execute in the current workspace provider and
+     *  render local-only transcript rows (never sent to the model). */
     const runLocalCommand = async (command, includeInContext) => {
-        state.rows.push({ id: nextRowId++, kind: 'local', text: command });
+        const workspace = workspaceService.describe(state.cwd);
+        state.rows.push({
+            id: nextRowId++,
+            kind: 'local',
+            text: command,
+            executionTarget: workspace.kind === 'local' ? workspace.badge : `${workspace.badge} · ${workspace.label}`,
+        });
         state.emit();
         let output = '(no output)';
-        if (bash) {
+        const executionShell = await workspaceService.commandShell(state.cwd) ?? bash;
+        if (executionShell) {
             try {
-                const spec = bash.resolve({
+                const spec = executionShell.resolve({
                     command,
                     workdir: state.cwd,
                     timeoutMs: 30000,
                 });
-                const result = await bash.run(spec);
+                const result = await executionShell.run(spec);
                 output =
                     result.stdout.text.trim() ||
                         result.stderr.text.trim() ||
@@ -2009,7 +2752,7 @@ ${output}
                     const failure = event.data.error;
                     if (failure !== undefined) {
                         card.tool.status = 'error';
-                        const errorText = `${failure.name}: ${failure.code}`;
+                        const errorText = toolErrorText(event);
                         card.tool.errorText = errorText;
                         state.contextSegments.tools += estimateTokens(errorText);
                     }
@@ -2094,7 +2837,7 @@ ${output}
                     state.rows.push({
                         id: nextRowId,
                         kind: 'interrupt',
-                        text: 'Interrupted · What should Claude do instead?',
+                        text: t('interrupted-by-user') + t('interrupted-ask-next'),
                     });
                     nextRowId += 1;
                     break;
@@ -2102,7 +2845,7 @@ ${output}
                 const detail = reason.kind === 'error' ? reason.error.message : '';
                 state.rows.push({ id: nextRowId, kind: 'notice', text: `turn ${reason.kind}${detail ? ` · ${detail}` : ''}` });
                 nextRowId += 1;
-                state.notify(`Turn ${reason.kind}${detail ? ` · ${detail}` : ''}`, { color: 'error', timeoutMs: 8000 });
+                state.notify(t('turn-failed', { detail: detail ? ` · ${detail}` : '' }), { color: 'error', timeoutMs: 8000 });
                 break;
             }
             case 'request/context':
@@ -2137,7 +2880,7 @@ ${output}
                 // Logged preset switch (blank sessions only, issue #8): a transcript
                 // marker so a replayed log shows which composition produced the
                 // turns after it. Not in dsh-session's typed union — matched here by
-                // name, the way `activity/status` is consumed in bindAgent.
+                // name, like the other plugin-defined events above.
                 if (event.type === 'agent-preset/selected') {
                     const data = event.data;
                     state.rows.push({
@@ -2159,29 +2902,97 @@ ${output}
     state.working = false;
     state.status = agent.status;
     state.emit();
-    // Live subscription list, rebound to a fresh agent by rewindTo.
+    // Live subscription list and activity timer, rebound to every replacement
+    // agent so no status from the previous session can leak across a swap.
     let agentSubscriptions = [];
+    let activityTracker = new ActivityTracker({
+        phrases: true,
+        detailLimit: 40,
+        showIdle: false,
+    });
+    let activityTickTimer;
+    const stopActivityTick = () => {
+        if (activityTickTimer === undefined)
+            return;
+        clearInterval(activityTickTimer);
+        activityTickTimer = undefined;
+    };
+    /** Render the current tracker into the TUI-only projection. */
+    const renderWorkingActivity = () => {
+        if (options.activity === false) {
+            state.workingActivity = undefined;
+            return undefined;
+        }
+        const rendered = activityTracker.render();
+        state.workingActivity = rendered;
+        return rendered;
+    };
     const bindAgent = () => {
         for (const dispose of agentSubscriptions)
             dispose();
+        stopActivityTick();
+        activityTracker = new ActivityTracker({
+            phrases: true,
+            detailLimit: 40,
+            showIdle: false,
+        });
+        activityTracker.onAgentStatus(agent.status);
+        renderWorkingActivity();
+        activityTickTimer = setInterval(() => {
+            const previous = state.workingActivity;
+            const rendered = renderWorkingActivity();
+            if (rendered === undefined)
+                return;
+            // Live phases deliberately wake at 500 ms even when the formatted line
+            // has not crossed its next whole-second boundary: turnElapsedMs remains
+            // a current state value, while line changes cover phrase rotation and
+            // the short-lived completed-tool summary.
+            if (rendered.phase === 'waiting' ||
+                rendered.phase === 'thinking' ||
+                rendered.phase === 'tool' ||
+                previous?.phase !== rendered.phase ||
+                previous.line !== rendered.line) {
+                state.emit();
+            }
+        }, 500);
+        activityTickTimer.unref();
         // Re-couple the channel-owned model selection to the new agent's
         // assembly/request waterfalls, then re-apply the persisted effort when
         // this agent's route offers it (dsh-agent installModelSelection).
         selection.current = undefined;
         selection.assembled = undefined;
+        // {{model}} backfill (issue #155): a resumed agent's route lives only in
+        // its session's request/header records — agentOptions.model stays
+        // undefined unless cordis.yml pins a COMPLETE provider+model pair — so
+        // the assemble-time persona variable `{{model}}` was registered but
+        // valueless, and dsh-system-prompt's interpolate() throws before any
+        // model call. Seed the selection from the channel's display route (on
+        // resume it already carries the session's recorded route; on create it
+        // matches the route the agent was created with). Per
+        // installModelSelection's contract an absent effort restores the
+        // provider/default behavior, so seeding never pins an effort the route
+        // did not ask for; applyPreferredEffort below still upgrades the seed
+        // when the user has a persisted preference the route offers.
+        if (agent.options?.model === undefined && state.provider !== '' && state.model !== '') {
+            selection.current = { provider: state.provider, model: state.model };
+        }
         void applyPreferredEffort();
+        refreshMode();
         agentSubscriptions = [
             installModelSelection(agent.ctx, selection),
             ctx.on('agent/status', ({ agent: subject, status }) => {
                 if (subject !== agent)
                     return;
                 state.status = status;
+                activityTracker.onAgentStatus(status);
+                renderWorkingActivity();
                 state.emit();
             }),
             ctx.on('agent/disposed', ({ agent: subject }) => {
                 if (subject !== agent)
                     return;
                 state.status = 'disposed';
+                stopActivityTick();
                 state.emit();
             }),
             // Pending delivery is driven by the agent inbox: a claimed message
@@ -2215,24 +3026,13 @@ ${output}
             ctx.on('session/event', (session, event) => {
                 if (session !== agent.session)
                     return;
-                // Live working-activity snapshot (log-only event, appended by
-                // dsh-working-activity for UI consumers). Consumed here — NOT in
-                // renderEvent — so replayed history never resurrects a stale line
-                // (the renderEvent switch's default arm ignores it on replay).
-                if (options.activity !== false &&
-                    event.type === 'activity/status') {
-                    const data = event.data;
-                    state.workingActivity = {
-                        phase: data.phase,
-                        line: data.line,
-                        toolCount: data.toolCount ?? 0,
-                        turnElapsedMs: data.turnElapsedMs ?? 0,
-                        ...(data.label === undefined ? {} : { label: data.label }),
-                        ...(data.detail === undefined ? {} : { detail: data.detail }),
-                        ...(data.phrase === undefined ? {} : { phrase: data.phrase }),
-                    };
-                    state.emit();
-                    return;
+                activityTracker.onSessionEvent(event);
+                renderWorkingActivity();
+                // Mode-affecting atoms fold into the Shift+Tab mode indicator the
+                // moment they land (whether appended by cycleMode or by hand).
+                const eventType = event.type;
+                if (eventType === 'plan/mode' || eventType === 'sandbox/mode' || eventType === 'approval/policy') {
+                    refreshMode();
                 }
                 renderEvent(event);
                 // Streaming deltas (one event per token) take the frame-aligned
@@ -2245,15 +3045,30 @@ ${output}
         ];
     };
     bindAgent();
+    // Cordis owns the Channel lifetime. Rebinding handles the common case;
+    // this effect closes the final timer when the Channel's context unloads.
+    const effect = ctx.effect;
+    effect?.call(ctx, () => () => { stopActivityTick(); }, 'dsh-tui activity timer');
     // Statusline breadcrumb: current git branch of the session cwd (best-effort).
-    if (bash) {
+    // Re-run when an agent swap adopts a different persisted cwd (/resume,
+    // issue #96) so the breadcrumb never shows the previous workspace's branch.
+    const refreshGitBranch = () => {
+        state.gitBranch = undefined;
+        if (!bash)
+            return;
+        // Capture the requested cwd: a /resume landing while this query is in
+        // flight refreshes the branch for the NEW cwd, so a late reply from the
+        // old workspace must be dropped (statusline staleness, issue #96 review).
+        const requestedCwd = state.cwd;
         void bash
             .run(bash.resolve({
             command: 'git branch --show-current',
-            workdir: options.cwd,
+            workdir: requestedCwd,
             timeoutMs: 3000,
         }))
             .then((result) => {
+            if (state.cwd !== requestedCwd)
+                return;
             const branch = result.stdout.text.trim();
             if (branch !== '') {
                 state.gitBranch = branch;
@@ -2265,7 +3080,8 @@ ${output}
             // backend may be unavailable (no confinement yet) or the cwd may
             // not be a git repo. Either way the statusline simply stays blank.
         });
-    }
+    };
+    refreshGitBranch();
     return state;
 }
 /** Path basename for the resume-list title (`C:/a/b` → `b`). */
@@ -2273,6 +3089,56 @@ function basename(path) {
     const parts = path.split(/[\\/]/);
     return parts[parts.length - 1] ?? path;
 }
+/** Normalize a cwd for comparison: forward slashes, no trailing slash; case
+ *  folded when the platform's filesystem semantics are case-insensitive. */
+function normalizeCwd(path, caseInsensitive) {
+    const normalized = path.replace(/\\/g, '/').replace(/\/+$/, '');
+    return caseInsensitive ? normalized.toLowerCase() : normalized;
+}
+/**
+ * `/resume` project filter (issue #96): exact cwd match, PLUS sessions
+ * recorded in a subdirectory — pre-upgrade launches recorded the launch
+ * subdirectory as the header cwd, and with the cwd default now resolving to
+ * the git worktree root an exact match would hide those sessions forever.
+ * They belong to the same workspace, so they stay listed. Comparison follows
+ * the platform's filesystem semantics (case-insensitive on Windows — a
+ * pre-upgrade header may record `C:\Repo` where the current launch resolves
+ * `c:\repo`). `caseInsensitive` is a parameter (not a platform read) so the
+ * verifier can exercise both modes on any host. Exported for
+ * scripts/verify-session-cwd.mjs.
+ *
+ * Boundary rule (issue #153): container directories are nobody's workspace.
+ * $HOME and the Windows root forms — plain drive roots (`C:`), UNC share
+ * roots (`//server/share`), and extended-length roots (`//?/C:`,
+ * `//?/UNC/server/share`) — are ancestors of unrelated projects, so the
+ * descendant rules below would list every session on the machine from `~`
+ * (and every session on the drive/share from those roots). At these
+ * boundaries, in either direction, only an exact match passes.
+ */
+export function sessionCwdMatches(stateCwd, headerCwd, caseInsensitive = process.platform === 'win32') {
+    const cwd = normalizeCwd(stateCwd, caseInsensitive);
+    const recorded = normalizeCwd(headerCwd, caseInsensitive);
+    if (recorded === '' || cwd === '')
+        return false;
+    const home = normalizeCwd(homeDir(), caseInsensitive);
+    // Paths below arrive backslash-normalized (`\\server\share` →
+    // `//server/share`, `\\?\C:\` → `//?/C:`), trailing slashes stripped.
+    const isContainer = (path) => (home !== '' && path === home) ||
+        /^[a-z]:$/i.test(path) || // drive root: C:
+        /^\/\/[^/]+\/[^/]+$/.test(path) || // UNC share root: //server/share
+        /^\/\/\?\/[a-z]:$/i.test(path) || // extended drive root: //?/C:
+        /^\/\/\?\/unc\/[^/]+\/[^/]+$/i.test(path); // extended UNC root: //?/UNC/server/share
+    if (isContainer(cwd) || isContainer(recorded))
+        return recorded === cwd;
+    return (recorded === cwd ||
+        // Pre-upgrade subdirectory session of this workspace.
+        recorded.startsWith(`${cwd}/`) ||
+        // Resumed INTO a pre-upgrade subdirectory session (state.cwd adopted its
+        // recorded subdirectory): the workspace-root sessions it belongs with
+        // must stay visible, or /resume looks like it lost them for the rest of
+        // the process lifetime (review leftover).
+        cwd.startsWith(`${recorded}/`));
+}
 /** Context-bar token estimate (pi-nano-context: ~4 chars per token). */
 function estimateTokens(text) {
     return Math.ceil(text.length / 4);
@@ -2355,84 +3221,146 @@ const MENTION_MAX_DIR_ENTRIES = 200;
 function mentionFs(ctx) {
     return ctx.get('fs');
 }
+function mentionAttachments(ctx) {
+    return ctx.get('attachments');
+}
+const MENTION_IMAGE_MEDIA_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+    '.gif': 'image/gif',
+};
+function mentionImageMediaType(path) {
+    return MENTION_IMAGE_MEDIA_TYPES[extname(path).toLowerCase()];
+}
 /**
  * Expand a submitted text's `@` mentions (issue #15) into model-facing
- * attachment blocks: each referenced file contributes its (capped) content,
- * each directory a shallow listing. The typed text stays the first block
- * verbatim — mentions that resolve keep their `@path` spelling in it, and
- * unresolved ones stay literal everywhere. Best-effort: an unreadable or
- * binary file degrades to `missing`, never a failed send.
+ * 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) {
+export async function expandMentions(fs, cwd, text, attachments, stagedImages) {
     const blocks = [{ type: 'text', text }];
     const attached = [];
     const missing = [];
     const mentions = extractMentions(text);
-    if (!fs || mentions.length === 0)
-        return { blocks, attached, missing };
     let budget = MENTION_MAX_TOTAL_CHARS;
-    for (const mention of mentions) {
-        if (budget <= 0)
-            break;
-        // Mentions resolve against the session cwd, same as the model-facing fs
-        // tools; absolute paths pass through untouched.
-        const absolute = isAbsolute(mention.path) ? mention.path : join(cwd, mention.path);
-        let target;
-        let info;
-        try {
-            target = await fs.resolve(absolute);
-            info = await fs.stat(target);
-        }
-        catch {
-            missing.push(mention.path);
-            continue;
-        }
-        if (info?.type === 'file') {
+    let imageCount = 0;
+    let imageBytes = 0;
+    if (fs !== undefined) {
+        for (const mention of mentions) {
+            const imageMediaType = mentionImageMediaType(mention.path);
+            if (budget <= 0 && imageMediaType === undefined)
+                break;
+            // Mentions resolve against the session cwd, same as the model-facing fs
+            // tools; absolute paths pass through untouched.
+            const absolute = isAbsolute(mention.path) ? mention.path : join(cwd, mention.path);
+            let target;
+            let info;
             try {
-                const cap = Math.min(MENTION_MAX_FILE_CHARS, budget);
-                let content = await fs.readText(target);
-                let truncated = false;
-                if (content.length > cap) {
-                    content = content.slice(0, cap);
-                    truncated = true;
-                }
-                budget -= content.length;
-                blocks.push({
-                    type: 'text',
-                    text: `<attached-file path="${mention.path}">\n${content}${truncated ? '\n[… truncated]' : ''}\n</attached-file>`,
-                });
-                attached.push(mention.path);
+                target = await fs.resolve(absolute);
+                info = await fs.stat(target);
             }
             catch {
-                // Binary/undecodable or unreadable — report it like a miss.
                 missing.push(mention.path);
+                continue;
             }
-            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)`);
+            if (info?.type === 'file') {
+                if (imageMediaType !== undefined && attachments !== undefined && fs.readBytes !== undefined) {
+                    const limits = attachments.imageLimits;
+                    if (!limits.mediaTypes.includes(imageMediaType) || imageCount >= limits.maxImagesPerMessage) {
+                        missing.push(mention.path);
+                        continue;
+                    }
+                    try {
+                        const data = await fs.readBytes(target, undefined, limits.maxImageBytes);
+                        if (imageBytes + data.byteLength > limits.maxMessageImageBytes) {
+                            missing.push(mention.path);
+                            continue;
+                        }
+                        const attachment = await attachments.saveImage({
+                            data,
+                            mediaType: imageMediaType,
+                            name: basename(target.displayPath),
+                        });
+                        blocks.push({ type: 'image', attachment });
+                        imageCount += 1;
+                        imageBytes += data.byteLength;
+                        attached.push(mention.path);
+                    }
+                    catch {
+                        missing.push(mention.path);
+                    }
+                    continue;
                 }
-                const body = listing.join('\n');
-                budget -= body.length;
-                blocks.push({
-                    type: 'text',
-                    text: `<attached-directory path="${mention.path}">\n${body}\n</attached-directory>`,
-                });
-                attached.push(mention.path);
+                try {
+                    const cap = Math.min(MENTION_MAX_FILE_CHARS, budget);
+                    let content = await fs.readText(target);
+                    let truncated = false;
+                    if (content.length > cap) {
+                        content = content.slice(0, cap);
+                        truncated = true;
+                    }
+                    budget -= content.length;
+                    blocks.push({
+                        type: 'text',
+                        text: `<attached-file path="${mention.path}">\n${content}${truncated ? '\n[… truncated]' : ''}\n</attached-file>`,
+                    });
+                    attached.push(mention.path);
+                }
+                catch {
+                    // Binary/undecodable or unreadable — report it like a miss.
+                    missing.push(mention.path);
+                }
+                continue;
             }
-            catch {
-                missing.push(mention.path);
+            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="${mention.path}">\n${body}\n</attached-directory>`,
+                    });
+                    attached.push(mention.path);
+                }
+                catch {
+                    missing.push(mention.path);
+                }
+                continue;
             }
-            continue;
+            // Absent (stat → undefined) or a special file.
+            missing.push(mention.path);
+        }
+    }
+    if (attachments !== undefined && stagedImages !== undefined) {
+        const limits = attachments.imageLimits;
+        for (const [token, attachment] of stagedImages) {
+            if (!text.includes(token))
+                continue;
+            // 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 (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;
         }
-        // Absent (stat → undefined) or a special file.
-        missing.push(mention.path);
     }
     return { blocks, attached, missing };
 }