vouchington-tooling 0.53.0 → 0.55.0

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 (197) hide show
  1. package/README.md +99 -12
  2. package/dist/agent-blackboard/index.d.mts +0 -1
  3. package/dist/agent-blackboard/index.mjs +0 -23
  4. package/dist/cli/commands/agent-blackboard-flags.d.mts +0 -1
  5. package/dist/cli/commands/agent-blackboard-flags.mjs +0 -9
  6. package/dist/cli/commands/agent-blackboard.d.mts +0 -2
  7. package/dist/cli/commands/agent-blackboard.mjs +7 -121
  8. package/dist/cli/commands/story-coverage.d.mts +2 -0
  9. package/dist/cli/commands/story-coverage.mjs +56 -0
  10. package/dist/cli/index.mjs +6 -0
  11. package/dist/cli/optional-peer.d.mts +5 -0
  12. package/dist/cli/optional-peer.mjs +17 -0
  13. package/dist/cli/parse-forwarded-commands.d.mts +3 -0
  14. package/dist/cli/parse-forwarded-commands.mjs +2 -0
  15. package/dist/cli/parse-story-coverage-fields.d.mts +19 -0
  16. package/dist/cli/parse-story-coverage-fields.mjs +69 -0
  17. package/dist/cli/parse-story-coverage.d.mts +8 -0
  18. package/dist/cli/parse-story-coverage.mjs +34 -0
  19. package/dist/cli/parse.d.mts +5 -1
  20. package/dist/cli/parse.mjs +3 -0
  21. package/dist/cli/story-coverage-lazy.d.mts +3 -0
  22. package/dist/cli/story-coverage-lazy.mjs +6 -0
  23. package/dist/cli/usage.d.mts +1 -1
  24. package/dist/cli/usage.mjs +8 -7
  25. package/dist/host-storage/check.d.mts +38 -0
  26. package/dist/host-storage/check.mjs +109 -0
  27. package/dist/host-storage/cli.d.mts +7 -0
  28. package/dist/host-storage/cli.mjs +102 -0
  29. package/dist/host-storage/host-storage.test-helpers.d.mts +26 -0
  30. package/dist/host-storage/host-storage.test-helpers.mjs +58 -0
  31. package/dist/host-storage/index.d.mts +3 -0
  32. package/dist/host-storage/index.mjs +3 -0
  33. package/dist/host-storage/preflight.d.mts +22 -0
  34. package/dist/host-storage/preflight.mjs +105 -0
  35. package/dist/index.d.mts +2 -0
  36. package/dist/index.mjs +1 -0
  37. package/dist/playwright/assertions.d.mts +1 -0
  38. package/dist/playwright/assertions.mjs +5 -0
  39. package/dist/playwright/blocked-external-network.d.mts +15 -0
  40. package/dist/playwright/blocked-external-network.mjs +73 -0
  41. package/dist/playwright/browser-dialog-issues.d.mts +12 -0
  42. package/dist/playwright/browser-dialog-issues.mjs +29 -0
  43. package/dist/playwright/browser-errors.d.mts +23 -0
  44. package/dist/playwright/browser-errors.mjs +130 -0
  45. package/dist/playwright/browser-issue-monitor.test-helpers.d.mts +31 -0
  46. package/dist/playwright/browser-issue-monitor.test-helpers.mjs +51 -0
  47. package/dist/playwright/browser-issue-records.d.mts +42 -0
  48. package/dist/playwright/browser-issue-records.mjs +148 -0
  49. package/dist/playwright/browser-test.d.mts +22 -0
  50. package/dist/playwright/browser-test.mjs +68 -0
  51. package/dist/playwright/expect-no-broken-images.d.mts +17 -0
  52. package/dist/playwright/expect-no-broken-images.mjs +39 -0
  53. package/dist/playwright/index.d.mts +32 -0
  54. package/dist/playwright/index.mjs +22 -0
  55. package/dist/playwright/mobile-assertions.d.mts +14 -0
  56. package/dist/playwright/mobile-assertions.mjs +43 -0
  57. package/dist/playwright/monitored-test-info.d.mts +14 -0
  58. package/dist/playwright/monitored-test-info.mjs +1 -0
  59. package/dist/playwright/navigate-to.d.mts +27 -0
  60. package/dist/playwright/navigate-to.mjs +39 -0
  61. package/dist/playwright/radix-select.d.mts +18 -0
  62. package/dist/playwright/radix-select.mjs +19 -0
  63. package/dist/playwright/random-id.d.mts +34 -0
  64. package/dist/playwright/random-id.mjs +37 -0
  65. package/dist/playwright/retry-on-connection-lost.d.mts +7 -0
  66. package/dist/playwright/retry-on-connection-lost.mjs +107 -0
  67. package/dist/playwright/scroll-to-load-more.d.mts +37 -0
  68. package/dist/playwright/scroll-to-load-more.mjs +158 -0
  69. package/dist/playwright/storybook.d.mts +2 -0
  70. package/dist/playwright/storybook.mjs +13 -0
  71. package/dist/playwright/test-fixtures.d.mts +1 -0
  72. package/dist/playwright/test-fixtures.mjs +2 -0
  73. package/dist/playwright/test-lifecycle-reporter.d.mts +27 -0
  74. package/dist/playwright/test-lifecycle-reporter.mjs +57 -0
  75. package/dist/playwright/totp.d.mts +6 -0
  76. package/dist/playwright/totp.mjs +37 -0
  77. package/dist/playwright/turnstile-stub.d.mts +8 -0
  78. package/dist/playwright/turnstile-stub.mjs +61 -0
  79. package/dist/playwright/viewport-constants.d.mts +30 -0
  80. package/dist/playwright/viewport-constants.mjs +9 -0
  81. package/dist/playwright/virtual-authenticator.d.mts +5 -0
  82. package/dist/playwright/virtual-authenticator.mjs +15 -0
  83. package/dist/playwright/wait-for-hydration.d.mts +29 -0
  84. package/dist/playwright/wait-for-hydration.mjs +81 -0
  85. package/dist/shell-parse/ansi-c-string.d.mts +12 -0
  86. package/dist/shell-parse/ansi-c-string.mjs +80 -0
  87. package/dist/shell-parse/index.d.mts +20 -0
  88. package/dist/shell-parse/index.mjs +15 -0
  89. package/dist/shell-parse/shell-command-substitution-reads.d.mts +8 -0
  90. package/dist/shell-parse/shell-command-substitution-reads.mjs +53 -0
  91. package/dist/shell-parse/shell-command-substitutions.d.mts +8 -0
  92. package/dist/shell-parse/shell-command-substitutions.mjs +52 -0
  93. package/dist/shell-parse/shell-command-wrappers.d.mts +26 -0
  94. package/dist/shell-parse/shell-command-wrappers.mjs +143 -0
  95. package/dist/shell-parse/shell-commands.d.mts +24 -0
  96. package/dist/shell-parse/shell-commands.mjs +155 -0
  97. package/dist/shell-parse/shell-heredoc-delimiter.d.mts +5 -0
  98. package/dist/shell-parse/shell-heredoc-delimiter.mjs +52 -0
  99. package/dist/shell-parse/shell-heredoc-parser.d.mts +7 -0
  100. package/dist/shell-parse/shell-heredoc-parser.mjs +49 -0
  101. package/dist/shell-parse/shell-heredoc-quote-state.d.mts +19 -0
  102. package/dist/shell-parse/shell-heredoc-quote-state.mjs +40 -0
  103. package/dist/shell-parse/shell-heredoc.d.mts +10 -0
  104. package/dist/shell-parse/shell-heredoc.mjs +90 -0
  105. package/dist/shell-parse/shell-redirections.d.mts +5 -0
  106. package/dist/shell-parse/shell-redirections.mjs +34 -0
  107. package/dist/shell-parse/shell-script-operand.d.mts +13 -0
  108. package/dist/shell-parse/shell-script-operand.mjs +103 -0
  109. package/dist/shell-parse/shell-stdin-script.d.mts +6 -0
  110. package/dist/shell-parse/shell-stdin-script.mjs +61 -0
  111. package/dist/shell-parse/shell-token-utils.d.mts +9 -0
  112. package/dist/shell-parse/shell-token-utils.mjs +33 -0
  113. package/dist/shell-parse/shell-tokenizer-comments.d.mts +1 -0
  114. package/dist/shell-parse/shell-tokenizer-comments.mjs +57 -0
  115. package/dist/shell-parse/shell-tokenizer-operators.d.mts +14 -0
  116. package/dist/shell-parse/shell-tokenizer-operators.mjs +47 -0
  117. package/dist/shell-parse/shell-tokenizer.d.mts +12 -0
  118. package/dist/shell-parse/shell-tokenizer.mjs +104 -0
  119. package/dist/story-coverage/analyze.d.mts +8 -0
  120. package/dist/story-coverage/analyze.mjs +24 -0
  121. package/dist/story-coverage/check.d.mts +11 -0
  122. package/dist/story-coverage/check.mjs +42 -0
  123. package/dist/story-coverage/components.d.mts +10 -0
  124. package/dist/story-coverage/components.mjs +40 -0
  125. package/dist/story-coverage/coverage.d.mts +10 -0
  126. package/dist/story-coverage/coverage.mjs +43 -0
  127. package/dist/story-coverage/index.d.mts +13 -0
  128. package/dist/story-coverage/index.mjs +7 -0
  129. package/dist/story-coverage/messages.d.mts +10 -0
  130. package/dist/story-coverage/messages.mjs +42 -0
  131. package/dist/story-coverage/options.d.mts +27 -0
  132. package/dist/story-coverage/options.mjs +51 -0
  133. package/dist/story-coverage/workspace.d.mts +2 -0
  134. package/dist/story-coverage/workspace.mjs +27 -0
  135. package/dist/test-helpers/cancel-runs.test-helpers.d.mts +39 -0
  136. package/dist/test-helpers/cancel-runs.test-helpers.mjs +124 -0
  137. package/dist/test-helpers/run-bounded-exit-observer.test-helpers.d.mts +12 -0
  138. package/dist/test-helpers/run-bounded-exit-observer.test-helpers.mjs +68 -0
  139. package/dist/test-helpers/run-bounded-output-fixture.test-helpers.d.mts +18 -0
  140. package/dist/test-helpers/run-bounded-output-fixture.test-helpers.mjs +162 -0
  141. package/dist/vitest-diagnostics/browser.d.mts +2 -0
  142. package/dist/vitest-diagnostics/browser.mjs +6 -0
  143. package/dist/vitest-diagnostics/index.d.mts +14 -23
  144. package/dist/vitest-diagnostics/index.mjs +8 -124
  145. package/dist/vitest-diagnostics/report-summary.d.mts +22 -0
  146. package/dist/vitest-diagnostics/report-summary.mjs +123 -0
  147. package/dist/vitest-diagnostics/vitest-fake-timer-guard.d.mts +6 -0
  148. package/dist/vitest-diagnostics/vitest-fake-timer-guard.mjs +34 -0
  149. package/dist/vitest-diagnostics/vitest-fork-leak-detection.d.mts +1 -0
  150. package/dist/vitest-diagnostics/vitest-fork-leak-detection.mjs +8 -0
  151. package/dist/vitest-diagnostics/vitest-fork-leak-diagnostics.d.mts +17 -1
  152. package/dist/vitest-diagnostics/vitest-fork-leak-diagnostics.mjs +44 -2
  153. package/dist/vitest-diagnostics/vitest-fork-leak-handshake-samples.d.mts +55 -0
  154. package/dist/vitest-diagnostics/vitest-fork-leak-handshake-samples.mjs +74 -0
  155. package/dist/vitest-diagnostics/vitest-fork-leak-handshake.d.mts +19 -0
  156. package/dist/vitest-diagnostics/vitest-fork-leak-handshake.mjs +136 -0
  157. package/dist/vitest-diagnostics/vitest-network-allowlist-dns.d.mts +7 -0
  158. package/dist/vitest-diagnostics/vitest-network-allowlist-dns.mjs +54 -0
  159. package/dist/vitest-diagnostics/vitest-network-allowlist-host.d.mts +8 -0
  160. package/dist/vitest-diagnostics/vitest-network-allowlist-host.mjs +48 -0
  161. package/dist/vitest-diagnostics/vitest-network-allowlist-socket.d.mts +14 -0
  162. package/dist/vitest-diagnostics/vitest-network-allowlist-socket.mjs +39 -0
  163. package/dist/vitest-diagnostics/vitest-network-allowlist.d.mts +7 -0
  164. package/dist/vitest-diagnostics/vitest-network-allowlist.mjs +72 -0
  165. package/dist/vitest-diagnostics/vitest-process-resources.d.mts +10 -0
  166. package/dist/vitest-diagnostics/vitest-process-resources.mjs +54 -0
  167. package/dist/vitest-effective-timeout/cap.d.mts +9 -0
  168. package/dist/vitest-effective-timeout/cap.mjs +28 -0
  169. package/dist/vitest-effective-timeout/check-profiles.d.mts +15 -0
  170. package/dist/vitest-effective-timeout/check-profiles.mjs +52 -0
  171. package/dist/vitest-effective-timeout/config-file.d.mts +6 -0
  172. package/dist/vitest-effective-timeout/config-file.mjs +23 -0
  173. package/dist/vitest-effective-timeout/fixtures.d.mts +2 -0
  174. package/dist/vitest-effective-timeout/fixtures.mjs +18 -0
  175. package/dist/vitest-effective-timeout/index.d.mts +7 -0
  176. package/dist/vitest-effective-timeout/index.mjs +4 -0
  177. package/dist/vitest-effective-timeout/profiles.d.mts +10 -0
  178. package/dist/vitest-effective-timeout/profiles.mjs +33 -0
  179. package/dist/vitest-effective-timeout/run-profile.d.mts +31 -0
  180. package/dist/vitest-effective-timeout/run-profile.mjs +95 -0
  181. package/docs/mcp-server.md +2 -13
  182. package/package.json +37 -2
  183. package/scripts/__pycache__/run_bounded_process.cpython-312.pyc +0 -0
  184. package/scripts/chromium-launch-probe.d.mts +7 -0
  185. package/scripts/chromium-launch-probe.mjs +101 -0
  186. package/scripts/run-bounded-fixtures/run-bounded-backpressure.py +186 -0
  187. package/scripts/run-bounded-fixtures/run-bounded-merged-output.py +75 -0
  188. package/scripts/run-bounded-fixtures/run-bounded-reset-socket.py +25 -0
  189. package/scripts/run-bounded.py +199 -0
  190. package/scripts/run_bounded_process.py +129 -0
  191. package/scripts/worktree/git-index-lock.sh +16 -0
  192. package/scripts/worktree/git-worktrees.sh +23 -20
  193. package/scripts/worktree/reset-worktree-run.sh +199 -0
  194. package/scripts/worktree/reset-worktree.sh +122 -0
  195. package/skills/blackboard/SKILL.md +4 -64
  196. package/skills/stacked-prs/SKILL.md +1 -1
  197. package/skills/stacked-prs/references/drain.md +2 -2
@@ -0,0 +1,129 @@
1
+ """Own downstream descriptors and command process-group lifetime."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import errno
6
+ import fcntl
7
+ import os
8
+ import signal
9
+ import stat
10
+ import subprocess
11
+ from contextlib import contextmanager
12
+
13
+
14
+ @contextmanager
15
+ def output_sinks():
16
+ targets: list[int | None] = []
17
+ primary: BaseException | None = None
18
+ try:
19
+ for fd in (1, 2):
20
+ try:
21
+ targets.append(fcntl.fcntl(fd, fcntl.F_DUPFD_CLOEXEC, 3))
22
+ except OSError as err:
23
+ if err.errno != errno.EBADF:
24
+ raise
25
+ targets.append(None) # Absent at entry, before Popen allocates source pipes.
26
+ # Keep the closed number occupied so a child pipe cannot become stderr.
27
+ occupy_closed_fd(fd)
28
+ yield targets
29
+ except BaseException as err:
30
+ primary = err
31
+ raise
32
+ finally:
33
+ errors: list[BaseException] = []
34
+ for fd in targets:
35
+ if fd is not None:
36
+ try:
37
+ os.close(fd)
38
+ except BaseException as err:
39
+ errors.append(err)
40
+ if errors:
41
+ details = ([repr(primary)] if primary is not None else []) + list(map(repr, errors))
42
+ raise RuntimeError('Output descriptor cleanup failed: ' + '; '.join(details)) from (primary or errors[0])
43
+
44
+
45
+ class WrapperSignal(BaseException):
46
+ def __init__(self, signum: int) -> None:
47
+ super().__init__(signum)
48
+ self.signum = signum
49
+
50
+
51
+ def occupy_closed_fd(fd: int) -> None:
52
+ null = os.open(os.devnull, os.O_WRONLY)
53
+ try:
54
+ if null != fd:
55
+ os.dup2(null, fd)
56
+ finally:
57
+ if null != fd:
58
+ os.close(null)
59
+
60
+
61
+ def exit_status(code: int) -> int:
62
+ if code < 0:
63
+ return 128 - code
64
+ return code
65
+
66
+
67
+ def signal_group(pid: int, sig: int) -> None:
68
+ try:
69
+ os.killpg(pid, sig)
70
+ except ProcessLookupError:
71
+ return
72
+
73
+
74
+ def arm_termination() -> None:
75
+ def handle(signum: int, _frame: object) -> None:
76
+ signal.signal(signum, signal.SIG_DFL)
77
+ raise WrapperSignal(signum)
78
+
79
+ signal.signal(signal.SIGTERM, handle)
80
+ signal.signal(signal.SIGINT, handle)
81
+
82
+
83
+ def reap_terminated_group(proc: subprocess.Popen[bytes], signum: int) -> int:
84
+ signal_group(proc.pid, signal.SIGTERM)
85
+ try:
86
+ proc.wait(timeout=10)
87
+ except subprocess.TimeoutExpired:
88
+ pass
89
+ # A TERM-resistant descendant can outlive the parent; finish the group.
90
+ signal_group(proc.pid, signal.SIGKILL)
91
+ proc.wait()
92
+ return 128 + signum
93
+
94
+
95
+ def run(proc: subprocess.Popen[bytes], seconds: int) -> int:
96
+ try:
97
+ return exit_status(proc.wait(timeout=seconds))
98
+ except subprocess.TimeoutExpired:
99
+ signal_group(proc.pid, signal.SIGTERM)
100
+ try:
101
+ proc.wait(timeout=10)
102
+ except subprocess.TimeoutExpired:
103
+ pass
104
+ # The parent can exit on SIGTERM while a descendant keeps running.
105
+ # Finish cleaning the group even when waiting for the parent succeeded.
106
+ signal_group(proc.pid, signal.SIGKILL)
107
+ proc.wait()
108
+ return 124
109
+
110
+
111
+
112
+ def command_outputs(targets: list[int | None]):
113
+ """Inherit non-stream descriptors; share one pipe for merged stream sinks."""
114
+ outputs = [
115
+ subprocess.PIPE
116
+ if fd is None or stat.S_ISFIFO(os.fstat(fd).st_mode) or stat.S_ISSOCK(os.fstat(fd).st_mode)
117
+ else fd
118
+ for fd in targets
119
+ ]
120
+ if all(fd is not None for fd in targets):
121
+ left, right = (os.fstat(fd) for fd in targets)
122
+ stream = stat.S_ISFIFO(left.st_mode) or stat.S_ISSOCK(left.st_mode)
123
+ same_endpoint = (left.st_dev, left.st_ino, left.st_mode) == (
124
+ right.st_dev, right.st_ino, right.st_mode
125
+ )
126
+ same_flags = fcntl.fcntl(targets[0], fcntl.F_GETFL) == fcntl.fcntl(targets[1], fcntl.F_GETFL)
127
+ if stream and same_endpoint and same_flags:
128
+ outputs[1] = subprocess.STDOUT
129
+ return dict(stdout=outputs[0], stderr=outputs[1])
@@ -0,0 +1,16 @@
1
+ #!/usr/bin/env bash
2
+ # Removes a 0-byte index.lock left by an interrupted git write.
3
+ # A non-empty index.lock means a git process is mid-write, so it stays.
4
+ # Git creates a 0-byte lock briefly before writing. Call this only when no
5
+ # concurrent git write is expected.
6
+
7
+ clear_stale_index_lock() {
8
+ local git_dir=$1
9
+ if [ -z "$git_dir" ]; then
10
+ return 1
11
+ fi
12
+ if [ -f "$git_dir/index.lock" ] && [ ! -s "$git_dir/index.lock" ]; then
13
+ rm -f "$git_dir/index.lock"
14
+ printf 'Cleared stale empty index.lock at %s/index.lock\n' "$git_dir"
15
+ fi
16
+ }
@@ -2,15 +2,19 @@
2
2
  # Helpers for parsing `git worktree list --porcelain` and identifying worktree paths.
3
3
 
4
4
  git_worktree_list_porcelain() {
5
- local repo_root=${1:-}
6
-
7
- if [ -n "$repo_root" ]; then
8
- (git -C "$repo_root" worktree list --porcelain 2>/dev/null)
5
+ if [ -n "${1:-}" ]; then
6
+ git -C "$1" worktree list --porcelain
9
7
  else
10
- (git worktree list --porcelain 2>/dev/null)
8
+ git worktree list --porcelain
11
9
  fi
12
10
  }
13
11
 
12
+ _git_worktree_records() {
13
+ local porcelain
14
+ porcelain=$(git_worktree_list_porcelain "${1:-}") || return 1
15
+ printf '%s\n' "$porcelain" | git_worktree_records_from_porcelain
16
+ }
17
+
14
18
  worktree_dir_from_path() {
15
19
  local path=$1
16
20
  local worktree_dir
@@ -60,52 +64,51 @@ git_worktree_records_from_porcelain() {
60
64
  }
61
65
 
62
66
  git_worktree_live_paths() {
63
- local repo_root=${1:-}
64
- local path prunable
67
+ local records path prunable
68
+ records=$(_git_worktree_records "${1:-}") || return 1
65
69
 
66
70
  while IFS=$'\t' read -r path prunable; do
67
71
  [ -n "$path" ] || continue
68
72
  if [ "$prunable" = 0 ] && [ -d "$path" ]; then
69
73
  printf '%s\n' "$path"
70
74
  fi
71
- done < <(git_worktree_list_porcelain "$repo_root" | git_worktree_records_from_porcelain)
75
+ done <<<"$records"
72
76
  }
73
77
 
74
78
  git_worktree_prunable_paths() {
75
- local repo_root=${1:-}
76
- local path prunable
79
+ local records path prunable
80
+ records=$(_git_worktree_records "${1:-}") || return 1
77
81
 
78
82
  while IFS=$'\t' read -r path prunable; do
79
83
  [ -n "$path" ] || continue
80
84
  if [ "$prunable" = 1 ]; then
81
85
  printf '%s\n' "$path"
82
86
  fi
83
- done < <(git_worktree_list_porcelain "$repo_root" | git_worktree_records_from_porcelain)
87
+ done <<<"$records"
84
88
  }
85
89
 
86
90
  git_worktree_main_path() {
87
- local repo_root=${1:-}
88
- local path prunable
91
+ local records path prunable
92
+ records=$(_git_worktree_records "${1:-}") || return 1
89
93
 
90
94
  while IFS=$'\t' read -r path prunable; do
91
95
  [ -n "$path" ] || continue
92
96
  printf '%s' "$path"
93
97
  return 0
94
- done < <(git_worktree_list_porcelain "$repo_root" | git_worktree_records_from_porcelain)
98
+ done <<<"$records"
99
+ return 1
95
100
  }
96
101
 
97
102
  git_worktree_path_is_registered() {
98
- local repo_root=$1
99
- local target_path=$2
100
- local path prunable
103
+ local records path prunable
104
+ records=$(_git_worktree_records "$1") || return 1
101
105
 
102
106
  while IFS=$'\t' read -r path prunable; do
103
107
  [ -n "$path" ] || continue
104
- if [ "$path" = "$target_path" ]; then
108
+ if [ "$path" = "$2" ]; then
105
109
  return 0
106
110
  fi
107
- done < <(git_worktree_list_porcelain "$repo_root" | git_worktree_records_from_porcelain)
108
-
111
+ done <<<"$records"
109
112
  return 1
110
113
  }
111
114
 
@@ -0,0 +1,199 @@
1
+ #!/usr/bin/env bash
2
+ # Body and lock supervisor for reset-worktree.sh. Sourced, not executed.
3
+
4
+ reset_worker=""
5
+ RESET_UNDER_LOCKF=false
6
+
7
+ cancel_reset() {
8
+ local exit_code="$1"
9
+ trap '' INT TERM HUP
10
+ reset_worker="${reset_worker:-${!:-}}"
11
+ if [ -n "$reset_worker" ]; then
12
+ kill -TERM -- "-$reset_worker" 2>/dev/null || true
13
+ local grace_tick=0
14
+ while [ "$grace_tick" -lt 10 ] && kill -0 -- "-$reset_worker" 2>/dev/null; do
15
+ /bin/sleep 0.1
16
+ grace_tick=$((grace_tick + 1))
17
+ done
18
+ kill -KILL -- "-$reset_worker" 2>/dev/null || true
19
+ wait "$reset_worker" 2>/dev/null || true
20
+ fi
21
+ exit "$exit_code"
22
+ }
23
+
24
+ run_reset_supervised() {
25
+ trap 'cancel_reset 130' INT
26
+ trap 'cancel_reset 143' TERM
27
+ trap 'cancel_reset 129' HUP
28
+ set -m
29
+ (
30
+ set +m
31
+ trap '' TTIN TTOU
32
+ export GIT_TERMINAL_PROMPT=0
33
+ "$@"
34
+ ) </dev/null 9>&- &
35
+ reset_worker=$!
36
+ set +m
37
+ wait "$reset_worker"
38
+ }
39
+
40
+ acquire_reset_lock() {
41
+ [ "${WORKTREE_RESET_UNDER_LOCKF:-}" != "$ROOT" ] || RESET_UNDER_LOCKF=true
42
+ mkdir -p "$ROOT/.local"
43
+ if [ "${WORKTREE_RESET_UNDER_LOCKF:-}" = "$ROOT" ]; then
44
+ unset WORKTREE_RESET_UNDER_LOCKF
45
+ return 0
46
+ fi
47
+ if command -v flock >/dev/null 2>&1; then
48
+ exec 9>>"$ROOT/.local/reset-worktree.lock"
49
+ flock -n 9 || { echo "Error: another worktree reset is running for this worktree." >&2; exit 1; }
50
+ elif command -v lockf >/dev/null 2>&1; then
51
+ run_reset_supervised env WORKTREE_RESET_UNDER_LOCKF="$ROOT" lockf -s -k -t 0 \
52
+ "$ROOT/.local/reset-worktree.lock" "$0" "${ORIGINAL_ARGS[@]}" && exit 0
53
+ lockf_status=$?
54
+ if [ "$lockf_status" -eq 75 ]; then
55
+ echo "Error: another worktree reset is running for this worktree." >&2
56
+ exit 1
57
+ fi
58
+ exit "$lockf_status"
59
+ else
60
+ echo "Error: worktree reset requires flock or lockf." >&2
61
+ exit 1
62
+ fi
63
+ unset WORKTREE_RESET_UNDER_LOCKF
64
+ }
65
+
66
+ refuse_dirty() {
67
+ if $FORCE; then
68
+ return 0
69
+ fi
70
+ git -C "$ROOT" update-index -q --refresh >/dev/null 2>&1 || true
71
+ if ! git -C "$ROOT" diff-index --quiet HEAD -- 2>/dev/null; then
72
+ echo "Error: uncommitted changes detected." >&2
73
+ echo "Commit, stash, or discard them first, or rerun with --force to discard." >&2
74
+ exit 1
75
+ fi
76
+ # The reset lock lives in the worktree and must not count as caller dirt.
77
+ if [ -n "$(git -C "$ROOT" status --porcelain --untracked-files=normal -- . ':(exclude).local/reset-worktree.lock' 2>/dev/null)" ]; then
78
+ echo "Error: untracked files detected." >&2
79
+ echo "Remove or commit them first, or rerun with --force to discard." >&2
80
+ exit 1
81
+ fi
82
+ }
83
+
84
+ clear_index_lock() {
85
+ local index_lock
86
+ index_lock=$(cd "$ROOT" && git rev-parse --path-format=absolute --git-path index.lock)
87
+ if [ -s "$index_lock" ]; then
88
+ echo "Error: $index_lock is non-empty -- a git process is mid-write." >&2
89
+ echo "Wait for it to finish, then rerun the reset." >&2
90
+ exit 1
91
+ fi
92
+ if [ -f "$index_lock" ]; then
93
+ rm -f "$index_lock"
94
+ fi
95
+ }
96
+
97
+ fetch_base_ref() {
98
+ local remote
99
+ case "$BASE_REF" in
100
+ refs/*) ;;
101
+ */*)
102
+ remote=${BASE_REF%%/*}
103
+ if git -C "$ROOT" remote | grep -Fqx -- "$remote"; then
104
+ git -C "$ROOT" fetch "$remote" "${BASE_REF#*/}" >/dev/null
105
+ fi
106
+ ;;
107
+ esac
108
+ }
109
+
110
+ verify_base_ref() {
111
+ if ! git -C "$ROOT" rev-parse --verify --quiet "$BASE_REF^{commit}" >/dev/null; then
112
+ echo "Error: base ref does not resolve to a commit: $BASE_REF" >&2
113
+ exit 2
114
+ fi
115
+ }
116
+
117
+ validate_caches() {
118
+ local cache segment normalized
119
+ local -a segments
120
+ if [ "${#CACHES[@]}" -eq 0 ]; then
121
+ return 0
122
+ fi
123
+ for cache in "${CACHES[@]}"; do
124
+ case "$cache" in
125
+ ''|/*)
126
+ echo "Error: cache path must stay inside the worktree: $cache" >&2
127
+ exit 2
128
+ ;;
129
+ esac
130
+ normalized=
131
+ IFS=/ read -r -a segments <<< "$cache"
132
+ for segment in "${segments[@]}"; do
133
+ case "$segment" in
134
+ ''|.) ;;
135
+ ..)
136
+ echo "Error: cache path must stay inside the worktree: $cache" >&2
137
+ exit 2
138
+ ;;
139
+ *) normalized="${normalized:+$normalized/}$segment" ;;
140
+ esac
141
+ done
142
+ case "$normalized" in
143
+ ''|.git|.git/*|.local|.local/*)
144
+ echo "Error: cache path must stay inside the worktree: $cache" >&2
145
+ exit 2
146
+ ;;
147
+ esac
148
+ done
149
+ }
150
+
151
+ remove_caches() {
152
+ local cache
153
+ if [ "${#CACHES[@]}" -gt 0 ]; then
154
+ for cache in "${CACHES[@]}"; do
155
+ rm -rf "$ROOT/$cache"
156
+ done
157
+ fi
158
+ local dir
159
+ while IFS= read -r -d '' dir; do
160
+ # A tracked .cache directory is source, not disposable cache.
161
+ if [ -z "$(git -C "$ROOT" ls-files -- "$dir")" ]; then
162
+ rm -rf "$dir"
163
+ fi
164
+ done < <(find "$ROOT" \
165
+ \( -path "$ROOT/.git" -o -name node_modules \) -prune -o \
166
+ -type d -name .cache -prune -print0)
167
+ find "$ROOT" -type d -name node_modules -prune \
168
+ -exec rm -rf '{}/.cache' '{}/.vite' '{}/.vitest' \;
169
+ }
170
+
171
+ run_hook() {
172
+ local hook=$1
173
+ if [ -z "$hook" ]; then
174
+ return 0
175
+ fi
176
+ (cd "$ROOT" && bash -c "$hook")
177
+ }
178
+
179
+ reset_worktree() {
180
+ validate_caches
181
+ refuse_dirty
182
+ clear_index_lock
183
+ fetch_base_ref
184
+ verify_base_ref
185
+ run_hook "$PRE_HOOK"
186
+ local slug new_branch
187
+ slug=$(openssl rand -hex 4)
188
+ new_branch="reset-${slug}"
189
+ if $FORCE; then
190
+ git -C "$ROOT" checkout -B "$new_branch" --force >/dev/null
191
+ git -C "$ROOT" clean -fd -e /.local/reset-worktree.lock >/dev/null
192
+ else
193
+ git -C "$ROOT" checkout -B "$new_branch" >/dev/null
194
+ fi
195
+ git -C "$ROOT" reset --hard "$BASE_REF" >/dev/null
196
+ remove_caches
197
+ run_hook "$POST_HOOK"
198
+ printf 'reset-branch=%s\n' "$new_branch"
199
+ }
@@ -0,0 +1,122 @@
1
+ #!/usr/bin/env bash
2
+ # Reset a git worktree onto a new branch at a caller-supplied base ref.
3
+ # Teardown, generated build outputs, and session files stay in caller hooks.
4
+ set -euo pipefail
5
+
6
+ usage() {
7
+ cat <<'USAGE'
8
+ Usage: reset-worktree.sh --base-ref <ref> [--force] [--root <dir>]
9
+ [--cache <path>]... [--pre <command>] [--post <command>]
10
+
11
+ Fetches <ref> when it names a remote branch (remote/branch), refuses a dirty
12
+ or untracked tree unless --force, then checks out reset-<hex> and hard-resets
13
+ it to <ref>. --pre runs after fetch and before the branch switch. --post runs
14
+ after cache removal. Each --cache value is a relative path removed from the
15
+ root. The script also removes .cache directories, and the direct .cache, .vite,
16
+ and .vitest directories inside node_modules.
17
+ USAGE
18
+ }
19
+
20
+ if [ "$#" -eq 1 ] && { [ "$1" = "--help" ] || [ "$1" = "-h" ]; }; then
21
+ usage
22
+ exit 0
23
+ fi
24
+
25
+ FORCE=false
26
+ BASE_REF=
27
+ ROOT=
28
+ PRE_HOOK=
29
+ POST_HOOK=
30
+ CACHES=()
31
+ ORIGINAL_ARGS=("$@")
32
+
33
+ require_value() {
34
+ if [ "$#" -lt 2 ] || [ -z "${2:-}" ]; then
35
+ echo "Error: $1 requires a value" >&2
36
+ usage >&2
37
+ exit 2
38
+ fi
39
+ }
40
+
41
+ reject_duplicate() {
42
+ echo "Error: duplicate option: $1" >&2
43
+ usage >&2
44
+ exit 2
45
+ }
46
+
47
+ while [ "$#" -gt 0 ]; do
48
+ case "$1" in
49
+ --force|-f)
50
+ if $FORCE; then reject_duplicate "$1"; fi
51
+ FORCE=true
52
+ shift
53
+ ;;
54
+ --help|-h)
55
+ echo "Error: help cannot be combined with other arguments" >&2
56
+ usage >&2
57
+ exit 2
58
+ ;;
59
+ --base-ref)
60
+ if [ -n "$BASE_REF" ]; then reject_duplicate "$1"; fi
61
+ require_value "$@"
62
+ BASE_REF=$2
63
+ shift 2
64
+ ;;
65
+ --root)
66
+ if [ -n "$ROOT" ]; then reject_duplicate "$1"; fi
67
+ require_value "$@"
68
+ ROOT=$2
69
+ shift 2
70
+ ;;
71
+ --pre)
72
+ if [ -n "$PRE_HOOK" ]; then reject_duplicate "$1"; fi
73
+ require_value "$@"
74
+ PRE_HOOK=$2
75
+ shift 2
76
+ ;;
77
+ --post)
78
+ if [ -n "$POST_HOOK" ]; then reject_duplicate "$1"; fi
79
+ require_value "$@"
80
+ POST_HOOK=$2
81
+ shift 2
82
+ ;;
83
+ --cache)
84
+ require_value "$@"
85
+ CACHES+=("$2")
86
+ shift 2
87
+ ;;
88
+ *)
89
+ echo "Error: unknown option: $1" >&2
90
+ usage >&2
91
+ exit 2
92
+ ;;
93
+ esac
94
+ done
95
+
96
+ if [ -z "$BASE_REF" ]; then
97
+ echo "Error: --base-ref is required" >&2
98
+ usage >&2
99
+ exit 2
100
+ fi
101
+
102
+ case "$BASE_REF" in
103
+ -*)
104
+ echo "Error: --base-ref must not start with '-': $BASE_REF" >&2
105
+ exit 2
106
+ ;;
107
+ esac
108
+
109
+ ROOT=$(cd "${ROOT:-.}" && pwd -P)
110
+ ROOT=$(git -C "$ROOT" rev-parse --show-toplevel 2>/dev/null) || {
111
+ echo "Error: not inside a git worktree: $ROOT" >&2
112
+ exit 2
113
+ }
114
+
115
+ # shellcheck source=reset-worktree-run.sh
116
+ source "$(dirname "$0")/reset-worktree-run.sh"
117
+ acquire_reset_lock
118
+ if $RESET_UNDER_LOCKF; then
119
+ reset_worktree
120
+ else
121
+ run_reset_supervised reset_worktree
122
+ fi
@@ -55,70 +55,10 @@ human which case applies before continuing:
55
55
  was unavailable, the `pendingCount` and `worktreePendingCount` (or that none was written), and
56
56
  each unjournaled finding.
57
57
 
58
- Prefer restoring MCP over the CLI fallback below, and use the fallback only when the human asks or
59
- MCP cannot be restored for this session. Harness sandboxes commonly withhold
60
- `AGENT_BLACKBOARD_TOKEN` from shell commands, so the fallback usually cannot deliver there. Never
61
- request an unsandboxed run only to obtain the token. When the fallback is used, record its reason,
62
- entrypoint, affected operations, and observed delivery status in the caller's journal. Do not treat
63
- a permission denial as tool unavailability or bypass a host approval requirement through the CLI.
64
- If neither path persists the note, stop and report the blocker.
65
-
66
- ## CLI fallback
67
-
68
- Deprecated and being phased out: the MCP tools replace it, and retrospective and PR writers are
69
- moving to MCP tools as well.
70
-
71
- Use a trusted machine-installed `vouchington` executable at a verified absolute path outside the
72
- consumer worktree. Resolve its symlinks and verify the installation's source and version before
73
- using credentials; its runtime dependencies must also belong to
74
- that trusted installation. The CLI resolves its client relative to its own installation; installing
75
- `agent-blackboard` only in the consumer worktree is insufficient for CLI fallback. Do not resolve the executable through the consumer's `node_modules/.bin`,
76
- `pnpm exec`, or repository-controlled `PATH`. Set `BLACKBOARD_CLI` below to that verified absolute
77
- script path, and bind any approval request to the same interpreter, script, and arguments.
78
- Never execute the script directly: its `#!/usr/bin/env node` line would pick whichever `node` comes
79
- first on `PATH`, which a consumer worktree can control. Set `BLACKBOARD_NODE` to a verified
80
- absolute Node 24+ binary outside the consumer worktree, and run it with `env -i` so only `HOME`, a
81
- fixed system `PATH`, and the two blackboard variables reach it. That also drops `NODE_OPTIONS` and
82
- other loader variables. If no trusted CLI is
83
- available, report the blocker; do not escalate a consumer-supplied executable. For local development,
84
- the reviewed source CLI may run inside the sandbox, subject to the harness's credential policy.
85
- `journal append` invokes the same validated writer as MCP, ensures the exact session identity,
86
- patches its repository union, and verifies delivery. Use a temporary `0600` markdown input file,
87
- remove it after the call, and inspect the JSON result: exit zero can mean retained pending feedback.
88
- The input file is transport to the supported writer, never a replacement journal. Append returns
89
- `pendingCount` for the caller and `worktreePendingCount` for the whole outbox. Use `journal status`
90
- or pass `--session-id` to `journal flush` for the same two counts; an unfiltered legacy flush reports
91
- only the whole-outbox count.
92
-
93
- ```bash
94
- blackboard() {
95
- env -i HOME="$HOME" PATH=/usr/bin:/bin \
96
- AGENT_BLACKBOARD_URL="$AGENT_BLACKBOARD_URL" \
97
- AGENT_BLACKBOARD_TOKEN="$AGENT_BLACKBOARD_TOKEN" \
98
- "$BLACKBOARD_NODE" "$BLACKBOARD_CLI" agent-blackboard "$@"
99
- }
100
- blackboard journal append \
101
- --session-id SESSION --agent AGENT --version VERSION \
102
- --mode interactive --source-event-id EVENT --work-outcome unknown \
103
- --repository owner/name --coverage-status not-assessed --dropped-count 0 \
104
- --outbox-directory "$PWD/.local/blackboard-outbox" --file NOTE
105
- blackboard journal entries --session-id SESSION
106
- blackboard journal status \
107
- --session-id SESSION --outbox-directory "$PWD/.local/blackboard-outbox"
108
- blackboard journal flush \
109
- --session-id SESSION --outbox-directory "$PWD/.local/blackboard-outbox"
110
- ```
111
-
112
- Pass `--parent-session-id` for a child, repeat `--repository` for additional repositories, and use
113
- explicit coverage sources when assessed. Omit `--timestamp` so the writer owns time. Autonomous
114
- mode omits `--outbox-directory` and still requires fresh online admission plus readback.
115
- For session-only or snapshot operations not exposed by this CLI, use the upstream
116
- `agent-blackboard` CLI under its skill's operation contract; preserve exact identities and tags.
117
- A sandboxed fallback may only write the outbox: without `AGENT_BLACKBOARD_TOKEN` it cannot deliver
118
- or read back. Leave the record pending, report `pendingCount`, and deliver it with `outbox_flush`
119
- once MCP is restored. Never read, print, copy, or export the token to work around the sandbox.
120
- Return to MCP when available and journal recovery. Never silently downgrade envelope validation,
121
- retention, or delivery checks because the transport changed.
58
+ Harness sandboxes commonly withhold `AGENT_BLACKBOARD_TOKEN` from shell commands. Never request an
59
+ unsandboxed run only to obtain the token, and do not treat a permission denial as tool
60
+ unavailability or bypass a host approval requirement. If MCP cannot persist the note, stop and
61
+ report the blocker.
122
62
 
123
63
  ## Journaling policy
124
64
 
@@ -63,7 +63,7 @@ a stack, and who may authorize a merge.
63
63
  - Ready every layer in parallel so the stack reaches ready together. A ready lower layer waits
64
64
  while the layers above are close behind (a poll or a ready-delay away).
65
65
  - Drain bottom-up only when the layers above will clearly take longer: a requested change or
66
- `FIX_CODE` still open, a pending human review, a blocker, or CI far longer than the wait so far.
66
+ `TRIAGE` still open, a pending human review, a blocker, or CI far longer than the wait so far.
67
67
  Then merge the ready lower layers in one command whose target is the highest ready layer, state
68
68
  why in the report, and merge the rest together when it is ready.
69
69
  - Re-read every layer's readiness immediately before merging. If the whole stack is ready and
@@ -47,7 +47,7 @@ Run one stack shepherd poll for the assigned stack, and follow its printed instr
47
47
  push to its owner.
48
48
  - Start the shepherd with the first pull request. While the poll is in a pure wait and the
49
49
  worktree is clean, commit the next layer once the lower layer is in decent shape. On a
50
- fix-code result, finish it on the owning layer before more upper edits. A ready-delay schedules
50
+ triage result, finish it on the owning layer before more upper edits. A ready-delay schedules
51
51
  the rerun: continue owned work on a later layer, and do not invent unrelated work.
52
52
  - Never run a printed merge command unless the human's approval covers that layer and every open
53
53
  layer below it, and the checks below pass. `gh stack merge <pr>` lands that pull request and
@@ -96,7 +96,7 @@ target is the top layer, and one command lands it and every layer below it. A sh
96
96
  a merge for a lower layer does not change that; when the whole stack is ready, target the top.
97
97
 
98
98
  Drain bottom-up only when the layers above will clearly take longer than the ready lower layers:
99
- an open requested change or `FIX_CODE`, a pending human review, a blocker, or CI far longer than
99
+ an open requested change or `TRIAGE`, a pending human review, a blocker, or CI far longer than
100
100
  the wait so far. A layer a poll or a ready-delay away is not a reason. Then the target is the
101
101
  highest layer of the ready, approved run from the bottom, still one command, and the report says
102
102
  why the upper layers were left.