@oakgreencc/cambium 0.0.42 → 0.0.44

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
@@ -54,16 +54,17 @@ A requeue is `q:task` with attempt + 1, or, once `maxAttempts` are spent, `q:hum
54
54
 
55
55
  ## State on GitHub
56
56
 
57
- | Label | Meaning |
58
- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
59
- | `q:intake`, `q:task`, `q:human`, `q:promote` | The queue. At most one per open issue. |
60
- | `q:promote` on a closed issue | Merged into `release.from`, not yet in `release.to` ([Awaiting promotion](#awaiting-promotion)). |
61
- | `running` | A worker holds the lease (with `q:task`). |
62
- | `why:budget`, `why:triage` (also `why:reject`, …) | Why it is in `q:human` (`why:triage`: sent there by triage, see below). |
63
- | `why:rescue` | In `q:human` because the [rescue graph](#the-rescue-graph) could not unstick it. |
64
- | `rescue` | A root-cause ticket the rescue graph filed. |
65
- | _no `q:` label_, cambium comment, open `agent/*` PR | Submitted: in the Release Queue, which is the PR's merge-queue state. |
66
- | `priority:critical` … `priority:low` | Scheduling order (configurable). Unlabelled sorts after every listed priority. |
57
+ | Label | Meaning |
58
+ | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
59
+ | `q:intake`, `q:task`, `q:human`, `q:promote` | The queue. At most one per open issue. |
60
+ | `q:promote` on a closed issue | Merged into `release.from`, not yet in `release.to` ([Awaiting promotion](#awaiting-promotion)). |
61
+ | `running` | A worker holds the lease (with `q:task`). |
62
+ | `why:budget`, `why:triage` (also `why:reject`, …) | Why it is in `q:human` (`why:triage`: sent there by triage, see below). |
63
+ | `why:rescue` | In `q:human` because the [rescue graph](#the-rescue-graph) could not unstick it. |
64
+ | `ask:*` | With `q:human`: what the person is asked (`ask:decide`, `ask:verify`, `ask:chore`, `ask:approve`; plus `ask:session`). |
65
+ | `rescue` | A root-cause ticket the rescue graph filed. |
66
+ | _no `q:` label_, cambium comment, open `agent/*` PR | Submitted: in the Release Queue, which is the PR's merge-queue state. |
67
+ | `priority:critical` … `priority:low` | Scheduling order (configurable). Unlabelled sorts after every listed priority. |
67
68
 
68
69
  Only cambium moves these labels; workers have `graft issue label` and `graft issue edit` denied.
69
70
 
@@ -129,7 +130,7 @@ One JSON file. Everything but `repos` is optional; these are the defaults:
129
130
  "priorityLabels": ["priority:critical", "priority:high", "priority:medium", "priority:low"],
130
131
  "release": { "enabled": false, "time": "06:00" },
131
132
  "reaper": { "everyMinutes": 60, "staleMinutes": 30, "orphanDays": 3 },
132
- "retriage": { "enabled": false, "time": "05:00" },
133
+ "retriage": { "enabled": false, "time": "05:00", "maxSkipDays": 14 },
133
134
  "rescue": {
134
135
  "everyMinutes": 60,
135
136
  "staleHours": 12,
@@ -205,7 +206,7 @@ Two clocks in the graph engine's `upkeep` step, after Watch (`src/upkeep.mjs`),
205
206
  | No issue (none named, or not readable) | Close the PR after `reaper.orphanDays` (default 3) untouched. The branch stays. |
206
207
  | A live worker on the issue, or the issue already tracks this PR | Leave it. |
207
208
 
208
- **Re-triage** (once a day at `retriage.time` when `retriage.enabled`; off by default). Every `q:human` issue goes back to `q:intake` without its `why:*`, so [triage](#the-dispatch-graph) looks again under its current rubric: done since (obsolete, closed), now checkable (defer), or now a task. Not `why:approve`, a merge only a human may make, where a re-triage would start a duplicate Task. Not one holding `running`. The reaper runs first, so an issue whose PR it adopted is not re-triaged.
209
+ **Re-triage** (once a day at `retriage.time` when `retriage.enabled`; off by default). Every `q:human` issue goes back to `q:intake` without its `why:*`, so [triage](#the-dispatch-graph) looks again under its current rubric: done since (obsolete, closed), now checkable (defer), or now a task. Not `why:approve`, a merge only a human may make, where a re-triage would start a duplicate Task. Not one holding `running`. Not one whose _triage inputs_ are unchanged: `start-triage` records on the marker a `fingerprint` (`{ hash, at }`, `src/triage-inputs.mjs`) of the title and body, the labels other than `q:*` / `why:*` / `wait:*` / `running`, the ids of human comments (as for [human replies](#the-dispatch-graph)), the GitHub "blocked by" issues and their states, the agent PRs naming the issue and their states, and `TRIAGE_RUBRIC`; `to-human` keeps it only for a needs-human verdict. A matching fingerprint younger than `retriage.maxSkipDays` (default 14; `0` never skips) leaves the issue in `q:human` with no worker and no label moves. A marker without one (another route to `q:human`, or written before fingerprints) is re-triaged and gains one. Bump `TRIAGE_RUBRIC` with any change to how triage judges an issue, so everything is looked at again. The log line reads `re-triage: k of n changed; m back to q:intake, s unchanged skipped`. Deferred rechecks are not gated: a defer waits on something outside the issue (a CD run, a release), which the fingerprint cannot see. The reaper runs first, so an issue whose PR it adopted is not re-triaged.
209
210
 
210
211
  ## Worktree GC
211
212
 
@@ -470,8 +471,8 @@ flowchart TD
470
471
  | `blocked` | step | `q:intake` | no |
471
472
  | `close-obsolete` | step | none | no |
472
473
 
473
- - **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).
474
- - **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.
474
+ - **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?, ask? }` (`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). `ask` (`src/ask.mjs`), read only on `needs-human`: `{ kind: 'decide' | 'verify' | 'chore' | 'approve', question, options?: { label, detail }[], recommendation?, interactive }`, `options` (two or more) required for `decide`. An invalid `ask` is dropped with a note in the reason, never failing the verdict, so the issue still lands in `q:human`. The prompt asks for `blocked`, not `needs-human`, when the issue waits on another open issue that is itself a human chore or check.
475
+ - **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` (plus `ask:<kind>`, and `ask:session` when `interactive`), the reason as the state comment's last failure; the marker keeps the `ask`, and the state comment renders it under the status line (question, numbered options with their detail, recommendation, how to answer). `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.
475
476
  - **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).
476
477
  - **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.
477
478
  - **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`.
@@ -575,7 +576,7 @@ flowchart TD
575
576
  | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
576
577
  | `many-queues` | More than one `q:*` label. |
577
578
  | `running-unqueued` | `running` outside `q:task` / `q:intake` (not another host's lease). |
578
- | `why-outside-human` | A `why:*` label without `q:human`. |
579
+ | `why-outside-human` | A `why:*` or `ask:*` label without `q:human`. |
579
580
  | `wait-outside-intake` | A `wait:*` label without `q:intake`. |
580
581
  | `closed-labelled` | A closed issue still carrying cambium labels (`q:promote` aside). |
581
582
  | `merged-open` | Its agent PR merged, the issue open in no queue. |
@@ -599,7 +600,7 @@ A label change counts after `rescue.graceMinutes` (default 30) since the issue's
599
600
  }
600
601
  ```
601
602
 
602
- **Actions**, in order: `clear-labels` (cambium labels only), `close-pr` (an open agent PR), then at most one move, last: `requeue` (to `q:task` or `q:intake` at its graph's entry, attempt 1, history kept, outcome `rescued`), `adopt-pr` (the task graph's `submit`, as the reaper adopts), `close-issue` (`completed` or `not_planned`), or `to-human` (`why:rescue`). `"stuck": false` takes no actions. Before anything is touched, the verdict is checked against the item (`checkPlan`); a missing, invalid or unworkable verdict, or a worker killed at its cap, sends the item to `q:human` + `why:rescue` with the error. When the worker exits the item is checked again: if none of the symptoms it started from still holds (someone fixed it meanwhile), the verdict is dropped.
603
+ **Actions**, in order: `clear-labels` (cambium labels only), `close-pr` (an open agent PR), then at most one move, last: `requeue` (to `q:task` or `q:intake` at its graph's entry, attempt 1, history kept, outcome `rescued`), `adopt-pr` (the task graph's `submit`, as the reaper adopts), `close-issue` (`completed` or `not_planned`), or `to-human` (`why:rescue`; an optional `ask`, triage's shape, adds its `ask:*` labels and is rendered in the state comment). `"stuck": false` takes no actions. Before anything is touched, the verdict is checked against the item (`checkPlan`); a missing, invalid or unworkable verdict, or a worker killed at its cap, sends the item to `q:human` + `why:rescue` with the error. When the worker exits the item is checked again: if none of the symptoms it started from still holds (someone fixed it meanwhile), the verdict is dropped.
603
604
 
604
605
  **Root causes.** Each becomes a ticket in its `repo`: the item's own, or `rescue.causeRepo` (e.g. the repo that holds cambium itself). A ticket is labelled `q:intake` and `rescue`, so [triage](#the-dispatch-graph) takes it from there; its body is the worker's, then how the item got stuck, then a hidden `<!-- cambium:rescue-cause <fingerprint> -->`. When an open issue in that repo already carries the fingerprint, cambium comments there that the cause struck again instead of filing it twice (a repo cambium does not read is de-duplicated by what this host filed).
605
606
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oakgreencc/cambium",
3
- "version": "0.0.42",
3
+ "version": "0.0.44",
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/ask.mjs ADDED
@@ -0,0 +1,90 @@
1
+ // @ts-check
2
+ /**
3
+ * A typed ask: what a person in the Human Queue is asked to do, so `q:human` is not one undifferentiated bucket.
4
+ * Triage (phases/dispatch.mjs `TriageResult`) and rescue's `to-human` action (phases/rescue.mjs) may carry one.
5
+ * cambium projects it as `ask:<kind>` labels next to `why:*` ({@link askLabels}), and renders it in the state
6
+ * comment ({@link renderAsk}) so the person can answer with one comment. The labels leave with `q:human`
7
+ * (labels.mjs `move`).
8
+ *
9
+ * - `decide`: a choice only a person can make; `options` lists the choices (two or more).
10
+ * - `verify`: a check only a person can make (a physical device, an account a machine cannot reach).
11
+ * - `chore`: offline work (a store listing, paperwork, a console setting); a checklist, not a session.
12
+ * - `approve`: a yes or no on something already written.
13
+ * `interactive`: whether a live session with the code would help answer it.
14
+ */
15
+ import { z } from 'zod'
16
+
17
+ export const ASK_KINDS = /** @type {const} */ (['decide', 'verify', 'chore', 'approve'])
18
+ /** Marks an ask whose answer a live session with the code would help (`interactive`). */
19
+ export const ASK_SESSION = 'ask:session'
20
+
21
+ const text = z.string().trim().min(1)
22
+
23
+ export const Ask = z
24
+ .object({
25
+ kind: z.enum(ASK_KINDS),
26
+ question: text,
27
+ options: z
28
+ .array(z.object({ label: text, detail: text }))
29
+ .min(1)
30
+ .optional(),
31
+ recommendation: text.optional(),
32
+ interactive: z.boolean(),
33
+ })
34
+ .refine((a) => a.kind !== 'decide' || (a.options?.length ?? 0) >= 2, {
35
+ message: 'a decide ask needs two or more options',
36
+ path: ['options'],
37
+ })
38
+
39
+ /** @typedef {z.infer<typeof Ask>} AskT */
40
+
41
+ /**
42
+ * An ask as a verdict field: a valid one is kept, an invalid one is dropped (undefined) without failing the verdict
43
+ * around it, so an issue that needs a human still gets to one.
44
+ */
45
+ export const LenientAsk = Ask.optional().catch(undefined)
46
+
47
+ /**
48
+ * Why `raw` is not a valid ask, or null when it is (or is absent).
49
+ * @param {unknown} raw @returns {string | null}
50
+ */
51
+ export function askError(raw) {
52
+ if (raw === undefined) return null
53
+ const r = Ask.safeParse(raw)
54
+ return r.success
55
+ ? null
56
+ : r.error.issues.map((i) => (i.path.length ? `${i.path.join('.')}: ${i.message}` : i.message)).join('; ')
57
+ }
58
+
59
+ /** The labels an ask adds beside `q:human`. @param {AskT | null | undefined} ask @returns {string[]} */
60
+ export const askLabels = (ask) => (ask ? [`ask:${ask.kind}`, ...(ask.interactive ? [ASK_SESSION] : [])] : [])
61
+
62
+ const HEAD = /** @type {const} */ ({
63
+ decide: 'Decide',
64
+ verify: 'Verify',
65
+ chore: 'Offline chore',
66
+ approve: 'Approve',
67
+ })
68
+
69
+ /**
70
+ * The ask as markdown for the state comment: the question, the options, the recommendation, and how to answer.
71
+ * @param {AskT} ask @returns {string[]} lines
72
+ */
73
+ export function renderAsk(ask) {
74
+ const one = (/** @type {string} */ s) => s.replace(/\n+/g, ' ')
75
+ return [
76
+ `**${HEAD[ask.kind]}:** ${one(ask.question)}`,
77
+ ...(ask.options?.length
78
+ ? ['', ...ask.options.map((o, i) => `${i + 1}. **${one(o.label)}**: ${one(o.detail)}`)]
79
+ : []),
80
+ ...(ask.recommendation ? ['', `**Recommendation:** ${one(ask.recommendation)}`] : []),
81
+ '',
82
+ `_${
83
+ ask.kind === 'decide' && ask.options?.length
84
+ ? 'Answer with one comment naming your choice'
85
+ : ask.kind === 'approve'
86
+ ? 'Answer with one comment: yes, or what to change'
87
+ : 'Comment when it is done, with anything the work needs'
88
+ }; cambium triages the issue again on your reply.${ask.interactive ? ' A live session with the code would help here.' : ''}_`,
89
+ ]
90
+ }
package/src/config.mjs CHANGED
@@ -41,7 +41,7 @@ import { join, resolve } from 'node:path'
41
41
  * priorityLabels: string[],
42
42
  * release: { enabled: boolean, time: string },
43
43
  * reaper: { everyMinutes: number, staleMinutes: number, orphanDays: number },
44
- * retriage: { enabled: boolean, time: string },
44
+ * retriage: { enabled: boolean, time: string, maxSkipDays: number },
45
45
  * rescue: RescueConfig,
46
46
  * paths: { home: string, db: string, heartbeat: string, logs: string },
47
47
  * logs: { keepPerIssue: number, daemonMaxBytes: number },
@@ -96,7 +96,7 @@ export function defaults(home = DEFAULT_HOME) {
96
96
  priorityLabels: ['priority:critical', 'priority:high', 'priority:medium', 'priority:low'],
97
97
  release: { enabled: false, time: '06:00' },
98
98
  reaper: { everyMinutes: 60, staleMinutes: 30, orphanDays: 3 },
99
- retriage: { enabled: false, time: '05:00' },
99
+ retriage: { enabled: false, time: '05:00', maxSkipDays: 14 },
100
100
  rescue: { everyMinutes: 60, staleHours: 12, graceMinutes: 30, cooldownHours: 24, maxRescues: 2, causeRepo: null },
101
101
  paths: {
102
102
  home,
@@ -140,6 +140,8 @@ export function resolveConfig(raw = {}) {
140
140
  for (const k of /** @type {const} */ (['home', 'db', 'heartbeat', 'logs'])) config.paths[k] = untilde(config.paths[k])
141
141
  if (!/^\d{2}:\d{2}$/.test(config.release.time)) throw new Error(`config: release.time must be HH:MM`)
142
142
  if (!/^\d{2}:\d{2}$/.test(config.retriage.time)) throw new Error(`config: retriage.time must be HH:MM`)
143
+ if (typeof config.retriage.maxSkipDays !== 'number' || !(config.retriage.maxSkipDays >= 0))
144
+ throw new Error(`config: retriage.maxSkipDays must be a number of days ≥ 0`)
143
145
  config.repos = (config.repos ?? []).map((r) => {
144
146
  if (!r?.slug || !/^[^/\s]+\/[^/\s]+$/.test(r.slug))
145
147
  throw new Error(`config: repo slug must be owner/name, got ${r?.slug}`)
package/src/github.mjs CHANGED
@@ -18,8 +18,8 @@ import { BASE_FIELDS, baseHealthOf } from './base-health.mjs'
18
18
  * }} Issue
19
19
  * `stateComment.author`: the login that wrote the state comment (cambium's). `comments`: the newest 20, oldest
20
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).
21
+ * @typedef {{ id?: number, author: string | null, bot: boolean, createdAt: string, body: string }} Comment
22
+ * `bot`: GitHub says the author is a `Bot` (an App). `id`: GitHub's database id (triage-inputs.mjs).
23
23
  * @typedef {{ number: number, state: 'OPEN' | 'CLOSED', closedAt: string | null }} Blocker
24
24
  * An issue GitHub records as blocking this one (the "blocked by" relationship).
25
25
  * @typedef {{ name: string, url: string | null, summary: string }} FailingCheck
@@ -117,7 +117,7 @@ fragment I on Issue {
117
117
  labels(first: 30) { nodes { name } }
118
118
  blockedBy(first: 20) { nodes { number state closedAt } }
119
119
  comments(first: 100) { nodes { databaseId body author { login } } }
120
- recent: comments(last: 20) { nodes { createdAt body author { login __typename } } }
120
+ recent: comments(last: 20) { nodes { databaseId createdAt body author { login __typename } } }
121
121
  }
122
122
  fragment P on PullRequest {
123
123
  number url title state createdAt headRefName baseRefName headRefOid reviewDecision
@@ -251,6 +251,7 @@ function toIssue(n, botLogin) {
251
251
  closedAt: b.closedAt ?? null,
252
252
  })),
253
253
  comments: (n.recent?.nodes ?? []).filter(Boolean).map((/** @type {any} */ c) => ({
254
+ ...(c.databaseId ? { id: c.databaseId } : {}),
254
255
  author: c.author?.login ?? null,
255
256
  bot: c.author?.__typename === 'Bot',
256
257
  createdAt: c.createdAt ?? '',
@@ -11,11 +11,13 @@
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 { Ask, askLabels } from '../ask.mjs'
14
15
  import { move, Q, WAIT, WHY } from '../labels.mjs'
15
16
  import { newMarker, withHistory } from '../marker.mjs'
16
17
  import { readTriage, TriageResult, triageComment, triagePrompt } from '../phases/dispatch.mjs'
17
18
  import { humanReplies, quoted, replyContextOf } from '../human-reply.mjs'
18
19
  import { traceWorker } from '../tracing.mjs'
20
+ import { fingerprintOf } from '../triage-inputs.mjs'
19
21
  import { stopOverdue } from '../workers.mjs'
20
22
  import { task } from './task.mjs'
21
23
 
@@ -68,6 +70,7 @@ async function land(ctx, node, marker, { extra = [], status = 'waiting' } = {})
68
70
  await setMarker(ctx, slug, issue, {
69
71
  ...graphMarker(marker),
70
72
  ...(PRE_VERDICT.has(node) ? {} : { reply: null }),
73
+ ...(node === 'to-human' ? {} : { ask: null }),
71
74
  graph: dispatch.name,
72
75
  graphVersion: dispatch.version,
73
76
  phase: 'dispatch',
@@ -164,6 +167,8 @@ const startTriage = declare(
164
167
  await land(ctx, 'triaging', {
165
168
  ...m0,
166
169
  reply,
170
+ // The inputs this worker sees; to-human keeps them on a needs-human verdict, so re-triage can skip it.
171
+ fingerprint: { hash: fingerprintOf(issue, snap, { botLogin: config.graft.botLogin }), at: iso(ctx.tick.now) },
167
172
  deferUntil: null,
168
173
  host: config.host,
169
174
  start: iso(ctx.tick.now),
@@ -388,13 +393,19 @@ const toTask = declare(
388
393
  },
389
394
  )
390
395
 
396
+ const HumanIn = z.object({ ...failure, ask: Ask.optional() })
391
397
  const toHuman = declare(
392
398
  defineNode({
393
399
  name: 'to-human',
394
- input: Failure,
400
+ input: HumanIn,
395
401
  output: Empty,
396
- /** Into the Human Queue with `why:triage` and the reason in the state comment. @param {z.infer<typeof Failure>} what @param {DispatchCtx} ctx */
397
- run: async (what, ctx) => {
402
+ /**
403
+ * Into the Human Queue with `why:triage` and the reason in the state comment; a needs-human verdict's `ask` adds
404
+ * its `ask:*` labels and is rendered there too. A needs-human verdict keeps the triage inputs `start-triage`
405
+ * recorded (re-triage skips the issue while they hold); a spent budget drops them.
406
+ * @param {z.infer<typeof HumanIn>} input @param {DispatchCtx} ctx
407
+ */
408
+ run: async ({ ask, ...what }, ctx) => {
398
409
  const issue = issueOf(ctx)
399
410
  const m = markerOf(issue)
400
411
  await land(
@@ -403,11 +414,13 @@ const toHuman = declare(
403
414
  {
404
415
  ...withHistory(m, { at: iso(ctx.tick.now), attempt: m.attempt, ...what }),
405
416
  lastFailure: what.reason,
417
+ ask: ask ?? null,
418
+ fingerprint: what.outcome === 'needs-human' ? (m.fingerprint ?? null) : null,
406
419
  host: null,
407
420
  start: null,
408
421
  input: null,
409
422
  },
410
- { extra: [WHY.triage] },
423
+ { extra: [WHY.triage, ...askLabels(ask)] },
411
424
  )
412
425
  ctx.log('warn', `→ q:human (${WHY.triage}): ${what.reason.split('\n')[0]}`, {
413
426
  repo: ctx.subject.slug,
@@ -416,7 +429,11 @@ const toHuman = declare(
416
429
  return {}
417
430
  },
418
431
  }),
419
- { queue: Q.human, running: false, about: 'Into q:human with why:triage and the reason in the state comment.' },
432
+ {
433
+ queue: Q.human,
434
+ running: false,
435
+ about: 'Into q:human with why:triage (plus ask:* from a needs-human ask) and the reason in the state comment.',
436
+ },
420
437
  )
421
438
 
422
439
  const DupIn = z.object({ duplicateOf: z.number().int(), reason: z.string(), log: z.string() })
@@ -658,7 +675,17 @@ export const dispatch = defineGraph({
658
675
  ['triaging', 'deferred', defer, (o) => ({ ...pick(o.result, ['reason', 'recheckHours']), log: o.log })],
659
676
  ['triaging', 'blocked', blocked, (o) => ({ blockedBy: o.result.blockedBy, reason: o.result.reason, log: o.log })],
660
677
  ['triaging', 'close-obsolete', obsolete, (o) => ({ reason: o.result.reason, log: o.log })],
661
- ['triaging', 'to-human', needsHuman, (o) => ({ reason: o.result.reason, outcome: 'needs-human', log: o.log })],
678
+ [
679
+ 'triaging',
680
+ 'to-human',
681
+ needsHuman,
682
+ (o) => ({
683
+ reason: o.result.reason,
684
+ outcome: 'needs-human',
685
+ log: o.log,
686
+ ...(o.result.ask ? { ask: o.result.ask } : {}),
687
+ }),
688
+ ],
662
689
  ['triaging', 'to-human'],
663
690
  ['retry-triage', 'start-triage', attemptsLeft, () => ({})],
664
691
  ['retry-triage', 'to-human'],
package/src/graphs/pr.mjs CHANGED
@@ -399,6 +399,7 @@ const toHuman = declare(
399
399
  ...withHistory(m, { ...nodeAt(what), at: iso(ctx.tick.now), attempt: m.attempt, outcome, reason, pr }),
400
400
  phase: 'task',
401
401
  lastFailure: reason,
402
+ ...(m.ask ? { ask: null } : {}),
402
403
  host: null,
403
404
  start: null,
404
405
  input: null,
@@ -13,6 +13,7 @@
13
13
  */
14
14
  import { z } from 'zod'
15
15
  import { advance, defineGraph, defineNode, defineWait, END } from '../graph/index.mjs'
16
+ import { askLabels } from '../ask.mjs'
16
17
  import { iso, key, markerOf, setLabels, setMarker } from '../issue-state.mjs'
17
18
  import { move, Q, RESCUE_LABEL, WHY } from '../labels.mjs'
18
19
  import { newMarker, withHistory } from '../marker.mjs'
@@ -85,10 +86,12 @@ const rescued = (ctx, m, reason) =>
85
86
  withHistory(m, { at: iso(ctx.tick.now), attempt: m.attempt, outcome: 'rescued', reason })
86
87
 
87
88
  /**
88
- * Into the Human Queue with `why:rescue`, resting at this graph's `to-human`.
89
+ * Into the Human Queue with `why:rescue`, resting at this graph's `to-human`; an `ask` adds its `ask:*` labels and is
90
+ * rendered in the state comment.
89
91
  * @param {RescueCtx} ctx @param {Issue} issue @param {string} reason @param {string} outcome
92
+ * @param {import('../ask.mjs').AskT} [ask]
90
93
  */
91
- async function handToHuman(ctx, issue, reason, outcome) {
94
+ async function handToHuman(ctx, issue, reason, outcome, ask) {
92
95
  const m = markerOf(issue)
93
96
  await place(
94
97
  ctx,
@@ -102,11 +105,12 @@ async function handToHuman(ctx, issue, reason, outcome) {
102
105
  status: 'waiting',
103
106
  enteredAt: iso(ctx.tick.now),
104
107
  lastFailure: reason,
108
+ ask: ask ?? null,
105
109
  host: null,
106
110
  start: null,
107
111
  input: null,
108
112
  },
109
- move(issue.labels, Q.human, { extra: [WHY.rescue] }),
113
+ move(issue.labels, Q.human, { extra: [WHY.rescue, ...askLabels(ask)] }),
110
114
  )
111
115
  }
112
116
 
@@ -151,7 +155,7 @@ async function act(ctx, issue, a) {
151
155
  case 'requeue':
152
156
  return requeue(ctx, issue, a.queue, a.reason)
153
157
  case 'to-human':
154
- return handToHuman(ctx, issue, a.reason, 'rescued')
158
+ return handToHuman(ctx, issue, a.reason, 'rescued', a.ask)
155
159
  case 'close-issue': {
156
160
  const m = markerOf(issue)
157
161
  await place(
@@ -431,6 +431,7 @@ const toHuman = declare(
431
431
  {
432
432
  ...withHistory(m, { ...nodeAt(what), at: iso(ctx.tick.now), attempt: m.attempt, outcome, reason, pr, log }),
433
433
  lastFailure: reason,
434
+ ...(m.ask ? { ask: null } : {}),
434
435
  host: null,
435
436
  start: null,
436
437
  input: null,
package/src/labels.mjs CHANGED
@@ -13,6 +13,10 @@ export const RUNNING = 'running'
13
13
  * `blockedBy` issues. Any queue move drops them unless it names one again.
14
14
  */
15
15
  export const WAIT = /** @type {const} */ ({ deferred: 'wait:deferred', blocked: 'wait:blocked' })
16
+ /**
17
+ * Why an issue is in q:human. Beside it, an `ask:*` label (ask.mjs) may say what the person is asked to do. Both
18
+ * leave with `q:human`; a new hand-off into it replaces the ask.
19
+ */
16
20
  export const WHY = /** @type {const} */ ({
17
21
  budget: 'why:budget',
18
22
  reject: 'why:reject',
@@ -33,11 +37,14 @@ export const queueOf = (labels) => labels.find((l) => l.startsWith('q:')) ?? nul
33
37
  */
34
38
  export function move(labels, target, { running = false, extra = [] } = {}) {
35
39
  const want = new Set([...(target ? [target] : []), ...extra, ...(running ? [RUNNING] : [])])
40
+ // A hand-off into q:human names its reason (`why:*`); its ask, if any, replaces the one there before.
41
+ const handOff = target === Q.human && extra.some((l) => l.startsWith('why:'))
36
42
  const leaving = (/** @type {string} */ l) =>
37
43
  !want.has(l) &&
38
44
  ((l.startsWith('q:') && l !== target) ||
39
45
  l === RUNNING ||
40
46
  (l.startsWith('why:') && target !== Q.human) ||
47
+ (l.startsWith('ask:') && (target !== Q.human || handOff)) ||
41
48
  l.startsWith('wait:'))
42
49
  return {
43
50
  add: [...want].filter((l) => !labels.includes(l)),
package/src/marker.mjs CHANGED
@@ -49,6 +49,8 @@
49
49
  * deferReason?: string | null,
50
50
  * blockedBy?: number[] | null,
51
51
  * reply?: { since: string, question: string | null } | null,
52
+ * ask?: import('./ask.mjs').AskT | null,
53
+ * fingerprint?: { hash: string, at: string } | null,
52
54
  * }} Marker
53
55
  * `mergeRefusal`: the last `graft pr merge` cambium was refused (PR graph `merge`), and on which head.
54
56
  * `reworks`: how many times the PR graph sent this issue's PR back to a worker.
@@ -57,9 +59,13 @@
57
59
  * GitHub `blockedBy` issues it waits on (no `deferUntil`).
58
60
  * `reply`: while triage is pending or running, what a human reply answers (human-reply.mjs): human comments after
59
61
  * `since` are quoted in the triage prompt as the answer to `question`. Cleared when triage lands a verdict.
62
+ * `ask`: at a `to-human` node, what the person is asked to do (ask.mjs); the comment renders it.
63
+ * `fingerprint`: the triage inputs (triage-inputs.mjs) the last triage saw, taken at `start-triage` and kept by
64
+ * `to-human` only for a needs-human verdict; re-triage skips the issue while they are unchanged.
60
65
  * `triage`: what the dispatch graph's triage added when it handed the issue to `q:task`; the task prompt shows it.
61
66
  * @typedef {{ graph: string, entryNode: string, nodes?: Iterable<string> }} QueueOwner
62
67
  */
68
+ import { renderAsk } from './ask.mjs'
63
69
 
64
70
  const PREFIX = '<!-- cambium:state '
65
71
  const RE = /<!-- cambium:state (.*?) -->/s
@@ -190,6 +196,7 @@ export function renderMarker(input, { maxAttempts } = {}) {
190
196
  ? ` · re-triage once ${marker.blockedBy.map((n) => `#${n}`).join(', ')} close`
191
197
  : ''),
192
198
  ]
199
+ if (marker.ask && marker.node === 'to-human' && marker.status !== 'done') lines.push('', ...renderAsk(marker.ask))
193
200
  if (marker.lastFailure)
194
201
  lines.push(
195
202
  '',
@@ -5,6 +5,7 @@
5
5
  * stub below and leaves `q:intake` alone.
6
6
  */
7
7
  import { z } from 'zod'
8
+ import { askError, LenientAsk } from '../ask.mjs'
8
9
 
9
10
  /**
10
11
  * @typedef {{ repo: string, intake: import('../github.mjs').Issue[], capacity: number, now: number }} DispatchInput
@@ -28,6 +29,8 @@ export const TriageResult = z
28
29
  reason: z.string().trim().min(1),
29
30
  title: z.string().trim().min(1).optional(),
30
31
  acceptance: z.array(z.string().trim().min(1)).optional(),
32
+ /** For needs-human: what the person is asked to do (ask.mjs). An invalid one is dropped, not fatal. */
33
+ ask: LenientAsk,
31
34
  })
32
35
  .refine((r) => r.verdict !== 'duplicate' || r.duplicateOf !== undefined, {
33
36
  message: 'a duplicate verdict needs duplicateOf',
@@ -116,7 +119,15 @@ export function readTriage(log, issue) {
116
119
  return { ok: false, error: `invalid triage result: duplicateOf: #${issue} cannot duplicate itself` }
117
120
  if (parsed.data.verdict === 'blocked' && parsed.data.blockedBy?.includes(issue))
118
121
  return { ok: false, error: `invalid triage result: blockedBy: #${issue} cannot block itself` }
119
- return { ok: true, result: parsed.data }
122
+ const { ask, ...rest } = parsed.data
123
+ if (rest.verdict !== 'needs-human') return { ok: true, result: rest }
124
+ const bad = askError(/** @type {any} */ (read.json)?.ask)
125
+ if (bad)
126
+ return {
127
+ ok: true,
128
+ result: { ...rest, reason: `${rest.reason}\n\n(triage's ask was invalid and was dropped: ${bad})` },
129
+ }
130
+ return { ok: true, result: ask ? { ...rest, ask } : rest }
120
131
  }
121
132
 
122
133
  /**
@@ -132,6 +143,7 @@ export function readTriage(log, issue) {
132
143
  * }} input
133
144
  * `blocked`: an earlier triage parked it on these issues, all closed now. `replied`: a human commented since the
134
145
  * issue last waited; `question` is what it waited on (the needs-human, defer or blocked reason).
146
+ * A change to how triage judges an issue bumps `TRIAGE_RUBRIC` (triage-inputs.mjs), so re-triage looks again.
135
147
  */
136
148
  export function triagePrompt({
137
149
  repo,
@@ -155,11 +167,15 @@ Your one job: decide what happens to GitHub issue #${issue.number} (below), whic
155
167
 
156
168
  Verdicts:
157
169
  - actionable: a worker could do it unattended from what is written (plus what you add), and would know when it is done. It goes to the task queue. When the issue lacks a clear task or checkable acceptance criteria, give \`title\` (an imperative task title) and \`acceptance\` (checks a reviewer can verify; CI green is always required, so do not list only that). cambium posts them on the issue and hands them to the task worker.
158
- - 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.
170
+ - 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. Fill \`ask\` so the person can answer with one comment:
171
+ - \`kind\`: \`decide\` (a choice only a person can make), \`verify\` (a check only a person can make: a physical device, an account no machine can reach), \`chore\` (offline work: a store listing, paperwork, a console setting) or \`approve\` (a yes or no on something already written).
172
+ - \`question\`: the one question, answerable in a comment. For \`decide\`, \`options\` (two or more, each a \`label\` and the tradeoff in \`detail\`) and, where you have one, \`recommendation\`.
173
+ - \`interactive\`: true only when a live session with the code would help the person answer (a design choice to explore); false for chores, checks and plain choices.
174
+ If the issue waits on another open issue that is itself a human chore or check, it is blocked by that issue, not needs-human: do not ask again what that issue already asks.
159
175
  - 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.
160
176
  - 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).
161
177
  - 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.
162
- - 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.
178
+ - blocked: it cannot start until other issues in ${repo} are done (including an open issue waiting on a person for a chore or check). \`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.
163
179
 
164
180
  How to look:
165
181
  - Read the code here (Read, Glob, Grep) to judge what the change touches and whether it already exists.
@@ -171,9 +187,9 @@ How to look:
171
187
 
172
188
  End your final message with exactly one fenced JSON block, and nothing after it:
173
189
  \`\`\`json
174
- { "verdict": "actionable" | "needs-human" | "duplicate" | "obsolete" | "defer" | "blocked", "duplicateOf": 123, "blockedBy": [124], "recheckHours": 6, "reason": "…", "title": "…", "acceptance": ["…"] }
190
+ { "verdict": "actionable" | "needs-human" | "duplicate" | "obsolete" | "defer" | "blocked", "duplicateOf": 123, "blockedBy": [124], "recheckHours": 6, "reason": "…", "title": "…", "acceptance": ["…"], "ask": { "kind": "decide" | "verify" | "chore" | "approve", "question": "…", "options": [{ "label": "…", "detail": "…" }], "recommendation": "…", "interactive": false } }
175
191
  \`\`\`
176
- \`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.
192
+ \`duplicateOf\` only for duplicate; \`blockedBy\` only for blocked; \`recheckHours\` only for defer, and optional; \`title\` and \`acceptance\` only for actionable, and optional; \`ask\` only for needs-human (\`options\` only for decide, \`recommendation\` optional). A missing or malformed block sends the issue to a human with the error.
177
193
  ${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` : ''}
178
194
  --- Issue #${issue.number}: ${issue.title} (${issue.url})
179
195
  ${issue.body}
@@ -4,8 +4,8 @@
4
4
  * its typed result and the checks cambium runs on it before acting, and the comments and root-cause tickets it
5
5
  * writes.
6
6
  *
7
- * An item is stuck when its labels break the queue rules (more than one `q:*`, `running` without a queue, `why:*`
8
- * outside `q:human`, `wait:*` outside `q:intake`, cambium labels left on a closed issue), when its agent PR closed
7
+ * An item is stuck when its labels break the queue rules (more than one `q:*`, `running` without a queue, `why:*` or
8
+ * `ask:*` outside `q:human`, `wait:*` outside `q:intake`, cambium labels left on a closed issue), when its agent PR closed
9
9
  * or merged and left it open in no queue, or when it has waited in a queue, or its PR has sat untouched, far longer
10
10
  * than cambium ever takes to move it.
11
11
  */
@@ -14,6 +14,7 @@ import { z } from 'zod'
14
14
  import { branchIssue } from '../github.mjs'
15
15
  import { MIN } from '../issue-state.mjs'
16
16
  import { Q, RUNNING } from '../labels.mjs'
17
+ import { LenientAsk } from '../ask.mjs'
17
18
  import { finalJson, formatZodIssue } from './dispatch.mjs'
18
19
 
19
20
  /**
@@ -28,7 +29,8 @@ import { finalJson, formatZodIssue } from './dispatch.mjs'
28
29
  const HOUR = 60 * MIN
29
30
 
30
31
  /** The labels cambium owns, which only cambium moves. @param {string} l */
31
- export const cambiumLabel = (l) => l.startsWith('q:') || l === RUNNING || l.startsWith('why:') || l.startsWith('wait:')
32
+ export const cambiumLabel = (l) =>
33
+ l.startsWith('q:') || l === RUNNING || l.startsWith('why:') || l.startsWith('ask:') || l.startsWith('wait:')
32
34
 
33
35
  /** The issue an agent PR is for: the first one it closes that the snapshot has, else the one its branch names. @param {PullRequest} pr */
34
36
  const issueOfPr = (pr) => pr.closes[0] ?? branchIssue(pr.branch)
@@ -94,7 +96,7 @@ export function findStuck(snap, o) {
94
96
  code: 'running-unqueued',
95
97
  detail: `labelled \`${RUNNING}\` ${queues.length ? `in ${queues.join(', ')}` : 'in no queue'}`,
96
98
  })
97
- const why = labels.filter((l) => l.startsWith('why:'))
99
+ const why = labels.filter((l) => l.startsWith('why:') || l.startsWith('ask:'))
98
100
  if (why.length && !labels.includes(Q.human))
99
101
  add(n, { code: 'why-outside-human', detail: `${why.join(', ')} without ${Q.human}` })
100
102
  const wait = labels.filter((l) => l.startsWith('wait:'))
@@ -223,7 +225,7 @@ const text = z.string().trim().min(1)
223
225
 
224
226
  export const RescueAction = z.discriminatedUnion('do', [
225
227
  z.object({ do: z.literal('requeue'), queue: z.enum(['task', 'intake']), reason: text }),
226
- z.object({ do: z.literal('to-human'), reason: text }),
228
+ z.object({ do: z.literal('to-human'), reason: text, ask: LenientAsk }),
227
229
  z.object({
228
230
  do: z.literal('close-issue'),
229
231
  as: z.enum(['completed', 'not_planned']).default('completed'),
@@ -381,7 +383,7 @@ ${symptomList(stuck.symptoms)}${previous ? `\n\ncambium has rescued this item ${
381
383
  How cambium's queues work (labels are the queue; only cambium moves them):
382
384
  - Exactly one queue label: \`${Q.intake}\` (triage decides what it is), \`${Q.task}\` (a task worker turns it into a PR), \`${Q.human}\` (waits for a person, with a \`why:*\` label saying why), \`${Q.promote}\` (merged, awaiting the release promotion).
383
385
  - \`${RUNNING}\`: a worker holds a lease on it right now. Without a live worker it is a lost lease.
384
- - \`why:*\` only with \`${Q.human}\`; \`wait:deferred\` / \`wait:blocked\` only with \`${Q.intake}\` (triage parked it).
386
+ - \`why:*\` and \`ask:*\` (what the person is asked to do) only with \`${Q.human}\`; \`wait:deferred\` / \`wait:blocked\` only with \`${Q.intake}\` (triage parked it).
385
387
  - Once a task worker publishes its PR, the issue leaves every queue and the PR graph owns it: it merges a green PR (or waits for a merge queue or a human), reworks a red or conflicting one back through \`${Q.task}\`, and closes the issue when the PR merges.
386
388
  - cambium's state comment on the issue holds a hidden JSON marker: the graph and node the issue rests at, and its history. It is below.
387
389
 
@@ -392,13 +394,13 @@ How to look:
392
394
  - Never \`gh\`. Be quick: a verdict with evidence, not an essay.
393
395
 
394
396
  Actions, in order (cambium checks them before it does anything; an invalid list sends the issue to a human):
395
- - \`{ "do": "clear-labels", "labels": ["…"], "reason": "…" }\`: remove stray cambium labels (\`q:*\`, \`${RUNNING}\`, \`why:*\`, \`wait:*\`) and nothing else.
397
+ - \`{ "do": "clear-labels", "labels": ["…"], "reason": "…" }\`: remove stray cambium labels (\`q:*\`, \`${RUNNING}\`, \`why:*\`, \`ask:*\`, \`wait:*\`) and nothing else.
396
398
  - \`{ "do": "close-pr", "pr": 123, "reason": "…" }\`: close an open agent PR that is superseded or abandoned.
397
399
  - At most one of these, last:
398
400
  - \`{ "do": "requeue", "queue": "task" | "intake", "reason": "…" }\`: back to a queue at its start, attempt 1: \`task\` when the work is still clear, \`intake\` when it needs triage again.
399
401
  - \`{ "do": "adopt-pr", "pr": 123 }\`: hand an open agent PR that holds the work to the PR graph.
400
402
  - \`{ "do": "close-issue", "as": "completed" | "not_planned", "reason": "…" }\`: the work is done (say where) or no longer applies.
401
- - \`{ "do": "to-human", "reason": "…" }\`: only a person can unstick it; \`reason\` says exactly what they must decide or do.
403
+ - \`{ "do": "to-human", "reason": "…", "ask": { … } }\`: only a person can unstick it; \`reason\` says exactly what they must decide or do. Where you can, add \`ask\` so they can answer with one comment: \`{ "kind": "decide" | "verify" | "chore" | "approve", "question": "…", "options": [{ "label": "…", "detail": "…" }], "recommendation": "…", "interactive": false }\` (\`options\`, two or more, only for decide; \`interactive\` true only when a live session with the code would help).
402
404
  If it is not actually stuck (cambium's check was wrong), say so with \`"stuck": false\` and no actions; a wrong check is itself a root cause worth a ticket.
403
405
 
404
406
  Root causes: only ones that need a change and that you can name with evidence (a cambium bug, a missing guard, a config gap, a process that keeps mislabelling). A one-off human relabel needs none. Each ticket's \`body\` is a task a worker could do unattended: the evidence, the change, and acceptance checks. \`fingerprint\` names the cause in a few kebab-case words, the same every time it recurs (e.g. \`sweep-skips-foreign-host-lease\`). \`repo\` is where the change belongs, one of: ${repos.join(', ')} (default ${repo}).
@@ -0,0 +1,87 @@
1
+ // @ts-check
2
+ /**
3
+ * Triage inputs: what a triage verdict was drawn from, hashed, so the daily re-triage can skip a `q:human` issue
4
+ * nothing has changed on since triage answered needs-human (upkeep.mjs `retriage`).
5
+ *
6
+ * The fingerprint covers the issue's title and body, its labels (not cambium's own: `q:*`, `why:*`, `wait:*`,
7
+ * `running`), the ids of its human comments (human-reply.mjs: not cambium, not a bot, not a state marker), its
8
+ * GitHub `blockedBy` issues and their states, the agent PRs that name it and their states, and
9
+ * {@link TRIAGE_RUBRIC}. `start-triage` records it on the marker (the inputs the worker saw), and `to-human` keeps
10
+ * it only for a needs-human verdict.
11
+ */
12
+ import { createHash } from 'node:crypto'
13
+ import { branchIssue } from './github.mjs'
14
+ import { parseMarker } from './marker.mjs'
15
+ import { RUNNING } from './labels.mjs'
16
+
17
+ /**
18
+ * @typedef {import('./github.mjs').Issue} Issue
19
+ * @typedef {import('./github.mjs').Snapshot} Snapshot
20
+ * @typedef {{ hash: string, at: string }} Fingerprint
21
+ * `at`: when it was taken, the start of the triage that answered; the backstop counts from it.
22
+ */
23
+
24
+ /**
25
+ * The triage prompt and rubric's version. Bump it with any change to how triage judges an issue
26
+ * (phases/dispatch.mjs `triagePrompt`): every fingerprint stops matching, so the next re-triage looks at every
27
+ * `q:human` issue again.
28
+ */
29
+ export const TRIAGE_RUBRIC = 1
30
+
31
+ const DAY = 24 * 60 * 60_000
32
+
33
+ /** cambium's own labels: moving an issue between queues is not a change triage should see. @param {string} l */
34
+ const cambiumLabel = (l) => l === RUNNING || /^(q|why|wait):/.test(l)
35
+
36
+ /**
37
+ * The inputs, in a stable order. @param {Issue} issue @param {Snapshot | undefined} snap
38
+ * @param {{ botLogin?: string | null, rubric?: number }} [o]
39
+ */
40
+ export function triageInputs(issue, snap, { botLogin = null, rubric = TRIAGE_RUBRIC } = {}) {
41
+ const self = new Set([botLogin, issue.stateComment?.author].filter(Boolean))
42
+ return {
43
+ rubric,
44
+ title: issue.title,
45
+ body: issue.body,
46
+ labels: issue.labels.filter((l) => !cambiumLabel(l)).sort(),
47
+ comments: (issue.comments ?? [])
48
+ .filter((c) => !!c.author && !c.bot && !self.has(c.author) && !parseMarker(c.body))
49
+ .map((c) => String(c.id ?? `${c.author}@${c.createdAt}`))
50
+ .sort(),
51
+ blockedBy: (issue.blockedBy ?? []).map((b) => `${b.number}:${b.state}`).sort(),
52
+ // Merged PRs come from the snapshot's newest 30; one that ages out of it changes the hash once.
53
+ prs: (snap?.prs ?? [])
54
+ .filter((p) => p.closes.includes(issue.number) || branchIssue(p.branch) === issue.number)
55
+ .map((p) => `${p.number}:${p.state}`)
56
+ .sort(),
57
+ }
58
+ }
59
+
60
+ /**
61
+ * @param {Issue} issue @param {Snapshot | undefined} snap @param {{ botLogin?: string | null, rubric?: number }} [o]
62
+ * @returns {string}
63
+ */
64
+ export const fingerprintOf = (issue, snap, o) =>
65
+ createHash('sha256')
66
+ .update(JSON.stringify(triageInputs(issue, snap, o)))
67
+ .digest('hex')
68
+ .slice(0, 16)
69
+
70
+ /**
71
+ * Whether re-triage sends a `q:human` issue back to triage. Pure.
72
+ * - `unchanged`: the marker's fingerprint matches and is younger than `maxSkipDays`: stays.
73
+ * - `changed`, `no fingerprint` (an issue triage never answered needs-human on, or one from before fingerprints),
74
+ * `backstop` (unchanged for `maxSkipDays`, so a change the fingerprint cannot see is seen eventually): goes.
75
+ *
76
+ * @param {Issue} issue @param {Snapshot | undefined} snap
77
+ * @param {{ now: number, maxSkipDays: number, botLogin?: string | null, rubric?: number }} o
78
+ * @returns {{ retriage: boolean, why: 'unchanged' | 'changed' | 'no fingerprint' | 'backstop' }}
79
+ */
80
+ export function retriageDecision(issue, snap, { now, maxSkipDays, botLogin, rubric }) {
81
+ const fp = issue.stateComment?.marker?.fingerprint
82
+ const at = fp ? Date.parse(fp.at) : NaN
83
+ if (!fp?.hash || !Number.isFinite(at)) return { retriage: true, why: 'no fingerprint' }
84
+ if (fp.hash !== fingerprintOf(issue, snap, { botLogin, rubric })) return { retriage: true, why: 'changed' }
85
+ if (now - at >= maxSkipDays * DAY) return { retriage: true, why: 'backstop' }
86
+ return { retriage: false, why: 'unchanged' }
87
+ }
package/src/upkeep.mjs CHANGED
@@ -11,7 +11,8 @@
11
11
  * - **Re-triage** (daily at `retriage.time` when `retriage.enabled`): every `q:human` issue goes back to `q:intake`,
12
12
  * so triage looks again under its current rubric: done since (obsolete), now checkable (defer), or now a task.
13
13
  * Not `why:approve` (a merge only a human may make: a re-triage would start a duplicate Task) and not one holding
14
- * `running`.
14
+ * `running`. Not one whose triage inputs (triage-inputs.mjs) are unchanged since triage answered needs-human,
15
+ * unless that was `retriage.maxSkipDays` (default 14) or more ago: it stays, no worker, no label moves.
15
16
  * - **Rescue** (rescue-engine.mjs, while `phases.rescue.cap > 0`): rescue workers every tick, and every
16
17
  * `rescue.everyMinutes` a sweep for stuck items, each diagnosed and unstuck by the rescue graph.
17
18
  */
@@ -22,6 +23,7 @@ import { move, Q, RUNNING, WHY } from './labels.mjs'
22
23
  import { releaseDue } from './phases/release.mjs'
23
24
  import { rescueStep } from './rescue-engine.mjs'
24
25
  import { each } from './tick.mjs'
26
+ import { retriageDecision } from './triage-inputs.mjs'
25
27
 
26
28
  /**
27
29
  * @typedef {import('./tick.mjs').Deps} Deps
@@ -119,7 +121,7 @@ export async function reap(deps, ctx) {
119
121
 
120
122
  /** @param {Deps} deps @param {Ctx} ctx */
121
123
  export async function retriage(deps, ctx) {
122
- const { enabled, time } = deps.config.retriage
124
+ const { enabled, time, maxSkipDays } = deps.config.retriage
123
125
  if (!enabled) return
124
126
  const last = deps.store.get('retriage.lastRun')
125
127
  if (!releaseDue(ctx.now, last === null ? null : Number(last), time)) return
@@ -133,10 +135,12 @@ export async function retriage(deps, ctx) {
133
135
  !i.labels.includes(RUNNING) &&
134
136
  !ctx.touched.has(key(slug, i.number)),
135
137
  )
138
+ const o = { now: ctx.now, maxSkipDays, botLogin: deps.config.graft.botLogin }
139
+ const changed = human.filter((i) => retriageDecision(i, snap, o).retriage)
136
140
  let moved = 0
137
141
  await each(
138
142
  deps,
139
- human,
143
+ changed,
140
144
  async (issue) => {
141
145
  await setLabels(deps, slug, issue, move(issue.labels, Q.intake))
142
146
  moved++
@@ -144,8 +148,11 @@ export async function retriage(deps, ctx) {
144
148
  (issue) => ({ repo: slug, issue: issue.number }),
145
149
  )
146
150
  if (human.length)
147
- deps.log('info', `re-triage: ${moved} of ${human.length} q:human issues back to q:intake (${iso(ctx.now)})`, {
148
- repo: slug,
149
- })
151
+ deps.log(
152
+ 'info',
153
+ `re-triage: ${changed.length} of ${human.length} changed; ${moved} back to q:intake, ` +
154
+ `${human.length - changed.length} unchanged skipped (${iso(ctx.now)})`,
155
+ { repo: slug },
156
+ )
150
157
  }
151
158
  }