@aitne/daemon 0.1.8 → 0.1.10

package/dist/core/backends/claude-tool-collection.js

@@ -45,6 +45,70 @@ import { isPathInsideOrEqual, shellPathForms } from "../path-compat.js";
  * `bashContextWriteHook` to defeat symlink-based bypasses that point
  * back into the context dir.
  */
+/**
+ * Slice the curl-relevant portion out of a pre-stripped scan string.
+ *
+ * Production hooks (2026-05) were flagging `curl … | head -c 2000` and
+ * `curl … | python3 -c '…'` as `curl --cookie-jar/-c not allowed`, because
+ * the short-flag regex `-[a-zA-Z]*c(?:\s|=|$)` was matching `-c` from a
+ * pipeline tail command rather than from curl's arg list. The
+ * chained-curl check earlier in `bashCurlHook` already guarantees at most
+ * one `curl` token per Bash invocation, so the curl segment is just the
+ * substring from the first `curl` token up to the next shell separator
+ * (`|`, `;`, `&&`, `||`, newline, end of string). Scoping short-flag
+ * presence checks to that segment eliminates the false positive while
+ * preserving the existing protections against the real curl flags.
+ *
+ * Caller invariant: `scan` is the output of `stripBashStringContent` so
+ * the separators we slice on are unquoted shell separators, not literal
+ * text inside a JSON body.
+ */
+function extractCurlSegment(scan) {
+    const curlIdx = scan.search(/\bcurl\b/);
+    if (curlIdx === -1)
+        return "";
+    const tail = scan.slice(curlIdx);
+    // Stop at the first unquoted pipe / semicolon / newline / `&&` / `||`.
+    // `& ` and `&\n` end the curl invocation too (backgrounding); but a bare
+    // `&` inside an unquoted shell context is rare and chained-curl already
+    // catches the case where a second curl follows it.
+    const stopMatch = tail.match(/[|;\n]|&&|\|\|/);
+    return stopMatch && stopMatch.index !== undefined
+        ? tail.slice(0, stopMatch.index)
+        : tail;
+}
+/**
+ * Collect the top-level (argv, not body) http(s) URL tokens from a
+ * heredoc-stripped command. A token counts as a target URL when it is a
+ * bare `http(s)://…` token OR a token whose ENTIRE content between matching
+ * quotes is such a URL. URLs that appear inside a larger quoted token
+ * (a JSON `-d` body, an `-H` header value) are intentionally not counted —
+ * the surrounding token carries non-URL characters, so neither pattern
+ * matches.
+ *
+ * Caller invariant: `tokenizable` is the output of `stripBashHeredocs` over
+ * the line-continuation-joined command, so heredoc bodies (stdin payload,
+ * never argv) and continuation-line smuggling cannot contribute a token. The
+ * curl hook's multi-URL block check is the sole caller; the single-pure-curl
+ * allow gate reuses its `topLevelUrls` result rather than recomputing.
+ */
+function collectTopLevelHttpUrls(tokenizable) {
+    const tokenRe = /'[^']*'|"[^"]*"|[^'"\s]+/g;
+    const urls = [];
+    let tokenMatch;
+    while ((tokenMatch = tokenRe.exec(tokenizable)) !== null) {
+        const token = tokenMatch[0];
+        if (/^https?:\/\//.test(token)) {
+            urls.push(token);
+            continue;
+        }
+        const quoted = /^(['"])(https?:\/\/[^'"\s]+)\1$/.exec(token);
+        if (quoted) {
+            urls.push(quoted[2]);
+        }
+    }
+    return urls;
+}
 function realpathLenient(absPath) {
     const segments = [];
     let current = absPath;
@@ -365,6 +429,29 @@ export function buildSecurityHooks(deps, allowMode = false) {
     const bashCurlHook = async (input) => {
         const toolInput = input.tool_input;
         const cmd = toolInput?.command ?? "";
+        // Collapse shell line-continuations (`\<NL>`) into a single logical line
+        // BEFORE deriving any analysis view. Two reasons, both load-bearing:
+        //
+        //   1. Faithful firewall. `stripBashHeredocs` greedily erases from the
+        //      FIRST newline through the heredoc's closing delimiter. On a
+        //      multi-line `curl … \<NL> -o /etc/passwd <<'D' … D` the dangerous
+        //      flag sits on a continuation line ahead of the heredoc and would
+        //      vanish from `scan` / `curlScan` / `tokenizable` — so the `-o` /
+        //      `--proxy` / `-d @file` / multi-URL checks below would all skip it.
+        //      Joining first puts every flag back on the curl line where the
+        //      scanners see it. (Latent pre-join hole; only masked because the
+        //      SDK denied multi-line heredoc curls outright. The allow gate at
+        //      the foot of this block now grants those, so the firewall MUST see
+        //      the real command.)
+        //   2. Enables the high-value retry fix. The multi-KB `today.md` PUT /
+        //      `schedule/batch` POST bodies the agent writes use exactly the
+        //      continued-then-heredoc shape; joining lets a clean one reach the
+        //      allow gate instead of being refused.
+        //
+        // `\<NL>` → space: the shell deletes it outright, but a space only ever
+        // SPLITS tokens, which is strictly safer for substring/token scanners —
+        // it can never merge a hidden metacharacter or URL away.
+        const joinedCmd = cmd.replace(/\\\r?\n/g, " ");
         // Three views of the command, each used by a different class of check:
         //
         // - `cmd` (raw)         — the initial `\bcurl\b` keyword presence test.
@@ -391,8 +478,21 @@ export function buildSecurityHooks(deps, allowMode = false) {
         // routinely contains the source URL ("Source: https://news.example.com/…").
         // Before this layered design the URL extractor scanned `cmd`, found
         // the body URL, and falsely blocked with "Multiple URL targets".
-        const scan = stripBashStringContent(cmd);
-        const tokenizable = stripBashHeredocs(cmd);
+        const scan = stripBashStringContent(joinedCmd);
+        const tokenizable = stripBashHeredocs(joinedCmd);
+        // Scope short-flag presence checks (`-c`, `-w`, `-D`, `-x`, `-L`,
+        // `-T`, …) to just the curl invocation. Without this scoping, pipeline
+        // tail commands that share a short-flag letter with curl trip false
+        // positives — e.g. `curl ... | head -c 2000` (head's `-c N` byte
+        // limit) was getting blocked as "curl --cookie-jar/-c not allowed",
+        // and `curl ... | python3 -c '...'` was also wrong-tripping the
+        // cookie-jar guard. The chained-curl check above guarantees there's
+        // at most one curl invocation, so the curl segment is simply
+        // everything from the `curl` token up to the next shell separator
+        // (`|`, `;`, `&&`, `||`, newline). Full-name flags
+        // (`--cookie-jar`, `--write-out`, …) keep using `scan` because their
+        // names don't collide with anything outside curl.
+        const curlScan = extractCurlSegment(scan);
         if (/\bcurl\b/.test(cmd)) {
             // ── Multi-request defenses (run BEFORE host/port loop) ─────────
             // The SDK `allowedTools` glob is a prefix match against the full
@@ -454,24 +554,7 @@ export function buildSecurityHooks(deps, allowMode = false) {
             //    shell argv — without that strip, the routine wiki.ingest_url
             //    shape of "store an article body that mentions other URLs"
             //    would trip this multi-URL rule on the body URL.
-            const topLevelTokenRe = /'[^']*'|"[^"]*"|[^'"\s]+/g;
-            const topLevelUrls = [];
-            let tokenMatch;
-            while ((tokenMatch = topLevelTokenRe.exec(tokenizable)) !== null) {
-                const token = tokenMatch[0];
-                if (/^https?:\/\//.test(token)) {
-                    topLevelUrls.push(token);
-                    continue;
-                }
-                // Fully-quoted URL token: the WHOLE content between matching
-                // single or double quotes must be the URL — anything else
-                // (JSON body, header value) starts with non-URL characters
-                // after the quote.
-                const quoted = /^(['"])(https?:\/\/[^'"\s]+)\1$/.exec(token);
-                if (quoted) {
-                    topLevelUrls.push(quoted[2]);
-                }
-            }
+            const topLevelUrls = collectTopLevelHttpUrls(tokenizable);
             if (topLevelUrls.length > 1) {
                 return {
                     decision: "block",
@@ -543,7 +626,7 @@ export function buildSecurityHooks(deps, allowMode = false) {
             // `-L`. Same shape applied to every short-flag below — without it
             // an attacker can stuff the dangerous letter into a benign-looking
             // flag bundle like `-fs<X>` and bypass the deny rule entirely.
-            if (/(?:^|\s)(?:--upload-file\b|-[a-zA-Z]*T(?:\s|=|$))/.test(scan)) {
+            if (/(?:^|\s)(?:--upload-file\b|-[a-zA-Z]*T(?:\s|=|$))/.test(curlScan)) {
                 return {
                     decision: "block",
                     reason: "curl --upload-file / -T not allowed — would read arbitrary files",
@@ -667,7 +750,7 @@ export function buildSecurityHooks(deps, allowMode = false) {
             // earlier heredoc-body occurrence of `-o /etc/passwd` cannot be
             // captured ahead of the real flag — while quoted paths like
             // `-o "my file.pdf"` are still readable.
-            const hasOutputFlag = /(?:^|\s)(?:--output(?:\b|=)|-[a-zA-Z]*o(?:\s|=|$))/.test(scan);
+            const hasOutputFlag = /(?:^|\s)(?:--output(?:\b|=)|-[a-zA-Z]*o(?:\s|=|$))/.test(curlScan);
             if (hasOutputFlag) {
                 // Three capture-group alternatives so quoted paths with spaces
                 // are caught — `[^\s'"]+` alone fails on `"my file"`.
@@ -688,19 +771,19 @@ export function buildSecurityHooks(deps, allowMode = false) {
                     };
                 }
             }
-            if (/(?:^|\s)(?:--remote-name(?:-all)?\b|-[a-zA-Z]*O(?:\s|=|$))/.test(scan)) {
+            if (/(?:^|\s)(?:--remote-name(?:-all)?\b|-[a-zA-Z]*O(?:\s|=|$))/.test(curlScan)) {
                 return {
                     decision: "block",
                     reason: "curl --remote-name/-O not allowed — would write to URL-derived path",
                 };
             }
-            if (/(?:^|\s)(?:--dump-header\b|-[a-zA-Z]*D(?:\s|=|$))/.test(scan)) {
+            if (/(?:^|\s)(?:--dump-header\b|-[a-zA-Z]*D(?:\s|=|$))/.test(curlScan)) {
                 return {
                     decision: "block",
                     reason: "curl --dump-header/-D not allowed — writes response headers to disk",
                 };
             }
-            if (/(?:^|\s)(?:--cookie-jar\b|-[a-zA-Z]*c(?:\s|=|$))/.test(scan)) {
+            if (/(?:^|\s)(?:--cookie-jar\b|-[a-zA-Z]*c(?:\s|=|$))/.test(curlScan)) {
                 return {
                     decision: "block",
                     reason: "curl --cookie-jar/-c not allowed — writes cookie state to disk",
@@ -713,20 +796,20 @@ export function buildSecurityHooks(deps, allowMode = false) {
             // `-b name=value` would require parsing the value; the simpler
             // safe stance is to refuse the flag outright since the daemon
             // API uses bearer tokens, not cookies.
-            if (/(?:^|\s)(?:--cookie\b|-[a-zA-Z]*b(?:\s|=|$))/.test(scan)) {
+            if (/(?:^|\s)(?:--cookie\b|-[a-zA-Z]*b(?:\s|=|$))/.test(curlScan)) {
                 return {
                     decision: "block",
                     reason: "curl --cookie/-b not allowed — when the value is a path, " +
                         "the file contents are sent as the Cookie header (file read).",
                 };
             }
-            if (/(?:^|\s)--trace(?:-ascii)?\b/.test(scan)) {
+            if (/(?:^|\s)--trace(?:-ascii)?\b/.test(curlScan)) {
                 return {
                     decision: "block",
                     reason: "curl --trace / --trace-ascii not allowed — writes protocol trace to disk",
                 };
             }
-            if (/(?:^|\s)(?:--write-out\b|-[a-zA-Z]*w(?:\s|=|$))/.test(scan)) {
+            if (/(?:^|\s)(?:--write-out\b|-[a-zA-Z]*w(?:\s|=|$))/.test(curlScan)) {
                 return {
                     decision: "block",
                     reason: "curl --write-out/-w not allowed — format strings include file/stderr sinks",
@@ -735,7 +818,7 @@ export function buildSecurityHooks(deps, allowMode = false) {
             // Cert / key file references. The daemon API is plain HTTP on
             // loopback; none of these flags are needed for legitimate
             // operation and they all read arbitrary files from disk.
-            if (/(?:^|\s)(?:--cert\b|--key\b|--cacert\b|--capath\b|-[a-zA-Z]*E(?:\s|=|$))/.test(scan)) {
+            if (/(?:^|\s)(?:--cert\b|--key\b|--cacert\b|--capath\b|-[a-zA-Z]*E(?:\s|=|$))/.test(curlScan)) {
                 return {
                     decision: "block",
                     reason: "curl --cert/--key/--cacert/--capath/-E not allowed — read arbitrary files",
@@ -748,12 +831,75 @@ export function buildSecurityHooks(deps, allowMode = false) {
             // Combined-short-flag forms (`-fsSL`, `-vL`) are caught by the
             // `[a-zA-Z]*L` alternation; the literal `--location` and
             // `--location-trusted` long forms are matched explicitly.
-            if (/(?:^|\s)(?:-[a-zA-Z]*L(?:\s|=|$)|--location(?:-trusted)?\b)/.test(scan)) {
+            if (/(?:^|\s)(?:-[a-zA-Z]*L(?:\s|=|$)|--location(?:-trusted)?\b)/.test(curlScan)) {
                 return {
                     decision: "block",
                     reason: "curl -L / --location not allowed — would follow redirects off localhost",
                 };
             }
+            // ── All curl firewall checks passed → grant permission explicitly. ──
+            //
+            // Why this is necessary (not just `{ continue: true }`): the SDK's
+            // `permissionMode: "dontAsk"` falls back to `allowedTools` prefix
+            // matching, and `Bash(curl *)` does NOT match a heredoc-bodied curl
+            // (`curl … -d @- <<'JSON' … JSON`) — the SDK command parser treats the
+            // heredoc redirect as un-prefixable and silently denies it. That shape
+            // is the DOCUMENTED way to send multi-KB context / observation bodies
+            // (agent-assets/skills/context/references/api.md; the curl shim's
+            // `-d @-` stdin path in daemon-api-cli.ts). The mismatch denied ~98%
+            // of heredoc curls in production, triggering multi-turn inline-retry
+            // storms and partial routine runs (fetch_window calendar posts, today
+            // PATCHes, observation batches). Returning `{ continue: true }` here
+            // means the carefully-built curl firewall above validates the command
+            // but then defers the verdict to a matcher that rejects the very shape
+            // the system tells the agent to use. This hook IS the curl authority
+            // (loopback-only host/port, single request, no file read/write, no
+            // connection override, no redirect-follow), so it grants permission.
+            //
+            // SAFETY — only a SINGLE, PURE curl is granted. The firewall above
+            // validates the curl invocation's flags/target, but does NOT bound a
+            // *second* command (`curl localhost/api/x && rm -rf ~`), a shell
+            // redirect (`curl localhost/api/x > /etc/passwd`), a pipe-to-shell
+            // (`curl … | sh`), or a command/variable expansion
+            // (`curl … -H "X: $(whoami)"`, `… $TOKEN`). The three checks below cap
+            // the grant to a lone curl; anything else falls through to
+            // `{ continue: true }` and stays under allowedTools + the absolute-block
+            // hook + the authoritative `disallowedTools` deny rules exactly as
+            // today. The `<<` heredoc is the one permitted redirect — its body is
+            // stdin payload, never argv, and is already validated above.
+            //
+            // All three views (`scan`, `curlScan`, `topLevelUrls`) are derived from
+            // the line-continuation-JOINED command (see the join at the top of this
+            // hook), so a metacharacter / flag / second URL smuggled onto a
+            // continuation line ahead of the heredoc cannot hide from these checks.
+            const heredocCarved = scan.replace(/<<-?\s*(?:'[^']*'|"[^"]*"|\w+)/g, " ");
+            // `scan` (single-quoted strings + heredoc bodies collapsed, heredoc op
+            // carved out) must carry no shell control character: `| ; & \` < > $`
+            // cover pipes, sequencing, background / and-lists, command substitution
+            // (backtick / `$(`), redirects, and variable / command expansion (`$`).
+            const hasShellMeta = /[|;&`<>$]/.test(heredocCarved);
+            // No command may trail the curl segment — `extractCurlSegment` stops at
+            // the first unquoted `| ; newline && ||`, so anything non-blank after it
+            // (e.g. a command on the line following a heredoc's closing delimiter)
+            // means the invocation is not a lone curl.
+            const curlStart = scan.search(/\bcurl\b/);
+            const trailing = scan.slice(curlStart + curlScan.length).trim();
+            // `topLevelUrls.length === 1` and every URL being localhost:apiPort are
+            // already guaranteed by the block returns above (length 0 / >1 and any
+            // non-localhost target each `block`); re-asserting the count keeps the
+            // grant condition self-evident at the call site.
+            const isSinglePureCurl = topLevelUrls.length === 1 && !hasShellMeta && trailing.length === 0;
+            if (isSinglePureCurl) {
+                return {
+                    hookSpecificOutput: {
+                        hookEventName: "PreToolUse",
+                        permissionDecision: "allow",
+                        permissionDecisionReason: "Single loopback daemon-API curl validated by bashCurlHook "
+                            + "(localhost host/port, one request, no file I/O, redirect, "
+                            + "or shell expansion).",
+                    },
+                };
+            }
         }
         return { continue: true };
     };
@@ -1090,4 +1236,3 @@ export function buildSecurityHooks(deps, allowMode = false) {
         ],
     };
 }
-//# sourceMappingURL=claude-tool-collection.js.map

package/dist/core/backends/cli-quota-guards.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Shared per-turn budget enforcement and failure classification for the CLI
+ * backends (`CodexCore`, `GeminiCliCore`).
+ *
+ * Both CLI backends surface the same two failover signals the dispatcher
+ * relies on — `BackendQuotaError` (retry/failover on a different window or
+ * backend) and `BackendDecisiveFailure` (auth / timeout / policy / other).
+ * The budget asserts and the failure-classification skeleton were previously
+ * duplicated byte-for-byte across the two cores, so a single bug fix to
+ * quota/cost handling had to be applied in both places with real drift risk.
+ * This module is the single source of truth for the CLI backends. Backend-
+ * specific bits (the rate-limit / auth regexes, the human-readable backend
+ * label, Gemini's policy-deny branch) stay with each core and are passed in.
+ *
+ * Deliberately NOT shared with the SDK backends — this mirrors the existing
+ * Claude/CLI error-handling split (see the `quota-reset-hints.ts` header):
+ *  - `OpenCodeCore` raises `BackendDecisiveFailure("model_unavailable")` with
+ *    a different estimation model.
+ *  - `ClaudeCodeCore` classifies `unknown` SDK errors via `instanceof` and
+ *    keeps its own budget-message detector `isClaudeCodeMaxBudgetError`
+ *    (`claude-errors.ts`) — a deliberate parallel to `isMaxBudgetMessage`
+ *    here, tuned to the Anthropic SDK's structured `{message, code, type}`
+ *    errors rather than raw CLI subprocess text. They share the same budget
+ *    regex today: a maintainer changing what counts as a budget-rejection
+ *    message must update BOTH detectors.
+ * Forcing those shapes through this module would be over-abstraction.
+ */
+import type { BackendId } from "@aitne/shared";
+import { BackendDecisiveFailure, BackendQuotaError, type BackendQuotaSpend } from "../agent-core.js";
+import type { PriceFetcher } from "./price-fetcher.js";
+/**
+ * True when a failure message looks like our own per-turn budget rejection
+ * (see `assertCostWithinMaxBudget`). Lets `classifyCliFailure` re-tag a budget
+ * message as `max_budget_usd` instead of mis-routing it into the generic
+ * rate-limit branch.
+ */
+export declare function isMaxBudgetMessage(message: string): boolean;
+/**
+ * Post-completion per-turn budget enforcement. Both Codex and Gemini meter
+ * `max_budget_usd` post-hoc — by the time we reject here the provider has
+ * already consumed tokens — so the just-completed turn's `spend` is attached
+ * to the `BackendQuotaError` so the dispatcher's error path can write a
+ * `result='failed'` agent_actions row with `cost_usd` / `numTurns` /
+ * `durationMs` populated. Without it, budget-rejected runs silently drop their
+ * spend on the success-only audit path. See `BackendQuotaSpend`.
+ */
+export declare function assertCostWithinMaxBudget(params: {
+    backendId: BackendId;
+    /** Human-readable backend name for the rejection message, e.g. "Codex". */
+    label: string;
+    costUsd: number;
+    maxBudgetUsd: number | undefined;
+    modelId: string;
+    spend?: Omit<BackendQuotaSpend, "modelId" | "costUsd">;
+}): void;
+/**
+ * Pre-flight per-turn budget guard. Estimates the prompt's input-token cost
+ * via the shared price fetcher and rejects before spawning the subprocess when
+ * even the prompt alone would exceed `max_budget_usd`.
+ */
+export declare function assertPromptCostWithinMaxBudget(params: {
+    backendId: BackendId;
+    label: string;
+    prompt: string;
+    maxBudgetUsd: number | undefined;
+    modelId: string;
+    priceFetcher: PriceFetcher;
+}): void;
+/**
+ * Optional pre-auth classifier — given a failure `message`, returns a
+ * `BackendDecisiveFailure` when it owns the message, else `null` to fall
+ * through to the shared auth/timeout/fallback branches. Runs BEFORE the auth
+ * branch so backend-specific messages (e.g. Gemini policy-deny wraps that
+ * contain "login"/"required") don't mis-tag as auth.
+ */
+export type CliFailureExtraClassifier = (message: string, backendId: BackendId) => BackendDecisiveFailure | null;
+/**
+ * Shared failure-classification skeleton for the CLI backends. Maps a raw
+ * failure `message` to the dispatcher's failover signals in a fixed order:
+ *
+ *   1. our own budget rejection                → BackendQuotaError("max_budget_usd")
+ *   2. rate-limit / quota (per-backend regex)  → BackendQuotaError("rate_limited")
+ *      with a best-effort reset-time hint for the dashboard
+ *   3. optional pre-auth `extraClassifier` (e.g. Gemini policy-deny) — runs
+ *      BEFORE auth so deny messages containing "login"/"required" don't
+ *      mis-tag as auth and trigger an auth-recovery flow
+ *   4. auth (per-backend regex)                → BackendDecisiveFailure("auth")
+ *   5. timeout                                 → BackendDecisiveFailure("timeout")
+ *   6. anything else                           → BackendDecisiveFailure("other_non_retryable")
+ *
+ * The rate-limit and auth regexes differ per backend (OpenAI vs Google
+ * wording), so each core passes its own.
+ */
+export declare function classifyCliFailure(params: {
+    backendId: BackendId;
+    message: string;
+    rateLimitPattern: RegExp;
+    authPattern: RegExp;
+    extraClassifier?: CliFailureExtraClassifier;
+}): BackendQuotaError | BackendDecisiveFailure;

package/dist/core/backends/cli-quota-guards.js

@@ -0,0 +1,95 @@
+import { BackendDecisiveFailure, BackendQuotaError, } from "../agent-core.js";
+import { extractGenericQuotaResetHint } from "./quota-reset-hints.js";
+import { estimateTextInputTokens, findRegisteredModel, } from "./model-registry.js";
+/**
+ * True when a failure message looks like our own per-turn budget rejection
+ * (see `assertCostWithinMaxBudget`). Lets `classifyCliFailure` re-tag a budget
+ * message as `max_budget_usd` instead of mis-routing it into the generic
+ * rate-limit branch.
+ */
+export function isMaxBudgetMessage(message) {
+    return /max(?:imum)? budget|max_budget_usd|budget limit|per-turn budget/i.test(message);
+}
+/**
+ * Post-completion per-turn budget enforcement. Both Codex and Gemini meter
+ * `max_budget_usd` post-hoc — by the time we reject here the provider has
+ * already consumed tokens — so the just-completed turn's `spend` is attached
+ * to the `BackendQuotaError` so the dispatcher's error path can write a
+ * `result='failed'` agent_actions row with `cost_usd` / `numTurns` /
+ * `durationMs` populated. Without it, budget-rejected runs silently drop their
+ * spend on the success-only audit path. See `BackendQuotaSpend`.
+ */
+export function assertCostWithinMaxBudget(params) {
+    const { backendId, label, costUsd, maxBudgetUsd, modelId, spend } = params;
+    if (maxBudgetUsd === undefined || costUsd <= maxBudgetUsd) {
+        return;
+    }
+    throw new BackendQuotaError(backendId, "max_budget_usd", null, `${label} estimated cost $${costUsd.toFixed(4)} exceeded the per-turn budget limit $${maxBudgetUsd.toFixed(2)} for ${modelId}.`, spend ? { ...spend, modelId, costUsd } : null);
+}
+/**
+ * Pre-flight per-turn budget guard. Estimates the prompt's input-token cost
+ * via the shared price fetcher and rejects before spawning the subprocess when
+ * even the prompt alone would exceed `max_budget_usd`.
+ */
+export function assertPromptCostWithinMaxBudget(params) {
+    const { backendId, label, prompt, maxBudgetUsd, modelId, priceFetcher } = params;
+    if (maxBudgetUsd === undefined) {
+        return;
+    }
+    const estimatedUsage = {
+        inputTokens: estimateTextInputTokens(prompt),
+        outputTokens: 0,
+        cacheCreationInputTokens: 0,
+        cacheReadInputTokens: 0,
+    };
+    const { costUsd } = priceFetcher.estimateUsageCost({
+        backendId,
+        modelId,
+        usage: estimatedUsage,
+        fallbackModel: findRegisteredModel(backendId, modelId),
+    });
+    if (costUsd <= maxBudgetUsd) {
+        return;
+    }
+    throw new BackendQuotaError(backendId, "max_budget_usd", null, `${label} estimated prompt cost $${costUsd.toFixed(4)} exceeded the per-turn budget limit $${maxBudgetUsd.toFixed(2)} for ${modelId}.`);
+}
+/**
+ * Shared failure-classification skeleton for the CLI backends. Maps a raw
+ * failure `message` to the dispatcher's failover signals in a fixed order:
+ *
+ *   1. our own budget rejection                → BackendQuotaError("max_budget_usd")
+ *   2. rate-limit / quota (per-backend regex)  → BackendQuotaError("rate_limited")
+ *      with a best-effort reset-time hint for the dashboard
+ *   3. optional pre-auth `extraClassifier` (e.g. Gemini policy-deny) — runs
+ *      BEFORE auth so deny messages containing "login"/"required" don't
+ *      mis-tag as auth and trigger an auth-recovery flow
+ *   4. auth (per-backend regex)                → BackendDecisiveFailure("auth")
+ *   5. timeout                                 → BackendDecisiveFailure("timeout")
+ *   6. anything else                           → BackendDecisiveFailure("other_non_retryable")
+ *
+ * The rate-limit and auth regexes differ per backend (OpenAI vs Google
+ * wording), so each core passes its own.
+ */
+export function classifyCliFailure(params) {
+    const { backendId, message, rateLimitPattern, authPattern, extraClassifier } = params;
+    if (isMaxBudgetMessage(message)) {
+        return new BackendQuotaError(backendId, "max_budget_usd", null, message);
+    }
+    if (rateLimitPattern.test(message)) {
+        // Best-effort reset-time extraction so the dashboard can surface
+        // "quota resets at HH:MM (TZ)" instead of a bare "rate_limited" tag.
+        // Falls through to null when no reset-time pattern matches.
+        return new BackendQuotaError(backendId, "rate_limited", extractGenericQuotaResetHint(message), message);
+    }
+    const extra = extraClassifier?.(message, backendId);
+    if (extra) {
+        return extra;
+    }
+    if (authPattern.test(message)) {
+        return new BackendDecisiveFailure(backendId, "auth", new Error(message));
+    }
+    if (/timed out|timeout/i.test(message)) {
+        return new BackendDecisiveFailure(backendId, "timeout", new Error(message));
+    }
+    return new BackendDecisiveFailure(backendId, "other_non_retryable", new Error(message));
+}

package/dist/core/backends/cli-utils.d.ts

@@ -37,7 +37,6 @@ export declare function runLineCommand(options: CommandRunOptions): Promise<Comm
  * but if the child catches and ignores SIGTERM, escalate to SIGKILL after
  * `gracePeriodMs` so the parent's `child.once("close")` listener actually
  * fires. Same hang motivation as {@link killTree}'s SIGKILL escalation
- * (see file-history note for the 2026-04-29 18m delegated_proxy.invoke).
  *
  * Note on `subprocess.killed` semantics: Node sets `killed=true` as soon
  * as `child.kill()` *sends* a signal — even if the child ignores it. So
@@ -50,6 +49,32 @@ export declare function killChildWithEscalation(child: ChildProcess, options?: {
     gracePeriodMs?: number;
 }): void;
 export declare function findExecutable(command: string): string | null;
+/**
+ * Build the `cmd.exe` argv that launches a `.cmd`/`.bat` shim with the given
+ * arguments, fully escaped against cmd.exe re-parsing. Pure (no filesystem),
+ * exported for unit testing of the escaping. Pair with
+ * `windowsVerbatimArguments: true` so Node passes the line verbatim.
+ */
+export declare function buildCmdShimArgs(shimPath: string, args: string[]): string[];
+export interface Win32Invocation {
+    command: string;
+    args: string[];
+    windowsVerbatimArguments: boolean;
+}
+/**
+ * Windows-only spawn rewrite for {@link runLineCommand}. Returns the
+ * substitute `{ command, args, windowsVerbatimArguments }`, or `null` when no
+ * rewrite is needed (so the caller spawns the original command unchanged, and
+ * an unresolvable bare name still ENOENTs naturally as before).
+ *
+ * - Bare name → resolved to its absolute path via PATHEXT (`findExecutable`).
+ * - Resolved `.cmd`/`.bat` → launched through a hand-escaped
+ *   `cmd.exe /d /s /c` wrapper (verbatim args).
+ * - Resolved `.exe`/`.com`/extensionless → spawned directly (`shell:false` is
+ *   safe for these); the only change vs. today is bare-name → absolute
+ *   resolution, which also closes the bare-name PATHEXT ENOENT.
+ */
+export declare function resolveWin32Invocation(command: string, args: string[]): Win32Invocation | null;
 /**
  * Lazy CLI path resolver with TTL-based revalidation (roadmap §9.4).
  *
@@ -92,4 +117,3 @@ export declare function removeFileIfExists(path: string): void;
  * format-only, so the dashboard doesn't misrepresent it as verified.
  */
 export declare function isPlausibleAnthropicApiKey(raw: string | undefined): boolean;
-//# sourceMappingURL=cli-utils.d.ts.map