vouchington-tooling 0.47.0 → 0.49.0

package/README.md

@@ -105,6 +105,20 @@ python3 extracted/package/scripts/allocate-browser-safe-ports.py <count> [--poli
 straddles the cutoff. CI jobs without an install should fetch the tarball instead. Tests enforce
 that the script stays stdlib-only and reads only its two sibling JSON files.
 
+### Configuring `ghcr-package-retention`
+
+Packages come from the arguments, or from `GHCR_PACKAGES` (space separated) when none are given.
+`GHCR_OWNER_TYPE` (`user` default, or `org` with `GHCR_OWNER`) picks the API root.
+
+- Default strategy: keep the newest `KEEP_MIN` (10) versions that carry no tag starting with
+  `PROTECTED_TAG_PREFIX` (`latest`) or containing `PROTECTED_TAG_CONTAINS` (`buildcache`). It
+  deletes unless `--dry-run` is passed.
+- `--main-history`: for images tagged `sha-<40 hex>`. Run from a full-history checkout. Deletes
+  images past the newest `GHCR_KEEP_MAIN` (30) commits reachable from `HEAD`, unreachable images
+  idle for `GHCR_UNMERGED_MIN_AGE_DAYS` (7) days, and attestation/platform attachments that
+  outlive every surviving image. A package that does not exist (HTTP 404) is skipped. This mode
+  is a dry run unless `--apply` is passed.
+
 For persistent `pnpm-install`, v5 metadata tracks structural inputs separately from the
 `--install-scripts` policy. A warm scripts-enabled tree can therefore toggle
 `true → false → true` without forced reconciliation; a tree first installed with scripts disabled
@@ -165,7 +179,11 @@ pass `--root`, `--workflow-directory`, or `--action-directory` for consumer-owne
 Claude-compatible transcript when `CURSOR_SESSION_ID` is set, and Grok's `updates.jsonl` session
 layout when `GROK_SESSION_ID` is set. Use `--grok-sessions-dir` to point discovery at a nondefault
 Grok session root. Without `--session-id`, it reads those session identities from the host
-environment.
+environment. `resolveTranscriptFile` is the canonical resolver: it lowercases and UUID-validates
+session ids, honors `CODEX_HOME`, `CLAUDE_CONFIG_DIR` and `GROK_HOME`, and errors when more than one
+transcript matches. The subpath also exports `normalizeCommandPrefix`, `splitCommandSegments`,
+`isPackageRunner`, `asRecord`, `asArray` and `openTranscriptLines(path, { maxRecordBytes })`, which
+streams lines (2 MiB per record by default) and throws from the iterable on an oversized record.
 
 `retrospective-facts` keeps local Git evidence separate from GitHub PR data. `Commits ahead of
 origin/main` is populated only from a local ancestry range; GitHub responses instead populate

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

@@ -45,6 +45,9 @@ export type BlackboardClientDependencies = {
     resolveFrom?: string | URL;
 };
 export declare function resolveBlackboardConnection(env?: NodeJS.ProcessEnv): BlackboardConnection;
+/** The upstream client package could not be resolved: a workspace-setup problem, not an outage. */
+export declare class BlackboardNotInstalledError extends Error {
+}
 export declare function loadClient(dependencies?: BlackboardClientDependencies): Promise<BlackboardClientModule>;
 export declare function isMissingModuleError(error: unknown): boolean;
 export {};

package/dist/agent-blackboard/client.mjs

@@ -18,6 +18,9 @@ export function resolveBlackboardConnection(env = process.env) {
         throw new Error('AGENT_BLACKBOARD_TOKEN is not set');
     return { baseUrl, token, readRetry: {} };
 }
+/** The upstream client package could not be resolved: a workspace-setup problem, not an outage. */
+export class BlackboardNotInstalledError extends Error {
+}
 export async function loadClient(dependencies = {}) {
     const loader = dependencies.loadClient ?? (() => defaultClientLoader(dependencies.resolveFrom));
     try {
@@ -25,7 +28,7 @@ export async function loadClient(dependencies = {}) {
     }
     catch (error) {
         if (isMissingModuleError(error))
-            throw new Error('agent-blackboard is not installed; install it alongside vouchington-tooling to use this integration', { cause: error });
+            throw new BlackboardNotInstalledError('agent-blackboard is not installed; install it alongside vouchington-tooling to use this integration', { cause: error });
         throw error;
     }
 }

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

@@ -3,6 +3,8 @@ import { type JournalInput } from './journal.mts';
 import { type BlackboardClientDependencies } from './client.mts';
 export { cleanupSnapshotPartitions, partitionSnapshot } from './snapshot.mts';
 export { assertSessionId } from './session-id.mts';
+export { payloadSessionId, probeAdvisory, sessionStartContext, sessionStartOutput, } from './session-start.mts';
+export type { SessionStartOptions } from './session-start.mts';
 export { appendJournalMarkdown } from './journal.mts';
 export type { JournalInput } from './journal.mts';
 export { archiveBlackboardSession, ensureBlackboardSession, exportSnapshot, } from './session-tools.mts';
@@ -14,7 +16,7 @@ export declare function appendJournal(input: JournalInput & {
 }): Promise<FeedbackDeliveryResult>;
 export declare function readJournal(sessionId: string, env?: NodeJS.ProcessEnv, dependencies?: BlackboardClientDependencies): Promise<unknown[]>;
 export declare function formatJournalEntries(sessionId: string, entries: unknown[]): string;
-export { resolveBlackboardConnection } from './client.mts';
+export { BlackboardNotInstalledError, resolveBlackboardConnection } from './client.mts';
 export type { BlackboardConnection, BlackboardClientModule, BlackboardClientDependencies, } from './client.mts';
 export type * from './feedback-types.mts';
 export { createFeedbackEnvelope, validateFeedbackEnvelope } from './feedback-codec.mts';

package/dist/agent-blackboard/index.mjs

@@ -4,6 +4,7 @@ import { readFile } from 'node:fs/promises';
 import { assertSessionId } from "./session-id.mjs";
 export { cleanupSnapshotPartitions, partitionSnapshot } from "./snapshot.mjs";
 export { assertSessionId } from "./session-id.mjs";
+export { payloadSessionId, probeAdvisory, sessionStartContext, sessionStartOutput, } from "./session-start.mjs";
 export { appendJournalMarkdown } from "./journal.mjs";
 export { archiveBlackboardSession, ensureBlackboardSession, exportSnapshot, } from "./session-tools.mjs";
 export async function probeBlackboard(env, dependencies) {
@@ -58,7 +59,7 @@ export function formatJournalEntries(sessionId, entries) {
         .map(({ createdAt, markdown }) => `## ${createdAt}\n\n${markdown}`)
         .join('\n\n');
 }
-export { resolveBlackboardConnection } from "./client.mjs";
+export { BlackboardNotInstalledError, resolveBlackboardConnection } from "./client.mjs";
 export { createFeedbackEnvelope, validateFeedbackEnvelope } from "./feedback-codec.mjs";
 export { writeFeedback, verifyFreshFeedback, flushFeedbackOutbox, FeedbackDeliveryError, } from "./feedback-delivery.mjs";
 export { feedbackOutboxStatus, readFeedbackOutbox } from "./feedback-outbox.mjs";

package/dist/agent-blackboard/session-start.d.mts

@@ -0,0 +1,28 @@
+import { type BlackboardClientDependencies } from './client.mts';
+export type SessionStartOptions = {
+    /** The parsed hook payload; unparseable stdin is `{}`. */
+    payload: Record<string, unknown>;
+    env?: NodeJS.ProcessEnv;
+    /** Environment variable that, when `1`, skips the probe only. Defaults to CHECK_BLACKBOARD_SKIP. */
+    skipEnv?: string;
+    /** Appended to the workspace-setup advisory: how this repository repairs its install. */
+    setupHint?: string;
+    /** Appended to the outage advisory: where this repository documents the deployment. */
+    docsPath?: string;
+    /** How this repository restores a missing journal server; appended to the sandbox advisory. */
+    restoreHint?: string;
+    /** Deadline for the probe in milliseconds. Defaults to 5000. */
+    timeoutMs?: number;
+    /** Called when the probe deadline passes, so a caller can force exit past a hung request. */
+    onTimeout?: () => void;
+    dependencies?: BlackboardClientDependencies;
+    /** Defaults to listing one session with the installed client. */
+    probe?: (env?: NodeJS.ProcessEnv, dependencies?: BlackboardClientDependencies) => Promise<void>;
+};
+/** The first valid, URL-safe session id in the payload, or undefined. */
+export declare function payloadSessionId(payload: Record<string, unknown>): string | undefined;
+/** The advisory line for the deployment probe, or undefined when it is skipped or healthy. */
+export declare function probeAdvisory(options: SessionStartOptions): Promise<string | undefined>;
+/** The `additionalContext` for a SessionStart hook, or undefined when there is nothing to say. */
+export declare function sessionStartContext(options: SessionStartOptions): Promise<string | undefined>;
+export declare function sessionStartOutput(context: string): string;

package/dist/agent-blackboard/session-start.mjs

@@ -0,0 +1,102 @@
+import { BlackboardNotInstalledError, loadClient, resolveBlackboardConnection, } from "./client.mjs";
+import { assertSessionId } from "./session-id.mjs";
+const PAYLOAD_SESSION_KEYS = ['session_id', 'sessionId', 'conversation_id'];
+/** The first valid, URL-safe session id in the payload, or undefined. */
+export function payloadSessionId(payload) {
+    for (const key of PAYLOAD_SESSION_KEYS) {
+        const value = payload[key];
+        if (typeof value !== 'string')
+            continue;
+        const trimmed = value.trim();
+        if (!trimmed || trimmed.length > 256)
+            continue;
+        try {
+            assertSessionId(trimmed);
+        }
+        catch {
+            continue;
+        }
+        return trimmed;
+    }
+    return undefined;
+}
+async function listOneSession(env, dependencies) {
+    const { Sessions } = await loadClient(dependencies);
+    await new Sessions(resolveBlackboardConnection(env)).list({ limit: 1 });
+}
+/** Rejects when the promise has not settled by the deadline; the timer never holds the process. */
+async function withDeadline(work, timeoutMs, onTimeout) {
+    let timer;
+    const deadline = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            onTimeout?.();
+            reject(new Error(`timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        timer.unref();
+    });
+    try {
+        await Promise.race([work, deadline]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** The advisory line for the deployment probe, or undefined when it is skipped or healthy. */
+export async function probeAdvisory(options) {
+    const env = options.env ?? process.env;
+    if (options.payload.source === 'compact')
+        return undefined;
+    if (env[options.skipEnv ?? 'CHECK_BLACKBOARD_SKIP'] === '1')
+        return undefined;
+    // The Claude Code sandbox unsets AGENT_BLACKBOARD_TOKEN and blocks egress, so a sandboxed run
+    // cannot tell "the deployment is down" from "I was never given the credential to check".
+    if (env.SANDBOX_RUNTIME)
+        return ('agent-blackboard probe skipped: it ran inside a sandbox, which withholds the deployment ' +
+            'credential and egress. This is NOT an outage and NOT a reason to stop work. Do not rerun ' +
+            'outside the sandbox to check. Journal through the journal server; search for ' +
+            '`journal_append`. If it is not connected, ' +
+            (options.restoreHint ??
+                'reconnect it from the harness (`/mcp` in Claude Code, or restart Codex)') +
+            ', and tell the user.');
+    try {
+        await withDeadline((options.probe ?? listOneSession)(env, options.dependencies), options.timeoutMs ?? 5000, options.onTimeout);
+    }
+    catch (error) {
+        const message = `sessions list probe failed: ${describe(error)}`;
+        if (error instanceof BlackboardNotInstalledError)
+            return (`agent-blackboard helpers are unavailable (${message}). This is a workspace-setup ` +
+                'problem in this worktree, not a deployment outage; AGENT_BLACKBOARD_URL and ' +
+                `AGENT_BLACKBOARD_TOKEN are not the cause and do not need checking.${hint(options.setupHint)} ` +
+                'Journaling does not need this install: search for `journal_append`, and when the server is ' +
+                'not connected stop journaling and tell the user the server is unavailable and how to fix it.');
+        return (`agent-blackboard availability assessment failed (${message}). Interactive feedback can ` +
+            'continue through the supported durable outbox; delivery remains visibly pending. Verify ' +
+            'the hosted deployment is reachable and AGENT_BLACKBOARD_URL and AGENT_BLACKBOARD_TOKEN are ' +
+            `exported and valid${options.docsPath ? ` (see ${options.docsPath})` : ''}, then start a ` +
+            'fresh session. This probe does not show whether the journal server is connected; if it is ' +
+            'not, stop journaling and tell the user the server is unavailable and how to fix it.');
+    }
+    return undefined;
+}
+function hint(text) {
+    return text ? ` ${text}` : '';
+}
+/** The `additionalContext` for a SessionStart hook, or undefined when there is nothing to say. */
+export async function sessionStartContext(options) {
+    const lines = [];
+    const sessionId = payloadSessionId(options.payload);
+    if (sessionId)
+        lines.push(`Blackboard sessionId: ${sessionId} (pass it as \`sessionId\` to every journal tool)`);
+    const advisory = await probeAdvisory(options);
+    if (advisory !== undefined)
+        lines.push(advisory);
+    return lines.length > 0 ? lines.join('\n') : undefined;
+}
+export function sessionStartOutput(context) {
+    return `${JSON.stringify({
+        hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: context },
+    })}\n`;
+}

package/dist/agent-harness-identity/index.d.mts

@@ -1,26 +1,4 @@
-export declare const HARNESS_IDS: readonly ["claude", "codex", "grok", "cursor"];
-export type HarnessId = (typeof HARNESS_IDS)[number];
-export interface HarnessEnvironment {
-    readonly claude: {
-        readonly compatMode: boolean;
-        readonly sessionId?: string;
-    };
-    readonly codex: {
-        readonly sessionId?: string;
-    };
-    readonly cursor: {
-        readonly agentMarker: boolean;
-        readonly sessionId?: string;
-    };
-    readonly grok: {
-        readonly agentMarker: boolean;
-        readonly hookEvent: boolean;
-        readonly sessionId?: string;
-    };
-}
-export interface HarnessSessionIdentity {
-    readonly harness: HarnessId;
-    readonly sessionId: string;
-}
+import { type HarnessEnvironment } from 'agent-blackboard';
+export { HARNESS_IDS, selectHarnessSession } from 'agent-blackboard';
+export type { HarnessEnvironment, HarnessId, HarnessSessionIdentity } from 'agent-blackboard';
 export declare function inspectHarnessEnvironment(env?: NodeJS.ProcessEnv): HarnessEnvironment;
-export declare function selectHarnessSession(environment: HarnessEnvironment, precedence: readonly HarnessId[]): HarnessSessionIdentity | undefined;

package/dist/agent-harness-identity/index.mjs

@@ -1,30 +1,5 @@
-export const HARNESS_IDS = ['claude', 'codex', 'grok', 'cursor'];
-function session(value) {
-    return value ? { sessionId: value } : {};
-}
+import { inspectHarnessEnvironment as inspect } from 'agent-blackboard';
+export { HARNESS_IDS, selectHarnessSession } from 'agent-blackboard';
 export function inspectHarnessEnvironment(env = process.env) {
-    return {
-        claude: {
-            compatMode: env.CLAUDECODE === '1',
-            ...session(env.CLAUDE_CODE_SESSION_ID),
-        },
-        codex: session(env.CODEX_THREAD_ID),
-        cursor: {
-            agentMarker: Boolean(env.CURSOR_AGENT),
-            ...session(env.CURSOR_SESSION_ID),
-        },
-        grok: {
-            agentMarker: Boolean(env.GROK_AGENT),
-            hookEvent: Boolean(env.GROK_HOOK_EVENT),
-            ...session(env.GROK_SESSION_ID),
-        },
-    };
-}
-export function selectHarnessSession(environment, precedence) {
-    for (const harness of precedence) {
-        const sessionId = environment[harness].sessionId;
-        if (sessionId)
-            return { harness, sessionId };
-    }
-    return undefined;
+    return inspect(env);
 }

package/dist/cli/commands/agent-blackboard-session-start.d.mts

@@ -0,0 +1,5 @@
+/**
+ * SessionStart hook. Advisory only: it never exits nonzero for a probe or credential problem, so a
+ * broken deployment cannot stop a session. Flag misuse still exits 2.
+ */
+export declare function runSessionStart(args: string[]): Promise<number>;

package/dist/cli/commands/agent-blackboard-session-start.mjs

@@ -0,0 +1,60 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { probeBlackboard } from "../../agent-blackboard/index.mjs";
+import { sessionStartContext, sessionStartOutput } from "../../agent-blackboard/session-start.mjs";
+import { assertAllowed, flagsToValues } from "./agent-blackboard-flags.mjs";
+const execFileAsync = promisify(execFile);
+async function insideWorkTree() {
+    try {
+        await execFileAsync('git', ['rev-parse', '--git-dir']);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readStdinPayload() {
+    if (process.stdin.isTTY)
+        return {};
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    const raw = Buffer.concat(chunks).toString('utf8').trim();
+    try {
+        const parsed = raw ? JSON.parse(raw) : {};
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * SessionStart hook. Advisory only: it never exits nonzero for a probe or credential problem, so a
+ * broken deployment cannot stop a session. Flag misuse still exits 2.
+ */
+export async function runSessionStart(args) {
+    const values = flagsToValues(args);
+    assertAllowed(values, ['skip-env', 'setup-hint', 'docs-path', 'restore-hint', 'timeout-ms']);
+    const timeoutMs = values['timeout-ms'] === undefined ? undefined : Number(values['timeout-ms']);
+    if (timeoutMs !== undefined && !(Number.isInteger(timeoutMs) && timeoutMs > 0))
+        throw new Error('--timeout-ms must be a positive integer');
+    if (!(await insideWorkTree()))
+        return 0;
+    const context = await sessionStartContext({
+        payload: await readStdinPayload(),
+        dependencies: { resolveFrom: import.meta.url },
+        probe: probeBlackboard,
+        // A request that ignores the deadline would keep the process alive: exit once output is out.
+        onTimeout: () => setTimeout(() => process.exit(0), 250).unref(),
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        ...(values['restore-hint'] ? { restoreHint: values['restore-hint'] } : {}),
+        ...(values['skip-env'] ? { skipEnv: values['skip-env'] } : {}),
+        ...(values['setup-hint'] ? { setupHint: values['setup-hint'] } : {}),
+        ...(values['docs-path'] ? { docsPath: values['docs-path'] } : {}),
+    });
+    if (context !== undefined)
+        process.stdout.write(sessionStartOutput(context));
+    return 0;
+}

package/dist/cli/commands/agent-blackboard-snapshot.d.mts

@@ -0,0 +1 @@
+export declare function runSnapshot(args: string[]): Promise<number>;

package/dist/cli/commands/agent-blackboard-snapshot.mjs

@@ -0,0 +1,29 @@
+import { cleanupSnapshotPartitions, partitionSnapshot } from "../../agent-blackboard/snapshot.mjs";
+import { assertAllowed, flagsToValues, required } from "./agent-blackboard-flags.mjs";
+export async function runSnapshot(args) {
+    const [action, ...flags] = args;
+    const values = flagsToValues(flags);
+    if (action === 'cleanup') {
+        assertAllowed(values, ['snapshot', 'partition-directory', 'receipt']);
+        if (values['partition-directory'] && !values.receipt)
+            throw new Error('--receipt is required with --partition-directory');
+        await cleanupSnapshotPartitions({
+            ...(values.snapshot ? { path: values.snapshot } : {}),
+            ...(values['partition-directory'] ? { directory: values['partition-directory'] } : {}),
+            ...(values.receipt ? { receipt: JSON.parse(values.receipt) } : {}),
+        });
+        process.stdout.write('{"cleaned":true}\n');
+        return 0;
+    }
+    if (action === 'partition') {
+        assertAllowed(values, ['snapshot', 'checksum', 'counts']);
+        const counts = JSON.parse(required(values, 'counts'));
+        process.stdout.write(`${JSON.stringify(await partitionSnapshot({
+            path: required(values, 'snapshot'),
+            checksum: { algorithm: 'sha256', value: required(values, 'checksum') },
+            counts,
+        }))}\n`);
+        return 0;
+    }
+    throw new Error('usage: agent-blackboard snapshot partition|cleanup');
+}

package/dist/cli/commands/agent-blackboard.mjs

@@ -1,6 +1,7 @@
 import { assertAllowed, flagsToValues, required, validatedSessionId, } from "./agent-blackboard-flags.mjs";
+import { runSnapshot } from "./agent-blackboard-snapshot.mjs";
+import { runSessionStart } from "./agent-blackboard-session-start.mjs";
 import { appendJournal, feedbackOutboxCounts, flushFeedbackOutbox, formatJournalEntries, probeBlackboard, readJournal, } from "../../agent-blackboard/index.mjs";
-import { cleanupSnapshotPartitions, partitionSnapshot } from "../../agent-blackboard/snapshot.mjs";
 const dependencies = { resolveFrom: import.meta.url };
 let journalReader = readJournal;
 export function setJournalReaderForTest(reader) {
@@ -17,40 +18,15 @@ export async function runAgentBlackboardCommand(args) {
             return await runJournal(rest);
         if (command === 'snapshot')
             return await runSnapshot(rest);
-        throw new Error('usage: agent-blackboard probe | journal append|entries|flush|status | snapshot partition|cleanup');
+        if (command === 'session-start')
+            return await runSessionStart(rest);
+        throw new Error('usage: agent-blackboard probe | session-start | journal append|entries|flush|status | snapshot partition|cleanup');
     }
     catch (error) {
         process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
         return 2;
     }
 }
-async function runSnapshot(args) {
-    const [action, ...flags] = args;
-    const values = flagsToValues(flags);
-    if (action === 'cleanup') {
-        assertAllowed(values, ['snapshot', 'partition-directory', 'receipt']);
-        if (values['partition-directory'] && !values.receipt)
-            throw new Error('--receipt is required with --partition-directory');
-        await cleanupSnapshotPartitions({
-            ...(values.snapshot ? { path: values.snapshot } : {}),
-            ...(values['partition-directory'] ? { directory: values['partition-directory'] } : {}),
-            ...(values.receipt ? { receipt: JSON.parse(values.receipt) } : {}),
-        });
-        process.stdout.write('{"cleaned":true}\n');
-        return 0;
-    }
-    if (action === 'partition') {
-        assertAllowed(values, ['snapshot', 'checksum', 'counts']);
-        const counts = JSON.parse(required(values, 'counts'));
-        process.stdout.write(`${JSON.stringify(await partitionSnapshot({
-            path: required(values, 'snapshot'),
-            checksum: { algorithm: 'sha256', value: required(values, 'checksum') },
-            counts,
-        }))}\n`);
-        return 0;
-    }
-    throw new Error('usage: agent-blackboard snapshot partition|cleanup');
-}
 async function runJournal(args) {
     const [action, ...flags] = args;
     const { repositories, remaining } = action === 'append' ? extractRepositories(flags) : { repositories: [], remaining: flags };

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  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  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\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]\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 status --session-id UUID --outbox-directory PATH\nagent-blackboard journal flush --outbox-directory PATH [--session-id UUID]\nInteractive journal append requires --outbox-directory PATH.\nagent-blackboard journal is deprecated and being phased out: agents journal through the mcp server.\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\nmcp\n  (no args)              Serve journal_append, journal_entries, outbox_status, outbox_flush,\n                         session_ensure, retrospective_check, retrospective_save,\n                         pr_validate, pr_create, pr_update,\n                         snapshot_export, snapshot_cleanup, and session_archive over stdio.\n                         Needs the optional @modelcontextprotocol/sdk peer (and zod).\n                         Launch it from inside the repository's git worktree.\n";
+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  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  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  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\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]\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>\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 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 status --session-id UUID --outbox-directory PATH\nagent-blackboard journal flush --outbox-directory PATH [--session-id UUID]\nInteractive journal append requires --outbox-directory PATH.\nagent-blackboard journal is deprecated and being phased out: agents journal through the mcp server.\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\nmcp\n  (no args)              Serve journal_append, journal_entries, outbox_status, outbox_flush,\n                         session_ensure, retrospective_check, retrospective_save,\n                         pr_validate, pr_create, pr_update,\n                         snapshot_export, snapshot_cleanup, and session_archive over stdio.\n                         Needs the optional @modelcontextprotocol/sdk peer (and zod).\n                         Launch it from inside the repository's git worktree.\n";
 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

@@ -34,7 +34,7 @@ Commands:
   materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl
   wait-for-apt-locks            Wait until apt/dpkg lock files are free
   install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json
-  ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN
+  ghcr-package-retention        Delete old GHCR package versions (KEEP_MIN or --main-history)
   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
@@ -106,7 +106,7 @@ lint-links [--offline] [--config PATH] [--glob PATTERN] [files...]
 materialize-pr-context
 wait-for-apt-locks
 install-playwright-chromium-arm64 [name:archive...]
-ghcr-package-retention <url-encoded-package>...
+ghcr-package-retention [--main-history] [--apply|--dry-run] [<url-encoded-package>...]
 harness-admission-lane <lanes>
 harness-assert-gates <gate>...
 gha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json
@@ -118,6 +118,7 @@ retrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH]
 link-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>  Link a packaged or repository-local skill
 retrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]
 agent-blackboard probe
+agent-blackboard session-start [--skip-env NAME] [--setup-hint TEXT] [--docs-path PATH] [--restore-hint TEXT] [--timeout-ms N]  (SessionStart hook; payload on stdin)
 agent-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]
 agent-blackboard journal entries --session-id UUID
 agent-blackboard journal status --session-id UUID --outbox-directory PATH

package/dist/mcp-server/pr-agent.mjs

@@ -1,5 +1,5 @@
+import { HARNESS_SESSION_PRECEDENCE } from 'agent-blackboard';
 import { inspectHarnessEnvironment } from "../agent-harness-identity/index.mjs";
-const PRECEDENCE = ['codex', 'claude', 'cursor', 'grok'];
 /**
  * The harness that launched this server, from the launch environment first and the MCP client's
  * `initialize` `clientInfo.name` second. Neither comes from a tool argument.
@@ -12,11 +12,11 @@ export function deriveAgent(env, clientName) {
         cursor: found.cursor.agentMarker || Boolean(found.cursor.sessionId),
         grok: found.grok.agentMarker || found.grok.hookEvent || Boolean(found.grok.sessionId),
     };
-    const fromEnv = PRECEDENCE.find((id) => present[id]);
+    const fromEnv = HARNESS_SESSION_PRECEDENCE.find((id) => present[id]);
     if (fromEnv !== undefined)
         return fromEnv;
     const name = clientName?.toLowerCase() ?? '';
-    return PRECEDENCE.find((id) => name.includes(id));
+    return HARNESS_SESSION_PRECEDENCE.find((id) => name.includes(id));
 }
 /**
  * The text of the `Agent:` line before the session. The agent is the derived harness; a caller

package/dist/retrospective-transcript/as-array.d.mts

@@ -0,0 +1 @@
+export declare function asArray(value: unknown): unknown[];

package/dist/retrospective-transcript/as-array.mjs

@@ -0,0 +1,3 @@
+export function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}

package/dist/retrospective-transcript/command-prefix.d.mts

@@ -0,0 +1 @@
+export declare function normalizeCommandPrefix(command: string): string;

package/dist/retrospective-transcript/command-prefix.mjs

@@ -0,0 +1,124 @@
+import { isPackageRunner, splitCommandSegments } from "./command-segments.mjs";
+// A real command/subcommand token (binary name, git subcommand, short flag, script
+// name) is always well under this length. A token that exceeds it isn't a command
+// token at all — it's payload that got tokenized as one word because it had no
+// internal whitespace (a `VAR={...json...}` assignment, a giant quoted printf arg).
+// Such tokens are replaced with a redaction marker rather than truncated: truncation
+// still leaks a prefix of whatever the token contains (a secret can sit at the front,
+// e.g. "AWS_SECRET_ACCESS_KEY=AKIA..."), while a full-token redaction leaks nothing
+// regardless of where sensitive content falls inside it. This intentionally also
+// redacts long-but-benign tokens (e.g. a `cd /very/long/worktree/path` argument) —
+// for a privacy boundary, over-redacting a legitimate token is the safe failure mode.
+const MAX_COMMAND_TOKEN_LENGTH = 40;
+const REDACTED_TOKEN = '…';
+function redactOverlongToken(token) {
+    return token.length > MAX_COMMAND_TOKEN_LENGTH ? REDACTED_TOKEN : token;
+}
+const ENV_ASSIGNMENT_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*=/;
+// A segment's real command starts after any leading `VAR=value` assignments (e.g.
+// "CI=1 pnpm exec vitest", "GIT_EDITOR=true git rebase --continue" — both real
+// patterns used in real agent sessions). Without stripping these, the
+// env-var token itself gets normalized as if it were the command, so "CI=1 pnpm exec
+// vitest" would classify as prefix "CI=1 pnpm" instead of "pnpm exec vitest". Only
+// strips when a token remains afterward — a segment that is *entirely*
+// assignment-shaped tokens (e.g. a lone `OLD_POLICY_JSON={...}` token with no
+// whitespace) has no command to recover, and is left alone so it still falls through
+// to the general redaction path below instead of normalizing to an empty prefix.
+function stripEnvPrefix(segment) {
+    const index = segment.findIndex((token) => !ENV_ASSIGNMENT_PATTERN.test(token));
+    return index === -1 ? segment : segment.slice(index);
+}
+// Git global options precede the real subcommand — "git -C <path> status" and
+// "git status" are the same command family for policy-matching purposes (`git -h`
+// documents `git [-C <path>] [-c <name>=<value>] ... <command> [<args>]`). `-C`/`-c`
+// take a separate-token argument; `--git-dir=<path>`-style options fold their argument
+// into one `=`-joined token; the rest take no argument at all. Skipping them keeps the
+// normalized prefix on the subcommand instead of stalling on the option — without this,
+// e.g. `git -C <worktree> status` normalizes to "git -C" and reports as an uncovered
+// escalation/block candidate under the wrong prefix, even though `git status` is
+// already covered by an existing narrow allow rule.
+const GIT_GLOBAL_OPTIONS_WITH_ARG = new Set(['-C', '-c']);
+const GIT_GLOBAL_OPTIONS_NO_ARG = new Set([
+    '-v',
+    '--version',
+    '-h',
+    '--help',
+    '--exec-path',
+    '--html-path',
+    '--man-path',
+    '--info-path',
+    '-p',
+    '--paginate',
+    '-P',
+    '--no-pager',
+    '--no-replace-objects',
+    '--bare',
+]);
+const GIT_GLOBAL_OPTION_WITH_INLINE_ARG = /^--[a-z-]+=/;
+function stripGitGlobalOptions(tokens) {
+    let index = 0;
+    while (index < tokens.length) {
+        const token = tokens[index];
+        if (GIT_GLOBAL_OPTIONS_WITH_ARG.has(token))
+            index += 2;
+        else if (GIT_GLOBAL_OPTIONS_NO_ARG.has(token) || GIT_GLOBAL_OPTION_WITH_INLINE_ARG.test(token))
+            index += 1;
+        else
+            break;
+    }
+    return tokens.slice(index);
+}
+// Normalizes a segment to "<leading token> <first subcommand>" (e.g. "git status",
+// "gh pr", or just "cat" when there's no second token), with one exception that goes
+// one token deeper because a permissions file may distinguish at that depth:
+// package runners — "pnpm run build" vs "pnpm exec build" are different
+// permission entries, so the run/exec target must
+// stay out of the generic two-token rule.
+function normalizeSegment(segment) {
+    const [first, ...rest] = segment;
+    if (!first)
+        return '';
+    // A segment that is only assignments (stripEnvPrefix left it intact) has no command;
+    // its value may be a secret of any length, so always redact it.
+    if (ENV_ASSIGNMENT_PATTERN.test(first))
+        return REDACTED_TOKEN;
+    if (isPackageRunner(first) && (rest[0] === 'run' || rest[0] === 'exec') && rest[1]) {
+        return `${redactOverlongToken(first)} ${rest[0]} ${redactOverlongToken(rest[1])}`;
+    }
+    const effectiveRest = first === 'git' ? stripGitGlobalOptions(rest) : rest;
+    return effectiveRest[0]
+        ? `${redactOverlongToken(first)} ${redactOverlongToken(effectiveRest[0])}`
+        : redactOverlongToken(first);
+}
+// A leading "cd <path> && ..." (or "cd <path>; ...") prelude is not itself the
+// actionable command — it's a workdir change common in Bash sessions with no separate
+// cwd param. Without skipping it, "cd /repo && pnpm install" would normalize to "cd
+// /repo" and both miss existing pnpm policy coverage and leak a checkout path into
+// non-raw retro output. Only a *leading run* of cd segments is skipped — a bare `cd
+// /repo` with nothing after it has no other segment to fall back to, so it still
+// normalizes as-is.
+function skipLeadingCdSegments(segments) {
+    let index = 0;
+    while (index < segments.length - 1 && stripEnvPrefix(segments[index])[0] === 'cd')
+        index++;
+    return segments.slice(index);
+}
+// Produces a classification key for a raw shell command, for comparison against the
+// prefix lists in a consumer permissions file (excluded commands, allow,
+// and deny lists). This is a privacy
+// boundary: callers building non---raw report output must emit only this normalized
+// prefix, never the raw `command` string.
+//
+// Only the first non-cd segment of a compound command (`git status && git push`) is
+// normalized — this is a rough per-command categorization tool, not a full command
+// parser, so a compound command is bucketed by its first actionable part.
+//
+// The leading token is preserved as-is (no basename stripping for a path-qualified
+// binary like "/usr/bin/git"):
+// permissions files may also list literal relative-path scripts (e.g. "./scripts/run")
+// that must not be collapsed to a basename.
+export function normalizeCommandPrefix(command) {
+    const segments = skipLeadingCdSegments(splitCommandSegments(command));
+    const segment = stripEnvPrefix(segments[0] ?? []);
+    return normalizeSegment(segment);
+}

package/dist/retrospective-transcript/command-segments.d.mts

@@ -0,0 +1,2 @@
+export declare function splitCommandSegments(command: string): string[][];
+export declare function isPackageRunner(word: string | undefined): boolean;

package/dist/retrospective-transcript/command-segments.mjs

@@ -0,0 +1,54 @@
+// Commands are matched by command position, not by scanning for words anywhere in
+// the string. The string is split into segments on unquoted `;`, `&`, `|` and
+// newlines (so `git push;gh pr view` splits even with no surrounding whitespace).
+// Quoted spans, including any whitespace inside them, are grouped into a single
+// word, mirroring real shell tokenization.
+export function splitCommandSegments(command) {
+    const segments = [];
+    let current = [];
+    let word = '';
+    let quote = null;
+    const flushWord = () => {
+        if (word) {
+            current.push(word);
+            word = '';
+        }
+    };
+    const flushSegment = () => {
+        flushWord();
+        if (current.length) {
+            segments.push(current);
+            current = [];
+        }
+    };
+    for (const char of command) {
+        if (quote) {
+            if (char === quote)
+                quote = null;
+            else
+                word += char;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            continue;
+        }
+        if (char === ';' || char === '&' || char === '|' || char === '\n' || char === '\r') {
+            flushSegment();
+            continue;
+        }
+        if (/\s/.test(char)) {
+            flushWord();
+            continue;
+        }
+        word += char;
+    }
+    flushSegment();
+    return segments;
+}
+const PACKAGE_RUNNERS = ['npx', 'pnpm', 'pnpx', 'yarn'];
+export function isPackageRunner(word) {
+    if (!word)
+        return false;
+    return PACKAGE_RUNNERS.some((runner) => word === runner || word.endsWith(`/${runner}`));
+}

package/dist/retrospective-transcript/index.d.mts

@@ -5,6 +5,11 @@ export { codexChildren, codexIdentity } from './codex.mts';
 export { formatTranscriptFacts, formatUnavailable } from './format.mts';
 export type { ResolveOptions } from './resolve-transcript-file.mts';
 export { resolveTranscriptFile } from './resolve-transcript-file.mts';
+export { asRecord } from './shared.mts';
+export { asArray } from './as-array.mts';
+export { normalizeCommandPrefix } from './command-prefix.mts';
+export { isPackageRunner, splitCommandSegments } from './command-segments.mts';
+export { DEFAULT_MAX_RECORD_BYTES, openTranscriptLines } from './transcript-lines.mts';
 export type RetrospectiveTranscriptReport = {
     markdown: string;
     coverage: 'complete' | 'partial' | 'unavailable';

package/dist/retrospective-transcript/index.mjs

@@ -11,6 +11,11 @@ import { emptyFacts, hasMalformedInteriorRecord, parseLines, } from "./shared.mj
 export { codexChildren, codexIdentity } from "./codex.mjs";
 export { formatTranscriptFacts, formatUnavailable } from "./format.mjs";
 export { resolveTranscriptFile } from "./resolve-transcript-file.mjs";
+export { asRecord } from "./shared.mjs";
+export { asArray } from "./as-array.mjs";
+export { normalizeCommandPrefix } from "./command-prefix.mjs";
+export { isPackageRunner, splitCommandSegments } from "./command-segments.mjs";
+export { DEFAULT_MAX_RECORD_BYTES, openTranscriptLines } from "./transcript-lines.mjs";
 const MALFORMED_INTERIOR = 'malformed interior transcript record';
 function partialCapture(lines) {
     return parseLines(lines).length !== lines.filter((line) => line.trim()).length;

package/dist/retrospective-transcript/resolve-transcript-file.d.mts

@@ -15,5 +15,15 @@ type TranscriptResolution = {
     error: string;
 };
 export declare function globFrom(root: string, pattern: string): string[];
+/**
+ * Canonical transcript resolution for consumers.
+ *
+ * - Session ids are validated as UUIDs and lowercased (`invalid session id format` otherwise).
+ * - Roots honor `CODEX_HOME`, `CLAUDE_CONFIG_DIR` and `GROK_HOME` from `options.env`
+ *   (default `process.env`), unless an explicit `*SessionsDir`/`projectsDir` is given.
+ * - Returns `{ error }` when more than one transcript matches a session, rather than
+ *   picking the first match, and when none matches.
+ * - An explicit `jsonlPath` skips discovery.
+ */
 export declare function resolveTranscriptFile(options: ResolveOptions): TranscriptResolution;
 export {};

package/dist/retrospective-transcript/resolve-transcript-file.mjs

@@ -7,6 +7,16 @@ export const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9
 export function globFrom(root, pattern) {
     return globSync(pattern, { cwd: root }).map((path) => join(root, path));
 }
+/**
+ * Canonical transcript resolution for consumers.
+ *
+ * - Session ids are validated as UUIDs and lowercased (`invalid session id format` otherwise).
+ * - Roots honor `CODEX_HOME`, `CLAUDE_CONFIG_DIR` and `GROK_HOME` from `options.env`
+ *   (default `process.env`), unless an explicit `*SessionsDir`/`projectsDir` is given.
+ * - Returns `{ error }` when more than one transcript matches a session, rather than
+ *   picking the first match, and when none matches.
+ * - An explicit `jsonlPath` skips discovery.
+ */
 export function resolveTranscriptFile(options) {
     if (options.sessionId && !SESSION_ID.test(options.sessionId))
         return { error: 'invalid session id format' };

package/dist/retrospective-transcript/transcript-lines.d.mts

@@ -0,0 +1,22 @@
+export declare const DEFAULT_MAX_RECORD_BYTES: number;
+export type OpenTranscriptLinesOptions = {
+    /** Largest allowed record (one line, excluding its newline) in bytes. Defaults to 2 MiB. */
+    maxRecordBytes?: number;
+};
+export type OpenTranscriptLinesResult = {
+    lines: AsyncIterable<string>;
+} | {
+    error: string;
+};
+/**
+ * Opens a transcript for streaming, one line at a time, with `String.split('\n')`
+ * semantics (a trailing newline yields a final empty line, `\r` is preserved).
+ *
+ * A `maxRecordBytes` that is not a non-negative safe integer rejects with `RangeError`.
+ * An open failure resolves to `{ error }`. An oversized record is NOT skipped or
+ * reported inline: the returned async iterable throws
+ * `transcript record exceeds <maxRecordBytes> byte limit` when it reaches the
+ * record, ending iteration, and the underlying stream is destroyed. Lines yielded
+ * before the oversized record remain valid.
+ */
+export declare function openTranscriptLines(path: string, { maxRecordBytes }?: OpenTranscriptLinesOptions): Promise<OpenTranscriptLinesResult>;

package/dist/retrospective-transcript/transcript-lines.mjs

@@ -0,0 +1,74 @@
+import { createReadStream } from 'node:fs';
+export const DEFAULT_MAX_RECORD_BYTES = 2 * 1024 * 1024;
+/**
+ * Opens a transcript for streaming, one line at a time, with `String.split('\n')`
+ * semantics (a trailing newline yields a final empty line, `\r` is preserved).
+ *
+ * A `maxRecordBytes` that is not a non-negative safe integer rejects with `RangeError`.
+ * An open failure resolves to `{ error }`. An oversized record is NOT skipped or
+ * reported inline: the returned async iterable throws
+ * `transcript record exceeds <maxRecordBytes> byte limit` when it reaches the
+ * record, ending iteration, and the underlying stream is destroyed. Lines yielded
+ * before the oversized record remain valid.
+ */
+export async function openTranscriptLines(path, { maxRecordBytes = DEFAULT_MAX_RECORD_BYTES } = {}) {
+    if (!Number.isSafeInteger(maxRecordBytes) || maxRecordBytes < 0)
+        throw new RangeError('maxRecordBytes must be a non-negative integer');
+    const stream = createReadStream(path);
+    try {
+        await new Promise((resolve, reject) => {
+            stream.once('open', () => resolve());
+            stream.once('error', reject);
+        });
+        const lines = streamTranscriptLines(stream, maxRecordBytes);
+        const release = lines.return.bind(lines);
+        // The file is already open, so cancelling before the first next() must still close it;
+        // an unstarted generator never reaches its own finally block.
+        lines.return = (value) => {
+            stream.destroy();
+            return release(value);
+        };
+        return { lines };
+    }
+    catch (err) {
+        stream.destroy();
+        return { error: err.message };
+    }
+}
+async function* streamTranscriptLines(stream, maxRecordBytes) {
+    const pending = [];
+    let pendingBytes = 0;
+    const tooLarge = () => new Error(`transcript record exceeds ${maxRecordBytes} byte limit`);
+    const line = (tail) => {
+        const bytes = pendingBytes + (tail?.byteLength ?? 0);
+        if (bytes > maxRecordBytes)
+            throw tooLarge();
+        const value = Buffer.concat(tail ? [...pending, tail] : pending, bytes).toString('utf8');
+        pending.length = 0;
+        pendingBytes = 0;
+        return value;
+    };
+    try {
+        for await (const chunk of stream) {
+            let start = 0;
+            for (;;) {
+                const newline = chunk.indexOf(10, start);
+                if (newline === -1)
+                    break;
+                yield line(chunk.subarray(start, newline));
+                start = newline + 1;
+            }
+            if (start < chunk.byteLength) {
+                const tail = chunk.subarray(start);
+                pendingBytes += tail.byteLength;
+                if (pendingBytes > maxRecordBytes)
+                    throw tooLarge();
+                pending.push(tail);
+            }
+        }
+        yield line();
+    }
+    finally {
+        stream.destroy();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.47.0",
+  "version": "0.49.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -375,6 +375,7 @@
     "@types/mdast": "4.0.4",
     "@types/unist": "3.0.3",
     "@typescript-eslint/parser": "^8.71.1",
+    "agent-blackboard": "^0.7.0",
     "csv-parse": "7.0.3",
     "csv-stringify": "6.9.0",
     "dockerfile-ast": "0.7.1",
@@ -390,22 +391,17 @@
     "@modelcontextprotocol/sdk": "1.32.1",
     "@types/picomatch": "^4.0.3",
     "@types/spdx-expression-parse": "4.0.0",
-    "agent-blackboard": "^0.6.1",
     "no-mistakes": "0.83.0",
     "smol-toml": "1.9.1",
     "typescript5": "npm:typescript@5.9.3"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.31.0",
-    "agent-blackboard": "^0.6.1",
     "no-mistakes": "*",
     "typescript": ">=5",
     "vitest": ">=5"
   },
   "peerDependenciesMeta": {
-    "agent-blackboard": {
-      "optional": true
-    },
     "@modelcontextprotocol/sdk": {
       "optional": true
     },

package/scripts/gha/ghcr-main-history.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# Sourced by ghcr-package-retention.sh for --main-history. Expects package_root, packages, apply,
+# keep_main and min_age_days from the caller.
+
+prune_main_history() {
+  # A zero keep count would delete every main image in one run.
+  case "$keep_main" in
+    '' | *[!0-9]*) keep_main=0 ;;
+  esac
+  if [ "$((10#$keep_main))" -lt 1 ]; then
+    echo 'ghcr-package-retention: GHCR_KEEP_MAIN must be a positive integer' >&2
+    exit 2
+  fi
+  case "$min_age_days" in
+    '' | *[!0-9]*)
+      echo 'ghcr-package-retention: GHCR_UNMERGED_MIN_AGE_DAYS must be a non-negative integer' >&2
+      exit 2
+      ;;
+  esac
+
+  # A shallow history would make every older main revision look unmerged.
+  if [ "$(git rev-parse --is-shallow-repository)" != false ]; then
+    echo 'ghcr-package-retention: --main-history needs the full main history (fetch-depth: 0)' >&2
+    exit 2
+  fi
+
+  # Global on purpose: the EXIT trap runs after this function returns.
+  work=$(mktemp -d)
+  trap 'rm -rf "$work"' EXIT
+  git rev-list HEAD > "$work/main-revisions"
+  local cutoff
+  cutoff=$(($(date -u +%s) - min_age_days * 86400))
+
+  local plan='
+  ($revisions | split("\n") | map(select(. != "") | {key: ., value: true}) | from_entries) as $main
+  | (add // []) as $versions
+  | def tags: .metadata.container.tags;
+    def created: .created_at | fromdateiso8601;
+    def idle: [.created_at, .updated_at] | map(fromdateiso8601) | max < $cutoff;
+    def attachment: tags | all(startswith("sha256-"));
+    def canonical: tags | length == 1 and (.[0] | test("^sha-[0-9a-f]{40}$"));
+    def merged: $main[tags[0][4:]] == true;
+    ($versions | map(select(canonical and merged)) | sort_by(.created_at, .id) | reverse
+      | .[$keep:] | map(. + {reason: "main"})) as $old_main
+    | ($versions | map(select(canonical and (merged | not) and idle) | . + {reason: "unmerged"}))
+      as $unmerged
+    | ($old_main + $unmerged | map(.id)) as $doomed
+    | ($versions | map(select((attachment | not) and (.id | IN($doomed[]) | not)) | created)
+      | min) as $oldest_image
+    | ($versions | map(select(attachment and idle and $oldest_image != null
+        and created < $oldest_image - 86400) | . + {reason: "orphan"})) as $orphans
+    | ($old_main + $unmerged + $orphans)[]
+    | "\(.id) \(tags | if length == 0 then "<untagged>" else join(",") end) \(.reason)"'
+
+  local deleted_total=0 package path error deletions id tags reason
+  for package in "${packages[@]}"; do
+    path="$package_root/$package/versions"
+    if ! error=$(gh api --paginate "$path?per_page=100" 2>&1 > "$work/pages"); then
+      case "$error" in
+        # A package that was never published has nothing to prune.
+        *'(HTTP 404)'*)
+          echo "· $package: no such package, skipping"
+          continue
+          ;;
+      esac
+      printf '::error::Could not list %s versions: %s\n' "$package" "$error" >&2
+      exit 1
+    fi
+
+    deletions=$(jq -r -s --rawfile revisions "$work/main-revisions" --argjson keep "$keep_main" \
+      --argjson cutoff "$cutoff" "$plan" "$work/pages")
+    echo "· $package: $(jq -s 'add // [] | length' "$work/pages") version(s)"
+    while read -r id tags reason; do
+      [ -n "$id" ] || continue
+      if [ "$apply" = true ]; then
+        gh api --method DELETE "$path/$id" > /dev/null < /dev/null
+        echo "  deleted $id $tags ($reason)"
+      else
+        echo "  would delete $id $tags ($reason)"
+      fi
+      deleted_total=$((deleted_total + 1))
+    done <<< "$deletions"
+  done
+
+  if [ "$apply" = true ]; then
+    echo "Deleted $deleted_total version(s)."
+  else
+    echo "Dry run: $deleted_total version(s) would be deleted. Pass --apply to delete."
+  fi
+}

package/scripts/gha/ghcr-package-retention.sh

@@ -1,6 +1,20 @@
 #!/usr/bin/env bash
-# Keep the most recent KEEP_MIN non-protected GHCR package versions, plus any
-# version whose tags match the protected prefix/contains rules.
+# Prune GHCR package versions. Two strategies:
+#
+# Default (recent): keep the most recent KEEP_MIN non-protected versions, plus any version whose
+# tags match the protected prefix/contains rules. Deletes unless --dry-run is passed.
+#
+# --main-history: for images published as <package>:sha-<40 hex> by merge groups and main. Run from
+# a full-history checkout. Each version is one of:
+# - An image, with a tag other than sha256-*. Only an image whose single tag is sha-<40 hex> is
+#   deleted: past the newest GHCR_KEEP_MAIN commits reachable from HEAD, or unreachable (an
+#   ejected or failed merge group) once created and updated GHCR_UNMERGED_MIN_AGE_DAYS ago.
+# - An attachment: untagged or tagged only sha256-*. Attestations and their referrer indexes are
+#   pushed after their image, and platform manifests moments before it, so an attachment created
+#   over a day before the oldest surviving image, and idle for the same age, belongs to none.
+# Packages that do not exist (HTTP 404) are skipped. Defaults to a dry run; pass --apply to delete.
+#
+# Packages come from the arguments, or from GHCR_PACKAGES (space separated) when none are given.
 set -euo pipefail
 
 KEEP_MIN="${KEEP_MIN:-10}"
@@ -8,6 +22,30 @@ OWNER_TYPE="${GHCR_OWNER_TYPE:-user}"
 OWNER="${GHCR_OWNER:-}"
 PROTECTED_PREFIX="${PROTECTED_TAG_PREFIX:-latest}"
 PROTECTED_CONTAINS="${PROTECTED_TAG_CONTAINS:-buildcache}"
+keep_main="${GHCR_KEEP_MAIN:-30}"
+min_age_days="${GHCR_UNMERGED_MIN_AGE_DAYS:-7}"
+main_history=false
+apply=''
+
+packages=()
+for argument in "$@"; do
+  case "$argument" in
+    --apply) apply=true ;;
+    --dry-run) apply=false ;;
+    --main-history) main_history=true ;;
+    --*)
+      echo "ghcr-package-retention: unknown argument: $argument" >&2
+      exit 2
+      ;;
+    *) packages+=("$argument") ;;
+  esac
+done
+if [ "${#packages[@]}" -eq 0 ] && [ -n "${GHCR_PACKAGES:-}" ]; then
+  read -r -a packages <<< "$GHCR_PACKAGES"
+fi
+if [ -z "$apply" ]; then
+  if [ "$main_history" = true ]; then apply=false; else apply=true; fi
+fi
 
 case "$KEEP_MIN" in
   *[!0-9]* | '')
@@ -31,12 +69,19 @@ case "$OWNER_TYPE" in
     ;;
 esac
 
-if [ "$#" -eq 0 ]; then
-  echo "usage: ghcr-package-retention.sh <url-encoded-package>..." >&2
+if [ "${#packages[@]}" -eq 0 ]; then
+  echo "usage: ghcr-package-retention.sh [--main-history] [--apply|--dry-run] <url-encoded-package>..." >&2
   exit 2
 fi
 
-for pkg in "$@"; do
+if [ "$main_history" = true ]; then
+  # shellcheck source=/dev/null
+  . "$(dirname "${BASH_SOURCE[0]}")/ghcr-main-history.sh"
+  prune_main_history
+  exit 0
+fi
+
+for pkg in "${packages[@]}"; do
   echo "=== Processing $pkg ==="
   count=0
   while IFS= read -r version_json; do
@@ -57,8 +102,12 @@ for pkg in "$@"; do
       continue
     fi
 
-    printf '  delete: version %s\n' "$version_id"
-    gh api -X DELETE "${package_root}/$pkg/versions/$version_id" || true
+    if [ "$apply" = true ]; then
+      printf '  delete: version %s\n' "$version_id"
+      gh api -X DELETE "${package_root}/$pkg/versions/$version_id" || true
+    else
+      printf '  would delete: version %s\n' "$version_id"
+    fi
   done < <(gh api \
     "${package_root}/$pkg/versions?per_page=100" \
     --jq '.[] | @json')