Skip to content

fix(runner): run claude-runner-sweep on macOS, keep rescues findable - #261

Open
rfay wants to merge 5 commits into
mainfrom
20261117_rfay_portable_runner_sweep
Open

rfay wants to merge 5 commits into
mainfrom
20261117_rfay_portable_runner_sweep

Conversation

@rfay

@rfay rfay commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Short Summary (TL;DR)

claude-runner-sweep now runs on macOS, and its rescues can be found again. The macOS Claude Code runner can use it as a post-session hook. Each rescue stash also gets a ref under refs/runner-rescue/, because the runner clears the stash list between sessions.

The Issue

The sweep cleans a self-hosted runner's checkouts after each session, and stashes uncommitted work as runner-rescue stashes.

  • The rescues were invisible. The runner clears each clone's stash reflog between sessions, so git stash list showed none of them, although the docs said to look there. Only the newest rescue per clone survived, as refs/stash, and the older ones were left for git gc. On a Coder runner workspace, the rescue log recorded 49 rescues, and git stash list showed none in any clone.
  • It didn't run correctly on macOS. The macOS runner reuses one checkout per repository across sessions, so it needs the sweep too:
    • Under macOS's bash 3.2, it exited with candidates[@]: unbound variable whenever the runner directory held no checkouts.
    • It logged with GNU date -Is, which BSD date may not support.
    • Behind a symlink, such as /var → /private/var, it didn't recognize the main checkout in git worktree list, which prints resolved paths. It labeled the checkout's stash as a worktree, and ran git worktree remove --force on the checkout, which git refused.

How This PR Solves The Issue

Change Why
A ref refs/runner-rescue/<time>-<session>-<what> for every rescue stash, with a counter when the name exists Refs survive the runner clearing the stash reflog, and no rescue overwrites another.
Adopt an earlier sweep's rescue still in refs/stash as refs/runner-rescue/<time>-earlier-sweep Rescues made before this change stay findable.
Expire rescue refs, instead of stash entries, after CLAUDE_RUNNER_RESCUE_DAYS The stash list is empty by the next session.
Docs, runner README, skill and SessionStart hook: git for-each-ref refs/runner-rescue and git stash apply <ref> That's where rescues are now. Leftovers a session stashes itself get a ref too.
${candidates[@]+"${candidates[@]}"} in both loops bash before 4.4 treats an empty array as unbound under set -u.
Log timestamps from date -u +%Y-%m-%dT%H:%M:%SZ Every date supports this format.
Compare worktree paths with the checkout's pwd -P too The main checkout is recognized behind a symlink.

Both module copies changed, through make sync-claude-runner-module.

Manual Testing Instructions

On a runner with this sweep as its post-session hook, start a session, leave an untracked file in its checkout, and end the session. Start a second session in the same repository and run:

git status --short
# Expect a clean checkout
git for-each-ref --format='%(refname) %(subject)' refs/runner-rescue
# Expect a ref whose subject says "runner-rescue … checkout on …"
git stash apply <that ref>
# Expect the untracked file back

Automated Testing Overview

Claude Code ran scenario scripts with bash 5.2 on Linux and with bash 3.2.57 in the bash:3.2 container, on a runner directory reached through a symlink:

  • The old sweep stashed a change, and .git/logs was deleted, as the runner does. The new sweep adopted that stash as a rescue ref.
  • Dirty changes in the checkout and in a worktree were stashed with refs, and the worktree was removed. The refs survived further .git/logs deletions.
  • Three sweeps in the same second gave three refs. Applying every ref restored every file.
  • CLAUDE_RUNNER_RESCUE_DAYS=-1 expired all rescue refs.
  • An empty runner directory returned 0. The old script exited 1 there under bash 3.2.

On a macOS 27.2.1 runner, the sweep ran as the post-session hook, with /bin/bash 3.2 and BSD tools. An earlier version found the symlink problem, and showed the session's own rescue missing from git stash list in the next session. With this version, one session left a dirty checkout, a dirty worktree, a pushed extra clone and an unpushed extra clone. After it ended, the next session found:

  • a clean checkout, with no worktree or extra clones
  • a rescue ref each for the checkout and the worktree, and an -earlier-sweep ref in every clone that still had a hidden rescue
  • the pushed clone deleted, and the unpushed clone moved to ~/.local/state/claude-runner-rescue/
  • git stash apply <ref> restoring the checkout's changes, including the untracked file
  • the hook finishing with exit 0 in about 8 seconds

🤖 Generated with Claude Code

https://claude.ai/code/session_01T3Cc2FfNKgEMqAZMMRVvjp

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Previews

Site Preview
docs.coder.ddev.com (docs/content, built by Read the Docs) https://coder-ddev--261.org.readthedocs.build/
start.coder.ddev.com (docs/*.html, deployed to gh-pages) https://start.coder.ddev.com/pr-preview/pr-261/

The landing-page preview creates workspaces on staging-coder.ddev.com, and its Documentation links open the docs preview. Read the Docs posts its build status and changed pages in its own comment; the docs preview may take a minute or two after a push to update.

Updated for 7cacb65

@rfay rfay changed the title fix(runner): make claude-runner-sweep work on macOS fix(runner): run claude-runner-sweep on macOS, keep rescues findable Nov 17, 2026
@read-the-docs-community

read-the-docs-community Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Documentation build overview

📚 coder-ddev | 🛠️ Build #35964105 | 📁 Comparing 7cacb65 against latest (4e928dc)

  🔍 Preview build  

1 file changed
± workspaces/ai-tools/index.html

claude-runner-sweep cleans a self-hosted runner's checkouts after each session. A macOS runner reuses one checkout per repository across sessions too, so it needs the same cleanup. Under macOS's bash 3.2 the script exited with "candidates[@]: unbound variable" when the runner directory held no checkouts. It also logged with GNU `date -Is`, which BSD date may not support. The script now expands the array safely, logs UTC timestamps in a format every date supports, and skips the `sessions` directory that the runner creates in its base directory on macOS, as it already skipped `_sessions`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T3Cc2FfNKgEMqAZMMRVvjp
git worktree list prints paths with symlinks resolved. When the runner directory sits behind a symlink, as under macOS /var, claude-runner-sweep didn't recognize the main checkout in that list. It labeled the checkout's stash as a worktree and ran git worktree remove --force on the checkout, which git refused. The sweep now compares worktree paths with the checkout's resolved path too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T3Cc2FfNKgEMqAZMMRVvjp
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
@rfay
rfay force-pushed the 20261117_rfay_portable_runner_sweep branch from 3f6be7a to cad7e74 Compare November 17, 2026 18:03
The macOS runner keeps session state in _sessions, like the Coder runner, so
the extra skip for sessions matched nothing.

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

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants