@deepseek-harness-tui/dsh-tui 0.8.6 → 0.8.8

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

@@ -7,11 +7,12 @@ import { SessionId } from '@deepseek-ai/dsh-session';
 import { renderContextSections, renderPrompt } from '@deepseek-ai/dsh-system-prompt';
 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 { completeCommands, HIDDEN_COMMAND_NAMES, isLocalCommandName, LOCAL_COMMANDS, parseCommandName } from '../commands.js';
 import { clearResumeTarget, forgetSession, readResumeTarget, touchSession, writeResumeTarget } from '../sessionHistory.js';
 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';
@@ -25,8 +26,10 @@ import { extractMentions } from '../utils/mentions.js';
 import { t } from '../i18n.js';
 import { modeDisplayName, resolveSessionModes } from '../sessionModes.js';
 import { normalizeStatusBar, normalizeToolBackground } from '../tuiDisplayPrefs.js';
+import { SubagentActivityStore } from './subagents.js';
 import { ActivityTracker } from 'dsh-working-activity/status';
 import { featureOn } from 'dsh-working-activity/config';
+import { setMinimalMode } from '../minimalMode.js';
 import { readActivityConfig } from '../activityPrefs.js';
 import { attachSessionToWorkspace } from './workspace.js';
 import { createLocalWorkspaceRuntime, getHostWorkspaceRuntime } from './workspaces.js';
@@ -40,6 +43,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 { 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.
@@ -136,6 +140,20 @@ function normalizeRewindDoneSummary(result, warn) {
  * observation (a provider whose directory watcher is still warming).
  */
 const SKILL_COMMAND_RETRY_MS = 800;
+/** Names the subagent delegation tools ship under (preset `toolName` values
+ *  plus the CLI default); each renders as a live subagent card, never a plain
+ *  tool card. */
+const SUBAGENT_TOOL_NAMES = new Set([
+    'task',
+    'subagent',
+    'subagent_fork',
+    'subagent_claude_code',
+    'subagent_codex',
+    'spawn_task',
+]);
+function isSubagentToolName(name) {
+    return SUBAGENT_TOOL_NAMES.has(name.toLowerCase());
+}
 const ARGS_PREVIEW_LIMIT = 160;
 const RESULT_PREVIEW_LIMIT = 240;
 /** Local `!`-command output cap (mirrors the result preview limit). */
@@ -405,6 +423,26 @@ async function waitForTurnEnd(session, fromSeq, timeoutMs) {
 export function createChannel(ctx, initialAgent, options) {
     let agent = initialAgent;
     let currentHandle = options.handle;
+    const subagentControl = {
+        interrupt(agentId) {
+            const child = subagentStore.get(agentId);
+            const target = child?.sessionId ?? agentId;
+            const runtime = ctx.subagents;
+            if (!runtime?.interrupt || !target)
+                return false;
+            try {
+                runtime.interrupt(target, { kind: 'ancestor', agent });
+                subagentStore.onCancelled(agentId, 'interrupted');
+                state.subagents = subagentStore.snapshot();
+                syncSubagentRows();
+                state.emit();
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
     // D-7 backstop: the extensions row installs the decision-subscription
     // gate, but the channel IS the dispatch path — a stale patch without that
     // row (or a bare embed mounting neither) would otherwise leave tui/input
@@ -418,6 +456,55 @@ export function createChannel(ctx, initialAgent, options) {
     const fallbackGrantStore = readGrantStore();
     const currentGrantStore = () => ctx.get('tuiPluginHost')?.grants ?? fallbackGrantStore;
     installDecisionGuard(ctx, currentGrantStore());
+    // Subagent activity tracking: collects agent/subagent/*, session/event for
+    // subagents, and exposes live snapshots for the UI.
+    const subagentStore = new SubagentActivityStore();
+    // Subagent ChatRow tracking: maps agentId to its ChatRow for live updates.
+    const subagentRowsByAgentId = new Map();
+    // Task tool descriptions, queued in call order; each subagent/start consumes
+    // the oldest one so the card shows the user-visible task label.
+    const pendingTaskDescriptions = [];
+    /**
+     * Sync subagentStore state into ChatRows (insert/update in state.rows).
+     * Called whenever subagent state changes (spawned/completed/failed/output).
+     */
+    const syncSubagentRows = () => {
+        const snapshot = subagentStore.snapshot();
+        for (const sub of snapshot) {
+            let row = subagentRowsByAgentId.get(sub.agentId);
+            if (!row) {
+                // New subagent: insert a new ChatRow after the last user or assistant message
+                row = {
+                    id: nextRowId++,
+                    kind: 'subagent',
+                    text: sub.description,
+                    subagent: undefined, // will be filled below
+                };
+                subagentRowsByAgentId.set(sub.agentId, row);
+                state.rows.push(row);
+            }
+            const subagentRow = {
+                agentId: sub.agentId,
+                runId: sub.runId,
+                description: sub.description,
+                provider: sub.provider,
+                model: sub.model || 'default',
+                effort: sub.effort,
+                status: sub.status,
+                startedAt: sub.startedAt,
+                completedAt: sub.completedAt,
+                durationMs: sub.completedAt ? sub.completedAt - sub.startedAt : Date.now() - sub.startedAt,
+                outputLines: sub.output.slice(-3),
+                toolCalls: sub.toolCalls,
+                tokens: sub.tokens,
+                summary: sub.summary,
+                stopReason: sub.stopReason,
+                error: sub.error,
+            };
+            row.subagent = subagentRow;
+            row.text = sub.description;
+        }
+    };
     // The DSH slash-command registry (optional service): /plan, /goal and
     // friends register here; the TUI merges their descriptors into the slash
     // menu and dispatches through `execute` (which logs the paired
@@ -686,6 +773,12 @@ export function createChannel(ctx, initialAgent, options) {
     /** Monotonic token: only the latest `interruptAndDeliver` re-queues, so a
      *  second interrupt while the abort settles cannot double-deliver. */
     let interruptSeq = 0;
+    // Cancellation is asynchronous: a fast second Esc can arrive after the
+    // driver has accepted the first abort but before its turn/end event lands.
+    // Do not cancel the same driver twice, or the second cancel can swallow the
+    // replacement work queued by interruptAndDeliver and leave the UI gated on
+    // a working flag that has not observed turn/end yet.
+    let cancelInFlight = false;
     /** The llm runtime seam (dsh-llm LlmRuntime): route metadata resolution. */
     const llmRuntime = ctx.get('llm');
     /** Mutable per-agent model selection (dsh-agent's routing override seam).
@@ -818,6 +911,17 @@ export function createChannel(ctx, initialAgent, options) {
         applyEffort(found);
         return true;
     };
+    /** 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) => {
+        if (installedMeetsVersion('@deepseek-ai/dsh-commands', '0.1.0-rc.8'))
+            return true;
+        return typeof service.execute?.length === 'number'
+            && service.execute.length >= 4;
+    };
     /** 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. */
@@ -864,7 +968,22 @@ export function createChannel(ctx, initialAgent, options) {
             return t('command-invoke-denied-owner', { name, owner: owner.componentId });
         }
         try {
-            const execution = await commandService.execute(agent, `/${name}${rawInput}`, new AbortController().signal);
+            const signal = new AbortController().signal;
+            const line = `/${name}${rawInput}`;
+            const images = await registryCommandImages(commandService, definition, line, signal);
+            // rc.8 moved the signal to the 4th parameter and added composer
+            // images; older lines (rc.7/rc.6) take (agent, line, signal).
+            const execution = images === undefined
+                ? await commandService.execute(agent, line, signal)
+                : await commandService.execute(agent, line, images.images, signal);
+            if (images !== undefined && images.dropped.length > 0) {
+                // Loud-drop policy mirrors the submit pipeline (mentions-missing):
+                // a referenced image that never reached the command must be visible.
+                state.notify(t('mentions-missing', { paths: images.dropped.join(' ') }), {
+                    color: 'warning',
+                    timeoutMs: 4000,
+                });
+            }
             // `undefined` = not registered; a handler error surfaces as its
             // message so the user sees why the command failed.
             return execution?.result.text ?? '';
@@ -873,6 +992,51 @@ export function createChannel(ctx, initialAgent, options) {
             return error instanceof Error ? error.message : String(error);
         }
     };
+    /** Encode the staged `@`-mention images the user pasted for THIS command
+     *  line into rc.8's `EncodedImageAttachment` payloads; undefined = the
+     *  installed dsh-commands line predates composer images (rc.7/rc.6), so
+     *  the caller uses the legacy 3-arg invoke. Matches the submit pipeline's
+     *  token rule (expandMentions): a staged image attaches only when the
+     *  line references its token. A command that does not declare
+     *  `input.images` gets NO images — rc.8 admission settles such a batch
+     *  as an error, and upstream sends images only to image-capable commands.
+     *  A failing read drops just that image (reported via the returned
+     *  tokens) while the command still runs. */
+    const registryCommandImages = async (service, definition, line, signal) => {
+        if (!commandServiceSupportsImages(service))
+            return undefined;
+        const declaresImages = definition?.input?.images === true;
+        if (!declaresImages || stagedImages.size === 0)
+            return { images: [], dropped: [] };
+        const store = mentionAttachments(ctx);
+        if (typeof store?.readImage !== 'function')
+            return { images: [], dropped: [] };
+        const images = [];
+        const dropped = [];
+        for (const [token, attachment] of stagedImages) {
+            if (!line.includes(token))
+                continue;
+            try {
+                const stored = await store.readImage(attachment, signal);
+                if (stored?.data instanceof Uint8Array && stored.data.byteLength > 0) {
+                    images.push({
+                        mediaType: attachment.mediaType,
+                        data: Buffer.from(stored.data).toString('base64'),
+                        name: attachment.name,
+                    });
+                }
+                else {
+                    dropped.push(token);
+                }
+            }
+            catch {
+                // One unreadable staged image is dropped — same loud policy as the
+                // submit pipeline's mentions-missing warning (deliverUserText).
+                dropped.push(token);
+            }
+        }
+        return { images, dropped };
+    };
     // 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
@@ -967,6 +1131,11 @@ 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 };
     const state = {
         effortLevels: undefined,
         version: 0,
@@ -1001,6 +1170,8 @@ export function createChannel(ctx, initialAgent, options) {
         thinkingFold: options.thinkingFold ?? 'preview',
         toolBackground: normalizeToolBackground(options.toolBackground),
         statusBar: normalizeStatusBar(options.statusBar),
+        whale: options.whale !== false,
+        minimal: options.minimal === true,
         activityEnabled: options.activity !== false,
         contextBarEnabled: options.contextBar !== false,
         agentPreset: options.agentPreset,
@@ -1042,6 +1213,8 @@ export function createChannel(ctx, initialAgent, options) {
             thinking: 0,
             tools: 0,
         },
+        subagents: [],
+        subagentControl,
         subscribe(listener) {
             listeners.add(listener);
             return () => {
@@ -1165,6 +1338,11 @@ export function createChannel(ctx, initialAgent, options) {
         cancel() {
             // Keep the staged queue: an interrupt aborts the running turn but the
             // queued/steered messages are delivered as the next turn (web parity).
+            // Cancellation converges asynchronously; ignore a repeated Esc/Ctrl+C
+            // until the aborted turn has produced its terminal event.
+            if (cancelInFlight)
+                return;
+            cancelInFlight = true;
             agent.cancel({ kind: 'user' }, { keepInbox: true });
         },
         interruptAndDeliver(texts) {
@@ -1176,8 +1354,13 @@ export function createChannel(ctx, initialAgent, options) {
             // followup. dsh-agent's cancel-convergence wake latch accepts this
             // wake immediately after cancel and starts it once the aborted turn
             // retires; waiting for whenIdle is unsafe because it also follows
-            // replacement work and may never settle.
-            agent.cancel({ kind: 'user' });
+            // replacement work and may never settle. If cancellation is already
+            // in flight, keep the existing abort and still replace the pending
+            // interrupt delivery; fake/embedded agents may not emit turn/end.
+            if (!cancelInFlight) {
+                cancelInFlight = true;
+                agent.cancel({ kind: 'user' });
+            }
             const token = ++interruptSeq;
             const deliver = () => {
                 // A second interrupt while the abort is still settling must not
@@ -1985,6 +2168,19 @@ export function createChannel(ctx, initialAgent, options) {
             state.statusBar = next;
             state.emit();
         },
+        setWhale(visible) {
+            if (visible === state.whale)
+                return;
+            state.whale = visible;
+            state.emit();
+        },
+        setMinimal(enabled) {
+            setMinimalMode(enabled);
+            if (enabled === state.minimal)
+                return;
+            state.minimal = enabled;
+            state.emit();
+        },
         setActivityFrames(name) {
             if (!isPresetName(name)) {
                 state.notify(t('unknown-activity-preset', { name }), { color: 'error' });
@@ -2098,13 +2294,15 @@ export function createChannel(ctx, initialAgent, options) {
             // snapshot() over list(): only a COMPLETE observation is authoritative
             // (same contract as the skill-command merge above) — a partial catalog
             // must surface as "failed", not as a misleading near-empty picker.
-            const registry = skillRegistryFor(agent);
+            const target = agent;
+            const registry = skillRegistryFor(target);
             if (registry === undefined)
                 return [];
             try {
-                const observation = await registry.snapshot(skillViewOptions(agent));
-                if (!observation.complete)
+                const observation = await registry.snapshot(skillViewOptions(target));
+                if (target !== agent || !observation.complete) {
                     return undefined;
+                }
                 return observation.skills.map(skill => ({
                     name: skill.name,
                     description: skill.description,
@@ -2269,9 +2467,33 @@ export function createChannel(ctx, initialAgent, options) {
                 signal: options?.signal,
             });
         },
-        listFiles() {
+        async listFileCandidates(query, options) {
+            const fs = ctx.get('fs');
+            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');
-            return listFilesDeep(fs, state.cwd);
+            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
@@ -2717,6 +2939,10 @@ export function createChannel(ctx, initialAgent, options) {
         const merged = [...LOCAL_COMMANDS];
         if (commandService) {
             for (const descriptor of commandService.list(target)) {
+                // Hidden TUI commands (e.g. /deepseek) stay out of the public
+                // command catalog even if a plugin/skill happens to share the name.
+                if (HIDDEN_COMMAND_NAMES.has(descriptor.name))
+                    continue;
                 if (merged.some(command => command.name === descriptor.name))
                     continue;
                 const descriptions = commandTrees?.descriptions(descriptor.name);
@@ -3559,6 +3785,22 @@ ${output}
                 // no card is a no-op below.
                 if (event.data.name === 'ask_user_question')
                     break;
+                // The Task tool's plain card is replaced by the live subagent card
+                // (Kimi Code semantics): the delegation itself renders as a subagent
+                // row, so the raw args/result card would only duplicate it. The call
+                // still runs - only its transcript rendering is suppressed.
+                if (isSubagentToolName(event.data.name)) {
+                    try {
+                        const args = JSON.parse(event.data.arguments);
+                        if (typeof args.description === 'string' && args.description)
+                            pendingTaskDescriptions.push(args.description);
+                    }
+                    catch {
+                        // Unparseable args leave the queue untouched; the card falls back
+                        // to the provider label.
+                    }
+                    break;
+                }
                 // Reasoning that led to a tool call is done thinking — fold the
                 // preview now, before the tool card grows the transcript past it
                 // (see foldLiveReasoning).
@@ -3629,6 +3871,7 @@ ${output}
                 break;
             }
             case 'turn/start': {
+                cancelInFlight = false;
                 state.working = true;
                 state.turnStart = Date.now();
                 state.responseChars = 0;
@@ -3644,6 +3887,7 @@ ${output}
                 break;
             }
             case 'turn/end': {
+                cancelInFlight = false;
                 settleStreaming();
                 state.working = false;
                 state.activeToolCount = 0;
@@ -3910,6 +4154,19 @@ ${output}
                 };
             })(),
             ctx.on('session/event', (session, event) => {
+                // First check if this is a subagent session
+                const subagentId = subagentStore.getSubagentIdBySession(session);
+                if (subagentId) {
+                    subagentStore.onSessionEvent(subagentId, event);
+                    state.subagents = subagentStore.snapshot();
+                    syncSubagentRows();
+                    if (event.type === 'assistant/chunk')
+                        state.emitStream();
+                    else
+                        state.emit();
+                    return;
+                }
+                // Otherwise handle main agent session
                 if (session !== agent.session)
                     return;
                 // Observation broker (C-042): maps user/message + assistant/message
@@ -3940,6 +4197,67 @@ ${output}
                 else
                     state.emit();
             }),
+            // Subagent lifecycle tracking. The dsh-subagent service publishes scoped
+            // observe-only events as `subagent/start` and `subagent/end`; the parent
+            // Agent is carried by Cordis scope dispatch, not included in the payload.
+            (() => {
+                const disposeStart = ctx.on('subagent/start', (info) => {
+                    if (!info?.id)
+                        return;
+                    subagentStore.onSpawned(info.id, info.provider || 'subagent', info.provider, {
+                        runId: info.runId ?? info.id,
+                        local: info.local,
+                        description: pendingTaskDescriptions.shift() ?? `${info.provider || 'subagent'} task`,
+                    });
+                    // In-process providers publish a child Agent during this notification.
+                    // Resolve through ctx.get('agents') (the property proxy is
+                    // topology-sensitive); the child carries its session (live output
+                    // stream) and its provider/model route for the card header.
+                    try {
+                        const agents = ctx.get('agents');
+                        const child = agents?.get(info.id);
+                        if (child?.session) {
+                            subagentStore.linkSession(info.id, child.session);
+                            const model = child.options?.model ?? child.options?.provider;
+                            if (model)
+                                subagentStore.patch(info.id, { model, provider: child.options?.provider ?? info.provider });
+                        }
+                    }
+                    catch {
+                        // Session discovery is best-effort and must not break the parent turn.
+                    }
+                    state.subagents = subagentStore.snapshot();
+                    syncSubagentRows();
+                    state.emit();
+                });
+                const disposeEnd = ctx.on('subagent/end', (info) => {
+                    if (!info?.id)
+                        return;
+                    const output = Array.isArray(info.lastAssistantMessage)
+                        ? info.lastAssistantMessage
+                            .map(block => typeof block === 'object' && block !== null && 'text' in block ? String(block.text ?? '') : '')
+                            .filter(Boolean)
+                            .join('\n')
+                        : '';
+                    // The final assistant output becomes the card's summary only; the
+                    // running waterfall came from the child session stream, so echoing
+                    // it into the output buffer would duplicate it on the collapsed card.
+                    subagentStore.flushOutput(info.id);
+                    if (info.stopReason === 'completed')
+                        subagentStore.onCompleted(info.id, output, info.stopReason);
+                    else if (info.stopReason === 'cancelled' || info.stopReason === 'aborted')
+                        subagentStore.onCancelled(info.id, info.stopReason, output);
+                    else
+                        subagentStore.onFailed(info.id, info.stopReason || 'Unknown error');
+                    state.subagents = subagentStore.snapshot();
+                    syncSubagentRows();
+                    state.emit();
+                });
+                return () => {
+                    disposeStart();
+                    disposeEnd();
+                };
+            })(),
         ];
     };
     // Subagents inherit provider/model from AgentOptions, but resumed TUI
@@ -4086,33 +4404,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;
@@ -4126,22 +4475,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). */