@cluesmith/codev 3.3.0 → 3.3.2

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

@@ -0,0 +1,636 @@
+/**
+ * Self-refresh orchestrator — the tail of the refresh machine, run by the
+ * builder on itself (Spec 1470).
+ *
+ * ## Why this exists separately from `runReset`
+ *
+ * `afx refresh` cannot be invoked by its own target. It sends a save request and
+ * then POLLS for the receipt while waiting for the terminal to fall quiet — but
+ * a builder running it would be mid-turn for the whole poll, so it could never
+ * answer its own request. The run would burn the 300 s receipt timeout and
+ * abort. The receipt and quiescence gates structurally require a driver outside
+ * the turn.
+ *
+ * So this module is the TAIL of that machine, not a second copy of it: verify an
+ * already-written save → assemble the re-orientation → schedule the re-entry →
+ * clear. The verification and assembly are the SAME modules `runReset` uses
+ * ({@link verifyReceipt}, {@link assembleReorientation}), which a structural test
+ * pins. What is deliberately different is the save REQUEST text — see
+ * {@link buildBoundarySaveRequest}.
+ *
+ * ## The two-step handshake, and why it is not one call
+ *
+ * `verifyReceipt` requires the nonce to be INSIDE the state file. In the self
+ * path the builder writes that file before invoking the command, so a nonce
+ * minted at invocation could never be in a file already on disk — every run
+ * would abort `wrong-nonce`. Hence:
+ *
+ *   begin   → mint nonce, write the challenge file, return the save request
+ *   (builder writes .builder-state.md, reproducing the nonce)
+ *   execute → verify against THAT nonce, assemble, schedule, clear, consume
+ *             the challenge
+ *
+ * The challenge is deleted on use and overwritten by every `begin`, which is
+ * what stops a stale `.builder-state.md` from an EARLIER boundary passing the
+ * gate. The driven path gets that freshness for free from being externally
+ * driven; the self path has to earn it.
+ *
+ * ## Ordering, and the one place it differs from `/arch-save`
+ *
+ * Schedule the re-entry FIRST, clear SECOND. `/arch-save` does the reverse. The
+ * two failure directions are not symmetric:
+ *
+ *   - schedule fails, no clear sent  → builder keeps everything. Recoverable.
+ *   - clear sent, schedule fails     → context destroyed, nobody coming back.
+ *
+ * Only the second is unrecoverable, so the destructive step goes last. Baked
+ * Decision 4 requires the automatic path to be MORE conservative than the manual
+ * one; this is that, made concrete rather than asserted.
+ *
+ * ## Everything is a port, and every action is logged before it happens
+ *
+ * Same discipline as `runReset`, for the same reason: every safety property here
+ * is an ORDERING property ("the clear never happens before X"), and ordering is
+ * what is hardest to prove by reading. Actions go through injected ports and the
+ * invariant tests assert over an ordered step log rather than over mocks, so "no
+ * clear without a verified save" becomes something a test can fail on.
+ *
+ * The IRREVERSIBLE action is logged BEFORE it is attempted (`clear-attempted`),
+ * with a second entry (`clear`) only on success. That asymmetry is deliberate:
+ * `sendRaw` can succeed on the wire and still throw, and a log written only on
+ * success would then claim no clear occurred about a context that no longer
+ * exists — with every `expectNoClear` assertion agreeing. Reversible steps are
+ * logged after they succeed, where a failure is genuinely a non-event.
+ * (`runReset` logs its clear after the fact; that same weakness is noted for the
+ * review artifact rather than fixed here, since this phase does not own it.)
+ */
+import { join } from 'node:path';
+import { CHALLENGE_FILE_NAME, DEFAULT_CHALLENGE_MAX_AGE_MS, MIN_ALLOWED_CHALLENGE_MAX_AGE_MS, DEFAULT_MIN_BYTES, MAX_NONCE_HEX_CHARS, MIN_ALLOWED_MIN_BYTES, MIN_ALLOWED_REENTRY_DELAY_SECONDS, MIN_ALLOWED_STABILITY_WINDOW_MS, DEFAULT_REENTRY_DELAY_SECONDS, DEFAULT_STABILITY_WINDOW_MS, REORIENT_FILE_NAME, STATE_FILE_NAME, } from './constants.js';
+import { nonceMarker, generateNonce, verifyReceipt, describeReceiptFailure, stateFilePath, } from './receipt.js';
+import { assembleReorientation, ReorientationAssemblyError, } from './reorient.js';
+import { enterBoundary } from '../../../commands/porch/context-refresh.js';
+// ============================================================================
+// The save request — deliberately NOT buildSaveRequest
+// ============================================================================
+/**
+ * The boundary-aware save request.
+ *
+ * This is the one place the self path deliberately diverges from the driven one.
+ * `buildSaveRequest` (receipt.ts) asks for a "complete working state" and says
+ * "do not summarise for brevity" — right for a MID-PHASE reset, where a builder
+ * may be holding a half-finished action nothing on disk records.
+ *
+ * A boundary save is a different problem. Spec 1470 fixes the boundaries at
+ * moments when the durable state is already externalised — the spec, the plan,
+ * `status.yaml`, the thread narrative and git — so what a cold reader actually
+ * needs is the residue those artifacts do NOT carry. Asking for "everything"
+ * here produces a long file that mostly restates the plan, and Baked Decision 2
+ * explicitly says to keep the builder save minimal.
+ *
+ * Hence: pointers over prose. Receipts with commit hashes, not narration of what
+ * the commits contain.
+ *
+ * At the REVIEW boundary there is one further exclusion, and it is the whole
+ * reason that boundary is a quality feature rather than only a context one: a
+ * builder entering review in a fresh context should read its own diff cold. If
+ * the save carries "I implemented X and it is correct because Y", the refresh
+ * hands back the very perspective it was supposed to remove.
+ */
+export function buildBoundarySaveRequest(nonce, statePath, boundary) {
+    // Derived, not typed out. A bare `'enter:review'` here is uncoupled from
+    // `enterBoundary()`, which is what actually produces boundary ids — so a
+    // change to that format would silently delete the review-boundary constraint
+    // rather than failing. The constraint is the whole reason the review boundary
+    // is a quality feature and not just a context one.
+    const isReview = boundary === enterBoundary('review');
+    const lines = [
+        'CONTEXT REFRESH — save your working state now.',
+        '',
+        boundary ? `Boundary: \`${boundary}\`` : 'Boundary: (unspecified)',
+        '',
+        `Write your working state to \`${statePath}\` (untracked; do not stage or commit it).`,
+        '',
+        'The file MUST begin with this exact line, reproduced character for character:',
+        '',
+        nonceMarker(nonce),
+        '',
+        'Write for a COLD READER — a competent agent that wakes up with your worktree,',
+        'your branch, and no memory of this conversation.',
+        '',
+        'This is a PROTOCOL BOUNDARY, so most of your state is already on disk. The spec,',
+        'the plan, `status.yaml`, your thread narrative and git history all survive the',
+        'refresh and will be re-read. Do not restate them.',
+        '',
+        'Carry only what those artifacts do NOT contain:',
+        '',
+        '1. **Receipts** — what is done and *verified*, with paths and commit hashes.',
+        '   Distinguish "written" from "verified"; a cold reader cannot tell.',
+        '2. **Deviations** — where the implementation diverges from the plan, and why.',
+        '3. **Flaky or skipped tests** you hit, and what you did about them.',
+        '4. **Deferred work** — anything knowingly left, and the reason.',
+        '5. **Standing orders** from the architect you are still bound by, including',
+        '   anything you were told NOT to do.',
+        '6. **Next concrete action** — the single thing to do first after the refresh.',
+    ];
+    if (isReview) {
+        lines.push('', 'THIS IS THE REVIEW BOUNDARY. You are about to read your own diff with fresh', 'eyes, which is the point of refreshing here. So do NOT carry:', '', '- any assessment of whether your implementation is correct or good;', '- any defence or justification of choices you made;', '- any narrative of how the code came to be.', '', 'Facts and pointers only. Let the diff speak for itself — if you tell the next', 'reader what to think of the code, you have handed back the exact perspective', 'this refresh exists to remove.');
+    }
+    lines.push('', `The save must be at least ${DEFAULT_MIN_BYTES} bytes to be accepted — not as a`, 'word count to pad out, but because a file below it is indistinguishable from a', 'stub. If you genuinely have less than that to say, you are probably omitting', 'receipts or standing orders. This boundary is refreshed AT MOST ONCE and is', 'never retried, so a save rejected here means the refresh simply does not happen.', '', 'Pointers, not prose. When the file is written, run the execute step.', '', 
+    // Observed live (Spec 1470, third pass): a refusal-and-retry put real work
+    // between `--begin` and the execute step, and the save still said "phase 2
+    // not started" when phase 2 was by then DONE. The subject noticed and
+    // rewrote it; a cold reader following the stale text would have
+    // re-implemented completed work.
+    //
+    // No gate can catch this — the file is authentic, substantive, settled and
+    // inside its age window, and simply false. The mechanism-level fix needs
+    // design (see the follow-up issue), so what ships here is the instruction,
+    // which addresses the observed case directly rather than pretending a new
+    // check would.
+    'IF YOU DID ANY WORK between the challenge step and this one — committed anything,', 'finished a phase, changed what is true — REWRITE THE SAVE FIRST. The gates check that', 'your file is authentic, substantial and settled; NOTHING checks that it is still', 'accurate. A save that was true when you wrote it and is stale when you clear on it', 'sends your successor to redo finished work.');
+    return lines.join('\n');
+}
+// ============================================================================
+// Paths
+// ============================================================================
+/**
+ * `path.join`, not string concatenation — the same reasoning `stateFilePath`
+ * documents. These paths are shown to the builder verbatim and stat'd by the
+ * gate, so a hand-built separator would name one path in the instruction and
+ * check a different one on Windows. `join` also collapses a trailing slash.
+ */
+export function challengeFilePath(worktreePath) {
+    return join(worktreePath, CHALLENGE_FILE_NAME);
+}
+export function reorientFilePath(worktreePath) {
+    return join(worktreePath, REORIENT_FILE_NAME);
+}
+/**
+ * Mint a challenge and tell the builder what to write.
+ *
+ * Overwrites any existing challenge deliberately: a fresh `begin` must invalidate
+ * a previous boundary's nonce, or a stale `.builder-state.md` left on disk would
+ * satisfy the gate without the builder writing anything.
+ *
+ * Writes NOTHING destructive and touches no terminal. Nothing here can lose work.
+ */
+export function beginSelfRefresh(options) {
+    const { fs, clock, worktree, boundary, makeNonce = generateNonce } = options;
+    const nonce = makeNonce();
+    const challengePath = challengeFilePath(worktree);
+    const statePath = stateFilePath(worktree, STATE_FILE_NAME);
+    const challenge = { nonce, issuedAt: clock.now(), boundary };
+    fs.write(challengePath, JSON.stringify(challenge, null, 2));
+    return {
+        nonce,
+        statePath,
+        challengePath,
+        saveRequest: buildBoundarySaveRequest(nonce, statePath, boundary),
+    };
+}
+// ============================================================================
+// Step 2 — execute
+// ============================================================================
+/**
+ * Parse and FULLY validate a persisted challenge.
+ *
+ * `JSON.parse` returns `any`, and casting it to {@link Challenge} buys a
+ * compile-time guarantee about a runtime value that came off disk. That gap is
+ * exploitable, and not theoretically:
+ *
+ *   `{"nonce": []}` survives a truthiness check, because `![]` is `false`. It is
+ *   then handed to `verifyReceipt`, whose `content.includes(nonce)` coerces the
+ *   array to `''` — and `String.includes('')` is true for EVERY string. The
+ *   freshness gate does not merely weaken, it inverts: any file over the size
+ *   floor passes as a fresh save.
+ *
+ *   A non-numeric or `NaN` `issuedAt` defeats the age bound the same way, since
+ *   every comparison with `NaN` is false. A FUTURE `issuedAt` yields a negative
+ *   age, which is likewise never "too old".
+ *
+ * So the shape is checked here, at the trust boundary, rather than assumed. The
+ * driven path needs no equivalent because it mints its nonce in-process and
+ * never reads one back from disk; only the self path takes a challenge from a
+ * file, which is exactly where validation belongs.
+ */
+/**
+ * Minimum nonce length, in hex characters.
+ *
+ * `generateNonce()` produces `randomBytes(6).toString('hex')` — 12 lowercase hex
+ * characters. Validating a FLOOR rather than an exact length keeps a future
+ * longer nonce valid while rejecting a short one.
+ *
+ * Length is a safety property here, not tidiness: freshness is proved by
+ * `content.includes(nonce)`, so a one-character nonce is found in nearly every
+ * state file ever written. A nonce short enough to collide is a nonce that
+ * proves nothing.
+ */
+const MIN_NONCE_HEX_CHARS = 12;
+const NONCE_PATTERN = new RegExp(`^[0-9a-f]{${MIN_NONCE_HEX_CHARS},${MAX_NONCE_HEX_CHARS}}$`);
+export function parseChallenge(raw, now) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, reason: 'is not valid JSON' };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return { ok: false, reason: 'is not a JSON object' };
+    }
+    const obj = parsed;
+    if (typeof obj.nonce !== 'string' || !NONCE_PATTERN.test(obj.nonce)) {
+        return {
+            ok: false,
+            reason: `carries a nonce that is not ${MIN_NONCE_HEX_CHARS}-${MAX_NONCE_HEX_CHARS} lowercase hex characters ` +
+                `(${JSON.stringify(obj.nonce)}). Freshness is proved by \`content.includes(nonce)\`, so a ` +
+                `short or non-hex nonce matches almost any file: "a" would be found in nearly every save, ` +
+                `and "" in all of them`,
+        };
+    }
+    if (typeof obj.issuedAt !== 'number' || !Number.isFinite(obj.issuedAt)) {
+        return {
+            ok: false,
+            reason: `carries a non-finite issuedAt (${JSON.stringify(obj.issuedAt)}); the age bound ` +
+                `cannot be evaluated against it`,
+        };
+    }
+    // A future timestamp yields a negative age, which no maximum can reject.
+    // Allow a small skew so an ordinary clock adjustment is not fatal.
+    const SKEW_MS = 60_000;
+    if (obj.issuedAt > now + SKEW_MS) {
+        return {
+            ok: false,
+            reason: `was issued in the future (issuedAt ${obj.issuedAt}, now ${now}); a future ` +
+                `timestamp cannot expire`,
+        };
+    }
+    if (obj.boundary !== undefined && typeof obj.boundary !== 'string') {
+        return { ok: false, reason: 'carries a non-string boundary' };
+    }
+    if (obj.consumedAt !== undefined && typeof obj.consumedAt !== 'number') {
+        return { ok: false, reason: 'carries a non-numeric consumedAt' };
+    }
+    return {
+        ok: true,
+        challenge: {
+            nonce: obj.nonce,
+            issuedAt: obj.issuedAt,
+            boundary: obj.boundary,
+            consumedAt: obj.consumedAt,
+        },
+    };
+}
+export async function runSelfRefresh(options) {
+    const { fs, clock, terminal, git, context, buildSpawnPrompt, buildResumeNotice, issue, addendum, minBytes = DEFAULT_MIN_BYTES, stabilityWindowMs = DEFAULT_STABILITY_WINDOW_MS, reentryDelaySeconds = DEFAULT_REENTRY_DELAY_SECONDS, challengeMaxAgeMs = DEFAULT_CHALLENGE_MAX_AGE_MS, expectedBoundary, dryRun = false, allowDirty = false, } = options;
+    const steps = [];
+    const step = (name, detail) => {
+        steps.push({ name, at: clock.now(), detail });
+    };
+    const worktree = context.worktree;
+    const statePath = stateFilePath(worktree, STATE_FILE_NAME);
+    const challengePath = challengeFilePath(worktree);
+    const reorientPath = reorientFilePath(worktree);
+    const abort = (failure, reason) => ({ outcome: 'aborted', steps, failure, reason, statePath });
+    // ------------------------------------------------------------------
+    // Gate 0 — the safety parameters themselves must be sane.
+    // ------------------------------------------------------------------
+    // Every one of these TUNES A GATE, so a bad value does not degrade the run —
+    // it silently disables a protection while everything still reports success.
+    // `minBytes: 0` accepts an empty save; `challengeMaxAgeMs: NaN` makes every
+    // comparison false so nothing ever expires; a non-positive stability window
+    // collapses two observations into one.
+    //
+    // Validated HERE rather than only at the CLI boundary: this function is the
+    // thing that clears a builder, and it should not depend on every future caller
+    // having remembered to check. `runReset` sets the same precedent for its own
+    // flags.
+    // Floors, not just positivity. "Finite and positive" is VALIDITY; these gates
+    // need SANITY, because a small positive value neuters the check it configures
+    // while everything still reports success. `--delay 0.001` is the dangerous
+    // one: the re-entry and the clear then race for the same clean prompt.
+    const parameterChecks = [
+        ['minBytes', minBytes, MIN_ALLOWED_MIN_BYTES],
+        ['stabilityWindowMs', stabilityWindowMs, MIN_ALLOWED_STABILITY_WINDOW_MS],
+        ['reentryDelaySeconds', reentryDelaySeconds, MIN_ALLOWED_REENTRY_DELAY_SECONDS],
+        ['challengeMaxAgeMs', challengeMaxAgeMs, MIN_ALLOWED_CHALLENGE_MAX_AGE_MS],
+    ];
+    for (const [name, value, floor] of parameterChecks) {
+        if (!Number.isFinite(value) || value < floor) {
+            return abort('invalid-parameters', `${name} must be a finite number >= ${floor} (got ${value}). Every safety parameter ` +
+                `here gates a check, so a too-small value disables a protection rather than ` +
+                `failing loudly — refusing instead.`);
+        }
+    }
+    // ------------------------------------------------------------------
+    // Gate 1 — the challenge must exist and be readable.
+    // ------------------------------------------------------------------
+    // Without it there is no nonce to verify against, so freshness is
+    // unprovable. Refusing here is what makes "run execute twice" safe: the
+    // first run consumes the challenge, the second finds nothing.
+    const rawChallenge = fs.read(challengePath);
+    if (rawChallenge === null) {
+        return abort('no-challenge', `No refresh challenge at ${challengePath}. Run the begin step first ` +
+            `(a challenge is consumed by each execute, so this also means "already refreshed").`);
+    }
+    const parsedChallenge = parseChallenge(rawChallenge, clock.now());
+    if (!parsedChallenge.ok) {
+        return abort('no-challenge', `Refresh challenge at ${challengePath} ${parsedChallenge.reason}. ` +
+            `Run the begin step again.`);
+    }
+    const challenge = parsedChallenge.challenge;
+    if (challenge.consumedAt !== undefined) {
+        // Burned by an earlier execute whose delete did not land. Refusing here is
+        // what makes the pre-clear mark sufficient on its own.
+        return abort('no-challenge', `Refresh challenge at ${challengePath} was already consumed. A challenge is ` +
+            `single-use; run the begin step again if you mean to refresh once more.`);
+    }
+    // A challenge is for ONE boundary at ONE moment. Both checks close the same
+    // hole from different sides: a run that aborted leaves its challenge on disk,
+    // and without these it would still satisfy the gate at a later boundary,
+    // against a state file describing work that has since moved on.
+    if (expectedBoundary !== undefined && challenge.boundary !== expectedBoundary) {
+        return abort('no-challenge', `Refresh challenge was issued for boundary '${challenge.boundary ?? '(none)'}' but this ` +
+            `run is for '${expectedBoundary}'. Run the begin step again — a challenge does not ` +
+            `carry across boundaries.`);
+    }
+    const age = clock.now() - challenge.issuedAt;
+    if (age > challengeMaxAgeMs) {
+        return abort('no-challenge', `Refresh challenge is ${Math.round(age / 1000)}s old (limit ` +
+            `${Math.round(challengeMaxAgeMs / 1000)}s). A save verified against a stale challenge ` +
+            `may describe work that has since moved on. Run the begin step again.`);
+    }
+    step('challenge-read', challenge.boundary ?? 'no-boundary');
+    // ------------------------------------------------------------------
+    // Gate 2 — the worktree must have no uncommitted tracked changes.
+    // ------------------------------------------------------------------
+    // A refresh fires at a protocol boundary, where porch has just committed.
+    // Uncommitted tracked work means we are NOT at that boundary — something is
+    // half-done, and the plan/spec/git triple that a refreshed builder re-reads
+    // would not describe it. Untracked `.builder-*` scaffold does not count; it
+    // is expected to be there.
+    if (!allowDirty && git.hasUncommittedTrackedChanges()) {
+        return abort('dirty-worktree', 'Worktree has uncommitted tracked changes. A refresh assumes a committed ' +
+            'boundary, and a fresh context re-orients from artifacts and git — work ' +
+            'that exists only in the working tree would be invisible to it. Commit ' +
+            'first, or pass --allow-dirty if this is deliberate.');
+    }
+    step('worktree-checked');
+    // ------------------------------------------------------------------
+    // Gate 3 — the save must pass the SAME receipt gate the driven path uses.
+    // ------------------------------------------------------------------
+    // Two observations, not one: `verifyReceipt` returns `still-growing` whenever
+    // `previous` is null, because stability requires agreement across a real time
+    // gap. One read cannot distinguish a finished file from one mid-write.
+    const first = verifyReceipt({
+        fs,
+        statePath,
+        nonce: challenge.nonce,
+        minBytes,
+        previous: null,
+        msSincePrevious: 0,
+        stabilityWindowMs,
+    });
+    // Fail fast on the reasons a second look cannot change. Sleeping 2 s to
+    // re-confirm a missing file helps nobody.
+    if (first.status === 'missing' || first.status === 'wrong-nonce' || first.status === 'too-small') {
+        return abort('receipt-rejected', describeReceiptFailure(first, statePath, minBytes));
+    }
+    const readMonotonic = () => (clock.monotonicNow ? clock.monotonicNow() : clock.now());
+    const beforeSleep = readMonotonic();
+    await clock.sleep(stabilityWindowMs);
+    // MEASURE the gap rather than asserting it. Passing `stabilityWindowMs` on
+    // faith would keep the gate passing even if the sleep did not actually
+    // advance the clock — the stability check would then be comparing two reads
+    // taken back to back while claiming they were seconds apart.
+    const elapsed = readMonotonic() - beforeSleep;
+    const second = verifyReceipt({
+        fs,
+        statePath,
+        nonce: challenge.nonce,
+        minBytes,
+        previous: first,
+        msSincePrevious: elapsed,
+        stabilityWindowMs,
+    });
+    if (second.status !== 'accepted') {
+        return abort('receipt-rejected', describeReceiptFailure(second, statePath, minBytes));
+    }
+    step('receipt-accepted', `${second.bytes} bytes`);
+    // ------------------------------------------------------------------
+    // Gate 4 — assemble the re-orientation (R3: complete or throw).
+    // ------------------------------------------------------------------
+    let payload;
+    try {
+        payload = assembleReorientation({
+            context,
+            statePath,
+            addendum,
+            buildSpawnPrompt,
+            buildResumeNotice,
+            issue,
+        });
+    }
+    catch (err) {
+        const reason = err instanceof ReorientationAssemblyError
+            ? err.message
+            : `Re-orientation assembly failed: ${err instanceof Error ? err.message : String(err)}`;
+        return abort('assembly-failed', reason);
+    }
+    step('assemble');
+    if (dryRun) {
+        // Everything above is a read or a pure computation, so stopping here is a
+        // complete rehearsal: the caller learns whether this refresh WOULD proceed
+        // without any of it having happened. The challenge is left intact so the
+        // real run can still use it.
+        return {
+            outcome: 'dry-run',
+            steps,
+            reason: 'dry run — verified and assembled, nothing sent',
+            statePath,
+            reorientPath,
+            payload,
+            stateBytes: second.bytes,
+        };
+    }
+    // ------------------------------------------------------------------
+    // R1 — the re-orientation is ON DISK before anything destructive.
+    // ------------------------------------------------------------------
+    try {
+        fs.write(reorientPath, payload.longForm);
+    }
+    catch (err) {
+        return abort('reorient-write-failed', `Could not write ${reorientPath}: ${err instanceof Error ? err.message : String(err)}. ` +
+            `Refusing to clear without the re-orientation on disk (R1).`);
+    }
+    step('reorient-written');
+    // ------------------------------------------------------------------
+    // Schedule the re-entry BEFORE the clear. This is the ordering that
+    // differs from `/arch-save`, and the reason is asymmetric damage: a failed
+    // schedule with no clear is recoverable, a clear with no re-entry is not.
+    // ------------------------------------------------------------------
+    try {
+        await terminal.scheduleReentry(buildAutomaticReentryFrame(payload.inline), reentryDelaySeconds);
+    }
+    catch (err) {
+        return abort('reentry-failed', `Could not schedule the post-clear re-entry: ` +
+            `${err instanceof Error ? err.message : String(err)}. ` +
+            `NOT clearing — your context is intact. The re-orientation is saved at ` +
+            `${reorientPath} if you want to retry.`);
+    }
+    step('reentry-scheduled', `+${reentryDelaySeconds}s`);
+    // ------------------------------------------------------------------
+    // Burn the challenge BEFORE clearing, not after.
+    // ------------------------------------------------------------------
+    // Deleting it afterwards is not enough: if the delete fails, the challenge and
+    // the already-verified state file both remain, so a second `execute` would
+    // sail through every gate and clear the builder AGAIN — scheduling a second
+    // re-entry into a context that just lost the first one.
+    //
+    // Marking is a write rather than a delete, and it happens while aborting is
+    // still free. If it fails we stop here with nothing destroyed. The delete
+    // after the clear is then pure tidiness: the mark alone already makes the
+    // challenge unusable.
+    try {
+        fs.write(challengePath, JSON.stringify({ ...challenge, consumedAt: clock.now() }, null, 2));
+    }
+    catch (err) {
+        return abort('challenge-burn-failed', `Could not mark the refresh challenge consumed: ` +
+            `${err instanceof Error ? err.message : String(err)}. ` +
+            `NOT clearing — an unburnable challenge could be replayed into a second clear. ` +
+            `Your context is intact, but a re-entry message is ALREADY QUEUED from the ` +
+            `previous step and will arrive shortly; it can be ignored. Note that retrying ` +
+            `queues a second one.`);
+    }
+    step('challenge-marked');
+    // ------------------------------------------------------------------
+    // The irreversible step. Everything above had to succeed to get here.
+    // ------------------------------------------------------------------
+    // Logged BEFORE it is attempted: see `clear-attempted`.
+    step('clear-attempted');
+    try {
+        await terminal.sendRaw('/clear');
+    }
+    catch (err) {
+        // Deliberately NOT "your context is intact". `sendRaw` can fail after the
+        // write reached the terminal, so from here we genuinely cannot tell whether
+        // the clear landed. Saying it did not would be a guess presented as a fact,
+        // and the reader would act on it. The re-entry is queued either way, so both
+        // outcomes recover.
+        return abort('clear-failed', `Re-entry was scheduled but sending the clear reported an error: ` +
+            `${err instanceof Error ? err.message : String(err)}. ` +
+            `The clear MAY still have landed — this path cannot tell. Either way the ` +
+            `re-orientation is at ${reorientPath} and a re-entry message is already queued.`);
+    }
+    step('clear');
+    // Tidy up. Genuinely optional now: the challenge was marked consumed before
+    // the clear, so even if this delete fails the file cannot be replayed — a
+    // marked challenge is refused at the gate above. Never turn a completed
+    // refresh into a failure over housekeeping.
+    try {
+        fs.remove(challengePath);
+        step('challenge-consumed');
+    }
+    catch {
+        // Left on disk, already neutralised. The next `begin` overwrites it.
+    }
+    return {
+        outcome: 'completed',
+        steps,
+        statePath,
+        reorientPath,
+        payload,
+        stateBytes: second.bytes,
+    };
+}
+/**
+ * Mark the re-entry as an AUTOMATIC refresh before it is scheduled.
+ *
+ * A builder cannot tell its own scheduled message from an architect's. Verified
+ * by probe during the specify phase: `afx send <self> "..."` is rendered by the
+ * harness as `### [ARCHITECT INSTRUCTION | … ] ###`. So a frame that merely says
+ * "context refresh" arrives looking like an order from the architect, and a
+ * refreshed builder may treat re-orientation as a new instruction — or, worse,
+ * wait for a follow-up that will never come.
+ *
+ * Added HERE rather than in `assembleReorientation`, which is shared: on the
+ * driven path the message genuinely IS from an architect who typed
+ * `afx refresh`, so labelling it automatic there would be false. The
+ * discriminator belongs to the path that is actually automatic.
+ */
+export function buildAutomaticReentryFrame(inline) {
+    return [
+        AUTOMATIC_REENTRY_MARKER,
+        '',
+        'This message is from YOU, not from the architect. Your own `afx self-refresh`',
+        'scheduled it before clearing your context at a protocol boundary. Nobody is',
+        'waiting on a reply and there is no new instruction here — this is your',
+        're-orientation, and the work to do next is whatever `porch next` returns.',
+        '',
+        inline,
+    ].join('\n');
+}
+/**
+ * The literal marker. Exported so tests pin the exact string a builder sees,
+ * rather than a paraphrase that could drift away from it.
+ */
+export const AUTOMATIC_REENTRY_MARKER = '## AUTOMATIC CONTEXT REFRESH — re-entry (not an architect instruction)';
+// ============================================================================
+// Reporting
+// ============================================================================
+/** Render a result for a human. */
+export function formatSelfRefreshReport(result) {
+    const lines = [];
+    const order = result.steps.map(s => s.name).join(' → ');
+    if (result.outcome === 'dry-run') {
+        // NOT "this refresh would proceed" — the rehearsal stops before the
+        // reorientation write, Tower scheduling, the challenge rewrite, the clear
+        // and the deletion, so it cannot speak for any of them. It establishes that
+        // the non-mutating preflight passes, which is genuinely useful and is not
+        // the same claim.
+        lines.push('Dry run — passed all non-mutating preflight checks.');
+        lines.push('  (verification and assembly only; nothing was written or sent)');
+        lines.push(`  state file:     ${result.statePath} (${result.stateBytes} bytes)`);
+        lines.push(`  steps:          ${order}`);
+        lines.push('');
+        lines.push('Nothing was sent, written or consumed.');
+        return lines.join('\n');
+    }
+    if (result.outcome === 'completed') {
+        lines.push('Context refresh complete.');
+        lines.push(`  state file:     ${result.statePath} (${result.stateBytes} bytes)`);
+        lines.push(`  re-orientation: ${result.reorientPath}`);
+        lines.push(`  steps:          ${order}`);
+        lines.push('');
+        lines.push('Your next instruction will arrive shortly. It will tell you to run `porch next`.');
+        return lines.join('\n');
+    }
+    lines.push(`Context refresh ABORTED${result.failure ? ` (${result.failure})` : ''}.`);
+    lines.push(`  reason: ${result.reason}`);
+    lines.push(`  steps:  ${order || '(none)'}`);
+    if (result.steps.some(s => s.name === 'clear-attempted')) {
+        lines.push('');
+        lines.push('A clear WAS attempted and may have landed. Do not assume your context survived.');
+    }
+    else {
+        lines.push('');
+        lines.push('No clear was attempted. Your context is intact.');
+    }
+    return lines.join('\n');
+}
+/**
+ * Did this run reach the irreversible step?
+ *
+ * True for a CONFIRMED clear and for an ATTEMPTED one, because an attempt whose
+ * send threw may still have landed. Anything asking "is this builder's context
+ * safe?" must treat both as unsafe; a helper that answered only about confirmed
+ * clears would be the optimistic reading of an ambiguous event.
+ */
+export function didClear(result) {
+    return result.steps.some(s => s.name === 'clear' || s.name === 'clear-attempted');
+}
+/** Strictly confirmed: `sendRaw` returned successfully. */
+export function didClearConfirmed(result) {
+    return result.steps.some(s => s.name === 'clear');
+}
+//# sourceMappingURL=self.js.map