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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: luv-cli
-Version: 0.1.0
+Version: 0.2.1
 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
@@ -75,6 +75,10 @@ luv -r my-repo 42
 # Clean up fully-merged workspaces
 luv --clean
 
+# Tear down a finished session: kill its tmux, delete its workspace
+luv rm myrepo-42
+luv rm --merged        # everything whose PR has landed
+
 # See what's running on your remote machine, and reattach
 luv ls
 luv continue
@@ -99,8 +103,11 @@ 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]` | List live sessions across hosts |
+| `luv ls [--host H] [--prune] [--no-pr]` | List live sessions across hosts, with each one's PR link |
 | `luv continue [<repo> [number]]` | Attach to a live session |
+| `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 |
 | `luv [org/]<repo> [prompt...]` | Create a new workspace and launch Claude (default) |
 | `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 |
@@ -210,6 +217,33 @@ Use `luv --clean -f` to skip all safety checks and delete everything. Add `--saf
 
 Workspaces with a live tmux session are skipped unless you pass `-f`.
 
+### Removing a specific session
+
+`luv --clean` is a garbage collector: it decides for itself what is safe to
+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 --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
+```
+
+A named target is taken as intent and removed without further checks —
+including any uncommitted work in it. The `--merged` and `--dead` selectors
+list what they matched and ask first; `-f` skips that prompt.
+
+`--dead` is the counterpart to `luv ls`: reconciliation drops a session from the
+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`.
+
 ## Configuration
 
 Run `luv config` for interactive setup, or `luv --init` to set just your default GitHub org. Both save to `~/.luv/config.json`:

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

@@ -52,6 +52,10 @@ luv -r my-repo 42
 # Clean up fully-merged workspaces
 luv --clean
 
+# Tear down a finished session: kill its tmux, delete its workspace
+luv rm myrepo-42
+luv rm --merged        # everything whose PR has landed
+
 # See what's running on your remote machine, and reattach
 luv ls
 luv continue
@@ -76,8 +80,11 @@ 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]` | List live sessions across hosts |
+| `luv ls [--host H] [--prune] [--no-pr]` | List live sessions across hosts, with each one's PR link |
 | `luv continue [<repo> [number]]` | Attach to a live session |
+| `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 |
 | `luv [org/]<repo> [prompt...]` | Create a new workspace and launch Claude (default) |
 | `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 |
@@ -187,6 +194,33 @@ Use `luv --clean -f` to skip all safety checks and delete everything. Add `--saf
 
 Workspaces with a live tmux session are skipped unless you pass `-f`.
 
+### Removing a specific session
+
+`luv --clean` is a garbage collector: it decides for itself what is safe to
+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 --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
+```
+
+A named target is taken as intent and removed without further checks —
+including any uncommitted work in it. The `--merged` and `--dead` selectors
+list what they matched and ask first; `-f` skips that prompt.
+
+`--dead` is the counterpart to `luv ls`: reconciliation drops a session from the
+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`.
+
 ## Configuration
 
 Run `luv config` for interactive setup, or `luv --init` to set just your default GitHub org. Both save to `~/.luv/config.json`:

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

@@ -343,6 +343,19 @@ happen. Type the prompt into the running agent instead.
 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.
 
+**Junk like `35;22;1M` appears at my prompt after a dropped connection**
+
+That's mouse-tracking reports. The remote tmux/agent turned mouse tracking on
+in *your* terminal and, having been killed along with the connection, never
+turned it off — so every mouse move now types coordinates at your shell.
+Bracketed paste (`200~` around pastes), a missing cursor, and a stuck
+alternate screen come from the same cause.
+
+luv now cleans this up itself: it stays alive as the parent of `ssh` and
+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.
+
 **A session is wedged**
 
 ```bash

luv_cli-0.2.1/docs/sessions.md

@@ -0,0 +1,212 @@
+# The session registry
+
+`luv ls` needs to answer "what am I running, and where?" — including for hosts
+that are currently offline. It does that from `~/.luv/sessions.json`, a local
+cache of every session luv has started, reconciled against live tmux state on
+each run.
+
+## Why it exists
+
+The obvious approach — just ask each host `tmux ls` — has two gaps:
+
+1. **luv wouldn't know which hosts to ask.** Once you use `-s` for a second
+   machine, the config's default host is no longer the whole picture.
+2. **tmux doesn't remember why a session exists.** The prompt you started with,
+   the org, and the agent aren't tmux's business.
+
+There's also a sequencing problem. Your laptop can't know the workspace number
+in advance — it comes from `gh api` running *on the remote* — so at dispatch
+time there is nothing stable to record. luv solves that by generating a random
+token, writing it into the registry, and having the remote stamp it onto the
+tmux session as a `@luv_id` option. Matching happens on that token, so renaming
+the session (which luv does as soon as the clone lands) breaks nothing.
+
+## Schema
+
+```json
+{
+  "sessions": [
+    {
+      "id": "k3f9a2c1",
+      "host": "box",
+      "session": "luv-myrepo-42",
+      "org": "exosphere",
+      "repo": "myrepo",
+      "workspace": "myrepo-42",
+      "agent": "claude",
+      "prompt": "fix the flaky test",
+      "created": 1753401234,
+      "last_seen": 1753408899,
+      "pr_number": 42,
+      "pr_url": "https://github.com/exosphere/myrepo/pull/42",
+      "pr_state": "OPEN",
+      "pr_checked": 1753408899
+    }
+  ]
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `id` | Random 8-char token; matches the session's `@luv_id` tmux option |
+| `host` | The `remote.host` value used, or absent for a local session |
+| `session` | tmux session name; starts as `luv-pending-<id>` and is corrected on the first reconcile |
+| `org`, `repo` | GitHub owner and repo, resolved on the laptop |
+| `workspace` | Folder name (`myrepo-42`); `null` until the remote reports it |
+| `agent` | `claude` or `codex` |
+| `prompt` | The prompt you launched with, for the `luv ls` label |
+| `created` | Unix time the entry was written |
+| `last_seen` | Unix time of the last successful reconcile |
+| `pr_number`, `pr_url` | The session's pull request; `null` until one exists |
+| `pr_state` | `OPEN`, `CLOSED` or `MERGED` — what `luv rm --merged` selects on |
+| `pr_checked` | Unix time GitHub was last asked about it |
+| `pr_hint` | PR number known at dispatch (`-l` / `-pr` only); absent otherwise |
+
+`attached`, `activity`, and `live` are recomputed on every reconcile and are
+deliberately **not** written back to the file.
+
+## Reconciliation
+
+On `luv ls` and `luv continue`, luv groups entries by host and runs one query
+per host (concurrently when there's more than one):
+
+```
+tmux list-sessions -F '#{@luv_id}|#{session_name}|#{@luv_workspace}|#{session_attached}|#{session_activity}'
+```
+
+Each entry then lands in one of three states:
+
+| State | Condition | Effect |
+|---|---|---|
+| **live** | Host answered and a session matched | Entry refreshed: name, workspace, attached, activity, `last_seen` |
+| **dead** | Host answered and no session matched | Entry pruned |
+| **unreachable** | Host never answered | Entry kept as-is, shown with `?`, warning printed |
+
+Matching prefers `@luv_id` and falls back to the session name, which covers
+sessions created before the option was stamped.
+
+**An unreachable host never causes pruning.** This is the rule the whole design
+protects: running `luv ls` on a plane, or while a box is rebooting, must not
+silently erase your session list. luv distinguishes the two cases by ssh's own
+exit code — 255 means ssh failed to connect, anything else means the host
+answered (an empty result from a host with no tmux server is a legitimate
+"nothing is running here").
+
+To forget a host you've genuinely retired:
+
+```bash
+luv ls --prune
+```
+
+That drops entries for hosts that didn't answer, in addition to the dead ones
+reconciliation already removed.
+
+## PR links
+
+Every luv workspace is one pull request by construction — folder `{repo}-{N}`,
+branch `luv-{N}` — so `luv ls` can show the PR each session is producing:
+
+```
+HOST  SESSION         WORKSPACE   AGENT   ATTACHED  ACTIVE  PR    PROMPT
+box   luv-myrepo-42   myrepo-42   claude  yes       2m ago  #42   fix the flaky test
+box   luv-myrepo-51   myrepo-51   codex   no        1h ago  -     add rate limiting
+```
+
+`#42` is an OSC 8 terminal hyperlink, so ctrl/cmd-click opens the PR. When
+stdout isn't a terminal there's nothing to click and a bare number would be
+useless, so `luv ls | grep` and redirects get the full URL instead.
+
+The lookup asks GitHub for the PR whose head branch is `luv-{N}`:
+
+```
+gh pr list --repo {org}/{repo} --head luv-{N} --state all --limit 1 --json number,url
+```
+
+`gh pr list` rather than the REST endpoint because its `--head` takes a bare
+branch name. REST wants `head={owner}:{branch}`, and the owner luv recorded is
+whatever you typed — which stops matching the moment the org is renamed or the
+repo is transferred.
+
+It is a head query and nothing else. Checking whether PR `#N` merely *exists*
+would show a stranger's PR whenever someone took that number between luv
+reserving the folder and the agent pushing — the folder number is only ever the
+*intended* PR number. Sessions started from an existing PR (`luv -l <url>`,
+`luv <repo> -pr <N>`) are the exception: there the number is known at dispatch
+and stored as `pr_hint`, so they resolve with no network call at all. Their
+branch is the PR's own head ref, which the head query would never match.
+
+Results are cached in the registry so repeat runs are instant and a link stays
+on screen when GitHub is unreachable — 5 minutes for a PR that was found, 1
+minute when there wasn't one yet (the agent may open it any moment). A session
+with no PR, no org, or a folder that isn't `{repo}-{N}` shows `-`.
+
+`luv ls --no-pr` skips the whole thing for a fast, offline-safe listing, which
+is also what happens automatically when `gh` isn't installed. `luv continue`
+renders the cached links but never triggers a lookup of its own.
+
+## Removing sessions
+
+`luv rm` is the teardown counterpart to `luv ls`: it kills the tmux session and
+deletes the workspace folder on whichever host the session lives on, then drops
+the registry entry.
+
+```bash
+luv rm myrepo-42          # by workspace, or by session name
+luv rm --merged           # every session whose PR state is MERGED
+luv rm --dead             # workspaces on a host with no live luv session
+luv rm --dead --host box  # scope either selector to one machine
+```
+
+`--merged` reads the `pr_state` the PR lookup already caches, so "clean up
+what's landed" costs nothing beyond what `luv ls` was doing anyway.
+
+`--dead` exists because **reconciliation removes a registry entry the moment its
+tmux session dies, but nothing removes the clone**. Those folders are invisible
+to `luv ls` — the registry has already forgotten them — and they are usually
+what is actually consuming the remote's disk. Finding them means asking the host
+directly: `ls -1` the workspace root, `tmux list-sessions`, and take the
+difference.
+
+That same asymmetry is why a named target falls back to a folder scan. A session
+you have just finished with is exactly one whose entry reconciliation has
+already dropped, so looking only in the registry would fail for the most common
+case.
+
+Two things bound the damage:
+
+- Only names matching `{repo}-{N}` are eligible, checked again immediately
+  before the `rm -rf` rather than only at selection time. A stray directory in
+  the workspace root is never a candidate, and a target that resolves to one is
+  an error, not a deletion.
+- A named target is its own confirmation, but `--merged` and `--dead` print what
+  they matched and ask, because a selector can sweep up folders on a machine you
+  are not looking at. `-f` skips the prompt.
+
+A failed delete — unreachable host, permissions — leaves the registry entry in
+place, so the session doesn't silently disappear from `luv ls` while its files
+are still on disk.
+
+## Concurrency
+
+Both dispatch (append an entry) and `ls` (prune entries) are read-modify-write,
+which an atomic file replace alone doesn't protect — two luv invocations at once
+would lose one entry. luv takes a lock at `~/.luv/sessions.lock` around the
+whole cycle, using `O_CREAT | O_EXCL`.
+
+A lock older than the timeout is assumed to belong to a killed process and is
+broken. If the lock still can't be taken, luv proceeds **without** it: losing a
+registry entry is a far better outcome than refusing to launch an agent.
+
+## Recovery
+
+The registry is a cache. Deleting it is safe:
+
+```bash
+rm ~/.luv/sessions.json
+```
+
+You lose the metadata luv can't recover — the prompt text, and which hosts to
+look at — but no sessions. They're still running; find them with
+`ssh <host> tmux ls` and reattach with `tmux attach -t <name>`.
+
+A corrupt or unparseable file is treated as empty rather than crashing.