vouchington-tooling 0.29.0 → 0.31.0

package/dist/api-contract-discovery/registered-route-terminal-error.mjs

@@ -0,0 +1,98 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { runtimeParameters } from './registered-route-runtime-parameters.mjs';
+import { handlerNodes } from './registered-route-handler-analysis.mjs';
+/** Proves a terminal 405 on the handler's own context, rather than finding a nested throw. */
+export function isTerminal405Handler(node, checker, bindings = new Map()) {
+    if (!(ts.isArrowFunction(node) ||
+        ts.isFunctionExpression(node) ||
+        ts.isFunctionDeclaration(node) ||
+        ts.isMethodDeclaration(node)) ||
+        !node.body)
+        return false;
+    const context = runtimeParameters(node)[0]?.name;
+    const symbol = context && ts.isIdentifier(context) ? checker.getSymbolAtLocation(context) : undefined;
+    return !!symbol && terminalBody(node, symbol, checker, new Set(), true, bindings);
+}
+function terminalBody(node, context, checker, active, returned = true, bindings = new Map()) {
+    if (!node.body || node.asteriskToken || active.has(node))
+        return false;
+    if (node.parameters.some((parameter) => !ts.isIdentifier(parameter.name) ||
+        parameter.dotDotDotToken ||
+        (parameter.initializer && !ts.isLiteralExpression(parameter.initializer))))
+        return false;
+    const next = new Set(active).add(node);
+    if (!ts.isBlock(node.body))
+        return terminalCall(node.body, context, checker, next, returned, bindings);
+    const statements = node.body.statements;
+    const terminal = statements.at(-1);
+    if (!terminal ||
+        !statements.slice(0, -1).every((statement) => isInertStatement(statement, context, checker)))
+        return false;
+    if (ts.isExpressionStatement(terminal))
+        return terminalCall(terminal.expression, context, checker, next, false, bindings);
+    return (ts.isReturnStatement(terminal) &&
+        !!terminal.expression &&
+        terminalCall(terminal.expression, context, checker, next, returned, bindings));
+}
+function terminalCall(expression, context, checker, active, returned, bindings) {
+    if (ts.isAwaitExpression(expression))
+        return terminalCall(expression.expression, context, checker, active, true, bindings);
+    if (ts.isParenthesizedExpression(expression))
+        return terminalCall(expression.expression, context, checker, active, returned, bindings);
+    if (!ts.isCallExpression(expression) || expression.questionDotToken)
+        return false;
+    if (expression.arguments.some((argument) => !ts.isIdentifier(argument) && !ts.isLiteralExpression(argument)))
+        return false;
+    const callee = expression.expression;
+    if (ts.isPropertyAccessExpression(callee) && callee.name.text === 'throw') {
+        const status = expression.arguments[0];
+        return (!callee.questionDotToken &&
+            ts.isIdentifier(callee.expression) &&
+            checker.getSymbolAtLocation(callee.expression) === context &&
+            !!status &&
+            ts.isNumericLiteral(status) &&
+            Number(status.text) === 405);
+    }
+    if (!ts.isIdentifier(callee))
+        return false;
+    const implementations = [];
+    handlerNodes(callee, checker, bindings, new Set(), true, implementations);
+    if (!returned && checker.getPropertyOfType(checker.getTypeAtLocation(expression), 'then'))
+        return false;
+    return (implementations.length > 0 &&
+        implementations.every(({ node: implementation, bindings: captured }) => {
+            if (!returned &&
+                implementation.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword))
+                return false;
+            const index = expression.arguments.findIndex((argument) => ts.isIdentifier(argument) && checker.getSymbolAtLocation(argument) === context);
+            const parameter = runtimeParameters(implementation)[index]?.name;
+            const symbol = parameter && ts.isIdentifier(parameter) ? checker.getSymbolAtLocation(parameter) : undefined;
+            return !!symbol && terminalBody(implementation, symbol, checker, active, returned, captured);
+        }));
+}
+function isInertStatement(statement, context, checker) {
+    if (ts.isEmptyStatement(statement))
+        return true;
+    if (ts.isExpressionStatement(statement)) {
+        const expression = statement.expression;
+        if (ts.isStringLiteral(expression))
+            return true;
+        if (!ts.isCallExpression(expression) || expression.arguments.length !== 2)
+            return false;
+        const callee = expression.expression;
+        const [header, value] = expression.arguments;
+        return (ts.isPropertyAccessExpression(callee) &&
+            callee.name.text === 'set' &&
+            ts.isIdentifier(callee.expression) &&
+            checker.getSymbolAtLocation(callee.expression) === context &&
+            ts.isStringLiteral(header) &&
+            header.text.toLowerCase() === 'allow' &&
+            ts.isStringLiteral(value) &&
+            /^[A-Z]+(?:, *[A-Z]+)*$/.test(value.text));
+    }
+    if (!ts.isVariableStatement(statement))
+        return false;
+    return statement.declarationList.declarations.every((declaration) => ts.isIdentifier(declaration.name) &&
+        checker.getSymbolAtLocation(declaration.name) !== context &&
+        (!declaration.initializer || ts.isLiteralExpression(declaration.initializer)));
+}

package/dist/api-contract-discovery/request-contract-registry.mjs

@@ -1,4 +1,5 @@
 import ts from '../contract-schema/typescript-api.mjs';
+import { registerPlatformCompilerLibraries } from './protocol-platform-callbacks.mjs';
 import { extractContractSchema } from '../contract-schema/index.mjs';
 import { registerRequestRouteContract, } from './request-contract-lenient.mjs';
 import { discoverImplicitRequestContract } from './request-contract-implicit.mjs';
@@ -14,6 +15,7 @@ import { collectHandlerBindings, enclosingRouteBinding, visit, } from './respons
  * `apiNoRequestBody` suppression) so Phase 2 knows to never harvest over it.
  */
 export function discoverApiRequestContracts(program, sourceFiles, requestedKeys, options) {
+    registerPlatformCompilerLibraries(program);
     const checker = program.getTypeChecker();
     const contracts = new Map();
     const markerKeys = new Set();

package/dist/api-contract-discovery/response-contract-implicit.mjs

@@ -6,11 +6,34 @@ import { isXmlResponseCall, streamingTextMediaType } from './response-contract-m
 import { markBufferedRouteUnavailable, registerRouteContract, } from './response-contract-lenient.mjs';
 import { enclosingRouteBinding, isContextMethod, isContextResponseBufferCall, isContextResponseEmptyCall, requestedKeyForBinding, responseMarker, } from './response-contract-route-analysis.mjs';
 import { resolveEmissionStatus } from './response-contract-status.mjs';
+import { opaqueHttpResponse, unsupportedContextResponse, supportedResponseContext, } from './protocol-http-association.mjs';
+import { contextResponseMethod } from './protocol-http-context.mjs';
+import { taintRouteKeys, markRouteTaint, isSseSetter } from './protocol-http-implicit-taint.mjs';
 export function discoverImplicitContract(call, checker, sourceFile, contracts, handlerBindings, requestedKeys, options) {
-    const binding = enclosingRouteBinding(call, checker, handlerBindings);
+    const opaqueResponse = opaqueHttpResponse(call, checker);
+    const binding = enclosingRouteBinding(call, checker, handlerBindings, !opaqueResponse);
     if (!binding)
         return;
     const key = requestedKeyForBinding(binding, requestedKeys);
+    const taintKeys = taintRouteKeys(contracts, binding, key);
+    if (!taintKeys.length)
+        return;
+    const context = supportedResponseContext(call, checker);
+    const bracketResponse = context &&
+        (ts.isElementAccessExpression(call.expression) ||
+            (ts.isPropertyAccessExpression(call.expression) &&
+                ts.isElementAccessExpression(call.expression.expression))) &&
+        contextResponseMethod(call.expression, context, checker);
+    const mutableResponse = unsupportedContextResponse(call, checker);
+    const sseSetter = isSseSetter(contracts, binding, bracketResponse || undefined);
+    if (opaqueResponse ||
+        mutableResponse ||
+        (bracketResponse && !sseSetter && !containsResponseMarker(call))) {
+        markRouteTaint(contracts, taintKeys, binding, sourceLocation(sourceFile, call), !!mutableResponse &&
+            !!context &&
+            !!contextResponseMethod(call.expression, context, checker, true));
+        return;
+    }
     if (!key)
         return;
     const body = responseBodyExpression(call);
@@ -30,17 +53,13 @@ export function discoverImplicitContract(call, checker, sourceFile, contracts, h
             mediaTypeKnowledge: 'known',
             ...status,
         };
-        // Primary body (bare key, or requested key in subset mode) uses the lenient path, so a
-        // genuine single-variant route still reports a real `unavailableReason` on failure.
+        // Keep primary extraction failures unavailable in both full and subset discovery.
         if (requestedKeys || !contracts.has(key)) {
             registerRouteContract(contracts, key, binding, location, emission, extract, options);
             return;
         }
-        // Full-scope discovery: a route can emit more than one distinct unmarked success body across
-        // branches (e.g. a webhook's `{received}` vs `{ignored}`); register each under its own key —
-        // `groupContractsByRoute` merges by method/routeTemplate, not this key. This route already has
-        // a primary contract, so retain this one under a deterministic variant key. A failed secondary
-        // extraction is registered as unavailable so the operation never silently omits a real branch.
+        // Preserve every additional unmarked body under a deterministic variant key, including
+        // unavailable secondary extractions. Route grouping merges these without hiding a branch.
         registerRouteContract(contracts, nextImplicitVariantKey(contracts, key), binding, location, emission, extract, options);
         return;
     }
@@ -72,8 +91,7 @@ export function discoverImplicitContract(call, checker, sourceFile, contracts, h
         }, () => extractContractSchema(checker.getStringType(), checker, location, options), options);
         return;
     }
-    // Empty and raw branches can coexist; AST order must not let empty hide an unmarked raw body,
-    // so every buffer or pipeline without an explicit response marker makes the route unavailable.
+    // Empty branches must not hide any unmarked buffer or pipeline body.
     if (isContextResponseBufferCall(call.expression) ||
         (isContextMethod(call.expression, 'pipeline') && !body && !containsResponseMarker(call))) {
         markBufferedRouteUnavailable(contracts, key, binding, sourceLocation(sourceFile, call));

package/dist/api-contract-discovery/response-contract-registry.mjs

@@ -1,13 +1,24 @@
 import ts from '../contract-schema/typescript-api.mjs';
+import { registerPlatformCompilerLibraries } from './protocol-platform-callbacks.mjs';
+import { requestedProtocolKey } from './protocol-requested-keys.mjs';
+import { discoverProtocolContracts } from './protocol-contract-registry.mjs';
 import { discoverImplicitContract } from './response-contract-implicit.mjs';
 import { registerRouteContract, } from './response-contract-lenient.mjs';
 import { binaryContentContract, contractError, extractBodyContract, noContentContract, sourceLocation, } from './response-contract-registration.mjs';
 import { collectHandlerBindings, enclosingRouteBinding, isContextMethod, responseMarker, visit, } from './response-contract-route-analysis.mjs';
 import { resolveEmissionStatus } from './response-contract-status.mjs';
 export function discoverApiResponseContracts(program, sourceFiles, requestedKeys, options) {
+    registerPlatformCompilerLibraries(program);
     const checker = program.getTypeChecker();
     const contracts = new Map();
     const handlerBindings = collectHandlerBindings(sourceFiles, checker);
+    const protocolContracts = new Map();
+    const protocolEmissions = discoverProtocolContracts(sourceFiles, checker, handlerBindings, protocolContracts, options, requestedKeys);
+    for (const [key, contract] of protocolContracts) {
+        const requestedKey = requestedProtocolKey(key, contract, requestedKeys);
+        if (requestedKey)
+            contracts.set(requestedKey, contract);
+    }
     for (const sourceFile of sourceFiles) {
         visit(sourceFile, (node) => {
             if (!ts.isCallExpression(node))
@@ -47,7 +58,9 @@ export function discoverApiResponseContracts(program, sourceFiles, requestedKeys
     }
     for (const sourceFile of sourceFiles) {
         visit(sourceFile, (node) => {
-            if (!ts.isCallExpression(node) || responseMarker(node.expression))
+            if (!ts.isCallExpression(node) ||
+                responseMarker(node.expression) ||
+                protocolEmissions.has(node))
                 return;
             discoverImplicitContract(node, checker, sourceFile, contracts, handlerBindings, requestedKeys, options);
         });

package/dist/api-contract-discovery/response-contract-route-analysis.d.mts

@@ -6,7 +6,7 @@ export type RouteBinding = {
 };
 export type HandlerBindings = Map<ts.Symbol, RouteBinding>;
 export declare function requestedKeyForBinding(binding: RouteBinding, requestedKeys?: ReadonlySet<string>): string | undefined;
-export declare function enclosingRouteBinding(node: ts.Node, checker: ts.TypeChecker, handlerBindings: HandlerBindings): RouteBinding | undefined;
+export declare function enclosingRouteBinding(node: ts.Node, checker: ts.TypeChecker, handlerBindings: HandlerBindings, proveCallbacks?: boolean): RouteBinding | undefined;
 export declare function collectHandlerBindings(sourceFiles: readonly ts.SourceFile[], checker: ts.TypeChecker): HandlerBindings;
 export declare function routeTemplateFromExpression(expression: ts.Expression): string | undefined;
 export declare function propertyName(expression: ts.Expression): string | undefined;

package/dist/api-contract-discovery/response-contract-route-analysis.mjs

@@ -1,4 +1,5 @@
 import ts from '../contract-schema/typescript-api.mjs';
+import { executableProtocolPath } from './protocol-execution-path.mjs';
 export { isContextMethod, isContextResponseBufferCall, isContextResponseEmptyCall, responseMarker, } from './response-contract-ctx-analysis.mjs';
 const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
 export function requestedKeyForBinding(binding, requestedKeys) {
@@ -19,23 +20,38 @@ export function requestedKeyForBinding(binding, requestedKeys) {
 function routeShape(routeTemplate) {
     return routeTemplate.replace(/:[^/]+/g, ':');
 }
-export function enclosingRouteBinding(node, checker, handlerBindings) {
+export function enclosingRouteBinding(node, checker, handlerBindings, proveCallbacks = true) {
     let current = node;
+    let insideHandlerFunction = false;
     while (current) {
+        if (ts.isFunctionLike(current))
+            insideHandlerFunction = true;
+        if (insideHandlerFunction && ts.isCallExpression(current)) {
+            const method = propertyName(current.expression)?.toUpperCase();
+            const routeTemplate = routeTemplateFromExpression(current.expression);
+            if (method && HTTP_METHODS.has(method) && routeTemplate)
+                return !proveCallbacks || executableProtocolPath(node, checker)
+                    ? { method, routeTemplate }
+                    : undefined;
+        }
         if (isFunctionLike(current) && ts.isCallExpression(current.parent)) {
             const handlerCall = current.parent;
             const method = propertyName(handlerCall.expression)?.toUpperCase();
             if (method && HTTP_METHODS.has(method)) {
                 const routeTemplate = routeTemplateFromExpression(handlerCall.expression);
                 if (routeTemplate)
-                    return { method, routeTemplate };
+                    return !proveCallbacks || executableProtocolPath(node, checker)
+                        ? { method, routeTemplate }
+                        : undefined;
             }
         }
         const handlerSymbol = functionSymbol(current, checker);
         if (handlerSymbol) {
             const binding = handlerBindings.get(resolveSymbol(handlerSymbol, checker));
             if (binding)
-                return binding;
+                return !proveCallbacks || executableProtocolPath(node, checker, current)
+                    ? binding
+                    : undefined;
         }
         current = current.parent;
     }
@@ -93,7 +109,9 @@ function handlerArgumentSymbols(node, checker) {
         }
         if (isFunctionLike(argument)) {
             visit(argument, (child) => {
-                if (!ts.isCallExpression(child) || !ts.isIdentifier(child.expression))
+                if (!ts.isCallExpression(child) ||
+                    !ts.isIdentifier(child.expression) ||
+                    !executableProtocolPath(child, checker))
                     return;
                 const symbol = checker.getSymbolAtLocation(child.expression);
                 if (symbol)

package/dist/api-contract-discovery/response-contract-status.d.mts

@@ -20,7 +20,7 @@ export declare function responseStatusCodesForContract(contract: BackendResponse
  * and the route-wide map (keyed only on `method:routeTemplate`) can't tell two markers in the
  * same route apart when they're preceded by different statuses.
  */
-export declare function resolveEmissionStatus(call: ts.CallExpression): {
+export declare function resolveEmissionStatus(call: ts.CallExpression | ts.NewExpression, matchesContext?: (expression: ts.Expression) => boolean): {
     statusCodes?: readonly [number, ...number[]];
     statusKnowledge: 'default' | 'explicit' | 'unknown';
     unavailableReason?: string;

package/dist/api-contract-discovery/response-contract-status.mjs

@@ -27,32 +27,34 @@ export function responseStatusCodesForContract(contract) {
  * and the route-wide map (keyed only on `method:routeTemplate`) can't tell two markers in the
  * same route apart when they're preceded by different statuses.
  */
-export function resolveEmissionStatus(call) {
-    if (isContextMethod(call.expression, 'setStatus'))
+export function resolveEmissionStatus(call, matchesContext = (expression) => isContextMethod(expression, 'setStatus')) {
+    if (ts.isCallExpression(call) && matchesContext(call.expression))
         return statusArgument(call.arguments[0]);
     let statement = call;
     while (!ts.isStatement(statement))
         statement = statement.parent;
-    return precedingStatus(statement);
+    return precedingStatus(statement, matchesContext);
 }
-function precedingStatus(statement) {
+function precedingStatus(statement, matchesContext) {
     const block = statement.parent;
     if (!ts.isBlock(block))
         return { statusKnowledge: 'default' };
     const index = block.statements.indexOf(statement);
     for (let i = index - 1; i >= 0; i--) {
-        const status = statusStatement(block.statements[i]);
+        const status = statusStatement(block.statements[i], matchesContext);
         if (status)
             return status;
     }
     const enclosing = block.parent;
-    return ts.isStatement(enclosing) ? precedingStatus(enclosing) : { statusKnowledge: 'default' };
+    return ts.isStatement(enclosing)
+        ? precedingStatus(enclosing, matchesContext)
+        : { statusKnowledge: 'default' };
 }
-function statusStatement(statement) {
+function statusStatement(statement, matchesContext) {
     if (!ts.isExpressionStatement(statement))
         return undefined;
     const expression = statement.expression;
-    if (!ts.isCallExpression(expression) || !isContextMethod(expression.expression, 'setStatus'))
+    if (!ts.isCallExpression(expression) || !matchesContext(expression.expression))
         return undefined;
     return statusArgument(expression.arguments[0]);
 }

package/dist/api-contract-discovery/response-contract-types.d.mts

@@ -11,6 +11,13 @@ export type BackendResponseContract = ExtractedResponseContract & {
     mediaType?: string;
     /** Raw buffers and arbitrary streams have an unknown media type; bodyless emissions have none. */
     mediaTypeKnowledge?: 'known' | 'none' | 'unknown';
+    /** Named SSE frames carried by the string stream body. */
+    sseEvents?: readonly {
+        eventName: string;
+        contract: ExtractedResponseContract;
+    }[];
+    /** A concrete error status can also be produced by the framework before dispatch. */
+    includeDefaultError?: boolean;
     /** Set when the route's response schema could not be extracted (lenient discovery mode). */
     unavailableReason?: string;
 };

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

@@ -0,0 +1,4 @@
+export declare function flagsToValues(flags: string[]): Record<string, string>;
+export declare function assertAllowed(values: Record<string, string>, allowed: string[]): void;
+export declare function required(values: Record<string, string>, key: string): string;
+export declare function validatedSessionId(sessionId: string | undefined): string | undefined;

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

@@ -0,0 +1,34 @@
+import { assertSessionId } from '../../agent-blackboard/session-id.mjs';
+export function flagsToValues(flags) {
+    const values = {};
+    for (let index = 0; index < flags.length; index += 2) {
+        const flag = flags[index];
+        const value = flags[index + 1];
+        if (!flag?.startsWith('--') || value === undefined)
+            throw new Error(`invalid option: ${flag ?? ''}`);
+        const key = flag.slice(2);
+        if (key in values)
+            throw new Error(`duplicate option: ${flag}`);
+        values[key] = value;
+    }
+    return values;
+}
+export function assertAllowed(values, allowed) {
+    for (const key of Object.keys(values))
+        if (!allowed.includes(key))
+            throw new Error(`unknown option: --${key}`);
+}
+export function required(values, key) {
+    const value = values[key];
+    if (!value)
+        throw new Error(`--${key} is required`);
+    return value;
+}
+export function validatedSessionId(sessionId) {
+    if (sessionId !== undefined) {
+        assertSessionId(sessionId);
+        if (sessionId.length > 256)
+            throw new Error('session identity is too long');
+    }
+    return sessionId;
+}

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

@@ -1,5 +1,7 @@
-import { appendJournal, flushFeedbackOutbox, formatJournalEntries, probeBlackboard, readJournal, } from '../../agent-blackboard/index.mjs';
+import { assertAllowed, flagsToValues, required, validatedSessionId, } from './agent-blackboard-flags.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) {
     journalReader = reader ?? readJournal;
@@ -8,14 +10,14 @@ export async function runAgentBlackboardCommand(args) {
     try {
         const [command, ...rest] = args;
         if (command === 'probe' && rest.length === 0) {
-            await probeBlackboard();
+            await probeBlackboard(undefined, dependencies);
             return 0;
         }
         if (command === 'journal')
             return await runJournal(rest);
         if (command === 'snapshot')
             return await runSnapshot(rest);
-        throw new Error('usage: agent-blackboard probe | journal append|entries|flush | snapshot partition|cleanup');
+        throw new Error('usage: agent-blackboard probe | journal append|entries|flush|status | snapshot partition|cleanup');
     }
     catch (error) {
         process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
@@ -53,10 +55,20 @@ 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`);
+    if (action === 'flush' || action === 'status') {
+        assertAllowed(values, ['outbox-directory', 'session-id']);
+        const directory = required(values, 'outbox-directory');
+        const sessionId = validatedSessionId(action === 'status' ? required(values, 'session-id') : values['session-id']);
+        const result = action === 'flush'
+            ? await flushFeedbackOutbox({ directory, dependencies })
+            : { pendingCount: 0 };
+        const counts = sessionId !== undefined ? feedbackOutboxCounts(directory, sessionId) : result;
+        process.stdout.write(`${JSON.stringify({
+            ...result,
+            ...counts,
+            sessionId,
+            status: counts.pendingCount ? 'pending' : 'empty',
+        })}\n`);
         return 0;
     }
     if (action === 'entries') {
@@ -64,7 +76,7 @@ async function runJournal(args) {
         const sessionId = required(values, 'session-id');
         let entries;
         try {
-            entries = await journalReader(sessionId);
+            entries = await journalReader(sessionId, undefined, dependencies);
         }
         catch (error) {
             if (!isNotFound(error))
@@ -91,6 +103,7 @@ async function runJournal(args) {
             'outbox-directory',
         ]);
         const result = await appendJournal({
+            dependencies,
             mode: required(values, 'mode'),
             sourceEventId: required(values, 'source-event-id'),
             workOutcome: required(values, 'work-outcome'),
@@ -108,10 +121,14 @@ async function runJournal(args) {
             ...('timestamp' in values ? { timestamp: values.timestamp } : {}),
             parentSessionId: values['parent-session-id'] ?? null,
         });
-        process.stdout.write(`${JSON.stringify(result)}\n`);
+        // Autonomous mode has no outbox, so its receipt must not depend on one.
+        const counts = values.mode === 'autonomous'
+            ? { pendingCount: 0, worktreePendingCount: 0 }
+            : feedbackOutboxCounts(required(values, 'outbox-directory'), required(values, 'session-id'));
+        process.stdout.write(`${JSON.stringify({ ...result, ...counts })}\n`);
         return 0;
     }
-    throw new Error('usage: agent-blackboard journal append|entries|flush');
+    throw new Error('usage: agent-blackboard journal append|entries|flush|status');
 }
 function extractRepositories(flags) {
     const repositories = [];
@@ -133,31 +150,6 @@ function requiredRepositories(repositories) {
         throw new Error('--repository is required');
     return repositories;
 }
-function flagsToValues(flags) {
-    const values = {};
-    for (let index = 0; index < flags.length; index += 2) {
-        const flag = flags[index];
-        const value = flags[index + 1];
-        if (!flag?.startsWith('--') || value === undefined)
-            throw new Error(`invalid option: ${flag ?? ''}`);
-        const key = flag.slice(2);
-        if (key in values)
-            throw new Error(`duplicate option: ${flag}`);
-        values[key] = value;
-    }
-    return values;
-}
-function assertAllowed(values, allowed) {
-    for (const key of Object.keys(values))
-        if (!allowed.includes(key))
-            throw new Error(`unknown option: --${key}`);
-}
-function required(values, key) {
-    const value = values[key];
-    if (!value)
-        throw new Error(`--${key} is required`);
-    return value;
-}
 function isNotFound(error) {
     return (typeof error === 'object' &&
         error !== null &&

package/dist/cli/index.d.mts

@@ -1,3 +1,5 @@
 #!/usr/bin/env node
 export declare function runCli(argv?: readonly string[]): number | Promise<number>;
 export declare function isMainModule(metaUrl: string, argv1: string | undefined): boolean;
+/** Runs the CLI and records its exit code. `bin/vouchington.mjs` calls this after its Node check. */
+export declare function runMain(argv?: readonly string[], run?: typeof runCli): Promise<void>;

package/dist/cli/index.mjs

@@ -2,7 +2,6 @@
 import { realpathSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { runAgentHarnessConfigCli } from '../agent-harness-config/cli.mjs';
 import { runPostReviewCli } from '../gha-post-review/cli.mjs';
 import { runStageReviewPayloadCli } from '../gha-review-payload/cli.mjs';
 import { runSwiftSemanticEqualCli } from '../swift-semantic-equal/cli.mjs';
@@ -98,8 +97,6 @@ export function runCli(argv = process.argv) {
             return runRunnerPortPolicy(parsed);
         case 'with-host-lock':
             return runWithHostLock(parsed.args);
-        case 'agent-harness-config':
-            return runAgentHarnessConfigCli(parsed.args);
         case 'gha-runtime-audit':
             return runGhaRuntimeAudit(parsed);
         case 'script': {
@@ -162,17 +159,17 @@ export function isMainModule(metaUrl, argv1) {
         return metaUrl === pathToFileURL(resolve(argv1)).href;
     }
 }
-/* v8 ignore next 8 */
-if (isMainModule(import.meta.url, process.argv[1])) {
-    const result = runCli();
-    if (typeof result === 'number')
-        process.exitCode = result;
-    else {
-        result.then((code) => {
-            process.exitCode = code;
-        }, (error) => {
-            process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
-            process.exitCode = 1;
-        });
+/** Runs the CLI and records its exit code. `bin/vouchington.mjs` calls this after its Node check. */
+export async function runMain(argv = process.argv, run = runCli) {
+    try {
+        process.exitCode = await run(argv);
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
     }
 }
+/* v8 ignore next 3 */
+if (isMainModule(import.meta.url, process.argv[1])) {
+    void runMain();
+}

package/dist/cli/parse-forwarded-commands.d.mts

@@ -1,9 +1,6 @@
 type ForwardedCommand = {
     kind: 'with-host-lock';
     args: string[];
-} | {
-    kind: 'agent-harness-config';
-    args: string[];
 } | {
     kind: 'pnpm-install';
     args: string[];

package/dist/cli/parse-forwarded-commands.mjs

@@ -1,8 +1,6 @@
 export function parseForwardedCommand(command, args) {
     if (command === 'with-host-lock')
         return { kind: 'with-host-lock', args };
-    if (command === 'agent-harness-config')
-        return { kind: 'agent-harness-config', args };
     if (command === 'pnpm-install')
         return { kind: 'pnpm-install', args };
     if (command === 'vitest-blob-manifest')

package/dist/cli/parse.d.mts

@@ -17,9 +17,6 @@ export type ParsedCli = {
 } | {
     kind: 'with-host-lock';
     args: string[];
-} | {
-    kind: 'agent-harness-config';
-    args: string[];
 } | {
     kind: 'script';
     command: ScriptCommand;