@staix/agent-hub 0.12.40 → 0.12.41

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 Issue and pull request numbers in the entries for 0.7.7 and earlier refer to the previous repository, archived on 2026-09-30 when this repository's history was rewritten; the one exception is the open smoke-check issue, formerly #12, which moved here as #1. Numbers in newer entries refer to this repository.
 
+## 0.12.41
+
+A one-fix release for a 0.12.40 regression.
+
+- `ahub codex` starts in a recorded Orca terminal again: 0.12.40 put the terminal launch id into the `--remote` URL (`ws://127.0.0.1:<port>/?launchId=...`) and Codex refused it with `invalid remote address`, because it accepts only `ws://host:port`. The launcher now passes `--remote-auth-token-env AGENTHUB_LAUNCH_ID`, Codex sends the id as the upgrade's bearer token, and the proxy reads it from there; `--remote-auth-token-env` joins the hub-owned Codex flags (#586).
+
 ## 0.12.40
 
 A bug-fix release. Held task offers settle on their own (#434), terminal recovery binds the live native owner (#482), a busy jcode takes an important message into its running turn (#572), and the check runner, hop-capped sends and planner pulls say what happened instead of hanging or claiming success (#558, #550, #531).

package/README.md

@@ -5,7 +5,7 @@ Codex, Kimi Code, Pi and a hub-owned local worker (Qwen Code, Jcode and Antigrav
 optional) share a message bus and a task board per project and one memory on the
 machine, each attached through its own native interface.
 
-Status: 0.12.40, control protocol 16. Bun + TypeScript, one loopback daemon per
+Status: 0.12.41, control protocol 16. Bun + TypeScript, one loopback daemon per
 project. Site: [agent-hub.staix.net](https://agent-hub.staix.net).
 
 ## What it does today
@@ -84,14 +84,15 @@ writes the running hub's own plugin bundle (#502). Since 0.12.37 the hub accepts
 Since 0.12.39 `ahub jcode` opens Jcode's native TUI on the hub-owned ACP session by
 default (#464); `--mode headless` or `ahub settings set peers.jcode.start_mode headless`
 keeps headless startup. On 0.12.39 the TUI launcher stopped after the first hub turn;
-0.12.40 opens it again (#564).
+0.12.40 opens it again (#564). On 0.12.40 `ahub codex` in a recorded Orca terminal
+failed with `invalid remote address`; 0.12.41 starts it again (#586).
 Cancellation needs a daemon advertising `task_cancel`; controlled downgrades
 refuse while cancelled rows exist. Live-test delegated CLI commands need a daemon
 advertising `cli_audit_delegated` and refuse with an upgrade remedy otherwise
 (#410). For local/Pi implementation, opt in to an available
 `checks.runner = "container"`; issue-backed owners also need authenticated
 spec access. PII work and designated reviewers retain their separate exemptions.
-See [release verification](docs/verification/2026-10-20-0.12.40.md) for the live legs
+See [release verification](docs/verification/2026-10-20-0.12.41.md) for the live legs
 still open, including #418 AC8, #438 AC7, the native console settings leg (#439 AC5),
 real upgrades with reattach (#463) and with a managed terminal and cancelled tasks
 (#478), a live headless Claude review (#223), a Claude session over 32 MiB (#517), a

package/docs/agent-notes/adapters.md

@@ -73,4 +73,4 @@ Scope: the Codex, ACP and Pi adapters and the Pi extension (turn `generation` an
 - Antigravity P1 (`src/adapters/agy/`): keep it optional, cloud, off roster by default, implementer/verifier only and pull-only. Until per-mode native prompt behavior is verified, reject hub permission/unattended mappings, headless starts and resume selectors; do not infer a quota source. The launcher refuses extra instances, any `agy --version` other than the pinned 1.4.2, and a hub without the `native_hook_launch` feature.
 - Only the person's `ahub agy` launcher manages `.agents/plugins/agent-hub/{plugin.json,mcp_config.json,hooks.json}`. Refuse linked/foreign entries before any write; cleanup only the matching launch. Never write project-level `.agents/hooks.json` or personal Gemini settings. The plugin MCP server is named `agent-hub_agent-hub` by the pinned native client.
 - Managed native facts use the definition's typed `NativeFactsPort` and the daemon's ephemeral `native_hook_launch` authority. Bind every observation to the daemon, launch, native session, project and current socket generation. Stop requires `fullyIdle`, normal termination and a fresh validated completion row; a missing readback keeps the peer busy. Native fact acknowledgement accepts only SDK ephemeral-message rows in the exact session transcript path.
-- `terminalOwner(launchId)` (`src/hub/peers.ts`, #482) answers only for the adapter's current native TUI owner bound to that launch (Codex: the claimed link with that `launchId`, both sockets open; Pi: a started, verified TUI owner on its requested session); a start acknowledgement is never ownership. A Codex link that is not the claimed one or has a closed socket never adopts a thread.
+- `terminalOwner(launchId)` (`src/hub/peers.ts`, #482) answers only for the adapter's current native TUI owner bound to that launch (Codex: the claimed link with that `launchId`, both sockets open; the launcher sends the id as the upgrade's bearer token through `--remote-auth-token-env`, because `codex --remote` refuses any path or query (#586); Pi: a started, verified TUI owner on its requested session); a start acknowledgement is never ownership. A Codex link that is not the claimed one or has a closed socket never adopts a thread.

package/docs/operations.md

@@ -1,6 +1,6 @@
 # Operations guide
 
-This guide describes ahub 0.12.40 and control protocol 16. Live verification
+This guide describes ahub 0.12.41 and control protocol 16. Live verification
 results and remaining prerequisites are recorded separately in [the smoke ledger](smoke.md).
 
 ## Agent-operated live verification
@@ -2044,21 +2044,21 @@ section is what they run.
 
 Upgrade running projects with the target release's own coordinator. It accepts
 a running source on control protocol 9 (0.6.x), 10 (0.7.0 through 0.12.0),
-11 (0.12.1 and 0.12.2), 12 (0.12.3), 13 (0.12.4 through 0.12.15), 14 (0.12.16), 15 (0.12.17 through 0.12.19) or 16 (0.12.20 through 0.12.40), and only
+11 (0.12.1 and 0.12.2), 12 (0.12.3), 13 (0.12.4 through 0.12.15), 14 (0.12.16), 15 (0.12.17 through 0.12.19) or 16 (0.12.20 through 0.12.41), and only
 a target on its own protocol, so the target's coordinator fits every supported
 source and carries every recovery fix released up to it. Protocol 8 and older
 (0.5.x and earlier) are refused as `manual-bootstrap-required`. Run from the
 project directory, without replacing the global CLI first:
 
 ```bash
-bunx --package @staix/agent-hub@0.12.40 ahub upgrade --to 0.12.40 --dry-run
-bunx --package @staix/agent-hub@0.12.40 ahub upgrade --to 0.12.40 --yes
+bunx --package @staix/agent-hub@0.12.41 ahub upgrade --to 0.12.41 --dry-run
+bunx --package @staix/agent-hub@0.12.41 ahub upgrade --to 0.12.41 --yes
 ```
 
 | Running now | Coordinator to use |
 | --- | --- |
 | 0.6.x (protocol 9) | the target's, through `bunx` as above |
-| 0.7.0 through 0.12.0 (protocol 10), 0.12.1 and 0.12.2 (protocol 11), 0.12.3 (protocol 12), 0.12.4 through 0.12.15 (protocol 13), 0.12.16 (protocol 14), 0.12.17 through 0.12.19 (protocol 15), 0.12.20 through 0.12.40 (protocol 16) | the target's, through `bunx` as above |
+| 0.7.0 through 0.12.0 (protocol 10), 0.12.1 and 0.12.2 (protocol 11), 0.12.3 (protocol 12), 0.12.4 through 0.12.15 (protocol 13), 0.12.16 (protocol 14), 0.12.17 through 0.12.19 (protocol 15), 0.12.20 through 0.12.41 (protocol 16) | the target's, through `bunx` as above |
 | any supported source, with the installed CLI already at the target | `ahub upgrade` below, which is the same coordinator |
 | 0.5.x or earlier (protocol 8 and older) | not supported: bootstrap by hand with the matching CLI |
 
@@ -2090,14 +2090,14 @@ projects first:
 
 ```bash
 ahub restart --dry-run
-ahub upgrade --to 0.12.40 --dry-run
+ahub upgrade --to 0.12.41 --dry-run
 ```
 
 Apply only after reviewing the plan:
 
 ```bash
 ahub restart --yes
-ahub upgrade --to 0.12.40 --yes
+ahub upgrade --to 0.12.41 --yes
 ahub recovery status [<operation-id>]
 ahub recovery resume [<operation-id>]
 ahub recovery abort [<operation-id>]

package/docs/quickstart.md

@@ -17,7 +17,7 @@ ahub setup                                # installs the Claude Code channel plu
 Or use the matching GitHub release:
 
 ```bash
-bun add -g github:STAIxBWLB/agent-hub#v0.12.40
+bun add -g github:STAIxBWLB/agent-hub#v0.12.41
 ahub setup
 ```
 
@@ -30,9 +30,13 @@ and upgrade or crash recovery, see the [operations guide](operations.md). To
 move running projects to a newer release later, run `ahub upgrade` in a
 terminal: it reviews the plan with you, applies it and follows it.
 
+## Upgrading to 0.12.41
+
+0.12.41 fixes one 0.12.40 regression: `ahub codex` in a recorded Orca terminal stopped at `invalid remote address`, because the launcher put the terminal launch id into the `--remote` URL, which Codex accepts only as `ws://host:port`. The id now travels as the upgrade's bearer token (#586). Coming from 0.12.39 or older, the 0.12.40 notes below apply too.
+
 ## Upgrading to 0.12.40
 
-Restart Claude sessions after upgrading: each keeps the plugin server it started with until restarted, so a restart loads the 0.12.40 plugin. That plugin asks Claude Code to list the hub tools again when a hub reconnect changes them (#490), and one from an older `ahub claude` launch is refused and stops reconnecting instead of reclaiming the peer (#551).
+Restart Claude sessions after upgrading: each keeps the plugin server it started with until restarted, so a restart loads the 0.12.41 plugin. That plugin asks Claude Code to list the hub tools again when a hub reconnect changes them (#490), and one from an older `ahub claude` launch is refused and stops reconnecting instead of reclaiming the peer (#551).
 
 `ahub jcode` opens its TUI again; on 0.12.39 it stopped after the first hub turn (#564). A busy Jcode now takes an `important` message into its running turn (#572), and `ahub doctor` lists the extra MCP servers the hub-owned Jcode loads from its config files. See [Jcode operations](operations.md#optional-jcode-peer).
 

package/docs/security.md

@@ -5,7 +5,7 @@ agent-hub connects agents that can each run commands. This page says what the hu
 ## Trust boundaries
 
 - **Other agents' text is untrusted.** Every message that crosses from one peer to another is framed as untrusted input: a channel tag with `meta.source` for Claude started with `ahub claude`; otherwise a fixed header line (`frame()`, `[agent-hub message from ...]`) with an instruction that says it is untrusted, the plugin's server instructions for a tools-only Claude reading `hub_inbox` and a standing instruction for the others. A message body cannot forge the hub's own headers: such lines are quoted (`sanitize`). Replies inherit a hop count capped at 3, so agents cannot ping-pong forever; neither a digest nor a steer can reset it.
-- **The control link is loopback plus a secret.** The daemon and the Codex proxy bind 127.0.0.1 only. The control WebSocket requires a per-run token (`.agenthub/state/control-token`, mode 600), and both servers refuse any request that carries an `Origin` header: any web page can open a WebSocket to localhost, and browsers always send `Origin`. External clients cannot claim the console user's id or a hub-managed peer's id.
+- **The control link is loopback plus a secret.** The daemon and the Codex proxy bind 127.0.0.1 only. The control WebSocket requires a per-run token (`.agenthub/state/control-token`, mode 600), and both servers refuse any request that carries an `Origin` header: any web page can open a WebSocket to localhost, and browsers always send `Origin`. The bearer header a Codex TUI sends to the proxy carries only the terminal launch id (#586): it binds terminal ownership and is not a credential. External clients cannot claim the console user's id or a hub-managed peer's id.
 - **Permission prompts stay on unless an operator selects a permission mode.** `ask` leaves native decisions unchanged. `ask-when-needed` grants scoped Claude file tools or Pi/local writes and edits; Kimi and Codex use their own native policies. `never-ask` requires explicit runtime confirmation or a person's console `y` for a config default at hub start. Until that config confirmation the peer runs in `ask`. Kimi's and `local`'s permission requests are relayed to the console and cancelled after `approvals.timeout_s` (default 120 s) of silence; the macOS notification for a waiting request carries the peer and the tool name only. The one exception is the hub's own tools (`hub_send` and the task tools, matched by exact name): Kimi's requests for them are approved once without a prompt and logged by name, the same trust Codex gets through `approval_mode` in the hub's config. They invoke hub-owned operations rather than arbitrary file or shell tools, and every call passes the hub's own checks. Identity comes from the exact permission title, or from the earlier tool-call title bound to the same call id and resolved against the configured MCP servers when the permission title contains argument JSON (Qwen). Payload text and unrelated display titles never establish identity. For ACP agents, a payload longer than the console shows is marked as cut and never offers a session-wide grant. Pi's write, edit, shell and git write requests are relayed the same way and can be answered `Always allow <tool> until Pi restarts`: later calls of that tool by the same Pi start skip the prompt but stay inside the path guard and sandbox. The grant covers every later call of that tool whatever its payload, is kept in memory only, cannot be given from the dashboard, and each call it allows is logged by tool name. A Pi or `local` request whose call was cancelled or whose turn ended is withdrawn at once: a later answer is refused and grants nothing, an `Always allow` included. One shell command runs without a hub approval: the `!command` a person types in the managed Pi TUI. It stays inside the same sandbox and denylist, and the hub takes it only from the verified owner process of a Pi in TUI mode, while Pi is idle, on a reservation that is used once; a model's own bash call never takes that path (issue #253). `--unattended` turns prompts off, says so loudly, and is never the default.
 - **A committed config cannot choose launch commands, credential files, data endpoints, permission modes or a wider sandbox.** The machine-local fields (`kimi_cmd`, `permission_modes`, `codex_bin`, `pi.cmd`, `checks`, `mlx.bin`, `mlx.runtimeDir`, `mlx.modelPath`, `omniroute.urls`, `omniroute.access_hosts`, the `omniroute` key files, `memory.worker_url`, `local.read_allow`, `local.bash_network`, `local.network_allow`, `terminal.open`, `instances`) apply only from a config file git confirms nobody committed (`instances` is read only from an untracked `.agenthub/config.local.json`; in `config.json` it is ignored even when untracked): `.agenthub/config.json` or `.agenthub/config.local.json`, matched by file identity so no other spelling the file system accepts slips past, and `.agenthub` itself not a committed symlink or submodule. Without a repository, or when git fails, they keep their defaults; an empty value always means the default. "Untracked" is answered by the repository that contains the project: a checkout copied or extracted into an unrelated repository, or into an ignored directory of one, is trusted like your own files. So a cloned repository cannot choose a launch command, a completion check, a gateway to send a key file to, a memory endpoint, a permission mode, the command that opens a terminal, or a wider sandbox. A command in `checks` runs as you, outside the local worker's sandbox, like a git hook. So do the `setup` and `verify` commands of a benchmark suite (issue #251): `ahub bench run <suite.json>` is a person's command, refused from an agent session, and it resets the work tree for each attempt, so it runs only with `bench.enabled`, at the root of a clean repository that tracks nothing under `.agenthub/`. Nothing in `routing.toml` or in task text is ever run. `routing.toml` and the other shared fields still come from the checkout, and they matter: `routing.toml` picks the models the local worker and the hub's inference use at your gateway and can turn the PII constraint off, and roles and budget shape who does what. Review them in a repository you do not trust. The hub's own git calls outside the sandbox (snapshots, facts, config trust, project discovery, memory recall, the bench runner) all use the single hardened implementation in the exact-pinned first-party `@staix/agent-mem/platform` package, re-exported by `src/hub/git.ts`, which disables the programs a repository's configuration can name — the file-system monitor, hooks, external diff, the pager, and the credential and askpass helpers, with prompts failing closed — so a config that ever does get written cannot run code with the hub's rights. Of those, the monitor, hooks and external diff are reachable by commands the hub issues (the planted-program test exercises all three; a `diff --no-index` reads the repo's config, so that call also passes `--no-ext-diff` and `--no-textconv`); the pager is not (every call pipes stdout). Credential and askpass helpers are disabled for project repositories; memory sync alone may use credentials for its own memory repository, without prompts. The cost: `core.fsmonitor=false` also turns off a person's enabled built-in monitor for the hub's own calls, so the per-turn snapshot's `add -A` scans the whole tree (the snapshot has a 10 s cap). git has no global switch for filter drivers, and of the hub's commands only the snapshot's `add`/`restore` would run one (its driver command lives in the protected `.git/config`).
 - **Telemetry holds no bodies.** `.agenthub/state/events.jsonl` (issue #40) records envelope ids, routing and sizes, task ids and states, overlapping paths and token counts, and the task id (with a PII flag) that each usage and token record is attributed to. It never records a message body, a task title or detail, and marks private (PII) envelopes and tasks as such. It stays on the machine; `ahub export` only prints it. Two opt-in stores copy numbers from it into your home directory, shared by every project on the machine (directories mode 700, files 600): research records (issue #247, `research.enabled`) in `~/.agenthub/research/` hold per approved task the ids, states, counts, tokens, times and PII flag the events hold, a person's label from a closed list, and a hash in place of the project id; benchmark runs (issue #251) in `~/.agenthub/bench/` hold suite name and hash, arm label, the attached peers' ids, models and permission modes, task ids, outcomes, exit codes, counts, tokens and times, never suite text or a command's output.

package/docs/verification/2026-10-20-0.12.41.md

@@ -0,0 +1,44 @@
+# 0.12.41 release verification
+
+This record covers release preparation and source review. It does not claim publication, installation, a running-hub restart or native/live acceptance beyond the manual Codex check below.
+
+## Candidate
+
+Version 0.12.41, control protocol 16 (unchanged; no daemon feature added), from merged main. The person reported the 0.12.40 failure `invalid remote address ws://127.0.0.1:4602/?launchId=...` from an Orca launch and directed on 2026-10-20 "이슈 586만 구현하고 배포하라" (implement and ship only #586).
+
+- Codex launch (#586, PR #587): the terminal launch id moved from the `--remote` URL query to `--remote-auth-token-env AGENTHUB_LAUNCH_ID`; the proxy reads `Authorization: Bearer <id>`; `--remote-auth-token-env` is a hub-owned Codex flag.
+- Still open (unchanged from 0.12.40): every live leg listed in [the 0.12.40 record](2026-10-20-0.12.40.md), including a real upgrade that exercises the `terminal_owner` record (#482).
+- Not in this release: everything else on the board; the person limited the release to #586.
+
+## Reviews
+
+| PR | Final head | Review | CI |
+| --- | --- | --- | --- |
+| #587 (#586) | 6c22808a | OCR delegation review of the source diff: no findings. codex-connector: P1 (the #482 leaf-wiring fixture still asserted the query) fixed at 6c22808a; P2 (negotiate bearer transport with a running 0.12.40 daemon) answered and declined: a 0.12.40 launcher's query makes Codex refuse to start, so a new daemon keeping query parsing serves no client, and a new CLI against an old daemon starts Codex and lacks only the terminal-owner proof until `ahub upgrade` restarts the daemon | exact head, success (both OS checks, 4/4 seeded shards) |
+
+## Manual check
+
+codex-cli 0.163.0, isolated `HOME`/`CODEX_HOME`, driven in a pty: `codex --remote ws://127.0.0.1:<p> --remote-auth-token-env X` sent `Authorization: Bearer <value of X>` on the loopback WebSocket upgrade. The same Codex refuses `--remote` with any path or query.
+
+## Document review
+
+Nine documents were stale against the 0.12.40 stamps (`e57b1936`), all through #587 and this release commit. Reviewed against `710c0771` and the release commit `644f9a45`.
+
+| Document | Result | Checked claims and correction |
+| --- | --- | --- |
+| `README.md` | corrected | Status 0.12.41; the 0.12.40 Codex launch failure and its fix (#586); verification link. |
+| `docs/quickstart.md` | corrected | Install pin `v0.12.41`; "Upgrading to 0.12.41" names the regression and points 0.12.39 users to the 0.12.40 notes; plugin restart names 0.12.41. |
+| `docs/operations.md` | corrected | Version line, protocol 16 range and the upgrade commands name 0.12.41. |
+| `docs/security.md` | corrected | The Codex proxy's bearer header carries only the launch id and is not a credential (#586). |
+| `docs/agent-notes/adapters.md` | corrected in #587 | `terminalOwner(launchId)`: the id arrives as the bearer token because `codex --remote` refuses a path or query. |
+| `docs/agent-notes/daemon.md` | no change | No daemon, recovery or control rule changed; the launch plan change is covered in `adapters.md`. |
+| `docs/agent-notes/tasks.md` | no change | No task or tool rule changed. |
+| `docs/agent-notes/tests.md` | no change | A fixture assertion changed; no test-gate rule changed. |
+| `src/cli/help.ts` | no change | No command, subcommand or flag changed; `--remote-auth-token-env` is refused as hub-owned, like `--remote`. |
+
+## Checks
+
+- PR #587's exact-head CI passed (table above). A local `scripts/check.sh` on the PR head was stopped by the whole-suite watchdog at 600 s under host load (load average 5.7); its only failures before the stop were the fixture fixed at 6c22808a and a `CLAUDE_CONFIG_DIR` leak from the agent session's Orca profile into `test/terminal-recovery.test.ts`, which passes with that variable unset. CI is the full gate for this release.
+- The release branch is merged main plus the version, release notes, bundle and document corrections. The bundle is rebuilt with the pinned Bun 1.4.2 (`scripts/build.mjs`) after `bun install --frozen-lockfile`; main's source reproduces the committed bundle byte-for-byte with that toolchain.
+- The stale stamps are restamped to the release commit `644f9a45`; `node scripts/check-docs.mjs --require-fresh` result is recorded in the release PR.
+- Exact-head CI on the release PR.

package/docs/verified.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "documents": {
     "README.md": {
-      "verifiedAgainst": "e57b1936bd234fad65aded000c921f5c9d7a3718",
+      "verifiedAgainst": "644f9a45a05e8dcaa8adf2a3febc1bedc9bd331b",
       "paths": [
         "package.json",
         "src/",
@@ -11,14 +11,14 @@
       ]
     },
     "docs/security.md": {
-      "verifiedAgainst": "e57b1936bd234fad65aded000c921f5c9d7a3718",
+      "verifiedAgainst": "644f9a45a05e8dcaa8adf2a3febc1bedc9bd331b",
       "paths": [
         "src/",
         "templates/"
       ]
     },
     "docs/operations.md": {
-      "verifiedAgainst": "e57b1936bd234fad65aded000c921f5c9d7a3718",
+      "verifiedAgainst": "644f9a45a05e8dcaa8adf2a3febc1bedc9bd331b",
       "paths": [
         "package.json",
         "src/",
@@ -35,7 +35,7 @@
       ]
     },
     "docs/quickstart.md": {
-      "verifiedAgainst": "e57b1936bd234fad65aded000c921f5c9d7a3718",
+      "verifiedAgainst": "644f9a45a05e8dcaa8adf2a3febc1bedc9bd331b",
       "paths": [
         "package.json",
         "src/",
@@ -43,7 +43,7 @@
       ]
     },
     "docs/agent-notes/adapters.md": {
-      "verifiedAgainst": "e57b1936bd234fad65aded000c921f5c9d7a3718",
+      "verifiedAgainst": "644f9a45a05e8dcaa8adf2a3febc1bedc9bd331b",
       "paths": [
         "src/adapters/",
         "src/pi/",
@@ -113,7 +113,7 @@
       ]
     },
     "docs/agent-notes/daemon.md": {
-      "verifiedAgainst": "e57b1936bd234fad65aded000c921f5c9d7a3718",
+      "verifiedAgainst": "644f9a45a05e8dcaa8adf2a3febc1bedc9bd331b",
       "paths": [
         "src/hub/daemon.ts",
         "src/hub/control-client.ts",
@@ -188,7 +188,7 @@
       ]
     },
     "docs/agent-notes/tasks.md": {
-      "verifiedAgainst": "e57b1936bd234fad65aded000c921f5c9d7a3718",
+      "verifiedAgainst": "644f9a45a05e8dcaa8adf2a3febc1bedc9bd331b",
       "paths": [
         "src/hub/tasks.ts",
         "src/hub/board.ts",
@@ -215,7 +215,7 @@
       ]
     },
     "docs/agent-notes/tests.md": {
-      "verifiedAgainst": "e57b1936bd234fad65aded000c921f5c9d7a3718",
+      "verifiedAgainst": "644f9a45a05e8dcaa8adf2a3febc1bedc9bd331b",
       "paths": [
         "test/",
         "scripts/check.sh",
@@ -242,7 +242,7 @@
       ]
     },
     "src/cli/help.ts": {
-      "verifiedAgainst": "e57b1936bd234fad65aded000c921f5c9d7a3718",
+      "verifiedAgainst": "644f9a45a05e8dcaa8adf2a3febc1bedc9bd331b",
       "paths": [
         "src/cli/main.ts",
         "src/cli/launch.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-hub",
-  "version": "0.12.40",
+  "version": "0.12.41",
   "description": "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   "license": "MIT",
   "type": "module",

package/plugins/agent-hub/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-hub",
-  "version": "0.12.40",
+  "version": "0.12.41",
   "description": "Channel between Claude Code and the agent-hub daemon: peer messages from Codex, Kimi and the local worker arrive as channel events; hub_send replies.",
   "author": {
     "name": "Young Joon Lee",

package/plugins/agent-hub/server.js

@@ -1841,7 +1841,7 @@ var init_codex_appserver = __esm(() => {
           fetch: (req, server) => {
             if (req.headers.has("origin"))
               return new Response("forbidden", { status: 403 });
-            const launchId = new URL(req.url).searchParams.get("launchId");
+            const launchId = /^Bearer (\S+)$/.exec(req.headers.get("authorization") ?? "")?.[1];
             if (server.upgrade(req, { data: { ...launchId && launchId.length <= 128 ? { launchId } : {} } }))
               return;
             return new Response("agent-hub codex proxy");
@@ -9396,22 +9396,20 @@ async function runCodexEntry(ctx) {
     ctx.executionCwd = res.executionCwd;
   }
   const control = readControl(stateDir);
-  let proxyUrl = res.proxyUrl;
+  let launchTokenEnv;
   try {
     if (control?.instanceId) {
       const terminal = await prepareTerminalLaunch(peer, cwd, stateDir, control.instanceId, ctx.instance ? { executionCwd: ctx.executionCwd } : undefined);
       if (terminal) {
         await registerTerminalLaunch(hub, terminal, process.env.AGENTHUB_RECOVERY_OPERATION);
-        const url = new URL(proxyUrl);
-        url.searchParams.set("launchId", terminal.launchId);
-        proxyUrl = url.toString();
+        launchTokenEnv = "AGENTHUB_LAUNCH_ID";
       }
     }
   } finally {
     hub.close();
   }
   const runningCodexBin = res.retainedLaunchConfig?.codex_bin;
-  const launch = buildLaunch("codex", args, { unattended: unattendedEnv, instance: peer, proxyUrl, codexBin: typeof runningCodexBin === "string" ? runningCodexBin : projectConfig().codex_bin });
+  const launch = buildLaunch("codex", args, { unattended: unattendedEnv, instance: peer, proxyUrl: res.proxyUrl, launchTokenEnv, codexBin: typeof runningCodexBin === "string" ? runningCodexBin : projectConfig().codex_bin });
   if (launch0.warning)
     console.error(launch0.warning);
   exec(launch.cmd, launch.args, "codex");
@@ -10426,7 +10424,7 @@ function codexNativeLaunch(ctx) {
     throw new Error("codex proxy url is missing");
   return nativeLaunchPlan({
     cmd: ctx.codexBin ?? "codex",
-    args: ["--enable", "tui_app_server", "--remote", ctx.proxyUrl, ...unattended ? ["--dangerously-bypass-approvals-and-sandbox"] : [], ...passthrough],
+    args: ["--enable", "tui_app_server", "--remote", ctx.proxyUrl, ...ctx.launchTokenEnv ? ["--remote-auth-token-env", ctx.launchTokenEnv] : [], ...unattended ? ["--dangerously-bypass-approvals-and-sandbox"] : [], ...passthrough],
     unattended,
     ...warning
   }, ctx);
@@ -10434,7 +10432,7 @@ function codexNativeLaunch(ctx) {
 var CODEX_LAUNCH_POLICY;
 var init_native_cli_codex_launch = __esm(() => {
   init_native_cli_launch_common();
-  CODEX_LAUNCH_POLICY = Object.freeze({ hubSwitches: Object.freeze(["--unattended", "--safe", "--new"]), ownedFlags: Object.freeze(["--remote", "--yolo", "--dangerously-bypass-approvals-and-sandbox"]), unattended: true, passthrough: true });
+  CODEX_LAUNCH_POLICY = Object.freeze({ hubSwitches: Object.freeze(["--unattended", "--safe", "--new"]), ownedFlags: Object.freeze(["--remote", "--remote-auth-token-env", "--yolo", "--dangerously-bypass-approvals-and-sandbox"]), unattended: true, passthrough: true });
 });
 
 // src/hub/events.ts
@@ -10732,7 +10730,7 @@ var init_builtin_metadata = __esm(() => {
         conductorStartable: true,
         unattended: true,
         hubSwitches: switches,
-        ownedFlags: Object.freeze(["--remote", "--yolo", "--dangerously-bypass-approvals-and-sandbox"])
+        ownedFlags: Object.freeze(["--remote", "--remote-auth-token-env", "--yolo", "--dangerously-bypass-approvals-and-sandbox"])
       },
       identity: { mcp: "env" },
       permission: {
@@ -10902,7 +10900,7 @@ var init_builtin_metadata = __esm(() => {
         conductorStartable: true,
         unattended: true,
         hubSwitches: switches,
-        ownedFlags: Object.freeze(["--remote", "--yolo", "--dangerously-bypass-approvals-and-sandbox"])
+        ownedFlags: Object.freeze(["--remote", "--remote-auth-token-env", "--yolo", "--dangerously-bypass-approvals-and-sandbox"])
       },
       identity: { mcp: "env" },
       permission: {
@@ -18418,7 +18416,7 @@ init_spec_read();
 // package.json
 var package_default = {
   name: "@staix/agent-hub",
-  version: "0.12.40",
+  version: "0.12.41",
   description: "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   license: "MIT",
   type: "module",

package/src/adapters/codex-appserver.ts

@@ -145,7 +145,7 @@ export class CodexPeer extends BasePeer {
       fetch: (req, server) => {
         // Browsers always send Origin on WebSocket upgrades; the TUI never does.
         if (req.headers.has("origin")) return new Response("forbidden", { status: 403 });
-        const launchId = new URL(req.url).searchParams.get("launchId");
+        const launchId = /^Bearer (\S+)$/.exec(req.headers.get("authorization") ?? "")?.[1]; // codex --remote-auth-token-env (#586)
         if (server.upgrade(req, { data: { ...(launchId && launchId.length <= 128 ? { launchId } : {}) } as Link })) return undefined;
         return new Response("agent-hub codex proxy");
       },

package/src/adapters/definitions/builtin-metadata.ts

@@ -93,7 +93,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     api: 1, kind: "codex", displayName: "Codex", family: "codex", transport: "codex-appserver",
     roles: Object.freeze(["implementer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
     start: { create: createCodex, daemonPort: "codex-appserver", forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: codexNativeLaunch, version: codexObservedVersion, ...CODEX_LAUNCH_POLICY, conductorStartable: true,
-      unattended: true, hubSwitches: switches, ownedFlags: Object.freeze(["--remote", "--yolo", "--dangerously-bypass-approvals-and-sandbox"]) },
+      unattended: true, hubSwitches: switches, ownedFlags: Object.freeze(["--remote", "--remote-auth-token-env", "--yolo", "--dangerously-bypass-approvals-and-sandbox"]) },
     identity: { mcp: "env" },
     permission: { trackUnattended: true, modes: { ask: { kind: "native-only", note: "restore the session's captured native approval policy" },
       "ask-when-needed": { kind: "codex-approval", policy: "on-request" }, "never-ask": { kind: "codex-approval", policy: "never" } },
@@ -180,7 +180,7 @@ export const BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition[] = Ob
     api: 1, kind: "codex", displayName: "Codex", family: "codex", transport: "codex-appserver",
     roles: Object.freeze(["implementer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
     start: { forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: ctx => compatibilityLaunch("codex", ctx), conductorStartable: true,
-      unattended: true, hubSwitches: switches, ownedFlags: Object.freeze(["--remote", "--yolo", "--dangerously-bypass-approvals-and-sandbox"]) },
+      unattended: true, hubSwitches: switches, ownedFlags: Object.freeze(["--remote", "--remote-auth-token-env", "--yolo", "--dangerously-bypass-approvals-and-sandbox"]) },
     identity: { mcp: "env" },
     permission: { modes: { ask: { kind: "native-only", note: "restore the session's captured native approval policy" },
       "ask-when-needed": { kind: "codex-approval", policy: "on-request" }, "never-ask": { kind: "codex-approval", policy: "never" } },

package/src/adapters/definitions/native-cli-codex-launch.ts

@@ -1,13 +1,13 @@
 import type { LaunchContext, LaunchPlan } from "../registry-types.ts";
 import { nativeLaunchArguments, nativeLaunchPlan } from "./native-cli-launch-common.ts";
 
-export const CODEX_LAUNCH_POLICY = Object.freeze({ hubSwitches: Object.freeze(["--unattended", "--safe", "--new"]), ownedFlags: Object.freeze(["--remote", "--yolo", "--dangerously-bypass-approvals-and-sandbox"]), unattended: true, passthrough: true });
+export const CODEX_LAUNCH_POLICY = Object.freeze({ hubSwitches: Object.freeze(["--unattended", "--safe", "--new"]), ownedFlags: Object.freeze(["--remote", "--remote-auth-token-env", "--yolo", "--dangerously-bypass-approvals-and-sandbox"]), unattended: true, passthrough: true });
 export function codexNativeLaunch(ctx: LaunchContext): LaunchPlan {
   const { passthrough, unattended, warning } = nativeLaunchArguments("codex", ctx, CODEX_LAUNCH_POLICY);
   if (!ctx.proxyUrl) throw new Error("codex proxy url is missing");
   return nativeLaunchPlan({
     cmd: ctx.codexBin ?? "codex",
-    args: ["--enable", "tui_app_server", "--remote", ctx.proxyUrl, ...(unattended ? ["--dangerously-bypass-approvals-and-sandbox"] : []), ...passthrough],
+    args: ["--enable", "tui_app_server", "--remote", ctx.proxyUrl, ...(ctx.launchTokenEnv ? ["--remote-auth-token-env", ctx.launchTokenEnv] : []), ...(unattended ? ["--dangerously-bypass-approvals-and-sandbox"] : []), ...passthrough],
     unattended,
     ...warning,
   }, ctx);

package/src/adapters/definitions/native-cli-entry-codex.ts

@@ -20,18 +20,18 @@ export async function runCodexEntry(ctx: NativeCliEntryContext): Promise<void> {
     ctx.executionCwd = res.executionCwd;
   }
   const control = readControl(stateDir);
-  let proxyUrl = res.proxyUrl;
+  let launchTokenEnv: string | undefined;
   try {
     if (control?.instanceId) {
       const terminal = await prepareTerminalLaunch(peer, cwd, stateDir, control.instanceId, ctx.instance ? { executionCwd: ctx.executionCwd } : undefined);
       if (terminal) {
         await registerTerminalLaunch(hub, terminal, process.env.AGENTHUB_RECOVERY_OPERATION);
-        const url = new URL(proxyUrl); url.searchParams.set("launchId", terminal.launchId); proxyUrl = url.toString();
+        launchTokenEnv = "AGENTHUB_LAUNCH_ID"; // codex --remote takes only ws://host:port, so the id rides the bearer header (#586)
       }
     }
   } finally { hub.close(); }
   const runningCodexBin = res.retainedLaunchConfig?.codex_bin;
-  const launch = buildLaunch("codex", args, { unattended: unattendedEnv, instance: peer, proxyUrl, codexBin: typeof runningCodexBin === "string" ? runningCodexBin : projectConfig().codex_bin });
+  const launch = buildLaunch("codex", args, { unattended: unattendedEnv, instance: peer, proxyUrl: res.proxyUrl, launchTokenEnv, codexBin: typeof runningCodexBin === "string" ? runningCodexBin : projectConfig().codex_bin });
   if (launch0.warning) console.error(launch0.warning);
   exec(launch.cmd, launch.args, "codex");
 }

package/src/adapters/registry-types.ts

@@ -29,6 +29,8 @@ export interface LaunchContext {
   userArgs: string[];
   unattended: boolean;
   proxyUrl?: string;
+  /** Env var holding the terminal launch id; Codex sends it as the proxy upgrade's bearer token (#586). */
+  launchTokenEnv?: string;
   codexBin?: string;
   statusLine?: StatusLineTee;
   facts?: FactsHook;

package/src/cli/launch.ts

@@ -329,7 +329,7 @@ export function sessionSettings(tee?: StatusLineTee, facts?: FactsHook): string
 export function buildLaunch(
   tool: "claude" | "codex",
   userArgs: string[],
-  ctx: { instance?: string; unattended: boolean; proxyUrl?: string; codexBin?: string; statusLine?: StatusLineTee; facts?: FactsHook; preview?: boolean },
+  ctx: { instance?: string; unattended: boolean; proxyUrl?: string; launchTokenEnv?: string; codexBin?: string; statusLine?: StatusLineTee; facts?: FactsHook; preview?: boolean },
 ): Launch {
   const adapter = definitionOf(tool);
   if (!adapter) throw new Error("native launch definition unavailable");