@oakgreencc/cambium 0.0.36 → 0.0.38

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
@@ -40,11 +40,11 @@ Every command takes `--config <file>`; the default is `$CAMBIUM_CONFIG`, then `~
40
40
 
41
41
  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.
42
42
 
43
- 1. **Read.** One GraphQL query per repo (`graft graphql`): open issues with any `q:` label (100 per page; more pages follow the cursor, so a busy queue's newest issues are not invisible), 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 (also the issue an open PR that closes none names by its branch, `agent/<n>-…`, for the [reaper](#upkeep)). A worker's PR that names no issue (found by its branch) gets `Closes #n` added at submission.
43
+ 1. **Read.** One GraphQL query per repo (`graft graphql`): open issues with any `q:` label (100 per page; more pages follow the cursor, so a busy queue's newest issues are not invisible), open and recently merged PRs on `agent/*` with their check rollup, merge-queue state, `mergeable`, `reviewDecision` and the issues they close. Each issue's newest 20 comments come with their time and author type, for [human replies](#the-dispatch-graph). 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 (also the issue an open PR that closes none names by its branch, `agent/<n>-…`, for the [reaper](#upkeep)). A worker's PR that names no issue (found by its branch) gets `Closes #n` added at submission.
44
44
  2. **Reconcile.** For each tracked worker: alive and under its wall-clock cap → nothing. Over the cap → terminate it: every process below `claude` (its Bash tools, a test run) is SIGKILLed at once, and `claude` gets SIGTERM, on which Claude Code ends its interaction span and flushes its exporter (a bare SIGKILL left `claude_code.*` spans orphaned under a root that was never exported). It usually exits within a second; still alive 30 s past the cap (and at least one tick later) → 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 and no process has its cwd inside it (`lsof`; the worktree's own nx daemon excepted), else kept with a `warn` saying why. Teardown stops the worktree's nx daemon (nx keys each daemon to its workspace root, so no other checkout's is touched; left running, it served the next client from a deleted tree until `nx reset`), moves the tree to `<paths.home>/trash` with one rename, prunes git's record, and erases the trash in the background: a worktree with CocoaPods in it took `git worktree remove` past the step timeout.
45
45
  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`.
46
46
  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.
47
- 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)).
47
+ 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`, first wake `q:human` and parked intake issues that have a human reply, then start triage workers for `q:intake` issues the same way ([the dispatch graph](#the-dispatch-graph)).
48
48
  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.
49
49
  7. **Upkeep** (graph engine). The hourly [reaper](#upkeep) of untracked agent PRs, then the daily [re-triage](#upkeep) of `q:human`.
50
50
  8. **Heartbeat.** Write the state file.
@@ -395,7 +395,8 @@ flowchart TD
395
395
  n4["to-human"]
396
396
  n5["close-duplicate"]
397
397
  n6["deferred"]
398
- n7["close-obsolete"]
398
+ n7["blocked"]
399
+ n8["close-obsolete"]
399
400
  end_(("end"))
400
401
  start_ --> n0
401
402
  n0 -->|"started"| n1
@@ -406,7 +407,8 @@ flowchart TD
406
407
  n1 -->|"actionable"| n3
407
408
  n1 -->|"duplicate"| n5
408
409
  n1 -->|"defer"| n6
409
- n1 -->|"obsolete"| n7
410
+ n1 -->|"blocked"| n7
411
+ n1 -->|"obsolete"| n8
410
412
  n1 -->|"needsHuman"| n4
411
413
  n1 --> n4
412
414
  n2 -->|"attemptsLeft"| n0
@@ -416,7 +418,9 @@ flowchart TD
416
418
  n5 --> end_
417
419
  n6 -->|"budgetSpent"| n4
418
420
  n6 --> end_
421
+ n7 -->|"noneOpen"| n6
419
422
  n7 --> end_
423
+ n8 --> end_
420
424
  ```
421
425
 
422
426
  | Node | Kind | Queue label | Holds `running` |
@@ -428,13 +432,17 @@ flowchart TD
428
432
  | `to-human` | step | `q:human` | no |
429
433
  | `close-duplicate` | step | none | no |
430
434
  | `deferred` | step | `q:intake` | no |
435
+ | `blocked` | step | `q:intake` | no |
431
436
  | `close-obsolete` | step | none | no |
432
437
 
433
- - **The verdict.** The worker's final message must end with a JSON block, validated by zod (`TriageResult`): `{ verdict: 'actionable' | 'needs-human' | 'duplicate' | 'obsolete' | 'defer', duplicateOf?, recheckHours?, reason, title?, acceptance? }` (`duplicateOf` is required on a duplicate and cannot be the issue itself). cambium reads it from the worker's stdout log: the last `result` event's `result` text, its last fenced block (else the bare JSON).
434
- - **Outcomes.** `actionable` → a comment with the reason, the task title and acceptance checks (when given), then `q:task` with a task-graph marker at `start-worker`, attempt 1, history kept; the checks also ride in the marker (`triage`) into the task worker's prompt. The issue body is never rewritten: cambium's write path has no issue edit, and the author's text stays as written. `needs-human` → `q:human` + `why:triage`, the reason as the state comment's last failure. `duplicate` → closed with reason `duplicate` and `Duplicate of #n (<link>). <reason>`. `obsolete` (the work no longer applies, verified: the code path is gone, already fixed, its check already passed) → closed as `not_planned` with `Obsolete: <reason>`. `defer` → stays in `q:intake` at `deferred` (see below). A missing or invalid verdict (no `result` event, no JSON, a schema error) or a worker killed at `wallClockMinutes` (the unlabelled `triaging → to-human` edge) → `q:human` + `why:triage` with the error.
438
+ - **The verdict.** The worker's final message must end with a JSON block, validated by zod (`TriageResult`): `{ verdict: 'actionable' | 'needs-human' | 'duplicate' | 'obsolete' | 'defer' | 'blocked', duplicateOf?, blockedBy?, recheckHours?, reason, title?, acceptance? }` (`duplicateOf` is required on a duplicate and cannot be the issue itself; `blockedBy`, issue numbers, likewise on blocked). cambium reads it from the worker's stdout log: the last `result` event's `result` text, its last fenced block (else the bare JSON).
439
+ - **Outcomes.** `actionable` → a comment with the reason, the task title and acceptance checks (when given), then `q:task` with a task-graph marker at `start-worker`, attempt 1, history kept; the checks also ride in the marker (`triage`) into the task worker's prompt. The issue body is never rewritten: cambium's write path has no issue edit, and the author's text stays as written. `needs-human` → `q:human` + `why:triage`, the reason as the state comment's last failure. `duplicate` → closed with reason `duplicate` and `Duplicate of #n (<link>). <reason>`. `obsolete` (the work no longer applies, verified: the code path is gone, already fixed, its check already passed) → closed as `not_planned` with `Obsolete: <reason>`. `defer` → stays in `q:intake` at `deferred`, `blocked` → stays in `q:intake` at `blocked` (see below). A missing or invalid verdict (no `result` event, no JSON, a schema error) or a worker killed at `wallClockMinutes` (the unlabelled `triaging → to-human` edge) → `q:human` + `why:triage` with the error.
435
440
  - **Read-only checkout.** Triage reads code to judge feasibility and duplicates, so it gets a checkout, but a disposable one: a detached worktree at `<root>/triage-<n>` on `origin/<base>` (the repo's worktree root), no install, hydrate or `prepare`, tools `Read,Glob,Grep,Bash` with Edit/Write and every graft/git write verb denied. It is removed outright after the verdict (no `graft status`: nothing in it is worth keeping).
436
441
  - **Retries.** A worker that cannot start, or a lost `running` lease on a `q:intake` issue (Sweep), goes back to `q:intake` with attempt + 1, then to `q:human` once `phases.dispatch.maxAttempts` are spent. A marker from another graph or a finished triage starts over at attempt 1.
437
- - **Defer, not a human.** A verdict that hangs on something a machine can check later (a CD run that has not happened, a release, a merge, a deploy) is `defer`, never `needs-human`: asking a human to verify what a machine can is what the factory exists to avoid. The issue rests at `deferred` with `deferUntil` (now + `recheckHours`, else `phases.dispatch.deferHours`, default 6) and `deferReason` in its marker; Schedule skips it until then, and the next triage gets the reason in its prompt ("check it now"). A defer is not a failed attempt. A deferred issue whose GitHub "blocked by" issues are all closed, at least one after it was deferred, is triaged again at the next tick instead of waiting for `deferUntil`. After `phases.dispatch.maxDefers` (default 8) it goes to `q:human` + `why:triage` with the last reason.
442
+ - **Defer, not a human.** A verdict that hangs on something a machine can check later (a CD run that has not happened, a release, a merge, a deploy) is `defer`, never `needs-human`: asking a human to verify what a machine can is what the factory exists to avoid. The issue rests at `deferred` with `deferUntil` (now + `recheckHours`, else `phases.dispatch.deferHours`, default 6) and `deferReason` in its marker; Schedule skips it until then, and the next triage gets the reason in its prompt ("check it now"). A defer is not a failed attempt. A deferred issue whose GitHub "blocked by" issues are all closed, at least one after it was deferred, is triaged again at the next tick instead of waiting for `deferUntil`. After `phases.dispatch.maxDefers` (default 8) it goes to `q:human` + `why:triage` with the last reason. While it waits it carries `wait:deferred`.
443
+ - **Blocked by issues, not a timer.** A verdict that waits on other issues is `blocked` with `blockedBy: [n, …]`. cambium adds each as a GitHub "blocked by" link on the issue when it is missing, then parks it at `blocked` with `wait:blocked`, the open blockers in the marker's `blockedBy` and no `deferUntil`. Schedule never triages an intake issue with an open `blockedBy` issue, whoever linked it: one not yet at `blocked` (new, or deferred) is parked there first. The tick after the last blocker closes, the label comes off and the issue is triaged again, its earlier reason in the prompt. A blocked wait is not a defer and does not count toward `maxDefers`; a `blocked` verdict none of whose issues is open (closed, or the link failed) is a defer.
444
+ - **`wait:*` labels.** Intake holds two kinds of issue: awaiting triage, and parked by it. `wait:deferred` and `wait:blocked` mark the parked ones (canopy shows them apart from Intake); Schedule adds or removes them each tick to match the marker and the blockers, and any queue move drops them.
445
+ - **A human reply wakes it.** Canopy's Inbox is read-only, so a human answers by commenting on the issue. A _human reply_ is a comment written after the issue entered its current state (the later of the marker's `enteredAt` and its last history `at`) whose author is not `graft.botLogin`, not the login that wrote the state comment, and not a `Bot`-type account; a comment carrying a state marker never counts. Read takes each issue's newest 20 comments with their `createdAt` and author type (`src/human-reply.mjs`). At Schedule, before parking: a `q:human` issue with any `why:*` but `why:approve` (as re-triage), no `running` and no tracked worker, with a human reply, goes back to `q:intake` without its `why:*`, at `start-triage`, attempt 1, history kept with a `human-reply` entry, and is triaged in the same tick when a slot is free. A parked issue (`deferred` / `blocked`) with a human reply is triaged now, whatever its `deferUntil` or open blockers: the human may be saying it is not waiting on anything. The triage prompt quotes the replies since the issue last waited (author, time, body; the newest 5, each cut at 2000 characters) as the answer to the needs-human, defer or blocked reason, which it quotes too; the rubric says such a reply usually makes it actionable, folded into `title` / `acceptance`, and needs-human again (saying what is still missing) if it leaves the question open. The marker carries that context (`reply`) until triage lands a verdict. No loops: cambium's own comments never count, and the verdict starts a new state, so a triage that answers needs-human again rests until the next human reply or the daily re-triage. The daily re-triage and a hand move to `q:intake` get the same quoting.
438
446
  - **Leaving intake.** If the issue is closed or relabelled while triage runs, the verdict is dropped and the checkout removed.
439
447
  - **Tracing.** Wired as in the task graph (see [Tracing](#tracing)): the driver's node and wait spans under a `cambium.issue` root that continues mycelium's intake span from the issue body, the triage worker's `TRACEPARENT` (its `start-triage` span), and its stream-json spans when `triaging` ends.
440
448
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oakgreencc/cambium",
3
- "version": "0.0.36",
3
+ "version": "0.0.38",
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",
@@ -5,15 +5,24 @@
5
5
  *
6
6
  * - Reconcile: every tracked triage worker's issue at `triaging`.
7
7
  * - Sweep: a stale `running` lease on a `q:intake` issue runs `retry-triage`.
8
- * - Schedule: `q:intake` issues without a lease, by priority then age, up to `phases.dispatch.cap` counted from
9
- * live triage workers, skipping one deferred until later; each starts at `start-triage`.
8
+ * - Schedule: first wakes: a `q:human` issue (not `why:approve`) without a lease that has a human reply since it
9
+ * entered its state (human-reply.mjs) goes back to `q:intake` at `start-triage`, attempt 1, history kept (outcome
10
+ * `human-reply`); a parked intake issue (`deferred` / `blocked`) with one is triaged now, whatever its blockers or
11
+ * `deferUntil`. Then parks: a `q:intake` issue without a lease that has an open GitHub `blockedBy` issue goes to the
12
+ * `blocked` node (`wait:blocked`) if it is not there yet, and every other one gets the `wait:*` label its marker
13
+ * calls for (`wait:deferred` while its `deferUntil` is ahead, none once due or unblocked). Then `q:intake` issues
14
+ * without a lease, by priority then age, up to `phases.dispatch.cap` counted from live triage workers, skipping
15
+ * one deferred until later or blocked; each starts at `start-triage`.
10
16
  *
11
17
  * A turn advances one transition at a time and stops on entering a wait, at the entry node again (only Schedule
12
18
  * admits entries), at a wait that is not ready, or at the end.
13
19
  */
14
20
  import { advance } from './graph/index.mjs'
15
- import { dispatch, lostLeaseOf, nodeOf } from './graphs/dispatch.mjs'
16
- import { byPriorityThenAge, Q, RUNNING } from './labels.mjs'
21
+ import { dispatch, lostLeaseOf, nodeOf, openBlockers } from './graphs/dispatch.mjs'
22
+ import { iso, key, markerOf, setLabels, setMarker } from './issue-state.mjs'
23
+ import { byPriorityThenAge, move, Q, RUNNING, WAIT, WHY } from './labels.mjs'
24
+ import { newMarker, withHistory } from './marker.mjs'
25
+ import { humanReplies, stateSince } from './human-reply.mjs'
17
26
  import { each, staleLeases } from './tick.mjs'
18
27
  import { markerTrace, turnTracer } from './tracing.mjs'
19
28
 
@@ -120,7 +129,7 @@ export function intakeCandidates(deps, ctx) {
120
129
  issue.labels.includes(Q.intake) &&
121
130
  !issue.labels.includes(RUNNING) &&
122
131
  !store.worker(slug, issue.number) &&
123
- !deferredPast(issue, ctx.now)
132
+ (replied(deps, issue) || (!deferredPast(issue, ctx.now) && !openBlockers(issue).length))
124
133
  )
125
134
  candidates.push({ slug, issue, snap })
126
135
  const order = byPriorityThenAge(config.priorityLabels)
@@ -141,6 +150,68 @@ const deferredPast = (issue, now) => {
141
150
  return !unblockedSince(issue.blockedBy ?? [], m.enteredAt)
142
151
  }
143
152
 
153
+ /**
154
+ * The `q:intake` issues at rest (no `running`, no tracked worker), whatever the cap: these are parked or unparked.
155
+ * @param {Deps} deps @param {Ctx} ctx
156
+ */
157
+ function restingIntake(deps, ctx) {
158
+ /** @type {{ slug: string, issue: import('./github.mjs').Issue, snap: import('./github.mjs').Snapshot }[]} */
159
+ const out = []
160
+ for (const [slug, snap] of ctx.snaps)
161
+ for (const issue of snap.issues.values())
162
+ if (
163
+ issue.state === 'OPEN' &&
164
+ issue.labels.includes(Q.intake) &&
165
+ !issue.labels.includes(RUNNING) &&
166
+ !deps.store.worker(slug, issue.number)
167
+ )
168
+ out.push({ slug, issue, snap })
169
+ return out
170
+ }
171
+
172
+ /**
173
+ * The `wait:*` label a resting `q:intake` issue should carry, open blockers aside: `wait:deferred` while its
174
+ * `deferUntil` is ahead, else none (it awaits triage).
175
+ * @param {import('./github.mjs').Issue} issue @param {number} now
176
+ */
177
+ const waitLabelOf = (issue, now) => (deferredPast(issue, now) ? WAIT.deferred : null)
178
+
179
+ /**
180
+ * Park and unpark: an issue with an open `blockedBy` goes to the `blocked` node unless it rests there already with
181
+ * `wait:blocked`; any other gets the `wait:*` label {@link waitLabelOf} says, and loses the rest.
182
+ * @param {Deps} deps @param {Ctx} ctx
183
+ */
184
+ async function park(deps, ctx) {
185
+ await each(
186
+ deps,
187
+ restingIntake(deps, ctx),
188
+ async (c) => {
189
+ const { issue } = c
190
+ if (replied(deps, issue)) return
191
+ const open = openBlockers(issue)
192
+ const m = issue.stateComment?.marker
193
+ const atBlocked = m?.graph === dispatch.name && m.node === 'blocked'
194
+ if (open.length) {
195
+ if (atBlocked && issue.labels.includes(WAIT.blocked)) return
196
+ const subject = { slug: c.slug, number: issue.number, snap: c.snap, issue }
197
+ const reason =
198
+ m?.graph === dispatch.name && m.node === 'deferred' && m.deferReason
199
+ ? m.deferReason
200
+ : `GitHub shows it blocked by ${open.map((n) => `#${n}`).join(', ')}.`
201
+ await driveDispatch(deps, ctx, subject, { node: 'blocked', input: { blockedBy: open, reason } })
202
+ return
203
+ }
204
+ const want = waitLabelOf(issue, ctx.now)
205
+ const has = issue.labels.filter((l) => l.startsWith('wait:'))
206
+ await setLabels(deps, c.slug, issue, {
207
+ add: want && !has.includes(want) ? [want] : [],
208
+ remove: has.filter((l) => l !== want),
209
+ })
210
+ },
211
+ (c) => ({ repo: c.slug, issue: c.issue.number }),
212
+ )
213
+ }
214
+
144
215
  /**
145
216
  * All blockers closed, at least one after `since`.
146
217
  * @param {import('./github.mjs').Blocker[]} blockers @param {string | null} since
@@ -150,8 +221,71 @@ const unblockedSince = (blockers, since) =>
150
221
  blockers.every((b) => b.state === 'CLOSED') &&
151
222
  blockers.some((b) => !since || (!!b.closedAt && Date.parse(b.closedAt) > Date.parse(since)))
152
223
 
224
+ /**
225
+ * Parked at `deferred` or `blocked` with a human reply since: the human may be saying it is not waiting on anything,
226
+ * so triage looks now. Starting triage moves the marker on, so the same reply wakes it once.
227
+ * @param {Deps} deps @param {import('./github.mjs').Issue} issue
228
+ */
229
+ function replied(deps, issue) {
230
+ const m = issue.stateComment?.marker
231
+ if (!(m?.graph === dispatch.name && (m.node === 'deferred' || m.node === 'blocked'))) return false
232
+ return humanReplies(issue, { since: stateSince(m), botLogin: deps.config.graft.botLogin }).length > 0
233
+ }
234
+
235
+ /**
236
+ * Wake: every `q:human` issue (any `why:*` but `why:approve`, as re-triage) with no lease, no tracked worker and a
237
+ * human reply since it entered its state goes back to `q:intake` at `start-triage`, attempt 1, its history kept with
238
+ * a `human-reply` entry and the `reply` context the triage prompt quotes. The new state starts now, so the same
239
+ * reply never wakes it again: a triage that answers needs-human again rests until the next reply.
240
+ * @param {Deps} deps @param {Ctx} ctx
241
+ */
242
+ async function wake(deps, ctx) {
243
+ const botLogin = deps.config.graft.botLogin
244
+ for (const [slug, snap] of ctx.snaps)
245
+ await each(
246
+ deps,
247
+ [...snap.issues.values()].filter(
248
+ (i) =>
249
+ i.state === 'OPEN' &&
250
+ i.labels.includes(Q.human) &&
251
+ !i.labels.includes(WHY.approve) &&
252
+ !i.labels.includes(RUNNING) &&
253
+ !deps.store.worker(slug, i.number) &&
254
+ !ctx.touched.has(key(slug, i.number)),
255
+ ),
256
+ async (issue) => {
257
+ const m = markerOf(issue)
258
+ const since = stateSince(issue.stateComment?.marker)
259
+ const replies = humanReplies(issue, { since, botLogin })
260
+ if (!since || !replies.length) return
261
+ const at = iso(ctx.now)
262
+ const who = [...new Set(replies.map((r) => `@${r.author}`))].join(', ')
263
+ await setMarker(deps, slug, issue, {
264
+ ...newMarker({
265
+ graph: dispatch.name,
266
+ graphVersion: dispatch.version,
267
+ node: dispatch.entry.node,
268
+ phase: 'dispatch',
269
+ enteredAt: at,
270
+ traceparent: m.traceparent,
271
+ history: withHistory(m, { at, attempt: m.attempt, outcome: 'human-reply', reason: `reply from ${who}` })
272
+ .history,
273
+ }),
274
+ reply: { since, question: m.lastFailure ?? m.history.at(-1)?.reason ?? null },
275
+ })
276
+ await setLabels(deps, slug, issue, move(issue.labels, Q.intake))
277
+ ctx.touched.add(key(slug, issue.number))
278
+ deps.log('info', `human reply from ${who}: q:human → q:intake for triage`, { repo: slug, issue: issue.number })
279
+ },
280
+ (issue) => ({ repo: slug, issue: issue.number }),
281
+ )
282
+ }
283
+
153
284
  /** @param {Deps} deps @param {Ctx} ctx */
154
285
  async function schedule(deps, ctx) {
286
+ if (deps.config.phases.dispatch.cap <= 0) return
287
+ await wake(deps, ctx)
288
+ await park(deps, ctx)
155
289
  await each(
156
290
  deps,
157
291
  intakeCandidates(deps, ctx),
package/src/github.mjs CHANGED
@@ -13,9 +13,13 @@ import { BASE_FIELDS, baseHealthOf } from './base-health.mjs'
13
13
  /**
14
14
  * @typedef {{
15
15
  * number: number, title: string, url: string, state: 'OPEN' | 'CLOSED', createdAt: string, body: string,
16
- * labels: string[], stateComment: { id: number, marker: import('./marker.mjs').Marker } | null,
17
- * blockedBy: Blocker[],
16
+ * labels: string[], stateComment: { id: number, marker: import('./marker.mjs').Marker, author?: string | null } | null,
17
+ * blockedBy: Blocker[], comments?: Comment[],
18
18
  * }} Issue
19
+ * `stateComment.author`: the login that wrote the state comment (cambium's). `comments`: the newest 20, oldest
20
+ * first, for human-reply detection (human-reply.mjs).
21
+ * @typedef {{ author: string | null, bot: boolean, createdAt: string, body: string }} Comment
22
+ * `bot`: GitHub says the author is a `Bot` (an App).
19
23
  * @typedef {{ number: number, state: 'OPEN' | 'CLOSED', closedAt: string | null }} Blocker
20
24
  * An issue GitHub records as blocking this one (the "blocked by" relationship).
21
25
  * @typedef {{ name: string, url: string | null, summary: string }} FailingCheck
@@ -64,10 +68,12 @@ import { BASE_FIELDS, baseHealthOf } from './base-health.mjs'
64
68
  * behindBase(slug: string, number: number): Promise<{ behind: number, base: string }>,
65
69
  * updatePull(slug: string, number: number): Promise<void>,
66
70
  * linkIssue(slug: string, pr: number, issue: number): Promise<void>,
71
+ * addBlockedBy(slug: string, number: number, blocker: number): Promise<{ state: 'OPEN' | 'CLOSED' }>,
67
72
  * }} GitHub
68
73
  * `behindBase`: how many commits of its base the PR's head lacks, read live (not from the tick's snapshot), so a
69
74
  * merge earlier in the same tick counts. `updatePull`: merge the base into the PR (`graft pr update`).
70
75
  * `linkIssue`: put `Closes #<issue>` at the top of the PR's body, so the PR names the issue it closes.
76
+ * `addBlockedBy`: record GitHub's "blocked by" dependency of issue `number` on `blocker`; resolves the blocker's state.
71
77
  */
72
78
 
73
79
  const PR_FIELDS = `number url headRefName state headRefOid isInMergeQueue body mergeable reviewDecision createdAt updatedAt
@@ -106,6 +112,7 @@ fragment I on Issue {
106
112
  labels(first: 30) { nodes { name } }
107
113
  blockedBy(first: 20) { nodes { number state closedAt } }
108
114
  comments(first: 100) { nodes { databaseId body author { login } } }
115
+ recent: comments(last: 20) { nodes { createdAt body author { login __typename } } }
109
116
  }
110
117
  fragment P on PullRequest {
111
118
  number url title state createdAt headRefName baseRefName headRefOid reviewDecision
@@ -149,13 +156,19 @@ const FAILED = new Set(['FAILURE', 'ERROR', 'TIMED_OUT', 'CANCELLED', 'ACTION_RE
149
156
  /**
150
157
  * The first comment holding a marker (from `botLogin` only, when set). Issues and PRs alike.
151
158
  * @param {any} n an issue or PR node with `comments` @param {string | null} botLogin
152
- * @returns {{ id: number, marker: import('./marker.mjs').Marker } | null}
159
+ * @returns {{ id: number, marker: import('./marker.mjs').Marker, author: string | null } | null}
153
160
  */
154
161
  function stateCommentOf(n, botLogin) {
155
162
  const comment = (n.comments?.nodes ?? []).find(
156
163
  (/** @type {any} */ c) => parseMarker(c.body) && (!botLogin || c.author?.login === botLogin),
157
164
  )
158
- return comment ? { id: comment.databaseId, marker: /** @type {any} */ (parseMarker(comment.body)) } : null
165
+ return comment
166
+ ? {
167
+ id: comment.databaseId,
168
+ marker: /** @type {any} */ (parseMarker(comment.body)),
169
+ author: comment.author?.login ?? null,
170
+ }
171
+ : null
159
172
  }
160
173
 
161
174
  /** @param {any} n @returns {string[]} */
@@ -220,9 +233,15 @@ function toIssue(n, botLogin) {
220
233
  stateComment: stateCommentOf(n, botLogin),
221
234
  blockedBy: (n.blockedBy?.nodes ?? []).filter(Boolean).map((/** @type {any} */ b) => ({
222
235
  number: b.number,
223
- state: b.state,
236
+ state: b.state === 'OPEN' ? 'OPEN' : 'CLOSED',
224
237
  closedAt: b.closedAt ?? null,
225
238
  })),
239
+ comments: (n.recent?.nodes ?? []).filter(Boolean).map((/** @type {any} */ c) => ({
240
+ author: c.author?.login ?? null,
241
+ bot: c.author?.__typename === 'Bot',
242
+ createdAt: c.createdAt ?? '',
243
+ body: c.body ?? '',
244
+ })),
226
245
  }
227
246
  }
228
247
 
@@ -475,5 +494,12 @@ export function graftGitHub({ config, exec: run = exec }) {
475
494
  const linked = `Closes #${issue}${body ? `\n\n${body}` : ''}`
476
495
  await graft(slug, ['api', 'PATCH', path, '--body', JSON.stringify({ body: linked })])
477
496
  },
497
+ async addBlockedBy(slug, number, blocker) {
498
+ // The dependencies API takes the blocker's database id, not its number.
499
+ const b = await json(graft(slug, ['api', 'GET', `/repos/${slug}/issues/${blocker}`]))
500
+ const path = `/repos/${slug}/issues/${number}/dependencies/blocked_by`
501
+ await graft(slug, ['api', 'POST', path, '--body', JSON.stringify({ issue_id: b.id })])
502
+ return { state: b.state === 'open' ? 'OPEN' : 'CLOSED' }
503
+ },
478
504
  }
479
505
  }
@@ -2,7 +2,7 @@
2
2
  /**
3
3
  * The Dispatch phase as a graph: a `q:intake` issue is triaged by a one-shot `claude -p` worker whose final
4
4
  * message carries a typed verdict ({@link TriageResult}), then moved to `q:task`, moved to `q:human`, or closed as
5
- * a duplicate or obsolete, or deferred to be triaged again later. Same conventions as the task graph (graphs/task.mjs): each node declares its queue label and
5
+ * a duplicate or obsolete, deferred to be triaged again later, or parked as blocked until its GitHub `blockedBy` issues close. Same conventions as the task graph (graphs/task.mjs): each node declares its queue label and
6
6
  * whether it holds `running`, and a node's write is the marker first, then the labels via `move()`.
7
7
  *
8
8
  * The triage worker runs in a read-only checkout (workers.mjs `readOnly`): detached at the base branch, no install,
@@ -11,9 +11,10 @@
11
11
  import { z } from 'zod'
12
12
  import { defineGraph, defineNode, defineWait, END } from '../graph/index.mjs'
13
13
  import { iso, key, markerOf, MIN, setLabels, setMarker } from '../issue-state.mjs'
14
- import { move, Q, WHY } from '../labels.mjs'
14
+ import { move, Q, WAIT, WHY } from '../labels.mjs'
15
15
  import { newMarker, withHistory } from '../marker.mjs'
16
16
  import { readTriage, TriageResult, triageComment, triagePrompt } from '../phases/dispatch.mjs'
17
+ import { humanReplies, quoted, replyContextOf } from '../human-reply.mjs'
17
18
  import { traceWorker } from '../tracing.mjs'
18
19
  import { stopOverdue } from '../workers.mjs'
19
20
  import { task } from './task.mjs'
@@ -29,7 +30,12 @@ import { task } from './task.mjs'
29
30
  */
30
31
 
31
32
  /** The nodes an issue in `q:intake` can rest at; a marker elsewhere starts triage over at attempt 1. */
32
- const INTAKE_NODES = new Set(['start-triage', 'triaging', 'retry-triage', 'deferred'])
33
+ const INTAKE_NODES = new Set(['start-triage', 'triaging', 'retry-triage', 'deferred', 'blocked'])
34
+ /** The nodes before a verdict: the marker keeps its `reply` context through them; any other node drops it. */
35
+ const PRE_VERDICT = new Set(['start-triage', 'triaging', 'retry-triage'])
36
+
37
+ /** The open issues among `issue`'s GitHub `blockedBy` links. @param {Issue} issue */
38
+ export const openBlockers = (issue) => (issue.blockedBy ?? []).filter((b) => b.state === 'OPEN').map((b) => b.number)
33
39
 
34
40
  /** The pseudo-branch that names an issue's triage checkout (`<root>/triage-<n>`); never created. @param {number} n */
35
41
  export const triageBranch = (n) => `cambium/triage-${n}`
@@ -61,6 +67,7 @@ async function land(ctx, node, marker, { extra = [], status = 'waiting' } = {})
61
67
  const decl = nodeOf(node)
62
68
  await setMarker(ctx, slug, issue, {
63
69
  ...graphMarker(marker),
70
+ ...(PRE_VERDICT.has(node) ? {} : { reply: null }),
64
71
  graph: dispatch.name,
65
72
  graphVersion: dispatch.version,
66
73
  phase: 'dispatch',
@@ -110,6 +117,8 @@ const needsHuman = (/** @type {Triaged} */ o) => verdictOf(o) === 'needs-human'
110
117
  const duplicate = (/** @type {Triaged} */ o) => verdictOf(o) === 'duplicate'
111
118
  const obsolete = (/** @type {Triaged} */ o) => verdictOf(o) === 'obsolete'
112
119
  const defer = (/** @type {Triaged} */ o) => verdictOf(o) === 'defer'
120
+ const blocked = (/** @type {Triaged} */ o) => verdictOf(o) === 'blocked'
121
+ const noneOpen = (/** @type {{ to: string }} */ o) => o.to === 'defer'
113
122
 
114
123
  /** @param {DispatchCtx} ctx */
115
124
  export const lostLeaseOf = (ctx) => ({
@@ -149,8 +158,12 @@ const startTriage = declare(
149
158
  } catch (err) {
150
159
  return { to: 'retry', reason: `could not start triage: ${errText(err)}`, outcome: 'spawn-failed' }
151
160
  }
161
+ // A human reply since the issue last waited (on a needs-human, defer or blocked reason) is the answer to it.
162
+ const reply = m0.reply ?? replyContextOf(markerOf(issue))
163
+ const replies = reply ? quoted(humanReplies(issue, { since: reply.since, botLogin: config.graft.botLogin })) : []
152
164
  await land(ctx, 'triaging', {
153
165
  ...m0,
166
+ reply,
154
167
  deferUntil: null,
155
168
  host: config.host,
156
169
  start: iso(ctx.tick.now),
@@ -183,7 +196,13 @@ const startTriage = declare(
183
196
  queued,
184
197
  agentsMd,
185
198
  deferHours: caps.deferHours,
186
- deferred: m0.deferReason ? { count: m0.defers ?? 0, reason: m0.deferReason } : null,
199
+ deferred:
200
+ !replies.length && m0.deferReason && !m0.blockedBy?.length
201
+ ? { count: m0.defers ?? 0, reason: m0.deferReason }
202
+ : null,
203
+ blocked:
204
+ !replies.length && m0.blockedBy?.length ? { by: m0.blockedBy, reason: m0.deferReason ?? '' } : null,
205
+ replied: replies.length ? { question: reply?.question ?? null, replies } : null,
187
206
  }),
188
207
  })
189
208
  } catch (err) {
@@ -455,21 +474,27 @@ const deferred = declare(
455
474
  }
456
475
  const hours = d.recheckHours ?? deferHours
457
476
  const until = iso(ctx.tick.now + hours * 60 * MIN)
458
- await land(ctx, 'deferred', {
459
- ...withHistory(m, {
460
- at: iso(ctx.tick.now),
461
- attempt: m.attempt,
462
- outcome: 'defer',
463
- reason: d.reason,
464
- log: d.log,
465
- }),
466
- defers,
467
- deferUntil: until,
468
- deferReason: d.reason,
469
- host: null,
470
- start: null,
471
- input: null,
472
- })
477
+ await land(
478
+ ctx,
479
+ 'deferred',
480
+ {
481
+ ...withHistory(m, {
482
+ at: iso(ctx.tick.now),
483
+ attempt: m.attempt,
484
+ outcome: 'defer',
485
+ reason: d.reason,
486
+ log: d.log,
487
+ }),
488
+ defers,
489
+ deferUntil: until,
490
+ deferReason: d.reason,
491
+ blockedBy: null,
492
+ host: null,
493
+ start: null,
494
+ input: null,
495
+ },
496
+ { extra: [WAIT.deferred] },
497
+ )
473
498
  ctx.log('info', `triage deferred until ${until} (${defers}/${maxDefers}): ${d.reason.split('\n')[0]}`, {
474
499
  repo: ctx.subject.slug,
475
500
  issue: issue.number,
@@ -480,6 +505,77 @@ const deferred = declare(
480
505
  { queue: Q.intake, running: false },
481
506
  )
482
507
 
508
+ const BlockedIn = z.object({
509
+ blockedBy: z.array(z.number().int().positive()).min(1),
510
+ reason: z.string(),
511
+ log: z.string().optional(),
512
+ })
513
+ const blockedNode = declare(
514
+ defineNode({
515
+ name: 'blocked',
516
+ input: BlockedIn,
517
+ output: z.discriminatedUnion('to', [
518
+ z.object({ to: z.literal('wait'), blockedBy: z.array(z.number().int()) }),
519
+ z.object({ to: z.literal('defer'), reason: z.string(), log: z.string() }),
520
+ ]),
521
+ /**
522
+ * Blocked: the issue waits on other issues. Each one triage named that GitHub does not link yet is added as a
523
+ * `blockedBy` link; then the issue rests here in `q:intake` with `wait:blocked` and no `deferUntil`. Schedule
524
+ * does not triage it while any `blockedBy` issue is open, and triages it the tick after the last one closes.
525
+ * Not a defer: `maxDefers` does not count it. Schedule also parks an untriaged issue here that GitHub already
526
+ * shows blocked. When none of the named issues is open (closed, or the link failed) it is a plain defer.
527
+ * @param {z.infer<typeof BlockedIn>} b @param {DispatchCtx} ctx
528
+ */
529
+ run: async (b, ctx) => {
530
+ const { slug } = ctx.subject
531
+ const issue = issueOf(ctx)
532
+ const m = markerOf(issue)
533
+ const links = [...(issue.blockedBy ?? [])]
534
+ for (const n of b.blockedBy) {
535
+ if (n === issue.number || links.some((l) => l.number === n)) continue
536
+ try {
537
+ const { state } = await ctx.github.addBlockedBy(slug, issue.number, n)
538
+ links.push({ number: n, state, closedAt: null })
539
+ ctx.log('info', `linked blockedBy #${n}`, { repo: slug, issue: issue.number })
540
+ } catch (err) {
541
+ ctx.log('warn', `could not link blockedBy #${n}: ${errText(err)}`, { repo: slug, issue: issue.number })
542
+ }
543
+ }
544
+ issue.blockedBy = links
545
+ const open = openBlockers(issue)
546
+ const list = b.blockedBy.map((n) => `#${n}`).join(', ')
547
+ if (!open.length)
548
+ return { to: 'defer', reason: `blocked by ${list}, but none is open. ${b.reason}`, log: b.log ?? '' }
549
+ await land(
550
+ ctx,
551
+ 'blocked',
552
+ {
553
+ ...withHistory(m, {
554
+ at: iso(ctx.tick.now),
555
+ attempt: m.attempt,
556
+ outcome: 'blocked',
557
+ reason: `${open.map((n) => `#${n}`).join(', ')}: ${b.reason}`,
558
+ ...(b.log ? { log: b.log } : {}),
559
+ }),
560
+ deferUntil: null,
561
+ deferReason: b.reason,
562
+ blockedBy: open,
563
+ host: null,
564
+ start: null,
565
+ input: null,
566
+ },
567
+ { extra: [WAIT.blocked] },
568
+ )
569
+ ctx.log('info', `blocked by ${open.map((n) => `#${n}`).join(', ')}: ${b.reason.split('\n')[0]}`, {
570
+ repo: slug,
571
+ issue: issue.number,
572
+ })
573
+ return { to: 'wait', blockedBy: open }
574
+ },
575
+ }),
576
+ { queue: Q.intake, running: false },
577
+ )
578
+
483
579
  const ObsIn = z.object({ reason: z.string(), log: z.string() })
484
580
  const closeObsolete = declare(
485
581
  defineNode({
@@ -527,7 +623,7 @@ export const dispatch = defineGraph({
527
623
  name: 'dispatch',
528
624
  version: 1,
529
625
  entry: { queue: Q.intake, node: 'start-triage', input: () => ({}) },
530
- nodes: [startTriage, triaging, retryTriage, toTask, toHuman, closeDuplicate, deferred, closeObsolete],
626
+ nodes: [startTriage, triaging, retryTriage, toTask, toHuman, closeDuplicate, deferred, blockedNode, closeObsolete],
531
627
  edges: [
532
628
  ['start-triage', 'triaging', started, (o) => ({ attempt: o.attempt })],
533
629
  ['start-triage', 'to-human', budgetSpent],
@@ -537,6 +633,7 @@ export const dispatch = defineGraph({
537
633
  ['triaging', 'to-task', actionable, (o) => ({ ...pick(o.result, ['reason', 'title', 'acceptance']), log: o.log })],
538
634
  ['triaging', 'close-duplicate', duplicate, (o) => ({ ...pick(o.result, ['duplicateOf', 'reason']), log: o.log })],
539
635
  ['triaging', 'deferred', defer, (o) => ({ ...pick(o.result, ['reason', 'recheckHours']), log: o.log })],
636
+ ['triaging', 'blocked', blocked, (o) => ({ blockedBy: o.result.blockedBy, reason: o.result.reason, log: o.log })],
540
637
  ['triaging', 'close-obsolete', obsolete, (o) => ({ reason: o.result.reason, log: o.log })],
541
638
  ['triaging', 'to-human', needsHuman, (o) => ({ reason: o.result.reason, outcome: 'needs-human', log: o.log })],
542
639
  ['triaging', 'to-human'],
@@ -547,6 +644,8 @@ export const dispatch = defineGraph({
547
644
  ['close-duplicate', END],
548
645
  ['deferred', 'to-human', budgetSpent],
549
646
  ['deferred', END],
647
+ ['blocked', 'deferred', noneOpen, (o) => ({ reason: o.reason, log: o.log })],
648
+ ['blocked', END],
550
649
  ['close-obsolete', END],
551
650
  ],
552
651
  })
@@ -0,0 +1,78 @@
1
+ // @ts-check
2
+ /**
3
+ * Human replies: a comment on an issue, written after the issue entered its current state, by someone who is
4
+ * neither cambium nor a bot. A human answers a `q:human` question (or says a parked issue is not really blocked) by
5
+ * commenting; cambium sends the issue back to triage at once and quotes the reply in the triage prompt
6
+ * (dispatch-engine.mjs `wake`, graphs/dispatch.mjs `start-triage`).
7
+ */
8
+ import { parseMarker } from './marker.mjs'
9
+
10
+ /**
11
+ * @typedef {import('./github.mjs').Issue} Issue
12
+ * @typedef {import('./github.mjs').Comment} Comment
13
+ * @typedef {import('./marker.mjs').Marker} Marker
14
+ * @typedef {{ since: string, question: string | null }} ReplyContext
15
+ * What a reply answers: the state's start (replies after it count) and the reason the issue was waiting for.
16
+ */
17
+
18
+ /** A reply quoted in the triage prompt is cut to this many characters. */
19
+ export const REPLY_CHARS = 2000
20
+ /** At most this many replies are quoted, the newest. */
21
+ export const REPLIES_KEPT = 5
22
+
23
+ /**
24
+ * When the marker's issue entered its current state: the later of `enteredAt` and the last history `at` (a
25
+ * stage-era write can leave an old `enteredAt` behind a newer history entry). Null without either.
26
+ * @param {Marker | null | undefined} m @returns {string | null}
27
+ */
28
+ export function stateSince(m) {
29
+ if (!m) return null
30
+ const times = [m.enteredAt, m.history.at(-1)?.at].filter((t) => t && Number.isFinite(Date.parse(t)))
31
+ if (!times.length) return null
32
+ return /** @type {string} */ (
33
+ times.reduce((a, b) => (Date.parse(/** @type {string} */ (b)) > Date.parse(/** @type {string} */ (a)) ? b : a))
34
+ )
35
+ }
36
+
37
+ /**
38
+ * The human replies on `issue` written after `since`, oldest first. Never cambium's: not by `botLogin`, not by the
39
+ * login that wrote the state comment, not a `Bot`-type author, and not a comment carrying a state marker. No `since`:
40
+ * none (nothing to be a reply to).
41
+ * @param {Issue} issue @param {{ since: string | null, botLogin?: string | null }} o @returns {Comment[]}
42
+ */
43
+ export function humanReplies(issue, { since, botLogin = null }) {
44
+ if (!since) return []
45
+ const after = Date.parse(since)
46
+ if (!Number.isFinite(after)) return []
47
+ const self = new Set([botLogin, issue.stateComment?.author].filter(Boolean))
48
+ return (issue.comments ?? []).filter(
49
+ (c) => !!c.author && !c.bot && !self.has(c.author) && !parseMarker(c.body) && Date.parse(c.createdAt) > after,
50
+ )
51
+ }
52
+
53
+ /**
54
+ * The context a triage after `m` quotes replies against, or null when `m` is not waiting on anything: the
55
+ * dispatch graph's `deferred` / `blocked` (the defer or blocked reason), or any `to-human` (the needs-human reason).
56
+ * @param {Marker | null | undefined} m @returns {ReplyContext | null}
57
+ */
58
+ export function replyContextOf(m) {
59
+ if (!m || m.status === 'done') return null
60
+ const since = stateSince(m)
61
+ if (!since) return null
62
+ if (m.graph === 'dispatch' && (m.node === 'deferred' || m.node === 'blocked'))
63
+ return { since, question: m.deferReason ?? m.history.at(-1)?.reason ?? null }
64
+ if (m.node === 'to-human') return { since, question: m.lastFailure ?? m.history.at(-1)?.reason ?? null }
65
+ return null
66
+ }
67
+
68
+ /**
69
+ * The replies as the triage prompt quotes them: the newest {@link REPLIES_KEPT}, each cut to {@link REPLY_CHARS}.
70
+ * @param {Comment[]} replies @returns {{ author: string, at: string, body: string }[]}
71
+ */
72
+ export function quoted(replies) {
73
+ return replies.slice(-REPLIES_KEPT).map((c) => ({
74
+ author: c.author ?? 'unknown',
75
+ at: c.createdAt,
76
+ body: c.body.length > REPLY_CHARS ? `${c.body.slice(0, REPLY_CHARS)}… (cut)` : c.body,
77
+ }))
78
+ }
package/src/labels.mjs CHANGED
@@ -7,6 +7,12 @@ export const Q = /** @type {const} */ ({
7
7
  })
8
8
  export const QUEUE_LABELS = Object.values(Q)
9
9
  export const RUNNING = 'running'
10
+ /**
11
+ * A parked `q:intake` issue triage already looked at, so canopy can tell it from one awaiting triage:
12
+ * `wait:deferred` rests at the dispatch graph's `deferred` node until `deferUntil`; `wait:blocked` has open GitHub
13
+ * `blockedBy` issues. Any queue move drops them unless it names one again.
14
+ */
15
+ export const WAIT = /** @type {const} */ ({ deferred: 'wait:deferred', blocked: 'wait:blocked' })
10
16
  export const WHY = /** @type {const} */ ({
11
17
  budget: 'why:budget',
12
18
  reject: 'why:reject',
@@ -25,7 +31,10 @@ export function move(labels, target, { running = false, extra = [] } = {}) {
25
31
  const want = new Set([...(target ? [target] : []), ...extra, ...(running ? [RUNNING] : [])])
26
32
  const leaving = (/** @type {string} */ l) =>
27
33
  !want.has(l) &&
28
- ((l.startsWith('q:') && l !== target) || l === RUNNING || (l.startsWith('why:') && target !== Q.human))
34
+ ((l.startsWith('q:') && l !== target) ||
35
+ l === RUNNING ||
36
+ (l.startsWith('why:') && target !== Q.human) ||
37
+ l.startsWith('wait:'))
29
38
  return {
30
39
  add: [...want].filter((l) => !labels.includes(l)),
31
40
  remove: labels.filter(leaving),
package/src/marker.mjs CHANGED
@@ -47,11 +47,16 @@
47
47
  * defers?: number,
48
48
  * deferUntil?: string | null,
49
49
  * deferReason?: string | null,
50
+ * blockedBy?: number[] | null,
51
+ * reply?: { since: string, question: string | null } | null,
50
52
  * }} Marker
51
53
  * `mergeRefusal`: the last `graft pr merge` cambium was refused (PR graph `merge`), and on which head.
52
54
  * `reworks`: how many times the PR graph sent this issue's PR back to a worker.
53
55
  * `defers`, `deferUntil`, `deferReason`: the dispatch graph's `deferred` node: how many times triage deferred, until
54
- * when, and what the next triage should check.
56
+ * when, and what the next triage should check. At the `blocked` node `deferReason` is why and `blockedBy` the open
57
+ * GitHub `blockedBy` issues it waits on (no `deferUntil`).
58
+ * `reply`: while triage is pending or running, what a human reply answers (human-reply.mjs): human comments after
59
+ * `since` are quoted in the triage prompt as the answer to `question`. Cleared when triage lands a verdict.
55
60
  * `triage`: what the dispatch graph's triage added when it handed the issue to `q:task`; the task prompt shows it.
56
61
  * @typedef {{ graph: string, entryNode: string, nodes?: Iterable<string> }} QueueOwner
57
62
  */
@@ -180,7 +185,10 @@ export function renderMarker(input, { maxAttempts } = {}) {
180
185
  (marker.pr ? ` · PR #${marker.pr}` : '') +
181
186
  (marker.host ? ` · host \`${marker.host}\`` : '') +
182
187
  (marker.start ? ` · started ${marker.start}` : '') +
183
- (marker.node === 'deferred' && marker.deferUntil ? ` · re-triage after ${marker.deferUntil}` : ''),
188
+ (marker.node === 'deferred' && marker.deferUntil ? ` · re-triage after ${marker.deferUntil}` : '') +
189
+ (marker.node === 'blocked' && marker.blockedBy?.length
190
+ ? ` · re-triage once ${marker.blockedBy.map((n) => `#${n}`).join(', ')} close`
191
+ : ''),
184
192
  ]
185
193
  if (marker.lastFailure)
186
194
  lines.push(
@@ -21,8 +21,9 @@ export const DISPATCH_NOT_BUILT = 'dispatch phase is not built yet; q:intake iss
21
21
  /** The verdict a triage worker ends with, as the last JSON block of its final message. */
22
22
  export const TriageResult = z
23
23
  .object({
24
- verdict: z.enum(['actionable', 'needs-human', 'duplicate', 'defer', 'obsolete']),
24
+ verdict: z.enum(['actionable', 'needs-human', 'duplicate', 'defer', 'blocked', 'obsolete']),
25
25
  duplicateOf: z.number().int().positive().optional(),
26
+ blockedBy: z.array(z.number().int().positive()).min(1).optional(),
26
27
  recheckHours: z.number().positive().max(168).optional(),
27
28
  reason: z.string().trim().min(1),
28
29
  title: z.string().trim().min(1).optional(),
@@ -32,6 +33,10 @@ export const TriageResult = z
32
33
  message: 'a duplicate verdict needs duplicateOf',
33
34
  path: ['duplicateOf'],
34
35
  })
36
+ .refine((r) => r.verdict !== 'blocked' || r.blockedBy !== undefined, {
37
+ message: 'a blocked verdict needs blockedBy',
38
+ path: ['blockedBy'],
39
+ })
35
40
 
36
41
  /** @typedef {z.infer<typeof TriageResult>} Triage */
37
42
 
@@ -100,6 +105,8 @@ export function readTriage(log, issue) {
100
105
  return { ok: false, error: `invalid triage result: ${parsed.error.issues.map(formatIssue).join('; ')}` }
101
106
  if (parsed.data.verdict === 'duplicate' && parsed.data.duplicateOf === issue)
102
107
  return { ok: false, error: `invalid triage result: duplicateOf: #${issue} cannot duplicate itself` }
108
+ if (parsed.data.verdict === 'blocked' && parsed.data.blockedBy?.includes(issue))
109
+ return { ok: false, error: `invalid triage result: blockedBy: #${issue} cannot block itself` }
103
110
  return { ok: true, result: parsed.data }
104
111
  }
105
112
 
@@ -111,9 +118,23 @@ export function readTriage(log, issue) {
111
118
  * repo: string, baseBranch: string, issue: import('../github.mjs').Issue,
112
119
  * queued: { number: number, title: string, labels: string[] }[], agentsMd: string | null,
113
120
  * deferred?: { count: number, reason: string } | null, deferHours?: number,
121
+ * blocked?: { by: number[], reason: string } | null,
122
+ * replied?: { question: string | null, replies: { author: string, at: string, body: string }[] } | null,
114
123
  * }} input
124
+ * `blocked`: an earlier triage parked it on these issues, all closed now. `replied`: a human commented since the
125
+ * issue last waited; `question` is what it waited on (the needs-human, defer or blocked reason).
115
126
  */
116
- export function triagePrompt({ repo, baseBranch, issue, queued, agentsMd, deferred = null, deferHours = 6 }) {
127
+ export function triagePrompt({
128
+ repo,
129
+ baseBranch,
130
+ issue,
131
+ queued,
132
+ agentsMd,
133
+ deferred = null,
134
+ deferHours = 6,
135
+ blocked = null,
136
+ replied = null,
137
+ }) {
117
138
  const others = queued
118
139
  .filter((q) => q.number !== issue.number)
119
140
  .map((q) => `- #${q.number} ${q.title} (${q.labels.filter((l) => l.startsWith('q:')).join(', ') || 'no queue'})`)
@@ -128,25 +149,43 @@ Verdicts:
128
149
  - needs-human: too foggy to ticket; a decision only a human can make (direction, priority, money, access, policy); information no one but a human has; or work that is not a code change in this repository. \`reason\` says exactly what the human must decide or supply. Never for something a machine can check, now or later.
129
150
  - duplicate: the same work as another issue, open or closed. \`duplicateOf\` is that issue's number (never #${issue.number}); \`reason\` says why they are the same.
130
151
  - obsolete: the work no longer applies, and you verified it: the code path is gone, the bug is already fixed on ${baseBranch}, or its verification already passed. cambium closes it as not planned. \`reason\` gives the evidence (commit, file, run).
131
- - defer: the verdict hangs on something a machine can check later but not yet: a CI or CD run that has not happened, a release, a PR still merging, a deploy, an upstream fix. cambium triages it again after \`recheckHours\` (default ${deferHours}). \`reason\` says exactly what to check next time and what each answer means (e.g. "next main cd run green → obsolete; red → actionable").
152
+ - defer: the verdict hangs on something a machine can check later but not yet: a CI or CD run that has not happened, a release, a PR still merging, a deploy, an upstream fix. cambium triages it again after \`recheckHours\` (default ${deferHours}). \`reason\` says exactly what to check next time and what each answer means (e.g. "next main cd run green → obsolete; red → actionable"). Not for waiting on another issue: that is blocked.
153
+ - blocked: it cannot start until other issues in ${repo} are done. \`blockedBy\` lists their numbers (never #${issue.number}); cambium records each as a GitHub "blocked by" link on this issue and triages it again as soon as the last of them closes, not on a timer. \`reason\` says what each blocker must deliver.
132
154
 
133
155
  How to look:
134
156
  - Read the code here (Read, Glob, Grep) to judge what the change touches and whether it already exists.
135
157
  - First, has it already been done? Its comments (\`graft api GET /repos/${repo}/issues/${issue.number}/comments\`) and its timeline (\`graft api GET '/repos/${repo}/issues/${issue.number}/timeline?per_page=100'\`: cross-referenced PRs, and whether they merged) often say so. A merged PR whose change is on ${baseBranch}, and nothing left of the issue, is obsolete; a PR still open or in CI is defer.
158
+ - Does it already wait on other issues? Its GitHub "blocked by" links: \`graft api GET /repos/${repo}/issues/${issue.number}/dependencies/blocked_by\`. An open one, or prose naming an open issue it needs first, is blocked.
136
159
  - Read an issue with \`graft issue read <n>\`; search with \`graft api GET '/search/issues?q=repo:${repo}+is:issue+<words>'\`. Never \`gh\`.
160
+ - A human reply (quoted below, when there is one) answering the open question usually makes the issue actionable: fold the answer into \`title\` and \`acceptance\` so the task worker gets it with the issue. If the reply leaves the question open, the verdict is needs-human again, and \`reason\` says what is still missing.
137
161
  - Be quick: a verdict, not an investigation. When in doubt whether the work is clear enough to do, choose needs-human; when in doubt whether something is true, check it, or defer until it can be checked.
138
162
 
139
163
  End your final message with exactly one fenced JSON block, and nothing after it:
140
164
  \`\`\`json
141
- { "verdict": "actionable" | "needs-human" | "duplicate" | "obsolete" | "defer", "duplicateOf": 123, "recheckHours": 6, "reason": "…", "title": "…", "acceptance": ["…"] }
165
+ { "verdict": "actionable" | "needs-human" | "duplicate" | "obsolete" | "defer" | "blocked", "duplicateOf": 123, "blockedBy": [124], "recheckHours": 6, "reason": "…", "title": "…", "acceptance": ["…"] }
142
166
  \`\`\`
143
- \`duplicateOf\` only for duplicate; \`recheckHours\` only for defer, and optional; \`title\` and \`acceptance\` only for actionable, and optional. A missing or malformed block sends the issue to a human with the error.
144
- ${deferred ? `\nThis is re-triage ${deferred.count + 1}: an earlier triage deferred it to check this:\n${deferred.reason}\nCheck it now. If it still cannot be checked, defer again.\n` : ''}${others ? `\nOther issues in cambium's queues right now:\n${others}\n` : ''}
167
+ \`duplicateOf\` only for duplicate; \`blockedBy\` only for blocked; \`recheckHours\` only for defer, and optional; \`title\` and \`acceptance\` only for actionable, and optional. A missing or malformed block sends the issue to a human with the error.
168
+ ${deferred ? `\nThis is re-triage ${deferred.count + 1}: an earlier triage deferred it to check this:\n${deferred.reason}\nCheck it now. If it still cannot be checked, defer again.\n` : ''}${blocked ? `\nAn earlier triage found it blocked by ${blocked.by.map((n) => `#${n}`).join(', ')}, now closed:\n${blocked.reason}\nJudge it again now that they are done.\n` : ''}${replied ? repliedNote(replied) : ''}${others ? `\nOther issues in cambium's queues right now:\n${others}\n` : ''}
145
169
  --- Issue #${issue.number}: ${issue.title} (${issue.url})
146
170
  ${issue.body}
147
171
  ${agentsMd ? `\n--- AGENTS.md (the contract a task worker will follow)\n${agentsMd}` : ''}`
148
172
  }
149
173
 
174
+ /**
175
+ * The prompt's section quoting the human replies as the answer to what the issue waited on.
176
+ * @param {NonNullable<Parameters<typeof triagePrompt>[0]['replied']>} r
177
+ */
178
+ function repliedNote({ question, replies }) {
179
+ const quote = (/** @type {string} */ s) =>
180
+ s
181
+ .split('\n')
182
+ .map((l) => `> ${l}`)
183
+ .join('\n')
184
+ return `\nAn earlier triage or step left it waiting on this:\n${quote(question ?? '(no reason recorded)')}\nA human has since replied on the issue. Read the reply as the answer to that:\n${replies
185
+ .map((r) => `\n@${r.author} at ${r.at}:\n${quote(r.body)}\n`)
186
+ .join('')}`
187
+ }
188
+
150
189
  /**
151
190
  * The comment triage leaves on an actionable issue.
152
191
  * @param {{ reason: string, title?: string, acceptance?: string[] }} t