@ai-agent-forge/agent-forge 0.85.0

package/dist/main.js

@@ -0,0 +1,1630 @@
+/**
+ * Main entry point for the coding agent CLI.
+ *
+ * This file handles CLI argument parsing and translates them into
+ * createAgentSession() options. The SDK does the heavy lifting.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import { modelsAreEqual } from "@agent-forge/ai";
+import { setCapabilityOverrides } from "@agent-forge/tui";
+import chalk from "chalk";
+import { isValidHostLogLevel, normalizeSessionName, parseArgs, printHelp } from "./cli/args.js";
+import { checkProviderAuth, createAuthCheckModelRuntime, getProviderCredential, } from "./cli/auth-check.js";
+import { AuthCommandError, getAuthCommandName, getAuthCommandUsage, isAuthCommandHelp, parseAuthCommand, printAuthCommandHelp, validateAuthCommandArgs, } from "./cli/auth-command.js";
+import { resolveCredentialForPrint } from "./cli/credential-print.js";
+import { processFileArguments } from "./cli/file-processor.js";
+import { buildInitialMessage } from "./cli/initial-message.js";
+import { listModels } from "./cli/list-models.js";
+import { handlePluginEcosystemCommand } from "./cli/plugin-command.js";
+import { runServeMode } from "./cli/serve.js";
+import { resolveSessionPath, selectSession } from "./cli/session-picker.js";
+import { shouldRunFirstTimeSetup, showFirstTimeSetup, showStartupSelector } from "./cli/startup-ui.js";
+import { runTraceView } from "./cli/trace-view.js";
+import { APP_NAME, CONFIG_DIR_NAME, ENV_SESSION_DIR, expandTildePath, getAgentDir, getPackageDir, getSessionsDir, VERSION, } from "./config.js";
+import { createAgentSessionRuntime } from "./core/agent-session-runtime.js";
+import { createAgentSessionFromServices, createAgentSessionServices, } from "./core/agent-session-services.js";
+import { formatNoModelsAvailableMessage } from "./core/auth-guidance.js";
+import { AuthStorage, ReadOnlyAuthStorage } from "./core/auth-storage.js";
+import { exportFromFile } from "./core/export-html/index.js";
+import { applyHttpProxySettings, configureHttpDispatcher } from "./core/http-dispatcher.js";
+import { createHostLogger } from "./core/logger.js";
+import { resolveCliModel, resolveModelScope } from "./core/model-resolver.js";
+import { ModelRuntime } from "./core/model-runtime.js";
+import { restoreStdout, takeOverStdout } from "./core/output-guard.js";
+import { formatMissingSessionCwdPrompt, getMissingSessionCwdIssue, MissingSessionCwdError, } from "./core/session-cwd.js";
+import { assertValidSessionId, SessionManager } from "./core/session-manager.js";
+import { collectSettingsDiagnostics, deduplicateDiagnostics } from "./core/settings-diagnostics.js";
+import { SettingsManager } from "./core/settings-manager.js";
+import { sweepTraceFiles } from "./core/trace-retention.js";
+import { createDefaultActivePluginBindingsResolverV1, defaultPluginHostFactsV1, } from "./plugins/ecosystem/default-active-bindings.js";
+import { runNodePluginBootstrapV1 } from "./plugins/ecosystem/node-plugin-bootstrap.js";
+import { createPluginSelectionStoreV1 } from "./plugins/ecosystem/selection-store.js";
+import { defaultBuiltinVerifiedPluginsV1, listBuiltinPluginProfilesV1, } from "./profile/plugin-profiles.js";
+import { isBuiltinSuiteId } from "./profiles/builtin-suites.js";
+import { clearDanglingSuiteSettings, createSuite, deleteSuite, findSuiteSessionRefs, releaseTrashedSuite, resetSuite, SuiteLifecycleError, sweepSuiteTrash, } from "./profiles/suite-lifecycle.js";
+import { getSuiteWorkspaceDir, listSuiteIds, SUITE_ENV_VAR, SUITE_MANIFEST_FILENAME, SuiteRebindError, SuiteResolutionError, } from "./profiles/suite-loader.js";
+import { createSubagentMailbox, createTurnProgressSourceV1 } from "@agent-forge/protocol/subagent";
+import { agentSessionsDir } from "./core/agent-session-paths.js";
+import { findSessionFile, readAgentSession } from "./core/agent-session-store.js";
+import { parseAgentTaskChildProfileV1, } from "./core/extensions/public-api.js";
+import { printTimings, resetTimings, time } from "./core/timings.js";
+import { runMigrations, showDeprecationWarnings } from "./migrations.js";
+import { InteractiveMode, runPrintMode, runRpcMode } from "./modes/index.js";
+import { initTheme, stopThemeWatcher } from "./modes/interactive/theme/theme.js";
+import { cleanupManagedInstall, handleConfigCommand, handlePackageCommand } from "./package-manager-cli.js";
+import { runSubagentTaskRunner } from "./plugins/subagent-task/runner-entry.js";
+import { createSubagentTaskSessionFactoryV1 } from "./plugins/subagent-task/session-factory.js";
+import { isLocalPath, normalizePath, resolvePath } from "./utils/paths.js";
+import { cleanupWindowsSelfUpdateQuarantine } from "./utils/windows-self-update.js";
+/**
+ * Process-level host logger (设计 §5), created lazily by {@link main}. The
+ * logger owns the process-wide uncaughtException/unhandledRejection hooks, so
+ * repeated `main()` invocations (tests, embedding loops) must reuse the first
+ * instance instead of accumulating listeners.
+ */
+let processHostLogger;
+/**
+ * Read all content from piped stdin.
+ * Returns undefined if stdin is a TTY (interactive terminal).
+ */
+async function readPipedStdin() {
+    // If stdin is a TTY, we're running interactively - don't read stdin
+    if (process.stdin.isTTY) {
+        return undefined;
+    }
+    return new Promise((resolve) => {
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on("end", () => {
+            resolve(data.trim() || undefined);
+        });
+        process.stdin.resume();
+    });
+}
+/**
+ * Suite 漂移/升级提示降噪（借鉴 lastChangelogVersion 的"记已见版本"模式）：
+ * 同一 suite 的同版本漂移/升级诊断只呈现一次——首次见到时保留并记录 ack，
+ * 之后相同指纹的提示在启动面静默（诊断仍可经 /debug 面查看）。新指纹
+ * （锁内容变化、更高的 factory revision）会重新提示。
+ */
+function filterAcknowledgedSuiteNotices(diagnostics, settingsManager) {
+    const driftPattern = /^Suite "([^"]+)" profile lock (drift|migration required): (.+)$/;
+    const upgradePattern = /^Suite "([^"]+)": factory revision (\d+) available/;
+    const kept = [];
+    for (const diagnostic of diagnostics) {
+        const drift = driftPattern.exec(diagnostic.message);
+        const upgrade = drift === null ? upgradePattern.exec(diagnostic.message) : undefined;
+        if (drift === null && upgrade === null) {
+            kept.push(diagnostic);
+            continue;
+        }
+        const upgradeRevisionMatch = upgrade?.[2];
+        const suiteId = drift?.[1] ?? upgrade?.[1];
+        if (suiteId === undefined) {
+            kept.push(diagnostic);
+            continue;
+        }
+        const previous = settingsManager.getSuiteNoticeAcknowledgement(suiteId);
+        if (drift !== null) {
+            const digest = drift[3] ?? "";
+            if (previous?.driftDigest === digest)
+                continue;
+            settingsManager.setSuiteNoticeAcknowledgement(suiteId, {
+                ...(previous ?? {}),
+                driftDigest: digest,
+            });
+        }
+        else if (upgrade !== null && upgradeRevisionMatch !== undefined) {
+            const revision = Number.parseInt(upgradeRevisionMatch, 10);
+            if (previous?.upgradeRevision !== undefined && previous.upgradeRevision >= revision)
+                continue;
+            settingsManager.setSuiteNoticeAcknowledgement(suiteId, {
+                ...(previous ?? {}),
+                upgradeRevision: revision,
+            });
+        }
+        kept.push(diagnostic);
+    }
+    return kept;
+}
+function reportDiagnostics(diagnostics) {
+    for (const diagnostic of diagnostics) {
+        const color = diagnostic.type === "error" ? chalk.red : diagnostic.type === "warning" ? chalk.yellow : chalk.dim;
+        const prefix = diagnostic.type === "error" ? "Error: " : diagnostic.type === "warning" ? "Warning: " : "";
+        console.error(color(`${prefix}${diagnostic.message}`));
+    }
+}
+function isTruthyEnvFlag(value) {
+    if (!value)
+        return false;
+    return value === "1" || value.toLowerCase() === "true" || value.toLowerCase() === "yes";
+}
+function resolveAppMode(parsed, stdinIsTTY, stdoutIsTTY) {
+    // Headless subagent runner (D-045): stdout is the subagent-task protocol
+    // channel, so this mode must never classify as interactive.
+    if (parsed.subagentRunner === true) {
+        return "print";
+    }
+    if (parsed.mode === "rpc") {
+        return "rpc";
+    }
+    if (parsed.mode === "json") {
+        return "json";
+    }
+    if (parsed.print || !stdinIsTTY || !stdoutIsTTY) {
+        return "print";
+    }
+    return "interactive";
+}
+function toPrintOutputMode(appMode) {
+    return appMode === "json" ? "json" : "text";
+}
+function isPlainRuntimeMetadataCommand(parsed) {
+    return !parsed.print && parsed.mode === undefined && (parsed.help === true || parsed.listModels !== undefined);
+}
+async function runAuthCommand(args) {
+    if (isAuthCommandHelp(args)) {
+        printAuthCommandHelp();
+        return true;
+    }
+    let command;
+    try {
+        command = parseAuthCommand(args);
+    }
+    catch (error) {
+        const message = error instanceof AuthCommandError ? error.message : "Failed to parse auth command";
+        console.error(chalk.red(`Error: ${message}`));
+        process.exitCode = 1;
+        return true;
+    }
+    if (!command)
+        return false;
+    const parsed = parseArgs(command.args);
+    // Unknown long options keep the dedicated "Invalid arguments" surface; every
+    // other parse diagnostic keeps the auth-check failure semantics (exit 2 for
+    // `auth check`) via the AuthCommandError path inside the try below.
+    const unknownLongOptions = parsed.diagnostics.filter((diagnostic) => diagnostic.message.startsWith("Unknown option: --"));
+    if (unknownLongOptions.length > 0) {
+        for (const diagnostic of unknownLongOptions) {
+            console.error(chalk.red(`Error: ${diagnostic.message}`));
+        }
+        console.error(chalk.red(`Invalid arguments for "${getAuthCommandName(command.kind)}".`));
+        console.error(chalk.dim(`Use "${APP_NAME} --help" or "${getAuthCommandUsage(command.kind)}".`));
+        process.exitCode = 1;
+        return true;
+    }
+    try {
+        if (parsed.diagnostics.length > 0) {
+            throw new AuthCommandError(parsed.diagnostics.map((diagnostic) => diagnostic.message).join("\n"));
+        }
+        if (command.kind !== "check") {
+            const signal = AbortSignal.timeout(15_000);
+            const modelRuntime = await ModelRuntime.create({ allowModelNetwork: false, signal });
+            const credential = await resolveCredentialForPrint(parsed, modelRuntime, command.kind, command.minExpiryMs, signal);
+            process.stdout.write(`${credential}\n`);
+            return true;
+        }
+        const requestedAuth = validateAuthCommandArgs(parsed, command.kind);
+        let result;
+        let credential;
+        try {
+            const credentials = command.noRefresh ? new ReadOnlyAuthStorage() : AuthStorage.create();
+            const modelRuntime = await createAuthCheckModelRuntime(credentials);
+            result = await checkProviderAuth(parsed, modelRuntime, { refresh: !command.noRefresh });
+            if (command.credentials && result.status === "ready") {
+                credential = await getProviderCredential(result.provider, modelRuntime, credentials, {
+                    refresh: !command.noRefresh,
+                });
+                if (!credential) {
+                    result = { status: "not_ready", provider: result.provider, reason: "credential_not_available" };
+                }
+            }
+        }
+        catch {
+            result = {
+                status: "invalid",
+                provider: requestedAuth.provider ?? requestedAuth.model,
+                reason: "invalid_state",
+            };
+        }
+        const output = command.json
+            ? JSON.stringify({ ...result, ...(credential ? { credentials: credential } : {}) })
+            : (credential ?? result.status);
+        process.stdout.write(`${output}\n`);
+        process.exitCode = result.status === "ready" ? 0 : result.status === "not_ready" ? 1 : 2;
+    }
+    catch (error) {
+        const message = error instanceof AuthCommandError ? error.message : "Failed to resolve credential";
+        console.error(chalk.red(`Error: ${message}`));
+        process.exitCode = command.kind === "check" ? 2 : 1;
+    }
+    return true;
+}
+async function prepareInitialMessage(parsed, autoResizeImages, stdinContent) {
+    if (parsed.fileArgs.length === 0) {
+        return buildInitialMessage({ parsed, stdinContent });
+    }
+    const { text, images } = await processFileArguments(parsed.fileArgs, { autoResizeImages });
+    return buildInitialMessage({
+        parsed,
+        fileText: text,
+        fileImages: images,
+        stdinContent,
+    });
+}
+async function findLocalSessionByExactId(sessionId, cwd, sessionDir) {
+    const localSessions = await SessionManager.list(cwd, sessionDir);
+    const localMatch = localSessions.find((s) => s.id === sessionId);
+    return localMatch ? { type: "local", path: localMatch.path } : undefined;
+}
+/** Prompt user for yes/no confirmation */
+async function promptConfirm(message) {
+    return new Promise((resolve) => {
+        const rl = createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        rl.question(`${message} [y/N] `, (answer) => {
+            rl.close();
+            resolve(answer.toLowerCase() === "y" || answer.toLowerCase() === "yes");
+        });
+    });
+}
+function printSuiteLifecycleError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(chalk.red(`Error: ${message}`));
+}
+function suiteWorkspaceExists(agentDir, id) {
+    return existsSync(join(getSuiteWorkspaceDir(agentDir, id), SUITE_MANIFEST_FILENAME));
+}
+/**
+ * Suite lifecycle one-shot actions (设计 §9, M4): --suite-create/--suite-delete/
+ * --suite-reset. Every performed action terminates the process; without any
+ * lifecycle flag this returns and startup continues. Non-interactive stdin
+ * refuses destructive actions (safe default).
+ */
+async function handleSuiteLifecycleCommands(parsed, cwd, agentDir) {
+    if (parsed.suiteCreate !== undefined) {
+        try {
+            const result = createSuite({
+                agentDir,
+                id: parsed.suiteCreate,
+                ...(parsed.cloneFrom === undefined ? {} : { cloneFrom: parsed.cloneFrom }),
+            });
+            console.log(`Created suite "${result.suiteId}" at ${result.suiteDir}`);
+        }
+        catch (error) {
+            printSuiteLifecycleError(error);
+            process.exit(1);
+        }
+        process.exit(0);
+    }
+    if (parsed.cloneFrom !== undefined) {
+        console.error(chalk.red("Error: --clone-from requires --suite-create"));
+        process.exit(1);
+    }
+    if (parsed.suiteDelete !== undefined) {
+        const id = parsed.suiteDelete;
+        if (isBuiltinSuiteId(id)) {
+            printSuiteLifecycleError(new SuiteLifecycleError("delete", id, [`builtin suite "${id}" cannot be deleted`]));
+            process.exit(1);
+        }
+        if (!suiteWorkspaceExists(agentDir, id)) {
+            printSuiteLifecycleError(new SuiteResolutionError(id, listSuiteIds(agentDir)));
+            process.exit(1);
+        }
+        const refs = findSuiteSessionRefs(agentDir, id);
+        if (refs.length > 0) {
+            console.error(chalk.red(`Error: suite "${id}" is referenced by ${refs.length} existing session(s); deletion refused:`));
+            for (const ref of refs) {
+                console.error(`  ${ref.sessionId}  ${ref.path}`);
+            }
+            process.exit(1);
+        }
+        const suiteDir = getSuiteWorkspaceDir(agentDir, id);
+        console.log(`Deleting suite "${id}": the workspace directory ${suiteDir} will be moved to the trash and released.`);
+        if (!process.stdin.isTTY) {
+            console.error(chalk.red(`Refusing to delete suite "${id}" without an interactive confirmation (non-interactive stdin). Re-run in a terminal to confirm.`));
+            process.exit(1);
+        }
+        if (!(await promptConfirm(`Delete suite "${id}"?`))) {
+            console.log(`Aborted: suite "${id}" was not deleted.`);
+            process.exit(1);
+        }
+        try {
+            const result = deleteSuite({ agentDir, id, refs });
+            const cleanup = clearDanglingSuiteSettings(SettingsManager.create(cwd, agentDir), id);
+            for (const scope of cleanup.clearedScopes) {
+                console.log(`Cleared the ${scope} settings "suite" key (pointed at "${id}").`);
+            }
+            releaseTrashedSuite(result.trashPath);
+            console.log(`Deleted suite "${id}"; the workspace was moved to ${result.trashPath} and is being released.`);
+        }
+        catch (error) {
+            printSuiteLifecycleError(error);
+            process.exit(1);
+        }
+        process.exit(0);
+    }
+    if (parsed.suiteReset !== undefined) {
+        const id = parsed.suiteReset;
+        if (!isBuiltinSuiteId(id)) {
+            const message = listSuiteIds(agentDir).includes(id)
+                ? `Suite "${id}" is a user suite; only builtin suites can be reset — use --suite-delete instead.`
+                : new SuiteResolutionError(id, listSuiteIds(agentDir)).message;
+            console.error(chalk.red(`Error: ${message}`));
+            process.exit(1);
+        }
+        try {
+            const plan = resetSuite({ agentDir, id });
+            if (plan.diffText.length === 0) {
+                console.log(`Suite "${id}" already matches the factory contents; nothing to reset.`);
+                process.exit(0);
+            }
+            console.log(`Resetting builtin suite "${id}" to the factory contents:\n`);
+            console.log(plan.diffText);
+            if (!process.stdin.isTTY) {
+                console.error(chalk.red(`Refusing to reset suite "${id}" without an interactive confirmation (non-interactive stdin). Review the diff above and re-run in a terminal to confirm.`));
+                process.exit(1);
+            }
+            if (!(await promptConfirm(`Apply reset of suite "${id}"?`))) {
+                console.log(`Aborted: suite "${id}" was not reset.`);
+                process.exit(1);
+            }
+            const result = plan.apply();
+            console.log(`Suite "${id}" was reset to the factory contents (profile lock generation ${result.lock.generation}).`);
+        }
+        catch (error) {
+            printSuiteLifecycleError(error);
+            process.exit(1);
+        }
+        process.exit(0);
+    }
+}
+function validateForkFlags(parsed) {
+    if (!parsed.fork)
+        return;
+    const conflictingFlags = [
+        parsed.session ? "--session" : undefined,
+        parsed.continue ? "--continue" : undefined,
+        parsed.resume ? "--resume" : undefined,
+        parsed.noSession ? "--no-session" : undefined,
+    ].filter((flag) => flag !== undefined);
+    if (conflictingFlags.length > 0) {
+        console.error(chalk.red(`Error: --fork cannot be combined with ${conflictingFlags.join(", ")}`));
+        process.exit(1);
+    }
+}
+function validateSessionIdFlags(parsed) {
+    if (parsed.sessionId === undefined)
+        return;
+    const conflictingFlags = [
+        parsed.session ? "--session" : undefined,
+        parsed.continue ? "--continue" : undefined,
+        parsed.resume ? "--resume" : undefined,
+    ].filter((flag) => flag !== undefined);
+    if (conflictingFlags.length > 0) {
+        console.error(chalk.red(`Error: --session-id cannot be combined with ${conflictingFlags.join(", ")}. To resume that exact session, drop the other flags and use --session-id alone (or use --continue to resume the most recent session).`));
+        process.exit(1);
+    }
+    try {
+        assertValidSessionId(parsed.sessionId);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(chalk.red(`Error: ${message}`));
+        process.exit(1);
+    }
+}
+function openSessionOrExit(path, sessionDir) {
+    try {
+        return SessionManager.open(path, sessionDir);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(chalk.red(`Error: ${message}`));
+        process.exit(1);
+    }
+}
+function forkSessionOrExit(sourcePath, cwd, sessionDir, sessionId) {
+    try {
+        return SessionManager.forkFrom(sourcePath, cwd, sessionDir, { id: sessionId });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(chalk.red(`Error: ${message}`));
+        process.exit(1);
+    }
+}
+export async function createSessionManager(parsed, cwd, sessionDir, settingsManager) {
+    if (parsed.noSession || parsed.help || parsed.listModels !== undefined) {
+        return SessionManager.inMemory(cwd, parsed.sessionId !== undefined ? { id: parsed.sessionId } : undefined);
+    }
+    if (parsed.fork) {
+        if (parsed.sessionId) {
+            const existingTarget = await findLocalSessionByExactId(parsed.sessionId, cwd, sessionDir);
+            if (existingTarget) {
+                console.error(chalk.red(`Session already exists with id '${parsed.sessionId}'`));
+                process.exit(1);
+            }
+        }
+        const resolved = await resolveSessionPath(parsed.fork, cwd, sessionDir);
+        switch (resolved.type) {
+            case "path":
+            case "local":
+            case "global":
+                return forkSessionOrExit(resolved.path, cwd, sessionDir, parsed.sessionId);
+            case "not_found":
+                console.error(chalk.red(`No session found matching '${resolved.arg}'`));
+                process.exit(1);
+        }
+    }
+    if (parsed.session) {
+        const resolved = await resolveSessionPath(parsed.session, cwd, sessionDir);
+        switch (resolved.type) {
+            case "path":
+            case "local":
+                return openSessionOrExit(resolved.path, sessionDir);
+            case "global": {
+                console.log(chalk.yellow(`Session found in different project: ${resolved.cwd}`));
+                const shouldFork = await promptConfirm("Fork this session into current directory?");
+                if (!shouldFork) {
+                    console.log(chalk.dim("Aborted."));
+                    process.exit(0);
+                }
+                return forkSessionOrExit(resolved.path, cwd, sessionDir);
+            }
+            case "not_found":
+                console.error(chalk.red(`No session found matching '${resolved.arg}'`));
+                process.exit(1);
+        }
+    }
+    if (parsed.resume) {
+        try {
+            const selectedPath = await selectSession((onProgress) => SessionManager.list(cwd, sessionDir, onProgress), (onProgress) => SessionManager.listAll(sessionDir, onProgress), settingsManager);
+            if (!selectedPath) {
+                console.log(chalk.dim("No session selected"));
+                process.exit(0);
+            }
+            return SessionManager.open(selectedPath, sessionDir);
+        }
+        finally {
+            stopThemeWatcher();
+        }
+    }
+    if (parsed.continue) {
+        return SessionManager.continueRecent(cwd, sessionDir);
+    }
+    if (parsed.sessionId) {
+        const existingSession = await findLocalSessionByExactId(parsed.sessionId, cwd, sessionDir);
+        if (existingSession) {
+            return SessionManager.open(existingSession.path, sessionDir);
+        }
+        console.error(chalk.yellow(`Warning: No project session found with id '${parsed.sessionId}'; creating a new session with that id.`));
+    }
+    return SessionManager.create(cwd, sessionDir, { id: parsed.sessionId });
+}
+function buildSessionOptions(parsed, scopedModels, hasExistingSession, modelRuntime, settingsManager) {
+    const options = {};
+    const diagnostics = [];
+    let cliThinkingFromModel = false;
+    // Model from CLI
+    // - supports --provider <name> --model <pattern>
+    // - supports --model <provider>/<pattern>
+    if (parsed.model) {
+        const resolved = resolveCliModel({
+            cliProvider: parsed.provider,
+            cliModel: parsed.model,
+            cliThinking: parsed.thinking,
+            modelRuntime,
+        });
+        if (resolved.warning) {
+            diagnostics.push({ type: "warning", message: resolved.warning });
+        }
+        if (resolved.error) {
+            diagnostics.push({ type: "error", message: resolved.error });
+        }
+        if (resolved.model) {
+            options.model = resolved.model;
+            // Allow "--model <pattern>:<thinking>" as a shorthand.
+            // Explicit --thinking still takes precedence (applied later).
+            if (!parsed.thinking && resolved.thinkingLevel) {
+                options.thinkingLevel = resolved.thinkingLevel;
+                cliThinkingFromModel = true;
+            }
+        }
+    }
+    if (!options.model && scopedModels.length > 0 && !hasExistingSession) {
+        // Check if saved default is in scoped models - use it if so, otherwise first scoped model
+        const savedProvider = settingsManager.getDefaultProvider();
+        const savedModelId = settingsManager.getDefaultModel();
+        const savedModel = savedProvider && savedModelId ? modelRuntime.getModel(savedProvider, savedModelId) : undefined;
+        const savedInScope = savedModel ? scopedModels.find((sm) => modelsAreEqual(sm.model, savedModel)) : undefined;
+        if (savedInScope) {
+            options.model = savedInScope.model;
+            // Use thinking level from scoped model config if explicitly set
+            if (!parsed.thinking && savedInScope.thinkingLevel) {
+                options.thinkingLevel = savedInScope.thinkingLevel;
+            }
+        }
+        else {
+            options.model = scopedModels[0].model;
+            // Use thinking level from first scoped model if explicitly set
+            if (!parsed.thinking && scopedModels[0].thinkingLevel) {
+                options.thinkingLevel = scopedModels[0].thinkingLevel;
+            }
+        }
+    }
+    // Thinking level from CLI (takes precedence over scoped model thinking levels set above)
+    if (parsed.thinking) {
+        options.thinkingLevel = parsed.thinking;
+    }
+    // Scoped models for Ctrl+P cycling
+    // Keep thinking level undefined when not explicitly set in the model pattern.
+    // Undefined means "inherit current session thinking level" during cycling.
+    if (scopedModels.length > 0) {
+        options.scopedModels = scopedModels.map((sm) => ({
+            model: sm.model,
+            thinkingLevel: sm.thinkingLevel,
+        }));
+    }
+    // API key from CLI - set as a non-persistent runtime override
+    // (handled by caller before createAgentSession)
+    // Tools
+    if (parsed.noTools) {
+        options.noTools = "all";
+    }
+    else if (parsed.noBuiltinTools) {
+        options.noTools = "builtin";
+    }
+    if (parsed.tools) {
+        options.tools = [...parsed.tools];
+    }
+    if (parsed.excludeTools) {
+        options.excludeTools = [...parsed.excludeTools];
+    }
+    if (parsed.suite) {
+        options.suite = parsed.suite;
+    }
+    return { options, cliThinkingFromModel, diagnostics };
+}
+function resolveCliPaths(cwd, paths) {
+    return paths?.map((value) => (isLocalPath(value) ? resolvePath(value, cwd) : value));
+}
+async function promptForMissingSessionCwd(issue, settingsManager) {
+    return showStartupSelector(settingsManager, formatMissingSessionCwdPrompt(issue), [
+        { label: "Continue", value: issue.fallbackCwd },
+        { label: "Cancel", value: undefined },
+    ]);
+}
+function isBuiltinPluginProfileId(value) {
+    return listBuiltinPluginProfilesV1().some((profile) => profile.id === value);
+}
+function selectionDiagnostics(status, diagnostics) {
+    return diagnostics.map((item) => ({
+        type: "error",
+        message: `Plugin selection ${status} (${item.code}): ${item.message}`,
+    }));
+}
+/**
+ * Resolve explicit CLI selection and the optional persisted profile snapshot.
+ * The store is deliberately not read for an ordinary run, so a user's saved
+ * plugin choices cannot silently change the default session surface.
+ */
+async function resolveCliPluginSelection(parsed, agentDir, cwd) {
+    const hasExplicitSelection = parsed.pluginProfile !== undefined ||
+        parsed.plugins !== undefined ||
+        parsed.disabledPlugins !== undefined ||
+        parsed.pluginSelectionScope !== undefined;
+    if (!hasExplicitSelection || parsed.noPlugins)
+        return { diagnostics: [] };
+    if (parsed.pluginProfile === undefined && parsed.plugins === undefined && parsed.disabledPlugins === undefined) {
+        return { diagnostics: [{ type: "error", message: "--plugin-scope requires an explicit plugin selection" }] };
+    }
+    const diagnostics = [];
+    const selectionScope = parsed.pluginSelectionScope ?? "global";
+    const selectionPath = selectionScope === "project"
+        ? join(cwd, CONFIG_DIR_NAME, ".plugin-selection.json")
+        : join(agentDir, ".plugin-selection.json");
+    const store = createPluginSelectionStoreV1({ filePath: selectionPath });
+    let persistedResult;
+    try {
+        persistedResult = await store.read();
+    }
+    catch {
+        diagnostics.push({ type: "error", message: "Plugin selection could not be read" });
+        return { diagnostics };
+    }
+    if (persistedResult.status === "invalid" || persistedResult.status === "cancelled") {
+        diagnostics.push(...selectionDiagnostics(persistedResult.status, persistedResult.diagnostics));
+        return { diagnostics };
+    }
+    const explicitProfileId = parsed.pluginProfile;
+    let profileId;
+    if (explicitProfileId !== undefined) {
+        if (!isBuiltinPluginProfileId(explicitProfileId)) {
+            diagnostics.push({ type: "error", message: `Unknown plugin profile: ${explicitProfileId}` });
+            return { diagnostics };
+        }
+        profileId = explicitProfileId;
+    }
+    let persistedSelection;
+    if (profileId !== undefined) {
+        persistedSelection = persistedResult.snapshot.selections.find((selection) => selection.profileId === profileId);
+    }
+    else if (parsed.plugins !== undefined || parsed.disabledPlugins !== undefined) {
+        if (persistedResult.snapshot.selections.length !== 1) {
+            diagnostics.push({
+                type: "error",
+                message: persistedResult.snapshot.selections.length === 0
+                    ? "--plugin/--disable-plugin requires --plugin-profile or one persisted plugin profile"
+                    : "--plugin/--disable-plugin requires --plugin-profile when multiple persisted profiles exist",
+            });
+            return { diagnostics };
+        }
+        persistedSelection = persistedResult.snapshot.selections[0];
+        if (persistedSelection !== undefined && isBuiltinPluginProfileId(persistedSelection.profileId)) {
+            profileId = persistedSelection.profileId;
+        }
+        else {
+            diagnostics.push({
+                type: "error",
+                message: `Unknown persisted plugin profile: ${persistedSelection?.profileId ?? ""}`,
+            });
+            return { diagnostics };
+        }
+    }
+    return {
+        ...(profileId === undefined ? {} : { profileId }),
+        ...(parsed.plugins !== undefined
+            ? { selectedPluginIds: Object.freeze([...parsed.plugins]) }
+            : persistedSelection === undefined
+                ? {}
+                : { selectedPluginIds: persistedSelection.selectedPluginIds }),
+        ...(parsed.disabledPlugins !== undefined
+            ? { disabledPluginIds: Object.freeze([...parsed.disabledPlugins]) }
+            : persistedSelection === undefined
+                ? {}
+                : { disabledPluginIds: persistedSelection.disabledPluginIds }),
+        diagnostics,
+    };
+}
+export async function main(args, options) {
+    resetTimings();
+    const offlineMode = args.includes("--offline") || isTruthyEnvFlag(process.env.AGENT_FORGE_OFFLINE);
+    if (offlineMode) {
+        process.env.AGENT_FORGE_OFFLINE = "1";
+        process.env.AGENT_FORGE_SKIP_VERSION_CHECK = "1";
+    }
+    if (await runAuthCommand(args)) {
+        return;
+    }
+    if (await handlePluginEcosystemCommand(args)) {
+        return;
+    }
+    if (process.platform === "win32") {
+        cleanupWindowsSelfUpdateQuarantine(getPackageDir());
+    }
+    cleanupManagedInstall();
+    const cwd = process.cwd();
+    const agentDir = getAgentDir();
+    const bootstrapSettingsManager = SettingsManager.create(cwd, agentDir);
+    applyHttpProxySettings(bootstrapSettingsManager.getGlobalSettings().httpProxy);
+    configureHttpDispatcher();
+    if (await handlePackageCommand(args)) {
+        const exitCode = process.exitCode ?? 0;
+        if (process.platform === "win32" && exitCode === 0 && args[0] === "update") {
+            // We normally prefer process.exit(0) for package commands so bad extensions cannot keep
+            // one-shot commands alive. On Windows, Node can assert after fetch() if process.exit(0)
+            // runs during teardown; let successful `pi update` drain naturally instead.
+            // https://github.com/nodejs/node/issues/56645
+            return;
+        }
+        process.exit(exitCode);
+        return;
+    }
+    const configCommandOptions = options?.pluginManagerController === undefined && options?.projectPluginManagerController === undefined
+        ? undefined
+        : {
+            ...(options?.pluginManagerController === undefined
+                ? {}
+                : { pluginManagerController: options.pluginManagerController }),
+            ...(options?.projectPluginManagerController === undefined
+                ? {}
+                : { projectPluginManagerController: options.projectPluginManagerController }),
+        };
+    if (await handleConfigCommand(args, configCommandOptions)) {
+        return;
+    }
+    const parsed = parseArgs(args);
+    if (parsed.diagnostics.length > 0) {
+        for (const d of parsed.diagnostics) {
+            const color = d.type === "error" ? chalk.red : chalk.yellow;
+            console.error(color(`${d.type === "error" ? "Error" : "Warning"}: ${d.message}`));
+        }
+        if (parsed.diagnostics.some((d) => d.type === "error")) {
+            process.exit(1);
+        }
+    }
+    time("parseArgs");
+    // 宿主进程日志（设计 §5）：目录随 agentDir（<agentDir>/logs），级别按
+    // --log-level → AGENT_FORGE_LOG_LEVEL → 默认 info 解析，保留窗口按
+    // AGENT_FORGE_LOG_MAX_AGE_DAYS 解析（缺省 14，非法值回退默认）。logger 自带
+    // uncaughtException/unhandledRejection 钩子（默认挂真实 process），一次性命令
+    // 与 serve 模式同样获得崩溃兜底日志；logger 句柄无需显式 close（进程生命周期）。
+    // 进程级单例：钩子随创建累积，重复创建会泄漏监听器；生产进程只 run 一次，
+    // 测试等重复入口复用首例（级别以首次解析为准）。
+    const envLogLevel = process.env.AGENT_FORGE_LOG_LEVEL;
+    const hostLogLevel = parsed.logLevel ?? (envLogLevel !== undefined && isValidHostLogLevel(envLogLevel) ? envLogLevel : undefined);
+    const rawLogMaxAgeDays = process.env.AGENT_FORGE_LOG_MAX_AGE_DAYS;
+    const hostLogMaxAgeDays = rawLogMaxAgeDays !== undefined && /^\d+$/.test(rawLogMaxAgeDays)
+        ? Number.parseInt(rawLogMaxAgeDays, 10)
+        : undefined;
+    if (processHostLogger === undefined) {
+        processHostLogger = createHostLogger({
+            dir: join(agentDir, "logs"),
+            ...(hostLogLevel === undefined ? {} : { level: hostLogLevel }),
+            ...(hostLogMaxAgeDays === undefined ? {} : { maxAgeDays: hostLogMaxAgeDays }),
+        });
+    }
+    // 轨迹保留（设计 §6）：AGENT_FORGE_TRACE_MAX_AGE_DAYS（>0 整数开启；缺省/非法 =
+    // 永久保留）。只清默认 sessions 根（根目录 + 一层子目录）下过期的 *.trace.jsonl，
+    // 永不触碰会话文件；自定义 sessionDir 不在清扫范围。删除事实经 hostLogger 可见：
+    // deleted>0 记 info，failed>0 记 warn。宿主启动一次性执行，失败不阻塞启动。
+    const rawTraceMaxAgeDays = process.env.AGENT_FORGE_TRACE_MAX_AGE_DAYS;
+    const traceMaxAgeDays = rawTraceMaxAgeDays !== undefined && /^\d+$/.test(rawTraceMaxAgeDays)
+        ? Number.parseInt(rawTraceMaxAgeDays, 10)
+        : 0;
+    if (traceMaxAgeDays > 0) {
+        const traceSweep = sweepTraceFiles(getSessionsDir(), { maxAgeDays: traceMaxAgeDays, now: Date.now });
+        if (traceSweep.deleted > 0) {
+            processHostLogger.info("retention", "trace sweep removed expired trace files", {
+                fields: { deleted: traceSweep.deleted, failed: traceSweep.failed },
+            });
+        }
+        if (traceSweep.failed > 0) {
+            processHostLogger.warn("retention", "trace sweep finished with failures", {
+                fields: { deleted: traceSweep.deleted, failed: traceSweep.failed },
+            });
+        }
+    }
+    if (parsed.version) {
+        console.log(VERSION);
+        process.exit(0);
+    }
+    if (parsed.export) {
+        let result;
+        try {
+            const outputPath = parsed.messages.length > 0 ? parsed.messages[0] : undefined;
+            result = await exportFromFile(parsed.export, outputPath);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Failed to export session";
+            console.error(chalk.red(`Error: ${message}`));
+            process.exit(1);
+        }
+        console.log(`Exported to: ${result}`);
+        process.exit(0);
+    }
+    // Trace viewer (设计 §8 第 3 期): same exit-style dispatch as --export above,
+    // which also wins when both are given. The view command needs no runtime
+    // service, so it runs before any session/manager creation; per the --export
+    // precedent it is not registered in the --serve conflictingFlags list (this
+    // dispatch exits before that check is reached).
+    if (parsed.trace !== undefined) {
+        const envSessionDir = process.env[ENV_SESSION_DIR];
+        const sessionDir = (parsed.sessionDir ? normalizePath(parsed.sessionDir) : undefined) ??
+            (envSessionDir ? expandTildePath(envSessionDir) : undefined) ??
+            bootstrapSettingsManager.getSessionDir();
+        const result = await runTraceView(parsed.trace, {
+            json: parsed.traceJson === true,
+            cwd,
+            ...(sessionDir === undefined ? {} : { sessionDir }),
+            ...(parsed.traceKind === undefined ? {} : { kinds: parsed.traceKind }),
+            ...(parsed.traceLimit === undefined ? {} : { limit: parsed.traceLimit }),
+        });
+        if (!result.ok) {
+            console.error(chalk.red(`Error: ${result.message}`));
+            process.exit(1);
+        }
+        process.exit(0);
+    }
+    // Remote server mode (E3 tail): serve the coding-agent session runtime over
+    // TCP and keep the process alive; no session manager or runtime is needed
+    // for startup, so this runs before any session/runtime service is created.
+    if (parsed.serve !== undefined) {
+        // help/listModels must win over starting the server, and the generic
+        // handlers below need the full runtime that serve mode deliberately
+        // never creates; answer them here with the same output instead.
+        if (parsed.help || parsed.listModels !== undefined) {
+            // Align with the generic path: migrate legacy settings first so the
+            // reported diagnostics reflect the post-migration state.
+            runMigrations(cwd);
+            reportDiagnostics(collectSettingsDiagnostics(bootstrapSettingsManager));
+            if (parsed.help) {
+                // Extension CLI flags are registered by the resource loader, which
+                // serve mode never builds; the generic help text stays accurate.
+                printHelp();
+                process.exit(0);
+            }
+            const modelRuntime = await ModelRuntime.create({ signal: AbortSignal.timeout(15_000) });
+            const searchPattern = typeof parsed.listModels === "string" ? parsed.listModels : undefined;
+            await listModels(modelRuntime, searchPattern, AbortSignal.timeout(15_000));
+            process.exit(0);
+        }
+        // Prompt/session inputs would silently change nothing in serve mode, so
+        // reject them up front with the concrete conflicting flags.
+        const conflictingFlags = [
+            parsed.print ? "--print" : undefined,
+            parsed.messages.length > 0 ? "positional args" : undefined,
+            parsed.fileArgs.length > 0 ? "@file args" : undefined,
+            parsed.continue ? "--continue" : undefined,
+            parsed.resume ? "--resume" : undefined,
+            parsed.session ? "--session" : undefined,
+            parsed.sessionId ? "--session-id" : undefined,
+            parsed.fork ? "--fork" : undefined,
+            parsed.noSession ? "--no-session" : undefined,
+            parsed.mode ? "--mode" : undefined,
+            parsed.suiteCreate ? "--suite-create" : undefined,
+            parsed.suiteDelete ? "--suite-delete" : undefined,
+            parsed.suiteReset ? "--suite-reset" : undefined,
+            parsed.cloneFrom ? "--clone-from" : undefined,
+        ].filter((flag) => flag !== undefined);
+        if (conflictingFlags.length > 0) {
+            console.error(chalk.red(`Error: --serve cannot be combined with ${conflictingFlags.join(", ")}`));
+            process.exit(1);
+        }
+        // Remaining options would be silently ignored; list the ones the user
+        // actually passed so nothing disappears without a trace.
+        const ignoredFlagChecks = [
+            ["--name", parsed.name !== undefined],
+            ["--thinking", parsed.thinking !== undefined],
+            ["--provider", parsed.provider !== undefined],
+            ["--model", parsed.model !== undefined],
+            ["--api-key", parsed.apiKey !== undefined],
+            ["--models", (parsed.models?.length ?? 0) > 0],
+            ["--verbose", parsed.verbose === true],
+            ["--tui-mode", parsed.tuiMode !== undefined],
+            ["--suite", parsed.suite !== undefined],
+            ["--tools", (parsed.tools?.length ?? 0) > 0],
+            ["--exclude-tools", (parsed.excludeTools?.length ?? 0) > 0],
+            ["--no-tools", parsed.noTools === true],
+            ["--no-builtin-tools", parsed.noBuiltinTools === true],
+            ["--skill", (parsed.skills?.length ?? 0) > 0],
+            ["--prompt-template", (parsed.promptTemplates?.length ?? 0) > 0],
+            ["--no-prompt-templates", parsed.noPromptTemplates === true],
+            ["--theme", (parsed.themes?.length ?? 0) > 0],
+            ["--use-theme", parsed.useTheme !== undefined],
+            ["--no-themes", parsed.noThemes === true],
+            ["--no-context-files", parsed.noContextFiles === true],
+            ["--no-skills", parsed.noSkills === true],
+            ["--no-plugins", parsed.noPlugins === true],
+            ["--no-trace", parsed.noTrace === true],
+            ["--plugin-profile", parsed.pluginProfile !== undefined],
+            ["--plugin", (parsed.plugins?.length ?? 0) > 0],
+            ["--disable-plugin", (parsed.disabledPlugins?.length ?? 0) > 0],
+            ["--system-prompt", parsed.systemPrompt !== undefined],
+            ["--append-system-prompt", (parsed.appendSystemPrompt?.length ?? 0) > 0],
+        ];
+        const ignoredFlags = ignoredFlagChecks.flatMap(([flag, passed]) => (passed ? [flag] : []));
+        if (ignoredFlags.length > 0) {
+            console.warn(chalk.yellow(`--serve ignores session/model/tool options: ${ignoredFlags.join(", ")}`));
+        }
+        await runServeMode(parsed.serve, {
+            ...(parsed.serveWorkspaceRoots === undefined ? {} : { workspaceRoots: parsed.serveWorkspaceRoots }),
+            ...(parsed.sessionDir === undefined ? {} : { sessionDir: parsed.sessionDir }),
+            // D-067 第一期 S3：serve 会话此前拿不到进程文件 logger（SDK 面为 no-op），
+            // 现在与交互模式同源注入，日志落 <agentDir>/logs。
+            ...(processHostLogger === undefined ? {} : { hostLogger: processHostLogger }),
+        });
+        return;
+    }
+    // Suite lifecycle one-shot actions (设计 §9, M4): only cwd + agentDir are
+    // needed, so they run before any session/runtime service is created and
+    // always terminate the process.
+    await handleSuiteLifecycleCommands(parsed, cwd, agentDir);
+    // Expired suite trash sweep (设计 §9, M4): fire-and-forget best-effort like
+    // the RPC model catalog refresh below — failures stay silent (7-day default
+    // retention) and the sweep re-runs on the next start.
+    void sweepSuiteTrash(agentDir).catch(() => { });
+    let appMode = resolveAppMode(parsed, process.stdin.isTTY, process.stdout.isTTY);
+    // Headless subagent runner (D-045) owns its stdout: the subagent-task protocol
+    // frames must reach the parent on the real stdout, so the non-interactive
+    // stdout takeover (which redirects process.stdout writes to stderr) is skipped.
+    const shouldTakeOverStdout = parsed.subagentRunner !== true && appMode !== "interactive" && !isPlainRuntimeMetadataCommand(parsed);
+    if (shouldTakeOverStdout) {
+        takeOverStdout();
+    }
+    if (parsed.mode === "rpc" && parsed.fileArgs.length > 0) {
+        console.error(chalk.red("Error: @file arguments are not supported in RPC mode"));
+        process.exit(1);
+    }
+    validateForkFlags(parsed);
+    validateSessionIdFlags(parsed);
+    // Run migrations (pass cwd for project-local migrations)
+    const { migratedAuthProviders: migratedProviders, deprecationWarnings } = runMigrations(cwd);
+    time("runMigrations");
+    const startupSettingsManager = SettingsManager.create(cwd, agentDir);
+    const startupSettingsDiagnostics = collectSettingsDiagnostics(startupSettingsManager);
+    // Experimental first-time setup: theme choice and analytics opt-in.
+    // Runs before any runtime services are created so the chosen settings apply everywhere.
+    if (appMode === "interactive" && !parsed.help && parsed.listModels === undefined && shouldRunFirstTimeSetup()) {
+        await showFirstTimeSetup(startupSettingsManager);
+        time("firstTimeSetup");
+    }
+    if (appMode === "interactive" && parsed.useTheme !== undefined) {
+        startupSettingsManager.applyOverrides({ theme: parsed.useTheme });
+    }
+    // Decide the final runtime cwd before creating cwd-bound runtime services.
+    // --session and --resume may select a session from another project, so project-local
+    // settings, resources, provider registrations, and models must be resolved only after
+    // the target session cwd is known. The startup-cwd settings manager is used only for
+    // sessionDir lookup during session selection.
+    const envSessionDir = process.env[ENV_SESSION_DIR];
+    const sessionDir = (parsed.sessionDir ? normalizePath(parsed.sessionDir) : undefined) ??
+        (envSessionDir ? expandTildePath(envSessionDir) : undefined) ??
+        startupSettingsManager.getSessionDir();
+    let sessionManager = await createSessionManager(parsed, cwd, sessionDir, startupSettingsManager);
+    const missingSessionCwdIssue = getMissingSessionCwdIssue(sessionManager, cwd);
+    if (missingSessionCwdIssue) {
+        if (appMode === "interactive") {
+            const selectedCwd = await promptForMissingSessionCwd(missingSessionCwdIssue, startupSettingsManager);
+            if (!selectedCwd) {
+                process.exit(0);
+            }
+            sessionManager = SessionManager.open(missingSessionCwdIssue.sessionFile, sessionDir, selectedCwd);
+        }
+        else {
+            console.error(chalk.red(new MissingSessionCwdError(missingSessionCwdIssue).message));
+            process.exit(1);
+        }
+    }
+    if (parsed.name !== undefined) {
+        const name = normalizeSessionName(parsed.name);
+        if (name === undefined) {
+            console.error(chalk.red("Error: --name requires a non-empty value"));
+            process.exit(1);
+        }
+        sessionManager.appendSessionInfo(name);
+    }
+    time("createSessionManager");
+    const cliPluginSelection = await resolveCliPluginSelection(parsed, agentDir, sessionManager.getCwd());
+    const resolvedSkillPaths = resolveCliPaths(cwd, parsed.skills);
+    const resolvedPromptTemplatePaths = resolveCliPaths(cwd, parsed.promptTemplates);
+    const resolvedThemePaths = resolveCliPaths(cwd, parsed.themes);
+    // Interaction host wiring (1A.8): createRuntime builds sessions before the
+    // mode owns its UI, so the interactive/rpc modes install their
+    // InteractionHostV1 into a late-bound slot after construction. Prompts that
+    // arrive before installation settle as "unavailable"; notify is dropped
+    // (nothing is on screen to receive it yet).
+    const createInteractionHostSlot = () => {
+        let target;
+        return {
+            host: {
+                notify: (request) => target?.notify(request),
+                prompt: (request, context) => target ? target.prompt(request, context) : Promise.resolve({ status: "unavailable" }),
+            },
+            setTarget: (next) => {
+                target = next;
+            },
+        };
+    };
+    const interactionHostSlots = {
+        interactive: createInteractionHostSlot(),
+        rpc: createInteractionHostSlot(),
+    };
+    // 启动 bootstrap（设计 §4.4）：在 suite/profile 解析之前，把出厂清单里缺失的
+    // 第一方插件经 npm 装入安装店。每进程只跑一次（含本地幂等比对）；出厂清单
+    // 当前为空，即零依赖调用的 no-op。bootstrap 自身异常兜底为诊断结果，绝不阻断
+    // 启动；AGENT_FORGE_PLUGIN_BOOTSTRAP=off 在接线层完全跳过。
+    let startupPluginBootstrap;
+    const runStartupPluginBootstrap = (bootstrapCwd) => {
+        startupPluginBootstrap ??= runNodePluginBootstrapV1({ agentDir, cwd: bootstrapCwd }).catch((error) => ({
+            version: 1,
+            status: "failed",
+            actions: [],
+            diagnostics: [
+                {
+                    code: "bootstrap_failed",
+                    message: `Startup plugin bootstrap failed: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            durationMs: 0,
+        }));
+        return startupPluginBootstrap;
+    };
+    const createRuntime = async ({ cwd, agentDir, sessionManager, childProfile, childModelId, subagentCommunicationWiring, }) => {
+        const runtimeSettingsManager = SettingsManager.create(cwd, agentDir);
+        // Bootstrap 先于 active 解析执行（设计 §4.4 触发点）：新装入店的第一方插件
+        // 在下面的 bindings 解析中立即可见。诊断走启动 stderr 通道（与 parseArgs
+        // 诊断同风格）；installed/skipped 动作静默。
+        if (!parsed.noPlugins) {
+            const bootstrapResult = await runStartupPluginBootstrap(cwd);
+            for (const diagnostic of bootstrapResult.diagnostics) {
+                console.error(chalk.yellow(`Plugin bootstrap ${diagnostic.code}: ${diagnostic.message}`));
+            }
+        }
+        const resolveActivePluginBindings = options?.resolveActivePluginBindings ?? createDefaultActivePluginBindingsResolverV1();
+        let activeBindings;
+        let pluginBindingDiagnostics = [];
+        // Installed-code-loading is profile-INDEPENDENT (D-075 设计 §"已装插件
+        // 进会话"链路): suite capability packages and sdk-membership families
+        // (memory/observability) must surface whenever they are installed, even
+        // without a --plugin-profile selection — the pre-D-075 embedded registry
+        // gave the coding suite its goal/plan/todo tools unconditionally, and
+        // bootstrap (§4.4) exists to make them available out of the box.
+        if (!parsed.noPlugins && options?.manifestOverrides === undefined) {
+            try {
+                const resolvedBindings = await resolveActivePluginBindings({ cwd, agentDir });
+                activeBindings = resolvedBindings;
+                pluginBindingDiagnostics = resolvedBindings.diagnostics.map((item) => ({
+                    type: resolvedBindings.status === "unavailable" ? "warning" : "info",
+                    message: `Active plugin binding ${item.code}: ${item.message}`,
+                }));
+            }
+            catch {
+                pluginBindingDiagnostics = [
+                    { type: "error", message: "Active plugin binding resolver failed; no installed version was selected" },
+                ];
+            }
+        }
+        const activeManifestOverrides = activeBindings?.status === "ready" ? activeBindings.manifestOverrides : undefined;
+        const activeVerifiedPlugins = activeBindings?.status === "ready" ? activeBindings.verifiedPlugins : undefined;
+        // Installed-code-loading (D-075 S2): the verified active installations'
+        // plugin.json paths ride the same channel as manifestOverrides into the
+        // sdk's explicit candidate pool (membership-filtered there).
+        const activeInstalledCapabilityPlugins = activeBindings?.status === "ready"
+            ? [...activeBindings.installedManifestPaths].map(([pluginId, manifestPath]) => ({
+                pluginId,
+                manifestPath,
+            }))
+            : undefined;
+        // D-075 S3: category-A plugin code ships in independent packages loaded
+        // from the install store, so the CLI no longer wires host-side adapters
+        // (desktop UIA / lsp / test-runner) into a runtime bridge. Profile
+        // resolution still needs host facts to run the resolver's fail-closed
+        // platform checks, and the packaged plugins declare no host features or
+        // adapters (design §4.1), so the observed runtime facts are sufficient;
+        // host injection always wins.
+        const pluginHost = options?.pluginHost ??
+            (parsed.noPlugins || (cliPluginSelection.profileId === undefined && activeBindings === undefined)
+                ? undefined
+                : defaultPluginHostFactsV1());
+        // First-party plugins of an explicitly selected Profile are trusted by
+        // default (the builtins ship with the product and the user chose the
+        // Profile explicitly); installed third-party versions still come from
+        // the disk resolver and host injection always wins.
+        const verifiedPlugins = options?.verifiedPlugins ??
+            (cliPluginSelection.profileId === undefined
+                ? activeVerifiedPlugins
+                : [
+                    ...defaultBuiltinVerifiedPluginsV1(cliPluginSelection.profileId).filter((builtin) => !activeVerifiedPlugins?.some((active) => active.pluginId === builtin.pluginId && active.version === builtin.version)),
+                    ...(activeVerifiedPlugins ?? []),
+                ]);
+        const services = await createAgentSessionServices({
+            cwd,
+            agentDir,
+            settingsManager: runtimeSettingsManager,
+            modelRuntimeSignal: AbortSignal.timeout(15_000),
+            // First-party entry suite assembly (方案实施计划 §7 范围 2): the
+            // three-level agents.md chain, system prompt gate, and association
+            // filters apply on this self-built loader; the suite resolves once
+            // here and rides to session creation via services.suiteId.
+            suite: parsed.suite,
+            suiteAssembly: true,
+            ...(parsed.noPlugins || cliPluginSelection.profileId === undefined
+                ? {}
+                : { pluginProfileId: cliPluginSelection.profileId }),
+            ...(parsed.noPlugins || cliPluginSelection.selectedPluginIds === undefined
+                ? {}
+                : { selectedPluginIds: cliPluginSelection.selectedPluginIds }),
+            ...(parsed.noPlugins || cliPluginSelection.disabledPluginIds === undefined
+                ? {}
+                : { disabledPluginIds: cliPluginSelection.disabledPluginIds }),
+            ...(parsed.noPlugins || pluginHost === undefined ? {} : { pluginHost }),
+            ...(parsed.noPlugins || verifiedPlugins === undefined ? {} : { verifiedPlugins }),
+            ...(parsed.noPlugins || options?.manifestOverrides === undefined
+                ? activeManifestOverrides === undefined
+                    ? {}
+                    : { manifestOverrides: activeManifestOverrides }
+                : { manifestOverrides: options.manifestOverrides }),
+            ...(parsed.noPlugins || activeInstalledCapabilityPlugins === undefined
+                ? {}
+                : { installedCapabilityPlugins: activeInstalledCapabilityPlugins }),
+            ...(pluginBindingDiagnostics.length === 0 ? {} : { pluginBindingDiagnostics }),
+            resourceLoaderOptions: {
+                additionalSkillPaths: resolvedSkillPaths,
+                additionalPromptTemplatePaths: resolvedPromptTemplatePaths,
+                additionalThemePaths: resolvedThemePaths,
+                noSkills: parsed.noSkills,
+                noPromptTemplates: parsed.noPromptTemplates,
+                noThemes: parsed.noThemes,
+                noContextFiles: parsed.noContextFiles,
+                systemPrompt: parsed.systemPrompt,
+                // 档案的 systemPromptAppend（承载退役切片 2）：runner 叶子经同一资源
+                // loader 追加通道落地（shared 侧由 child loader 覆盖点做的事在这里做）。
+                appendSystemPrompt: [
+                    ...(parsed.appendSystemPrompt ?? []),
+                    ...(childProfile?.systemPromptAppend === undefined ? [] : [childProfile.systemPromptAppend]),
+                ],
+            },
+        });
+        const { settingsManager, modelRuntime } = services;
+        const diagnostics = [
+            ...cliPluginSelection.diagnostics,
+            ...services.diagnostics,
+            ...collectSettingsDiagnostics(settingsManager),
+        ];
+        const modelPatterns = parsed.models ?? settingsManager.getEnabledModels();
+        const scopedModels = modelPatterns && modelPatterns.length > 0
+            ? await resolveModelScope(modelPatterns, modelRuntime, { signal: AbortSignal.timeout(15_000) })
+            : [];
+        // 档案 model 解析（pooled parity 补口）：与 shared 侧同一纪律——只能在 runner 自己
+        // 的 scoped models 里挑，解析不到即失败并列出可用 id，不静默回落默认模型。
+        const profileModel = childModelId === undefined
+            ? undefined
+            : (() => {
+                const entry = scopedModels.find((candidate) => candidate.model.id === childModelId);
+                if (entry === undefined) {
+                    const available = scopedModels.map((candidate) => candidate.model.id).sort();
+                    throw new Error(`agent task child profile model ${JSON.stringify(childModelId)} is not among the runner's scoped models` +
+                        (available.length === 0 ? " (none configured)" : `; available: ${available.join(", ")}`));
+                }
+                return entry.model;
+            })();
+        const sessionContext = sessionManager.buildSessionContext();
+        const { options: sessionOptions, cliThinkingFromModel, diagnostics: sessionOptionDiagnostics, } = buildSessionOptions(parsed, scopedModels, sessionContext.messages.length > 0, modelRuntime, settingsManager);
+        diagnostics.push(...sessionOptionDiagnostics);
+        // Resume model restoration (dogfood 2026-09-25 live defect): the last explicit
+        // model_change in the session file (/model switch) must be honored on restart —
+        // previously the model silently reverted to the default, so turns after the
+        // switch ran on (and were billed to) the old provider. Explicit CLI --model
+        // takes priority over the persisted value.
+        const resumedSessionModel = (() => {
+            if (sessionOptions.model)
+                return undefined;
+            const persisted = sessionContext.model;
+            if (!persisted)
+                return undefined;
+            return modelRuntime.getModel(persisted.provider, persisted.modelId) ?? undefined;
+        })();
+        if (parsed.apiKey) {
+            if (!sessionOptions.model) {
+                diagnostics.push({
+                    type: "error",
+                    message: "--api-key requires a model to be specified via --model, --provider/--model, or --models",
+                });
+            }
+            else {
+                await modelRuntime.setRuntimeApiKey(sessionOptions.model.provider, parsed.apiKey);
+            }
+        }
+        // pooled runner 叶子：档案只收窄（mode 更严、thinkingLevel 更窄），不放大。
+        const childProfileMode = childProfile !== undefined && childProfile.mode === "readonly" && parsed.subagentRunner === true
+            ? "readonly"
+            : undefined;
+        const created = await createAgentSessionFromServices({
+            services,
+            sessionManager,
+            model: profileModel ?? sessionOptions.model ?? resumedSessionModel,
+            thinkingLevel: childProfile?.thinkingLevel ?? sessionOptions.thinkingLevel,
+            scopedModels: sessionOptions.scopedModels,
+            tools: sessionOptions.tools,
+            excludeTools: sessionOptions.excludeTools,
+            noTools: sessionOptions.noTools,
+            customTools: sessionOptions.customTools,
+            suite: sessionOptions.suite,
+            discoverCapabilityPlugins: parsed.noPlugins ? false : undefined,
+            // Trace/log control face (设计 §4.4/§5/§6)：--no-trace 关闭本会话轨迹
+            // 收集；进程级 logger（含崩溃钩子）传给会话打点，未创建时保持 no-op 契约。
+            traceEnabled: parsed.noTrace === true ? false : undefined,
+            // OTLP 遥测导出（设计 §8，D-065 增补 5）：标准 OTEL_EXPORTER_OTLP_ENDPOINT
+            // 环境变量显式开启 OTLP/HTTP+JSON 轨迹导出；未设置时导出器不存在，行为零变化。
+            ...(typeof process.env.OTEL_EXPORTER_OTLP_ENDPOINT === "string" &&
+                process.env.OTEL_EXPORTER_OTLP_ENDPOINT.trim().length > 0
+                ? { traceOptions: { otlp: { endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT.trim() } } }
+                : {}),
+            hostLogger: processHostLogger,
+            ...(childProfileMode === undefined ? {} : { capabilityMode: childProfileMode }),
+            // 叶子不再整体关闭 agent tasks（承载退役切片 2）：它经自动池化获得自己的
+            // 委派面（嵌套委派保留，递归边界由 delegate 沿 S2 血缘头的深度硬限与每父级
+            // 总量配额执行），并因 sdk 的 reader/lister 注入同时获得回读面。
+            // 子代理通信面（D-060 S5 pooled parity）：runner 叶子的 post/drainInbox 接线
+            // 经 services 装配传入（文件承载信箱，跨进程与父侧 drain 同一目录）。
+            ...(subagentCommunicationWiring === undefined ? {} : { subagentCommunicationWiring }),
+            // 承载退役切片 1（生产 CLI 默认 pooled）：CLI 进程声明自身入口可信——
+            // 未显式配置池时按 self-invocation 自动池化（叶子路径无害：delegate 不装配池）。
+            subagentPoolFromSelfInvocation: true,
+            // Interaction capability (1A.8): only the interactive TUI and RPC hosts
+            // serve interaction tasks; print/json hosts leave the feature absent.
+            ...(appMode === "interactive" ? { interactionHost: interactionHostSlots.interactive.host } : {}),
+            ...(appMode === "rpc" ? { interactionHost: interactionHostSlots.rpc.host } : {}),
+        });
+        for (const rejection of created.pluginRejections) {
+            diagnostics.push({
+                type: "warning",
+                message: `Capability plugin rejected (${rejection.code}): ${rejection.pluginId ?? rejection.manifestPath}: ${rejection.message}`,
+            });
+        }
+        const cliThinkingOverride = parsed.thinking !== undefined || cliThinkingFromModel;
+        if (created.session.model && cliThinkingOverride) {
+            created.session.setThinkingLevel(created.session.thinkingLevel);
+        }
+        if (childProfile?.tools !== undefined) {
+            // 档案的工具面是白名单：与叶子继承面求交（不放大），随后由 server 侧核验。
+            const inherited = created.session.getActiveToolNames();
+            const narrowed = inherited.filter((name) => childProfile.tools?.includes(name));
+            created.session.setActiveToolsByName(narrowed);
+        }
+        return {
+            ...created,
+            services: {
+                ...services,
+                // /metrics 数据源 ref 由 createAgentSession 内建的 services 携带
+                // （observability 插件工厂挂载时写入）。运行时对外暴露的是外层
+                // session-independent services，不含该 ref——不对齐的话 TUI/RPC 的
+                // 惰性闭包永远读到 undefined（/metrics 曾因此永远报未挂载）。
+                observabilityGetMetricsRef: created.session.observabilityGetMetricsRef,
+            },
+            diagnostics,
+            ...(childProfile === undefined
+                ? {}
+                : {
+                    childFacts: (() => {
+                        const sessionApi = created.session.getSessionAPI();
+                        const systemPromptOptions = sessionApi.getSystemPromptOptions?.();
+                        return {
+                            activeTools: created.session.getActiveToolNames(),
+                            ...(childProfile?.thinkingLevel === undefined
+                                ? {}
+                                : { thinkingLevel: sessionApi.getThinkingLevel?.() }),
+                            // 叶子实际生效的 append 段（CLI append 与档案 append 的合并串，已含
+                            // 方案 APPEND_SYSTEM.md 门控结果）：server 用包含语义核验档案 append。
+                            ...(systemPromptOptions?.appendSystemPrompt === undefined
+                                ? {}
+                                : { systemPromptAppend: systemPromptOptions.appendSystemPrompt }),
+                            ...(created.session.model === undefined
+                                ? {}
+                                : {
+                                    model: {
+                                        provider: created.session.model.provider,
+                                        id: created.session.model.id,
+                                        contextWindow: created.session.model.contextWindow,
+                                        maxTokens: created.session.model.maxTokens,
+                                        reasoning: created.session.model.reasoning,
+                                    },
+                                }),
+                            capabilityMode: created.session.getCapabilityRuntime().host.mode,
+                        };
+                    })(),
+                }),
+        };
+    };
+    time("createRuntime");
+    /**
+     * runner 叶子的档案解析：形状由公共解析器校验；字段级不支持的情况在这里 fail fast，
+     * 不做静默忽略（当前全部字段均可落地：model 按 runner 自身 scoped models 解析）。
+     */
+    function parseSubagentTaskChildProfile(raw) {
+        if (raw === undefined)
+            return undefined;
+        const parsed = parseAgentTaskChildProfileV1(raw);
+        if (!parsed.ok)
+            throw new Error(`child task profile is invalid: ${parsed.message}`);
+        return parsed.profile;
+    }
+    // Headless subagent runner (D-045 pooled increment 2b): serve the subagent-task
+    // protocol on stdio and never construct the parent session runtime — stdout is
+    // the protocol channel, so this branch must run before any mode startup output.
+    if (parsed.subagentRunner === true) {
+        const runnerSessionCwd = sessionManager.getCwd();
+        const runner = runSubagentTaskRunner({
+            input: process.stdin,
+            output: process.stdout,
+            createSession: createSubagentTaskSessionFactoryV1({
+                createSession: async (request) => {
+                    // 每任务一个独立叶子会话。档案（若上游带了）在这一层落地：mode/thinkingLevel
+                    // 经创建选项，tools 收窄在 createRuntime 内完成，事实回传给 server 核验。
+                    const childProfile = parseSubagentTaskChildProfile(request.profile);
+                    // resume（D-060 S5 pooled parity）：目标必须是本父会话的**已落盘**子会话，
+                    // 血缘不过线与不存在同型失败；命中则打开既有 JSONL 续写（同一 sessionId）。
+                    const resumeRead = typeof request.resumeSessionId === "string" && request.resumeSessionId !== ""
+                        ? readAgentSession({ agentDir, sessionId: request.resumeSessionId })
+                        : undefined;
+                    if (typeof request.resumeSessionId === "string" && request.resumeSessionId !== "") {
+                        if (resumeRead === undefined ||
+                            request.parentSessionId === undefined ||
+                            resumeRead.parentAgentSession !== request.parentSessionId) {
+                            throw new Error(`resume target ${request.resumeSessionId} is not a persisted child of session ${String(request.parentSessionId)}`);
+                        }
+                    }
+                    const resumeFilePath = resumeRead !== undefined && typeof request.resumeSessionId === "string"
+                        ? findSessionFile(agentSessionsDir(agentDir), request.resumeSessionId)
+                        : undefined;
+                    // 通信面（D-060 S5 pooled parity）：叶子向自己的父 post（escalate/兄弟消息）
+                    // 并 drain 自己的收件箱——文件承载信箱，root 以父会话 id 为键；叶子身份在
+                    // create 返回后补上（工厂注册先于身份可知）。
+                    const leafIdentity = { current: undefined };
+                    const requireIdentity = () => {
+                        if (leafIdentity.current === undefined)
+                            throw new Error("leaf session identity is not bound yet");
+                        return leafIdentity.current;
+                    };
+                    const leafWiring = request.parentSessionId === undefined
+                        ? {}
+                        : {
+                            postEscalate: (text) => {
+                                createSubagentMailbox({
+                                    agentDir,
+                                    ownerParentSessionId: () => request.parentSessionId,
+                                }).postEscalate(requireIdentity(), text);
+                            },
+                            sendSibling: (toSessionId, text) => {
+                                createSubagentMailbox({
+                                    agentDir,
+                                    ownerParentSessionId: () => request.parentSessionId,
+                                }).postSibling(requireIdentity(), toSessionId, text);
+                            },
+                            drainInbox: (limit) => createSubagentMailbox({
+                                agentDir,
+                                ownerParentSessionId: () => request.parentSessionId,
+                            }).drainInbox(requireIdentity(), limit),
+                        };
+                    const created = await createRuntime({
+                        cwd: runnerSessionCwd,
+                        agentDir,
+                        // 叶子会话落盘（D-060 §3）：与 root 会话同构的 JSONL，放 _agents 目录，
+                        // 头部写血缘（父 agent 会话 id + 角色 id），父侧可按 sessionId 回读。
+                        // resume 改为打开既有会话文件续写（同一 sessionId，多轮子任务）。
+                        sessionManager: resumeFilePath !== undefined && request.resumeSessionId !== undefined
+                            ? SessionManager.open(resumeFilePath, agentSessionsDir(agentDir), runnerSessionCwd)
+                            : SessionManager.create(runnerSessionCwd, agentSessionsDir(agentDir), {
+                                ...(request.parentSessionId === undefined
+                                    ? {}
+                                    : { parentAgentSession: request.parentSessionId }),
+                                // 回合级血缘：仅 create 消费；resume（open）不写头。
+                                ...(request.parentTraceId === undefined ? {} : { parentTraceId: request.parentTraceId }),
+                                ...(childProfile?.roleId === undefined ? {} : { agentRole: childProfile.roleId }),
+                            }),
+                        ...(childProfile === undefined ? {} : { childProfile }),
+                        ...(childProfile?.model === undefined ? {} : { childModelId: childProfile.model }),
+                        ...(Object.keys(leafWiring).length === 0 ? {} : { subagentCommunicationWiring: leafWiring }),
+                    });
+                    const session = created.session;
+                    const sessionApi = session.getSessionAPI();
+                    leafIdentity.current = sessionApi.getAgentSessionId?.() ?? sessionApi.getSessionId();
+                    // 显式映射到命令面会话契约：不复用 AgentSession 全量面，避免隐藏依赖会话布局。
+                    return {
+                        prompt: (text) => session.prompt(text, { expandPromptTemplates: false }),
+                        abort: (reason) => session.abort(reason),
+                        dispose: () => session.dispose(),
+                        getMessages: () => sessionApi.getMessages(),
+                        getSessionId: () => sessionApi.getSessionId(),
+                        // D-044 §5.6：回合级进度（turn_end + 有界工具摘要）经协议 progress 事件回父侧。
+                        onProgress: createTurnProgressSourceV1(session),
+                        // 父→子引导（D-060 S5 pooled parity）：转发会话自身 steer。
+                        ...(sessionApi.steer === undefined
+                            ? {}
+                            : {
+                                steer: (text) => {
+                                    const steerFn = sessionApi.steer;
+                                    if (steerFn === undefined)
+                                        return Promise.resolve();
+                                    return steerFn.call(sessionApi, text);
+                                },
+                            }),
+                        // 档案事实：只有带档案的 create 才会被 server 要求自证。
+                        ...(created.childFacts === undefined
+                            ? {}
+                            : { facts: () => created.childFacts }),
+                    };
+                },
+            }),
+        });
+        await runner.done;
+        return;
+    }
+    let runtime;
+    // Unresolved startup suite id (设计 §9): interactive mode recovers in-process
+    // by handing a pending selector to InteractiveMode (the user picks a suite
+    // before the first prompt); print/json/rpc keep the structured exit-1.
+    let pendingSuiteSelector;
+    try {
+        runtime = await createAgentSessionRuntime(createRuntime, {
+            cwd: sessionManager.getCwd(),
+            agentDir,
+            sessionManager,
+        });
+    }
+    catch (error) {
+        // 已绑定会话换 suite / Profile 身份漂移（SuiteRebindError）：用户可自行纠正的
+        // 参数错误，干净的一行 stderr + 退出 1，不甩内部栈（dogfood 2026-09-25 实测）。
+        if (error instanceof SuiteRebindError) {
+            console.error(chalk.red(`Error: ${error.message}`));
+            process.exit(1);
+        }
+        // Unknown --suite/env/settings suite ids are a structured startup error
+        // (设计 §9): list the available ids and exit 1 instead of a stack trace.
+        if (!(error instanceof SuiteResolutionError))
+            throw error;
+        if (appMode !== "interactive") {
+            console.error(chalk.red(`Error: ${error.message}`));
+            process.exit(1);
+        }
+        // One in-process recovery attempt (设计 §9 startup selector): record the
+        // pending pick, clear this run's explicit suite for the retry, and delete
+        // AGENT_FORGE_SUITE when it named the unknown id — the env is the only
+        // source this process may eliminate. A settings-level unknown id cannot
+        // be resolved in-process (silently rewriting the user's settings files is
+        // not a startup decision), so the retry still throws and exits 1 below
+        // with the same structured guidance.
+        pendingSuiteSelector = { requestedId: error.requestedId, available: error.availableSuiteIds };
+        parsed.suite = undefined;
+        if (process.env[SUITE_ENV_VAR] === error.requestedId) {
+            delete process.env[SUITE_ENV_VAR];
+        }
+        try {
+            runtime = await createAgentSessionRuntime(createRuntime, {
+                cwd: sessionManager.getCwd(),
+                agentDir,
+                sessionManager,
+            });
+        }
+        catch (retryError) {
+            if (retryError instanceof SuiteResolutionError) {
+                console.error(chalk.red(`Error: ${retryError.message}`));
+                process.exit(1);
+            }
+            throw retryError;
+        }
+    }
+    time("createAgentSessionRuntime");
+    const { services, session, modelFallbackMessage } = runtime;
+    const { settingsManager, modelRuntime } = services;
+    setCapabilityOverrides(settingsManager.getTerminalCapabilityOverrides());
+    applyHttpProxySettings(settingsManager.getGlobalSettings().httpProxy);
+    configureHttpDispatcher(settingsManager.getHttpIdleTimeoutMs());
+    if (parsed.help) {
+        reportDiagnostics(startupSettingsDiagnostics);
+        printHelp();
+        process.exit(0);
+    }
+    if (parsed.listModels !== undefined) {
+        reportDiagnostics(startupSettingsDiagnostics);
+        const searchPattern = typeof parsed.listModels === "string" ? parsed.listModels : undefined;
+        await listModels(modelRuntime, searchPattern, AbortSignal.timeout(15_000));
+        process.exit(0);
+    }
+    // Read piped stdin content (if any) - skip for RPC mode which uses stdin for JSON-RPC
+    let stdinContent;
+    if (appMode !== "rpc") {
+        stdinContent = await readPipedStdin();
+        // v8 ignore next -- stdin 的 isTTY 在两次读取间不会变化，交互模式下不可能读到管道内容
+        if (stdinContent !== undefined && appMode === "interactive") {
+            appMode = "print";
+        }
+    }
+    time("readPipedStdin");
+    const { initialMessage, initialImages } = await prepareInitialMessage(parsed, settingsManager.getImageAutoResize(), stdinContent);
+    time("prepareInitialMessage");
+    initTheme(settingsManager.getTheme(), appMode === "interactive");
+    time("initTheme");
+    // Show deprecation warnings in interactive mode
+    if (appMode === "interactive" && deprecationWarnings.length > 0) {
+        await showDeprecationWarnings(deprecationWarnings);
+    }
+    time("resolveModelScope");
+    const allStartupDiagnostics = deduplicateDiagnostics([...startupSettingsDiagnostics, ...runtime.diagnostics]);
+    const startupDiagnostics = filterAcknowledgedSuiteNotices(allStartupDiagnostics, settingsManager);
+    // ack 经 save() 的异步写队列落盘；print 模式随即退出、TUI 退出链也不经过
+    // settings flush，这里统一等待落盘，否则"已读"记录静默丢失。
+    await settingsManager.flush().catch(() => { });
+    const hasRuntimeErrors = runtime.diagnostics.some((diagnostic) => diagnostic.type === "error");
+    if (appMode !== "interactive" || hasRuntimeErrors) {
+        reportDiagnostics(startupDiagnostics);
+    }
+    if (hasRuntimeErrors) {
+        process.exit(1);
+    }
+    // D-028: interactive mode suppresses startup warnings above, so rejected
+    // capability plugins get an explicit stderr note before the TUI takes over.
+    if (appMode === "interactive") {
+        for (const rejection of runtime.pluginRejections) {
+            console.error(chalk.yellow(`Warning: capability plugin rejected (${rejection.code}): ${rejection.pluginId ?? rejection.manifestPath}: ${rejection.message}`));
+        }
+    }
+    time("createAgentSession");
+    // With nothing configured, agent core falls back to an all-"unknown"
+    // placeholder model (packages/agent/src/agent.ts DEFAULT_MODEL), so a truthy
+    // session.model does not mean a usable model. Non-interactive modes must
+    // stop here with the login guidance instead of dying mid-request.
+    const noModelResolved = !session.model || (session.model.provider === "unknown" && session.model.id === "unknown");
+    if (appMode !== "interactive" && noModelResolved) {
+        console.error(chalk.red(modelFallbackMessage ?? formatNoModelsAvailableMessage()));
+        process.exit(1);
+    }
+    const startupBenchmark = isTruthyEnvFlag(process.env.AGENT_FORGE_STARTUP_BENCHMARK);
+    if (startupBenchmark && appMode !== "interactive") {
+        console.error(chalk.red("Error: AGENT_FORGE_STARTUP_BENCHMARK only supports interactive mode"));
+        process.exit(1);
+    }
+    // RPC refreshes catalogs here in the background; interactive mode starts its refresh after TUI initialization.
+    if (!offlineMode && appMode === "rpc") {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 15_000);
+        void modelRuntime
+            .refresh({ signal: controller.signal })
+            .catch(() => { })
+            .finally(() => clearTimeout(timeout));
+    }
+    if (appMode === "rpc") {
+        printTimings();
+        await runRpcMode(runtime, {
+            interactionHostSlot: interactionHostSlots.rpc,
+            // 惰性解引用：插件工厂在挂载时才执行，构造期取 ref.current 会拿到
+            // undefined（/metrics 曾因此永远报未挂载）。
+            getMetrics: (options) => runtime.observabilityGetMetricsRef?.current?.(options),
+        });
+    }
+    else if (appMode === "interactive") {
+        const interactiveMode = new InteractiveMode(runtime, {
+            // 惰性解引用：插件工厂在挂载时才执行，构造期取 ref.current 会拿到
+            // undefined（/metrics 曾因此永远报未挂载）。
+            getMetrics: (options) => runtime.observabilityGetMetricsRef?.current?.(options),
+            migratedProviders,
+            startupDiagnostics,
+            modelFallbackMessage,
+            initialMessage,
+            initialImages,
+            initialMessages: parsed.messages,
+            verbose: parsed.verbose,
+            tuiMode: parsed.tuiMode,
+            initialThemeSetting: parsed.useTheme,
+            pendingSuiteSelector,
+            settingsManager,
+        });
+        // Interaction capability (1A.8): the TUI owns the dialog surface, so its
+        // host backs the slot the session was created with.
+        interactionHostSlots.interactive.setTarget(interactiveMode.createInteractionHostV1());
+        if (startupBenchmark) {
+            await interactiveMode.init();
+            time("interactiveMode.init");
+            // Give the TUI's stdin handler a brief chance to consume terminal query replies
+            // (Kitty keyboard protocol, device attributes, cell size) before restoring the terminal.
+            await new Promise((resolve) => setTimeout(resolve, 150));
+            interactiveMode.stop();
+            stopThemeWatcher();
+            printTimings();
+            if (process.stdout.writableLength > 0) {
+                await new Promise((resolve) => process.stdout.once("drain", resolve));
+            }
+            if (process.stderr.writableLength > 0) {
+                await new Promise((resolve) => process.stderr.once("drain", resolve));
+            }
+            return;
+        }
+        printTimings();
+        await interactiveMode.run();
+    }
+    else {
+        printTimings();
+        const exitCode = await runPrintMode(runtime, {
+            mode: toPrintOutputMode(appMode),
+            messages: parsed.messages,
+            initialMessage,
+            initialImages,
+        });
+        stopThemeWatcher();
+        restoreStdout();
+        if (exitCode !== 0) {
+            process.exitCode = exitCode;
+        }
+        return;
+    }
+}
+//# sourceMappingURL=main.js.map