feat(box): restart a claude session at a turn boundary, keeping its conversation

Draft
ST
7d ago
+657-10

What and why

Penguini (a multiplayer agent workspace) drives berthd in a runner container through a hub. The hub needs to restart a running Claude chat session (for a Claude Code upgrade, an MCP config change, or a new login) without losing the conversation. Today the only way is to kill the session or wait for it to exit, then resume it. This PR adds a restart that waits for the end of the current turn.

API

POST /v1/sessions/{name}/restart, optional body {"reason": "…"}, optional ?timeout=10m (default 10m, max 1h) for how long to wait for the turn to end.

  1. Waits until the conversation is between turns: its log has been read back, Claude isn't busy, nothing is pending (permissions or a helper's ask), and the turn ledger has no pending, running or waiting turn. Then it takes the session's send lock.
  2. Stops the agent-host. Claude exits on stdin EOF, then the restart waits for the pane to show it has exited.
  3. Appends a host entry {"dir":"host","event":"restart","text":reason} to events.jsonl.
  4. Starts Claude again in place, on the same log and socket. It uses --resume <agent_session_id>, or --session-id if the session was never prompted, and keeps the model, effort and permission mode it ran with.

A client following events.jsonl by seq sees host exited, then restart, then started, and the seq carries on with no reset. Prompts sent with when: idle during the restart are held in the inbox and go to the new agent.

Answers 200 {"name","agent_session_id","waited_ms","reason"}. Errors:

  • 404: unknown session.
  • 409: not a structured Claude session, its agent has already ended, or a restart is already running.
  • 504: the turn didn't end within the timeout. The agent is left running.
  • 400: bad timeout.

The restart also publishes a session.restarted bus event, and boxes list the sessions.restart capability. It passes through before:session.start gates with restart: true.

CLI

berthd session restart NAME [--reason TEXT] [--timeout 10m] [--json]. The laptop form is berth session restart BOX/NAME ….

Fix: resume dropped model and effort

relaunch called launchClaudeIn(…, "", "", mode, …), so resuming a Claude conversation dropped the --model/--effort saved in meta.json. It now passes them, and uses the saved mode when the caller doesn't ask for one. carryOn copies model and effort into the new conversation's meta.

Races handled

  • The old conversation follower is forgotten before the host is stopped. Without this, the bus would announce the agent as exited, which triggers phone notifications and leaves the ledger in exited. A forgotten follower now stops instead of attaching to the new host on the same socket, where it could double-answer bypass permissions.
  • Boundary check under the lock: sendPrompt holds the send lock while it writes and publishes session.sent. After taking the lock, the restart checks the boundary again so that a send that won the race keeps its turn.
  • While a session is restarting, deliverInbox puts its held prompts back instead of blocking the Turns loop or starting a turn on the old agent. The restart kicks the inbox when it is done.
  • If anything reported the old agent as exited mid-restart, a Ready is queued after it, so the inbox goes on.

Tests

New tests in internal/box/restart_test.go, using fakeStreamClaude with a new take your time turn that ends by itself after 1.5s:

  • A restart requested mid-turn waits for the result before the host's exited. waited_ms is at least 500.
  • Both host started argv carry the same --model/--effort/--permission-mode, and the second adds --resume <sid>.
  • Log seq is contiguous with no reset. Host entries are started, exited, restart(reason), started.
  • A when: idle send made during the restart is queued, goes in after the new started, and is answered.
  • Timeout: ?timeout=500ms on a turn that doesn't end returns 504. The host is still alive, no exit is logged, and the session still takes an interrupt and new sends.
  • A session that was never prompted restarts with --session-id. The tests also check 404 (unknown session), 409 (terminal session) and 400 (bad timeout).
  • A unit test checks that relaunch keeps model, effort and mode.

I broke the code on purpose to check that the tests catch it: dropping model/effort in relaunch and skipping the boundary wait each make the tests fail.

Checks run:

  • go vet ./... passes.
  • go test -race ./internal/box/... ./internal/boxcmd/... ./internal/agenthost/... ./cmd/... passes, except TestTheCatalogIsCapped, which also fails on a clean origin/main on this machine.
  • The full go test -race ./... passes apart from that test and one flaky TempDir cleanup in internal/agent, which passes on rerun and is untouched here.
  • docs-site pnpm build passes.
  • gofmt is clean on the changed files.

🤖 Generated with Claude Code


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.