Sandboxed Claude session loses login after token expiry; auto-update fails #181

Problem

A Claude session in the relay sandbox loses its login after some hours. Inside the sandbox it cannot re-authenticate. Logging in from an unsandboxed terminal and starting a new sandbox session fixes it. Auto-update also fails in the sandbox.

Root cause

Partly measured.

Measured by running the generated Claude profile (cmd/relay/testdata/golden_sandbox_profile_claude.sb) under sandbox-exec:

Claude Code keeps its OAuth login (claudeAiOauth: access token, refresh token, expiresAt) in both the keychain and ~/.claude/.credentials.json. The access token lasts about 8 hours.

Hypothesis, not yet reproduced: the sandboxed client refreshes the token, the server rotates the refresh token, the keychain write is denied, and the stored refresh token is then dead. A login inside the sandbox fails at the same keychain write.

Auto-update fails because the updater must write the version directory and relink ~/.local/bin/claude. Granting those read-write would let a sandboxed agent replace the binary the next unsandboxed launch runs. Do not grant them.

Fix

Options; needs owner decision: secrets.

• A. Credentials file only. Make the sandboxed Claude read and write ~/.claude/.credentials.json and never the keychain, so refresh survives. Open question: does Claude Code fall back to the file after a keychain write fails, or does it prefer the stale keychain copy? Settle this first.
• B. Inject a token from relay (CLAUDE_CODE_OAUTH_TOKEN). Open question: a long-running session may go stale if the injected token does not refresh. Unknown whether it refreshes or expires fixed. Needs a measurement.
• C. Grant write on ~/Library/Keychains. Works, but lets the sandbox alter any keychain item. Least preferred.
• Auto-update: set DISABLE_AUTOUPDATER=1 in sandbox sessions and update from an unsandboxed terminal.

What I'd notice

Sandbox sessions stay logged in across the 8 hour token lifetime, and no update error appears at start.

Tasks

• Reproduce: sandbox session past token expiry, record where the refresh fails (keychain write vs. file).
• Determine whether the file store is used after a keychain write failure.
• Determine whether an injected token refreshes in a long session.
• Pick A, B or C; update the profile and golden test.
• Set DISABLE_AUTOUPDATER=1 for sandbox sessions.

Contract

Login half only; the updater half shipped in relay#502. Owner decisions of 2026-10-19 are final. One PR, branch fix/181-login-store, base main.

Fix: every sandboxed Claude Code launch gets CLAUDE_CONFIG_DIR=<sandbox Claude folder>, one relay-owned folder shared by every sandboxed Claude on the Mac. Relay creates it (mode 0700) and seeds it with links to the person's ~/.claude entries, never credentials. The profile grants it read-write. Claude then keeps its login in <folder>/.credentials.json. The keychain write that the sandbox refuses no longer leaves a stale item that shadows the file: the owner measured that CLAUDE_CONFIG_DIR=<empty dir> reports loggedIn: false while the default item is readable, so Claude looks up a different keychain item for a non-default folder. Every sandboxed Claude logs out once, until the person runs /login inside one.

Acceptance criteria

• AC1. A sandboxed claude session starts with CLAUDE_CONFIG_DIR set to the sandbox Claude folder.
• AC2. A sandboxed terminal launch of the claude-code template starts with CLAUDE_CONFIG_DIR set to the same folder.
• AC3. An unsandboxed launch starts without CLAUDE_CONFIG_DIR, and relay creates no sandbox Claude folder for it. An SSH host launch does not change.
• AC4. A CLAUDE_CONFIG_DIR value in the template's own env reaches the child unchanged.
• AC5. The profile of both launches lets the session write inside the folder, and still refuses a write beside it.
• AC6. Relay creates the folder with mode 0700 and links each listed ~/.claude entry into it by absolute path.
• AC7. The folder holds no .credentials.json and no .claude.json, and no entry in it is a copy of a ~/.claude file.
• AC8. Seeding keeps an entry that already exists, link or not, and a second launch changes nothing.
• AC9. When the folder path exists and is not a real directory, the launch is refused with 400 sandbox_unavailable, and the message names the path.
• AC10. No keychain grant changes.

Interfaces

internal/sessions/childenv/childenv.go (stays a stdlib-only leaf; update the package doc):

const EnvClaudeConfigDir = "CLAUDE_CONFIG_DIR"
// SandboxClaudeDir is <os.UserConfigDir()>/relay/sandbox-claude: the same
// "relay" folder bridge.DefaultConfigDir names. Deliberately not bridge.ConfigDir:
// it does not move with --config-dir, so every relay instance under one HOME
// (Relay.app, each verify stack) shares one login. An os.UserConfigDir error is
// returned wrapped, never replaced by a fallback.
func SandboxClaudeDir() (string, error)
// SandboxedClaude now takes the folder: {DISABLE_AUTOUPDATER: "1", CLAUDE_CONFIG_DIR: configDir}.
func SandboxedClaude(configDir string) map[string]string

cmd/relay/session_claude_dir.go (new):

// isClaudeLaunch: kind == KindClaude, or kind == KindPTY and tmpl.ID == kindTemplateIDs[KindClaude].
func isClaudeLaunch(kind string, tmpl *config.TerminalTemplate) bool
// ensureSandboxClaudeDir resolves SandboxClaudeDir, creates it and seeds it; returns the folder.
func ensureSandboxClaudeDir() (string, error)

ensureSandboxClaudeDir behaviour:

1. os.MkdirAll the parent (0700), then os.Mkdir(dir, 0o700). If it exists, os.Lstat must report a directory, not a link: otherwise return sandbox claude dir <path>: not a directory. An existing directory keeps its mode.
2. For each name in sandboxClaudeLinks: if os.Lstat(<dir>/<name>) finds anything, skip it (never overwrite, links included). Target is <home>/.claude/<name> from os.UserHomeDir, not symlink-resolved. projects and sessions get their target created first (MkdirAll, 0700). Every other name is linked only when its target exists. os.Symlink(target, link); EEXIST counts as seeded (a parallel launch got there first); any other error returns sandbox claude dir <path>: link <name>: <err>.
3. It never reads, copies or opens a file in ~/.claude.

sandboxClaudeLinks, each with its reason:

• settings.json: the person's permissions, hooks, env and model choice, as an unsandboxed Claude sees them.
• CLAUDE.md: the person's global instructions; a sandboxed Claude reads them today through ~/.claude.
• skills, agents, commands: the person's own skills, subagents and slash commands.
• projects: transcripts. Relay reads history on join and deletes transcripts under ~/.claude/projects (ReadClaudeHistory, DeleteSession), and the outside-session probe reads there too.
• sessions: Claude's pid registry. The outside-session probe and devboxverify read ~/.claude/sessions.
• Never linked: .credentials.json (the login itself); .claude.json, which lives in the folder under CLAUDE_CONFIG_DIR and can hold account data or an API key. Plugins and the rest stay out (Q4).

cmd/relay/session_launch.go, AuthorizeLaunch, right after sandbox is computed: when sandbox && isClaudeLaunch(req.Kind, tmpl), call ensureSandboxClaudeDir; an error returns invalidRequest("sandbox_unavailable", err.Error(), baseFields) (an existing, documented code: audited and evented as today). The PTY block from relay#502 passes that folder to childenv.SandboxedClaude(dir), and a key the template's env sets still wins.

cmd/relay/session_sandbox.go, sandboxSpecForLaunch: when isClaudeLaunch(kind, tmpl), append childenv.SandboxClaudeDir() to readWrite, beside the pi leaf. This is not demoted in a read-only-projects session, because it is not a project. sandboxWritableRoots needs no change: the folder is under home, which is always in W.

internal/sessions/provider/claude.go, Start (console spawn): when p.cfg.SandboxProfile != "", resolve childenv.SandboxClaudeDir(). An error fails the start with sandboxed claude: %w. buildClaudeEnv merges childenv.SandboxedClaude(dir). Relay already created the folder in AuthorizeLaunch (a resume goes through it too), so the provider creates nothing.

Wire shapes: none change. No hostapi field; both processes resolve the same function under the same HOME, and the e2e path assertions catch any drift.

Paths

• Simple: the person opens a Claude Code terminal (eve terminal card, relay sandbox claude-code) or starts a Claude session. The first sandboxed Claude asks for a login. The person runs /login once inside it, and every later sandboxed Claude on the Mac shares that login and refreshes it. No new screen, no new choice.
• Power: settings.json terminal_templates[] claude-code env.CLAUDE_CONFIG_DIR points a terminal at another folder, which the operator must also grant in read_write. A claude session reads no template env, so it has no power door. That is deliberate: one store for every session.

File ownership

Dev task (A):

• internal/sessions/childenv/childenv.go
• internal/sessions/provider/claude.go
• cmd/relay/session_claude_dir.go (new)
• cmd/relay/session_launch.go
• cmd/relay/session_sandbox.go
• internal/sessions/sandbox/sandbox.go: package comment only. The ~/Library/Keychains sentence no longer holds for Claude's login; it becomes: kept readable, but the login no longer depends on it.
• docs/session-host.md: a new subsection after the updater paragraph covering the folder, who makes it, the link list, /login once, the keychain untouched, template env wins, and unsandboxed and SSH host launches unchanged. Also extend the "Every session" grant row: a Claude launch also gets the sandbox Claude folder.
• docs/FEATURES.md: a new row G1.44 "Sandboxed Claude keeps its own login". Simple door: none (turns on by itself; /login once). Power door: settings.json terminal_templates[].env. Doors as G1.43. Proof: event:session.launch=ok#session_id code:http:POST /api/sessions#400. Tests: the nine names below.

Test task (B):

• e2e/features/bug181_sandboxed_claude_login_test.go (new; reuses b181Start and b181Terminal from the updater file, which it does not edit)
• e2e/fakes/fakeagent/main.go: add CLAUDE_CONFIG_DIR to watchedEnv, nothing else
• docs/testing.md: the watched-variable sentence names CLAUDE_CONFIG_DIR

No other file. docs/THREAT-MODEL.md does not change: a sandboxed Claude reaches a Claude login it already reaches today (keychain read, ~/.claude read-write), now in a relay-owned leaf. No promise moves; the reviewer confirms. No golden profile test exists (relay has no unit tests); AC5 is proven by behaviour.

Tests (task B), expected folder W = <i.Home>/Library/Application Support/relay/sandbox-claude

1. TestBug181SandboxedClaudeSessionConfigDir: the session's start line has CLAUDE_CONFIG_DIR == W (AC1).
2. TestBug181SandboxedClaudeTerminalConfigDir: b181Terminal env has CLAUDE_CONFIG_DIR == W (AC2).
3. TestBug181UnsandboxedClaudeNoConfigDir: with sandbox:false, the key is unset and W does not exist (AC3).
4. TestBug181TemplateConfigDirWins: template env CLAUDE_CONFIG_DIR=<i.Tmp>/acme-claude reaches the child as that value (AC4).
5. TestBug181SandboxClaudeDirWritable: in a session, !sh touch "<W>/acme-probe" answers exit: 0 and the file exists. !sh touch "<i.Home>/Library/Application Support/relay/acme-outside" does not answer exit: 0, and no file appears (AC5). Quote the paths: they contain a space.
6. TestBug181SandboxClaudeTerminalDirWritable: override the claude-code template's command with /bin/sh -c 'touch "$CLAUDE_CONFIG_DIR/acme-probe"'. relay sandbox claude-code from the project folder exits 0 and the file exists in W (AC2, AC5).
7. TestBug181SandboxClaudeDirSeeded: the fixture ~/.claude holds settings.json, CLAUDE.md, skills/, agents/, commands/, plus a .credentials.json and a ~/.claude.json of placeholder bytes (acme-placeholder, never a token). After one session turn: W is mode 0700. Each of the seven names is a link whose Readlink is <i.Home>/.claude/<name>, and the projects and sessions targets are directories. W holds no .credentials.json and no .claude.json. No regular file in W holds the placeholder bytes, and every entry in W is one of the seven (AC6, AC7).
8. TestBug181SandboxClaudeDirKeepsOwnEntries: W exists before the launch with a regular settings.json (acme-own). Two launches both answer 201. settings.json stays a regular file with the same bytes, and the other links match after each launch (AC8).
9. TestBug181SandboxClaudeDirNotADirRefused: W is a symlink to <i.Home>/acme-elsewhere. POST /api/sessions answers 400 with code sandbox_unavailable and a message containing W, and acme-elsewhere stays empty (AC9).

AC10: review only. The diff changes no read entry and no keychain path.

Test surface

• e2e (integration through HTTP and CLI): AC1 to AC9.
• Playwright: none, because no UI changes.
• Real-app check (test machine, needs no account): build the head, then start a sandboxed claude-code terminal. Before (main): claude auth status inside reads the stale store. After (head): CLAUDE_CONFIG_DIR is the folder, the links are present, and claude auth status reports loggedIn: false, the decided one-time logout.
• Interactive, owner only, not a merge condition: /login inside a sandboxed Claude, then a check past one token refresh.

Waits

• Task A: Waits: none; it adds no async work. Seeding finishes inside AuthorizeLaunch before the launch response.
• Task B: Waits: boot on harness.Start (ready.json) and WaitSessionHost. A session launch waits on its 201, a turn on the session message reply (the start line is written before the first reply). A terminal waits on the session.exited event for its id. relay sandbox waits on the CLI process exit. A refusal waits on the HTTP response. Never a sleep.

Budget

• A: 8 files, about 160 lines (code about 110, docs about 50).
• B: 3 files, about 260 lines.
• Single PR, about 420 lines. Past 11 files or 550 lines is a question for the coordinator.

Tasks

• A: dev, as above.
• B: tests 1 to 9. Red on main: test 1 fails at its assertion on main (CLAUDE_CONFIG_DIR unset) through POST /api/sessions.
• Verification task (last; no devlock): repo-suite (cd e2e && go test -race ./features/). Then devboxverify: stack-up r181 --relay <head checkout> --eve <eve main checkout>, go run ./cmd/devboxverify --stack <stack.json> --phase api, stack-down r181. Then the real-app check above. Post Verified: <head> · repo-suite: … · devboxverify: … · real-app: … · log: …. The login journeys are expected to fail until the owner's /login (Q2).

Open questions (recommendation first)

1. INSIDE. Should the grant go in code? Yes, code, as with the pi leaf. The env value must be code anyway: env values do not expand ~, and a claude session reads no template env. The grant could only go in the template through a settings migration that rewrites every install's claude-code template. That is a larger diff, it edits the person's config, and it lets the env and the grant disagree.
2. BEYOND. This PR's stack run, and every later verify on the machine, fails the five login journeys until the owner runs /login once inside a sandboxed Claude on the test machine. Recommendation: the PR records them as an expected known defect pointing at this issue, with no harness change. Pause the nightly (its pause file) from merge until that /login, so a RED night from those journeys does not trigger Revert first.
3. INSIDE. Should projects and sessions be linked, beyond the owner's list? Yes. Without them, history on join, transcript delete and the outside-session probe lose sandboxed sessions. Neither holds credentials.
4. BEYOND. Should plugins be linked? No, not in this PR; it is outside the owner's list. A sandboxed Claude loses the person's plugins until a follow-up is approved. File a from-dev idea if anyone misses them.
5. INSIDE. Should seeding replace a link that points elsewhere (one a session planted)? No: never overwrite, links included. Such a link only reaches what the profile already grants.

ship-blocker: no (owner decision 2026-10-10: not a regression; a known issue until the owner has a working sandbox login)