@martinloop/mcp 0.3.3 → 0.3.4

package/dist/tools/eval.js

@@ -15,15 +15,20 @@ export async function martinEvalTool(input) {
         verifiers: detail.loop.task?.verificationPlan ?? [],
         signals
     });
+    const observationMismatch = hasObservationMismatch(detail.loop.events ?? []);
     const checks = {
         taskCompletion: detail.loop.status === "completed" ? "passed" : detail.loop.status === "exited" ? "warning" : "failed",
         verifier: verification.status === "passed"
             ? "passed"
-            : verification.status === "failed"
+            : verification.status === "failed" || verification.status === "contradicted"
                 ? "failed"
                 : "warning",
-        diffDiscipline: (detail.loop.task?.allowedPaths?.length ?? 0) > 0 ? "passed" : "warning",
-        regressionRisk: verification.status === "passed" ? "passed" : "warning",
+        diffDiscipline: observationMismatch
+            ? "failed"
+            : (detail.loop.task?.allowedPaths?.length ?? 0) > 0
+                ? "passed"
+                : "warning",
+        regressionRisk: verification.status === "passed" && !observationMismatch ? "passed" : "warning",
         securityRisk: risk.level === "high" ? "failed" : risk.level === "medium" ? "warning" : "passed",
         reviewability: detail.loop.attempts.length > 0 && (detail.loop.events?.length ?? 0) > 0 ? "passed" : "warning"
     };
@@ -35,7 +40,7 @@ export async function martinEvalTool(input) {
     score -= checks.securityRisk === "failed" ? 20 : checks.securityRisk === "warning" ? 10 : 0;
     score -= checks.reviewability === "warning" ? 8 : 0;
     score = Math.max(0, score);
-    const grade = verification.status === "unavailable"
+    const grade = verification.status === "not_run" || observationMismatch
         ? "insufficient_evidence"
         : score >= 90
             ? "mergeable"
@@ -44,7 +49,14 @@ export async function martinEvalTool(input) {
                 : score >= 55
                     ? "needs_review"
                     : "blocked";
-    const warnings = [...detail.warnings, ...verification.warnings, ...risk.reasons];
+    const warnings = [
+        ...detail.warnings,
+        ...verification.warnings,
+        ...risk.reasons,
+        ...(observationMismatch
+            ? ["Change observation mismatch: adapter-reported files differ from repo-observed files."]
+            : [])
+    ];
     return {
         source: detail.source,
         sourceKind: detail.sourceKind,
@@ -64,3 +76,15 @@ export async function martinEvalTool(input) {
                         : `Run ${detail.loop.loopId} is blocked from promotion by verification or risk gaps.`
     };
 }
+function hasObservationMismatch(events) {
+    return events.some((event) => {
+        if (event.type !== "observation.reconciled") {
+            return false;
+        }
+        const observation = isRecord(event.payload?.["observation"]) ? event.payload?.["observation"] : undefined;
+        return observation?.["status"] === "mismatch";
+    });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}

package/dist/tools/execution-policy.d.ts

@@ -0,0 +1,11 @@
+import { type ExecutionPolicy } from "../vendor/contracts/index.js";
+export interface CompileMcpExecutionPolicyInput {
+    workingDirectory: string;
+    maxUsd?: number;
+    maxIterations?: number;
+    maxTokens?: number;
+    verificationPlan?: string[];
+    allowedPaths?: string[];
+    deniedPaths?: string[];
+}
+export declare function compileMcpExecutionPolicy(input: CompileMcpExecutionPolicyInput): ExecutionPolicy;

package/dist/tools/execution-policy.js

@@ -0,0 +1,47 @@
+import { DEFAULT_BUDGET } from "../vendor/contracts/index.js";
+import { compileExecutionPolicy } from "../vendor/core/index.js";
+export function compileMcpExecutionPolicy(input) {
+    const normalizedBudget = {
+        maxUsd: input.maxUsd ?? DEFAULT_BUDGET.maxUsd,
+        softLimitUsd: Math.min(DEFAULT_BUDGET.softLimitUsd, input.maxUsd ?? DEFAULT_BUDGET.maxUsd),
+        maxIterations: input.maxIterations ?? DEFAULT_BUDGET.maxIterations,
+        maxTokens: input.maxTokens ?? DEFAULT_BUDGET.maxTokens
+    };
+    const policy = compileExecutionPolicy({
+        configPath: "mcp://inline",
+        defaults: {
+            budget: DEFAULT_BUDGET,
+            policyProfile: "balanced",
+            telemetryDestination: "local-only",
+            destructiveActionPolicy: "approval",
+            verifierRules: []
+        },
+        request: {
+            budget: normalizedBudget,
+            budgetOverrides: {
+                ...(input.maxUsd !== undefined ? { maxUsd: true } : {}),
+                ...(input.maxIterations !== undefined ? { maxIterations: true } : {}),
+                ...(input.maxTokens !== undefined ? { maxTokens: true } : {})
+            },
+            verificationPlan: input.verificationPlan,
+            repoRoot: input.workingDirectory,
+            allowedPaths: input.allowedPaths,
+            deniedPaths: input.deniedPaths
+        }
+    });
+    const softLimitSource = input.maxUsd !== undefined && normalizedBudget.softLimitUsd !== DEFAULT_BUDGET.softLimitUsd
+        ? "request"
+        : "default";
+    return {
+        ...policy,
+        budget: normalizedBudget,
+        provenance: [
+            ...policy.provenance.filter((entry) => entry.field !== "budget.softLimitUsd"),
+            {
+                field: "budget.softLimitUsd",
+                source: softLimitSource,
+                value: String(normalizedBudget.softLimitUsd)
+            }
+        ]
+    };
+}

package/dist/tools/run-dossier.js

@@ -37,12 +37,12 @@ export async function martinRunDossierTool(input) {
         risk,
         outcome: verification.status === "passed"
             ? "passed"
-            : verification.status === "failed"
+            : verification.status === "failed" || verification.status === "contradicted"
                 ? "failed"
                 : "needs_review",
         nextAction: verification.status === "passed"
             ? "Review the dossier and evaluation, then decide whether to merge or promote."
-            : verification.status === "failed"
+            : verification.status === "failed" || verification.status === "contradicted"
                 ? "Investigate the latest verifier failure before retrying or promoting."
                 : "Collect more evidence before claiming completion."
     };

package/dist/tools/run-loop.d.ts

@@ -10,6 +10,7 @@ export interface RunLoopInput {
     maxUsd?: number;
     maxIterations?: number;
     maxTokens?: number;
+    verifyTimeoutMs?: number;
     verificationPlan?: string[];
     allowedPaths?: string[];
     deniedPaths?: string[];

package/dist/tools/run-loop.js

@@ -66,17 +66,27 @@ export async function runLoopTool(input) {
         ? createVerifierOnlyAdapter({
             workingDirectory,
             label: "Proof mode adapter (MARTIN_LIVE=false)",
+            ...(input.verifyTimeoutMs !== undefined ? { verifyTimeoutMs: input.verifyTimeoutMs } : {}),
             ...(proofModeVerifierSpawnImpl ? { spawnImpl: proofModeVerifierSpawnImpl } : {})
         })
         : engine === "codex"
             ? createCodexCliAdapter({
                 workingDirectory,
+                ...(input.verifyTimeoutMs !== undefined ? { verifyTimeoutMs: input.verifyTimeoutMs } : {}),
                 ...(model ? { model } : {}),
                 ...(codexCommandOverride ? { command: codexCommandOverride } : {})
             })
             : engine === "gemini"
-                ? createGeminiCliAdapter({ workingDirectory, ...(model ? { model } : {}) })
-                : createClaudeCliAdapter({ workingDirectory, ...(model ? { model } : {}) });
+                ? createGeminiCliAdapter({
+                    workingDirectory,
+                    ...(input.verifyTimeoutMs !== undefined ? { verifyTimeoutMs: input.verifyTimeoutMs } : {}),
+                    ...(model ? { model } : {})
+                })
+                : createClaudeCliAdapter({
+                    workingDirectory,
+                    ...(input.verifyTimeoutMs !== undefined ? { verifyTimeoutMs: input.verifyTimeoutMs } : {}),
+                    ...(model ? { model } : {})
+                });
     const partialBudget = {};
     if (input.maxUsd !== undefined) {
         partialBudget.maxUsd = input.maxUsd;
@@ -97,6 +107,9 @@ export async function runLoopTool(input) {
             title: input.objective.slice(0, 100),
             objective: input.objective,
             verificationPlan: input.verificationPlan ?? [],
+            ...(input.verifyTimeoutMs !== undefined
+                ? { verificationTimeoutMs: input.verifyTimeoutMs }
+                : {}),
             repoRoot: workingDirectory,
             ...(allowedPaths ? { allowedPaths } : {}),
             ...(deniedPaths ? { deniedPaths } : {})

package/dist/tools/run-store.js

@@ -16,17 +16,17 @@ async function attachReceiptIntegrity(detail) {
             loopRecordPath: detail.canonicalLoopRecordPath,
             ledgerPath
         }).catch(() => ({
-            state: "unsigned",
+            state: "material_missing",
             reason: "Receipt integrity verification could not be completed."
         }))
         : detail.canonicalLoopRecordPath && detail.canonicalRunDirectory
             ? ({
-                state: "unsigned",
+                state: "material_missing",
                 reason: "Receipt integrity material is incomplete for this canonical run."
             })
             : ({
-                state: "unsigned",
-                reason: "Receipt integrity is only available for canonical run directories."
+                state: "selector_noncanonical",
+                reason: "Receipt integrity is only available for canonical run selectors."
             });
     const receiptScope = resolveReceiptScope(detail.loop, detail.runsRoot);
     return {

package/dist/tools/tool-support.d.ts

@@ -61,7 +61,7 @@ export interface ArtifactSummary {
     }>;
 }
 export interface VerificationSummary {
-    status: "passed" | "failed" | "unavailable";
+    status: "passed" | "failed" | "contradicted" | "not_run";
     eventCount: number;
     ledgerEventCount: number;
     latestAttemptIndex?: number;

package/dist/tools/tool-support.js

@@ -31,14 +31,16 @@ export function detectCliAvailability(command) {
             command,
             available: true,
             locator,
-            detail: `${command} is available on PATH.`,
+            detail: isOnPathDirectly(command, resolvedPath)
+                ? `${command} is available on PATH.`
+                : `${command} found at ${resolvedPath} (not on PATH, auto-discovered).`,
             ...(resolvedPath ? { resolvedPath } : {})
         }
         : {
             command,
             available: false,
             locator,
-            detail: `${command} is not available on PATH.`
+            detail: `${command} is not installed. ${suggestInstallCommand(command)}`
         };
     cliAvailabilityCache.set(cacheKey, {
         expiresAt: Date.now() + CLI_CACHE_TTL_MS,
@@ -49,13 +51,6 @@ export function detectCliAvailability(command) {
 function findCommandOnPath(command) {
     const pathKey = Object.keys(process.env).find((key) => key.toLowerCase() === "path");
     const rawPath = pathKey ? process.env[pathKey] : undefined;
-    if (!rawPath) {
-        return undefined;
-    }
-    const pathEntries = rawPath
-        .split(process.platform === "win32" ? ";" : ":")
-        .map((entry) => entry.trim())
-        .filter(Boolean);
     const hasExtension = /\.[A-Za-z0-9]+$/u.test(command);
     const candidateNames = process.platform === "win32" && !hasExtension
         ? (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD")
@@ -64,7 +59,25 @@ function findCommandOnPath(command) {
             .filter(Boolean)
             .map((extension) => `${command}${extension.toLowerCase()}`)
         : [command];
-    for (const directory of pathEntries) {
+    // 1. Search PATH entries
+    if (rawPath) {
+        const pathEntries = rawPath
+            .split(process.platform === "win32" ? ";" : ":")
+            .map((entry) => entry.trim())
+            .filter(Boolean);
+        for (const directory of pathEntries) {
+            for (const candidateName of candidateNames) {
+                const candidatePath = join(directory, candidateName);
+                if (isExecutablePath(candidatePath)) {
+                    return candidatePath;
+                }
+            }
+        }
+    }
+    // 2. Search common install locations when PATH didn't find it.
+    //    This catches CLIs installed via npm/brew/pip that aren't on the
+    //    current shell's PATH (common in IDEs, CI, and agent environments).
+    for (const directory of discoverCommonInstallDirectories(command)) {
         for (const candidateName of candidateNames) {
             const candidatePath = join(directory, candidateName);
             if (isExecutablePath(candidatePath)) {
@@ -74,6 +87,49 @@ function findCommandOnPath(command) {
     }
     return undefined;
 }
+/**
+ * Returns directories where CLI tools are commonly installed but may not
+ * be on PATH. Checked only as a fallback after PATH search fails.
+ */
+function discoverCommonInstallDirectories(command) {
+    const dirs = [];
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    if (process.platform === "win32") {
+        // npm global bin (Roaming)
+        const appData = process.env.APPDATA;
+        if (appData) {
+            dirs.push(join(appData, "npm"));
+        }
+        // Codex desktop install
+        const localAppData = process.env.LOCALAPPDATA;
+        if (localAppData) {
+            dirs.push(join(localAppData, "OpenAI", "Codex", "bin"));
+        }
+        // Scoop
+        if (home) {
+            dirs.push(join(home, "scoop", "shims"));
+        }
+    }
+    else {
+        // Common Unix install paths
+        dirs.push("/usr/local/bin", "/opt/homebrew/bin");
+        if (home) {
+            dirs.push(join(home, ".local", "bin"), // pip, pipx
+            join(home, ".npm-global", "bin"), // npm prefix
+            join(home, ".bun", "bin"), // bun
+            join(home, ".cargo", "bin"), // cargo
+            join(home, "go", "bin") // go install
+            );
+        }
+        // nvm managed node
+        const nvmDir = process.env.NVM_DIR;
+        if (nvmDir) {
+            const nvmBin = join(nvmDir, "current", "bin");
+            dirs.push(nvmBin);
+        }
+    }
+    return dirs.filter(Boolean);
+}
 function isExecutablePath(candidatePath) {
     try {
         accessSync(candidatePath, process.platform === "win32" ? constants.F_OK : constants.X_OK);
@@ -83,6 +139,39 @@ function isExecutablePath(candidatePath) {
         return false;
     }
 }
+/**
+ * Returns true if the resolved path is inside a directory that's already
+ * on PATH (i.e., it was found via normal PATH lookup, not auto-discovery).
+ */
+function isOnPathDirectly(command, resolvedPath) {
+    const pathKey = Object.keys(process.env).find((key) => key.toLowerCase() === "path");
+    const rawPath = pathKey ? process.env[pathKey] : undefined;
+    if (!rawPath)
+        return false;
+    const pathEntries = rawPath
+        .split(process.platform === "win32" ? ";" : ":")
+        .map((entry) => entry.trim().replace(/[\\/]+$/u, ""))
+        .filter(Boolean);
+    const resolvedDir = resolvedPath
+        .replace(/[\\/][^\\/]+$/u, "")
+        .replace(/[\\/]+$/u, "");
+    return pathEntries.some((entry) => entry.toLowerCase() === resolvedDir.toLowerCase());
+}
+/**
+ * Returns a platform-specific one-liner install command for a known CLI.
+ */
+function suggestInstallCommand(command) {
+    const npmInstalls = {
+        claude: "npm install -g @anthropic-ai/claude-code",
+        codex: "npm install -g @openai/codex",
+        gemini: "npm install -g @google/gemini-cli"
+    };
+    const install = npmInstalls[command];
+    if (install) {
+        return `Install with: ${install}`;
+    }
+    return `Install ${command} and ensure it is on PATH.`;
+}
 export function getEngineAvailability(engine) {
     return detectCliAvailability(engine);
 }
@@ -182,18 +271,22 @@ export function buildVerificationSummary(loop, ledgerEvents = []) {
     const latestEvidence = selectedEvidence.evidence;
     if (!latestEvidence) {
         return {
-            status: "unavailable",
+            status: "not_run",
             eventCount: verificationEvents.length,
             ledgerEventCount: verificationLedgerEvents.length,
             warnings
         };
     }
+    const contradicted = latestEvidence.passed === true &&
+        warnings.some((warning) => warning.toLowerCase().includes("conflicts for the latest attempt"));
     return {
-        status: latestEvidence.passed === true
-            ? "passed"
-            : latestEvidence.passed === false
-                ? "failed"
-                : "unavailable",
+        status: contradicted
+            ? "contradicted"
+            : latestEvidence.passed === true
+                ? "passed"
+                : latestEvidence.passed === false
+                    ? "failed"
+                    : "not_run",
         eventCount: verificationEvents.length,
         ledgerEventCount: verificationLedgerEvents.length,
         ...(latestEvidence.attemptIndex !== undefined ? { latestAttemptIndex: latestEvidence.attemptIndex } : {}),
@@ -206,7 +299,7 @@ export function buildVerificationSummary(loop, ledgerEvents = []) {
 }
 export function resolveReceiptIntegrity(loop) {
     return (loop.receiptIntegrity ?? {
-        state: "unsigned",
+        state: "selector_noncanonical",
         reason: "Receipt integrity metadata was not available on the loop record."
     });
 }
@@ -398,7 +491,7 @@ function selectLatestVerificationEvidence(loop, verificationEvents, verification
         .map((candidate) => candidate.passed)
         .filter((candidate) => typeof candidate === "boolean"));
     if (distinctStatuses.size > 1) {
-        warnings.push("Verification evidence conflicts for the latest attempt; reporting status as unavailable.");
+        warnings.push("Verification evidence conflicts for the latest attempt; marking verification as contradicted.");
         return { warnings };
     }
     return {

package/dist/tools/triage-runs.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { decideCircuitBreak } from "../vendor/core/index.js";
 import { buildLoopPreview, buildSuggestedPromptNames, buildSuggestedResourceUris, buildVerificationSummary } from "./tool-support.js";
 import { listLoopRecords, readLedgerEvents } from "./run-store.js";
 import { resolveSafeLoopRecordPath } from "../server-validation.js";
@@ -14,6 +15,16 @@ export async function martinTriageRunsTool(input) {
     const findings = await Promise.all(listed.loops.map(async (loop) => {
         try {
             const preview = buildLoopPreview(loop);
+            const trajectory = decideCircuitBreak({
+                objective: loop.task?.objective ?? loop.loopId,
+                verificationPlan: loop.task?.verificationPlan,
+                attempts: loop.attempts.map((attempt) => ({
+                    index: attempt.index,
+                    summary: attempt.summary,
+                    failureClass: attempt.failureClass
+                })),
+                remainingIterations: preview.remainingIterations
+            });
             let ledgerEvents = [];
             const canonicalLoopRecordPath = resolveSafeLoopRecordPath(loop.loopId, listed.runsRoot);
             ledgerEvents = await readLedgerEvents({
@@ -26,7 +37,7 @@ export async function martinTriageRunsTool(input) {
                 canonicalLoopRecordPath
             });
             const verification = buildVerificationSummary(loop, ledgerEvents);
-            return buildTriageFinding(preview, verification);
+            return buildTriageFinding(preview, verification, trajectory);
         }
         catch {
             warnings.push(`Skipped triage for '${loop.loopId}' because its run record or verification evidence is unreadable.`);
@@ -59,13 +70,17 @@ export async function martinTriageRunsTool(input) {
         warnings
     };
 }
-function buildTriageFinding(loop, verification) {
+function buildTriageFinding(loop, verification, trajectory) {
     const reasonCodes = [];
     let severity = "low";
     if (verification.status === "failed") {
         reasonCodes.push("verification_failed");
         severity = maxSeverity(severity, "critical");
     }
+    if (verification.status === "contradicted") {
+        reasonCodes.push("verification_contradicted");
+        severity = maxSeverity(severity, "critical");
+    }
     if (loop.pressure === "hard_limit" || loop.shouldStop) {
         reasonCodes.push("budget_hard_limit");
         severity = maxSeverity(severity, "critical");
@@ -78,8 +93,12 @@ function buildTriageFinding(loop, verification) {
         reasonCodes.push("diminishing_returns");
         severity = maxSeverity(severity, "high");
     }
-    if (verification.status === "unavailable" && loop.attempts > 0) {
-        reasonCodes.push("verification_unavailable");
+    if (trajectory.shouldStop || trajectory.assessment.status === "stalled") {
+        reasonCodes.push("trajectory_stalled");
+        severity = maxSeverity(severity, "critical");
+    }
+    if (verification.status === "not_run" && loop.attempts > 0) {
+        reasonCodes.push("verification_not_run");
         severity = maxSeverity(severity, "medium");
     }
     if (loop.pressure === "soft_limit") {
@@ -104,6 +123,9 @@ function buildTriageFinding(loop, verification) {
     };
 }
 function summarizeFinding(loop, verification, severity, reasonCodes) {
+    if (reasonCodes.includes("trajectory_stalled")) {
+        return `Severity ${severity}: ${loop.loopId} should not spend another attempt before operator review.`;
+    }
     if (reasonCodes.includes("verification_failed")) {
         return `Severity ${severity}: ${loop.loopId} failed verification after ${loop.attempts} attempt(s).`;
     }
@@ -113,8 +135,11 @@ function summarizeFinding(loop, verification, severity, reasonCodes) {
     if (reasonCodes.includes("status_failed")) {
         return `Severity ${severity}: ${loop.loopId} is currently failed/${loop.lifecycleState}.`;
     }
-    if (reasonCodes.includes("verification_unavailable")) {
-        return `Severity ${severity}: ${loop.loopId} has ${loop.attempts} attempt(s) but verification is unavailable.`;
+    if (reasonCodes.includes("verification_contradicted")) {
+        return `Severity ${severity}: ${loop.loopId} has contradictory verification evidence and needs operator review.`;
+    }
+    if (reasonCodes.includes("verification_not_run")) {
+        return `Severity ${severity}: ${loop.loopId} has ${loop.attempts} attempt(s) but verification was not recorded.`;
     }
     if (reasonCodes.includes("budget_soft_limit")) {
         return `Severity ${severity}: ${loop.loopId} is at soft-limit pressure with ${loop.remainingBudgetUsd.toFixed(2)} USD remaining.`;

package/dist/vendor/adapters/claude-cli.js

@@ -242,12 +242,66 @@ function extractGeminiJsonResult(stdout, modelLabel) {
 function createStreamingUsageInspector(capUsd, modelLabel) {
     const pricing = (modelLabel ? MODEL_PRICING[modelLabel] : undefined) ??
         { inputPer1K: BLENDED_INPUT_COST_PER_1K, outputPer1K: BLENDED_OUTPUT_COST_PER_1K };
+    // Safety margin: terminate at 80% of cap to bound one-turn overshoot.
+    // Without this, a single expensive turn can blow past the cap before the
+    // next check fires (proven live: $1.50 cap → $28.42 actual).
+    const effectiveCapUsd = capUsd * 0.8;
+    // Token-count ceiling fallback: if no usage events are ever parsed (e.g.
+    // Claude changes its stream-json event format), use raw byte volume as a
+    // last-resort circuit breaker. Derived from budget / blended cost per char.
+    const blendedCostPerChar = (pricing.inputPer1K / 1000 / 4) + (pricing.outputPer1K / 1000 / 4);
+    const bytesCeiling = blendedCostPerChar > 0
+        ? Math.ceil((capUsd / blendedCostPerChar) * 2)
+        : 100_000_000;
     let buffer = "";
     let cumulativeUsd = 0;
     let tokensIn = 0;
     let tokensOut = 0;
     let turns = 0;
+    let totalBytes = 0;
+    let usageEventSeen = false;
     let finalResult;
+    const checkBudgetExceeded = (terminate) => {
+        if (capUsd > 0 && cumulativeUsd > effectiveCapUsd) {
+            terminate(`Streaming usage cap exceeded after ${String(turns)} turn(s): cumulative cost ~$${cumulativeUsd.toFixed(4)} ` +
+                `surpassed the per-attempt cap $${capUsd.toFixed(4)} (80% threshold: $${effectiveCapUsd.toFixed(4)}). ` +
+                `Subprocess terminated to bound runaway overspend.`);
+        }
+    };
+    const extractUsageFromEvent = (event, terminate) => {
+        // Check for authoritative total_cost_usd on ANY event — if Claude reports
+        // cost exceeding cap, terminate immediately regardless of event type.
+        if (typeof event.total_cost_usd === "number" && event.total_cost_usd > 0) {
+            cumulativeUsd = event.total_cost_usd;
+            checkBudgetExceeded(terminate);
+            return;
+        }
+        // Extract usage from any event shape that carries it:
+        //   - { type: "assistant", message: { usage: { ... } } }  (original format)
+        //   - { usage: { input_tokens, output_tokens, ... } }      (top-level usage)
+        //   - { message: { usage: { ... } } }                      (nested without type check)
+        const usage = (event.message && typeof event.message === "object" && "usage" in event.message
+            ? event.message.usage
+            : undefined) ??
+            (event.usage && typeof event.usage === "object" ? event.usage : undefined);
+        if (!usage || typeof usage !== "object") {
+            return;
+        }
+        const usageRecord = usage;
+        const turnTokensIn = (usageRecord.input_tokens ?? usageRecord.inputTokens ?? 0) +
+            (usageRecord.cache_read_input_tokens ?? usageRecord.cacheReadInputTokens ?? 0) +
+            (usageRecord.cache_creation_input_tokens ?? usageRecord.cacheCreationInputTokens ?? 0);
+        const turnTokensOut = usageRecord.output_tokens ?? usageRecord.outputTokens ?? 0;
+        if (turnTokensIn === 0 && turnTokensOut === 0) {
+            return;
+        }
+        tokensIn += turnTokensIn;
+        tokensOut += turnTokensOut;
+        turns += 1;
+        usageEventSeen = true;
+        cumulativeUsd += (turnTokensIn / 1000) * pricing.inputPer1K + (turnTokensOut / 1000) * pricing.outputPer1K;
+        checkBudgetExceeded(terminate);
+    };
     const ingestLine = (line, terminate) => {
         const trimmed = line.trim();
         if (!trimmed) {
@@ -260,30 +314,25 @@ function createStreamingUsageInspector(capUsd, modelLabel) {
         catch {
             return;
         }
-        if (event.type === "assistant" && event.message?.usage) {
-            const usage = event.message.usage;
-            const turnTokensIn = (usage.input_tokens ?? usage.inputTokens ?? 0) +
-                (usage.cache_read_input_tokens ?? usage.cacheReadInputTokens ?? 0) +
-                (usage.cache_creation_input_tokens ?? usage.cacheCreationInputTokens ?? 0);
-            const turnTokensOut = usage.output_tokens ?? usage.outputTokens ?? 0;
-            tokensIn += turnTokensIn;
-            tokensOut += turnTokensOut;
-            turns += 1;
-            cumulativeUsd += (turnTokensIn / 1000) * pricing.inputPer1K + (turnTokensOut / 1000) * pricing.outputPer1K;
-            if (capUsd > 0 && cumulativeUsd > capUsd) {
-                terminate(`Streaming usage cap exceeded after ${String(turns)} turn(s): cumulative cost ~$${cumulativeUsd.toFixed(4)} ` +
-                    `surpassed the per-attempt cap $${capUsd.toFixed(4)} (derived from remaining loop budget). ` +
-                    `Subprocess terminated to bound runaway overspend.`);
-            }
-            return;
-        }
+        extractUsageFromEvent(event, terminate);
         if (event.type === "result") {
             finalResult = event;
         }
     };
     return {
         onChunk: (chunk, terminate) => {
-            buffer += chunk.toString("utf8");
+            const chunkStr = chunk.toString("utf8");
+            totalBytes += chunk.byteLength;
+            buffer += chunkStr;
+            // Token-count ceiling fallback: if we've ingested a lot of bytes but
+            // never seen a single usage event, the event format may have changed
+            // and the inspector is silently blind. Terminate as a last resort.
+            if (!usageEventSeen && capUsd > 0 && totalBytes > bytesCeiling) {
+                terminate(`Streaming byte ceiling exceeded (${String(totalBytes)} bytes > ${String(bytesCeiling)} ceiling) ` +
+                    `without any usage events parsed. The Claude stream-json event format may have changed. ` +
+                    `Subprocess terminated as a fallback budget guard for cap $${capUsd.toFixed(4)}.`);
+                return;
+            }
             let newlineIndex = buffer.indexOf("\n");
             while (newlineIndex !== -1) {
                 const line = buffer.slice(0, newlineIndex);
@@ -883,7 +932,8 @@ function buildPrompt(request) {
         for (const attempt of request.previousAttempts) {
             const failurePart = attempt.failureClass ? ` [${attempt.failureClass}]` : "";
             const interventionPart = attempt.intervention ? ` -> intervention: ${attempt.intervention}` : "";
-            lines.push(`  Attempt ${String(attempt.index)}${failurePart}: ${sanitizeForPrompt(attempt.summary ?? "")}${interventionPart}`);
+            const diagPart = attempt.diagnosticHint ? `\n    DIAGNOSIS: ${sanitizeForPrompt(attempt.diagnosticHint)}` : "";
+            lines.push(`  Attempt ${String(attempt.index)}${failurePart}: ${sanitizeForPrompt(attempt.summary ?? "")}${interventionPart}${diagPart}`);
         }
         lines.push("");
     }

package/dist/vendor/adapters/cli-bridge.d.ts

@@ -77,4 +77,10 @@ export interface SpawnPlan {
     args: string[];
 }
 export declare function createSpawnPlan(command: string, args: string[], cwd: string, preserveRawForInjectedSpawn: boolean): SpawnPlan;
+/**
+ * Returns true if the command string contains shell operators that cannot be
+ * passed as literal arguments to spawn(). These must be routed through a
+ * platform shell (cmd.exe /c or sh -c) so the operator is interpreted.
+ */
+export declare function containsShellOperator(command: string): boolean;
 export declare function splitCommand(command: string): string[];