ticket-runner 0.6.3 → 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 (49) 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 +49 -5
  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 +7 -6
  16. package/src/conventions.ts +23 -20
  17. package/src/credential.ts +92 -7
  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 +194 -144
  31. package/src/ports/agent-runner.ts +21 -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 +74 -25
  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 +72 -10
  41. package/src/staleness.ts +14 -14
  42. package/src/start.ts +20 -15
  43. package/src/stranded.ts +19 -19
  44. package/src/templates.ts +191 -73
  45. package/src/timer.ts +25 -0
  46. package/src/title.ts +45 -9
  47. package/src/verdict.ts +7 -7
  48. package/src/version-number.ts +13 -13
  49. package/src/version-pr.ts +12 -12
@@ -1,10 +1,11 @@
1
1
  import { branchName, worktreePath } from "./branch.js";
2
2
  import type { Config } from "./config.js";
3
3
  import {
4
+ type Billing,
4
5
  CREDENTIAL_WORDS,
5
6
  type Credential,
6
- type StrayStage,
7
7
  expectedKeySource,
8
+ recordStage,
8
9
  } from "./credential.js";
9
10
  import { tickMetCriteria } from "./criteria.js";
10
11
  import type { BaseBranchChecks, FailingBase } from "./failing-base.js";
@@ -46,6 +47,7 @@ import {
46
47
  import { retryLogDir, stageLogDir } from "./run-log.js";
47
48
  import { holdsClaim } from "./stranded.js";
48
49
  import {
50
+ type BranchFailure,
49
51
  RELEASE_WORDS,
50
52
  releaseWords,
51
53
  draftPullRequestBody,
@@ -57,7 +59,13 @@ import {
57
59
  pullRequestBody,
58
60
  squashCommit,
59
61
  } from "./templates.js";
60
- import { CODE_STAGE_JSON_SCHEMA, parseTitle, pullRequestTitle } from "./title.js";
62
+ import type { StartTimer } from "./timer.js";
63
+ import {
64
+ CODE_STAGE_JSON_SCHEMA,
65
+ parseNoCommitReason,
66
+ parseTitle,
67
+ pullRequestTitle,
68
+ } from "./title.js";
61
69
  import {
62
70
  type Verdict,
63
71
  VERDICT_JSON_SCHEMA,
@@ -102,7 +110,7 @@ export type TicketOutcome =
102
110
  * told. Absent for an API failure, which says nothing of when it ends.
103
111
  */
104
112
  limitResetsAt?: string;
105
- /** 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. */
106
114
  failingBase?: { commit: string; command: string };
107
115
  notes: RoutedNote[];
108
116
  }
@@ -123,7 +131,7 @@ export interface Pipeline {
123
131
  repoRoot: string;
124
132
  runId: string;
125
133
  /**
126
- * 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
127
135
  * the Run writes (ADR-0007). A string, never a lookup: nothing here reads
128
136
  * `package.json` or runs git, so every stamp of one Run is the same string.
129
137
  */
@@ -139,11 +147,11 @@ export interface Pipeline {
139
147
  */
140
148
  credential: Credential;
141
149
  /**
142
- * Every Stage of this Run that said it ran on something other than
143
- * {@link credential}, in the order they came back, shared by every Ticket so
144
- * the Run summary can name them all.
150
+ * What every Stage of this Run said it was billed, shared by every Ticket so
151
+ * the Run summary can name each Stage that ran on something other than
152
+ * {@link credential}, and say what the Run spent.
145
153
  */
146
- strayStages: StrayStage[];
154
+ billing: Billing;
147
155
  /**
148
156
  * The branch every Ticket of this Run branches from, rebases onto, merges
149
157
  * into and pulls, resolved once before the Run started
@@ -153,7 +161,7 @@ export interface Pipeline {
153
161
  /**
154
162
  * The Run's Landing, made once before the first Ticket and shared by every
155
163
  * Ticket it drives: only one of them is between its rebase and the pull of
156
- * the Base branch after its merge at a time (ADR-0005).
164
+ * the base branch after its merge at a time (ADR-0005).
157
165
  */
158
166
  landing: Landing;
159
167
  /**
@@ -163,9 +171,9 @@ export interface Pipeline {
163
171
  */
164
172
  standingNotes: StandingNotes;
165
173
  /**
166
- * 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
167
175
  * shared by every Ticket: the Tickets that fail together over one broken
168
- * 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.
169
177
  */
170
178
  baseChecks: BaseBranchChecks;
171
179
  /**
@@ -175,6 +183,12 @@ export interface Pipeline {
175
183
  * there is a Stage told to exercise it through its tests and fakes.
176
184
  */
177
185
  selfHosted: boolean;
186
+ /**
187
+ * How the Run waits between its looks at the Frontier while a Lane is free
188
+ * and another busy: the real clock, unless a test hands it one it moves
189
+ * itself. Never the interval, which is fixed.
190
+ */
191
+ startTimer?: StartTimer;
178
192
  log?: (line: string) => void;
179
193
  }
180
194
 
@@ -182,6 +196,10 @@ export interface Pipeline {
182
196
  * A failure that ends the Ticket, unless the fix budget can still buy it a
183
197
  * second try. `kind` is set on exactly the failures a fix Stage is given:
184
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.
185
203
  */
186
204
  class TicketFailure extends Error {
187
205
  constructor(
@@ -189,6 +207,7 @@ class TicketFailure extends Error {
189
207
  readonly summary: string,
190
208
  readonly evidence: string = "",
191
209
  readonly kind?: FailureKind,
210
+ readonly reason?: string,
192
211
  ) {
193
212
  super(summary);
194
213
  }
@@ -198,7 +217,7 @@ class TicketFailure extends Error {
198
217
  * What stops a Ticket that says nothing about it: the rate limit, a transient
199
218
  * API failure — the API overloaded, broken or silent on its own side after the
200
219
  * CLI had already retried it — the API key of an `--api-key` Run out of credit
201
- * 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
202
221
  * the Ticket's branch failed.
203
222
  */
204
223
  export type ReleaseCause = StageReleaseCause | "failing-base";
@@ -218,7 +237,7 @@ function releaseCause(result: StageResult): StageReleaseCause | undefined {
218
237
  * A Stage something other than the Ticket stopped, on its way to a Release.
219
238
  *
220
239
  * The Stage failures that say nothing about the Ticket are the ones that
221
- * 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
222
241
  * file is left for the next Run to resume from (ADR-0004). It is not a
223
242
  * {@link TicketFailure} because every path that handles one of those would
224
243
  * either hand the Ticket off or buy it a fix Stage, and this is neither.
@@ -230,13 +249,20 @@ class Releasing extends Error {
230
249
  readonly state: ReachedState,
231
250
  readonly reason: ReleaseCause,
232
251
  readonly limitResetsAt?: string,
233
- /** The Check the Base branch fails too, for a Release over it. */
234
- readonly failingBase?: FailingBase,
252
+ /** The Check the base branch fails too, for a Release over it. */
253
+ readonly failingBase?: InheritedFailure,
235
254
  ) {
236
255
  super(`the ${point} Stage was stopped · ${RELEASE_WORDS[reason]}`);
237
256
  }
238
257
  }
239
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
+
240
266
  /** An error the pipeline did not raise itself, blamed on the step it was on. */
241
267
  function asTicketFailure(error: unknown, point: FailurePoint): TicketFailure {
242
268
  return error instanceof TicketFailure
@@ -248,13 +274,12 @@ function asTicketFailure(error: unknown, point: FailurePoint): TicketFailure {
248
274
  * Take one Ticket from claimed to merged, hand it to a human, or pass it over.
249
275
  *
250
276
  * The happy path is: guards → claim → worktree and branch → implement Stage →
251
- * Checks → verify Stage → rebase → PR → CI → squash merge → cleanup. Work left
252
- * uncommitted, a failing Check, an unmet criterion, a red CI or a rebase
253
- * conflict the conflict Stage could not resolve spends the Ticket's fix budget
254
- * and starts again at the Checks; every other failure, and every second
255
- * failure, ends in a hand-off.
256
- * Nothing ends in a merge that has not been through a green pass of the whole
257
- * 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.
258
283
  *
259
284
  * A Stage the subscription rate limit or a transient API failure stopped ends
260
285
  * none of that: the Ticket is released, and a Run started once the limit has
@@ -269,9 +294,9 @@ function asTicketFailure(error: unknown, point: FailurePoint): TicketFailure {
269
294
  * untriaged from its Frontier, but the Ticket may have changed hands since the
270
295
  * listing, so the guards ask again.
271
296
  *
272
- * From the pull of the Base branch before the rebase to the pull after the
273
- * merge the Ticket holds the Run's Landing, so no other Ticket of the same Run moves the Base
274
- * 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).
275
300
  */
276
301
  export async function processTicket(
277
302
  pipeline: Pipeline,
@@ -310,7 +335,7 @@ async function takeTicket(
310
335
 
311
336
  // What an earlier Run left behind, read before the guards because it decides
312
337
  // one of them: a Ticket this pipeline still holds with state recorded for it is
313
- // 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
314
339
  // came back — and the refusals must not read it as somebody else's.
315
340
  const recorded = await workspace.readState(ticket);
316
341
  const stranded = recorded !== undefined && holdsClaim(issue, user, config.labels.inProgress);
@@ -337,12 +362,12 @@ async function takeTicket(
337
362
  log,
338
363
  });
339
364
 
340
- // 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,
341
366
  // so a Run that is killed mid-Ticket — or a human handed the Ticket — still
342
367
  // leaves the next Run something to resume. A resumed Ticket carries on from
343
368
  // what it had already reached.
344
369
  //
345
- // 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
346
371
  // has to rule out: a crash between the writes then leaves a Ticket nobody has
347
372
  // claimed with state beside it, which is a released Ticket and resumes itself.
348
373
  const record = await ResumeRecord.claim(pipeline, {
@@ -357,7 +382,7 @@ async function takeTicket(
357
382
 
358
383
  // The claim is the first write on the board: it shows what the pipeline holds
359
384
  // before anything else can go wrong. A stranded Ticket is resumed in place,
360
- // 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
361
386
  // only risk the Ticket on three tracker calls that change nothing.
362
387
  if (!stranded) {
363
388
  await tracker.assign(ticket, user);
@@ -392,8 +417,8 @@ async function takeTicket(
392
417
  // The pass behind a fix Stage logs beside the first one rather than over it.
393
418
  let logDir = stageLogDir(repoRoot, runId, ticket);
394
419
  // The unmet criteria the fix Stage was sent in for, and their evidence, which
395
- // the verify behind it is held to. Only this Run's: the State file keeps no
396
- // 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.
397
422
  let unmetBefore: string | undefined;
398
423
 
399
424
  // Declared out here because ticking the Acceptance Criteria it proved happens
@@ -422,7 +447,7 @@ async function takeTicket(
422
447
  // Where the branch is decides what the human is asked to do about it:
423
448
  // a branch that is checked out cannot simply be deleted, so the human
424
449
  // is sent to the worktree holding it instead. Nothing the pipeline left
425
- // 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
426
451
  // without ever reaching this — so the branch is a human's either way.
427
452
  const checkedOutAt = (await workspace.hasWorktree({ path: worktree, branch }))
428
453
  ? worktree
@@ -456,8 +481,8 @@ async function takeTicket(
456
481
  let commits: string[];
457
482
  let coAuthors: string[];
458
483
  let title: string;
459
- // Owed once, by a Ticket released over a failing Base branch, and inside
460
- // 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
461
486
  // budget as one at the Landing does.
462
487
  let rebaseOwed = resume?.rebaseFirst === true;
463
488
 
@@ -480,11 +505,11 @@ async function takeTicket(
480
505
  verdict = await verify(pipeline, issue, worktree, logDir, progress, notes, unmetBefore);
481
506
 
482
507
  point = "rebase";
483
- // The Landing, from here until the Base branch has been pulled: the
484
- // 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
485
510
  // the one its merge will land on.
486
511
  await landing.enter();
487
- // 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
488
513
  // is a rebase that changes nothing and a pull request that conflicts,
489
514
  // which GitHub then runs no CI for. One that cannot be brought up is a
490
515
  // failure here, since rebasing onto it would be the same mistake.
@@ -504,7 +529,7 @@ async function takeTicket(
504
529
  progress,
505
530
  );
506
531
  // The resolution is code nothing has graded: the Checks passed on one
507
- // 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
508
533
  // for again, because the conflict Stage is told to change no
509
534
  // behaviour the Acceptance Criteria are about.
510
535
  point = "checks";
@@ -602,13 +627,13 @@ async function takeTicket(
602
627
 
603
628
  // The Ticket is merged from here on, so nothing below may hand it off, and
604
629
  // it is still in the Landing: the pull below is the last of it.
605
- // 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
606
631
  // next Run, whatever else below fails — which is worth the Landing staying
607
632
  // shut for three writes nobody else is waiting on.
608
633
  try {
609
634
  await workspace.removeState(ticket);
610
635
  } catch (error) {
611
- 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}`);
612
637
  }
613
638
  try {
614
639
  await tickMetCriteria(tracker, ticket, verdict, log);
@@ -623,7 +648,7 @@ async function takeTicket(
623
648
  }
624
649
  try {
625
650
  await workspace.pullBase(baseBranch);
626
- // 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
627
652
  // that already carries this one, and the cleanup below holds nobody up.
628
653
  landing.leave();
629
654
  await workspace.removeWorktree({ path: worktree, branch });
@@ -673,7 +698,7 @@ interface Resumable {
673
698
  /**
674
699
  * Why it cannot, when it cannot: this Host's copy of the branch has parted
675
700
  * from the remote one, or the worktree could not be made ready at all.
676
- * Either is a hand-off at setup, and the State stays.
701
+ * Either is a hand-off at setup, and the state stays.
677
702
  */
678
703
  refusal?: string;
679
704
  /** The worktree the branch is checked out in, for a refusal to send a human to. */
@@ -684,7 +709,7 @@ interface Resumable {
684
709
  * The state an earlier Run left for this Ticket, if a Run can still resume it,
685
710
  * with the worktree it resumes in made ready.
686
711
  *
687
- * 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
688
713
  * the Workspace's answer, and the branch on the remote is what it answers from
689
714
  * (ADR-0004). Any Host's Run pushes it each time a Stage commits, so a Host
690
715
  * with no worktree of the Ticket makes one from it, and one that still has a
@@ -705,7 +730,7 @@ async function resumable(
705
730
  if (state === undefined) return undefined;
706
731
  const ref = { path: worktree, branch: state.branch };
707
732
  // Caught here, because nothing is claimed yet: the refusal is raised once the
708
- // 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.
709
734
  let found: WorktreeFromRemote;
710
735
  let checkedOut: boolean;
711
736
  try {
@@ -730,7 +755,7 @@ async function resumable(
730
755
  pipeline.log?.(
731
756
  `#${ticket} was resumable, but ${state.branch} is neither in ${worktree} nor on the remote`,
732
757
  );
733
- // 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
734
759
  // over it in a moment, from the top.
735
760
  try {
736
761
  await pipeline.workspace.removeState(ticket);
@@ -771,7 +796,7 @@ function describeParted(
771
796
  * How this Run came by the Ticket, for the one line it logs about it: resumed
772
797
  * from a recorded state, taken from the top, or claimed outright. A stranded
773
798
  * Ticket with nothing left to resume into is the middle one — it is started
774
- * 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.
775
800
  */
776
801
  function howItWasTaken(resume: TicketState | undefined, stranded: boolean): string {
777
802
  if (resume !== undefined) return `resumed from ${resume.state}`;
@@ -787,10 +812,10 @@ type Advance = Partial<
787
812
  >;
788
813
 
789
814
  /**
790
- * 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.
791
816
  *
792
817
  * A Ticket is resumable for as long as its branch carries work worth resuming,
793
- * 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
794
819
  * reaches something a later Run should not pay for again. The release is one
795
820
  * more such write rather than the only one, which is what makes a Run that was
796
821
  * killed recoverable too, and the hand-off is another.
@@ -812,12 +837,12 @@ class ResumeRecord {
812
837
  }
813
838
 
814
839
  /**
815
- * 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
816
841
  * keeps it current.
817
842
  *
818
- * 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,
819
844
  * so a remote that will not take the file costs nothing at all: the Ticket ends
820
- * 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
821
846
  * board that no later Run could ever resume — which is the state this record
822
847
  * exists to rule out.
823
848
  */
@@ -852,12 +877,12 @@ class ResumeRecord {
852
877
  }
853
878
 
854
879
  /**
855
- * 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
856
881
  * Ticket reached: they say which pipeline left the file, so a Run that cannot
857
882
  * read one can still name what wrote it (ADR-0007).
858
883
  */
859
884
  private file(): TicketState {
860
- // 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
861
886
  // nobody has to do.
862
887
  const { rebaseFirst, ...reached } = this.reached;
863
888
  return {
@@ -905,8 +930,8 @@ async function passOver(
905
930
  * config names. Everything a Stage differs in is the prompt, where it runs and
906
931
  * where it logs; the limits come from one place so no Stage can quietly skip them.
907
932
  *
908
- * The credential is the Run's too, and what the Stage says it actually ran on
909
- * 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
910
935
  * choose is named whichever Stage it was.
911
936
  */
912
937
  async function runStage(
@@ -938,29 +963,29 @@ async function runStage(
938
963
  ? {}
939
964
  : { resultRequired: request.resultRequired }),
940
965
  });
941
- noteStrayCredential(pipeline, request.ticket, stage, result);
966
+ noteBilling(pipeline, request.ticket, stage, result);
942
967
  return result;
943
968
  }
944
969
 
945
970
  /**
946
- * Name a Stage whose `system/init` event reported another `apiKeySource` than
947
- * the Run's credential expects, in the log now and in the summary at the end.
948
- * A Stage that reported none, one that never started, is not named: there is
949
- * nothing it said to set against the Run's choice.
971
+ * Add a Stage to what the Run was billed, and name it in the log now when its
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,
974
+ * one that never started, is not named: there is nothing it said to set
975
+ * against the Run's choice. The log line carries no amount: the summary is the
976
+ * only place one is printed.
950
977
  */
951
- function noteStrayCredential(
978
+ function noteBilling(
952
979
  pipeline: Pipeline,
953
980
  ticket: number,
954
981
  stage: StageName,
955
982
  result: StageResult,
956
983
  ): void {
957
- const { apiKeySource } = result;
958
- const expected = expectedKeySource(pipeline.credential);
959
- if (apiKeySource === undefined || apiKeySource === expected) return;
960
- pipeline.strayStages.push({ ticket, stage, apiKeySource });
984
+ const stray = recordStage(pipeline.billing, pipeline.credential, ticket, stage, result);
985
+ if (stray === undefined) return;
961
986
  pipeline.log?.(
962
- `#${ticket} ${stage} ran on apiKeySource ${apiKeySource}, ` +
963
- `not the ${CREDENTIAL_WORDS[pipeline.credential]} (${expected})`,
987
+ `#${ticket} ${stage} ran on apiKeySource ${stray.apiKeySource}, ` +
988
+ `not the ${CREDENTIAL_WORDS[pipeline.credential]} (${expectedKeySource(pipeline.credential)})`,
964
989
  );
965
990
  }
966
991
 
@@ -1095,7 +1120,7 @@ async function commitCount(pipeline: Pipeline, branch: string): Promise<number>
1095
1120
  * Push the branch a Stage has just committed on, so the work outlives the Host
1096
1121
  * it was done on and a Run on any Host resumes from it (ADR-0004).
1097
1122
  *
1098
- * 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
1099
1124
  * does not land is: the remote then holds an earlier tip of the same work, and
1100
1125
  * resuming from further back costs a Stage rather than being wrong. The push
1101
1126
  * the pull request needs is a different one, and fails the Ticket where it is.
@@ -1113,6 +1138,26 @@ async function pushCommitted(
1113
1138
  }
1114
1139
  }
1115
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
+
1116
1161
  async function implement(
1117
1162
  pipeline: Pipeline,
1118
1163
  issue: Issue,
@@ -1137,9 +1182,9 @@ async function implement(
1137
1182
  cwd: worktree,
1138
1183
  logDir,
1139
1184
  jsonSchema: CODE_STAGE_JSON_SCHEMA,
1140
- // The title and the Notes are side channels, not the Stage's product: a
1141
- // session that emitted neither has implemented the Ticket exactly as it
1142
- // 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.
1143
1188
  resultRequired: false,
1144
1189
  });
1145
1190
  await collectNotes(pipeline, issue.number, "implement", result, notes);
@@ -1156,28 +1201,26 @@ async function implement(
1156
1201
  // failure, not something to verify. A resumed Ticket's branch is not clean —
1157
1202
  // it carries what the Stage a Release stopped had committed — so this
1158
1203
  // asks the same question there: is there anything at all to grade. Whether it
1159
- // 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.
1160
1206
  if (commits === 0) {
1161
1207
  await progress.record(stageRow("implement", result, "❌ no commits"));
1162
- throw new TicketFailure(
1163
- "implement",
1164
- "the implement Stage left no new commits on the branch",
1165
- );
1208
+ throw leftNoCommits("implement", "", result);
1166
1209
  }
1167
1210
 
1168
1211
  await progress.record(stageRow("implement", result, "✅ committed"));
1169
1212
  }
1170
1213
 
1171
1214
  /**
1172
- * 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
1173
1216
  * before its Checks grade it, so a fix a human has landed there meanwhile
1174
1217
  * reaches the branch. Without it the Ticket would meet the same failure with
1175
1218
  * its budget unspent, and spend it.
1176
1219
  *
1177
- * 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
1178
1221
  * branch is brought up to the remote's and rebased onto (ADR-0005), and out of
1179
1222
  * it again at once: nothing is merged behind them. A conflict goes to the
1180
- * 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
1181
1224
  * there runs again before the pull request anyway. Left unresolved, the
1182
1225
  * branch would keep the merge-base that fails and be released again by every
1183
1226
  * Run that took it up.
@@ -1247,9 +1290,9 @@ async function runChecks(
1247
1290
  if (!result.ok) {
1248
1291
  const durationMs = Date.now() - startedAt;
1249
1292
  // Asked before the row is written, because the row is what differs: a
1250
- // Check the Base branch fails too is nothing the Ticket did.
1293
+ // Check the base branch fails too is nothing the Ticket did.
1251
1294
  await releaseIfTheBaseFails(pipeline, {
1252
- point: "checks",
1295
+ onBranch: { point: "checks", command, output: result.output, timedOut: result.timedOut },
1253
1296
  worktree,
1254
1297
  commands: [command],
1255
1298
  progress,
@@ -1271,15 +1314,17 @@ async function runChecks(
1271
1314
  );
1272
1315
  }
1273
1316
  }
1317
+ // No command is not a pass: only `gates.checks` off lets a Run start with
1318
+ // none, and the row says so as the ci row does for a pull request with none.
1274
1319
  await progress.record({
1275
1320
  point: "checks",
1276
- outcome: "✅ passed",
1321
+ outcome: pipeline.config.checks.length === 0 ? "⚠️ no checks" : "✅ passed",
1277
1322
  durationMs: Date.now() - startedAt,
1278
1323
  });
1279
1324
  }
1280
1325
 
1281
1326
  /**
1282
- * 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
1283
1328
  * `worktree` inherited from it, or nothing when it passes them all.
1284
1329
  *
1285
1330
  * Nothing, too, when the merge-base could not be graded at all: the Ticket is
@@ -1313,7 +1358,7 @@ async function inheritedFailure(
1313
1358
  }
1314
1359
 
1315
1360
  /**
1316
- * 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
1317
1362
  * row that says so; return when it does not, for the caller to charge the
1318
1363
  * failure to the Ticket as it always did.
1319
1364
  *
@@ -1323,13 +1368,14 @@ async function inheritedFailure(
1323
1368
  async function releaseIfTheBaseFails(
1324
1369
  pipeline: Pipeline,
1325
1370
  {
1326
- point,
1371
+ onBranch,
1327
1372
  worktree,
1328
1373
  commands,
1329
1374
  progress,
1330
1375
  durationMs,
1331
1376
  }: {
1332
- point: "checks" | "ci";
1377
+ /** How the branch failed, which is also where: its Checks, or CI. */
1378
+ onBranch: BranchFailure;
1333
1379
  worktree: string;
1334
1380
  commands: readonly string[];
1335
1381
  progress: Progress;
@@ -1340,11 +1386,14 @@ async function releaseIfTheBaseFails(
1340
1386
  const inherited = await inheritedFailure(pipeline, worktree, commands);
1341
1387
  if (inherited === undefined) return;
1342
1388
  await progress.record({
1343
- point,
1344
- outcome: `⏸ \`${inherited.command}\` fails on the Base branch`,
1389
+ point: onBranch.point,
1390
+ outcome: `⏸ \`${inherited.command}\` fails on the base branch`,
1345
1391
  durationMs,
1346
1392
  });
1347
- throw new Releasing(point, "implemented", "failing-base", undefined, inherited);
1393
+ throw new Releasing(onBranch.point, "implemented", "failing-base", undefined, {
1394
+ ...inherited,
1395
+ onBranch,
1396
+ });
1348
1397
  }
1349
1398
 
1350
1399
  /**
@@ -1366,7 +1415,7 @@ async function verify(
1366
1415
  logDir: string,
1367
1416
  progress: Progress,
1368
1417
  notes: RoutedNote[],
1369
- /** 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. */
1370
1419
  unmetBefore: string | undefined,
1371
1420
  ): Promise<Verdict> {
1372
1421
  const stage = pipeline.config.stages.verify;
@@ -1386,13 +1435,14 @@ async function verify(
1386
1435
  });
1387
1436
 
1388
1437
  // Before anything else is done with the Stage at all, as the code Stages do
1389
- // 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
1390
1439
  // can be made of, still noticed whatever it noticed. The scratch work it
1391
1440
  // noticed it in is about to be discarded, so its Notes are all that is left —
1392
1441
  // and a worktree that will not discard them is no reason to lose them too.
1393
1442
  await collectNotes(pipeline, issue.number, "verify", result, notes);
1394
1443
 
1395
- // 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.
1396
1446
  await pipeline.workspace.discardChanges(worktree);
1397
1447
 
1398
1448
  if (!result.ok) throw await stageDidNotFinish(pipeline, progress, "verify", result);
@@ -1401,10 +1451,10 @@ async function verify(
1401
1451
  try {
1402
1452
  verdict = parseVerdict(result.result);
1403
1453
  } catch (error) {
1404
- await progress.record(stageRow("verify", result, "❌ no Verdict"));
1454
+ await progress.record(stageRow("verify", result, "❌ no verdict"));
1405
1455
  throw new TicketFailure(
1406
1456
  "verify",
1407
- "the verify Stage did not return a usable Verdict",
1457
+ "the verify Stage did not return a usable verdict",
1408
1458
  (error as Error).message,
1409
1459
  );
1410
1460
  }
@@ -1488,7 +1538,7 @@ async function fix(
1488
1538
  if (!result.ok) throw await stageDidNotFinish(pipeline, progress, "fix", result);
1489
1539
 
1490
1540
  // A session that came back clean mended nothing, whatever it says. Believing
1491
- // 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
1492
1542
  // over a branch nobody touched, which can only fail the way it just did — and
1493
1543
  // a progress row claiming the Stage committed. The budget is already spent,
1494
1544
  // so this ends the Ticket rather than buying another try.
@@ -1497,16 +1547,14 @@ async function fix(
1497
1547
  // changed: a session that squashed the branch shorter, or amended in place,
1498
1548
  // is read here as having committed nothing.
1499
1549
  //
1500
- // 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
1501
1552
  // nothing is also how a fix Stage hands back an unmet criterion only a human
1502
- // 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.
1503
1555
  if (!grew) {
1504
1556
  await progress.record(stageRow("fix", result, "❌ no commits"));
1505
- throw new TicketFailure(
1506
- "fix",
1507
- "the fix Stage left no new commits on the branch",
1508
- failure.evidence,
1509
- );
1557
+ throw leftNoCommits("fix", failure.evidence, result);
1510
1558
  }
1511
1559
 
1512
1560
  await progress.record(stageRow("fix", result, "✅ committed"));
@@ -1644,7 +1692,7 @@ interface PullRequestSubject {
1644
1692
  *
1645
1693
  * A second pass comes back to a pull request that already exists: the push is
1646
1694
  * what GitHub re-runs its checks on, and the title and body are rewritten so
1647
- * 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
1648
1696
  * the base branch.
1649
1697
  *
1650
1698
  * One that already exists is also taken out of draft, because a Ticket resumed
@@ -1714,12 +1762,12 @@ async function requireGreenCi(
1714
1762
  // fix Stage, it leaves, and the Checks below take minutes nobody else
1715
1763
  // should wait behind.
1716
1764
  landing.leave();
1717
- // 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
1718
1766
  // workflow that runs only on pull requests leaves a squash commit with
1719
1767
  // none, and a failure the clock brings starts after its last green run.
1720
1768
  // So the merge-base is graded with the Checks, which CI runs too.
1721
1769
  await releaseIfTheBaseFails(pipeline, {
1722
- point: "ci",
1770
+ onBranch: { point: "ci", summary: outcome.summary, excerpt: outcome.excerpt },
1723
1771
  worktree,
1724
1772
  commands: pipeline.config.checks,
1725
1773
  progress,
@@ -1737,7 +1785,7 @@ async function requireGreenCi(
1737
1785
  `the pull request checks did not finish within ${pipeline.config.ciTimeoutMinutes} minutes`,
1738
1786
  );
1739
1787
  case "conflicting":
1740
- // 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
1741
1789
  // under a pull request, but not a human merging on GitHub meanwhile. A
1742
1790
  // fix Stage has nothing to act on, so no fix kind: a human takes it.
1743
1791
  await record("❌ conflicting");
@@ -1762,15 +1810,15 @@ interface Release {
1762
1810
  user: string;
1763
1811
  branch: string;
1764
1812
  stopped: Releasing;
1765
- /** 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. */
1766
1814
  record: ResumeRecord;
1767
- /** 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. */
1768
1816
  fixUsed: boolean;
1769
1817
  notes: RoutedNote[];
1770
1818
  }
1771
1819
 
1772
1820
  /**
1773
- * 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.
1774
1822
  *
1775
1823
  * The opposite of a hand-off, and deliberately quiet. Nothing about the Ticket
1776
1824
  * failed, nobody has to look at it, and the work already on its branch is worth
@@ -1785,9 +1833,9 @@ async function release(
1785
1833
  const { tracker, config } = pipeline;
1786
1834
  const ticket = issue.number;
1787
1835
 
1788
- // 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
1789
1837
  // whose state is out of date is one the next Run would redo Stages for. One
1790
- // 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,
1791
1839
  // or it would meet the same failure.
1792
1840
  await record.advance({
1793
1841
  state: stopped.state,
@@ -1795,7 +1843,7 @@ async function release(
1795
1843
  ...(stopped.failingBase === undefined ? {} : { rebaseFirst: true }),
1796
1844
  });
1797
1845
  if (stopped.failingBase !== undefined) {
1798
- await noteFailingBase(pipeline, { issue, branch, stopped, failing: stopped.failingBase, notes });
1846
+ await noteFailingBase(pipeline, { issue, branch, failing: stopped.failingBase, notes });
1799
1847
  }
1800
1848
 
1801
1849
  // The claim, undone in the order it was made, so the assignee — which is what
@@ -1825,9 +1873,9 @@ async function release(
1825
1873
  }
1826
1874
 
1827
1875
  /**
1828
- * 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
1829
1877
  * commit however many Tickets it releases: the pipeline's own Note, on the
1830
- * 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.
1831
1879
  *
1832
1880
  * Logged and nothing more when it cannot be posted, as a Stage's Note is: the
1833
1881
  * Release is what the Ticket is owed, and the next Ticket released over the
@@ -1838,14 +1886,12 @@ async function noteFailingBase(
1838
1886
  {
1839
1887
  issue,
1840
1888
  branch,
1841
- stopped,
1842
1889
  failing,
1843
1890
  notes,
1844
1891
  }: {
1845
1892
  issue: Issue;
1846
1893
  branch: string;
1847
- stopped: Releasing;
1848
- failing: FailingBase;
1894
+ failing: InheritedFailure;
1849
1895
  notes: RoutedNote[];
1850
1896
  },
1851
1897
  ): Promise<void> {
@@ -1859,7 +1905,6 @@ async function noteFailingBase(
1859
1905
  number,
1860
1906
  failingBaseNote({
1861
1907
  origin,
1862
- point: stopped.point === "ci" ? "ci" : "checks",
1863
1908
  baseBranch: pipeline.baseBranch,
1864
1909
  branch,
1865
1910
  ...failing,
@@ -1901,7 +1946,7 @@ interface HandOff {
1901
1946
  /** Where the work is, absent when the Ticket failed before it had a worktree. */
1902
1947
  worktree?: HandOffWorktree;
1903
1948
  /**
1904
- * 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
1905
1950
  * carries is the pipeline's, whether or not this Run may push it.
1906
1951
  */
1907
1952
  keepsState: boolean;
@@ -1909,38 +1954,40 @@ interface HandOff {
1909
1954
  failure: TicketFailure;
1910
1955
  /** Whether the Ticket's fix budget had already been spent when this failure came. */
1911
1956
  fixUsed: boolean;
1912
- /** 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. */
1913
1958
  record: ResumeRecord;
1914
1959
  notes: RoutedNote[];
1915
1960
  }
1916
1961
 
1917
1962
  /**
1918
- * Hand the Ticket to a human: a draft PR to review, a comment naming where the
1919
- * work is, and the labels a human filters on. The branch, the worktree and the
1920
- * State file stay put, so a human who relabels the Ticket `ready-for-agent`
1921
- * hands it back and the next Run carries on from what it reached. The Stages'
1922
- * transcripts go up beside the State, since the Host they were written on may
1923
- * be gone by the time a human looks, and the comment says where they and the
1924
- * branch are. The draft PR's body says where they are too, once they are
1925
- * kept: a draft is opened first, because the State records it, and one that
1926
- * 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.
1927
1973
  *
1928
1974
  * A Ticket handed over before its worktree was created has none: nothing was
1929
- * branched, so there is no directory to name and nothing to push a draft PR out
1930
- * of. Both are left out rather than written as a path that is not there and a
1931
- * 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.
1932
1978
  *
1933
1979
  * Where a human is sent and what the pipeline pushes are two different facts. A
1934
1980
  * Ticket refused at setup over a branch still checked out somewhere names that
1935
1981
  * worktree and stops there: the work in it is a human's, and pushing it or
1936
- * 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.
1937
1984
  *
1938
- * 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
1939
1986
  * of is one a Stage of it worked in, and what it left is the pipeline's to
1940
1987
  * resume; a branch in the way at setup leaves nothing of the pipeline's behind,
1941
1988
  * and a file kept over it would let a later Run resume into a human's work and
1942
1989
  * run an implement Stage over it — which is what refusing at setup exists to
1943
- * 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
1944
1991
  * one parted from the remote branch: both copies are the pipeline's, and
1945
1992
  * pushing either over the other is the choice the human is handed.
1946
1993
  */
@@ -1964,14 +2011,15 @@ async function handOff(
1964
2011
 
1965
2012
  // Nothing of this Run's is on the branch, so nothing may leave the Ticket
1966
2013
  // looking resumable: the next Run must not implement over what a human holds.
1967
- // Wrapped because the hand-off itself — the draft PR, the comment, the labels
1968
- // — 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.
1969
2017
  if (!keepsState) {
1970
2018
  try {
1971
2019
  await workspace.removeState(ticket);
1972
2020
  } catch (error) {
1973
2021
  pipeline.log?.(
1974
- `#${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}`,
1975
2023
  );
1976
2024
  }
1977
2025
  }
@@ -1988,7 +2036,8 @@ async function handOff(
1988
2036
  if (pullRequest !== undefined) {
1989
2037
  await tracker.convertPullRequestToDraft(pullRequest);
1990
2038
  } else if (worktree?.pushable === true) {
1991
- // 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.
1992
2041
  try {
1993
2042
  await workspace.push(worktree.path, branch);
1994
2043
  const pr = await tracker.createPullRequest({
@@ -2005,7 +2054,7 @@ async function handOff(
2005
2054
  pullRequest = pr.number;
2006
2055
  drafted = true;
2007
2056
  } catch (error) {
2008
- 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}`);
2009
2058
  }
2010
2059
  }
2011
2060
 
@@ -2013,17 +2062,17 @@ async function handOff(
2013
2062
  // Written after the draft pull request, because that pull request is part of
2014
2063
  // what a resuming Run must not open a second one beside.
2015
2064
  //
2016
- // 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
2017
2066
  // human's hands, and whatever they did to it is what the fresh budget is
2018
2067
  // for. Nothing is lost by it — the hand-off comment says the budget was
2019
- // spent, and the Claim only marks that comment as history.
2068
+ // spent, and the claim only marks that comment as history.
2020
2069
  await record.advance({
2021
2070
  fixUsed: false,
2022
2071
  ...(pullRequest === undefined ? {} : { pullRequest }),
2023
2072
  });
2024
2073
  }
2025
- // Only beside a State that stays, because they go when it does, and after
2026
- // 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.
2027
2076
  const transcripts = keepsState ? await keepTranscripts(pipeline, ticket) : undefined;
2028
2077
  // A draft this hand-off opened went up before anything was kept, and one it
2029
2078
  // converted still carries an earlier body, so either learns where only now.
@@ -2054,6 +2103,7 @@ async function handOff(
2054
2103
  ...(worktree === undefined ? {} : { worktree: worktree.path }),
2055
2104
  ...(transcripts === undefined ? {} : { transcripts }),
2056
2105
  evidence: failure.evidence,
2106
+ ...(failure.reason === undefined ? {} : { reason: failure.reason }),
2057
2107
  fixUsed,
2058
2108
  ...(pullRequest === undefined ? {} : { pullRequest }),
2059
2109
  }),