@nanhara/hara 0.125.3 → 0.126.0

package/dist/index.js

@@ -14,7 +14,7 @@ import { homedir, tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
 import { delimiter, dirname, join, relative, resolve } from "node:path";
-import { loadConfig, configPath, readRawConfig, writeConfigValue, setModelVisionOverride, providerEnvKey, providerDefaultBaseURL, CONFIG_KEYS, APPROVAL_MODES, SANDBOX_MODES, REASONING_EFFORTS, } from "./config.js";
+import { loadConfig, configPath, readRawConfig, writeConfigValue, setModelVisionOverride, providerCatalog, providerEnvKey, providerDefaultBaseURL, providerIsLocal, providerRequiresApiKey, normalizePersonalProviderConfig, reusablePersonalProviderApiKey, updatePersonalProviderConfig, isProviderId, CONFIG_KEYS, APPROVAL_MODES, SANDBOX_MODES, REASONING_EFFORTS, } from "./config.js";
 import { runAgent } from "./agent/loop.js";
 import { formatAgentDuration, parseAgentRunTimeoutMs, MIN_AGENT_RUN_TIMEOUT_MS, MAX_AGENT_RUN_TIMEOUT_MS, MAX_AGENT_MAX_ROUNDS, } from "./agent/limits.js";
 import { parseSchemaArg, structuredOutputTool, STRUCTURED_INSTRUCTION, STRUCTURED_NUDGE } from "./agent/structured.js";
@@ -45,8 +45,8 @@ import { resetReachability } from "./tools/net-reachability.js";
 import { resetRepeatGuard } from "./agent/repeat-guard.js";
 import { allowsEvolutionTool, EVOLUTION_SYSTEM, evolutionStatus, shouldAutoEvolve } from "./agent/evolution.js";
 import { EXPLORE_SYSTEM } from "./tools/agent.js";
-import { createAnthropicProvider } from "./providers/anthropic.js";
-import { createOpenAIProvider } from "./providers/openai.js";
+import { overrideProviderTarget, profileForConfig, resolveByokProviderTarget, resolveGatewayModel, } from "./providers/target.js";
+import { createProviderForTarget } from "./providers/factory.js";
 import { resolvePlatform } from "./providers/registry.js";
 import { boundedProviderTurn } from "./providers/bounded-turn.js";
 import { levelsFor } from "./tui/model-picker.js";
@@ -54,6 +54,7 @@ import { listModels } from "./providers/models.js";
 import { listJobs, tailJob, killJob } from "./exec/jobs.js";
 import { readModelContextFileSync } from "./fs-read.js";
 import { MIN_NODE_VERSION, unsupportedNodeMessage } from "./runtime.js";
+import { redactKnownSecrets } from "./security/secrets.js";
 /** Render the background-job list for /jobs (user-facing view of what the agent has running in the
  *  background — dev servers, watchers, long tasks). Mirrors codex/Claude-Code process visibility. */
 function renderBgJobs() {
@@ -68,7 +69,7 @@ function renderBgJobs() {
     });
     return `Background jobs — /jobs tail <id> · /jobs kill <id>:\n${rows.join("\n")}`;
 }
-import { qwenDeviceLogin, getValidQwenAuth, loadQwenToken } from "./providers/qwen-oauth.js";
+import { qwenDeviceLogin, loadQwenToken } from "./providers/qwen-oauth.js";
 import { loadAgentContext, hasAgentsMd, INIT_PROMPT, findProjectRoot } from "./context/agents-md.js";
 import { homeWorkspaceActionError, isUnsafeProjectWorkspace, resolveWorkspaceSwitch, } from "./context/workspace-scope.js";
 import { getEmbedder } from "./search/embed.js";
@@ -79,6 +80,7 @@ import { newSessionId, shortId, resolveSessionId, validSessionId, sessionFileExi
 import { consumePendingTaskSteering, continueTaskExecution, createTaskExecution, finishTaskExecution, formatTaskExecution, hasPendingTaskSteering, newSteerInteraction, newTurnInteraction, recordTaskSteering, recoverTaskExecution, routeTaskInteraction, requestsTaskContinuation, taskExecutionContext, } from "./session/task.js";
 import { displaySessionCwd, resolveSessionResumeTarget } from "./session/resume.js";
 import { setSessionForceModel, isSessionForceModel, effectiveRoleModel } from "./session/session-model.js";
+import { createPhysicalOperationDrain } from "./session/operation-drain.js";
 import { loadGlobalRoles, loadRoles, roleToolFilter, scaffoldRoles, subagentToolFilter } from "./org/roles.js";
 import { buildAgentsIndex, canonicalProjectPath, resolveAgent, loadProjects, addProject, removeProject } from "./org/projects.js";
 import { loadSkillIndex, loadSkillBody, scaffoldSkills, globalSkillsDir } from "./skills/skills.js";
@@ -93,6 +95,7 @@ import { c, out, statusLine } from "./ui.js";
 import * as bar from "./statusbar.js";
 import { nearest } from "./fuzzy.js";
 import "./tools/builtin.js"; // register read_file/write_file/bash
+import "./tools/runtime.js"; // register tool_search/tool_result_read
 import "./tools/edit.js"; // register edit_file
 import "./tools/search.js"; // register grep/glob/ls
 import "./tools/patch.js"; // register apply_patch
@@ -123,70 +126,52 @@ const pkg = {
             }
         })()),
 };
-const maskKey = (v) => (v ? `${v.slice(0, 7)}…${v.slice(-4)}` : "(unset)");
-async function buildProvider(cfg) {
+const maskKey = (v) => (v ? `••••${v.slice(-4)}` : "(unset)");
+async function buildProvider(cfg, targetOverride) {
     // Identity-profile is the source of truth for routing. `cfg` is the *merged* HaraConfig (env +
     // project + global) and still drives non-routing concerns (model overrides, baseURL fallbacks
     // for things like vision/route/fallback sidecars). The active profile decides "where to send
     // requests" — gateway (deviceToken at the gateway) vs BYOK (user's key direct to the provider).
-    const ap = loadActiveProfile();
-    // CFG-OVERRIDE PATH: when a sidecar (vision / route / fallback) calls buildProvider with a tweaked
-    // cfg that explicitly carries an apiKey + baseURL, honor those over the profile — they're the
-    // sidecar's intended target. Detected by "cfg.apiKey present + cfg.baseURL present and we're not
-    // routing to a gateway." This keeps `withRouting`/vision unchanged.
-    const isSidecarOverride = !!cfg.apiKey && !!cfg.baseURL && ap.kind === "byok" && cfg.apiKey !== ap.apiKey;
-    if (ap.kind === "gateway" && !isSidecarOverride) {
+    const { profile: ap } = profileForConfig(cfg);
+    if (ap.kind === "gateway") {
         if (!ap.gatewayUrl || !ap.deviceToken)
             return null;
         const baseURL = ap.baseURL || `${ap.gatewayUrl.replace(/\/$/, "")}/v1`;
-        const model = cfg.model || effectiveModel(ap);
-        return createOpenAIProvider({ apiKey: ap.deviceToken, baseURL, model, label: "hara-gateway", reasoningEffort: cfg.reasoningEffort });
-    }
-    // BYOK paths — use the active profile's provider/key/baseURL by default, but let the merged cfg
-    // override (so `--profile`/`HARA_PROFILE`-overridden values flow + sidecar provider builds work).
-    const provider = (cfg.provider && cfg.provider !== "hara-gateway" ? cfg.provider : ap.provider) || "anthropic";
-    const apiKey = cfg.apiKey ?? ap.apiKey;
-    // Resolve base URL: explicit (cfg → profile) wins; otherwise fall back to the provider's preset
-    // (GLM/DeepSeek/OpenRouter). This keeps `profile add --byok --provider glm` working even when the
-    // user didn't pass --base-url (anthropic/openai stay undefined → their SDK defaults).
-    const baseURL = cfg.baseURL ?? ap.baseURL ?? providerDefaultBaseURL(provider);
-    const model = cfg.model || effectiveModel(ap);
-    if (provider === "qwen-oauth") {
-        const auth = await getValidQwenAuth();
-        if (!auth)
-            return null;
-        return createOpenAIProvider({ apiKey: auth.accessToken, baseURL: auth.baseURL, model, label: "qwen-oauth", reasoningEffort: cfg.reasoningEffort });
-    }
-    if (!apiKey)
-        return null;
-    // Transport is chosen from the provider REGISTRY (the dictionary) by wire protocol — so a custom
-    // baseURL Just Works: a vendor's `.../anthropic` endpoint (DeepSeek/Kimi/GLM/MiniMax/Aliyun) speaks the
-    // Anthropic wire (gets cache_control + thinking budget), DashScope/Ollama/OpenAI speak chat, etc.
-    const wire = resolvePlatform(provider, baseURL).wireApi;
-    if (wire === "anthropic") {
-        return createAnthropicProvider({ apiKey, model, baseURL, reasoningEffort: cfg.reasoningEffort });
-    }
-    if (wire === "responses") {
-        // The OpenAI Responses API (e.g. Aliyun Token Plan's newest models) — a distinct wire hara doesn't
-        // speak yet. Fail with guidance instead of sending a chat body it will reject. (Tracked for when a
-        // Token-Plan key is available to build + verify against; the chat + anthropic endpoints work today.)
-        return {
-            id: provider,
-            model,
-            async turn() {
-                return { text: "", toolUses: [], stop: "error", errorMsg: `This endpoint uses the OpenAI Responses API, which hara doesn't speak yet. Point hara at the plan's OpenAI-compatible chat endpoint (…/compatible-mode/v1 or …/v1) or its Anthropic-compatible endpoint (…/apps/anthropic) instead.` };
-            },
-        };
-    }
-    return createOpenAIProvider({ apiKey, model, baseURL, label: provider, reasoningEffort: cfg.reasoningEffort });
+        const model = resolveGatewayModel(cfg, ap, process.env, targetOverride?.model);
+        const target = { provider: "hara-gateway", apiKey: ap.deviceToken, baseURL, model };
+        const built = await createProviderForTarget(target, cfg.reasoningEffort);
+        if (!targetOverride && built) {
+            cfg.provider = target.provider;
+            cfg.model = target.model;
+            cfg.baseURL = target.baseURL;
+            cfg.apiKey = undefined;
+        }
+        return built;
+    }
+    const baseTarget = resolveByokProviderTarget(cfg, ap, false);
+    const target = overrideProviderTarget(baseTarget, targetOverride);
+    const built = await createProviderForTarget(target, cfg.reasoningEffort);
+    // The rest of the active run (status, vision classification, role defaults, resume) must see the resolved
+    // identity route rather than the always-populated Personal/global fields. Explicit sidecars stay isolated.
+    if (!targetOverride && built) {
+        cfg.provider = target.provider;
+        cfg.model = target.model;
+        cfg.baseURL = target.baseURL;
+        cfg.apiKey = target.apiKey;
+    }
+    return built;
 }
 /** Wrap the main provider with per-turn model routing when `routeModel` is configured: trivial/non-coding
  *  turns go to the alternate (cheap/general) model, real coding/action work stays on the primary. No-op when
  *  routeModel is unset or equals the primary model. routeBaseURL/routeApiKey default to the primary's. */
 async function withRouting(primary, cfg) {
-    if (!primary || !cfg.routeModel || cfg.routeModel === cfg.model)
+    if (!primary || !cfg.routeModel || cfg.routeModel === primary.model)
         return primary;
-    const alt = await buildProvider({ ...cfg, model: cfg.routeModel, baseURL: cfg.routeBaseURL ?? cfg.baseURL, apiKey: cfg.routeApiKey ?? cfg.apiKey });
+    const alt = await buildProvider(cfg, {
+        model: cfg.routeModel,
+        ...(cfg.routeBaseURL ? { baseURL: cfg.routeBaseURL } : {}),
+        ...(cfg.routeApiKey ? { apiKey: cfg.routeApiKey } : {}),
+    });
     return alt ? routingProvider(primary, alt) : primary;
 }
 /** Guardian veto model: the CHEAP tier if `routeModel` is configured (a small classifier call, not real
@@ -197,21 +182,148 @@ async function buildGuardian(cfg, primary) {
     if (cfg.guardian === "off")
         return undefined;
     let gp = primary;
-    if (cfg.routeModel && cfg.routeModel !== cfg.model) {
-        gp = (await buildProvider({ ...cfg, model: cfg.routeModel, baseURL: cfg.routeBaseURL ?? cfg.baseURL, apiKey: cfg.routeApiKey ?? cfg.apiKey })) ?? primary;
+    if (cfg.routeModel && cfg.routeModel !== primary?.model) {
+        gp = (await buildProvider(cfg, {
+            model: cfg.routeModel,
+            ...(cfg.routeBaseURL ? { baseURL: cfg.routeBaseURL } : {}),
+            ...(cfg.routeApiKey ? { apiKey: cfg.routeApiKey } : {}),
+        })) ?? primary;
     }
     return { provider: gp, enabled: true };
 }
 function authHint(cfg) {
-    const ap = loadActiveProfile();
+    const { profile: ap } = profileForConfig(cfg);
     if (ap.kind === "gateway")
         return `Active profile '${ap.id}' is a gateway profile but is missing deviceToken — re-enroll with \`hara profile add ${ap.id} --gateway <url> --code <code>\`.`;
-    const provider = ap.provider ?? cfg.provider;
+    const target = resolveByokProviderTarget(cfg, ap, false);
+    const provider = target.provider;
     if (provider === "qwen-oauth")
         return `Run ${c.bold("hara login qwen")} to authenticate.`;
+    if (providerIsLocal(provider)) {
+        return `Start ${provider === "ollama" ? "Ollama" : "LM Studio"} at ${c.bold(target.baseURL ?? "its local endpoint")}, then choose an installed model.`;
+    }
     return `Set ${c.bold(providerEnvKey(provider))} (or ${c.bold("HARA_API_KEY")}), or run ${c.bold("hara setup")}.`;
 }
-const SETUP_DEFAULT_MODEL = { anthropic: "claude-opus-4-8", qwen: "qwen-plus", openai: "gpt-4o-mini", glm: "glm-4.6", deepseek: "deepseek-chat", openrouter: "openai/gpt-4o-mini", "qwen-oauth": "coder-model" };
+function providerEnvironmentOverride() {
+    return !!(process.env.HARA_PROVIDER ||
+        process.env.HARA_MODEL ||
+        process.env.HARA_BASE_URL);
+}
+function providerSettingsSnapshot(targetCwd) {
+    const live = loadConfig({ cwd: targetCwd });
+    const { profile, resolution } = profileForConfig(live);
+    const catalog = providerCatalog();
+    if (profile.kind === "gateway") {
+        const entry = catalog.find((candidate) => candidate.id === "hara-gateway");
+        return {
+            current: {
+                provider: "hara-gateway",
+                model: process.env.HARA_MODEL || effectiveModel(profile) || live.model,
+                baseURL: profile.baseURL || (profile.gatewayUrl ? `${profile.gatewayUrl.replace(/\/+$/, "")}/v1` : undefined),
+                location: entry.location,
+                auth: entry.auth,
+                keyConfigured: !!profile.deviceToken,
+                authenticated: !!profile.gatewayUrl && !!profile.deviceToken,
+                profileId: profile.id,
+                profileKind: profile.kind,
+                profileSource: resolution.source,
+                editable: false,
+            },
+            providers: catalog,
+        };
+    }
+    const target = resolveByokProviderTarget(live, profile, false);
+    const provider = target.provider;
+    const entry = catalog.find((candidate) => candidate.id === provider) ?? catalog[0];
+    const baseURL = target.baseURL;
+    const model = target.model;
+    const apiKey = target.apiKey;
+    const environmentOverride = providerEnvironmentOverride();
+    const keyConfigured = providerIsLocal(provider) ||
+        (provider === "qwen-oauth" ? loadQwenToken() !== null : !!apiKey);
+    return {
+        current: {
+            provider,
+            model,
+            ...(baseURL ? { baseURL } : {}),
+            location: entry.location,
+            auth: entry.auth,
+            keyConfigured,
+            authenticated: keyConfigured,
+            profileId: profile.id,
+            profileKind: profile.kind,
+            profileSource: resolution.source,
+            editable: profile.id === PERSONAL_ID && !environmentOverride,
+            ...(environmentOverride ? { environmentOverride: true } : {}),
+        },
+        providers: catalog,
+    };
+}
+async function testProviderSettingsCandidate(input) {
+    if (!isProviderId(input.provider) || input.provider === "hara-gateway") {
+        throw new Error("provider is not a configurable personal provider");
+    }
+    const candidate = normalizePersonalProviderConfig({
+        provider: input.provider,
+        model: input.model,
+        baseURL: input.baseURL,
+        apiKey: input.apiKey,
+        clearApiKey: input.clearApiKey,
+    });
+    const raw = readRawConfig();
+    const apiKey = reusablePersonalProviderApiKey(candidate, raw);
+    if (providerRequiresApiKey(candidate.provider) && !apiKey) {
+        return {
+            ok: false,
+            models: [],
+            error: "A new API key is required when the provider or endpoint changes",
+        };
+    }
+    const models = await listModels(candidate.baseURL, apiKey ?? "");
+    const probeModel = providerIsLocal(candidate.provider) &&
+        models.length > 0 &&
+        !models.includes(candidate.model) &&
+        (candidate.model === "local-model" || candidate.model === "qwen3")
+        ? models[0]
+        : candidate.model;
+    const provider = await createProviderForTarget({
+        provider: candidate.provider,
+        apiKey,
+        model: probeModel,
+        baseURL: candidate.baseURL,
+    });
+    if (!provider) {
+        const error = candidate.provider === "qwen-oauth"
+            ? "Qwen browser sign-in is not complete; run `hara login qwen` first"
+            : "provider is not authenticated";
+        return { ok: false, models, error };
+    }
+    const result = await boundedProviderTurn(provider, {
+        system: "This is a connection check. Reply with the single word ok.",
+        history: [{ role: "user", content: "ok" }],
+        tools: [],
+        onText: () => { },
+    }, { timeoutMs: 12_000, label: "provider connection test" });
+    if (result.stop === "error") {
+        return {
+            ok: false,
+            models,
+            error: redactKnownSecrets(result.errorMsg || "provider connection test failed", [apiKey]).text.slice(0, 500),
+        };
+    }
+    return { ok: true, models };
+}
+const SETUP_DEFAULT_MODEL = {
+    anthropic: "claude-opus-4-8",
+    qwen: "qwen-plus",
+    openai: "gpt-4o-mini",
+    glm: "glm-4.6",
+    deepseek: "deepseek-chat",
+    openrouter: "openai/gpt-4o-mini",
+    ollama: "qwen3",
+    lmstudio: "local-model",
+    "qwen-oauth": "coder-model",
+};
 /** Numbered provider menu for `hara setup`. Order is the displayed order; `id` maps to a ProviderId
  *  (or the special "custom"/"qwen-oauth" routes). GLM/DeepSeek carry a preset base URL so the user
  *  never types one; "custom" prompts for an OpenAI-compatible base URL. */
@@ -221,6 +333,8 @@ const SETUP_MENU = [
     { label: "GLM (Zhipu)", id: "glm" },
     { label: "DeepSeek", id: "deepseek" },
     { label: "Qwen (DashScope key)", id: "qwen" },
+    { label: "Ollama (local, no key)", id: "ollama" },
+    { label: "LM Studio (local, no key)", id: "lmstudio" },
     { label: "OpenAI-compatible (custom base URL)", id: "custom" },
     { label: "Qwen — free, no key (browser sign-in)", id: "qwen-oauth" },
 ];
@@ -299,12 +413,12 @@ function readSecret(prompt, rl) {
  *  friendly "connected" hint; the wizard saves config regardless. */
 async function pingProvider(args) {
     const { provider, apiKey, model, baseURL } = args;
-    if (!apiKey || !model)
+    if ((!apiKey && !providerIsLocal(provider)) || !model)
         return false;
-    const prov = provider === "anthropic"
-        ? createAnthropicProvider({ apiKey, model, baseURL })
-        : createOpenAIProvider({ apiKey, model, baseURL, label: provider });
     try {
+        const prov = await createProviderForTarget({ provider, apiKey: apiKey || undefined, model, baseURL });
+        if (!prov)
+            return false;
         const r = await boundedProviderTurn(prov, {
             system: "Reply with the single word: ok",
             history: [{ role: "user", content: "ping" }],
@@ -337,8 +451,11 @@ async function runSetup() {
         if (choice.id === "qwen-oauth") {
             try {
                 await qwenDeviceLogin((m) => out(m + "\n"));
-                writeConfigValue("provider", "qwen-oauth");
-                writeConfigValue("model", "coder-model");
+                updatePersonalProviderConfig({
+                    provider: "qwen-oauth",
+                    model: "coder-model",
+                    clearApiKey: true,
+                });
                 out(c.green("\n✓ Qwen OAuth complete — provider set to qwen-oauth (model coder-model).\n") + c.dim(`Check it with ${c.bold("hara doctor")}, then just run ${c.bold("hara")}.\n`));
             }
             catch (e) {
@@ -361,18 +478,20 @@ async function runSetup() {
             baseURL = providerDefaultBaseURL(provider) ?? "";
         }
         const envKey = providerEnvKey(provider);
-        const apiKey = (await readSecret(`API key ${c.dim(`(masked; blank = use the ${envKey} env var)`)}: `, rl)).trim();
+        const apiKey = providerRequiresApiKey(provider)
+            ? (await readSecret(`API key ${c.dim(`(masked; blank = use the ${envKey} env var)`)}: `, rl)).trim()
+            : "";
         const defaultModel = SETUP_DEFAULT_MODEL[choice.id === "custom" ? "openai" : provider] ?? "";
         const model = (await rl.question(`Model [${defaultModel || "?"}]: `)).trim() || defaultModel;
-        writeConfigValue("provider", provider);
-        if (baseURL)
-            writeConfigValue("baseURL", baseURL);
-        if (apiKey)
-            writeConfigValue("apiKey", apiKey);
-        if (model)
-            writeConfigValue("model", model);
+        updatePersonalProviderConfig({
+            provider,
+            model,
+            ...(baseURL ? { baseURL } : {}),
+            ...(apiKey ? { apiKey } : {}),
+            ...(!providerRequiresApiKey(provider) ? { clearApiKey: true } : {}),
+        });
         // One-shot validation ping (best-effort; never blocks saving). Only when we have a key + model.
-        if (apiKey && model) {
+        if ((apiKey || providerIsLocal(provider)) && model) {
             out(c.dim("\nChecking connection… "));
             const ok = await pingProvider({ provider, apiKey, model, baseURL: baseURL || undefined });
             out(ok ? c.green("✓ connected\n") : c.yellow(`⚠ couldn't reach ${provider} (saved anyway)\n`));
@@ -528,7 +647,7 @@ async function runOrg(task, o) {
     // Role-model resolution: respect role.model by default; --force collapses everything to cfg.model.
     const __roleModel = effectiveRoleModel(role.model, o.cfg.model);
     const roleProvider = __roleModel
-        ? ((await buildProvider({ ...o.cfg, model: __roleModel })) ?? o.baseProvider)
+        ? ((await buildProvider(o.cfg, { model: __roleModel })) ?? o.baseProvider)
         : o.baseProvider;
     const toolFilter = roleToolFilter(role);
     const history = [{ role: "user", content: await expandMentionsAsync(task, o.cwd) }];
@@ -567,7 +686,7 @@ async function runOrg(task, o) {
     // Review chain: a reviewer role inspects the diff and APPROVES or sends it back, looping until clean.
     const reviewer = roles.find((r) => r.id === "reviewer");
     const __revModel = effectiveRoleModel(reviewer?.model, o.cfg.model);
-    const revProvider = __revModel ? ((await buildProvider({ ...o.cfg, model: __revModel })) ?? o.baseProvider) : o.baseProvider;
+    const revProvider = __revModel ? ((await buildProvider(o.cfg, { model: __revModel })) ?? o.baseProvider) : o.baseProvider;
     const revSystem = reviewer?.system ?? REVIEWER_SYSTEM;
     const revTools = roleToolFilter(reviewer ? { ...reviewer, readOnly: true } : undefined) ?? ((n) => READONLY_TOOLS.has(n));
     const maxRounds = Math.max(1, o.rounds ?? 3);
@@ -639,7 +758,7 @@ async function executeAtom(atom, plan, done, roles, o) {
         return false;
     }
     const __atomModel = effectiveRoleModel(role?.model, o.cfg.model);
-    const roleProvider = __atomModel ? ((await buildProvider({ ...o.cfg, model: __atomModel })) ?? o.baseProvider) : o.baseProvider;
+    const roleProvider = __atomModel ? ((await buildProvider(o.cfg, { model: __atomModel })) ?? o.baseProvider) : o.baseProvider;
     const toolFilter = roleToolFilter(role);
     const history = [{ role: "user", content: atomPrompt(atom, plan, done) }];
     try {
@@ -903,7 +1022,7 @@ async function curateSessionLearning(provider, history, cfg, options) {
 // cannot drift into different context semantics.
 /** Summarize the conversation and replace history with the summary (keeping working-memory notes). Shared by
  *  /compact (manual) and auto-compaction. Returns the summary, or null on failure / nothing to do. */
-async function compactConversation(provider, history, meta, stats, signal, task) {
+async function compactConversation(provider, history, meta, stats, signal, task, onProviderTurn) {
     if (history.length < 2 || signal?.aborted)
         return null;
     const recent = recentHistoryForCompaction(history);
@@ -912,7 +1031,7 @@ async function compactConversation(provider, history, meta, stats, signal, task)
         history: [...compactionSourceHistory(history), { role: "user", content: "Create the bounded execution checkpoint now." }],
         tools: [],
         onText: () => { },
-    }, { timeoutMs: 60_000, label: "conversation compaction", signal });
+    }, { timeoutMs: 60_000, label: "conversation compaction", signal, onProviderTurn });
     if (signal?.aborted || r.stop === "error")
         return null;
     const rawSummary = r.text.trim();
@@ -948,7 +1067,7 @@ async function compactConversation(provider, history, meta, stats, signal, task)
 /** Auto-compact (à la Claude Code) when the last turn filled the context past the threshold, so the NEXT turn
  *  doesn't overflow. Opt-out via `autoCompact: false` / `HARA_AUTO_COMPACT=0`. Best-effort; `notify` surfaces
  *  a one-line status. Returns true if it compacted. */
-async function maybeAutoCompact(provider, history, meta, stats, cfg, notify, signal, task) {
+async function maybeAutoCompact(provider, history, meta, stats, cfg, notify, signal, task, onProviderTurn) {
     if (signal?.aborted)
         return false;
     const lastInput = stats.lastInput ?? 0;
@@ -963,14 +1082,14 @@ async function maybeAutoCompact(provider, history, meta, stats, cfg, notify, sig
     if (signal?.aborted)
         return false;
     notify(`✻ Auto-compacting conversation (context ${pct}% full, ~${Math.round(lastInput / 1000)}k tok)…`);
-    const summary = await compactConversation(provider, history, meta, stats, signal, task);
+    const summary = await compactConversation(provider, history, meta, stats, signal, task, onProviderTurn);
     if (signal?.aborted)
         return false;
     notify(summary ? `(auto-compacted — context replaced with a summary; ${meta.workingSet?.length ?? 0} notes kept)` : "(auto-compact failed — use /compact or /clear)");
     return !!summary;
 }
 /** Run a (read-only by default) sub-agent to completion, quietly, and return its final text. */
-async function runSubagent(cfg, baseProvider, cwd, sandbox, projectContext, stats, task, roleId, signal) {
+async function runSubagent(cfg, baseProvider, cwd, sandbox, projectContext, stats, task, roleId, signal, observers) {
     const roles = loadRoles(cwd);
     const roleRef = roleId?.trim();
     if (roleId !== undefined && !roleRef)
@@ -1001,7 +1120,7 @@ async function runSubagent(cfg, baseProvider, cwd, sandbox, projectContext, stat
     }
     const __subModel = effectiveRoleModel(role?.model, baseProvider.model);
     const provider = __subModel && __subModel !== baseProvider.model
-        ? ((await buildProvider({ ...cfg, model: __subModel })) ?? baseProvider)
+        ? ((await buildProvider(cfg, { model: __subModel })) ?? baseProvider)
         : baseProvider;
     // A sub-agent runs full-auto + UNCONFIRMED + parallel, so it is ALWAYS read-only — a role may narrow
     // further but can never GRANT write/exec to a fan-out sub-agent (that would bypass the approval gate).
@@ -1026,6 +1145,7 @@ async function runSubagent(cfg, baseProvider, cwd, sandbox, projectContext, stat
             signal,
             timeoutMs: Math.min(cfg.runTimeoutMs, 8 * 60_000),
             maxRounds: Math.min(cfg.maxAgentRounds, 24),
+            ...(observers ?? {}),
         });
     }
     finally {
@@ -1063,9 +1183,10 @@ function runDoctor(cfg) {
     const ok = (b) => (b ? c.green("✓") : c.red("✗"));
     const dot = c.dim("·");
     const nodeSupported = unsupportedNodeMessage() === null;
-    const hasKey = !!(cfg.apiKey || process.env[providerEnvKey(cfg.provider)] || process.env.HARA_API_KEY);
+    const envKey = providerEnvKey(cfg.provider);
+    const hasKey = !!(cfg.apiKey || (envKey ? process.env[envKey] : undefined) || process.env.HARA_API_KEY);
     const oauthOk = cfg.provider === "qwen-oauth" && loadQwenToken() !== null;
-    const authed = hasKey || oauthOk;
+    const authed = hasKey || oauthOk || providerIsLocal(cfg.provider);
     const ad = assetsDir();
     const roles = loadRoles(cfg.cwd);
     const vcap = classifyVision(cfg.provider, cfg.model, cfg.modelVision);
@@ -1074,7 +1195,7 @@ function runDoctor(cfg) {
         c.bold("hara doctor"),
         `${ok(nodeSupported)} node ${process.versions.node} ${c.dim(`(need ≥${MIN_NODE_VERSION})`)}`,
         `${dot} provider ${c.bold(cfg.provider)} · model ${c.bold(cfg.model)}${cfg.baseURL ? c.dim(" · " + cfg.baseURL) : ""}`,
-        `${ok(authed)} auth ${authed ? c.dim("configured") : c.yellow("missing — " + authHint(cfg))}`,
+        `${ok(authed)} auth ${providerIsLocal(cfg.provider) ? c.dim("not required (local endpoint)") : authed ? c.dim("configured") : c.yellow("missing — " + authHint(cfg))}`,
         `${ok(existsSync(configPath()))} config ${c.dim(configPath())}`,
         `${dot} code-assets ${existsSync(ad) ? c.dim(ad) : c.dim("none — run: hara recall --init")}`,
         `${dot} roles ${roles.length ? c.dim(`${roles.length} (${roles.slice(0, 8).map((r) => r.id).join(", ")}${roles.length > 8 ? ", …" : ""})`) : c.dim("none — run: hara roles init")}`,
@@ -1086,7 +1207,7 @@ function runDoctor(cfg) {
         `${dot} plugins ${(() => { const inst = listInstalled(); const on = enabledPlugins().length; return inst.length ? c.dim(`${on}/${inst.length} enabled: ${inst.map((p) => p.name).slice(0, 6).join(", ")}`) : c.dim("none — hara plugin add <source>"); })()}`,
         `${dot} mcp ${c.dim(`client: ${Object.keys({ ...pluginMcpServers(), ...cfg.mcpServers }).length} server(s) · serve: ${mcpServeToolNames().length} read tools via \`hara mcp\``)}`,
         `${dot} hooks ${(() => { const ph = pluginHooks(); const pre = (cfg.hooks.PreToolUse ?? []).length + (ph.PreToolUse ?? []).length; const post = (cfg.hooks.PostToolUse ?? []).length + (ph.PostToolUse ?? []).length; return pre + post ? c.dim(`${pre} pre · ${post} post`) : c.dim("none — config.json \"hooks\""); })()}`,
-        `${dot} run-limits ${c.bold(formatAgentDuration(cfg.runTimeoutMs))}${c.dim(" total · ")}${c.bold(String(cfg.maxAgentRounds))}${c.dim(" rounds · sub-agents ≤8m/24")}`,
+        `${dot} run-limits ${c.bold(formatAgentDuration(cfg.runTimeoutMs))}${c.dim(" active execution · ")}${c.bold(String(cfg.maxAgentRounds))}${c.dim(" rounds · sub-agents ≤8m/24")}`,
         `${dot} notify ${cfg.notify === "off" ? c.dim("off — hara config set notify bell|system") : c.bold(cfg.notify)}`,
         `${dot} cron ${(() => { try {
             const n = loadJobs().length;
@@ -1653,7 +1774,7 @@ profileCmd
     .option("--code <code>", "(gateway) enrollment code from your admin")
     .option("--label <label>", "human-friendly label for the profile")
     .option("--byok", "(byok) BYOK profile — bring your own provider key")
-    .option("--provider <id>", "(byok) anthropic | openai | glm | deepseek | openrouter | qwen | qwen-oauth")
+    .option("--provider <id>", "(byok/local) anthropic | openai | glm | deepseek | openrouter | qwen | qwen-oauth | ollama | lmstudio")
     .option("--key <key>", "(byok) API key (else read from the provider's env var at use-time)")
     .option("--base-url <url>", "(byok) override the provider base URL (OpenAI-compatible endpoints)")
     .option("--model <model>", "(byok) default model for this profile")
@@ -1691,17 +1812,35 @@ profileCmd
         return;
     }
     if (opts.byok || opts.provider) {
-        const provider = (opts.provider || "anthropic");
+        const requestedProvider = opts.provider || "anthropic";
+        if (!isProviderId(requestedProvider)) {
+            return void out(c.red(`Unknown provider '${requestedProvider}'. Run \`hara setup\` to see supported providers.\n`));
+        }
+        const provider = requestedProvider;
         if (provider === "hara-gateway")
             return void out(c.red("`--provider hara-gateway` is retired — use --gateway <url> --code <code> instead.\n"));
+        const preset = providerCatalog().find((entry) => entry.id === provider);
+        let normalized;
+        try {
+            normalized = normalizePersonalProviderConfig({
+                provider,
+                apiKey: opts.key,
+                baseURL: opts.baseUrl ?? preset.defaultBaseURL,
+                model: opts.model ?? preset.defaultModel,
+            });
+        }
+        catch (err) {
+            out(c.red(`Invalid provider profile: ${err instanceof Error ? err.message : String(err)}\n`));
+            process.exit(1);
+        }
         const p = {
             id,
             kind: "byok",
             label: opts.label || id,
-            provider,
-            apiKey: opts.key,
-            baseURL: opts.baseUrl,
-            defaultModel: opts.model,
+            provider: normalized.provider,
+            apiKey: normalized.apiKey,
+            baseURL: normalized.baseURL,
+            defaultModel: normalized.model,
         };
         const r = addProfile(p);
         if (!r.ok) {
@@ -1712,7 +1851,7 @@ profileCmd
         out(c.dim(`Switch to it with \`hara profile use ${id}\`.\n`));
         return;
     }
-    out(c.red("usage:\n") + c.dim("  hara profile add <id> --gateway <url> --code <code> [--label …]\n") + c.dim("  hara profile add <id> --byok --provider anthropic|openai|glm|deepseek|openrouter|qwen|qwen-oauth [--key … --base-url … --model …]\n"));
+    out(c.red("usage:\n") + c.dim("  hara profile add <id> --gateway <url> --code <code> [--label …]\n") + c.dim("  hara profile add <id> --byok --provider anthropic|openai|glm|deepseek|openrouter|qwen|qwen-oauth|ollama|lmstudio [--key … --base-url … --model …]\n"));
     process.exit(1);
 });
 profileCmd
@@ -1952,14 +2091,10 @@ program
     .option("--cwd <dir>", "default working directory for new sessions (default: current directory)")
     .option("--approval <mode>", "default approval mode for sessions: suggest | auto-edit | full-auto", "auto-edit")
     .action(async (o) => {
-    const cfg = loadConfig();
+    const cwd = o.cwd ? (await import("node:path")).resolve(o.cwd) : process.cwd();
+    const cfg = loadConfig({ cwd });
     const provider0 = await withRouting(await buildProvider(cfg), cfg);
-    if (!provider0) {
-        out(c.red(`Not authenticated for '${cfg.provider}' — run \`hara setup\` first.\n`));
-        process.exit(1);
-    }
     const guardianOpt = await buildGuardian(cfg, provider0);
-    const cwd = o.cwd ? (await import("node:path")).resolve(o.cwd) : process.cwd();
     const sandbox = (process.env.HARA_SANDBOX ?? cfg.sandbox ?? "off");
     const approval = APPROVAL_MODES.includes(o.approval) ? o.approval : "auto-edit";
     const { startServe } = await import("./serve/server.js");
@@ -1976,26 +2111,74 @@ program
         },
         buildProviderFor: async (model, effort, targetCwd) => {
             const live = loadConfig({ cwd: targetCwd ?? cwd });
-            return withRouting(await buildProvider({ ...live, model, reasoningEffort: effort ?? live.reasoningEffort }), live);
+            return withRouting(await buildProvider({
+                ...live,
+                reasoningEffort: effort ?? live.reasoningEffort,
+            }, { model }), live);
         },
         listModels: (targetCwd) => {
             const live = loadConfig({ cwd: targetCwd ?? cwd });
-            return listModels(live.baseURL ?? providerDefaultBaseURL(live.provider), live.apiKey ?? "");
+            const { profile } = profileForConfig(live);
+            if (profile.kind === "gateway") {
+                const baseURL = profile.baseURL || (profile.gatewayUrl ? `${profile.gatewayUrl.replace(/\/+$/, "")}/v1` : undefined);
+                return listModels(baseURL, profile.deviceToken ?? "");
+            }
+            const target = resolveByokProviderTarget(live, profile, false);
+            return listModels(target.baseURL, target.apiKey ?? "");
+        },
+        providerSettings: (targetCwd) => providerSettingsSnapshot(targetCwd ?? cwd),
+        testProviderSettings: (input) => testProviderSettingsCandidate(input),
+        saveProviderSettings: async (input, targetCwd) => {
+            const settingsCwd = targetCwd ?? cwd;
+            if (!isProviderId(input.provider) || input.provider === "hara-gateway") {
+                throw new Error("provider is not a configurable personal provider");
+            }
+            if (providerEnvironmentOverride()) {
+                throw new Error("provider/model/base URL is overridden by HARA_* environment variables; remove the override before editing System Settings");
+            }
+            const resolution = resolveActive(settingsCwd);
+            if (resolution.id !== PERSONAL_ID) {
+                if (resolution.source === "flag" || resolution.source === "env" || resolution.source === "pin") {
+                    throw new Error(`profile '${resolution.id}' is selected by ${resolution.source}; switch or unpin it before editing Personal provider settings`);
+                }
+                if (input.activatePersonal !== true) {
+                    throw new Error(`profile '${resolution.id}' is active; confirm activatePersonal to save and switch to Personal`);
+                }
+            }
+            const normalized = normalizePersonalProviderConfig({
+                provider: input.provider,
+                model: input.model,
+                baseURL: input.baseURL,
+                apiKey: input.apiKey,
+                clearApiKey: input.clearApiKey,
+            });
+            const raw = readRawConfig();
+            const availableKey = reusablePersonalProviderApiKey(normalized, raw);
+            if (providerRequiresApiKey(normalized.provider) && !availableKey) {
+                throw new Error("a new API key is required when the provider or endpoint changes");
+            }
+            updatePersonalProviderConfig(normalized);
+            if (resolution.id !== PERSONAL_ID) {
+                const switched = useProfile(PERSONAL_ID);
+                if (!switched.ok)
+                    throw new Error(switched.reason);
+            }
+            return providerSettingsSnapshot(settingsCwd);
         },
         effortLevels: levelsFor(resolvePlatform(cfg.provider, cfg.baseURL ?? providerDefaultBaseURL(cfg.provider)).reasoning, cfg.model).filter((e) => !!e),
         runtimeInfo: (targetCwd, selectedModel) => {
-            const live = loadConfig({ cwd: targetCwd ?? cwd });
-            const model = selectedModel ?? live.model;
+            const current = providerSettingsSnapshot(targetCwd ?? cwd).current;
+            const model = selectedModel ?? current.model;
             return {
-                providerId: live.provider,
+                providerId: current.provider,
                 model,
-                effortLevels: levelsFor(resolvePlatform(live.provider, live.baseURL ?? providerDefaultBaseURL(live.provider)).reasoning, model).filter((e) => !!e),
+                effortLevels: levelsFor(resolvePlatform(current.provider, current.baseURL).reasoning, model).filter((e) => !!e),
             };
         },
         runLimits: (targetCwd) => agentRunLimits(loadConfig({ cwd: targetCwd ?? cwd })),
-        spawnSubagent: (provider, scwd, projectContext, stats, task, role, signal) => {
+        spawnSubagent: (provider, scwd, projectContext, stats, task, role, signal, observers) => {
             const live = loadConfig({ cwd: scwd });
-            return runSubagent(live, provider, scwd, sandbox, projectContext, stats, task, role, signal);
+            return runSubagent(live, provider, scwd, sandbox, projectContext, stats, task, role, signal, observers);
         },
         guardian: guardianOpt,
         buildGuardian: async (targetCwd) => {
@@ -2006,7 +2189,8 @@ program
         sandbox,
         approval,
     });
-    out(c.bold("hara serve") + c.dim(`  ·  ws://${o.host}:${handle.port}  ·  ${cfg.provider}:${cfg.model}  ·  approval ${approval}  ·  token → ~/.hara/serve.json\n`));
+    const setupStatus = provider0 ? `${cfg.provider}:${cfg.model}` : `setup required · ${cfg.provider}:${cfg.model}`;
+    out(c.bold("hara serve") + c.dim(`  ·  ws://${o.host}:${handle.port}  ·  ${setupStatus}  ·  approval ${approval}  ·  token → ~/.hara/serve.json\n`));
     const bye = async () => {
         await handle.close();
         process.exit(0);
@@ -2834,31 +3018,39 @@ program.action(async (opts) => {
     const machineOutput = !!opts.print && !!opts.schema;
     if (opts.model)
         cfg.model = opts.model;
-    const provider0 = await withRouting(await buildProvider(cfg), cfg);
+    const provider0 = await withRouting(await buildProvider(cfg, opts.model ? { model: cfg.model } : undefined), cfg);
+    if (provider0) {
+        cfg.provider = provider0.id;
+        cfg.model = provider0.model;
+    }
     // Fallback provider, built correctly for CROSS-PROVIDER failover. The old `baseURL: fallbackBaseURL ??
     // baseURL` sent the fallback model to the PRIMARY endpoint when no fallbackBaseURL was set — e.g.
     // deepseek-v4-pro posted to coding.dashscope → 400. Now: `fallbackProvider` routes to that vendor's
     // endpoint + its own key (fallbackBaseURL/fallbackApiKey still override); without it we stay on the
     // primary endpoint (correct only for a same-endpoint fallback).
     let fallbackProv = null;
-    if (provider0 && cfg.fallbackModel && cfg.fallbackModel !== cfg.model) {
+    if (provider0 && cfg.fallbackModel && cfg.fallbackModel !== provider0.model) {
         const fp = cfg.fallbackProvider;
-        const cross = !!fp && fp !== cfg.provider;
+        const cross = !!fp && fp !== provider0.id;
         const family = (m) => m.toLowerCase().split(/[-.:/]/)[0];
-        if (cross && !cfg.fallbackApiKey && !cfg.apiKey) {
+        const fallbackEnvKey = fp ? providerEnvKey(fp) : "";
+        const crossKey = cfg.fallbackApiKey ?? (fallbackEnvKey ? process.env[fallbackEnvKey] : undefined);
+        if (fp === "hara-gateway") {
+            process.stderr.write("hara: fallbackProvider cannot be hara-gateway; select an enrolled gateway profile instead. Fallback disabled.\n");
+        }
+        else if (cross && providerRequiresApiKey(fp) && !crossKey) {
             process.stderr.write(`hara: fallbackProvider '${fp}' needs its own key — set fallbackApiKey. Fallback disabled.\n`);
         }
-        else if (!fp && !cfg.fallbackBaseURL && family(cfg.fallbackModel) !== family(cfg.model)) {
+        else if (!fp && !cfg.fallbackBaseURL && family(cfg.fallbackModel) !== family(provider0.model)) {
             // A different-looking vendor with no routing set would hit the primary endpoint and 400 on failover.
-            process.stderr.write(`hara: fallbackModel '${cfg.fallbackModel}' looks like a different vendor than '${cfg.model}', but no fallbackProvider/fallbackBaseURL is set — it would hit the PRIMARY endpoint (likely 400). Set fallbackProvider (+ fallbackApiKey). Fallback disabled.\n`);
+            process.stderr.write(`hara: fallbackModel '${cfg.fallbackModel}' looks like a different vendor than '${provider0.model}', but no fallbackProvider/fallbackBaseURL is set — it would hit the PRIMARY endpoint (likely 400). Set fallbackProvider (+ fallbackApiKey). Fallback disabled.\n`);
         }
         else {
-            fallbackProv = await buildProvider({
-                ...cfg,
-                provider: fp ?? cfg.provider,
+            fallbackProv = await buildProvider(cfg, {
+                ...(fp ? { provider: fp } : {}),
                 model: cfg.fallbackModel,
-                baseURL: cfg.fallbackBaseURL ?? (fp ? providerDefaultBaseURL(fp) : cfg.baseURL),
-                apiKey: cfg.fallbackApiKey ?? (cross ? undefined : cfg.apiKey),
+                ...(cfg.fallbackBaseURL ? { baseURL: cfg.fallbackBaseURL } : {}),
+                ...(cross ? { apiKey: crossKey } : cfg.fallbackApiKey ? { apiKey: cfg.fallbackApiKey } : {}),
             });
         }
     }
@@ -2923,12 +3115,14 @@ program.action(async (opts) => {
     // one-shot
     if (opts.print) {
         let headlessLockId = null;
-        const pendingHeadlessOperations = new Set();
-        const trackHeadlessOperation = (operation) => {
-            pendingHeadlessOperations.add(operation);
-            const settled = () => { pendingHeadlessOperations.delete(operation); };
-            void operation.then(settled, settled);
-        };
+        const headlessOperations = createPhysicalOperationDrain(() => {
+            if (!headlessLockId)
+                return;
+            const lockId = headlessLockId;
+            headlessLockId = null;
+            releaseSessionLock(lockId);
+        });
+        const trackHeadlessOperation = headlessOperations.observe;
         try {
             const projectContext = loadAgentContext(cwd) || undefined;
             // Vision sidecar for headless runs (gateway/cron): without it the computer tool's screenshots come back
@@ -2937,7 +3131,11 @@ program.action(async (opts) => {
             const describeImage = async (path, hint, signal) => {
                 const cap = classifyVision(cfg.provider, cfg.model, cfg.modelVision);
                 const vp = cfg.visionModel
-                    ? ((await buildProvider({ ...cfg, model: cfg.visionModel, baseURL: cfg.visionBaseURL ?? cfg.baseURL, apiKey: cfg.visionApiKey ?? cfg.apiKey })) ?? null)
+                    ? ((await buildProvider(cfg, {
+                        model: cfg.visionModel,
+                        ...(cfg.visionBaseURL ? { baseURL: cfg.visionBaseURL } : {}),
+                        ...(cfg.visionApiKey ? { apiKey: cfg.visionApiKey } : {}),
+                    })) ?? null)
                     : cap === "vision"
                         ? provider
                         : null;
@@ -3044,13 +3242,13 @@ program.action(async (opts) => {
                             catch { /* ignore */ }
                             cfg.model = __fb;
                             meta.model = __fb;
-                            const __rb = await buildProvider(cfg);
+                            const __rb = await buildProvider(cfg, { model: cfg.model });
                             if (__rb)
                                 provider = __rb;
                         }
                         else {
                             cfg.model = meta.model;
-                            const __rb = await buildProvider(cfg);
+                            const __rb = await buildProvider(cfg, { model: cfg.model });
                             if (__rb)
                                 provider = __rb;
                         }
@@ -3109,7 +3307,11 @@ program.action(async (opts) => {
             else if (inboundImgs.length && cfg.visionModel) {
                 let desc = "";
                 try {
-                    const vp = await buildProvider({ ...cfg, model: cfg.visionModel, baseURL: cfg.visionBaseURL ?? cfg.baseURL, apiKey: cfg.visionApiKey ?? cfg.apiKey });
+                    const vp = await buildProvider(cfg, {
+                        model: cfg.visionModel,
+                        ...(cfg.visionBaseURL ? { baseURL: cfg.visionBaseURL } : {}),
+                        ...(cfg.visionApiKey ? { apiKey: cfg.visionApiKey } : {}),
+                    });
                     if (vp)
                         desc = await describeImages(vp, inboundImgs);
                 }
@@ -3158,7 +3360,7 @@ program.action(async (opts) => {
                     headlessHooks = false;
                 const roleModel = effectiveRoleModel(requestedHeadlessRole.model, cfg.model);
                 if (roleModel && roleModel !== provider.model) {
-                    const selected = await buildProvider({ ...cfg, model: roleModel });
+                    const selected = await buildProvider(cfg, { model: roleModel });
                     if (!selected) {
                         process.stderr.write(`hara: role '${opts.role}' requires model '${roleModel}', but that provider is not authenticated.\n`);
                         process.exitCode = 2;
@@ -3172,7 +3374,15 @@ program.action(async (opts) => {
             let structuredSet = false;
             const printRunOpts = {
                 provider: headlessProvider,
-                ctx: { cwd, sandbox, spawn: (t, role, signal) => runSubagent(cfg, headlessProvider, cwd, sandbox, projectContext, stats, t, role, signal), describeImage },
+                ctx: {
+                    cwd,
+                    sandbox,
+                    spawn: (t, role, signal) => runSubagent(cfg, headlessProvider, cwd, sandbox, projectContext, stats, t, role, signal, {
+                        onProviderTurn: trackHeadlessOperation,
+                        onToolRun: trackHeadlessOperation,
+                    }),
+                    describeImage,
+                },
                 approval: "full-auto",
                 confirm: async () => true,
                 projectContext,
@@ -3239,7 +3449,7 @@ program.action(async (opts) => {
                 // Long-session safety: auto-compact before saving so a long chat/cron thread never overflows context.
                 // Silent (no-op notify) in headless mode so nothing leaks into a captured -p reply. Opt-out via config.
                 if (runOutcome.status === "completed") {
-                    await maybeAutoCompact(headlessProvider, history, meta, stats, cfg, () => { }, undefined, task);
+                    await maybeAutoCompact(headlessProvider, history, meta, stats, cfg, () => { }, undefined, task, trackHeadlessOperation);
                 }
                 saveSession(meta, history, task); // persist when resuming/continuing; plain -p stays stateless
             }
@@ -3249,19 +3459,11 @@ program.action(async (opts) => {
             return;
         }
         finally {
-            if (headlessLockId) {
-                const lockId = headlessLockId;
-                if (pendingHeadlessOperations.size) {
-                    // Do not await here: the logical deadline stays hard. A late operation with active handles keeps
-                    // this process (and therefore its cross-process session lease) alive until physical settlement.
-                    // A truly inert never-settling Promise has no side effect/handle, so normal process exit makes the
-                    // PID-backed lease safely reclaimable.
-                    void Promise.allSettled([...pendingHeadlessOperations]).then(() => releaseSessionLock(lockId));
-                }
-                else {
-                    releaseSessionLock(lockId);
-                }
-            }
+            // Do not await here: the logical deadline stays hard. The live drain includes operations registered
+            // by an already-observed outer tool after cleanup begins, and releases the PID-backed session lease
+            // only when the entire physical tree is empty. Handle-less inert Promises cannot keep the process
+            // alive; after process exit the ordinary stale-PID recovery remains authoritative.
+            headlessOperations.close();
             await closeMcp();
         }
     }
@@ -3424,13 +3626,13 @@ program.action(async (opts) => {
                 out(c.yellow(`⚠ resumed session was pinned to '${meta.model}', which isn't in this profile's availableModels (${__ap.availableModels.join(", ")}). Falling back to '${__fallback}'.\n`));
                 cfg.model = __fallback;
                 meta.model = __fallback;
-                const __rebuilt = await buildProvider(cfg);
+                const __rebuilt = await buildProvider(cfg, { model: cfg.model });
                 if (__rebuilt)
                     provider = __rebuilt;
             }
             else {
                 cfg.model = meta.model;
-                const __rebuilt = await buildProvider(cfg);
+                const __rebuilt = await buildProvider(cfg, { model: cfg.model });
                 if (__rebuilt)
                     provider = __rebuilt;
             }
@@ -3643,7 +3845,7 @@ program.action(async (opts) => {
                 setSessionForceModel(force);
                 visionProvider = undefined;
                 remindedVision = false;
-                const p = await buildProvider(cfg);
+                const p = await buildProvider(cfg, { model: cfg.model });
                 if (p) {
                     provider = p;
                     if (bar.isActive())
@@ -3985,7 +4187,11 @@ program.action(async (opts) => {
         const getVisionProvider = async () => {
             if (visionProvider !== undefined)
                 return visionProvider;
-            visionProvider = await buildProvider({ ...cfg, model: cfg.visionModel, baseURL: cfg.visionBaseURL ?? cfg.baseURL, apiKey: cfg.visionApiKey ?? cfg.apiKey });
+            visionProvider = await buildProvider(cfg, {
+                model: cfg.visionModel,
+                ...(cfg.visionBaseURL ? { baseURL: cfg.visionBaseURL } : {}),
+                ...(cfg.visionApiKey ? { apiKey: cfg.visionApiKey } : {}),
+            });
             return visionProvider;
         };
         // lets the computer tool return a screenshot as text (describe via the vision sidecar / a vision main model).
@@ -4289,7 +4495,7 @@ program.action(async (opts) => {
                             cfg.reasoningEffort = chosen.effort;
                             visionProvider = undefined;
                             remindedVision = false;
-                            const p2 = await buildProvider(cfg);
+                            const p2 = await buildProvider(cfg, { model: cfg.model });
                             if (!p2)
                                 return void h.sink.notice("(could not rebuild provider)");
                             provider = p2;
@@ -4301,7 +4507,7 @@ program.action(async (opts) => {
                         setSessionForceModel(force);
                         visionProvider = undefined; // new model may resolve a different describer / capability
                         remindedVision = false;
-                        const p = await buildProvider(cfg);
+                        const p = await buildProvider(cfg, { model: cfg.model });
                         if (p) {
                             provider = p;
                             persistSession(); // persist the session-pinned model so resume restores it