@sweny-ai/core 0.1.198 → 0.1.200

package/dist/executor.d.ts

@@ -40,7 +40,11 @@ export interface ExecuteOptions {
     logger?: Logger;
     /** Working directory for resolving file Sources (default: process.cwd()) */
     cwd?: string;
-    /** Environment variables for Source resolution auth lookup */
+    /**
+     * The env SWEny itself reads for this run: skill config, `context:` Source
+     * auth, the branch pusher's token and the run's identity. It never reaches
+     * the agent; to change the agent's env, pass `env` / `envRemove` to the harness.
+     */
     env?: NodeJS.ProcessEnv;
     /** Host → env-var-name map for URL Source authentication */
     fetchAuth?: Record<string, string>;

package/dist/executor.js

@@ -30,7 +30,7 @@ import { toolRunContext } from "./run-context.js";
 import { fenceUntrusted, fenceUntrustedJson } from "./untrusted.js";
 import { asClaude } from "./harness/compat.js";
 import { budgetGate, isToolClass, policyGate, resolveHarnessPolicy } from "./harness/policy.js";
-import { BudgetGuard, describeOverrun, minLimits, spendOf, toLimits } from "./budget.js";
+import { BudgetGuard, BudgetRefusal, describeOverrun, minLimits, spendOf, toLimits } from "./budget.js";
 import { createRunDecider, wantsDecider } from "./decider.js";
 import { redact, runSecretValues } from "./journal.js";
 import { buildNodePolicy, resolveNodePermissions } from "./node-policy.js";
@@ -90,6 +90,7 @@ export async function execute(workflow, input, options) {
         };
         results.set(at.node, result);
         trace.steps.push({ node: at.node, status: "failed", iteration: at.iteration });
+        at.syncSpend?.();
         safeObserve(options.observer, { type: "node:exit", node: at.node, result }, logger);
         logger.error(`  ${err.message}`, { node: at.node });
         journalDegraded();
@@ -130,6 +131,130 @@ async function executeRun(workflow, input, options, results, trace, at) {
     // Spend budgets (#449): the run ceiling is the lower of the workflow's
     // `budget` and the caller's (`--max-tokens`, `--max-cost`).
     const budgetGuard = new BudgetGuard(minLimits(toLimits(workflow.budget), toLimits(options.budget)));
+    // The executor's own completions (judge, route, retry reflection, safe-output
+    // screen) report usage into the same guard as node runs, under their kind,
+    // and into the journal so a resume keeps them. Every call passes a gate
+    // first: once a ceiling is reached (or a usage record could not be
+    // journaled) the call is refused, not made. `sink` counts one completion's
+    // total and keeps any breach for the caller; it never throws into the
+    // adapter, so a journal failure inside it is held in `meterFault` and
+    // rethrown by the executor at the next step.
+    let meterFault;
+    const throwIfMeterFault = () => {
+        if (meterFault)
+            throw meterFault;
+    };
+    const metered = (refuse, sink) => {
+        const gate = () => {
+            throwIfMeterFault();
+            const stop = refuse();
+            if (stop)
+                throw new BudgetRefusal(stop);
+        };
+        return {
+            defaultJudgeModel: claude.defaultJudgeModel,
+            run: (req) => claude.run(req),
+            evaluate: async (opts) => {
+                gate();
+                return claude.evaluate({ ...opts, onUsage: sink });
+            },
+            ask: async (opts) => {
+                gate();
+                return claude.ask({ ...opts, onUsage: sink });
+            },
+        };
+    };
+    const journalMeter = (kind, node, iteration, u) => {
+        if (!journal?.meter || meterFault)
+            return;
+        try {
+            journal.meter(kind, node, iteration, u);
+        }
+        catch (err) {
+            meterFault = err;
+        }
+    };
+    const syncSpend = () => {
+        if (budgetGuard.hasMeteredCalls)
+            trace.spend = budgetGuard.breakdown();
+    };
+    at.syncSpend = syncSpend;
+    // A route call that crossed the run budget, or was refused because the run
+    // budget was already spent. The next node is then refused at its start; a
+    // route that ends the run fails the node it left.
+    let routeBreach;
+    let routingFrom;
+    const routeClaude = metered(() => (routeBreach ??= budgetGuard.runExhausted()), (u) => {
+        const b = budgetGuard.meter("route", u);
+        if (routingFrom)
+            journalMeter("route", routingFrom.node, routingFrom.iteration, u);
+        syncSpend();
+        if (b) {
+            routeBreach ??= b;
+            logger.warn(`  ${describeOverrun(b)}; the next node does not start`);
+        }
+    });
+    // Routing from `from`. `budgetStop` says the run ended there on the budget:
+    // the caller then writes no route record, so the journal keeps the visit
+    // ended but unrouted. A resume (with a larger cap) then routes a visit that
+    // succeeded again, like a crash between node:end and the route; a visit
+    // that had failed (`on_fail: continue`) is run again.
+    const advance = async (from) => {
+        routeBreach = undefined;
+        routingFrom = { node: from, iteration: nodeRunCounts.get(from) ?? 1 };
+        // No paid routing once the run budget is spent: the decider (an HTTP
+        // model call) is skipped like the agent's route evaluation, which the gate refuses.
+        const spentBeforeRouting = budgetGuard.runExhausted();
+        if (spentBeforeRouting && routing.decider && !trace.deciderOff)
+            trace.deciderOff = "run budget spent";
+        const routeOpts = spentBeforeRouting ? { ...routing, decider: null } : routing;
+        let routed;
+        let refused = false;
+        try {
+            routed = await advanceFromNode(workflow, from, results, input, routeClaude, observer, edgeCounts, logger, trace, routeOpts);
+        }
+        catch (err) {
+            throwIfMeterFault();
+            if (!(err instanceof BudgetRefusal))
+                throw err;
+            logger.warn(`  ${describeOverrun(err.breach)}; not routing from '${from}'`, { node: from });
+            routed = { next: null };
+            refused = true;
+        }
+        finally {
+            routingFrom = undefined;
+        }
+        throwIfMeterFault();
+        const breach = routeBreach;
+        routeBreach = undefined;
+        if (breach && routed.next === null) {
+            // No node is left to refuse: the stop lands on the node the route left.
+            const prior = results.get(from);
+            if (prior && !prior.budget) {
+                const error = describeOverrun(breach, from);
+                // A node that had already failed keeps its own error; the budget reason has its own field.
+                const priorError = prior.data?.error;
+                const amended = {
+                    ...prior,
+                    status: "failed",
+                    data: { ...prior.data, error: priorError ?? error, budget_error: error, budget_exceeded: true },
+                    budget: breach,
+                };
+                results.set(from, amended);
+                // The trace and observers already saw the visit end: they get the amended result as an amendment, not a second exit.
+                const iteration = nodeRunCounts.get(from) ?? 1;
+                const step = [...trace.steps].reverse().find((st) => st.node === from && st.iteration === iteration);
+                if (step)
+                    step.status = "failed";
+                safeObserve(observer, { type: "node:amended", node: from, result: amended }, logger);
+            }
+            // Routing already announced its own end (an invalid target); a refused route announced nothing.
+            if (refused)
+                safeObserve(observer, { type: "route", from, to: "(end)", reason: "budget exceeded" }, logger);
+            return { ...routed, budgetStop: true };
+        }
+        return routed;
+    };
     const harnessPolicy = options.harnessPolicy ?? resolveHarnessPolicy(runEnv);
     // #473: a checkout that persisted a git credential (actions/checkout's
     // default). Each harness masks it for read-only and staged nodes, or reports
@@ -279,8 +404,9 @@ async function executeRun(workflow, input, options, results, trace, at) {
             logger.info(`  replayed from the run journal: ${replay.result.status}`, { node: currentId });
             const from = currentId;
             if (replay.next === undefined) {
-                const routed = await advanceFromNode(workflow, from, results, input, claude, observer, edgeCounts, logger, trace, routing);
-                journal?.route(from, routed.next, routed.rung, decider?.counters);
+                const routed = await advance(from);
+                if (!routed.budgetStop)
+                    journal?.route(from, routed.next, routed.rung, decider?.counters);
                 currentId = routed.next;
             }
             else {
@@ -304,6 +430,27 @@ async function executeRun(workflow, input, options, results, trace, at) {
             continue;
         }
         journal?.nodeStart(currentId, iteration);
+        // The run budget is already spent (by a route call, or by the node before
+        // a skipped one): this node neither starts nor routes on, whatever its
+        // `requires` say, so a skipped node cannot carry the run past the stop.
+        // A checkpointed visit (resume) already ran its agent: its writes still apply.
+        const runSpent = replay?.kind === "checkpoint" ? undefined : budgetGuard.runExhausted();
+        if (runSpent) {
+            const error = describeOverrun(runSpent, currentId);
+            const result = {
+                status: "failed",
+                data: { error, budget_exceeded: true },
+                toolCalls: [],
+                budget: runSpent,
+            };
+            results.set(currentId, result);
+            journal?.nodeEnd(currentId, iteration, result, writeState);
+            trace.steps.push({ node: currentId, status: "failed", iteration });
+            safeObserve(observer, { type: "node:exit", node: currentId, result }, logger);
+            logger.warn(`  ${error}; not starting the node`, { node: currentId });
+            safeObserve(observer, { type: "route", from: currentId, to: "(end)", reason: "node failed (budget exceeded)" }, logger);
+            break;
+        }
         // Gather tools from the node's skills, then apply the node's optional
         // skill-tool filter (`tools.allow` / `tools.deny`). Filtered tools are
         // never registered for the run, so the model cannot see or call them.
@@ -406,8 +553,9 @@ async function executeRun(workflow, input, options, results, trace, at) {
             }
             // Apply normal routing rules (dry run gate + resolveNext).
             // TODO: dedupe with requires path — see advanceFromNode helper below
-            const routed = await advanceFromNode(workflow, currentId, results, input, claude, observer, edgeCounts, logger, trace, routing);
-            journal?.route(currentId, routed.next, routed.rung, decider?.counters);
+            const routed = await advance(currentId);
+            if (!routed.budgetStop)
+                journal?.route(currentId, routed.next, routed.rung, decider?.counters);
             currentId = routed.next;
             continue;
         }
@@ -496,12 +644,40 @@ async function executeRun(workflow, input, options, results, trace, at) {
         // run's. The gate says whether the harness can keep them; a strict policy
         // refuses the node when it cannot report the budgeted unit at all.
         const nodeBudget = budgetGuard.node(toLimits(node.budget));
+        // Resume: this visit's spend before the crash counts against its node
+        // budget again (the run total already has it from the seed), whether the
+        // write stage is replayed or the visit runs again.
+        const visitPrior = replay?.kind === "checkpoint" ? replay.spent : replay ? undefined : journal?.visitSpent?.(currentId, iteration);
+        if (visitPrior)
+            nodeBudget.restore(visitPrior);
         const budgetOn = budgetGuard.active(nodeBudget.limits);
         const budgetCheck = budgetOn && options.harness
             ? budgetGate(options.harness.capabilities, minLimits(nodeBudget.limits, budgetGuard.runLimits), permissions.strict || harnessPolicy === "strict")
             : undefined;
         // A budget stop: fail_soft and on_fail: continue never apply, the run halts.
         let budgetStop;
+        // This visit's own completions (judge scoring, retry reflection, output
+        // screen) count against the node and the run; a crossing is kept here.
+        let meterBreach;
+        const visitId = currentId;
+        const visitClaude = (kind) => metered(
+        // Latched: once refused, every later call of this visit is refused too.
+        () => (meterBreach ??= budgetOn ? nodeBudget.exhausted() : undefined), (u) => {
+            const b = nodeBudget.meter(kind, u);
+            journalMeter(kind, visitId, iteration, u);
+            syncSpend();
+            meterBreach ??= b;
+        });
+        const judgeClaude = visitClaude("judge");
+        const reflectClaude = visitClaude("reflect");
+        const screenClaude = visitClaude("screen");
+        // A ceiling reached before a paid executor call (judges, reflection): the
+        // node fails with the budget reason instead of making the call.
+        const stopAtCeiling = (r, b) => {
+            const error = describeOverrun(b, visitId);
+            logger.warn(`  ${error}`, { node: currentId });
+            return { ...r, status: "failed", data: { ...r.data, error, budget_exceeded: true }, budget: b };
+        };
         let previous;
         while (true) {
             if (replay?.kind === "checkpoint") {
@@ -509,6 +685,8 @@ async function executeRun(workflow, input, options, results, trace, at) {
                 // write intents; the write stage below skips what the journal shows was already applied.
                 ({ result, agentRunFailed, attempt } = replay);
                 intents.push(...replay.intents);
+                // The visit's own spend before the crash counts against its node budget
+                // again (the run total already has it from the seed).
                 break;
             }
             const refusal = gate?.refuse ?? budgetCheck?.refuse;
@@ -562,7 +740,6 @@ async function executeRun(workflow, input, options, results, trace, at) {
             }
             const journalUsage = journal?.usage
                 ? (u) => {
-                    liveUsage = { ...liveUsage, ...u };
                     if (journalFault)
                         return;
                     try {
@@ -574,12 +751,12 @@ async function executeRun(workflow, input, options, results, trace, at) {
                     }
                 }
                 : undefined;
-            const onUsage = attemptBudget || journalUsage
-                ? (u) => {
-                    attemptBudget?.onUsage(u);
-                    journalUsage?.(u);
-                }
-                : undefined;
+            // Live usage is always collected: with no limit it still feeds the split by kind.
+            const onUsage = (u) => {
+                liveUsage = { ...liveUsage, ...u };
+                attemptBudget?.onUsage(u);
+                journalUsage?.(u);
+            };
             try {
                 result = await claude.run({
                     nodeId: currentId,
@@ -597,13 +774,17 @@ async function executeRun(workflow, input, options, results, trace, at) {
                     ...(nodePolicy ? { policy: nodePolicy } : {}),
                     ...(readOnlyNode || stageOutputs ? {} : { mcpServers: skillMcpServers }),
                     ...(readOnlyNode ? { readOnly: true } : {}),
-                    ...(onUsage ? { onUsage } : {}),
+                    onUsage,
                     onProgress: (message) => {
                         safeObserve(observer, { type: "node:progress", node: currentId, message }, logger);
                     },
                 });
                 // Commit the attempt's spend before anything here can throw (#549); `finish` below reads the breach.
-                attemptBudget?.settle(result.usage);
+                if (attemptBudget)
+                    attemptBudget.settle(result.usage);
+                // No limit to enforce: still count the run, so the split by kind is complete.
+                else
+                    budgetGuard.meter("node", attemptSpend(result.usage, liveUsage));
             }
             catch (err) {
                 if (journalFault)
@@ -741,13 +922,37 @@ async function executeRun(workflow, input, options, results, trace, at) {
                 result.evals = [failure];
             }
             else {
-                const evalResults = await evaluateAll(node.eval, result, {
-                    aliases: toolAliases,
-                    claude,
-                    node,
-                    workflow,
-                });
-                result.evals = evalResults;
+                // With a budget on, judges run one at a time, so a crossing (or a
+                // ceiling already reached) refuses the rest instead of all starting at once.
+                let evalResults;
+                try {
+                    evalResults = await evaluateAll(node.eval, result, {
+                        aliases: toolAliases,
+                        claude: judgeClaude,
+                        node,
+                        workflow,
+                        sequential: budgetOn,
+                        ...(signal ? { signal } : {}),
+                        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+                    });
+                }
+                catch (err) {
+                    throwIfMeterFault();
+                    if (!(err instanceof BudgetRefusal))
+                        throw err;
+                }
+                throwIfMeterFault();
+                if (evalResults)
+                    result.evals = evalResults;
+                if (meterBreach || !evalResults) {
+                    // Judge spend crossed a ceiling, or a judge was refused at one (the
+                    // refusal latched it): the node fails whatever the verdicts said.
+                    const stop = meterBreach ?? nodeBudget.exhausted() ?? budgetGuard.runExhausted();
+                    result = stop ? stopAtCeiling(result, stop) : result;
+                    agentRunFailed = true;
+                    budgetStop = stop;
+                    break;
+                }
                 outcome = aggregateEval(evalResults, node.eval_policy ?? "all_pass");
             }
             if (outcome.pass)
@@ -786,13 +991,21 @@ async function executeRun(workflow, input, options, results, trace, at) {
                 evalFailures: outcome.failures,
                 toolCalls: result.toolCalls,
                 nodeInstruction: resolvedInstruction,
-                claude,
+                claude: reflectClaude,
                 logger,
                 context,
                 model: nodeModel,
                 signal,
                 timeoutMs,
             });
+            throwIfMeterFault();
+            // A reflection refused at a ceiling (or one whose spend crossed it): no further attempt.
+            if (meterBreach) {
+                result = stopAtCeiling(result, meterBreach);
+                agentRunFailed = true;
+                budgetStop = meterBreach;
+                break;
+            }
             currentInstruction = `${preamble}\n\n---\n\n${instruction}`;
             safeObserve(observer, { type: "node:retry", node: currentId, attempt: attempt + 1, reason: outcome.error ?? "eval failed", preamble }, logger);
             attempt++;
@@ -840,19 +1053,35 @@ async function executeRun(workflow, input, options, results, trace, at) {
                     state: writeState,
                     logger,
                     input: runInput,
-                    screen: async (writes) => claude.ask({
-                        instruction: SAFE_OUTPUT_SCREEN_INSTRUCTION,
-                        context: { writes },
-                        model: nodeModel,
-                        signal,
-                        timeoutMs,
-                    }),
+                    ...(journal?.reconcile
+                        ? {
+                            reconcile: (sk, tool, args, ctx) => journal.reconcile(visitId, iteration, sk, tool, args, ctx),
+                        }
+                        : {}),
+                    screen: async (writes) => {
+                        const verdict = await screenClaude.ask({
+                            instruction: SAFE_OUTPUT_SCREEN_INSTRUCTION,
+                            context: { writes },
+                            model: nodeModel,
+                            signal,
+                            timeoutMs,
+                        });
+                        // A screen whose spend crossed a ceiling, or whose meter record the
+                        // journal could not write, allows nothing: the writes are vetoed.
+                        return meterBreach || meterFault ? null : verdict;
+                    },
                 });
+                throwIfMeterFault();
                 result = { ...result, outputs: stage.receipts };
                 if (stage.error) {
                     logger.warn(`  ${stage.error}`, { node: currentId });
                     result = { ...result, status: "failed", data: { ...result.data, error: stage.error } };
                 }
+                if (meterBreach && !budgetStop) {
+                    // The screen's spend crossed a ceiling: the node fails and the run halts.
+                    result = stopAtCeiling(result, meterBreach);
+                    budgetStop = meterBreach;
+                }
             }
             else if (intents.length > 0) {
                 result = {
@@ -885,17 +1114,33 @@ async function executeRun(workflow, input, options, results, trace, at) {
         }
         // Dry run gate + routing — shared with requires path via advanceFromNode helper.
         const routedFrom = currentId;
-        const routed = await advanceFromNode(workflow, currentId, results, input, claude, observer, edgeCounts, logger, trace, routing);
-        journal?.route(routedFrom, routed.next, routed.rung, decider?.counters);
+        const routed = await advance(routedFrom);
+        if (!routed.budgetStop)
+            journal?.route(routedFrom, routed.next, routed.rung, decider?.counters);
         currentId = routed.next;
     }
     safeObserve(observer, {
         type: "workflow:end",
         results: Object.fromEntries(results),
     }, logger);
+    syncSpend();
     return { results, trace };
 }
 // ─── Internals ───────────────────────────────────────────────────
+/**
+ * An attempt's spend as usage: per unit, the larger of the final report and
+ * the last live one (what `BudgetAttempt.settle` commits), so the split is the
+ * same with and without a limit. Undefined when neither reported anything.
+ */
+function attemptSpend(final, live) {
+    const f = spendOf(final);
+    const l = spendOf(live);
+    const tokens = f.tokens === undefined && l.tokens === undefined ? undefined : Math.max(f.tokens ?? 0, l.tokens ?? 0);
+    const costUsd = f.costUsd === undefined && l.costUsd === undefined ? undefined : Math.max(f.costUsd ?? 0, l.costUsd ?? 0);
+    if (tokens === undefined && costUsd === undefined)
+        return undefined;
+    return { ...(tokens !== undefined ? { inputTokens: tokens } : {}), ...(costUsd !== undefined ? { costUsd } : {}) };
+}
 /**
  * Thrown when a conditional routing decision could not be made and there is
  * no explicit default (unconditional) edge to fall back to. Fails closed: the

package/dist/harness/acp.d.ts

@@ -45,7 +45,7 @@
  * - Timeout: `session/cancel`, a grace period, then the process is killed.
  */
 import type { Logger, McpServerConfig, ToolContext } from "../types.js";
-import { type SandboxMode } from "../agent-env.js";
+import { type HarnessEnvOptions, type SandboxMode } from "../agent-env.js";
 import type { AgentHarness, HarnessCapabilities, HarnessCompleteRequest, HarnessId, HarnessInfo, HarnessRunRequest, HarnessRunResult, ToolClass } from "./types.js";
 import { ACP_CAPABILITIES } from "./capabilities.js";
 import { type HarnessPolicyMode } from "./policy.js";
@@ -53,7 +53,7 @@ import { type SandboxWrapper } from "./sandbox-wrapper.js";
 export { ACP_CAPABILITIES };
 /** The ACP major version sweny speaks (`InitializeRequest.protocolVersion`). */
 export declare const ACP_PROTOCOL_VERSION = 1;
-export interface AcpHarnessOptions {
+export interface AcpHarnessOptions extends HarnessEnvOptions {
     /**
      * The agent to run: a command line (`"opencode acp"`, the part after `acp:`)
      * or an explicit `{command, args}`. Never run through a shell.
@@ -139,6 +139,7 @@ export declare class AcpHarness implements AgentHarness {
     private envPassthrough;
     private authVars;
     private envScope;
+    private envOverlay;
     private sandboxMode;
     private sandboxWrapper;
     private policyMode;
@@ -167,6 +168,8 @@ export declare class AcpHarness implements AgentHarness {
      * vars the operator named. Skill credentials are dropped either way
      * ({@link finishAgentEnv}) unless the node granted them with `agent_env`; an
      * operator-named auth var stays, and the gate counts it if it is a write token.
+     * The caller's `envRemove` / `env` are applied after scoping
+     * ({@link applyEnvOverlay}), before that credential rule.
      */
     private buildEnv;
     /** The node policy, with the harness policy mode and the watchdog budget applied. */

package/dist/harness/acp.js

@@ -45,14 +45,13 @@
  * - Timeout: `session/cancel`, a grace period, then the process is killed.
  */
 import { spawn } from "node:child_process";
-import * as fs from "node:fs";
 import * as path from "node:path";
 import { consoleLogger } from "../types.js";
-import { finishAgentEnv, heldCredentials, parseList, reportWithheldEnv, resolveEnvScope, resolveSandboxMode, scopeAgentEnv, withPushBlocked, mcpWithheld, } from "../agent-env.js";
+import { agentEnvOverlay, applyEnvOverlay, finishAgentEnv, heldCredentials, overlaidProcessEnv, resolveExecutable, parseList, reportWithheldEnv, resolveEnvScope, resolveSandboxMode, scopeAgentEnv, withPushBlocked, mcpWithheld, } from "../agent-env.js";
 import { ACP_CAPABILITIES } from "./capabilities.js";
 import { policyGate, resolveHarnessPolicy, TOOL_CLASSES } from "./policy.js";
 import { gitCredentialPolicy } from "../git-credentials.js";
-import { buildNodePrompt } from "./prompts.js";
+import { buildNodePrompt, reportCompletionUsage } from "./prompts.js";
 import { makeAbort } from "./abort.js";
 import { parseToolResultContent, schemaMismatches, summarizeToolError, tryParseJSON } from "./parse.js";
 import { startToolBridge } from "./tool-bridge/server.js";
@@ -148,25 +147,6 @@ export function toAcpMcpServers(servers, agentHttp) {
     }
     return { list, unsupported };
 }
-function resolveOnPath(command, env) {
-    const ok = (p) => {
-        try {
-            fs.accessSync(p, fs.constants.X_OK);
-            return fs.statSync(p).isFile();
-        }
-        catch {
-            return false;
-        }
-    };
-    if (command.includes(path.sep) || command.includes("/"))
-        return ok(command) ? command : undefined;
-    for (const dir of (env.PATH ?? "").split(path.delimiter).filter(Boolean)) {
-        const p = path.join(dir, command);
-        if (ok(p))
-            return p;
-    }
-    return undefined;
-}
 // ─── Process registry (crash cleanup) ────────────────────────────
 const liveChildren = new Set();
 let exitHookInstalled = false;
@@ -207,6 +187,7 @@ export class AcpHarness {
     envPassthrough;
     authVars;
     envScope;
+    envOverlay;
     sandboxMode;
     sandboxWrapper;
     policyMode;
@@ -238,6 +219,7 @@ export class AcpHarness {
         this.envPassthrough = opts.envPassthrough;
         this.authVars = opts.authVars ?? [];
         this.envScope = opts.envScope;
+        this.envOverlay = agentEnvOverlay(opts);
         this.sandboxMode = opts.sandbox;
         this.sandboxWrapper = opts.sandboxWrapper;
         this.policyMode = opts.policy ?? resolveHarnessPolicy(process.env, undefined, this.logger);
@@ -256,7 +238,7 @@ export class AcpHarness {
      * first run (`agentInfo.version`).
      */
     async preflight() {
-        const found = resolveOnPath(this.agent.command, process.env);
+        const found = resolveExecutable(this.agent.command, overlaidProcessEnv(this.envOverlay, this.authVars), this.cwd);
         if (!found) {
             const example = [this.agent.command, ...this.agent.args].join(" ");
             return {
@@ -271,6 +253,8 @@ export class AcpHarness {
      * vars the operator named. Skill credentials are dropped either way
      * ({@link finishAgentEnv}) unless the node granted them with `agent_env`; an
      * operator-named auth var stays, and the gate counts it if it is a write token.
+     * The caller's `envRemove` / `env` are applied after scoping
+     * ({@link applyEnvOverlay}), before that credential rule.
      */
     buildEnv(access) {
         const full = Object.fromEntries(Object.entries(process.env).filter((e) => e[1] != null));
@@ -287,6 +271,7 @@ export class AcpHarness {
             reportWithheldEnv(scoped.withheld, this.logger);
             env = scoped.env;
         }
+        env = applyEnvOverlay(env, this.envOverlay, this.authVars);
         return finishAgentEnv(env, { access, keep: this.authVars, passthrough, logger: this.logger }).env;
     }
     /** The node policy, with the harness policy mode and the watchdog budget applied. */
@@ -952,6 +937,9 @@ export class AcpHarness {
         }
         if (conv.agentVersion)
             this.agentVersion = conv.agentVersion;
+        // A completion that failed was still billed: report before the outcome.
+        if (conv.costUsd !== undefined)
+            reportCompletionUsage(req.onUsage, { costUsd: conv.costUsd }, this.logger);
         if (conv.spawnError)
             return failClosed(`the ACP agent could not start: ${conv.spawnError}`);
         if (conv.abortReason === "timeout")

package/dist/harness/auth.js

@@ -30,7 +30,8 @@ function truthy(v) {
  */
 export function detectClaudeCodeLogin(opts = {}) {
     const env = opts.env ?? process.env;
-    const home = opts.home ?? os.homedir();
+    // The env's HOME, not the process's: a harness `env` overlay may give the run its own.
+    const home = opts.home ?? (env.HOME || os.homedir());
     const platform = opts.platform ?? process.platform;
     const configDir = env.CLAUDE_CONFIG_DIR || path.join(home, ".claude");
     try {