@deepseek-harness-tui/dsh-tui 0.8.7 → 0.9.0

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

@@ -12,19 +12,22 @@ import { clearResumeTarget, forgetSession, readResumeTarget, touchSession, write
 import { appendSessionTitle, deleteSessionLog, ensureLegacySessionEventTypes, sessionsRoots } from './compat/index.js';
 import { listSummaries, locateSession, noteBranch, previewSession, } from './sessions/index.js';
 import { writeActivityFrames } from '../activityPrefs.js';
+import { isPathLikeQuery, rankFileCandidates } from '../utils/fileSuggestions.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 { isPresetName, PRESET_NAMES } 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 { getLang, LANGS, t } from '../i18n.js';
+import { AUTO_THEME_NAME, THEME_NAMES } from '../theme.js';
+import { listCustomThemes } from '../customTheme.js';
 import { modeDisplayName, resolveSessionModes } from '../sessionModes.js';
-import { normalizeStatusBar, normalizeToolBackground } from '../tuiDisplayPrefs.js';
+import { normalizeScrollGutter, normalizeStatusBar, normalizeToolBackground } from '../tuiDisplayPrefs.js';
 import { SubagentActivityStore } from './subagents.js';
 import { ActivityTracker } from 'dsh-working-activity/status';
 import { featureOn } from 'dsh-working-activity/config';
@@ -42,7 +45,7 @@ import { installDecisionGuard } from './decision-guard.js';
 import { commandOwner } from './command-attribution.js';
 import { readGrantStore } from './grants.js';
 import { hasCommandErrorCode, mapCommandError } from './command-errors.js';
-import { installedLineOf } from './contract.js';
+import { installedMeetsVersion } from './contract.js';
 import { pluginsInfoLines } from './plugins-info.js';
 import { cleanRenderText, cleanScalarText } from './sanitize.js';
 /** `tui/input` return normalization: transform/handled/cancel or no opinion.
@@ -327,6 +330,72 @@ function toolResultText(event) {
         return '';
     return block.content.map(item => item.type === 'text' ? item.text : '').join('').trim();
 }
+/** Phase badge for the harness goal card — mirrors the panel's PhaseBadge. */
+const GOAL_RESULT_BADGE = {
+    active: '● active',
+    paused: '⏸ paused',
+    blocked: '⛔ blocked',
+    complete: '✓ complete',
+};
+/**
+ * Summary cards for the harness's goal/todo tools. Their results are machine
+ * JSON (`{"goal":{…}}` / `{"todos":[…]}`) that would otherwise dump under the
+ * tool card as a raw `⎿ {"goal":…}` line. Matched by tool-name substring AND
+ * payload shape, so unrelated tools and plain-text results pass through to
+ * the registry/raw-text path untouched. Runs on the live stream and replay.
+ */
+function harnessToolResultView(name, data) {
+    const lower = name.toLowerCase();
+    const isGoalTool = lower.includes('goal');
+    const isTodoTool = lower.includes('todo');
+    if (!isGoalTool && !isTodoTool)
+        return undefined;
+    const block = data.message.content[0];
+    if (block === undefined || block.type !== 'tool-result')
+        return undefined;
+    const text = block.content.map(item => item.type === 'text' ? item.text : '').join('').trim();
+    if (text === '' || !text.startsWith('{'))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const record = parsed;
+    if (isGoalTool && typeof record.goal === 'object' && record.goal !== null) {
+        const goal = record.goal;
+        if (typeof goal.objective === 'string' && typeof goal.phase === 'string') {
+            const badge = GOAL_RESULT_BADGE[goal.phase] ?? goal.phase;
+            const rounds = typeof goal.roundsStarted === 'number' && typeof goal.maxGoalRounds === 'number'
+                ? ` · ${goal.roundsStarted}/${goal.maxGoalRounds}`
+                : '';
+            const activation = typeof record.activation === 'string' ? ` · ${record.activation}` : '';
+            const lines = [`🎯 ${goal.objective}`, `${badge}${rounds}${activation}`];
+            const blocked = goal.blockedReason?.message;
+            if (typeof blocked === 'string')
+                lines.push(`⛔ ${blocked}`);
+            return { card: 'generic', content: lines.map(line => ({ type: 'text', text: line })) };
+        }
+    }
+    if (isTodoTool && Array.isArray(record.todos)) {
+        const rows = record.todos;
+        const done = rows.filter(row => row.status === 'completed').length;
+        const lines = [`todos ✓ ${done}/${rows.length}`];
+        for (const row of rows) {
+            if (row.status !== 'in_progress' || typeof row.content !== 'string')
+                continue;
+            lines.push(`● ${row.content}`);
+            if (lines.length >= 4)
+                break;
+        }
+        return { card: 'generic', content: lines.map(line => ({ type: 'text', text: line })) };
+    }
+    return undefined;
+}
 function toolErrorText(event) {
     const failure = event.data.error;
     if (failure === undefined)
@@ -432,8 +501,7 @@ export function createChannel(ctx, initialAgent, options) {
             try {
                 runtime.interrupt(target, { kind: 'ancestor', agent });
                 subagentStore.onCancelled(agentId, 'interrupted');
-                state.subagents = subagentStore.snapshot();
-                syncSubagentRows();
+                syncSubagentsNow();
                 state.emit();
                 return true;
             }
@@ -466,9 +534,12 @@ export function createChannel(ctx, initialAgent, options) {
     /**
      * Sync subagentStore state into ChatRows (insert/update in state.rows).
      * Called whenever subagent state changes (spawned/completed/failed/output).
+     * Accepts a caller-taken snapshot to avoid the double copy on the hot path
+     * (session/event fires per subagent token: snapshot here + snapshot in the
+     * caller = two full state copies before emitStream's 16ms throttle).
      */
-    const syncSubagentRows = () => {
-        const snapshot = subagentStore.snapshot();
+    const syncSubagentRows = (preSnapshot) => {
+        const snapshot = preSnapshot ?? subagentStore.snapshot();
         for (const sub of snapshot) {
             let row = subagentRowsByAgentId.get(sub.agentId);
             if (!row) {
@@ -545,6 +616,32 @@ export function createChannel(ctx, initialAgent, options) {
     const listeners = new Set();
     /** True while a frame-aligned stream notification is pending (emitStream). */
     let streamNotifyScheduled = false;
+    /** True while subagent assistant/chunk deltas have deferred their
+     *  snapshot+projection to the frame-aligned flush (emitStream's timer).
+     *  Chunks arrive at token rate (100-300 events/s) and the projection is a
+     *  full deep state copy (SubagentActivityStore.snapshot) plus a SubagentRow
+     *  rebuild per tracked agent — running that per token sits BEFORE
+     *  emitStream's 16ms coalescing and defeats it. Non-chunk events
+     *  (tool/call, subagent/end, interrupt) project immediately and clear
+     *  this flag, so lifecycle transitions stay synchronous. */
+    let subagentStreamDirty = false;
+    /** Deferred projection for the frame-aligned flush: runs INSIDE the
+     *  emitStream timer, before listeners wake, so React always reads fully
+     *  projected rows. No-op unless a chunk marked the projection dirty. */
+    const flushSubagentStream = () => {
+        if (!subagentStreamDirty)
+            return;
+        subagentStreamDirty = false;
+        state.subagents = subagentStore.snapshot();
+        syncSubagentRows(state.subagents);
+    };
+    /** Immediate projection; supersedes any pending deferred flush (the fresh
+     *  snapshot already contains everything the deferred pass would project). */
+    const syncSubagentsNow = () => {
+        subagentStreamDirty = false;
+        state.subagents = subagentStore.snapshot();
+        syncSubagentRows(state.subagents);
+    };
     // foldRows incremental cursor (see foldRows): rows only append past the
     // fold line, so each pass touches only newly-eligible rows.
     const foldCursor = { rows: null, index: 0 };
@@ -910,13 +1007,14 @@ export function createChannel(ctx, initialAgent, options) {
         applyEffort(found);
         return true;
     };
-    /** Whether the installed command service takes composer images: rc line
-     *  gate with a structural fallback, so a failed manifest probe (bundlers,
-     *  exotic loaders) still lands on the 4-param rc.8 shape at runtime. */
+    /** Whether the installed command service takes composer images: version
+     *  gate (composer images arrived on 0.1.0-rc.8 and every later family —
+     *  0.1.1 included — keeps the 4-param shape) with a structural fallback,
+     *  so a failed manifest probe (bundlers, exotic loaders) still lands on
+     *  the 4-param rc.8 shape at runtime. */
     const commandServiceSupportsImages = (service) => {
-        const line = installedLineOf('@deepseek-ai/dsh-commands');
-        if (line !== undefined)
-            return line >= 8;
+        if (installedMeetsVersion('@deepseek-ai/dsh-commands', '0.1.0-rc.8'))
+            return true;
         return typeof service.execute?.length === 'number'
             && service.execute.length >= 4;
     };
@@ -1129,6 +1227,74 @@ export function createChannel(ctx, initialAgent, options) {
         const index = deriveModeIndex(agent.session.events);
         await applyMode(sessionModes[(index + 1) % sessionModes.length]);
     };
+    // Session-lifetime candidate pool for non-path queries. The load promise is
+    // shared so concurrent first keystrokes cannot kick off duplicate scans, and
+    // it is keyed by cwd so a /workspace switch or resumed session never reuses
+    // another directory's listing.
+    const fileCandidateCache = { cwd: '', load: undefined };
+    // `/model <provider/id>` completion: the model catalog is async (one llm
+    // listModels per provider), so the first keystrokes that could be heading
+    // for /model warm a session-lifetime cache — the shared promise dedupes
+    // concurrent triggers, children() synchronously serves whatever has landed,
+    // and the arrival state.emit() reopens the menu mid-typing. switchModel's
+    // success path drops the cache so the [current] tag re-resolves against
+    // the new route.
+    const modelNodeCache = {
+        nodes: undefined,
+        load: undefined,
+    };
+    const warmModelNodes = () => {
+        if (modelNodeCache.load !== undefined)
+            return;
+        modelNodeCache.load = state.listModels().then((list) => {
+            modelNodeCache.nodes = list.map((model) => ({
+                name: `${model.provider}/${model.id}`,
+                description: model.name,
+                ...(state.provider === model.provider && state.model === model.id
+                    ? { tag: 'current' }
+                    : {}),
+            }));
+            state.emit();
+        }).catch(() => {
+            // listModels already swallows per-provider failures; this only fires
+            // when the llm service shape itself is missing — settle on an empty
+            // menu rather than retrying on every keystroke.
+            modelNodeCache.nodes = [];
+        });
+    };
+    // `/preset <id>` completion: same warm-cache pattern as models. The
+    // current/default tags resolve at children() time (sync state reads), so
+    // no cache invalidation is needed on switch.
+    const presetOptionCache = {
+        list: undefined,
+        load: undefined,
+    };
+    const warmPresetOptions = () => {
+        if (presetOptionCache.load !== undefined)
+            return;
+        presetOptionCache.load = state.listPresets().then((list) => {
+            presetOptionCache.list = list;
+            state.emit();
+        }).catch(() => {
+            presetOptionCache.list = [];
+        });
+    };
+    // `/effort <id>` completion: state.effortLevels is the sync vocabulary
+    // (populated on route changes); when still unknown, one best-effort
+    // resolveEfforts warms it. `tried` caps the retry — resolveEfforts
+    // notifies on hard errors, so keystroke-time retries would spam.
+    const effortWarm = { tried: false };
+    const warmEffortLevels = () => {
+        if (state.effortLevels !== undefined || effortWarm.tried)
+            return;
+        effortWarm.tried = true;
+        void resolveEfforts().then((resolved) => {
+            if (resolved === 'unavailable' || resolved === 'error')
+                return;
+            effortWarm.tried = false;
+            state.emit();
+        }).catch(() => { });
+    };
     const state = {
         effortLevels: undefined,
         version: 0,
@@ -1162,6 +1328,7 @@ export function createChannel(ctx, initialAgent, options) {
         diffLayout: options.diffLayout ?? 'auto',
         thinkingFold: options.thinkingFold ?? 'preview',
         toolBackground: normalizeToolBackground(options.toolBackground),
+        scrollGutter: normalizeScrollGutter(options.scrollGutter),
         statusBar: normalizeStatusBar(options.statusBar),
         whale: options.whale !== false,
         minimal: options.minimal === true,
@@ -1174,7 +1341,94 @@ export function createChannel(ctx, initialAgent, options) {
         pending: [],
         commandList: LOCAL_COMMANDS,
         commandCompletions(input) {
+            // Warm the async vocabularies as soon as the input could be heading
+            // for their commands (`/m`, `/pre`, …) — by the time a trailing space
+            // asks children() for nodes, the fetch has usually landed.
+            const head = input.slice(1).split(/[\t ]/)[0]?.toLowerCase() ?? '';
+            if (head !== '') {
+                if ('model'.startsWith(head))
+                    warmModelNodes();
+                if ('preset'.startsWith(head))
+                    warmPresetOptions();
+                if ('effort'.startsWith(head))
+                    warmEffortLevels();
+            }
             return completeCommands(input, state.commandList, (path) => {
+                if (path.length === 1 && path[0] === 'model') {
+                    // provider/id specs, current model tagged; see modelNodeCache.
+                    warmModelNodes();
+                    return modelNodeCache.nodes ?? [];
+                }
+                if (path.length === 1 && path[0] === 'lang') {
+                    return [
+                        { name: 'status', description: 'Show the current UI language', descriptionKey: 'sugg-status-desc' },
+                        ...LANGS.map((lang) => ({
+                            name: lang,
+                            description: `Switch the UI language to ${lang}`,
+                            descriptionKey: lang === 'zh' ? 'sugg-lang-zh-desc' : 'sugg-lang-en-desc',
+                            ...(getLang() === lang ? { tag: 'current' } : {}),
+                        })),
+                    ];
+                }
+                if (path.length === 1 && path[0] === 'theme') {
+                    return [
+                        { name: 'status', description: 'Show the current theme', descriptionKey: 'sugg-status-desc' },
+                        { name: AUTO_THEME_NAME, description: 'Follow the terminal background', descriptionKey: 'sugg-theme-auto-desc' },
+                        ...THEME_NAMES.map((name) => ({
+                            name,
+                            description: `Built-in theme ${name}`,
+                            descriptionKey: 'sugg-theme-builtin-desc',
+                        })),
+                        ...listCustomThemes()
+                            .filter((spec) => spec.name !== AUTO_THEME_NAME)
+                            .map((spec) => ({
+                            name: spec.name,
+                            description: `User theme (${spec.base} base)`,
+                            descriptionKey: 'sugg-theme-user-desc',
+                        })),
+                    ];
+                }
+                if (path.length === 1 && path[0] === 'effort') {
+                    warmEffortLevels();
+                    return [
+                        { name: 'status', description: 'Show the current reasoning effort', descriptionKey: 'sugg-status-desc' },
+                        ...(state.effortLevels ?? []).map((id) => ({
+                            name: id,
+                            description: 'Reasoning effort level',
+                            descriptionKey: 'sugg-effort-level-desc',
+                            ...(state.reasoningEffort === id ? { tag: 'current' } : {}),
+                        })),
+                    ];
+                }
+                if (path.length === 1 && path[0] === 'preset') {
+                    warmPresetOptions();
+                    return [
+                        { name: 'status', description: 'Show the current agent preset', descriptionKey: 'sugg-status-desc' },
+                        ...(presetOptionCache.list ?? []).map((preset) => ({
+                            name: preset.id,
+                            description: preset.description ?? preset.name ?? preset.id,
+                            ...(preset.id === state.agentPreset
+                                ? { tag: 'current' }
+                                : preset.isDefault
+                                    ? { tag: 'default' }
+                                    : {}),
+                        })),
+                    ];
+                }
+                if (path.length === 1 && path[0] === 'activity') {
+                    return [
+                        { name: 'status', description: 'Show the current activity preset', descriptionKey: 'sugg-status-desc' },
+                        { name: 'frames', description: 'List or switch frame presets', descriptionKey: 'sugg-activity-frames-desc' },
+                    ];
+                }
+                if (path.length === 2 && path[0] === 'activity' && path[1] === 'frames') {
+                    return PRESET_NAMES.map((name) => ({
+                        name,
+                        description: 'Animation frame preset',
+                        descriptionKey: 'sugg-activity-frame-desc',
+                        ...(state.activityFrames === name ? { tag: 'current' } : {}),
+                    }));
+                }
                 if (path.length === 1 && path[0] === 'workspace') {
                     const builtins = [
                         { name: 'resume', description: 'Switch to another workspace', descriptionKey: 'cmd-desc-workspace-resume' },
@@ -1193,6 +1447,21 @@ export function createChannel(ctx, initialAgent, options) {
                         })),
                     ];
                 }
+                if (path.length === 1 && path[0] === 'permission') {
+                    // Sandbox-preset vocabulary of the `/permission` picker — Tab
+                    // completes it for keyboard users, Enter still dispatches.
+                    return [
+                        { name: 'read-only', description: 'Read-only session: no file writes, no commands', descriptionKey: 'permission-preset-readonly-desc' },
+                        { name: 'workspace-write', description: 'Read/write inside the workspace; writes need a prior read', descriptionKey: 'permission-preset-workspace-write-desc' },
+                        { name: 'danger-full-access', description: 'Unrestricted access, no approvals', descriptionKey: 'permission-preset-full-access-desc' },
+                    ];
+                }
+                if (path.length === 1 && path[0] === 'plan') {
+                    return [
+                        { name: 'on', description: 'Enter plan mode: read-only, plan before acting', descriptionKey: 'plan-mode-on-desc' },
+                        { name: 'off', description: 'Exit plan mode, back to normal execution', descriptionKey: 'plan-mode-off-desc' },
+                    ];
+                }
                 return commandTrees?.children(path) ?? [];
             });
         },
@@ -1233,6 +1502,9 @@ export function createChannel(ctx, initialAgent, options) {
             streamNotifyScheduled = true;
             const timer = setTimeout(() => {
                 streamNotifyScheduled = false;
+                // Deferred subagent projection rides this same frame: flush BEFORE
+                // the listeners wake so React reads fully projected rows.
+                flushSubagentStream();
                 foldRows(state.rows, MAX_ROWS, foldCursor);
                 for (const listener of listeners)
                     listener();
@@ -2043,6 +2315,11 @@ export function createChannel(ctx, initialAgent, options) {
             state.agentPreset = modelComposed.agentPreset;
             state.model = model;
             state.provider = provider;
+            // /model completion cache: the [current] tag was resolved at fetch
+            // time — drop the cache so the next `/model ` refetches for the new
+            // route.
+            modelNodeCache.nodes = undefined;
+            modelNodeCache.load = undefined;
             state.tps = undefined;
             state.tpsSamples = [];
             state.lastUsage = undefined;
@@ -2153,6 +2430,13 @@ export function createChannel(ctx, initialAgent, options) {
             state.toolBackground = normalized;
             state.emit();
         },
+        setScrollGutter(mode) {
+            const normalized = normalizeScrollGutter(mode);
+            if (normalized === state.scrollGutter)
+                return;
+            state.scrollGutter = normalized;
+            state.emit();
+        },
         setStatusBar(config) {
             const next = normalizeStatusBar({ ...state.statusBar, ...config });
             const changed = Object.keys(next).some(key => next[key] !== state.statusBar[key]);
@@ -2460,9 +2744,33 @@ export function createChannel(ctx, initialAgent, options) {
                 signal: options?.signal,
             });
         },
-        listFiles() {
+        async listFileCandidates(query, options) {
             const fs = ctx.get('fs');
-            return listFilesDeep(fs, state.cwd);
+            if (!fs || options?.signal?.aborted)
+                return [];
+            if (isPathLikeQuery(query)) {
+                return listPathCandidates(fs, state.cwd, query, options?.signal, options?.topK ?? 50);
+            }
+            if (fileCandidateCache.cwd !== state.cwd) {
+                fileCandidateCache.cwd = state.cwd;
+                fileCandidateCache.load = undefined;
+            }
+            fileCandidateCache.load ??= listFilesDeepCandidates(fs, state.cwd).then(candidates => {
+                if (candidates.length > 0)
+                    return candidates;
+                // An empty scan is not worth caching forever — retry on next query.
+                fileCandidateCache.load = undefined;
+                return candidates;
+            });
+            const candidates = await fileCandidateCache.load;
+            if (options?.signal?.aborted)
+                return [];
+            return rankFileCandidates(candidates, query, options?.topK ?? 50);
+        },
+        async listFiles() {
+            const fs = ctx.get('fs');
+            const candidates = await listFilesDeepCandidates(fs, state.cwd);
+            return candidates.map(candidate => candidate.path);
         },
         async listSessions() {
             // Every stored session, classified and unfiltered. Which of them a
@@ -3310,6 +3618,12 @@ ${output}
      *  its result-time contextual diff back from here). */
     const presentResultView = (name, rawArgs, data) => {
         try {
+            // Harness goal/todo tools first: their raw JSON reads as noise in the
+            // transcript — fold recognizable shapes into a summary card before the
+            // registry gets a chance to (not) know them.
+            const local = harnessToolResultView(name, data);
+            if (local !== undefined)
+                return local;
             const tool = toolsRegistry?.get(name, agent);
             if (tool?.presentResult === undefined)
                 return undefined;
@@ -3442,9 +3756,21 @@ ${output}
             state.spinnerMode = 'requesting';
         }
     };
+    /** Fold one goal mutation into the channel's goal projection. */
+    const applyGoalChange = (change) => {
+        if (change.operation === 'clear') {
+            state.goal = undefined;
+        }
+        else if (change.goal !== undefined) {
+            state.goal = {
+                ...change.goal,
+                roundsStarted: change.roundsStarted ?? state.goal?.roundsStarted ?? 0,
+            };
+        }
+    };
     /**
      * Fold one goal-sourced message into the channel's goal projection.
-     * Round-zero goal messages carry the full durable snapshot (or a clear
+     * Round-zero goal messages may carry the full durable snapshot (or a clear
      * tombstone) in their source; positive-round messages are admitted
      * continuation prompts that only advance the rounds counter.
      */
@@ -3464,15 +3790,7 @@ ${output}
         // oxlint-disable-next-line typescript/no-unnecessary-condition -- durable replay data may not match the static type
         if (change === undefined || change.kind !== 'goal/change')
             return;
-        if (change.operation === 'clear') {
-            state.goal = undefined;
-        }
-        else if (change.goal !== undefined) {
-            state.goal = {
-                ...change.goal,
-                roundsStarted: change.roundsStarted ?? state.goal?.roundsStarted ?? 0,
-            };
-        }
+        applyGoalChange(change);
     };
     /** True while the durable transcript is being replayed (boot /resume /
      *  rewind / model-switch fork). The assistant/message reasoning-rebuild
@@ -3500,6 +3818,15 @@ ${output}
         }
     };
     const renderEvent = (event) => {
+        // Top-level `goal/change` events are how the goal service actually
+        // records durable goal mutations (create/edit/pause/resume/complete/
+        // block/clear) — confirmed in production logs. The pinned peer's
+        // SessionEvent union predates the type, so admit it structurally: the
+        // goal chip and panel stay dark without this fold.
+        if (event.type === 'goal/change') {
+            applyGoalChange(event.data);
+            return;
+        }
         switch (event.type) {
             case 'user/message': {
                 // Compaction checkpoint: `source = { kind: 'plugin', plugin:
@@ -3542,10 +3869,13 @@ ${output}
                     contextWarned = false;
                     break;
                 }
-                // Same-session goal domain: round-zero goal-sourced messages carry
-                // the durable goal snapshot (or clear tombstone) in their source.
-                // They are not transcript bubbles — they drive the goal panel's
-                // live projection (replayed on resume/rewind like every other event).
+                // Same-session goal domain: goal-sourced messages are the round
+                // driver's continuation prompts (positive rounds advance the
+                // counter); some hosts also inline the durable snapshot in a
+                // round-zero source. They are not transcript bubbles — they drive
+                // the goal panel's live projection (replayed on resume/rewind like
+                // every other event; the snapshot itself arrives as the top-level
+                // `goal/change` event admitted above).
                 if (event.data.source.kind === 'goal') {
                     applyGoalEvent(event);
                     break;
@@ -4127,12 +4457,18 @@ ${output}
                 const subagentId = subagentStore.getSubagentIdBySession(session);
                 if (subagentId) {
                     subagentStore.onSessionEvent(subagentId, event);
-                    state.subagents = subagentStore.snapshot();
-                    syncSubagentRows();
-                    if (event.type === 'assistant/chunk')
+                    if (event.type === 'assistant/chunk') {
+                        // Token-rate path (100-300 events/s): the store append stays
+                        // synchronous (cheap); the expensive snapshot + row projection
+                        // defers to the frame-aligned flush inside emitStream's 16ms
+                        // timer, so it coalesces exactly like the main-agent stream.
+                        subagentStreamDirty = true;
                         state.emitStream();
-                    else
+                    }
+                    else {
+                        syncSubagentsNow();
                         state.emit();
+                    }
                     return;
                 }
                 // Otherwise handle main agent session
@@ -4195,8 +4531,7 @@ ${output}
                     catch {
                         // Session discovery is best-effort and must not break the parent turn.
                     }
-                    state.subagents = subagentStore.snapshot();
-                    syncSubagentRows();
+                    syncSubagentsNow();
                     state.emit();
                 });
                 const disposeEnd = ctx.on('subagent/end', (info) => {
@@ -4218,8 +4553,7 @@ ${output}
                         subagentStore.onCancelled(info.id, info.stopReason, output);
                     else
                         subagentStore.onFailed(info.id, info.stopReason || 'Unknown error');
-                    state.subagents = subagentStore.snapshot();
-                    syncSubagentRows();
+                    syncSubagentsNow();
                     state.emit();
                 });
                 return () => {
@@ -4373,33 +4707,64 @@ function usageOutputTokens(usage) {
         ? value
         : undefined;
 }
-/**
- * `@` file listing through the leaf's fs service (dsh-fs-local): skips
- * VCS/dependency/build dirs and rotates across directory listings so one
- * large subtree cannot consume the global MAX_FILES budget. That budget also
- * bounds directory reads without imposing an arbitrary source-tree depth.
- * Relative directories retain the trailing `/` that FileSuggestions expects.
- * Unreadable subtrees are skipped, not fatal.
- */
-async function listFilesDeep(fs, root) {
+async function listPathCandidates(fs, cwd, query, signal, topK) {
+    const normalized = query.replaceAll('\\', '/');
+    const slash = normalized.lastIndexOf('/');
+    // `.` / `..` without a trailing separator are whole-directory queries too.
+    const bareDir = slash < 0 && (normalized === '.' || normalized === '..' || normalized === '~');
+    const directoryPart = slash < 0 ? (bareDir ? `${normalized}/` : '') : normalized.slice(0, slash + 1);
+    const nameQuery = slash < 0 || bareDir ? '' : normalized.slice(slash + 1);
+    // `~/` expands against the host home (matches the cwd resolution rules);
+    // drive-letter and POSIX-absolute prefixes pass through untouched.
+    const expanded = directoryPart === '~/'
+        ? `${homeDir()}/`
+        : directoryPart.startsWith('/') || /^[A-Za-z]:\//.test(directoryPart)
+            ? directoryPart
+            : join(cwd, directoryPart || '.');
+    try {
+        if (signal?.aborted)
+            return [];
+        const target = await fs.resolve(expanded);
+        const entries = (await fs.listDir(target)).slice().sort((a, b) => a.name.localeCompare(b.name));
+        return rankFileCandidates(entries.filter(entry => entry.type === 'file' || entry.type === 'directory').map(entry => {
+            const path = `${directoryPart}${entry.name}${entry.type === 'directory' ? '/' : ''}`;
+            return { id: path, path, displayPath: path, name: entry.name, kind: entry.type, score: 0 };
+        }), nameQuery, topK);
+    }
+    catch {
+        return [];
+    }
+}
+async function listFilesDeepCandidates(fs, root, signal) {
     if (!fs)
         return [];
     const out = [];
     const SKIP = new Set(['node_modules', '.git', '.hg', '.svn', '.DS_Store', 'dist']);
     const BUILD_DIR = /^(?:build(?:[-_].*)?|cmake-build(?:[-_].*)?)$/i;
-    const MAX_FILES = 100;
-    const directories = [{ dir: root, prefix: '', index: 0 }];
-    while (directories.length > 0 && out.length < MAX_FILES) {
-        const current = directories.shift();
-        if (!current)
-            continue;
+    const queue = [{ dir: root, prefix: '', index: 0 }];
+    const visited = new Set();
+    const maxFiles = 100;
+    const maxDirectories = 100;
+    let fileCount = 0;
+    let dirCount = 0;
+    // Round-robin: each directory yields ONE non-skipped entry per visit before
+    // it re-queues, so a large early sibling (e.g. `generated/` with 120 files)
+    // cannot starve `src/` out of the per-kind budgets. This is the regression
+    // contract pinned by scripts/verify-file-completion.mjs.
+    while (queue.length && fileCount < maxFiles && dirCount < maxDirectories) {
+        if (signal?.aborted)
+            return [];
+        const current = queue.shift();
         if (!current.entries) {
             try {
                 const target = await fs.resolve(current.dir);
-                current.entries = await fs.listDir(target);
+                if (visited.has(target.displayPath))
+                    continue;
+                visited.add(target.displayPath);
+                current.entries = (await fs.listDir(target)).slice().sort((a, b) => a.name.localeCompare(b.name));
             }
             catch {
-                continue; // unreadable subtree — skip
+                continue;
             }
         }
         let entry;
@@ -4413,22 +4778,23 @@ async function listFilesDeep(fs, root) {
         if (!entry)
             continue;
         if (current.index < current.entries.length)
-            directories.push(current);
-        const rel = current.prefix ? `${current.prefix}/${entry.name}` : entry.name;
+            queue.push(current);
+        const path = current.prefix ? `${current.prefix}/${entry.name}` : entry.name;
         if (entry.type === 'directory') {
-            out.push(`${rel}/`);
-            directories.push({
-                // oxlint-disable-next-line typescript/no-unnecessary-condition -- runtime guard: symlink targets optional
-                dir: entry.target?.displayPath ?? join(current.dir, entry.name),
-                prefix: rel,
-                index: 0,
-            });
+            if (dirCount >= maxDirectories)
+                continue;
+            out.push({ id: `${path}/`, path: `${path}/`, displayPath: `${path}/`, name: entry.name, kind: 'directory', score: 0 });
+            dirCount += 1;
+            queue.push({ dir: entry.target?.displayPath ?? join(current.dir, entry.name), prefix: path, index: 0 });
         }
         else if (entry.type === 'file') {
-            out.push(rel);
+            if (fileCount >= maxFiles)
+                continue;
+            out.push({ id: path, path, displayPath: path, name: entry.name, kind: 'file', score: 0 });
+            fileCount += 1;
         }
     }
-    return out;
+    return out.sort((a, b) => a.path.localeCompare(b.path));
 }
 /** One attached file's contribution is capped so an absent-minded `@` of a
  *  huge file cannot blow the context window (CC caps @-attachments too). */