@achieveai/hitl-mcp-server 2.9.1 → 2.11.0

package/dist/plan-review.d.ts

@@ -0,0 +1,54 @@
+import type { InlineComment, PlanVerdict, PlanReviewResponseBody } from './types.js';
+/**
+ * Pure shaping and validation of a plan-review response.
+ *
+ * Kept out of mcp-server.ts so it can be tested without booting an MCP server,
+ * and because the rules here are the authoritative ones — the review window
+ * mirrors them for fast feedback, but the server decides.
+ */
+/** Every verdict the wire may legitimately carry. */
+export declare const VALID_VERDICTS: readonly PlanVerdict[];
+/** Raised when a response cannot be accepted as submitted. */
+export declare class ReviewResponseError extends Error {
+    constructor(message: string);
+}
+/** What ReviewPlan returns to the agent. */
+export interface ReviewPlanResult {
+    success: true;
+    timestamp: number;
+    respondedFrom: string;
+    verdict: PlanVerdict;
+    overallFeedback: string;
+    inlineComments: InlineComment[];
+    revision: number;
+    isNewPlan: boolean;
+    /** 'sha256:<hex>' of the content the human actually reviewed (A-8). */
+    snapshotHash: string;
+}
+/**
+ * Coerce an unknown verdict string.
+ *
+ * An unrecognized value is a client that is broken or newer than this server —
+ * never a human decision. Reporting it as `'skipped'` would tell the agent the
+ * human deliberately declined, and would route around the A-5 gate that makes
+ * `changes_requested` say what to change. Refusing is the only honest answer.
+ */
+export declare function parseVerdict(raw: unknown): PlanVerdict;
+/**
+ * Trim, drop empties, and sort inline comments into a canonical order.
+ *
+ * The comparator is total — it falls through to the comment text — so the same
+ * set of comments serializes byte-identically no matter which order the human
+ * clicked them in (A-4). A merely stable sort would not achieve that: two
+ * comments on one anchor would keep their insertion order.
+ */
+export declare function normalizeInlineComments(raw: unknown, defaultPath: string): InlineComment[];
+/**
+ * Normalize a decoded response body and enforce the server-side rules.
+ *
+ * `changes_requested` and `rejected` need either overall feedback or at least
+ * one surviving inline comment; anything else leaves the agent told to change
+ * something with no indication of what (A-5).
+ */
+export declare function normalizeResponseBody(verdict: PlanVerdict, raw: unknown, defaultPath: string): PlanReviewResponseBody;
+//# sourceMappingURL=plan-review.d.ts.map

package/dist/plan-review.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-review.d.ts","sourceRoot":"","sources":["../src/plan-review.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAErF;;;;;;GAMG;AAEH,qDAAqD;AACrD,eAAO,MAAM,cAAc,EAAE,SAAS,WAAW,EAMhD,CAAC;AAKF,8DAA8D;AAC9D,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,WAAW,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,uEAAuE;IACvE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CAKtD;AAgBD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,aAAa,EAAE,CA+B1F;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,WAAW,EACpB,GAAG,EAAE,OAAO,EACZ,WAAW,EAAE,MAAM,GAClB,sBAAsB,CAkBxB"}

package/dist/plan-review.js

@@ -0,0 +1,110 @@
+/**
+ * Pure shaping and validation of a plan-review response.
+ *
+ * Kept out of mcp-server.ts so it can be tested without booting an MCP server,
+ * and because the rules here are the authoritative ones — the review window
+ * mirrors them for fast feedback, but the server decides.
+ */
+/** Every verdict the wire may legitimately carry. */
+export const VALID_VERDICTS = [
+    'approved',
+    'changes_requested',
+    'rejected',
+    'skipped',
+    'cancelled',
+];
+/** Verdicts that say "change something" and therefore must say what (A-5). */
+const VERDICTS_REQUIRING_FEEDBACK = ['changes_requested', 'rejected'];
+/** Raised when a response cannot be accepted as submitted. */
+export class ReviewResponseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ReviewResponseError';
+    }
+}
+/**
+ * Coerce an unknown verdict string.
+ *
+ * An unrecognized value is a client that is broken or newer than this server —
+ * never a human decision. Reporting it as `'skipped'` would tell the agent the
+ * human deliberately declined, and would route around the A-5 gate that makes
+ * `changes_requested` say what to change. Refusing is the only honest answer.
+ */
+export function parseVerdict(raw) {
+    if (VALID_VERDICTS.includes(raw))
+        return raw;
+    throw new ReviewResponseError(`Unrecognized verdict ${JSON.stringify(raw)}; expected one of ${VALID_VERDICTS.join(', ')}.`);
+}
+/**
+ * Order two strings by Unicode code point.
+ *
+ * `localeCompare` is wrong here twice over: it returns 0 for strings that are
+ * canonically equivalent but not byte-equal (NFC vs NFD, which is exactly what
+ * a macOS and a Windows client produce for the same accented word), and its
+ * ordering depends on the host locale. A-4 requires the same comments to
+ * serialize to the same bytes on every device, so the comparator has to be
+ * decided by the bytes (M3).
+ */
+function compareCodePoints(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Trim, drop empties, and sort inline comments into a canonical order.
+ *
+ * The comparator is total — it falls through to the comment text — so the same
+ * set of comments serializes byte-identically no matter which order the human
+ * clicked them in (A-4). A merely stable sort would not achieve that: two
+ * comments on one anchor would keep their insertion order.
+ */
+export function normalizeInlineComments(raw, defaultPath) {
+    if (!Array.isArray(raw))
+        return [];
+    const cleaned = [];
+    for (const entry of raw) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const c = entry;
+        const comment = typeof c.comment === 'string' ? c.comment.trim() : '';
+        if (comment === '')
+            continue; // An empty comment anchors nothing.
+        const startLine = toLineNumber(c.startLine, 1);
+        const endLine = Math.max(startLine, toLineNumber(c.endLine, startLine));
+        cleaned.push({
+            path: typeof c.path === 'string' && c.path !== '' ? c.path : defaultPath,
+            startLine,
+            endLine,
+            side: c.side === 'old' ? 'old' : 'new',
+            comment,
+        });
+    }
+    return cleaned.sort((a, b) => compareCodePoints(a.path, b.path) ||
+        a.startLine - b.startLine ||
+        a.endLine - b.endLine ||
+        compareCodePoints(a.side, b.side) ||
+        compareCodePoints(a.comment, b.comment));
+}
+/**
+ * Normalize a decoded response body and enforce the server-side rules.
+ *
+ * `changes_requested` and `rejected` need either overall feedback or at least
+ * one surviving inline comment; anything else leaves the agent told to change
+ * something with no indication of what (A-5).
+ */
+export function normalizeResponseBody(verdict, raw, defaultPath) {
+    const body = (typeof raw === 'object' && raw !== null ? raw : {});
+    const overallFeedback = typeof body.overallFeedback === 'string' ? body.overallFeedback.trim() : '';
+    const inlineComments = normalizeInlineComments(body.inlineComments, defaultPath);
+    if (VERDICTS_REQUIRING_FEEDBACK.includes(verdict) &&
+        overallFeedback === '' &&
+        inlineComments.length === 0) {
+        throw new ReviewResponseError(`Verdict '${verdict}' requires either overall feedback or at least one inline comment, ` +
+            `but the response carried neither.`);
+    }
+    return { overallFeedback, inlineComments };
+}
+function toLineNumber(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 1
+        ? Math.floor(value)
+        : fallback;
+}
+//# sourceMappingURL=plan-review.js.map

package/dist/plan-review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-review.js","sourceRoot":"","sources":["../src/plan-review.ts"],"names":[],"mappings":"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"}

package/dist/setup.d.ts

@@ -1,7 +1,7 @@
 /** Result of a single setup step. */
 export interface SetupStepResult {
     step: string;
-    status: 'ok' | 'created' | 'launched' | 'already_running' | 'not_found' | 'error';
+    status: 'ok' | 'created' | 'launched' | 'already_running' | 'not_found' | 'error' | 'warning';
     message: string;
 }
 /** Aggregated result of the full setup process. */
@@ -24,18 +24,35 @@ export declare function isProcessRunning(processName: string): boolean;
 export declare function findClientBinary(serverDir: string): string | null;
 /**
  * Launch the client binary as a fully detached background process.
+ *
+ * The `'error'` listener is not optional. Node reports a failed exec (ENOENT,
+ * EACCES) by emitting `'error'` asynchronously, and an unhandled `'error'` on
+ * an EventEmitter is rethrown as an uncaught exception — which, from inside a
+ * tool call, kills the whole MCP server instead of returning a message the
+ * agent can act on (H9).
  */
 export declare function launchClient(binaryPath: string): void;
+/** Outcome of ensureClientRunning — the caller must not publish when `ok` is false. */
+export interface ClientRunningResult {
+    ok: boolean;
+    /** Why the client is unavailable. Present only when `ok` is false. */
+    reason?: string;
+}
 /**
  * Ensure the HITL client is running. Finds and launches it if needed.
- * Logs to stderr only — safe to call from the hot path of ask_human.
+ *
+ * Returns the outcome rather than only logging it: with timeouts removed, a
+ * caller that publishes to a topic nobody is subscribed to blocks forever and
+ * the human never sees anything (A-10). Both "binary not found" and "launch
+ * failed" must reach the agent as an error before anything is published.
  */
-export declare function ensureClientRunning(serverDir: string): void;
+export declare function ensureClientRunning(serverDir: string): ClientRunningResult;
 /**
  * Perform the full HITL client setup:
  *   1. Ensure ~/.hitl/config.json exists
- *   2. Check if the client process is running
- *   3. Find and launch the client binary if needed
+ *   2. Non-fatal diagnostic: warn if the auto-background env guard isn't active
+ *   3. Check if the client process is running
+ *   4. Find and launch the client binary if needed
  *
  * @param serverDir - The directory of the running server JS (used to resolve relative binary paths)
  */

package/dist/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"AAMA,qCAAqC;AACrC,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,IAAI,GAAG,SAAS,GAAG,UAAU,GAAG,iBAAiB,GAAG,WAAW,GAAG,OAAO,CAAC;IAClF,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;CACjB;AAkBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAe7D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA0BjE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAMrD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAgB3D;AAqBD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAmD1E"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"AAOA,qCAAqC;AACrC,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,IAAI,GAAG,SAAS,GAAG,UAAU,GAAG,iBAAiB,GAAG,WAAW,GAAG,OAAO,GAAG,SAAS,CAAC;IAC9F,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;CACjB;AAkBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAe7D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA0BjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CASrD;AAED,uFAAuF;AACvF,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,CA0B1E;AAqBD;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAmE1E"}

package/dist/setup.js

@@ -1,8 +1,9 @@
-import { existsSync, chmodSync } from 'fs';
+import { existsSync, chmodSync, accessSync, constants } from 'fs';
 import { execSync, spawn } from 'child_process';
 import { homedir, arch } from 'os';
 import path from 'path';
 import { saveConfig, generateDefaultConfig, getConfigPath } from './config.js';
+import { detectAutoBackgroundStatus, buildAutoBackgroundRemediationText } from './host-settings.js';
 /**
  * Get the platform-specific subdirectory name for bundled binaries.
  * Maps Node.js platform/arch to the artifact names used in CI.
@@ -73,32 +74,54 @@ export function findClientBinary(serverDir) {
 }
 /**
  * Launch the client binary as a fully detached background process.
+ *
+ * The `'error'` listener is not optional. Node reports a failed exec (ENOENT,
+ * EACCES) by emitting `'error'` asynchronously, and an unhandled `'error'` on
+ * an EventEmitter is rethrown as an uncaught exception — which, from inside a
+ * tool call, kills the whole MCP server instead of returning a message the
+ * agent can act on (H9).
  */
 export function launchClient(binaryPath) {
     const child = spawn(binaryPath, [], {
         detached: true,
         stdio: 'ignore',
     });
+    child.on('error', (err) => {
+        console.error(`HITL client at ${binaryPath} failed to start: ${err.message}`);
+    });
     child.unref();
 }
 /**
  * Ensure the HITL client is running. Finds and launches it if needed.
- * Logs to stderr only — safe to call from the hot path of ask_human.
+ *
+ * Returns the outcome rather than only logging it: with timeouts removed, a
+ * caller that publishes to a topic nobody is subscribed to blocks forever and
+ * the human never sees anything (A-10). Both "binary not found" and "launch
+ * failed" must reach the agent as an error before anything is published.
  */
 export function ensureClientRunning(serverDir) {
     const binaryName = process.platform === 'win32' ? 'hitl-client.exe' : 'hitl-client';
     if (isProcessRunning(binaryName)) {
-        return;
+        return { ok: true };
     }
     const binaryPath = findClientBinary(serverDir);
-    if (binaryPath) {
-        try {
-            launchClient(binaryPath);
-            console.error(`Auto-launched HITL client from ${binaryPath}`);
-        }
-        catch (err) {
-            console.error(`Failed to auto-launch HITL client: ${err}`);
-        }
+    if (!binaryPath) {
+        return { ok: false, reason: buildNotFoundMessage(serverDir) };
+    }
+    try {
+        // Checked synchronously so an unusable binary becomes a returned reason
+        // rather than an async 'error' event that arrives after this function has
+        // already told the caller everything was fine.
+        accessSync(binaryPath, constants.X_OK);
+        launchClient(binaryPath);
+        console.error(`Auto-launched HITL client from ${binaryPath}`);
+        return { ok: true };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: `Failed to launch the HITL client at ${binaryPath}: ${err instanceof Error ? err.message : String(err)}`,
+        };
     }
 }
 /**
@@ -122,8 +145,9 @@ function buildNotFoundMessage(serverDir) {
 /**
  * Perform the full HITL client setup:
  *   1. Ensure ~/.hitl/config.json exists
- *   2. Check if the client process is running
- *   3. Find and launch the client binary if needed
+ *   2. Non-fatal diagnostic: warn if the auto-background env guard isn't active
+ *   3. Check if the client process is running
+ *   4. Find and launch the client binary if needed
  *
  * @param serverDir - The directory of the running server JS (used to resolve relative binary paths)
  */
@@ -150,13 +174,26 @@ export async function performSetup(serverDir) {
             });
         }
     }
-    // Step 2: Check if client is already running
+    // Step 2 (non-fatal diagnostic): warn if the auto-background env guard
+    // isn't active, so a blocking HITL call can't get yanked into the
+    // background before the human answers. This never flips overallSuccess —
+    // it's advisory only, and setup never writes to the host settings file
+    // itself; the user (or a future explicit command) applies the fix.
+    const autoBackgroundStatus = detectAutoBackgroundStatus();
+    steps.push({
+        step: 'auto-background-env',
+        status: autoBackgroundStatus.active ? 'ok' : 'warning',
+        message: autoBackgroundStatus.active
+            ? `Auto-background guard is active (${autoBackgroundStatus.activeInEnv ? 'current session' : 'configured for next restart'})`
+            : buildAutoBackgroundRemediationText(),
+    });
+    // Step 3: Check if client is already running
     const binaryName = process.platform === 'win32' ? 'hitl-client.exe' : 'hitl-client';
     if (isProcessRunning(binaryName)) {
         steps.push({ step: 'client', status: 'already_running', message: 'HITL client is already running' });
         return { success: overallSuccess, steps, summary: formatSummary(steps) };
     }
-    // Step 3: Find and launch binary
+    // Step 4: Find and launch binary
     const binaryPath = findClientBinary(serverDir);
     if (!binaryPath) {
         overallSuccess = false;

package/dist/setup.js.map

@@ -1 +1 @@
-{"version":3,"file":"setup.js","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"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"}

package/dist/snapshot-store.d.ts

@@ -0,0 +1,104 @@
+/**
+ * On-disk revision history for reviewed plans.
+ *
+ *   ~/.hitl/plans/<sha256(identityKey)>/<sha256(normalizedPath)>/
+ *     latest.json          {displayPath, digest, revision, createdAt}
+ *     objects/<sha256>     immutable content, one file per unique revision
+ *     drafts/<planId>.json in-flight comments — written by the client, not here
+ *
+ * Deliberately lock-free. Two MCP server processes reviewing the same plan can
+ * race `latest.json`, but `objects/<sha256>` is content-addressed and immutable,
+ * so a lost race costs cosmetic staleness (whose revision is called "latest"),
+ * never corruption. Last writer wins.
+ *
+ * Crash safety is the atomic temp-file + rename on `latest.json` (B-9): the
+ * object lands first, then the pointer flips in one operation, so an
+ * interrupted write leaves the previous `latest.json` byte-identical.
+ */
+/** The trusted contents of `latest.json`. */
+export interface SnapshotMeta {
+    /** Repo-relative display path — never absolute (F-9). */
+    displayPath: string;
+    /** Bare lowercase sha256 hex of the content. `snapshotHash` prefixes it with 'sha256:'. */
+    digest: string;
+    revision: number;
+    /** Unix millis. */
+    createdAt: number;
+}
+/** Where a given plan file's history lives, and how it is named on the wire. */
+export interface PlanIdentity {
+    /** Stable across revisions; keys drafts. */
+    planId: string;
+    /** Absolute directory holding latest.json / objects / drafts. */
+    dir: string;
+    /** Repo-relative when the plan is inside a repo, else just the basename (F-9). */
+    displayPath: string;
+    /** Absolute repo root, or null when the plan is not in a work tree. */
+    repoRoot: string | null;
+    /** The resolved, symlink-free plan path this identity describes. */
+    resolvedPath: string;
+}
+/** Outcome of recording a revision. */
+export interface RecordedRevision {
+    revision: number;
+    /** Bare sha256 hex of the content just recorded. */
+    digest: string;
+    isNewPlan: boolean;
+    /** The revision this one supersedes, or null on a first review. */
+    previous: SnapshotMeta | null;
+    /** Content of `previous`, or null when there is none / the object is missing. */
+    previousContent: string | null;
+}
+/** A revision whose content is stored but which is not yet the plan's latest. */
+export interface PreparedRevision extends RecordedRevision {
+    /**
+     * Flip `latest.json` to this revision, making it the baseline the next review
+     * diffs against. Until this is called the object sits in `objects/` and the
+     * plan's history is unchanged.
+     */
+    commit(): RecordedRevision;
+}
+/** Root of the snapshot store. Overridable so tests never touch a real home dir. */
+export declare function getPlansRoot(): string;
+/**
+ * Locate a plan file's history directory and its display name.
+ *
+ * Identity is keyed on the repo root when there is one, else on the containing
+ * directory — so the same relative path in two different repos gets two
+ * identities (B-7), while two spellings of one Windows path collapse to one
+ * (B-10). Git is resolved from the plan's own directory, never `process.cwd()`,
+ * because the plan usually lives in a sibling repo (B-6).
+ */
+export declare function resolvePlanIdentity(resolvedPath: string): PlanIdentity;
+/**
+ * Validate a raw `latest.json` body before anything trusts it.
+ *
+ * Returns null — never a partially-trusted object — when the digest is not 64
+ * lowercase hex, the revision is not a positive integer, `createdAt` is zero,
+ * or the recorded `displayPath` names a different file than the one being
+ * reviewed. A rejected pointer degrades to "no history", which restarts the
+ * revision count rather than diffing against something unverified.
+ */
+export declare function parseLatest(raw: string, expectedDisplayPath: string): SnapshotMeta | null;
+/** Read and validate `latest.json`, or null when absent or untrustworthy. */
+export declare function readLatest(identity: PlanIdentity): SnapshotMeta | null;
+/** Read a stored revision by digest, or null when the object is missing. */
+export declare function readObject(identity: PlanIdentity, digest: string): string | null;
+/**
+ * Stage `content` as the next revision of this plan.
+ *
+ * Byte-identical content still advances the revision: a resubmit is a distinct
+ * review event, and the human must still be able to select every line of an
+ * unchanged plan (B-3).
+ *
+ * The pointer flip is deliberately a separate step. `latest.json` is what the
+ * next review diffs against, so writing it before the plan has actually reached
+ * the human means a failed publish silently rebases the next review onto a
+ * revision nobody ever saw — the change the human was meant to review vanishes
+ * from the diff (M6). Callers commit once the revision is out the door.
+ *
+ * The object is written either way; it is content-addressed and immutable, so
+ * an uncommitted one costs a few KB of orphaned disk and nothing else.
+ */
+export declare function prepareRevision(identity: PlanIdentity, content: string): PreparedRevision;
+//# sourceMappingURL=snapshot-store.d.ts.map

package/dist/snapshot-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-store.d.ts","sourceRoot":"","sources":["../src/snapshot-store.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;GAgBG;AAEH,6CAA6C;AAC7C,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IACZ,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,uCAAuC;AACvC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,mEAAmE;IACnE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9B,iFAAiF;IACjF,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,iFAAiF;AACjF,MAAM,WAAW,gBAAiB,SAAQ,gBAAgB;IACxD;;;;OAIG;IACH,MAAM,IAAI,gBAAgB,CAAC;CAC5B;AAED,oFAAoF;AACpF,wBAAgB,YAAY,IAAI,MAAM,CAErC;AASD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,YAAY,CAgBtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAiBzF;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,QAAQ,EAAE,YAAY,GAAG,YAAY,GAAG,IAAI,CAStE;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAShF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAmCzF"}