iosm-cli 0.1.2 → 0.2.0

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,6 +19,9 @@ 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 { ContractService, normalizeEngineeringContract, } from "../../core/contract.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";
@@ -70,6 +73,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",
@@ -264,11 +355,13 @@ 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.lastSigintTime = 0;
         this.lastEscapeTime = 0;
         this.changelogMarkdown = undefined;
@@ -309,6 +402,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;
@@ -353,14 +447,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();
@@ -372,6 +471,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}`;
@@ -797,6 +934,82 @@ export class InteractiveMode {
         }
         return null;
     }
+    getSemanticArgumentCompletions(prefix) {
+        const subcommands = ["ui", "setup", "status", "index", "rebuild", "query", "help"];
+        const queryFlags = ["--top-k"];
+        const topKValues = ["5", "8", "10", "20"];
+        const hasTrailingSpace = /\\s$/.test(prefix);
+        const tokens = this.parseSlashArgs(prefix);
+        const first = tokens[0]?.toLowerCase();
+        if (!first || (tokens.length === 1 && !hasTrailingSpace)) {
+            const query = first ?? "";
+            const candidates = subcommands.filter((item) => item.includes(query));
+            return candidates.map((item) => ({ value: item, label: item }));
+        }
+        if (first !== "query") {
+            return null;
+        }
+        const topKIndex = tokens.findIndex((token) => token === "--top-k");
+        if (topKIndex >= 0) {
+            const currentValue = tokens[topKIndex + 1];
+            if (!currentValue) {
+                return topKValues.map((value) => ({ value, label: value }));
+            }
+            return topKValues
+                .filter((value) => value.startsWith(currentValue))
+                .map((value) => ({ value, label: value }));
+        }
+        const query = hasTrailingSpace ? "" : (tokens[tokens.length - 1] ?? "");
+        if (query.startsWith("--")) {
+            return queryFlags
+                .filter((flag) => flag.includes(query))
+                .map((flag) => ({ value: flag, label: flag }));
+        }
+        if (hasTrailingSpace) {
+            return queryFlags.map((flag) => ({ value: flag, label: flag }));
+        }
+        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;
+    }
     setupAutocomplete(fdPath) {
         // Define commands for autocomplete
         const builtinCommands = BUILTIN_SLASH_COMMANDS.filter((command) => this.activeProfileName === "iosm" || !IOSM_PROFILE_ONLY_COMMANDS.has(command.name));
@@ -838,6 +1051,18 @@ export class InteractiveMode {
         if (memoryCommand) {
             memoryCommand.getArgumentCompletions = (prefix) => this.getMemoryArgumentCompletions(prefix);
         }
+        const semanticCommand = slashCommands.find((command) => command.name === "semantic");
+        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);
+        }
         // Convert prompt templates to SlashCommand format for autocomplete
         const templateCommands = this.session.promptTemplates.map((cmd) => ({
             name: cmd.name,
@@ -1091,7 +1316,9 @@ export class InteractiveMode {
         }
         // Commands and keys
         const commandsLine = `${pad}${theme.fg("dim", "cmds")}  ` +
-            ["model", "login", "mcp", "memory", "doctor", "new"].map((c) => theme.fg("accent", `/${c}`)).join(theme.fg("dim", "  "));
+            ["model", "login", "contract", "singular", "semantic", "memory", "new"]
+                .map((c) => theme.fg("accent", `/${c}`))
+                .join(theme.fg("dim", "  "));
         const keysLine = `${pad}${theme.fg("dim", "keys")}  ` +
             appKeyHint(kb, "interrupt", "stop") +
             theme.fg("dim", "  ") +
@@ -1519,8 +1746,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) {
@@ -1985,6 +2214,28 @@ export class InteractiveMode {
         const result = await this.showExtensionSelector(`${title}\n${message}`, ["Yes", "No"], opts);
         return result === "Yes";
     }
+    async runWithExtensionLoader(message, task) {
+        const loader = new BorderedLoader(this.ui, theme, message, {
+            cancellable: false,
+        });
+        this.editorContainer.clear();
+        this.editorContainer.addChild(loader);
+        this.ui.setFocus(loader);
+        this.ui.requestRender();
+        const restoreEditor = () => {
+            loader.dispose();
+            this.editorContainer.clear();
+            this.editorContainer.addChild(this.editor);
+            this.ui.setFocus(this.editor);
+            this.ui.requestRender();
+        };
+        try {
+            return await task();
+        }
+        finally {
+            restoreEditor();
+        }
+    }
     /**
      * Show a text input for extensions.
      */
@@ -2222,6 +2473,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;
@@ -2384,6 +2636,21 @@ export class InteractiveMode {
                 await this.handleMemoryCommand(text);
                 return;
             }
+            if (text === "/semantic" || text.startsWith("/semantic ")) {
+                this.editor.setText("");
+                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("");
@@ -3492,19 +3759,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);
@@ -3749,6 +4008,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;
@@ -3756,6 +4017,7 @@ export class InteractiveMode {
         if (!hasPendingQueuedMessages &&
             !hasAutomationWork &&
             !hasVerificationWork &&
+            !hasSingularWork &&
             !hasMainStreaming &&
             !hasRetryWork &&
             !hasCompactionWork &&
@@ -3788,7 +4050,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());
@@ -3796,8 +4060,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;
     }
@@ -4948,6 +5234,7 @@ export class InteractiveMode {
         });
     }
     async handleResumeSession(sessionPath) {
+        this.contractService.clear("session");
         // Stop loading animation
         if (this.loadingAnimation) {
             this.loadingAnimation.stop();
@@ -4965,6 +5252,7 @@ export class InteractiveMode {
         // Clear and re-render the chat
         this.chatContainer.clear();
         this.renderInitialMessages();
+        this.syncRuntimePromptSuffix();
         this.refreshBuiltInHeader();
         this.showStatus("Resumed session");
     }
@@ -5018,7 +5306,8 @@ export class InteractiveMode {
         const providerInfo = this.session.modelRegistry.authStorage.getOAuthProviders().find((p) => p.id === providerId);
         return providerInfo?.name || providerId;
     }
-    async handleOpenRouterApiKeyLogin() {
+    async handleOpenRouterApiKeyLogin(options) {
+        const openModelSelector = options?.openModelSelector ?? true;
         const providerName = this.getProviderDisplayName(OPENROUTER_PROVIDER_ID);
         const existingCredential = this.session.modelRegistry.authStorage.get(OPENROUTER_PROVIDER_ID);
         if (existingCredential) {
@@ -5041,7 +5330,9 @@ export class InteractiveMode {
         this.session.modelRegistry.authStorage.set(OPENROUTER_PROVIDER_ID, { type: "api_key", key: apiKey });
         await this.updateAvailableProviderCount();
         this.showStatus(`${providerName} API key saved to ${getAuthPath()}`);
-        await this.showModelProviderSelector(OPENROUTER_PROVIDER_ID);
+        if (openModelSelector) {
+            await this.showModelProviderSelector(OPENROUTER_PROVIDER_ID);
+        }
     }
     async showLoginDialog(providerId) {
         const providerInfo = this.session.modelRegistry.authStorage.getOAuthProviders().find((p) => p.id === providerId);
@@ -5499,104 +5790,1693 @@ export class InteractiveMode {
             this.showError(error instanceof Error ? error.message : String(error));
         }
     }
-    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;
+    createSemanticRuntime() {
+        return new SemanticSearchRuntime({
+            cwd: this.sessionManager.getCwd(),
+            agentDir: getAgentDir(),
+            authStorage: this.session.modelRegistry.authStorage,
+        });
     }
-    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);
+    parseSemanticScopeOptions(args, usage = "Usage: /semantic setup --scope <user|project>") {
+        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();
+                if (!value) {
+                    return { scope, rest, error: usage };
+                }
+                if (value !== "user" && value !== "project") {
+                    return { scope, rest, error: `Invalid semantic scope "${value}". Use user or project.` };
+                }
+                scope = value;
+                index += 1;
                 continue;
             }
-            active.set(entry.targetId, {
-                name,
-                targetId: entry.targetId,
-                labelEntryId: entry.id,
-                timestamp: entry.timestamp,
-            });
+            rest.push(token);
         }
-        return [...active.values()].sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+        return { scope, rest };
     }
-    buildDefaultCheckpointName(checkpoints) {
-        const used = new Set(checkpoints.map((checkpoint) => checkpoint.name.toLowerCase()));
-        let index = 1;
-        while (used.has(`cp-${index}`)) {
-            index += 1;
+    parseSemanticTopKOptions(args) {
+        let topK;
+        const rest = [];
+        for (let index = 0; index < args.length; index++) {
+            const token = args[index] ?? "";
+            const normalized = token.toLowerCase();
+            if (normalized === "--top-k" || normalized === "--topk") {
+                const raw = (args[index + 1] ?? "").trim();
+                if (!raw) {
+                    return { topK, rest, error: "Usage: /semantic query <text> [--top-k 1..20]" };
+                }
+                const parsed = Number.parseInt(raw, 10);
+                if (!Number.isFinite(parsed) || `${parsed}` !== raw || parsed < 1 || parsed > 20) {
+                    return { topK, rest, error: "--top-k must be an integer between 1 and 20." };
+                }
+                topK = parsed;
+                index += 1;
+                continue;
+            }
+            rest.push(token);
         }
-        return `cp-${index}`;
+        return { topK, rest };
     }
-    formatCheckpointList(checkpoints) {
-        if (checkpoints.length === 0) {
-            return "No checkpoints yet.\nCreate one with: /checkpoint [name]";
+    formatSemanticStatusReport(status) {
+        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"}`,
+        ];
+        if (status.provider)
+            lines.push(`provider: ${status.provider}`);
+        if (status.model)
+            lines.push(`model: ${status.model}`);
+        lines.push(`files: ${status.files}`);
+        lines.push(`chunks: ${status.chunks}`);
+        if (status.dimension !== undefined)
+            lines.push(`dimension: ${status.dimension}`);
+        if (status.ageSeconds !== undefined)
+            lines.push(`age_seconds: ${status.ageSeconds}`);
+        lines.push(`index_path: ${status.indexPath}`);
+        lines.push(`config_user: ${status.configPathUser}`);
+        lines.push(`config_project: ${status.configPathProject}`);
+        if (!status.configured) {
+            lines.push("hint: run /semantic setup");
         }
-        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}`;
+    formatSemanticIndexReport(result) {
+        return [
+            `action: ${result.action}`,
+            `processed_files: ${result.processedFiles}`,
+            `reused_files: ${result.reusedFiles}`,
+            `new_files: ${result.newFiles}`,
+            `changed_files: ${result.changedFiles}`,
+            `removed_files: ${result.removedFiles}`,
+            `chunks: ${result.chunks}`,
+            `dimension: ${result.dimension}`,
+            `duration_ms: ${result.durationMs}`,
+            `built_at: ${result.builtAt}`,
+            `index_path: ${result.indexPath}`,
+        ].join("\n");
     }
-    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;
+    formatSemanticQueryReport(result) {
+        const lines = [
+            `query: ${result.query}`,
+            `top_k: ${result.topK}`,
+            `auto_refreshed: ${result.autoRefreshed ? "yes" : "no"}`,
+        ];
+        if (result.hits.length === 0) {
+            lines.push("hits: none");
+            return lines.join("\n");
         }
-        if (subcommand === "help" || subcommand === "-h" || subcommand === "--help") {
-            this.showCommandTextBlock("Checkpoint Help", ["Usage:", "  /checkpoint [name]", "  /checkpoint list", "", "Examples:", "  /checkpoint", "  /checkpoint before-refactor"].join("\n"));
-            return;
+        lines.push("hits:");
+        for (let index = 0; index < result.hits.length; index++) {
+            const hit = result.hits[index];
+            lines.push(`${index + 1}. score=${hit.score.toFixed(4)} ${hit.path}:${hit.lineStart}-${hit.lineEnd}`);
+            lines.push(`   ${hit.snippet}`);
         }
-        const leafId = this.sessionManager.getLeafId();
-        if (!leafId) {
-            this.showWarning("Cannot create checkpoint yet (session has no entries).");
+        return lines.join("\n");
+    }
+    getSemanticSetupProviderLabel(type) {
+        if (type === "openrouter")
+            return "openrouter";
+        if (type === "ollama")
+            return "ollama";
+        return "custom_openai";
+    }
+    async ensureOpenRouterSemanticCredentials() {
+        const existing = await this.session.modelRegistry.authStorage.getApiKey(OPENROUTER_PROVIDER_ID);
+        if (existing)
             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.");
+        const shouldLogin = await this.showExtensionConfirm("Semantic setup: OpenRouter key missing", "No OpenRouter API key found. Open login flow now?");
+        if (!shouldLogin) {
+            this.showWarning("OpenRouter key is missing. semantic index/query will fail until credentials are added.");
             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;
+        await this.handleOpenRouterApiKeyLogin({ openModelSelector: false });
+        const afterLogin = await this.session.modelRegistry.authStorage.getApiKey(OPENROUTER_PROVIDER_ID);
+        if (!afterLogin) {
+            this.showWarning("OpenRouter key is still missing. You can run /login later.");
+        }
+    }
+    async selectSemanticModelFromCatalog(title, catalogModels, currentModel, options) {
+        const normalizedCurrent = currentModel.trim();
+        const uniqueModels = [];
+        const seen = new Set();
+        for (const model of catalogModels) {
+            const normalized = model.trim();
+            if (!normalized || seen.has(normalized))
+                continue;
+            seen.add(normalized);
+            uniqueModels.push(normalized);
+        }
+        const optionToModel = new Map();
+        const selectorOptions = [];
+        const addOption = (label, modelId) => {
+            let uniqueLabel = label;
+            let suffix = 2;
+            while (optionToModel.has(uniqueLabel)) {
+                uniqueLabel = `${label} (${suffix})`;
+                suffix += 1;
+            }
+            optionToModel.set(uniqueLabel, modelId);
+            selectorOptions.push(uniqueLabel);
+        };
+        if (normalizedCurrent) {
+            addOption(`Current: ${normalizedCurrent}`, normalizedCurrent);
+        }
+        for (const modelId of uniqueModels) {
+            const marker = options?.highlightLikelyEmbedding && isLikelyEmbeddingModelId(modelId) ? " [embedding]" : "";
+            addOption(`${modelId}${marker}`, modelId);
+        }
+        const manualOption = "Enter model manually";
+        selectorOptions.push(manualOption);
+        const selected = await this.showExtensionSelector(title, selectorOptions);
+        if (!selected)
+            return undefined;
+        if (selected === manualOption) {
+            const modelInput = await this.showExtensionInput(`${title}: model`, normalizedCurrent || "model-id");
+            if (modelInput === undefined)
+                return undefined;
+            const model = modelInput.trim();
+            if (!model) {
+                this.showWarning("Model cannot be empty.");
+                return undefined;
+            }
+            return model;
+        }
+        return optionToModel.get(selected);
+    }
+    async runSemanticSetupWizard(initialScope) {
+        const cwd = this.sessionManager.getCwd();
+        const agentDir = getAgentDir();
+        const merged = loadMergedSemanticConfig(cwd, agentDir);
+        const config = merged.config ?? getDefaultSemanticSearchConfig();
+        let scope = initialScope;
+        if (!scope) {
+            const pickedScope = await this.showExtensionSelector("/semantic setup: scope", [
+                "user (Recommended)",
+                "project",
+            ]);
+            if (!pickedScope) {
+                this.showStatus("Semantic setup cancelled");
+                return;
+            }
+            scope = pickedScope.startsWith("project") ? "project" : "user";
+        }
+        const providerOption = await this.showExtensionSelector("/semantic setup: provider", [
+            "openrouter (Recommended)",
+            "ollama",
+            "custom_openai",
+        ]);
+        if (!providerOption) {
+            this.showStatus("Semantic setup cancelled");
+            return;
+        }
+        const providerType = providerOption.startsWith("ollama")
+            ? "ollama"
+            : providerOption.startsWith("custom_openai")
+                ? "custom_openai"
+                : "openrouter";
+        const providerDefaults = {
+            openrouter: "openai/text-embedding-3-small",
+            ollama: "nomic-embed-text",
+            custom_openai: "text-embedding-3-small",
+        };
+        const currentModel = (config.provider.type === providerType ? config.provider.model : providerDefaults[providerType]).trim();
+        let model = currentModel;
+        const nextProvider = {
+            ...config.provider,
+            type: providerType,
+            model: model || providerDefaults[providerType],
+        };
+        if (providerType === "ollama") {
+            const defaultBase = (config.provider.type === "ollama" ? config.provider.baseUrl : undefined) ?? "http://127.0.0.1:11434";
+            const baseUrlInput = await this.showExtensionInput("/semantic setup: ollama base URL", defaultBase);
+            if (baseUrlInput === undefined) {
+                this.showStatus("Semantic setup cancelled");
+                return;
+            }
+            const baseUrl = baseUrlInput.trim();
+            nextProvider.baseUrl = baseUrl || undefined;
+            nextProvider.apiKeyEnv = undefined;
+            let ollamaModels = [];
+            try {
+                ollamaModels = await listOllamaLocalModels({
+                    baseUrl: nextProvider.baseUrl,
+                    headers: config.provider.type === "ollama" ? config.provider.headers : undefined,
+                    timeoutMs: nextProvider.timeoutMs,
+                });
+                if (ollamaModels.length === 0) {
+                    this.showWarning("No local Ollama models found at /api/tags. You can enter model manually.");
+                }
+            }
+            catch (error) {
+                const errorMsg = error instanceof Error ? error.message : String(error);
+                this.showWarning(`Failed to load Ollama models automatically: ${errorMsg}`);
+            }
+            const selectedModel = await this.selectSemanticModelFromCatalog("/semantic setup: ollama model", ollamaModels, currentModel || providerDefaults.ollama, { highlightLikelyEmbedding: true });
+            if (!selectedModel) {
+                this.showStatus("Semantic setup cancelled");
+                return;
+            }
+            model = selectedModel;
+        }
+        else if (providerType === "custom_openai") {
+            const defaultBase = (config.provider.type === "custom_openai" ? config.provider.baseUrl : undefined) ?? "http://127.0.0.1:8000/v1";
+            const baseUrlInput = await this.showExtensionInput("/semantic setup: custom base URL", defaultBase);
+            if (baseUrlInput === undefined) {
+                this.showStatus("Semantic setup cancelled");
+                return;
+            }
+            const baseUrl = baseUrlInput.trim();
+            if (!baseUrl) {
+                this.showWarning("Custom provider base URL cannot be empty.");
+                return;
+            }
+            nextProvider.baseUrl = baseUrl;
+            const defaultApiKeyEnv = (config.provider.type === "custom_openai" ? config.provider.apiKeyEnv : undefined) ?? "OPENAI_API_KEY";
+            const apiKeyEnvInput = await this.showExtensionInput("/semantic setup: custom API key env (optional)", defaultApiKeyEnv);
+            if (apiKeyEnvInput === undefined) {
+                this.showStatus("Semantic setup cancelled");
+                return;
+            }
+            nextProvider.apiKeyEnv = apiKeyEnvInput.trim() || undefined;
+            const modelInput = await this.showExtensionInput("/semantic setup: custom model", currentModel);
+            if (modelInput === undefined) {
+                this.showStatus("Semantic setup cancelled");
+                return;
+            }
+            const normalizedModel = modelInput.trim();
+            if (!normalizedModel) {
+                this.showWarning("Model cannot be empty.");
+                return;
+            }
+            model = normalizedModel;
+        }
+        else {
+            nextProvider.baseUrl = undefined;
+            nextProvider.apiKeyEnv = undefined;
+            let openRouterModels = [];
+            try {
+                openRouterModels = await listOpenRouterEmbeddingModels({
+                    timeoutMs: nextProvider.timeoutMs,
+                    authStorage: this.session.modelRegistry.authStorage,
+                });
+                if (openRouterModels.length === 0) {
+                    this.showWarning("OpenRouter embeddings catalog is empty. You can enter model manually.");
+                }
+            }
+            catch (error) {
+                const errorMsg = error instanceof Error ? error.message : String(error);
+                this.showWarning(`Failed to load OpenRouter embedding models automatically: ${errorMsg}`);
+            }
+            const selectedModel = await this.selectSemanticModelFromCatalog("/semantic setup: openrouter model", openRouterModels, currentModel || providerDefaults.openrouter);
+            if (!selectedModel) {
+                this.showStatus("Semantic setup cancelled");
+                return;
+            }
+            model = selectedModel;
+        }
+        nextProvider.model = model;
+        while (true) {
+            const headersInput = await this.showExtensionInput("/semantic setup: headers (optional KEY=VALUE,CSV; press Enter to skip)", "");
+            if (headersInput === undefined) {
+                this.showStatus("Semantic setup cancelled");
+                return;
+            }
+            const parsedHeaders = this.parseMcpKeyValueMapInput(headersInput);
+            if (parsedHeaders.error) {
+                this.showWarning(parsedHeaders.error);
+                continue;
+            }
+            nextProvider.headers = parsedHeaders.value;
+            break;
+        }
+        const nextConfig = {
+            ...config,
+            enabled: true,
+            provider: nextProvider,
+        };
+        const savedPath = upsertScopedSemanticSearchConfig(scope, nextConfig, cwd, agentDir);
+        if (providerType === "openrouter") {
+            await this.ensureOpenRouterSemanticCredentials();
+        }
+        this.showStatus(`Semantic setup saved (${scope})`);
+        this.showCommandTextBlock("Semantic Setup", [
+            `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;
+            try {
+                status = await this.createSemanticRuntime().status();
+            }
+            catch (error) {
+                this.reportSemanticError(error, "status");
+            }
+            const summary = status
+                ? `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",
+                "Show status",
+                "Index now",
+                "Rebuild index",
+                "Query index",
+                `Automatic indexing: ${status?.autoIndex ? "on" : "off"}`,
+                "Show config/index paths",
+                "Close",
+            ]);
+            if (!selected || selected === "Close") {
+                return;
+            }
+            if (selected === "Configure provider/model") {
+                await this.runSemanticSetupWizard();
+                continue;
+            }
+            if (selected === "Show status") {
+                try {
+                    const result = await this.runWithExtensionLoader("Checking semantic index status...", async () => this.createSemanticRuntime().status());
+                    this.showCommandTextBlock("Semantic Status", this.formatSemanticStatusReport(result));
+                }
+                catch (error) {
+                    this.reportSemanticError(error, "status");
+                }
+                continue;
+            }
+            if (selected === "Index now") {
+                try {
+                    const result = await this.runWithExtensionLoader("Indexing semantic embeddings...", async () => this.createSemanticRuntime().index());
+                    this.showStatus(`Semantic index updated (${result.processedFiles} files).`);
+                    this.showCommandTextBlock("Semantic Index", this.formatSemanticIndexReport(result));
+                }
+                catch (error) {
+                    this.reportSemanticError(error, "index");
+                }
+                continue;
+            }
+            if (selected === "Rebuild index") {
+                try {
+                    const result = await this.runWithExtensionLoader("Rebuilding semantic index...", async () => this.createSemanticRuntime().rebuild());
+                    this.showStatus(`Semantic index rebuilt (${result.processedFiles} files).`);
+                    this.showCommandTextBlock("Semantic Rebuild", this.formatSemanticIndexReport(result));
+                }
+                catch (error) {
+                    this.reportSemanticError(error, "rebuild");
+                }
+                continue;
+            }
+            if (selected === "Query index") {
+                const queryInput = await this.showExtensionInput("/semantic query", "where auth token is validated");
+                if (queryInput === undefined)
+                    continue;
+                const query = queryInput.trim();
+                if (!query) {
+                    this.showWarning("Semantic query cannot be empty.");
+                    continue;
+                }
+                const topKInput = await this.showExtensionInput("/semantic query: top-k (optional, 1..20)", "8");
+                if (topKInput === undefined)
+                    continue;
+                const topKRaw = topKInput.trim();
+                let topK = undefined;
+                if (topKRaw) {
+                    const parsed = Number.parseInt(topKRaw, 10);
+                    if (!Number.isFinite(parsed) || parsed < 1 || parsed > 20) {
+                        this.showWarning("top-k must be an integer between 1 and 20.");
+                        continue;
+                    }
+                    topK = parsed;
+                }
+                try {
+                    const result = await this.runWithExtensionLoader("Querying semantic index...", async () => this.createSemanticRuntime().query(query, topK));
+                    this.showCommandTextBlock("Semantic Query", this.formatSemanticQueryReport(result));
+                }
+                catch (error) {
+                    this.reportSemanticError(error, "query");
+                }
+                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();
+                const agentDir = getAgentDir();
+                try {
+                    const semanticStatus = await this.runWithExtensionLoader("Loading semantic paths...", async () => runtime.status());
+                    this.showCommandTextBlock("Semantic Paths", [
+                        `user_config: ${getSemanticConfigPath("user", cwd, agentDir)}`,
+                        `project_config: ${getSemanticConfigPath("project", cwd, agentDir)}`,
+                        `index_dir: ${semanticStatus.indexPath}`,
+                    ].join("\n"));
+                }
+                catch (error) {
+                    this.reportSemanticError(error, "status");
+                }
+                continue;
+            }
+        }
+    }
+    reportSemanticError(error, context) {
+        if (error instanceof SemanticConfigMissingError) {
+            this.showWarning("Semantic search is not configured. Run /semantic setup.");
+            this.showCommandTextBlock("Semantic Config", [
+                `user_config: ${error.userConfigPath}`,
+                `project_config: ${error.projectConfigPath}`,
+                "next: /semantic setup",
+            ].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.");
+            return;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        this.showError(`Semantic ${context} failed: ${message}`);
+    }
+    async handleSemanticCommand(text) {
+        const args = this.parseSlashArgs(text).slice(1);
+        if (args.length === 0 || (args[0]?.toLowerCase() ?? "") === "ui") {
+            await this.runSemanticInteractiveMenu();
+            return;
+        }
+        const subcommand = (args[0] ?? "").toLowerCase();
+        const rest = args.slice(1);
+        if (subcommand === "help" || subcommand === "-h" || subcommand === "--help") {
+            this.showCommandTextBlock("Semantic Help", [
+                "Usage:",
+                "  /semantic",
+                "  /semantic ui",
+                "  /semantic setup [--scope user|project]",
+                "  /semantic auto-index [on|off] [--scope user|project]",
+                "  /semantic status",
+                "  /semantic index",
+                "  /semantic rebuild",
+                "  /semantic query <text> [--top-k N]",
+                "  /semantic help",
+            ].join("\n"));
+            return;
+        }
+        if (subcommand === "setup") {
+            const parsedScope = this.parseSemanticScopeOptions(rest);
+            if (parsedScope.error) {
+                this.showWarning(parsedScope.error);
+                return;
+            }
+            if (parsedScope.rest.length > 0) {
+                this.showWarning(`Unexpected arguments for /semantic setup: ${parsedScope.rest.join(" ")}`);
+                return;
+            }
+            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());
+                this.showCommandTextBlock("Semantic Status", this.formatSemanticStatusReport(result));
+            }
+            catch (error) {
+                this.reportSemanticError(error, "status");
+            }
+            return;
+        }
+        if (subcommand === "index") {
+            try {
+                const result = await this.runWithExtensionLoader("Indexing semantic embeddings...", async () => this.createSemanticRuntime().index());
+                this.showStatus(`Semantic index updated (${result.processedFiles} files).`);
+                this.showCommandTextBlock("Semantic Index", this.formatSemanticIndexReport(result));
+            }
+            catch (error) {
+                this.reportSemanticError(error, "index");
+            }
+            return;
+        }
+        if (subcommand === "rebuild") {
+            try {
+                const result = await this.runWithExtensionLoader("Rebuilding semantic index...", async () => this.createSemanticRuntime().rebuild());
+                this.showStatus(`Semantic index rebuilt (${result.processedFiles} files).`);
+                this.showCommandTextBlock("Semantic Rebuild", this.formatSemanticIndexReport(result));
+            }
+            catch (error) {
+                this.reportSemanticError(error, "rebuild");
+            }
+            return;
+        }
+        if (subcommand === "query") {
+            const parsed = this.parseSemanticTopKOptions(rest);
+            if (parsed.error) {
+                this.showWarning(parsed.error);
+                return;
+            }
+            const query = parsed.rest.join(" ").trim();
+            if (!query) {
+                this.showWarning("Usage: /semantic query <text> [--top-k N]");
+                return;
+            }
+            try {
+                const result = await this.runWithExtensionLoader("Querying semantic index...", async () => this.createSemanticRuntime().query(query, parsed.topK));
+                this.showCommandTextBlock("Semantic Query", this.formatSemanticQueryReport(result));
+            }
+            catch (error) {
+                this.reportSemanticError(error, "query");
+            }
+            return;
+        }
+        this.showWarning(`Unknown /semantic subcommand "${subcommand}". Use /semantic help.`);
+    }
+    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 };
+    }
+    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 } : {}),
+        });
+    }
+    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"));
+    }
+    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];
+            }
+            else {
+                nextPayload[field.key] = normalized;
+            }
+            return normalizeEngineeringContract(nextPayload);
+        }
+        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];
+        }
+        else {
+            nextPayload[field.key] = values;
+        }
+        return normalizeEngineeringContract(nextPayload);
+    }
+    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 editContractScope(scope) {
+        const state = this.getContractStateSafe();
+        if (!state)
+            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;
+            }
+            if (selected.startsWith("Open JSON preview")) {
+                this.showCommandTextBlock(`Contract Draft (${scope})`, JSON.stringify(Object.keys(draft).length > 0 ? draft : {}, null, 2));
+                continue;
+            }
+            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;
+                    }
+                }
+                this.contractService.clear(scope);
+                this.syncRuntimePromptSuffix();
+                this.showStatus(`Contract cleared (${scope}).`);
+                return;
+            }
+            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));
+            }
+        }
+    }
+    async runContractInteractiveMenu() {
+        while (true) {
+            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 (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.");
+                }
+                catch (error) {
+                    this.showWarning(error instanceof Error ? error.message : String(error));
+                }
+                continue;
+            }
+            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 (selected === "Delete session contract") {
+                this.contractService.clear("session");
+                this.syncRuntimePromptSuffix();
+                this.showStatus("Session contract deleted.");
+                continue;
+            }
+            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.");
+            }
+        }
+    }
+    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;
+            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 (parsed.rest.length > 0) {
+                this.showWarning(`Unexpected arguments for /contract edit: ${parsed.rest.join(" ")}`);
+                return;
+            }
+            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 (!parsed.scope) {
+                this.showWarning("Usage: /contract clear --scope <project|session>");
+                return;
+            }
+            if (parsed.rest.length > 0) {
+                this.showWarning(`Unexpected arguments for /contract clear: ${parsed.rest.join(" ")}`);
+                return;
+            }
+            this.contractService.clear(parsed.scope);
+            this.syncRuntimePromptSuffix();
+            this.showStatus(`Contract cleared (${parsed.scope}).`);
+            return;
+        }
+        this.showWarning(`Unknown /contract subcommand "${subcommand}". Use /contract help.`);
+    }
+    normalizeSingularComplexity(value, fallback) {
+        const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
+        if (normalized === "low" || normalized === "medium" || normalized === "high") {
+            return normalized;
+        }
+        return fallback;
+    }
+    normalizeSingularBlastRadius(value, fallback) {
+        const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
+        if (normalized === "low" || normalized === "medium" || normalized === "high") {
+            return normalized;
+        }
+        return fallback;
+    }
+    normalizeSingularRecommendation(value, fallback) {
+        const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
+        if (normalized === "implement_now" || normalized === "implement_incrementally" || normalized === "defer") {
+            return normalized;
+        }
+        return fallback;
+    }
+    normalizeSingularStageFit(value) {
+        const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
+        if (normalized === "needed_now" || normalized === "optional_now" || normalized === "later") {
+            return normalized;
+        }
+        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;
+        }
+        return lines;
+    }
+    normalizeSingularImpactAnalysis(value, fallback) {
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            return fallback;
+        }
+        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("; ")}`);
+        }
+        if ((contract.scope_exclude ?? []).length > 0) {
+            lines.push(`- scope_exclude: ${(contract.scope_exclude ?? []).slice(0, 8).join("; ")}`);
+        }
+        if ((contract.constraints ?? []).length > 0) {
+            lines.push(`- constraints: ${(contract.constraints ?? []).slice(0, 10).join("; ")}`);
+        }
+        if ((contract.quality_gates ?? []).length > 0) {
+            lines.push(`- quality_gates: ${(contract.quality_gates ?? []).slice(0, 10).join("; ")}`);
+        }
+        if ((contract.definition_of_done ?? []).length > 0) {
+            lines.push(`- definition_of_done: ${(contract.definition_of_done ?? []).slice(0, 10).join("; ")}`);
+        }
+        if ((contract.non_goals ?? []).length > 0) {
+            lines.push(`- non_goals: ${(contract.non_goals ?? []).slice(0, 8).join("; ")}`);
+        }
+        return lines.length > 0 ? lines.join("\n") : "- none";
+    }
+    buildSingularAgentPrompt(request, baseline, contract) {
+        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}`,
+            "",
+            "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;
+        }
+        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;
+        }
+        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,
+            });
+        }
+        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,
+        };
+    }
+    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 runSingularAgentFeasibilityPass(request, baseline, contract) {
+        const model = this.session.model;
+        if (!model) {
+            return undefined;
+        }
+        const cwd = this.sessionManager.getCwd();
+        const agentDir = getAgentDir();
+        const settingsManager = SettingsManager.create(cwd, agentDir);
+        const authStorage = AuthStorage.create(getAuthPath());
+        const modelRegistry = new ModelRegistry(authStorage, getModelsPath());
+        const resourceLoader = new DefaultResourceLoader({
+            cwd,
+            agentDir,
+            settingsManager,
+            noExtensions: true,
+            noSkills: true,
+            noPromptTemplates: true,
+        });
+        await resourceLoader.reload();
+        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)`,
+        });
+        const unsubscribe = session.subscribe((event) => {
+            eventBridge(event);
+            if (event.type === "tool_execution_start") {
+                toolCallsStarted += 1;
+                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());
+                    }
+                }
+            }
+        });
+        this.singularAnalysisSession = session;
+        try {
+            const primaryPrompt = this.buildSingularAgentPrompt(request, baseline, contract);
+            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 {
+                    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);
+            }
+            if ((parsed.parsedOptions < 3 || !parsed.hasRecommendation) || toolCallsStarted === 0) {
+                return undefined;
+            }
+            return parsed.result;
+        }
+        finally {
+            if (session.isStreaming) {
+                await session.abort().catch(() => {
+                    // best effort
+                });
+            }
+            if (this.singularAnalysisSession === session) {
+                this.singularAnalysisSession = undefined;
+            }
+            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}`);
+            }
+            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 to generate a detailed execution draft in editor");
+        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" || result.recommendation === "defer") {
+            this.showStatus("Singular: defer option selected, implementation postponed.");
+            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,
+            });
+            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);
+                    if (enriched) {
+                        result = enriched;
+                    }
+                    else {
+                        this.showWarning("Agent feasibility pass returned incomplete output. Showing heuristic fallback.");
+                    }
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    this.showWarning(`Agent feasibility pass failed. Showing heuristic fallback: ${message}`);
+                }
+            }
+            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",
+                "",
+                "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;
+            }
+            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", [
@@ -5680,6 +7560,8 @@ export class InteractiveMode {
         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 = [];
@@ -5693,6 +7575,12 @@ export class InteractiveMode {
                 }
                 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");
             }
@@ -5723,6 +7611,14 @@ export class InteractiveMode {
                 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");
@@ -5734,7 +7630,17 @@ export class InteractiveMode {
                 return;
             }
             if (selected === "Show auth/models paths") {
-                this.showCommandTextBlock("Runtime Paths", [`auth.json: ${getAuthPath()}`, `models.json: ${getModelsPath()}`].join("\n"));
+                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;
             }
         }
@@ -5761,6 +7667,22 @@ export class InteractiveMode {
         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) {
@@ -5802,6 +7724,44 @@ export class InteractiveMode {
         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(", ")}.`);
         }
@@ -6265,6 +8225,7 @@ export class InteractiveMode {
     }
     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();
@@ -6279,7 +8240,7 @@ export class InteractiveMode {
                     this.statusContainer.addChild(this.loadingAnimation);
                     break;
                 case "message_start":
-                    if (event.message.role === "assistant") {
+                    if (event.message.role === "assistant" && !hideAssistantText) {
                         verifyStreamingComponent = new AssistantMessageComponent(undefined, false, this.getMarkdownThemeWithSettings());
                         verifyStreamingMessage = event.message;
                         this.chatContainer.addChild(verifyStreamingComponent);
@@ -8598,6 +10559,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();
@@ -8613,6 +10575,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();