@sagentlab/navarch-runtime 0.1.14 → 0.1.17

package/README.md

@@ -6,10 +6,10 @@ it. Plain Node/TypeScript, zero production dependencies, no Next.js coupling
 — this directory is a self-contained package you can `npx` on any fresh
 machine.
 
-The control plane selects **Claude Code**, **OpenAI Codex**, or **Google
-Gemini CLI** from the project's default and any task override. Workers
-advertise the adapters they can run, so tasks wait for an eligible runtime
-and capability match — see "Choosing an agent" below.
+The machine operator selects **Claude Code**, **OpenAI Codex**, or **Google
+Gemini CLI** when connecting a worker. Any selected agent can run any project
+task; task eligibility depends on capabilities and project gates, not agent
+type — see "Choosing an agent" below.
 
 See [`docs/agent-platform-project-plan.md`](../docs/agent-platform-project-plan.md)
 §3.8/§3.9/§3.11 and [`docs/navarch/implementation-plan.md`](../docs/navarch/implementation-plan.md)
@@ -74,6 +74,22 @@ the runtime. The UI-generated npm commands remain the source of truth for the
 token, project, agent, capacity, API origin, and config directory; translate
 those same options to `node bin/navarch.cjs` for a source install.
 
+### Releasing a runtime change
+
+Publication is triggered by the version, not by the code: a push to `main` that
+changes `runtime/package.json` publishes that exact version of
+`@sagentlab/navarch-runtime` and rolls it out. So a pull request that edits
+`runtime/src/**` or `runtime/bin/**` without bumping the version merges green
+and never reaches a machine. Bump `runtime/package.json` and
+`runtime/package-lock.json` to the same new version in the pull request that
+carries the change; CI's `Runtime` job fails the pull request when that bump is
+missing, when the two manifests disagree, or when the version is one the base
+branch tip or npm already carries.
+
+[`playbooks/runtime-releases.md`](../playbooks/runtime-releases.md) is the full
+release contract — the guard's exact cases, the post-merge duplicate backstop,
+and the recovery steps.
+
 The operator-only `register` command enrolls a globally managed machine. It is
 not the normal public onboarding path. `register` prints the machine auth token
 once and stores the same `machine.json` identity used by `connect`. For
@@ -354,15 +370,15 @@ export NAVARCH_AGENT=codex
 # NAVARCH_GEMINI_BIN pointing at it).
 export NAVARCH_AGENT=gemini
 
-# Or let one worker serve tasks selected for any installed adapter.
+# Advanced compatibility mode: advertise every installed adapter.
 export NAVARCH_RUNTIMES=claude-code,codex,gemini
 ```
 
 For the legacy single-runtime setting, priority is `start --agent` →
 `NAVARCH_AGENT` → the locally saved choice → `claude-code`.
-`NAVARCH_RUNTIMES` expands what the worker advertises; the control plane then
-resolves `tasks.runtime_override` → `projects.default_runtime` and returns the
-selected adapter with the claim.
+`NAVARCH_RUNTIMES` expands what the worker advertises. For normal projects,
+the locally selected `NAVARCH_AGENT` handles every claimed task. Sandbox
+projects remain constrained to Claude Code.
 
 All three adapters implement the same `AgentAdapter` interface
 (`src/adapters/types.cts`) and run either directly on the host or via

package/dist/api.cjs

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NavarchApiClient = exports.NavarchTransportError = exports.NavarchApiError = void 0;
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const MAX_ERROR_CAUSE_DEPTH = 4;
+const MAX_AGGREGATE_ERRORS = 4;
 class NavarchApiError extends Error {
     status;
     body;
@@ -34,10 +37,12 @@ class NavarchApiClient {
     baseUrl;
     token;
     fetchImpl;
+    requestTimeoutMs;
     constructor(opts) {
         this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
         this.token = opts.token;
         this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.requestTimeoutMs = opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
     }
     /** The control-plane base URL this client talks to (used to build the per-session platform MCP config -- see mcp-config.cts). */
     getBaseUrl() {
@@ -57,29 +62,41 @@ class NavarchApiClient {
             headers.authorization = `Bearer ${this.token}`;
         }
         const requestUrl = `${this.baseUrl}${pathname}`;
-        let response;
+        const abortController = new AbortController();
+        const requestTimeout = setTimeout(() => {
+            const timeoutError = new Error(`request timed out after ${this.requestTimeoutMs}ms`);
+            timeoutError.name = "TimeoutError";
+            abortController.abort(timeoutError);
+        }, this.requestTimeoutMs);
         try {
-            response = await this.fetchImpl(requestUrl, {
+            const response = await this.fetchImpl(requestUrl, {
                 method,
                 headers,
                 body: body === undefined ? undefined : JSON.stringify(body),
+                signal: abortController.signal,
             });
+            if (response.status === 204)
+                return null;
+            const text = await response.text();
+            const parsed = text ? safeJsonParse(text) : null;
+            if (!response.ok) {
+                throw new NavarchApiError(`Navarch API ${method} ${pathname} failed with ${response.status}`, response.status, parsed ?? text);
+            }
+            if (opts?.allowEmpty && parsed === null)
+                return null;
+            return parsed;
         }
         catch (err) {
+            if (err instanceof NavarchApiError)
+                throw err;
             // Include enough request/cause context to diagnose DNS, connection, and
-            // TLS failures. Deliberately omit headers and URL credentials/query data.
+            // TLS/body-stream failures. Deliberately omit headers and URL
+            // credentials/query data.
             throw new NavarchTransportError(method, safeEndpoint(requestUrl, pathname), err);
         }
-        if (response.status === 204)
-            return null;
-        const text = await response.text();
-        const parsed = text ? safeJsonParse(text) : null;
-        if (!response.ok) {
-            throw new NavarchApiError(`Navarch API ${method} ${pathname} failed with ${response.status}`, response.status, parsed ?? text);
+        finally {
+            clearTimeout(requestTimeout);
         }
-        if (opts?.allowEmpty && parsed === null)
-            return null;
-        return parsed;
     }
     /** Global machine registration using the operator-configured enrollment secret. */
     async registerMachine(req) {
@@ -163,16 +180,26 @@ function safeEndpoint(requestUrl, pathname) {
         return pathname;
     }
 }
-function describeError(err) {
+function describeError(err, seen = new Set(), depth = 0) {
     if (!(err instanceof Error))
         return String(err);
-    let detail = `${err.name}: ${err.message}`;
-    const cause = err.cause;
-    if (cause instanceof Error) {
-        detail += `; cause: ${cause.name}: ${cause.message}`;
-    }
-    else if (cause && typeof cause === "object" && "code" in cause) {
-        detail += `; cause code: ${String(cause.code)}`;
+    if (seen.has(err))
+        return "[circular error cause]";
+    const detail = err.message ? `${err.name}: ${err.message}` : err.name;
+    if (depth >= MAX_ERROR_CAUSE_DEPTH)
+        return detail;
+    seen.add(err);
+    const nested = [];
+    if (err.cause !== undefined) {
+        nested.push(`cause: ${describeError(err.cause, seen, depth + 1)}`);
+    }
+    if (err instanceof AggregateError) {
+        const errors = Array.from(err.errors).slice(0, MAX_AGGREGATE_ERRORS);
+        if (errors.length > 0) {
+            nested.push(`errors: [${errors
+                .map((child) => describeError(child, seen, depth + 1))
+                .join("; ")}]`);
+        }
     }
-    return detail;
+    return nested.length > 0 ? `${detail}; ${nested.join("; ")}` : detail;
 }

package/dist/cli.cjs

@@ -247,8 +247,14 @@ async function startCommand(flags) {
 async function superviseCommand(flags) {
     const config = configFromFlags(flags);
     const identity = await (0, machine_store_cjs_1.resolveMachineIdentity)(config.configDir, config.apiBase);
-    const agentType = agentFromFlag(flags);
-    const workerArgs = agentType ? ["--agent", agentType] : [];
+    // Resolve and pin the adapter before spawning the worker. The supervisor
+    // passes machine credentials through the environment, so the child no
+    // longer reads machine.json for identity fields (including agent_type).
+    // Without an explicit worker argument, a saved Codex/Gemini selection
+    // therefore falls back to Claude Code.
+    const agentType = agentFromFlag(flags) ??
+        (process.env.NAVARCH_AGENT ? config.agentType : identity.agent_type ?? config.agentType);
+    const workerArgs = ["--agent", agentType];
     // Pin the identity for this supervisor's lifetime. Without this snapshot, a
     // replacement worker rereads machine.json after an automatic update and can
     // silently become a different machine if another terminal reused the same

package/dist/config.cjs

@@ -20,6 +20,16 @@ function envInt(env, name, fallback) {
     const n = Number(raw);
     return Number.isFinite(n) && n > 0 ? n : fallback;
 }
+/** Default `$CODEX_HOME`, matching the Codex CLI's own resolution. */
+function defaultCodexHome(env) {
+    return env.CODEX_HOME ?? node_path_1.default.join(node_os_1.default.homedir(), ".codex");
+}
+/** Claude Code's global config sits beside the home dir, or under `CLAUDE_CONFIG_DIR`. */
+function defaultClaudeConfigPath(env) {
+    return env.CLAUDE_CONFIG_DIR
+        ? node_path_1.default.join(env.CLAUDE_CONFIG_DIR, ".claude.json")
+        : node_path_1.default.join(node_os_1.default.homedir(), ".claude.json");
+}
 function envList(env, name, fallback) {
     const raw = env[name];
     if (!raw)
@@ -82,5 +92,10 @@ function loadRuntimeConfig(env = process.env) {
         updateChannel: env.NAVARCH_UPDATE_CHANNEL === "canary" ? "canary" : "stable",
         autoUpdate: env.NAVARCH_SUPERVISED === "1" &&
             !["off", "false", "0"].includes(env.NAVARCH_AUTO_UPDATE ?? ""),
+        // Reads only the quota numbers providers already write to disk, so it is on
+        // by default; operators who would rather share nothing can opt out.
+        reportUsageLimits: !["off", "false", "0"].includes(env.NAVARCH_USAGE_LIMITS ?? ""),
+        codexHome: defaultCodexHome(env),
+        claudeConfigPath: defaultClaudeConfigPath(env),
     };
 }

package/dist/exit-conditions.cjs

@@ -175,7 +175,7 @@ function summarize(text, maxLen = 500) {
 function mapExitCondition(result) {
     // Agent output is untrusted evidence, including the final completion
     // message. session.cts resolves PR evidence independently through GitHub
-    // using this session's exact repository and worktree head branch.
+    // using the session repository and the worktree's live branch/commit.
     const parsedJson = parseClaudeJsonResult(result.stdout);
     const evidenceUrls = [];
     if (result.killedByLeaseLoss) {

package/dist/git-worktree.cjs

@@ -127,6 +127,28 @@ class GitWorktree {
             await this.runGit(["-C", this.worktreePath, "remote", "add", "origin", this.cloneUrl], false);
         }
     }
+    /**
+     * Resolves the worktree's current branch and commit after an agent turn.
+     *
+     * Agents may check out an existing PR branch or rename the generated session
+     * branch. Completion evidence must follow that live HEAD rather than the
+     * immutable branch name allocated when the worktree was created.
+     */
+    async resolveCurrentHead() {
+        const [branchResult, shaResult] = await Promise.all([
+            this.runGit(["-C", this.worktreePath, "rev-parse", "--abbrev-ref", "HEAD"], false),
+            this.runGit(["-C", this.worktreePath, "rev-parse", "--verify", "HEAD"], false),
+        ]);
+        const branch = branchResult.stdout.trim();
+        const sha = shaResult.stdout.trim();
+        if (!/^[0-9a-f]{40,64}$/i.test(sha)) {
+            throw new Error(`git rev-parse returned an invalid HEAD SHA: ${sha || "<empty>"}`);
+        }
+        return {
+            branch: branch && branch !== "HEAD" ? branch : null,
+            sha,
+        };
+    }
     async cleanup() {
         await withRepositoryLock(this.repositoryPath, async () => {
             await this.runner

package/dist/github-pr.cjs

@@ -22,21 +22,49 @@ async function resolveGitHubToken(options) {
         return undefined;
     }
 }
+function matchingPullRequestUrl(body, repository, matchesHead) {
+    if (!Array.isArray(body)) {
+        throw new Error("GitHub pull request lookup returned a non-array response");
+    }
+    const matches = body.filter((candidate) => {
+        if (!matchesHead(candidate))
+            return false;
+        const headRepository = candidate.head?.repo?.full_name;
+        if (typeof headRepository !== "string")
+            return false;
+        if (headRepository.toLowerCase() !== repository)
+            return false;
+        if (typeof candidate.html_url !== "string")
+            return false;
+        return isPullRequestUrlForRepository(candidate.html_url, repository);
+    });
+    const candidate = matches.find((pullRequest) => pullRequest.state === "open") ?? matches[0];
+    return typeof candidate?.html_url === "string" ? candidate.html_url : null;
+}
+async function fetchPullRequests(url, headers, fetchImpl) {
+    const response = await fetchImpl(url, { headers });
+    if (!response.ok) {
+        throw new Error(`GitHub pull request lookup failed with HTTP ${response.status}`);
+    }
+    return response.json();
+}
 /**
- * Finds the PR opened from this session's exact same-repository head branch.
- * GitHub's head filter narrows the response, and the response is checked again
- * before its URL is trusted so another repository or branch can never be
- * attached as completion evidence.
+ * Finds a same-repository PR for the worktree's current head.
+ *
+ * The exact branch remains the first and cheapest lookup. If an agent checked
+ * out or renamed a branch, the current commit provides a secure fallback:
+ * GitHub must report a PR whose head SHA and head repository exactly match the
+ * local worktree before its URL is accepted as completion evidence.
  */
 async function findHeadBranchPullRequestUrl(options) {
     const [owner, name, ...extra] = options.repository.split("/");
     if (!owner || !name || extra.length > 0) {
         throw new Error(`Invalid GitHub repository name: ${options.repository}`);
     }
-    const url = new URL(`https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/pulls`);
-    url.searchParams.set("state", "all");
-    url.searchParams.set("head", `${owner}:${options.headBranch}`);
-    url.searchParams.set("per_page", "10");
+    const branchUrl = new URL(`https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/pulls`);
+    branchUrl.searchParams.set("state", "all");
+    branchUrl.searchParams.set("head", `${owner}:${options.headBranch}`);
+    branchUrl.searchParams.set("per_page", "10");
     const headers = {
         accept: "application/vnd.github+json",
         "user-agent": "navarch-runtime",
@@ -45,30 +73,22 @@ async function findHeadBranchPullRequestUrl(options) {
     const githubToken = await resolveGitHubToken(options);
     if (githubToken)
         headers.authorization = `Bearer ${githubToken}`;
-    const response = await (options.fetchImpl ?? fetch)(url, { headers });
-    if (!response.ok) {
-        throw new Error(`GitHub pull request lookup failed with HTTP ${response.status}`);
-    }
-    const body = await response.json();
-    if (!Array.isArray(body)) {
-        throw new Error("GitHub pull request lookup returned a non-array response");
-    }
+    const fetchImpl = options.fetchImpl ?? fetch;
     const normalizedRepository = options.repository.toLowerCase();
-    for (const candidate of body) {
-        if (candidate.head?.ref !== options.headBranch)
-            continue;
-        const headRepository = candidate.head.repo?.full_name;
-        if (typeof headRepository !== "string")
-            continue;
-        if (headRepository.toLowerCase() !== normalizedRepository)
-            continue;
-        if (typeof candidate.html_url !== "string")
-            continue;
-        if (!isPullRequestUrlForRepository(candidate.html_url, normalizedRepository))
-            continue;
-        return candidate.html_url;
+    const normalizedHeadSha = options.headSha?.toLowerCase();
+    if (normalizedHeadSha && !/^[0-9a-f]{40,64}$/.test(normalizedHeadSha)) {
+        throw new Error(`Invalid Git head SHA: ${options.headSha}`);
     }
-    return null;
+    const branchMatch = matchingPullRequestUrl(await fetchPullRequests(branchUrl, headers, fetchImpl), normalizedRepository, (candidate) => candidate.head?.ref === options.headBranch &&
+        (!normalizedHeadSha ||
+            (typeof candidate.head.sha === "string" &&
+                candidate.head.sha.toLowerCase() === normalizedHeadSha)));
+    if (branchMatch || !normalizedHeadSha)
+        return branchMatch;
+    const commitUrl = new URL(`https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/commits/${normalizedHeadSha}/pulls`);
+    commitUrl.searchParams.set("per_page", "10");
+    return matchingPullRequestUrl(await fetchPullRequests(commitUrl, headers, fetchImpl), normalizedRepository, (candidate) => typeof candidate.head?.sha === "string" &&
+        candidate.head.sha.toLowerCase() === normalizedHeadSha);
 }
 function isPullRequestUrlForRepository(value, repository) {
     try {

package/dist/heartbeat-loop.cjs

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MachineHeartbeatLoop = void 0;
 const version_cjs_1 = require("./version.cjs");
+const usage_limits_cjs_1 = require("./usage-limits.cjs");
 const logger_cjs_1 = require("./logger.cjs");
 const log = (0, logger_cjs_1.createLogger)("heartbeat");
 /**
@@ -19,6 +20,8 @@ class MachineHeartbeatLoop {
     onResult;
     onHealthy;
     timer = null;
+    heartbeatInFlight = false;
+    heartbeatPending = false;
     updateState = "idle";
     lastUpdateError;
     draining = false;
@@ -41,6 +44,7 @@ class MachineHeartbeatLoop {
         if (this.timer)
             clearInterval(this.timer);
         this.timer = null;
+        this.heartbeatPending = false;
     }
     setUpdateState(state, error) {
         this.updateState = state;
@@ -49,24 +53,48 @@ class MachineHeartbeatLoop {
         void this.tick();
     }
     async tick() {
+        if (this.heartbeatInFlight) {
+            this.heartbeatPending = true;
+            return;
+        }
+        this.heartbeatInFlight = true;
         try {
-            const result = await this.api.machineHeartbeat(this.machineId, {
-                available_capacity: this.draining ? 0 : this.capacity.available(),
-                capabilities: this.config.capabilities,
-                runtime: {
-                    version: version_cjs_1.RUNTIME_VERSION,
-                    updater_protocol: version_cjs_1.UPDATER_PROTOCOL_VERSION,
-                    channel: this.config.updateChannel,
-                    state: this.updateState,
-                    boot_id: this.bootId,
-                    ...(this.lastUpdateError ? { last_update_error: this.lastUpdateError } : {}),
-                },
-            });
-            this.onHealthy?.();
-            this.onResult?.(result);
+            do {
+                this.heartbeatPending = false;
+                try {
+                    // Always sent when collection is enabled, including as an empty array:
+                    // that is how the control plane learns a previously reported quota is
+                    // gone (agent uninstalled, telemetry disabled) instead of pinning a
+                    // reading that no longer exists.
+                    const agentUsage = this.config.reportUsageLimits
+                        ? await (0, usage_limits_cjs_1.collectAgentUsage)({
+                            codexHome: this.config.codexHome,
+                            claudeConfigPath: this.config.claudeConfigPath,
+                        })
+                        : null;
+                    const result = await this.api.machineHeartbeat(this.machineId, {
+                        available_capacity: this.draining ? 0 : this.capacity.available(),
+                        capabilities: this.config.capabilities,
+                        ...(agentUsage ? { agent_usage: agentUsage } : {}),
+                        runtime: {
+                            version: version_cjs_1.RUNTIME_VERSION,
+                            updater_protocol: version_cjs_1.UPDATER_PROTOCOL_VERSION,
+                            channel: this.config.updateChannel,
+                            state: this.updateState,
+                            boot_id: this.bootId,
+                            ...(this.lastUpdateError ? { last_update_error: this.lastUpdateError } : {}),
+                        },
+                    });
+                    this.onHealthy?.();
+                    this.onResult?.(result);
+                }
+                catch (err) {
+                    log.warn(`machine heartbeat failed: ${String(err)}`);
+                }
+            } while (this.heartbeatPending);
         }
-        catch (err) {
-            log.warn(`machine heartbeat failed: ${String(err)}`);
+        finally {
+            this.heartbeatInFlight = false;
         }
     }
 }

package/dist/session.cjs

@@ -259,14 +259,17 @@ async function runSession(deps, claimed, sessionId) {
             });
         }
     }
+    // Kept outside the try so the crash path can report the telemetry this
+    // session actually produced instead of zeroing it.
+    let lastCompletion = null;
     try {
         await gitWorktree.prepare();
         if (sandbox) {
             await sandbox.create();
             await sandbox.injectEnv(toEnvMap(secrets, gitCredentialRefresh, config.gitAuthorName, config.gitAuthorEmail));
         }
-        // The control plane resolves the project default/task override before
-        // claim and returns one of this worker's advertised runtimes.
+        // The control plane returns the agent type selected for this worker.
+        // Any agent type may run any task; capabilities remain the task-level gate.
         // All adapters implement the same AgentAdapter.run() shape
         // (adapters/types.cts), so nothing else in this function branches on
         // which agent is running.
@@ -334,10 +337,22 @@ async function runSession(deps, claimed, sessionId) {
                 ...result,
                 killedByLeaseLoss: leaseLost || result.killedByLeaseLoss,
             });
+            let headBranch = gitWorktree.branch;
+            let headSha;
+            try {
+                const currentHead = await gitWorktree.resolveCurrentHead();
+                headBranch = currentHead.branch ?? headBranch;
+                headSha = currentHead.sha;
+            }
+            catch (err) {
+                // Preserve the original exact-branch lookup if HEAD cannot be read.
+                log.warn(`worktree HEAD lookup failed for ${leaseId}: ${String(err)}`);
+            }
             try {
                 const prUrl = await (0, github_pr_cjs_1.findHeadBranchPullRequestUrl)({
                     repository: bundle.repository?.full_name ?? task.repo,
-                    headBranch: gitWorktree.branch,
+                    headBranch,
+                    headSha,
                     githubToken,
                 });
                 if (prUrl)
@@ -369,7 +384,9 @@ async function runSession(deps, claimed, sessionId) {
                 transcriptUrl = public_url;
             }
             catch (err) {
-                log.warn(`transcript upload failed for ${leaseId}: ${String(err)}`);
+                // The message carries up to 500 chars of the storage response body, so
+                // redact it like every other warn in this block.
+                log.warn(`transcript upload failed for ${leaseId}: ${(0, redact_cjs_1.redactText)(String(err), knownSecrets)}`);
             }
             const completion = {
                 status: mapping.leaseOutcome,
@@ -385,6 +402,12 @@ async function runSession(deps, claimed, sessionId) {
                 agent_type: runtime,
                 ...executionReport,
             };
+            lastCompletion = {
+                report: completion.report,
+                evidence_urls: completion.evidence_urls,
+                cost: completion.cost,
+                transcript_url: completion.transcript_url,
+            };
             try {
                 await api.completeLease(leaseId, completion);
                 break;
@@ -394,38 +417,70 @@ async function runSession(deps, claimed, sessionId) {
                     log.warn(`completion skipped for ${leaseId}: the lease was already released.`);
                     return sessionOutcome;
                 }
-                const rejection = mapping.leaseOutcome === "completed" ? completionRemediationMessage(err) : null;
+                const rejection = completionRejection(err);
                 if (!rejection)
                     throw err;
-                const redactedRejection = (0, redact_cjs_1.redactText)(rejection, knownSecrets);
-                if (completionRemediationRetries < COMPLETION_REMEDIATION_RETRIES) {
+                const redactedRejection = (0, redact_cjs_1.redactText)(rejection.message, knownSecrets);
+                const remediable = mapping.leaseOutcome === "completed" && rejection.remediable;
+                if (remediable && completionRemediationRetries < COMPLETION_REMEDIATION_RETRIES) {
                     completionRemediationRetries += 1;
                     log.warn(`completion for ${leaseId} needs more work; restarting agent turn ${completionRemediationRetries}/${COMPLETION_REMEDIATION_RETRIES} in the same worktree.`);
                     nextPrompt = redactedRejection;
                     continue;
                 }
-                log.warn(`completion for ${leaseId} is still not ready after ${COMPLETION_REMEDIATION_RETRIES} retries; failing with the control-plane rejection.`);
-                await api.completeLease(leaseId, {
-                    ...completion,
-                    status: "failed",
-                    report: redactedRejection,
-                    failure_summary: redactedRejection,
-                    exit_status: "failed",
-                });
+                if (remediable) {
+                    log.warn(`completion for ${leaseId} is still not ready after ${COMPLETION_REMEDIATION_RETRIES} retries; failing with the control-plane rejection.`);
+                }
+                else {
+                    // Not something another turn can fix (e.g. review_evidence_tampered).
+                    // Fail the lease once, keeping this attempt's real report, cost and
+                    // evidence — this is a rejected attempt, not a crashed session.
+                    log.error(`completion for ${leaseId} was rejected as ${rejection.code}, which is not remediable; failing the lease.`);
+                }
+                try {
+                    await api.completeLease(leaseId, {
+                        ...completion,
+                        status: "failed",
+                        report: remediable
+                            ? redactedRejection
+                            : `${redactedRejection}\n\n---\n\n${completion.report}`,
+                        failure_summary: redactedRejection,
+                        exit_status: "failed",
+                    });
+                }
+                catch (fallbackErr) {
+                    // Same race as the primary completion above: if something else released
+                    // the lease first, this is a clean exit, not a crash. Letting it escape
+                    // would post a second `Session crashed:` completion with zeroed cost.
+                    if (!isAlreadyReleasedCompletionError(fallbackErr))
+                        throw fallbackErr;
+                    log.warn(`fallback completion skipped for ${leaseId}: the lease was already released.`);
+                    return sessionOutcome;
+                }
                 break;
             }
         }
     }
     catch (err) {
-        log.error(`session ${leaseId} threw before completing: ${String(err)}`);
-        const failureSummary = (0, redact_cjs_1.redactText)(`Session crashed: ${String(err)}`, registry.list());
+        const knownSecrets = registry.list();
+        // NavarchApiError's message is only the status line; the control plane's
+        // explanation rides in `err.body`. Keep it in the agent log (redacted like
+        // every other body we surface) so a 4xx/5xx completion stays diagnosable.
+        const crashDetail = (0, redact_cjs_1.redactText)(describeCompletionError(err), knownSecrets);
+        log.error(`session ${leaseId} threw before completing: ${crashDetail}`);
+        const failureSummary = (0, redact_cjs_1.redactText)(`Session crashed: ${String(err)}`, knownSecrets);
         await api
             .completeLease(leaseId, {
             status: "failed",
-            report: failureSummary,
+            report: lastCompletion
+                ? `${lastCompletion.report}\n\n---\n\n${failureSummary}`
+                : failureSummary,
             failure_summary: failureSummary,
-            evidence_urls: [],
-            cost: { tokens_in: 0, tokens_out: 0, cost_usd: 0 },
+            evidence_urls: lastCompletion?.evidence_urls ?? [],
+            cost: lastCompletion?.cost ?? { tokens_in: 0, tokens_out: 0, cost_usd: 0 },
+            ...(lastCompletion?.transcript_url
+                ? { transcript_url: lastCompletion.transcript_url }
+                : {}),
             exit_status: "crashed",
             agent_type: runtime,
             ...executionReport,
@@ -460,27 +515,100 @@ function sumReportedUsage(attempts, key) {
     });
     return reported.length > 0 ? reported.reduce((sum, value) => sum + value, 0) : undefined;
 }
-function completionRemediationMessage(err) {
+/** Rejection codes another agent turn in the same worktree can plausibly fix. */
+const REMEDIABLE_REJECTION_CODES = new Set([
+    "pr_required",
+    "pr_not_ready",
+    "review_attestation_required",
+    "review_attestation_invalid",
+    "review_head_changed",
+    "review_evidence_missing",
+    // The marker is already on the right head; the reviewer only has to relabel
+    // the body, which is exactly what a remediation turn can do.
+    "review_evidence_mislabeled",
+]);
+/**
+ * A 409 the control plane raised to reject *this* completion's contents (as
+ * opposed to a lease that is simply gone). Non-remediable codes still describe
+ * a failed attempt, not a crashed session, so the caller fails the lease once
+ * rather than routing the error through the crash path.
+ */
+function completionRejection(err) {
     if (!(err instanceof api_cjs_1.NavarchApiError) || err.status !== 409)
         return null;
-    if (typeof err.body !== "object" || err.body === null || Array.isArray(err.body))
-        return null;
-    const body = err.body;
-    return (body.code === "pr_required" || body.code === "pr_not_ready") &&
-        typeof body.error === "string"
-        ? body.error
-        : null;
+    if (typeof err.body === "object" && err.body !== null && !Array.isArray(err.body)) {
+        const body = err.body;
+        if (typeof body.code === "string" && typeof body.error === "string") {
+            return {
+                code: body.code,
+                message: body.error,
+                remediable: REMEDIABLE_REJECTION_CODES.has(body.code),
+            };
+        }
+    }
+    // A 409 whose body the runtime cannot interpret — an edge/proxy error page,
+    // an HTML body, a truncated response (api.cts hands the raw text through when
+    // safeJsonParse fails). The lease is still rejected, so fail it once with this
+    // attempt's real report/cost/evidence rather than crashing the session and
+    // posting a zeroed-cost `Session crashed:` completion. Callers check
+    // isAlreadyReleasedCompletionError first, so the benign race never lands here.
+    return {
+        code: UNRECOGNIZED_REJECTION_CODE,
+        message: "The control plane rejected this completion with HTTP 409, but the response body " +
+            `was not a recognizable rejection: ${describeResponseBody(err.body)}`,
+        remediable: false,
+    };
+}
+/** Synthetic code for a 409 that carried no machine-readable `{error, code}` pair. */
+const UNRECOGNIZED_REJECTION_CODE = "unrecognized_completion_rejection";
+const MAX_DESCRIBED_BODY_CHARS = 500;
+/** Collapses an arbitrary error-response body into one bounded, loggable line. */
+function describeResponseBody(body) {
+    let text;
+    if (body === null || body === undefined) {
+        text = "";
+    }
+    else if (typeof body === "string") {
+        text = body;
+    }
+    else {
+        try {
+            text = JSON.stringify(body) ?? String(body);
+        }
+        catch {
+            text = String(body);
+        }
+    }
+    const collapsed = text.replace(/\s+/g, " ").trim();
+    if (collapsed.length === 0)
+        return "<empty>";
+    return collapsed.length > MAX_DESCRIBED_BODY_CHARS
+        ? `${collapsed.slice(0, MAX_DESCRIBED_BODY_CHARS)}…`
+        : collapsed;
+}
+/** Error text for the crash log, including a NavarchApiError's response body. */
+function describeCompletionError(err) {
+    if (!(err instanceof api_cjs_1.NavarchApiError))
+        return String(err);
+    return `${String(err)} (body: ${describeResponseBody(err.body)})`;
 }
 function isTerminalLeaseHeartbeatError(err) {
     return err instanceof api_cjs_1.NavarchApiError && [403, 404, 410].includes(err.status);
 }
+/**
+ * A 409 that means "someone already released this lease" — a benign race, not
+ * work to remediate. The control plane tags it `code: "already_released"`
+ * (app/api/dispatch/[leaseId]/complete/route.ts); the prose form is what
+ * control planes before that shipped, and is kept so a new runtime still
+ * recognizes an older deployment.
+ */
 function isAlreadyReleasedCompletionError(err) {
     if (!(err instanceof api_cjs_1.NavarchApiError) || err.status !== 409)
         return false;
     if (typeof err.body !== "object" || err.body === null || Array.isArray(err.body))
         return false;
     const body = err.body;
-    return body.error === "lease already released";
+    return body.code === "already_released" || body.error === "lease already released";
 }
 /** Uppercases + sanitizes secret names into shell-safe env var names for injectEnv(). */
 function toEnvMap(secrets, credentialRefreshOrAuthorName, gitAuthorNameOrEmail = "sagentlab", gitAuthorEmail = "z@sagentlab.com") {

package/dist/upload.cjs

@@ -7,6 +7,8 @@ exports.uploadTranscript = uploadTranscript;
  * implementation-plan.md WP-07). Kept as its own module so the storage
  * mechanism is a one-function swap if it ever changes.
  */
+/** Storage error bodies are small JSON blobs; cap in case we get an HTML page. */
+const MAX_ERROR_BODY = 500;
 async function uploadTranscript(uploadUrl, content, fetchImpl = fetch) {
     const response = await fetchImpl(uploadUrl, {
         method: "PUT",
@@ -14,6 +16,21 @@ async function uploadTranscript(uploadUrl, content, fetchImpl = fetch) {
         body: content,
     });
     if (!response.ok) {
-        throw new Error(`Transcript upload failed with ${response.status}`);
+        // Supabase Storage answers with {statusCode, error, message} here, which is
+        // the only thing distinguishing an RLS rejection from a bad/expired token
+        // from a bucket misconfiguration. Without it a 403 is unattributable.
+        throw new Error(`Transcript upload failed with ${response.status}: ${await readErrorBody(response)}`);
     }
 }
+async function readErrorBody(response) {
+    let body;
+    try {
+        body = (await response.text()).trim();
+    }
+    catch (err) {
+        return `<unreadable response body: ${String(err)}>`;
+    }
+    if (!body)
+        return "<empty response body>";
+    return body.length > MAX_ERROR_BODY ? `${body.slice(0, MAX_ERROR_BODY)}…` : body;
+}

package/dist/usage-limits.cjs

@@ -0,0 +1,400 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyWindow = classifyWindow;
+exports.parseCodexRateLimitSnapshot = parseCodexRateLimitSnapshot;
+exports.findLatestCodexSnapshot = findLatestCodexSnapshot;
+exports.collectCodexUsage = collectCodexUsage;
+exports.parseClaudeUsageCache = parseClaudeUsageCache;
+exports.collectClaudeUsage = collectClaudeUsage;
+exports.collectAgentUsage = collectAgentUsage;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const logger_cjs_1 = require("./logger.cjs");
+const log = (0, logger_cjs_1.createLogger)("usage-limits");
+/**
+ * Reads the usage-limit telemetry that coding agents already write to disk on
+ * this machine and normalizes it for the machine heartbeat (see
+ * heartbeat-loop.cts).
+ *
+ * Ground rules, because this reads files an agent wrote for its own use:
+ *
+ * - Only provider-emitted quota numbers are collected. Credentials, prompts,
+ *   transcripts and token counts that sit next to them in the same files are
+ *   never read out, and the report is rebuilt field by field rather than
+ *   forwarded, so nothing unrecognized can ride along.
+ * - Every field is optional and version-sensitive. A value we cannot verify is
+ *   dropped, never guessed: a missing window is reported as absent so the UI
+ *   can say "not reported" instead of inventing a quota.
+ * - Collection is best-effort and must never break a heartbeat. Every failure
+ *   path returns an empty report.
+ */
+/** Cap on windows kept per provider — Codex reports 2, Claude Code 2. */
+const MAX_WINDOWS_PER_PROVIDER = 6;
+/** Tail of a rollout file we are willing to read; snapshots are appended. */
+const ROLLOUT_TAIL_BYTES = 256 * 1024;
+/** Newest rollout files to scan before giving up on finding a snapshot. */
+const MAX_ROLLOUT_CANDIDATES = 5;
+/** Ceiling on rollout paths collected while walking the sessions tree. */
+const MAX_ROLLOUT_SCAN = 200;
+/** Largest `.claude.json` we will parse. The file also holds unrelated state. */
+const MAX_CLAUDE_CONFIG_BYTES = 8 * 1024 * 1024;
+/**
+ * Window durations Codex's own TUI recognizes, with the same ±5% tolerance it
+ * uses (codex-rs/tui/src/chatwidget/rate_limits.rs). Neither provider promises
+ * that `primary` is the short window, so the label is always derived from the
+ * reported duration rather than the slot it arrived in.
+ */
+const WINDOW_KINDS = [
+    [300, "5h"],
+    [1440, "daily"],
+    [10080, "weekly"],
+    [43200, "monthly"],
+    [525600, "annual"],
+];
+function classifyWindow(windowMinutes) {
+    if (windowMinutes === null)
+        return "unknown";
+    for (const [expected, kind] of WINDOW_KINDS) {
+        if (windowMinutes >= expected * 0.95 && windowMinutes <= expected * 1.05)
+            return kind;
+    }
+    return "unknown";
+}
+/**
+ * Percentages are contract-bounded to 0-100. An out-of-range number means we
+ * misread the provider's scale, so the window is dropped rather than clamped —
+ * clamping 4200 to 100 would render as a confident "quota exhausted".
+ */
+function normalizeUsedPercent(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return null;
+    if (value < 0 || value > 100)
+        return null;
+    return Math.round(value * 10) / 10;
+}
+/** Positive whole minutes, capped at ten years to reject nonsense durations. */
+function normalizeWindowMinutes(value) {
+    if (typeof value !== "number" || !Number.isInteger(value))
+        return null;
+    if (value <= 0 || value > 5_256_000)
+        return null;
+    return value;
+}
+/** Rejects reset instants outside [2020, now + 2y] as unparseable rather than real. */
+function isoFromEpochMs(ms, nowMs) {
+    if (!Number.isFinite(ms))
+        return null;
+    if (ms < Date.UTC(2020, 0, 1))
+        return null;
+    if (ms > nowMs + 2 * 365 * 24 * 60 * 60 * 1000)
+        return null;
+    return new Date(ms).toISOString();
+}
+function isoFromEpochSeconds(value, nowMs) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return null;
+    return isoFromEpochMs(Math.round(value * 1000), nowMs);
+}
+/** Codex ≤ v0.47 reported a duration relative to the emitting event. */
+function isoFromRelativeSeconds(value, observedAtMs, nowMs) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+        return null;
+    return isoFromEpochMs(observedAtMs + Math.round(value * 1000), nowMs);
+}
+function isoFromString(value, nowMs) {
+    if (typeof value !== "string" || !value.trim())
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isNaN(parsed) ? null : isoFromEpochMs(parsed, nowMs);
+}
+function buildWindow(usedPercent, windowMinutes, resetsAt) {
+    if (usedPercent === null)
+        return null;
+    return {
+        kind: classifyWindow(windowMinutes),
+        window_minutes: windowMinutes,
+        used_percent: usedPercent,
+        resets_at: resetsAt,
+    };
+}
+// --------------------------------------------------------------------------
+// Codex — session rollout JSONL
+// --------------------------------------------------------------------------
+/**
+ * Parses one Codex `RateLimitSnapshot`. Field names are stable across the
+ * versions we support (`used_percent`, `window_minutes`); `resets_at` (epoch
+ * seconds) replaced `resets_in_seconds` in Codex v0.48, so both are accepted.
+ * Everything else in the snapshot — plan type, credit balance, spend controls —
+ * is deliberately ignored.
+ */
+function parseCodexRateLimitSnapshot(snapshot, observedAtMs, nowMs) {
+    if (!snapshot || typeof snapshot !== "object")
+        return [];
+    const raw = snapshot;
+    const windows = [];
+    for (const slot of ["primary", "secondary"]) {
+        const value = raw[slot];
+        if (!value || typeof value !== "object")
+            continue;
+        const win = value;
+        const parsed = buildWindow(normalizeUsedPercent(win.used_percent), normalizeWindowMinutes(win.window_minutes), isoFromEpochSeconds(win.resets_at, nowMs) ??
+            isoFromRelativeSeconds(win.resets_in_seconds, observedAtMs, nowMs));
+        if (parsed)
+            windows.push(parsed);
+    }
+    return windows.slice(0, MAX_WINDOWS_PER_PROVIDER);
+}
+/**
+ * Scans a rollout JSONL tail backwards for the newest `token_count` event that
+ * carries a rate-limit snapshot. Codex appends these throughout a session, so
+ * the last one is the freshest quota reading this machine has seen.
+ */
+function findLatestCodexSnapshot(jsonl) {
+    const lines = jsonl.split("\n");
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i]?.trim() ?? "";
+        // Cheap reject before paying for JSON.parse on every transcript line.
+        if (!line || !line.includes("\"token_count\"") || !line.includes("\"rate_limits\""))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!parsed || typeof parsed !== "object")
+            continue;
+        const entry = parsed;
+        if (entry.type !== "event_msg")
+            continue;
+        const payload = entry.payload;
+        if (!payload || typeof payload !== "object")
+            continue;
+        const event = payload;
+        if (event.type !== "token_count")
+            continue;
+        if (!event.rate_limits || typeof event.rate_limits !== "object")
+            continue;
+        const timestamp = typeof entry.timestamp === "string" ? Date.parse(entry.timestamp) : Number.NaN;
+        return {
+            snapshot: event.rate_limits,
+            observedAtMs: Number.isNaN(timestamp) ? null : timestamp,
+        };
+    }
+    return null;
+}
+async function listSortedDirs(dir, limit) {
+    const entries = await node_fs_1.promises.readdir(dir, { withFileTypes: true }).catch(() => []);
+    return entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort()
+        .reverse()
+        .slice(0, limit);
+}
+/**
+ * Collects rollout paths from the newest `sessions/YYYY/MM/DD` directories.
+ * Names are zero-padded, so lexical order is chronological order; two branches
+ * per level covers a month or year boundary crossed mid-session.
+ */
+async function recentRolloutFiles(sessionsDir) {
+    const files = [];
+    for (const year of await listSortedDirs(sessionsDir, 2)) {
+        for (const month of await listSortedDirs(node_path_1.default.join(sessionsDir, year), 2)) {
+            for (const day of await listSortedDirs(node_path_1.default.join(sessionsDir, year, month), 2)) {
+                const dayDir = node_path_1.default.join(sessionsDir, year, month, day);
+                const entries = await node_fs_1.promises.readdir(dayDir, { withFileTypes: true }).catch(() => []);
+                for (const entry of entries) {
+                    // Cold rollouts are rewritten as `.jsonl.zst`; the newest session —
+                    // the only one with a current quota reading — is never compressed.
+                    if (entry.isFile() && entry.name.startsWith("rollout-") && entry.name.endsWith(".jsonl")) {
+                        files.push(node_path_1.default.join(dayDir, entry.name));
+                    }
+                }
+                if (files.length >= MAX_ROLLOUT_SCAN)
+                    return files;
+            }
+        }
+    }
+    return files;
+}
+/** Reads the last `maxBytes` of a file, discarding a leading partial line. */
+async function readTail(file, maxBytes) {
+    const handle = await node_fs_1.promises.open(file, "r");
+    try {
+        const { size } = await handle.stat();
+        const start = size > maxBytes ? size - maxBytes : 0;
+        const length = size - start;
+        if (length <= 0)
+            return "";
+        const buffer = Buffer.alloc(length);
+        await handle.read(buffer, 0, length, start);
+        const text = buffer.toString("utf8");
+        if (start === 0)
+            return text;
+        const firstBreak = text.indexOf("\n");
+        return firstBreak === -1 ? "" : text.slice(firstBreak + 1);
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function collectCodexUsage(options) {
+    const nowMs = (options.now ?? Date.now)();
+    const sessionsDir = node_path_1.default.join(options.codexHome, "sessions");
+    const candidates = await recentRolloutFiles(sessionsDir);
+    if (candidates.length === 0)
+        return null;
+    const stated = await Promise.all(candidates.map(async (file) => {
+        const stat = await node_fs_1.promises.stat(file).catch(() => null);
+        return stat ? { file, mtimeMs: stat.mtimeMs } : null;
+    }));
+    const newest = stated
+        .filter((entry) => entry !== null)
+        .sort((a, b) => b.mtimeMs - a.mtimeMs)
+        .slice(0, MAX_ROLLOUT_CANDIDATES);
+    for (const { file, mtimeMs } of newest) {
+        const tail = await readTail(file, ROLLOUT_TAIL_BYTES).catch(() => "");
+        if (!tail)
+            continue;
+        const found = findLatestCodexSnapshot(tail);
+        if (!found)
+            continue;
+        const observedAtMs = found.observedAtMs ?? mtimeMs;
+        const windows = parseCodexRateLimitSnapshot(found.snapshot, observedAtMs, nowMs);
+        if (windows.length === 0)
+            continue;
+        const observedAt = isoFromEpochMs(observedAtMs, nowMs);
+        if (!observedAt)
+            continue;
+        return { provider: "codex", source: "codex-rollout", observed_at: observedAt, windows };
+    }
+    return null;
+}
+// --------------------------------------------------------------------------
+// Claude Code — cached utilization in the global config
+// --------------------------------------------------------------------------
+/**
+ * Claude Code's five-hour and weekly windows reach disk only through
+ * `cachedUsageUtilization` in its global config, which it refreshes when a
+ * human runs `/usage` on this machine. Headless `claude -p` sessions — the ones
+ * the runtime dispatches — never write it, so an absent or stale reading is the
+ * normal case and is reported as such rather than back-filled from token counts.
+ *
+ * On this path `utilization` is a percentage (0-100) and `resets_at` an ISO
+ * string. Claude Code keeps a *second*, header-derived store in different units
+ * — a 0-1 fraction with an epoch-seconds reset — which it exposes to statusline
+ * scripts. Reading one as the other silently misreports usage by 100×, so a
+ * numeric `resets_at` is taken as proof we are looking at the wrong shape and
+ * the window is discarded rather than converted on a guess.
+ */
+function parseClaudeUsageCache(value, nowMs) {
+    if (!value || typeof value !== "object")
+        return null;
+    const cache = value;
+    const fetchedAtMs = cache.fetchedAtMs;
+    if (typeof fetchedAtMs !== "number" || !Number.isFinite(fetchedAtMs))
+        return null;
+    // A reading from the future is a broken clock, not a fresh observation.
+    if (fetchedAtMs > nowMs + 5 * 60 * 1000)
+        return null;
+    if (!isoFromEpochMs(fetchedAtMs, nowMs))
+        return null;
+    const utilization = cache.utilization;
+    if (!utilization || typeof utilization !== "object")
+        return null;
+    const byWindow = utilization;
+    const windows = [];
+    for (const [key, windowMinutes] of [
+        ["five_hour", 300],
+        ["seven_day", 10080],
+    ]) {
+        const entry = byWindow[key];
+        if (!entry || typeof entry !== "object")
+            continue;
+        const raw = entry;
+        if (typeof raw.resets_at === "number")
+            continue;
+        const parsed = buildWindow(normalizeUsedPercent(raw.utilization), windowMinutes, isoFromString(raw.resets_at, nowMs));
+        if (parsed)
+            windows.push(parsed);
+    }
+    if (windows.length === 0)
+        return null;
+    return { observedAtMs: fetchedAtMs, windows: windows.slice(0, MAX_WINDOWS_PER_PROVIDER) };
+}
+async function collectClaudeUsage(options) {
+    const nowMs = (options.now ?? Date.now)();
+    const stat = await node_fs_1.promises.stat(options.configPath).catch(() => null);
+    if (!stat || !stat.isFile() || stat.size > MAX_CLAUDE_CONFIG_BYTES)
+        return null;
+    const raw = await node_fs_1.promises.readFile(options.configPath, "utf8").catch(() => null);
+    if (!raw)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const found = parseClaudeUsageCache(parsed.cachedUsageUtilization, nowMs);
+    if (!found)
+        return null;
+    const observedAt = isoFromEpochMs(found.observedAtMs, nowMs);
+    if (!observedAt)
+        return null;
+    return {
+        provider: "claude-code",
+        source: "claude-usage-cache",
+        observed_at: observedAt,
+        windows: found.windows,
+    };
+}
+const DEFAULT_COLLECT_TIMEOUT_MS = 5_000;
+/**
+ * Gathers every provider report available on this machine. Providers are read
+ * independently so one unreadable or malformed source cannot suppress another,
+ * and any thrown error degrades to "no report" rather than failing the caller.
+ */
+async function collectAgentUsage(options) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_COLLECT_TIMEOUT_MS;
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(null), timeoutMs);
+        // Never hold the process open on account of usage collection.
+        timer.unref?.();
+    });
+    try {
+        const collection = Promise.allSettled([
+            collectCodexUsage({ codexHome: options.codexHome, now: options.now }),
+            collectClaudeUsage({ configPath: options.claudeConfigPath, now: options.now }),
+        ]);
+        const settled = await Promise.race([collection, deadline]);
+        if (!settled) {
+            log.warn(`usage collection timed out after ${timeoutMs}ms`);
+            return [];
+        }
+        const reports = [];
+        for (const result of settled) {
+            if (result.status === "fulfilled") {
+                if (result.value)
+                    reports.push(result.value);
+            }
+            else {
+                log.warn(`usage collection failed: ${String(result.reason)}`);
+            }
+        }
+        return reports;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.14",
+  "version": "0.1.17",
   "description": "Navarch machine-side session manager: claims delivery tasks and runs them through Claude Code, Codex, or Gemini CLI.",
   "type": "commonjs",
   "license": "MIT",