vouchington-tooling 0.25.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/context.d.mts

@@ -8,8 +8,7 @@ type ToolContext = {
     env: NodeJS.ProcessEnv;
     dependencies: BlackboardClientDependencies;
 };
-type ToolResult = string | Record<string, unknown>;
-export type ToolHandler = (args: Args, context: ToolContext) => Promise<ToolResult>;
+export type ToolHandler = (args: Args, context: ToolContext) => Promise<Record<string, unknown>>;
 /**
  * The consumer convention for the interactive outbox. It is derived, never accepted from the
  * caller, so a credentialed, unsandboxed server cannot be pointed at an arbitrary directory.

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)
@@ -54,14 +55,7 @@ export async function callTool(name, rawArguments, environment) {
             // The client resolves from the validated worktree, never from the server's own location.
             dependencies: { ...environment.blackboard, resolveFrom: join(worktree, 'package.json') },
         });
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
-                },
-            ],
-        };
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     }
     catch (error) {
         return { isError: true, content: [{ type: 'text', text: describeError(error) }] };

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

@@ -4,6 +4,7 @@ export declare const BLACKBOARD_ENV: {
     AGENT_BLACKBOARD_TOKEN: string;
 };
 type StoredEntry = {
+    sessionId?: string;
     createdAt: string;
     data: unknown;
 };
@@ -21,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;
@@ -28,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

@@ -1,5 +1,4 @@
 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, formatJournalEntries, 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,43 +40,51 @@ 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 };
 };
-export const journalEntries = async (_args, context) => formatJournalEntries(context.sessionId, await readJournal(context.sessionId, context.env, context.dependencies));
-export const outboxStatus = async (_args, context) => ({
+// `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.
+function createdAtOf(entry) {
+    const createdAt = entry?.createdAt;
+    return typeof createdAt === 'string' ? createdAt : '';
+}
+function byCreatedAt(left, right) {
+    const leftAt = createdAtOf(left);
+    const rightAt = createdAtOf(right);
+    if (leftAt === rightAt)
+        return 0;
+    return leftAt < rightAt ? -1 : 1;
+}
+/** Every entry as the client returns it, oldest first. Nothing is filtered or rewritten. */
+export const journalEntries = async (_args, context) => ({
     sessionId: context.sessionId,
-    ...feedbackOutboxStatus(outboxDirectory(context.worktree)),
+    entries: (await readJournal(context.sessionId, context.env, context.dependencies)).toSorted(byCreatedAt),
 });
-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,
@@ -97,11 +98,14 @@ export const TOOLS = [
         'repositories',
         'feedbackCoverage',
     ]),
-    tool('journal_entries', 'Returns the journal entries of one session, oldest first, as markdown.', 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('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 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