vouchington-tooling 0.87.1 → 0.88.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.
- package/dist/agent-blackboard/snapshot-cleanup-receipt.d.mts +2 -2
- package/dist/agent-blackboard/snapshot-cleanup-receipt.mjs +20 -12
- package/dist/agent-blackboard/snapshot-partition-cleanup.d.mts +1 -0
- package/dist/agent-blackboard/snapshot-partition-cleanup.mjs +3 -0
- package/dist/agent-blackboard/snapshot-partitions.mjs +1 -1
- package/dist/agent-blackboard/snapshot-types.d.mts +8 -0
- package/dist/mcp-server/dispatch.mjs +1 -1
- package/dist/mcp-server/handlers-pr.mjs +1 -1
- package/dist/mcp-server/handlers-snapshot-cleanup.mjs +8 -0
- package/dist/mcp-server/handlers-snapshot-partition.mjs +6 -1
- package/dist/mcp-server/install-info.d.mts +2 -2
- package/dist/mcp-server/install-info.mjs +10 -6
- package/dist/mcp-server/pr-prepare.mjs +17 -11
- package/dist/mcp-server/server.mjs +2 -1
- package/dist/mcp-server/snapshot-recovery.d.mts +8 -0
- package/dist/mcp-server/snapshot-recovery.mjs +76 -0
- package/dist/mcp-server/snapshot-registry.d.mts +3 -1
- package/dist/mcp-server/snapshot-registry.mjs +3 -1
- package/dist/mcp-server/tools-pr.mjs +2 -1
- package/dist/mcp-server/tools.mjs +16 -5
- package/dist/mcp-server/worktree.mjs +3 -0
- package/docs/mcp-server.md +24 -8
- package/package.json +1 -1
- package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
- package/skills/agent-workflow/SKILL.md +7 -1
- package/skills/dependabot/SKILL.md +4 -3
- package/skills/final-review/references/orchestrator.md +3 -3
- package/skills/manifest.json +25 -33
- package/skills/planning/SKILL.md +3 -0
- package/skills/review-ci-logs/SKILL.md +2 -0
- package/skills/stacked-prs/SKILL.md +8 -2
- package/skills/stacked-prs/references/drain.md +3 -1
- package/skills/triage-loop/SKILL.md +125 -21
- package/skills/triage-loop/references/shepherd.md +45 -0
- package/skills/triage-prs/SKILL.md +15 -18
- package/skills/triage-prs/references/rubric.md +2 -2
- package/skills/triage-sweep/SKILL.md +40 -12
- package/skills/ready-and-shepherd/SKILL.md +0 -110
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import type { SnapshotCleanupReceipt, SnapshotPartition } from './snapshot-types.mts';
|
|
1
|
+
import type { SnapshotCleanupOwner, SnapshotCleanupReceipt, SnapshotPartition } from './snapshot-types.mts';
|
|
2
2
|
export declare const RECEIPT_NAME = ".agent-blackboard-cleanup-receipt.json";
|
|
3
3
|
export declare function serializeCleanupReceipt(receipt: SnapshotCleanupReceipt): string;
|
|
4
4
|
export declare function sameCleanupReceipt(left: unknown, right: SnapshotCleanupReceipt): boolean;
|
|
5
|
-
export declare function writeCleanupReceipt(directory: string, partitions: Array<Pick<SnapshotPartition, 'path' | 'checksum'
|
|
5
|
+
export declare function writeCleanupReceipt(directory: string, partitions: Array<Pick<SnapshotPartition, 'path' | 'checksum'>>, owner?: SnapshotCleanupOwner): Promise<SnapshotCleanupReceipt>;
|
|
6
6
|
export declare function verifyCleanupReceipt(receipt: SnapshotCleanupReceipt): Promise<void>;
|
|
@@ -9,19 +9,25 @@ function record(value) {
|
|
|
9
9
|
function exact(value, keys) {
|
|
10
10
|
return Object.keys(value).length === keys.length && keys.every((key) => key in value);
|
|
11
11
|
}
|
|
12
|
+
function canonicalOwner(receipt) {
|
|
13
|
+
if (!('owner' in receipt))
|
|
14
|
+
return {};
|
|
15
|
+
const { owner } = receipt;
|
|
16
|
+
if (!record(owner) ||
|
|
17
|
+
!exact(owner, ['sessionId', 'worktree', 'source']) ||
|
|
18
|
+
!Object.values(owner).every((value) => typeof value === 'string' && value))
|
|
19
|
+
throw new Error('partition directory cleanup receipt is invalid');
|
|
20
|
+
const { sessionId, worktree, source } = owner;
|
|
21
|
+
return { owner: { sessionId, worktree, source } };
|
|
22
|
+
}
|
|
12
23
|
function canonical(receipt, signature) {
|
|
24
|
+
const base = ['schemaVersion', 'directory', 'directoryDev', 'directoryIno', 'token', 'partitions'];
|
|
13
25
|
if (!record(receipt) ||
|
|
14
|
-
!exact(receipt,
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
'directoryIno',
|
|
20
|
-
'token',
|
|
21
|
-
'partitions',
|
|
22
|
-
'signature',
|
|
23
|
-
]
|
|
24
|
-
: ['schemaVersion', 'directory', 'directoryDev', 'directoryIno', 'token', 'partitions']))
|
|
26
|
+
!exact(receipt, [
|
|
27
|
+
...base,
|
|
28
|
+
...('owner' in receipt ? ['owner'] : []),
|
|
29
|
+
...(signature ? ['signature'] : []),
|
|
30
|
+
]))
|
|
25
31
|
throw new Error('partition directory cleanup receipt is invalid');
|
|
26
32
|
const { schemaVersion, directory, directoryDev, directoryIno, token, partitions } = receipt;
|
|
27
33
|
if (schemaVersion !== 1 ||
|
|
@@ -64,6 +70,7 @@ function canonical(receipt, signature) {
|
|
|
64
70
|
directoryIno: normalizedDirectoryIno,
|
|
65
71
|
token,
|
|
66
72
|
partitions: normalized,
|
|
73
|
+
...canonicalOwner(receipt),
|
|
67
74
|
};
|
|
68
75
|
if (!signature)
|
|
69
76
|
return JSON.stringify(unsigned);
|
|
@@ -85,7 +92,7 @@ export function sameCleanupReceipt(left, right) {
|
|
|
85
92
|
return false;
|
|
86
93
|
}
|
|
87
94
|
}
|
|
88
|
-
export async function writeCleanupReceipt(directory, partitions) {
|
|
95
|
+
export async function writeCleanupReceipt(directory, partitions, owner) {
|
|
89
96
|
const info = await lstat(directory);
|
|
90
97
|
const unsigned = {
|
|
91
98
|
schemaVersion: 1,
|
|
@@ -94,6 +101,7 @@ export async function writeCleanupReceipt(directory, partitions) {
|
|
|
94
101
|
directoryIno: info.ino,
|
|
95
102
|
token: randomUUID(),
|
|
96
103
|
partitions: partitions.map(({ path, checksum }) => ({ name: basename(path), checksum })),
|
|
104
|
+
...(owner === undefined ? {} : { owner }),
|
|
97
105
|
};
|
|
98
106
|
const signature = createHmac('sha256', await loadCleanupSigningKey())
|
|
99
107
|
.update(payload(unsigned))
|
|
@@ -9,5 +9,6 @@ declare const defaults: {
|
|
|
9
9
|
rmdir: typeof rmdir;
|
|
10
10
|
};
|
|
11
11
|
export declare function setSnapshotCleanupFilesystemForTest(overrides?: Partial<typeof defaults>): void;
|
|
12
|
+
export declare function assertGeneratedPartitionDirectory(path: string): void;
|
|
12
13
|
export declare function cleanupSnapshotPartitions(options: SnapshotCleanupOptions): Promise<void>;
|
|
13
14
|
export {};
|
|
@@ -18,6 +18,9 @@ function assertGeneratedPath(path, expression, label) {
|
|
|
18
18
|
!expression.test(basename(path)))
|
|
19
19
|
throw new Error(`${label} must be a generated temporary ${label}`);
|
|
20
20
|
}
|
|
21
|
+
export function assertGeneratedPartitionDirectory(path) {
|
|
22
|
+
assertGeneratedPath(path, DIRECTORY_NAME, 'partition directory');
|
|
23
|
+
}
|
|
21
24
|
async function removeCaptured(path, expression, directory, receipt) {
|
|
22
25
|
const label = directory ? 'partition directory' : 'snapshot path';
|
|
23
26
|
assertGeneratedPath(path, expression, label);
|
|
@@ -86,7 +86,7 @@ export async function partitionSnapshot(options) {
|
|
|
86
86
|
return {
|
|
87
87
|
directory: directory,
|
|
88
88
|
partitions,
|
|
89
|
-
cleanupReceipt: await writeCleanupReceipt(directory, partitions),
|
|
89
|
+
cleanupReceipt: await writeCleanupReceipt(directory, partitions, options.owner),
|
|
90
90
|
};
|
|
91
91
|
}
|
|
92
92
|
catch (error) {
|
|
@@ -37,6 +37,7 @@ export type SnapshotPartitionOptions = {
|
|
|
37
37
|
counts?: SnapshotCounts;
|
|
38
38
|
maxSessions?: number;
|
|
39
39
|
maxBytes?: number;
|
|
40
|
+
owner?: SnapshotCleanupOwner;
|
|
40
41
|
};
|
|
41
42
|
export type SnapshotPartition = {
|
|
42
43
|
path: string;
|
|
@@ -44,6 +45,12 @@ export type SnapshotPartition = {
|
|
|
44
45
|
checksum: SnapshotChecksum;
|
|
45
46
|
manifest: SnapshotManifest;
|
|
46
47
|
};
|
|
48
|
+
/** Who exported a snapshot and the generated file it came from, signed into the receipt. */
|
|
49
|
+
export type SnapshotCleanupOwner = {
|
|
50
|
+
sessionId: string;
|
|
51
|
+
worktree: string;
|
|
52
|
+
source: string;
|
|
53
|
+
};
|
|
47
54
|
export type SnapshotCleanupReceipt = {
|
|
48
55
|
schemaVersion: 1;
|
|
49
56
|
directory: string;
|
|
@@ -54,6 +61,7 @@ export type SnapshotCleanupReceipt = {
|
|
|
54
61
|
name: string;
|
|
55
62
|
checksum: SnapshotChecksum;
|
|
56
63
|
}>;
|
|
64
|
+
owner?: SnapshotCleanupOwner;
|
|
57
65
|
signature: string;
|
|
58
66
|
};
|
|
59
67
|
export type SnapshotPartitionResult = {
|
|
@@ -40,7 +40,7 @@ const DIAGNOSTIC_HINTS = {
|
|
|
40
40
|
'authentication-rejected': 'the blackboard rejected AGENT_BLACKBOARD_TOKEN',
|
|
41
41
|
'blackboard-unavailable': 'the blackboard could not be reached or returned an error',
|
|
42
42
|
'configuration-invalid': 'AGENT_BLACKBOARD_URL or AGENT_BLACKBOARD_TOKEN is missing or invalid',
|
|
43
|
-
'client-unavailable': 'agent-blackboard is not installed next to vouchington-tooling',
|
|
43
|
+
'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
44
|
'readback-unconfirmed': 'the write could not be confirmed; retry the same call (same sourceEventId and content)',
|
|
45
45
|
'delivery-timeout': 'delivery timed out; retry the same call (same sourceEventId and content)',
|
|
46
46
|
};
|
|
@@ -15,7 +15,7 @@ function rejectErrors(prepared) {
|
|
|
15
15
|
}
|
|
16
16
|
export const handlePrValidate = async (args, context) => {
|
|
17
17
|
const { body, errors, warnings } = await prepare(args, context, 'validate', readPr(args, false));
|
|
18
|
-
return { body, errors, warnings };
|
|
18
|
+
return { ok: errors.length === 0, body, errors, warnings };
|
|
19
19
|
};
|
|
20
20
|
export const handlePrCreate = async (args, context) => {
|
|
21
21
|
const prepared = await prepare(args, context, 'create', undefined);
|
|
@@ -1,12 +1,20 @@
|
|
|
1
1
|
import { cleanupSnapshotPartitions } from "../agent-blackboard/index.mjs";
|
|
2
2
|
import { loadClient } from "../agent-blackboard/client.mjs";
|
|
3
3
|
import { requiredString } from "./args.mjs";
|
|
4
|
+
import { recoverSnapshot } from "./snapshot-recovery.mjs";
|
|
4
5
|
/**
|
|
5
6
|
* Deletes the files one `snapshot_export` recorded. The caller supplies only the token: the paths
|
|
6
7
|
* and the signed receipt come from the server's own record, and the record is checked against the
|
|
7
8
|
* caller's sessionId and resolved worktree before any filesystem call.
|
|
8
9
|
*/
|
|
9
10
|
export const snapshotCleanup = async (args, context) => {
|
|
11
|
+
if (args.cleanupToken !== undefined && args.recoveryDirectory !== undefined)
|
|
12
|
+
throw new Error('pass exactly one of cleanupToken or recoveryDirectory, not both');
|
|
13
|
+
if (args.recoveryDirectory !== undefined) {
|
|
14
|
+
// After a restart the registry is empty; the signed receipt, not the caller, proves ownership.
|
|
15
|
+
await recoverSnapshot(requiredString(args, 'recoveryDirectory'), context.sessionId, context.worktree);
|
|
16
|
+
return { sessionId: context.sessionId, cleaned: true };
|
|
17
|
+
}
|
|
10
18
|
const token = requiredString(args, 'cleanupToken');
|
|
11
19
|
// Taking the record is synchronous, so a concurrent second call finds the token already spent.
|
|
12
20
|
const record = context.snapshots.take(token, context.sessionId, context.worktree);
|
|
@@ -59,8 +59,13 @@ export const snapshotPartition = async (args, context) => {
|
|
|
59
59
|
// A client that wrote an ownership marker partitions only with its own capability. An export
|
|
60
60
|
// without one came from an older client, whose partitions the in-tree code splits and signs.
|
|
61
61
|
let result;
|
|
62
|
+
// The in-tree receipt is signed with the owner and source file, so a restarted server can
|
|
63
|
+
// prove who the directory belongs to; see `snapshot-recovery.mts`.
|
|
62
64
|
if (record.clientToken === undefined)
|
|
63
|
-
result = await partitionSnapshot(
|
|
65
|
+
result = await partitionSnapshot({
|
|
66
|
+
...options,
|
|
67
|
+
owner: { sessionId: context.sessionId, worktree: context.worktree, source: record.path },
|
|
68
|
+
});
|
|
64
69
|
else if (client.partitionSnapshot)
|
|
65
70
|
result = await client.partitionSnapshot({ ...options, cleanupToken: record.clientToken });
|
|
66
71
|
else
|
|
@@ -7,5 +7,5 @@ export type InstallInfo = {
|
|
|
7
7
|
};
|
|
8
8
|
export declare function captureInstall(version?: string): InstallInfo;
|
|
9
9
|
export declare function describeInstall(install: InstallInfo): string;
|
|
10
|
-
/** The suffix appended to every tool error so a stale or
|
|
11
|
-
export declare function installSuffix(error: unknown, install: InstallInfo): string;
|
|
10
|
+
/** The suffix appended to every tool error so a stale, swapped, or removed install is obvious. */
|
|
11
|
+
export declare function installSuffix(error: unknown, install: InstallInfo, exists?: (path: string) => boolean): string;
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { existsSync } from 'node:fs';
|
|
1
2
|
import { isAbsolute, relative, sep } from 'node:path';
|
|
2
3
|
import { fileURLToPath } from 'node:url';
|
|
3
4
|
import { readInstalledVersion } from "../cli/installed-version.mjs";
|
|
@@ -36,10 +37,13 @@ function isInstallSwapped(error, install) {
|
|
|
36
37
|
const rel = relative(install.location, target);
|
|
37
38
|
return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
|
|
38
39
|
}
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
40
|
+
const RECONNECT = 'reconnect the server (`/mcp` in Claude Code, or restart Codex)';
|
|
41
|
+
/** The suffix appended to every tool error so a stale, swapped, or removed install is obvious. */
|
|
42
|
+
export function installSuffix(error, install, exists = existsSync) {
|
|
43
|
+
let hint = '';
|
|
44
|
+
if (!exists(install.location))
|
|
45
|
+
hint = ` The server's install directory (${install.location}) was removed: if it was installed at a fixed path, reinstall it and its peer dependencies there first, then ${RECONNECT}.`;
|
|
46
|
+
else if (isInstallSwapped(error, install))
|
|
47
|
+
hint = ` The server install changed underneath it: ${RECONNECT}.`;
|
|
48
|
+
return `${hint}\n[${describeInstall(install)}]`;
|
|
45
49
|
}
|
|
@@ -25,11 +25,10 @@ export function policyFor(context) {
|
|
|
25
25
|
...(context.spawnPolicy === undefined ? {} : { spawn: context.spawnPolicy }),
|
|
26
26
|
};
|
|
27
27
|
}
|
|
28
|
+
/** The checked-out branch, or undefined for a detached HEAD. */
|
|
28
29
|
async function currentBranch(git) {
|
|
29
30
|
const branch = (await git(['rev-parse', '--abbrev-ref', 'HEAD'])).trim();
|
|
30
|
-
|
|
31
|
-
throw new Error('the worktree has a detached HEAD: check out a branch');
|
|
32
|
-
return branch;
|
|
31
|
+
return branch === 'HEAD' ? undefined : branch;
|
|
33
32
|
}
|
|
34
33
|
async function label(context, git) {
|
|
35
34
|
const listing = await git(['worktree', 'list', '--porcelain', '-z']);
|
|
@@ -43,17 +42,21 @@ async function liveFor(kind, context, pr) {
|
|
|
43
42
|
: readLivePullRequest(ghIn(context), pr);
|
|
44
43
|
}
|
|
45
44
|
/**
|
|
46
|
-
* The head to validate. An update accepts the worktree branch, or an alias branch
|
|
47
|
-
* the live head commit, and then uses the live head name; anything else is rejected.
|
|
45
|
+
* The head to validate. An update accepts the worktree branch, or an alias branch or detached HEAD
|
|
46
|
+
* at the live head commit, and then uses the live head name; anything else is rejected. A detached
|
|
47
|
+
* HEAD (worktreeHead undefined) is only acceptable that way, for an update of a live pull request.
|
|
48
48
|
*/
|
|
49
49
|
async function headFor(kind, git, live, pr, worktreeHead) {
|
|
50
|
-
if (
|
|
51
|
-
|
|
52
|
-
|
|
50
|
+
if (live === undefined || kind !== 'update') {
|
|
51
|
+
if (worktreeHead === undefined)
|
|
52
|
+
throw new Error('the worktree has a detached HEAD: check out a branch');
|
|
53
|
+
return worktreeHead;
|
|
54
|
+
}
|
|
55
|
+
if (live.headRefName === worktreeHead)
|
|
53
56
|
return worktreeHead;
|
|
54
57
|
const sha = (await git(['rev-parse', 'HEAD'])).trim();
|
|
55
58
|
if (sha !== live.headRefOid)
|
|
56
|
-
throw new Error(`pull request ${pr} has head ${live.headRefName} at ${live.headRefOid}, not the worktree branch ${worktreeHead} at ${sha}`);
|
|
59
|
+
throw new Error(`pull request ${pr} has head ${live.headRefName} at ${live.headRefOid}, not the worktree ${worktreeHead === undefined ? 'detached HEAD' : `branch ${worktreeHead}`} at ${sha}`);
|
|
57
60
|
return live.headRefName;
|
|
58
61
|
}
|
|
59
62
|
/** Renders the body, preserves the live journal for an update, and runs the policy validator. */
|
|
@@ -67,11 +70,14 @@ export async function prepare(args, context, kind, pr) {
|
|
|
67
70
|
const git = gitIn(context);
|
|
68
71
|
const live = await liveFor(kind, context, pr);
|
|
69
72
|
// A read-only validation of an existing pull request judges the head that pull request has.
|
|
70
|
-
const
|
|
73
|
+
const readOnly = live !== undefined && kind === 'validate';
|
|
74
|
+
const worktreeHead = readOnly ? undefined : await currentBranch(git);
|
|
71
75
|
// The local branch is checked before any diagnostic or alias resolution can echo or drop it.
|
|
72
76
|
if (worktreeHead !== undefined && secrets.some((secret) => worktreeHead.includes(secret)))
|
|
73
77
|
throw new Error('the worktree branch name contains a server credential: rename the branch');
|
|
74
|
-
const head =
|
|
78
|
+
const head = readOnly
|
|
79
|
+
? live.headRefName
|
|
80
|
+
: await headFor(kind, git, live, pr, worktreeHead);
|
|
75
81
|
// Branch names are refs passed to gh as is: redacting one would name a branch that does not exist.
|
|
76
82
|
if (secrets.some((secret) => head.includes(secret)))
|
|
77
83
|
throw new Error('the worktree branch name contains a server credential: rename the branch');
|
|
@@ -8,7 +8,8 @@ const INSTRUCTIONS = 'Journals agent-blackboard feedback for a vouchington consu
|
|
|
8
8
|
'Code mcp__vouchington-tooling__<tool>, Codex mcp__vouchington_tooling__<tool>, Grok ' +
|
|
9
9
|
'vouchington-tooling__<tool> (through search_tool and use_tool), Cursor the vouchington-tooling ' +
|
|
10
10
|
'namespace (through GetDynamicTools and CallDynamicTool). Search for journal_append before ' +
|
|
11
|
-
'concluding this server is unavailable. Tool errors are actionable; do not fall back to a CLI.'
|
|
11
|
+
'concluding this server is unavailable. Tool errors are actionable; do not fall back to a CLI. ' +
|
|
12
|
+
'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).';
|
|
12
13
|
/**
|
|
13
14
|
* Builds the server. The tool list and call handlers go on the low-level `server` because the
|
|
14
15
|
* high-level `registerTool` path needs zod schemas, and this package keeps zod out of its own code.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Removes a generated partition directory and its source snapshot after a server restart. The
|
|
3
|
+
* caller's path only selects a candidate; deletion follows the signed receipt and reuses the
|
|
4
|
+
* receipt cleanup's own checks (generated names, temp location, no symlinks, directory identity,
|
|
5
|
+
* partition checksums). Every proof failure is one message, so probing learns nothing. The
|
|
6
|
+
* directory is gone afterward, so a second call is rejected, and a concurrent call is too.
|
|
7
|
+
*/
|
|
8
|
+
export declare function recoverSnapshot(directory: unknown, sessionId: string, worktree: string): Promise<void>;
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import { constants } from 'node:fs';
|
|
2
|
+
import { lstat, open } from 'node:fs/promises';
|
|
3
|
+
import { join } from 'node:path';
|
|
4
|
+
import { assertGeneratedPartitionDirectory, cleanupSnapshotPartitions, } from "../agent-blackboard/snapshot-partition-cleanup.mjs";
|
|
5
|
+
import { RECEIPT_NAME, verifyCleanupReceipt, } from "../agent-blackboard/snapshot-cleanup-receipt.mjs";
|
|
6
|
+
const REJECTED = 'recoveryDirectory is not a snapshot partition directory this session and worktree generated ' +
|
|
7
|
+
'and this server can still verify; nothing was deleted';
|
|
8
|
+
const MAX_MARKER_BYTES = 64 * 1024;
|
|
9
|
+
const inFlight = new Set();
|
|
10
|
+
/** Reads the owner-only receipt marker through a no-follow descriptor, never a followed link. */
|
|
11
|
+
async function readMarker(directory) {
|
|
12
|
+
const marker = join(directory, RECEIPT_NAME);
|
|
13
|
+
const info = await lstat(marker);
|
|
14
|
+
if (info.isSymbolicLink() || !info.isFile() || info.nlink !== 1 || info.size > MAX_MARKER_BYTES)
|
|
15
|
+
throw new Error('marker is not a regular file');
|
|
16
|
+
const handle = await open(marker, constants.O_RDONLY | constants.O_NOFOLLOW);
|
|
17
|
+
try {
|
|
18
|
+
return JSON.parse(await handle.readFile('utf8'));
|
|
19
|
+
}
|
|
20
|
+
finally {
|
|
21
|
+
await handle.close();
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Proves a partition directory is one this server generated for this caller, without any state
|
|
26
|
+
* from before a restart. The directory must be a direct, non-symlink child of the temp directory
|
|
27
|
+
* with the generated name; its marker must carry a valid HMAC signature under the server's
|
|
28
|
+
* persistent key; and the signed owner must equal the caller's sessionId and worktree. Receipts
|
|
29
|
+
* signed without an owner (older ones) are never recoverable.
|
|
30
|
+
*/
|
|
31
|
+
async function proveOwnership(directory, sessionId, worktree) {
|
|
32
|
+
if (typeof directory !== 'string')
|
|
33
|
+
throw new Error('not a path');
|
|
34
|
+
assertGeneratedPartitionDirectory(directory);
|
|
35
|
+
const info = await lstat(directory);
|
|
36
|
+
if (info.isSymbolicLink() || !info.isDirectory())
|
|
37
|
+
throw new Error('not a directory');
|
|
38
|
+
const receipt = (await readMarker(directory));
|
|
39
|
+
await verifyCleanupReceipt(receipt);
|
|
40
|
+
const { owner } = receipt;
|
|
41
|
+
if (receipt.directory !== directory ||
|
|
42
|
+
owner?.sessionId !== sessionId ||
|
|
43
|
+
owner.worktree !== worktree)
|
|
44
|
+
throw new Error('not the owner');
|
|
45
|
+
return receipt;
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* Removes a generated partition directory and its source snapshot after a server restart. The
|
|
49
|
+
* caller's path only selects a candidate; deletion follows the signed receipt and reuses the
|
|
50
|
+
* receipt cleanup's own checks (generated names, temp location, no symlinks, directory identity,
|
|
51
|
+
* partition checksums). Every proof failure is one message, so probing learns nothing. The
|
|
52
|
+
* directory is gone afterward, so a second call is rejected, and a concurrent call is too.
|
|
53
|
+
*/
|
|
54
|
+
export async function recoverSnapshot(directory, sessionId, worktree) {
|
|
55
|
+
const key = typeof directory === 'string' ? directory : '';
|
|
56
|
+
if (inFlight.has(key))
|
|
57
|
+
throw new Error(REJECTED);
|
|
58
|
+
inFlight.add(key);
|
|
59
|
+
try {
|
|
60
|
+
let receipt;
|
|
61
|
+
try {
|
|
62
|
+
receipt = await proveOwnership(directory, sessionId, worktree);
|
|
63
|
+
}
|
|
64
|
+
catch {
|
|
65
|
+
throw new Error(REJECTED);
|
|
66
|
+
}
|
|
67
|
+
await cleanupSnapshotPartitions({
|
|
68
|
+
path: receipt.owner.source,
|
|
69
|
+
directory: receipt.directory,
|
|
70
|
+
receipt,
|
|
71
|
+
});
|
|
72
|
+
}
|
|
73
|
+
finally {
|
|
74
|
+
inFlight.delete(key);
|
|
75
|
+
}
|
|
76
|
+
}
|
|
@@ -23,6 +23,8 @@ export type SnapshotRegistry = {
|
|
|
23
23
|
export declare const MAX_RECORDS = 256;
|
|
24
24
|
/**
|
|
25
25
|
* Tokens live in memory only. A server restart forgets every binding, so an old token is then
|
|
26
|
-
* rejected as unknown
|
|
26
|
+
* rejected as unknown. A partitioned snapshot can still be removed through `snapshot-recovery.mts`,
|
|
27
|
+
* which proves ownership from the signed receipt on disk; a plain export file has no receipt, so
|
|
28
|
+
* it is left for the operating system to reap from its temp directory.
|
|
27
29
|
*/
|
|
28
30
|
export declare function createSnapshotRegistry(): SnapshotRegistry;
|
|
@@ -3,7 +3,9 @@ export const MAX_RECORDS = 256;
|
|
|
3
3
|
const REJECTED = 'cleanupToken is unknown, already used, or bound to another session or worktree; nothing was deleted';
|
|
4
4
|
/**
|
|
5
5
|
* Tokens live in memory only. A server restart forgets every binding, so an old token is then
|
|
6
|
-
* rejected as unknown
|
|
6
|
+
* rejected as unknown. A partitioned snapshot can still be removed through `snapshot-recovery.mts`,
|
|
7
|
+
* which proves ownership from the signed receipt on disk; a plain export file has no receipt, so
|
|
8
|
+
* it is left for the operating system to reap from its temp directory.
|
|
7
9
|
*/
|
|
8
10
|
export function createSnapshotRegistry() {
|
|
9
11
|
const records = new Map();
|
|
@@ -74,7 +74,8 @@ export const PR_TOOLS = [
|
|
|
74
74
|
'Pass pr to validate an update of that pull request: the live body is read and its Shepherd ' +
|
|
75
75
|
'Journal preserved; the pull request may be in any state and on any head (the head given to ' +
|
|
76
76
|
'the policy is its own, and no liveness check applies, unlike pr_update). Returns ' +
|
|
77
|
-
'{ body, errors, warnings }
|
|
77
|
+
'{ ok, body, errors, warnings }; blocking errors do not fail the tool call, so callers must ' +
|
|
78
|
+
'check ok (true only when errors is empty) or errors.', openWorld(READ_ONLY), { ...FIELDS, pr: PR_NUMBER }, REQUIRED),
|
|
78
79
|
tool('pr_create', 'Creates a draft pull request from the worktree branch. ' +
|
|
79
80
|
RENDERING +
|
|
80
81
|
'Validation errors block creation. The policy pullRequestDefaults export may add labels, a ' +
|
|
@@ -113,10 +113,21 @@ export const TOOLS = [
|
|
|
113
113
|
},
|
|
114
114
|
}, ['cleanupToken', 'sessionIds']),
|
|
115
115
|
tool('snapshot_cleanup', 'Deletes the snapshot file and the partition directory (from snapshot_partition) that ' +
|
|
116
|
-
'snapshot_export produced.
|
|
117
|
-
'
|
|
118
|
-
'
|
|
119
|
-
'
|
|
120
|
-
'
|
|
116
|
+
'snapshot_export produced. Pass exactly one of cleanupToken or recoveryDirectory. ' +
|
|
117
|
+
'cleanupToken is the one snapshot_export returned: the server resolves the paths from its ' +
|
|
118
|
+
'own record, never from the caller. The token is bound to the sessionId and worktree that ' +
|
|
119
|
+
'exported, is single-use, and is forgotten when the server restarts. After a restart, pass ' +
|
|
120
|
+
'recoveryDirectory, the directory snapshot_partition returned: the server deletes it and ' +
|
|
121
|
+
'its source snapshot only if the signed receipt inside proves it generated them for this ' +
|
|
122
|
+
'sessionId and worktree in the temp directory. A plain unpartitioned snapshot has no ' +
|
|
123
|
+
'receipt and cannot be recovered. Recovery is single-use and every rejection is one ' +
|
|
124
|
+
'message. A failed cleanup keeps the token valid and names any retained tombstone so the ' +
|
|
125
|
+
'same call can retry. Call it as a finally step.', { ...MUTATING, idempotentHint: false }, {
|
|
126
|
+
cleanupToken: { type: 'string', description: 'The cleanupToken snapshot_export returned.' },
|
|
127
|
+
recoveryDirectory: {
|
|
128
|
+
type: 'string',
|
|
129
|
+
description: 'After a server restart, the partition directory snapshot_partition returned.',
|
|
130
|
+
},
|
|
131
|
+
}, []),
|
|
121
132
|
tool('session_archive', 'Marks a session as distilled. Its metadata becomes immutable; entries stay appendable.', MUTATING),
|
|
122
133
|
];
|
|
@@ -89,6 +89,9 @@ export async function resolveWorktree(input) {
|
|
|
89
89
|
if (!isAbsolute(path))
|
|
90
90
|
throw new Error('worktree must be an absolute path to a git worktree');
|
|
91
91
|
const target = await canonical(path);
|
|
92
|
+
if (requested === undefined && target === undefined)
|
|
93
|
+
throw new Error(`the launch worktree ${path} no longer exists, so there is no default to fall back to: ` +
|
|
94
|
+
'pass worktree as the absolute path of an existing worktree');
|
|
92
95
|
if (target !== undefined && (await launchWorktreeRoot(target, runGit)) === target) {
|
|
93
96
|
if (launchRoot === undefined || (await repositoryWorktrees(launchRoot, runGit)).has(target))
|
|
94
97
|
return target;
|
package/docs/mcp-server.md
CHANGED
|
@@ -62,7 +62,8 @@ the Node version first: on Node older than 24 they print one line to stderr, suc
|
|
|
62
62
|
The command takes no arguments and may be launched with any working directory, including one outside
|
|
63
63
|
every git repository (for example `~`). When the working directory is inside a git worktree, that
|
|
64
64
|
worktree's top level is the default for tools called without `worktree`. Otherwise those calls fail
|
|
65
|
-
with a tool error asking for an explicit `worktree`.
|
|
65
|
+
with a tool error asking for an explicit `worktree`. If the launch worktree is later removed, those
|
|
66
|
+
calls fail naming the removed path and asking for an explicit `worktree`. stdout carries only protocol frames, and
|
|
66
67
|
diagnostics go to stderr.
|
|
67
68
|
|
|
68
69
|
## Tools
|
|
@@ -83,7 +84,7 @@ as MCP tool errors (`isError: true`) with an actionable message rather than cras
|
|
|
83
84
|
| `snapshot_export` | optional `agent`, `version`, `parentSessionId`, `data`, `dataArrayContains`, `inactiveForHours` | `sessionId`, `path`, `counts`, `checksum`, `manifest`, `cleanupToken` |
|
|
84
85
|
| `snapshot_partition` | `cleanupToken`, optional `checksum`, `counts`, `maxSessions`, `maxBytes` | `sessionId`, `directory`, `partitions` (`path`, `counts`, `checksum`, `manifest` of each) |
|
|
85
86
|
| `snapshot_archive` | `cleanupToken`, `sessionIds` (1 to 100) | `sessionId`, `archived`, `skipped` (`sessionId`, `reason`; never entry content) |
|
|
86
|
-
| `snapshot_cleanup` | `cleanupToken`
|
|
87
|
+
| `snapshot_cleanup` | one of `cleanupToken` or `recoveryDirectory` | `sessionId`, `cleaned: true` |
|
|
87
88
|
| `session_archive` | none | `sessionId`, `archived: true` |
|
|
88
89
|
|
|
89
90
|
`journal_append` validates the whole feedback envelope with `validateFeedbackEnvelope` before
|
|
@@ -206,10 +207,22 @@ failure.
|
|
|
206
207
|
the owner's token. If the cleanup itself fails, the token stays valid and the error carries the
|
|
207
208
|
reason, including the retained tombstone path when a partition directory was half removed, so the
|
|
208
209
|
same call can retry. A file that is already gone counts as cleaned.
|
|
209
|
-
- **Server restart.** Bindings are in memory only
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
210
|
+
- **Server restart.** Bindings are in memory only, so after a restart every earlier token is
|
|
211
|
+
unknown. Instead of persisting client capabilities, `recoveryDirectory` (the directory
|
|
212
|
+
`snapshot_partition` returned, used in place of `cleanupToken`) lets the server prove it generated
|
|
213
|
+
the output. The directory must be a non-symlink child of the OS temp directory with the generated
|
|
214
|
+
name; the `.agent-blackboard-cleanup-receipt.json` marker inside must carry a valid HMAC signature
|
|
215
|
+
under the server's persistent owner-only key; and the signed `owner` (`sessionId`, `worktree`, and
|
|
216
|
+
the source snapshot path, all signed into the receipt) must equal the caller's. Deletion then
|
|
217
|
+
reuses the receipt cleanup's checks (directory identity, partition checksums, no unexpected
|
|
218
|
+
content). The source snapshot is removed with it. Recovery is single use (the directory is gone
|
|
219
|
+
afterward, and a concurrent call is refused) and every rejection is one message that deletes
|
|
220
|
+
nothing.
|
|
221
|
+
- **Not recoverable.** A plain unpartitioned export file has no receipt, so after a restart it is
|
|
222
|
+
left for the operating system to reap. So are directories partitioned by a newer client that
|
|
223
|
+
keeps its own ownership marker (its capability is never persisted), and directories whose
|
|
224
|
+
receipt predates the signed `owner` field. Run the distill pass again to export a fresh snapshot.
|
|
225
|
+
The registry remembers at most 256 exports and forgets the oldest first.
|
|
213
226
|
|
|
214
227
|
The outbox lives at `<worktree>/.local/blackboard-outbox` and is used only in interactive mode.
|
|
215
228
|
Autonomous mode forbids a filesystem outbox, so a failed delivery is an error.
|
|
@@ -401,14 +414,17 @@ The provenance lines are collapsed because they serve audits, not reviewers; eac
|
|
|
401
414
|
own line, so a policy can match them with line-anchored patterns.
|
|
402
415
|
|
|
403
416
|
The head branch is the worktree's current branch (for `pr_validate` with `pr`, the live pull
|
|
404
|
-
request's head, which may equal `base` for a fork)
|
|
417
|
+
request's head, which may equal `base` for a fork). `pr_update` also accepts a detached HEAD whose
|
|
418
|
+
commit is the live pull request's head commit and then uses the live head name; a detached HEAD at
|
|
419
|
+
another commit is rejected naming both commits. Otherwise a detached HEAD, or a head equal to `base`, is rejected. The body must stay within GitHub's 65536 characters. `pr_create` sees no stack membership,
|
|
405
420
|
so a consumer policy may reject any `base` other than the default branch; create stacked layers
|
|
406
421
|
with the repository's stack tooling instead.
|
|
407
422
|
|
|
408
423
|
### Tools
|
|
409
424
|
|
|
410
425
|
- `pr_validate` (read-only): renders the body, runs the policy `validatePullRequest({ title, body,
|
|
411
|
-
base, head, mode, noSourceIssue?, pr? })` export and returns `{ body, errors, warnings }`.
|
|
426
|
+
base, head, mode, noSourceIssue?, pr? })` export and returns `{ ok, body, errors, warnings }`. Blocking errors do not fail the tool call: callers must
|
|
427
|
+
check `ok` (true only when `errors` is empty) or `errors`. With
|
|
412
428
|
`pr`, the live body is read (never written) so its Shepherd Journal is preserved as in
|
|
413
429
|
`pr_update`. The liveness checks of `pr_update` do not apply: any state (merged or closed
|
|
414
430
|
included) and any head are accepted, and the policy sees the pull request's own head and base.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "vouchington-tooling",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.88.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": {
|
|
Binary file
|
|
@@ -32,9 +32,15 @@ blocker or follow-up does not authorize widening the task.
|
|
|
32
32
|
This section is the single home for the hand-off retrospective and merge-note rules.
|
|
33
33
|
|
|
34
34
|
- Report actual validation, open pull requests, and remaining blockers.
|
|
35
|
+
- **Shepherding.** The agent that authored a pull request shepherds it itself with pr-shepherd.
|
|
36
|
+
When the session must end or the owner asks, delegate instead: mark the pull request ready, post
|
|
37
|
+
the fixed literal comment `/shepherd` once (`gh pr comment <N> --body '/shepherd'`), and stop. The
|
|
38
|
+
triage loop then owns the pull request (one `/shepherd` on the top pull request of a stack). Do
|
|
39
|
+
not post it again on re-runs. No other agent merges.
|
|
35
40
|
- **Hand-off retrospective.** When you hand a pull request to the human as ready, write one
|
|
36
41
|
[retrospective](../retrospective/SKILL.md) from the session that did the work, which reads that
|
|
37
|
-
session's transcripts and journal.
|
|
42
|
+
session's transcripts and journal. Write it before you stop, including when you delegate with
|
|
43
|
+
`/shepherd`. A native stack gets one retrospective when the stack is handed
|
|
38
44
|
off, covering every layer; never one per layer or for an intermediate commit.
|
|
39
45
|
- Give each hand-off its own `sourceEventId`, such as `handoff-pr<number>` (a stack uses its top
|
|
40
46
|
pull request's number), on both `retrospective_check` and `retrospective_save`. The default ID
|
|
@@ -59,8 +59,8 @@ groups:
|
|
|
59
59
|
- Do not add generic groups such as `other-minor-and-patch`, `minor-and-patch`,
|
|
60
60
|
`security-minor-and-patch`, or `security-updates`. Do not use `patterns: ['*']` to force every
|
|
61
61
|
update into a group. Narrow family wildcards are expected. Leave unrelated packages ungrouped.
|
|
62
|
-
- Omit `update-types` so a family receives major, minor, and patch updates. Major updates
|
|
63
|
-
|
|
62
|
+
- Omit `update-types` so a family receives major, minor, and patch updates. Major updates are never
|
|
63
|
+
auto-merged by the workflow. Leaving majors out of the group splits the release train.
|
|
64
64
|
- Groups default to `applies-to: version-updates`. When the same family is also safe to upgrade
|
|
65
65
|
together for security fixes, add a separate group such as `react-security` with the same patterns
|
|
66
66
|
and `applies-to: security-updates`. Do not combine unrelated vulnerability fixes into one group.
|
|
@@ -91,7 +91,8 @@ groups:
|
|
|
91
91
|
per local policy.
|
|
92
92
|
- Auto-merge only a verified semver patch, or a stable minor whose old and new majors are both at
|
|
93
93
|
least 1. Majors, pre-1.0 minors, prereleases, downgrades, malformed or inconsistent metadata, and
|
|
94
|
-
consumer-declared manual ecosystems need a human.
|
|
94
|
+
consumer-declared manual ecosystems need a human. The workflow never merges majors; the triage
|
|
95
|
+
loop may merge them under its grant, as triage-sweep Phase A describes.
|
|
95
96
|
- Enable platform auto-merge. Do not auto-approve. Required checks and branch rules remain the gate.
|
|
96
97
|
- Store `DEPENDABOT_AUTOMERGE_TOKEN` as a Dependabot secret, not only as an Actions secret. Grant
|
|
97
98
|
only the Contents and Pull requests access needed to enable or disable auto-merge. Fail an
|
|
@@ -27,9 +27,9 @@ compaction, rebuild the queue from pending requests and the status of the pull r
|
|
|
27
27
|
|
|
28
28
|
## Hand-back
|
|
29
29
|
|
|
30
|
-
Posting the review is the hand-back: the
|
|
31
|
-
and its inline comments. Also reply to the requester with the verdict and the review link. Merge
|
|
32
|
-
authority is separate: the human or the
|
|
30
|
+
Posting the review is the hand-back: the PR's active shepherd (usually the triage loop's) sees
|
|
31
|
+
the review and its inline comments. Also reply to the requester with the verdict and the review link. Merge
|
|
32
|
+
authority is separate: the human, or the triage loop within its grant, merges, never the final reviewer.
|
|
33
33
|
|
|
34
34
|
## Presenting to the human
|
|
35
35
|
|