muonroi-cli 1.8.4 → 1.9.0

package/dist/src/utils/settings.js

@@ -1,7 +1,7 @@
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
-import { getEffectiveReasoningEffort, getFirstCatalogModel, getFirstCatalogProvider, getModelByTier, getModelIds, getModelInfo, MODELS, normalizeModelId, } from "../models/registry.js";
+import { getCatalogCouncilRouting, getEffectiveReasoningEffort, getFirstCatalogModel, getFirstCatalogProvider, getModelByTier, getModelIds, getModelInfo, MODELS, normalizeModelId, } from "../models/registry.js";
 import { apiBaseFor, PROVIDER_ENDPOINTS } from "../providers/endpoints.js";
 import { ALL_PROVIDER_IDS } from "../providers/types.js";
 import { logger } from "./logger.js";
@@ -72,8 +72,9 @@ export function parseSubAgentsRawList(raw) {
 export function loadValidSubAgents() {
     return parseSubAgentsRawList(loadUserSettings().subAgents);
 }
-const USER_DIR = path.join(os.homedir(), ".muonroi-cli");
-const USER_SETTINGS_PATH = path.join(USER_DIR, "user-settings.json");
+function getUserSettingsPath() {
+    return path.join(os.homedir(), ".muonroi-cli", "user-settings.json");
+}
 function ensureDir(dir) {
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -179,7 +180,7 @@ export function ensureFootprintGitignored(cwd = process.cwd()) {
     }
 }
 export function loadUserSettings() {
-    return readJson(USER_SETTINGS_PATH) || {};
+    return readJson(getUserSettingsPath()) || {};
 }
 export function saveUserSettings(partial) {
     const current = loadUserSettings();
@@ -248,7 +249,7 @@ export function saveUserSettings(partial) {
             }
             : {}),
     };
-    writeJson(USER_SETTINGS_PATH, next);
+    writeJson(getUserSettingsPath(), next);
 }
 export function loadProjectSettings() {
     const projectPath = path.join(process.cwd(), ".muonroi-cli", "settings.json");
@@ -274,10 +275,12 @@ export function saveProjectSettings(partial) {
 }
 export function getApiKey() {
     // Test escape hatch (api-key harness spec): suppress all key sources so the
-    // boot flow reaches the API-key modal. See src/index.ts resolveKeyForModel.
+    // boot flow reaches the provider picker. See src/index.ts resolveKeyForModel.
     if (process.env.MUONROI_TEST_NO_KEYCHAIN === "1")
         return undefined;
-    return process.env.MUONROI_API_KEY || loadUserSettings().apiKey;
+    // Env-only: the legacy plaintext `settings.apiKey` is migrated to the
+    // env-store on first run (migrateLegacyKeysToEnv) and no longer read here.
+    return process.env.MUONROI_API_KEY || undefined;
 }
 export function getBaseURL(provider) {
     if (process.env.MUONROI_BASE_URL)
@@ -310,11 +313,6 @@ export function getProviderConfigs(mainApiKey) {
     if (openaiKey) {
         configs.openai = { apiKey: openaiKey, baseURL: p.openai?.baseURL };
     }
-    // Google Gemini
-    const googleKey = process.env.GOOGLE_API_KEY ?? p.google?.apiKey;
-    if (googleKey) {
-        configs.google = { apiKey: googleKey, baseURL: p.google?.baseURL };
-    }
     // DeepSeek
     const deepseekKey = process.env.DEEPSEEK_API_KEY ?? p.deepseek?.apiKey;
     if (deepseekKey) {
@@ -323,14 +321,6 @@ export function getProviderConfigs(mainApiKey) {
             baseURL: p.deepseek?.baseURL ?? apiBaseFor("deepseek"),
         };
     }
-    // SiliconFlow
-    const siliconflowKey = process.env.SILICONFLOW_API_KEY ?? p.siliconflow?.apiKey;
-    if (siliconflowKey) {
-        configs.siliconflow = {
-            apiKey: siliconflowKey,
-            baseURL: p.siliconflow?.baseURL ?? apiBaseFor("siliconflow"),
-        };
-    }
     // xAI / Grok (OpenAI-compatible)
     const xaiKey = process.env.XAI_API_KEY ?? p.xai?.apiKey;
     if (xaiKey) {
@@ -339,6 +329,22 @@ export function getProviderConfigs(mainApiKey) {
             baseURL: p.xai?.baseURL ?? apiBaseFor("xai"),
         };
     }
+    // Z.ai (OpenAI-compatible)
+    const zaiKey = process.env.ZAI_API_KEY ?? p.zai?.apiKey;
+    if (zaiKey) {
+        configs.zai = {
+            apiKey: zaiKey,
+            baseURL: p.zai?.baseURL ?? apiBaseFor("zai"),
+        };
+    }
+    // OpenCode Go (OpenAI-compatible)
+    const opencodeGoKey = process.env.OPENCODE_GO_API_KEY ?? p["opencode-go"]?.apiKey;
+    if (opencodeGoKey) {
+        configs["opencode-go"] = {
+            apiKey: opencodeGoKey,
+            baseURL: p["opencode-go"]?.baseURL ?? apiBaseFor("opencode-go"),
+        };
+    }
     // Ollama — no key needed, just baseURL
     const ollamaURL = process.env.OLLAMA_URL ?? p.ollama?.baseURL ?? "http://localhost:11434";
     configs.ollama = { baseURL: ollamaURL };
@@ -591,6 +597,12 @@ export function getAutoCompactThresholdPct() {
         return val;
     return 0.4; // default 40% — Reduced from 25% after session bf58d0f46b51 analysis: 13 compacts in 43min generated 1.3M uncached tokens. Higher threshold = fewer compacts = less compaction overhead. For DeepSeek 128K context: fires at 51K instead of 32K.
 }
+export function getAutoCompactMinNewTokens() {
+    const val = loadUserSettings().autoCompactMinNewTokens;
+    if (typeof val === "number" && val >= 0 && val <= 200_000)
+        return val;
+    return 20_000; // Observed thrash: re-compact after ~14K new tokens (session ff932f8568e8).
+}
 /**
  * Per-invocation cap on cumulative tool-output chars inside a `task`
  * sub-agent. See orchestrator/sub-agent-cap.ts for the tiered compression
@@ -627,6 +639,65 @@ export function getProviderStallTimeoutMs() {
     }
     return 120_000;
 }
+/**
+ * No-forward-progress watchdog timeout (ms) for streaming model calls. Distinct
+ * from the stall watchdog: the stall watchdog re-arms on ANY stream chunk —
+ * including a reasoning model's `reasoning-delta` chunks — so a model stuck in an
+ * endless chain-of-thought keeps petting it and it NEVER fires (observed live
+ * 2026-07-10: a deepseek-v4-flash sub-agent churned reasoning for 30+ min, 1.4M
+ * input tokens, ZERO text/tool output, and the 2-min stall watchdog never tripped
+ * because reasoning chunks kept arriving). This second watchdog is petted ONLY on
+ * REAL forward progress (a text-delta or a tool-call), so a runaway-reasoning /
+ * no-output loop is aborted while a legitimately long reasoning burst that DOES
+ * eventually emit text/tools survives. Set generously above a normal reasoning
+ * burst. Range 30_000–1_800_000; 0 disables. Default 300_000 (5 min). Env
+ * override: MUONROI_PROVIDER_PROGRESS_TIMEOUT_MS.
+ */
+export function getProviderProgressTimeoutMs() {
+    const envRaw = process.env.MUONROI_PROVIDER_PROGRESS_TIMEOUT_MS;
+    if (envRaw !== undefined && envRaw !== "") {
+        const n = Number(envRaw);
+        if (Number.isFinite(n) && n === 0)
+            return 0; // explicit disable
+        if (Number.isFinite(n) && n >= 30_000 && n <= 1_800_000)
+            return Math.floor(n);
+    }
+    return 300_000;
+}
+/**
+ * Event-loop block reporting threshold (ms). The monitor
+ * (`src/utils/event-loop-monitor.ts`) reports a block when its own tick runs at
+ * least this late — evidence that the JS thread was stuck and NO timer could
+ * fire, which is why the provider stall watchdogs above cannot see this class
+ * of freeze (measured live 2026-07-16: a 304.5s TUI freeze that the 120s stall
+ * watchdog only rescued 6.7s AFTER the loop recovered).
+ *
+ * 2s is well clear of ordinary GC pauses and heavy renders while still catching
+ * anything a user would call a freeze. Range 250–60_000; 0 disables.
+ * Default 2_000. Env override: MUONROI_LOOP_BLOCK_THRESHOLD_MS.
+ */
+export function getLoopBlockThresholdMs() {
+    const envRaw = process.env.MUONROI_LOOP_BLOCK_THRESHOLD_MS;
+    if (envRaw !== undefined && envRaw !== "") {
+        const n = Number(envRaw);
+        if (Number.isFinite(n) && n === 0)
+            return 0; // explicit disable
+        if (Number.isFinite(n) && n >= 250 && n <= 60_000)
+            return Math.floor(n);
+    }
+    return 2_000;
+}
+/**
+ * Whether to run the rolling CPU profiler (`src/utils/loop-profiler.ts`) so a
+ * reported event-loop block comes with the culprit's stack rather than just a
+ * duration. OFF by default: continuous V8 sampling costs a little on every
+ * session, and this is a diagnostic for a sporadic bug, not a feature. Arm it
+ * when hunting a freeze. Env: MUONROI_LOOP_PROFILE=1 (0/unset disables).
+ */
+export function isLoopProfileEnabled() {
+    const raw = process.env.MUONROI_LOOP_PROFILE?.trim().toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
 /**
  * Number of times to AUTOMATICALLY re-issue a streaming model call after the
  * stall watchdog fires WITHOUT any chunk having arrived (a time-to-first-byte
@@ -702,17 +773,50 @@ export function getSubAgentCompactKeepLast() {
  * top-level loops typically carry more useful early context.
  * Env override: MUONROI_TOP_LEVEL_COMPACT_THRESHOLD_CHARS.
  */
-export function getTopLevelCompactThresholdChars() {
+export function getTopLevelCompactThresholdChars(contextWindowTokens) {
     const envRaw = process.env.MUONROI_TOP_LEVEL_COMPACT_THRESHOLD_CHARS;
     if (envRaw) {
         const n = Number(envRaw);
-        if (Number.isFinite(n) && n >= 50_000 && n <= 1_500_000)
+        if (Number.isFinite(n) && n >= 10_000 && n <= 1_500_000)
             return Math.floor(n);
     }
-    // Phase C5 — lowered from 200_000 to 100_000 chars (symmetric with the
-    // sub-agent 80→40K reduction). Same evidence applies: tool results are
-    // capped, so the chars threshold rarely trips while token billing climbs.
-    return 100_000;
+    // For small-context models (e.g. DeepSeek 64K), scale threshold proportionally
+    // to prevent linear token growth during tool loops. A model with 64K context
+    // gets threshold = 64000 * 4 * 0.35 = 89,600 chars (~22K tokens = 35% of window).
+    // Large-context models (128K+) keep the original 200K default.
+    if (contextWindowTokens && contextWindowTokens > 0) {
+        const dynamicThreshold = Math.floor(contextWindowTokens * 4 * 0.35);
+        return Math.min(200_000, dynamicThreshold);
+    }
+    return 200_000;
+}
+/**
+ * Compaction hysteresis factor for the top-level loop. Once B4 compaction has
+ * fired within a turn, the compacted prefix is FROZEN and only new messages are
+ * appended (keeping the provider prompt-cache prefix byte-stable) until the
+ * cumulative size grows past `lastTriggerChars * factor` — then it re-compacts.
+ *
+ * Why: measured on session 1afb2728e67a — a 24-step turn re-ran compaction every
+ * step, and each step's sliding keepLast boundary flipped one more tool result
+ * verbatim→stub, breaking the cache prefix at that position. 63% of that
+ * session's FRESH input came from 5 such compaction-induced cache breaks.
+ * Holding the boundary between compactions trades a higher peak input for far
+ * fewer cache-break re-bills.
+ *
+ * Range 1.0–3.0. Default 1.15 (re-compact at +15% growth). `1.0` or env `0`
+ * disables hysteresis → legacy per-step compaction.
+ * Env override: MUONROI_COMPACT_HYSTERESIS.
+ */
+export function getTopLevelCompactHysteresis() {
+    const envRaw = process.env.MUONROI_COMPACT_HYSTERESIS;
+    if (envRaw !== undefined && envRaw.trim() !== "") {
+        const n = Number(envRaw);
+        if (Number.isFinite(n) && n === 0)
+            return 1.0; // explicit disable
+        if (Number.isFinite(n) && n >= 1.0 && n <= 3.0)
+            return n;
+    }
+    return 1.15;
 }
 /**
  * Phase B4 — number of trailing tool turns kept verbatim during top-level
@@ -720,22 +824,59 @@ export function getTopLevelCompactThresholdChars() {
  * decisions across longer horizons.
  * Env override: MUONROI_TOP_LEVEL_COMPACT_KEEP_LAST.
  */
-export function getTopLevelCompactKeepLast() {
+export function getTopLevelCompactKeepLast(contextWindowTokens) {
     const envRaw = process.env.MUONROI_TOP_LEVEL_COMPACT_KEEP_LAST;
     if (envRaw) {
         const n = Number(envRaw);
         if (Number.isFinite(n) && n >= 1 && n <= 30)
             return Math.floor(n);
     }
+    // Small-context models (< 100K tokens) benefit from keeping fewer trailing
+    // turns — each verbatim turn with tool results + reasoning tokens costs
+    // 5-15K tokens. Reduce from 5 to 3 for small windows.
+    if (contextWindowTokens && contextWindowTokens < 100_000) {
+        return 3;
+    }
     return 5;
 }
+/**
+ * O2 — byte budget for the verbatim tail (last keepLast turns) in top-level B4
+ * compaction. The keepLast shrink is otherwise fill-ratio based, so on a
+ * large-context model a read-heavy tail stays verbatim at ~50% fill, pinning
+ * each tool round at 60-80K input (measured on July-8 sessions). This caps the
+ * tail's actual chars, shrinking keepLast further (floor 2) when the kept tool
+ * results are large. 0 disables. Env: MUONROI_TOP_LEVEL_COMPACT_TAIL_BUDGET_CHARS.
+ */
+export function getTopLevelCompactTailBudgetChars(contextWindowTokens) {
+    const envRaw = process.env.MUONROI_TOP_LEVEL_COMPACT_TAIL_BUDGET_CHARS;
+    if (envRaw !== undefined && envRaw.trim() !== "") {
+        const n = Number(envRaw);
+        // 0 = explicit disable; otherwise clamp to a sane floor so a fat-fingered
+        // tiny value can't stub away all recent context.
+        if (Number.isFinite(n) && n === 0)
+            return 0;
+        if (Number.isFinite(n) && n >= 20_000 && n <= 1_000_000)
+            return Math.floor(n);
+    }
+    // Default 50K chars (~12.5K tokens). Chosen from a deterministic measurement:
+    // on a realistic read-heavy turn the keepLast=5 verbatim tail is ~70-100K
+    // chars, so a looser budget (e.g. 120K) never bites (no-op). 50K shrinks the
+    // effective tail to ~3 turns on heavy turns (matching the sub-agent keepLast
+    // default) — ~7K tokens/call saved — while high-value results stay verbatim
+    // and light turns (below the 200K compaction threshold) are untouched. For
+    // small windows, scale to ~20% of the window so the tail can't dominate.
+    if (contextWindowTokens && contextWindowTokens > 0) {
+        return Math.min(50_000, Math.floor(contextWindowTokens * 4 * 0.2));
+    }
+    return 50_000;
+}
 /**
  * Per-turn cap on cumulative tool-output chars inside the top-level
  * orchestrator agentic loop. Same tiered compression as the sub-agent cap,
  * higher default so single-tool turns are unaffected. Env override:
  * MUONROI_TOP_LEVEL_TOOL_BUDGET_CHARS.
  */
-export function getTopLevelToolBudgetChars(maxRounds) {
+export function getTopLevelToolBudgetChars(maxRounds, contextWindowTokens) {
     const envRaw = process.env.MUONROI_TOP_LEVEL_TOOL_BUDGET_CHARS;
     if (envRaw) {
         const n = Number(envRaw);
@@ -748,10 +889,35 @@ export function getTopLevelToolBudgetChars(maxRounds) {
     // Dynamically scale default based on maxRounds relative to default base (40)
     const baseRounds = 40;
     const scale = maxRounds && maxRounds > baseRounds ? maxRounds / baseRounds : 1;
-    return Math.floor(400_000 * scale);
+    const baseDefault = Math.floor(400_000 * scale);
+    // For small-context models (e.g. DeepSeek 64K), scale the budget to 60% of
+    // the context window in chars so tiered compression kicks in before the
+    // cumulative tool output exceeds what the model can hold in context.
+    if (contextWindowTokens && contextWindowTokens > 0 && contextWindowTokens < 200_000) {
+        const windowBudget = Math.floor(contextWindowTokens * 4 * 0.6);
+        return Math.min(baseDefault, Math.max(50_000, windowBudget));
+    }
+    return baseDefault;
 }
 export function getRoleModel(role) {
-    return loadUserSettings().roleModels?.[role];
+    const configured = loadUserSettings().roleModels?.[role];
+    if (!configured)
+        return undefined;
+    // Graceful staleness guard (mirrors getCurrentModel's pickValid): a role model
+    // persisted before a catalog rename/drop (e.g. "grok-build-0.1" after it was
+    // dropped in favor of grok-composer-2.5-fast) must NOT leak a dead id to the
+    // runtime, where resolveModelRuntime throws "not found in catalog — cannot
+    // determine provider" and takes down the whole council speaker (observed:
+    // Experience Auditor on the research role). If the catalog hasn't loaded yet,
+    // trust the normalized id; otherwise drop unresolved ids so the caller falls
+    // back to its own default instead of crashing.
+    const normalized = normalizeModelId(configured);
+    if (MODELS.length === 0)
+        return normalized;
+    if (getModelInfo(normalized))
+        return normalized;
+    logger.warn("cli", `roleModels.${role} = "${configured}" is not in the catalog (renamed or removed); ignoring so the caller falls back to its default. Update it via /config.`);
+    return undefined;
 }
 export function getRoleModels() {
     return loadUserSettings().roleModels ?? {};
@@ -778,18 +944,92 @@ export function normalizeAutoCouncilMinRoles(val) {
 export function getAutoCouncilConfidence() {
     return normalizeAutoCouncilConfidence(loadUserSettings().autoCouncilConfidence);
 }
+/**
+ * Whether the auto-council path runs the pre-debate clarification interview
+ * (model-designed askcards) before debating. Default true so a broadly-scoped
+ * "debate mode" request is clarified first. Env override wins over the user
+ * setting for quick dev toggling; env "0"/"false" disables, "1"/"true" enables.
+ */
+export function isAutoCouncilClarifyEnabled() {
+    const env = process.env.MUONROI_AUTOCOUNCIL_CLARIFY?.trim().toLowerCase();
+    if (env === "0" || env === "false")
+        return false;
+    if (env === "1" || env === "true")
+        return true;
+    return loadUserSettings().autoCouncilClarify ?? true;
+}
+/**
+ * Whether auto-council should be skipped when the session model is a reasoning
+ * model. Default true. Env override wins over the user setting for quick dev
+ * toggling; env "0"/"false" disables the skip (forces council), "1"/"true"
+ * enables the skip.
+ */
+export function isAutoCouncilSkipReasoning() {
+    const env = process.env.MUONROI_AUTOCOUNCIL_SKIP_REASONING?.trim().toLowerCase();
+    if (env === "0" || env === "false")
+        return false;
+    if (env === "1" || env === "true")
+        return true;
+    return loadUserSettings().autoCouncilSkipReasoning ?? true;
+}
 export function getAutoCouncilMinRoles() {
     return normalizeAutoCouncilMinRoles(loadUserSettings().autoCouncilMinRoles);
 }
 export function isCouncilMultiProviderPreferred() {
-    return loadUserSettings().councilPreferMultiProvider ?? false;
+    const user = loadUserSettings().councilPreferMultiProvider;
+    if (user !== undefined)
+        return user;
+    return getCatalogCouncilRouting()?.prefer_multi_provider ?? true;
 }
 export function getCouncilExperienceMode() {
     return loadUserSettings().councilExperienceMode ?? "advisory";
 }
+export function normalizePeakHourPolicy(raw) {
+    if (!raw || typeof raw !== "object") {
+        return { enabled: true, mode: "switch" };
+    }
+    const p = raw;
+    return {
+        enabled: p.enabled !== false,
+        mode: p.mode === "downgrade" ? "downgrade" : "switch",
+    };
+}
+export function getPeakHourPolicy() {
+    return normalizePeakHourPolicy(loadUserSettings().peakHourPolicy);
+}
 export function isCouncilCostAware() {
     return loadUserSettings().councilCostAware ?? true;
 }
+/**
+ * Normalize a raw councilLanguage value (Feature B). Trims + lowercases the two
+ * reserved modes ("auto", "english"); any other non-empty string is preserved
+ * as-is (trimmed) so locale labels keep the user's exact casing (e.g. "日本語").
+ * Empty / non-string → "auto".
+ */
+export function normalizeCouncilLanguage(raw) {
+    if (typeof raw !== "string")
+        return "auto";
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return "auto";
+    const lower = trimmed.toLowerCase();
+    if (lower === "auto" || lower === "english")
+        return lower;
+    return trimmed;
+}
+export function getCouncilLanguage() {
+    return normalizeCouncilLanguage(loadUserSettings().councilLanguage);
+}
+/**
+ * Router tier-promotion ceiling. See UserSettings.routingPromoteMax.
+ * Default "balanced" — router may promote up to balanced but never silently
+ * to premium. Validated to the three allowed values; any unknown value
+ * falls back to the default.
+ */
+export function getRoutingPromoteMax() {
+    const raw = loadUserSettings().routingPromoteMax;
+    return raw === "off" || raw === "balanced" || raw === "any" ? raw : "balanced";
+}
 export function getDisabledProviders() {
     const raw = loadUserSettings().disabledProviders;
     if (!Array.isArray(raw))

package/dist/src/utils/side-question.d.ts

@@ -1,4 +1,3 @@
-import type { ProviderFactory as LegacyProvider } from "../providers/runtime.js";
 export interface SideQuestionResult {
     response: string;
     usage?: {
@@ -7,4 +6,4 @@ export interface SideQuestionResult {
         outputTokens?: number;
     };
 }
-export declare function runSideQuestion(question: string, provider: LegacyProvider, modelId: string, conversationContext: string, signal?: AbortSignal): Promise<SideQuestionResult>;
+export declare function runSideQuestion(question: string, modelId: string, conversationContext: string, signal?: AbortSignal): Promise<SideQuestionResult>;

package/dist/src/utils/side-question.js

@@ -3,8 +3,8 @@ import { resolveModelRuntime } from "../providers/runtime.js";
 const SIDE_QUESTION_SYSTEM = `You are a helpful coding assistant answering a quick side question. The user is in the middle of a coding session and needs a fast, concise answer. Keep your response short and focused — this is a side question, not the main task.
 
 If conversation context is provided below, use it to give a more relevant answer.`;
-export async function runSideQuestion(question, provider, modelId, conversationContext, signal) {
-    const runtime = resolveModelRuntime(provider, modelId);
+export async function runSideQuestion(question, modelId, conversationContext, signal) {
+    const runtime = resolveModelRuntime(modelId);
     const system = conversationContext
         ? `${SIDE_QUESTION_SYSTEM}\n\n<conversation_context>\n${conversationContext}\n</conversation_context>`
         : SIDE_QUESTION_SYSTEM;

package/dist/src/utils/visible-retry.d.ts

@@ -17,4 +17,15 @@ export interface VisibleRetryOpts {
     /** Hook called before each delay; default writes to stderr. */
     onRetry?: (attempt: number, totalAttempts: number, delayMs: number, error: Error) => void;
 }
+/**
+ * Optional UI sink for retry progress. The TUI registers one via
+ * {@link setRetryReporter}; without it (headless/CLI, tests) retries fall back
+ * to stderr. This exists because a raw `process.stderr.write` under OpenTUI's
+ * raw-mode alt-screen paints over wherever the cursor sits — the retry line was
+ * bleeding into the composer input frame (user-reported). Routing through a
+ * toast keeps it in the proper surface.
+ */
+type RetryReporter = (message: string, level: "warn" | "info") => void;
+export declare function setRetryReporter(fn: RetryReporter | null): void;
 export declare function withVisibleRetry<T>(fn: () => Promise<T>, opts?: VisibleRetryOpts): Promise<T>;
+export {};

package/dist/src/utils/visible-retry.js

@@ -6,9 +6,18 @@ function isRetryableError(err) {
     const msg = (e?.message ?? "").toLowerCase();
     return msg.includes("rate limit") || msg.includes("too many requests") || msg.includes("timeout");
 }
+let retryReporter = null;
+export function setRetryReporter(fn) {
+    retryReporter = fn;
+}
 function defaultOnRetry(attempt, total, delayMs, error) {
     const reason = error.statusCode === 429 ? "rate-limited (429)" : error.message.slice(0, 80);
-    process.stderr.write(`[retry] ${reason} — waiting ${Math.round(delayMs / 1000)}s before attempt ${attempt + 1}/${total}\n`);
+    const message = `[retry] ${reason} — waiting ${Math.round(delayMs / 1000)}s before attempt ${attempt + 1}/${total}`;
+    if (retryReporter) {
+        retryReporter(message, "warn");
+        return;
+    }
+    process.stderr.write(`${message}\n`);
 }
 export async function withVisibleRetry(fn, opts = {}) {
     const delays = opts.delaysMs ?? [2000, 4000, 8000, 16000, 32000];

package/dist/src/verify/entrypoint.d.ts

@@ -27,4 +27,4 @@ export declare function getVerifyCliError(options: {
     hasPrompt?: boolean;
     hasMessageArgs?: boolean;
 }): string | null;
-export { defaultShellInit, inferVerifyProjectProfile, inferVerifySmokeUrl, normalizeVerifyRecipe, type VerifyProjectProfile, } from "./recipes.js";
+export { defaultShellInit, inferVerifyProjectProfile, inferVerifySmokeUrl, normalizeVerifyRecipe, shouldTrustDeterministicRecipe, type VerifyProjectProfile, } from "./recipes.js";

package/dist/src/verify/entrypoint.js

@@ -1,3 +1,4 @@
+import { VERIFY_FAIL_MARKER, VERIFY_PASS_MARKER } from "../product-loop/verify-result.js";
 import { ensureVerifyCheckpoint } from "./checkpoint.js";
 import { loadVerifyEnvironment } from "./environment.js";
 import { buildBrowserGuidance, buildEvidenceGuidance, buildReadinessGuidance } from "./evidence.js";
@@ -69,6 +70,51 @@ export function buildVerifyTaskPrompt(cwd, settings, recipeOverride, sandboxMode
             "Phase 1 — Setup:",
             "- Probe the host for runtimes. If missing, attempt to install them or report as blockers.",
         ];
+    // Does this project actually expose a long-running app to start + smoke-test in
+    // a browser? Only then are Phase 3 (start app) / Phase 4 (browser QA) applicable.
+    // A CLI/library/script project (pytest-only Python, a Go/Rust binary, a plain
+    // script) has smokeKind "cli"/"none" and no startCommand — forcing "Start the
+    // app (REQUIRED)" + "browser QA (REQUIRED)" there is contradictory: the sub-agent
+    // cannot satisfy them, so it emits NEITHER verdict marker → parseVerifyResult →
+    // UNKNOWN → engineering-floor fails → the sprint retries forever on a passing
+    // build. Gate the runtime/browser phases and the verdict rule on this flag.
+    const hasRuntimeSmoke = profile.recipe.smokeKind === "http" && Boolean(profile.recipe.startCommand);
+    const runtimePhases = hasRuntimeSmoke
+        ? [
+            "Phase 3 — Start the app (REQUIRED, do not skip):",
+            "- Start the app using startCommand from the recipe, running it in the background.",
+            "- Wait for the app to be ready: use a curl readiness loop or `agent-browser wait --load networkidle`.",
+            "- If the app fails to start, report the error but still attempt to capture evidence (logs, screenshots).",
+            "",
+            "Phase 4 — Browser QA testing (REQUIRED, do not skip):",
+            "- You are a QA tester. Open the app in the browser and test it like a human would.",
+            `- agent-browser commands run on the HOST${sandboxMode === "shuru" ? ", not the sandbox" : ""}. They WILL work. Do not skip them.`,
+            "- Record a video of the entire browser session.",
+            "- Navigate the app: click links, buttons, menus. Verify pages load correctly.",
+            "- Check for JavaScript console errors.",
+            "- Spend 3-5 interactions testing the critical path. Take screenshots after each.",
+            "- This is the most important phase. Build/lint passing means nothing if the app doesn't actually work.",
+            "",
+            "Phase 5 — Teardown:",
+            "- Stop recording, close browser, THEN stop the dev server.",
+        ]
+        : [
+            "Phase 3 — Runtime smoke (CLI / library / script — there is NO long-running app to start):",
+            '- This project exposes no HTTP server or startable app (smokeKind is not "http"), so there is NOTHING to start in the background and NO browser QA to run.',
+            "- Do the equivalent CLI smoke instead: run the built binary / script (or the recipe's smoke command) once and confirm it produces the expected output and a zero exit code.",
+            "- Capture the exact command and its output as evidence.",
+            "- Browser and app-start phases are NOT APPLICABLE here — skipping them is CORRECT and is NOT a failure. Do NOT treat their absence as a blocker.",
+        ];
+    const verdictRule = hasRuntimeSmoke
+        ? [
+            `- After the report, emit the verdict on its own final line: exactly \`${VERIFY_PASS_MARKER}\` if install/build/test and the smoke/QA phases all succeeded, otherwise exactly \`${VERIFY_FAIL_MARKER}\`.`,
+            `- Emit \`${VERIFY_FAIL_MARKER}\` on ANY failed or skipped required phase (build error, failing test, app did not start, blocking console error). Do NOT emit \`${VERIFY_PASS_MARKER}\` if you could not actually run the recipe.`,
+        ]
+        : [
+            `- After the report, emit the verdict on its own final line: exactly \`${VERIFY_PASS_MARKER}\` if install/build/test (and the CLI smoke, if any) all succeeded, otherwise exactly \`${VERIFY_FAIL_MARKER}\`.`,
+            `- This is a CLI/library/script project with no app to start: the browser and app-start phases are N/A, NOT failures. Do NOT withhold \`${VERIFY_PASS_MARKER}\` merely because they were not run.`,
+            `- Emit \`${VERIFY_FAIL_MARKER}\` ONLY on a real failure: an install/build error, a failing test, or a CLI smoke that produced the wrong result. Do NOT emit \`${VERIFY_PASS_MARKER}\` if you could not actually run the recipe's tests.`,
+        ];
     return [
         "Run a local verification pass for the current workspace.",
         "",
@@ -90,22 +136,7 @@ export function buildVerifyTaskPrompt(cwd, settings, recipeOverride, sandboxMode
         "Phase 2 — Build and test:",
         "- Run installCommands, buildCommands, and testCommands from the recipe.",
         "",
-        "Phase 3 — Start the app (REQUIRED, do not skip):",
-        "- Start the app using startCommand from the recipe, running it in the background.",
-        "- Wait for the app to be ready: use a curl readiness loop or `agent-browser wait --load networkidle`.",
-        "- If the app fails to start, report the error but still attempt to capture evidence (logs, screenshots).",
-        "",
-        "Phase 4 — Browser QA testing (REQUIRED, do not skip):",
-        "- You are a QA tester. Open the app in the browser and test it like a human would.",
-        `- agent-browser commands run on the HOST${sandboxMode === "shuru" ? ", not the sandbox" : ""}. They WILL work. Do not skip them.`,
-        "- Record a video of the entire browser session.",
-        "- Navigate the app: click links, buttons, menus. Verify pages load correctly.",
-        "- Check for JavaScript console errors.",
-        "- Spend 3-5 interactions testing the critical path. Take screenshots after each.",
-        "- This is the most important phase. Build/lint passing means nothing if the app doesn't actually work.",
-        "",
-        "Phase 5 — Teardown:",
-        "- Stop recording, close browser, THEN stop the dev server.",
+        ...runtimePhases,
         ...buildReadinessGuidance(profile),
         ...buildBrowserGuidance(profile),
         ...buildRetryGuidance(profile),
@@ -122,6 +153,10 @@ export function buildVerifyTaskPrompt(cwd, settings, recipeOverride, sandboxMode
         "- The Summary must say what recipe/source of truth you used and whether you changed the inferred/default one.",
         "- Evidence is mandatory even on failure. If you captured screenshots, video, or logs, include their exact workspace-relative file paths in the Evidence section.",
         "- Use markdown links for artifact paths when practical, otherwise include the plain relative paths.",
+        "",
+        "Verdict marker (MANDATORY — the loop parses this, an absent marker scores the sprint 0.00):",
+        ...verdictRule,
+        "- The marker is the last line, nothing after it.",
     ].join("\n");
 }
 export function createVerifyTaskRequest(cwd, settings, recipeOverride, sandboxMode = "shuru") {
@@ -382,5 +417,5 @@ export function getVerifyCliError(options) {
     }
     return null;
 }
-export { defaultShellInit, inferVerifyProjectProfile, inferVerifySmokeUrl, normalizeVerifyRecipe, } from "./recipes.js";
+export { defaultShellInit, inferVerifyProjectProfile, inferVerifySmokeUrl, normalizeVerifyRecipe, shouldTrustDeterministicRecipe, } from "./recipes.js";
 //# sourceMappingURL=entrypoint.js.map

package/dist/src/verify/orchestrator.d.ts

@@ -1,5 +1,5 @@
 import type { TaskRequest, ToolResult, VerifyRecipe } from "../types/index.js";
-import type { SandboxSettings } from "../utils/settings.js";
+import { type SandboxSettings } from "../utils/settings.js";
 import { type PreparedVerifyCheckpoint } from "./checkpoint.js";
 import { type VerifyProjectProfile } from "./recipes.js";
 export interface VerifyAgentLike {

package/dist/src/verify/orchestrator.js

@@ -1,3 +1,4 @@
+import { getCurrentSandboxMode } from "../utils/settings.js";
 import { ensureVerifyCheckpoint } from "./checkpoint.js";
 import { buildVerifyTaskPrompt } from "./entrypoint.js";
 import { loadVerifyEnvironment, saveVerifyEnvironment } from "./environment.js";
@@ -39,8 +40,21 @@ export async function prepareVerifyRun(agent, options = {}) {
         }
     }
     const sandboxSettings = buildRuntimeSandboxSettings(profile);
-    options.onProgress?.("Preparing verify checkpoint");
-    const checkpoint = await ensureVerifyCheckpoint(cwd, profile, sandboxSettings);
+    // Sandbox "off" → run the recipe directly on the host; do NOT bootstrap a
+    // `shuru` checkpoint. ensureVerifyCheckpoint spawns `shuru checkpoint …`
+    // whenever the recipe has installCommands, regardless of mode — on a host
+    // without shuru installed that throws "Executable not found in $PATH: shuru",
+    // which parseVerifyResult maps to ERROR (never PASS), pinning the sprint score
+    // at 0.00. Skip it when the sole source of truth (getCurrentSandboxMode) is off.
+    const checkpoint = getCurrentSandboxMode() === "off"
+        ? { created: false }
+        : await (async () => {
+            options.onProgress?.("Preparing verify checkpoint");
+            return ensureVerifyCheckpoint(cwd, profile, sandboxSettings);
+        })();
+    if (getCurrentSandboxMode() === "off") {
+        options.onProgress?.("Sandbox off — running verify on host (no shuru checkpoint)");
+    }
     if (checkpoint.checkpointName) {
         sandboxSettings.from = checkpoint.checkpointName;
         if (checkpoint.guestWorkdir) {
@@ -57,7 +71,10 @@ export async function prepareVerifyRun(agent, options = {}) {
     const taskRequest = {
         agent: "verify",
         description: "Run local verification",
-        prompt: buildVerifyTaskPrompt(cwd, sandboxSettings, profile.recipe),
+        // Thread the resolved mode so the prompt tells the sub-agent to run "on the
+        // host" instead of "inside the active Shuru sandbox" when sandbox is off
+        // (the param defaults to "shuru", which was wrong for an off host).
+        prompt: buildVerifyTaskPrompt(cwd, sandboxSettings, profile.recipe, getCurrentSandboxMode()),
     };
     return {
         profile,