@sagentlab/navarch-runtime 0.1.9 → 0.1.11

package/dist/adapters/codex.cjs

@@ -136,7 +136,11 @@ function tomlKey(value) {
 function safeEnvSegment(value) {
     return value.toUpperCase().replace(/[^A-Z0-9_]/g, "_");
 }
-/** Parses stdout for `codex exec --json` usage/final-message events and folds them onto the raw result (best-effort; leaves tokensIn/tokensOut/costUsd/reportText unset when nothing parses — see exit-conditions.cts#parseCodexJsonEvents). */
+/**
+ * Parses stdout for `codex exec --json` usage/final-message events and folds
+ * them onto the raw result. Codex currently reports token counts but no USD
+ * cost, so costUsd remains absent unless the stream explicitly provides one.
+ */
 function attachUsage(result) {
     const events = (0, exit_conditions_cjs_1.parseCodexJsonEvents)(result.stdout);
     if (events.length === 0)
@@ -147,7 +151,7 @@ function attachUsage(result) {
         ...result,
         tokensIn: usage.tokensIn,
         tokensOut: usage.tokensOut,
-        costUsd: usage.costUsd,
+        ...(usage.costUsd !== undefined ? { costUsd: usage.costUsd } : {}),
         ...(reportText !== undefined ? { reportText } : {}),
     };
 }

package/dist/api.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NavarchApiClient = exports.NavarchApiError = void 0;
+exports.NavarchApiClient = exports.NavarchTransportError = exports.NavarchApiError = void 0;
 class NavarchApiError extends Error {
     status;
     body;
@@ -12,6 +12,18 @@ class NavarchApiError extends Error {
     }
 }
 exports.NavarchApiError = NavarchApiError;
+/** A request that failed before the control plane returned an HTTP response. */
+class NavarchTransportError extends Error {
+    method;
+    endpoint;
+    constructor(method, endpoint, cause) {
+        super(`Navarch API ${method} ${endpoint} transport failed: ${describeError(cause)}`, { cause });
+        this.method = method;
+        this.endpoint = endpoint;
+        this.name = "NavarchTransportError";
+    }
+}
+exports.NavarchTransportError = NavarchTransportError;
 /**
  * Typed client for the Navarch control-plane API surface WP-07 depends on:
  * dispatch/claim, per-lease heartbeat, complete, and broker/issue
@@ -44,11 +56,20 @@ class NavarchApiClient {
             }
             headers.authorization = `Bearer ${this.token}`;
         }
-        const response = await this.fetchImpl(`${this.baseUrl}${pathname}`, {
-            method,
-            headers,
-            body: body === undefined ? undefined : JSON.stringify(body),
-        });
+        const requestUrl = `${this.baseUrl}${pathname}`;
+        let response;
+        try {
+            response = await this.fetchImpl(requestUrl, {
+                method,
+                headers,
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            // Include enough request/cause context to diagnose DNS, connection, and
+            // TLS 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();
@@ -133,3 +154,25 @@ function safeJsonParse(text) {
         return null;
     }
 }
+function safeEndpoint(requestUrl, pathname) {
+    try {
+        const parsed = new URL(requestUrl);
+        return `${parsed.origin}${parsed.pathname}`;
+    }
+    catch {
+        return pathname;
+    }
+}
+function describeError(err) {
+    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)}`;
+    }
+    return detail;
+}

package/dist/claim-loop.cjs

@@ -5,6 +5,7 @@ const node_crypto_1 = require("node:crypto");
 const api_cjs_1 = require("./api.cjs");
 const logger_cjs_1 = require("./logger.cjs");
 const log = (0, logger_cjs_1.createLogger)("claim");
+const MAX_CLAIM_BACKOFF_MS = 60_000;
 /**
  * Polls dispatch/claim on an interval, gated by available capacity
  * (implementation-plan.md WP-07 "Claim loop: poll dispatch, receive context
@@ -20,6 +21,8 @@ class ClaimLoop {
     timer = null;
     stopped = false;
     claimInFlight = false;
+    consecutiveFailures = 0;
+    nextClaimAt = 0;
     quiescenceWaiters = new Set();
     constructor(api, config, capacity, runSession) {
         this.api = api;
@@ -31,6 +34,8 @@ class ClaimLoop {
         if (this.timer)
             return;
         this.stopped = false;
+        this.consecutiveFailures = 0;
+        this.nextClaimAt = 0;
         this.timer = setInterval(() => void this.tick(), this.config.pollIntervalMs);
     }
     stop() {
@@ -52,7 +57,10 @@ class ClaimLoop {
         await new Promise((resolve) => this.quiescenceWaiters.add(resolve));
     }
     async tick() {
-        if (this.stopped || this.claimInFlight || !this.capacity.hasCapacity())
+        if (this.stopped ||
+            this.claimInFlight ||
+            !this.capacity.hasCapacity() ||
+            Date.now() < this.nextClaimAt)
             return;
         this.claimInFlight = true;
         try {
@@ -66,6 +74,11 @@ class ClaimLoop {
                 agent_type: this.config.agentType,
                 session_id: sessionId,
             });
+            if (this.consecutiveFailures > 0) {
+                log.info(`claim polling recovered after ${this.consecutiveFailures} failed attempt(s)`);
+            }
+            this.consecutiveFailures = 0;
+            this.nextClaimAt = 0;
             if (!claimed)
                 return;
             this.capacity.acquire(claimed.lease_id);
@@ -75,16 +88,20 @@ class ClaimLoop {
                 .finally(() => this.capacity.release(claimed.lease_id));
         }
         catch (err) {
+            this.consecutiveFailures += 1;
+            const retryDelayMs = Math.min(MAX_CLAIM_BACKOFF_MS, this.config.pollIntervalMs * 2 ** this.consecutiveFailures);
+            this.nextClaimAt = Date.now() + retryDelayMs;
             // NavarchApiError's message is only the status line ("… failed with
             // 500"); the control plane's actual error text lives in `.body`. Log it
             // so a server-side claim failure is diagnosable from the runtime alone
             // instead of an opaque bare status.
             if (err instanceof api_cjs_1.NavarchApiError) {
                 const detail = typeof err.body === "string" ? err.body : JSON.stringify(err.body);
-                log.warn(`claim failed: ${err.message}${detail ? ` — ${detail}` : ""}`);
+                log.warn(`claim failed (attempt ${this.consecutiveFailures}; retrying in ${retryDelayMs}ms): ` +
+                    `${err.message}${detail ? ` — ${detail}` : ""}`);
             }
             else {
-                log.warn(`claim failed: ${String(err)}`);
+                log.warn(`claim failed (attempt ${this.consecutiveFailures}; retrying in ${retryDelayMs}ms): ${String(err)}`);
             }
         }
         finally {

package/dist/cli.cjs

@@ -19,6 +19,19 @@ const update_coordinator_cjs_1 = require("./update-coordinator.cjs");
 const supervisor_cjs_1 = require("./supervisor.cjs");
 const log = (0, logger_cjs_1.createLogger)("cli");
 const PACKAGE_NAME = "@sagentlab/navarch-runtime";
+/** Include a control-plane response's safe error detail in top-level CLI failures. */
+function describeCliError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (!err || typeof err !== "object" || !("body" in err))
+        return message;
+    const body = err.body;
+    const detail = body && typeof body === "object" && "error" in body && typeof body.error === "string"
+        ? body.error
+        : typeof body === "string"
+            ? body
+            : undefined;
+    return detail && !message.includes(detail) ? `${message}: ${detail}` : message;
+}
 /**
  * How to tell the user to re-invoke this CLI, matching however THEY launched
  * it. The bare `navarch-runtime` bin only exists on PATH after a global install
@@ -305,7 +318,7 @@ async function main(argv = process.argv.slice(2)) {
         }
     }
     catch (err) {
-        log.error(err instanceof Error ? err.message : String(err));
+        log.error(describeCliError(err));
         process.exitCode = 1;
     }
 }

package/dist/exit-conditions.cjs

@@ -95,7 +95,7 @@ function parseCodexJsonEvents(stdout) {
 function extractUsageFromCodexEvents(events) {
     let tokensIn = 0;
     let tokensOut = 0;
-    let costUsd = 0;
+    let costUsd;
     for (const event of events) {
         if (event.type === "turn.completed" && event.usage) {
             tokensIn = event.usage.input_tokens ?? 0;
@@ -104,8 +104,22 @@ function extractUsageFromCodexEvents(events) {
                 costUsd = event.usage.total_cost_usd;
         }
         if (event.msg?.type === "token_count") {
-            tokensIn = (event.msg.input_tokens ?? 0) + (event.msg.cached_input_tokens ?? 0);
-            tokensOut = event.msg.output_tokens ?? 0;
+            const nested = event.msg.info?.total_token_usage;
+            tokensIn = nested
+                ? (nested.input_tokens ?? 0)
+                : (event.msg.input_tokens ?? 0) + (event.msg.cached_input_tokens ?? 0);
+            tokensOut = nested?.output_tokens ?? event.msg.output_tokens ?? 0;
+            if (typeof nested?.total_cost_usd === "number")
+                costUsd = nested.total_cost_usd;
+        }
+        if (event.type === "event_msg" && event.payload?.type === "token_count") {
+            const total = event.payload.info?.total_token_usage;
+            if (total) {
+                tokensIn = total.input_tokens ?? 0;
+                tokensOut = total.output_tokens ?? 0;
+                if (typeof total.total_cost_usd === "number")
+                    costUsd = total.total_cost_usd;
+            }
         }
         if (typeof event.msg?.total_cost_usd === "number") {
             costUsd = event.msg.total_cost_usd;

package/dist/session.cjs

@@ -7,6 +7,7 @@ exports.runSession = runSession;
 exports.toEnvMap = toEnvMap;
 const node_path_1 = __importDefault(require("node:path"));
 const node_fs_1 = require("node:fs");
+const api_cjs_1 = require("./api.cjs");
 const sandbox_cjs_1 = require("./sandbox.cjs");
 const index_cjs_1 = require("./adapters/index.cjs");
 const exit_conditions_cjs_1 = require("./exit-conditions.cjs");
@@ -21,6 +22,7 @@ const worktree_guard_cjs_1 = require("./worktree-guard.cjs");
 /** Filename the generated platform MCP config is written under inside the session metadata directory. */
 const MCP_CONFIG_FILENAME = "mcp-config.json";
 const GIT_CREDENTIAL_HELPER_FILENAME = "git-credential-navarch.cjs";
+const PR_REQUIRED_COMPLETION_RETRIES = 2;
 const log = (0, logger_cjs_1.createLogger)("session");
 /**
  * Runs one claimed task end to end (implementation-plan.md WP-07):
@@ -250,7 +252,8 @@ async function runSession(deps, claimed, sessionId) {
         const bin = config.agentType === "codex" ? config.codexBin : config.claudeBin;
         const extraArgs = config.agentType === "codex" ? config.codexExtraArgs : config.claudeExtraArgs;
         const attempts = [];
-        let result;
+        let nextPrompt = null;
+        let prRequiredCompletionRetries = 0;
         while (true) {
             // Guidance can arrive while the worktree/sandbox is being prepared.
             // It is already included in deliveredGuidance, so clear the pending
@@ -259,9 +262,11 @@ async function runSession(deps, claimed, sessionId) {
             activeAbortController = new AbortController();
             if (leaseLost)
                 activeAbortController.abort();
-            const runPrompt = deliveredGuidance.length > (bundle.guidance?.length ?? 0)
-                ? (0, prompt_cjs_1.renderGuidanceCorrectionPrompt)(promptText, deliveredGuidance)
-                : promptText;
+            const runPrompt = nextPrompt ??
+                (deliveredGuidance.length > (bundle.guidance?.length ?? 0)
+                    ? (0, prompt_cjs_1.renderGuidanceCorrectionPrompt)(promptText, deliveredGuidance)
+                    : promptText);
+            nextPrompt = null;
             await node_fs_1.promises.writeFile(node_path_1.default.join(workDir, "prompt.md"), runPrompt, "utf8");
             const turnResult = await adapter.run({
                 prompt: runPrompt,
@@ -286,66 +291,93 @@ async function runSession(deps, claimed, sessionId) {
             await pollLease();
             if (!leaseLost && pendingGuidance.length > 0)
                 continue;
-            result = {
+            const result = {
                 ...turnResult,
-                tokensIn: attempts.reduce((sum, attempt) => sum + (attempt.tokensIn ?? 0), 0),
-                tokensOut: attempts.reduce((sum, attempt) => sum + (attempt.tokensOut ?? 0), 0),
-                costUsd: attempts.reduce((sum, attempt) => sum + (attempt.costUsd ?? 0), 0),
+                tokensIn: sumReportedUsage(attempts, "tokensIn"),
+                tokensOut: sumReportedUsage(attempts, "tokensOut"),
+                costUsd: sumReportedUsage(attempts, "costUsd"),
             };
-            break;
-        }
-        const mapping = (0, exit_conditions_cjs_1.mapExitCondition)({ ...result, killedByLeaseLoss: leaseLost || result.killedByLeaseLoss });
-        try {
-            const prUrl = await (0, github_pr_cjs_1.findHeadBranchPullRequestUrl)({
-                repository: bundle.repository?.full_name ?? task.repo,
-                headBranch: gitWorktree.branch,
-                githubToken,
+            const mapping = (0, exit_conditions_cjs_1.mapExitCondition)({
+                ...result,
+                killedByLeaseLoss: leaseLost || result.killedByLeaseLoss,
             });
-            if (prUrl)
-                mapping.evidenceUrls.push(prUrl);
-        }
-        catch (err) {
-            // Evidence discovery is best-effort: a GitHub outage or token scope
-            // mismatch must not turn an otherwise valid completion into a crash.
-            log.warn(`head-branch PR lookup failed for ${leaseId}: ${String(err)}`);
-        }
-        const knownSecrets = registry.list();
-        if (mapping.leaseOutcome === "failed") {
-            log.warn(`adapter failed for ${leaseId}: ${(0, redact_cjs_1.redactText)(mapping.reportSummary, knownSecrets)}`);
-        }
-        const transcript = attempts
-            .flatMap((attempt, index) => [
-            `# agent turn ${index + 1} stdout`,
-            (0, redact_cjs_1.redactText)(attempt.stdout, knownSecrets),
-            "",
-            `# agent turn ${index + 1} stderr`,
-            (0, redact_cjs_1.redactText)(attempt.stderr, knownSecrets),
-            "",
-        ])
-            .join("\n");
-        let transcriptUrl;
-        try {
-            const { upload_url, public_url } = await api.getTranscriptUploadUrl(leaseId);
-            await (0, upload_cjs_1.uploadTranscript)(upload_url, transcript);
-            transcriptUrl = public_url;
-        }
-        catch (err) {
-            log.warn(`transcript upload 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,
+                    githubToken,
+                });
+                if (prUrl)
+                    mapping.evidenceUrls.push(prUrl);
+            }
+            catch (err) {
+                // Evidence discovery is best-effort: a GitHub outage or token scope
+                // mismatch must not turn an otherwise valid completion into a crash.
+                log.warn(`head-branch PR lookup failed for ${leaseId}: ${String(err)}`);
+            }
+            const knownSecrets = registry.list();
+            if (mapping.leaseOutcome === "failed") {
+                log.warn(`adapter failed for ${leaseId}: ${(0, redact_cjs_1.redactText)(mapping.reportSummary, knownSecrets)}`);
+            }
+            const transcript = attempts
+                .flatMap((attempt, index) => [
+                `# agent turn ${index + 1} stdout`,
+                (0, redact_cjs_1.redactText)(attempt.stdout, knownSecrets),
+                "",
+                `# agent turn ${index + 1} stderr`,
+                (0, redact_cjs_1.redactText)(attempt.stderr, knownSecrets),
+                "",
+            ])
+                .join("\n");
+            let transcriptUrl;
+            try {
+                const { upload_url, public_url } = await api.getTranscriptUploadUrl(leaseId);
+                await (0, upload_cjs_1.uploadTranscript)(upload_url, transcript);
+                transcriptUrl = public_url;
+            }
+            catch (err) {
+                log.warn(`transcript upload failed for ${leaseId}: ${String(err)}`);
+            }
+            const completion = {
+                status: mapping.leaseOutcome,
+                report: (0, redact_cjs_1.redactText)(mapping.reportSummary, knownSecrets),
+                evidence_urls: mapping.evidenceUrls,
+                cost: {
+                    ...(result.tokensIn !== undefined ? { tokens_in: result.tokensIn } : {}),
+                    ...(result.tokensOut !== undefined ? { tokens_out: result.tokensOut } : {}),
+                    ...(result.costUsd !== undefined ? { cost_usd: result.costUsd } : {}),
+                },
+                transcript_url: transcriptUrl,
+                exit_status: mapping.exitStatus,
+                agent_type: config.agentType,
+                ...executionReport,
+            };
+            try {
+                await api.completeLease(leaseId, completion);
+                break;
+            }
+            catch (err) {
+                const rejection = mapping.leaseOutcome === "completed" ? prRequiredRejectionMessage(err) : null;
+                if (!rejection)
+                    throw err;
+                const redactedRejection = (0, redact_cjs_1.redactText)(rejection, knownSecrets);
+                if (prRequiredCompletionRetries < PR_REQUIRED_COMPLETION_RETRIES) {
+                    prRequiredCompletionRetries += 1;
+                    log.warn(`completion for ${leaseId} requires a pull request; restarting agent turn ${prRequiredCompletionRetries}/${PR_REQUIRED_COMPLETION_RETRIES} in the same worktree.`);
+                    nextPrompt = redactedRejection;
+                    continue;
+                }
+                log.warn(`completion for ${leaseId} still requires a pull request after ${PR_REQUIRED_COMPLETION_RETRIES} retries; failing with the control-plane rejection.`);
+                await api.completeLease(leaseId, {
+                    ...completion,
+                    status: "failed",
+                    report: redactedRejection,
+                    failure_summary: redactedRejection,
+                    exit_status: "failed",
+                });
+                break;
+            }
         }
-        await api.completeLease(leaseId, {
-            status: mapping.leaseOutcome,
-            report: (0, redact_cjs_1.redactText)(mapping.reportSummary, knownSecrets),
-            evidence_urls: mapping.evidenceUrls,
-            cost: {
-                tokens_in: result.tokensIn ?? 0,
-                tokens_out: result.tokensOut ?? 0,
-                cost_usd: result.costUsd ?? 0,
-            },
-            transcript_url: transcriptUrl,
-            exit_status: mapping.exitStatus,
-            agent_type: config.agentType,
-            ...executionReport,
-        });
     }
     catch (err) {
         log.error(`session ${leaseId} threw before completing: ${String(err)}`);
@@ -373,6 +405,23 @@ async function runSession(deps, claimed, sessionId) {
         await node_fs_1.promises.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
     }
 }
+function sumReportedUsage(attempts, key) {
+    const reported = attempts.flatMap((attempt) => {
+        const value = attempt[key];
+        return value === undefined ? [] : [value];
+    });
+    return reported.length > 0 ? reported.reduce((sum, value) => sum + value, 0) : undefined;
+}
+function prRequiredRejectionMessage(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" && typeof body.error === "string"
+        ? body.error
+        : null;
+}
 /** Uppercases + sanitizes secret names into shell-safe env var names for injectEnv(). */
 function toEnvMap(secrets, credentialRefreshOrAuthorName, gitAuthorNameOrEmail = "sagentlab", gitAuthorEmail = "z@sagentlab.com") {
     // Keep the existing `(secrets, authorName, authorEmail)` call shape while

package/dist/worktree-guard.cjs

@@ -5,9 +5,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.guardHookScriptPath = guardHookScriptPath;
 exports.prepareWorktreeGuard = prepareWorktreeGuard;
+exports.codexToolReadRoots = codexToolReadRoots;
 exports.codexWorktreeGuardArgs = codexWorktreeGuardArgs;
 const node_path_1 = __importDefault(require("node:path"));
 const node_fs_1 = require("node:fs");
+const node_os_1 = __importDefault(require("node:os"));
 const CODEX_GUARD_PROFILE = "navarch-worktree";
 /**
  * Tools the hook screens. Everything else — the lease-scoped Navarch MCP
@@ -55,6 +57,29 @@ async function prepareWorktreeGuard(options) {
     await node_fs_1.promises.writeFile(settingsPath, JSON.stringify(settings, null, 2), "utf8");
     return { settingsPath, configPath, hookScriptPath };
 }
+/**
+ * Read-only roots required by Codex's own tools and installed skills.
+ *
+ * Deliberately exclude the CODEX_HOME root itself: it may contain auth.json
+ * and user configuration. Package executables, installed skill instructions,
+ * plugin code, the operator's executable directory, and browser/toolchain
+ * installations are sufficient for helpers such as apply_patch, npm, gh, and
+ * browser evidence tooling.
+ */
+function codexToolReadRoots(env = process.env) {
+    const homeDir = env.HOME?.trim() || node_os_1.default.homedir();
+    const codexHome = env.CODEX_HOME?.trim() || node_path_1.default.join(homeDir, ".codex");
+    return [
+        node_path_1.default.join(codexHome, "packages"),
+        node_path_1.default.join(codexHome, "skills"),
+        node_path_1.default.join(codexHome, "plugins"),
+        node_path_1.default.join(homeDir, ".agents", "skills"),
+        node_path_1.default.join(homeDir, ".local", "bin"),
+        "/opt/homebrew",
+        node_path_1.default.join(homeDir, "Library", "Caches", "ms-playwright"),
+        node_path_1.default.join(homeDir, ".cache", "ms-playwright"),
+    ];
+}
 /**
  * Builds one-off Codex permission-profile arguments for a host session.
  *
@@ -78,6 +103,12 @@ function codexWorktreeGuardArgs(options) {
         [node_path_1.default.resolve(options.worktreePath)]: "write",
         [node_path_1.default.resolve(options.repositoryPath)]: "write",
     };
+    for (const root of codexToolReadRoots()) {
+        const resolved = node_path_1.default.resolve(root);
+        if (isPathInside(resolved, node_path_1.default.resolve(options.workspaceRoot)))
+            continue;
+        filesystem[resolved] = "read";
+    }
     for (const root of options.extraRoots ?? []) {
         const resolved = node_path_1.default.resolve(root);
         // Match the Claude hook's denied-root precedence: an extra root cannot

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Navarch machine-side session manager: registers a machine, claims tasks from the control-plane dispatcher, runs them via the Claude Code or Codex adapter, and reports results back.",
   "type": "commonjs",
   "license": "MIT",
@@ -18,7 +18,7 @@
     "task-runner"
   ],
   "bin": {
-    "navarch-runtime": "./bin/navarch.cjs"
+    "navarch-runtime": "bin/navarch.cjs"
   },
   "files": [
     "dist",