ticket-runner 0.6.4 → 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.
Files changed (50) hide show
  1. package/README.ko.md +5 -5
  2. package/README.md +4 -4
  3. package/docs/templates/operator-skill.md +81 -16
  4. package/package.json +1 -1
  5. package/src/acceptance-criteria.ts +99 -2
  6. package/src/adapters/claude-agent-runner.ts +5 -5
  7. package/src/adapters/exec.ts +32 -4
  8. package/src/adapters/gh-tracker.ts +276 -60
  9. package/src/adapters/git-workspace.ts +27 -10
  10. package/src/adapters/liveness.ts +77 -0
  11. package/src/adapters/process-tree.ts +4 -7
  12. package/src/adapters/version.ts +5 -5
  13. package/src/branch.ts +1 -1
  14. package/src/cli.ts +2 -2
  15. package/src/config.ts +22 -4
  16. package/src/conventions.ts +22 -19
  17. package/src/credential.ts +14 -13
  18. package/src/criteria.ts +102 -52
  19. package/src/failing-base.ts +7 -7
  20. package/src/failure-message.ts +72 -0
  21. package/src/guards.ts +21 -6
  22. package/src/handoff.ts +2 -2
  23. package/src/init.ts +8 -8
  24. package/src/landing.ts +1 -1
  25. package/src/lifecycle.ts +2 -2
  26. package/src/lock.ts +10 -2
  27. package/src/note-schema.ts +14 -11
  28. package/src/notes.ts +19 -7
  29. package/src/operator-skill.ts +2 -2
  30. package/src/orchestrator.ts +758 -275
  31. package/src/outside-fault.ts +103 -0
  32. package/src/ports/agent-runner.ts +1 -1
  33. package/src/ports/tracker.ts +29 -15
  34. package/src/ports/workspace.ts +52 -24
  35. package/src/progress.ts +42 -7
  36. package/src/prompts.ts +242 -34
  37. package/src/readiness.ts +11 -11
  38. package/src/remove.ts +7 -7
  39. package/src/resume.ts +28 -20
  40. package/src/run-log.ts +5 -5
  41. package/src/run.ts +55 -13
  42. package/src/staleness.ts +14 -14
  43. package/src/start.ts +29 -16
  44. package/src/stranded.ts +19 -19
  45. package/src/templates.ts +398 -149
  46. package/src/title.ts +106 -8
  47. package/src/transcript-home.ts +49 -0
  48. package/src/verdict.ts +132 -27
  49. package/src/version-number.ts +13 -13
  50. package/src/version-pr.ts +12 -12
package/README.ko.md CHANGED
@@ -13,7 +13,7 @@
13
13
 
14
14
  체인은 둘로 나뉩니다. **Planning**은 사람 몫입니다. `/grilling`, `/to-spec`, `/to-tickets`(또는
15
15
  `/triage`)로 기능 하나를 작은 GitHub 이슈 여러 개로 나눕니다. 이슈마다 `ready-for-agent` 라벨과
16
- Acceptance Criteria 체크리스트가 달리고, blocker가 연결됩니다. **Execution**은 파이프라인 몫입니다.
16
+ Acceptance Criteria 체크리스트가 달리고, blocker가 연결됩니다. **실행**은 파이프라인 몫입니다.
17
17
  그런 이슈 가운데 blocker가 모두 닫힌 것마다 다음을 합니다.
18
18
 
19
19
  1. 이슈를 맡고, 그 이슈의 branch와 git worktree를 만듭니다.
@@ -37,10 +37,10 @@ Acceptance Criteria 체크리스트가 달리고, blocker가 연결됩니다. **
37
37
  설정해 두었고, Ticket 하나는 세션 하나로 끝낼 만큼 작습니다.
38
38
  - pull request에서 도는 CI 워크플로가 있고, 파이프라인이 직접 돌릴 테스트나 typecheck 명령이 있습니다.
39
39
  - 돌리는 머신에 Node 22 이상, `git`, 인증된 [`gh`](https://cli.github.com/), 그리고
40
- [`mattpocock-skills`](https://github.com/mattpocock/skills) 플러그인 1.2.3 이상 버전을 설치한 `claude`가
40
+ [`mattpocock-skills`](https://github.com/mattpocock/skills) 플러그인 1.3.0 이상 버전을 설치한 `claude`가
41
41
  있습니다.
42
42
 
43
- 파이프라인은 묻지 않고 Base branch에 merge합니다. 그걸 원하는 저장소에 쓰세요.
43
+ 파이프라인은 묻지 않고 base branch에 merge합니다. 그걸 원하는 저장소에 쓰세요.
44
44
 
45
45
  ## 써 보기
46
46
 
@@ -55,7 +55,7 @@ npx ticket-runner run # 준비된 이슈를 모두 처리합니다
55
55
 
56
56
  `init`은 검토하고 commit할 파일 몇 개를 씁니다. `.gitignore` 줄, conventions 문서, `CLAUDE.md`의 한
57
57
  섹션, Claude skill 하나입니다. 또 triage 라벨을 만들고, squash merge와 merge 시 branch 삭제를 켭니다.
58
- commit은 하지 않습니다. 세션은 이 파일들이 Base branch에 올라간 뒤에야 읽으므로, 첫 `run` 전에
58
+ commit은 하지 않습니다. 세션은 이 파일들이 base branch에 올라간 뒤에야 읽으므로, 첫 `run` 전에
59
59
  push하세요.
60
60
 
61
61
  계속 쓰려면 전역으로 설치하세요.
@@ -73,7 +73,7 @@ npm install -g ticket-runner
73
73
  | `ticket-runner run --api-key` | 모든 세션을 Claude 요금제 대신 `ANTHROPIC_API_KEY`로 과금합니다. |
74
74
  | `ticket-runner stop` | 진행 중인 Run에게 맡은 것만 끝내고 더 맡지 말라고 합니다. |
75
75
  | `ticket-runner remove` | 이 저장소에서 파이프라인을 걷어 냅니다. |
76
- | `ticket-runner -v` | Version을 출력합니다. |
76
+ | `ticket-runner -v` | 버전을 출력합니다. |
77
77
 
78
78
  Claude 앱에서도 Run을 시작할 수 있습니다. Target에서 Claude Code 클라우드 세션을 열고 "run it"이라고
79
79
  말하면 됩니다. 클라우드 세션은 늘 요금제로 돌기 때문에 `--api-key`를 거절합니다.
package/README.md CHANGED
@@ -40,9 +40,9 @@ It fits a repository where:
40
40
  run itself
41
41
  - the machine running it has Node 22 or newer, `git`, an authenticated
42
42
  [`gh`](https://cli.github.com/), and `claude` with the
43
- [`mattpocock-skills`](https://github.com/mattpocock/skills) plugin, version 1.2.3 or later
43
+ [`mattpocock-skills`](https://github.com/mattpocock/skills) plugin, version 1.3.0 or later
44
44
 
45
- It merges to your Base branch without asking. It is for repositories where that is what you want.
45
+ It merges to your base branch without asking. It is for repositories where that is what you want.
46
46
 
47
47
  ## Try it
48
48
 
@@ -58,7 +58,7 @@ npx ticket-runner run # work through every ready issue
58
58
  `init` writes a few files for you to review and commit: `.gitignore` lines, a conventions
59
59
  document, a section in `CLAUDE.md` and a Claude skill. It also creates the triage labels and
60
60
  turns on squash merging and branch deletion on merge. It commits nothing, and a session reads
61
- those files only once they are on your Base branch, so push them before the first `run`.
61
+ those files only once they are on your base branch, so push them before the first `run`.
62
62
 
63
63
  To keep it, install it globally:
64
64
 
@@ -75,7 +75,7 @@ npm install -g ticket-runner
75
75
  | `ticket-runner run --api-key` | Bill every session to your `ANTHROPIC_API_KEY`, not your Claude plan |
76
76
  | `ticket-runner stop` | Ask the Run in progress to finish what it holds and take no more |
77
77
  | `ticket-runner remove` | Take the pipeline out of this repository |
78
- | `ticket-runner -v` | Print the Version |
78
+ | `ticket-runner -v` | Print the version |
79
79
 
80
80
  A Run can also be started from the Claude app, in a Claude Code cloud session on the Target:
81
81
  say "run it". A cloud session always runs on your plan, so it refuses `--api-key`.
@@ -1,25 +1,25 @@
1
1
  ---
2
2
  name: ticket-runner
3
- description: Operate ticket-runner on this repository from a Claude Code cloud session — ready the Host, start a Run in the background, narrowed to the Tickets the human names when they name any, report what it prints, pass on a Stop, and release a Run lock a vanished Host left behind. Use when the human asks to run the pipeline ("run it"), to work particular Tickets, to stop the Run, or to release its lock. Never from a Stage.
3
+ description: Operate ticket-runner on this repository from a Claude Code cloud session — ready the Host (the machine the pipeline runs on), start a Run (one invocation of the pipeline) detached from the session's shell, narrowed to the Tickets (GitHub issues each sized for one session of work) the human names when they name any, watch its log and report each Ticket as it ends, pass on a Stop (the human's request that a Run finish the Tickets it holds and take no more), release a Run lock a vanished Host left behind, and, while no Run holds this repository, carry the human's decision on a handed-off Ticket (one given to a human to carry on) to the board when they ask. Use when the human asks to run the pipeline ("run it"), to work particular Tickets, to stop the Run, to release its lock, or to put a handed-off Ticket back for a Run. Never from a Stage (a Claude Code session a Run started for a single purpose).
4
4
  ---
5
5
 
6
6
  # Operating ticket-runner
7
7
 
8
- You are the Operator: the Claude session a human opened on this repository to run `ticket-runner` for them, and to watch and steer it from the app. You start the Run, report what it prints, pass on a Stop, and release a lock when asked. Nothing else. The Run does the work, and everything else a human wants of a Ticket goes through the board.
8
+ You are the Operator: the Claude session a human opened on this repository to run `ticket-runner` for them, and to watch and steer it from the app. You start the Run, report the Tickets it ends, pass on a Stop, and release a lock when asked. While no Run holds this repository, you also carry the human's decision on a handed-off Ticket to the board when they ask, in the three ways [The board while no Run holds it](#the-board-while-no-run-holds-it) lists. Nothing else. The Run does the work, and everything else a human wants of a Ticket goes through the board by their own hand.
9
9
 
10
10
  If `TICKET_RUNNER_STAGE` is set in your shell, you are a Stage of a Run, not an Operator. Stop here and use none of this.
11
11
 
12
12
  ## Ready the Host
13
13
 
14
- Install only what this Host does not already have. What the cloud environment's setup script installed is used as it is, whichever Version it is.
14
+ Install only what this Host does not already have. What the cloud environment's setup script installed is used as it is, whichever version it is.
15
15
 
16
- 1. The pipeline. If `ticket-runner --version` answers, use that copy. Otherwise read the Version on the first line of `docs/agents/pipeline-conventions.md`, the `<number>` in `<!-- ticket-runner:version <number> -->`, and install that Version:
16
+ 1. The pipeline. If `ticket-runner --version` answers, use that copy. Otherwise read the version on the first line of `docs/agents/pipeline-conventions.md`, the `<number>` in `<!-- ticket-runner:version <number> -->`, and install that version:
17
17
 
18
18
  ```bash
19
19
  npm install -g ticket-runner@<number>
20
20
  ```
21
21
 
22
- If the first line carries no Version, install nothing and tell the human to run `ticket-runner init` on this repository from a workstation.
22
+ If the first line carries no version, install nothing and tell the human to run `ticket-runner init` on this repository from a workstation.
23
23
 
24
24
  2. The skills plugin. If `claude plugin list` lists `mattpocock-skills`, it is there. Otherwise register the official marketplace first, then install the plugin from it:
25
25
 
@@ -35,32 +35,77 @@ Install only what this Host does not already have. What the cloud environment's
35
35
  apt-get install -y gh
36
36
  ```
37
37
 
38
- The `gh` apt offers is older than GitHub's own, and enough: the pipeline reaches GitHub through `gh api` alone. If the install fails, start nothing and tell the human what apt printed: a Run started without `gh` is refused as a Target that is not set up, saying only that `gh` is not installed and must be installed first.
38
+ The `gh` apt offers is older than GitHub's own, and enough: the pipeline reaches GitHub through `gh api` alone. If the install fails, start nothing and tell the human what apt printed: a Run started without `gh` is refused, because its Target, the repository a Run takes its work from and merges into, is not set up, saying only that `gh` is not installed and must be installed first.
39
39
 
40
- 4. This repository's own dependencies, in this checkout. Every Ticket's worktree lives inside this checkout, and a Check that finds nothing installed in its worktree uses what is installed here, so without them every Check fails to start and spends its Ticket's fix budget on that. If they are installed here already, `node_modules/` beside a `package.json` for instance, use them as they are. Otherwise work out the install command from what this repository declares, its lockfile first and then its README or contributing guide, and run it at the root of this checkout: `npm ci` beside a `package-lock.json`, say. A repository that declares no dependencies needs nothing here. If the install fails, start nothing and tell the human what the install printed.
40
+ 4. This repository's own dependencies, in this checkout. Every Ticket's worktree lives inside this checkout, and a Check, a command the pipeline runs itself on a Ticket's code to gate it, such as its tests, uses what is installed here when it finds nothing installed in its worktree. Without them every Check fails to start and spends its Ticket's fix budget, the fix Stages it is allowed, on that. If they are installed here already, `node_modules/` beside a `package.json` for instance, use them as they are. Otherwise work out the install command from what this repository declares, its lockfile first and then its README or contributing guide, and run it at the root of this checkout: `npm ci` beside a `package-lock.json`, say. A repository that declares no dependencies needs nothing here. If the install fails, start nothing and tell the human what the install printed.
41
41
 
42
42
  Tell the human in one line which of these you installed, this repository's dependencies included, or that nothing was missing.
43
43
 
44
44
  ## Start
45
45
 
46
- Start what the human asked for as a background command, so the session stays free to answer them while it runs:
46
+ Start what the human asked for detached from your shell, with its output going to a log file, so it runs for as long as it needs and the session stays free to answer them. Give it no timeout, and never start it as a background command: one with a time limit is killed when the limit runs out, in the middle of a Ticket, and leaves the lock held and no summary.
47
47
 
48
- - `ticket-runner run` to work through every Ticket that is ready.
49
- - `ticket-runner run <n>...` when the human names Tickets, one number each. The Run takes only those, lowest number first whatever order they were named in, and leaves every other Ticket alone.
50
- - `ticket-runner run --lanes <count>` when the human asks for a number of Tickets at once, with or without numbers. Pass it only when they do; otherwise the repository's own config decides.
51
- - `ticket-runner run --api-key` when the human asks for the Run to bill their API key rather than their Claude plan, beside numbers or `--lanes` or without. Pass it only when they do. Tell them an API-key Run needs a workstation Host: a cloud Host refuses it, because a cloud session runs every Stage on the subscription whatever key it exports.
48
+ What goes in place of `<arguments>` below:
49
+
50
+ - Nothing, to work through every Ticket that is ready.
51
+ - `<n>...` when the human names Tickets, one number each. The Run takes only those, lowest number first whatever order they were named in, and leaves every other Ticket alone.
52
+ - `--lanes <count>` when the human asks for a number of Tickets at once, with or without numbers. Pass it only when they do; otherwise the repository's own config decides.
53
+ - `--api-key` when the human asks for the Run to bill their API key rather than their Claude plan, beside numbers or `--lanes` or without. Pass it only when they do. Tell them an API-key Run needs a workstation Host: a cloud Host refuses it, because a cloud session runs every Stage on the subscription whatever key it exports.
54
+
55
+ ```bash
56
+ mkdir -p .ticket-runner
57
+ rm -f .ticket-runner/run.pid
58
+ setsid sh -c 'echo $$ > .ticket-runner/run.pid; ticket-runner run "$@"; echo "ticket-runner exited with $?"' sh <arguments> > .ticket-runner/run.log 2>&1 < /dev/null &
59
+ until [ -s .ticket-runner/run.pid ]; do sleep 1; done
60
+ ```
61
+
62
+ The log's last line is then the exit line, `ticket-runner exited with <code>`, written once the Run has ended. `.ticket-runner/` is ignored by git, so the log touches nothing the Run pulls. `ticket-runner stop` still finds the Run, through the pid its lock names.
52
63
 
53
64
  Start one at a time. While a Run of yours is running, start no other.
54
65
 
66
+ ## Watch
67
+
68
+ Watch the log with your tool that streams to you each line a command prints, running this command with `from` set to the first line to read:
69
+
70
+ ```bash
71
+ from=1
72
+ tail -n "+$from" -F --pid="$(cat .ticket-runner/run.pid)" .ticket-runner/run.log 2>/dev/null |
73
+ awk -v n="$from" '
74
+ /^ticket-runner [0-9][^ ]* run / { summary = 1 }
75
+ summary || !/^#[0-9]+ (claimed|resumed from|taken from the top|verified ·|fixing ·|rebased onto|resolving a rebase conflict|noted on #)/ { print n ": " $0; fflush() }
76
+ { n++ }'
77
+ ```
78
+
79
+ It shows each line it reads with that line's number in the log, except the progress lines: a Ticket claimed (resumed, or taken from the top), verified, fixing, rebased, resolving a rebase conflict, or noted on. From the summary's header on, it shows every line. It exits by itself once the Run has ended and the exit line has arrived.
80
+
81
+ When the watch expires before that, arm it again at once with `from` one past the number of the last line it showed, and say nothing to the human about it. Arm one watch at a time, and none once the exit line has come.
82
+
55
83
  ## Report
56
84
 
57
- Report what the Run prints as it prints it, in a form a phone screen reads: one short line per Ticket that ended, saying which Ticket and whether it merged, was handed off, was released or was skipped, and why when the Run gives a reason. Pass on a refusal as it is worded: it names what to do.
85
+ Report what the watch shows, in a form a phone screen reads:
58
86
 
59
- When the Run ends, report its summary and what its exit code means: `1` at least one Ticket was handed off to a human, `2` nothing was taken at all, because the Run was refused or because it was given Ticket numbers and took none of them, every one skipped or blocked, and `0` otherwise.
87
+ - One short line per Ticket that ended, saying which Ticket and whether it merged, was handed off (given to a human to carry on), was released (given back for a later Run to take up again) or was skipped, and why when the Run gives a reason.
88
+ - Any other line it shows, as it is worded: a refusal, which names what to do, the line saying a Release, or a hand-off GitHub or the remote cut short, stopped the Run, the Tickets a Stop left to finish, a warning.
89
+
90
+ Say nothing about a line the watch did not show, and nothing when you arm it again.
91
+
92
+ When the exit line arrives, report the summary, what the exit code means, and how many Notes the Run posted: defects a Stage met that belong to another Ticket or to none yet, posted on GitHub where a human will find them instead of being fixed there, one `noted` row each in the summary. Its exit code is `1` when at least one Ticket was handed off to a human, `2` when nothing was taken at all, because the Run was refused or because it was given Ticket numbers and took none of them, every one skipped or blocked, and `0` otherwise.
60
93
 
61
94
  ## Stop
62
95
 
63
- When the human asks for a Stop, send the Run SIGTERM by running `ticket-runner stop`, which signals the Run this Host holds the lock for. Report what it prints, then keep reporting the Run: a Stop finishes the Tickets the Run already holds and takes no more, so the Run ends by itself with its summary, whether or not it was given Ticket numbers. Never end a Run any other way. SIGINT or SIGKILL ends it in the middle of a Ticket.
96
+ When the human asks for a Stop, send the Run SIGTERM by running `ticket-runner stop`, which signals the Run this Host holds the lock for. Report what it prints, then keep watching: a Stop finishes the Tickets the Run already holds and takes no more, so the Run ends by itself with its summary, whether or not it was given Ticket numbers. Never end a Run any other way. SIGINT or SIGKILL ends it in the middle of a Ticket.
97
+
98
+ ## Your own Run gone
99
+
100
+ Your Run has gone without its summary when the watch ended with no summary before the exit line, or the log has no exit line and the pid in `.ticket-runner/run.pid` is no longer running (`kill -0` fails). It was killed: its Tickets were left stranded and its lock held. Read the lock, and this session's id beside it:
101
+
102
+ ```bash
103
+ git fetch origin ticket-runner/lock
104
+ git show FETCH_HEAD:lock.json
105
+ echo "${CLAUDE_CODE_REMOTE_SESSION_ID:-$CLAUDE_CODE_SESSION_ID}"
106
+ ```
107
+
108
+ When the lock's `host.id` is this session's id, the lock names this Operator's Host. Do not ask the human to release it: a Run started here takes over a lock whose Run on this Host has gone, by itself, and resumes the Tickets it left stranded. Tell the human the Run ended without its summary, and offer to start it again; start it, as under [Start](#start), when they ask. A lock that names another Host is the next section's.
64
109
 
65
110
  ## Release a lock another Host left
66
111
 
@@ -82,7 +127,27 @@ git push --no-verify --force-with-lease="refs/heads/ticket-runner/lock:$tip" ori
82
127
 
83
128
  Check that the `lock.json` it shows names the Host the refusal named before you push. If the push is refused, the lock moved: read it again and tell the human who holds it now. Delete nothing, on the remote or here.
84
129
 
130
+ ## The board while no Run holds it
131
+
132
+ While a Run holds this repository, the board is the human's alone: the Run reads it as it goes, and a Stop is the human's only way into a running Run. No Run holds it while the lock is free, `lock.json` reading `{ "held": false }`, or names only your own Run that has gone ([Your own Run gone](#your-own-run-gone)). Read the lock as that section does right before you write. Then, and only when the human explicitly asks, you may carry their decision on a handed-off Ticket to the board in these three ways:
133
+
134
+ - Swap the Ticket's `ready-for-human` label for `ready-for-agent`, keeping its other labels. Where `ticket-runner.json` renames either label, use its name.
135
+ - Post the human's decision as a comment on the Ticket, in words the human approved, with each new criterion as its own `- [ ]` checkbox line.
136
+ - Turn a criterion the human names as replaced from `- [ ] X` into `- (superseded) X`, keeping its words, in the body or comment that holds it, so the verify Stage no longer grades it.
137
+
138
+ Write through `gh api`, as the Run does: a cloud Host refuses the GraphQL that `gh issue edit` and `gh issue comment` use. `{owner}/{repo}` is filled in by `gh` itself.
139
+
140
+ ```bash
141
+ gh api -X DELETE "repos/{owner}/{repo}/issues/<n>/labels/ready-for-human"
142
+ gh api "repos/{owner}/{repo}/issues/<n>/labels" -f "labels[]=ready-for-agent"
143
+ gh api "repos/{owner}/{repo}/issues/<n>/comments" -F body=@<file>
144
+ gh api -X PATCH "repos/{owner}/{repo}/issues/<n>" -F body=@<file>
145
+ gh api -X PATCH "repos/{owner}/{repo}/issues/comments/<comment id>" -F body=@<file>
146
+ ```
147
+
148
+ Keep `<file>` outside the checkout, in a temporary directory, and change nothing in it but the criterion the human named. Rewrite no criterion and no part of the body otherwise. If a Run holds the lock, write nothing, and tell the human to make the change on the board themselves.
149
+
85
150
  ## What you leave alone
86
151
 
87
152
  - While your Run holds this repository, leave the checkout and `.worktrees/` alone. Edit no file, and run no git command that changes them: no checkout, pull, commit, stash, reset or worktree command. The Run pulls this checkout after every merge, and an edit of yours breaks that pull.
88
- - Relabel, comment on, close or edit no issue or pull request, and change no code. When the human asks for anything about a Ticket other than running it, stopping the Run or releasing the lock, tell them to do it on the board: a label, a comment or an edit to the issue is how a Run is steered.
153
+ - Change no code, and close or edit no pull request. Relabel, comment on or edit an issue only as [The board while no Run holds it](#the-board-while-no-run-holds-it) allows: at the human's explicit request, while no Run holds this repository, and in those three ways. When the human asks for anything else about a Ticket, or for one of those while a Run holds this repository, tell them to do it on the board: a label, a comment or an edit to the issue is how a Run is steered.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ticket-runner",
3
- "version": "0.6.4",
3
+ "version": "0.6.6",
4
4
  "description": "Drives the mattpocock-skills chain: humans plan, the pipeline executes.",
5
5
  "keywords": [
6
6
  "claude-code",
@@ -3,7 +3,7 @@
3
3
  *
4
4
  * Readers recognise a criterion by its shape and would disagree about it if each
5
5
  * carried its own pattern: the `no-criteria` guard counts one to decide a Ticket
6
- * is usable, the merge ticks one a Verdict proved and then counts the boxes it
6
+ * is usable, the merge ticks one a verdict proved and then counts the boxes it
7
7
  * ticked, and a Note has one escaped before it is posted. Drift between them is
8
8
  * not a cosmetic bug — a criterion the guard sees but the escaper misses lets a
9
9
  * Note read as work somebody promised, and one the merge ticks but the guard
@@ -32,7 +32,7 @@ const ITEM_HEAD = String.raw`^([ \t]*[-*+] )`;
32
32
  export const UNCHECKED_BOX = String.raw`${ITEM_HEAD}\[ \]`;
33
33
 
34
34
  /**
35
- * The ticked twin, for the merge alone: having ticked what a Verdict proved, it
35
+ * The ticked twin, for the merge alone: having ticked what a verdict proved, it
36
36
  * counts the boxes now ticked to tell whether a met criterion matched nothing.
37
37
  *
38
38
  * It shares {@link UNCHECKED_BOX}'s head so that count cannot drift from the
@@ -42,3 +42,100 @@ export const UNCHECKED_BOX = String.raw`${ITEM_HEAD}\[ \]`;
42
42
  * before and the after of the same count.
43
43
  */
44
44
  export const TICKED_BOX = String.raw`${ITEM_HEAD}\[x\]`;
45
+
46
+ /** {@link UNCHECKED_BOX}, extended to capture the criterion after the box. */
47
+ const CRITERION_LINE = new RegExp(`${UNCHECKED_BOX}(.*)$`);
48
+
49
+ /** Any task list item, ticked or not, which a criterion's indented lines stop short of. */
50
+ const ANY_BOX = new RegExp(String.raw`${ITEM_HEAD}\[[ xX]\]`);
51
+
52
+ /**
53
+ * One Acceptance Criterion as the pipeline lists it for the verify Stage, by
54
+ * the number the verdict answers it with.
55
+ *
56
+ * The verdict answers a number rather than a copy of the text, so nothing ever
57
+ * has to match a Stage's copy back to a checkbox: the copy is where the verdict
58
+ * folded a sub-list into its line, decoded an escape or split a sentence, and
59
+ * left a met criterion unticked.
60
+ */
61
+ export interface ListedCriterion {
62
+ /** Its place in the list, from 1: the body's checkboxes first, then each comment's. */
63
+ number: number;
64
+ /**
65
+ * The checkbox line exactly as the Ticket wrote it when it was listed. A met
66
+ * criterion is ticked on the unticked line that still reads so.
67
+ */
68
+ line: string;
69
+ /** The criterion as its checkbox line reads after the box. */
70
+ text: string;
71
+ /**
72
+ * The indented lines under the checkbox that are not checkboxes themselves,
73
+ * as written: a sub-list or a code block that says what the line means. A
74
+ * nested checkbox is a criterion of its own, and so are the lines under it.
75
+ */
76
+ details: string[];
77
+ }
78
+
79
+ /**
80
+ * Every unticked checkbox on a Ticket, numbered in reading order: `texts` are
81
+ * the places it writes its criteria, its body first and then its comments.
82
+ */
83
+ export function listCriteria(texts: readonly string[]): ListedCriterion[] {
84
+ const listed: ListedCriterion[] = [];
85
+ for (const text of texts) {
86
+ // A body edited on GitHub's web form ends its lines in CRLF; the line a
87
+ // criterion is listed as is the one ticking finds, which never holds the CR.
88
+ const lines = text.split(/\r?\n/);
89
+ for (const [index, line] of lines.entries()) {
90
+ const match = CRITERION_LINE.exec(line);
91
+ if (match === null) continue;
92
+ listed.push({
93
+ number: listed.length + 1,
94
+ line,
95
+ text: (match[2] ?? "").trim(),
96
+ details: detailsUnder(lines, index),
97
+ });
98
+ }
99
+ }
100
+ return listed;
101
+ }
102
+
103
+ /**
104
+ * The lines indented under the checkbox at `lines[at]`, up to the first line
105
+ * that is not, leaving out any checkbox among them and the lines indented under
106
+ * that one. A blank line inside the run is kept; blank lines at its end are not.
107
+ */
108
+ function detailsUnder(lines: readonly string[], at: number): string[] {
109
+ const own = indentOf(lines[at] ?? "");
110
+ const details: string[] = [];
111
+ /** The indent of a nested checkbox whose own lines are being passed over. */
112
+ let nested: number | undefined;
113
+ for (const line of lines.slice(at + 1)) {
114
+ if (line.trim() === "") {
115
+ if (nested === undefined) details.push(line);
116
+ continue;
117
+ }
118
+ const indent = indentOf(line);
119
+ if (indent <= own) break;
120
+ if (nested !== undefined && indent > nested) continue;
121
+ nested = undefined;
122
+ if (ANY_BOX.test(line)) {
123
+ nested = indent;
124
+ continue;
125
+ }
126
+ details.push(line);
127
+ }
128
+ while (details.length > 0 && (details.at(-1) ?? "").trim() === "") details.pop();
129
+ return details;
130
+ }
131
+
132
+ /** How far a line is indented, a tab counting as four columns as Markdown counts it. */
133
+ function indentOf(line: string): number {
134
+ let width = 0;
135
+ for (const character of line) {
136
+ if (character === " ") width += 1;
137
+ else if (character === "\t") width += 4 - (width % 4);
138
+ else break;
139
+ }
140
+ return width;
141
+ }
@@ -29,7 +29,7 @@ export interface ClaudeAgentRunnerOptions {
29
29
  const STAGE_SHELL = "/bin/bash";
30
30
 
31
31
  /**
32
- * The Session mark: a variable every Stage carries at a value no other Stage
32
+ * The session mark: a variable every Stage carries at a value no other Stage
33
33
  * session shares, and every process it starts inherits. A Stage killed at its
34
34
  * time limit is killed with every process still carrying its value, whoever
35
35
  * their parent is by then.
@@ -321,7 +321,7 @@ interface StageLog {
321
321
  /**
322
322
  * What stands in a Stage's files for the Host's API key, wherever the session
323
323
  * printed it: an `--api-key` Stage that runs `env` would otherwise put the key
324
- * in a transcript, which reaches the Target's remote with a hand-off.
324
+ * in a transcript, which a hand-off may keep on the Target's remote.
325
325
  */
326
326
  const REDACTED_KEY = `<${API_KEY_ENV_VAR}>`;
327
327
 
@@ -363,7 +363,7 @@ function startStageLog(
363
363
  appendFileSync(path(suffix), text.slice(0, text.length - held));
364
364
  appended[suffix] += chunk.length;
365
365
  } catch {
366
- // Nothing is lost: the chunk is still part of the Execution.
366
+ // Nothing is lost: the chunk is still part of the execution.
367
367
  }
368
368
  };
369
369
 
@@ -430,7 +430,7 @@ function isInitEvent(event: unknown): event is InitEvent {
430
430
 
431
431
  /**
432
432
  * What the session said it was billed to: the first init event's word on it.
433
- * A waking for a background agent is the same session on the same credential.
433
+ * A waking for a background agent is the same session, billed to the same.
434
434
  */
435
435
  function keySource(events: unknown[]): string | undefined {
436
436
  const source = events.find(isInitEvent)?.apiKeySource;
@@ -597,7 +597,7 @@ function structuredOutputOf(result: ResultEvent): unknown {
597
597
  * How the environment differed from the Host's leads it: a subscription Stage
598
598
  * ran without the Host's key, which `env -u` removes again, and an API-key
599
599
  * Stage ran on it, which is named and left for the shell to fill in. Its value
600
- * is never written: command files reach the Target's remote with a hand-off.
600
+ * is never written: a hand-off may keep command files on the Target's remote.
601
601
  */
602
602
  function quoteCommand(
603
603
  credential: Credential,
@@ -1,4 +1,5 @@
1
1
  import { spawn } from "node:child_process";
2
+ import { OutsideFault, faultSide, firstLine } from "../outside-fault.js";
2
3
  import { type Mark, killTree } from "./process-tree.js";
3
4
 
4
5
  export interface Execution {
@@ -186,20 +187,47 @@ export async function execOrThrow(
186
187
  return throwOnFailure(command, args, await exec(command, args, options));
187
188
  }
188
189
 
189
- /** Turn a non-zero exit into an error naming the command and its output. */
190
+ /**
191
+ * Turn a non-zero exit into an error naming the command and its output.
192
+ *
193
+ * The message's first line is the whole command and how it exited, and every
194
+ * line after it is what the command printed, so whatever shows the message on
195
+ * one line takes its first. An argument with a newline in it — a pull
196
+ * request's body, a commit message — is shown by its first line and ` …`:
197
+ * the rest is what the pipeline wrote, not what the command printed, and
198
+ * given whole it would carry the command onto lines a reader takes for its
199
+ * output.
200
+ */
190
201
  export function throwOnFailure(
191
202
  command: string,
192
203
  args: string[],
193
204
  result: Execution,
194
205
  ): Execution {
195
206
  if (result.exitCode !== 0) {
196
- throw new Error(
197
- `\`${command} ${args.join(" ")}\` exited ${result.exitCode}\n${result.output.trim()}`,
198
- );
207
+ const shown = shownCommand(command, args);
208
+ const message = `\`${shown}\` exited ${result.exitCode}\n${result.output.trim()}`;
209
+ // The same message either way: what differs is whether the caller can
210
+ // tell GitHub or the remote failed, rather than the Ticket's own work.
211
+ const side = faultSide(command, result.output);
212
+ // stderr first, where both commands say why they failed: `gh api` prints
213
+ // the body of a 5xx, often a page of HTML, on stdout before it.
214
+ const line = firstLine(result.stderr) || firstLine(result.output);
215
+ throw side === undefined ? new Error(message) : new OutsideFault(side, shown, line, message);
199
216
  }
200
217
  return result;
201
218
  }
202
219
 
220
+ /** A command as a failure names it: on one line, each argument by its first. */
221
+ export function shownCommand(command: string, args: string[]): string {
222
+ return [command, ...args.map(firstLineOf)].join(" ");
223
+ }
224
+
225
+ /** An argument as a failed command's message shows it: on one line. */
226
+ function firstLineOf(arg: string): string {
227
+ const newline = arg.search(/\r?\n/);
228
+ return newline === -1 ? arg : `${arg.slice(0, newline).trimEnd()} …`;
229
+ }
230
+
203
231
  /**
204
232
  * The environment a child is given, or nothing where it inherits this
205
233
  * process's own untouched.