@oakgreencc/cambium 0.0.19 → 0.0.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -28,6 +28,7 @@ cambium status
28
28
  | `cambium resume` | Back to `running`. |
29
29
  | `cambium run task --issue <n> [--repo <owner/name>]` | Claim one open `q:task` issue, run its worker in the foreground, then make the same transition the daemon would. |
30
30
  | `cambium run <graph> --issue <n> [--repo <owner/name>] [--follow]` | `engine: "graph"` only (`task` is the one graph today). Advance one issue through the graph runtime in the foreground: a `q:task` issue without a lease starts with a foreground worker; anything else resumes where its marker rests. Stops at the first wait that is not ready; `--follow` re-reads and polls every `tickSeconds` until the graph ends. |
31
+ | `cambium gc [--dry-run] [--repo <owner/name>]` | Collect worktrees now; `--dry-run` only reports. See [Worktree GC](#worktree-gc). |
31
32
  | `cambium install [--dry-run]` | Write the launchd agent (`KeepAlive`, `RunAtLoad`) for `start --config <this config>`; `--dry-run` prints it. It does not call `launchctl`; it prints the command. |
32
33
  | `cambium update [--check] [--version <v>]` | Install the latest version (or `<v>`, even an older one) from npm into this global install, then SIGTERM the launchd agent so it finishes its tick and KeepAlive starts the new version. `--check` only reports. No config file needed. See [Self-update](#self-update). |
33
34
 
@@ -38,7 +39,7 @@ Every command takes `--config <file>`; the default is `$CAMBIUM_CONFIG`, then `~
38
39
  Each step is bounded by `stepTimeoutSeconds`. A step that throws or times out is logged and recorded in the heartbeat, and the tick moves on. Nothing waits on a worker.
39
40
 
40
41
  1. **Read.** One GraphQL query per repo (`graft graphql`): open issues with any `q:` label, open and recently merged PRs on `agent/*` with their check rollup, merge-queue state and the issues they close. GitHub links closing references only for a PR into the default branch, so cambium also reads `Closes/Fixes/Resolves #n` from the PR body, fetching issues the first query did not read in one more. A worker's PR that names no issue (found by its branch) gets `Closes #n` added at submission.
41
- 2. **Reconcile.** For each tracked worker: alive and under its wall-clock cap → nothing. Over the cap → kill its process group. Gone → exit check (a PR on its branch, or closing its issue, that is open or merged and not still on the commit CI already failed) → `submitted`; otherwise requeue with the stderr tail (a failed prepare step requeues as `spawn-failed`). Then the worktree is torn down if `graft status` says GitHub holds everything in it, else kept with a `warn` saying why.
42
+ 2. **Reconcile.** For each tracked worker: alive and under its wall-clock cap → nothing. Over the cap → kill its process group and every descendant (Claude Code runs each Bash command in a group of its own, so a group kill alone left a test run loading the next attempt). Gone → exit check (a PR on its branch, or closing its issue, that is open or merged and not still on the commit CI already failed) → `submitted`; otherwise requeue with the stderr tail (a failed prepare step requeues as `spawn-failed`). Then the worktree is torn down if `graft status` says GitHub holds everything in it, else kept with a `warn` saying why.
42
43
  3. **Watch** (no agent), for agent PRs whose issue is in no queue: merged → close the issue, delete the branch; red → requeue with the failing checks' summaries; left the merge queue without merging → requeue; not merged `mergeQueueMinutes` after submission → `q:human`.
43
44
  4. **Sweep.** An issue labelled `running` with this host (or no host) in its marker and no tracked worker → requeue. This is what makes losing the SQLite file cost one requeue.
44
45
  5. **Schedule.** Start Task workers for `q:task` issues without `running`, by priority label then age, up to `phases.task.cap` counted from live workers. A task requeued earlier in the same tick can start in that tick. Then, with `engine: "graph"` and `phases.dispatch.cap > 0`, start triage workers for `q:intake` issues the same way ([the dispatch graph](#the-dispatch-graph)).
@@ -81,7 +82,7 @@ A worker is `claude -p --output-format stream-json --verbose --max-turns <maxTur
81
82
 
82
83
  - in its own worktree, by the target repo's [worktree convention](#target-repo-convention);
83
84
  - behind the prepare step: `node src/prepare.mjs -- claude …` runs install-fresh, hydrate and the repo's `prepare` commands in the worktree, writing to the worker's stderr log, then becomes the worker. It runs in the detached process so a long install never blocks a tick;
84
- - detached, leading its own process group (a kill takes its children), stdin from the prompt file;
85
+ - detached, leading its own process group (a kill takes the group and, by a `ps` snapshot, every descendant), stdin from the prompt file;
85
86
  - with `CAMBIUM_REPO`, `CAMBIUM_ISSUE`, `CAMBIUM_PHASE`, `CAMBIUM_BRANCH` set, `GRAFT_APP=<worker.graftApp>` when configured, then `worker.env`, then `TRACEPARENT` (the starting node's span) when [tracing](#tracing) is on;
86
87
  - with its prompt, stdout and stderr at `<paths.logs>/<owner>__<name>/issue-<n>/a<attempt>-<stamp>.{prompt.md,out.log,err.log}`, keeping the newest `logs.keepPerIssue` runs per issue.
87
88
 
@@ -115,7 +116,8 @@ One JSON file. Everything but `repos` is optional; these are the defaults:
115
116
  "logs": { "keepPerIssue": 20, "daemonMaxBytes": 10485760 },
116
117
  "graft": { "command": "graft", "app": null, "botLogin": null },
117
118
  "worker": { "command": "claude", "args": [], "graftApp": null, "fetch": true, "env": {} },
118
- "update": { "auto": false, "checkMinutes": 360 }
119
+ "update": { "auto": false, "checkMinutes": 360 },
120
+ "gc": { "everyMinutes": 60, "graceMinutes": 60, "staleDays": 14 }
119
121
  }
120
122
  ```
121
123
 
@@ -157,6 +159,16 @@ How a repo's worktrees are made is the repo's call: a `"cambium"` key in its roo
157
159
 
158
160
  The key decides which commands run on this host, so list `package.json` as protected (CODEOWNERS) in the target repo, next to its `"graft"` policy.
159
161
 
162
+ ## Worktree GC
163
+
164
+ Every `gc.everyMinutes` (0: off; `cambium gc` still works) the daemon looks at each worktree under a repo's convention root, the checkout itself never. Skipped: a cambium worker's, a locked one (a Claude Code session lock counts only while its pid is alive with the start it names), and one touched within `gc.graceMinutes` (its directory, HEAD, reflog or a dirty path). The rest:
165
+
166
+ - **complete**: `graft status` says GitHub holds all of it. Removed, with its local branch.
167
+ - **stale**: idle `gc.staleDays` with work GitHub lacks. Archived to `<home>/gc/<owner>__<name>/<dir>-<stamp>/` (`commits.bundle` of HEAD less `origin/<base>`, `changes.patch`, `untracked/`, `worktree.json`), then removed. Restore commits with `git fetch <bundle> HEAD:<branch>`.
168
+ - **kept**: anything else; `cambium gc --dry-run` says why.
169
+
170
+ A worktree whose directory is gone is pruned. The sweep is not awaited by the tick; removals and archives are logged.
171
+
160
172
  ## Self-update
161
173
 
162
174
  cambium updates itself only when it is a **global npm install** (`<prefix>/lib/node_modules/@oakgreencc/cambium`, e.g. nvm's or Homebrew's prefix), and only into that same prefix, so the launchd agent's node and bin paths stay valid. A source checkout (`pnpm start`), an `npm link` or a copy inside another package's `node_modules` is left to whoever installed it. npm is the one next to the running Node, else `npm` on `PATH`; the version is the registry's `latest` dist-tag.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oakgreencc/cambium",
3
- "version": "0.0.19",
3
+ "version": "0.0.21",
4
4
  "description": "The scheduler daemon: reads the q:* queues from GitHub every tick, runs headless claude workers in their own worktrees up to a cap, and makes every queue transition itself.",
5
5
  "license": "AGPL-3.0-only",
6
6
  "type": "module",
package/src/cli.mjs CHANGED
@@ -9,6 +9,7 @@ import { homedir } from 'node:os'
9
9
  import { dirname, resolve } from 'node:path'
10
10
  import { fileURLToPath } from 'node:url'
11
11
  import { configPath, loadConfig } from './config.mjs'
12
+ import { collectGarbage, describe } from './gc.mjs'
12
13
  import { acquireLock, readHeartbeat, realDeps, runDaemon } from './daemon.mjs'
13
14
  import { plist, plistPath } from './launchd.mjs'
14
15
  import { openStore } from './store.mjs'
@@ -31,6 +32,9 @@ export const HELP = `cambium ${VERSION} — the scheduler daemon
31
32
  cambium run <graph> --issue <n> [--repo <owner/name>] [--follow]
32
33
  engine "graph": advance the issue in the foreground to the first wait
33
34
  that is not ready; --follow keeps polling until the graph ends
35
+ cambium gc [--dry-run] [--repo <owner/name>]
36
+ remove worktrees GitHub holds all of; archive (to ~/.cambium/gc) then
37
+ remove stale ones; skip live workers and live Claude Code sessions
34
38
  cambium install [--dry-run] write the launchd agent (KeepAlive); --dry-run prints it
35
39
  cambium update [--check] [--version <v>]
36
40
  install the latest (or <v>) from npm into this global install, then
@@ -138,12 +142,34 @@ export async function main(argv, io) {
138
142
  }
139
143
  case 'run':
140
144
  return runOne(config, rest, io, depsFor)
145
+ case 'gc':
146
+ return gc(config, rest, io, depsFor)
141
147
  case 'install':
142
148
  return install(cfgPath, config, io, has(rest, '--dry-run'))
143
149
  }
144
150
  return fail(io, `unknown verb "${verb}"\n\n${HELP}`)
145
151
  }
146
152
 
153
+ /**
154
+ * @param {import('./config.mjs').Config} config @param {string[]} argv @param {IO} io
155
+ * @param {(c: import('./config.mjs').Config) => import('./tick.mjs').Deps} depsFor
156
+ */
157
+ async function gc(config, argv, io, depsFor) {
158
+ const repo = flag(argv, '--repo')
159
+ if (repo && !config.repos.some((r) => r.slug === repo)) return fail(io, `no repo ${repo} in the config`)
160
+ const deps = depsFor(config)
161
+ const dryRun = has(argv, '--dry-run')
162
+ try {
163
+ const out = await collectGarbage({ ...deps, now: deps.clock.now }, { dryRun, repo })
164
+ for (const o of out) io.out(describe(o))
165
+ if (!out.length) io.out('no worktrees')
166
+ else if (dryRun) io.out('(dry run: nothing changed)')
167
+ return 0
168
+ } finally {
169
+ deps.store.close?.()
170
+ }
171
+ }
172
+
147
173
  /** @param {IO} io @param {string} msg */
148
174
  function fail(io, msg) {
149
175
  io.err(`cambium: ${msg}`)
package/src/config.mjs CHANGED
@@ -34,7 +34,12 @@ import { join, resolve } from 'node:path'
34
34
  * graft: { command: string, app: string | null, botLogin: string | null },
35
35
  * worker: { command: string, args: string[], graftApp: string | null, fetch: boolean, env: Record<string, string> },
36
36
  * update: { auto: boolean, checkMinutes: number },
37
+ * gc: GcConfig,
37
38
  * }} Config
39
+ * @typedef {{ everyMinutes: number, graceMinutes: number, staleDays: number }} GcConfig
40
+ * Worktree garbage collection (gc.mjs): the daemon sweeps every `everyMinutes` (0: only `cambium gc`). A
41
+ * worktree touched within `graceMinutes` is left alone; one idle `staleDays` with work GitHub lacks is
42
+ * archived under `<home>/gc/`, then removed.
38
43
  */
39
44
 
40
45
  /** @type {readonly MergePolicy[]} */
@@ -68,6 +73,7 @@ export function defaults(home = DEFAULT_HOME) {
68
73
  graft: { command: 'graft', app: null, botLogin: null },
69
74
  worker: { command: 'claude', args: [], graftApp: null, fetch: true, env: {} },
70
75
  update: { auto: false, checkMinutes: 360 },
76
+ gc: { everyMinutes: 60, graceMinutes: 60, staleDays: 14 },
71
77
  }
72
78
  }
73
79
 
@@ -129,6 +135,9 @@ export function resolveConfig(raw = {}) {
129
135
  throw new Error('config: worker.env must be an object of string values')
130
136
  if (typeof config.update.auto !== 'boolean') throw new Error('config: update.auto must be true or false')
131
137
  if (!(Number(config.update.checkMinutes) >= 5)) throw new Error('config: update.checkMinutes must be at least 5')
138
+ for (const k of /** @type {const} */ (['everyMinutes', 'graceMinutes', 'staleDays']))
139
+ if (!(typeof config.gc[k] === 'number' && config.gc[k] >= 0))
140
+ throw new Error(`config: gc.${k} must be a number, at least 0`)
132
141
  if (config.engine !== 'legacy' && config.engine !== 'graph')
133
142
  throw new Error(`config: engine must be "legacy" or "graph", got ${JSON.stringify(config.engine)}`)
134
143
  const merging = config.repos.filter((r) => r.merge === 'green')
package/src/daemon.mjs CHANGED
@@ -3,6 +3,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSy
3
3
  import { dirname, join } from 'node:path'
4
4
  import { setTimeout as sleep } from 'node:timers/promises'
5
5
  import { applyReload } from './config.mjs'
6
+ import { gcRunner } from './gc.mjs'
6
7
  import { graftGitHub } from './github.mjs'
7
8
  import { openStore } from './store.mjs'
8
9
  import { tick } from './tick.mjs'
@@ -69,13 +70,15 @@ export function realDeps(config, { echo } = {}) {
69
70
  maxBytes: config.logs.daemonMaxBytes,
70
71
  echo,
71
72
  })
73
+ const spawner = processSpawner({ config })
72
74
  return {
73
75
  config,
74
76
  clock: { now: Date.now },
75
77
  github: graftGitHub({ config }),
76
78
  store,
77
- spawner: processSpawner({ config }),
79
+ spawner,
78
80
  procs: realProcs,
81
+ gc: gcRunner({ config, store, spawner, procs: realProcs, now: Date.now }, log),
79
82
  log,
80
83
  events,
81
84
  heartbeat: (state) => writeHeartbeat(config.paths.heartbeat, state),
package/src/gc.mjs ADDED
@@ -0,0 +1,314 @@
1
+ // @ts-check
2
+ /**
3
+ * Worktree garbage collection. Every worktree under a repo's convention root
4
+ * that no live worker and no live Claude Code session holds ends one of three ways:
5
+ *
6
+ * complete — `graft status` says GitHub holds all of it: removed, with its local branch;
7
+ * stale — idle `gc.staleDays` with work GitHub lacks: archived under `<home>/gc/`
8
+ * (a bundle of the commits the base lacks, the uncommitted diff, the untracked files), then removed;
9
+ * kept — anything else, with the reason.
10
+ *
11
+ * A worktree touched within `gc.graceMinutes` is left alone; one whose directory is gone is pruned.
12
+ * A lock is respected unless it names a Claude Code session whose process is gone.
13
+ */
14
+ import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
15
+ import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path'
16
+ import { exec as defaultExec } from './github.mjs'
17
+ import { slugDir } from './workers.mjs'
18
+
19
+ const MIN = 60_000
20
+ const DAY = 24 * 60 * MIN
21
+
22
+ /**
23
+ * @typedef {{ path: string, head: string | null, branch: string | null, locked: string | null, prunable: boolean }} Entry
24
+ * @typedef {'removed' | 'archived' | 'pruned' | 'kept' | 'skipped'} Action
25
+ * @typedef {{ repo: string, worktree: string, action: Action, reason: string | null, archive?: string }} Outcome
26
+ * @typedef {{
27
+ * config: import('./config.mjs').Config,
28
+ * store: Pick<import('./store.mjs').Store, 'workers'>,
29
+ * spawner: Pick<import('./workers.mjs').Spawner, 'convention' | 'held' | 'cleanup'>,
30
+ * procs: Pick<import('./workers.mjs').Procs, 'alive'>,
31
+ * now: () => number,
32
+ * exec?: import('./github.mjs').Exec,
33
+ * stamp?: () => string,
34
+ * }} GcDeps
35
+ * @typedef {{ dryRun?: boolean, repo?: string }} GcOptions
36
+ */
37
+
38
+ /** @type {Record<string, (e: Entry, v: string) => void>} */
39
+ const FIELDS = {
40
+ worktree: (e, v) => {
41
+ e.path = v
42
+ },
43
+ HEAD: (e, v) => {
44
+ e.head = v
45
+ },
46
+ branch: (e, v) => {
47
+ e.branch = v.replace(/^refs\/heads\//, '')
48
+ },
49
+ locked: (e, v) => {
50
+ e.locked = v
51
+ },
52
+ prunable: (e) => {
53
+ e.prunable = true
54
+ },
55
+ }
56
+
57
+ /** `git worktree list --porcelain` → its entries. @param {string} out @returns {Entry[]} */
58
+ export function parseWorktrees(out) {
59
+ return out
60
+ .split(/\n\s*\n/)
61
+ .filter((b) => b.trim())
62
+ .map((block) => {
63
+ /** @type {Entry} */
64
+ const e = { path: '', head: null, branch: null, locked: null, prunable: false }
65
+ for (const line of block.split('\n')) {
66
+ const at = line.indexOf(' ')
67
+ const [k, v] = at === -1 ? [line, ''] : [line.slice(0, at), line.slice(at + 1)]
68
+ FIELDS[k]?.(e, v)
69
+ }
70
+ return e
71
+ })
72
+ }
73
+
74
+ /** A Claude Code session lock's reason → its pid and start (UTC), or null. @param {string} reason */
75
+ export function sessionLock(reason) {
76
+ const m = /^claude session .*\(pid (\d+) start ([^)]+)\)$/.exec(reason.trim())
77
+ return m ? { pid: Number(m[1]), start: m[2] } : null
78
+ }
79
+
80
+ /** `child` is strictly inside `root`. @param {string} root @param {string} child */
81
+ export const inside = (root, child) => {
82
+ const rel = relative(root, child)
83
+ return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel)
84
+ }
85
+
86
+ /** @param {string} p */
87
+ const real = (p) => {
88
+ try {
89
+ return realpathSync(p)
90
+ } catch {
91
+ return resolve(p)
92
+ }
93
+ }
94
+
95
+ /** @param {string} s */
96
+ const utc = (s) => Date.parse(`${s.trim().replace(/\s+/g, ' ')} UTC`)
97
+
98
+ /**
99
+ * Whether a lock still holds. Anything but a Claude Code session lock always does; a session lock
100
+ * holds while its pid is alive with the start it names. An unreadable start counts as a match.
101
+ *
102
+ * @param {GcDeps} deps @param {string | null} reason
103
+ */
104
+ export async function lockHolds(deps, reason) {
105
+ if (reason === null) return false
106
+ const s = sessionLock(reason)
107
+ if (!s) return true
108
+ if (!deps.procs.alive(s.pid)) return false
109
+ const run = deps.exec ?? defaultExec
110
+ const out = await run('ps', ['-o', 'lstart=', '-p', String(s.pid)], { env: { ...process.env, TZ: 'UTC' } }).catch(
111
+ () => '',
112
+ )
113
+ const [a, b] = [utc(out), utc(s.start)]
114
+ return Number.isNaN(a) || Number.isNaN(b) || Math.abs(a - b) < 2000
115
+ }
116
+
117
+ /** @param {string} p */
118
+ const mtime = (p) => {
119
+ try {
120
+ return lstatSync(p).mtimeMs
121
+ } catch {
122
+ return 0
123
+ }
124
+ }
125
+
126
+ /** The worktree's git directory, from its `.git` file. @param {string} wt */
127
+ function gitDirOf(wt) {
128
+ try {
129
+ const m = /^gitdir: (.+)$/m.exec(readFileSync(join(wt, '.git'), 'utf8'))
130
+ return m ? resolve(wt, m[1].trim()) : null
131
+ } catch {
132
+ return null
133
+ }
134
+ }
135
+
136
+ /**
137
+ * The last time anything in a worktree moved: its directory, its HEAD and reflog, and every path
138
+ * `git status` reports. Not the index: any `git status` (graft's included) rewrites it.
139
+ *
140
+ * @param {(args: string[]) => Promise<string>} git runs in the worktree @param {string} wt
141
+ */
142
+ export async function lastActivity(git, wt) {
143
+ const gd = gitDirOf(wt)
144
+ const paths = [wt, ...(gd ? ['HEAD', 'logs/HEAD'].map((f) => join(gd, f)) : [])]
145
+ const status = await git([
146
+ '--no-optional-locks',
147
+ 'status',
148
+ '--porcelain',
149
+ '-z',
150
+ '--no-renames',
151
+ '--untracked-files=all',
152
+ ]).catch(() => '')
153
+ for (const rec of status.split('\0')) if (rec.length > 3) paths.push(join(wt, rec.slice(3)))
154
+ return Math.max(...paths.map(mtime))
155
+ }
156
+
157
+ /**
158
+ * Save what GitHub may lack before a stale worktree goes: `commits.bundle` (HEAD less the base),
159
+ * `changes.patch` (`git diff --binary HEAD`), `untracked/`, and `worktree.json`.
160
+ *
161
+ * @param {GcDeps} deps @param {import('./config.mjs').Repo} repo @param {Entry} e
162
+ * @param {(args: string[]) => Promise<string>} git runs in the worktree @param {string} why
163
+ * @returns {Promise<string>} the archive directory
164
+ */
165
+ export async function archive(deps, repo, e, git, why) {
166
+ const stamp = (deps.stamp ?? (() => new Date(deps.now()).toISOString().replace(/[:.]/g, '-')))()
167
+ const dir = join(deps.config.paths.home, 'gc', slugDir(repo.slug), `${basename(e.path)}-${stamp}`)
168
+ mkdirSync(dir, { recursive: true })
169
+ const base = `refs/remotes/origin/${repo.baseBranch}`
170
+ const not = (await git(['rev-parse', '--verify', '-q', base]).catch(() => '')).trim() ? ['--not', base] : []
171
+ const ahead = Number((await git(['rev-list', '--count', 'HEAD', ...not]).catch(() => '0')).trim())
172
+ if (ahead > 0) await git(['bundle', 'create', join(dir, 'commits.bundle'), 'HEAD', ...not])
173
+ const diff = await git(['diff', '--binary', 'HEAD']).catch(() => '')
174
+ if (diff) writeFileSync(join(dir, 'changes.patch'), diff)
175
+ const untracked = (await git(['ls-files', '-z', '--others', '--exclude-standard'])).split('\0').filter(Boolean)
176
+ for (const f of untracked) {
177
+ mkdirSync(dirname(join(dir, 'untracked', f)), { recursive: true })
178
+ cpSync(join(e.path, f), join(dir, 'untracked', f), { recursive: true, verbatimSymlinks: true })
179
+ }
180
+ const info = { worktree: e.path, branch: e.branch, head: e.head, commits: ahead, reason: why, at: stamp }
181
+ writeFileSync(join(dir, 'worktree.json'), `${JSON.stringify(info, null, 2)}\n`)
182
+ return dir
183
+ }
184
+
185
+ /**
186
+ * @typedef {{
187
+ * repo: import('./config.mjs').Repo, e: Entry, dryRun: boolean, workers: Set<string>,
188
+ * git: (args: string[], cwd?: string) => Promise<string>,
189
+ * }} One
190
+ */
191
+
192
+ /** Why this worktree is not looked at, or null. @param {GcDeps} deps @param {One} one */
193
+ async function skipped(deps, { e, workers }) {
194
+ if (workers.has(real(e.path))) return 'a cambium worker holds it'
195
+ if (await lockHolds(deps, e.locked)) return `locked: ${e.locked || 'no reason given'}`
196
+ return null
197
+ }
198
+
199
+ /** @param {number} ms */
200
+ const ago = (ms) => (ms >= DAY ? `${Math.floor(ms / DAY)}d` : `${Math.floor(ms / MIN)}m`)
201
+
202
+ /** @param {GcDeps} deps @param {One} one @returns {Promise<Omit<Outcome, 'repo' | 'worktree'>>} */
203
+ async function collectOne(deps, one) {
204
+ const { repo, e, dryRun, git } = one
205
+ if (e.prunable || !existsSync(e.path)) return { action: 'pruned', reason: 'its directory is gone' }
206
+ const skip = await skipped(deps, one)
207
+ if (skip) return { action: 'skipped', reason: skip }
208
+ const wt = (/** @type {string[]} */ args) => git(args, e.path)
209
+ const idle = deps.now() - (await lastActivity(wt, e.path))
210
+ if (idle < deps.config.gc.graceMinutes * MIN) return { action: 'skipped', reason: `active ${ago(idle)} ago` }
211
+ const w = { repo, worktree: e.path, branch: e.branch ?? '' }
212
+ const h = await deps.spawner.held(w)
213
+ if (h.clean) return complete(deps, one, w)
214
+ if (idle < deps.config.gc.staleDays * DAY) return { action: 'kept', reason: h.reason }
215
+ const why = `stale: idle ${ago(idle)}; ${h.reason}`
216
+ if (dryRun) return { action: 'archived', reason: why }
217
+ const dir = await archive(deps, repo, e, wt, why)
218
+ await git(['worktree', 'remove', '--force', '--force', e.path])
219
+ if (e.branch) await git(['branch', '-D', e.branch]).catch(() => {})
220
+ return { action: 'archived', reason: why, archive: dir }
221
+ }
222
+
223
+ /**
224
+ * @param {GcDeps} deps @param {One} one @param {{ repo: import('./config.mjs').Repo, worktree: string, branch: string }} w
225
+ * @returns {Promise<Omit<Outcome, 'repo' | 'worktree'>>}
226
+ */
227
+ async function complete(deps, { e, dryRun, git }, w) {
228
+ const reason = 'complete: GitHub holds all of it'
229
+ if (dryRun) return { action: 'removed', reason }
230
+ if (e.locked !== null) await git(['worktree', 'unlock', e.path])
231
+ const t = await deps.spawner.cleanup(w)
232
+ return t.removed ? { action: 'removed', reason } : { action: 'kept', reason: t.reason }
233
+ }
234
+
235
+ /**
236
+ * Collect one repo's worktrees. Only those under its convention root are looked at, never the checkout itself.
237
+ *
238
+ * @param {GcDeps} deps @param {import('./config.mjs').Repo} repo @param {boolean} dryRun
239
+ * @returns {Promise<Outcome[]>}
240
+ */
241
+ async function collectRepo(deps, repo, dryRun) {
242
+ const run = deps.exec ?? defaultExec
243
+ const git = (/** @type {string[]} */ args, cwd = repo.path) => run('git', ['-C', cwd, ...args])
244
+ const root = real(deps.spawner.convention(repo).root)
245
+ const workers = new Set(
246
+ deps.store
247
+ .workers()
248
+ .filter((w) => w.repo === repo.slug)
249
+ .map((w) => real(w.worktree)),
250
+ )
251
+ const entries = parseWorktrees(await git(['worktree', 'list', '--porcelain'])).filter((e) => inside(root, e.path))
252
+ /** @type {Outcome[]} */
253
+ const out = []
254
+ for (const e of entries) {
255
+ try {
256
+ out.push({ repo: repo.slug, worktree: e.path, ...(await collectOne(deps, { repo, e, dryRun, workers, git })) })
257
+ } catch (err) {
258
+ out.push({
259
+ repo: repo.slug,
260
+ worktree: e.path,
261
+ action: 'kept',
262
+ reason: /** @type {Error} */ (err)?.message ?? String(err),
263
+ })
264
+ }
265
+ }
266
+ if (!dryRun && out.some((o) => o.action === 'pruned')) await git(['worktree', 'prune']).catch(() => {})
267
+ return out
268
+ }
269
+
270
+ /**
271
+ * Collect every configured repo's worktrees (or only `repo`'s). `dryRun` reports what would happen.
272
+ *
273
+ * @param {GcDeps} deps @param {GcOptions} [opts]
274
+ * @returns {Promise<Outcome[]>}
275
+ */
276
+ export async function collectGarbage(deps, { dryRun = false, repo } = {}) {
277
+ /** @type {Outcome[]} */
278
+ const out = []
279
+ for (const r of deps.config.repos) if (!repo || r.slug === repo) out.push(...(await collectRepo(deps, r, dryRun)))
280
+ return out
281
+ }
282
+
283
+ /** One line per outcome. @param {Outcome} o */
284
+ export const describe = (o) =>
285
+ `${o.action.padEnd(8)} ${o.worktree}${o.reason ? ` (${o.reason})` : ''}${o.archive ? `\n archive ${o.archive}` : ''}`
286
+
287
+ /**
288
+ * The daemon's sweep: at most one run at a time, never awaited by the tick (a run checks each worktree
289
+ * with GitHub and can outlast a step). What it removed, archived or pruned is logged.
290
+ *
291
+ * @param {GcDeps} deps @param {import('./tick.mjs').Deps['log']} log
292
+ * @returns {() => Promise<Outcome[] | null>} null while a run is in flight
293
+ */
294
+ export function gcRunner(deps, log) {
295
+ /** @type {Promise<Outcome[]> | null} */
296
+ let running = null
297
+ return () => {
298
+ if (running) return Promise.resolve(null)
299
+ running = collectGarbage(deps)
300
+ .then((out) => {
301
+ for (const o of out)
302
+ if (o.action !== 'kept' && o.action !== 'skipped') log('info', `gc: ${describe(o)}`, { repo: o.repo })
303
+ return out
304
+ })
305
+ .catch((err) => {
306
+ log('error', `gc: ${/** @type {Error} */ (err)?.message ?? err}`)
307
+ return []
308
+ })
309
+ .finally(() => {
310
+ running = null
311
+ })
312
+ return running
313
+ }
314
+ }
package/src/github.mjs CHANGED
@@ -278,6 +278,8 @@ export function exec(cmd, args, { input, cwd, env } = {}) {
278
278
  child.on('close', (code) =>
279
279
  code === 0 ? resolveOut(out) : reject(new Error(`${cmd} ${args[0]} exited ${code}: ${err.trim() || out.trim()}`)),
280
280
  )
281
+ // A child that exits without reading stdin (EPIPE) is judged by its exit code, not by the write.
282
+ child.stdin.on('error', () => {})
281
283
  child.stdin.end(input ?? '')
282
284
  })
283
285
  }
package/src/tick.mjs CHANGED
@@ -1,6 +1,6 @@
1
1
  // @ts-check
2
2
  /**
3
- * One tick: Read → Reconcile → Watch → Sweep → Schedule → Release →
3
+ * One tick: Read → Reconcile → Watch → Sweep → Schedule → Release → GC →
4
4
  * Heartbeat. Every collaborator is injected ({@link Deps}); the daemon is a
5
5
  * loop around this function. Each step is bounded by `stepTimeoutSeconds`; a
6
6
  * step that throws or times out is recorded and the tick moves on. Nothing
@@ -37,6 +37,7 @@ import { DISPATCH_NOT_BUILT, dispatchNotBuilt } from './phases/dispatch.mjs'
37
37
  * tickNumber?: number,
38
38
  * telemetry?: import('./tracing.mjs').Telemetry,
39
39
  * updater?: import('./update.mjs').Updater,
40
+ * gc?: () => Promise<unknown>,
40
41
  * daemonStartedAt?: number,
41
42
  * pid?: number,
42
43
  * }} Deps
@@ -92,6 +93,7 @@ export async function tick(deps) {
92
93
  ])),
93
94
  ...(ctx.mode === 'running' ? /** @type {[string, StepFn][]} */ ([['schedule', schedule]]) : []),
94
95
  ...(paused ? [] : /** @type {[string, any][]} */ ([['release', release]])),
96
+ ...(paused || !deps.gc ? [] : /** @type {[string, StepFn][]} */ ([['gc', gc]])),
95
97
  ]
96
98
  for (const [name, fn] of steps) await runStep(deps, ctx, name, () => fn(deps, ctx))
97
99
  const state = heartbeatState(deps, ctx)
@@ -575,6 +577,22 @@ export async function startTask(deps, ctx, slug, issue, snap, { foreground = fal
575
577
  return { ...started, attempt: marker.attempt }
576
578
  }
577
579
 
580
+ // ---- GC
581
+
582
+ /**
583
+ * Start a worktree sweep (gc.mjs) every `gc.everyMinutes`; 0 switches it off. Not awaited: a sweep asks
584
+ * GitHub about each worktree and can outlast the step.
585
+ *
586
+ * @param {Deps} deps @param {Ctx} ctx
587
+ */
588
+ async function gc(deps, ctx) {
589
+ const every = deps.config.gc.everyMinutes
590
+ const last = Number(deps.store.get('gc.lastRun') ?? 0)
591
+ if (!every || ctx.now - last < every * MIN) return
592
+ deps.store.set('gc.lastRun', String(ctx.now))
593
+ void deps.gc?.()
594
+ }
595
+
578
596
  // ---- Release (no agent). Legacy: once a day, the run is a seam. Graph: the release-prepare / release-promote
579
597
  // graphs (graphs/release.mjs), per repo.
580
598
 
package/src/workers.mjs CHANGED
@@ -5,7 +5,7 @@
5
5
  * group, behind the prepare step, with its output in rotated log files on this
6
6
  * host, and {@link Procs} to probe and kill by pid.
7
7
  */
8
- import { spawn } from 'node:child_process'
8
+ import { spawn, spawnSync } from 'node:child_process'
9
9
  import {
10
10
  closeSync,
11
11
  existsSync,
@@ -38,10 +38,12 @@ import { exec as defaultExec } from './github.mjs'
38
38
  * reused: string | null,
39
39
  * }} Started `reused`: why the previous attempt's worktree was kept, when it was
40
40
  * @typedef {{ removed: boolean, reason: string | null }} Teardown
41
+ * @typedef {{ clean: boolean, reason: string | null }} Held `clean`: `graft status` says GitHub holds all of it
41
42
  * @typedef {{
42
43
  * convention(repo: import('./config.mjs').Repo): Convention,
43
44
  * start(spec: StartSpec): Promise<Started>,
44
45
  * cleanup(w: { repo: import('./config.mjs').Repo, worktree: string, branch: string, readOnly?: boolean }): Promise<Teardown>,
46
+ * held(w: { repo: import('./config.mjs').Repo, worktree: string, branch: string }): Promise<Held>,
45
47
  * tail(path: string, lines?: number): string,
46
48
  * readLog(path: string): string,
47
49
  * }} Spawner
@@ -167,10 +169,37 @@ export function processSpawner({
167
169
  }
168
170
 
169
171
  /**
170
- * Remove a worktree only once `graft status` says GitHub holds everything in
171
- * it; otherwise keep it and say why. Its local branch goes with it.
172
+ * Whether GitHub holds everything in a worktree, per `graft status`. An empty `branch` (a detached HEAD)
173
+ * is left out of the call.
172
174
  *
173
175
  * @param {{ repo: import('./config.mjs').Repo, worktree: string, branch: string }} w
176
+ * @returns {Promise<Held>}
177
+ */
178
+ async function held({ repo, worktree, branch }) {
179
+ let out
180
+ try {
181
+ out = await exec(
182
+ config.graft.command,
183
+ ['status', ...(branch ? [branch] : []), '-C', worktree, '--repo', repo.slug],
184
+ {
185
+ cwd: worktree,
186
+ env: graftEnv,
187
+ },
188
+ )
189
+ } catch (err) {
190
+ return { clean: false, reason: `graft status failed: ${/** @type {Error} */ (err)?.message ?? err}` }
191
+ }
192
+ const verdict = out.trim().split('\n').at(-1) ?? ''
193
+ return verdict === GRAFT_CLEAN
194
+ ? { clean: true, reason: null }
195
+ : { clean: false, reason: verdict || 'graft status printed nothing' }
196
+ }
197
+
198
+ /**
199
+ * Remove a worktree only once {@link held} says GitHub holds everything in
200
+ * it; otherwise keep it and say why. Its local branch goes with it.
201
+ *
202
+ * @param {{ repo: import('./config.mjs').Repo, worktree: string, branch: string, readOnly?: boolean }} w
174
203
  * @returns {Promise<Teardown>}
175
204
  */
176
205
  async function teardown({ repo, worktree, branch, readOnly = false }) {
@@ -179,17 +208,8 @@ export function processSpawner({
179
208
  await git(repo.path, ['worktree', 'prune']).catch(() => {})
180
209
  return { removed: true, reason: null }
181
210
  }
182
- let out
183
- try {
184
- out = await exec(config.graft.command, ['status', branch, '-C', worktree, '--repo', repo.slug], {
185
- cwd: worktree,
186
- env: graftEnv,
187
- })
188
- } catch (err) {
189
- return { removed: false, reason: `graft status failed: ${/** @type {Error} */ (err)?.message ?? err}` }
190
- }
191
- const verdict = out.trim().split('\n').at(-1) ?? ''
192
- if (verdict !== GRAFT_CLEAN) return { removed: false, reason: verdict || 'graft status printed nothing' }
211
+ const h = await held({ repo, worktree, branch })
212
+ if (!h.clean) return { removed: false, reason: h.reason }
193
213
  const head = (await git(worktree, ['symbolic-ref', '--short', '-q', 'HEAD']).catch(() => '')).trim()
194
214
  await git(repo.path, ['worktree', 'remove', '--force', worktree])
195
215
  if (head === branch) await git(repo.path, ['branch', '-D', branch]).catch(() => {})
@@ -306,11 +326,46 @@ export function processSpawner({
306
326
  return { pid: child.pid, worktree, ...files, exited, reused }
307
327
  },
308
328
  cleanup: teardown,
329
+ held,
309
330
  tail: tailFile,
310
331
  readLog: readLogFile,
311
332
  }
312
333
  }
313
334
 
335
+ /**
336
+ * Every pid under `root` in a `pid ppid` process table (`ps -A -o pid=,ppid=`), deepest last.
337
+ * @param {number} root @param {string} table @returns {number[]}
338
+ */
339
+ export function descendants(root, table) {
340
+ /** @type {Map<number, number[]>} */
341
+ const children = new Map()
342
+ for (const line of table.split('\n')) {
343
+ const [pid, ppid] = line.trim().split(/\s+/).map(Number)
344
+ if (!Number.isInteger(pid) || !Number.isInteger(ppid) || pid === ppid) continue
345
+ children.set(ppid, [...(children.get(ppid) ?? []), pid])
346
+ }
347
+ const out = []
348
+ const seen = new Set([root])
349
+ for (let i = -1; i < out.length; i++) {
350
+ for (const c of children.get(i < 0 ? root : out[i]) ?? []) {
351
+ if (seen.has(c)) continue
352
+ seen.add(c)
353
+ out.push(c)
354
+ }
355
+ }
356
+ return out
357
+ }
358
+
359
+ /** @param {number} target */
360
+ function sigkill(target) {
361
+ try {
362
+ process.kill(target, 'SIGKILL')
363
+ return true
364
+ } catch {
365
+ return false
366
+ }
367
+ }
368
+
314
369
  /** @type {Procs} */
315
370
  export const realProcs = {
316
371
  alive(pid) {
@@ -322,12 +377,13 @@ export const realProcs = {
322
377
  }
323
378
  },
324
379
  kill(pid) {
380
+ // The process group is not enough: Claude Code runs each Bash command in a group of its own, so a test
381
+ // run the worker started outlives the group kill and loads the next attempt. Snapshot the tree first
382
+ // (killed children reparent to launchd and drop out of it), then kill it and the group.
383
+ const ps = spawnSync('ps', ['-A', '-o', 'pid=,ppid='], { encoding: 'utf8' })
384
+ const tree = ps.status === 0 ? descendants(pid, ps.stdout) : []
325
385
  // A detached worker leads its own process group: the negative pid takes its children with it.
326
- for (const target of [-pid, pid]) {
327
- try {
328
- process.kill(target, 'SIGKILL')
329
- return
330
- } catch {}
331
- }
386
+ if (!sigkill(-pid)) sigkill(pid)
387
+ for (const p of tree) sigkill(p)
332
388
  },
333
389
  }