vouchington-tooling 3.0.1 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/dist/agent-blackboard/feedback-delivery.d.mts +11 -4
  2. package/dist/agent-blackboard/feedback-delivery.mjs +22 -5
  3. package/dist/agent-blackboard/feedback-failure-parse.d.mts +3 -0
  4. package/dist/agent-blackboard/feedback-failure-parse.mjs +39 -0
  5. package/dist/agent-blackboard/feedback-failure.d.mts +32 -0
  6. package/dist/agent-blackboard/feedback-failure.mjs +48 -0
  7. package/dist/agent-blackboard/feedback-online-error.d.mts +5 -1
  8. package/dist/agent-blackboard/feedback-online-error.mjs +8 -1
  9. package/dist/agent-blackboard/feedback-online.mjs +3 -2
  10. package/dist/agent-blackboard/feedback-outbox-failure.d.mts +16 -0
  11. package/dist/agent-blackboard/feedback-outbox-failure.mjs +41 -0
  12. package/dist/agent-blackboard/feedback-outbox-read.d.mts +11 -0
  13. package/dist/agent-blackboard/feedback-outbox-read.mjs +33 -0
  14. package/dist/agent-blackboard/feedback-outbox-rejected.d.mts +14 -5
  15. package/dist/agent-blackboard/feedback-outbox-rejected.mjs +45 -19
  16. package/dist/agent-blackboard/feedback-outbox-write.d.mts +2 -0
  17. package/dist/agent-blackboard/feedback-outbox-write.mjs +26 -0
  18. package/dist/agent-blackboard/feedback-outbox.d.mts +2 -7
  19. package/dist/agent-blackboard/feedback-outbox.mjs +7 -52
  20. package/dist/agent-blackboard/feedback-types.d.mts +1 -1
  21. package/dist/agent-blackboard/index.d.mts +2 -0
  22. package/dist/agent-blackboard/index.mjs +2 -0
  23. package/dist/host-lock/with-host-lock-diagnostics.test-helpers.d.mts +10 -0
  24. package/dist/host-lock/with-host-lock-diagnostics.test-helpers.mjs +27 -0
  25. package/dist/host-lock/with-host-lock.test-helpers.d.mts +0 -10
  26. package/dist/host-lock/with-host-lock.test-helpers.mjs +7 -28
  27. package/dist/mcp-server/dispatch.mjs +3 -1
  28. package/dist/mcp-server/handlers-outbox.d.mts +1 -0
  29. package/dist/mcp-server/handlers-outbox.mjs +31 -2
  30. package/dist/mcp-server/tools-outbox.d.mts +2 -0
  31. package/dist/mcp-server/tools-outbox.mjs +31 -0
  32. package/dist/mcp-server/tools.mjs +2 -8
  33. package/docs/mcp-server.md +28 -15
  34. package/package.json +1 -1
  35. package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
  36. package/skills/blackboard/SKILL.md +10 -1
  37. package/skills/manifest.json +9 -9
  38. package/skills/retrospective-distill/SKILL.md +3 -1
  39. package/skills/triage-loop/SKILL.md +71 -21
  40. package/skills/triage-sweep/SKILL.md +32 -11
@@ -37,7 +37,7 @@ export type FeedbackReceipt = {
37
37
  /** Set when the session already stored a different `version`; the entry was delivered into it. */
38
38
  storedVersion?: string;
39
39
  };
40
- export type FeedbackDiagnostic = 'blackboard-unavailable' | 'client-unavailable' | 'configuration-invalid' | 'authentication-rejected' | 'identity-conflict' | 'readback-unconfirmed' | 'event-conflict' | 'archived-session' | 'delivery-timeout';
40
+ export type FeedbackDiagnostic = 'blackboard-unavailable' | 'client-unavailable' | 'configuration-invalid' | 'authentication-rejected' | 'identity-conflict' | 'readback-unconfirmed' | 'event-conflict' | 'archived-session' | 'delivery-timeout' | 'delivery-quarantined';
41
41
  export type FeedbackDeliveryResult = {
42
42
  status: 'delivered';
43
43
  sourceEventId: string;
@@ -21,6 +21,8 @@ export type * from './feedback-types.mts';
21
21
  export { createFeedbackEnvelope, validateFeedbackEnvelope } from './feedback-codec.mts';
22
22
  export { writeFeedback, verifyFreshFeedback, flushFeedbackOutbox, FeedbackDeliveryError, } from './feedback-delivery.mts';
23
23
  export { feedbackOutboxStatus, readFeedbackOutbox } from './feedback-outbox.mts';
24
+ export { readFeedbackFailures } from './feedback-outbox-failure.mts';
25
+ export { pruneRejectedFeedbackOutbox, readRejectedDetails } from './feedback-outbox-rejected.mts';
24
26
  export { composeRetrospective } from './feedback-compose.mts';
25
27
  export type { RetrospectiveCompositionInput, FeedbackAssessment } from './feedback-compose.mts';
26
28
  export type { JournalAuditOptions } from './feedback-journal-audit.mts';
@@ -40,5 +40,7 @@ export { BlackboardNotInstalledError, resolveBlackboardConnection } from "./clie
40
40
  export { createFeedbackEnvelope, validateFeedbackEnvelope } from "./feedback-codec.mjs";
41
41
  export { writeFeedback, verifyFreshFeedback, flushFeedbackOutbox, FeedbackDeliveryError, } from "./feedback-delivery.mjs";
42
42
  export { feedbackOutboxStatus, readFeedbackOutbox } from "./feedback-outbox.mjs";
43
+ export { readFeedbackFailures } from "./feedback-outbox-failure.mjs";
44
+ export { pruneRejectedFeedbackOutbox, readRejectedDetails } from "./feedback-outbox-rejected.mjs";
43
45
  export { composeRetrospective } from "./feedback-compose.mjs";
44
46
  export { feedbackOutboxCounts } from "./feedback-outbox-counts.mjs";
@@ -0,0 +1,10 @@
1
+ type Completion = {
2
+ code: number | null;
3
+ stderr: string;
4
+ };
5
+ export declare function assertWithLockDiagnostics({ lockRoot, lockName, guard }: {
6
+ lockRoot: string;
7
+ lockName: string;
8
+ guard: string;
9
+ }, results: Completion[], assertion: () => void): Promise<void>;
10
+ export {};
@@ -0,0 +1,27 @@
1
+ import { readdir, stat } from 'node:fs/promises';
2
+ async function describePath(path) {
3
+ try {
4
+ await stat(path);
5
+ }
6
+ catch {
7
+ return 'absent';
8
+ }
9
+ const entries = await readdir(path).catch(() => undefined);
10
+ return entries === undefined ? 'present' : `present [${entries.join(', ')}]`;
11
+ }
12
+ // On failure, rethrows with the lock dir, guard, and both wrappers' exit codes
13
+ // and stderr so a recurrence of an overlapping-holders flake names the cause.
14
+ export async function assertWithLockDiagnostics({ lockRoot, lockName, guard }, results, assertion) {
15
+ try {
16
+ assertion();
17
+ }
18
+ catch (error) {
19
+ const diagnostics = [
20
+ `lock dir ${lockRoot}/${lockName}.lock.d: ${await describePath(`${lockRoot}/${lockName}.lock.d`)}`,
21
+ `reap dir: ${await describePath(`${lockRoot}/${lockName}.lock.reap.d`)}`,
22
+ `guard ${guard}: ${await describePath(guard)}`,
23
+ ...results.map((result, index) => `wrapper ${index + 1}: code=${result.code} stderr=${JSON.stringify(result.stderr)}`),
24
+ ];
25
+ throw new Error(`${String(error)}\n${diagnostics.join('\n')}`, { cause: error });
26
+ }
27
+ }
@@ -19,13 +19,3 @@ export declare function withFinalTimeoutProbe(home: string, assertProbe: ({ lock
19
19
  stderr: string;
20
20
  }>;
21
21
  }) => Promise<void>): Promise<void>;
22
- type Completion = {
23
- code: number | null;
24
- stderr: string;
25
- };
26
- export declare function assertWithLockDiagnostics({ lockRoot, lockName, guard }: {
27
- lockRoot: string;
28
- lockName: string;
29
- guard: string;
30
- }, results: Completion[], assertion: () => void): Promise<void>;
31
- export {};
@@ -1,5 +1,5 @@
1
1
  import { execFile, spawn } from 'node:child_process';
2
- import { mkdtemp, mkdir, readdir, rm, stat, writeFile } from 'node:fs/promises';
2
+ import { mkdtemp, mkdir, rm, stat, writeFile } from 'node:fs/promises';
3
3
  import { tmpdir } from 'node:os';
4
4
  import { join } from 'node:path';
5
5
  import { promisify } from 'node:util';
@@ -40,6 +40,11 @@ export function spawnHostLock(home, name, timeoutSeconds, command, env = {}, ext
40
40
  stdio: ['ignore', 'pipe', 'pipe'],
41
41
  });
42
42
  }
43
+ // macOS Bash 3.2 (`set -m`) can race the parent and forked child both calling
44
+ // setpgid under CPU load and print this warning. The process group is still
45
+ // established by the winner, and the warning is owned by the shell, not by
46
+ // with-host-lock, so assertions on the wrapper's own stderr drop it.
47
+ const benignJobControlWarning = /^.*: (?:child )?setpgid \(\d+ to \d+\): Operation not permitted\n/gm;
43
48
  export function completion(child) {
44
49
  return new Promise((resolve, reject) => {
45
50
  let stderr = '';
@@ -47,7 +52,7 @@ export function completion(child) {
47
52
  stderr += String(chunk);
48
53
  });
49
54
  child.once('error', reject);
50
- child.once('close', (code) => resolve({ code, stderr }));
55
+ child.once('close', (code) => resolve({ code, stderr: stderr.replace(benignJobControlWarning, '') }));
51
56
  });
52
57
  }
53
58
  export async function waitForPath(path) {
@@ -122,29 +127,3 @@ exec "$HOST_LOCK_REAL_SLEEP" "$@"
122
127
  await Promise.all([ownerDone, ...(contenderDone ? [contenderDone] : [])]);
123
128
  }
124
129
  }
125
- async function describePath(path) {
126
- try {
127
- await stat(path);
128
- }
129
- catch {
130
- return 'absent';
131
- }
132
- const entries = await readdir(path).catch(() => undefined);
133
- return entries === undefined ? 'present' : `present [${entries.join(', ')}]`;
134
- }
135
- // On failure, rethrows with the lock dir, guard, and both wrappers' exit codes
136
- // and stderr so a recurrence of an overlapping-holders flake names the cause.
137
- export async function assertWithLockDiagnostics({ lockRoot, lockName, guard }, results, assertion) {
138
- try {
139
- assertion();
140
- }
141
- catch (error) {
142
- const diagnostics = [
143
- `lock dir ${lockRoot}/${lockName}.lock.d: ${await describePath(`${lockRoot}/${lockName}.lock.d`)}`,
144
- `reap dir: ${await describePath(`${lockRoot}/${lockName}.lock.reap.d`)}`,
145
- `guard ${guard}: ${await describePath(guard)}`,
146
- ...results.map((result, index) => `wrapper ${index + 1}: code=${result.code} stderr=${JSON.stringify(result.stderr)}`),
147
- ];
148
- throw new Error(`${String(error)}\n${diagnostics.join('\n')}`, { cause: error });
149
- }
150
- }
@@ -4,7 +4,7 @@ import { readSessionId } from "./context.mjs";
4
4
  import { journalAppend, journalEntries } from "./handlers-journal.mjs";
5
5
  import { retrospectiveSave } from "./handlers-retrospective.mjs";
6
6
  import { retrospectiveCheck } from "./retrospective-check.mjs";
7
- import { outboxFlush, outboxStatus } from "./handlers-outbox.mjs";
7
+ import { outboxFlush, outboxPruneRejected, outboxStatus } from "./handlers-outbox.mjs";
8
8
  import { snapshotArchive } from "./handlers-snapshot-archive.mjs";
9
9
  import { snapshotCleanup } from "./handlers-snapshot-cleanup.mjs";
10
10
  import { snapshotPartition } from "./handlers-snapshot-partition.mjs";
@@ -21,6 +21,7 @@ const HANDLERS = {
21
21
  journal_entries: journalEntries,
22
22
  outbox_status: outboxStatus,
23
23
  outbox_flush: outboxFlush,
24
+ outbox_prune_rejected: outboxPruneRejected,
24
25
  session_ensure: sessionEnsure,
25
26
  retrospective_check: retrospectiveCheck,
26
27
  retrospective_save: retrospectiveSave,
@@ -43,6 +44,7 @@ const DIAGNOSTIC_HINTS = {
43
44
  'client-unavailable': 'agent-blackboard is not installed next to vouchington-tooling; if the install directory was removed, reinstall it first when it lives at a fixed path, then reconnect the server (`/mcp` in Claude Code, or restart Codex)',
44
45
  'readback-unconfirmed': 'the write could not be confirmed; retry the same call (same sourceEventId and content)',
45
46
  'delivery-timeout': 'delivery timed out; retry the same call (same sourceEventId and content)',
47
+ 'delivery-quarantined': 'delivery failed repeatedly and the record was moved to the rejected area',
46
48
  };
47
49
  function describeError(error) {
48
50
  if (error instanceof FeedbackDeliveryError)
@@ -9,4 +9,5 @@ export declare function outboxCounts(worktree: string, sessionId: string): {
9
9
  worktreePendingCount: number;
10
10
  };
11
11
  export declare const outboxStatus: ToolHandler;
12
+ export declare const outboxPruneRejected: ToolHandler;
12
13
  export declare const outboxFlush: ToolHandler;
@@ -1,4 +1,4 @@
1
- import { flushFeedbackOutbox, feedbackOutboxCounts } from "../agent-blackboard/index.mjs";
1
+ import { flushFeedbackOutbox, feedbackOutboxCounts, pruneRejectedFeedbackOutbox, readFeedbackFailures, readRejectedDetails, } from "../agent-blackboard/index.mjs";
2
2
  import { outboxDirectory } from "./context.mjs";
3
3
  /**
4
4
  * The outbox belongs to the worktree, not to one session, so two counts are reported. `pendingCount`
@@ -15,9 +15,38 @@ function statusCounts(worktree, sessionId) {
15
15
  function sessionStatus(pendingCount) {
16
16
  return pendingCount === 0 ? 'empty' : 'pending';
17
17
  }
18
+ /** Why each pending record last failed and why each kept record was rejected: causes only. */
19
+ function causes(worktree) {
20
+ const directory = outboxDirectory(worktree);
21
+ const failures = readFeedbackFailures(directory);
22
+ const rejected = readRejectedDetails(directory).map(({ record, rejection }) => ({
23
+ sourceEventId: record.envelope.sourceEventId,
24
+ ...rejection,
25
+ }));
26
+ return {
27
+ ...(failures.length === 0 ? {} : { failures }),
28
+ ...(rejected.length === 0 ? {} : { rejected }),
29
+ };
30
+ }
18
31
  export const outboxStatus = async (_args, context) => {
19
32
  const counts = statusCounts(context.worktree, context.sessionId);
20
- return { sessionId: context.sessionId, status: sessionStatus(counts.pendingCount), ...counts };
33
+ return {
34
+ sessionId: context.sessionId,
35
+ status: sessionStatus(counts.pendingCount),
36
+ ...counts,
37
+ ...causes(context.worktree),
38
+ };
39
+ };
40
+ export const outboxPruneRejected = async (args, context) => {
41
+ const days = args.olderThanDays ?? 7;
42
+ if (typeof days !== 'number' || !Number.isInteger(days) || days < 0)
43
+ throw new Error('olderThanDays must be a non-negative integer');
44
+ const prunedCount = pruneRejectedFeedbackOutbox(outboxDirectory(context.worktree), days);
45
+ return {
46
+ sessionId: context.sessionId,
47
+ prunedCount,
48
+ ...statusCounts(context.worktree, context.sessionId),
49
+ };
21
50
  };
22
51
  export const outboxFlush = async (_args, context) => {
23
52
  // Flushing creates the outbox directory, so an empty or absent outbox is reported as is.
@@ -0,0 +1,2 @@
1
+ import { type ToolDefinition } from './tools-schema.mts';
2
+ export declare const OUTBOX_TOOLS: readonly ToolDefinition[];
@@ -0,0 +1,31 @@
1
+ import { IDEMPOTENT_ADDITIVE, MUTATING, READ_ONLY, tool, } from "./tools-schema.mjs";
2
+ export const OUTBOX_TOOLS = [
3
+ tool('outbox_status', 'Reports unsent journal records in the worktree outbox. pendingCount and status (empty or ' +
4
+ 'pending) cover the caller sessionId only; worktreePendingCount covers every session. ' +
5
+ 'rejectedCount (and worktreeRejectedCount) counts permanently rejected records kept aside. ' +
6
+ 'failures lists each pending record that failed its last flush as sourceEventId, cause, ' +
7
+ 'optional httpStatus and code, and attempts; rejected lists each kept rejection with its ' +
8
+ 'stored diagnostic and cause. Causes are non-secret (network, timeout, http-5xx, ' +
9
+ 'http-4xx, missing-env:NAME, and similar), never a message, URL, or response body.', READ_ONLY),
10
+ tool('outbox_flush', 'Delivers every retained record in the worktree outbox, whichever session wrote it, and ' +
11
+ 'returns deliveredCount for the whole flush. pendingCount and status cover the remaining ' +
12
+ 'records of the caller sessionId; worktreePendingCount covers every session. ' +
13
+ 'A record with a permanent rejection moves to the rejected area and is listed in rejected ' +
14
+ 'as sourceEventId, diagnostic, and cause. A record that fails delivery on a non-transient, ' +
15
+ 'record-specific cause (a 4xx other than 401, 403, 408, or 429, or an unexpected error) on 5 ' +
16
+ 'consecutive flushes is quarantined into the rejected area with diagnostic ' +
17
+ 'delivery-quarantined, so it no longer counts as pending. Network errors, timeouts, 5xx, ' +
18
+ 'credential and environment faults stay pending. failures lists each record that failed ' +
19
+ 'this flush as sourceEventId, cause (network, http-5xx, missing-env:NAME, and similar, ' +
20
+ 'never a message or URL), optional httpStatus and code, and attempts. diagnostic stays ' +
21
+ 'the summary of the flush.', IDEMPOTENT_ADDITIVE),
22
+ tool('outbox_prune_rejected', 'Deletes rejected records (permanent rejections and quarantined records) from the worktree ' +
23
+ 'outbox that were last written at least olderThanDays days ago (default 7; 0 deletes ' +
24
+ 'all). Pending records are never touched. Returns prunedCount and the remaining counts.', MUTATING, {
25
+ olderThanDays: {
26
+ type: 'integer',
27
+ minimum: 0,
28
+ description: 'Minimum age in days of rejected records to delete (default 7).',
29
+ },
30
+ }),
31
+ ];
@@ -1,4 +1,5 @@
1
1
  import { ADDITIVE, AGENT, COVERAGE, IDEMPOTENT_ADDITIVE, IDENTITY, IDENTITY_REQUIRED, ID_PATTERN, MUTATING, OUTCOMES, PARENT_SESSION_ID, READ_ONLY, VERSION, tool, } from "./tools-schema.mjs";
2
+ import { OUTBOX_TOOLS } from "./tools-outbox.mjs";
2
3
  import { PR_TOOLS } from "./tools-pr.mjs";
3
4
  import { RETROSPECTIVE_TOOLS } from "./tools-retrospective.mjs";
4
5
  export const TOOLS = [
@@ -36,14 +37,7 @@ export const TOOLS = [
36
37
  tool('journal_entries', 'Returns every entry of one session, oldest first, as JSON: { sessionId, entries }. Each ' +
37
38
  'entry is exactly as the blackboard returns it ({ sessionId, createdAt, data }), including ' +
38
39
  'non-journal types such as retrospective and legacy entries without a feedback envelope.', READ_ONLY),
39
- tool('outbox_status', 'Reports unsent journal records in the worktree outbox. pendingCount and status (empty or ' +
40
- 'pending) cover the caller sessionId only; worktreePendingCount covers every session. ' +
41
- 'rejectedCount (and worktreeRejectedCount) counts permanently rejected records kept aside.', READ_ONLY),
42
- tool('outbox_flush', 'Delivers every retained record in the worktree outbox, whichever session wrote it, and ' +
43
- 'returns deliveredCount for the whole flush. pendingCount and status cover the remaining ' +
44
- 'records of the caller sessionId; worktreePendingCount covers every session. ' +
45
- 'A record with a permanent rejection moves to the rejected area and is listed in rejected ' +
46
- 'as sourceEventId and diagnostic.', IDEMPOTENT_ADDITIVE),
40
+ ...OUTBOX_TOOLS,
47
41
  tool('session_ensure', 'Idempotently creates a session, or verifies an existing one has the same identity. Child or ' +
48
42
  "worker sessions must pass their orchestrator's session id as parentSessionId.", IDEMPOTENT_ADDITIVE, IDENTITY, IDENTITY_REQUIRED),
49
43
  ...RETROSPECTIVE_TOOLS,
@@ -72,20 +72,21 @@ Every tool takes an explicit `sessionId` (`^[A-Za-z0-9._:-]+$`, at most 256 char
72
72
  server never infers, and an optional `worktree`. Unknown arguments are rejected. Failures come back
73
73
  as MCP tool errors (`isError: true`) with an actionable message rather than crashing the server.
74
74
 
75
- | Tool | Arguments besides `sessionId` and `worktree` | Returns |
76
- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
77
- | `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` |
78
- | `journal_entries` | none | `sessionId` and `entries`, every entry oldest first |
79
- | `outbox_status` | none | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount` |
80
- | `outbox_flush` | none | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`, `deliveredCount`, `rejected` (when any) |
81
- | `session_ensure` | `parentSessionId`, `agent`, `version` | `sessionId`, `status` (`created` or `exists`), `archived` |
82
- | `retrospective_check` | optional `sourceEventId` | `sessionId`, `saved`, `entries` (`sourceEventId`, `timestamp`, `issues`, `prs` of each retrospective, oldest first) |
83
- | `retrospective_save` | `parentSessionId`, `agent`, `version`, `mode`, `workOutcome`, `feedbackCoverage`, exactly one of `markdown` or `compose`, optional `repositories`, `sourceEventId`, `category`, `dryRun`, `knownSensitiveValues` (markdown only); or `previewToken` with identity, `mode` and `sourceEventId` | as `journal_append` plus `policy.warnings`; with `dryRun`, `markdown`, `previewToken` and `policy.warnings` |
84
- | `snapshot_export` | optional `agent`, `version`, `parentSessionId`, `data`, `dataArrayContains`, `inactiveForHours` | `sessionId`, `path`, `counts`, `checksum`, `manifest`, `cleanupToken` |
85
- | `snapshot_partition` | `cleanupToken`, optional `checksum`, `counts`, `maxSessions`, `maxBytes` | `sessionId`, `directory`, `partitions` (`path`, `counts`, `checksum`, `manifest` of each) |
86
- | `snapshot_archive` | `cleanupToken`, `sessionIds` (1 to 100) | `sessionId`, `archived`, `skipped` (`sessionId`, `reason`; never entry content) |
87
- | `snapshot_cleanup` | one of `cleanupToken` or `recoveryDirectory` | `sessionId`, `cleaned: true` |
88
- | `session_archive` | none | `sessionId`, `archived: true` |
75
+ | Tool | Arguments besides `sessionId` and `worktree` | Returns |
76
+ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
77
+ | `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` |
78
+ | `journal_entries` | none | `sessionId` and `entries`, every entry oldest first |
79
+ | `outbox_status` | none | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`, `failures` and `rejected` (when any) |
80
+ | `outbox_flush` | none | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`, `deliveredCount`, `rejected` and `failures` (when any) |
81
+ | `outbox_prune_rejected` | `olderThanDays` (integer, default 7; 0 prunes all) | `sessionId`, `prunedCount`, and the counts |
82
+ | `session_ensure` | `parentSessionId`, `agent`, `version` | `sessionId`, `status` (`created` or `exists`), `archived` |
83
+ | `retrospective_check` | optional `sourceEventId` | `sessionId`, `saved`, `entries` (`sourceEventId`, `timestamp`, `issues`, `prs` of each retrospective, oldest first) |
84
+ | `retrospective_save` | `parentSessionId`, `agent`, `version`, `mode`, `workOutcome`, `feedbackCoverage`, exactly one of `markdown` or `compose`, optional `repositories`, `sourceEventId`, `category`, `dryRun`, `knownSensitiveValues` (markdown only); or `previewToken` with identity, `mode` and `sourceEventId` | as `journal_append` plus `policy.warnings`; with `dryRun`, `markdown`, `previewToken` and `policy.warnings` |
85
+ | `snapshot_export` | optional `agent`, `version`, `parentSessionId`, `data`, `dataArrayContains`, `inactiveForHours` | `sessionId`, `path`, `counts`, `checksum`, `manifest`, `cleanupToken` |
86
+ | `snapshot_partition` | `cleanupToken`, optional `checksum`, `counts`, `maxSessions`, `maxBytes` | `sessionId`, `directory`, `partitions` (`path`, `counts`, `checksum`, `manifest` of each) |
87
+ | `snapshot_archive` | `cleanupToken`, `sessionIds` (1 to 100) | `sessionId`, `archived`, `skipped` (`sessionId`, `reason`; never entry content) |
88
+ | `snapshot_cleanup` | one of `cleanupToken` or `recoveryDirectory` | `sessionId`, `cleaned: true` |
89
+ | `session_archive` | none | `sessionId`, `archived: true` |
89
90
 
90
91
  `journal_append` validates the whole feedback envelope with `validateFeedbackEnvelope` before
91
92
  anything is written, so a missing required field writes nothing. It returns the verified read-back
@@ -134,7 +135,19 @@ worktree, whichever session wrote it, so its `deliveredCount` covers the whole f
134
135
  or during `outbox_flush`, moves the record out of the pending set into the outbox's rejected area,
135
136
  keeping its content. `rejectedCount` and `worktreeRejectedCount` report those records, and a
136
137
  corrected retry with the same `sourceEventId` is accepted. `outbox_flush` also returns
137
- `rejected: [{ sourceEventId, diagnostic }]` for what it moved. Flushing an empty
138
+ `rejected: [{ sourceEventId, diagnostic, cause }]` for what it moved, and the stored rejection keeps
139
+ that diagnostic and cause. A record that fails to deliver reports its non-secret cause, as
140
+ `failures: [{ sourceEventId, cause, httpStatus?, code?, attempts }]` on `outbox_flush` (this flush)
141
+ and `outbox_status` (the last failed flush of each pending record). `cause` is a closed vocabulary
142
+ (`network`, `timeout`, `http-5xx`, `http-4xx`, `http-401`, `http-403`, `http-408`, `http-429`,
143
+ `missing-env:<NAME>`, `invalid-url`, `client-unavailable`, `error:<ClassName>`), never a message,
144
+ URL, token, or response body; `diagnostic` stays the summary. A record that fails with the same
145
+ record-specific cause (`http-4xx` other than 401, 403, 408, 429, or `error:*`) on 5 consecutive
146
+ flushes is quarantined into the rejected area with diagnostic `delivery-quarantined`, so it no
147
+ longer counts as pending. Network errors, timeouts, 5xx, throttling, credential, and environment
148
+ faults never quarantine. The attempt count is stored with the record. `outbox_status` also lists
149
+ each kept rejection as `rejected`, and `outbox_prune_rejected` deletes rejected records last
150
+ written at least `olderThanDays` days ago. Flushing an empty
138
151
  outbox does not create the directory. `snapshot_export` never accepts a destination: the
139
152
  `agent-blackboard` client chooses a private file and returns its path. `session_archive` and
140
153
  `snapshot_archive` are the destructive tools; archived metadata is immutable, while entries stay
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vouchington-tooling",
3
- "version": "3.0.1",
3
+ "version": "3.1.0",
4
4
  "description": "Vouchington CLI and extractable tooling libraries.",
5
5
  "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
6
6
  "bugs": {
@@ -14,7 +14,8 @@ record. Read local `AGENTS.md` for the provider, credential, retention, and
14
14
  subagent-identity rules.
15
15
 
16
16
  Journal operations are tools of the `vouchington-tooling` MCP server (`vouchington mcp`):
17
- `journal_append`, `journal_entries`, `outbox_status`, `outbox_flush`, `session_ensure`,
17
+ `journal_append`, `journal_entries`, `outbox_status`, `outbox_flush`, `outbox_prune_rejected`,
18
+ `session_ensure`,
18
19
  `snapshot_export`, `snapshot_archive`, and `session_archive`. Harnesses name them differently, so match the bare tool
19
20
  name: `mcp__vouchington-tooling__<tool>`, `mcp__vouchington_tooling__<tool>` (the hyphen becomes an
20
21
  underscore), or `vouchington-tooling__<tool>` reached through a `search_tool` and `use_tool` pair,
@@ -35,6 +36,14 @@ Every call takes an exact `sessionId`, never inferred, whose meaning depends on
35
36
  of the pending set, not retained: `rejectedCount` and `worktreeRejectedCount` count the kept copies,
36
37
  `outbox_flush` reports them as `rejected` (`sourceEventId` and `diagnostic`), and a corrected retry
37
38
  with the same `sourceEventId` is accepted.
39
+ `outbox_flush` and `outbox_status` report why a pending record failed as `failures`
40
+ (`sourceEventId`, a non-secret `cause` such as `network`, `http-5xx`, or `missing-env:NAME`,
41
+ optional `httpStatus`, and `attempts`), so a stuck record is diagnosable without reading files.
42
+ A record that fails on the same record-specific cause (a 4xx other than 401, 403, 408, 429) for
43
+ 5 consecutive flushes is quarantined into the rejected area as `delivery-quarantined` and no
44
+ longer counts as pending; transient and environment causes never quarantine. Rejections keep their
45
+ diagnostic, listed by `outbox_status` as `rejected`; `outbox_prune_rejected` (`olderThanDays`,
46
+ default 7, 0 for all) deletes the old ones.
38
47
 
39
48
  Every call may take `worktree`, the absolute path of a worktree of the current repository (the
40
49
  launch worktree by default). Writing or retrying an entry needs no provider skill, temporary file,
@@ -4,57 +4,57 @@
4
4
  {
5
5
  "name": "blackboard",
6
6
  "plugin": "vouchington-workflow",
7
- "pluginVersion": "0.23.2",
7
+ "pluginVersion": "0.23.3",
8
8
  "path": "blackboard/SKILL.md"
9
9
  },
10
10
  {
11
11
  "name": "organize-github-issues",
12
12
  "plugin": "vouchington-workflow",
13
- "pluginVersion": "0.23.2",
13
+ "pluginVersion": "0.23.3",
14
14
  "path": "organize-github-issues/SKILL.md"
15
15
  },
16
16
  {
17
17
  "name": "pr-description",
18
18
  "plugin": "vouchington-workflow",
19
- "pluginVersion": "0.23.2",
19
+ "pluginVersion": "0.23.3",
20
20
  "path": "pr-description/SKILL.md"
21
21
  },
22
22
  {
23
23
  "name": "retrospective",
24
24
  "plugin": "vouchington-workflow",
25
- "pluginVersion": "0.23.2",
25
+ "pluginVersion": "0.23.3",
26
26
  "path": "retrospective/SKILL.md"
27
27
  },
28
28
  {
29
29
  "name": "retrospective-distill",
30
30
  "plugin": "vouchington-workflow",
31
- "pluginVersion": "0.23.2",
31
+ "pluginVersion": "0.23.3",
32
32
  "path": "retrospective-distill/SKILL.md"
33
33
  },
34
34
  {
35
35
  "name": "review-github-issue-taxonomy",
36
36
  "plugin": "vouchington-workflow",
37
- "pluginVersion": "0.23.2",
37
+ "pluginVersion": "0.23.3",
38
38
  "path": "review-github-issue-taxonomy/SKILL.md",
39
39
  "prerequisites": ["organize-github-issues"]
40
40
  },
41
41
  {
42
42
  "name": "triage-loop",
43
43
  "plugin": "vouchington-workflow",
44
- "pluginVersion": "0.23.2",
44
+ "pluginVersion": "0.23.3",
45
45
  "path": "triage-loop/SKILL.md"
46
46
  },
47
47
  {
48
48
  "name": "triage-prs",
49
49
  "plugin": "vouchington-workflow",
50
- "pluginVersion": "0.23.2",
50
+ "pluginVersion": "0.23.3",
51
51
  "path": "triage-prs/SKILL.md",
52
52
  "prerequisites": ["pr-description", "retrospective"]
53
53
  },
54
54
  {
55
55
  "name": "triage-sweep",
56
56
  "plugin": "vouchington-workflow",
57
- "pluginVersion": "0.23.2",
57
+ "pluginVersion": "0.23.3",
58
58
  "path": "triage-sweep/SKILL.md",
59
59
  "prerequisites": [
60
60
  "triage-loop",
@@ -20,7 +20,9 @@ Use when completed retrospectives or journals should become durable follow-up wo
20
20
  `git worktree list` reports, passing each path as `worktree`, and stop if any reports a
21
21
  `worktreePendingCount` above 0. Use the worktree count, never `pendingCount` or `status`, which
22
22
  cover only the caller's own session: the sessions to distill belong to other agents, and an
23
- archived session refuses later delivery, so a retained record would never be distilled. Outboxes
23
+ archived session refuses later delivery, so a retained record would never be distilled. A record
24
+ that repeatedly fails delivery is quarantined by `outbox_flush` into the rejected area
25
+ (`delivery-quarantined`), so it stops counting as pending; report any such rejection. Outboxes
24
26
  in removed worktrees or on other machines cannot be drained this way, so apply the age cutoffs under
25
27
  [session shapes](#session-shapes-and-eligibility) to give them time to deliver. Leave in-progress sessions intact. If a search
26
28
  for `snapshot_export` (the tool names carry a harness prefix, see the