@jbkjr/relay 0.0.0-stage → 1.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/LICENSES/Apache-2.0.txt +201 -0
- package/LICENSES/README.md +19 -0
- package/LICENSES/codex-NOTICE.txt +6 -0
- package/README.md +386 -2
- package/SECURITY.md +145 -0
- package/adapters/briefs/claude.md +43 -0
- package/adapters/briefs/codex.md +56 -0
- package/adapters/briefs/models.json +33 -0
- package/adapters/build.mjs +8 -0
- package/adapters/claude/.claude-plugin/marketplace.json +13 -0
- package/adapters/claude/relay/.claude-plugin/plugin.json +5 -0
- package/adapters/claude/relay/agents/codex.md +21 -0
- package/adapters/claude/relay/agents/operator.md +21 -0
- package/adapters/claude/relay/skills/ask/SKILL.md +20 -0
- package/adapters/claude/relay/skills/chat/SKILL.md +13 -0
- package/adapters/claude/relay/skills/delegate/SKILL.md +21 -0
- package/adapters/claude/relay/skills/discuss/SKILL.md +19 -0
- package/adapters/claude/relay/skills/review/SKILL.md +21 -0
- package/adapters/claude/relay/skills/tree/SKILL.md +10 -0
- package/adapters/claude/relay/skills/write-for-codex/SKILL.md +78 -0
- package/adapters/codex/.agents/plugins/marketplace.json +20 -0
- package/adapters/codex/AGENTS.snippet.md +5 -0
- package/adapters/codex/relay/.codex-plugin/plugin.json +6 -0
- package/adapters/codex/relay/skills/relay-ask/SKILL.md +20 -0
- package/adapters/codex/relay/skills/relay-chat/SKILL.md +13 -0
- package/adapters/codex/relay/skills/relay-delegate/SKILL.md +21 -0
- package/adapters/codex/relay/skills/relay-discuss/SKILL.md +19 -0
- package/adapters/codex/relay/skills/relay-review/SKILL.md +21 -0
- package/adapters/codex/relay/skills/relay-tree/SKILL.md +10 -0
- package/adapters/codex/relay/skills/relay-write-for-claude/SKILL.md +66 -0
- package/adapters/generate.mjs +124 -0
- package/bin/relay +59 -0
- package/codex-pin.json +12 -0
- package/dist/backends/acp.js +1424 -0
- package/dist/backends/claude.js +890 -0
- package/dist/backends/cli-version.js +112 -0
- package/dist/backends/codex-app.js +1525 -0
- package/dist/backends/codex-daybreak.js +75 -0
- package/dist/backends/codex-env.js +656 -0
- package/dist/backends/codex-network.js +304 -0
- package/dist/backends/codex-pin.js +320 -0
- package/dist/backends/codex-shell-policy.js +182 -0
- package/dist/backends/codex-stage2.js +998 -0
- package/dist/backends/codex-subagents.js +47 -0
- package/dist/backends/codex.js +637 -0
- package/dist/backends/copilot.js +246 -0
- package/dist/backends/env.js +147 -0
- package/dist/backends/gemini.js +607 -0
- package/dist/backends/grok.js +337 -0
- package/dist/backends/index.js +8 -0
- package/dist/backends/native-temp.js +187 -0
- package/dist/backends/never-admission.js +90 -0
- package/dist/backends/run.js +67 -0
- package/dist/backends/stream.js +230 -0
- package/dist/backends/tool-discovery.js +15 -0
- package/dist/backends/types.js +264 -0
- package/dist/build-info.json +5 -0
- package/dist/cli.js +344 -0
- package/dist/confine/bridge.js +113 -0
- package/dist/confine/broker-core.js +76 -0
- package/dist/confine/broker-http.js +650 -0
- package/dist/confine/broker-names.js +9 -0
- package/dist/confine/broker.js +258 -0
- package/dist/confine/canary.js +380 -0
- package/dist/confine/diagnostics.js +122 -0
- package/dist/confine/gemini-tools-main.js +8 -0
- package/dist/confine/gemini-tools.js +181 -0
- package/dist/confine/hardlinks.js +58 -0
- package/dist/confine/harness-config.js +16 -0
- package/dist/confine/index.js +117 -0
- package/dist/confine/leases.js +217 -0
- package/dist/confine/paths.js +6 -0
- package/dist/confine/peer.js +115 -0
- package/dist/confine/port-policy.js +8 -0
- package/dist/confine/ports.js +365 -0
- package/dist/confine/private-root.js +208 -0
- package/dist/confine/probe-stage2.js +501 -0
- package/dist/confine/probe.js +1109 -0
- package/dist/confine/proxy.js +783 -0
- package/dist/confine/sbcheck.js +208 -0
- package/dist/confine/seatbelt-never.js +41 -0
- package/dist/confine/seatbelt-stage2.js +139 -0
- package/dist/confine/seatbelt.js +1129 -0
- package/dist/confine/sockets.js +36 -0
- package/dist/confine/turn-probe.js +19 -0
- package/dist/confine/turn.js +86 -0
- package/dist/core/adoption.js +124 -0
- package/dist/core/api-keys.js +423 -0
- package/dist/core/approvals.js +740 -0
- package/dist/core/build-identity.js +248 -0
- package/dist/core/caller.js +749 -0
- package/dist/core/calls.js +102 -0
- package/dist/core/claude-settings.js +1045 -0
- package/dist/core/config.js +453 -0
- package/dist/core/context.js +186 -0
- package/dist/core/db.js +753 -0
- package/dist/core/dispatch.js +110 -0
- package/dist/core/env-broker.js +505 -0
- package/dist/core/env-policy.js +182 -0
- package/dist/core/escalation-authority.js +76 -0
- package/dist/core/escalation-contract.js +13 -0
- package/dist/core/escalation-person-path.js +131 -0
- package/dist/core/escalation-policy.js +79 -0
- package/dist/core/escalation-runtime.js +135 -0
- package/dist/core/escalation-state.js +42 -0
- package/dist/core/escalations.js +191 -0
- package/dist/core/events.js +235 -0
- package/dist/core/executables.js +147 -0
- package/dist/core/extensions.js +645 -0
- package/dist/core/families.js +204 -0
- package/dist/core/git.js +657 -0
- package/dist/core/identity.js +113 -0
- package/dist/core/liveness.js +68 -0
- package/dist/core/mediated-network-provider.js +81 -0
- package/dist/core/never-checkpoint.js +76 -0
- package/dist/core/never-coverage.js +97 -0
- package/dist/core/never-network.js +49 -0
- package/dist/core/never-policy.js +302 -0
- package/dist/core/never-proxy-policy.js +109 -0
- package/dist/core/never-schema.js +61 -0
- package/dist/core/never-tools.js +56 -0
- package/dist/core/notices.js +48 -0
- package/dist/core/ops.js +959 -0
- package/dist/core/outcome.js +224 -0
- package/dist/core/params.js +32 -0
- package/dist/core/presence.js +174 -0
- package/dist/core/procs.js +546 -0
- package/dist/core/prompts.js +363 -0
- package/dist/core/protected-config.js +238 -0
- package/dist/core/raw-network.js +192 -0
- package/dist/core/redact.js +152 -0
- package/dist/core/refusal.js +33 -0
- package/dist/core/relay-command.js +310 -0
- package/dist/core/reported.js +3 -0
- package/dist/core/restart-overlay.js +651 -0
- package/dist/core/retention.js +1135 -0
- package/dist/core/secrets.js +329 -0
- package/dist/core/session-token.js +175 -0
- package/dist/core/session.js +744 -0
- package/dist/core/shell.js +2 -0
- package/dist/core/shipped-pin.js +47 -0
- package/dist/core/shown.js +42 -0
- package/dist/core/slots.js +67 -0
- package/dist/core/stage2-executors.js +453 -0
- package/dist/core/stage2-switch.js +5 -0
- package/dist/core/steering.js +149 -0
- package/dist/core/storage.js +358 -0
- package/dist/core/toml.js +175 -0
- package/dist/core/views.js +324 -0
- package/dist/core/wait.js +114 -0
- package/dist/core/wake.js +207 -0
- package/dist/core/watch.js +247 -0
- package/dist/core/worktree.js +213 -0
- package/dist/hosts/claude-desktop.js +274 -0
- package/dist/hosts/claude.js +249 -0
- package/dist/hosts/codex.js +329 -0
- package/dist/hosts/desktop-shared.js +20 -0
- package/dist/hosts/index.js +11 -0
- package/dist/hosts/types.js +4 -0
- package/dist/install/basics.js +18 -0
- package/dist/install/claude-init.js +133 -0
- package/dist/install/common.js +655 -0
- package/dist/install/doctor.js +629 -0
- package/dist/install/qualify-codex.js +205 -0
- package/dist/install.js +524 -0
- package/dist/mcp/elicit.js +209 -0
- package/dist/mcp/gateway.js +218 -0
- package/dist/mcp/host.js +253 -0
- package/dist/mcp/server.js +1124 -0
- package/dist/mcp/stdio.js +37 -0
- package/dist/modes/discussion.js +393 -0
- package/dist/modes/review.js +722 -0
- package/dist/native/relay-sbcheck +0 -0
- package/dist/targets/briefs.js +86 -0
- package/dist/targets/claude.js +94 -0
- package/dist/targets/codex.js +66 -0
- package/dist/targets/copilot.js +93 -0
- package/dist/targets/gemini.js +119 -0
- package/dist/targets/grok.js +126 -0
- package/dist/targets/index.js +192 -0
- package/dist/targets/types.js +18 -0
- package/dist/targets/verified.js +35 -0
- package/dist/worker.js +113 -0
- package/docs/UPGRADING.md +1502 -0
- package/docs/pinned-codex.md +321 -0
- package/experiments/stage2-redteam/lib/oracles.mjs +214 -0
- package/experiments/stage2-redteam/lib/report.mjs +35 -0
- package/npm-shrinkwrap.json +1632 -0
- package/package.json +82 -4
- package/scripts/codex-qualify/codex-pin-store.mjs +353 -0
- package/scripts/codex-qualify/codex-qualifier-process.mjs +265 -0
- package/scripts/codex-qualify/codex-qualifier.example.json +5 -0
- package/scripts/codex-qualify/codex-qualifier.mjs +281 -0
- package/scripts/codex-qualify/codex-shipped-pin.mjs +158 -0
- package/scripts/codex-qualify/codex-stage2-pin.mjs +48 -0
- package/scripts/codex-qualify/codex-stage2.mjs +2381 -0
- package/scripts/codex-qualify/install-codex-qualifier.mjs +98 -0
- package/scripts/codex-qualify/main-module.mjs +14 -0
- package/scripts/codex-qualify/relay-codex-qualifier.plist +37 -0
- package/scripts/codex-qualify/scratch-env.mjs +31 -0
- package/scripts/codex-qualify/session.mjs +96 -0
- package/scripts/codex-qualify/stage2-escalation-cases.mjs +125 -0
- package/test/codex-permissions.test.ts +875 -0
- package/test/fixtures/boundary-probes.mjs +17 -0
- package/test/fixtures/denial-stream-host.mjs +7 -0
- package/test/fixtures/families.json +246 -0
- package/test/fixtures/install-snapshots/claude-desktop-foreign.txt +158 -0
- package/test/fixtures/install-snapshots/claude-desktop-fresh.txt +101 -0
- package/test/fixtures/install-snapshots/claude-desktop-installed.txt +161 -0
- package/test/fixtures/install-snapshots/claude-foreign.txt +133 -0
- package/test/fixtures/install-snapshots/claude-fresh.txt +77 -0
- package/test/fixtures/install-snapshots/claude-installed.txt +133 -0
- package/test/fixtures/install-snapshots/codex-foreign.txt +159 -0
- package/test/fixtures/install-snapshots/codex-fresh.txt +107 -0
- package/test/fixtures/install-snapshots/codex-installed.txt +161 -0
- package/test/fixtures/link-parent.mjs +6 -0
- package/test/fixtures/mediated-command.cjs +72 -0
- package/test/fixtures/native-skill-isolation.json +280 -0
- package/test/fixtures/pinned-codex-app-server.mjs +25 -0
- package/test/fixtures/qualified-ext-adapters.mjs +36 -0
- package/test/fixtures/refusals/README.md +52 -0
- package/test/fixtures/refusals/claude-source-result.json +7 -0
- package/test/fixtures/refusals/openai-app-capacity.json +24 -0
- package/test/fixtures/refusals/openai-app-cyberPolicy.json +24 -0
- package/test/fixtures/refusals/openai-gpt-6-astra-max.json +12 -0
- package/test/fixtures/refusals/openai-gpt-6.1-sol-xhigh.json +12 -0
- package/test/fixtures/refusals/openai-review-capacity.json +24 -0
- package/test/fixtures/relay-0.2.0.sql +57 -0
- package/test/fixtures/relay-0.9.1.gen.mjs +212 -0
- package/test/fixtures/relay-0.9.1.sql +340 -0
- package/test/fixtures/slow-boundary-probes.mjs +37 -0
- package/test/fixtures/stable-surfaces/config.json +1122 -0
- package/test/fixtures/stable-surfaces/escalation.json +128 -0
- package/test/fixtures/stable-surfaces/events.json +37 -0
- package/test/fixtures/stable-surfaces/gemini-native-resume.json +4 -0
- package/test/fixtures/stable-surfaces/inbox.jsonl +2 -0
- package/test/fixtures/stable-surfaces/notice.txt +1 -0
- package/test/fixtures/stable-surfaces/refusal-item.json +28 -0
- package/test/fixtures/stable-surfaces/refusal-review.json +23 -0
- package/test/fixtures/stable-surfaces/registry.json +49 -0
- package/test/fixtures/stable-surfaces/tools-desktop.json +575 -0
- package/test/fixtures/stable-surfaces/tools.json +716 -0
- package/test/fixtures/stable-surfaces/usage.txt +46 -0
- package/test/fixtures/stage2-acp-native.mjs +138 -0
- package/test/fixtures/stage2-app-server.mjs +23 -0
- package/test/fixtures/stage2-catalog.json +91 -0
- package/test/fixtures/stage2-hostile-web.mjs +35 -0
- package/test/fixtures/stage2-native-network.mjs +62 -0
- package/test/fixtures/stage2-worker.ts +87 -0
- package/test/fixtures/status-views/expected.json +7825 -0
- package/test/fixtures/status-views/registries.json +1 -0
- package/test/fixtures/steering.json +209 -0
- package/test/helpers.ts +740 -0
- package/test/host-env.ts +7 -0
- package/test/keychain-decoy.ts +197 -0
- package/test/live-scope.ts +44 -0
- package/test/mediated-network.test.ts +192 -0
- package/test/mediated-proxy.test.ts +264 -0
- package/test/native-temp-alias.ts +10 -0
- package/test/never-policy.test.ts +629 -0
- package/test/never-tools.test.ts +136 -0
- package/test/process-home.ts +18 -0
- package/test/proxy.test.ts +531 -0
- package/test/restart-overlay-live.test.ts +85 -0
- package/test/restart-overlay-profile.test.ts +66 -0
- package/test/restart-overlay.test.ts +416 -0
- package/test/stable-surfaces.test.ts +249 -0
- package/test/stage2-escalation-live.test.ts +544 -0
- package/test/stage2-escalation-qualification.test.ts +170 -0
- package/test/stage2-escalation.test.ts +747 -0
- package/test/stage2-executor.test.ts +849 -0
- package/test/stage2-grant.test.ts +603 -0
- package/test/stage2-native-live.test.ts +647 -0
- package/test/stage2-network-decisions.test.ts +70 -0
- package/test/stage2-probe.test.ts +845 -0
- package/test/stage2-standing-live.test.ts +203 -0
- package/test/stubs/broker-host.mjs +59 -0
- package/test/stubs/broker-peer.mjs +20 -0
- package/test/stubs/confined-harness.mjs +91 -0
- package/test/stubs/ext-broken-server.mjs +2 -0
- package/test/stubs/ext-odd-server.mjs +21 -0
- package/test/stubs/ext-server.mjs +31 -0
- package/test/stubs/fake-host-cli.mjs +218 -0
- package/test/stubs/procargs.mjs +30 -0
- package/test/stubs/stub-acp +4 -0
- package/test/stubs/stub-agent.mjs +322 -0
- package/test/stubs/stub-claude +4 -0
- package/test/stubs/stub-codex +4 -0
- package/test/stubs/targets/acp.mjs +307 -0
- package/test/stubs/targets/claude.mjs +149 -0
- package/test/stubs/targets/codex.mjs +479 -0
- package/test/stubs/targets/gemini.mjs +604 -0
- package/test/temp-root.ts +11 -0
- package/test/wp4-adapters.test.ts +353 -0
- package/test/wp4-interlock.test.ts +136 -0
|
@@ -0,0 +1,1502 @@
|
|
|
1
|
+
# Upgrading relay
|
|
2
|
+
|
|
3
|
+
How to move an installed relay to a newer release, and back. The release notes below say, for
|
|
4
|
+
each release, whether its registry or config changed and anything to do on upgrade.
|
|
5
|
+
|
|
6
|
+
## How to upgrade
|
|
7
|
+
|
|
8
|
+
1. **Let relay's work finish**, or cancel what you do not need (`relay tree` shows a run;
|
|
9
|
+
`relay cancel <id>`). Upgrading replaces relay's files under any relay process still running.
|
|
10
|
+
Such a process goes on with the code it has loaded, but loads parts of relay only when it first
|
|
11
|
+
needs them, and starts workers from the files on disk, so it can mix the old release with the
|
|
12
|
+
new. Under a release's shipped Codex pin it refuses further Codex turns ("relay was changed on
|
|
13
|
+
disk after this process started") until it is restarted.
|
|
14
|
+
2. **Install the new release.**
|
|
15
|
+
- From npm: `npm install -g @jbkjr/relay@latest`.
|
|
16
|
+
- From a checkout: pull, then `npm ci` and `npm run build`. A pull alone leaves the old build
|
|
17
|
+
in `dist/` running; `relay doctor` reports the commit the build was made from and warns when
|
|
18
|
+
the checkout has moved on.
|
|
19
|
+
3. **Run `relay install <host> --write` again for each host you use** (`claude`, `codex`,
|
|
20
|
+
`claude-desktop`). It puts relay's plugin in again where the host's copy differs from this
|
|
21
|
+
release's, updates relay's registration where its form changed, and migrates relay's registry
|
|
22
|
+
if the release changed it, backing it up first (below). `relay install codex --write` also puts
|
|
23
|
+
the new release's shipped Codex pin in place, unless a pin you qualified on this Mac with
|
|
24
|
+
`relay qualify-codex` is current; until it has, relay refuses the old release's shipped pin,
|
|
25
|
+
which names the old build ([Pinned Codex](pinned-codex.md)).
|
|
26
|
+
4. **Restart the hosts' sessions.** Each runs its own relay server. The Claude desktop app runs one
|
|
27
|
+
for all its chats and for all its Cowork and Code tab sessions, and restarts it only when you
|
|
28
|
+
quit and reopen the app.
|
|
29
|
+
5. **Check:** `relay --version` and `relay doctor`.
|
|
30
|
+
|
|
31
|
+
### Your config across versions
|
|
32
|
+
|
|
33
|
+
Every version validates `~/.config/relay/config.json` strictly and refuses a key or value it does
|
|
34
|
+
not know, so a setting only a newer version knows stops an older one from starting. Add a new
|
|
35
|
+
release's settings only after upgrading. If more than one relay reads the same config file (one
|
|
36
|
+
shared between machines, say), add them only once every one of those relays runs a version that
|
|
37
|
+
knows them. Release notes name each new key, and which earlier versions reject it.
|
|
38
|
+
|
|
39
|
+
## The registry
|
|
40
|
+
|
|
41
|
+
Relay keeps its runs, jobs, approval requests and events in one SQLite file, `relay.db`, in its
|
|
42
|
+
state directory (`RELAY_HOME`, by default `~/.local/state/relay`).
|
|
43
|
+
|
|
44
|
+
- The file carries a schema version (`PRAGMA user_version`). When a relay opens a registry with a
|
|
45
|
+
lower version, it first writes a consistent copy next to it,
|
|
46
|
+
`relay.db.backup-v<old version>-<time>-<pid>`, then migrates the file and records the new
|
|
47
|
+
version. If the copy cannot be written, relay stops and leaves the file as it is.
|
|
48
|
+
- Any relay process that opens the registry does this on its first open: the MCP server a host
|
|
49
|
+
session starts, workers, and commands such as `tree`, `chat`, `cancel`, `clean`, `approvals`,
|
|
50
|
+
`approve` and `deny`. `relay install <host> --write` does it before it changes anything in the
|
|
51
|
+
host, prints the backup's path and records it in `~/.config/relay/install.json`. `relay doctor`,
|
|
52
|
+
`--version`, `help`, and `install` without `--write` do not open the registry (without `--write`,
|
|
53
|
+
install only says that it would migrate it).
|
|
54
|
+
- A registry with a higher version than the running relay knows is refused, so an older relay
|
|
55
|
+
never works on a schema it does not know.
|
|
56
|
+
- Retention (`keep_records_days`) never deletes a migration backup. A backup can hold prompts and
|
|
57
|
+
results; delete it yourself once you will not go back to the version that wrote it.
|
|
58
|
+
- To look at the registry with `sqlite3`, open it as `sqlite3 "file:$HOME/.local/state/relay/relay.db?mode=rw"`,
|
|
59
|
+
not by a bare path and not with `-readonly`. The file is in WAL mode, and macOS's own
|
|
60
|
+
`/usr/bin/sqlite3` has failed a read-only open ("unable to open database file") on a registry no
|
|
61
|
+
process had open. `mode=rw` opens only a file that exists, where a plain `sqlite3 <path>` would
|
|
62
|
+
create an empty one. Do not use `?immutable=1`: it skips the write-ahead log and can show stale
|
|
63
|
+
rows while relay is running. Write `$HOME`, not `~`, inside the quotes.
|
|
64
|
+
|
|
65
|
+
## Rollback
|
|
66
|
+
|
|
67
|
+
Going back to an earlier release means restoring the registry backup the upgrade made, not running
|
|
68
|
+
the earlier relay on the migrated file (it refuses a schema it does not know). When no release
|
|
69
|
+
after the one you go back to changed the registry (the release notes say), skip step 3.
|
|
70
|
+
|
|
71
|
+
1. **The config first.** Remove the settings the earlier release does not know (the release notes
|
|
72
|
+
name them), or restore the file you had before upgrading.
|
|
73
|
+
2. **Stop relay.** Let work finish or cancel it, quit the sessions that use relay and the Claude
|
|
74
|
+
desktop app, and make sure no relay process is left: `pgrep -fl 'dist/cli.js (mcp|worker)'`
|
|
75
|
+
prints nothing. Keep the branches and worktrees of finished write jobs whose work you want.
|
|
76
|
+
3. **Restore the registry backup** the upgrade made: the path `relay install` printed and recorded
|
|
77
|
+
in `~/.config/relay/install.json`, never a guess at the newest-looking file. Check it first:
|
|
78
|
+
`sqlite3 "file:<backup>?mode=rw" 'PRAGMA user_version'` must print the earlier schema version.
|
|
79
|
+
Then fold the migrated file's write-ahead log into it, and keep it, with whatever is left of
|
|
80
|
+
its log, beside the restored one:
|
|
81
|
+
|
|
82
|
+
```sh
|
|
83
|
+
cd ~/.local/state/relay
|
|
84
|
+
sqlite3 "file:relay.db?mode=rw" 'PRAGMA wal_checkpoint(TRUNCATE)' # prints 0|0|0; a first 1 means something still has it open: back to step 2
|
|
85
|
+
ts=$(date +%Y%m%d%H%M%S)
|
|
86
|
+
mv relay.db relay.db.migrated-$ts
|
|
87
|
+
[ -e relay.db-wal ] && mv relay.db-wal relay.db.migrated-$ts-wal
|
|
88
|
+
[ -e relay.db-shm ] && mv relay.db-shm relay.db.migrated-$ts-shm
|
|
89
|
+
cp relay.db.backup-v<N>-<time>-<pid> relay.db
|
|
90
|
+
sqlite3 "file:relay.db?mode=rw" 'PRAGMA user_version' # the earlier schema version
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
4. **Install the earlier release**: `npm install -g @jbkjr/relay@<version>`, or in a checkout
|
|
94
|
+
`git switch --detach v<version>` and then `npm ci && npm run build`. Run
|
|
95
|
+
`relay install <host> --write` for each host, and restart the hosts' sessions. Where the
|
|
96
|
+
earlier installer takes the newer release's registration for one you changed yourself, it says
|
|
97
|
+
so and stops; `--force` replaces it, after saving it. `relay install codex --write` puts the
|
|
98
|
+
earlier release's shipped Codex pin in place, as on an upgrade, unless a pin you qualified on
|
|
99
|
+
this Mac is current.
|
|
100
|
+
|
|
101
|
+
What restoring loses: the registry's record of whatever ran under the newer release. Job branches
|
|
102
|
+
(`relay/<job>`) and worktrees stay in git and on disk. Uninstall does not restore the registry.
|
|
103
|
+
|
|
104
|
+
# Release notes
|
|
105
|
+
|
|
106
|
+
Newest first. Relay 1.1.4 and earlier came before the first public release; their notes are kept
|
|
107
|
+
because later notes and the reference docs point into them.
|
|
108
|
+
|
|
109
|
+
## Relay 1.2.1
|
|
110
|
+
|
|
111
|
+
The first public release (1.2.0 was tagged in the pre-publication repository and never published,
|
|
112
|
+
so its notes are folded in here): relay is published to npm as `@jbkjr/relay`, and a release can ship a
|
|
113
|
+
Codex pin the maintainer qualified, so Codex works without an hour-and-a-half qualification on your
|
|
114
|
+
Mac. No config or registry migration is needed (the registry schema and the config file are as in
|
|
115
|
+
1.1.4). Codex pins already in your store keep working, whichever relay commit or build they record.
|
|
116
|
+
What changes:
|
|
117
|
+
|
|
118
|
+
- **Install from npm** (`npm install -g @jbkjr/relay`), then `relay install codex --write`, which
|
|
119
|
+
now also makes relay's Codex home for the one-time `codex login` there (below). From a checkout
|
|
120
|
+
nothing changes, except that `relay qualify-codex` replaces running the qualifier script by hand.
|
|
121
|
+
- **`relay doctor`** reports the build and Codex's setup as relay's jobs see them (below).
|
|
122
|
+
- **Fixes** to events, turn authority and the sandbox-denial stream (below), and Claude Code 2.1.326
|
|
123
|
+
verified.
|
|
124
|
+
- **Node 24.15 or newer** is required (below).
|
|
125
|
+
- **The never floor's built-in ports are macOS's own services only**, and a `never.ports` entry of
|
|
126
|
+
yours for this Mac works with Codex's strict network (below).
|
|
127
|
+
|
|
128
|
+
### `relay doctor`: the build on an npm install, and Codex as relay's jobs see it
|
|
129
|
+
|
|
130
|
+
- **build.** On an npm install, which has no checkout, the line names the build by relay's build
|
|
131
|
+
identity, the version and hash a shipped Codex pin names: `an npm install of @jbkjr/relay (no git
|
|
132
|
+
checkout): relay 1.2.1, build 0123456789abcdef; built from <commit> on <date>`. Before, it said
|
|
133
|
+
relay could not read the checkout's HEAD. A checkout is reported as before.
|
|
134
|
+
- **codex launch** and **codex env** come from the checks a Codex turn makes before it starts: a
|
|
135
|
+
short-lived Codex app server reports its effective configuration for a job started in the current
|
|
136
|
+
directory, every layer merged (system, managed, the directory's project layers and relay's Codex
|
|
137
|
+
home), and relay judges it as the turn does, for the configured default job (default model and
|
|
138
|
+
speed, relay's tools, no grants), read and write. Before, these lines judged the `config.toml` in
|
|
139
|
+
relay's Codex home, which relay rewrites on every turn, and saw no other layer. When that file
|
|
140
|
+
holds changes of yours, doctor says that they never apply to a job. Doctor now starts two Codex app
|
|
141
|
+
servers to ask (no thread, no model request), so it takes a few seconds longer. Run inside an
|
|
142
|
+
agent whose sandbox keeps it from relay's Codex home, it says the check could not be made there.
|
|
143
|
+
- **codex login** asks `codex login status` of relay's Codex home, where relay's Codex jobs sign in,
|
|
144
|
+
not of `~/.codex`. A missing or signed-out home of relay's is a requirement not met, with the
|
|
145
|
+
command that signs it in.
|
|
146
|
+
- **your codex** is new: your own `~/.codex` is for your own Codex sessions, and relay's jobs read
|
|
147
|
+
none of it (its `config.toml`, rules, skills, `AGENTS.md` and login).
|
|
148
|
+
- **relay on PATH**: npm's global `relay` command for this install counts as this relay, so a
|
|
149
|
+
correct npm install no longer warns there.
|
|
150
|
+
- Registration lines say "from this npm install" on an npm install.
|
|
151
|
+
|
|
152
|
+
### `relay install codex --write` makes relay's Codex home
|
|
153
|
+
|
|
154
|
+
Codex refuses a `CODEX_HOME` that does not exist, so on a fresh install, where nothing had made
|
|
155
|
+
relay's Codex home yet, the one-time `CODEX_HOME=… codex login` failed. `relay install codex --write` now
|
|
156
|
+
makes it (a private directory with the `config.toml` relay writes there on every turn, so the login
|
|
157
|
+
goes to the file store relay's turns read) and prints the sign-in command. A dry run says it would.
|
|
158
|
+
|
|
159
|
+
### Fixes
|
|
160
|
+
|
|
161
|
+
- **Events.** A discussion reply followed at once by the borrowed session's own queued turn is
|
|
162
|
+
announced; before, only the session's completion was.
|
|
163
|
+
- **Turn authority.** A turn's authority ends when its agent exits, not after relay's bookkeeping
|
|
164
|
+
(process-group checks, writing the final message), so nothing left of the agent can start, steer
|
|
165
|
+
or file requests for the turn in between.
|
|
166
|
+
- **Sandbox-denial stream.** Closing it signals its process group only while relay's child still
|
|
167
|
+
leads it, so a reused group id (another agent's, say) is never signalled.
|
|
168
|
+
- **Claude Code 2.1.326** is verified for the temp link and for `cc-plugin-privacy`, which relay
|
|
169
|
+
now checks by a digest per verified version.
|
|
170
|
+
- **Dependencies:** `@hono/node-server` 2.1.8 and `hono` 4.13.18, both through the lock.
|
|
171
|
+
|
|
172
|
+
### Node 24.15 or newer
|
|
173
|
+
|
|
174
|
+
Relay needs Node 24.15 or newer (before: 22.18). `node:sqlite`, which relay's registry uses, printed
|
|
175
|
+
an `ExperimentalWarning` on every command under Node 22 and earlier Node 24 releases; 24.15 is the
|
|
176
|
+
first without it. Install a Node 24 LTS (or a later release) before upgrading relay: the launcher
|
|
177
|
+
`bin/relay` passes over an older Node, and `relay doctor` fails the `node` line on one.
|
|
178
|
+
|
|
179
|
+
### The never floor: built-in ports and yours
|
|
180
|
+
|
|
181
|
+
- **Built-in ports.** `service.sshd` (22) and `service.screen-sharing` (5900) are the only built-in
|
|
182
|
+
never ports, and stage 2's static deny is macOS's own services (22, 5900, 3283, 3031, 445, 548,
|
|
183
|
+
631). Two built-ins that named services of one particular Mac, a mail bridge's ports (1025, 1143)
|
|
184
|
+
and an MCP gateway's (8787, 11143), are gone. If you run such a service, add its ports under
|
|
185
|
+
`never.ports` with `"destinations": "this-machine"`. A run started before the upgrade keeps
|
|
186
|
+
them in its floor until it ends. An `override_builtin` entry naming one of the two is still
|
|
187
|
+
accepted and removes nothing; relay warns about it.
|
|
188
|
+
- **Your this-Mac ports and native Codex.** A `never.ports` entry of yours with
|
|
189
|
+
`"destinations": "this-machine"` no longer refuses a Codex turn with strict shell network (a
|
|
190
|
+
network grant or `child_network`, stage 2 off): strict reaches none of this Mac's addresses, so it
|
|
191
|
+
enforces the entry as it does the built-ins. Local mode (`grant.local_network`) and
|
|
192
|
+
`allow_dangerous` write turns, which reach this Mac's addresses, still refuse any `never.ports`
|
|
193
|
+
entry of yours, now a UDP-only one too. `relay doctor`'s "never Codex" line says which.
|
|
194
|
+
- The raw-network consent text now names your `never.ports` among the denied ports, so a job holding
|
|
195
|
+
a raw-network consent is asked again.
|
|
196
|
+
|
|
197
|
+
### The package is @jbkjr/relay, with a dependency lock in its build identity
|
|
198
|
+
|
|
199
|
+
- **Name.** The package is named `@jbkjr/relay`, its npm name. The command is still `relay`.
|
|
200
|
+
`relay install` still recognises a `~/.local/bin/relay` link into a checkout whose package.json
|
|
201
|
+
says `relay`, so an older checkout's link is replaced, not reported as someone else's.
|
|
202
|
+
- **Dependency lock.** `package-lock.json` is now `npm-shrinkwrap.json`, which npm also honours when
|
|
203
|
+
it installs relay from the registry: relay's dependencies are installed at the versions it names,
|
|
204
|
+
checked against their integrities. Run `npm ci` as before.
|
|
205
|
+
- **Build identity `relay-build-v2`.** The identity a Codex pin records now covers that lock, so a
|
|
206
|
+
shipped pin also fixes relay's dependencies ([pinned-codex.md](pinned-codex.md#relays-build-identity)).
|
|
207
|
+
Existing local pins keep working, whichever identity or commit they record. A failure recorded
|
|
208
|
+
under `relay-build-v1` no longer matches, so those inputs are qualified again, and a shipped pin
|
|
209
|
+
naming `relay-build-v1` is refused.
|
|
210
|
+
- **Exact dependencies.** `package.json` names relay's direct dependencies at exactly their locked
|
|
211
|
+
versions. The qualifier refuses to run, and relay refuses to run Codex under a shipped pin, when
|
|
212
|
+
any dependency relay would load, transitive ones included, is not the version the lock names.
|
|
213
|
+
- **The sandbox_check helper** is linked under a fixed name, so two builds of the same sources give
|
|
214
|
+
the same `dist/native/relay-sbcheck`.
|
|
215
|
+
|
|
216
|
+
### Claude consent: ordinary skill and command frontmatter no longer withholds
|
|
217
|
+
|
|
218
|
+
Relay's frontmatter check, used for skills, legacy commands and
|
|
219
|
+
agents (plugin and personal), withheld the approval dialog and `confirm` for ordinary YAML. Among
|
|
220
|
+
these were permissions such as `allowed-tools: Bash(git add:*)` (it took the `:*` for an alias),
|
|
221
|
+
flow lists such as `tools: ["Read", "Grep"]` and `argument-hint: [project-name]`, and values on
|
|
222
|
+
the line after their key. On a machine with the claude-plugins-official marketplace this was about
|
|
223
|
+
25 of the reasons.
|
|
224
|
+
|
|
225
|
+
- The check now follows how Claude Code reads a definition's frontmatter: up to the first `---`
|
|
226
|
+
anywhere, Bun's YAML parser, then one retry with column-0 `key: value` values quoted, and
|
|
227
|
+
hooks from the top-level `hooks` key. A top-level key starts at column 0 in each of those, so
|
|
228
|
+
relay withholds when `hooks` followed by `:` appears anywhere in the block, or when a line at
|
|
229
|
+
column 0 is anything but a comment, a `- ` entry, or a plain `key:` entry. It also withholds when
|
|
230
|
+
such a line continues a quoted value or flow list opened earlier.
|
|
231
|
+
- Still withheld, as margin: flow mappings, anchors, aliases, tags, directives, quoted and
|
|
232
|
+
explicit keys, duplicate top-level keys, nested flow lists, and comments or pairs inside a flow
|
|
233
|
+
list. Lookalikes such as `hooks:` inside a quoted or folded description still withhold too.
|
|
234
|
+
- A hooks file that loads a hooks module (`"modules"` in `hooks/hooks.json`, as the
|
|
235
|
+
code-modernization and theme-examples plugins do) still withholds. The reason now says so
|
|
236
|
+
instead of "could not read".
|
|
237
|
+
|
|
238
|
+
### Claude consent: marketplaces that declare only skills keep the approval dialog
|
|
239
|
+
|
|
240
|
+
A plugin marketplace entry that declares `skills` no longer
|
|
241
|
+
withholds the approval dialog and `confirm` by itself. Before, any marketplace manifest entry
|
|
242
|
+
that declared hooks, skills, agents or commands withheld both, so the `anthropic-agent-skills`
|
|
243
|
+
marketplace (anthropics/skills) turned dialogs off on any machine that had it added.
|
|
244
|
+
|
|
245
|
+
- For an entry that declares only skills, relay finds every copy of that plugin on disk: under the
|
|
246
|
+
marketplace for a relative `source` (also under `metadata.pluginRoot`), each cached version
|
|
247
|
+
(`plugins/cache/<marketplace>/<plugin>/<version>`), and each recorded install path. It reads
|
|
248
|
+
the leading frontmatter of every `SKILL.md` under each declared path, with the same
|
|
249
|
+
conservative check as other skills: any `hooks` key, or frontmatter it cannot read or rule out,
|
|
250
|
+
withholds both. So does a declared path or `source` outside the plugin or marketplace (`..`), a
|
|
251
|
+
link that leads out of the plugin directory (even between plugins of one marketplace, which
|
|
252
|
+
Claude Code itself allows), a zipped cached copy, a plugin name relay cannot place in the cache,
|
|
253
|
+
and an entry it cannot read.
|
|
254
|
+
- A remote plugin (a `github`, `url` or `git-subdir` source) that was never installed has no copy
|
|
255
|
+
on disk and adds nothing. Once installed, its cached copy is checked.
|
|
256
|
+
- Every cached version (`plugins/cache/<marketplace>/<plugin>/<version>`) now counts as a plugin
|
|
257
|
+
root even when it has no `plugin.json`. Its default `skills/`, `agents/`, `commands/` and
|
|
258
|
+
`hooks/hooks.json` are read like an installed plugin's. Before, relay read them only for a copy
|
|
259
|
+
with a manifest or a recorded install path. A running session can still have an older version
|
|
260
|
+
loaded.
|
|
261
|
+
- Entries that declare `hooks`, `agents` or `commands` withhold as before.
|
|
262
|
+
- New: `CLAUDE_CODE_PLUGIN_CACHE_DIR` and `CLAUDE_CODE_PLUGIN_SEED_DIR` in relay's environment
|
|
263
|
+
withhold both. They move plugins outside the directories relay scans.
|
|
264
|
+
|
|
265
|
+
Other checks can still withhold on your machine. `relay doctor` (the `claude consent` line) gives
|
|
266
|
+
the first reason that applies. Restart relay's MCP servers to apply the change.
|
|
267
|
+
|
|
268
|
+
### Codex 0.170.0: seven new default-on features pinned off; a new tool and an isolate helper admitted
|
|
269
|
+
|
|
270
|
+
Codex 0.170.0 turns on by default seven features that 0.167.2 lists off or not at all:
|
|
271
|
+
`code_mode_host_grpc`, `code_mode_host_output_truncation`, `guardian_include_additional_context`,
|
|
272
|
+
`incremental_tools_legacy`, `retain_client_tool_outputs`, `unified_image_budget` and
|
|
273
|
+
`untrusted_as_tool_output`. The stage-2 readback refused every turn on them as unqualified
|
|
274
|
+
features. None adds a tool or host action, and relay now pins each off on 0.170.0 and later,
|
|
275
|
+
keeping 0.167.2's behaviour. It does not require them of older versions. 0.170.0's model catalog
|
|
276
|
+
also offers `send_message_to_user_async`, which only posts a message to the thread, so relay now
|
|
277
|
+
admits it. Code mode's JavaScript gains a `content` helper, a sibling of `text`/`image`/`audio`,
|
|
278
|
+
which is admitted too. The reasons, file by file, are in the
|
|
279
|
+
[qualification](qualification/codex-0.170.0.md). No config or registry migration is needed. A
|
|
280
|
+
Codex pin you qualified on your Mac moves to 0.170.0 only when the qualifier qualifies it with this
|
|
281
|
+
release.
|
|
282
|
+
|
|
283
|
+
### Codex 0.167.2: `incremental_tools_legacy_gcp` pinned off
|
|
284
|
+
|
|
285
|
+
Codex 0.167.2 adds the feature `incremental_tools_legacy_gcp`, stable and on by default, and the
|
|
286
|
+
stage-2 readback refused every turn on it as an unqualified feature. Relay now pins it
|
|
287
|
+
off on 0.167.2 and later, as it does `deferred_tool_world_state`, and does not require it of
|
|
288
|
+
0.167.1 or earlier, which do not list it (the maintainer, 2026-11-16). Codex reads it only when the model
|
|
289
|
+
provider is `gcp` (`core/src/session/step_context.rs`), so relay's OpenAI-provider turns are
|
|
290
|
+
unchanged. No config or registry migration is needed. Relay's Codex pin stays 0.167.0; 0.167.2's
|
|
291
|
+
route was checked by relay's release checks ([qualification](qualification/codex-0.167.2.md)).
|
|
292
|
+
|
|
293
|
+
### `relay qualify-codex`, and a qualifier LaunchAgent for any user
|
|
294
|
+
|
|
295
|
+
**`relay qualify-codex [--version X.Y.Z] [--force]`** runs the Codex qualifier once, from a git
|
|
296
|
+
checkout or an npm install, into `targets.codex.pin_store`. It has the same checks as the optional
|
|
297
|
+
qualifier LaunchAgent, which calls the same code. Without a pin, `relay doctor` and every refused
|
|
298
|
+
Codex job now name it. The command refuses inside a launched agent and outside a complete relay
|
|
299
|
+
build, and the pin it writes names relay's build identity
|
|
300
|
+
([pinned-codex.md](pinned-codex.md#relays-build-identity)). It ends by asking relay which Codex it
|
|
301
|
+
would run, and exits 0 only for a qualified pin. Details: [pinned-codex.md](pinned-codex.md).
|
|
302
|
+
|
|
303
|
+
The LaunchAgent's installer (`scripts/codex-qualify/install-codex-qualifier.mjs`) works for any
|
|
304
|
+
user. Its label is `local.<login name>.relay-codex-qualifier` unless `--label` sets another, and
|
|
305
|
+
the plist is written as `~/Library/LaunchAgents/<label>.plist` from the template
|
|
306
|
+
`scripts/codex-qualify/relay-codex-qualifier.plist`.
|
|
307
|
+
|
|
308
|
+
### A release ships a Codex pin
|
|
309
|
+
|
|
310
|
+
A release packed for npm
|
|
311
|
+
can carry `codex-pin.json`: the maintainer's qualification of one Codex release (version and npm
|
|
312
|
+
integrity) with exactly that relay build. `relay install codex --write` downloads that Codex,
|
|
313
|
+
verifies it against the pin and makes it current under `shipped/` in the pin store, so Codex works
|
|
314
|
+
without a local qualification. Relay runs a shipped tree only while the running build is the one
|
|
315
|
+
the pin names. A pin you qualified yourself stays in force over a shipped one; `relay qualify-codex
|
|
316
|
+
--shipped` switches to the shipped one. `relay doctor` reports which is in force. **Nothing changes
|
|
317
|
+
for a git checkout**, which ships no pin: `relay qualify-codex` as before. Existing local pins are
|
|
318
|
+
unchanged. [pinned-codex.md](pinned-codex.md#a-releases-shipped-pin) has the format, the precedence
|
|
319
|
+
rule and the maintainer's steps.
|
|
320
|
+
|
|
321
|
+
### Codex pins name relay's build, and `relay qualify-codex` runs from an npm install
|
|
322
|
+
|
|
323
|
+
A new pin records
|
|
324
|
+
`relayBuild`, relay's version and a SHA-256 of its installed build (`dist/`, the qualifier and the
|
|
325
|
+
files its stage-2 run loads), instead of `relayCommit`. `relay qualify-codex` no longer needs a git
|
|
326
|
+
checkout or refuses one with local changes; it refuses an incomplete build instead, before anything
|
|
327
|
+
runs, and runs stage 2 from a verified copy of the build in its scratch directory.
|
|
328
|
+
`package.json` now has a `files` list that ships that build, and `npm pack` refuses to run without
|
|
329
|
+
`dist/` (`scripts/check-pack.mjs`). **Pins already in the store keep working**, as before: a local
|
|
330
|
+
pin is not bound to the relay that runs it. Failed-qualification records keyed by a relay commit
|
|
331
|
+
no longer match, so a release that failed before is qualified again on its next run.
|
|
332
|
+
[pinned-codex.md](pinned-codex.md#relays-build-identity) has the scheme.
|
|
333
|
+
|
|
334
|
+
## Relay 1.1.4
|
|
335
|
+
|
|
336
|
+
No config or registry migration is needed. Codex pins already qualified under `stage2-v3` stay
|
|
337
|
+
valid; the qualifier stores new ones under `stage2-v4` (item 33, below). What changes:
|
|
338
|
+
|
|
339
|
+
- **Claude jobs get the never floor whether or not stage 2 is on.** In 1.1.3 a Claude job got it
|
|
340
|
+
only with stage 2 on. Now its settings always carry it: sandbox `denyRead`/`denyWrite` and
|
|
341
|
+
Read/Edit deny rules for `~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.netrc`, the CLIs' login files
|
|
342
|
+
(`~/.config/gh/hosts.yml`, `~/.config/gcloud`, Codex's, Claude's, Gemini's, Copilot's, Grok's),
|
|
343
|
+
relay's key directory, the keychain files and your `never.paths`, and `allowUnsandboxedCommands:
|
|
344
|
+
false`. These bind Claude's sandboxed commands and file tools, not the Claude Code process
|
|
345
|
+
(relay starts it unwrapped), which signs in as before. What a Claude job can no longer do:
|
|
346
|
+
- use `gh` with a token in `hosts.yml` or the keychain, git over SSH or with git's osxkeychain
|
|
347
|
+
credentials, GPG signing, `~/.netrc`, or the AWS or gcloud CLIs from its shell. Claude Code's
|
|
348
|
+
sandbox lets commands reach the security daemons (keychain IPC), but reading an item in a
|
|
349
|
+
file-based keychain, such as the login keychain, also needs its keychain file, which the floor
|
|
350
|
+
denies (measured 2026-11-04; checked each release by `claude-floor`). So there is no need to
|
|
351
|
+
move gh's token out of the keychain (`gh auth login --insecure-storage`) for the floor. What the
|
|
352
|
+
daemons serve without a keychain file, such as data-protection keychain items, is not covered,
|
|
353
|
+
nor is a copy of a keychain file kept outside the denied directories;
|
|
354
|
+
- run a command outside its sandbox: Claude's own unsandboxed retry is off, and relay refuses
|
|
355
|
+
every command approval for a Claude job, one that would stay in its sandbox as well
|
|
356
|
+
(`never: Claude command approvals are unavailable under the never floor …`);
|
|
357
|
+
- run at all under `child_settings: "inherit"`, `child_hooks: true` or `child_mcp: "inherit"`
|
|
358
|
+
(global settings: they refuse every Claude job), or on a machine with organisation-managed
|
|
359
|
+
Claude Code settings on disk, even with `claude_managed_settings: "accept"`;
|
|
360
|
+
- run a write job under `allow_dangerous`;
|
|
361
|
+
- use WebSearch or WebFetch while any `never.hosts` entry is set.
|
|
362
|
+
|
|
363
|
+
`relay doctor`'s "never enforced" block now shows Claude as enforced in both stage-2 states, and
|
|
364
|
+
doctor warns (`claude launch`) when the config or the machine would refuse Claude jobs. Its
|
|
365
|
+
per-agent text comes from the same predicate as the launches (`core/never-coverage.ts`); the
|
|
366
|
+
1.1.3 `neverPathEnforcement` text is gone. The escape hatch is `never.override_builtin` (e.g.
|
|
367
|
+
`{ "id": "credentials.files", "acknowledge": "REMOVE BUILT-IN NEVER credentials.files",
|
|
368
|
+
"reason": "…" }`): it removes that built-in group for new runs of every agent, Codex too, not for
|
|
369
|
+
Claude alone; it lifts denies, not the refusals above, and cannot remove `relay.config`,
|
|
370
|
+
`relay.install` or `relay.authority`. Runs started earlier keep their recorded floor, and their
|
|
371
|
+
Claude jobs take it from their next turn under the new relay.
|
|
372
|
+
- **Doctor's "never enforced" block lists keychain IPC separately from the path entries.** The
|
|
373
|
+
floor's keychain-file denies do not cover the security daemons. Only relay's own Seatbelt denies
|
|
374
|
+
those; Claude Code's sandbox leaves them open on every turn, and Codex's native sandbox opens
|
|
375
|
+
them on a turn with shell network while stage 2 is off (`core/never-coverage.ts`
|
|
376
|
+
`neverKeychainIpc`). The file denies still keep items in file-based keychains unreadable, since
|
|
377
|
+
reading one needs its keychain file as well as the daemons (measured 2026-11-04; checked each
|
|
378
|
+
release by a floored decoy keychain and its control without the file deny). What the daemons
|
|
379
|
+
serve without a keychain file, such as data-protection keychain items, is not covered, nor is a
|
|
380
|
+
copy of a keychain file kept outside the denied directories. 1.1.3's doctor line and docs said the floor's "keychain and port rules"
|
|
381
|
+
followed the path entries, which overstated it for Codex network-on turns and for Claude under
|
|
382
|
+
stage 2. The floor's port rules, likewise, reach only relay's own Seatbelt; elsewhere relay's
|
|
383
|
+
proxy and native Codex admission screen ports.
|
|
384
|
+
- **Claude agents are no longer told to retry a command with the sandbox disabled.** Their prompt
|
|
385
|
+
says a blocked command cannot be approved out of the sandbox: use the file tools (write jobs) or
|
|
386
|
+
WebSearch/WebFetch, which ask, report what was blocked, or ask for a network grant on a later turn.
|
|
387
|
+
- **Required release checks for this change** (all passed 2026-11-04 at `d690592`, with the full
|
|
388
|
+
gate chain and the red team):
|
|
389
|
+
- release check `claude-floor` (`RELEASE_CHECK_CASES` in
|
|
390
|
+
`scripts/codex-qualify/stage2-escalation-cases.mjs`; run with the release gates and the red
|
|
391
|
+
team, never by the Codex pin qualifier): part `nativeStage2Off`, item 29's installed-Claude case
|
|
392
|
+
with stage 2 off, and part `keychainDecoy`, the decoy keychain from two Claude turns with stage
|
|
393
|
+
2 off (`RELAY_TEST_KEYCHAIN_LIVE=1`): refused with its directory in `never.paths`, and in the
|
|
394
|
+
control without that entry, retrieved, as doctor's "keychain IPC open" says;
|
|
395
|
+
- qualification item 33, the decoy keychain from native Codex turns with network off and on:
|
|
396
|
+
refused on every floored turn, and each control without the file deny matching doctor's
|
|
397
|
+
keychain IPC (refused with network off, retrieved with network on). It is a Codex pin
|
|
398
|
+
requirement (verdict schema `stage2-v4`): a new Codex version can change its seatbelt policy.
|
|
399
|
+
Pins stored under `stage2-v3` stay valid;
|
|
400
|
+
- one signed-in `claude-live.mjs turn` under the keychain login with stage 2 off (the local
|
|
401
|
+
release checks, whose scratch config leaves `child_auth` at "login"), to show Claude still signs in with the floor's keychain-file denies in place.
|
|
402
|
+
|
|
403
|
+
Rerun 2026-11-08 on the merge with main (`f67f622`), Codex pin 0.167.0 by hash, macOS 27.2: all
|
|
404
|
+
passed in the same shape. What 1.1.4 adds after `f67f622` (below) changes no confinement code.
|
|
405
|
+
- **Codex 0.167.0:** its new `deferred_tool_world_state` feature is pinned off with the other
|
|
406
|
+
stage-2 features (model-visible deferred tool namespaces, no host action). Relay's release checks
|
|
407
|
+
verified Codex 0.167.0's route and Gemini CLI 0.67.0's tool discovery (informational records).
|
|
408
|
+
- **Qualifier fixes** (the pinned-Codex qualifier, not relay itself): its launchd job runs at
|
|
409
|
+
Standard priority, not Background (background QoS stalled `ps` for 5–30 s on a busy Mac and
|
|
410
|
+
failed runs); the process inventory waits up to 30 s and logs one over 5 s; a failed cleanup no
|
|
411
|
+
longer hides the error that started it; and a group kill macOS answers with EPERM counts as done
|
|
412
|
+
when only zombies are left in the group. Reinstall its LaunchAgent (`ProcessType Standard`).
|
|
413
|
+
- **Claude Code 2.1.325 runs again.** It (and 2.1.321 on) bundles `cc-plugin-privacy`, which relay
|
|
414
|
+
did not disable, so every Claude turn was refused ("plugins bundled with this Claude Code version
|
|
415
|
+
that relay does not yet disable"). Relay now disables it and `claude-platform` (2.1.325's name for
|
|
416
|
+
2.1.321's `cc-plugin-claude-platform`), and relay's release checks read the built-in registry, not
|
|
417
|
+
only `cc-plugin-` strings, so an unprefixed built-in is seen. Disabling `cc-plugin-privacy` means a
|
|
418
|
+
launched Claude agent no longer gets Claude Code's check against sending the signed-in account's
|
|
419
|
+
email as a client's identity.
|
|
420
|
+
- **Launched Claude agents keep `cc-plugin-privacy` on** (the maintainer, 2026-11-16), so they keep Claude
|
|
421
|
+
Code's refusal of a call that puts the signed-in account's email into a client's identity (a
|
|
422
|
+
User-Agent, a `From:` header, git's `user.email`, an SEC EDGAR identity), as an interactive
|
|
423
|
+
session has. Relay's isolation still fails closed for everything else: the plugin is admitted only
|
|
424
|
+
on a Claude Code version in `VERIFIED.claudePrivacyPlugin`, now <!-- verified:claudePrivacyPlugin -->2.1.325 and 2.1.326<!-- /verified -->,
|
|
425
|
+
whose copy relay read (a deny-only `tool.check` hook with the `fs.list`, `fs.read` and
|
|
426
|
+
`session.identity` calls; from 2.1.326 also a `session.identity` hook that only refuses or
|
|
427
|
+
withholds the identity it is asked for), and only when the init report lists it as
|
|
428
|
+
exactly that built-in, with no skill, command, agent, MCP server or tool of its own. On any other
|
|
429
|
+
version, or one whose `--version` relay cannot read, relay disables it as before, and an init
|
|
430
|
+
report that lists it anyway refuses the turn. `claude-platform` and every other built-in stay
|
|
431
|
+
disabled. Relay's release checks compare the plugin's code in each new release whole, canonicalized and
|
|
432
|
+
hashed (`PRIVACY_PLUGIN_DIGESTS`, one per version a person read), and adds the version to the list only when it is one of those; any
|
|
433
|
+
change, or anything it cannot read, is reported with a diff for review and the plugin stays off there. Nothing to do on upgrade.
|
|
434
|
+
|
|
435
|
+
## Relay 1.1.3
|
|
436
|
+
|
|
437
|
+
No config or registry migration is needed. What changes:
|
|
438
|
+
|
|
439
|
+
- **`relay doctor` says which agents the never floor's path entries bind** (new "never enforced"
|
|
440
|
+
line). Codex's sandbox takes `never.paths` and the built-in entries on every sandboxed turn;
|
|
441
|
+
Claude's, Copilot's, Gemini's and Grok's profiles take them only with stage 2 on, which then
|
|
442
|
+
refuses Copilot and Grok. With stage 2 off, the default, those four agents are not held to the
|
|
443
|
+
path entries. This is disclosure only, the maintainer's decision for 1.1.3 (Nov 4, 2026); enforcement is
|
|
444
|
+
unchanged. `relay doctor`'s "never enforced" line shows which agents enforce what.
|
|
445
|
+
- **Qualification fixes** (the qualifier and red team, not relay itself):
|
|
446
|
+
- checks that could pass without evidence now fail closed: item 6 (the token check and the
|
|
447
|
+
app-server half count only when their command ran and the app server was read), item 13 (the
|
|
448
|
+
older Codex's part needs its command to have run), the Codex live lane's Daybreak cases (no
|
|
449
|
+
thread, or a rollout with no turn, is "not run"), and the red team's tick, process-table and
|
|
450
|
+
nc probes;
|
|
451
|
+
- item 12's negatives count only plugin discovery at the run's fake service, so Codex 0.166.0's
|
|
452
|
+
account-check, settings and analytics calls with plugins off no longer fail it; a discovery
|
|
453
|
+
request still does;
|
|
454
|
+
- item 27's listen case binds a port below the ephemeral range, so an outgoing connection can no
|
|
455
|
+
longer take it first (`EADDRINUSE`);
|
|
456
|
+
- the suite's real-Codex sandbox tests take `RELAY_TEST_CODEX`, which gates set to the pinned
|
|
457
|
+
Codex, and fail rather than skip under `RELAY_REQUIRE_REAL_CODEX=1`.
|
|
458
|
+
- **For contributors:** the test harness writes an owner file (`<dir>.owner`, the pid) beside each
|
|
459
|
+
`/Users/Shared/relay-*` scratch tree and, at start-up, removes the trees of this user's whose
|
|
460
|
+
owner process is gone (a killed run skips its exit cleanup). Trees without an owner file, from
|
|
461
|
+
before 1.1.3, are left for you to remove; `RELAY_TEST_KEEP_SCRATCH=1` turns the sweep off.
|
|
462
|
+
- **Diagnostics:** when an app server's stop cannot be confirmed, the job's error now says the
|
|
463
|
+
executor stays quarantined until you clear it (below), instead of "until a later sweep does".
|
|
464
|
+
|
|
465
|
+
- **An app server relay cannot confirm stopped keeps its executor quarantined, as a refused stop
|
|
466
|
+
does.** When a job's worker has died and reap kills its orphaned Codex app server, but the
|
|
467
|
+
group is still there a second after SIGKILL, or a cancel's process group does not exit (and was
|
|
468
|
+
not refused), the stage-2 executor is still stopped and swept, but its record stays in
|
|
469
|
+
`<relay home>/executors/` (`~/.local/state/relay/executors/` by default), tainted
|
|
470
|
+
`untraceable app-server cleanup: …`. No later sweep, however clean, lets it go: the app server
|
|
471
|
+
may still be running and could reconnect to the executor's port. Before, a clean sweep released
|
|
472
|
+
the record.
|
|
473
|
+
- **While the record is there, its ports stay leased and local mode is refused.** The record
|
|
474
|
+
keeps its ports in relay's reserved range, so no other turn is given them, and the local-mode
|
|
475
|
+
interlock refuses `grant.local_network` (`executor <record> of <job> state tainted; reap/cancel
|
|
476
|
+
and verify cleanup before local launch`). The job's error, or the cancel's warning, names the
|
|
477
|
+
process group that may still be running.
|
|
478
|
+
- **Clearing it is the person's, after checking cleanup.** Relay never clears this quarantine by
|
|
479
|
+
itself. Seeing that the group named is gone is not enough: a detached descendant (one that
|
|
480
|
+
called setsid, or a double fork) has left that group and still runs. Check that nothing of the
|
|
481
|
+
turn is left, including such processes: the app server and whatever it started, and the
|
|
482
|
+
executor's pid, group and the `descendants` its record lists. Look for any process whose
|
|
483
|
+
arguments or environment name the record's `tmpDir` or the job's worktree, for example with
|
|
484
|
+
`ps -E -axww`. Stop anything you find. Then remove the record file from
|
|
485
|
+
`<relay home>/executors/`. Its ports are free again once no process its leases name is running
|
|
486
|
+
(`<relay home>/ports/`), and the interlock no longer refuses on that record.
|
|
487
|
+
|
|
488
|
+
That clears only the record. Two other things can still make the interlock refuse local mode,
|
|
489
|
+
and relay has no supported way to clear either yet:
|
|
490
|
+
- **A launch reservation.** A stage-2 turn's reservation (raw network, or an overlay's turn)
|
|
491
|
+
comes out clean only when reap finds the turn's executor record and the worker recorded the
|
|
492
|
+
app server's cleanup as clean. Once the record is removed, it can never come out clean, so it
|
|
493
|
+
stays, tainted, and refuses local mode (`launch reservation <turn> of <job> tainted reserves
|
|
494
|
+
stage2; …`).
|
|
495
|
+
- **The job's agent group, for a job with no reservation.** Relay keeps the group it could not
|
|
496
|
+
confirm stopped on the job's record. The interlock refuses local mode while a write turn with
|
|
497
|
+
raw network has an agent group on record (`… terminal turn retains agent group`). Cancel and
|
|
498
|
+
the lost-worker reap act only on active jobs, so neither looks at that group again.
|
|
499
|
+
|
|
500
|
+
## Relay 1.1.2
|
|
501
|
+
|
|
502
|
+
No config or registry migration is needed. What changes:
|
|
503
|
+
|
|
504
|
+
- **A tool call can no longer hang on a broken broker request.** When relay's broker cannot
|
|
505
|
+
serve an MCP request, the call now fails instead of staying pending until Codex's tool timeout
|
|
506
|
+
(an MCP `status` call could hang this way). Error replies keep the request's id where it is
|
|
507
|
+
known instead of answering with `id: null`, broken SSE responses end cleanly instead of getting
|
|
508
|
+
a raw HTTP status line, the server's header timeout is on, and client errors are logged with
|
|
509
|
+
their code.
|
|
510
|
+
- **The stage-2 network probe retries port-0 listens past denied ports**, up to
|
|
511
|
+
max(5, longest run of denied ports + 2) times, with diagnostics if it still fails.
|
|
512
|
+
- **Qualification item 12 has a positive control for discovery prefetch.** New pin receipts use
|
|
513
|
+
the `stage2-v3` schema (v2 plus item 12's `prefetch` part). Existing 1.1.0 and 1.1.1 pins keep
|
|
514
|
+
validating against the schema they were qualified under; nothing needs to be requalified.
|
|
515
|
+
- **The qualifier skips a Codex version that already failed** at the same binary and Relay
|
|
516
|
+
commit; `--force` retries it. See [Pinned Codex](pinned-codex.md).
|
|
517
|
+
- **A replaced installation refuses only for the sealed Codex pin store.** If a package-manager
|
|
518
|
+
upgrade replaces something in relay's pinned Codex store during a run, that run refuses to
|
|
519
|
+
launch until a fresh one starts: restart relay's MCP server (per-session connection) or use a
|
|
520
|
+
new session (shared server). Updates to other CLIs, Node or git are taken up at the next
|
|
521
|
+
checkpoint, as before.
|
|
522
|
+
- **Agent cleanup is sturdier.** The Codex app server, ACP and stream backends take their last
|
|
523
|
+
process snapshot before every stop signal. If a group cleanup is refused, the turn still
|
|
524
|
+
settles: its pipes and pending requests are closed, the refusal is reported as a warning, and a
|
|
525
|
+
stage-2 executor stays quarantined with its record and ports rather than being signalled or
|
|
526
|
+
swept.
|
|
527
|
+
- **For contributors:** three load-sensitive tests now wait on state rather than on fixed
|
|
528
|
+
timings.
|
|
529
|
+
|
|
530
|
+
## Relay 1.1.1
|
|
531
|
+
|
|
532
|
+
No config or registry migration is needed. What changes:
|
|
533
|
+
|
|
534
|
+
- **Launches re-check this Mac's addresses.** Relay takes a fresh never-floor checkpoint
|
|
535
|
+
immediately before Codex's `turn/start`, the exec spawn and ACP's `session/prompt`. If the
|
|
536
|
+
floor has gained a routable address since the launch plan was built, the turn is refused
|
|
537
|
+
with nothing started; send it again. Rotating link-local addresses still pass.
|
|
538
|
+
- **Relay never signals its own process group or a parent's.** Every group signal goes through
|
|
539
|
+
one guard, which refuses such a group (unless its recorded leader is verified fresh) and
|
|
540
|
+
reports the refusal; cleanup derived from a refused group is skipped. If an orphaned app
|
|
541
|
+
server's stop is refused, its executor stays quarantined: it is not cleaned up, its lease is
|
|
542
|
+
not released, and the quarantine reason is kept.
|
|
543
|
+
- **Pin receipts are versioned.** Verdicts and new pin manifests record the schema they were
|
|
544
|
+
qualified under (`stage2-v1`, `stage2-v2`), and new manifests seal the verdict's SHA-256.
|
|
545
|
+
Existing 1.1.0 pins keep validating against the `stage2-v1` baseline; nothing needs to be
|
|
546
|
+
requalified.
|
|
547
|
+
- **Codex 0.166.0 can be admitted.** From 0.166.0, relay pins `plugin_discovery_prefetch` and
|
|
548
|
+
`prediction_preserve_parent_tools` off and allows `reasoning_effort_override`; qualification
|
|
549
|
+
item 10 gains an effort check. 0.164.0 stays the pin until the qualifier qualifies 0.166.0.
|
|
550
|
+
- **Codex 0.167.0 is no longer refused for `deferred_tool_world_state`.** 0.167.0 turns this
|
|
551
|
+
feature on by default (it describes deferred tool namespaces to the model), and the stage-2
|
|
552
|
+
readback refused every turn because relay had not qualified it on. Relay now pins it off on
|
|
553
|
+
every version, as 0.164.0 and 0.166.0 already ship it. 0.167.0 still needs the qualifier.
|
|
554
|
+
- **The qualifier needs a rebuilt checkout.** Its process supervisor now imports the checkout's
|
|
555
|
+
`dist/core/procs.js`; after updating the qualifier's dedicated checkout, rebuild it before
|
|
556
|
+
resuming its schedule. See [Pinned Codex](pinned-codex.md).
|
|
557
|
+
- **For contributors:** `npm test` runs eight test files at a time, and
|
|
558
|
+
`RELAY_TEST_ESCALATION_LONG=readback` gives qualification item 30 a readback-only mode for
|
|
559
|
+
release gates (the hour-long call is recorded as not run, so it can never promote a pin).
|
|
560
|
+
|
|
561
|
+
## Relay 1.1.0
|
|
562
|
+
|
|
563
|
+
### Before you upgrade: Relay's Codex runs on a pinned copy
|
|
564
|
+
|
|
565
|
+
Relay's Codex jobs now run on Relay's own qualified copy of Codex, with stage 2 on or off.
|
|
566
|
+
Your interactive Codex keeps updating by itself and is not used. `targets.codex.pinned`
|
|
567
|
+
defaults to `true`, so **until a qualified copy exists on this Mac, every Relay Codex job
|
|
568
|
+
refuses**, including reviews, with `relay refuses Codex: no valid qualified pin`. There is no
|
|
569
|
+
fallback to interactive Codex.
|
|
570
|
+
|
|
571
|
+
Before installing this version on a Mac that runs Codex jobs, follow
|
|
572
|
+
[Pinned Codex](pinned-codex.md): qualify a Codex from a logged-in terminal, and log in once to
|
|
573
|
+
Relay's own Codex home (`~/.local/share/relay-codex-home`). (A release's shipped pin, from a later
|
|
574
|
+
release on, replaces the first step.) `targets.codex.pinned: false` is the
|
|
575
|
+
explicit opt-out, and selects `targets.codex.bin`.
|
|
576
|
+
|
|
577
|
+
Stage 2 itself stays off unless `targets.codex.stage2` is set.
|
|
578
|
+
|
|
579
|
+
### Escalation qualification gates (WP6)
|
|
580
|
+
|
|
581
|
+
Stage-2 qualification now requires items **1–32**, including the restart/authority,
|
|
582
|
+
deadline/floor, overlay-profile, mediated and adapter tests. Historical 22-item
|
|
583
|
+
verdicts do not qualify this enlarged gate. Known missing integrated cases remain
|
|
584
|
+
explicit pending parts; no pin is promoted from partial, skipped or opt-out evidence.
|
|
585
|
+
The new `RELAY_TEST_ESCALATION_LONG=1` probe runs a real Codex MCP call for 3601 seconds;
|
|
586
|
+
the public control still requires `RELAY_TEST_PUBLIC_NET=1`. See the
|
|
587
|
+
[acceptance map, omissions and exact host commands](qualification/escalation-wp6.md).
|
|
588
|
+
The owner decisions below also change stage-2 network routing; no config schema or
|
|
589
|
+
registry migration is required.
|
|
590
|
+
|
|
591
|
+
### Mediated network, standing and one-turn
|
|
592
|
+
|
|
593
|
+
`escalate` accepts `{ "kind": "network", "mode": "mediated" }` for one replacement
|
|
594
|
+
Codex app-server turn. With stage 2 enabled, network-disabled jobs now use the stage-2
|
|
595
|
+
executor too, so they can request that restart. The authenticated owning run root may
|
|
596
|
+
approve clearly authorized network work; uncertain authorization goes to the person.
|
|
597
|
+
Raw/local network remains person-only. With stage 2 on, standing non-raw `grant.network`,
|
|
598
|
+
`child_network` and kept grants on resume use this same mediated provider every turn,
|
|
599
|
+
without escalation. Read jobs with network use the executor and proxy too; filesystem
|
|
600
|
+
access stays read-only. An overlay preserves that baseline plus its approved addition;
|
|
601
|
+
raw substitution is refused. Unqualified stage2 settings, an exec-only backend or an
|
|
602
|
+
unavailable provider refuse launch with a reason; there is no native strict or raw fallback.
|
|
603
|
+
Stage 2 off preserves the released native route and its never-host refusal.
|
|
604
|
+
|
|
605
|
+
Hosted web search still runs at OpenAI, live with a network grant, and is disabled and
|
|
606
|
+
read back when `never.hosts` is set. It does not traverse the executor proxy. The native
|
|
607
|
+
"strict" note describes only the stage-2-off route; these turns report "stage-2 mediated"
|
|
608
|
+
and doctor describes both routes.
|
|
609
|
+
|
|
610
|
+
The trusted worker runs relay's existing public HTTP forwarding, CONNECT and SOCKS5
|
|
611
|
+
proxy at 127.0.0.1 on a separately leased port. Commands get uppercase and lowercase
|
|
612
|
+
HTTP_PROXY, HTTPS_PROXY and ALL_PROXY, with empty NO_PROXY. The app server receives
|
|
613
|
+
no added proxy environment: its broker credential retains its existing bypass.
|
|
614
|
+
Codex's `network_proxy` stays pinned off. Relay's executor profile has egress disabled
|
|
615
|
+
and allows only the worker proxy's leased IPv4 transport port; its final never rules
|
|
616
|
+
retain all service and control restrictions with that internal transport exception.
|
|
617
|
+
Approved IPv4 localhost-connect additions also permit their named port. No proxy credential is
|
|
618
|
+
required; other jobs' sandboxes cannot reach the port, and unsandboxed local processes
|
|
619
|
+
already have network authority.
|
|
620
|
+
|
|
621
|
+
Never hosts are compatible with mediated networking. Worker DNS follows CNAMEs,
|
|
622
|
+
checks every requested authority and every numeric result, and dials only screened
|
|
623
|
+
numeric addresses. Before every new request it refreshes all forbidden DNS endpoints
|
|
624
|
+
and retains every endpoint seen during the turn. An unavailable, malformed or stale
|
|
625
|
+
forbidden endpoint set refuses the connection; launch also requires an initial set.
|
|
626
|
+
No stale-cache or raw fallback exists. The proxy follows no redirects: each client
|
|
627
|
+
request after a redirect is screened again, including its port. Teardown cancels DNS,
|
|
628
|
+
closes listeners, pending connects and live tunnels. A teardown error follows the
|
|
629
|
+
existing uncertain-cleanup accounting. A worker crash closes the proxy's sockets.
|
|
630
|
+
|
|
631
|
+
No Go/Swift TLS for these jobs until Release B: TRUST remains off, so tools using
|
|
632
|
+
Security.framework TLS verification fail. Node/OpenSSL success does not qualify them.
|
|
633
|
+
Tools must honour proxy settings, or explicitly use the HTTP/SOCKS5 endpoint; direct
|
|
634
|
+
TCP, UDP and DNS fail except separately approved localhost capabilities. Tools that
|
|
635
|
+
ignore proxy variables fail closed. Opaque CONNECT/SOCKS tunnels are screened by
|
|
636
|
+
requested authority and checked endpoint, without TLS inspection or SNI checks.
|
|
637
|
+
Native strict's existing trustd
|
|
638
|
+
residual is unchanged: the lead measured certificate-driven blind OCSP/CRL GETs to
|
|
639
|
+
owned local decoys (including redirects) on 1.0.5/1.0.6, without establishing arbitrary
|
|
640
|
+
response access. Stage 2's no-TRUST path is unaffected by that measured route; Claude's
|
|
641
|
+
corresponding trustd behavior is unverified. See [qualification and host commands](qualification/mediated-network.md).
|
|
642
|
+
|
|
643
|
+
### IPv4 localhost-port connects
|
|
644
|
+
|
|
645
|
+
`{kind:"localhost", operation:"connect", host:"127.0.0.1", port:P}` compiles to
|
|
646
|
+
Seatbelt's `(remote ip4 "localhost:P")`. This also reaches port P on this Mac's LAN
|
|
647
|
+
and tailnet addresses; the approval request, receipt and result disclose it, including
|
|
648
|
+
failed or cancelled turns. `127.0.0.2`, `::1`, mapped IPv6 and other ports stay denied
|
|
649
|
+
unless separate baseline authority already permits them. Clearly authorized work may
|
|
650
|
+
be approved by the owning supervisor; otherwise ask the person. Service API effects
|
|
651
|
+
count. Never and relay control ports stay denied by number, with final denies winning.
|
|
652
|
+
Connect additions remain refused with `never.hosts`: their direct allowance cannot
|
|
653
|
+
enforce forbidden DNS endpoints. No per-turn proxy token was added.
|
|
654
|
+
|
|
655
|
+
### Test temporary paths
|
|
656
|
+
|
|
657
|
+
All test files share a short temp root when the inherited macOS TMPDIR would make a
|
|
658
|
+
probe socket exceed 103 bytes. Child fixtures inherit it too. The cancellation probe's
|
|
659
|
+
polling timer now clears even when setup/assertion fails, so an earlier socket failure
|
|
660
|
+
cannot keep that test process alive. Run the full suite from the default shell with
|
|
661
|
+
`node --test --test-timeout=600000 --test-concurrency=1 test/*.test.ts` after building.
|
|
662
|
+
|
|
663
|
+
### Escalation approval authority (WP3)
|
|
664
|
+
|
|
665
|
+
The child broker serves `escalate` independently of delegation. It requests typed capabilities
|
|
666
|
+
for one replacement turn; a qualified WP2 lifecycle must be registered before a provider is
|
|
667
|
+
available. Missing providers refuse before approval. The tool executes no command and creates no
|
|
668
|
+
standing grant. Release A still refuses local mode while stage 2 is enabled.
|
|
669
|
+
|
|
670
|
+
The existing boolean `escalation` setting remains supported. To require person approval for
|
|
671
|
+
port-0, use `"escalation": { "port0_authority": "person" }`; the default is `"supervisor"`,
|
|
672
|
+
meaning the authenticated owning run root, for clearly authorized tests/servers. Broad raw/local
|
|
673
|
+
network remains person-only. Labels and `user_confirmed` prose never substitute for that route.
|
|
674
|
+
Port-0 approval and job results disclose possible 0.0.0.0/LAN listening and whole-turn access to
|
|
675
|
+
worktree code the agent may edit after approval. Missing person channels return
|
|
676
|
+
`person_path_unavailable`. Outside writes persist; results report launch scope and cleanup.
|
|
677
|
+
|
|
678
|
+
New Codex registrations reserve the finite overlay/transition budget too: the default MCP timeout
|
|
679
|
+
is 11400 seconds. Reinstall and restart Codex to refresh the root registration. The prior shipped
|
|
680
|
+
3600-second default upgrades automatically; unrelated custom settings retain existing safeguards.
|
|
681
|
+
Launched stdio/broker registrations and readback share the timeout calculation. See
|
|
682
|
+
[WP3 integration and qualification](qualification/escalation-wp3.md) for the WP2 seam and host checks.
|
|
683
|
+
### Never policy (WP1)
|
|
684
|
+
|
|
685
|
+
WP1 adds strict additive `never.paths`, `never.ports`, `never.hosts` and
|
|
686
|
+
`never.override_builtin` config. **The registry stays at schema 4; no migration.**
|
|
687
|
+
The per-run never floor lives in private `params_json` within the existing run JSON
|
|
688
|
+
envelope, separate from effective config. Each run durably retains every observed
|
|
689
|
+
addition; removals need a new run. Host entries disable raw grants and require
|
|
690
|
+
hosted web search/open-page withholding with effective readback. Extension servers
|
|
691
|
+
are refused for Release A until their per-server never-screen adapter is qualified,
|
|
692
|
+
before consent or launch. The initial production catalog is empty; person consent
|
|
693
|
+
does not bypass this refusal. The adapter interface remains available for qualification.
|
|
694
|
+
Older relay
|
|
695
|
+
versions reject the new public config keys; remove them from person-edited config
|
|
696
|
+
before using an older version.
|
|
697
|
+
|
|
698
|
+
Stage 2 runs a Codex job's commands inside relay's own Seatbelt sandbox, so that the job can have
|
|
699
|
+
raw network. It is off by default and requires no registry migration. MCP tools and
|
|
700
|
+
config change additively.
|
|
701
|
+
|
|
702
|
+
- **New config key: `targets.codex.stage2`** (boolean, default off). It switches stage 2 on.
|
|
703
|
+
`RELAY_EXPERIMENTAL_CODEX_STAGE2=1` in relay's environment does the same, for tests and
|
|
704
|
+
development. Keep the key out of a config that an older relay reads: an older relay rejects
|
|
705
|
+
unknown keys.
|
|
706
|
+
- **New: `grant.raw_network: true`** on `delegate` and `resume`, for Codex write jobs, with
|
|
707
|
+
`network: true` in the same grant, on the app-server backend. It cannot be combined with
|
|
708
|
+
`local_network`. With stage 2 off, it is refused.
|
|
709
|
+
- **Only you can allow it.** Relay files a person-only request (`raw_network`) before the job's
|
|
710
|
+
first turn under the grant. The root's `approve` and `relay approve` cannot allow it. Where relay
|
|
711
|
+
has no way to ask you, the grant is refused up front. A resume that changes the grant asks again.
|
|
712
|
+
A resume that drops `raw_network` ends the consent. A local-network consent never counts.
|
|
713
|
+
- **What the job gets.** Raw TCP, UDP, ssh and DNS to the internet. Your LAN and tailnet on every
|
|
714
|
+
port; relay cannot close them. This Mac's loopback except the denied ports (TCP 22, 1025, 1143,
|
|
715
|
+
8787, 11143, 5900, 3283, 3031, 445, 548, 631; every port anything on this Mac listens on when the
|
|
716
|
+
turn starts, the system's included; relay's reserved range 47200-47263 but the job's own block) and
|
|
717
|
+
UDP 1900 and 5351 to every host. Over IPv6 the denied ports are refused at every host: the sandbox
|
|
718
|
+
cannot otherwise refuse the IPv4-mapped forms of this Mac's addresses (`::ffff:0.0.0.0`,
|
|
719
|
+
`::ffff:` and its LAN address), which reach its services. IPv6 to those port numbers fails
|
|
720
|
+
everywhere, and so does IPv4 sent through an IPv6 socket (Java by default). Otherwise the deny
|
|
721
|
+
matches this Mac's own addresses only: a port forward reached through NAT hairpin, a tailnet
|
|
722
|
+
subnet router or a VM bridge can lead back to a denied service.
|
|
723
|
+
- **What the job loses.** Read these before you switch it on:
|
|
724
|
+
- It can listen only on its block of 4 TCP ports (`PORT`, `PORTS`). Port 0 and every other fixed
|
|
725
|
+
port fail: `node --inspect` on 9229, `python -m http.server` without a port, `ssh -L`, test
|
|
726
|
+
runners that pick their own port. A server bound on 0.0.0.0 on a block port is visible on your
|
|
727
|
+
LAN and tailnet.
|
|
728
|
+
- Services already running when the turn started, yours or the system's, are denied to it at
|
|
729
|
+
every address of this Mac: your database, ollama, Jupyter, a dev server.
|
|
730
|
+
- git cannot write inside the job. `git add`, `commit`, `stash`, `checkout -b`, `rebase`, and
|
|
731
|
+
tools that call git fail. Relay commits the worktree at the end of each turn with its own
|
|
732
|
+
message, so the agent's own commits and messages are lost.
|
|
733
|
+
- Unix sockets only under the turn's temporary directory and a relay-made worktree; no image
|
|
734
|
+
generation; executables only from the usual system and developer locations.
|
|
735
|
+
- **No relay tools.** The job's Codex app server runs without Codex's own local environment
|
|
736
|
+
(`CODEX_EXEC_SERVER_URL=none`), so that a turn Codex starts by itself has nowhere outside
|
|
737
|
+
relay's sandbox to run a command. A stdio MCP server needs that environment, relay's own
|
|
738
|
+
included, so a raw-network job cannot delegate, ask or use any other relay tool, and runs no MCP
|
|
739
|
+
server at all. Give such a job everything it needs up front, or do the nesting from the root.
|
|
740
|
+
- **Requirements.** Codex 0.164.0 or later, `child_mcp: "relay-only"`, `child_hooks: false`, and no
|
|
741
|
+
extension servers on the job. Otherwise the turn is refused with the reason.
|
|
742
|
+
- **Switching stage 2 on switches local mode off.** Codex's local-mode proxy has no
|
|
743
|
+
authentication, and Codex binds it on ephemeral ports, so relay cannot fence it off. While stage
|
|
744
|
+
2 is on, `grant.local_network` is refused on `delegate` and `resume`, and a turn of a job that
|
|
745
|
+
still holds it fails before its agent starts, asking nobody. Continue such jobs with
|
|
746
|
+
`raw_network` (and the person's consent) or with `network` alone.
|
|
747
|
+
- **Across runs.** The switch is read from each run's config, fixed when the run starts. While a
|
|
748
|
+
raw-network turn runs, a local-mode turn of a run with stage 2 off gets hosted web search only,
|
|
749
|
+
with the reason in its notes; while a local-mode turn that started before the switch runs, a
|
|
750
|
+
raw-network turn is refused. Relay sees its own registry only.
|
|
751
|
+
- **With stage 2 off, nothing changes.** `grant.raw_network: false` is accepted as no grant, from
|
|
752
|
+
the root and from launched agents alike, as before the key existed. With stage 2 on it counts as
|
|
753
|
+
a grant: a root's `resume` with it replaces the job's grant (dropping raw network), and a launched
|
|
754
|
+
agent's is refused like any grant it gives. A local-mode turn reads relay's registry once for
|
|
755
|
+
running raw-network turns; with stage 2 off everywhere it finds none.
|
|
756
|
+
- **Local mode is to be retired fully when stage 2 ships (decision D2). Not done yet.** Jobs that use
|
|
757
|
+
`grant.local_network` will have to move to `raw_network`, with renewed consent. That brings raw
|
|
758
|
+
egress, the LAN, the port block and the denied running services along. No mode will be left with
|
|
759
|
+
proxied egress and loopback.
|
|
760
|
+
|
|
761
|
+
## Relay 1.0.7 (2026-10-29)
|
|
762
|
+
|
|
763
|
+
- **A native turn's temp cleanup no longer crashes the worker.** In 1.0.6, if a job left files in
|
|
764
|
+
its private temporary directory that were still being closed, removing it could fail with
|
|
765
|
+
`ENOTEMPTY`. The worker then stopped with an error, and the job was marked failed although its
|
|
766
|
+
agent had finished. Removal now retries briefly. If something still can't be removed, the turn
|
|
767
|
+
keeps its outcome and reports the leftover as a warning in its result and its agent log;
|
|
768
|
+
relay's temp sweep retries later.
|
|
769
|
+
|
|
770
|
+
## Relay 1.0.6 (2026-10-29)
|
|
771
|
+
|
|
772
|
+
- **Relay-enforced harnesses (Copilot, Gemini, Grok) with the network on now have IPv4 only.**
|
|
773
|
+
Through 1.0.5 their profile refused this Mac's own addresses with `(remote ip "localhost:*")`,
|
|
774
|
+
which Seatbelt does not match for the IPv4-mapped IPv6 spellings of those addresses, loopback's
|
|
775
|
+
apart: a connect to `::ffff:0.0.0.0` reached this Mac's loopback services, and one to `::ffff:`
|
|
776
|
+
followed by its LAN or tailnet address reached services listening there (review R1, measured on
|
|
777
|
+
macOS 27.0.1). The only rule that refuses those spellings refuses all IPv6, so the profile now
|
|
778
|
+
allows IPv4 alone and refuses this Mac's own IPv4 addresses. Tools that try IPv6 first fall back
|
|
779
|
+
to IPv4 at once (curl, git over HTTPS and Node's fetch, measured). A client that reaches IPv4
|
|
780
|
+
hosts through an IPv6 socket (Java by default) is refused; `-Djava.net.preferIPv4Stack=true`
|
|
781
|
+
avoids it. The per-turn probes now try every address of this Mac's own, the IPv4-mapped and
|
|
782
|
+
-compatible spellings included, with the network on and off. Strict Codex jobs and Claude jobs
|
|
783
|
+
are not affected: their proxies already refused these spellings.
|
|
784
|
+
- **No grant may cover what relay runs outside every sandbox** (review r_0c11d860 X1): relay's own
|
|
785
|
+
installation (the checkout whose `dist/` is running), the Node it runs on, and each target's CLI,
|
|
786
|
+
by the name relay starts, the file it leads to and the Homebrew keg, npm package or Node
|
|
787
|
+
distribution holding it. Before, a person-given `grant.write_paths` over the checkout or one of its
|
|
788
|
+
parents let a write job change relay's code, which relay runs unconfined at its next start. A grant
|
|
789
|
+
a job already holds is checked again on its next turn and refused there if it covers one of them;
|
|
790
|
+
continue such a job with a grant that leaves that out. File requests there are refused too, and
|
|
791
|
+
relay's Seatbelt profiles and Claude's sandbox settings deny writing relay's installation and Node.
|
|
792
|
+
Limits: README, Known limits.
|
|
793
|
+
- **Relay runs every program by an absolute path, and no grant may cover a directory on its PATH**
|
|
794
|
+
(r_0c11d860 X1). macOS's own tools (`pgrep`, `osascript`, `sw_vers`, `xcode-select`, `sleep`, `tty`)
|
|
795
|
+
run from the system volume; git and the target CLIs are found on PATH and run by the absolute
|
|
796
|
+
name found (git once per process). Before, relay started several by name, so a program a job put
|
|
797
|
+
in a granted directory earlier on PATH would have run instead, unconfined. The git relay runs is
|
|
798
|
+
protected as relay's installation is (grants, file requests, the sandboxes' write denies), and so
|
|
799
|
+
are the developer tools behind `/usr/bin/git` when that is the git found. A grant over a directory
|
|
800
|
+
on relay's PATH, one holding it or one inside it, is now refused, and a kept one is refused on its
|
|
801
|
+
next turn. Relay's Seatbelt profiles and Claude's sandbox settings now deny writing the target CLIs
|
|
802
|
+
and relay's PATH directories as well, and a turn whose own PATH finds its target's CLI in, or
|
|
803
|
+
passes through, one of its write paths is refused at launch.
|
|
804
|
+
|
|
805
|
+
## Relay 1.0.5
|
|
806
|
+
|
|
807
|
+
1.0.5 closes the local reach of network-granted Codex jobs and of Claude jobs' shells (Unix
|
|
808
|
+
sockets, loopback and, for Claude, the LAN) that 1.0.4 recorded as still open, by address. The
|
|
809
|
+
network's own public address is not screened; a Claude job under `child_settings: "inherit"` keeps
|
|
810
|
+
any Unix sockets your own settings list in `allowUnixSockets`; and Claude's own WebFetch is pointed
|
|
811
|
+
at relay's proxy but not guaranteed to use it under settings relay cannot see (README, Known
|
|
812
|
+
limits). It also closes a way out of Codex's sandbox through
|
|
813
|
+
exec-policy allow rules. No registry migration; the MCP tools change additively
|
|
814
|
+
(`grant.local_network`).
|
|
815
|
+
|
|
816
|
+
### Codex jobs
|
|
817
|
+
|
|
818
|
+
- **A Codex job's granted network now goes through Codex's own network proxy, in strict mode.**
|
|
819
|
+
Codex's plain network toggle, which relay set before, also opened every Unix socket (your tmux
|
|
820
|
+
server's among them) and all of loopback (sshd, Proton Bridge) to the job's commands. Relay no
|
|
821
|
+
longer sets it alone. A job given network (a grant, or `child_network`; `allow_dangerous` is
|
|
822
|
+
unchanged) runs with `features.network_proxy` on, every public host allowed, no upstream proxy,
|
|
823
|
+
`allow_local_binding` off, and Unix sockets only under the turn's temporary directory and, for a
|
|
824
|
+
write job in its own worktree, that worktree. HTTP(S) works (curl, git over https, npm, pip); raw
|
|
825
|
+
TCP, ssh remotes, direct DNS, this Mac's loopback and the local network do not. A job that relied
|
|
826
|
+
on reaching a local service, or on ssh remotes, now fails at that step; see local mode below.
|
|
827
|
+
- **Verified before every turn, and hosted web search only where it cannot be.** A short-lived app
|
|
828
|
+
server with the turn's exact settings must show the proxy: config readback (the proxy feature as
|
|
829
|
+
`true`, the network table exactly), no administrator's network requirements, `network_proxy`
|
|
830
|
+
listed and on in Codex's feature list, and a check Codex runs in the sandbox itself
|
|
831
|
+
(`command/exec`) that finds relay's own loopback port and Unix socket unreachable and the proxy
|
|
832
|
+
refusing loopback. Strict mode also requires that none of this Mac's own addresses is one the
|
|
833
|
+
proxy would treat as public (a global IPv6 address), and that no exec-policy rules file Codex
|
|
834
|
+
loads holds `network_rule`. Otherwise the turn gets Codex's hosted web search and no shell
|
|
835
|
+
network, with the reason in the job's notes and at the top of the turn's input. The turn's own
|
|
836
|
+
server repeats all of these checks before its thread starts, and refuses the turn on a mismatch
|
|
837
|
+
(under `codex_backend: "exec"`, the short-lived server that checks its configuration does, since
|
|
838
|
+
`codex exec` reports nothing). Each
|
|
839
|
+
network turn's mode (strict, local, hosted search only) is in the job's notes (`status`, result).
|
|
840
|
+
This works on Codex 0.163.0 and 0.164.0, where the feature is experimental.
|
|
841
|
+
- **New: `grant.local_network: true`** (Codex write jobs, with `network: true`) for a job that needs
|
|
842
|
+
its own server on localhost. It opens this Mac's loopback and the local network to the job's
|
|
843
|
+
shell, with your account's reach: loopback directly as well as through the proxy, and the job may
|
|
844
|
+
listen on every interface, so devices on your LAN or tailnet can connect to servers it starts. Only you can allow it: a person-only request
|
|
845
|
+
(`local_network`) asked before the job's first turn under that grant, and again when a resume
|
|
846
|
+
changes the grant. The root's `approve` and `relay approve` cannot allow it; where relay has no
|
|
847
|
+
way to ask you (no approval dialog or `confirm`, or escalation off) the grant is refused up front.
|
|
848
|
+
- **Network added to one command.** On a Codex job without a network grant, relay now declines,
|
|
849
|
+
without asking anyone, a command's request to add the network to its sandbox
|
|
850
|
+
(`additionalPermissions.network`): without the proxy, Codex would give that command the old open
|
|
851
|
+
policy. Such denials are recorded with the job's refusals (`blocked`) and explained to the agent.
|
|
852
|
+
- **No access is added to one Codex command's sandbox any more.** Every turn switches off Codex's
|
|
853
|
+
`request_permissions` tool (its requests were never answered by relay) and its
|
|
854
|
+
`exec_permission_approvals` feature (`-c features.request_permissions_tool=false`, `-c
|
|
855
|
+
features.exec_permission_approvals=false`), both read back from the configuration and checked in
|
|
856
|
+
the feature list. With `exec_permission_approvals` on, a command your exec-policy rules allow
|
|
857
|
+
would get the access it names (`with_additional_permissions`, network included) without any
|
|
858
|
+
request reaching relay. If you turned the feature on, per-command file and network additions no
|
|
859
|
+
longer happen in relay's jobs.
|
|
860
|
+
- **Codex jobs can no longer read credential stores**: `~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.netrc`
|
|
861
|
+
and Codex's own `auth.json` (`$CODEX_HOME/auth.json` where CODEX_HOME is set) are denied in
|
|
862
|
+
relay's profile, read and write jobs alike, and confirmed by the exact profile readback on every
|
|
863
|
+
turn. A job that needed them (an ssh git remote, an AWS CLI call) now fails at that step.
|
|
864
|
+
- **Exec-policy allow rules no longer take a command out of the sandbox.** Codex runs a command your
|
|
865
|
+
rules allow (`~/.codex/rules`, `/etc/codex/rules`, or a trusted repository's committed
|
|
866
|
+
`.codex/rules`, which a job's worktree loads too) without asking and, before 1.0.5, outside the
|
|
867
|
+
sandbox. While a profile denies a read, Codex lets no command leave the sandbox, so such a command
|
|
868
|
+
now runs sandboxed. `relay doctor` lists your own rules files (`codex rules`). (From 1.1.0
|
|
869
|
+
relay's Codex jobs run with relay's own Codex home, so they load its `rules` folder, not
|
|
870
|
+
`~/.codex/rules`.)
|
|
871
|
+
- **An approved Codex command, or file change, no longer runs with full access.** For the same
|
|
872
|
+
reason Codex runs it in a sandbox that can write anywhere but the denied stores, with the job's own
|
|
873
|
+
network (none without a grant or after a fallback to hosted search; through the proxy in strict
|
|
874
|
+
mode; loopback and the LAN open directly in local mode). Writing anywhere in your home
|
|
875
|
+
directory is still your authority; the request's effect now says this instead of "full access".
|
|
876
|
+
A request to reach a host the sandbox blocked (`networkApprovalContext`) is declined by relay on
|
|
877
|
+
every job: with the proxy it can only be this Mac's own or a private address, and without it no
|
|
878
|
+
approval can give the network (the agent is told to ask for a network grant).
|
|
879
|
+
- **Codex's hosted web search with a network grant is unchanged** (`web_search = "live"`): it runs
|
|
880
|
+
at OpenAI, so it reaches nothing on this Mac, but its results can still carry prompt injection
|
|
881
|
+
and its queries leave the Mac.
|
|
882
|
+
|
|
883
|
+
### Claude jobs with a network grant
|
|
884
|
+
|
|
885
|
+
- **Their shell no longer reaches this Mac's local services or its LAN by address, and WebFetch
|
|
886
|
+
does not either unless settings relay cannot see exempt it.** In 1.0.4 relay gave a Claude job
|
|
887
|
+
with the network (a grant or `child_network`) Claude Code's own sandbox proxy with every host
|
|
888
|
+
allowed (`allowedDomains: ["*"]`). That proxy connected the job to loopback and LAN addresses by
|
|
889
|
+
IP literal (plain HTTP, CONNECT and SOCKS5 alike), and WebFetch, which runs outside the sandbox,
|
|
890
|
+
reached them directly. In 1.0.5 the sandbox sends every connection to a proxy relay runs for the
|
|
891
|
+
turn (`sandbox.network.httpProxyPort` and `socksProxyPort`), and the Claude process gets
|
|
892
|
+
`HTTPS_PROXY` with the turn's token and an empty `NO_PROXY`, which points WebFetch and Claude's
|
|
893
|
+
model traffic at it too (console-delivered settings can still exempt them: README, Known limits). The proxy refuses every address that is not public (see the README's
|
|
894
|
+
Known limits for the list), resolving each name itself and connecting to the address it checked.
|
|
895
|
+
It does not know the network's own public (WAN) address, which a router's port forwards, UPnP
|
|
896
|
+
mappings or hairpin NAT can lead back to this Mac or the LAN (README, Known limits).
|
|
897
|
+
- **What still works:** any public host on any port, over HTTP, HTTPS or SOCKS5 (`git` over https
|
|
898
|
+
and over ssh, `npm`, `pip`, `curl`), public IP literals, WebFetch and WebSearch. **What stops
|
|
899
|
+
working** (for the shell always; for WebFetch unless unseen settings exempt it): anything the job reached on `localhost`, the LAN, a Tailscale address (`100.64/10`) or
|
|
900
|
+
this Mac's own addresses. A job that needs a local server needs a run without relay's sandbox
|
|
901
|
+
(an approved unsandboxed command, or `allow_dangerous` for a write job).
|
|
902
|
+
- **Relay checks it as the turn runs.** It sets `SRT_DEBUG`, whose output (the sandbox's report of
|
|
903
|
+
its proxy ports) goes to the agent log only. A report naming a port other than relay's stops the
|
|
904
|
+
job at once. Network turns run with `--include-partial-messages`, and at the start of Claude's
|
|
905
|
+
first response, before a tool in it can run, both ports must have been relay's and the Claude
|
|
906
|
+
process must have sent at least one request with the turn's token to the model host through the
|
|
907
|
+
proxy (`api.anthropic.com`, or Bedrock's or Vertex's where chosen; another `CLAUDE_CODE_USE_*`
|
|
908
|
+
provider refuses the grant), or the job is stopped then with a reason saying which. This catches a
|
|
909
|
+
Claude process that ignores relay's proxy variables and a `NO_PROXY` covering the model host; it
|
|
910
|
+
does not prove that the model requests themselves, or WebFetch, went through the proxy. Settings
|
|
911
|
+
relay cannot see (an organisation's, from the claude.ai console: a managed `ANTHROPIC_BASE_URL`
|
|
912
|
+
with a `NO_PROXY` for its host, or a `NO_PROXY` listing local ranges) can send model requests or
|
|
913
|
+
WebFetch around the proxy unnoticed: that is outside what relay guarantees (README, Known limits).
|
|
914
|
+
- **New refusals, for network grants only:** a proxy (`HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY`) in
|
|
915
|
+
the environment relay passes to Claude, and, with `claude_managed_settings: "accept"`, managed
|
|
916
|
+
settings on disk that set the sandbox's proxy ports, local binding, Unix sockets or proxy
|
|
917
|
+
variables. A job without the network is unaffected by either.
|
|
918
|
+
- **Every Claude turn** now sets `allowLocalBinding` and `allowAllUnixSockets` to false in relay's
|
|
919
|
+
settings, which outrank your own under `child_settings: "inherit"`. A list of `allowUnixSockets`
|
|
920
|
+
in your own settings is still merged in under "inherit".
|
|
921
|
+
- **Checking a Claude Code version:** `RELAY_HOME=<scratch> node smoke/claude-network-probe.mjs`
|
|
922
|
+
runs relay's launch of the installed Claude Code (or `CLAUDE_BIN`) against a stub model and
|
|
923
|
+
reports every route, its stub model reached through relay's proxy; `--control port`, `--control
|
|
924
|
+
noproxy` and `--control modelbypass` check that relay stops a job whose sandbox, or whose model
|
|
925
|
+
traffic, bypasses its proxy, and `--control collision` shows the known limit above (not stopped). It spends no model usage. Relay's release checks run it on each new
|
|
926
|
+
version.
|
|
927
|
+
|
|
928
|
+
## Relay 1.0.4
|
|
929
|
+
|
|
930
|
+
Two things to know before upgrading: the registry migrates (schema 3 to 4), and `relay approve`
|
|
931
|
+
now has to be run at a terminal by a person. Still open in 1.0.4: a Codex job with a network
|
|
932
|
+
grant can reach local IPC and loopback (fixed in 1.0.5, above). What changes:
|
|
933
|
+
|
|
934
|
+
### What changes
|
|
935
|
+
|
|
936
|
+
- **Inbox notices say who sent them.** Claude Code shows everything on its inbox socket as a
|
|
937
|
+
message from another Claude session, so a relay notice could be read as coming from one, or
|
|
938
|
+
from the agent it is about. After the unchanged `relay (event N, tag <32 hex digits>): ` prefix,
|
|
939
|
+
each notice now says so: `Sent by the local relay server, not by a Claude session or by the
|
|
940
|
+
Codex agent (OpenAI) of job j_….`, naming that agent's harness and family from relay's
|
|
941
|
+
registry, or just `Sent by the local relay server, not by a Claude session.` when the event is
|
|
942
|
+
about no launched agent. The verification direction and pointer follow as before. Consumers
|
|
943
|
+
matching the prefix are unaffected; anything matching `): Verify first` straight after the tag
|
|
944
|
+
must allow the new sentence. Tool-result `events` and verified events are unchanged. Line 1 of
|
|
945
|
+
`notice.txt` and line 2 of `inbox.jsonl` change accordingly; no other fixture does. Claude
|
|
946
|
+
Code's inbox format has no documented sender field relay could set instead
|
|
947
|
+
([stable-surfaces](stable-surfaces.md#events-and-notices)).
|
|
948
|
+
- **`relay approve` now requires a person at an interactive terminal.** Allowing a request from the
|
|
949
|
+
command line prints a one-time code that you type back, and refuses unless stdin and stdout are an
|
|
950
|
+
interactive terminal and the command is not running inside a relay-launched agent's process tree
|
|
951
|
+
(by the environment marker relay sets on launched agents, or by process ancestry, group or
|
|
952
|
+
session). This replaces the old environment-marker-only check. It raises the bar against a naive
|
|
953
|
+
or accidental approval; it is **not** a security boundary. The boundary that keeps a launched
|
|
954
|
+
agent from deciding its own request is confinement — the sandbox that keeps the agent out of
|
|
955
|
+
relay's registry. A command relay does not confine (`allow_dangerous`, or a command allowed to run
|
|
956
|
+
outside the sandbox) runs with your authority and can get past this check, the same way it could
|
|
957
|
+
write relay's registry directly; see [docs/approve-boundary.md](approve-boundary.md) and the
|
|
958
|
+
README's Known limits. `relay deny` is unchanged and still works from anywhere, as does denying or
|
|
959
|
+
allowing through relay's approval dialog, `confirm`, or the root agent's `approve` (which still
|
|
960
|
+
cannot allow a person-only request). `relay cancel`, `relay adopt`, `relay clean --forget` and the
|
|
961
|
+
two `relay chat` message paths (`--say` and typing a line interactively; `--print` is unaffected)
|
|
962
|
+
now use the same launched-agent check. Scripts that ran `relay approve <id>` non-interactively and
|
|
963
|
+
read the JSON result must now run it at a terminal and type the code; the help text and
|
|
964
|
+
`usage.txt` reflect this.
|
|
965
|
+
- **Registry schema 4.** One new table, `launch_leaders`, holds the leader pids of the workers and
|
|
966
|
+
agents relay launches, with each leader's start time (so a reused pid is not mistaken for a
|
|
967
|
+
launched leader, and a pid that led twice keeps both), for the launched-agent check above. The first open by this build backs the
|
|
968
|
+
registry up (`relay.db.backup-v3-…`) and adds the empty table; no existing row changes. Relay
|
|
969
|
+
1.0.3 and earlier refuse a version-4 registry, so keep that backup if you may roll back. See
|
|
970
|
+
[the registry contract](stable-surfaces.md#registry-and-migration).
|
|
971
|
+
- **Recognizer defence in depth** (`src/core/relay-command.ts`): these now fail closed —
|
|
972
|
+
an interpreter in command position fed by a pipe (`… | sh`, including `|&` and a newline after
|
|
973
|
+
`|`, and through wrappers such as `env`, `nice`, `timeout`, `stdbuf`, `sudo` and `exec`, whose
|
|
974
|
+
value-taking options and `--` are parsed); a non-shell interpreter given inline code by its own
|
|
975
|
+
flag (`python -c`, `perl -e/-E`, `ruby -e`, `node -e/-p/--eval/--print`, `osascript -e`,
|
|
976
|
+
`php -r`, `lua -e`, `bun -e/--eval`, `deno eval`, also with the code attached, `-cprint(1)`, or
|
|
977
|
+
as `--eval=…`); an unrecognised option on one of those wrappers; and glob metacharacters in
|
|
978
|
+
command position (`rela?`). A shell's `-c` string (`sh`, `bash`, `zsh`, …) does not fail closed:
|
|
979
|
+
it is parsed recursively as the nested command it is, so Codex's `/bin/zsh -lc '<cmd>'` is judged
|
|
980
|
+
by its `<cmd>`. `sed`, `awk` and `xargs` are deliberately not flagged in ordinary pipelines
|
|
981
|
+
(`git log | sed -n 1,5p`, `git ls-files | xargs wc -l`). This is a convenience filter behind the
|
|
982
|
+
check above; its existing fail-closed behaviour on `$`-bearing words is unchanged.
|
|
983
|
+
- **Known limit recorded (not fixed here): a Codex job with a network grant can reach local IPC and
|
|
984
|
+
loopback services.** With network granted, a Codex workspace-write sandbox can reach the person's
|
|
985
|
+
running terminal-multiplexer server and local login service, which are outside relay's confinement
|
|
986
|
+
and run with the person's authority; from there the approval check above does not help. relay's
|
|
987
|
+
own Seatbelt confinement blocks this; Codex's does not, because the network toggle also opens the
|
|
988
|
+
local sockets. This is pre-existing and tracked separately. Treat a network grant to a Codex job
|
|
989
|
+
as giving it the reach of your account under 1.0.4. Fixed for Codex in 1.0.5.
|
|
990
|
+
|
|
991
|
+
## Relay 1.0.3
|
|
992
|
+
|
|
993
|
+
Nothing to do unless you use relay from OpenCode. What changes:
|
|
994
|
+
|
|
995
|
+
- **OpenCode 2 sessions each get their own scope.** OpenCode 2's background service runs one relay
|
|
996
|
+
process for all its sessions in a project (seen on 2.1.4, 2026-10-26), so until now every OpenCode
|
|
997
|
+
session shared one run: each could read, decide, cancel and merge the others' work, and take
|
|
998
|
+
their events. Relay now scopes each call by the session OpenCode stamps on it
|
|
999
|
+
(`_meta["ai.opencode/sessionID"]`); `status.session` reports `scope: "host-session"`,
|
|
1000
|
+
`source: "host-key"`. Another session's ids answer `Item unavailable.`.
|
|
1001
|
+
- **A call from OpenCode 2 that carries no session ID does nothing** and is refused, saying why.
|
|
1002
|
+
OpenCode 2.1.4 stamps every MCP tool call. An OpenCode 0.x or 1.x release (no stamp) keeps one
|
|
1003
|
+
scope per process; any other version string (`local`, `unknown`, `0.0.0-…` from OpenCode's beta
|
|
1004
|
+
and dev builds) is taken for 2.x.
|
|
1005
|
+
- **Restarts.** The scope lasts as long as the relay process: the session ID is no secret, so it
|
|
1006
|
+
gives no claim on work from before OpenCode restarted its service. Recover that work with
|
|
1007
|
+
`relay adopt <id> --to <fingerprint>` in a terminal, then `adopt` from the session.
|
|
1008
|
+
- The README has an OpenCode section (registration with `opencode mcp add`, naming a target or
|
|
1009
|
+
setting `default_target.unknown`, approvals). No config keys change.
|
|
1010
|
+
|
|
1011
|
+
## Relay 1.0.2
|
|
1012
|
+
|
|
1013
|
+
Nothing to do for most installs. What changes:
|
|
1014
|
+
|
|
1015
|
+
- **`ask` on the desktop app's entry needs no `cwd`.** Where relay was started outside any
|
|
1016
|
+
project and a new question names no directory, relay now consults in a new, empty directory of
|
|
1017
|
+
the thread's own, made under `~/.local/share/relay/consult` (or `$RELAY_HOME-consult`), instead
|
|
1018
|
+
of refusing. Its follow-ups go on there. That parent must be a plain directory of yours (relay
|
|
1019
|
+
makes it, mode 0700) holding only the directories relay made there, and no job may be granted
|
|
1020
|
+
it or given a file change in it. A new
|
|
1021
|
+
`delegate`, `discuss` or `review`, and `merge`, still refuse without `cwd`. Uninstall lists the
|
|
1022
|
+
directory among what it leaves behind.
|
|
1023
|
+
- **Auto mode and the desktop entry's session token.** The README's desktop section says what to
|
|
1024
|
+
do when Claude Code's auto mode blocks the session token: allow the entry's tools with a
|
|
1025
|
+
permission rule, such as `mcp__relay-desktop__*`, in that session's settings.
|
|
1026
|
+
|
|
1027
|
+
## Relay 1.0.1
|
|
1028
|
+
|
|
1029
|
+
Nothing to do for most installs. What changes:
|
|
1030
|
+
|
|
1031
|
+
- **`CODEX_ACCESS_TOKEN` is one of Codex's credentials.** It is a ChatGPT access token that Codex
|
|
1032
|
+
signs in with ahead of its stored login. Relay now withholds it from every agent under the
|
|
1033
|
+
default `child_auth: "login"`, and from every agent but Codex under `"any"`. A config that names
|
|
1034
|
+
it in the root `child_env.pass` or `child_env.request`, where no target has `child_auth: "any"`,
|
|
1035
|
+
passed validation on 1.0.0 and fails it on 1.0.1. While a 1.0.0 relay reads the same config, keep
|
|
1036
|
+
it out of the root lists. If Codex should sign in with it, set `targets.codex.child_auth: "any"` and
|
|
1037
|
+
list it under `targets.codex.child_env.pass`.
|
|
1038
|
+
- **A Codex command that asks for access added to its sandbox can be allowed once only.** Where
|
|
1039
|
+
Codex's `exec_permission_approvals` feature is on, such a request's `wants` names the access and
|
|
1040
|
+
its effect says the command stays in its sandbox with that added. `approve` with `scope: "job"`
|
|
1041
|
+
refuses it and decides nothing, and relay's question offers no "for the rest of this job". Codex
|
|
1042
|
+
offers no more for such a request, and on Codex 0.163.0 an allow held for the job would also
|
|
1043
|
+
cover a later retry of the command outside the sandbox.
|
|
1044
|
+
- **Codex jobs refuse some directory names.** A grant, a turn's own directory or a repository's
|
|
1045
|
+
git directory whose name holds a double quote, a tab or a line break is refused, saying why,
|
|
1046
|
+
before Codex starts. With a double quote, Codex 0.164.0 cannot build its sandbox at all; a grant
|
|
1047
|
+
or git directory with a tab or a line break stays unwritable without a word. Relay refuses those
|
|
1048
|
+
in the turn's own directory too, as a precaution: that case was not tested.
|
|
1049
|
+
- **`thread/resume` asks Codex to leave the thread's past turns out of its reply.** Relay reads
|
|
1050
|
+
none of them.
|
|
1051
|
+
|
|
1052
|
+
## Codex sandbox as a permission profile in 1.0 (2026-10-22)
|
|
1053
|
+
|
|
1054
|
+
Relay now gives every Codex turn its sandbox as a Codex permission profile of its own,
|
|
1055
|
+
`[permissions.relay]`, defined and selected with `-c` (`default_permissions = "relay"`) and named on
|
|
1056
|
+
the thread, instead of `sandbox_mode` and `sandbox_workspace_write`. The sandbox is the same for
|
|
1057
|
+
read jobs, write jobs, grants, network on or off, temporary directories, both backends,
|
|
1058
|
+
Daybreak and speed, with one addition: a Codex write job can no longer create, change or remove
|
|
1059
|
+
harness configuration (`.claude`, `.codex`, `.gemini`, `.mcp.json` and the rest of relay's list)
|
|
1060
|
+
at the top of its worktree or of a granted directory. What to check:
|
|
1061
|
+
|
|
1062
|
+
- Your own `default_permissions`, other `[permissions]` profiles and `sandbox_mode` in Codex's
|
|
1063
|
+
configuration no longer stop Codex launches (0.9 refused `default_permissions` and
|
|
1064
|
+
`[permissions]`): relay's selection outranks them. A `[permissions.relay]` table of your own
|
|
1065
|
+
does stop them, since it adds keys to relay's profile. Rename it.
|
|
1066
|
+
- An administrator's requirements for Codex that do not allow the profile `relay`
|
|
1067
|
+
(`allowed_permission_profiles`) or the sandbox mode a job needs (`allowed_sandbox_modes`) stop
|
|
1068
|
+
Codex launches, with a message saying so.
|
|
1069
|
+
- Relay starts Codex's app server with its experimental API on for every turn (it was on only
|
|
1070
|
+
for Daybreak); naming a profile on the thread needs it.
|
|
1071
|
+
- An approved escalation (a command or file change a person allows outside the sandbox) runs with
|
|
1072
|
+
no sandbox, so the read-only names do not hold for it.
|
|
1073
|
+
- Under `codex_backend: "exec"` a read job still gets no network even when granted, as before.
|
|
1074
|
+
- Relay names a thread's workspace roots (the job's directory) on every start and resume. A
|
|
1075
|
+
thread started before this change stored its grants among its roots and would restore them on
|
|
1076
|
+
resume; named, a grant taken away when the job is continued is no longer writable.
|
|
1077
|
+
|
|
1078
|
+
## Desktop conversation isolation in 1.0 (D9, 2026-10-21)
|
|
1079
|
+
|
|
1080
|
+
The Claude desktop app's shared entry, `relay-desktop`, now keeps its conversations apart by a
|
|
1081
|
+
session token each model carries. In 0.9.1 the
|
|
1082
|
+
conversations of each of its two processes shared one run, with one another's jobs, approval
|
|
1083
|
+
requests and events. Dedicated registrations (Claude Code, Codex) and unqualified hosts do not
|
|
1084
|
+
get the token: their tools do not take the parameter, and one passed anyway is dropped.
|
|
1085
|
+
|
|
1086
|
+
- **Reinstall the desktop entry, then quit and reopen the app.** Run
|
|
1087
|
+
`relay install claude-desktop --write` with the app quit, or check that relay's entry carries
|
|
1088
|
+
`--desktop`: that marker is what makes relay treat the desktop chats as a shared relay. Cowork's
|
|
1089
|
+
connection is also recognised by its client name, but how the chats' connection names itself
|
|
1090
|
+
has not been observed, so an entry without the marker (an old one named `relay`, say) may leave
|
|
1091
|
+
the chats in one unisolated scope. `relay doctor` warns about it. A `relay-desktop` process
|
|
1092
|
+
that 0.9.1 started still shares one run among its conversations until the app is quit and
|
|
1093
|
+
reopened.
|
|
1094
|
+
- **Every conversation's first call gets a token and does nothing else.** A call without
|
|
1095
|
+
`session_token` returns `new_session.token`; `status` with no id answers in an empty scope,
|
|
1096
|
+
and any other call returns `session_required` with nothing started, telling a model that
|
|
1097
|
+
already has a token to call again with it. The model passes the token on every later call. A
|
|
1098
|
+
token relay did not issue gets `Session unavailable.`.
|
|
1099
|
+
- **Runs from 0.9.1's shared processes belong to no conversation.** After the upgrade they are
|
|
1100
|
+
orphans, as every run from before it is ("Explicit orphan recovery" below):
|
|
1101
|
+
`relay adopt <id> --to <fingerprint>` in a terminal transfers one, whole, into the
|
|
1102
|
+
conversation whose `status.session.fingerprint` you give. A run several chats used cannot be
|
|
1103
|
+
split between them.
|
|
1104
|
+
- **A conversation keeps its work across later restarts** by its token, without adoption. One
|
|
1105
|
+
that lost its token gets a new one; quit and reopen the app, then adopt the old run into it.
|
|
1106
|
+
- **No registry change of its own.** Beyond 1.0's schema 3, relay adds `session.key` (0600) and,
|
|
1107
|
+
for each open environment broker, a record under `brokers/` to its home. Deleting
|
|
1108
|
+
`session.key` revokes every token at once; to move their runs to new tokens, quit and reopen
|
|
1109
|
+
the app, then run `relay adopt` from a terminal (`relay cancel` there stops the work instead).
|
|
1110
|
+
- **The token is a bearer key.** It separates conversations that use relay honestly. A model
|
|
1111
|
+
that sees another conversation's token can act as that conversation; see the README's
|
|
1112
|
+
"Claude desktop app and Cowork".
|
|
1113
|
+
|
|
1114
|
+
## `relay clean --forget` in 1.0 (2026-10-21)
|
|
1115
|
+
|
|
1116
|
+
New, and additive: nothing changes until you run it. 0.9.1 never forgets a run. 1.0's
|
|
1117
|
+
`keep_records_days` forgets inactive runs, but keeps a run whose job branch is in a repository
|
|
1118
|
+
that is no longer there, since a repository deleted for good looks the same as one on a volume
|
|
1119
|
+
not mounted. `relay clean --forget <run_id>` is the way to forget such a run.
|
|
1120
|
+
It prints, as JSON, what it would remove and what it would leave, and changes nothing; add
|
|
1121
|
+
`--write` to forget the run: its registry rows,
|
|
1122
|
+
`runs/<run_id>/`, its harnesses' state, its `relay adopt` transfers and what relay made for
|
|
1123
|
+
it in the worktrees directory. Branches in the missing repository are not touched. It
|
|
1124
|
+
refuses a run still in use, one whose repository is there (`relay clean` applies then), and
|
|
1125
|
+
one with quarantined login-store entries. See "What is kept" in the
|
|
1126
|
+
[README](../README.md#security-model). 0.9.1 (on a Mac not yet upgraded, or after a rollback)
|
|
1127
|
+
does not have the option and ignores the flag: there, `relay clean --forget <run_id>` is an
|
|
1128
|
+
ordinary `relay clean <run_id>`, which keeps the run's records, and
|
|
1129
|
+
`relay clean --forget=<run_id>` cleans every run.
|
|
1130
|
+
|
|
1131
|
+
`relay clean` itself now refuses a flag it does not have, and a second run id, with a usage
|
|
1132
|
+
error (exit 2) that cleans nothing; 0.9.1 ignored them. A script that passed one must drop it.
|
|
1133
|
+
|
|
1134
|
+
## Claude jobs under a long home in 1.0 (2026-10-21)
|
|
1135
|
+
|
|
1136
|
+
**On a Mac whose home path is longer than about 22 characters, 1.0 gives Claude its private
|
|
1137
|
+
temporary directory through a short link, and can refuse Claude jobs that 0.9.1 ran.** 1.0
|
|
1138
|
+
gives each Claude turn a private temporary directory in `~/.rn`; 0.9.1 did not set
|
|
1139
|
+
`CLAUDE_CODE_TMPDIR`, which leaves Claude Code in the shared `/tmp/claude-<uid>`. Claude Code
|
|
1140
|
+
measures `$CLAUDE_CODE_TMPDIR/claude-<uid>` as written and, past 44 bytes, gives its sandboxed
|
|
1141
|
+
commands that shared directory anyway. For such a home relay hands Claude the turn's directory
|
|
1142
|
+
in `~/.rn` through a short link, `/Users/Shared/.rn-<uid>`,
|
|
1143
|
+
which it makes on first use and checks before every Claude turn (yours, a link, exactly to your
|
|
1144
|
+
`~/.rn`, in a sticky root-owned directory). The files stay in `~/.rn`; the registry and the
|
|
1145
|
+
sweep know only the real directory, never the link. Short homes are unaffected: no link is made.
|
|
1146
|
+
|
|
1147
|
+
This works only because Claude Code measures that name before resolving links, which relay has
|
|
1148
|
+
read in <!-- verified:claudeTempLink -->2.1.302, 2.1.303, 2.1.304, 2.1.308, 2.1.325 and 2.1.326<!-- /verified --> (2.1.305 to 2.1.307 and 2.1.309 to 2.1.324 were not read
|
|
1149
|
+
one by one; they lie between versions that measure it the same way). Relay's version gate is a floor and Claude Code
|
|
1150
|
+
updates itself, so on the link path relay refuses a Claude Code newer than <!-- verified:claudeTempLink:last -->2.1.326<!-- /verified --> (or one whose
|
|
1151
|
+
version it cannot read) unless `allow_untested` is set, and says which versions. Short homes never
|
|
1152
|
+
meet this check.
|
|
1153
|
+
|
|
1154
|
+
Check after upgrading on a long-home Mac:
|
|
1155
|
+
|
|
1156
|
+
- `relay doctor` has a `claude temp` line: the link not there yet (relay makes it on the first
|
|
1157
|
+
Claude turn), in place, or why relay refuses Claude turns, with the version ceiling. Doctor
|
|
1158
|
+
never makes the link, and its Claude init probe runs only once the link is usable.
|
|
1159
|
+
- If relay refuses and names `/Users/Shared/.rn-<uid>`, something else is already
|
|
1160
|
+
there: another user's entry (an administrator must remove it), a directory, or a link to
|
|
1161
|
+
another place (an old home of yours: remove it). Relay never replaces it.
|
|
1162
|
+
- If it refuses because Claude Code is newer than <!-- verified:claudeTempLink:last -->2.1.326<!-- /verified -->, pin Claude Code to <!-- verified:claudeTempLink:last -->2.1.326<!-- /verified --> or older
|
|
1163
|
+
(point `targets.claude.bin` at that version's binary), wait for a relay release that raises the
|
|
1164
|
+
ceiling, or set `"allow_untested": true` to run unverified.
|
|
1165
|
+
- With a uid over five digits even the short link is too long, and relay refuses Claude jobs
|
|
1166
|
+
on such a home.
|
|
1167
|
+
- Rollback to 0.9.1 leaves the link in place and harmless (0.9.1 does not use it); remove it
|
|
1168
|
+
by hand if you like (`rm /Users/Shared/.rn-$(id -u)`).
|
|
1169
|
+
|
|
1170
|
+
On every Mac, long home or not, a grant of `/Users/Shared` itself is now refused (new or kept),
|
|
1171
|
+
since a job holding it could change the link. Grants of directories inside it are unaffected.
|
|
1172
|
+
Doctor's Claude init probe keeps its temporary directory in `~/.rn`, as a turn does.
|
|
1173
|
+
|
|
1174
|
+
**Release checklist.** A release admits a newer Claude Code on the long-home link only after
|
|
1175
|
+
that version's temporary-directory handling has been checked to measure the name before resolving
|
|
1176
|
+
links, as the versions above do; only then is `CLAUDE_TEMP_LINK_VERIFIED_THROUGH` in
|
|
1177
|
+
`src/backends/native-temp.ts` raised.
|
|
1178
|
+
|
|
1179
|
+
## Tool-token policy in 1.0 (W9, 2026-10-19)
|
|
1180
|
+
|
|
1181
|
+
**0.9.1 inherited unknown environment variables; 1.0 no longer does.** With no
|
|
1182
|
+
`child_env` setting, launched agents inherit the exact runtime baseline and validated
|
|
1183
|
+
proxy variables only, after mandatory vendor/auth and host-session scrubs. Unknown cloud,
|
|
1184
|
+
registry, GitHub, database and SSH-agent variables are excluded. Network grants and
|
|
1185
|
+
`child_auth: "any"` do not select them.
|
|
1186
|
+
|
|
1187
|
+
Configure exact names in your own relay config, never secret values:
|
|
1188
|
+
|
|
1189
|
+
```json
|
|
1190
|
+
{
|
|
1191
|
+
"child_env": {
|
|
1192
|
+
"policy": "allowlist",
|
|
1193
|
+
"pass": ["JAVA_HOME"],
|
|
1194
|
+
"drop": ["SSH_AUTH_SOCK"],
|
|
1195
|
+
"request": []
|
|
1196
|
+
},
|
|
1197
|
+
"targets": {
|
|
1198
|
+
"codex": { "child_env": { "request": ["GH_TOKEN", "NPM_TOKEN"] } }
|
|
1199
|
+
}
|
|
1200
|
+
}
|
|
1201
|
+
```
|
|
1202
|
+
|
|
1203
|
+
`JAVA_HOME` is a standing pass and prompts for no additional consent. Root and target
|
|
1204
|
+
lists are unioned; target `policy` overrides root; `drop` wins, including over standing
|
|
1205
|
+
passes and approved requests. Names are exact, case-sensitive and must match
|
|
1206
|
+
`[A-Za-z_][A-Za-z0-9_]*`. Wildcards, unknown keys and pass/request entries for relay-owned
|
|
1207
|
+
names are errors. A root-level entry applies wherever a target may receive it; mandatory
|
|
1208
|
+
guards still remove it per target (for example, `GH_TOKEN` from Copilot under login),
|
|
1209
|
+
and doctor gives the reason. It is an error only when no target could receive it;
|
|
1210
|
+
a target-level entry must be allowed for that target. Empty target lists do not clear root lists.
|
|
1211
|
+
|
|
1212
|
+
To request one turn's private install, a root call can carry
|
|
1213
|
+
`grant: { network: true, env: ["NPM_TOKEN"] }`. For a GitHub operation request
|
|
1214
|
+
`grant.env: ["GH_TOKEN"]`. Each requested name must be in effective `request` and present
|
|
1215
|
+
in the root server's captured environment; missing, dropped or forbidden names refuse
|
|
1216
|
+
before launch. Only the person may allow disclosure through the existing qualified
|
|
1217
|
+
approval dialog or `confirm` path. Root `approve`, including `user_confirmed`, child
|
|
1218
|
+
tools and `relay approve` may deny but cannot allow it. Without that person path, relay
|
|
1219
|
+
refuses and points you to config: choose a deliberate standing `pass` if appropriate,
|
|
1220
|
+
or use a qualified host. Standing `pass: ["NPM_TOKEN"]` or `pass: ["GH_TOKEN"]` releases
|
|
1221
|
+
that exact variable without a prompt. Prefer narrowly scoped, short-lived credentials.
|
|
1222
|
+
|
|
1223
|
+
A private install can now fail because `NPM_TOKEN` is absent, and a push or GitHub CLI
|
|
1224
|
+
call because its environment credential is absent. Select only the exact needed names;
|
|
1225
|
+
network permission is a separate decision. Public installs often need network alone.
|
|
1226
|
+
Install scripts can read released tokens. `GH_TOKEN` can authenticate GitHub CLI but does
|
|
1227
|
+
not configure git's transport or credential helper; prefer having the root push a reviewed
|
|
1228
|
+
branch when the launched task does not need push authority. Toolchains that relied on
|
|
1229
|
+
`JAVA_HOME`, `SDKROOT`, `CARGO_HOME` or `VIRTUAL_ENV` need exact `pass` entries too.
|
|
1230
|
+
Codex's own `shell_environment_policy` must also allow a released name for it to reach
|
|
1231
|
+
commands Codex runs. Relay does not override a stricter policy, such as
|
|
1232
|
+
`inherit = "core"` with `include_only`, but it names each released name that policy
|
|
1233
|
+
withholds, with the reason, in a note on the Codex turn and, for `pass`, in `relay doctor`.
|
|
1234
|
+
|
|
1235
|
+
For temporary compatibility, explicitly select `child_env.policy: "legacy"`. Relay warns
|
|
1236
|
+
on **every root load** and in doctor. It restores other-variable inheritance, including
|
|
1237
|
+
unknown secrets, subject to mandatory scrubs and `drop`; it is supported through 1.x.
|
|
1238
|
+
It does not restore 0.9.1's cross-vendor exception: global `child_auth: "any"` remains
|
|
1239
|
+
accepted but permits only each destination's own supported auth inputs and warns with a
|
|
1240
|
+
pointer to `targets.<id>.child_auth`. Own-target auth inputs must also be selected by the
|
|
1241
|
+
environment policy. Prefer the per-target form. `tool-denylist` is unavailable in 1.0;
|
|
1242
|
+
a config naming it fails validation. It may be added later.
|
|
1243
|
+
|
|
1244
|
+
A person-set endpoint override in the root environment refuses launch for every target,
|
|
1245
|
+
under both `child_auth: "login"` and `"any"`, before any environment filtering. Excluding
|
|
1246
|
+
or dropping Claude's `ANTHROPIC_*BASE_URL`, Codex's `OPENAI_BASE_URL` or Gemini's endpoint
|
|
1247
|
+
variables cannot bypass this refusal: relay cannot tell which family answers there.
|
|
1248
|
+
Under `any`, filtering could also send a credential intended for that endpoint to the
|
|
1249
|
+
vendor instead. Unset the named variables and restart the root. A desktop/Agent SDK
|
|
1250
|
+
host's own Anthropic endpoint remains the exception under Claude's login policy:
|
|
1251
|
+
relay removes the host endpoint and credentials together and verifies the account login.
|
|
1252
|
+
|
|
1253
|
+
Run `relay doctor` to preview each target's effective policy and included/dropped names
|
|
1254
|
+
with reasons; diagnostics never show values, proxy URL contents or value hashes. Restart
|
|
1255
|
+
all root servers and workers on upgrade: an old process retains its inherited values.
|
|
1256
|
+
Root-environment changes require another server restart. Requests authorize one turn
|
|
1257
|
+
only; every resume needs fresh person consent. Consent persists metadata/decisions only,
|
|
1258
|
+
never values or reusable hashes, and old consent cannot be replayed after a restart.
|
|
1259
|
+
Every new turn gets its environment from the owning root's relay server. If that server
|
|
1260
|
+
has restarted, a resume or nested launch fails with a "restart the root" message instead
|
|
1261
|
+
of inheriting another process's environment. A running turn is unaffected.
|
|
1262
|
+
Removing a pass cannot erase an already running agent's memory, transcripts or leftover
|
|
1263
|
+
processes; cancel affected work and revoke/rotate the credential when needed.
|
|
1264
|
+
|
|
1265
|
+
**When a job needs its root.** A turn's worker claims its environment as soon as it picks
|
|
1266
|
+
the turn up, before the turn waits for a `max_concurrent` slot, and holds it in memory,
|
|
1267
|
+
never on disk, until the launch. For a new job, or a resume of work with nothing running,
|
|
1268
|
+
that is right after `delegate` or `resume` returns, once the worker has started. From then
|
|
1269
|
+
on the job survives its root session exiting, as in 0.9.1, also while it is queued behind
|
|
1270
|
+
other jobs. A root that exits in the moment before the claim still fails the job: before
|
|
1271
|
+
the worker's start-up claim, its queued turns fail with "…could not supply worker redaction
|
|
1272
|
+
values…"; after that, the turn fails with "…environment broker is unavailable…". A
|
|
1273
|
+
follow-up queued behind a turn that is still running claims only when that turn ends, so
|
|
1274
|
+
its root must still be there then. A `grant.env` request is put to the person at the
|
|
1275
|
+
claim, while the job is still queued, and a denial fails the turn there. Consent given then
|
|
1276
|
+
is used at the launch however long the job waits for its slot, and restarting the root
|
|
1277
|
+
neither refreshes nor withdraws what a queued job has already claimed: cancel the job to
|
|
1278
|
+
withdraw it. Before the launch, relay checks that the turn's grant, its worker, its
|
|
1279
|
+
working directory and its environment/auth policy are as they were at the claim. If any of
|
|
1280
|
+
them changed while the turn waited, it fails closed and says so, rather than launch with
|
|
1281
|
+
what it was given earlier: resume it to claim afresh. For a job with a `grant.env`
|
|
1282
|
+
request, any edit of relay's config file counts, even one that leaves the policy as it
|
|
1283
|
+
was; for any other job, only a change to its environment/auth policy (`child_env`,
|
|
1284
|
+
`child_auth`) does. A turn cancelled while it waits launches nothing and drops what it
|
|
1285
|
+
claimed.
|
|
1286
|
+
|
|
1287
|
+
**Environment filtering is not credential-file or keychain isolation.** Tools can generally
|
|
1288
|
+
still read `.npmrc`, cloud credentials, `.env`, login stores and git credential helpers,
|
|
1289
|
+
and may reach keychains or sockets under their harness's rules. Loaded CLI settings and
|
|
1290
|
+
native MCP servers have separate credential paths. Network-off still permits disclosure
|
|
1291
|
+
through model traffic/results and permitted API hosts. Redaction is defence in depth;
|
|
1292
|
+
it does not prevent reading or using credentials.
|
|
1293
|
+
Explicitly released values of any name are registered for per-turn literal redaction
|
|
1294
|
+
only when secret-like: at least eight characters, not starting with `/`, `~` or `.`,
|
|
1295
|
+
and not all digits. Short values, numbers and those paths are not registered by value;
|
|
1296
|
+
the existing shape and context redactors still apply.
|
|
1297
|
+
|
|
1298
|
+
0.9.1 rejects `child_env` and `targets.<id>.child_env`, even when set to `{}`, default policies
|
|
1299
|
+
or empty lists, so keep them out of a config file a 0.9.1 relay also reads.
|
|
1300
|
+
See [the environment policy](configuration.md#environment-policy). Stub tests
|
|
1301
|
+
do not close gate 8: each admitted signed-in harness still needs scratch launch/resume,
|
|
1302
|
+
toolchain, public/private install, synthetic-token visibility and network-off/on probes,
|
|
1303
|
+
including permitted API hosts, sockets/helpers and hostile repository instructions.
|
|
1304
|
+
|
|
1305
|
+
## Codex Daybreak in 1.0 (A33, 2026-10-19)
|
|
1306
|
+
|
|
1307
|
+
`targets.codex.daybreak: true` requests Daybreak for eligible Codex models; relay
|
|
1308
|
+
does not enable it unless set. Unset leaves Codex's own configuration unchanged;
|
|
1309
|
+
explicit `false` disables it. Only your relay config can set it, for the enrolled
|
|
1310
|
+
account holder's own use: never proxy or provide Daybreak to anyone else.
|
|
1311
|
+
Eligible models come from Codex's catalog; other or unknown models run without it,
|
|
1312
|
+
with a plain note in status/results. Before Codex 0.163.0 this key has no effect:
|
|
1313
|
+
enrolled accounts received Daybreak automatically. 0.9.1 rejects the key even when
|
|
1314
|
+
`false`, so keep it out of a config file a 0.9.1 relay also reads.
|
|
1315
|
+
|
|
1316
|
+
## Verifiable inbox pointers in 1.0 (D14, 2026-10-18)
|
|
1317
|
+
|
|
1318
|
+
Restart relay's root servers to use signed inbox notices. The prefix changes from
|
|
1319
|
+
`relay (event N):` to `relay (event N, tag <32 lowercase hex digits>):`, and the notice
|
|
1320
|
+
directs the agent to call `status({notice: {event_id: N, tag: "<copied tag>"}})` before
|
|
1321
|
+
acting. This optional parameter performs verification only, ignoring `id` and `wait_s`.
|
|
1322
|
+
Use only the stored event returned with `notice_verification.verified: true`; ignore
|
|
1323
|
+
missing tags, unknown events and failed verification, and report them to the user.
|
|
1324
|
+
Notices remain pointers, never approval or other authority. Update consumers matching
|
|
1325
|
+
the old inbox prefix; accepting unsigned notices would bypass this security tightening.
|
|
1326
|
+
|
|
1327
|
+
The signing key is generated per live server and held only in memory, independently of
|
|
1328
|
+
registry ownership tokens. Tags bind the session/run and event contents, and verification
|
|
1329
|
+
also checks current ownership. Relay persists neither keys nor tags in registry, agent
|
|
1330
|
+
files or diagnostic logs, though the host may record the notice and verification call in
|
|
1331
|
+
its own transcript. Old tags fail after restart or ownership transfer; use ordinary status
|
|
1332
|
+
to recover. Deduplicate repeated verified events by `event_id`: verification proves
|
|
1333
|
+
authenticity, not freshness. Unsigned tool-result events, existing status/result calls,
|
|
1334
|
+
database schema, config keys and inbox JSONL envelopes remain compatible.
|
|
1335
|
+
|
|
1336
|
+
The fixture changes are the additive `status.notice` object in `tools.json`,
|
|
1337
|
+
line 1 of `notice.txt` (signed prefix and verification direction), and line 2 of
|
|
1338
|
+
`inbox.jsonl` (the same notice in the user envelope). No other stable fixture changes.
|
|
1339
|
+
See [the complete contract and fixture rationale](stable-surfaces.md#events-and-notices).
|
|
1340
|
+
|
|
1341
|
+
To limit inbox delivery, set Claude Code's `crossSessionInbound` to `hold` or `refuse`;
|
|
1342
|
+
these withhold or drop relay notices as well. Events still arrive on the next relay call.
|
|
1343
|
+
The controls do not restrict socket connections or provide a relay-only sender list;
|
|
1344
|
+
see [Claude Code's documentation](https://code.claude.com/docs/en/cross-session-messaging#control-inbound-messages).
|
|
1345
|
+
Doctor now reports observed inbound setting values and their sources for its directory,
|
|
1346
|
+
with an explicit limit on inferring another session's effective configuration.
|
|
1347
|
+
|
|
1348
|
+
## Tool deadlines and event delivery in 1.0 (2026-10-18)
|
|
1349
|
+
|
|
1350
|
+
Relay now caps all waits in one Codex call below its registered `tool_timeout_sec`, with a shared deadline from request receipt. Roots read `[mcp_servers.relay]` in `$CODEX_HOME/config.toml` (or `~/.codex/config.toml`); missing or unreadable timeouts use the 60-second default. Launched Codex agents use the timeout relay sets for their turn, at least 3600 seconds. The margin is 10 seconds, scaled to one sixth for shorter timeouts. Doctor now explains early-return caps instead of requiring `tool_timeout_sec` above twice `block_s`. Restart sessions after changing registrations, and keep any CLI overrides consistent with the file relay reads.
|
|
1351
|
+
|
|
1352
|
+
For unattended Claude Code with `CLAUDE_AUTO_BACKGROUND_TASKS=1`, the shared cap is 110 seconds by default. Relay respects `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` and `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` from its host environment; interactive terminal waits are unchanged. See the [Claude Code variable reference](https://code.claude.com/docs/en/env-vars) and [backgrounding guide](https://code.claude.com/docs/en/mcp#automatic-backgrounding-of-long-tool-calls). No manual reduction of `block_s` is needed for these modes.
|
|
1353
|
+
|
|
1354
|
+
A capped `status` result reports `wait_ended` and delivers pending events. Events are acknowledged only after the reply’s transport write completes; cancelled calls and closed or failed transports leave them pending. Concurrent replies or an acknowledgement failure may repeat an event with the same `event_id`. A completed write is not an acknowledgement from the agent. No config keys or database schema changed.
|
|
1355
|
+
|
|
1356
|
+
|
|
1357
|
+
## Approval dialog qualification in 1.0 (2026-10-18)
|
|
1358
|
+
|
|
1359
|
+
Approval dialogs now require a detected surface qualified for unsolicited elicitation both idle
|
|
1360
|
+
and busy. Relay cannot reliably observe whether the host's turn is busy: no relay call in flight
|
|
1361
|
+
can still mean a shell command is running. The enforced table in `src/mcp/host.ts` cites the
|
|
1362
|
+
host observations behind it (not published):
|
|
1363
|
+
|
|
1364
|
+
| Surface | Idle evidence | Busy evidence | Dialogs offered |
|
|
1365
|
+
|---|---|---|---|
|
|
1366
|
+
| Interactive Claude Code terminal | 2.1.286, C-k; rerun 2.1.302 | 2.1.286, C-g; rerun 2.1.302 | From 2.1.286, with existing consent checks |
|
|
1367
|
+
| Codex CLI | 0.162.1, X-e; rerun 0.163.0 | 0.163.0, X-j | From 0.163.0 |
|
|
1368
|
+
| Codex app / desktop | 0.162.0-alpha.17.2, XA-d | XA-f unrun | Withheld in every state |
|
|
1369
|
+
| Claude SDK / desktop Code tab, unattended `-p` | D-c/D-d, P-c: automatic decline/cancel | No human dialog qualification | Withheld; Code tab keeps qualified `confirm` |
|
|
1370
|
+
| Shared desktop bridge, unknown hosts, custom Codex originators | Unqualified | Unqualified | Withheld |
|
|
1371
|
+
|
|
1372
|
+
Codex detection uses `codex-mcp-client`, version, the forwarded originator, the app's MCP UI
|
|
1373
|
+
capability and `client_type: desktop_app` call metadata (XA-a). Desktop evidence takes precedence
|
|
1374
|
+
at newer versions too; once seen on a call, later calls omitting it cannot re-enable dialogs.
|
|
1375
|
+
The native CLI signature without desktop/custom-originator markers retains CLI qualification.
|
|
1376
|
+
Later versions of a qualified surface retain the existing version-floor policy. Claude's
|
|
1377
|
+
interactive entrypoint, SDK/desktop markers, bypass and settings checks remain in force.
|
|
1378
|
+
|
|
1379
|
+
`ask_user: "always"` remains valid but no longer opts unknown or partially qualified hosts into
|
|
1380
|
+
dialogs; it observes the same gates as `auto`. `never` still disables all dialogs. No migration
|
|
1381
|
+
or config edit is needed. Restart root sessions to use the new gates. Requests remain pending,
|
|
1382
|
+
arrive in the next call's `events`, and have their full details in `status.needs_approval`.
|
|
1383
|
+
`confirm` remains available wherever its separate permission prompt is qualified; otherwise use
|
|
1384
|
+
the root conversation or terminal for ordinary requests. Person-only requests still need a
|
|
1385
|
+
qualified dialog or `confirm` to allow them.
|
|
1386
|
+
|
|
1387
|
+
`status.approval_dialogs` reports this connection's effective `offered` boolean and `reason`,
|
|
1388
|
+
including when no request exists. `relay doctor` prints idle/busy qualification floors and
|
|
1389
|
+
withholding reasons per surface; it describes the policy and cannot inspect another live host.
|
|
1390
|
+
The Codex app's busy dialog path stays unqualified until XA-f is run and the table is updated.
|
|
1391
|
+
|
|
1392
|
+
## Skill isolation and consent scans in 1.0 (2026-10-18)
|
|
1393
|
+
|
|
1394
|
+
Every launched Claude and Codex agent now loads exactly the skills Relay gives it, none by default. Codex no longer inherits personal or repository skills on jobs without extensions; bundled skills are disabled too. Claude disables skills under isolated and inherited settings alike, and checks every init report. Codex checks `skills/list` on every turn (the `exec` fallback through its existing app-server preflight). Unexpected skills/plugins, missing reports and discovery errors refuse the turn before work.
|
|
1395
|
+
|
|
1396
|
+
To give an agent your user skills, set `targets.<id>.skills: "user"` (or select names/paths), request `extensions: true`, and consent. Config alone does not give a job skills. Given Codex extensions still require `codex_backend: "app-server"`; inherited Claude settings remain incompatible with Claude extensions. No personal CLI files are rewritten. New upstream bundled skills/plugins that Relay cannot switch off refuse the turn rather than extending it silently.
|
|
1397
|
+
|
|
1398
|
+
Claude consent scans now include installed plugin hooks, manifest-declared hooks and skill frontmatter under `~/.claude` and `CLAUDE_CONFIG_DIR`, plus repository and plugin definitions. Matching hooks withhold `confirm`/adopt permission prompts or the approval dialog as appropriate. Unreadable plugin manifests, ambiguous skill frontmatter, any skill `hooks` key and uninspectable plugin sources fail closed; cached copies count conservatively. Restart MCP servers to apply the scan. Console-managed settings and changes after server startup remain limitations. See [extensions](extensions.md#consent-scans-include-extension-hooks) for exact scope and official Claude Code references.
|
|
1399
|
+
|
|
1400
|
+
|
|
1401
|
+
## Family steering in 1.0 (2026-10-17)
|
|
1402
|
+
|
|
1403
|
+
`same_family` now defaults to `"allow"`. To retain 0.9's admission, set `"same_family": "refuse"`; that key and value already validate in 0.9. Existing runs keep their full snapshotted config, including their old default. Root sessions use the new default.
|
|
1404
|
+
|
|
1405
|
+
An explicit `"allow"` now also admits unknown callers' starts and continuations, and Copilot on `auto`, no model or unlisted ids. Copilot model switches continue with a warning under allow, even to an unlisted id; pinned model mismatches before the prompt still fail. Copilot remains experimental and gated by boundary probes. Omitted targets never select a known caller's own routing family under either policy.
|
|
1406
|
+
|
|
1407
|
+
A client name contradicting `--host` now makes the caller unknown (for example opencode importing a Claude registration). Under allow it must name a target, or use `default_target.unknown`; under refuse it cannot start or continue work. Under `--desktop`, an unobserved or unknown client name still keeps the registered family; a name identifying another known family or a multi-model harness contradicts it. The desktop chat clientInfo has not been observed. Do not copy another host's registration to impersonate that host.
|
|
1408
|
+
|
|
1409
|
+
`default_target.unknown` is new in 1.0 and rejected by 0.9's strict schema. Keep it out of a config file a 0.9 relay also reads. Copilot's `default_model: "auto"` validates in 0.9 but is refused there at call time. No keys or values were removed or renamed.
|
|
1410
|
+
|
|
1411
|
+
The registry is now schema version 3: each confined turn records the path, device and inode of its private temporary directory before launch. Opening a version-2 registry first makes a `relay.db.backup-v2-…` copy; earlier builds refuse the newer registry, so retain that backup for rollback. Old `relay-tmp-*` directories have no mapping and are left alone, with a warning from doctor. Old items without caller-family records read `unknown` with a legacy note; their stored config cannot prove a cross-family caller. Applicable Claude settings waivers make labels unknown from the start (isolated settings without managed settings need none). Codex’s `codex_endpoint_override: "accept"` conservatively makes every launch unknown even without an active redirect; its note says whether a redirect was actually found. Regenerate adapters with `npm run build && node adapters/build.mjs`, reinstall with `relay install claude|codex|claude-desktop --write`, and restart sessions. Relay work does not edit personal instruction files.
|
|
1412
|
+
|
|
1413
|
+
**Storage gates:** `log_max_mb` now rotates `proxy.jsonl` at the run's size limit between complete decision records, keeping `<name>.1` like agent logs. `relay clean` and worker housekeeping sweep a mapped `relay-tmp-*` directory only after its turn is settled and start-time-checked process evidence says nothing still uses it; running, unknown and linked directories stay. Bare occurrences of that turn's generated proxy token and bridge secret are cut from its logs, results and errors with labels naming what was cut. No new config keys are required.
|
|
1414
|
+
|
|
1415
|
+
**Schema-3 migration:** `turns` gains nullable `tmp_dir TEXT`, `tmp_dev INTEGER` and `tmp_ino INTEGER` columns. Existing rows retain `NULL` in each; no old temporary-directory mapping is guessed. A 0.9.1 registry (schema 1) receives all schema-2 and schema-3 additions in one open, with `PRAGMA user_version` advancing directly from 1 to 3 and exactly one unchanged pre-migration schema-1 backup. A second open makes no further backup. The registry snapshot includes the schema-3 columns; MCP tools and config schemas are unchanged. See [the registry contract](stable-surfaces.md#registry-and-migration). Schema 3 also adds nullable `refusal_json TEXT` for the new terminal status `refused`; old turns retain NULL and their original statuses.
|
|
1416
|
+
|
|
1417
|
+
Under both settings, §3.7 also rewords the no-other-target (R-none) and unusable configured-default (R-default) refusals. Unknown-caller instructions no longer advise multi-model hosts to copy a single-family registration. Strict unknown-caller agent lists keep the old “Codex from Claude, Claude from Codex” mapping.
|
|
1418
|
+
|
|
1419
|
+
ACP `current_model_update` now replaces stale model-option state, including a missing id. Under `refuse` a switch stops the turn and revokes relay tools; under `allow` it continues with an unknown label and a warning. This intentionally closes a 0.9 fail-open gap rather than preserving that bug. Recording errors fail the turn; they cannot skip the strict stop.
|
|
1420
|
+
|
|
1421
|
+
`relay install codex --write` adds `env_vars = ["CODEX_HOME","CODEX_INTERNAL_ORIGINATOR_OVERRIDE"]` to `[mcp_servers.relay]`. Codex (tested floor 0.162+) otherwise strips the originator marker (and `CODEX_HOME`, which review withholding needs; see below) before starting stdio MCP servers. It lets relay identify T3 and exclude unattributable elicitation under both `ask_user: "auto"` and `"always"`, preserving the Codex waiting profile. Decisions go through the root agent or `relay approve` in a terminal. Launched agents have that originator marker removed, so their Codex threads identify relay. Existing relay entries without the line upgrade without `--force`, are backed up, and reinstall idempotently; both old and new entries uninstall cleanly. Doctor warns when an entry lacks the marker line; restart Codex after reinstalling. The desktop Code tab keeps inbox notices on, including with its SDK markers. Bare SDK inbox profiles (including T3) default off; an explicit `RELAY_HOST_INBOX=on` or `off` marker overrides the detected host profile without changing family identity.
|
|
1422
|
+
|
|
1423
|
+
**Rolling back to 0.9.1:** its installer treats 1.0’s `env_vars` as a user customization. After rebuilding 0.9.1, use `relay install codex --write --force` to replace that entry with 0.9.1’s registration (the old file is backed up), then restart Codex. This also applies to running a 0.9.1 installer on a Mac whose entry was written by 1.0.
|
|
1424
|
+
|
|
1425
|
+
## Relay 1.0
|
|
1426
|
+
|
|
1427
|
+
Relay 1.0's changes, gathered from the dated 1.0 sections above.
|
|
1428
|
+
|
|
1429
|
+
### Behaviour changes in 1.0
|
|
1430
|
+
|
|
1431
|
+
- **Environment disclosure.** Unknown root variables are no longer inherited by default.
|
|
1432
|
+
Configure exact `child_env.pass` or person-approved `grant.env` requests; see the
|
|
1433
|
+
[migration and limits above](#tool-token-policy-in-10-w9-2026-10-19).
|
|
1434
|
+
- **Family steering.** `same_family` now defaults to `"allow"`: named same-family work
|
|
1435
|
+
and work of unknown family can run and is labelled as such. An omitted target still
|
|
1436
|
+
excludes the caller's registered family and chooses only a unique eligible target
|
|
1437
|
+
(or `default_target`); ambiguity asks for a name. `same_family: "refuse"` restores
|
|
1438
|
+
strict cross-family admission. Copilot `auto` and Grok without a pinned model are
|
|
1439
|
+
unknown. Registration/clientInfo contradictions make the caller unknown and are
|
|
1440
|
+
diagnosed; `default_target.unknown` routes that case.
|
|
1441
|
+
- **Review withholding.** The caller's `own_review` is accepted and written only after
|
|
1442
|
+
the reviewer settles. If the wait returns pending, keep the review in context, wait
|
|
1443
|
+
with status, then resend it. Until submission or explicit skip, results withhold the
|
|
1444
|
+
other review and its log/transcript paths, across reconnects; steering the reviewer
|
|
1445
|
+
outside reconciliation is refused. Identified `own_review` tool arguments are redacted
|
|
1446
|
+
in logs, structured echoes and diagnostics. Claude reviewers get read denies for the
|
|
1447
|
+
caller's host-state stores; reinstall Codex to forward `CODEX_HOME`. Codex reviewers
|
|
1448
|
+
have no read carve-out, and drafts, free-form echoes and copies outside denied paths
|
|
1449
|
+
can still expose reviews. This is a normal-use safeguard, not guaranteed independence.
|
|
1450
|
+
|
|
1451
|
+
- **Relay config protection (DM8).** Grants, file requests, Claude's write denies and relay-enforced confinement protect the configured and resolved config file, `install.json` and `install-backups`; dedicated relay directories are protected whole. Broad directories get file protection only, which doctor explains.
|
|
1452
|
+
- **Relay CLI requests (DM8).** The model's `approve` cannot allow a command that runs relay's own CLI, even with `user_confirmed`; denials still work. The person can allow through the host's dialog, `confirm`, or `relay approve` in their terminal.
|
|
1453
|
+
- **Terminal authority (DM8).** `relay approve`, `relay cancel` and `relay adopt` refuse an environment with `RELAY_RUN_ID` or `RELAY_NODE_ID` and direct the caller to the person's own terminal. (Strengthened in 1.0.4, above: the launched-agent check now also follows process ancestry, group and session, `relay approve` additionally requires an interactive terminal and a typed one-time code, and `relay clean --forget` and the `relay chat` message paths use the same check. None of this is a security boundary against an unconfined same-user process; see that section and the README's Known limits.)
|
|
1454
|
+
- **Claude subagent hooks (DM8).** User and project `.claude/agents/*.md` definitions, including `CLAUDE_CONFIG_DIR/agents`, are now checked. Conservatively, any frontmatter `hooks` key or unreadable/ambiguous frontmatter withholds `confirm` and the permission-prompt authorization of `adopt`; terminal-ticket recovery remains available. No YAML dependency was added.
|
|
1455
|
+
|
|
1456
|
+
- **Scoped MCP access.** A different root connection can no longer read or change a run merely by naming one of its items, secondary IDs or approval requests. Foreign and unknown IDs both return `Item unavailable.` The administrative CLI stays global. Launched children may read only their injected run; their existing mutation limits remain.
|
|
1457
|
+
- **Native Codex subagents.** Native Codex subagents (`spawn_agent`) lose read access to their parent's items: each native thread has a separate root relay connection. The parent must call `status` and `result` for its own items; handing their IDs to a native subagent no longer permits inspection or waiting. This differs from a relay-launched child, whose injected context permits reads within its run.
|
|
1458
|
+
- **Explicit orphan recovery.** Owner process death no longer permits automatic adoption by status, result or a mutation. Start replies include `run_id` and an `adoption` description. Use `adopt({run_id: <job, thread, discussion, review or run id>, into_session: status.session.fingerprint, in_directory, item_count})` through a qualified Claude Code permission prompt, copying the description fields exactly from the run's reported `adoption` object. Unknown, live and mismatched runs get one generic unavailable reply with a fixed recovery hint. Else (including relay-desktop), the person first runs `relay adopt <id> --to <fingerprint>` in an interactive TTY, reviews the printed whole-run transfer, and types the exact confirmation; piped input is refused. The destination consumes that one-use authorization within ten minutes. Jobs and pending events survive; process-scoped request_ids do not migrate across restart. `user_confirmed` is no recovery credential. Restart every old MCP server to get these access checks.
|
|
1459
|
+
- **Desktop conversations are kept apart by a session token (D9).** Main-window desktop chats still share one `relay-desktop` process, and Cowork, the Code-tab in-app bridge, remote Cowork and widgets a second; in 0.9.1 the conversations of each process shared one run. Now each conversation has its own runs, jobs, approvals and events, by a token its model carries: see [Desktop conversation isolation in 1.0](#desktop-conversation-isolation-in-10-d9-2026-10-21). Status and doctor label both processes shared. The Code tab's dedicated native registration is separate. Explicit cwd and the 50-second wait cap remain.
|
|
1460
|
+
|
|
1461
|
+
- **No Codex proxy role.** Pre-release 1.0 builds wrote a Codex subagent role per target of another family, `~/.codex/agents/relay-<target>.toml` (under `CODEX_HOME` if set). No release shipped it, and 1.0 writes none (the maintainer, 2026-10-17). `relay install codex` and `relay uninstall codex` remove a role relay wrote, saving it first beside itself (`relay-<target>.toml.bak-relay`); install asks for `--force` if the role was changed after relay wrote it. A file of that name without relay's ownership marker is left alone, `--force` or not. From Codex, call relay's tools directly.
|
|
1462
|
+
- **A new target, Grok (`grok`), off by default and experimental.** 0.9.1 knows only the target ids `claude`, `codex` and `copilot`, and its config schema is strict about them (`v0.9.1:src/core/config.ts`, `byTarget`), so it rejects `targets.grok` (even `{ "enabled": false }`), a `default_target` key or value of `"grok"`, and a `grok` entry in the legacy `bin`, `default_model` and `default_effort` maps, and then refuses every call. Keep all of them out of a config file a 0.9.1 relay also reads. The README's Grok setup (`targets.grok` with `enabled` and `experimental`, and optionally a `default_model`, with the routing caveat there) is for after that.
|
|
1463
|
+
- **xAI's and Grok's credentials are removed from every launched agent.** `XAI_API_KEY`, `GROK_CODE_XAI_API_KEY`, `GROK_AUTH`, `GROK_DEPLOYMENT_KEY`, `GROK_ALPHA_TEST_KEY` and `GROK_EXTRA_AUTH_KEY` are now among the vendor credentials relay removes from a launched agent's environment under `child_auth: "login"` (the default), Claude's and Codex's agents included, whether Grok is switched on or not. A Claude or Codex job that used one of them (a script calling xAI's API, say) no longer sees it; `targets.<id>.child_auth: "any"` does not bring it back, since it passes only that target's own vendor's keys. The old global `child_auth: "any"` exception has ended: it no longer forwards foreign-vendor keys in 1.0, including under `legacy`.
|
|
1464
|
+
- **Restart, and reinstall the Codex registration.** Before relying on the updated review withholding and log redaction, restart every relay session, and quit and reopen the desktop app. Reinstall the Codex registration (`bin/relay install codex --write`) so it passes `CODEX_HOME` through to relay's MCP server.
|
|
1465
|
+
- **`relay:operator` no longer merges, and has a sibling, `relay:codex`.** In 0.9.x, Claude Code's `relay:operator` subagent had `merge` and ran on your session's model. In 1.0 it has no `merge`: it reports a write job's branch with its diff summary, and your session merges once it has looked. It runs on Sonnet (from Claude Code 2.1.251; before that, on `CLAUDE_CODE_SUBAGENT_MODEL` when you set it), and in the background (`background: true`), its report arriving as a notification; under `claude -p` a job that outlasts Claude Code's 10-minute wait for background work loses that report, and a later session collects it only after adopting its run (README, "Claude Code"). A new `relay:codex` subagent does the same but always names Codex, for "use the codex agent". Both come with relay's plugin, whose content changed: run `bin/relay install claude --write` again and restart Claude Code's sessions.
|
|
1466
|
+
|
|
1467
|
+
- **Google's credentials are removed from every launched agent, and what decides Gemini's key is out of every job's reach (Gemini target).** Gemini's target adds Google's credential variables (`GEMINI_API_KEY`, `GOOGLE_API_KEY`, `GOOGLE_GENAI_USE_VERTEXAI`, `GOOGLE_GENAI_USE_GCA`, `GOOGLE_CLOUD_ACCESS_TOKEN`, `GEMINI_CLI_USE_COMPUTE_ADC`, `GEMINI_CLI_AUTH_OVERRIDE`, `GEMINI_API_KEY_AUTH_MECHANISM`) to the vendor keys relay removes from Claude, Codex and Copilot, whether Gemini is switched on or not: under `child_auth: "login"` and under another target's per-target `"any"`. The global `child_auth: "any"` cross-vendor exception has ended in 1.0; `legacy` does not restore it. Gemini still uses only its configured key file. Every relay-enforced turn (Copilot's) is denied `~/.config/relay-keys`, and a key file `~/.config/relay/local.json` moves elsewhere; Claude's turns may not read them either (its sandbox's `denyRead` and `Read` deny rules), while Codex's still can. No job may be granted, keep a grant over, have a file request approved in, or (Claude) write `~/.config/relay`, `~/.config/relay-keys` or a directory `~/.config/relay/local.json` moves a key file to: a job continued with such a grant (one given by 0.9.x, say) is refused until it is given one that leaves the directory out.
|
|
1468
|
+
- **Unsafe login-store entries are quarantined after a turn (1.0).** Relay renames offending names and token files into its private `quarantine/<run>/<node>/<turn>/` directory before reporting failure (EXDEV: `.relay-quarantine.<turn>.<name>` inside the store). The result lists moves or loud per-name failures; run `grok login` again before using Grok. Further turns still require a safe store and restored login.
|
|
1469
|
+
|
|
1470
|
+
- **Speed.** `speed` is `standard`, `fast`, or `ultrafast` where the target/model/account
|
|
1471
|
+
supports it; unset uses the configured target speed or standard (a continuing session
|
|
1472
|
+
keeps its own). Faster service costs money or allowance and is requested only when
|
|
1473
|
+
the user asks. Codex checks the account catalog before prompting; a fast Claude turn
|
|
1474
|
+
that reports standard returns a warning. Launched agents cannot start or continue
|
|
1475
|
+
work faster than their own speed. Older Codex/Claude CLIs are now below the tested floor.
|
|
1476
|
+
- **Extensions.** Claude and Codex jobs/consults may request `extensions: true` when
|
|
1477
|
+
the config allowlists skills or MCP servers. Relay asks the person to consent before
|
|
1478
|
+
launch; only the person may allow consent, gated server calls or other requests from
|
|
1479
|
+
an MCP-bearing session. Skills are filtered and copied per turn; server processes run
|
|
1480
|
+
outside the agent sandbox and go through relay's tool gate. MCP-bearing sessions get
|
|
1481
|
+
no network, no extra write paths and no relay delegation; incompatible inheritance,
|
|
1482
|
+
full-access settings and the Codex exec backend are refused. No extension is inherited
|
|
1483
|
+
merely because it exists in the host config. See [extensions](extensions.md).
|
|
1484
|
+
- **Storage retention.** Defaults keep logs and records indefinitely. `log_max_mb`
|
|
1485
|
+
rotates each log to one `.1` file; `keep_records_days` removes inactive, unused
|
|
1486
|
+
runs through clean and a worker's daily cleanup. Registry migration backups are never
|
|
1487
|
+
deleted by retention and may contain prompts; remove them yourself once rollback is
|
|
1488
|
+
no longer needed. Doctor reports usage and warns below 1 GB free.
|
|
1489
|
+
- **Targets off by default.** Copilot remains off by default and unqualified at 1.0.98;
|
|
1490
|
+
opt in with enabled + experimental. Its Free plan's `auto` runs as unknown family,
|
|
1491
|
+
it drops relay's tools, and repository skills/hooks load inside relay's sandbox.
|
|
1492
|
+
Grok is off by default and unqualified at 1.0.62. Gemini CLI is off by default and
|
|
1493
|
+
qualified (the maintainer, 2026-10-22; 0.64.0 and 0.65.0 recorded, its documented residuals accepted):
|
|
1494
|
+
opt in with enabled alone, and a `targets.gemini.experimental` kept from before is accepted
|
|
1495
|
+
and changes nothing. Its agents
|
|
1496
|
+
get relay's tools through Gemini's own tool discovery on any version relay runs, with a
|
|
1497
|
+
check at each launch that Gemini ran relay's discovery command (where it did not, the agent is told before its
|
|
1498
|
+
prompt and the turn says so); verified live on <!-- verified:geminiToolDiscovery -->0.64.0, 0.65.0, 0.67.0 and 0.68.0<!-- /verified -->, which `relay doctor`
|
|
1499
|
+
reports ([gemini.md](gemini.md) §3.8). It runs only with
|
|
1500
|
+
`targets.gemini.child_auth: "any"` and the key file of its setup ([gemini.md](gemini.md)
|
|
1501
|
+
§4; [security row](security-model.md#per-harness-security)). Neither
|
|
1502
|
+
`allow_untested` nor an installed binary substitutes for Copilot's or Grok's experimental opt-in.
|