ticket-runner 0.6.1 → 0.6.3

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.
@@ -1,4 +1,5 @@
1
1
  import { spawn } from "node:child_process";
2
+ import { type Mark, killTree } from "./process-tree.js";
2
3
 
3
4
  export interface Execution {
4
5
  exitCode: number;
@@ -19,8 +20,21 @@ export interface ExecOptions {
19
20
  /** Run through the shell, for user-supplied Check commands. */
20
21
  shell?: boolean;
21
22
  timeoutMs?: number;
23
+ /**
24
+ * How long a command killed at `timeoutMs` has between SIGTERM and SIGKILL.
25
+ * `KILL_GRACE_MS` unless a test needs it shorter.
26
+ */
27
+ killGraceMs?: number;
22
28
  /** Variables merged over the environment the child inherits, not replacing it. */
23
29
  extraEnv?: Record<string, string>;
30
+ /** Variables the child does not inherit, whatever this process carries. */
31
+ unsetEnv?: string[];
32
+ /**
33
+ * A variable set over `extraEnv`, whose value nothing else on the Host
34
+ * carries. A kill at `timeoutMs` also takes every process still carrying it,
35
+ * which reaches what the child started after its parent has exited.
36
+ */
37
+ mark?: Mark;
24
38
  /**
25
39
  * Called with each chunk the child prints on that stream, as it arrives, so
26
40
  * a caller that saves the output has it before the child exits. A sink runs
@@ -45,6 +59,13 @@ export interface ExecOptions {
45
59
  */
46
60
  const DRAIN_MS = 100;
47
61
 
62
+ /**
63
+ * How long a command killed at its time limit, and everything it started, has
64
+ * to end on SIGTERM before SIGKILL. Long enough for a session to write out what
65
+ * it holds, short enough that the Ticket is not held up waiting.
66
+ */
67
+ const KILL_GRACE_MS = 5_000;
68
+
48
69
  /**
49
70
  * How a child process is run. Adapters take one so tests can hand them
50
71
  * recorded output instead of spawning anything.
@@ -62,11 +83,13 @@ export function exec(
62
83
  options: ExecOptions = {},
63
84
  ): Promise<Execution> {
64
85
  return new Promise((resolve, reject) => {
86
+ const { mark } = options;
87
+ const extraEnv =
88
+ mark === undefined ? options.extraEnv : { ...options.extraEnv, [mark.name]: mark.value };
89
+ const env = childEnv(extraEnv, options.unsetEnv);
65
90
  const child = spawn(command, args, {
66
91
  ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
67
- ...(options.extraEnv === undefined
68
- ? {}
69
- : { env: { ...process.env, ...options.extraEnv } }),
92
+ ...(env === undefined ? {} : { env }),
70
93
  shell: options.shell ?? false,
71
94
  stdio: ["ignore", "pipe", "pipe"],
72
95
  });
@@ -78,6 +101,7 @@ export function exec(
78
101
  let settled = false;
79
102
  let limit: NodeJS.Timeout | undefined;
80
103
  let drain: NodeJS.Timeout | undefined;
104
+ let killing: Promise<void> | undefined;
81
105
 
82
106
  /** The child itself is gone. Only a descendant can still hold its pipes. */
83
107
  const hasExited = () =>
@@ -95,13 +119,17 @@ export function exec(
95
119
  const finish = () => {
96
120
  if (settled) return;
97
121
  stopWaiting();
98
- resolve({
122
+ const execution = {
99
123
  exitCode: killed ? 124 : (child.exitCode ?? 1),
100
124
  stdout,
101
125
  stderr,
102
126
  output,
103
127
  timedOut: killed,
104
- });
128
+ };
129
+ // A killed command is reported once what it started is gone too, so the
130
+ // caller never works beside what is left of it.
131
+ if (killing === undefined) resolve(execution);
132
+ else void killing.then(() => resolve(execution));
105
133
  };
106
134
 
107
135
  /** Keep reading for a moment, then stop waiting on the pipes for good. */
@@ -115,7 +143,11 @@ export function exec(
115
143
  // the drain, and its own exit code is the honest one to report.
116
144
  if (hasExited()) return;
117
145
  killed = true;
118
- child.kill("SIGKILL");
146
+ if (child.pid === undefined) child.kill("SIGKILL");
147
+ else {
148
+ const graceMs = options.killGraceMs ?? KILL_GRACE_MS;
149
+ killing = killTree(child.pid, graceMs, mark === undefined ? {} : { mark });
150
+ }
119
151
  }, options.timeoutMs);
120
152
  }
121
153
 
@@ -167,3 +199,17 @@ export function throwOnFailure(
167
199
  }
168
200
  return result;
169
201
  }
202
+
203
+ /**
204
+ * The environment a child is given, or nothing where it inherits this
205
+ * process's own untouched.
206
+ */
207
+ function childEnv(
208
+ extraEnv: Record<string, string> | undefined,
209
+ unsetEnv: string[] | undefined,
210
+ ): NodeJS.ProcessEnv | undefined {
211
+ if (extraEnv === undefined && (unsetEnv === undefined || unsetEnv.length === 0)) return undefined;
212
+ const env: NodeJS.ProcessEnv = { ...process.env, ...extraEnv };
213
+ for (const name of unsetEnv ?? []) delete env[name];
214
+ return env;
215
+ }
@@ -16,6 +16,7 @@ import type {
16
16
  } from "../ports/tracker.js";
17
17
  import { DEFAULT_CI_GRACE_MINUTES } from "../config.js";
18
18
  import { type HostKind, hostKind } from "../host.js";
19
+ import { MAX_TAIL_LINES, logTail } from "../log-tail.js";
19
20
  import { highestVersion } from "../version-number.js";
20
21
  import { type Execution, type RunProcess, exec, throwOnFailure } from "./exec.js";
21
22
 
@@ -587,31 +588,30 @@ export class GhTracker implements Tracker {
587
588
  const logs: string[] = [];
588
589
  for (const { name, job, link } of jobs.slice(0, MAX_LOG_JOBS)) {
589
590
  const log = await this.jobLog(job);
591
+ const tail = log === undefined ? "" : logTail(log);
590
592
  logs.push(
591
- log === undefined
593
+ tail === ""
592
594
  ? `${name}\n(the log was unavailable; the job is at ${link})`
593
- : `${name}\n${tail(log)}`,
595
+ : `${name}\n${tail}`,
594
596
  );
595
597
  }
596
598
  return logs.join("\n\n");
597
599
  }
598
600
 
599
601
  /**
600
- * One Actions job's log through REST, up to the last line the runner marked
601
- * as an error, or nothing when there is no log to be had.
602
+ * One Actions job's whole log through REST, or nothing when there is no log
603
+ * to be had.
602
604
  *
603
605
  * REST gives the whole job where `gh run view --log-failed` gave the failed
604
- * steps, so what the post-job cleanup printed after the failure is cut off:
605
- * otherwise it would be the tail that is kept.
606
+ * steps, so {@link logTail} cuts what the post-job cleanup printed after the
607
+ * failure.
606
608
  */
607
609
  private async jobLog(job: string): Promise<string | undefined> {
608
610
  try {
609
611
  const result = await this.gh(["api", `repos/{owner}/{repo}/actions/jobs/${job}/logs`], {
610
612
  allowFailure: true,
611
613
  });
612
- if (result.exitCode !== 0) return undefined;
613
- const log = throughLastError(result.stdout).trim();
614
- return log === "" ? undefined : log;
614
+ return result.exitCode === 0 ? result.stdout : undefined;
615
615
  } catch {
616
616
  // `gh` itself could not be run. The failure still stands; the log does not.
617
617
  return undefined;
@@ -806,16 +806,10 @@ const ACTIONS_JOB_URL = /\/actions\/runs\/\d+\/job\/(\d+)(?:[?#]|$)/;
806
806
  *
807
807
  * A matrix build fails a leg at a time with the same log each time, and the
808
808
  * prompt and the hand-off comment both have to stay readable, so the excerpt
809
- * is bounded by this times {@link MAX_LOG_LINES} rather than by the build.
809
+ * is bounded by this times {@link MAX_TAIL_LINES} rather than by the build.
810
810
  */
811
811
  const MAX_LOG_JOBS = 3;
812
812
 
813
- /** Lines kept from the tail of one job's log. */
814
- const MAX_LOG_LINES = 40;
815
-
816
- /** Characters kept from the tail of one job's log, for lines long enough to need it. */
817
- const MAX_LOG_CHARS = 4_000;
818
-
819
813
  /**
820
814
  * A comment's id, as the string {@link Tracker.updateComment} takes, or nothing
821
815
  * when REST reported none.
@@ -914,13 +908,6 @@ function linked(url: string | null | undefined): { link?: string } {
914
908
  return url ? { link: url } : {};
915
909
  }
916
910
 
917
- /** Everything up to the last line an Actions runner marked `##[error]`, or all of it. */
918
- function throughLastError(log: string): string {
919
- const lines = log.split("\n");
920
- const last = lines.findLastIndex((line) => line.includes("##[error]"));
921
- return last === -1 ? log : lines.slice(0, last + 1).join("\n");
922
- }
923
-
924
911
  /**
925
912
  * The Actions job id behind a check's link, or nothing when the check does not
926
913
  * report from one. An external app's check has a link of its own shape and no
@@ -930,26 +917,3 @@ function actionsJobId(link: string | undefined): string | undefined {
930
917
  const match = link === undefined ? null : ACTIONS_JOB_URL.exec(link);
931
918
  return match ? (match[1] as string) : undefined;
932
919
  }
933
-
934
- /**
935
- * The end of a log, under a fixed cap, saying what it left out.
936
- *
937
- * The tail is the part worth carrying: a runner prints the assertion or the
938
- * stack that ended the job last, under however much setup noise came first.
939
- */
940
- function tail(log: string): string {
941
- const lines = log.split("\n");
942
- let kept = lines.slice(-MAX_LOG_LINES);
943
- while (kept.length > 1 && kept.join("\n").length > MAX_LOG_CHARS) kept = kept.slice(1);
944
-
945
- const text = kept.join("\n");
946
- const omitted = lines.length - kept.length;
947
-
948
- // A single line longer than the whole cap keeps its own tail: the error is at
949
- // the end of it. Its own start is cut too, which the count alone would not say.
950
- if (text.length > MAX_LOG_CHARS) {
951
- const earlier = omitted > 0 ? `${omitted} earlier lines and the start of this one` : "the start of this line";
952
- return `… (${earlier} omitted)\n${text.slice(-MAX_LOG_CHARS)}`;
953
- }
954
- return omitted > 0 ? `… (${omitted} earlier lines omitted)\n${text}` : text;
955
- }
@@ -54,6 +54,9 @@ export { STATE_BRANCH };
54
54
  /** The name every Ticket's worktree has under `.worktrees/`. */
55
55
  const TICKET_WORKTREE = /^ticket-\d+$/;
56
56
 
57
+ /** The name a worktree at a merge-base has there, which a Check runs in. */
58
+ const BASE_WORKTREE = /^base-[0-9a-f]+$/;
59
+
57
60
  /**
58
61
  * How many times a change to the state branch is tried, read again from the
59
62
  * remote each time, before its push failing is an error. Meant for a remote
@@ -144,7 +147,7 @@ export class GitWorkspace implements Workspace {
144
147
 
145
148
  constructor(
146
149
  private readonly repoRoot: string,
147
- private readonly remote = "origin",
150
+ readonly remote = "origin",
148
151
  { host = currentHost(process.env), checkProcess = checkProcessTable }: LockOptions = {},
149
152
  ) {
150
153
  this.host = host;
@@ -160,6 +163,12 @@ export class GitWorkspace implements Workspace {
160
163
  await this.git(["worktree", "add", "--no-track", "-b", branch, path, from]);
161
164
  }
162
165
 
166
+ async createDetachedWorktree(path: string, commit: string): Promise<void> {
167
+ if (existsSync(path)) await this.tryGit(["worktree", "remove", "--force", path]);
168
+ rmSync(path, { recursive: true, force: true });
169
+ await this.addWorktree(["--detach", path, commit]);
170
+ }
171
+
163
172
  async removeWorktree({ path, branch }: { path: string; branch?: string }): Promise<void> {
164
173
  await this.git(["worktree", "remove", "--force", path]);
165
174
  // A worktree directory left behind would block the next Run on this Ticket.
@@ -182,8 +191,14 @@ export class GitWorkspace implements Workspace {
182
191
  const listed = lines.find((line) => line.startsWith("worktree "))?.slice(9);
183
192
  if (listed === undefined) continue;
184
193
  const path = resolve(listed);
185
- if (dirname(path) !== worktrees || !TICKET_WORKTREE.test(basename(path))) continue;
186
- if (!existsSync(path)) continue;
194
+ if (dirname(path) !== worktrees || !existsSync(path)) continue;
195
+ // A checkout of a commit the remote already has, and whatever a Check
196
+ // printed into it: nothing there is anybody's work.
197
+ if (BASE_WORKTREE.test(basename(path))) {
198
+ found.push({ path, uncommitted: false, unpushed: false });
199
+ continue;
200
+ }
201
+ if (!TICKET_WORKTREE.test(basename(path))) continue;
187
202
 
188
203
  const branch = lines
189
204
  .find((line) => line.startsWith("branch refs/heads/"))
@@ -374,6 +389,12 @@ export class GitWorkspace implements Workspace {
374
389
  return result.exitCode === 0;
375
390
  }
376
391
 
392
+ async mergeBase(cwd: string, base: string): Promise<string> {
393
+ const from = (await this.fetchBranch(base)) ?? base;
394
+ const { stdout } = await execOrThrow("git", ["merge-base", "HEAD", from], { cwd });
395
+ return stdout.trim();
396
+ }
397
+
377
398
  async commitSubjects(branch: string, base: string): Promise<string[]> {
378
399
  // --reverse turns git's newest-first log into the order they were written.
379
400
  const { stdout } = await this.git([
@@ -554,6 +575,15 @@ export class GitWorkspace implements Workspace {
554
575
  return stdout.trim() !== "";
555
576
  }
556
577
 
578
+ async readRemoteFile(branch: string, path: string): Promise<string | undefined> {
579
+ // Fetched first, as a worktree is made from it: the checkout's own
580
+ // remote-tracking ref may predate a push another clone made.
581
+ const tracking = await this.fetchBranch(branch);
582
+ if (tracking === undefined) return undefined;
583
+ const read = await this.tryGit(["cat-file", "blob", `${tracking}:${path}`]);
584
+ return read.exitCode === 0 ? read.stdout : undefined;
585
+ }
586
+
557
587
  async deleteRemoteBranch(branch: string): Promise<void> {
558
588
  // Asked before anything is sent: a repository that deletes a merged branch
559
589
  // has usually done it by now, and a cloud Host, which may delete nothing,
@@ -0,0 +1,227 @@
1
+ import { spawnSync } from "node:child_process";
2
+ import { readFileSync, readdirSync } from "node:fs";
3
+
4
+ /**
5
+ * Killing a command together with everything it started.
6
+ *
7
+ * The command's own process group would not do: a Stage shares the Run's
8
+ * process group (ADR-0006), so that group is the Run itself, and Claude Code
9
+ * starts each Bash tool command in a session of its own, so the test suite a
10
+ * Stage runs is in no group the Stage is in. What is killed instead is the
11
+ * command, every process descended from it, and every process group one of
12
+ * them leads.
13
+ *
14
+ * A process whose parent has exited is no longer descended from anything the
15
+ * command started: the shell that ran `cmd &` in a Bash call exits, and `cmd`
16
+ * lives on under init in a group of its own. A command given a mark carries an
17
+ * environment variable whose value nothing else on the Host shares, and every
18
+ * process it starts inherits it, so the kill also takes every process that
19
+ * still carries that value, whoever its parent is by then. The environment is
20
+ * read from `/proc/<pid>/environ` where there is a `/proc`, as on Linux, and
21
+ * from `ps -wwE` where there is not, as on macOS. A process whose environment
22
+ * cannot be read, or that cleared it, is reached by the walk alone.
23
+ */
24
+
25
+ /** How often a kill looks for what is still alive while the grace runs. */
26
+ const POLL_MS = 50;
27
+
28
+ /** One line of the process table, as far as a kill needs it. */
29
+ interface ProcessRow {
30
+ pid: number;
31
+ ppid: number;
32
+ pgid: number;
33
+ }
34
+
35
+ /** A variable only one command and what it starts carry, at this value. */
36
+ export interface Mark {
37
+ name: string;
38
+ value: string;
39
+ }
40
+
41
+ /**
42
+ * Which processes on the Host carry the mark. Throws, or answers nothing, when
43
+ * no environment can be read; a test hands in its own.
44
+ */
45
+ export type FindMarked = (mark: Mark) => number[];
46
+
47
+ export interface KillOptions {
48
+ /** The mark the command was started with, when it was given one. */
49
+ mark?: Mark;
50
+ findMarked?: FindMarked;
51
+ }
52
+
53
+ /** A command's processes as one kill signals them. */
54
+ interface Tree {
55
+ pids: Set<number>;
56
+ /** Process groups led by one of the pids, never the Run's own. */
57
+ groups: Set<number>;
58
+ }
59
+
60
+ /**
61
+ * SIGTERM to the command and everything it started, then SIGKILL to whatever
62
+ * is still there once `graceMs` is over. Settles when nothing it signalled is
63
+ * left, or once the SIGKILL is sent.
64
+ */
65
+ export async function killTree(
66
+ root: number,
67
+ graceMs: number,
68
+ options: KillOptions = {},
69
+ ): Promise<void> {
70
+ const marked = () => markedPids(options);
71
+ const tree = treeOf([root, ...marked()]);
72
+ signal(tree, "SIGTERM");
73
+
74
+ const deadline = Date.now() + graceMs;
75
+ while (Date.now() < deadline) {
76
+ if (!anyAlive(tree)) {
77
+ // What it signalled is gone, but one of them may have started another
78
+ // as it went: that one still carries the mark.
79
+ const late = treeOf(marked().filter((pid) => alive(pid)));
80
+ if (late.pids.size === 0) return;
81
+ signal(late, "SIGTERM");
82
+ for (const pid of late.pids) tree.pids.add(pid);
83
+ for (const group of late.groups) tree.groups.add(group);
84
+ }
85
+ await new Promise((resolve) => setTimeout(resolve, POLL_MS));
86
+ }
87
+
88
+ // Walked and looked for again from what survived: a process can start
89
+ // another in the grace.
90
+ const stragglers = treeOf([...tree.pids].filter((pid) => alive(pid)).concat(marked()));
91
+ for (const group of tree.groups) stragglers.groups.add(group);
92
+ signal(stragglers, "SIGKILL");
93
+ }
94
+
95
+ /**
96
+ * The roots, their descendants and the groups those lead. Without `ps` to ask,
97
+ * it is the roots alone.
98
+ */
99
+ function treeOf(roots: number[]): Tree {
100
+ const table = processTable();
101
+ if (table === undefined) return { pids: new Set(roots), groups: new Set() };
102
+
103
+ const children = new Map<number, number[]>();
104
+ for (const row of table) {
105
+ children.set(row.ppid, [...(children.get(row.ppid) ?? []), row.pid]);
106
+ }
107
+ const pids = new Set<number>();
108
+ const queue = [...roots];
109
+ for (let pid = queue.shift(); pid !== undefined; pid = queue.shift()) {
110
+ if (pids.has(pid)) continue;
111
+ pids.add(pid);
112
+ queue.push(...(children.get(pid) ?? []));
113
+ }
114
+
115
+ const own = table.find((row) => row.pid === process.pid)?.pgid;
116
+ const groups = new Set(
117
+ table
118
+ .filter((row) => pids.has(row.pid) && row.pgid === row.pid && row.pgid !== own)
119
+ .map((row) => row.pgid),
120
+ );
121
+ return { pids, groups };
122
+ }
123
+
124
+ /**
125
+ * The processes carrying the mark, never this one. None when there is no mark,
126
+ * or when its read failed: the walk still reaches what it reaches.
127
+ */
128
+ function markedPids({ mark, findMarked = processesMarked }: KillOptions): number[] {
129
+ if (mark === undefined) return [];
130
+ try {
131
+ return findMarked(mark).filter((pid) => pid !== process.pid);
132
+ } catch {
133
+ return [];
134
+ }
135
+ }
136
+
137
+ /** The processes carrying the mark, read from `/proc` or else from `ps`. */
138
+ export function processesMarked(mark: Mark): number[] {
139
+ const entries = procEntries();
140
+ if (entries === undefined) return markedInPs(psWithEnvironment(), mark);
141
+
142
+ const wanted = asEntry(mark);
143
+ return entries.flatMap((pid) => {
144
+ try {
145
+ const environ = readFileSync(`/proc/${pid}/environ`, "utf8");
146
+ return environ.split("\0").includes(wanted) ? [pid] : [];
147
+ } catch {
148
+ // Gone since the listing, or another user's: the walk alone reaches it.
149
+ return [];
150
+ }
151
+ });
152
+ }
153
+
154
+ /** The mark as an environment holds it. */
155
+ function asEntry(mark: Mark): string {
156
+ return `${mark.name}=${mark.value}`;
157
+ }
158
+
159
+ /** The pids under `/proc`, or nothing on a Host without one. */
160
+ function procEntries(): number[] | undefined {
161
+ try {
162
+ return readdirSync("/proc").filter((entry) => /^\d+$/.test(entry)).map(Number);
163
+ } catch {
164
+ return undefined;
165
+ }
166
+ }
167
+
168
+ /**
169
+ * Every process with its environment appended to its command, as BSD `ps`
170
+ * prints it. `-ww` because it cuts its lines when stdout is not a terminal,
171
+ * `-A` because a detached process has no terminal to be listed under.
172
+ */
173
+ function psWithEnvironment(): string {
174
+ const listed = spawnSync("ps", ["-A", "-wwE", "-o", "pid=,command="], { encoding: "utf8" });
175
+ if (listed.error !== undefined) throw listed.error;
176
+ if (listed.status !== 0) throw new Error(`ps exited ${listed.status}`);
177
+ return listed.stdout;
178
+ }
179
+
180
+ /**
181
+ * The processes in `ps -wwE -o pid=,command=` output that carry the mark, as
182
+ * one whitespace-separated `NAME=value` word in their line.
183
+ */
184
+ export function markedInPs(output: string, mark: Mark): number[] {
185
+ const wanted = asEntry(mark);
186
+ return output.split("\n").flatMap((line) => {
187
+ const [pid, ...words] = line.trim().split(/\s+/);
188
+ if (pid === undefined || !/^\d+$/.test(pid)) return [];
189
+ return words.includes(wanted) ? [Number(pid)] : [];
190
+ });
191
+ }
192
+
193
+ /** Every process on the Host, or nothing when `ps` cannot be run. */
194
+ function processTable(): ProcessRow[] | undefined {
195
+ const listed = spawnSync("ps", ["-A", "-o", "pid=,ppid=,pgid="], { encoding: "utf8" });
196
+ if (listed.error !== undefined || listed.status !== 0) return undefined;
197
+ return listed.stdout.split("\n").flatMap((line) => {
198
+ const [pid, ppid, pgid] = line.trim().split(/\s+/).map(Number);
199
+ if (pid === undefined || ppid === undefined || pgid === undefined) return [];
200
+ if (!Number.isInteger(pid) || !Number.isInteger(ppid) || !Number.isInteger(pgid)) return [];
201
+ return [{ pid, ppid, pgid }];
202
+ });
203
+ }
204
+
205
+ function signal(tree: Tree, name: NodeJS.Signals): void {
206
+ for (const group of tree.groups) send(-group, name);
207
+ for (const pid of tree.pids) send(pid, name);
208
+ }
209
+
210
+ function anyAlive(tree: Tree): boolean {
211
+ return [...tree.groups].some((group) => alive(-group)) || [...tree.pids].some(alive);
212
+ }
213
+
214
+ /** A negative id is a process group. */
215
+ function alive(id: number): boolean {
216
+ return send(id, 0);
217
+ }
218
+
219
+ /** Whether the signal reached anything; one already gone is not an error here. */
220
+ function send(id: number, name: NodeJS.Signals | 0): boolean {
221
+ try {
222
+ process.kill(id, name);
223
+ return true;
224
+ } catch {
225
+ return false;
226
+ }
227
+ }
package/src/branch.ts CHANGED
@@ -31,3 +31,11 @@ export function branchName(ticket: number, title: string): string {
31
31
  export function worktreePath(repoRoot: string, ticket: number): string {
32
32
  return join(repoRoot, ".worktrees", `ticket-${ticket}`);
33
33
  }
34
+
35
+ /**
36
+ * The gitignored worktree a Check runs in at a merge-base with the Base branch,
37
+ * beside the Tickets' own: named for the commit, shortened as git shortens one.
38
+ */
39
+ export function baseWorktreePath(repoRoot: string, commit: string): string {
40
+ return join(repoRoot, ".worktrees", `base-${commit.slice(0, 12)}`);
41
+ }
@@ -34,6 +34,10 @@ Usage:
34
34
  Options:
35
35
  --lanes <n> With \`run\`: work on up to <n> issues at once,
36
36
  whatever \`lanes\` in ticket-runner.json says.
37
+ --api-key With \`run\`: bill every session to the
38
+ ANTHROPIC_API_KEY this shell exports. Without
39
+ it, sessions run on your Claude login and the
40
+ key is kept from them. Not on a cloud session.
37
41
  -y, --yes With \`remove\`: go ahead without asking.
38
42
  -h, --help Show this message.
39
43
  -v, --version Show which version this pipeline is.`;
@@ -75,6 +79,11 @@ export function readCommandLine(argv: string[]): CommandLine {
75
79
  return refused("`--lanes` is for `run` only, which has a Frontier to share out.");
76
80
  }
77
81
 
82
+ // The same for `--api-key`: only `run` starts the sessions it would bill.
83
+ if (values["api-key"] === true && command !== "run") {
84
+ return refused("`--api-key` is for `run` only, the one command that starts Stages.");
85
+ }
86
+
78
87
  // The same for `--yes` everywhere but `remove`, the one command that asks
79
88
  // before it acts: given to any other, it answers a question nobody asks.
80
89
  if (values.yes === true && command !== "remove") {
@@ -101,6 +110,7 @@ export function readCommandLine(argv: string[]): CommandLine {
101
110
  command: "run",
102
111
  ...(lanes === undefined ? {} : { lanes }),
103
112
  ...(tickets.length === 0 ? {} : { tickets }),
113
+ ...(values["api-key"] === true ? { apiKey: true as const } : {}),
104
114
  },
105
115
  };
106
116
  }
@@ -148,7 +158,13 @@ function refused(complaint: string): CommandLine {
148
158
  /** What `parseArgs` makes of the arguments: the options, and the rest. */
149
159
  interface ParsedArgs {
150
160
  positionals: string[];
151
- values: { help?: boolean; version?: boolean; lanes?: string; yes?: boolean };
161
+ values: {
162
+ help?: boolean;
163
+ version?: boolean;
164
+ lanes?: string;
165
+ "api-key"?: boolean;
166
+ yes?: boolean;
167
+ };
152
168
  }
153
169
 
154
170
  /**
@@ -169,6 +185,7 @@ function parseCommandLine(argv: string[]): ParsedArgs | string {
169
185
  help: { type: "boolean", short: "h" },
170
186
  version: { type: "boolean", short: "v" },
171
187
  lanes: { type: "string" },
188
+ "api-key": { type: "boolean" },
172
189
  yes: { type: "boolean", short: "y" },
173
190
  },
174
191
  allowPositionals: true,
package/src/config.ts CHANGED
@@ -125,10 +125,10 @@ export interface Config {
125
125
 
126
126
  const STAGE_DEFAULTS = {
127
127
  implement: { maxTurns: 300, maxMinutes: 60 },
128
- verify: { maxTurns: 80, maxMinutes: 20 },
128
+ verify: { maxTurns: 130, maxMinutes: 30 },
129
129
  fix: { maxTurns: 150, maxMinutes: 40 },
130
- // Resolving one rebase is narrower work than mending a defect, and the skill
131
- // has the Checks to run before it finishes.
130
+ // Resolving one rebase is narrower work than mending a defect, and the full
131
+ // Checks are the pipeline's to run once it finishes.
132
132
  conflict: { maxTurns: 120, maxMinutes: 30 },
133
133
  } as const;
134
134
 
@@ -104,6 +104,7 @@ A Ticket is one issue the pipeline can implement in a single session. It is refu
104
104
  ## Checks
105
105
 
106
106
  - The Checks of different Tickets may run at the same time, each in its own worktree, because a Run has as many Lanes as \`lanes\` says. A Target whose Checks need a port, a database or anything else they would have to share keeps \`lanes\` at one, or makes them independent of each other.
107
+ - A Check that fails on a Ticket's branch, or CI that fails on its pull request, is graded again at what the branch inherited: the pipeline runs the Check commands in a clean worktree at the branch's merge-base with the Base branch. One that fails there too is the Base branch's, not the Ticket's, so the Ticket is released without spending its Fix budget, the Run claims no more Tickets, and the pipeline posts a Note on the standing Notes issue naming the Check. The next Run rebases the Ticket onto the Base branch before its Checks, so mending the Base branch is what frees it. Nothing is installed in the worktree at the merge-base: its Checks find their dependencies in the main checkout, as a Ticket's worktree does, so Checks that need an install or a build step of their own fail there and release the Ticket, and the Note's output shows it.
107
108
 
108
109
  ## The Operator's skill
109
110
 
@@ -113,6 +114,6 @@ A Ticket is one issue the pipeline can implement in a single session. It is refu
113
114
 
114
115
  Both are \`ticket-runner\`'s own, both are gitignored by \`ticket-runner init\`, and neither is ever committed.
115
116
 
116
- - \`.worktrees/ticket-<n>/\` — one git worktree per claimed Ticket, where its Stages run.
117
+ - \`.worktrees/ticket-<n>/\` — one git worktree per claimed Ticket, where its Stages run. Beside them, \`.worktrees/base-<commit>/\` is a clean worktree at a merge-base with the Base branch, made to run a failing Check there once and removed when it has run.
117
118
  - \`.ticket-runner/\` — the Run's logs and Stage transcripts. The Run lock and the State a Ticket keeps while its branch has work worth resuming are not here but on the Target's remote, so that a Run on any Host sees which Run holds the Target, and carries on from where a killed Run, or a handed-off Ticket relabelled \`ready-for-agent\`, stopped.
118
119
  `;