ticket-runner 0.6.3 → 0.6.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.ko.md +4 -4
  2. package/README.md +3 -3
  3. package/docs/templates/operator-skill.md +7 -7
  4. package/package.json +1 -1
  5. package/src/acceptance-criteria.ts +2 -2
  6. package/src/adapters/claude-agent-runner.ts +49 -5
  7. package/src/adapters/exec.ts +19 -4
  8. package/src/adapters/gh-tracker.ts +17 -17
  9. package/src/adapters/git-workspace.ts +12 -8
  10. package/src/adapters/liveness.ts +77 -0
  11. package/src/adapters/process-tree.ts +4 -7
  12. package/src/adapters/version.ts +5 -5
  13. package/src/branch.ts +1 -1
  14. package/src/cli.ts +2 -2
  15. package/src/config.ts +7 -6
  16. package/src/conventions.ts +23 -20
  17. package/src/credential.ts +92 -7
  18. package/src/criteria.ts +107 -15
  19. package/src/failing-base.ts +7 -7
  20. package/src/failure-message.ts +72 -0
  21. package/src/guards.ts +2 -2
  22. package/src/handoff.ts +2 -2
  23. package/src/init.ts +8 -8
  24. package/src/landing.ts +1 -1
  25. package/src/lifecycle.ts +2 -2
  26. package/src/lock.ts +10 -2
  27. package/src/note-schema.ts +3 -3
  28. package/src/notes.ts +8 -6
  29. package/src/operator-skill.ts +2 -2
  30. package/src/orchestrator.ts +194 -144
  31. package/src/ports/agent-runner.ts +21 -1
  32. package/src/ports/tracker.ts +14 -13
  33. package/src/ports/workspace.ts +23 -22
  34. package/src/progress.ts +2 -2
  35. package/src/prompts.ts +74 -25
  36. package/src/readiness.ts +11 -11
  37. package/src/remove.ts +7 -7
  38. package/src/resume.ts +12 -12
  39. package/src/run-log.ts +5 -5
  40. package/src/run.ts +72 -10
  41. package/src/staleness.ts +14 -14
  42. package/src/start.ts +20 -15
  43. package/src/stranded.ts +19 -19
  44. package/src/templates.ts +191 -73
  45. package/src/timer.ts +25 -0
  46. package/src/title.ts +45 -9
  47. package/src/verdict.ts +7 -7
  48. package/src/version-number.ts +13 -13
  49. package/src/version-pr.ts +12 -12
package/src/resume.ts CHANGED
@@ -4,15 +4,15 @@ import { z } from "zod";
4
4
  import { REACHED_STATES, type StateFile, type TicketState } from "./ports/workspace.js";
5
5
 
6
6
  /**
7
- * The State file a Ticket keeps while its branch carries work worth resuming,
7
+ * The state file a Ticket keeps while its branch carries work worth resuming,
8
8
  * and what a later Run makes of it (ADR-0004).
9
9
  *
10
10
  * A Ticket keeps the file for as long as there is work on its branch worth
11
- * resuming, so it is written as part of the Claim and rewritten whenever the
11
+ * resuming, so it is written as part of the claim and rewritten whenever the
12
12
  * Ticket reaches something a later Run should not pay for again. Three Runs read
13
13
  * it, and what the board says decides which. One finds a Ticket the subscription
14
14
  * rate limit or a transient API failure released: nothing was wrong with it, so
15
- * the Claim came off and this file says where to carry on from. One finds a
15
+ * the claim came off and this file says where to carry on from. One finds a
16
16
  * Ticket still claimed — the Run that claimed it was killed and never released
17
17
  * anything — and resumes it in place. One finds a Ticket a human was handed and has relabelled
18
18
  * `ready-for-agent`, which is the human handing it back. A Ticket still sitting
@@ -25,7 +25,7 @@ import { REACHED_STATES, type StateFile, type TicketState } from "./ports/worksp
25
25
  * This is only what the file says and what its name is, which that Workspace
26
26
  * reads and writes through here. Whether the branch a file names is still there
27
27
  * is the Workspace's other question, and whether the Ticket is released or
28
- * stranded is the Claim's, read off GitHub.
28
+ * stranded is the claim's, read off GitHub.
29
29
  */
30
30
 
31
31
  const stateSchema = z.object({
@@ -66,7 +66,7 @@ export function stateFileContents(state: TicketState): string {
66
66
  * A file that is not JSON, one missing what resuming needs, and one a newer
67
67
  * pipeline shaped differently are all unreadable: starting the Ticket over is
68
68
  * always safe, and resuming on a guess is not. So is one that names another
69
- * Ticket than its own name does, which no Version would resume either.
69
+ * Ticket than its own name does, which no version would resume either.
70
70
  */
71
71
  export function readStateFile(contents: string, ticket: number): StateFile {
72
72
  const raw = parseJson(contents);
@@ -76,7 +76,7 @@ export function readStateFile(contents: string, ticket: number): StateFile {
76
76
  return { readable: false, ticket, ...(version === undefined ? {} : { version }) };
77
77
  }
78
78
 
79
- // A pull request nobody opened, a title no Stage answered, and a Version an
79
+ // A pull request nobody opened, a title no Stage answered, and a version an
80
80
  // older pipeline never wrote, are keys that are not there rather than keys
81
81
  // holding nothing: the rest of the pipeline reads these with the same
82
82
  // distinction.
@@ -94,11 +94,11 @@ export function readStateFile(contents: string, ticket: number): StateFile {
94
94
  }
95
95
 
96
96
  /**
97
- * The Version a file that will not parse still names, where it names one.
97
+ * The version a file that will not parse still names, where it names one.
98
98
  *
99
99
  * Read off the raw JSON rather than the schema, because the schema is exactly
100
- * what refused the file: a State file a newer pipeline wrote is named by the
101
- * Version that wrote it, whatever else about it this one cannot read.
100
+ * what refused the file: a state file a newer pipeline wrote is named by the
101
+ * version that wrote it, whatever else about it this one cannot read.
102
102
  */
103
103
  function namedVersion(raw: unknown): string | undefined {
104
104
  if (raw === null || typeof raw !== "object" || !("version" in raw)) return undefined;
@@ -116,7 +116,7 @@ function parseJson(contents: string): unknown {
116
116
  }
117
117
 
118
118
  /**
119
- * The branch of the Target's remote that holds every Ticket's State, one file
119
+ * The branch of the Target's remote that holds every Ticket's state, one file
120
120
  * per Ticket, and the transcripts of a handed-off Ticket's Stages beside it,
121
121
  * under the prefix the pipeline owns (ADR-0004). Named here rather than only in
122
122
  * the Workspace that writes it, because `ticket-runner remove` deletes it by
@@ -124,11 +124,11 @@ function parseJson(contents: string): unknown {
124
124
  */
125
125
  export const STATE_BRANCH = "ticket-runner/state";
126
126
 
127
- /** Where a pipeline before the state branch kept the State files, in the checkout. */
127
+ /** Where a pipeline before the state branch kept the state files, in the checkout. */
128
128
  export const LOCAL_STATE_DIR = join(".ticket-runner", "state");
129
129
 
130
130
  /**
131
- * The Tickets whose State files a pipeline before the state branch left in this
131
+ * The Tickets whose state files a pipeline before the state branch left in this
132
132
  * checkout, in ascending number.
133
133
  *
134
134
  * Nothing reads them any more, and nothing migrates them (ADR-0004): a Run that
package/src/run-log.ts CHANGED
@@ -18,21 +18,21 @@ export function stageLogDir(repoRoot: string, runId: string, ticket: number): st
18
18
  * Where the fix Stage and the pass it bought write instead.
19
19
  *
20
20
  * A Stage's files are named after the Stage and emptied when it starts, so a
21
- * second verify would overwrite the Verdict that spent the fix budget — which
21
+ * second verify would overwrite the verdict that spent the fix budget — which
22
22
  * is the transcript a human most needs when the Ticket is handed off anyway.
23
23
  */
24
24
  export function retryLogDir(repoRoot: string, runId: string, ticket: number): string {
25
25
  return join(stageLogDir(repoRoot, runId, ticket), "retry");
26
26
  }
27
27
 
28
- /** The file naming the Version, at the top of a Run's transcripts. */
28
+ /** The file naming the version, at the top of a Run's transcripts. */
29
29
  export const VERSION_FILE = "version.txt";
30
30
 
31
31
  /**
32
- * Say which Version this Run is, beside the transcripts it is about to write.
32
+ * Say which version this Run is, beside the transcripts it is about to write.
33
33
  *
34
34
  * Written before the first Stage, so a transcript always sits beside the
35
- * pipeline that wrote it: the Run summary names the Version too, but that is a
35
+ * pipeline that wrote it: the Run summary names the version too, but that is a
36
36
  * terminal the night is over for, and these files outlive it (ADR-0007).
37
37
  */
38
38
  export function writeRunVersion(repoRoot: string, runId: string, version: string): void {
@@ -58,7 +58,7 @@ export interface TranscriptFile {
58
58
  /**
59
59
  * The files Run `runId` wrote for `ticket` that a hand-off keeps, in name
60
60
  * order: every Stage's command line and transcript, the retries' in `retry/`,
61
- * and the Version the Run was, so they still name the pipeline that wrote them
61
+ * and the version the Run was, so they still name the pipeline that wrote them
62
62
  * once they are somewhere else. None when the Run wrote nothing for the Ticket.
63
63
  */
64
64
  export function transcriptFiles(
package/src/run.ts CHANGED
@@ -6,6 +6,14 @@ import { type Pipeline, type TicketOutcome, processTicket } from "./orchestrator
6
6
  import { StopSignal, stopLine } from "./stop.js";
7
7
  import { holdsClaim, strandedTickets } from "./stranded.js";
8
8
  import { releaseWords } from "./templates.js";
9
+ import { startTimer } from "./timer.js";
10
+
11
+ /**
12
+ * How long a free Lane waits, after the Run last listed the Frontier, before it
13
+ * looks at the Frontier again while another Lane is busy. Fixed: nothing in the
14
+ * Target's config or on the command line sets it, and nothing turns it off.
15
+ */
16
+ export const POLL_MS = 5 * 60_000;
9
17
 
10
18
  /**
11
19
  * What a Run has to show for itself: every Ticket it took, in the order they
@@ -26,7 +34,7 @@ export interface RunResult {
26
34
  * A Run that drained the Frontier carries what was left held back; one a
27
35
  * Release stopped carries no candidates, because it ended before it could say
28
36
  * one was held back all Run, and the rate limit carries when it resets, where a
29
- * Stage was told, and a failing Base branch the Check it fails and where; one
37
+ * Stage was told, and a failing base branch the Check it fails and where; one
30
38
  * a human stopped carries the moment it was asked and what it still had in
31
39
  * hand. That is why this is a choice rather than a flag beside
32
40
  * the list: the stops do not report the same things.
@@ -73,13 +81,22 @@ export type RunStop =
73
81
  * working is still an open blocker. Those edges are the whole of what keeps two
74
82
  * Tickets apart: no heuristic here decides which are safe together.
75
83
  *
84
+ * A Ticket can also join the Frontier with no Lane ending — a human labels it
85
+ * `ready-for-agent`, or closes its last blocker outside the Run — so while one
86
+ * Lane is free and another busy, the Run looks at the Frontier again
87
+ * {@link POLL_MS} after it last listed it, whatever listed it, and takes what
88
+ * a refill would. A Run with nothing busy has nothing to wait for and ends, as
89
+ * before: it never waits for new Tickets. A look that cannot list is logged
90
+ * and tried again next time, since nothing about the Run depended on it; a
91
+ * refill that cannot list still ends the Run's claiming.
92
+ *
76
93
  * A Ticket that fails is handed off and the Lane moves on: one bad Ticket must
77
94
  * not cost the rest of the night.
78
95
  *
79
96
  * A Release stops the Run filling Lanes and nothing more. Nothing was wrong with
80
97
  * the Ticket — the subscription or the API key ran out of room, or the API
81
98
  * failed on its own side after the CLI had given up retrying it — so the next
82
- * one would be stopped the same way, and claiming it would spend a Claim, a
99
+ * one would be stopped the same way, and claiming it would spend a claim, a
83
100
  * worktree and a doomed Stage to learn what the first one already said. The Lanes still busy finish
84
101
  * what they hold, and the Run reports what stopped it once the last of them
85
102
  * comes back. It does not wait for the limit to reset: a human or an Operator
@@ -92,7 +109,7 @@ export type RunStop =
92
109
  * own behind where a killed one leaves all of them (ADR-0006).
93
110
  *
94
111
  * Before any of that, the Tickets a Run that never came back left claimed are
95
- * resumed. They are not on the Frontier and never will be — the Claim they still
112
+ * resumed. They are not on the Frontier and never will be — the claim they still
96
113
  * wear is what keeps them off it — so this sweep is the only thing that ever
97
114
  * picks them up again, and a free Lane takes one before it takes anything the
98
115
  * Frontier is offering.
@@ -115,14 +132,14 @@ export async function processRun(
115
132
  // Every Ticket this Run has taken. A Ticket normally leaves the candidate
116
133
  // list by being closed or relabelled; this is what stops a Run offering one
117
134
  // to a second Lane, whether because that write did not land or because the
118
- // Claim of the Lane holding it has not reached GitHub yet.
135
+ // claim of the Lane holding it has not reached GitHub yet.
119
136
  const taken = new Set<number>();
120
137
  // The Lanes with a Ticket in them, by Ticket number. A Lane takes itself out
121
138
  // of here as its Ticket ends rather than where the Run waits, so a fill pass
122
139
  // that several Lanes came back during sees every one of them free.
123
140
  const busy = new Map<number, Promise<void>>();
124
141
  // What the last Frontier this Run computed held back, which is what a Run
125
- // that drained the Frontier reports. Replaced at every refill: a candidate a
142
+ // that drained the Frontier reports. Replaced at every listing: a candidate a
126
143
  // Lane unblocked on the way is not one the Run was still held up by.
127
144
  let blocked: number[] = [];
128
145
  // Why this Run stopped, which is also what it reports. Set by whichever of
@@ -137,6 +154,12 @@ export async function processRun(
137
154
  // went down, so the error waits for them and is thrown where a Run with one
138
155
  // Lane threw it: out of the Run, with nothing else left running.
139
156
  let listing: unknown;
157
+ // How many Lanes have ended, and how many had when the last pass listed the
158
+ // Frontier, which tells a refill a Lane's ending brought from a look the
159
+ // clock brought: a listing that fails is the Run's to throw only in the
160
+ // first. -1 until the first pass, which is a refill too.
161
+ let ended = 0;
162
+ let endedAtLastPass = -1;
140
163
 
141
164
  // Registered before the sweep, because a Stop that arrives during it is a Run
142
165
  // that claims nothing at all: the Lanes are empty, so there is nothing to
@@ -181,6 +204,7 @@ export async function processRun(
181
204
  ticket.number,
182
205
  take(pipeline, ticket).then((outcome) => {
183
206
  busy.delete(ticket.number);
207
+ ended += 1;
184
208
  outcomes.push(outcome);
185
209
  if (outcome.outcome !== "released") return;
186
210
  if (runStop === undefined) {
@@ -228,18 +252,50 @@ export async function processRun(
228
252
  }
229
253
  }
230
254
 
255
+ /**
256
+ * Whether a free Lane should look at the Frontier again before a busy one
257
+ * ends. Only after a pass that listed it, which every pass that leaves a Lane
258
+ * free while the Run is still taking Tickets did: so the wait counts from
259
+ * that listing.
260
+ */
261
+ function polling(): boolean {
262
+ return runStop === undefined && listing === undefined && busy.size > 0 && laneFree();
263
+ }
264
+
265
+ /** Wait for a Lane to end, or for the time to look at the Frontier again. */
266
+ async function nextPass(): Promise<void> {
267
+ const ending = Promise.race(busy.values());
268
+ if (!polling()) return await ending;
269
+ const poll = (pipeline.startTimer ?? startTimer)(POLL_MS);
270
+ try {
271
+ await Promise.race([ending, poll.elapsed]);
272
+ } finally {
273
+ poll.cancel();
274
+ }
275
+ }
276
+
231
277
  for (;;) {
232
278
  if (runStop === undefined && listing === undefined) {
279
+ const endedBefore = ended;
280
+ const looking = endedBefore === endedAtLastPass;
233
281
  try {
234
282
  await fillLanes();
283
+ endedAtLastPass = ended;
235
284
  } catch (error) {
236
- listing = error;
285
+ if (!looking) {
286
+ listing = error;
287
+ } else {
288
+ pipeline.log?.(pollFailure(error));
289
+ // A Lane that ended while the look was listing is still owed its
290
+ // refill, which runs now, and only that one's failure is the Run's.
291
+ if (ended !== endedBefore) continue;
292
+ }
237
293
  }
238
294
  }
239
295
  // Never while a Lane is busy, whatever the Frontier had to offer: that Lane
240
296
  // may be about to close the blocker the rest of the Frontier is waiting on.
241
297
  if (busy.size === 0) break;
242
- await Promise.race(busy.values());
298
+ await nextPass();
243
299
  }
244
300
 
245
301
  if (listing !== undefined) throw listing;
@@ -255,9 +311,15 @@ export async function processRun(
255
311
  return { outcomes, stop };
256
312
  }
257
313
 
314
+ /** The one line a look at the Frontier that could not list it earns. */
315
+ function pollFailure(error: unknown): string {
316
+ const minutes = POLL_MS / 60_000;
317
+ return `listing the Frontier failed, trying again in ${minutes} minutes · ${(error as Error).message}`;
318
+ }
319
+
258
320
  /**
259
321
  * The stop a Release puts on the Run: what released it, when a limit resets,
260
- * and which Check the Base branch fails.
322
+ * and which Check the base branch fails.
261
323
  */
262
324
  function releaseStop(
263
325
  outcome: Extract<TicketOutcome, { outcome: "released" }>,
@@ -281,7 +343,7 @@ function releaseStop(
281
343
  * it alone needs the human to act: no wait mends it, only the Console. The
282
344
  * rate limit outranks an API failure, which says nothing of when the next Run
283
345
  * can start, and a limit nobody was told the end of is outranked by one a
284
- * Stage was told. A failing Base branch and a Stop stay whatever comes after
346
+ * Stage was told. A failing base branch and a Stop stay whatever comes after
285
347
  * them, and so does an API budget, and a limit already told when it resets.
286
348
  */
287
349
  function outranks(
@@ -392,7 +454,7 @@ async function take(pipeline: Pipeline, ticket: Taken): Promise<TicketOutcome> {
392
454
  *
393
455
  * The branch is carried rather than derived, because the two ways a Run reaches
394
456
  * a Ticket know it differently: a candidate off the Frontier has whatever its
395
- * title derives to, and a stranded Ticket has the branch its State file names —
457
+ * title derives to, and a stranded Ticket has the branch its state file names —
396
458
  * which is where the work actually is, whatever the title says now.
397
459
  */
398
460
  interface Taken {
package/src/staleness.ts CHANGED
@@ -1,18 +1,18 @@
1
1
  /**
2
- * What a Run and `init` say when something around them is from another Version,
2
+ * What a Run and `init` say when something around them is from another version,
3
3
  * and the one thing neither ever does about it.
4
4
  *
5
5
  * Two questions, both answered in one line and neither ever a refusal
6
- * (ADR-0007): is a newer Version published than the one running, and is the
7
- * Target's conventions document from another Version than the one reading it.
8
- * Nothing here is a gate. A pipeline that refused to work while a newer Version
6
+ * (ADR-0007): is a newer version published than the one running, and is the
7
+ * Target's conventions document from another version than the one reading it.
8
+ * Nothing here is a gate. A pipeline that refused to work while a newer version
9
9
  * existed would strand a Target on the night its maintainer was asleep, and
10
10
  * Target readiness already says what a Target is refused over: the document's
11
- * absence or a missing Version stamp, never what it says or which Version.
11
+ * absence or a missing version stamp, never what it says or which version.
12
12
  *
13
13
  * A number against a number, always. A development checkout runs a commit past
14
- * the Version it reports, so comparing anything finer would call every checkout
15
- * stale the moment its Version was cut.
14
+ * the version it reports, so comparing anything finer would call every checkout
15
+ * stale the moment its version was cut.
16
16
  */
17
17
 
18
18
  import { join } from "node:path";
@@ -22,14 +22,14 @@ import { readTargetFile } from "./readiness.js";
22
22
  import { isHigher, tagNumber, versionNumber } from "./version-number.js";
23
23
 
24
24
  /**
25
- * How any copy is upgraded, whatever repository it asks about: every Version
25
+ * How any copy is upgraded, whatever repository it asks about: every version
26
26
  * is on npm before it has a GitHub Release (ADR-0007).
27
27
  */
28
28
  export const UPGRADE_COMMAND = "npm install -g ticket-runner";
29
29
 
30
30
  export interface StalenessQuestion {
31
31
  tracker: Tracker;
32
- /** The Version this copy is, as the CLI resolved it once and handed it down. */
32
+ /** The version this copy is, as the CLI resolved it once and handed it down. */
33
33
  version: string;
34
34
  /**
35
35
  * The pipeline's own repository, as `owner/name`. Undefined where the package
@@ -40,13 +40,13 @@ export interface StalenessQuestion {
40
40
  }
41
41
 
42
42
  /**
43
- * One line naming the Version that is out and the Version running, and nothing
43
+ * One line naming the version that is out and the version running, and nothing
44
44
  * at all where this copy is the latest, is ahead of it, or could not ask.
45
45
  *
46
46
  * What has been published as a GitHub Release is the question rather than the
47
47
  * highest tag, because a tag a workflow has not finished publishing is not a
48
- * Version anybody can install yet. The tag workflow makes the GitHub Release
49
- * only once npm has the Version, so the answer names one the upgrade finds.
48
+ * version anybody can install yet. The tag workflow makes the GitHub Release
49
+ * only once npm has the version, so the answer names one the upgrade finds.
50
50
  */
51
51
  export async function newerVersionLine({
52
52
  tracker,
@@ -60,7 +60,7 @@ export async function newerVersionLine({
60
60
  const published = latest === undefined ? undefined : tagNumber(latest);
61
61
  if (published === undefined || !isHigher(published, own)) return undefined;
62
62
 
63
- return `A newer Version is out: ${published}, and this is ${own} — upgrade with \`${UPGRADE_COMMAND}\`.`;
63
+ return `A newer version is out: ${published}, and this is ${own} — upgrade with \`${UPGRADE_COMMAND}\`.`;
64
64
  }
65
65
 
66
66
  /**
@@ -84,7 +84,7 @@ async function publishedVersionTag(
84
84
 
85
85
  /**
86
86
  * The one warning a Run prints about the conventions document in `repoRoot`,
87
- * and nothing where the document is this Version's own.
87
+ * and nothing where the document is this version's own.
88
88
  *
89
89
  * Worded for whichever side is behind, because only one of them can be put
90
90
  * right from here: a document an older pipeline left is `init`'s to rewrite,
package/src/start.ts CHANGED
@@ -1,8 +1,9 @@
1
1
  import { resolveBaseBranch } from "./base-branch.js";
2
2
  import type { Config } from "./config.js";
3
- import { type Credential, credentialRefusal } from "./credential.js";
3
+ import { type Credential, credentialRefusal, emptyBilling } from "./credential.js";
4
4
  import { type HostKind, hostKind } from "./host.js";
5
5
  import { BaseBranchChecks } from "./failing-base.js";
6
+ import { printEachOutputOnce } from "./failure-message.js";
6
7
  import { Landing } from "./landing.js";
7
8
  import { StandingNotes } from "./notes.js";
8
9
  import { lockHeldMessage, unreleasedLockMessage } from "./lock.js";
@@ -57,12 +58,12 @@ export interface StartOptions {
57
58
  workspace: Workspace;
58
59
  runId: string;
59
60
  /**
60
- * The Version this Run is, resolved once in the CLI (ADR-0007). Everything
61
+ * The version this Run is, resolved once in the CLI (ADR-0007). Everything
61
62
  * the Run stamps takes it from here, so every stamp says the same thing.
62
63
  */
63
64
  version: string;
64
65
  /**
65
- * The pipeline's own repository, as `owner/name`, which the newer-Version
66
+ * The pipeline's own repository, as `owner/name`, which the newer-version
66
67
  * notice is looked up against; see {@link import("./staleness.js")}.
67
68
  */
68
69
  repository?: string | undefined;
@@ -85,7 +86,7 @@ export interface StartOptions {
85
86
  *
86
87
  * Every refusal comes before the lock: an `--api-key` the Host cannot honour,
87
88
  * a Target `init` has not set up, one whose remote lacks what `init` wrote,
88
- * one holding State files an earlier pipeline left in the checkout, and one
89
+ * one holding state files an earlier pipeline left in the checkout, and one
89
90
  * with nothing to gate a merge. None is a Run that went wrong, so none should
90
91
  * leave a lock behind for the next one to reclaim.
91
92
  */
@@ -101,7 +102,7 @@ export async function startRun(given: StartOptions): Promise<number> {
101
102
  const env = options.env ?? process.env;
102
103
 
103
104
  // First, because it asks nothing of the Target: the Host either can or
104
- // cannot run the Stages on the credential the Run was started with.
105
+ // cannot bill the Stages to what the Run was started with.
105
106
  const credential: Credential = options.work.apiKey === true ? "api-key" : "subscription";
106
107
  const host = hostKind(env);
107
108
  const refusedCredential = credentialRefusal(credential, host, env);
@@ -135,9 +136,9 @@ export async function startRun(given: StartOptions): Promise<number> {
135
136
  }
136
137
 
137
138
  const { refusal, warnings } = startupMessages(config);
138
- // Which Version the document names is a warning and never a refusal, so it
139
+ // Which version the document names is a warning and never a refusal, so it
139
140
  // joins the config's own: readiness has already refused a copy naming none,
140
- // and one naming another Version is nothing a Run is worse for (ADR-0007).
141
+ // and one naming another version is nothing a Run is worse for (ADR-0007).
141
142
  const stale = conventionsWarning(repoRoot, options.version);
142
143
  for (const warning of [...warnings, ...(stale === undefined ? [] : [stale])]) {
143
144
  error(`warning: ${warning}`);
@@ -198,10 +199,14 @@ async function execute(
198
199
  host,
199
200
  baseBranch,
200
201
  }: { credential: Credential; host: HostKind; baseBranch: string },
201
- log: (line: string) => void,
202
+ print: (line: string) => void,
202
203
  stopping: StopSignal,
203
204
  ): Promise<number> {
204
205
  const { work, repoRoot, config, tracker, runner, workspace, runId, version } = options;
206
+ // Every event of the Run goes through this, and one cause tends to fail
207
+ // several of them with the same output, so each output is printed once. The
208
+ // summary is printed as it is: it is one block, written once.
209
+ const log = printEachOutputOnce(print);
205
210
 
206
211
  // Before the first Stage, and before the tracker is asked anything: a
207
212
  // transcript has to sit beside the pipeline that wrote it, and the Run
@@ -211,7 +216,7 @@ async function execute(
211
216
  try {
212
217
  writeRunVersion(repoRoot, runId, version);
213
218
  } catch (error) {
214
- log(`could not record the Version beside the transcripts: ${(error as Error).message}`);
219
+ log(`could not record the version beside the transcripts: ${(error as Error).message}`);
215
220
  }
216
221
 
217
222
  // Asked once, and said twice: at the top of the log a human watches, and
@@ -236,7 +241,7 @@ async function execute(
236
241
  version,
237
242
  host,
238
243
  credential,
239
- strayStages: [],
244
+ billing: emptyBilling(),
240
245
  baseBranch,
241
246
  // Once per Run as well, and for the same reason: the Tickets of one Run
242
247
  // take turns between their rebase and their merge, and a Landing made per
@@ -262,18 +267,18 @@ async function execute(
262
267
  durationMs: Date.now() - startedAt,
263
268
  credential,
264
269
  outcomes,
265
- strayStages: pipeline.strayStages,
270
+ billing: pipeline.billing,
266
271
  ...(newer === undefined ? {} : { newer }),
267
272
  stop,
268
273
  });
269
274
 
270
275
  const { outcomes, stop } = await processRun(pipeline, stopping, work.tickets);
271
- log(`\n${summary(outcomes, stop)}`);
276
+ print(`\n${summary(outcomes, stop)}`);
272
277
  return exitCode(outcomes, work.tickets !== undefined);
273
278
  }
274
279
 
275
280
  /**
276
- * Why a Run will not start over State files a pipeline before the state branch
281
+ * Why a Run will not start over state files a pipeline before the state branch
277
282
  * left in the checkout, and what the human does about it.
278
283
  *
279
284
  * Each is a Ticket that pipeline could resume and this one cannot see, since
@@ -284,9 +289,9 @@ async function execute(
284
289
  function localStateMessage(tickets: number[]): string {
285
290
  const named = tickets.map((ticket) => `#${ticket}`).join(", ");
286
291
  return (
287
- `${LOCAL_STATE_DIR} holds State files for ${named}, which this Version no longer reads: ` +
292
+ `${LOCAL_STATE_DIR} holds state files for ${named}, which this version no longer reads: ` +
288
293
  "a Ticket's resume state lives on the Target's remote now. Finish those Tickets with " +
289
- `the Version that wrote the files, or hand them to a human, then delete ${LOCAL_STATE_DIR} ` +
294
+ `the version that wrote the files, or hand them to a human, then delete ${LOCAL_STATE_DIR} ` +
290
295
  "and run again."
291
296
  );
292
297
  }
package/src/stranded.ts CHANGED
@@ -5,26 +5,26 @@ import type { StateFile, Workspace } from "./ports/workspace.js";
5
5
  * The Tickets a Run that never came back left claimed, and how a later Run finds
6
6
  * them.
7
7
  *
8
- * A Run killed mid-Ticket releases nothing: the Claim stays on the board, the
9
- * State file on the Target's remote, and the branch on the remote as of its
8
+ * A Run killed mid-Ticket releases nothing: the claim stays on the board, the
9
+ * state file on the Target's remote, and the branch on the remote as of its
10
10
  * last committing Stage. The Frontier cannot see such a Ticket — it is claimed —
11
11
  * so without this nobody would ever pick it up again, on this Host or another.
12
12
  *
13
13
  * Nothing here needs a process id. The Run lock allows one Run at a time
14
- * (ADR-0004), so a Run holding the lock that finds a State file whose Ticket
15
- * still carries this user's Claim knows the Run that wrote it is gone.
14
+ * (ADR-0004), so a Run holding the lock that finds a state file whose Ticket
15
+ * still carries this user's claim knows the Run that wrote it is gone.
16
16
  */
17
17
 
18
18
  /** A Ticket still claimed by a Run that never came back, and where its work is. */
19
19
  export interface StrandedTicket {
20
20
  number: number;
21
21
  title: string;
22
- /** The branch the State file named, which is where the work actually is. */
22
+ /** The branch the state file named, which is where the work actually is. */
23
23
  branch: string;
24
24
  }
25
25
 
26
26
  /**
27
- * Whether this issue carries this user's Claim: assigned to them and labelled
27
+ * Whether this issue carries this user's claim: assigned to them and labelled
28
28
  * `in-progress`, which is what {@link import("./orchestrator.js").processTicket}
29
29
  * writes when it claims a Ticket. Both halves, because a Ticket holding only one
30
30
  * of them is one nobody can say is being worked on.
@@ -35,12 +35,12 @@ export function holdsClaim(issue: Issue, user: string, inProgress: string): bool
35
35
 
36
36
  export interface StrandedSweep {
37
37
  tracker: Tracker;
38
- /** Where the State is kept. */
38
+ /** Where the state is kept. */
39
39
  workspace: Workspace;
40
40
  /** The `in-progress` label, as this repo configured it. */
41
41
  inProgress: string;
42
42
  /**
43
- * The Tickets a narrowed Run was given. The State of every other Ticket is
43
+ * The Tickets a narrowed Run was given. The state of every other Ticket is
44
44
  * not read, asked about or removed: it is the next unnarrowed Run's.
45
45
  */
46
46
  only?: ReadonlySet<number>;
@@ -48,13 +48,13 @@ export interface StrandedSweep {
48
48
  }
49
49
 
50
50
  /**
51
- * Sweep the State the Workspace keeps on the remote for the Tickets this
51
+ * Sweep the state the Workspace keeps on the remote for the Tickets this
52
52
  * pipeline still holds, whichever Host's Run claimed them.
53
53
  *
54
- * Four things can be behind a State file, and only one of them is stranded:
54
+ * Four things can be behind a state file, and only one of them is stranded:
55
55
  *
56
- * - the Ticket still carries this user's Claim — stranded, and resumed in place
57
- * - the Claim has come off — a released Ticket, or one handed to a human, and
56
+ * - the Ticket still carries this user's claim — stranded, and resumed in place
57
+ * - the claim has come off — a released Ticket, or one handed to a human, and
58
58
  * neither is the sweep's: the Frontier picks up whichever of them is labelled
59
59
  * `ready-for-agent`, and a `ready-for-human` Ticket waits, inert, until a
60
60
  * human relabels it. Both are passed over in silence
@@ -118,19 +118,19 @@ export async function strandedTickets(sweep: StrandedSweep): Promise<StrandedTic
118
118
  }
119
119
 
120
120
  /**
121
- * A State file nothing here can resume from, named rather than dropped.
121
+ * A state file nothing here can resume from, named rather than dropped.
122
122
  *
123
- * The file and the Claim are left exactly where they are. A Ticket carrying a
123
+ * The file and the claim are left exactly where they are. A Ticket carrying a
124
124
  * file this pipeline cannot use is one a newer pipeline probably wrote, and
125
- * deleting either would take a Claim off the board that the machine which
125
+ * deleting either would take a claim off the board that the machine which
126
126
  * understands the file is still counting on (ADR-0007). So the sweep says the
127
- * Ticket number and whichever Version the file names, and a human decides.
127
+ * Ticket number and whichever version the file names, and a human decides.
128
128
  *
129
129
  * `cannot use` rather than `cannot read`, because the two files that land here
130
130
  * are not the same: one will not parse at all, and one parses but names another
131
- * Ticket than the file it is in, which no Version would resume either.
131
+ * Ticket than the file it is in, which no version would resume either.
132
132
  */
133
133
  function unreadableLine(file: Extract<StateFile, { readable: false }>): string {
134
- const wrote = file.version === undefined ? "naming no Version" : `written by ${file.version}`;
135
- return `#${file.ticket} has a State file this Version cannot use, ${wrote}; it and the Claim are left alone`;
134
+ const wrote = file.version === undefined ? "naming no version" : `written by ${file.version}`;
135
+ return `#${file.ticket} has a state file this version cannot use, ${wrote}; it and the claim are left alone`;
136
136
  }