vouchington-tooling 0.29.0 → 0.31.0

package/dist/openapi-document/build-openapi-catalog-sse.mjs

@@ -0,0 +1,27 @@
+import { catalogResponse } from './openapi-route-helpers.mjs';
+/** Keeps a cataloged stream unavailable until its extracted variants describe SSE. */
+export function retainCatalogSseResponse(kind, variants, rendered) {
+    if (kind !== 'sse' ||
+        variants.some((variant) => variant.mediaType === 'text/event-stream' &&
+            variant.mediaTypeKnowledge !== 'unknown' &&
+            variant.bodyKind !== 'none'))
+        return rendered;
+    const reason = [rendered.unavailableReason, catalogResponse('sse').unavailableReason]
+        .filter(Boolean)
+        .join('; ');
+    const existing = rendered.responses[200];
+    return {
+        responses: {
+            ...rendered.responses,
+            200: {
+                ...existing,
+                description: existing?.description ?? 'OK',
+                content: { ...existing?.content, 'text/event-stream': { schema: {} } },
+                'x-schema-unavailable': true,
+                'x-schema-unavailable-reason': reason,
+            },
+        },
+        unavailable: true,
+        unavailableReason: reason,
+    };
+}

package/dist/openapi-document/build-openapi-document.mjs

@@ -1,6 +1,7 @@
 import { queryParameters } from './build-openapi-query.mjs';
 import { buildOperationRequestBody } from './build-openapi-request.mjs';
 import { buildOperationResponse } from './build-openapi-response.mjs';
+import { retainCatalogSseResponse } from './build-openapi-catalog-sse.mjs';
 import { createComponentRegistry } from './component-registry.mjs';
 import { responseStatusCodesForContract, routeShape, } from './operation-types.mjs';
 import { registerOpenApiErrorResponse } from './openapi-error-response.mjs';
@@ -112,10 +113,12 @@ function assertFixedNoContent(catalogRoute, variants, groupKey) {
     throw new Error(`OpenAPI fixed-no-content metadata conflicts with extracted response variants for ${groupKey}`);
 }
 function renderOperation(catalogRoute, variants, registry) {
-    if (catalogRoute?.kind === 'sse' || catalogRoute?.kind === 'fixed-no-content')
+    if (catalogRoute?.kind === 'fixed-no-content')
         return catalogResponse(catalogRoute.kind, catalogRoute.fixedStatus);
     if (variants)
-        return buildOperationResponse(variants, registry);
+        return retainCatalogSseResponse(catalogRoute?.kind, variants, buildOperationResponse(variants, registry));
+    if (catalogRoute?.kind === 'sse')
+        return catalogResponse('sse');
     if (catalogRoute?.kind === 'error-only')
         return catalogResponse('error-only');
     return catalogResponse('ordinary');

package/dist/openapi-document/build-openapi-response.d.mts

@@ -1,8 +1,8 @@
 import type { ComponentRegistry } from './component-registry.mts';
 import { type ResponseContract } from './operation-types.mts';
-import type { OpenApiResponseOrRef, OpenApiSchema } from './openapi-types.mts';
+import type { OpenApiResponse, OpenApiSchema } from './openapi-types.mts';
 export declare function buildOperationResponse(variants: ResponseContract[], registry: ComponentRegistry): {
-    responses: Record<number, OpenApiResponseOrRef>;
+    responses: Record<number, OpenApiResponse>;
     unavailable: boolean;
     unavailableReason?: string;
 };

package/dist/openapi-document/build-openapi-response.mjs

@@ -1,4 +1,5 @@
 import { STATUS_CODES } from 'node:http';
+import { collectSseEventSchemas, renderSseEvents, } from './build-openapi-sse-events.mjs';
 import { nodeToOpenApi } from './contract-schema-to-openapi.mjs';
 import { responseStatusCodesForContract } from './operation-types.mjs';
 export function buildOperationResponse(variants, registry) {
@@ -7,6 +8,8 @@ export function buildOperationResponse(variants, registry) {
     const operationFailures = [];
     for (const contract of variants) {
         const converted = convertContract(contract, registry);
+        const events = collectSseEventSchemas(contract, registry);
+        operationFailures.push(...events.failureReasons);
         if (converted.failureReason)
             operationFailures.push(converted.failureReason);
         if (contract.statusKnowledge === 'unknown' && !converted.failureReason)
@@ -17,6 +20,8 @@ export function buildOperationResponse(variants, registry) {
                 if (converted.failureReason)
                     reasons.push(converted.failureReason);
                 bodyless.set(status, reasons);
+                if (contract.includeDefaultError)
+                    addDefaultError(content, status, registry);
                 continue;
             }
             const mediaType = mediaTypeFor(contract);
@@ -25,12 +30,21 @@ export function buildOperationResponse(variants, registry) {
                 continue;
             }
             const byMedia = content.get(status) ?? new Map();
-            const bucket = byMedia.get(mediaType) ?? { schemas: [], failureReasons: [] };
-            bucket.schemas.push(converted.schema ?? {});
+            const bucket = byMedia.get(mediaType) ?? {
+                schemas: [],
+                failureReasons: [],
+                sseEvents: new Map(),
+            };
+            bucket.schemas.push(mediaType === 'text/event-stream' ? { type: 'string' } : (converted.schema ?? {}));
+            bucket.failureReasons.push(...events.failureReasons);
             if (converted.failureReason)
                 bucket.failureReasons.push(converted.failureReason);
+            for (const [name, schemas] of events.schemas)
+                bucket.sseEvents.set(name, [...(bucket.sseEvents.get(name) ?? []), ...schemas]);
             byMedia.set(mediaType, bucket);
             content.set(status, byMedia);
+            if (contract.includeDefaultError)
+                addDefaultError(content, status, registry);
         }
     }
     const responses = {};
@@ -45,6 +59,17 @@ export function buildOperationResponse(variants, registry) {
         ...(reasons.length > 0 ? { unavailableReason: reasons.join('; ') } : {}),
     };
 }
+function addDefaultError(content, status, registry) {
+    const byMedia = content.get(status) ?? new Map();
+    const bucket = byMedia.get('application/json') ?? {
+        schemas: [],
+        failureReasons: [],
+        sseEvents: new Map(),
+    };
+    bucket.schemas.push({ $ref: `#/components/schemas/${registry.refName('ErrorBody')}` });
+    byMedia.set('application/json', bucket);
+    content.set(status, byMedia);
+}
 function renderStatusResponse(status, byMedia, bodyless, operationFailures) {
     const hasBodyless = bodyless.has(status);
     const conflictReason = byMedia && hasBodyless
@@ -67,7 +92,12 @@ function renderStatusResponse(status, byMedia, bodyless, operationFailures) {
                     .toSorted(([left], [right]) => left.localeCompare(right))
                     .map(([mediaType, bucket]) => [
                     mediaType,
-                    { schema: mergeVariantSchemas(bucket.schemas) },
+                    {
+                        schema: mergeVariantSchemas(bucket.schemas),
+                        ...(bucket.sseEvents.size
+                            ? { 'x-sse-events': renderSseEvents(bucket.sseEvents) }
+                            : {}),
+                    },
                 ])),
             }
             : {}),

package/dist/openapi-document/build-openapi-sse-events.d.mts

@@ -0,0 +1,11 @@
+import type { ComponentRegistry } from './component-registry.mts';
+import type { ResponseContract } from './operation-types.mts';
+import type { OpenApiSchema } from './openapi-types.mts';
+export type SseEventSchemas = Map<string, OpenApiSchema[]>;
+export declare function collectSseEventSchemas(contract: ResponseContract, registry: ComponentRegistry): {
+    schemas: SseEventSchemas;
+    failureReasons: string[];
+};
+export declare function renderSseEvents(schemas: SseEventSchemas): Record<string, {
+    dataSchema: OpenApiSchema;
+}>;

package/dist/openapi-document/build-openapi-sse-events.mjs

@@ -0,0 +1,46 @@
+import { nodeToOpenApi } from './contract-schema-to-openapi.mjs';
+export function collectSseEventSchemas(contract, registry) {
+    const schemas = new Map();
+    const failureReasons = [];
+    if (contract.mediaType !== 'text/event-stream' && !contract.sseEvents)
+        return { schemas, failureReasons };
+    if (contract.mediaType !== 'text/event-stream' || contract.bodyKind === 'none')
+        return {
+            schemas,
+            failureReasons: ['SSE event metadata requires a text/event-stream response body'],
+        };
+    if (!contract.sseEvents?.length)
+        return { schemas, failureReasons: ['SSE event payload contracts are missing'] };
+    for (const { eventName, contract: event } of contract.sseEvents) {
+        if (!eventName.trim() || event.schema.root.type === 'unknown') {
+            failureReasons.push('SSE event payload or name is not statically known');
+            continue;
+        }
+        let schema;
+        try {
+            schema = nodeToOpenApi(event.schema.root, {
+                definitions: event.schema.definitions,
+                refName: registry.refName,
+            });
+        }
+        catch (error) {
+            failureReasons.push(String(error));
+            continue;
+        }
+        registry.register(event.source, event.schema.definitions);
+        const variants = schemas.get(eventName) ?? [];
+        variants.push(schema);
+        schemas.set(eventName, variants);
+    }
+    return { schemas, failureReasons };
+}
+export function renderSseEvents(schemas) {
+    return Object.fromEntries([...schemas.entries()]
+        .toSorted(([left], [right]) => left.localeCompare(right))
+        .map(([name, variants]) => {
+        const unique = [
+            ...new Map(variants.map((schema) => [JSON.stringify(schema), schema])).values(),
+        ].toSorted((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+        return [name, { dataSchema: unique.length === 1 ? unique[0] : { anyOf: unique } }];
+    }));
+}

package/dist/openapi-document/contract-schema-intersection-merge.mjs

@@ -11,10 +11,10 @@ export function intersectionToOpenApi(node, ctx, nodeToOpenApi) {
     if (resolved.some((variant) => variant === undefined)) {
         return { allOf: node.variants.map((variant) => nodeToOpenApi(variant, ctx)) };
     }
-    const properties = {};
+    const properties = new Map();
     for (const variant of resolved) {
         for (const [key, property] of Object.entries(variant.properties)) {
-            const existing = properties[key];
+            const existing = properties.get(key);
             if (existing &&
                 hashSchemaNode(existing.schema, ctx) !== hashSchemaNode(property.schema, ctx)) {
                 // A member re-declaring a shared key with a strictly narrower type is a common, valid
@@ -23,33 +23,33 @@ export function intersectionToOpenApi(node, ctx, nodeToOpenApi) {
                 // narrower type, not a conflict. Prefer whichever side is the narrower one; only two
                 // genuinely incompatible schemas (neither a subset of the other) are a real conflict.
                 if (isNarrowerVariant(property.schema, existing.schema, ctx)) {
-                    properties[key] = {
+                    properties.set(key, {
                         schema: property.schema,
                         required: existing.required || property.required,
-                    };
+                    });
                     continue;
                 }
                 /* v8 ignore next 6 -- symmetric of the previous branch; covered by order-swapped fixtures */
                 if (isNarrowerVariant(existing.schema, property.schema, ctx)) {
-                    properties[key] = {
+                    properties.set(key, {
                         schema: existing.schema,
                         required: existing.required || property.required,
-                    };
+                    });
                     continue;
                 }
                 throw new Error(`Cannot merge intersection: property "${key}" has conflicting schemas across members`);
             }
-            properties[key] = {
+            properties.set(key, {
                 schema: property.schema,
                 required: existing?.required || property.required,
-            };
+            });
         }
     }
-    const sortedKeys = Object.keys(properties).toSorted();
-    const required = sortedKeys.filter((key) => properties[key].required);
+    const sortedKeys = [...properties.keys()].toSorted();
+    const required = sortedKeys.filter((key) => properties.get(key).required);
     return {
         type: 'object',
-        properties: Object.fromEntries(sortedKeys.map((key) => [key, nodeToOpenApi(properties[key].schema, ctx)])),
+        properties: Object.fromEntries(sortedKeys.map((key) => [key, nodeToOpenApi(properties.get(key).schema, ctx)])),
         ...(required.length > 0 ? { required } : {}),
         additionalProperties: false,
     };

package/dist/openapi-document/contract-schema-to-openapi.mjs

@@ -42,17 +42,17 @@ function tupleToOpenApi(node, ctx) {
 }
 function objectToOpenApi(node, ctx) {
     const keys = Object.keys(node.properties).toSorted();
-    const properties = {};
+    const properties = new Map();
     const required = [];
     for (const key of keys) {
         const property = node.properties[key];
-        properties[key] = nodeToOpenApi(property.schema, ctx);
+        properties.set(key, nodeToOpenApi(property.schema, ctx));
         if (property.required)
             required.push(key);
     }
     return {
         type: 'object',
-        properties,
+        properties: Object.fromEntries(properties),
         ...(required.length > 0 ? { required } : {}),
         additionalProperties: node.additionalProperties === false ? false : nodeToOpenApi(node.additionalProperties, ctx),
     };

package/dist/openapi-document/openapi-route-helpers.mjs

@@ -34,11 +34,9 @@ export function catalogResponse(kind, fixedStatus) {
         };
     }
     if (kind === 'error-only') {
-        const reason = 'registered route has no success response';
         return {
             responses: { 405: { $ref: '#/components/responses/Error' } },
-            unavailable: true,
-            unavailableReason: reason,
+            unavailable: false,
         };
     }
     const reason = kind === 'sse'

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

@@ -39,6 +39,9 @@ export type OpenApiResponse = {
     description: string;
     content?: Record<string, {
         schema: OpenApiSchema;
+        'x-sse-events'?: Record<string, {
+            dataSchema: OpenApiSchema;
+        }>;
     }>;
     'x-schema-unavailable'?: true;
     'x-schema-unavailable-reason'?: string;

package/dist/openapi-document/operation-types.d.mts

@@ -1,3 +1,4 @@
+import type { ExtractedResponseContract } from '../contract-schema/types.mts';
 import type { ContractSchema } from './contract-schema-types.mts';
 import type { OpenApiQueryContract } from './query-types.mts';
 export type ResponseContract = {
@@ -11,6 +12,12 @@ export type ResponseContract = {
     mediaType?: string;
     mediaTypeKnowledge?: 'known' | 'none' | 'unknown';
     unavailableReason?: string;
+    sseEvents?: readonly {
+        eventName: string;
+        contract: ExtractedResponseContract;
+    }[];
+    /** Merge the framework error body into this explicit response's JSON variants. */
+    includeDefaultError?: boolean;
 };
 export type RequestContract = {
     source: string;

package/docs/mcp-server.md

@@ -11,30 +11,68 @@ are later phases.
 
 ## Install
 
-The server needs three packages next to `vouchington-tooling`. The last two are optional peer
-dependencies, so nothing else in the CLI requires them:
+Install the server once per machine, in its own dedicated directory, not in a project or a
+worktree: `pnpm add` installs into the directory it runs in. The server needs these packages
+installed next to `vouchington-tooling`. `agent-blackboard` and `@modelcontextprotocol/sdk` are
+optional peer dependencies, so nothing else in the CLI requires them. Pin exact versions; replace
+the placeholders with the current releases:
 
 ```bash
-pnpm add -D vouchington-tooling agent-blackboard@^0.6.0
-pnpm add -D @modelcontextprotocol/sdk zod
+mkdir -p ~/.local/share/vouchington-mcp
+cd ~/.local/share/vouchington-mcp
+pnpm init
+pnpm add --save-exact vouchington-tooling@<version> agent-blackboard@<version>
+pnpm add --save-exact @modelcontextprotocol/sdk@<version> zod@<version>
 ```
 
-`zod` is required by the SDK. When the SDK is missing, `vouchington mcp` writes a message naming the
-package to stderr and exits with status 1. `agent-blackboard` is resolved from the validated
-worktree at call time (`createRequire` on `<worktree>/package.json`), never from this package.
+Launch the server by the absolute path into that directory, for example
+`/abs/node ~/.local/share/vouchington-mcp/node_modules/vouchington-tooling/bin/vouchington-mcp.mjs`
+with `~` expanded to an absolute path (see [Launch](#launch)).
+
+`zod` is required by the SDK. Both `agent-blackboard` and the SDK are resolved from the server's own
+install, relative to this package's module, never from the worktree a tool call names, so
+repositories do not need to depend on `agent-blackboard`. When either is missing, `vouchington mcp`
+writes a message naming the package and the install directory to add it in to stderr and exits with
+status 1.
 
 The connection comes from `AGENT_BLACKBOARD_URL` and `AGENT_BLACKBOARD_TOKEN` in the server's
 environment. The server never searches for, prints, or mints them.
 
+## CLI fallback
+
+If MCP is unavailable, use `vouchington agent-blackboard journal append|entries|flush|status` as described
+in the blackboard skill. Record the fallback and delivery status in the journal and tell the human. The CLI resolves its
+client from its own installation, so install `agent-blackboard` alongside that trusted CLI.
+Run the script with a verified absolute `node` and a cleared environment (`env -i`), never through
+its `#!/usr/bin/env node` line, which takes `node` from a possibly repository-controlled `PATH`.
+A missing MCP connection does not waive persistence or readback requirements.
+
 ## Launch
 
 ```bash
 vouchington mcp
 ```
 
-The command takes no arguments. Start it inside the repository's git worktree: that repository
-defines which worktrees the tools accept. stdout carries only protocol frames, and diagnostics go
-to stderr.
+The stable entry point, for a harness that launches the server without a shell or a `PATH`
+lookup, is this package-relative file:
+
+```text
+node_modules/vouchington-tooling/bin/vouchington-mcp.mjs
+```
+
+Run it with an absolute Node, for example
+`/abs/node /abs/machine/node_modules/vouchington-tooling/bin/vouchington-mcp.mjs`. It is also the
+`vouchington-mcp` bin (`node_modules/.bin/vouchington-mcp`) and the `vouchington-tooling/mcp-server/bin`
+export. It takes no arguments, skips CLI argument parsing, and is a hand-written plain-JavaScript
+file that a CLI refactor does not move; a test pins the path. Both it and `bin/vouchington.mjs` check
+the Node version first: on Node older than 24 they print one line to stderr, such as
+`vouchington requires Node >=24 (found 18.19.0)`, and exit with status 1.
+
+The command takes no arguments and may be launched with any working directory, including one outside
+every git repository (for example `~`). When the working directory is inside a git worktree, that
+worktree's top level is the default for tools called without `worktree`. Otherwise those calls fail
+with a tool error asking for an explicit `worktree`. stdout carries only protocol frames, and
+diagnostics go to stderr.
 
 ## Tools
 
@@ -113,42 +151,62 @@ instructions shows it to the agent.
 
 ## Worktree validation
 
-`worktree` must be an absolute path that, after resolving symlinks, exactly matches an entry of
-`git worktree list --porcelain` for the repository the server was launched from. The list is read on
-every call, so worktrees created after launch are accepted and removed ones are refused. Anything
-else is rejected: a subdirectory of a worktree, a relative or nonexistent path, and a separate
-repository, including one made with `git init` elsewhere. It defaults to the launch worktree's root.
-Git runs without `GIT_*` variables, so `GIT_DIR` cannot redirect the check.
+`worktree` is checked on every call. It must be an absolute path that, after resolving symlinks,
+equals the top level of a git worktree, that is, what `git rev-parse --show-toplevel` prints when
+run in it. Any git worktree on the machine is accepted, including one of a repository unrelated to
+the launch directory, so the tools can act on every checkout the user can reach. Worktrees created
+after launch are accepted and removed ones are refused. Rejected: a subdirectory of a worktree, a
+relative or nonexistent path, and a directory that is not in a git worktree. Git runs without
+`GIT_*` variables, so `GIT_DIR` cannot redirect the check, and with `LC_ALL=C` and no `LANGUAGE`, so
+its "not a git repository" diagnostic is never translated.
+
+`worktree` only chooses where the outbox lives. It is not a trust boundary for loading code: the
+server never imports modules from it, and a tool that needs to must first get a repository allowlist
+from the machine registration.
+
+When `worktree` is omitted, the launch directory's worktree top level is used if the launch
+directory is inside one, and it is validated like any explicit path. If the server was launched
+outside a git worktree, the call fails with a tool error asking for an explicit `worktree`.
 
 ## Registering the server
 
-The commands below run `vouchington` from the repository's own `node_modules`, so a fresh worktree
-uses the version its lockfile pins. Set the blackboard credentials in the environment the harness
-gives the server.
+Register the machine-wide installation from [Install](#install) at user level, with absolute paths.
+Never check a registration into a repository: it names a path and a Node that exist only on your
+machine, and every worktree inherits it from your user config. Replace `/abs/node` with the absolute
+path of a Node >= 24 and `/home/you` with your home directory (neither file expands `~`). Set the
+blackboard credentials in the environment you start the harness from.
 
-Claude Code, `.mcp.json`:
+Claude Code, `mcpServers` in `~/.claude.json`:
 
 ```json
 {
   "mcpServers": {
     "vouchington-tooling": {
-      "command": "bash",
-      "args": ["-c", "exec \"$(git rev-parse --show-toplevel)/node_modules/.bin/vouchington\" mcp"]
+      "command": "/abs/node",
+      "args": [
+        "/home/you/.local/share/vouchington-mcp/node_modules/vouchington-tooling/bin/vouchington-mcp.mjs"
+      ]
     }
   }
 }
 ```
 
-Codex, `.codex/config.toml`:
+Codex, `~/.codex/config.toml`:
 
 ```toml
 [mcp_servers.vouchington-tooling]
-command = "bash"
-args = ["-c", "exec \"$(git rev-parse --show-toplevel)/node_modules/.bin/vouchington\" mcp"]
+command = "/abs/node"
+args = [
+  "/home/you/.local/share/vouchington-mcp/node_modules/vouchington-tooling/bin/vouchington-mcp.mjs",
+]
+env_vars = ["AGENT_BLACKBOARD_URL", "AGENT_BLACKBOARD_TOKEN"]
 default_tools_approval_mode = "approve"
 required = false
 ```
 
+`env_vars` forwards those variables from Codex's own environment. Codex does not expand `${VAR}`
+inside `env`, so do not write the credentials there.
+
 Approving every tool of the server at once:
 
 - Claude Code permission rule: `mcp__vouchington-tooling__*`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -14,10 +14,12 @@
     "directory": "packages/vouchington-tooling"
   },
   "bin": {
-    "vouchington": "dist/cli/index.mjs"
+    "vouchington": "bin/vouchington.mjs",
+    "vouchington-mcp": "bin/vouchington-mcp.mjs"
   },
   "files": [
     "ast-grep",
+    "bin",
     "dist",
     "docs",
     "skills",
@@ -68,6 +70,7 @@
       "import": "./dist/agent-blackboard/index.mjs",
       "default": "./dist/agent-blackboard/index.mjs"
     },
+    "./mcp-server/bin": "./bin/vouchington-mcp.mjs",
     "./session-friction": {
       "types": "./dist/session-friction/index.d.mts",
       "import": "./dist/session-friction/index.mjs",
@@ -113,11 +116,6 @@
       "import": "./dist/ast-grep-pack/index.mjs",
       "default": "./dist/ast-grep-pack/index.mjs"
     },
-    "./agent-harness-config": {
-      "types": "./dist/agent-harness-config/index.d.mts",
-      "import": "./dist/agent-harness-config/index.mjs",
-      "default": "./dist/agent-harness-config/index.mjs"
-    },
     "./vitest-blob-manifest": {
       "types": "./dist/vitest-blob-manifest/index.d.mts",
       "import": "./dist/vitest-blob-manifest/index.mjs",
@@ -352,7 +350,6 @@
     "picomatch": "4.0.7",
     "remark": "15.0.1",
     "remark-gfm": "4.0.1",
-    "smol-toml": "1.9.0",
     "spdx-expression-parse": "5.0.0",
     "yaml": "2.9.1"
   },
@@ -361,14 +358,19 @@
     "@modelcontextprotocol/sdk": "1.31.0",
     "@types/picomatch": "^4.0.3",
     "@types/spdx-expression-parse": "4.0.0",
-    "agent-blackboard": "^0.6.0"
+    "agent-blackboard": "^0.6.0",
+    "smol-toml": "1.9.0"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.31.0",
+    "agent-blackboard": "^0.6.0",
     "typescript": ">=5",
     "vitest": ">=5"
   },
   "peerDependenciesMeta": {
+    "agent-blackboard": {
+      "optional": true
+    },
     "@modelcontextprotocol/sdk": {
       "optional": true
     },

package/scripts/build.mjs

@@ -34,3 +34,5 @@ await copyFile(
   new URL('../skills/manifest.json', import.meta.url),
 )
 await chmod(new URL('../dist/cli/index.mjs', import.meta.url), 0o755)
+await chmod(new URL('../bin/vouchington.mjs', import.meta.url), 0o755)
+await chmod(new URL('../bin/vouchington-mcp.mjs', import.meta.url), 0o755)

package/skills/blackboard/SKILL.md

@@ -35,9 +35,71 @@ launch worktree by default). Writing or retrying an entry needs no provider skil
 `--file` flag, or replay command.
 Search for `journal_append` (by bare name, so every prefix matches) before concluding the server is
 unavailable; a deferred harness lists the tool only on request. If the search finds no such tool
-because the server is not registered, not connected, or not approved, stop and report that the
-journal server is unavailable, and name any per-user approval the harness still needs to load
-it (the consumer wrapper documents it). Do not fall back to a CLI command.
+because the server is not registered or not connected, use the supported CLI fallback below.
+Tell the human that MCP is unavailable and which CLI is being used. Record the fallback reason,
+entrypoint, affected operations, and observed delivery status in the caller's journal before
+continuing primary work. Do not treat a permission denial as tool unavailability or bypass a host
+approval requirement through the CLI. If neither path persists the note, stop and report the blocker.
+
+## CLI fallback
+
+Use a trusted machine-installed `vouchington` executable at a verified absolute path outside the
+consumer worktree. Resolve its symlinks and verify the installation's source and version before
+using credentials or requesting an unsandboxed run; its runtime dependencies must also belong to
+that trusted installation. The CLI resolves its client relative to its own installation; installing
+`agent-blackboard` only in the consumer worktree is insufficient for CLI fallback. Do not resolve the executable through the consumer's `node_modules/.bin`,
+`pnpm exec`, or repository-controlled `PATH`. Set `BLACKBOARD_CLI` below to that verified absolute
+script path, and bind any approval request to the same interpreter, script, and arguments.
+Never execute the script directly: its `#!/usr/bin/env node` line would pick whichever `node` comes
+first on `PATH`, which a consumer worktree can control. Set `BLACKBOARD_NODE` to a verified
+absolute Node 24+ binary outside the consumer worktree, and run it with `env -i` so only `HOME`, a
+fixed system `PATH`, and the two blackboard variables reach it. That also drops `NODE_OPTIONS` and
+other loader variables. If no trusted CLI is
+available, report the blocker; do not escalate a consumer-supplied executable. For local development,
+the reviewed source CLI may run inside the sandbox, subject to the harness's credential policy.
+`journal append` invokes the same validated writer as MCP, ensures the exact session identity,
+patches its repository union, and verifies delivery. Use a temporary `0600` markdown input file,
+remove it after the call, and inspect the JSON result: exit zero can mean retained pending feedback.
+The input file is transport to the supported writer, never a replacement journal. Append returns
+`pendingCount` for the caller and `worktreePendingCount` for the whole outbox. Use `journal status`
+or pass `--session-id` to `journal flush` for the same two counts; an unfiltered legacy flush reports
+only the whole-outbox count.
+
+```bash
+blackboard() {
+  env -i HOME="$HOME" PATH=/usr/bin:/bin \
+    AGENT_BLACKBOARD_URL="$AGENT_BLACKBOARD_URL" \
+    AGENT_BLACKBOARD_TOKEN="$AGENT_BLACKBOARD_TOKEN" \
+    "$BLACKBOARD_NODE" "$BLACKBOARD_CLI" agent-blackboard "$@"
+}
+blackboard journal append \
+  --session-id SESSION --agent AGENT --version VERSION \
+  --mode interactive --source-event-id EVENT --work-outcome unknown \
+  --repository owner/name --coverage-status not-assessed --dropped-count 0 \
+  --outbox-directory "$PWD/.local/blackboard-outbox" --file NOTE
+blackboard journal entries --session-id SESSION
+blackboard journal status \
+  --session-id SESSION --outbox-directory "$PWD/.local/blackboard-outbox"
+blackboard journal flush \
+  --session-id SESSION --outbox-directory "$PWD/.local/blackboard-outbox"
+```
+
+Pass `--parent-session-id` for a child, repeat `--repository` for additional repositories, and use
+explicit coverage sources when assessed. Omit `--timestamp` so the writer owns time. Autonomous
+mode omits `--outbox-directory` and still requires fresh online admission plus readback.
+For session-only or snapshot operations not exposed by this CLI, use the upstream
+`agent-blackboard` CLI under its skill's operation contract; preserve exact identities and tags.
+A sandboxed fallback may only write the outbox: the machine's harness sandbox can withhold
+`AGENT_BLACKBOARD_TOKEN`, so it cannot deliver or read back. If delivery or readback needs the
+credentials and the sandbox withholds them, run that one command unsandboxed through the harness's
+normal approval path for running one command outside the sandbox, with each such run approved
+individually. Never read, print, copy, or export the token
+to work around the sandbox. If approval is denied, leave the record pending in the outbox, report
+`pendingCount`, and tell the human.
+Return to MCP when available and journal recovery. Never silently downgrade envelope validation,
+retention, or delivery checks because the transport changed.
+
+## Journaling policy
 
 1. Capture consequential observations before filing an issue: failed or recovered checks, denied or
    approved permissions, repeated fixes, scope changes, first-party tool behavior, and architectural
@@ -65,7 +127,7 @@ it (the consumer wrapper documents it). Do not fall back to a CLI command.
    `journal_append` reports it as pending. Report `pendingCount` (this session's unsent records),
    and `worktreePendingCount` when other sessions' records are also unsent, from `journal_append`
    or `outbox_status`. Deliver with `outbox_flush` once the provider is reachable, and continue
-   primary work only after persistence succeeds. A full, unsafe, or unwritable outbox blocks
+   primary work only after persistence succeeds. A full, corrupt, or unwritable outbox blocks
    capture; never evict or silently discard an unsent record.
 5. Autonomous runners require online `session_ensure`, a fresh admission `journal_append`, and
    readback before launching an attempt. Give each attempt's admission entry a `sourceEventId`