@sagentlab/navarch-runtime 0.1.129 → 0.1.131

package/README.md

@@ -286,10 +286,70 @@ 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.
 
+## Live steering
+
+A person can send a message to a session that is already running, from the
+task page, Slack or the user MCP, without stopping it. A project opts in with
+`projects.steering_live_enabled`; while that is off, guidance behaves as
+described under [Active-task guidance](#active-task-guidance). The design is in
+[`docs/navarch/live-steering.md`](../docs/navarch/live-steering.md).
+
+The runtime sends a **capability record** with every claim, and the control
+plane resolves each message against it, so a message is never silently
+downgraded. Every adapter except the retired Gemini tombstone says
+`queue: boundary, interrupt: restart`. Claude Code on the host also says
+`steer: native` once a startup probe finds that the installed CLI accepts
+streaming input.
+
+| Sent as | Claude Code (host) | Every other adapter, and Claude Code in Docker |
+|---|---|---|
+| `steer` | Written to the running agent, which reads it at its next step. The turn is not stopped. | Becomes `queue`, with the fallback reason `steer_unsupported`. |
+| `queue` | Waits for the current turn to end, then the next turn resumes the conversation with it. | The same: the next turn carries it (`codex exec resume` for Codex; a fresh invocation with the full brief for the rest). |
+| `interrupt` | The agent process is stopped and the next turn, in the same lease and worktree, starts with the message (`claude -p --resume`). | The same. In Docker the sandbox container is restarted first, because stopping the agent stops the container. |
+
+How it works:
+
+- A long-poll (`GET /api/dispatch/:leaseId/steering?wait=20`) delivers a message
+  within about a second. The lease heartbeat carries the same payload as a
+  fallback, so a lost long-poll does not lose a message, but the heartbeat is
+  `NAVARCH_LEASE_HEARTBEAT_INTERVAL_MS` apart (five minutes by default) and the
+  control plane gives a `steer` or `interrupt` 90 s to be acknowledged, so such a
+  message then falls back to the next session. A control plane without the
+  endpoint answers 404 three times in a row and the runtime stops long-polling.
+- Each message is **acknowledged** once the agent has it: when the agent process
+  first produces output after starting with the message in its prompt (or five
+  seconds after it started without failing), or, for a native steer, when Claude
+  Code echoes the message back (`--replay-user-messages`) as proof that it read
+  it. A message the runtime cannot deliver, including one whose agent never
+  started, is acknowledged `failed`, and the control plane hands it to the next
+  session; nothing is dropped silently.
+- A message is introduced to the agent with a header that names the sender, the
+  time, a short id and the mode, for example
+  `[Message from Alex at 2026-10-21T12:03:00.000Z, id a1b2c3d4, sent as queue]`.
+  The id lets the agent ignore a repeat. After an interrupt the prompt also says
+  that the previous turn was stopped, so the agent inspects `git status`.
+- A completion that races a message is refused with `409 steering_pending`; the
+  runtime runs another turn instead of finishing.
+- A sender can cancel a queued message until it reaches the agent. The runtime
+  answers the cancel instead of delivering it.
+
+Set `NAVARCH_LIVE_STEERING=off` to make a machine a legacy runtime: it sends no
+capability record and only an explicit interrupt reaches it. Native steering
+needs host mode, a `claude` that lists `--input-format` and
+`--replay-user-messages` in `--help`, and no `--input-format` or
+`--output-format` in `NAVARCH_CLAUDE_EXTRA_ARGS`; otherwise Claude Code keeps
+the baseline above.
+
+`NAVARCH_LIVE_STEERING_SMOKE=1 npx vitest run tests/steering-live-smoke.test.cts`
+runs steer, queue and interrupt against the installed `claude` (add
+`NAVARCH_LIVE_STEERING_SMOKE_CODEX=1` for Codex) and an in-process port of the
+control-plane contract, and `NAVARCH_LIVE_SMOKE_REPORT=<file>` writes the
+evidence. It spends a few cents of provider usage per scenario.
+
 ## Active-task guidance
 
-Guidance added to a task that is already running is delivered on that
-task's next lease heartbeat (every
+Guidance added to a task that is already running, on a project without live
+steering, is delivered on that task's next lease heartbeat (every
 `NAVARCH_LEASE_HEARTBEAT_INTERVAL_MS`, five minutes by default). The runtime
 stops the current agent process and starts a **new agent turn**. This is a
 turn restart, not a new dispatch:
@@ -471,12 +531,13 @@ unchanged across the deployment.
 | `NAVARCH_POLL_INTERVAL_MS` | `30000` | 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 60-minute lease TTL (schema-design.md §4). |
+| `NAVARCH_LIVE_STEERING` | on | Tell the control plane this runtime takes live-steering messages (see [Live steering](#live-steering)). `off` makes it a legacy runtime. |
 | `NAVARCH_SESSION_TIMEOUT_MS` | `0` (disabled) | Optional absolute runtime budget across agent turns in a claimed session. |
 | `NAVARCH_SESSION_IDLE_TIMEOUT_MS` | `2700000` (45 min) | Stop after a continuously observed window with no stdout/stderr or process-tree CPU activity. `0` disables idle detection. |
 | `NAVARCH_OPENCODE_STARTUP_TIMEOUT_MS` | `120000` (2 min) | Stop OpenCode when it produces no stdout/stderr during startup. This catches provider auth/quota failures that leave its CLI process alive. `0` disables the startup deadline. |
 | `NAVARCH_WORKTREE_CLEANUP_INTERVAL_MS` | `3600000` (1 hour) | How often the runtime scans for session worktrees abandoned by a hard exit or host restart. |
 | `NAVARCH_WORKTREE_STALE_AFTER_MS` | `86400000` (24 hours) | Minimum inactivity age before an abandoned session worktree is removed. Active sessions are always protected. |
-| `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_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. For a project whose git proxy mode is not `off`, the control plane's commit identity (the GitHub App bot, or the consenting requester per the project's `git_attribution_mode`) replaces it, and a shared `prepare-commit-msg` hook adds `Navarch-Task` and any `Co-authored-by` trailer once. |
 | `NAVARCH_SANDBOX_MODE` | `host` | `host` uses the resources already available to the agent process. Set `docker` explicitly for container isolation. |
 | `NAVARCH_SANDBOX_PROFILE` | `trusted-development` | Named security profile for Docker sessions (`src/sandbox-profile.cts`): `trusted-development` (image-default user, uncapped, open egress), `untrusted-code` (non-root, 2 CPU / 4g / 512 PIDs, deny-by-default egress, read-only shared git), `elevated-verification` (non-root, 4 CPU / 8g / 2048 PIDs, egress limited to GitHub plus package registries). The default is the exact pre-profile flag set. |
 | `NAVARCH_SANDBOX_EGRESS_NETWORK` | _(unset)_ | Docker network that enforces a profile's egress allowlist. Docker cannot filter by domain itself, so an allowlist profile without this fails closed to `--network=none` and records the denial. |

package/dist/adapters/acp.cjs

@@ -6,6 +6,7 @@ const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_stream_1 = require("node:stream");
 const kill_agent_cjs_1 = require("../kill-agent.cjs");
+const types_cjs_1 = require("./types.cjs");
 /**
  * How long a cancelled agent may take to observe `session/cancel` and settle
  * the in-flight `session/prompt` before the subprocess is terminated. The
@@ -276,4 +277,5 @@ function describeError(error) {
 exports.acpAdapter = {
     agentType: "acp",
     run: runAcpAdapter,
+    steering: types_cjs_1.TURN_RESTART_STEERING,
 };

package/dist/adapters/antigravity.cjs

@@ -12,6 +12,7 @@ const node_string_decoder_1 = require("node:string_decoder");
 const config_cjs_1 = require("../config.cjs");
 const kill_agent_cjs_1 = require("../kill-agent.cjs");
 const antigravity_mcp_cjs_1 = require("./antigravity-mcp.cjs");
+const types_cjs_1 = require("./types.cjs");
 /** Documented agy 1.3.1 contract, not Gemini CLI's similarly named format.
  * https://antigravity.google/docs/cli/headless/
  * https://antigravity.google/docs/changelog (1.1.27, 1.1.28, 1.2.6, 1.2.10)
@@ -345,4 +346,4 @@ async function runDocker(options, args, input) {
     }
 }
 function quote(value) { return `'${value.replace(/'/g, `'\\''`)}'`; }
-exports.antigravityAdapter = { agentType: "antigravity", run: runAntigravityAdapter };
+exports.antigravityAdapter = { agentType: "antigravity", run: runAntigravityAdapter, steering: types_cjs_1.TURN_RESTART_STEERING };

package/dist/adapters/claude.cjs

@@ -2,9 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.claudeCodeAdapter = void 0;
 exports.runClaudeCodeAdapter = runClaudeCodeAdapter;
+exports.probeClaudeSteering = probeClaudeSteering;
 const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
 const exit_conditions_cjs_1 = require("../exit-conditions.cjs");
 const kill_agent_cjs_1 = require("../kill-agent.cjs");
+const types_cjs_1 = require("./types.cjs");
 const claude_conversation_cjs_1 = require("./claude-conversation.cjs");
 const adapter_capacity_cjs_1 = require("../adapter-capacity.cjs");
 const DEFAULT_CLAUDE_MODEL = "claude-opus-5-5";
@@ -163,6 +166,16 @@ async function runClaudeAttempt(options, automaticFallback) {
         if (!hasFlag(options.extraArgs, "--verbose"))
             args.push("--verbose");
     }
+    // Native steering (docs/navarch/live-steering.md section 5.3). The prompt then
+    // travels as the first stream-json user message and stdin stays open, so a
+    // later message reaches the agent at its next step. Only on the host path and
+    // only when the operator has not chosen the stream formats themselves.
+    const liveInput = options.liveInput && !options.dockerExec && !hasFlag(options.extraArgs, "--input-format") &&
+        !hasFlag(options.extraArgs, "--output-format")
+        ? options.liveInput
+        : undefined;
+    if (liveInput)
+        args.push("--input-format", "stream-json", "--replay-user-messages");
     args.push(...options.extraArgs);
     if (options.resumeSessionId)
         args.push("--resume", options.resumeSessionId);
@@ -180,7 +193,11 @@ async function runClaudeAttempt(options, automaticFallback) {
             env: { ...options.env, CLAUDE_CODE_EFFORT_LEVEL: options.reasoningEffort },
         }
         : options;
-    const raw = runOptions.dockerExec ? await runViaDocker(runOptions, args) : await runOnHost(runOptions, args);
+    const raw = runOptions.dockerExec
+        ? await runViaDocker(runOptions, args)
+        : liveInput
+            ? await runOnHostStreaming(runOptions, args, liveInput)
+            : await runOnHost(runOptions, args);
     return attachSession(attachUsage(raw), options);
 }
 /**
@@ -297,6 +314,228 @@ async function runOnHost(options, args) {
         });
     });
 }
+/** How long the process may stay open for a written message the agent has not echoed after its turn ended. */
+const UNECHOED_INPUT_GRACE_MS = 30_000;
+/**
+ * `claude -p --input-format stream-json --replay-user-messages`: the prompt is
+ * the first user message, and stdin stays open so a steering message written
+ * during the turn is injected at the agent's next step (spike S1 in
+ * docs/navarch/live-steering.md, verified against claude 2.1.304).
+ *
+ * `--replay-user-messages` makes Claude Code echo each user message back, with
+ * its uuid, when it takes the message into the conversation. That echo is the
+ * only proof of consumption, so the process is closed to input only once every
+ * written message has been echoed: Claude Code reads a message that is already
+ * in the pipe even after stdin ends and runs it as a further turn, but a
+ * message written after the process has finished is silently dropped, which is
+ * why `send` refuses once input is closed.
+ */
+async function runOnHostStreaming(options, args, live) {
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let killedByLeaseLoss = false;
+        let inputOpen = true;
+        let lineBuffer = "";
+        let graceTimer;
+        // Written steering messages the agent has not echoed yet.
+        const pending = new Map();
+        const child = (0, node_child_process_1.spawn)(options.bin, args, {
+            detached: process.platform !== "win32",
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env },
+        });
+        let attached = false;
+        const detach = () => {
+            if (!attached)
+                return;
+            attached = false;
+            live.attach(null);
+        };
+        child.stdin?.on("error", () => {
+            // The child exited before reading; `close` reports it, and the session
+            // takes back every message it never echoed.
+            inputOpen = false;
+            detach();
+        });
+        const writeUser = (id, text) => {
+            child.stdin?.write(`${JSON.stringify({
+                type: "user",
+                uuid: id,
+                message: { role: "user", content: [{ type: "text", text }] },
+            })}\n`);
+        };
+        const closeInput = () => {
+            if (!inputOpen)
+                return;
+            inputOpen = false;
+            clearTimeout(graceTimer);
+            detach();
+            child.stdin?.end();
+        };
+        const promptId = (0, node_crypto_1.randomUUID)();
+        writeUser(promptId, options.prompt);
+        attached = true;
+        live.attach({
+            send: (input) => {
+                if (!inputOpen || child.exitCode !== null || child.killed)
+                    return false;
+                try {
+                    writeUser(input.id, input.text);
+                }
+                catch {
+                    return false;
+                }
+                pending.set(input.id, { afterTurnEnd: false });
+                return true;
+            },
+        });
+        options.onProcessStarted?.(child.pid);
+        /** Reads one stdout line. Returns false for the line that must stay out of the transcript. */
+        const handleRecord = (line) => {
+            if (!line.startsWith("{"))
+                return true;
+            let record;
+            try {
+                record = JSON.parse(line);
+            }
+            catch {
+                return true;
+            }
+            if (typeof record !== "object" || record === null || Array.isArray(record))
+                return true;
+            const { type, uuid, isReplay } = record;
+            if (type === "user" && isReplay === true && typeof uuid === "string") {
+                // The echo of the task brief would copy the whole prompt into every
+                // transcript; a one-shot launch never prints it. Steering messages are
+                // kept: the echo shows where in the turn the agent took them in.
+                if (uuid === promptId)
+                    return false;
+                const entry = pending.get(uuid);
+                if (!entry)
+                    return true;
+                pending.delete(uuid);
+                live.consumed(uuid, entry.afterTurnEnd);
+            }
+            else if (type === "result") {
+                // A turn ended. A message written during it that was not echoed will
+                // start the next turn, so it now counts as consumed after the boundary.
+                for (const entry of pending.values())
+                    entry.afterTurnEnd = true;
+                if (pending.size === 0)
+                    closeInput();
+                else {
+                    clearTimeout(graceTimer);
+                    graceTimer = setTimeout(closeInput, UNECHOED_INPUT_GRACE_MS);
+                }
+            }
+            return true;
+        };
+        /** Passes on a stdout line to the result and the live transcript, unless it is withheld. */
+        const forwardLine = (line, terminator) => (handleRecord(line.trim()) ? line + terminator : "");
+        const timer = options.timeoutMs > 0 ? setTimeout(() => {
+            timedOut = true;
+            (0, kill_agent_cjs_1.killAgent)(child);
+        }, options.timeoutMs) : undefined;
+        const onAbort = () => {
+            killedByLeaseLoss = true;
+            (0, kill_agent_cjs_1.killAgent)(child);
+        };
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        if (options.signal?.aborted)
+            onAbort();
+        child.stdout.on("data", (d) => {
+            options.onActivity?.();
+            lineBuffer += d.toString();
+            let forwarded = "";
+            let newline = lineBuffer.indexOf("\n");
+            while (newline >= 0) {
+                forwarded += forwardLine(lineBuffer.slice(0, newline), "\n");
+                lineBuffer = lineBuffer.slice(newline + 1);
+                newline = lineBuffer.indexOf("\n");
+            }
+            if (forwarded) {
+                stdout += forwarded;
+                options.onOutput?.("stdout", forwarded);
+            }
+        });
+        child.stderr.on("data", (d) => {
+            options.onActivity?.();
+            const text = d.toString();
+            stderr += text;
+            options.onOutput?.("stderr", text);
+        });
+        const finish = (exitCode) => {
+            clearTimeout(timer);
+            clearTimeout(graceTimer);
+            inputOpen = false;
+            detach();
+            if (lineBuffer) {
+                // A final line with no newline.
+                const rest = forwardLine(lineBuffer, "");
+                lineBuffer = "";
+                if (rest) {
+                    stdout += rest;
+                    options.onOutput?.("stdout", rest);
+                }
+            }
+            options.signal?.removeEventListener("abort", onAbort);
+            resolve({ exitCode, timedOut, killedByLeaseLoss, stdout, stderr });
+        };
+        child.on("error", (err) => {
+            stderr += `\n${String(err)}`;
+            finish(null);
+        });
+        child.on("close", (code) => finish(code));
+    });
+}
+/** `claude --help`, cached per binary: it lists the flags this version accepts. */
+const claudeHelpCache = new Map();
+function readClaudeHelp(bin, env) {
+    const cached = claudeHelpCache.get(bin);
+    if (cached)
+        return cached;
+    const help = new Promise((resolve) => {
+        let output = "";
+        let settled = false;
+        const done = (text) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(text);
+        };
+        const child = (0, node_child_process_1.spawn)(bin, ["--help"], { env: { ...process.env, ...env }, stdio: ["ignore", "pipe", "ignore"] });
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            done("");
+        }, 10_000);
+        child.stdout?.on("data", (chunk) => { output += chunk.toString(); });
+        child.on("error", () => done(""));
+        child.on("close", (code) => done(code === 0 ? output : ""));
+    });
+    // A failed probe is not remembered: the CLI may be installed or fixed later.
+    void help.then((text) => { if (!text)
+        claudeHelpCache.delete(bin); });
+    claudeHelpCache.set(bin, help);
+    return help;
+}
+/**
+ * Native steering needs `--input-format stream-json` and
+ * `--replay-user-messages`, the host path (Docker `exec -i` has no streaming
+ * runner here), and the stream formats left to Navarch.
+ */
+async function probeClaudeSteering(context) {
+    if (context.sandboxMode !== "host")
+        return null;
+    if (hasFlag(context.extraArgs, "--input-format") || hasFlag(context.extraArgs, "--output-format"))
+        return null;
+    const help = await readClaudeHelp(context.bin, context.env);
+    if (!/--input-format\b/.test(help) || !/--replay-user-messages\b/.test(help))
+        return null;
+    return { steer: "native", queue: "boundary", interrupt: "restart" };
+}
 async function runViaDocker(options, args) {
     const { containerName, runner } = options.dockerExec;
     const quoted = [options.bin, ...args].map(shellQuote).join(" ");
@@ -351,6 +590,8 @@ exports.claudeCodeAdapter = {
     agentType: "claude-code",
     run: runClaudeCodeAdapter,
     resumesTurns: true,
+    steering: types_cjs_1.TURN_RESTART_STEERING,
+    probeSteering: probeClaudeSteering,
     // `usage` is per turn; `total_cost_usd` covers the whole resumed conversation.
     cumulativeResumeUsage: ["costUsd"],
     conversation: claude_conversation_cjs_1.claudeConversationRunner,

package/dist/adapters/codex.cjs

@@ -8,6 +8,7 @@ const node_fs_1 = require("node:fs");
 const exit_conditions_cjs_1 = require("../exit-conditions.cjs");
 const codex_pricing_cjs_1 = require("../codex-pricing.cjs");
 const kill_agent_cjs_1 = require("../kill-agent.cjs");
+const types_cjs_1 = require("./types.cjs");
 /**
  * Headless OpenAI Codex CLI adapter — the Codex sibling of claude.cts's
  * `runClaudeCodeAdapter`, implementing the same AgentAdapter interface
@@ -364,6 +365,7 @@ exports.codexAdapter = {
     agentType: "codex",
     run: runCodexAdapter,
     resumesTurns: true,
+    steering: types_cjs_1.TURN_RESTART_STEERING,
     // `exec resume` reports the thread's total_token_usage, not the turn's.
     cumulativeResumeUsage: ["tokensIn", "tokensOut", "cacheHitTokensIn", "costUsd"],
 };

package/dist/adapters/gemini.cjs

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.geminiAdapter = void 0;
 exports.runGeminiAdapter = runGeminiAdapter;
+const types_cjs_1 = require("./types.cjs");
 /** Tombstone for stale claims. Provider IDs and credentials are never aliased. */
 async function runGeminiAdapter(options) {
     return {
@@ -12,4 +13,4 @@ async function runGeminiAdapter(options) {
         stderr: "Gemini CLI is retired. Explicitly install and authenticate Antigravity, select antigravity, and update the task's runtime pin. No Gemini credentials or conversation IDs are transferred.",
     };
 }
-exports.geminiAdapter = { agentType: "gemini", run: runGeminiAdapter };
+exports.geminiAdapter = { agentType: "gemini", run: runGeminiAdapter, steering: types_cjs_1.NO_STEERING };

package/dist/adapters/muse.cjs

@@ -12,6 +12,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const node_crypto_1 = require("node:crypto");
 const kill_agent_cjs_1 = require("../kill-agent.cjs");
 const version_cjs_1 = require("../version.cjs");
+const types_cjs_1 = require("./types.cjs");
 const CANCEL_GRACE_MS = 2_000;
 const SHUTDOWN_GRACE_MS = 30_000;
 const TERMINATE_GRACE_MS = 2_000;
@@ -430,4 +431,4 @@ function spawnMuse(options) {
 }
 // Read-only Navi conversations are deliberately absent: an approval mode is
 // not a filesystem read boundary, and the SDK cannot yet prove that contract.
-exports.museAdapter = { agentType: "muse", run: runMuseAdapter };
+exports.museAdapter = { agentType: "muse", run: runMuseAdapter, steering: types_cjs_1.TURN_RESTART_STEERING };

package/dist/adapters/opencode.cjs

@@ -13,6 +13,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const config_cjs_1 = require("../config.cjs");
 const kill_agent_cjs_1 = require("../kill-agent.cjs");
 const opencode_providers_cjs_1 = require("./opencode-providers.cjs");
+const types_cjs_1 = require("./types.cjs");
 /**
  * Headless OpenCode adapter, fixture-pinned to the OpenCode JSON event
  * contract shared by V1 and V2 (verified against 1.19.1, 2.0.6 and 2.0.17):
@@ -541,4 +542,5 @@ function shellQuote(value) {
 exports.openCodeAdapter = {
     agentType: "opencode",
     run: runOpenCodeAdapter,
+    steering: types_cjs_1.TURN_RESTART_STEERING,
 };

package/dist/adapters/pi-local.cjs

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.localPiAdapter = void 0;
 exports.runLocalPiAdapter = runLocalPiAdapter;
+const types_cjs_1 = require("./types.cjs");
 const pi_cjs_1 = require("./pi.cjs");
 /** BYO Pi: native MCP, operator provider catalog, and a local OpenAI-compatible default. */
 async function runLocalPiAdapter(options) {
@@ -18,4 +19,4 @@ async function runLocalPiAdapter(options) {
     args.push("-p");
     return (0, pi_cjs_1.attachPiOutput)(await (0, pi_cjs_1.runOnHost)(options, args, true));
 }
-exports.localPiAdapter = { agentType: "pi-local", run: runLocalPiAdapter };
+exports.localPiAdapter = { agentType: "pi-local", run: runLocalPiAdapter, steering: types_cjs_1.TURN_RESTART_STEERING };

package/dist/adapters/pi.cjs

@@ -16,6 +16,7 @@ const node_fs_1 = require("node:fs");
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const kill_agent_cjs_1 = require("../kill-agent.cjs");
+const types_cjs_1 = require("./types.cjs");
 /**
  * Headless Pi coding-agent adapter (#885) — the process-side twin of the
  * Cloudflare hosted executor (worker/hosted-pi/lifecycle.ts). It invokes
@@ -444,4 +445,5 @@ function shellQuote(value) {
 exports.piAdapter = {
     agentType: "pi",
     run: runPiAdapter,
+    steering: types_cjs_1.TURN_RESTART_STEERING,
 };

package/dist/adapters/qoder.cjs

@@ -5,6 +5,7 @@ exports.runQoderAdapter = runQoderAdapter;
 const node_child_process_1 = require("node:child_process");
 const exit_conditions_cjs_1 = require("../exit-conditions.cjs");
 const kill_agent_cjs_1 = require("../kill-agent.cjs");
+const types_cjs_1 = require("./types.cjs");
 function hasFlag(args, flag) {
     return args.some((arg) => arg === flag || arg.startsWith(`${flag}=`));
 }
@@ -175,4 +176,5 @@ function shellQuote(value) {
 exports.qoderAdapter = {
     agentType: "qoder",
     run: runQoderAdapter,
+    steering: types_cjs_1.TURN_RESTART_STEERING,
 };

package/dist/adapters/types.cjs

@@ -1,2 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_STEERING = exports.TURN_RESTART_STEERING = void 0;
+/**
+ * Every adapter that runs inside session.cts's turn loop gets at least this:
+ * a queued message joins the next turn once the current one ends, and an
+ * interrupt stops the process and starts the next turn in the same worktree
+ * (resuming the conversation when `resumesTurns` is set). There is no channel
+ * for input during a turn, so `steer` is `none` and falls back to `queue`.
+ */
+exports.TURN_RESTART_STEERING = Object.freeze({
+    steer: "none",
+    queue: "boundary",
+    interrupt: "restart",
+});
+/** Retired adapters take no messages: every send falls back to the next session. */
+exports.NO_STEERING = Object.freeze({
+    steer: "none",
+    queue: "none",
+    interrupt: "none",
+});

package/dist/api.cjs

@@ -63,11 +63,16 @@ class NavarchApiClient {
         }
         const requestUrl = `${this.baseUrl}${pathname}`;
         const abortController = new AbortController();
+        const timeoutMs = opts?.timeoutMs ?? this.requestTimeoutMs;
         const requestTimeout = setTimeout(() => {
-            const timeoutError = new Error(`request timed out after ${this.requestTimeoutMs}ms`);
+            const timeoutError = new Error(`request timed out after ${timeoutMs}ms`);
             timeoutError.name = "TimeoutError";
             abortController.abort(timeoutError);
-        }, this.requestTimeoutMs);
+        }, timeoutMs);
+        const onCallerAbort = () => abortController.abort(opts?.signal?.reason);
+        opts?.signal?.addEventListener("abort", onCallerAbort, { once: true });
+        if (opts?.signal?.aborted)
+            onCallerAbort();
         try {
             const response = await this.fetchImpl(requestUrl, {
                 method,
@@ -96,6 +101,7 @@ class NavarchApiClient {
         }
         finally {
             clearTimeout(requestTimeout);
+            opts?.signal?.removeEventListener("abort", onCallerAbort);
         }
     }
     /** Global machine registration using the operator-configured enrollment secret. */
@@ -141,6 +147,29 @@ class NavarchApiClient {
             throw new Error("heartbeatLease: empty response from control plane.");
         return result;
     }
+    /**
+     * `GET /api/dispatch/:leaseId/steering?after_seq=N&wait=S`: the live-steering
+     * long-poll (docs/navarch/live-steering.md section 6.2). The server answers as
+     * soon as a message is dispatched to the lease or a cancel is requested, else
+     * after `waitSeconds` with the lease's unacked messages. It does not renew the
+     * lease. An older control plane answers 404.
+     */
+    async pollSteering(leaseId, opts) {
+        const query = new URLSearchParams({
+            after_seq: String(opts.afterSeq),
+            wait: String(opts.waitSeconds),
+        });
+        const result = await this.request("GET", `/api/dispatch/${encodeURIComponent(leaseId)}/steering?${query}`, undefined, 
+        // The server holds the request for up to `wait` seconds; leave room for it.
+        { timeoutMs: this.requestTimeoutMs + opts.waitSeconds * 1000, signal: opts.signal });
+        if (!result)
+            throw new Error("pollSteering: empty response from control plane.");
+        return result;
+    }
+    /** `POST /api/dispatch/:leaseId/steering/:messageId/ack` (section 6.3). A 409 means the message is no longer this lease's to deliver. */
+    async ackSteering(leaseId, messageId, ack) {
+        await this.request("POST", `/api/dispatch/${encodeURIComponent(leaseId)}/steering/${encodeURIComponent(messageId)}/ack`, ack, { allowEmpty: true });
+    }
     /** Best-effort, lease-scoped activity signal for connected machines. */
     async reportActivity(leaseId, phase, detail) {
         await this.request("POST", `/api/dispatch/${encodeURIComponent(leaseId)}/activity`, { phase, ...(detail ? { detail } : {}) }, { allowEmpty: true });

package/dist/claim-loop.cjs

@@ -4,6 +4,8 @@ exports.ClaimLoop = void 0;
 const node_crypto_1 = require("node:crypto");
 const api_cjs_1 = require("./api.cjs");
 const logger_cjs_1 = require("./logger.cjs");
+const index_cjs_1 = require("./adapters/index.cjs");
+const steering_cjs_1 = require("./steering.cjs");
 const log = (0, logger_cjs_1.createLogger)("claim");
 const MAX_CLAIM_BACKOFF_MS = 60_000;
 const pendingClaimSlot = "pending-claim-request";
@@ -77,11 +79,16 @@ class ClaimLoop {
             this.capacity.acquire(pendingClaimSlot);
             let claimed;
             try {
+                // The record is the primary adapter's. When the control plane assigns
+                // another advertised runtime, the session corrects it on its first
+                // lease heartbeat (session.cts).
+                const steeringCapabilities = (0, steering_cjs_1.liveSteeringCapabilities)((0, index_cjs_1.selectAdapter)(this.config.agentType), this.config);
                 claimed = await this.api.claim({
                     available_capacity: availableCapacity,
                     capabilities: this.config.capabilities,
                     agent_type: this.config.agentType,
                     runtimes: this.config.runtimes,
+                    ...(steeringCapabilities ? { steering_capabilities: steeringCapabilities } : {}),
                     session_id: sessionId,
                 });
             }