Skip to content

Commit 3f6be7a

Browse files
committed
fix(runner): keep runner-rescue stashes findable with refs
The runner clears each clone's stash reflog between sessions, so `git stash list` showed none of the sweep's runner-rescue stashes. Only the newest survived, as refs/stash, and the older ones were left for git gc. The sweep now also points a ref under refs/runner-rescue/ at each rescue stash. Names get a counter when one already exists. The sweep adopts an earlier sweep's rescue still in refs/stash, and expires rescue refs after CLAUDE_RUNNER_RESCUE_DAYS. The docs, runner README, skill and SessionStart hook now say to list rescues with `git for-each-ref refs/runner-rescue` and restore one with `git stash apply <ref>`. Leftovers a session stashes itself get a ref too. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T3Cc2FfNKgEMqAZMMRVvjp
1 parent c4b659d commit 3f6be7a

9 files changed

Lines changed: 77 additions & 31 deletions

File tree

‎docs/content/workspaces/ai-tools.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,5 +121,5 @@ On every start, the runner runs in the `tmux` session `claude-runner` (`tmux att
121121

122122
- **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.
123123
- **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.
124-
- **Checkouts are cleaned between sessions.** A runner keeps its clones under `~/workspace/runner-<n>`. 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.
124+
- **Checkouts are cleaned between sessions.** A runner keeps its clones under `~/workspace/runner-<n>`. 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 <ref>`. 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.
125125
- **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 the Coder workspace key. Add your fork as an SSH remote, such as `git@github.com:<you>/<repo>`. If you don't forward an agent, add the key that `coder publickey` prints to your GitHub account.

‎freeform/modules/claude-self-hosted-runner/files/README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,10 @@ directory. The workspace rewrites this README on every start.
3030
`/tmp/claude-runner-<n>.log`.
3131
- Live sessions, their checkouts and unpushed commits: `claude-sessions`.
3232
- Checkouts: `~/workspace/runner-<n>/<owner>/<repo>`.
33-
- Work a session left uncommitted: `git stash list | grep runner-rescue` in
34-
the checkout. Extra clones with unpushed commits are moved to
33+
- Work a session left uncommitted: `git for-each-ref refs/runner-rescue` in
34+
the checkout, and `git stash apply <ref>` to restore one. The runner
35+
clears the stash list between sessions, so `git stash list` doesn't show
36+
them. Extra clones with unpushed commits are moved to
3537
`~/.local/state/claude-runner-rescue/`, and its `log` lists every change.
3638
Both are kept for 30 days.
3739

‎freeform/modules/claude-self-hosted-runner/files/SKILL.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,9 @@ since another session can start at any time.
2828
branches or git state under another runner's directory.
2929
- A runner keeps its checkouts from one session to the next. After every
3030
session, `claude-runner-sweep` cleans them: it stashes uncommitted changes
31-
as `runner-rescue` stashes, removes worktrees, and moves other clones to
31+
and keeps each stash under `refs/runner-rescue/` (list them with
32+
`git for-each-ref refs/runner-rescue`), removes worktrees, and moves other
33+
clones to
3234
`~/.local/state/claude-runner-rescue/`. See "Leave the checkout clean"
3335
below.
3436
- Work in the checkout the runner gave you. Do not make a new clone, and
@@ -44,7 +46,8 @@ change what it generates, such as DDEV's image tags.
4446

4547
- If the hook reports leftovers, they are not yours. Save them, then carry
4648
on in the same checkout:
47-
`git stash push --include-untracked -m "leftovers from an earlier session"`.
49+
`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`.
50+
The ref keeps the stash after the runner clears the stash list.
4851
Do not commit, delete or restore them.
4952
- The runner can end your session without warning once the user has sent
5053
nothing for 30 minutes. Before you finish a turn and wait for the user,

‎freeform/modules/claude-self-hosted-runner/files/claude-checkout-check‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,12 +20,12 @@ sid=$(jq -r '.session_id // empty' <<<"$input" 2>/dev/null)
2020
if [ -n "$sid" ] && [ -f "$rescue_root/log" ] && grep -qF -- "$sid" "$rescue_root/log"; then
2121
echo "This session was released earlier, and the runner saved what it had left uncommitted. Entries in $rescue_root/log:"
2222
grep -F -- "$sid" "$rescue_root/log" | tail -10
23-
echo "Stashes are in the checkout named there (find them with: git -C <checkout> stash list | grep runner-rescue). Before restoring one, tell the user what it holds."
23+
echo "Stashes are in the checkout named there (find them with: git -C <checkout> for-each-ref refs/runner-rescue, and restore one with git stash apply <ref>). Before restoring one, tell the user what it holds."
2424
fi
2525
status=$(git -C "$dir" status --porcelain 2>/dev/null) || exit 0
2626
[ -n "$status" ] || exit 0
2727
count=$(printf '%s\n' "$status" | wc -l)
2828
echo "The checkout $dir is not clean at the start of this session: an earlier session left $count changed or untracked path(s)."
29-
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."
29+
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."
3030
printf '%s\n' "$status" | head -20
3131
[ "$count" -le 20 ] || echo "... and $((count - 20)) more"

‎freeform/modules/claude-self-hosted-runner/files/claude-runner-sweep‎

Lines changed: 27 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,15 @@
55
# Runs as the runner's post-session hook and before every runner start, so
66
# never while a session uses the directory (each runner has --capacity 1).
77
# Nothing a session left is deleted unless a commit or remote already holds it:
8-
# - Leftover changes in the runner's clones go into a "runner-rescue" stash.
8+
# - Leftover changes in the runner's clones go into a "runner-rescue" stash,
9+
# kept by a ref under refs/runner-rescue/. The runner clears the stash
10+
# reflog between sessions, so `git stash list` no longer shows the stash;
11+
# list rescues with `git for-each-ref refs/runner-rescue`.
912
# - Worktrees are removed, after stashing their changes the same way.
1013
# - Other clones, and broken worktrees, are deleted if they hold nothing
1114
# unpushed, and otherwise moved to the rescue directory,
1215
# ~/.local/state/claude-runner-rescue/<runner>/<time>/.
13-
# Every action is logged in the rescue directory's "log". Rescue stashes and
16+
# Every action is logged in the rescue directory's "log". Rescue refs and
1417
# directories older than CLAUDE_RUNNER_RESCUE_DAYS (default 30) are removed.
1518
# Portable to macOS: bash 3.2 and BSD date, find and sed.
1619
set -u
@@ -55,7 +58,17 @@ rescue_stash() {
5558
return 1
5659
fi
5760
fi
58-
note "stashed changes in $dir as \"$msg\""
61+
# The stash reflog doesn't survive to the next session; a ref does.
62+
local ref slug
63+
slug=$(printf '%s' "$session-$what" | tr -c 'A-Za-z0-9._-' '-')
64+
ref="refs/runner-rescue/$stamp-$slug"
65+
local n=1
66+
while git -C "$dir" show-ref -q --verify "$ref"; do
67+
n=$((n + 1))
68+
ref="refs/runner-rescue/$stamp-$slug-$n"
69+
done
70+
git -C "$dir" update-ref "$ref" refs/stash 2>/dev/null || ref="refs/stash"
71+
note "stashed changes in $dir as \"$msg\" ($ref)"
5972
}
6073

6174
# True when deleting this checkout loses nothing: no changes, no stashes and
@@ -93,6 +106,14 @@ done
93106
# Runner clones first, so their worktrees are gone before the second pass.
94107
for dir in ${candidates[@]+"${candidates[@]}"}; do
95108
is_runner_clone "$dir" || continue
109+
# Older sweeps kept rescues only as stashes. When refs/stash is one that no
110+
# rescue ref holds, give it a ref before another stash replaces it.
111+
old=$(git -C "$dir" rev-parse -q --verify refs/stash 2>/dev/null)
112+
if [ -n "$old" ] && git -C "$dir" log -1 --format=%s "$old" 2>/dev/null | grep -q runner-rescue &&
113+
! git -C "$dir" for-each-ref --format='%(objectname)' refs/runner-rescue/ 2>/dev/null | grep -qx "$old"; then
114+
ref="refs/runner-rescue/$(git -C "$dir" log -1 --format=%ct "$old")-earlier-sweep"
115+
git -C "$dir" update-ref "$ref" "$old" && note "kept the earlier rescue stash in $dir as $ref"
116+
fi
96117
# git prints worktree paths with symlinks resolved, as with macOS /var.
97118
real=$(cd "$dir" && pwd -P)
98119
while read -r wt; do
@@ -106,13 +127,10 @@ for dir in ${candidates[@]+"${candidates[@]}"}; do
106127
done < <(git -C "$dir" worktree list --porcelain 2>/dev/null | sed -n 's/^worktree //p')
107128
git -C "$dir" worktree prune 2>/dev/null
108129
rescue_stash "$dir" "checkout"
109-
# Drop expired rescue stashes, highest index (oldest) first, so the lower
110-
# indexes stay valid.
111130
cutoff=$(($(date +%s) - keep_days * 86400))
112-
git -C "$dir" stash list --format='%gd %ct %gs' 2>/dev/null | sort -t'{' -k2 -rn |
113-
while read -r ref ct subject; do
114-
case "$subject" in *runner-rescue*) ;; *) continue ;; esac
115-
[ "$ct" -lt "$cutoff" ] && git -C "$dir" stash drop --quiet "$ref" 2>/dev/null
131+
git -C "$dir" for-each-ref --format='%(refname) %(committerdate:unix)' refs/runner-rescue/ 2>/dev/null |
132+
while read -r ref ct; do
133+
[ "$ct" -lt "$cutoff" ] && git -C "$dir" update-ref -d "$ref" 2>/dev/null
116134
done
117135
done
118136

‎modules/claude-self-hosted-runner/files/README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,10 @@ directory. The workspace rewrites this README on every start.
3030
`/tmp/claude-runner-<n>.log`.
3131
- Live sessions, their checkouts and unpushed commits: `claude-sessions`.
3232
- Checkouts: `~/workspace/runner-<n>/<owner>/<repo>`.
33-
- Work a session left uncommitted: `git stash list | grep runner-rescue` in
34-
the checkout. Extra clones with unpushed commits are moved to
33+
- Work a session left uncommitted: `git for-each-ref refs/runner-rescue` in
34+
the checkout, and `git stash apply <ref>` to restore one. The runner
35+
clears the stash list between sessions, so `git stash list` doesn't show
36+
them. Extra clones with unpushed commits are moved to
3537
`~/.local/state/claude-runner-rescue/`, and its `log` lists every change.
3638
Both are kept for 30 days.
3739

‎modules/claude-self-hosted-runner/files/SKILL.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,9 @@ since another session can start at any time.
2828
branches or git state under another runner's directory.
2929
- A runner keeps its checkouts from one session to the next. After every
3030
session, `claude-runner-sweep` cleans them: it stashes uncommitted changes
31-
as `runner-rescue` stashes, removes worktrees, and moves other clones to
31+
and keeps each stash under `refs/runner-rescue/` (list them with
32+
`git for-each-ref refs/runner-rescue`), removes worktrees, and moves other
33+
clones to
3234
`~/.local/state/claude-runner-rescue/`. See "Leave the checkout clean"
3335
below.
3436
- Work in the checkout the runner gave you. Do not make a new clone, and
@@ -44,7 +46,8 @@ change what it generates, such as DDEV's image tags.
4446

4547
- If the hook reports leftovers, they are not yours. Save them, then carry
4648
on in the same checkout:
47-
`git stash push --include-untracked -m "leftovers from an earlier session"`.
49+
`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`.
50+
The ref keeps the stash after the runner clears the stash list.
4851
Do not commit, delete or restore them.
4952
- The runner can end your session without warning once the user has sent
5053
nothing for 30 minutes. Before you finish a turn and wait for the user,

‎modules/claude-self-hosted-runner/files/claude-checkout-check‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,12 +20,12 @@ sid=$(jq -r '.session_id // empty' <<<"$input" 2>/dev/null)
2020
if [ -n "$sid" ] && [ -f "$rescue_root/log" ] && grep -qF -- "$sid" "$rescue_root/log"; then
2121
echo "This session was released earlier, and the runner saved what it had left uncommitted. Entries in $rescue_root/log:"
2222
grep -F -- "$sid" "$rescue_root/log" | tail -10
23-
echo "Stashes are in the checkout named there (find them with: git -C <checkout> stash list | grep runner-rescue). Before restoring one, tell the user what it holds."
23+
echo "Stashes are in the checkout named there (find them with: git -C <checkout> for-each-ref refs/runner-rescue, and restore one with git stash apply <ref>). Before restoring one, tell the user what it holds."
2424
fi
2525
status=$(git -C "$dir" status --porcelain 2>/dev/null) || exit 0
2626
[ -n "$status" ] || exit 0
2727
count=$(printf '%s\n' "$status" | wc -l)
2828
echo "The checkout $dir is not clean at the start of this session: an earlier session left $count changed or untracked path(s)."
29-
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."
29+
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."
3030
printf '%s\n' "$status" | head -20
3131
[ "$count" -le 20 ] || echo "... and $((count - 20)) more"

‎modules/claude-self-hosted-runner/files/claude-runner-sweep‎

Lines changed: 27 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,15 @@
55
# Runs as the runner's post-session hook and before every runner start, so
66
# never while a session uses the directory (each runner has --capacity 1).
77
# Nothing a session left is deleted unless a commit or remote already holds it:
8-
# - Leftover changes in the runner's clones go into a "runner-rescue" stash.
8+
# - Leftover changes in the runner's clones go into a "runner-rescue" stash,
9+
# kept by a ref under refs/runner-rescue/. The runner clears the stash
10+
# reflog between sessions, so `git stash list` no longer shows the stash;
11+
# list rescues with `git for-each-ref refs/runner-rescue`.
912
# - Worktrees are removed, after stashing their changes the same way.
1013
# - Other clones, and broken worktrees, are deleted if they hold nothing
1114
# unpushed, and otherwise moved to the rescue directory,
1215
# ~/.local/state/claude-runner-rescue/<runner>/<time>/.
13-
# Every action is logged in the rescue directory's "log". Rescue stashes and
16+
# Every action is logged in the rescue directory's "log". Rescue refs and
1417
# directories older than CLAUDE_RUNNER_RESCUE_DAYS (default 30) are removed.
1518
# Portable to macOS: bash 3.2 and BSD date, find and sed.
1619
set -u
@@ -55,7 +58,17 @@ rescue_stash() {
5558
return 1
5659
fi
5760
fi
58-
note "stashed changes in $dir as \"$msg\""
61+
# The stash reflog doesn't survive to the next session; a ref does.
62+
local ref slug
63+
slug=$(printf '%s' "$session-$what" | tr -c 'A-Za-z0-9._-' '-')
64+
ref="refs/runner-rescue/$stamp-$slug"
65+
local n=1
66+
while git -C "$dir" show-ref -q --verify "$ref"; do
67+
n=$((n + 1))
68+
ref="refs/runner-rescue/$stamp-$slug-$n"
69+
done
70+
git -C "$dir" update-ref "$ref" refs/stash 2>/dev/null || ref="refs/stash"
71+
note "stashed changes in $dir as \"$msg\" ($ref)"
5972
}
6073

6174
# True when deleting this checkout loses nothing: no changes, no stashes and
@@ -93,6 +106,14 @@ done
93106
# Runner clones first, so their worktrees are gone before the second pass.
94107
for dir in ${candidates[@]+"${candidates[@]}"}; do
95108
is_runner_clone "$dir" || continue
109+
# Older sweeps kept rescues only as stashes. When refs/stash is one that no
110+
# rescue ref holds, give it a ref before another stash replaces it.
111+
old=$(git -C "$dir" rev-parse -q --verify refs/stash 2>/dev/null)
112+
if [ -n "$old" ] && git -C "$dir" log -1 --format=%s "$old" 2>/dev/null | grep -q runner-rescue &&
113+
! git -C "$dir" for-each-ref --format='%(objectname)' refs/runner-rescue/ 2>/dev/null | grep -qx "$old"; then
114+
ref="refs/runner-rescue/$(git -C "$dir" log -1 --format=%ct "$old")-earlier-sweep"
115+
git -C "$dir" update-ref "$ref" "$old" && note "kept the earlier rescue stash in $dir as $ref"
116+
fi
96117
# git prints worktree paths with symlinks resolved, as with macOS /var.
97118
real=$(cd "$dir" && pwd -P)
98119
while read -r wt; do
@@ -106,13 +127,10 @@ for dir in ${candidates[@]+"${candidates[@]}"}; do
106127
done < <(git -C "$dir" worktree list --porcelain 2>/dev/null | sed -n 's/^worktree //p')
107128
git -C "$dir" worktree prune 2>/dev/null
108129
rescue_stash "$dir" "checkout"
109-
# Drop expired rescue stashes, highest index (oldest) first, so the lower
110-
# indexes stay valid.
111130
cutoff=$(($(date +%s) - keep_days * 86400))
112-
git -C "$dir" stash list --format='%gd %ct %gs' 2>/dev/null | sort -t'{' -k2 -rn |
113-
while read -r ref ct subject; do
114-
case "$subject" in *runner-rescue*) ;; *) continue ;; esac
115-
[ "$ct" -lt "$cutoff" ] && git -C "$dir" stash drop --quiet "$ref" 2>/dev/null
131+
git -C "$dir" for-each-ref --format='%(refname) %(committerdate:unix)' refs/runner-rescue/ 2>/dev/null |
132+
while read -r ref ct; do
133+
[ "$ct" -lt "$cutoff" ] && git -C "$dir" update-ref -d "$ref" 2>/dev/null
116134
done
117135
done
118136

0 commit comments

Comments
 (0)