ticket-runner 0.6.4 → 0.6.6

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 (50) hide show
  1. package/README.ko.md +5 -5
  2. package/README.md +4 -4
  3. package/docs/templates/operator-skill.md +81 -16
  4. package/package.json +1 -1
  5. package/src/acceptance-criteria.ts +99 -2
  6. package/src/adapters/claude-agent-runner.ts +5 -5
  7. package/src/adapters/exec.ts +32 -4
  8. package/src/adapters/gh-tracker.ts +276 -60
  9. package/src/adapters/git-workspace.ts +27 -10
  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 +22 -4
  16. package/src/conventions.ts +22 -19
  17. package/src/credential.ts +14 -13
  18. package/src/criteria.ts +102 -52
  19. package/src/failing-base.ts +7 -7
  20. package/src/failure-message.ts +72 -0
  21. package/src/guards.ts +21 -6
  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 +14 -11
  28. package/src/notes.ts +19 -7
  29. package/src/operator-skill.ts +2 -2
  30. package/src/orchestrator.ts +758 -275
  31. package/src/outside-fault.ts +103 -0
  32. package/src/ports/agent-runner.ts +1 -1
  33. package/src/ports/tracker.ts +29 -15
  34. package/src/ports/workspace.ts +52 -24
  35. package/src/progress.ts +42 -7
  36. package/src/prompts.ts +242 -34
  37. package/src/readiness.ts +11 -11
  38. package/src/remove.ts +7 -7
  39. package/src/resume.ts +28 -20
  40. package/src/run-log.ts +5 -5
  41. package/src/run.ts +55 -13
  42. package/src/staleness.ts +14 -14
  43. package/src/start.ts +29 -16
  44. package/src/stranded.ts +19 -19
  45. package/src/templates.ts +398 -149
  46. package/src/title.ts +106 -8
  47. package/src/transcript-home.ts +49 -0
  48. package/src/verdict.ts +132 -27
  49. package/src/version-number.ts +13 -13
  50. package/src/version-pr.ts +12 -12
@@ -0,0 +1,103 @@
1
+ /**
2
+ * A fault of GitHub's or of the Host's, which says nothing about the Ticket.
3
+ *
4
+ * Read off what `gh` and git print, since that is all either says about why it
5
+ * failed: GitHub answering with a 5xx status or with a response that is not
6
+ * complete JSON, and git unable to connect to or authenticate with the remote.
7
+ * A Ticket that meets one is released rather than handed off, as over a
8
+ * failing base branch: a human relabelling it would change nothing in its work,
9
+ * and every Ticket behind it would meet the same fault.
10
+ *
11
+ * Everything else a command prints is the Ticket's to answer for, as before: a
12
+ * GitHub 4xx, and a git failure that persists, such as a pull refused over a
13
+ * base branch that has really diverged.
14
+ */
15
+
16
+ /** Whose side the fault is on: GitHub's, or the git remote's. */
17
+ export type FaultSide = "github" | "remote";
18
+
19
+ /** A command that failed for a fault outside the Ticket, and how it failed. */
20
+ export class OutsideFault extends Error {
21
+ constructor(
22
+ readonly side: FaultSide,
23
+ /** The command as a human would type it, on one line. */
24
+ readonly command: string,
25
+ /** The first line of what it printed, which is what the Run's last line quotes. */
26
+ readonly line: string,
27
+ message: string,
28
+ ) {
29
+ super(message);
30
+ this.name = "OutsideFault";
31
+ }
32
+ }
33
+
34
+ /**
35
+ * GitHub failing on its own side: a 5xx status as `gh` reports it, and a
36
+ * response `gh` could not read as JSON, which is how a gateway that cut the
37
+ * answer short shows.
38
+ */
39
+ const GITHUB_FAULTS = [
40
+ /\bHTTP 5\d\d\b/,
41
+ /unexpected end of JSON input/i,
42
+ /invalid character .{1,12} looking for beginning of value/,
43
+ ];
44
+
45
+ /**
46
+ * git unable to reach the remote or to be let in. `Could not read from remote
47
+ * repository` is not among them: git says it after a repository that does not
48
+ * exist as well, which no wait mends.
49
+ */
50
+ const REMOTE_FAULTS = [
51
+ /Permission denied \(publickey/i,
52
+ /Could not resolve host/i,
53
+ /Authentication failed/i,
54
+ /could not read (Username|Password) for/i,
55
+ /Connection refused/i,
56
+ /Connection timed out/i,
57
+ /Operation timed out/i,
58
+ /Connection reset by peer/i,
59
+ /Failed to connect to/i,
60
+ ];
61
+
62
+ /** The remote answering with a 5xx, which a push it failed on reports too. */
63
+ const REMOTE_5XX = [/The requested URL returned error: 5\d\d/, /RPC failed; HTTP 5\d\d/];
64
+
65
+ /** Whether `gh` printed a fault of GitHub's own. */
66
+ export function isGitHubFault(output: string): boolean {
67
+ return GITHUB_FAULTS.some((pattern) => pattern.test(output));
68
+ }
69
+
70
+ /**
71
+ * A push the remote, or a hook before it, refused. A connection that cannot
72
+ * be made fails before git gets that far, so the words of one printed beside
73
+ * it are a pre-push hook's own output, such as a test that could not reach
74
+ * its database, and no fault of the remote's.
75
+ */
76
+ const PUSH_REFUSED = /failed to push some refs/;
77
+
78
+ /** Whether git printed that it could not connect to or authenticate with the remote. */
79
+ export function isRemoteFault(output: string): boolean {
80
+ if (REMOTE_5XX.some((pattern) => pattern.test(output))) return true;
81
+ return !PUSH_REFUSED.test(output) && REMOTE_FAULTS.some((pattern) => pattern.test(output));
82
+ }
83
+
84
+ /**
85
+ * Whose fault a failed `command` is, from what it printed, or nothing when it
86
+ * is no fault outside the Ticket. Only `gh` speaks for GitHub and only git for
87
+ * the remote, so a Check that happens to print the same words is never one.
88
+ */
89
+ export function faultSide(command: string, output: string): FaultSide | undefined {
90
+ if (command === "gh" && isGitHubFault(output)) return "github";
91
+ if (command === "git" && isRemoteFault(output)) return "remote";
92
+ return undefined;
93
+ }
94
+
95
+ /** The first line of `output` with anything on it, trimmed; empty when there is none. */
96
+ export function firstLine(output: string): string {
97
+ return (
98
+ output
99
+ .split(/\r?\n/)
100
+ .map((line) => line.trim())
101
+ .find((line) => line !== "") ?? ""
102
+ );
103
+ }
@@ -65,7 +65,7 @@ export interface StageRequest {
65
65
  * Whether a Stage that emitted no structured output has failed. Defaults to
66
66
  * true.
67
67
  *
68
- * It is the verify Stage's Verdict that makes it true there: a session that
68
+ * It is the verify Stage's verdict that makes it true there: a session that
69
69
  * graded nothing has done none of its job. A schema that only carries Notes
70
70
  * is a side channel the Stage may have had nothing to put in, and failing a
71
71
  * Ticket over an empty one would be failing it for finding nothing.
@@ -40,7 +40,7 @@ export interface Issue {
40
40
  * Whether the issue is closed.
41
41
  *
42
42
  * Only ever asked of a Ticket the pipeline kept local state for: a Run sweeps
43
- * its State files before it does anything else, and a Ticket that has closed
43
+ * its state files before it does anything else, and a Ticket that has closed
44
44
  * since is one there is nothing left to resume.
45
45
  */
46
46
  closed: boolean;
@@ -128,13 +128,14 @@ export interface CreatePullRequest {
128
128
  * The outcome of waiting for a pull request's CI checks. Distinct from a Check,
129
129
  * which is a command the pipeline runs itself (GLOSSARY.md).
130
130
  *
131
- * `none` means the PR has no checks at all, which `gates.ci` treats as a
132
- * failure rather than a silent bypass.
131
+ * `none` means the pull request has no checks at all, which `gates.ci` treats
132
+ * as a failure rather than a silent bypass.
133
133
  *
134
- * `conflicting` means the PR has no checks because GitHub reports it as
135
- * conflicting with the Base branch: GitHub runs no `pull_request` workflow for
136
- * such a PR, so it would otherwise read as `none`. It cannot be merged, so no gate
137
- * lets it through, and it has nothing a fix Stage could act on.
134
+ * `conflicting` means the pull request has no checks because GitHub reports it
135
+ * as conflicting with the base branch: GitHub runs no `pull_request` workflow
136
+ * for such a pull request, so it would otherwise read as `none`. It cannot be
137
+ * merged, so no gate lets it through, and it has nothing a fix Stage could act
138
+ * on.
138
139
  */
139
140
  export type CiOutcome =
140
141
  | { state: "passed" }
@@ -172,6 +173,9 @@ export type Authentication = "authenticated" | "unauthenticated" | "not-installe
172
173
  */
173
174
  export type NumberKind = "issue" | "pull-request" | "nothing";
174
175
 
176
+ /** Whether anybody may read a repository, or only those it is shared with. */
177
+ export type Visibility = "public" | "private";
178
+
175
179
  export interface Tracker {
176
180
  /**
177
181
  * Whether `gh` can speak to GitHub as somebody, and if not, whether it is
@@ -203,21 +207,31 @@ export interface Tracker {
203
207
  */
204
208
  repository(): Promise<string | undefined>;
205
209
  /**
206
- * The tag of the highest Version `repository` has published as a GitHub
210
+ * Whether anybody may read the Target, or nothing where GitHub could not be
211
+ * asked. An `internal` repository, readable only inside its enterprise, is
212
+ * private here.
213
+ *
214
+ * Asked once at the start of a Run, and only where the config does not say
215
+ * whether a handed-off Ticket's transcripts are kept on the remote. Nothing
216
+ * is refused over the answer: no answer counts as public.
217
+ */
218
+ visibility(): Promise<Visibility | undefined>;
219
+ /**
220
+ * The tag of the highest version `repository` has published as a GitHub
207
221
  * Release, named `owner/name`, or nothing where GitHub could not be asked.
208
222
  *
209
223
  * Named for the tag rather than for the Release, because a Release in this
210
224
  * codebase is what a Stage the rate limit or an API failure stopped does to
211
225
  * a Ticket (GLOSSARY.md). A published GitHub Release is what makes a tag a
212
- * Version anybody can install, which is why it is the question rather than
226
+ * version anybody can install, which is why it is the question rather than
213
227
  * the tag alone.
214
228
  *
215
229
  * The one method of this port that is not about the Target: it is asked about
216
230
  * the pipeline's own repository, so a Run and `init` can say that a newer
217
- * Version is out. Nothing is ever refused over the answer, so no answer is an
231
+ * version is out. Nothing is ever refused over the answer, so no answer is an
218
232
  * answer — a Target with no network is a Target that works (ADR-0007).
219
233
  *
220
- * Drafts and pre-releases are not published Versions and are not counted. The
234
+ * Drafts and pre-releases are not published versions and are not counted. The
221
235
  * tag comes back as it was cut, `v0.4.0`, because that is what a human would
222
236
  * go and look for.
223
237
  */
@@ -292,7 +306,7 @@ export interface Tracker {
292
306
  /**
293
307
  * Replace an issue's body.
294
308
  *
295
- * Only ever used to tick Acceptance Criteria a Verdict proved, so whatever
309
+ * Only ever used to tick Acceptance Criteria a verdict proved, so whatever
296
310
  * else the body says is read first and written back unchanged.
297
311
  */
298
312
  updateIssueBody(number: number, body: string): Promise<void>;
@@ -317,9 +331,9 @@ export interface Tracker {
317
331
  /**
318
332
  * Replace the body of an open pull request.
319
333
  *
320
- * A Ticket that spends its fix budget is graded twice, and the body carries
321
- * the Verdict a human reads; without this it would keep the Verdict that
322
- * failed while the squash commit carried the one that passed.
334
+ * A Ticket that spends its fix budget comes back to its pull request, and
335
+ * the body is written from the latest body a Stage answered; without this it
336
+ * would keep describing the branch before the fix Stage changed it.
323
337
  */
324
338
  updatePullRequestBody(number: number, body: string): Promise<void>;
325
339
  /**
@@ -11,7 +11,7 @@ import type { Host } from "../host.js";
11
11
  * Run, and a port that kept its own copy would be a second answer to the same
12
12
  * question.
13
13
  *
14
- * It also keeps the pipeline's own bookkeeping about the Target: the State each
14
+ * It also keeps the pipeline's own bookkeeping about the Target: the state each
15
15
  * resumable Ticket keeps, and the Run lock. Where those live is the adapter's
16
16
  * business (ADR-0004), so nothing above the port says whether they are files,
17
17
  * a branch, or a map in a test.
@@ -46,7 +46,7 @@ export type RebaseState = { resolved: true } | { resolved: false; unresolved: st
46
46
  * behind it.
47
47
  *
48
48
  * A state of the lifecycle, not a Stage — a Stage is a session (GLOSSARY.md), and
49
- * what the State records is what the Ticket has, not what was running. Only these
49
+ * what the state records is what the Ticket has, not what was running. Only these
50
50
  * two, because everything after the implement Stage — the Checks, the rebase,
51
51
  * the pull request, CI and the merge — is re-run from the top by a Run that
52
52
  * resumes at `implemented`, and none of them is worth a state a resume could
@@ -56,16 +56,16 @@ export const REACHED_STATES = ["claimed", "implemented"] as const;
56
56
 
57
57
  export type ReachedState = (typeof REACHED_STATES)[number];
58
58
 
59
- /** The State a Ticket keeps while its branch carries work worth resuming. */
59
+ /** The state a Ticket keeps while its branch carries work worth resuming. */
60
60
  export interface TicketState {
61
- /** Carried in the State as well as its name, so it reads on its own. */
61
+ /** Carried in the state as well as its name, so it reads on its own. */
62
62
  ticket: number;
63
63
  /** The branch the work is on, which the resuming Run uses rather than deriving. */
64
64
  branch: string;
65
65
  /** The state the Ticket had reached, which is where a later Run picks it up. */
66
66
  state: ReachedState;
67
67
  /**
68
- * Whether the Fix budget has been spent. Resuming must not hand the Ticket a
68
+ * Whether the fix budget has been spent. Resuming must not hand the Ticket a
69
69
  * second fix Stage it never earned — except after a hand-off, which records it
70
70
  * unspent, the Ticket having been through a human's hands since.
71
71
  */
@@ -79,21 +79,31 @@ export interface TicketState {
79
79
  * The latest title a Stage answered for the whole branch, which names the
80
80
  * pull request and the squash commit. Without it a Run that resumes after the
81
81
  * Stage that wrote it would fall back to the first commit subject. Absent
82
- * when no Stage has answered one, and in State an earlier pipeline left.
82
+ * when no Stage has answered one, and in state an earlier pipeline left.
83
83
  */
84
84
  title?: string;
85
+ /**
86
+ * The latest pull request body, problem and solution a Stage answered for
87
+ * the whole branch, which the pull request body and the squash commit are
88
+ * written from. Without them a Run that resumes after the Stage that wrote
89
+ * them would publish `Closes #<n>` alone. Each is absent when no Stage has
90
+ * answered it, and in state an earlier pipeline left.
91
+ */
92
+ body?: string;
93
+ problem?: string;
94
+ solution?: string;
85
95
  /**
86
96
  * Whether the Run that takes the Ticket up rebases its branch onto the Base
87
- * branch before its Checks. Set by a Release over a failing Base branch, so
97
+ * branch before its Checks. Set by a Release over a failing base branch, so
88
98
  * a fix a human has landed there meanwhile reaches the branch; absent
89
- * otherwise, and in State an earlier pipeline left.
99
+ * otherwise, and in state an earlier pipeline left.
90
100
  */
91
101
  rebaseFirst?: boolean;
92
- /** The Run that last wrote the State, and when — both for a human reading it. */
102
+ /** The Run that last wrote the state, and when — both for a human reading it. */
93
103
  runId: string;
94
104
  /**
95
- * The Version that wrote the State (ADR-0007). Written on every write, and
96
- * optional when read: State an earlier pipeline left names none, and a
105
+ * The version that wrote the state (ADR-0007). Written on every write, and
106
+ * optional when read: state an earlier pipeline left names none, and a
97
107
  * Ticket claimed before this existed still resumes.
98
108
  */
99
109
  version?: string;
@@ -102,10 +112,10 @@ export interface TicketState {
102
112
  }
103
113
 
104
114
  /**
105
- * What one Ticket's recorded State turned out to be.
115
+ * What one Ticket's recorded state turned out to be.
106
116
  *
107
- * Two cases, where no State at all is a third: State a Run can resume from, and
108
- * State it cannot. The second is the one that most needs saying out loud: its
117
+ * Two cases, where no state at all is a third: state a Run can resume from, and
118
+ * state it cannot. The second is the one that most needs saying out loud: its
109
119
  * Ticket is claimed on the board, so the sweep for Stranded Tickets is the only
110
120
  * thing that could ever have found it (ADR-0007).
111
121
  */
@@ -113,9 +123,9 @@ export type StateFile =
113
123
  | { readable: true; state: TicketState }
114
124
  | {
115
125
  readable: false;
116
- /** Read off where the State was kept, which is the only part of it that parsed. */
126
+ /** Read off where the state was kept, which is the only part of it that parsed. */
117
127
  ticket: number;
118
- /** The Version the State names, where it names one a reader can make out. */
128
+ /** The version the state names, where it names one a reader can make out. */
119
129
  version?: string;
120
130
  };
121
131
 
@@ -313,8 +323,8 @@ export interface Workspace {
313
323
  * Subjects of the commits on `branch` that `base` does not have, oldest first.
314
324
  *
315
325
  * The order is the port's promise, not an accident of git's default: the
316
- * first subject names the whole Ticket, and the squash commit lists the rest
317
- * in the order they were written.
326
+ * first subject names the whole Ticket, and a squash commit with no solution
327
+ * answered lists them in the order they were written.
318
328
  */
319
329
  commitSubjects(branch: string, base: string): Promise<string[]>;
320
330
  /**
@@ -389,11 +399,21 @@ export interface Workspace {
389
399
  */
390
400
  readRemoteFile(branch: string, path: string): Promise<string | undefined>;
391
401
  /**
392
- * Delete `branch` on the remote; the PR is merged, so nothing references it.
402
+ * Delete `branch` on the remote; the pull request is merged, so nothing
403
+ * references it.
393
404
  * A branch the remote already deleted, as GitHub does on merge when told to,
394
405
  * counts as deleted without a delete being sent, which a cloud Host could not.
395
406
  */
396
407
  deleteRemoteBranch(branch: string): Promise<void>;
408
+ /**
409
+ * Fetch the whole history of a clone that is shallow, and say whether it was.
410
+ *
411
+ * Asked once before a Run claims anything. A shallow clone cannot show that
412
+ * the remote's base branch is a fast-forward of a local one left on an
413
+ * older commit, so every {@link pullBase} on it is refused, and every Ticket
414
+ * handed off at the rebase.
415
+ */
416
+ unshallow(): Promise<boolean>;
397
417
  /**
398
418
  * Fast-forward the main checkout's `base` to the remote: at the door of the
399
419
  * Landing, so the rebase is onto what the merge will land on, and after a
@@ -402,15 +422,15 @@ export interface Workspace {
402
422
  pullBase(base: string): Promise<void>;
403
423
 
404
424
  /**
405
- * The State `ticket` keeps, when a Run can resume from it.
425
+ * The state `ticket` keeps, when a Run can resume from it.
406
426
  *
407
- * State nothing wrote, and State this pipeline cannot read, are both
427
+ * State nothing wrote, and state this pipeline cannot read, are both
408
428
  * undefined: starting the Ticket over is always safe, and resuming on a guess
409
429
  * is not.
410
430
  */
411
431
  readState(ticket: number): Promise<TicketState | undefined>;
412
432
  /**
413
- * Every Ticket's State, in ascending Ticket number, the unreadable ones
433
+ * Every Ticket's state, in ascending Ticket number, the unreadable ones
414
434
  * included: their Tickets are claimed, and the sweep is what tells a human
415
435
  * they are there.
416
436
  */
@@ -419,12 +439,12 @@ export interface Workspace {
419
439
  writeState(state: TicketState): Promise<void>;
420
440
  /**
421
441
  * Forget `ticket` is resumable, and the transcripts {@link keepTranscripts}
422
- * kept beside its State with it. A Ticket with no State is not an error.
442
+ * kept beside its state with it. A Ticket with no state is not an error.
423
443
  */
424
444
  removeState(ticket: number): Promise<void>;
425
445
  /**
426
446
  * Keep the command lines and transcripts of the Stages Run `runId` ran for
427
- * `ticket` beside its State, where a human can still read them once this
447
+ * `ticket` beside its state, where a human can still read them once this
428
448
  * Host is gone. Asked of a hand-off, and nothing else: a Ticket nobody has to
429
449
  * look into leaves nothing behind.
430
450
  *
@@ -432,6 +452,14 @@ export interface Workspace {
432
452
  * the Run left none for the Ticket.
433
453
  */
434
454
  keepTranscripts(ticket: number, runId: string): Promise<KeptTranscripts | undefined>;
455
+ /**
456
+ * Where on this Host Run `runId` wrote the files {@link keepTranscripts}
457
+ * would keep for `ticket`, as a `/`-separated directory relative to the
458
+ * checkout and ending in `/`, or nothing when it wrote none. Asked of a
459
+ * hand-off whose Run keeps transcripts off the remote: relative, so a public
460
+ * comment naming it does not publish the Host's home path.
461
+ */
462
+ transcriptsOnHost(ticket: number, runId: string): Promise<string | undefined>;
435
463
  /**
436
464
  * Take the Run lock for this Run, or say what stands in the way. Taking it is
437
465
  * the whole of the mutual exclusion: two Runs never both get `taken`, on one
package/src/progress.ts CHANGED
@@ -26,14 +26,19 @@ export const PROGRESS_MARKER = "<!-- ticket-runner:progress -->";
26
26
  /**
27
27
  * What a row is about. Named after the lifecycle step rather than the Stage, for
28
28
  * the reason `FailurePoint` in `lifecycle.ts` is: the Checks, CI and the merge
29
- * each earn a row, and none of them is an agent session.
29
+ * each earn a row, and none of them is an agent session. `setup`, `rebase` and
30
+ * `pr` earn one only where GitHub or the remote failing on its own side
31
+ * released the Ticket there.
30
32
  */
31
33
  export type ProgressPoint =
34
+ | "setup"
32
35
  | "implement"
33
36
  | "checks"
34
37
  | "verify"
35
38
  | "fix"
36
39
  | "conflict"
40
+ | "rebase"
41
+ | "pr"
37
42
  | "ci"
38
43
  | "merge";
39
44
 
@@ -51,7 +56,7 @@ export interface ProgressRow {
51
56
  const NO_ANSWER = "–";
52
57
 
53
58
  export interface ProgressCommentBody {
54
- /** The Version reporting, as every line one Run stamps carries it. */
59
+ /** The version reporting, as every line one Run stamps carries it. */
55
60
  version: string;
56
61
  runId: string;
57
62
  branch: string;
@@ -88,7 +93,7 @@ export function progressComment({
88
93
  "|---|---|---|---|",
89
94
  ...rows.map(
90
95
  (row) =>
91
- `| ${row.point} | ${cell(row.outcome)} | ${count(row.turns)} | ${minutes(row.durationMs)} |`,
96
+ `| ${row.point} | ${cell(row.outcome)} | ${count(row.turns)} | ${duration(row.durationMs)} |`,
92
97
  ),
93
98
  "",
94
99
  ].join("\n");
@@ -99,7 +104,7 @@ export function progressComment({
99
104
  *
100
105
  * Every section under the marker, minus the last when it is this Run's own: a
101
106
  * Run that reads the Ticket again rewrites its section rather than starting a
102
- * second. A comment an earlier Version wrote, with one header and one table, is
107
+ * second. A comment an earlier version wrote, with one header and one table, is
103
108
  * one section like any other.
104
109
  */
105
110
  function earlierSections(body: string, runId: string): string {
@@ -136,9 +141,20 @@ function count(turns: number | undefined): string {
136
141
  return turns === undefined ? NO_ANSWER : String(turns);
137
142
  }
138
143
 
139
- /** Minutes, as the rest of the pipeline reports durations to humans. */
140
- function minutes(durationMs: number | undefined): string {
141
- return durationMs === undefined ? NO_ANSWER : `${Math.round(durationMs / 60_000)}m`;
144
+ /**
145
+ * A duration as GitHub Actions writes one on a pull request's checks: `40s`,
146
+ * `1m 5s`, `3h 15m 35s`. The template says why. A clock stepped back mid-Stage
147
+ * reads `0s` rather than a negative.
148
+ */
149
+ function duration(durationMs: number | undefined): string {
150
+ if (durationMs === undefined) return NO_ANSWER;
151
+ const total = Math.max(0, Math.round(durationMs / 1000));
152
+ const hours = Math.floor(total / 3600);
153
+ const minutes = Math.floor((total % 3600) / 60);
154
+ const seconds = total % 60;
155
+ if (hours > 0) return `${hours}h ${minutes}m ${seconds}s`;
156
+ if (minutes > 0) return `${minutes}m ${seconds}s`;
157
+ return `${seconds}s`;
142
158
  }
143
159
 
144
160
  /**
@@ -181,6 +197,8 @@ export class Progress {
181
197
  private readonly earlier: string;
182
198
  /** Set when reporting again could only mean a second comment, never an edit. */
183
199
  private stopped = false;
200
+ /** Set while the comment on the Ticket lacks a row the last write failed to carry. */
201
+ private behind = false;
184
202
 
185
203
  constructor(private readonly options: ProgressOptions) {
186
204
  // A Ticket taken back from a human keeps the comment that human read: a
@@ -198,6 +216,20 @@ export class Progress {
198
216
  /** Append a row, and show it on the Ticket. */
199
217
  async record(row: ProgressRow): Promise<void> {
200
218
  this.rows.push(row);
219
+ await this.write();
220
+ }
221
+
222
+ /**
223
+ * Write the comment once more if its last write failed, so a row GitHub
224
+ * refused mid-Ticket is on the Ticket by the time it ends. Called once the
225
+ * Ticket merges, is handed off or is released: no later write of the Run
226
+ * would carry it otherwise.
227
+ */
228
+ async settle(): Promise<void> {
229
+ if (this.behind) await this.write();
230
+ }
231
+
232
+ private async write(): Promise<void> {
201
233
  if (this.stopped) return;
202
234
 
203
235
  const { tracker, ticket, version, runId, branch } = this.options;
@@ -213,9 +245,11 @@ export class Progress {
213
245
  const id = this.comment?.id;
214
246
  if (id !== undefined) {
215
247
  await tracker.updateComment(id, body);
248
+ this.behind = false;
216
249
  return;
217
250
  }
218
251
  this.comment = await tracker.comment(ticket, body);
252
+ this.behind = false;
219
253
  if (this.comment.id === undefined) {
220
254
  // A comment nothing can edit is a comment per Stage, which is the noise
221
255
  // this whole table exists to avoid. One row is better than a dozen.
@@ -223,6 +257,7 @@ export class Progress {
223
257
  this.options.log?.(`#${ticket} posted a progress comment it cannot edit again`);
224
258
  }
225
259
  } catch (error) {
260
+ this.behind = true;
226
261
  this.options.log?.(
227
262
  `#${ticket} could not write the progress comment: ${(error as Error).message}`,
228
263
  );