@oakgreencc/cambium 0.0.42 → 0.0.43

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
@@ -129,7 +129,7 @@ One JSON file. Everything but `repos` is optional; these are the defaults:
129
129
  "priorityLabels": ["priority:critical", "priority:high", "priority:medium", "priority:low"],
130
130
  "release": { "enabled": false, "time": "06:00" },
131
131
  "reaper": { "everyMinutes": 60, "staleMinutes": 30, "orphanDays": 3 },
132
- "retriage": { "enabled": false, "time": "05:00" },
132
+ "retriage": { "enabled": false, "time": "05:00", "maxSkipDays": 14 },
133
133
  "rescue": {
134
134
  "everyMinutes": 60,
135
135
  "staleHours": 12,
@@ -205,7 +205,7 @@ Two clocks in the graph engine's `upkeep` step, after Watch (`src/upkeep.mjs`),
205
205
  | No issue (none named, or not readable) | Close the PR after `reaper.orphanDays` (default 3) untouched. The branch stays. |
206
206
  | A live worker on the issue, or the issue already tracks this PR | Leave it. |
207
207
 
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.
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`. 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
209
 
210
210
  ## Worktree GC
211
211
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oakgreencc/cambium",
3
- "version": "0.0.42",
3
+ "version": "0.0.43",
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/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 ?? '',
@@ -16,6 +16,7 @@ import { newMarker, withHistory } from '../marker.mjs'
16
16
  import { readTriage, TriageResult, triageComment, triagePrompt } from '../phases/dispatch.mjs'
17
17
  import { humanReplies, quoted, replyContextOf } from '../human-reply.mjs'
18
18
  import { traceWorker } from '../tracing.mjs'
19
+ import { fingerprintOf } from '../triage-inputs.mjs'
19
20
  import { stopOverdue } from '../workers.mjs'
20
21
  import { task } from './task.mjs'
21
22
 
@@ -164,6 +165,8 @@ const startTriage = declare(
164
165
  await land(ctx, 'triaging', {
165
166
  ...m0,
166
167
  reply,
168
+ // The inputs this worker sees; to-human keeps them on a needs-human verdict, so re-triage can skip it.
169
+ fingerprint: { hash: fingerprintOf(issue, snap, { botLogin: config.graft.botLogin }), at: iso(ctx.tick.now) },
167
170
  deferUntil: null,
168
171
  host: config.host,
169
172
  start: iso(ctx.tick.now),
@@ -393,7 +396,11 @@ const toHuman = declare(
393
396
  name: 'to-human',
394
397
  input: Failure,
395
398
  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 */
399
+ /**
400
+ * Into the Human Queue with `why:triage` and the reason in the state comment. A needs-human verdict keeps the
401
+ * triage inputs `start-triage` recorded (re-triage skips the issue while they hold); a spent budget drops them.
402
+ * @param {z.infer<typeof Failure>} what @param {DispatchCtx} ctx
403
+ */
397
404
  run: async (what, ctx) => {
398
405
  const issue = issueOf(ctx)
399
406
  const m = markerOf(issue)
@@ -403,6 +410,7 @@ const toHuman = declare(
403
410
  {
404
411
  ...withHistory(m, { at: iso(ctx.tick.now), attempt: m.attempt, ...what }),
405
412
  lastFailure: what.reason,
413
+ fingerprint: what.outcome === 'needs-human' ? (m.fingerprint ?? null) : null,
406
414
  host: null,
407
415
  start: null,
408
416
  input: null,
package/src/marker.mjs CHANGED
@@ -49,6 +49,7 @@
49
49
  * deferReason?: string | null,
50
50
  * blockedBy?: number[] | null,
51
51
  * reply?: { since: string, question: string | null } | null,
52
+ * fingerprint?: { hash: string, at: string } | null,
52
53
  * }} Marker
53
54
  * `mergeRefusal`: the last `graft pr merge` cambium was refused (PR graph `merge`), and on which head.
54
55
  * `reworks`: how many times the PR graph sent this issue's PR back to a worker.
@@ -57,6 +58,8 @@
57
58
  * GitHub `blockedBy` issues it waits on (no `deferUntil`).
58
59
  * `reply`: while triage is pending or running, what a human reply answers (human-reply.mjs): human comments after
59
60
  * `since` are quoted in the triage prompt as the answer to `question`. Cleared when triage lands a verdict.
61
+ * `fingerprint`: the triage inputs (triage-inputs.mjs) the last triage saw, taken at `start-triage` and kept by
62
+ * `to-human` only for a needs-human verdict; re-triage skips the issue while they are unchanged.
60
63
  * `triage`: what the dispatch graph's triage added when it handed the issue to `q:task`; the task prompt shows it.
61
64
  * @typedef {{ graph: string, entryNode: string, nodes?: Iterable<string> }} QueueOwner
62
65
  */
@@ -132,6 +132,7 @@ export function readTriage(log, issue) {
132
132
  * }} input
133
133
  * `blocked`: an earlier triage parked it on these issues, all closed now. `replied`: a human commented since the
134
134
  * issue last waited; `question` is what it waited on (the needs-human, defer or blocked reason).
135
+ * A change to how triage judges an issue bumps `TRIAGE_RUBRIC` (triage-inputs.mjs), so re-triage looks again.
135
136
  */
136
137
  export function triagePrompt({
137
138
  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
  }