@autopilot-harness/core 0.1.0

package/dist/review-engine.d.ts

@@ -0,0 +1,263 @@
+import { type ConfirmLens } from "./review-lenses.js";
+import type { ReviewScope } from "./project-config.js";
+import { type SessionRow, type StateStore } from "./state-store.js";
+import { type VerifyCommandConfig } from "./verify-report.js";
+export type FollowupKind = "review.fix" | "review.confirm" | "review.confirm_final" | "advance" | "done" | "review_complete" | "recover" | "recover_planning" | "recover_ambient" | "stuck" | "verify_fix";
+export interface FollowupAction {
+    kind: FollowupKind;
+    message: string;
+    /** false = deliver message once without requesting another agent turn. */
+    loop: boolean;
+    meta?: Record<string, string | number | boolean>;
+}
+export interface StopHandlerInput {
+    conversationId: string;
+    status: "completed" | "error" | "aborted";
+    loopCount: number;
+    /** Cursor transcript path — enables pending redelivery / in-flight gating. */
+    transcriptPath?: string;
+}
+export interface ReviewEngineConfig {
+    confirmRounds: number;
+    /** When completed-stop fix→confirm may run. Default executing_only. */
+    reviewScope: ReviewScope;
+    verifyEnabled: boolean;
+    verifyCommands: VerifyCommandConfig[];
+    maxIdleStops: number;
+    /** 0 = never pause on turn errors. */
+    maxErrorsBeforePause: number;
+    projectRoot: string;
+    /**
+     * Error-stop recover debounce / same-window coalesce (ms).
+     * Default {@link RECOVER_DEBOUNCE_MS} (3000). Tests pass 0 to skip sleep.
+     */
+    recoverDebounceMs?: number;
+    /** Override sync sleep used by recover debounce (tests). */
+    sleepSync?: (ms: number) => void;
+    /** Optional override for verify report path (tests). */
+    verifyReportPath?: string;
+    /** Render followup message; default English templates. */
+    renderFollowup?: (kind: FollowupKind, vars: Record<string, string | number>) => string;
+    /** Resolve confirm lens; default English CONFIRM_LENSES. */
+    resolveLens?: (roundIndex: number, confirmRounds: number) => ConfirmLens;
+}
+export declare class ReviewEngine {
+    private readonly store;
+    private readonly config;
+    constructor(store: StateStore, config: ReviewEngineConfig);
+    private render;
+    private lens;
+    /**
+     * FS trust root: StateStore is authoritative.
+     * config.projectRoot must not widen the boundary (mismatched/evil config).
+     */
+    private trustedProjectRoot;
+    /**
+     * Parse session checklist only when realpath stays under the project root.
+     * O_NOFOLLOW alone cannot stop intermediate directory symlink escapes or a
+     * poisoned absolute checklist_path in the session row.
+     */
+    private parseSessionChecklist;
+    private reviewChainResetFields;
+    private renderAdvanceOrDone;
+    /** Resolve sticky reviewing id from chain, or fall back to hint / firstUnchecked. */
+    private resolveReviewingItemId;
+    /** E1: afterFileEdit product code → code_edited=1 (+ sticky reviewing_item_id). */
+    onCodeEdited(conversationId: string): void;
+    handleStop(input: StopHandlerInput): FollowupAction | null;
+    private pendingBlocksAdvance;
+    private tryRedeliverPending;
+    private inferPendingKind;
+    private emit;
+    /**
+     * Cursor Stop button (and similar host interrupts) arrive as status=aborted.
+     * Do not inject recover — that fights the user and loops with loop_limit:null.
+     * Drop recover/stuck pending so transcript revert cannot redeliver them later.
+     * Clear sticky code_edited so Stop→revert→resend cannot open a phantom fix
+     * chain on the next completed stop (disk may already be clean).
+     * Leave fix/confirm pending alone (delivery retry still valid if inject raced).
+     * Both clears share one exclusiveWrite so a mid-abort failure cannot leave
+     * recover gone while code_edited sticky (or the reverse).
+     */
+    private handleAbortedStop;
+    private handleErrorStop;
+    private resolveRecoverDebounceMs;
+    private sleepRecoverDebounce;
+    /**
+     * Error recover: claim under exclusiveWrite → sleep debounce → emit at most
+     * once per window. Concurrent error stops in the same window coalesce to null.
+     * Outside the window, if still dead, redeliver once (new window).
+     * Emit ownership is CAS'd on `pending_followup_at` so claimer+redeliver
+     * cannot both return followup_message after overlapping sleeps.
+     */
+    private debouncedErrorRecover;
+    /**
+     * Claim the recover inject slot for this error storm.
+     * - coalesced: another stop already owns the window → do not emit
+     * - claimer/redeliver: pending written; `stamp` is pending_followup_at for CAS emit
+     * - failed: exclusiveWrite threw
+     */
+    private tryClaimErrorRecoverWindow;
+    /**
+     * After debounce: skip inject if the session already revived or recover is
+     * already in-flight on the transcript; otherwise CAS-emit on claim stamp.
+     */
+    private finishErrorRecoverAfterDebounce;
+    /**
+     * True when finish-time inflight is the same dead harness tip snapped at claim.
+     * Requires the same harness kind first (fix vs confirm must not match), then
+     * exact match. Only fix tips allow finish starting with claim's 48-char prefix
+     * (round digits appear early in en/zh). Confirm is exact-only: English confirm
+     * puts {lensTitle} after ~100 chars, so a 48-prefix would treat different
+     * lenses as the same tip. Advance/Briefly stay exact-only for the same
+     * shared-lead-in reason.
+     */
+    private isSameDeadHarnessTip;
+    /**
+     * Classify completed-stop orphan transcript errors from one tail read.
+     * - none: no unresolved turn_ended error
+     * - skip_recover_tip: unresolved error AND a recover tip after that error
+     *   (do not re-bump error_count / re-enter handleErrorStop)
+     * - salvage: unresolved error with no post-error recover tip yet
+     *
+     * Invariant: a newer turn_ended error after an old unanswered recover tip must
+     * salvage again — the prior tip does not cover the new failure.
+     */
+    private classifyCompletedOrphan;
+    /** Coarse kind bucket so fix/confirm/advance tips cannot share a prefix match. */
+    private harnessFollowupKind;
+    /**
+     * Atomically take emit ownership: only the stop whose claim stamp still
+     * matches may return followup. Winner bumps pending_followup_at so a racing
+     * redeliver lands in-window and coalesces instead of double-injecting.
+     */
+    private tryCasRecoverEmit;
+    private clearRecoverPendingBestEffort;
+    /**
+     * Block completed-stop recover redelivery for ~holdMs using pending_redeliver_at
+     * against {@link PENDING_REDELIVER_COOLDOWN_MS}. CAS emit nulls the hold so a
+     * host-dropped inject can redeliver immediately (unlike gating on
+     * pending_followup_at, which CAS refreshes and would extend the block).
+     *
+     * When holdMs > cooldown, `at` is in the future so
+     * {@link pendingRedeliverAllowed} stays false until ~holdMs elapses — do not
+     * clamp hold to cooldown (that would unblock mid-sleep for long debounce).
+     */
+    private armRecoverClaimRedeliverHold;
+    /**
+     * Last-resort when tryClaimErrorRecoverWindow's exclusiveWrite failed.
+     * Retries ambient soft-reset+pending up to 3×; then column-only disarm +
+     * emitRecover (never unlocked neutralize/soft-reset, never full-neutralize
+     * after transient lock failures — that wiped mid-confirm confirm_left).
+     * Skip wipe/emit when recover pending already exists.
+     */
+    private compensateFailedErrorRecoverClaim;
+    /** After a successful compensate write, drop recover if session paused mid-flight. */
+    private recoverActionIfStillRunnable;
+    private sessionStillErrorRecoverable;
+    /**
+     * Compensating emit after claim failure: never overwrite a peer recover pending.
+     * Ambient: soft-reset under the same lock before stamp (resume mid-fix /
+     * preserve mid-confirm). Never unlocked soft-reset on the legacy fallback.
+     * If exclusiveWrite is unavailable, fall back to legacy {@link emit} only when
+     * no recover pending is visible and a recover row was stamped.
+     */
+    private emitRecoverAfterFailedClaim;
+    /**
+     * Ambient error recover write: soft-reset + recover pending under one
+     * exclusiveWrite. "exists" = peer already claimed recover (do not overwrite).
+     */
+    private tryCommitAmbientErrorRecover;
+    /**
+     * Ambient/planning error recover: drop confirm/pending arming so recover
+     * (armChain=false) cannot leave chain_pending=1 → phantom E3.
+     *
+     * Call only under exclusiveWrite (with savePendingFollowup). Compensate must
+     * not call this unlocked: clearing undelivered confirm/fix pending while
+     * confirm_left is already post-decrement desyncs the next E4 lens.
+     *
+     * Preserve mid-confirm / E5-ready counters so the completed stop after
+     * recover continues E4/E5. Ready-for-E3 (fix done, chain_pending only)
+     * advances into confirm via confirm_left=confirmRounds (E4 emits 1/N) —
+     * do not regress to another fix. Ready-for-E3 requires empty pending (not
+     * merely !fixPending). Force code_edited only for an active fix
+     * (code_edited / undelivered fix pending / chain_pending with pending still
+     * set). Bare leftover fix_round is ignored (ambient phantom residue).
+     */
+    private applySoftResetAmbientChainForErrorRecover;
+    /** Shared with inferPendingKind — locale templates must keep these prefixes. */
+    private isFixFollowupMessage;
+    /** Mid-confirm or E5-ready — must not phantom-arm code_edited over E4/E5. */
+    private isMidConfirmOrE5;
+    /** True when a stop may still advance the review chain (re-check under write lock). */
+    private sessionRunnable;
+    /** Genuine error stop may inject recover (planning, project ambient, or armed executing). */
+    private sessionErrorRecoverable;
+    private recoverKindForPhase;
+    /** completed stop → reset error_count */
+    noteCompletedOk(session: SessionRow): void;
+    private maybeResetErrorCountOnItemChange;
+    /**
+     * E0': checklist executing, not in fix/confirm — skip lenses when there is no
+     * product code edit. Soft/verified success advances in one IMMEDIATE txn with
+     * evidence re-check (never arm at-E5 first). Only required-verify *fail*
+     * arms at-E5 to reuse E5c verify_fix / stuck.
+     */
+    private e0NoCodeContinue;
+    /**
+     * E0 direct advance/done: re-check soft or verified evidence under one
+     * IMMEDIATE write — never enters the confirm/E5 state machine.
+     */
+    private e0DirectAdvance;
+    /** Arm confirm_left=0 + ICC=1 only when still idle on the no-code path. */
+    private armAtE5ForNoCode;
+    /** Undo a failed arm so the next stop cannot skip soft evidence via E5. */
+    private disarmE5NoCode;
+    /** Session-monotonic round counter (fix + confirm share fix_round; no hard cap). */
+    private nextSessionRound;
+    private e2Fix;
+    private e3ArmConfirm;
+    private e4Confirm;
+    private e5Gate;
+    private e5bAdvance;
+    private bumpProgress;
+    /**
+     * Best-effort session bookkeeping after a followup was already committed
+     * (pending_followup in exclusiveWrite). Must not throw into handleStop's
+     * soft-fail catch — that would drop the committed action from the hook reply.
+     */
+    private afterFollowupCommitted;
+    private incrementIdle;
+    /** After a no-progress stop that didn't inject, check stuck threshold. */
+    checkStuck(session: SessionRow): FollowupAction | null;
+}
+/** Apply OFF trigger side effects (v0.1). */
+export declare function applyOff(store: StateStore, conversationId: string): SessionRow | null;
+/** Apply ON trigger side effects (v0.1). */
+export declare function applyOn(store: StateStore, conversationId: string, projectRoot: string, opts?: {
+    initialBrief?: string;
+    slug?: string;
+}): {
+    ok: true;
+    session: SessionRow;
+} | {
+    ok: false;
+    userMessage: string;
+};
+export type ApplyResumeResult = {
+    ok: true;
+    session: SessionRow | null;
+} | {
+    ok: false;
+    userMessage: string;
+};
+/**
+ * Apply RESUME: unpause local session, or claim another conversation's track
+ * onto this conversation_id (preserving review_chains).
+ */
+export declare function applyResume(store: StateStore, conversationId: string, opts?: {
+    slug?: string;
+}): ApplyResumeResult;
+/** resume_review: only chain_pending=1 */
+export declare function applyResumeReview(store: StateStore, conversationId: string): void;
+//# sourceMappingURL=review-engine.d.ts.map

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

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