[luv-legion-43] Hand back the exact 'luv continue' when a session breaks (#43)

* Hand back the exact 'luv continue' when a session breaks

A dropped connection already left the terminal usable; it still left you
working out which of several live sessions you had just lost, and with what
arguments. luv knows both, so it now prints the command — repo and number
filled in — on its way out, on a line of its own to be copied and run.

Only on a bad exit: a clean one is a detach or the agent finishing, and
neither wants advice. The detached-start notices print the same command
instead of a bare 'luv continue'. Where a hint can't be complete it gets
shorter rather than wrong — a repo alone takes its newest session — and where
the agent took the tmux session down with it, 'luv continue' now passes you
on to 'luv <repo> <n> -r' rather than stopping at "no live sessions".

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LCiSTa4QuwBDrecuSUTBZ3

* Bump to 0.5.1

Same class of change as 0.2.1: polish on the dropped-connection path rather
than a new subsystem.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LCiSTa4QuwBDrecuSUTBZ3

* Remind on commit when the branch's version still matches main

Releases here are cut from the version in pyproject.toml: a push to main whose
version has no tag yet publishes itself. A branch that changes the tool and
forgets the bump therefore merges into a main that publishes nothing, and the
change sits unreleased until somebody notices.

A failproofai convention policy — .failproofai/policies/ is auto-loaded, no
install step, so everyone working in the repo gets it. It instructs rather than
blocks, fires only while the working tree's version equals the base branch's,
and goes quiet the moment it is bumped. Never on main, never on a repo with no
manifest or no base ref, and every git call fails open.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LCiSTa4QuwBDrecuSUTBZ3

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: NiveditJain

.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 };

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 |

luv/__init__.py

@@ -1585,7 +1585,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 +1633,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 +1655,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 +1683,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 +1799,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 +3190,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 +3222,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:
@@ -3471,7 +3524,8 @@ def take_value(flag: str, what: str) -> str | None:
   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.

pyproject.toml

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