ticket-runner 0.6.4 → 0.6.5

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.
Files changed (48) hide show
  1. package/README.ko.md +4 -4
  2. package/README.md +3 -3
  3. package/docs/templates/operator-skill.md +7 -7
  4. package/package.json +1 -1
  5. package/src/acceptance-criteria.ts +2 -2
  6. package/src/adapters/claude-agent-runner.ts +3 -3
  7. package/src/adapters/exec.ts +19 -4
  8. package/src/adapters/gh-tracker.ts +17 -17
  9. package/src/adapters/git-workspace.ts +12 -8
  10. package/src/adapters/liveness.ts +77 -0
  11. package/src/adapters/process-tree.ts +4 -7
  12. package/src/adapters/version.ts +5 -5
  13. package/src/branch.ts +1 -1
  14. package/src/cli.ts +2 -2
  15. package/src/config.ts +4 -4
  16. package/src/conventions.ts +21 -18
  17. package/src/credential.ts +14 -13
  18. package/src/criteria.ts +107 -15
  19. package/src/failing-base.ts +7 -7
  20. package/src/failure-message.ts +72 -0
  21. package/src/guards.ts +2 -2
  22. package/src/handoff.ts +2 -2
  23. package/src/init.ts +8 -8
  24. package/src/landing.ts +1 -1
  25. package/src/lifecycle.ts +2 -2
  26. package/src/lock.ts +10 -2
  27. package/src/note-schema.ts +3 -3
  28. package/src/notes.ts +8 -6
  29. package/src/operator-skill.ts +2 -2
  30. package/src/orchestrator.ts +168 -128
  31. package/src/ports/agent-runner.ts +1 -1
  32. package/src/ports/tracker.ts +14 -13
  33. package/src/ports/workspace.ts +23 -22
  34. package/src/progress.ts +2 -2
  35. package/src/prompts.ts +67 -24
  36. package/src/readiness.ts +11 -11
  37. package/src/remove.ts +7 -7
  38. package/src/resume.ts +12 -12
  39. package/src/run-log.ts +5 -5
  40. package/src/run.ts +7 -7
  41. package/src/staleness.ts +14 -14
  42. package/src/start.ts +17 -12
  43. package/src/stranded.ts +19 -19
  44. package/src/templates.ts +147 -66
  45. package/src/title.ts +44 -8
  46. package/src/verdict.ts +7 -7
  47. package/src/version-number.ts +13 -13
  48. package/src/version-pr.ts +12 -12
@@ -47,6 +47,7 @@ import {
47
47
  import { retryLogDir, stageLogDir } from "./run-log.js";
48
48
  import { holdsClaim } from "./stranded.js";
49
49
  import {
50
+ type BranchFailure,
50
51
  RELEASE_WORDS,
51
52
  releaseWords,
52
53
  draftPullRequestBody,
@@ -59,7 +60,12 @@ import {
59
60
  squashCommit,
60
61
  } from "./templates.js";
61
62
  import type { StartTimer } from "./timer.js";
62
- import { CODE_STAGE_JSON_SCHEMA, parseTitle, pullRequestTitle } from "./title.js";
63
+ import {
64
+ CODE_STAGE_JSON_SCHEMA,
65
+ parseNoCommitReason,
66
+ parseTitle,
67
+ pullRequestTitle,
68
+ } from "./title.js";
63
69
  import {
64
70
  type Verdict,
65
71
  VERDICT_JSON_SCHEMA,
@@ -104,7 +110,7 @@ export type TicketOutcome =
104
110
  * told. Absent for an API failure, which says nothing of when it ends.
105
111
  */
106
112
  limitResetsAt?: string;
107
- /** The Check the Base branch fails, and where, for a Release over it. */
113
+ /** The Check the base branch fails, and where, for a Release over it. */
108
114
  failingBase?: { commit: string; command: string };
109
115
  notes: RoutedNote[];
110
116
  }
@@ -125,7 +131,7 @@ export interface Pipeline {
125
131
  repoRoot: string;
126
132
  runId: string;
127
133
  /**
128
- * The Version this Run is, resolved once in the CLI and stamped on everything
134
+ * The version this Run is, resolved once in the CLI and stamped on everything
129
135
  * the Run writes (ADR-0007). A string, never a lookup: nothing here reads
130
136
  * `package.json` or runs git, so every stamp of one Run is the same string.
131
137
  */
@@ -155,7 +161,7 @@ export interface Pipeline {
155
161
  /**
156
162
  * The Run's Landing, made once before the first Ticket and shared by every
157
163
  * Ticket it drives: only one of them is between its rebase and the pull of
158
- * the Base branch after its merge at a time (ADR-0005).
164
+ * the base branch after its merge at a time (ADR-0005).
159
165
  */
160
166
  landing: Landing;
161
167
  /**
@@ -165,9 +171,9 @@ export interface Pipeline {
165
171
  */
166
172
  standingNotes: StandingNotes;
167
173
  /**
168
- * The Checks the Run ran at merge-bases with the Base branch, made once and
174
+ * The Checks the Run ran at merge-bases with the base branch, made once and
169
175
  * shared by every Ticket: the Tickets that fail together over one broken
170
- * Base branch run the Check there once between them, and post one Note.
176
+ * base branch run the Check there once between them, and post one Note.
171
177
  */
172
178
  baseChecks: BaseBranchChecks;
173
179
  /**
@@ -190,6 +196,10 @@ export interface Pipeline {
190
196
  * A failure that ends the Ticket, unless the fix budget can still buy it a
191
197
  * second try. `kind` is set on exactly the failures a fix Stage is given:
192
198
  * everything else is a hand-off the moment it is thrown.
199
+ *
200
+ * `reason` is set on exactly one failure of each code Stage: the Stage
201
+ * finished and left no new commit, and it said why. The hand-off quotes it, and
202
+ * since it lives on this failure alone, no other hand-off of the Ticket can.
193
203
  */
194
204
  class TicketFailure extends Error {
195
205
  constructor(
@@ -197,6 +207,7 @@ class TicketFailure extends Error {
197
207
  readonly summary: string,
198
208
  readonly evidence: string = "",
199
209
  readonly kind?: FailureKind,
210
+ readonly reason?: string,
200
211
  ) {
201
212
  super(summary);
202
213
  }
@@ -206,7 +217,7 @@ class TicketFailure extends Error {
206
217
  * What stops a Ticket that says nothing about it: the rate limit, a transient
207
218
  * API failure — the API overloaded, broken or silent on its own side after the
208
219
  * CLI had already retried it — the API key of an `--api-key` Run out of credit
209
- * or past its workspace's spend limit, and a Base branch that fails the Check
220
+ * or past its workspace's spend limit, and a base branch that fails the Check
210
221
  * the Ticket's branch failed.
211
222
  */
212
223
  export type ReleaseCause = StageReleaseCause | "failing-base";
@@ -226,7 +237,7 @@ function releaseCause(result: StageResult): StageReleaseCause | undefined {
226
237
  * A Stage something other than the Ticket stopped, on its way to a Release.
227
238
  *
228
239
  * The Stage failures that say nothing about the Ticket are the ones that
229
- * neither end it nor spend its Fix budget: the Claim is released and a State
240
+ * neither end it nor spend its fix budget: the claim is released and a state
230
241
  * file is left for the next Run to resume from (ADR-0004). It is not a
231
242
  * {@link TicketFailure} because every path that handles one of those would
232
243
  * either hand the Ticket off or buy it a fix Stage, and this is neither.
@@ -238,13 +249,20 @@ class Releasing extends Error {
238
249
  readonly state: ReachedState,
239
250
  readonly reason: ReleaseCause,
240
251
  readonly limitResetsAt?: string,
241
- /** The Check the Base branch fails too, for a Release over it. */
242
- readonly failingBase?: FailingBase,
252
+ /** The Check the base branch fails too, for a Release over it. */
253
+ readonly failingBase?: InheritedFailure,
243
254
  ) {
244
255
  super(`the ${point} Stage was stopped · ${RELEASE_WORDS[reason]}`);
245
256
  }
246
257
  }
247
258
 
259
+ /**
260
+ * A Check the base branch fails, and how the branch itself failed, which the
261
+ * Note about it quotes beside the merge-base's output: only the command is
262
+ * compared, so the two need not be the same failure.
263
+ */
264
+ type InheritedFailure = FailingBase & { onBranch: BranchFailure };
265
+
248
266
  /** An error the pipeline did not raise itself, blamed on the step it was on. */
249
267
  function asTicketFailure(error: unknown, point: FailurePoint): TicketFailure {
250
268
  return error instanceof TicketFailure
@@ -256,13 +274,12 @@ function asTicketFailure(error: unknown, point: FailurePoint): TicketFailure {
256
274
  * Take one Ticket from claimed to merged, hand it to a human, or pass it over.
257
275
  *
258
276
  * The happy path is: guards → claim → worktree and branch → implement Stage →
259
- * Checks → verify Stage → rebase → PR → CI → squash merge → cleanup. Work left
260
- * uncommitted, a failing Check, an unmet criterion, a red CI or a rebase
261
- * conflict the conflict Stage could not resolve spends the Ticket's fix budget
262
- * and starts again at the Checks; every other failure, and every second
263
- * failure, ends in a hand-off.
264
- * Nothing ends in a merge that has not been through a green pass of the whole
265
- * gauntlet.
277
+ * Checks → verify Stage → rebase → pull request → CI → squash merge → cleanup.
278
+ * Work left uncommitted, a failing Check, an unmet criterion, a red CI or a
279
+ * rebase conflict the conflict Stage could not resolve spends the Ticket's fix
280
+ * budget and starts again at the Checks; every other failure, and every second
281
+ * failure, ends in a hand-off. Nothing ends in a merge that has not been
282
+ * through a green pass of the whole gauntlet.
266
283
  *
267
284
  * A Stage the subscription rate limit or a transient API failure stopped ends
268
285
  * none of that: the Ticket is released, and a Run started once the limit has
@@ -277,9 +294,9 @@ function asTicketFailure(error: unknown, point: FailurePoint): TicketFailure {
277
294
  * untriaged from its Frontier, but the Ticket may have changed hands since the
278
295
  * listing, so the guards ask again.
279
296
  *
280
- * From the pull of the Base branch before the rebase to the pull after the
281
- * merge the Ticket holds the Run's Landing, so no other Ticket of the same Run moves the Base
282
- * branch underneath the branch CI is grading (ADR-0005).
297
+ * From the pull of the base branch before the rebase to the pull after the
298
+ * merge the Ticket holds the Run's Landing, so no other Ticket of the same Run
299
+ * moves the base branch underneath the branch CI is grading (ADR-0005).
283
300
  */
284
301
  export async function processTicket(
285
302
  pipeline: Pipeline,
@@ -318,7 +335,7 @@ async function takeTicket(
318
335
 
319
336
  // What an earlier Run left behind, read before the guards because it decides
320
337
  // one of them: a Ticket this pipeline still holds with state recorded for it is
321
- // stranded — the Claim on it is this pipeline's own, left by a Run that never
338
+ // stranded — the claim on it is this pipeline's own, left by a Run that never
322
339
  // came back — and the refusals must not read it as somebody else's.
323
340
  const recorded = await workspace.readState(ticket);
324
341
  const stranded = recorded !== undefined && holdsClaim(issue, user, config.labels.inProgress);
@@ -345,12 +362,12 @@ async function takeTicket(
345
362
  log,
346
363
  });
347
364
 
348
- // The State file, written as part of the Claim and kept current from here on,
365
+ // The state file, written as part of the claim and kept current from here on,
349
366
  // so a Run that is killed mid-Ticket — or a human handed the Ticket — still
350
367
  // leaves the next Run something to resume. A resumed Ticket carries on from
351
368
  // what it had already reached.
352
369
  //
353
- // First of the two, because a Claim no State file names is the one thing this
370
+ // First of the two, because a claim no state file names is the one thing this
354
371
  // has to rule out: a crash between the writes then leaves a Ticket nobody has
355
372
  // claimed with state beside it, which is a released Ticket and resumes itself.
356
373
  const record = await ResumeRecord.claim(pipeline, {
@@ -365,7 +382,7 @@ async function takeTicket(
365
382
 
366
383
  // The claim is the first write on the board: it shows what the pipeline holds
367
384
  // before anything else can go wrong. A stranded Ticket is resumed in place,
368
- // wearing the Claim it never gave up — re-writing what is already there would
385
+ // wearing the claim it never gave up — re-writing what is already there would
369
386
  // only risk the Ticket on three tracker calls that change nothing.
370
387
  if (!stranded) {
371
388
  await tracker.assign(ticket, user);
@@ -400,8 +417,8 @@ async function takeTicket(
400
417
  // The pass behind a fix Stage logs beside the first one rather than over it.
401
418
  let logDir = stageLogDir(repoRoot, runId, ticket);
402
419
  // The unmet criteria the fix Stage was sent in for, and their evidence, which
403
- // the verify behind it is held to. Only this Run's: the State file keeps no
404
- // Verdict, so a retry a later Run resumes is graded without them.
420
+ // the verify behind it is held to. Only this Run's: the state file keeps no
421
+ // verdict, so a retry a later Run resumes is graded without them.
405
422
  let unmetBefore: string | undefined;
406
423
 
407
424
  // Declared out here because ticking the Acceptance Criteria it proved happens
@@ -430,7 +447,7 @@ async function takeTicket(
430
447
  // Where the branch is decides what the human is asked to do about it:
431
448
  // a branch that is checked out cannot simply be deleted, so the human
432
449
  // is sent to the worktree holding it instead. Nothing the pipeline left
433
- // is here — a Ticket it handed off keeps its State file and resumes
450
+ // is here — a Ticket it handed off keeps its state file and resumes
434
451
  // without ever reaching this — so the branch is a human's either way.
435
452
  const checkedOutAt = (await workspace.hasWorktree({ path: worktree, branch }))
436
453
  ? worktree
@@ -464,8 +481,8 @@ async function takeTicket(
464
481
  let commits: string[];
465
482
  let coAuthors: string[];
466
483
  let title: string;
467
- // Owed once, by a Ticket released over a failing Base branch, and inside
468
- // the passes rather than before them: a conflict it meets spends the Fix
484
+ // Owed once, by a Ticket released over a failing base branch, and inside
485
+ // the passes rather than before them: a conflict it meets spends the fix
469
486
  // budget as one at the Landing does.
470
487
  let rebaseOwed = resume?.rebaseFirst === true;
471
488
 
@@ -488,11 +505,11 @@ async function takeTicket(
488
505
  verdict = await verify(pipeline, issue, worktree, logDir, progress, notes, unmetBefore);
489
506
 
490
507
  point = "rebase";
491
- // The Landing, from here until the Base branch has been pulled: the
492
- // Ticket waits its turn, and the Base branch it rebases onto is then
508
+ // The Landing, from here until the base branch has been pulled: the
509
+ // Ticket waits its turn, and the base branch it rebases onto is then
493
510
  // the one its merge will land on.
494
511
  await landing.enter();
495
- // Up to the remote first: a Base branch the checkout holds behind it
512
+ // Up to the remote first: a base branch the checkout holds behind it
496
513
  // is a rebase that changes nothing and a pull request that conflicts,
497
514
  // which GitHub then runs no CI for. One that cannot be brought up is a
498
515
  // failure here, since rebasing onto it would be the same mistake.
@@ -512,7 +529,7 @@ async function takeTicket(
512
529
  progress,
513
530
  );
514
531
  // The resolution is code nothing has graded: the Checks passed on one
515
- // side of the conflict and CI on the other. The Verdict is not asked
532
+ // side of the conflict and CI on the other. The verdict is not asked
516
533
  // for again, because the conflict Stage is told to change no
517
534
  // behaviour the Acceptance Criteria are about.
518
535
  point = "checks";
@@ -610,13 +627,13 @@ async function takeTicket(
610
627
 
611
628
  // The Ticket is merged from here on, so nothing below may hand it off, and
612
629
  // it is still in the Landing: the pull below is the last of it.
613
- // The State file goes first: a merged Ticket must not look resumable to the
630
+ // The state file goes first: a merged Ticket must not look resumable to the
614
631
  // next Run, whatever else below fails — which is worth the Landing staying
615
632
  // shut for three writes nobody else is waiting on.
616
633
  try {
617
634
  await workspace.removeState(ticket);
618
635
  } catch (error) {
619
- log(`#${ticket} merged, but clearing its State file failed: ${(error as Error).message}`);
636
+ log(`#${ticket} merged, but clearing its state file failed: ${(error as Error).message}`);
620
637
  }
621
638
  try {
622
639
  await tickMetCriteria(tracker, ticket, verdict, log);
@@ -631,7 +648,7 @@ async function takeTicket(
631
648
  }
632
649
  try {
633
650
  await workspace.pullBase(baseBranch);
634
- // The pull ends the Landing: the next Ticket now rebases onto a Base branch
651
+ // The pull ends the Landing: the next Ticket now rebases onto a base branch
635
652
  // that already carries this one, and the cleanup below holds nobody up.
636
653
  landing.leave();
637
654
  await workspace.removeWorktree({ path: worktree, branch });
@@ -681,7 +698,7 @@ interface Resumable {
681
698
  /**
682
699
  * Why it cannot, when it cannot: this Host's copy of the branch has parted
683
700
  * from the remote one, or the worktree could not be made ready at all.
684
- * Either is a hand-off at setup, and the State stays.
701
+ * Either is a hand-off at setup, and the state stays.
685
702
  */
686
703
  refusal?: string;
687
704
  /** The worktree the branch is checked out in, for a refusal to send a human to. */
@@ -692,7 +709,7 @@ interface Resumable {
692
709
  * The state an earlier Run left for this Ticket, if a Run can still resume it,
693
710
  * with the worktree it resumes in made ready.
694
711
  *
695
- * The State file only names where the work is; where the work actually is, is
712
+ * The state file only names where the work is; where the work actually is, is
696
713
  * the Workspace's answer, and the branch on the remote is what it answers from
697
714
  * (ADR-0004). Any Host's Run pushes it each time a Stage commits, so a Host
698
715
  * with no worktree of the Ticket makes one from it, and one that still has a
@@ -713,7 +730,7 @@ async function resumable(
713
730
  if (state === undefined) return undefined;
714
731
  const ref = { path: worktree, branch: state.branch };
715
732
  // Caught here, because nothing is claimed yet: the refusal is raised once the
716
- // Claim is made, as a hand-off a human can see on the board.
733
+ // claim is made, as a hand-off a human can see on the board.
717
734
  let found: WorktreeFromRemote;
718
735
  let checkedOut: boolean;
719
736
  try {
@@ -738,7 +755,7 @@ async function resumable(
738
755
  pipeline.log?.(
739
756
  `#${ticket} was resumable, but ${state.branch} is neither in ${worktree} nor on the remote`,
740
757
  );
741
- // Logged and nothing more when it fails: the Claim writes this Ticket's State
758
+ // Logged and nothing more when it fails: the claim writes this Ticket's state
742
759
  // over it in a moment, from the top.
743
760
  try {
744
761
  await pipeline.workspace.removeState(ticket);
@@ -779,7 +796,7 @@ function describeParted(
779
796
  * How this Run came by the Ticket, for the one line it logs about it: resumed
780
797
  * from a recorded state, taken from the top, or claimed outright. A stranded
781
798
  * Ticket with nothing left to resume into is the middle one — it is started
782
- * again, but the Claim it is started under is the one it already had.
799
+ * again, but the claim it is started under is the one it already had.
783
800
  */
784
801
  function howItWasTaken(resume: TicketState | undefined, stranded: boolean): string {
785
802
  if (resume !== undefined) return `resumed from ${resume.state}`;
@@ -795,10 +812,10 @@ type Advance = Partial<
795
812
  >;
796
813
 
797
814
  /**
798
- * The State file a Ticket keeps, and the one place a Ticket writes it.
815
+ * The state file a Ticket keeps, and the one place a Ticket writes it.
799
816
  *
800
817
  * A Ticket is resumable for as long as its branch carries work worth resuming,
801
- * so the file is written as part of the Claim and rewritten whenever the Ticket
818
+ * so the file is written as part of the claim and rewritten whenever the Ticket
802
819
  * reaches something a later Run should not pay for again. The release is one
803
820
  * more such write rather than the only one, which is what makes a Run that was
804
821
  * killed recoverable too, and the hand-off is another.
@@ -820,12 +837,12 @@ class ResumeRecord {
820
837
  }
821
838
 
822
839
  /**
823
- * Record what the Claim is about to make true, and hand back the record that
840
+ * Record what the claim is about to make true, and hand back the record that
824
841
  * keeps it current.
825
842
  *
826
- * The one write that is allowed to fail the Ticket. It runs before the Claim,
843
+ * The one write that is allowed to fail the Ticket. It runs before the claim,
827
844
  * so a remote that will not take the file costs nothing at all: the Ticket ends
828
- * at setup with nothing claimed, where carrying on would put a Claim on the
845
+ * at setup with nothing claimed, where carrying on would put a claim on the
829
846
  * board that no later Run could ever resume — which is the state this record
830
847
  * exists to rule out.
831
848
  */
@@ -860,12 +877,12 @@ class ResumeRecord {
860
877
  }
861
878
 
862
879
  /**
863
- * The Run, the Version and the time belong to the write, not to what the
880
+ * The Run, the version and the time belong to the write, not to what the
864
881
  * Ticket reached: they say which pipeline left the file, so a Run that cannot
865
882
  * read one can still name what wrote it (ADR-0007).
866
883
  */
867
884
  private file(): TicketState {
868
- // Written only while it is owed, so a State file says nothing of a rebase
885
+ // Written only while it is owed, so a state file says nothing of a rebase
869
886
  // nobody has to do.
870
887
  const { rebaseFirst, ...reached } = this.reached;
871
888
  return {
@@ -913,8 +930,8 @@ async function passOver(
913
930
  * config names. Everything a Stage differs in is the prompt, where it runs and
914
931
  * where it logs; the limits come from one place so no Stage can quietly skip them.
915
932
  *
916
- * The credential is the Run's too, and what the Stage says it actually ran on
917
- * is checked here for the same reason: a Stage billed somewhere the Run did not
933
+ * What the Stages are billed to is the Run's too, and what the Stage says it
934
+ * actually ran on is checked here for the same reason: a Stage billed somewhere the Run did not
918
935
  * choose is named whichever Stage it was.
919
936
  */
920
937
  async function runStage(
@@ -952,8 +969,8 @@ async function runStage(
952
969
 
953
970
  /**
954
971
  * Add a Stage to what the Run was billed, and name it in the log now when its
955
- * `system/init` event reported another `apiKeySource` than the Run's credential
956
- * expects; the summary names it again at the end. A Stage that reported none,
972
+ * `system/init` event reported another `apiKeySource` than the Run's
973
+ * subscription or API key expects; the summary names it again at the end. A Stage that reported none,
957
974
  * one that never started, is not named: there is nothing it said to set
958
975
  * against the Run's choice. The log line carries no amount: the summary is the
959
976
  * only place one is printed.
@@ -1103,7 +1120,7 @@ async function commitCount(pipeline: Pipeline, branch: string): Promise<number>
1103
1120
  * Push the branch a Stage has just committed on, so the work outlives the Host
1104
1121
  * it was done on and a Run on any Host resumes from it (ADR-0004).
1105
1122
  *
1106
- * A push that does not land is logged and nothing more, as a State write that
1123
+ * A push that does not land is logged and nothing more, as a state write that
1107
1124
  * does not land is: the remote then holds an earlier tip of the same work, and
1108
1125
  * resuming from further back costs a Stage rather than being wrong. The push
1109
1126
  * the pull request needs is a different one, and fails the Ticket where it is.
@@ -1121,6 +1138,26 @@ async function pushCommitted(
1121
1138
  }
1122
1139
  }
1123
1140
 
1141
+ /**
1142
+ * The failure of a code Stage that finished with no new commit, carrying the
1143
+ * reason it gave, if any, for the hand-off to quote. Never one a fix Stage is
1144
+ * bought for: the implement Stage's has nothing to grade, and the fix Stage's
1145
+ * comes after the budget is spent.
1146
+ */
1147
+ function leftNoCommits(
1148
+ stage: "implement" | "fix",
1149
+ evidence: string,
1150
+ result: StageResult,
1151
+ ): TicketFailure {
1152
+ return new TicketFailure(
1153
+ stage,
1154
+ `the ${stage} Stage left no new commits on the branch`,
1155
+ evidence,
1156
+ undefined,
1157
+ parseNoCommitReason(result.result),
1158
+ );
1159
+ }
1160
+
1124
1161
  async function implement(
1125
1162
  pipeline: Pipeline,
1126
1163
  issue: Issue,
@@ -1145,9 +1182,9 @@ async function implement(
1145
1182
  cwd: worktree,
1146
1183
  logDir,
1147
1184
  jsonSchema: CODE_STAGE_JSON_SCHEMA,
1148
- // The title and the Notes are side channels, not the Stage's product: a
1149
- // session that emitted neither has implemented the Ticket exactly as it
1150
- // always did.
1185
+ // The title, the Notes and the reason for no commit are side channels,
1186
+ // not the Stage's product: a session that emitted none of them has
1187
+ // implemented the Ticket exactly as it always did.
1151
1188
  resultRequired: false,
1152
1189
  });
1153
1190
  await collectNotes(pipeline, issue.number, "implement", result, notes);
@@ -1164,28 +1201,26 @@ async function implement(
1164
1201
  // failure, not something to verify. A resumed Ticket's branch is not clean —
1165
1202
  // it carries what the Stage a Release stopped had committed — so this
1166
1203
  // asks the same question there: is there anything at all to grade. Whether it
1167
- // is enough is the Verdict's business, not this guard's.
1204
+ // is enough is the verdict's business, not this guard's. The hand-off quotes
1205
+ // why, where the Stage said.
1168
1206
  if (commits === 0) {
1169
1207
  await progress.record(stageRow("implement", result, "❌ no commits"));
1170
- throw new TicketFailure(
1171
- "implement",
1172
- "the implement Stage left no new commits on the branch",
1173
- );
1208
+ throw leftNoCommits("implement", "", result);
1174
1209
  }
1175
1210
 
1176
1211
  await progress.record(stageRow("implement", result, "✅ committed"));
1177
1212
  }
1178
1213
 
1179
1214
  /**
1180
- * Bring a Ticket released over a failing Base branch up to the Base branch
1215
+ * Bring a Ticket released over a failing base branch up to the base branch
1181
1216
  * before its Checks grade it, so a fix a human has landed there meanwhile
1182
1217
  * reaches the branch. Without it the Ticket would meet the same failure with
1183
1218
  * its budget unspent, and spend it.
1184
1219
  *
1185
- * The pull and the rebase go through the Landing, which is where the Base
1220
+ * The pull and the rebase go through the Landing, which is where the base
1186
1221
  * branch is brought up to the remote's and rebased onto (ADR-0005), and out of
1187
1222
  * it again at once: nothing is merged behind them. A conflict goes to the
1188
- * Conflict Stage as one at the Landing does, outside it, since the rebase
1223
+ * conflict Stage as one at the Landing does, outside it, since the rebase
1189
1224
  * there runs again before the pull request anyway. Left unresolved, the
1190
1225
  * branch would keep the merge-base that fails and be released again by every
1191
1226
  * Run that took it up.
@@ -1255,9 +1290,9 @@ async function runChecks(
1255
1290
  if (!result.ok) {
1256
1291
  const durationMs = Date.now() - startedAt;
1257
1292
  // Asked before the row is written, because the row is what differs: a
1258
- // Check the Base branch fails too is nothing the Ticket did.
1293
+ // Check the base branch fails too is nothing the Ticket did.
1259
1294
  await releaseIfTheBaseFails(pipeline, {
1260
- point: "checks",
1295
+ onBranch: { point: "checks", command, output: result.output, timedOut: result.timedOut },
1261
1296
  worktree,
1262
1297
  commands: [command],
1263
1298
  progress,
@@ -1289,7 +1324,7 @@ async function runChecks(
1289
1324
  }
1290
1325
 
1291
1326
  /**
1292
- * The first of `commands` the Base branch fails, at the commit the branch at
1327
+ * The first of `commands` the base branch fails, at the commit the branch at
1293
1328
  * `worktree` inherited from it, or nothing when it passes them all.
1294
1329
  *
1295
1330
  * Nothing, too, when the merge-base could not be graded at all: the Ticket is
@@ -1323,7 +1358,7 @@ async function inheritedFailure(
1323
1358
  }
1324
1359
 
1325
1360
  /**
1326
- * Release the Ticket when the Base branch fails one of `commands` too, with the
1361
+ * Release the Ticket when the base branch fails one of `commands` too, with the
1327
1362
  * row that says so; return when it does not, for the caller to charge the
1328
1363
  * failure to the Ticket as it always did.
1329
1364
  *
@@ -1333,13 +1368,14 @@ async function inheritedFailure(
1333
1368
  async function releaseIfTheBaseFails(
1334
1369
  pipeline: Pipeline,
1335
1370
  {
1336
- point,
1371
+ onBranch,
1337
1372
  worktree,
1338
1373
  commands,
1339
1374
  progress,
1340
1375
  durationMs,
1341
1376
  }: {
1342
- point: "checks" | "ci";
1377
+ /** How the branch failed, which is also where: its Checks, or CI. */
1378
+ onBranch: BranchFailure;
1343
1379
  worktree: string;
1344
1380
  commands: readonly string[];
1345
1381
  progress: Progress;
@@ -1350,11 +1386,14 @@ async function releaseIfTheBaseFails(
1350
1386
  const inherited = await inheritedFailure(pipeline, worktree, commands);
1351
1387
  if (inherited === undefined) return;
1352
1388
  await progress.record({
1353
- point,
1354
- outcome: `⏸ \`${inherited.command}\` fails on the Base branch`,
1389
+ point: onBranch.point,
1390
+ outcome: `⏸ \`${inherited.command}\` fails on the base branch`,
1355
1391
  durationMs,
1356
1392
  });
1357
- throw new Releasing(point, "implemented", "failing-base", undefined, inherited);
1393
+ throw new Releasing(onBranch.point, "implemented", "failing-base", undefined, {
1394
+ ...inherited,
1395
+ onBranch,
1396
+ });
1358
1397
  }
1359
1398
 
1360
1399
  /**
@@ -1376,7 +1415,7 @@ async function verify(
1376
1415
  logDir: string,
1377
1416
  progress: Progress,
1378
1417
  notes: RoutedNote[],
1379
- /** The unmet criteria and evidence of the Verdict a fix Stage was sent in for. */
1418
+ /** The unmet criteria and evidence of the verdict a fix Stage was sent in for. */
1380
1419
  unmetBefore: string | undefined,
1381
1420
  ): Promise<Verdict> {
1382
1421
  const stage = pipeline.config.stages.verify;
@@ -1396,13 +1435,14 @@ async function verify(
1396
1435
  });
1397
1436
 
1398
1437
  // Before anything else is done with the Stage at all, as the code Stages do
1399
- // it: a session that ran out of turns, or came back with a Verdict nothing
1438
+ // it: a session that ran out of turns, or came back with a verdict nothing
1400
1439
  // can be made of, still noticed whatever it noticed. The scratch work it
1401
1440
  // noticed it in is about to be discarded, so its Notes are all that is left —
1402
1441
  // and a worktree that will not discard them is no reason to lose them too.
1403
1442
  await collectNotes(pipeline, issue.number, "verify", result, notes);
1404
1443
 
1405
- // verify is allowed to write throwaway tests; none of them reach the PR.
1444
+ // verify is allowed to write throwaway tests; none of them reach the pull
1445
+ // request.
1406
1446
  await pipeline.workspace.discardChanges(worktree);
1407
1447
 
1408
1448
  if (!result.ok) throw await stageDidNotFinish(pipeline, progress, "verify", result);
@@ -1411,10 +1451,10 @@ async function verify(
1411
1451
  try {
1412
1452
  verdict = parseVerdict(result.result);
1413
1453
  } catch (error) {
1414
- await progress.record(stageRow("verify", result, "❌ no Verdict"));
1454
+ await progress.record(stageRow("verify", result, "❌ no verdict"));
1415
1455
  throw new TicketFailure(
1416
1456
  "verify",
1417
- "the verify Stage did not return a usable Verdict",
1457
+ "the verify Stage did not return a usable verdict",
1418
1458
  (error as Error).message,
1419
1459
  );
1420
1460
  }
@@ -1498,7 +1538,7 @@ async function fix(
1498
1538
  if (!result.ok) throw await stageDidNotFinish(pipeline, progress, "fix", result);
1499
1539
 
1500
1540
  // A session that came back clean mended nothing, whatever it says. Believing
1501
- // it costs the Ticket a whole second pass of the Checks, the Verdict and CI
1541
+ // it costs the Ticket a whole second pass of the Checks, the verdict and CI
1502
1542
  // over a branch nobody touched, which can only fail the way it just did — and
1503
1543
  // a progress row claiming the Stage committed. The budget is already spent,
1504
1544
  // so this ends the Ticket rather than buying another try.
@@ -1507,16 +1547,14 @@ async function fix(
1507
1547
  // changed: a session that squashed the branch shorter, or amended in place,
1508
1548
  // is read here as having committed nothing.
1509
1549
  //
1510
- // The hand-off carries the evidence the Stage was sent in with. Committing
1550
+ // The hand-off carries the evidence the Stage was sent in with, and the
1551
+ // reason the Stage gave for committing nothing where it gave one. Committing
1511
1552
  // nothing is also how a fix Stage hands back an unmet criterion only a human
1512
- // can settle, and the human then reads the question where it was asked.
1553
+ // can settle, and that reason is the one place it says which, and why: the
1554
+ // evidence it was sent in with need not ask the question at all.
1513
1555
  if (!grew) {
1514
1556
  await progress.record(stageRow("fix", result, "❌ no commits"));
1515
- throw new TicketFailure(
1516
- "fix",
1517
- "the fix Stage left no new commits on the branch",
1518
- failure.evidence,
1519
- );
1557
+ throw leftNoCommits("fix", failure.evidence, result);
1520
1558
  }
1521
1559
 
1522
1560
  await progress.record(stageRow("fix", result, "✅ committed"));
@@ -1654,7 +1692,7 @@ interface PullRequestSubject {
1654
1692
  *
1655
1693
  * A second pass comes back to a pull request that already exists: the push is
1656
1694
  * what GitHub re-runs its checks on, and the title and body are rewritten so
1657
- * the subject and the Verdict a human reads there are the ones that will reach
1695
+ * the subject and the verdict a human reads there are the ones that will reach
1658
1696
  * the base branch.
1659
1697
  *
1660
1698
  * One that already exists is also taken out of draft, because a Ticket resumed
@@ -1724,12 +1762,12 @@ async function requireGreenCi(
1724
1762
  // fix Stage, it leaves, and the Checks below take minutes nobody else
1725
1763
  // should wait behind.
1726
1764
  landing.leave();
1727
- // CI's own runs on the Base branch cannot say whether it fails there: a
1765
+ // CI's own runs on the base branch cannot say whether it fails there: a
1728
1766
  // workflow that runs only on pull requests leaves a squash commit with
1729
1767
  // none, and a failure the clock brings starts after its last green run.
1730
1768
  // So the merge-base is graded with the Checks, which CI runs too.
1731
1769
  await releaseIfTheBaseFails(pipeline, {
1732
- point: "ci",
1770
+ onBranch: { point: "ci", summary: outcome.summary, excerpt: outcome.excerpt },
1733
1771
  worktree,
1734
1772
  commands: pipeline.config.checks,
1735
1773
  progress,
@@ -1747,7 +1785,7 @@ async function requireGreenCi(
1747
1785
  `the pull request checks did not finish within ${pipeline.config.ciTimeoutMinutes} minutes`,
1748
1786
  );
1749
1787
  case "conflicting":
1750
- // The Landing keeps the Run's own Tickets from moving the Base branch
1788
+ // The Landing keeps the Run's own Tickets from moving the base branch
1751
1789
  // under a pull request, but not a human merging on GitHub meanwhile. A
1752
1790
  // fix Stage has nothing to act on, so no fix kind: a human takes it.
1753
1791
  await record("❌ conflicting");
@@ -1772,15 +1810,15 @@ interface Release {
1772
1810
  user: string;
1773
1811
  branch: string;
1774
1812
  stopped: Releasing;
1775
- /** The Ticket's State file, which the release brings up to date and leaves. */
1813
+ /** The Ticket's state file, which the release brings up to date and leaves. */
1776
1814
  record: ResumeRecord;
1777
- /** Whether the Fix budget was spent by a failure of the Ticket's own. */
1815
+ /** Whether the fix budget was spent by a failure of the Ticket's own. */
1778
1816
  fixUsed: boolean;
1779
1817
  notes: RoutedNote[];
1780
1818
  }
1781
1819
 
1782
1820
  /**
1783
- * Release the Ticket: undo the Claim and leave a State file behind.
1821
+ * Release the Ticket: undo the claim and leave a state file behind.
1784
1822
  *
1785
1823
  * The opposite of a hand-off, and deliberately quiet. Nothing about the Ticket
1786
1824
  * failed, nobody has to look at it, and the work already on its branch is worth
@@ -1795,9 +1833,9 @@ async function release(
1795
1833
  const { tracker, config } = pipeline;
1796
1834
  const ticket = issue.number;
1797
1835
 
1798
- // Brought up to date before the Claim comes off: a Ticket back on the Frontier
1836
+ // Brought up to date before the claim comes off: a Ticket back on the Frontier
1799
1837
  // whose state is out of date is one the next Run would redo Stages for. One
1800
- // released over a failing Base branch is rebased first when it comes back,
1838
+ // released over a failing base branch is rebased first when it comes back,
1801
1839
  // or it would meet the same failure.
1802
1840
  await record.advance({
1803
1841
  state: stopped.state,
@@ -1805,7 +1843,7 @@ async function release(
1805
1843
  ...(stopped.failingBase === undefined ? {} : { rebaseFirst: true }),
1806
1844
  });
1807
1845
  if (stopped.failingBase !== undefined) {
1808
- await noteFailingBase(pipeline, { issue, branch, stopped, failing: stopped.failingBase, notes });
1846
+ await noteFailingBase(pipeline, { issue, branch, failing: stopped.failingBase, notes });
1809
1847
  }
1810
1848
 
1811
1849
  // The claim, undone in the order it was made, so the assignee — which is what
@@ -1835,9 +1873,9 @@ async function release(
1835
1873
  }
1836
1874
 
1837
1875
  /**
1838
- * Tell triage the Base branch fails a Check, once this Run per merge-base
1876
+ * Tell triage the base branch fails a Check, once this Run per merge-base
1839
1877
  * commit however many Tickets it releases: the pipeline's own Note, on the
1840
- * standing Notes issue, since the defect is the Base branch's and no Ticket's.
1878
+ * standing Notes issue, since the defect is the base branch's and no Ticket's.
1841
1879
  *
1842
1880
  * Logged and nothing more when it cannot be posted, as a Stage's Note is: the
1843
1881
  * Release is what the Ticket is owed, and the next Ticket released over the
@@ -1848,14 +1886,12 @@ async function noteFailingBase(
1848
1886
  {
1849
1887
  issue,
1850
1888
  branch,
1851
- stopped,
1852
1889
  failing,
1853
1890
  notes,
1854
1891
  }: {
1855
1892
  issue: Issue;
1856
1893
  branch: string;
1857
- stopped: Releasing;
1858
- failing: FailingBase;
1894
+ failing: InheritedFailure;
1859
1895
  notes: RoutedNote[];
1860
1896
  },
1861
1897
  ): Promise<void> {
@@ -1869,7 +1905,6 @@ async function noteFailingBase(
1869
1905
  number,
1870
1906
  failingBaseNote({
1871
1907
  origin,
1872
- point: stopped.point === "ci" ? "ci" : "checks",
1873
1908
  baseBranch: pipeline.baseBranch,
1874
1909
  branch,
1875
1910
  ...failing,
@@ -1911,7 +1946,7 @@ interface HandOff {
1911
1946
  /** Where the work is, absent when the Ticket failed before it had a worktree. */
1912
1947
  worktree?: HandOffWorktree;
1913
1948
  /**
1914
- * Whether the State stays for a later Run to resume from: what the branch
1949
+ * Whether the state stays for a later Run to resume from: what the branch
1915
1950
  * carries is the pipeline's, whether or not this Run may push it.
1916
1951
  */
1917
1952
  keepsState: boolean;
@@ -1919,38 +1954,40 @@ interface HandOff {
1919
1954
  failure: TicketFailure;
1920
1955
  /** Whether the Ticket's fix budget had already been spent when this failure came. */
1921
1956
  fixUsed: boolean;
1922
- /** The Ticket's State file, which the hand-off either leaves current or removes. */
1957
+ /** The Ticket's state file, which the hand-off either leaves current or removes. */
1923
1958
  record: ResumeRecord;
1924
1959
  notes: RoutedNote[];
1925
1960
  }
1926
1961
 
1927
1962
  /**
1928
- * Hand the Ticket to a human: a draft PR to review, a comment naming where the
1929
- * work is, and the labels a human filters on. The branch, the worktree and the
1930
- * State file stay put, so a human who relabels the Ticket `ready-for-agent`
1931
- * hands it back and the next Run carries on from what it reached. The Stages'
1932
- * transcripts go up beside the State, since the Host they were written on may
1933
- * be gone by the time a human looks, and the comment says where they and the
1934
- * branch are. The draft PR's body says where they are too, once they are
1935
- * kept: a draft is opened first, because the State records it, and one that
1936
- * was already open is rewritten, since its body is an earlier Run's.
1963
+ * Hand the Ticket to a human: a draft pull request to review, a comment naming
1964
+ * where the work is, and the labels a human filters on. The branch, the
1965
+ * worktree and the state file stay put, so a human who relabels the Ticket
1966
+ * `ready-for-agent` hands it back and the next Run carries on from what it
1967
+ * reached. The Stages' transcripts go up beside the state, since the Host they
1968
+ * were written on may be gone by the time a human looks, and the comment says
1969
+ * where they and the branch are. The draft pull request's body says where they
1970
+ * are too, once they are kept: a draft is opened first, because the state
1971
+ * records it, and one that was already open is rewritten, since its body is an
1972
+ * earlier Run's.
1937
1973
  *
1938
1974
  * A Ticket handed over before its worktree was created has none: nothing was
1939
- * branched, so there is no directory to name and nothing to push a draft PR out
1940
- * of. Both are left out rather than written as a path that is not there and a
1941
- * push that fails.
1975
+ * branched, so there is no directory to name and nothing to push a draft pull
1976
+ * request out of. Both are left out rather than written as a path that is not
1977
+ * there and a push that fails.
1942
1978
  *
1943
1979
  * Where a human is sent and what the pipeline pushes are two different facts. A
1944
1980
  * Ticket refused at setup over a branch still checked out somewhere names that
1945
1981
  * worktree and stops there: the work in it is a human's, and pushing it or
1946
- * opening a PR that says `Closes #<n>` over it would claim it for this Run.
1982
+ * opening a pull request that says `Closes #<n>` over it would claim it for
1983
+ * this Run.
1947
1984
  *
1948
- * The same fact mostly decides the State file. A worktree this Run may push out
1985
+ * The same fact mostly decides the state file. A worktree this Run may push out
1949
1986
  * of is one a Stage of it worked in, and what it left is the pipeline's to
1950
1987
  * resume; a branch in the way at setup leaves nothing of the pipeline's behind,
1951
1988
  * and a file kept over it would let a later Run resume into a human's work and
1952
1989
  * run an implement Stage over it — which is what refusing at setup exists to
1953
- * prevent. The one worktree this Run may not push out of whose State stays is
1990
+ * prevent. The one worktree this Run may not push out of whose state stays is
1954
1991
  * one parted from the remote branch: both copies are the pipeline's, and
1955
1992
  * pushing either over the other is the choice the human is handed.
1956
1993
  */
@@ -1974,14 +2011,15 @@ async function handOff(
1974
2011
 
1975
2012
  // Nothing of this Run's is on the branch, so nothing may leave the Ticket
1976
2013
  // looking resumable: the next Run must not implement over what a human holds.
1977
- // Wrapped because the hand-off itself — the draft PR, the comment, the labels
1978
- // — is what a human is waiting for, and no file is worth losing it over.
2014
+ // Wrapped because the hand-off itself — the draft pull request, the comment,
2015
+ // the labels — is what a human is waiting for, and no file is worth losing it
2016
+ // over.
1979
2017
  if (!keepsState) {
1980
2018
  try {
1981
2019
  await workspace.removeState(ticket);
1982
2020
  } catch (error) {
1983
2021
  pipeline.log?.(
1984
- `#${ticket} handed off, but clearing its State file failed: ${(error as Error).message}`,
2022
+ `#${ticket} handed off, but clearing its state file failed: ${(error as Error).message}`,
1985
2023
  );
1986
2024
  }
1987
2025
  }
@@ -1998,7 +2036,8 @@ async function handOff(
1998
2036
  if (pullRequest !== undefined) {
1999
2037
  await tracker.convertPullRequestToDraft(pullRequest);
2000
2038
  } else if (worktree?.pushable === true) {
2001
- // A draft PR is worth trying for, but never worth losing the relabel over.
2039
+ // A draft pull request is worth trying for, but never worth losing the
2040
+ // relabel over.
2002
2041
  try {
2003
2042
  await workspace.push(worktree.path, branch);
2004
2043
  const pr = await tracker.createPullRequest({
@@ -2015,7 +2054,7 @@ async function handOff(
2015
2054
  pullRequest = pr.number;
2016
2055
  drafted = true;
2017
2056
  } catch (error) {
2018
- pipeline.log?.(`#${ticket} could not open a draft PR: ${(error as Error).message}`);
2057
+ pipeline.log?.(`#${ticket} could not open a draft pull request: ${(error as Error).message}`);
2019
2058
  }
2020
2059
  }
2021
2060
 
@@ -2023,17 +2062,17 @@ async function handOff(
2023
2062
  // Written after the draft pull request, because that pull request is part of
2024
2063
  // what a resuming Run must not open a second one beside.
2025
2064
  //
2026
- // The Fix budget goes back unspent: the Ticket only comes back through a
2065
+ // The fix budget goes back unspent: the Ticket only comes back through a
2027
2066
  // human's hands, and whatever they did to it is what the fresh budget is
2028
2067
  // for. Nothing is lost by it — the hand-off comment says the budget was
2029
- // spent, and the Claim only marks that comment as history.
2068
+ // spent, and the claim only marks that comment as history.
2030
2069
  await record.advance({
2031
2070
  fixUsed: false,
2032
2071
  ...(pullRequest === undefined ? {} : { pullRequest }),
2033
2072
  });
2034
2073
  }
2035
- // Only beside a State that stays, because they go when it does, and after
2036
- // it, so the State they sit beside is the one a resuming Run reads.
2074
+ // Only beside a state that stays, because they go when it does, and after
2075
+ // it, so the state they sit beside is the one a resuming Run reads.
2037
2076
  const transcripts = keepsState ? await keepTranscripts(pipeline, ticket) : undefined;
2038
2077
  // A draft this hand-off opened went up before anything was kept, and one it
2039
2078
  // converted still carries an earlier body, so either learns where only now.
@@ -2064,6 +2103,7 @@ async function handOff(
2064
2103
  ...(worktree === undefined ? {} : { worktree: worktree.path }),
2065
2104
  ...(transcripts === undefined ? {} : { transcripts }),
2066
2105
  evidence: failure.evidence,
2106
+ ...(failure.reason === undefined ? {} : { reason: failure.reason }),
2067
2107
  fixUsed,
2068
2108
  ...(pullRequest === undefined ? {} : { pullRequest }),
2069
2109
  }),