vouchington-tooling 0.22.1 → 0.24.0

package/dist/agent-blackboard/index.mjs

@@ -1,27 +1,10 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
+import { createFeedbackEnvelope, normalizeRepositories } from './feedback-codec.mjs';
+import { writeFeedback } from './feedback-delivery.mjs';
+import { loadClient, resolveBlackboardConnection, } from './client.mjs';
 import { readFile } from 'node:fs/promises';
-import { createRequire } from 'node:module';
-import { resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { assertSessionId } from './session-id.mjs';
 export { cleanupSnapshotPartitions, partitionSnapshot } from './snapshot.mjs';
 export { assertSessionId } from './session-id.mjs';
-export function resolveBlackboardConnection(env = process.env) {
-    const baseUrl = env.AGENT_BLACKBOARD_URL;
-    const token = env.AGENT_BLACKBOARD_TOKEN;
-    if (!baseUrl)
-        throw new Error('AGENT_BLACKBOARD_URL is not set');
-    if (!token)
-        throw new Error('AGENT_BLACKBOARD_TOKEN is not set');
-    return { baseUrl, token, readRetry: {} };
-}
 export async function probeBlackboard(env, dependencies) {
     const { Sessions } = await loadClient(dependencies);
     await new Sessions(resolveBlackboardConnection(env)).list({ limit: 1 });
@@ -30,7 +13,7 @@ export async function appendJournal(input) {
     assertSessionId(input.sessionId);
     if (input.parentSessionId != null)
         assertSessionId(input.parentSessionId, 'parent session id');
-    const repositories = normalizeRepositories(input.repositories, true);
+    const repositories = normalizeRepositories(input.repositories);
     const timestamp = input.timestamp === undefined ? new Date() : new Date(input.timestamp);
     if (Number.isNaN(timestamp.valueOf()))
         throw new Error('journal timestamp is not a valid date-time');
@@ -38,48 +21,35 @@ export async function appendJournal(input) {
     try {
         markdown = new TextDecoder('utf-8', { fatal: true }).decode(await readFile(input.markdownFile));
     }
-    catch (error) {
-        throw new Error(`note file is not valid UTF-8: ${input.markdownFile}`, { cause: error });
+    catch {
+        throw new Error('note file is not valid UTF-8 or cannot be read');
     }
     if (!markdown)
-        throw new Error(`note file is empty: ${input.markdownFile}`);
-    const connection = resolveBlackboardConnection(input.env);
-    const { Sessions, Entries } = await loadClient(input.dependencies);
-    const sessions = new Sessions(connection);
-    const ensured = await sessions.ensure({
-        id: input.sessionId,
-        parentSessionId: input.parentSessionId ?? null,
-        agent: input.agent,
-        version: input.version,
-    });
-    if (ensured.session.archivedAt != null)
-        throw new Error(`session is archived; create a new session: ${input.sessionId}`);
-    const current = ensured.session.data.repositories;
-    const cumulative = normalizeRepositories(current, false);
-    const merged = [...new Set([...cumulative, ...repositories])].sort();
-    if (JSON.stringify(current) !== JSON.stringify(merged))
-        await sessions.patch({ sessionId: input.sessionId, data: { repositories: merged } });
-    const entry = await new Entries(connection).append({
-        sessionId: input.sessionId,
-        data: { type: 'journal', markdown, timestamp: timestamp.toISOString(), repositories },
+        throw new Error('note file is empty');
+    return writeFeedback({
+        identity: {
+            sessionId: input.sessionId,
+            parentSessionId: input.parentSessionId,
+            agent: input.agent,
+            version: input.version,
+        },
+        envelope: createFeedbackEnvelope({
+            schemaVersion: 1,
+            type: 'journal',
+            sourceEventId: input.sourceEventId,
+            timestamp: timestamp.toISOString(),
+            repositories,
+            markdown,
+            workOutcome: input.workOutcome,
+            feedbackCoverage: input.feedbackCoverage,
+            ...(input.category === undefined ? {} : { category: input.category }),
+        }),
+        mode: input.mode,
+        ...(input.outboxDirectory === undefined ? {} : { outboxDirectory: input.outboxDirectory }),
+        ...(input.env === undefined ? {} : { env: input.env }),
+        ...(input.dependencies === undefined ? {} : { dependencies: input.dependencies }),
+        ...(input.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }),
     });
-    return `Journaled to agent-blackboard session ${input.sessionId} (entry created at ${entry.createdAt}).`;
-}
-function normalizeRepositories(value, required) {
-    if (value === undefined && !required)
-        return [];
-    if (!Array.isArray(value) || (required && value.length === 0))
-        throw new Error('repositories must be a non-empty array of owner/name strings');
-    const repositories = [];
-    for (const candidate of value) {
-        if (typeof candidate !== 'string')
-            throw new Error('repositories must be a non-empty array of owner/name strings');
-        const repository = candidate.trim().toLowerCase();
-        if (!/^[a-z0-9-]+\/[a-z0-9._-]+$/.test(repository))
-            throw new Error(`invalid repository: ${candidate}`);
-        repositories.push(repository);
-    }
-    return [...new Set(repositories)].sort();
 }
 export async function readJournal(sessionId, env, dependencies) {
     assertSessionId(sessionId);
@@ -115,24 +85,8 @@ export function formatJournalEntries(sessionId, entries) {
         .map(({ createdAt, markdown }) => `## ${createdAt}\n\n${markdown}`)
         .join('\n\n');
 }
-async function loadClient(dependencies = {}) {
-    const loader = dependencies.loadClient ?? (() => defaultClientLoader(dependencies.resolveFrom));
-    try {
-        return await loader();
-    }
-    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 error;
-    }
-}
-async function defaultClientLoader(resolveFrom) {
-    const consumerRequire = createRequire(resolveFrom ?? resolve(process.cwd(), 'package.json'));
-    const specifier = pathToFileURL(consumerRequire.resolve('agent-blackboard')).href;
-    return (await import(__rewriteRelativeImportExtension(specifier)));
-}
-function isMissingModuleError(error) {
-    return (error instanceof Error &&
-        'code' in error &&
-        (error.code === 'ERR_MODULE_NOT_FOUND' || error.code === 'MODULE_NOT_FOUND'));
-}
+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 { composeRetrospective } from './feedback-compose.mjs';

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

@@ -1,4 +1,4 @@
-import { appendJournal, formatJournalEntries, probeBlackboard, readJournal, } from '../../agent-blackboard/index.mjs';
+import { appendJournal, flushFeedbackOutbox, formatJournalEntries, probeBlackboard, readJournal, } from '../../agent-blackboard/index.mjs';
 import { cleanupSnapshotPartitions, partitionSnapshot } from '../../agent-blackboard/snapshot.mjs';
 let journalReader = readJournal;
 export function setJournalReaderForTest(reader) {
@@ -15,7 +15,7 @@ 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 | snapshot partition|cleanup');
+        throw new Error('usage: agent-blackboard probe | journal append|entries|flush | snapshot partition|cleanup');
     }
     catch (error) {
         process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
@@ -53,6 +53,12 @@ async function runJournal(args) {
     const [action, ...flags] = args;
     const { repositories, remaining } = action === 'append' ? extractRepositories(flags) : { repositories: [], remaining: flags };
     const values = flagsToValues(remaining);
+    if (action === 'flush') {
+        assertAllowed(values, ['outbox-directory']);
+        const result = await flushFeedbackOutbox({ directory: required(values, 'outbox-directory') });
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+        return 0;
+    }
     if (action === 'entries') {
         assertAllowed(values, ['session-id']);
         const sessionId = required(values, 'session-id');
@@ -76,11 +82,36 @@ async function runJournal(args) {
             'file',
             'parent-session-id',
             'timestamp',
+            'mode',
+            'source-event-id',
+            'work-outcome',
+            'coverage-status',
+            'coverage-source',
+            'dropped-count',
+            'outbox-directory',
         ]);
-        process.stdout.write(`${await appendJournal({ sessionId: required(values, 'session-id'), agent: required(values, 'agent'), version: values.version ?? 'unknown', repositories: requiredRepositories(repositories), markdownFile: required(values, 'file'), ...(values['parent-session-id'] ? { parentSessionId: values['parent-session-id'] } : {}), ...('timestamp' in values ? { timestamp: values.timestamp } : {}) })}\n`);
+        const result = await appendJournal({
+            mode: required(values, 'mode'),
+            sourceEventId: required(values, 'source-event-id'),
+            workOutcome: required(values, 'work-outcome'),
+            feedbackCoverage: {
+                status: required(values, 'coverage-status'),
+                sources: values['coverage-source']?.split(',') ?? [],
+                droppedCount: Number(values['dropped-count'] ?? '0'),
+            },
+            ...(values['outbox-directory'] ? { outboxDirectory: values['outbox-directory'] } : {}),
+            sessionId: required(values, 'session-id'),
+            agent: required(values, 'agent'),
+            version: values.version ?? 'unknown',
+            repositories: requiredRepositories(repositories),
+            markdownFile: required(values, 'file'),
+            ...('timestamp' in values ? { timestamp: values.timestamp } : {}),
+            parentSessionId: values['parent-session-id'] ?? null,
+        });
+        process.stdout.write(`${JSON.stringify(result)}\n`);
         return 0;
     }
-    throw new Error('usage: agent-blackboard journal append|entries');
+    throw new Error('usage: agent-blackboard journal append|entries|flush');
 }
 function extractRepositories(flags) {
     const repositories = [];

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\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 --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601]\nagent-blackboard journal entries --session-id UUID\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]\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  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\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]\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

@@ -118,8 +118,10 @@ 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 journal append --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601]
+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 flush --outbox-directory PATH
+Interactive journal append requires --outbox-directory PATH.
 agent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{"sessions":N,"entries":N,"records":N,"bytes":N}'
 agent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]
 `;

package/dist/markdown/details-scope.d.mts

@@ -0,0 +1,13 @@
+import type { MarkdownSectionsDiagnostic } from './document-types.mts';
+/** Tracks disclosure tags from HTML nodes, never from fenced code or Markdown comments. */
+export declare class DetailsScope {
+    private readonly markdown;
+    readonly diagnostics: MarkdownSectionsDiagnostic[];
+    private readonly frames;
+    constructor(markdown: string);
+    get visible(): boolean;
+    acceptHtml(html: string, startOffset: number): void;
+    finish(): void;
+    private acceptTag;
+    private problem;
+}

package/dist/markdown/details-scope.mjs

@@ -0,0 +1,73 @@
+/** Tracks disclosure tags from HTML nodes, never from fenced code or Markdown comments. */
+export class DetailsScope {
+    markdown;
+    diagnostics = [];
+    frames = [];
+    constructor(markdown) {
+        this.markdown = markdown;
+    }
+    get visible() {
+        return this.frames.length === 0;
+    }
+    acceptHtml(html, startOffset) {
+        const tokens = /<!--[\s\S]*?(?:-->|$)|<\/?[a-z][a-z\d:-]*(?:[^"'<>]|"[^"]*"|'[^']*')*>/giu;
+        for (const token of html.matchAll(tokens)) {
+            if (token[0].startsWith('<!--'))
+                continue;
+            const tag = /^<(\/?)([a-z][a-z\d:-]*)/iu.exec(token[0]);
+            const name = tag[2].toLowerCase();
+            if (name !== 'details' && name !== 'summary')
+                continue;
+            const line = this.markdown.slice(0, startOffset + token.index).split('\n').length;
+            if (/\/\s*>$/u.test(token[0])) {
+                this.problem(line, `${tag[2]} cannot be self-closing`);
+                continue;
+            }
+            this.acceptTag(name, tag[1] === '/', line);
+        }
+    }
+    finish() {
+        for (const frame of this.frames)
+            this.problem(frame.line, 'details has no closing tag');
+    }
+    acceptTag(name, closing, line) {
+        if (name === 'details') {
+            if (!closing) {
+                if (this.frames.at(-1)?.summary === 'open') {
+                    this.problem(line, 'details cannot open inside summary');
+                }
+                this.frames.push({ line, summary: 'absent' });
+                return;
+            }
+            const frame = this.frames.pop();
+            if (!frame)
+                this.problem(line, 'details closes without an opening tag');
+            else if (frame.summary === 'open')
+                this.problem(line, 'summary has no closing tag');
+            return;
+        }
+        const frame = this.frames.at(-1);
+        if (!frame) {
+            this.problem(line, 'summary must be inside details');
+            return;
+        }
+        if (closing) {
+            if (frame.summary !== 'open')
+                this.problem(line, 'summary closes without an opening tag');
+            else
+                frame.summary = 'closed';
+        }
+        else if (frame.summary !== 'absent') {
+            this.problem(line, 'details contains more than one summary or a nested summary');
+        }
+        else
+            frame.summary = 'open';
+    }
+    problem(line, reason) {
+        this.diagnostics.push({
+            code: 'malformed-details',
+            line,
+            message: `Malformed details: ${reason}.`,
+        });
+    }
+}

package/dist/markdown/document-sections.d.mts

@@ -0,0 +1,3 @@
+import type { MarkdownSectionsDocument } from './document-types.mts';
+/** Parses visible root H2 sections while retaining exact source ranges and disclosure scope. */
+export declare function parseMarkdownSections(markdown: string): MarkdownSectionsDocument;

package/dist/markdown/document-sections.mjs

@@ -0,0 +1,64 @@
+import { parseGfmMarkdown } from './ast.mjs';
+import { DetailsScope } from './details-scope.mjs';
+/** Parses visible root H2 sections while retaining exact source ranges and disclosure scope. */
+export function parseMarkdownSections(markdown) {
+    const sections = [];
+    const scope = new DetailsScope(markdown);
+    let current;
+    const visit = (node, collectText) => {
+        if (node.type === 'html') {
+            scope.acceptHtml(node.value, node.position.start.offset);
+            return;
+        }
+        if (node.type === 'code' || node.type === 'image')
+            return;
+        if (collectText &&
+            scope.visible &&
+            current &&
+            (node.type === 'text' || node.type === 'inlineCode') &&
+            node.value.trim()) {
+            current.hasVisibleContent = true;
+        }
+        if (!('children' in node))
+            return;
+        for (const [index, child] of node.children.entries()) {
+            visit(child, collectText && node.type !== 'heading' && (node.type !== 'table' || index > 0));
+        }
+    };
+    for (const node of parseGfmMarkdown(markdown).children) {
+        if (node.type === 'heading') {
+            const wasVisible = scope.visible;
+            const heading = headingText(node, scope).replace(/\s+/gu, ' ').trim();
+            if (node.depth === 2 && wasVisible && heading) {
+                if (current)
+                    current.endOffset = node.position.start.offset;
+                current = {
+                    heading,
+                    content: '',
+                    startOffset: node.position.end.offset,
+                    endOffset: markdown.length,
+                    line: node.position.start.line,
+                    hasVisibleContent: false,
+                };
+                sections.push(current);
+            }
+            continue;
+        }
+        visit(node, node.type === 'paragraph' || node.type === 'list' || node.type === 'table');
+    }
+    scope.finish();
+    for (const section of sections)
+        section.content = markdown.slice(section.startOffset, section.endOffset);
+    return { sections, diagnostics: scope.diagnostics };
+}
+function headingText(node, scope) {
+    if (node.type === 'html') {
+        scope.acceptHtml(node.value, node.position.start.offset);
+        return '';
+    }
+    if (node.type === 'text' || node.type === 'inlineCode')
+        return scope.visible ? node.value : '';
+    if (!('children' in node))
+        return '';
+    return node.children.map((child) => headingText(child, scope)).join('');
+}

package/dist/markdown/document-types.d.mts

@@ -0,0 +1,21 @@
+export type MarkdownVisibleSection = {
+    heading: string;
+    content: string;
+    startOffset: number;
+    endOffset: number;
+    line: number;
+    hasVisibleContent: boolean;
+};
+export type MarkdownSectionsDiagnostic = {
+    code: 'missing-heading' | 'duplicate-heading' | 'empty-section' | 'malformed-details';
+    message: string;
+    heading?: string;
+    line?: number;
+};
+export type MarkdownSectionsDocument = {
+    sections: MarkdownVisibleSection[];
+    diagnostics: MarkdownSectionsDiagnostic[];
+};
+export type ValidateMarkdownSectionsOptions = {
+    requiredHeadings: readonly string[];
+};

package/dist/markdown/document-types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/markdown/index.d.mts

@@ -1,5 +1,8 @@
 export { findMarkdownNode, findMarkdownNodes, parseGfmMarkdown, walkMarkdown } from './ast.mts';
 export { extractLooseMarkdownTableRows } from './loose-pipe-rows.mts';
+export { parseMarkdownSections } from './document-sections.mts';
+export { validateMarkdownSections } from './validate-sections.mts';
+export type { MarkdownVisibleSection, MarkdownSectionsDiagnostic, MarkdownSectionsDocument, ValidateMarkdownSectionsOptions, } from './document-types.mts';
 export { markdownSectionBetweenHeadings } from './sections.mts';
 export { extractMarkdownTables, parseMarkdownTables } from './tables.mts';
 export { markdownNodeText } from './text.mts';

package/dist/markdown/index.mjs

@@ -1,5 +1,7 @@
 export { findMarkdownNode, findMarkdownNodes, parseGfmMarkdown, walkMarkdown } from './ast.mjs';
 export { extractLooseMarkdownTableRows } from './loose-pipe-rows.mjs';
+export { parseMarkdownSections } from './document-sections.mjs';
+export { validateMarkdownSections } from './validate-sections.mjs';
 export { markdownSectionBetweenHeadings } from './sections.mjs';
 export { extractMarkdownTables, parseMarkdownTables } from './tables.mjs';
 export { markdownNodeText } from './text.mjs';

package/dist/markdown/validate-sections.d.mts

@@ -0,0 +1,3 @@
+import type { MarkdownSectionsDiagnostic, MarkdownSectionsDocument, ValidateMarkdownSectionsOptions } from './document-types.mts';
+/** Validates caller-owned headings and visible core content without inferring semantic relevance. */
+export declare function validateMarkdownSections(document: MarkdownSectionsDocument, options: ValidateMarkdownSectionsOptions): MarkdownSectionsDiagnostic[];

package/dist/markdown/validate-sections.mjs

@@ -0,0 +1,34 @@
+/** Validates caller-owned headings and visible core content without inferring semantic relevance. */
+export function validateMarkdownSections(document, options) {
+    const diagnostics = [...document.diagnostics];
+    for (const heading of options.requiredHeadings) {
+        const sections = document.sections.filter((section) => section.heading === heading);
+        if (sections.length === 0) {
+            diagnostics.push({
+                code: 'missing-heading',
+                heading,
+                message: `Missing required section: ${heading}.`,
+            });
+            continue;
+        }
+        if (sections.length > 1) {
+            diagnostics.push({
+                code: 'duplicate-heading',
+                heading,
+                line: sections[1].line,
+                message: `Duplicate required section: ${heading}.`,
+            });
+        }
+        for (const section of sections) {
+            if (!section.hasVisibleContent) {
+                diagnostics.push({
+                    code: 'empty-section',
+                    heading,
+                    line: section.line,
+                    message: `Required section has no visible prose, list, or table content: ${heading}.`,
+                });
+            }
+        }
+    }
+    return diagnostics;
+}

package/dist/retrospective-facts/coverage.d.mts

@@ -0,0 +1,6 @@
+import type { CommandResult } from './shared.mts';
+export type RetrospectiveFactsReport = {
+    markdown: string;
+    coverage: 'complete' | 'partial' | 'unavailable';
+};
+export declare function completeCommandFacts(command: string, args: string[], result: CommandResult): boolean;

package/dist/retrospective-facts/coverage.mjs

@@ -0,0 +1,42 @@
+import { readJson } from './format.mjs';
+export function completeCommandFacts(command, args, result) {
+    if (command === 'git' && args[0] === 'merge-base' && args[1] === '--is-ancestor')
+        return result.ok || result.exitCode === 1;
+    if (!result.ok)
+        return false;
+    if (command !== 'gh') {
+        if (args[0] === 'branch')
+            return Boolean(result.stdout.trim());
+        if (args[0] === 'rev-list')
+            return /^\d+$/.test(result.stdout.trim());
+        return true;
+    }
+    const data = readJson(result.stdout);
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        return false;
+    if (!Number.isInteger(data.number) ||
+        Number(data.number) < 1 ||
+        typeof data.state !== 'string' ||
+        !['OPEN', 'CLOSED', 'MERGED'].includes(data.state) ||
+        typeof data.headRefName !== 'string' ||
+        !data.headRefName ||
+        typeof data.baseRefName !== 'string' ||
+        !data.baseRefName ||
+        !Number.isInteger(data.changedFiles) ||
+        Number(data.changedFiles) < 0 ||
+        !Array.isArray(data.files) ||
+        data.files.length !== data.changedFiles ||
+        !data.files.every((file) => file && typeof file === 'object' && typeof file.path === 'string' && file.path) ||
+        !Array.isArray(data.commits) ||
+        data.commits.length >= 100)
+        return false;
+    if (data.state === 'MERGED')
+        return (typeof data.mergedAt === 'string' &&
+            Boolean(data.mergedAt) &&
+            Boolean(data.mergeCommit &&
+                typeof data.mergeCommit === 'object' &&
+                'oid' in data.mergeCommit &&
+                typeof data.mergeCommit.oid === 'string' &&
+                data.mergeCommit.oid));
+    return true;
+}

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

@@ -1,3 +1,6 @@
+import { type RetrospectiveFactsReport } from './coverage.mts';
 import type { RetrospectiveFactsOptions } from './shared.mts';
 export type { CommandExecutor, CommandResult, RetrospectiveFactsOptions } from './shared.mts';
+export type { RetrospectiveFactsReport } from './coverage.mts';
 export declare function runRetrospectiveFacts(options: RetrospectiveFactsOptions): Promise<string>;
+export declare function runRetrospectiveFactsReport(options: RetrospectiveFactsOptions): Promise<RetrospectiveFactsReport>;

package/dist/retrospective-facts/index.mjs

@@ -1,10 +1,27 @@
 import { shell } from './exec.mjs';
 import { foreignFacts } from './foreign.mjs';
 import { localFacts } from './local.mjs';
+import { completeCommandFacts } from './coverage.mjs';
 export async function runRetrospectiveFacts(options) {
+    return (await runRetrospectiveFactsReport(options)).markdown;
+}
+export async function runRetrospectiveFactsReport(options) {
     validate(options);
     const execute = options.execute ?? shell;
-    return options.repo ? foreignFacts(options, execute) : localFacts(options, execute);
+    let complete = true;
+    let successful = 0;
+    const collect = async (command, args) => {
+        const result = await execute(command, args);
+        if (result.ok)
+            successful++;
+        if (!completeCommandFacts(command, args, result))
+            complete = false;
+        return result;
+    };
+    const markdown = await (options.repo
+        ? foreignFacts(options, collect)
+        : localFacts(options, collect));
+    return { markdown, coverage: complete ? 'complete' : successful ? 'partial' : 'unavailable' };
 }
 function validate(options) {
     if (options.pr !== undefined && !/^\d+$/.test(options.pr))

package/dist/retrospective-transcript/codex.mjs

@@ -5,10 +5,15 @@ export function codexChildren(lines, ownerPath = '/root') {
     const base = ownerPath.replace(/\/$/, '');
     for (const record of parseLines(lines)) {
         const payload = asRecord(record.payload);
-        if (record.type !== 'event_msg' || payload?.type !== 'sub_agent_activity')
+        if (record.type !== 'event_msg')
             continue;
-        const threadId = payload.agent_thread_id;
-        const agentPath = payload.agent_path;
+        const activity = payload?.type === 'sub_agent_activity'
+            ? payload
+            : payload?.type === 'item_completed' && asRecord(payload.item)?.type === 'SubAgentActivity'
+                ? asRecord(payload.item)
+                : undefined;
+        const threadId = activity?.agent_thread_id;
+        const agentPath = activity?.agent_path;
         if (typeof threadId !== 'string' || typeof agentPath !== 'string')
             continue;
         const normalized = agentPath.replace(/\/$/, '');

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

@@ -5,5 +5,10 @@ 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 type RetrospectiveTranscriptReport = {
+    markdown: string;
+    coverage: 'complete' | 'partial' | 'unavailable';
+};
 export declare function computeTranscriptFacts(lines: string[], subagents?: Array<string[] | CodexSegment>): TranscriptFacts;
 export declare function runRetrospectiveTranscript(options: ResolveOptions): Promise<string>;
+export declare function runRetrospectiveTranscriptReport(options: ResolveOptions): Promise<RetrospectiveTranscriptReport>;