vouchington-tooling 0.86.0 → 0.87.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.
@@ -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 runner-policy Check workflow runner labels and jobs against a config\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 workspace-registry-check Check syncpack, pnpm workspace and CI path-filter registries against tracked manifests\n final-review Post, revoke, check, or benchmark multi-pillar final reviews\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]\nrunner-policy [--config FILE] [--root DIR]\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\nfinal-review post --repo owner/name --pr N --head-sha SHA --input findings.json [--dry-run]\nfinal-review diff --repo owner/name --pr N\nfinal-review revoke --repo owner/name --pr N\nfinal-review status --repo owner/name --pr N\nfinal-review bench --cases cases.json --prompts DIR --out DIR [--pillar NAME]... [--case ID]... [--model NAME] [--jobs N] [--max-turns N] [--score-only] [--judge MODEL]\nfinal-review bench-verifier --cases cases.json --findings-from DIR --prompts DIR --out DIR [--case ID]... [--model NAME] [--jobs N] [--max-turns N] [--score-only] [--judge MODEL] [--checker MODEL]\n post renders verified findings as one or more COMMENT reviews (verdict, reviewed SHA and effort in\n the header; inline comments where the diff allows, the rest in the body) and adds the \"final\n approval\" label on Approve or removes it otherwise. It refuses when the head moved. diff prints the pull request\n diff with base and head line numbers on every line, for reviewers to cite. revoke removes\n the label before a re-review. status exits 0 only when the newest final review approved the current\n head and the label is present. bench runs each pillar prompt against labeled cases from a git-free\n snapshot of the pre-merge head and scores recall and precision; --judge grades by claim\n with a model instead of by location. bench-verifier runs only the verifier, one call per case\n and no subagents, on the pillar findings a bench --out DIR saved (each judged-real finding is\n also planted under a second pillar), and scores real findings kept, label recall, severity\n agreement, duplicates merged, and other blocking and high findings confirmed by --checker;\n --prompts is the skill's references directory.\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 command in a workflow run block or shell script (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\nworkspace-registry-check [--root <dir>] [--syncpack-config <path>] [--workspace-file <path>]\n [--path-filters <path>] [--tooling-group <name>] [--trigger-only-glob <glob>] [--runtime-prefix <prefix>]\n Reconciles git-tracked package.json manifests with the syncpack \"source\" globs (default\n .syncpackrc.json), the pnpm \"packages\" globs (pnpm-workspace.yaml) and the dorny/paths-filter groups\n (.github/ci-path-filters.yml) and prints one line per violation (exit 1). The --tooling-group group\n (default tooling) must reach every manifest and wildcard workspace glob, and its --trigger-only-glob\n (default **/package.json) does not count as registering a manifest. Each group named with\n --runtime-prefix (default runtime-) must mirror the primary group of the same name.\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 runner-policy Check workflow runner labels and jobs against a config\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 workspace-registry-check Check syncpack, pnpm workspace and CI path-filter registries against tracked manifests\n final-review Post, revoke, check, or benchmark multi-pillar final reviews\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]\nrunner-policy [--config FILE] [--root DIR]\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, snapshot_export, snapshot_partition,\n snapshot_archive, 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\nfinal-review post --repo owner/name --pr N --head-sha SHA --input findings.json [--dry-run]\nfinal-review diff --repo owner/name --pr N\nfinal-review revoke --repo owner/name --pr N\nfinal-review status --repo owner/name --pr N\nfinal-review bench --cases cases.json --prompts DIR --out DIR [--pillar NAME]... [--case ID]... [--model NAME] [--jobs N] [--max-turns N] [--score-only] [--judge MODEL]\nfinal-review bench-verifier --cases cases.json --findings-from DIR --prompts DIR --out DIR [--case ID]... [--model NAME] [--jobs N] [--max-turns N] [--score-only] [--judge MODEL] [--checker MODEL]\n post renders verified findings as one or more COMMENT reviews (verdict, reviewed SHA and effort in\n the header; inline comments where the diff allows, the rest in the body) and adds the \"final\n approval\" label on Approve or removes it otherwise. It refuses when the head moved. diff prints the pull request\n diff with base and head line numbers on every line, for reviewers to cite. revoke removes\n the label before a re-review. status exits 0 only when the newest final review approved the current\n head and the label is present. bench runs each pillar prompt against labeled cases from a git-free\n snapshot of the pre-merge head and scores recall and precision; --judge grades by claim\n with a model instead of by location. bench-verifier runs only the verifier, one call per case\n and no subagents, on the pillar findings a bench --out DIR saved (each judged-real finding is\n also planted under a second pillar), and scores real findings kept, label recall, severity\n agreement, duplicates merged, and other blocking and high findings confirmed by --checker;\n --prompts is the skill's references directory.\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 command in a workflow run block or shell script (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\nworkspace-registry-check [--root <dir>] [--syncpack-config <path>] [--workspace-file <path>]\n [--path-filters <path>] [--tooling-group <name>] [--trigger-only-glob <glob>] [--runtime-prefix <prefix>]\n Reconciles git-tracked package.json manifests with the syncpack \"source\" globs (default\n .syncpackrc.json), the pnpm \"packages\" globs (pnpm-workspace.yaml) and the dorny/paths-filter groups\n (.github/ci-path-filters.yml) and prints one line per violation (exit 1). The --tooling-group group\n (default tooling) must reach every manifest and wildcard workspace glob, and its --trigger-only-glob\n (default **/package.json) does not count as registering a manifest. Each group named with\n --runtime-prefix (default runtime-) must mirror the primary group of the same name.\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";
@@ -146,8 +146,8 @@ agent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH
146
146
  mcp
147
147
  (no args) Serve journal_append, journal_entries, outbox_status, outbox_flush,
148
148
  session_ensure, retrospective_check, retrospective_save,
149
- pr_validate, pr_create, pr_update,
150
- snapshot_export, snapshot_partition, snapshot_cleanup, and session_archive over stdio.
149
+ pr_validate, pr_create, pr_update, snapshot_export, snapshot_partition,
150
+ snapshot_archive, snapshot_cleanup, and session_archive over stdio.
151
151
  Needs the optional @modelcontextprotocol/sdk peer (and zod).
152
152
  Launch it from inside the repository's git worktree.
153
153
 
@@ -5,6 +5,7 @@ import { journalAppend, journalEntries } from "./handlers-journal.mjs";
5
5
  import { retrospectiveSave } from "./handlers-retrospective.mjs";
6
6
  import { retrospectiveCheck } from "./retrospective-check.mjs";
7
7
  import { outboxFlush, outboxStatus } from "./handlers-outbox.mjs";
8
+ import { snapshotArchive } from "./handlers-snapshot-archive.mjs";
8
9
  import { snapshotCleanup } from "./handlers-snapshot-cleanup.mjs";
9
10
  import { snapshotPartition } from "./handlers-snapshot-partition.mjs";
10
11
  import { sessionArchive, sessionEnsure, snapshotExport } from "./handlers-session.mjs";
@@ -28,6 +29,7 @@ const HANDLERS = {
28
29
  pr_update: handlePrUpdate,
29
30
  snapshot_export: snapshotExport,
30
31
  snapshot_partition: snapshotPartition,
32
+ snapshot_archive: snapshotArchive,
31
33
  snapshot_cleanup: snapshotCleanup,
32
34
  session_archive: sessionArchive,
33
35
  };
@@ -26,6 +26,10 @@ export type FakeOptions = {
26
26
  };
27
27
  entries?: StoredEntry[];
28
28
  entriesError?: unknown;
29
+ /** Fails the read of just these sessions, keyed by session id. */
30
+ entriesErrors?: Record<string, unknown>;
31
+ /** Fails the archive of just these sessions, keyed by session id. */
32
+ archiveErrors?: Record<string, unknown>;
29
33
  /** An entry another caller writes just before the next append, after that append's read. */
30
34
  lateEntry?: StoredEntry;
31
35
  };
@@ -45,6 +45,8 @@ export function fakeBlackboard(options = {}) {
45
45
  return options.conflictingSession;
46
46
  }
47
47
  async archive(sessionId) {
48
+ if (options.archiveErrors && sessionId in options.archiveErrors)
49
+ throw options.archiveErrors[sessionId];
48
50
  calls.archive.push(sessionId);
49
51
  }
50
52
  }
@@ -68,7 +70,11 @@ export function fakeBlackboard(options = {}) {
68
70
  calls.get.push(input);
69
71
  if (options.entriesError !== undefined)
70
72
  throw options.entriesError;
71
- yield* stored;
73
+ const id = input.sessionId;
74
+ if (options.entriesErrors && id in options.entriesErrors)
75
+ throw options.entriesErrors[id];
76
+ // An entry with no sessionId belongs to whichever session is read, as before.
77
+ yield* stored.filter((entry) => entry.sessionId === undefined || entry.sessionId === id);
72
78
  }
73
79
  }
74
80
  class Snapshots {
@@ -0,0 +1,8 @@
1
+ import type { ToolHandler } from './context.mts';
2
+ /**
3
+ * Archives each listed session whose live entries still match the ones `snapshot_export` recorded.
4
+ * The server reads the snapshot and the live journal itself, so no entry content reaches the
5
+ * caller: the result names only the sessions archived and a reason for each one skipped. The
6
+ * token is only read, never spent, so `snapshot_cleanup` can still use it.
7
+ */
8
+ export declare const snapshotArchive: ToolHandler;
@@ -0,0 +1,67 @@
1
+ import { archiveBlackboardSession } from "../agent-blackboard/index.mjs";
2
+ import { assertSessionId } from "../agent-blackboard/session-id.mjs";
3
+ import { requiredString, requiredStringArray } from "./args.mjs";
4
+ import { readEntriesIfPresent } from "./journal-read.mjs";
5
+ import { entryDigest, readExportedDigests } from "./snapshot-entry-digests.mjs";
6
+ const MAX_ARCHIVE_SESSIONS = 100;
7
+ const MAX_REASON = 200;
8
+ function readSessionIds(value) {
9
+ if (value.length > MAX_ARCHIVE_SESSIONS)
10
+ throw new Error(`sessionIds holds at most ${MAX_ARCHIVE_SESSIONS} session ids`);
11
+ for (const id of value)
12
+ assertSessionId(id);
13
+ return [...new Set(value)];
14
+ }
15
+ function sameEntries(exported, live) {
16
+ const current = new Set(live.map((entry) => entryDigest(entry.data)));
17
+ return current.size === exported.size && [...current].every((digest) => exported.has(digest));
18
+ }
19
+ /**
20
+ * Archives each listed session whose live entries still match the ones `snapshot_export` recorded.
21
+ * The server reads the snapshot and the live journal itself, so no entry content reaches the
22
+ * caller: the result names only the sessions archived and a reason for each one skipped. The
23
+ * token is only read, never spent, so `snapshot_cleanup` can still use it.
24
+ */
25
+ export const snapshotArchive = async (args, context) => {
26
+ const token = requiredString(args, 'cleanupToken');
27
+ const sessionIds = readSessionIds(requiredStringArray(args, 'sessionIds'));
28
+ const record = context.snapshots.take(token, context.sessionId, context.worktree);
29
+ const archived = [];
30
+ const skipped = [];
31
+ try {
32
+ const exported = await readExportedDigests(record.path, new Set(sessionIds), record.checksum);
33
+ for (const sessionId of sessionIds) {
34
+ const expected = exported.get(sessionId);
35
+ if (expected === undefined) {
36
+ skipped.push({ sessionId, reason: 'not in the export' });
37
+ continue;
38
+ }
39
+ try {
40
+ const live = await readEntriesIfPresent(sessionId, context.env, context.dependencies);
41
+ if (live === undefined)
42
+ skipped.push({ sessionId, reason: 'session not found' });
43
+ else if (!sameEntries(expected, live))
44
+ skipped.push({ sessionId, reason: 'entries changed since the export' });
45
+ else {
46
+ await archiveBlackboardSession({
47
+ sessionId,
48
+ env: context.env,
49
+ dependencies: context.dependencies,
50
+ });
51
+ archived.push(sessionId);
52
+ }
53
+ }
54
+ catch (error) {
55
+ const reason = error instanceof Error ? error.message : String(error);
56
+ skipped.push({ sessionId, reason: `failed: ${reason}`.slice(0, MAX_REASON) });
57
+ }
58
+ }
59
+ }
60
+ catch (error) {
61
+ throw new Error(`snapshot archive failed before any session was archived and the cleanupToken is still valid. ${error.message}`, { cause: error });
62
+ }
63
+ finally {
64
+ context.snapshots.restore(token, record);
65
+ }
66
+ return { sessionId: context.sessionId, archived, skipped };
67
+ };
@@ -0,0 +1,12 @@
1
+ import type { SnapshotChecksum } from '../agent-blackboard/snapshot-types.mts';
2
+ /**
3
+ * The identity of one entry: its content without the server-assigned `timestamp`, so entries that
4
+ * differ only in it are one event. Hashed, so a comparison holds digests, never entry content.
5
+ */
6
+ export declare function entryDigest(data: unknown): string;
7
+ /**
8
+ * Reads the snapshot once and returns, for each requested session present in it, the set of its
9
+ * entries' digests. The file is read through a no-follow descriptor and, when the export reported
10
+ * a checksum, verified against it, so a file replaced since the export is refused.
11
+ */
12
+ export declare function readExportedDigests(path: string, wanted: ReadonlySet<string>, checksum: SnapshotChecksum | undefined): Promise<Map<string, Set<string>>>;
@@ -0,0 +1,48 @@
1
+ import { createHash } from 'node:crypto';
2
+ import { constants } from 'node:fs';
3
+ import { open } from 'node:fs/promises';
4
+ import { canonicalFeedback } from "../agent-blackboard/feedback-canonical.mjs";
5
+ import { parseSnapshotRecord } from "../agent-blackboard/snapshot-partition-format.mjs";
6
+ import { isObject } from "../agent-blackboard/snapshot-partition-guards.mjs";
7
+ import { readLines } from "../agent-blackboard/snapshot-partition-io.mjs";
8
+ /**
9
+ * The identity of one entry: its content without the server-assigned `timestamp`, so entries that
10
+ * differ only in it are one event. Hashed, so a comparison holds digests, never entry content.
11
+ */
12
+ export function entryDigest(data) {
13
+ const content = isObject(data)
14
+ ? Object.fromEntries(Object.entries(data).filter(([key]) => key !== 'timestamp'))
15
+ : data;
16
+ return createHash('sha256').update(canonicalFeedback(content)).digest('hex');
17
+ }
18
+ /**
19
+ * Reads the snapshot once and returns, for each requested session present in it, the set of its
20
+ * entries' digests. The file is read through a no-follow descriptor and, when the export reported
21
+ * a checksum, verified against it, so a file replaced since the export is refused.
22
+ */
23
+ export async function readExportedDigests(path, wanted, checksum) {
24
+ const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
25
+ const digests = new Map();
26
+ const hash = createHash('sha256');
27
+ try {
28
+ if (!(await file.stat()).isFile())
29
+ throw new Error('snapshot path is not a regular file');
30
+ for await (const line of readLines(file, hash)) {
31
+ const record = parseSnapshotRecord(line);
32
+ if (record.type === 'session') {
33
+ const id = record.session.id;
34
+ if (wanted.has(id))
35
+ digests.set(id, new Set());
36
+ }
37
+ else if (record.type === 'entry') {
38
+ digests.get(record.entry.sessionId)?.add(entryDigest(record.entry.data));
39
+ }
40
+ }
41
+ }
42
+ finally {
43
+ await file.close();
44
+ }
45
+ if (checksum !== undefined && hash.digest('hex') !== checksum.value)
46
+ throw new Error('snapshot checksum does not match the export');
47
+ return digests;
48
+ }
@@ -91,6 +91,27 @@ export const TOOLS = [
91
91
  },
92
92
  maxBytes: { type: 'integer', minimum: 1, description: 'Bytes per partition (1048576).' },
93
93
  }, ['cleanupToken']),
94
+ tool('snapshot_archive', 'Archives, in one call, every listed session whose live entries still match the ones ' +
95
+ 'snapshot_export recorded. Takes the cleanupToken snapshot_export returned and sessionIds ' +
96
+ '(the sessions to archive, not the caller; at most 100). For each, the server confirms the ' +
97
+ 'session is in the export, reads its live entries, compares them with the exported ones by ' +
98
+ 'content without the server-assigned timestamp, and archives only on an exact match; ' +
99
+ 'otherwise it skips with a reason (not in the export, session not found, entries changed ' +
100
+ 'since the export, or failed). Returns only { archived, skipped: [{ sessionId, reason }] }, ' +
101
+ 'never entry content. Archiving makes session metadata immutable. The token stays valid for ' +
102
+ 'snapshot_cleanup; keep the snapshot until the last archive call. Each call holds the token ' +
103
+ 'while it runs, so send archive calls one at a time and call snapshot_cleanup only after ' +
104
+ 'the last one returns.', MUTATING, {
105
+ cleanupToken: { type: 'string', description: 'The cleanupToken snapshot_export returned.' },
106
+ sessionIds: {
107
+ type: 'array',
108
+ items: { type: 'string', pattern: ID_PATTERN, maxLength: 256 },
109
+ minItems: 1,
110
+ maxItems: 100,
111
+ uniqueItems: true,
112
+ description: 'Sessions to archive, from the export (at most 100 per call).',
113
+ },
114
+ }, ['cleanupToken', 'sessionIds']),
94
115
  tool('snapshot_cleanup', 'Deletes the snapshot file and the partition directory (from snapshot_partition) that ' +
95
116
  'snapshot_export produced. Takes only the cleanupToken it returned: the server resolves the ' +
96
117
  'paths from its own record, never from the caller. The token is bound to the sessionId and ' +
@@ -82,6 +82,7 @@ as MCP tool errors (`isError: true`) with an actionable message rather than cras
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
84
  | `snapshot_partition` | `cleanupToken`, optional `checksum`, `counts`, `maxSessions`, `maxBytes` | `sessionId`, `directory`, `partitions` (`path`, `counts`, `checksum`, `manifest` of each) |
85
+ | `snapshot_archive` | `cleanupToken`, `sessionIds` (1 to 100) | `sessionId`, `archived`, `skipped` (`sessionId`, `reason`; never entry content) |
85
86
  | `snapshot_cleanup` | `cleanupToken` | `sessionId`, `cleaned: true` |
86
87
  | `session_archive` | none | `sessionId`, `archived: true` |
87
88
 
@@ -134,8 +135,9 @@ keeping its content. `rejectedCount` and `worktreeRejectedCount` report those re
134
135
  corrected retry with the same `sourceEventId` is accepted. `outbox_flush` also returns
135
136
  `rejected: [{ sourceEventId, diagnostic }]` for what it moved. Flushing an empty
136
137
  outbox does not create the directory. `snapshot_export` never accepts a destination: the
137
- `agent-blackboard` client chooses a private file and returns its path. `session_archive` is the one
138
- destructive tool; archived metadata is immutable, while entries stay appendable.
138
+ `agent-blackboard` client chooses a private file and returns its path. `session_archive` and
139
+ `snapshot_archive` are the destructive tools; archived metadata is immutable, while entries stay
140
+ appendable.
139
141
 
140
142
  ### Snapshot partition
141
143
 
@@ -158,6 +160,28 @@ returns), and the client requires the snapshot to sit directly in its own `os.tm
158
160
  recorded partition directory together. A failed partition leaves the token valid for a retry, and a
159
161
  snapshot is partitioned once: a second call fails until a fresh export.
160
162
 
163
+ ### Snapshot archive
164
+
165
+ `snapshot_archive` archives many distilled sessions in one call, verified by the server, so a pass
166
+ neither reads every session's entries into the agent's context nor makes one `session_archive` call
167
+ per session. It takes the `cleanupToken` `snapshot_export` returned and `sessionIds` (the sessions to
168
+ archive, not the caller; at most 100 per call, duplicates ignored).
169
+
170
+ - **Server-side comparison.** The server reads the snapshot from its own record (through a no-follow
171
+ descriptor, verified against the export's checksum when it reported one), and for each listed
172
+ session confirms it is in the export, reads the live entries, and compares the two sets by content
173
+ with the server-assigned `timestamp` left out, so entries that differ only in it are one event.
174
+ It archives on an exact match.
175
+ - **Skips, not failures.** A session that is not in the export (`not in the export`), no longer
176
+ exists (`session not found`), gained, lost, or changed an entry (`entries changed since the
177
+ export`), or whose read or archive failed (`failed: ...`) is skipped with that reason and left for
178
+ the next pass. The result is only `{ archived, skipped: [{ sessionId, reason }] }`.
179
+ - **Not spent.** The token stays valid for `snapshot_cleanup`. A snapshot that cannot be read or
180
+ verified fails the whole call before anything is archived, and the token stays valid.
181
+ - **One call at a time.** A call holds the token while it runs, so a parallel `snapshot_archive`,
182
+ `snapshot_partition`, or `snapshot_cleanup` with the same token fails as unknown. Send archive
183
+ calls sequentially and call `snapshot_cleanup` only after the last one returns.
184
+
161
185
  ### Snapshot cleanup
162
186
 
163
187
  `snapshot_export` writes a private file in the OS temp directory, and `snapshot_cleanup` is the only
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vouchington-tooling",
3
- "version": "0.86.0",
3
+ "version": "0.87.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": {
@@ -539,7 +539,7 @@
539
539
  "@vouchington/postgres": "0.4.0",
540
540
  "@vouchington/worker-runtime": "0.3.1",
541
541
  "glide-mq": "^0.20.0",
542
- "next": "16.4.3",
542
+ "next": "16.4.4",
543
543
  "no-mistakes": "0.108.0",
544
544
  "pg": "8.23.1",
545
545
  "react": "19.3.1",
@@ -15,7 +15,7 @@ subagent-identity rules.
15
15
 
16
16
  Journal operations are tools of the `vouchington-tooling` MCP server (`vouchington mcp`):
17
17
  `journal_append`, `journal_entries`, `outbox_status`, `outbox_flush`, `session_ensure`,
18
- `snapshot_export`, and `session_archive`. Harnesses name them differently, so match the bare tool
18
+ `snapshot_export`, `snapshot_archive`, and `session_archive`. Harnesses name them differently, so match the bare tool
19
19
  name: `mcp__vouchington-tooling__<tool>`, `mcp__vouchington_tooling__<tool>` (the hyphen becomes an
20
20
  underscore), or `vouchington-tooling__<tool>` reached through a `search_tool` and `use_tool` pair,
21
21
  or the `vouchington-tooling` namespace reached through `GetDynamicTools` and `CallDynamicTool`.
@@ -25,6 +25,8 @@ Every call takes an exact `sessionId`, never inferred, whose meaning depends on
25
25
  session unless a runner ensures a child identity.
26
26
  - `journal_entries` and `session_archive`: the session read or archived, which during distillation
27
27
  belongs to another agent.
28
+ - `snapshot_archive`: the caller, which also owns the `cleanupToken`; its `sessionIds` name the
29
+ sessions archived.
28
30
  - `snapshot_export`, `outbox_status`, and `outbox_flush`: only the caller. The outbox is per
29
31
  worktree, so `outbox_status` and `outbox_flush` report two counts: `pendingCount` is the unsent
30
32
  records of that `sessionId`, and `worktreePendingCount` is the unsent records of every session in
@@ -44,11 +44,13 @@ A run's cost is the rows it reads and the work it starts, not the memory it hold
44
44
  continue with a plain keyset cursor, `(key, id) < ($1, $2)`. The page `LIMIT` plus a time window
45
45
  or the keyset bound the read. A keyset alone does not bound rows scanned. When a filter can
46
46
  reject long runs, such as a viewer's blocks or mutes, the time window is the scan bound where the
47
- sort has one, and EXPLAIN at representative cardinality compares rows read with rows returned. No
48
- candidate pools: no capped or `MATERIALIZED` CTE over the listed entity that is filtered or
49
- limited afterward, no window loops or resume probes, no proof state in the cursor, and no
50
- runtime-config fields that exist only to cap a read. A page is never short or empty while
51
- `has_next_page` is true. Small viewer-scoped sets (the viewer's follows, mutes, blocks and
47
+ sort has one, and EXPLAIN at representative cardinality compares rows read with rows returned. The
48
+ simplest query comes first; anything more complex needs `EXPLAIN ANALYZE` plans beating it. For a
49
+ ranked list that is a join and `ORDER BY` on the stored score. No candidate pools: no capped or
50
+ `MATERIALIZED` CTE over the listed entity that is filtered or limited afterward, no window loops
51
+ or resume probes, no proof state in the cursor, and no runtime-config fields that exist only to
52
+ cap a read. A single walk with an inspected-row cap is fine, and may return a short or empty page
53
+ with a continuation cursor and `has_next_page` true. Small viewer-scoped sets (the viewer's follows, mutes, blocks and
52
54
  memberships) may be subqueries or semi-joins, because write limits bound them. Measure a
53
55
  list-read change against the plain single walk, not only against the base branch. See
54
56
  [`MATERIALIZED` CTEs](../postgres-node-performance-tuning/references/performance-patterns.md).
@@ -342,6 +342,9 @@ CROSS JOIN LATERAL (
342
342
  ) due;
343
343
  ```
344
344
 
345
+ This is a complex shape: keep it only with `EXPLAIN ANALYZE` plans showing it beats the plain
346
+ query.
347
+
345
348
  The loose scan beats a small thresholds table here because the intervals are chosen per row and
346
349
  there is no second source of truth to drift. If the intervals are a fixed, reviewed set, a
347
350
  thresholds table is just as bounded. Either way the bucket count must itself be bounded, for
@@ -44,7 +44,8 @@ option `concurrency`, `lockDuration`, and `job.moveToDelayed(timestamp)`. Read
44
44
 
45
45
  Dispatchers, paged fan-out, and job-id deduplication follow
46
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
47
+ replaces holding a PostgreSQL transaction open across it, and PostgreSQL advisory locks are never
48
+ used; see
48
49
  [performance patterns](../postgres-node-performance-tuning/references/performance-patterns.md).
49
50
 
50
51
  Consumer policy owns queue names, lane keys, caps and their configuration source, the lease helper,
@@ -4,7 +4,7 @@
4
4
  {
5
5
  "name": "agent-workflow",
6
6
  "plugin": "vouchington-workflow",
7
- "pluginVersion": "0.16.0",
7
+ "pluginVersion": "0.16.1",
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.16.0",
27
+ "pluginVersion": "0.16.1",
28
28
  "path": "blackboard/SKILL.md"
29
29
  },
30
30
  {
31
31
  "name": "bounded-iteration",
32
32
  "plugin": "vouchington-database",
33
- "pluginVersion": "0.10.0",
33
+ "pluginVersion": "0.11.0",
34
34
  "path": "bounded-iteration/SKILL.md"
35
35
  },
36
36
  {
37
37
  "name": "dependabot",
38
38
  "plugin": "vouchington-workflow",
39
- "pluginVersion": "0.16.0",
39
+ "pluginVersion": "0.16.1",
40
40
  "path": "dependabot/SKILL.md",
41
41
  "prerequisites": ["github-actions-checklist"]
42
42
  },
@@ -50,38 +50,38 @@
50
50
  {
51
51
  "name": "final-review",
52
52
  "plugin": "vouchington-workflow",
53
- "pluginVersion": "0.16.0",
53
+ "pluginVersion": "0.16.1",
54
54
  "path": "final-review/SKILL.md"
55
55
  },
56
56
  {
57
57
  "name": "git-commit-checklist",
58
58
  "plugin": "vouchington-workflow",
59
- "pluginVersion": "0.16.0",
59
+ "pluginVersion": "0.16.1",
60
60
  "path": "git-commit-checklist/SKILL.md"
61
61
  },
62
62
  {
63
63
  "name": "github-actions-authoring",
64
64
  "plugin": "vouchington-workflow",
65
- "pluginVersion": "0.16.0",
65
+ "pluginVersion": "0.16.1",
66
66
  "path": "github-actions-authoring/SKILL.md",
67
67
  "prerequisites": ["github-actions-checklist"]
68
68
  },
69
69
  {
70
70
  "name": "github-actions-checklist",
71
71
  "plugin": "vouchington-workflow",
72
- "pluginVersion": "0.16.0",
72
+ "pluginVersion": "0.16.1",
73
73
  "path": "github-actions-checklist/SKILL.md"
74
74
  },
75
75
  {
76
76
  "name": "github-issue",
77
77
  "plugin": "vouchington-workflow",
78
- "pluginVersion": "0.16.0",
78
+ "pluginVersion": "0.16.1",
79
79
  "path": "github-issue/SKILL.md"
80
80
  },
81
81
  {
82
82
  "name": "glide-mq",
83
83
  "plugin": "vouchington-database",
84
- "pluginVersion": "0.10.0",
84
+ "pluginVersion": "0.11.0",
85
85
  "path": "glide-mq/SKILL.md"
86
86
  },
87
87
  {
@@ -94,26 +94,26 @@
94
94
  {
95
95
  "name": "npm-publishing",
96
96
  "plugin": "vouchington-workflow",
97
- "pluginVersion": "0.16.0",
97
+ "pluginVersion": "0.16.1",
98
98
  "path": "npm-publishing/SKILL.md"
99
99
  },
100
100
  {
101
101
  "name": "organize-github-issues",
102
102
  "plugin": "vouchington-workflow",
103
- "pluginVersion": "0.16.0",
103
+ "pluginVersion": "0.16.1",
104
104
  "path": "organize-github-issues/SKILL.md",
105
105
  "prerequisites": ["github-issue"]
106
106
  },
107
107
  {
108
108
  "name": "package-json-checklist",
109
109
  "plugin": "vouchington-workflow",
110
- "pluginVersion": "0.16.0",
110
+ "pluginVersion": "0.16.1",
111
111
  "path": "package-json-checklist/SKILL.md"
112
112
  },
113
113
  {
114
114
  "name": "planning",
115
115
  "plugin": "vouchington-workflow",
116
- "pluginVersion": "0.16.0",
116
+ "pluginVersion": "0.16.1",
117
117
  "path": "planning/SKILL.md",
118
118
  "prerequisites": ["github-issue"]
119
119
  },
@@ -127,78 +127,78 @@
127
127
  {
128
128
  "name": "postgres-node-performance-tuning",
129
129
  "plugin": "vouchington-database",
130
- "pluginVersion": "0.10.0",
130
+ "pluginVersion": "0.11.0",
131
131
  "path": "postgres-node-performance-tuning/SKILL.md"
132
132
  },
133
133
  {
134
134
  "name": "postgres-partitioning-uuid-v7",
135
135
  "plugin": "vouchington-database",
136
- "pluginVersion": "0.10.0",
136
+ "pluginVersion": "0.11.0",
137
137
  "path": "postgres-partitioning-uuid-v7/SKILL.md"
138
138
  },
139
139
  {
140
140
  "name": "postgres-schema-design",
141
141
  "plugin": "vouchington-database",
142
- "pluginVersion": "0.10.0",
142
+ "pluginVersion": "0.11.0",
143
143
  "path": "postgres-schema-design/SKILL.md"
144
144
  },
145
145
  {
146
146
  "name": "pr-description",
147
147
  "plugin": "vouchington-workflow",
148
- "pluginVersion": "0.16.0",
148
+ "pluginVersion": "0.16.1",
149
149
  "path": "pr-description/SKILL.md"
150
150
  },
151
151
  {
152
152
  "name": "ready-and-shepherd",
153
153
  "plugin": "vouchington-workflow",
154
- "pluginVersion": "0.16.0",
154
+ "pluginVersion": "0.16.1",
155
155
  "path": "ready-and-shepherd/SKILL.md",
156
156
  "prerequisites": ["stacked-prs"]
157
157
  },
158
158
  {
159
159
  "name": "retrospective",
160
160
  "plugin": "vouchington-workflow",
161
- "pluginVersion": "0.16.0",
161
+ "pluginVersion": "0.16.1",
162
162
  "path": "retrospective/SKILL.md"
163
163
  },
164
164
  {
165
165
  "name": "retrospective-distill",
166
166
  "plugin": "vouchington-workflow",
167
- "pluginVersion": "0.16.0",
167
+ "pluginVersion": "0.16.1",
168
168
  "path": "retrospective-distill/SKILL.md",
169
169
  "prerequisites": ["github-issue"]
170
170
  },
171
171
  {
172
172
  "name": "review-ci-logs",
173
173
  "plugin": "vouchington-workflow",
174
- "pluginVersion": "0.16.0",
174
+ "pluginVersion": "0.16.1",
175
175
  "path": "review-ci-logs/SKILL.md",
176
176
  "prerequisites": ["github-actions-checklist", "pr-description"]
177
177
  },
178
178
  {
179
179
  "name": "review-github-issue-taxonomy",
180
180
  "plugin": "vouchington-workflow",
181
- "pluginVersion": "0.16.0",
181
+ "pluginVersion": "0.16.1",
182
182
  "path": "review-github-issue-taxonomy/SKILL.md",
183
183
  "prerequisites": ["github-issue"]
184
184
  },
185
185
  {
186
186
  "name": "revisit-followups",
187
187
  "plugin": "vouchington-workflow",
188
- "pluginVersion": "0.16.0",
188
+ "pluginVersion": "0.16.1",
189
189
  "path": "revisit-followups/SKILL.md",
190
190
  "prerequisites": ["github-issue"]
191
191
  },
192
192
  {
193
193
  "name": "stacked-prs",
194
194
  "plugin": "vouchington-workflow",
195
- "pluginVersion": "0.16.0",
195
+ "pluginVersion": "0.16.1",
196
196
  "path": "stacked-prs/SKILL.md"
197
197
  },
198
198
  {
199
199
  "name": "static-analysis-checklist",
200
200
  "plugin": "vouchington-workflow",
201
- "pluginVersion": "0.16.0",
201
+ "pluginVersion": "0.16.1",
202
202
  "path": "static-analysis-checklist/SKILL.md",
203
203
  "prerequisites": ["github-actions-checklist"]
204
204
  },
@@ -225,14 +225,14 @@
225
225
  {
226
226
  "name": "triage-loop",
227
227
  "plugin": "vouchington-workflow",
228
- "pluginVersion": "0.16.0",
228
+ "pluginVersion": "0.16.1",
229
229
  "path": "triage-loop/SKILL.md",
230
230
  "prerequisites": ["ready-and-shepherd", "github-issue"]
231
231
  },
232
232
  {
233
233
  "name": "triage-prs",
234
234
  "plugin": "vouchington-workflow",
235
- "pluginVersion": "0.16.0",
235
+ "pluginVersion": "0.16.1",
236
236
  "path": "triage-prs/SKILL.md",
237
237
  "prerequisites": [
238
238
  "pr-description",
@@ -246,7 +246,7 @@
246
246
  {
247
247
  "name": "triage-sweep",
248
248
  "plugin": "vouchington-workflow",
249
- "pluginVersion": "0.16.0",
249
+ "pluginVersion": "0.16.1",
250
250
  "path": "triage-sweep/SKILL.md",
251
251
  "prerequisites": [
252
252
  "triage-loop",
@@ -11,6 +11,12 @@ Local policy overrides these defaults; do not reload an already-read adapter or
11
11
 
12
12
  Measure the query plan and the workload shape before changing code.
13
13
 
14
+ Owner's principle: "the basic premise is to use the simplest query, and making it more complex
15
+ requires explain analyze plans". Start with filters in `WHERE`, keyed `EXISTS`, joins or
16
+ subqueries, `ORDER BY`, and `LIMIT`. A complex shape stays only with `EXPLAIN ANALYZE` plans showing
17
+ it beats that simple query, not merely the previous version; see
18
+ [simplest query first](references/performance-patterns.md#simplest-query-first).
19
+
14
20
  - Select only the required columns.
15
21
  - Bound each result set. Paginate or stream a large read. A stream bounds memory, not work: cap
16
22
  the rows per run as in [bounded iteration](../bounded-iteration/SKILL.md).
@@ -3,8 +3,8 @@
3
3
  Use pools and release checked-out clients in `finally`, especially for cursors, streams, and COPY.
4
4
  Route ordinary reads to a replica when its lag is acceptable; route read-after-write, locking, and
5
5
  transaction-consistent reads to the writer. Do not hold a client across unrelated application work.
6
- Never hold a transaction, connection, or advisory lock across an external call; take a token lease
7
- in a shared store instead, with a TTL, renewal, and compare-and-delete release. Stop work when
6
+ Never use advisory locks, and never hold a transaction or connection across an external call; take
7
+ a token lease in a shared store instead, with a TTL, renewal, and compare-and-delete release. Stop work when
8
8
  renewal fails, and guard any write a stale owner could make with the token.
9
9
 
10
10
  For large reads, use keyset pagination, cursors, or streams with cancellation and bounded batches.
@@ -21,6 +21,19 @@ data, but it does not replace suitable local indexes or predicates that permit p
21
21
 
22
22
  ## Query shapes
23
23
 
24
+ ### Simplest query first
25
+
26
+ Owner's principle: "hot/best should just be a JOIN and an ORDER BY". A ranked sort joins the
27
+ entity to its stored score and orders by it. Filters go in `WHERE`; membership is a keyed `EXISTS`,
28
+ join, or subquery; then `ORDER BY` and `LIMIT`.
29
+
30
+ These need `EXPLAIN ANALYZE` plans, at representative cardinality, showing they beat the simple
31
+ query for the same result, not merely the previous version on the base branch: `MATERIALIZED` or
32
+ capped candidate CTEs, `UNION`, `GROUP BY` or `DISTINCT` dedupe, `LATERAL` joins and planner
33
+ fences, cohort or window ranking, and multi-stage cap-filter-rank pipelines. Never build a
34
+ candidate pool. A walk that stops at an inspected-row cap and returns a short or empty page with a
35
+ continuation cursor is fine.
36
+
24
37
  Test existence with `EXISTS`, not `COUNT(*) > 0`. Use correlated `NOT EXISTS` rather than
25
38
  `NOT IN (SELECT ...)`, whose NULL behavior can silently exclude expected rows. Filter and order
26
39
  UUIDv7 rows by `id`, not generated `created_at`, so the key's index supports the query.
@@ -32,7 +45,8 @@ Use keyset pagination, never `OFFSET`. An optimizer fence is a `MATERIALIZED` CT
32
45
  The outer query still reads CTE rows on demand and can stop at its `LIMIT`, but when its filters
33
46
  reject most CTE rows, or it sorts, aggregates or hash-joins them, it reads every row up to the CTE's own
34
47
  `LIMIT`. Use a `MATERIALIZED` CTE only when it holds the final `LIMIT`, or for a small
35
- viewer-scoped set. Never use it as a candidate pool before the page `LIMIT`. Constrain a partitioned table's partition key, or document the reason for a
48
+ viewer-scoped set, and only with plans showing it beats the plain query. Never use it as a
49
+ candidate pool before the page `LIMIT`. Constrain a partitioned table's partition key, or document the reason for a
36
50
  cross-partition query. Choose the partition key from dominant access patterns; a hot reader
37
51
  of `RANGE (id)` needs an id or time bound.
38
52
 
@@ -98,7 +112,8 @@ count over its output. A restriction on a grouping column can still be pushed be
98
112
  so let the plan decide. Confirm from the
99
113
  plan (large `Actual Rows` and `Actual Loops` inside the view's nodes), then choose the ids from the
100
114
  base tables first and read the view by its key, as a correlated `LATERAL` lookup so the page
101
- restriction can reach inside the view. This works for an aggregate or `GROUP BY` view whose key is
115
+ restriction can reach inside the view. Reach for this only after the plan shows the simple
116
+ query builds the whole view, and keep it only if its plan beats the simple query. This works for an aggregate or `GROUP BY` view whose key is
102
117
  a grouping column; a `LIMIT` in the view blocks pushdown of any qual, so rewrite that view's query
103
118
  against the base tables instead. A plain join to the page is a join clause, not a restriction
104
119
  inside the view, so the planner can still build the whole aggregate first.
@@ -148,7 +163,9 @@ Overlap independent cache and PostgreSQL reads with `Promise.all`, such as a rat
148
163
  alongside the user fetch. Serialize only true dependencies, where one result feeds the next call. Suppress the
149
164
  sequential-await lint only when each step consumes the previous step's result; a shared
150
165
  transaction client or lock ordering is not a data dependency. A lock that must be taken first
151
- stays a separate, earlier statement; never reorder or parallelize it. Audit every added suppression.
166
+ stays a separate, earlier statement; never reorder or parallelize it. Do not keep a lock only
167
+ because it exists: one that fails the lock rule in
168
+ [schema design](../../postgres-schema-design/SKILL.md) is deleted. Audit every added suppression.
152
169
 
153
170
  Correctness comes before round trips. Before folding a statement away, state the guarantee it
154
171
  gave (what it locked, which snapshot it read) and reject the fold if that weakens. An `EXISTS`
@@ -14,6 +14,13 @@ Local policy overrides these portable conventions.
14
14
  - Split differing shapes, share identical values, and keep history documents as JSON.
15
15
  - Use canonical [table shapes](references/table-shapes.md) for revisions, changes, work, and cursors.
16
16
  - Default to finite retention for everything except user content; see [table shapes](references/table-shapes.md#retention).
17
+ - No unnecessary locks. Owner's words: "do we have a rule? no unnecessary locks", "seems like we
18
+ have way too many locks for no reason", "keep things simple". Lock (`FOR UPDATE`) only when a
19
+ concurrent write would corrupt the rows this transaction writes. Never lock a read set or a
20
+ parent row, and never use advisory locks. Caps and "don't remove the last X" guards are best
21
+ effort: count up to the cap (`LIMIT cap+1`), then write. Never add counter or projection tables,
22
+ slot tables, claim tables, or constraints that exist only to make a cap exact. Remove a lock by
23
+ deleting it, not by swapping in another serializer.
17
24
  - Reuse parameterized trigger functions instead of copying bodies.
18
25
  - Comment every table, column, and view; document reviewed exceptions explicitly.
19
26
 
@@ -29,7 +29,9 @@ Default to a queue job whose job id is the durable row id, enqueued after commit
29
29
  sweep that re-enqueues rows with no recorded outcome. The queue already supplies attempts,
30
30
  backoff, locking, stall recovery and unique ids. A lease or outbox work-item table needs a stated
31
31
  reason: legal or payment records, old values that vanish at commit, or an outcome that must
32
- commit with domain rows.
32
+ commit with domain rows. Making a cap exact is never a reason: no counter, slot, or claim table
33
+ for a cap; count up to the cap and write, as in the lock rule in
34
+ [schema design](../SKILL.md).
33
35
 
34
36
  When a table is justified, fence with one compare-and-set on the outcome or a generation
35
37
  (`WHERE completed_at IS NULL` / `AND generation = $n`) instead of a full set of lease columns.
@@ -71,11 +71,14 @@ Use when completed retrospectives or journals should become durable follow-up wo
71
71
  denied-external tracking behavior.
72
72
  7. Archive only verified records fully processed across every represented repository, and never
73
73
  while any worktree's `outbox_status` reports a `worktreePendingCount` above 0, under the
74
- repository's retention rules. Make one `session_archive` call per session, whose `sessionId` is the archived session,
75
- not the caller. Immediately before each call, read that session with `journal_entries` and
76
- archive only if its entries match the verified snapshot's by source identity; otherwise leave it
77
- for the next pass, because an entry added after the export would never be distilled.
78
- Archiving makes the session's metadata immutable, so it needs the archival authorization that
74
+ repository's retention rules. Archive with the `snapshot_archive` tool, passing the
75
+ `cleanupToken` from `snapshot_export` and up to 100 `sessionIds` per call, which are the sessions
76
+ to archive, not the caller. The server confirms each session is in that export, reads its live
77
+ entries, compares them with the exported ones by content (entries that differ only in
78
+ the server-assigned `timestamp` are one event), and archives only on an exact match. Do not read
79
+ sessions with `journal_entries` to compare them yourself. It returns only
80
+ `{archived, skipped: [{sessionId, reason}]}`: leave every skipped session for the next pass,
81
+ because an entry added after the export would never be distilled. Archiving makes the session's metadata immutable, so it needs the archival authorization that
79
82
  local policy requires. A one-repository pass leaves a multi-repository session active until the other
80
83
  repositories are reviewed. Report reviewed, fixed, duplicate, deferred, quarantined, and
81
84
  actionable dispositions with reasons. Keep the top five themes in human prose without dropping
@@ -128,7 +131,8 @@ difference is a conflicting payload and stays quarantined.
128
131
  summary: partition index, deduplicated themes with their session IDs, and each session's
129
132
  disposition. Inspectors hand-read only journal-only and retrospective sessions; every other shape
130
133
  is determined structurally.
131
- - Keep the verified snapshot until the last `session_archive`, because the archival check reads it.
134
+ - Keep the verified snapshot until the last `snapshot_archive` call, because the server's archival
135
+ check reads it.
132
136
  Then call `snapshot_cleanup`, which removes the snapshot and the partitions
133
137
  `snapshot_partition` recorded, in a cleanup path that runs even when no session is archived.
134
138
  - Report reviewed, fixed, duplicate, deferred, quarantined, actionable, created, updated,
@@ -138,8 +142,9 @@ difference is a conflicting payload and stays quarantined.
138
142
 
139
143
  Cleanup, as a finally step: whether processing succeeded or failed, call `snapshot_cleanup` with
140
144
  the `cleanupToken` from `snapshot_export`, with the same `sessionId` and `worktree`, once the
141
- snapshot and its partitions are no longer needed. The token is single-use and server-restart-scoped; if cleanup fails,
142
- retry the same call.
145
+ snapshot and its partitions are no longer needed. `snapshot_partition` and `snapshot_archive` leave the token valid, so cleanup comes after the last
146
+ archive call. The token is single-use and server-restart-scoped; if cleanup fails, retry the same
147
+ call.
143
148
 
144
149
  Use source records only for local verification and leave them in the repository's approved journal
145
150
  or retention system. Public issue bodies contain only the minimum bounded facts or redacted
@@ -150,5 +155,5 @@ copy its contents into an issue.
150
155
 
151
156
  This skill supplies no issue repository, labels, milestones, projects, or approval model; it reads
152
157
  sessions only from the snapshot file that `snapshot_export` writes, and archives them only with
153
- `session_archive`. Consumer wrappers cannot weaken this export
158
+ `snapshot_archive`. Consumer wrappers cannot weaken this export
154
159
  boundary; they provide only those local details.
@@ -32,6 +32,11 @@ Resolve these first and stop to ask when one is missing; never guess.
32
32
  - **Issue taxonomy:** milestone and project rules, and where sensitive issues go.
33
33
  - **Dispatch targets:** isolated-worktree subagents, and any terminal workspace manager whose
34
34
  agents accept prompts.
35
+ - **Distill cutoffs:** `retroDays` and `sessionDays` (non-negative finite day counts), and whether
36
+ archiving the distilled sessions is authorized. The values come from the repository's
37
+ [retrospective-distill](../retrospective-distill/SKILL.md) adapter (the alias its `AGENTS.md`
38
+ declares, otherwise `.agents/skills/retrospective-distill/SKILL.md`); Phase E of
39
+ `triage-sweep` passes them through.
35
40
  - **Fallback interval:** the cron cadence for a full sweep (default every 6 hours).
36
41
  - **Late-review window:** how far back Phase F rescans merged PRs (default 14 days).
37
42
 
@@ -95,8 +95,11 @@ PR. For each one, under the adapter's taxonomy through
95
95
  ## Phase E - Retrospective distill
96
96
 
97
97
  Run [retrospective-distill](../retrospective-distill/SKILL.md) for sessions completed after
98
- `retroCursor`. File the verified follow-ups through [github-issue](../github-issue/SKILL.md). The
99
- grant covers archiving the sessions it distilled. Advance `retroCursor` only after cleanup
98
+ `retroCursor`, with the adapter's distill cutoffs (`retroDays` and `sessionDays`; see the loop's
99
+ [adapter parameters](../triage-loop/SKILL.md#adapter-parameters)). Stop and ask when either is
100
+ missing. File the verified follow-ups through [github-issue](../github-issue/SKILL.md). The
101
+ grant covers archiving the sessions it distilled, only when the adapter authorizes archival;
102
+ otherwise skip step 7 and still clean up. Advance `retroCursor` only after cleanup
100
103
  succeeds.
101
104
 
102
105
  ## Phase F - Missed code reviews