vouchington-tooling 0.30.0 → 0.32.0

package/dist/mcp-server/run.mjs

@@ -1,4 +1,4 @@
-import { loadMcpSdk } from './sdk.mjs';
+import { assertBlackboardInstalled, loadMcpSdk } from './sdk.mjs';
 import { createMcpServer } from './server.mjs';
 import { launchWorktreeRoot, runIsolatedGit } from './worktree.mjs';
 /**
@@ -8,11 +8,14 @@ import { launchWorktreeRoot, runIsolatedGit } from './worktree.mjs';
 export async function runMcpServer(options) {
     const runGit = options.runGit ?? runIsolatedGit;
     const sdk = await loadMcpSdk(options.importSdk);
+    if (options.blackboard === undefined)
+        assertBlackboardInstalled(options.resolveFrom);
     const launchRoot = await launchWorktreeRoot(options.cwd, runGit);
     const environment = {
         launchRoot,
         env: options.env,
         runGit,
+        ...(options.resolveFrom === undefined ? {} : { resolveFrom: options.resolveFrom }),
         ...(options.blackboard === undefined ? {} : { blackboard: options.blackboard }),
     };
     const server = createMcpServer(sdk, environment, options.version);

package/dist/mcp-server/sdk.d.mts

@@ -9,9 +9,18 @@ export type McpSdk = {
     ListToolsRequestSchema: typeof ListToolsRequestSchema;
 };
 export type SdkImporter = (specifier: string) => Promise<unknown>;
-export declare const MISSING_SDK_MESSAGE: string;
+/**
+ * The directory the server was installed into: the parent of the outermost `node_modules` above
+ * `from`, which is where `pnpm add` must run so the peers resolve from this package. Outside any
+ * `node_modules` (a source checkout) it is the module's own directory.
+ */
+export declare function installDirectory(from?: string | URL): string;
+export declare function missingSdkMessage(directory: string): string;
 /**
  * Imports the SDK lazily. A static import would make every `vouchington` command fail on a
  * consumer that never installed the optional peer.
  */
-export declare function loadMcpSdk(importSdk?: SdkImporter): Promise<McpSdk>;
+export declare function loadMcpSdk(importSdk?: SdkImporter, directory?: string): Promise<McpSdk>;
+export declare function missingBlackboardMessage(directory: string): string;
+/** Fails fast at startup when `agent-blackboard` cannot be resolved from this package's install. */
+export declare function assertBlackboardInstalled(resolveFrom?: string | URL): void;

package/dist/mcp-server/sdk.mjs

@@ -6,17 +6,34 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+import { createRequire } from 'node:module';
+import { dirname, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { isMissingModuleError } from '../agent-blackboard/client.mjs';
 const SDK_PACKAGE = '@modelcontextprotocol/sdk';
-export const MISSING_SDK_MESSAGE = `vouchington mcp needs ${SDK_PACKAGE} (and its zod peer), which is an optional peer ` +
-    `dependency of vouchington-tooling and is not installed. Install it next to ` +
-    `vouchington-tooling: pnpm add -D ${SDK_PACKAGE} zod`;
+/**
+ * The directory the server was installed into: the parent of the outermost `node_modules` above
+ * `from`, which is where `pnpm add` must run so the peers resolve from this package. Outside any
+ * `node_modules` (a source checkout) it is the module's own directory.
+ */
+export function installDirectory(from = import.meta.url) {
+    const file = typeof from === 'string' && !from.startsWith('file:') ? from : fileURLToPath(from);
+    const marker = `${sep}node_modules${sep}`;
+    const index = file.indexOf(marker);
+    return index === -1 ? dirname(file) : file.slice(0, index);
+}
+export function missingSdkMessage(directory) {
+    return (`vouchington mcp needs ${SDK_PACKAGE} (and its zod peer), which is an optional peer ` +
+        `dependency of vouchington-tooling and is not installed. Install it in the directory ` +
+        `vouchington-tooling is installed in, not in a project: cd ${directory} && ` +
+        `pnpm add ${SDK_PACKAGE} zod`);
+}
 const defaultImporter = (specifier) => import(__rewriteRelativeImportExtension(specifier));
 /**
  * Imports the SDK lazily. A static import would make every `vouchington` command fail on a
  * consumer that never installed the optional peer.
  */
-export async function loadMcpSdk(importSdk = defaultImporter) {
+export async function loadMcpSdk(importSdk = defaultImporter, directory = installDirectory()) {
     try {
         const [server, stdio, types] = await Promise.all([
             importSdk(`${SDK_PACKAGE}/server/mcp.js`),
@@ -27,7 +44,22 @@ export async function loadMcpSdk(importSdk = defaultImporter) {
     }
     catch (error) {
         if (isMissingModuleError(error))
-            throw new Error(MISSING_SDK_MESSAGE, { cause: error });
+            throw new Error(missingSdkMessage(directory), { cause: error });
         throw error;
     }
 }
+export function missingBlackboardMessage(directory) {
+    return ('vouchington mcp needs agent-blackboard, which is an optional peer dependency of ' +
+        'vouchington-tooling and is not installed. Install it in the directory vouchington-tooling ' +
+        `is installed in, not in a project: cd ${directory} && pnpm add agent-blackboard`);
+}
+/** Fails fast at startup when `agent-blackboard` cannot be resolved from this package's install. */
+export function assertBlackboardInstalled(resolveFrom = import.meta.url) {
+    try {
+        createRequire(resolveFrom).resolve('agent-blackboard');
+    }
+    catch (error) {
+        // `resolve` only fails when the package cannot be found from `resolveFrom`.
+        throw new Error(missingBlackboardMessage(installDirectory(resolveFrom)), { cause: error });
+    }
+}

package/dist/mcp-server/server.mjs

@@ -2,8 +2,9 @@ import { callTool } from './dispatch.mjs';
 import { TOOLS } from './tools.mjs';
 export const SERVER_NAME = 'vouchington-tooling';
 const INSTRUCTIONS = 'Journals agent-blackboard feedback for a vouchington consumer. Every tool takes an explicit ' +
-    'sessionId and an optional worktree (an absolute path listed by `git worktree list` for the ' +
-    'repository this server was launched from). Hosts prefix the tool names differently: Claude ' +
+    'sessionId and an optional worktree (the absolute path of a git worktree top level; it ' +
+    'defaults to the launch directory worktree and is required when the server was launched ' +
+    'outside one). Hosts prefix the tool names differently: Claude ' +
     'Code mcp__vouchington-tooling__<tool>, Codex mcp__vouchington_tooling__<tool>, Grok ' +
     'vouchington-tooling__<tool> (through search_tool and use_tool), Cursor the vouchington-tooling ' +
     'namespace (through GetDynamicTools and CallDynamicTool). Search for journal_append before ' +

package/dist/mcp-server/tools.mjs

@@ -7,8 +7,9 @@ const SESSION_ID = {
 };
 const WORKTREE = {
     type: 'string',
-    description: 'Absolute path of a worktree listed by `git worktree list` for the repository the server ' +
-        'was launched from. Defaults to the launch worktree.',
+    description: 'Absolute path of the top level of a git worktree (`git rev-parse --show-toplevel`), not a ' +
+        'subdirectory. Defaults to the launch directory worktree; required when the server was ' +
+        'launched outside a git worktree.',
 };
 const PARENT_SESSION_ID = {
     type: ['string', 'null'],

package/dist/mcp-server/worktree.d.mts

@@ -1,18 +1,25 @@
 import { type RunTextCommand } from '../gh-cli/exec.mts';
-/** Runs git without inherited `GIT_*` variables so `GIT_DIR` cannot redirect the check. */
+/**
+ * The environment for git: no inherited `GIT_*` variables, so `GIT_DIR` cannot redirect the check,
+ * and the C locale, so git's diagnostics are not translated and can be classified reliably.
+ */
+export declare function isolatedGitEnv(): NodeJS.ProcessEnv;
 export declare const runIsolatedGit: RunTextCommand;
-/** The worktree root containing `cwd`, or a message that says how to fix the launch directory. */
-export declare function launchWorktreeRoot(cwd: string, runGit: RunTextCommand): Promise<string>;
-/** Paths of the non-bare entries in `git worktree list --porcelain` output. */
-export declare function parseWorktreeList(porcelain: string): string[];
 /**
- * Resolves the worktree a tool call may act on. The list is read from git on every call, so
- * worktrees created after the server started are accepted and removed ones are not. The
- * comparison is exact on real paths: a subdirectory of a worktree, or an unrelated repository,
- * is rejected.
+ * The worktree root containing `cwd`, or undefined when git reports `cwd` is not inside one (so
+ * the server may be launched from anywhere). Any other git failure, such as a missing git binary
+ * or an unsafe repository, is thrown with the cause rather than reported as "outside a worktree".
+ */
+export declare function launchWorktreeRoot(cwd: string, runGit: RunTextCommand): Promise<string | undefined>;
+/**
+ * Resolves the worktree a tool call may act on. It must be an absolute path that, after
+ * resolving symlinks, is exactly the top level of a git worktree (of any repository on the
+ * machine). A subdirectory, a relative or nonexistent path, and a non-git directory are rejected.
+ * Git is asked on every call, so worktrees created after the server started are accepted and
+ * removed ones are not. Without `requested`, the launch worktree is used when there is one.
  */
 export declare function resolveWorktree(input: {
-    launchRoot: string;
+    launchRoot: string | undefined;
     requested?: string | undefined;
     runGit: RunTextCommand;
 }): Promise<string>;

package/dist/mcp-server/worktree.mjs

@@ -5,8 +5,15 @@ import { promisify } from 'node:util';
 import { createCommandRunner } from '../gh-cli/exec.mjs';
 import { gitEnv } from '../shared-context/index.mjs';
 const execFileAsync = promisify(execFile);
-/** Runs git without inherited `GIT_*` variables so `GIT_DIR` cannot redirect the check. */
-export const runIsolatedGit = createCommandRunner('git', (command, args) => execFileAsync(command, args, { env: gitEnv() }));
+/**
+ * The environment for git: no inherited `GIT_*` variables, so `GIT_DIR` cannot redirect the check,
+ * and the C locale, so git's diagnostics are not translated and can be classified reliably.
+ */
+export function isolatedGitEnv() {
+    const { LANGUAGE: _language, ...env } = gitEnv();
+    return { ...env, LC_ALL: 'C' };
+}
+export const runIsolatedGit = createCommandRunner('git', (command, args) => execFileAsync(command, args, { env: isolatedGitEnv() }));
 async function canonical(path) {
     try {
         return await realpath(path);
@@ -15,44 +22,54 @@ async function canonical(path) {
         return undefined;
     }
 }
-/** The worktree root containing `cwd`, or a message that says how to fix the launch directory. */
+/**
+ * git's two "no worktree here" outcomes: outside any repository, and inside a `.git` directory.
+ * The messages are English because `isolatedGitEnv` forces the C locale.
+ */
+function isNotAGitRepository(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const { stderr, message } = error;
+    return [stderr, message].some((text) => typeof text === 'string' && /not a git repository|must be run in a work tree/i.test(text));
+}
+/**
+ * The worktree root containing `cwd`, or undefined when git reports `cwd` is not inside one (so
+ * the server may be launched from anywhere). Any other git failure, such as a missing git binary
+ * or an unsafe repository, is thrown with the cause rather than reported as "outside a worktree".
+ */
 export async function launchWorktreeRoot(cwd, runGit) {
+    let output;
     try {
-        return await realpath((await runGit(['-C', cwd, 'rev-parse', '--show-toplevel'])).trim());
+        output = await runGit(['-C', cwd, 'rev-parse', '--show-toplevel']);
     }
     catch (error) {
-        throw new Error(`vouchington mcp must be launched inside a git worktree; ${cwd} is not one (${errorText(error)})`);
+        if (isNotAGitRepository(error))
+            return undefined;
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`git could not determine the worktree of ${cwd}: ${reason}. Check that git is installed and ` +
+            'on PATH, that the directory exists, and that the repository is readable by this user ' +
+            '(see safe.directory).', { cause: error });
     }
-}
-/** Paths of the non-bare entries in `git worktree list --porcelain` output. */
-export function parseWorktreeList(porcelain) {
-    const paths = [];
-    for (const block of porcelain.split(/\r?\n\r?\n/)) {
-        const lines = block.split(/\r?\n/);
-        const first = lines.find((line) => line.startsWith('worktree '));
-        if (first !== undefined && !lines.includes('bare'))
-            paths.push(first.slice('worktree '.length));
-    }
-    return paths;
+    return realpath(output.trim());
 }
 /**
- * Resolves the worktree a tool call may act on. The list is read from git on every call, so
- * worktrees created after the server started are accepted and removed ones are not. The
- * comparison is exact on real paths: a subdirectory of a worktree, or an unrelated repository,
- * is rejected.
+ * Resolves the worktree a tool call may act on. It must be an absolute path that, after
+ * resolving symlinks, is exactly the top level of a git worktree (of any repository on the
+ * machine). A subdirectory, a relative or nonexistent path, and a non-git directory are rejected.
+ * Git is asked on every call, so worktrees created after the server started are accepted and
+ * removed ones are not. Without `requested`, the launch worktree is used when there is one.
  */
 export async function resolveWorktree(input) {
     const { launchRoot, requested, runGit } = input;
-    if (requested !== undefined && !isAbsolute(requested))
-        throw new Error('worktree must be an absolute path to a git worktree of the launch repository');
-    const target = requested === undefined ? launchRoot : await canonical(requested);
-    const listing = await runGit(['-C', launchRoot, 'worktree', 'list', '--porcelain']);
-    const known = (await Promise.all(parseWorktreeList(listing).map(canonical))).filter((path) => path !== undefined);
-    if (target !== undefined && known.includes(target))
+    if (requested === undefined && launchRoot === undefined)
+        throw new Error('worktree is required: this server was launched outside a git worktree, so pass ' +
+            'worktree as the absolute path of the git worktree to act on');
+    const path = requested ?? launchRoot;
+    if (!isAbsolute(path))
+        throw new Error('worktree must be an absolute path to a git worktree');
+    const target = await canonical(path);
+    if (target !== undefined && (await launchWorktreeRoot(target, runGit)) === target)
         return target;
-    throw new Error(`worktree ${requested ?? launchRoot} is not a worktree of the repository this server was ` +
-        `launched from (${launchRoot}). Registered worktrees: ${known.join(', ')}`);
-}
-function errorText(error) {
-    return error instanceof Error ? error.message : String(error);
+    throw new Error(`worktree ${path} is not the top level of a git worktree: it must exist and be the ` +
+        'directory `git rev-parse --show-toplevel` reports, not a subdirectory of it');
 }

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.30.0",
+  "version": "0.32.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",
@@ -360,10 +363,14 @@
   },
   "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`