iosm-cli 0.1.3 → 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,7 +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 { getDefaultSemanticSearchConfig, getSemanticConfigPath, getSemanticIndexDir, isLikelyEmbeddingModelId, listOllamaLocalModels, listOpenRouterEmbeddingModels, loadMergedSemanticConfig, SemanticConfigMissingError, SemanticRebuildRequiredError, SemanticSearchRuntime, upsertScopedSemanticSearchConfig, } from "../../core/semantic/index.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";
@@ -71,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",
@@ -265,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;
@@ -310,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;
@@ -354,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();
@@ -373,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}`;
@@ -834,6 +970,46 @@ export class InteractiveMode {
         }
         return null;
     }
+    getContractArgumentCompletions(prefix) {
+        const subcommands = ["ui", "show", "edit", "clear", "help"];
+        const scopeFlags = ["--scope"];
+        const scopeValues = ["project", "session"];
+        const hasTrailingSpace = /\\s$/.test(prefix);
+        const tokens = this.parseSlashArgs(prefix);
+        const first = tokens[0]?.toLowerCase();
+        if (!first || (tokens.length === 1 && !hasTrailingSpace)) {
+            const query = first ?? "";
+            return [...subcommands, ...scopeFlags]
+                .filter((item) => item.includes(query))
+                .map((item) => ({ value: item, label: item }));
+        }
+        const scopeIndex = tokens.findIndex((token) => token === "--scope");
+        if (scopeIndex >= 0) {
+            const currentValue = tokens[scopeIndex + 1];
+            if (!currentValue) {
+                return scopeValues.map((value) => ({ value, label: value }));
+            }
+            return scopeValues
+                .filter((value) => value.startsWith(currentValue))
+                .map((value) => ({ value, label: value }));
+        }
+        const query = hasTrailingSpace ? "" : (tokens[tokens.length - 1] ?? "");
+        if (query.startsWith("--")) {
+            return scopeFlags.filter((flag) => flag.includes(query)).map((flag) => ({ value: flag, label: flag }));
+        }
+        return null;
+    }
+    getSingularArgumentCompletions(prefix) {
+        const subcommands = ["help", "last"];
+        const hasTrailingSpace = /\\s$/.test(prefix);
+        const tokens = this.parseSlashArgs(prefix);
+        const first = tokens[0]?.toLowerCase();
+        if (!first || (tokens.length === 1 && !hasTrailingSpace)) {
+            const query = first ?? "";
+            return subcommands.filter((item) => item.includes(query)).map((item) => ({ value: item, label: item }));
+        }
+        return null;
+    }
     setupAutocomplete(fdPath) {
         // Define commands for autocomplete
         const builtinCommands = BUILTIN_SLASH_COMMANDS.filter((command) => this.activeProfileName === "iosm" || !IOSM_PROFILE_ONLY_COMMANDS.has(command.name));
@@ -879,6 +1055,14 @@ export class InteractiveMode {
         if (semanticCommand) {
             semanticCommand.getArgumentCompletions = (prefix) => this.getSemanticArgumentCompletions(prefix);
         }
+        const contractCommand = slashCommands.find((command) => command.name === "contract");
+        if (contractCommand) {
+            contractCommand.getArgumentCompletions = (prefix) => this.getContractArgumentCompletions(prefix);
+        }
+        const singularCommand = slashCommands.find((command) => command.name === "singular");
+        if (singularCommand) {
+            singularCommand.getArgumentCompletions = (prefix) => this.getSingularArgumentCompletions(prefix);
+        }
         // Convert prompt templates to SlashCommand format for autocomplete
         const templateCommands = this.session.promptTemplates.map((cmd) => ({
             name: cmd.name,
@@ -1132,7 +1316,7 @@ export class InteractiveMode {
         }
         // Commands and keys
         const commandsLine = `${pad}${theme.fg("dim", "cmds")}  ` +
-            ["model", "login", "mcp", "semantic", "memory", "doctor", "new"]
+            ["model", "login", "contract", "singular", "semantic", "memory", "new"]
                 .map((c) => theme.fg("accent", `/${c}`))
                 .join(theme.fg("dim", "  "));
         const keysLine = `${pad}${theme.fg("dim", "keys")}  ` +
@@ -1562,8 +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) {
@@ -2287,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;
@@ -2454,6 +2641,16 @@ export class InteractiveMode {
                 await this.handleSemanticCommand(text);
                 return;
             }
+            if (text === "/contract" || text.startsWith("/contract ")) {
+                this.editor.setText("");
+                await this.handleContractCommand(text);
+                return;
+            }
+            if (text === "/singular" || text.startsWith("/singular ")) {
+                this.editor.setText("");
+                await this.handleSingularCommand(text);
+                return;
+            }
             if (text === "/settings") {
                 this.showSettingsSelector();
                 this.editor.setText("");
@@ -3562,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);
@@ -3819,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;
@@ -3826,6 +4017,7 @@ export class InteractiveMode {
         if (!hasPendingQueuedMessages &&
             !hasAutomationWork &&
             !hasVerificationWork &&
+            !hasSingularWork &&
             !hasMainStreaming &&
             !hasRetryWork &&
             !hasCompactionWork &&
@@ -3858,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());
@@ -3866,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;
     }
@@ -5018,6 +5234,7 @@ export class InteractiveMode {
         });
     }
     async handleResumeSession(sessionPath) {
+        this.contractService.clear("session");
         // Stop loading animation
         if (this.loadingAnimation) {
             this.loadingAnimation.stop();
@@ -5035,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");
     }
@@ -5579,7 +5797,7 @@ export class InteractiveMode {
             authStorage: this.session.modelRegistry.authStorage,
         });
     }
-    parseSemanticScopeOptions(args) {
+    parseSemanticScopeOptions(args, usage = "Usage: /semantic setup --scope <user|project>") {
         let scope;
         const rest = [];
         for (let index = 0; index < args.length; index++) {
@@ -5588,7 +5806,7 @@ export class InteractiveMode {
             if (normalized === "--scope") {
                 const value = (args[index + 1] ?? "").toLowerCase();
                 if (!value) {
-                    return { scope, rest, error: "Usage: /semantic setup --scope <user|project>" };
+                    return { scope, rest, error: usage };
                 }
                 if (value !== "user" && value !== "project") {
                     return { scope, rest, error: `Invalid semantic scope "${value}". Use user or project.` };
@@ -5628,6 +5846,7 @@ export class InteractiveMode {
         const lines = [
             `configured: ${status.configured ? "yes" : "no"}`,
             `enabled: ${status.enabled ? "yes" : "no"}`,
+            `auto_index: ${status.autoIndex ? "on" : "off"}`,
             `indexed: ${status.indexed ? "yes" : "no"}`,
             `stale: ${status.stale ? `yes${status.staleReason ? ` (${status.staleReason})` : ""}` : "no"}`,
         ];
@@ -5912,10 +6131,42 @@ export class InteractiveMode {
             `scope: ${scope}`,
             `provider: ${this.getSemanticSetupProviderLabel(providerType)}`,
             `model: ${nextProvider.model}`,
+            `auto_index: ${nextConfig.autoIndex ? "on" : "off"}`,
             `config: ${savedPath}`,
             `index_dir: ${getSemanticIndexDir(cwd, agentDir)}`,
         ].join("\n"));
     }
+    resolveSemanticAutoIndexWriteScope(cwd, agentDir) {
+        const project = readScopedSemanticConfig("project", cwd, agentDir);
+        if (!project.error && project.file.semanticSearch) {
+            return "project";
+        }
+        return "user";
+    }
+    async updateSemanticAutoIndexSetting(options) {
+        const cwd = this.sessionManager.getCwd();
+        const agentDir = getAgentDir();
+        const merged = loadMergedSemanticConfig(cwd, agentDir);
+        if (!merged.config) {
+            this.showWarning("Semantic search is not configured. Run /semantic setup first.");
+            return;
+        }
+        const scope = options?.scope ?? this.resolveSemanticAutoIndexWriteScope(cwd, agentDir);
+        const value = options?.value ?? !merged.config.autoIndex;
+        const nextConfig = {
+            ...merged.config,
+            autoIndex: value,
+        };
+        const savedPath = upsertScopedSemanticSearchConfig(scope, nextConfig, cwd, agentDir);
+        const effective = await this.createSemanticRuntime().status().catch(() => undefined);
+        this.showStatus(`Semantic auto-index ${value ? "enabled" : "disabled"} (${scope}).`);
+        this.showCommandTextBlock("Semantic Auto-Index", [
+            `scope: ${scope}`,
+            `saved: ${value ? "on" : "off"}`,
+            `effective: ${effective ? (effective.autoIndex ? "on" : "off") : "unknown"}`,
+            `config: ${savedPath}`,
+        ].join("\n"));
+    }
     async runSemanticInteractiveMenu() {
         while (true) {
             let status;
@@ -5926,7 +6177,7 @@ export class InteractiveMode {
                 this.reportSemanticError(error, "status");
             }
             const summary = status
-                ? `configured=${status.configured ? "yes" : "no"} indexed=${status.indexed ? "yes" : "no"} stale=${status.stale ? "yes" : "no"}`
+                ? `configured=${status.configured ? "yes" : "no"} auto_index=${status.autoIndex ? "on" : "off"} indexed=${status.indexed ? "yes" : "no"} stale=${status.stale ? "yes" : "no"}`
                 : "status unavailable";
             const selected = await this.showExtensionSelector(`/semantic manager\n${summary}`, [
                 "Configure provider/model",
@@ -5934,6 +6185,7 @@ export class InteractiveMode {
                 "Index now",
                 "Rebuild index",
                 "Query index",
+                `Automatic indexing: ${status?.autoIndex ? "on" : "off"}`,
                 "Show config/index paths",
                 "Close",
             ]);
@@ -6007,6 +6259,10 @@ export class InteractiveMode {
                 }
                 continue;
             }
+            if (selected.startsWith("Automatic indexing:")) {
+                await this.updateSemanticAutoIndexSetting();
+                continue;
+            }
             if (selected === "Show config/index paths") {
                 const runtime = this.createSemanticRuntime();
                 const cwd = this.sessionManager.getCwd();
@@ -6036,6 +6292,11 @@ export class InteractiveMode {
             ].join("\n"));
             return;
         }
+        if (error instanceof SemanticIndexRequiredError) {
+            this.showWarning(error.message);
+            this.showWarning("Run /semantic index (or enable automatic indexing in /semantic).");
+            return;
+        }
         if (error instanceof SemanticRebuildRequiredError) {
             this.showWarning(error.message);
             this.showWarning("Run /semantic rebuild.");
@@ -6058,6 +6319,7 @@ export class InteractiveMode {
                 "  /semantic",
                 "  /semantic ui",
                 "  /semantic setup [--scope user|project]",
+                "  /semantic auto-index [on|off] [--scope user|project]",
                 "  /semantic status",
                 "  /semantic index",
                 "  /semantic rebuild",
@@ -6079,6 +6341,34 @@ export class InteractiveMode {
             await this.runSemanticSetupWizard(parsedScope.scope);
             return;
         }
+        if (subcommand === "auto-index" || subcommand === "autoindex") {
+            const parsedScope = this.parseSemanticScopeOptions(rest, "Usage: /semantic auto-index [on|off] [--scope user|project]");
+            if (parsedScope.error) {
+                this.showWarning(parsedScope.error);
+                return;
+            }
+            let value;
+            if (parsedScope.rest.length > 1) {
+                this.showWarning("Usage: /semantic auto-index [on|off] [--scope user|project]");
+                return;
+            }
+            if (parsedScope.rest.length === 1) {
+                const mode = parsedScope.rest[0]?.toLowerCase();
+                if (mode === "on" || mode === "enable" || mode === "enabled")
+                    value = true;
+                else if (mode === "off" || mode === "disable" || mode === "disabled")
+                    value = false;
+                else {
+                    this.showWarning(`Unknown auto-index mode "${parsedScope.rest[0]}". Use on|off.`);
+                    return;
+                }
+            }
+            await this.updateSemanticAutoIndexSetting({
+                scope: parsedScope.scope,
+                value,
+            });
+            return;
+        }
         if (subcommand === "status") {
             try {
                 const result = await this.runWithExtensionLoader("Checking semantic index status...", async () => this.createSemanticRuntime().status());
@@ -6133,6 +6423,962 @@ export class InteractiveMode {
         }
         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;
@@ -6315,6 +7561,7 @@ export class InteractiveMode {
             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 = [];
@@ -6331,6 +7578,9 @@ export class InteractiveMode {
             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");
             }
@@ -6365,6 +7615,10 @@ export class InteractiveMode {
                 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");
@@ -6381,6 +7635,8 @@ export class InteractiveMode {
                 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)}`,
@@ -6419,6 +7675,14 @@ export class InteractiveMode {
         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) {
@@ -6483,8 +7747,21 @@ export class InteractiveMode {
             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} · files=${semanticStatus.files} chunks=${semanticStatus.chunks}`);
+            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(", ")}.`);
         }
@@ -6948,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();
@@ -6962,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);
@@ -9281,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();
@@ -9296,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();