vouchington-tooling 0.26.0 → 0.28.0

package/README.md

@@ -80,6 +80,7 @@ vouchington install-playwright-chromium-arm64
 vouchington ghcr-package-retention example%2Fapi
 vouchington harness-admission-lane 4
 vouchington harness-assert-gates HARNESS_DISPATCH_ENABLED HARNESS_SHEPHERD_ENABLED
+echo '[{"login":"octocat","type":"User"}]' | vouchington gha-collaborator-trust owner/repo --allow-bot github-actions[bot]
 vouchington nuget-central-version trusted.props candidate.props metadata.json out.props
 vouchington swift-semantic-equal BASE HEAD App.swift
 vouchington post-review
@@ -554,7 +555,10 @@ Identity, content, and archived-session conflicts fail in either mode while pres
 record; they are not reported as transient pending delivery. Replay retains permanently conflicted
 records and continues to deliver unrelated pending records; transient failures stop that replay.
 Verified delivery retains its receipt when local cleanup fails, returning
-`cleanupDiagnostic` with value `"outbox-cleanup-failed"`. A retained or crash-reappearing record is safe to replay with exact dedup.
+`cleanupDiagnostic` with value `"outbox-cleanup-failed"`. A retained or crash-reappearing record is
+safe to replay: an event is identified by session, `sourceEventId`, and content, and a duplicate that
+differs only in `timestamp` is the same event, so it reports the stored record's `timestamp` and
+receipt and the retained duplicate is removed.
 Use `vouchington agent-blackboard journal flush --outbox-directory PATH` to replay unchanged pending
 records after connectivity returns.
 

package/dist/agent-blackboard/feedback-canonical.d.mts

@@ -1 +1,8 @@
+import type { FeedbackEnvelope } from './feedback-types.mts';
 export declare function canonicalFeedback(value: unknown): string;
+/**
+ * The identity of a feedback event is its session, `sourceEventId`, and content. The `timestamp` is
+ * assigned by the server on each attempt, so a retry that differs only in `timestamp` is the same
+ * event and is left out of the comparison.
+ */
+export declare function canonicalFeedbackEvent(envelope: FeedbackEnvelope): string;

package/dist/agent-blackboard/feedback-canonical.mjs

@@ -2,6 +2,14 @@ import { isObject } from './snapshot-partition-guards.mjs';
 export function canonicalFeedback(value) {
     return JSON.stringify(ordered(value));
 }
+/**
+ * The identity of a feedback event is its session, `sourceEventId`, and content. The `timestamp` is
+ * assigned by the server on each attempt, so a retry that differs only in `timestamp` is the same
+ * event and is left out of the comparison.
+ */
+export function canonicalFeedbackEvent(envelope) {
+    return canonicalFeedback(Object.fromEntries(Object.entries(envelope).filter(([key]) => key !== 'timestamp')));
+}
 function ordered(value) {
     if (Array.isArray(value))
         return value.map(ordered);

package/dist/agent-blackboard/feedback-delivery.mjs

@@ -18,13 +18,14 @@ export async function writeFeedback(input) {
     }
     if (!input.outboxDirectory)
         throw new Error('interactive feedback requires an explicit durable outbox directory');
-    persistFeedbackOutbox(input.outboxDirectory, { identity: input.identity, envelope });
+    // A retained record for the same event keeps its own timestamp and is the one delivered.
+    const record = persistFeedbackOutbox(input.outboxDirectory, {
+        identity: input.identity,
+        envelope,
+    });
     try {
-        const receipt = await deliverFeedbackOnline({ ...input, envelope });
-        const cleanup = removeFeedbackOutbox(input.outboxDirectory, {
-            identity: input.identity,
-            envelope,
-        });
+        const receipt = await deliverFeedbackOnline({ ...input, envelope: record.envelope });
+        const cleanup = removeFeedbackOutbox(input.outboxDirectory, record);
         return { status: 'delivered', sourceEventId: envelope.sourceEventId, ...cleanup, receipt };
     }
     catch (error) {
@@ -34,6 +35,7 @@ export async function writeFeedback(input) {
         return {
             status: 'pending',
             sourceEventId: envelope.sourceEventId,
+            timestamp: record.envelope.timestamp,
             pendingCount: feedbackOutboxStatus(input.outboxDirectory).pendingCount,
             diagnostic,
         };

package/dist/agent-blackboard/feedback-online.mjs

@@ -1,6 +1,6 @@
 import { feedbackDeadline } from './feedback-deadline.mjs';
 import { FeedbackDeliveryError, feedbackDiagnostic } from './feedback-online-error.mjs';
-import { canonicalFeedback } from './feedback-canonical.mjs';
+import { canonicalFeedback, canonicalFeedbackEvent } from './feedback-canonical.mjs';
 import { loadClient, resolveBlackboardConnection } from './client.mjs';
 import { normalizeRepositories, validateFeedbackEnvelope } from './feedback-codec.mjs';
 import { validateFeedbackIdentity } from './feedback-identity.mjs';
@@ -48,13 +48,18 @@ async function findEvent(entries, envelope, expectedCreatedAt) {
         catch {
             throw new FeedbackDeliveryError('event-conflict');
         }
-        if (canonicalFeedback(entry.data) !== canonicalFeedback(envelope) ||
+        // Same event means same content; the stored `timestamp` may differ from this attempt's.
+        if (canonicalFeedbackEvent(entry.data) !== canonicalFeedbackEvent(envelope) ||
             typeof entry.createdAt !== 'string')
             throw new FeedbackDeliveryError('event-conflict');
         if (++matching > 1 && expectedCreatedAt !== undefined)
             throw new FeedbackDeliveryError('event-conflict');
-        if (expectedCreatedAt === undefined || entry.createdAt === expectedCreatedAt)
-            found = { createdAt: entry.createdAt };
+        // Duplicates of one event (a late write beside a retry) report the earliest stored record, so
+        // every retry returns the same timestamp.
+        if (expectedCreatedAt === undefined
+            ? found === undefined || entry.createdAt < found.createdAt
+            : entry.createdAt === expectedCreatedAt)
+            found = { createdAt: entry.createdAt, timestamp: entry.data.timestamp };
     }
     return found;
 }
@@ -108,6 +113,7 @@ export async function deliverFeedbackOnline(input, fresh = false) {
                     sessionId: input.identity.sessionId,
                     sourceEventId: input.envelope.sourceEventId,
                     createdAt: existing.createdAt,
+                    timestamp: existing.timestamp,
                     verified: true,
                 };
             const appended = await entries.append({
@@ -127,6 +133,7 @@ export async function deliverFeedbackOnline(input, fresh = false) {
                 sessionId: input.identity.sessionId,
                 sourceEventId: input.envelope.sourceEventId,
                 createdAt: confirmed.createdAt,
+                timestamp: confirmed.timestamp,
                 verified: true,
             };
         }

package/dist/agent-blackboard/feedback-outbox.d.mts

@@ -1,7 +1,14 @@
 import type { FeedbackOutboxRecord, FeedbackOutboxStatus } from './feedback-types.mts';
 export declare function feedbackOutboxStatus(directory: string): FeedbackOutboxStatus;
 export declare function listFeedbackOutbox(directory: string): FeedbackOutboxRecord[];
-export declare function persistFeedbackOutbox(directory: string, record: FeedbackOutboxRecord): number;
+/** Reads the retained records without creating the outbox directory. */
+export declare function readFeedbackOutbox(directory: string): FeedbackOutboxRecord[];
+/**
+ * Retains the record unless the same event is already retained, in which case that record stays:
+ * the event is the session, `sourceEventId`, and content, and the earlier `timestamp` wins. The
+ * returned record is the one to deliver.
+ */
+export declare function persistFeedbackOutbox(directory: string, record: FeedbackOutboxRecord): FeedbackOutboxRecord;
 export declare function removeFeedbackOutbox(directory: string, record: FeedbackOutboxRecord): {
     pendingCount: number;
     cleanupDiagnostic?: 'outbox-cleanup-failed';

package/dist/agent-blackboard/feedback-outbox.mjs

@@ -1,4 +1,4 @@
-import { canonicalFeedback } from './feedback-canonical.mjs';
+import { canonicalFeedback, canonicalFeedbackEvent } from './feedback-canonical.mjs';
 import { createHash, randomUUID } from 'node:crypto';
 import { closeSync, constants, fsyncSync, fstatSync, openSync, readdirSync, renameSync, unlinkSync, } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
@@ -83,6 +83,18 @@ export function listFeedbackOutbox(directory) {
     const path = outboxDirectory(directory, true);
     return withFileLock(join(path, '.records'), () => records(path).map((item) => item.record));
 }
+/** Reads the retained records without creating the outbox directory. */
+export function readFeedbackOutbox(directory) {
+    const path = outboxDirectory(directory, false);
+    if (!ensurePrivateDirectory(path, false))
+        return [];
+    return withFileLock(join(path, '.records'), () => records(path).map((item) => item.record));
+}
+/**
+ * Retains the record unless the same event is already retained, in which case that record stays:
+ * the event is the session, `sourceEventId`, and content, and the earlier `timestamp` wins. The
+ * returned record is the one to deliver.
+ */
 export function persistFeedbackOutbox(directory, record) {
     validateFeedbackIdentity(record.identity);
     validateFeedbackEnvelope(record.envelope);
@@ -93,9 +105,10 @@ export function persistFeedbackOutbox(directory, record) {
         const existing = current.find((item) => item.path === join(path, name));
         const serialized = JSON.stringify(record);
         if (existing) {
-            if (canonicalFeedback(existing.record) !== canonicalFeedback(record))
+            if (canonicalFeedback(existing.record.identity) !== canonicalFeedback(record.identity) ||
+                canonicalFeedbackEvent(existing.record.envelope) !== canonicalFeedbackEvent(record.envelope))
                 throw new Error('feedback source event conflicts with a retained unsent record');
-            return current.length;
+            return existing.record;
         }
         const bytes = Buffer.byteLength(serialized);
         if (bytes > RECORD_MAX_BYTES ||
@@ -128,7 +141,7 @@ export function persistFeedbackOutbox(directory, record) {
             catch { }
             throw error;
         }
-        return current.length + 1;
+        return record;
     });
 }
 export function removeFeedbackOutbox(directory, record) {

package/dist/agent-blackboard/feedback-types.d.mts

@@ -31,6 +31,8 @@ export type FeedbackReceipt = {
     sessionId: string;
     sourceEventId: string;
     createdAt: string;
+    /** The `timestamp` of the stored entry, which may be earlier than the attempt that confirmed it. */
+    timestamp: string;
     verified: true;
 };
 export type FeedbackDiagnostic = 'blackboard-unavailable' | 'client-unavailable' | 'configuration-invalid' | 'authentication-rejected' | 'identity-conflict' | 'readback-unconfirmed' | 'event-conflict' | 'archived-session' | 'delivery-timeout';
@@ -43,6 +45,8 @@ export type FeedbackDeliveryResult = {
 } | {
     status: 'pending';
     sourceEventId: string;
+    /** The `timestamp` of the retained record that a later flush delivers. */
+    timestamp: string;
     pendingCount: number;
     diagnostic: FeedbackDiagnostic;
 };

package/dist/agent-blackboard/index.d.mts

@@ -19,7 +19,7 @@ export type { BlackboardConnection, BlackboardClientModule, BlackboardClientDepe
 export type * from './feedback-types.mts';
 export { createFeedbackEnvelope, validateFeedbackEnvelope } from './feedback-codec.mts';
 export { writeFeedback, verifyFreshFeedback, flushFeedbackOutbox, FeedbackDeliveryError, } from './feedback-delivery.mts';
-export { feedbackOutboxStatus } from './feedback-outbox.mts';
+export { feedbackOutboxStatus, readFeedbackOutbox } from './feedback-outbox.mts';
 export { composeRetrospective } from './feedback-compose.mts';
 export type { RetrospectiveCompositionInput, FeedbackAssessment } from './feedback-compose.mts';
 export type { JournalAuditOptions } from './feedback-journal-audit.mts';

package/dist/agent-blackboard/index.mjs

@@ -61,5 +61,5 @@ export function formatJournalEntries(sessionId, entries) {
 export { resolveBlackboardConnection } from './client.mjs';
 export { createFeedbackEnvelope, validateFeedbackEnvelope } from './feedback-codec.mjs';
 export { writeFeedback, verifyFreshFeedback, flushFeedbackOutbox, FeedbackDeliveryError, } from './feedback-delivery.mjs';
-export { feedbackOutboxStatus } from './feedback-outbox.mjs';
+export { feedbackOutboxStatus, readFeedbackOutbox } from './feedback-outbox.mjs';
 export { composeRetrospective } from './feedback-compose.mjs';

package/dist/cli/index.mjs

@@ -73,6 +73,10 @@ const SCRIPT_PATHS = {
         path: 'scripts/gha/harness-admission-lane.sh',
     },
     'harness-assert-gates': { command: 'bash', path: 'scripts/gha/harness-assert-gates.sh' },
+    'gha-collaborator-trust': {
+        command: 'bash',
+        path: 'scripts/gha/gha-collaborator-trust.sh',
+    },
 };
 export function runCli(argv = process.argv) {
     const parsed = parseCli(argv);

package/dist/cli/parse.d.mts

@@ -89,7 +89,7 @@ export type ParsedCli = {
     workflowDirectories?: string[];
     actionDirectories?: string[];
 } | ParsedGhaRuntimeAudit | ParsedGhaArtifactsCleanup;
-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';
+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';
 export declare function parseCli(argv: readonly string[]): ParsedCli;
 export declare function parseCommandHelp(command: string | undefined, rest: readonly string[]): {
     kind: 'command-help';

package/dist/cli/parse.mjs

@@ -25,6 +25,7 @@ const SCRIPT_COMMANDS = new Set([
     'ghcr-package-retention',
     'harness-admission-lane',
     'harness-assert-gates',
+    'gha-collaborator-trust',
 ]);
 export function parseCli(argv) {
     const args = argv.slice(2);

package/dist/cli/usage.d.mts

@@ -1,4 +1,4 @@
-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  agent-harness-config          Apply classifier-auto + sandbox keys to agent harnesses\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  require-up-to-date            Require HEAD to include a fetched remote 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  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 past KEEP_MIN\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  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\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 and journal an Agent Blackboard deployment\n  mcp                           Serve the agent-blackboard journal tools over stdio (MCP)\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\nagent-harness-config dump\nagent-harness-config check|apply [--global] [--repo PATH]... [--harness claude|codex|grok|cursor]...\n  [--home PATH]\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>\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]\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 <url-encoded-package>...\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\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 journal append --mode interactive|autonomous --source-event-id ID --work-outcome OUTCOME --coverage-status STATUS --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601] [--coverage-source SOURCE,...] [--dropped-count N] [--outbox-directory PATH]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard journal flush --outbox-directory PATH\nInteractive journal append requires --outbox-directory PATH.\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, snapshot_export, 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";
+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  agent-harness-config          Apply classifier-auto + sandbox keys to agent harnesses\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  require-up-to-date            Require HEAD to include a fetched remote 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  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 past KEEP_MIN\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  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 and journal an Agent Blackboard deployment\n  mcp                           Serve the agent-blackboard journal tools over stdio (MCP)\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\nagent-harness-config dump\nagent-harness-config check|apply [--global] [--repo PATH]... [--harness claude|codex|grok|cursor]...\n  [--home PATH]\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>\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]\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 <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>\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 journal append --mode interactive|autonomous --source-event-id ID --work-outcome OUTCOME --coverage-status STATUS --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601] [--coverage-source SOURCE,...] [--dropped-count N] [--outbox-directory PATH]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard journal flush --outbox-directory PATH\nInteractive journal append requires --outbox-directory PATH.\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, snapshot_export, 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";
 export declare function printUsage(stream?: NodeJS.WritableStream): void;
 export declare function commandNames(usage?: string): string[];
 export declare function commandUsage(command: string, usage?: string): string;

package/dist/cli/usage.mjs

@@ -37,6 +37,7 @@ Commands:
   ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN
   harness-admission-lane        Compute a GITHUB_RUN_ID admission lane for fleet fan-out
   harness-assert-gates          Fail if any named HARNESS_*_ENABLED gate is enabled
+  gha-collaborator-trust        Classify authors as write-access collaborators or not
   nuget-central-version         Validate a Directory.Packages.props PackageVersion delta
   swift-semantic-equal          Compare Swift sources ignoring comments and whitespace
   post-review                   Post one COMMENT review from a staged payload file
@@ -111,6 +112,7 @@ install-playwright-chromium-arm64 [name:archive...]
 ghcr-package-retention <url-encoded-package>...
 harness-admission-lane <lanes>
 harness-assert-gates <gate>...
+gha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json
 nuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>
 swift-semantic-equal <base> <head> <file.swift>
 post-review

package/dist/mcp-server/dispatch.mjs

@@ -2,7 +2,8 @@ import { join } from 'node:path';
 import { FeedbackDeliveryError } from '../agent-blackboard/index.mjs';
 import { optionalString, rejectUnknown, requireObject } from './args.mjs';
 import { readSessionId } from './context.mjs';
-import { journalAppend, journalEntries, outboxFlush, outboxStatus } from './handlers-journal.mjs';
+import { journalAppend, journalEntries } from './handlers-journal.mjs';
+import { outboxFlush, outboxStatus } from './handlers-outbox.mjs';
 import { sessionArchive, sessionEnsure, snapshotExport } from './handlers-session.mjs';
 import { TOOLS } from './tools.mjs';
 import { resolveWorktree } from './worktree.mjs';
@@ -17,14 +18,14 @@ const HANDLERS = {
 };
 const DIAGNOSTIC_HINTS = {
     'identity-conflict': 'the session already exists with a different parent, agent, or version',
-    'event-conflict': 'sourceEventId was already used with different content or timestamp; use a new sourceEventId',
+    'event-conflict': 'sourceEventId was already used with different content; use a new sourceEventId',
     'archived-session': 'the session is archived; write to a new session',
     'authentication-rejected': 'the blackboard rejected AGENT_BLACKBOARD_TOKEN',
     'blackboard-unavailable': 'the blackboard could not be reached or returned an error',
     'configuration-invalid': 'AGENT_BLACKBOARD_URL or AGENT_BLACKBOARD_TOKEN is missing or invalid',
     'client-unavailable': 'agent-blackboard is not installed in the worktree',
-    'readback-unconfirmed': 'the write could not be confirmed; retry with the same sourceEventId and timestamp',
-    'delivery-timeout': 'delivery timed out; retry with the same sourceEventId and timestamp',
+    'readback-unconfirmed': 'the write could not be confirmed; retry the same call (same sourceEventId and content)',
+    'delivery-timeout': 'delivery timed out; retry the same call (same sourceEventId and content)',
 };
 function describeError(error) {
     if (error instanceof FeedbackDeliveryError)

package/dist/mcp-server/fake-blackboard.test-helpers.d.mts

@@ -22,6 +22,8 @@ export type FakeOptions = {
     };
     entries?: StoredEntry[];
     entriesError?: unknown;
+    /** An entry another caller writes just before the next append, after that append's read. */
+    lateEntry?: StoredEntry;
 };
 export type FakeBlackboard = {
     dependencies: BlackboardClientDependencies;
@@ -29,6 +31,7 @@ export type FakeBlackboard = {
         ensure: unknown[];
         patch: unknown[];
         append: unknown[];
+        get: unknown[];
         archive: string[];
         export: unknown[];
     };

package/dist/mcp-server/fake-blackboard.test-helpers.mjs

@@ -15,6 +15,7 @@ export function fakeBlackboard(options = {}) {
         ensure: [],
         patch: [],
         append: [],
+        get: [],
         archive: [],
         export: [],
     };
@@ -44,9 +45,13 @@ export function fakeBlackboard(options = {}) {
     }
     if (options.omitArchive)
         delete Sessions.prototype.archive;
+    let lateEntry = options.lateEntry;
     class Entries {
         async append(input) {
             calls.append.push(input);
+            if (lateEntry)
+                stored.push(lateEntry);
+            lateEntry = undefined;
             const entry = {
                 createdAt: `2026-01-01T00:00:${String(stored.length).padStart(2, '0')}.000Z`,
                 data: input.data,
@@ -54,7 +59,8 @@ export function fakeBlackboard(options = {}) {
             stored.push(entry);
             return entry;
         }
-        async *get() {
+        async *get(input) {
+            calls.get.push(input);
             if (options.entriesError !== undefined)
                 throw options.entriesError;
             yield* stored;

package/dist/mcp-server/handlers-journal.d.mts

@@ -2,5 +2,3 @@ import { type ToolHandler } from './context.mts';
 export declare const journalAppend: ToolHandler;
 /** Every entry as the client returns it, oldest first. Nothing is filtered or rewritten. */
 export declare const journalEntries: ToolHandler;
-export declare const outboxStatus: ToolHandler;
-export declare const outboxFlush: ToolHandler;

package/dist/mcp-server/handlers-journal.mjs

@@ -1,6 +1,7 @@
-import { appendJournalMarkdown, feedbackOutboxStatus, flushFeedbackOutbox, readJournal, } from '../agent-blackboard/index.mjs';
+import { appendJournalMarkdown, readJournal, } from '../agent-blackboard/index.mjs';
 import { optionalRecord, optionalString, requiredChoice, requiredString, requiredStringArray, rejectUnknown, } from './args.mjs';
 import { outboxDirectory, readIdentity } from './context.mjs';
+import { outboxCounts } from './handlers-outbox.mjs';
 const MODES = ['interactive', 'autonomous'];
 const OUTCOMES = [
     'in-progress',
@@ -39,26 +40,35 @@ function readCoverage(args) {
 export const journalAppend = async (args, context) => {
     const identity = readIdentity(args, context.sessionId);
     const mode = requiredChoice(args, 'mode', MODES);
-    // The envelope includes the timestamp, so a retry of one sourceEventId must reuse it. Fixing the
-    // default here and returning it lets the caller do that.
-    const timestamp = optionalString(args, 'timestamp') ?? new Date().toISOString();
+    const sourceEventId = requiredString(args, 'sourceEventId');
     const category = optionalString(args, 'category');
-    const result = await appendJournalMarkdown({
-        ...identity,
-        mode,
-        // Interactive delivery needs a durable outbox; autonomous delivery forbids one.
-        ...(mode === 'interactive' ? { outboxDirectory: outboxDirectory(context.worktree) } : {}),
+    const entry = {
         markdown: requiredString(args, 'markdown'),
-        sourceEventId: requiredString(args, 'sourceEventId'),
         workOutcome: requiredChoice(args, 'workOutcome', OUTCOMES),
         repositories: requiredStringArray(args, 'repositories'),
         feedbackCoverage: readCoverage(args),
-        timestamp,
+    };
+    // Interactive delivery needs a durable outbox; autonomous delivery forbids one.
+    const directory = mode === 'interactive' ? outboxDirectory(context.worktree) : undefined;
+    const result = await appendJournalMarkdown({
+        ...identity,
+        ...entry,
+        mode,
+        sourceEventId,
+        ...(directory === undefined ? {} : { outboxDirectory: directory }),
         ...(category === undefined ? {} : { category }),
         env: context.env,
         dependencies: context.dependencies,
     });
-    return { sessionId: context.sessionId, timestamp, ...result };
+    // The server owns the timestamp: a first append takes the current time, and a retry of the same
+    // event (same session, sourceEventId, and content) reports the one already stored or retained.
+    const timestamp = result.status === 'delivered' ? result.receipt.timestamp : result.timestamp;
+    // Autonomous delivery never uses an outbox, so it has nothing pending. Interactive delivery
+    // reports the outbox as it is after delivery, split into the caller's session and the worktree.
+    const counts = mode === 'interactive'
+        ? outboxCounts(context.worktree, context.sessionId)
+        : { pendingCount: 0, worktreePendingCount: 0 };
+    return { sessionId: context.sessionId, ...result, timestamp, ...counts };
 };
 // `Entries.get` documents no order, and `createdAt` is a service-generated ISO 8601 UTC time whose
 // text order is time order. An entry without a usable `createdAt` sorts first rather than throwing.
@@ -78,21 +88,3 @@ export const journalEntries = async (_args, context) => ({
     sessionId: context.sessionId,
     entries: (await readJournal(context.sessionId, context.env, context.dependencies)).toSorted(byCreatedAt),
 });
-export const outboxStatus = async (_args, context) => ({
-    sessionId: context.sessionId,
-    ...feedbackOutboxStatus(outboxDirectory(context.worktree)),
-});
-export const outboxFlush = async (_args, context) => {
-    const directory = outboxDirectory(context.worktree);
-    // Flushing creates the outbox directory, so an empty or absent outbox is reported as is.
-    if (feedbackOutboxStatus(directory).pendingCount === 0)
-        return { sessionId: context.sessionId, status: 'empty', pendingCount: 0, deliveredCount: 0 };
-    return {
-        sessionId: context.sessionId,
-        ...(await flushFeedbackOutbox({
-            directory,
-            env: context.env,
-            dependencies: context.dependencies,
-        })),
-    };
-};

package/dist/mcp-server/handlers-outbox.d.mts

@@ -0,0 +1,11 @@
+import { type ToolHandler } from './context.mts';
+/**
+ * The outbox belongs to the worktree, not to one session, so two counts are reported. `pendingCount`
+ * is the caller's session only; `worktreePendingCount` is every session's records.
+ */
+export declare function outboxCounts(worktree: string, sessionId: string): {
+    pendingCount: number;
+    worktreePendingCount: number;
+};
+export declare const outboxStatus: ToolHandler;
+export declare const outboxFlush: ToolHandler;

package/dist/mcp-server/handlers-outbox.mjs

@@ -0,0 +1,45 @@
+import { flushFeedbackOutbox, readFeedbackOutbox } from '../agent-blackboard/index.mjs';
+import { outboxDirectory } from './context.mjs';
+/**
+ * The outbox belongs to the worktree, not to one session, so two counts are reported. `pendingCount`
+ * is the caller's session only; `worktreePendingCount` is every session's records.
+ */
+export function outboxCounts(worktree, sessionId) {
+    // A read that never creates the directory, so asking about an empty outbox leaves no trace.
+    const records = readFeedbackOutbox(outboxDirectory(worktree));
+    return {
+        pendingCount: records.filter((record) => record.identity.sessionId === sessionId).length,
+        worktreePendingCount: records.length,
+    };
+}
+function sessionStatus(pendingCount) {
+    return pendingCount === 0 ? 'empty' : 'pending';
+}
+export const outboxStatus = async (_args, context) => {
+    const counts = outboxCounts(context.worktree, context.sessionId);
+    return { sessionId: context.sessionId, status: sessionStatus(counts.pendingCount), ...counts };
+};
+export const outboxFlush = async (_args, context) => {
+    // Flushing creates the outbox directory, so an empty or absent outbox is reported as is.
+    if (outboxCounts(context.worktree, context.sessionId).worktreePendingCount === 0)
+        return {
+            sessionId: context.sessionId,
+            status: 'empty',
+            pendingCount: 0,
+            worktreePendingCount: 0,
+            deliveredCount: 0,
+        };
+    // The flush delivers every session's records; only the counts below are per session.
+    const flushed = await flushFeedbackOutbox({
+        directory: outboxDirectory(context.worktree),
+        env: context.env,
+        dependencies: context.dependencies,
+    });
+    const counts = outboxCounts(context.worktree, context.sessionId);
+    return {
+        sessionId: context.sessionId,
+        ...flushed,
+        status: sessionStatus(counts.pendingCount),
+        ...counts,
+    };
+};

package/dist/mcp-server/harness.test-helpers.d.mts

@@ -29,5 +29,10 @@ export declare const JOURNAL_ARGS: {
         sources: string[];
         droppedCount: number;
     };
-    timestamp: string;
+};
+/** The time `useFixedClock` pins, which is the timestamp the server mints for a first append. */
+export declare const NOW = "2026-01-01T00:00:00.000Z";
+/** Pins `Date` only, so timers and child processes keep running. */
+export declare function useFixedClock(): {
+    advance: (milliseconds: number) => void;
 };

package/dist/mcp-server/harness.test-helpers.mjs

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import { afterEach, beforeEach } from 'vitest';
+import { afterEach, beforeEach, vi } from 'vitest';
 import { callTool } from './dispatch.mjs';
 import { BLACKBOARD_ENV, fakeBlackboard, } from './fake-blackboard.test-helpers.mjs';
 import { createRepoFixture } from './git-fixture.test-helpers.mjs';
@@ -44,5 +44,17 @@ export const JOURNAL_ARGS = {
     workOutcome: 'success',
     repositories: ['owner/repo'],
     feedbackCoverage: { status: 'complete', sources: ['tool-result'], droppedCount: 0 },
-    timestamp: '2026-01-01T00:00:00.000Z',
 };
+/** The time `useFixedClock` pins, which is the timestamp the server mints for a first append. */
+export const NOW = '2026-01-01T00:00:00.000Z';
+/** Pins `Date` only, so timers and child processes keep running. */
+export function useFixedClock() {
+    beforeEach(() => {
+        vi.useFakeTimers({ toFake: ['Date'] });
+        vi.setSystemTime(new Date(NOW));
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    return { advance: (milliseconds) => vi.setSystemTime(new Date(Date.now() + milliseconds)) };
+}

package/dist/mcp-server/server.mjs

@@ -3,7 +3,11 @@ import { TOOLS } from './tools.mjs';
 export const SERVER_NAME = 'vouchington-tooling';
 const INSTRUCTIONS = 'Journals agent-blackboard feedback for a vouchington consumer. Every tool takes an explicit ' +
     'sessionId and an optional worktree (an absolute path listed by `git worktree list` for the ' +
-    'repository this server was launched from). Tool errors are actionable; do not fall back to a CLI.';
+    'repository this server was launched from). Hosts prefix the tool names differently: Claude ' +
+    'Code mcp__vouchington-tooling__<tool>, Codex mcp__vouchington_tooling__<tool>, Grok ' +
+    'vouchington-tooling__<tool> (through search_tool and use_tool), Cursor the vouchington-tooling ' +
+    'namespace (through GetDynamicTools and CallDynamicTool). Search for journal_append before ' +
+    'concluding this server is unavailable. Tool errors are actionable; do not fall back to a CLI.';
 /**
  * Builds the server. The tool list and call handlers go on the low-level `server` because the
  * high-level `registerTool` path needs zod schemas, and this package keeps zod out of its own code.