ticket-runner 0.6.1 → 0.6.3

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/src/run.ts CHANGED
@@ -5,6 +5,7 @@ import type { RoutedNote } from "./notes.js";
5
5
  import { type Pipeline, type TicketOutcome, processTicket } from "./orchestrator.js";
6
6
  import { StopSignal, stopLine } from "./stop.js";
7
7
  import { holdsClaim, strandedTickets } from "./stranded.js";
8
+ import { releaseWords } from "./templates.js";
8
9
 
9
10
  /**
10
11
  * What a Run has to show for itself: every Ticket it took, in the order they
@@ -22,11 +23,13 @@ export interface RunResult {
22
23
  /**
23
24
  * Why a Run ended.
24
25
  *
25
- * A Run that drained the Frontier carries what was left held back; one the rate
26
- * limit stopped carries nothing, because it ended before it could say a
27
- * candidate was held back all Run; one a human stopped carries the moment it
28
- * was asked and what it still had in hand. That is why this is a choice rather
29
- * than a flag beside the list: the three stops do not report the same things.
26
+ * A Run that drained the Frontier carries what was left held back; one a
27
+ * Release stopped carries no candidates, because it ended before it could say
28
+ * one was held back all Run, and the rate limit carries when it resets, where a
29
+ * Stage was told, and a failing Base branch the Check it fails and where; one
30
+ * a human stopped carries the moment it was asked and what it still had in
31
+ * hand. That is why this is a choice rather than a flag beside
32
+ * the list: the stops do not report the same things.
30
33
  */
31
34
  export type RunStop =
32
35
  | {
@@ -37,7 +40,21 @@ export type RunStop =
37
40
  */
38
41
  blocked: number[];
39
42
  }
40
- | { reason: "rate-limited" }
43
+ | {
44
+ reason: "rate-limited";
45
+ /** When the limit resets, ISO-8601, absent where no Stage was told. */
46
+ resetsAt?: string;
47
+ }
48
+ | { reason: "api-error" }
49
+ | { reason: "out-of-budget" }
50
+ | {
51
+ reason: "failing-base";
52
+ baseBranch: string;
53
+ /** The merge-base the Check failed at, in full. */
54
+ commit: string;
55
+ /** The Check command it failed. */
56
+ command: string;
57
+ }
41
58
  | {
42
59
  reason: "stopped";
43
60
  /** When the Stop reached the Run, ISO-8601. */
@@ -60,11 +77,13 @@ export type RunStop =
60
77
  * not cost the rest of the night.
61
78
  *
62
79
  * A Release stops the Run filling Lanes and nothing more. Nothing was wrong with
63
- * the Ticket — the subscription ran out of room — so the next one would be
64
- * stopped by the same limit, and claiming it would spend a Claim, a worktree and
65
- * a doomed Stage to learn what the first one already said. The Lanes still busy
66
- * finish what they hold, and the Run reports the limit once the last of them
67
- * comes back.
80
+ * the Ticket — the subscription or the API key ran out of room, or the API
81
+ * failed on its own side after the CLI had given up retrying it — so the next
82
+ * one would be stopped the same way, and claiming it would spend a Claim, a
83
+ * worktree and a doomed Stage to learn what the first one already said. The Lanes still busy finish
84
+ * what they hold, and the Run reports what stopped it once the last of them
85
+ * comes back. It does not wait for the limit to reset: a human or an Operator
86
+ * starts the next Run, and the summary says when the limit resets.
68
87
  *
69
88
  * A Stop is the same shape with a different reason: a human asked for no more
70
89
  * Tickets rather than the subscription, so the Lanes busy at that moment finish
@@ -107,10 +126,11 @@ export async function processRun(
107
126
  // Lane unblocked on the way is not one the Run was still held up by.
108
127
  let blocked: number[] = [];
109
128
  // Why this Run stopped, which is also what it reports. Set by whichever of
110
- // the Release and the Stop came first and never overwritten: a Stop that
111
- // arrives after a Release asked for what was already happening, and a Release
112
- // afterwards stopped nothing that was not stopped already. Undefined is a Run
113
- // still taking Tickets, which is why it doubles as the guard at every refill.
129
+ // the Release and the Stop came first: a Stop that arrives after a Release
130
+ // asked for what was already happening, and a Release afterwards stopped
131
+ // nothing that was not stopped already. Only a later API budget or rate
132
+ // limit overwrites it, and only where `outranks` says so. Undefined is a Run still taking
133
+ // Tickets, which is why it doubles as the guard at every refill.
114
134
  let runStop: RunStop | undefined;
115
135
  // A Frontier the tracker refused to list, kept until the Lanes still busy are
116
136
  // back. A Run must not walk away from a Ticket mid-Stage to report that `gh`
@@ -147,13 +167,13 @@ export async function processRun(
147
167
  * Put a Ticket in a Lane, and record what came back when it ends.
148
168
  *
149
169
  * The line about the Run stopping is logged by the Release that stopped it and
150
- * by no other. The Ticket's own release is already logged where it happened;
151
- * this says the Run goes no further, so a transcript shows the Frontier was
152
- * left alone rather than found empty, and a Release into a Run that an earlier
153
- * Release or a Stop had stopped already claims to have stopped nothing. It
154
- * leads with the Ticket's number all the same: a transcript of interleaved
155
- * Lanes must not lose the line that explains why one Lane was the last to be
156
- * filled.
170
+ * by no other, even where a later Release outranks it on the last line. The
171
+ * Ticket's own release is already logged where it happened; this says the Run
172
+ * goes no further, so a transcript shows the Frontier was left alone rather
173
+ * than found empty, and a Release into a Run that an earlier Release or a
174
+ * Stop had stopped already claims to have stopped nothing. It leads with the
175
+ * Ticket's number all the same: a transcript of interleaved Lanes must not
176
+ * lose the line that explains why one Lane was the last to be filled.
157
177
  */
158
178
  function fillLane(ticket: Taken): void {
159
179
  taken.add(ticket.number);
@@ -162,9 +182,14 @@ export async function processRun(
162
182
  take(pipeline, ticket).then((outcome) => {
163
183
  busy.delete(ticket.number);
164
184
  outcomes.push(outcome);
165
- if (outcome.outcome === "released" && runStop === undefined) {
166
- runStop = { reason: "rate-limited" };
167
- pipeline.log?.(`#${outcome.ticket} stopped the Run · rate limit`);
185
+ if (outcome.outcome !== "released") return;
186
+ if (runStop === undefined) {
187
+ runStop = releaseStop(outcome, pipeline.baseBranch);
188
+ pipeline.log?.(
189
+ `#${outcome.ticket} stopped the Run · ${releaseWords(outcome.cause, pipeline.credential)}`,
190
+ );
191
+ } else if (outranks(outcome, runStop)) {
192
+ runStop = releaseStop(outcome, pipeline.baseBranch);
168
193
  }
169
194
  }),
170
195
  );
@@ -230,6 +255,52 @@ export async function processRun(
230
255
  return { outcomes, stop };
231
256
  }
232
257
 
258
+ /**
259
+ * The stop a Release puts on the Run: what released it, when a limit resets,
260
+ * and which Check the Base branch fails.
261
+ */
262
+ function releaseStop(
263
+ outcome: Extract<TicketOutcome, { outcome: "released" }>,
264
+ baseBranch: string,
265
+ ): RunStop {
266
+ if (outcome.cause === "api-error") return { reason: "api-error" };
267
+ if (outcome.cause === "out-of-budget") return { reason: "out-of-budget" };
268
+ if (outcome.failingBase !== undefined) {
269
+ return { reason: "failing-base", baseBranch, ...outcome.failingBase };
270
+ }
271
+ return {
272
+ reason: "rate-limited",
273
+ ...(outcome.limitResetsAt === undefined ? {} : { resetsAt: outcome.limitResetsAt }),
274
+ };
275
+ }
276
+
277
+ /**
278
+ * Whether a Ticket released after `stop` puts its own stop in its place.
279
+ *
280
+ * An API key out of budget outranks the rate limit and an API failure, since
281
+ * it alone needs the human to act: no wait mends it, only the Console. The
282
+ * rate limit outranks an API failure, which says nothing of when the next Run
283
+ * can start, and a limit nobody was told the end of is outranked by one a
284
+ * Stage was told. A failing Base branch and a Stop stay whatever comes after
285
+ * them, and so does an API budget, and a limit already told when it resets.
286
+ */
287
+ function outranks(
288
+ outcome: Extract<TicketOutcome, { outcome: "released" }>,
289
+ stop: RunStop,
290
+ ): boolean {
291
+ switch (outcome.cause) {
292
+ case "out-of-budget":
293
+ return stop.reason === "rate-limited" || stop.reason === "api-error";
294
+ case "rate-limited":
295
+ return (
296
+ stop.reason === "api-error" ||
297
+ (stop.reason === "rate-limited" && stop.resetsAt === undefined)
298
+ );
299
+ default:
300
+ return false;
301
+ }
302
+ }
303
+
233
304
  /**
234
305
  * A Ticket a narrowed Run was given and never met, as the row that says why.
235
306
  *
package/src/start.ts CHANGED
@@ -1,6 +1,8 @@
1
1
  import { resolveBaseBranch } from "./base-branch.js";
2
2
  import type { Config } from "./config.js";
3
- import { hostKind } from "./host.js";
3
+ import { type Credential, credentialRefusal } from "./credential.js";
4
+ import { type HostKind, hostKind } from "./host.js";
5
+ import { BaseBranchChecks } from "./failing-base.js";
4
6
  import { Landing } from "./landing.js";
5
7
  import { StandingNotes } from "./notes.js";
6
8
  import { lockHeldMessage, unreleasedLockMessage } from "./lock.js";
@@ -8,7 +10,7 @@ import type { Pipeline, TicketOutcome } from "./orchestrator.js";
8
10
  import type { AgentRunner } from "./ports/agent-runner.js";
9
11
  import type { Tracker } from "./ports/tracker.js";
10
12
  import type { Workspace } from "./ports/workspace.js";
11
- import { readinessRefusal } from "./readiness.js";
13
+ import { readinessRefusal, unpushedRefusal } from "./readiness.js";
12
14
  import { LOCAL_STATE_DIR, localStateTickets } from "./resume.js";
13
15
  import { writeRunVersion } from "./run-log.js";
14
16
  import { type RunStop, processRun } from "./run.js";
@@ -35,11 +37,15 @@ import { runSummary } from "./templates.js";
35
37
  * because how many Tickets a Host can carry at once is the Host's business, not
36
38
  * the Target's (ADR-0008). It may also be narrowed to the Tickets a human
37
39
  * named, ascending and each once; with none it drains the whole Frontier.
40
+ * It runs its Stages on the Host's API key only when it was started with
41
+ * `--api-key`, for the same reason: whose money a Run spends is the Host's
42
+ * business.
38
43
  */
39
44
  export interface Work {
40
45
  command: "run";
41
46
  lanes?: number;
42
47
  tickets?: number[];
48
+ apiKey?: true;
43
49
  }
44
50
 
45
51
  export interface StartOptions {
@@ -67,15 +73,21 @@ export interface StartOptions {
67
73
  error?: (line: string) => void;
68
74
  /** Where SIGTERM comes from. The process itself, unless a test is watching. */
69
75
  signals?: StopSource;
76
+ /**
77
+ * The Host's environment, which says what kind of Host this is and whether it
78
+ * exports a key. The process's own, unless a test says otherwise.
79
+ */
80
+ env?: Record<string, string | undefined>;
70
81
  }
71
82
 
72
83
  /**
73
84
  * Start a Run, and answer with the exit code it earned.
74
85
  *
75
- * Every refusal comes before the lock: a Target `init` has not set up, one
76
- * holding State files an earlier pipeline left in the checkout, and one with
77
- * nothing to gate a merge. None is a Run that went wrong, so none should leave
78
- * a lock behind for the next one to reclaim.
86
+ * Every refusal comes before the lock: an `--api-key` the Host cannot honour,
87
+ * a Target `init` has not set up, one whose remote lacks what `init` wrote,
88
+ * one holding State files an earlier pipeline left in the checkout, and one
89
+ * with nothing to gate a merge. None is a Run that went wrong, so none should
90
+ * leave a lock behind for the next one to reclaim.
79
91
  */
80
92
  export async function startRun(given: StartOptions): Promise<number> {
81
93
  // The count a Run was told is folded into the config once, here, so
@@ -86,6 +98,17 @@ export async function startRun(given: StartOptions): Promise<number> {
86
98
  const { repoRoot, config, tracker, workspace } = options;
87
99
  const log = options.log ?? ((line: string) => console.log(line));
88
100
  const error = options.error ?? ((line: string) => console.error(line));
101
+ const env = options.env ?? process.env;
102
+
103
+ // First, because it asks nothing of the Target: the Host either can or
104
+ // cannot run the Stages on the credential the Run was started with.
105
+ const credential: Credential = options.work.apiKey === true ? "api-key" : "subscription";
106
+ const host = hostKind(env);
107
+ const refusedCredential = credentialRefusal(credential, host, env);
108
+ if (refusedCredential !== undefined) {
109
+ error(refusedCredential);
110
+ return 2;
111
+ }
89
112
 
90
113
  const notReady = await readinessRefusal({ repoRoot, labels: config.labels, tracker });
91
114
  if (notReady !== undefined) {
@@ -93,6 +116,18 @@ export async function startRun(given: StartOptions): Promise<number> {
93
116
  return 2;
94
117
  }
95
118
 
119
+ // Once per Run, and here rather than with the rest of the Run's setup:
120
+ // readiness asks the remote's copy of this branch for what `init` wrote, and
121
+ // every branch, rebase, pull request and pull of the Run goes to the same one.
122
+ // After readiness's own questions, since the lookup may ask GitHub, which only
123
+ // a `gh` that runs can.
124
+ const baseBranch = await resolveBaseBranch(tracker, config);
125
+ const notPushed = await unpushedRefusal({ workspace, baseBranch });
126
+ if (notPushed !== undefined) {
127
+ error(notPushed);
128
+ return 2;
129
+ }
130
+
96
131
  const leftBehind = localStateTickets(repoRoot);
97
132
  if (leftBehind.length > 0) {
98
133
  error(localStateMessage(leftBehind));
@@ -139,7 +174,7 @@ export async function startRun(given: StartOptions): Promise<number> {
139
174
  const stopping = new StopSignal();
140
175
  const deafen = listenForStop(stopping, options.signals);
141
176
  try {
142
- return await execute(options, log, stopping);
177
+ return await execute(options, { credential, host, baseBranch }, log, stopping);
143
178
  } finally {
144
179
  // The lock goes first: SIGTERM between the two is a kill again, and a kill
145
180
  // that leaves the lock behind costs the next Run a stale holder to reclaim,
@@ -158,6 +193,11 @@ export async function startRun(given: StartOptions): Promise<number> {
158
193
 
159
194
  async function execute(
160
195
  options: StartOptions,
196
+ {
197
+ credential,
198
+ host,
199
+ baseBranch,
200
+ }: { credential: Credential; host: HostKind; baseBranch: string },
161
201
  log: (line: string) => void,
162
202
  stopping: StopSignal,
163
203
  ): Promise<number> {
@@ -182,11 +222,7 @@ async function execute(
182
222
  repository: options.repository,
183
223
  });
184
224
 
185
- // Once per Run, before any Ticket: every branch, rebase, pull request and
186
- // pull of this Run goes to the branch this answers.
187
- const baseBranch = await resolveBaseBranch(tracker, config);
188
-
189
- // Once per Run as well: only a Target that is the pipeline's own repository
225
+ // Once per Run: only a Target that is the pipeline's own repository
190
226
  // has a checkout that is the pipeline, and every Stage is told which it is in.
191
227
  const selfHosted = await isPipelineRepository(tracker, options.repository);
192
228
 
@@ -198,7 +234,9 @@ async function execute(
198
234
  repoRoot,
199
235
  runId,
200
236
  version,
201
- host: hostKind(process.env),
237
+ host,
238
+ credential,
239
+ strayStages: [],
202
240
  baseBranch,
203
241
  // Once per Run as well, and for the same reason: the Tickets of one Run
204
242
  // take turns between their rebase and their merge, and a Landing made per
@@ -207,6 +245,9 @@ async function execute(
207
245
  // Once per Run as well: the Notes of every Ticket the night takes land on
208
246
  // one issue, and the Run looks it up once however many it writes.
209
247
  standingNotes: new StandingNotes(),
248
+ // Once per Run as well: Tickets failing one Check over one broken Base
249
+ // branch run it at their merge-base once between them.
250
+ baseChecks: new BaseBranchChecks(),
210
251
  selfHosted,
211
252
  log,
212
253
  };
@@ -219,7 +260,9 @@ async function execute(
219
260
  version,
220
261
  runId,
221
262
  durationMs: Date.now() - startedAt,
263
+ credential,
222
264
  outcomes,
265
+ strayStages: pipeline.strayStages,
223
266
  ...(newer === undefined ? {} : { newer }),
224
267
  stop,
225
268
  });
@@ -269,7 +312,7 @@ function opening(runId: string, work: Work, lanes: number): string {
269
312
  /**
270
313
  * A hand-off is what the exit code reports first, because it is the one outcome
271
314
  * that asks a human for something. A released Ticket was taken all the same:
272
- * the rate limit resets and a later Run resumes it.
315
+ * the rate limit resets, or the API recovers, and a later Run resumes it.
273
316
  *
274
317
  * A narrowed Run that took none of the Tickets it was given — every one
275
318
  * skipped, blocked, or a mix — took nothing at all, which is the same nothing a
package/src/templates.ts CHANGED
@@ -4,11 +4,13 @@
4
4
  */
5
5
 
6
6
  import { UNCHECKED_BOX } from "./acceptance-criteria.js";
7
+ import { CREDENTIAL_WORDS, type Credential, type StrayStage } from "./credential.js";
7
8
  import type { GuardReason } from "./guards.js";
8
9
  import type { HostKind } from "./host.js";
9
10
  import type { FailurePoint } from "./lifecycle.js";
11
+ import { logTail } from "./log-tail.js";
10
12
  import type { NoteText, NotingStage, RoutedNote } from "./notes.js";
11
- import type { TicketOutcome } from "./orchestrator.js";
13
+ import type { ReleaseCause, TicketOutcome } from "./orchestrator.js";
12
14
  import type { IssueComment, SquashCommit } from "./ports/tracker.js";
13
15
  import type { KeptTranscripts } from "./ports/workspace.js";
14
16
  import type { RunStop } from "./run.js";
@@ -418,6 +420,61 @@ export function noteComment(subject: NoteSubject): string {
418
420
  return [NOTE_MARKER, noteProvenance(subject), "", paragraphs.join("\n\n"), ""].join("\n");
419
421
  }
420
422
 
423
+ /** A Check the Base branch fails, as the pipeline's own Note reports it. */
424
+ export interface FailingBaseNote {
425
+ /** The Ticket the failure released. */
426
+ origin: number;
427
+ /** Where the Ticket's branch failed: its Checks, or CI on its pull request. */
428
+ point: "checks" | "ci";
429
+ baseBranch: string;
430
+ /** The Ticket's branch, whose merge-base with the Base branch `commit` is. */
431
+ branch: string;
432
+ /** The merge-base, in full, so it can be checked out as it is. */
433
+ commit: string;
434
+ command: string;
435
+ output: string;
436
+ timedOut: boolean;
437
+ }
438
+
439
+ /** The pipeline's Note's summary, which is also the Run summary's `noted` row. */
440
+ export function failingBaseSummary(baseBranch: string, command: string): string {
441
+ return `The Base branch \`${baseBranch}\` fails \`${command}\`.`;
442
+ }
443
+
444
+ /**
445
+ * The one Note no Stage writes: a Ticket was released because the Base branch
446
+ * fails the Check its branch failed, so the defect is the Base branch's and a
447
+ * human has to mend it there.
448
+ *
449
+ * Signed and laid out as a Stage's Note is, so triage reads it the same way,
450
+ * with the provenance naming the pipeline rather than a Stage. The tail of the
451
+ * output is the one a CI log excerpt keeps, so long lines cannot push the Note
452
+ * past what GitHub takes in a comment. It is fenced with more backticks than
453
+ * any run of them inside it, so a fence the output prints cannot close it early.
454
+ */
455
+ export function failingBaseNote(note: FailingBaseNote): string {
456
+ const { baseBranch, branch, commit, command } = note;
457
+ const tail = logTail(note.output);
458
+ const where = `\`${command}\` ${note.timedOut ? "timed out" : "failed"} in a clean worktree at ${commit}, the merge-base of \`${branch}\` with \`${baseBranch}\`.`;
459
+ const fence = "`".repeat(Math.max(3, ...[...tail.matchAll(/`+/g)].map(([run]) => run.length + 1)));
460
+ const evidence =
461
+ tail === ""
462
+ ? `**Evidence**: ${where} It printed nothing.`
463
+ : `**Evidence**: ${where} The tail of its output:\n\n${fence}\n${escapeCheckboxes(tail)}\n${fence}`;
464
+ return [
465
+ NOTE_MARKER,
466
+ `From the pipeline, releasing #${note.origin} at ${note.point}`,
467
+ "",
468
+ [
469
+ `**${failingBaseSummary(baseBranch, command)}**`,
470
+ evidence,
471
+ `**Impact**: every Ticket whose branch inherits ${commit} fails the same Check. #${note.origin} was released with its Fix budget as it was, and the Run claimed no more Tickets.`,
472
+ `**Next**: mend \`${command}\` on \`${baseBranch}\`. The next Run takes the released Tickets up again from their State files, rebased onto \`${baseBranch}\` before their Checks.`,
473
+ ].join("\n\n"),
474
+ "",
475
+ ].join("\n");
476
+ }
477
+
421
478
  /** Whether an issue's body says it is the standing Notes issue. */
422
479
  export function isNotesIssue(body: string): boolean {
423
480
  return carriesMarker(body, NOTES_ISSUE_MARKER);
@@ -440,7 +497,8 @@ export function notesIssue(): { title: string; body: string } {
440
497
  "**Notes from the pipeline.** Every finding a Stage could not post on a " +
441
498
  "Ticket arrives here as a comment: one that named no Ticket, one whose " +
442
499
  "Ticket would have buried it, and one whose Ticket refused the comment. " +
443
- "Each comment says which Ticket and Stage found it.",
500
+ "So does the pipeline's own Note about a Base branch that fails a Check. " +
501
+ "Each comment says which Ticket and Stage, or the pipeline, found it.",
444
502
  "",
445
503
  "Triage empties this issue by hand: promote what deserves a Ticket, record " +
446
504
  "the promotion in this body, and close the issue once the body accounts " +
@@ -456,7 +514,14 @@ export interface RunSummary {
456
514
  version: string;
457
515
  runId: string;
458
516
  durationMs: number;
517
+ /** What the Run's Stages were billed to, which its header names. */
518
+ credential: Credential;
459
519
  outcomes: TicketOutcome[];
520
+ /**
521
+ * Every Stage that said it ran on something else, each named in a row after
522
+ * its own Ticket's.
523
+ */
524
+ strayStages?: readonly StrayStage[];
460
525
  /**
461
526
  * The line saying a newer Version is out, where one is. Above the header
462
527
  * rather than below it: the Run already said this hours ago, at the top of a
@@ -467,24 +532,56 @@ export interface RunSummary {
467
532
  stop: RunStop;
468
533
  }
469
534
 
535
+ /**
536
+ * What a Release is put down to, in the words the Run summary and the log
537
+ * share: the rate limit, a transient API failure, an API key out of credit or
538
+ * past its spend limit, or a Base branch that fails the Check the Ticket's
539
+ * branch failed.
540
+ */
541
+ export const RELEASE_WORDS: Record<ReleaseCause, string> = {
542
+ "rate-limited": "rate limit",
543
+ "api-error": "API failure",
544
+ "out-of-budget": "out of API budget",
545
+ "failing-base": "failing Base branch",
546
+ };
547
+
548
+ /**
549
+ * The same words, for a Run on `credential`. A rate limit on an `--api-key`
550
+ * Run is the API's, not the subscription's, and is named so: what the human
551
+ * looks at about it is the Console, not their plan.
552
+ */
553
+ export function releaseWords(cause: ReleaseCause, credential: Credential): string {
554
+ return cause === "rate-limited" && credential === "api-key"
555
+ ? "API rate limit"
556
+ : RELEASE_WORDS[cause];
557
+ }
558
+
470
559
  /** Every summary row is `<verb> #<n> <detail>`, so the numbers line up. */
471
560
  const VERB_WIDTH = 9;
472
561
 
473
562
  /**
474
563
  * What a Run prints when it ends. One line per Ticket, then why the Run
475
564
  * stopped — the Frontier is empty, everything left on it is blocked, the rate
476
- * limit released a Ticket and the Run went no further, or a human stopped it.
565
+ * limit, a transient API failure, the API key's budget or a failing Base branch
566
+ * released a Ticket and the Run went no further, or a human stopped it.
477
567
  */
478
568
  export function runSummary({
479
569
  version,
480
570
  runId,
481
571
  durationMs,
572
+ credential,
482
573
  outcomes,
574
+ strayStages = [],
483
575
  newer,
484
576
  stop,
485
577
  }: RunSummary): string {
486
578
  const rows = [
487
- ...outcomes.flatMap(ticketRows),
579
+ ...outcomes.flatMap((outcome) => [
580
+ ...ticketRows(outcome, credential),
581
+ ...strayStages
582
+ .filter((stray) => stray.ticket === outcome.ticket)
583
+ .map((stray) => row("billed", stray.ticket, `${stray.stage} · apiKeySource ${stray.apiKeySource}`)),
584
+ ]),
488
585
  // Only a Run that reached the end of the Frontier can name what was held
489
586
  // back all Run, so only that stop carries candidates to skip.
490
587
  ...(stop.reason === "frontier"
@@ -494,20 +591,30 @@ export function runSummary({
494
591
 
495
592
  return [
496
593
  ...(newer === undefined ? [] : [newer]),
497
- `ticket-runner ${version} run ${runId} · ${Math.round(durationMs / 60_000)}m`,
594
+ `ticket-runner ${version} run ${runId} · ${Math.round(durationMs / 60_000)}m · ${CREDENTIAL_WORDS[credential]}`,
498
595
  "",
499
596
  ...(rows.length === 0 ? [" nothing to do"] : rows),
500
597
  "",
501
- lastLine(stop),
598
+ lastLine(stop, credential),
502
599
  "",
503
600
  ].join("\n");
504
601
  }
505
602
 
506
603
  /** The one line that says why the Run stopped. */
507
- function lastLine(stop: RunStop): string {
604
+ function lastLine(stop: RunStop, credential: Credential): string {
508
605
  switch (stop.reason) {
509
- case "rate-limited":
510
- return "Rate limited.";
606
+ case "rate-limited": {
607
+ const limited = credential === "api-key" ? "API rate limited" : "Rate limited";
608
+ return stop.resetsAt === undefined
609
+ ? `${limited}.`
610
+ : `${limited} · resets ${utcMinute(stop.resetsAt)}.`;
611
+ }
612
+ case "api-error":
613
+ return "API failure.";
614
+ case "out-of-budget":
615
+ return "Out of API budget.";
616
+ case "failing-base":
617
+ return `Base branch \`${stop.baseBranch}\` fails \`${stop.command}\` at ${stop.commit.slice(0, 7)}.`;
511
618
  case "stopped":
512
619
  return `Stopped at ${clockTime(stop.at)} · ${holding(stop.busy)}.`;
513
620
  case "frontier":
@@ -523,6 +630,14 @@ function clockTime(at: string): string {
523
630
  return at.slice(11, 16);
524
631
  }
525
632
 
633
+ /**
634
+ * The date and minute a limit resets, in UTC like the Stop's clock time. The
635
+ * date is kept because a weekly limit can reset days after the Run stopped.
636
+ */
637
+ function utcMinute(at: string): string {
638
+ return `${at.slice(0, 10)} ${at.slice(11, 16)} UTC`;
639
+ }
640
+
526
641
  /** What the Lanes were holding when the Stop arrived, and what to call none. */
527
642
  function holding(busy: number[]): string {
528
643
  if (busy.length === 0) return "nothing to finish";
@@ -535,9 +650,9 @@ function holding(busy: number[]): string {
535
650
  * The Notes follow their own Ticket rather than being gathered at the end, so a
536
651
  * Run that took six Tickets still says which one noticed what.
537
652
  */
538
- function ticketRows(outcome: TicketOutcome): string[] {
653
+ function ticketRows(outcome: TicketOutcome, credential: Credential): string[] {
539
654
  return [
540
- ticketRow(outcome),
655
+ ticketRow(outcome, credential),
541
656
  ...(outcome.outcome === "skipped" ? [] : outcome.notes.map(noteRow)),
542
657
  ];
543
658
  }
@@ -570,7 +685,7 @@ function noteRow({ origin, stage, issue, opened, summary }: RoutedNote): string
570
685
  }
571
686
 
572
687
  /** One Ticket's line in a summary: what happened to it, and where to look. */
573
- function ticketRow(outcome: TicketOutcome): string {
688
+ function ticketRow(outcome: TicketOutcome, credential: Credential): string {
574
689
  switch (outcome.outcome) {
575
690
  case "merged":
576
691
  return row("merged", outcome.ticket, `${outcome.title} (PR #${outcome.pullRequest})`);
@@ -581,9 +696,13 @@ function ticketRow(outcome: TicketOutcome): string {
581
696
  `${outcome.title} · ${outcome.stage} · ${outcome.failure}`,
582
697
  );
583
698
  case "released":
584
- // Nothing for a human to do, so the row says only where the limit landed
585
- // and leaves the rest to the Run that resumes the Ticket.
586
- return row("released", outcome.ticket, `${outcome.title} · rate limit at ${outcome.stage}`);
699
+ // Nothing for a human to do, so the row says only what stopped the Stage
700
+ // and where, and leaves the rest to the Run that resumes the Ticket.
701
+ return row(
702
+ "released",
703
+ outcome.ticket,
704
+ `${outcome.title} · ${releaseWords(outcome.cause, credential)} at ${outcome.stage}`,
705
+ );
587
706
  case "skipped":
588
707
  // The reason is the guard's own word for it, which is also the marker on
589
708
  // the warning comment the human is being pointed at.
package/src/title.ts CHANGED
@@ -10,7 +10,7 @@
10
10
  * rewriting it.
11
11
  */
12
12
 
13
- import { NOTES_LIST_SCHEMA } from "./note-schema.js";
13
+ import { CODE_STAGE_NOTES_LIST_SCHEMA } from "./note-schema.js";
14
14
 
15
15
  /**
16
16
  * What a title is asked to be, in the words both the schema and the prompts of
@@ -41,7 +41,7 @@ export const CODE_STAGE_JSON_SCHEMA = {
41
41
  type: "string",
42
42
  description: `Write ${BRANCH_TITLE}: \`<type>(<scope>): <summary>\`, without the \`(#<n>)\`. It titles the pull request and the squash commit that lands.`,
43
43
  },
44
- notes: NOTES_LIST_SCHEMA,
44
+ notes: CODE_STAGE_NOTES_LIST_SCHEMA,
45
45
  },
46
46
  required: ["title", "notes"],
47
47
  additionalProperties: false,