vouchington-tooling 0.58.0 → 0.60.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 (162) hide show
  1. package/README.md +80 -0
  2. package/dist/agent-issue-labels/ensure-labels.d.mts +1 -1
  3. package/dist/agent-issue-labels/ensure-labels.mjs +1 -1
  4. package/dist/browser-session-runner/tail-queue.d.mts +1 -1
  5. package/dist/browser-session-runner/tail-queue.mjs +1 -1
  6. package/dist/cli/commands/gitleaks-directory-scan.d.mts +4 -0
  7. package/dist/cli/commands/gitleaks-directory-scan.mjs +9 -0
  8. package/dist/cli/commands/hook.d.mts +2 -0
  9. package/dist/cli/commands/hook.mjs +19 -0
  10. package/dist/cli/commands/transient-retry.d.mts +13 -0
  11. package/dist/cli/commands/transient-retry.mjs +68 -0
  12. package/dist/cli/index.mjs +14 -53
  13. package/dist/cli/parse-forwarded-commands.d.mts +12 -0
  14. package/dist/cli/parse-forwarded-commands.mjs +8 -0
  15. package/dist/cli/parse.d.mts +12 -0
  16. package/dist/cli/script-paths.d.mts +5 -0
  17. package/dist/cli/script-paths.mjs +48 -0
  18. package/dist/cli/usage-text.d.mts +1 -0
  19. package/dist/cli/usage-text.mjs +170 -0
  20. package/dist/cli/usage.d.mts +2 -1
  21. package/dist/cli/usage.mjs +2 -149
  22. package/dist/command-policy/engine.d.mts +7 -0
  23. package/dist/command-policy/engine.mjs +58 -0
  24. package/dist/command-policy/git-patterns.d.mts +20 -0
  25. package/dist/command-policy/git-patterns.mjs +82 -0
  26. package/dist/command-policy/git-process.d.mts +4 -0
  27. package/dist/command-policy/git-process.mjs +54 -0
  28. package/dist/command-policy/github-checkout-owners.d.mts +22 -0
  29. package/dist/command-policy/github-checkout-owners.mjs +122 -0
  30. package/dist/command-policy/github-command-context.d.mts +6 -0
  31. package/dist/command-policy/github-command-context.mjs +19 -0
  32. package/dist/command-policy/github-command-cwd.d.mts +8 -0
  33. package/dist/command-policy/github-command-cwd.mjs +130 -0
  34. package/dist/command-policy/github-command-position.d.mts +7 -0
  35. package/dist/command-policy/github-command-position.mjs +12 -0
  36. package/dist/command-policy/github-configured-base.d.mts +25 -0
  37. package/dist/command-policy/github-configured-base.mjs +59 -0
  38. package/dist/command-policy/github-invocation.d.mts +9 -0
  39. package/dist/command-policy/github-invocation.mjs +80 -0
  40. package/dist/command-policy/github-merge-authority.d.mts +21 -0
  41. package/dist/command-policy/github-merge-authority.mjs +86 -0
  42. package/dist/command-policy/github-option-flags.d.mts +3 -0
  43. package/dist/command-policy/github-option-flags.mjs +67 -0
  44. package/dist/command-policy/github-options.d.mts +12 -0
  45. package/dist/command-policy/github-options.mjs +73 -0
  46. package/dist/command-policy/github-stack-workflow.d.mts +9 -0
  47. package/dist/command-policy/github-stack-workflow.mjs +94 -0
  48. package/dist/command-policy/github-workflow.d.mts +7 -0
  49. package/dist/command-policy/github-workflow.mjs +50 -0
  50. package/dist/command-policy/hook/args.d.mts +11 -0
  51. package/dist/command-policy/hook/args.mjs +49 -0
  52. package/dist/command-policy/hook/harness.d.mts +26 -0
  53. package/dist/command-policy/hook/harness.mjs +119 -0
  54. package/dist/command-policy/hook/policy-module.d.mts +7 -0
  55. package/dist/command-policy/hook/policy-module.mjs +48 -0
  56. package/dist/command-policy/hook/post-tool-use.d.mts +9 -0
  57. package/dist/command-policy/hook/post-tool-use.mjs +51 -0
  58. package/dist/command-policy/hook/pre-tool-use.d.mts +21 -0
  59. package/dist/command-policy/hook/pre-tool-use.mjs +45 -0
  60. package/dist/command-policy/hook/run.d.mts +17 -0
  61. package/dist/command-policy/hook/run.mjs +69 -0
  62. package/dist/command-policy/hook/types.d.mts +33 -0
  63. package/dist/command-policy/hook/types.mjs +5 -0
  64. package/dist/command-policy/index.d.mts +29 -0
  65. package/dist/command-policy/index.mjs +23 -0
  66. package/dist/command-policy/path-references.d.mts +14 -0
  67. package/dist/command-policy/path-references.mjs +68 -0
  68. package/dist/command-policy/path-rules.d.mts +11 -0
  69. package/dist/command-policy/path-rules.mjs +37 -0
  70. package/dist/command-policy/payload.d.mts +8 -0
  71. package/dist/command-policy/payload.mjs +54 -0
  72. package/dist/command-policy/types.d.mts +77 -0
  73. package/dist/command-policy/types.mjs +1 -0
  74. package/dist/dead-code/baseline.d.mts +19 -0
  75. package/dist/dead-code/baseline.mjs +124 -0
  76. package/dist/dead-code/child-command.d.mts +6 -0
  77. package/dist/dead-code/child-command.mjs +107 -0
  78. package/dist/dead-code/cli.d.mts +5 -0
  79. package/dist/dead-code/cli.mjs +71 -0
  80. package/dist/dead-code/entry-roots.d.mts +7 -0
  81. package/dist/dead-code/entry-roots.mjs +43 -0
  82. package/dist/dead-code/fixture-deadline.test-helpers.d.mts +1 -0
  83. package/dist/dead-code/fixture-deadline.test-helpers.mjs +9 -0
  84. package/dist/dead-code/gate.d.mts +29 -0
  85. package/dist/dead-code/gate.mjs +33 -0
  86. package/dist/dead-code/gate.test-helpers.d.mts +14 -0
  87. package/dist/dead-code/gate.test-helpers.mjs +35 -0
  88. package/dist/dead-code/index.d.mts +9 -0
  89. package/dist/dead-code/index.mjs +7 -0
  90. package/dist/dead-code/scan.d.mts +11 -0
  91. package/dist/dead-code/scan.mjs +37 -0
  92. package/dist/dead-code/tracked-snapshot.d.mts +2 -0
  93. package/dist/dead-code/tracked-snapshot.mjs +72 -0
  94. package/dist/index.d.mts +2 -0
  95. package/dist/index.mjs +1 -0
  96. package/dist/markdown/details-scope.d.mts +1 -1
  97. package/dist/markdown/details-scope.mjs +1 -1
  98. package/dist/tmux/cli-shared.d.mts +18 -0
  99. package/dist/tmux/cli-shared.mjs +8 -0
  100. package/dist/tmux/cli.d.mts +3 -0
  101. package/dist/tmux/cli.mjs +34 -0
  102. package/dist/tmux/config.d.mts +24 -0
  103. package/dist/tmux/config.mjs +91 -0
  104. package/dist/tmux/fake-tmux.test-helpers.d.mts +46 -0
  105. package/dist/tmux/fake-tmux.test-helpers.mjs +105 -0
  106. package/dist/tmux/hook-payload.d.mts +8 -0
  107. package/dist/tmux/hook-payload.mjs +39 -0
  108. package/dist/tmux/index.d.mts +9 -0
  109. package/dist/tmux/index.mjs +7 -0
  110. package/dist/tmux/launcher.d.mts +11 -0
  111. package/dist/tmux/launcher.mjs +127 -0
  112. package/dist/tmux/reminder-post-tool.d.mts +21 -0
  113. package/dist/tmux/reminder-post-tool.mjs +88 -0
  114. package/dist/tmux/runner.d.mts +11 -0
  115. package/dist/tmux/runner.mjs +26 -0
  116. package/dist/tmux/session-name.d.mts +5 -0
  117. package/dist/tmux/session-name.mjs +10 -0
  118. package/dist/tmux/shell-quote.d.mts +9 -0
  119. package/dist/tmux/shell-quote.mjs +16 -0
  120. package/dist/tmux/up.d.mts +2 -0
  121. package/dist/tmux/up.mjs +73 -0
  122. package/dist/tmux/windows.d.mts +18 -0
  123. package/dist/tmux/windows.mjs +50 -0
  124. package/dist/transient-retry/attempts.d.mts +1 -1
  125. package/dist/transient-retry/attempts.mjs +1 -1
  126. package/dist/transient-retry/decision-evaluator.d.mts +3 -3
  127. package/dist/transient-retry/gh-api.d.mts +30 -0
  128. package/dist/transient-retry/gh-api.mjs +68 -0
  129. package/dist/transient-retry/github-actions-log.d.mts +7 -0
  130. package/dist/transient-retry/github-actions-log.mjs +33 -0
  131. package/dist/transient-retry/index.d.mts +15 -0
  132. package/dist/transient-retry/index.mjs +8 -0
  133. package/dist/transient-retry/log-stream.d.mts +12 -0
  134. package/dist/transient-retry/log-stream.mjs +39 -0
  135. package/dist/transient-retry/log-window.d.mts +18 -0
  136. package/dist/transient-retry/log-window.mjs +94 -0
  137. package/dist/transient-retry/rerun.d.mts +23 -0
  138. package/dist/transient-retry/rerun.mjs +68 -0
  139. package/dist/transient-retry/run-context-annotations.d.mts +7 -0
  140. package/dist/transient-retry/run-context-annotations.mjs +44 -0
  141. package/dist/transient-retry/run-context-jobs.d.mts +20 -0
  142. package/dist/transient-retry/run-context-jobs.mjs +54 -0
  143. package/dist/transient-retry/run-context-logs.d.mts +12 -0
  144. package/dist/transient-retry/run-context-logs.mjs +86 -0
  145. package/dist/transient-retry/run-context-rule-attempts.d.mts +14 -0
  146. package/dist/transient-retry/run-context-rule-attempts.mjs +65 -0
  147. package/dist/transient-retry/run-context-types.d.mts +49 -0
  148. package/dist/transient-retry/run-context-types.mjs +3 -0
  149. package/dist/transient-retry/run-context.d.mts +9 -0
  150. package/dist/transient-retry/run-context.mjs +25 -0
  151. package/dist/transient-retry/run-context.test-helpers.d.mts +16 -0
  152. package/dist/transient-retry/run-context.test-helpers.mjs +56 -0
  153. package/dist/transient-retry/types.d.mts +8 -7
  154. package/dist/vitest-diagnostics/vitest-worker-exit-diagnostics-reporter.mjs +1 -1
  155. package/dist/workflow-secrets-drift/gh.d.mts +1 -1
  156. package/dist/workflow-secrets-drift/gh.mjs +1 -1
  157. package/package.json +16 -1
  158. package/scripts/__pycache__/run_bounded_process.cpython-312.pyc +0 -0
  159. package/scripts/tmux/tmux-agent-reminder.sh +68 -0
  160. package/scripts/tmux/tmux-name.sh +34 -0
  161. package/scripts/tmux/tmux-read-title.sh +13 -0
  162. package/scripts/tmux/tmux-target.sh +130 -0
package/README.md CHANGED
@@ -86,6 +86,12 @@ vouchington harness-assert-gates HARNESS_DISPATCH_ENABLED HARNESS_SHEPHERD_ENABL
86
86
  echo '[{"login":"octocat","type":"User"}]' | vouchington gha-collaborator-trust owner/repo --allow-bot github-actions[bot]
87
87
  vouchington nuget-central-version trusted.props candidate.props metadata.json out.props
88
88
  vouchington verify-workflow-secrets --repo owner/name --inventory .github/workflows/workflow-secrets-inventory.mts
89
+ vouchington tmux up --config tmux.json --no-attach
90
+ vouchington tmux name my-topic
91
+ vouchington tmux read-title
92
+ vouchington tmux agent-reminder session-start
93
+ vouchington tmux post-tool < hook-payload.json
94
+ vouchington dead-code --baseline dead-code-baseline.json --config .jscpd.json --update
89
95
  vouchington swift-semantic-equal BASE HEAD App.swift
90
96
  vouchington post-review
91
97
  vouchington stage-review-payload optional|required <source> <destination>
@@ -250,6 +256,25 @@ The script also deletes `.cache` directories and the direct `.cache`, `.vite`, a
250
256
  directories inside `node_modules`. It needs `flock` or `lockf` and holds
251
257
  `.local/reset-worktree.lock` for the run.
252
258
 
259
+ ## Rerunning known-transient workflow failures
260
+
261
+ `vouchington transient-retry --rules <module> [--repo owner/name] [--token-env NAME] [--dry-run]
262
+ <run-id>` fetches a failed GitHub Actions run, evaluates the rules your module exports, and runs
263
+ `gh run rerun` only when a rule asks for a rerun. The engine ships no rules: the module exports
264
+ `rules` (an array of `WorkflowRetryRule`) and optionally `limits`. It exits 0 when a rerun was
265
+ requested (or would be, with `--dry-run`), 2 when none is warranted, and 1 on error. The repository
266
+ comes from `--repo`, `GITHUB_REPOSITORY`, or the checkout; `--token-env` names the variable that
267
+ holds the token, which is passed to `gh` as `GH_TOKEN`.
268
+
269
+ Rules receive a `WorkflowRunContext`: job names, conclusions and steps, plus failed-job logs and
270
+ annotations that are fetched only when a rule reads them. Logs may contain secrets, so they are
271
+ streamed and never buffered whole: each job keeps a head window and a tail window
272
+ (`limits.headBytes`, `limits.tailBytes`), reading stops at `limits.maxReadBytes`, and the run keeps
273
+ at most `limits.totalBytes` in all. A log that cannot be read is reported through
274
+ `failedJobLogFetchFailures` with empty text. Only job names and the decision are printed. The same
275
+ pieces are exported from `vouchington-tooling/transient-retry` (`rerunKnownTransient`,
276
+ `buildWorkflowRunContext`, `createGhApi`).
277
+
253
278
  ## Reclaiming finished worktrees
254
279
 
255
280
  `vouchington worktree reclaim [--yes] [--json]` removes git worktrees whose work is done. It is a
@@ -370,6 +395,8 @@ import { runAstGrepExamples } from 'vouchington-tooling/ast-grep-examples'
370
395
  import { astGrepPackPaths } from 'vouchington-tooling/ast-grep-pack'
371
396
  import { validateNugetUpdate } from 'vouchington-tooling/nuget-central-version'
372
397
  import { runVerifyWorkflowSecretsCli } from 'vouchington-tooling/workflow-secrets-drift'
398
+ import { launchSession, loadTmuxConfig } from 'vouchington-tooling/tmux'
399
+ import { runDeadCodeGate } from 'vouchington-tooling/dead-code'
373
400
  import { normalizeSwiftSource } from 'vouchington-tooling/swift-semantic-equal'
374
401
  import { parseUniqueSwiftBinaryTargetChecksum } from 'vouchington-tooling/swift-source-offset'
375
402
  import { validateResolvedPinDelta } from 'vouchington-tooling/swift-resolved-pin-delta'
@@ -393,6 +420,24 @@ import { tokenizeShellWords } from 'vouchington-tooling/shell-parse'
393
420
 
394
421
  `vouchington-tooling/shell-parse` splits shell text into words, heredocs, redirections, and command prefixes. Callers pass the text. The parser does not decide which commands are allowed. `stripQuotedShellText` and `commandsToInspect*` do not scan `$(...)` substitutions in the command text: call `extractShellCommandSubstitutions` and inspect each result too.
395
422
 
423
+ `vouchington-tooling/command-policy` judges a tool call's shell command against a rule table the
424
+ caller supplies. `evaluateCommandPolicy(payload, policy, { automationContext })` returns a
425
+ `BlockDecision` or `null`. The `CommandPolicy` table holds typo paths, protected paths (blocked only
426
+ in automation), command and git regex rules (`standardGitPatterns()` is an opt-in preset), and an
427
+ optional `stack` section for `gh stack` workflow rules. Merge authority is generic: automation never
428
+ merges, and one plain interactive `gh pr merge` yields a `confirm` disposition. Every path, reason,
429
+ base branch, and guidance pointer is a parameter; the module has no repository-specific rules. The
430
+ GitHub command parsing it uses (invocations, options, command position and working directory,
431
+ checkout owners) is exported too.
432
+
433
+ `vouchington hook pre-tool-use|post-tool-use --harness claude|codex|cursor|grok --policy <module>`
434
+ runs that engine as a harness hook. Register it in each harness's hook configuration with the
435
+ repository's own policy module, which default-exports a `HookPolicy` (`defineHookPolicy`): a
436
+ `command` rule table, post-tool-use `checkers`, an optional `reminder`, and an optional `onPayload`
437
+ callback (for example to persist the harness session id). `pre-tool-use` exits 2 to block, including
438
+ when the module cannot load; `post-tool-use` is advisory and always exits 0, folding checker warnings
439
+ and the reminder into one `additionalContext`. `--root` defaults to the working directory. `--automation-env NAME` (repeatable) names an extra environment variable that marks the run unattended when it is set and not empty, `0`, or `false`; CI markers and `claude -p` always count. Register `post-tool-use` with an edit-only matcher (for example `Edit|Write|apply_patch`): the command treats every `file_path` it sees as an edit, and it emits the Claude/Codex `hookSpecificOutput` shape for every harness.
440
+
396
441
  `processDiffCommand` runs a caller-supplied `git diff` or `gh pr diff` executable and argv without
397
442
  a shell, emitting complete unified-diff file blocks without accumulating the whole patch. It keeps
398
443
  at most one file block (which can itself be large), preserves preambles and line content, and drains
@@ -925,3 +970,38 @@ The check preserves the existing nested SELECT/CTE, equality, inner-join, and co
925
970
  heuristics. It rejects weakened OR/NOT/boolean/CASE predicates and non-filtering left joins. Every
926
971
  recognized live source reader must be protected. Unparseable SQL fragments are skipped; malformed
927
972
  source returns false. These are bounded syntactic heuristics, not a general SQL safety proof.
973
+
974
+ ## tmux dev sessions
975
+
976
+ `vouchington tmux up --config <file>` starts the windows named in a JSON config inside one tmux
977
+ session per worktree (`<sessionPrefix>d<hash of the worktree path>`), reuses a running session,
978
+ and respawns dead windows. The config holds everything product-specific:
979
+
980
+ ```json
981
+ {
982
+ "sessionPrefix": "dev-",
983
+ "readyMarker": "ready",
984
+ "launcherPidVar": "TMUX_LAUNCHER_PID",
985
+ "env": { "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318" },
986
+ "summary": ["Web: http://localhost:3000"],
987
+ "windows": [
988
+ {
989
+ "name": "web",
990
+ "cwd": "web",
991
+ "command": "pnpm run dev",
992
+ "env": { "OTEL_SERVICE_NAME": "web" }
993
+ },
994
+ { "name": "api", "command": "node --watch api.mts" }
995
+ ]
996
+ }
997
+ ```
998
+
999
+ Windows run through `bash -lc '<command>; read'` (`"keepOpen": false` drops the `; read`).
1000
+ `--verbose` sets `TMUX_LOG_LEVEL=info` (default `error`) in every window. The tmux binary comes
1001
+ from `TMUX_TARGET_BIN`, the worktree from `TMUX_TARGET_ROOT` (default: current directory).
1002
+
1003
+ `tmux name`, `tmux read-title` and `tmux agent-reminder` verify that the pane (from
1004
+ `--socket/--pane/--worktree` or `AGENT_TMUX_SOCKET/PANE/WORKTREE`) belongs to the worktree before
1005
+ touching it. `tmux post-tool` reads an agent post-tool hook payload on stdin and prints a rename
1006
+ reminder at plan, PR, push and reset checkpoints; reminders name `TMUX_NAME_COMMAND` (default
1007
+ `vouchington tmux name`).
@@ -1,4 +1,4 @@
1
- import { type RunTextCommand } from '../gh-cli/exec.mts';
1
+ import { type RunTextCommand } from '../gh-cli/index.mts';
2
2
  import { type LabelPolicy } from './label-policy.mts';
3
3
  export type EnsureLabelsOptions = {
4
4
  labels: readonly string[];
@@ -1,4 +1,4 @@
1
- import { runGh } from "../gh-cli/exec.mjs";
1
+ import { runGh } from "../gh-cli/index.mjs";
2
2
  import { DEFAULT_LABEL_POLICY, labelMetadata } from "./label-policy.mjs";
3
3
  /**
4
4
  * Creates missing repository labels through `gh` (or force-updates all with `update`). Every label
@@ -1,7 +1,7 @@
1
1
  export declare class TailQueue {
2
- readonly maxBytes: number;
3
2
  readonly chunks: Buffer[];
4
3
  bytes: number;
4
+ readonly maxBytes: number;
5
5
  constructor(maxBytes: number);
6
6
  append(text: string): void;
7
7
  toBuffer(): Buffer;
@@ -1,7 +1,7 @@
1
1
  export class TailQueue {
2
- maxBytes;
3
2
  chunks = [];
4
3
  bytes = 0;
4
+ maxBytes;
5
5
  constructor(maxBytes) {
6
6
  this.maxBytes = maxBytes;
7
7
  }
@@ -0,0 +1,4 @@
1
+ export declare function runGitleaksDirectoryScanCommand(parsed: {
2
+ config: string;
3
+ directory?: string | undefined;
4
+ }): number | Promise<number>;
@@ -0,0 +1,9 @@
1
+ import { packageScriptPath } from "../script-path.mjs";
2
+ import { runScript } from "./spawn-script.mjs";
3
+ export function runGitleaksDirectoryScanCommand(parsed) {
4
+ return runScript('bash', packageScriptPath('scripts/gitleaks-directory-scan.sh'), [
5
+ '--config',
6
+ parsed.config,
7
+ ...(parsed.directory === undefined ? [] : ['--root', parsed.directory]),
8
+ ]);
9
+ }
@@ -0,0 +1,2 @@
1
+ /** `vouchington hook pre-tool-use|post-tool-use`: see `runHook`. */
2
+ export declare function runHookCommand(args: string[]): Promise<number>;
@@ -0,0 +1,19 @@
1
+ import { runHook } from "../../command-policy/hook/run.mjs";
2
+ async function readStdin() {
3
+ if (process.stdin.isTTY)
4
+ return '';
5
+ const chunks = [];
6
+ for await (const chunk of process.stdin)
7
+ chunks.push(chunk);
8
+ return Buffer.concat(chunks).toString('utf8');
9
+ }
10
+ /** `vouchington hook pre-tool-use|post-tool-use`: see `runHook`. */
11
+ export function runHookCommand(args) {
12
+ return runHook(args, {
13
+ readStdin,
14
+ stdout: process.stdout,
15
+ stderr: process.stderr,
16
+ env: process.env,
17
+ cwd: process.cwd(),
18
+ });
19
+ }
@@ -0,0 +1,13 @@
1
+ import type { LogLimits } from '../../transient-retry/log-window.mts';
2
+ interface RulesModule {
3
+ rules?: unknown;
4
+ limits?: Partial<LogLimits>;
5
+ }
6
+ type LoadModule = (specifier: string) => Promise<RulesModule>;
7
+ /**
8
+ * `vouchington transient-retry --rules <module> [--repo owner/name] [--token-env NAME] [--dry-run]
9
+ * <run-id>`. The module must export `rules` (an array of retry rules) and may export `limits`.
10
+ * Exits 0 when a rerun was requested, 2 when none is warranted, 1 on error.
11
+ */
12
+ export declare function runTransientRetryCommand(args: readonly string[], env?: NodeJS.ProcessEnv, load?: LoadModule): Promise<number>;
13
+ export {};
@@ -0,0 +1,68 @@
1
+ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
2
+ if (typeof path === "string" && /^\.\.?\//.test(path)) {
3
+ return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
4
+ return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
5
+ });
6
+ }
7
+ return path;
8
+ };
9
+ import { resolve } from 'node:path';
10
+ import { pathToFileURL } from 'node:url';
11
+ import { parseArgs } from 'node:util';
12
+ import { createGhApi, createGhRunner } from "../../transient-retry/gh-api.mjs";
13
+ import { createGhLogStreamer } from "../../transient-retry/log-stream.mjs";
14
+ import { rerunKnownTransient } from "../../transient-retry/rerun.mjs";
15
+ import { commandUsage } from "../usage.mjs";
16
+ const loadModule = (specifier) => import(__rewriteRelativeImportExtension(specifier));
17
+ /**
18
+ * `vouchington transient-retry --rules <module> [--repo owner/name] [--token-env NAME] [--dry-run]
19
+ * <run-id>`. The module must export `rules` (an array of retry rules) and may export `limits`.
20
+ * Exits 0 when a rerun was requested, 2 when none is warranted, 1 on error.
21
+ */
22
+ export async function runTransientRetryCommand(args, env = process.env, load = loadModule) {
23
+ let parsed;
24
+ try {
25
+ parsed = parse(args);
26
+ }
27
+ catch (error) {
28
+ process.stderr.write(`vouchington: ${error.message}\n${commandUsage('transient-retry')}`);
29
+ return 2;
30
+ }
31
+ const { values, positionals } = parsed;
32
+ const [runId, extra] = positionals;
33
+ if (values.rules === undefined || runId === undefined || extra !== undefined) {
34
+ process.stderr.write(`vouchington: expected --rules <module> and one run id\n${commandUsage('transient-retry')}`);
35
+ return 2;
36
+ }
37
+ const repository = values.repo ?? env.GITHUB_REPOSITORY;
38
+ try {
39
+ const module = await load(pathToFileURL(resolve(values.rules)).href);
40
+ if (!Array.isArray(module.rules))
41
+ throw new Error('rules module must export a `rules` array');
42
+ return await rerunKnownTransient({
43
+ api: createGhApi({ run: createGhRunner(values['token-env']) }),
44
+ streamLog: createGhLogStreamer(values['token-env']),
45
+ dryRun: values['dry-run'],
46
+ rules: module.rules,
47
+ runId,
48
+ ...(module.limits === undefined ? {} : { limits: module.limits }),
49
+ ...(repository === undefined ? {} : { repository }),
50
+ });
51
+ }
52
+ catch (error) {
53
+ process.stderr.write(`vouchington: ${error instanceof Error ? error.message : String(error)}\n`);
54
+ return 1;
55
+ }
56
+ }
57
+ function parse(args) {
58
+ return parseArgs({
59
+ args: [...args],
60
+ allowPositionals: true,
61
+ options: {
62
+ 'dry-run': { type: 'boolean', default: false },
63
+ repo: { type: 'string' },
64
+ rules: { type: 'string' },
65
+ 'token-env': { type: 'string' },
66
+ },
67
+ });
68
+ }
@@ -8,11 +8,13 @@ import { runSwiftSemanticEqualCli } from "../swift-semantic-equal/cli.mjs";
8
8
  import { runAgentIssueLabels } from "./commands/agent-issue-labels.mjs";
9
9
  import { runGhaArtifactsCleanup } from "./commands/gha-artifacts-cleanup.mjs";
10
10
  import { runGhaRuntimeAudit } from "./commands/gha-runtime-audit.mjs";
11
+ import { runGitleaksDirectoryScanCommand } from "./commands/gitleaks-directory-scan.mjs";
11
12
  import { runHttpOrigin } from "./commands/http-origin.mjs";
12
13
  import { runPnpmInstallCli } from "./commands/pnpm-install.mjs";
13
14
  import { runRunnerPortPolicy } from "./commands/runner-port-policy.mjs";
14
15
  import { runScript } from "./commands/spawn-script.mjs";
15
16
  import { runNugetCentralVersionCommand } from "./commands/nuget-central-version.mjs";
17
+ import { runDeadCodeCli } from "../dead-code/cli.mjs";
16
18
  import { runVerifyWorkflowSecretsCli } from "../workflow-secrets-drift/cli.mjs";
17
19
  import { runVitestBlobManifestCommand } from "./commands/vitest-blob-manifest.mjs";
18
20
  import { runVitestReportAttemptCommand } from "./commands/vitest-report-attempt.mjs";
@@ -21,8 +23,10 @@ import { runRetrospectiveTranscriptCommand } from "./commands/retrospective-tran
21
23
  import { runLinkSkill } from "./commands/link-skill.mjs";
22
24
  import { runRetrospectiveFactsCommand } from "./commands/retrospective-facts.mjs";
23
25
  import { runAgentBlackboardCommand } from "./commands/agent-blackboard.mjs";
26
+ import { runHookCommand } from "./commands/hook.mjs";
24
27
  import { runMcpCommand } from "./commands/mcp.mjs";
25
28
  import { runWorktreeCommand } from "./commands/worktree.mjs";
29
+ import { runTmuxCommand } from "../tmux/cli.mjs";
26
30
  import { runHostStoragePreflightCli } from "../host-storage/cli.mjs";
27
31
  import { runWithHostLock } from "./commands/with-host-lock.mjs";
28
32
  import { runFreshBase } from "./commands/fresh-base.mjs";
@@ -32,57 +36,10 @@ import { runAstGrepPackCommand } from "./commands/ast-grep-pack.mjs";
32
36
  import { runGhaWorkspacePolicy } from "./commands/gha-workspace-policy.mjs";
33
37
  import { readInstalledVersion } from "./installed-version.mjs";
34
38
  import { parseCli } from "./parse.mjs";
39
+ import { SCRIPT_PATHS } from "./script-paths.mjs";
35
40
  import { runStoryCoverageLazy } from "./story-coverage-lazy.mjs";
36
41
  import { packageScriptPath } from "./script-path.mjs";
37
42
  import { commandUsage, printUsage } from "./usage.mjs";
38
- const SCRIPT_PATHS = {
39
- 'gha-output': { command: 'bash', path: 'scripts/gha/write-github-multiline-output.sh' },
40
- 'gha-needs-results': { command: 'bash', path: 'scripts/gha/check-needs-results.sh' },
41
- 'download-with-diagnostics': {
42
- command: 'bash',
43
- path: 'scripts/gha/download-with-diagnostics.sh',
44
- },
45
- 'download-optional-run-artifacts': {
46
- command: 'bash',
47
- path: 'scripts/gha/download-optional-run-artifacts.sh',
48
- },
49
- 'host-pressure-diagnostics': {
50
- command: 'bash',
51
- path: 'scripts/gha/host-pressure-diagnostics.sh',
52
- },
53
- 'allocate-browser-safe-ports': {
54
- command: 'python3',
55
- path: 'scripts/allocate-browser-safe-ports.py',
56
- },
57
- 'diagnose-port-collision': {
58
- command: 'bash',
59
- path: 'scripts/gha/diagnose-port-collision.sh',
60
- },
61
- 'prepare-trivy-db': { command: 'bash', path: 'scripts/gha/prepare-trivy-db.sh' },
62
- 'check-cache-size': { command: 'bash', path: 'scripts/gha/check-cache-size.sh' },
63
- 'make-shard-matrix': { command: 'bash', path: 'scripts/gha/make-shard-matrix.sh' },
64
- 'load-runner-env': { command: 'bash', path: 'scripts/gha/load-runner-env.sh' },
65
- 'clean-workspace': { command: 'bash', path: 'scripts/gha/clean-workspace.sh' },
66
- 'install-github-release': { command: 'bash', path: 'scripts/gha/install-github-release.sh' },
67
- 'run-with-timeout': { command: 'bash', path: 'scripts/gha/run-with-timeout.sh' },
68
- 'lint-links': { command: 'bash', path: 'scripts/gha/lint-links.sh' },
69
- 'materialize-pr-context': { command: 'bash', path: 'scripts/gha/materialize-pr-context.sh' },
70
- 'wait-for-apt-locks': { command: 'bash', path: 'scripts/gha/wait-for-apt-locks.sh' },
71
- 'install-playwright-chromium-arm64': {
72
- command: 'bash',
73
- path: 'scripts/gha/install-playwright-chromium-arm64.sh',
74
- },
75
- 'ghcr-package-retention': { command: 'bash', path: 'scripts/gha/ghcr-package-retention.sh' },
76
- 'harness-admission-lane': {
77
- command: 'bash',
78
- path: 'scripts/gha/harness-admission-lane.sh',
79
- },
80
- 'harness-assert-gates': { command: 'bash', path: 'scripts/gha/harness-assert-gates.sh' },
81
- 'gha-collaborator-trust': {
82
- command: 'bash',
83
- path: 'scripts/gha/gha-collaborator-trust.sh',
84
- },
85
- };
86
43
  export function runCli(argv = process.argv) {
87
44
  const parsed = parseCli(argv);
88
45
  switch (parsed.kind) {
@@ -123,6 +80,8 @@ export function runCli(argv = process.argv) {
123
80
  return runNugetCentralVersionCommand(parsed.args);
124
81
  case 'verify-workflow-secrets':
125
82
  return runVerifyWorkflowSecretsCli(parsed.args);
83
+ case 'dead-code':
84
+ return runDeadCodeCli(parsed.args);
126
85
  case 'swift-semantic-equal':
127
86
  return runSwiftSemanticEqualCli(parsed.args);
128
87
  case 'post-review':
@@ -147,18 +106,20 @@ export function runCli(argv = process.argv) {
147
106
  return runAgentBlackboardCommand(parsed.args);
148
107
  case 'mcp':
149
108
  return runMcpCommand(parsed.args);
109
+ case 'transient-retry':
110
+ return import("./commands/transient-retry.mjs").then((command) => command.runTransientRetryCommand(parsed.args));
111
+ case 'hook':
112
+ return runHookCommand(parsed.args);
150
113
  case 'worktree':
151
114
  return runWorktreeCommand(parsed.args);
115
+ case 'tmux':
116
+ return runTmuxCommand(parsed.args);
152
117
  case 'require-up-to-date':
153
118
  return runRequireUpToDate(parsed);
154
119
  case 'fresh-base':
155
120
  return runFreshBase(parsed);
156
121
  case 'gitleaks-directory-scan':
157
- return runScript('bash', packageScriptPath('scripts/gitleaks-directory-scan.sh'), [
158
- '--config',
159
- parsed.config,
160
- ...(parsed.directory === undefined ? [] : ['--root', parsed.directory]),
161
- ]);
122
+ return runGitleaksDirectoryScanCommand(parsed);
162
123
  case 'ast-grep-examples':
163
124
  return runAstGrepExamplesCommand(parsed);
164
125
  case 'ast-grep-pack':
@@ -22,6 +22,9 @@ type ForwardedCommand = {
22
22
  } | {
23
23
  kind: 'verify-workflow-secrets';
24
24
  args: string[];
25
+ } | {
26
+ kind: 'dead-code';
27
+ args: string[];
25
28
  } | {
26
29
  kind: 'swift-semantic-equal';
27
30
  args: string[];
@@ -43,9 +46,18 @@ type ForwardedCommand = {
43
46
  } | {
44
47
  kind: 'mcp';
45
48
  args: string[];
49
+ } | {
50
+ kind: 'hook';
51
+ args: string[];
46
52
  } | {
47
53
  kind: 'worktree';
48
54
  args: string[];
55
+ } | {
56
+ kind: 'transient-retry';
57
+ args: string[];
58
+ } | {
59
+ kind: 'tmux';
60
+ args: string[];
49
61
  };
50
62
  export declare function parseForwardedCommand(command: string | undefined, args: string[]): ForwardedCommand | undefined;
51
63
  export {};
@@ -15,6 +15,8 @@ export function parseForwardedCommand(command, args) {
15
15
  return { kind: 'nuget-central-version', args };
16
16
  if (command === 'verify-workflow-secrets')
17
17
  return { kind: 'verify-workflow-secrets', args };
18
+ if (command === 'dead-code')
19
+ return { kind: 'dead-code', args };
18
20
  if (command === 'swift-semantic-equal')
19
21
  return { kind: 'swift-semantic-equal', args };
20
22
  if (command === 'post-review')
@@ -29,7 +31,13 @@ export function parseForwardedCommand(command, args) {
29
31
  return { kind: 'agent-blackboard', args };
30
32
  if (command === 'mcp')
31
33
  return { kind: 'mcp', args };
34
+ if (command === 'hook')
35
+ return { kind: 'hook', args };
32
36
  if (command === 'worktree')
33
37
  return { kind: 'worktree', args };
38
+ if (command === 'transient-retry')
39
+ return { kind: 'transient-retry', args };
40
+ if (command === 'tmux')
41
+ return { kind: 'tmux', args };
34
42
  return undefined;
35
43
  }
@@ -44,6 +44,9 @@ export type ParsedCli = {
44
44
  } | {
45
45
  kind: 'verify-workflow-secrets';
46
46
  args: string[];
47
+ } | {
48
+ kind: 'dead-code';
49
+ args: string[];
47
50
  } | {
48
51
  kind: 'swift-semantic-equal';
49
52
  args: string[];
@@ -74,9 +77,18 @@ export type ParsedCli = {
74
77
  } | {
75
78
  kind: 'mcp';
76
79
  args: string[];
80
+ } | {
81
+ kind: 'hook';
82
+ args: string[];
77
83
  } | {
78
84
  kind: 'worktree';
79
85
  args: string[];
86
+ } | {
87
+ kind: 'transient-retry';
88
+ args: string[];
89
+ } | {
90
+ kind: 'tmux';
91
+ args: string[];
80
92
  } | {
81
93
  kind: 'require-up-to-date';
82
94
  remote: string;
@@ -0,0 +1,5 @@
1
+ import type { ScriptCommand } from './parse.mts';
2
+ export declare const SCRIPT_PATHS: Record<ScriptCommand, {
3
+ command: string;
4
+ path: string;
5
+ }>;
@@ -0,0 +1,48 @@
1
+ export const SCRIPT_PATHS = {
2
+ 'gha-output': { command: 'bash', path: 'scripts/gha/write-github-multiline-output.sh' },
3
+ 'gha-needs-results': { command: 'bash', path: 'scripts/gha/check-needs-results.sh' },
4
+ 'download-with-diagnostics': {
5
+ command: 'bash',
6
+ path: 'scripts/gha/download-with-diagnostics.sh',
7
+ },
8
+ 'download-optional-run-artifacts': {
9
+ command: 'bash',
10
+ path: 'scripts/gha/download-optional-run-artifacts.sh',
11
+ },
12
+ 'host-pressure-diagnostics': {
13
+ command: 'bash',
14
+ path: 'scripts/gha/host-pressure-diagnostics.sh',
15
+ },
16
+ 'allocate-browser-safe-ports': {
17
+ command: 'python3',
18
+ path: 'scripts/allocate-browser-safe-ports.py',
19
+ },
20
+ 'diagnose-port-collision': {
21
+ command: 'bash',
22
+ path: 'scripts/gha/diagnose-port-collision.sh',
23
+ },
24
+ 'prepare-trivy-db': { command: 'bash', path: 'scripts/gha/prepare-trivy-db.sh' },
25
+ 'check-cache-size': { command: 'bash', path: 'scripts/gha/check-cache-size.sh' },
26
+ 'make-shard-matrix': { command: 'bash', path: 'scripts/gha/make-shard-matrix.sh' },
27
+ 'load-runner-env': { command: 'bash', path: 'scripts/gha/load-runner-env.sh' },
28
+ 'clean-workspace': { command: 'bash', path: 'scripts/gha/clean-workspace.sh' },
29
+ 'install-github-release': { command: 'bash', path: 'scripts/gha/install-github-release.sh' },
30
+ 'run-with-timeout': { command: 'bash', path: 'scripts/gha/run-with-timeout.sh' },
31
+ 'lint-links': { command: 'bash', path: 'scripts/gha/lint-links.sh' },
32
+ 'materialize-pr-context': { command: 'bash', path: 'scripts/gha/materialize-pr-context.sh' },
33
+ 'wait-for-apt-locks': { command: 'bash', path: 'scripts/gha/wait-for-apt-locks.sh' },
34
+ 'install-playwright-chromium-arm64': {
35
+ command: 'bash',
36
+ path: 'scripts/gha/install-playwright-chromium-arm64.sh',
37
+ },
38
+ 'ghcr-package-retention': { command: 'bash', path: 'scripts/gha/ghcr-package-retention.sh' },
39
+ 'harness-admission-lane': {
40
+ command: 'bash',
41
+ path: 'scripts/gha/harness-admission-lane.sh',
42
+ },
43
+ 'harness-assert-gates': { command: 'bash', path: 'scripts/gha/harness-assert-gates.sh' },
44
+ 'gha-collaborator-trust': {
45
+ command: 'bash',
46
+ path: 'scripts/gha/gha-collaborator-trust.sh',
47
+ },
48
+ };
@@ -0,0 +1 @@
1
+ export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n runner-port-policy Print or validate a runner port policy\n with-host-lock Run a command under a host-wide lock\n host-storage Check free space on caller-supplied paths\n gha-runtime-audit Audit successful GitHub Actions job runtimes\n require-up-to-date Require HEAD to include a fetched remote branch\n fresh-base Classify the worktree against a remote base branch\n gitleaks-directory-scan Scan a directory with Gitleaks\n ast-grep-examples Run AST-grep rule examples\n ast-grep-pack Print shipped unconditional AST-grep pack paths as JSON\n gha-workspace-policy Check GitHub Actions workspace safety policy\n gha-output Write a collision-safe multiline GITHUB_OUTPUT record\n gha-needs-results Fail if required GitHub Actions job results failed\n download-with-diagnostics Download a URL and report HTTP status on failure\n download-optional-run-artifacts Download optional artifacts from the current run\n host-pressure-diagnostics Print a bounded host memory/OOM/PSI snapshot\n allocate-browser-safe-ports Allocate Fetch-safe localhost ports\n diagnose-port-collision Capture bounded localhost port diagnostics\n prepare-trivy-db Download the Trivy vulnerability database\n gha-artifacts-cleanup Delete classified GitHub Actions artifacts\n agent-issue-labels Map changed paths to labels; create missing repository labels\n http-origin Validate an optional HTTP(S) origin\n vitest-blob-manifest Stamp a vitest-blob-manifest:v1 identity file\n vitest-report-attempt Write or read a Vitest report-attempt marker\n prepare-vitest-reports Validate and select Vitest report JSON files\n pnpm-install Install a pnpm workspace with retry and release-age fail-fast\n check-cache-size Measure a path and decide whether to save a GHA cache\n make-shard-matrix Emit a [1..N] GitHub Actions shard matrix\n load-runner-env Overlay a runner env file onto GITHUB_ENV with injection guards\n clean-workspace Reset a persistent-runner workspace with a fork-PR trust gate\n install-github-release Download a checksum-verified GitHub Release binary\n run-with-timeout Run a command with GNU timeout or a Perl fallback\n lint-links Two-pass lychee: internal links fail, external warn\n materialize-pr-context Dump PR title/body/files/diff/comments and #N crawl\n wait-for-apt-locks Wait until apt/dpkg lock files are free\n install-playwright-chromium-arm64 Install Playwright Chromium from browsers.json\n ghcr-package-retention Delete old GHCR package versions (KEEP_MIN or --main-history)\n harness-admission-lane Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n harness-assert-gates Fail if any named HARNESS_*_ENABLED gate is enabled\n gha-collaborator-trust Classify authors as write-access collaborators or not\n nuget-central-version Validate a Directory.Packages.props PackageVersion delta\n verify-workflow-secrets Check a secret inventory against live repository and environment secrets\n dead-code Gate unused code against a committed jscpd baseline\n swift-semantic-equal Compare Swift sources ignoring comments and whitespace\n post-review Post one COMMENT review from a staged payload file\n stage-review-payload Validate a review payload file into a staging directory\n retrospective-transcript Format facts from Claude-compatible, Codex, or Grok transcripts\n link-skill Link one packaged skill into an explicit consumer directory\n retrospective-facts Gather immutable facts for a retrospective\n agent-blackboard Probe an Agent Blackboard deployment, classify distill sessions, manage snapshots\n mcp Serve the agent-blackboard journal tools over stdio (MCP)\n hook Run a repository policy module as a pre/post tool-use hook\n worktree Reclaim finished git worktrees (dry run unless --yes)\n tmux Run configured dev windows in tmux; name panes; agent reminders\n story-coverage Check component exports are imported by stories\n transient-retry Rerun a failed GitHub Actions run when an injected rule matches\n\nOptions:\n -h, --help Show this help\n -v, --version Print the package version\n\nrunner-port-policy\n (no args) Print the shipped policy as JSON\n --file <path> Validate and print a policy file\n --reserved <port> Print true if the port is reserved\n\nwith-host-lock\n --name <family>\n [--slots <n>]\n --timeout-seconds <n>\n [--command-timeout-seconds <n>]\n [--failure-diagnostics <absolute-script>]\n [--on-acquire-timeout fail|run-unlocked]\n -- <command> [args...]\n\nhost-storage --path <path> [--path <path>...] [--minimum-free-bytes <bytes>] [--pnpm-store] [--docker-root] [--docker-desktop-path <path>] [--discovery-timeout-ms <ms>]\n\ngha-runtime-audit\n [--repository owner/name] Default GITHUB_REPOSITORY\n [--branch main]\n [--median-threshold-floor <seconds>] Off unless set. Must be below the ceiling\n [--median-threshold-ceiling <seconds>] Default 360. Flags a five-sample median above this\n --pr-workflow <name|/regex/> Repeatable\n --push-workflow <name|/regex/> Repeatable\n\nrequire-up-to-date --remote <name> --branch <name>\nfresh-base [--remote <name>] [--branch <name>] [--skip-fetch]\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name>... | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports <count> [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nagent-issue-labels labels-from-paths [--labeler <path>] <path>...\nagent-issue-labels ensure-labels [--repo owner/name] [--policy-file json] [--update] <label>...\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention [--main-history] [--apply|--dry-run] [<url-encoded-package>...]\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nverify-workflow-secrets [--repo OWNER/NAME] [--confirm NAME,...] [--inventory MODULE] [--export NAME] [--branch NAME]\ndead-code --baseline PATH [--seed|--update] [--config PATH] [--binary PATH] [--repo-root PATH] [--entry GLOB]... [--snapshot-ignore GLOB]... [--exclude GLOB]...\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir> Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard session-start [--skip-env NAME] [--setup-hint TEXT] [--docs-path PATH] [--restore-hint TEXT] [--timeout-ms N] (SessionStart hook; payload on stdin)\nagent-blackboard distill classify <partition.jsonl> --retro-cutoff ISO8601 --session-cutoff ISO8601\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\nmcp\n (no args) Serve journal_append, journal_entries, outbox_status, outbox_flush,\n session_ensure, retrospective_check, retrospective_save,\n pr_validate, pr_create, pr_update,\n snapshot_export, snapshot_cleanup, and session_archive over stdio.\n Needs the optional @modelcontextprotocol/sdk peer (and zod).\n Launch it from inside the repository's git worktree.\n\nhook pre-tool-use|post-tool-use --harness claude|codex|cursor|grok --policy <module> [--root <dir>] [--automation-env NAME]...\n Reads the harness hook payload on stdin. <module> default-exports a policy object (or a function\n of the hook context returning one) with a command rule table, post-tool-use checkers, and an\n optional reminder. pre-tool-use exits 2 to block, and also when the policy cannot load.\n post-tool-use is advisory and always exits 0. --root defaults to the working directory.\n Each --automation-env NAME (repeatable) marks the run unattended when that environment variable\n is set, non-empty, and not 0 or false; CI markers and claude -p are always unattended.\n\nworktree reclaim [--yes] [--json]\n Dry run by default. Removes clean, fully pushed worktrees whose same-repository PR for the\n branch is merged or closed at exactly HEAD, using git worktree remove (never forced).\n Skips the main checkout, the current worktree, and locked, bare or detached worktrees.\n\ntransient-retry --rules <module> [--repo owner/name] [--token-env NAME] [--dry-run] <run-id>\n Loads a module exporting \"rules\" (and optionally \"limits\"), evaluates them against the failed run,\n and reruns only on a match. Exits 0 on rerun, 2 when none is warranted, 1 on error.\n\ntmux up --config <file> [--root <dir>] [--no-attach] [-v|--verbose]\ntmux name [--socket PATH --pane %ID --worktree PATH] <name> | read-title | post-tool | agent-reminder <event>\n Environment: TMUX_TARGET_BIN, TMUX_TARGET_ROOT, TMUX_NAME_COMMAND, AGENT_TMUX_SOCKET/PANE/WORKTREE.\n\nstory-coverage --root <dir> --component-root <rel> --story-root <rel> --source-extension <ext> --component-extension <ext> --marker <regex> --story-pattern <regex> [--alias <prefix>=<path>] [--exclusions <json>] [--exclusions-label <text>]\n";