vouchington-tooling 0.23.0 → 0.24.1

package/README.md

@@ -66,7 +66,7 @@ vouchington wait-for-apt-locks
 vouchington retrospective-transcript --jsonl /path/to/transcript.jsonl
 vouchington retrospective-facts --pr 49 --repo vouchington/vouchington-infra --raw
 vouchington agent-blackboard probe
-vouchington agent-blackboard journal append --session-id <uuid> --agent codex --version 1 --file note.md --repository vouchington/vouchington-tooling
+vouchington agent-blackboard journal append --session-id <uuid> --agent codex --version 1 --file note.md --repository owner/repo --mode autonomous --source-event-id event:1 --work-outcome in-progress --coverage-status partial --timestamp 2026-01-01T00:00:00.000Z
 vouchington agent-blackboard journal entries --session-id <uuid>
 vouchington agent-blackboard snapshot partition --snapshot <snapshot.jsonl> --checksum <sha256> --counts <counts.json>
 vouchington agent-blackboard snapshot cleanup --snapshot <snapshot.jsonl> --partition-directory <partitions-dir> --receipt <receipt-json>
@@ -147,7 +147,10 @@ as not merged to main, and a missing base is unavailable.
 
 Agent Blackboard support is optional: only the `agent-blackboard` subpath and its CLI commands
 need `agent-blackboard@^0.6.0`. Snapshot cleanup accepts only package-generated temporary paths.
-`appendJournal` requires a `repositories: string[]` argument. The CLI accepts one or more
+`appendJournal` and the journal CLI now require explicit mode, stable source-event identity, work
+outcome, feedback coverage, and exact repositories. This is a breaking pre-1.0 API change; adopt the
+shared contract before upgrading consumers. `appendJournal` reads a bounded UTF-8 note and delegates
+to `writeFeedback`, returning delivered or pending state rather than a success-shaped message. The CLI accepts one or more
 `--repository owner/name` flags; it records the entry's exact repositories and updates the session's
 cumulative repository list before appending.
 Programmatic callers launched from a different workspace directory pass their own module URL as
@@ -405,13 +408,19 @@ absolute log directory, host-independent observation, and journal loader; it doe
 environment variables, install hooks, or connect to a journal service by itself. Invoking
 `recordFriction` touches the session log even when no event is classified, preserving the
 difference between an observed clean session and missing evidence. Report markdown keeps backend
-diagnostics separate from its paste-safe output. Capture stores at most 500 events per session,
+diagnostics separate from its paste-safe output. Capture stores at most 500 events per session and counts rejected captures in a fixed-size atomic
+sidecar under the same session lock for either the event or byte limit, with visible `truncated`/`droppedCount` metadata. Saturated
+capture reads only the bounded counter; reports also preserve historical overflow markers.
+Interrupted or inconsistent counter updates make coverage unavailable. Malformed records also make the scan partial. It
 truncates event detail to 1,000 characters, and consumes up to 500 entries from the journal loader
 when building a report, stopping earlier when its aggregate 1 MB inspected-byte budget is reached.
 Bounded journal scans that stop before exhaustion are reported as incomplete rather than clean.
 Report liveness inherits the caller-supplied journal loader, which must bound its own I/O and yields.
 Log reads are capped at 2 MB, journal Markdown at 10,000 bytes per entry,
-and rendered audit fields at 120 escaped characters. The supplied log directory must be dedicated
+and rendered audit fields at 120 escaped characters. Permission requests record requested outcomes; explicit result observations may record approved
+or denied outcomes. A decision and simultaneous tool failure are both retained and counted in
+the report. Escalation detail without a decision remains unknown. Localhost connection
+refusal is an ambiguous failure and does not establish a sandbox cause. The supplied log directory must be dedicated
 to session-friction; existing directories must already be owner-only, while newly created
 directories and log files are enforced as owner-only when recording. Reads use a fixed bounded
 buffer that can detect growth one byte beyond the documented 2 MB cap.
@@ -506,3 +515,66 @@ links declared prerequisites. Without a manifest, it links the conventional
 outside either root, and existing non-matching destinations.
 `targetRoot` must already exist as a physical directory path: symlinked target roots or ancestors are
 rejected.
+
+## Validated feedback and delivery
+
+Import `createFeedbackEnvelope`, `validateFeedbackEnvelope`, `writeFeedback`, `verifyFreshFeedback`,
+`composeRetrospective`, `feedbackOutboxStatus`, and `flushFeedbackOutbox` from the existing
+`vouchington-tooling/agent-blackboard` subpath. Consumers must run Node 24 or newer and install `agent-blackboard@^0.6.0` explicitly alongside
+`vouchington-tooling`; the provider is not installed by this package. Missing provider installation
+returns `client-unavailable`; missing or invalid connection configuration returns
+`configuration-invalid`, separately from transport outages and authentication rejection.
+The upstream `agent-blackboard` client still owns the
+service protocol; this integration adds no provider schema or service. Supply consumer module
+context through `dependencies.resolveFrom` or inject the client loader at the transport boundary.
+
+The version-one envelope retains canonical `markdown` and storage `type: journal | retrospective`.
+It requires exact canonical repositories, stable URL-safe `sourceEventId`, ISO timestamp, explicit
+`workOutcome`, and `feedbackCoverage` with status, sources, and dropped count. Optional category is
+context only. Retrospectives retain valid date and integer/string issue/PR references. Markdown is
+capped at 12 KB and the envelope at 16 KB. Known credentials are redacted; authors remain responsible
+for minimizing summaries and excluding raw logs, transcripts, environment dumps, and undisclosed
+secrets. A bound violation fails visibly without clipping findings.
+
+`writeFeedback({identity, envelope, mode, ...})` accepts an exact caller-owned session identity and
+never manufactures native agent identities. Interactive mode requires an absolute private outbox
+directory. The writer persists before transport with atomic rename, file/directory fsync, a stable
+record path, and owner-only permissions. The outbox holds at most 128 records and 2 MB. Saturation,
+corruption, or persistence failure blocks capture and preserves unsent records. Delivered records
+are removed only after matching readback. Pending state includes count and a safe diagnostic;
+interactive CLI exit zero means durable retention, and callers must inspect the printed status to
+know whether delivery was acknowledged. Autonomous errors and unpersisted writes fail nonzero.
+Identity, content, and archived-session conflicts fail in either mode while preserving the unsent
+record; they are not reported as transient pending delivery. Replay retains permanently conflicted
+records and continues to deliver unrelated pending records; transient failures stop that replay.
+Verified delivery retains its receipt when local cleanup fails, returning
+`cleanupDiagnostic` with value `"outbox-cleanup-failed"`. A retained or crash-reappearing record is safe to replay with exact dedup.
+Use `vouchington agent-blackboard journal flush --outbox-directory PATH` to replay unchanged pending
+records after connectivity returns.
+
+Autonomous mode prohibits the filesystem outbox. `verifyFreshFeedback` requires a fresh source-event
+write plus readback of its own append receipt and rejects visible duplicate source records. This
+is fresh online reporting evidence, not a distributed execution lease: eventually consistent
+provider reads cannot establish source uniqueness. Trusted controllers
+supply a unique new authorization-probe source ID, preserve their authoritative run/session
+lineage, and atomically claim and revalidate the attempt before execution. Terminal writes keep work outcome separate from coverage and returned delivery state.
+The delivered result includes a verified receipt with session ID, source-event ID and creation time.
+Controllers require this online result together with atomically established attempt ownership
+before execution.
+
+Delivery is at least once. Replays pre-read matching source identity/content, accept equivalent
+persistent duplicates, and reject conflicting reuse. Equality ignores object property order while
+preserving array order. Each online operation has a 20-second deadline (`timeoutMs` can shorten it);
+readback scans at most 10,000 records or 2 MB. The SDK does not expose cancellation for in-flight
+requests, so a timed-out write can commit later. That never grants admission or a delivery receipt;
+replay the identical envelope and source ID to verify its actual persistence.
+
+`composeRetrospective` invokes the existing fact/transcript collectors with raw output disabled and
+generates required sections and markers. Tool and architectural assessments preserve observation,
+evidence, disposition and tracking reference. None-observed and unassessed states need a scoped
+reason. Complete coverage is rejected when required sources are unavailable or capture is partial.
+Typed collector reports expose availability independently of rendered text. Composition rejects
+aggregate dropped counts below observed friction drops and retains larger caller aggregates without
+double counting. Generated frontmatter carries validated `work_outcome` and `feedback_coverage`
+for consumers to preserve or reject conflicting explicit overrides; trusted mode stays external.
+Human top-five summaries do not authorize dropping additional durable findings.

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

@@ -0,0 +1,34 @@
+export type BlackboardConnection = {
+    baseUrl: string;
+    token: string;
+    readRetry: Record<string, never>;
+};
+export type BlackboardClientModule = {
+    Sessions: new (connection: BlackboardConnection) => {
+        ensure(input: unknown): Promise<{
+            status: 'created' | 'exists';
+            session: {
+                data: Record<string, unknown>;
+                archivedAt?: string | null;
+            };
+        }>;
+        patch(input: unknown): Promise<unknown>;
+        list(input: unknown): Promise<unknown>;
+        get(id: string): Promise<unknown>;
+    };
+    Entries: new (connection: BlackboardConnection) => {
+        append(input: unknown): Promise<{
+            createdAt: string;
+            data: unknown;
+        }>;
+        get(input: unknown): AsyncIterable<unknown>;
+    };
+};
+type BlackboardClientLoader = () => Promise<BlackboardClientModule>;
+export type BlackboardClientDependencies = {
+    loadClient?: BlackboardClientLoader;
+    resolveFrom?: string | URL;
+};
+export declare function resolveBlackboardConnection(env?: NodeJS.ProcessEnv): BlackboardConnection;
+export declare function loadClient(dependencies?: BlackboardClientDependencies): Promise<BlackboardClientModule>;
+export {};

package/dist/agent-blackboard/client.mjs

@@ -0,0 +1,41 @@
+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 { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+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 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'));
+}

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

@@ -0,0 +1 @@
+export declare function canonicalFeedback(value: unknown): string;

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

@@ -0,0 +1,13 @@
+import { isObject } from './snapshot-partition-guards.mjs';
+export function canonicalFeedback(value) {
+    return JSON.stringify(ordered(value));
+}
+function ordered(value) {
+    if (Array.isArray(value))
+        return value.map(ordered);
+    if (!isObject(value))
+        return value;
+    return Object.fromEntries(Object.keys(value)
+        .sort()
+        .map((key) => [key, ordered(value[key])]));
+}

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

@@ -0,0 +1,7 @@
+export { normalizeRepositories } from './feedback-fields.mts';
+import type { FeedbackEnvelope } from './feedback-types.mts';
+export declare function validateFeedbackEnvelope(value: unknown): asserts value is FeedbackEnvelope;
+export declare function redactFeedbackText(value: string, knownSensitiveValues?: string[]): string;
+export declare function createFeedbackEnvelope(input: FeedbackEnvelope, options?: {
+    knownSensitiveValues?: string[];
+}): FeedbackEnvelope;

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

@@ -0,0 +1,121 @@
+import { normalizeRepositories, validateFeedbackText, validateFeedbackReferences, } from './feedback-fields.mjs';
+export { normalizeRepositories } from './feedback-fields.mjs';
+import { isCount, isObject } from './snapshot-partition-guards.mjs';
+const FEEDBACK_MAX_BYTES = 16_384;
+const OUTCOMES = [
+    'in-progress',
+    'success',
+    'failure',
+    'cancelled',
+    'timed-out',
+    'no-change',
+    'policy-refusal',
+    'unknown',
+];
+const COVERAGE = ['complete', 'partial', 'unavailable', 'not-assessed', 'not-started'];
+const FIELDS = [
+    'schemaVersion',
+    'type',
+    'sourceEventId',
+    'timestamp',
+    'repositories',
+    'markdown',
+    'workOutcome',
+    'feedbackCoverage',
+    'category',
+    'date',
+    'issues',
+    'prs',
+];
+export function validateFeedbackEnvelope(value) {
+    if (!isObject(value) ||
+        value.schemaVersion !== 1 ||
+        typeof value.type !== 'string' ||
+        !['journal', 'retrospective'].includes(value.type))
+        throw new Error('invalid feedback storage type or schemaVersion');
+    if (Object.keys(value).some((key) => !FIELDS.includes(key)))
+        throw new Error('unsupported feedback field');
+    validateFeedbackText(value.sourceEventId, 'sourceEventId', 256);
+    if (!/^[A-Za-z0-9._:-]+$/.test(value.sourceEventId))
+        throw new Error('sourceEventId must be URL-safe');
+    validateFeedbackText(value.timestamp, 'timestamp', 40);
+    if (!Number.isFinite(Date.parse(value.timestamp)) ||
+        new Date(value.timestamp).toISOString() !== value.timestamp)
+        throw new Error('timestamp must be a canonical ISO date-time');
+    if (JSON.stringify(value.repositories) !== JSON.stringify(normalizeRepositories(value.repositories)))
+        throw new Error('repositories must be canonical');
+    validateFeedbackText(value.markdown, 'markdown', 12_000);
+    if (typeof value.workOutcome !== 'string' || !OUTCOMES.includes(value.workOutcome))
+        throw new Error('workOutcome must be explicit');
+    if (!isObject(value.feedbackCoverage) ||
+        typeof value.feedbackCoverage.status !== 'string' ||
+        !COVERAGE.includes(value.feedbackCoverage.status) ||
+        !isCount(value.feedbackCoverage.droppedCount))
+        throw new Error('feedbackCoverage must be explicit');
+    if (Object.keys(value.feedbackCoverage).some((key) => !['status', 'sources', 'droppedCount'].includes(key)))
+        throw new Error('unsupported feedbackCoverage field');
+    if (!Array.isArray(value.feedbackCoverage.sources) || value.feedbackCoverage.sources.length > 32)
+        throw new Error('coverage sources must be bounded');
+    for (const source of value.feedbackCoverage.sources)
+        validateFeedbackText(source, 'coverage source', 160);
+    if (value.feedbackCoverage.status === 'complete' && value.feedbackCoverage.droppedCount !== 0)
+        throw new Error('complete coverage cannot have dropped records');
+    if (value.category !== undefined)
+        validateFeedbackText(value.category, 'category', 160);
+    if (value.type === 'retrospective' || value.date !== undefined) {
+        if (typeof value.date !== 'string' ||
+            !/^\d{4}-\d{2}-\d{2}$/.test(value.date) ||
+            !Number.isFinite(Date.parse(value.date)) ||
+            new Date(value.date).toISOString().slice(0, 10) !== value.date)
+            throw new Error('date must be a valid YYYY-MM-DD');
+    }
+    if (value.type === 'retrospective' || value.issues !== undefined)
+        validateFeedbackReferences(value.issues, 'issues');
+    if (value.type === 'retrospective' || value.prs !== undefined)
+        validateFeedbackReferences(value.prs, 'prs');
+    if (Buffer.byteLength(JSON.stringify(value)) > FEEDBACK_MAX_BYTES)
+        throw new Error('feedback envelope is too large');
+}
+export function redactFeedbackText(value, knownSensitiveValues = []) {
+    let result = value;
+    for (const secret of knownSensitiveValues)
+        if (secret.length >= 4)
+            result = result.split(secret).join('[REDACTED]');
+    return result
+        .replace(/\b(?:abb_sk_|gh[pousr]_|github_pat_|sk-(?:proj-)?)?[A-Za-z0-9_-]{30,}\b/g, (match) => /^(?:abb_sk_|gh[pousr]_|github_pat_|sk-)/.test(match) ? '[REDACTED]' : match)
+        .replace(/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, '[REDACTED]')
+        .replace(/(Bearer\s+)[^\s]+/gi, '$1[REDACTED]')
+        .replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+:[^\s/@]+@/gi, '$1[REDACTED]@')
+        .replace(/((?:password|secret|token|api[_-]?key)\s*[=:]\s*)(?:"[^"]*"|'[^']*'|[^\s,;]+)/gi, '$1[REDACTED]');
+}
+export function createFeedbackEnvelope(input, options = {}) {
+    validateFeedbackText(input.markdown, 'markdown', 12_000);
+    validateFeedbackText(input.timestamp, 'timestamp', 40);
+    const envelope = {
+        ...input,
+        repositories: normalizeRepositories(input.repositories),
+        markdown: redactFeedbackText(input.markdown, options.knownSensitiveValues),
+        timestamp: Number.isFinite(Date.parse(input.timestamp))
+            ? new Date(input.timestamp).toISOString()
+            : input.timestamp,
+        feedbackCoverage: {
+            ...input.feedbackCoverage,
+            sources: input.feedbackCoverage.sources.map((source) => redactFeedbackText(source, options.knownSensitiveValues)),
+        },
+        ...(input.category === undefined
+            ? {}
+            : { category: redactFeedbackText(input.category, options.knownSensitiveValues) }),
+        ...(input.issues === undefined
+            ? {}
+            : {
+                issues: input.issues.map((ref) => typeof ref === 'string' ? redactFeedbackText(ref, options.knownSensitiveValues) : ref),
+            }),
+        ...(input.prs === undefined
+            ? {}
+            : {
+                prs: input.prs.map((ref) => typeof ref === 'string' ? redactFeedbackText(ref, options.knownSensitiveValues) : ref),
+            }),
+    };
+    validateFeedbackEnvelope(envelope);
+    return envelope;
+}

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

@@ -0,0 +1,37 @@
+import { type RetrospectiveFactsOptions } from '../retrospective-facts/index.mts';
+import { type ResolveOptions } from '../retrospective-transcript/index.mts';
+import { type SessionFrictionReportOptions } from '../session-friction/index.mts';
+import type { FeedbackCoverage, FeedbackReference, WorkOutcome } from './feedback-types.mts';
+export type FeedbackAssessment = {
+    status: 'findings' | 'none-observed' | 'not-assessed' | 'unavailable';
+    findings?: Array<{
+        observation: string;
+        evidence: string;
+        disposition: string;
+        trackingReference?: string;
+    }>;
+    reason?: string;
+};
+type Unassessed = {
+    status: 'unavailable' | 'not-assessed';
+    reason: string;
+};
+export type RetrospectiveCompositionInput = {
+    sessionId: string;
+    date: string;
+    issues: FeedbackReference[];
+    prs: FeedbackReference[];
+    description: string;
+    repositories: string[];
+    workOutcome: WorkOutcome;
+    feedbackCoverage: FeedbackCoverage;
+    narrative: string;
+    facts: Omit<RetrospectiveFactsOptions, 'raw'> | Unassessed;
+    transcript: ResolveOptions | Unassessed;
+    friction?: SessionFrictionReportOptions;
+    tools: FeedbackAssessment;
+    architecture: FeedbackAssessment;
+    knownSensitiveValues?: string[];
+};
+export declare function composeRetrospective(input: RetrospectiveCompositionInput): Promise<string>;
+export {};

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

@@ -0,0 +1,109 @@
+import { runRetrospectiveFactsReport, } from '../retrospective-facts/index.mjs';
+import { runRetrospectiveTranscriptReport, } from '../retrospective-transcript/index.mjs';
+import { buildSessionFrictionReport, } from '../session-friction/index.mjs';
+import { createFeedbackEnvelope, redactFeedbackText } from './feedback-codec.mjs';
+import { validateFeedbackText } from './feedback-fields.mjs';
+function assessment(title, value) {
+    if (!['findings', 'none-observed', 'not-assessed', 'unavailable'].includes(value.status))
+        throw new Error('assessment status must be explicit');
+    if (value.status !== 'findings' &&
+        (typeof value.reason !== 'string' ||
+            !value.reason.trim() ||
+            Buffer.byteLength(value.reason) > 240))
+        throw new Error('assessment reason and inspected scope must be explicit and bounded');
+    const findings = value.findings ?? [];
+    if (findings.length > 20 || (value.status === 'findings') !== Boolean(findings.length))
+        throw new Error('assessment findings must match status and remain bounded');
+    const lines = findings.map((finding) => {
+        for (const field of [finding.observation, finding.evidence, finding.disposition])
+            if (typeof field !== 'string' || !field.trim() || Buffer.byteLength(field) > 1000)
+                throw new Error('assessment finding must contain bounded observation, evidence and disposition');
+        if (finding.trackingReference !== undefined)
+            validateFeedbackText(finding.trackingReference, 'assessment tracking reference', 240);
+        return `- ${finding.observation}\n  - Evidence: ${finding.evidence}\n  - Disposition: ${finding.disposition}${finding.trackingReference ? `\n  - Tracking: ${finding.trackingReference}` : ''}`;
+    });
+    return `## ${title}\nStatus: ${value.status.replaceAll('-', ' ')}${value.reason ? ` (${value.reason})` : ''}\n${lines.join('\n')}`;
+}
+function unavailable(marker, input) {
+    if (input.status !== 'unavailable' && input.status !== 'not-assessed')
+        throw new Error('unassessed status must be unavailable or not-assessed');
+    if (!input.reason.trim() || Buffer.byteLength(input.reason) > 240)
+        throw new Error('unavailable reason must be bounded and explicit');
+    return `${marker}\nStatus: ${input.status.replaceAll('-', ' ')} (${input.reason})`;
+}
+export async function composeRetrospective(input) {
+    const unavailableFacts = 'status' in input.facts
+        ? {
+            markdown: unavailable('=== Retrospective Facts ===', input.facts),
+            coverage: input.facts.status,
+        }
+        : undefined;
+    const unavailableTranscript = 'status' in input.transcript
+        ? {
+            markdown: unavailable('=== Transcript Facts ===', input.transcript),
+            coverage: input.transcript.status,
+        }
+        : undefined;
+    const [facts, transcript, friction] = await Promise.all([
+        'status' in input.facts
+            ? Promise.resolve(unavailableFacts)
+            : runRetrospectiveFactsReport({ ...input.facts, raw: false }),
+        'status' in input.transcript
+            ? Promise.resolve(unavailableTranscript)
+            : runRetrospectiveTranscriptReport(input.transcript),
+        input.friction
+            ? buildSessionFrictionReport(input.sessionId, input.friction)
+            : Promise.resolve({
+                coverage: {
+                    journalStatus: 'unavailable',
+                    frictionStatus: 'absent',
+                    truncated: false,
+                },
+                markdown: '## CI Failures\nStatus: unavailable (not assessed)\n\n## Sandbox & Permission Audit\nStatus: unavailable (not assessed)',
+            }),
+    ]);
+    if (input.feedbackCoverage.status === 'complete' &&
+        (facts.coverage !== 'complete' ||
+            transcript.coverage !== 'complete' ||
+            ['not-assessed', 'unavailable'].includes(input.tools.status) ||
+            ['not-assessed', 'unavailable'].includes(input.architecture.status) ||
+            friction.coverage.journalStatus !== 'complete' ||
+            !['empty', 'events'].includes(friction.coverage.frictionStatus) ||
+            friction.coverage.truncated))
+        throw new Error('complete feedback coverage requires assessed available factual and finding sources');
+    if ((friction.coverage.droppedCount ?? 0) > input.feedbackCoverage.droppedCount)
+        throw new Error('feedback coverage dropped count must include observed friction drops');
+    const markdown = [
+        '---',
+        `date: ${JSON.stringify(input.date)}`,
+        `issues: ${JSON.stringify(input.issues)}`,
+        `prs: ${JSON.stringify(input.prs)}`,
+        `session_id: ${JSON.stringify(input.sessionId)}`,
+        `description: ${JSON.stringify(input.description)}`,
+        `work_outcome: ${JSON.stringify(input.workOutcome)}`,
+        `feedback_coverage: ${JSON.stringify(input.feedbackCoverage)}`,
+        '---',
+        '',
+        input.narrative,
+        `## Outcome\nWork outcome: ${input.workOutcome}\nFeedback coverage: ${input.feedbackCoverage.status}\nDropped records: ${input.feedbackCoverage.droppedCount}`,
+        `## Verifiable Facts\n${facts.markdown.trim()}`,
+        `## Transcript Facts\n${transcript.markdown.trim()}`,
+        friction.markdown,
+        assessment('Tool Findings', input.tools),
+        assessment('Architecture Findings', input.architecture),
+    ].join('\n\n');
+    const envelope = createFeedbackEnvelope({
+        schemaVersion: 1,
+        type: 'retrospective',
+        sourceEventId: 'composition-validation',
+        timestamp: `${input.date}T00:00:00.000Z`,
+        date: input.date,
+        issues: input.issues,
+        prs: input.prs,
+        repositories: input.repositories,
+        markdown: redactFeedbackText(markdown, input.knownSensitiveValues),
+        workOutcome: input.workOutcome,
+        feedbackCoverage: input.feedbackCoverage,
+    });
+    return envelope.markdown;
+}

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

@@ -0,0 +1 @@
+export declare function feedbackDeadline<T>(operation: () => Promise<T>, timeoutMs?: number): Promise<T>;

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

@@ -0,0 +1,18 @@
+import { FeedbackDeliveryError } from './feedback-online-error.mjs';
+export async function feedbackDeadline(operation, timeoutMs = 20_000) {
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 20_000)
+        throw new Error('feedback timeoutMs must be between 1 and 20000');
+    let timer;
+    try {
+        return await Promise.race([
+            operation(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new FeedbackDeliveryError('delivery-timeout')), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

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

@@ -0,0 +1,18 @@
+import type { BlackboardClientDependencies } from './client.mts';
+import type { FeedbackDeliveryOptions, FeedbackDeliveryResult, FeedbackDiagnostic, FeedbackOnlineOptions } from './feedback-types.mts';
+export { FeedbackDeliveryError } from './feedback-online-error.mts';
+export declare function writeFeedback(input: FeedbackDeliveryOptions): Promise<FeedbackDeliveryResult>;
+export declare function verifyFreshFeedback(input: FeedbackOnlineOptions): Promise<Extract<FeedbackDeliveryResult, {
+    status: 'delivered';
+}>>;
+export declare function flushFeedbackOutbox(input: {
+    directory: string;
+    env?: NodeJS.ProcessEnv;
+    dependencies?: BlackboardClientDependencies;
+}): Promise<{
+    status: 'empty' | 'pending';
+    pendingCount: number;
+    deliveredCount: number;
+    diagnostic?: FeedbackDiagnostic;
+    cleanupDiagnostic?: 'outbox-cleanup-failed';
+}>;

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

@@ -0,0 +1,88 @@
+import { createFeedbackEnvelope, validateFeedbackEnvelope } from './feedback-codec.mjs';
+import { validateFeedbackIdentity } from './feedback-identity.mjs';
+import { deliverFeedbackOnline } from './feedback-online.mjs';
+import { FeedbackDeliveryError, feedbackDiagnostic } from './feedback-online-error.mjs';
+import { feedbackOutboxStatus, listFeedbackOutbox, persistFeedbackOutbox, removeFeedbackOutbox, } from './feedback-outbox.mjs';
+export { FeedbackDeliveryError } from './feedback-online-error.mjs';
+export async function writeFeedback(input) {
+    if (input.mode !== 'interactive' && input.mode !== 'autonomous')
+        throw new Error('feedback mode must be explicitly interactive or autonomous');
+    validateFeedbackIdentity(input.identity);
+    validateFeedbackEnvelope(input.envelope);
+    const envelope = prepareEnvelope(input);
+    if (input.mode === 'autonomous') {
+        if (input.outboxDirectory !== undefined)
+            throw new Error('autonomous feedback cannot use a filesystem outbox');
+        const receipt = await deliverFeedbackOnline({ ...input, envelope });
+        return { status: 'delivered', sourceEventId: envelope.sourceEventId, pendingCount: 0, receipt };
+    }
+    if (!input.outboxDirectory)
+        throw new Error('interactive feedback requires an explicit durable outbox directory');
+    persistFeedbackOutbox(input.outboxDirectory, { identity: input.identity, envelope });
+    try {
+        const receipt = await deliverFeedbackOnline({ ...input, envelope });
+        const cleanup = removeFeedbackOutbox(input.outboxDirectory, {
+            identity: input.identity,
+            envelope,
+        });
+        return { status: 'delivered', sourceEventId: envelope.sourceEventId, ...cleanup, receipt };
+    }
+    catch (error) {
+        const diagnostic = feedbackDiagnostic(error);
+        if (['identity-conflict', 'event-conflict', 'archived-session'].includes(diagnostic))
+            throw new FeedbackDeliveryError(diagnostic);
+        return {
+            status: 'pending',
+            sourceEventId: envelope.sourceEventId,
+            pendingCount: feedbackOutboxStatus(input.outboxDirectory).pendingCount,
+            diagnostic,
+        };
+    }
+}
+export async function verifyFreshFeedback(input) {
+    const envelope = prepareEnvelope(input);
+    const receipt = await deliverFeedbackOnline({ ...input, envelope }, true);
+    return { status: 'delivered', sourceEventId: envelope.sourceEventId, pendingCount: 0, receipt };
+}
+export async function flushFeedbackOutbox(input) {
+    let deliveredCount = 0;
+    let diagnostic;
+    let cleanupDiagnostic;
+    for (const record of listFeedbackOutbox(input.directory)) {
+        try {
+            await deliverFeedbackOnline({
+                ...record,
+                ...(input.env === undefined ? {} : { env: input.env }),
+                ...(input.dependencies === undefined ? {} : { dependencies: input.dependencies }),
+            });
+            const cleanup = removeFeedbackOutbox(input.directory, record);
+            cleanupDiagnostic ??= cleanup.cleanupDiagnostic;
+            deliveredCount++;
+        }
+        catch (error) {
+            const current = feedbackDiagnostic(error);
+            diagnostic ??= current;
+            if (['identity-conflict', 'event-conflict', 'archived-session'].includes(current))
+                continue;
+            diagnostic = current;
+            break;
+        }
+    }
+    return {
+        ...feedbackOutboxStatus(input.directory),
+        deliveredCount,
+        ...(cleanupDiagnostic === undefined ? {} : { cleanupDiagnostic }),
+        ...(diagnostic === undefined ? {} : { diagnostic }),
+    };
+}
+function prepareEnvelope(input) {
+    const token = (input.env ?? process.env).AGENT_BLACKBOARD_TOKEN;
+    const envelope = createFeedbackEnvelope(input.envelope, {
+        knownSensitiveValues: token ? [token] : [],
+    });
+    if (token &&
+        token.length >= 4 &&
+        JSON.stringify({ identity: input.identity, envelope }).includes(token))
+        throw new Error('feedback identity contains a configured sensitive value');
+    return envelope;
+}

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

@@ -0,0 +1,4 @@
+import type { FeedbackReference } from './feedback-types.mts';
+export declare function validateFeedbackText(value: unknown, label: string, maximum: number): asserts value is string;
+export declare function normalizeRepositories(value: unknown, required?: boolean): string[];
+export declare function validateFeedbackReferences(value: unknown, label: string): asserts value is FeedbackReference[];