vouchington-tooling 0.73.0 → 0.74.1

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 ' +
@@ -17,6 +17,9 @@ export type Scenario = {
17
17
  jobErrors?: number[];
18
18
  transient?: number[];
19
19
  transientFailures?: number;
20
+ listing?: 'error' | 'empty' | 'null';
21
+ pullError?: boolean;
22
+ listingStatus?: Status;
20
23
  env?: Record<string, string>;
21
24
  };
22
25
  export declare const sha: (digit: string) => string;
@@ -47,12 +47,20 @@ case "$*" in
47
47
  if [[ -f "$file" ]]; then cat "$file"; else echo '{"jobs":[{"name":"build","conclusion":"success"}]}'; fi
48
48
  exit 0 ;;
49
49
  *"/pulls/"*)
50
+ if [[ "$FAKE_PULL_ERROR" == "true" ]]; then echo 'gh: Server Error (HTTP 502)' >&2; exit 1; fi
50
51
  echo "$FAKE_MERGED"
51
52
  exit 0 ;;
52
53
  esac
53
54
  [[ "$1 $2" == "api --paginate" ]] || { echo "unexpected gh call: $*" >&2; exit 99; }
54
55
  status="\${url#*status=}"
55
56
  status="\${status%%&*}"
57
+ mode="\${FAKE_LISTING:-}"
58
+ if [[ -n "\${FAKE_LISTING_STATUS:-}" && "$FAKE_LISTING_STATUS" != "$status" ]]; then mode=; fi
59
+ case "$mode" in
60
+ error) echo 'gh: Server Error (HTTP 502)' >&2; exit 1 ;;
61
+ empty) exit 0 ;;
62
+ null) echo 'null'; exit 0 ;;
63
+ esac
56
64
  file="$FAKE_GH_DIR/list-$status.json"
57
65
  if [[ -f "$file" ]]; then cat "$file"; else echo '{"total_count":0,"workflow_runs":[]}'; fi
58
66
  `;
@@ -95,6 +103,9 @@ export function createHarness(script, defaultEnv = {}) {
95
103
  FAKE_JOB_ERROR_IDS: (scenario.jobErrors ?? []).join(' '),
96
104
  FAKE_TRANSIENT_IDS: (scenario.transient ?? []).join(' '),
97
105
  FAKE_TRANSIENT_FAILURES: String(scenario.transientFailures ?? 1),
106
+ FAKE_LISTING: scenario.listing ?? '',
107
+ FAKE_LISTING_STATUS: scenario.listingStatus ?? '',
108
+ FAKE_PULL_ERROR: String(scenario.pullError ?? false),
98
109
  FAKE_MERGED: String(scenario.merged ?? false),
99
110
  GH_TOKEN: 'token',
100
111
  PR_NUMBER: scenario.pr ?? '14',
@@ -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.73.0",
3
+ "version": "0.74.1",
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": {
@@ -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,7 +24,7 @@
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
  {
@@ -36,7 +36,7 @@
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,26 +50,26 @@
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
75
  {
@@ -88,26 +88,26 @@
88
88
  {
89
89
  "name": "npm-publishing",
90
90
  "plugin": "vouchington-workflow",
91
- "pluginVersion": "0.14.2",
91
+ "pluginVersion": "0.14.3",
92
92
  "path": "npm-publishing/SKILL.md"
93
93
  },
94
94
  {
95
95
  "name": "organize-github-issues",
96
96
  "plugin": "vouchington-workflow",
97
- "pluginVersion": "0.14.2",
97
+ "pluginVersion": "0.14.3",
98
98
  "path": "organize-github-issues/SKILL.md",
99
99
  "prerequisites": ["github-issue"]
100
100
  },
101
101
  {
102
102
  "name": "package-json-checklist",
103
103
  "plugin": "vouchington-workflow",
104
- "pluginVersion": "0.14.2",
104
+ "pluginVersion": "0.14.3",
105
105
  "path": "package-json-checklist/SKILL.md"
106
106
  },
107
107
  {
108
108
  "name": "planning",
109
109
  "plugin": "vouchington-workflow",
110
- "pluginVersion": "0.14.2",
110
+ "pluginVersion": "0.14.3",
111
111
  "path": "planning/SKILL.md",
112
112
  "prerequisites": ["github-issue"]
113
113
  },
@@ -139,53 +139,53 @@
139
139
  {
140
140
  "name": "pr-description",
141
141
  "plugin": "vouchington-workflow",
142
- "pluginVersion": "0.14.2",
142
+ "pluginVersion": "0.14.3",
143
143
  "path": "pr-description/SKILL.md"
144
144
  },
145
145
  {
146
146
  "name": "retrospective",
147
147
  "plugin": "vouchington-workflow",
148
- "pluginVersion": "0.14.2",
148
+ "pluginVersion": "0.14.3",
149
149
  "path": "retrospective/SKILL.md"
150
150
  },
151
151
  {
152
152
  "name": "retrospective-distill",
153
153
  "plugin": "vouchington-workflow",
154
- "pluginVersion": "0.14.2",
154
+ "pluginVersion": "0.14.3",
155
155
  "path": "retrospective-distill/SKILL.md",
156
156
  "prerequisites": ["github-issue"]
157
157
  },
158
158
  {
159
159
  "name": "review-ci-logs",
160
160
  "plugin": "vouchington-workflow",
161
- "pluginVersion": "0.14.2",
161
+ "pluginVersion": "0.14.3",
162
162
  "path": "review-ci-logs/SKILL.md",
163
163
  "prerequisites": ["github-actions-checklist", "pr-description"]
164
164
  },
165
165
  {
166
166
  "name": "review-github-issue-taxonomy",
167
167
  "plugin": "vouchington-workflow",
168
- "pluginVersion": "0.14.2",
168
+ "pluginVersion": "0.14.3",
169
169
  "path": "review-github-issue-taxonomy/SKILL.md",
170
170
  "prerequisites": ["github-issue"]
171
171
  },
172
172
  {
173
173
  "name": "revisit-followups",
174
174
  "plugin": "vouchington-workflow",
175
- "pluginVersion": "0.14.2",
175
+ "pluginVersion": "0.14.3",
176
176
  "path": "revisit-followups/SKILL.md",
177
177
  "prerequisites": ["github-issue"]
178
178
  },
179
179
  {
180
180
  "name": "stacked-prs",
181
181
  "plugin": "vouchington-workflow",
182
- "pluginVersion": "0.14.2",
182
+ "pluginVersion": "0.14.3",
183
183
  "path": "stacked-prs/SKILL.md"
184
184
  },
185
185
  {
186
186
  "name": "static-analysis-checklist",
187
187
  "plugin": "vouchington-workflow",
188
- "pluginVersion": "0.14.2",
188
+ "pluginVersion": "0.14.3",
189
189
  "path": "static-analysis-checklist/SKILL.md",
190
190
  "prerequisites": ["github-actions-checklist"]
191
191
  },
@@ -212,7 +212,7 @@
212
212
  {
213
213
  "name": "triage-prs",
214
214
  "plugin": "vouchington-workflow",
215
- "pluginVersion": "0.14.2",
215
+ "pluginVersion": "0.14.3",
216
216
  "path": "triage-prs/SKILL.md",
217
217
  "prerequisites": [
218
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