@oakgreencc/cambium 0.0.27 → 0.0.28

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
@@ -19,18 +19,18 @@ cambium status
19
19
 
20
20
  ## Commands
21
21
 
22
- | Command | What |
23
- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
24
- | `cambium start [--once]` | Foreground daemon, one tick every `tickSeconds`. SIGTERM/SIGINT stop it after the current tick; workers keep running and are re-adopted on restart. One daemon per database. |
25
- | `cambium status [--json]` | Mode, last tick, queue counts, workers, failed steps. Exit 1 when there is no heartbeat or it is older than 3 ticks. |
26
- | `cambium pause` | Read and heartbeat only: no transitions, no starts. Running workers are left alone. |
27
- | `cambium drain` | Reconcile, watch and sweep as usual; start nothing new. |
28
- | `cambium resume` | Back to `running`. |
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
- | `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). |
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. |
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). |
22
+ | Command | What |
23
+ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
24
+ | `cambium start [--once]` | Foreground daemon, one tick every `tickSeconds`. SIGTERM/SIGINT stop it after the current tick; workers keep running and are re-adopted on restart. One daemon per database. |
25
+ | `cambium status [--json]` | Mode, last tick, queue counts, workers, failed steps. Exit 1 when there is no heartbeat or it is older than 3 ticks. |
26
+ | `cambium pause` | Read and heartbeat only: no transitions, no starts. Running workers are left alone. |
27
+ | `cambium drain` | Reconcile, watch and sweep as usual; start nothing new. |
28
+ | `cambium resume` | Back to `running`. |
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
+ | `cambium run <task | pr> --issue <n> [--repo <owner/name>] [--follow]` | `engine: "graph"` only. `pr`: the [PR graph](#the-pr-graph) for the issue's PR. `task`: 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). |
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. |
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). |
34
34
 
35
35
  Every command takes `--config <file>`; the default is `$CAMBIUM_CONFIG`, then `~/.cambium/config.json`.
36
36
 
@@ -38,15 +38,15 @@ Every command takes `--config <file>`; the default is `$CAMBIUM_CONFIG`, then `~
38
38
 
39
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.
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
+ 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, `mergeable`, `reviewDecision` 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.
42
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.
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
+ 3. **Watch** (no agent). Graph engine: the [PR graph](#the-pr-graph), once per tick for each agent PR whose CI has settled and whose issue has no Task queued or running: merge, rework, close, or `q:human`. Legacy, 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`.
44
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.
45
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)).
46
46
  6. **Release.** Legacy: once a day at `release.time` when `release.enabled`; the run itself is a seam. Graph: the [release graphs](#the-release-graphs), per repo.
47
47
  7. **Heartbeat.** Write the state file.
48
48
 
49
- A requeue is `q:task` with attempt + 1, or, once `maxAttempts` are spent, `q:human` + `why:budget`. Who merges a Task PR is the repo's `merge` setting ([Merging](#merging)): by default not cambium (a merge queue, auto-merge or a human); with `"merge": "green"` cambium merges it once CI is green. The other merge cambium asks for is an approved promotion PR, through `graft pr merge`; see [The release graphs](#the-release-graphs).
49
+ A requeue is `q:task` with attempt + 1, or, once `maxAttempts` are spent, `q:human` + `why:budget`. Who merges a Task PR is the repo's `merge` setting ([The PR graph](#the-pr-graph)): by default not cambium (a merge queue, auto-merge or a human); with `"merge": "green"` cambium merges it once CI is green. The other merge cambium asks for is an approved promotion PR, through `graft pr merge`; see [The release graphs](#the-release-graphs).
50
50
 
51
51
  ## State on GitHub
52
52
 
@@ -100,7 +100,7 @@ One JSON file. Everything but `repos` is optional; these are the defaults:
100
100
  "stepTimeoutSeconds": 20,
101
101
  "repos": [{ "slug": "oakgreencc/monorepo", "path": "~/OGCC/monorepo", "baseBranch": "main" }],
102
102
  "phases": {
103
- "task": { "cap": 2, "wallClockMinutes": 60, "maxTurns": 200, "maxAttempts": 3 },
103
+ "task": { "cap": 2, "wallClockMinutes": 60, "maxTurns": 200, "maxAttempts": 3, "maxReworks": 3 },
104
104
  "dispatch": {
105
105
  "cap": 0,
106
106
  "wallClockMinutes": 15,
@@ -134,7 +134,7 @@ One JSON file. Everything but `repos` is optional; these are the defaults:
134
134
  - The daemon re-reads the file before every tick, so caps, limits, `tickSeconds`, `repos`, priority labels, `release` and `worker` take effect without a restart (logged as `config reloaded: <keys>`). `host`, `engine`, `paths`, `logs` and `graft` are baked in at start: a change to them logs `restart cambium to apply` once and is not applied. A file that does not load, or has no `repos`, keeps the running config and logs one warning until it is fixed.
135
135
  - `repos[].path` is a local clone; worktrees are added from it and `graft` runs in it.
136
136
  - `graft.app` is the App cambium acts as (`GRAFT_APP` for its own `graft` calls); `worker.graftApp` the one workers act as. Neither leaks into the other.
137
- - `merge` (top level, or per repo in `repos[]`): who merges a Task PR. See [Merging](#merging).
137
+ - `merge` (top level, or per repo in `repos[]`): who merges a Task PR. See [The PR graph](#the-pr-graph).
138
138
  - `repos[].requiredCheck` (default `"ci"`): the check whose runs on `baseBranch` say whether the base is green; `null` turns the [red-base](#red-base) gate and repair off for that repo.
139
139
  - `engine` picks how the Task phase runs: `"legacy"` (the stage tick, the default) or `"graph"` (the [`task` graph](#the-task-graph)). Both make the same moves; see [The task graph](#the-task-graph). Only `"graph"` runs the [`dispatch` graph](#the-dispatch-graph) (gated by `phases.dispatch.cap`); legacy leaves `q:intake` alone.
140
140
  - Setting `paths.home` moves every default path under it.
@@ -261,45 +261,28 @@ The mode lives in the SQLite file (`paths.db`, table `control`), so `cambium sta
261
261
 
262
262
  ## The task graph
263
263
 
264
- With `"engine": "graph"` the tick's Task-phase steps (Reconcile, Watch, Sweep, Schedule) drive the `task` graph (`src/graphs/task.mjs`) instead of the stage tick in `src/tick.mjs`. The default stays `"legacy"`; flipping it and deleting the legacy path is a follow-up.
264
+ With `"engine": "graph"` the tick's Task-phase steps (Reconcile, Sweep, Schedule) drive the `task` graph (`src/graphs/task.mjs`) instead of the stage tick in `src/tick.mjs`. The default stays `"legacy"`; flipping it and deleting the legacy path is a follow-up. The task graph turns a `q:task` issue into a published PR and **ends there** (`submit`); the PR is then the [PR graph](#the-pr-graph)'s.
265
265
 
266
266
  ```mermaid
267
267
  flowchart TD
268
268
  start_(["q:task"])
269
269
  n0["start-worker"]
270
270
  n1{{"worker-running"}}
271
- n2{{"ci-running"}}
272
- n3["merge"]
273
- n4{{"merging"}}
274
- n5{{"merge-queue"}}
275
- n6["close-out"]
276
- n7["requeue"]
277
- n8["to-human"]
271
+ n2["submit"]
272
+ n3["requeue"]
273
+ n4["to-human"]
278
274
  end_(("end"))
279
275
  start_ --> n0
280
276
  n0 -->|"started"| n1
281
- n0 -->|"budgetSpent"| n8
282
- n0 --> n7
277
+ n0 -->|"budgetSpent"| n4
278
+ n0 --> n3
283
279
  n1 -->|"issueGone"| end_
284
280
  n1 -->|"submitted"| n2
285
- n1 --> n7
286
- n2 -->|"merged"| n6
287
- n2 -->|"inMergeQueue"| n5
288
- n2 -->|"green"| n3
289
- n2 -->|"stalled"| n8
290
- n2 --> n7
281
+ n1 --> n3
282
+ n2 --> end_
283
+ n3 -->|"attemptsLeft"| n0
291
284
  n3 --> n4
292
- n4 -->|"merged"| n6
293
- n4 -->|"green"| n3
294
- n4 -->|"stalled"| n8
295
- n4 --> n7
296
- n5 -->|"merged"| n6
297
- n5 -->|"stalled"| n8
298
- n5 --> n7
299
- n7 -->|"attemptsLeft"| n0
300
- n7 --> n8
301
- n6 --> end_
302
- n8 --> end_
285
+ n4 --> end_
303
286
  ```
304
287
 
305
288
  Generated by `toMermaid(task)`; a test keeps this copy current. Boxes are step nodes, hexagons are waits.
@@ -308,29 +291,67 @@ Generated by `toMermaid(task)`; a test keeps this copy current. Boxes are step n
308
291
  | ---------------- | ---- | ----------- | --------------- |
309
292
  | `start-worker` | step | `q:task` | no |
310
293
  | `worker-running` | wait | `q:task` | yes |
311
- | `ci-running` | wait | none | no |
312
- | `merge` | step | none | no |
313
- | `merging` | wait | none | no |
314
- | `merge-queue` | wait | none | no |
315
- | `close-out` | step | none | no |
294
+ | `submit` | step | none | no |
316
295
  | `requeue` | step | `q:task` | no |
317
296
  | `to-human` | step | `q:human` | no |
318
297
 
319
298
  - **Labels are a projection.** Each node declares its queue label and whether it holds `running`. When an issue lands on a node, the marker is written first, then the labels come from `move()` (`labels.mjs`) with that declaration.
320
- - **Where a turn starts.** Reconcile polls `worker-running` for every tracked worker. Watch polls `ci-running` / `merging` / `merge-queue` for agent PRs whose issue is in no queue; a merged PR goes to `close-out` wherever the issue is, as in the stage tick. Sweep sends a stale `running` lease to its node's `recover` (default: `requeue`). Schedule is the gate on the entry node: caps and priority pick the issues, each starts at `start-worker`.
321
- - **Where a turn stops.** At a wait that is not ready, on entering a wait (it is polled next tick; `merge-queue` is polled on entry, so a stall is caught in the same pass), on reaching `start-worker` again (only Schedule admits it), or at the end.
322
- - **Markers.** The graph writes marker v2 without `stage`: `node` is where the issue rests. `merge-queue` is the stage tick's `submitted` with `queued: true`, and a stage-era marker in that state resumes at `merge-queue`. A marker whose node the current graph version no longer has restarts at `start-worker` with a `graph-changed` history entry.
323
- - **Same moves.** Every scenario in `test/tick.test.mjs` runs on both engines; the test compares their GitHub calls in order (markers semantically, not by rendered text), worker starts with their prompts, kills, teardowns and logs.
299
+ - **Where a turn starts.** Reconcile polls `worker-running` for every tracked worker. Sweep sends a stale `running` lease to its node's `recover` (default: `requeue`). Schedule is the gate on the entry node: caps and priority pick the issues, each starts at `start-worker`.
300
+ - **Where a turn stops.** At a wait that is not ready, on entering a wait (it is polled next tick), on reaching `start-worker` again (only Schedule admits it), or at the end.
301
+ - **`submit`.** The worker exited with an open (or merged) PR: history `submitted`, `submittedAt`, the PR on the marker (`status: done`), the issue out of every queue, and `Closes #n` added to a PR found only by its branch. A worker that exits without one, or is killed at `wallClockMinutes`, is a `requeue` (attempt + 1, then `q:human` + `why:budget`).
302
+ - **Markers.** The graph writes marker v2 without `stage`: `node` is where the issue rests. v2 of the graph moved `ci-running`, `merge`, `merging`, `merge-queue` and `close-out` to the PR graph: a marker resting at one of them (or a stage-era `submitted`) is the PR graph's, not a restart. A marker at any other node the current version no longer has restarts at `start-worker` with a `graph-changed` history entry.
303
+ - **Same moves.** Every scenario in `test/tick.test.mjs` up to a PR's submission runs on both engines; the test compares their GitHub calls in order (markers semantically, not by rendered text), worker starts with their prompts, kills, teardowns and logs. Past submission the engines differ by design; those scenarios are legacy only, and `test/pr-graph.test.mjs` is the graph side.
304
+
305
+ ## The PR graph
306
+
307
+ Every tick, Watch starts one turn of the `pr` graph (`src/graphs/pr.mjs`) at `assess` for each agent PR (head `agent/*`) that closes a cambium-owned issue, when
324
308
 
325
- ## Merging
309
+ - the PR is merged and its issue still open (→ `close-out`), or
310
+ - the PR is open, its CI has settled (not `PENDING`/`EXPECTED`), and its issue has no Task queued or running: no `q:task`, `q:intake` or `q:promote`, no `running`, no tracked worker.
326
311
 
327
- Neither of our repos runs a GitHub merge queue (it costs), so `merge` says who merges a Task PR, per repo (`repos[].merge`, falling back to the top-level `merge`):
312
+ `assess` decides from the PR as the snapshot reads it, one step acts, and the turn ends. There are no waits: the next tick assesses again.
328
313
 
329
- - `"none"` (default): not cambium. A merge queue, auto-merge or a human merges it; `mergeQueueMinutes` after submission an unmerged PR sends its issue to `q:human` (`stalled`).
330
- - `"green"`: cambium merges it. Needs `engine: "graph"` (config refuses it on legacy). When `ci-running` sees the PR's checks `SUCCESS`, with no auto-merge armed and not in a merge queue, it goes to `merge`: `graft pr merge <n> --auto`, so graft's merge policy (bases, protected paths, a red base) still decides: a clean PR merges now, otherwise auto-merge is armed. Then `merging` waits for the merge. A refusal is recorded in the marker (`mergeRefusal`, history `merge-refused`) and asked again on a new head or after 10 minutes. Red CI still requeues, and `mergeQueueMinutes` still stalls to `q:human`.
331
- - **Up to date first.** Before merging, `merge` asks GitHub live how far the PR's head is behind its base (`compare`, so a merge earlier in the same tick counts). Behind → `graft pr update <n>` instead of the merge (history `branch-updated`, held like a refusal on the old head), and the updated head merges once its CI is green; red there requeues like any red CI. This is a merge queue without the cost: two PRs green on the same base can be red together (sektorapp/monorepo#4624 + #4625 broke develop 8 s apart), and the base does not require up-to-date branches. An update GitHub refuses (a conflict) is a `merge-refused` and stalls to `q:human` like any other.
314
+ ```mermaid
315
+ flowchart TD
316
+ start_(["start"])
317
+ n0["assess"]
318
+ n1["merge"]
319
+ n2["rework"]
320
+ n3["close-pr"]
321
+ n4["close-out"]
322
+ n5["to-human"]
323
+ end_(("end"))
324
+ start_ --> n0
325
+ n0 -->|"merged"| n4
326
+ n0 -->|"toMerge"| n1
327
+ n0 -->|"toRework"| n2
328
+ n0 -->|"toClose"| n3
329
+ n0 -->|"toHumanInbox"| n5
330
+ n0 --> end_
331
+ n1 -->|"needsApproval"| n5
332
+ n1 --> end_
333
+ n2 -->|"reworksSpent"| n5
334
+ n2 --> end_
335
+ n3 --> end_
336
+ n4 --> end_
337
+ n5 --> end_
338
+ ```
332
339
 
333
- The worker prompt says which: "Green: stop; cambium merges the PR once CI is green" or "…the PR is merged outside this session".
340
+ | Node | What it does |
341
+ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
342
+ | `assess` | In order: merged → `close-out`; issue closed → `close-pr`; a newer open agent PR closes the same issue → `close-pr` (superseded); red CI, a conflict (`mergeable: CONFLICTING`) or `CHANGES_REQUESTED` → `rework`; green, clean and the repo's `merge` is `"green"`, nothing armed, no refusal on this head within 10 min → `merge`; not merged `mergeQueueMinutes` after submission → `to-human` (`why:approve`); else nothing this tick. |
343
+ | `merge` | Behind its base (read live, so a merge earlier in the tick counts) → `graft pr update` instead (history `branch-updated`, held like a refusal on the old head; the new head merges once its CI is green). Otherwise `graft pr merge --auto` (history `merge-armed`), so graft's merge policy decides. A refusal is recorded (`mergeRefusal`, history `merge-refused`) and asked again on a new head or after 10 min; one only a human can clear (protected paths, a base agents may not merge into, a broken policy) → `to-human` (`why:approve`). |
344
+ | `rework` | Back to the task graph at `start-worker` in `q:task`: attempt 1 of a fresh `maxAttempts`, `reworks` + 1, the reason (the failing checks, the conflict, the review) as `lastFailure`, the head as `failedSha` (a worker that pushes nothing new has not reworked it). The worker's prompt names the rework and the PR; it resumes the branch. Past `phases.task.maxReworks` (default 3) → `to-human` (`why:budget`). |
345
+ | `close-pr` | Closes the PR with the reason and `Closed by cambium.`; an open issue gets a `pr-closed` history entry. |
346
+ | `close-out` | Merged: marker done, out of every queue, the issue closed (`Merged in #n. Closed by cambium.`), the branch deleted. |
347
+ | `to-human` | `q:human` with the `why:` label and the reason as the last failure. |
348
+
349
+ - **The Human Queue is the human's.** For an issue in `q:human` the PR graph only merges a PR that is green and clean (e.g. a worker's PR published after its issue was handed over, as sektorapp/monorepo#4627 was), and not on a head a human-only refusal sent there. It never reworks or closes one.
350
+ - **State.** The PR graph's state is the issue's marker (`graph: "pr"`), like the task graph's; `rework` writes a task-graph marker.
351
+ - **Who merges.** `repos[].merge` (falling back to the top-level `merge`): `"none"` (default) leaves a green PR to a merge queue, auto-merge or a human, and stalls it to `q:human` after `mergeQueueMinutes`; `"green"` lets the PR graph merge it (needs `engine: "graph"`). Neither of our repos runs a GitHub merge queue (it costs); updating a PR that is behind before merging is the merge queue without the cost: two PRs green on the same base can be red together (sektorapp/monorepo#4624 + #4625 broke develop 8 s apart).
352
+ - **Foreground.** `cambium run pr --issue <n> [--follow]` runs the same turn for one issue's PR; `--follow` repeats it every `tickSeconds` until the issue is closed.
353
+
354
+ The worker prompt says who merges: "Green: stop; cambium merges the PR once CI is green" or "…the PR is merged outside this session".
334
355
 
335
356
  ## Red base
336
357
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oakgreencc/cambium",
3
- "version": "0.0.27",
3
+ "version": "0.0.28",
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
@@ -29,7 +29,7 @@ export const HELP = `cambium ${VERSION} — the scheduler daemon
29
29
  cambium drain reconcile and watch, start no new workers
30
30
  cambium run task --issue <n> [--repo <owner/name>]
31
31
  claim one q:task issue, run its worker in the foreground, transition
32
- cambium run <graph> --issue <n> [--repo <owner/name>] [--follow]
32
+ cambium run <task|pr> --issue <n> [--repo <owner/name>] [--follow]
33
33
  engine "graph": advance the issue in the foreground to the first wait
34
34
  that is not ready; --follow keeps polling until the graph ends
35
35
  cambium gc [--dry-run] [--repo <owner/name>]
package/src/config.mjs CHANGED
@@ -23,13 +23,16 @@ import { join, resolve } from 'node:path'
23
23
  * `requiredCheck` (default `ci`): the check whose runs on `baseBranch` say whether the base is green (see
24
24
  * base-health.mjs); `null` turns the red-base gate and repair off for the repo.
25
25
  * @typedef {{ cap: number, wallClockMinutes: number, maxTurns: number, maxAttempts: number }} PhaseCaps
26
+ * @typedef {PhaseCaps & { maxReworks: number }} TaskCaps
27
+ * `maxReworks`: how many times the PR graph sends one PR back to a worker (red CI, a conflict, changes
28
+ * requested) before it goes to `q:human`. Each rework gets a fresh `maxAttempts`.
26
29
  * @typedef {{
27
30
  * host: string,
28
31
  * engine: 'legacy' | 'graph',
29
32
  * tickSeconds: number,
30
33
  * stepTimeoutSeconds: number,
31
34
  * repos: Repo[],
32
- * phases: { task: PhaseCaps, dispatch: PhaseCaps & { maxRounds: number, deferHours: number, maxDefers: number } },
35
+ * phases: { task: TaskCaps, dispatch: PhaseCaps & { maxRounds: number, deferHours: number, maxDefers: number } },
33
36
  * mergeQueueMinutes: number,
34
37
  * merge: MergePolicy,
35
38
  * priorityLabels: string[],
@@ -61,7 +64,7 @@ export function defaults(home = DEFAULT_HOME) {
61
64
  stepTimeoutSeconds: 20,
62
65
  repos: [],
63
66
  phases: {
64
- task: { cap: 2, wallClockMinutes: 60, maxTurns: 200, maxAttempts: 3 },
67
+ task: { cap: 2, wallClockMinutes: 60, maxTurns: 200, maxAttempts: 3, maxReworks: 3 },
65
68
  dispatch: {
66
69
  cap: 0,
67
70
  wallClockMinutes: 15,
package/src/github.mjs CHANGED
@@ -20,7 +20,11 @@ import { BASE_FIELDS, baseHealthOf } from './base-health.mjs'
20
20
  * number: number, url: string, branch: string, state: 'OPEN' | 'MERGED' | 'CLOSED', headSha: string | null,
21
21
  * branchExists: boolean, inMergeQueue: boolean, autoMerge: boolean,
22
22
  * checks: 'SUCCESS' | 'FAILURE' | 'ERROR' | 'PENDING' | 'EXPECTED' | null, failing: FailingCheck[], closes: number[],
23
+ * mergeable: 'MERGEABLE' | 'CONFLICTING' | 'UNKNOWN' | null,
24
+ * reviewDecision: 'APPROVED' | 'CHANGES_REQUESTED' | 'REVIEW_REQUIRED' | null, createdAt: string | null,
23
25
  * }} PullRequest
26
+ * `mergeable`: GitHub's conflict check against the base (UNKNOWN while it computes). `reviewDecision`: null
27
+ * when the base requires no review.
24
28
  * @typedef {{
25
29
  * number: number, url: string, title: string, state: 'OPEN' | 'MERGED' | 'CLOSED', createdAt: string,
26
30
  * head: string, base: string, headSha: string | null, labels: string[], approved: boolean, autoMerge: boolean,
@@ -62,7 +66,7 @@ import { BASE_FIELDS, baseHealthOf } from './base-health.mjs'
62
66
  * `linkIssue`: put `Closes #<issue>` at the top of the PR's body, so the PR names the issue it closes.
63
67
  */
64
68
 
65
- const PR_FIELDS = `number url headRefName state headRefOid isInMergeQueue body
69
+ const PR_FIELDS = `number url headRefName state headRefOid isInMergeQueue body mergeable reviewDecision createdAt
66
70
  headRef { id }
67
71
  autoMergeRequest { enabledAt }
68
72
  closingIssuesReferences(first: 5) { nodes { ...I } }
@@ -263,6 +267,9 @@ export function normalize(data, { botLogin = null, release = null, health = null
263
267
  checks: rollup?.state ?? null,
264
268
  failing,
265
269
  closes: [...new Set([...(p.closingIssuesReferences?.nodes ?? []).map(addIssue), ...bodyCloses(p.body)])],
270
+ mergeable: p.mergeable ?? null,
271
+ reviewDecision: p.reviewDecision ?? null,
272
+ createdAt: p.createdAt ?? null,
266
273
  })
267
274
  }
268
275
  return {
@@ -1,27 +1,28 @@
1
1
  // @ts-check
2
2
  /**
3
- * `engine: "graph"`: the Task-phase steps of the tick, driven through the `task` graph (graphs/task.mjs).
3
+ * `engine: "graph"`: the Task-phase steps of the tick, driven through the `task` graph (graphs/task.mjs) and the
4
+ * `pr` graph (graphs/pr.mjs).
4
5
  *
5
- * The tick keeps its shape (Reconcile → Watch → Sweep → Schedule) so both engines make the same moves in the
6
- * same order; each step only chooses where an issue's turn starts:
6
+ * The tick keeps its shape (Reconcile → Watch → Sweep → Schedule); each step only chooses where a turn starts:
7
7
  *
8
- * - Reconcile: every tracked worker's issue at `worker-running`.
9
- * - Watch: issues resting at `ci-running` / `merge-queue` (from the marker), and any task issue in no queue with
10
- * an open PR (a queue label removed by hand), which starts at `ci-running` (`merge-queue` if `queued`); a
11
- * merged PR goes to `close-out` from wherever the issue is.
8
+ * - Reconcile: every tracked worker's issue at `worker-running` (task graph, which ends at `submit`).
9
+ * - Watch: every agent PR paired with a cambium-owned issue, at the PR graph's `assess`: a merged one (its issue
10
+ * open) to close out, an open one once its CI has settled and its issue has no Task queued or running.
12
11
  * - Sweep: a stale `running` lease runs its node's `recover` (default: `requeue`).
13
- * - Schedule: the gate on the entry node. Caps and priority pick the issues; each starts at `start-worker`.
12
+ * - Schedule: the gate on the task entry. Caps and priority pick the issues; each starts at `start-worker`.
14
13
  *
15
14
  * A turn ({@link drive}) advances one transition at a time and stops when it reaches the entry node again (only
16
15
  * Schedule admits entries), when it enters a wait (polled next tick, unless the wait is `pollOnEntry`), at END,
17
16
  * or at a wait that is not ready.
18
17
  */
19
18
  import { advance, END } from './graph/index.mjs'
20
- import { deleteMergedBranch, inputFor, lostLeaseOf, nodeOf, task, TASK_QUEUES, TERMINAL } from './graphs/task.mjs'
19
+ import { deleteMergedBranch, prGraph } from './graphs/pr.mjs'
20
+ import { HANDED_OFF, inputFor, lostLeaseOf, task, TASK_QUEUES, TERMINAL } from './graphs/task.mjs'
21
+ import { prFor } from './phases/task.mjs'
21
22
  import { iso, key, markerOf, setLabels, setMarker } from './issue-state.mjs'
22
23
  import { effectivePosition, graphVersionDecision, withHistory } from './marker.mjs'
23
- import { each, newCtx, staleLeases, taskCandidates, watched, watchPairs } from './tick.mjs'
24
- import { move, Q } from './labels.mjs'
24
+ import { each, newCtx, staleLeases, taskCandidates, watchPairs } from './tick.mjs'
25
+ import { move, Q, RUNNING } from './labels.mjs'
25
26
  import { markerTrace, turnTracer } from './tracing.mjs'
26
27
  import { DISPATCH_STEPS } from './dispatch-engine.mjs'
27
28
  import { trackPromotion } from './promotion.mjs'
@@ -39,18 +40,27 @@ import { trackBaseHealth } from './base-health.mjs'
39
40
  /** @param {Deps} deps @param {Ctx} ctx @param {Subject} subject @returns {import('./graphs/task.mjs').TaskCtx} */
40
41
  const taskCtx = (deps, ctx, subject) => ({ ...deps, tick: ctx, subject })
41
42
 
43
+ /** @param {import('./graph/define.mjs').Graph} g @param {string} name @returns {import('./graphs/task.mjs').TaskNode} */
44
+ function nodeIn(g, name) {
45
+ const node = g.nodes.find((n) => n.name === name)
46
+ if (!node) throw new Error(`${g.name} graph has no node "${name}"`)
47
+ return /** @type {import('./graphs/task.mjs').TaskNode} */ (node)
48
+ }
49
+
42
50
  /**
43
- * One issue's turn from `at`. A node error is rethrown as the node's own error (the step logs it, as the legacy
44
- * tick does); a worker whose `worker-running` was left is torn down only after the turn's writes succeeded.
51
+ * One issue's turn from `at` in graph `g` (the task graph unless given). A node error is rethrown as the node's own
52
+ * error (the step logs it, as the legacy tick does); a worker whose `worker-running` was left is torn down only
53
+ * after the turn's writes succeeded.
45
54
  *
46
55
  * @param {Deps} deps @param {Ctx} ctx @param {Subject} subject @param {Position} at
56
+ * @param {import('./graph/define.mjs').Graph} [g]
47
57
  * @returns {Promise<Turn>}
48
58
  */
49
- export async function drive(deps, ctx, subject, at) {
59
+ export async function drive(deps, ctx, subject, at, g = task) {
50
60
  const c = taskCtx(deps, ctx, subject)
51
61
  const traced = turnTracer(deps.telemetry, subject, {
52
- graph: task.name,
53
- graphVersion: task.version,
62
+ graph: g.name,
63
+ graphVersion: g.version,
54
64
  repo: subject.slug,
55
65
  issue: subject.number,
56
66
  issueBody: subject.issue?.body ?? null,
@@ -62,22 +72,22 @@ export async function drive(deps, ctx, subject, at) {
62
72
  /** @type {Turn['reason']} */
63
73
  let reason
64
74
  for (;;) {
65
- const r = await advance(task, pos, c, { maxTransitions: 1, instrument: traced.instrument })
75
+ const r = await advance(g, pos, c, { maxTransitions: 1, instrument: traced.instrument })
66
76
  if (r.error) throw r.error.cause instanceof Error ? r.error.cause : r.error
67
77
  transitions.push(...r.transitions)
68
78
  const t = r.transitions[0]
69
79
  traced.sync()
70
- if (t && t.to !== END) await nodeOf(t.to).enter?.(t.next, c)
80
+ if (t && t.to !== END) await nodeIn(g, t.to).enter?.(t.next, c)
71
81
  pos = { node: r.node, input: r.input }
72
82
  if (r.reason !== 'limit') {
73
83
  reason = r.reason === 'waiting' ? 'waiting' : 'end'
74
84
  break
75
85
  }
76
- if (r.node === task.entry.node) {
86
+ if (r.node === g.entry.node) {
77
87
  reason = 'gated'
78
88
  break
79
89
  }
80
- const next = nodeOf(r.node)
90
+ const next = nodeIn(g, r.node)
81
91
  if (next.kind === 'wait' && !next.pollOnEntry) {
82
92
  reason = 'waiting'
83
93
  break
@@ -100,8 +110,9 @@ async function releaseWorker(deps, s) {
100
110
 
101
111
  /**
102
112
  * Where an issue rests in the task graph, from its labels and marker: the label wins (marker.mjs
103
- * `effectivePosition`), a stage-era `submitted` that the merge queue holds is `merge-queue`, and a node the
104
- * current graph version no longer has restarts at the entry (with a `graph-changed` history note).
113
+ * `effectivePosition`), a node the PR graph now owns (v1's `ci-running` … `close-out`, a stage-era `submitted`)
114
+ * is not the task graph's, and any other node the current graph version no longer has restarts at the entry (with
115
+ * a `graph-changed` history note).
105
116
  *
106
117
  * @param {import('./github.mjs').Issue} issue @param {number} now
107
118
  * @returns {(Position & { note?: import('./marker.mjs').HistoryEntry }) | null} null: not in the task graph
@@ -111,6 +122,7 @@ export function locate(issue, now) {
111
122
  const pos = effectivePosition(issue.labels, marker, TASK_QUEUES)
112
123
  if (!pos || pos.graph !== task.name) return null
113
124
  if (pos.reset || !marker) return { node: task.entry.node, input: {} }
125
+ if (!issue.labels.includes(Q.task) && HANDED_OFF.has(pos.node)) return null
114
126
  const v = graphVersionDecision(marker, {
115
127
  version: task.version,
116
128
  nodes: task.nodes.map((n) => n.name),
@@ -118,8 +130,7 @@ export function locate(issue, now) {
118
130
  at: iso(now),
119
131
  })
120
132
  if (v.action === 'restart') return { node: v.node, input: {}, note: v.note }
121
- const node = pos.node === 'ci-running' && marker.queued ? 'merge-queue' : pos.node
122
- return { node, input: inputFor(node, marker) }
133
+ return { node: pos.node, input: inputFor(pos.node, marker) }
123
134
  }
124
135
 
125
136
  /**
@@ -160,8 +171,20 @@ async function reconcile(deps, ctx) {
160
171
  )
161
172
  }
162
173
 
163
- /** The waits Watch drives: an open PR on its way to a merge. */
164
- const WATCHED = new Set(['ci-running', 'merging', 'merge-queue'])
174
+ /** Queues that mean a Task is still to run (or a triage, or a promotion): the PR graph leaves the PR alone. */
175
+ const BUSY = new Set([Q.task, Q.intake, Q.promote])
176
+
177
+ /**
178
+ * The PR graph may assess this pair: its CI has settled and its issue has no Task queued or running (no lease, no
179
+ * tracked worker). `q:human` is allowed; `assess` only takes such an issue back to merge a green PR.
180
+ * @param {Deps} deps @param {string} slug @param {import('./github.mjs').PullRequest} pr @param {import('./github.mjs').Issue} issue
181
+ */
182
+ export const assessable = (deps, slug, pr, issue) =>
183
+ pr.state === 'OPEN' &&
184
+ pr.checks !== 'PENDING' &&
185
+ pr.checks !== 'EXPECTED' &&
186
+ !issue.labels.some((l) => BUSY.has(l) || l === RUNNING) &&
187
+ !deps.store.worker(slug, issue.number)
165
188
 
166
189
  /** @param {Deps} deps @param {Ctx} ctx */
167
190
  async function watch(deps, ctx) {
@@ -175,20 +198,13 @@ async function watch(deps, ctx) {
175
198
  if (ctx.touched.has(key(slug, issue.number))) return
176
199
  /** @type {Subject} */
177
200
  const subject = { slug, number: issue.number, snap, issue, pr, deleted }
201
+ const entry = { node: prGraph.entry.node, input: {} }
178
202
  if (pr.state === 'MERGED') {
179
- if (issue.state === 'OPEN') await drive(deps, ctx, subject, { node: 'close-out', input: { pr: pr.number } })
203
+ if (issue.state === 'OPEN') await drive(deps, ctx, subject, entry, prGraph)
180
204
  else await deleteMergedBranch(taskCtx(deps, ctx, subject), pr)
181
205
  return
182
206
  }
183
- if (pr.state !== 'OPEN' || issue.state !== 'OPEN' || !watched(deps, slug, issue)) return
184
- const at = locate(issue, ctx.now)
185
- if (!at) return
186
- if (at.note) return restart(deps, ctx, slug, issue, at.note)
187
- if (WATCHED.has(at.node)) return drive(deps, ctx, subject, at)
188
- // Out of every queue with an open PR, but resting elsewhere (a queue label removed by hand): watch the PR
189
- // from where it is, as the legacy Watch does.
190
- const node = markerOf(issue).queued ? 'merge-queue' : 'ci-running'
191
- await drive(deps, ctx, subject, { node, input: { pr: pr.number, branch: pr.branch } })
207
+ if (assessable(deps, slug, pr, issue)) await drive(deps, ctx, subject, entry, prGraph)
192
208
  },
193
209
  ([, issue]) => ({ repo: slug, issue: issue.number }),
194
210
  )
@@ -205,7 +221,7 @@ async function sweep(deps, ctx) {
205
221
  const subject = { slug, number: issue.number, snap, issue }
206
222
  const c = taskCtx(deps, ctx, subject)
207
223
  const at = locate(issue, ctx.now)
208
- const recover = (at && nodeOf(at.node).recover) || defaultRecover
224
+ const recover = (at && nodeIn(task, at.node).recover) || defaultRecover
209
225
  await drive(deps, ctx, subject, recover(c))
210
226
  },
211
227
  (issue) => ({ repo: slug, issue: issue.number }),
@@ -247,7 +263,9 @@ export const GRAPH_ENGINE = {
247
263
  // ---- `cambium run <graph> --issue <n> [--follow]`
248
264
 
249
265
  /** Graphs `cambium run` knows, by name. */
250
- export const GRAPHS = { [task.name]: task }
266
+ export const GRAPHS = { [task.name]: task, [prGraph.name]: prGraph }
267
+
268
+ export { prGraph }
251
269
 
252
270
  /**
253
271
  * The graph runtime in the foreground for one issue. A `q:task` issue without a lease starts at the entry with a
@@ -264,6 +282,7 @@ export const GRAPHS = { [task.name]: task }
264
282
  export async function runIssue(deps, { graph, slug, number, follow = false, out, sleep = delay, signal }) {
265
283
  if (!Object.hasOwn(GRAPHS, graph))
266
284
  return { ok: false, error: `unknown graph "${graph}"; known: ${Object.keys(GRAPHS).join(', ')}` }
285
+ if (graph === prGraph.name) return runPr(deps, { slug, number, follow, out, sleep, signal })
267
286
  /** @type {Set<number>} */
268
287
  const reaped = new Set()
269
288
  let first = true
@@ -284,7 +303,13 @@ export async function runIssue(deps, { graph, slug, number, follow = false, out,
284
303
  ? { node: 'worker-running', input: { branch: worker.branch, attempt: worker.attempt } }
285
304
  : locate(issue, ctx.now)
286
305
  if (!located || TERMINAL.has(located.node)) {
287
- if (first) return { ok: false, error: `${slug}#${number} has nothing to run in the ${graph} graph` }
306
+ if (first)
307
+ return {
308
+ ok: false,
309
+ error: `${slug}#${number} has nothing to run in the ${graph} graph${
310
+ located ? '' : `; a submitted PR is the pr graph's: cambium run pr --issue ${number}`
311
+ }`,
312
+ }
288
313
  return report(out, slug, number, issue)
289
314
  }
290
315
  if (located.note) await restart(deps, ctx, slug, issue, located.note)
@@ -309,6 +334,37 @@ export async function runIssue(deps, { graph, slug, number, follow = false, out,
309
334
  }
310
335
  }
311
336
 
337
+ /**
338
+ * `cambium run pr --issue N [--follow]`: the PR graph for the issue's agent PR, as Watch would run it: one turn
339
+ * when its CI has settled and no Task is queued or running, else a report. `--follow` re-reads every `tickSeconds`
340
+ * until the issue is closed.
341
+ * @param {Deps} deps
342
+ * @param {{ slug: string, number: number, follow: boolean, out: (line: string) => void, sleep: (ms: number) => Promise<void>, signal?: AbortSignal }} o
343
+ * @returns {Promise<{ ok: boolean, error?: string }>}
344
+ */
345
+ async function runPr(deps, { slug, number, follow, out, sleep, signal }) {
346
+ for (let first = true; ; first = false) {
347
+ const ctx = newCtx(deps)
348
+ const snap = await deps.github.read(slug)
349
+ ctx.snaps.set(slug, snap)
350
+ const issue = snap.issues.get(number)
351
+ const pr = issue ? prFor(snap, { issue: number, branch: issue.stateComment?.marker.branch ?? null }) : null
352
+ if (first && (!issue || !pr)) return { ok: false, error: `${slug}#${number} has no agent PR to assess` }
353
+ if (issue && pr && issue.stateComment) {
354
+ /** @type {Subject} */
355
+ const subject = { slug, number, snap, issue, pr }
356
+ const entry = { node: prGraph.entry.node, input: {} }
357
+ if ((pr.state === 'MERGED' && issue.state === 'OPEN') || assessable(deps, slug, pr, issue)) {
358
+ const turn = await drive(deps, ctx, subject, entry, prGraph)
359
+ out(`PR #${pr.number}: ${turn.transitions.map((t) => String(t.to)).join(' → ') || 'assessed'}`)
360
+ } else out(`PR #${pr.number}: not assessed (CI ${pr.checks ?? 'none'}, ${pr.state.toLowerCase()})`)
361
+ }
362
+ if (!follow || issue?.state !== 'OPEN' || signal?.aborted) return report(out, slug, number, issue)
363
+ await sleep(deps.config.tickSeconds * 1000)
364
+ if (signal?.aborted) return report(out, slug, number, issue)
365
+ }
366
+ }
367
+
312
368
  /** @param {number} ms */
313
369
  const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
314
370