vouchington-tooling 0.26.0 → 0.27.0

package/README.md

@@ -554,7 +554,10 @@ Identity, content, and archived-session conflicts fail in either mode while pres
 record; they are not reported as transient pending delivery. Replay retains permanently conflicted
 records and continues to deliver unrelated pending records; transient failures stop that replay.
 Verified delivery retains its receipt when local cleanup fails, returning
-`cleanupDiagnostic` with value `"outbox-cleanup-failed"`. A retained or crash-reappearing record is safe to replay with exact dedup.
+`cleanupDiagnostic` with value `"outbox-cleanup-failed"`. A retained or crash-reappearing record is
+safe to replay: an event is identified by session, `sourceEventId`, and content, and a duplicate that
+differs only in `timestamp` is the same event, so it reports the stored record's `timestamp` and
+receipt and the retained duplicate is removed.
 Use `vouchington agent-blackboard journal flush --outbox-directory PATH` to replay unchanged pending
 records after connectivity returns.
 

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

@@ -1 +1,8 @@
+import type { FeedbackEnvelope } from './feedback-types.mts';
 export declare function canonicalFeedback(value: unknown): string;
+/**
+ * The identity of a feedback event is its session, `sourceEventId`, and content. The `timestamp` is
+ * assigned by the server on each attempt, so a retry that differs only in `timestamp` is the same
+ * event and is left out of the comparison.
+ */
+export declare function canonicalFeedbackEvent(envelope: FeedbackEnvelope): string;

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

@@ -2,6 +2,14 @@ import { isObject } from './snapshot-partition-guards.mjs';
 export function canonicalFeedback(value) {
     return JSON.stringify(ordered(value));
 }
+/**
+ * The identity of a feedback event is its session, `sourceEventId`, and content. The `timestamp` is
+ * assigned by the server on each attempt, so a retry that differs only in `timestamp` is the same
+ * event and is left out of the comparison.
+ */
+export function canonicalFeedbackEvent(envelope) {
+    return canonicalFeedback(Object.fromEntries(Object.entries(envelope).filter(([key]) => key !== 'timestamp')));
+}
 function ordered(value) {
     if (Array.isArray(value))
         return value.map(ordered);

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

@@ -18,13 +18,14 @@ export async function writeFeedback(input) {
     }
     if (!input.outboxDirectory)
         throw new Error('interactive feedback requires an explicit durable outbox directory');
-    persistFeedbackOutbox(input.outboxDirectory, { identity: input.identity, envelope });
+    // A retained record for the same event keeps its own timestamp and is the one delivered.
+    const record = persistFeedbackOutbox(input.outboxDirectory, {
+        identity: input.identity,
+        envelope,
+    });
     try {
-        const receipt = await deliverFeedbackOnline({ ...input, envelope });
-        const cleanup = removeFeedbackOutbox(input.outboxDirectory, {
-            identity: input.identity,
-            envelope,
-        });
+        const receipt = await deliverFeedbackOnline({ ...input, envelope: record.envelope });
+        const cleanup = removeFeedbackOutbox(input.outboxDirectory, record);
         return { status: 'delivered', sourceEventId: envelope.sourceEventId, ...cleanup, receipt };
     }
     catch (error) {
@@ -34,6 +35,7 @@ export async function writeFeedback(input) {
         return {
             status: 'pending',
             sourceEventId: envelope.sourceEventId,
+            timestamp: record.envelope.timestamp,
             pendingCount: feedbackOutboxStatus(input.outboxDirectory).pendingCount,
             diagnostic,
         };

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

@@ -1,6 +1,6 @@
 import { feedbackDeadline } from './feedback-deadline.mjs';
 import { FeedbackDeliveryError, feedbackDiagnostic } from './feedback-online-error.mjs';
-import { canonicalFeedback } from './feedback-canonical.mjs';
+import { canonicalFeedback, canonicalFeedbackEvent } from './feedback-canonical.mjs';
 import { loadClient, resolveBlackboardConnection } from './client.mjs';
 import { normalizeRepositories, validateFeedbackEnvelope } from './feedback-codec.mjs';
 import { validateFeedbackIdentity } from './feedback-identity.mjs';
@@ -48,13 +48,18 @@ async function findEvent(entries, envelope, expectedCreatedAt) {
         catch {
             throw new FeedbackDeliveryError('event-conflict');
         }
-        if (canonicalFeedback(entry.data) !== canonicalFeedback(envelope) ||
+        // Same event means same content; the stored `timestamp` may differ from this attempt's.
+        if (canonicalFeedbackEvent(entry.data) !== canonicalFeedbackEvent(envelope) ||
             typeof entry.createdAt !== 'string')
             throw new FeedbackDeliveryError('event-conflict');
         if (++matching > 1 && expectedCreatedAt !== undefined)
             throw new FeedbackDeliveryError('event-conflict');
-        if (expectedCreatedAt === undefined || entry.createdAt === expectedCreatedAt)
-            found = { createdAt: entry.createdAt };
+        // Duplicates of one event (a late write beside a retry) report the earliest stored record, so
+        // every retry returns the same timestamp.
+        if (expectedCreatedAt === undefined
+            ? found === undefined || entry.createdAt < found.createdAt
+            : entry.createdAt === expectedCreatedAt)
+            found = { createdAt: entry.createdAt, timestamp: entry.data.timestamp };
     }
     return found;
 }
@@ -108,6 +113,7 @@ export async function deliverFeedbackOnline(input, fresh = false) {
                     sessionId: input.identity.sessionId,
                     sourceEventId: input.envelope.sourceEventId,
                     createdAt: existing.createdAt,
+                    timestamp: existing.timestamp,
                     verified: true,
                 };
             const appended = await entries.append({
@@ -127,6 +133,7 @@ export async function deliverFeedbackOnline(input, fresh = false) {
                 sessionId: input.identity.sessionId,
                 sourceEventId: input.envelope.sourceEventId,
                 createdAt: confirmed.createdAt,
+                timestamp: confirmed.timestamp,
                 verified: true,
             };
         }

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

@@ -1,7 +1,14 @@
 import type { FeedbackOutboxRecord, FeedbackOutboxStatus } from './feedback-types.mts';
 export declare function feedbackOutboxStatus(directory: string): FeedbackOutboxStatus;
 export declare function listFeedbackOutbox(directory: string): FeedbackOutboxRecord[];
-export declare function persistFeedbackOutbox(directory: string, record: FeedbackOutboxRecord): number;
+/** Reads the retained records without creating the outbox directory. */
+export declare function readFeedbackOutbox(directory: string): FeedbackOutboxRecord[];
+/**
+ * Retains the record unless the same event is already retained, in which case that record stays:
+ * the event is the session, `sourceEventId`, and content, and the earlier `timestamp` wins. The
+ * returned record is the one to deliver.
+ */
+export declare function persistFeedbackOutbox(directory: string, record: FeedbackOutboxRecord): FeedbackOutboxRecord;
 export declare function removeFeedbackOutbox(directory: string, record: FeedbackOutboxRecord): {
     pendingCount: number;
     cleanupDiagnostic?: 'outbox-cleanup-failed';

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

@@ -1,4 +1,4 @@
-import { canonicalFeedback } from './feedback-canonical.mjs';
+import { canonicalFeedback, canonicalFeedbackEvent } from './feedback-canonical.mjs';
 import { createHash, randomUUID } from 'node:crypto';
 import { closeSync, constants, fsyncSync, fstatSync, openSync, readdirSync, renameSync, unlinkSync, } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
@@ -83,6 +83,18 @@ export function listFeedbackOutbox(directory) {
     const path = outboxDirectory(directory, true);
     return withFileLock(join(path, '.records'), () => records(path).map((item) => item.record));
 }
+/** Reads the retained records without creating the outbox directory. */
+export function readFeedbackOutbox(directory) {
+    const path = outboxDirectory(directory, false);
+    if (!ensurePrivateDirectory(path, false))
+        return [];
+    return withFileLock(join(path, '.records'), () => records(path).map((item) => item.record));
+}
+/**
+ * Retains the record unless the same event is already retained, in which case that record stays:
+ * the event is the session, `sourceEventId`, and content, and the earlier `timestamp` wins. The
+ * returned record is the one to deliver.
+ */
 export function persistFeedbackOutbox(directory, record) {
     validateFeedbackIdentity(record.identity);
     validateFeedbackEnvelope(record.envelope);
@@ -93,9 +105,10 @@ export function persistFeedbackOutbox(directory, record) {
         const existing = current.find((item) => item.path === join(path, name));
         const serialized = JSON.stringify(record);
         if (existing) {
-            if (canonicalFeedback(existing.record) !== canonicalFeedback(record))
+            if (canonicalFeedback(existing.record.identity) !== canonicalFeedback(record.identity) ||
+                canonicalFeedbackEvent(existing.record.envelope) !== canonicalFeedbackEvent(record.envelope))
                 throw new Error('feedback source event conflicts with a retained unsent record');
-            return current.length;
+            return existing.record;
         }
         const bytes = Buffer.byteLength(serialized);
         if (bytes > RECORD_MAX_BYTES ||
@@ -128,7 +141,7 @@ export function persistFeedbackOutbox(directory, record) {
             catch { }
             throw error;
         }
-        return current.length + 1;
+        return record;
     });
 }
 export function removeFeedbackOutbox(directory, record) {

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

@@ -31,6 +31,8 @@ export type FeedbackReceipt = {
     sessionId: string;
     sourceEventId: string;
     createdAt: string;
+    /** The `timestamp` of the stored entry, which may be earlier than the attempt that confirmed it. */
+    timestamp: string;
     verified: true;
 };
 export type FeedbackDiagnostic = 'blackboard-unavailable' | 'client-unavailable' | 'configuration-invalid' | 'authentication-rejected' | 'identity-conflict' | 'readback-unconfirmed' | 'event-conflict' | 'archived-session' | 'delivery-timeout';
@@ -43,6 +45,8 @@ export type FeedbackDeliveryResult = {
 } | {
     status: 'pending';
     sourceEventId: string;
+    /** The `timestamp` of the retained record that a later flush delivers. */
+    timestamp: string;
     pendingCount: number;
     diagnostic: FeedbackDiagnostic;
 };

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

@@ -19,7 +19,7 @@ export type { BlackboardConnection, BlackboardClientModule, BlackboardClientDepe
 export type * from './feedback-types.mts';
 export { createFeedbackEnvelope, validateFeedbackEnvelope } from './feedback-codec.mts';
 export { writeFeedback, verifyFreshFeedback, flushFeedbackOutbox, FeedbackDeliveryError, } from './feedback-delivery.mts';
-export { feedbackOutboxStatus } from './feedback-outbox.mts';
+export { feedbackOutboxStatus, readFeedbackOutbox } from './feedback-outbox.mts';
 export { composeRetrospective } from './feedback-compose.mts';
 export type { RetrospectiveCompositionInput, FeedbackAssessment } from './feedback-compose.mts';
 export type { JournalAuditOptions } from './feedback-journal-audit.mts';

package/dist/agent-blackboard/index.mjs

@@ -61,5 +61,5 @@ export function formatJournalEntries(sessionId, entries) {
 export { resolveBlackboardConnection } from './client.mjs';
 export { createFeedbackEnvelope, validateFeedbackEnvelope } from './feedback-codec.mjs';
 export { writeFeedback, verifyFreshFeedback, flushFeedbackOutbox, FeedbackDeliveryError, } from './feedback-delivery.mjs';
-export { feedbackOutboxStatus } from './feedback-outbox.mjs';
+export { feedbackOutboxStatus, readFeedbackOutbox } from './feedback-outbox.mjs';
 export { composeRetrospective } from './feedback-compose.mjs';

package/dist/mcp-server/dispatch.mjs

@@ -2,7 +2,8 @@ import { join } from 'node:path';
 import { FeedbackDeliveryError } from '../agent-blackboard/index.mjs';
 import { optionalString, rejectUnknown, requireObject } from './args.mjs';
 import { readSessionId } from './context.mjs';
-import { journalAppend, journalEntries, outboxFlush, outboxStatus } from './handlers-journal.mjs';
+import { journalAppend, journalEntries } from './handlers-journal.mjs';
+import { outboxFlush, outboxStatus } from './handlers-outbox.mjs';
 import { sessionArchive, sessionEnsure, snapshotExport } from './handlers-session.mjs';
 import { TOOLS } from './tools.mjs';
 import { resolveWorktree } from './worktree.mjs';
@@ -17,14 +18,14 @@ const HANDLERS = {
 };
 const DIAGNOSTIC_HINTS = {
     'identity-conflict': 'the session already exists with a different parent, agent, or version',
-    'event-conflict': 'sourceEventId was already used with different content or timestamp; use a new sourceEventId',
+    'event-conflict': 'sourceEventId was already used with different content; use a new sourceEventId',
     'archived-session': 'the session is archived; write to a new session',
     'authentication-rejected': 'the blackboard rejected AGENT_BLACKBOARD_TOKEN',
     'blackboard-unavailable': 'the blackboard could not be reached or returned an error',
     'configuration-invalid': 'AGENT_BLACKBOARD_URL or AGENT_BLACKBOARD_TOKEN is missing or invalid',
     'client-unavailable': 'agent-blackboard is not installed in the worktree',
-    'readback-unconfirmed': 'the write could not be confirmed; retry with the same sourceEventId and timestamp',
-    'delivery-timeout': 'delivery timed out; retry with the same sourceEventId and timestamp',
+    'readback-unconfirmed': 'the write could not be confirmed; retry the same call (same sourceEventId and content)',
+    'delivery-timeout': 'delivery timed out; retry the same call (same sourceEventId and content)',
 };
 function describeError(error) {
     if (error instanceof FeedbackDeliveryError)

package/dist/mcp-server/fake-blackboard.test-helpers.d.mts

@@ -22,6 +22,8 @@ export type FakeOptions = {
     };
     entries?: StoredEntry[];
     entriesError?: unknown;
+    /** An entry another caller writes just before the next append, after that append's read. */
+    lateEntry?: StoredEntry;
 };
 export type FakeBlackboard = {
     dependencies: BlackboardClientDependencies;
@@ -29,6 +31,7 @@ export type FakeBlackboard = {
         ensure: unknown[];
         patch: unknown[];
         append: unknown[];
+        get: unknown[];
         archive: string[];
         export: unknown[];
     };

package/dist/mcp-server/fake-blackboard.test-helpers.mjs

@@ -15,6 +15,7 @@ export function fakeBlackboard(options = {}) {
         ensure: [],
         patch: [],
         append: [],
+        get: [],
         archive: [],
         export: [],
     };
@@ -44,9 +45,13 @@ export function fakeBlackboard(options = {}) {
     }
     if (options.omitArchive)
         delete Sessions.prototype.archive;
+    let lateEntry = options.lateEntry;
     class Entries {
         async append(input) {
             calls.append.push(input);
+            if (lateEntry)
+                stored.push(lateEntry);
+            lateEntry = undefined;
             const entry = {
                 createdAt: `2026-01-01T00:00:${String(stored.length).padStart(2, '0')}.000Z`,
                 data: input.data,
@@ -54,7 +59,8 @@ export function fakeBlackboard(options = {}) {
             stored.push(entry);
             return entry;
         }
-        async *get() {
+        async *get(input) {
+            calls.get.push(input);
             if (options.entriesError !== undefined)
                 throw options.entriesError;
             yield* stored;

package/dist/mcp-server/handlers-journal.d.mts

@@ -2,5 +2,3 @@ import { type ToolHandler } from './context.mts';
 export declare const journalAppend: ToolHandler;
 /** Every entry as the client returns it, oldest first. Nothing is filtered or rewritten. */
 export declare const journalEntries: ToolHandler;
-export declare const outboxStatus: ToolHandler;
-export declare const outboxFlush: ToolHandler;

package/dist/mcp-server/handlers-journal.mjs

@@ -1,6 +1,7 @@
-import { appendJournalMarkdown, feedbackOutboxStatus, flushFeedbackOutbox, readJournal, } from '../agent-blackboard/index.mjs';
+import { appendJournalMarkdown, readJournal, } from '../agent-blackboard/index.mjs';
 import { optionalRecord, optionalString, requiredChoice, requiredString, requiredStringArray, rejectUnknown, } from './args.mjs';
 import { outboxDirectory, readIdentity } from './context.mjs';
+import { outboxCounts } from './handlers-outbox.mjs';
 const MODES = ['interactive', 'autonomous'];
 const OUTCOMES = [
     'in-progress',
@@ -39,26 +40,35 @@ function readCoverage(args) {
 export const journalAppend = async (args, context) => {
     const identity = readIdentity(args, context.sessionId);
     const mode = requiredChoice(args, 'mode', MODES);
-    // The envelope includes the timestamp, so a retry of one sourceEventId must reuse it. Fixing the
-    // default here and returning it lets the caller do that.
-    const timestamp = optionalString(args, 'timestamp') ?? new Date().toISOString();
+    const sourceEventId = requiredString(args, 'sourceEventId');
     const category = optionalString(args, 'category');
-    const result = await appendJournalMarkdown({
-        ...identity,
-        mode,
-        // Interactive delivery needs a durable outbox; autonomous delivery forbids one.
-        ...(mode === 'interactive' ? { outboxDirectory: outboxDirectory(context.worktree) } : {}),
+    const entry = {
         markdown: requiredString(args, 'markdown'),
-        sourceEventId: requiredString(args, 'sourceEventId'),
         workOutcome: requiredChoice(args, 'workOutcome', OUTCOMES),
         repositories: requiredStringArray(args, 'repositories'),
         feedbackCoverage: readCoverage(args),
-        timestamp,
+    };
+    // Interactive delivery needs a durable outbox; autonomous delivery forbids one.
+    const directory = mode === 'interactive' ? outboxDirectory(context.worktree) : undefined;
+    const result = await appendJournalMarkdown({
+        ...identity,
+        ...entry,
+        mode,
+        sourceEventId,
+        ...(directory === undefined ? {} : { outboxDirectory: directory }),
         ...(category === undefined ? {} : { category }),
         env: context.env,
         dependencies: context.dependencies,
     });
-    return { sessionId: context.sessionId, timestamp, ...result };
+    // The server owns the timestamp: a first append takes the current time, and a retry of the same
+    // event (same session, sourceEventId, and content) reports the one already stored or retained.
+    const timestamp = result.status === 'delivered' ? result.receipt.timestamp : result.timestamp;
+    // Autonomous delivery never uses an outbox, so it has nothing pending. Interactive delivery
+    // reports the outbox as it is after delivery, split into the caller's session and the worktree.
+    const counts = mode === 'interactive'
+        ? outboxCounts(context.worktree, context.sessionId)
+        : { pendingCount: 0, worktreePendingCount: 0 };
+    return { sessionId: context.sessionId, ...result, timestamp, ...counts };
 };
 // `Entries.get` documents no order, and `createdAt` is a service-generated ISO 8601 UTC time whose
 // text order is time order. An entry without a usable `createdAt` sorts first rather than throwing.
@@ -78,21 +88,3 @@ export const journalEntries = async (_args, context) => ({
     sessionId: context.sessionId,
     entries: (await readJournal(context.sessionId, context.env, context.dependencies)).toSorted(byCreatedAt),
 });
-export const outboxStatus = async (_args, context) => ({
-    sessionId: context.sessionId,
-    ...feedbackOutboxStatus(outboxDirectory(context.worktree)),
-});
-export const outboxFlush = async (_args, context) => {
-    const directory = outboxDirectory(context.worktree);
-    // Flushing creates the outbox directory, so an empty or absent outbox is reported as is.
-    if (feedbackOutboxStatus(directory).pendingCount === 0)
-        return { sessionId: context.sessionId, status: 'empty', pendingCount: 0, deliveredCount: 0 };
-    return {
-        sessionId: context.sessionId,
-        ...(await flushFeedbackOutbox({
-            directory,
-            env: context.env,
-            dependencies: context.dependencies,
-        })),
-    };
-};

package/dist/mcp-server/handlers-outbox.d.mts

@@ -0,0 +1,11 @@
+import { type ToolHandler } from './context.mts';
+/**
+ * The outbox belongs to the worktree, not to one session, so two counts are reported. `pendingCount`
+ * is the caller's session only; `worktreePendingCount` is every session's records.
+ */
+export declare function outboxCounts(worktree: string, sessionId: string): {
+    pendingCount: number;
+    worktreePendingCount: number;
+};
+export declare const outboxStatus: ToolHandler;
+export declare const outboxFlush: ToolHandler;

package/dist/mcp-server/handlers-outbox.mjs

@@ -0,0 +1,45 @@
+import { flushFeedbackOutbox, readFeedbackOutbox } from '../agent-blackboard/index.mjs';
+import { outboxDirectory } from './context.mjs';
+/**
+ * The outbox belongs to the worktree, not to one session, so two counts are reported. `pendingCount`
+ * is the caller's session only; `worktreePendingCount` is every session's records.
+ */
+export function outboxCounts(worktree, sessionId) {
+    // A read that never creates the directory, so asking about an empty outbox leaves no trace.
+    const records = readFeedbackOutbox(outboxDirectory(worktree));
+    return {
+        pendingCount: records.filter((record) => record.identity.sessionId === sessionId).length,
+        worktreePendingCount: records.length,
+    };
+}
+function sessionStatus(pendingCount) {
+    return pendingCount === 0 ? 'empty' : 'pending';
+}
+export const outboxStatus = async (_args, context) => {
+    const counts = outboxCounts(context.worktree, context.sessionId);
+    return { sessionId: context.sessionId, status: sessionStatus(counts.pendingCount), ...counts };
+};
+export const outboxFlush = async (_args, context) => {
+    // Flushing creates the outbox directory, so an empty or absent outbox is reported as is.
+    if (outboxCounts(context.worktree, context.sessionId).worktreePendingCount === 0)
+        return {
+            sessionId: context.sessionId,
+            status: 'empty',
+            pendingCount: 0,
+            worktreePendingCount: 0,
+            deliveredCount: 0,
+        };
+    // The flush delivers every session's records; only the counts below are per session.
+    const flushed = await flushFeedbackOutbox({
+        directory: outboxDirectory(context.worktree),
+        env: context.env,
+        dependencies: context.dependencies,
+    });
+    const counts = outboxCounts(context.worktree, context.sessionId);
+    return {
+        sessionId: context.sessionId,
+        ...flushed,
+        status: sessionStatus(counts.pendingCount),
+        ...counts,
+    };
+};

package/dist/mcp-server/harness.test-helpers.d.mts

@@ -29,5 +29,10 @@ export declare const JOURNAL_ARGS: {
         sources: string[];
         droppedCount: number;
     };
-    timestamp: string;
+};
+/** The time `useFixedClock` pins, which is the timestamp the server mints for a first append. */
+export declare const NOW = "2026-01-01T00:00:00.000Z";
+/** Pins `Date` only, so timers and child processes keep running. */
+export declare function useFixedClock(): {
+    advance: (milliseconds: number) => void;
 };

package/dist/mcp-server/harness.test-helpers.mjs

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import { afterEach, beforeEach } from 'vitest';
+import { afterEach, beforeEach, vi } from 'vitest';
 import { callTool } from './dispatch.mjs';
 import { BLACKBOARD_ENV, fakeBlackboard, } from './fake-blackboard.test-helpers.mjs';
 import { createRepoFixture } from './git-fixture.test-helpers.mjs';
@@ -44,5 +44,17 @@ export const JOURNAL_ARGS = {
     workOutcome: 'success',
     repositories: ['owner/repo'],
     feedbackCoverage: { status: 'complete', sources: ['tool-result'], droppedCount: 0 },
-    timestamp: '2026-01-01T00:00:00.000Z',
 };
+/** The time `useFixedClock` pins, which is the timestamp the server mints for a first append. */
+export const NOW = '2026-01-01T00:00:00.000Z';
+/** Pins `Date` only, so timers and child processes keep running. */
+export function useFixedClock() {
+    beforeEach(() => {
+        vi.useFakeTimers({ toFake: ['Date'] });
+        vi.setSystemTime(new Date(NOW));
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    return { advance: (milliseconds) => vi.setSystemTime(new Date(Date.now() + milliseconds)) };
+}

package/dist/mcp-server/server.mjs

@@ -3,7 +3,11 @@ 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). Tool errors are actionable; do not fall back to a CLI.';
+    'repository this server was launched from). 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 ' +
+    'concluding this server is unavailable. Tool errors are actionable; do not fall back to a CLI.';
 /**
  * Builds the server. The tool list and call handlers go on the low-level `server` because the
  * high-level `registerTool` path needs zod schemas, and this package keeps zod out of its own code.

package/dist/mcp-server/tools.mjs

@@ -59,7 +59,13 @@ const IDENTITY_REQUIRED = ['parentSessionId', 'agent', 'version'];
 export const TOOLS = [
     tool('journal_append', 'Appends one journal entry to the caller session and returns the verified read-back receipt. ' +
         'Nothing is written unless every required field validates. Interactive mode retains the ' +
-        'envelope in the worktree outbox when the blackboard is unreachable.', ADDITIVE, {
+        'envelope in the worktree outbox when the blackboard is unreachable. The server owns the ' +
+        'entry timestamp and returns it. An event is identified by sessionId, sourceEventId, and ' +
+        'content, never by timestamp: to retry, repeat the identical call, and a retry of an ' +
+        'event already stored or retained reports the stored timestamp instead of a new one. The ' +
+        'same sourceEventId with different content is an event-conflict. pendingCount counts ' +
+        'unsent records of the caller sessionId; worktreePendingCount counts those of every ' +
+        'session in the worktree outbox (both 0 in autonomous mode, which never uses an outbox).', ADDITIVE, {
         ...IDENTITY,
         mode: { enum: ['interactive', 'autonomous'], description: 'Delivery mode.' },
         markdown: { type: 'string', description: 'Journal note as markdown text (max 12000 bytes).' },
@@ -82,11 +88,6 @@ export const TOOLS = [
             additionalProperties: false,
             description: 'Explicit coverage; sources default to [] and droppedCount to 0.',
         },
-        timestamp: {
-            type: 'string',
-            description: 'Optional ISO 8601 time; defaults to now and is returned. Reuse the same sourceEventId ' +
-                'and timestamp when retrying, because the whole envelope must match.',
-        },
         category: { type: 'string', description: 'Optional context; never changes entry type.' },
     }, [
         ...IDENTITY_REQUIRED,
@@ -100,10 +101,11 @@ export const TOOLS = [
     tool('journal_entries', 'Returns every entry of one session, oldest first, as JSON: { sessionId, entries }. Each ' +
         'entry is exactly as the blackboard returns it ({ sessionId, createdAt, data }), including ' +
         'non-journal types such as retrospective and legacy entries without a feedback envelope.', READ_ONLY),
-    tool('outbox_status', 'Reports how many unsent journal records the worktree outbox retains. sessionId identifies ' +
-        'the caller; the count covers the whole outbox.', READ_ONLY),
-    tool('outbox_flush', 'Delivers retained outbox records and returns the remaining count. sessionId identifies the ' +
-        'caller; the flush covers every record in the worktree outbox.', IDEMPOTENT_ADDITIVE),
+    tool('outbox_status', 'Reports unsent journal records in the worktree outbox. pendingCount and status (empty or ' +
+        'pending) cover the caller sessionId only; worktreePendingCount covers every session.', READ_ONLY),
+    tool('outbox_flush', 'Delivers every retained record in the worktree outbox, whichever session wrote it, and ' +
+        'returns deliveredCount for the whole flush. pendingCount and status cover the remaining ' +
+        'records of the caller sessionId; worktreePendingCount covers every session.', IDEMPOTENT_ADDITIVE),
     tool('session_ensure', 'Idempotently creates a session, or verifies that an existing one has the same identity. ' +
         'Returns the session id and whether it was created.', IDEMPOTENT_ADDITIVE, IDENTITY, IDENTITY_REQUIRED),
     tool('snapshot_export', 'Exports non-archived sessions into a private local JSONL file chosen by the blackboard ' +

package/dist/pnpm-install/pnpm-install-fake-pnpm.test-helpers.mjs

@@ -7,7 +7,7 @@ if [ "\${1:-}" = m ]; then
   exit 0
 fi
 if [ "\${1:-}" = --version ]; then
-  printf '%s\\n' "\${PNPM_VERSION:-11.0.0}"
+  printf '%s\\n' "\${PNPM_VERSION:-1.0.0}"
   exit 0
 fi
 printf '%s\\n' "$*" >> "$PNPM_LOG"
@@ -23,7 +23,7 @@ write_modules() {
 print_release_age_violation() {
   printf '%s\\n' '✗ Lockfile failed supply-chain policy check (1 entries in 0.1s)'
   printf '%s\\n' '[ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION] 1 lockfile entries failed verification:'
-  printf '%s\\n' '  undici@8.10.0 was published at 2026-08-03T15:06:33.000Z, within the minimumReleaseAge cutoff (2026-08-02T04:48:10.357Z)'
+  printf '%s\\n' '  fixture-package@1.0.0 was published at 2026-08-03T15:06:33.000Z, within the minimumReleaseAge cutoff (2026-08-02T04:48:10.357Z)'
 }
 if [ "\${PNPM_FAIL_CALL:-0}" = "$calls" ]; then
   if [ -n "\${PNPM_FAIL_RELEASE_AGE:-}" ]; then print_release_age_violation; fi

package/docs/mcp-server.md

@@ -42,22 +42,36 @@ Every tool takes an explicit `sessionId` (`^[A-Za-z0-9._:-]+$`, at most 256 char
 server never infers, and an optional `worktree`. Unknown arguments are rejected. Failures come back
 as MCP tool errors (`isError: true`) with an actionable message rather than crashing the server.
 
-| Tool              | Arguments besides `sessionId` and `worktree`                                                                                                                                                    | Returns                                                                                         |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `journal_append`  | `parentSessionId`, `agent`, `version`, `mode` (`interactive` or `autonomous`), `markdown`, `sourceEventId`, `workOutcome`, `repositories`, `feedbackCoverage`, optional `timestamp`, `category` | `sessionId`, `timestamp`, delivery `status` (`delivered` with a verified receipt, or `pending`) |
-| `journal_entries` | none                                                                                                                                                                                            | `sessionId` and `entries`, every entry oldest first                                             |
-| `outbox_status`   | none                                                                                                                                                                                            | `sessionId`, `status`, `pendingCount`                                                           |
-| `outbox_flush`    | none                                                                                                                                                                                            | `sessionId`, `status`, `pendingCount`, `deliveredCount`                                         |
-| `session_ensure`  | `parentSessionId`, `agent`, `version`                                                                                                                                                           | `sessionId`, `status` (`created` or `exists`), `archived`                                       |
-| `snapshot_export` | optional `agent`, `version`, `parentSessionId`, `data`, `dataArrayContains`, `inactiveForHours`                                                                                                 | `sessionId`, `path`, `counts`, `checksum`, `manifest`, `cleanupToken`                           |
-| `session_archive` | none                                                                                                                                                                                            | `sessionId`, `archived: true`                                                                   |
+| Tool              | Arguments besides `sessionId` and `worktree`                                                                                                                                       | Returns                                                                                                                                 |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `journal_append`  | `parentSessionId`, `agent`, `version`, `mode` (`interactive` or `autonomous`), `markdown`, `sourceEventId`, `workOutcome`, `repositories`, `feedbackCoverage`, optional `category` | `sessionId`, `timestamp`, delivery `status` (`delivered` with a verified receipt, or `pending`), `pendingCount`, `worktreePendingCount` |
+| `journal_entries` | none                                                                                                                                                                               | `sessionId` and `entries`, every entry oldest first                                                                                     |
+| `outbox_status`   | none                                                                                                                                                                               | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`                                                                           |
+| `outbox_flush`    | none                                                                                                                                                                               | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `deliveredCount`                                                         |
+| `session_ensure`  | `parentSessionId`, `agent`, `version`                                                                                                                                              | `sessionId`, `status` (`created` or `exists`), `archived`                                                                               |
+| `snapshot_export` | optional `agent`, `version`, `parentSessionId`, `data`, `dataArrayContains`, `inactiveForHours`                                                                                    | `sessionId`, `path`, `counts`, `checksum`, `manifest`, `cleanupToken`                                                                   |
+| `session_archive` | none                                                                                                                                                                               | `sessionId`, `archived: true`                                                                                                           |
 
 `journal_append` validates the whole feedback envelope with `validateFeedbackEnvelope` before
 anything is written, so a missing required field writes nothing. It returns the verified read-back
-result of `writeFeedback`. Delivery is at least once. The envelope includes its timestamp, so when
-retrying the same `sourceEventId`, resend the same content and the `timestamp` the first call
-returned; the server fixes a default timestamp and returns it for that reason. Markdown is limited
-to 12000 bytes.
+result of `writeFeedback`. Delivery is at least once. Markdown is limited to 12000 bytes.
+
+The server owns the entry `timestamp`: the tool takes no `timestamp` argument and rejects one, so an
+agent cannot fabricate it, and the result returns the timestamp it reports. An event is identified by
+`sessionId`, `sourceEventId`, and content; the timestamp is not part of that identity. The server
+stamps each attempt with the current time, and the delivery step compares the new attempt with what
+the blackboard or the worktree outbox already holds while ignoring only `timestamp`. To retry, repeat
+the identical call. A retry of an event that is already stored, or already retained in the outbox,
+is the same event: it writes nothing, drops the duplicate retained record, and returns the stored
+record's `timestamp` and `receipt`, so repeated retries report the same timestamp, including after a
+server restart and when the provider was unreachable for the retry. An outbox record that was
+delivered before the retry is recognized the same way when it is flushed, so it drains instead of
+blocking. Any difference in the other envelope fields under the same `sessionId` and
+`sourceEventId` is an `event-conflict` (or a conflict with the retained unsent record) and writes
+nothing. If an autonomous write of the same event lands between the check and the append, both
+entries exist, but the report names the earliest stored one and later retries report it again.
+Admission freshness (`verifyFreshFeedback`) keeps its stricter rule: any earlier record of the event,
+whatever its timestamp, is a conflict.
 
 `journal_entries` returns `{ sessionId, entries }`. Each entry is exactly what the `agent-blackboard`
 client returns (`sessionId`, `createdAt`, `data`), so `data` keeps its envelope fields such as
@@ -67,7 +81,13 @@ order, so they are sorted stably by `createdAt`, oldest first. An empty session
 `entries: []`. `vouchington agent-blackboard journal entries` still prints journal markdown only.
 
 `sessionId` on `outbox_status`, `outbox_flush`, and `snapshot_export` only identifies the caller.
-The outbox is per worktree and the status and flush cover every record in it. Flushing an empty
+The outbox is per worktree, so the results name two counts apart. `pendingCount` is the number of
+unsent records of the caller's `sessionId`, and `status` (`empty` or `pending`) follows it.
+`worktreePendingCount` is the number of unsent records of every session in the worktree outbox. Both
+are 0 in autonomous mode, which has no outbox. `outbox_flush` delivers every retained record in the
+worktree, whichever session wrote it, so its `deliveredCount` covers the whole flush while
+`pendingCount` and `worktreePendingCount` report what remains. A record that cannot be delivered, for
+example after an `event-conflict`, stays in the count of the session that wrote it. Flushing an empty
 outbox does not create the directory. `snapshot_export` never accepts a destination: the
 `agent-blackboard` client chooses a private file and returns its path. `session_archive` is the one
 destructive tool; archived metadata is immutable, while entries stay appendable.
@@ -75,6 +95,22 @@ destructive tool; archived metadata is immutable, while entries stay appendable.
 The outbox lives at `<worktree>/.local/blackboard-outbox` and is used only in interactive mode.
 Autonomous mode forbids a filesystem outbox, so a failed delivery is an error.
 
+### Tool names by harness
+
+Each harness names the same tools differently, and some load them on demand. The names in this page
+are the bare tool names; find yours by searching for `journal_append` before concluding the server
+is unavailable.
+
+| Harness     | `journal_append` is called                                                                                               |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Claude Code | `mcp__vouchington-tooling__journal_append`                                                                               |
+| Codex       | `mcp__vouchington_tooling__journal_append` (the server name's hyphen becomes an underscore)                              |
+| Cursor      | deferred: look it up with `GetDynamicTools` and call it with `CallDynamicTool` under the `vouchington-tooling` namespace |
+| Grok        | `vouchington-tooling__journal_append`, found with `search_tool` and called with `use_tool`                               |
+
+The server sends the same list in its MCP `instructions`, so a harness that surfaces server
+instructions shows it to the agent.
+
 ## Worktree validation
 
 `worktree` must be an absolute path that, after resolving symlinks, exactly matches an entry of
@@ -119,6 +155,11 @@ Approving every tool of the server at once:
 - Cursor permission rule: `Mcp(vouchington-tooling:*)`
 - Codex: `default_tools_approval_mode = "approve"` above
 
+Cursor also asks each user to approve loading a project server, separately from the permission rule
+above, and the rule does not replace it. Approve it once, interactively, with
+`cursor-agent mcp enable vouchington-tooling`. Headless `cursor-agent -p` does not keep that
+approval: pass `--approve-mcps` on every run.
+
 ## What is verified
 
 Covered by this package's tests: the tool list and schemas, every tool's success and rejection
@@ -126,6 +167,9 @@ paths against a faked blackboard client, the worktree gate against real temporar
 an in-process client and server round trip through the SDK's in-memory transport, and a spawned
 `vouchington mcp` process driven over real stdio.
 
+The per-harness tool names and the Cursor approval steps come from headless smoke runs of the
+server in each harness, not from this package's tests.
+
 Not verified, and tracked as the unchecked Phase 0 checklist in
 [#324](https://github.com/vouchington/vouchington-tooling/issues/324): each harness's approval
 syntax and whether the rules above take effect, the working directory after entering a worktree,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {

package/skills/blackboard/SKILL.md

@@ -15,21 +15,29 @@ subagent-identity rules.
 
 Journal operations are tools of the `vouchington-tooling` MCP server (`vouchington mcp`):
 `journal_append`, `journal_entries`, `outbox_status`, `outbox_flush`, `session_ensure`,
-`snapshot_export`, and `session_archive`. A harness may prefix the tool names with the server name.
+`snapshot_export`, and `session_archive`. Harnesses name them differently, so match the bare tool
+name: `mcp__vouchington-tooling__<tool>`, `mcp__vouchington_tooling__<tool>` (the hyphen becomes an
+underscore), or `vouchington-tooling__<tool>` reached through a `search_tool` and `use_tool` pair,
+or the `vouchington-tooling` namespace reached through `GetDynamicTools` and `CallDynamicTool`.
 Every call takes an exact `sessionId`, never inferred, whose meaning depends on the tool:
 
 - `journal_append` and `session_ensure`: the session written or ensured, which is the caller's own
   session unless a runner ensures a child identity.
 - `journal_entries` and `session_archive`: the session read or archived, which during distillation
   belongs to another agent.
-- `snapshot_export`, `outbox_status`, and `outbox_flush`: only the caller. The outbox tools cover
-  every record in the worktree outbox, not only that session's.
+- `snapshot_export`, `outbox_status`, and `outbox_flush`: only the caller. The outbox is per
+  worktree, so `outbox_status` and `outbox_flush` report two counts: `pendingCount` is the unsent
+  records of that `sessionId`, and `worktreePendingCount` is the unsent records of every session in
+  the worktree outbox. `outbox_flush` delivers every retained record in the worktree.
 
 Every call may take `worktree`, the absolute path of a worktree of the current repository (the
 launch worktree by default). Writing or retrying an entry needs no provider skill, temporary file,
 `--file` flag, or replay command.
-If these tools are not available because the server is not registered or not connected, stop and
-report that the journal server is unavailable. Do not fall back to a CLI 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.
 
 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
@@ -40,11 +48,10 @@ report that the journal server is unavailable. Do not fall back to a CLI command
 2. Record each observation with one `journal_append` call and pass the note as its `markdown`
    argument (at most 12000 bytes). Required arguments are `sessionId`, `parentSessionId` (null for a
    root session), `agent`, `version`, `mode`, `markdown`, a stable `sourceEventId`, `workOutcome`,
-   canonical exact `repositories`, and explicit `feedbackCoverage`. Also pass an ISO 8601
-   `timestamp` fixed before the first attempt: the server otherwise generates one, and a failed or
-   timed-out call returns no result to learn it from. Nothing is written unless the
-   whole envelope validates. The tool writes journal entries; `category` is optional context and
-   never changes storage type or distillation eligibility. Generate routine facts and metadata
+   canonical exact `repositories`, and explicit `feedbackCoverage`. Never pass a `timestamp`: the
+   server owns it, rejects the argument, and returns the timestamp it used. Nothing is written
+   unless the whole envelope validates. The tool writes journal entries; `category` is optional
+   context and never changes storage type or distillation eligibility. Generate routine facts and metadata
    through the approved composer and pass its output as `markdown` instead of hand-authoring
    factual markers. `journal_append` stores only journal entries: save a composed retrospective
    through the retrospective skill's writer, never through `journal_append`.
@@ -55,10 +62,11 @@ report that the journal server is unavailable. Do not fall back to a CLI command
    the exact identity only when a runner must confirm the session before work starts.
 4. Select the repository's trusted `mode` (`interactive` or `autonomous`) explicitly. In interactive
    mode an outage may retain the validated, sanitized record in the bounded durable outbox, and
-   `journal_append` reports it as pending. Report the pending count from `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 capture; never evict or
-   silently discard an unsent record.
+   `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
+   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`
    unique to that attempt: reusing an earlier one returns the earlier receipt, which does not
@@ -66,9 +74,11 @@ report that the journal server is unavailable. Do not fall back to a CLI command
    Terminal reporting preserves work outcome separately from feedback coverage and delivery. A
    filesystem outbox never grants admission or acknowledged completion.
 6. Use at-least-once delivery with consumer deduplication by exact session/source identity. To
-   retry a pending or failed append, call `journal_append` again with the same `sourceEventId`,
-   content, and `timestamp` from the first attempt: the whole envelope must match, and conflicting
-   source reuse is rejected. A transport timeout can leave a late
+   retry a pending or failed append, repeat the identical `journal_append` call with the same
+   `sourceEventId` and content. The server's timestamp is not part of an event's identity, so a
+   retry of an event already stored or retained reports the stored timestamp, even after a restart
+   or an outage. The same `sourceEventId` with different content is rejected as a conflict, so use
+   a new `sourceEventId` for a changed note. A transport timeout can leave a late
    durable write; pending or blocked is never an acknowledged receipt.
 7. Read the session's entries oldest-first with `journal_entries` for retrospectives. It returns
    every entry with its envelope, including its type and repository tags, so a retrospective can

package/skills/manifest.json

@@ -4,7 +4,7 @@
     {
       "name": "agent-workflow",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "agent-workflow/SKILL.md",
       "prerequisites": ["github-issue", "pr-description", "review-ci-logs"]
     },
@@ -18,13 +18,13 @@
     {
       "name": "blackboard",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "blackboard/SKILL.md"
     },
     {
       "name": "dependabot",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "dependabot/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
@@ -38,26 +38,26 @@
     {
       "name": "git-commit-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "git-commit-checklist/SKILL.md"
     },
     {
       "name": "github-actions-authoring",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "github-actions-authoring/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
     {
       "name": "github-actions-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "github-actions-checklist/SKILL.md"
     },
     {
       "name": "github-issue",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "github-issue/SKILL.md"
     },
     {
@@ -70,26 +70,26 @@
     {
       "name": "npm-publishing",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "npm-publishing/SKILL.md"
     },
     {
       "name": "organize-github-issues",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "organize-github-issues/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "package-json-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "package-json-checklist/SKILL.md"
     },
     {
       "name": "planning",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "planning/SKILL.md",
       "prerequisites": ["github-issue"]
     },
@@ -103,65 +103,71 @@
     {
       "name": "postgres-node-performance-tuning",
       "plugin": "vouchington-database",
-      "pluginVersion": "0.2.0",
+      "pluginVersion": "0.3.0",
       "path": "postgres-node-performance-tuning/SKILL.md"
     },
     {
       "name": "postgres-partitioning-uuid-v7",
       "plugin": "vouchington-database",
-      "pluginVersion": "0.2.0",
+      "pluginVersion": "0.3.0",
       "path": "postgres-partitioning-uuid-v7/SKILL.md"
     },
+    {
+      "name": "postgres-schema-design",
+      "plugin": "vouchington-database",
+      "pluginVersion": "0.3.0",
+      "path": "postgres-schema-design/SKILL.md"
+    },
     {
       "name": "pr-description",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "pr-description/SKILL.md"
     },
     {
       "name": "retrospective",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "retrospective/SKILL.md"
     },
     {
       "name": "retrospective-distill",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "retrospective-distill/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "review-ci-logs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "review-ci-logs/SKILL.md",
       "prerequisites": ["github-actions-checklist", "pr-description"]
     },
     {
       "name": "review-github-issue-taxonomy",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "review-github-issue-taxonomy/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "revisit-followups",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "revisit-followups/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "stacked-prs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "stacked-prs/SKILL.md"
     },
     {
       "name": "static-analysis-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "static-analysis-checklist/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },

package/skills/postgres-node-performance-tuning/references/performance-patterns.md

@@ -12,3 +12,25 @@ Check query predicates, joins, ordering, and selected columns against index shap
 evidence to confirm planner behavior. Add extended statistics only when observed estimates show a
 correlation problem; verify the statistics are collected and used. Partitioning can reduce scanned
 data, but it does not replace suitable local indexes or predicates that permit pruning.
+
+## Query shapes
+
+Test existence with `EXISTS`, not `COUNT(*) > 0`. Use correlated `NOT EXISTS` rather than
+`NOT IN (SELECT ...)`, whose NULL behavior can silently exclude expected rows. Filter and order
+UUIDv7 rows by `id`, not generated `created_at`, so the key's index supports the query.
+Read and return tables with explicit columns: no `SELECT *`, `alias.*`, or `RETURNING *`.
+A view may use `*` when its reviewed column list is the reader contract.
+
+Use keyset pagination, never `OFFSET`. An optimizer fence is a `MATERIALIZED` CTE, not
+`OFFSET 0`. Constrain a partitioned table's partition key, or document the reason for a
+cross-partition query. Choose the partition key from dominant access patterns; a hot reader
+of `RANGE (id)` needs an id or time bound.
+
+A UUIDv7 child cannot predate its parent. For a `RANGE (id)` child read by parent id, use a
+shared lower-bound helper equivalent to
+`id >= min_uuidv7(uuid_extract_timestamp(parent_id) - interval '1 hour')` to prune earlier
+partitions; the overlap allows clock skew. Rate limits query an actor-keyed table rather than
+recipient-keyed fan-out rows. Verify actual pruning with EXPLAIN.
+
+Generic `jonathanong/no-mistakes` checks include `postgres-no-offset`; inspect available rules
+and configure reviewed cross-partition exceptions rather than treating a rule as plan evidence.

package/skills/postgres-partitioning-uuid-v7/SKILL.md

@@ -9,6 +9,9 @@ Read applicable `AGENTS.md` and their declared adapter alias, otherwise
 `.agents/skills/postgres-partitioning-uuid-v7/SKILL.md` from the repository root if present.
 Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
 
+For schema names, references, and canonical table shapes, read
+[postgres-schema-design](../postgres-schema-design/SKILL.md).
+
 Partition only after lifecycle, retention, and query predicates show that it helps.
 
 - Treat a UUIDv7 as time ordered. Where the meaning matters, keep an explicit business timestamp.

package/skills/postgres-schema-design/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: postgres-schema-design
+description: Design PostgreSQL names, relations, history, work queues, and cursors.
+---
+
+# PostgreSQL schema design
+
+Read applicable `AGENTS.md` and the repository's local database adapter when present.
+Local policy overrides these portable conventions.
+
+- Names explain the stored thing; read [naming](references/naming.md) when naming schema objects.
+- Columns say their type and FK target; finite sets use enums or lookup tables.
+- Joined identities use foreign keys; read [relations](references/relations.md) before modeling references.
+- Split differing shapes, share identical values, and keep history documents as JSON.
+- Use canonical [table shapes](references/table-shapes.md) for revisions, changes, work, and cursors.
+- Reuse parameterized trigger functions instead of copying bodies.
+- Comment every table, column, and view; document reviewed exceptions explicitly.
+
+For query shape, read [performance patterns](../postgres-node-performance-tuning/references/performance-patterns.md).
+For partition lifecycle, use [UUIDv7 partitioning](../postgres-partitioning-uuid-v7/SKILL.md).
+Consumer policy owns lifecycle, retention, migration strategy, and enforcement configuration.

package/skills/postgres-schema-design/references/naming.md

@@ -0,0 +1,34 @@
+# Naming
+
+Use full words in snake_case. Tables read as `<owner>_<thing>s`, with only the last word
+plural: `account_payment_methods`, not `accounts_payments_methods`. Core entities may use one
+word (`accounts`, `orders`, `invoices`) when local policy permits it. Enum names follow the same
+plural convention. Choose a shorter full-word name when a base identifier would exceed 63 bytes.
+
+Indexes use `idx_<table>__<suffix>`; a unique index may use `uq_`. The suffix describes its
+purpose or keys. The table portion may abbreviate only when it expands unambiguously to the
+indexed table: preserve every word, its order, and separators. Each shortened word keeps its
+first letter and at least three letters in their original order; words of three or fewer letters
+stay whole. `idx_ord_line_itms__invoice_id` can name an index on `order_line_items`.
+Initialisms and dropped words cannot. All identifiers stay within 63 bytes.
+
+Column names and types imply each other:
+
+- `timestamptz` ends in `_at`; dates use `day` or `_on`.
+- Booleans contain a predicate prefix `is_`, `has_`, `can_`, or `should_` at a word boundary.
+- FK columns end in the target's final word, singular: `invoice_id` references `invoices`.
+  Drop redundant owner words when the column's table already supplies them.
+- A column referencing a natural key may use that key's name. A retained identity reference
+  keeps the entity's name even though the retained table ends in `identities`.
+- Reserve `_user_id` and actor `_by_id` for references to users or retained user identities.
+  Adapt the actor convention to the repository's account model; never use an actor suffix for
+  an unrelated FK or an opaque token.
+
+Trigger functions use `fn_<verb>_<what>` with this closed verb list:
+`reject` (raise on invalid writes), `update` (set the current row), `project` (derived state in
+other rows), `create` (companion rows), `lock`, `register`, and `ensure` (retained identity).
+Ordinary functions use a name that explains their return value.
+
+Generic enforcement: `postgres-object-naming`, `postgres-column-naming`, and
+`postgres-identifier-length` in `jonathanong/no-mistakes`. Check the installed rule's supported options before enabling it;
+an upstream rule name does not establish that the installed release includes it.

package/skills/postgres-schema-design/references/relations.md

@@ -0,0 +1,46 @@
+# Relations
+
+An identity that readers join is an FK column or an FK child row. JSON holds structured,
+schemaless data and history snapshots, including identities recorded as they were at the time.
+Do not use UUID arrays, JSON ids, or type/id pairs for live relations. A column never names a
+table: use one table per target and generate any per-relation progress enum from the same metadata.
+Cursor positions and random fencing tokens are intentionally not live entity references; record
+their reviewed exception instead of inventing a foreign key.
+
+Split tables when their columns or FK targets differ; share a table when only a value differs.
+Identical lookup values share a row without a source discriminator. Put subtype-only columns in
+a subtype table whose primary key also references the base row (`business_accounts.account_id`
+references `accounts.id`). A 1:N child remains an ordinary child table.
+
+For one of several sources, use an exclusive arc:
+
+```sql
+CHECK (num_nonnulls(order_id, invoice_id) = 1)
+```
+
+Both source columns have their own FK. If a reference must belong to the same account, enforce
+`FOREIGN KEY (account_id, invoice_id) REFERENCES invoices (account_id, id)` with a corresponding
+unique key on the target. A validation trigger is unnecessary. With nullable `invoice_id`,
+default `MATCH SIMPLE` skips that composite check when the reference is absent.
+
+A ledger that survives deletion references a retained identity row with explicit deletion
+behavior. Retained identities preserve history; they do not authorize operations on a deleted
+account, order, or invoice. Index FK columns with a leading key usable by referential checks.
+
+Finite code-defined values use enums. Use a lookup table when values carry attributes or arrive
+at runtime. Authenticated vendor-defined values are inserted into a shared lookup on first sight,
+with validation and concurrent insertion handled explicitly. Do not let untrusted strangers
+create unbounded permanent lookup rows; reviewed raw text can be appropriate for their input.
+Free text and a lookup's own natural key are not finite sets.
+
+Arrays are for enums or outside-defined lists; live identity collections use FK child rows,
+never `uuid[]`. User-submitted URLs go through one registry with centralized normalization and
+validation, then use URL FKs. Keep exact external protocol identifiers, capability URLs, and
+evidence snapshots unchanged when their contract requires it; document the exception.
+Do not duplicate a child collection into a parent column unless a trigger maintains the projection.
+
+Generic enforcement in `jonathanong/no-mistakes`: `postgres-column-naming`,
+`postgres-array-columns`, `postgres-table-shape`, `postgres-fk-index`, and
+`postgres-require-fk-on-delete`. These cover naming, configured shapes, and FK mechanics;
+inspect the installed rule versions and options rather than assuming complete semantic coverage.
+Comments and reviewed exceptions remain necessary.

package/skills/postgres-schema-design/references/table-shapes.md

@@ -0,0 +1,56 @@
+# Table shapes
+
+Choose a shape by lifecycle and meaning. Do not store hand-synchronized status beside lifecycle
+timestamps. A final lifecycle derives enum status with an immutable generated expression over
+timestamps such as `claimed_at`, `completed_at`, and `failed_at`. A time-based expiry needs an
+explicit sweeper-written timestamp; `now()` cannot appear in an immutable generated expression.
+When state keeps returning to earlier states, record append-only attempts or changes and derive
+current state from the latest row rather than erasing the previous lifecycle.
+
+| Concept                    | Shape                                                                                                                                                                                      |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Field-diff history         | `<entity>_revisions`: UUIDv7 `id`, entity FK, nullable revision actor FK with `ON DELETE SET NULL`, revision-type enum, `changes jsonb`.                                                   |
+| Typed lifecycle ledger     | `<entity>_changes`: UUIDv7 `id`, entity FK, change-type enum, retained actor identity FK with `ON DELETE RESTRICT`, typed joined payload and JSON for unjoined data. Time comes from `id`. |
+| Current state from a log   | Latest change by `id DESC`, projected through a shared trigger or read through a view.                                                                                                     |
+| Per-entity work            | `<entity>_<job>_work_items`: entity FK, lease and final-outcome columns, claim index, retention.                                                                                           |
+| Job progress               | `<job>_cursors`: finite enum key or checked singleton, keyset positions without FKs, optional sweep upper bound.                                                                           |
+| Inbound or protocol events | Append-only `<source>_events` with `occurred_at` recording the event's business time.                                                                                                      |
+
+Revisions and changes are append-only through a generic `fn_reject_mutation`, parameterized by
+actor columns that may be erased to NULL. Permit only those erasures; parent-cascade deletion
+may be permitted by policy. A trigger-depth test alone cannot prove a delete came from a parent
+cascade, because another trigger also increases depth. Do not copy the parent into each ledger
+row. Keep historical before/after snapshots as JSON rather than joined history child tables.
+A system change has a NULL actor. Retained actors remain historical identities, without authority.
+
+## Work leases
+
+The lease lives on a row that exists only for the work. If an invoice outlives a delivery job,
+use `invoice_delivery_work_items`, with an invoice FK and `ON DELETE CASCADE`, rather than putting
+the lease on the invoice. Do not create a shared polymorphic lease table.
+
+Use `lease_token uuid`, `leased_at`, `lease_expires_at`, `attempt_count`, `available_at`, and
+`completed_at` plus timestamps for final outcomes. Add `generation` only when re-enqueue can race
+a running worker. Each claim or reclaim gets a fresh opaque token. Every renewal, completion,
+and failure must include `WHERE lease_token = $mine`; zero affected rows means ownership was lost.
+Keep retries in an optional `_attempts` ledger with `attempt_number` when their lifecycle must
+survive. One-shot compare-and-set claims and human assignments need their own shapes.
+
+## Cursors and shared functions
+
+A cursor key names the finite thing being swept. A singleton uses
+`is_singleton boolean PRIMARY KEY DEFAULT true CHECK (is_singleton)`; the job seeds its own row
+with `ON CONFLICT DO NOTHING`. `cursor_<thing>_id` and optional `sweep_upper_bound_<thing>_id` are
+FK-free UUIDv7 positions; NULL means the start. Per-unit work progress belongs in work items.
+A UUIDv7 is assigned at insert, not commit: jobs that must see every committed row re-scan an
+overlap rather than assuming an id high-water mark proves commit order.
+
+Use `updated_at` only for mutable rows, always maintained by its trigger; application code never
+writes it. Comment every table, column, and view, including generated objects. Self-explanatory
+columns may have explicit reviewed local exceptions; view comments describe their reader boundary.
+Reuse generic trigger functions with `TG_ARGV` and `TG_TABLE_NAME`; quote dynamic identifiers
+with `format('%I', ...)`. A trigger function and a SQL-callable helper are separate functions.
+
+Generic enforcement in `jonathanong/no-mistakes`: `postgres-table-shape` and
+`postgres-duplicate-function-body`. Configure canonical shapes explicitly and verify which
+rules the installed release supports; lifecycle and authority decisions still need review.

package/skills/retrospective-distill/SKILL.md

@@ -17,11 +17,15 @@ Use when completed retrospectives or journals should become durable follow-up wo
    `data` fields, `dataArrayContains`, and `inactiveForHours`. It exports non-archived sessions to a
    private local file and returns the path, counts, checksum, and manifest, never the records.
    Before exporting, call `outbox_flush` and then `outbox_status` for every worktree that
-   `git worktree list` reports, passing each path as `worktree`, and stop if any still reports
-   pending records: an archived session refuses later delivery, so a retained record would never
-   be distilled. Outboxes in removed worktrees or on other machines cannot be drained this way, so
-   select with `inactiveForHours` to give them time to deliver. Leave in-progress sessions intact.
-   If the server is not connected, stop and report it; do not fall back to a CLI command.
+   `git worktree list` reports, passing each path as `worktree`, and stop if any reports a
+   `worktreePendingCount` above 0. Use the worktree count, never `pendingCount` or `status`, which
+   cover only the caller's own session: the sessions to distill belong to other agents, and an
+   archived session refuses later delivery, so a retained record would never be distilled. Outboxes
+   in removed worktrees or on other machines cannot be drained this way, so select with
+   `inactiveForHours` to give them time to deliver. Leave in-progress sessions intact. If a search
+   for `snapshot_export` (the tool names carry a harness prefix, see the
+   [blackboard skill](../blackboard/SKILL.md)) finds no server, stop and report it; do not fall back
+   to a CLI command.
 2. Before using any record, verify the file against the returned checksum, counts, and terminal
    manifest with the consumer's approved snapshot reader, and stop on a mismatch rather than
    treating missing records as absent. Read full records, with their storage type, repository
@@ -34,7 +38,8 @@ Use when completed retrospectives or journals should become durable follow-up wo
 3. Validate storage type and the shared envelope independently of optional category. Never repair
    unknown legacy types or repository provenance by inference. Quarantine malformed sessions with
    an explicit reason while processing valid unrelated sessions. Deduplicate at-least-once records
-   by exact session/source identity and reject conflicting duplicate content. Retain coverage,
+   by exact session/source identity and reject conflicting duplicate content. Records that differ
+   only in their server-assigned `timestamp` are one event. Retain coverage,
    dropped counts, requested versus observed outcomes, and useful resolved findings.
 4. Cluster findings by root cause. Prefer a few broad actionable themes over many narrow issues.
    Treat a finding already linked to an open tracker as context, not a duplicate.
@@ -47,8 +52,8 @@ Use when completed retrospectives or journals should become durable follow-up wo
    [github-issue](../github-issue/SKILL.md), including its repository gate, label approval, and
    denied-external tracking behavior.
 7. Archive only verified records fully processed across every represented repository, and never
-   while any worktree's `outbox_status` reports pending records, under the repository's retention
-   rules. Make one `session_archive` call per session, whose `sessionId` is the archived session,
+   while any worktree's `outbox_status` reports a `worktreePendingCount` above 0, under the
+   repository's retention rules. Make one `session_archive` call per session, whose `sessionId` is the archived session,
    not the caller. Immediately before each call, read that session with `journal_entries` and
    archive only if its entries match the verified snapshot's by source identity; otherwise leave it
    for the next pass, because an entry added after the export would never be distilled.