ticket-runner 0.6.2 → 0.6.4

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.
@@ -0,0 +1,159 @@
1
+ import type { HostKind } from "./host.js";
2
+
3
+ /**
4
+ * Whose money a Run's Stages spend, decided once when the Run starts and held
5
+ * for the whole Run: the subscription the Host is logged in with, or the API
6
+ * key the Host exports, which a Run uses only when it was started with
7
+ * `--api-key`. The choice is the Host's business, so it is a flag and never a
8
+ * field of the Target's config.
9
+ */
10
+ export type Credential = "subscription" | "api-key";
11
+
12
+ /**
13
+ * The variable the CLI reads an API key from. Under `-p` it outranks the
14
+ * subscription login without asking, so a Stage of a subscription Run is
15
+ * started without it, whatever the Host exports.
16
+ */
17
+ export const API_KEY_ENV_VAR = "ANTHROPIC_API_KEY";
18
+
19
+ /** The credential, as the Run summary's header and the log name it. */
20
+ export const CREDENTIAL_WORDS: Record<Credential, string> = {
21
+ subscription: "subscription",
22
+ "api-key": "API key",
23
+ };
24
+
25
+ /**
26
+ * The `apiKeySource` a Stage's `system/init` event reports when it ran on the
27
+ * Run's credential. Any other is a Stage billed somewhere the Run did not
28
+ * choose: a key an `apiKeyHelper` in the Host's settings supplied, say, which
29
+ * no environment variable removes.
30
+ */
31
+ export function expectedKeySource(credential: Credential): string {
32
+ return credential === "api-key" ? API_KEY_ENV_VAR : "none";
33
+ }
34
+
35
+ /**
36
+ * A Stage that reported another `apiKeySource` than its Run's credential
37
+ * expects, which the Run's log and its summary each name.
38
+ */
39
+ export interface StrayStage {
40
+ ticket: number;
41
+ stage: string;
42
+ /** What the Stage's `system/init` event said it ran on. */
43
+ apiKeySource: string;
44
+ /** What the CLI priced the Stage at, where it said. */
45
+ costUsd?: number;
46
+ /** Present, and true, where {@link costUsd} is only part of the Stage's. */
47
+ costIncomplete?: true;
48
+ }
49
+
50
+ /**
51
+ * What a Run's Stages were billed, gathered as each comes back and shared by
52
+ * every Ticket, for the Run summary and nothing else: the log and the Progress
53
+ * comment carry no amount.
54
+ */
55
+ export interface Billing {
56
+ /** Every Stage that ran on something other than the Run's credential, in order. */
57
+ strays: StrayStage[];
58
+ /**
59
+ * The Spend, in dollars: the CLI's figures for the Stages of an `--api-key`
60
+ * Run that ran on the Run's own key, added up, which is the amount that key's
61
+ * Console can be checked against. Always zero on a subscription Run, whose
62
+ * figure is an estimate at API prices and not money spent.
63
+ */
64
+ spendUsd: number;
65
+ /**
66
+ * Whether a Stage that ran on the Run's own key reported no figure, or only
67
+ * part of its session's — one the wall-clock limit stopped or that crashed —
68
+ * so the Spend is at least {@link spendUsd}.
69
+ */
70
+ spendUnreported: boolean;
71
+ /** Whether any Stage said it ran on the subscription's extra usage. */
72
+ extraUsage: boolean;
73
+ }
74
+
75
+ /** A Run's billing before any Stage has come back. */
76
+ export function emptyBilling(): Billing {
77
+ return { strays: [], spendUsd: 0, spendUnreported: false, extraUsage: false };
78
+ }
79
+
80
+ /** What a Stage said about what it was billed to, as far as {@link Billing} needs it. */
81
+ export interface StageBilling {
82
+ /** What the Stage's `system/init` event said it ran on, absent where it printed none. */
83
+ apiKeySource?: string;
84
+ /** What the CLI priced the Stage at, absent where no `result` event gave a figure. */
85
+ costUsd?: number;
86
+ /** Present, and true, where {@link costUsd} is only part of the Stage's. */
87
+ costIncomplete?: true;
88
+ /** Present, and true, where the Stage ran on the subscription's extra usage. */
89
+ extraUsage?: true;
90
+ }
91
+
92
+ /**
93
+ * Add one Stage of a Run on `credential` to the Run's billing, and return it as
94
+ * a stray where it ran on something else.
95
+ *
96
+ * A Stage that reported no `apiKeySource` printed no `system/init` event and so
97
+ * made no request: it is no stray, adds no Spend and leaves the Spend exact. A
98
+ * stray's figure stays on its own row and out of the Spend, which is the Run's
99
+ * own key's alone.
100
+ */
101
+ export function recordStage(
102
+ billing: Billing,
103
+ credential: Credential,
104
+ ticket: number,
105
+ stage: string,
106
+ { apiKeySource, costUsd, costIncomplete, extraUsage }: StageBilling,
107
+ ): StrayStage | undefined {
108
+ if (extraUsage === true) billing.extraUsage = true;
109
+ if (apiKeySource === undefined) return undefined;
110
+
111
+ if (apiKeySource !== expectedKeySource(credential)) {
112
+ const stray: StrayStage = {
113
+ ticket,
114
+ stage,
115
+ apiKeySource,
116
+ ...(costUsd === undefined ? {} : { costUsd }),
117
+ ...(costUsd !== undefined && costIncomplete === true ? { costIncomplete } : {}),
118
+ };
119
+ billing.strays.push(stray);
120
+ return stray;
121
+ }
122
+
123
+ if (credential === "api-key") {
124
+ if (costUsd === undefined || costIncomplete === true) billing.spendUnreported = true;
125
+ billing.spendUsd += costUsd ?? 0;
126
+ }
127
+ return undefined;
128
+ }
129
+
130
+ /**
131
+ * Why a Run on `credential` will not start on this Host, or nothing where it
132
+ * can.
133
+ *
134
+ * Only an `--api-key` Run can be refused. A cloud Host always runs its
135
+ * sessions on the subscription whatever its environment says, so the flag
136
+ * would be a Run spending the subscription without a word; and a Host that
137
+ * exports no key has none to hand the Stages.
138
+ */
139
+ export function credentialRefusal(
140
+ credential: Credential,
141
+ host: HostKind,
142
+ env: Record<string, string | undefined>,
143
+ ): string | undefined {
144
+ if (credential !== "api-key") return undefined;
145
+ if (host === "cloud") {
146
+ return (
147
+ "`--api-key` needs a workstation Host: a cloud session runs every Stage on the " +
148
+ `subscription, whatever \`${API_KEY_ENV_VAR}\` says. Run without \`--api-key\`, or ` +
149
+ "start the Run on a workstation."
150
+ );
151
+ }
152
+ if ((env[API_KEY_ENV_VAR] ?? "") === "") {
153
+ return (
154
+ `\`--api-key\` runs every Stage on the \`${API_KEY_ENV_VAR}\` this shell exports, and it ` +
155
+ "exports none. Export the key, or run without `--api-key` to run on the subscription."
156
+ );
157
+ }
158
+ return undefined;
159
+ }
@@ -1,5 +1,12 @@
1
1
  import { branchName, worktreePath } from "./branch.js";
2
2
  import type { Config } from "./config.js";
3
+ import {
4
+ type Billing,
5
+ CREDENTIAL_WORDS,
6
+ type Credential,
7
+ expectedKeySource,
8
+ recordStage,
9
+ } from "./credential.js";
3
10
  import { tickMetCriteria } from "./criteria.js";
4
11
  import type { BaseBranchChecks, FailingBase } from "./failing-base.js";
5
12
  import { type SkipReason, isGuardReason, skipReason } from "./guards.js";
@@ -41,6 +48,7 @@ import { retryLogDir, stageLogDir } from "./run-log.js";
41
48
  import { holdsClaim } from "./stranded.js";
42
49
  import {
43
50
  RELEASE_WORDS,
51
+ releaseWords,
44
52
  draftPullRequestBody,
45
53
  failingBaseNote,
46
54
  failingBaseSummary,
@@ -50,6 +58,7 @@ import {
50
58
  pullRequestBody,
51
59
  squashCommit,
52
60
  } from "./templates.js";
61
+ import type { StartTimer } from "./timer.js";
53
62
  import { CODE_STAGE_JSON_SCHEMA, parseTitle, pullRequestTitle } from "./title.js";
54
63
  import {
55
64
  type Verdict,
@@ -126,6 +135,17 @@ export interface Pipeline {
126
135
  * can point at the Run's directory: a cloud Host's is gone with its session.
127
136
  */
128
137
  host: HostKind;
138
+ /**
139
+ * What every Stage of this Run is billed to, chosen once when it started:
140
+ * the subscription, or the Host's API key for a Run started with `--api-key`.
141
+ */
142
+ credential: Credential;
143
+ /**
144
+ * What every Stage of this Run said it was billed, shared by every Ticket so
145
+ * the Run summary can name each Stage that ran on something other than
146
+ * {@link credential}, and say what the Run spent.
147
+ */
148
+ billing: Billing;
129
149
  /**
130
150
  * The branch every Ticket of this Run branches from, rebases onto, merges
131
151
  * into and pulls, resolved once before the Run started
@@ -157,6 +177,12 @@ export interface Pipeline {
157
177
  * there is a Stage told to exercise it through its tests and fakes.
158
178
  */
159
179
  selfHosted: boolean;
180
+ /**
181
+ * How the Run waits between its looks at the Frontier while a Lane is free
182
+ * and another busy: the real clock, unless a test hands it one it moves
183
+ * itself. Never the interval, which is fixed.
184
+ */
185
+ startTimer?: StartTimer;
160
186
  log?: (line: string) => void;
161
187
  }
162
188
 
@@ -177,18 +203,21 @@ class TicketFailure extends Error {
177
203
  }
178
204
 
179
205
  /**
180
- * What stops a Ticket that says nothing about it: the subscription rate limit,
181
- * a transient API failure — the API overloaded, broken or silent on its own
182
- * side after the CLI had already retried it — and a Base branch that fails the
183
- * Check the Ticket's branch failed.
206
+ * What stops a Ticket that says nothing about it: the rate limit, a transient
207
+ * API failure — the API overloaded, broken or silent on its own side after the
208
+ * CLI had already retried it — the API key of an `--api-key` Run out of credit
209
+ * or past its workspace's spend limit, and a Base branch that fails the Check
210
+ * the Ticket's branch failed.
184
211
  */
185
212
  export type ReleaseCause = StageReleaseCause | "failing-base";
186
213
 
187
214
  /** The Stage failures among them. */
188
- type StageReleaseCause = Extract<StageFailure, "rate-limited" | "api-error">;
215
+ type StageReleaseCause = Extract<StageFailure, "rate-limited" | "api-error" | "out-of-budget">;
189
216
 
190
217
  function releaseCause(result: StageResult): StageReleaseCause | undefined {
191
- return result.failure === "rate-limited" || result.failure === "api-error"
218
+ return result.failure === "rate-limited" ||
219
+ result.failure === "api-error" ||
220
+ result.failure === "out-of-budget"
192
221
  ? result.failure
193
222
  : undefined;
194
223
  }
@@ -883,11 +912,16 @@ async function passOver(
883
912
  * Start one Stage under the model, effort, turn and wall-clock limits its own
884
913
  * config names. Everything a Stage differs in is the prompt, where it runs and
885
914
  * where it logs; the limits come from one place so no Stage can quietly skip them.
915
+ *
916
+ * The credential is the Run's too, and what the Stage says it actually ran on
917
+ * is checked here for the same reason: a Stage billed somewhere the Run did not
918
+ * choose is named whichever Stage it was.
886
919
  */
887
- function runStage(
920
+ async function runStage(
888
921
  pipeline: Pipeline,
889
922
  stage: StageName,
890
923
  request: {
924
+ ticket: number;
891
925
  prompt: string;
892
926
  cwd: string;
893
927
  logDir: string;
@@ -896,12 +930,13 @@ function runStage(
896
930
  },
897
931
  ): Promise<StageResult> {
898
932
  const limits = pipeline.config.stages[stage];
899
- return pipeline.runner.run({
933
+ const result = await pipeline.runner.run({
900
934
  stage,
901
935
  prompt: request.prompt,
902
936
  cwd: request.cwd,
903
937
  logDir: request.logDir,
904
938
  permissionMode: pipeline.config.permissionMode,
939
+ credential: pipeline.credential,
905
940
  model: limits.model,
906
941
  effort: limits.effort,
907
942
  maxTurns: limits.maxTurns,
@@ -911,6 +946,30 @@ function runStage(
911
946
  ? {}
912
947
  : { resultRequired: request.resultRequired }),
913
948
  });
949
+ noteBilling(pipeline, request.ticket, stage, result);
950
+ return result;
951
+ }
952
+
953
+ /**
954
+ * Add a Stage to what the Run was billed, and name it in the log now when its
955
+ * `system/init` event reported another `apiKeySource` than the Run's credential
956
+ * expects; the summary names it again at the end. A Stage that reported none,
957
+ * one that never started, is not named: there is nothing it said to set
958
+ * against the Run's choice. The log line carries no amount: the summary is the
959
+ * only place one is printed.
960
+ */
961
+ function noteBilling(
962
+ pipeline: Pipeline,
963
+ ticket: number,
964
+ stage: StageName,
965
+ result: StageResult,
966
+ ): void {
967
+ const stray = recordStage(pipeline.billing, pipeline.credential, ticket, stage, result);
968
+ if (stray === undefined) return;
969
+ pipeline.log?.(
970
+ `#${ticket} ${stage} ran on apiKeySource ${stray.apiKeySource}, ` +
971
+ `not the ${CREDENTIAL_WORDS[pipeline.credential]} (${expectedKeySource(pipeline.credential)})`,
972
+ );
914
973
  }
915
974
 
916
975
  /**
@@ -924,13 +983,16 @@ function runStage(
924
983
  * work that is already on the branch.
925
984
  */
926
985
  async function releasedStage(
986
+ pipeline: Pipeline,
927
987
  progress: Progress,
928
988
  stage: StageName,
929
989
  point: FailurePoint,
930
990
  result: StageResult,
931
991
  cause: StageReleaseCause,
932
992
  ): Promise<Releasing> {
933
- await progress.record(stageRow(stage, result, `⏸ ${STAGE_FAILURES[cause].cell}`));
993
+ await progress.record(
994
+ stageRow(stage, result, `⏸ ${stageFailureCell(result, pipeline.credential)}`),
995
+ );
934
996
  return new Releasing(
935
997
  point,
936
998
  stage === "implement" ? "claimed" : "implemented",
@@ -955,13 +1017,15 @@ async function stageDidNotFinish(
955
1017
  ): Promise<TicketFailure | Releasing> {
956
1018
  const cause = releaseCause(result);
957
1019
  if (cause !== undefined) {
958
- return await releasedStage(progress, stage, stage, result, cause);
1020
+ return await releasedStage(pipeline, progress, stage, stage, result, cause);
959
1021
  }
960
1022
 
961
- await progress.record(stageRow(stage, result, `❌ ${stageFailureCell(result)}`));
1023
+ await progress.record(
1024
+ stageRow(stage, result, `❌ ${stageFailureCell(result, pipeline.credential)}`),
1025
+ );
962
1026
  return new TicketFailure(
963
1027
  stage,
964
- describeStageFailure(stage, pipeline.config.stages[stage], result),
1028
+ describeStageFailure(stage, pipeline.config.stages[stage], result, pipeline.credential),
965
1029
  );
966
1030
  }
967
1031
 
@@ -1069,6 +1133,7 @@ async function implement(
1069
1133
  ): Promise<void> {
1070
1134
  const stage = pipeline.config.stages.implement;
1071
1135
  const result = await runStage(pipeline, "implement", {
1136
+ ticket: issue.number,
1072
1137
  prompt: implementPrompt(
1073
1138
  issue.url,
1074
1139
  pipeline.baseBranch,
@@ -1214,9 +1279,11 @@ async function runChecks(
1214
1279
  );
1215
1280
  }
1216
1281
  }
1282
+ // No command is not a pass: only `gates.checks` off lets a Run start with
1283
+ // none, and the row says so as the ci row does for a pull request with none.
1217
1284
  await progress.record({
1218
1285
  point: "checks",
1219
- outcome: "✅ passed",
1286
+ outcome: pipeline.config.checks.length === 0 ? "⚠️ no checks" : "✅ passed",
1220
1287
  durationMs: Date.now() - startedAt,
1221
1288
  });
1222
1289
  }
@@ -1314,6 +1381,7 @@ async function verify(
1314
1381
  ): Promise<Verdict> {
1315
1382
  const stage = pipeline.config.stages.verify;
1316
1383
  const result = await runStage(pipeline, "verify", {
1384
+ ticket: issue.number,
1317
1385
  prompt: verifyPrompt(
1318
1386
  issue.url,
1319
1387
  stage.extraPrompt,
@@ -1406,6 +1474,7 @@ async function fix(
1406
1474
  const commitsBefore = await commitCount(pipeline, branch);
1407
1475
 
1408
1476
  const result = await runStage(pipeline, "fix", {
1477
+ ticket: issue.number,
1409
1478
  prompt: fixPrompt(
1410
1479
  issue.url,
1411
1480
  failure,
@@ -1520,6 +1589,7 @@ async function conflictStage(
1520
1589
  const stage = pipeline.config.stages.conflict;
1521
1590
  try {
1522
1591
  const result = await runStage(pipeline, "conflict", {
1592
+ ticket: issue.number,
1523
1593
  prompt: conflictPrompt(
1524
1594
  issue.url,
1525
1595
  conflict,
@@ -1550,7 +1620,7 @@ async function conflictStage(
1550
1620
  // rebases is clean.
1551
1621
  const cause = releaseCause(result);
1552
1622
  if (cause !== undefined) {
1553
- return await releasedStage(progress, "conflict", "rebase", result, cause);
1623
+ return await releasedStage(pipeline, progress, "conflict", "rebase", result, cause);
1554
1624
  }
1555
1625
 
1556
1626
  await progress.record(stageRow("conflict", result, "❌ unresolved"));
@@ -1558,7 +1628,7 @@ async function conflictStage(
1558
1628
  "rebase",
1559
1629
  result.ok
1560
1630
  ? `the conflict Stage did not finish the rebase onto ${pipeline.baseBranch}`
1561
- : describeStageFailure("conflict", stage, result),
1631
+ : describeStageFailure("conflict", stage, result, pipeline.credential),
1562
1632
  [conflict, state.unresolved].join("\n\n"),
1563
1633
  "unresolved-conflict",
1564
1634
  );
@@ -1744,7 +1814,7 @@ async function release(
1744
1814
  await tracker.removeLabel(ticket, config.labels.inProgress);
1745
1815
  await tracker.unassign(ticket, user);
1746
1816
  pipeline.log?.(
1747
- `#${ticket} released at ${stopped.point} · ${RELEASE_WORDS[stopped.reason]} · ${branch}`,
1817
+ `#${ticket} released at ${stopped.point} · ${releaseWords(stopped.reason, pipeline.credential)} · ${branch}`,
1748
1818
  );
1749
1819
 
1750
1820
  return {
@@ -2099,6 +2169,11 @@ const STAGE_FAILURES: Record<
2099
2169
  cell: "API failure",
2100
2170
  sentence: () => "was stopped by an API failure the CLI had given up retrying",
2101
2171
  },
2172
+ // And so is this one.
2173
+ "out-of-budget": {
2174
+ cell: "out of API budget",
2175
+ sentence: () => "ran out of API budget: the key's credit or its workspace's spend limit",
2176
+ },
2102
2177
  "timed-out": {
2103
2178
  cell: "timed out",
2104
2179
  sentence: (limits) => `ran past its ${limits.maxMinutes} minute limit`,
@@ -2117,7 +2192,14 @@ const STAGE_FAILURES: Record<
2117
2192
  /** A Stage that came back without saying why gets the one word that is true. */
2118
2193
  const UNEXPLAINED = { cell: "failed", sentence: () => "failed" } as const;
2119
2194
 
2120
- function stageFailure(result: StageResult) {
2195
+ /**
2196
+ * The rate limit of an `--api-key` Run, which is the API's own rather than the
2197
+ * subscription's, and is named so wherever the subscription's would be.
2198
+ */
2199
+ const API_RATE_LIMIT = { cell: "API rate limited", sentence: () => "hit the API rate limit" } as const;
2200
+
2201
+ function stageFailure(result: StageResult, credential: Credential) {
2202
+ if (result.failure === "rate-limited" && credential === "api-key") return API_RATE_LIMIT;
2121
2203
  return result.failure ? STAGE_FAILURES[result.failure] : UNEXPLAINED;
2122
2204
  }
2123
2205
 
@@ -2125,11 +2207,12 @@ function describeStageFailure(
2125
2207
  stage: string,
2126
2208
  limits: StageLimits,
2127
2209
  result: StageResult,
2210
+ credential: Credential,
2128
2211
  ): string {
2129
- return `the ${stage} Stage ${stageFailure(result).sentence(limits)}`;
2212
+ return `the ${stage} Stage ${stageFailure(result, credential).sentence(limits)}`;
2130
2213
  }
2131
2214
 
2132
2215
  /** The same failure, short enough for a table cell. */
2133
- function stageFailureCell(result: StageResult): string {
2134
- return stageFailure(result).cell;
2216
+ function stageFailureCell(result: StageResult, credential: Credential): string {
2217
+ return stageFailure(result, credential).cell;
2135
2218
  }
@@ -1,3 +1,5 @@
1
+ import type { Credential } from "../credential.js";
2
+
1
3
  /**
2
4
  * One Claude Code session per Stage (ADR-0002).
3
5
  *
@@ -25,14 +27,16 @@ export const EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"] as const;
25
27
  export type Effort = (typeof EFFORT_LEVELS)[number];
26
28
 
27
29
  /**
28
- * Why a Stage did not finish cleanly. `rate-limited` and `api-error` are singled
29
- * out because the pipeline releases a claim rather than blaming the Ticket for
30
- * either: one is the subscription running out of room, the other the API failing
31
- * on its side after the CLI had given up retrying it.
30
+ * Why a Stage did not finish cleanly. `rate-limited`, `api-error` and
31
+ * `out-of-budget` are singled out because the pipeline releases a claim rather
32
+ * than blaming the Ticket for any of them: the rate limit, the API failing on
33
+ * its side after the CLI had given up retrying it, and the API key's
34
+ * organization out of credit or its workspace past its spend limit.
32
35
  */
33
36
  export type StageFailure =
34
37
  | "rate-limited"
35
38
  | "api-error"
39
+ | "out-of-budget"
36
40
  | "timed-out"
37
41
  | "turn-capped"
38
42
  | "nonzero-exit"
@@ -48,6 +52,11 @@ export interface StageRequest {
48
52
  maxTurns: number;
49
53
  maxMinutes: number;
50
54
  permissionMode: PermissionMode;
55
+ /**
56
+ * What the session is billed to: the subscription, with the Host's API key
57
+ * kept out of its environment, or that key.
58
+ */
59
+ credential: Credential;
51
60
  /** Where the command line, stdout, stderr and transcript are written. */
52
61
  logDir: string;
53
62
  /** When set, the Stage is asked for structured output matching this schema. */
@@ -80,6 +89,33 @@ export interface StageResult {
80
89
  * when the CLI said.
81
90
  */
82
91
  limitResetsAt?: string;
92
+ /**
93
+ * What the session said it was billed to, as its `system/init` event's
94
+ * `apiKeySource` names it: `none` for the subscription login,
95
+ * `ANTHROPIC_API_KEY`, `apiKeyHelper` and so on for a key. Absent where the
96
+ * session printed no such event.
97
+ */
98
+ apiKeySource?: string;
99
+ /**
100
+ * What the CLI priced the session at, in dollars: the `total_cost_usd` of its
101
+ * last `result` event. A session that woke for background agents repeats the
102
+ * whole session's figure on every waking, so it is read once, never summed.
103
+ * Absent where no `result` event carried one: a session a Stop killed, the
104
+ * wall-clock limit stopped, or that crashed before it.
105
+ */
106
+ costUsd?: number;
107
+ /**
108
+ * Present, and true, when {@link costUsd} is only part of the session's:
109
+ * the session went on past the last `result` event that gave a figure, and
110
+ * was killed or crashed before it gave another, or the wall-clock limit
111
+ * stopped it while it waited for a background agent.
112
+ */
113
+ costIncomplete?: true;
114
+ /**
115
+ * Present, and true, when one of the session's `rate_limit_event`s said it
116
+ * was using the subscription's extra usage (`isUsingOverage`).
117
+ */
118
+ extraUsage?: true;
83
119
  }
84
120
 
85
121
  /**
@@ -374,6 +374,20 @@ export interface Workspace {
374
374
  * where the work is once this Host is gone only when that is true.
375
375
  */
376
376
  hasRemoteBranch(branch: string): Promise<boolean>;
377
+ /**
378
+ * The remote every branch is fetched from and pushed to, by the name a human
379
+ * types after `git push`, so a message can spell a branch on it as `origin/main`.
380
+ */
381
+ readonly remote: string;
382
+ /**
383
+ * The contents of `path` at the tip of `branch` as the remote holds it now,
384
+ * which is what every Ticket's worktree is made from, and nothing when the
385
+ * remote has no such branch or the branch no such file.
386
+ *
387
+ * Asked by Target readiness alone, before a Run takes the lock: a file `init`
388
+ * wrote and nobody pushed is in the checkout and in no Stage's worktree.
389
+ */
390
+ readRemoteFile(branch: string, path: string): Promise<string | undefined>;
377
391
  /**
378
392
  * Delete `branch` on the remote; the PR is merged, so nothing references it.
379
393
  * A branch the remote already deleted, as GitHub does on merge when told to,
package/src/prompts.ts CHANGED
@@ -86,8 +86,13 @@ const titleGuidance = (base: string) =>
86
86
  /**
87
87
  * Guidance appended to every implement Stage, working around known defects of
88
88
  * the `implement` skill in an unattended session.
89
+ *
90
+ * The Ticket's URL is handed to the review explicitly: the review looks for its
91
+ * spec in the commit messages first, the skill does not always pass it on, and
92
+ * commit subjects need not carry the Ticket number.
89
93
  */
90
94
  const implementGuidance = (
95
+ issueUrl: string,
91
96
  base: string,
92
97
  checks: readonly string[],
93
98
  ) => `This session is unattended. Follow this guidance as well as the skill's own:
@@ -95,6 +100,7 @@ const implementGuidance = (
95
100
  - Make an initial commit before running \`/mattpocock-skills:code-review\`, so the reviewed diff is not empty.
96
101
  ${titleGuidance(base)}
97
102
  - The review the skill asks for is \`/mattpocock-skills:code-review\`. Invoke it by that full name: the short name also matches the CLI's own built-in review skill, which runs neither the Standards review nor the Spec review.
103
+ - Pass the review this Ticket's URL, \`${issueUrl}\`, as the spec. It otherwise looks for the spec in the commit messages, which need not name the Ticket, and reviews with no spec without saying so.
98
104
  - Spawn its review sub-agents with \`run_in_background: false\` set explicitly, several in one message so they still run in parallel. Omitting \`run_in_background\` still runs them in the background, and you would then reach your answer before the review has come back.
99
105
  - Do not answer the schema until the review has returned and the fixes you take from it are committed. An answer you have already given does not stop you committing: the pipeline waits for this session to exit before it reads the branch.
100
106
  - A later answer replaces an earlier one, so if you answer again, repeat every Note you still stand by.${codeChecksLine(checks, true)}
@@ -284,7 +290,7 @@ export function implementPrompt(
284
290
  ): string {
285
291
  return sections([
286
292
  `/mattpocock-skills:implement ${issueUrl}`,
287
- implementGuidance(base, checks),
293
+ implementGuidance(issueUrl, base, checks),
288
294
  stageBoundary(selfHosted),
289
295
  notesGuidance(standingNotes),
290
296
  extraPrompt,