@oakgreencc/cambium 0.0.20 → 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
 
@@ -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.20",
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
@@ -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,6 +326,7 @@ 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
  }