vouchington-tooling 0.59.0 → 0.61.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 (141) hide show
  1. package/README.md +108 -0
  2. package/dist/cli/commands/hook.d.mts +2 -0
  3. package/dist/cli/commands/hook.mjs +19 -0
  4. package/dist/cli/commands/sandbox-command-audit.d.mts +7 -0
  5. package/dist/cli/commands/sandbox-command-audit.mjs +27 -0
  6. package/dist/cli/index.mjs +8 -0
  7. package/dist/cli/parse-forwarded-commands.d.mts +9 -0
  8. package/dist/cli/parse-forwarded-commands.mjs +6 -0
  9. package/dist/cli/parse.d.mts +9 -0
  10. package/dist/cli/usage-text.d.mts +1 -0
  11. package/dist/cli/usage-text.mjs +179 -0
  12. package/dist/cli/usage.d.mts +2 -1
  13. package/dist/cli/usage.mjs +2 -156
  14. package/dist/command-policy/engine.d.mts +7 -0
  15. package/dist/command-policy/engine.mjs +58 -0
  16. package/dist/command-policy/git-patterns.d.mts +20 -0
  17. package/dist/command-policy/git-patterns.mjs +82 -0
  18. package/dist/command-policy/git-process.d.mts +4 -0
  19. package/dist/command-policy/git-process.mjs +54 -0
  20. package/dist/command-policy/github-checkout-owners.d.mts +22 -0
  21. package/dist/command-policy/github-checkout-owners.mjs +122 -0
  22. package/dist/command-policy/github-command-context.d.mts +6 -0
  23. package/dist/command-policy/github-command-context.mjs +19 -0
  24. package/dist/command-policy/github-command-cwd.d.mts +8 -0
  25. package/dist/command-policy/github-command-cwd.mjs +130 -0
  26. package/dist/command-policy/github-command-position.d.mts +7 -0
  27. package/dist/command-policy/github-command-position.mjs +12 -0
  28. package/dist/command-policy/github-configured-base.d.mts +25 -0
  29. package/dist/command-policy/github-configured-base.mjs +59 -0
  30. package/dist/command-policy/github-invocation.d.mts +9 -0
  31. package/dist/command-policy/github-invocation.mjs +80 -0
  32. package/dist/command-policy/github-merge-authority.d.mts +21 -0
  33. package/dist/command-policy/github-merge-authority.mjs +86 -0
  34. package/dist/command-policy/github-option-flags.d.mts +3 -0
  35. package/dist/command-policy/github-option-flags.mjs +67 -0
  36. package/dist/command-policy/github-options.d.mts +12 -0
  37. package/dist/command-policy/github-options.mjs +73 -0
  38. package/dist/command-policy/github-stack-workflow.d.mts +9 -0
  39. package/dist/command-policy/github-stack-workflow.mjs +94 -0
  40. package/dist/command-policy/github-workflow.d.mts +7 -0
  41. package/dist/command-policy/github-workflow.mjs +50 -0
  42. package/dist/command-policy/hook/args.d.mts +11 -0
  43. package/dist/command-policy/hook/args.mjs +49 -0
  44. package/dist/command-policy/hook/harness.d.mts +26 -0
  45. package/dist/command-policy/hook/harness.mjs +119 -0
  46. package/dist/command-policy/hook/policy-module.d.mts +7 -0
  47. package/dist/command-policy/hook/policy-module.mjs +48 -0
  48. package/dist/command-policy/hook/post-tool-use.d.mts +9 -0
  49. package/dist/command-policy/hook/post-tool-use.mjs +51 -0
  50. package/dist/command-policy/hook/pre-tool-use.d.mts +21 -0
  51. package/dist/command-policy/hook/pre-tool-use.mjs +45 -0
  52. package/dist/command-policy/hook/run.d.mts +17 -0
  53. package/dist/command-policy/hook/run.mjs +69 -0
  54. package/dist/command-policy/hook/types.d.mts +33 -0
  55. package/dist/command-policy/hook/types.mjs +5 -0
  56. package/dist/command-policy/index.d.mts +29 -0
  57. package/dist/command-policy/index.mjs +23 -0
  58. package/dist/command-policy/path-references.d.mts +14 -0
  59. package/dist/command-policy/path-references.mjs +68 -0
  60. package/dist/command-policy/path-rules.d.mts +11 -0
  61. package/dist/command-policy/path-rules.mjs +37 -0
  62. package/dist/command-policy/payload.d.mts +8 -0
  63. package/dist/command-policy/payload.mjs +54 -0
  64. package/dist/command-policy/types.d.mts +77 -0
  65. package/dist/command-policy/types.mjs +1 -0
  66. package/dist/index.d.mts +2 -0
  67. package/dist/index.mjs +1 -0
  68. package/dist/sandbox-command-audit/args.d.mts +20 -0
  69. package/dist/sandbox-command-audit/args.mjs +64 -0
  70. package/dist/sandbox-command-audit/classify-prefixes.d.mts +23 -0
  71. package/dist/sandbox-command-audit/classify-prefixes.mjs +50 -0
  72. package/dist/sandbox-command-audit/classify.d.mts +46 -0
  73. package/dist/sandbox-command-audit/classify.mjs +74 -0
  74. package/dist/sandbox-command-audit/claude-extract.d.mts +23 -0
  75. package/dist/sandbox-command-audit/claude-extract.mjs +76 -0
  76. package/dist/sandbox-command-audit/claude-tool-uses.d.mts +15 -0
  77. package/dist/sandbox-command-audit/claude-tool-uses.mjs +53 -0
  78. package/dist/sandbox-command-audit/codex-extract.d.mts +21 -0
  79. package/dist/sandbox-command-audit/codex-extract.mjs +77 -0
  80. package/dist/sandbox-command-audit/codex-scan.d.mts +11 -0
  81. package/dist/sandbox-command-audit/codex-scan.mjs +98 -0
  82. package/dist/sandbox-command-audit/codex-spool.d.mts +14 -0
  83. package/dist/sandbox-command-audit/codex-spool.mjs +46 -0
  84. package/dist/sandbox-command-audit/discover-files.d.mts +44 -0
  85. package/dist/sandbox-command-audit/discover-files.mjs +85 -0
  86. package/dist/sandbox-command-audit/failure-text.d.mts +7 -0
  87. package/dist/sandbox-command-audit/failure-text.mjs +34 -0
  88. package/dist/sandbox-command-audit/fixtures.test-helpers.d.mts +34 -0
  89. package/dist/sandbox-command-audit/fixtures.test-helpers.mjs +41 -0
  90. package/dist/sandbox-command-audit/index.d.mts +26 -0
  91. package/dist/sandbox-command-audit/index.mjs +15 -0
  92. package/dist/sandbox-command-audit/json-record.d.mts +6 -0
  93. package/dist/sandbox-command-audit/json-record.mjs +16 -0
  94. package/dist/sandbox-command-audit/limits.d.mts +30 -0
  95. package/dist/sandbox-command-audit/limits.mjs +66 -0
  96. package/dist/sandbox-command-audit/repo-scope.d.mts +25 -0
  97. package/dist/sandbox-command-audit/repo-scope.mjs +79 -0
  98. package/dist/sandbox-command-audit/report-raw.d.mts +16 -0
  99. package/dist/sandbox-command-audit/report-raw.mjs +55 -0
  100. package/dist/sandbox-command-audit/report.d.mts +10 -0
  101. package/dist/sandbox-command-audit/report.mjs +61 -0
  102. package/dist/sandbox-command-audit/run.d.mts +36 -0
  103. package/dist/sandbox-command-audit/run.mjs +70 -0
  104. package/dist/sandbox-command-audit/scan.d.mts +10 -0
  105. package/dist/sandbox-command-audit/scan.mjs +79 -0
  106. package/dist/sandbox-command-audit/transcript-cwd.d.mts +14 -0
  107. package/dist/sandbox-command-audit/transcript-cwd.mjs +153 -0
  108. package/dist/sandbox-command-audit/types.d.mts +59 -0
  109. package/dist/sandbox-command-audit/types.mjs +23 -0
  110. package/dist/tmux/cli-shared.d.mts +18 -0
  111. package/dist/tmux/cli-shared.mjs +8 -0
  112. package/dist/tmux/cli.d.mts +3 -0
  113. package/dist/tmux/cli.mjs +34 -0
  114. package/dist/tmux/config.d.mts +24 -0
  115. package/dist/tmux/config.mjs +91 -0
  116. package/dist/tmux/fake-tmux.test-helpers.d.mts +46 -0
  117. package/dist/tmux/fake-tmux.test-helpers.mjs +105 -0
  118. package/dist/tmux/hook-payload.d.mts +8 -0
  119. package/dist/tmux/hook-payload.mjs +39 -0
  120. package/dist/tmux/index.d.mts +9 -0
  121. package/dist/tmux/index.mjs +7 -0
  122. package/dist/tmux/launcher.d.mts +11 -0
  123. package/dist/tmux/launcher.mjs +127 -0
  124. package/dist/tmux/reminder-post-tool.d.mts +21 -0
  125. package/dist/tmux/reminder-post-tool.mjs +88 -0
  126. package/dist/tmux/runner.d.mts +11 -0
  127. package/dist/tmux/runner.mjs +26 -0
  128. package/dist/tmux/session-name.d.mts +5 -0
  129. package/dist/tmux/session-name.mjs +10 -0
  130. package/dist/tmux/shell-quote.d.mts +9 -0
  131. package/dist/tmux/shell-quote.mjs +16 -0
  132. package/dist/tmux/up.d.mts +2 -0
  133. package/dist/tmux/up.mjs +73 -0
  134. package/dist/tmux/windows.d.mts +18 -0
  135. package/dist/tmux/windows.mjs +50 -0
  136. package/package.json +16 -1
  137. package/scripts/__pycache__/run_bounded_process.cpython-312.pyc +0 -0
  138. package/scripts/tmux/tmux-agent-reminder.sh +68 -0
  139. package/scripts/tmux/tmux-name.sh +34 -0
  140. package/scripts/tmux/tmux-read-title.sh +13 -0
  141. package/scripts/tmux/tmux-target.sh +130 -0
package/README.md CHANGED
@@ -86,6 +86,11 @@ 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
89
94
  vouchington dead-code --baseline dead-code-baseline.json --config .jscpd.json --update
90
95
  vouchington swift-semantic-equal BASE HEAD App.swift
91
96
  vouchington post-review
@@ -270,6 +275,54 @@ at most `limits.totalBytes` in all. A log that cannot be read is reported throug
270
275
  pieces are exported from `vouchington-tooling/transient-retry` (`rerunKnownTransient`,
271
276
  `buildWorkflowRunContext`, `createGhApi`).
272
277
 
278
+ ## Auditing sandbox escalations
279
+
280
+ `vouchington sandbox-command-audit --rules <module> [--settings-path <file>] [--repo-root <dir>]...
281
+ [--worktree-glob <glob>]... [--projects-dir <dir>] [--codex-sessions-dir <dir>] [--session-id <id>]
282
+ [--limit N] [--since DAYS] [--json] [--raw]` scans agent transcripts for Bash calls that left the
283
+ sandbox (`dangerouslyDisableSandbox`), were denied, or failed on a permission signature, and groups
284
+ them by command prefix. Transcript roots default to `CLAUDE_CONFIG_DIR/projects` and
285
+ `CODEX_HOME/sessions` (else `~/.claude` and `~/.codex`). Discovery is scoped to the repository so
286
+ other projects' commands are not reported as this repository's gaps: the roots are the current
287
+ checkout plus every worktree `git worktree list` knows, or the `--repo-root` values, plus the
288
+ matches of each `--worktree-glob` (a glob relative to each root, for worktree layouts git no longer
289
+ lists). A transcript is attributed by its first recorded `cwd`; files whose cwd is unknown or
290
+ outside the roots are counted on the `Scope:` line, never dropped silently. `--limit` caps files per
291
+ source after scoping and `--since` is a day window. The default report holds only prefixes and
292
+ counts; `--raw` adds full command and failure text for local inspection and `--json` serializes
293
+ either view.
294
+
295
+ The package ships no classification. The module named by `--rules` default-exports (or exports as
296
+ `rules`) an object, or a function returning one:
297
+
298
+ ```js
299
+ export default {
300
+ // Required. Turns the settings location into the repository's coverage answer, or { error }.
301
+ loadPolicy: ({ settingsPath, cwd }) => ({
302
+ // list is 'allow' | 'deny' | 'excluded'. 'allow' and 'excluded' receive a normalized
303
+ // command prefix; 'deny' receives each raw command.
304
+ covers: (list, commandOrPrefix) =>
305
+ myPolicy[list].some((rule) => matches(rule, commandOrPrefix)),
306
+ }),
307
+ // Optional. Claims a failed Bash result for a bucket of your own (any string); it runs after the
308
+ // E2BIG check and before the generic permission signatures, and its kinds are reported
309
+ // separately from bypass candidates. It also runs on Codex CommandExecution output, and Codex
310
+ // transcripts are only read when this rule is set.
311
+ classifyFailure: (command, text, source) =>
312
+ /read-only file system/.test(text) ? 'write-path' : undefined,
313
+ // Optional. Overrides any scan cap (see AuditLimits); each must be a non-negative integer.
314
+ limits: { maxRetainedRecords: 1000 },
315
+ worktreeGlobs: ['../checkouts/*'],
316
+ }
317
+ ```
318
+
319
+ Built-in failure kinds are `genuine` (permission denied, `EACCES`, `EPERM`, sandbox start failures,
320
+ and a timeout against a loopback address) and `e2big`. A missing or unreadable policy, or an
321
+ unresolvable repository, prints a `Status: unavailable` report so a retrospective can still embed
322
+ the output. The pieces are exported from `vouchington-tooling/sandbox-command-audit`
323
+ (`scanTranscripts`, `discoverTranscriptFiles`, `resolveRepoRoots`, `classifyAudit`, `formatReport`,
324
+ `runAudit`). Codex escalations are not scanned: Codex agents journal those separately.
325
+
273
326
  ## Reclaiming finished worktrees
274
327
 
275
328
  `vouchington worktree reclaim [--yes] [--json]` removes git worktrees whose work is done. It is a
@@ -352,6 +405,7 @@ import {
352
405
  writeGeneratedFiles,
353
406
  } from 'vouchington-tooling/api-fixtures'
354
407
  import { decide, deriveRetryAttempt } from 'vouchington-tooling/transient-retry'
408
+ import { scanTranscripts, classifyAudit } from 'vouchington-tooling/sandbox-command-audit'
355
409
  import { parseCsvRows, streamCsvRows } from 'vouchington-tooling/csv'
356
410
  import {
357
411
  extractLooseMarkdownTableRows,
@@ -390,6 +444,7 @@ import { runAstGrepExamples } from 'vouchington-tooling/ast-grep-examples'
390
444
  import { astGrepPackPaths } from 'vouchington-tooling/ast-grep-pack'
391
445
  import { validateNugetUpdate } from 'vouchington-tooling/nuget-central-version'
392
446
  import { runVerifyWorkflowSecretsCli } from 'vouchington-tooling/workflow-secrets-drift'
447
+ import { launchSession, loadTmuxConfig } from 'vouchington-tooling/tmux'
393
448
  import { runDeadCodeGate } from 'vouchington-tooling/dead-code'
394
449
  import { normalizeSwiftSource } from 'vouchington-tooling/swift-semantic-equal'
395
450
  import { parseUniqueSwiftBinaryTargetChecksum } from 'vouchington-tooling/swift-source-offset'
@@ -414,6 +469,24 @@ import { tokenizeShellWords } from 'vouchington-tooling/shell-parse'
414
469
 
415
470
  `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.
416
471
 
472
+ `vouchington-tooling/command-policy` judges a tool call's shell command against a rule table the
473
+ caller supplies. `evaluateCommandPolicy(payload, policy, { automationContext })` returns a
474
+ `BlockDecision` or `null`. The `CommandPolicy` table holds typo paths, protected paths (blocked only
475
+ in automation), command and git regex rules (`standardGitPatterns()` is an opt-in preset), and an
476
+ optional `stack` section for `gh stack` workflow rules. Merge authority is generic: automation never
477
+ merges, and one plain interactive `gh pr merge` yields a `confirm` disposition. Every path, reason,
478
+ base branch, and guidance pointer is a parameter; the module has no repository-specific rules. The
479
+ GitHub command parsing it uses (invocations, options, command position and working directory,
480
+ checkout owners) is exported too.
481
+
482
+ `vouchington hook pre-tool-use|post-tool-use --harness claude|codex|cursor|grok --policy <module>`
483
+ runs that engine as a harness hook. Register it in each harness's hook configuration with the
484
+ repository's own policy module, which default-exports a `HookPolicy` (`defineHookPolicy`): a
485
+ `command` rule table, post-tool-use `checkers`, an optional `reminder`, and an optional `onPayload`
486
+ callback (for example to persist the harness session id). `pre-tool-use` exits 2 to block, including
487
+ when the module cannot load; `post-tool-use` is advisory and always exits 0, folding checker warnings
488
+ 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.
489
+
417
490
  `processDiffCommand` runs a caller-supplied `git diff` or `gh pr diff` executable and argv without
418
491
  a shell, emitting complete unified-diff file blocks without accumulating the whole patch. It keeps
419
492
  at most one file block (which can itself be large), preserves preambles and line content, and drains
@@ -946,3 +1019,38 @@ The check preserves the existing nested SELECT/CTE, equality, inner-join, and co
946
1019
  heuristics. It rejects weakened OR/NOT/boolean/CASE predicates and non-filtering left joins. Every
947
1020
  recognized live source reader must be protected. Unparseable SQL fragments are skipped; malformed
948
1021
  source returns false. These are bounded syntactic heuristics, not a general SQL safety proof.
1022
+
1023
+ ## tmux dev sessions
1024
+
1025
+ `vouchington tmux up --config <file>` starts the windows named in a JSON config inside one tmux
1026
+ session per worktree (`<sessionPrefix>d<hash of the worktree path>`), reuses a running session,
1027
+ and respawns dead windows. The config holds everything product-specific:
1028
+
1029
+ ```json
1030
+ {
1031
+ "sessionPrefix": "dev-",
1032
+ "readyMarker": "ready",
1033
+ "launcherPidVar": "TMUX_LAUNCHER_PID",
1034
+ "env": { "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318" },
1035
+ "summary": ["Web: http://localhost:3000"],
1036
+ "windows": [
1037
+ {
1038
+ "name": "web",
1039
+ "cwd": "web",
1040
+ "command": "pnpm run dev",
1041
+ "env": { "OTEL_SERVICE_NAME": "web" }
1042
+ },
1043
+ { "name": "api", "command": "node --watch api.mts" }
1044
+ ]
1045
+ }
1046
+ ```
1047
+
1048
+ Windows run through `bash -lc '<command>; read'` (`"keepOpen": false` drops the `; read`).
1049
+ `--verbose` sets `TMUX_LOG_LEVEL=info` (default `error`) in every window. The tmux binary comes
1050
+ from `TMUX_TARGET_BIN`, the worktree from `TMUX_TARGET_ROOT` (default: current directory).
1051
+
1052
+ `tmux name`, `tmux read-title` and `tmux agent-reminder` verify that the pane (from
1053
+ `--socket/--pane/--worktree` or `AGENT_TMUX_SOCKET/PANE/WORKTREE`) belongs to the worktree before
1054
+ touching it. `tmux post-tool` reads an agent post-tool hook payload on stdin and prints a rename
1055
+ reminder at plan, PR, push and reset checkpoints; reminders name `TMUX_NAME_COMMAND` (default
1056
+ `vouchington tmux name`).
@@ -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,7 @@
1
+ import { type LoadRulesModule } from '../../sandbox-command-audit/run.mts';
2
+ /**
3
+ * `vouchington sandbox-command-audit --rules <module> [flags]`: scans Claude and Codex transcripts
4
+ * for sandbox escalations, denials and permission failures, scoped to the repository, and prints a
5
+ * report. Exits 0 with a report, 2 on a usage error, 1 when the rules module cannot load.
6
+ */
7
+ export declare function runSandboxCommandAuditCommand(args: readonly string[], env?: NodeJS.ProcessEnv, load?: LoadRulesModule): Promise<number>;
@@ -0,0 +1,27 @@
1
+ import { parseAuditArgs } from "../../sandbox-command-audit/args.mjs";
2
+ import { runAudit } from "../../sandbox-command-audit/run.mjs";
3
+ import { commandUsage } from "../usage.mjs";
4
+ /**
5
+ * `vouchington sandbox-command-audit --rules <module> [flags]`: scans Claude and Codex transcripts
6
+ * for sandbox escalations, denials and permission failures, scoped to the repository, and prints a
7
+ * report. Exits 0 with a report, 2 on a usage error, 1 when the rules module cannot load.
8
+ */
9
+ export async function runSandboxCommandAuditCommand(args, env = process.env, load) {
10
+ let parsed;
11
+ try {
12
+ parsed = parseAuditArgs(args, env);
13
+ }
14
+ catch (error) {
15
+ const usage = commandUsage('sandbox-command-audit');
16
+ process.stderr.write(`vouchington: ${error.message}\n${usage}`);
17
+ return 2;
18
+ }
19
+ try {
20
+ process.stdout.write(await runAudit(parsed, { cwd: process.cwd(), ...(load ? { load } : {}) }));
21
+ return 0;
22
+ }
23
+ catch (error) {
24
+ process.stderr.write(`vouchington: ${error instanceof Error ? error.message : String(error)}\n`);
25
+ return 1;
26
+ }
27
+ }
@@ -23,8 +23,10 @@ import { runRetrospectiveTranscriptCommand } from "./commands/retrospective-tran
23
23
  import { runLinkSkill } from "./commands/link-skill.mjs";
24
24
  import { runRetrospectiveFactsCommand } from "./commands/retrospective-facts.mjs";
25
25
  import { runAgentBlackboardCommand } from "./commands/agent-blackboard.mjs";
26
+ import { runHookCommand } from "./commands/hook.mjs";
26
27
  import { runMcpCommand } from "./commands/mcp.mjs";
27
28
  import { runWorktreeCommand } from "./commands/worktree.mjs";
29
+ import { runTmuxCommand } from "../tmux/cli.mjs";
28
30
  import { runHostStoragePreflightCli } from "../host-storage/cli.mjs";
29
31
  import { runWithHostLock } from "./commands/with-host-lock.mjs";
30
32
  import { runFreshBase } from "./commands/fresh-base.mjs";
@@ -106,8 +108,14 @@ export function runCli(argv = process.argv) {
106
108
  return runMcpCommand(parsed.args);
107
109
  case 'transient-retry':
108
110
  return import("./commands/transient-retry.mjs").then((command) => command.runTransientRetryCommand(parsed.args));
111
+ case 'sandbox-command-audit':
112
+ return import("./commands/sandbox-command-audit.mjs").then((command) => command.runSandboxCommandAuditCommand(parsed.args));
113
+ case 'hook':
114
+ return runHookCommand(parsed.args);
109
115
  case 'worktree':
110
116
  return runWorktreeCommand(parsed.args);
117
+ case 'tmux':
118
+ return runTmuxCommand(parsed.args);
111
119
  case 'require-up-to-date':
112
120
  return runRequireUpToDate(parsed);
113
121
  case 'fresh-base':
@@ -46,12 +46,21 @@ type ForwardedCommand = {
46
46
  } | {
47
47
  kind: 'mcp';
48
48
  args: string[];
49
+ } | {
50
+ kind: 'hook';
51
+ args: string[];
49
52
  } | {
50
53
  kind: 'worktree';
51
54
  args: string[];
52
55
  } | {
53
56
  kind: 'transient-retry';
54
57
  args: string[];
58
+ } | {
59
+ kind: 'sandbox-command-audit';
60
+ args: string[];
61
+ } | {
62
+ kind: 'tmux';
63
+ args: string[];
55
64
  };
56
65
  export declare function parseForwardedCommand(command: string | undefined, args: string[]): ForwardedCommand | undefined;
57
66
  export {};
@@ -31,9 +31,15 @@ export function parseForwardedCommand(command, args) {
31
31
  return { kind: 'agent-blackboard', args };
32
32
  if (command === 'mcp')
33
33
  return { kind: 'mcp', args };
34
+ if (command === 'hook')
35
+ return { kind: 'hook', args };
34
36
  if (command === 'worktree')
35
37
  return { kind: 'worktree', args };
36
38
  if (command === 'transient-retry')
37
39
  return { kind: 'transient-retry', args };
40
+ if (command === 'sandbox-command-audit')
41
+ return { kind: 'sandbox-command-audit', args };
42
+ if (command === 'tmux')
43
+ return { kind: 'tmux', args };
38
44
  return undefined;
39
45
  }
@@ -77,12 +77,21 @@ export type ParsedCli = {
77
77
  } | {
78
78
  kind: 'mcp';
79
79
  args: string[];
80
+ } | {
81
+ kind: 'hook';
82
+ args: string[];
80
83
  } | {
81
84
  kind: 'worktree';
82
85
  args: string[];
83
86
  } | {
84
87
  kind: 'transient-retry';
85
88
  args: string[];
89
+ } | {
90
+ kind: 'sandbox-command-audit';
91
+ args: string[];
92
+ } | {
93
+ kind: 'tmux';
94
+ args: string[];
86
95
  } | {
87
96
  kind: 'require-up-to-date';
88
97
  remote: string;
@@ -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 sandbox-command-audit Audit agent transcripts for sandbox escalations and denials\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\nsandbox-command-audit --rules <module> [--settings-path <file>] [--repo-root <dir>]... [--worktree-glob <glob>]... [--projects-dir <dir>] [--codex-sessions-dir <dir>] [--session-id <id>] [--limit N] [--since DAYS] [--json] [--raw]\n Scans Claude and Codex transcripts scoped to this repository (git roots plus any --worktree-glob\n layouts) and reports Bash escalations, denials and permission failures by command prefix.\n <module> exports an object (default or \"rules\") with loadPolicy({ settingsPath, cwd }), which\n returns { covers(list, commandOrPrefix) } for the allow/deny/excluded lists or { error }, and\n optionally classifyFailure(command, text, source), limits and worktreeGlobs. Transcript roots\n default to CLAUDE_CONFIG_DIR/projects and CODEX_HOME/sessions. --raw prints full command text.\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";
@@ -0,0 +1,179 @@
1
+ export const USAGE = `Usage: vouchington <command> [options]
2
+
3
+ Commands:
4
+ runner-port-policy Print or validate a runner port policy
5
+ with-host-lock Run a command under a host-wide lock
6
+ host-storage Check free space on caller-supplied paths
7
+ gha-runtime-audit Audit successful GitHub Actions job runtimes
8
+ require-up-to-date Require HEAD to include a fetched remote branch
9
+ fresh-base Classify the worktree against a remote base branch
10
+ gitleaks-directory-scan Scan a directory with Gitleaks
11
+ ast-grep-examples Run AST-grep rule examples
12
+ ast-grep-pack Print shipped unconditional AST-grep pack paths as JSON
13
+ gha-workspace-policy Check GitHub Actions workspace safety policy
14
+ gha-output Write a collision-safe multiline GITHUB_OUTPUT record
15
+ gha-needs-results Fail if required GitHub Actions job results failed
16
+ download-with-diagnostics Download a URL and report HTTP status on failure
17
+ download-optional-run-artifacts Download optional artifacts from the current run
18
+ host-pressure-diagnostics Print a bounded host memory/OOM/PSI snapshot
19
+ allocate-browser-safe-ports Allocate Fetch-safe localhost ports
20
+ diagnose-port-collision Capture bounded localhost port diagnostics
21
+ prepare-trivy-db Download the Trivy vulnerability database
22
+ gha-artifacts-cleanup Delete classified GitHub Actions artifacts
23
+ agent-issue-labels Map changed paths to labels; create missing repository labels
24
+ http-origin Validate an optional HTTP(S) origin
25
+ vitest-blob-manifest Stamp a vitest-blob-manifest:v1 identity file
26
+ vitest-report-attempt Write or read a Vitest report-attempt marker
27
+ prepare-vitest-reports Validate and select Vitest report JSON files
28
+ pnpm-install Install a pnpm workspace with retry and release-age fail-fast
29
+ check-cache-size Measure a path and decide whether to save a GHA cache
30
+ make-shard-matrix Emit a [1..N] GitHub Actions shard matrix
31
+ load-runner-env Overlay a runner env file onto GITHUB_ENV with injection guards
32
+ clean-workspace Reset a persistent-runner workspace with a fork-PR trust gate
33
+ install-github-release Download a checksum-verified GitHub Release binary
34
+ run-with-timeout Run a command with GNU timeout or a Perl fallback
35
+ lint-links Two-pass lychee: internal links fail, external warn
36
+ materialize-pr-context Dump PR title/body/files/diff/comments and #N crawl
37
+ wait-for-apt-locks Wait until apt/dpkg lock files are free
38
+ install-playwright-chromium-arm64 Install Playwright Chromium from browsers.json
39
+ ghcr-package-retention Delete old GHCR package versions (KEEP_MIN or --main-history)
40
+ harness-admission-lane Compute a GITHUB_RUN_ID admission lane for fleet fan-out
41
+ harness-assert-gates Fail if any named HARNESS_*_ENABLED gate is enabled
42
+ gha-collaborator-trust Classify authors as write-access collaborators or not
43
+ nuget-central-version Validate a Directory.Packages.props PackageVersion delta
44
+ verify-workflow-secrets Check a secret inventory against live repository and environment secrets
45
+ dead-code Gate unused code against a committed jscpd baseline
46
+ swift-semantic-equal Compare Swift sources ignoring comments and whitespace
47
+ post-review Post one COMMENT review from a staged payload file
48
+ stage-review-payload Validate a review payload file into a staging directory
49
+ retrospective-transcript Format facts from Claude-compatible, Codex, or Grok transcripts
50
+ link-skill Link one packaged skill into an explicit consumer directory
51
+ retrospective-facts Gather immutable facts for a retrospective
52
+ agent-blackboard Probe an Agent Blackboard deployment, classify distill sessions, manage snapshots
53
+ mcp Serve the agent-blackboard journal tools over stdio (MCP)
54
+ hook Run a repository policy module as a pre/post tool-use hook
55
+ worktree Reclaim finished git worktrees (dry run unless --yes)
56
+ tmux Run configured dev windows in tmux; name panes; agent reminders
57
+ story-coverage Check component exports are imported by stories
58
+ transient-retry Rerun a failed GitHub Actions run when an injected rule matches
59
+ sandbox-command-audit Audit agent transcripts for sandbox escalations and denials
60
+
61
+ Options:
62
+ -h, --help Show this help
63
+ -v, --version Print the package version
64
+
65
+ runner-port-policy
66
+ (no args) Print the shipped policy as JSON
67
+ --file <path> Validate and print a policy file
68
+ --reserved <port> Print true if the port is reserved
69
+
70
+ with-host-lock
71
+ --name <family>
72
+ [--slots <n>]
73
+ --timeout-seconds <n>
74
+ [--command-timeout-seconds <n>]
75
+ [--failure-diagnostics <absolute-script>]
76
+ [--on-acquire-timeout fail|run-unlocked]
77
+ -- <command> [args...]
78
+
79
+ host-storage --path <path> [--path <path>...] [--minimum-free-bytes <bytes>] [--pnpm-store] [--docker-root] [--docker-desktop-path <path>] [--discovery-timeout-ms <ms>]
80
+
81
+ gha-runtime-audit
82
+ [--repository owner/name] Default GITHUB_REPOSITORY
83
+ [--branch main]
84
+ [--median-threshold-floor <seconds>] Off unless set. Must be below the ceiling
85
+ [--median-threshold-ceiling <seconds>] Default 360. Flags a five-sample median above this
86
+ --pr-workflow <name|/regex/> Repeatable
87
+ --push-workflow <name|/regex/> Repeatable
88
+
89
+ require-up-to-date --remote <name> --branch <name>
90
+ fresh-base [--remote <name>] [--branch <name>] [--skip-fetch]
91
+ gitleaks-directory-scan --config <path> [--directory <path>]
92
+ ast-grep-examples --rules <directory> --config <path>
93
+ ast-grep-pack
94
+ gha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]
95
+
96
+ gha-output <name>
97
+ gha-needs-results [label]
98
+ download-with-diagnostics <url> <destination> [-- curl-args...]
99
+ download-optional-run-artifacts (--name <name>... | --pattern <pattern>) --dir <directory>
100
+ host-pressure-diagnostics
101
+ allocate-browser-safe-ports <count> [--policy path] [--forbidden-ports path]
102
+ diagnose-port-collision [--ports "2200 2216"] [--output-dir PATH]
103
+ prepare-trivy-db
104
+ gha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]
105
+ gha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]
106
+ agent-issue-labels labels-from-paths [--labeler <path>] <path>...
107
+ agent-issue-labels ensure-labels [--repo owner/name] [--policy-file json] [--update] <label>...
108
+ http-origin [--field NAME] [value]
109
+ vitest-blob-manifest <suite> [reports-directory]
110
+ vitest-report-attempt <write DIRECTORY SUITE|read ROOT>
111
+ prepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]
112
+ pnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false
113
+ check-cache-size <path> <max-bytes> <label>
114
+ make-shard-matrix <total>
115
+ load-runner-env
116
+ clean-workspace
117
+ install-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]
118
+ run-with-timeout <timeout-seconds> <kill-after-seconds> <command...>
119
+ lint-links [--offline] [--config PATH] [--glob PATTERN] [files...]
120
+ materialize-pr-context
121
+ wait-for-apt-locks
122
+ install-playwright-chromium-arm64 [name:archive...]
123
+ ghcr-package-retention [--main-history] [--apply|--dry-run] [<url-encoded-package>...]
124
+ harness-admission-lane <lanes>
125
+ harness-assert-gates <gate>...
126
+ gha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json
127
+ nuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>
128
+ verify-workflow-secrets [--repo OWNER/NAME] [--confirm NAME,...] [--inventory MODULE] [--export NAME] [--branch NAME]
129
+ dead-code --baseline PATH [--seed|--update] [--config PATH] [--binary PATH] [--repo-root PATH] [--entry GLOB]... [--snapshot-ignore GLOB]... [--exclude GLOB]...
130
+ swift-semantic-equal <base> <head> <file.swift>
131
+ post-review
132
+ stage-review-payload optional|required <source> <destination>
133
+ retrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]
134
+ link-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir> Link a packaged or repository-local skill
135
+ retrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]
136
+ agent-blackboard probe
137
+ agent-blackboard session-start [--skip-env NAME] [--setup-hint TEXT] [--docs-path PATH] [--restore-hint TEXT] [--timeout-ms N] (SessionStart hook; payload on stdin)
138
+ agent-blackboard distill classify <partition.jsonl> --retro-cutoff ISO8601 --session-cutoff ISO8601
139
+ agent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{"sessions":N,"entries":N,"records":N,"bytes":N}'
140
+ agent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]
141
+ mcp
142
+ (no args) Serve journal_append, journal_entries, outbox_status, outbox_flush,
143
+ session_ensure, retrospective_check, retrospective_save,
144
+ pr_validate, pr_create, pr_update,
145
+ snapshot_export, snapshot_cleanup, and session_archive over stdio.
146
+ Needs the optional @modelcontextprotocol/sdk peer (and zod).
147
+ Launch it from inside the repository's git worktree.
148
+
149
+ hook pre-tool-use|post-tool-use --harness claude|codex|cursor|grok --policy <module> [--root <dir>] [--automation-env NAME]...
150
+ Reads the harness hook payload on stdin. <module> default-exports a policy object (or a function
151
+ of the hook context returning one) with a command rule table, post-tool-use checkers, and an
152
+ optional reminder. pre-tool-use exits 2 to block, and also when the policy cannot load.
153
+ post-tool-use is advisory and always exits 0. --root defaults to the working directory.
154
+ Each --automation-env NAME (repeatable) marks the run unattended when that environment variable
155
+ is set, non-empty, and not 0 or false; CI markers and claude -p are always unattended.
156
+
157
+ worktree reclaim [--yes] [--json]
158
+ Dry run by default. Removes clean, fully pushed worktrees whose same-repository PR for the
159
+ branch is merged or closed at exactly HEAD, using git worktree remove (never forced).
160
+ Skips the main checkout, the current worktree, and locked, bare or detached worktrees.
161
+
162
+ transient-retry --rules <module> [--repo owner/name] [--token-env NAME] [--dry-run] <run-id>
163
+ Loads a module exporting "rules" (and optionally "limits"), evaluates them against the failed run,
164
+ and reruns only on a match. Exits 0 on rerun, 2 when none is warranted, 1 on error.
165
+
166
+ sandbox-command-audit --rules <module> [--settings-path <file>] [--repo-root <dir>]... [--worktree-glob <glob>]... [--projects-dir <dir>] [--codex-sessions-dir <dir>] [--session-id <id>] [--limit N] [--since DAYS] [--json] [--raw]
167
+ Scans Claude and Codex transcripts scoped to this repository (git roots plus any --worktree-glob
168
+ layouts) and reports Bash escalations, denials and permission failures by command prefix.
169
+ <module> exports an object (default or "rules") with loadPolicy({ settingsPath, cwd }), which
170
+ returns { covers(list, commandOrPrefix) } for the allow/deny/excluded lists or { error }, and
171
+ optionally classifyFailure(command, text, source), limits and worktreeGlobs. Transcript roots
172
+ default to CLAUDE_CONFIG_DIR/projects and CODEX_HOME/sessions. --raw prints full command text.
173
+
174
+ tmux up --config <file> [--root <dir>] [--no-attach] [-v|--verbose]
175
+ tmux name [--socket PATH --pane %ID --worktree PATH] <name> | read-title | post-tool | agent-reminder <event>
176
+ Environment: TMUX_TARGET_BIN, TMUX_TARGET_ROOT, TMUX_NAME_COMMAND, AGENT_TMUX_SOCKET/PANE/WORKTREE.
177
+
178
+ story-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>]
179
+ `;
@@ -1,4 +1,5 @@
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 worktree Reclaim finished git worktrees (dry run unless --yes)\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\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\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";
1
+ import { USAGE } from './usage-text.mts';
2
+ export { USAGE };
2
3
  export declare function printUsage(stream?: NodeJS.WritableStream): void;
3
4
  export declare function commandNames(usage?: string): string[];
4
5
  export declare function commandUsage(command: string, usage?: string): string;