`remote/driver.py` + `--remote` interception — orchestrate the remote run

❌ This issue is not open for contribution. Visit Contributing guidelines to learn about the contributing process and how to find suitable issues.

Overview

A driver.py module providing run_remotely() — the orchestration that ties config, transport, and session into a full remote run.

Complexity: High
Target branch: main

Context

• Flags land on the base parser (chefs.py:99).
• Interception is in main() (chefs.py:517).
• Consumes config.py (#703), transport.py (#704), session.py (#705).
• The box can own secrets (STUDIO_TOKEN, Google Docs, Box), independent of the client.
• tokens.py:39 already reads STUDIO_TOKEN on the box, exactly as locally.

Out of Scope

• The out-of-band remote subcommand group and its doctor/cache commands (cli.py).

Acceptance Criteria

General

• --remote[=<name>], --env KEY=VALUE (repeatable), and --env-pass KEY (repeatable) are added to the base SushiChef parser.
• main() hands a --remote run to run_remotely().
• main() does not call run() for a --remote run.
• Remote argv is rebuilt from sys.argv with --remote, --token, --env, --env-pass stripped.
• Preflight verifies the host is reachable before syncing.
• Preflight verifies uv is present on the box before syncing.
• Preflight verifies tmux is present on the box before syncing.
• The venv builds with uv sync when the chef has a pyproject.toml, else uv pip install -r requirements.txt.
• The venv is rebuilt only when the manifest hash changes.
• A chef with neither manifest falls back to a shared default venv with released ricecooker.
• The shared default venv lives at <remote_root>/.default-venv/.
• Optional ricecooker_source = "local" syncs the developer's ricecooker checkout to the box.
• With ricecooker_source = "local", that checkout installs editable into the chef's venv.

Environment

• Box-owned secrets live in ~/.config/ricecooker/remote-env on the box (mode 600).
• The run wrapper sources that file before running the chef.
• Box-owned secrets never transit the client.
• Client-supplied --env/--env-pass/resolved token are forwarded via tmux set-environment.
• Client-supplied values override box-owned ones for that run.
• Under --remote the client never prompts for a token.
• The client forwards a token only if it resolves non-interactively.
• Client-supplied secrets are never written to the box's disk or the chef's argv.

Run lifecycle

• A live session is reported with its start time.
• A live session is attached, not restarted.
• A finished pane's previous exit code is reported.
• The finished pane is then killed.
• A fresh run starts after the pane is killed.
• No session → create it detached.
• After creating, attach to the session.
• Ctrl-C reaches the chef as SIGINT over the PTY.
• Ctrl-C does not kill the session.
• Detaching exits 0.
• Detaching prints instructions to reattach.
• After attach, the client reads .ricecooker-remote/exitcode and exits with it.
• run_remotely() creates <remote_root>/.ricecookerfilecache/ when absent.
• The file cache is passed to the chef as <remote_root>/.ricecookerfilecache/.
• config_logger writes logs/… on the box.
• tmux pipe-pane captures the raw session to a log.
• Both log paths are printed on exit.

Failures

• Plumbing errors are prefixed remote:.
• Plumbing errors pass ssh/rsync stderr through verbatim.
• A venv build failure leaves the session alive for inspection.
• A venv build failure shows the tail of the uv output.
• A chef exiting nonzero passes through unprefixed.

Testing

• Integration tests drive run_remotely() through the fake-box runner.
• Coverage includes the no-session path.
• Coverage includes the live-session path.
• Coverage includes the finished-pane path.
• Coverage includes exit-code propagation.
• Coverage includes the token reaching the environment.
• tests/test_argparse.py asserts main() skips run() under --remote.
• tests/test_argparse.py asserts the token lands in env, not argv.
• One opt-in localhost-over-ssh e2e exercises a real run end-to-end.

AI usage

Claude (Claude Code) drafted this from the design spec; I directed the design and reviewed it.