ticket-runner 0.6.5 → 0.6.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -13,12 +13,14 @@ import type {
13
13
  PullRequestRef,
14
14
  SquashCommit,
15
15
  Tracker,
16
+ Visibility,
16
17
  } from "../ports/tracker.js";
17
18
  import { DEFAULT_CI_GRACE_MINUTES } from "../config.js";
18
19
  import { type HostKind, hostKind } from "../host.js";
19
20
  import { MAX_TAIL_LINES, logTail } from "../log-tail.js";
20
21
  import { highestVersion } from "../version-number.js";
21
- import { type Execution, type RunProcess, exec, throwOnFailure } from "./exec.js";
22
+ import { OutsideFault, firstLine, isGitHubFault } from "../outside-fault.js";
23
+ import { type Execution, type RunProcess, exec, shownCommand, throwOnFailure } from "./exec.js";
22
24
 
23
25
  export interface GhTrackerOptions {
24
26
  run?: RunProcess;
@@ -38,6 +40,44 @@ export interface GhTrackerOptions {
38
40
  host?: HostKind;
39
41
  }
40
42
 
43
+ /**
44
+ * How long each try again of a `gh` call GitHub failed on its own side waits,
45
+ * in turn: doubling, and about a minute in all. A gateway down for seconds
46
+ * costs seconds, and one still down after the last is a fault of GitHub's,
47
+ * which the caller is told as an {@link OutsideFault}.
48
+ */
49
+ export const GITHUB_RETRY_DELAYS_MS: readonly number[] = [2_000, 4_000, 8_000, 16_000, 30_000];
50
+
51
+ /** What a call's stdout has to parse as: one JSON document, or one per line as `--jq` prints them. */
52
+ type Json = "document" | "lines";
53
+
54
+ /** How one `gh` call is run, and what of its failure the caller takes as an answer. */
55
+ interface GhOptions {
56
+ /** A failure comes back rather than throwing, once GitHub's own faults have had their tries. */
57
+ allowFailure?: boolean;
58
+ /** The one failure a caller takes as an answer: it comes back instead of throwing. */
59
+ tolerate?: RegExp;
60
+ /** What stdout must parse as. A response that does not is GitHub's fault, and tried again. */
61
+ json?: Json;
62
+ /**
63
+ * Tried once whatever fails: a write that creates something, which a second
64
+ * try after a failure that had in fact landed would create twice.
65
+ */
66
+ once?: boolean;
67
+ /**
68
+ * Whether what the call does has already happened, as a pull request a 502
69
+ * opened all the same has. Yes ends the tries, and the call answers with the
70
+ * failure it last met.
71
+ *
72
+ * Asked after each wait, before trying again, as a glance: once, and a
73
+ * failure to answer is a no. Asked again when GitHub refuses the call, since
74
+ * a refusal can be GitHub declining to do twice what an earlier try did while
75
+ * the glance between them failed. That ask is `patient`: tried again like any
76
+ * read, and a fault of GitHub's that outlasts the tries is thrown.
77
+ */
78
+ landed?: (patient: boolean) => Promise<boolean>;
79
+ }
80
+
41
81
  /**
42
82
  * One issue as the REST API reports it, in the fields the pipeline reads. The
43
83
  * issue list, the dependency list and a single issue all answer in this shape.
@@ -82,6 +122,8 @@ interface RawPullRequest {
82
122
  /** The GraphQL id, which a workstation's draft and ready mutations take. */
83
123
  node_id: string;
84
124
  draft: boolean;
125
+ /** Whether it has merged, which a merge GitHub failed to answer may have. */
126
+ merged?: boolean;
85
127
  head: { sha: string };
86
128
  /**
87
129
  * Whether GitHub can merge the pull request into its base: `false` when the
@@ -233,6 +275,26 @@ export class GhTracker implements Tracker {
233
275
  }
234
276
  }
235
277
 
278
+ /**
279
+ * Whether the Target is public, read through REST like {@link repository}.
280
+ * Every failure, and a visibility GitHub may add later, is no answer, which
281
+ * the caller counts as public.
282
+ */
283
+ async visibility(): Promise<Visibility | undefined> {
284
+ try {
285
+ const { exitCode, stdout } = await this.gh(
286
+ ["api", "repos/{owner}/{repo}", "--jq", ".visibility"],
287
+ { allowFailure: true },
288
+ );
289
+ if (exitCode !== 0) return undefined;
290
+ const said = stdout.trim();
291
+ if (said === "public") return "public";
292
+ return said === "private" || said === "internal" ? "private" : undefined;
293
+ } catch {
294
+ return undefined;
295
+ }
296
+ }
297
+
236
298
  /**
237
299
  * The tag of the highest version published on `repository` as a Release.
238
300
  *
@@ -249,7 +311,7 @@ export class GhTracker implements Tracker {
249
311
  try {
250
312
  const { exitCode, stdout } = await this.gh(
251
313
  ["api", "--method", "GET", `repos/${repository}/releases`, "-F", "per_page=100"],
252
- { allowFailure: true },
314
+ { allowFailure: true, json: "document" },
253
315
  );
254
316
  if (exitCode !== 0) return undefined;
255
317
  const releases = JSON.parse(stdout) as RawRelease[];
@@ -327,7 +389,9 @@ export class GhTracker implements Tracker {
327
389
  * its blockers, only a count of each.
328
390
  */
329
391
  async getIssue(number: number): Promise<Issue> {
330
- const { stdout } = await this.gh(["api", `repos/{owner}/{repo}/issues/${number}`]);
392
+ const { stdout } = await this.gh(["api", `repos/{owner}/{repo}/issues/${number}`], {
393
+ json: "document",
394
+ });
331
395
  const raw = JSON.parse(stdout) as RawIssue;
332
396
  const comments = await this.list<RawComment>(`repos/{owner}/{repo}/issues/${number}/comments`);
333
397
  const blockers = await this.blockers(number);
@@ -365,11 +429,18 @@ export class GhTracker implements Tracker {
365
429
  * issue, so a missing label is `init`'s to catch, not this call's.
366
430
  */
367
431
  async createIssue(issue: CreateIssue): Promise<IssueRef> {
368
- const { stdout } = await this.rest("POST", "repos/{owner}/{repo}/issues", [
369
- `title=${issue.title}`,
370
- `body=${issue.body}`,
371
- ...issue.labels.map((label) => `labels[]=${label}`),
372
- ]);
432
+ // Once: a 502 can follow an issue GitHub did open, and a second try would
433
+ // open a second.
434
+ const { stdout } = await this.rest(
435
+ "POST",
436
+ "repos/{owner}/{repo}/issues",
437
+ [
438
+ `title=${issue.title}`,
439
+ `body=${issue.body}`,
440
+ ...issue.labels.map((label) => `labels[]=${label}`),
441
+ ],
442
+ { once: true, json: "document" },
443
+ );
373
444
  const created = JSON.parse(stdout) as Partial<RawIssue>;
374
445
  if (typeof created.number !== "number" || typeof created.html_url !== "string") {
375
446
  throw new Error(`could not read an issue number from gh output: ${stdout}`);
@@ -419,6 +490,7 @@ export class GhTracker implements Tracker {
419
490
  "POST",
420
491
  `repos/{owner}/{repo}/issues/${number}/assignees`,
421
492
  [`assignees[]=${user}`],
493
+ { json: "document" },
422
494
  );
423
495
  const assignees = (JSON.parse(stdout) as Partial<RawIssue>).assignees ?? [];
424
496
  if (!assignees.some((assignee) => assignee.login.toLowerCase() === user.toLowerCase())) {
@@ -450,11 +522,18 @@ export class GhTracker implements Tracker {
450
522
  await this.rest("DELETE", path, [], { tolerate: /Label does not exist/ });
451
523
  }
452
524
 
453
- /** REST answers with the new comment, whose id is what it is edited by later. */
525
+ /**
526
+ * REST answers with the new comment, whose id is what it is edited by later.
527
+ * Posted once, as an issue is opened once: a second try after a 502 that had
528
+ * posted it would post it twice, and notify twice.
529
+ */
454
530
  async comment(number: number, body: string): Promise<IssueComment> {
455
- const { stdout } = await this.rest("POST", `repos/{owner}/{repo}/issues/${number}/comments`, [
456
- `body=${body}`,
457
- ]);
531
+ const { stdout } = await this.rest(
532
+ "POST",
533
+ `repos/{owner}/{repo}/issues/${number}/comments`,
534
+ [`body=${body}`],
535
+ { once: true, json: "document" },
536
+ );
458
537
  return { ...withCommentId(JSON.parse(stdout) as RawComment), body };
459
538
  }
460
539
 
@@ -470,14 +549,29 @@ export class GhTracker implements Tracker {
470
549
  /**
471
550
  * Open a pull request through REST, and read its number back out of the
472
551
  * answer rather than off anything printed.
552
+ *
553
+ * Tried again after a fault of GitHub's like any write, but only once no
554
+ * pull request is open on the branch: one the failed try opened all the
555
+ * same is the answer. A try GitHub refuses, as it refuses a second pull
556
+ * request on one branch, is asked about the same way, so one opened while
557
+ * the lookup between tries failed is still the answer.
473
558
  */
474
559
  async createPullRequest(pr: CreatePullRequest): Promise<PullRequestRef> {
560
+ let opened: PullRequestRef | undefined;
475
561
  const { stdout } = await this.rest(
476
562
  "POST",
477
563
  "repos/{owner}/{repo}/pulls",
478
564
  [`base=${pr.base}`, `head=${pr.head}`, `title=${pr.title}`, `body=${pr.body}`],
479
- { typed: [`draft=${pr.draft}`] },
565
+ {
566
+ typed: [`draft=${pr.draft}`],
567
+ json: "document",
568
+ landed: async (patient) => {
569
+ opened = await this.openPullRequestOn(pr.head, patient);
570
+ return opened !== undefined;
571
+ },
572
+ },
480
573
  );
574
+ if (opened !== undefined) return opened;
481
575
  const created = JSON.parse(stdout) as Partial<RawPullRequest>;
482
576
  if (typeof created.number !== "number" || typeof created.html_url !== "string") {
483
577
  throw new Error(`could not read a pull request number from gh output: ${stdout}`);
@@ -493,6 +587,29 @@ export class GhTracker implements Tracker {
493
587
  return pulls.map((pull) => ({ number: pull.number, head: pull.head.ref }));
494
588
  }
495
589
 
590
+ /**
591
+ * The open pull request from `head`, or nothing where there is none.
592
+ *
593
+ * Between the tries of a create it is asked once, and GitHub not saying is
594
+ * nothing too: the next try then asks GitHub to open one, as it would have
595
+ * anyway. After a refusal it is asked `patient`ly, and a GitHub that still
596
+ * will not say is a fault of GitHub's, thrown as any read's is.
597
+ */
598
+ private async openPullRequestOn(head: string, patient: boolean): Promise<PullRequestRef | undefined> {
599
+ try {
600
+ const pulls = await this.list<{ number: number; html_url: string; head: { ref: string } }>(
601
+ "repos/{owner}/{repo}/pulls",
602
+ ["-f", "state=open"],
603
+ patient ? {} : { once: true },
604
+ );
605
+ const pull = pulls.find((candidate) => candidate.head.ref === head);
606
+ return pull === undefined ? undefined : { number: pull.number, url: pull.html_url };
607
+ } catch (error) {
608
+ if (patient) throw error;
609
+ return undefined;
610
+ }
611
+ }
612
+
496
613
  async convertPullRequestToDraft(number: number): Promise<void> {
497
614
  await this.setDraft(number, true);
498
615
  }
@@ -621,18 +738,36 @@ export class GhTracker implements Tracker {
621
738
  /**
622
739
  * Squash-merge through REST, with the subject and body the pipeline composed
623
740
  * as the commit's title and message.
741
+ *
742
+ * Tried again after a fault of GitHub's, but only while the pull request has
743
+ * not merged: a merge the failed try made is done. A try GitHub refuses, as
744
+ * it refuses to merge a pull request already merged, is asked about the same
745
+ * way, so a merge made while the lookup between tries failed is still done.
624
746
  */
625
747
  async squashMerge(number: number, commit: SquashCommit): Promise<void> {
626
- await this.rest("PUT", `repos/{owner}/{repo}/pulls/${number}/merge`, [
627
- "merge_method=squash",
628
- `commit_title=${commit.subject}`,
629
- `commit_message=${commit.body}`,
630
- ]);
748
+ await this.rest(
749
+ "PUT",
750
+ `repos/{owner}/{repo}/pulls/${number}/merge`,
751
+ ["merge_method=squash", `commit_title=${commit.subject}`, `commit_message=${commit.body}`],
752
+ {
753
+ landed: async (patient) => {
754
+ try {
755
+ return (await this.pullRequest(number, patient ? {} : { once: true })).merged === true;
756
+ } catch (error) {
757
+ if (patient) throw error;
758
+ return false;
759
+ }
760
+ },
761
+ },
762
+ );
631
763
  }
632
764
 
633
765
  /** One pull request, read through REST. */
634
- private async pullRequest(number: number): Promise<RawPullRequest> {
635
- const { stdout } = await this.gh(["api", `repos/{owner}/{repo}/pulls/${number}`]);
766
+ private async pullRequest(number: number, options: GhOptions = {}): Promise<RawPullRequest> {
767
+ const { stdout } = await this.gh(["api", `repos/{owner}/{repo}/pulls/${number}`], {
768
+ ...options,
769
+ json: "document",
770
+ });
636
771
  return JSON.parse(stdout) as RawPullRequest;
637
772
  }
638
773
 
@@ -677,10 +812,14 @@ export class GhTracker implements Tracker {
677
812
  * counts as its re-run, as `gh pr checks` counted it.
678
813
  */
679
814
  private async ciSnapshot(number: number): Promise<CiSnapshot> {
680
- const pr = await this.gh(["api", `repos/{owner}/{repo}/pulls/${number}`], {
681
- allowFailure: true,
682
- });
683
- if (pr.exitCode !== 0) return { checks: undefined, conflicting: false };
815
+ const args = ["api", `repos/{owner}/{repo}/pulls/${number}`];
816
+ const pr = await this.gh(args, { allowFailure: true, json: "document" });
817
+ if (pr.exitCode !== 0) {
818
+ // GitHub failing on its own side after every try is no reading at all,
819
+ // where any other refusal reads as no checks, as it always has.
820
+ if (isGitHubFault(pr.output)) throwOnFailure("gh", args, pr);
821
+ return { checks: undefined, conflicting: false };
822
+ }
684
823
  const { head, mergeable } = JSON.parse(pr.stdout) as RawPullRequest;
685
824
  // `null` is GitHub still working it out, which is no conflict yet.
686
825
  const conflicting = mergeable === false;
@@ -709,10 +848,12 @@ export class GhTracker implements Tracker {
709
848
  * joins arrays, not the objects around them.
710
849
  */
711
850
  private async wrappedList(path: string, key: string): Promise<unknown[] | undefined> {
712
- const result = await this.gh([...pagedGet(path), "--jq", `.${key}[]`], {
713
- allowFailure: true,
714
- });
715
- if (result.exitCode !== 0) return undefined;
851
+ const args = [...pagedGet(path), "--jq", `.${key}[]`];
852
+ const result = await this.gh(args, { allowFailure: true, json: "lines" });
853
+ if (result.exitCode !== 0) {
854
+ if (isGitHubFault(result.output)) throwOnFailure("gh", args, result);
855
+ return undefined;
856
+ }
716
857
  try {
717
858
  return result.stdout
718
859
  .split("\n")
@@ -755,39 +896,114 @@ export class GhTracker implements Tracker {
755
896
  method: "POST" | "PATCH" | "PUT" | "DELETE",
756
897
  path: string,
757
898
  fields: string[],
758
- options: { allowFailure?: boolean; typed?: string[]; tolerate?: RegExp } = {},
899
+ options: GhOptions & { typed?: string[] } = {},
759
900
  ): Promise<Execution> {
901
+ const { typed = [], ...rest } = options;
760
902
  const args = [
761
903
  "api",
762
904
  "--method",
763
905
  method,
764
906
  path,
765
907
  ...fields.flatMap((field) => ["-f", field]),
766
- ...(options.typed ?? []).flatMap((field) => ["-F", field]),
908
+ ...typed.flatMap((field) => ["-F", field]),
767
909
  ];
768
- const result = await this.gh(args, { allowFailure: true });
769
- if (options.allowFailure || options.tolerate?.test(result.output)) return result;
770
- return throwOnFailure("gh", args, result);
910
+ return await this.gh(args, rest);
771
911
  }
772
912
 
773
913
  /**
774
914
  * Every page of a REST list, as one array: `gh --paginate` joins the pages.
775
915
  * `--method GET` is spelled out because fields would otherwise make it a POST.
776
916
  */
777
- private async list<T>(path: string, fields: string[] = []): Promise<T[]> {
778
- const { stdout } = await this.gh([...pagedGet(path), ...fields]);
917
+ private async list<T>(path: string, fields: string[] = [], options: GhOptions = {}): Promise<T[]> {
918
+ const { stdout } = await this.gh([...pagedGet(path), ...fields], { ...options, json: "document" });
779
919
  return JSON.parse(stdout) as T[];
780
920
  }
781
921
 
782
- private async gh(
783
- args: string[],
784
- options: { allowFailure?: boolean } = {},
785
- ): Promise<Execution> {
786
- const result = await this.runProcess("gh", args, {
787
- ...(this.cwd === undefined ? {} : { cwd: this.cwd }),
788
- });
789
- return options.allowFailure ? result : throwOnFailure("gh", args, result);
922
+ /**
923
+ * One `gh` call, tried again while GitHub fails on its own side.
924
+ *
925
+ * A 5xx, or an answer that is not the complete JSON the caller reads, is
926
+ * GitHub's: the call waits and tries again, {@link GITHUB_RETRY_DELAYS_MS}
927
+ * apart, and one that still fails after the last is an {@link OutsideFault}
928
+ * — or, for a caller that takes failures as answers, the failure it met.
929
+ * Every other failure is the caller's at once, as it always was, unless the
930
+ * call can tell it has landed: a refusal that follows a try GitHub failed may
931
+ * be GitHub declining to do again what that try did after all.
932
+ */
933
+ private async gh(args: string[], options: GhOptions = {}): Promise<Execution> {
934
+ for (let tried = 0; ; tried++) {
935
+ const result = await this.runProcess("gh", args, {
936
+ ...(this.cwd === undefined ? {} : { cwd: this.cwd }),
937
+ });
938
+ const fault = githubFaultIn(result, options);
939
+ const delay = options.once === true ? undefined : GITHUB_RETRY_DELAYS_MS[tried];
940
+ if (fault === undefined || delay === undefined) {
941
+ if (tried > 0 && refused(result, fault, options) && (await options.landed?.(true))) {
942
+ return result;
943
+ }
944
+ return finalAnswer(args, result, fault, options);
945
+ }
946
+ await this.sleep(delay);
947
+ if (await options.landed?.(false)) return result;
948
+ }
949
+ }
950
+ }
951
+
952
+ /**
953
+ * The fault of GitHub's a call met, in the one line the Run's last line quotes,
954
+ * or nothing where it met none: a 5xx or an unreadable answer `gh` reported,
955
+ * or an answer that is not the JSON the caller asked for. A failure the caller
956
+ * tolerates is its answer, whatever it says.
957
+ */
958
+ function githubFaultIn(result: Execution, options: GhOptions): string | undefined {
959
+ if (result.exitCode !== 0) {
960
+ if (options.tolerate?.test(result.output)) return undefined;
961
+ return isGitHubFault(result.output) ? firstLine(result.output) : undefined;
962
+ }
963
+ return options.json === undefined ? undefined : incompleteJson(result.stdout, options.json);
964
+ }
965
+
966
+ /**
967
+ * Whether GitHub turned the call down, as a 4xx: a failure that is no fault of
968
+ * GitHub's and that the caller does not take as an answer.
969
+ */
970
+ function refused(result: Execution, fault: string | undefined, options: GhOptions): boolean {
971
+ if (result.exitCode === 0 || fault !== undefined || options.allowFailure) return false;
972
+ return options.tolerate?.test(result.output) !== true;
973
+ }
974
+
975
+ /** Why `stdout` is not the JSON a caller reads, or nothing when it is. */
976
+ function incompleteJson(stdout: string, json: Json): string | undefined {
977
+ try {
978
+ if (json === "document") JSON.parse(stdout);
979
+ else for (const line of stdout.split("\n")) if (line.trim() !== "") JSON.parse(line);
980
+ return undefined;
981
+ } catch (error) {
982
+ return (error as Error).message;
983
+ }
984
+ }
985
+
986
+ /** A call's last answer, as its caller takes it: the result, or the error it is. */
987
+ function finalAnswer(
988
+ args: string[],
989
+ result: Execution,
990
+ fault: string | undefined,
991
+ options: GhOptions,
992
+ ): Execution {
993
+ if (result.exitCode !== 0) {
994
+ if (options.allowFailure || options.tolerate?.test(result.output)) return result;
995
+ return throwOnFailure("gh", args, result);
996
+ }
997
+ if (fault !== undefined) {
998
+ const shown = shownCommand("gh", args);
999
+ throw new OutsideFault(
1000
+ "github",
1001
+ shown,
1002
+ fault,
1003
+ `\`${shown}\` answered with a response that is not complete JSON\n${fault}`,
1004
+ );
790
1005
  }
1006
+ return result;
791
1007
  }
792
1008
 
793
1009
  /**
@@ -1,6 +1,6 @@
1
1
  import { existsSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
2
2
  import { tmpdir } from "node:os";
3
- import { basename, dirname, join, resolve } from "node:path";
3
+ import { basename, dirname, join, relative, resolve, sep } from "node:path";
4
4
  import { type Host, currentHost, sameHost } from "../host.js";
5
5
  import {
6
6
  LOCK_BRANCH,
@@ -36,7 +36,7 @@ import {
36
36
  stateFileName,
37
37
  stateFileTicket,
38
38
  } from "../resume.js";
39
- import { transcriptFiles } from "../run-log.js";
39
+ import { stageLogDir, transcriptFiles } from "../run-log.js";
40
40
  import { exec, execOrThrow, throwOnFailure } from "./exec.js";
41
41
 
42
42
  /**
@@ -597,6 +597,13 @@ export class GitWorkspace implements Workspace {
597
597
  throwOnFailure("git", args, result);
598
598
  }
599
599
 
600
+ async unshallow(): Promise<boolean> {
601
+ const { stdout } = await this.git(["rev-parse", "--is-shallow-repository"]);
602
+ if (stdout.trim() !== "true") return false;
603
+ await this.git(["fetch", "--unshallow", this.remote]);
604
+ return true;
605
+ }
606
+
600
607
  async pullBase(base: string): Promise<void> {
601
608
  const { stdout } = await this.git(["rev-parse", "--abbrev-ref", "HEAD"]);
602
609
  if (stdout.trim() === base) {
@@ -676,6 +683,12 @@ export class GitWorkspace implements Workspace {
676
683
  return { branch: STATE_BRANCH, path: directory };
677
684
  }
678
685
 
686
+ async transcriptsOnHost(ticket: number, runId: string): Promise<string | undefined> {
687
+ if (transcriptFiles(this.repoRoot, runId, ticket).length === 0) return undefined;
688
+ const directory = relative(this.repoRoot, stageLogDir(this.repoRoot, runId, ticket));
689
+ return `${directory.split(sep).join("/")}/`;
690
+ }
691
+
679
692
  /**
680
693
  * Rewrite the state branch as one new snapshot commit, the same as the tip
681
694
  * but for `edits`, and push it over the tip it was built from. Edits that
package/src/config.ts CHANGED
@@ -38,6 +38,7 @@ const configSchema = z
38
38
  baseBranch: z.string().min(1).optional(),
39
39
  lanes: z.number().int().positive().optional(),
40
40
  checks: z.array(z.string().min(1)).optional(),
41
+ merge: z.boolean().optional(),
41
42
  gates: z
42
43
  .object({ checks: z.boolean().optional(), ci: z.boolean().optional() })
43
44
  .strict()
@@ -55,6 +56,7 @@ const configSchema = z
55
56
  ciTimeoutMinutes: z.number().positive().optional(),
56
57
  ciGraceMinutes: z.number().nonnegative().optional(),
57
58
  checkTimeoutMinutes: z.number().positive().optional(),
59
+ keepTranscripts: z.boolean().optional(),
58
60
  labels: z
59
61
  .object({
60
62
  needsTriage: z.string().min(1).optional(),
@@ -100,6 +102,13 @@ export interface Config {
100
102
  */
101
103
  lanes: number;
102
104
  checks: string[];
105
+ /**
106
+ * Whether a Run merges a Ticket whose CI is green. A Target that merges by
107
+ * hand sets it to `false`, and its green Tickets are handed off with their
108
+ * pull requests as published. Not a gate: a gate switched off loosens what
109
+ * reaches a merge, and this tightens it.
110
+ */
111
+ merge: boolean;
103
112
  gates: { checks: boolean; ci: boolean };
104
113
  stages: {
105
114
  implement: StageConfig;
@@ -121,6 +130,12 @@ export interface Config {
121
130
  * the whole pipeline, and every command gets the whole of it.
122
131
  */
123
132
  checkTimeoutMinutes: number;
133
+ /**
134
+ * Whether a handed-off Ticket's transcripts are kept on the Target's remote,
135
+ * where the config says. Absent means it follows the Target's visibility,
136
+ * which {@link import("./transcript-home.js").resolveTranscriptHome} reads.
137
+ */
138
+ keepTranscripts?: boolean;
124
139
  labels: Labels;
125
140
  }
126
141
 
@@ -189,6 +204,7 @@ export function loadConfig(repoRoot: string, version: string): Config {
189
204
  ...(file.baseBranch === undefined ? {} : { baseBranch: file.baseBranch }),
190
205
  lanes: file.lanes ?? DEFAULT_LANES,
191
206
  checks: file.checks ?? inferChecks(repoRoot),
207
+ merge: file.merge ?? true,
192
208
  gates: {
193
209
  checks: file.gates?.checks ?? true,
194
210
  ci: file.gates?.ci ?? true,
@@ -203,6 +219,8 @@ export function loadConfig(repoRoot: string, version: string): Config {
203
219
  ciTimeoutMinutes: file.ciTimeoutMinutes ?? 30,
204
220
  ciGraceMinutes: file.ciGraceMinutes ?? DEFAULT_CI_GRACE_MINUTES,
205
221
  checkTimeoutMinutes: file.checkTimeoutMinutes ?? DEFAULT_CHECK_TIMEOUT_MINUTES,
222
+ // Spread, as baseBranch is: unset is an answer of its own, not false.
223
+ ...(file.keepTranscripts === undefined ? {} : { keepTranscripts: file.keepTranscripts }),
206
224
  labels: labels(file.labels),
207
225
  };
208
226
  }
@@ -94,13 +94,13 @@ Besides names such as GitHub and Claude Code, a capitalised word below is one of
94
94
  ## Branches
95
95
 
96
96
  - \`agent/<n>-<slug>\` belongs to the pipeline. A Run creates one per Ticket, works in a worktree of it, and pushes it after every Stage that commits. The repository deletes it when the pull request merges, a setting \`ticket-runner init\` switches on. Nothing else branches there.
97
- - \`ticket-runner/lock\` and \`ticket-runner/state\` belong to the pipeline too. The first says which Run holds this repository, and the second keeps the state file of every Ticket a Run can resume, and the transcripts of the Stages of a handed-off Ticket. A Hand-off gives a Ticket to a human rather than merging it, and leaves its work where they can carry on from it. Nothing else commits to either, except a human, or an Operator a human asked, the Claude session a human opens on a cloud Host from the Claude app to start a Run, watch it and stop it, releasing a lock a vanished Host left behind.
97
+ - \`ticket-runner/lock\` and \`ticket-runner/state\` belong to the pipeline too. The first says which Run holds this repository, and the second keeps the state file of every Ticket a Run can resume, and the transcripts of the Stages of a handed-off Ticket where the \`keepTranscripts\` setting keeps them there, which it does by default only on a private repository. A Hand-off gives a Ticket to a human rather than merging it, and leaves its work where they can carry on from it. Nothing else commits to either, except a human, or an Operator a human asked, the Claude session a human opens on a cloud Host from the Claude app to start a Run, watch it and stop it, and, while no Run holds this repository, to carry the human's decision on a handed-off Ticket to the board, releasing a lock a vanished Host left behind.
98
98
 
99
99
  ## What a Ticket needs
100
100
 
101
101
  A Ticket is one issue the pipeline can implement in a single session. It is refused unless it carries all three:
102
102
 
103
- - **Acceptance Criteria** — unticked task list items, a \`- [ ]\` at the head of a line, in the issue body or in one of its comments. They are the only thing the verify Stage grades, so a promise written as prose is not one.
103
+ - **Acceptance Criteria** — unticked task list items, a \`- [ ]\` at the head of a line, in the issue body or in one of its comments. The verify Stage grades them one by one, and beside them any defect the Ticket's own branch made, which fails the Ticket as an unmet criterion does unless the Ticket leaves it out of scope or a documented decision accepts it. A promise written as prose is not a criterion, and a Ticket whose checkboxes are all ticked has none.
104
104
  - **Blockers as native dependencies** — GitHub's own \`blocked by\` edges, as \`gh issue create --blocked-by <n>\` records them. A \`Blocked by\` section in the body is a human-readable copy and nothing the pipeline reads.
105
105
  - **The \`ready-for-agent\` label** — how a Run finds the Ticket. A Run labels it \`in-progress\` for as long as it holds it.
106
106
 
@@ -111,7 +111,7 @@ A Ticket is one issue the pipeline can implement in a single session. It is refu
111
111
 
112
112
  ## The Operator's skill
113
113
 
114
- - \`.claude/skills/ticket-runner/\` belongs to the pipeline. It tells an Operator how to start a Run, report on it and pass on a Stop, a human's request that the Run finish the Tickets its Lanes hold and take no more. \`ticket-runner init\` writes it and rewrites it like this file, so an edit made there does not survive the next \`init\` either.
114
+ - \`.claude/skills/ticket-runner/\` belongs to the pipeline. It tells an Operator how to start a Run, report on it and pass on a Stop, a human's request that the Run finish the Tickets its Lanes hold and take no more. It also says what an Operator may write on the board, only at a human's explicit request and only while no Run holds this repository: swap a handed-off Ticket's \`ready-for-human\` label for \`ready-for-agent\`, post the human's decision as a comment with each new criterion as its own \`- [ ]\` checkbox, and turn a criterion the human names as replaced into \`- (superseded)\` followed by its words. It rewrites no criterion and no body otherwise. \`ticket-runner init\` writes it and rewrites it like this file, so an edit made there does not survive the next \`init\` either.
115
115
 
116
116
  ## Local directories
117
117