iosm-cli 0.2.0 → 0.2.2

package/dist/modes/interactive/interactive-mode.js

@@ -15,16 +15,20 @@ import { parseSkillBlock } from "../../core/agent-session.js";
 import { FooterDataProvider } from "../../core/footer-data-provider.js";
 import { KeybindingsManager } from "../../core/keybindings.js";
 import { createCompactionSummaryMessage, INTERNAL_UI_META_CUSTOM_TYPE, isInternalUiMetaDetails, } from "../../core/messages.js";
+import { loadModelsDevProviderCatalog, } from "../../core/models-dev-provider-catalog.js";
 import { ModelRegistry } from "../../core/model-registry.js";
+import { MODELS_DEV_PROVIDERS } from "../../core/models-dev-providers.js";
 import { resolveModelScope } from "../../core/model-resolver.js";
 import { getMcpCommandHelp, parseMcpAddCommand, parseMcpTargetCommand, } from "../../core/mcp/index.js";
 import { addMemoryEntry, getMemoryFilePath, readMemoryEntries, removeMemoryEntry, updateMemoryEntry, } from "../../core/memory.js";
 import { ContractService, normalizeEngineeringContract, } from "../../core/contract.js";
+import { buildProjectIndex, collectChangedFilesSince, ensureProjectIndex, loadProjectIndex, queryProjectIndex, saveProjectIndex, } from "../../core/project-index/index.js";
 import { SingularService, } from "../../core/singular.js";
 import { getDefaultSemanticSearchConfig, getSemanticConfigPath, getSemanticIndexDir, isLikelyEmbeddingModelId, listOllamaLocalModels, listOpenRouterEmbeddingModels, loadMergedSemanticConfig, readScopedSemanticConfig, SemanticConfigMissingError, SemanticIndexRequiredError, SemanticRebuildRequiredError, SemanticSearchRuntime, upsertScopedSemanticSearchConfig, } from "../../core/semantic/index.js";
 import { DefaultResourceLoader } from "../../core/resource-loader.js";
 import { createAgentSession } from "../../core/sdk.js";
 import { createTeamRun, getTeamRun, listTeamRuns } from "../../core/agent-teams.js";
+import { buildSwarmPlanFromSingular, buildSwarmPlanFromTask, runSwarmScheduler, SwarmStateStore, } from "../../core/swarm/index.js";
 import { loadCustomSubagents, resolveCustomSubagentReference, } from "../../core/subagents.js";
 import { getSubagentRun, listSubagentRuns } from "../../core/subagent-runs.js";
 import { SessionManager } from "../../core/session-manager.js";
@@ -270,6 +274,41 @@ function resolveDoctorCliToolStatuses() {
     });
 }
 const OPENROUTER_PROVIDER_ID = "openrouter";
+const PROVIDER_DISPLAY_NAME_OVERRIDES = {
+    "azure-openai-responses": "Azure OpenAI Responses",
+    "google-antigravity": "Google Antigravity",
+    "google-gemini-cli": "Google Gemini CLI",
+    "kimi-coding": "Kimi Coding",
+    "openai-codex": "OpenAI Codex",
+    "opencode-go": "OpenCode Go",
+    "vercel-ai-gateway": "Vercel AI Gateway",
+};
+function toProviderDisplayName(providerId) {
+    const override = PROVIDER_DISPLAY_NAME_OVERRIDES[providerId];
+    if (override)
+        return override;
+    return providerId
+        .split(/[-_]/g)
+        .map((part) => {
+        const lower = part.toLowerCase();
+        if (lower === "ai")
+            return "AI";
+        if (lower === "api")
+            return "API";
+        if (lower === "gpt")
+            return "GPT";
+        if (lower === "aws")
+            return "AWS";
+        if (lower === "ui")
+            return "UI";
+        if (lower === "llm")
+            return "LLM";
+        if (lower === "id")
+            return "ID";
+        return part.charAt(0).toUpperCase() + part.slice(1);
+    })
+        .join(" ");
+}
 function isAbortLikeMessage(message) {
     const normalized = message.trim().toLowerCase();
     return normalized.includes("aborted") || normalized.includes("cancelled");
@@ -362,6 +401,7 @@ export class InteractiveMode {
         this.permissionPromptLock = Promise.resolve();
         this.sessionAllowedToolSignatures = new Set();
         this.singularLastEffectiveContract = {};
+        this.swarmActiveRunId = undefined;
         this.lastSigintTime = 0;
         this.lastEscapeTime = 0;
         this.changelogMarkdown = undefined;
@@ -375,6 +415,7 @@ export class InteractiveMode {
         this.pendingTools = new Map();
         // Subagent execution tracking with live progress/metadata for task tool calls.
         this.subagentComponents = new Map();
+        this.subagentElapsedTimer = undefined;
         // Internal UI metadata emitted by runtime for orchestration rendering.
         this.pendingInternalUserDisplayAliases = [];
         this.pendingAssistantOrchestrationContexts = 0;
@@ -417,6 +458,17 @@ export class InteractiveMode {
         this.builtInHeader = undefined;
         // ASCII logo component for startup screen
         this.asciiLogo = undefined;
+        // API-key provider labels cached for /login and status messages.
+        this.apiKeyProviderDisplayNames = new Map();
+        this.modelsDevProviderCatalog = MODELS_DEV_PROVIDERS;
+        this.modelsDevProviderCatalogById = new Map(MODELS_DEV_PROVIDERS.map((provider) => [
+            provider.id,
+            {
+                ...provider,
+                models: [],
+            },
+        ]));
+        this.modelsDevProviderCatalogRefreshPromise = undefined;
         // Custom header from extension (undefined = use built-in header)
         this.customHeader = undefined;
         /**
@@ -1010,6 +1062,32 @@ export class InteractiveMode {
         }
         return null;
     }
+    getSwarmArgumentCompletions(prefix) {
+        const subcommands = ["run", "from-singular", "watch", "retry", "resume", "help"];
+        const hasTrailingSpace = /\\s$/.test(prefix);
+        const tokens = this.parseSlashArgs(prefix);
+        const first = tokens[0]?.toLowerCase();
+        if (!first || (tokens.length === 1 && !hasTrailingSpace)) {
+            const query = first ?? "";
+            return subcommands.filter((item) => item.includes(query)).map((item) => ({ value: item, label: item }));
+        }
+        const active = first;
+        if (active === "run" || active === "from-singular") {
+            const flags = ["--max-parallel", "--budget-usd", ...(active === "from-singular" ? ["--option"] : [])];
+            const query = hasTrailingSpace ? "" : (tokens[tokens.length - 1] ?? "");
+            if (!query || query.startsWith("--")) {
+                return flags.filter((flag) => flag.includes(query)).map((flag) => ({ value: flag, label: flag }));
+            }
+        }
+        if (active === "retry") {
+            const flags = ["--reset-brief"];
+            const query = hasTrailingSpace ? "" : (tokens[tokens.length - 1] ?? "");
+            if (!query || query.startsWith("--")) {
+                return flags.filter((flag) => flag.includes(query)).map((flag) => ({ value: flag, label: flag }));
+            }
+        }
+        return null;
+    }
     setupAutocomplete(fdPath) {
         // Define commands for autocomplete
         const builtinCommands = BUILTIN_SLASH_COMMANDS.filter((command) => this.activeProfileName === "iosm" || !IOSM_PROFILE_ONLY_COMMANDS.has(command.name));
@@ -1063,6 +1141,10 @@ export class InteractiveMode {
         if (singularCommand) {
             singularCommand.getArgumentCompletions = (prefix) => this.getSingularArgumentCompletions(prefix);
         }
+        const swarmCommand = slashCommands.find((command) => command.name === "swarm");
+        if (swarmCommand) {
+            swarmCommand.getArgumentCompletions = (prefix) => this.getSwarmArgumentCompletions(prefix);
+        }
         // Convert prompt templates to SlashCommand format for autocomplete
         const templateCommands = this.session.promptTemplates.map((cmd) => ({
             name: cmd.name,
@@ -1241,6 +1323,8 @@ export class InteractiveMode {
         this.footerDataProvider.onBranchChange(() => {
             this.ui.requestRender();
         });
+        // Refresh provider catalog from models.dev in background once per startup.
+        void this.refreshModelsDevProviderCatalog();
         // Initialize available provider count for footer display
         await this.updateAvailableProviderCount();
     }
@@ -2581,6 +2665,11 @@ export class InteractiveMode {
                 await this.handleOrchestrateSlashCommand(text);
                 return;
             }
+            if (text === "/swarm" || text.startsWith("/swarm ")) {
+                this.editor.setText("");
+                await this.handleSwarmCommand(text);
+                return;
+            }
             if (text === "/agents" || text.startsWith("/agents ")) {
                 this.editor.setText("");
                 await this.handleAgentsSlashCommand(text);
@@ -2839,6 +2928,59 @@ export class InteractiveMode {
             this.editor.addToHistory?.(text);
         };
     }
+    updateRunningSubagentDisplay(subagent) {
+        subagent.component.update({
+            description: subagent.description,
+            profile: subagent.profile,
+            status: "running",
+            phase: subagent.phase ?? "running",
+            phaseState: subagent.phaseState,
+            cwd: subagent.cwd,
+            agent: subagent.agent,
+            lockKey: subagent.lockKey,
+            isolation: subagent.isolation,
+            activeTool: subagent.activeTool,
+            toolCallsStarted: subagent.toolCallsStarted,
+            toolCallsCompleted: subagent.toolCallsCompleted,
+            assistantMessages: subagent.assistantMessages,
+            delegatedTasks: subagent.delegatedTasks,
+            delegatedSucceeded: subagent.delegatedSucceeded,
+            delegatedFailed: subagent.delegatedFailed,
+            delegateIndex: subagent.delegateIndex,
+            delegateTotal: subagent.delegateTotal,
+            delegateDescription: subagent.delegateDescription,
+            delegateProfile: subagent.delegateProfile,
+            delegateItems: subagent.delegateItems,
+            durationMs: Date.now() - subagent.startTime,
+        });
+    }
+    ensureSubagentElapsedTimer() {
+        if (this.subagentElapsedTimer || this.subagentComponents.size === 0) {
+            return;
+        }
+        this.subagentElapsedTimer = setInterval(() => {
+            if (this.subagentComponents.size === 0) {
+                this.clearSubagentElapsedTimer();
+                return;
+            }
+            for (const subagent of this.subagentComponents.values()) {
+                this.updateRunningSubagentDisplay(subagent);
+            }
+            this.ui.requestRender();
+        }, 1000);
+    }
+    clearSubagentElapsedTimer() {
+        if (!this.subagentElapsedTimer) {
+            return;
+        }
+        clearInterval(this.subagentElapsedTimer);
+        this.subagentElapsedTimer = undefined;
+    }
+    stopSubagentElapsedTimerIfIdle() {
+        if (this.subagentComponents.size === 0) {
+            this.clearSubagentElapsedTimer();
+        }
+    }
     subscribeToAgent() {
         this.unsubscribe = this.session.subscribe(async (event) => {
             await this.handleEvent(event);
@@ -3020,6 +3162,7 @@ export class InteractiveMode {
                         delegateProfile: info.delegateProfile,
                         delegateItems: info.delegateItems,
                     });
+                    this.ensureSubagentElapsedTimer();
                     this.ui.requestRender();
                 }
                 else if (event.toolName !== "task" && !this.pendingTools.has(event.toolCallId)) {
@@ -3105,29 +3248,7 @@ export class InteractiveMode {
                             subagent.phase = text.trim();
                         }
                     }
-                    subagent.component.update({
-                        description: subagent.description,
-                        profile: subagent.profile,
-                        status: "running",
-                        phase: subagent.phase ?? "running",
-                        phaseState: subagent.phaseState,
-                        cwd: subagent.cwd,
-                        agent: subagent.agent,
-                        lockKey: subagent.lockKey,
-                        isolation: subagent.isolation,
-                        activeTool: subagent.activeTool,
-                        toolCallsStarted: subagent.toolCallsStarted,
-                        toolCallsCompleted: subagent.toolCallsCompleted,
-                        assistantMessages: subagent.assistantMessages,
-                        delegatedTasks: subagent.delegatedTasks,
-                        delegatedSucceeded: subagent.delegatedSucceeded,
-                        delegatedFailed: subagent.delegatedFailed,
-                        delegateIndex: subagent.delegateIndex,
-                        delegateTotal: subagent.delegateTotal,
-                        delegateDescription: subagent.delegateDescription,
-                        delegateProfile: subagent.delegateProfile,
-                        delegateItems: subagent.delegateItems,
-                    });
+                    this.updateRunningSubagentDisplay(subagent);
                     this.ui.requestRender();
                     break;
                 }
@@ -3191,6 +3312,7 @@ export class InteractiveMode {
                         this.pendingTools.delete(event.toolCallId);
                     }
                     this.subagentComponents.delete(event.toolCallId);
+                    this.stopSubagentElapsedTimerIfIdle();
                     this.ui.requestRender();
                     break;
                 }
@@ -3215,6 +3337,7 @@ export class InteractiveMode {
                 }
                 this.pendingTools.clear();
                 this.subagentComponents.clear();
+                this.clearSubagentElapsedTimer();
                 await this.checkShutdownRequested();
                 this.ui.requestRender();
                 break;
@@ -3797,7 +3920,7 @@ export class InteractiveMode {
                 this.updateEditorBorderColor();
                 this.refreshBuiltInHeader();
                 const thinkingStr = result.model.reasoning && result.thinkingLevel !== "off" ? ` (thinking: ${result.thinkingLevel})` : "";
-                this.showStatus(`Switched to ${result.model.name || result.model.id}${thinkingStr}`);
+                this.showStatus(`Switched to ${result.model.provider}/${result.model.id}${thinkingStr}`);
             }
         }
         catch (error) {
@@ -4837,7 +4960,7 @@ export class InteractiveMode {
                 this.footer.invalidate();
                 this.updateEditorBorderColor();
                 this.refreshBuiltInHeader();
-                this.showStatus(`Model: ${model.id}`);
+                this.showStatus(`Model: ${model.provider}/${model.id}`);
                 this.checkDaxnutsEasterEgg(model);
             }
             catch (error) {
@@ -4848,6 +4971,7 @@ export class InteractiveMode {
         this.showModelSelector(searchTerm);
     }
     async showModelProviderSelector(preferredProvider) {
+        await this.hydrateMissingProviderModelsForSavedAuth();
         this.session.modelRegistry.refresh();
         let models = [];
         try {
@@ -4959,7 +5083,7 @@ export class InteractiveMode {
                     this.updateEditorBorderColor();
                     this.refreshBuiltInHeader();
                     done();
-                    this.showStatus(`Model: ${model.id}`);
+                    this.showStatus(`Model: ${model.provider}/${model.id}`);
                     this.checkDaxnutsEasterEgg(model);
                 }
                 catch (error) {
@@ -5268,22 +5392,29 @@ export class InteractiveMode {
                 return;
             }
         }
+        await this.refreshModelsDevProviderCatalog();
+        const apiKeyProviders = this.getApiKeyLoginProviders(this.modelsDevProviderCatalog);
         this.showSelector((done) => {
-            const selector = new OAuthSelectorComponent(mode, this.session.modelRegistry.authStorage, async (providerId) => {
+            const selector = new OAuthSelectorComponent(mode, this.session.modelRegistry.authStorage, async (provider) => {
                 done();
                 if (mode === "login") {
-                    if (providerId === OPENROUTER_PROVIDER_ID) {
-                        await this.handleOpenRouterApiKeyLogin();
+                    if (provider.kind === "api_key") {
+                        if (provider.id === OPENROUTER_PROVIDER_ID) {
+                            await this.handleOpenRouterApiKeyLogin();
+                        }
+                        else {
+                            await this.handleApiKeyLogin(provider.id, { providerName: provider.name });
+                        }
                     }
                     else {
-                        await this.showLoginDialog(providerId);
+                        await this.showLoginDialog(provider.id);
                     }
                 }
                 else {
                     // Logout flow
-                    const providerName = this.getProviderDisplayName(providerId);
+                    const providerName = this.getProviderDisplayName(provider.id);
                     try {
-                        this.session.modelRegistry.authStorage.logout(providerId);
+                        this.session.modelRegistry.authStorage.logout(provider.id);
                         this.session.modelRegistry.refresh();
                         await this.updateAvailableProviderCount();
                         this.showStatus(`Logged out of ${providerName}`);
@@ -5295,21 +5426,156 @@ export class InteractiveMode {
             }, () => {
                 done();
                 this.ui.requestRender();
-            });
+            }, apiKeyProviders);
             return { component: selector, focus: selector };
         });
     }
+    async refreshModelsDevProviderCatalog() {
+        if (this.modelsDevProviderCatalogRefreshPromise) {
+            await this.modelsDevProviderCatalogRefreshPromise;
+            return;
+        }
+        this.modelsDevProviderCatalogRefreshPromise = (async () => {
+            const catalog = await loadModelsDevProviderCatalog();
+            this.modelsDevProviderCatalogById = catalog;
+            this.modelsDevProviderCatalog = Array.from(catalog.values())
+                .map((provider) => ({
+                id: provider.id,
+                name: provider.name,
+                env: provider.env,
+            }))
+                .sort((a, b) => a.name.localeCompare(b.name, "en") || a.id.localeCompare(b.id, "en"));
+        })()
+            .catch(() => {
+            this.modelsDevProviderCatalog = MODELS_DEV_PROVIDERS;
+            this.modelsDevProviderCatalogById = new Map(MODELS_DEV_PROVIDERS.map((provider) => [
+                provider.id,
+                {
+                    ...provider,
+                    models: [],
+                },
+            ]));
+        })
+            .finally(() => {
+            this.modelsDevProviderCatalogRefreshPromise = undefined;
+        });
+        await this.modelsDevProviderCatalogRefreshPromise;
+    }
+    resolveModelsDevApi(modelNpm) {
+        const npm = modelNpm?.toLowerCase() ?? "";
+        if (npm.includes("anthropic"))
+            return "anthropic-messages";
+        if (npm.includes("google-vertex"))
+            return "google-vertex";
+        if (npm.includes("google"))
+            return "google-generative-ai";
+        if (npm.includes("amazon-bedrock"))
+            return "bedrock-converse-stream";
+        if (npm.includes("mistral"))
+            return "mistral-conversations";
+        if (npm.includes("@ai-sdk/openai") && !npm.includes("compatible"))
+            return "openai-responses";
+        return "openai-completions";
+    }
+    buildModelsDevProviderConfig(providerInfo) {
+        const baseUrl = providerInfo.api ?? providerInfo.models.find((model) => !!model.api)?.api;
+        if (!baseUrl)
+            return undefined;
+        if (providerInfo.models.length === 0)
+            return undefined;
+        const models = providerInfo.models.map((model) => ({
+            id: model.id,
+            name: model.name,
+            api: this.resolveModelsDevApi(model.npm ?? providerInfo.npm),
+            reasoning: model.reasoning,
+            input: [...model.input],
+            cost: model.cost,
+            contextWindow: model.contextWindow,
+            maxTokens: model.maxTokens,
+            headers: Object.keys(model.headers).length > 0 ? model.headers : undefined,
+        }));
+        return {
+            baseUrl,
+            models,
+        };
+    }
+    hasRegisteredProviderModels(providerId) {
+        const registry = this.session.modelRegistry;
+        if (typeof registry.getAll !== "function")
+            return true;
+        return registry.getAll().some((model) => model.provider === providerId);
+    }
+    async hydrateProviderModelsFromModelsDev(providerId) {
+        if (this.hasRegisteredProviderModels(providerId))
+            return true;
+        await this.refreshModelsDevProviderCatalog();
+        const providerInfo = this.modelsDevProviderCatalogById.get(providerId);
+        if (!providerInfo)
+            return false;
+        const config = this.buildModelsDevProviderConfig(providerInfo);
+        if (!config)
+            return false;
+        try {
+            this.session.modelRegistry.registerProvider(providerId, config);
+            return this.hasRegisteredProviderModels(providerId);
+        }
+        catch {
+            return false;
+        }
+    }
+    async hydrateMissingProviderModelsForSavedAuth() {
+        const savedProviders = this.session.modelRegistry.authStorage.list();
+        if (savedProviders.length === 0)
+            return;
+        for (const providerId of savedProviders) {
+            if (this.hasRegisteredProviderModels(providerId))
+                continue;
+            await this.hydrateProviderModelsFromModelsDev(providerId);
+        }
+    }
+    getApiKeyLoginProviders(modelsDevProviders) {
+        const providerNames = new Map();
+        this.apiKeyProviderDisplayNames.clear();
+        for (const model of this.session.modelRegistry.getAll()) {
+            if (!providerNames.has(model.provider)) {
+                providerNames.set(model.provider, toProviderDisplayName(model.provider));
+            }
+        }
+        for (const provider of modelsDevProviders) {
+            const fallbackName = toProviderDisplayName(provider.id);
+            const current = providerNames.get(provider.id);
+            if (!current || current === fallbackName) {
+                providerNames.set(provider.id, provider.name || fallbackName);
+            }
+        }
+        for (const providerId of this.session.modelRegistry.authStorage.list()) {
+            if (!providerNames.has(providerId)) {
+                providerNames.set(providerId, toProviderDisplayName(providerId));
+            }
+        }
+        const oauthProviderIds = new Set(this.session.modelRegistry.authStorage.getOAuthProviders().map((provider) => provider.id));
+        const providers = [];
+        for (const [id, name] of providerNames.entries()) {
+            if (oauthProviderIds.has(id))
+                continue;
+            this.apiKeyProviderDisplayNames.set(id, name);
+            providers.push({ id, name, kind: "api_key" });
+        }
+        providers.sort((a, b) => a.name.localeCompare(b.name));
+        return providers;
+    }
     getProviderDisplayName(providerId) {
-        if (providerId === OPENROUTER_PROVIDER_ID) {
-            return "OpenRouter";
+        const apiKeyName = this.apiKeyProviderDisplayNames.get(providerId);
+        if (apiKeyName) {
+            return apiKeyName;
         }
         const providerInfo = this.session.modelRegistry.authStorage.getOAuthProviders().find((p) => p.id === providerId);
-        return providerInfo?.name || providerId;
+        return providerInfo?.name || toProviderDisplayName(providerId);
     }
-    async handleOpenRouterApiKeyLogin(options) {
+    async handleApiKeyLogin(providerId, options) {
+        const providerName = options?.providerName || this.getProviderDisplayName(providerId);
         const openModelSelector = options?.openModelSelector ?? true;
-        const providerName = this.getProviderDisplayName(OPENROUTER_PROVIDER_ID);
-        const existingCredential = this.session.modelRegistry.authStorage.get(OPENROUTER_PROVIDER_ID);
+        const existingCredential = this.session.modelRegistry.authStorage.get(providerId);
         if (existingCredential) {
             const overwrite = await this.showExtensionConfirm(`${providerName}: replace existing credentials?`, `Stored at ${getAuthPath()}`);
             if (!overwrite) {
@@ -5317,7 +5583,11 @@ export class InteractiveMode {
                 return;
             }
         }
-        const keyInput = await this.showExtensionInput(`${providerName} API key\nCreate key: https://openrouter.ai/keys`, "sk-or-v1-...");
+        const promptLines = [`${providerName} API key`];
+        if (options?.createKeyUrl) {
+            promptLines.push(`Create key: ${options.createKeyUrl}`);
+        }
+        const keyInput = await this.showExtensionInput(promptLines.join("\n"), options?.placeholder ?? "api-key");
         if (keyInput === undefined) {
             this.showStatus(`${providerName} login cancelled.`);
             return;
@@ -5327,13 +5597,28 @@ export class InteractiveMode {
             this.showWarning(`${providerName} API key cannot be empty.`);
             return;
         }
-        this.session.modelRegistry.authStorage.set(OPENROUTER_PROVIDER_ID, { type: "api_key", key: apiKey });
+        this.session.modelRegistry.authStorage.set(providerId, { type: "api_key", key: apiKey });
+        let hasProviderModels = this.hasRegisteredProviderModels(providerId);
+        if (!hasProviderModels) {
+            hasProviderModels = await this.hydrateProviderModelsFromModelsDev(providerId);
+        }
         await this.updateAvailableProviderCount();
         this.showStatus(`${providerName} API key saved to ${getAuthPath()}`);
-        if (openModelSelector) {
-            await this.showModelProviderSelector(OPENROUTER_PROVIDER_ID);
+        if (openModelSelector && hasProviderModels) {
+            await this.showModelProviderSelector(providerId);
+        }
+        else if (openModelSelector) {
+            this.showWarning(`${providerName} configured, but no models are available yet. Run /model after network is available.`);
         }
     }
+    async handleOpenRouterApiKeyLogin(options) {
+        await this.handleApiKeyLogin(OPENROUTER_PROVIDER_ID, {
+            providerName: "OpenRouter",
+            openModelSelector: options?.openModelSelector,
+            createKeyUrl: "https://openrouter.ai/keys",
+            placeholder: "sk-or-v1-...",
+        });
+    }
     async showLoginDialog(providerId) {
         const providerInfo = this.session.modelRegistry.authStorage.getOAuthProviders().find((p) => p.id === providerId);
         const providerName = this.getProviderDisplayName(providerId);
@@ -6838,7 +7123,105 @@ export class InteractiveMode {
         }
         return lines.length > 0 ? lines.join("\n") : "- none";
     }
-    buildSingularAgentPrompt(request, baseline, contract) {
+    resolveSingularRepoScaleMode(baseline) {
+        if (baseline.scannedFiles >= 8000 || baseline.sourceFiles >= 4000) {
+            return {
+                mode: "large",
+                reason: `scanned=${baseline.scannedFiles}, source=${baseline.sourceFiles}`,
+            };
+        }
+        if (baseline.scannedFiles >= 2500 || baseline.sourceFiles >= 1200) {
+            return {
+                mode: "medium",
+                reason: `scanned=${baseline.scannedFiles}, source=${baseline.sourceFiles}`,
+            };
+        }
+        return {
+            mode: "small",
+            reason: `scanned=${baseline.scannedFiles}, source=${baseline.sourceFiles}`,
+        };
+    }
+    buildSingularSemanticGuidanceFromStatus(status) {
+        if (!status.configured) {
+            return {
+                statusLine: "not_configured",
+                promptGuidance: [
+                    "Semantic index is unavailable; use narrow path-based discovery and avoid wide repo scans.",
+                    "If confidence is low, explicitly ask user to run /semantic setup and /semantic index, then rerun /singular.",
+                ],
+                operatorHint: "Large/medium repo mode: semantic index is not configured. Run /semantic setup, then /semantic index.",
+            };
+        }
+        if (!status.enabled) {
+            return {
+                statusLine: "configured_but_disabled",
+                promptGuidance: [
+                    "Semantic index is configured but disabled; proceed with targeted rg/read steps only.",
+                    "If discovery quality is insufficient, ask user to enable semantic search in /semantic setup.",
+                ],
+                operatorHint: "Large/medium repo mode: semantic index is disabled. Enable it in /semantic setup for faster planning.",
+            };
+        }
+        if (!status.indexed) {
+            return {
+                statusLine: "configured_not_indexed",
+                promptGuidance: [
+                    "Semantic index is configured but missing; do focused discovery and avoid broad scans.",
+                    "If context coverage is insufficient, ask user to run /semantic index before final recommendation.",
+                ],
+                operatorHint: "Large/medium repo mode: semantic index is missing. Run /semantic index.",
+            };
+        }
+        if (status.stale) {
+            const requiresRebuild = status.staleReason === "provider_changed" ||
+                status.staleReason === "chunking_changed" ||
+                status.staleReason === "index_filters_changed" ||
+                status.staleReason === "dimension_mismatch";
+            return {
+                statusLine: `stale${status.staleReason ? ` (${status.staleReason})` : ""}`,
+                promptGuidance: [
+                    "Semantic index is stale; treat semantic hits as hints and verify with direct file reads.",
+                    "If index staleness blocks confidence, ask user to run /semantic rebuild or /semantic index.",
+                ],
+                operatorHint: requiresRebuild
+                    ? "Large/medium repo mode: semantic index is stale and requires /semantic rebuild."
+                    : "Large/medium repo mode: semantic index is stale. Run /semantic index.",
+            };
+        }
+        return {
+            statusLine: `ready (${status.provider}/${status.model}, files=${status.files}, chunks=${status.chunks}, auto_index=${status.autoIndex ? "on" : "off"})`,
+            promptGuidance: [
+                "Use semantic_search for first-pass discovery, then confirm with targeted reads and grep.",
+                "Avoid full-tree scans unless evidence is still insufficient.",
+            ],
+        };
+    }
+    async buildSingularSemanticGuidance(scaleMode) {
+        if (scaleMode === "small") {
+            return {
+                statusLine: "optional_for_small_repo",
+                promptGuidance: [
+                    "Prefer direct targeted reads/grep; semantic index is optional for this repository size.",
+                ],
+            };
+        }
+        try {
+            const status = await this.createSemanticRuntime().status();
+            return this.buildSingularSemanticGuidanceFromStatus(status);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                statusLine: `status_unavailable (${message})`,
+                promptGuidance: [
+                    "Semantic status is unavailable; proceed with conservative targeted discovery.",
+                    "If discovery quality is insufficient, ask user to configure /semantic setup and rerun /singular.",
+                ],
+                operatorHint: `Large/medium repo mode: cannot read semantic status (${message}). Run /semantic status.`,
+            };
+        }
+    }
+    buildSingularAgentPrompt(request, baseline, contract, runtimeGuidance) {
         const filesHint = baseline.matchedFiles.length > 0
             ? baseline.matchedFiles.slice(0, 12).map((item) => `- ${item}`).join("\n")
             : "- no direct file matches found in heuristic pass";
@@ -6895,6 +7278,12 @@ export class InteractiveMode {
             `- baseline_blast_radius: ${baseline.baselineBlastRadius}`,
             `- baseline_recommendation: ${baseline.recommendation}`,
             "",
+            "Repository runtime guidance:",
+            `- scale_mode: ${runtimeGuidance.scaleMode}`,
+            `- scale_reason: ${runtimeGuidance.scaleReason}`,
+            `- semantic_status: ${runtimeGuidance.semanticStatusLine}`,
+            ...runtimeGuidance.semanticGuidance.map((line) => `- ${line}`),
+            "",
             "Matched file hints from baseline (verify, do not assume blindly):",
             filesHint,
             "",
@@ -7025,7 +7414,7 @@ export class InteractiveMode {
             hasRecommendation: recommendationRaw !== undefined,
         };
     }
-    async runSingularAgentFeasibilityPass(request, baseline, contract) {
+    async runSingularAgentFeasibilityPass(request, baseline, contract, runtimeGuidance) {
         const model = this.session.model;
         if (!model) {
             return undefined;
@@ -7076,7 +7465,7 @@ export class InteractiveMode {
         });
         this.singularAnalysisSession = session;
         try {
-            const primaryPrompt = this.buildSingularAgentPrompt(request, baseline, contract);
+            const primaryPrompt = this.buildSingularAgentPrompt(request, baseline, contract, runtimeGuidance);
             const strictRetryPrompt = [
                 "Retry strict mode:",
                 "- Inspect repository files using tools first.",
@@ -7176,7 +7565,7 @@ export class InteractiveMode {
         }
         lines.push("");
         lines.push("next_action:");
-        lines.push("  choose option 1/2/3 to generate a detailed execution draft in editor");
+        lines.push("  choose option 1/2/3, then pick Start with Swarm or Continue without Swarm");
         return lines.join("\n");
     }
     buildSingularExecutionDraft(result, option, contract) {
@@ -7280,10 +7669,22 @@ export class InteractiveMode {
             "cons:",
             ...picked.cons.map((item) => `- ${item}`),
         ].join("\n"));
-        if (picked.id === "3" || result.recommendation === "defer") {
+        if (picked.id === "3") {
             this.showStatus("Singular: defer option selected, implementation postponed.");
             return;
         }
+        const executionChoice = await this.showExtensionSelector("/singular: execution mode", ["Start with Swarm (Recommended)", "Continue without Swarm", "Cancel"]);
+        if (!executionChoice || executionChoice === "Cancel") {
+            this.showStatus("Singular: execution cancelled.");
+            return;
+        }
+        if (executionChoice.startsWith("Start with Swarm")) {
+            await this.runSwarmFromSingular({
+                runId: result.runId,
+                option: Number.parseInt(picked.id, 10),
+            });
+            return;
+        }
         this.editor.setText(this.buildSingularExecutionDraft(result, picked, this.singularLastEffectiveContract));
         this.showStatus("Singular: detailed execution draft generated in editor.");
     }
@@ -7319,13 +7720,27 @@ export class InteractiveMode {
                 autosave: false,
                 contract: effectiveContract,
             });
+            const scale = this.resolveSingularRepoScaleMode(baseline);
+            const semanticGuidance = await this.buildSingularSemanticGuidance(scale.mode);
+            if (scale.mode !== "small") {
+                this.showStatus(`Singular scale mode: ${scale.mode} (${scale.reason})`);
+            }
+            if (semanticGuidance.operatorHint) {
+                this.showWarning(semanticGuidance.operatorHint);
+            }
+            const runtimeGuidance = {
+                scaleMode: scale.mode,
+                scaleReason: scale.reason,
+                semanticStatusLine: semanticGuidance.statusLine,
+                semanticGuidance: semanticGuidance.promptGuidance,
+            };
             let result = baseline;
             if (!this.session.model) {
                 this.showWarning("No model selected. /singular used heuristic analysis only. Use /model to enable agent feasibility pass.");
             }
             else {
                 try {
-                    const enriched = await this.runSingularAgentFeasibilityPass(request, baseline, effectiveContract);
+                    const enriched = await this.runSingularAgentFeasibilityPass(request, baseline, effectiveContract, runtimeGuidance);
                     if (enriched) {
                         result = enriched;
                     }
@@ -7362,6 +7777,9 @@ export class InteractiveMode {
                 "  /singular last",
                 "  /singular help",
                 "",
+                "Flow:",
+                "  /singular -> choose option -> Start with Swarm or Continue without Swarm",
+                "",
                 "Examples:",
                 "  /singular add account dashboard",
                 "  /singular introduce RBAC for API",
@@ -8206,13 +8624,28 @@ export class InteractiveMode {
                     return;
                 }
             }
+            const mentionTask = cleaned.length > 0 ? cleaned : userInput;
+            const orchestrationAwareAgent = /orchestrator/i.test(mentionedAgent);
+            const mentionMode = orchestrationAwareAgent ? "parallel" : "sequential";
+            const mentionMaxParallel = orchestrationAwareAgent ? 20 : undefined;
             const mentionPrompt = [
-                "<orchestrate mode=\"sequential\" agents=\"1\">",
+                `<orchestrate mode="${mentionMode}" agents="1"${mentionMaxParallel ? ` max_parallel="${mentionMaxParallel}"` : ""}>`,
                 `- agent 1: profile=${this.activeProfileName} cwd=${this.sessionManager.getCwd()} agent=${mentionedAgent}`,
-                `task: ${cleaned.length > 0 ? cleaned : userInput}`,
+                `task: ${mentionTask}`,
                 "constraints:",
                 "- user selected a concrete custom agent via @mention",
                 `- MUST call task tool with agent="${mentionedAgent}"`,
+                ...(orchestrationAwareAgent
+                    ? [
+                        "- Include delegate_parallel_hint in the task call.",
+                        "- If user explicitly requested an agent count, set delegate_parallel_hint to that count (clamp 1..10).",
+                        "- Otherwise set delegate_parallel_hint based on complexity: simple=1, medium=3-6, complex/risky=7-10.",
+                        "- For non-trivial tasks, prefer delegate_parallel_hint >= 2 and split into independent <delegate_task> workstreams.",
+                        '- Prefer existing custom agents for delegated work when suitable (use <delegate_task agent="name" ...>).',
+                        "- If no existing custom agent fits, create focused delegate streams via profile-based <delegate_task> blocks.",
+                        "- If single-agent execution is still chosen, include one line: DELEGATION_IMPOSSIBLE: <reason>.",
+                    ]
+                    : []),
                 "</orchestrate>",
             ].join("\n");
             await this.session.prompt(mentionPrompt, {
@@ -8385,6 +8818,1104 @@ export class InteractiveMode {
         }
         return { targetIndex, maxIterations, forceInit };
     }
+    getSwarmHelpText() {
+        return [
+            "Usage:",
+            "  /swarm run <task> [--max-parallel N] [--budget-usd X]",
+            "  /swarm from-singular <run-id> --option <1|2|3> [--max-parallel N] [--budget-usd X]",
+            "  /swarm watch [run-id]",
+            "  /swarm retry <run-id> <task-id> [--reset-brief]",
+            "  /swarm resume <run-id>",
+            "  /swarm help",
+            "",
+            "Consistency model:",
+            "  Scopes -> Touches -> Locks -> Gates -> Done",
+        ].join("\n");
+    }
+    buildSwarmRecommendationFromOrchestrate(parsed) {
+        const reasons = [];
+        let score = 0;
+        const task = parsed.task.replace(/\s+/g, " ").trim();
+        const normalizedTask = task.toLowerCase();
+        const dependencyEdges = parsed.dependencies?.reduce((sum, entry) => sum + entry.dependsOn.length, 0) ?? 0;
+        const effectiveParallel = parsed.mode === "parallel" ? parsed.maxParallel ?? parsed.agents : 1;
+        const highRiskPattern = /\b(refactor|rewrite|migration|migrate|breaking|rollback|security|auth|authentication|authorization|permission|payment|billing|schema|database|critical)\b/i;
+        const mediumRiskPattern = /\b(cross[-\s]?module|architecture|infra|platform|multi[-\s]?file|integration)\b/i;
+        if (highRiskPattern.test(normalizedTask)) {
+            score += 2;
+            reasons.push("task has high-risk keywords");
+        }
+        else if (mediumRiskPattern.test(normalizedTask)) {
+            score += 1;
+            reasons.push("task has architecture/cross-module scope");
+        }
+        if (parsed.agents >= 4) {
+            score += 2;
+            reasons.push(`high agent count (${parsed.agents})`);
+        }
+        else if (parsed.agents >= 3) {
+            score += 1;
+            reasons.push(`multi-agent run (${parsed.agents})`);
+        }
+        if (dependencyEdges >= 3) {
+            score += 2;
+            reasons.push(`complex dependency graph (${dependencyEdges} edges)`);
+        }
+        else if (dependencyEdges > 0) {
+            score += 1;
+            reasons.push(`dependency graph present (${dependencyEdges} edges)`);
+        }
+        if (effectiveParallel >= 3) {
+            score += 1;
+            reasons.push(`high parallelism (${effectiveParallel})`);
+        }
+        if ((parsed.locks?.length ?? 0) > 0) {
+            score += 1;
+            reasons.push("explicit lock coordination requested");
+        }
+        if (task.length >= 180) {
+            score += 1;
+            reasons.push("long task brief");
+        }
+        const safeTask = task.replace(/"/g, "'");
+        const commandParts = [`/swarm run "${safeTask}"`];
+        if (parsed.maxParallel !== undefined && parsed.maxParallel > 0) {
+            commandParts.push(`--max-parallel ${parsed.maxParallel}`);
+        }
+        return {
+            recommend: score >= 3,
+            reasons,
+            command: commandParts.join(" "),
+        };
+    }
+    isEffectiveContractReady(contract) {
+        const hasText = (value) => typeof value === "string" && value.trim().length > 0;
+        const hasList = (value) => Array.isArray(value) && value.some((item) => item.trim().length > 0);
+        return (hasText(contract.goal) ||
+            hasList(contract.scope_include) ||
+            hasList(contract.constraints) ||
+            hasList(contract.quality_gates) ||
+            hasList(contract.definition_of_done));
+    }
+    parseContractListInput(raw) {
+        if (!raw)
+            return [];
+        return raw
+            .split(/[\n;,]+/)
+            .map((item) => item.trim())
+            .filter((item) => item.length > 0);
+    }
+    buildAutoDraftContractFromTask(task) {
+        const normalizedTask = task.replace(/\s+/g, " ").trim();
+        const hints = loadProjectIndex(this.sessionManager.getCwd());
+        const matchedFiles = hints ? queryProjectIndex(hints, task, 8).matches.map((entry) => entry.path) : [];
+        const scopeInclude = matchedFiles.length > 0 ? matchedFiles.map((filePath) => filePath.split("/").slice(0, 2).join("/")).slice(0, 6) : [];
+        return normalizeEngineeringContract({
+            goal: normalizedTask.length > 0 ? normalizedTask : "Deliver requested change safely with bounded blast radius.",
+            scope_include: scopeInclude.length > 0 ? [...new Set(scopeInclude)].map((scope) => `${scope}/**`) : ["src/**", "test/**"],
+            scope_exclude: ["node_modules/**", "dist/**", ".iosm/**"],
+            constraints: [
+                "Preserve backward compatibility unless explicitly approved.",
+                "Keep changes scoped to declared touch zones.",
+            ],
+            quality_gates: [
+                "Targeted tests for touched modules pass.",
+                "Lint/type checks pass for changed files.",
+            ],
+            definition_of_done: [
+                "Implementation merged with verification evidence.",
+                "Risk notes and rollback path documented.",
+            ],
+        });
+    }
+    async runSwarmContractGuidedInterview(task) {
+        const goal = await this.showExtensionInput("Swarm contract: goal (required)", task.trim() || "Deliver requested change safely.");
+        if (goal === undefined)
+            return undefined;
+        const scopeInclude = await this.showExtensionInput("Swarm contract: scope_include (comma/newline separated)", "src/**, test/**");
+        if (scopeInclude === undefined)
+            return undefined;
+        const scopeExclude = await this.showExtensionInput("Swarm contract: scope_exclude (comma/newline separated)", "node_modules/**, dist/**, .iosm/**");
+        if (scopeExclude === undefined)
+            return undefined;
+        const constraints = await this.showExtensionInput("Swarm contract: constraints (comma/newline separated)", "no breaking API changes; no unrelated refactors");
+        if (constraints === undefined)
+            return undefined;
+        const gates = await this.showExtensionInput("Swarm contract: quality_gates (comma/newline separated)", "targeted tests pass; lint/type checks pass");
+        if (gates === undefined)
+            return undefined;
+        const done = await this.showExtensionInput("Swarm contract: definition_of_done (comma/newline separated)", "implementation complete; validation evidence attached");
+        if (done === undefined)
+            return undefined;
+        return normalizeEngineeringContract({
+            goal: goal.trim(),
+            scope_include: this.parseContractListInput(scopeInclude),
+            scope_exclude: this.parseContractListInput(scopeExclude),
+            constraints: this.parseContractListInput(constraints),
+            quality_gates: this.parseContractListInput(gates),
+            definition_of_done: this.parseContractListInput(done),
+        });
+    }
+    async ensureSwarmEffectiveContract(task) {
+        const initialState = this.getContractStateSafe();
+        if (!initialState)
+            return undefined;
+        if (this.isEffectiveContractReady(initialState.effective)) {
+            return initialState.effective;
+        }
+        while (true) {
+            const selected = await this.showExtensionSelector([
+                "/swarm requires an effective /contract before execution can start.",
+                "Choose how to bootstrap contract policy:",
+            ].join("\n"), [
+                "Auto-draft from task (Recommended)",
+                "Guided Q&A",
+                "Open manual /contract editor",
+                "Cancel",
+            ]);
+            if (!selected || selected === "Cancel") {
+                this.showStatus("Swarm cancelled: contract bootstrap not completed.");
+                return undefined;
+            }
+            if (selected.startsWith("Auto-draft")) {
+                try {
+                    const draft = this.buildAutoDraftContractFromTask(task);
+                    this.contractService.save("session", draft);
+                    this.syncRuntimePromptSuffix();
+                    this.showStatus("Swarm contract bootstrap: auto-draft saved to session overlay.");
+                }
+                catch (error) {
+                    this.showWarning(error instanceof Error ? error.message : String(error));
+                }
+            }
+            else if (selected === "Guided Q&A") {
+                const drafted = await this.runSwarmContractGuidedInterview(task);
+                if (!drafted) {
+                    this.showStatus("Swarm contract interview cancelled.");
+                }
+                else {
+                    try {
+                        this.contractService.save("session", drafted);
+                        this.syncRuntimePromptSuffix();
+                        this.showStatus("Swarm contract bootstrap: guided contract saved to session overlay.");
+                    }
+                    catch (error) {
+                        this.showWarning(error instanceof Error ? error.message : String(error));
+                    }
+                }
+            }
+            else if (selected === "Open manual /contract editor") {
+                await this.runContractInteractiveMenu();
+            }
+            const state = this.getContractStateSafe();
+            if (!state)
+                return undefined;
+            if (this.isEffectiveContractReady(state.effective)) {
+                return state.effective;
+            }
+            this.showWarning("Effective contract is still empty. Swarm execution remains blocked.");
+        }
+    }
+    async maybeWarnSwarmSemantic(scaleMode) {
+        if (scaleMode === "small") {
+            return "optional_for_small_repo";
+        }
+        try {
+            const status = await this.createSemanticRuntime().status();
+            if (!status.configured) {
+                this.showWarning("Swarm recommendation: configure semantic index via /semantic setup and /semantic index.");
+                return "not_configured";
+            }
+            if (!status.enabled) {
+                this.showWarning("Swarm recommendation: enable semantic index in /semantic setup for medium/large repositories.");
+                return "configured_but_disabled";
+            }
+            if (!status.indexed) {
+                this.showWarning("Swarm recommendation: run /semantic index before long swarm runs.");
+                return "configured_not_indexed";
+            }
+            if (status.stale) {
+                const action = status.staleReason === "provider_changed" || status.staleReason === "dimension_mismatch" ? "/semantic rebuild" : "/semantic index";
+                this.showWarning(`Swarm recommendation: semantic index is stale (${status.staleReason ?? "unknown"}). Run ${action}.`);
+                return `stale:${status.staleReason ?? "unknown"}`;
+            }
+            return `ready:${status.provider}/${status.model}`;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.showWarning(`Swarm recommendation: semantic status unavailable (${message}). Use /semantic status.`);
+            return `status_unavailable:${message}`;
+        }
+    }
+    ensureSwarmProjectIndex(task) {
+        const cwd = this.sessionManager.getCwd();
+        const existing = loadProjectIndex(cwd);
+        if (existing) {
+            if (existing.meta.repoScaleMode === "small") {
+                return { index: existing, scaleMode: "small", rebuilt: false };
+            }
+            const ensured = ensureProjectIndex(cwd, existing.meta.repoScaleMode);
+            return { index: ensured.index, scaleMode: ensured.index.meta.repoScaleMode, rebuilt: ensured.rebuilt };
+        }
+        const quick = buildProjectIndex(cwd, { maxFiles: 6_000 });
+        const scaleMode = quick.meta.repoScaleMode;
+        if (scaleMode === "small") {
+            return { index: quick, scaleMode, rebuilt: true };
+        }
+        saveProjectIndex(cwd, quick);
+        return { index: quick, scaleMode, rebuilt: true };
+    }
+    parseSwarmCommand(text) {
+        const args = this.parseSlashArgs(text).slice(1);
+        if (args.length === 0) {
+            return { subcommand: "help" };
+        }
+        const subcommand = (args[0] ?? "").toLowerCase();
+        const rest = args.slice(1);
+        if (subcommand === "help" || subcommand === "-h" || subcommand === "--help") {
+            return { subcommand: "help" };
+        }
+        if (subcommand === "watch") {
+            return {
+                subcommand: "watch",
+                runId: rest[0],
+            };
+        }
+        if (subcommand === "resume") {
+            const runId = rest[0];
+            if (!runId) {
+                this.showWarning("Usage: /swarm resume <run-id>");
+                return undefined;
+            }
+            return { subcommand: "resume", runId };
+        }
+        if (subcommand === "retry") {
+            const runId = rest[0];
+            const taskId = rest[1];
+            if (!runId || !taskId) {
+                this.showWarning("Usage: /swarm retry <run-id> <task-id> [--reset-brief]");
+                return undefined;
+            }
+            const resetBrief = rest.slice(2).some((token) => token === "--reset-brief");
+            return { subcommand: "retry", runId, taskId, resetBrief };
+        }
+        let maxParallel;
+        let budgetUsd;
+        const taskParts = [];
+        let fromSingularOption;
+        let fromSingularRunId;
+        for (let index = 0; index < rest.length; index += 1) {
+            const token = rest[index] ?? "";
+            if (token === "--max-parallel") {
+                const next = rest[index + 1];
+                const parsed = next ? Number.parseInt(next, 10) : Number.NaN;
+                if (!Number.isInteger(parsed) || parsed < 1 || parsed > 20) {
+                    this.showWarning("Invalid --max-parallel value (expected 1..20).");
+                    return undefined;
+                }
+                maxParallel = parsed;
+                index += 1;
+                continue;
+            }
+            if (token === "--budget-usd") {
+                const next = rest[index + 1];
+                const parsed = next ? Number.parseFloat(next) : Number.NaN;
+                if (!Number.isFinite(parsed) || parsed <= 0) {
+                    this.showWarning("Invalid --budget-usd value (expected > 0).");
+                    return undefined;
+                }
+                budgetUsd = parsed;
+                index += 1;
+                continue;
+            }
+            if (token === "--option") {
+                const next = rest[index + 1];
+                const parsed = next ? Number.parseInt(next, 10) : Number.NaN;
+                if (!Number.isInteger(parsed) || parsed < 1 || parsed > 3) {
+                    this.showWarning("Invalid --option value (expected 1|2|3).");
+                    return undefined;
+                }
+                fromSingularOption = parsed;
+                index += 1;
+                continue;
+            }
+            if (token.startsWith("-")) {
+                this.showWarning(`Unknown option for /swarm ${subcommand}: ${token}`);
+                return undefined;
+            }
+            if (subcommand === "from-singular" && !fromSingularRunId) {
+                fromSingularRunId = token;
+                continue;
+            }
+            taskParts.push(token);
+        }
+        if (subcommand === "run") {
+            const task = taskParts.join(" ").trim();
+            if (!task) {
+                this.showWarning("Usage: /swarm run <task> [--max-parallel N] [--budget-usd X]");
+                return undefined;
+            }
+            return { subcommand, task, maxParallel, budgetUsd };
+        }
+        if (subcommand === "from-singular") {
+            if (!fromSingularRunId || !fromSingularOption) {
+                this.showWarning("Usage: /swarm from-singular <run-id> --option <1|2|3> [--max-parallel N] [--budget-usd X]");
+                return undefined;
+            }
+            return {
+                subcommand,
+                runId: fromSingularRunId,
+                option: fromSingularOption,
+                maxParallel,
+                budgetUsd,
+            };
+        }
+        this.showWarning(`Unknown /swarm subcommand "${subcommand}". Use /swarm help.`);
+        return undefined;
+    }
+    buildSwarmBootstrapState(runId, plan, budgetUsd) {
+        const tasks = {};
+        for (const task of plan.tasks) {
+            tasks[task.id] = {
+                id: task.id,
+                status: task.depends_on.length === 0 ? "ready" : "pending",
+                attempts: 0,
+                depends_on: [...task.depends_on],
+                touches: [...task.touches],
+                scopes: [...task.scopes],
+            };
+        }
+        return {
+            runId,
+            status: "running",
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            tick: 0,
+            noProgressTicks: 0,
+            readyQueue: Object.values(tasks)
+                .filter((task) => task.status === "ready")
+                .map((task) => task.id),
+            blockedTasks: [],
+            tasks,
+            locks: {},
+            retries: {},
+            budget: {
+                limitUsd: budgetUsd,
+                spentUsd: 0,
+                warned80: false,
+                hardStopped: false,
+            },
+        };
+    }
+    buildSwarmRunMeta(input) {
+        return {
+            runId: input.runId,
+            createdAt: new Date().toISOString(),
+            source: input.source,
+            request: input.request,
+            contract: input.contract,
+            contractHash: crypto.createHash("sha256").update(JSON.stringify(input.contract)).digest("hex").slice(0, 16),
+            repoScaleMode: input.repoScaleMode,
+            semanticStatus: input.semanticStatus,
+            maxParallel: input.maxParallel,
+            budgetUsd: input.budgetUsd,
+            linkedSingularRunId: input.linkedSingularRunId,
+            linkedSingularOption: input.linkedSingularOption,
+        };
+    }
+    resolveSwarmTaskProfile(task) {
+        if (task.concurrency_class === "analysis")
+            return "explore";
+        if (task.concurrency_class === "verification" || task.concurrency_class === "tests")
+            return "iosm_verifier";
+        if (task.concurrency_class === "docs")
+            return "plan";
+        return "full";
+    }
+    estimateSwarmTaskCostUsd(task) {
+        if (task.severity === "high")
+            return 0.35;
+        if (task.severity === "medium")
+            return 0.2;
+        return 0.12;
+    }
+    deriveSwarmTaskDelegateParallelHint(task) {
+        const brief = task.brief.toLowerCase();
+        const hasComplexKeyword = /(refactor|migration|rewrite|split|cross[-\s]?module|architecture|platform|integration|security|auth)/i.test(brief);
+        const hasVeryComplexSignal = /(overhaul|major|system-wide|cross-cutting|multi-service|facet|registry)/i.test(brief) ||
+            task.touches.length >= 5 ||
+            task.scopes.length >= 4;
+        if (task.severity === "low" && task.touches.length <= 2 && task.scopes.length <= 2 && !hasComplexKeyword) {
+            return 1;
+        }
+        if (task.severity === "high" && (hasVeryComplexSignal || hasComplexKeyword || task.touches.length >= 3)) {
+            return 10;
+        }
+        if (task.severity === "high")
+            return 8;
+        if (task.severity === "medium" && (hasVeryComplexSignal || task.touches.length >= 4 || hasComplexKeyword))
+            return 7;
+        if (task.severity === "medium")
+            return 5;
+        return hasComplexKeyword ? 3 : 1;
+    }
+    parseSwarmSpawnCandidates(output, parentTaskId) {
+        const lines = output.split(/\r?\n/);
+        const results = [];
+        for (const rawLine of lines) {
+            const line = rawLine.trim();
+            const match = line.match(/^[*-]\s+(.+?)\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|\s*(low|medium|high)\s*$/i);
+            if (!match)
+                continue;
+            results.push({
+                description: match[1].trim(),
+                path: match[2].trim(),
+                changeType: match[3].trim(),
+                severity: match[4].trim().toLowerCase(),
+                parentTaskId,
+            });
+            if (results.length >= 10)
+                break;
+        }
+        return results;
+    }
+    loadSingularAnalysisByRunId(runId) {
+        const analysisPath = path.join(this.singularService.getAnalysesRoot(), runId, "analysis.json");
+        if (!fs.existsSync(analysisPath))
+            return undefined;
+        try {
+            return JSON.parse(fs.readFileSync(analysisPath, "utf8"));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async dispatchSwarmTaskWithAgent(input) {
+        const model = this.session.model;
+        if (!model) {
+            return {
+                taskId: input.task.id,
+                status: "error",
+                error: "No active model configured for swarm task dispatch.",
+                costUsd: this.estimateSwarmTaskCostUsd(input.task),
+            };
+        }
+        const profile = this.resolveSwarmTaskProfile(input.task);
+        const delegateParallelHint = this.deriveSwarmTaskDelegateParallelHint(input.task);
+        const safeDescription = input.task.brief.replace(/\s+/g, " ").trim().slice(0, 120).replace(/"/g, "'");
+        const prompt = [
+            `<swarm_task run_id="${input.meta.runId}" task_id="${input.task.id}" profile_hint="${profile}">`,
+            `request: ${input.meta.request}`,
+            `task_brief: ${input.task.brief}`,
+            `touches: ${input.runtime.touches.join(", ") || "(none)"}`,
+            `scopes: ${input.runtime.scopes.join(", ") || "(none)"}`,
+            `constraints: ${(input.contract.constraints ?? []).join("; ") || "(none)"}`,
+            `quality_gates: ${(input.contract.quality_gates ?? []).join("; ") || "(none)"}`,
+            "",
+            "Execution requirements:",
+            `- Use the task tool exactly once with description="${safeDescription || input.task.id}", profile="${profile}", delegate_parallel_hint=${delegateParallelHint}, run_id="${input.meta.runId}", task_id="${input.task.id}".`,
+            `- Inside this single task call, prefer decomposition into <delegate_task> subtasks when delegate_parallel_hint >= 2 (target parallel fan-out up to ${delegateParallelHint}).`,
+            "- If decomposition is not beneficial, continue with single-agent execution (optional note: DELEGATION_IMPOSSIBLE: <reason>).",
+            "- Keep edits inside declared scopes/touches. If scope expansion is required, explain and stop.",
+            "- If blocked, respond with line: BLOCKED: <reason>",
+            "- Optional spawn candidates format: '- <description> | <path> | <change_type> | <low|medium|high>'",
+            "</swarm_task>",
+        ].join("\n");
+        const cwd = this.sessionManager.getCwd();
+        const agentDir = getAgentDir();
+        const settingsManager = SettingsManager.create(cwd, agentDir);
+        const authStorage = this.session.modelRegistry.authStorage;
+        const resourceLoader = new DefaultResourceLoader({
+            cwd,
+            agentDir,
+            settingsManager,
+            noExtensions: true,
+            noSkills: true,
+            noPromptTemplates: true,
+        });
+        try {
+            await resourceLoader.reload();
+        }
+        catch (error) {
+            return {
+                taskId: input.task.id,
+                status: "error",
+                error: `Failed to initialize swarm task runtime: ${error instanceof Error ? error.message : String(error)}`,
+                costUsd: this.estimateSwarmTaskCostUsd(input.task),
+            };
+        }
+        let swarmSession;
+        try {
+            const created = await createAgentSession({
+                cwd,
+                sessionManager: SessionManager.inMemory(),
+                settingsManager,
+                authStorage,
+                modelRegistry: this.session.modelRegistry,
+                resourceLoader,
+                model,
+                thinkingLevel: this.session.thinkingLevel,
+                profile: "full",
+                enableTaskTool: true,
+            });
+            swarmSession = created.session;
+        }
+        catch (error) {
+            return {
+                taskId: input.task.id,
+                status: "error",
+                error: `Failed to create isolated swarm session: ${error instanceof Error ? error.message : String(error)}`,
+                costUsd: this.estimateSwarmTaskCostUsd(input.task),
+            };
+        }
+        let taskToolCalls = 0;
+        const taskErrors = [];
+        let delegatedFailed = 0;
+        let delegatedTasks = 0;
+        const delegatedFailureCauses = new Map();
+        const accumulateFailureCauses = (raw) => {
+            if (!raw || typeof raw !== "object")
+                return;
+            for (const [cause, count] of Object.entries(raw)) {
+                if (typeof cause !== "string" || !cause.trim())
+                    continue;
+                const numeric = typeof count === "number" ? count : Number.parseInt(String(count ?? 0), 10);
+                if (!Number.isFinite(numeric) || numeric <= 0)
+                    continue;
+                delegatedFailureCauses.set(cause, (delegatedFailureCauses.get(cause) ?? 0) + numeric);
+            }
+        };
+        const chunks = [];
+        const unsubscribe = swarmSession.subscribe((event) => {
+            if (event.type === "tool_execution_start" && event.toolName === "task") {
+                taskToolCalls += 1;
+                return;
+            }
+            if (event.type === "tool_execution_end" && event.toolName === "task") {
+                const result = event.result;
+                const details = result?.details;
+                if (typeof details?.delegatedFailed === "number" && Number.isFinite(details.delegatedFailed)) {
+                    delegatedFailed += Math.max(0, details.delegatedFailed);
+                }
+                if (typeof details?.delegatedTasks === "number" && Number.isFinite(details.delegatedTasks)) {
+                    delegatedTasks += Math.max(0, details.delegatedTasks);
+                }
+                accumulateFailureCauses(details?.failureCauses);
+                if (event.isError) {
+                    taskErrors.push(result?.error ?? result?.output ?? "task tool failed");
+                }
+                return;
+            }
+            if (event.type === "message_end" && event.message.role === "assistant") {
+                for (const part of event.message.content) {
+                    if (part.type === "text" && part.text.trim()) {
+                        chunks.push(part.text.trim());
+                    }
+                }
+            }
+        });
+        try {
+            await swarmSession.prompt(prompt, {
+                expandPromptTemplates: false,
+                skipIosmAutopilot: true,
+                skipOrchestrationDirective: true,
+                source: "interactive",
+            });
+        }
+        catch (error) {
+            return {
+                taskId: input.task.id,
+                status: "error",
+                error: error instanceof Error ? error.message : String(error),
+                costUsd: this.estimateSwarmTaskCostUsd(input.task),
+            };
+        }
+        finally {
+            unsubscribe();
+            if (swarmSession.isStreaming) {
+                await swarmSession.abort().catch(() => {
+                    // best effort
+                });
+            }
+            swarmSession.dispose();
+        }
+        const output = chunks.join("\n\n").trim();
+        if (/^\s*BLOCKED\s*:/im.test(output)) {
+            const reason = output.match(/^\s*BLOCKED\s*:\s*(.+)$/im)?.[1]?.trim() ?? "Blocked by execution policy.";
+            return {
+                taskId: input.task.id,
+                status: "blocked",
+                error: reason,
+                costUsd: this.estimateSwarmTaskCostUsd(input.task),
+            };
+        }
+        if (taskToolCalls === 0) {
+            return {
+                taskId: input.task.id,
+                status: "error",
+                error: "No task tool call executed by assistant.",
+                costUsd: this.estimateSwarmTaskCostUsd(input.task),
+            };
+        }
+        if (taskErrors.length > 0) {
+            return {
+                taskId: input.task.id,
+                status: "error",
+                error: taskErrors.join(" | "),
+                failureCause: "task_tool_error",
+                costUsd: this.estimateSwarmTaskCostUsd(input.task),
+            };
+        }
+        if (delegatedFailed > 0) {
+            const failureSummary = [...delegatedFailureCauses.entries()]
+                .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+                .map(([cause, count]) => `${cause}=${count}`)
+                .join(", ");
+            const totalDelegates = delegatedTasks > 0 ? delegatedTasks : delegatedFailed;
+            const error = `delegates_failed ${delegatedFailed}/${totalDelegates}${failureSummary ? ` (${failureSummary})` : ""}`;
+            return {
+                taskId: input.task.id,
+                status: "error",
+                error,
+                failureCause: failureSummary || "delegates_failed",
+                costUsd: this.estimateSwarmTaskCostUsd(input.task),
+            };
+        }
+        return {
+            taskId: input.task.id,
+            status: "done",
+            costUsd: this.estimateSwarmTaskCostUsd(input.task),
+            spawnCandidates: this.parseSwarmSpawnCandidates(output, input.task.id),
+        };
+    }
+    async executeSwarmRun(input) {
+        const cwd = this.sessionManager.getCwd();
+        const store = new SwarmStateStore(cwd, input.runId);
+        const initialState = input.resumeState ?? this.buildSwarmBootstrapState(input.runId, input.plan, input.budgetUsd);
+        if (!input.resumeState) {
+            store.init(input.meta, input.plan, initialState);
+        }
+        let rollingIndex = input.projectIndex;
+        let localStopRequested = false;
+        const refreshIncrementalIndex = () => {
+            if (!input.enableIncrementalIndex || !rollingIndex)
+                return;
+            const changed = collectChangedFilesSince(rollingIndex, cwd);
+            if (changed.length === 0)
+                return;
+            const rebuilt = buildProjectIndex(cwd, {
+                incrementalFrom: rollingIndex,
+                changedFiles: changed,
+                maxFiles: Math.max(2_000, rollingIndex.meta.totalFiles + 1_000),
+            });
+            saveProjectIndex(cwd, rebuilt);
+            rollingIndex = rebuilt;
+        };
+        this.swarmActiveRunId = input.runId;
+        this.showStatus(`Swarm run started: ${input.runId}`);
+        const schedulerResult = await runSwarmScheduler({
+            runId: input.runId,
+            plan: input.plan,
+            contract: input.contract,
+            maxParallel: input.meta.maxParallel,
+            budgetUsd: input.budgetUsd,
+            existingState: initialState,
+            dispatchTask: async ({ task, runtime }) => this.dispatchSwarmTaskWithAgent({
+                meta: input.meta,
+                task,
+                runtime,
+                contract: input.contract,
+            }),
+            confirmSpawn: async ({ candidate, parentTask }) => {
+                const requiresConfirmation = candidate.severity === "high" || parentTask.spawn_policy === "manual_high_risk";
+                if (!requiresConfirmation)
+                    return true;
+                const choice = await this.showExtensionSelector([
+                    `/swarm spawn candidate requires confirmation`,
+                    `severity=${candidate.severity} task=${parentTask.id}`,
+                    `description=${candidate.description}`,
+                    `path=${candidate.path}`,
+                ].join("\n"), ["Approve spawn", "Reject spawn (Recommended)", "Abort run"]);
+                if (!choice || choice.startsWith("Reject")) {
+                    this.showStatus(`Swarm spawn rejected: ${candidate.description}`);
+                    return false;
+                }
+                if (choice === "Abort run") {
+                    localStopRequested = true;
+                    this.showWarning("Swarm run marked to stop after current scheduling step.");
+                    return false;
+                }
+                return true;
+            },
+            onEvent: (event) => {
+                store.appendEvent(event);
+            },
+            onStateChanged: (state) => {
+                store.saveState(state);
+                store.saveCheckpoint(state);
+                refreshIncrementalIndex();
+            },
+            shouldStop: () => this.shutdownRequested || localStopRequested,
+        });
+        this.swarmActiveRunId = undefined;
+        const taskStates = Object.values(schedulerResult.state.tasks);
+        const doneCount = taskStates.filter((task) => task.status === "done").length;
+        const errorCount = taskStates.filter((task) => task.status === "error").length;
+        const blockedCount = taskStates.filter((task) => task.status === "blocked").length;
+        const total = taskStates.length;
+        const reportLines = [
+            "# Swarm Integration Report",
+            "",
+            `- run_id: ${input.runId}`,
+            `- source: ${input.meta.source}`,
+            `- request: ${input.meta.request}`,
+            `- status: ${schedulerResult.state.status}`,
+            `- tasks: ${doneCount}/${total} done, ${errorCount} error, ${blockedCount} blocked`,
+            `- budget: ${schedulerResult.state.budget.spentUsd.toFixed(2)}${input.meta.budgetUsd ? ` / ${input.meta.budgetUsd.toFixed(2)}` : ""} USD`,
+            "",
+            "## Consistency Model",
+            "Scopes -> Touches -> Locks -> Gates -> Done",
+            "",
+            "## Task Gates",
+            ...schedulerResult.taskGates.map((gate) => `- ${gate.taskId}: ${gate.pass ? "pass" : "fail"}${gate.failures.length > 0 ? ` (${gate.failures.join("; ")})` : ""}`),
+            "",
+            "## Run Gates",
+            `- pass: ${schedulerResult.runGate.pass}`,
+            ...schedulerResult.runGate.failures.map((item) => `- fail: ${item}`),
+            ...schedulerResult.runGate.warnings.map((item) => `- warn: ${item}`),
+            "",
+            "## Spawn Backlog",
+            ...(schedulerResult.spawnBacklog.length > 0
+                ? schedulerResult.spawnBacklog.map((item) => `- ${item.description} | ${item.path} | ${item.changeType} | fp=${item.fingerprint}`)
+                : ["- none"]),
+        ];
+        store.writeReports({
+            integrationReport: reportLines.join("\n"),
+            gates: {
+                task_gates: schedulerResult.taskGates,
+                run_gate: schedulerResult.runGate,
+                status: schedulerResult.state.status,
+            },
+            sharedContext: [
+                "# Shared Context",
+                "",
+                `Run ${input.runId} finished with status: ${schedulerResult.state.status}.`,
+                `Recommendation: ${schedulerResult.runGate.pass ? "proceed to /iosm for measurable optimization" : "resolve failed gates before /iosm"}.`,
+            ].join("\n"),
+        });
+        this.showCommandTextBlock("Swarm Run", [
+            `run_id: ${input.runId}`,
+            `status: ${schedulerResult.state.status}`,
+            `tasks: ${doneCount}/${total} done · ${errorCount} error · ${blockedCount} blocked`,
+            `budget_usd: ${schedulerResult.state.budget.spentUsd.toFixed(2)}${input.meta.budgetUsd ? `/${input.meta.budgetUsd.toFixed(2)}` : ""}`,
+            `watch: /swarm watch ${input.runId}`,
+            `resume: /swarm resume ${input.runId}`,
+        ].join("\n"));
+    }
+    async runSwarmFromTask(task, options) {
+        const contract = await this.ensureSwarmEffectiveContract(task);
+        if (!contract)
+            return;
+        const indexInfo = this.ensureSwarmProjectIndex(task);
+        if (indexInfo.rebuilt) {
+            this.showStatus(`Swarm project index ready (${indexInfo.scaleMode}).`);
+        }
+        const semanticStatus = await this.maybeWarnSwarmSemantic(indexInfo.scaleMode);
+        const plan = buildSwarmPlanFromTask({
+            request: task,
+            contract,
+            index: indexInfo.index,
+        });
+        const runId = `swarm_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const maxParallel = Math.max(1, Math.min(20, options.maxParallel ?? 3));
+        const meta = this.buildSwarmRunMeta({
+            runId,
+            source: "plain",
+            request: task,
+            contract,
+            repoScaleMode: indexInfo.scaleMode,
+            semanticStatus,
+            maxParallel,
+            budgetUsd: options.budgetUsd,
+        });
+        await this.executeSwarmRun({
+            runId,
+            plan,
+            meta,
+            contract,
+            budgetUsd: options.budgetUsd,
+            projectIndex: indexInfo.index,
+            enableIncrementalIndex: indexInfo.scaleMode !== "small",
+        });
+    }
+    async runSwarmFromSingular(input) {
+        const analysis = this.loadSingularAnalysisByRunId(input.runId);
+        if (!analysis) {
+            this.showWarning(`Singular run not found: ${input.runId}`);
+            return;
+        }
+        const option = analysis.options.find((item) => item.id === String(input.option));
+        if (!option) {
+            this.showWarning(`Option ${input.option} not found in singular run ${input.runId}.`);
+            return;
+        }
+        const contract = await this.ensureSwarmEffectiveContract(analysis.request);
+        if (!contract)
+            return;
+        const indexInfo = this.ensureSwarmProjectIndex(`${analysis.request} ${option.title}`);
+        const semanticStatus = await this.maybeWarnSwarmSemantic(indexInfo.scaleMode);
+        const plan = buildSwarmPlanFromSingular({
+            analysis,
+            option,
+            contract,
+            index: indexInfo.index,
+        });
+        const runId = `swarm_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const maxParallel = Math.max(1, Math.min(20, input.maxParallel ?? 3));
+        const meta = this.buildSwarmRunMeta({
+            runId,
+            source: "singular",
+            request: analysis.request,
+            contract,
+            repoScaleMode: indexInfo.scaleMode,
+            semanticStatus,
+            maxParallel,
+            budgetUsd: input.budgetUsd,
+            linkedSingularRunId: analysis.runId,
+            linkedSingularOption: option.id,
+        });
+        await this.executeSwarmRun({
+            runId,
+            plan,
+            meta,
+            contract,
+            budgetUsd: input.budgetUsd,
+            projectIndex: indexInfo.index,
+            enableIncrementalIndex: indexInfo.scaleMode !== "small",
+        });
+    }
+    loadSwarmRunBundle(runId) {
+        const store = new SwarmStateStore(this.sessionManager.getCwd(), runId);
+        const meta = store.loadMeta();
+        const plan = store.loadPlan();
+        const state = store.loadState();
+        if (!meta || !plan || !state)
+            return undefined;
+        return { meta, plan, state };
+    }
+    computeSwarmCriticalPathLength(plan) {
+        const byId = new Map(plan.tasks.map((task) => [task.id, task]));
+        const memo = new Map();
+        const visiting = new Set();
+        const visit = (taskId) => {
+            if (memo.has(taskId))
+                return memo.get(taskId);
+            if (visiting.has(taskId))
+                return 1;
+            visiting.add(taskId);
+            const task = byId.get(taskId);
+            if (!task)
+                return 1;
+            const depMax = task.depends_on.reduce((maxValue, depId) => Math.max(maxValue, visit(depId)), 0);
+            const value = depMax + 1;
+            memo.set(taskId, value);
+            visiting.delete(taskId);
+            return value;
+        };
+        let best = 0;
+        for (const task of plan.tasks) {
+            best = Math.max(best, visit(task.id));
+        }
+        return best;
+    }
+    computeSwarmDependentCounts(plan) {
+        const counts = new Map();
+        for (const task of plan.tasks) {
+            for (const dep of task.depends_on) {
+                counts.set(dep, (counts.get(dep) ?? 0) + 1);
+            }
+        }
+        return counts;
+    }
+    formatSwarmWatch(meta, plan, state) {
+        const tasks = Object.values(state.tasks);
+        const done = tasks.filter((task) => task.status === "done").length;
+        const running = tasks.filter((task) => task.status === "running").length;
+        const blocked = tasks.filter((task) => task.status === "blocked").length;
+        const errors = tasks.filter((task) => task.status === "error").length;
+        const pending = tasks.filter((task) => task.status === "pending" || task.status === "ready").length;
+        const total = tasks.length;
+        const remaining = Math.max(0, total - done);
+        const throughputPerTick = done > 0 && state.tick > 0 ? done / state.tick : 0;
+        const etaTicks = throughputPerTick > 0 ? Math.ceil(remaining / throughputPerTick) : undefined;
+        const criticalPath = this.computeSwarmCriticalPathLength(plan);
+        const speedupPotential = criticalPath > 0 ? total / criticalPath : 1;
+        const dependentCounts = this.computeSwarmDependentCounts(plan);
+        const bottlenecks = [...dependentCounts.entries()]
+            .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+            .slice(0, 3);
+        const lines = [
+            `run_id: ${meta.runId}`,
+            `status: ${state.status}`,
+            `source: ${meta.source}`,
+            `request: ${meta.request}`,
+            "consistency_model: Scopes -> Touches -> Locks -> Gates -> Done",
+            `progress: done=${done}/${tasks.length} running=${running} pending=${pending} blocked=${blocked} error=${errors}`,
+            `budget_usd: ${state.budget.spentUsd.toFixed(2)}${meta.budgetUsd ? `/${meta.budgetUsd.toFixed(2)}` : ""} warned80=${state.budget.warned80 ? "yes" : "no"}`,
+            `tick: ${state.tick} no_progress_ticks: ${state.noProgressTicks}`,
+            `eta_ticks: ${etaTicks ?? "unknown"} throughput_per_tick=${throughputPerTick > 0 ? throughputPerTick.toFixed(2) : "0.00"}`,
+            `critical_path: ${criticalPath} theoretical_speedup=${speedupPotential.toFixed(2)}x`,
+            `repo_scale: ${meta.repoScaleMode} semantic: ${meta.semanticStatus ?? "unknown"}`,
+            "",
+            ...(bottlenecks.length > 0
+                ? ["bottlenecks:", ...bottlenecks.map(([taskId, dependents]) => `- ${taskId}: unlocks ${dependents} downstream task(s)`), ""]
+                : []),
+            "tasks:",
+            ...plan.tasks.map((task) => {
+                const runtime = state.tasks[task.id];
+                if (!runtime)
+                    return `- ${task.id}: missing runtime state`;
+                return `- ${task.id}: ${runtime.status} attempts=${runtime.attempts} touches=${runtime.touches.slice(0, 3).join(",") || "-"}`;
+            }),
+        ];
+        if (Object.keys(state.locks).length > 0) {
+            lines.push("", "locks:");
+            for (const [taskId, touches] of Object.entries(state.locks)) {
+                lines.push(`- ${taskId}: ${touches.join(", ")}`);
+            }
+        }
+        return lines.join("\n");
+    }
+    async runSwarmResume(runId) {
+        const bundle = this.loadSwarmRunBundle(runId);
+        if (!bundle) {
+            this.showWarning(`Swarm run not found or incomplete: ${runId}`);
+            return;
+        }
+        if (bundle.state.status === "completed") {
+            this.showStatus(`Swarm run ${runId} is already completed.`);
+            return;
+        }
+        bundle.state.status = "running";
+        bundle.state.updatedAt = new Date().toISOString();
+        await this.executeSwarmRun({
+            runId,
+            plan: bundle.plan,
+            meta: bundle.meta,
+            contract: bundle.meta.contract,
+            budgetUsd: bundle.meta.budgetUsd,
+            resumeState: bundle.state,
+            projectIndex: bundle.meta.repoScaleMode === "small" ? undefined : loadProjectIndex(this.sessionManager.getCwd()),
+            enableIncrementalIndex: bundle.meta.repoScaleMode !== "small",
+        });
+    }
+    async runSwarmRetry(runId, taskId, resetBrief) {
+        const bundle = this.loadSwarmRunBundle(runId);
+        if (!bundle) {
+            this.showWarning(`Swarm run not found or incomplete: ${runId}`);
+            return;
+        }
+        const target = bundle.state.tasks[taskId];
+        if (!target) {
+            this.showWarning(`Task ${taskId} not found in run ${runId}.`);
+            return;
+        }
+        if (resetBrief) {
+            const existingPlan = bundle.plan.tasks.find((task) => task.id === taskId);
+            const edited = await this.showExtensionInput(`/swarm retry: update brief for ${taskId}`, existingPlan?.brief ?? target.id);
+            if (edited === undefined) {
+                this.showStatus("Swarm retry cancelled.");
+                return;
+            }
+            if (existingPlan) {
+                existingPlan.brief = edited.trim() || existingPlan.brief;
+            }
+        }
+        target.status = "ready";
+        target.lastError = undefined;
+        target.completedAt = undefined;
+        bundle.state.retries[taskId] = 0;
+        bundle.state.status = "running";
+        bundle.state.updatedAt = new Date().toISOString();
+        const store = new SwarmStateStore(this.sessionManager.getCwd(), runId);
+        store.savePlan(bundle.plan);
+        store.saveState(bundle.state);
+        store.appendEvent({
+            type: "task_retry",
+            timestamp: new Date().toISOString(),
+            runId,
+            taskId,
+            message: resetBrief ? "manual retry with reset brief" : "manual retry",
+        });
+        await this.executeSwarmRun({
+            runId,
+            plan: bundle.plan,
+            meta: bundle.meta,
+            contract: bundle.meta.contract,
+            budgetUsd: bundle.meta.budgetUsd,
+            resumeState: bundle.state,
+            projectIndex: bundle.meta.repoScaleMode === "small" ? undefined : loadProjectIndex(this.sessionManager.getCwd()),
+            enableIncrementalIndex: bundle.meta.repoScaleMode !== "small",
+        });
+    }
+    async handleSwarmCommand(text) {
+        if (this.session.isStreaming) {
+            this.showWarning("Cannot run /swarm while the agent is processing another request.");
+            return;
+        }
+        if (this.session.isCompacting) {
+            this.showWarning("Cannot run /swarm while compaction is running.");
+            return;
+        }
+        const parsed = this.parseSwarmCommand(text);
+        if (!parsed)
+            return;
+        if (parsed.subcommand === "help") {
+            this.showCommandTextBlock("Swarm Help", this.getSwarmHelpText());
+            return;
+        }
+        if (parsed.subcommand === "watch") {
+            let runId = parsed.runId;
+            if (!runId) {
+                const runs = SwarmStateStore.listRuns(this.sessionManager.getCwd(), 20);
+                if (runs.length === 0) {
+                    this.showStatus("No swarm runs found.");
+                    return;
+                }
+                runId = runs[0].runId;
+            }
+            const bundle = this.loadSwarmRunBundle(runId);
+            if (!bundle) {
+                this.showWarning(`Swarm run not found or incomplete: ${runId}`);
+                return;
+            }
+            this.showCommandTextBlock("Swarm Watch", this.formatSwarmWatch(bundle.meta, bundle.plan, bundle.state));
+            return;
+        }
+        if (parsed.subcommand === "resume") {
+            await this.runSwarmResume(parsed.runId);
+            return;
+        }
+        if (parsed.subcommand === "retry") {
+            await this.runSwarmRetry(parsed.runId, parsed.taskId, parsed.resetBrief);
+            return;
+        }
+        if (parsed.subcommand === "run") {
+            await this.runSwarmFromTask(parsed.task, {
+                maxParallel: parsed.maxParallel,
+                budgetUsd: parsed.budgetUsd,
+            });
+            return;
+        }
+        if (parsed.subcommand === "from-singular") {
+            await this.runSwarmFromSingular({
+                runId: parsed.runId,
+                option: parsed.option,
+                maxParallel: parsed.maxParallel,
+                budgetUsd: parsed.budgetUsd,
+            });
+        }
+    }
     parseOrchestrateSlashCommand(text) {
         const args = this.parseSlashArgs(text).slice(1);
         let mode;
@@ -8590,10 +10121,20 @@ export class InteractiveMode {
             this.showWarning("Cannot run /orchestrate while compaction is running.");
             return;
         }
+        const rawArgs = this.parseSlashArgs(text).slice(1);
+        if (rawArgs.includes("--swarm")) {
+            this.showWarning("`/orchestrate --swarm` was removed to avoid ambiguity. Use `/swarm` commands directly.");
+            this.showCommandTextBlock("Swarm Usage", this.getSwarmHelpText());
+            return;
+        }
         const parsed = this.parseOrchestrateSlashCommand(text);
         if (!parsed) {
             return;
         }
+        const swarmRecommendation = this.buildSwarmRecommendationFromOrchestrate(parsed);
+        if (swarmRecommendation.recommend) {
+            this.showWarning(`This task looks complex/risky for legacy /orchestrate (${swarmRecommendation.reasons.join("; ")}). Consider ${swarmRecommendation.command}.`);
+        }
         const currentCwd = this.sessionManager.getCwd();
         const assignments = [];
         const assignmentRecords = [];
@@ -8637,6 +10178,7 @@ export class InteractiveMode {
             "- use task tool for every agent assignment",
             "- for parallel mode, emit all independent task calls in one assistant response",
             "- in parallel mode, use parallel tool-call style (<use_parallel_tool_calls>)",
+            "- when assignment lines include depends_on, still emit one task call per assignment; runtime enforces dependency gating",
             "- keep required orchestration task calls in foreground; do not set background=true unless user explicitly requested detached async runs",
             "- do not poll .iosm/subagents/background via bash/read during orchestration; wait for task results and then synthesize",
             "- include run_id and task_id from each assignment in the task tool arguments",
@@ -10746,6 +12288,7 @@ The agent will automatically receive IOSM context on every turn.`;
         return result;
     }
     stop() {
+        this.clearSubagentElapsedTimer();
         if (this.loadingAnimation) {
             this.loadingAnimation.stop();
             this.loadingAnimation = undefined;