@bitfab/sdk 0.64.14 → 0.64.15

package/cloudReplay.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import argparse
 import base64
+import calendar
 import contextlib
 import functools
 import json
@@ -47,6 +48,9 @@ OUTPUT_LIMIT = 16 * 1024 * 1024
 DISK_LIMIT = 1024 * 1024 * 1024
 NEW_FILES_LIMIT = 20 * 1024 * 1024
 POLL_SECONDS = 5
+CLEANABLE_STATES = ("completed", "prepared", "dispatch_unknown", "dispatch_rejected")
+CLOCK_SKEW_SECONDS = 600
+TIMESTAMP = "%Y-%m-%dT%H:%M:%SZ"
 ITEM_ERROR_FIELDS = (
     "error",
     "traceError",
@@ -99,6 +103,8 @@ SECRET_ENV_NAME = re.compile(
     r"(?:^|_)(?:KEY|SECRET|TOKEN|PASSWORD|PASSWD|CREDENTIALS?)(?:_|$)", re.IGNORECASE
 )
 ENV_FLAG = "--cloud-env"
+ALLOW_FLAG = "--cloud-allow-file"
+REPEATED_FLAGS = (ENV_FLAG, ALLOW_FLAG)
 URL_PASSWORD = re.compile(r"[A-Za-z][A-Za-z0-9+.-]*://[^/\s:@]*:[^/\s@]+@")
 FOLLOW_FLAGS = (
     "--cloud-status",
@@ -121,7 +127,10 @@ RENAMED_FLAGS = {
 SEED_FLAGS = ("--seed", "--cases", "--from-trace", "--run")
 PATH_FLAGS = ("--registry", "--params", "--code-change")
 CODE_CHANGE_FLAGS = ("--code-change", "--no-code-change")
-SELECTION_FLAGS = ("--trace-ids", "--dataset-ids", "--dataset-id", "--resume")
+CHECK_ARGUMENTS_SECONDS = 300
+CHECK_ARGUMENTS_FLAG = "--check-arguments"
+REPLAY_ARGUMENTS_FLAG = "--replay-arguments"
+ARGUMENTS_CHECKED_ENV = "BITFAB_REPLAY_ARGUMENTS_CHECKED"
 ACTIONS = {
     "checkout": "actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1",
     "node": "actions/setup-node@820762786026740c76f36085b0efc47a31fe5020",
@@ -142,35 +151,45 @@ HELP = """Cloud replay: run the replay you run locally on GitHub Actions by addi
 
   bitfab-replay --registry scripts/replay.ts classify --trace-ids UUID --cloud
 
-Every replay option works as it does locally, including --dry-run and --fail-on-error.
-The runner replays a snapshot of your working tree (changed files, plus new files git
-does not ignore) from the same directory, and this command prints the replay's output
-and exits with its exit code. Credential-like files are refused. Requires git and
-Python 3.10+ on macOS or Linux, with a github.com origin.
+Every replay option works as it does locally, including --dry-run and --fail-on-error,
+and your SDK checks them before anything is uploaded. The runner replays a snapshot of
+your working tree (changed files, plus new files git does not ignore) from the same
+directory, and this command prints the replay's output and exits with its exit code.
+Credential-like files that are not on GitHub yet are refused unless you name them with
+--cloud-allow-file. Requires git and Python 3.10+ on macOS or Linux, with a github.com
+origin.
 
 The replay's stderr comes back as it printed it. Its stdout result comes back as a
 short summary instead of every item: the experiment ID and URL, how many traces were
 replayed, same, changed, and errored, each errored trace with its error, and the exit
-code. Every item's input and output are already saved in the experiment in Bitfab.
+code. Every item's input and output are saved in the experiment in Bitfab, where the
+Bitfab MCP tools read them, so by default the job log holds no trace data.
 
 Options added by --cloud:
   --cloud-preview        List what the snapshot would contain and push nothing.
   --cloud-detach         Return after dispatch instead of waiting.
   --cloud-full-output    Print the replay's whole stdout result, every item included,
-                         instead of the summary. Large runs can exceed what the
-                         GitHub job log holds.
+                         instead of the summary. The result passes through the
+                         GitHub job log, so it is refused on a public repository,
+                         and large runs can exceed what the log holds.
   --cloud-timeout MIN    Stop the replay after MIN minutes (1..7200).
   --cloud-env NAME=VALUE Set an environment variable for this replay only; repeat it
                          for more. NAME alone copies the value from your shell. The
                          value is stored in the snapshot commit on GitHub, so this is
                          for settings, never secrets: names that look like secrets,
                          and names the workflow reads from a secret, are refused.
+  --cloud-allow-file PATH
+                         Upload PATH even though it looks like a credential, such as
+                         a test certificate; repeat it for more. Refused on a public
+                         repository, where anyone can read the snapshot branch.
   --cloud-request-id ID  Recover a submission whose response was lost.
   --cloud-ref BRANCH     Replay BRANCH as it is on GitHub, with no snapshot of your
                          working tree, and record the experiment on BRANCH. Meant for
-                         CI jobs, such as a nightly replay of dev. Needs only GitHub
-                         access that can run Actions, and a workflow on BRANCH that
-                         declares a request input.
+                         CI jobs, such as a nightly replay of dev. Runs from a
+                         checkout of the repository, with GitHub access that can
+                         read it and run Actions (a job token needs contents: read
+                         and actions: write, passed as GH_TOKEN), and a workflow on
+                         BRANCH that declares a request input.
 
 A workflow can also dispatch bitfab-replay.yml itself on any branch other than a
 bitfab-replay/ snapshot branch, passing the replay as JSON in the request input:
@@ -190,6 +209,8 @@ the replay does. Traces that errored fail it only under --fail-on-error.
 
 Follow a replay by the execution UUID it prints:
   --cloud-watch ID | --cloud-status ID | --cloud-cancel ID | --cloud-cleanup ID
+--cloud-cleanup removes the snapshot branch once the run completed, or when GitHub
+shows no run for it, such as after a dispatch that failed.
 
 Set up once:
   --cloud-init [--secret NAME ...] [--environment NAME] [--run COMMAND]
@@ -211,6 +232,12 @@ class CommandError(RuntimeError):
         self.http_status = http_status
 
 
+class DispatchRejected(ValueError):
+    def __init__(self, message, record):
+        super().__init__(message)
+        self.record = record
+
+
 class KeepRedirect(urllib.request.HTTPRedirectHandler):
     def redirect_request(self, *args, **kwargs):
         return None
@@ -609,7 +636,7 @@ def split_arguments(argv):
         name = option_name(token)
         if name in RENAMED_FLAGS:
             raise ValueError(f"{name} is gone; use {RENAMED_FLAGS[name]}")
-        if name == ENV_FLAG:
+        if name in REPEATED_FLAGS:
             if "=" in token:
                 value = token.split("=", 1)[1]
                 index += 1
@@ -617,8 +644,12 @@ def split_arguments(argv):
                 value = argv[index + 1]
                 index += 2
             else:
-                raise ValueError(f"{ENV_FLAG} needs NAME=VALUE or NAME")
-            cloud.setdefault(ENV_FLAG, []).append(value)
+                raise ValueError(
+                    f"{ENV_FLAG} needs NAME=VALUE or NAME"
+                    if name == ENV_FLAG
+                    else f"{name} needs a path"
+                )
+            cloud.setdefault(name, []).append(value)
         elif name in CLOUD_VALUE_FLAGS:
             if "=" in token:
                 value = token.split("=", 1)[1]
@@ -655,10 +686,6 @@ def parse(argv):
             raise ValueError(
                 "Add --cloud to the replay command you run locally, such as bitfab-replay --registry scripts/replay.ts classify --trace-ids UUID --cloud"
             )
-        if not any(option_name(token) in SELECTION_FLAGS for token in replay):
-            raise ValueError(
-                "Select traces with --trace-ids, --dataset-ids, or --resume"
-            )
         timeout = cloud.get("--cloud-timeout")
         if timeout is not None and not (
             timeout.isdigit() and 1 <= int(timeout) <= 7200
@@ -676,6 +703,10 @@ def parse(argv):
             )
         if ENV_FLAG in cloud:
             cloud[ENV_FLAG] = replay_environment(cloud[ENV_FLAG])
+        if ALLOW_FLAG in cloud and "--cloud-ref" in cloud:
+            raise ValueError(
+                f"{ALLOW_FLAG} lets a file into the snapshot of your working tree, and --cloud-ref replays the branch on GitHub with no snapshot"
+            )
         operation = "submit"
         execution_id = cloud.get("--cloud-request-id") or str(uuid.uuid4())
     if not UUID.fullmatch(execution_id):
@@ -761,6 +792,38 @@ def dry_run(args):
     return "--dry-run" in args
 
 
+def replay_arguments(argv):
+    try:
+        parsed = parse(argv)
+    except ValueError:
+        return None
+    return parsed["replay"] if parsed["operation"] == "submit" else None
+
+
+def check_arguments(replay):
+    if os.environ.get(ARGUMENTS_CHECKED_ENV) == "1":
+        return
+    try:
+        result = subprocess.run(
+            [*replay_command(), CHECK_ARGUMENTS_FLAG, *replay],
+            text=True,
+            capture_output=True,
+            stdin=subprocess.DEVNULL,
+            check=False,
+            timeout=CHECK_ARGUMENTS_SECONDS,
+        )
+    except subprocess.TimeoutExpired:
+        raise ValueError(
+            f"The replay command took more than {CHECK_ARGUMENTS_SECONDS} seconds to check these options, so nothing was uploaded; make sure it reaches the Bitfab replay entry point without waiting on input or a slow setup step"
+        ) from None
+    if result.returncode:
+        message = (result.stderr or result.stdout).strip()
+        raise ValueError(
+            message
+            or f"The replay command refused these options (exit {result.returncode})"
+        )
+
+
 def replay_request(root, parsed):
     cwd = Path.cwd().resolve()
     args, files = [], []
@@ -826,7 +889,7 @@ def sensitive(path):
     )
 
 
-def snapshot(root, workflow, files, request, *, preview=False):
+def snapshot(root, workflow, files, request, *, preview=False, allowed=()):
     if git(root, "ls-files", "-u"):
         raise ValueError("Resolve merge conflicts before snapshotting")
     head = git(root, "rev-parse", "HEAD")
@@ -843,10 +906,6 @@ def snapshot(root, workflow, files, request, *, preview=False):
                 raise ValueError(
                     f"{path} is a submodule or nested repository, which cloud snapshots do not support"
                 )
-            if sensitive(path):
-                raise ValueError(
-                    f"Refusing credential-like file {path}; add it to .gitignore, or git rm --cached it when it is tracked"
-                )
         ignored = [
             path
             for path in [f"{WORKFLOW_DIRECTORY}/{workflow}", *files]
@@ -867,6 +926,23 @@ def snapshot(root, workflow, files, request, *, preview=False):
         ]
         new_files = sorted(path for status, path in changes if status == "A")
         changed_files = sorted(path for status, path in changes if status != "A")
+        unpushed = git(
+            root,
+            "log",
+            "--format=",
+            "--name-only",
+            "--no-renames",
+            "--diff-filter=AM",
+            head,
+            "--not",
+            "--remotes",
+        ).splitlines()
+        uploaded = ({*new_files, *changed_files} & tracked) | set(unpushed)
+        for path in sorted(uploaded - set(allowed)):
+            if sensitive(path):
+                raise ValueError(
+                    f"Refusing to upload {path}, which looks like a credential and is not on GitHub yet; add it to .gitignore and take it out of any commit you have not pushed, or pass {ALLOW_FLAG} {path} if it is safe to upload. If it is already on GitHub, run git fetch so this check can see it"
+                )
         sizes = {path: (root / path).lstat().st_size for path in new_files}
         size = sum(sizes.values())
         if size > NEW_FILES_LIMIT:
@@ -943,22 +1019,24 @@ def find_run(record):
 
 
 def find_branch_run(record):
+    dispatched = calendar.timegm(time.strptime(record["dispatchedAt"], TIMESTAMP))
     query = urlencode(
         {
             "event": "workflow_dispatch",
             "branch": record["branch"],
-            "created": ">=" + record["dispatchedAt"],
+            "created": ">=" + timestamp(dispatched - CLOCK_SKEW_SECONDS),
             "per_page": 100,
         }
     )
     runs = api(
         record["repository"], f"actions/workflows/{record['workflow']}/runs?{query}"
     )
-    matches = [
-        run
-        for run in runs["workflow_runs"]
-        if run["head_branch"] == record["branch"]
-        and run.get("created_at", "") >= record["dispatchedAt"]
+    on_branch = [
+        run for run in runs["workflow_runs"] if run["head_branch"] == record["branch"]
+    ]
+    named = [run for run in on_branch if record["id"] in run.get("display_title", "")]
+    matches = named or [
+        run for run in on_branch if run.get("created_at", "") >= record["dispatchedAt"]
     ]
     if len(matches) > 1:
         raise ValueError(
@@ -967,8 +1045,12 @@ def find_branch_run(record):
     return matches[0] if matches else None
 
 
+def timestamp(seconds):
+    return time.strftime(TIMESTAMP, time.gmtime(seconds))
+
+
 def status(record, *, fetch_result=True):
-    if record["state"] == "prepared":
+    if record["state"] in ("prepared", "dispatch_rejected"):
         return record
     run = (
         api(record["repository"], f"actions/runs/{record['runId']}")
@@ -1091,7 +1173,7 @@ def print_outcome(found):
                 if summary.get("experimentUrl")
                 else ""
             )
-            + ". Add --cloud-full-output to print every item here instead"
+            + "; the Bitfab MCP tools read them. Add --cloud-full-output to print every item here instead"
         )
     if record.get("stoppedEarly"):
         progress(
@@ -1112,7 +1194,7 @@ def cleanup(root, record):
     if record.get("snapshot") is False:
         record["cleaned"] = True
         return
-    if record.get("state") not in ("completed", "prepared"):
+    if record.get("state") not in CLEANABLE_STATES:
         raise ValueError(
             "Cleanup requires a confirmed completed GitHub run; cancel and wait first"
         )
@@ -1140,7 +1222,7 @@ def http_status(error):
     return f" (HTTP {status})" if status else ""
 
 
-def preflight(repo, workflow, *, pushes=True):
+def preflight(repo, workflow, *, pushes=True, full_output=False, allows_files=False):
     access = github_access()
     try:
         details = api(repo, "")
@@ -1152,6 +1234,14 @@ def preflight(repo, workflow, *, pushes=True):
         raise ValueError(
             f"GitHub access from {access['source']} cannot push to {repo}; use an account or token with write access to it"
         )
+    if full_output and (details or {}).get("private") is False:
+        raise ValueError(
+            f"--cloud-full-output writes every trace's input and output into the Actions job log, and anyone can read the logs of {repo} because it is public; leave it off and read the items in the experiment with the Bitfab MCP tools"
+        )
+    if allows_files and (details or {}).get("private") is False:
+        raise ValueError(
+            f"{ALLOW_FLAG} uploads a credential-like file to a snapshot branch, and anyone can read the branches of {repo} because it is public"
+        )
     path = f"{WORKFLOW_DIRECTORY}/{workflow}"
     try:
         registered = api(repo, f"actions/workflows/{workflow}")
@@ -1177,14 +1267,24 @@ def describe_snapshot(source):
     )
 
 
+def allowed_files(root, parsed):
+    cwd = Path.cwd().resolve()
+    return [
+        repository_path(root, cwd / value)
+        for value in parsed["cloud"].get(ALLOW_FLAG, [])
+    ]
+
+
 def submit(root, repo, workflow, parsed, path):
     execution_id = parsed["id"]
     request, files = replay_request(root, parsed)
+    check_arguments(parsed["replay"])
+    allowed = allowed_files(root, parsed)
     if "--cloud-preview" in parsed["switches"]:
         return {
             "preview": True,
             "repository": repo,
-            **snapshot(root, workflow, files, request, preview=True),
+            **snapshot(root, workflow, files, request, preview=True, allowed=allowed),
         }
     if path.exists():
         record = json.loads(path.read_text())
@@ -1195,13 +1295,19 @@ def submit(root, repo, workflow, parsed, path):
             raise ValueError(
                 "Submission stopped before dispatch. Use --cloud-cleanup, then submit a new execution UUID"
             )
+        refuse_rejected(record)
         return record
-    preflight(repo, workflow)
+    preflight(
+        repo,
+        workflow,
+        full_output=request.get("fullOutput") is True,
+        allows_files=bool(allowed),
+    )
     if dry_run(request["args"]):
         progress(
             "--dry-run dispatches a GitHub run that checks secrets and resolves the traces without replaying; it receives the workflow's secrets"
         )
-    source = snapshot(root, workflow, files, request)
+    source = snapshot(root, workflow, files, request, allowed=allowed)
     describe_snapshot(source)
     record = {
         "id": execution_id,
@@ -1264,8 +1370,22 @@ def dispatch(record, inputs, declared, *, run_details=False):
                 raise
             response = api(record["repository"], path, method="POST", payload=payload)
     except RuntimeError as error:
+        code = getattr(error, "http_status", None)
+        problem = f"Dispatching {record['workflow']} on {record['branch']} failed{http_status(error)}"
+        if code is not None and 400 <= code < 500 and code != 429:
+            record["state"] = "dispatch_rejected"
+            raise DispatchRejected(
+                f"{problem}, so no run started"
+                + (
+                    ""
+                    if record.get("snapshot") is False
+                    else " and the snapshot branch was removed"
+                )
+                + ". The GitHub account needs write access to Actions, and the registered workflow must accept workflow_dispatch",
+                record,
+            ) from error
         raise ValueError(
-            f"Dispatching {record['workflow']} on {record['branch']} failed{http_status(error)}; the GitHub account needs write access to Actions, and the registered workflow must accept workflow_dispatch. Check the Actions tab, then resume with --cloud-watch {record['id']}"
+            f"{problem}, and GitHub may still have started it. Follow it with --cloud-watch {record['id']}, or once --cloud-status {record['id']} shows no run, remove it with --cloud-cleanup {record['id']}"
         ) from error
     if isinstance(response, dict) and response.get("workflow_run_id"):
         record["runId"] = response["workflow_run_id"]
@@ -1302,6 +1422,7 @@ def submit_as_is(root, repo, workflow, parsed, path):
     execution_id = parsed["id"]
     branch = parsed["cloud"]["--cloud-ref"]
     request, _ = replay_request(root, parsed)
+    check_arguments(parsed["replay"])
     sha = branch_head(repo, branch)
     if "--cloud-preview" in parsed["switches"]:
         return {
@@ -1320,8 +1441,11 @@ def submit_as_is(root, repo, workflow, parsed, path):
         ):
             raise ValueError("Execution ID already belongs to a different request")
         status(record, fetch_result=False)
+        refuse_rejected(record)
         return record
-    preflight(repo, workflow, pushes=False)
+    preflight(
+        repo, workflow, pushes=False, full_output=request.get("fullOutput") is True
+    )
     declared = declared_inputs(branch_workflow(repo, workflow, sha))
     if "request" not in declared:
         raise ValueError(
@@ -1336,9 +1460,7 @@ def submit_as_is(root, repo, workflow, parsed, path):
         "request": request,
         "state": "dispatch_unknown",
         "sha": sha,
-        "dispatchedAt": time.strftime(
-            "%Y-%m-%dT%H:%M:%SZ", time.gmtime(time.time() - 5)
-        ),
+        "dispatchedAt": timestamp(time.time() - 5),
     }
     save(path, record)
     progress(
@@ -1363,12 +1485,20 @@ def report_steps(record, shown):
             progress(step.get("name"))
 
 
+def refuse_rejected(record):
+    if record["state"] == "dispatch_rejected":
+        raise ValueError(
+            "GitHub refused this execution's dispatch, so no run exists; submit the replay again without --cloud-request-id"
+        )
+
+
 def wait(record, path):
     started = time.monotonic()
     announced, steps = None, set()
     while record["state"] != "completed":
         status(record, fetch_result=False)
         save(path, record)
+        refuse_rejected(record)
         if record["state"] != announced and record.get("url"):
             announced = record["state"]
             progress(f"{announced.replace('_', ' ').capitalize()}: {record['url']}")
@@ -1398,7 +1528,12 @@ def run_cli(argv):
     with execution_lock(directory, execution_id):
         if operation == "submit":
             submitter = submit_as_is if "--cloud-ref" in parsed["cloud"] else submit
-            record = submitter(root, repo, workflow, parsed, path)
+            try:
+                record = submitter(root, repo, workflow, parsed, path)
+            except DispatchRejected as error:
+                cleanup(root, error.record)
+                save(path, error.record)
+                raise
             if record.get("preview"):
                 return record, None
         else:
@@ -1426,11 +1561,13 @@ def run_cli(argv):
             wait(record, path)
             found = outcome(record)
         if record["state"] == "completed" or (
-            operation == "cleanup" and record["state"] == "prepared"
+            operation == "cleanup" and record["state"] in CLEANABLE_STATES
         ):
             cleanup(root, record)
         elif operation == "cleanup":
-            raise ValueError("Execution is not completed; no branch was deleted")
+            raise ValueError(
+                f"The GitHub run is {record['state'].replace('_', ' ')}; cancel it with --cloud-cancel {record['id']} and clean up once it completes. No branch was deleted"
+            )
         save(path, record)
         return record, found
 
@@ -1922,6 +2059,8 @@ def run_command(
                 stop(child)
                 raise
             finally:
+                with contextlib.suppress(ProcessLookupError, PermissionError):
+                    os.killpg(child.pid, signal.SIGKILL)
                 reader.join(timeout=5)
             code = child.returncode if child.returncode >= 0 else 1
         text, omitted = relayed_stdout(output, code, summarize)
@@ -1938,6 +2077,9 @@ def stop(child):
     child.wait()
 
 
+PNPM_FOR_LOCKFILE = {"9": "10", "6": "8", "5": "7"}
+DEFAULT_PNPM = "10"
+RUBY_VERSION_FILES = [".ruby-version", ".tool-versions"]
 PLAIN_SCALAR = re.compile(r"[A-Za-z0-9_./][A-Za-z0-9_ ./@*+=,()-]*")
 YAML_WORDS = {"true", "false", "yes", "no", "on", "off", "null", "~", "y", "n"}
 
@@ -2048,9 +2190,16 @@ def typescript_project(root, start):
     }[manager]
     steps = []
     if manager == "pnpm":
-        steps.append({"uses": ACTIONS["pnpm"]})
+        steps.append(pnpm_setup(root, directory, lockfile))
     if manager == "bun":
         steps.append({"uses": ACTIONS["bun"]})
+    cache = {}
+    if manager in ("pnpm", "yarn", "npm") and lockfile:
+        cache["cache"] = manager
+        if directory != root:
+            cache["cache-dependency-path"] = (
+                (directory / lockfile).relative_to(root).as_posix()
+            )
     steps += [
         {
             "uses": ACTIONS["node"],
@@ -2058,11 +2207,7 @@ def typescript_project(root, start):
                 **version_input(
                     root, start, "node", [".nvmrc", ".node-version"], "lts/*"
                 ),
-                **(
-                    {"cache": manager}
-                    if manager in ("pnpm", "yarn", "npm") and lockfile
-                    else {}
-                ),
+                **cache,
             },
         },
         {**step_directory(root, directory or start), "run": install},
@@ -2076,6 +2221,28 @@ def typescript_project(root, start):
     return steps, run
 
 
+def pnpm_setup(root, directory, lockfile):
+    package = directory / "package.json"
+    try:
+        declared = json.loads(package.read_text()).get("packageManager", "")
+    except (OSError, ValueError, AttributeError):
+        declared = ""
+    if isinstance(declared, str) and declared.startswith("pnpm@"):
+        if directory == root:
+            return {"uses": ACTIONS["pnpm"]}
+        return {
+            "uses": ACTIONS["pnpm"],
+            "with": {"package_json_file": package.relative_to(root).as_posix()},
+        }
+    found = re.search(
+        r"^lockfileVersion:\s*['\"]?(\d+)",
+        (directory / lockfile).read_text(errors="replace"),
+        re.MULTILINE,
+    )
+    version = PNPM_FOR_LOCKFILE.get(found[1] if found else "", DEFAULT_PNPM)
+    return {"uses": ACTIONS["pnpm"], "with": {"version": version}}
+
+
 def python_project(root, start):
     directory, lockfile = find_upward(
         root, start, ["uv.lock", "poetry.lock", "requirements.txt", "pyproject.toml"]
@@ -2108,12 +2275,33 @@ def python_project(root, start):
 
 def ruby_project(root, start):
     directory, _ = find_upward(root, start, ["Gemfile"])
-    location = step_directory(root, directory or start)
+    directory = directory or start
+    found, name = find_upward(root, directory, RUBY_VERSION_FILES)
+    version = (
+        {}
+        if found == directory
+        else {"ruby-version": (name and ruby_version(found / name)) or "ruby"}
+    )
     return [
-        {"uses": ACTIONS["ruby"], "with": {"bundler-cache": True, **location}}
+        {
+            "uses": ACTIONS["ruby"],
+            "with": {
+                **version,
+                "bundler-cache": True,
+                **step_directory(root, directory),
+            },
+        }
     ], "bundle exec bitfab-replay"
 
 
+def ruby_version(path):
+    text = path.read_text(errors="replace")
+    if path.name == ".tool-versions":
+        found = re.search(r"^ruby\s+(\S+)", text, re.MULTILINE)
+        return found[1] if found else None
+    return text.strip() or None
+
+
 def go_project(root, start):
     directory, name = find_upward(root, start, ["go.mod"])
     version = (
@@ -2188,9 +2376,13 @@ def workflow_document(steps, run, directory, env, *, runs_on, environment):
     ]
     return {
         "name": "Bitfab replay",
+        "run-name": "Bitfab replay ${{ inputs.execution_id || github.ref_name }}",
         "on": {
             "workflow_dispatch": {
-                "inputs": {"request": {"type": "string", "required": False}}
+                "inputs": {
+                    "execution_id": {"type": "string", "required": False},
+                    "request": {"type": "string", "required": False},
+                }
             }
         },
         "permissions": {"contents": "read"},
@@ -2320,6 +2512,9 @@ def main():
         if argv[:1] == ["--cloud-secrets"]:
             print_json(configure_secrets(argv[1:]))
             return 0
+        if argv[:1] == [REPLAY_ARGUMENTS_FLAG]:
+            print_json(replay_arguments(argv[1:]))
+            return 0
         if argv == ["--cloud-execute"]:
             result = execute()
             annotate(result)
@@ -2334,7 +2529,7 @@ def main():
         return record.get("exitCode", 0) if record.get("state") == "completed" else 0
     except KeyboardInterrupt:
         progress(
-            "Detached. The GitHub run continues; follow it with the printed execution UUID"
+            "Detached. A GitHub run that already started continues; follow it with --cloud-watch and the printed execution UUID, or stop it with --cloud-cancel and remove its snapshot branch with --cloud-cleanup once it completes"
         )
         return 130
     except (