ticket-runner 0.6.1 → 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.
@@ -25,11 +25,14 @@ export const EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"] as const;
25
25
  export type Effort = (typeof EFFORT_LEVELS)[number];
26
26
 
27
27
  /**
28
- * Why a Stage did not finish cleanly. `rate-limited` is singled out because the
29
- * pipeline releases a claim rather than blaming the Ticket for it.
28
+ * Why a Stage did not finish cleanly. `rate-limited` and `api-error` are singled
29
+ * out because the pipeline releases a claim rather than blaming the Ticket for
30
+ * either: one is the subscription running out of room, the other the API failing
31
+ * on its side after the CLI had given up retrying it.
30
32
  */
31
33
  export type StageFailure =
32
34
  | "rate-limited"
35
+ | "api-error"
33
36
  | "timed-out"
34
37
  | "turn-capped"
35
38
  | "nonzero-exit"
@@ -71,6 +74,12 @@ export interface StageResult {
71
74
  transcriptPath: string;
72
75
  turns?: number;
73
76
  durationMs: number;
77
+ /**
78
+ * When the subscription rate limit resets, ISO-8601, as the event that
79
+ * rejected the request said. Present only on a `rate-limited` Stage, and only
80
+ * when the CLI said.
81
+ */
82
+ limitResetsAt?: string;
74
83
  }
75
84
 
76
85
  /**
@@ -126,7 +126,7 @@ export interface CreatePullRequest {
126
126
 
127
127
  /**
128
128
  * The outcome of waiting for a pull request's CI checks. Distinct from a Check,
129
- * which is a command the pipeline runs itself (CONTEXT.md).
129
+ * which is a command the pipeline runs itself (GLOSSARY.md).
130
130
  *
131
131
  * `none` means the PR has no checks at all, which `gates.ci` treats as a
132
132
  * failure rather than a silent bypass.
@@ -207,9 +207,10 @@ export interface Tracker {
207
207
  * Release, named `owner/name`, or nothing where GitHub could not be asked.
208
208
  *
209
209
  * Named for the tag rather than for the Release, because a Release in this
210
- * codebase is what a rate-limited Stage does to a Ticket (CONTEXT.md). A
211
- * published GitHub Release is what makes a tag a Version anybody can install,
212
- * which is why it is the question rather than the tag alone.
210
+ * codebase is what a Stage the rate limit or an API failure stopped does to
211
+ * a Ticket (GLOSSARY.md). A published GitHub Release is what makes a tag a
212
+ * Version anybody can install, which is why it is the question rather than
213
+ * the tag alone.
213
214
  *
214
215
  * The one method of this port that is not about the Target: it is asked about
215
216
  * the pipeline's own repository, so a Run and `init` can say that a newer
@@ -45,7 +45,7 @@ export type RebaseState = { resolved: true } | { resolved: false; unresolved: st
45
45
  * `implemented` one carrying that Stage's work on its branch with no merge
46
46
  * behind it.
47
47
  *
48
- * A state of the lifecycle, not a Stage — a Stage is a session (CONTEXT.md), and
48
+ * A state of the lifecycle, not a Stage — a Stage is a session (GLOSSARY.md), and
49
49
  * what the State records is what the Ticket has, not what was running. Only these
50
50
  * two, because everything after the implement Stage — the Checks, the rebase,
51
51
  * the pull request, CI and the merge — is re-run from the top by a Run that
@@ -82,6 +82,13 @@ export interface TicketState {
82
82
  * when no Stage has answered one, and in State an earlier pipeline left.
83
83
  */
84
84
  title?: string;
85
+ /**
86
+ * Whether the Run that takes the Ticket up rebases its branch onto the Base
87
+ * branch before its Checks. Set by a Release over a failing Base branch, so
88
+ * a fix a human has landed there meanwhile reaches the branch; absent
89
+ * otherwise, and in State an earlier pipeline left.
90
+ */
91
+ rebaseFirst?: boolean;
85
92
  /** The Run that last wrote the State, and when — both for a human reading it. */
86
93
  runId: string;
87
94
  /**
@@ -228,6 +235,12 @@ export interface Workspace {
228
235
  * out at `path`. The checkout's own `base` is not moved.
229
236
  */
230
237
  createWorktree(worktree: WorktreeRef, base: string): Promise<void>;
238
+ /**
239
+ * Check `commit` out, detached, in a fresh worktree at `path`, where a Check
240
+ * can be run against what a Ticket's branch inherited. A worktree a killed
241
+ * Run left at `path` is replaced: nothing in one is worth keeping.
242
+ */
243
+ createDetachedWorktree(path: string, commit: string): Promise<void>;
231
244
  /**
232
245
  * Remove the worktree and delete its branch; a detached worktree, which has
233
246
  * none, is only removed.
@@ -235,7 +248,9 @@ export interface Workspace {
235
248
  removeWorktree(worktree: { path: string; branch?: string }): Promise<void>;
236
249
  /**
237
250
  * Every `ticket-<n>` worktree of this repo under the Target's `.worktrees/`,
238
- * whatever Ticket or Run made it, with what each holds that GitHub lacks.
251
+ * whatever Ticket or Run made it, with what each holds that GitHub lacks,
252
+ * and every `base-<commit>` worktree a Run killed mid-Check left there,
253
+ * which holds nothing worth keeping whatever the Check wrote into it.
239
254
  *
240
255
  * Asked by `ticket-runner remove` alone, which refuses to take out a
241
256
  * worktree holding work nothing else has.
@@ -287,6 +302,13 @@ export interface Workspace {
287
302
  * answers yes about.
288
303
  */
289
304
  hasBranch(branch: string): Promise<boolean>;
305
+ /**
306
+ * The commit the branch checked out at `cwd` inherited from `base`: their
307
+ * merge-base, with `base` as the remote holds it now. The checkout's own
308
+ * `base` may be behind what the branch was made from, and the remote's ahead
309
+ * of it, and neither changes what the branch inherited.
310
+ */
311
+ mergeBase(cwd: string, base: string): Promise<string>;
290
312
  /**
291
313
  * Subjects of the commits on `branch` that `base` does not have, oldest first.
292
314
  *
package/src/prompts.ts CHANGED
@@ -6,6 +6,7 @@
6
6
 
7
7
  import { CONVENTIONS_PATH } from "./conventions.js";
8
8
  import type { FailureKind } from "./lifecycle.js";
9
+ import { OWN_DEFECT } from "./note-schema.js";
9
10
  import { STAGE_ENV_VAR } from "./stage-guard.js";
10
11
  import { BRANCH_TITLE } from "./title.js";
11
12
 
@@ -47,10 +48,32 @@ function stageBoundary(selfHosted: boolean): string {
47
48
  * a Stage told only to remove what no commit carries deletes the dependencies
48
49
  * it installed for nothing.
49
50
  */
50
- const FINISH_GUIDANCE = `- Never end your turn while uncommitted work waits on a background task: the session ends with your turn and stops that task, and the work is never committed. Run your final tests in the foreground, then commit.
51
+ const FINISH_GUIDANCE = `- Never end your turn while uncommitted work waits on a background task: the session ends with your turn and stops that task, and the work is never committed.
51
52
  - Leave the worktree clean: commit your work and remove every untracked file that is not ignored and that no commit carries, test output included. The pipeline refuses a worktree holding changes no commit carries.
52
53
  - Keep gitignored files, such as dependencies you installed. The pipeline does not count them against a clean worktree, and deleting them only leaves the next Stage to install them again.`;
53
54
 
55
+ /** The Check commands as a prompt names them. */
56
+ function checkList(checks: readonly string[]): string {
57
+ return checks.map((command) => `\`${command}\``).join(", ");
58
+ }
59
+
60
+ /**
61
+ * How the two Stages that write code are told about the Checks, where the
62
+ * config names any; nothing where it names none.
63
+ *
64
+ * The pipeline runs them as soon as the Stage finishes, so a Stage that runs the
65
+ * whole suite while it works, and again after each change, pays for runs the
66
+ * pipeline is about to make anyway: in the logged Runs that was half of an
67
+ * implement Stage's wall clock. One run after its last commit still catches a
68
+ * failure before it spends the Fix budget. implement's comes after the review,
69
+ * because the review changes code in nearly every Stage.
70
+ */
71
+ function codeChecksLine(checks: readonly string[], afterReview: boolean): string {
72
+ if (checks.length === 0) return "";
73
+ const review = afterReview ? " That one run comes after the review's fixes are committed." : "";
74
+ return `\n- The pipeline runs its Checks as soon as you finish: ${checkList(checks)}. While you work, run only the tests your change touches. Commit, then run the full Checks once, in the foreground, and commit whatever that run makes you change.${review}`;
75
+ }
76
+
54
77
  /**
55
78
  * How the two Stages that write code are told to title the branch. The title is
56
79
  * an answer rather than a commit subject because a commit subject describes its
@@ -64,15 +87,17 @@ const titleGuidance = (base: string) =>
64
87
  * Guidance appended to every implement Stage, working around known defects of
65
88
  * the `implement` skill in an unattended session.
66
89
  */
67
- const implementGuidance = (base: string) => `This session is unattended. Follow this guidance as well as the skill's own:
90
+ const implementGuidance = (
91
+ base: string,
92
+ checks: readonly string[],
93
+ ) => `This session is unattended. Follow this guidance as well as the skill's own:
68
94
 
69
- - Confirm the Ticket title matches what you are about to build before you start.
70
95
  - Make an initial commit before running \`/mattpocock-skills:code-review\`, so the reviewed diff is not empty.
71
96
  ${titleGuidance(base)}
72
97
  - The review the skill asks for is \`/mattpocock-skills:code-review\`. Invoke it by that full name: the short name also matches the CLI's own built-in review skill, which runs neither the Standards review nor the Spec review.
73
98
  - Spawn its review sub-agents with \`run_in_background: false\` set explicitly, several in one message so they still run in parallel. Omitting \`run_in_background\` still runs them in the background, and you would then reach your answer before the review has come back.
74
99
  - Do not answer the schema until the review has returned and the fixes you take from it are committed. An answer you have already given does not stop you committing: the pipeline waits for this session to exit before it reads the branch.
75
- - A later answer replaces an earlier one, so if you answer again, repeat every Note you still stand by.
100
+ - A later answer replaces an earlier one, so if you answer again, repeat every Note you still stand by.${codeChecksLine(checks, true)}
76
101
  ${FINISH_GUIDANCE}
77
102
  - Do not spawn nested review agents beyond what the skill itself does.
78
103
  - Do not open pull requests and do not close the issue; the pipeline does both.
@@ -83,10 +108,15 @@ ${FINISH_GUIDANCE}
83
108
  * things this Ticket is not about. Nothing here changes what the Stage is for:
84
109
  * it is the channel that stops a finding becoming either scope creep or a lost
85
110
  * paragraph in a transcript.
111
+ *
112
+ * A defect the branch itself introduced is the exception, and is said first:
113
+ * "another Ticket" alone left it unowned, and such Notes became bug issues
114
+ * opened after the branch that caused them had merged.
86
115
  */
87
116
  const notesGuidance = (standingNotes?: number) => `Notes for other Tickets: if you discover something that belongs to another Ticket, or to no Ticket yet, do not act on it here and do not widen this Ticket to cover it.
88
117
 
89
- - Record it as a Note instead. Your structured output carries a \`notes\` list, and the pipeline posts each entry where a human will meet it.
118
+ - ${OWN_DEFECT}: fix it, and do not record it as a Note.
119
+ - Record anything else as a Note instead. Your structured output carries a \`notes\` list, and the pipeline posts each entry where a human will meet it.
90
120
  ${noteEntryGuidance(standingNotes)}`;
91
121
 
92
122
  /**
@@ -142,32 +172,87 @@ function standingLine(standingNotes?: number): string {
142
172
  return `\n- Notes with no Ticket are gathered on #${standingNotes}. Read it first and take what it already records as recorded: write a second Note about a condition it names only when what you saw changes what a reader would do about it, and not when it is another instance of the same thing.`;
143
173
  }
144
174
 
145
- const VERIFY_INSTRUCTIONS = `You are the verify Stage of an unattended pipeline. Your job is adversarial: try to prove each Acceptance Criterion is NOT met.
175
+ /**
176
+ * What makes an unmet criterion one only a human can settle, in the words both
177
+ * the verify and the fix Stage are given.
178
+ */
179
+ const NEEDS_A_HUMAN =
180
+ "cannot be met without overturning a documented decision or another criterion";
181
+
182
+ /**
183
+ * The verify Stage's brief. It grades a commit the Checks have just passed, so
184
+ * where the config names any it is told so and told not to run them again: in
185
+ * the logged Runs re-running them was about two fifths of a verify Stage's wall
186
+ * clock, spent proving what the pipeline had already proved.
187
+ *
188
+ * A criterion that collides with a documented decision or another criterion is
189
+ * `unmet` with a human's decision as its evidence, rather than met on a
190
+ * workaround: the fix Stage it buys is told to commit nothing for it, which is
191
+ * what hands the question to a human.
192
+ */
193
+ const verifyInstructions = (checks: readonly string[]) => `You are the verify Stage of an unattended pipeline. Your job is adversarial: try to prove each Acceptance Criterion is NOT met.
146
194
 
147
195
  - Read the Ticket's Acceptance Criteria from its body and from its comments; the checkbox list may live in either.
148
196
  - Work in the checked-out branch, which already contains the implementation.
149
- - Attempt to falsify every criterion: run the code, run the tests, and write throwaway tests where that is the only way to tell.
197
+ - Attempt to falsify every criterion: run the code, run the tests that bear on it, and write throwaway tests where that is the only way to tell.${verifyChecksLine(checks)}
150
198
  - Judge the code as it is. Do not fix anything, and never commit, stage or push. Scratch files are fine; the pipeline discards them.
151
199
  - Mark a criterion \`unverifiable\` only when no evidence can be gathered, never as a substitute for looking.
200
+ - When a criterion ${NEEDS_A_HUMAN}, mark it \`unmet\` and say in its evidence that a human decision is needed, naming what it collides with. A workaround that sidesteps the collision does not meet it.
152
201
  - End by emitting the Verdict: one entry per criterion with its status and the evidence you actually gathered.`;
153
202
 
154
- const fixInstructions = (base: string) => `You are the fix Stage of an unattended pipeline. The Ticket below is already implemented on the branch you are on, and one gate failed. You are what its fix budget bought, and the budget is spent: a second failure of any kind hands the Ticket to a human.
203
+ /** The Checks as the verify Stage is told about them: passed, and not its to run. */
204
+ function verifyChecksLine(checks: readonly string[]): string {
205
+ if (checks.length === 0) return "";
206
+ return `\n- The pipeline's Checks passed on this commit: ${checkList(checks)}. Do not re-run them: grade a criterion that asks only for them from that fact, and spend your turns on targeted tests and probes.`;
207
+ }
208
+
209
+ /**
210
+ * The fix Stage's brief. Sent in for unmet criteria, it is told what to do when
211
+ * one of them needs a human decision: commit nothing, which hands the Ticket to
212
+ * a human with the criteria and their evidence. Left to itself it worked around
213
+ * every such criterion it met, and the verify behind it passed the workaround.
214
+ */
215
+ const fixInstructions = (
216
+ base: string,
217
+ kind: FailureKind,
218
+ checks: readonly string[],
219
+ ) => `You are the fix Stage of an unattended pipeline. The Ticket below is already implemented on the branch you are on, and one gate failed. You are what its fix budget bought, and the budget is spent: a second failure of any kind hands the Ticket to a human.
155
220
 
156
221
  - Commit your fix on the branch you are on, in this worktree. Do not create a branch, do not open pull requests, and do not close the Ticket.
157
222
  - Start from the evidence: reproduce the failure, find what actually causes it, and fix that rather than the symptom.
158
- - Where the failure is an unmet Acceptance Criterion, add the regression test that would have caught it and commit it with the fix.
159
- - Stay inside this Ticket's Acceptance Criteria. Anything else you find belongs to another Ticket, not to this session; record it as a Note rather than mending it.
223
+ - Where the failure is an unmet Acceptance Criterion, add the regression test that would have caught it and commit it with the fix.${kind === "unmet-criteria" ? HUMAN_DECISION_LINE : ""}
224
+ - Stay inside this Ticket's Acceptance Criteria and the defects this branch introduced. Anything else you find belongs to another Ticket, not to this session; record it as a Note rather than mending it.${codeChecksLine(checks, false)}
160
225
  ${FINISH_GUIDANCE}
161
226
  - Write commit subjects in the convention \`${CONVENTIONS_PATH}\` states. The pipeline re-runs the Checks and the verify Stage as soon as you finish.
162
227
  ${titleGuidance(base)}`;
163
228
 
164
- const conflictInstructions = (base: string) => `You are the conflict Stage of an unattended pipeline. The Ticket below is already implemented on the branch you are on, and rebasing it onto \`${base}\` stopped on a conflict. That rebase is still in progress in this worktree, and finishing it is the whole of your job.
229
+ /** What the fix Stage sent in for unmet criteria does with one only a human can settle. */
230
+ const HUMAN_DECISION_LINE = `
231
+ - When any unmet criterion ${NEEDS_A_HUMAN}, as the verify Stage's evidence may already say, commit nothing and say why in your last message. Do not work around it: a fix Stage that commits nothing hands the Ticket to a human, with the unmet criteria and their evidence.`;
232
+
233
+ /**
234
+ * The conflict Stage's brief. It may reach past the conflicted files only to
235
+ * repair what the merge broke there, such as a name the Base branch renamed:
236
+ * a Stage that left those red would spend the Fix budget on them. Nothing it
237
+ * does may change behaviour the criteria cover, because verify does not run
238
+ * again after it.
239
+ */
240
+ const conflictInstructions = (
241
+ base: string,
242
+ checks: readonly string[],
243
+ ) => `You are the conflict Stage of an unattended pipeline. The Ticket below is already implemented on the branch you are on, and rebasing it onto \`${base}\` stopped on a conflict. That rebase is still in progress in this worktree, and finishing it is the whole of your job.
165
244
 
166
245
  - Resolve every hunk and carry the rebase through to the end; never \`git rebase --abort\`, and never rewind the branch to escape the conflict.
167
246
  - Where the two sides are compatible, keep both intents. Where they are not, keep the behaviour this Ticket's Acceptance Criteria ask for, and keep \`${base}\`'s everywhere the Ticket is silent.
168
- - Resolve, do not redesign. Implement nothing new, and touch no file the conflict did not.
247
+ - Resolve, do not redesign. Change a file the conflict did not touch only to repair what the merge itself broke, such as a renamed name or a moved field. Implement nothing new, and change no behaviour this Ticket's Acceptance Criteria cover: verify does not grade the branch again after you.
169
248
  - Leave no conflict marker behind in any file, committed or not.
170
- - Do not push, do not open pull requests, and do not close the Ticket. The pipeline runs the Checks again as soon as you finish, and a failure there spends this Ticket's fix budget.`;
249
+ - Do not push, do not open pull requests, and do not close the Ticket.${conflictChecksLine(checks)}`;
250
+
251
+ /** The Checks as the conflict Stage is told about them: the pipeline's to run in full. */
252
+ function conflictChecksLine(checks: readonly string[]): string {
253
+ if (checks.length === 0) return "";
254
+ return `\n- The pipeline runs its Checks as soon as you finish, and a failure there spends this Ticket's fix budget: ${checkList(checks)}. Run the type checker and the tests covering the files you resolved, not the whole suite.`;
255
+ }
171
256
 
172
257
  /** How the fix prompt announces each kind of failure. */
173
258
  const failureSentences = (base: string): Record<FailureKind, string> => ({
@@ -194,27 +279,38 @@ export function implementPrompt(
194
279
  base: string,
195
280
  extraPrompt: string,
196
281
  selfHosted: boolean,
282
+ checks: readonly string[],
197
283
  standingNotes?: number,
198
284
  ): string {
199
285
  return sections([
200
286
  `/mattpocock-skills:implement ${issueUrl}`,
201
- implementGuidance(base),
287
+ implementGuidance(base, checks),
202
288
  stageBoundary(selfHosted),
203
289
  notesGuidance(standingNotes),
204
290
  extraPrompt,
205
291
  ]);
206
292
  }
207
293
 
208
- /** A fresh session with no plugin skill, graded against the Verdict schema. */
294
+ /**
295
+ * A fresh session with no plugin skill, graded against the Verdict schema.
296
+ *
297
+ * `unmetBefore` is the evidence of the Verdict a fix Stage was sent in for, in
298
+ * the same Run; a first verify has none. Without it the verify behind a fix
299
+ * graded the fix on its own terms, and passed a caveat the first one had
300
+ * counted as unmet.
301
+ */
209
302
  export function verifyPrompt(
210
303
  issueUrl: string,
211
304
  extraPrompt: string,
212
305
  selfHosted: boolean,
306
+ checks: readonly string[],
213
307
  standingNotes?: number,
308
+ unmetBefore?: string,
214
309
  ): string {
215
310
  return sections([
216
311
  `Ticket: ${issueUrl}`,
217
- VERIFY_INSTRUCTIONS,
312
+ verifyInstructions(checks),
313
+ unmetBefore === undefined ? "" : unmetBeforeSection(unmetBefore),
218
314
  stageBoundary(selfHosted),
219
315
  verifyNotesGuidance(standingNotes),
220
316
  extraPrompt,
@@ -228,10 +324,11 @@ export function conflictPrompt(
228
324
  base: string,
229
325
  extraPrompt: string,
230
326
  selfHosted: boolean,
327
+ checks: readonly string[],
231
328
  ): string {
232
329
  return sections([
233
330
  `Ticket: ${issueUrl}`,
234
- conflictInstructions(base),
331
+ conflictInstructions(base, checks),
235
332
  outputSection("## Where the rebase stopped", conflict),
236
333
  stageBoundary(selfHosted),
237
334
  extraPrompt,
@@ -245,11 +342,12 @@ export function fixPrompt(
245
342
  base: string,
246
343
  extraPrompt: string,
247
344
  selfHosted: boolean,
345
+ checks: readonly string[],
248
346
  standingNotes?: number,
249
347
  ): string {
250
348
  return sections([
251
349
  `Ticket: ${issueUrl}`,
252
- fixInstructions(base),
350
+ fixInstructions(base, failure.kind, checks),
253
351
  failureSection(failure, base),
254
352
  stageBoundary(selfHosted),
255
353
  notesGuidance(standingNotes),
@@ -266,6 +364,15 @@ function failureSection({ kind, summary, evidence }: FixFailure, base: string):
266
364
  );
267
365
  }
268
366
 
367
+ /** The unmet criteria a fix Stage was sent in for, and what meeting them now takes. */
368
+ function unmetBeforeSection(evidence: string): string {
369
+ return outputSection(
370
+ "## Judged unmet before the fix",
371
+ evidence,
372
+ "The verify Stage before you judged these criteria unmet, with this evidence, and a fix Stage has worked on the branch since. Such a criterion is met only when that counterexample is gone and the whole criterion holds: a fix that answers the evidence but not the rest of the criterion, or a caveat in place of the behaviour, leaves it `unmet`.",
373
+ );
374
+ }
375
+
269
376
  /**
270
377
  * A heading, an optional line of prose, and raw command output. The output is
271
378
  * fenced because it would otherwise be read as Markdown.
package/src/resume.ts CHANGED
@@ -11,10 +11,10 @@ import { REACHED_STATES, type StateFile, type TicketState } from "./ports/worksp
11
11
  * resuming, so it is written as part of the Claim and rewritten whenever the
12
12
  * Ticket reaches something a later Run should not pay for again. Three Runs read
13
13
  * it, and what the board says decides which. One finds a Ticket the subscription
14
- * rate limit released: nothing was wrong with it, so the Claim came off and this
15
- * file says where to carry on from. One finds a Ticket still claimed — the Run
16
- * that claimed it was killed and never released anything — and resumes it in
17
- * place. One finds a Ticket a human was handed and has relabelled
14
+ * rate limit or a transient API failure released: nothing was wrong with it, so
15
+ * the Claim came off and this file says where to carry on from. One finds a
16
+ * Ticket still claimed — the Run that claimed it was killed and never released
17
+ * anything — and resumes it in place. One finds a Ticket a human was handed and has relabelled
18
18
  * `ready-for-agent`, which is the human handing it back. A Ticket still sitting
19
19
  * in `ready-for-human` is none of them: its file is inert until a human moves
20
20
  * the label or the issue closes.
@@ -35,6 +35,7 @@ const stateSchema = z.object({
35
35
  fixUsed: z.boolean(),
36
36
  pullRequest: z.number().int().positive().optional(),
37
37
  title: z.string().optional(),
38
+ rebaseFirst: z.boolean().optional(),
38
39
  runId: z.string(),
39
40
  version: z.string().optional(),
40
41
  updatedAt: z.string(),
@@ -79,13 +80,14 @@ export function readStateFile(contents: string, ticket: number): StateFile {
79
80
  // older pipeline never wrote, are keys that are not there rather than keys
80
81
  // holding nothing: the rest of the pipeline reads these with the same
81
82
  // distinction.
82
- const { pullRequest, title, version, ...state } = parsed.data;
83
+ const { pullRequest, title, rebaseFirst, version, ...state } = parsed.data;
83
84
  return {
84
85
  readable: true,
85
86
  state: {
86
87
  ...state,
87
88
  ...(pullRequest === undefined ? {} : { pullRequest }),
88
89
  ...(title === undefined ? {} : { title }),
90
+ ...(rebaseFirst === undefined ? {} : { rebaseFirst }),
89
91
  ...(version === undefined ? {} : { version }),
90
92
  },
91
93
  };
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 { RELEASE_WORDS } 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,20 @@ 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
+ | {
50
+ reason: "failing-base";
51
+ baseBranch: string;
52
+ /** The merge-base the Check failed at, in full. */
53
+ commit: string;
54
+ /** The Check command it failed. */
55
+ command: string;
56
+ }
41
57
  | {
42
58
  reason: "stopped";
43
59
  /** When the Stop reached the Run, ISO-8601. */
@@ -60,11 +76,13 @@ export type RunStop =
60
76
  * not cost the rest of the night.
61
77
  *
62
78
  * 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.
79
+ * the Ticket — the subscription ran out of room, or the API failed on its own
80
+ * side after the CLI had given up retrying it — so the next one would be stopped
81
+ * the same way, and claiming it would spend a Claim, a worktree and a doomed
82
+ * Stage to learn what the first one already said. The Lanes still busy finish
83
+ * what they hold, and the Run reports what stopped it once the last of them
84
+ * comes back. It does not wait for the limit to reset: a human or an Operator
85
+ * starts the next Run, and the summary says when the limit resets.
68
86
  *
69
87
  * A Stop is the same shape with a different reason: a human asked for no more
70
88
  * Tickets rather than the subscription, so the Lanes busy at that moment finish
@@ -107,10 +125,11 @@ export async function processRun(
107
125
  // Lane unblocked on the way is not one the Run was still held up by.
108
126
  let blocked: number[] = [];
109
127
  // 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.
128
+ // the Release and the Stop came first: a Stop that arrives after a Release
129
+ // asked for what was already happening, and a Release afterwards stopped
130
+ // nothing that was not stopped already. Only a later rate limit overwrites
131
+ // it, and only where limitOutranks says so. Undefined is a Run still taking
132
+ // Tickets, which is why it doubles as the guard at every refill.
114
133
  let runStop: RunStop | undefined;
115
134
  // A Frontier the tracker refused to list, kept until the Lanes still busy are
116
135
  // back. A Run must not walk away from a Ticket mid-Stage to report that `gh`
@@ -147,13 +166,14 @@ export async function processRun(
147
166
  * Put a Ticket in a Lane, and record what came back when it ends.
148
167
  *
149
168
  * 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.
169
+ * by no other, even where a later rate limit replaces the API failure it
170
+ * stopped the Run with. The Ticket's own release is already logged where it
171
+ * happened; this says the Run goes no further, so a transcript shows the
172
+ * Frontier was left alone rather than found empty, and a Release into a Run
173
+ * that an earlier Release or a Stop had stopped already claims to have
174
+ * stopped nothing. It leads with the Ticket's number all the same: a
175
+ * transcript of interleaved Lanes must not lose the line that explains why
176
+ * 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,12 @@ 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?.(`#${outcome.ticket} stopped the Run · ${RELEASE_WORDS[outcome.cause]}`);
189
+ } else if (outcome.cause === "rate-limited" && limitOutranks(runStop)) {
190
+ runStop = releaseStop(outcome, pipeline.baseBranch);
168
191
  }
169
192
  }),
170
193
  );
@@ -230,6 +253,35 @@ export async function processRun(
230
253
  return { outcomes, stop };
231
254
  }
232
255
 
256
+ /**
257
+ * The stop a Release puts on the Run: what released it, when a limit resets,
258
+ * and which Check the Base branch fails.
259
+ */
260
+ function releaseStop(
261
+ outcome: Extract<TicketOutcome, { outcome: "released" }>,
262
+ baseBranch: string,
263
+ ): RunStop {
264
+ if (outcome.cause === "api-error") return { reason: "api-error" };
265
+ if (outcome.failingBase !== undefined) {
266
+ return { reason: "failing-base", baseBranch, ...outcome.failingBase };
267
+ }
268
+ return {
269
+ reason: "rate-limited",
270
+ ...(outcome.limitResetsAt === undefined ? {} : { resetsAt: outcome.limitResetsAt }),
271
+ };
272
+ }
273
+
274
+ /**
275
+ * Whether a Ticket the rate limit released after `stop` puts the limit in its
276
+ * place. An API failure says nothing of when the next Run can start, so the
277
+ * limit outranks it; a limit nobody was told the end of is outranked by one a
278
+ * Stage was told. A failing Base branch and a Stop stay whatever comes after
279
+ * them, and so does a limit already told when it resets.
280
+ */
281
+ function limitOutranks(stop: RunStop): boolean {
282
+ return stop.reason === "api-error" || (stop.reason === "rate-limited" && stop.resetsAt === undefined);
283
+ }
284
+
233
285
  /**
234
286
  * A Ticket a narrowed Run was given and never met, as the row that says why.
235
287
  *
package/src/start.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import { resolveBaseBranch } from "./base-branch.js";
2
2
  import type { Config } from "./config.js";
3
3
  import { hostKind } from "./host.js";
4
+ import { BaseBranchChecks } from "./failing-base.js";
4
5
  import { Landing } from "./landing.js";
5
6
  import { StandingNotes } from "./notes.js";
6
7
  import { lockHeldMessage, unreleasedLockMessage } from "./lock.js";
@@ -207,6 +208,9 @@ async function execute(
207
208
  // Once per Run as well: the Notes of every Ticket the night takes land on
208
209
  // one issue, and the Run looks it up once however many it writes.
209
210
  standingNotes: new StandingNotes(),
211
+ // Once per Run as well: Tickets failing one Check over one broken Base
212
+ // branch run it at their merge-base once between them.
213
+ baseChecks: new BaseBranchChecks(),
210
214
  selfHosted,
211
215
  log,
212
216
  };
@@ -269,7 +273,7 @@ function opening(runId: string, work: Work, lanes: number): string {
269
273
  /**
270
274
  * A hand-off is what the exit code reports first, because it is the one outcome
271
275
  * 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.
276
+ * the rate limit resets, or the API recovers, and a later Run resumes it.
273
277
  *
274
278
  * A narrowed Run that took none of the Tickets it was given — every one
275
279
  * skipped, blocked, or a mix — took nothing at all, which is the same nothing a