@cluesmith/codev 3.2.4 → 3.3.1

package/dist/agent-farm/commands/reset/index.js

@@ -0,0 +1,488 @@
+/**
+ * Reset orchestrator — the `afx refresh` state machine (Spec 1273).
+ *
+ * Composes the verified parts from phases 1–5 into the flow the architect ran by
+ * hand on 2026-07-27: request save-state → verify the receipt → wait for the
+ * turn to end → `/clear` → re-orient.
+ *
+ * ## Why this is a state machine over injected ports
+ *
+ * Reset is destructive in a way almost nothing else in Agent Farm is: `/clear`
+ * discards a builder's entire conversation, and there is no undo. Every safety
+ * property is therefore an ORDERING property — "the clear never happens before
+ * X" — and ordering is exactly what is hardest to prove by reading code.
+ *
+ * So the orchestrator does two things no ordinary command does:
+ *
+ *   1. Every externally-visible action goes through a port (`clock`, `fs`,
+ *      `sendMessage`, `sendRaw`, `sendEscape`). Nothing here touches Tower, a
+ *      PTY or the filesystem directly.
+ *   2. Every action is appended to an ordered **step log** before it is
+ *      performed.
+ *
+ * The invariant tests then assert over that log — that `clear` never appears
+ * without `assemble` before it, that `escalate-esc` never precedes
+ * `receipt-accepted`, that an aborted run contains no `clear` at all. That turns
+ * "impossible by construction" from a claim in a comment into something a test
+ * can fail on.
+ *
+ * ## The invariants, and where each is enforced
+ *
+ * - **R1** (never clear without a saved re-orientation): `runReset` assembles and
+ *   writes `.builder-reorient.md` at step 2, before any destructive step exists
+ *   in the log. Assembly failure returns before the request is even sent.
+ * - **R2** (never clear without a verified receipt): the poll loop only leaves
+ *   `awaiting-receipt` on `accepted`; every other exit path returns an aborted
+ *   result.
+ * - **R3** (complete-or-abort re-orientation): delegated wholesale to
+ *   `assembleReorientation`, which throws rather than emitting a partial frame.
+ * - **R4** (never clear a builder mid-turn): quiescence is a bounded wait, then
+ *   at most ONE ESC escalation, then a second bounded wait. Still not quiet
+ *   aborts — there is deliberately no third attempt and no "clear anyway".
+ */
+import { assembleReorientation, ReorientationAssemblyError, } from './reorient.js';
+import { buildSaveRequest, describeReceiptFailure, generateNonce, stateFilePath, verifyReceipt, } from './receipt.js';
+import { DEFAULT_MIN_BYTES, DEFAULT_POLL_INTERVAL_MS, DEFAULT_QUIESCE_POST_ESCALATION_TIMEOUT_MS, DEFAULT_QUIESCE_TIMEOUT_MS, DEFAULT_QUIET_WINDOW_MS, DEFAULT_RECEIPT_TIMEOUT_MS, DEFAULT_STABILITY_WINDOW_MS, REORIENT_FILE_NAME, } from './constants.js';
+/** Thrown for conditions that must stop the run before anything is touched. */
+export class ResetPreflightError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ResetPreflightError';
+    }
+}
+// ============================================================================
+// Orchestration
+// ============================================================================
+export async function runReset(options) {
+    const { context, fs, clock, terminal, buildSpawnPrompt, buildResumeNotice, issue, addendum, dryRun = false, interruptFirst = false, receiptTimeoutMs = DEFAULT_RECEIPT_TIMEOUT_MS, pollIntervalMs = DEFAULT_POLL_INTERVAL_MS, minBytes = DEFAULT_MIN_BYTES, stabilityWindowMs = DEFAULT_STABILITY_WINDOW_MS, quietWindowMs = DEFAULT_QUIET_WINDOW_MS, quiesceTimeoutMs = DEFAULT_QUIESCE_TIMEOUT_MS, quiescePostEscalationTimeoutMs = DEFAULT_QUIESCE_POST_ESCALATION_TIMEOUT_MS, stateFileName, } = options;
+    const steps = [];
+    const step = (name, detail) => {
+        steps.push({ name, at: clock.now(), detail });
+    };
+    const statePath = resolveStatePath(context.worktree, stateFileName);
+    const reorientPath = stateFilePath(context.worktree, REORIENT_FILE_NAME);
+    const nonce = generateNonce();
+    // --------------------------------------------------------------------
+    // 0. Timing-parameter sanity.
+    //
+    // Validated HERE as well as at the CLI boundary, because these values do not
+    // merely tune the run — each one can switch OFF a safety gate while the run
+    // still reports success. A negative quiet window makes every quiescence check
+    // pass instantly (R4 gone); a non-positive minimum accepts any state file
+    // however empty (R2's substance floor gone); a NaN timeout produces a NaN
+    // deadline, and since every comparison against NaN is false, the wait never
+    // expires and the command hangs.
+    //
+    // The orchestrator is the component that OWNS these invariants, so it does
+    // not delegate their preconditions to its callers. A programmatic caller must
+    // not be able to disable R2 or R4 by passing a number.
+    // --------------------------------------------------------------------
+    requirePositive(receiptTimeoutMs, 'receiptTimeoutMs');
+    requirePositive(pollIntervalMs, 'pollIntervalMs');
+    requirePositive(minBytes, 'minBytes');
+    requirePositive(stabilityWindowMs, 'stabilityWindowMs');
+    requirePositive(quietWindowMs, 'quietWindowMs');
+    requirePositive(quiesceTimeoutMs, 'quiesceTimeoutMs');
+    requirePositive(quiescePostEscalationTimeoutMs, 'quiescePostEscalationTimeoutMs');
+    // --------------------------------------------------------------------
+    // 1. Preflight. Everything that can refuse does so before ANY write.
+    // --------------------------------------------------------------------
+    // Harness capability is checked first and aborts loudly, naming the harness.
+    // No substituted mechanism: if this agent has no in-session context reset,
+    // there is no partial version of a reset worth doing (fail fast).
+    if (!context.harness.supportsContextReset) {
+        throw new ResetPreflightError(`Builder '${context.builderId}' runs under the '${context.harnessName}' harness, ` +
+            `which has no in-session context reset. Refresh is a no-op there — there is no ` +
+            `substitute mechanism. Use the boundary-recycle pattern instead: let the builder ` +
+            `finish, then respawn with 'afx spawn <id> --resume'.`);
+    }
+    const observed = await terminal.observe();
+    if (!observed.exists) {
+        throw new ResetPreflightError(`Builder '${context.builderId}' has no live terminal. Refresh writes to a running ` +
+            `session; there is nothing to clear. Check 'afx status'.`);
+    }
+    // Writability is checked HERE, in preflight, not left to fail on the first
+    // send. The plan's contract is validate-before-touch: discovering the problem
+    // later would mean `.builder-reorient.md` had already been written to the
+    // builder's worktree for a reset that could never proceed.
+    //
+    // `status: 'running'` is not sufficient evidence — a session whose shellper
+    // connection died reports exactly that while dropping every write (#1198),
+    // which is the specific case this catches.
+    if (observed.writable === false) {
+        throw new ResetPreflightError(`Builder '${context.builderId}' has a terminal that is not accepting input ` +
+            `(its process connection is down — #1198). Refresh would send a save request that ` +
+            `is silently dropped. Nothing has been touched. Check Tower logs, or retry once ` +
+            `the session reconnects.`);
+    }
+    step('resolve', `${context.protocol}/${context.mode} in ${context.worktree}`);
+    // --------------------------------------------------------------------
+    // 2. Assemble + persist the re-orientation. THIS IS R1's ENFORCEMENT POINT.
+    //
+    // Everything destructive is downstream of here. A throw from assembly (R3)
+    // propagates with the builder completely untouched — no message sent, no
+    // keystroke written.
+    // --------------------------------------------------------------------
+    let payload;
+    try {
+        payload = assembleReorientation({
+            context,
+            statePath,
+            addendum,
+            buildSpawnPrompt,
+            buildResumeNotice,
+            issue,
+        });
+    }
+    catch (err) {
+        if (err instanceof ReorientationAssemblyError) {
+            throw new ResetPreflightError(`Refusing to refresh: ${err.message} The builder has not been touched.`);
+        }
+        throw err;
+    }
+    step('assemble', `${payload.inline.split('\n').length} inline lines`);
+    const saveRequest = buildSaveRequest(nonce, statePath);
+    // A dry run stops here, having proved the two things worth proving before a
+    // real run: that assembly succeeds (R3) and what the builder would receive.
+    // Zero writes reach the builder, which is what makes R1 auditable by
+    // inspection rather than by trust.
+    if (dryRun) {
+        return {
+            outcome: 'dry-run',
+            steps,
+            nonce,
+            statePath,
+            reorientPath,
+            payload,
+            saveRequest,
+        };
+    }
+    fs.write(reorientPath, payload.longForm);
+    step('write-reorient-file', reorientPath);
+    // --------------------------------------------------------------------
+    // 3. Optional pre-emptive interrupt.
+    //
+    // Default OFF. A builder that is reachable should be ASKED to save, not
+    // interrupted first — an ESC into a working builder costs it the turn it was
+    // mid-way through. This is opt-in for the case the architect already knows
+    // about: a builder wedged on a foreground wait, where every queued message
+    // including the save request would go unread until the turn ends.
+    // --------------------------------------------------------------------
+    if (interruptFirst) {
+        await terminal.sendEscape();
+        step('interrupt-first');
+    }
+    // --------------------------------------------------------------------
+    // 4–5. Request the save, then gate on a VERIFIED receipt (R2).
+    // --------------------------------------------------------------------
+    await terminal.sendMessage(saveRequest);
+    step('send-save-request', `nonce ${nonce}`);
+    const receipt = await awaitReceipt({
+        fs,
+        clock,
+        statePath,
+        nonce,
+        minBytes,
+        stabilityWindowMs,
+        pollIntervalMs,
+        timeoutMs: receiptTimeoutMs,
+    });
+    if (receipt.status !== 'accepted') {
+        // Abort with the builder's context fully intact. The state file may exist
+        // and be perfectly good — it simply was not PROVEN good, and an unproven
+        // save is not a basis for discarding a conversation.
+        return {
+            outcome: 'aborted',
+            steps,
+            abortReason: `Save-state receipt not verified. ${describeReceiptFailure(receipt, statePath, minBytes)}`,
+            nonce,
+            statePath,
+            reorientPath,
+            payload,
+            saveRequest,
+        };
+    }
+    step('receipt-accepted', `${receipt.bytes} bytes`);
+    // --------------------------------------------------------------------
+    // 6. Quiescence (R4).
+    //
+    // The receipt proves the file is written; it does NOT prove the turn ended.
+    // A builder that wrote the file and kept working would receive `/clear` as
+    // literal text mid-turn — the keystroke would land in its input buffer rather
+    // than executing. Hence a real silence check.
+    // --------------------------------------------------------------------
+    let quiet = await awaitQuiescence({
+        terminal,
+        clock,
+        quietWindowMs,
+        timeoutMs: quiesceTimeoutMs,
+        pollIntervalMs,
+    });
+    if (!quiet.quiet) {
+        if (quiet.reason === 'terminal-gone') {
+            return {
+                outcome: 'aborted',
+                steps,
+                abortReason: `Builder '${context.builderId}' lost its terminal while waiting for its turn to end. ` +
+                    `Nothing was cleared. Its saved state is at ${statePath} — that file survives the ` +
+                    `terminal, so respawn with 'afx spawn <id> --resume' and point the new session at it.`,
+                nonce,
+                statePath,
+                reorientPath,
+                payload,
+                saveRequest,
+                stateBytes: receipt.bytes,
+            };
+        }
+        if (quiet.reason === 'unobservable') {
+            return {
+                outcome: 'aborted',
+                steps,
+                abortReason: `Cannot observe terminal quiescence: this Tower does not report 'lastDataAt' ` +
+                    `(Spec 1273 / phase 2). Refusing to clear a builder whose turn state is unknown — ` +
+                    `treating "unknown" as "idle" is exactly how a mid-turn clear happens. ` +
+                    `Restart Tower on a current build.`,
+                nonce,
+                statePath,
+                reorientPath,
+                payload,
+                saveRequest,
+                stateBytes: receipt.bytes,
+            };
+        }
+        // EXACTLY ONE escalation, and it is legal only here — after the R2 receipt.
+        // Before the receipt an ESC could interrupt the very save being requested;
+        // after it, the worst case is ending a turn whose valuable output is already
+        // on disk.
+        await terminal.sendEscape();
+        step('escalate-esc');
+        quiet = await awaitQuiescence({
+            terminal,
+            clock,
+            quietWindowMs,
+            timeoutMs: quiescePostEscalationTimeoutMs,
+            pollIntervalMs,
+        });
+        if (!quiet.quiet) {
+            // No third attempt, no "clear anyway". Aborting leaves a builder with its
+            // context and a saved state file — recoverable. Clearing a busy builder
+            // does not.
+            return {
+                outcome: 'aborted',
+                steps,
+                abortReason: `Builder did not go quiet within ${quiescePostEscalationTimeoutMs}ms of the ESC ` +
+                    `escalation. Refusing to clear a builder that is still mid-turn (R4). Its state ` +
+                    `file is saved at ${statePath}; retry once it settles, or raise --quiet-window.`,
+                nonce,
+                statePath,
+                reorientPath,
+                payload,
+                saveRequest,
+                stateBytes: receipt.bytes,
+            };
+        }
+    }
+    step('quiescent');
+    // --------------------------------------------------------------------
+    // 7–9. Clear, confirm best-effort, re-orient.
+    // --------------------------------------------------------------------
+    // Snapshot the buffer size BEFORE clearing, so confirmation can distinguish
+    // the harness's response from the echo of our own keystroke.
+    const totalBeforeClear = terminal.readOutput
+        ? ((await terminal.readOutput())?.total ?? 0)
+        : 0;
+    await terminal.sendRaw('/clear');
+    step('clear');
+    const confirmed = await confirmClear(terminal, totalBeforeClear);
+    step(confirmed ? 'clear-confirmed' : 'clear-unconfirmed');
+    await terminal.sendMessage(payload.inline);
+    step('send-reorientation');
+    return {
+        outcome: 'completed',
+        steps,
+        nonce,
+        statePath,
+        reorientPath,
+        payload,
+        saveRequest,
+        stateBytes: receipt.bytes,
+    };
+}
+/**
+ * Poll the state file until it is accepted or the wait expires.
+ *
+ * Returns the LAST observation rather than a boolean, so the abort message can
+ * name the specific gate that failed — "wrote a 200-byte stub" and "never wrote
+ * anything" call for different responses from the architect.
+ */
+async function awaitReceipt(options) {
+    const { fs, clock, statePath, nonce, minBytes, stabilityWindowMs, pollIntervalMs, timeoutMs } = options;
+    const deadline = clock.now() + timeoutMs;
+    let previous = null;
+    let previousAt = clock.now();
+    let latest = { status: 'missing' };
+    for (;;) {
+        const now = clock.now();
+        latest = verifyReceipt({
+            fs,
+            statePath,
+            nonce,
+            minBytes,
+            previous,
+            msSincePrevious: now - previousAt,
+            stabilityWindowMs,
+        });
+        if (latest.status === 'accepted')
+            return latest;
+        // Only advance the stability baseline when the gap has actually been
+        // consumed. Resetting `previousAt` on every poll would make the two
+        // observations always "too close together" and stability unreachable.
+        if (now - previousAt >= stabilityWindowMs) {
+            previous = latest;
+            previousAt = now;
+        }
+        if (clock.now() >= deadline)
+            return latest;
+        await clock.sleep(pollIntervalMs);
+        if (clock.now() >= deadline) {
+            // Re-evaluate once after the final sleep so a file that landed during it
+            // is not discarded on a technicality.
+            const now2 = clock.now();
+            latest = verifyReceipt({
+                fs,
+                statePath,
+                nonce,
+                minBytes,
+                previous,
+                msSincePrevious: now2 - previousAt,
+                stabilityWindowMs,
+            });
+            return latest;
+        }
+    }
+}
+/**
+ * Wait until the terminal has produced no output for `quietWindowMs`.
+ *
+ * `lastDataAt === undefined` is reported as `unobservable`, NOT as quiet. An
+ * older Tower omits the field, and defaulting it to 0 would compute an age of
+ * ~56 years and clear a busy builder instantly.
+ */
+async function awaitQuiescence(options) {
+    const { terminal, clock, quietWindowMs, timeoutMs, pollIntervalMs } = options;
+    const deadline = clock.now() + timeoutMs;
+    for (;;) {
+        const observation = await terminal.observe();
+        // Checked BEFORE lastDataAt. A terminal that vanished mid-run also reports
+        // no lastDataAt, and conflating the two sends the architect to check their
+        // Tower version when the real event is that the builder's terminal died.
+        // The two need different responses, so they get different reasons.
+        if (!observation.exists) {
+            return { quiet: false, reason: 'terminal-gone' };
+        }
+        if (observation.lastDataAt === undefined) {
+            return { quiet: false, reason: 'unobservable' };
+        }
+        if (clock.now() - observation.lastDataAt >= quietWindowMs) {
+            return { quiet: true };
+        }
+        if (clock.now() >= deadline)
+            return { quiet: false, reason: 'timeout' };
+        await clock.sleep(pollIntervalMs);
+        if (clock.now() >= deadline) {
+            const final = await terminal.observe();
+            if (!final.exists)
+                return { quiet: false, reason: 'terminal-gone' };
+            if (final.lastDataAt === undefined)
+                return { quiet: false, reason: 'unobservable' };
+            if (clock.now() - final.lastDataAt >= quietWindowMs)
+                return { quiet: true };
+            return { quiet: false, reason: 'timeout' };
+        }
+    }
+}
+/**
+ * Best-effort check that `/clear` took effect.
+ *
+ * Deliberately advisory. There is no reliable cross-version signal that Claude
+ * Code cleared its context, and an unconfirmed clear is reported as unconfirmed
+ * rather than as failure — the re-orientation that follows is correct either
+ * way. The worst case of a silent no-op is a builder that kept its context and
+ * also received a re-orientation, which loses nothing.
+ */
+async function confirmClear(terminal, totalBeforeClear) {
+    if (!terminal.readOutput)
+        return false;
+    try {
+        const output = await terminal.readOutput();
+        if (!output)
+            return false;
+        // Consider ONLY lines produced after the clear was sent. Everything the
+        // refresh itself wrote is at or before `totalBeforeClear`, so this excludes
+        // its own text by construction rather than by hoping the pattern avoids it.
+        const newLineCount = output.total - totalBeforeClear;
+        if (newLineCount <= 0)
+            return false;
+        const fresh = output.lines.slice(-newLineCount).join('\n');
+        return /context (?:cleared|reset)|conversation (?:cleared|reset)|cleared conversation/i.test(fresh);
+    }
+    catch {
+        // Confirmation must never be able to fail the run — it is a report field.
+        return false;
+    }
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Reject a timing/threshold parameter that would weaken a gate.
+ *
+ * `Number.isFinite` rather than a bare `> 0` comparison: `NaN > 0` is false but
+ * so is `NaN <= 0`, so a NaN slips through any single comparison written the
+ * obvious way. Infinity is rejected too — an infinite deadline is a hang.
+ */
+function requirePositive(value, name) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new ResetPreflightError(`Invalid ${name}: ${value}. Must be a positive, finite number. ` +
+            `This parameter gates a safety check (R2/R4) — a bad value would disable it silently.`);
+    }
+}
+/**
+ * Resolve the state-file path, refusing anything that escapes the worktree.
+ *
+ * The path is handed to the builder as a write instruction, so an override of
+ * `../../../etc/whatever` would have the builder write outside its own worktree.
+ * Containment is checked on the resolved path, not the raw string, so `..`
+ * segments cannot slip through.
+ */
+function resolveStatePath(worktree, stateFileName) {
+    const candidate = stateFilePath(worktree, stateFileName);
+    if (!stateFileName)
+        return candidate;
+    const normalizedWorktree = worktree.endsWith('/') ? worktree : `${worktree}/`;
+    if (!candidate.startsWith(normalizedWorktree)) {
+        throw new ResetPreflightError(`State-file override '${stateFileName}' resolves to ${candidate}, outside the builder's ` +
+            `worktree (${worktree}). Refusing: the path is sent to the builder as a write instruction.`);
+    }
+    return candidate;
+}
+/**
+ * Render the step log as the run report.
+ *
+ * Each line carries its EVIDENCE, not just a tick. "Receipt accepted" alone is
+ * the kind of reassurance that hides a stale file; "accepted — 8,432 bytes
+ * carrying nonce a1b2c3" is checkable.
+ */
+export function formatResetReport(result) {
+    const lines = [];
+    for (const s of result.steps) {
+        lines.push(s.detail ? `  ✓ ${s.name} — ${s.detail}` : `  ✓ ${s.name}`);
+    }
+    if (result.outcome === 'aborted') {
+        lines.push('');
+        lines.push(`  ✗ ABORTED: ${result.abortReason}`);
+        lines.push('  The builder\'s context was NOT cleared.');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=index.js.map

package/dist/agent-farm/commands/reset/index.js.map

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

package/dist/agent-farm/commands/reset/receipt.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The reset receipt gate — invariant R2 (Spec 1273).
+ *
+ * `afx refresh` clears a builder's context, which is irreversible. The manual
+ * version of this flow guarded that step by eyeballing the state file ("ours was
+ * 203 lines"). This module replaces the eyeball with evidence: a state file is
+ * accepted only if it proves it is *this run's* save, is substantive, and has
+ * stopped growing.
+ *
+ * Freshness comes from a nonce written INSIDE the file, not from mtime. mtime
+ * was rejected deliberately: filesystem timestamp granularity and clock skew
+ * make it fragile, and it cannot distinguish "rewritten in response to this
+ * request" from "touched". A nonce the builder must reproduce can only appear
+ * in a file written after the request that carried it.
+ *
+ * Pure: all filesystem access arrives through injected ports, so every rejection
+ * path is testable without a real builder, a real worktree, or real time.
+ */
+/** Filesystem access needed by the gate. Injected so tests need no real files. */
+export interface ReceiptFsPort {
+    /** Byte length of the file, or null when it does not exist. */
+    sizeOf(path: string): number | null;
+    /** Full contents, or null when the file does not exist. */
+    read(path: string): string | null;
+}
+/**
+ * Generate a per-run nonce.
+ *
+ * Short enough that a builder reproduces it without transcription errors, long
+ * enough that a stale file from a previous reset cannot collide with it.
+ */
+export declare function generateNonce(): string;
+/**
+ * The marker line the builder is asked to reproduce verbatim.
+ *
+ * An HTML comment so it is invisible in rendered markdown but trivially
+ * greppable, and harmless if the file is later read by a human.
+ */
+export declare function nonceMarker(nonce: string): string;
+/**
+ * Build the message asking the builder to write its working state.
+ *
+ * The checklist is the quality bar. It cannot be enforced programmatically (see
+ * `verifyReceipt` — the gate is structural on purpose), so it has to be explicit
+ * enough that a builder writing in good faith produces something a cold reader
+ * can actually use.
+ */
+export declare function buildSaveRequest(nonce: string, statePath: string): string;
+/** Why a candidate state file was not accepted, or that it was. */
+export type ReceiptStatus = 'accepted' | 'missing' | 'wrong-nonce' | 'too-small' | 'still-growing';
+export interface ReceiptObservation {
+    status: ReceiptStatus;
+    /** Size at the moment of observation, when the file existed. */
+    bytes?: number;
+}
+export interface VerifyReceiptOptions {
+    fs: ReceiptFsPort;
+    statePath: string;
+    nonce: string;
+    minBytes?: number;
+    /** A previous observation, for the stability comparison. */
+    previous?: ReceiptObservation | null;
+    /** ms since `previous` was taken. Stability needs a real gap, not two reads in a row. */
+    msSincePrevious?: number;
+    stabilityWindowMs?: number;
+}
+/**
+ * Evaluate the state file once.
+ *
+ * Checks run in escalating order so the reported reason is the *most specific*
+ * one true: existence, then freshness, then substance, then stability. A caller
+ * polls this and only proceeds on `accepted`.
+ *
+ * Stability requires agreement between two observations separated by at least
+ * `stabilityWindowMs`. Without the time gap, a builder mid-write would look
+ * stable simply because two reads landed between the same two `write()` calls.
+ */
+export declare function verifyReceipt(options: VerifyReceiptOptions): ReceiptObservation;
+/**
+ * Human-readable explanation of a non-acceptance, for the abort message.
+ *
+ * Reset aborts loudly rather than clearing on a doubtful file, so the architect
+ * needs to know which gate failed — "timed out" alone would not distinguish a
+ * builder that never responded from one that wrote a stub.
+ */
+export declare function describeReceiptFailure(observation: ReceiptObservation, statePath: string, minBytes?: number): string;
+/**
+ * Absolute path of the state file for a worktree.
+ *
+ * Uses `path.join` rather than string concatenation: this path is handed to the
+ * builder verbatim in the save request, so on Windows a hand-built
+ * `C:\repo\wt\` + `/` + name would instruct the builder to write to a path that
+ * is not the one the gate then stats. `path.join` also collapses redundant
+ * separators, so a trailing slash on the worktree is harmless.
+ */
+export declare function stateFilePath(worktreePath: string, fileName?: string): string;
+//# sourceMappingURL=receipt.d.ts.map

package/dist/agent-farm/commands/reset/receipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt.d.ts","sourceRoot":"","sources":["../../../../src/agent-farm/commands/reset/receipt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAcH,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,2DAA2D;IAC3D,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACnC;AAMD;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjD;AAMD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CA2BzE;AAMD,mEAAmE;AACnE,MAAM,MAAM,aAAa,GACrB,UAAU,GACV,SAAS,GACT,aAAa,GACb,WAAW,GACX,eAAe,CAAC;AAEpB,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,aAAa,CAAC;IACtB,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,aAAa,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACrC,yFAAyF;IACzF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,kBAAkB,CAiC/E;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,kBAAkB,EAC/B,SAAS,EAAE,MAAM,EACjB,QAAQ,SAAoB,GAC3B,MAAM,CAaR;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,SAAkB,GAAG,MAAM,CAEtF"}