@sagentlab/navarch-runtime 0.1.8 → 0.1.10

package/README.md

@@ -60,8 +60,9 @@ project only (it will never be dispatched work from any other project).
 
 ```sh
 npx @sagentlab/navarch-runtime connect --token flmt_<...> --project <project-id> \
-    --name my-agent-1 --agent codex --api-base https://navarch.example.com
-npx @sagentlab/navarch-runtime supervise
+    --name my-agent-1 --agent codex --api-base https://navarch.example.com \
+    --config-dir ~/.navarch/my-agent-1
+npx @sagentlab/navarch-runtime supervise --config-dir ~/.navarch/my-agent-1
 ```
 
 (`@sagentlab/navarch-runtime` is published to npm, so `npx
@@ -79,6 +80,30 @@ The from-source flow — `git clone` + `./install.sh` + `node bin/navarch.cjs
 | `supervise [--agent claude-code\|codex]` | Runs the daemon under the update supervisor, enabling drain-safe automatic updates and rollback. |
 | `doctor` | Prints resolved config + Docker/registration status; no side effects. |
 
+### Running multiple agents on one machine
+
+Every agent instance must have its own config directory. The directory contains
+the machine identity, update state, managed runtime versions, and (by default)
+session workspaces. Reusing it lets a later `connect` replace `machine.json` and
+causes both processes to race over update and workspace state.
+
+Pass the same `--config-dir` to `connect` and `supervise` for each instance:
+
+```sh
+npx @sagentlab/navarch-runtime connect <pebble enrollment options> \
+  --name pebble-agent-2816 --agent codex --config-dir ~/.navarch/pebble
+npx @sagentlab/navarch-runtime supervise --config-dir ~/.navarch/pebble
+
+npx @sagentlab/navarch-runtime connect <tobi enrollment options> \
+  --name tobi-agent-1521 --agent codex --config-dir ~/.navarch/tobi
+npx @sagentlab/navarch-runtime supervise --config-dir ~/.navarch/tobi
+```
+
+`NAVARCH_CONFIG_DIR` remains equivalent for service managers and environment
+files. A supervisor also pins its starting identity into replacement workers,
+so an accidental later edit to `machine.json` cannot change that running
+instance during an automatic-update handoff.
+
 ## Active-task guidance
 
 Guidance added to a task that is already running is delivered on that
@@ -183,7 +208,7 @@ unchanged across the deployment.
 | `NAVARCH_MACHINE_NAME` | — | Used by `register`. |
 | `NAVARCH_ENROLLMENT_TOKEN` | — | Alternative to `register --token` / `connect --token`. |
 | `NAVARCH_PROJECT_ID` | — | Alternative to `connect --project`. |
-| `NAVARCH_CONFIG_DIR` | `~/.navarch` | Where `machine.json` lives. |
+| `NAVARCH_CONFIG_DIR` | `~/.navarch` | Per-instance state root. Equivalent to `--config-dir`; use a different directory for every agent on the same host. |
 | `NAVARCH_WORKSPACE_ROOT` | `<config dir>/sandboxes` | Persistent bare repo caches plus isolated per-session worktrees. |
 | `NAVARCH_MAX_SESSIONS` | `5` | Local concurrent-session capacity cap — see `src/capacity.cts`. |
 | `NAVARCH_CAPABILITIES` | `shell` (`docker-sandbox,shell` in Docker mode) | Comma list reported at heartbeat/claim time. |
@@ -192,6 +217,7 @@ unchanged across the deployment.
 | `NAVARCH_HEARTBEAT_INTERVAL_MS` | `60000` | Machine-level heartbeat interval. |
 | `NAVARCH_LEASE_HEARTBEAT_INTERVAL_MS` | `300000` | Per-lease heartbeat interval; must stay well under the 15-minute lease TTL (schema-design.md §4). |
 | `NAVARCH_SESSION_TIMEOUT_MS` | `2700000` (45 min) | Hard kill timeout for a single session. |
+| `NAVARCH_GIT_AUTHOR_NAME` / `NAVARCH_GIT_AUTHOR_EMAIL` | `sagentlab` / `z@sagentlab.com` | Git identity forced into session commits so host-level personal config is not inherited; override both for a project-authorized bot. |
 | `NAVARCH_SANDBOX_MODE` | `host` | `host` uses the resources already available to the agent process. Set `docker` explicitly for container isolation. |
 | `NAVARCH_DOCKER_IMAGE` | `node:20-slim` | Image used for the per-session container. |
 | `NAVARCH_AGENT` | saved choice, then `claude-code` | Local choice of agent CLI: `claude-code` or `codex`. Overrides the choice saved by `connect`/`register`; `start --agent` has highest priority. |

package/bin/git-credential-navarch.cjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+// Git credential helper for managed Navarch repositories. Git invokes this
+// for every remote operation, so each lookup gets a fresh installation token
+// from the lease-scoped broker instead of relying on the session-start token.
+
+const operation = process.argv[2];
+if (operation !== "get") process.exit(0);
+
+const apiBase = process.env.NAVARCH_GIT_CREDENTIAL_API_BASE?.replace(/\/+$/, "");
+const machineToken = process.env.NAVARCH_GIT_CREDENTIAL_MACHINE_TOKEN;
+const leaseId = process.env.NAVARCH_GIT_CREDENTIAL_LEASE_ID;
+
+if (!apiBase || !machineToken || !leaseId) {
+  console.error("navarch git credential helper is missing broker configuration");
+  process.exit(1);
+}
+
+async function main() {
+  try {
+    const response = await fetch(`${apiBase}/api/broker/issue`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${machineToken}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ lease_id: leaseId, secret_names: ["github-pat"] }),
+      signal: AbortSignal.timeout(15_000),
+    });
+    if (!response.ok) {
+      throw new Error(`broker returned HTTP ${response.status}`);
+    }
+    const result = await response.json();
+    const token = result?.secrets?.["github-pat"];
+    if (typeof token !== "string" || token.length === 0) {
+      throw new Error("broker did not issue github-pat");
+    }
+    process.stdout.write(`username=x-access-token\npassword=${token}\n`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`navarch git credential refresh failed: ${message}`);
+    process.exitCode = 1;
+  }
+}
+
+void main();

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/cli.cjs

@@ -1,8 +1,12 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.main = main;
 const config_cjs_1 = require("./config.cjs");
 const node_crypto_1 = require("node:crypto");
+const node_path_1 = __importDefault(require("node:path"));
 const machine_store_cjs_1 = require("./machine-store.cjs");
 const api_cjs_1 = require("./api.cjs");
 const capacity_cjs_1 = require("./capacity.cjs");
@@ -15,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
@@ -32,6 +49,17 @@ function invocation(subcommand) {
     const prefix = viaNpx ? `npx ${PACKAGE_NAME}` : "navarch-runtime";
     return `${prefix} ${subcommand}`;
 }
+/** Keep the post-enrollment next step pinned to the identity we just saved. */
+function superviseInvocation(configDir) {
+    return `${invocation("supervise")} --config-dir ${configDir}`;
+}
+/** Resolve CLI-local configuration without mutating the parent shell environment. */
+function configFromFlags(flags) {
+    const configDir = flags["config-dir"];
+    return (0, config_cjs_1.loadRuntimeConfig)(configDir
+        ? { ...process.env, NAVARCH_CONFIG_DIR: node_path_1.default.resolve(configDir) }
+        : process.env);
+}
 function agentFromFlag(flags) {
     const value = flags.agent;
     if (value === undefined)
@@ -66,7 +94,7 @@ function parseArgs(argv) {
  * RegisterMachineRequest for the (assumed, to-confirm) endpoint contract.
  */
 async function registerCommand(flags) {
-    const config = (0, config_cjs_1.loadRuntimeConfig)();
+    const config = configFromFlags(flags);
     const apiBase = flags["api-base"] ?? config.apiBase;
     const enrollmentToken = flags.token ?? process.env.NAVARCH_ENROLLMENT_TOKEN;
     const name = flags.name ?? process.env.NAVARCH_MACHINE_NAME;
@@ -102,7 +130,7 @@ async function registerCommand(flags) {
     console.log("Machine registered.");
     console.log(`  machine_id: ${result.machine_id}`);
     console.log(`  token:      ${result.token}`);
-    console.log(`\nStored in ${config.configDir}/machine.json (mode 0600). Run \`${invocation("supervise")}\` to begin serving tasks.`);
+    console.log(`\nStored in ${config.configDir}/machine.json (mode 0600). Run \`${superviseInvocation(config.configDir)}\` to begin serving tasks.`);
 }
 /**
  * `navarch-runtime connect` — "Connect an agent to a project"
@@ -114,7 +142,7 @@ async function registerCommand(flags) {
  * machine token exactly once, same discipline as `register`.
  */
 async function connectCommand(flags) {
-    const config = (0, config_cjs_1.loadRuntimeConfig)();
+    const config = configFromFlags(flags);
     const apiBase = flags["api-base"] ?? config.apiBase;
     const enrollmentToken = flags.token ?? process.env.NAVARCH_ENROLLMENT_TOKEN;
     const name = flags.name ?? process.env.NAVARCH_MACHINE_NAME;
@@ -150,10 +178,10 @@ async function connectCommand(flags) {
     console.log("Machine connected.");
     console.log(`  machine_id: ${result.machine_id}`);
     console.log(`  token:      ${result.token}`);
-    console.log(`\nStored in ${config.configDir}/machine.json (mode 0600). Run \`${invocation("supervise")}\` to begin serving tasks.`);
+    console.log(`\nStored in ${config.configDir}/machine.json (mode 0600). Run \`${superviseInvocation(config.configDir)}\` to begin serving tasks.`);
 }
 async function startCommand(flags) {
-    const baseConfig = (0, config_cjs_1.loadRuntimeConfig)();
+    const baseConfig = configFromFlags(flags);
     const identity = await (0, machine_store_cjs_1.resolveMachineIdentity)(baseConfig.configDir, baseConfig.apiBase);
     // Adapter selection belongs to the local machine: an explicit start flag
     // wins, followed by NAVARCH_AGENT, the choice saved at connect/register
@@ -203,14 +231,25 @@ async function startCommand(flags) {
     process.on("SIGTERM", shutdown);
 }
 async function superviseCommand(flags) {
-    const config = (0, config_cjs_1.loadRuntimeConfig)();
+    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] : [];
-    const exitCode = await (0, supervisor_cjs_1.superviseRuntime)(config.configDir, process.argv[1] ?? "", workerArgs);
+    // 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
+    // config directory in the meantime.
+    const exitCode = await (0, supervisor_cjs_1.superviseRuntime)(config.configDir, process.argv[1] ?? "", workerArgs, 120_000, {
+        NAVARCH_CONFIG_DIR: config.configDir,
+        NAVARCH_MACHINE_ID: identity.machine_id,
+        NAVARCH_MACHINE_TOKEN: identity.token,
+        NAVARCH_MACHINE_NAME: identity.name,
+        NAVARCH_API_BASE: identity.api_base,
+    });
     process.exitCode = exitCode;
 }
 async function doctorCommand(flags) {
-    const config = (0, config_cjs_1.loadRuntimeConfig)();
+    const config = configFromFlags(flags);
     const dockerOk = await (0, sandbox_cjs_1.isDockerAvailable)();
     console.log(`api_base:        ${config.apiBase}`);
     console.log(`config_dir:      ${config.configDir}`);
@@ -237,14 +276,15 @@ function helpText() {
 
 Usage:
   navarch-runtime register --token <enrollment-token> --name <machine-name> \\
-      [--agent claude-code|codex] [--capabilities a,b] [--max-sessions N] [--owner-zone z] [--api-base url]
+      [--config-dir <path>] [--agent claude-code|codex] [--capabilities a,b] [--max-sessions N] [--owner-zone z] [--api-base url]
   navarch-runtime connect --token <enrollment-token> --name <machine-name> \\
-      [--agent claude-code|codex] [--project <project-id>] [--capabilities a,b] [--max-sessions N] [--api-base url]
-  navarch-runtime start [--agent claude-code|codex]
-  navarch-runtime supervise [--agent claude-code|codex]
-  navarch-runtime doctor
+      [--config-dir <path>] [--agent claude-code|codex] [--project <project-id>] [--capabilities a,b] [--max-sessions N] [--api-base url]
+  navarch-runtime start [--config-dir <path>] [--agent claude-code|codex]
+  navarch-runtime supervise [--config-dir <path>] [--agent claude-code|codex]
+  navarch-runtime doctor [--config-dir <path>]
 
-Configuration is via NAVARCH_* environment variables; see runtime/README.md.
+Use a different --config-dir (or NAVARCH_CONFIG_DIR) for every agent instance.
+Other configuration is via NAVARCH_* environment variables; see runtime/README.md.
 `;
 }
 async function main(argv = process.argv.slice(2)) {
@@ -278,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/config.cjs

@@ -57,6 +57,8 @@ function loadRuntimeConfig(env = process.env) {
         claudeExtraArgs: envList(env, "NAVARCH_CLAUDE_EXTRA_ARGS", []),
         codexBin: env.NAVARCH_CODEX_BIN ?? "codex",
         codexExtraArgs: envList(env, "NAVARCH_CODEX_EXTRA_ARGS", []),
+        gitAuthorName: env.NAVARCH_GIT_AUTHOR_NAME ?? "sagentlab",
+        gitAuthorEmail: env.NAVARCH_GIT_AUTHOR_EMAIL ?? "z@sagentlab.com",
         mcpConfigPath: env.NAVARCH_MCP_CONFIG_PATH ?? null,
         sandboxMode,
         dockerImage: env.NAVARCH_DOCKER_IMAGE ?? "node:20-slim",

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/git-worktree.cjs

@@ -38,40 +38,95 @@ class GitWorktree {
         await node_fs_1.promises.mkdir(node_path_1.default.dirname(this.repositoryPath), { recursive: true });
         await node_fs_1.promises.mkdir(this.sessionRoot, { recursive: true });
         await withRepositoryLock(this.repositoryPath, async () => {
-            if (!(await pathExists(node_path_1.default.join(this.repositoryPath, "HEAD")))) {
-                await this.runGit(["clone", "--bare", this.cloneUrl, this.repositoryPath], true);
+            await this.ensureRepositoryCache();
+            try {
+                await this.addSessionWorktree();
             }
-            else {
-                const origin = await this.runGit(["--git-dir", this.repositoryPath, "remote", "get-url", "origin"], false);
-                if (normalizeCloneUrl(origin.stdout) !== normalizeCloneUrl(this.cloneUrl)) {
-                    await this.runGit(["--git-dir", this.repositoryPath, "remote", "set-url", "origin", this.cloneUrl], false);
-                }
+            catch (error) {
+                if (!isInvalidReferenceError(error))
+                    throw error;
+                // This bare cache owns the metadata for every active session worktree.
+                // Replacing it here would invalidate those worktrees, so leave it intact
+                // and fail with enough context for a coordinated repair.
+                throw new Error(`Failed to create a session worktree because the cached repository at ${this.repositoryPath} ` +
+                    `could not resolve the fetched start ref. The shared cache was preserved to avoid invalidating ` +
+                    `active worktrees; retry after active sessions finish or repair the cache in place: ${errorMessage(error)}`);
             }
-            const remoteHead = await this.runGit(["--git-dir", this.repositoryPath, "ls-remote", "--symref", "origin", "HEAD"], true);
-            const defaultBranch = parseRemoteHead(remoteHead.stdout);
-            const startRef = defaultBranch
-                ? defaultBranch.replace(/^refs\/heads\//, "refs/remotes/origin/")
-                : "HEAD";
-            await this.runGit([
-                "--git-dir",
-                this.repositoryPath,
-                "fetch",
-                "--prune",
-                "origin",
-                "+refs/heads/*:refs/remotes/origin/*",
-            ], true);
-            await this.runGit([
-                "--git-dir",
-                this.repositoryPath,
-                "worktree",
-                "add",
-                "-b",
-                this.branch,
-                this.worktreePath,
-                startRef,
-            ], false);
         });
     }
+    /** Clones the bare cache if missing, repoints origin if needed, and fetches all branches. */
+    async ensureRepositoryCache() {
+        if (!(await pathExists(node_path_1.default.join(this.repositoryPath, "HEAD")))) {
+            await this.runGit(["clone", "--bare", this.cloneUrl, this.repositoryPath], true);
+        }
+        else {
+            const origin = await this.runGit(["--git-dir", this.repositoryPath, "remote", "get-url", "origin"], false);
+            if (normalizeCloneUrl(origin.stdout) !== normalizeCloneUrl(this.cloneUrl)) {
+                await this.runGit(["--git-dir", this.repositoryPath, "remote", "set-url", "origin", this.cloneUrl], false);
+            }
+        }
+        await this.runGit([
+            "--git-dir",
+            this.repositoryPath,
+            "fetch",
+            "--prune",
+            "origin",
+            "+refs/heads/*:refs/remotes/origin/*",
+        ], true);
+    }
+    async addSessionWorktree() {
+        const startRef = await this.resolveStartRef();
+        if (!startRef) {
+            // Empty remote (no commits yet): there is nothing to base the session on,
+            // so bootstrap an orphan branch the session can push as the first commit.
+            await this.addOrphanWorktree();
+            return;
+        }
+        await this.runGit([
+            "--git-dir",
+            this.repositoryPath,
+            "worktree",
+            "add",
+            "-b",
+            this.branch,
+            this.worktreePath,
+            startRef,
+        ], false);
+    }
+    /**
+     * Resolves the remote-tracking ref new session branches start from, or null
+     * when the remote has no branches at all (a freshly provisioned empty repo).
+     */
+    async resolveStartRef() {
+        const remoteHead = await this.runGit(["--git-dir", this.repositoryPath, "ls-remote", "--symref", "origin", "HEAD"], true);
+        const defaultBranch = parseRemoteHead(remoteHead.stdout);
+        if (defaultBranch)
+            return defaultBranch.replace(/^refs\/heads\//, "refs/remotes/origin/");
+        // No symref (e.g. an unborn remote HEAD): fall back to whatever branches
+        // the fetch brought in, preferring the conventional default names.
+        const refs = await this.runGit(["--git-dir", this.repositoryPath, "for-each-ref", "--format=%(refname)", "refs/remotes/origin"], false);
+        const branches = refs.stdout
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line && line !== "refs/remotes/origin/HEAD");
+        for (const preferred of ["refs/remotes/origin/main", "refs/remotes/origin/master"]) {
+            if (branches.includes(preferred))
+                return preferred;
+        }
+        return branches[0] ?? null;
+    }
+    async addOrphanWorktree() {
+        try {
+            await this.runGit(["--git-dir", this.repositoryPath, "worktree", "add", "--orphan", "-b", this.branch, this.worktreePath], false);
+        }
+        catch (error) {
+            // `worktree add --orphan` needs git >= 2.42; older gits reject the flag.
+            if (!/unknown option|usage: git worktree add/i.test(errorMessage(error)))
+                throw error;
+            await this.runGit(["init", "--initial-branch", this.branch, this.worktreePath], false);
+            await this.runGit(["-C", this.worktreePath, "remote", "add", "origin", this.cloneUrl], false);
+        }
+    }
     async cleanup() {
         await withRepositoryLock(this.repositoryPath, async () => {
             await this.runner
@@ -172,3 +227,9 @@ function parseRemoteHead(output) {
     const match = output.match(/^ref:\s+(refs\/heads\/[A-Za-z0-9._/-]+)\s+HEAD$/m);
     return match?.[1] ?? null;
 }
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isInvalidReferenceError(error) {
+    return /invalid reference/i.test(errorMessage(error));
+}

package/dist/session.cjs

@@ -4,8 +4,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 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");
@@ -19,11 +21,14 @@ const github_pr_cjs_1 = require("./github-pr.cjs");
 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):
  *   1. write the prompt file
- *   2. fetch secrets from the broker once, at session start
+ *   2. fetch secrets from the broker at session start (managed GitHub git
+ *      credentials are subsequently refreshed by a lease-scoped helper)
  *   3. optionally stand up a Docker sandbox when explicitly configured
  *   4. run the configured agent adapter (Claude Code or Codex, per
  *      NAVARCH_AGENT — adapters/index.cts#selectAdapter), heartbeating the
@@ -58,17 +63,30 @@ async function runSession(deps, claimed, sessionId) {
     await node_fs_1.promises.mkdir(workDir, { recursive: true });
     const promptText = (0, prompt_cjs_1.renderPrompt)(task, bundle);
     await node_fs_1.promises.writeFile(node_path_1.default.join(workDir, "prompt.md"), promptText, "utf8");
-    // Secrets: fetched once, held only in memory (registry + env map below),
+    // Secrets: initially fetched once, held only in memory (registry + env map below),
     // never written to disk on the host. They only ever reach disk inside the
     // sandbox's tmpfs (sandbox.cts injectEnv), which is wiped with the container.
     const registry = new redact_cjs_1.SecretRegistry();
     let secrets = {};
+    let managedGithubCredential = false;
     const secretNames = bundle.secret_manifest.map((s) => s.name);
     if (secretNames.length > 0) {
         const issued = await api.issueSecrets({ lease_id: leaseId, secret_names: secretNames });
         secrets = issued.secrets;
+        managedGithubCredential = issued.github_app_issued === true;
         registry.registerAll(secrets);
     }
+    let gitCredentialRefresh;
+    if (managedGithubCredential && secrets["github-pat"]) {
+        const helperPath = node_path_1.default.join(workDir, GIT_CREDENTIAL_HELPER_FILENAME);
+        await node_fs_1.promises.copyFile(node_path_1.default.resolve(__dirname, "../bin/git-credential-navarch.cjs"), helperPath);
+        gitCredentialRefresh = {
+            helperPath,
+            apiBase: api.getBaseUrl(),
+            machineToken: api.getToken() ?? "",
+            leaseId,
+        };
+    }
     const cloneUrl = bundle.repository?.clone_url ??
         (task.repo ? `https://github.com/${task.repo.replace(/\.git$/, "")}.git` : null);
     if (!cloneUrl) {
@@ -223,7 +241,7 @@ async function runSession(deps, claimed, sessionId) {
         await gitWorktree.prepare();
         if (sandbox) {
             await sandbox.create();
-            await sandbox.injectEnv(toEnvMap(secrets));
+            await sandbox.injectEnv(toEnvMap(secrets, gitCredentialRefresh, config.gitAuthorName, config.gitAuthorEmail));
         }
         // Picks the Claude Code or Codex adapter per NAVARCH_AGENT
         // (config.cts's `agentType`) — see adapters/index.cts#selectAdapter.
@@ -234,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
@@ -243,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,
@@ -255,7 +276,7 @@ async function runSession(deps, claimed, sessionId) {
                 model: execution.model,
                 reasoningEffort: execution.reasoning_effort,
                 timeoutMs: config.sessionTimeoutMs,
-                env: toEnvMap(secrets),
+                env: toEnvMap(secrets, gitCredentialRefresh, config.gitAuthorName, config.gitAuthorEmail),
                 settingsPath: claudeSettingsPath,
                 codexGuardArgs,
                 cwd: sandbox ? undefined : gitWorktree.worktreePath,
@@ -270,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)}`);
@@ -357,22 +405,71 @@ 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) {
+function toEnvMap(secrets, credentialRefreshOrAuthorName, gitAuthorNameOrEmail = "sagentlab", gitAuthorEmail = "z@sagentlab.com") {
+    // Keep the existing `(secrets, authorName, authorEmail)` call shape while
+    // accepting a refresh config before the author identity for managed repos.
+    const gitCredentialRefresh = typeof credentialRefreshOrAuthorName === "string"
+        ? undefined
+        : credentialRefreshOrAuthorName;
+    const gitAuthorName = typeof credentialRefreshOrAuthorName === "string"
+        ? credentialRefreshOrAuthorName
+        : gitAuthorNameOrEmail;
+    const resolvedGitAuthorEmail = typeof credentialRefreshOrAuthorName === "string"
+        ? gitAuthorNameOrEmail
+        : gitAuthorEmail;
     const out = {};
     for (const [name, value] of Object.entries(secrets)) {
         out[name.toUpperCase().replace(/[^A-Z0-9_]/g, "_")] = value;
     }
+    const gitConfig = [
+        ["user.name", gitAuthorName],
+        ["user.email", resolvedGitAuthorEmail],
+    ];
     if (secrets["github-pat"] && !out.GITHUB_TOKEN) {
         out.GITHUB_TOKEN = secrets["github-pat"];
-        // Make ordinary `git push` calls from the agent use the in-memory token.
-        // The helper contains only an env-var reference; the token itself never
-        // lands in argv, git config, or the worktree.
-        out.GIT_CONFIG_COUNT = "1";
-        out.GIT_CONFIG_KEY_0 = "credential.helper";
-        out.GIT_CONFIG_VALUE_0 =
-            '!f() { echo username=x-access-token; echo "password=$GITHUB_TOKEN"; }; f';
-        out.GIT_TERMINAL_PROMPT = "0";
+        if (gitCredentialRefresh) {
+            out.NAVARCH_GIT_CREDENTIAL_API_BASE = gitCredentialRefresh.apiBase;
+            out.NAVARCH_GIT_CREDENTIAL_MACHINE_TOKEN = gitCredentialRefresh.machineToken;
+            out.NAVARCH_GIT_CREDENTIAL_LEASE_ID = gitCredentialRefresh.leaseId;
+            gitConfig.unshift(["credential.helper", ""], ["credential.helper", `!node ${shellQuote(gitCredentialRefresh.helperPath)}`]);
+            out.GIT_TERMINAL_PROMPT = "0";
+        }
+        else {
+            // Make ordinary `git push` calls from the agent use the in-memory token.
+            // The helper contains only an env-var reference; the token itself never
+            // lands in argv, git config, or the worktree.
+            gitConfig.unshift([
+                "credential.helper",
+                '!f() { echo username=x-access-token; echo "password=$GITHUB_TOKEN"; }; f',
+            ]);
+            out.GIT_TERMINAL_PROMPT = "0";
+        }
     }
+    out.GIT_CONFIG_COUNT = String(gitConfig.length);
+    gitConfig.forEach(([key, value], index) => {
+        out[`GIT_CONFIG_KEY_${index}`] = key;
+        out[`GIT_CONFIG_VALUE_${index}`] = value;
+    });
     return out;
 }
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}

package/dist/supervisor.cjs

@@ -6,10 +6,10 @@ const logger_cjs_1 = require("./logger.cjs");
 const update_installer_cjs_1 = require("./update-installer.cjs");
 const log = (0, logger_cjs_1.createLogger)("supervisor");
 const UPDATE_RESTART_EXIT_CODE = 75;
-function runWorker(binPath, args, healthTimeoutMs, setCurrentChild, onHealthy) {
+function runWorker(binPath, args, healthTimeoutMs, workerEnv, setCurrentChild, onHealthy) {
     return new Promise((resolve) => {
         const child = (0, node_child_process_1.spawn)(process.execPath, [binPath, "start", ...args], {
-            env: { ...process.env, NAVARCH_SUPERVISED: "1" },
+            env: { ...process.env, ...workerEnv, NAVARCH_SUPERVISED: "1" },
             stdio: ["inherit", "inherit", "inherit", "ipc"],
         });
         setCurrentChild(child);
@@ -70,7 +70,7 @@ function runWorker(binPath, args, healthTimeoutMs, setCurrentChild, onHealthy) {
     });
 }
 /** Runs the worker and owns update activation, health checking, and rollback. */
-async function superviseRuntime(configDir, initialBinPath, workerArgs = [], healthTimeoutMs = 120_000) {
+async function superviseRuntime(configDir, initialBinPath, workerArgs = [], healthTimeoutMs = 120_000, workerEnv = {}) {
     let currentBin = initialBinPath;
     let rollbackBin = null;
     let candidatePending = null;
@@ -99,7 +99,7 @@ async function superviseRuntime(configDir, initialBinPath, workerArgs = [], heal
         }
         while (!stopping) {
             const candidateThisRun = awaitingCandidateHealth;
-            const result = await runWorker(currentBin, workerArgs, candidateThisRun ? healthTimeoutMs : null, (child) => {
+            const result = await runWorker(currentBin, workerArgs, candidateThisRun ? healthTimeoutMs : null, workerEnv, (child) => {
                 currentChild = child;
             }, async () => {
                 if (candidateThisRun) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "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",