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,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,11 +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` is singled out because the
29
- * pipeline releases a claim rather than blaming the Ticket for 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.
30
35
  */
31
36
  export type StageFailure =
32
37
  | "rate-limited"
38
+ | "api-error"
39
+ | "out-of-budget"
33
40
  | "timed-out"
34
41
  | "turn-capped"
35
42
  | "nonzero-exit"
@@ -45,6 +52,11 @@ export interface StageRequest {
45
52
  maxTurns: number;
46
53
  maxMinutes: number;
47
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;
48
60
  /** Where the command line, stdout, stderr and transcript are written. */
49
61
  logDir: string;
50
62
  /** When set, the Stage is asked for structured output matching this schema. */
@@ -71,6 +83,19 @@ export interface StageResult {
71
83
  transcriptPath: string;
72
84
  turns?: number;
73
85
  durationMs: number;
86
+ /**
87
+ * When the subscription rate limit resets, ISO-8601, as the event that
88
+ * rejected the request said. Present only on a `rate-limited` Stage, and only
89
+ * when the CLI said.
90
+ */
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;
74
99
  }
75
100
 
76
101
  /**
@@ -126,7 +126,7 @@ export interface CreatePullRequest {
126
126
 
127
127
  /**
128
128
  * The outcome of waiting for a pull request's CI checks. Distinct from a Check,
129
- * which is a command the pipeline runs itself (CONTEXT.md).
129
+ * which is a command the pipeline runs itself (GLOSSARY.md).
130
130
  *
131
131
  * `none` means the PR has no checks at all, which `gates.ci` treats as a
132
132
  * failure rather than a silent bypass.
@@ -207,9 +207,10 @@ export interface Tracker {
207
207
  * Release, named `owner/name`, or nothing where GitHub could not be asked.
208
208
  *
209
209
  * Named for the tag rather than for the Release, because a Release in this
210
- * codebase is what a rate-limited Stage does to a Ticket (CONTEXT.md). A
211
- * published GitHub Release is what makes a tag a Version anybody can install,
212
- * which is why it is the question rather than the tag alone.
210
+ * codebase is what a Stage the rate limit or an API failure stopped does to
211
+ * a Ticket (GLOSSARY.md). A published GitHub Release is what makes a tag a
212
+ * Version anybody can install, which is why it is the question rather than
213
+ * the tag alone.
213
214
  *
214
215
  * The one method of this port that is not about the Target: it is asked about
215
216
  * the pipeline's own repository, so a Run and `init` can say that a newer
@@ -45,7 +45,7 @@ export type RebaseState = { resolved: true } | { resolved: false; unresolved: st
45
45
  * `implemented` one carrying that Stage's work on its branch with no merge
46
46
  * behind it.
47
47
  *
48
- * A state of the lifecycle, not a Stage — a Stage is a session (CONTEXT.md), and
48
+ * A state of the lifecycle, not a Stage — a Stage is a session (GLOSSARY.md), and
49
49
  * what the State records is what the Ticket has, not what was running. Only these
50
50
  * two, because everything after the implement Stage — the Checks, the rebase,
51
51
  * the pull request, CI and the merge — is re-run from the top by a Run that
@@ -82,6 +82,13 @@ export interface TicketState {
82
82
  * when no Stage has answered one, and in State an earlier pipeline left.
83
83
  */
84
84
  title?: string;
85
+ /**
86
+ * Whether the Run that takes the Ticket up rebases its branch onto the Base
87
+ * branch before its Checks. Set by a Release over a failing Base branch, so
88
+ * a fix a human has landed there meanwhile reaches the branch; absent
89
+ * otherwise, and in State an earlier pipeline left.
90
+ */
91
+ rebaseFirst?: boolean;
85
92
  /** The Run that last wrote the State, and when — both for a human reading it. */
86
93
  runId: string;
87
94
  /**
@@ -228,6 +235,12 @@ export interface Workspace {
228
235
  * out at `path`. The checkout's own `base` is not moved.
229
236
  */
230
237
  createWorktree(worktree: WorktreeRef, base: string): Promise<void>;
238
+ /**
239
+ * Check `commit` out, detached, in a fresh worktree at `path`, where a Check
240
+ * can be run against what a Ticket's branch inherited. A worktree a killed
241
+ * Run left at `path` is replaced: nothing in one is worth keeping.
242
+ */
243
+ createDetachedWorktree(path: string, commit: string): Promise<void>;
231
244
  /**
232
245
  * Remove the worktree and delete its branch; a detached worktree, which has
233
246
  * none, is only removed.
@@ -235,7 +248,9 @@ export interface Workspace {
235
248
  removeWorktree(worktree: { path: string; branch?: string }): Promise<void>;
236
249
  /**
237
250
  * Every `ticket-<n>` worktree of this repo under the Target's `.worktrees/`,
238
- * whatever Ticket or Run made it, with what each holds that GitHub lacks.
251
+ * whatever Ticket or Run made it, with what each holds that GitHub lacks,
252
+ * and every `base-<commit>` worktree a Run killed mid-Check left there,
253
+ * which holds nothing worth keeping whatever the Check wrote into it.
239
254
  *
240
255
  * Asked by `ticket-runner remove` alone, which refuses to take out a
241
256
  * worktree holding work nothing else has.
@@ -287,6 +302,13 @@ export interface Workspace {
287
302
  * answers yes about.
288
303
  */
289
304
  hasBranch(branch: string): Promise<boolean>;
305
+ /**
306
+ * The commit the branch checked out at `cwd` inherited from `base`: their
307
+ * merge-base, with `base` as the remote holds it now. The checkout's own
308
+ * `base` may be behind what the branch was made from, and the remote's ahead
309
+ * of it, and neither changes what the branch inherited.
310
+ */
311
+ mergeBase(cwd: string, base: string): Promise<string>;
290
312
  /**
291
313
  * Subjects of the commits on `branch` that `base` does not have, oldest first.
292
314
  *
@@ -352,6 +374,20 @@ export interface Workspace {
352
374
  * where the work is once this Host is gone only when that is true.
353
375
  */
354
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>;
355
391
  /**
356
392
  * Delete `branch` on the remote; the PR is merged, so nothing references it.
357
393
  * A branch the remote already deleted, as GitHub does on merge when told to,
package/src/prompts.ts CHANGED
@@ -6,6 +6,7 @@
6
6
 
7
7
  import { CONVENTIONS_PATH } from "./conventions.js";
8
8
  import type { FailureKind } from "./lifecycle.js";
9
+ import { OWN_DEFECT } from "./note-schema.js";
9
10
  import { STAGE_ENV_VAR } from "./stage-guard.js";
10
11
  import { BRANCH_TITLE } from "./title.js";
11
12
 
@@ -47,10 +48,32 @@ function stageBoundary(selfHosted: boolean): string {
47
48
  * a Stage told only to remove what no commit carries deletes the dependencies
48
49
  * it installed for nothing.
49
50
  */
50
- const FINISH_GUIDANCE = `- Never end your turn while uncommitted work waits on a background task: the session ends with your turn and stops that task, and the work is never committed. Run your final tests in the foreground, then commit.
51
+ const FINISH_GUIDANCE = `- Never end your turn while uncommitted work waits on a background task: the session ends with your turn and stops that task, and the work is never committed.
51
52
  - Leave the worktree clean: commit your work and remove every untracked file that is not ignored and that no commit carries, test output included. The pipeline refuses a worktree holding changes no commit carries.
52
53
  - Keep gitignored files, such as dependencies you installed. The pipeline does not count them against a clean worktree, and deleting them only leaves the next Stage to install them again.`;
53
54
 
55
+ /** The Check commands as a prompt names them. */
56
+ function checkList(checks: readonly string[]): string {
57
+ return checks.map((command) => `\`${command}\``).join(", ");
58
+ }
59
+
60
+ /**
61
+ * How the two Stages that write code are told about the Checks, where the
62
+ * config names any; nothing where it names none.
63
+ *
64
+ * The pipeline runs them as soon as the Stage finishes, so a Stage that runs the
65
+ * whole suite while it works, and again after each change, pays for runs the
66
+ * pipeline is about to make anyway: in the logged Runs that was half of an
67
+ * implement Stage's wall clock. One run after its last commit still catches a
68
+ * failure before it spends the Fix budget. implement's comes after the review,
69
+ * because the review changes code in nearly every Stage.
70
+ */
71
+ function codeChecksLine(checks: readonly string[], afterReview: boolean): string {
72
+ if (checks.length === 0) return "";
73
+ const review = afterReview ? " That one run comes after the review's fixes are committed." : "";
74
+ return `\n- The pipeline runs its Checks as soon as you finish: ${checkList(checks)}. While you work, run only the tests your change touches. Commit, then run the full Checks once, in the foreground, and commit whatever that run makes you change.${review}`;
75
+ }
76
+
54
77
  /**
55
78
  * How the two Stages that write code are told to title the branch. The title is
56
79
  * an answer rather than a commit subject because a commit subject describes its
@@ -64,15 +87,17 @@ const titleGuidance = (base: string) =>
64
87
  * Guidance appended to every implement Stage, working around known defects of
65
88
  * the `implement` skill in an unattended session.
66
89
  */
67
- const implementGuidance = (base: string) => `This session is unattended. Follow this guidance as well as the skill's own:
90
+ const implementGuidance = (
91
+ base: string,
92
+ checks: readonly string[],
93
+ ) => `This session is unattended. Follow this guidance as well as the skill's own:
68
94
 
69
- - Confirm the Ticket title matches what you are about to build before you start.
70
95
  - Make an initial commit before running \`/mattpocock-skills:code-review\`, so the reviewed diff is not empty.
71
96
  ${titleGuidance(base)}
72
97
  - 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.
73
98
  - 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.
74
99
  - 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.
75
- - A later answer replaces an earlier one, so if you answer again, repeat every Note you still stand by.
100
+ - A later answer replaces an earlier one, so if you answer again, repeat every Note you still stand by.${codeChecksLine(checks, true)}
76
101
  ${FINISH_GUIDANCE}
77
102
  - Do not spawn nested review agents beyond what the skill itself does.
78
103
  - Do not open pull requests and do not close the issue; the pipeline does both.
@@ -83,10 +108,15 @@ ${FINISH_GUIDANCE}
83
108
  * things this Ticket is not about. Nothing here changes what the Stage is for:
84
109
  * it is the channel that stops a finding becoming either scope creep or a lost
85
110
  * paragraph in a transcript.
111
+ *
112
+ * A defect the branch itself introduced is the exception, and is said first:
113
+ * "another Ticket" alone left it unowned, and such Notes became bug issues
114
+ * opened after the branch that caused them had merged.
86
115
  */
87
116
  const notesGuidance = (standingNotes?: number) => `Notes for other Tickets: if you discover something that belongs to another Ticket, or to no Ticket yet, do not act on it here and do not widen this Ticket to cover it.
88
117
 
89
- - Record it as a Note instead. Your structured output carries a \`notes\` list, and the pipeline posts each entry where a human will meet it.
118
+ - ${OWN_DEFECT}: fix it, and do not record it as a Note.
119
+ - Record anything else as a Note instead. Your structured output carries a \`notes\` list, and the pipeline posts each entry where a human will meet it.
90
120
  ${noteEntryGuidance(standingNotes)}`;
91
121
 
92
122
  /**
@@ -142,32 +172,87 @@ function standingLine(standingNotes?: number): string {
142
172
  return `\n- Notes with no Ticket are gathered on #${standingNotes}. Read it first and take what it already records as recorded: write a second Note about a condition it names only when what you saw changes what a reader would do about it, and not when it is another instance of the same thing.`;
143
173
  }
144
174
 
145
- const VERIFY_INSTRUCTIONS = `You are the verify Stage of an unattended pipeline. Your job is adversarial: try to prove each Acceptance Criterion is NOT met.
175
+ /**
176
+ * What makes an unmet criterion one only a human can settle, in the words both
177
+ * the verify and the fix Stage are given.
178
+ */
179
+ const NEEDS_A_HUMAN =
180
+ "cannot be met without overturning a documented decision or another criterion";
181
+
182
+ /**
183
+ * The verify Stage's brief. It grades a commit the Checks have just passed, so
184
+ * where the config names any it is told so and told not to run them again: in
185
+ * the logged Runs re-running them was about two fifths of a verify Stage's wall
186
+ * clock, spent proving what the pipeline had already proved.
187
+ *
188
+ * A criterion that collides with a documented decision or another criterion is
189
+ * `unmet` with a human's decision as its evidence, rather than met on a
190
+ * workaround: the fix Stage it buys is told to commit nothing for it, which is
191
+ * what hands the question to a human.
192
+ */
193
+ const verifyInstructions = (checks: readonly string[]) => `You are the verify Stage of an unattended pipeline. Your job is adversarial: try to prove each Acceptance Criterion is NOT met.
146
194
 
147
195
  - Read the Ticket's Acceptance Criteria from its body and from its comments; the checkbox list may live in either.
148
196
  - Work in the checked-out branch, which already contains the implementation.
149
- - Attempt to falsify every criterion: run the code, run the tests, and write throwaway tests where that is the only way to tell.
197
+ - Attempt to falsify every criterion: run the code, run the tests that bear on it, and write throwaway tests where that is the only way to tell.${verifyChecksLine(checks)}
150
198
  - Judge the code as it is. Do not fix anything, and never commit, stage or push. Scratch files are fine; the pipeline discards them.
151
199
  - Mark a criterion \`unverifiable\` only when no evidence can be gathered, never as a substitute for looking.
200
+ - When a criterion ${NEEDS_A_HUMAN}, mark it \`unmet\` and say in its evidence that a human decision is needed, naming what it collides with. A workaround that sidesteps the collision does not meet it.
152
201
  - End by emitting the Verdict: one entry per criterion with its status and the evidence you actually gathered.`;
153
202
 
154
- const fixInstructions = (base: string) => `You are the fix Stage of an unattended pipeline. The Ticket below is already implemented on the branch you are on, and one gate failed. You are what its fix budget bought, and the budget is spent: a second failure of any kind hands the Ticket to a human.
203
+ /** The Checks as the verify Stage is told about them: passed, and not its to run. */
204
+ function verifyChecksLine(checks: readonly string[]): string {
205
+ if (checks.length === 0) return "";
206
+ return `\n- The pipeline's Checks passed on this commit: ${checkList(checks)}. Do not re-run them: grade a criterion that asks only for them from that fact, and spend your turns on targeted tests and probes.`;
207
+ }
208
+
209
+ /**
210
+ * The fix Stage's brief. Sent in for unmet criteria, it is told what to do when
211
+ * one of them needs a human decision: commit nothing, which hands the Ticket to
212
+ * a human with the criteria and their evidence. Left to itself it worked around
213
+ * every such criterion it met, and the verify behind it passed the workaround.
214
+ */
215
+ const fixInstructions = (
216
+ base: string,
217
+ kind: FailureKind,
218
+ checks: readonly string[],
219
+ ) => `You are the fix Stage of an unattended pipeline. The Ticket below is already implemented on the branch you are on, and one gate failed. You are what its fix budget bought, and the budget is spent: a second failure of any kind hands the Ticket to a human.
155
220
 
156
221
  - Commit your fix on the branch you are on, in this worktree. Do not create a branch, do not open pull requests, and do not close the Ticket.
157
222
  - Start from the evidence: reproduce the failure, find what actually causes it, and fix that rather than the symptom.
158
- - Where the failure is an unmet Acceptance Criterion, add the regression test that would have caught it and commit it with the fix.
159
- - Stay inside this Ticket's Acceptance Criteria. Anything else you find belongs to another Ticket, not to this session; record it as a Note rather than mending it.
223
+ - Where the failure is an unmet Acceptance Criterion, add the regression test that would have caught it and commit it with the fix.${kind === "unmet-criteria" ? HUMAN_DECISION_LINE : ""}
224
+ - Stay inside this Ticket's Acceptance Criteria and the defects this branch introduced. Anything else you find belongs to another Ticket, not to this session; record it as a Note rather than mending it.${codeChecksLine(checks, false)}
160
225
  ${FINISH_GUIDANCE}
161
226
  - Write commit subjects in the convention \`${CONVENTIONS_PATH}\` states. The pipeline re-runs the Checks and the verify Stage as soon as you finish.
162
227
  ${titleGuidance(base)}`;
163
228
 
164
- const conflictInstructions = (base: string) => `You are the conflict Stage of an unattended pipeline. The Ticket below is already implemented on the branch you are on, and rebasing it onto \`${base}\` stopped on a conflict. That rebase is still in progress in this worktree, and finishing it is the whole of your job.
229
+ /** What the fix Stage sent in for unmet criteria does with one only a human can settle. */
230
+ const HUMAN_DECISION_LINE = `
231
+ - When any unmet criterion ${NEEDS_A_HUMAN}, as the verify Stage's evidence may already say, commit nothing and say why in your last message. Do not work around it: a fix Stage that commits nothing hands the Ticket to a human, with the unmet criteria and their evidence.`;
232
+
233
+ /**
234
+ * The conflict Stage's brief. It may reach past the conflicted files only to
235
+ * repair what the merge broke there, such as a name the Base branch renamed:
236
+ * a Stage that left those red would spend the Fix budget on them. Nothing it
237
+ * does may change behaviour the criteria cover, because verify does not run
238
+ * again after it.
239
+ */
240
+ const conflictInstructions = (
241
+ base: string,
242
+ checks: readonly string[],
243
+ ) => `You are the conflict Stage of an unattended pipeline. The Ticket below is already implemented on the branch you are on, and rebasing it onto \`${base}\` stopped on a conflict. That rebase is still in progress in this worktree, and finishing it is the whole of your job.
165
244
 
166
245
  - Resolve every hunk and carry the rebase through to the end; never \`git rebase --abort\`, and never rewind the branch to escape the conflict.
167
246
  - Where the two sides are compatible, keep both intents. Where they are not, keep the behaviour this Ticket's Acceptance Criteria ask for, and keep \`${base}\`'s everywhere the Ticket is silent.
168
- - Resolve, do not redesign. Implement nothing new, and touch no file the conflict did not.
247
+ - Resolve, do not redesign. Change a file the conflict did not touch only to repair what the merge itself broke, such as a renamed name or a moved field. Implement nothing new, and change no behaviour this Ticket's Acceptance Criteria cover: verify does not grade the branch again after you.
169
248
  - Leave no conflict marker behind in any file, committed or not.
170
- - Do not push, do not open pull requests, and do not close the Ticket. The pipeline runs the Checks again as soon as you finish, and a failure there spends this Ticket's fix budget.`;
249
+ - Do not push, do not open pull requests, and do not close the Ticket.${conflictChecksLine(checks)}`;
250
+
251
+ /** The Checks as the conflict Stage is told about them: the pipeline's to run in full. */
252
+ function conflictChecksLine(checks: readonly string[]): string {
253
+ if (checks.length === 0) return "";
254
+ return `\n- The pipeline runs its Checks as soon as you finish, and a failure there spends this Ticket's fix budget: ${checkList(checks)}. Run the type checker and the tests covering the files you resolved, not the whole suite.`;
255
+ }
171
256
 
172
257
  /** How the fix prompt announces each kind of failure. */
173
258
  const failureSentences = (base: string): Record<FailureKind, string> => ({
@@ -194,27 +279,38 @@ export function implementPrompt(
194
279
  base: string,
195
280
  extraPrompt: string,
196
281
  selfHosted: boolean,
282
+ checks: readonly string[],
197
283
  standingNotes?: number,
198
284
  ): string {
199
285
  return sections([
200
286
  `/mattpocock-skills:implement ${issueUrl}`,
201
- implementGuidance(base),
287
+ implementGuidance(base, checks),
202
288
  stageBoundary(selfHosted),
203
289
  notesGuidance(standingNotes),
204
290
  extraPrompt,
205
291
  ]);
206
292
  }
207
293
 
208
- /** A fresh session with no plugin skill, graded against the Verdict schema. */
294
+ /**
295
+ * A fresh session with no plugin skill, graded against the Verdict schema.
296
+ *
297
+ * `unmetBefore` is the evidence of the Verdict a fix Stage was sent in for, in
298
+ * the same Run; a first verify has none. Without it the verify behind a fix
299
+ * graded the fix on its own terms, and passed a caveat the first one had
300
+ * counted as unmet.
301
+ */
209
302
  export function verifyPrompt(
210
303
  issueUrl: string,
211
304
  extraPrompt: string,
212
305
  selfHosted: boolean,
306
+ checks: readonly string[],
213
307
  standingNotes?: number,
308
+ unmetBefore?: string,
214
309
  ): string {
215
310
  return sections([
216
311
  `Ticket: ${issueUrl}`,
217
- VERIFY_INSTRUCTIONS,
312
+ verifyInstructions(checks),
313
+ unmetBefore === undefined ? "" : unmetBeforeSection(unmetBefore),
218
314
  stageBoundary(selfHosted),
219
315
  verifyNotesGuidance(standingNotes),
220
316
  extraPrompt,
@@ -228,10 +324,11 @@ export function conflictPrompt(
228
324
  base: string,
229
325
  extraPrompt: string,
230
326
  selfHosted: boolean,
327
+ checks: readonly string[],
231
328
  ): string {
232
329
  return sections([
233
330
  `Ticket: ${issueUrl}`,
234
- conflictInstructions(base),
331
+ conflictInstructions(base, checks),
235
332
  outputSection("## Where the rebase stopped", conflict),
236
333
  stageBoundary(selfHosted),
237
334
  extraPrompt,
@@ -245,11 +342,12 @@ export function fixPrompt(
245
342
  base: string,
246
343
  extraPrompt: string,
247
344
  selfHosted: boolean,
345
+ checks: readonly string[],
248
346
  standingNotes?: number,
249
347
  ): string {
250
348
  return sections([
251
349
  `Ticket: ${issueUrl}`,
252
- fixInstructions(base),
350
+ fixInstructions(base, failure.kind, checks),
253
351
  failureSection(failure, base),
254
352
  stageBoundary(selfHosted),
255
353
  notesGuidance(standingNotes),
@@ -266,6 +364,15 @@ function failureSection({ kind, summary, evidence }: FixFailure, base: string):
266
364
  );
267
365
  }
268
366
 
367
+ /** The unmet criteria a fix Stage was sent in for, and what meeting them now takes. */
368
+ function unmetBeforeSection(evidence: string): string {
369
+ return outputSection(
370
+ "## Judged unmet before the fix",
371
+ evidence,
372
+ "The verify Stage before you judged these criteria unmet, with this evidence, and a fix Stage has worked on the branch since. Such a criterion is met only when that counterexample is gone and the whole criterion holds: a fix that answers the evidence but not the rest of the criterion, or a caveat in place of the behaviour, leaves it `unmet`.",
373
+ );
374
+ }
375
+
269
376
  /**
270
377
  * A heading, an optional line of prose, and raw command output. The output is
271
378
  * fenced because it would otherwise be read as Markdown.
package/src/readiness.ts CHANGED
@@ -4,6 +4,7 @@ import type { Labels } from "./config.js";
4
4
  import { CLAUDE_SECTION, CONVENTIONS_PATH, conventionsMark } from "./conventions.js";
5
5
  import { OPERATOR_SKILL_PATH } from "./operator-skill.js";
6
6
  import type { Authentication, Tracker } from "./ports/tracker.js";
7
+ import type { Workspace } from "./ports/workspace.js";
7
8
 
8
9
  /**
9
10
  * What `ticket-runner init` must have left in a Target before a Run may start.
@@ -22,17 +23,26 @@ import type { Authentication, Tracker } from "./ports/tracker.js";
22
23
  * Version it names: an Operator installs the pipeline a cloud Host runs at that
23
24
  * Version, and a Target without one leaves it guessing (ADR-0008).
24
25
  *
25
- * The Target's own files are read here rather than through a port, which every
26
+ * The checkout's files are read here rather than through a port, which every
26
27
  * external effect of a Run goes through. What a port buys is a fake to drive the
27
- * state machine with, and there is no state machine here: this is five questions
28
+ * state machine with, and there is no state machine here: these are questions
28
29
  * asked of a directory before a Run exists, and the answers are already driven
29
30
  * from a temporary repository root, which is how the local state under
30
- * `.ticket-runner/` is tested too (ADR-0004). Widening the `Workspace` port for
31
- * them would put reads no Stage and no Ticket ever makes on the interface the
32
- * orchestrator depends on.
31
+ * `.ticket-runner/` is tested too (ADR-0004).
32
+ *
33
+ * The same files on the remote's Base branch are the one exception, read
34
+ * through `Workspace` like every other question about the remote: every
35
+ * Ticket's worktree is made from that branch, so a file `init` wrote and nobody
36
+ * pushed is in the checkout and in no Stage's worktree. The conventions
37
+ * document, the `CLAUDE.md` pointer and the Operator's skill are asked of it
38
+ * the same way they are asked of the checkout. The gitignore lines are not:
39
+ * the directories they cover exist only in the main checkout, and only its
40
+ * copy takes effect there.
33
41
  *
34
42
  * Every item is asked on every Host, the cloud's own needs included, so a
35
- * Target a workstation accepts is never one a cloud Run then refuses.
43
+ * Target a workstation accepts is never one a cloud Run then refuses. A cloud
44
+ * Host's checkout is a clone of the remote, so there the remote's answers are
45
+ * the checkout's.
36
46
  */
37
47
 
38
48
  /** The file every agent session in a Target reads first. */
@@ -148,6 +158,10 @@ export interface ReadinessOptions {
148
158
  * is refused without a network call at all. Whether `gh` is there to ask comes
149
159
  * next, so a Host without it is refused in words rather than with the spawn
150
160
  * error the first label lookup would crash on.
161
+ *
162
+ * What the remote's Base branch lacks is asked after all of these, by
163
+ * {@link unpushedRefusal}, once the Run has resolved which branch that is: the
164
+ * lookup may ask GitHub, which only a `gh` that runs can.
151
165
  */
152
166
  export async function readinessRefusal({
153
167
  repoRoot,
@@ -155,7 +169,7 @@ export async function readinessRefusal({
155
169
  tracker,
156
170
  }: ReadinessOptions): Promise<string | undefined> {
157
171
  const missing =
158
- missingFileMessage(repoRoot) ??
172
+ (await missingFileMessage(repoRoot)) ??
159
173
  (await missingGhMessage(tracker)) ??
160
174
  (await missingLabelMessage(tracker, labels)) ??
161
175
  (await missingBranchDeletionMessage(tracker));
@@ -168,14 +182,56 @@ export async function readinessRefusal({
168
182
  ].join(" ");
169
183
  }
170
184
 
185
+ export interface UnpushedOptions {
186
+ workspace: Pick<Workspace, "remote" | "readRemoteFile">;
187
+ /** The Run's Base branch, resolved once and carried on into the Run. */
188
+ baseBranch: string;
189
+ }
190
+
191
+ /**
192
+ * The message a Run is refused with when the remote's Base branch lacks a file
193
+ * the checkout has, and nothing when it has them all.
194
+ *
195
+ * Asked once {@link readinessRefusal} has found nothing missing, so a Target
196
+ * that never ran `init` is told to run it and only one that did is told to
197
+ * push. A Base branch the remote does not have lacks every file. The remedy is
198
+ * a commit and a push, which `init` leaves to the human, so this names no
199
+ * command of the pipeline's.
200
+ */
201
+ export async function unpushedRefusal({
202
+ workspace,
203
+ baseBranch,
204
+ }: UnpushedOptions): Promise<string | undefined> {
205
+ const remoteBase = `${workspace.remote}/${baseBranch}`;
206
+ const missing = await missingItemMessage((path) => workspace.readRemoteFile(baseBranch, path));
207
+ if (missing === undefined) return undefined;
208
+
209
+ return [
210
+ `This Target's \`${remoteBase}\` is not set up: ${missing}.`,
211
+ `Every Ticket's worktree is made from \`${remoteBase}\`, not from this checkout:`,
212
+ "commit and push what `init` wrote there, then start again.",
213
+ ].join(" ");
214
+ }
215
+
171
216
  /** Names the first thing `init` writes into a Target that this one does not have. */
172
- function missingFileMessage(repoRoot: string): string | undefined {
217
+ async function missingFileMessage(repoRoot: string): Promise<string | undefined> {
173
218
  const [unignored] = missingIgnoreLines(repoRoot);
174
219
  if (unignored !== undefined) {
175
220
  return `\`.gitignore\` does not ignore \`${unignored.line}\``;
176
221
  }
177
222
 
178
- const conventions = readTargetFile(join(repoRoot, CONVENTIONS_PATH));
223
+ return missingItemMessage(async (path) => readTargetFile(join(repoRoot, path)));
224
+ }
225
+
226
+ /**
227
+ * Names the first of the items both the checkout and the remote's Base branch
228
+ * must carry that `read` does not find, asking each the same question in both
229
+ * places. Where it was asked is the refusal's to say.
230
+ */
231
+ async function missingItemMessage(
232
+ read: (path: string) => Promise<string | undefined>,
233
+ ): Promise<string | undefined> {
234
+ const conventions = await read(CONVENTIONS_PATH);
179
235
  if (conventions === undefined) {
180
236
  return `\`${CONVENTIONS_PATH}\` is not there`;
181
237
  }
@@ -183,13 +239,13 @@ function missingFileMessage(repoRoot: string): string | undefined {
183
239
  return `\`${CONVENTIONS_PATH}\` carries no Version`;
184
240
  }
185
241
 
186
- if (!hasClaudePointer(readTargetFile(join(repoRoot, CLAUDE_FILENAME)))) {
242
+ if (!hasClaudePointer(await read(CLAUDE_FILENAME))) {
187
243
  return `\`${CLAUDE_FILENAME}\` does not point at \`${CONVENTIONS_PATH}\``;
188
244
  }
189
245
 
190
246
  // Asked of a workstation too, though only a cloud session reads it: a Target
191
247
  // a local Run accepts is then one the app can run as well (ADR-0008).
192
- if (readTargetFile(join(repoRoot, OPERATOR_SKILL_PATH)) === undefined) {
248
+ if ((await read(OPERATOR_SKILL_PATH)) === undefined) {
193
249
  return `the Operator's skill \`${OPERATOR_SKILL_PATH}\` is not there`;
194
250
  }
195
251
 
package/src/resume.ts CHANGED
@@ -11,10 +11,10 @@ import { REACHED_STATES, type StateFile, type TicketState } from "./ports/worksp
11
11
  * resuming, so it is written as part of the Claim and rewritten whenever the
12
12
  * Ticket reaches something a later Run should not pay for again. Three Runs read
13
13
  * it, and what the board says decides which. One finds a Ticket the subscription
14
- * rate limit released: nothing was wrong with it, so the Claim came off and this
15
- * file says where to carry on from. One finds a Ticket still claimed — the Run
16
- * that claimed it was killed and never released anything — and resumes it in
17
- * place. One finds a Ticket a human was handed and has relabelled
14
+ * rate limit or a transient API failure released: nothing was wrong with it, so
15
+ * the Claim came off and this file says where to carry on from. One finds a
16
+ * Ticket still claimed — the Run that claimed it was killed and never released
17
+ * anything — and resumes it in place. One finds a Ticket a human was handed and has relabelled
18
18
  * `ready-for-agent`, which is the human handing it back. A Ticket still sitting
19
19
  * in `ready-for-human` is none of them: its file is inert until a human moves
20
20
  * the label or the issue closes.
@@ -35,6 +35,7 @@ const stateSchema = z.object({
35
35
  fixUsed: z.boolean(),
36
36
  pullRequest: z.number().int().positive().optional(),
37
37
  title: z.string().optional(),
38
+ rebaseFirst: z.boolean().optional(),
38
39
  runId: z.string(),
39
40
  version: z.string().optional(),
40
41
  updatedAt: z.string(),
@@ -79,13 +80,14 @@ export function readStateFile(contents: string, ticket: number): StateFile {
79
80
  // older pipeline never wrote, are keys that are not there rather than keys
80
81
  // holding nothing: the rest of the pipeline reads these with the same
81
82
  // distinction.
82
- const { pullRequest, title, version, ...state } = parsed.data;
83
+ const { pullRequest, title, rebaseFirst, version, ...state } = parsed.data;
83
84
  return {
84
85
  readable: true,
85
86
  state: {
86
87
  ...state,
87
88
  ...(pullRequest === undefined ? {} : { pullRequest }),
88
89
  ...(title === undefined ? {} : { title }),
90
+ ...(rebaseFirst === undefined ? {} : { rebaseFirst }),
89
91
  ...(version === undefined ? {} : { version }),
90
92
  },
91
93
  };