hilos-agent 0.11.2 → 0.11.4

package/README.md

@@ -1,13 +1,16 @@
 # hilos-agent
 
-Run **your own** coding agent — Claude Code, Codex, Cursor, opencode, Hermes, or any command — as
+Run **your own** coding agent — Claude Code, Codex, Cursor, opencode,
+Antigravity, Hermes, or any command — as
 an autonomous teammate inside a [hilos](https://hilos.sh) channel.
 
 It connects to hilos over MCP, watches for `@mentions` of your agent in a
 git-linked channel (including thread replies) and for **every message in a DM
 with your agent — no tag needed there**, runs your coding agent in a
-**local** checkout, and — by default — **opens a PR for review**. Your code and
-your git/`gh` credentials never leave your machine — hilos only relays messages.
+**local** checkout, and — by default — **opens a PR for review**. The checkout
+and your coding-provider/git credentials stay on your machine. Changes go to the
+configured Git remote; hilos receives bounded plans, progress, reports, and—when
+the pre-push gate is enabled—the proposal diff.
 
 ```
 hilos channel  ──MCP/HTTPS──▶  hilos-agent (your laptop)
@@ -19,13 +22,13 @@ hilos channel  ──MCP/HTTPS──▶  hilos-agent (your laptop)
          Changes  ▶  agent re-works with your note
 ```
 
-Prefer **approve-before-push**? Set `"gate": true` — the agent then posts the
-proposed diff as a card and pushes only after you Approve (nothing leaves your
-machine until then).
+Prefer **approve-before-push**? Set `"gate": true` — the agent posts a bounded
+proposed diff to hilos as a card, then pushes the change to the Git remote only
+after you Approve.
 
 ## Quick start
 
-In hilos: open your agent's profile → **Connect** → **Run in channel**. Copy the
+In hilos: open your agent's profile → **Connect agent** → **Run in channel**. Copy the
 terminal command and run it from inside your repo's folder. It waits at a hidden
 prompt; copy the private join code from Hilos and paste it there. The daemon
 matches the repo by its git remote, so no config is needed, and the reusable
@@ -39,30 +42,42 @@ npx hilos-agent@latest --join-stdin  # then paste the private join code when ask
 Previously copied `--join <blob>` commands remain compatible. New commands use
 stdin because the blob contains the agent token and should not live in argv.
 
-Running from elsewhere, or want to map several repos explicitly? Use a config:
+Running from elsewhere, or want to map several repos explicitly? Save this as
+`~/.hilos/agent.json` (or `./hilos-agent.json`). The file is strict JSON, so it
+cannot contain comments:
 
-```jsonc
-// ~/.hilos/agent.json  (or ./hilos-agent.json)
+```json
 {
   "url": "https://hilos.sh/api/mcp",
   "token": "mgo_…",
   "repos": { "your-org/your-repo": "/Users/you/code/your-repo" },
-  "codingCmd": "claude -p --permission-mode acceptEdits",  // safe default; see Permissions / autonomy. or "codex exec", "cursor-agent -p --output-format text --trust", "opencode run", "agy -p", any command
-  "codingModel": "",  // Codex tier ("most-capable" | "balanced" | "fastest"), resolved against this account's own model list; "" = the tool's default
-  "chatCmd": "",  // FAST command for chat replies + the plan-ack. Empty = derived from codingCmd's tool (codex daemons chat with codex, etc.); set to override
-  "webSearch": true,  // native public-web tools are on by default; false stops Hilos enablement/instructions
+  "codingCmd": "claude -p --permission-mode acceptEdits",
+  "codingModel": "",
+  "chatCmd": "",
+  "webSearch": true,
   "defaultBranch": "main",
-  "gate": false,               // default: open a PR directly. true = approve-before-push
-  "heartbeatMs": 180000,       // long runs post one "still working…" thread reply this often (0 = off, min 15s)
-  "chatTimeoutMs": 90000,      // cap a chat reply / plan-ack so a stalled model can't go silent
-  "longPollMs": 20000,         // ask the server to HOLD the mention poll and answer the moment work lands (0 = plain 5s polling; older servers fall back automatically)
-  "catchupMs": 86400000        // how far back a restart replays mentions from the persisted cursor (default 24h; 0 = restart at "now", the pre-0866 behavior)
+  "gate": false,
+  "heartbeatMs": 180000,
+  "chatTimeoutMs": 90000,
+  "longPollMs": 20000,
+  "catchupMs": 86400000
 }
 ```
 
+`codingCmd` above is the safe default; it can also be `codex exec`,
+`cursor-agent -p --output-format text --trust`, `opencode run`, `agy -p`, or a
+custom command. `codingModel` accepts the Codex tiers `most-capable`, `balanced`,
+or `fastest`; empty uses the tool's default. Empty `chatCmd` derives a fast chat
+command from `codingCmd`. `webSearch: false` disables hilos's web-search
+enablement, and `gate: true` switches to approve-before-push. `heartbeatMs: 0`
+disables the heartbeat (minimum nonzero value 15 seconds); `longPollMs: 0` uses
+plain five-second polling; `catchupMs: 0` restarts at now instead of replaying
+the default 24-hour window.
+
 **Staying responsive.** Every code task posts an **instant acknowledgement**
-(under a second), and — if your server exposes `edit_message` and a `chatCmd` is
-set — a quick **plan** ("On it — I'll do X, then open a PR") edits into it. On a
+(under a second), and — if your server exposes `edit_message` and a fast chat
+command can be resolved (explicit `chatCmd` or one derived from `codingCmd`) —
+a quick **plan** ("On it — I'll do X, then open a PR") edits into it. On a
 run longer than `heartbeatMs` (default 3 min; env `HILOS_HEARTBEAT_MS`, `0`
 disables, clamped to ≥15s) the agent posts **one progress reply** in the thread
 then edits it in place with elapsed time + the CLI's latest line — so the channel
@@ -98,7 +113,7 @@ The local daemon can give its coding and chat agents a narrow bridge to
 third-party WebMCP sites. It is off until you name exact origins and exact read
 tools in the machine's config:
 
-```jsonc
+```json
 {
   "webMcp": {
     "origins": {
@@ -152,8 +167,10 @@ access its operator granted. See the complete contract in
   it", "approved", or "go for it" after a request, in any language → a code run.
 - **Repo resolution** — the channel's linked repo is mapped to a local path via
   `repos`. No mapping → the agent says so and stops.
-- **Run** — it branches off `defaultBranch` (refuses a dirty tree), runs
-  `codingCmd` with the task, and stages the result.
+- **Run** — it temporarily stashes a dirty checkout, branches off
+  `defaultBranch`, runs `codingCmd` with the task, stages the result, and attempts
+  to restore the person's pre-existing work on every exit path. If `stash pop`
+  conflicts, the stash stays intact and the room gets the recovery command.
 - **Continue the thread's PR** — when the mention lands in a thread hilos says is
   about a pull request, the daemon works on *that* PR instead of opening a second
   one: it fetches the PR's head branch, commits there, and the same PR updates.
@@ -192,8 +209,7 @@ to a plain **local folder** and the agent works in it **directly** — it edits
 files in place (no branch, no commit, no PR), then posts a report of what changed.
 It's your own machine, so this is the same trust as running the CLI yourself.
 
-```jsonc
-// hilos-agent.json
+```json
 {
   "folders": { "<channelId>": "/Users/you/notes-site" }
 }
@@ -227,7 +243,7 @@ It's your own machine, so this is the same trust as running the CLI yourself.
 
 Add an optional per-channel deploy target next to `folders`:
 
-```jsonc
+```json
 {
   "folders": { "<channelId>": "/Users/you/notes-site" },
   "deploy": { "<channelId>": { "provider": "vercel", "prod": false } }
@@ -282,30 +298,29 @@ touching the token.
 
 ## Permissions / autonomy
 
-`codingCmd` decides how much the coding agent can do on its own. Three levels,
-safest first:
-
-- **`opencode run` (runtime-gated).** When the connected hilos server advertises
-  runtime permissions, the daemon runs OpenCode through an authenticated
-  loopback server and becomes its sole permission responder. A tool ask pauses
-  mechanically, posts a card in the run thread, and resumes only after a channel
-  member chooses **Allow once**, an exact harness-suggested **Always** rule, or
-  **Deny**. Missing transport, expiry, and cancellation all reject the tool
-  call. `opencode run --auto` deliberately bypasses these cards and keeps
-  OpenCode's dangerous auto-approve behavior.
-- **`--permission-mode acceptEdits` (default).** The agent edits files without
-  prompting, but in headless `claude -p` a step that needs bash — run the tests,
-  install a dep — has no interactive prompt to grant, so the task can **stall**.
-  Good when the work is edit-only; frustrating for anything that needs to run
-  commands.
-- **`--dangerously-skip-permissions` (recommended for independent agents).** Full
-  autonomy: the agent can run the tests, install deps, and finish hands-off.
-  Caution: it can run **any** command in the repo you point it at — only use it
-  on a repo and machine where that's acceptable. This is the option to pick if
-  you want the agent to actually work on its own.
-
-  ```jsonc
-  "codingCmd": "claude -p --dangerously-skip-permissions"
+There are two separate gates:
+
+- **Room runtime permissions.** When the workspace has granted runtime
+  permissions, current daemons put Claude Code, Codex, Cursor, and OpenCode
+  behind the same server-authorized card flow. A tool ask pauses mechanically
+  and resumes only after an eligible channel member chooses **Allow once**, an
+  exact harness-suggested **Always** rule, or **Deny**. Cursor and OpenCode use
+  ACP; Claude Code uses its permission-prompt tool; Codex uses `codex
+  mcp-server` because `codex exec` has no approval transport. Once a relay is
+  active, authority loss, expiry, cancellation, and transport failure all fail
+  closed. A positively unavailable old-CLI transport is the compatibility
+  exception: the daemon warns the room, then starts the ungated fallback.
+  Explicit vendor bypass modes such as `opencode run --auto` or Claude Code's
+  `--dangerously-skip-permissions` deliberately opt out of the cards.
+- **The CLI's own mode.** Without a workspace runtime grant, `codingCmd` remains
+  authoritative. The default Claude Code command uses
+  `--permission-mode acceptEdits`: it may edit without prompting, but a headless
+  command that needs additional approval can stall. For a fully independent
+  local agent, `--dangerously-skip-permissions` can run any command in the repo
+  you point it at, so use it only where that trust is acceptable.
+
+  ```json
+  { "codingCmd": "claude -p --dangerously-skip-permissions" }
   ```
 
 - **Approve-before-push (`gate:true`), most cautious.** Independent of the two
@@ -314,9 +329,9 @@ safest first:
 
 The default stays `acceptEdits`. Reach for `--dangerously-skip-permissions` when
 you want a truly hands-off teammate, and keep `gate:true` if you'd rather review
-before anything is pushed. When the workspace grants runtime approvals,
-OpenCode, Cursor, Claude Code, and Codex all pause on the same durable hilos
-permission card. A refusal or broken decision path fails closed.
+before anything is pushed. Runtime cards and the push gate are independent: one
+governs tools during the run, the other governs when the resulting code leaves
+the machine.
 
 ## Hooks — keep a raw Codex, Claude Code, or Cursor session in the room
 
@@ -365,8 +380,9 @@ npx hilos-agent@latest hooks print
   live card. The normal one-line `--join` flow does not need that file for
   replies: its token stays in daemon memory, and Hilos signs each session
   binding so the daemon can verify it before resuming local code.
-- Keep `hilos-agent` running to pick replies up. Hooks alone still stream live
-  steps, but MCP has no server-push channel that can wake an idle local client.
+- Keep `hilos-agent` running to pick replies up. Hooks only emit lifecycle
+  events; the daemon is the consumer that waits on the server's wake/long-poll
+  path and resumes the local session.
 
 **What you get:**
 - Team members see "Editing lib/x.ts" or "Running pnpm test" on the agent's live
@@ -376,12 +392,23 @@ npx hilos-agent@latest hooks print
   `hilos-agent` is running. Ambient messages, older thread history, and agent
   replies do not wake it. Current workspace roles are checked at pickup: guests,
   removed people, and unknown authors remain advisory and cannot start code.
+- Every initial mention job is also signed for its exact agent-token row and
+  answer room after final server revalidation. The daemon keeps that proof on a
+  job-local MCP client, so concurrent rooms cannot exchange project context. A
+  guest-visible room may be explicitly allowed to run code, but its task still
+  cannot pull workspace memory, Docs, Tasks, sibling conversations, or external
+  context into the answer.
 - The resumed turn receives bounded thread, room, and member context. Codex also
   gets a random loopback-only Hilos MCP URL for that turn, so it can search any
   room its linked owner can access when that owner minted the current key,
   without receiving the bearer token. Regenerate an older key from Connect to
   enable that inheritance. Admin-issued keys and other people's private rooms
-  stay outside the context.
+  stay outside the context. Hilos signs the turn's room into a short-lived
+  claim tied to that exact agent-token row; the loopback fixes the claim in an
+  upstream header that the coding child cannot replace. A missing, malformed,
+  cross-token, or conflicting room claim is refused, and a guest-visible turn
+  cannot use workspace-wide tools to pull private sibling context into its
+  answer.
 - The room's normal execution gate still applies; a chat-only guest room cannot
   resume local code.
 - Steps are coalesced into ~2s batches to keep traffic light.
@@ -422,8 +449,9 @@ An older server simply leaves it off.
 ### Run transcripts are opt-in
 
 The room gets what a teammate needs to see: a plan, live progress, a report, a
-PR. The coding tool's own stream is **not** part of that by default — the live
-card is an eight-step window and nothing keeps it after the run.
+PR. The coding tool's raw stream is **not** part of that by default. Current
+servers do keep a bounded, redacted set of structured activity facts through
+the runtime-neutral event protocol described above; that is not a transcript.
 
 Set `"uploadTranscripts": true` and the daemon, after posting its report, sends
 the tail of that run's stream to hilos, where it becomes the same transcript a
@@ -457,8 +485,14 @@ arguments can be visible to other processes on the machine, so use
 Likewise, prefer `--join-stdin` over the legacy `--join <blob>` form for a new
 connection.
 
-Env: `HILOS_TOKEN`, `HILOS_URL`, `HILOS_CHANNEL`, `CODING_CMD`, `HILOS_ONCE=1`,
-`HILOS_BACKFILL=1`, `HILOS_UPLOAD_TRANSCRIPTS=1|0`.
+See `hilos-agent --help` for the `init`, `webmcp`, `web doctor`, and `hooks`
+subcommands.
+
+Env: `HILOS_TOKEN`, `HILOS_URL`, `HILOS_CHANNEL`, `CODING_CMD`,
+`HILOS_CODING_MODEL`, `HILOS_CHAT_CMD`, `HILOS_WEB_SEARCH=1|0`,
+`HILOS_ACP=1|0`, `HILOS_HEARTBEAT_MS`, `HILOS_PROGRESS_MS`,
+`HILOS_CHAT_TIMEOUT_MS`, `HILOS_REPLY_BRIDGE=1|0`, `HILOS_ONCE=1`,
+`HILOS_BACKFILL=1`, and `HILOS_UPLOAD_TRANSCRIPTS=1|0`.
 
 ## Releasing
 

package/bin/hilos-agent.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 // hilos-agent — run your coding agent as an autonomous teammate in a hilos
-// channel. Picks up @mentions and opens a PR by default; --gate adds a human
-// approval checkpoint before the push. Your code + credentials never leave
-// your machine.
+// channel. Picks up @mentions and opens a PR by default; an optional pre-push
+// gate waits for a person's approval. The checkout and credentials stay local;
+// changes go to the configured Git remote and bounded run state goes to hilos.
 //
 // Usage:
 //   hilos-agent --join <blob>      connect with a copy-paste link from hilos

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hilos-agent",
-  "version": "0.11.2",
-  "description": "Run your own coding agent (Claude Code, Codex, Cursor, OpenCode, Hermes, or any command) as a teammate in a hilos room. It picks up mentions, makes the change locally, and opens a PR for human review.",
+  "version": "0.11.4",
+  "description": "Run your own coding agent (Claude Code, Codex, Cursor, OpenCode, Hermes, or any command) as a teammate in a hilos room. The checkout and credentials stay local; changes go to your configured Git remote as a PR for human review, and bounded progress and reports go to hilos.",
   "type": "module",
   "bin": {
     "hilos-agent": "bin/hilos-agent.mjs"

package/src/handler.mjs

@@ -5,7 +5,8 @@
 //
 // Turn an @mention in a git-linked channel into a branch + a coding-agent run.
 // By default it opens a PR for review; with gate:true it posts a proposed diff
-// and pushes only after approval. Your code + credentials stay local.
+// and pushes only after approval. The checkout and credentials stay local;
+// bounded progress/reports go to hilos and changes go to the Git remote.
 
 import { spawnSync } from "node:child_process";
 import { randomBytes, randomUUID } from "node:crypto";

package/src/mcp-loopback.mjs

@@ -28,6 +28,22 @@ const FORWARDED_REQUEST_HEADERS = [
 ];
 const MAX_HEADER_LENGTH = 4096;
 
+/** A v2 claim is the only format the server may use as ambient authority. This
+ * local shape check is not verification — the upstream server still checks the
+ * HMAC and exact token id — but it keeps 48-hour v1 state from advertising a
+ * loopback whose every call would be rejected after the rollout. */
+export function isV2AmbientBindingClaim(claim) {
+  if (typeof claim !== "string" || !claim || claim.length > MAX_HEADER_LENGTH) return false;
+  const [payload, signature, extra] = claim.split(".");
+  if (!payload || !signature || extra) return false;
+  try {
+    const parsed = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    return parsed?.v === 2 && typeof parsed?.tokenId === "string" && Boolean(parsed.tokenId);
+  } catch {
+    return false;
+  }
+}
+
 function readBody(request) {
   return new Promise((resolve, reject) => {
     let size = 0;
@@ -52,21 +68,19 @@ function readBody(request) {
  * @param {{
  *   url?: string,
  *   token?: string,
- *   channelId?: string,
+ *   bindingClaim?: string,
  *   fetchImpl?: typeof fetch,
  * }} [options]
  * @returns {Promise<{url: string, close: () => Promise<void>} | null>}
  */
-export async function startHilosMcpLoopback({ url, token, channelId = "", fetchImpl = fetch } = {}) {
-  if (!url || !token) return null;
+export async function startHilosMcpLoopback({ url, token, bindingClaim = "", fetchImpl = fetch } = {}) {
+  const ambientBinding = typeof bindingClaim === "string" ? bindingClaim.trim() : "";
+  // A continuation without its server-signed binding must not get a workspace
+  // MCP bridge whose guest-sensitive reads have no authoritative room context.
+  if (!url || !token || !isV2AmbientBindingClaim(ambientBinding)) return null;
   const nonce = randomBytes(24).toString("hex");
   const path = `/mcp/${nonce}`;
   const upstream = new URL(url);
-  // Preserve the room that caused this turn as MCP's effective context. This
-  // does not widen or narrow token access, but it keeps guest-room memory gates
-  // and other context-sensitive server policy active even when the model calls
-  // a workspace-scoped tool without a channelId argument.
-  if (channelId) upstream.searchParams.set("channelId", channelId);
   const upstreamRequests = new Set();
 
   const server = createServer(async (request, response) => {
@@ -83,6 +97,9 @@ export async function startHilosMcpLoopback({ url, token, channelId = "", fetchI
       const body = request.method === "POST" ? await readBody(request) : undefined;
       const headers = {
         authorization: `Bearer ${token}`,
+        // 1215 — fixed daemon-owned authority. This header is intentionally not
+        // in FORWARDED_REQUEST_HEADERS, so a coding child cannot replace it.
+        "x-hilos-ambient-binding": ambientBinding,
         // This short-lived proxy is part of the persistent daemon's return
         // path. Marking it on-demand would temporarily relabel a live daemon
         // and could suppress the offline/wakeup behavior after the turn.

package/src/mcp.mjs

@@ -11,6 +11,7 @@ const META_CLIENT_INFO = "io.modelcontextprotocol/clientInfo";
 const DEFAULT_TIMEOUT_MS = 35_000;
 const DISCOVERY_TIMEOUT_MS = 10_000;
 const RETRY_DELAY_MS = 250;
+const MAX_AMBIENT_BINDING_LENGTH = 4_096;
 
 function installedVersion() {
   try {
@@ -51,6 +52,13 @@ export class McpAuthStopError extends McpRequestError {
   }
 }
 
+export class McpAmbientBindingError extends McpRequestError {
+  constructor(message, details = {}) {
+    super(message, { ...details, ambientBindingRejected: true });
+    this.name = "McpAmbientBindingError";
+  }
+}
+
 function headerValue(value) {
   const text = String(value);
   return /^[\x20-\x7e]+$/.test(text)
@@ -233,6 +241,9 @@ export function makeClient({
       authorization: `Bearer ${token}`,
       "x-hilos-connection-mode": "daemon",
       ...(DAEMON_CLIENT ? { "x-hilos-client": DAEMON_CLIENT } : {}),
+      ...(options.ambientBinding
+        ? { "x-hilos-ambient-binding": options.ambientBinding }
+        : {}),
       ...(modern
         ? {
             "mcp-protocol-version": MCP_PROTOCOL_VERSION,
@@ -256,9 +267,23 @@ export function makeClient({
     let res;
     let json = null;
     let transportError = null;
+    let requestUrl = url;
+    if (options.ambientChannelId) {
+      try {
+        const scopedUrl = new URL(url);
+        scopedUrl.searchParams.set("channelId", options.ambientChannelId);
+        requestUrl = scopedUrl.toString();
+      } catch (error) {
+        bounded.cleanup();
+        throw new McpRequestError("hilos has an invalid MCP URL", {
+          cause: error,
+          malformedResponse: true,
+        });
+      }
+    }
     try {
       try {
-        res = await fetchImpl(url, {
+        res = await fetchImpl(requestUrl, {
           method: "POST",
           headers,
           body: JSON.stringify({ jsonrpc: "2.0", id: requestId, method, params: requestParams }),
@@ -347,7 +372,7 @@ export function makeClient({
     for (let attempt = 0; attempt < 2; attempt += 1) {
       try {
         const result = await request("server/discover", undefined, {
-          signal: options.signal,
+          ...options,
           timeoutMs: Math.min(timeoutMs, DISCOVERY_TIMEOUT_MS),
           protocolVersion: MCP_PROTOCOL_VERSION,
         });
@@ -411,6 +436,49 @@ export function makeClient({
     }
   }
 
+  /**
+   * Pin every call made by one queued daemon job to the room claim returned
+   * with that job. This is a closure, not mutable client state: concurrent
+   * work from different rooms can never overwrite or inherit another job's
+   * ambient privacy boundary.
+   */
+  function bindTool(bindingClaim, channelId) {
+    const bindingClaimAbsent = bindingClaim === undefined;
+    const ambientBinding =
+      typeof bindingClaim === "string" ? bindingClaim.trim() : "";
+    const ambientChannelId = typeof channelId === "string" ? channelId.trim() : "";
+    return async (name, args = {}, options = {}) => {
+      if (
+        !ambientChannelId ||
+        (!bindingClaimAbsent &&
+          (!ambientBinding || ambientBinding.length > MAX_AMBIENT_BINDING_LENGTH))
+      ) {
+        throw new McpAmbientBindingError("hilos returned an invalid ambient room binding", {
+          malformedResponse: true,
+        });
+      }
+      try {
+        return await tool(name, args, {
+          ...options,
+          ambientChannelId,
+          ...(ambientBinding ? { ambientBinding } : {}),
+        });
+      } catch (error) {
+        // A scoped 401 without the terminal-token bit means the bearer token
+        // still exists but this queued job's room proof was rejected (expired,
+        // rotated, or mismatched). Surface a distinct failure so the daemon can
+        // restart from its durable cursor instead of acknowledging lost work.
+        if (error?.status === 401 && error?.stop !== true) {
+          throw new McpAmbientBindingError(error.message, {
+            ...error,
+            cause: error,
+          });
+        }
+        throw error;
+      }
+    };
+  }
+
   // Full tool objects, schemas included. Never turn discovery errors into an
   // empty registry: that would silently downgrade a current daemon until its
   // next restart. One bounded retry handles a transient read failure.
@@ -440,5 +508,12 @@ export function makeClient({
     return (await listTools(options)).map((tool) => tool.name);
   }
 
-  return { rpc, tool, listTools, listToolNames, stopSignal: stopController.signal };
+  return {
+    rpc,
+    tool,
+    bindTool,
+    listTools,
+    listToolNames,
+    stopSignal: stopController.signal,
+  };
 }

package/src/reply-bridge.mjs

@@ -17,7 +17,10 @@ import { makeStreamParser } from "./agent-events.mjs";
 import { detectVendor, codeStreamArgs, createProgressEmitter } from "./progress-emitter.mjs";
 import { buildResumeArgs } from "./resume.mjs";
 import { commandArgv } from "./argv.mjs";
-import { startHilosMcpLoopback } from "./mcp-loopback.mjs";
+import {
+  isV2AmbientBindingClaim,
+  startHilosMcpLoopback,
+} from "./mcp-loopback.mjs";
 import {
   HOOK_STATE_DIR,
   hookConnectionKey,
@@ -255,11 +258,15 @@ function matchingSessions(sessions, { connectionKey = "" } = {}) {
   );
 }
 
-/** Persist a one-way credential scope only after the real hilos server accepts
- * the hook's signed binding claim. Re-read after the best-effort write so an IO
- * failure stays fail-closed. */
-function claimVerifiedSession(binding, connectionKey, stateDir) {
-  if (!binding?.sessionId || !binding?.bindingClaim || !connectionKey) return false;
+/** Persist a freshly server-verified v2 claim, optionally claiming a tokenless
+ * hook session for this credential at the same time. Re-read after the write so
+ * an IO failure or concurrent replacement stays fail-closed. */
+function persistVerifiedBinding(binding, nextClaim, stateDir, connectionKey = "") {
+  if (
+    !binding?.sessionId ||
+    !binding?.bindingClaim ||
+    !isV2AmbientBindingClaim(nextClaim)
+  ) return false;
   const state = readState(binding.sessionId, stateDir);
   if (!state || (state.connectionKey && state.connectionKey !== connectionKey)) return false;
   const current = (Array.isArray(state.bindings) ? state.bindings : []).find(
@@ -270,9 +277,27 @@ function claimVerifiedSession(binding, connectionKey, stateDir) {
       item?.agentId === binding.agentId,
   );
   if (!current) return false;
-  state.connectionKey = connectionKey;
+  current.bindingClaim = nextClaim;
+  if (connectionKey) state.connectionKey = connectionKey;
   writeState(binding.sessionId, state, stateDir);
-  return readState(binding.sessionId, stateDir)?.connectionKey === connectionKey;
+  const saved = readState(binding.sessionId, stateDir);
+  const savedBinding = saved?.bindings?.find(
+    (item) =>
+      item?.threadRootId === binding.threadRootId &&
+      item?.anchorMessageId === binding.anchorMessageId &&
+      item?.agentId === binding.agentId,
+  );
+  return savedBinding?.bindingClaim === nextClaim &&
+    (!connectionKey || saved?.connectionKey === connectionKey);
+}
+
+function bindingVerificationArgs(binding) {
+  return {
+    claim: binding.bindingClaim,
+    channelId: binding.channelId,
+    threadRootId: binding.threadRootId,
+    messageId: binding.anchorMessageId,
+  };
 }
 
 async function verifyBindingAuthority(binding, authority, tool, stateDir) {
@@ -284,14 +309,14 @@ async function verifyBindingAuthority(binding, authority, tool, stateDir) {
     !authority.agentId ||
     binding.agentId !== authority.agentId
   ) return false;
-  const verified = await tool("verify_session_binding", {
-    claim: binding.bindingClaim,
-    channelId: binding.channelId,
-    threadRootId: binding.threadRootId,
-    messageId: binding.anchorMessageId,
-  });
+  const verified = await tool("verify_session_binding", bindingVerificationArgs(binding));
   return verified?.valid === true &&
-    claimVerifiedSession(binding, authority.connectionKey, stateDir);
+    persistVerifiedBinding(
+      binding,
+      verified.bindingClaim,
+      stateDir,
+      authority.connectionKey,
+    );
 }
 
 function clearPendingDelivery(sessionId, deliveryId, stateDir = HOOK_STATE_DIR) {
@@ -675,12 +700,21 @@ function vendorLabel(vendor) {
  *   now?: () => number,
  *   log?: { log: (...args: any[]) => void },
  *   signal?: AbortSignal,
+ *   startLoopback?: typeof startHilosMcpLoopback,
  * }} deps
  */
 export async function handleReplyBridgeJob(
   { binding, replies: queuedReplies, context },
   cfg,
-  { tool, run = runCli, stateDir = HOOK_STATE_DIR, now = Date.now, log = console, signal },
+  {
+    tool,
+    run = runCli,
+    stateDir = HOOK_STATE_DIR,
+    now = Date.now,
+    log = console,
+    signal,
+    startLoopback = startHilosMcpLoopback,
+  },
 ) {
   // A second batch may have queued while the first continuation was running.
   // Re-read the durable processed set at execution time so the overlap is
@@ -692,7 +726,13 @@ export async function handleReplyBridgeJob(
   const processed = new Set(
     Array.isArray(currentBinding?.processedReplyIds) ? currentBinding.processedReplyIds : [],
   );
-  const liveBinding = currentBinding ? { ...binding, ...currentBinding } : binding;
+  const liveBinding = {
+    ...binding,
+    ...(currentBinding ?? {}),
+    // scanReplyBridge may have just claimed a tokenless hook session by writing
+    // the top-level key; carry that fresh authority into this already-built job.
+    connectionKey: currentState?.connectionKey || binding.connectionKey || "",
+  };
   const queuedIds = new Set(
     (queuedReplies || []).map((reply) => reply?.id).filter((id) => id && !processed.has(id)),
   );
@@ -733,11 +773,31 @@ export async function handleReplyBridgeJob(
     return { status: "skipped" };
   }
 
-  const loopback = liveBinding.vendor === "codex"
-    ? await startHilosMcpLoopback({
+  // Verify and rotate the claim against the current server immediately before
+  // exposing MCP. This upgrades persisted v1 state, prevents a new daemon from
+  // trusting an older server, and keeps active bindings ahead of the 48-hour
+  // claim expiry that successful continuations also renew locally.
+  const ambientVerification =
+    liveBinding.vendor === "codex" && liveBinding.bindingClaim
+      ? await tool("verify_session_binding", bindingVerificationArgs(liveBinding))
+          .catch(() => null)
+      : null;
+  const refreshedAmbientClaim =
+    ambientVerification?.valid === true &&
+    isV2AmbientBindingClaim(ambientVerification.bindingClaim) &&
+    persistVerifiedBinding(
+      liveBinding,
+      ambientVerification.bindingClaim,
+      stateDir,
+      liveBinding.connectionKey,
+    )
+      ? ambientVerification.bindingClaim
+      : "";
+  const loopback = refreshedAmbientClaim
+    ? await startLoopback({
         url: cfg?.url,
         token: cfg?.token,
-        channelId: liveBinding.channelId,
+        bindingClaim: refreshedAmbientClaim,
       }).catch(() => null)
     : null;
   const prompt = bridgePrompt(replies, context, { hilosMcp: Boolean(loopback) });

package/src/run.mjs

@@ -104,6 +104,9 @@ export async function run(
   // Match the typed client error by its stable cross-realm name. This also
   // works for embedding hosts and test doubles that do not share a constructor.
   const isAuthStop = (error) => error?.name === "McpAuthStopError";
+  const isAmbientBindingRejection = (error) =>
+    error?.name === "McpAmbientBindingError" ||
+    error?.ambientBindingRejected === true;
   const reportAuthStop = (error) => {
     if (!isAuthStop(error)) return false;
     emitStopping();
@@ -113,7 +116,7 @@ export async function run(
   const client = makeClient({ url: cfg.url, token: cfg.token });
   // Keep injected/older test clients compatible; the real makeClient always
   // provides this lifecycle signal and terminal auth still latches through it.
-  const { tool, listTools, listToolNames } = client;
+  const { tool, bindTool, listTools, listToolNames } = client;
   const stopSignal = client.stopSignal ?? new AbortController().signal;
   const abortFromAuthStop = () => runController.abort(stopSignal.reason);
   stopSignal.addEventListener("abort", abortFromAuthStop, { once: true });
@@ -145,6 +148,7 @@ export async function run(
   let iterateClaimRecoveryStore = null;
   let queue = null;
   let wake = null;
+  let fatalJobError = null;
   let reconcileClaimsOnce = async () => true;
   const withinShutdownReconcileBound = async (promise) => {
     let timer;
@@ -522,6 +526,10 @@ export async function run(
 
   async function safeHandle(message, channelId, jobSignal) {
     emit({ type: "task-start", channelId, messageId: message.id, text: (message.body || "").slice(0, 200) });
+    const taskTool =
+      typeof bindTool === "function"
+        ? bindTool(message.bindingClaim, channelId)
+        : tool;
     // 0779 — pull this mention's images to disk HERE, as the job starts, not
     // when it was enqueued. Downloading at enqueue meant a burst of image
     // mentions held every job's bytes (up to 4 x 10MB each) on the user's disk
@@ -548,7 +556,7 @@ export async function run(
       if (stopNoticed) return;
       stopNoticed = true;
       const who = typeof by === "string" && by.trim() ? by.trim() : null;
-      void tool("post_message", {
+      void taskTool("post_message", {
         channelId,
         parentId: message.parentId ?? null,
         body: who ? `Stopped by ${who} from the room.` : "Stopped from the room.",
@@ -559,7 +567,14 @@ export async function run(
       log.log(`→ task in ${channelId}: "${(message.body || "").slice(0, 80)}"`);
       // liveCfg so a job uses the latest model/permission/codingCmd at run time.
       const result = await handler(
-        { message: withImages, channelId, tool, me, caps, iterateClaimRecoveryStore },
+        {
+          message: withImages,
+          channelId,
+          tool: taskTool,
+          me,
+          caps,
+          iterateClaimRecoveryStore,
+        },
         liveCfg,
         undefined,
         { signal: jobSignal, onStopRequested },
@@ -568,7 +583,18 @@ export async function run(
     } catch (e) {
       emit({ type: "task-error", channelId, error: e?.message || String(e) });
       log.error(`handler error: ${e.message}`);
-      await tool("post_message", {
+      if (isAmbientBindingRejection(e)) {
+        // The job's room proof is no longer usable. Close intake synchronously
+        // before runJob unwinds so createQueue skips afterJob (and therefore
+        // cannot persist this mention's cursor), then restart from the durable
+        // cursor. Posting with the same rejected proof would only hide the
+        // failure behind a second 401.
+        fatalJobError ??= e;
+        runController.abort(e);
+        void queue.shutdown("ambient room binding rejected");
+        throw e;
+      }
+      await taskTool("post_message", {
         channelId,
         body: `Hit an error working on that: ${e.message}`,
       }).catch(() => {});
@@ -877,6 +903,8 @@ export async function run(
     await interruptibleSleep(pollAgainMs != null ? Math.min(base, pollAgainMs) : base);
   } while (!runSignal.aborted);
 
+  if (fatalJobError) throw fatalJobError;
+
   // A terminal response may first surface inside a concurrently running
   // handler while the poll loop is sleeping. The client latch aborts the run
   // immediately; preserve the original typed error after the loop has fenced