Remote chef execution (`--remote`)

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

Overview

Run a chef on a shared, well-connected remote box instead of the developer's laptop, so content downloads don't consume home bandwidth. The iteration loop is unchanged — edit locally, re-run, read the log — with the bytes moving on the box. A single --remote flag on the base SushiChef parser turns any chef into a remote run.

Scope

Included:

• --remote[=<name>] on the base SushiChef parser.
• main() intercepts a --remote run and runs it remotely instead of locally.
• ssh + rsync + tmux against a shared service account.
• No server component.
• Two-layer config: global host profiles (per laptop) + per-chef sync file (name/protect/exclude).
• Host resolves --remote=<name> > global default.
• Per-script sync/venv/session on the box.
• One run at a time per script (the session is the lock).
• File cache shared across scripts at <remote_root>/.ricecookerfilecache/.
• Box-owned secrets (STUDIO_TOKEN + service creds like Google Docs, Box) that never leave the box.
• Client-supplied --env KEY=VALUE / --env-pass KEY that override box values for a run.
• Under --remote the client never prompts for a token: forwards one only if resolved non-interactively, else the box supplies it.
• A remote subcommand group on the chef CLI for out-of-band commands (python chef.py remote {attach,sync,pull,shell,cache,doctor}).

Excluded (non-goals):

• Concurrent runs of different scripts (start simple — one at a time).
• Job history or database.
• Web UI.
• Multi-tenant auth.
• Container isolation.
• Queueing or scheduling.
• A remote-fetch-only mode with the chef still running locally.

Strategy

• ssh provides transport, auth, and log streaming.
• ssh delivers SIGINT and gives debugger access.
• tmux adds survival across disconnects.
• A bespoke daemon was rejected — it would re-implement what SSH gives free.
• Code lives in a new ricecooker/utils/remote/ package, one module per responsibility, so the backend is swappable:

• No ssh/rsync string is constructed outside transport.py.
• The five sub-issues follow this dependency order: config → transport → session → driver (+ --remote interception) → CLI.

Testing Requirements

• Integration tests exercise the real config → transport → session → driver stack end-to-end.
• The only mock is the external process boundary — actual ssh/rsync/tmux execution.
• That boundary is a single injectable seam in transport.py — a runner that spawns the subprocess.
• Tests substitute a fake box: a runner simulating a remote filesystem (.ricecooker-remote/exitcode, bookkeeping) and a session registry.
• Lifecycle is exercised through the driver, not asserted per module.
• Covered paths: no session, live session, and finished pane.
• Coverage also includes exit-code propagation and token-in-environment.
• One real end-to-end against localhost over ssh, fully unmocked, skipped unless an env var is set. Not run in CI.

Acceptance Criteria

• All five sub-issues (config, transport, session, driver + --remote interception, CLI) are merged.
• python chef.py --remote uploadchannel … runs any SushiChef on the configured box and propagates its exit code.
• Re-running --remote while a script's session is live attaches instead of starting a second run.
• A client with no local token can run a chef whose box holds STUDIO_TOKEN — the token never transits the client.
• --env/--env-pass reach the chef's environment on the box and override box-owned values for that run.
• Client-supplied secrets are never written to the box's disk or the chef's argv.
• python chef.py remote {attach,sync,pull,shell,cache,doctor} run the out-of-band commands against the chef's box.
• Integration tests cover the run lifecycle through the fake-box seam.
• The opt-in localhost e2e passes.
• User-facing docs cover config setup (global profiles + per-chef file) and the --remote workflow.

AI usage

Claude (Claude Code) drafted this tracking issue and its sub-issues from a design spec I wrote (.specs/2026-07-20-remote-chef-execution-design.md). I directed the decomposition. I corrected the design through several rounds of review. I updated the spec to match before filing.

This tracking issue is explicitly not open for contribution and coordinates five dependent sub-issues rather than naming a starter task. If work becomes available, begin with the referenced design spec at .specs/2026-07-20-remote-chef-execution-design.md and follow the config → transport → session → driver → CLI order; completion is defined by the listed acceptance criteria and integration tests.