ticket-runner 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/LICENSE +21 -0
  2. package/README.ko.md +97 -0
  3. package/README.md +98 -0
  4. package/bin/ticket-runner.js +6 -0
  5. package/docs/templates/operator-skill.md +87 -0
  6. package/package.json +42 -0
  7. package/src/acceptance-criteria.ts +44 -0
  8. package/src/adapters/claude-agent-runner.ts +389 -0
  9. package/src/adapters/exec.ts +169 -0
  10. package/src/adapters/gh-tracker.ts +955 -0
  11. package/src/adapters/git-workspace.ts +951 -0
  12. package/src/adapters/repo-root.ts +20 -0
  13. package/src/adapters/version.ts +118 -0
  14. package/src/base-branch.ts +21 -0
  15. package/src/branch.ts +33 -0
  16. package/src/cli.ts +135 -0
  17. package/src/command-line.ts +190 -0
  18. package/src/config.ts +277 -0
  19. package/src/conventions.ts +118 -0
  20. package/src/criteria.ts +106 -0
  21. package/src/frontier.ts +36 -0
  22. package/src/guards.ts +143 -0
  23. package/src/handoff.ts +82 -0
  24. package/src/host.ts +116 -0
  25. package/src/init.ts +405 -0
  26. package/src/labels.ts +42 -0
  27. package/src/landing.ts +75 -0
  28. package/src/lifecycle.ts +34 -0
  29. package/src/lock.ts +215 -0
  30. package/src/note-schema.ts +58 -0
  31. package/src/notes.ts +433 -0
  32. package/src/operator-skill.ts +24 -0
  33. package/src/orchestrator.ts +1816 -0
  34. package/src/ports/agent-runner.ts +105 -0
  35. package/src/ports/tracker.ts +334 -0
  36. package/src/ports/workspace.ts +422 -0
  37. package/src/progress.ts +231 -0
  38. package/src/prompts.ts +288 -0
  39. package/src/readiness.ts +256 -0
  40. package/src/remove.ts +732 -0
  41. package/src/resume.ts +145 -0
  42. package/src/run-log.ts +85 -0
  43. package/src/run.ts +331 -0
  44. package/src/self-hosting.ts +33 -0
  45. package/src/stage-guard.ts +32 -0
  46. package/src/staleness.ts +101 -0
  47. package/src/start.ts +284 -0
  48. package/src/startup.ts +34 -0
  49. package/src/stop.ts +178 -0
  50. package/src/stranded.ts +136 -0
  51. package/src/templates.ts +596 -0
  52. package/src/title.ts +97 -0
  53. package/src/verdict.ts +88 -0
  54. package/src/version-number.ts +67 -0
  55. package/src/version-pr.ts +103 -0
package/src/resume.ts ADDED
@@ -0,0 +1,145 @@
1
+ import { readdirSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ import { z } from "zod";
4
+ import { REACHED_STATES, type StateFile, type TicketState } from "./ports/workspace.js";
5
+
6
+ /**
7
+ * The State file a Ticket keeps while its branch carries work worth resuming,
8
+ * and what a later Run makes of it (ADR-0004).
9
+ *
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
12
+ * Ticket reaches something a later Run should not pay for again. Three Runs read
13
+ * it, and what the board says decides which. One finds a Ticket the subscription
14
+ * rate limit released: nothing was wrong with it, so the Claim came off and this
15
+ * file says where to carry on from. One finds a Ticket still claimed — the Run
16
+ * that claimed it was killed and never released anything — and resumes it in
17
+ * place. One finds a Ticket a human was handed and has relabelled
18
+ * `ready-for-agent`, which is the human handing it back. A Ticket still sitting
19
+ * in `ready-for-human` is none of them: its file is inert until a human moves
20
+ * the label or the issue closes.
21
+ *
22
+ * It lives on the Target's remote, where a Run on any Host finds it; where
23
+ * exactly is the git-backed Workspace's business
24
+ * ({@link import("./ports/workspace.js").Workspace.readState} and the rest).
25
+ * This is only what the file says and what its name is, which that Workspace
26
+ * reads and writes through here. Whether the branch a file names is still there
27
+ * is the Workspace's other question, and whether the Ticket is released or
28
+ * stranded is the Claim's, read off GitHub.
29
+ */
30
+
31
+ const stateSchema = z.object({
32
+ ticket: z.number().int().positive(),
33
+ branch: z.string().min(1),
34
+ state: z.enum(REACHED_STATES),
35
+ fixUsed: z.boolean(),
36
+ pullRequest: z.number().int().positive().optional(),
37
+ title: z.string().optional(),
38
+ runId: z.string(),
39
+ version: z.string().optional(),
40
+ updatedAt: z.string(),
41
+ });
42
+
43
+ /** One file per Ticket, named for it. */
44
+ export function stateFileName(ticket: number): string {
45
+ return `ticket-${ticket}.json`;
46
+ }
47
+
48
+ /** The name {@link stateFileName} gives, read back the other way. */
49
+ const STATE_FILE = /^ticket-(\d+)\.json$/;
50
+
51
+ /** The Ticket a file of that name is about, or undefined for any other file. */
52
+ export function stateFileTicket(name: string): number | undefined {
53
+ const match = STATE_FILE.exec(name);
54
+ return match === null ? undefined : Number.parseInt(match[1] as string, 10);
55
+ }
56
+
57
+ /** What the file holds: JSON a human can read without the pipeline. */
58
+ export function stateFileContents(state: TicketState): string {
59
+ return `${JSON.stringify(state, null, 2)}\n`;
60
+ }
61
+
62
+ /**
63
+ * What the file `ticket` keeps says, and which of the two things it is.
64
+ *
65
+ * A file that is not JSON, one missing what resuming needs, and one a newer
66
+ * pipeline shaped differently are all unreadable: starting the Ticket over is
67
+ * always safe, and resuming on a guess is not. So is one that names another
68
+ * Ticket than its own name does, which no Version would resume either.
69
+ */
70
+ export function readStateFile(contents: string, ticket: number): StateFile {
71
+ const raw = parseJson(contents);
72
+ const parsed = stateSchema.safeParse(raw);
73
+ if (!parsed.success || parsed.data.ticket !== ticket) {
74
+ const version = namedVersion(raw);
75
+ return { readable: false, ticket, ...(version === undefined ? {} : { version }) };
76
+ }
77
+
78
+ // A pull request nobody opened, a title no Stage answered, and a Version an
79
+ // older pipeline never wrote, are keys that are not there rather than keys
80
+ // holding nothing: the rest of the pipeline reads these with the same
81
+ // distinction.
82
+ const { pullRequest, title, version, ...state } = parsed.data;
83
+ return {
84
+ readable: true,
85
+ state: {
86
+ ...state,
87
+ ...(pullRequest === undefined ? {} : { pullRequest }),
88
+ ...(title === undefined ? {} : { title }),
89
+ ...(version === undefined ? {} : { version }),
90
+ },
91
+ };
92
+ }
93
+
94
+ /**
95
+ * The Version a file that will not parse still names, where it names one.
96
+ *
97
+ * Read off the raw JSON rather than the schema, because the schema is exactly
98
+ * what refused the file: a State file a newer pipeline wrote is named by the
99
+ * Version that wrote it, whatever else about it this one cannot read.
100
+ */
101
+ function namedVersion(raw: unknown): string | undefined {
102
+ if (raw === null || typeof raw !== "object" || !("version" in raw)) return undefined;
103
+ const version = (raw as { version: unknown }).version;
104
+ return typeof version === "string" && version !== "" ? version : undefined;
105
+ }
106
+
107
+ /** The file's JSON, or undefined where it is not JSON — which the schema refuses. */
108
+ function parseJson(contents: string): unknown {
109
+ try {
110
+ return JSON.parse(contents);
111
+ } catch {
112
+ return undefined;
113
+ }
114
+ }
115
+
116
+ /**
117
+ * The branch of the Target's remote that holds every Ticket's State, one file
118
+ * per Ticket, and the transcripts of a handed-off Ticket's Stages beside it,
119
+ * under the prefix the pipeline owns (ADR-0004). Named here rather than only in
120
+ * the Workspace that writes it, because `ticket-runner remove` deletes it by
121
+ * name and the conventions document names it to every human.
122
+ */
123
+ export const STATE_BRANCH = "ticket-runner/state";
124
+
125
+ /** Where a pipeline before the state branch kept the State files, in the checkout. */
126
+ export const LOCAL_STATE_DIR = join(".ticket-runner", "state");
127
+
128
+ /**
129
+ * The Tickets whose State files a pipeline before the state branch left in this
130
+ * checkout, in ascending number.
131
+ *
132
+ * Nothing reads them any more, and nothing migrates them (ADR-0004): a Run that
133
+ * finds any refuses to start, because each is a Ticket a Run would otherwise
134
+ * take from the top, or never sweep at all, without a word.
135
+ */
136
+ export function localStateTickets(repoRoot: string): number[] {
137
+ let entries: string[];
138
+ try {
139
+ entries = readdirSync(join(repoRoot, LOCAL_STATE_DIR));
140
+ } catch {
141
+ // No directory at all: no earlier pipeline ever claimed anything here.
142
+ return [];
143
+ }
144
+ return entries.flatMap((entry) => stateFileTicket(entry) ?? []).sort((a, b) => a - b);
145
+ }
package/src/run-log.ts ADDED
@@ -0,0 +1,85 @@
1
+ import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
2
+ import { join, sep } from "node:path";
3
+
4
+ /** Where one Run's transcripts live: one directory per Run, under the repo root. */
5
+ export function runLogDir(repoRoot: string, runId: string): string {
6
+ return join(repoRoot, ".ticket-runner", "runs", runId);
7
+ }
8
+
9
+ /**
10
+ * Where a Stage's command line, stdout, stderr and transcript are written:
11
+ * one directory per Run, per Ticket, under the gitignored run directory.
12
+ */
13
+ export function stageLogDir(repoRoot: string, runId: string, ticket: number): string {
14
+ return join(runLogDir(repoRoot, runId), String(ticket));
15
+ }
16
+
17
+ /**
18
+ * Where the fix Stage and the pass it bought write instead.
19
+ *
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
22
+ * is the transcript a human most needs when the Ticket is handed off anyway.
23
+ */
24
+ export function retryLogDir(repoRoot: string, runId: string, ticket: number): string {
25
+ return join(stageLogDir(repoRoot, runId, ticket), "retry");
26
+ }
27
+
28
+ /** The file naming the Version, at the top of a Run's transcripts. */
29
+ export const VERSION_FILE = "version.txt";
30
+
31
+ /**
32
+ * Say which Version this Run is, beside the transcripts it is about to write.
33
+ *
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
36
+ * terminal the night is over for, and these files outlive it (ADR-0007).
37
+ */
38
+ export function writeRunVersion(repoRoot: string, runId: string, version: string): void {
39
+ const directory = runLogDir(repoRoot, runId);
40
+ mkdirSync(directory, { recursive: true });
41
+ writeFileSync(join(directory, VERSION_FILE), `${version}\n`);
42
+ }
43
+
44
+ /**
45
+ * What of a Stage's files a hand-off keeps: its command line, to reproduce it
46
+ * by hand, and its transcript, to read why it did what it did. Its stdout is
47
+ * what the transcript was parsed out of, and its stderr is the CLI's own.
48
+ */
49
+ const KEPT_SUFFIXES = [".command", ".transcript.jsonl"];
50
+
51
+ /** One file a hand-off keeps: its name under the Ticket's, and where it is on disk. */
52
+ export interface TranscriptFile {
53
+ /** `/`-separated, whatever the platform, since it names a file on a git branch. */
54
+ name: string;
55
+ path: string;
56
+ }
57
+
58
+ /**
59
+ * The files Run `runId` wrote for `ticket` that a hand-off keeps, in name
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
62
+ * once they are somewhere else. None when the Run wrote nothing for the Ticket.
63
+ */
64
+ export function transcriptFiles(
65
+ repoRoot: string,
66
+ runId: string,
67
+ ticket: number,
68
+ ): TranscriptFile[] {
69
+ const directory = stageLogDir(repoRoot, runId, ticket);
70
+ if (!existsSync(directory)) return [];
71
+
72
+ const stages = readdirSync(directory, { recursive: true, encoding: "utf8" })
73
+ .filter((name) => KEPT_SUFFIXES.some((suffix) => name.endsWith(suffix)))
74
+ .map((name) => ({ name: name.split(sep).join("/"), path: join(directory, name) }));
75
+ if (stages.length === 0) return [];
76
+
77
+ const version = join(runLogDir(repoRoot, runId), VERSION_FILE);
78
+ const files = existsSync(version) ? [...stages, { name: VERSION_FILE, path: version }] : stages;
79
+ return files.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
80
+ }
81
+
82
+ /** A run id that sorts chronologically and is safe in a path. */
83
+ export function newRunId(now: Date = new Date()): string {
84
+ return now.toISOString().replace(/[:.]/g, "-").replace("Z", "");
85
+ }
package/src/run.ts ADDED
@@ -0,0 +1,331 @@
1
+ import { branchName } from "./branch.js";
2
+ import { selectFrontier } from "./frontier.js";
3
+ import { type Refusal, isGuardReason, skipReason } from "./guards.js";
4
+ import type { RoutedNote } from "./notes.js";
5
+ import { type Pipeline, type TicketOutcome, processTicket } from "./orchestrator.js";
6
+ import { StopSignal, stopLine } from "./stop.js";
7
+ import { holdsClaim, strandedTickets } from "./stranded.js";
8
+
9
+ /**
10
+ * What a Run has to show for itself: every Ticket it took, in the order they
11
+ * ended, and why it stopped taking them.
12
+ *
13
+ * The order is completion rather than claim because Lanes run side by side: two
14
+ * Tickets claimed in the same breath finish whenever their own Stages let them,
15
+ * and the summary reads as the night happened rather than as it was planned.
16
+ */
17
+ export interface RunResult {
18
+ outcomes: TicketOutcome[];
19
+ stop: RunStop;
20
+ }
21
+
22
+ /**
23
+ * Why a Run ended.
24
+ *
25
+ * A Run that drained the Frontier carries what was left held back; one the rate
26
+ * limit stopped carries nothing, because it ended before it could say a
27
+ * candidate was held back all Run; one a human stopped carries the moment it
28
+ * was asked and what it still had in hand. That is why this is a choice rather
29
+ * than a flag beside the list: the three stops do not report the same things.
30
+ */
31
+ export type RunStop =
32
+ | {
33
+ reason: "frontier";
34
+ /**
35
+ * Candidates still held back by an open blocker when the Run ended: of
36
+ * a narrowed Run, only the ones it was given, whatever blocks them.
37
+ */
38
+ blocked: number[];
39
+ }
40
+ | { reason: "rate-limited" }
41
+ | {
42
+ reason: "stopped";
43
+ /** When the Stop reached the Run, ISO-8601. */
44
+ at: string;
45
+ /** The Tickets its Lanes were holding at that moment, ascending. */
46
+ busy: number[];
47
+ };
48
+
49
+ /**
50
+ * Drain the Frontier through the Lanes the Target's config gives the Run.
51
+ *
52
+ * Every free Lane is filled at once, and a Lane is filled again the moment the
53
+ * Ticket in it ends — merged, handed off or released. The Frontier is recomputed
54
+ * at every refill rather than snapshotted, so a merge that closes a blocker puts
55
+ * the Ticket it unblocked into the same Run, and a Ticket another Lane is still
56
+ * working is still an open blocker. Those edges are the whole of what keeps two
57
+ * Tickets apart: no heuristic here decides which are safe together.
58
+ *
59
+ * A Ticket that fails is handed off and the Lane moves on: one bad Ticket must
60
+ * not cost the rest of the night.
61
+ *
62
+ * A Release stops the Run filling Lanes and nothing more. Nothing was wrong with
63
+ * the Ticket — the subscription ran out of room — so the next one would be
64
+ * stopped by the same limit, and claiming it would spend a Claim, a worktree and
65
+ * a doomed Stage to learn what the first one already said. The Lanes still busy
66
+ * finish what they hold, and the Run reports the limit once the last of them
67
+ * comes back.
68
+ *
69
+ * A Stop is the same shape with a different reason: a human asked for no more
70
+ * Tickets rather than the subscription, so the Lanes busy at that moment finish
71
+ * what they hold and the Run takes nothing else — not off the Frontier and not
72
+ * off the Stranded Tickets, which is what makes a stopped Run leave none of its
73
+ * own behind where a killed one leaves all of them (ADR-0006).
74
+ *
75
+ * Before any of that, the Tickets a Run that never came back left claimed are
76
+ * resumed. They are not on the Frontier and never will be — the Claim they still
77
+ * wear is what keeps them off it — so this sweep is the only thing that ever
78
+ * picks them up again, and a free Lane takes one before it takes anything the
79
+ * Frontier is offering.
80
+ *
81
+ * A Run given `tickets` is that Run narrowed to them, and nothing else about it
82
+ * changes: the sweep and every refill see only those Tickets, and every other
83
+ * one, stranded or on the Frontier, is left as it was for the next Run. One of
84
+ * them the Run never met — nobody's to take, or no issue at all — is reported
85
+ * as skipped once the Lanes are back, so none of them drops out of the summary.
86
+ */
87
+ export async function processRun(
88
+ pipeline: Pipeline,
89
+ stopping: StopSignal = new StopSignal(),
90
+ tickets?: readonly number[],
91
+ ): Promise<RunResult> {
92
+ const { tracker, config } = pipeline;
93
+ const named = tickets === undefined ? undefined : new Set(tickets);
94
+
95
+ const outcomes: TicketOutcome[] = [];
96
+ // Every Ticket this Run has taken. A Ticket normally leaves the candidate
97
+ // list by being closed or relabelled; this is what stops a Run offering one
98
+ // to a second Lane, whether because that write did not land or because the
99
+ // Claim of the Lane holding it has not reached GitHub yet.
100
+ const taken = new Set<number>();
101
+ // The Lanes with a Ticket in them, by Ticket number. A Lane takes itself out
102
+ // of here as its Ticket ends rather than where the Run waits, so a fill pass
103
+ // that several Lanes came back during sees every one of them free.
104
+ const busy = new Map<number, Promise<void>>();
105
+ // What the last Frontier this Run computed held back, which is what a Run
106
+ // that drained the Frontier reports. Replaced at every refill: a candidate a
107
+ // Lane unblocked on the way is not one the Run was still held up by.
108
+ let blocked: number[] = [];
109
+ // Why this Run stopped, which is also what it reports. Set by whichever of
110
+ // the Release and the Stop came first and never overwritten: a Stop that
111
+ // arrives after a Release asked for what was already happening, and a Release
112
+ // afterwards stopped nothing that was not stopped already. Undefined is a Run
113
+ // still taking Tickets, which is why it doubles as the guard at every refill.
114
+ let runStop: RunStop | undefined;
115
+ // A Frontier the tracker refused to list, kept until the Lanes still busy are
116
+ // back. A Run must not walk away from a Ticket mid-Stage to report that `gh`
117
+ // went down, so the error waits for them and is thrown where a Run with one
118
+ // Lane threw it: out of the Run, with nothing else left running.
119
+ let listing: unknown;
120
+
121
+ // Registered before the sweep, because a Stop that arrives during it is a Run
122
+ // that claims nothing at all: the Lanes are empty, so there is nothing to
123
+ // finish and nothing to report but the request itself.
124
+ stopping.watch(({ at }) => {
125
+ const held = [...busy.keys()].sort((first, second) => first - second);
126
+ pipeline.log?.(stopLine(held));
127
+ runStop ??= { reason: "stopped", at, busy: held };
128
+ });
129
+
130
+ // Taken off the front as Lanes free, so the sweep is a queue rather than a
131
+ // pass of its own: a stranded Ticket and a Frontier Ticket can be in two
132
+ // Lanes at once, and neither waits for the other's kind to run out.
133
+ const stranded = await strandedTickets({
134
+ tracker,
135
+ workspace: pipeline.workspace,
136
+ inProgress: config.labels.inProgress,
137
+ ...(named === undefined ? {} : { only: named }),
138
+ ...(pipeline.log === undefined ? {} : { log: pipeline.log }),
139
+ });
140
+
141
+ /** Whether the Run has a Lane to put a Ticket in right now. */
142
+ function laneFree(): boolean {
143
+ return busy.size < config.lanes;
144
+ }
145
+
146
+ /**
147
+ * Put a Ticket in a Lane, and record what came back when it ends.
148
+ *
149
+ * The line about the Run stopping is logged by the Release that stopped it and
150
+ * by no other. The Ticket's own release is already logged where it happened;
151
+ * this says the Run goes no further, so a transcript shows the Frontier was
152
+ * left alone rather than found empty, and a Release into a Run that an earlier
153
+ * Release or a Stop had stopped already claims to have stopped nothing. It
154
+ * leads with the Ticket's number all the same: a transcript of interleaved
155
+ * Lanes must not lose the line that explains why one Lane was the last to be
156
+ * filled.
157
+ */
158
+ function fillLane(ticket: Taken): void {
159
+ taken.add(ticket.number);
160
+ busy.set(
161
+ ticket.number,
162
+ take(pipeline, ticket).then((outcome) => {
163
+ busy.delete(ticket.number);
164
+ outcomes.push(outcome);
165
+ if (outcome.outcome === "released" && runStop === undefined) {
166
+ runStop = { reason: "rate-limited" };
167
+ pipeline.log?.(`#${outcome.ticket} stopped the Run · rate limit`);
168
+ }
169
+ }),
170
+ );
171
+ }
172
+
173
+ /** Fill every free Lane: the stranded Tickets first, the Frontier second. */
174
+ async function fillLanes(): Promise<void> {
175
+ while (laneFree()) {
176
+ const resumable = stranded.shift();
177
+ if (resumable === undefined) break;
178
+ fillLane(resumable);
179
+ }
180
+ // Asked for only when a Lane is still free, so a Run whose Lanes are full of
181
+ // stranded Tickets spends no call on a Frontier it could not take from.
182
+ if (!laneFree()) return;
183
+
184
+ const candidates = await tracker.listCandidates(config.labels.readyForAgent);
185
+ const selection = selectFrontier(
186
+ named === undefined ? candidates : candidates.filter(({ number }) => named.has(number)),
187
+ );
188
+ blocked = selection.blocked.map((candidate) => candidate.number);
189
+ // Asked again after the listing, because a Lane that came back while it was
190
+ // in flight may have been released, and a Stop may have arrived: the Run
191
+ // fills no Lane after either, and this selection is one it already had no
192
+ // business taking from.
193
+ if (runStop !== undefined) return;
194
+
195
+ for (const candidate of selection.frontier) {
196
+ if (!laneFree()) break;
197
+ if (taken.has(candidate.number)) continue;
198
+ fillLane({
199
+ number: candidate.number,
200
+ title: candidate.title,
201
+ branch: branchName(candidate.number, candidate.title),
202
+ });
203
+ }
204
+ }
205
+
206
+ for (;;) {
207
+ if (runStop === undefined && listing === undefined) {
208
+ try {
209
+ await fillLanes();
210
+ } catch (error) {
211
+ listing = error;
212
+ }
213
+ }
214
+ // Never while a Lane is busy, whatever the Frontier had to offer: that Lane
215
+ // may be about to close the blocker the rest of the Frontier is waiting on.
216
+ if (busy.size === 0) break;
217
+ await Promise.race(busy.values());
218
+ }
219
+
220
+ if (listing !== undefined) throw listing;
221
+ const stop = runStop ?? { reason: "frontier", blocked };
222
+ if (named !== undefined) {
223
+ const stillBlocked = stop.reason === "frontier" ? stop.blocked : [];
224
+ for (const ticket of named) {
225
+ if (taken.has(ticket) || stillBlocked.includes(ticket)) continue;
226
+ const skipped = await neverMet(pipeline, ticket);
227
+ if (skipped !== undefined) outcomes.push(skipped);
228
+ }
229
+ }
230
+ return { outcomes, stop };
231
+ }
232
+
233
+ /**
234
+ * A Ticket a narrowed Run was given and never met, as the row that says why.
235
+ *
236
+ * Neither source offered it, so it is nobody's to take — somebody else holds
237
+ * it, it was never offered or has closed — or it is no issue at all. It is
238
+ * asked about only now, when the Run is over, and passed over in silence: a
239
+ * warning is for a Planning defect, and a Ticket a guard could have refused was
240
+ * on the Frontier, where the guard already had its say.
241
+ *
242
+ * Nothing comes back for one the Run could still have taken, which a Stop or a
243
+ * Release kept it from, or for one the tracker would not answer about: the Run
244
+ * has no reason to give for either, and the last line says why it stopped.
245
+ */
246
+ async function neverMet(pipeline: Pipeline, ticket: number): Promise<Skipped | undefined> {
247
+ let skipped: Skipped | undefined;
248
+ try {
249
+ skipped = await nobodysToTake(pipeline, ticket);
250
+ } catch (error) {
251
+ pipeline.log?.(`#${ticket} was never met, and reading it failed: ${(error as Error).message}`);
252
+ return undefined;
253
+ }
254
+ if (skipped !== undefined) pipeline.log?.(`#${ticket} skipped · ${skipped.reason}`);
255
+ return skipped;
256
+ }
257
+
258
+ /** The row a Ticket passed over earns. */
259
+ type Skipped = Extract<TicketOutcome, { outcome: "skipped" }>;
260
+
261
+ /** `ticket` skipped for why it is nobody's to take, or nothing where it is somebody's. */
262
+ async function nobodysToTake(pipeline: Pipeline, ticket: number): Promise<Skipped | undefined> {
263
+ const { tracker, workspace, config } = pipeline;
264
+ const skipped = (reason: Refusal, title?: string): Skipped => ({
265
+ outcome: "skipped",
266
+ ticket,
267
+ ...(title === undefined ? {} : { title }),
268
+ reason,
269
+ });
270
+
271
+ const kind = await tracker.numberKind(ticket);
272
+ if (kind === "nothing") return skipped("no-issue");
273
+ if (kind === "pull-request") return skipped("pull-request");
274
+
275
+ const issue = await tracker.getIssue(ticket);
276
+ // A closed issue is offered to nobody, whatever labels it kept.
277
+ if (issue.closed) return skipped("not-ready", issue.title);
278
+ // Read as the Run's own guards read it, so a Stranded Ticket the Run never
279
+ // got to is not reported as somebody else's.
280
+ const stranded =
281
+ (await workspace.readState(ticket)) !== undefined &&
282
+ holdsClaim(issue, await tracker.currentUser(), config.labels.inProgress);
283
+ const reason = skipReason(issue, config.labels.readyForAgent, stranded);
284
+ if (reason === undefined || isGuardReason(reason)) return undefined;
285
+ return skipped(reason, issue.title);
286
+ }
287
+
288
+ /**
289
+ * One Ticket, and never an exception.
290
+ *
291
+ * {@link processTicket} hands off everything it can, but its claim and its own
292
+ * hand-off writes are outside that net: a tracker that goes down mid-Ticket
293
+ * would otherwise take the whole Run with it. The Ticket is reported as handed
294
+ * off — which, without the label, is what a human will find on the board.
295
+ */
296
+ async function take(pipeline: Pipeline, ticket: Taken): Promise<TicketOutcome> {
297
+ // Handed to the Ticket rather than read off its outcome, because there is no
298
+ // outcome on this path: a Note already on GitHub has to reach the summary
299
+ // whether or not the Ticket that made it came back.
300
+ const notes: RoutedNote[] = [];
301
+ try {
302
+ return await processTicket(pipeline, ticket.number, notes);
303
+ } catch (error) {
304
+ const failure = (error as Error).message;
305
+ pipeline.log?.(`#${ticket.number} failed outside the hand-off path: ${failure}`);
306
+ return {
307
+ outcome: "handed-off",
308
+ ticket: ticket.number,
309
+ title: ticket.title,
310
+ branch: ticket.branch,
311
+ stage: "setup",
312
+ failure,
313
+ notes,
314
+ };
315
+ }
316
+ }
317
+
318
+ /**
319
+ * One Ticket a Run is about to take, named well enough to report on it when
320
+ * nothing comes back.
321
+ *
322
+ * The branch is carried rather than derived, because the two ways a Run reaches
323
+ * a Ticket know it differently: a candidate off the Frontier has whatever its
324
+ * title derives to, and a stranded Ticket has the branch its State file names —
325
+ * which is where the work actually is, whatever the title says now.
326
+ */
327
+ interface Taken {
328
+ number: number;
329
+ title: string;
330
+ branch: string;
331
+ }
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Whether a Run's Target is the pipeline's own repository.
3
+ *
4
+ * Only there is the checkout a Stage stands in the pipeline itself, with tests
5
+ * and fakes to exercise it through and spellings of its commands that name no
6
+ * installed `ticket-runner` (`prompts.ts`). The pipeline decides this rather
7
+ * than leaving a Stage to judge it from the files around it, and it decides it
8
+ * once per Run, before the first Ticket.
9
+ */
10
+
11
+ import type { Tracker } from "./ports/tracker.js";
12
+
13
+ /**
14
+ * True where the Target's GitHub repository is `pipeline`, the pipeline's own
15
+ * as its package names it, and false wherever either side cannot be read.
16
+ *
17
+ * GitHub reads `owner/name` without regard to case, so this does too. Nothing
18
+ * here may stop a Run: a tracker that fails is a Target that is not the
19
+ * pipeline's own, which gives its Stages the guidance that holds anywhere.
20
+ */
21
+ export async function isPipelineRepository(
22
+ tracker: Tracker,
23
+ pipeline: string | undefined,
24
+ ): Promise<boolean> {
25
+ if (pipeline === undefined) return false;
26
+ let target: string | undefined;
27
+ try {
28
+ target = await tracker.repository();
29
+ } catch {
30
+ return false;
31
+ }
32
+ return target !== undefined && target.toLowerCase() === pipeline.toLowerCase();
33
+ }
@@ -0,0 +1,32 @@
1
+ /**
2
+ * The Stage boundary: a Stage session may not run the pipeline that started it.
3
+ *
4
+ * Every Stage the AgentRunner starts carries the Stage mark, an environment
5
+ * variable the child inherits, and the CLI refuses to do anything while it is
6
+ * present. It is a tripwire against an honest mistake, not a sandbox — a
7
+ * session that unsets the variable still gets through. The prompt guidance in
8
+ * `prompts.ts` is what covers intent.
9
+ */
10
+
11
+ /** The Stage mark: set by the AgentRunner to the name of the Stage it starts. */
12
+ export const STAGE_ENV_VAR = "TICKET_RUNNER_STAGE";
13
+
14
+ /**
15
+ * Why this invocation must not start, when the shell carries the Stage mark.
16
+ * Takes the environment so the refusal can be tested without `process.env`.
17
+ */
18
+ export function nestedRunRefusal(env: Record<string, string | undefined>): string | undefined {
19
+ const mark = env[STAGE_ENV_VAR];
20
+ if (mark === undefined) return undefined;
21
+
22
+ // A blanked mark is still a mark; only an unset variable is a human's shell.
23
+ const stage = mark.trim() === "" ? undefined : mark.trim();
24
+ return [
25
+ `Refusing to start: ${STAGE_ENV_VAR} is set${stage === undefined ? "" : ` to \`${stage}\``},`,
26
+ `so this shell belongs to ${stage === undefined ? "a" : `the ${stage}`} Stage of a Run`,
27
+ "that is already in progress.",
28
+ "A Stage may not run the pipeline: doing so claims a Ticket on the live tracker,",
29
+ "creates a second worktree and starts a nested Run.",
30
+ "Leave the pipeline to the Run that started this shell, and carry on with the Stage's own work.",
31
+ ].join(" ");
32
+ }