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
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({
@@ -35,6 +35,9 @@ const stateSchema = z.object({
35
35
  fixUsed: z.boolean(),
36
36
  pullRequest: z.number().int().positive().optional(),
37
37
  title: z.string().optional(),
38
+ body: z.string().optional(),
39
+ problem: z.string().optional(),
40
+ solution: z.string().optional(),
38
41
  rebaseFirst: z.boolean().optional(),
39
42
  runId: z.string(),
40
43
  version: z.string().optional(),
@@ -66,7 +69,7 @@ export function stateFileContents(state: TicketState): string {
66
69
  * A file that is not JSON, one missing what resuming needs, and one a newer
67
70
  * pipeline shaped differently are all unreadable: starting the Ticket over is
68
71
  * 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.
72
+ * Ticket than its own name does, which no version would resume either.
70
73
  */
71
74
  export function readStateFile(contents: string, ticket: number): StateFile {
72
75
  const raw = parseJson(contents);
@@ -76,17 +79,21 @@ export function readStateFile(contents: string, ticket: number): StateFile {
76
79
  return { readable: false, ticket, ...(version === undefined ? {} : { version }) };
77
80
  }
78
81
 
79
- // A pull request nobody opened, a title no Stage answered, and a Version an
80
- // older pipeline never wrote, are keys that are not there rather than keys
81
- // holding nothing: the rest of the pipeline reads these with the same
82
- // distinction.
83
- const { pullRequest, title, rebaseFirst, version, ...state } = parsed.data;
82
+ // A pull request nobody opened, a title, body, problem or solution no Stage
83
+ // answered, and a version an older pipeline never wrote, are keys that are
84
+ // not there rather than keys holding nothing: the rest of the pipeline reads
85
+ // these with the same distinction.
86
+ const { pullRequest, title, body, problem, solution, rebaseFirst, version, ...state } =
87
+ parsed.data;
84
88
  return {
85
89
  readable: true,
86
90
  state: {
87
91
  ...state,
88
92
  ...(pullRequest === undefined ? {} : { pullRequest }),
89
93
  ...(title === undefined ? {} : { title }),
94
+ ...(body === undefined ? {} : { body }),
95
+ ...(problem === undefined ? {} : { problem }),
96
+ ...(solution === undefined ? {} : { solution }),
90
97
  ...(rebaseFirst === undefined ? {} : { rebaseFirst }),
91
98
  ...(version === undefined ? {} : { version }),
92
99
  },
@@ -94,11 +101,11 @@ export function readStateFile(contents: string, ticket: number): StateFile {
94
101
  }
95
102
 
96
103
  /**
97
- * The Version a file that will not parse still names, where it names one.
104
+ * The version a file that will not parse still names, where it names one.
98
105
  *
99
106
  * 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.
107
+ * what refused the file: a state file a newer pipeline wrote is named by the
108
+ * version that wrote it, whatever else about it this one cannot read.
102
109
  */
103
110
  function namedVersion(raw: unknown): string | undefined {
104
111
  if (raw === null || typeof raw !== "object" || !("version" in raw)) return undefined;
@@ -116,19 +123,20 @@ function parseJson(contents: string): unknown {
116
123
  }
117
124
 
118
125
  /**
119
- * The branch of the Target's remote that holds every Ticket's State, one file
120
- * per Ticket, and the transcripts of a handed-off Ticket's Stages beside it,
121
- * under the prefix the pipeline owns (ADR-0004). Named here rather than only in
122
- * the Workspace that writes it, because `ticket-runner remove` deletes it by
123
- * name and the conventions document names it to every human.
126
+ * The branch of the Target's remote that holds every Ticket's state, one file
127
+ * per Ticket, and the transcripts of a handed-off Ticket's Stages beside it
128
+ * where the Run keeps them on the remote, under the prefix the pipeline owns
129
+ * (ADR-0004). Named here rather than only in the Workspace that writes it,
130
+ * because `ticket-runner remove` deletes it by name and the conventions
131
+ * document names it to every human.
124
132
  */
125
133
  export const STATE_BRANCH = "ticket-runner/state";
126
134
 
127
- /** Where a pipeline before the state branch kept the State files, in the checkout. */
135
+ /** Where a pipeline before the state branch kept the state files, in the checkout. */
128
136
  export const LOCAL_STATE_DIR = join(".ticket-runner", "state");
129
137
 
130
138
  /**
131
- * The Tickets whose State files a pipeline before the state branch left in this
139
+ * The Tickets whose state files a pipeline before the state branch left in this
132
140
  * checkout, in ascending number.
133
141
  *
134
142
  * 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
@@ -2,7 +2,8 @@ import { branchName } from "./branch.js";
2
2
  import { selectFrontier } from "./frontier.js";
3
3
  import { type Refusal, isGuardReason, skipReason } from "./guards.js";
4
4
  import type { RoutedNote } from "./notes.js";
5
- import { type Pipeline, type TicketOutcome, processTicket } from "./orchestrator.js";
5
+ import { type Pipeline, type TicketOutcome, faultOutcome, processTicket } from "./orchestrator.js";
6
+ import { type FaultSide, OutsideFault } from "./outside-fault.js";
6
7
  import { StopSignal, stopLine } from "./stop.js";
7
8
  import { holdsClaim, strandedTickets } from "./stranded.js";
8
9
  import { releaseWords } from "./templates.js";
@@ -34,7 +35,8 @@ export interface RunResult {
34
35
  * A Run that drained the Frontier carries what was left held back; one a
35
36
  * Release stopped carries no candidates, because it ended before it could say
36
37
  * one was held back all Run, and the rate limit carries when it resets, where a
37
- * Stage was told, and a failing Base branch the Check it fails and where; one
38
+ * Stage was told, a failing base branch the Check it fails and where, and a
39
+ * fault of GitHub's or the remote's the command and what it printed; one
38
40
  * a human stopped carries the moment it was asked and what it still had in
39
41
  * hand. That is why this is a choice rather than a flag beside
40
42
  * the list: the stops do not report the same things.
@@ -63,6 +65,14 @@ export type RunStop =
63
65
  /** The Check command it failed. */
64
66
  command: string;
65
67
  }
68
+ | {
69
+ /** GitHub, or the git remote, failing on its own side. */
70
+ reason: FaultSide;
71
+ /** The command that failed, on one line. */
72
+ command: string;
73
+ /** The first line it printed. */
74
+ line: string;
75
+ }
66
76
  | {
67
77
  reason: "stopped";
68
78
  /** When the Stop reached the Run, ISO-8601. */
@@ -96,11 +106,13 @@ export type RunStop =
96
106
  * A Release stops the Run filling Lanes and nothing more. Nothing was wrong with
97
107
  * the Ticket — the subscription or the API key ran out of room, or the API
98
108
  * failed on its own side after the CLI had given up retrying it — so the next
99
- * one would be stopped the same way, and claiming it would spend a Claim, a
109
+ * one would be stopped the same way, and claiming it would spend a claim, a
100
110
  * worktree and a doomed Stage to learn what the first one already said. The Lanes still busy finish
101
111
  * what they hold, and the Run reports what stopped it once the last of them
102
112
  * comes back. It does not wait for the limit to reset: a human or an Operator
103
- * starts the next Run, and the summary says when the limit resets.
113
+ * starts the next Run, and the summary says when the limit resets. A hand-off
114
+ * that GitHub or the remote cut short stops it the same way, for the same
115
+ * reason, though its Ticket is reported handed off.
104
116
  *
105
117
  * A Stop is the same shape with a different reason: a human asked for no more
106
118
  * Tickets rather than the subscription, so the Lanes busy at that moment finish
@@ -109,7 +121,7 @@ export type RunStop =
109
121
  * own behind where a killed one leaves all of them (ADR-0006).
110
122
  *
111
123
  * Before any of that, the Tickets a Run that never came back left claimed are
112
- * resumed. They are not on the Frontier and never will be — the Claim they still
124
+ * resumed. They are not on the Frontier and never will be — the claim they still
113
125
  * wear is what keeps them off it — so this sweep is the only thing that ever
114
126
  * picks them up again, and a free Lane takes one before it takes anything the
115
127
  * Frontier is offering.
@@ -132,7 +144,7 @@ export async function processRun(
132
144
  // Every Ticket this Run has taken. A Ticket normally leaves the candidate
133
145
  // list by being closed or relabelled; this is what stops a Run offering one
134
146
  // to a second Lane, whether because that write did not land or because the
135
- // Claim of the Lane holding it has not reached GitHub yet.
147
+ // claim of the Lane holding it has not reached GitHub yet.
136
148
  const taken = new Set<number>();
137
149
  // The Lanes with a Ticket in them, by Ticket number. A Lane takes itself out
138
150
  // of here as its Ticket ends rather than where the Run waits, so a fill pass
@@ -189,9 +201,10 @@ export async function processRun(
189
201
  /**
190
202
  * Put a Ticket in a Lane, and record what came back when it ends.
191
203
  *
192
- * The line about the Run stopping is logged by the Release that stopped it and
193
- * by no other, even where a later Release outranks it on the last line. The
194
- * Ticket's own release is already logged where it happened; this says the Run
204
+ * The line about the Run stopping is logged by the Release that stopped it,
205
+ * or by the hand-off a fault outside the Ticket cut short, and by no other,
206
+ * even where a later Release outranks it on the last line. The Ticket's own
207
+ * release is already logged where it happened; this says the Run
195
208
  * goes no further, so a transcript shows the Frontier was left alone rather
196
209
  * than found empty, and a Release into a Run that an earlier Release or a
197
210
  * Stop had stopped already claims to have stopped nothing. It leads with the
@@ -206,6 +219,17 @@ export async function processRun(
206
219
  busy.delete(ticket.number);
207
220
  ended += 1;
208
221
  outcomes.push(outcome);
222
+ if (outcome.outcome === "handed-off" && outcome.fault !== undefined) {
223
+ // A hand-off the fault cut short stops the Run as a Release over it
224
+ // would, and outranks nothing that stopped it first.
225
+ if (runStop !== undefined) return;
226
+ const { side, command, line } = outcome.fault;
227
+ runStop = { reason: side, command, line };
228
+ pipeline.log?.(
229
+ `#${outcome.ticket} stopped the Run · ${releaseWords(side, pipeline.credential)}`,
230
+ );
231
+ return;
232
+ }
209
233
  if (outcome.outcome !== "released") return;
210
234
  if (runStop === undefined) {
211
235
  runStop = releaseStop(outcome, pipeline.baseBranch);
@@ -319,7 +343,7 @@ function pollFailure(error: unknown): string {
319
343
 
320
344
  /**
321
345
  * The stop a Release puts on the Run: what released it, when a limit resets,
322
- * and which Check the Base branch fails.
346
+ * which Check the base branch fails, and what GitHub or the remote failed.
323
347
  */
324
348
  function releaseStop(
325
349
  outcome: Extract<TicketOutcome, { outcome: "released" }>,
@@ -327,6 +351,9 @@ function releaseStop(
327
351
  ): RunStop {
328
352
  if (outcome.cause === "api-error") return { reason: "api-error" };
329
353
  if (outcome.cause === "out-of-budget") return { reason: "out-of-budget" };
354
+ if ((outcome.cause === "github" || outcome.cause === "remote") && outcome.fault !== undefined) {
355
+ return { reason: outcome.cause, ...outcome.fault };
356
+ }
330
357
  if (outcome.failingBase !== undefined) {
331
358
  return { reason: "failing-base", baseBranch, ...outcome.failingBase };
332
359
  }
@@ -343,8 +370,9 @@ function releaseStop(
343
370
  * it alone needs the human to act: no wait mends it, only the Console. The
344
371
  * rate limit outranks an API failure, which says nothing of when the next Run
345
372
  * can start, and a limit nobody was told the end of is outranked by one a
346
- * Stage was told. A failing Base branch and a Stop stay whatever comes after
347
- * them, and so does an API budget, and a limit already told when it resets.
373
+ * Stage was told. A failing base branch and a Stop stay whatever comes after
374
+ * them, and so does an API budget, a limit already told when it resets, and a
375
+ * fault of GitHub's or the remote's.
348
376
  */
349
377
  function outranks(
350
378
  outcome: Extract<TicketOutcome, { outcome: "released" }>,
@@ -425,6 +453,10 @@ async function nobodysToTake(pipeline: Pipeline, ticket: number): Promise<Skippe
425
453
  * hand-off writes are outside that net: a tracker that goes down mid-Ticket
426
454
  * would otherwise take the whole Run with it. The Ticket is reported as handed
427
455
  * off — which, without the label, is what a human will find on the board.
456
+ *
457
+ * Unless GitHub or the remote failed on its own side, before the claim or in
458
+ * it: that is a fault outside the Ticket, reported released so the Run claims
459
+ * no more, and the Ticket is left as far as the claim got, for the next Run.
428
460
  */
429
461
  async function take(pipeline: Pipeline, ticket: Taken): Promise<TicketOutcome> {
430
462
  // Handed to the Ticket rather than read off its outcome, because there is no
@@ -434,6 +466,16 @@ async function take(pipeline: Pipeline, ticket: Taken): Promise<TicketOutcome> {
434
466
  try {
435
467
  return await processTicket(pipeline, ticket.number, notes);
436
468
  } catch (error) {
469
+ if (error instanceof OutsideFault) {
470
+ pipeline.log?.(`#${ticket.number} stopped at setup · ${error.message}`);
471
+ return faultOutcome(
472
+ { number: ticket.number, title: ticket.title },
473
+ ticket.branch,
474
+ "setup",
475
+ error,
476
+ notes,
477
+ );
478
+ }
437
479
  const failure = (error as Error).message;
438
480
  pipeline.log?.(`#${ticket.number} failed outside the hand-off path: ${failure}`);
439
481
  return {
@@ -454,7 +496,7 @@ async function take(pipeline: Pipeline, ticket: Taken): Promise<TicketOutcome> {
454
496
  *
455
497
  * The branch is carried rather than derived, because the two ways a Run reaches
456
498
  * a Ticket know it differently: a candidate off the Frontier has whatever its
457
- * title derives to, and a stranded Ticket has the branch its State file names —
499
+ * title derives to, and a stranded Ticket has the branch its state file names —
458
500
  * which is where the work actually is, whatever the title says now.
459
501
  */
460
502
  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
@@ -3,6 +3,7 @@ import type { Config } from "./config.js";
3
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";
@@ -19,6 +20,7 @@ import { conventionsWarning, newerVersionLine } from "./staleness.js";
19
20
  import { type StopSource, StopSignal, listenForStop } from "./stop.js";
20
21
  import { startupMessages } from "./startup.js";
21
22
  import { runSummary } from "./templates.js";
23
+ import { resolveTranscriptHome } from "./transcript-home.js";
22
24
 
23
25
  /**
24
26
  * Everything between the arguments and the work: the two refusals a Run can
@@ -57,12 +59,12 @@ export interface StartOptions {
57
59
  workspace: Workspace;
58
60
  runId: string;
59
61
  /**
60
- * The Version this Run is, resolved once in the CLI (ADR-0007). Everything
62
+ * The version this Run is, resolved once in the CLI (ADR-0007). Everything
61
63
  * the Run stamps takes it from here, so every stamp says the same thing.
62
64
  */
63
65
  version: string;
64
66
  /**
65
- * The pipeline's own repository, as `owner/name`, which the newer-Version
67
+ * The pipeline's own repository, as `owner/name`, which the newer-version
66
68
  * notice is looked up against; see {@link import("./staleness.js")}.
67
69
  */
68
70
  repository?: string | undefined;
@@ -85,7 +87,7 @@ export interface StartOptions {
85
87
  *
86
88
  * Every refusal comes before the lock: an `--api-key` the Host cannot honour,
87
89
  * 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
90
+ * one holding state files an earlier pipeline left in the checkout, and one
89
91
  * with nothing to gate a merge. None is a Run that went wrong, so none should
90
92
  * leave a lock behind for the next one to reclaim.
91
93
  */
@@ -101,7 +103,7 @@ export async function startRun(given: StartOptions): Promise<number> {
101
103
  const env = options.env ?? process.env;
102
104
 
103
105
  // 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.
106
+ // cannot bill the Stages to what the Run was started with.
105
107
  const credential: Credential = options.work.apiKey === true ? "api-key" : "subscription";
106
108
  const host = hostKind(env);
107
109
  const refusedCredential = credentialRefusal(credential, host, env);
@@ -135,9 +137,9 @@ export async function startRun(given: StartOptions): Promise<number> {
135
137
  }
136
138
 
137
139
  const { refusal, warnings } = startupMessages(config);
138
- // Which Version the document names is a warning and never a refusal, so it
140
+ // Which version the document names is a warning and never a refusal, so it
139
141
  // 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).
142
+ // and one naming another version is nothing a Run is worse for (ADR-0007).
141
143
  const stale = conventionsWarning(repoRoot, options.version);
142
144
  for (const warning of [...warnings, ...(stale === undefined ? [] : [stale])]) {
143
145
  error(`warning: ${warning}`);
@@ -174,7 +176,7 @@ export async function startRun(given: StartOptions): Promise<number> {
174
176
  const stopping = new StopSignal();
175
177
  const deafen = listenForStop(stopping, options.signals);
176
178
  try {
177
- return await execute(options, { credential, host, baseBranch }, log, stopping);
179
+ return await execute(options, { credential, baseBranch, host }, log, stopping);
178
180
  } finally {
179
181
  // The lock goes first: SIGTERM between the two is a kill again, and a kill
180
182
  // that leaves the lock behind costs the next Run a stale holder to reclaim,
@@ -195,13 +197,17 @@ async function execute(
195
197
  options: StartOptions,
196
198
  {
197
199
  credential,
198
- host,
199
200
  baseBranch,
200
- }: { credential: Credential; host: HostKind; baseBranch: string },
201
- log: (line: string) => void,
201
+ host,
202
+ }: { credential: Credential; baseBranch: string; host: HostKind },
203
+ print: (line: string) => void,
202
204
  stopping: StopSignal,
203
205
  ): Promise<number> {
204
206
  const { work, repoRoot, config, tracker, runner, workspace, runId, version } = options;
207
+ // Every event of the Run goes through this, and one cause tends to fail
208
+ // several of them with the same output, so each output is printed once. The
209
+ // summary is printed as it is: it is one block, written once.
210
+ const log = printEachOutputOnce(print);
205
211
 
206
212
  // Before the first Stage, and before the tracker is asked anything: a
207
213
  // transcript has to sit beside the pipeline that wrote it, and the Run
@@ -211,7 +217,7 @@ async function execute(
211
217
  try {
212
218
  writeRunVersion(repoRoot, runId, version);
213
219
  } catch (error) {
214
- log(`could not record the Version beside the transcripts: ${(error as Error).message}`);
220
+ log(`could not record the version beside the transcripts: ${(error as Error).message}`);
215
221
  }
216
222
 
217
223
  // Asked once, and said twice: at the top of the log a human watches, and
@@ -225,6 +231,9 @@ async function execute(
225
231
  // Once per Run: only a Target that is the pipeline's own repository
226
232
  // has a checkout that is the pipeline, and every Stage is told which it is in.
227
233
  const selfHosted = await isPipelineRepository(tracker, options.repository);
234
+ // Once per Run as well: whether the Target is public is read here and no
235
+ // later, so every hand-off of the Run keeps its transcripts in one place.
236
+ const transcriptHome = await resolveTranscriptHome({ config, tracker, host });
228
237
 
229
238
  const pipeline: Pipeline = {
230
239
  tracker,
@@ -234,7 +243,6 @@ async function execute(
234
243
  repoRoot,
235
244
  runId,
236
245
  version,
237
- host,
238
246
  credential,
239
247
  billing: emptyBilling(),
240
248
  baseBranch,
@@ -249,12 +257,17 @@ async function execute(
249
257
  // branch run it at their merge-base once between them.
250
258
  baseChecks: new BaseBranchChecks(),
251
259
  selfHosted,
260
+ transcriptHome: transcriptHome.home,
252
261
  log,
253
262
  };
254
263
 
255
264
  const startedAt = Date.now();
256
265
  log(opening(runId, work, config.lanes));
257
266
  if (newer !== undefined) log(newer);
267
+ if (transcriptHome.said !== undefined) log(transcriptHome.said);
268
+ // Before the first claim, on any Host: a shallow clone refuses every move of
269
+ // its base branch a rebase needs, and would hand off each Ticket there.
270
+ if (await workspace.unshallow()) log("the clone was shallow, so its full history was fetched");
258
271
  const summary = (outcomes: TicketOutcome[], stop: RunStop) =>
259
272
  runSummary({
260
273
  version,
@@ -268,12 +281,12 @@ async function execute(
268
281
  });
269
282
 
270
283
  const { outcomes, stop } = await processRun(pipeline, stopping, work.tickets);
271
- log(`\n${summary(outcomes, stop)}`);
284
+ print(`\n${summary(outcomes, stop)}`);
272
285
  return exitCode(outcomes, work.tickets !== undefined);
273
286
  }
274
287
 
275
288
  /**
276
- * Why a Run will not start over State files a pipeline before the state branch
289
+ * Why a Run will not start over state files a pipeline before the state branch
277
290
  * left in the checkout, and what the human does about it.
278
291
  *
279
292
  * Each is a Ticket that pipeline could resume and this one cannot see, since
@@ -284,9 +297,9 @@ async function execute(
284
297
  function localStateMessage(tickets: number[]): string {
285
298
  const named = tickets.map((ticket) => `#${ticket}`).join(", ");
286
299
  return (
287
- `${LOCAL_STATE_DIR} holds State files for ${named}, which this Version no longer reads: ` +
300
+ `${LOCAL_STATE_DIR} holds state files for ${named}, which this version no longer reads: ` +
288
301
  "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} ` +
302
+ `the version that wrote the files, or hand them to a human, then delete ${LOCAL_STATE_DIR} ` +
290
303
  "and run again."
291
304
  );
292
305
  }
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
  }