vouchington-tooling 0.72.3 → 0.74.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.
@@ -33,6 +33,23 @@ export type BlackboardClientModule = {
33
33
  export(options?: unknown): Promise<unknown>;
34
34
  };
35
35
  /** Newer clients own the ownership markers of their exports and clean them with a capability. */
36
+ /** Newer clients partition with the export's own capability and write a partition marker. */
37
+ partitionSnapshot?: (options: {
38
+ path: string;
39
+ cleanupToken: string;
40
+ checksum?: {
41
+ algorithm: 'sha256';
42
+ value: string;
43
+ };
44
+ counts?: {
45
+ sessions: number;
46
+ entries: number;
47
+ records: number;
48
+ bytes: number;
49
+ };
50
+ maxSessions?: number;
51
+ maxBytes?: number;
52
+ }) => Promise<unknown>;
36
53
  cleanupSnapshotPartitions?: (options: {
37
54
  path?: string;
38
55
  directory?: string;
@@ -1 +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 cloc Count tracked lines of code by category and service with scc\n coverage-scope-check Check positive-threshold coverage rules against the Vitest scope\n trivy-policy Check tracked Trivy workflow scans and the exception registry\n docker-image-mirror Require tracked Docker images to come from a Docker Hub mirror\n storybook-browser-runner Run the Storybook Vitest browser project with cache, retry and watchdog\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] [--max-worktrees N] [--timeout-ms N] [--pr-limit N] [--after PATH]\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\ncloc --config <file> [--scc-bin <path>] [--json]\n Counts git-tracked lines with scc (SCC_BIN or --scc-bin, else \"scc\"), classified into\n source/tests/tooling and by service, and prints an aligned table (--json: rows). <file> is a .json\n file or a module whose default (or \"config\") export is the layout: services [{ name, match }],\n defaultService, categories, testPatterns, toolingPatterns, countedRoots, countedRootFiles,\n excludedDirs, ignoredDirs, sccBin, missingSccHint.\n\ncoverage-scope-check [--rules <path>] [--scope-file <json>] [--include <glob>]... [--exclude <glob>]...\n Fails (exit 1) when a git-tracked file that a coverage rules file (default .coverage-rules.yml)\n gives a patch_coverage_min above 0, and its scope does not ignore, is outside the collector's\n scope. The collector scope is the repeated --include/--exclude globs plus, optionally, the\n include/exclude string arrays of a --scope-file JSON written from the Vitest coverage config.\n At least one include glob is required.\n\ntrivy-policy [--root <dir>] [--ignore-file <path>] [--findings-exit-code-env <NAME>] [--cleanup-url-prefix <url>] [--min-gates N] [--min-sboms N] [--max-expiry-days N]\n Reads git-tracked workflows, composite actions and shell scripts and prints each violation (exit 1).\n Every Trivy package scan must be an auditable CLI run block (no action, wrapper, substitution or\n background). Vulnerability gates need --scanners vuln, --pkg-types os, --severity CRITICAL,HIGH,\n --ignore-unfixed, --skip-db-update, --quiet, table output to a file, --ignorefile <ignore-file>\n (default .trivyignore.yaml) and --exit-code \"$<NAME>\" (default TRIVY_FINDINGS_EXIT_CODE).\n CycloneDX SBOM scans must be unfiltered with --exit-code 0. At least --min-gates gates and\n --min-sboms SBOM scans (default 2 each) must exist. The tracked ignore registry needs purl-exact OS\n packages, a \"Not exploitable: ... Cleanup: <issue URL>\" statement (URL must start with\n --cleanup-url-prefix when given) and an expired_at between tomorrow and --max-expiry-days (30).\n\ndocker-image-mirror [--root <dir>] [--mirror <host>] [--allow-registry <prefix>]... [--require-digest]\n [--allow-ref-expression <text>]...\n Prints each Docker Hub image in git-tracked workflows, composite actions and Dockerfiles (exit 1):\n run, pull and create commands, containers, services, docker:// references, buildx drivers, FROM,\n COPY --from and # syntax. Images must name a registry host; --mirror (default mirror.gcr.io) is\n the host the message tells you to use. --allow-registry (repeatable) instead requires every image,\n including FROM and COPY --from, to start with one of the prefixes; a reference that expands a\n variable passes only when its literal text before the variable starts with a prefix. --require-digest\n requires @sha256: plus 64 lowercase hex characters. Stage aliases and scratch stay exempt.\n --allow-ref-expression (repeatable) is an audited escape hatch for dynamic job outputs: a reference\n whose raw text exactly equals the value is accepted. Images the same file builds locally are exempt.\n\nstorybook-browser-runner --project <name> [--command <cmd>] [--result-file <path>]... [--completion-file <path>] [--coverage-arg=<arg>]... [--optimize-deps-config <path>] [--env-prefix <PREFIX>] [--progress-prefix <text>] [-- <argv>...]\n Spawns <cmd> (default pnpm) in its own process group with <argv> (default \"exec vitest run\n --project <name>\") plus the coverage args (default --coverage) and supervises it: a Vite optimizer\n cache, retries on known Vite and browser start-up flakes, and stall, hang and session-budget\n watchdogs. --result-file paths are removed before each attempt and --completion-file is the one\n whose appearance is recorded. Tuned by <PREFIX>_STARTUP_ATTEMPTS, _OPTIMIZER_STALL_MS, _HANG_MS,\n _SESSION_BUDGET_MS, _DIAGNOSTICS_FILE, _PERSISTENT_CACHE, _PERSISTENT_CACHE_DIR and _COVERAGE\n (PREFIX defaults to STORYBOOK_BROWSER). Exits with the resolved test exit code.\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";
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 cloc Count tracked lines of code by category and service with scc\n coverage-scope-check Check positive-threshold coverage rules against the Vitest scope\n trivy-policy Check tracked Trivy workflow scans and the exception registry\n docker-image-mirror Require tracked Docker images to come from a Docker Hub mirror\n storybook-browser-runner Run the Storybook Vitest browser project with cache, retry and watchdog\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_partition, 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] [--max-worktrees N] [--timeout-ms N] [--pr-limit N] [--after PATH]\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\ncloc --config <file> [--scc-bin <path>] [--json]\n Counts git-tracked lines with scc (SCC_BIN or --scc-bin, else \"scc\"), classified into\n source/tests/tooling and by service, and prints an aligned table (--json: rows). <file> is a .json\n file or a module whose default (or \"config\") export is the layout: services [{ name, match }],\n defaultService, categories, testPatterns, toolingPatterns, countedRoots, countedRootFiles,\n excludedDirs, ignoredDirs, sccBin, missingSccHint.\n\ncoverage-scope-check [--rules <path>] [--scope-file <json>] [--include <glob>]... [--exclude <glob>]...\n Fails (exit 1) when a git-tracked file that a coverage rules file (default .coverage-rules.yml)\n gives a patch_coverage_min above 0, and its scope does not ignore, is outside the collector's\n scope. The collector scope is the repeated --include/--exclude globs plus, optionally, the\n include/exclude string arrays of a --scope-file JSON written from the Vitest coverage config.\n At least one include glob is required.\n\ntrivy-policy [--root <dir>] [--ignore-file <path>] [--findings-exit-code-env <NAME>] [--cleanup-url-prefix <url>] [--min-gates N] [--min-sboms N] [--max-expiry-days N]\n Reads git-tracked workflows, composite actions and shell scripts and prints each violation (exit 1).\n Every Trivy package scan must be an auditable CLI run block (no action, wrapper, substitution or\n background). Vulnerability gates need --scanners vuln, --pkg-types os, --severity CRITICAL,HIGH,\n --ignore-unfixed, --skip-db-update, --quiet, table output to a file, --ignorefile <ignore-file>\n (default .trivyignore.yaml) and --exit-code \"$<NAME>\" (default TRIVY_FINDINGS_EXIT_CODE).\n CycloneDX SBOM scans must be unfiltered with --exit-code 0. At least --min-gates gates and\n --min-sboms SBOM scans (default 2 each) must exist. The tracked ignore registry needs purl-exact OS\n packages, a \"Not exploitable: ... Cleanup: <issue URL>\" statement (URL must start with\n --cleanup-url-prefix when given) and an expired_at between tomorrow and --max-expiry-days (30).\n\ndocker-image-mirror [--root <dir>] [--mirror <host>] [--allow-registry <prefix>]... [--require-digest]\n [--allow-ref-expression <text>]...\n Prints each Docker Hub image in git-tracked workflows, composite actions and Dockerfiles (exit 1):\n run, pull and create commands, containers, services, docker:// references, buildx drivers, FROM,\n COPY --from and # syntax. Images must name a registry host; --mirror (default mirror.gcr.io) is\n the host the message tells you to use. --allow-registry (repeatable) instead requires every image,\n including FROM and COPY --from, to start with one of the prefixes; a reference that expands a\n variable passes only when its literal text before the variable starts with a prefix. --require-digest\n requires @sha256: plus 64 lowercase hex characters. Stage aliases and scratch stay exempt.\n --allow-ref-expression (repeatable) is an audited escape hatch for dynamic job outputs: a reference\n whose raw text exactly equals the value is accepted. Images the same file builds locally are exempt.\n\nstorybook-browser-runner --project <name> [--command <cmd>] [--result-file <path>]... [--completion-file <path>] [--coverage-arg=<arg>]... [--optimize-deps-config <path>] [--env-prefix <PREFIX>] [--progress-prefix <text>] [-- <argv>...]\n Spawns <cmd> (default pnpm) in its own process group with <argv> (default \"exec vitest run\n --project <name>\") plus the coverage args (default --coverage) and supervises it: a Vite optimizer\n cache, retries on known Vite and browser start-up flakes, and stall, hang and session-budget\n watchdogs. --result-file paths are removed before each attempt and --completion-file is the one\n whose appearance is recorded. Tuned by <PREFIX>_STARTUP_ATTEMPTS, _OPTIMIZER_STALL_MS, _HANG_MS,\n _SESSION_BUDGET_MS, _DIAGNOSTICS_FILE, _PERSISTENT_CACHE, _PERSISTENT_CACHE_DIR and _COVERAGE\n (PREFIX defaults to STORYBOOK_BROWSER). Exits with the resolved test exit code.\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";
@@ -145,7 +145,7 @@ mcp
145
145
  (no args) Serve journal_append, journal_entries, outbox_status, outbox_flush,
146
146
  session_ensure, retrospective_check, retrospective_save,
147
147
  pr_validate, pr_create, pr_update,
148
- snapshot_export, snapshot_cleanup, and session_archive over stdio.
148
+ snapshot_export, snapshot_partition, snapshot_cleanup, and session_archive over stdio.
149
149
  Needs the optional @modelcontextprotocol/sdk peer (and zod).
150
150
  Launch it from inside the repository's git worktree.
151
151
 
@@ -6,6 +6,7 @@ import { retrospectiveSave } from "./handlers-retrospective.mjs";
6
6
  import { retrospectiveCheck } from "./retrospective-check.mjs";
7
7
  import { outboxFlush, outboxStatus } from "./handlers-outbox.mjs";
8
8
  import { snapshotCleanup } from "./handlers-snapshot-cleanup.mjs";
9
+ import { snapshotPartition } from "./handlers-snapshot-partition.mjs";
9
10
  import { sessionArchive, sessionEnsure, snapshotExport } from "./handlers-session.mjs";
10
11
  import { handlePrCreate, handlePrUpdate, handlePrValidate } from "./handlers-pr.mjs";
11
12
  import { createSnapshotRegistry } from "./snapshot-registry.mjs";
@@ -24,6 +25,7 @@ const HANDLERS = {
24
25
  pr_create: handlePrCreate,
25
26
  pr_update: handlePrUpdate,
26
27
  snapshot_export: snapshotExport,
28
+ snapshot_partition: snapshotPartition,
27
29
  snapshot_cleanup: snapshotCleanup,
28
30
  session_archive: sessionArchive,
29
31
  };
@@ -15,6 +15,8 @@ export type FakeOptions = {
15
15
  exportResult?: unknown;
16
16
  /** Gives the fake client its own capability-aware snapshot cleanup. */
17
17
  clientCleanup?: (options: unknown) => Promise<void>;
18
+ /** Gives the fake client its own capability-aware snapshot partition. */
19
+ clientPartition?: (options: unknown) => Promise<unknown>;
18
20
  /** Makes `ensure` fail for any other identity, and `get` report a session with this one. */
19
21
  conflictingSession?: {
20
22
  id: string;
@@ -84,6 +84,9 @@ export function fakeBlackboard(options = {}) {
84
84
  ...(options.clientCleanup === undefined
85
85
  ? {}
86
86
  : { cleanupSnapshotPartitions: options.clientCleanup }),
87
+ ...(options.clientPartition === undefined
88
+ ? {}
89
+ : { partitionSnapshot: options.clientPartition }),
87
90
  };
88
91
  return { dependencies: { loadClient: async () => module }, calls, stored };
89
92
  }
@@ -59,6 +59,8 @@ export const snapshotExport = async (args, context) => {
59
59
  sessionId: context.sessionId,
60
60
  worktree: context.worktree,
61
61
  path: outcome.path,
62
+ ...(outcome.checksum === undefined ? {} : { checksum: outcome.checksum }),
63
+ ...(outcome.counts === undefined ? {} : { counts: outcome.counts }),
62
64
  ...(typeof clientToken === 'string' ? { clientToken } : {}),
63
65
  ...recordedPartitions(outcome),
64
66
  }),
@@ -0,0 +1,8 @@
1
+ import type { ToolHandler } from './context.mts';
2
+ /**
3
+ * Partitions the snapshot one `snapshot_export` recorded. The caller supplies only the registry
4
+ * token and optional bounds: the path and the blackboard client's own capability come from the
5
+ * server's record, and the partition runs in this process, so the client's temporary-directory
6
+ * check compares the snapshot with this server's directory, never the caller's.
7
+ */
8
+ export declare const snapshotPartition: ToolHandler;
@@ -0,0 +1,96 @@
1
+ import { partitionSnapshot } from "../agent-blackboard/index.mjs";
2
+ import { loadClient } from "../agent-blackboard/client.mjs";
3
+ import { isObject } from "../agent-blackboard/snapshot-partition-guards.mjs";
4
+ import { optionalRecord, optionalString, requiredString } from "./args.mjs";
5
+ const COUNT_KEYS = ['sessions', 'entries', 'records', 'bytes'];
6
+ function optionalLimit(args, name) {
7
+ const value = args[name];
8
+ if (value === undefined)
9
+ return undefined;
10
+ if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1)
11
+ throw new Error(`${name} must be a positive integer`);
12
+ return value;
13
+ }
14
+ function optionalChecksum(args) {
15
+ const value = optionalString(args, 'checksum');
16
+ if (value === undefined)
17
+ return undefined;
18
+ if (!/^[0-9a-f]{64}$/.test(value))
19
+ throw new Error('checksum must be a sha256 hex digest');
20
+ return { algorithm: 'sha256', value };
21
+ }
22
+ function optionalCounts(args) {
23
+ const value = optionalRecord(args, 'counts');
24
+ if (value === undefined)
25
+ return undefined;
26
+ const valid = Object.keys(value).length === COUNT_KEYS.length &&
27
+ COUNT_KEYS.every((key) => Number.isSafeInteger(value[key]) && value[key] >= 0);
28
+ if (!valid)
29
+ throw new Error(`counts must hold exactly non-negative integer ${COUNT_KEYS.join(', ')}`);
30
+ return value;
31
+ }
32
+ /**
33
+ * Partitions the snapshot one `snapshot_export` recorded. The caller supplies only the registry
34
+ * token and optional bounds: the path and the blackboard client's own capability come from the
35
+ * server's record, and the partition runs in this process, so the client's temporary-directory
36
+ * check compares the snapshot with this server's directory, never the caller's.
37
+ */
38
+ export const snapshotPartition = async (args, context) => {
39
+ const token = requiredString(args, 'cleanupToken');
40
+ const checksum = optionalChecksum(args);
41
+ const counts = optionalCounts(args);
42
+ const maxSessions = optionalLimit(args, 'maxSessions');
43
+ const maxBytes = optionalLimit(args, 'maxBytes');
44
+ const record = context.snapshots.take(token, context.sessionId, context.worktree);
45
+ let current;
46
+ try {
47
+ if (record.directory !== undefined)
48
+ throw new Error('this snapshot is already partitioned; clean it up and export again');
49
+ const expectedChecksum = checksum ?? record.checksum;
50
+ const expectedCounts = counts ?? record.counts;
51
+ const options = {
52
+ path: record.path,
53
+ ...(expectedChecksum === undefined ? {} : { checksum: expectedChecksum }),
54
+ ...(expectedCounts === undefined ? {} : { counts: expectedCounts }),
55
+ ...(maxSessions === undefined ? {} : { maxSessions }),
56
+ ...(maxBytes === undefined ? {} : { maxBytes }),
57
+ };
58
+ const client = await loadClient(context.dependencies);
59
+ // A client that wrote an ownership marker partitions only with its own capability. An export
60
+ // without one came from an older client, whose partitions the in-tree code splits and signs.
61
+ let result;
62
+ if (record.clientToken === undefined)
63
+ result = await partitionSnapshot(options);
64
+ else if (client.partitionSnapshot)
65
+ result = await client.partitionSnapshot({ ...options, cleanupToken: record.clientToken });
66
+ else
67
+ throw new Error('the installed agent-blackboard client cannot partition snapshots');
68
+ // Record whatever directory the client created before judging the rest of its result, so a
69
+ // malformed result cannot orphan a directory that cleanup would then never remove.
70
+ if (isObject(result) && typeof result.directory === 'string') {
71
+ const receipt = isObject(result.cleanupReceipt)
72
+ ? result.cleanupReceipt
73
+ : undefined;
74
+ current = {
75
+ ...record,
76
+ directory: result.directory,
77
+ ...(receipt === undefined ? {} : { receipt }),
78
+ };
79
+ context.snapshots.restore(token, current);
80
+ }
81
+ if (!current || !isObject(result) || !Array.isArray(result.partitions))
82
+ throw new Error('agent-blackboard returned an unexpected snapshot partition result');
83
+ return {
84
+ sessionId: context.sessionId,
85
+ directory: current.directory,
86
+ partitions: result.partitions,
87
+ };
88
+ }
89
+ catch (error) {
90
+ context.snapshots.restore(token, current ?? record);
91
+ const reason = error instanceof Error ? error.message : String(error);
92
+ throw new Error(`snapshot partition failed and the cleanupToken is still valid. ${reason}`, {
93
+ cause: error,
94
+ });
95
+ }
96
+ };
@@ -1,4 +1,4 @@
1
- import type { SnapshotCleanupReceipt } from '../agent-blackboard/snapshot-types.mts';
1
+ import type { SnapshotChecksum, SnapshotCleanupReceipt, SnapshotCounts } from '../agent-blackboard/snapshot-types.mts';
2
2
  /** What the server itself recorded when it exported a snapshot. Never read from a caller. */
3
3
  export type SnapshotRecord = {
4
4
  sessionId: string;
@@ -6,6 +6,9 @@ export type SnapshotRecord = {
6
6
  path: string;
7
7
  /** The exporting client's own capability; kept server-side and never returned to a caller. */
8
8
  clientToken?: string;
9
+ /** What the export reported, so a partition verifies the file against the server's own record. */
10
+ checksum?: SnapshotChecksum;
11
+ counts?: SnapshotCounts;
9
12
  directory?: string;
10
13
  receipt?: SnapshotCleanupReceipt;
11
14
  };
@@ -58,7 +58,40 @@ export const TOOLS = [
58
58
  dataArrayContains: { type: 'object', description: 'Exact string membership in arrays.' },
59
59
  inactiveForHours: { type: 'number', exclusiveMinimum: 0 },
60
60
  }),
61
- tool('snapshot_cleanup', 'Deletes the snapshot file (and partition directory, when one was recorded) that ' +
61
+ tool('snapshot_partition', 'Splits the snapshot snapshot_export wrote into bounded, whole-session, read-only JSONL ' +
62
+ 'partitions. Takes the cleanupToken snapshot_export returned: the server resolves the file ' +
63
+ 'and the blackboard client capability from its own record, verifies the file against the ' +
64
+ 'checksum and counts the export reported (or the ones supplied), and records the partition ' +
65
+ 'directory so snapshot_cleanup removes it with the snapshot. Returns the directory and each ' +
66
+ "partition's path, counts, checksum, and manifest. The token stays valid for " +
67
+ 'snapshot_cleanup; a snapshot is partitioned once, and a failed partition leaves the token ' +
68
+ 'valid for a retry. Hand subagents only these partitions, never the snapshot.', ADDITIVE, {
69
+ cleanupToken: { type: 'string', description: 'The cleanupToken snapshot_export returned.' },
70
+ checksum: {
71
+ type: 'string',
72
+ pattern: '^[0-9a-f]{64}$',
73
+ description: 'Expected sha256 hex of the snapshot; defaults to the export checksum.',
74
+ },
75
+ counts: {
76
+ type: 'object',
77
+ properties: {
78
+ sessions: { type: 'integer', minimum: 0 },
79
+ entries: { type: 'integer', minimum: 0 },
80
+ records: { type: 'integer', minimum: 0 },
81
+ bytes: { type: 'integer', minimum: 0 },
82
+ },
83
+ required: ['sessions', 'entries', 'records', 'bytes'],
84
+ additionalProperties: false,
85
+ description: 'Expected counts of the snapshot; defaults to the export counts.',
86
+ },
87
+ maxSessions: {
88
+ type: 'integer',
89
+ minimum: 1,
90
+ description: 'Whole sessions per partition (25).',
91
+ },
92
+ maxBytes: { type: 'integer', minimum: 1, description: 'Bytes per partition (1048576).' },
93
+ }, ['cleanupToken']),
94
+ tool('snapshot_cleanup', 'Deletes the snapshot file and the partition directory (from snapshot_partition) that ' +
62
95
  'snapshot_export produced. Takes only the cleanupToken it returned: the server resolves the ' +
63
96
  'paths from its own record, never from the caller. The token is bound to the sessionId and ' +
64
97
  'worktree that exported, is single-use, and is forgotten when the server restarts (the ' +
@@ -81,6 +81,7 @@ as MCP tool errors (`isError: true`) with an actionable message rather than cras
81
81
  | `retrospective_check` | optional `sourceEventId` | `sessionId`, `saved`, `entries` (`sourceEventId`, `timestamp`, `issues`, `prs` of each retrospective, oldest first) |
82
82
  | `retrospective_save` | `parentSessionId`, `agent`, `version`, `mode`, `workOutcome`, `feedbackCoverage`, exactly one of `markdown` or `compose`, optional `repositories`, `sourceEventId`, `category`, `dryRun`, `knownSensitiveValues` (markdown only); or `previewToken` with identity, `mode` and `sourceEventId` | as `journal_append` plus `policy.warnings`; with `dryRun`, `markdown`, `previewToken` and `policy.warnings` |
83
83
  | `snapshot_export` | optional `agent`, `version`, `parentSessionId`, `data`, `dataArrayContains`, `inactiveForHours` | `sessionId`, `path`, `counts`, `checksum`, `manifest`, `cleanupToken` |
84
+ | `snapshot_partition` | `cleanupToken`, optional `checksum`, `counts`, `maxSessions`, `maxBytes` | `sessionId`, `directory`, `partitions` (`path`, `counts`, `checksum`, `manifest` of each) |
84
85
  | `snapshot_cleanup` | `cleanupToken` | `sessionId`, `cleaned: true` |
85
86
  | `session_archive` | none | `sessionId`, `archived: true` |
86
87
 
@@ -136,6 +137,27 @@ outbox does not create the directory. `snapshot_export` never accepts a destinat
136
137
  `agent-blackboard` client chooses a private file and returns its path. `session_archive` is the one
137
138
  destructive tool; archived metadata is immutable, while entries stay appendable.
138
139
 
140
+ ### Snapshot partition
141
+
142
+ `snapshot_partition` splits the exported snapshot into bounded, whole-session, read-only JSONL files
143
+ so a distill pass can hand subagents partitions instead of the raw snapshot. It replaces running
144
+ `agent-blackboard snapshot partition` by hand, which cannot work with the server's token: the
145
+ client's ownership marker stores the hash of the client's own `cleanupToken` (which the server never
146
+ returns), and the client requires the snapshot to sit directly in its own `os.tmpdir()`.
147
+
148
+ - **Same token, resolved server-side.** It takes the `cleanupToken` `snapshot_export` returned,
149
+ checked against the exporting `sessionId` and `worktree` like `snapshot_cleanup`. The server reads
150
+ the path and the client's capability from its own record and calls the installed client's
151
+ `partitionSnapshot` in-process, so the temporary-directory check compares the snapshot with this
152
+ server's directory, not the caller's `TMPDIR`. An export without a client capability (an older
153
+ client) is partitioned by the in-tree `partitionSnapshot`, which records a signed receipt.
154
+ - **Verified by default.** The file is verified against the checksum and counts the export reported;
155
+ `checksum` (sha256 hex) and `counts` (`sessions`, `entries`, `records`, `bytes`) override them.
156
+ `maxSessions` (default 25) and `maxBytes` (default 1 MiB) bound each partition.
157
+ - **Not spent.** The token stays valid for `snapshot_cleanup`, which removes the snapshot and the
158
+ recorded partition directory together. A failed partition leaves the token valid for a retry, and a
159
+ snapshot is partitioned once: a second call fails until a fresh export.
160
+
139
161
  ### Snapshot cleanup
140
162
 
141
163
  `snapshot_export` writes a private file in the OS temp directory, and `snapshot_cleanup` is the only
@@ -145,8 +167,8 @@ whether or not archiving happened. Call it as a finally step after processing, o
145
167
  failure.
146
168
 
147
169
  - **No caller-chosen path.** The tool takes only `cleanupToken` (`path`, `directory`, and `receipt`
148
- are unsupported arguments). The server records the export's file path itself, plus a partition
149
- directory and its signed receipt when the client reports both, and cleans exactly that record.
170
+ are unsupported arguments). The server records the export's file path itself, plus the partition
171
+ directory `snapshot_partition` created (with its signed receipt when the in-tree partition ran), and cleans exactly that record.
150
172
  When the client's export carried its own cleanup capability, the server keeps it (never
151
173
  returning it) and cleans through the client's `cleanupSnapshotPartitions`, so the client's
152
174
  ownership marker goes with the file; otherwise it uses the in-tree `cleanupSnapshotPartitions`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vouchington-tooling",
3
- "version": "0.72.3",
3
+ "version": "0.74.0",
4
4
  "description": "Vouchington CLI and extractable tooling libraries.",
5
5
  "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
6
6
  "bugs": {
@@ -0,0 +1,51 @@
1
+ ---
2
+ name: glide-mq
3
+ description: Design glide-mq queue jobs, ordering lanes, worker concurrency, and cross-job caps when writing or reviewing queue producers, workers, and dispatchers.
4
+ ---
5
+
6
+ # glide-mq queues
7
+
8
+ Read applicable `AGENTS.md` and the repository's local queue adapter when present.
9
+ Local policy overrides these portable conventions.
10
+
11
+ Names below are the glide-mq API: the job option `ordering: { key, concurrency }`, the worker
12
+ option `concurrency`, `lockDuration`, and `job.moveToDelayed(timestamp)`. Read
13
+ [lease patterns](references/lease-patterns.md) for the lease shape.
14
+
15
+ 1. **Every shared-queue job sets `ordering`.** An ungrouped job in a shared queue competes for
16
+ every worker slot, so a flood of it starves other families. Give each job an
17
+ `ordering.key` prefixed with its domain name and an explicit `ordering.concurrency`.
18
+ 2. **`ordering.concurrency` is a global cap; the worker `concurrency` is per process.** The key's
19
+ cap holds across all workers and processes. The worker option only bounds one process's
20
+ active jobs. Never size lane caps to sum to the worker option. Take caps from runtime
21
+ configuration, and give batched families a low cap.
22
+ 3. **Group FIFO ignores `priority`.** Jobs sharing an ordering key run in enqueue order whatever
23
+ their priority. Work that must not wait behind a flood, and dispatchers that rely on
24
+ priority, get their own lane. Put work that outsiders can flood in a lane of its own.
25
+ Ordering keys are the orchestration layer; add none on top.
26
+ 4. **`globalConcurrency` caps the whole queue.** The worker option `globalConcurrency` limits
27
+ every job on the queue together, so on a shared queue it throttles all families at once. Use
28
+ ordering lanes for per-family caps, and use `globalConcurrency` only when one resource bounds
29
+ the whole queue.
30
+ 5. **A job moved to delayed keeps its ordering slot until it completes.** A deferred job still
31
+ counts against `ordering.concurrency`, so deferred jobs can fill a key and block ready work
32
+ on it. A cap that must survive deferral belongs in a token-owned lease, released before
33
+ `moveToDelayed`, not in the ordering key. Never fix starvation by raising the key's
34
+ concurrency: overlap grows and the same number of deferred jobs still fill the slots.
35
+ 6. **Lease mechanics.** Acquire a token-owned lease with `SET key token NX PX ttl` before the
36
+ guarded work. Set the TTL at or above the job's `lockDuration`, renew it while the job runs,
37
+ and release it with compare-and-delete in `finally`. On contention, `moveToDelayed` only this
38
+ job by a short, bounded, jittered delay so it keeps its id, cursor, and dedup. Release the
39
+ lease before any `moveToDelayed` for quota deferral. Reuse the repository's lease helper
40
+ rather than adding a second. See [lease patterns](references/lease-patterns.md).
41
+ 7. **Job count is not a KPI.** Many small jobs with a dispatcher and a sweep are fine. Do not
42
+ merge or remove jobs to cut the count. Judge a design by model calls or spend per item and by
43
+ how simply the jobs share a lifecycle.
44
+
45
+ Dispatchers, paged fan-out, and job-id deduplication follow
46
+ [bounded iteration](../bounded-iteration/SKILL.md). A lease for work that spans an external call
47
+ replaces holding a PostgreSQL transaction or advisory lock open across it; see
48
+ [performance patterns](../postgres-node-performance-tuning/references/performance-patterns.md).
49
+
50
+ Consumer policy owns queue names, lane keys, caps and their configuration source, the lease helper,
51
+ and enforcement configuration.
@@ -0,0 +1,44 @@
1
+ # Lease patterns
2
+
3
+ A lease caps work across jobs and survives deferral, which an `ordering` slot does not: a job
4
+ moved to delayed keeps its slot until it completes.
5
+
6
+ ## Acquire, renew, release
7
+
8
+ ```ts
9
+ const token = randomUUID()
10
+ // SET leaseKey token NX PX ttlMs -> null when another job holds the lease
11
+ if (!(await setIfAbsent(leaseKey, token, ttlMs))) {
12
+ return job.moveToDelayed(Date.now() + jitteredDelayMs) // this job only; never falls through
13
+ }
14
+ try {
15
+ // renew while running, e.g. every ttlMs / 3, only while the stored value equals token
16
+ await doGuardedWork()
17
+ } finally {
18
+ await compareAndDelete(leaseKey, token) // script: delete only when the value equals token
19
+ }
20
+ ```
21
+
22
+ - The TTL is at least the job's `lockDuration`. A shorter lease can expire while the job is
23
+ still active, and a second job then enters the guarded section.
24
+ - Renewal and release are scripts that compare the stored value with the token. A plain `DEL`
25
+ can remove a lease another job has since acquired.
26
+ - The delay on contention is short, bounded, and jittered so deferred jobs do not wake together.
27
+ `moveToDelayed` defers this job only and keeps its id, cursor, and dedup.
28
+
29
+ ## Quota deferral
30
+
31
+ When the work defers itself for a quota or rate, release the lease first, then call
32
+ `moveToDelayed`. `moveToDelayed` never returns, so a release placed after it does not run, and a
33
+ deferred job that keeps the lease blocks the jobs the lease exists to admit.
34
+
35
+ ```ts
36
+ await compareAndDelete(leaseKey, token)
37
+ await job.moveToDelayed(resumeAt)
38
+ ```
39
+
40
+ ## Why not the ordering key
41
+
42
+ Concurrency 1 on a key serializes ready work but lets deferred jobs hold the slot. Raising it to
43
+ 2 lets two guarded sections overlap, and two deferred jobs still fill both slots. A lease
44
+ separates the cap on active work from the queue-order slot.
@@ -4,7 +4,7 @@
4
4
  {
5
5
  "name": "agent-workflow",
6
6
  "plugin": "vouchington-workflow",
7
- "pluginVersion": "0.14.2",
7
+ "pluginVersion": "0.14.3",
8
8
  "path": "agent-workflow/SKILL.md",
9
9
  "prerequisites": [
10
10
  "blackboard",
@@ -24,19 +24,19 @@
24
24
  {
25
25
  "name": "blackboard",
26
26
  "plugin": "vouchington-workflow",
27
- "pluginVersion": "0.14.2",
27
+ "pluginVersion": "0.14.3",
28
28
  "path": "blackboard/SKILL.md"
29
29
  },
30
30
  {
31
31
  "name": "bounded-iteration",
32
32
  "plugin": "vouchington-database",
33
- "pluginVersion": "0.8.0",
33
+ "pluginVersion": "0.9.0",
34
34
  "path": "bounded-iteration/SKILL.md"
35
35
  },
36
36
  {
37
37
  "name": "dependabot",
38
38
  "plugin": "vouchington-workflow",
39
- "pluginVersion": "0.14.2",
39
+ "pluginVersion": "0.14.3",
40
40
  "path": "dependabot/SKILL.md",
41
41
  "prerequisites": ["github-actions-checklist"]
42
42
  },
@@ -50,28 +50,34 @@
50
50
  {
51
51
  "name": "git-commit-checklist",
52
52
  "plugin": "vouchington-workflow",
53
- "pluginVersion": "0.14.2",
53
+ "pluginVersion": "0.14.3",
54
54
  "path": "git-commit-checklist/SKILL.md"
55
55
  },
56
56
  {
57
57
  "name": "github-actions-authoring",
58
58
  "plugin": "vouchington-workflow",
59
- "pluginVersion": "0.14.2",
59
+ "pluginVersion": "0.14.3",
60
60
  "path": "github-actions-authoring/SKILL.md",
61
61
  "prerequisites": ["github-actions-checklist"]
62
62
  },
63
63
  {
64
64
  "name": "github-actions-checklist",
65
65
  "plugin": "vouchington-workflow",
66
- "pluginVersion": "0.14.2",
66
+ "pluginVersion": "0.14.3",
67
67
  "path": "github-actions-checklist/SKILL.md"
68
68
  },
69
69
  {
70
70
  "name": "github-issue",
71
71
  "plugin": "vouchington-workflow",
72
- "pluginVersion": "0.14.2",
72
+ "pluginVersion": "0.14.3",
73
73
  "path": "github-issue/SKILL.md"
74
74
  },
75
+ {
76
+ "name": "glide-mq",
77
+ "plugin": "vouchington-database",
78
+ "pluginVersion": "0.9.0",
79
+ "path": "glide-mq/SKILL.md"
80
+ },
75
81
  {
76
82
  "name": "nextjs-vitest-test-authoring",
77
83
  "plugin": "vouchington-testing",
@@ -82,26 +88,26 @@
82
88
  {
83
89
  "name": "npm-publishing",
84
90
  "plugin": "vouchington-workflow",
85
- "pluginVersion": "0.14.2",
91
+ "pluginVersion": "0.14.3",
86
92
  "path": "npm-publishing/SKILL.md"
87
93
  },
88
94
  {
89
95
  "name": "organize-github-issues",
90
96
  "plugin": "vouchington-workflow",
91
- "pluginVersion": "0.14.2",
97
+ "pluginVersion": "0.14.3",
92
98
  "path": "organize-github-issues/SKILL.md",
93
99
  "prerequisites": ["github-issue"]
94
100
  },
95
101
  {
96
102
  "name": "package-json-checklist",
97
103
  "plugin": "vouchington-workflow",
98
- "pluginVersion": "0.14.2",
104
+ "pluginVersion": "0.14.3",
99
105
  "path": "package-json-checklist/SKILL.md"
100
106
  },
101
107
  {
102
108
  "name": "planning",
103
109
  "plugin": "vouchington-workflow",
104
- "pluginVersion": "0.14.2",
110
+ "pluginVersion": "0.14.3",
105
111
  "path": "planning/SKILL.md",
106
112
  "prerequisites": ["github-issue"]
107
113
  },
@@ -115,71 +121,71 @@
115
121
  {
116
122
  "name": "postgres-node-performance-tuning",
117
123
  "plugin": "vouchington-database",
118
- "pluginVersion": "0.8.0",
124
+ "pluginVersion": "0.9.0",
119
125
  "path": "postgres-node-performance-tuning/SKILL.md"
120
126
  },
121
127
  {
122
128
  "name": "postgres-partitioning-uuid-v7",
123
129
  "plugin": "vouchington-database",
124
- "pluginVersion": "0.8.0",
130
+ "pluginVersion": "0.9.0",
125
131
  "path": "postgres-partitioning-uuid-v7/SKILL.md"
126
132
  },
127
133
  {
128
134
  "name": "postgres-schema-design",
129
135
  "plugin": "vouchington-database",
130
- "pluginVersion": "0.8.0",
136
+ "pluginVersion": "0.9.0",
131
137
  "path": "postgres-schema-design/SKILL.md"
132
138
  },
133
139
  {
134
140
  "name": "pr-description",
135
141
  "plugin": "vouchington-workflow",
136
- "pluginVersion": "0.14.2",
142
+ "pluginVersion": "0.14.3",
137
143
  "path": "pr-description/SKILL.md"
138
144
  },
139
145
  {
140
146
  "name": "retrospective",
141
147
  "plugin": "vouchington-workflow",
142
- "pluginVersion": "0.14.2",
148
+ "pluginVersion": "0.14.3",
143
149
  "path": "retrospective/SKILL.md"
144
150
  },
145
151
  {
146
152
  "name": "retrospective-distill",
147
153
  "plugin": "vouchington-workflow",
148
- "pluginVersion": "0.14.2",
154
+ "pluginVersion": "0.14.3",
149
155
  "path": "retrospective-distill/SKILL.md",
150
156
  "prerequisites": ["github-issue"]
151
157
  },
152
158
  {
153
159
  "name": "review-ci-logs",
154
160
  "plugin": "vouchington-workflow",
155
- "pluginVersion": "0.14.2",
161
+ "pluginVersion": "0.14.3",
156
162
  "path": "review-ci-logs/SKILL.md",
157
163
  "prerequisites": ["github-actions-checklist", "pr-description"]
158
164
  },
159
165
  {
160
166
  "name": "review-github-issue-taxonomy",
161
167
  "plugin": "vouchington-workflow",
162
- "pluginVersion": "0.14.2",
168
+ "pluginVersion": "0.14.3",
163
169
  "path": "review-github-issue-taxonomy/SKILL.md",
164
170
  "prerequisites": ["github-issue"]
165
171
  },
166
172
  {
167
173
  "name": "revisit-followups",
168
174
  "plugin": "vouchington-workflow",
169
- "pluginVersion": "0.14.2",
175
+ "pluginVersion": "0.14.3",
170
176
  "path": "revisit-followups/SKILL.md",
171
177
  "prerequisites": ["github-issue"]
172
178
  },
173
179
  {
174
180
  "name": "stacked-prs",
175
181
  "plugin": "vouchington-workflow",
176
- "pluginVersion": "0.14.2",
182
+ "pluginVersion": "0.14.3",
177
183
  "path": "stacked-prs/SKILL.md"
178
184
  },
179
185
  {
180
186
  "name": "static-analysis-checklist",
181
187
  "plugin": "vouchington-workflow",
182
- "pluginVersion": "0.14.2",
188
+ "pluginVersion": "0.14.3",
183
189
  "path": "static-analysis-checklist/SKILL.md",
184
190
  "prerequisites": ["github-actions-checklist"]
185
191
  },
@@ -206,7 +212,7 @@
206
212
  {
207
213
  "name": "triage-prs",
208
214
  "plugin": "vouchington-workflow",
209
- "pluginVersion": "0.14.2",
215
+ "pluginVersion": "0.14.3",
210
216
  "path": "triage-prs/SKILL.md",
211
217
  "prerequisites": [
212
218
  "pr-description",
@@ -31,8 +31,12 @@ Use when completed retrospectives or journals should become durable follow-up wo
31
31
  treating missing records as absent. Require `manifest.schemaVersion` to be 1, `manifest.status`
32
32
  to be `"complete"`, a nonempty `cleanupToken`, and manifest counts that exactly match the export
33
33
  counts, including the terminal manifest record. Hand subagents only read-only partitions of the
34
- verified file, never the original snapshot. Bound each partition to at most 25 contiguous
35
- session groups or 1 MiB. A session's record and entries form an indivisible group, so fail the run
34
+ verified file, never the original snapshot. Create the partitions with the `snapshot_partition`
35
+ tool of the same server, passing the `cleanupToken` from `snapshot_export`: the server holds the
36
+ blackboard client's capability and the export path, so do not run the `agent-blackboard
37
+ snapshot partition` CLI or hand-roll a partition. Each partition holds at most 25 contiguous
38
+ session groups or 1 MiB (the tool's defaults; `maxSessions` and `maxBytes` may only lower
39
+ them). A session's record and entries form an indivisible group, so fail the run
36
40
  rather than split a group or weaken the bound. Only the root keeps the `cleanupToken`; never
37
41
  delegate it. Read full records, with their storage type, repository
38
42
  tags, source identity, coverage, and outcomes, from that file. Do not distill from
@@ -125,9 +129,8 @@ difference is a conflicting payload and stays quarantined.
125
129
  disposition. Inspectors hand-read only journal-only and retrospective sessions; every other shape
126
130
  is determined structurally.
127
131
  - Keep the verified snapshot until the last `session_archive`, because the archival check reads it.
128
- Then remove the snapshot with the cleanup capability returned at export, and any partitions with
129
- the separate receipt returned when they were created (the export capability cannot remove them),
130
- in a cleanup path that runs even when no session is archived.
132
+ Then call `snapshot_cleanup`, which removes the snapshot and the partitions
133
+ `snapshot_partition` recorded, in a cleanup path that runs even when no session is archived.
131
134
  - Report reviewed, fixed, duplicate, deferred, quarantined, actionable, created, updated,
132
135
  not-yet-eligible, entry-type-unresolved, and archived counts with reasons, splitting eligible
133
136
  sessions into retrospective and stale (checkpoint-only, journal-only, zero-entry child, and
@@ -135,7 +138,7 @@ difference is a conflicting payload and stays quarantined.
135
138
 
136
139
  Cleanup, as a finally step: whether processing succeeded or failed, call `snapshot_cleanup` with
137
140
  the `cleanupToken` from `snapshot_export`, with the same `sessionId` and `worktree`, once the
138
- snapshot is no longer needed. The token is single-use and server-restart-scoped; if cleanup fails,
141
+ snapshot and its partitions are no longer needed. The token is single-use and server-restart-scoped; if cleanup fails,
139
142
  retry the same call.
140
143
 
141
144
  Use source records only for local verification and leave them in the repository's approved journal