ticket-runner 0.6.0

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 (55) hide show
  1. package/LICENSE +21 -0
  2. package/README.ko.md +97 -0
  3. package/README.md +98 -0
  4. package/bin/ticket-runner.js +6 -0
  5. package/docs/templates/operator-skill.md +87 -0
  6. package/package.json +42 -0
  7. package/src/acceptance-criteria.ts +44 -0
  8. package/src/adapters/claude-agent-runner.ts +389 -0
  9. package/src/adapters/exec.ts +169 -0
  10. package/src/adapters/gh-tracker.ts +955 -0
  11. package/src/adapters/git-workspace.ts +951 -0
  12. package/src/adapters/repo-root.ts +20 -0
  13. package/src/adapters/version.ts +118 -0
  14. package/src/base-branch.ts +21 -0
  15. package/src/branch.ts +33 -0
  16. package/src/cli.ts +135 -0
  17. package/src/command-line.ts +190 -0
  18. package/src/config.ts +277 -0
  19. package/src/conventions.ts +118 -0
  20. package/src/criteria.ts +106 -0
  21. package/src/frontier.ts +36 -0
  22. package/src/guards.ts +143 -0
  23. package/src/handoff.ts +82 -0
  24. package/src/host.ts +116 -0
  25. package/src/init.ts +405 -0
  26. package/src/labels.ts +42 -0
  27. package/src/landing.ts +75 -0
  28. package/src/lifecycle.ts +34 -0
  29. package/src/lock.ts +215 -0
  30. package/src/note-schema.ts +58 -0
  31. package/src/notes.ts +433 -0
  32. package/src/operator-skill.ts +24 -0
  33. package/src/orchestrator.ts +1816 -0
  34. package/src/ports/agent-runner.ts +105 -0
  35. package/src/ports/tracker.ts +334 -0
  36. package/src/ports/workspace.ts +422 -0
  37. package/src/progress.ts +231 -0
  38. package/src/prompts.ts +288 -0
  39. package/src/readiness.ts +256 -0
  40. package/src/remove.ts +732 -0
  41. package/src/resume.ts +145 -0
  42. package/src/run-log.ts +85 -0
  43. package/src/run.ts +331 -0
  44. package/src/self-hosting.ts +33 -0
  45. package/src/stage-guard.ts +32 -0
  46. package/src/staleness.ts +101 -0
  47. package/src/start.ts +284 -0
  48. package/src/startup.ts +34 -0
  49. package/src/stop.ts +178 -0
  50. package/src/stranded.ts +136 -0
  51. package/src/templates.ts +596 -0
  52. package/src/title.ts +97 -0
  53. package/src/verdict.ts +88 -0
  54. package/src/version-number.ts +67 -0
  55. package/src/version-pr.ts +103 -0
@@ -0,0 +1,1816 @@
1
+ import { branchName, worktreePath } from "./branch.js";
2
+ import type { Config } from "./config.js";
3
+ import { tickMetCriteria } from "./criteria.js";
4
+ import { type SkipReason, isGuardReason, skipReason } from "./guards.js";
5
+ import { markHandoffsTaken } from "./handoff.js";
6
+ import type { HostKind } from "./host.js";
7
+ import type { Landing, LandingTurn } from "./landing.js";
8
+ import type { FailureKind, FailurePoint } from "./lifecycle.js";
9
+ import {
10
+ type NotingStage,
11
+ type RoutedNote,
12
+ type StandingNotes,
13
+ type StandingNotesLookup,
14
+ routeNotes,
15
+ } from "./notes.js";
16
+ import type {
17
+ AgentRunner,
18
+ StageFailure,
19
+ StageName,
20
+ StageResult,
21
+ } from "./ports/agent-runner.js";
22
+ import type { Issue, Tracker } from "./ports/tracker.js";
23
+ import type {
24
+ KeptTranscripts,
25
+ ReachedState,
26
+ TicketState,
27
+ Workspace,
28
+ WorktreeFromRemote,
29
+ } from "./ports/workspace.js";
30
+ import { Progress, type ProgressPoint, type ProgressRow } from "./progress.js";
31
+ import {
32
+ type FixFailure,
33
+ conflictPrompt,
34
+ fixPrompt,
35
+ implementPrompt,
36
+ verifyPrompt,
37
+ } from "./prompts.js";
38
+ import { retryLogDir, stageLogDir } from "./run-log.js";
39
+ import { holdsClaim } from "./stranded.js";
40
+ import {
41
+ draftPullRequestBody,
42
+ guardComment,
43
+ handoffComment,
44
+ hasGuardWarning,
45
+ pullRequestBody,
46
+ squashCommit,
47
+ } from "./templates.js";
48
+ import { CODE_STAGE_JSON_SCHEMA, parseTitle, pullRequestTitle } from "./title.js";
49
+ import {
50
+ type Verdict,
51
+ VERDICT_JSON_SCHEMA,
52
+ countStatuses,
53
+ parseVerdict,
54
+ passes,
55
+ unmetCriteria,
56
+ } from "./verdict.js";
57
+
58
+ export type TicketOutcome =
59
+ | {
60
+ outcome: "merged";
61
+ ticket: number;
62
+ /** Carried so a Run summary can name the Ticket without asking again. */
63
+ title: string;
64
+ branch: string;
65
+ pullRequest: number;
66
+ /** Every Note this Ticket's Stages routed, in the order they were routed. */
67
+ notes: RoutedNote[];
68
+ }
69
+ | {
70
+ outcome: "handed-off";
71
+ ticket: number;
72
+ title: string;
73
+ branch: string;
74
+ stage: FailurePoint;
75
+ failure: string;
76
+ pullRequest?: number;
77
+ notes: RoutedNote[];
78
+ }
79
+ | {
80
+ outcome: "released";
81
+ ticket: number;
82
+ title: string;
83
+ branch: string;
84
+ /** Where the rate limit landed, which is all the summary says about it. */
85
+ stage: FailurePoint;
86
+ notes: RoutedNote[];
87
+ }
88
+ | {
89
+ outcome: "skipped";
90
+ ticket: number;
91
+ /** Absent where the number has no issue behind it to take a title from. */
92
+ title?: string;
93
+ /** The guard that passed it over, in the guard's own word for it. */
94
+ reason: SkipReason;
95
+ };
96
+
97
+ export interface Pipeline {
98
+ tracker: Tracker;
99
+ runner: AgentRunner;
100
+ workspace: Workspace;
101
+ config: Config;
102
+ repoRoot: string;
103
+ runId: string;
104
+ /**
105
+ * The Version this Run is, resolved once in the CLI and stamped on everything
106
+ * the Run writes (ADR-0007). A string, never a lookup: nothing here reads
107
+ * `package.json` or runs git, so every stamp of one Run is the same string.
108
+ */
109
+ version: string;
110
+ /**
111
+ * The Host the Run is on, which decides whether a merged pull request's body
112
+ * can point at the Run's directory: a cloud Host's is gone with its session.
113
+ */
114
+ host: HostKind;
115
+ /**
116
+ * The branch every Ticket of this Run branches from, rebases onto, merges
117
+ * into and pulls, resolved once before the Run started
118
+ * ({@link import("./base-branch.js").resolveBaseBranch}).
119
+ */
120
+ baseBranch: string;
121
+ /**
122
+ * The Run's Landing, made once before the first Ticket and shared by every
123
+ * Ticket it drives: only one of them is between its rebase and the pull of
124
+ * the Base branch after its merge at a time (ADR-0005).
125
+ */
126
+ landing: Landing;
127
+ /**
128
+ * The Run's standing Notes issue, resolved once and shared by every Ticket:
129
+ * the Notes of a whole night land on one issue, and the Stages that write
130
+ * them are told which one it is.
131
+ */
132
+ standingNotes: StandingNotes;
133
+ /**
134
+ * Whether the Target is the pipeline's own repository, decided once before
135
+ * the Run started ({@link import("./self-hosting.js").isPipelineRepository}).
136
+ * Only there is the checkout a Stage stands in the pipeline itself, so only
137
+ * there is a Stage told to exercise it through its tests and fakes.
138
+ */
139
+ selfHosted: boolean;
140
+ log?: (line: string) => void;
141
+ }
142
+
143
+ /**
144
+ * A failure that ends the Ticket, unless the fix budget can still buy it a
145
+ * second try. `kind` is set on exactly the failures a fix Stage is given:
146
+ * everything else is a hand-off the moment it is thrown.
147
+ */
148
+ class TicketFailure extends Error {
149
+ constructor(
150
+ readonly point: FailurePoint,
151
+ readonly summary: string,
152
+ readonly evidence: string = "",
153
+ readonly kind?: FailureKind,
154
+ ) {
155
+ super(summary);
156
+ }
157
+ }
158
+
159
+ /**
160
+ * A Stage the subscription rate limit stopped.
161
+ *
162
+ * The one Stage failure that says nothing about the Ticket, so it is the one
163
+ * that neither ends it nor spends its Fix budget: the Claim is released and a
164
+ * State file is left for the next Run to resume from (ADR-0004). It is not a
165
+ * {@link TicketFailure} because every path that handles one of those would
166
+ * either hand the Ticket off or buy it a fix Stage, and this is neither.
167
+ */
168
+ class RateLimited extends Error {
169
+ constructor(
170
+ readonly point: FailurePoint,
171
+ /** The state the Ticket reached, which is where a later Run picks it up. */
172
+ readonly state: ReachedState,
173
+ ) {
174
+ super(`the ${point} Stage hit the subscription rate limit`);
175
+ }
176
+ }
177
+
178
+ /** An error the pipeline did not raise itself, blamed on the step it was on. */
179
+ function asTicketFailure(error: unknown, point: FailurePoint): TicketFailure {
180
+ return error instanceof TicketFailure
181
+ ? error
182
+ : new TicketFailure(point, (error as Error).message);
183
+ }
184
+
185
+ /**
186
+ * Take one Ticket from claimed to merged, hand it to a human, or pass it over.
187
+ *
188
+ * The happy path is: guards → claim → worktree and branch → implement Stage →
189
+ * Checks → verify Stage → rebase → PR → CI → squash merge → cleanup. Work left
190
+ * uncommitted, a failing Check, an unmet criterion, a red CI or a rebase
191
+ * conflict the conflict Stage could not resolve spends the Ticket's fix budget
192
+ * and starts again at the Checks; every other failure, and every second
193
+ * failure, ends in a hand-off.
194
+ * Nothing ends in a merge that has not been through a green pass of the whole
195
+ * gauntlet.
196
+ *
197
+ * A Stage the subscription rate limit stopped ends none of that: the Ticket is
198
+ * released, and a Run started once the limit has reset resumes it from the state
199
+ * it had reached rather than from the top. A hand-off keeps that state too, so a
200
+ * human who relabels the Ticket `ready-for-agent` hands it back and the next Run
201
+ * carries on from what it reached rather than paying for the implement Stage a
202
+ * second time.
203
+ *
204
+ * The guards come before the claim, so an issue the pipeline will not take is
205
+ * never marked as taken. A Run has already dropped the claimed and the
206
+ * untriaged from its Frontier, but the Ticket may have changed hands since the
207
+ * listing, so the guards ask again.
208
+ *
209
+ * From the pull of the Base branch before the rebase to the pull after the
210
+ * merge the Ticket holds the Run's Landing, so no other Ticket of the same Run moves the Base
211
+ * branch underneath the branch CI is grading (ADR-0005).
212
+ */
213
+ export async function processTicket(
214
+ pipeline: Pipeline,
215
+ ticket: number,
216
+ /**
217
+ * Where the Notes are collected, so a caller that has to catch an exception
218
+ * this function could not turn into a hand-off still knows what was routed.
219
+ * The returned outcome carries the same array.
220
+ */
221
+ notes: RoutedNote[] = [],
222
+ ): Promise<TicketOutcome> {
223
+ // Made here rather than where it is first entered, so that however the Ticket
224
+ // ends — including on a path nobody wrote a hand-off for — the Landing is
225
+ // given back. Every path that leaves it early says so where it happens; this
226
+ // is only the backstop behind them.
227
+ const turn = pipeline.landing.turn();
228
+ try {
229
+ return await takeTicket(pipeline, ticket, turn, notes);
230
+ } finally {
231
+ turn.leave();
232
+ }
233
+ }
234
+
235
+ /** One Ticket, holding the turn at the Landing its caller owes the Run. */
236
+ async function takeTicket(
237
+ pipeline: Pipeline,
238
+ ticket: number,
239
+ landing: LandingTurn,
240
+ notes: RoutedNote[],
241
+ ): Promise<TicketOutcome> {
242
+ const { tracker, workspace, config, repoRoot, runId, baseBranch } = pipeline;
243
+ const log = pipeline.log ?? (() => {});
244
+
245
+ const issue = await tracker.getIssue(ticket);
246
+ const user = await tracker.currentUser();
247
+
248
+ // What an earlier Run left behind, read before the guards because it decides
249
+ // one of them: a Ticket this pipeline still holds with state recorded for it is
250
+ // stranded — the Claim on it is this pipeline's own, left by a Run that never
251
+ // came back — and the refusals must not read it as somebody else's.
252
+ const recorded = await workspace.readState(ticket);
253
+ const stranded = recorded !== undefined && holdsClaim(issue, user, config.labels.inProgress);
254
+ const skip = skipReason(issue, config.labels.readyForAgent, stranded);
255
+ if (skip !== undefined) return await passOver(pipeline, issue, skip);
256
+
257
+ const worktree = worktreePath(repoRoot, ticket);
258
+ // Whether the work that state names is still there, on this Host or the
259
+ // remote. Its branch is the one the work is on, which the Ticket's title may
260
+ // no longer say anything about.
261
+ const found = await resumable(pipeline, ticket, worktree, recorded);
262
+ const resume = found?.state;
263
+ const branch = resume?.branch ?? branchName(ticket, issue.title);
264
+ // Built from the comments the Ticket already has, so a Run that comes back to
265
+ // a Ticket an earlier Run reported on adds its section to that comment rather
266
+ // than opening a second one. Nothing is written until the first Stage finishes.
267
+ const progress = new Progress({
268
+ tracker,
269
+ ticket,
270
+ version: pipeline.version,
271
+ runId,
272
+ branch,
273
+ comments: issue.comments,
274
+ log,
275
+ });
276
+
277
+ // The State file, written as part of the Claim and kept current from here on,
278
+ // so a Run that is killed mid-Ticket — or a human handed the Ticket — still
279
+ // leaves the next Run something to resume. A resumed Ticket carries on from
280
+ // what it had already reached.
281
+ //
282
+ // First of the two, because a Claim no State file names is the one thing this
283
+ // has to rule out: a crash between the writes then leaves a Ticket nobody has
284
+ // claimed with state beside it, which is a released Ticket and resumes itself.
285
+ const record = await ResumeRecord.claim(pipeline, {
286
+ ticket,
287
+ branch,
288
+ state: resume?.state ?? "claimed",
289
+ fixUsed: resume?.fixUsed ?? false,
290
+ ...(resume?.pullRequest === undefined ? {} : { pullRequest: resume.pullRequest }),
291
+ ...(resume?.title === undefined ? {} : { title: resume.title }),
292
+ });
293
+
294
+ // The claim is the first write on the board: it shows what the pipeline holds
295
+ // before anything else can go wrong. A stranded Ticket is resumed in place,
296
+ // wearing the Claim it never gave up — re-writing what is already there would
297
+ // only risk the Ticket on three tracker calls that change nothing.
298
+ if (!stranded) {
299
+ await tracker.assign(ticket, user);
300
+ await tracker.addLabel(ticket, config.labels.inProgress);
301
+ await tracker.removeLabel(ticket, config.labels.readyForAgent);
302
+ }
303
+ log(`#${ticket} ${howItWasTaken(resume, stranded)} · ${branch}`);
304
+
305
+ // Whatever hand-off left this Ticket to a human is no longer the last word on
306
+ // it. Marked here because the comments are already in hand, and because one
307
+ // place covers both endings: the Ticket that merges from here, and the one
308
+ // that is handed off a second time below a hand-off that has been defused.
309
+ await markHandoffsTaken({ tracker, ticket, comments: issue.comments, log });
310
+
311
+ // A pull request an earlier Run had already opened: without it this Run would
312
+ // try to open a second one for the same branch.
313
+ let pullRequest: number | undefined = resume?.pullRequest;
314
+ // Where an unexpected error would have happened, so the hand-off comment
315
+ // names the step the human has to look at rather than guessing.
316
+ let point: FailurePoint = "setup";
317
+ // The worktree a hand-off can send a human to, once there is one, and whether
318
+ // this Run may push out of it. A Ticket that failed before `createWorktree`
319
+ // ran has none; a resumed Ticket is resumed into the one this Host kept, or
320
+ // made from its remote branch.
321
+ let worktreeOnDisk: HandOffWorktree | undefined =
322
+ resume === undefined ? undefined : { path: worktree, pushable: true };
323
+ // The fix budget, which is one per Ticket and spent by the first failure a
324
+ // fix Stage is offered. Once it is gone the next failure of any kind — even a
325
+ // kind the fix Stage never touched — is a hand-off. A resumed Ticket keeps the
326
+ // budget recorded when it stopped: resuming buys no second chances.
327
+ let fixUsed = resume?.fixUsed ?? false;
328
+ // The pass behind a fix Stage logs beside the first one rather than over it.
329
+ let logDir = stageLogDir(repoRoot, runId, ticket);
330
+
331
+ // Declared out here because ticking the Acceptance Criteria it proved happens
332
+ // after the merge, where a failure may no longer hand the Ticket off.
333
+ let verdict: Verdict;
334
+
335
+ try {
336
+ // A resumed Ticket's worktree is ready by now, and the Stages that already
337
+ // succeeded on its branch are not paid for twice.
338
+ if (found?.refusal !== undefined) {
339
+ // Nothing is pushed out of a worktree this Run cannot resume in, since
340
+ // what the remote holds may be another Host's newer work.
341
+ worktreeOnDisk =
342
+ found.checkedOutAt === undefined
343
+ ? undefined
344
+ : { path: found.checkedOutAt, pushable: false };
345
+ throw new TicketFailure("setup", found.refusal);
346
+ }
347
+ if (resume === undefined) {
348
+ // The branch is asked about before it is branched: `createWorktree`
349
+ // branches fresh from the base branch and fails on a name that is taken,
350
+ // and a branch nobody can account for is not reused (ADR-0004). Refusing
351
+ // here is what turns git's `fatal: a branch named ... already exists`
352
+ // into a hand-off that says whose branch it is and what to do with it.
353
+ if (await workspace.hasBranch(branch)) {
354
+ // Where the branch is decides what the human is asked to do about it:
355
+ // a branch that is checked out cannot simply be deleted, so the human
356
+ // is sent to the worktree holding it instead. Nothing the pipeline left
357
+ // is here — a Ticket it handed off keeps its State file and resumes
358
+ // without ever reaching this — so the branch is a human's either way.
359
+ const checkedOutAt = (await workspace.hasWorktree({ path: worktree, branch }))
360
+ ? worktree
361
+ : undefined;
362
+ // Not this Run's worktree, but the one holding the branch it was told
363
+ // to use: the hand-off names a directory a human can open either way,
364
+ // and pushes nothing out of work no Stage of this Run produced.
365
+ worktreeOnDisk =
366
+ checkedOutAt === undefined ? undefined : { path: checkedOutAt, pushable: false };
367
+ throw new TicketFailure(
368
+ "setup",
369
+ describeBranchInTheWay(branch, checkedOutAt, config.labels.readyForAgent),
370
+ );
371
+ }
372
+ await workspace.createWorktree({ path: worktree, branch }, baseBranch);
373
+ worktreeOnDisk = { path: worktree, pushable: true };
374
+ } else {
375
+ // A Run that was killed mid-rebase left git stopped in the worktree, with
376
+ // conflict markers in files the Checks are about to grade. Back to the
377
+ // branch tip first, then: a no-op on a worktree nothing stopped, so every
378
+ // resume rebases from the same clean start a released Ticket does.
379
+ await workspace.abortRebase(worktree);
380
+ }
381
+ if (resume === undefined || resume.state === "claimed") {
382
+ point = "implement";
383
+ await implement(pipeline, issue, worktree, branch, logDir, progress, notes, record);
384
+ // The branch now carries work no later Run should pay for again.
385
+ await record.advance({ state: "implemented" });
386
+ }
387
+
388
+ let commits: string[];
389
+ let coAuthors: string[];
390
+ let title: string;
391
+
392
+ // Checks through CI, run again from the top when the fix budget buys a
393
+ // second pass: a fix earns no shortcut, so every gate grades it afresh.
394
+ for (;;) {
395
+ try {
396
+ point = "checks";
397
+ // Before anything grades the worktree, and so before verify discards
398
+ // what a Stage left uncommitted.
399
+ await requireCommitted(pipeline, worktree, progress);
400
+ await runChecks(pipeline, worktree, progress);
401
+ point = "verify";
402
+ verdict = await verify(pipeline, issue, worktree, logDir, progress, notes);
403
+
404
+ point = "rebase";
405
+ // The Landing, from here until the Base branch has been pulled: the
406
+ // Ticket waits its turn, and the Base branch it rebases onto is then
407
+ // the one its merge will land on.
408
+ await landing.enter();
409
+ // Up to the remote first: a Base branch the checkout holds behind it
410
+ // is a rebase that changes nothing and a pull request that conflicts,
411
+ // which GitHub then runs no CI for. One that cannot be brought up is a
412
+ // failure here, since rebasing onto it would be the same mistake.
413
+ await workspace.pullBase(baseBranch);
414
+ const rebase = await workspace.rebase(worktree, baseBranch);
415
+ if (!rebase.ok) {
416
+ // Once per conflict, not once per Ticket: a pass the fix budget
417
+ // bought meets a branch the fix Stage has changed, so the conflict it
418
+ // rebases into is a new one.
419
+ await resolveConflict(
420
+ pipeline,
421
+ issue,
422
+ worktree,
423
+ branch,
424
+ logDir,
425
+ rebase.conflict,
426
+ progress,
427
+ );
428
+ // The resolution is code nothing has graded: the Checks passed on one
429
+ // side of the conflict and CI on the other. The Verdict is not asked
430
+ // for again, because the conflict Stage is told to change no
431
+ // behaviour the Acceptance Criteria are about.
432
+ point = "checks";
433
+ await runChecks(pipeline, worktree, progress);
434
+ }
435
+
436
+ point = "pr";
437
+ // Read after the rebase, because these are the commits that land on
438
+ // the base branch.
439
+ commits = await workspace.commitSubjects(branch, baseBranch);
440
+ coAuthors = await workspace.coAuthors(branch, baseBranch);
441
+ // The latest title a Stage answered, in this Run or the one it resumes,
442
+ // before anything read off the commits.
443
+ title = pullRequestTitle(record.title, commits, issue.title);
444
+ pullRequest = await publishPullRequest(
445
+ pipeline,
446
+ { issue, branch, worktree, verdict, title },
447
+ pullRequest,
448
+ );
449
+ await record.advance({ pullRequest });
450
+ point = "ci";
451
+ await requireGreenCi(pipeline, pullRequest, progress);
452
+ break;
453
+ } catch (error) {
454
+ // A rate limit is nobody's defect, so the fix budget does not answer
455
+ // for it: the Ticket is released, whole, further up.
456
+ if (error instanceof RateLimited) throw error;
457
+ const failure = asTicketFailure(error, point);
458
+ if (fixUsed || failure.kind === undefined) throw failure;
459
+ fixUsed = true;
460
+ point = "fix";
461
+ // A fix Stage is a session nobody else is waiting on, so the Landing
462
+ // goes back: another Ticket lands while it runs, and this one rejoins
463
+ // the queue at the back when it reaches the rebase again.
464
+ landing.leave();
465
+ logDir = retryLogDir(repoRoot, runId, ticket);
466
+ await fix(
467
+ pipeline,
468
+ issue,
469
+ worktree,
470
+ branch,
471
+ logDir,
472
+ { kind: failure.kind, summary: failure.summary, evidence: failure.evidence },
473
+ progress,
474
+ notes,
475
+ record,
476
+ );
477
+ // Recorded once the Stage has come back, not when the budget was
478
+ // committed: a fix Stage the rate limit stopped before it ran spends
479
+ // nothing, and the release below says so.
480
+ await record.advance({ fixUsed: true });
481
+ }
482
+ }
483
+
484
+ point = "merge";
485
+ await tracker.squashMerge(
486
+ pullRequest,
487
+ squashCommit({ ticket, pullRequest, title, verdict, commits, coAuthors }),
488
+ );
489
+ await progress.record({ point: "merge", outcome: `✅ #${pullRequest}` });
490
+ } catch (error) {
491
+ // Out of the Landing before either ending is written: a hand-off's draft
492
+ // pull request and a Release's labels are nothing for the next Ticket to
493
+ // wait behind, and a Ticket that never reached the rebase gives up nothing.
494
+ landing.leave();
495
+ if (error instanceof RateLimited) {
496
+ return release(pipeline, {
497
+ issue,
498
+ user,
499
+ branch,
500
+ limit: error,
501
+ record,
502
+ // A fix Stage the limit stopped before it ran spends nothing: the
503
+ // budget is still there for the Run that resumes the Ticket.
504
+ fixUsed: fixUsed && error.point !== "fix",
505
+ notes,
506
+ });
507
+ }
508
+ return handOff(pipeline, {
509
+ issue,
510
+ user,
511
+ branch,
512
+ ...(worktreeOnDisk === undefined ? {} : { worktree: worktreeOnDisk }),
513
+ // A resume refused at setup keeps it too: the work is the pipeline's,
514
+ // and whichever side a human keeps is one a later Run resumes from.
515
+ keepsState: found?.refusal !== undefined || worktreeOnDisk?.pushable === true,
516
+ pullRequest,
517
+ failure: asTicketFailure(error, point),
518
+ fixUsed,
519
+ record,
520
+ notes,
521
+ });
522
+ }
523
+
524
+ // The Ticket is merged from here on, so nothing below may hand it off, and
525
+ // it is still in the Landing: the pull below is the last of it.
526
+ // The State file goes first: a merged Ticket must not look resumable to the
527
+ // next Run, whatever else below fails — which is worth the Landing staying
528
+ // shut for three writes nobody else is waiting on.
529
+ try {
530
+ await workspace.removeState(ticket);
531
+ } catch (error) {
532
+ log(`#${ticket} merged, but clearing its State file failed: ${(error as Error).message}`);
533
+ }
534
+ try {
535
+ await tickMetCriteria(tracker, ticket, verdict, log);
536
+ } catch (error) {
537
+ log(`#${ticket} merged, but ticking its criteria failed: ${(error as Error).message}`);
538
+ }
539
+ // The merge closes the issue; the label would otherwise outlive the work.
540
+ try {
541
+ await tracker.removeLabel(ticket, config.labels.inProgress);
542
+ } catch (error) {
543
+ log(`#${ticket} merged, but clearing in-progress failed: ${(error as Error).message}`);
544
+ }
545
+ try {
546
+ await workspace.pullBase(baseBranch);
547
+ // The pull ends the Landing: the next Ticket now rebases onto a Base branch
548
+ // that already carries this one, and the cleanup below holds nobody up.
549
+ landing.leave();
550
+ await workspace.removeWorktree({ path: worktree, branch });
551
+ await workspace.deleteRemoteBranch(branch);
552
+ } catch (error) {
553
+ log(`#${ticket} merged, but cleaning up failed: ${(error as Error).message}`);
554
+ }
555
+ log(`#${ticket} merged · PR #${pullRequest}`);
556
+
557
+ return { outcome: "merged", ticket, title: issue.title, branch, pullRequest, notes };
558
+ }
559
+
560
+ /**
561
+ * What the human is told about a branch nothing can be branched over.
562
+ *
563
+ * One line, because that is what the hand-off comment, the Run summary and the
564
+ * Run log each carry. It names the branch twice on purpose: once as the thing
565
+ * that is in the way, and once inside the command that clears it.
566
+ *
567
+ * `checkedOutAt` is the worktree the branch is in, when it is in one: a branch
568
+ * git will not let go of is not one `git branch -D` can delete, so being told
569
+ * to run that would send the human round a second failure.
570
+ */
571
+ function describeBranchInTheWay(
572
+ branch: string,
573
+ checkedOutAt: string | undefined,
574
+ readyForAgent: string,
575
+ ): string {
576
+ const relabel = `then relabel the Ticket ${readyForAgent}`;
577
+ if (checkedOutAt !== undefined) {
578
+ return (
579
+ `the branch ${branch} already exists and is checked out at ${checkedOutAt}; ` +
580
+ `finish the work there by hand, or throw it away with ` +
581
+ `\`git worktree remove ${checkedOutAt} && git branch -D ${branch}\`, ${relabel}`
582
+ );
583
+ }
584
+ return (
585
+ `the branch ${branch} already exists but no worktree of this repo is on it; ` +
586
+ `delete it with \`git branch -D ${branch}\` if the work on it is abandoned, ` +
587
+ `or finish it by hand, ${relabel}`
588
+ );
589
+ }
590
+
591
+ /** A Ticket a Run can resume, and whether it can carry on in its worktree. */
592
+ interface Resumable {
593
+ state: TicketState;
594
+ /**
595
+ * Why it cannot, when it cannot: this Host's copy of the branch has parted
596
+ * from the remote one, or the worktree could not be made ready at all.
597
+ * Either is a hand-off at setup, and the State stays.
598
+ */
599
+ refusal?: string;
600
+ /** The worktree the branch is checked out in, for a refusal to send a human to. */
601
+ checkedOutAt?: string;
602
+ }
603
+
604
+ /**
605
+ * The state an earlier Run left for this Ticket, if a Run can still resume it,
606
+ * with the worktree it resumes in made ready.
607
+ *
608
+ * The State file only names where the work is; where the work actually is, is
609
+ * the Workspace's answer, and the branch on the remote is what it answers from
610
+ * (ADR-0004). Any Host's Run pushes it each time a Stage commits, so a Host
611
+ * with no worktree of the Ticket makes one from it, and one that still has a
612
+ * worktree keeps it only when it sits on top of the remote branch.
613
+ *
614
+ * Taken from the top, and the file with it, only when the branch is on neither
615
+ * this Host nor the remote: there is no work left to resume, released or
616
+ * stranded alike. That is not free: the branch may still be here without its
617
+ * worktree, and then the Ticket is handed over at setup with a failure naming
618
+ * it. Better that than resuming into a worktree that is not there.
619
+ */
620
+ async function resumable(
621
+ pipeline: Pipeline,
622
+ ticket: number,
623
+ worktree: string,
624
+ state: TicketState | undefined,
625
+ ): Promise<Resumable | undefined> {
626
+ if (state === undefined) return undefined;
627
+ const ref = { path: worktree, branch: state.branch };
628
+ // Caught here, because nothing is claimed yet: the refusal is raised once the
629
+ // Claim is made, as a hand-off a human can see on the board.
630
+ let found: WorktreeFromRemote;
631
+ let checkedOut: boolean;
632
+ try {
633
+ found = await pipeline.workspace.worktreeFromRemote(ref);
634
+ checkedOut = found === "parted" && (await pipeline.workspace.hasWorktree(ref));
635
+ } catch (error) {
636
+ return {
637
+ state,
638
+ refusal: `the worktree of ${state.branch} could not be made ready to resume in: ${(error as Error).message}`,
639
+ };
640
+ }
641
+ if (found === "made" || found === "kept") return { state };
642
+ if (found === "parted") {
643
+ const checkedOutAt = checkedOut ? worktree : undefined;
644
+ return {
645
+ state,
646
+ refusal: describeParted(state.branch, checkedOutAt, pipeline.config.labels.readyForAgent),
647
+ ...(checkedOutAt === undefined ? {} : { checkedOutAt }),
648
+ };
649
+ }
650
+
651
+ pipeline.log?.(
652
+ `#${ticket} was resumable, but ${state.branch} is neither in ${worktree} nor on the remote`,
653
+ );
654
+ // Logged and nothing more when it fails: the Claim writes this Ticket's State
655
+ // over it in a moment, from the top.
656
+ try {
657
+ await pipeline.workspace.removeState(ticket);
658
+ } catch (error) {
659
+ pipeline.log?.(`#${ticket} could not forget its state: ${(error as Error).message}`);
660
+ }
661
+ return undefined;
662
+ }
663
+
664
+ /**
665
+ * What the human is told about a branch whose copy here has parted from the
666
+ * one on the remote: which two copies, and the two ways to make them one.
667
+ *
668
+ * One line, as for {@link describeBranchInTheWay}. `checkedOutAt` is the
669
+ * worktree the branch is in, when it is in one.
670
+ */
671
+ function describeParted(
672
+ branch: string,
673
+ checkedOutAt: string | undefined,
674
+ readyForAgent: string,
675
+ ): string {
676
+ const here =
677
+ checkedOutAt === undefined
678
+ ? `the branch ${branch} on this Host`
679
+ : `the worktree at ${checkedOutAt}`;
680
+ const discard =
681
+ checkedOutAt === undefined
682
+ ? `\`git branch -D ${branch}\``
683
+ : `\`git worktree remove ${checkedOutAt} && git branch -D ${branch}\``;
684
+ return (
685
+ `${here} and the branch ${branch} on the remote have parted, each holding commits ` +
686
+ `the other lacks; keep the remote's by throwing this Host's away with ${discard}, ` +
687
+ `or force-push this Host's over it by hand, then relabel the Ticket ${readyForAgent}`
688
+ );
689
+ }
690
+
691
+ /**
692
+ * How this Run came by the Ticket, for the one line it logs about it: resumed
693
+ * from a recorded state, taken from the top, or claimed outright. A stranded
694
+ * Ticket with nothing left to resume into is the middle one — it is started
695
+ * again, but the Claim it is started under is the one it already had.
696
+ */
697
+ function howItWasTaken(resume: TicketState | undefined, stranded: boolean): string {
698
+ if (resume !== undefined) return `resumed from ${resume.state}`;
699
+ return stranded ? "taken from the top, still claimed" : "claimed";
700
+ }
701
+
702
+ /** What the Ticket itself has reached, which is all a resume needs to be told. */
703
+ type Reached = Omit<TicketState, "runId" | "updatedAt">;
704
+
705
+ /** What one write moves that on by. */
706
+ type Advance = Partial<Pick<Reached, "state" | "fixUsed" | "pullRequest" | "title">>;
707
+
708
+ /**
709
+ * The State file a Ticket keeps, and the one place a Ticket writes it.
710
+ *
711
+ * A Ticket is resumable for as long as its branch carries work worth resuming,
712
+ * so the file is written as part of the Claim and rewritten whenever the Ticket
713
+ * reaches something a later Run should not pay for again. The release is one
714
+ * more such write rather than the only one, which is what makes a Run that was
715
+ * killed recoverable too, and the hand-off is another.
716
+ *
717
+ * A write that does not land is logged and nothing more. What the remote holds
718
+ * is then an earlier state of the same Ticket, and resuming from further back
719
+ * costs a Stage rather than being wrong — where failing the Ticket over its
720
+ * bookkeeping would throw away the work the Stages have already done.
721
+ */
722
+ class ResumeRecord {
723
+ /** What the Ticket has; the Run and the time are what each write adds to it. */
724
+ private readonly reached: Reached;
725
+
726
+ private constructor(
727
+ private readonly pipeline: Pipeline,
728
+ reached: Reached,
729
+ ) {
730
+ this.reached = { ...reached };
731
+ }
732
+
733
+ /**
734
+ * Record what the Claim is about to make true, and hand back the record that
735
+ * keeps it current.
736
+ *
737
+ * The one write that is allowed to fail the Ticket. It runs before the Claim,
738
+ * so a remote that will not take the file costs nothing at all: the Ticket ends
739
+ * at setup with nothing claimed, where carrying on would put a Claim on the
740
+ * board that no later Run could ever resume — which is the state this record
741
+ * exists to rule out.
742
+ */
743
+ static async claim(pipeline: Pipeline, reached: Reached): Promise<ResumeRecord> {
744
+ const record = new ResumeRecord(pipeline, reached);
745
+ await pipeline.workspace.writeState(record.file());
746
+ return record;
747
+ }
748
+
749
+ /** The latest title a Stage answered for the branch, in this Run or an earlier one. */
750
+ get title(): string | undefined {
751
+ return this.reached.title;
752
+ }
753
+
754
+ /**
755
+ * Move the record on, and put it where the next Run will look for it.
756
+ *
757
+ * A write that does not land here is logged and nothing more: what the remote
758
+ * holds is an earlier state of the same Ticket, so resuming from further back
759
+ * costs a Stage rather than being wrong — where failing a Ticket mid-flight
760
+ * over its bookkeeping would throw away the Stages that have already succeeded.
761
+ */
762
+ async advance(reached: Advance): Promise<void> {
763
+ Object.assign(this.reached, reached);
764
+ try {
765
+ await this.pipeline.workspace.writeState(this.file());
766
+ } catch (error) {
767
+ this.pipeline.log?.(
768
+ `#${this.reached.ticket} could not record its state: ${(error as Error).message}`,
769
+ );
770
+ }
771
+ }
772
+
773
+ /**
774
+ * The Run, the Version and the time belong to the write, not to what the
775
+ * Ticket reached: they say which pipeline left the file, so a Run that cannot
776
+ * read one can still name what wrote it (ADR-0007).
777
+ */
778
+ private file(): TicketState {
779
+ return {
780
+ ...this.reached,
781
+ runId: this.pipeline.runId,
782
+ version: this.pipeline.version,
783
+ updatedAt: new Date().toISOString(),
784
+ };
785
+ }
786
+ }
787
+
788
+ /**
789
+ * Pass a candidate over, and warn about it once.
790
+ *
791
+ * The warning is a Planning defect a human has to fix, so it is posted at most
792
+ * once per reason: a Run that meets the same issue again — and, for everything
793
+ * but a Spec, the label is still there, so it will — says nothing a second
794
+ * time. An issue that was never offered to the pipeline is refused in silence.
795
+ */
796
+ async function passOver(
797
+ pipeline: Pipeline,
798
+ issue: Issue,
799
+ reason: SkipReason,
800
+ ): Promise<TicketOutcome> {
801
+ const { tracker, config } = pipeline;
802
+
803
+ if (isGuardReason(reason)) {
804
+ if (!hasGuardWarning(issue.comments, reason)) {
805
+ await tracker.comment(issue.number, guardComment(reason));
806
+ }
807
+ // A Spec is not a Ticket and no edit will make it one; the other two are
808
+ // fixable in place, so their candidates keep the label and stay visible.
809
+ if (reason === "spec") {
810
+ await tracker.removeLabel(issue.number, config.labels.readyForAgent);
811
+ }
812
+ }
813
+
814
+ pipeline.log?.(`#${issue.number} skipped · ${reason}`);
815
+ return { outcome: "skipped", ticket: issue.number, title: issue.title, reason };
816
+ }
817
+
818
+ /**
819
+ * Start one Stage under the model, effort, turn and wall-clock limits its own
820
+ * config names. Everything a Stage differs in is the prompt, where it runs and
821
+ * where it logs; the limits come from one place so no Stage can quietly skip them.
822
+ */
823
+ function runStage(
824
+ pipeline: Pipeline,
825
+ stage: StageName,
826
+ request: {
827
+ prompt: string;
828
+ cwd: string;
829
+ logDir: string;
830
+ jsonSchema?: unknown;
831
+ resultRequired?: boolean;
832
+ },
833
+ ): Promise<StageResult> {
834
+ const limits = pipeline.config.stages[stage];
835
+ return pipeline.runner.run({
836
+ stage,
837
+ prompt: request.prompt,
838
+ cwd: request.cwd,
839
+ logDir: request.logDir,
840
+ permissionMode: pipeline.config.permissionMode,
841
+ model: limits.model,
842
+ effort: limits.effort,
843
+ maxTurns: limits.maxTurns,
844
+ maxMinutes: limits.maxMinutes,
845
+ ...(request.jsonSchema === undefined ? {} : { jsonSchema: request.jsonSchema }),
846
+ ...(request.resultRequired === undefined
847
+ ? {}
848
+ : { resultRequired: request.resultRequired }),
849
+ });
850
+ }
851
+
852
+ /**
853
+ * Report a Stage the rate limit stopped, and raise the Ticket's release.
854
+ *
855
+ * The one place the pause is composed, because the conflict Stage reaches it by
856
+ * another road: the row reads as a pause rather than a cross, and the error
857
+ * carries the state a later Run resumes the Ticket from. Only the implement
858
+ * Stage can leave a Ticket short of `implemented`; every other Stage runs on
859
+ * work that is already on the branch.
860
+ */
861
+ async function releasedStage(
862
+ progress: Progress,
863
+ stage: StageName,
864
+ point: FailurePoint,
865
+ result: StageResult,
866
+ ): Promise<RateLimited> {
867
+ await progress.record(stageRow(stage, result, "⏸ rate limited"));
868
+ return new RateLimited(point, stage === "implement" ? "claimed" : "implemented");
869
+ }
870
+
871
+ /**
872
+ * Report a Stage that did not come back, and say what it costs the Ticket.
873
+ *
874
+ * The rate limit is the one Stage failure the Ticket did nothing to earn, so it
875
+ * releases the Ticket instead of ending it. Every other failure is the Stage's
876
+ * own, and its caller decides whether the fix budget can buy another.
877
+ */
878
+ async function stageDidNotFinish(
879
+ pipeline: Pipeline,
880
+ progress: Progress,
881
+ stage: "implement" | "verify" | "fix",
882
+ result: StageResult,
883
+ ): Promise<TicketFailure | RateLimited> {
884
+ if (result.failure === "rate-limited") {
885
+ return await releasedStage(progress, stage, stage, result);
886
+ }
887
+
888
+ await progress.record(stageRow(stage, result, `❌ ${stageFailureCell(result)}`));
889
+ return new TicketFailure(
890
+ stage,
891
+ describeStageFailure(stage, pipeline.config.stages[stage], result),
892
+ );
893
+ }
894
+
895
+ /**
896
+ * Put a Stage's Notes where they belong, before its own outcome is judged.
897
+ *
898
+ * Before, because a Stage that ran out of turns still noticed whatever it
899
+ * noticed, and the Ticket it noticed it on has no idea a Run is even happening.
900
+ * Losing the Notes would be a second cost for the same failure.
901
+ */
902
+ async function collectNotes(
903
+ pipeline: Pipeline,
904
+ ticket: number,
905
+ stage: NotingStage,
906
+ result: StageResult,
907
+ notes: RoutedNote[],
908
+ ): Promise<void> {
909
+ notes.push(
910
+ ...(await routeNotes(
911
+ {
912
+ ...standingNotesLookup(pipeline),
913
+ origin: ticket,
914
+ stage,
915
+ inProgress: pipeline.config.labels.inProgress,
916
+ standing: pipeline.standingNotes,
917
+ },
918
+ result.result,
919
+ )),
920
+ );
921
+ }
922
+
923
+ /**
924
+ * Record the title a code Stage answered for the whole branch, when it answered
925
+ * one that counts, so it names the pull request and outlives this Run.
926
+ *
927
+ * One that does not count costs the title alone, as a malformed Note costs that
928
+ * Note: the one before it, or the first commit subject, is used instead.
929
+ */
930
+ async function recordTitle(result: StageResult, record: ResumeRecord): Promise<void> {
931
+ const title = parseTitle(result.result);
932
+ if (title !== undefined) await record.advance({ title });
933
+ }
934
+
935
+ /** What the Run's standing Notes issue is found — and opened — with. */
936
+ function standingNotesLookup(pipeline: Pipeline): StandingNotesLookup {
937
+ return {
938
+ tracker: pipeline.tracker,
939
+ needsTriage: pipeline.config.labels.needsTriage,
940
+ ...(pipeline.log === undefined ? {} : { log: pipeline.log }),
941
+ };
942
+ }
943
+
944
+ /**
945
+ * The standing Notes issue's number for a Stage's prompt, or nothing when none
946
+ * is open yet.
947
+ *
948
+ * Asked before the Stage rather than after it, because what it buys is a Stage
949
+ * that reads what has already been reported before it writes a Note of its own.
950
+ * Nothing is opened for it: an issue is opened when a Note needs one.
951
+ */
952
+ async function standingNotesNumber(pipeline: Pipeline): Promise<number | undefined> {
953
+ return await pipeline.standingNotes.current(standingNotesLookup(pipeline));
954
+ }
955
+
956
+ /**
957
+ * How many commits the branch carries that the base branch does not, which is
958
+ * how both code Stages are asked whether they committed anything.
959
+ */
960
+ async function commitCount(pipeline: Pipeline, branch: string): Promise<number> {
961
+ const subjects = await pipeline.workspace.commitSubjects(branch, pipeline.baseBranch);
962
+ return subjects.length;
963
+ }
964
+
965
+ /**
966
+ * Push the branch a Stage has just committed on, so the work outlives the Host
967
+ * it was done on and a Run on any Host resumes from it (ADR-0004).
968
+ *
969
+ * A push that does not land is logged and nothing more, as a State write that
970
+ * does not land is: the remote then holds an earlier tip of the same work, and
971
+ * resuming from further back costs a Stage rather than being wrong. The push
972
+ * the pull request needs is a different one, and fails the Ticket where it is.
973
+ */
974
+ async function pushCommitted(
975
+ pipeline: Pipeline,
976
+ ticket: number,
977
+ worktree: string,
978
+ branch: string,
979
+ ): Promise<void> {
980
+ try {
981
+ await pipeline.workspace.push(worktree, branch);
982
+ } catch (error) {
983
+ pipeline.log?.(`#${ticket} could not push ${branch}: ${(error as Error).message}`);
984
+ }
985
+ }
986
+
987
+ async function implement(
988
+ pipeline: Pipeline,
989
+ issue: Issue,
990
+ worktree: string,
991
+ branch: string,
992
+ logDir: string,
993
+ progress: Progress,
994
+ notes: RoutedNote[],
995
+ record: ResumeRecord,
996
+ ): Promise<void> {
997
+ const stage = pipeline.config.stages.implement;
998
+ const result = await runStage(pipeline, "implement", {
999
+ prompt: implementPrompt(
1000
+ issue.url,
1001
+ pipeline.baseBranch,
1002
+ stage.extraPrompt,
1003
+ pipeline.selfHosted,
1004
+ await standingNotesNumber(pipeline),
1005
+ ),
1006
+ cwd: worktree,
1007
+ logDir,
1008
+ jsonSchema: CODE_STAGE_JSON_SCHEMA,
1009
+ // The title and the Notes are side channels, not the Stage's product: a
1010
+ // session that emitted neither has implemented the Ticket exactly as it
1011
+ // always did.
1012
+ resultRequired: false,
1013
+ });
1014
+ await collectNotes(pipeline, issue.number, "implement", result, notes);
1015
+ await recordTitle(result, record);
1016
+
1017
+ // Pushed whatever became of the Stage, like its Notes: a session that
1018
+ // committed and then ran into the rate limit still committed, and the Host
1019
+ // that resumes the Ticket may be another one.
1020
+ const commits = await commitCount(pipeline, branch);
1021
+ if (commits > 0) await pushCommitted(pipeline, issue.number, worktree, branch);
1022
+ if (!result.ok) throw await stageDidNotFinish(pipeline, progress, "implement", result);
1023
+
1024
+ // An agent that gave up silently leaves a clean branch behind. That is a
1025
+ // failure, not something to verify. A resumed Ticket's branch is not clean —
1026
+ // it carries what the Stage the rate limit stopped had committed — so this
1027
+ // asks the same question there: is there anything at all to grade. Whether it
1028
+ // is enough is the Verdict's business, not this guard's.
1029
+ if (commits === 0) {
1030
+ await progress.record(stageRow("implement", result, "❌ no commits"));
1031
+ throw new TicketFailure(
1032
+ "implement",
1033
+ "the implement Stage left no new commits on the branch",
1034
+ );
1035
+ }
1036
+
1037
+ await progress.record(stageRow("implement", result, "✅ committed"));
1038
+ }
1039
+
1040
+ /**
1041
+ * Refuse a worktree holding changes no commit carries, naming every path.
1042
+ *
1043
+ * Nothing is discarded here: a fix Stage sent in for it decides what belongs
1044
+ * to the Ticket, and a hand-off leaves the changes where a human can find them.
1045
+ * The summary names no Stage, because a resumed Ticket cannot say which one
1046
+ * left them: a fix Stage the rate limit stopped spent no budget.
1047
+ */
1048
+ async function requireCommitted(
1049
+ pipeline: Pipeline,
1050
+ worktree: string,
1051
+ progress: Progress,
1052
+ ): Promise<void> {
1053
+ const paths = await pipeline.workspace.uncommittedPaths(worktree);
1054
+ if (paths.length === 0) return;
1055
+
1056
+ await progress.record({ point: "checks", outcome: "❌ uncommitted work" });
1057
+ throw new TicketFailure(
1058
+ "checks",
1059
+ "the worktree holds changes no commit carries",
1060
+ paths.join("\n"),
1061
+ "uncommitted-work",
1062
+ );
1063
+ }
1064
+
1065
+ async function runChecks(
1066
+ pipeline: Pipeline,
1067
+ worktree: string,
1068
+ progress: Progress,
1069
+ ): Promise<void> {
1070
+ // One row for the whole gate, however many commands it is made of: which
1071
+ // command failed is the outcome, and its output is the hand-off's business.
1072
+ const startedAt = Date.now();
1073
+ const minutes = pipeline.config.checkTimeoutMinutes;
1074
+ for (const command of pipeline.config.checks) {
1075
+ const result = await pipeline.workspace.runCheck(command, worktree, minutes * 60_000);
1076
+ if (!result.ok) {
1077
+ // A Check that hung and one that failed are the same failure to the fix
1078
+ // budget and the hand-off; they are told apart only in what they say, so
1079
+ // that a fix Stage knows whether it is mending a hang or an assertion.
1080
+ await progress.record({
1081
+ point: "checks",
1082
+ outcome: `❌ \`${command}\` ${result.timedOut ? "timed out" : "failed"}`,
1083
+ durationMs: Date.now() - startedAt,
1084
+ });
1085
+ throw new TicketFailure(
1086
+ "checks",
1087
+ `Check \`${command}\` ${result.timedOut ? "timed out" : "failed"}`,
1088
+ result.timedOut ? killedEvidence(command, result.output, minutes) : result.output,
1089
+ "failed-check",
1090
+ );
1091
+ }
1092
+ }
1093
+ await progress.record({
1094
+ point: "checks",
1095
+ outcome: "✅ passed",
1096
+ durationMs: Date.now() - startedAt,
1097
+ });
1098
+ }
1099
+
1100
+ /**
1101
+ * What the Check printed before the kill, and then a line saying that a kill is
1102
+ * what ended it. A fix Stage is given the evidence and little else, so the
1103
+ * output alone would read as a suite that simply stopped mid-run.
1104
+ */
1105
+ function killedEvidence(command: string, output: string, minutes: number): string {
1106
+ const unit = minutes === 1 ? "minute" : "minutes";
1107
+ const trailer = `\`${command}\` was killed after ${minutes} ${unit} at the Check wall-clock limit: it hung rather than failing, and everything above is what it had printed by then.`;
1108
+ const printed = output.trimEnd();
1109
+ return printed === "" ? trailer : `${printed}\n\n${trailer}`;
1110
+ }
1111
+
1112
+ async function verify(
1113
+ pipeline: Pipeline,
1114
+ issue: Issue,
1115
+ worktree: string,
1116
+ logDir: string,
1117
+ progress: Progress,
1118
+ notes: RoutedNote[],
1119
+ ): Promise<Verdict> {
1120
+ const stage = pipeline.config.stages.verify;
1121
+ const result = await runStage(pipeline, "verify", {
1122
+ prompt: verifyPrompt(
1123
+ issue.url,
1124
+ stage.extraPrompt,
1125
+ pipeline.selfHosted,
1126
+ await standingNotesNumber(pipeline),
1127
+ ),
1128
+ cwd: worktree,
1129
+ logDir,
1130
+ jsonSchema: VERDICT_JSON_SCHEMA,
1131
+ });
1132
+
1133
+ // Before anything else is done with the Stage at all, as the code Stages do
1134
+ // it: a session that ran out of turns, or came back with a Verdict nothing
1135
+ // can be made of, still noticed whatever it noticed. The scratch work it
1136
+ // noticed it in is about to be discarded, so its Notes are all that is left —
1137
+ // and a worktree that will not discard them is no reason to lose them too.
1138
+ await collectNotes(pipeline, issue.number, "verify", result, notes);
1139
+
1140
+ // verify is allowed to write throwaway tests; none of them reach the PR.
1141
+ await pipeline.workspace.discardChanges(worktree);
1142
+
1143
+ if (!result.ok) throw await stageDidNotFinish(pipeline, progress, "verify", result);
1144
+
1145
+ let verdict: Verdict;
1146
+ try {
1147
+ verdict = parseVerdict(result.result);
1148
+ } catch (error) {
1149
+ await progress.record(stageRow("verify", result, "❌ no Verdict"));
1150
+ throw new TicketFailure(
1151
+ "verify",
1152
+ "the verify Stage did not return a usable Verdict",
1153
+ (error as Error).message,
1154
+ );
1155
+ }
1156
+
1157
+ const counts = countStatuses(verdict);
1158
+
1159
+ // The agent's own `pass` is advisory; this is the decision that counts.
1160
+ if (!passes(verdict)) {
1161
+ const unmet = unmetCriteria(verdict);
1162
+ if (unmet.length === 0) {
1163
+ await progress.record(stageRow("verify", result, "❌ no evidence"));
1164
+ throw new TicketFailure(
1165
+ "verify",
1166
+ "every criterion came back unverifiable, so there is no evidence to merge on",
1167
+ verdict.criteria.map((c) => `- ${c.text} — ${c.evidence}`).join("\n"),
1168
+ );
1169
+ }
1170
+ await progress.record(stageRow("verify", result, `❌ ${unmet.length} unmet`));
1171
+ throw new TicketFailure(
1172
+ "verify",
1173
+ `${unmet.length} of ${verdict.criteria.length} criteria unmet`,
1174
+ unmet.map((c) => `- ${c.text} — ${c.evidence}`).join("\n"),
1175
+ "unmet-criteria",
1176
+ );
1177
+ }
1178
+
1179
+ const summary = `${counts.met} met · ${counts.unverifiable} unverifiable`;
1180
+ await progress.record(stageRow("verify", result, `✅ ${summary}`));
1181
+ pipeline.log?.(`#${issue.number} verified · ${summary}`);
1182
+ return verdict;
1183
+ }
1184
+
1185
+ /**
1186
+ * What the fix budget buys: a fresh session on the same branch in the same
1187
+ * worktree, handed the failure and its evidence and nothing else to do.
1188
+ *
1189
+ * It drives no plugin skill. The implement skill would re-read the Ticket and
1190
+ * start over, where what is wanted here is one concrete defect mended.
1191
+ */
1192
+ async function fix(
1193
+ pipeline: Pipeline,
1194
+ issue: Issue,
1195
+ worktree: string,
1196
+ branch: string,
1197
+ logDir: string,
1198
+ failure: FixFailure,
1199
+ progress: Progress,
1200
+ notes: RoutedNote[],
1201
+ record: ResumeRecord,
1202
+ ): Promise<void> {
1203
+ const stage = pipeline.config.stages.fix;
1204
+ pipeline.log?.(`#${issue.number} fixing · ${failure.summary}`);
1205
+
1206
+ // Read before the Stage runs, because the implement Stage's work is already
1207
+ // on the branch: what this asks afterwards is whether the branch grew, not
1208
+ // whether it has anything on it at all.
1209
+ const commitsBefore = await commitCount(pipeline, branch);
1210
+
1211
+ const result = await runStage(pipeline, "fix", {
1212
+ prompt: fixPrompt(
1213
+ issue.url,
1214
+ failure,
1215
+ pipeline.baseBranch,
1216
+ stage.extraPrompt,
1217
+ pipeline.selfHosted,
1218
+ await standingNotesNumber(pipeline),
1219
+ ),
1220
+ cwd: worktree,
1221
+ logDir,
1222
+ jsonSchema: CODE_STAGE_JSON_SCHEMA,
1223
+ resultRequired: false,
1224
+ });
1225
+ await collectNotes(pipeline, issue.number, "fix", result, notes);
1226
+ await recordTitle(result, record);
1227
+
1228
+ // Pushed whatever became of the Stage, as the implement Stage's work is.
1229
+ const grew = (await commitCount(pipeline, branch)) > commitsBefore;
1230
+ if (grew) await pushCommitted(pipeline, issue.number, worktree, branch);
1231
+ if (!result.ok) throw await stageDidNotFinish(pipeline, progress, "fix", result);
1232
+
1233
+ // A session that came back clean mended nothing, whatever it says. Believing
1234
+ // it costs the Ticket a whole second pass of the Checks, the Verdict and CI
1235
+ // over a branch nobody touched, which can only fail the way it just did — and
1236
+ // a progress row claiming the Stage committed. The budget is already spent,
1237
+ // so this ends the Ticket rather than buying another try.
1238
+ //
1239
+ // A branch that grew is the whole signal, which is not the same as one that
1240
+ // changed: a session that squashed the branch shorter, or amended in place,
1241
+ // is read here as having committed nothing.
1242
+ if (!grew) {
1243
+ await progress.record(stageRow("fix", result, "❌ no commits"));
1244
+ throw new TicketFailure("fix", "the fix Stage left no new commits on the branch");
1245
+ }
1246
+
1247
+ await progress.record(stageRow("fix", result, "✅ committed"));
1248
+ }
1249
+
1250
+ /**
1251
+ * Send one session into the stopped rebase to resolve it.
1252
+ *
1253
+ * It is not what the fix budget buys and it does not spend it: a conflict is
1254
+ * the base branch moving on underneath a branch, not a defect in the branch,
1255
+ * and a Ticket that hits one has done nothing wrong yet. The budget covers what
1256
+ * is left if this fails.
1257
+ *
1258
+ * The tree decides whether it worked, not the session's exit status. A Stage
1259
+ * that finished the rebase and then ran out of turns has done the job; one that
1260
+ * came back clean because it quietly abandoned the rebase has not, and only the
1261
+ * worktree can tell the difference.
1262
+ *
1263
+ * A Stage the rate limit stopped is read the same way, and only then released:
1264
+ * one that had already finished the rebase leaves nothing that needs an agent
1265
+ * session, so the Ticket carries on to the Checks, the pull request and CI.
1266
+ */
1267
+ async function resolveConflict(
1268
+ pipeline: Pipeline,
1269
+ issue: Issue,
1270
+ worktree: string,
1271
+ branch: string,
1272
+ logDir: string,
1273
+ conflict: string,
1274
+ progress: Progress,
1275
+ ): Promise<void> {
1276
+ pipeline.log?.(`#${issue.number} resolving a rebase conflict`);
1277
+
1278
+ const failure = await conflictStage(
1279
+ pipeline,
1280
+ issue,
1281
+ worktree,
1282
+ branch,
1283
+ logDir,
1284
+ conflict,
1285
+ progress,
1286
+ );
1287
+ if (failure === undefined) return;
1288
+
1289
+ // Nothing may leave this function with a rebase still in the worktree, least
1290
+ // of all the fix Stage the budget may still buy: it has to have a branch to
1291
+ // commit on, and the hand-off behind it has to have one it can push.
1292
+ await pipeline.workspace.abortRebase(worktree);
1293
+ throw failure;
1294
+ }
1295
+
1296
+ /**
1297
+ * The Stage, and what is left of the conflict once it has finished: `undefined`
1298
+ * when the worktree came back rebased.
1299
+ *
1300
+ * It returns its failure rather than throwing it so that nothing — not a Stage
1301
+ * that fell over, not git itself — can skip the abort its caller owes the
1302
+ * worktree.
1303
+ */
1304
+ async function conflictStage(
1305
+ pipeline: Pipeline,
1306
+ issue: Issue,
1307
+ worktree: string,
1308
+ branch: string,
1309
+ logDir: string,
1310
+ conflict: string,
1311
+ progress: Progress,
1312
+ ): Promise<TicketFailure | RateLimited | undefined> {
1313
+ const stage = pipeline.config.stages.conflict;
1314
+ try {
1315
+ const result = await runStage(pipeline, "conflict", {
1316
+ prompt: conflictPrompt(
1317
+ issue.url,
1318
+ conflict,
1319
+ pipeline.baseBranch,
1320
+ stage.extraPrompt,
1321
+ pipeline.selfHosted,
1322
+ ),
1323
+ cwd: worktree,
1324
+ logDir,
1325
+ });
1326
+
1327
+ const state = await pipeline.workspace.rebaseState(worktree, pipeline.baseBranch);
1328
+ if (state.resolved) {
1329
+ // The worktree decides the row, as it decides the outcome: a Stage that
1330
+ // ran out of turns, or into the rate limit, after finishing the rebase
1331
+ // did the job it was sent to do.
1332
+ await progress.record(stageRow("conflict", result, "✅ rebased"));
1333
+ // The rebase rewrote the branch, and the resolution is a commit of the
1334
+ // Stage's like any other.
1335
+ await pushCommitted(pipeline, issue.number, worktree, branch);
1336
+ return undefined;
1337
+ }
1338
+
1339
+ // A rate limit left the conflict exactly as it found it: nothing for a fix
1340
+ // Stage to mend and nothing to blame the Ticket for. The caller still owes
1341
+ // the worktree its abort, so the branch the resumed Run rebases is clean.
1342
+ if (result.failure === "rate-limited") {
1343
+ return await releasedStage(progress, "conflict", "rebase", result);
1344
+ }
1345
+
1346
+ await progress.record(stageRow("conflict", result, "❌ unresolved"));
1347
+ return new TicketFailure(
1348
+ "rebase",
1349
+ result.ok
1350
+ ? `the conflict Stage did not finish the rebase onto ${pipeline.baseBranch}`
1351
+ : describeStageFailure("conflict", stage, result),
1352
+ [conflict, state.unresolved].join("\n\n"),
1353
+ "unresolved-conflict",
1354
+ );
1355
+ } catch (error) {
1356
+ // The Stage never ran, or git could not be asked what it left behind.
1357
+ // Neither is a defect in the branch, so no fix Stage is offered for it.
1358
+ // Nothing read the worktree, so nothing here knows what the Stage left.
1359
+ await progress.record({ point: "conflict", outcome: "❌ unknown" });
1360
+ return asTicketFailure(error, "rebase");
1361
+ }
1362
+ }
1363
+
1364
+ interface PullRequestSubject {
1365
+ issue: Issue;
1366
+ branch: string;
1367
+ worktree: string;
1368
+ verdict: Verdict;
1369
+ title: string;
1370
+ }
1371
+
1372
+ /**
1373
+ * Push the branch, then open the pull request or bring the open one up to date.
1374
+ *
1375
+ * A second pass comes back to a pull request that already exists: the push is
1376
+ * what GitHub re-runs its checks on, and the title and body are rewritten so
1377
+ * the subject and the Verdict a human reads there are the ones that will reach
1378
+ * the base branch.
1379
+ *
1380
+ * One that already exists is also taken out of draft, because a Ticket resumed
1381
+ * after a hand-off comes back to the pull request the hand-off drafted and a
1382
+ * draft cannot be merged. Here rather than at the merge: a draft pull request
1383
+ * often runs no workflows at all, so the wait for CI below would read it as
1384
+ * "no checks" and end the Ticket before the merge was ever asked for.
1385
+ */
1386
+ async function publishPullRequest(
1387
+ pipeline: Pipeline,
1388
+ { issue, branch, worktree, verdict, title }: PullRequestSubject,
1389
+ existing: number | undefined,
1390
+ ): Promise<number> {
1391
+ await pipeline.workspace.push(worktree, branch);
1392
+ const body = pullRequestBody({
1393
+ ticket: issue.number,
1394
+ verdict,
1395
+ runId: pipeline.runId,
1396
+ host: pipeline.host,
1397
+ });
1398
+
1399
+ if (existing !== undefined) {
1400
+ // Retitled as well, so a title a fix Stage answered after the pull request
1401
+ // opened is the one it shows, as it is the subject that lands.
1402
+ await pipeline.tracker.updatePullRequestTitle(existing, title);
1403
+ await pipeline.tracker.updatePullRequestBody(existing, body);
1404
+ await pipeline.tracker.markPullRequestReady(existing);
1405
+ return existing;
1406
+ }
1407
+
1408
+ const pr = await pipeline.tracker.createPullRequest({
1409
+ base: pipeline.baseBranch,
1410
+ head: branch,
1411
+ title,
1412
+ body,
1413
+ draft: false,
1414
+ });
1415
+ return pr.number;
1416
+ }
1417
+
1418
+ /**
1419
+ * A red, unfinished or conflicting pull request is a failure whatever the
1420
+ * gates say. Turning `gates.ci` off only tolerates a pull request that has no
1421
+ * checks at all.
1422
+ */
1423
+ async function requireGreenCi(
1424
+ pipeline: Pipeline,
1425
+ pullRequest: number,
1426
+ progress: Progress,
1427
+ ): Promise<void> {
1428
+ const startedAt = Date.now();
1429
+ const outcome = await pipeline.tracker.waitForCi(
1430
+ pullRequest,
1431
+ pipeline.config.ciTimeoutMinutes * 60_000,
1432
+ );
1433
+ const record = (cell: string) =>
1434
+ progress.record({ point: "ci", outcome: cell, durationMs: Date.now() - startedAt });
1435
+
1436
+ switch (outcome.state) {
1437
+ case "passed":
1438
+ await record("✅ passed");
1439
+ return;
1440
+ case "failed":
1441
+ await record("❌ failed");
1442
+ // The names are the line a human reads; the log excerpt is what a fix
1443
+ // Stage works from, and it is empty whenever none could be fetched.
1444
+ throw new TicketFailure("ci", outcome.summary, outcome.excerpt, "failed-ci");
1445
+ case "timed-out":
1446
+ await record("❌ timed out");
1447
+ throw new TicketFailure(
1448
+ "ci",
1449
+ `the pull request checks did not finish within ${pipeline.config.ciTimeoutMinutes} minutes`,
1450
+ );
1451
+ case "conflicting":
1452
+ // The Landing keeps the Run's own Tickets from moving the Base branch
1453
+ // under a pull request, but not a human merging on GitHub meanwhile. A
1454
+ // fix Stage has nothing to act on, so no fix kind: a human takes it.
1455
+ await record("❌ conflicting");
1456
+ throw new TicketFailure(
1457
+ "ci",
1458
+ `the pull request conflicts with \`${pipeline.baseBranch}\`, so GitHub will neither run its checks nor merge it`,
1459
+ );
1460
+ case "none":
1461
+ // A gate switched off is worth a row of its own: the Ticket merged on
1462
+ // nobody's word but the pipeline's own Checks.
1463
+ await record(pipeline.config.gates.ci ? "❌ no checks" : "⚠️ no checks");
1464
+ if (!pipeline.config.gates.ci) return;
1465
+ throw new TicketFailure(
1466
+ "ci",
1467
+ "the pull request has no checks, so CI cannot gate the merge",
1468
+ );
1469
+ }
1470
+ }
1471
+
1472
+ interface Release {
1473
+ issue: Issue;
1474
+ user: string;
1475
+ branch: string;
1476
+ limit: RateLimited;
1477
+ /** The Ticket's State file, which the release brings up to date and leaves. */
1478
+ record: ResumeRecord;
1479
+ /** Whether the Fix budget was spent by a failure of the Ticket's own. */
1480
+ fixUsed: boolean;
1481
+ notes: RoutedNote[];
1482
+ }
1483
+
1484
+ /**
1485
+ * Release the Ticket: undo the Claim and leave a State file behind.
1486
+ *
1487
+ * The opposite of a hand-off, and deliberately quiet. Nothing about the Ticket
1488
+ * failed, nobody has to look at it, and the work already on its branch is worth
1489
+ * keeping — so the branch and the worktree stay, no comment is posted, no draft
1490
+ * pull request is opened, and the Ticket goes back on the Frontier for a Run
1491
+ * started after the limit has reset.
1492
+ */
1493
+ async function release(
1494
+ pipeline: Pipeline,
1495
+ { issue, user, branch, limit, record, fixUsed, notes }: Release,
1496
+ ): Promise<TicketOutcome> {
1497
+ const { tracker, config } = pipeline;
1498
+ const ticket = issue.number;
1499
+
1500
+ // Brought up to date before the Claim comes off: a Ticket back on the Frontier
1501
+ // whose state is out of date is one the next Run would redo Stages for.
1502
+ await record.advance({ state: limit.state, fixUsed });
1503
+
1504
+ // The claim, undone in the order it was made, so the assignee — which is what
1505
+ // another Run reads to tell a taken Ticket from a free one — comes off last.
1506
+ await tracker.addLabel(ticket, config.labels.readyForAgent);
1507
+ await tracker.removeLabel(ticket, config.labels.inProgress);
1508
+ await tracker.unassign(ticket, user);
1509
+ pipeline.log?.(`#${ticket} released at ${limit.point} · rate limit · ${branch}`);
1510
+
1511
+ return { outcome: "released", ticket, title: issue.title, branch, stage: limit.point, notes };
1512
+ }
1513
+
1514
+ /** The worktree a hand-off has to hand, which is not always one of this Run's. */
1515
+ interface HandOffWorktree {
1516
+ /** Where the branch is checked out, which is where a human is sent. */
1517
+ path: string;
1518
+ /**
1519
+ * Whether this Run may push out of it: true for a worktree it created or was
1520
+ * resumed into, where a Stage of it could have left work. A worktree the
1521
+ * pipeline only found the branch checked out in holds a human's work.
1522
+ */
1523
+ pushable: boolean;
1524
+ }
1525
+
1526
+ interface HandOff {
1527
+ issue: Issue;
1528
+ user: string;
1529
+ branch: string;
1530
+ /** Where the work is, absent when the Ticket failed before it had a worktree. */
1531
+ worktree?: HandOffWorktree;
1532
+ /**
1533
+ * Whether the State stays for a later Run to resume from: what the branch
1534
+ * carries is the pipeline's, whether or not this Run may push it.
1535
+ */
1536
+ keepsState: boolean;
1537
+ pullRequest: number | undefined;
1538
+ failure: TicketFailure;
1539
+ /** Whether the Ticket's fix budget had already been spent when this failure came. */
1540
+ fixUsed: boolean;
1541
+ /** The Ticket's State file, which the hand-off either leaves current or removes. */
1542
+ record: ResumeRecord;
1543
+ notes: RoutedNote[];
1544
+ }
1545
+
1546
+ /**
1547
+ * Hand the Ticket to a human: a draft PR to review, a comment naming where the
1548
+ * work is, and the labels a human filters on. The branch, the worktree and the
1549
+ * State file stay put, so a human who relabels the Ticket `ready-for-agent`
1550
+ * hands it back and the next Run carries on from what it reached. The Stages'
1551
+ * transcripts go up beside the State, since the Host they were written on may
1552
+ * be gone by the time a human looks, and the comment says where they and the
1553
+ * branch are. The draft PR's body says where they are too, once they are
1554
+ * kept: a draft is opened first, because the State records it, and one that
1555
+ * was already open is rewritten, since its body is an earlier Run's.
1556
+ *
1557
+ * A Ticket handed over before its worktree was created has none: nothing was
1558
+ * branched, so there is no directory to name and nothing to push a draft PR out
1559
+ * of. Both are left out rather than written as a path that is not there and a
1560
+ * push that fails.
1561
+ *
1562
+ * Where a human is sent and what the pipeline pushes are two different facts. A
1563
+ * Ticket refused at setup over a branch still checked out somewhere names that
1564
+ * worktree and stops there: the work in it is a human's, and pushing it or
1565
+ * opening a PR that says `Closes #<n>` over it would claim it for this Run.
1566
+ *
1567
+ * The same fact mostly decides the State file. A worktree this Run may push out
1568
+ * of is one a Stage of it worked in, and what it left is the pipeline's to
1569
+ * resume; a branch in the way at setup leaves nothing of the pipeline's behind,
1570
+ * and a file kept over it would let a later Run resume into a human's work and
1571
+ * run an implement Stage over it — which is what refusing at setup exists to
1572
+ * prevent. The one worktree this Run may not push out of whose State stays is
1573
+ * one parted from the remote branch: both copies are the pipeline's, and
1574
+ * pushing either over the other is the choice the human is handed.
1575
+ */
1576
+ async function handOff(
1577
+ pipeline: Pipeline,
1578
+ {
1579
+ issue,
1580
+ user,
1581
+ branch,
1582
+ worktree,
1583
+ keepsState,
1584
+ pullRequest,
1585
+ failure,
1586
+ fixUsed,
1587
+ record,
1588
+ notes,
1589
+ }: HandOff,
1590
+ ): Promise<TicketOutcome> {
1591
+ const { tracker, workspace, config } = pipeline;
1592
+ const ticket = issue.number;
1593
+
1594
+ // Nothing of this Run's is on the branch, so nothing may leave the Ticket
1595
+ // looking resumable: the next Run must not implement over what a human holds.
1596
+ // Wrapped because the hand-off itself — the draft PR, the comment, the labels
1597
+ // — is what a human is waiting for, and no file is worth losing it over.
1598
+ if (!keepsState) {
1599
+ try {
1600
+ await workspace.removeState(ticket);
1601
+ } catch (error) {
1602
+ pipeline.log?.(
1603
+ `#${ticket} handed off, but clearing its State file failed: ${(error as Error).message}`,
1604
+ );
1605
+ }
1606
+ }
1607
+
1608
+ const draftBody = {
1609
+ ticket,
1610
+ stage: failure.point,
1611
+ failure: failure.summary,
1612
+ runId: pipeline.runId,
1613
+ };
1614
+ // Whether the draft's body is one this hand-off wrote, naming no transcripts.
1615
+ // One it only converted still says what its Run said, which is not this.
1616
+ let drafted = false;
1617
+ if (pullRequest !== undefined) {
1618
+ await tracker.convertPullRequestToDraft(pullRequest);
1619
+ } else if (worktree?.pushable === true) {
1620
+ // A draft PR is worth trying for, but never worth losing the relabel over.
1621
+ try {
1622
+ await workspace.push(worktree.path, branch);
1623
+ const pr = await tracker.createPullRequest({
1624
+ base: pipeline.baseBranch,
1625
+ head: branch,
1626
+ // Nothing here is merged, so there is no commit subject worth deriving.
1627
+ title: issue.title,
1628
+ body: draftPullRequestBody(draftBody),
1629
+ draft: true,
1630
+ });
1631
+ pullRequest = pr.number;
1632
+ drafted = true;
1633
+ } catch (error) {
1634
+ pipeline.log?.(`#${ticket} could not open a draft PR: ${(error as Error).message}`);
1635
+ }
1636
+ }
1637
+
1638
+ if (keepsState) {
1639
+ // Written after the draft pull request, because that pull request is part of
1640
+ // what a resuming Run must not open a second one beside.
1641
+ //
1642
+ // The Fix budget goes back unspent: the Ticket only comes back through a
1643
+ // human's hands, and whatever they did to it is what the fresh budget is
1644
+ // for. Nothing is lost by it — the hand-off comment says the budget was
1645
+ // spent, and the Claim only marks that comment as history.
1646
+ await record.advance({
1647
+ fixUsed: false,
1648
+ ...(pullRequest === undefined ? {} : { pullRequest }),
1649
+ });
1650
+ }
1651
+ // Only beside a State that stays, because they go when it does, and after
1652
+ // it, so the State they sit beside is the one a resuming Run reads.
1653
+ const transcripts = keepsState ? await keepTranscripts(pipeline, ticket) : undefined;
1654
+ // A draft this hand-off opened went up before anything was kept, and one it
1655
+ // converted still carries an earlier body, so either learns where only now.
1656
+ if (pullRequest !== undefined && !(drafted && transcripts === undefined)) {
1657
+ try {
1658
+ await tracker.updatePullRequestBody(
1659
+ pullRequest,
1660
+ draftPullRequestBody({
1661
+ ...draftBody,
1662
+ ...(transcripts === undefined ? {} : { transcripts }),
1663
+ }),
1664
+ );
1665
+ } catch (error) {
1666
+ pipeline.log?.(
1667
+ `#${ticket} could not rewrite the body of PR #${pullRequest}: ${(error as Error).message}`,
1668
+ );
1669
+ }
1670
+ }
1671
+ const onRemote = await branchOnRemote(pipeline, ticket, branch);
1672
+
1673
+ await tracker.comment(
1674
+ ticket,
1675
+ handoffComment({
1676
+ stage: failure.point,
1677
+ failure: failure.summary,
1678
+ branch,
1679
+ onRemote,
1680
+ ...(worktree === undefined ? {} : { worktree: worktree.path }),
1681
+ ...(transcripts === undefined ? {} : { transcripts }),
1682
+ evidence: failure.evidence,
1683
+ fixUsed,
1684
+ ...(pullRequest === undefined ? {} : { pullRequest }),
1685
+ }),
1686
+ );
1687
+ await tracker.removeLabel(ticket, config.labels.inProgress);
1688
+ await tracker.addLabel(ticket, config.labels.readyForHuman);
1689
+ await tracker.unassign(ticket, user);
1690
+ pipeline.log?.(`#${ticket} handed off at ${failure.point} · ${failure.summary}`);
1691
+
1692
+ return {
1693
+ outcome: "handed-off",
1694
+ ticket,
1695
+ title: issue.title,
1696
+ branch,
1697
+ stage: failure.point,
1698
+ failure: failure.summary,
1699
+ notes,
1700
+ ...(pullRequest === undefined ? {} : { pullRequest }),
1701
+ };
1702
+ }
1703
+
1704
+ /**
1705
+ * Keep the transcripts of the Stages this Run ran for a handed-off Ticket on
1706
+ * the remote, where a human can still read them once this Host is gone, and
1707
+ * say where.
1708
+ *
1709
+ * Nothing when that fails, and the failure logged: the hand-off is what a
1710
+ * human is waiting for, and the transcripts are still on this Host for as long
1711
+ * as it lasts.
1712
+ */
1713
+ async function keepTranscripts(
1714
+ pipeline: Pipeline,
1715
+ ticket: number,
1716
+ ): Promise<KeptTranscripts | undefined> {
1717
+ try {
1718
+ return await pipeline.workspace.keepTranscripts(ticket, pipeline.runId);
1719
+ } catch (error) {
1720
+ pipeline.log?.(
1721
+ `#${ticket} handed off, but keeping its transcripts failed: ${(error as Error).message}`,
1722
+ );
1723
+ return undefined;
1724
+ }
1725
+ }
1726
+
1727
+ /**
1728
+ * Whether the remote has the branch, for a hand-off comment that says so only
1729
+ * when it does. A remote that cannot be asked counts as no: saying less than
1730
+ * is so sends nobody looking for a branch that is not there.
1731
+ */
1732
+ async function branchOnRemote(pipeline: Pipeline, ticket: number, branch: string): Promise<boolean> {
1733
+ try {
1734
+ return await pipeline.workspace.hasRemoteBranch(branch);
1735
+ } catch (error) {
1736
+ pipeline.log?.(`#${ticket} could not ask the remote for ${branch}: ${(error as Error).message}`);
1737
+ return false;
1738
+ }
1739
+ }
1740
+
1741
+ /**
1742
+ * One Stage's row, with the turns and wall-clock the runner reported.
1743
+ *
1744
+ * A Stage the runner could not put a turn count on gets no count rather than a
1745
+ * zero: nothing ran is not the same as nothing was needed.
1746
+ */
1747
+ function stageRow(
1748
+ stage: ProgressPoint,
1749
+ result: StageResult,
1750
+ outcome: string,
1751
+ ): ProgressRow {
1752
+ return {
1753
+ point: stage,
1754
+ outcome,
1755
+ ...(result.turns === undefined ? {} : { turns: result.turns }),
1756
+ durationMs: result.durationMs,
1757
+ };
1758
+ }
1759
+
1760
+ /** The limits a Stage was given, which are half of what its failure means. */
1761
+ interface StageLimits {
1762
+ maxTurns: number;
1763
+ maxMinutes: number;
1764
+ }
1765
+
1766
+ /**
1767
+ * Why a Stage did not finish, said twice: the words a hand-off comment reads in
1768
+ * and the two the progress table has room for. Kept in one entry per failure so
1769
+ * a new one cannot be given a sentence and left without a cell.
1770
+ */
1771
+ const STAGE_FAILURES: Record<
1772
+ StageFailure,
1773
+ { cell: string; sentence: (limits: StageLimits) => string }
1774
+ > = {
1775
+ "rate-limited": {
1776
+ cell: "rate limited",
1777
+ // The cell is all any path reads today: a rate-limited Stage releases the
1778
+ // Ticket rather than ending it, so no hand-off comment is written about one.
1779
+ // The sentence is kept true rather than dropped, because the table is one
1780
+ // entry per failure and the next path to need it must not have to invent it.
1781
+ sentence: () => "hit the subscription rate limit",
1782
+ },
1783
+ "timed-out": {
1784
+ cell: "timed out",
1785
+ sentence: (limits) => `ran past its ${limits.maxMinutes} minute limit`,
1786
+ },
1787
+ "turn-capped": {
1788
+ cell: "turn capped",
1789
+ sentence: (limits) => `hit its ${limits.maxTurns} turn limit`,
1790
+ },
1791
+ "nonzero-exit": { cell: "exited non-zero", sentence: () => "exited non-zero" },
1792
+ "invalid-result": {
1793
+ cell: "invalid result",
1794
+ sentence: () => "returned output its schema rejected",
1795
+ },
1796
+ };
1797
+
1798
+ /** A Stage that came back without saying why gets the one word that is true. */
1799
+ const UNEXPLAINED = { cell: "failed", sentence: () => "failed" } as const;
1800
+
1801
+ function stageFailure(result: StageResult) {
1802
+ return result.failure ? STAGE_FAILURES[result.failure] : UNEXPLAINED;
1803
+ }
1804
+
1805
+ function describeStageFailure(
1806
+ stage: string,
1807
+ limits: StageLimits,
1808
+ result: StageResult,
1809
+ ): string {
1810
+ return `the ${stage} Stage ${stageFailure(result).sentence(limits)}`;
1811
+ }
1812
+
1813
+ /** The same failure, short enough for a table cell. */
1814
+ function stageFailureCell(result: StageResult): string {
1815
+ return stageFailure(result).cell;
1816
+ }