ticket-runner 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/LICENSE +21 -0
  2. package/README.ko.md +97 -0
  3. package/README.md +98 -0
  4. package/bin/ticket-runner.js +6 -0
  5. package/docs/templates/operator-skill.md +87 -0
  6. package/package.json +42 -0
  7. package/src/acceptance-criteria.ts +44 -0
  8. package/src/adapters/claude-agent-runner.ts +389 -0
  9. package/src/adapters/exec.ts +169 -0
  10. package/src/adapters/gh-tracker.ts +955 -0
  11. package/src/adapters/git-workspace.ts +951 -0
  12. package/src/adapters/repo-root.ts +20 -0
  13. package/src/adapters/version.ts +118 -0
  14. package/src/base-branch.ts +21 -0
  15. package/src/branch.ts +33 -0
  16. package/src/cli.ts +135 -0
  17. package/src/command-line.ts +190 -0
  18. package/src/config.ts +277 -0
  19. package/src/conventions.ts +118 -0
  20. package/src/criteria.ts +106 -0
  21. package/src/frontier.ts +36 -0
  22. package/src/guards.ts +143 -0
  23. package/src/handoff.ts +82 -0
  24. package/src/host.ts +116 -0
  25. package/src/init.ts +405 -0
  26. package/src/labels.ts +42 -0
  27. package/src/landing.ts +75 -0
  28. package/src/lifecycle.ts +34 -0
  29. package/src/lock.ts +215 -0
  30. package/src/note-schema.ts +58 -0
  31. package/src/notes.ts +433 -0
  32. package/src/operator-skill.ts +24 -0
  33. package/src/orchestrator.ts +1816 -0
  34. package/src/ports/agent-runner.ts +105 -0
  35. package/src/ports/tracker.ts +334 -0
  36. package/src/ports/workspace.ts +422 -0
  37. package/src/progress.ts +231 -0
  38. package/src/prompts.ts +288 -0
  39. package/src/readiness.ts +256 -0
  40. package/src/remove.ts +732 -0
  41. package/src/resume.ts +145 -0
  42. package/src/run-log.ts +85 -0
  43. package/src/run.ts +331 -0
  44. package/src/self-hosting.ts +33 -0
  45. package/src/stage-guard.ts +32 -0
  46. package/src/staleness.ts +101 -0
  47. package/src/start.ts +284 -0
  48. package/src/startup.ts +34 -0
  49. package/src/stop.ts +178 -0
  50. package/src/stranded.ts +136 -0
  51. package/src/templates.ts +596 -0
  52. package/src/title.ts +97 -0
  53. package/src/verdict.ts +88 -0
  54. package/src/version-number.ts +67 -0
  55. package/src/version-pr.ts +103 -0
@@ -0,0 +1,101 @@
1
+ /**
2
+ * What a Run and `init` say when something around them is from another Version,
3
+ * and the one thing neither ever does about it.
4
+ *
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
9
+ * existed would strand a Target on the night its maintainer was asleep, and
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.
12
+ *
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.
16
+ */
17
+
18
+ import { join } from "node:path";
19
+ import { CONVENTIONS_PATH, conventionsMark } from "./conventions.js";
20
+ import type { Tracker } from "./ports/tracker.js";
21
+ import { readTargetFile } from "./readiness.js";
22
+ import { isHigher, tagNumber, versionNumber } from "./version-number.js";
23
+
24
+ export interface StalenessQuestion {
25
+ tracker: Tracker;
26
+ /** The Version this copy is, as the CLI resolved it once and handed it down. */
27
+ version: string;
28
+ /**
29
+ * The pipeline's own repository, as `owner/name`. Undefined where the package
30
+ * names none, which asks nothing of the tracker at all: the lookup has no
31
+ * repository to be about, and a Run is owed silence rather than a guess.
32
+ */
33
+ repository?: string | undefined;
34
+ }
35
+
36
+ /**
37
+ * One line naming the Version that is out and the Version running, and nothing
38
+ * at all where this copy is the latest, is ahead of it, or could not ask.
39
+ *
40
+ * What has been published as a GitHub Release is the question rather than the
41
+ * highest tag, because a tag a workflow has not finished publishing is not a
42
+ * Version anybody can install yet.
43
+ */
44
+ export async function newerVersionLine({
45
+ tracker,
46
+ version,
47
+ repository,
48
+ }: StalenessQuestion): Promise<string | undefined> {
49
+ const own = versionNumber(version);
50
+ if (own === undefined || repository === undefined) return undefined;
51
+
52
+ const latest = await publishedVersionTag(tracker, repository);
53
+ const published = latest === undefined ? undefined : tagNumber(latest);
54
+ if (published === undefined || !isHigher(published, own)) return undefined;
55
+
56
+ return `A newer Version is out: ${published}, and this is ${own} — upgrade with \`npm install -g "github:${repository}#semver:*"\`.`;
57
+ }
58
+
59
+ /**
60
+ * Asking, where asking is possible, and nothing where it is not.
61
+ *
62
+ * The port answers with nothing when it could not reach GitHub, and this
63
+ * catches what it could not answer at all — a `gh` that is not installed, a
64
+ * tracker that threw. Both are the same answer here, because the one thing this
65
+ * may not do is stop a Run.
66
+ */
67
+ async function publishedVersionTag(
68
+ tracker: Tracker,
69
+ repository: string,
70
+ ): Promise<string | undefined> {
71
+ try {
72
+ return await tracker.latestVersionTag(repository);
73
+ } catch {
74
+ return undefined;
75
+ }
76
+ }
77
+
78
+ /**
79
+ * The one warning a Run prints about the conventions document in `repoRoot`,
80
+ * and nothing where the document is this Version's own.
81
+ *
82
+ * Worded for whichever side is behind, because only one of them can be put
83
+ * right from here: a document an older pipeline left is `init`'s to rewrite,
84
+ * and a document a newer one left is the install's to catch up with. A copy
85
+ * carrying no mark at all is not this function's: readiness refuses it before a
86
+ * Run gets this far.
87
+ */
88
+ export function conventionsWarning(repoRoot: string, version: string): string | undefined {
89
+ const own = versionNumber(version);
90
+ if (own === undefined) return undefined;
91
+
92
+ const document = readTargetFile(join(repoRoot, CONVENTIONS_PATH));
93
+ const mark = conventionsMark(document);
94
+ if (mark === undefined || mark === own) return undefined;
95
+
96
+ const subject = `This Target's \`${CONVENTIONS_PATH}\``;
97
+ if (isHigher(mark, own)) {
98
+ return `${subject} was left by ${mark}, and this Run is ${own} — upgrade \`ticket-runner\`.`;
99
+ }
100
+ return `${subject} was left by ${mark}, and this Run is ${own} — run \`ticket-runner init\` here to bring it up to date.`;
101
+ }
package/src/start.ts ADDED
@@ -0,0 +1,284 @@
1
+ import { resolveBaseBranch } from "./base-branch.js";
2
+ import type { Config } from "./config.js";
3
+ import { hostKind } from "./host.js";
4
+ import { Landing } from "./landing.js";
5
+ import { StandingNotes } from "./notes.js";
6
+ import { lockHeldMessage, unreleasedLockMessage } from "./lock.js";
7
+ import type { Pipeline, TicketOutcome } from "./orchestrator.js";
8
+ import type { AgentRunner } from "./ports/agent-runner.js";
9
+ import type { Tracker } from "./ports/tracker.js";
10
+ import type { Workspace } from "./ports/workspace.js";
11
+ import { readinessRefusal } from "./readiness.js";
12
+ import { LOCAL_STATE_DIR, localStateTickets } from "./resume.js";
13
+ import { writeRunVersion } from "./run-log.js";
14
+ import { type RunStop, processRun } from "./run.js";
15
+ import { isPipelineRepository } from "./self-hosting.js";
16
+ import { conventionsWarning, newerVersionLine } from "./staleness.js";
17
+ import { type StopSource, StopSignal, listenForStop } from "./stop.js";
18
+ import { startupMessages } from "./startup.js";
19
+ import { runSummary } from "./templates.js";
20
+
21
+ /**
22
+ * Everything between the arguments and the work: the two refusals a Run can
23
+ * meet before it starts, the Run lock, and the summary it ends with.
24
+ *
25
+ * It lives here rather than in the CLI so that a refusal is provable — a test
26
+ * drives a whole `run` against a temporary Target and a fake Tracker and asserts
27
+ * that neither the lock nor the Frontier was ever reached. The CLI is left with
28
+ * the arguments, the Target's root and the three adapters.
29
+ */
30
+
31
+ /**
32
+ * What this invocation was asked to do, once the arguments are understood.
33
+ *
34
+ * A Run may be told how many Lanes it has, which wins over the Target's config
35
+ * because how many Tickets a Host can carry at once is the Host's business, not
36
+ * the Target's (ADR-0008). It may also be narrowed to the Tickets a human
37
+ * named, ascending and each once; with none it drains the whole Frontier.
38
+ */
39
+ export interface Work {
40
+ command: "run";
41
+ lanes?: number;
42
+ tickets?: number[];
43
+ }
44
+
45
+ export interface StartOptions {
46
+ work: Work;
47
+ repoRoot: string;
48
+ config: Config;
49
+ tracker: Tracker;
50
+ runner: AgentRunner;
51
+ workspace: Workspace;
52
+ runId: string;
53
+ /**
54
+ * The Version this Run is, resolved once in the CLI (ADR-0007). Everything
55
+ * the Run stamps takes it from here, so every stamp says the same thing.
56
+ */
57
+ version: string;
58
+ /**
59
+ * The pipeline's own repository, as `owner/name`, which the newer-Version
60
+ * notice is looked up against; see {@link import("./staleness.js")}.
61
+ */
62
+ repository?: string | undefined;
63
+ /** The command line the Run lock records, for whoever loses it. */
64
+ command: string;
65
+ log?: (line: string) => void;
66
+ /** Warnings and refusals, which the CLI puts on stderr as it always has. */
67
+ error?: (line: string) => void;
68
+ /** Where SIGTERM comes from. The process itself, unless a test is watching. */
69
+ signals?: StopSource;
70
+ }
71
+
72
+ /**
73
+ * Start a Run, and answer with the exit code it earned.
74
+ *
75
+ * Every refusal comes before the lock: a Target `init` has not set up, one
76
+ * holding State files an earlier pipeline left in the checkout, and one with
77
+ * nothing to gate a merge. None is a Run that went wrong, so none should leave
78
+ * a lock behind for the next one to reclaim.
79
+ */
80
+ export async function startRun(given: StartOptions): Promise<number> {
81
+ // The count a Run was told is folded into the config once, here, so
82
+ // nothing downstream has two Lane counts to choose between.
83
+ const { lanes } = given.work;
84
+ const options =
85
+ lanes === undefined ? given : { ...given, config: { ...given.config, lanes } };
86
+ const { repoRoot, config, tracker, workspace } = options;
87
+ const log = options.log ?? ((line: string) => console.log(line));
88
+ const error = options.error ?? ((line: string) => console.error(line));
89
+
90
+ const notReady = await readinessRefusal({ repoRoot, labels: config.labels, tracker });
91
+ if (notReady !== undefined) {
92
+ error(notReady);
93
+ return 2;
94
+ }
95
+
96
+ const leftBehind = localStateTickets(repoRoot);
97
+ if (leftBehind.length > 0) {
98
+ error(localStateMessage(leftBehind));
99
+ return 2;
100
+ }
101
+
102
+ const { refusal, warnings } = startupMessages(config);
103
+ // Which Version the document names is a warning and never a refusal, so it
104
+ // joins the config's own: readiness has already refused a copy naming none,
105
+ // and one naming another Version is nothing a Run is worse for (ADR-0007).
106
+ const stale = conventionsWarning(repoRoot, options.version);
107
+ for (const warning of [...warnings, ...(stale === undefined ? [] : [stale])]) {
108
+ error(`warning: ${warning}`);
109
+ }
110
+ if (refusal !== undefined) {
111
+ error(refusal);
112
+ return 2;
113
+ }
114
+
115
+ // Taken before the first write, so two Runs never both claim a Ticket, and
116
+ // on the Target's remote, so that holds whichever Host each Run is on.
117
+ const claim = {
118
+ pid: process.pid,
119
+ command: options.command,
120
+ runId: options.runId,
121
+ startedAt: new Date().toISOString(),
122
+ };
123
+ const found = await workspace.takeRunLock(claim);
124
+ // A lock whose Run on this Host has gone is taken over: the alternative is a
125
+ // Run ended by Ctrl+C blocking the Target until a human releases a lock they
126
+ // have never heard of. One held from another Host is never abandoned, and
127
+ // waits for that human.
128
+ const lock = found.outcome === "abandoned" ? await workspace.takeOverRunLock(claim) : found;
129
+ if (lock.outcome === "held") {
130
+ error(lockHeldMessage(lock));
131
+ return 2;
132
+ }
133
+
134
+ // Listened for only while the lock is held, because the lock is what names
135
+ // the process a human sends SIGTERM to, and only a Run holding Tickets has
136
+ // anything to finish. Stopped again in the same breath as the lock: a signal
137
+ // handler holds the event loop open, so a Run still listening would print its
138
+ // summary and never exit.
139
+ const stopping = new StopSignal();
140
+ const deafen = listenForStop(stopping, options.signals);
141
+ try {
142
+ return await execute(options, log, stopping);
143
+ } finally {
144
+ // The lock goes first: SIGTERM between the two is a kill again, and a kill
145
+ // that leaves the lock behind costs the next Run a stale holder to reclaim,
146
+ // where one that leaves the Stop unread costs nothing at all.
147
+ try {
148
+ await workspace.releaseRunLock();
149
+ } catch (failure) {
150
+ // Reported, and the Run's own exit code kept: every Ticket it took has
151
+ // already ended, and the lock left behind is the one thing to tell.
152
+ error(unreleasedLockMessage(failure instanceof Error ? failure.message : String(failure)));
153
+ } finally {
154
+ deafen();
155
+ }
156
+ }
157
+ }
158
+
159
+ async function execute(
160
+ options: StartOptions,
161
+ log: (line: string) => void,
162
+ stopping: StopSignal,
163
+ ): Promise<number> {
164
+ const { work, repoRoot, config, tracker, runner, workspace, runId, version } = options;
165
+
166
+ // Before the first Stage, and before the tracker is asked anything: a
167
+ // transcript has to sit beside the pipeline that wrote it, and the Run
168
+ // summary that says the same thing is a terminal these files outlive.
169
+ // Logged and nothing more when it fails — a directory that will not take a
170
+ // one-line file is no reason to take no Ticket at all.
171
+ try {
172
+ writeRunVersion(repoRoot, runId, version);
173
+ } catch (error) {
174
+ log(`could not record the Version beside the transcripts: ${(error as Error).message}`);
175
+ }
176
+
177
+ // Asked once, and said twice: at the top of the log a human watches, and
178
+ // again at the head of the summary they scroll back to hours later.
179
+ const newer = await newerVersionLine({
180
+ tracker,
181
+ version,
182
+ repository: options.repository,
183
+ });
184
+
185
+ // Once per Run, before any Ticket: every branch, rebase, pull request and
186
+ // pull of this Run goes to the branch this answers.
187
+ const baseBranch = await resolveBaseBranch(tracker, config);
188
+
189
+ // Once per Run as well: only a Target that is the pipeline's own repository
190
+ // has a checkout that is the pipeline, and every Stage is told which it is in.
191
+ const selfHosted = await isPipelineRepository(tracker, options.repository);
192
+
193
+ const pipeline: Pipeline = {
194
+ tracker,
195
+ runner,
196
+ workspace,
197
+ config,
198
+ repoRoot,
199
+ runId,
200
+ version,
201
+ host: hostKind(process.env),
202
+ baseBranch,
203
+ // Once per Run as well, and for the same reason: the Tickets of one Run
204
+ // take turns between their rebase and their merge, and a Landing made per
205
+ // Ticket would be a queue of one every time (ADR-0005).
206
+ landing: new Landing(),
207
+ // Once per Run as well: the Notes of every Ticket the night takes land on
208
+ // one issue, and the Run looks it up once however many it writes.
209
+ standingNotes: new StandingNotes(),
210
+ selfHosted,
211
+ log,
212
+ };
213
+
214
+ const startedAt = Date.now();
215
+ log(opening(runId, work, config.lanes));
216
+ if (newer !== undefined) log(newer);
217
+ const summary = (outcomes: TicketOutcome[], stop: RunStop) =>
218
+ runSummary({
219
+ version,
220
+ runId,
221
+ durationMs: Date.now() - startedAt,
222
+ outcomes,
223
+ ...(newer === undefined ? {} : { newer }),
224
+ stop,
225
+ });
226
+
227
+ const { outcomes, stop } = await processRun(pipeline, stopping, work.tickets);
228
+ log(`\n${summary(outcomes, stop)}`);
229
+ return exitCode(outcomes, work.tickets !== undefined);
230
+ }
231
+
232
+ /**
233
+ * Why a Run will not start over State files a pipeline before the state branch
234
+ * left in the checkout, and what the human does about it.
235
+ *
236
+ * Each is a Ticket that pipeline could resume and this one cannot see, since
237
+ * resume state lives on the Target's remote now and nothing migrates it
238
+ * (ADR-0004). A Run that went ahead would take a released one from the top, over
239
+ * the branch it left, and never sweep a stranded one at all.
240
+ */
241
+ function localStateMessage(tickets: number[]): string {
242
+ const named = tickets.map((ticket) => `#${ticket}`).join(", ");
243
+ return (
244
+ `${LOCAL_STATE_DIR} holds State files for ${named}, which this Version no longer reads: ` +
245
+ "a Ticket's resume state lives on the Target's remote now. Finish those Tickets with " +
246
+ `the Version that wrote the files, or hand them to a human, then delete ${LOCAL_STATE_DIR} ` +
247
+ "and run again."
248
+ );
249
+ }
250
+
251
+ /**
252
+ * The line a Run opens with, and the only place the Lane count is said out loud.
253
+ *
254
+ * Everything after it that is about a Ticket starts with that Ticket's number,
255
+ * so a transcript of interleaved Lanes can be read one Ticket at a time; the
256
+ * lines about the Run itself — this one, and the summary — carry no number.
257
+ *
258
+ * A narrowed Run names the Tickets it was given after its Lanes, ascending,
259
+ * which is also the order it takes the ones the Frontier offers in.
260
+ */
261
+ function opening(runId: string, work: Work, lanes: number): string {
262
+ const subject = [
263
+ `${lanes} ${lanes === 1 ? "lane" : "lanes"}`,
264
+ ...(work.tickets === undefined ? [] : [work.tickets.map((ticket) => `#${ticket}`).join(" ")]),
265
+ ];
266
+ return `ticket-runner run ${runId} · ${subject.join(" · ")}`;
267
+ }
268
+
269
+ /**
270
+ * A hand-off is what the exit code reports first, because it is the one outcome
271
+ * that asks a human for something. A released Ticket was taken all the same:
272
+ * the rate limit resets and a later Run resumes it.
273
+ *
274
+ * A narrowed Run that took none of the Tickets it was given — every one
275
+ * skipped, blocked, or a mix — took nothing at all, which is the same nothing a
276
+ * lock or a bad argument reports. A Run that was not narrowed and skipped every
277
+ * candidate still exits 0: draining a Frontier of unusable Tickets is the job,
278
+ * not a failure to do it.
279
+ */
280
+ function exitCode(outcomes: TicketOutcome[], narrowed: boolean): number {
281
+ if (outcomes.some((outcome) => outcome.outcome === "handed-off")) return 1;
282
+ if (narrowed && outcomes.every((outcome) => outcome.outcome === "skipped")) return 2;
283
+ return 0;
284
+ }
package/src/startup.ts ADDED
@@ -0,0 +1,34 @@
1
+ import { CONFIG_FILENAME, type Config } from "./config.js";
2
+
3
+ export interface StartupMessages {
4
+ /** When set, the Run must not start; this explains why. */
5
+ refusal?: string;
6
+ warnings: string[];
7
+ }
8
+
9
+ /**
10
+ * What the human has to be told before a Run starts: a refusal when nothing
11
+ * would gate a merge, and a warning for each gate they turned off on purpose.
12
+ */
13
+ export function startupMessages(config: Config): StartupMessages {
14
+ const warnings: string[] = [];
15
+ if (!config.gates.checks) {
16
+ warnings.push("Checks gate off: nothing deterministic will gate a merge.");
17
+ }
18
+ if (!config.gates.ci) {
19
+ warnings.push("CI gate off: a pull request with no checks will still be merged.");
20
+ }
21
+
22
+ if (config.gates.checks && config.checks.length === 0) {
23
+ return {
24
+ refusal: [
25
+ "No Check commands are configured and none could be inferred from package.json.",
26
+ `Add them to \`checks\` in ${CONFIG_FILENAME}, add \`test\` and \`typecheck\` scripts to package.json,`,
27
+ `or set \`gates.checks\` to false in ${CONFIG_FILENAME} to run without a net.`,
28
+ ].join(" "),
29
+ warnings,
30
+ };
31
+ }
32
+
33
+ return { warnings };
34
+ }
package/src/stop.ts ADDED
@@ -0,0 +1,178 @@
1
+ import { describeHost } from "./host.js";
2
+ import { LOCK_BRANCH } from "./lock.js";
3
+ import type { LockHolder, Workspace } from "./ports/workspace.js";
4
+
5
+ /**
6
+ * A Stop: how a human asks for one, and how a Run comes to hear about it.
7
+ *
8
+ * SIGTERM is the whole of what a Stop is on the wire (ADR-0006): no file beside
9
+ * the Run lock, and no meaning for Ctrl+C. So both ends of it are small enough
10
+ * to live together — `ticket-runner stop` reads the lock and signals the
11
+ * process it names, and the Run listening at the other end turns that signal
12
+ * into something a test can raise without a process to send one to. What the
13
+ * Run then does with it — finish the Tickets its Lanes hold and claim nothing
14
+ * more — is the Run's own business, and lives with the Run.
15
+ */
16
+
17
+ /** A Stop that reached a Run, and when it did. */
18
+ export interface Stop {
19
+ /** ISO-8601, so a summary and the run id above it read in the same clock. */
20
+ at: string;
21
+ }
22
+
23
+ /** Where SIGTERM comes from: the process itself, unless a test is watching. */
24
+ export interface StopSource {
25
+ on(signal: "SIGTERM", listener: () => void): unknown;
26
+ off(signal: "SIGTERM", listener: () => void): unknown;
27
+ }
28
+
29
+ /**
30
+ * The one Stop a Run can be asked for.
31
+ *
32
+ * A Stop cannot be taken back and never arrives twice: a second SIGTERM is
33
+ * ignored rather than escalated to a kill. That is dropped here, once, rather
34
+ * than guarded against at each of the places a Run acts on the first one.
35
+ */
36
+ export class StopSignal {
37
+ private stop: Stop | undefined;
38
+
39
+ /** What the first request has yet to reach. Emptied as it does. */
40
+ private readonly watchers: ((stop: Stop) => void)[] = [];
41
+
42
+ /** Ask the Run to stop. Every request after the first changes nothing. */
43
+ request(at: Date = new Date()): void {
44
+ if (this.stop !== undefined) return;
45
+ this.stop = { at: at.toISOString() };
46
+ for (const watcher of this.watchers.splice(0)) watcher(this.stop);
47
+ }
48
+
49
+ /**
50
+ * Be told when the Stop arrives, or at once when it already has.
51
+ *
52
+ * A watcher rather than something a Run polls, because what a Run has to
53
+ * report about a Stop — the Tickets its Lanes were holding — is true only at
54
+ * the moment it arrived: by the time the Run next looks, those are the Lanes
55
+ * that have come back.
56
+ */
57
+ watch(watcher: (stop: Stop) => void): void {
58
+ if (this.stop !== undefined) {
59
+ watcher(this.stop);
60
+ return;
61
+ }
62
+ this.watchers.push(watcher);
63
+ }
64
+ }
65
+
66
+ /**
67
+ * Hear SIGTERM as a Stop until the returned function is called.
68
+ *
69
+ * Listening at all is the whole of the difference between a Stop and a kill:
70
+ * with a handler on it, SIGTERM no longer ends the process. It is stopped when
71
+ * the Run ends, because a signal handler holds the event loop open — a Run that
72
+ * kept listening would print its summary and never exit.
73
+ */
74
+ export function listenForStop(signal: StopSignal, source: StopSource = process): () => void {
75
+ const stop = (): void => signal.request();
76
+ source.on("SIGTERM", stop);
77
+ return () => {
78
+ source.off("SIGTERM", stop);
79
+ };
80
+ }
81
+
82
+ /**
83
+ * The one line a Run logs when a Stop reaches it.
84
+ *
85
+ * It leads with the Tickets the Lanes hold because they are the only thing
86
+ * about a Stop that is not already known: the request itself came from the
87
+ * human reading the line, and what is left of the transcript is theirs.
88
+ */
89
+ export function stopLine(busy: number[]): string {
90
+ const held = busy.length === 0 ? "nothing" : busy.map((ticket) => `#${ticket}`).join(" ");
91
+ return `${held} left to finish · stopped`;
92
+ }
93
+
94
+ /** What `ticket-runner stop` needs: the Target's lock, and seams for tests. */
95
+ export interface StopRequest {
96
+ /** Where the Run lock is read from, and which Host is asking. */
97
+ workspace: Workspace;
98
+ /** How the Stop is delivered. A real SIGTERM by default. */
99
+ send?: (pid: number) => void;
100
+ log?: (line: string) => void;
101
+ /** Refusals, which the CLI puts on stderr as it always has. */
102
+ error?: (line: string) => void;
103
+ }
104
+
105
+ /**
106
+ * Ask the Run holding this Target's lock to stop, and answer with an exit code.
107
+ *
108
+ * A thin wrapper over the lock, and deliberately nothing more: no config file,
109
+ * no `gh` and no Target readiness, because a human reaching for this has a Run
110
+ * they want to end rather than a Target they want checked. Repeating it is
111
+ * harmless — the second SIGTERM is one the Run ignores (ADR-0006) — so it says
112
+ * the same thing every time rather than reporting a Stop already asked for.
113
+ */
114
+ export async function requestStop({
115
+ workspace,
116
+ send = sendStop,
117
+ log = (line: string) => console.log(line),
118
+ error = (line: string) => console.error(line),
119
+ }: StopRequest): Promise<number> {
120
+ const held = await workspace.runLockHolder();
121
+ if (held === undefined) {
122
+ error(
123
+ `No Run to stop: nothing holds the Run lock on the \`${LOCK_BRANCH}\` branch, or the` +
124
+ " Run on this Host that left it there is gone. A lock like that is the next Run's to" +
125
+ " reclaim, so nothing here removes it.",
126
+ );
127
+ return 2;
128
+ }
129
+
130
+ // A Stop is a signal to a process, and only the Host the process runs on can
131
+ // send one (ADR-0006). A pid read off another Host's lock is a stranger's
132
+ // here, if it is anybody's.
133
+ const { holder, onAnotherHost } = held;
134
+ if (onAnotherHost) {
135
+ error(
136
+ `\`${holder.command}\` (run ${holder.runId}) holds the Run lock from` +
137
+ ` ${describeHost(holder.host)}, started ${holder.startedAt}. Only that Host can send` +
138
+ " it a Stop: `ticket-runner stop` there, or its Operator on a cloud Host. Nothing" +
139
+ " was sent.",
140
+ );
141
+ return 2;
142
+ }
143
+
144
+ try {
145
+ send(holder.pid);
146
+ } catch (failure) {
147
+ // The Run can end between the liveness check and the signal, and one
148
+ // started by another user cannot be signalled from this shell at all.
149
+ error(`Could not ask ${describeHolder(holder)} to stop: ${reason(failure)}`);
150
+ return 2;
151
+ }
152
+
153
+ log(
154
+ `${describeHolder(holder)} will stop once the Tickets it holds are finished. It claims no more.`,
155
+ );
156
+ log(
157
+ "Ctrl+C in that Run's own terminal stops it at once instead, at the cost of killing the" +
158
+ " Stages it is running and leaving their Tickets stranded for the next Run.",
159
+ );
160
+ return 0;
161
+ }
162
+
163
+ /**
164
+ * Which Run, in the three things the lock knows about it: how `stop` names a
165
+ * holder on this Host, and `remove` too.
166
+ */
167
+ export function describeHolder(holder: LockHolder): string {
168
+ return `\`${holder.command}\` (run ${holder.runId}, pid ${holder.pid})`;
169
+ }
170
+
171
+ /** SIGTERM to the process the lock names, which is the whole of a Stop. */
172
+ function sendStop(pid: number): void {
173
+ process.kill(pid, "SIGTERM");
174
+ }
175
+
176
+ function reason(failure: unknown): string {
177
+ return failure instanceof Error ? failure.message : String(failure);
178
+ }