diff --git a/docs/content/workspaces/ai-tools.md b/docs/content/workspaces/ai-tools.md index 9c9f01f..2ce0e72 100644 --- a/docs/content/workspaces/ai-tools.md +++ b/docs/content/workspaces/ai-tools.md @@ -121,7 +121,7 @@ On every start, the runner runs in the `tmux` session `claude-runner` (`tmux att - **Use a workspace only for the runner.** The runner rewrites `~/.gitconfig` and `~/.config/git` before every session. It can't be turned on together with remote control. - **Concurrent sessions** (1 to 4) sets how many sessions run at once. They share the workspace's Docker daemon and DDEV, and a skill installed in `~/.claude/skills/coder-shared-workspace` tells them how to stay out of each other's way. For full isolation, use several workspaces with one session each; the same environment secret works in all of them (see [Who can use the runner](#who-can-use-the-runner)). -- **Checkouts are cleaned between sessions.** A runner keeps its clones under `~/workspace/runner-`. When a session ends, including when the runner releases it after 30 idle minutes, `claude-runner-sweep` cleans that runner's directory, and it runs again before each runner start. Uncommitted changes become `runner-rescue` stashes in the clone (`git stash list`). Worktrees are removed. Extra clones a session made are deleted if everything in them is pushed, and otherwise moved to `~/.local/state/claude-runner-rescue/`. Everything the sweep does is logged in `~/.local/state/claude-runner-rescue/log`, and rescues are kept for 30 days. If a checkout is still dirty when a session starts, a hook tells Claude to stash the leftovers rather than work around them. +- **Checkouts are cleaned between sessions.** A runner keeps its clones under `~/workspace/runner-`. When a session ends, including when the runner releases it after 30 idle minutes, `claude-runner-sweep` cleans that runner's directory, and it runs again before each runner start. Uncommitted changes become `runner-rescue` stashes in the clone. The runner clears the stash list between sessions, so each rescue also gets a ref: list them with `git for-each-ref refs/runner-rescue` and restore one with `git stash apply `. Worktrees are removed. Extra clones a session made are deleted if everything in them is pushed, and otherwise moved to `~/.local/state/claude-runner-rescue/`. Everything the sweep does is logged in `~/.local/state/claude-runner-rescue/log`, and rescues are kept for 30 days. If a checkout is still dirty when a session starts, a hook tells Claude to stash the leftovers rather than work around them. - **Pushing to your fork.** Runner and remote-control sessions use the workspace SSH agent: your own agent when you have one forwarded (VS Code, `coder ssh -A`), otherwise your Coder key. Add your fork as an SSH remote, such as `git@github.com:/`. If you don't forward an agent, add the key that `coder publickey` prints to your GitHub account. The runner adds GitHub's host keys to `~/.ssh/known_hosts`. SSH pushes act as the workspace owner, whoever started the session; see [Who acts on GitHub](#who-acts-on-github). ### Who acts on GitHub diff --git a/freeform/modules/claude-self-hosted-runner/files/README.md b/freeform/modules/claude-self-hosted-runner/files/README.md index 86ca76b..5378d78 100644 --- a/freeform/modules/claude-self-hosted-runner/files/README.md +++ b/freeform/modules/claude-self-hosted-runner/files/README.md @@ -30,8 +30,10 @@ directory. The workspace rewrites this README on every start. `/tmp/claude-runner-.log`. - Live sessions, their checkouts and unpushed commits: `claude-sessions`. - Checkouts: `~/workspace/runner-//`. -- Work a session left uncommitted: `git stash list | grep runner-rescue` in - the checkout. Extra clones with unpushed commits are moved to +- Work a session left uncommitted: `git for-each-ref refs/runner-rescue` in + the checkout, and `git stash apply ` to restore one. The runner + clears the stash list between sessions, so `git stash list` doesn't show + them. Extra clones with unpushed commits are moved to `~/.local/state/claude-runner-rescue/`, and its `log` lists every change. Both are kept for 30 days. diff --git a/freeform/modules/claude-self-hosted-runner/files/SKILL.md b/freeform/modules/claude-self-hosted-runner/files/SKILL.md index 120bc4a..d9537d4 100644 --- a/freeform/modules/claude-self-hosted-runner/files/SKILL.md +++ b/freeform/modules/claude-self-hosted-runner/files/SKILL.md @@ -28,9 +28,10 @@ since another session can start at any time. branches or git state under another runner's directory. - A runner keeps its checkouts from one session to the next. After every session, `claude-runner-sweep` cleans them: it stashes uncommitted changes - as `runner-rescue` stashes, removes worktrees, and moves other clones to - `~/.local/state/claude-runner-rescue/`. See "Leave the checkout clean" - below. + and keeps each stash under `refs/runner-rescue/` (list them with + `git for-each-ref refs/runner-rescue`), removes worktrees, and moves other + clones to `~/.local/state/claude-runner-rescue/`. See "Leave the checkout + clean" below. - Work in the checkout the runner gave you. Do not make a new clone, and never make a worktree or clone to get around files an earlier session left behind. If a task needs a second checkout, ask the user first. @@ -44,7 +45,8 @@ change what it generates, such as DDEV's image tags. - If the hook reports leftovers, they are not yours. Save them, then carry on in the same checkout: - `git stash push --include-untracked -m "leftovers from an earlier session"`. + `git stash push --include-untracked -m "leftovers from an earlier session" && git update-ref "refs/runner-rescue/$(date -u +%Y%m%d-%H%M%S)-leftovers" refs/stash`. + The ref keeps the stash after the runner clears the stash list. Do not commit, delete or restore them. - The runner can end your session without warning once the user has sent nothing for 30 minutes. Before you finish a turn and wait for the user, diff --git a/freeform/modules/claude-self-hosted-runner/files/claude-checkout-check b/freeform/modules/claude-self-hosted-runner/files/claude-checkout-check index d621f33..66f1170 100755 --- a/freeform/modules/claude-self-hosted-runner/files/claude-checkout-check +++ b/freeform/modules/claude-self-hosted-runner/files/claude-checkout-check @@ -20,12 +20,12 @@ sid=$(jq -r '.session_id // empty' <<<"$input" 2>/dev/null) if [ -n "$sid" ] && [ -f "$rescue_root/log" ] && grep -qF -- "$sid" "$rescue_root/log"; then echo "This session was released earlier, and the runner saved what it had left uncommitted. Entries in $rescue_root/log:" grep -F -- "$sid" "$rescue_root/log" | tail -10 - echo "Stashes are in the checkout named there (find them with: git -C stash list | grep runner-rescue). Before restoring one, tell the user what it holds." + echo "Stashes are in the checkout named there (find them with: git -C for-each-ref refs/runner-rescue, and restore one with git stash apply ). Before restoring one, tell the user what it holds." fi status=$(git -C "$dir" status --porcelain 2>/dev/null) || exit 0 [ -n "$status" ] || exit 0 count=$(printf '%s\n' "$status" | wc -l) echo "The checkout $dir is not clean at the start of this session: an earlier session left $count changed or untracked path(s)." -echo "They are not part of your task. Save them with: git stash push --include-untracked -m \"leftovers from an earlier session\". Then continue in this checkout; do not make a worktree or a new clone to avoid them. See \"Leave the checkout clean\" in the coder-shared-workspace skill." +echo "They are not part of your task. Save them with: git stash push --include-untracked -m \"leftovers from an earlier session\" && git update-ref refs/runner-rescue/\$(date -u +%Y%m%d-%H%M%S)-leftovers refs/stash. Then continue in this checkout; do not make a worktree or a new clone to avoid them. See \"Leave the checkout clean\" in the coder-shared-workspace skill." printf '%s\n' "$status" | head -20 [ "$count" -le 20 ] || echo "... and $((count - 20)) more" diff --git a/freeform/modules/claude-self-hosted-runner/files/claude-runner-sweep b/freeform/modules/claude-self-hosted-runner/files/claude-runner-sweep index 7ff74dd..d1e3f06 100755 --- a/freeform/modules/claude-self-hosted-runner/files/claude-runner-sweep +++ b/freeform/modules/claude-self-hosted-runner/files/claude-runner-sweep @@ -5,13 +5,17 @@ # Runs as the runner's post-session hook and before every runner start, so # never while a session uses the directory (each runner has --capacity 1). # Nothing a session left is deleted unless a commit or remote already holds it: -# - Leftover changes in the runner's clones go into a "runner-rescue" stash. +# - Leftover changes in the runner's clones go into a "runner-rescue" stash, +# kept by a ref under refs/runner-rescue/. The runner clears the stash +# reflog between sessions, so `git stash list` no longer shows the stash; +# list rescues with `git for-each-ref refs/runner-rescue`. # - Worktrees are removed, after stashing their changes the same way. # - Other clones, and broken worktrees, are deleted if they hold nothing # unpushed, and otherwise moved to the rescue directory, # ~/.local/state/claude-runner-rescue//