vouchington-tooling 0.2.0 → 0.3.0

package/README.md

@@ -6,6 +6,8 @@ Libraries and the `vouchington` CLI.
 npm install vouchington-tooling
 # optional, only if you import vouchington-tooling/sql-ast
 npm install @libpg-query/parser
+# optional, only for vouchington-tooling/agent-blackboard and agent-blackboard CLI commands
+npm install agent-blackboard@^0.3.1
 ```
 
 ## CLI
@@ -39,8 +41,16 @@ vouchington lint-links --offline
 vouchington materialize-pr-context
 vouchington wait-for-apt-locks
 vouchington retrospective-transcript --jsonl /path/to/transcript.jsonl
+vouchington retrospective-facts --pr 49 --repo vouchington/vouchington-infra --raw
+vouchington agent-blackboard probe
+vouchington agent-blackboard journal append --session-id <uuid> --agent codex --version 1 --file note.md
+vouchington agent-blackboard journal entries --session-id <uuid>
+vouchington agent-blackboard snapshot partition --snapshot <snapshot.jsonl> --checksum <sha256> --counts <counts.json>
+vouchington agent-blackboard snapshot cleanup --snapshot <snapshot.jsonl> --partition-directory <partitions-dir> --receipt <receipt-json>
 vouchington install-playwright-chromium-arm64
 vouchington ghcr-package-retention example%2Fapi
+vouchington harness-admission-lane 4
+vouchington harness-assert-gates HARNESS_DISPATCH_ENABLED HARNESS_SHEPHERD_ENABLED
 vouchington nuget-central-version trusted.props candidate.props metadata.json out.props
 vouchington swift-semantic-equal BASE HEAD App.swift
 vouchington post-review
@@ -68,6 +78,27 @@ layout when `GROK_SESSION_ID` is set. Use `--grok-sessions-dir` to point discove
 Grok session root. Without `--session-id`, it reads those session identities from the host
 environment.
 
+`retrospective-facts` keeps local Git evidence separate from GitHub PR data. `Commits ahead of
+origin/main` is populated only from a local ancestry range; GitHub responses instead populate
+`PR commits`. API-derived file and directory counts are labelled `GitHub API`. When a named local
+branch is absent, the command refreshes `origin/<branch>` before using it and refuses a stale
+remote ref when that refresh fails.
+For an explicit `--repo`, it performs no local Git checks: `Merged to main` is `yes` only when
+GitHub reports a merged PR whose `baseRefName` is `main`; a merged PR into another base is reported
+as not merged to main, and a missing base is unavailable.
+
+Agent Blackboard support is optional: only the `agent-blackboard` subpath and its CLI commands
+need `agent-blackboard@^0.3.1`. Snapshot cleanup accepts only package-generated temporary paths.
+It captures a target under a private tombstone, validates partition names, permissions, JSONL,
+ordering, terminal manifests, and the identity-bound cleanup receipt before deleting files, and
+restores the original path on a validation failure. Once deletion begins, it retains a private
+tombstone plus signed resume metadata instead; retry cleanup with the original partition-directory
+path and the same receipt until it completes. The partition command returns that receipt; directory
+cleanup requires it.
+The receipt is authenticated with an owner-only per-user HMAC key stored under a dedicated
+`0700` directory in the system temporary directory. This small host-local state is the trust
+boundary: a copied or caller-created receipt cannot authorize cleanup without that key.
+
 Host-lock environment:
 
 | Variable                                | Default               | Meaning                                     |
@@ -144,6 +175,7 @@ import {
   readDiagnosticReportSummaries,
 } from 'vouchington-tooling/vitest-diagnostics'
 import { runRetrospectiveTranscript } from 'vouchington-tooling/retrospective-transcript'
+import { appendJournal, probeBlackboard } from 'vouchington-tooling/agent-blackboard'
 import { buildSessionFrictionReport, recordFriction } from 'vouchington-tooling/session-friction'
 ```
 

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

@@ -0,0 +1,41 @@
+export { cleanupSnapshotPartitions, partitionSnapshot } from './snapshot.mts';
+export { assertSessionId } from './session-id.mts';
+export type * from './snapshot-types.mts';
+export type BlackboardConnection = {
+    baseUrl: string;
+    token: string;
+    readRetry: Record<string, never>;
+};
+export type BlackboardClientModule = {
+    Sessions: new (connection: BlackboardConnection) => {
+        ensure(input: unknown): Promise<{
+            status: 'created' | 'exists';
+        }>;
+        list(input: unknown): Promise<unknown>;
+        get(id: string): Promise<unknown>;
+    };
+    Entries: new (connection: BlackboardConnection) => {
+        append(input: unknown): Promise<{
+            createdAt: string;
+        }>;
+        get(input: unknown): AsyncIterable<unknown>;
+    };
+};
+type BlackboardClientLoader = () => Promise<BlackboardClientModule>;
+export type BlackboardClientDependencies = {
+    loadClient?: BlackboardClientLoader;
+};
+export declare function resolveBlackboardConnection(env?: NodeJS.ProcessEnv): BlackboardConnection;
+export declare function probeBlackboard(env?: NodeJS.ProcessEnv, dependencies?: BlackboardClientDependencies): Promise<void>;
+export declare function appendJournal(input: {
+    sessionId: string;
+    agent: string;
+    version: string;
+    markdownFile: string;
+    parentSessionId?: string | null;
+    timestamp?: string;
+    env?: NodeJS.ProcessEnv;
+    dependencies?: BlackboardClientDependencies;
+}): Promise<string>;
+export declare function readJournal(sessionId: string, env?: NodeJS.ProcessEnv, dependencies?: BlackboardClientDependencies): Promise<unknown[]>;
+export declare function formatJournalEntries(sessionId: string, entries: unknown[]): string;

package/dist/agent-blackboard/index.mjs

@@ -0,0 +1,94 @@
+import { readFile } from 'node:fs/promises';
+import { assertSessionId } from './session-id.mjs';
+export { cleanupSnapshotPartitions, partitionSnapshot } from './snapshot.mjs';
+export { assertSessionId } from './session-id.mjs';
+export function resolveBlackboardConnection(env = process.env) {
+    const baseUrl = env.AGENT_BLACKBOARD_URL;
+    const token = env.AGENT_BLACKBOARD_TOKEN;
+    if (!baseUrl)
+        throw new Error('AGENT_BLACKBOARD_URL is not set');
+    if (!token)
+        throw new Error('AGENT_BLACKBOARD_TOKEN is not set');
+    return { baseUrl, token, readRetry: {} };
+}
+export async function probeBlackboard(env, dependencies) {
+    const { Sessions } = await loadClient(dependencies?.loadClient);
+    await new Sessions(resolveBlackboardConnection(env)).list({ limit: 1 });
+}
+export async function appendJournal(input) {
+    assertSessionId(input.sessionId);
+    if (input.parentSessionId != null)
+        assertSessionId(input.parentSessionId, 'parent session id');
+    const timestamp = input.timestamp === undefined ? new Date() : new Date(input.timestamp);
+    if (Number.isNaN(timestamp.valueOf()))
+        throw new Error('journal timestamp is not a valid date-time');
+    let markdown;
+    try {
+        markdown = new TextDecoder('utf-8', { fatal: true }).decode(await readFile(input.markdownFile));
+    }
+    catch (error) {
+        throw new Error(`note file is not valid UTF-8: ${input.markdownFile}`, { cause: error });
+    }
+    if (!markdown)
+        throw new Error(`note file is empty: ${input.markdownFile}`);
+    const connection = resolveBlackboardConnection(input.env);
+    const { Sessions, Entries } = await loadClient(input.dependencies?.loadClient);
+    await new Sessions(connection).ensure({
+        id: input.sessionId,
+        parentSessionId: input.parentSessionId ?? null,
+        agent: input.agent,
+        version: input.version,
+    });
+    const entry = await new Entries(connection).append({
+        sessionId: input.sessionId,
+        data: { type: 'journal', markdown, timestamp: timestamp.toISOString() },
+    });
+    return `Journaled to agent-blackboard session ${input.sessionId} (entry created at ${entry.createdAt}).`;
+}
+export async function readJournal(sessionId, env, dependencies) {
+    assertSessionId(sessionId);
+    const { Entries } = await loadClient(dependencies?.loadClient);
+    const entries = [];
+    for await (const entry of new Entries(resolveBlackboardConnection(env)).get({
+        sessionId,
+        format: 'json',
+    }))
+        entries.push(entry);
+    return entries;
+}
+export function formatJournalEntries(sessionId, entries) {
+    const journals = entries.flatMap((entry) => {
+        if (typeof entry !== 'object' ||
+            entry === null ||
+            !('createdAt' in entry) ||
+            !('data' in entry) ||
+            typeof entry.createdAt !== 'string' ||
+            typeof entry.data !== 'object' ||
+            entry.data === null ||
+            !('type' in entry.data) ||
+            !('markdown' in entry.data) ||
+            entry.data.type !== 'journal' ||
+            typeof entry.data.markdown !== 'string')
+            return [];
+        return [{ createdAt: entry.createdAt, markdown: entry.data.markdown }];
+    });
+    if (!journals.length)
+        return `No journal entries found for session ${sessionId}.`;
+    return journals
+        .sort((left, right) => left.createdAt.localeCompare(right.createdAt))
+        .map(({ createdAt, markdown }) => `## ${createdAt}\n\n${markdown}`)
+        .join('\n\n');
+}
+async function loadClient(loader = defaultClientLoader) {
+    try {
+        return await loader();
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ERR_MODULE_NOT_FOUND')
+            throw new Error('agent-blackboard is not installed; install the optional agent-blackboard peer dependency', { cause: error });
+        throw error;
+    }
+}
+async function defaultClientLoader() {
+    return (await import('agent-blackboard'));
+}

package/dist/agent-blackboard/session-id.d.mts

@@ -0,0 +1 @@
+export declare function assertSessionId(sessionId: string, label?: string): void;

package/dist/agent-blackboard/session-id.mjs

@@ -0,0 +1,5 @@
+const SESSION_ID = /^[A-Za-z0-9._:-]+$/;
+export function assertSessionId(sessionId, label = 'session id') {
+    if (!SESSION_ID.test(sessionId))
+        throw new Error(`${label} must be URL-safe`);
+}

package/dist/agent-blackboard/snapshot-cleanup-directory.d.mts

@@ -0,0 +1,11 @@
+import type { lstat, readFile, readdir, rm, rmdir } from 'node:fs/promises';
+import type { SnapshotCleanupReceipt } from './snapshot-types.mts';
+type Filesystem = {
+    lstat: typeof lstat;
+    readFile: typeof readFile;
+    readdir: typeof readdir;
+    rm: typeof rm;
+    rmdir: typeof rmdir;
+};
+export declare function removePartitionDirectory(filesystem: Filesystem, path: string, originalPath: string, receipt: SnapshotCleanupReceipt, directory: Awaited<ReturnType<typeof lstat>>, resume: boolean, startDeleting: () => void): Promise<void>;
+export {};

package/dist/agent-blackboard/snapshot-cleanup-directory.mjs

@@ -0,0 +1,66 @@
+import { join } from 'node:path';
+import { RECEIPT_NAME, sameCleanupReceipt } from './snapshot-cleanup-receipt.mjs';
+import { removeResumeReceipt, writeResumeReceipt } from './snapshot-cleanup-resume.mjs';
+import { assertPartitionFile, validatePartition } from './snapshot-partition-validate.mjs';
+const PARTITION = /^partition-([1-9][0-9]*)\.jsonl$/;
+export async function removePartitionDirectory(filesystem, path, originalPath, receipt, directory, resume, startDeleting) {
+    const names = await filesystem.readdir(path);
+    const ordered = names
+        .filter((name) => PARTITION.test(name))
+        .map((name) => ({ name, number: Number(PARTITION.exec(name)?.[1]) }))
+        .sort((left, right) => left.number - right.number);
+    const expected = receipt.partitions.map(({ name }) => name);
+    const remaining = expected.slice(expected.length - ordered.length);
+    const hasReceipt = names.includes(RECEIPT_NAME);
+    if ((!hasReceipt && !resume) ||
+        names.length !== ordered.length + Number(hasReceipt) ||
+        ordered.some(({ name }, index) => name !== remaining[index]) ||
+        (!resume && ordered.length !== expected.length))
+        throw new Error('partition directory contains unexpected content');
+    const partitionNames = ordered.map(({ name }) => name);
+    if (hasReceipt)
+        await validateReceipt(filesystem, originalPath, path, receipt, directory, partitionNames);
+    else
+        validateReceiptOutput(originalPath, receipt, directory, partitionNames);
+    for (const { name } of ordered) {
+        const file = join(path, name);
+        const info = await filesystem.lstat(file);
+        assertPartitionFile(info);
+        await validatePartition(file, info, receipt.partitions.find((partition) => partition.name === name)?.checksum);
+    }
+    if (!resume)
+        await writeResumeReceipt(receipt);
+    startDeleting();
+    for (const { name } of ordered)
+        await filesystem.rm(join(path, name), { force: false });
+    if (hasReceipt)
+        await filesystem.rm(join(path, RECEIPT_NAME), { force: false });
+    await filesystem.rmdir(path);
+    await removeResumeReceipt(receipt);
+}
+async function validateReceipt(filesystem, originalPath, path, receipt, directory, names) {
+    const marker = join(path, RECEIPT_NAME);
+    const info = await filesystem.lstat(marker);
+    assertPartitionFile(info);
+    let parsed;
+    try {
+        parsed = JSON.parse(await filesystem.readFile(marker, 'utf8'));
+    }
+    catch {
+        throw new Error('partition directory cleanup receipt is invalid');
+    }
+    if (!sameCleanupReceipt(parsed, receipt))
+        throw new Error('partition directory cleanup receipt does not match generated output');
+    validateReceiptOutput(originalPath, receipt, directory, names);
+}
+function validateReceiptOutput(originalPath, receipt, directory, names) {
+    if (receipt.schemaVersion !== 1 ||
+        receipt.directory !== originalPath ||
+        receipt.directoryDev !== directory.dev ||
+        receipt.directoryIno !== directory.ino ||
+        receipt.partitions.filter(({ name }) => names.includes(name)).length !== names.length ||
+        receipt.partitions
+            .filter(({ name }) => names.includes(name))
+            .some(({ name, checksum }, index) => name !== names[index] || checksum.algorithm !== 'sha256' || !checksum.value))
+        throw new Error('partition directory cleanup receipt does not match generated output');
+}

package/dist/agent-blackboard/snapshot-cleanup-key.d.mts

@@ -0,0 +1,14 @@
+import { link, lstat, mkdir, open, readdir, unlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+declare const defaults: {
+    lstat: typeof lstat;
+    mkdir: typeof mkdir;
+    open: typeof open;
+    readdir: typeof readdir;
+    link: typeof link;
+    unlink: typeof unlink;
+};
+export declare function setCleanupKeyTempDirectoryForTest(directory?: typeof tmpdir): void;
+export declare function setCleanupKeyFilesystemForTest(overrides?: Partial<typeof defaults>): void;
+export declare function loadCleanupSigningKey(): Promise<Buffer>;
+export {};

package/dist/agent-blackboard/snapshot-cleanup-key.mjs

@@ -0,0 +1,129 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { link, lstat, mkdir, open, readdir, unlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+const KEY_NAME = 'receipt-hmac-sha256.key';
+const KEY_BYTES = 32;
+const defaults = { lstat, mkdir, open, readdir, link, unlink };
+let filesystem = defaults;
+let temporaryDirectory = tmpdir;
+export function setCleanupKeyTempDirectoryForTest(directory = tmpdir) {
+    temporaryDirectory = directory;
+}
+export function setCleanupKeyFilesystemForTest(overrides) {
+    filesystem = { ...defaults, ...overrides };
+}
+function euid() {
+    if (typeof process.geteuid !== 'function')
+        throw new Error('snapshot cleanup receipts require a POSIX effective user ID');
+    return process.geteuid();
+}
+function assertDirectory(info, uid) {
+    if (info.isSymbolicLink() ||
+        !info.isDirectory() ||
+        info.uid !== uid ||
+        (Number(info.mode) & 0o777) !== 0o700)
+        throw new Error('snapshot cleanup key directory is not owner-only');
+}
+function assertKey(info, uid, links = 1) {
+    if (info.isSymbolicLink() ||
+        !info.isFile() ||
+        info.nlink !== links ||
+        info.uid !== uid ||
+        (Number(info.mode) & 0o777) !== 0o600)
+        throw new Error('snapshot cleanup key is not an owner-only regular file');
+}
+async function keyPath() {
+    const uid = euid();
+    const directory = join(temporaryDirectory(), `agent-blackboard-cleanup-${uid}`);
+    try {
+        await filesystem.mkdir(directory, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    assertDirectory(await filesystem.lstat(directory), uid);
+    return { path: join(directory, KEY_NAME), uid };
+}
+async function readKey(path, uid) {
+    try {
+        return await readPresentKey(path, uid);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        return readPresentKey(path, uid);
+    }
+}
+async function readPresentKey(path, uid) {
+    let before = await filesystem.lstat(path);
+    if (before.nlink === 2) {
+        assertKey(before, uid, 2);
+        const candidates = (await filesystem.readdir(dirname(path))).filter((name) => new RegExp(`^\\.${KEY_NAME.replaceAll('.', '\\.')}\\.[0-9a-f-]{36}$`).test(name));
+        const linked = await Promise.all(candidates.map(async (name) => ({
+            name,
+            info: await filesystem.lstat(join(dirname(path), name)),
+        })));
+        const matches = linked.filter(({ info }) => info.dev === before.dev && info.ino === before.ino);
+        if (matches.length !== 1)
+            throw new Error('snapshot cleanup key has an unsafe temporary link');
+        const temporary = join(dirname(path), matches[0].name);
+        const staged = matches[0].info;
+        assertKey(staged, uid, 2);
+        await filesystem.unlink(temporary);
+        before = await filesystem.lstat(path);
+    }
+    assertKey(before, uid);
+    const file = await filesystem.open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const after = await file.stat();
+        assertKey(after, uid);
+        if (after.dev !== before.dev || after.ino !== before.ino)
+            throw new Error('snapshot cleanup key changed while it was opened');
+        const key = await file.readFile();
+        if (key.byteLength !== KEY_BYTES)
+            throw new Error('snapshot cleanup key has an invalid length');
+        return key;
+    }
+    finally {
+        await file.close();
+    }
+}
+async function publishKey(path, uid) {
+    const temporary = join(dirname(path), `.${KEY_NAME}.${randomUUID()}`);
+    const file = await filesystem.open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        await file.writeFile(randomBytes(KEY_BYTES));
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    try {
+        await filesystem.link(temporary, path);
+    }
+    finally {
+        await filesystem.unlink(temporary).catch(() => undefined);
+    }
+    await readKey(path, uid);
+}
+export async function loadCleanupSigningKey() {
+    const { path, uid } = await keyPath();
+    try {
+        return await readKey(path, uid);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    try {
+        await publishKey(path, uid);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    return readKey(path, uid);
+}

package/dist/agent-blackboard/snapshot-cleanup-receipt.d.mts

@@ -0,0 +1,6 @@
+import type { SnapshotCleanupReceipt, SnapshotPartition } from './snapshot-types.mts';
+export declare const RECEIPT_NAME = ".agent-blackboard-cleanup-receipt.json";
+export declare function serializeCleanupReceipt(receipt: SnapshotCleanupReceipt): string;
+export declare function sameCleanupReceipt(left: unknown, right: SnapshotCleanupReceipt): boolean;
+export declare function writeCleanupReceipt(directory: string, partitions: Array<Pick<SnapshotPartition, 'path' | 'checksum'>>): Promise<SnapshotCleanupReceipt>;
+export declare function verifyCleanupReceipt(receipt: SnapshotCleanupReceipt): Promise<void>;

package/dist/agent-blackboard/snapshot-cleanup-receipt.mjs

@@ -0,0 +1,117 @@
+import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+import { chmod, lstat, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { loadCleanupSigningKey } from './snapshot-cleanup-key.mjs';
+export const RECEIPT_NAME = '.agent-blackboard-cleanup-receipt.json';
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function exact(value, keys) {
+    return Object.keys(value).length === keys.length && keys.every((key) => key in value);
+}
+function canonical(receipt, signature) {
+    if (!record(receipt) ||
+        !exact(receipt, signature
+            ? [
+                'schemaVersion',
+                'directory',
+                'directoryDev',
+                'directoryIno',
+                'token',
+                'partitions',
+                'signature',
+            ]
+            : ['schemaVersion', 'directory', 'directoryDev', 'directoryIno', 'token', 'partitions']))
+        throw new Error('partition directory cleanup receipt is invalid');
+    const { schemaVersion, directory, directoryDev, directoryIno, token, partitions } = receipt;
+    if (schemaVersion !== 1 ||
+        typeof directory !== 'string' ||
+        !directory ||
+        !Number.isSafeInteger(directoryDev) ||
+        directoryDev < 0 ||
+        !Number.isSafeInteger(directoryIno) ||
+        directoryIno < 0 ||
+        typeof token !== 'string' ||
+        !/^[0-9a-f-]{36}$/.test(token) ||
+        !Array.isArray(partitions))
+        throw new Error('partition directory cleanup receipt is invalid');
+    const normalizedDirectoryDev = directoryDev;
+    const normalizedDirectoryIno = directoryIno;
+    const normalized = partitions.map((partition) => {
+        if (!record(partition) ||
+            !exact(partition, ['name', 'checksum']) ||
+            typeof partition.name !== 'string' ||
+            !/^partition-[1-9][0-9]*\.jsonl$/.test(partition.name) ||
+            !record(partition.checksum) ||
+            !exact(partition.checksum, ['algorithm', 'value']) ||
+            partition.checksum.algorithm !== 'sha256' ||
+            typeof partition.checksum.value !== 'string' ||
+            !/^[0-9a-f]{64}$/.test(partition.checksum.value))
+            throw new Error('partition directory cleanup receipt is invalid');
+        return {
+            name: partition.name,
+            checksum: { algorithm: 'sha256', value: partition.checksum.value },
+        };
+    });
+    if (new Set(normalized.map(({ name }) => name)).size !== normalized.length)
+        throw new Error('partition directory cleanup receipt is invalid');
+    const unsigned = {
+        schemaVersion: 1,
+        directory,
+        directoryDev: normalizedDirectoryDev,
+        directoryIno: normalizedDirectoryIno,
+        token,
+        partitions: normalized,
+    };
+    if (!signature)
+        return JSON.stringify(unsigned);
+    if (typeof receipt.signature !== 'string' || !/^[0-9a-f]{64}$/.test(receipt.signature))
+        throw new Error('partition directory cleanup receipt signature is invalid');
+    return JSON.stringify({ ...unsigned, signature: receipt.signature });
+}
+function payload(receipt) {
+    return canonical(receipt, false);
+}
+export function serializeCleanupReceipt(receipt) {
+    return canonical(receipt, true);
+}
+export function sameCleanupReceipt(left, right) {
+    try {
+        return (serializeCleanupReceipt(left) === serializeCleanupReceipt(right));
+    }
+    catch {
+        return false;
+    }
+}
+export async function writeCleanupReceipt(directory, partitions) {
+    const info = await lstat(directory);
+    const unsigned = {
+        schemaVersion: 1,
+        directory,
+        directoryDev: info.dev,
+        directoryIno: info.ino,
+        token: randomUUID(),
+        partitions: partitions.map(({ path, checksum }) => ({ name: basename(path), checksum })),
+    };
+    const signature = createHmac('sha256', await loadCleanupSigningKey())
+        .update(payload(unsigned))
+        .digest('hex');
+    const receipt = { ...unsigned, signature };
+    const marker = join(directory, RECEIPT_NAME);
+    await writeFile(marker, serializeCleanupReceipt(receipt), { flag: 'wx', mode: 0o400 });
+    await chmod(marker, 0o400);
+    return receipt;
+}
+export async function verifyCleanupReceipt(receipt) {
+    if (!record(receipt) ||
+        typeof receipt.signature !== 'string' ||
+        !/^[0-9a-f]{64}$/.test(receipt.signature))
+        throw new Error('partition directory cleanup receipt signature is invalid');
+    const serialized = serializeCleanupReceipt(receipt);
+    const { signature, ...unsigned } = JSON.parse(serialized);
+    const expected = createHmac('sha256', await loadCleanupSigningKey())
+        .update(payload(unsigned))
+        .digest('hex');
+    if (!timingSafeEqual(Buffer.from(signature, 'hex'), Buffer.from(expected, 'hex')))
+        throw new Error('partition directory cleanup receipt signature is invalid');
+}

package/dist/agent-blackboard/snapshot-cleanup-resume.d.mts

@@ -0,0 +1,16 @@
+import { link, lstat, open, readFile, readdir, rm, unlink } from 'node:fs/promises';
+import type { SnapshotCleanupReceipt } from './snapshot-types.mts';
+declare const defaults: {
+    link: typeof link;
+    lstat: typeof lstat;
+    open: typeof open;
+    readFile: typeof readFile;
+    readdir: typeof readdir;
+    rm: typeof rm;
+    unlink: typeof unlink;
+};
+export declare function setResumeFilesystemForTest(overrides?: Partial<typeof defaults>): void;
+export declare function writeResumeReceipt(receipt: SnapshotCleanupReceipt): Promise<void>;
+export declare function removeResumeReceipt(receipt: SnapshotCleanupReceipt): Promise<void>;
+export declare function requireResumeReceipt(receipt: SnapshotCleanupReceipt): Promise<void>;
+export {};

package/dist/agent-blackboard/snapshot-cleanup-resume.mjs

@@ -0,0 +1,98 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { link, lstat, open, readFile, readdir, rm, unlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { sameCleanupReceipt, verifyCleanupReceipt } from './snapshot-cleanup-receipt.mjs';
+const defaults = { link, lstat, open, readFile, readdir, rm, unlink };
+let filesystem = defaults;
+export function setResumeFilesystemForTest(overrides) {
+    filesystem = { ...defaults, ...overrides };
+}
+function pathFor(receipt) {
+    if (!/^[0-9a-f-]{36}$/.test(receipt.token))
+        throw new Error('partition directory cleanup receipt has an invalid token');
+    return join(tmpdir(), `.agent-blackboard-cleanup-${receipt.token}.resume.json`);
+}
+function temporaryPath(receipt) {
+    return `${pathFor(receipt)}.${randomUUID()}.tmp`;
+}
+function assertResumeFile(info, links = 1) {
+    if (info.isSymbolicLink() ||
+        !info.isFile() ||
+        info.nlink !== links ||
+        (Number(info.mode) & 0o777) !== 0o400 ||
+        (typeof process.geteuid === 'function' && info.uid !== process.geteuid()))
+        throw new Error('partition directory cleanup resume metadata is unsafe');
+}
+async function read(receipt) {
+    const path = pathFor(receipt);
+    let before = await filesystem.lstat(path);
+    if (before.nlink === 2) {
+        assertResumeFile(before, 2);
+        const candidates = (await filesystem.readdir(tmpdir())).filter((name) => new RegExp(`^${path.split('/').at(-1).replaceAll('.', '\\.')}(?:\\.[0-9a-f-]{36}\\.tmp)$`).test(name));
+        const linked = await Promise.all(candidates.map(async (name) => ({
+            name,
+            info: await filesystem.lstat(join(tmpdir(), name)),
+        })));
+        const matches = linked.filter(({ info }) => info.dev === before.dev && info.ino === before.ino);
+        if (matches.length !== 1)
+            throw new Error('partition directory cleanup resume metadata is unsafe');
+        const temporary = join(tmpdir(), matches[0].name);
+        const staged = matches[0].info;
+        assertResumeFile(staged, 2);
+        await filesystem.unlink(temporary);
+        before = await filesystem.lstat(path);
+    }
+    assertResumeFile(before);
+    const contents = await filesystem.readFile(path, 'utf8');
+    const after = await filesystem.lstat(path);
+    assertResumeFile(after);
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch {
+        throw new Error('partition directory cleanup resume metadata does not match receipt');
+    }
+    if (before.dev !== after.dev || before.ino !== after.ino || !sameCleanupReceipt(parsed, receipt))
+        throw new Error('partition directory cleanup resume metadata does not match receipt');
+    await verifyCleanupReceipt(receipt);
+}
+export async function writeResumeReceipt(receipt) {
+    const path = pathFor(receipt);
+    const temporary = temporaryPath(receipt);
+    let file;
+    try {
+        file = await filesystem.open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o400);
+        const { serializeCleanupReceipt } = await import('./snapshot-cleanup-receipt.mjs');
+        await file.writeFile(serializeCleanupReceipt(receipt));
+        await file.sync();
+        await file.close();
+        file = undefined;
+        await filesystem.link(temporary, path);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    finally {
+        await file?.close();
+        await filesystem.unlink(temporary).catch(() => undefined);
+    }
+    await read(receipt);
+}
+export async function removeResumeReceipt(receipt) {
+    try {
+        await read(receipt);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    await filesystem.rm(pathFor(receipt), { force: false });
+}
+export async function requireResumeReceipt(receipt) {
+    await read(receipt);
+}