@scira/cli 0.1.5 → 0.1.7

package/dist/agent/harness-agent.js

@@ -0,0 +1,216 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { HarnessAgent } from "@ai-sdk/harness/agent";
+import { createClaudeCode } from "@ai-sdk/harness-claude-code";
+import { createCodex } from "@ai-sdk/harness-codex";
+import { createLocalSandbox } from "../providers/harness/local-sandbox.js";
+import { createResearchTools } from "../tools/agent-tools.js";
+import { SKILLS } from "./skills.js";
+// Scira's built-in skills surfaced to the harness runtime (the adapter
+// materializes them natively — e.g. Claude Code writes them as SKILL.md files).
+const HARNESS_SKILLS = SKILLS.map((s) => ({ name: s.name, description: s.summary, content: s.content }));
+/** Resolve a promise but never hang the caller longer than `ms`. Clears the timer when settled so it can't keep the event loop alive (e.g. delaying quit). */
+function withTimeout(p, ms) {
+    let timer;
+    const timeout = new Promise((resolve) => { timer = setTimeout(() => resolve(undefined), ms); });
+    return Promise.race([
+        Promise.resolve(p).finally(() => clearTimeout(timer)),
+        timeout,
+    ]);
+}
+function permissionModeFor(provider, config) {
+    // Codex has no built-in tool-approval flow; it only runs under allow-all.
+    if (provider === "codex")
+        return "allow-all";
+    switch (config.approvalMode) {
+        case "manual": return "allow-reads";
+        case "auto": return "allow-all";
+        default: return "allow-edits"; // "suggest"
+    }
+}
+// With no explicit `auth`, the adapters auto-detect credentials from the host
+// env (gateway key first, then provider key / base URL / org). To force the
+// bundled CLI onto the user's local OAuth login instead, we strip every env var
+// those resolvers read or emit — covering both the host-inherited copy and the
+// adapter-injected copy (the local sandbox strips after merging the spawn env).
+const GATEWAY_ENV = ["AI_GATEWAY_API_KEY", "AI_GATEWAY_BASE_URL"];
+const STRIP_ENV = {
+    "claude-code": [...GATEWAY_ENV, "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_BASE_URL"],
+    codex: [...GATEWAY_ENV, "OPENAI_API_KEY", "CODEX_API_KEY", "OPENAI_BASE_URL", "OPENAI_ORGANIZATION", "OPENAI_PROJECT"]
+};
+function buildAgent(provider, config, workspacePath, instructions, runPath) {
+    const sandbox = createLocalSandbox({ rootDir: workspacePath, stripEnv: STRIP_ENV[provider] });
+    const permissionMode = permissionModeFor(provider, config);
+    const model = config.model.trim() || undefined; // empty = CLI default
+    // Give the harness Scira's own multi-query web search + page reader as host
+    // tools, so it grounds answers through our search pipeline instead of the
+    // CLI's built-in web tools.
+    const { webSearch, readUrl } = createResearchTools(runPath, config, undefined, workspacePath, () => false);
+    // Use a non-colliding name. Claude Code ships a built-in `webSearch` (single
+    // query); naming ours the same lets the built-in shadow it, so the model ends
+    // up doing single-query searches. `multiWebSearch` can't be shadowed.
+    // Cast bridges the project's `ai` Tool type to the harness's bundled-`ai`
+    // ToolSet (same runtime shape, different package versions).
+    const tools = { multiWebSearch: webSearch, readUrl };
+    // The harness CLI writes relative to its own working directory and has no
+    // knowledge of Scira's run layout, so pin the exact run directory and require
+    // absolute paths for artifacts — otherwise it guesses (e.g. ~/.scira/runs/).
+    const runDir = path.resolve(runPath);
+    const runDirSteer = `\n\nRUN DIRECTORY: Write every run artifact — plan.md, notes.md, sources.jsonl, claims.jsonl, report.md — to this exact absolute path, nowhere else:\n  ${runDir}\nFor example, the report goes to ${runDir}/report.md. Always use the absolute path; do not use a bare "sources.jsonl" or a ".scira/runs/…" path. If a file already exists, Read it before writing (your Write tool requires that) — or edit it in place.`;
+    // Positive, authoritative steering pointing at the unique tool name.
+    const webSteer = `\n\nWEB ACCESS: For any web search use the \`multiWebSearch\` tool and pass 3-5 query variations in a single call (it searches them in parallel). Use \`readUrl\` to read a specific page. These are your only web tools.`;
+    const fullInstructions = `${instructions}${runDirSteer}${webSteer}`;
+    // No `auth`: the bundled CLI authenticates with the user's local login
+    // (`claude login` → ~/.claude, `codex login` → ~/.codex). We never pass an
+    // API key, so a Pro/Max/ChatGPT subscription session is used as-is.
+    const harness = provider === "claude-code"
+        ? createClaudeCode({
+            model,
+            thinking: config.harness.thinking,
+            maxTurns: config.harness.maxTurns
+        })
+        : createCodex({
+            model,
+            reasoningEffort: config.harness.reasoningEffort,
+            // Built-in harness web search is always disabled.
+            webSearch: false
+        });
+    return new HarnessAgent({ harness, sandbox, permissionMode, instructions: fullInstructions, tools, skills: HARNESS_SKILLS });
+}
+/** Settings that, if changed, require rebuilding the session (not just the prompt). */
+function settingsFingerprint(provider, config) {
+    return JSON.stringify([provider, config.model, config.approvalMode, config.harness]);
+}
+// One live harness session per run directory, reused across turns so the
+// underlying CLI keeps its native conversation/workspace state.
+const sessions = new Map();
+function messageText(content) {
+    if (typeof content === "string")
+        return content;
+    return content
+        .map((part) => (part.type === "text" ? part.text : ""))
+        .join("");
+}
+function lastUserText(args) {
+    const { prompt, messages } = args;
+    if (typeof prompt === "string")
+        return prompt;
+    if (Array.isArray(messages)) {
+        for (let i = messages.length - 1; i >= 0; i--) {
+            if (messages[i].role === "user")
+                return messageText(messages[i].content);
+        }
+    }
+    return "";
+}
+function stateFile(runPath) {
+    return path.join(runPath, "harness-state.json");
+}
+async function readPersistedState(runPath) {
+    try {
+        return JSON.parse(await fs.readFile(stateFile(runPath), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+async function clearPersistedState(runPath) {
+    await fs.rm(stateFile(runPath), { force: true }).catch(() => { });
+}
+async function acquireSession(runPath, provider, config, workspacePath, instructions, abortSignal) {
+    const fingerprint = settingsFingerprint(provider, config);
+    const existing = sessions.get(runPath);
+    // Reuse only if provider/model/approval/harness settings are unchanged.
+    if (existing && existing.fingerprint === fingerprint)
+        return existing;
+    if (existing) {
+        await withTimeout(existing.session.destroy(), 5000).catch(() => { });
+        sessions.delete(runPath);
+    }
+    const agent = buildAgent(provider, config, workspacePath, instructions, runPath);
+    // Try to resume the run's prior harness session (across process restarts).
+    // Only when the persisted settings match; any failure falls back to fresh.
+    let session;
+    const persisted = await readPersistedState(runPath);
+    if (persisted && persisted.provider === provider && persisted.fingerprint === fingerprint) {
+        try {
+            session = await agent.createSession({ sessionId: runPath, resumeFrom: persisted.state, abortSignal });
+        }
+        catch {
+            await clearPersistedState(runPath);
+            session = undefined;
+        }
+    }
+    if (!session)
+        session = await agent.createSession({ sessionId: runPath, abortSignal });
+    const entry = { agent, session, provider, fingerprint };
+    sessions.set(runPath, entry);
+    return entry;
+}
+/**
+ * Stop a live session, persisting its resume state so the run can continue in a
+ * future process. Falls back to destroy() (and clears stale state) on failure.
+ */
+async function stopAndPersist(runPath, entry) {
+    try {
+        // Bounded so a wedged bridge can't hang TUI teardown.
+        const state = await withTimeout(entry.session.stop(), 5000);
+        if (state === undefined)
+            throw new Error("stop() timed out");
+        const payload = { provider: entry.provider, fingerprint: entry.fingerprint, state };
+        await fs.writeFile(stateFile(runPath), JSON.stringify(payload), "utf8");
+    }
+    catch {
+        await withTimeout(entry.session.destroy(), 5000).catch(() => { });
+        await clearPersistedState(runPath);
+    }
+}
+/**
+ * A ToolLoopAgent-shaped wrapper around a local harness session. `stream()`
+ * matches the subset the TUI's `consume()` loop uses, so harness providers drop
+ * into the same turn pipeline as the LLM providers.
+ */
+class HarnessChatAgent {
+    runPath;
+    provider;
+    config;
+    workspacePath;
+    instructions;
+    constructor(runPath, provider, config, workspacePath, instructions) {
+        this.runPath = runPath;
+        this.provider = provider;
+        this.config = config;
+        this.workspacePath = workspacePath;
+        this.instructions = instructions;
+    }
+    async stream(options) {
+        const abortSignal = options.abortSignal;
+        const { agent, session } = await acquireSession(this.runPath, this.provider, this.config, this.workspacePath, this.instructions, abortSignal);
+        const prompt = lastUserText(options);
+        const result = await agent.stream({ session, prompt, abortSignal });
+        return result;
+    }
+}
+/**
+ * Build a harness-backed chat bundle for `config.llmProvider` (claude-code /
+ * codex). The session persists across turns; `close()` is a no-op so the native
+ * CLI state survives. Use {@link closeHarnessSession} on `/new` or teardown.
+ */
+export function createHarnessBundle(opts) {
+    const agent = new HarnessChatAgent(opts.runPath, opts.provider, opts.config, opts.workspacePath, opts.instructions);
+    return { agent, close: async () => { } };
+}
+/** Stop a run's harness session and persist its resume state. No-op if none. */
+export async function closeHarnessSession(runPath) {
+    const entry = sessions.get(runPath);
+    if (!entry)
+        return;
+    sessions.delete(runPath);
+    await stopAndPersist(runPath, entry);
+}
+/** Stop every live harness session, persisting resume state. Intended for process shutdown. */
+export async function closeAllHarnessSessions() {
+    const entries = [...sessions.entries()];
+    sessions.clear();
+    await Promise.all(entries.map(([runPath, entry]) => stopAndPersist(runPath, entry)));
+}

package/dist/agent/{research-agent.js → main-agent.js}

@@ -2,7 +2,8 @@ import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { ToolLoopAgent, isLoopFinished } from "ai";
 import { Spinner } from "picospinner";
-import { getLanguageModel, requireLlmKeys } from "../providers/llm/registry.js";
+import { getLanguageModel, requireLlmKeys, isHarnessProvider } from "../providers/llm/registry.js";
+import { createHarnessBundle } from "./harness-agent.js";
 import { createResearchTools, createOneShotTools, createCodingTools, wrapToolsForPlanMode } from "../tools/agent-tools.js";
 import { SKILL_CATALOG } from "./skills.js";
 import { createMcpBridge } from "../tools/mcp-bridge.js";
@@ -25,7 +26,7 @@ You are in plan mode. Explore and plan before making changes.
 - Read-only bash is OK: ls, cat, git status, git log, git diff, find, grep (workspace-relative paths only)
 - When the plan is ready, summarize it and tell the user to type /plan to exit plan mode and begin execution`;
 }
-function instructions(goal, config, options = {}) {
+function instructions(goal, config, options = {}, runPath) {
     const { workspacePath } = options;
     const planMode = resolvePlanMode(options);
     const now = new Date();
@@ -42,12 +43,13 @@ function instructions(goal, config, options = {}) {
 
 PROJECT LAYOUT:
 - Project root (codebase): ${workspacePath}
-- Run harness (.scira/runs/…): plan.md, notes.md, report.md, sources.jsonl, claims.jsonl, todos.json
+- This run's directory: ${runPath ?? "(the active run)"}  ← artifacts live here
+- Run artifacts: plan.md, notes.md, report.md, sources.jsonl, claims.jsonl, todos.json — pass the bare filename (e.g. \`report.md\`) or the absolute path above. Don't guess a \`.scira/runs/…\` path.
 
 FILE TOOLS:
 - readFile / writeFile / editFile route automatically:
-  - Harness files by bare name: plan.md, notes.md, report.md, sources.jsonl → stored under .scira/runs/
-  - Everything else (src/…, package.json, …) → project root
+  - Harness files (plan.md, notes.md, report.md, sources.jsonl, claims.jsonl): pass the BARE filename only — e.g. \`plan.md\`. The tool puts it in this run's directory for you. Never prefix it with a directory, \`.scira\`, \`runs\`, or \`latest\`; those paths are rejected.
+  - Source code / project files (src/…, package.json, …): relative to the project root.
 - Never write source code under .scira. Never put harness files at the project root.
 
 CODING TOOLS:
@@ -62,7 +64,7 @@ When the task involves code:
 - Use editFile for precise changes, writeFile for new source files (paths like src/foo.ts)
 - Run tests/builds with bash; use bash action=background for servers then action=output to check logs
 - Match existing code style and patterns` : "";
-    return `You are Scira AI CLI, made by Zaid Mukaddam, an autonomous research ${workspacePath ? "and coding " : ""}agent.${workspacePath ? " Source code lives at the project root; harness artifacts live under .scira/runs/." : " You operate inside a single run directory on the user's machine."}
+    return `You are Scira AI CLI, made by Zaid Mukaddam, an autonomous research ${workspacePath ? "and coding " : ""}agent.${workspacePath ? ` Source code lives at the project root; run artifacts live in this run's directory${runPath ? ` (${runPath})` : ""}.` : ` You operate inside a single run directory${runPath ? ` (${runPath})` : ""} on the user's machine.`}
 
 Your goal:
 ${goal}
@@ -129,6 +131,15 @@ Rules for browser tools:
 }
 export async function createResearchAgent(runPath, goal, config, onApprovalRequired, options = {}) {
     requireLlmKeys(config);
+    if (isHarnessProvider(config.llmProvider)) {
+        return createHarnessBundle({
+            runPath,
+            provider: config.llmProvider,
+            config,
+            workspacePath: options.workspacePath ?? process.cwd(),
+            instructions: instructions(goal, config, options, runPath)
+        });
+    }
     const bridge = await createMcpBridge(config);
     const getPlanMode = options.getPlanMode ?? (() => options.planMode ?? false);
     const researchTools = createResearchTools(runPath, config, onApprovalRequired, options.workspacePath, getPlanMode);
@@ -139,18 +150,18 @@ export async function createResearchAgent(runPath, goal, config, onApprovalRequi
     const bgContext = options.backgroundTasks ? await options.backgroundTasks.formatContextForAgent() : "";
     const agent = new ToolLoopAgent({
         model: getLanguageModel(config),
-        instructions: instructions(goal, config, options) + bgContext + devtoolsInstructionsBlock(bridge.toolNames),
+        instructions: instructions(goal, config, options, runPath) + bgContext + devtoolsInstructionsBlock(bridge.toolNames),
         tools,
         stopWhen: isLoopFinished()
     });
     return { agent, close: bridge.close };
 }
-function oneShotInstructions(goal, hasDevtools, options = {}) {
+function oneShotInstructions(goal, hasDevtools, options = {}, runPath) {
     const { workspacePath } = options;
     const planMode = resolvePlanMode(options);
     const codingHint = workspacePath ? `
 
-Project root: ${workspacePath}. readFile/writeFile/editFile route code paths to the project root; harness files (plan.md, notes.md, …) stay under .scira/runs/.
+Project root: ${workspacePath}. readFile/writeFile/editFile route code paths to the project root; run artifacts (plan.md, notes.md, …) go in this run's directory${runPath ? ` (${runPath})` : ""} — pass the bare filename or that absolute path.
 - listWorkspaceDir, grepWorkspace, bash (with background tasks), todo
 Use them for code questions, debugging, and implementation tasks.` : "";
     const now = new Date();
@@ -194,6 +205,15 @@ Step 2 — If you decide to answer directly:
 }
 export async function createOneShotAgent(runPath, goal, config, onApprovalRequired, onEscalate, options = {}) {
     requireLlmKeys(config);
+    if (isHarnessProvider(config.llmProvider)) {
+        return createHarnessBundle({
+            runPath,
+            provider: config.llmProvider,
+            config,
+            workspacePath: options.workspacePath ?? process.cwd(),
+            instructions: oneShotInstructions(goal, false, options, runPath)
+        });
+    }
     const bridge = await createMcpBridge(config);
     const getPlanMode = options.getPlanMode ?? (() => options.planMode ?? false);
     const tools = {
@@ -203,7 +223,7 @@ export async function createOneShotAgent(runPath, goal, config, onApprovalRequir
     const bgContext = options.backgroundTasks ? await options.backgroundTasks.formatContextForAgent() : "";
     const agent = new ToolLoopAgent({
         model: getLanguageModel(config),
-        instructions: oneShotInstructions(goal, bridge.toolNames.length > 0, options) + bgContext + devtoolsInstructionsBlock(bridge.toolNames),
+        instructions: oneShotInstructions(goal, bridge.toolNames.length > 0, options, runPath) + bgContext + devtoolsInstructionsBlock(bridge.toolNames),
         tools,
         stopWhen: isLoopFinished()
     });

package/dist/cli/commands/init.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-import { mkdir, writeFile, readFile } from "node:fs/promises";
+import { mkdir } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -33,8 +33,8 @@ export async function initCommand() {
     // Create .scira directory if it doesn't exist
     await mkdir(SCIRA_DIR, { recursive: true });
     // Read existing .env and config
-    const existingEnv = existsSync(ENV_FILE) ? parseEnvFile(await readFile(ENV_FILE, "utf8")) : {};
-    const existingConfig = existsSync(CONFIG_FILE) ? JSON.parse(await readFile(CONFIG_FILE, "utf8")) : null;
+    const existingEnv = existsSync(ENV_FILE) ? parseEnvFile(await Bun.file(ENV_FILE).text()) : {};
+    const existingConfig = existsSync(CONFIG_FILE) ? (await Bun.file(CONFIG_FILE).json()) : null;
     // Ask if user wants to reconfigure
     const shouldReconfigure = existingConfig ? await p.confirm({
         message: "Configuration already exists. Reconfigure?",
@@ -247,7 +247,7 @@ export async function initCommand() {
     const envContent = Object.entries(envKeys)
         .map(([key, value]) => `${key}=${value}`)
         .join("\n");
-    await writeFile(ENV_FILE, envContent, "utf8");
+    await Bun.write(ENV_FILE, envContent);
     p.log.success("API keys saved to ~/.scira/.env");
     // Step 3: Model Selection
     p.note("Select your AI model", "Model");
@@ -261,6 +261,7 @@ export async function initCommand() {
             model: defaultModelFor(llmProvider),
             lastModels: {},
             approvalMode: "suggest",
+            harness: { thinking: "adaptive", reasoningEffort: "medium" },
             alwaysAllowLinks: false,
             runDirectory: ".scira/runs",
             maxSources: 20,
@@ -346,6 +347,7 @@ export async function initCommand() {
         model,
         lastModels: { [llmProvider]: model, ...(existingConfig?.lastModels || {}) },
         approvalMode: approvalMode,
+        harness: existingConfig?.harness ?? { thinking: "adaptive", reasoningEffort: "medium" },
         alwaysAllowLinks: existingConfig?.alwaysAllowLinks ?? false,
         search: {
             provider: searchProvider,
@@ -366,7 +368,7 @@ export async function initCommand() {
             servers: [],
         },
     };
-    await writeFile(CONFIG_FILE, JSON.stringify(config, null, 2), "utf8");
+    await Bun.write(CONFIG_FILE, JSON.stringify(config, null, 2));
     p.log.success("Configuration saved to ~/.scira/config.json");
     // Step 5: Verify
     p.note("Verifying your setup...", "Verification");

package/dist/cli/index.js

@@ -4,8 +4,9 @@ if (typeof Bun === "undefined") {
     console.error("scira requires Bun. Install it from https://bun.sh and run: bun run dist/cli/index.js");
     process.exit(1);
 }
-import { readFileSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import sade from "sade";
@@ -16,7 +17,7 @@ loadSciraEnv(process.cwd());
 import { loadConfig } from "../config/load-config.js";
 import { createRun, findRun, listRuns, summarizeRun, verificationReport, getRunPaths } from "../storage/run-store.js";
 import { readJsonl } from "../storage/jsonl.js";
-import { runResearchAgent } from "../agent/research-agent.js";
+import { runResearchAgent } from "../agent/main-agent.js";
 import { openShell } from "./shell/shell.js";
 import { openTui, openTuiHome } from "./shell/tui.js";
 import { detectEnv } from "../providers/llm/readiness.js";
@@ -28,6 +29,17 @@ import { createMcpBridge } from "../tools/mcp-bridge.js";
 import { saveGlobalMcpConfig } from "../config/load-config.js";
 import { runOAuthFlow } from "../tools/mcp-oauth.js";
 import { initCommand } from "./commands/init.js";
+import { checkForUpdate, formatUpdateNotice } from "../utils/update-check.js";
+// Once per invocation (throttled to a real npm check at most daily): surface an
+// available update. The TUI shows it as an in-app notice; CLI commands print it.
+// Skip for --version/--help so those stay instant (the daily check can spend up
+// to ~3s on the network, and sade prints+exits for these before any command).
+const argv = process.argv.slice(2);
+const wantsUpdateCheck = !argv.some((a) => ["-v", "--version", "-h", "--help"].includes(a));
+const update = wantsUpdateCheck ? await checkForUpdate(pkgVersion) : null;
+const updateNotice = update ? formatUpdateNotice(update) : undefined;
+// The TUI renders the notice in-app, so the finally banner would double it up.
+let noticeShownInApp = false;
 const prog = sade("scira");
 prog
     .version(pkgVersion)
@@ -39,7 +51,8 @@ prog
     const question = opts._.length > 0 ? opts._.join(" ") : undefined;
     const config = await loadConfig();
     if (!question) {
-        await openTuiHome(config);
+        noticeShownInApp = !!updateNotice;
+        await openTuiHome(config, updateNotice);
         return;
     }
     requireLlmKeys(config);
@@ -65,7 +78,8 @@ prog
     const config = await loadConfig();
     const run = await createRun(question, config);
     if (opts.tui) {
-        await openTui(run.path, config);
+        noticeShownInApp = !!updateNotice;
+        await openTui(run.path, config, updateNotice);
     }
     else if (opts.shell) {
         await openShell(run.path, config);
@@ -86,7 +100,8 @@ prog
         await openShell(runPath, config);
     }
     else {
-        await openTui(runPath, config);
+        noticeShownInApp = !!updateNotice;
+        await openTui(runPath, config, updateNotice);
     }
 });
 prog
@@ -131,7 +146,7 @@ prog
     const runPath = await findRun(runId, config);
     let output;
     if (fmt === "md") {
-        output = await readFile(`${runPath}/report.md`, "utf8");
+        output = await Bun.file(`${runPath}/report.md`).text().catch(() => "");
     }
     else {
         const { toJson, toCsv } = await import("../export/formatters.js");
@@ -148,7 +163,7 @@ prog
         const { writeFile, mkdir } = await import("node:fs/promises");
         const { dirname } = await import("node:path");
         await mkdir(dirname(opts.output), { recursive: true });
-        await writeFile(opts.output, output, "utf8");
+        await Bun.write(opts.output, output);
         console.log(`Exported to ${opts.output}`);
     }
     else {
@@ -331,6 +346,9 @@ prog
     const nodeCheck = checkNodeVersion(20);
     const nodeStatus = nodeCheck.ok ? "ok" : "fail";
     console.log(`Node:           ${process.version} (${nodeStatus}, requires >=${nodeCheck.required})`);
+    const bunVersion = await getBunVersion();
+    const bunOk = bunVersion !== null && versionAtLeast(bunVersion, "1.2.0");
+    console.log(`Bun:            ${bunVersion ?? "not found"} (${bunOk ? "ok" : "fail"}, requires >=1.2.0)`);
     console.log(`LLM provider:   ${config.llmProvider}`);
     console.log(`Model:          ${config.model}`);
     console.log(`Search provider: ${config.search.provider}`);
@@ -343,6 +361,24 @@ prog
         console.log(`  ${status} ${check.name}${tag}  - ${check.purpose}`);
     }
     console.log("");
+    console.log("Local agent runtimes (claude-code / codex providers):");
+    // Claude Code's token lives in the Keychain on macOS, but the logged-in
+    // account metadata is mirrored in ~/.claude.json (oauthAccount), so that's a
+    // reliable, cross-platform login check. Codex stores a readable auth file.
+    const claudeOnPath = await commandResolves("claude");
+    const claudeAccount = readClaudeAccount();
+    const claudeStatus = !claudeOnPath ? "missing" : claudeAccount ? "ok     " : "no auth";
+    const claudeWho = claudeAccount ? ` (logged in as ${claudeAccount})` : "";
+    console.log(`  ${claudeStatus} claude-code  - "claude" ${claudeOnPath ? "on PATH" : "not on PATH (install Claude Code)"}, login ${claudeAccount ? "found" : "not found"}${claudeWho}`);
+    if (claudeOnPath && !claudeAccount)
+        console.log(`           Tip: run "claude" and use /login (or "claude doctor" to check) — no API key needed.`);
+    const codexOnPath = await commandResolves("codex");
+    const codexLoggedIn = existsSync(join(homedir(), ".codex", "auth.json"));
+    const codexStatus = !codexOnPath ? "missing" : codexLoggedIn ? "ok     " : "no auth";
+    console.log(`  ${codexStatus} codex  - "codex" ${codexOnPath ? "on PATH" : "not on PATH (install Codex)"}, login ${codexLoggedIn ? "found" : "not found"}`);
+    if (codexOnPath && !codexLoggedIn)
+        console.log(`           Tip: run "codex login" to authenticate without an API key.`);
+    console.log("");
     console.log("MCP servers:");
     const dt = config.mcp.chromeDevtools;
     const userServers = config.mcp.servers;
@@ -392,6 +428,8 @@ prog
     const blockers = [];
     if (!nodeCheck.ok)
         blockers.push(`upgrade Node to >=${nodeCheck.required}`);
+    if (!bunOk)
+        blockers.push(bunVersion ? "upgrade Bun to >=1.2.0" : "install Bun (https://bun.sh) — Scira runs on the Bun runtime");
     if (missingRequired.length > 0) {
         blockers.push(`set ${missingRequired.map((c) => c.name).join(", ")} in ~/.scira/.env or .scira/.env in your project`);
     }
@@ -430,18 +468,35 @@ function checkNodeVersion(required) {
     const current = m ? Number(m[1]) : 0;
     return { ok: current >= required, required, current };
 }
-async function commandResolves(command) {
-    const { exec } = await import("node:child_process");
-    const { promisify } = await import("node:util");
-    const which = process.platform === "win32" ? "where" : "command -v";
+/** The logged-in Claude Code account email from ~/.claude.json, or null if not logged in. */
+function readClaudeAccount() {
     try {
-        await promisify(exec)(`${which} ${command}`);
-        return true;
+        const raw = readFileSync(join(homedir(), ".claude.json"), "utf8");
+        const account = JSON.parse(raw).oauthAccount;
+        return account?.emailAddress ?? null;
     }
     catch {
-        return false;
+        return null;
     }
 }
+/** The running Bun version (e.g. "1.3.14"), or null if not running under Bun. */
+function getBunVersion() {
+    return typeof Bun !== "undefined" ? Bun.version : null;
+}
+/** True when `version` (semver) is >= `min` (semver). */
+function versionAtLeast(version, min) {
+    const a = version.split(".").map((n) => Number.parseInt(n, 10) || 0);
+    const b = min.split(".").map((n) => Number.parseInt(n, 10) || 0);
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const x = a[i] ?? 0, y = b[i] ?? 0;
+        if (x !== y)
+            return x > y;
+    }
+    return true;
+}
+function commandResolves(command) {
+    return Bun.which(command) !== null;
+}
 try {
     const parsed = prog.parse(process.argv, { lazy: true });
     if (parsed?.handler) {
@@ -452,3 +507,9 @@ catch (error) {
     console.error(error instanceof Error ? error.message : String(error));
     process.exitCode = 1;
 }
+finally {
+    // Reminder after a CLI command finishes. Skipped when the TUI already
+    // rendered the notice in-app, so we don't show it twice.
+    if (updateNotice && !noticeShownInApp)
+        process.stderr.write(`\n\x1b[2m${updateNotice}\x1b[0m\n`);
+}

package/dist/cli/shell/shell.js

@@ -1,8 +1,7 @@
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
-import { readFile } from "node:fs/promises";
 import { getRunPaths, summarizeRun, verificationReport } from "../../storage/run-store.js";
-import { runResearchAgent } from "../../agent/research-agent.js";
+import { runResearchAgent } from "../../agent/main-agent.js";
 import { readJsonl } from "../../storage/jsonl.js";
 export async function openShell(runPath, config) {
     const rl = createInterface({ input, output });
@@ -20,7 +19,7 @@ export async function openShell(runPath, config) {
                     console.log(await renderStatus(runPath));
                     break;
                 case "/plan":
-                    console.log(await readFile(getRunPaths(runPath).plan, "utf8"));
+                    console.log(await Bun.file(getRunPaths(runPath).plan).text().catch(() => "No plan.md yet."));
                     break;
                 case "/run":
                     await runResearchAgent(runPath, state.goal, config);
@@ -38,10 +37,10 @@ export async function openShell(runPath, config) {
                     console.log(await verificationReport(runPath));
                     break;
                 case "/report":
-                    console.log(await readFile(getRunPaths(runPath).report, "utf8").catch(() => "No report.md yet."));
+                    console.log(await Bun.file(getRunPaths(runPath).report).text().catch(() => "No report.md yet."));
                     break;
                 case "/handoff":
-                    console.log(await readFile(getRunPaths(runPath).handoff, "utf8"));
+                    console.log(await Bun.file(getRunPaths(runPath).handoff).text());
                     break;
                 case "/close":
                 case "exit":

package/dist/cli/shell/tui.js

@@ -1,11 +1,14 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { render } from "ink";
 import { SciraApp } from "../../ui/ink/SciraApp.js";
-export async function openTuiHome(config) {
-    const instance = render(_jsx(SciraApp, { config: config }), { alternateScreen: true, maxFps: 20 });
+import { closeAllHarnessSessions } from "../../agent/harness-agent.js";
+export async function openTuiHome(config, updateNotice) {
+    const instance = render(_jsx(SciraApp, { config: config, updateNotice: updateNotice }), { alternateScreen: true, maxFps: 20, exitOnCtrlC: false });
     await instance.waitUntilExit();
+    await closeAllHarnessSessions();
 }
-export async function openTui(runPath, config) {
-    const instance = render(_jsx(SciraApp, { runPath: runPath, config: config }), { alternateScreen: true, maxFps: 20 });
+export async function openTui(runPath, config, updateNotice) {
+    const instance = render(_jsx(SciraApp, { runPath: runPath, config: config, updateNotice: updateNotice }), { alternateScreen: true, maxFps: 20, exitOnCtrlC: false });
     await instance.waitUntilExit();
+    await closeAllHarnessSessions();
 }

package/dist/config/env-guide.js

@@ -11,6 +11,30 @@ export const ENV_KEY_GUIDES = {
             "Create a key and paste it here (starts with vc_)."
         ]
     },
+    ANTHROPIC_API_KEY: {
+        name: "ANTHROPIC_API_KEY",
+        label: "Anthropic (Claude Code)",
+        signupUrl: "https://console.anthropic.com/",
+        docsUrl: "https://docs.anthropic.com/en/api/overview",
+        placeholder: "sk-ant-...",
+        steps: [
+            "Create an account at console.anthropic.com.",
+            "Open Settings → API Keys → Create Key.",
+            "Paste the key here (starts with sk-ant-). Powers the local Claude Code harness."
+        ]
+    },
+    OPENAI_API_KEY: {
+        name: "OPENAI_API_KEY",
+        label: "OpenAI (Codex)",
+        signupUrl: "https://platform.openai.com/api-keys",
+        docsUrl: "https://platform.openai.com/docs/api-reference",
+        placeholder: "sk-...",
+        steps: [
+            "Create an account at platform.openai.com.",
+            "Open API keys → Create new secret key.",
+            "Paste the key here (starts with sk-). Powers the local Codex harness."
+        ]
+    },
     XAI_API_KEY: {
         name: "XAI_API_KEY",
         label: "xAI (Grok)",