luv-cli 0.5.0__tar.gz → 0.6.0__tar.gz

luv_cli-0.6.0/.failproofai/policies/version-policies.mjs

@@ -0,0 +1,107 @@
+/**
+ * version-policies.mjs — remind the agent to bump the release version.
+ *
+ * Auto-loaded by failproofai from .failproofai/policies/ — no install step.
+ *
+ * Publishing here is driven by the version in the manifest: a push to main
+ * whose version has no tag yet releases itself (.github/workflows/publish.yml).
+ * So a branch that changes the tool and forgets the version merges into a main
+ * that publishes nothing, and the change sits unreleased until someone notices.
+ *
+ * So this says so on `git commit`, and only while the branch's version still
+ * matches the base branch's — it is context, not a block, and bumping the
+ * version is what turns it off for the rest of the branch.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { customPolicies, allow, instruct } from "failproofai";
+
+// First match wins, so the order is "most likely to be the release manifest".
+const MANIFESTS = [
+  { file: "pyproject.toml", re: /^\s*version\s*=\s*["']([^"']+)["']/m },
+  { file: "package.json", re: /"version"\s*:\s*"([^"]+)"/ },
+  { file: "Cargo.toml", re: /^\s*version\s*=\s*["']([^"']+)["']/m },
+];
+
+const BASE_REFS = ["origin/main", "main", "origin/master", "master"];
+
+// A `git … commit` that starts a command, so a shell segment is allowed to
+// carry flags and their values (`git -C dir commit`) but a `commit` merely
+// spoken about (`echo "run git commit later"`) is not mistaken for one.
+const GIT_COMMIT = /(?:^|[;&|\n(]|&&|\|\|)\s*(?:\w+=\S+\s+)*git\b[^;&|\n]*?\bcommit\b/;
+
+/** git, or null on any failure — this policy never gets in the way. */
+function git(cwd, args) {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function versionIn(text, re) {
+  const m = text == null ? null : text.match(re);
+  return m ? m[1] : null;
+}
+
+/** The manifest this repo releases from, with the version on both sides. */
+function releaseVersions(cwd) {
+  const base = BASE_REFS.find((ref) =>
+    git(cwd, ["rev-parse", "--verify", "--quiet", ref]) !== null);
+  if (!base) return null;
+
+  for (const { file, re } of MANIFESTS) {
+    if (!existsSync(join(cwd, file))) continue;
+    let head;
+    try {
+      head = versionIn(readFileSync(join(cwd, file), "utf8"), re);
+    } catch {
+      return null;
+    }
+    // No version on the base side means the manifest is new on this branch;
+    // there is nothing to bump relative to.
+    const baseVersion = versionIn(git(cwd, ["show", `${base}:${file}`]), re);
+    if (!head || !baseVersion) return null;
+    return { file, base, head, baseVersion };
+  }
+  return null;
+}
+
+customPolicies.add({
+  name: "remind-version-bump-on-commit",
+  description: "On git commit, remind that the release version is still the base branch's",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (!GIT_COMMIT.test(cmd)) return allow();
+
+    const cwd = ctx.session?.cwd ?? process.cwd();
+
+    // Committing on the base branch is a different problem, and one the
+    // block-work-on-main policy already has an opinion about.
+    const branch = git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    if (branch === null || branch === "main" || branch === "master") return allow();
+
+    const found = releaseVersions(cwd);
+    if (!found) return allow();
+    if (found.head !== found.baseVersion) return allow(); // already bumped
+
+    return instruct(
+      `${found.file} still says version ${found.head}, the same as ${found.base}. ` +
+      "Releases are cut from that version when this branch lands, so a merge " +
+      "with it unchanged publishes nothing. Bump it in this branch — patch for " +
+      "a fix or polish, minor for a feature — unless the change is docs, tests, " +
+      "or CI only, in which case say so and carry on."
+    );
+  },
+});
+
+export { customPolicies };

luv_cli-0.6.0/.github/workflows/publish.yml

@@ -0,0 +1,117 @@
+name: Publish to PyPI
+
+# Two ways in.
+#
+#   * A push to main publishes when the version in pyproject.toml is one no tag
+#     exists for yet. That is what makes a merged version bump release itself.
+#   * A v* tag publishes whatever it points at, kept so a release can still be
+#     cut by hand.
+#
+# The tag is created here rather than by a separate workflow because a tag
+# pushed with GITHUB_TOKEN does not trigger other workflows — GitHub's recursion
+# guard. Tagging elsewhere and relying on the v* trigger to fire would leave the
+# tag in place and nothing published, which is the worst of both.
+#
+# Deliberately no `paths:` filter. It would be evaluated for tag pushes as well,
+# so `paths: [pyproject.toml]` would silently drop a hand-pushed tag whose commit
+# did not happen to touch that file. The "is this already tagged" check below is
+# the real guard; a filter would only be an optimisation, and a lossy one.
+
+on:
+  push:
+    tags:
+      - "v*"
+    branches:
+      - main
+
+concurrency:
+  group: publish
+  cancel-in-progress: false
+
+jobs:
+  decide:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      publish: ${{ steps.resolve.outputs.publish }}
+      version: ${{ steps.resolve.outputs.version }}
+      needs_tag: ${{ steps.resolve.outputs.needs_tag }}
+    steps:
+      # Its own job so the pypi environment — which may require a reviewer — is
+      # never entered by a run that turns out to have nothing to publish.
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # tags, so the guard below can see them
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Work out whether there is a release to make
+        id: resolve
+        run: |
+          set -euo pipefail
+
+          if [ "${GITHUB_REF_TYPE}" = "tag" ]; then
+            version="${GITHUB_REF_NAME#v}"
+            needs_tag=false
+          else
+            version="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+            needs_tag=true
+          fi
+
+          if [ -z "${version}" ]; then
+            echo "could not determine a version to publish" >&2
+            exit 1
+          fi
+
+          if [ "${needs_tag}" = true ] && git rev-parse -q --verify "refs/tags/v${version}" >/dev/null; then
+            echo "v${version} is already tagged — nothing to release"
+            echo "publish=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "releasing ${version}"
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+          echo "needs_tag=${needs_tag}" >> "$GITHUB_OUTPUT"
+          echo "publish=true" >> "$GITHUB_OUTPUT"
+
+  publish:
+    needs: decide
+    if: needs.decide.outputs.publish == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: write # push the tag a merged version bump implies
+      id-token: write # PyPI trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # Before the build, so a tag that cannot be pushed — protected tags, say —
+      # fails the run rather than publishing a version with no tag to show for it.
+      - name: Tag the release
+        if: needs.decide.outputs.needs_tag == 'true'
+        env:
+          VERSION: ${{ needs.decide.outputs.version }}
+        run: |
+          set -euo pipefail
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "v${VERSION}" -m "v${VERSION}"
+          git push origin "v${VERSION}"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

{luv_cli-0.5.0 → luv_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: luv-cli
-Version: 0.5.0
+Version: 0.6.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
@@ -169,6 +169,32 @@ Handover flags:
 | `--purge` | Delete the source folder once the copy is verified |
 | `-y` | Skip the "an agent may still be running" confirmation |
 
+## The session's environment
+
+A session luv starts for you — a remote dispatch, a handover, a detached start
+— is exec'd by tmux or ssh with no shell in between, so it never sources
+`~/.bashrc` or `~/.zshrc` and would otherwise run with whatever environment the
+tmux server happened to start with. luv asks your login shell (`$SHELL -lic`)
+for its environment and fills in the gaps before cloning or launching anything,
+so the agent gets the API keys and the `PATH` you'd have in a terminal there.
+
+Precedence, highest first:
+
+1. Anything already set — `FOO=bar luv …`, or `-e` — is a decision about *this*
+   session and is never overwritten.
+2. Your rc's exports fill in the rest. `PATH` is merged instead of replaced:
+   entries the rc adds (nvm, pyenv, `~/.local/bin`) are appended after the ones
+   already there.
+
+The probe runs on the machine the session runs on, so a remote session picks up
+the *remote* user's rc. It is skipped when you run `luv` yourself — that
+process already inherited your shell — and can be turned off entirely with
+`luv config set shell_env false`. An rc that hangs is given 15 seconds and then
+ignored.
+
+Docker sessions are the exception: the container has its own environment, and
+only `-e` crosses into it (see below).
+
 ## 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.

{luv_cli-0.5.0 → luv_cli-0.6.0}/README.md

@@ -146,6 +146,32 @@ Handover flags:
 | `--purge` | Delete the source folder once the copy is verified |
 | `-y` | Skip the "an agent may still be running" confirmation |
 
+## The session's environment
+
+A session luv starts for you — a remote dispatch, a handover, a detached start
+— is exec'd by tmux or ssh with no shell in between, so it never sources
+`~/.bashrc` or `~/.zshrc` and would otherwise run with whatever environment the
+tmux server happened to start with. luv asks your login shell (`$SHELL -lic`)
+for its environment and fills in the gaps before cloning or launching anything,
+so the agent gets the API keys and the `PATH` you'd have in a terminal there.
+
+Precedence, highest first:
+
+1. Anything already set — `FOO=bar luv …`, or `-e` — is a decision about *this*
+   session and is never overwritten.
+2. Your rc's exports fill in the rest. `PATH` is merged instead of replaced:
+   entries the rc adds (nvm, pyenv, `~/.local/bin`) are appended after the ones
+   already there.
+
+The probe runs on the machine the session runs on, so a remote session picks up
+the *remote* user's rc. It is skipped when you run `luv` yourself — that
+process already inherited your shell — and can be turned off entirely with
+`luv config set shell_env false`. An rc that hangs is given 15 seconds and then
+ignored.
+
+Docker sessions are the exception: the container has its own environment, and
+only `-e` crosses into it (see below).
+
 ## 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.

{luv_cli-0.5.0 → luv_cli-0.6.0}/docs/configuration.md

@@ -70,6 +70,35 @@ pushed. Workspaces created before slugs existed keep working.
 *string, default `~/prs`.* Where workspace folders are created on **this**
 machine. `~` is expanded.
 
+### `shell_env`
+
+*boolean, default `true`.* Whether a session luv starts should inherit your
+shell's environment.
+
+tmux and ssh exec their command directly, so a remote dispatch, a handover, or
+a detached start never sources `~/.bashrc` or `~/.zshrc` — it runs with the
+environment the tmux server was started with, frozen at whenever that server
+first came up. Anything you export from your rc (the API key an agent
+authenticates with, the `PATH` entry that makes `codex` resolvable) is simply
+absent, and only for the sessions luv started for you.
+
+With this on, luv runs `$SHELL -lic` on the machine the session runs on and
+fills in what's missing before it clones or launches anything. Values already
+set win, so `FOO=bar luv …` and `-e` still decide; `PATH` is merged rather than
+replaced, with the rc's entries appended. An rc that never returns is abandoned
+after 15 seconds.
+
+Set it to `false` if your rc is slow, or if you want sessions to see only what
+you pass them explicitly:
+
+```bash
+luv config set shell_env false
+```
+
+This is read on the machine the session runs on, so a remote host can opt out
+independently of your laptop. It does not apply to Docker sessions — the
+container has its own environment, and only `-e` crosses into it.
+
 ### `remote.host`
 
 *string.* SSH destination — an `~/.ssh/config` alias (`box`), a `user@host`, or

{luv_cli-0.5.0 → luv_cli-0.6.0}/docs/remote-sessions.md

@@ -256,6 +256,19 @@ 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.
 
+When a session ends on its own — the connection drops, ssh is killed, the pane
+dies — luv prints the way back in, already filled in for that session:
+
+```
+luv: session ended unexpectedly — continue it with:
+
+    luv continue myrepo 42
+```
+
+Copy that line and run it. If the agent took the tmux session down with it,
+there is nothing left to attach to; `luv continue` says so and hands you
+`luv myrepo 42 -r`, which reopens the workspace and resumes the conversation.
+
 ## Reaching servers the agent started
 
 An agent working on the remote starts servers there — a dev server, a compose
@@ -409,7 +422,7 @@ machine with `--from` and luv will move the folder and start it fresh.
 | 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 |
+| `Ctrl-b d` or lost connection | tmux session keeps running; agent unaffected; Docker containers stay up. A connection that broke leaves the exact `luv continue <repo> <n>` for it in your terminal |
 | `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 |
@@ -508,6 +521,19 @@ The key isn't installed or isn't being offered. Test with `ssh -v box`. Check
 `gh` is authenticated on your laptop but not on the remote. luv numbers
 workspaces with `gh api` *on the remote*, so it needs its own login there.
 
+**The agent can't find an API key / a tool it needs is missing**
+Sessions inherit your rc: before cloning or launching, luv asks the remote's
+login shell (`$SHELL -lic`) for its environment and fills in whatever tmux
+didn't pass on, `PATH` included. So this means the var isn't exported by the
+*remote* user's `~/.bashrc`/`~/.zshrc` — check with
+`ssh box 'zsh -lic "printenv | cut -d= -f1"'` — or that the rc takes longer than
+15 seconds, or that `shell_env` is `false` there. `-e` with a `LUV_`-prefixed
+variable forwards one from your laptop regardless. See
+[configuration.md](configuration.md#shell_env).
+
+Note that this happens *inside* the remote luv, so it can't help ssh find `luv`
+itself — that's the `PATH` problem above.
+
 **My prompt didn't get sent**
 Reopening a workspace that already has a live session attaches to it, and tmux
 discards the command — so the prompt is dropped. luv prints a note when this can

{luv_cli-0.5.0 → luv_cli-0.6.0}/luv/__init__.py

@@ -57,13 +57,13 @@ def die(msg: str) -> None:
     sys.exit(1)
 
 
-def run(cmd: list[str], *, cwd: str | None = None,
-        timeout: float | None = None) -> subprocess.CompletedProcess:
+def run(cmd: list[str], *, cwd: str | None = None, timeout: float | None = None,
+        stdin: int | None = None) -> subprocess.CompletedProcess:
     """Capture a subprocess. A timeout surfaces as a failure, not an exception,
     so callers keep their plain returncode checks."""
     try:
         return subprocess.run(cmd, capture_output=True, text=True, cwd=cwd,
-                              timeout=timeout)
+                              timeout=timeout, stdin=stdin)
     except subprocess.TimeoutExpired:
         return subprocess.CompletedProcess(cmd, 124, "", f"timed out after {timeout}s")
 
@@ -743,6 +743,84 @@ def collect_luv_env() -> dict[str, str]:
     return result
 
 
+# An rc file is a program, and some of them never finish: one that starts tmux,
+# or waits on a prompt, would otherwise hang every session start.
+SHELL_ENV_TIMEOUT = 15
+
+# Vars that describe the shell we just ran rather than the setup we asked it
+# about. Importing them would tell the agent it is somewhere it is not.
+SHELL_ENV_SKIP = {"_", "OLDPWD", "PWD", "SHLVL"}
+
+
+def shell_env() -> dict[str, str]:
+    """Everything the user's login+interactive shell exports.
+
+    tmux and ssh exec their command directly, with no shell in between, so a
+    session luv started — a remote dispatch, a handover, a detached start —
+    never sources ~/.bashrc or ~/.zshrc. It runs with whatever environment the
+    tmux server was started with, frozen at whenever that server first came up.
+    The API key an agent authenticates with and the PATH entry that makes
+    'codex' resolvable both live in the rc, and both go missing.
+
+    Asking $SHELL for its own environment is the only way to get them back: rc
+    files are code, not data, and there is no reading them from outside. -l
+    covers the profile files, -i the rc files; between them they reach where
+    bash and zsh users actually put their exports.
+    """
+    shell = os.environ.get("SHELL") or "/bin/bash"
+    marker = "__luv_env__"
+    code = ("import json,os,sys;"
+            f"sys.stdout.write({marker!r} + json.dumps(dict(os.environ)))")
+    probe = f"{shlex.quote(sys.executable)} -c {shlex.quote(code)}"
+    # DEVNULL because an interactive shell sharing our tty would fight the
+    # agent for it, and lose to SIGTTOU rather than to the timeout.
+    r = run([shell, "-lic", probe], timeout=SHELL_ENV_TIMEOUT,
+            stdin=subprocess.DEVNULL)
+    # Match on the marker, not the exit status: rc files greet, warn, and fail
+    # in ways that say nothing about whether the environment came back. What
+    # precedes the marker is the greeting; raw_decode drops anything an exit
+    # hook prints after it.
+    if marker not in r.stdout:
+        return {}
+    try:
+        env, _ = json.JSONDecoder().raw_decode(r.stdout.split(marker, 1)[1].lstrip())
+    except ValueError:
+        return {}
+    return {k: v for k, v in env.items() if isinstance(v, str)}
+
+
+def merged_path(current: str, from_rc: str) -> str:
+    """`current` first, then whatever the rc adds. PATH order is a precedence
+    list, so the binaries that got us this far keep winning."""
+    entries = [p for p in current.split(os.pathsep) if p]
+    entries += [p for p in from_rc.split(os.pathsep) if p and p not in entries]
+    return os.pathsep.join(entries)
+
+
+def apply_shell_env() -> None:
+    """Fill this process's environment in from the user's shell.
+
+    Only for the luv that tmux or ssh started (_LUV_INNER). A luv you ran
+    yourself already inherited the shell it ran in; re-deriving it there would
+    charge every session start for an rc that has already run.
+
+    What is already set wins. 'FOO=bar luv …' and -e are statements about this
+    session, while the rc is the background default, and a session that quietly
+    overrode the value you handed it would be worse than one missing it. PATH
+    is the exception, being a list rather than a value: the rc's entries are
+    appended, which is how nvm's node and ~/.local/bin become findable.
+    """
+    if not os.environ.get("_LUV_INNER") or load_config().get("shell_env") is False:
+        return
+    for key, value in shell_env().items():
+        if key in SHELL_ENV_SKIP:
+            continue
+        if key == "PATH":
+            os.environ["PATH"] = merged_path(os.environ.get("PATH", ""), value)
+        elif key not in os.environ:
+            os.environ[key] = value
+
+
 def docker_env_flags(env_vars: dict[str, str]) -> list[str]:
     """Convert env dict to docker compose exec -e flags."""
     flags: list[str] = []
@@ -1585,7 +1663,36 @@ def terminal_guard():
                 os.write(fd, TERM_RESET.encode())
 
 
-def hand_over(argv: list[str], *, restore: bool = True, watch=None) -> None:
+def continue_hint(repo: str | None, workspace: str | None = None) -> str:
+    """The 'luv continue …' line to hand back when a session breaks.
+
+    As narrow as what we actually know, and no narrower: the number is read off
+    the workspace folder, which a session dispatched before the remote picked
+    one doesn't have yet. Every shorter form is still a command that works —
+    a repo alone takes its newest session, and bare 'luv continue' asks.
+    """
+    parts = ["luv", "continue"]
+    if repo:
+        parts.append(repo)
+        number = workspace_number(repo, workspace or "")
+        if number is not None:
+            parts.append(str(number))
+    return " ".join(parts)
+
+
+def reopen_hint(args: list[str]) -> str:
+    """The 'luv <repo> [n] -r' line for a session whose tmux is already gone.
+
+    Takes the same [<repo> [number]] grammar 'luv continue' does, so whatever
+    was just typed carries straight over to the command that still works.
+    """
+    repo = args[0].rstrip("/").rsplit("/", 1)[-1]
+    number = args[1] if len(args) > 1 and args[1].isdigit() else None
+    return " ".join(["luv", repo] + ([number] if number else []) + ["-r"])
+
+
+def hand_over(argv: list[str], *, restore: bool = True, watch=None,
+              hint: str | None = None) -> None:
     """Give the terminal to a child and exit with its status. Never returns.
 
     Without `restore` this is a plain execv, which is the better deal when
@@ -1604,6 +1711,12 @@ def hand_over(argv: list[str], *, restore: bool = True, watch=None) -> None:
     the agent starts ten minutes in. It runs on a daemon thread and touches
     neither the terminal nor termios — this path is the one that has to stay
     boring.
+
+    `hint` is the way back in, printed when the child exits badly. A clean exit
+    is either a detach or the agent finishing, and neither wants advice; a bad
+    one is usually ssh losing the connection out from under a session that is
+    still running on the other side, and the terminal it lands back in should
+    not have to be told twice how to get there.
     """
     if not restore:
         os.execv(argv[0], argv)
@@ -1620,19 +1733,25 @@ def hand_over(argv: list[str], *, restore: bool = True, watch=None) -> None:
                     # The child got this same Ctrl-C from the tty and decides
                     # for itself what to do with it; outliving it is the point.
                     continue
+        if code != 0 and hint:
+            # After the guard, not inside it: a terminal still in the remote
+            # program's modes is no place to print something to be copied.
+            print(f"\nluv: session ended unexpectedly — continue it with:\n\n"
+                  f"    {hint}\n", file=sys.stderr)
         sys.exit(code)
 
 
-def exec_ssh(hc: dict, remote_cmd: str, *, tty: bool = True, watch=None) -> None:
+def exec_ssh(hc: dict, remote_cmd: str, *, tty: bool = True, watch=None,
+             hint: str | None = None) -> None:
     """Hand the terminal to ssh. Never returns."""
     ssh_bin = shutil.which("ssh")
     if not ssh_bin:
         die("'ssh' not found in PATH")
     argv = ssh_base(hc, tty=tty) + [remote_shell(remote_cmd)]
-    hand_over([ssh_bin] + argv[1:], restore=tty, watch=watch)
+    hand_over([ssh_bin] + argv[1:], restore=tty, watch=watch, hint=hint)
 
 
-def attach_session(hc: dict | None, name: str) -> None:
+def attach_session(hc: dict | None, name: str, *, hint: str | None = None) -> None:
     """Attach to a tmux session, locally or over ssh. Never returns.
 
     -d detaches other clients so the pane isn't size-clamped to a stale window
@@ -1642,11 +1761,11 @@ def attach_session(hc: dict | None, name: str) -> None:
         tmux_bin = shutil.which("tmux")
         if not tmux_bin:
             die("'tmux' not found in PATH")
-        hand_over([tmux_bin, "attach", "-d", "-t", name])
+        hand_over([tmux_bin, "attach", "-d", "-t", name], hint=hint)
         return
     print(f"luv: attaching {name} on {hc['host']}")
     exec_ssh(hc, shlex.join(["tmux", "attach", "-d", "-t", name]),
-             watch=port_watch(hc, session=name))
+             watch=port_watch(hc, session=name), hint=hint)
 
 
 def remote_prompt(args: list[str]) -> str | None:
@@ -1758,14 +1877,18 @@ def dispatch_remote(hc: dict, remote_args: list[str], *, workspace: str | None =
         record_session({**meta, "id": sid, "host": hc["host"], "session": session,
                         "workspace": workspace, "created": int(time.time())})
 
+    # Only a tmux session is there to come back to; -nit and --clean run to
+    # completion over ssh and have nothing to continue.
+    hint = continue_hint((meta or {}).get("repo"), workspace) if use_tmux else None
     print(f"luv: {hc['host']} — {session or 'no tmux'}")
     if detach:
         r = run(ssh_base(hc, batch=True) + [remote_shell(cmd)])
         if r.returncode != 0:
             die(f"could not start {session} on {hc['host']}: {r.stderr.strip()}")
-        print(f"luv: started detached — 'luv continue' to attach")
+        print(f"luv: started detached — attach with: {hint or 'luv continue'}")
         return
-    exec_ssh(hc, cmd, tty=tty, watch=port_watch(hc, sid=sid, session=session))
+    exec_ssh(hc, cmd, tty=tty, watch=port_watch(hc, sid=sid, session=session),
+             hint=hint)
 
 
 def cmd_paths() -> None:
@@ -3145,14 +3268,21 @@ def cmd_continue(args: list[str], identity: str | None = None) -> None:
     live, label = filter_sessions([s for s in sessions if s.get("live")], args)
 
     if not live:
-        die(f"no live luv sessions{label}")
+        # This is where a hint printed after a crash lands when the agent took
+        # the tmux session down with it, so send it on rather than stopping at
+        # the bad news: the workspace outlives the session, and -r reopens it.
+        named = bool(args) and not args[0].startswith("-")
+        die(f"no live luv sessions{label}"
+            + (f" — if its workspace is still there: {reopen_hint(args)}"
+               if named else ""))
     live.sort(key=session_sort_key, reverse=True)
 
     # An explicit repo means "the newest one for it".
     target = live[0] if (len(live) == 1 or args) else choose_session(live)
 
     host = target.get("host")
-    attach_session(resolve_host(host, identity) if host else None, target["session"])
+    attach_session(resolve_host(host, identity) if host else None, target["session"],
+                   hint=continue_hint(target.get("repo"), target.get("workspace")))
 
 
 def start_local_session(workspace: str, luv_args: list[str], meta: dict,
@@ -3170,13 +3300,14 @@ def start_local_session(workspace: str, luv_args: list[str], meta: dict,
              shutil.which("luv") or "luv"] + luv_args
     argv = [tmux_bin, "new-session"] + ([] if attach else ["-d"]) + \
            ["-A", "-s", session, "--"] + inner
+    hint = continue_hint(meta.get("repo"), workspace)
     print(f"luv: local — {session}")
     if attach:
-        os.execv(tmux_bin, argv)
+        hand_over(argv, hint=hint)
     r = subprocess.run(argv)
     if r.returncode != 0:
         die(f"could not start {session}")
-    print("luv: started detached — 'luv continue' to attach")
+    print(f"luv: started detached — attach with: {hint}")
 
 
 def workspace_origin(hc: dict | None, ws: Path) -> tuple[str, str] | None:
@@ -3404,6 +3535,11 @@ def main() -> None:
         die("--local cannot be combined with -s or -i")
 
     args = [a for a in args if a not in ("-n", "-r", "-e", "-f", "--force", "-p", "-nit", "--safe", "--claude", "--codex", "--local", "--no-agent-state", "--no-attach", "--purge", "-y")]
+
+    # Before anything shells out: the clone needs gh and git on PATH as much as
+    # the agent needs its credentials, and both come from the same rc. Ahead of
+    # collect_luv_env() too, so a LUV_* exported there is one -e can forward.
+    apply_shell_env()
     extra_env = collect_luv_env() if env_mode else {}
 
     # _LUV_INNER marks the remote-side luv: it must never dispatch onward.
@@ -3471,7 +3607,8 @@ Remote:
   Once 'luv config' has a remote host, every workspace command runs there inside
   a tmux session that survives disconnects. 'luv ls' shows what is running on
   every host — including sessions started from another machine — and
-  'luv continue' reattaches. Use --local for a one-off local run.
+  'luv continue' reattaches. A session that ends badly prints the exact
+  'luv continue <repo> <n>' for itself. Use --local for a one-off local run.
   'luv handover' moves a running session — workspace, uncommitted work, and the
   agent's conversation — to another machine, then resumes it there.
   Requires luv, tmux, gh and git on the remote. See docs/remote-sessions.md.

{luv_cli-0.5.0 → luv_cli-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "luv-cli"
-version = "0.5.0"
+version = "0.6.0"
 description = "Launch Claude Code or Codex agents on GitHub repos with isolated workspaces and optional Docker dev environments"
 requires-python = ">=3.10"
 license = "MIT"

{luv_cli-0.5.0 → luv_cli-0.6.0}/tests/test_agents.py

@@ -387,6 +387,142 @@ class TerminalRestoreTests(unittest.TestCase):
         self.assertNotEqual(hand_over.call_args.kwargs.get("restore"), False)
 
 
+class _OrderedStderr(io.StringIO):
+    """A stderr that notes where its first write falls in a sequence."""
+
+    def __init__(self, order):
+        super().__init__()
+        self.order = order
+
+    def write(self, s):
+        if s.strip() and "hint" not in self.order:
+            self.order.append("hint")
+        return super().write(s)
+
+
+class ContinueHintTests(unittest.TestCase):
+    """A session that breaks must say how to get back into it, in one line
+    that can be copied off the terminal and run as-is."""
+
+    FD = TerminalRestoreTests.FD
+    SAVED = TerminalRestoreTests.SAVED
+    HINT = "luv continue myrepo 42"
+
+    def _hand_over(self, stderr, **kwargs):
+        """Run hand_over over a fake child, with the terminal all stubbed out."""
+        with (patch.object(luv, "terminal_fd", return_value=self.FD),
+              patch.object(luv.subprocess, "Popen",
+                           return_value=_FakeProc(kwargs.pop("returncode", 0))),
+              patch.object(luv.termios, "tcgetattr", return_value=self.SAVED),
+              patch.object(luv.termios, "tcsetattr"),
+              patch.object(luv.os, "write", side_effect=self.on_write),
+              contextlib.redirect_stderr(stderr),
+              self.assertRaises(SystemExit) as exit_ctx):
+            luv.hand_over(["/bin/ssh", "box"], **kwargs)
+        return exit_ctx.exception.code
+
+    def on_write(self, fd, data):
+        return len(data)
+
+    def test_broken_session_hands_back_a_runnable_command(self):
+        err = io.StringIO()
+        code = self._hand_over(err, returncode=255, hint=self.HINT)
+
+        self.assertEqual(code, 255)
+        self.assertIn(self.HINT, err.getvalue())
+        # Copy-pasteable means the whole command sits on a line of its own, with
+        # nothing but indentation around it to select past.
+        line = next(l for l in err.getvalue().splitlines() if self.HINT in l)
+        self.assertEqual(line.strip(), self.HINT)
+
+    def test_a_clean_exit_says_nothing(self):
+        # Detaching and the agent finishing both land here; neither is broken.
+        err = io.StringIO()
+        code = self._hand_over(err, returncode=0, hint=self.HINT)
+
+        self.assertEqual(code, 0)
+        self.assertNotIn("luv continue", err.getvalue())
+
+    def test_the_hint_waits_for_the_terminal_to_be_restored(self):
+        # Printed inside the guard it would land in the remote program's modes,
+        # which is where unreadable output comes from in the first place.
+        order = []
+        self.on_write = lambda fd, data: order.append("reset")
+        self._hand_over(_OrderedStderr(order), returncode=255, hint=self.HINT)
+
+        self.assertEqual(order, ["reset", "hint"])
+
+    def test_hint_names_the_repo_and_number_it_knows(self):
+        self.assertEqual(luv.continue_hint("myrepo", "myrepo-box-42"),
+                         "luv continue myrepo 42")
+        self.assertEqual(luv.continue_hint("myrepo", "myrepo-42"),
+                         "luv continue myrepo 42", "pre-slug folders too")
+
+    def test_hint_degrades_to_what_is_known(self):
+        # A brand-new workspace has no number until the remote picks one, and an
+        # adopted session may not even have a repo. Both shorter forms still run.
+        self.assertEqual(luv.continue_hint("myrepo", "luv-pending-abc123"),
+                         "luv continue myrepo")
+        self.assertEqual(luv.continue_hint("myrepo", None), "luv continue myrepo")
+        self.assertEqual(luv.continue_hint(None, "myrepo-box-42"), "luv continue")
+
+    def test_remote_session_carries_its_own_hint(self):
+        with (patch.object(luv.shutil, "which", side_effect=lambda n: f"/bin/{n}"),
+              patch.object(luv, "record_session"),
+              patch.object(luv, "port_watch", return_value=None),
+              patch.object(luv, "hand_over") as hand_over,
+              contextlib.redirect_stdout(io.StringIO())):
+            luv.dispatch_remote({"host": "box"}, ["myrepo", "42"],
+                                workspace="myrepo-box-42",
+                                meta={"repo": "myrepo", "org": "acme"})
+
+        self.assertEqual(hand_over.call_args.kwargs.get("hint"),
+                         "luv continue myrepo 42")
+
+    def test_a_run_with_no_session_behind_it_gets_no_hint(self):
+        # -nit streams to a pipe and exits; there is nothing to continue.
+        with (patch.object(luv.shutil, "which", side_effect=lambda n: f"/bin/{n}"),
+              patch.object(luv, "port_watch", return_value=None),
+              patch.object(luv, "hand_over") as hand_over,
+              contextlib.redirect_stdout(io.StringIO())):
+            luv.dispatch_remote({"host": "box"}, ["myrepo", "42", "-nit"],
+                                use_tmux=False, tty=False)
+
+        self.assertIsNone(hand_over.call_args.kwargs.get("hint"))
+
+    def test_attaching_carries_the_hint_for_the_session_it_picked(self):
+        row = {"host": "box", "session": "luv-myrepo-42", "live": True,
+               "repo": "myrepo", "workspace": "myrepo-box-42"}
+        with (patch.object(luv, "refresh_sessions", return_value=([row], set())),
+              patch.object(luv, "resolve_host", return_value={"host": "box"}),
+              patch.object(luv, "attach_session") as attach,
+              contextlib.redirect_stdout(io.StringIO())):
+            luv.cmd_continue(["myrepo", "42"])
+
+        self.assertEqual(attach.call_args.kwargs.get("hint"),
+                         "luv continue myrepo 42")
+
+    def test_a_session_that_is_already_gone_points_at_the_reopen(self):
+        # Where the hint lands when the agent took the tmux session down with
+        # it: the workspace outlives the session, so pass the user on.
+        with (patch.object(luv, "refresh_sessions", return_value=([], set())),
+              contextlib.redirect_stdout(io.StringIO())):
+            with self.assertRaises(SystemExit):
+                with contextlib.redirect_stderr(io.StringIO()) as err:
+                    luv.cmd_continue(["myrepo", "42"])
+
+        self.assertIn("luv myrepo 42 -r", err.getvalue())
+
+    def test_nothing_live_at_all_suggests_nothing(self):
+        with (patch.object(luv, "refresh_sessions", return_value=([], set())),
+              contextlib.redirect_stdout(io.StringIO())):
+            with self.assertRaises(SystemExit):
+                with contextlib.redirect_stderr(io.StringIO()) as err:
+                    luv.cmd_continue([])
+
+        self.assertNotIn("-r", err.getvalue())
+
+
 class SessionNameTests(unittest.TestCase):
     def test_illegal_tmux_characters_are_replaced(self):
         self.assertEqual(luv.tmux_session_name("foo.js-7"), "luv-foo_js-7")
@@ -676,6 +812,102 @@ class ConfigTests(unittest.TestCase):
         self.assertIn("ConnectTimeout=5", base)
 
 
+def _shell_env_output(env, before="", after=""):
+    """What the probe sees: an rc's greeting, the marker, the environment."""
+    return f"{before}__luv_env__{json.dumps(env)}{after}"
+
+
+class ShellEnvTests(unittest.TestCase):
+    """tmux and ssh exec without a shell, so the rc has to be asked for."""
+
+    def _probe(self, stdout, returncode=0):
+        with (patch.dict(luv.os.environ, {"SHELL": "/bin/zsh"}, clear=True),
+              patch.object(luv, "run",
+                           return_value=_completed(stdout, returncode)) as run):
+            return luv.shell_env(), run.call_args
+
+    def test_asks_the_users_own_shell_as_login_and_interactive(self):
+        env, call = self._probe(_shell_env_output({"API_BASE": "https://x"}))
+
+        self.assertEqual(env, {"API_BASE": "https://x"})
+        self.assertEqual(call.args[0][:2], ["/bin/zsh", "-lic"])
+        self.assertEqual(call.kwargs["stdin"], subprocess.DEVNULL)
+        self.assertEqual(call.kwargs["timeout"], luv.SHELL_ENV_TIMEOUT)
+
+    def test_greeting_before_the_marker_is_ignored(self):
+        env, _ = self._probe(_shell_env_output({"A": "1"}, before="welcome back!\n"))
+
+        self.assertEqual(env, {"A": "1"})
+
+    def test_exit_hook_after_the_environment_is_ignored(self):
+        env, _ = self._probe(_shell_env_output({"A": "1"}, after="\ngoodbye\n"))
+
+        self.assertEqual(env, {"A": "1"})
+
+    def test_failing_rc_still_yields_what_it_exported(self):
+        env, _ = self._probe(_shell_env_output({"A": "1"}), returncode=1)
+
+        self.assertEqual(env, {"A": "1"})
+
+    def test_a_shell_that_says_nothing_useful_is_not_an_error(self):
+        self.assertEqual(self._probe("")[0], {})
+        self.assertEqual(self._probe("__luv_env__not json")[0], {})
+
+    def test_timeout_is_not_an_error(self):
+        # run() turns a hung rc into returncode 124 rather than an exception.
+        self.assertEqual(self._probe("", returncode=124)[0], {})
+
+
+class ApplyShellEnvTests(unittest.TestCase):
+    def _apply(self, environ, rc, config=None):
+        with (patch.dict(luv.os.environ, environ, clear=True),
+              patch.object(luv, "load_config", return_value=config or {}),
+              patch.object(luv, "shell_env", return_value=rc) as probe):
+            luv.apply_shell_env()
+            return dict(luv.os.environ), probe.called
+
+    def test_only_runs_for_the_luv_tmux_or_ssh_started(self):
+        env, probed = self._apply({}, {"API_KEY": "from-rc"})
+
+        self.assertFalse(probed)
+        self.assertNotIn("API_KEY", env)
+
+    def test_fills_in_what_the_session_never_sourced(self):
+        env, _ = self._apply({"_LUV_INNER": "1"}, {"API_KEY": "from-rc"})
+
+        self.assertEqual(env["API_KEY"], "from-rc")
+
+    def test_what_the_caller_set_wins(self):
+        env, _ = self._apply({"_LUV_INNER": "1", "API_KEY": "explicit"},
+                             {"API_KEY": "from-rc", "OTHER": "from-rc"})
+
+        self.assertEqual(env["API_KEY"], "explicit")
+        self.assertEqual(env["OTHER"], "from-rc")
+
+    def test_path_is_merged_rather_than_replaced(self):
+        env, _ = self._apply({"_LUV_INNER": "1", "PATH": "/usr/bin:/bin"},
+                             {"PATH": "/home/u/.nvm/bin:/usr/bin:/home/u/.local/bin"})
+
+        self.assertEqual(env["PATH"],
+                         "/usr/bin:/bin:/home/u/.nvm/bin:/home/u/.local/bin")
+
+    def test_the_probe_shells_own_bookkeeping_is_left_behind(self):
+        env, _ = self._apply({"_LUV_INNER": "1"},
+                             {"PWD": "/home/u", "SHLVL": "3", "_": "/usr/bin/env",
+                              "OLDPWD": "/tmp", "KEEP": "yes"})
+
+        self.assertEqual(env["KEEP"], "yes")
+        for key in ("PWD", "SHLVL", "_", "OLDPWD"):
+            self.assertNotIn(key, env)
+
+    def test_config_can_turn_it_off(self):
+        env, probed = self._apply({"_LUV_INNER": "1"}, {"API_KEY": "from-rc"},
+                                  config={"shell_env": False})
+
+        self.assertFalse(probed)
+        self.assertNotIn("API_KEY", env)
+
+
 class CleanGuardTests(unittest.TestCase):
     def test_live_session_folder_is_skipped(self):
         tempdir = tempfile.TemporaryDirectory()

luv_cli-0.5.0/.github/workflows/publish.yml

@@ -1,29 +0,0 @@
-name: Publish to PyPI
-
-on:
-  push:
-    tags:
-      - "v*"
-
-permissions:
-  id-token: write
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    environment: pypi
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - name: Install build tools
-        run: pip install build
-
-      - name: Build package
-        run: python -m build
-
-      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1