ticket-runner 0.6.0 → 0.6.2

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.
@@ -0,0 +1,227 @@
1
+ import { spawnSync } from "node:child_process";
2
+ import { readFileSync, readdirSync } from "node:fs";
3
+
4
+ /**
5
+ * Killing a command together with everything it started.
6
+ *
7
+ * The command's own process group would not do: a Stage shares the Run's
8
+ * process group (ADR-0006), so that group is the Run itself, and Claude Code
9
+ * starts each Bash tool command in a session of its own, so the test suite a
10
+ * Stage runs is in no group the Stage is in. What is killed instead is the
11
+ * command, every process descended from it, and every process group one of
12
+ * them leads.
13
+ *
14
+ * A process whose parent has exited is no longer descended from anything the
15
+ * command started: the shell that ran `cmd &` in a Bash call exits, and `cmd`
16
+ * lives on under init in a group of its own. A command given a mark carries an
17
+ * environment variable whose value nothing else on the Host shares, and every
18
+ * process it starts inherits it, so the kill also takes every process that
19
+ * still carries that value, whoever its parent is by then. The environment is
20
+ * read from `/proc/<pid>/environ` where there is a `/proc`, as on Linux, and
21
+ * from `ps -wwE` where there is not, as on macOS. A process whose environment
22
+ * cannot be read, or that cleared it, is reached by the walk alone.
23
+ */
24
+
25
+ /** How often a kill looks for what is still alive while the grace runs. */
26
+ const POLL_MS = 50;
27
+
28
+ /** One line of the process table, as far as a kill needs it. */
29
+ interface ProcessRow {
30
+ pid: number;
31
+ ppid: number;
32
+ pgid: number;
33
+ }
34
+
35
+ /** A variable only one command and what it starts carry, at this value. */
36
+ export interface Mark {
37
+ name: string;
38
+ value: string;
39
+ }
40
+
41
+ /**
42
+ * Which processes on the Host carry the mark. Throws, or answers nothing, when
43
+ * no environment can be read; a test hands in its own.
44
+ */
45
+ export type FindMarked = (mark: Mark) => number[];
46
+
47
+ export interface KillOptions {
48
+ /** The mark the command was started with, when it was given one. */
49
+ mark?: Mark;
50
+ findMarked?: FindMarked;
51
+ }
52
+
53
+ /** A command's processes as one kill signals them. */
54
+ interface Tree {
55
+ pids: Set<number>;
56
+ /** Process groups led by one of the pids, never the Run's own. */
57
+ groups: Set<number>;
58
+ }
59
+
60
+ /**
61
+ * SIGTERM to the command and everything it started, then SIGKILL to whatever
62
+ * is still there once `graceMs` is over. Settles when nothing it signalled is
63
+ * left, or once the SIGKILL is sent.
64
+ */
65
+ export async function killTree(
66
+ root: number,
67
+ graceMs: number,
68
+ options: KillOptions = {},
69
+ ): Promise<void> {
70
+ const marked = () => markedPids(options);
71
+ const tree = treeOf([root, ...marked()]);
72
+ signal(tree, "SIGTERM");
73
+
74
+ const deadline = Date.now() + graceMs;
75
+ while (Date.now() < deadline) {
76
+ if (!anyAlive(tree)) {
77
+ // What it signalled is gone, but one of them may have started another
78
+ // as it went: that one still carries the mark.
79
+ const late = treeOf(marked().filter((pid) => alive(pid)));
80
+ if (late.pids.size === 0) return;
81
+ signal(late, "SIGTERM");
82
+ for (const pid of late.pids) tree.pids.add(pid);
83
+ for (const group of late.groups) tree.groups.add(group);
84
+ }
85
+ await new Promise((resolve) => setTimeout(resolve, POLL_MS));
86
+ }
87
+
88
+ // Walked and looked for again from what survived: a process can start
89
+ // another in the grace.
90
+ const stragglers = treeOf([...tree.pids].filter((pid) => alive(pid)).concat(marked()));
91
+ for (const group of tree.groups) stragglers.groups.add(group);
92
+ signal(stragglers, "SIGKILL");
93
+ }
94
+
95
+ /**
96
+ * The roots, their descendants and the groups those lead. Without `ps` to ask,
97
+ * it is the roots alone.
98
+ */
99
+ function treeOf(roots: number[]): Tree {
100
+ const table = processTable();
101
+ if (table === undefined) return { pids: new Set(roots), groups: new Set() };
102
+
103
+ const children = new Map<number, number[]>();
104
+ for (const row of table) {
105
+ children.set(row.ppid, [...(children.get(row.ppid) ?? []), row.pid]);
106
+ }
107
+ const pids = new Set<number>();
108
+ const queue = [...roots];
109
+ for (let pid = queue.shift(); pid !== undefined; pid = queue.shift()) {
110
+ if (pids.has(pid)) continue;
111
+ pids.add(pid);
112
+ queue.push(...(children.get(pid) ?? []));
113
+ }
114
+
115
+ const own = table.find((row) => row.pid === process.pid)?.pgid;
116
+ const groups = new Set(
117
+ table
118
+ .filter((row) => pids.has(row.pid) && row.pgid === row.pid && row.pgid !== own)
119
+ .map((row) => row.pgid),
120
+ );
121
+ return { pids, groups };
122
+ }
123
+
124
+ /**
125
+ * The processes carrying the mark, never this one. None when there is no mark,
126
+ * or when its read failed: the walk still reaches what it reaches.
127
+ */
128
+ function markedPids({ mark, findMarked = processesMarked }: KillOptions): number[] {
129
+ if (mark === undefined) return [];
130
+ try {
131
+ return findMarked(mark).filter((pid) => pid !== process.pid);
132
+ } catch {
133
+ return [];
134
+ }
135
+ }
136
+
137
+ /** The processes carrying the mark, read from `/proc` or else from `ps`. */
138
+ export function processesMarked(mark: Mark): number[] {
139
+ const entries = procEntries();
140
+ if (entries === undefined) return markedInPs(psWithEnvironment(), mark);
141
+
142
+ const wanted = asEntry(mark);
143
+ return entries.flatMap((pid) => {
144
+ try {
145
+ const environ = readFileSync(`/proc/${pid}/environ`, "utf8");
146
+ return environ.split("\0").includes(wanted) ? [pid] : [];
147
+ } catch {
148
+ // Gone since the listing, or another user's: the walk alone reaches it.
149
+ return [];
150
+ }
151
+ });
152
+ }
153
+
154
+ /** The mark as an environment holds it. */
155
+ function asEntry(mark: Mark): string {
156
+ return `${mark.name}=${mark.value}`;
157
+ }
158
+
159
+ /** The pids under `/proc`, or nothing on a Host without one. */
160
+ function procEntries(): number[] | undefined {
161
+ try {
162
+ return readdirSync("/proc").filter((entry) => /^\d+$/.test(entry)).map(Number);
163
+ } catch {
164
+ return undefined;
165
+ }
166
+ }
167
+
168
+ /**
169
+ * Every process with its environment appended to its command, as BSD `ps`
170
+ * prints it. `-ww` because it cuts its lines when stdout is not a terminal,
171
+ * `-A` because a detached process has no terminal to be listed under.
172
+ */
173
+ function psWithEnvironment(): string {
174
+ const listed = spawnSync("ps", ["-A", "-wwE", "-o", "pid=,command="], { encoding: "utf8" });
175
+ if (listed.error !== undefined) throw listed.error;
176
+ if (listed.status !== 0) throw new Error(`ps exited ${listed.status}`);
177
+ return listed.stdout;
178
+ }
179
+
180
+ /**
181
+ * The processes in `ps -wwE -o pid=,command=` output that carry the mark, as
182
+ * one whitespace-separated `NAME=value` word in their line.
183
+ */
184
+ export function markedInPs(output: string, mark: Mark): number[] {
185
+ const wanted = asEntry(mark);
186
+ return output.split("\n").flatMap((line) => {
187
+ const [pid, ...words] = line.trim().split(/\s+/);
188
+ if (pid === undefined || !/^\d+$/.test(pid)) return [];
189
+ return words.includes(wanted) ? [Number(pid)] : [];
190
+ });
191
+ }
192
+
193
+ /** Every process on the Host, or nothing when `ps` cannot be run. */
194
+ function processTable(): ProcessRow[] | undefined {
195
+ const listed = spawnSync("ps", ["-A", "-o", "pid=,ppid=,pgid="], { encoding: "utf8" });
196
+ if (listed.error !== undefined || listed.status !== 0) return undefined;
197
+ return listed.stdout.split("\n").flatMap((line) => {
198
+ const [pid, ppid, pgid] = line.trim().split(/\s+/).map(Number);
199
+ if (pid === undefined || ppid === undefined || pgid === undefined) return [];
200
+ if (!Number.isInteger(pid) || !Number.isInteger(ppid) || !Number.isInteger(pgid)) return [];
201
+ return [{ pid, ppid, pgid }];
202
+ });
203
+ }
204
+
205
+ function signal(tree: Tree, name: NodeJS.Signals): void {
206
+ for (const group of tree.groups) send(-group, name);
207
+ for (const pid of tree.pids) send(pid, name);
208
+ }
209
+
210
+ function anyAlive(tree: Tree): boolean {
211
+ return [...tree.groups].some((group) => alive(-group)) || [...tree.pids].some(alive);
212
+ }
213
+
214
+ /** A negative id is a process group. */
215
+ function alive(id: number): boolean {
216
+ return send(id, 0);
217
+ }
218
+
219
+ /** Whether the signal reached anything; one already gone is not an error here. */
220
+ function send(id: number, name: NodeJS.Signals | 0): boolean {
221
+ try {
222
+ process.kill(id, name);
223
+ return true;
224
+ } catch {
225
+ return false;
226
+ }
227
+ }
package/src/branch.ts CHANGED
@@ -31,3 +31,11 @@ export function branchName(ticket: number, title: string): string {
31
31
  export function worktreePath(repoRoot: string, ticket: number): string {
32
32
  return join(repoRoot, ".worktrees", `ticket-${ticket}`);
33
33
  }
34
+
35
+ /**
36
+ * The gitignored worktree a Check runs in at a merge-base with the Base branch,
37
+ * beside the Tickets' own: named for the commit, shortened as git shortens one.
38
+ */
39
+ export function baseWorktreePath(repoRoot: string, commit: string): string {
40
+ return join(repoRoot, ".worktrees", `base-${commit.slice(0, 12)}`);
41
+ }
package/src/cli.ts CHANGED
@@ -81,7 +81,6 @@ async function main(argv: string[]): Promise<number> {
81
81
  return removeTarget({
82
82
  repoRoot: root,
83
83
  version,
84
- repository,
85
84
  config: loadConfig(root, version),
86
85
  tracker: new GhTracker({ cwd: root }),
87
86
  workspace: new GitWorkspace(root),
package/src/config.ts CHANGED
@@ -125,10 +125,10 @@ export interface Config {
125
125
 
126
126
  const STAGE_DEFAULTS = {
127
127
  implement: { maxTurns: 300, maxMinutes: 60 },
128
- verify: { maxTurns: 80, maxMinutes: 20 },
128
+ verify: { maxTurns: 130, maxMinutes: 30 },
129
129
  fix: { maxTurns: 150, maxMinutes: 40 },
130
- // Resolving one rebase is narrower work than mending a defect, and the skill
131
- // has the Checks to run before it finishes.
130
+ // Resolving one rebase is narrower work than mending a defect, and the full
131
+ // Checks are the pipeline's to run once it finishes.
132
132
  conflict: { maxTurns: 120, maxMinutes: 30 },
133
133
  } as const;
134
134
 
@@ -104,6 +104,7 @@ A Ticket is one issue the pipeline can implement in a single session. It is refu
104
104
  ## Checks
105
105
 
106
106
  - The Checks of different Tickets may run at the same time, each in its own worktree, because a Run has as many Lanes as \`lanes\` says. A Target whose Checks need a port, a database or anything else they would have to share keeps \`lanes\` at one, or makes them independent of each other.
107
+ - A Check that fails on a Ticket's branch, or CI that fails on its pull request, is graded again at what the branch inherited: the pipeline runs the Check commands in a clean worktree at the branch's merge-base with the Base branch. One that fails there too is the Base branch's, not the Ticket's, so the Ticket is released without spending its Fix budget, the Run claims no more Tickets, and the pipeline posts a Note on the standing Notes issue naming the Check. The next Run rebases the Ticket onto the Base branch before its Checks, so mending the Base branch is what frees it. Nothing is installed in the worktree at the merge-base: its Checks find their dependencies in the main checkout, as a Ticket's worktree does, so Checks that need an install or a build step of their own fail there and release the Ticket, and the Note's output shows it.
107
108
 
108
109
  ## The Operator's skill
109
110
 
@@ -113,6 +114,6 @@ A Ticket is one issue the pipeline can implement in a single session. It is refu
113
114
 
114
115
  Both are \`ticket-runner\`'s own, both are gitignored by \`ticket-runner init\`, and neither is ever committed.
115
116
 
116
- - \`.worktrees/ticket-<n>/\` — one git worktree per claimed Ticket, where its Stages run.
117
+ - \`.worktrees/ticket-<n>/\` — one git worktree per claimed Ticket, where its Stages run. Beside them, \`.worktrees/base-<commit>/\` is a clean worktree at a merge-base with the Base branch, made to run a failing Check there once and removed when it has run.
117
118
  - \`.ticket-runner/\` — the Run's logs and Stage transcripts. The Run lock and the State a Ticket keeps while its branch has work worth resuming are not here but on the Target's remote, so that a Run on any Host sees which Run holds the Target, and carries on from where a killed Run, or a handed-off Ticket relabelled \`ready-for-agent\`, stopped.
118
119
  `;
@@ -0,0 +1,132 @@
1
+ /**
2
+ * Whether a Check a Ticket's branch failed is one it inherited.
3
+ *
4
+ * The Checks run on the Ticket's branch, and CI on its pull request, so a
5
+ * failure alone cannot say whether the branch brought it or the Base branch
6
+ * did. A test that starts failing on the Base branch fails on every branch at
7
+ * once, and a fix Stage per Ticket then mends it differently in each pull
8
+ * request, at the cost of every Ticket's Fix budget. So a failure is graded
9
+ * once more, at what the branch inherited: its merge-base with the Base branch,
10
+ * checked out clean in a worktree of its own. One that fails there too is the
11
+ * Base branch's, and the Ticket is released rather than charged for it.
12
+ */
13
+
14
+ import { baseWorktreePath } from "./branch.js";
15
+ import type { RoutedNote } from "./notes.js";
16
+ import type { CheckOutcome, Workspace } from "./ports/workspace.js";
17
+
18
+ /** A Check command the Base branch fails, and how. */
19
+ export interface FailingBase {
20
+ /** The merge-base it fails at, in full. */
21
+ commit: string;
22
+ command: string;
23
+ output: string;
24
+ timedOut: boolean;
25
+ }
26
+
27
+ /** What it takes to run a Check at a merge-base. */
28
+ export interface BaseCheckRun {
29
+ workspace: Workspace;
30
+ repoRoot: string;
31
+ /** The Check wall-clock limit, which a Check gets at a merge-base as anywhere. */
32
+ timeoutMs: number;
33
+ log?: (line: string) => void;
34
+ }
35
+
36
+ /**
37
+ * The Run's record of the Checks it ran at merge-bases, and of the Notes it
38
+ * posted about the ones that failed there.
39
+ *
40
+ * A Run has one and every Lane shares it, so the Tickets that fail together
41
+ * over one broken Base branch cost one run of the Check between them, and one
42
+ * Note. Runs at the same commit take turns, because they share its worktree.
43
+ * A run that could not be made — no worktree, no git — is forgotten rather
44
+ * than kept, as a standing Notes lookup that failed is: the Ticket that asked
45
+ * is charged as it always was, and the next one asks again.
46
+ */
47
+ export class BaseBranchChecks {
48
+ /** Each command's outcome at each commit, keyed `<commit> <command>`. */
49
+ readonly #outcomes = new Map<string, Promise<CheckOutcome>>();
50
+ /** The last run at each commit, which the next one there waits behind. */
51
+ readonly #turns = new Map<string, Promise<unknown>>();
52
+ /** The Note posted about each commit, or being posted. */
53
+ readonly #notes = new Map<string, Promise<RoutedNote>>();
54
+
55
+ /**
56
+ * The first of `commands` that fails at `commit`, run in that order and
57
+ * stopping there as the Checks do, or nothing when the commit passes them
58
+ * all. Each command runs at a commit at most once per Run.
59
+ */
60
+ async firstFailing(
61
+ run: BaseCheckRun,
62
+ commit: string,
63
+ commands: readonly string[],
64
+ ): Promise<FailingBase | undefined> {
65
+ for (const command of commands) {
66
+ const outcome = await this.#outcome(run, commit, command);
67
+ if (!outcome.ok) {
68
+ return { commit, command, output: outcome.output, timedOut: outcome.timedOut };
69
+ }
70
+ }
71
+ return undefined;
72
+ }
73
+
74
+ /**
75
+ * Post the Note about `commit` once this Run: the first caller posts it and
76
+ * gets it back, and every caller after it gets nothing. A post that failed
77
+ * is forgotten, so a Ticket that was waiting on it, or one released over the
78
+ * same commit later, tries again.
79
+ */
80
+ async noteOnce(commit: string, post: () => Promise<RoutedNote>): Promise<RoutedNote | undefined> {
81
+ const posted = this.#notes.get(commit);
82
+ if (posted !== undefined) {
83
+ const delivered = await posted.then(
84
+ () => true,
85
+ () => false,
86
+ );
87
+ return delivered ? undefined : await this.noteOnce(commit, post);
88
+ }
89
+ const posting = post();
90
+ this.#notes.set(commit, posting);
91
+ try {
92
+ return await posting;
93
+ } catch (error) {
94
+ this.#notes.delete(commit);
95
+ throw error;
96
+ }
97
+ }
98
+
99
+ #outcome(run: BaseCheckRun, commit: string, command: string): Promise<CheckOutcome> {
100
+ const key = `${commit} ${command}`;
101
+ const known = this.#outcomes.get(key);
102
+ if (known !== undefined) return known;
103
+
104
+ const before = this.#turns.get(commit) ?? Promise.resolve();
105
+ const outcome = before.catch(() => undefined).then(() => runAt(run, commit, command));
106
+ this.#turns.set(commit, outcome);
107
+ this.#outcomes.set(key, outcome);
108
+ outcome.catch(() => {
109
+ if (this.#outcomes.get(key) === outcome) this.#outcomes.delete(key);
110
+ });
111
+ return outcome;
112
+ }
113
+ }
114
+
115
+ /**
116
+ * One command in a clean worktree at `commit`, which goes again once it has
117
+ * run. A worktree that will not go is logged and nothing more: the outcome is
118
+ * still the answer, and the next run at the commit replaces what is left.
119
+ */
120
+ async function runAt(run: BaseCheckRun, commit: string, command: string): Promise<CheckOutcome> {
121
+ const path = baseWorktreePath(run.repoRoot, commit);
122
+ await run.workspace.createDetachedWorktree(path, commit);
123
+ try {
124
+ return await run.workspace.runCheck(command, path, run.timeoutMs);
125
+ } finally {
126
+ try {
127
+ await run.workspace.removeWorktree({ path });
128
+ } catch (error) {
129
+ run.log?.(`could not remove the worktree at ${commit}: ${(error as Error).message}`);
130
+ }
131
+ }
132
+ }
package/src/guards.ts CHANGED
@@ -53,7 +53,7 @@ export function skipReason(
53
53
  readyForAgent: string,
54
54
  /**
55
55
  * Whether this is a **Stranded Ticket**: one this checkout already holds, left
56
- * claimed by a Run that never came back (CONTEXT.md). Both refusals read the
56
+ * claimed by a Run that never came back (GLOSSARY.md). Both refusals read the
57
57
  * Claim as somebody else's work, and a stranded Ticket wears it itself — the
58
58
  * assignee is this very user and `ready-for-agent` came off when the Claim was
59
59
  * made — so it passes them and is resumed rather than refused. The Planning
package/src/host.ts CHANGED
@@ -4,7 +4,7 @@ import { existsSync, readFileSync } from "node:fs";
4
4
  import { hostname } from "node:os";
5
5
 
6
6
  /**
7
- * Which kind of Host a Run executes on (CONTEXT.md), decided here and nowhere
7
+ * Which kind of Host a Run executes on (GLOSSARY.md), decided here and nowhere
8
8
  * else, so every part of the pipeline that behaves differently in the cloud
9
9
  * asks the same question the same way.
10
10
  */
@@ -0,0 +1,51 @@
1
+ /**
2
+ * The end of what a command printed, cut to fit where the pipeline quotes it.
3
+ *
4
+ * A CI log goes to a fix Stage and into a hand-off comment, and a failing Base
5
+ * branch's output goes into a Note on the standing Notes issue. Both have to
6
+ * stay readable, and a comment has to stay under what GitHub accepts, so both
7
+ * quote the same tail.
8
+ */
9
+
10
+ /** Lines kept from the tail. */
11
+ export const MAX_TAIL_LINES = 40;
12
+
13
+ /** Characters kept from the tail, for lines long enough to need it. */
14
+ export const MAX_TAIL_CHARS = 4_000;
15
+
16
+ /**
17
+ * The end of a log, under a fixed cap, saying what it left out, or nothing when
18
+ * the log holds nothing but blank space.
19
+ *
20
+ * The tail is the part worth carrying: a runner prints the assertion or the
21
+ * stack that ended the job last, under however much setup noise came first.
22
+ * Both callers pass the output as it came, so one output gives one tail
23
+ * wherever it is quoted.
24
+ */
25
+ export function logTail(log: string): string {
26
+ const lines = throughLastError(log).trim().split("\n");
27
+ let kept = lines.slice(-MAX_TAIL_LINES);
28
+ while (kept.length > 1 && kept.join("\n").length > MAX_TAIL_CHARS) kept = kept.slice(1);
29
+
30
+ const text = kept.join("\n");
31
+ const omitted = lines.length - kept.length;
32
+
33
+ // A single line longer than the whole cap keeps its own tail: the error is at
34
+ // the end of it. Its own start is cut too, which the count alone would not say.
35
+ if (text.length > MAX_TAIL_CHARS) {
36
+ const earlier = omitted > 0 ? `${omitted} earlier lines and the start of this one` : "the start of this line";
37
+ return `… (${earlier} omitted)\n${text.slice(-MAX_TAIL_CHARS)}`;
38
+ }
39
+ return omitted > 0 ? `… (${omitted} earlier lines omitted)\n${text}` : text;
40
+ }
41
+
42
+ /**
43
+ * Everything up to the last line an Actions runner marked `##[error]`, or all
44
+ * of it. What the post-job cleanup prints after the failure would otherwise be
45
+ * the tail that is kept; output with no such line is left whole.
46
+ */
47
+ function throughLastError(log: string): string {
48
+ const lines = log.split("\n");
49
+ const last = lines.findLastIndex((line) => line.includes("##[error]"));
50
+ return last === -1 ? log : lines.slice(0, last + 1).join("\n");
51
+ }
@@ -20,6 +20,9 @@
20
20
  * reading the whole Note, and tells one that waits on a decision from one that
21
21
  * only needs a Ticket by its `next`. `next` alone is optional, because a Stage
22
22
  * that knows neither a fix nor the decision in the way has nothing to put there.
23
+ *
24
+ * This is the list as the verify Stage reads it. The Stages that write code read
25
+ * {@link CODE_STAGE_NOTES_LIST_SCHEMA}, the same list with one more sentence.
23
26
  */
24
27
  export const NOTES_LIST_SCHEMA = {
25
28
  type: "array",
@@ -56,3 +59,21 @@ export const NOTES_LIST_SCHEMA = {
56
59
  additionalProperties: false,
57
60
  },
58
61
  } as const;
62
+
63
+ /**
64
+ * Whose a defect the branch itself introduced is, in the words both the code
65
+ * Stages' schema and their prompts use: one declaration, so the two cannot drift.
66
+ */
67
+ export const OWN_DEFECT =
68
+ "A defect this branch introduced, one that behaves correctly on the Base branch and wrongly here, or one in code this branch added, belongs to this Ticket";
69
+
70
+ /**
71
+ * The list as the implement and fix Stages read it: a defect their own branch
72
+ * introduced is theirs to fix, not to list. verify keeps the list without it,
73
+ * because it fixes nothing and grades the Acceptance Criteria alone, so a
74
+ * regression it demonstrates beside them still has only a Note to go in.
75
+ */
76
+ export const CODE_STAGE_NOTES_LIST_SCHEMA = {
77
+ ...NOTES_LIST_SCHEMA,
78
+ description: `Defects that belong to another Ticket, or to no Ticket yet. ${OWN_DEFECT}: fix it, and do not list it here. Empty when you found none, which is the ordinary case.`,
79
+ } as const;
package/src/notes.ts CHANGED
@@ -30,8 +30,8 @@ import { z } from "zod";
30
30
  * A Stage that ends with Notes.
31
31
  *
32
32
  * Narrower than a Stage name on purpose: the conflict Stage is given no Notes
33
- * channel — it finishes a rebase and touches no file the conflict did not — so
34
- * a Note that claimed to come from one would be a Note nothing could have made.
33
+ * channel — it finishes a rebase and implements nothing — so a Note that
34
+ * claimed to come from one would be a Note nothing could have made.
35
35
  */
36
36
  export type NotingStage = "implement" | "verify" | "fix";
37
37
 
@@ -57,9 +57,13 @@ export interface Note extends NoteText {
57
57
 
58
58
  /** A Note that reached GitHub, which is what a Run summary reports. */
59
59
  export interface RoutedNote {
60
- /** The Ticket whose Stage made the finding. */
60
+ /** The Ticket whose Stage made the finding, or whose Release did. */
61
61
  origin: number;
62
- stage: NotingStage;
62
+ /**
63
+ * The Stage that made it, or the pipeline itself: the one Note no Stage
64
+ * writes is the pipeline's, about a Base branch failing a Check.
65
+ */
66
+ stage: NotingStage | "pipeline";
63
67
  /** The issue the Note reached: the Ticket it named, or the standing Notes issue. */
64
68
  issue: number;
65
69
  /**