@sagentlab/navarch-runtime 0.1.1 → 0.1.2

package/README.md

@@ -7,7 +7,8 @@ it. Plain Node/TypeScript, zero production dependencies, no Next.js coupling
 machine.
 
 The agent CLI a session runs is either **Claude Code** or **OpenAI Codex**,
-selected per machine via `NAVARCH_AGENT` (default `claude-code`) — see
+selected by the local machine via `--agent` or `NAVARCH_AGENT` (default
+`claude-code`) — see
 "Choosing an agent (Claude Code vs. Codex)" below.
 
 See [`docs/agent-platform-project-plan.md`](../docs/agent-platform-project-plan.md)
@@ -20,7 +21,7 @@ the API contract.
 
 ```sh
 git clone <this repo> && cd sagentlab/runtime
-./install.sh          # checks node/docker, npm install, npm run build
+./install.sh          # checks node, npm install, npm run build
 export NAVARCH_API_BASE=https://navarch.example.com
 node bin/navarch.cjs register --token <enrollment-token> --name my-machine-1
 node bin/navarch.cjs start
@@ -48,8 +49,8 @@ availability, and registration status without starting the daemon.
 
 `connect` is the project-scoped sibling of `register` — "Connect an agent to
 a project" (self-hosted-runner style, like a GitHub Actions self-hosted
-runner token): a project **owner** mints a short-lived (60 minute),
-single-use token from the platform UI (the project settings page's "Connect
+runner token): a project **owner** mints a single-use token from the platform
+UI (the project settings page's "Connect
 an agent" panel, or the onboarding wizard's Agent step),
 `POST /api/projects/:id/enrollment-tokens`, and pastes you the ready-to-run
 command. Unlike `register`, no `NAVARCH_ENROLLMENT_SECRET` or
@@ -59,7 +60,7 @@ 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 --api-base https://navarch.example.com
+    --name my-agent-1 --agent codex --api-base https://navarch.example.com
 node bin/navarch.cjs start
 ```
 
@@ -72,9 +73,9 @@ The from-source flow — `git clone` + `./install.sh` + `node bin/navarch.cjs
 
 | Command | Purpose |
 |---|---|
-| `register --token <t> --name <n> [--capabilities a,b] [--max-sessions N] [--owner-zone z] [--api-base url]` | Registers this machine (global enrollment secret), prints the token once. |
-| `connect --token <t> --name <n> [--project <id>] [--capabilities a,b] [--max-sessions N] [--api-base url]` | Connects this machine to exactly one project (project-scoped enrollment token), prints the token once. |
-| `start` | Runs the daemon: machine heartbeat loop + claim loop, `NAVARCH_MAX_SESSIONS` concurrent task sessions. |
+| `register --token <t> --name <n> [--agent claude-code\|codex] […]` | Registers this machine, saves its local agent choice, and prints the token once. |
+| `connect --token <t> --name <n> [--agent claude-code\|codex] [--project <id>] […]` | Connects this machine to one project, saves its local agent choice, and prints the token once. |
+| `start [--agent claude-code\|codex]` | Runs the daemon. A start-time agent choice overrides the saved choice. |
 | `doctor` | Prints resolved config + Docker/registration status; no side effects. |
 
 ## Configuration (`NAVARCH_*` env vars)
@@ -87,17 +88,17 @@ The from-source flow — `git clone` + `./install.sh` + `node bin/navarch.cjs
 | `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_WORKSPACE_ROOT` | `<config dir>/sandboxes` | Per-session working directories (host side; mounted into each container). |
-| `NAVARCH_MAX_SESSIONS` | `3` | Capacity cap — see `src/capacity.cts`. |
-| `NAVARCH_CAPABILITIES` | `docker-sandbox,shell` | Comma list reported at heartbeat/claim time. |
+| `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. |
 | `NAVARCH_OWNER_ZONE` | `sagentlab` | `sagentlab` or `customer-<slug>-premises` (project-plan.md §3.11). |
 | `NAVARCH_POLL_INTERVAL_MS` | `5000` | Claim-loop poll interval. |
 | `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_SANDBOX_MODE` | `docker` | `docker` or `host` (host mode skips the container — dev/debug only, no isolation). |
+| `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` | `claude-code` | Which agent CLI runs sessions: `claude-code` or `codex`. Any other value falls back to `claude-code`. Recorded as `agent_type` on the `complete()` call so the sessions row shows which one ran. |
+| `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. |
 | `NAVARCH_CLAUDE_BIN` | `claude` | Path/name of the Claude Code CLI binary. |
 | `NAVARCH_CLAUDE_EXTRA_ARGS` | — | Comma list of extra CLI args appended after `--mcp-config` (Claude Code). |
 | `NAVARCH_CODEX_BIN` | `codex` | Path/name of the Codex CLI binary. |
@@ -106,8 +107,10 @@ The from-source flow — `git clone` + `./install.sh` + `node bin/navarch.cjs
 
 ## Choosing an agent (Claude Code vs. Codex)
 
-Each machine runs sessions with exactly one agent CLI, set once via
-`NAVARCH_AGENT`:
+Each machine chooses its own agent CLI. Pass `--agent` while connecting to
+persist the choice in local `machine.json`, override it for one daemon start
+with `start --agent`, or set `NAVARCH_AGENT` in the machine's service
+environment:
 
 ```sh
 # Claude Code (default) — requires the `claude` CLI installed and
@@ -120,6 +123,9 @@ export NAVARCH_AGENT=claude-code
 export NAVARCH_AGENT=codex
 ```
 
+Priority is `start --agent` → `NAVARCH_AGENT` → the locally saved choice →
+`claude-code`. The control plane does not choose the adapter.
+
 Both adapters implement the same `AgentAdapter` interface
 (`src/adapters/types.cts`) and run either directly on the host or via
 `docker exec` in the session's sandbox container, exactly like the Claude
@@ -149,7 +155,9 @@ cli.cts
           └─ runSession (session.cts), one per claimed lease, run concurrently up to NAVARCH_MAX_SESSIONS:
                1. write prompt.md (prompt.cts renders the 4-layer context bundle)
                2. api.issueSecrets()                  → held in memory only
-               3. DockerSandbox.create/injectEnv/cloneRepo (sandbox.cts)
+               3. fetch the project's bare repository cache and create a
+                  unique git worktree for this session; optionally mount it
+                  into Docker when NAVARCH_SANDBOX_MODE=docker
                4. selectAdapter(config.agentType) (adapters/index.cts) picks one AgentAdapter
                   (adapters/types.cts) by NAVARCH_AGENT, then .run(...):
                     - claudeCodeAdapter (adapters/claude.cts) — `claude -p <prompt> --mcp-config <path>`
@@ -158,7 +166,8 @@ cli.cts
                   a failed heartbeat aborts the run (kills the process) and marks the outcome as lease-lost
                5. mapExitCondition (exit-conditions.cts) → redact.cts scrubs the transcript → upload.cts PUTs it
                6. api.completeLease(), reporting agent_type: config.agentType
-               7. sandbox.wipe() unconditionally (finally block)
+               7. sandbox.wipe() when present; remove the session workspace
+                  unconditionally (finally block)
 ```
 
 `adapter.cts` (top-level) is now a backward-compat re-export of

package/dist/claim-loop.cjs

@@ -47,6 +47,7 @@ class ClaimLoop {
             const claimed = await this.api.claim({
                 available_capacity: this.capacity.available(),
                 capabilities: this.config.capabilities,
+                agent_type: this.config.agentType,
                 session_id: sessionId,
             });
             if (!claimed)

package/dist/cli.cjs

@@ -29,6 +29,15 @@ function invocation(subcommand) {
     const prefix = viaNpx ? `npx ${PACKAGE_NAME}` : "navarch-runtime";
     return `${prefix} ${subcommand}`;
 }
+function agentFromFlag(flags) {
+    const value = flags.agent;
+    if (value === undefined)
+        return undefined;
+    if (!(0, config_cjs_1.isRuntimeAgentType)(value)) {
+        throw new Error("--agent must be either 'claude-code' or 'codex'.");
+    }
+    return value;
+}
 function parseArgs(argv) {
     const [command, ...rest] = argv;
     const flags = {};
@@ -70,6 +79,7 @@ async function registerCommand(flags) {
         .map((s) => s.trim())
         .filter(Boolean);
     const ownerZone = flags["owner-zone"] ?? config.ownerZone;
+    const agentType = agentFromFlag(flags) ?? config.agentType;
     const client = new api_cjs_1.NavarchApiClient({ baseUrl: apiBase });
     const result = await client.registerMachine({
         enrollment_token: enrollmentToken,
@@ -83,6 +93,7 @@ async function registerCommand(flags) {
         token: result.token,
         name,
         api_base: apiBase,
+        agent_type: agentType,
     });
     // Printed exactly once. Never logged or echoed again after this point.
     console.log("Machine registered.");
@@ -93,8 +104,8 @@ async function registerCommand(flags) {
 /**
  * `navarch-runtime connect` — "Connect an agent to a project"
  * (docs/navarch/schema-design.md §7 "Agent connect"; self-hosted-runner
- * style). The project-scoped sibling of `register`: redeems a short-lived,
- * single-use enrollment token a project owner minted from the platform UI
+ * style). The project-scoped sibling of `register`: redeems a single-use
+ * enrollment token a project owner minted from the platform UI
  * (ConnectAgentPanel → POST /api/projects/:id/enrollment-tokens) instead of
  * the global NAVARCH_ENROLLMENT_SECRET `register` needs. Prints the
  * machine token exactly once, same discipline as `register`.
@@ -116,6 +127,7 @@ async function connectCommand(flags) {
         .split(",")
         .map((s) => s.trim())
         .filter(Boolean);
+    const agentType = agentFromFlag(flags) ?? config.agentType;
     const client = new api_cjs_1.NavarchApiClient({ baseUrl: apiBase });
     const result = await client.connectMachine({
         enrollment_token: enrollmentToken,
@@ -129,6 +141,7 @@ async function connectCommand(flags) {
         token: result.token,
         name,
         api_base: apiBase,
+        agent_type: agentType,
     });
     // Printed exactly once. Never logged or echoed again after this point.
     console.log("Machine connected.");
@@ -136,16 +149,22 @@ async function connectCommand(flags) {
     console.log(`  token:      ${result.token}`);
     console.log(`\nStored in ${config.configDir}/machine.json (mode 0600). Run \`${invocation("start")}\` to begin serving tasks.`);
 }
-async function startCommand() {
-    const config = (0, config_cjs_1.loadRuntimeConfig)();
-    const identity = await (0, machine_store_cjs_1.resolveMachineIdentity)(config.configDir, config.apiBase);
+async function startCommand(flags) {
+    const baseConfig = (0, config_cjs_1.loadRuntimeConfig)();
+    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
+    // time, and finally the backwards-compatible Claude Code default.
+    const agentType = agentFromFlag(flags) ??
+        (process.env.NAVARCH_AGENT ? baseConfig.agentType : identity.agent_type ?? baseConfig.agentType);
+    const config = { ...baseConfig, agentType };
     const api = new api_cjs_1.NavarchApiClient({ baseUrl: identity.api_base, token: identity.token });
     const capacity = new capacity_cjs_1.CapacityTracker(config.maxSessions);
     const heartbeat = new heartbeat_loop_cjs_1.MachineHeartbeatLoop(api, identity.machine_id, config, capacity);
     const claimLoop = new claim_loop_cjs_1.ClaimLoop(api, config, capacity, (claimed, sessionId) => (0, session_cjs_1.runSession)({ api, config }, claimed, sessionId));
     heartbeat.start();
     claimLoop.start();
-    log.info(`navarch-runtime started: machine=${identity.name} max_sessions=${config.maxSessions} api_base=${identity.api_base}`);
+    log.info(`navarch-runtime started: machine=${identity.name} agent=${config.agentType} max_sessions=${config.maxSessions} api_base=${identity.api_base}`);
     const shutdown = () => {
         log.info("shutting down...");
         heartbeat.stop();
@@ -155,7 +174,7 @@ async function startCommand() {
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
 }
-async function doctorCommand() {
+async function doctorCommand(flags) {
     const config = (0, config_cjs_1.loadRuntimeConfig)();
     const dockerOk = await (0, sandbox_cjs_1.isDockerAvailable)();
     console.log(`api_base:        ${config.apiBase}`);
@@ -165,23 +184,28 @@ async function doctorCommand() {
     console.log(`capabilities:    ${config.capabilities.join(", ")}`);
     console.log(`sandbox_mode:    ${config.sandboxMode}`);
     console.log(`docker:          ${dockerOk ? "available" : "NOT AVAILABLE (docker-backed sessions will fail)"}`);
+    let identity;
     try {
-        const identity = await (0, machine_store_cjs_1.resolveMachineIdentity)(config.configDir, config.apiBase);
-        console.log(`machine:         ${identity.name} (${identity.machine_id})`);
+        identity = await (0, machine_store_cjs_1.resolveMachineIdentity)(config.configDir, config.apiBase);
     }
     catch {
         console.log(`machine:         not registered — run \`${invocation("register")}\``);
+        return;
     }
+    const agentType = agentFromFlag(flags) ??
+        (process.env.NAVARCH_AGENT ? config.agentType : identity.agent_type ?? config.agentType);
+    console.log(`machine:         ${identity.name} (${identity.machine_id})`);
+    console.log(`agent:           ${agentType}`);
 }
 function helpText() {
     return `navarch-runtime — Navarch machine-side session manager
 
 Usage:
   navarch-runtime register --token <enrollment-token> --name <machine-name> \\
-      [--capabilities a,b] [--max-sessions N] [--owner-zone z] [--api-base url]
+      [--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> \\
-      [--project <project-id>] [--capabilities a,b] [--max-sessions N] [--api-base url]
-  navarch-runtime start
+      [--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 doctor
 
 Configuration is via NAVARCH_* environment variables; see runtime/README.md.
@@ -198,10 +222,10 @@ async function main(argv = process.argv.slice(2)) {
                 await connectCommand(flags);
                 break;
             case "start":
-                await startCommand();
+                await startCommand(flags);
                 break;
             case "doctor":
-                await doctorCommand();
+                await doctorCommand(flags);
                 break;
             case "help":
             case "--help":

package/dist/config.cjs

@@ -3,9 +3,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRuntimeAgentType = isRuntimeAgentType;
 exports.loadRuntimeConfig = loadRuntimeConfig;
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
+function isRuntimeAgentType(value) {
+    return value === "claude-code" || value === "codex";
+}
 function envInt(env, name, fallback) {
     const raw = env[name];
     if (!raw)
@@ -30,12 +34,17 @@ function envList(env, name, fallback) {
 function loadRuntimeConfig(env = process.env) {
     const configDir = env.NAVARCH_CONFIG_DIR ?? node_path_1.default.join(node_os_1.default.homedir(), ".navarch");
     const leaseHeartbeatIntervalMs = envInt(env, "NAVARCH_LEASE_HEARTBEAT_INTERVAL_MS", 5 * 60 * 1000);
+    // Run the agent with the resources already available on its machine by
+    // default. Docker isolation is an explicit operator opt-in, not a
+    // prerequisite for claiming ordinary shell work.
+    const sandboxMode = env.NAVARCH_SANDBOX_MODE === "docker" ? "docker" : "host";
+    const defaultCapabilities = sandboxMode === "docker" ? ["docker-sandbox", "shell"] : ["shell"];
     return {
         apiBase: env.NAVARCH_API_BASE ?? "http://localhost:3000",
         workspaceRoot: env.NAVARCH_WORKSPACE_ROOT ?? node_path_1.default.join(configDir, "sandboxes"),
         configDir,
-        maxSessions: envInt(env, "NAVARCH_MAX_SESSIONS", 3),
-        capabilities: envList(env, "NAVARCH_CAPABILITIES", ["docker-sandbox", "shell"]),
+        maxSessions: envInt(env, "NAVARCH_MAX_SESSIONS", 5),
+        capabilities: envList(env, "NAVARCH_CAPABILITIES", defaultCapabilities),
         ownerZone: env.NAVARCH_OWNER_ZONE ?? "sagentlab",
         pollIntervalMs: envInt(env, "NAVARCH_POLL_INTERVAL_MS", 5000),
         machineHeartbeatIntervalMs: envInt(env, "NAVARCH_HEARTBEAT_INTERVAL_MS", 60_000),
@@ -43,13 +52,13 @@ function loadRuntimeConfig(env = process.env) {
         // interval must stay comfortably under that TTL.
         leaseHeartbeatIntervalMs,
         sessionTimeoutMs: envInt(env, "NAVARCH_SESSION_TIMEOUT_MS", 45 * 60 * 1000),
-        agentType: env.NAVARCH_AGENT === "codex" ? "codex" : "claude-code",
+        agentType: isRuntimeAgentType(env.NAVARCH_AGENT) ? env.NAVARCH_AGENT : "claude-code",
         claudeBin: env.NAVARCH_CLAUDE_BIN ?? "claude",
         claudeExtraArgs: envList(env, "NAVARCH_CLAUDE_EXTRA_ARGS", []),
         codexBin: env.NAVARCH_CODEX_BIN ?? "codex",
         codexExtraArgs: envList(env, "NAVARCH_CODEX_EXTRA_ARGS", []),
         mcpConfigPath: env.NAVARCH_MCP_CONFIG_PATH ?? null,
-        sandboxMode: env.NAVARCH_SANDBOX_MODE === "host" ? "host" : "docker",
+        sandboxMode,
         dockerImage: env.NAVARCH_DOCKER_IMAGE ?? "node:20-slim",
     };
 }

package/dist/git-worktree.cjs

@@ -0,0 +1,142 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitWorktree = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = require("node:fs");
+const sandbox_cjs_1 = require("./sandbox.cjs");
+const repositoryLocks = new Map();
+/**
+ * Maintains one bare repository cache per project and checks out each session
+ * into its own uniquely named worktree. The cache avoids N full clones while
+ * git's worktree metadata keeps concurrent agents from sharing an index or
+ * working directory.
+ */
+class GitWorktree {
+    sessionRoot;
+    worktreePath;
+    repositoryPath;
+    branch;
+    runner;
+    cloneUrl;
+    githubToken;
+    constructor(options) {
+        const projectKey = safePathSegment(options.projectId);
+        const sessionKey = safePathSegment(options.sessionId);
+        this.sessionRoot = node_path_1.default.join(options.workspaceRoot, "sessions", sessionKey);
+        this.worktreePath = node_path_1.default.join(this.sessionRoot, "repo");
+        this.repositoryPath = node_path_1.default.join(options.workspaceRoot, "repositories", `${projectKey}.git`);
+        this.branch = `navarch/${safePathSegment(options.taskId).slice(0, 32)}-${sessionKey.slice(0, 12)}`;
+        this.runner = options.runner ?? sandbox_cjs_1.nodeCommandRunner;
+        this.cloneUrl = options.cloneUrl;
+        this.githubToken = options.githubToken;
+    }
+    async prepare() {
+        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);
+            }
+            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);
+                }
+            }
+            const remoteHead = await this.runGit(["ls-remote", "--symref", "origin", "HEAD"], true);
+            const startRef = parseRemoteHead(remoteHead.stdout) ?? "HEAD";
+            await this.runGit([
+                "--git-dir",
+                this.repositoryPath,
+                "fetch",
+                "--prune",
+                "origin",
+                "+refs/heads/*:refs/heads/*",
+            ], true);
+            await this.runGit([
+                "--git-dir",
+                this.repositoryPath,
+                "worktree",
+                "add",
+                "-b",
+                this.branch,
+                this.worktreePath,
+                startRef,
+            ], false);
+        });
+    }
+    async cleanup() {
+        await withRepositoryLock(this.repositoryPath, async () => {
+            await this.runner
+                .run("git", ["--git-dir", this.repositoryPath, "worktree", "remove", "--force", this.worktreePath])
+                .catch(() => undefined);
+            await this.runner
+                .run("git", ["--git-dir", this.repositoryPath, "branch", "-D", this.branch])
+                .catch(() => undefined);
+            await this.runner
+                .run("git", ["--git-dir", this.repositoryPath, "worktree", "prune"])
+                .catch(() => undefined);
+        });
+    }
+    async runGit(args, authenticated) {
+        const credentialArgs = authenticated && this.githubToken
+            ? [
+                "-c",
+                'credential.helper=!f() { echo username=x-access-token; echo "password=$GITHUB_TOKEN"; }; f',
+            ]
+            : [];
+        const result = await this.runner.run("git", [...credentialArgs, ...args], {
+            env: this.githubToken
+                ? { ...process.env, GITHUB_TOKEN: this.githubToken, GIT_TERMINAL_PROMPT: "0" }
+                : { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+        });
+        if (result.code !== 0) {
+            throw new Error(`git ${args[0] ?? "command"} failed: ${result.stderr || result.stdout}`);
+        }
+        return result;
+    }
+}
+exports.GitWorktree = GitWorktree;
+async function withRepositoryLock(key, work) {
+    const previous = repositoryLocks.get(key) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolve) => {
+        release = resolve;
+    });
+    const queued = previous.then(() => current);
+    repositoryLocks.set(key, queued);
+    await previous;
+    try {
+        return await work();
+    }
+    finally {
+        release();
+        if (repositoryLocks.get(key) === queued)
+            repositoryLocks.delete(key);
+    }
+}
+async function pathExists(value) {
+    try {
+        await node_fs_1.promises.access(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function safePathSegment(value) {
+    const safe = value.replace(/[^A-Za-z0-9_.-]/g, "-").replace(/^-+|-+$/g, "");
+    if (!safe)
+        throw new Error("Cannot create a git worktree without a valid project/session identifier.");
+    return safe;
+}
+function normalizeCloneUrl(value) {
+    return value.trim().replace(/\.git$/, "").replace(/\/+$/, "").toLowerCase();
+}
+function parseRemoteHead(output) {
+    const match = output.match(/^ref:\s+(refs\/heads\/[A-Za-z0-9._/-]+)\s+HEAD$/m);
+    return match?.[1] ?? null;
+}

package/dist/machine-store.cjs

@@ -48,6 +48,9 @@ async function resolveMachineIdentity(configDir, apiBaseFallback) {
             token: envToken,
             name: process.env.NAVARCH_MACHINE_NAME ?? envId,
             api_base: process.env.NAVARCH_API_BASE ?? apiBaseFallback,
+            agent_type: process.env.NAVARCH_AGENT === "codex" || process.env.NAVARCH_AGENT === "claude-code"
+                ? process.env.NAVARCH_AGENT
+                : undefined,
         };
     }
     const stored = await loadMachineIdentity(configDir);

package/dist/prompt.cjs

@@ -10,13 +10,19 @@ exports.renderPrompt = renderPrompt;
  */
 function renderPrompt(task, bundle) {
     if (bundle.task_context) {
-        return [bundle.task_context.trim(), bundle.retry_context?.trim()]
+        const repositoryContext = bundle.repository
+            ? `Repository: ${bundle.repository.full_name} (${bundle.repository.url})\nLocal checkout: this session's isolated git worktree (current working directory).`
+            : null;
+        return [repositoryContext, bundle.task_context.trim(), bundle.retry_context?.trim()]
             .filter((section) => Boolean(section))
             .join("\n\n") + "\n";
     }
     const sections = [];
     sections.push(`# Task: ${task.summary}`);
     sections.push(`Type: ${task.task_type} | Repo: ${task.repo} | Environment: ${task.environment_scope}`);
+    if (bundle.repository) {
+        sections.push(`Repository URL: ${bundle.repository.url}\nLocal checkout: this session's isolated git worktree (current working directory).`);
+    }
     if (task.github_issue_url) {
         sections.push(`GitHub issue: ${task.github_issue_url}`);
     }

package/dist/sandbox.cjs

@@ -15,7 +15,7 @@ exports.SandboxUnavailableError = SandboxUnavailableError;
 exports.nodeCommandRunner = {
     run(cmd, args, opts = {}) {
         return new Promise((resolve, reject) => {
-            const child = (0, node_child_process_1.spawn)(cmd, args, { cwd: opts.cwd });
+            const child = (0, node_child_process_1.spawn)(cmd, args, { cwd: opts.cwd, env: opts.env });
             let stdout = "";
             let stderr = "";
             let settled = false;
@@ -91,14 +91,27 @@ class DockerSandbox {
     runner;
     workDir;
     image;
+    containerWorkDir;
+    sharedGitDir;
     constructor(opts) {
         this.name = containerName(opts.sessionId);
         this.runner = opts.runner ?? exports.nodeCommandRunner;
         this.workDir = node_path_1.default.join(opts.workspaceRoot, opts.sessionId);
         this.image = opts.image;
+        this.containerWorkDir = opts.containerWorkDir ?? null;
+        this.sharedGitDir = opts.sharedGitDir ?? null;
     }
     async create() {
         await node_fs_1.promises.mkdir(this.workDir, { recursive: true });
+        const mounts = this.containerWorkDir
+            ? [
+                "-v",
+                `${this.workDir}:${this.workDir}`,
+                ...(this.sharedGitDir ? ["-v", `${this.sharedGitDir}:${this.sharedGitDir}`] : []),
+                "-w",
+                this.containerWorkDir,
+            ]
+            : ["-v", `${this.workDir}:/workspace`, "-w", "/workspace"];
         const result = await this.runner.run("docker", [
             "run",
             "-d",
@@ -110,10 +123,7 @@ class DockerSandbox {
             "/tmp",
             "--tmpfs",
             "/run",
-            "-v",
-            `${this.workDir}:/workspace`,
-            "-w",
-            "/workspace",
+            ...mounts,
             this.image,
             "tail",
             "-f",
@@ -156,9 +166,13 @@ class DockerSandbox {
     }
     /** Force-removes the container and the host-side workspace mount. Best-effort: never throws. */
     async wipe() {
-        await this.runner.run("docker", ["rm", "-f", this.name]).catch(() => undefined);
+        await this.stop();
         await node_fs_1.promises.rm(this.workDir, { recursive: true, force: true }).catch(() => undefined);
     }
+    /** Stops/removes only the container; the session orchestrator owns worktree cleanup. */
+    async stop() {
+        await this.runner.run("docker", ["rm", "-f", this.name]).catch(() => undefined);
+    }
 }
 exports.DockerSandbox = DockerSandbox;
 function shellQuote(value) {

package/dist/session.cjs

@@ -14,14 +14,15 @@ const upload_cjs_1 = require("./upload.cjs");
 const prompt_cjs_1 = require("./prompt.cjs");
 const mcp_config_cjs_1 = require("./mcp-config.cjs");
 const logger_cjs_1 = require("./logger.cjs");
-/** Filename the generated platform MCP config is written under, inside the session's workDir (host-side; also /workspace inside the Docker sandbox -- see sandbox.cts's bind mount). */
+const git_worktree_cjs_1 = require("./git-worktree.cjs");
+/** Filename the generated platform MCP config is written under inside the session metadata directory. */
 const MCP_CONFIG_FILENAME = "mcp-config.json";
 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
- *   3. stand up a Docker sandbox, clone the repo, inject env vars
+ *   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
  *      lease throughout
@@ -29,11 +30,11 @@ const log = (0, logger_cjs_1.createLogger)("session");
  *      lease (recording which agent_type ran it)
  *   6. wipe the sandbox unconditionally
  *
- * NEEDS LIVE VERIFICATION: the full path requires a real Docker daemon, a
- * real `claude` (or `codex`) binary, and a live control-plane API — none of
- * which are available in this offline build environment. Unit tests exercise
- * each collaborator (api.cts, sandbox.cts, exit-conditions.cts, redact.cts,
- * adapters/*.cts) in isolation instead; see runtime/README.md.
+ * NEEDS LIVE VERIFICATION: the full path requires a real `claude` (or
+ * `codex`) binary and a live control-plane API; Docker-backed execution also
+ * requires a real Docker daemon. Unit tests exercise each collaborator
+ * (api.cts, sandbox.cts, exit-conditions.cts, redact.cts, adapters/*.cts) in
+ * isolation instead; see runtime/README.md.
  */
 async function runSession(deps, claimed, sessionId) {
     const { api, config } = deps;
@@ -41,7 +42,7 @@ async function runSession(deps, claimed, sessionId) {
     // The session's identity is the pre-allocated session id sent at claim time
     // (recorded on the lease by the dispatcher). Lease-scoped API calls
     // (heartbeat/complete/issue/transcript) still key on leaseId.
-    const workDir = node_path_1.default.join(config.workspaceRoot, sessionId);
+    const workDir = node_path_1.default.join(config.workspaceRoot, "sessions", 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");
@@ -56,6 +57,31 @@ async function runSession(deps, claimed, sessionId) {
         secrets = issued.secrets;
         registry.registerAll(secrets);
     }
+    const cloneUrl = bundle.repository?.clone_url ??
+        (task.repo ? `https://github.com/${task.repo.replace(/\.git$/, "")}.git` : null);
+    if (!cloneUrl) {
+        const failureSummary = `Project ${task.project_id} has no GitHub repository URL. Set it in Project settings before dispatching work.`;
+        await api.completeLease(leaseId, {
+            status: "failed",
+            report: failureSummary,
+            failure_summary: failureSummary,
+            evidence_urls: [],
+            cost: { tokens_in: 0, tokens_out: 0, cost_usd: 0 },
+            exit_status: "crashed",
+            agent_type: config.agentType,
+        });
+        secrets = {};
+        await node_fs_1.promises.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
+        return;
+    }
+    const gitWorktree = new git_worktree_cjs_1.GitWorktree({
+        workspaceRoot: config.workspaceRoot,
+        projectId: task.project_id,
+        taskId: task.id,
+        sessionId,
+        cloneUrl,
+        githubToken: secrets[bundle.repository?.credential_secret_name ?? "github-pat"],
+    });
     const abortController = new AbortController();
     let leaseLost = false;
     const heartbeatTimer = setInterval(() => {
@@ -73,16 +99,25 @@ async function runSession(deps, claimed, sessionId) {
             .completeLease(leaseId, {
             status: "failed",
             report: "Docker sandbox unavailable on this machine.",
+            failure_summary: "Docker sandbox unavailable on this machine.",
             evidence_urls: [],
             cost: { tokens_in: 0, tokens_out: 0, cost_usd: 0 },
             exit_status: "crashed",
             agent_type: config.agentType,
         })
             .catch((err) => log.warn(`complete() after docker-unavailable also failed: ${String(err)}`));
+        secrets = {};
+        await node_fs_1.promises.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
         return;
     }
     const sandbox = dockerAvailable
-        ? new sandbox_cjs_1.DockerSandbox({ sessionId, workspaceRoot: config.workspaceRoot, image: config.dockerImage })
+        ? new sandbox_cjs_1.DockerSandbox({
+            sessionId,
+            workspaceRoot: node_path_1.default.join(config.workspaceRoot, "sessions"),
+            image: config.dockerImage,
+            containerWorkDir: gitWorktree.worktreePath,
+            sharedGitDir: gitWorktree.repositoryPath,
+        })
         : null;
     // Platform MCP config (implementation-plan.md WP-07: "--mcp-config
     // pointing at the platform MCP server"): generated fresh per session,
@@ -90,8 +125,8 @@ async function runSession(deps, claimed, sessionId) {
     // auth app/api/mcp/route.ts requires -- see lib/navarch/mcp/context.ts),
     // unless the operator pinned a static override via NAVARCH_MCP_CONFIG_PATH
     // (e.g. pointing at a fake MCP server in local testing). Written to
-    // workDir (host path) so it also lands at /workspace/mcp-config.json
-    // inside the Docker sandbox (sandbox.cts binds workDir at /workspace) --
+    // workDir (host path), which Docker mode mounts at that same absolute path
+    // so worktree .git pointers and this config path remain valid --
     // the selected adapter (adapters/claude.cts or adapters/codex.cts) needs a
     // path valid in whichever environment it actually runs.
     let mcpConfigPath = config.mcpConfigPath;
@@ -102,13 +137,13 @@ async function runSession(deps, claimed, sessionId) {
             leaseId,
         });
         await node_fs_1.promises.writeFile(node_path_1.default.join(workDir, MCP_CONFIG_FILENAME), JSON.stringify(mcpConfig, null, 2), "utf8");
-        mcpConfigPath = sandbox ? `/workspace/${MCP_CONFIG_FILENAME}` : node_path_1.default.join(workDir, MCP_CONFIG_FILENAME);
+        mcpConfigPath = node_path_1.default.join(workDir, MCP_CONFIG_FILENAME);
     }
     try {
+        await gitWorktree.prepare();
         if (sandbox) {
             await sandbox.create();
             await sandbox.injectEnv(toEnvMap(secrets));
-            await sandbox.cloneRepo(task.repo, Boolean(secrets["github-pat"]));
         }
         // Picks the Claude Code or Codex adapter per NAVARCH_AGENT
         // (config.cts's `agentType`) — see adapters/index.cts#selectAdapter.
@@ -124,8 +159,8 @@ async function runSession(deps, claimed, sessionId) {
             bin,
             extraArgs,
             timeoutMs: config.sessionTimeoutMs,
-            env: secrets,
-            cwd: sandbox ? undefined : workDir,
+            env: toEnvMap(secrets),
+            cwd: sandbox ? undefined : gitWorktree.worktreePath,
             dockerExec: sandbox ? { containerName: sandbox.name, runner: sandbox_cjs_1.nodeCommandRunner } : undefined,
             signal: abortController.signal,
         });
@@ -164,10 +199,12 @@ async function runSession(deps, claimed, sessionId) {
     }
     catch (err) {
         log.error(`session ${leaseId} threw before completing: ${String(err)}`);
+        const failureSummary = (0, redact_cjs_1.redactText)(`Session crashed: ${String(err)}`, registry.list());
         await api
             .completeLease(leaseId, {
             status: "failed",
-            report: (0, redact_cjs_1.redactText)(`Session crashed: ${String(err)}`, registry.list()),
+            report: failureSummary,
+            failure_summary: failureSummary,
             evidence_urls: [],
             cost: { tokens_in: 0, tokens_out: 0, cost_usd: 0 },
             exit_status: "crashed",
@@ -179,7 +216,8 @@ async function runSession(deps, claimed, sessionId) {
         clearInterval(heartbeatTimer);
         secrets = {};
         if (sandbox)
-            await sandbox.wipe();
+            await sandbox.stop();
+        await gitWorktree.cleanup();
         await node_fs_1.promises.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
     }
 }
@@ -191,6 +229,14 @@ function toEnvMap(secrets) {
     }
     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";
     }
     return out;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.1",
-  "description": "Navarch machine-side session manager: registers a machine, claims tasks from the control-plane dispatcher, runs them in a Docker sandbox via the Claude Code or Codex adapter, and reports results back.",
+  "version": "0.1.2",
+  "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",
   "repository": {