vouchington-tooling 0.86.1 → 0.87.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.
package/README.md CHANGED
@@ -82,7 +82,6 @@ vouchington mcp
82
82
  vouchington install-playwright-chromium-arm64
83
83
  vouchington ghcr-package-retention example%2Fapi
84
84
  vouchington harness-admission-lane 4
85
- vouchington harness-assert-gates HARNESS_DISPATCH_ENABLED HARNESS_SHEPHERD_ENABLED
86
85
  echo '[{"login":"octocat","type":"User"}]' | vouchington gha-collaborator-trust owner/repo --allow-bot github-actions[bot]
87
86
  vouchington nuget-central-version trusted.props candidate.props metadata.json out.props
88
87
  vouchington verify-workflow-secrets --repo owner/name --inventory .github/workflows/workflow-secrets-inventory.mts
@@ -74,10 +74,10 @@ function writeNativeTests(rules, testDir, semanticDir) {
74
74
  fs.writeFileSync(join(semanticDir, `${rule.id}.yml`), yamlDump(semanticRule));
75
75
  }
76
76
  }
77
- function scanScopedRule(loaded, root, languageGlobs, execute) {
78
- const { invalid, rule } = loaded;
77
+ function scanScopedRule({ invalid, rule }, root, languageGlobs, execute) {
78
+ const { examples, ...scopedRule } = rule;
79
79
  const expected = new Map();
80
- for (const example of rule.examples) {
80
+ for (const example of examples) {
81
81
  assertExample(rule, example);
82
82
  const file = example.file.replace(/\\/g, '/').replace(/^\.\//, '');
83
83
  expected.set(file, eligible(rule, file));
@@ -85,7 +85,7 @@ function scanScopedRule(loaded, root, languageGlobs, execute) {
85
85
  fs.mkdirSync(dirname(path), { recursive: true });
86
86
  fs.writeFileSync(path, invalid);
87
87
  }
88
- fs.copyFileSync(loaded.ruleFile, join(root, 'rule.yml'));
88
+ fs.writeFileSync(join(root, 'rule.yml'), yamlDump(scopedRule));
89
89
  fs.writeFileSync(join(root, 'sgconfig.yml'), yamlDump({ languageGlobs }));
90
90
  const result = execute(['scan', '--rule', 'rule.yml', '--config', 'sgconfig.yml', '--json', '--no-ignore', 'hidden'], root);
91
91
  if (result.status === null || result.status > 1)
@@ -141,7 +141,7 @@ export type ParsedCli = {
141
141
  workflowDirectories?: string[];
142
142
  actionDirectories?: string[];
143
143
  } | ParsedGhaRuntimeAudit | ParsedGhaArtifactsCleanup | ParsedAgentIssueLabels | ParsedStoryCoverage;
144
- export type ScriptCommand = 'gha-output' | 'gha-needs-results' | 'download-with-diagnostics' | 'download-optional-run-artifacts' | 'host-pressure-diagnostics' | 'allocate-browser-safe-ports' | 'diagnose-port-collision' | 'prepare-trivy-db' | 'check-cache-size' | 'make-shard-matrix' | 'load-runner-env' | 'clean-workspace' | 'install-github-release' | 'run-with-timeout' | 'lint-links' | 'materialize-pr-context' | 'wait-for-apt-locks' | 'install-playwright-chromium-arm64' | 'ghcr-package-retention' | 'harness-admission-lane' | 'harness-assert-gates' | 'gha-collaborator-trust';
144
+ export type ScriptCommand = 'gha-output' | 'gha-needs-results' | 'download-with-diagnostics' | 'download-optional-run-artifacts' | 'host-pressure-diagnostics' | 'allocate-browser-safe-ports' | 'diagnose-port-collision' | 'prepare-trivy-db' | 'check-cache-size' | 'make-shard-matrix' | 'load-runner-env' | 'clean-workspace' | 'install-github-release' | 'run-with-timeout' | 'lint-links' | 'materialize-pr-context' | 'wait-for-apt-locks' | 'install-playwright-chromium-arm64' | 'ghcr-package-retention' | 'harness-admission-lane' | 'gha-collaborator-trust';
145
145
  export declare function parseCli(argv: readonly string[]): ParsedCli;
146
146
  export declare function parseCommandHelp(command: string | undefined, rest: readonly string[]): {
147
147
  kind: 'command-help';
@@ -27,7 +27,6 @@ const SCRIPT_COMMANDS = new Set([
27
27
  'install-playwright-chromium-arm64',
28
28
  'ghcr-package-retention',
29
29
  'harness-admission-lane',
30
- 'harness-assert-gates',
31
30
  'gha-collaborator-trust',
32
31
  ]);
33
32
  export function parseCli(argv) {
@@ -40,7 +40,6 @@ export const SCRIPT_PATHS = {
40
40
  command: 'bash',
41
41
  path: 'scripts/gha/harness-admission-lane.sh',
42
42
  },
43
- 'harness-assert-gates': { command: 'bash', path: 'scripts/gha/harness-assert-gates.sh' },
44
43
  'gha-collaborator-trust': {
45
44
  command: 'bash',
46
45
  path: 'scripts/gha/gha-collaborator-trust.sh',
@@ -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 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>\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";
@@ -39,7 +39,6 @@ Commands:
39
39
  install-playwright-chromium-arm64 Install Playwright Chromium from browsers.json
40
40
  ghcr-package-retention Delete old GHCR package versions (KEEP_MIN or --main-history)
41
41
  harness-admission-lane Compute a GITHUB_RUN_ID admission lane for fleet fan-out
42
- harness-assert-gates Fail if any named HARNESS_*_ENABLED gate is enabled
43
42
  gha-collaborator-trust Classify authors as write-access collaborators or not
44
43
  nuget-central-version Validate a Directory.Packages.props PackageVersion delta
45
44
  verify-workflow-secrets Check a secret inventory against live repository and environment secrets
@@ -126,7 +125,6 @@ wait-for-apt-locks
126
125
  install-playwright-chromium-arm64 [name:archive...]
127
126
  ghcr-package-retention [--main-history] [--apply|--dry-run] [<url-encoded-package>...]
128
127
  harness-admission-lane <lanes>
129
- harness-assert-gates <gate>...
130
128
  gha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json
131
129
  nuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>
132
130
  verify-workflow-secrets [--repo OWNER/NAME] [--confirm NAME,...] [--inventory MODULE] [--export NAME] [--branch NAME]
@@ -146,8 +144,8 @@ agent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH
146
144
  mcp
147
145
  (no args) Serve journal_append, journal_entries, outbox_status, outbox_flush,
148
146
  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.
147
+ pr_validate, pr_create, pr_update, snapshot_export, snapshot_partition,
148
+ snapshot_archive, snapshot_cleanup, and session_archive over stdio.
151
149
  Needs the optional @modelcontextprotocol/sdk peer (and zod).
152
150
  Launch it from inside the repository's git worktree.
153
151
 
@@ -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.1",
3
+ "version": "0.87.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": {
@@ -528,7 +528,7 @@
528
528
  "yaml": "2.9.1"
529
529
  },
530
530
  "devDependencies": {
531
- "@ast-grep/cli": "0.51.0",
531
+ "@ast-grep/cli": "0.51.1",
532
532
  "@modelcontextprotocol/sdk": "1.32.2",
533
533
  "@playwright/test": "1.64.1",
534
534
  "@types/pg": "8.23.1",
@@ -539,8 +539,8 @@
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",
543
- "no-mistakes": "0.108.0",
542
+ "next": "16.4.4",
543
+ "no-mistakes": "0.108.1",
544
544
  "pg": "8.23.1",
545
545
  "react": "19.3.1",
546
546
  "react-dom": "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
@@ -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,7 +24,7 @@
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
  {
@@ -36,7 +36,7 @@
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,32 +50,32 @@
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
  {
@@ -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
  },
@@ -145,60 +145,60 @@
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",
@@ -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
@@ -1,24 +0,0 @@
1
- #!/usr/bin/env bash
2
- set -euo pipefail
3
-
4
- if [ "$#" -eq 0 ]; then
5
- echo "usage: harness-assert-gates.sh <gate>..." >&2
6
- exit 2
7
- fi
8
-
9
- for gate in "$@"; do
10
- if ! [[ "$gate" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; then
11
- echo "::error::invalid gate name: '$gate'"
12
- exit 1
13
- fi
14
- done
15
-
16
- for gate in "$@"; do
17
- value="${!gate:-}"
18
- if [ "$value" = "true" ]; then
19
- echo "::error::$gate must be disabled but is enabled"
20
- exit 1
21
- fi
22
- done
23
-
24
- exit 0