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,951 @@
1
+ import { existsSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
2
+ import { tmpdir } from "node:os";
3
+ import { basename, dirname, join, resolve } from "node:path";
4
+ import { type Host, currentHost, sameHost } from "../host.js";
5
+ import {
6
+ LOCK_BRANCH,
7
+ LOCK_FILE,
8
+ type ProcessCheck,
9
+ checkProcessTable,
10
+ holderStanding,
11
+ lockCommitMessage,
12
+ lockFileContents,
13
+ readLockFile,
14
+ } from "../lock.js";
15
+ import type {
16
+ CheckOutcome,
17
+ HeldLock,
18
+ KeptTranscripts,
19
+ LockClaim,
20
+ LockHolder,
21
+ LockOutcome,
22
+ LockTake,
23
+ WorktreeRef,
24
+ RebaseOutcome,
25
+ RebaseState,
26
+ StateFile,
27
+ TicketState,
28
+ TicketWorktree,
29
+ Workspace,
30
+ WorktreeFromRemote,
31
+ } from "../ports/workspace.js";
32
+ import {
33
+ STATE_BRANCH,
34
+ readStateFile,
35
+ stateFileContents,
36
+ stateFileName,
37
+ stateFileTicket,
38
+ } from "../resume.js";
39
+ import { transcriptFiles } from "../run-log.js";
40
+ import { exec, execOrThrow, throwOnFailure } from "./exec.js";
41
+
42
+ /**
43
+ * The start of a line git only writes when it cannot merge two hunks itself.
44
+ * Anchored, so a marker quoted inside source or prose is not mistaken for one:
45
+ * a real marker is the whole line, label and all.
46
+ */
47
+ const CONFLICT_MARKER = "^(<{7}|>{7}|\\|{7}) ";
48
+
49
+ /** The two directories git keeps a rebase in, depending on which one it used. */
50
+ const REBASE_DIRS = ["rebase-merge", "rebase-apply"];
51
+
52
+ export { STATE_BRANCH };
53
+
54
+ /** The name every Ticket's worktree has under `.worktrees/`. */
55
+ const TICKET_WORKTREE = /^ticket-\d+$/;
56
+
57
+ /**
58
+ * How many times a change to the state branch is tried, read again from the
59
+ * remote each time, before its push failing is an error. Meant for a remote
60
+ * that moved between the read and the push, whose lease then refuses it; a
61
+ * push that failed for any other reason is tried again too, which costs a
62
+ * moment. The Lanes of one Run take turns and only one Run holds a Target, so
63
+ * a second attempt is already the unusual case.
64
+ */
65
+ const STATE_ATTEMPTS = 3;
66
+
67
+ /**
68
+ * How many times taking or releasing the Run lock reads the lock branch again
69
+ * after a push its lease refused. A refused lease is another Run that moved
70
+ * the lock since this one read it, and reading it again is how this one finds
71
+ * out who; a third move in a row is not a race but something to report.
72
+ */
73
+ const LOCK_ATTEMPTS = 3;
74
+
75
+ /** How the Run lock tells who this Host is, and whether a holder here is running. */
76
+ export interface LockOptions {
77
+ /** The Host this Workspace runs on; the one the environment names by default. */
78
+ host?: Host;
79
+ /** Seam for tests; defaults to the real process table and its start times. */
80
+ checkProcess?: (pid: number) => ProcessCheck;
81
+ }
82
+
83
+ /**
84
+ * One change to the state branch: a file written with `contents`, a file
85
+ * written with what is on disk at `from`, or everything at `remove` gone, the
86
+ * file of that name or the directory of it.
87
+ */
88
+ type StateEdit =
89
+ | { name: string; contents: string }
90
+ | { name: string; from: string }
91
+ | { remove: string };
92
+
93
+ /** One entry of the snapshot's tree, as `git ls-tree` names it. */
94
+ interface TreeEntry {
95
+ type: string;
96
+ object: string;
97
+ name: string;
98
+ }
99
+
100
+ /**
101
+ * The git-backed {@link Workspace}: one worktree per Ticket, branched from the
102
+ * main checkout's base branch, so the checkout itself is never touched.
103
+ *
104
+ * Commands that run in the main checkout go one at a time, because the Tickets
105
+ * of a Run do not: adding and removing worktrees, deleting branches and moving
106
+ * the Base branch all take git refs and index locks that git fails on rather
107
+ * than waits for, and a read of a commit range taken while another Ticket is
108
+ * moving the Base branch is a range nobody asked for. Commands inside a
109
+ * worktree are left parallel — that is where a Run spends its time, and no two
110
+ * Tickets share one.
111
+ *
112
+ * One command at a time, not one operation: the two commands an operation such
113
+ * as {@link removeWorktree} is made of can have another Ticket's between them.
114
+ * What each of them needs is a main checkout nobody else is writing to while it
115
+ * runs, which is what this gives; a pair that had to be indivisible would have
116
+ * to say so, and none of them is.
117
+ *
118
+ * The State lives on the Target's remote, on {@link STATE_BRANCH}, so a Run on
119
+ * any Host resumes a Ticket another left (ADR-0004). The branch is one snapshot
120
+ * commit, rewritten whole and force-pushed with a lease on the tip it was built
121
+ * from, and built from objects and a scratch index alone: the main checkout's
122
+ * tree, index and branches are never touched. Each change to it takes a turn of
123
+ * its own, whole — read, rewrite, push — because two Lanes that rewrote the
124
+ * same tip would each push a snapshot missing the other's Ticket.
125
+ *
126
+ * The Run lock lives on the remote too, on {@link LOCK_BRANCH}, where every
127
+ * Host sees it (ADR-0008). Unlike the state branch it keeps its history: each
128
+ * take and release is a commit on the tip it read, pushed with a lease on that
129
+ * tip, so a human reading the branch on GitHub sees who held the Target when.
130
+ */
131
+ export class GitWorkspace implements Workspace {
132
+ /**
133
+ * Main-checkout commands, one at a time. A command that failed is still a
134
+ * command that finished, so the queue carries on rather than rejecting
135
+ * everything behind it.
136
+ */
137
+ private readonly mainCheckout = new Turns();
138
+ /** Changes to the state branch, and reads of it, one whole operation at a time. */
139
+ private readonly stateBranch = new Turns();
140
+ private readonly host: Host;
141
+ private readonly checkProcess: (pid: number) => ProcessCheck;
142
+ /** The holder this Workspace recorded when it took the lock, which is what it releases. */
143
+ private holding: LockHolder | undefined;
144
+
145
+ constructor(
146
+ private readonly repoRoot: string,
147
+ private readonly remote = "origin",
148
+ { host = currentHost(process.env), checkProcess = checkProcessTable }: LockOptions = {},
149
+ ) {
150
+ this.host = host;
151
+ this.checkProcess = checkProcess;
152
+ }
153
+
154
+ async createWorktree({ path, branch }: WorktreeRef, base: string): Promise<void> {
155
+ // From the remote's base branch, not the checkout's: a cloud session's clone
156
+ // can start commits behind it, and nothing else here has pulled it yet. The
157
+ // checkout's own ref is left for the Landing to move. Untracked, so nothing
158
+ // pushed from the worktree can mistake the base branch for its upstream.
159
+ const from = (await this.fetchBranch(base)) ?? base;
160
+ await this.git(["worktree", "add", "--no-track", "-b", branch, path, from]);
161
+ }
162
+
163
+ async removeWorktree({ path, branch }: { path: string; branch?: string }): Promise<void> {
164
+ await this.git(["worktree", "remove", "--force", path]);
165
+ // A worktree directory left behind would block the next Run on this Ticket.
166
+ rmSync(path, { recursive: true, force: true });
167
+ if (branch !== undefined) await this.git(["branch", "-D", branch]);
168
+ }
169
+
170
+ /**
171
+ * The worktrees git lists whose directory is still there, so one a human
172
+ * deleted by hand is left for {@link deleteBranch} to have git forget. Paths
173
+ * are compared resolved, and against the repo root's real path, which is the
174
+ * spelling git lists them in.
175
+ */
176
+ async ticketWorktrees(): Promise<TicketWorktree[]> {
177
+ const { stdout } = await this.git(["worktree", "list", "--porcelain"]);
178
+ const worktrees = resolve(realpathSync(this.repoRoot), ".worktrees");
179
+ const found: TicketWorktree[] = [];
180
+ for (const entry of stdout.split("\n\n")) {
181
+ const lines = entry.split("\n");
182
+ const listed = lines.find((line) => line.startsWith("worktree "))?.slice(9);
183
+ if (listed === undefined) continue;
184
+ const path = resolve(listed);
185
+ if (dirname(path) !== worktrees || !TICKET_WORKTREE.test(basename(path))) continue;
186
+ if (!existsSync(path)) continue;
187
+
188
+ const branch = lines
189
+ .find((line) => line.startsWith("branch refs/heads/"))
190
+ ?.slice("branch refs/heads/".length);
191
+ found.push({
192
+ path,
193
+ ...(branch === undefined ? {} : { branch }),
194
+ uncommitted: (await this.uncommittedPaths(path)).length > 0,
195
+ unpushed: await this.holdsUnpushed(path, branch),
196
+ });
197
+ }
198
+ return found;
199
+ }
200
+
201
+ /**
202
+ * Whether the worktree's tip has commits the remote lacks: measured against
203
+ * its own branch there when the remote has one, which is fetched first, and
204
+ * against every branch the remote has when it does not, so a branch nobody
205
+ * pushed still counts what it shares with the base branch as pushed.
206
+ */
207
+ private async holdsUnpushed(path: string, branch: string | undefined): Promise<boolean> {
208
+ const tip = (await execOrThrow("git", ["rev-parse", "HEAD"], { cwd: path })).stdout.trim();
209
+ const tracking = branch === undefined ? undefined : await this.fetchBranch(branch);
210
+ const { stdout } = await this.git([
211
+ "rev-list",
212
+ "--count",
213
+ tip,
214
+ "--not",
215
+ tracking ?? `--remotes=${this.remote}`,
216
+ ]);
217
+ return Number(stdout.trim()) > 0;
218
+ }
219
+
220
+ async listBranches(prefix: string): Promise<string[]> {
221
+ const { stdout } = await this.git([
222
+ "for-each-ref",
223
+ "--format=%(refname)",
224
+ `refs/heads/${prefix}`.replace(/\/$/, ""),
225
+ ]);
226
+ return branchNames(stdout.split("\n"), prefix);
227
+ }
228
+
229
+ async listRemoteBranches(prefix: string): Promise<string[]> {
230
+ const { stdout } = await this.git([
231
+ "ls-remote",
232
+ "--heads",
233
+ this.remote,
234
+ `refs/heads/${prefix}*`,
235
+ ]);
236
+ return branchNames(
237
+ stdout.split("\n").map((line) => line.split("\t")[1] ?? ""),
238
+ prefix,
239
+ );
240
+ }
241
+
242
+ /**
243
+ * Git is asked to forget a worktree whose directory a human deleted first:
244
+ * it still counts the branch as checked out there, and refuses the delete.
245
+ */
246
+ async deleteBranch(branch: string): Promise<void> {
247
+ await this.git(["worktree", "prune"]);
248
+ await this.git(["branch", "-D", branch]);
249
+ }
250
+
251
+ /**
252
+ * Both halves are asked, because either can go on its own: a human who
253
+ * deleted the directory leaves git listing the worktree until somebody prunes
254
+ * it, and a worktree moved onto another branch is no longer holding the work
255
+ * that was left there.
256
+ */
257
+ async hasWorktree({ path, branch }: WorktreeRef): Promise<boolean> {
258
+ if (!existsSync(path)) return false;
259
+
260
+ const { stdout } = await this.git(["worktree", "list", "--porcelain"]);
261
+ // One paragraph per worktree: its path, then the branch it is on unless it
262
+ // is detached. Paths are compared resolved, because the one git recorded
263
+ // and the one the pipeline composed need not be spelt the same.
264
+ for (const entry of stdout.split("\n\n")) {
265
+ const lines = entry.split("\n");
266
+ const listed = lines.find((line) => line.startsWith("worktree "))?.slice(9);
267
+ if (listed === undefined || resolve(listed) !== resolve(path)) continue;
268
+ return lines.includes(`branch refs/heads/${branch}`);
269
+ }
270
+ return false;
271
+ }
272
+
273
+ /**
274
+ * The remote branch is fetched into its remote-tracking ref, which is also
275
+ * what the lease of every later {@link push} is taken against: a push from
276
+ * here then overwrites only the tip this Host last saw.
277
+ *
278
+ * A rebase a Run was killed in the middle of is aborted first, because it
279
+ * leaves the worktree detached rather than on its branch, and git would
280
+ * then neither list the worktree as the branch's nor let it be checked out
281
+ * anywhere else.
282
+ */
283
+ async worktreeFromRemote({ path, branch }: WorktreeRef): Promise<WorktreeFromRemote> {
284
+ // Only in a directory that is itself a worktree: git run anywhere else
285
+ // under the repo would find the main checkout, and abort a human's rebase.
286
+ if (existsSync(join(path, ".git"))) await this.abortRebase(path);
287
+ const here = await this.hasWorktree({ path, branch });
288
+ const remoteRef = await this.fetchBranch(branch);
289
+ if (remoteRef === undefined) return here ? "kept" : "gone";
290
+
291
+ const localRef = `refs/heads/${branch}`;
292
+ if (here || (await this.hasBranch(branch))) {
293
+ // A rebase this Host made and never pushed rewrote every commit the
294
+ // remote has, so it is told from another Host's work by what the commits
295
+ // change rather than by their ids.
296
+ if (
297
+ (await this.contains(localRef, remoteRef)) ||
298
+ (await this.replays(localRef, remoteRef))
299
+ ) {
300
+ if (!here) await this.addWorktree([path, branch]);
301
+ return here ? "kept" : "made";
302
+ }
303
+ if (!(await this.contains(remoteRef, localRef))) return "parted";
304
+ // Behind the remote and nothing more: every commit here is one the
305
+ // remote already has, so moving up to it loses nothing.
306
+ if (here) {
307
+ await execOrThrow("git", ["merge", "--ff-only", remoteRef], { cwd: path });
308
+ return "kept";
309
+ }
310
+ }
311
+
312
+ // -B, because a branch left behind without its worktree is by now known to
313
+ // hold nothing the remote lacks, and is moved to the remote tip.
314
+ await this.addWorktree(["-B", branch, path, remoteRef]);
315
+ return "made";
316
+ }
317
+
318
+ /**
319
+ * `worktree add`, after git has forgotten any worktree whose directory a
320
+ * human deleted: git refuses to check a branch out where it still believes
321
+ * one is.
322
+ */
323
+ private async addWorktree(args: string[]): Promise<void> {
324
+ await this.git(["worktree", "prune"]);
325
+ await this.git(["worktree", "add", ...args]);
326
+ }
327
+
328
+ /**
329
+ * Fetch `branch` from the remote into its remote-tracking ref and name that
330
+ * ref, or nothing when the remote has no such branch. Forced, because the
331
+ * remote branch is rewritten by every rebase that is pushed.
332
+ */
333
+ private async fetchBranch(branch: string): Promise<string | undefined> {
334
+ const tracking = `refs/remotes/${this.remote}/${branch}`;
335
+ if (!(await this.hasRemoteBranch(branch))) {
336
+ // A tip the remote no longer has would be the lease of the next push,
337
+ // and refuse it: the push is then creating the branch, not replacing it.
338
+ await this.tryGit(["update-ref", "-d", tracking]);
339
+ return undefined;
340
+ }
341
+
342
+ await this.git(["fetch", this.remote, `+refs/heads/${branch}:${tracking}`]);
343
+ return tracking;
344
+ }
345
+
346
+ /** Whether `ref` holds every commit `other` does. */
347
+ private async contains(ref: string, other: string): Promise<boolean> {
348
+ const result = await this.tryGit(["merge-base", "--is-ancestor", other, ref]);
349
+ return result.exitCode === 0;
350
+ }
351
+
352
+ /**
353
+ * Whether `ref` makes every change `other` makes, under other commit ids:
354
+ * `git cherry` marks a commit of `other` with `+` when `ref` has no commit
355
+ * with the same patch.
356
+ */
357
+ private async replays(ref: string, other: string): Promise<boolean> {
358
+ const { stdout } = await this.git(["cherry", ref, other]);
359
+ return !stdout.split("\n").some((line) => line.startsWith("+"));
360
+ }
361
+
362
+ /**
363
+ * A ref lookup, never the output of a failed `worktree add`: the branch is
364
+ * asked about before anything is created, and `refs/heads/` is spelt out so a
365
+ * tag or a remote-tracking ref of the same name is not mistaken for a branch.
366
+ */
367
+ async hasBranch(branch: string): Promise<boolean> {
368
+ const result = await this.tryGit([
369
+ "show-ref",
370
+ "--verify",
371
+ "--quiet",
372
+ `refs/heads/${branch}`,
373
+ ]);
374
+ return result.exitCode === 0;
375
+ }
376
+
377
+ async commitSubjects(branch: string, base: string): Promise<string[]> {
378
+ // --reverse turns git's newest-first log into the order they were written.
379
+ const { stdout } = await this.git([
380
+ "log",
381
+ "--reverse",
382
+ "--format=%s",
383
+ `${base}..${branch}`,
384
+ ]);
385
+ // Only git's trailing newline is dropped: a commit with an empty subject is
386
+ // still a commit, and losing it would shift which one counts as the first.
387
+ const subjects = stdout.split("\n");
388
+ if (subjects.at(-1) === "") subjects.pop();
389
+ return subjects;
390
+ }
391
+
392
+ async coAuthors(branch: string, base: string): Promise<string[]> {
393
+ const { stdout } = await this.git([
394
+ "log",
395
+ "--reverse",
396
+ "--format=%(trailers:key=Co-authored-by,valueonly)",
397
+ `${base}..${branch}`,
398
+ ]);
399
+ const seen = new Set<string>();
400
+ for (const line of stdout.split("\n")) {
401
+ const value = line.trim();
402
+ if (value !== "") seen.add(value);
403
+ }
404
+ return [...seen];
405
+ }
406
+
407
+ /**
408
+ * The kill reaches the shell the command runs in, not whatever it started:
409
+ * a test runner left behind is tolerated, the same trade `exec` already makes
410
+ * when it drains a dead child's pipes on a clock.
411
+ */
412
+ async runCheck(command: string, cwd: string, timeoutMs: number): Promise<CheckOutcome> {
413
+ const result = await exec(command, [], { cwd, shell: true, timeoutMs });
414
+ if (result.exitCode === 0) return { ok: true, output: result.output };
415
+ return { ok: false, output: result.output, timedOut: result.timedOut };
416
+ }
417
+
418
+ /**
419
+ * NUL-separated, so a path git would otherwise quote comes back as it is
420
+ * spelt. Ignored files stay out, which is git's default; a whole untracked
421
+ * directory is named once, as the directory, which is also git's default.
422
+ * The untracked mode is spelt out so a Target's status.showUntrackedFiles
423
+ * cannot hide an uncommitted file.
424
+ */
425
+ async uncommittedPaths(cwd: string): Promise<string[]> {
426
+ const { stdout } = await execOrThrow(
427
+ "git",
428
+ ["status", "--porcelain", "-z", "--untracked-files=normal"],
429
+ { cwd },
430
+ );
431
+ const entries = stdout.split("\0");
432
+ const paths: string[] = [];
433
+ for (let i = 0; i < entries.length; i++) {
434
+ const entry = entries[i] ?? "";
435
+ if (entry === "") continue;
436
+ paths.push(entry.slice(3));
437
+ // A rename or a copy is followed by the path it came from, which no
438
+ // longer holds anything to commit.
439
+ if (/[RC]/.test(entry.slice(0, 2))) i++;
440
+ }
441
+ return paths;
442
+ }
443
+
444
+ async discardChanges(cwd: string): Promise<void> {
445
+ await execOrThrow("git", ["reset", "--hard"], { cwd });
446
+ // No -x: gitignored files such as node_modules are not the agent's scratch.
447
+ await execOrThrow("git", ["clean", "-fd"], { cwd });
448
+ }
449
+
450
+ async rebase(cwd: string, base: string): Promise<RebaseOutcome> {
451
+ const result = await exec("git", ["rebase", base], { cwd });
452
+ if (result.exitCode === 0) return { ok: true };
453
+
454
+ // The rebase is deliberately left where it stopped: the conflict Stage
455
+ // needs the conflicted tree, and the caller owes the worktree an
456
+ // `abortRebase` if it decides not to send one in.
457
+ return { ok: false, conflict: result.output.trim() };
458
+ }
459
+
460
+ /**
461
+ * Every way a worktree can still be short of a finished rebase, gathered into
462
+ * one answer so nothing downstream has to ask git itself.
463
+ *
464
+ * The ancestry check is what catches the resolution nobody asked for: a
465
+ * session that gave up and ran `git rebase --abort` leaves a tree as clean as
466
+ * a finished rebase, on a branch that has never met the commits it conflicts
467
+ * with.
468
+ */
469
+ async rebaseState(cwd: string, base: string): Promise<RebaseState> {
470
+ const reasons: string[] = [];
471
+
472
+ if (await this.rebaseInProgress(cwd)) {
473
+ reasons.push("a rebase is still in progress");
474
+ } else if (!(await this.isRebasedOn(cwd, base))) {
475
+ reasons.push(`the branch is not rebased onto ${base}`);
476
+ } else {
477
+ // Being on top of the base branch is not the same as having been replayed
478
+ // onto it: merging it in would satisfy the ancestry and put a merge commit
479
+ // on a branch whose every commit is about to be listed in a squash message.
480
+ const merges = await this.lines(cwd, ["rev-list", "--merges", `${base}..HEAD`]);
481
+ if (merges.length > 0) {
482
+ reasons.push(`the conflict was merged into the branch, not rebased onto ${base}`);
483
+ }
484
+ }
485
+
486
+ const unmerged = await this.lines(cwd, ["diff", "--name-only", "--diff-filter=U"]);
487
+ if (unmerged.length > 0) reasons.push(`unmerged paths: ${unmerged.join(", ")}`);
488
+
489
+ // --untracked, because a marker in a file nobody staged is still a marker
490
+ // in the tree; ignored files stay out, so node_modules is not searched.
491
+ // -I: a binary file that happens to hold those bytes is not a conflict.
492
+ const marked = await this.lines(cwd, [
493
+ "grep",
494
+ "--files-with-matches",
495
+ "--untracked",
496
+ "-I",
497
+ "-E",
498
+ CONFLICT_MARKER,
499
+ ]);
500
+ if (marked.length > 0) reasons.push(`conflict markers left in: ${marked.join(", ")}`);
501
+
502
+ return reasons.length === 0
503
+ ? { resolved: true }
504
+ : { resolved: false, unresolved: reasons.join("\n") };
505
+ }
506
+
507
+ async abortRebase(cwd: string): Promise<void> {
508
+ // Non-zero only when there was no rebase to abort, which is the outcome
509
+ // this asks for anyway.
510
+ await exec("git", ["rebase", "--abort"], { cwd });
511
+ }
512
+
513
+ private async rebaseInProgress(cwd: string): Promise<boolean> {
514
+ const paths = await this.lines(cwd, [
515
+ "rev-parse",
516
+ ...REBASE_DIRS.flatMap((dir) => ["--git-path", dir]),
517
+ ]);
518
+ // --git-path answers relative to the worktree it was asked in.
519
+ return paths.some((path) => existsSync(resolve(cwd, path)));
520
+ }
521
+
522
+ private async isRebasedOn(cwd: string, base: string): Promise<boolean> {
523
+ const result = await exec("git", ["merge-base", "--is-ancestor", base, "HEAD"], {
524
+ cwd,
525
+ });
526
+ return result.exitCode === 0;
527
+ }
528
+
529
+ /** A git command whose output is one path per line, and none when it finds none. */
530
+ private async lines(cwd: string, args: string[]): Promise<string[]> {
531
+ const { stdout } = await exec("git", args, { cwd });
532
+ return stdout
533
+ .split("\n")
534
+ .map((line) => line.trim())
535
+ .filter((line) => line !== "");
536
+ }
537
+
538
+ async push(cwd: string, branch: string): Promise<void> {
539
+ // The rebase rewrote the branch, so an earlier push has to be overwritten.
540
+ await execOrThrow(
541
+ "git",
542
+ ["push", "--force-with-lease", "--set-upstream", this.remote, branch],
543
+ { cwd },
544
+ );
545
+ }
546
+
547
+ async hasRemoteBranch(branch: string): Promise<boolean> {
548
+ const { stdout } = await this.git([
549
+ "ls-remote",
550
+ "--heads",
551
+ this.remote,
552
+ `refs/heads/${branch}`,
553
+ ]);
554
+ return stdout.trim() !== "";
555
+ }
556
+
557
+ async deleteRemoteBranch(branch: string): Promise<void> {
558
+ // Asked before anything is sent: a repository that deletes a merged branch
559
+ // has usually done it by now, and a cloud Host, which may delete nothing,
560
+ // would be refused whether the branch were there or not (ADR-0008).
561
+ if (!(await this.hasRemoteBranch(branch))) return;
562
+ const args = ["push", this.remote, "--delete", branch];
563
+ const result = await this.tryGit(args);
564
+ // Asked again after a refusal, because GitHub may have got there between
565
+ // the two: the branch is gone either way, which is all this step is for.
566
+ if (result.exitCode !== 0 && !(await this.hasRemoteBranch(branch))) return;
567
+ throwOnFailure("git", args, result);
568
+ }
569
+
570
+ async pullBase(base: string): Promise<void> {
571
+ const { stdout } = await this.git(["rev-parse", "--abbrev-ref", "HEAD"]);
572
+ if (stdout.trim() === base) {
573
+ await this.git(["pull", "--ff-only", this.remote, base]);
574
+ return;
575
+ }
576
+ // The base branch is not checked out here, so move the ref without
577
+ // touching the tree.
578
+ await this.git(["fetch", this.remote, `${base}:${base}`]);
579
+ }
580
+
581
+ async readState(ticket: number): Promise<TicketState | undefined> {
582
+ return this.stateBranch.take(async () => {
583
+ const tracking = await this.fetchBranch(STATE_BRANCH);
584
+ if (tracking === undefined) return undefined;
585
+ const read = await this.tryGit([
586
+ "cat-file",
587
+ "blob",
588
+ `${tracking}:${stateFileName(ticket)}`,
589
+ ]);
590
+ if (read.exitCode !== 0) return undefined;
591
+ const file = readStateFile(read.stdout, ticket);
592
+ return file.readable ? file.state : undefined;
593
+ });
594
+ }
595
+
596
+ async readAllStates(): Promise<StateFile[]> {
597
+ return this.stateBranch.take(async () => {
598
+ const tracking = await this.fetchBranch(STATE_BRANCH);
599
+ if (tracking === undefined) return [];
600
+ const files = (await this.snapshot(tracking)).flatMap((entry) => {
601
+ const ticket = stateFileTicket(entry.name);
602
+ return entry.type === "blob" && ticket !== undefined ? [{ ticket, entry }] : [];
603
+ });
604
+ files.sort((a, b) => a.ticket - b.ticket);
605
+ const read: StateFile[] = [];
606
+ for (const { ticket, entry } of files) {
607
+ const { stdout } = await this.git(["cat-file", "blob", entry.object]);
608
+ read.push(readStateFile(stdout, ticket));
609
+ }
610
+ return read;
611
+ });
612
+ }
613
+
614
+ async writeState(state: TicketState): Promise<void> {
615
+ await this.changeState(`Record #${state.ticket} at ${state.state}`, [
616
+ { name: stateFileName(state.ticket), contents: stateFileContents(state) },
617
+ ]);
618
+ }
619
+
620
+ async removeState(ticket: number): Promise<void> {
621
+ await this.changeState(`Forget #${ticket}`, [
622
+ { remove: stateFileName(ticket) },
623
+ { remove: transcriptsDir(ticket) },
624
+ ]);
625
+ }
626
+
627
+ /**
628
+ * Each file goes up under `ticket-<n>/<runId>/`, beside the Ticket's State
629
+ * file, as the Run's own directory lays it out; a Ticket handed off by more
630
+ * than one Run keeps each Run's apart, and {@link removeState} takes them
631
+ * all.
632
+ */
633
+ async keepTranscripts(ticket: number, runId: string): Promise<KeptTranscripts | undefined> {
634
+ const files = transcriptFiles(this.repoRoot, runId, ticket);
635
+ if (files.length === 0) return undefined;
636
+
637
+ const directory = `${transcriptsDir(ticket)}/${runId}/`;
638
+ await this.changeState(
639
+ `Keep #${ticket}'s transcripts from ${runId}`,
640
+ files.map((file) => ({ name: `${directory}${file.name}`, from: file.path })),
641
+ );
642
+ return { branch: STATE_BRANCH, path: directory };
643
+ }
644
+
645
+ /**
646
+ * Rewrite the state branch as one new snapshot commit, the same as the tip
647
+ * but for `edits`, and push it over the tip it was built from. Edits that
648
+ * change nothing push nothing, so removing what the tip does not have never
649
+ * creates the branch.
650
+ *
651
+ * No parent, because nothing reads the branch's history and a branch that
652
+ * grew with every Stage would grow the Target with it. The lease is on the
653
+ * tip read, or on no branch at all where there was none, so a snapshot that
654
+ * another writer moved on since is never overwritten: it is read again and
655
+ * the edits made over it.
656
+ */
657
+ private async changeState(message: string, edits: StateEdit[]): Promise<void> {
658
+ await this.stateBranch.take(async () => {
659
+ for (let attempt = 1; ; attempt++) {
660
+ const tracking = await this.fetchBranch(STATE_BRANCH);
661
+ const tip =
662
+ tracking === undefined
663
+ ? undefined
664
+ : (await this.git(["rev-parse", tracking])).stdout.trim();
665
+ if (tip === undefined && edits.every((edit) => "remove" in edit)) return;
666
+
667
+ const tree = await this.editTree(tip, edits);
668
+ const unchanged =
669
+ tip !== undefined &&
670
+ tree === (await this.git(["rev-parse", `${tip}^{tree}`])).stdout.trim();
671
+ if (unchanged) return;
672
+ // Unsigned, like the push is unhooked: a signing key that asks for a
673
+ // passphrase would otherwise stop every write of an unattended Run.
674
+ const { stdout } = await this.git([
675
+ "commit-tree",
676
+ "--no-gpg-sign",
677
+ tree,
678
+ "-m",
679
+ message,
680
+ ]);
681
+ const args = [
682
+ "push",
683
+ // The state branch holds no code, so a Target's pre-push hooks have
684
+ // nothing to check on it.
685
+ "--no-verify",
686
+ `--force-with-lease=refs/heads/${STATE_BRANCH}:${tip ?? ""}`,
687
+ this.remote,
688
+ `${stdout.trim()}:refs/heads/${STATE_BRANCH}`,
689
+ ];
690
+ const pushed = await this.tryGit(args);
691
+ if (pushed.exitCode === 0) return;
692
+ if (attempt === STATE_ATTEMPTS) throwOnFailure("git", args, pushed);
693
+ }
694
+ });
695
+ }
696
+
697
+ /** The entries at the top of the snapshot `tip` is, files and directories alike. */
698
+ private async snapshot(tip: string): Promise<TreeEntry[]> {
699
+ const { stdout } = await this.git(["ls-tree", "-z", tip]);
700
+ return stdout
701
+ .split("\0")
702
+ .filter((line) => line !== "")
703
+ .map((line) => {
704
+ // `<mode> <type> <object>\t<name>`, the name spelt as it is under -z.
705
+ const tab = line.indexOf("\t");
706
+ const [, type = "", object = ""] = line.slice(0, tab).split(" ");
707
+ return { type, object, name: line.slice(tab + 1) };
708
+ });
709
+ }
710
+
711
+ /**
712
+ * The tree `tip` has with `edits` made to it, built in a scratch index so the
713
+ * main checkout's own index is never the one written. Contents go through a
714
+ * scratch file on their way to a blob, because `exec` gives a child no stdin
715
+ * to read them from.
716
+ */
717
+ private async editTree(tip: string | undefined, edits: StateEdit[]): Promise<string> {
718
+ return this.withScratch(async (scratch) => {
719
+ const env = { GIT_INDEX_FILE: join(scratch, "index") };
720
+ await this.git(["read-tree", ...(tip === undefined ? ["--empty"] : [tip])], env);
721
+ for (const [index, edit] of edits.entries()) {
722
+ if ("remove" in edit) {
723
+ // Every file under a directory's name, or the one file of that name:
724
+ // an index holds files alone, so a directory goes a file at a time.
725
+ const { stdout } = await this.git(["ls-files", "-z", "--", edit.remove], env);
726
+ const paths = stdout.split("\0").filter((path) => path !== "");
727
+ if (paths.length > 0) {
728
+ await this.git(["update-index", "--force-remove", "--", ...paths], env);
729
+ }
730
+ continue;
731
+ }
732
+
733
+ let from: string;
734
+ if ("from" in edit) {
735
+ from = edit.from;
736
+ } else {
737
+ from = join(scratch, `blob-${index}`);
738
+ writeFileSync(from, edit.contents);
739
+ }
740
+ // --no-filters: the bytes written are the bytes kept, whatever the
741
+ // checkout's attributes would make of a JSON file.
742
+ const blob = (
743
+ await this.git(["hash-object", "-w", "--no-filters", "--", from])
744
+ ).stdout.trim();
745
+ await this.git(
746
+ ["update-index", "--add", "--cacheinfo", `100644,${blob},${edit.name}`],
747
+ env,
748
+ );
749
+ }
750
+ const { stdout } = await this.git(["write-tree"], env);
751
+ return stdout.trim();
752
+ });
753
+ }
754
+
755
+ private async withScratch<T>(use: (scratch: string) => Promise<T>): Promise<T> {
756
+ const scratch = mkdtempSync(join(tmpdir(), "ticket-runner-state-"));
757
+ try {
758
+ return await use(scratch);
759
+ } finally {
760
+ rmSync(scratch, { recursive: true, force: true });
761
+ }
762
+ }
763
+
764
+ async takeRunLock(claim: LockClaim): Promise<LockTake> {
765
+ return this.acquireLock(claim, false);
766
+ }
767
+
768
+ async takeOverRunLock(claim: LockClaim): Promise<LockOutcome> {
769
+ return this.acquireLock(claim, true);
770
+ }
771
+
772
+ async runLockHolder(): Promise<HeldLock | undefined> {
773
+ const holder = (await this.readLock())?.holder;
774
+ if (holder === undefined) return undefined;
775
+ const standing = holderStanding(holder, this.host, this.checkProcess);
776
+ if (standing === "abandoned") return undefined;
777
+ return { holder, onAnotherHost: standing === "elsewhere" };
778
+ }
779
+
780
+ /**
781
+ * A "free" commit on the tip, pushed only while that tip is still this
782
+ * Workspace's own "held" one: a lock a human released and another Run took
783
+ * since is that Run's.
784
+ */
785
+ async releaseRunLock(): Promise<void> {
786
+ const mine = this.holding;
787
+ if (mine === undefined) return;
788
+ for (let attempt = 1; ; attempt++) {
789
+ const read = await this.readLock();
790
+ if (read?.holder === undefined || !sameHolder(read.holder, mine)) break;
791
+ const push = await this.pushLock(read.tip, undefined);
792
+ if (push.result.exitCode === 0) break;
793
+ if (attempt === LOCK_ATTEMPTS) throwOnFailure("git", push.args, push.result);
794
+ }
795
+ this.holding = undefined;
796
+ }
797
+
798
+ /**
799
+ * Take the lock from the tip as it is read, which is free, or held by a Run
800
+ * this Host can see has gone when `overAbandoned` says so. Its "held" commit
801
+ * goes on that tip with a lease on it, so a Run that read the same tip and
802
+ * pushed first leaves this one's push refused; the tip is then read again,
803
+ * and names who has the lock now.
804
+ */
805
+ private async acquireLock(claim: LockClaim, overAbandoned: true): Promise<LockOutcome>;
806
+ private async acquireLock(claim: LockClaim, overAbandoned: false): Promise<LockTake>;
807
+ private async acquireLock(claim: LockClaim, overAbandoned: boolean): Promise<LockTake> {
808
+ for (let attempt = 1; ; attempt++) {
809
+ const { tip, holder } = (await this.readLock()) ?? (await this.createLock());
810
+ if (holder !== undefined) {
811
+ const standing = holderStanding(holder, this.host, this.checkProcess);
812
+ if (standing !== "abandoned") {
813
+ return { outcome: "held", holder, onAnotherHost: standing === "elsewhere" };
814
+ }
815
+ if (!overAbandoned) return { outcome: "abandoned", holder };
816
+ }
817
+
818
+ const recorded = this.holderFor(claim);
819
+ const push = await this.pushLock(tip, recorded);
820
+ if (push.result.exitCode === 0) {
821
+ this.holding = recorded;
822
+ return { outcome: "taken" };
823
+ }
824
+ if (attempt === LOCK_ATTEMPTS) throwOnFailure("git", push.args, push.result);
825
+ }
826
+ }
827
+
828
+ /**
829
+ * What this Run records as the holder. The process's own start time is read
830
+ * here rather than taken from the caller, which a recycled pid could
831
+ * impersonate as easily as it impersonates the pid itself.
832
+ */
833
+ private holderFor(claim: LockClaim): LockHolder {
834
+ const own = this.checkProcess(claim.pid);
835
+ return {
836
+ host: this.host,
837
+ ...claim,
838
+ ...(own.alive && own.startedAt !== undefined ? { processStartedAt: own.startedAt } : {}),
839
+ };
840
+ }
841
+
842
+ /** The lock branch's tip, and who it says holds the lock; nothing when there is no branch. */
843
+ private async readLock(): Promise<{ tip: string; holder: LockHolder | undefined } | undefined> {
844
+ const tracking = await this.fetchBranch(LOCK_BRANCH);
845
+ if (tracking === undefined) return undefined;
846
+ const tip = (await this.git(["rev-parse", tracking])).stdout.trim();
847
+ const file = await this.tryGit(["cat-file", "blob", `${tip}:${LOCK_FILE}`]);
848
+ return { tip, holder: file.exitCode === 0 ? readLockFile(file.stdout) : undefined };
849
+ }
850
+
851
+ /**
852
+ * Create the lock branch free, by the same lease a take is pushed with,
853
+ * expecting no branch at all: of two Runs that both found it missing, the
854
+ * second's push is refused, and it reads the first's.
855
+ */
856
+ private async createLock(): Promise<{ tip: string; holder: LockHolder | undefined }> {
857
+ const push = await this.pushLock(undefined, undefined);
858
+ const read = await this.readLock();
859
+ if (read === undefined) throwOnFailure("git", push.args, push.result);
860
+ // A remote that took the push and then shows no branch is not one to argue with.
861
+ if (read === undefined) throw new Error(`${this.remote} has no ${LOCK_BRANCH} branch`);
862
+ return read;
863
+ }
864
+
865
+ /**
866
+ * Push a commit saying `holder` holds the lock, or that nobody does, on top
867
+ * of `tip`, with a lease on `tip` or on no branch at all. The rest of the
868
+ * tip's tree is kept: a README a human put there is theirs.
869
+ *
870
+ * The push's own result, because a refused lease is an answer here: somebody
871
+ * moved the lock.
872
+ */
873
+ private async pushLock(tip: string | undefined, holder: LockHolder | undefined) {
874
+ const tree = await this.editTree(tip, [
875
+ { name: LOCK_FILE, contents: lockFileContents(holder) },
876
+ ]);
877
+ const { stdout } = await this.git([
878
+ "commit-tree",
879
+ "--no-gpg-sign",
880
+ tree,
881
+ ...(tip === undefined ? [] : ["-p", tip]),
882
+ "-m",
883
+ lockCommitMessage(holder),
884
+ ]);
885
+ const args = [
886
+ "push",
887
+ "--no-verify",
888
+ `--force-with-lease=refs/heads/${LOCK_BRANCH}:${tip ?? ""}`,
889
+ this.remote,
890
+ `${stdout.trim()}:refs/heads/${LOCK_BRANCH}`,
891
+ ];
892
+ return { args, result: await this.tryGit(args) };
893
+ }
894
+
895
+ /**
896
+ * A git command in the main checkout, waiting its turn. Every command this
897
+ * class runs there goes through here or through {@link tryGit}, so a new one
898
+ * is serialized by being written the way the others are.
899
+ */
900
+ private git(args: string[], extraEnv?: Record<string, string>) {
901
+ return this.mainCheckout.take(() =>
902
+ execOrThrow("git", args, { cwd: this.repoRoot, ...(extraEnv && { extraEnv }) }),
903
+ );
904
+ }
905
+
906
+ /** The same, for a command whose failure is an answer rather than an error. */
907
+ private tryGit(args: string[]) {
908
+ return this.mainCheckout.take(() => exec("git", args, { cwd: this.repoRoot }));
909
+ }
910
+ }
911
+
912
+ /**
913
+ * The branch names among full ref names, those under `prefix` alone: a pattern
914
+ * git matched on a path boundary can still name a ref the caller did not mean.
915
+ */
916
+ function branchNames(refs: string[], prefix: string): string[] {
917
+ return refs
918
+ .map((ref) => ref.trim())
919
+ .filter((ref) => ref.startsWith(`refs/heads/${prefix}`))
920
+ .map((ref) => ref.slice("refs/heads/".length));
921
+ }
922
+
923
+ /**
924
+ * The directory of the state branch a handed-off Ticket's transcripts are kept
925
+ * in, named like its State file without the extension, so the two sort together.
926
+ */
927
+ function transcriptsDir(ticket: number): string {
928
+ return `ticket-${ticket}`;
929
+ }
930
+
931
+ /** Whether two holders are the same Run on the same Host. */
932
+ function sameHolder(a: LockHolder, b: LockHolder): boolean {
933
+ return a.runId === b.runId && a.pid === b.pid && sameHost(a.host, b.host);
934
+ }
935
+
936
+ /**
937
+ * Work that takes turns: each piece waits for the last one queued to settle,
938
+ * either way, before it starts.
939
+ */
940
+ class Turns {
941
+ private last: Promise<unknown> = Promise.resolve();
942
+
943
+ take<T>(work: () => Promise<T>): Promise<T> {
944
+ const started = this.last.then(work, work);
945
+ this.last = started.then(
946
+ () => undefined,
947
+ () => undefined,
948
+ );
949
+ return started;
950
+ }
951
+ }