@cluesmith/codev 3.3.0 → 3.3.2

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

@@ -0,0 +1,335 @@
+/**
+ * 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 { type ReceiptFsPort, type ReceiptObservation } from './receipt.js';
+import { type IssuePayload, type ReorientationPayload, type ResumeNoticePort, type SpawnPromptPort } from './reorient.js';
+import type { ResolvedBuilderContext } from './context.js';
+/** Filesystem surface. Superset of the receipt gate's, plus writes and delete. */
+export interface SelfRefreshFsPort extends ReceiptFsPort {
+    write(path: string, content: string): void;
+    remove(path: string): void;
+}
+/** Wall clock and sleep, injected so tests run instantly and deterministically. */
+export interface SelfRefreshClockPort {
+    /** Wall clock, for timestamps that cross process boundaries (`issuedAt`). */
+    now(): number;
+    sleep(ms: number): Promise<void>;
+    /**
+     * MONOTONIC reading, for measuring the stability gap.
+     *
+     * `Date.now()` is not monotonic: an NTP step forward inside the window would
+     * make the measured gap satisfy the stability check when no real time passed —
+     * spoofing the very measurement that replaced an asserted value. (A backward
+     * step is already fail-safe: negative elapsed reads as still-growing.)
+     *
+     * Optional so existing callers and fakes keep working; when absent the code
+     * falls back to `now()`, which is the previous behaviour rather than a new
+     * hazard.
+     */
+    monotonicNow?(): number;
+}
+/**
+ * What the builder can do to its OWN terminal.
+ *
+ * Two distinct operations, never one `send(data, mode)`. Tower's raw route types
+ * literal input into the PTY; the delayed route persists a formatted message to
+ * the mailbox for later delivery. Confusing them is silent: `/clear` sent as a
+ * normal message would be delivered as text rather than executed.
+ */
+export interface SelfTerminalPort {
+    /** Schedule a message to self for delivery after `delaySeconds`. */
+    scheduleReentry(message: string, delaySeconds: number): Promise<void>;
+    /** Type literal text into our own PTY. This is how `/clear` is delivered. */
+    sendRaw(text: string): Promise<void>;
+}
+/** Git surface — only what the dirty-worktree gate needs. */
+export interface SelfGitPort {
+    /** True when tracked files have uncommitted modifications (staged or not). */
+    hasUncommittedTrackedChanges(): boolean;
+}
+/**
+ * The ordered record of what happened.
+ *
+ * `clear` is the only irreversible entry. Every invariant test is a statement
+ * about this array — most importantly that `clear` never appears without
+ * `reorient-written` and `reentry-scheduled` before it.
+ */
+export type SelfRefreshStepName = 'challenge-read' | 'worktree-checked' | 'receipt-accepted' | 'assemble' | 'reorient-written' | 'reentry-scheduled' | 'challenge-marked'
+/**
+ * Logged BEFORE the clear is sent, and never removed.
+ *
+ * The distinction from `clear` is the whole point. `terminal.sendRaw` can
+ * succeed on the wire and still throw client-side — a dropped socket after
+ * delivery, say — and in that case the builder IS cleared while the call
+ * reports failure. Logging only on success would produce a run that says "no
+ * clear happened" about a context that no longer exists, and every
+ * `expectNoClear` assertion would agree with it.
+ *
+ * So the log records the INTENT before the irreversible act. `clear-attempted`
+ * without `clear` means "we do not know" — which is the truth, and is
+ * reportable. Anything asserting that no clear occurred must check for both.
+ */
+ | 'clear-attempted'
+/** Logged only after `sendRaw` returned successfully. */
+ | 'clear' | 'challenge-consumed';
+export interface SelfRefreshStep {
+    name: SelfRefreshStepName;
+    at: number;
+    detail?: string;
+}
+export type SelfRefreshFailure = 'no-challenge'
+/**
+ * A safety PARAMETER was invalid — a configuration error, not a bad save.
+ *
+ * Distinct from `receipt-rejected` because the advice differs completely:
+ * "rewrite your save" is exactly wrong when the real problem is `--min-bytes 0`.
+ */
+ | 'invalid-parameters' | 'dirty-worktree' | 'receipt-rejected' | 'assembly-failed'
+/**
+ * The frame was built but could not be persisted.
+ *
+ * Distinct from `assembly-failed` because the causes and the fixes differ: one
+ * is a missing input (a context field), the other is the filesystem. A caller
+ * that cannot tell them apart cannot advise.
+ */
+ | 'reorient-write-failed' | 'reentry-failed'
+/**
+ * The challenge could not be marked consumed, so the clear was not attempted.
+ *
+ * Distinct from `reentry-failed` because the recovery differs: by this point a
+ * re-entry is already queued, so a retry queues a SECOND one. The message has
+ * to say so.
+ */
+ | 'challenge-burn-failed' | 'clear-failed';
+export interface BeginResult {
+    nonce: string;
+    statePath: string;
+    challengePath: string;
+    /** The message telling the builder what to write. */
+    saveRequest: string;
+}
+export interface SelfRefreshResult {
+    /**
+     * `dry-run` is deliberately distinct from `aborted`.
+     *
+     * A rehearsal that verified and assembled cleanly is a SUCCESS, and folding it
+     * into `aborted` would make the report announce "ABORTED" on a healthy run and
+     * force every caller's exit-code logic to special-case `failure === undefined`
+     * — a contract nobody would guess from the type.
+     */
+    outcome: 'completed' | 'aborted' | 'dry-run';
+    steps: SelfRefreshStep[];
+    /** Present when aborted — which gate refused, for the report. */
+    failure?: SelfRefreshFailure;
+    /** Human-readable reason, naming the specific gate. */
+    reason?: string;
+    statePath: string;
+    reorientPath?: string;
+    payload?: ReorientationPayload;
+    stateBytes?: number;
+}
+/** The persisted challenge. */
+export interface Challenge {
+    nonce: string;
+    issuedAt: number;
+    /** Boundary id from porch, e.g. `enter:review`. Shapes the save request. */
+    boundary?: string;
+    /**
+     * Set immediately BEFORE the clear is attempted; refused by the gate on any
+     * later run. Makes a challenge single-use even when the post-clear delete
+     * fails, which is the difference between "tidied up" and "cannot be replayed".
+     */
+    consumedAt?: number;
+}
+/**
+ * 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 declare function buildBoundarySaveRequest(nonce: string, statePath: string, boundary?: string): string;
+/**
+ * `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 declare function challengeFilePath(worktreePath: string): string;
+export declare function reorientFilePath(worktreePath: string): string;
+export interface BeginOptions {
+    fs: SelfRefreshFsPort;
+    clock: SelfRefreshClockPort;
+    worktree: string;
+    boundary?: string;
+    /** Injected for tests; defaults to the real generator. */
+    makeNonce?: () => string;
+}
+/**
+ * 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 declare function beginSelfRefresh(options: BeginOptions): BeginResult;
+export declare function parseChallenge(raw: string, now: number): {
+    ok: true;
+    challenge: Challenge;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface RunSelfRefreshOptions {
+    fs: SelfRefreshFsPort;
+    clock: SelfRefreshClockPort;
+    terminal: SelfTerminalPort;
+    git: SelfGitPort;
+    context: ResolvedBuilderContext;
+    buildSpawnPrompt: SpawnPromptPort;
+    buildResumeNotice?: ResumeNoticePort;
+    issue?: IssuePayload;
+    addendum?: string;
+    minBytes?: number;
+    stabilityWindowMs?: number;
+    reentryDelaySeconds?: number;
+    /**
+     * Reject a challenge older than this. Defaults to
+     * {@link DEFAULT_CHALLENGE_MAX_AGE_MS}.
+     */
+    challengeMaxAgeMs?: number;
+    /**
+     * Boundary this run is FOR, when the caller knows it.
+     *
+     * A challenge names the boundary it was issued at. If an execute aborts
+     * (dirty worktree, Tower down) the challenge survives on disk, and the builder
+     * may then commit, work on, and reach a LATER boundary. Running execute there
+     * without a fresh `begin` would let the lingering challenge validate a
+     * `.builder-state.md` describing superseded work — precisely the staleness the
+     * handshake exists to stop.
+     */
+    expectedBoundary?: string;
+    /** Report what would happen; send nothing, clear nothing, consume nothing. */
+    dryRun?: boolean;
+    /** Escape hatch for a worktree that is legitimately dirty. Off by default. */
+    allowDirty?: boolean;
+}
+export declare function runSelfRefresh(options: RunSelfRefreshOptions): Promise<SelfRefreshResult>;
+/**
+ * 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 declare function buildAutomaticReentryFrame(inline: string): string;
+/**
+ * The literal marker. Exported so tests pin the exact string a builder sees,
+ * rather than a paraphrase that could drift away from it.
+ */
+export declare const AUTOMATIC_REENTRY_MARKER = "## AUTOMATIC CONTEXT REFRESH \u2014 re-entry (not an architect instruction)";
+/** Render a result for a human. */
+export declare function formatSelfRefreshReport(result: SelfRefreshResult): string;
+/**
+ * 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 declare function didClear(result: SelfRefreshResult): boolean;
+/** Strictly confirmed: `sendRaw` returned successfully. */
+export declare function didClearConfirmed(result: SelfRefreshResult): boolean;
+export type { ReceiptObservation };
+//# sourceMappingURL=self.d.ts.map

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

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