@zhijiewang/openharness 2.20.0 → 2.22.0

package/dist/main.js

@@ -23,9 +23,10 @@ import { detectProject, projectContextToPrompt } from "./harness/onboarding.js";
 import { discoverSkills, skillsToPrompt } from "./harness/plugins.js";
 import { createRulesFile, loadRules, loadRulesAsPrompt } from "./harness/rules.js";
 import { listSessions } from "./harness/session.js";
-import { connectedMcpServers, disconnectMcpClients, getMcpInstructions, loadMcpPrompts, loadMcpTools, } from "./mcp/loader.js";
+import { connectedMcpServers, disconnectMcpClients, getMcpInstructions, loadMcpPrompts, loadMcpTools, parseMcpConfigFile, } from "./mcp/loader.js";
 import { loadOutputStyle } from "./outputStyles/index.js";
 import { getAllTools } from "./tools.js";
+import { configureDebug, debug } from "./utils/debug.js";
 import { validateAgainstJsonSchema } from "./utils/json-schema.js";
 import { parseMaxBudgetUsd } from "./utils/parse-budget.js";
 const _require = createRequire(import.meta.url);
@@ -75,6 +76,40 @@ You have access to tools for reading, writing, and searching files, running shel
 - When referencing code, include file_path:line_number.
 - Do not restate what the user said. Do not add trailing summaries unless asked.
 - Keep responses short and direct. If you can say it in one sentence, don't use three.`;
+/**
+ * Read a system prompt from a file path, or exit 2 with a stderr message.
+ * Used by `--system-prompt-file` / `--append-system-prompt-file` so callers
+ * can keep prompts as version-controlled files instead of stuffing them on
+ * the command line. Trailing newline is stripped (most editors add one).
+ */
+function readSystemPromptFile(path, label) {
+    try {
+        return readFileSync(path, "utf8").replace(/\n$/, "");
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`Error: ${label} '${path}' could not be read: ${message}\n`);
+        process.exit(2);
+    }
+}
+/**
+ * Parse `--mcp-config <path>` (and the optional `--strict-mcp-config` flag)
+ * into a `LoadMcpOptions` shape ready to pass to `loadMcpTools`. Returns
+ * undefined when the user didn't pass `--mcp-config`. Exits 2 with a stderr
+ * message on parse / shape errors.
+ */
+function buildMcpLoadOpts(opts) {
+    if (!opts.mcpConfig)
+        return undefined;
+    try {
+        const extraServers = parseMcpConfigFile(opts.mcpConfig);
+        return { extraServers, strict: opts.strictMcpConfig === true };
+    }
+    catch (err) {
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(2);
+    }
+}
 /**
  * Parse the `--max-budget-usd` CLI argument into a positive USD amount, or
  * exit 2 with an error message. The pure parser lives in
@@ -89,7 +124,19 @@ function parseMaxBudgetUsdOrExit(raw) {
     }
     return result.value;
 }
-function buildSystemPrompt(model) {
+/**
+ * Build the assembled system prompt for a session.
+ *
+ * In `bare` mode (audit A4 — `--bare`) every optional contributor is skipped:
+ * no project context, no rules, no user profile, no remembered memories, no
+ * skill catalog, no MCP server instructions, no language directive, no output
+ * style. The result is exactly `DEFAULT_SYSTEM_PROMPT`. Used for fast SDK /
+ * CI invocations where the model just needs the tool-use baseline and the
+ * caller will supply its own context.
+ */
+function buildSystemPrompt(model, opts = {}) {
+    if (opts.bare)
+        return DEFAULT_SYSTEM_PROMPT;
     const cfg = readOhConfig();
     // Output-style preface (first — sets personality for everything that follows).
     // Skipped silently for the "default" style (empty prompt).
@@ -146,13 +193,36 @@ program
     .addOption(new Option("--output-format <format>", "Output format").choices(["json", "text", "stream-json"]).default("text"))
     .option("--max-turns <n>", "Maximum turns", "20")
     .option("--system-prompt <prompt>", "Override the system prompt")
+    .option("--system-prompt-file <path>", "Read the system prompt from a file (overrides --system-prompt)")
     .option("--append-system-prompt <text>", "Append text to the system prompt")
+    .option("--append-system-prompt-file <path>", "Append the contents of a file to the system prompt")
     .option("--allowed-tools <tools>", "Comma-separated list of allowed tools")
     .option("--disallowed-tools <tools>", "Comma-separated list of disallowed tools")
     .option("--resume <id>", "Resume a saved session (replays its message history before this prompt)")
     .option("--setting-sources <sources>", "Comma-separated list of setting sources to merge (e.g. 'user,project,local'). Mirrors Claude Code's setting_sources.")
     .option("--max-budget-usd <amount>", "Hard cap on session cost in USD. The agent halts with reason 'budget_exceeded' once totalCost reaches this amount. Mirrors Claude Code's --max-budget-usd.")
+    .option("--no-session-persistence", "Skip writing the session to disk under ~/.oh/sessions/. Useful for ephemeral CI runs that don't need resume.")
+    .option("--mcp-config <path>", 'Load MCP servers from a JSON file (in addition to .oh/config.yaml). File format: {"mcpServers": [...]} or a bare array.')
+    .option("--strict-mcp-config", "With --mcp-config, ignore .oh/config.yaml mcpServers — use only the file's servers.")
+    .option("--bare", "Skip optional startup work (project detection, plugins, memory, skills, MCP). System prompt is just the tool-use baseline. Useful for fast CI / SDK invocations.")
+    .option("--debug [categories]", "Enable categorized debug logs to stderr. Pass comma-separated categories (e.g. 'mcp,hooks') or no value for all. Also reads OH_DEBUG.")
+    .option("--debug-file <path>", "When --debug is set, append debug lines to this file instead of stderr.")
+    .option("--fallback-model <model>", "One-shot fallback model used when the primary fails with a retriable error (429/5xx/network/timeout). Format: provider/model or just model. REPLACES .oh/config.yaml fallbackProviders for this run. Mirrors Claude Code's --fallback-model.")
+    .option("--init", "Run the interactive `oh init` setup wizard before starting the command. Useful for first-run on a fresh project.")
+    .option("--init-only", "Run `oh init` and exit, without proceeding to the run/session.")
+    .option("--permission-prompt-tool <mcp_tool>", 'Delegate per-tool permission decisions to a configured MCP tool (e.g. "mcp__myperm__check"). The tool is invoked when a tool needs approval and no permission hook decided. Mirrors Claude Code\'s --permission-prompt-tool.')
     .action(async (promptArg, opts) => {
+    configureDebug({
+        categories: opts.debug,
+        ...(opts.debugFile ? { file: opts.debugFile } : {}),
+    });
+    const bare = opts.bare === true;
+    debug("startup", "oh run", { bare, model: opts.model });
+    // --init / --init-only run the setup wizard before (or instead of) the
+    // actual run. --init-only exits after the wizard; --init falls through.
+    if (opts.init === true || opts.initOnly === true) {
+        await runInitWizard({ exitOnDone: opts.initOnly === true });
+    }
     // Read from stdin if prompt is "-" or omitted and stdin is not a TTY
     let prompt;
     if (!promptArg || promptArg === "-" || !process.stdin.isTTY) {
@@ -187,10 +257,16 @@ program
         overrides.apiKey = savedConfig.apiKey;
     if (savedConfig?.baseUrl)
         overrides.baseUrl = savedConfig.baseUrl;
-    const { provider, model } = await createProvider(effectiveModel, Object.keys(overrides).length ? overrides : undefined);
+    const { provider, model } = await createProvider(effectiveModel, Object.keys(overrides).length ? overrides : undefined, opts.fallbackModel ? { fallbackModel: opts.fallbackModel } : {});
     const { query } = await import("./query.js");
-    // Tool filtering
-    let tools = getAllTools();
+    // Tool list = built-ins + MCP server tools (project config + --mcp-config).
+    // Previously oh run skipped MCP entirely, which silently broke the SDK
+    // `tools=[...]` feature (the SDK injects mcpServers into a temp config but
+    // the CLI never read it back). `--bare` opts back out — built-ins only.
+    const mcpLoadOpts = buildMcpLoadOpts(opts);
+    const mcpTools = bare ? [] : await loadMcpTools(mcpLoadOpts);
+    debug("mcp", "loaded", { count: mcpTools.length, bare });
+    let tools = [...getAllTools(), ...mcpTools];
     if (opts.allowedTools) {
         const allowed = new Set(opts.allowedTools.split(",").map((s) => s.trim()));
         tools = tools.filter((t) => allowed.has(t.name));
@@ -199,13 +275,22 @@ program
         const disallowed = new Set(opts.disallowedTools.split(",").map((s) => s.trim()));
         tools = tools.filter((t) => !disallowed.has(t.name));
     }
-    // System prompt
+    process.on("exit", () => disconnectMcpClients());
+    // System prompt — file variants take precedence over inline string variants
+    // so callers can override-from-file without removing a stale --system-prompt
+    // they were previously passing.
     let systemPrompt;
-    if (opts.systemPrompt) {
+    if (opts.systemPromptFile) {
+        systemPrompt = readSystemPromptFile(opts.systemPromptFile, "--system-prompt-file");
+    }
+    else if (opts.systemPrompt) {
         systemPrompt = opts.systemPrompt;
     }
     else {
-        systemPrompt = buildSystemPrompt(model);
+        systemPrompt = buildSystemPrompt(model, { bare });
+    }
+    if (opts.appendSystemPromptFile) {
+        systemPrompt += `\n\n${readSystemPromptFile(opts.appendSystemPromptFile, "--append-system-prompt-file")}`;
     }
     if (opts.appendSystemPrompt) {
         systemPrompt += `\n\n${opts.appendSystemPrompt}`;
@@ -218,6 +303,7 @@ program
         maxTurns: parseInt(opts.maxTurns, 10),
         model,
         ...(opts.maxBudgetUsd !== undefined ? { maxCost: parseMaxBudgetUsdOrExit(opts.maxBudgetUsd) } : {}),
+        ...(opts.permissionPromptTool ? { permissionPromptTool: opts.permissionPromptTool } : {}),
     };
     const outputFormat = opts.json ? "json" : (opts.outputFormat ?? "text");
     let fullOutput = "";
@@ -233,6 +319,8 @@ program
     // --resume <id> on a later run. Without this, every fresh `oh run` was
     // a programmatic dead-end for resumption (issue #60).
     const { createSession, loadSession, saveSession } = await import("./harness/session.js");
+    // Commander rewrites --no-session-persistence to opts.sessionPersistence === false.
+    const persistSession = opts.sessionPersistence !== false;
     let priorMessages;
     let sessionId;
     let sessionRecord;
@@ -250,7 +338,8 @@ program
     else {
         sessionRecord = createSession(provider.name, model);
         sessionId = sessionRecord.id;
-        saveSession(sessionRecord);
+        if (persistSession)
+            saveSession(sessionRecord);
     }
     if (outputFormat === "stream-json") {
         // Emit a session_start event so SDK callers can capture the id for
@@ -352,16 +441,18 @@ program
     // they're per-tool ephemerals; the assistant's final text is what
     // matters for context resumption. Mirrors the REPL's save-on-exit pattern
     // (src/components/REPL.tsx:120) but at one-shot scope.
-    try {
-        const { createUserMessage, createAssistantMessage } = await import("./types/message.js");
-        const newMessages = [...(priorMessages ?? []), createUserMessage(prompt)];
-        if (fullOutput)
-            newMessages.push(createAssistantMessage(fullOutput));
-        sessionRecord.messages = newMessages;
-        saveSession(sessionRecord);
-    }
-    catch {
-        /* persistence is best-effort — never fail the user's run on a save error */
+    if (persistSession) {
+        try {
+            const { createUserMessage, createAssistantMessage } = await import("./types/message.js");
+            const newMessages = [...(priorMessages ?? []), createUserMessage(prompt)];
+            if (fullOutput)
+                newMessages.push(createAssistantMessage(fullOutput));
+            sessionRecord.messages = newMessages;
+            saveSession(sessionRecord);
+        }
+        catch {
+            /* persistence is best-effort — never fail the user's run on a save error */
+        }
     }
 });
 // ── `oh session`: long-lived stateful session for the Python SDK ──
@@ -376,10 +467,32 @@ program
     .option("--disallowed-tools <tools>", "Comma-separated disallowed tool names")
     .option("--max-turns <n>", "Maximum turns per prompt", "20")
     .option("--system-prompt <prompt>", "Override the system prompt")
+    .option("--system-prompt-file <path>", "Read the system prompt from a file (overrides --system-prompt)")
+    .option("--append-system-prompt <text>", "Append text to the system prompt")
+    .option("--append-system-prompt-file <path>", "Append the contents of a file to the system prompt")
     .option("--resume <id>", "Resume a saved session (seeds the conversation with its prior message history)")
     .option("--setting-sources <sources>", "Comma-separated list of setting sources to merge (mirrors Claude Code's setting_sources).")
     .option("--max-budget-usd <amount>", "Hard cap on session cost in USD. Each prompt's cost accumulates; the agent halts with reason 'budget_exceeded' once totalCost reaches this amount.")
+    .option("--no-session-persistence", "Skip writing the session to disk under ~/.oh/sessions/. Useful for ephemeral SDK clients that don't need resume.")
+    .option("--mcp-config <path>", 'Load MCP servers from a JSON file (in addition to .oh/config.yaml). File format: {"mcpServers": [...]} or a bare array.')
+    .option("--strict-mcp-config", "With --mcp-config, ignore .oh/config.yaml mcpServers — use only the file's servers.")
+    .option("--bare", "Skip optional startup work (project detection, plugins, memory, skills, MCP). System prompt is just the tool-use baseline.")
+    .option("--debug [categories]", "Enable categorized debug logs to stderr. Pass comma-separated categories (e.g. 'mcp,hooks') or no value for all. Also reads OH_DEBUG.")
+    .option("--debug-file <path>", "When --debug is set, append debug lines to this file instead of stderr.")
+    .option("--fallback-model <model>", "One-shot fallback model used when the primary fails with a retriable error. Format: provider/model or just model. REPLACES .oh/config.yaml fallbackProviders for this run.")
+    .option("--init", "Run the interactive setup wizard before starting the session.")
+    .option("--init-only", "Run `oh init` and exit, without proceeding to the session.")
+    .option("--permission-prompt-tool <mcp_tool>", 'Delegate per-tool permission decisions to a configured MCP tool (e.g. "mcp__myperm__check"). Invoked when a tool needs approval and no permission hook decided.')
     .action(async (opts) => {
+    configureDebug({
+        categories: opts.debug,
+        ...(opts.debugFile ? { file: opts.debugFile } : {}),
+    });
+    const bare = opts.bare === true;
+    debug("startup", "oh session", { bare, model: opts.model });
+    if (opts.init === true || opts.initOnly === true) {
+        await runInitWizard({ exitOnDone: opts.initOnly === true });
+    }
     const settingSources = parseSettingSources(opts.settingSources);
     const savedConfig = readOhConfig(undefined, settingSources);
     const permissionMode = (opts.permissionMode ??
@@ -392,10 +505,17 @@ program
         overrides.apiKey = savedConfig.apiKey;
     if (savedConfig?.baseUrl)
         overrides.baseUrl = savedConfig.baseUrl;
-    const { provider, model } = await createProvider(effectiveModel, Object.keys(overrides).length ? overrides : undefined);
+    const { provider, model } = await createProvider(effectiveModel, Object.keys(overrides).length ? overrides : undefined, opts.fallbackModel ? { fallbackModel: opts.fallbackModel } : {});
     const { query } = await import("./query.js");
     const { createAssistantMessage, createToolResultMessage, createUserMessage } = await import("./types/message.js");
-    let tools = getAllTools();
+    // Tool list = built-ins + MCP server tools (project config + --mcp-config).
+    // Same fix as `oh run` — `oh session` previously skipped MCP entirely,
+    // which silently broke the SDK `tools=[...]` feature for stateful clients.
+    // `--bare` opts back out — built-ins only.
+    const mcpLoadOpts = buildMcpLoadOpts(opts);
+    const mcpTools = bare ? [] : await loadMcpTools(mcpLoadOpts);
+    debug("mcp", "loaded", { count: mcpTools.length, bare });
+    let tools = [...getAllTools(), ...mcpTools];
     if (opts.allowedTools) {
         const allowed = new Set(opts.allowedTools.split(",").map((s) => s.trim()));
         tools = tools.filter((t) => allowed.has(t.name));
@@ -404,7 +524,23 @@ program
         const disallowed = new Set(opts.disallowedTools.split(",").map((s) => s.trim()));
         tools = tools.filter((t) => !disallowed.has(t.name));
     }
-    const systemPrompt = opts.systemPrompt ?? buildSystemPrompt(model);
+    process.on("exit", () => disconnectMcpClients());
+    let systemPrompt;
+    if (opts.systemPromptFile) {
+        systemPrompt = readSystemPromptFile(opts.systemPromptFile, "--system-prompt-file");
+    }
+    else if (opts.systemPrompt) {
+        systemPrompt = opts.systemPrompt;
+    }
+    else {
+        systemPrompt = buildSystemPrompt(model, { bare });
+    }
+    if (opts.appendSystemPromptFile) {
+        systemPrompt += `\n\n${readSystemPromptFile(opts.appendSystemPromptFile, "--append-system-prompt-file")}`;
+    }
+    if (opts.appendSystemPrompt) {
+        systemPrompt += `\n\n${opts.appendSystemPrompt}`;
+    }
     const config = {
         provider,
         tools,
@@ -413,6 +549,7 @@ program
         maxTurns: parseInt(opts.maxTurns, 10),
         model,
         ...(opts.maxBudgetUsd !== undefined ? { maxCost: parseMaxBudgetUsdOrExit(opts.maxBudgetUsd) } : {}),
+        ...(opts.permissionPromptTool ? { permissionPromptTool: opts.permissionPromptTool } : {}),
     };
     // Conversation history, shared across all prompts for this process.
     // Seeded from a prior session when --resume <id> is passed; otherwise a
@@ -420,6 +557,8 @@ program
     // event for later resume (issue #60).
     const conversation = [];
     const { createSession, loadSession, saveSession } = await import("./harness/session.js");
+    // Commander rewrites --no-session-persistence to opts.sessionPersistence === false.
+    const persistSession = opts.sessionPersistence !== false;
     let sessionId;
     let sessionRecord;
     if (opts.resume) {
@@ -436,7 +575,8 @@ program
     else {
         sessionRecord = createSession(provider.name, model);
         sessionId = sessionRecord.id;
-        saveSession(sessionRecord);
+        if (persistSession)
+            saveSession(sessionRecord);
     }
     let turnCounter = 0;
     // Will be set to the current prompt id before each turn so hook_decision
@@ -549,12 +689,15 @@ program
         }
         // Persist after every completed turn so a later --resume picks up the
         // history. Best-effort — a save failure shouldn't break the live session.
-        try {
-            sessionRecord.messages = conversation.slice();
-            saveSession(sessionRecord);
-        }
-        catch {
-            /* save errors don't propagate to the client */
+        // Skipped entirely when --no-session-persistence was passed.
+        if (persistSession) {
+            try {
+                sessionRecord.messages = conversation.slice();
+                saveSession(sessionRecord);
+            }
+            catch {
+                /* save errors don't propagate to the client */
+            }
         }
     }
 });
@@ -578,7 +721,22 @@ program
     .option("--json-schema <schema>", "Constrain output to match a JSON schema (headless mode)")
     .option("--input-format <format>", "Input format: text (default) or stream-json (NDJSON on stdin)")
     .option("--replay-user-messages", "Re-emit user messages on stdout (requires stream-json output)")
+    .option("--bare", "Skip optional startup work (project detection, plugins, memory, skills, MCP). System prompt is just the tool-use baseline.")
+    .option("--debug [categories]", "Enable categorized debug logs to stderr. Pass comma-separated categories (e.g. 'mcp,hooks') or no value for all. Also reads OH_DEBUG.")
+    .option("--debug-file <path>", "When --debug is set, append debug lines to this file instead of stderr.")
+    .option("--fallback-model <model>", "One-shot fallback model used when the primary fails with a retriable error. Format: provider/model or just model. REPLACES .oh/config.yaml fallbackProviders for this run.")
+    .option("--init", "Run the interactive setup wizard before starting the chat session.")
+    .option("--init-only", "Run `oh init` and exit, without proceeding to the chat session.")
     .action(async (opts) => {
+    configureDebug({
+        categories: opts.debug,
+        ...(opts.debugFile ? { file: opts.debugFile } : {}),
+    });
+    const bare = opts.bare === true;
+    debug("startup", "oh chat", { bare, model: opts.model, print: !!opts.print });
+    if (opts.init === true || opts.initOnly === true) {
+        await runInitWizard({ exitOnDone: opts.initOnly === true });
+    }
     // Load saved config as defaults (env vars + CLI flags override)
     const savedConfig = readOhConfig();
     const effectiveModel = opts.model ?? savedConfig?.model;
@@ -603,7 +761,7 @@ program
         if (fresh?.baseUrl)
             overrides.baseUrl = fresh.baseUrl;
         const targetModel = fresh?.model ?? effectiveModel;
-        return createProvider(targetModel, Object.keys(overrides).length ? overrides : undefined);
+        return createProvider(targetModel, Object.keys(overrides).length ? overrides : undefined, opts.fallbackModel ? { fallbackModel: opts.fallbackModel } : {});
     };
     try {
         const result = await tryCreateProvider();
@@ -648,25 +806,31 @@ program
             process.exit(0);
         }
     }
-    const mcpTools = await loadMcpTools();
-    const mcpNames = connectedMcpServers();
-    if (mcpNames.length > 0) {
-        console.log(`[mcp] Connected: ${mcpNames.join(", ")}`);
-    }
-    // Surface MCP-server prompts (`prompts/list`) as `/server:prompt` slash
-    // commands. Errors are swallowed inside loadMcpPrompts — servers that
-    // don't implement the prompts capability return [] without throwing.
-    try {
-        const { registerMcpPromptCommands } = await import("./commands/index.js");
-        const prompts = await loadMcpPrompts();
-        registerMcpPromptCommands(prompts);
-        if (prompts.length > 0) {
-            console.log(`[mcp] Prompts: ${prompts.map((p) => `/${p.qualifiedName}`).join(", ")}`);
+    // `--bare` skips MCP entirely (servers, prompts, instructions). The
+    // built-in tool set is still loaded — bare is about reducing optional
+    // startup work, not stripping the agent's tool surface.
+    const mcpTools = bare ? [] : await loadMcpTools();
+    if (!bare) {
+        const mcpNames = connectedMcpServers();
+        if (mcpNames.length > 0) {
+            console.log(`[mcp] Connected: ${mcpNames.join(", ")}`);
+        }
+        // Surface MCP-server prompts (`prompts/list`) as `/server:prompt` slash
+        // commands. Errors are swallowed inside loadMcpPrompts — servers that
+        // don't implement the prompts capability return [] without throwing.
+        try {
+            const { registerMcpPromptCommands } = await import("./commands/index.js");
+            const prompts = await loadMcpPrompts();
+            registerMcpPromptCommands(prompts);
+            if (prompts.length > 0) {
+                console.log(`[mcp] Prompts: ${prompts.map((p) => `/${p.qualifiedName}`).join(", ")}`);
+            }
+        }
+        catch {
+            /* prompt registration is best-effort; never block the REPL */
         }
     }
-    catch {
-        /* prompt registration is best-effort; never block the REPL */
-    }
+    debug("mcp", "loaded", { count: mcpTools.length, bare });
     const tools = [...getAllTools(), ...mcpTools];
     process.on("exit", () => disconnectMcpClients());
     // Compute working directory and git branch
@@ -728,7 +892,7 @@ program
         const qConfig = {
             provider,
             tools,
-            systemPrompt: buildSystemPrompt(resolvedModel),
+            systemPrompt: buildSystemPrompt(resolvedModel, { bare }),
             permissionMode: effectivePermMode,
             maxTurns: 20,
             model: resolvedModel,
@@ -914,11 +1078,17 @@ program
     }
     console.log();
 });
-// ── init ──
-program
-    .command("init")
-    .description("Initialize OpenHarness for the current project (interactive setup wizard)")
-    .action(async () => {
+/**
+ * Run the interactive setup wizard. Used by both the `oh init` subcommand and
+ * the `--init` / `--init-only` flag added to chat / run / session (audit B5).
+ *
+ * `exitOnDone` controls the wizard's `onDone` behavior:
+ *   - true  → wizard exits the process when the user finishes (the standalone
+ *             `oh init` command path)
+ *   - false → wizard resolves and the caller continues (the `--init` flag path,
+ *             where the wizard is just a setup step before running the command)
+ */
+async function runInitWizard(opts) {
     const { default: InitWizard } = await import("./components/InitWizard.js");
     const rulesPath = createRulesFile();
     const ctx = detectProject();
@@ -931,8 +1101,144 @@ program
     }
     console.log(`  Rules file: ${rulesPath}`);
     console.log();
-    const { waitUntilExit } = render(_jsx(InitWizard, { onDone: () => process.exit(0) }));
+    const { waitUntilExit } = render(_jsx(InitWizard, { onDone: () => (opts.exitOnDone ? process.exit(0) : undefined) }));
     await waitUntilExit();
+}
+// ── init ──
+program
+    .command("init")
+    .description("Initialize OpenHarness for the current project (interactive setup wizard)")
+    .action(async () => {
+    await runInitWizard({ exitOnDone: true });
+});
+// ── auth (audit B6) — provider-agnostic credential management ──
+//
+// `oh auth login [provider] --key <value>`  — set API key for a provider
+// `oh auth logout [provider]`              — clear API key for a provider
+// `oh auth status`                         — show which providers have keys
+//
+// `provider` defaults to the current `cfg.provider` so a bare `oh auth login`
+// works for the just-configured project. Mirrors Claude Code's `claude auth`.
+const authCmd = program.command("auth").description("Manage API keys for any provider (login / logout / status)");
+// Providers that run locally and don't use API keys — `oh auth login <local>`
+// is a no-op for these; redirect users to `oh init` which configures the
+// base URL and downloads / launches the model.
+const LOCAL_PROVIDERS = new Set(["ollama", "llamacpp", "llama.cpp", "lmstudio", "lm studio"]);
+authCmd
+    .command("login [provider]")
+    .description("Set the API key for a provider (defaults to the configured provider)")
+    .option("--key <value>", "API key value (omit to read from stdin)")
+    .action(async (providerArg, opts) => {
+    const { setCredential } = await import("./harness/credentials.js");
+    const cfg = readOhConfig();
+    const provider = providerArg ?? cfg?.provider;
+    if (!provider) {
+        process.stderr.write("Error: no provider specified and no default in .oh/config.yaml.\nRun `oh init` first to pick a provider — including local options (Ollama, llama.cpp, LM Studio) that don't need API keys.\n");
+        process.exit(2);
+    }
+    if (LOCAL_PROVIDERS.has(provider.toLowerCase())) {
+        console.log([
+            `${provider} runs locally and doesn't use an API key — nothing to log in.`,
+            "",
+            "To configure your local model and base URL, run:",
+            "  oh init",
+            "",
+            "Or skip the wizard and run directly:",
+            `  oh --model ${provider}/<model-name>`,
+        ].join("\n"));
+        return;
+    }
+    let key = opts.key;
+    if (!key) {
+        // TTY: prompt the user for a key (one line, hidden behavior is OS-dependent
+        // — we don't try to mask, callers wanting silent input should pipe).
+        // Non-TTY: read until EOF so `echo $KEY | oh auth login` works.
+        if (process.stdin.isTTY) {
+            const readline = await import("node:readline");
+            const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+            key = await new Promise((resolve) => {
+                rl.question(`Enter API key for ${provider}: `, (answer) => {
+                    rl.close();
+                    resolve(answer.trim());
+                });
+            });
+        }
+        else {
+            const chunks = [];
+            for await (const chunk of process.stdin)
+                chunks.push(chunk);
+            key = Buffer.concat(chunks).toString("utf8").trim();
+        }
+    }
+    if (!key) {
+        process.stderr.write("Error: no API key provided (pass --key <value> or pipe on stdin).\n");
+        process.exit(2);
+    }
+    setCredential(`${provider}-api-key`, key);
+    console.log(`Stored API key for ${provider} in ~/.oh/credentials.enc.`);
+});
+authCmd
+    .command("logout [provider]")
+    .description("Clear the stored API key for a provider")
+    .action(async (providerArg) => {
+    const { deleteCredential, getCredential } = await import("./harness/credentials.js");
+    const cfg = readOhConfig();
+    const provider = providerArg ?? cfg?.provider;
+    if (!provider) {
+        process.stderr.write("Error: no provider specified and no default in .oh/config.yaml.\n");
+        process.exit(2);
+    }
+    const key = `${provider}-api-key`;
+    if (!getCredential(key)) {
+        console.log(`No stored API key for ${provider}.`);
+        return;
+    }
+    deleteCredential(key);
+    console.log(`Cleared stored API key for ${provider}.`);
+});
+authCmd
+    .command("status")
+    .description("Show which providers have stored API keys")
+    .action(async () => {
+    const { listCredentials } = await import("./harness/credentials.js");
+    const keys = listCredentials();
+    const providerKeys = keys.filter((k) => k.endsWith("-api-key"));
+    if (providerKeys.length === 0) {
+        console.log("No stored API keys.");
+        console.log("");
+        console.log("To add one (cloud providers): oh auth login <provider>");
+        console.log("To use a local LLM (no key):  oh init   — picks Ollama / llama.cpp / LM Studio");
+        return;
+    }
+    console.log("Stored API keys:");
+    for (const k of providerKeys) {
+        const provider = k.replace(/-api-key$/, "");
+        console.log(`  ${provider}`);
+    }
+    // Also show env-var status — useful when debugging which path resolveApiKey takes.
+    const envProviders = ["anthropic", "openai", "openrouter"].filter((p) => process.env[`${p.toUpperCase()}_API_KEY`]);
+    if (envProviders.length > 0) {
+        console.log("");
+        console.log("Env-var keys (override stored):");
+        for (const p of envProviders)
+            console.log(`  ${p} (${p.toUpperCase()}_API_KEY)`);
+    }
+    console.log("");
+    console.log("Local LLMs (Ollama / llama.cpp / LM Studio) need no auth — configure via `oh init`.");
+});
+// ── update (audit B7) — provider-agnostic self-update guidance ──
+program
+    .command("update")
+    .description("Show the right upgrade command for how this CLI was installed")
+    .action(async () => {
+    const { detectInstallMethod, getDefaultMainPath } = await import("./utils/install-method.js");
+    const result = detectInstallMethod(getDefaultMainPath());
+    console.log();
+    console.log(`  Current version: ${VERSION}`);
+    console.log(`  Install method: ${result.method}`);
+    console.log();
+    console.log(result.message);
+    console.log();
 });
 // ── sessions ──
 program
@@ -1063,60 +1369,7 @@ program
         process.exit(0);
     });
 });
-// ── auth ──
-program
-    .command("auth")
-    .description("Manage API key credentials")
-    .argument("<action>", "login | logout | status")
-    .argument("[provider]", "Provider name (anthropic, openai, openrouter)")
-    .action(async (action, providerName) => {
-    const { setCredential, deleteCredential, listCredentials, getCredential } = await import("./harness/credentials.js");
-    if (action === "status") {
-        const keys = listCredentials();
-        if (keys.length === 0) {
-            console.log("  No stored credentials. API keys come from environment variables or config.yaml.");
-            return;
-        }
-        console.log("\n  Stored credentials:");
-        for (const k of keys) {
-            const val = getCredential(k);
-            console.log(`  ${k}: ${val ? `****${val.slice(-4)}` : "(empty)"}`);
-        }
-        console.log();
-        return;
-    }
-    if (action === "login") {
-        if (!providerName) {
-            console.error("  Usage: oh auth login <provider>");
-            process.exit(1);
-        }
-        // Read key from stdin
-        process.stdout.write(`  Enter API key for ${providerName}: `);
-        const chunks = [];
-        for await (const chunk of process.stdin) {
-            chunks.push(chunk);
-            break;
-        }
-        const key = Buffer.concat(chunks).toString("utf-8").trim();
-        if (!key) {
-            console.error("  No key provided.");
-            process.exit(1);
-        }
-        setCredential(`${providerName}-api-key`, key);
-        console.log(`  ✓ API key saved securely for ${providerName}`);
-        return;
-    }
-    if (action === "logout") {
-        if (!providerName) {
-            console.error("  Usage: oh auth logout <provider>");
-            process.exit(1);
-        }
-        deleteCredential(`${providerName}-api-key`);
-        console.log(`  ✓ API key removed for ${providerName}`);
-        return;
-    }
-    console.error(`  Unknown action: ${action}. Use: login, logout, status`);
-});
+// (oh auth subcommand is registered above near the init command)
 // ── serve (MCP server) ──
 program
     .command("serve")