iosm-cli 0.1.3 → 0.2.1

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

@@ -6,7 +6,7 @@ import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { CombinedAutocompleteProvider, Container, fuzzyFilter, Loader, Markdown, matchesKey, ProcessTerminal, Spacer, Text, TruncatedText, TUI, visibleWidth, } from "@mariozechner/pi-tui";
+import { CombinedAutocompleteProvider, Container, fuzzyFilter, Loader, Markdown, matchesKey, ProcessTerminal, Spacer, Text, truncateToWidth, TruncatedText, TUI, visibleWidth, } from "@mariozechner/pi-tui";
 import { spawn, spawnSync } from "child_process";
 import { APP_NAME, CHANGELOG_URL, ENV_SESSION_TRACE, ENV_OFFLINE, ENV_SKIP_VERSION_CHECK, getAgentDir, getAuthPath, getDebugLogPath, getModelsPath, getSessionTracePath, getShareViewerUrl, getUpdateInstruction, isSessionTraceEnabled, PACKAGE_NAME, VERSION, } from "../../config.js";
 import { AuthStorage } from "../../core/auth-storage.js";
@@ -19,10 +19,14 @@ import { ModelRegistry } from "../../core/model-registry.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 { getDefaultSemanticSearchConfig, getSemanticConfigPath, getSemanticIndexDir, isLikelyEmbeddingModelId, listOllamaLocalModels, listOpenRouterEmbeddingModels, loadMergedSemanticConfig, SemanticConfigMissingError, SemanticRebuildRequiredError, SemanticSearchRuntime, upsertScopedSemanticSearchConfig, } from "../../core/semantic/index.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";
@@ -71,6 +75,94 @@ function isExpandable(obj) {
 }
 const IOSM_PROFILE_ONLY_COMMANDS = new Set(["iosm", "cycle-list", "cycle-plan", "cycle-status", "cycle-report"]);
 const CHECKPOINT_LABEL_PREFIX = "checkpoint:";
+const INTERRUPT_ABORT_TIMEOUT_MS = 8_000;
+const CONTRACT_FIELD_DEFINITIONS = [
+    { key: "goal", kind: "text", placeholder: "Ship X with measurable impact", help: "Single primary objective." },
+    {
+        key: "scope_include",
+        kind: "list",
+        placeholder: "auth/*",
+        help: "What is explicitly in scope.",
+    },
+    {
+        key: "scope_exclude",
+        kind: "list",
+        placeholder: "billing/*",
+        help: "What must remain untouched for this change.",
+    },
+    {
+        key: "constraints",
+        kind: "list",
+        placeholder: "no breaking API changes",
+        help: "Hard constraints that cannot be violated.",
+    },
+    {
+        key: "quality_gates",
+        kind: "list",
+        placeholder: "tests pass",
+        help: "Objective quality checks before merge.",
+    },
+    {
+        key: "definition_of_done",
+        kind: "list",
+        placeholder: "docs updated",
+        help: "Completion criteria.",
+    },
+    {
+        key: "assumptions",
+        kind: "list",
+        placeholder: "API v2 stays backward compatible",
+        help: "Assumptions the plan depends on.",
+    },
+    {
+        key: "non_goals",
+        kind: "list",
+        placeholder: "no redesign in this cycle",
+        help: "Intentional exclusions.",
+    },
+    {
+        key: "risks",
+        kind: "list",
+        placeholder: "migration may affect legacy clients",
+        help: "Known delivery risks.",
+    },
+    {
+        key: "deliverables",
+        kind: "list",
+        placeholder: "CLI command + tests + docs",
+        help: "Expected artifacts.",
+    },
+    {
+        key: "success_metrics",
+        kind: "list",
+        placeholder: "p95 latency < 250ms",
+        help: "Measurable target outcomes.",
+    },
+    {
+        key: "stakeholders",
+        kind: "list",
+        placeholder: "backend team, QA",
+        help: "Who should review/accept the result.",
+    },
+    {
+        key: "owner",
+        kind: "text",
+        placeholder: "team/platform",
+        help: "Owner accountable for delivery.",
+    },
+    {
+        key: "timebox",
+        kind: "text",
+        placeholder: "this sprint",
+        help: "Deadline or delivery window.",
+    },
+    {
+        key: "notes",
+        kind: "text",
+        placeholder: "additional context",
+        help: "Free-form context for this contract.",
+    },
+];
 const DOCTOR_CLI_TOOL_SPECS = [
     {
         tool: "rg",
@@ -265,11 +357,14 @@ export class InteractiveMode {
         this.pendingWorkingMessage = undefined;
         this.defaultWorkingMessage = "Working...";
         this.activeProfileName = "full";
+        this.profilePromptSuffix = undefined;
         this.permissionMode = "ask";
         this.permissionAllowRules = [];
         this.permissionDenyRules = [];
         this.permissionPromptLock = Promise.resolve();
         this.sessionAllowedToolSignatures = new Set();
+        this.singularLastEffectiveContract = {};
+        this.swarmActiveRunId = undefined;
         this.lastSigintTime = 0;
         this.lastEscapeTime = 0;
         this.changelogMarkdown = undefined;
@@ -283,6 +378,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;
@@ -310,6 +406,7 @@ export class InteractiveMode {
         // IOSM automation state
         this.iosmAutomationRun = undefined;
         this.iosmVerificationSession = undefined;
+        this.singularAnalysisSession = undefined;
         // Extension UI state
         this.extensionSelector = undefined;
         this.extensionInput = undefined;
@@ -354,14 +451,19 @@ export class InteractiveMode {
         this.footerDataProvider = new FooterDataProvider();
         this.footer = new FooterComponent(session, this.footerDataProvider);
         this.footer.setAutoCompactEnabled(session.autoCompactionEnabled);
-        this.activeProfileName = getAgentProfile(options.profile).name;
+        const profile = getAgentProfile(options.profile);
+        this.activeProfileName = profile.name;
+        this.profilePromptSuffix = profile.systemPromptAppend || undefined;
         this.mcpRuntime = options.mcpRuntime;
+        this.contractService = new ContractService({ cwd: this.sessionManager.getCwd() });
+        this.singularService = new SingularService({ cwd: this.sessionManager.getCwd() });
         // Apply plan mode and profile badges immediately if set
         if (options.planMode || this.activeProfileName === "plan") {
             this.footer.setPlanMode(true);
         }
         this.footer.setActiveProfile(this.activeProfileName);
         this.session.setIosmAutopilotEnabled(this.activeProfileName === "iosm");
+        this.syncRuntimePromptSuffix();
         this.permissionMode = this.settingsManager.getPermissionMode();
         this.permissionAllowRules = this.settingsManager.getPermissionAllowRules();
         this.permissionDenyRules = this.settingsManager.getPermissionDenyRules();
@@ -373,6 +475,44 @@ export class InteractiveMode {
         setRegisteredThemes(this.session.resourceLoader.getThemes().themes);
         initTheme(this.settingsManager.getTheme(), true);
     }
+    syncRuntimePromptSuffix() {
+        let contractSuffix;
+        try {
+            contractSuffix = this.contractService.buildPromptContext();
+        }
+        catch {
+            contractSuffix = undefined;
+        }
+        const suffix = [this.profilePromptSuffix, contractSuffix]
+            .map((entry) => entry?.trim())
+            .filter((entry) => !!entry && entry.length > 0)
+            .join("\n\n");
+        this.session.setSystemPromptSuffix(suffix || undefined);
+    }
+    getContractStateSafe() {
+        try {
+            return this.contractService.getState();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.showWarning(`Contract load failed: ${message}`);
+            return undefined;
+        }
+    }
+    getProfileToolNames(profileName) {
+        const profile = getAgentProfile(profileName);
+        const availableTools = new Set(this.session.getAllTools().map((tool) => tool.name));
+        const nextActiveTools = [...profile.tools];
+        if (availableTools.has("task"))
+            nextActiveTools.push("task");
+        if (availableTools.has("todo_write"))
+            nextActiveTools.push("todo_write");
+        if (availableTools.has("todo_read"))
+            nextActiveTools.push("todo_read");
+        if (availableTools.has("ask_user"))
+            nextActiveTools.push("ask_user");
+        return [...new Set(nextActiveTools)];
+    }
     getToolPermissionSignature(request) {
         const summary = request.summary.trim().replace(/\s+/g, " ");
         return `${request.toolName}:${summary}`;
@@ -834,6 +974,72 @@ export class InteractiveMode {
         }
         return null;
     }
+    getContractArgumentCompletions(prefix) {
+        const subcommands = ["ui", "show", "edit", "clear", "help"];
+        const scopeFlags = ["--scope"];
+        const scopeValues = ["project", "session"];
+        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, ...scopeFlags]
+                .filter((item) => item.includes(query))
+                .map((item) => ({ value: item, label: item }));
+        }
+        const scopeIndex = tokens.findIndex((token) => token === "--scope");
+        if (scopeIndex >= 0) {
+            const currentValue = tokens[scopeIndex + 1];
+            if (!currentValue) {
+                return scopeValues.map((value) => ({ value, label: value }));
+            }
+            return scopeValues
+                .filter((value) => value.startsWith(currentValue))
+                .map((value) => ({ value, label: value }));
+        }
+        const query = hasTrailingSpace ? "" : (tokens[tokens.length - 1] ?? "");
+        if (query.startsWith("--")) {
+            return scopeFlags.filter((flag) => flag.includes(query)).map((flag) => ({ value: flag, label: flag }));
+        }
+        return null;
+    }
+    getSingularArgumentCompletions(prefix) {
+        const subcommands = ["help", "last"];
+        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 }));
+        }
+        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));
@@ -879,6 +1085,18 @@ export class InteractiveMode {
         if (semanticCommand) {
             semanticCommand.getArgumentCompletions = (prefix) => this.getSemanticArgumentCompletions(prefix);
         }
+        const contractCommand = slashCommands.find((command) => command.name === "contract");
+        if (contractCommand) {
+            contractCommand.getArgumentCompletions = (prefix) => this.getContractArgumentCompletions(prefix);
+        }
+        const singularCommand = slashCommands.find((command) => command.name === "singular");
+        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,
@@ -1132,7 +1350,7 @@ export class InteractiveMode {
         }
         // Commands and keys
         const commandsLine = `${pad}${theme.fg("dim", "cmds")}  ` +
-            ["model", "login", "mcp", "semantic", "memory", "doctor", "new"]
+            ["model", "login", "contract", "singular", "semantic", "memory", "new"]
                 .map((c) => theme.fg("accent", `/${c}`))
                 .join(theme.fg("dim", "  "));
         const keysLine = `${pad}${theme.fg("dim", "keys")}  ` +
@@ -1562,8 +1780,10 @@ export class InteractiveMode {
                     const names = extensionPaths.map((p) => theme.fg("dim", this.formatDisplayPath(p)));
                     lines.push(`  ${theme.fg("muted", "ext")}  ${names.join(theme.fg("dim", ", "))}`);
                 }
+                const resourceWidth = Math.max(24, this.ui?.terminal?.columns ?? 120);
+                const safeLines = lines.map((line) => visibleWidth(line) > resourceWidth ? truncateToWidth(line, resourceWidth, "") : line);
                 this.chatContainer.addChild(new Spacer(1));
-                this.chatContainer.addChild(new Text(lines.join("\n"), 0, 0));
+                this.chatContainer.addChild(new Text(safeLines.join("\n"), 0, 0));
             }
         }
         if (showDiagnostics) {
@@ -2287,6 +2507,7 @@ export class InteractiveMode {
                 this.session.isRetrying ||
                 this.iosmAutomationRun !== undefined ||
                 this.iosmVerificationSession !== undefined ||
+                this.singularAnalysisSession !== undefined ||
                 queuedMessages.steering.length > 0 ||
                 queuedMessages.followUp.length > 0 ||
                 queuedMeta.length > 0;
@@ -2394,6 +2615,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);
@@ -2454,6 +2680,16 @@ export class InteractiveMode {
                 await this.handleSemanticCommand(text);
                 return;
             }
+            if (text === "/contract" || text.startsWith("/contract ")) {
+                this.editor.setText("");
+                await this.handleContractCommand(text);
+                return;
+            }
+            if (text === "/singular" || text.startsWith("/singular ")) {
+                this.editor.setText("");
+                await this.handleSingularCommand(text);
+                return;
+            }
             if (text === "/settings") {
                 this.showSettingsSelector();
                 this.editor.setText("");
@@ -2642,6 +2878,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);
@@ -2823,6 +3112,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)) {
@@ -2908,29 +3198,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;
                 }
@@ -2994,6 +3262,7 @@ export class InteractiveMode {
                         this.pendingTools.delete(event.toolCallId);
                     }
                     this.subagentComponents.delete(event.toolCallId);
+                    this.stopSubagentElapsedTimerIfIdle();
                     this.ui.requestRender();
                     break;
                 }
@@ -3018,6 +3287,7 @@ export class InteractiveMode {
                 }
                 this.pendingTools.clear();
                 this.subagentComponents.clear();
+                this.clearSubagentElapsedTimer();
                 await this.checkShutdownRequested();
                 this.ui.requestRender();
                 break;
@@ -3562,19 +3832,11 @@ export class InteractiveMode {
     }
     applyProfile(profileName) {
         const profile = getAgentProfile(profileName);
-        const availableTools = new Set(this.session.getAllTools().map((tool) => tool.name));
-        const nextActiveTools = [...profile.tools];
-        if (availableTools.has("task"))
-            nextActiveTools.push("task");
-        if (availableTools.has("todo_write"))
-            nextActiveTools.push("todo_write");
-        if (availableTools.has("todo_read"))
-            nextActiveTools.push("todo_read");
-        if (availableTools.has("ask_user"))
-            nextActiveTools.push("ask_user");
-        this.session.setActiveToolsByName([...new Set(nextActiveTools)]);
+        const nextActiveTools = this.getProfileToolNames(profile.name);
+        this.session.setActiveToolsByName(nextActiveTools);
         this.session.setThinkingLevel(profile.thinkingLevel);
-        this.session.setSystemPromptSuffix(profile.systemPromptAppend || undefined);
+        this.profilePromptSuffix = profile.systemPromptAppend || undefined;
+        this.syncRuntimePromptSuffix();
         this.session.setIosmAutopilotEnabled(profile.name === "iosm");
         this.activeProfileName = profile.name;
         this.footer.setActiveProfile(profile.name);
@@ -3819,6 +4081,8 @@ export class InteractiveMode {
         const hasAutomationWork = this.iosmAutomationRun !== undefined;
         const verificationSession = this.iosmVerificationSession;
         const hasVerificationWork = verificationSession !== undefined;
+        const singularSession = this.singularAnalysisSession;
+        const hasSingularWork = singularSession !== undefined;
         const hasMainStreaming = this.session.isStreaming;
         const hasRetryWork = this.session.isRetrying;
         const hasCompactionWork = this.session.isCompacting;
@@ -3826,6 +4090,7 @@ export class InteractiveMode {
         if (!hasPendingQueuedMessages &&
             !hasAutomationWork &&
             !hasVerificationWork &&
+            !hasSingularWork &&
             !hasMainStreaming &&
             !hasRetryWork &&
             !hasCompactionWork &&
@@ -3858,7 +4123,9 @@ export class InteractiveMode {
             ? "Stopping IOSM automation..."
             : hasVerificationWork
                 ? "Stopping IOSM verification..."
-                : "Stopping current run...");
+                : hasSingularWork
+                    ? "Stopping /singular analysis..."
+                    : "Stopping current run...");
         const abortPromises = [];
         if (hasMainStreaming) {
             abortPromises.push(this.session.abort());
@@ -3866,8 +4133,30 @@ export class InteractiveMode {
         if (verificationSession) {
             abortPromises.push(verificationSession.abort());
         }
+        if (singularSession) {
+            abortPromises.push(singularSession.abort());
+        }
         if (abortPromises.length > 0) {
-            await Promise.allSettled(abortPromises);
+            const settleWithTimeout = (promise) => new Promise((resolve) => {
+                let finished = false;
+                const timeout = setTimeout(() => {
+                    if (finished)
+                        return;
+                    finished = true;
+                    resolve("timeout");
+                }, INTERRUPT_ABORT_TIMEOUT_MS);
+                promise.finally(() => {
+                    if (finished)
+                        return;
+                    finished = true;
+                    clearTimeout(timeout);
+                    resolve("done");
+                });
+            });
+            const settled = await Promise.all(abortPromises.map((promise) => settleWithTimeout(promise)));
+            if (settled.includes("timeout")) {
+                this.showWarning(`Abort is taking longer than ${Math.round(INTERRUPT_ABORT_TIMEOUT_MS / 1000)}s. Try interrupt again if the run is still active.`);
+            }
         }
         return true;
     }
@@ -5018,6 +5307,7 @@ export class InteractiveMode {
         });
     }
     async handleResumeSession(sessionPath) {
+        this.contractService.clear("session");
         // Stop loading animation
         if (this.loadingAnimation) {
             this.loadingAnimation.stop();
@@ -5035,6 +5325,7 @@ export class InteractiveMode {
         // Clear and re-render the chat
         this.chatContainer.clear();
         this.renderInitialMessages();
+        this.syncRuntimePromptSuffix();
         this.refreshBuiltInHeader();
         this.showStatus("Resumed session");
     }
@@ -5579,7 +5870,7 @@ export class InteractiveMode {
             authStorage: this.session.modelRegistry.authStorage,
         });
     }
-    parseSemanticScopeOptions(args) {
+    parseSemanticScopeOptions(args, usage = "Usage: /semantic setup --scope <user|project>") {
         let scope;
         const rest = [];
         for (let index = 0; index < args.length; index++) {
@@ -5588,7 +5879,7 @@ export class InteractiveMode {
             if (normalized === "--scope") {
                 const value = (args[index + 1] ?? "").toLowerCase();
                 if (!value) {
-                    return { scope, rest, error: "Usage: /semantic setup --scope <user|project>" };
+                    return { scope, rest, error: usage };
                 }
                 if (value !== "user" && value !== "project") {
                     return { scope, rest, error: `Invalid semantic scope "${value}". Use user or project.` };
@@ -5628,6 +5919,7 @@ export class InteractiveMode {
         const lines = [
             `configured: ${status.configured ? "yes" : "no"}`,
             `enabled: ${status.enabled ? "yes" : "no"}`,
+            `auto_index: ${status.autoIndex ? "on" : "off"}`,
             `indexed: ${status.indexed ? "yes" : "no"}`,
             `stale: ${status.stale ? `yes${status.staleReason ? ` (${status.staleReason})` : ""}` : "no"}`,
         ];
@@ -5912,10 +6204,42 @@ export class InteractiveMode {
             `scope: ${scope}`,
             `provider: ${this.getSemanticSetupProviderLabel(providerType)}`,
             `model: ${nextProvider.model}`,
+            `auto_index: ${nextConfig.autoIndex ? "on" : "off"}`,
             `config: ${savedPath}`,
             `index_dir: ${getSemanticIndexDir(cwd, agentDir)}`,
         ].join("\n"));
     }
+    resolveSemanticAutoIndexWriteScope(cwd, agentDir) {
+        const project = readScopedSemanticConfig("project", cwd, agentDir);
+        if (!project.error && project.file.semanticSearch) {
+            return "project";
+        }
+        return "user";
+    }
+    async updateSemanticAutoIndexSetting(options) {
+        const cwd = this.sessionManager.getCwd();
+        const agentDir = getAgentDir();
+        const merged = loadMergedSemanticConfig(cwd, agentDir);
+        if (!merged.config) {
+            this.showWarning("Semantic search is not configured. Run /semantic setup first.");
+            return;
+        }
+        const scope = options?.scope ?? this.resolveSemanticAutoIndexWriteScope(cwd, agentDir);
+        const value = options?.value ?? !merged.config.autoIndex;
+        const nextConfig = {
+            ...merged.config,
+            autoIndex: value,
+        };
+        const savedPath = upsertScopedSemanticSearchConfig(scope, nextConfig, cwd, agentDir);
+        const effective = await this.createSemanticRuntime().status().catch(() => undefined);
+        this.showStatus(`Semantic auto-index ${value ? "enabled" : "disabled"} (${scope}).`);
+        this.showCommandTextBlock("Semantic Auto-Index", [
+            `scope: ${scope}`,
+            `saved: ${value ? "on" : "off"}`,
+            `effective: ${effective ? (effective.autoIndex ? "on" : "off") : "unknown"}`,
+            `config: ${savedPath}`,
+        ].join("\n"));
+    }
     async runSemanticInteractiveMenu() {
         while (true) {
             let status;
@@ -5926,7 +6250,7 @@ export class InteractiveMode {
                 this.reportSemanticError(error, "status");
             }
             const summary = status
-                ? `configured=${status.configured ? "yes" : "no"} indexed=${status.indexed ? "yes" : "no"} stale=${status.stale ? "yes" : "no"}`
+                ? `configured=${status.configured ? "yes" : "no"} auto_index=${status.autoIndex ? "on" : "off"} indexed=${status.indexed ? "yes" : "no"} stale=${status.stale ? "yes" : "no"}`
                 : "status unavailable";
             const selected = await this.showExtensionSelector(`/semantic manager\n${summary}`, [
                 "Configure provider/model",
@@ -5934,6 +6258,7 @@ export class InteractiveMode {
                 "Index now",
                 "Rebuild index",
                 "Query index",
+                `Automatic indexing: ${status?.autoIndex ? "on" : "off"}`,
                 "Show config/index paths",
                 "Close",
             ]);
@@ -6007,6 +6332,10 @@ export class InteractiveMode {
                 }
                 continue;
             }
+            if (selected.startsWith("Automatic indexing:")) {
+                await this.updateSemanticAutoIndexSetting();
+                continue;
+            }
             if (selected === "Show config/index paths") {
                 const runtime = this.createSemanticRuntime();
                 const cwd = this.sessionManager.getCwd();
@@ -6036,6 +6365,11 @@ export class InteractiveMode {
             ].join("\n"));
             return;
         }
+        if (error instanceof SemanticIndexRequiredError) {
+            this.showWarning(error.message);
+            this.showWarning("Run /semantic index (or enable automatic indexing in /semantic).");
+            return;
+        }
         if (error instanceof SemanticRebuildRequiredError) {
             this.showWarning(error.message);
             this.showWarning("Run /semantic rebuild.");
@@ -6058,6 +6392,7 @@ export class InteractiveMode {
                 "  /semantic",
                 "  /semantic ui",
                 "  /semantic setup [--scope user|project]",
+                "  /semantic auto-index [on|off] [--scope user|project]",
                 "  /semantic status",
                 "  /semantic index",
                 "  /semantic rebuild",
@@ -6079,6 +6414,34 @@ export class InteractiveMode {
             await this.runSemanticSetupWizard(parsedScope.scope);
             return;
         }
+        if (subcommand === "auto-index" || subcommand === "autoindex") {
+            const parsedScope = this.parseSemanticScopeOptions(rest, "Usage: /semantic auto-index [on|off] [--scope user|project]");
+            if (parsedScope.error) {
+                this.showWarning(parsedScope.error);
+                return;
+            }
+            let value;
+            if (parsedScope.rest.length > 1) {
+                this.showWarning("Usage: /semantic auto-index [on|off] [--scope user|project]");
+                return;
+            }
+            if (parsedScope.rest.length === 1) {
+                const mode = parsedScope.rest[0]?.toLowerCase();
+                if (mode === "on" || mode === "enable" || mode === "enabled")
+                    value = true;
+                else if (mode === "off" || mode === "disable" || mode === "disabled")
+                    value = false;
+                else {
+                    this.showWarning(`Unknown auto-index mode "${parsedScope.rest[0]}". Use on|off.`);
+                    return;
+                }
+            }
+            await this.updateSemanticAutoIndexSetting({
+                scope: parsedScope.scope,
+                value,
+            });
+            return;
+        }
         if (subcommand === "status") {
             try {
                 const result = await this.runWithExtensionLoader("Checking semantic index status...", async () => this.createSemanticRuntime().status());
@@ -6133,979 +6496,3213 @@ export class InteractiveMode {
         }
         this.showWarning(`Unknown /semantic subcommand "${subcommand}". Use /semantic help.`);
     }
-    parseCheckpointNameFromLabel(label) {
-        if (!label)
-            return undefined;
-        if (!label.startsWith(CHECKPOINT_LABEL_PREFIX))
-            return undefined;
-        const name = label.slice(CHECKPOINT_LABEL_PREFIX.length).trim();
-        return name.length > 0 ? name : undefined;
+    parseContractScopeOptions(args, usage = "Usage: /contract <edit|clear> --scope <project|session>") {
+        let scope;
+        const rest = [];
+        for (let index = 0; index < args.length; index++) {
+            const token = args[index] ?? "";
+            const normalized = token.toLowerCase();
+            if (normalized === "--scope") {
+                const value = (args[index + 1] ?? "").toLowerCase().trim();
+                if (!value) {
+                    return { scope, rest, error: usage };
+                }
+                if (value !== "project" && value !== "session") {
+                    return { scope, rest, error: `Invalid contract scope "${value}". Use project or session.` };
+                }
+                scope = value;
+                index += 1;
+                continue;
+            }
+            rest.push(token);
+        }
+        return { scope, rest };
     }
-    buildCheckpointLabel(name) {
-        return `${CHECKPOINT_LABEL_PREFIX}${name}`;
+    cloneContract(contract) {
+        return normalizeEngineeringContract({
+            ...(contract.goal ? { goal: contract.goal } : {}),
+            ...(contract.scope_include ? { scope_include: [...contract.scope_include] } : {}),
+            ...(contract.scope_exclude ? { scope_exclude: [...contract.scope_exclude] } : {}),
+            ...(contract.constraints ? { constraints: [...contract.constraints] } : {}),
+            ...(contract.quality_gates ? { quality_gates: [...contract.quality_gates] } : {}),
+            ...(contract.definition_of_done ? { definition_of_done: [...contract.definition_of_done] } : {}),
+            ...(contract.assumptions ? { assumptions: [...contract.assumptions] } : {}),
+            ...(contract.non_goals ? { non_goals: [...contract.non_goals] } : {}),
+            ...(contract.risks ? { risks: [...contract.risks] } : {}),
+            ...(contract.deliverables ? { deliverables: [...contract.deliverables] } : {}),
+            ...(contract.success_metrics ? { success_metrics: [...contract.success_metrics] } : {}),
+            ...(contract.stakeholders ? { stakeholders: [...contract.stakeholders] } : {}),
+            ...(contract.owner ? { owner: contract.owner } : {}),
+            ...(contract.timebox ? { timebox: contract.timebox } : {}),
+            ...(contract.notes ? { notes: contract.notes } : {}),
+        });
     }
-    normalizeCheckpointName(raw) {
-        const normalized = raw.replace(/\s+/g, " ").trim();
-        if (!normalized)
-            return undefined;
-        if (normalized.length > 80)
-            return undefined;
-        return normalized;
+    formatContractSection(title, contract) {
+        const payload = Object.keys(contract).length > 0 ? contract : {};
+        return `${title}:\n${JSON.stringify(payload, null, 2)}`;
+    }
+    formatContractFieldPreview(field, value) {
+        if (field.kind === "text") {
+            if (typeof value !== "string" || value.trim().length === 0)
+                return "(empty)";
+            return value.trim();
+        }
+        if (!Array.isArray(value) || value.length === 0)
+            return "(empty)";
+        const values = value.filter((item) => typeof item === "string" && item.trim().length > 0);
+        if (values.length === 0)
+            return "(empty)";
+        const preview = values.slice(0, 2).join("; ");
+        return values.length > 2 ? `${preview} (+${values.length - 2})` : preview;
+    }
+    showContractState(state) {
+        this.showCommandTextBlock("Contract", [
+            `project_path: ${state.projectPath}${state.hasProjectFile ? "" : " (missing)"}`,
+            "",
+            this.formatContractSection("Project", state.project),
+            "",
+            this.formatContractSection("Session overlay", state.sessionOverlay),
+            "",
+            this.formatContractSection("Effective", state.effective),
+        ].join("\n"));
     }
-    getSessionCheckpoints() {
-        const active = new Map();
-        for (const entry of this.sessionManager.getEntries()) {
-            if (entry.type !== "label")
-                continue;
-            const name = this.parseCheckpointNameFromLabel(entry.label);
-            if (!name) {
-                active.delete(entry.targetId);
-                continue;
+    async editContractFieldValue(scope, field, draft) {
+        const payload = draft;
+        const current = payload[field.key];
+        if (field.kind === "text") {
+            const entered = await this.showExtensionInput(`/contract ${scope}: ${field.key}\n${field.help}\nEnter empty value to clear.`, typeof current === "string" && current.trim().length > 0 ? current : field.placeholder);
+            if (entered === undefined)
+                return undefined;
+            const nextPayload = { ...payload };
+            const normalized = entered.trim();
+            if (normalized.length === 0) {
+                delete nextPayload[field.key];
             }
-            active.set(entry.targetId, {
-                name,
-                targetId: entry.targetId,
-                labelEntryId: entry.id,
-                timestamp: entry.timestamp,
-            });
+            else {
+                nextPayload[field.key] = normalized;
+            }
+            return normalizeEngineeringContract(nextPayload);
         }
-        return [...active.values()].sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
-    }
-    buildDefaultCheckpointName(checkpoints) {
-        const used = new Set(checkpoints.map((checkpoint) => checkpoint.name.toLowerCase()));
-        let index = 1;
-        while (used.has(`cp-${index}`)) {
-            index += 1;
+        const prefill = Array.isArray(current)
+            ? current.filter((item) => typeof item === "string").join("\n")
+            : "";
+        const edited = await this.showExtensionEditor(`/contract ${scope}: ${field.key}\n${field.help}\nOne item per line. Empty value clears the field.`, prefill);
+        if (edited === undefined)
+            return undefined;
+        const values = edited
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+        const nextPayload = { ...payload };
+        if (values.length === 0) {
+            delete nextPayload[field.key];
         }
-        return `cp-${index}`;
-    }
-    formatCheckpointList(checkpoints) {
-        if (checkpoints.length === 0) {
-            return "No checkpoints yet.\nCreate one with: /checkpoint [name]";
+        else {
+            nextPayload[field.key] = values;
         }
-        const newestFirst = [...checkpoints].reverse();
-        const lines = newestFirst.map((checkpoint, index) => {
-            const target = this.sessionManager.getEntry(checkpoint.targetId);
-            const type = target?.type ?? "missing";
-            return `${index + 1}. ${checkpoint.name} -> ${checkpoint.targetId} (${type}) @ ${checkpoint.timestamp}`;
-        });
-        lines.push("");
-        lines.push("Usage: /rollback [name|index]");
-        return lines.join("\n");
+        return normalizeEngineeringContract(nextPayload);
     }
-    formatCheckpointOption(index, checkpoint) {
-        const target = this.sessionManager.getEntry(checkpoint.targetId);
-        const type = target?.type ?? "missing";
-        return `${index}. ${checkpoint.name} -> ${checkpoint.targetId} (${type}) @ ${checkpoint.timestamp}`;
-    }
-    handleCheckpointCommand(text) {
-        const args = this.parseSlashArgs(text).slice(1);
-        const subcommand = args[0]?.toLowerCase();
-        const checkpoints = this.getSessionCheckpoints();
-        if (subcommand === "list" || subcommand === "ls") {
-            this.showCommandTextBlock("Checkpoints", this.formatCheckpointList(checkpoints));
-            return;
-        }
-        if (subcommand === "help" || subcommand === "-h" || subcommand === "--help") {
-            this.showCommandTextBlock("Checkpoint Help", ["Usage:", "  /checkpoint [name]", "  /checkpoint list", "", "Examples:", "  /checkpoint", "  /checkpoint before-refactor"].join("\n"));
-            return;
-        }
-        const leafId = this.sessionManager.getLeafId();
-        if (!leafId) {
-            this.showWarning("Cannot create checkpoint yet (session has no entries).");
-            return;
-        }
-        const requestedName = args.join(" ");
-        const name = requestedName ? this.normalizeCheckpointName(requestedName) : this.buildDefaultCheckpointName(checkpoints);
-        if (!name) {
-            this.showWarning("Invalid checkpoint name. Use 1-80 visible characters.");
-            return;
-        }
-        this.sessionManager.appendLabelChange(leafId, this.buildCheckpointLabel(name));
-        this.showStatus(`Checkpoint saved: ${name} (${leafId})`);
+    formatContractEditorSummary(scope, draft) {
+        const setCount = CONTRACT_FIELD_DEFINITIONS.filter((field) => {
+            const value = draft[field.key];
+            if (field.kind === "text")
+                return typeof value === "string" && value.trim().length > 0;
+            return Array.isArray(value) && value.length > 0;
+        }).length;
+        return `/contract editor (${scope})\nfilled=${setCount}/${CONTRACT_FIELD_DEFINITIONS.length}`;
     }
-    async handleRollbackCommand(text) {
-        const args = this.parseSlashArgs(text).slice(1);
-        const subcommand = args[0]?.toLowerCase();
-        const checkpoints = this.getSessionCheckpoints();
-        if (subcommand === "list" || subcommand === "ls") {
-            this.showCommandTextBlock("Checkpoints", this.formatCheckpointList(checkpoints));
-            return;
-        }
-        if (subcommand === "help" || subcommand === "-h" || subcommand === "--help") {
-            this.showCommandTextBlock("Rollback Help", [
-                "Usage:",
-                "  /rollback",
-                "  /rollback <name>",
-                "  /rollback <index>",
-                "",
-                "Examples:",
-                "  /rollback",
-                "  /rollback before-refactor",
-                "  /rollback 2",
-            ].join("\n"));
-            return;
-        }
-        if (checkpoints.length === 0) {
-            this.showWarning("No checkpoints available. Create one with /checkpoint.");
+    async editContractScope(scope) {
+        const state = this.getContractStateSafe();
+        if (!state)
             return;
-        }
-        const newestFirst = [...checkpoints].reverse();
-        const selector = args.join(" ").trim();
-        let target = newestFirst[0];
-        if (selector) {
-            const numeric = Number.parseInt(selector, 10);
-            if (Number.isFinite(numeric) && `${numeric}` === selector) {
-                target = newestFirst[numeric - 1];
-                if (!target) {
-                    this.showWarning(`Checkpoint index ${numeric} is out of range.`);
-                    return;
-                }
+        let draft = this.cloneContract(scope === "project" ? state.project : state.sessionOverlay);
+        while (true) {
+            const fieldOptions = CONTRACT_FIELD_DEFINITIONS.map((field) => {
+                const value = draft[field.key];
+                return {
+                    field,
+                    label: `Edit ${field.key}: ${this.formatContractFieldPreview(field, value)}`,
+                };
+            });
+            const selected = await this.showExtensionSelector(`${this.formatContractEditorSummary(scope, draft)}\nHow to use: select a field and press Enter to edit. Changes are auto-saved immediately.`, [
+                ...fieldOptions.map((entry) => entry.label),
+                "Open JSON preview",
+                "Delete scope contract",
+                "Cancel",
+            ]);
+            if (!selected || selected.startsWith("Cancel")) {
+                this.showStatus("Contract edit cancelled.");
+                return;
             }
-            else {
-                target = newestFirst.find((checkpoint) => checkpoint.name === selector);
-                if (!target) {
-                    this.showWarning(`Checkpoint "${selector}" not found.`);
-                    return;
-                }
+            if (selected.startsWith("Open JSON preview")) {
+                this.showCommandTextBlock(`Contract Draft (${scope})`, JSON.stringify(Object.keys(draft).length > 0 ? draft : {}, null, 2));
+                continue;
             }
-        }
-        else {
-            const canShowInteractiveSelector = !!this.ui && !!this.editorContainer;
-            if (canShowInteractiveSelector) {
-                const options = newestFirst.map((checkpoint, index) => this.formatCheckpointOption(index + 1, checkpoint));
-                const picked = await this.showExtensionSelector("/rollback: choose checkpoint", options);
-                if (!picked) {
-                    this.showStatus("Rollback cancelled");
-                    return;
-                }
-                const selectedIndex = options.indexOf(picked);
-                if (selectedIndex >= 0) {
-                    target = newestFirst[selectedIndex];
+            if (selected.startsWith("Delete scope contract")) {
+                if (scope === "project") {
+                    const confirm = await this.showExtensionConfirm("Delete project contract?", `${state.projectPath}\nThis removes .iosm/contract.json`);
+                    if (!confirm) {
+                        this.showStatus("Project contract delete cancelled.");
+                        continue;
+                    }
                 }
-            }
-        }
-        if (!target) {
-            this.showWarning("No rollback target selected.");
-            return;
-        }
-        try {
-            const result = await this.session.navigateTree(target.targetId, { summarize: false });
-            if (result.cancelled || result.aborted) {
-                this.showStatus("Rollback cancelled");
+                this.contractService.clear(scope);
+                this.syncRuntimePromptSuffix();
+                this.showStatus(`Contract cleared (${scope}).`);
                 return;
             }
-            this.chatContainer.clear();
-            this.renderInitialMessages();
-            if (result.editorText && !this.editor.getText().trim()) {
-                this.editor.setText(result.editorText);
+            const fieldEntry = fieldOptions.find((entry) => entry.label === selected);
+            const field = fieldEntry?.field;
+            if (!field) {
+                this.showWarning("Unknown contract field selection.");
+                continue;
+            }
+            const updated = await this.editContractFieldValue(scope, field, draft);
+            if (!updated) {
+                this.showStatus(`Field edit cancelled (${field.key}).`);
+                continue;
+            }
+            draft = updated;
+            try {
+                this.contractService.save(scope, draft);
+                this.syncRuntimePromptSuffix();
+                this.showStatus(`Saved ${field.key} (${scope}).`);
+            }
+            catch (error) {
+                this.showWarning(error instanceof Error ? error.message : String(error));
             }
-            this.showStatus(`Rolled back to checkpoint: ${target.name}`);
-        }
-        catch (error) {
-            this.showError(error instanceof Error ? error.message : String(error));
         }
     }
-    async runDoctorInteractiveFixes(checks) {
-        const canShowInteractiveSelector = !!this.ui && !!this.editorContainer;
-        if (!canShowInteractiveSelector) {
-            return;
-        }
-        const hasModelIssues = checks.some((check) => (check.label === "Active model" || check.label === "Active model auth" || check.label === "Available models") &&
-            check.level === "fail");
-        const hasMcpIssues = checks.some((check) => check.label === "MCP servers" && check.level !== "ok");
-        const hasSemanticIssues = checks.some((check) => check.label === "Semantic index" && check.level !== "ok");
-        const hasResourceIssues = checks.some((check) => check.label === "Resources" && check.level !== "ok");
+    async runContractInteractiveMenu() {
         while (true) {
-            const options = [];
-            if (hasModelIssues) {
-                options.push("Open model selector");
-                options.push("Login provider");
+            const state = this.getContractStateSafe();
+            if (!state)
+                return;
+            const selected = await this.showExtensionSelector([
+                `/contract manager`,
+                `project=${state.hasProjectFile ? "yes" : "no"} session_keys=${Object.keys(state.sessionOverlay).length} effective_keys=${Object.keys(state.effective).length}`,
+                `How to use: open effective to inspect merged JSON, edit session for temporary changes, edit project for persistent changes.`,
+                `Field edits are auto-saved right after Enter.`,
+            ].join("\n"), [
+                "Open effective contract",
+                "Edit session contract",
+                "Edit project contract",
+                "Copy effective -> session",
+                "Copy effective -> project",
+                "Delete session contract",
+                "Delete project contract",
+                "Close",
+            ]);
+            if (!selected || selected.startsWith("Close")) {
+                return;
             }
-            if (this.mcpRuntime) {
-                if (hasMcpIssues) {
-                    options.push("Open MCP manager");
+            if (selected === "Open effective contract") {
+                this.showContractState(state);
+                continue;
+            }
+            if (selected === "Edit session contract") {
+                await this.editContractScope("session");
+                continue;
+            }
+            if (selected === "Edit project contract") {
+                await this.editContractScope("project");
+                continue;
+            }
+            if (selected === "Copy effective -> session") {
+                try {
+                    this.contractService.save("session", state.effective);
+                    this.syncRuntimePromptSuffix();
+                    this.showStatus("Effective contract copied to session overlay.");
                 }
-                options.push("Refresh MCP runtime");
+                catch (error) {
+                    this.showWarning(error instanceof Error ? error.message : String(error));
+                }
+                continue;
             }
-            if (hasSemanticIssues) {
-                options.push("Open semantic manager");
+            if (selected === "Copy effective -> project") {
+                try {
+                    this.contractService.save("project", state.effective);
+                    this.syncRuntimePromptSuffix();
+                    this.showStatus("Effective contract copied to project.");
+                }
+                catch (error) {
+                    this.showWarning(error instanceof Error ? error.message : String(error));
+                }
+                continue;
             }
-            if (this.permissionMode === "yolo") {
-                options.push("Set permissions mode to ask");
+            if (selected === "Delete session contract") {
+                this.contractService.clear("session");
+                this.syncRuntimePromptSuffix();
+                this.showStatus("Session contract deleted.");
+                continue;
             }
-            if (hasResourceIssues) {
-                options.push("Reload resources");
+            if (selected === "Delete project contract") {
+                const confirm = await this.showExtensionConfirm("Delete project contract?", `${state.projectPath}\nThis removes .iosm/contract.json`);
+                if (!confirm) {
+                    this.showStatus("Project contract delete cancelled.");
+                    continue;
+                }
+                this.contractService.clear("project");
+                this.syncRuntimePromptSuffix();
+                this.showStatus("Project contract deleted.");
             }
-            options.push("Show auth/models paths");
-            options.push("Close");
-            const selected = await this.showExtensionSelector("/doctor fixes", options);
-            if (!selected || selected === "Close") {
+        }
+    }
+    async handleContractCommand(text) {
+        const args = this.parseSlashArgs(text).slice(1);
+        if (args.length === 0 || (args[0]?.toLowerCase() ?? "") === "ui") {
+            await this.runContractInteractiveMenu();
+            return;
+        }
+        const subcommand = (args[0] ?? "").toLowerCase();
+        const rest = args.slice(1);
+        if (subcommand === "help" || subcommand === "-h" || subcommand === "--help") {
+            this.showCommandTextBlock("Contract Help", [
+                "Usage:",
+                "  /contract",
+                "  /contract ui",
+                "  /contract show",
+                "  /contract edit --scope <project|session>",
+                "  /contract clear --scope <project|session>",
+                "  /contract help",
+                "",
+                "Editor model:",
+                "  - Fill fields interactively (goal, scope, constraints, quality gates, DoD, risks, etc.)",
+                "  - Each field is saved immediately after Enter (no extra Save step)",
+            ].join("\n"));
+            return;
+        }
+        if (subcommand === "show" || subcommand === "status" || subcommand === "open") {
+            const state = this.getContractStateSafe();
+            if (!state)
                 return;
-            }
-            if (selected === "Open model selector") {
-                await this.showModelProviderSelector();
+            this.showContractState(state);
+            return;
+        }
+        if (subcommand === "edit") {
+            const parsed = this.parseContractScopeOptions(rest, "Usage: /contract edit --scope <project|session>");
+            if (parsed.error) {
+                this.showWarning(parsed.error);
                 return;
             }
-            if (selected === "Login provider") {
-                await this.showOAuthSelector("login");
+            if (parsed.rest.length > 0) {
+                this.showWarning(`Unexpected arguments for /contract edit: ${parsed.rest.join(" ")}`);
                 return;
             }
-            if (selected === "Open MCP manager") {
-                await this.refreshMcpRuntimeAndSession();
-                this.showMcpSelector();
+            await this.editContractScope(parsed.scope ?? "session");
+            return;
+        }
+        if (subcommand === "clear" || subcommand === "rm" || subcommand === "remove" || subcommand === "delete") {
+            const parsed = this.parseContractScopeOptions(rest, "Usage: /contract clear --scope <project|session>");
+            if (parsed.error) {
+                this.showWarning(parsed.error);
                 return;
             }
-            if (selected === "Refresh MCP runtime") {
-                await this.refreshMcpRuntimeAndSession();
-                this.showStatus("MCP servers refreshed");
-                continue;
-            }
-            if (selected === "Open semantic manager") {
-                await this.handleSemanticCommand("/semantic");
+            if (!parsed.scope) {
+                this.showWarning("Usage: /contract clear --scope <project|session>");
                 return;
             }
-            if (selected === "Set permissions mode to ask") {
-                this.permissionMode = "ask";
-                this.settingsManager.setPermissionMode("ask");
-                this.showStatus("Permissions: ask");
-                continue;
-            }
-            if (selected === "Reload resources") {
-                await this.handleReloadCommand();
+            if (parsed.rest.length > 0) {
+                this.showWarning(`Unexpected arguments for /contract clear: ${parsed.rest.join(" ")}`);
                 return;
             }
-            if (selected === "Show auth/models paths") {
-                const cwd = this.sessionManager.getCwd();
-                const agentDir = getAgentDir();
-                this.showCommandTextBlock("Runtime Paths", [
-                    `auth.json: ${getAuthPath()}`,
-                    `models.json: ${getModelsPath()}`,
-                    `semantic(user): ${getSemanticConfigPath("user", cwd, agentDir)}`,
-                    `semantic(project): ${getSemanticConfigPath("project", cwd, agentDir)}`,
-                    `semantic(index): ${getSemanticIndexDir(cwd, agentDir)}`,
-                ].join("\n"));
-                continue;
-            }
+            this.contractService.clear(parsed.scope);
+            this.syncRuntimePromptSuffix();
+            this.showStatus(`Contract cleared (${parsed.scope}).`);
+            return;
         }
+        this.showWarning(`Unknown /contract subcommand "${subcommand}". Use /contract help.`);
     }
-    async handleDoctorCommand(text) {
-        const args = this.parseSlashArgs(text).slice(1);
-        const outputJson = args.includes("--json");
-        const hooks = this.getHookPolicySummary();
-        const model = this.session.model;
-        const modelRegistry = this.session.modelRegistry;
-        const allModels = modelRegistry.getAll();
-        const availableModels = modelRegistry.getAvailable();
-        const modelLoadError = modelRegistry.getError();
-        const authProviders = modelRegistry.authStorage.list();
-        const hasModelAuth = model ? modelRegistry.authStorage.hasAuth(model.provider) : false;
-        const extensionErrors = this.session.resourceLoader.getExtensions().errors.length;
-        const skillDiagnostics = this.session.resourceLoader.getSkills().diagnostics.length;
-        const promptDiagnostics = this.session.resourceLoader.getPrompts().diagnostics.length;
-        const themeDiagnostics = this.session.resourceLoader.getThemes().diagnostics.length;
-        const mcpStatuses = this.mcpRuntime?.getServers() ?? [];
-        const mcpConfigErrors = this.mcpRuntime?.getErrors() ?? [];
-        const mcpConnected = mcpStatuses.filter((status) => status.state === "connected").length;
-        const mcpErrored = mcpStatuses.filter((status) => status.state === "error").length;
-        const mcpDisabled = mcpStatuses.filter((status) => !status.enabled).length;
-        const cliToolStatuses = resolveDoctorCliToolStatuses();
-        const missingCliTools = cliToolStatuses.filter((status) => !status.available).map((status) => status.tool);
-        let semanticStatus;
-        let semanticStatusError;
-        try {
-            semanticStatus = await this.createSemanticRuntime().status();
+    normalizeSingularComplexity(value, fallback) {
+        const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
+        if (normalized === "low" || normalized === "medium" || normalized === "high") {
+            return normalized;
         }
-        catch (error) {
-            semanticStatusError = error instanceof Error ? error.message : String(error);
-        }
-        const checks = [];
-        const addCheck = (level, label, detail, fix) => checks.push({ level, label, detail, fix });
-        if (!model) {
-            addCheck("fail", "Active model", "No active model selected", "Run /model and pick a model.");
-        }
-        else if (!hasModelAuth) {
-            addCheck("fail", "Active model auth", `Model ${model.provider}/${model.id} has no auth configured`, `Run /login ${model.provider} or set API key env vars.`);
-        }
-        else {
-            addCheck("ok", "Active model", `${model.provider}/${model.id}`);
+        return fallback;
+    }
+    normalizeSingularBlastRadius(value, fallback) {
+        const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
+        if (normalized === "low" || normalized === "medium" || normalized === "high") {
+            return normalized;
         }
-        if (availableModels.length === 0) {
-            addCheck("fail", "Available models", "No models currently have valid auth", "Run /login or configure API keys.");
+        return fallback;
+    }
+    normalizeSingularRecommendation(value, fallback) {
+        const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
+        if (normalized === "implement_now" || normalized === "implement_incrementally" || normalized === "defer") {
+            return normalized;
         }
-        else {
-            addCheck("ok", "Available models", `${availableModels.length}/${allModels.length} ready`);
+        return fallback;
+    }
+    normalizeSingularStageFit(value) {
+        const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
+        if (normalized === "needed_now" || normalized === "optional_now" || normalized === "later") {
+            return normalized;
         }
-        if (modelLoadError) {
-            addCheck("warn", "models.json", modelLoadError.split("\n")[0] ?? modelLoadError, `Inspect ${getModelsPath()}.`);
+        if (normalized === "now")
+            return "needed_now";
+        if (normalized === "optional")
+            return "optional_now";
+        return undefined;
+    }
+    toTrimmedString(value, maxLength, fallback) {
+        if (typeof value !== "string")
+            return fallback;
+        const compact = value.replace(/\s+/g, " ").trim();
+        if (!compact)
+            return fallback;
+        if (compact.length <= maxLength)
+            return compact;
+        return compact.slice(0, maxLength).trim();
+    }
+    toTrimmedStringList(value, maxItems, maxLength = 220) {
+        if (!Array.isArray(value))
+            return [];
+        const lines = [];
+        for (const item of value) {
+            const normalized = this.toTrimmedString(item, maxLength);
+            if (!normalized)
+                continue;
+            lines.push(normalized);
+            if (lines.length >= maxItems)
+                break;
         }
-        else {
-            addCheck("ok", "models.json", "Loaded without schema/runtime errors");
+        return lines;
+    }
+    normalizeSingularImpactAnalysis(value, fallback) {
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            return fallback;
         }
-        if (!fs.existsSync(getAuthPath())) {
-            addCheck("warn", "auth.json", `Missing ${getAuthPath()}`, "Run /login to create credentials.");
+        const payload = value;
+        const codebase = this.toTrimmedString(payload.codebase, 260, fallback?.codebase ?? "Unknown.");
+        const delivery = this.toTrimmedString(payload.delivery, 260, fallback?.delivery ?? "Unknown.");
+        const risks = this.toTrimmedString(payload.risks, 260, fallback?.risks ?? "Unknown.");
+        const operations = this.toTrimmedString(payload.operations, 260, fallback?.operations ?? "Unknown.");
+        if (!codebase || !delivery || !risks || !operations)
+            return fallback;
+        return {
+            codebase,
+            delivery,
+            risks,
+            operations,
+        };
+    }
+    buildSingularContractPromptSection(contract) {
+        const lines = [];
+        if (contract.goal)
+            lines.push(`- goal: ${contract.goal}`);
+        if ((contract.scope_include ?? []).length > 0) {
+            lines.push(`- scope_include: ${(contract.scope_include ?? []).slice(0, 8).join("; ")}`);
         }
-        else {
-            addCheck("ok", "auth.json", `${authProviders.length} provider credential(s) stored`);
+        if ((contract.scope_exclude ?? []).length > 0) {
+            lines.push(`- scope_exclude: ${(contract.scope_exclude ?? []).slice(0, 8).join("; ")}`);
         }
-        if (!this.mcpRuntime) {
-            addCheck("warn", "MCP runtime", "Unavailable in this session");
+        if ((contract.constraints ?? []).length > 0) {
+            lines.push(`- constraints: ${(contract.constraints ?? []).slice(0, 10).join("; ")}`);
         }
-        else if (mcpStatuses.length === 0) {
-            addCheck("warn", "MCP servers", "No MCP servers configured", "Use /mcp add or iosm mcp add ...");
+        if ((contract.quality_gates ?? []).length > 0) {
+            lines.push(`- quality_gates: ${(contract.quality_gates ?? []).slice(0, 10).join("; ")}`);
         }
-        else if (mcpErrored > 0 || mcpConfigErrors.length > 0) {
-            addCheck("warn", "MCP servers", `${mcpConnected} connected, ${mcpErrored} error, ${mcpDisabled} disabled`, "Open /mcp to reconnect or inspect server errors.");
+        if ((contract.definition_of_done ?? []).length > 0) {
+            lines.push(`- definition_of_done: ${(contract.definition_of_done ?? []).slice(0, 10).join("; ")}`);
         }
-        else {
-            addCheck("ok", "MCP servers", `${mcpConnected} connected, ${mcpDisabled} disabled`);
+        if ((contract.non_goals ?? []).length > 0) {
+            lines.push(`- non_goals: ${(contract.non_goals ?? []).slice(0, 8).join("; ")}`);
         }
-        if (semanticStatusError) {
-            addCheck("fail", "Semantic index", semanticStatusError, "Run /semantic setup and retry /semantic status.");
+        return lines.length > 0 ? lines.join("\n") : "- none";
+    }
+    resolveSingularRepoScaleMode(baseline) {
+        if (baseline.scannedFiles >= 8000 || baseline.sourceFiles >= 4000) {
+            return {
+                mode: "large",
+                reason: `scanned=${baseline.scannedFiles}, source=${baseline.sourceFiles}`,
+            };
         }
-        else if (!semanticStatus) {
-            addCheck("warn", "Semantic index", "Status unavailable", "Run /semantic setup.");
+        if (baseline.scannedFiles >= 2500 || baseline.sourceFiles >= 1200) {
+            return {
+                mode: "medium",
+                reason: `scanned=${baseline.scannedFiles}, source=${baseline.sourceFiles}`,
+            };
         }
-        else if (!semanticStatus.configured) {
-            addCheck("warn", "Semantic index", "Not configured", `Run /semantic setup (user: ${semanticStatus.configPathUser} or project: ${semanticStatus.configPathProject}).`);
+        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.",
+            };
         }
-        else if (!semanticStatus.enabled) {
-            addCheck("warn", "Semantic index", "Configured but disabled", "Enable semanticSearch.enabled or rerun /semantic setup.");
+        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.",
+            };
         }
-        else if (!semanticStatus.indexed) {
-            addCheck("warn", "Semantic index", "Configured but index is missing", "Run /semantic index.");
+        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.",
+            };
         }
-        else if (semanticStatus.stale) {
-            const requiresRebuild = semanticStatus.staleReason === "provider_changed" ||
-                semanticStatus.staleReason === "chunking_changed" ||
-                semanticStatus.staleReason === "index_filters_changed" ||
-                semanticStatus.staleReason === "dimension_mismatch";
-            addCheck("warn", "Semantic index", `Indexed but stale${semanticStatus.staleReason ? ` (${semanticStatus.staleReason})` : ""}`, requiresRebuild ? "Run /semantic rebuild." : "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.",
+            };
         }
-        else {
-            addCheck("ok", "Semantic index", `${semanticStatus.provider}/${semanticStatus.model} · files=${semanticStatus.files} chunks=${semanticStatus.chunks}`);
+        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.",
+                ],
+            };
         }
-        if (missingCliTools.length > 0) {
-            addCheck("warn", "CLI toolchain", `${cliToolStatuses.length - missingCliTools.length}/${cliToolStatuses.length} available (missing: ${missingCliTools.join(", ")})`, `Install missing CLI tools: ${missingCliTools.join(", ")}.`);
+        try {
+            const status = await this.createSemanticRuntime().status();
+            return this.buildSingularSemanticGuidanceFromStatus(status);
         }
-        else {
-            addCheck("ok", "CLI toolchain", `${cliToolStatuses.length}/${cliToolStatuses.length} available`);
+        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.`,
+            };
         }
-        if (extensionErrors > 0 || skillDiagnostics > 0 || promptDiagnostics > 0 || themeDiagnostics > 0) {
-            addCheck("warn", "Resources", `extensions:${extensionErrors} skills:${skillDiagnostics} prompts:${promptDiagnostics} themes:${themeDiagnostics}`, "Run /reload and inspect warnings shown in the chat.");
+    }
+    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";
+        return [
+            "You are running a feasibility pass for `/singular`.",
+            "Task: analyze the codebase for this request and decide whether to implement now, incrementally, or defer.",
+            "",
+            "Hard requirements:",
+            "- Inspect repository files with tools before final output (at least one tool call).",
+            "- Return a human-readable markdown report (no JSON).",
+            "- Include exactly three options (Option 1, Option 2, Option 3).",
+            "- Each option must contain concrete file paths when possible.",
+            "",
+            "Use this exact template:",
+            "# Singular Feasibility",
+            "Recommendation: implement_now|implement_incrementally|defer",
+            "Reason: <one concise reason>",
+            "Complexity: low|medium|high",
+            "Blast Radius: low|medium|high",
+            "Stage Fit: needed_now|optional_now|later",
+            "Stage Fit Reason: <why this stage fit>",
+            "Impact - Codebase: <impact>",
+            "Impact - Delivery: <impact>",
+            "Impact - Risks: <impact>",
+            "Impact - Operations: <impact>",
+            "",
+            "## Option 1: <title>",
+            "Summary: <summary>",
+            "Complexity: low|medium|high",
+            "Blast Radius: low|medium|high",
+            "When to choose: <guidance>",
+            "Suggested files:",
+            "- <path>",
+            "Plan:",
+            "1. <step>",
+            "Pros:",
+            "- <pro>",
+            "Cons:",
+            "- <con>",
+            "",
+            "## Option 2: <title>",
+            "... same fields ...",
+            "",
+            "## Option 3: <title>",
+            "... same fields ...",
+            "",
+            `Feature request: ${request}`,
+            "",
+            "Baseline scan summary (heuristic pass):",
+            `- scanned_files: ${baseline.scannedFiles}`,
+            `- source_files: ${baseline.sourceFiles}`,
+            `- test_files: ${baseline.testFiles}`,
+            `- baseline_complexity: ${baseline.baselineComplexity}`,
+            `- 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,
+            "",
+            "Active engineering contract:",
+            this.buildSingularContractPromptSection(contract),
+        ].join("\n");
+    }
+    extractLabeledValue(text, labels, maxLength = 320) {
+        for (const label of labels) {
+            const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            const match = text.match(new RegExp(`^\\s*${escaped}\\s*:\\s*(.+?)\\s*$`, "im"));
+            if (!match?.[1])
+                continue;
+            const normalized = this.toTrimmedString(match[1], maxLength);
+            if (normalized)
+                return normalized;
         }
-        else {
-            addCheck("ok", "Resources", "No extension/skill/prompt/theme diagnostics");
+        return undefined;
+    }
+    parseSingularListSection(block, heading, maxItems) {
+        const headings = [
+            "Summary",
+            "Complexity",
+            "Blast Radius",
+            "When to choose",
+            "Suggested files",
+            "Plan",
+            "Pros",
+            "Cons",
+        ];
+        const escapedHeading = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const nextHeadings = headings.filter((item) => item !== heading).map((item) => item.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+        const sectionRegex = new RegExp(`(?:^|\\n)\\s*${escapedHeading}\\s*:\\s*([\\s\\S]*?)(?=\\n\\s*(?:${nextHeadings.join("|")})\\s*:|\\n\\s*##\\s*Option\\s*[123]\\s*:|$)`, "i");
+        const sectionMatch = block.match(sectionRegex);
+        if (!sectionMatch?.[1])
+            return [];
+        const result = [];
+        const lines = sectionMatch[1].split(/\r?\n/);
+        for (const rawLine of lines) {
+            let line = rawLine.trim();
+            if (!line)
+                continue;
+            line = line.replace(/^[-*]\s+/, "").replace(/^\d+[.)]\s+/, "").trim();
+            if (!line)
+                continue;
+            result.push(line);
+            if (result.length >= maxItems)
+                break;
         }
-        addCheck(this.permissionMode === "yolo" ? "warn" : "ok", "Permissions", `mode=${this.permissionMode}, allowRules=${this.permissionAllowRules.length}, denyRules=${this.permissionDenyRules.length}`, this.permissionMode === "yolo" ? "Switch to /permissions ask for safer execution." : undefined);
-        addCheck(process.env[ENV_OFFLINE] ? "warn" : "ok", "Environment", `offline=${process.env[ENV_OFFLINE] ? "on" : "off"}, sessionTrace=${isSessionTraceEnabled() ? "on" : "off"}`, process.env[ENV_OFFLINE] ? "Unset IOSM_OFFLINE/PI_OFFLINE when network access is required." : undefined);
-        addCheck("ok", "Hooks", hooks
-            ? `U${hooks.userPromptSubmit}/P${hooks.preToolUse}/T${hooks.postToolUse}/S${hooks.stop}`
-            : "No hooks loaded");
-        const recommendations = [...new Set(checks.map((check) => check.fix).filter((fix) => !!fix))];
-        if (outputJson) {
-            this.showCommandJsonBlock("Doctor Report", {
-                timestamp: new Date().toISOString(),
-                cwd: this.sessionManager.getCwd(),
-                sessionFile: this.sessionManager.getSessionFile() ?? null,
-                activeProfile: this.activeProfileName,
-                externalCliTools: cliToolStatuses,
-                checks,
-                recommendations,
+        return result;
+    }
+    parseSingularOptionsFromText(text, baseline) {
+        const optionRegex = /^##\s*Option\s*([123])\s*:\s*(.+?)\s*$/gim;
+        const matches = [...text.matchAll(optionRegex)];
+        const parsed = [];
+        for (let index = 0; index < matches.length; index += 1) {
+            const current = matches[index];
+            const optionIndexRaw = Number.parseInt(current[1] ?? "", 10);
+            const optionIndex = Number.isInteger(optionIndexRaw) ? Math.max(1, Math.min(3, optionIndexRaw)) - 1 : index;
+            const fallback = baseline.options[optionIndex] ?? baseline.options[Math.min(index, baseline.options.length - 1)];
+            if (!fallback)
+                continue;
+            const bodyStart = (current.index ?? 0) + current[0].length;
+            const bodyEnd = index + 1 < matches.length ? (matches[index + 1].index ?? text.length) : text.length;
+            const body = text.slice(bodyStart, bodyEnd);
+            const title = this.toTrimmedString(current[2], 120, fallback.title) ?? fallback.title;
+            const summary = this.extractLabeledValue(body, ["Summary"], 320) ?? fallback.summary;
+            const complexity = this.normalizeSingularComplexity(this.extractLabeledValue(body, ["Complexity"], 24), fallback.complexity);
+            const blastRadius = this.normalizeSingularBlastRadius(this.extractLabeledValue(body, ["Blast Radius", "Blast"], 24), fallback.blast_radius);
+            const whenToChoose = this.extractLabeledValue(body, ["When to choose"], 220) ?? fallback.when_to_choose;
+            const suggestedFiles = this.parseSingularListSection(body, "Suggested files", 8);
+            const plan = this.parseSingularListSection(body, "Plan", 8);
+            const pros = this.parseSingularListSection(body, "Pros", 6);
+            const cons = this.parseSingularListSection(body, "Cons", 6);
+            parsed.push({
+                id: String(parsed.length + 1),
+                title,
+                summary,
+                complexity,
+                blast_radius: blastRadius,
+                suggested_files: suggestedFiles.length > 0 ? suggestedFiles : fallback.suggested_files,
+                plan: plan.length > 0 ? plan : fallback.plan,
+                pros: pros.length > 0 ? pros : fallback.pros,
+                cons: cons.length > 0 ? cons : fallback.cons,
+                when_to_choose: whenToChoose,
             });
-            return;
-        }
-        const lines = [];
-        lines.push(`Timestamp: ${new Date().toISOString()}`);
-        lines.push(`CWD: ${this.sessionManager.getCwd()}`);
-        lines.push(`Session: ${this.sessionManager.getSessionFile() ?? "in-memory"}`);
-        lines.push(`Profile: ${this.activeProfileName}`);
-        lines.push("");
-        for (const check of checks) {
-            const prefix = check.level === "ok" ? "[OK]" : check.level === "warn" ? "[WARN]" : "[FAIL]";
-            lines.push(`${prefix} ${check.label}: ${check.detail}`);
-        }
-        lines.push("");
-        lines.push("External CLI tools:");
-        for (const status of cliToolStatuses) {
-            const prefix = status.available ? "[OK]" : "[WARN]";
-            const sourceLabel = status.source === "missing"
-                ? "missing"
-                : `${status.source}${status.command ? ` (${status.command})` : ""}`;
-            lines.push(`${prefix} ${status.tool}: ${sourceLabel}`);
-            if (!status.available && status.hint) {
-                lines.push(`       fix: ${status.hint}`);
-            }
-        }
-        if (recommendations.length > 0) {
-            lines.push("");
-            lines.push("Recommended actions:");
-            for (const recommendation of recommendations) {
-                lines.push(`- ${recommendation}`);
-            }
         }
-        lines.push("");
-        lines.push("Tip: /doctor --json");
-        this.showCommandTextBlock("Doctor Report", lines.join("\n"));
-        const wantsInteractiveFixes = !args.includes("--no-fix");
-        if (wantsInteractiveFixes) {
-            await this.runDoctorInteractiveFixes(checks);
+        while (parsed.length < 3 && parsed.length < baseline.options.length) {
+            const fallback = baseline.options[parsed.length];
+            parsed.push({
+                ...fallback,
+                id: String(parsed.length + 1),
+            });
         }
+        return {
+            options: parsed.slice(0, 3),
+            parsedCount: matches.length,
+        };
     }
-    showCommandTextBlock(title, body) {
-        this.chatContainer.addChild(new Spacer(1));
-        this.chatContainer.addChild(new DynamicBorder());
-        this.chatContainer.addChild(new Text(theme.bold(theme.fg("accent", title)), 1, 0));
-        this.chatContainer.addChild(new Spacer(1));
-        this.chatContainer.addChild(new Text(body, 1, 0));
-        this.chatContainer.addChild(new DynamicBorder());
-        this.ui.requestRender();
-    }
-    showCommandJsonBlock(title, value) {
-        const json = JSON.stringify(value, null, 2);
-        this.chatContainer.addChild(new Spacer(1));
-        this.chatContainer.addChild(new DynamicBorder());
-        this.chatContainer.addChild(new Text(theme.bold(theme.fg("accent", title)), 1, 0));
-        this.chatContainer.addChild(new Spacer(1));
-        this.chatContainer.addChild(new Markdown(`\`\`\`json\n${json}\n\`\`\``, 1, 1, this.getMarkdownThemeWithSettings()));
-        this.chatContainer.addChild(new DynamicBorder());
-        this.ui.requestRender();
+    parseSingularAgentAnalysisFromText(baseline, rawText) {
+        const recommendationRaw = this.extractLabeledValue(rawText, ["Recommendation"], 64);
+        const recommendation = this.normalizeSingularRecommendation(recommendationRaw, baseline.recommendation);
+        const recommendationReason = this.extractLabeledValue(rawText, ["Reason", "Recommendation Reason"], 320) ?? baseline.recommendationReason;
+        const baselineComplexity = this.normalizeSingularComplexity(this.extractLabeledValue(rawText, ["Complexity"], 24), baseline.baselineComplexity);
+        const baselineBlastRadius = this.normalizeSingularBlastRadius(this.extractLabeledValue(rawText, ["Blast Radius", "Blast"], 24), baseline.baselineBlastRadius);
+        const stageFit = this.normalizeSingularStageFit(this.extractLabeledValue(rawText, ["Stage Fit"], 40)) ?? baseline.stageFit;
+        const stageFitReason = this.extractLabeledValue(rawText, ["Stage Fit Reason"], 280) ?? baseline.stageFitReason;
+        const impactAnalysis = {
+            codebase: this.extractLabeledValue(rawText, ["Impact - Codebase", "Codebase Impact"], 260) ?? "Unknown.",
+            delivery: this.extractLabeledValue(rawText, ["Impact - Delivery", "Delivery Impact"], 260) ?? "Unknown.",
+            risks: this.extractLabeledValue(rawText, ["Impact - Risks", "Risk Impact"], 260) ?? "Unknown.",
+            operations: this.extractLabeledValue(rawText, ["Impact - Operations", "Operations Impact"], 260) ?? "Unknown.",
+        };
+        const { options, parsedCount } = this.parseSingularOptionsFromText(rawText, baseline);
+        return {
+            result: {
+                ...baseline,
+                recommendation,
+                recommendationReason,
+                baselineComplexity,
+                baselineBlastRadius,
+                stageFit,
+                stageFitReason,
+                impactAnalysis,
+                options,
+            },
+            parsedOptions: parsedCount,
+            hasRecommendation: recommendationRaw !== undefined,
+        };
     }
-    async runIosmInitAgentVerification(result, targetDir, onEvent) {
-        if (!result.cycle) {
-            return {
-                completed: false,
-                skippedReason: "No cycle scaffold was available for verification.",
-            };
+    async runSingularAgentFeasibilityPass(request, baseline, contract, runtimeGuidance) {
+        const model = this.session.model;
+        if (!model) {
+            return undefined;
         }
-        const cycleId = result.cycle.cycleId;
-        process.env[ENV_SESSION_TRACE] = "1";
-        process.env.PI_SESSION_TRACE = "1";
+        const cwd = this.sessionManager.getCwd();
         const agentDir = getAgentDir();
-        const settingsManager = SettingsManager.create(targetDir, agentDir);
-        const settingsErrors = settingsManager.drainErrors();
-        for (const { scope, error } of settingsErrors) {
-            this.showWarning(`Init verify warning (${scope} settings): ${error.message}`);
-        }
-        const authStorage = AuthStorage.create();
+        const settingsManager = SettingsManager.create(cwd, agentDir);
+        const authStorage = AuthStorage.create(getAuthPath());
         const modelRegistry = new ModelRegistry(authStorage, getModelsPath());
         const resourceLoader = new DefaultResourceLoader({
-            cwd: targetDir,
+            cwd,
             agentDir,
             settingsManager,
             noExtensions: true,
+            noSkills: true,
+            noPromptTemplates: true,
         });
         await resourceLoader.reload();
-        const { session, modelFallbackMessage } = await createAgentSession({
-            cwd: targetDir,
+        const { session } = await createAgentSession({
+            cwd,
             sessionManager: SessionManager.inMemory(),
             settingsManager,
             authStorage,
             modelRegistry,
             resourceLoader,
+            model,
+            profile: "plan",
+            enableTaskTool: false,
+        });
+        let toolCallsStarted = 0;
+        const chunks = [];
+        const eventBridge = this.createIosmVerificationEventBridge({
+            loaderMessage: `Running /singular feasibility analysis... (${appKey(this.keybindings, "interrupt")} to interrupt)`,
         });
-        let toolExecutions = 0;
-        const activityLog = [];
-        const pushActivity = (line, persist = false) => {
-            activityLog.push(line);
-            if (activityLog.length > 30) {
-                activityLog.shift();
-            }
-            if (persist) {
-                this.showProgressLine(`IOSM init verify: ${line}`);
-            }
-        };
-        const setVerifyLiveStatus = (message) => {
-            this.setWorkingMessage(`${message} (${appKey(this.keybindings, "interrupt")} to interrupt)`);
-        };
         const unsubscribe = session.subscribe((event) => {
-            onEvent?.(event);
-            if (event.type === "turn_start") {
-                pushActivity("agent turn started");
-                setVerifyLiveStatus("Verifying workspace...");
+            eventBridge(event);
+            if (event.type === "tool_execution_start") {
+                toolCallsStarted += 1;
                 return;
             }
-            if (event.type !== "tool_execution_start") {
-                return;
-            }
-            toolExecutions += 1;
-            if (event.toolName === "bash") {
-                const commandRaw = event.args && typeof event.args === "object" && "command" in event.args
-                    ? String(event.args.command ?? "")
-                    : "";
-                const preview = commandRaw.replace(/\s+/g, " ").trim().slice(0, 68);
-                const line = `bash #${toolExecutions}${preview ? ` ${preview}${commandRaw.length > 68 ? "..." : ""}` : ""}`;
-                pushActivity(line);
-                setVerifyLiveStatus(`Verifying workspace · ${line}`);
-                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());
+                    }
+                }
             }
-            const line = `${event.toolName} #${toolExecutions}`;
-            pushActivity(line);
-            setVerifyLiveStatus(`Verifying workspace · ${line}`);
         });
-        this.iosmVerificationSession = session;
+        this.singularAnalysisSession = session;
         try {
-            if (!session.model) {
+            const primaryPrompt = this.buildSingularAgentPrompt(request, baseline, contract, runtimeGuidance);
+            const strictRetryPrompt = [
+                "Retry strict mode:",
+                "- Inspect repository files using tools first.",
+                "- Return markdown report using the exact template from previous prompt.",
+                "- Include Recommendation and Option 1/2/3 sections.",
+                "- Do not return JSON.",
+            ].join("\n");
+            const runAttempt = async (promptText) => {
+                const chunkStart = chunks.length;
+                const toolStart = toolCallsStarted;
+                await session.prompt(promptText, {
+                    expandPromptTemplates: false,
+                    skipIosmAutopilot: true,
+                    skipOrchestrationDirective: true,
+                    source: "interactive",
+                });
                 return {
-                    completed: false,
-                    skippedReason: modelFallbackMessage ??
-                        "No model available for agent verification. Configure /login or an API key, then re-run /init.",
-                    activityLog,
+                    text: chunks.slice(chunkStart).join("\n\n").trim(),
+                    toolCalls: Math.max(0, toolCallsStarted - toolStart),
                 };
+            };
+            let attempt = await runAttempt(primaryPrompt);
+            let parsed = this.parseSingularAgentAnalysisFromText(baseline, attempt.text);
+            if ((parsed.parsedOptions < 3 || !parsed.hasRecommendation || attempt.toolCalls === 0) && !session.isStreaming) {
+                attempt = await runAttempt(strictRetryPrompt);
+                parsed = this.parseSingularAgentAnalysisFromText(baseline, attempt.text);
             }
-            const timeoutMs = 180_000;
-            const startedAt = Date.now();
-            const heartbeatMs = 10_000;
-            let nextPersistentHeartbeatSec = 30;
-            let timeoutHandle;
-            let heartbeatHandle;
-            try {
-                pushActivity("waiting for model response...", true);
-                setVerifyLiveStatus("Waiting for model response...");
-                heartbeatHandle = setInterval(() => {
-                    const elapsedSec = Math.round((Date.now() - startedAt) / 1000);
-                    if (toolExecutions === 0 && elapsedSec >= nextPersistentHeartbeatSec) {
-                        pushActivity(`still waiting for model response (${elapsedSec}s)`, true);
-                        nextPersistentHeartbeatSec += 30;
-                    }
-                    setVerifyLiveStatus(toolExecutions === 0
-                        ? `Waiting for model response... ${elapsedSec}s`
-                        : `Verifying workspace... ${elapsedSec}s · tool calls=${toolExecutions}`);
-                }, heartbeatMs);
-                await Promise.race([
-                    session.prompt(buildIosmAgentVerificationPrompt(result), {
-                        expandPromptTemplates: false,
-                        skipIosmAutopilot: true,
-                        source: "interactive",
-                    }),
-                    new Promise((_resolve, reject) => {
-                        timeoutHandle = setTimeout(() => {
-                            reject(new Error(`Verifier timeout after ${Math.round(timeoutMs / 1000)}s.`));
-                        }, timeoutMs);
-                    }),
-                ]);
+            if ((parsed.parsedOptions < 3 || !parsed.hasRecommendation) || toolCallsStarted === 0) {
+                return undefined;
             }
-            finally {
-                if (timeoutHandle) {
-                    clearTimeout(timeoutHandle);
-                }
-                if (heartbeatHandle) {
-                    clearInterval(heartbeatHandle);
-                }
+            return parsed.result;
+        }
+        finally {
+            if (session.isStreaming) {
+                await session.abort().catch(() => {
+                    // best effort
+                });
             }
-            const messages = session.state.messages;
-            let lastAssistant;
-            for (let index = messages.length - 1; index >= 0; index--) {
-                const message = messages[index];
-                if (message.role === "assistant") {
-                    lastAssistant = message;
-                    break;
-                }
+            if (this.singularAnalysisSession === session) {
+                this.singularAnalysisSession = undefined;
             }
-            if (lastAssistant &&
-                (lastAssistant.stopReason === "error" || lastAssistant.stopReason === "aborted")) {
-                pushActivity(`agent finished with ${lastAssistant.stopReason}`);
-                if (lastAssistant.stopReason === "aborted") {
-                    return {
-                        completed: false,
-                        cancelled: true,
-                        skippedReason: "Cancelled by user.",
-                        tracePath: session.sessionTracePath ??
-                            (isSessionTraceEnabled() ? getSessionTracePath(session.sessionManager.getSessionId()) : undefined),
-                        activityLog,
-                    };
-                }
-                return {
-                    completed: false,
-                    error: lastAssistant.errorMessage ?? `Verifier finished with ${lastAssistant.stopReason}.`,
-                    tracePath: session.sessionTracePath ??
-                        (isSessionTraceEnabled() ? getSessionTracePath(session.sessionManager.getSessionId()) : undefined),
-                    activityLog,
-                };
+            unsubscribe();
+            session.dispose();
+        }
+    }
+    formatSingularRunReport(result) {
+        const recommendedId = this.resolveRecommendedSingularOptionId(result);
+        const coverageLine = `${result.scannedFiles} scanned · ${result.sourceFiles} source · ${result.testFiles} tests`;
+        const lines = [
+            `run_id: ${result.runId}`,
+            `request: ${result.request}`,
+            `generated_at: ${result.generatedAt}`,
+            "",
+            "overview:",
+            `  recommendation: ${result.recommendation}`,
+            `  reason: ${result.recommendationReason}`,
+            `  complexity: ${result.baselineComplexity}`,
+            `  blast_radius: ${result.baselineBlastRadius}`,
+            `  repository_coverage: ${coverageLine}`,
+        ];
+        if (result.stageFit) {
+            lines.push(`  stage_fit: ${result.stageFit}`);
+        }
+        if (result.stageFitReason) {
+            lines.push(`  stage_fit_reason: ${result.stageFitReason}`);
+        }
+        if (result.impactAnalysis) {
+            lines.push("");
+            lines.push("impact_analysis:");
+            lines.push(`  codebase: ${result.impactAnalysis.codebase}`);
+            lines.push(`  delivery: ${result.impactAnalysis.delivery}`);
+            lines.push(`  risks: ${result.impactAnalysis.risks}`);
+            lines.push(`  operations: ${result.impactAnalysis.operations}`);
+        }
+        if (result.matchedFiles.length > 0) {
+            lines.push("");
+            lines.push(`matched_files: ${result.matchedFiles.slice(0, 8).join(", ")}`);
+        }
+        if (result.contractSignals.length > 0) {
+            lines.push(`contract_signals: ${result.contractSignals.join(", ")}`);
+        }
+        lines.push("");
+        lines.push("implementation_options:");
+        for (const option of result.options) {
+            const recommendedMark = option.id === recommendedId ? " [recommended]" : "";
+            lines.push(`${option.id}. ${option.title}${recommendedMark} [complexity=${option.complexity}, blast=${option.blast_radius}]`);
+            lines.push(`   ${option.summary}`);
+            if (option.when_to_choose) {
+                lines.push(`   when_to_choose: ${option.when_to_choose}`);
             }
-            let authoredGuide;
-            try {
-                pushActivity("authoring IOSM.md from repository evidence...");
-                setVerifyLiveStatus("Authoring IOSM.md...");
-                await session.prompt(buildIosmGuideAuthoringPrompt(result), {
-                    expandPromptTemplates: false,
-                    skipIosmAutopilot: true,
-                    source: "interactive",
-                });
-                const guideAssistant = (() => {
-                    const messages = session.state.messages;
-                    for (let index = messages.length - 1; index >= 0; index--) {
-                        const message = messages[index];
-                        if (message.role === "assistant") {
-                            return message;
-                        }
+            if (option.suggested_files.length > 0) {
+                lines.push(`   files: ${option.suggested_files.slice(0, 8).join(", ")}`);
+            }
+            if (option.plan.length > 0) {
+                lines.push(`   first_step: ${option.plan[0]}`);
+            }
+        }
+        lines.push("");
+        lines.push("next_action:");
+        lines.push("  choose option 1/2/3, then pick Start with Swarm or Continue without Swarm");
+        return lines.join("\n");
+    }
+    buildSingularExecutionDraft(result, option, contract) {
+        const effectiveContract = contract ?? this.singularLastEffectiveContract ?? {};
+        const defaultQualityGates = [
+            "Targeted tests for changed flows pass.",
+            "No regressions in adjacent user paths.",
+            "Logs/metrics updated for the new behavior.",
+        ];
+        const defaultDoD = [
+            "Core behavior implemented and manually validated.",
+            "Automated coverage added for critical path.",
+            "Documentation/changelog updated for user-visible changes.",
+        ];
+        const qualityGates = (effectiveContract.quality_gates ?? []).length > 0
+            ? (effectiveContract.quality_gates ?? []).slice(0, 10)
+            : defaultQualityGates;
+        const definitionOfDone = (effectiveContract.definition_of_done ?? []).length > 0
+            ? (effectiveContract.definition_of_done ?? []).slice(0, 10)
+            : defaultDoD;
+        const constraints = (effectiveContract.constraints ?? []).slice(0, 10);
+        const scopeInclude = (effectiveContract.scope_include ?? []).slice(0, 10);
+        const scopeExclude = (effectiveContract.scope_exclude ?? []).slice(0, 10);
+        const risksFromOption = option.cons.slice(0, 6);
+        const files = option.suggested_files.slice(0, 14);
+        const planSteps = option.plan.length > 0 ? option.plan : ["Implement minimal working path for selected option."];
+        const lines = [
+            "# Singular Execution Plan",
+            "",
+            `Request: ${result.request}`,
+            `Selected option: ${option.id}. ${option.title}`,
+            `Decision context: recommendation=${result.recommendation}, complexity=${option.complexity}, blast_radius=${option.blast_radius}`,
+            ...(result.stageFit ? [`Stage fit: ${result.stageFit}`] : []),
+            ...(result.stageFitReason ? [`Stage fit reason: ${result.stageFitReason}`] : []),
+            ...(option.when_to_choose ? [`When to choose: ${option.when_to_choose}`] : []),
+            "",
+            "## 1) Scope and Boundaries",
+            "In scope:",
+            ...(scopeInclude.length > 0 ? scopeInclude.map((item) => `- ${item}`) : ["- Deliver selected option with minimal blast radius."]),
+            "Out of scope:",
+            ...(scopeExclude.length > 0 ? scopeExclude.map((item) => `- ${item}`) : ["- Broad refactors outside touched modules."]),
+            "Hard constraints:",
+            ...(constraints.length > 0 ? constraints.map((item) => `- ${item}`) : ["- Keep backward compatibility for existing behavior."]),
+            "",
+            "## 2) Implementation Phases",
+            "Phase A - Preparation",
+            "1. Confirm acceptance criteria and edge cases for the selected option.",
+            "2. Lock touched modules and define rollback strategy before coding.",
+            "Phase B - Implementation",
+            ...planSteps.map((step, index) => `${index + 1}. ${step}`),
+            "Phase C - Hardening",
+            "1. Run targeted regression checks on impacted flows.",
+            "2. Address review findings and update docs if behavior changed.",
+            "",
+            "## 3) Priority Files",
+        ];
+        lines.push(...(files.length > 0 ? files.map((filePath) => `- ${filePath}`) : ["- Determine target files during code scan."]));
+        lines.push("", "## 4) Validation and Quality Gates", "Functional checks:", "- Validate main user flow end-to-end.", "- Validate failure/edge path handling.", "Quality gates:", ...qualityGates.map((gate) => `- [ ] ${gate}`), "", "## 5) Risk Controls and Rollout", ...(result.impactAnalysis?.risks ? [`- Risk focus: ${result.impactAnalysis.risks}`] : ["- Risk focus: maintain safe rollout with quick rollback."]), ...(risksFromOption.length > 0 ? risksFromOption.map((risk) => `- [ ] Mitigate: ${risk}`) : ["- [ ] Track and mitigate newly discovered risks during implementation."]), "- [ ] Prepare rollback checkpoint before merge.", "- [ ] Use incremental rollout/feature-flag if blast radius is medium or high.", "", "## 6) Definition of Done", ...definitionOfDone.map((item) => `- [ ] ${item}`), "", "## 7) Delivery Notes", "- Keep commits scoped by phase (prep -> impl -> hardening).", "- Include tests and docs in the same delivery stream.");
+        return lines.join("\n");
+    }
+    resolveRecommendedSingularOptionId(result) {
+        if (result.recommendation === "defer") {
+            return "3";
+        }
+        if (result.recommendation === "implement_incrementally") {
+            const incremental = result.options.find((option) => /increment|mvp|phased/i.test(`${option.title} ${option.summary}`));
+            return incremental?.id ?? "1";
+        }
+        const nonDefer = result.options.find((option) => !/defer|later|postpone/i.test(`${option.title} ${option.summary}`));
+        return nonDefer?.id ?? "1";
+    }
+    async promptSingularDecision(result) {
+        const recommendedId = this.resolveRecommendedSingularOptionId(result);
+        const options = result.options.map((option) => {
+            const recommendedSuffix = option.id === recommendedId ? " (Recommended)" : "";
+            return `Option ${option.id}${recommendedSuffix}: ${option.title} [risk=${option.blast_radius}]`;
+        });
+        options.push("Close without decision");
+        const selected = await this.showExtensionSelector("/singular: choose next step", options);
+        if (!selected || selected === "Close without decision")
+            return;
+        const match = selected.match(/^Option\s+(\d+)/);
+        if (!match)
+            return;
+        const picked = result.options.find((option) => option.id === match[1]);
+        if (!picked)
+            return;
+        this.showCommandTextBlock("Singular Decision", [
+            `selected: ${picked.id}. ${picked.title}`,
+            `summary: ${picked.summary}`,
+            `complexity: ${picked.complexity}`,
+            `blast_radius: ${picked.blast_radius}`,
+            ...(picked.when_to_choose ? [`when_to_choose: ${picked.when_to_choose}`] : []),
+            "",
+            "plan:",
+            ...picked.plan.map((step, index) => `${index + 1}. ${step}`),
+            "",
+            "pros:",
+            ...picked.pros.map((item) => `- ${item}`),
+            "",
+            "cons:",
+            ...picked.cons.map((item) => `- ${item}`),
+        ].join("\n"));
+        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.");
+    }
+    showSingularLastSummary() {
+        const last = this.singularService.getLastRun();
+        if (!last) {
+            this.showWarning("No /singular analyses found yet.");
+            return;
+        }
+        this.showCommandTextBlock("Singular Last Run", [
+            `run_id: ${last.runId}`,
+            `generated_at: ${last.generatedAt ?? "unknown"}`,
+            `recommendation: ${last.recommendation ?? "unknown"}`,
+            `request: ${last.request ?? "unknown"}`,
+            `analysis_path: ${last.analysisPath}`,
+            ...(last.metaPath ? [`meta_path: ${last.metaPath}`] : []),
+        ].join("\n"));
+    }
+    async runSingularAnalysis(request) {
+        let effectiveContract = {};
+        try {
+            effectiveContract = this.contractService.getState().effective;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.showWarning(`Contract unavailable, continuing /singular without contract overlay: ${message}`);
+        }
+        this.singularLastEffectiveContract = effectiveContract;
+        try {
+            this.showStatus("Singular: preparing baseline scan...");
+            const baseline = await this.singularService.analyze({
+                request,
+                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, runtimeGuidance);
+                    if (enriched) {
+                        result = enriched;
+                    }
+                    else {
+                        this.showWarning("Agent feasibility pass returned incomplete output. Showing heuristic fallback.");
                     }
-                    return undefined;
-                })();
-                const guideText = extractAssistantText(guideAssistant);
-                const normalizedGuide = normalizeIosmGuideMarkdown(guideText);
-                if (normalizedGuide.trim().length > 0) {
-                    authoredGuide = normalizedGuide;
-                    pushActivity("IOSM.md authored by agent");
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    this.showWarning(`Agent feasibility pass failed. Showing heuristic fallback: ${message}`);
                 }
             }
-            catch {
-                pushActivity("agent IOSM.md authoring failed; using structured fallback");
+            this.singularService.saveAnalysis(result);
+            this.showStatus(`Singular analysis complete: ${result.runId}`);
+            this.showCommandTextBlock("Singular Analysis", this.formatSingularRunReport(result));
+            await this.promptSingularDecision(result);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.showError(`Singular analysis failed: ${message}`);
+        }
+    }
+    async handleSingularCommand(text) {
+        const args = this.parseSlashArgs(text).slice(1);
+        if (args.length === 0) {
+            this.showWarning("Usage: /singular <feature request>");
+            return;
+        }
+        const subcommand = (args[0] ?? "").toLowerCase();
+        if (subcommand === "help" || subcommand === "-h" || subcommand === "--help") {
+            this.showCommandTextBlock("Singular Help", [
+                "Usage:",
+                "  /singular <feature request>",
+                "  /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",
+            ].join("\n"));
+            return;
+        }
+        if (subcommand === "last" && args.length === 1) {
+            this.showSingularLastSummary();
+            return;
+        }
+        const request = args.join(" ").trim();
+        if (!request) {
+            this.showWarning("Usage: /singular <feature request>");
+            return;
+        }
+        await this.runSingularAnalysis(request);
+    }
+    parseCheckpointNameFromLabel(label) {
+        if (!label)
+            return undefined;
+        if (!label.startsWith(CHECKPOINT_LABEL_PREFIX))
+            return undefined;
+        const name = label.slice(CHECKPOINT_LABEL_PREFIX.length).trim();
+        return name.length > 0 ? name : undefined;
+    }
+    buildCheckpointLabel(name) {
+        return `${CHECKPOINT_LABEL_PREFIX}${name}`;
+    }
+    normalizeCheckpointName(raw) {
+        const normalized = raw.replace(/\s+/g, " ").trim();
+        if (!normalized)
+            return undefined;
+        if (normalized.length > 80)
+            return undefined;
+        return normalized;
+    }
+    getSessionCheckpoints() {
+        const active = new Map();
+        for (const entry of this.sessionManager.getEntries()) {
+            if (entry.type !== "label")
+                continue;
+            const name = this.parseCheckpointNameFromLabel(entry.label);
+            if (!name) {
+                active.delete(entry.targetId);
+                continue;
             }
-            let current;
-            let guidePath;
-            try {
-                const report = readIosmCycleReport(result.rootDir, cycleId);
+            active.set(entry.targetId, {
+                name,
+                targetId: entry.targetId,
+                labelEntryId: entry.id,
+                timestamp: entry.timestamp,
+            });
+        }
+        return [...active.values()].sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    }
+    buildDefaultCheckpointName(checkpoints) {
+        const used = new Set(checkpoints.map((checkpoint) => checkpoint.name.toLowerCase()));
+        let index = 1;
+        while (used.has(`cp-${index}`)) {
+            index += 1;
+        }
+        return `cp-${index}`;
+    }
+    formatCheckpointList(checkpoints) {
+        if (checkpoints.length === 0) {
+            return "No checkpoints yet.\nCreate one with: /checkpoint [name]";
+        }
+        const newestFirst = [...checkpoints].reverse();
+        const lines = newestFirst.map((checkpoint, index) => {
+            const target = this.sessionManager.getEntry(checkpoint.targetId);
+            const type = target?.type ?? "missing";
+            return `${index + 1}. ${checkpoint.name} -> ${checkpoint.targetId} (${type}) @ ${checkpoint.timestamp}`;
+        });
+        lines.push("");
+        lines.push("Usage: /rollback [name|index]");
+        return lines.join("\n");
+    }
+    formatCheckpointOption(index, checkpoint) {
+        const target = this.sessionManager.getEntry(checkpoint.targetId);
+        const type = target?.type ?? "missing";
+        return `${index}. ${checkpoint.name} -> ${checkpoint.targetId} (${type}) @ ${checkpoint.timestamp}`;
+    }
+    handleCheckpointCommand(text) {
+        const args = this.parseSlashArgs(text).slice(1);
+        const subcommand = args[0]?.toLowerCase();
+        const checkpoints = this.getSessionCheckpoints();
+        if (subcommand === "list" || subcommand === "ls") {
+            this.showCommandTextBlock("Checkpoints", this.formatCheckpointList(checkpoints));
+            return;
+        }
+        if (subcommand === "help" || subcommand === "-h" || subcommand === "--help") {
+            this.showCommandTextBlock("Checkpoint Help", ["Usage:", "  /checkpoint [name]", "  /checkpoint list", "", "Examples:", "  /checkpoint", "  /checkpoint before-refactor"].join("\n"));
+            return;
+        }
+        const leafId = this.sessionManager.getLeafId();
+        if (!leafId) {
+            this.showWarning("Cannot create checkpoint yet (session has no entries).");
+            return;
+        }
+        const requestedName = args.join(" ");
+        const name = requestedName ? this.normalizeCheckpointName(requestedName) : this.buildDefaultCheckpointName(checkpoints);
+        if (!name) {
+            this.showWarning("Invalid checkpoint name. Use 1-80 visible characters.");
+            return;
+        }
+        this.sessionManager.appendLabelChange(leafId, this.buildCheckpointLabel(name));
+        this.showStatus(`Checkpoint saved: ${name} (${leafId})`);
+    }
+    async handleRollbackCommand(text) {
+        const args = this.parseSlashArgs(text).slice(1);
+        const subcommand = args[0]?.toLowerCase();
+        const checkpoints = this.getSessionCheckpoints();
+        if (subcommand === "list" || subcommand === "ls") {
+            this.showCommandTextBlock("Checkpoints", this.formatCheckpointList(checkpoints));
+            return;
+        }
+        if (subcommand === "help" || subcommand === "-h" || subcommand === "--help") {
+            this.showCommandTextBlock("Rollback Help", [
+                "Usage:",
+                "  /rollback",
+                "  /rollback <name>",
+                "  /rollback <index>",
+                "",
+                "Examples:",
+                "  /rollback",
+                "  /rollback before-refactor",
+                "  /rollback 2",
+            ].join("\n"));
+            return;
+        }
+        if (checkpoints.length === 0) {
+            this.showWarning("No checkpoints available. Create one with /checkpoint.");
+            return;
+        }
+        const newestFirst = [...checkpoints].reverse();
+        const selector = args.join(" ").trim();
+        let target = newestFirst[0];
+        if (selector) {
+            const numeric = Number.parseInt(selector, 10);
+            if (Number.isFinite(numeric) && `${numeric}` === selector) {
+                target = newestFirst[numeric - 1];
+                if (!target) {
+                    this.showWarning(`Checkpoint index ${numeric} is out of range.`);
+                    return;
+                }
+            }
+            else {
+                target = newestFirst.find((checkpoint) => checkpoint.name === selector);
+                if (!target) {
+                    this.showWarning(`Checkpoint "${selector}" not found.`);
+                    return;
+                }
+            }
+        }
+        else {
+            const canShowInteractiveSelector = !!this.ui && !!this.editorContainer;
+            if (canShowInteractiveSelector) {
+                const options = newestFirst.map((checkpoint, index) => this.formatCheckpointOption(index + 1, checkpoint));
+                const picked = await this.showExtensionSelector("/rollback: choose checkpoint", options);
+                if (!picked) {
+                    this.showStatus("Rollback cancelled");
+                    return;
+                }
+                const selectedIndex = options.indexOf(picked);
+                if (selectedIndex >= 0) {
+                    target = newestFirst[selectedIndex];
+                }
+            }
+        }
+        if (!target) {
+            this.showWarning("No rollback target selected.");
+            return;
+        }
+        try {
+            const result = await this.session.navigateTree(target.targetId, { summarize: false });
+            if (result.cancelled || result.aborted) {
+                this.showStatus("Rollback cancelled");
+                return;
+            }
+            this.chatContainer.clear();
+            this.renderInitialMessages();
+            if (result.editorText && !this.editor.getText().trim()) {
+                this.editor.setText(result.editorText);
+            }
+            this.showStatus(`Rolled back to checkpoint: ${target.name}`);
+        }
+        catch (error) {
+            this.showError(error instanceof Error ? error.message : String(error));
+        }
+    }
+    async runDoctorInteractiveFixes(checks) {
+        const canShowInteractiveSelector = !!this.ui && !!this.editorContainer;
+        if (!canShowInteractiveSelector) {
+            return;
+        }
+        const hasModelIssues = checks.some((check) => (check.label === "Active model" || check.label === "Active model auth" || check.label === "Available models") &&
+            check.level === "fail");
+        const hasMcpIssues = checks.some((check) => check.label === "MCP servers" && check.level !== "ok");
+        const hasSemanticIssues = checks.some((check) => check.label === "Semantic index" && check.level !== "ok");
+        const hasContractIssues = checks.some((check) => check.label === "Contract state" && check.level !== "ok");
+        const hasResourceIssues = checks.some((check) => check.label === "Resources" && check.level !== "ok");
+        while (true) {
+            const options = [];
+            if (hasModelIssues) {
+                options.push("Open model selector");
+                options.push("Login provider");
+            }
+            if (this.mcpRuntime) {
+                if (hasMcpIssues) {
+                    options.push("Open MCP manager");
+                }
+                options.push("Refresh MCP runtime");
+            }
+            if (hasSemanticIssues) {
+                options.push("Open semantic manager");
+            }
+            if (hasContractIssues) {
+                options.push("Open contract manager");
+            }
+            if (this.permissionMode === "yolo") {
+                options.push("Set permissions mode to ask");
+            }
+            if (hasResourceIssues) {
+                options.push("Reload resources");
+            }
+            options.push("Show auth/models paths");
+            options.push("Close");
+            const selected = await this.showExtensionSelector("/doctor fixes", options);
+            if (!selected || selected === "Close") {
+                return;
+            }
+            if (selected === "Open model selector") {
+                await this.showModelProviderSelector();
+                return;
+            }
+            if (selected === "Login provider") {
+                await this.showOAuthSelector("login");
+                return;
+            }
+            if (selected === "Open MCP manager") {
+                await this.refreshMcpRuntimeAndSession();
+                this.showMcpSelector();
+                return;
+            }
+            if (selected === "Refresh MCP runtime") {
+                await this.refreshMcpRuntimeAndSession();
+                this.showStatus("MCP servers refreshed");
+                continue;
+            }
+            if (selected === "Open semantic manager") {
+                await this.handleSemanticCommand("/semantic");
+                return;
+            }
+            if (selected === "Open contract manager") {
+                await this.handleContractCommand("/contract");
+                return;
+            }
+            if (selected === "Set permissions mode to ask") {
+                this.permissionMode = "ask";
+                this.settingsManager.setPermissionMode("ask");
+                this.showStatus("Permissions: ask");
+                continue;
+            }
+            if (selected === "Reload resources") {
+                await this.handleReloadCommand();
+                return;
+            }
+            if (selected === "Show auth/models paths") {
+                const cwd = this.sessionManager.getCwd();
+                const agentDir = getAgentDir();
+                this.showCommandTextBlock("Runtime Paths", [
+                    `auth.json: ${getAuthPath()}`,
+                    `models.json: ${getModelsPath()}`,
+                    `contract(project): ${this.contractService.getProjectPath()}`,
+                    `singular(analyses): ${this.singularService.getAnalysesRoot()}`,
+                    `semantic(user): ${getSemanticConfigPath("user", cwd, agentDir)}`,
+                    `semantic(project): ${getSemanticConfigPath("project", cwd, agentDir)}`,
+                    `semantic(index): ${getSemanticIndexDir(cwd, agentDir)}`,
+                ].join("\n"));
+                continue;
+            }
+        }
+    }
+    async handleDoctorCommand(text) {
+        const args = this.parseSlashArgs(text).slice(1);
+        const outputJson = args.includes("--json");
+        const hooks = this.getHookPolicySummary();
+        const model = this.session.model;
+        const modelRegistry = this.session.modelRegistry;
+        const allModels = modelRegistry.getAll();
+        const availableModels = modelRegistry.getAvailable();
+        const modelLoadError = modelRegistry.getError();
+        const authProviders = modelRegistry.authStorage.list();
+        const hasModelAuth = model ? modelRegistry.authStorage.hasAuth(model.provider) : false;
+        const extensionErrors = this.session.resourceLoader.getExtensions().errors.length;
+        const skillDiagnostics = this.session.resourceLoader.getSkills().diagnostics.length;
+        const promptDiagnostics = this.session.resourceLoader.getPrompts().diagnostics.length;
+        const themeDiagnostics = this.session.resourceLoader.getThemes().diagnostics.length;
+        const mcpStatuses = this.mcpRuntime?.getServers() ?? [];
+        const mcpConfigErrors = this.mcpRuntime?.getErrors() ?? [];
+        const mcpConnected = mcpStatuses.filter((status) => status.state === "connected").length;
+        const mcpErrored = mcpStatuses.filter((status) => status.state === "error").length;
+        const mcpDisabled = mcpStatuses.filter((status) => !status.enabled).length;
+        const cliToolStatuses = resolveDoctorCliToolStatuses();
+        const missingCliTools = cliToolStatuses.filter((status) => !status.available).map((status) => status.tool);
+        let semanticStatus;
+        let semanticStatusError;
+        try {
+            semanticStatus = await this.createSemanticRuntime().status();
+        }
+        catch (error) {
+            semanticStatusError = error instanceof Error ? error.message : String(error);
+        }
+        let contractState;
+        let contractStateError;
+        try {
+            contractState = this.contractService.getState();
+        }
+        catch (error) {
+            contractStateError = error instanceof Error ? error.message : String(error);
+        }
+        const checks = [];
+        const addCheck = (level, label, detail, fix) => checks.push({ level, label, detail, fix });
+        if (!model) {
+            addCheck("fail", "Active model", "No active model selected", "Run /model and pick a model.");
+        }
+        else if (!hasModelAuth) {
+            addCheck("fail", "Active model auth", `Model ${model.provider}/${model.id} has no auth configured`, `Run /login ${model.provider} or set API key env vars.`);
+        }
+        else {
+            addCheck("ok", "Active model", `${model.provider}/${model.id}`);
+        }
+        if (availableModels.length === 0) {
+            addCheck("fail", "Available models", "No models currently have valid auth", "Run /login or configure API keys.");
+        }
+        else {
+            addCheck("ok", "Available models", `${availableModels.length}/${allModels.length} ready`);
+        }
+        if (modelLoadError) {
+            addCheck("warn", "models.json", modelLoadError.split("\n")[0] ?? modelLoadError, `Inspect ${getModelsPath()}.`);
+        }
+        else {
+            addCheck("ok", "models.json", "Loaded without schema/runtime errors");
+        }
+        if (!fs.existsSync(getAuthPath())) {
+            addCheck("warn", "auth.json", `Missing ${getAuthPath()}`, "Run /login to create credentials.");
+        }
+        else {
+            addCheck("ok", "auth.json", `${authProviders.length} provider credential(s) stored`);
+        }
+        if (!this.mcpRuntime) {
+            addCheck("warn", "MCP runtime", "Unavailable in this session");
+        }
+        else if (mcpStatuses.length === 0) {
+            addCheck("warn", "MCP servers", "No MCP servers configured", "Use /mcp add or iosm mcp add ...");
+        }
+        else if (mcpErrored > 0 || mcpConfigErrors.length > 0) {
+            addCheck("warn", "MCP servers", `${mcpConnected} connected, ${mcpErrored} error, ${mcpDisabled} disabled`, "Open /mcp to reconnect or inspect server errors.");
+        }
+        else {
+            addCheck("ok", "MCP servers", `${mcpConnected} connected, ${mcpDisabled} disabled`);
+        }
+        if (semanticStatusError) {
+            addCheck("fail", "Semantic index", semanticStatusError, "Run /semantic setup and retry /semantic status.");
+        }
+        else if (!semanticStatus) {
+            addCheck("warn", "Semantic index", "Status unavailable", "Run /semantic setup.");
+        }
+        else if (!semanticStatus.configured) {
+            addCheck("warn", "Semantic index", "Not configured", `Run /semantic setup (user: ${semanticStatus.configPathUser} or project: ${semanticStatus.configPathProject}).`);
+        }
+        else if (!semanticStatus.enabled) {
+            addCheck("warn", "Semantic index", "Configured but disabled", "Enable semanticSearch.enabled or rerun /semantic setup.");
+        }
+        else if (!semanticStatus.indexed) {
+            addCheck("warn", "Semantic index", "Configured but index is missing", "Run /semantic index.");
+        }
+        else if (semanticStatus.stale) {
+            const requiresRebuild = semanticStatus.staleReason === "provider_changed" ||
+                semanticStatus.staleReason === "chunking_changed" ||
+                semanticStatus.staleReason === "index_filters_changed" ||
+                semanticStatus.staleReason === "dimension_mismatch";
+            addCheck("warn", "Semantic index", `Indexed but stale${semanticStatus.staleReason ? ` (${semanticStatus.staleReason})` : ""}`, requiresRebuild ? "Run /semantic rebuild." : "Run /semantic index.");
+        }
+        else {
+            addCheck("ok", "Semantic index", `${semanticStatus.provider}/${semanticStatus.model} · auto_index=${semanticStatus.autoIndex ? "on" : "off"} · files=${semanticStatus.files} chunks=${semanticStatus.chunks}`);
+        }
+        if (contractStateError) {
+            addCheck("fail", "Contract state", contractStateError, "Fix .iosm/contract.json or run /contract clear --scope project.");
+        }
+        else if (!contractState) {
+            addCheck("warn", "Contract state", "Unavailable", "Run /contract show to inspect state.");
+        }
+        else if (!contractState.hasProjectFile && Object.keys(contractState.sessionOverlay).length === 0) {
+            addCheck("warn", "Contract state", "No project/session contract active", "Run /contract to define constraints and quality gates.");
+        }
+        else {
+            addCheck("ok", "Contract state", `project=${contractState.hasProjectFile ? "yes" : "no"} session_keys=${Object.keys(contractState.sessionOverlay).length} effective_keys=${Object.keys(contractState.effective).length}`);
+        }
+        addCheck("ok", "Singular analyzer", "Available via /singular <request>");
+        if (missingCliTools.length > 0) {
+            addCheck("warn", "CLI toolchain", `${cliToolStatuses.length - missingCliTools.length}/${cliToolStatuses.length} available (missing: ${missingCliTools.join(", ")})`, `Install missing CLI tools: ${missingCliTools.join(", ")}.`);
+        }
+        else {
+            addCheck("ok", "CLI toolchain", `${cliToolStatuses.length}/${cliToolStatuses.length} available`);
+        }
+        if (extensionErrors > 0 || skillDiagnostics > 0 || promptDiagnostics > 0 || themeDiagnostics > 0) {
+            addCheck("warn", "Resources", `extensions:${extensionErrors} skills:${skillDiagnostics} prompts:${promptDiagnostics} themes:${themeDiagnostics}`, "Run /reload and inspect warnings shown in the chat.");
+        }
+        else {
+            addCheck("ok", "Resources", "No extension/skill/prompt/theme diagnostics");
+        }
+        addCheck(this.permissionMode === "yolo" ? "warn" : "ok", "Permissions", `mode=${this.permissionMode}, allowRules=${this.permissionAllowRules.length}, denyRules=${this.permissionDenyRules.length}`, this.permissionMode === "yolo" ? "Switch to /permissions ask for safer execution." : undefined);
+        addCheck(process.env[ENV_OFFLINE] ? "warn" : "ok", "Environment", `offline=${process.env[ENV_OFFLINE] ? "on" : "off"}, sessionTrace=${isSessionTraceEnabled() ? "on" : "off"}`, process.env[ENV_OFFLINE] ? "Unset IOSM_OFFLINE/PI_OFFLINE when network access is required." : undefined);
+        addCheck("ok", "Hooks", hooks
+            ? `U${hooks.userPromptSubmit}/P${hooks.preToolUse}/T${hooks.postToolUse}/S${hooks.stop}`
+            : "No hooks loaded");
+        const recommendations = [...new Set(checks.map((check) => check.fix).filter((fix) => !!fix))];
+        if (outputJson) {
+            this.showCommandJsonBlock("Doctor Report", {
+                timestamp: new Date().toISOString(),
+                cwd: this.sessionManager.getCwd(),
+                sessionFile: this.sessionManager.getSessionFile() ?? null,
+                activeProfile: this.activeProfileName,
+                externalCliTools: cliToolStatuses,
+                checks,
+                recommendations,
+            });
+            return;
+        }
+        const lines = [];
+        lines.push(`Timestamp: ${new Date().toISOString()}`);
+        lines.push(`CWD: ${this.sessionManager.getCwd()}`);
+        lines.push(`Session: ${this.sessionManager.getSessionFile() ?? "in-memory"}`);
+        lines.push(`Profile: ${this.activeProfileName}`);
+        lines.push("");
+        for (const check of checks) {
+            const prefix = check.level === "ok" ? "[OK]" : check.level === "warn" ? "[WARN]" : "[FAIL]";
+            lines.push(`${prefix} ${check.label}: ${check.detail}`);
+        }
+        lines.push("");
+        lines.push("External CLI tools:");
+        for (const status of cliToolStatuses) {
+            const prefix = status.available ? "[OK]" : "[WARN]";
+            const sourceLabel = status.source === "missing"
+                ? "missing"
+                : `${status.source}${status.command ? ` (${status.command})` : ""}`;
+            lines.push(`${prefix} ${status.tool}: ${sourceLabel}`);
+            if (!status.available && status.hint) {
+                lines.push(`       fix: ${status.hint}`);
+            }
+        }
+        if (recommendations.length > 0) {
+            lines.push("");
+            lines.push("Recommended actions:");
+            for (const recommendation of recommendations) {
+                lines.push(`- ${recommendation}`);
+            }
+        }
+        lines.push("");
+        lines.push("Tip: /doctor --json");
+        this.showCommandTextBlock("Doctor Report", lines.join("\n"));
+        const wantsInteractiveFixes = !args.includes("--no-fix");
+        if (wantsInteractiveFixes) {
+            await this.runDoctorInteractiveFixes(checks);
+        }
+    }
+    showCommandTextBlock(title, body) {
+        this.chatContainer.addChild(new Spacer(1));
+        this.chatContainer.addChild(new DynamicBorder());
+        this.chatContainer.addChild(new Text(theme.bold(theme.fg("accent", title)), 1, 0));
+        this.chatContainer.addChild(new Spacer(1));
+        this.chatContainer.addChild(new Text(body, 1, 0));
+        this.chatContainer.addChild(new DynamicBorder());
+        this.ui.requestRender();
+    }
+    showCommandJsonBlock(title, value) {
+        const json = JSON.stringify(value, null, 2);
+        this.chatContainer.addChild(new Spacer(1));
+        this.chatContainer.addChild(new DynamicBorder());
+        this.chatContainer.addChild(new Text(theme.bold(theme.fg("accent", title)), 1, 0));
+        this.chatContainer.addChild(new Spacer(1));
+        this.chatContainer.addChild(new Markdown(`\`\`\`json\n${json}\n\`\`\``, 1, 1, this.getMarkdownThemeWithSettings()));
+        this.chatContainer.addChild(new DynamicBorder());
+        this.ui.requestRender();
+    }
+    async runIosmInitAgentVerification(result, targetDir, onEvent) {
+        if (!result.cycle) {
+            return {
+                completed: false,
+                skippedReason: "No cycle scaffold was available for verification.",
+            };
+        }
+        const cycleId = result.cycle.cycleId;
+        process.env[ENV_SESSION_TRACE] = "1";
+        process.env.PI_SESSION_TRACE = "1";
+        const agentDir = getAgentDir();
+        const settingsManager = SettingsManager.create(targetDir, agentDir);
+        const settingsErrors = settingsManager.drainErrors();
+        for (const { scope, error } of settingsErrors) {
+            this.showWarning(`Init verify warning (${scope} settings): ${error.message}`);
+        }
+        const authStorage = AuthStorage.create();
+        const modelRegistry = new ModelRegistry(authStorage, getModelsPath());
+        const resourceLoader = new DefaultResourceLoader({
+            cwd: targetDir,
+            agentDir,
+            settingsManager,
+            noExtensions: true,
+        });
+        await resourceLoader.reload();
+        const { session, modelFallbackMessage } = await createAgentSession({
+            cwd: targetDir,
+            sessionManager: SessionManager.inMemory(),
+            settingsManager,
+            authStorage,
+            modelRegistry,
+            resourceLoader,
+        });
+        let toolExecutions = 0;
+        const activityLog = [];
+        const pushActivity = (line, persist = false) => {
+            activityLog.push(line);
+            if (activityLog.length > 30) {
+                activityLog.shift();
+            }
+            if (persist) {
+                this.showProgressLine(`IOSM init verify: ${line}`);
+            }
+        };
+        const setVerifyLiveStatus = (message) => {
+            this.setWorkingMessage(`${message} (${appKey(this.keybindings, "interrupt")} to interrupt)`);
+        };
+        const unsubscribe = session.subscribe((event) => {
+            onEvent?.(event);
+            if (event.type === "turn_start") {
+                pushActivity("agent turn started");
+                setVerifyLiveStatus("Verifying workspace...");
+                return;
+            }
+            if (event.type !== "tool_execution_start") {
+                return;
+            }
+            toolExecutions += 1;
+            if (event.toolName === "bash") {
+                const commandRaw = event.args && typeof event.args === "object" && "command" in event.args
+                    ? String(event.args.command ?? "")
+                    : "";
+                const preview = commandRaw.replace(/\s+/g, " ").trim().slice(0, 68);
+                const line = `bash #${toolExecutions}${preview ? ` ${preview}${commandRaw.length > 68 ? "..." : ""}` : ""}`;
+                pushActivity(line);
+                setVerifyLiveStatus(`Verifying workspace · ${line}`);
+                return;
+            }
+            const line = `${event.toolName} #${toolExecutions}`;
+            pushActivity(line);
+            setVerifyLiveStatus(`Verifying workspace · ${line}`);
+        });
+        this.iosmVerificationSession = session;
+        try {
+            if (!session.model) {
+                return {
+                    completed: false,
+                    skippedReason: modelFallbackMessage ??
+                        "No model available for agent verification. Configure /login or an API key, then re-run /init.",
+                    activityLog,
+                };
+            }
+            const timeoutMs = 180_000;
+            const startedAt = Date.now();
+            const heartbeatMs = 10_000;
+            let nextPersistentHeartbeatSec = 30;
+            let timeoutHandle;
+            let heartbeatHandle;
+            try {
+                pushActivity("waiting for model response...", true);
+                setVerifyLiveStatus("Waiting for model response...");
+                heartbeatHandle = setInterval(() => {
+                    const elapsedSec = Math.round((Date.now() - startedAt) / 1000);
+                    if (toolExecutions === 0 && elapsedSec >= nextPersistentHeartbeatSec) {
+                        pushActivity(`still waiting for model response (${elapsedSec}s)`, true);
+                        nextPersistentHeartbeatSec += 30;
+                    }
+                    setVerifyLiveStatus(toolExecutions === 0
+                        ? `Waiting for model response... ${elapsedSec}s`
+                        : `Verifying workspace... ${elapsedSec}s · tool calls=${toolExecutions}`);
+                }, heartbeatMs);
+                await Promise.race([
+                    session.prompt(buildIosmAgentVerificationPrompt(result), {
+                        expandPromptTemplates: false,
+                        skipIosmAutopilot: true,
+                        source: "interactive",
+                    }),
+                    new Promise((_resolve, reject) => {
+                        timeoutHandle = setTimeout(() => {
+                            reject(new Error(`Verifier timeout after ${Math.round(timeoutMs / 1000)}s.`));
+                        }, timeoutMs);
+                    }),
+                ]);
+            }
+            finally {
+                if (timeoutHandle) {
+                    clearTimeout(timeoutHandle);
+                }
+                if (heartbeatHandle) {
+                    clearInterval(heartbeatHandle);
+                }
+            }
+            const messages = session.state.messages;
+            let lastAssistant;
+            for (let index = messages.length - 1; index >= 0; index--) {
+                const message = messages[index];
+                if (message.role === "assistant") {
+                    lastAssistant = message;
+                    break;
+                }
+            }
+            if (lastAssistant &&
+                (lastAssistant.stopReason === "error" || lastAssistant.stopReason === "aborted")) {
+                pushActivity(`agent finished with ${lastAssistant.stopReason}`);
+                if (lastAssistant.stopReason === "aborted") {
+                    return {
+                        completed: false,
+                        cancelled: true,
+                        skippedReason: "Cancelled by user.",
+                        tracePath: session.sessionTracePath ??
+                            (isSessionTraceEnabled() ? getSessionTracePath(session.sessionManager.getSessionId()) : undefined),
+                        activityLog,
+                    };
+                }
+                return {
+                    completed: false,
+                    error: lastAssistant.errorMessage ?? `Verifier finished with ${lastAssistant.stopReason}.`,
+                    tracePath: session.sessionTracePath ??
+                        (isSessionTraceEnabled() ? getSessionTracePath(session.sessionManager.getSessionId()) : undefined),
+                    activityLog,
+                };
+            }
+            let authoredGuide;
+            try {
+                pushActivity("authoring IOSM.md from repository evidence...");
+                setVerifyLiveStatus("Authoring IOSM.md...");
+                await session.prompt(buildIosmGuideAuthoringPrompt(result), {
+                    expandPromptTemplates: false,
+                    skipIosmAutopilot: true,
+                    source: "interactive",
+                });
+                const guideAssistant = (() => {
+                    const messages = session.state.messages;
+                    for (let index = messages.length - 1; index >= 0; index--) {
+                        const message = messages[index];
+                        if (message.role === "assistant") {
+                            return message;
+                        }
+                    }
+                    return undefined;
+                })();
+                const guideText = extractAssistantText(guideAssistant);
+                const normalizedGuide = normalizeIosmGuideMarkdown(guideText);
+                if (normalizedGuide.trim().length > 0) {
+                    authoredGuide = normalizedGuide;
+                    pushActivity("IOSM.md authored by agent");
+                }
+            }
+            catch {
+                pushActivity("agent IOSM.md authoring failed; using structured fallback");
+            }
+            let current;
+            let guidePath;
+            try {
+                const report = readIosmCycleReport(result.rootDir, cycleId);
                 current = createMetricSnapshot(report);
                 if (authoredGuide) {
                     guidePath = getIosmGuidePath(targetDir);
                     fs.writeFileSync(guidePath, authoredGuide, "utf8");
                 }
                 else {
-                    guidePath = writeIosmGuideDocument({
-                        rootDir: targetDir,
-                        cycleId,
-                        assessmentSource: "verified",
-                        metrics: report.metrics,
-                        iosmIndex: report.iosm_index,
-                        decisionConfidence: report.decision_confidence,
-                        goals: report.goals,
-                        filesAnalyzed: result.analysis.files_analyzed,
-                        sourceFileCount: result.analysis.source_file_count,
-                        testFileCount: result.analysis.test_file_count,
-                        docFileCount: result.analysis.doc_file_count,
-                    }, true).path;
+                    guidePath = writeIosmGuideDocument({
+                        rootDir: targetDir,
+                        cycleId,
+                        assessmentSource: "verified",
+                        metrics: report.metrics,
+                        iosmIndex: report.iosm_index,
+                        decisionConfidence: report.decision_confidence,
+                        goals: report.goals,
+                        filesAnalyzed: result.analysis.files_analyzed,
+                        sourceFileCount: result.analysis.source_file_count,
+                        testFileCount: result.analysis.test_file_count,
+                        docFileCount: result.analysis.doc_file_count,
+                    }, true).path;
+                }
+            }
+            catch {
+                current = undefined;
+                guidePath = undefined;
+            }
+            let historyPath;
+            try {
+                const history = recordIosmCycleHistory(result.rootDir, cycleId);
+                historyPath = history.historyPath;
+            }
+            catch {
+                historyPath = undefined;
+            }
+            pushActivity(`completed (${toolExecutions} tool calls)`, true);
+            return {
+                completed: true,
+                current,
+                historyPath,
+                guidePath,
+                toolCalls: toolExecutions,
+                tracePath: session.sessionTracePath ??
+                    (isSessionTraceEnabled() ? getSessionTracePath(session.sessionManager.getSessionId()) : undefined),
+                activityLog,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (isAbortLikeMessage(message)) {
+                pushActivity("cancelled by user", true);
+                return {
+                    completed: false,
+                    cancelled: true,
+                    skippedReason: "Cancelled by user.",
+                    activityLog,
+                };
+            }
+            pushActivity(`failed (${message})`);
+            this.showWarning(`IOSM init verify: failed (${message})`);
+            return {
+                completed: false,
+                error: message,
+                activityLog,
+            };
+        }
+        finally {
+            try {
+                if (session.isStreaming) {
+                    await session.abort();
+                }
+            }
+            catch {
+                // Best-effort shutdown to avoid a stuck verification loader.
+            }
+            if (this.iosmVerificationSession === session) {
+                this.iosmVerificationSession = undefined;
+            }
+            unsubscribe();
+            session.dispose();
+            if (this.loadingAnimation) {
+                this.loadingAnimation.stop();
+                this.loadingAnimation = undefined;
+            }
+            this.statusContainer.clear();
+            this.pendingWorkingMessage = undefined;
+            this.ui.requestRender();
+        }
+    }
+    getLastAssistantMessage() {
+        return this.session.messages
+            .slice()
+            .reverse()
+            .find((message) => {
+            if (message.role !== "assistant") {
+                return false;
+            }
+            return !(message.stopReason === "aborted" && message.content.length === 0);
+        });
+    }
+    sanitizeAssistantDisplayMessage(message) {
+        const hideAllTextForOrchestration = this.activeAssistantOrchestrationContext;
+        let changed = false;
+        const nextContent = message.content.map((content) => {
+            if (content.type !== "text")
+                return content;
+            if (hideAllTextForOrchestration) {
+                if (content.text !== "") {
+                    changed = true;
+                }
+                return { ...content, text: "" };
+            }
+            return content;
+        });
+        return changed ? { ...message, content: nextContent } : message;
+    }
+    resolveMentionedAgent(text) {
+        const cwd = this.sessionManager.getCwd();
+        const loaded = loadCustomSubagents({ cwd, agentDir: getAgentDir() });
+        if (loaded.agents.length === 0)
+            return undefined;
+        const matches = text.matchAll(/(?:^|\s)@([^\s]+)/g);
+        for (const match of matches) {
+            const candidate = (match[1] ?? "").trim();
+            const resolved = resolveCustomSubagentReference(candidate, loaded.agents);
+            if (resolved) {
+                return resolved;
+            }
+        }
+        return undefined;
+    }
+    isCapabilityQuery(text) {
+        const normalized = text.toLowerCase().trim();
+        if (!normalized)
+            return true;
+        return (normalized === "?" ||
+            normalized === "help" ||
+            normalized === "--help" ||
+            normalized === "/help" ||
+            normalized === "/capabilities" ||
+            normalized === "capabilities");
+    }
+    async promptWithTaskFallback(userInput) {
+        const mentionedAgent = this.resolveMentionedAgent(userInput);
+        if (mentionedAgent) {
+            const cleaned = userInput.replace(/(?:^|\s)@[^\s]+/g, " ").trim();
+            if (this.isCapabilityQuery(cleaned)) {
+                const cwd = this.sessionManager.getCwd();
+                const loaded = loadCustomSubagents({ cwd, agentDir: getAgentDir() });
+                const agent = loaded.agents.find((item) => item.name === mentionedAgent);
+                if (agent) {
+                    const capabilityPrompt = [
+                        "<agent_capability_query>",
+                        `agent_name: ${agent.name}`,
+                        `description: ${agent.description}`,
+                        `profile: ${agent.profile ?? "full"}`,
+                        `model: ${agent.model ?? "default"}`,
+                        `background: ${agent.background ? "true" : "false"}`,
+                        `tools: ${agent.tools?.join(", ") ?? "default profile tools"}`,
+                        `disallowed_tools: ${agent.disallowedTools?.join(", ") ?? "none"}`,
+                        "",
+                        "agent_instructions:",
+                        agent.instructions,
+                        "",
+                        `user_question: ${cleaned || "what can you do?"}`,
+                        "Answer normally and concisely in plain language. Do not run task tool for this query.",
+                        "</agent_capability_query>",
+                    ].join("\n");
+                    await this.session.prompt(capabilityPrompt, {
+                        expandPromptTemplates: false,
+                        source: "interactive",
+                    });
+                    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="${mentionMode}" agents="1"${mentionMaxParallel ? ` max_parallel="${mentionMaxParallel}"` : ""}>`,
+                `- agent 1: profile=${this.activeProfileName} cwd=${this.sessionManager.getCwd()} agent=${mentionedAgent}`,
+                `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, {
+                expandPromptTemplates: false,
+                source: "interactive",
+            });
+            return;
+        }
+        await this.session.prompt(userInput);
+    }
+    createIosmVerificationEventBridge(options) {
+        const loaderMessage = options?.loaderMessage ?? `Verifying workspace... (${appKey(this.keybindings, "interrupt")} to interrupt)`;
+        const hideAssistantText = options?.hideAssistantText === true;
+        let verifyStreamingComponent;
+        let verifyStreamingMessage;
+        const verifyPendingTools = new Map();
+        return (event) => {
+            switch (event.type) {
+                case "agent_start":
+                    if (this.loadingAnimation) {
+                        this.loadingAnimation.stop();
+                    }
+                    this.statusContainer.clear();
+                    this.loadingAnimation = new DecryptLoader(this.ui, (s) => theme.fg("accent", s), (t) => theme.fg("muted", t), loaderMessage);
+                    this.statusContainer.addChild(this.loadingAnimation);
+                    break;
+                case "message_start":
+                    if (event.message.role === "assistant" && !hideAssistantText) {
+                        verifyStreamingComponent = new AssistantMessageComponent(undefined, false, this.getMarkdownThemeWithSettings());
+                        verifyStreamingMessage = event.message;
+                        this.chatContainer.addChild(verifyStreamingComponent);
+                        verifyStreamingComponent.updateContent(verifyStreamingMessage);
+                    }
+                    break;
+                case "message_update":
+                    if (verifyStreamingComponent && event.message.role === "assistant") {
+                        verifyStreamingMessage = event.message;
+                        verifyStreamingComponent.updateContent(verifyStreamingMessage);
+                        for (const content of verifyStreamingMessage.content) {
+                            if (content.type === "toolCall" && !verifyPendingTools.has(content.id)) {
+                                const component = new ToolExecutionComponent(content.name, content.arguments, { showImages: this.settingsManager.getShowImages() }, this.getRegisteredToolDefinition(content.name), this.ui);
+                                component.setExpanded(this.toolOutputExpanded);
+                                this.chatContainer.addChild(component);
+                                verifyPendingTools.set(content.id, component);
+                            }
+                        }
+                    }
+                    break;
+                case "message_end":
+                    if (verifyStreamingComponent && event.message.role === "assistant") {
+                        verifyStreamingMessage = event.message;
+                        verifyStreamingComponent.updateContent(verifyStreamingMessage);
+                        verifyStreamingComponent = undefined;
+                        verifyStreamingMessage = undefined;
+                    }
+                    break;
+                case "tool_execution_start":
+                    if (!verifyPendingTools.has(event.toolCallId)) {
+                        const component = new ToolExecutionComponent(event.toolName, event.args, { showImages: this.settingsManager.getShowImages() }, this.getRegisteredToolDefinition(event.toolName), this.ui);
+                        component.setExpanded(this.toolOutputExpanded);
+                        this.chatContainer.addChild(component);
+                        verifyPendingTools.set(event.toolCallId, component);
+                    }
+                    break;
+                case "tool_execution_update": {
+                    const component = verifyPendingTools.get(event.toolCallId);
+                    if (component) {
+                        component.updateResult({ ...event.partialResult, isError: false }, true);
+                    }
+                    break;
+                }
+                case "tool_execution_end": {
+                    const component = verifyPendingTools.get(event.toolCallId);
+                    if (component) {
+                        component.updateResult({ ...event.result, isError: event.isError });
+                        verifyPendingTools.delete(event.toolCallId);
+                    }
+                    break;
+                }
+                case "agent_end":
+                    if (this.loadingAnimation) {
+                        this.loadingAnimation.stop();
+                        this.loadingAnimation = undefined;
+                        this.statusContainer.clear();
+                    }
+                    verifyPendingTools.clear();
+                    break;
+            }
+            this.ui.requestRender();
+        };
+    }
+    resolveIosmSnapshot(result, verification) {
+        let snapshot = verification?.current;
+        if (!snapshot && result.cycle) {
+            try {
+                snapshot = createMetricSnapshot(readIosmCycleReport(result.rootDir, result.cycle.cycleId));
+            }
+            catch {
+                snapshot = undefined;
+            }
+        }
+        return (snapshot ?? {
+            metrics: result.analysis.metrics,
+            iosm_index: null,
+            decision_confidence: null,
+        });
+    }
+    async runIosmRefreshPass(options) {
+        const initResult = await initIosmWorkspace({ cwd: options.cwd, force: options.force });
+        let verification;
+        if (options.agentVerify) {
+            verification = await this.runIosmInitAgentVerification(initResult, options.cwd, this.createIosmVerificationEventBridge());
+        }
+        let cycleDecision;
+        if (initResult.cycle) {
+            try {
+                cycleDecision = inspectIosmCycle(initResult.rootDir, initResult.cycle.cycleId).decision;
+            }
+            catch {
+                cycleDecision = undefined;
+            }
+        }
+        return {
+            initResult,
+            verification,
+            snapshot: this.resolveIosmSnapshot(initResult, verification),
+            guidePath: verification?.guidePath ?? getIosmGuidePath(initResult.rootDir),
+            cycleDecision,
+        };
+    }
+    parseIosmAutomationSlashCommand(text) {
+        const args = this.parseSlashArgs(text).slice(1);
+        let targetIndex;
+        let maxIterations;
+        let forceInit = false;
+        for (let index = 0; index < args.length; index++) {
+            const arg = args[index];
+            if (arg === "--force-init" || arg === "--force") {
+                forceInit = true;
+                continue;
+            }
+            if (arg === "--max-iterations") {
+                const nextValue = args[index + 1];
+                const parsed = nextValue ? Number.parseInt(nextValue, 10) : Number.NaN;
+                if (!Number.isInteger(parsed) || parsed < 1) {
+                    this.showWarning('Usage: /iosm [target-index] [--max-iterations N] [--force-init]');
+                    return undefined;
+                }
+                maxIterations = parsed;
+                index += 1;
+                continue;
+            }
+            if (arg.startsWith("-")) {
+                this.showWarning(`Unknown option for /iosm: ${arg}`);
+                this.showWarning('Usage: /iosm [target-index] [--max-iterations N] [--force-init]');
+                return undefined;
+            }
+            if (targetIndex !== undefined) {
+                this.showWarning(`Unexpected argument for /iosm: ${arg}`);
+                this.showWarning('Usage: /iosm [target-index] [--max-iterations N] [--force-init]');
+                return undefined;
+            }
+            const parsed = Number.parseFloat(arg);
+            if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+                this.showWarning(`Invalid target index for /iosm: ${arg}`);
+                this.showWarning("Target index must be a number in the range 0.0 to 1.0.");
+                return undefined;
+            }
+            targetIndex = parsed;
+        }
+        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));
+                    }
                 }
             }
-            catch {
-                current = undefined;
-                guidePath = undefined;
+            else if (selected === "Open manual /contract editor") {
+                await this.runContractInteractiveMenu();
             }
-            let historyPath;
-            try {
-                const history = recordIosmCycleHistory(result.rootDir, cycleId);
-                historyPath = history.historyPath;
+            const state = this.getContractStateSafe();
+            if (!state)
+                return undefined;
+            if (this.isEffectiveContractReady(state.effective)) {
+                return state.effective;
             }
-            catch {
-                historyPath = undefined;
+            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";
             }
-            pushActivity(`completed (${toolExecutions} tool calls)`, true);
-            return {
-                completed: true,
-                current,
-                historyPath,
-                guidePath,
-                toolCalls: toolExecutions,
-                tracePath: session.sessionTracePath ??
-                    (isSessionTraceEnabled() ? getSessionTracePath(session.sessionManager.getSessionId()) : undefined),
-                activityLog,
-            };
+            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);
-            if (isAbortLikeMessage(message)) {
-                pushActivity("cancelled by user", true);
-                return {
-                    completed: false,
-                    cancelled: true,
-                    skippedReason: "Cancelled by user.",
-                    activityLog,
-                };
+            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 };
             }
-            pushActivity(`failed (${message})`);
-            this.showWarning(`IOSM init verify: failed (${message})`);
+            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 {
-                completed: false,
-                error: message,
-                activityLog,
+                subcommand: "watch",
+                runId: rest[0],
             };
         }
-        finally {
-            try {
-                if (session.isStreaming) {
-                    await session.abort();
+        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;
             }
-            catch {
-                // Best-effort shutdown to avoid a stuck verification loader.
+            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 (this.iosmVerificationSession === session) {
-                this.iosmVerificationSession = undefined;
+            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;
             }
-            unsubscribe();
-            session.dispose();
-            if (this.loadingAnimation) {
-                this.loadingAnimation.stop();
-                this.loadingAnimation = undefined;
+            if (token.startsWith("-")) {
+                this.showWarning(`Unknown option for /swarm ${subcommand}: ${token}`);
+                return undefined;
             }
-            this.statusContainer.clear();
-            this.pendingWorkingMessage = undefined;
-            this.ui.requestRender();
-        }
-    }
-    getLastAssistantMessage() {
-        return this.session.messages
-            .slice()
-            .reverse()
-            .find((message) => {
-            if (message.role !== "assistant") {
-                return false;
+            if (subcommand === "from-singular" && !fromSingularRunId) {
+                fromSingularRunId = token;
+                continue;
             }
-            return !(message.stopReason === "aborted" && message.content.length === 0);
-        });
-    }
-    sanitizeAssistantDisplayMessage(message) {
-        const hideAllTextForOrchestration = this.activeAssistantOrchestrationContext;
-        let changed = false;
-        const nextContent = message.content.map((content) => {
-            if (content.type !== "text")
-                return content;
-            if (hideAllTextForOrchestration) {
-                if (content.text !== "") {
-                    changed = true;
-                }
-                return { ...content, text: "" };
+            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 content;
-        });
-        return changed ? { ...message, content: nextContent } : message;
-    }
-    resolveMentionedAgent(text) {
-        const cwd = this.sessionManager.getCwd();
-        const loaded = loadCustomSubagents({ cwd, agentDir: getAgentDir() });
-        if (loaded.agents.length === 0)
-            return undefined;
-        const matches = text.matchAll(/(?:^|\s)@([^\s]+)/g);
-        for (const match of matches) {
-            const candidate = (match[1] ?? "").trim();
-            const resolved = resolveCustomSubagentReference(candidate, loaded.agents);
-            if (resolved) {
-                return resolved;
+            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;
     }
-    isCapabilityQuery(text) {
-        const normalized = text.toLowerCase().trim();
-        if (!normalized)
-            return true;
-        return (normalized === "?" ||
-            normalized === "help" ||
-            normalized === "--help" ||
-            normalized === "/help" ||
-            normalized === "/capabilities" ||
-            normalized === "capabilities");
+    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,
+            },
+        };
     }
-    async promptWithTaskFallback(userInput) {
-        const mentionedAgent = this.resolveMentionedAgent(userInput);
-        if (mentionedAgent) {
-            const cleaned = userInput.replace(/(?:^|\s)@[^\s]+/g, " ").trim();
-            if (this.isCapabilityQuery(cleaned)) {
-                const cwd = this.sessionManager.getCwd();
-                const loaded = loadCustomSubagents({ cwd, agentDir: getAgentDir() });
-                const agent = loaded.agents.find((item) => item.name === mentionedAgent);
-                if (agent) {
-                    const capabilityPrompt = [
-                        "<agent_capability_query>",
-                        `agent_name: ${agent.name}`,
-                        `description: ${agent.description}`,
-                        `profile: ${agent.profile ?? "full"}`,
-                        `model: ${agent.model ?? "default"}`,
-                        `background: ${agent.background ? "true" : "false"}`,
-                        `tools: ${agent.tools?.join(", ") ?? "default profile tools"}`,
-                        `disallowed_tools: ${agent.disallowedTools?.join(", ") ?? "none"}`,
-                        "",
-                        "agent_instructions:",
-                        agent.instructions,
-                        "",
-                        `user_question: ${cleaned || "what can you do?"}`,
-                        "Answer normally and concisely in plain language. Do not run task tool for this query.",
-                        "</agent_capability_query>",
-                    ].join("\n");
-                    await this.session.prompt(capabilityPrompt, {
-                        expandPromptTemplates: false,
-                        source: "interactive",
-                    });
-                    return;
+    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;
             }
-            const mentionPrompt = [
-                "<orchestrate mode=\"sequential\" agents=\"1\">",
-                `- agent 1: profile=${this.activeProfileName} cwd=${this.sessionManager.getCwd()} agent=${mentionedAgent}`,
-                `task: ${cleaned.length > 0 ? cleaned : userInput}`,
-                "constraints:",
-                "- user selected a concrete custom agent via @mention",
-                `- MUST call task tool with agent="${mentionedAgent}"`,
-                "</orchestrate>",
-            ].join("\n");
-            await this.session.prompt(mentionPrompt, {
+            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",
             });
-            return;
         }
-        await this.session.prompt(userInput);
-    }
-    createIosmVerificationEventBridge(options) {
-        const loaderMessage = options?.loaderMessage ?? `Verifying workspace... (${appKey(this.keybindings, "interrupt")} to interrupt)`;
-        let verifyStreamingComponent;
-        let verifyStreamingMessage;
-        const verifyPendingTools = new Map();
-        return (event) => {
-            switch (event.type) {
-                case "agent_start":
-                    if (this.loadingAnimation) {
-                        this.loadingAnimation.stop();
-                    }
-                    this.statusContainer.clear();
-                    this.loadingAnimation = new DecryptLoader(this.ui, (s) => theme.fg("accent", s), (t) => theme.fg("muted", t), loaderMessage);
-                    this.statusContainer.addChild(this.loadingAnimation);
-                    break;
-                case "message_start":
-                    if (event.message.role === "assistant") {
-                        verifyStreamingComponent = new AssistantMessageComponent(undefined, false, this.getMarkdownThemeWithSettings());
-                        verifyStreamingMessage = event.message;
-                        this.chatContainer.addChild(verifyStreamingComponent);
-                        verifyStreamingComponent.updateContent(verifyStreamingMessage);
-                    }
-                    break;
-                case "message_update":
-                    if (verifyStreamingComponent && event.message.role === "assistant") {
-                        verifyStreamingMessage = event.message;
-                        verifyStreamingComponent.updateContent(verifyStreamingMessage);
-                        for (const content of verifyStreamingMessage.content) {
-                            if (content.type === "toolCall" && !verifyPendingTools.has(content.id)) {
-                                const component = new ToolExecutionComponent(content.name, content.arguments, { showImages: this.settingsManager.getShowImages() }, this.getRegisteredToolDefinition(content.name), this.ui);
-                                component.setExpanded(this.toolOutputExpanded);
-                                this.chatContainer.addChild(component);
-                                verifyPendingTools.set(content.id, component);
-                            }
-                        }
-                    }
-                    break;
-                case "message_end":
-                    if (verifyStreamingComponent && event.message.role === "assistant") {
-                        verifyStreamingMessage = event.message;
-                        verifyStreamingComponent.updateContent(verifyStreamingMessage);
-                        verifyStreamingComponent = undefined;
-                        verifyStreamingMessage = undefined;
-                    }
-                    break;
-                case "tool_execution_start":
-                    if (!verifyPendingTools.has(event.toolCallId)) {
-                        const component = new ToolExecutionComponent(event.toolName, event.args, { showImages: this.settingsManager.getShowImages() }, this.getRegisteredToolDefinition(event.toolName), this.ui);
-                        component.setExpanded(this.toolOutputExpanded);
-                        this.chatContainer.addChild(component);
-                        verifyPendingTools.set(event.toolCallId, component);
-                    }
-                    break;
-                case "tool_execution_update": {
-                    const component = verifyPendingTools.get(event.toolCallId);
-                    if (component) {
-                        component.updateResult({ ...event.partialResult, isError: false }, true);
-                    }
-                    break;
-                }
-                case "tool_execution_end": {
-                    const component = verifyPendingTools.get(event.toolCallId);
-                    if (component) {
-                        component.updateResult({ ...event.result, isError: event.isError });
-                        verifyPendingTools.delete(event.toolCallId);
-                    }
-                    break;
-                }
-                case "agent_end":
-                    if (this.loadingAnimation) {
-                        this.loadingAnimation.stop();
-                        this.loadingAnimation = undefined;
-                        this.statusContainer.clear();
-                    }
-                    verifyPendingTools.clear();
-                    break;
+        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
+                });
             }
-            this.ui.requestRender();
+            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),
         };
     }
-    resolveIosmSnapshot(result, verification) {
-        let snapshot = verification?.current;
-        if (!snapshot && result.cycle) {
-            try {
-                snapshot = createMetricSnapshot(readIosmCycleReport(result.rootDir, result.cycle.cycleId));
-            }
-            catch {
-                snapshot = undefined;
-            }
+    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}).`);
         }
-        return (snapshot ?? {
-            metrics: result.analysis.metrics,
-            iosm_index: null,
-            decision_confidence: null,
+        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 runIosmRefreshPass(options) {
-        const initResult = await initIosmWorkspace({ cwd: options.cwd, force: options.force });
-        let verification;
-        if (options.agentVerify) {
-            verification = await this.runIosmInitAgentVerification(initResult, options.cwd, this.createIosmVerificationEventBridge());
+    async runSwarmFromSingular(input) {
+        const analysis = this.loadSingularAnalysisByRunId(input.runId);
+        if (!analysis) {
+            this.showWarning(`Singular run not found: ${input.runId}`);
+            return;
         }
-        let cycleDecision;
-        if (initResult.cycle) {
-            try {
-                cycleDecision = inspectIosmCycle(initResult.rootDir, initResult.cycle.cycleId).decision;
-            }
-            catch {
-                cycleDecision = undefined;
-            }
+        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;
         }
-        return {
-            initResult,
-            verification,
-            snapshot: this.resolveIosmSnapshot(initResult, verification),
-            guidePath: verification?.guidePath ?? getIosmGuidePath(initResult.rootDir),
-            cycleDecision,
-        };
+        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",
+        });
     }
-    parseIosmAutomationSlashCommand(text) {
-        const args = this.parseSlashArgs(text).slice(1);
-        let targetIndex;
-        let maxIterations;
-        let forceInit = false;
-        for (let index = 0; index < args.length; index++) {
-            const arg = args[index];
-            if (arg === "--force-init" || arg === "--force") {
-                forceInit = true;
-                continue;
+    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(", ")}`);
             }
-            if (arg === "--max-iterations") {
-                const nextValue = args[index + 1];
-                const parsed = nextValue ? Number.parseInt(nextValue, 10) : Number.NaN;
-                if (!Number.isInteger(parsed) || parsed < 1) {
-                    this.showWarning('Usage: /iosm [target-index] [--max-iterations N] [--force-init]');
-                    return undefined;
+        }
+        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;
                 }
-                maxIterations = parsed;
-                index += 1;
-                continue;
-            }
-            if (arg.startsWith("-")) {
-                this.showWarning(`Unknown option for /iosm: ${arg}`);
-                this.showWarning('Usage: /iosm [target-index] [--max-iterations N] [--force-init]');
-                return undefined;
-            }
-            if (targetIndex !== undefined) {
-                this.showWarning(`Unexpected argument for /iosm: ${arg}`);
-                this.showWarning('Usage: /iosm [target-index] [--max-iterations N] [--force-init]');
-                return undefined;
+                runId = runs[0].runId;
             }
-            const parsed = Number.parseFloat(arg);
-            if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
-                this.showWarning(`Invalid target index for /iosm: ${arg}`);
-                this.showWarning("Target index must be a number in the range 0.0 to 1.0.");
-                return undefined;
+            const bundle = this.loadSwarmRunBundle(runId);
+            if (!bundle) {
+                this.showWarning(`Swarm run not found or incomplete: ${runId}`);
+                return;
             }
-            targetIndex = parsed;
+            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,
+            });
         }
-        return { targetIndex, maxIterations, forceInit };
     }
     parseOrchestrateSlashCommand(text) {
         const args = this.parseSlashArgs(text).slice(1);
@@ -7312,10 +9909,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 = [];
@@ -7359,6 +9966,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",
@@ -9281,6 +11889,7 @@ The agent will automatically receive IOSM context on every turn.`;
         this.ui.requestRender();
     }
     async handleClearCommand() {
+        this.contractService.clear("session");
         // Stop loading animation
         if (this.loadingAnimation) {
             this.loadingAnimation.stop();
@@ -9296,6 +11905,7 @@ The agent will automatically receive IOSM context on every turn.`;
         this.streamingComponent = undefined;
         this.streamingMessage = undefined;
         this.pendingTools.clear();
+        this.syncRuntimePromptSuffix();
         this.chatContainer.addChild(new Spacer(1));
         this.chatContainer.addChild(new Text(`${theme.fg("accent", "✓ New session started")}`, 1, 1));
         this.refreshBuiltInHeader();
@@ -9466,6 +12076,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;