luv-cli 0.2.1__tar.gz → 0.4.0__tar.gz

{luv_cli-0.2.1 → luv_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: luv-cli
-Version: 0.2.1
+Version: 0.4.0
 Summary: Launch Claude Code or Codex agents on GitHub repos with isolated workspaces and optional Docker dev environments
 Project-URL: Homepage, https://github.com/exospherehost/luv
 Project-URL: Repository, https://github.com/exospherehost/luv
@@ -63,7 +63,7 @@ luv other-org/my-repo "fix the bug"
 # Reopen workspace #42
 luv my-repo 42
 
-# Open any GitHub PR by URL
+# Clone any GitHub PR by URL into a fresh workspace
 luv -l https://github.com/org/repo/pull/123
 
 # Open a shell instead of Claude
@@ -76,7 +76,7 @@ luv -r my-repo 42
 luv --clean
 
 # Tear down a finished session: kill its tmux, delete its workspace
-luv rm myrepo-42
+luv rm myrepo-mbp-42
 luv rm --merged        # everything whose PR has landed
 
 # See what's running on your remote machine, and reattach
@@ -86,15 +86,33 @@ luv continue
 
 ## How it works
 
-1. Clones the repo into `~/prs/{repo}-{number}/`
-2. Creates a new branch `luv-{number}`
+1. Clones the repo into `~/prs/{repo}-{machine}-{number}/`
+2. Creates a new branch `luv-{machine}-{number}`
 3. Configures the selected agent with the workspace's PR conventions
 4. Launches Claude with Opus 5 at max effort, or Codex in YOLO mode
 
-All workspaces live under `~/prs/`. The number comes from the repo's GitHub issue counter to avoid collisions.
+All workspaces live under `~/prs/`. The number comes from the repo's GitHub issue counter, and `{machine}` is a short name for the machine that created the workspace — by default the hostname, or whatever you set with `luv config set machine mbp`.
+
+The machine name is what keeps two computers apart. Each one works out the next number from GitHub independently, so your laptop and your box will happily pick the same one; without the slug they would both push a branch called `luv-43`. Folders and branches created before this keep working unchanged.
 
 With a remote host configured, steps 1–4 happen on that machine inside a tmux session instead — see [Remote sessions](#remote-sessions).
 
+### Opening an existing PR
+
+`luv -l <PR URL>` gives you the PR as it is *right now*: a full clone into a
+workspace of its own, checked out on the PR's head branch. It never reuses a
+folder that happens to be sitting there — a URL you paste is a request to look
+at that PR, not at whatever was checked out in `myrepo-mbp-123` last week. Run
+it twice on the same PR and you get `myrepo-mbp-123` and `myrepo-mbp-123_2`,
+which are independent workspaces you can run side by side. When the PR comes
+from a fork, the base repo is added as `upstream` and fetched too, so the branch
+you need to diff or rebase against is there.
+
+`-r` is the exception: resuming means picking up a conversation, and a
+conversation lives in the folder it was held in, so `luv -l <URL> -r` reopens the
+newest workspace for that PR instead of cloning another. `luv <repo> -pr <N>`
+also keeps reusing its workspace — it names a workspace, where a URL names a PR.
+
 ## Commands
 
 | Command | Description |
@@ -103,8 +121,9 @@ With a remote host configured, steps 1–4 happen on that machine inside a tmux
 | `luv config set\|get\|unset <key> [value]` | Read or write a single setting |
 | `luv config list` | Show all settings |
 | `luv --init` | Configure default GitHub org only |
-| `luv ls [--host H] [--prune] [--no-pr]` | List live sessions across hosts, with each one's PR link |
+| `luv ls [--host H] [--prune] [--no-pr]` | List every live session on every host, with each one's PR link |
 | `luv continue [<repo> [number]]` | Attach to a live session |
+| `luv handover [<repo> [n]] --to HOST` | Move a session to another machine and resume it there |
 | `luv rm <session\|workspace>...` | Kill a session and delete its workspace on its host |
 | `luv rm --merged [--host H] [-f]` | Remove every session whose PR is merged |
 | `luv rm --dead [--host H] [-f]` | Remove workspaces with no live session |
@@ -112,8 +131,8 @@ With a remote host configured, steps 1–4 happen on that machine inside a tmux
 | `luv --codex [org/]<repo> [prompt...]` | Create a workspace and launch Codex in YOLO mode |
 | `luv [org/]<repo> -b <branch> [prompt...]` | Create a workspace based off `<branch>` instead of the default |
 | `luv [org/]<repo> <number> [prompt]` | Reopen an existing workspace |
-| `luv -l <PR URL> [prompt]` | Open any GitHub PR by URL |
-| `luv [org/]<repo> -pr <number> [prompt]` | Open a PR by repo + number |
+| `luv -l <PR URL> [prompt]` | Clone any GitHub PR by URL into a fresh workspace |
+| `luv [org/]<repo> -pr <number> [prompt]` | Open a PR by repo + number, reusing its workspace |
 | `luv --clean` | Delete workspaces where the branch is fully pushed/merged |
 | `luv --clean -f` | Force delete all workspaces |
 | `luv --clean --safe -f` | Force delete only workspaces older than 24h |
@@ -134,9 +153,20 @@ With a remote host configured, steps 1–4 happen on that machine inside a tmux
 | `-s HOST` | Run on `HOST` over SSH, overriding the configured remote host |
 | `-i PATH` | SSH identity file to use for this invocation |
 | `--local` | Force local execution even when a remote host is configured |
-| `-f`, `--force` | Skip safety checks (with `--clean`) |
+| `-f`, `--force` | Skip safety checks (with `--clean`); replace an existing destination folder (with `handover`) |
 | `--safe` | With `--clean -f`, only delete workspaces older than 24h (mtime) |
 
+Handover flags:
+
+| Flag | Description |
+|------|-------------|
+| `--to HOST` | Destination machine; `local` for the one you're on |
+| `--from HOST` | Source machine, when luv can't tell from its session registry |
+| `--no-agent-state` | Move the workspace only; the agent starts a new conversation |
+| `--no-attach` | Leave the destination session running detached |
+| `--purge` | Delete the source folder once the copy is verified |
+| `-y` | Skip the "an agent may still be running" confirmation |
+
 ## Docker dev environments
 
 If a repo contains `.luv/settings.json` with a `compose_file` key, `luv` automatically starts a Docker Compose environment and runs Claude inside the `dev-environment` container.
@@ -179,7 +209,7 @@ The `dev-environment` service **must** have the selected agent CLI (`claude` or
 
 1. Detects `.luv/settings.json` with `compose_file` key
 2. Tears down any stale environment from a previous run
-3. Starts `docker compose up -d --build` with a unique project name (`luv-{repo}-{number}`) for network/volume isolation
+3. Starts `docker compose up -d --build` with a unique project name (`luv-{repo}-{machine}-{number}`) for network/volume isolation
 4. Verifies the `dev-environment` service is running
 5. Runs the selected agent inside the container via `docker compose exec`
 6. The repo is volume-mounted, so all file changes and git commits are visible on the host
@@ -201,8 +231,24 @@ luv continue                        # reattach exactly where you left off
 
 `luv` re-invokes itself on the remote over SSH, so every flag works there unchanged. The remote needs `luv`, `tmux`, `gh`, and `git` on its `PATH`.
 
+`luv ls` lists what is running on every host it knows about, not only the sessions this machine started — a session dispatched from your laptop shows up on your desktop, and `luv continue` and `luv rm` reach it from either.
+
 Use `--local` for a one-off local run, `-s HOST` to target a different machine, and `-i PATH` for a different SSH key.
 
+### Handing a session to another machine
+
+Start something on your laptop, then move it — workspace, uncommitted work, and the agent's conversation — to a machine that won't go to sleep:
+
+```bash
+luv --local myrepo "start something"   # working locally
+luv handover myrepo 43 --to box        # resumes mid-conversation on box
+luv handover myrepo 43 --to local      # ...and back again later
+```
+
+The whole folder crosses over, including untracked and gitignored files, so a workspace that ran before the move still runs after it. The agent's transcript moves too, so it picks up where it left off rather than starting fresh. Bytes are relayed through the machine you run the command on, so the two ends never need SSH access to each other.
+
+The source folder is left on disk (`--purge` deletes it), and the workspace keeps the name it was created with.
+
 Full guide, including how to prepare a fresh Ubuntu box and set up SSH keys: **[docs/remote-sessions.md](docs/remote-sessions.md)**.
 
 ## Workspace cleanup
@@ -224,8 +270,8 @@ delete, and never touches a workspace with a live session. `luv rm` is the
 opposite — you name what goes, and it goes, on whichever host it lives on.
 
 ```bash
-luv rm myrepo-42          # kill its tmux session, delete ~/prs/myrepo-42 on its host
-luv rm luv-myrepo-42      # the session name works too
+luv rm myrepo-mbp-42      # kill its tmux session, delete the folder on its host
+luv rm luv-myrepo-mbp-42  # the session name works too
 luv rm --merged           # every session whose PR has been merged
 luv rm --dead             # workspaces left behind by sessions that already exited
 luv rm --dead --host box  # scope either selector to one machine
@@ -240,9 +286,10 @@ registry as soon as its tmux session exits, but the clone it was working in
 stays on the remote disk. Those orphans are invisible to `luv ls` and are
 usually what is actually filling up the box.
 
-Only folders named `{repo}-{N}` are ever eligible — anything else in the
-workspace root is left alone, and a target that doesn't resolve to one is an
-error rather than an `rm -rf`.
+Only folders ending in `-{N}` are ever eligible — `{repo}-{machine}-{N}`, a
+`luv -l` copy `{repo}-{machine}-{N}_2`, and pre-slug `{repo}-{N}` alike.
+Anything else in the workspace root is left alone, and a target that doesn't
+resolve to one is an error rather than an `rm -rf`.
 
 ## Configuration
 

{luv_cli-0.2.1 → luv_cli-0.4.0}/README.md

@@ -40,7 +40,7 @@ luv other-org/my-repo "fix the bug"
 # Reopen workspace #42
 luv my-repo 42
 
-# Open any GitHub PR by URL
+# Clone any GitHub PR by URL into a fresh workspace
 luv -l https://github.com/org/repo/pull/123
 
 # Open a shell instead of Claude
@@ -53,7 +53,7 @@ luv -r my-repo 42
 luv --clean
 
 # Tear down a finished session: kill its tmux, delete its workspace
-luv rm myrepo-42
+luv rm myrepo-mbp-42
 luv rm --merged        # everything whose PR has landed
 
 # See what's running on your remote machine, and reattach
@@ -63,15 +63,33 @@ luv continue
 
 ## How it works
 
-1. Clones the repo into `~/prs/{repo}-{number}/`
-2. Creates a new branch `luv-{number}`
+1. Clones the repo into `~/prs/{repo}-{machine}-{number}/`
+2. Creates a new branch `luv-{machine}-{number}`
 3. Configures the selected agent with the workspace's PR conventions
 4. Launches Claude with Opus 5 at max effort, or Codex in YOLO mode
 
-All workspaces live under `~/prs/`. The number comes from the repo's GitHub issue counter to avoid collisions.
+All workspaces live under `~/prs/`. The number comes from the repo's GitHub issue counter, and `{machine}` is a short name for the machine that created the workspace — by default the hostname, or whatever you set with `luv config set machine mbp`.
+
+The machine name is what keeps two computers apart. Each one works out the next number from GitHub independently, so your laptop and your box will happily pick the same one; without the slug they would both push a branch called `luv-43`. Folders and branches created before this keep working unchanged.
 
 With a remote host configured, steps 1–4 happen on that machine inside a tmux session instead — see [Remote sessions](#remote-sessions).
 
+### Opening an existing PR
+
+`luv -l <PR URL>` gives you the PR as it is *right now*: a full clone into a
+workspace of its own, checked out on the PR's head branch. It never reuses a
+folder that happens to be sitting there — a URL you paste is a request to look
+at that PR, not at whatever was checked out in `myrepo-mbp-123` last week. Run
+it twice on the same PR and you get `myrepo-mbp-123` and `myrepo-mbp-123_2`,
+which are independent workspaces you can run side by side. When the PR comes
+from a fork, the base repo is added as `upstream` and fetched too, so the branch
+you need to diff or rebase against is there.
+
+`-r` is the exception: resuming means picking up a conversation, and a
+conversation lives in the folder it was held in, so `luv -l <URL> -r` reopens the
+newest workspace for that PR instead of cloning another. `luv <repo> -pr <N>`
+also keeps reusing its workspace — it names a workspace, where a URL names a PR.
+
 ## Commands
 
 | Command | Description |
@@ -80,8 +98,9 @@ With a remote host configured, steps 1–4 happen on that machine inside a tmux
 | `luv config set\|get\|unset <key> [value]` | Read or write a single setting |
 | `luv config list` | Show all settings |
 | `luv --init` | Configure default GitHub org only |
-| `luv ls [--host H] [--prune] [--no-pr]` | List live sessions across hosts, with each one's PR link |
+| `luv ls [--host H] [--prune] [--no-pr]` | List every live session on every host, with each one's PR link |
 | `luv continue [<repo> [number]]` | Attach to a live session |
+| `luv handover [<repo> [n]] --to HOST` | Move a session to another machine and resume it there |
 | `luv rm <session\|workspace>...` | Kill a session and delete its workspace on its host |
 | `luv rm --merged [--host H] [-f]` | Remove every session whose PR is merged |
 | `luv rm --dead [--host H] [-f]` | Remove workspaces with no live session |
@@ -89,8 +108,8 @@ With a remote host configured, steps 1–4 happen on that machine inside a tmux
 | `luv --codex [org/]<repo> [prompt...]` | Create a workspace and launch Codex in YOLO mode |
 | `luv [org/]<repo> -b <branch> [prompt...]` | Create a workspace based off `<branch>` instead of the default |
 | `luv [org/]<repo> <number> [prompt]` | Reopen an existing workspace |
-| `luv -l <PR URL> [prompt]` | Open any GitHub PR by URL |
-| `luv [org/]<repo> -pr <number> [prompt]` | Open a PR by repo + number |
+| `luv -l <PR URL> [prompt]` | Clone any GitHub PR by URL into a fresh workspace |
+| `luv [org/]<repo> -pr <number> [prompt]` | Open a PR by repo + number, reusing its workspace |
 | `luv --clean` | Delete workspaces where the branch is fully pushed/merged |
 | `luv --clean -f` | Force delete all workspaces |
 | `luv --clean --safe -f` | Force delete only workspaces older than 24h |
@@ -111,9 +130,20 @@ With a remote host configured, steps 1–4 happen on that machine inside a tmux
 | `-s HOST` | Run on `HOST` over SSH, overriding the configured remote host |
 | `-i PATH` | SSH identity file to use for this invocation |
 | `--local` | Force local execution even when a remote host is configured |
-| `-f`, `--force` | Skip safety checks (with `--clean`) |
+| `-f`, `--force` | Skip safety checks (with `--clean`); replace an existing destination folder (with `handover`) |
 | `--safe` | With `--clean -f`, only delete workspaces older than 24h (mtime) |
 
+Handover flags:
+
+| Flag | Description |
+|------|-------------|
+| `--to HOST` | Destination machine; `local` for the one you're on |
+| `--from HOST` | Source machine, when luv can't tell from its session registry |
+| `--no-agent-state` | Move the workspace only; the agent starts a new conversation |
+| `--no-attach` | Leave the destination session running detached |
+| `--purge` | Delete the source folder once the copy is verified |
+| `-y` | Skip the "an agent may still be running" confirmation |
+
 ## Docker dev environments
 
 If a repo contains `.luv/settings.json` with a `compose_file` key, `luv` automatically starts a Docker Compose environment and runs Claude inside the `dev-environment` container.
@@ -156,7 +186,7 @@ The `dev-environment` service **must** have the selected agent CLI (`claude` or
 
 1. Detects `.luv/settings.json` with `compose_file` key
 2. Tears down any stale environment from a previous run
-3. Starts `docker compose up -d --build` with a unique project name (`luv-{repo}-{number}`) for network/volume isolation
+3. Starts `docker compose up -d --build` with a unique project name (`luv-{repo}-{machine}-{number}`) for network/volume isolation
 4. Verifies the `dev-environment` service is running
 5. Runs the selected agent inside the container via `docker compose exec`
 6. The repo is volume-mounted, so all file changes and git commits are visible on the host
@@ -178,8 +208,24 @@ luv continue                        # reattach exactly where you left off
 
 `luv` re-invokes itself on the remote over SSH, so every flag works there unchanged. The remote needs `luv`, `tmux`, `gh`, and `git` on its `PATH`.
 
+`luv ls` lists what is running on every host it knows about, not only the sessions this machine started — a session dispatched from your laptop shows up on your desktop, and `luv continue` and `luv rm` reach it from either.
+
 Use `--local` for a one-off local run, `-s HOST` to target a different machine, and `-i PATH` for a different SSH key.
 
+### Handing a session to another machine
+
+Start something on your laptop, then move it — workspace, uncommitted work, and the agent's conversation — to a machine that won't go to sleep:
+
+```bash
+luv --local myrepo "start something"   # working locally
+luv handover myrepo 43 --to box        # resumes mid-conversation on box
+luv handover myrepo 43 --to local      # ...and back again later
+```
+
+The whole folder crosses over, including untracked and gitignored files, so a workspace that ran before the move still runs after it. The agent's transcript moves too, so it picks up where it left off rather than starting fresh. Bytes are relayed through the machine you run the command on, so the two ends never need SSH access to each other.
+
+The source folder is left on disk (`--purge` deletes it), and the workspace keeps the name it was created with.
+
 Full guide, including how to prepare a fresh Ubuntu box and set up SSH keys: **[docs/remote-sessions.md](docs/remote-sessions.md)**.
 
 ## Workspace cleanup
@@ -201,8 +247,8 @@ delete, and never touches a workspace with a live session. `luv rm` is the
 opposite — you name what goes, and it goes, on whichever host it lives on.
 
 ```bash
-luv rm myrepo-42          # kill its tmux session, delete ~/prs/myrepo-42 on its host
-luv rm luv-myrepo-42      # the session name works too
+luv rm myrepo-mbp-42      # kill its tmux session, delete the folder on its host
+luv rm luv-myrepo-mbp-42  # the session name works too
 luv rm --merged           # every session whose PR has been merged
 luv rm --dead             # workspaces left behind by sessions that already exited
 luv rm --dead --host box  # scope either selector to one machine
@@ -217,9 +263,10 @@ registry as soon as its tmux session exits, but the clone it was working in
 stays on the remote disk. Those orphans are invisible to `luv ls` and are
 usually what is actually filling up the box.
 
-Only folders named `{repo}-{N}` are ever eligible — anything else in the
-workspace root is left alone, and a target that doesn't resolve to one is an
-error rather than an `rm -rf`.
+Only folders ending in `-{N}` are ever eligible — `{repo}-{machine}-{N}`, a
+`luv -l` copy `{repo}-{machine}-{N}_2`, and pre-slug `{repo}-{N}` alike.
+Anything else in the workspace root is left alone, and a target that doesn't
+resolve to one is an error rather than an `rm -rf`.
 
 ## Configuration
 

{luv_cli-0.2.1 → luv_cli-0.4.0}/docs/configuration.md

@@ -43,6 +43,28 @@ want for hosts, paths, and org names.
 The **laptop** resolves this before dispatching, so a remote machine never needs
 its own `org` configured.
 
+### `machine`
+
+*string, default: this machine's hostname.* A short name for **this** machine,
+used in the workspace folder (`myrepo-mbp-43`) and branch (`luv-mbp-43`) of
+everything created here.
+
+It exists because every machine works out the next workspace number from
+GitHub's issue counter independently, so a laptop and a box will happily pick
+the same one — and without the slug they would push the same branch. The value
+is lowercased, stripped to letters and digits, and capped at 8 characters, so
+`Niveds-MacBook.local` becomes `nivedsma`; set it explicitly for something
+readable:
+
+```bash
+luv config set machine mbp
+```
+
+The slug is stamped when a workspace is created and never changes afterwards —
+`luv handover` moves `myrepo-mbp-43` to another machine under that same name,
+because it records where the workspace came from and its branch may already be
+pushed. Workspaces created before slugs existed keep working.
+
 ### `prs_dir`
 
 *string, default `~/prs`.* Where workspace folders are created on **this**
@@ -107,6 +129,7 @@ those combinations contradict each other.
 ```json
 {
   "org": "exosphere",
+  "machine": "mbp",
   "prs_dir": "~/prs",
   "remote": {
     "host": "box",

{luv_cli-0.2.1 → luv_cli-0.4.0}/docs/remote-sessions.md

@@ -9,6 +9,7 @@ still up.
 - [Preparing a new remote machine (Ubuntu)](#preparing-a-new-remote-machine-ubuntu)
 - [Configuring luv](#configuring-luv)
 - [Daily use](#daily-use)
+- [Handing a session to another machine](#handing-a-session-to-another-machine)
 - [Session lifecycle](#session-lifecycle)
 - [Session naming and identity](#session-naming-and-identity)
 - [What runs where](#what-runs-where)
@@ -28,9 +29,9 @@ luv myrepo "fix the bug"
   └─ ssh -t box 'bash -lc "…"'  ────►  tmux new-session -A -s luv-pending-3f9a
                                          └─ luv exosphere/myrepo "fix the bug"
                                               ├─ gh api        → next number = 42
-                                              ├─ git clone     → ~/prs/myrepo-42
-                                              ├─ git checkout -b luv-42
-                                              ├─ tmux rename-session → luv-myrepo-42
+                                              ├─ git clone     → ~/prs/myrepo-box-42
+                                              ├─ git checkout -b luv-box-42
+                                              ├─ tmux rename-session → luv-myrepo-box-42
                                               └─ exec claude …
                                        (session keeps running after you disconnect)
 ```
@@ -210,19 +211,24 @@ On your laptop:
 luv config
 ```
 
-The wizard asks for the host, the SSH identity file, and the remote workspace
-directory, then offers to set your default GitHub org. It finishes by checking
-the remote for `tmux`, `luv`, `gh`, and `git` and telling you exactly what's
-missing.
+The wizard asks for this machine's name, the host, the SSH identity file, and
+the remote workspace directory, then offers to set your default GitHub org. It
+finishes by checking the remote for `tmux`, `luv`, `gh`, and `git` and telling
+you exactly what's missing.
 
 Non-interactively:
 
 ```bash
+luv config set machine mbp
 luv config set remote.host box
 luv config set remote.identity_file ~/.ssh/id_ed25519
 luv config list
 ```
 
+Setting `machine` on each machine you use is worth the ten seconds: it is the
+label that ends up in every workspace folder and branch name, and the hostname
+default is rarely the nicest one.
+
 Full key reference: [configuration.md](configuration.md).
 
 ## Daily use
@@ -233,7 +239,7 @@ about how you use luv changes:
 ```bash
 luv myrepo "fix the flaky test"     # new workspace on the remote
 luv myrepo 42 "keep going"          # reopen workspace 42 there
-luv ls                              # what's running, across all hosts
+luv ls                              # what's running, on every host, whoever started it
 luv continue                        # attach to a session
 luv continue myrepo                 # attach to the newest myrepo session
 luv continue myrepo 42              # attach to a specific workspace
@@ -250,36 +256,124 @@ luv -i ~/.ssh/other_key myrepo      # use a different key this once
 Detach from a session with `Ctrl-b d` (tmux's default prefix). The agent keeps
 running.
 
+## Handing a session to another machine
+
+`luv handover` relocates a running workspace. The usual direction is laptop →
+box: you start something locally, then decide it should keep running somewhere
+that doesn't sleep.
+
+```bash
+luv --local myrepo "start something"   # → ~/prs/myrepo-mbp-43, branch luv-mbp-43
+luv handover myrepo 43 --to box        # attaches to it, now running on box
+luv handover myrepo 43 --to local      # and back down again later
+```
+
+```
+                LAPTOP (the one you run the command on)
+                  │
+  ssh box tar -c ─┤─ ssh gpu tar -x        ← bytes are relayed through here, so
+                  │                          box and gpu need no keys for each other
+   BOX                                    GPU-BOX
+   tmux kill-session luv-myrepo-mbp-43
+   docker compose -p … down
+   ~/prs/myrepo-mbp-43   ───────────────► ~/prs/myrepo-mbp-43     (whole folder)
+   ~/.claude/projects/-home-u-prs-…  ───► ~/.claude/projects/…    (transcript)
+   (folder left in place)                 tmux new-session -A -s luv-myrepo-mbp-43
+                                            └─ luv exo/myrepo 43 -r → claude --resume
+```
+
+**Everything crosses over.** The folder is copied byte for byte — `.git`, staged
+and unstaged edits, untracked files, and gitignored ones like `.env` and
+`node_modules`. A workspace that ran before the move still runs after it.
+
+**So does the conversation.** Claude's transcript
+(`~/.claude/projects/<path-slug>/*.jsonl`) and Codex's rollouts
+(`~/.codex/sessions/**/rollout-*.jsonl`) travel with the workspace, and the
+absolute path recorded inside them is rewritten for the new machine — the two
+rarely agree on it. The destination then starts with `-r`, so `claude --resume`
+or `codex resume --last` continues the thread rather than opening a new one.
+This part depends on each agent's on-disk layout, so luv says what it found and
+carries on with a fresh conversation if it finds nothing; `--no-agent-state`
+skips it deliberately.
+
+**The agent is briefly down.** luv checks everything it can first — the
+destination is reachable, has luv, and has no folder in the way — then stops the
+agent, because copying a workspace out from under a running one is the only way
+to get a torn tree. Killing the tmux session SIGHUPs the pane, so luv also tears
+the Docker environment down explicitly rather than relying on the agent's exit.
+
+**Nothing is deleted.** The source folder stays on disk, so a failed transfer
+costs nothing: luv prints the command to restart the session where it was. Use
+`--purge` to delete it once the copy verifies, or `luv --clean` on that machine
+later.
+
+**The name doesn't change.** `myrepo-mbp-43` stays `myrepo-mbp-43` on the box —
+the slug records where a workspace came from, and its branch may already be
+pushed. That is also what makes the move safe: a workspace created on the box
+would be `myrepo-box-43`, so the two can sit side by side.
+
+Handover works on a workspace whose agent has already exited, too — name the
+machine with `--from` and luv will move the folder and start it fresh.
+
+| Flag | |
+|---|---|
+| `--to HOST` | Destination; `local` for the machine you're on. Required. |
+| `--from HOST` | Source, when luv's registry doesn't already know |
+| `--no-agent-state` | Move the workspace only |
+| `--no-attach` | Leave the new session detached |
+| `--purge` | Delete the source folder after the copy verifies |
+| `-f` | Replace an existing folder on the destination |
+| `-y` | Skip the "an agent may still be running" confirmation |
+
 ## Session lifecycle
 
 | Step | What happens |
 |---|---|
 | `luv myrepo "…"` | Laptop records a registry entry, opens SSH, creates the tmux session, remote luv clones and launches the agent |
 | `Ctrl-b d` or lost connection | tmux session keeps running; agent unaffected; Docker containers stay up |
-| `luv ls` | Laptop queries each host's tmux and refreshes the registry |
+| `luv ls` | Laptop queries every known host's tmux and refreshes the registry, adopting sessions another machine started |
 | `luv continue` | Reattaches; other clients are detached so the pane isn't size-clamped |
 | Agent exits | The pane's command ends, tmux session disappears, Docker environment is torn down, `luv ls` prunes the entry on its next run |
 
 ## Session naming and identity
 
-Sessions are named after the workspace folder: `~/prs/myrepo-42` becomes
-`luv-myrepo-42`. tmux forbids `.` and `:` in session names, so a repo like
-`foo.js` becomes `luv-foo_js-42`.
-
-When the workspace is already known — reopening by number, `-pr`, or `-l` — the
-laptop uses that name directly and `tmux new-session -A` doubles as "attach if
-it's already running".
-
-When it isn't known — a brand new workspace, or bare `-n`/`-r` — the laptop uses
-a placeholder `luv-pending-<id>` and the remote renames it once the clone lands.
+Workspace folders are `{repo}-{machine}-{number}` and branches
+`luv-{machine}-{number}`, where `{machine}` names whichever machine created the
+workspace (config key `machine`, defaulting to the hostname). Each machine works
+out the next number from GitHub's issue counter on its own, so without that slug
+a laptop and a box would routinely pick the same one and push the same branch.
+Folders and branches created before slugs existed keep working — luv looks for
+its own name first, then any other machine's, then the plain `{repo}-{number}`.
+
+`luv -l <PR URL>` clones into a folder of its own every time, so a second run on
+the same PR gets `{repo}-{machine}-{number}_2`, a third `_3`. The suffix is part
+of the number's segment, so those folders are still workspace `{number}`
+everywhere it matters — `luv ls`, `luv rm`, `--clean`, handover. Where a number
+has several copies, the newest wins: that is the one you just made.
+
+Sessions are named after the workspace folder: `~/prs/myrepo-box-42` becomes
+`luv-myrepo-box-42`. tmux forbids `.` and `:` in session names, so a repo like
+`foo.js` becomes `luv-foo_js-box-42`.
+
+When the workspace is already known — reopening by number, `-pr`, or `-l -r` —
+the laptop pins the session name down before dispatching, so `tmux new-session
+-A` doubles as "attach if it's already running". It can't compute that name,
+though, since the slug belongs to the machine holding the folder: it takes it
+from the session registry, or asks the host directly, and falls back to the
+`luv-pending-<id>` rename-on-arrival path if the host doesn't answer.
+
+When it isn't known — a brand new workspace, plain `luv -l` (whose folder the
+remote only picks once it sees what is already there), or bare `-n`/`-r` — the
+laptop uses a placeholder `luv-pending-<id>` and the remote renames it once the
+clone lands.
 If the target name is already taken by another live session, luv keeps the
-session under `luv-myrepo-42-2` and warns rather than failing.
+session under `luv-myrepo-box-42-2` and warns rather than failing.
 
 Each session also carries two tmux options, which is what `luv ls` reads:
 
 ```bash
-tmux show-options -t luv-myrepo-42 -v @luv_id
-tmux show-options -t luv-myrepo-42 -v @luv_workspace
+tmux show-options -t luv-myrepo-box-42 -v @luv_id
+tmux show-options -t luv-myrepo-box-42 -v @luv_workspace
 ```
 
 ## What runs where
@@ -288,6 +382,7 @@ tmux show-options -t luv-myrepo-42 -v @luv_workspace
 |---|---|---|
 | `luv config`, `luv --init` | Always local | – |
 | `luv ls`, `luv continue` | Local, queries remote over SSH | – |
+| `luv handover` | Local, drives both machines over SSH | starts one on the destination |
 | `luv <repo> [prompt]` | Remote | yes |
 | `luv <repo> <n>`, `-pr`, `-l` | Remote | yes |
 | `luv <repo> -n` / `-r` | Remote | yes |
@@ -304,7 +399,7 @@ invocation, `docker compose up` runs *inside* the pane:
 
 - Detaching leaves the containers running.
 - Teardown happens when the agent exits, not when your SSH client goes away.
-- The compose project name is still `luv-{repo}-{number}`, so two workspaces on
+- The compose project name is still `luv-{repo}-{machine}-{number}`, so two workspaces on
   the same repo don't collide.
 
 Install Docker on the remote and add your user to the `docker` group:
@@ -340,8 +435,10 @@ discards the command — so the prompt is dropped. luv prints a note when this c
 happen. Type the prompt into the running agent instead.
 
 **`luv ls` says a host is unreachable**
-It shows the last known state rather than pruning; nothing is lost. When a host
-is gone for good, `luv ls --prune` forgets its entries.
+It shows that host's last known state rather than pruning; nothing is lost. A
+configured host with no entries yet has no state to show, so it just says its
+sessions aren't listed. When a host is gone for good, `luv ls --prune` forgets
+its entries — and `luv config unset remote.hosts.<name>` stops the scan.
 
 **Junk like `35;22;1M` appears at my prompt after a dropped connection**
 
@@ -356,11 +453,29 @@ restores the terminal whatever happens to the connection. If you land in this
 state from something else, `reset` (or `stty sane` plus
 `printf '\033[?1003l\033[?1006l\033[?2004l'`) clears it.
 
+**Handover says the destination already has that folder**
+Something with the same name is already there — either the same workspace from
+an earlier handover, or one created on the machine that made this one. Look at
+it first (`ssh box ls ~/prs`), then either `luv --clean` it or pass `-f` to
+replace it.
+
+**After a handover the agent started a fresh conversation**
+luv prints a warning when it can't find a transcript for the workspace. The
+usual cause is the workspace having been opened under a different path than the
+one the agent recorded, or a Codex rollout stored somewhere other than
+`~/.codex/sessions`. The workspace itself is unaffected — the code, branch, and
+uncommitted work all moved.
+
+**Handover left the session down**
+The source folder is never deleted without `--purge`, so restart it where it
+was: `luv <repo> <n> -r -s <source-host>`. luv prints that exact command before
+it starts copying.
+
 **A session is wedged**
 
 ```bash
 ssh box tmux ls                          # see everything, not just luv's
-ssh box tmux kill-session -t luv-myrepo-42
+ssh box tmux kill-session -t luv-myrepo-box-42
 ```
 
 **I'm already inside tmux locally**