toolroll 0.5.0

package/dist/claim.d.ts

@@ -0,0 +1,688 @@
+/**
+ * The claim, and the fence around it.
+ *
+ * This is the record §4 calls the one that matters, and the reason is a
+ * specific 3am failure. A runner takes a task, starts work, and then stops
+ * being reachable — the machine sleeps, the process is OOM-killed, the network
+ * partitions. The scheduler cannot tell "dead" from "slow", so it waits for the
+ * lease to expire and gives the task to someone else. Then the first runner
+ * wakes up, finishes the work it was doing, and reports success for a task that
+ * another runner is now halfway through.
+ *
+ * Both runners are behaving correctly. Without a fence, the control plane
+ * believes the last one to speak.
+ *
+ * So a lease carries two things. `lease_id` is immutable and identifies one
+ * grant of one task to one runner. `lease_generation` counts how many times
+ * that task has been granted at all, and it only ever goes up. Acquiring is a
+ * compare-and-swap on the generation; every later call carries the lease it
+ * thinks it holds, and anything whose generation has been superseded is
+ * refused. The late completion above is refused not because we detected the
+ * crash — we never did — but because the world moved on without it.
+ *
+ * Losing a race here is ordinary, not an error. Several runners asking for the
+ * same task at the same moment is the system working; exactly one wins.
+ *
+ * Time is a parameter everywhere. Expiry decided by an implicit clock is
+ * untestable, and a lease is exactly the kind of thing that has to be provable
+ * rather than probable.
+ */
+import { type Store, type Mutation, type TaskState } from "./store.js";
+import type { ParsedDecision, Problem } from "./decision.js";
+import type { ParsedPlan } from "./plan.js";
+import { type PlannerSource } from "./planner-source.js";
+import type { AuthorityChangeField } from "./plan.js";
+import type { ParsedReport } from "./scout-report.js";
+export type Claim = {
+    taskRef: number;
+    /** Immutable. Identifies this grant, and no other. */
+    leaseId: string;
+    /** Monotonic per task. The fencing token. */
+    generation: number;
+    runner: string;
+    acquiredAt: string;
+    expiresAt: string;
+    heartbeatAt: string;
+};
+export type AcquireResult = {
+    ok: true;
+    claim: Claim;
+    reclaimed: boolean;
+    replayed?: boolean;
+} | {
+    ok: false;
+    reason: "held";
+    by: string;
+    until: string;
+} | {
+    ok: false;
+    reason: "reserved";
+    reservedFor: string;
+} | {
+    ok: false;
+    reason: "external";
+    detail: "stale-mirror" | "external-closed" | "dispatch-revoked" | "plane-blocked";
+}
+/** An attended authorization holds this task for its named runner (v25).
+ * Its OWN reason token — never the `reserved` tag, whose reservedFor field
+ * is a documented public contract meaning task_ref.assigned_runner. */
+ | {
+    ok: false;
+    reason: "attended-held";
+    runner: string;
+}
+/** The task's only authority is an attended authorization, and the
+ * operator is not watching (or the one attempt is spent). Expiry never
+ * converts attended work into unattended work. */
+ | {
+    ok: false;
+    reason: "attended-only";
+}
+/** A mode-sealed approval whose signature no longer stands (v29): the
+ * approval falls back to a person; nothing dispatches on a dead mode. */
+ | {
+    ok: false;
+    reason: "mode-ended";
+    message: string;
+}
+/** The credential presented with this acquisition did not verify against
+ * the runner row AT CLAIM TIME (MCP spec v6): stale incarnations never
+ * ride a successor's rotation. */
+ | {
+    ok: false;
+    reason: "unauthenticated";
+    detail: "unknown" | "bad-token" | "retired" | "expired";
+}
+/** The task is placed nowhere — a repo-scoped runner cannot be
+ * authorized for null. Place it, then dispatch. */
+ | {
+    ok: false;
+    reason: "unplaced";
+}
+/** The runner's bound repo list does not contain the task's repo.
+ * The refusal names the binding road. */
+ | {
+    ok: false;
+    reason: "unauthorized-repo";
+    repo: string;
+}
+/** A coordinator filed this and no password ceremony has sealed its
+ * scope yet — nothing claims, plans, or runs it until one does. */
+ | {
+    ok: false;
+    reason: "coordinator-filed";
+};
+/** `fenced` means the lease was superseded; `unknown` means it never existed. */
+export type FenceResult = {
+    ok: true;
+    claim: Claim;
+    duplicate?: boolean;
+} | {
+    ok: false;
+    reason: "fenced" | "unknown" | "stopped";
+};
+/**
+ * Completion's OWN result (external dispatch, finding 33): `completed` is
+ * today's world — the task is done/failed as asked; `disowned` means the
+ * tracker closed this mirror while it was being built — the task is
+ * cancelled, the branch is kept as evidence, and the caller must never
+ * publish. The arm is DURABLE (claim.released_by), so a retried completion
+ * returns its original answer forever.
+ */
+export type CompleteResult = {
+    ok: true;
+    arm: "completed" | "disowned";
+    claim: Claim;
+    duplicate?: boolean;
+} | {
+    ok: false;
+    reason: "fenced" | "unknown" | "stopped";
+};
+/** How stale a mirror's last complete sync may be before admission refuses. */
+export declare const SYNC_MAX_AGE_MS: number;
+export type AcquireOptions = {
+    now: Date;
+    /** The runner's minted credential, re-verified INSIDE the claim
+     * transaction (MCP gateway spec v6, Codex round-5 finding 1): a
+     * takeover that rotates the credential between the caller's own auth
+     * and this CAS must not let the stale process ride its successor's
+     * authority. */
+    token: string;
+    ttlMs?: number;
+    /** Injected in tests so a lease id can be asserted on. */
+    newLeaseId?: () => string;
+    /** The watch incarnation dispatching this claim, for crash recovery keyed to it. */
+    incarnation?: string;
+    mutation?: Mutation;
+    /** External-mirror freshness bound; defaults to SYNC_MAX_AGE_MS. */
+    syncMaxAgeMs?: number;
+};
+/**
+ * Long enough that an ordinary build does not lose its lease mid-thought,
+ * short enough that a dead runner's work is picked up the same night rather
+ * than at breakfast.
+ */
+export declare const DEFAULT_LEASE_MS: number;
+/**
+ * Take the task, if it is free.
+ *
+ * Free means no claim, or a claim whose lease expired, or one already released.
+ * A live lease belonging to somebody else is refused with who holds it and
+ * until when, because "no" without a reason is indistinguishable from a bug.
+ */
+export declare function acquire(store: Store, taskRef: number, runner: string, options: AcquireOptions): AcquireResult;
+/**
+ * Why `acquireIfReady` said no before the race was even run. `not-ready` is
+ * about the task's own state; `capability` is about the machine's — a gap a
+ * person can fill, named so the caller can say which.
+ */
+export type NotReady = {
+    ok: false;
+    reason: "not-ready" | "capability" | "attention-budget" | "capacity" | "quota" | "provider-unavailable";
+    message: string;
+};
+/** DESIGN §8 gate 6: above this many open decisions, stop dispatching the parkers.
+ * `missingCapability` remains re-exported for callers of the old claim seam. */
+export { DEFAULT_MAX_OPEN_DECISIONS, missingCapability } from "./dispatch.js";
+/**
+ * Take the task, if it is free *and still worth taking*.
+ *
+ * `listReady` then `acquire` is two reads of a world that moves between them:
+ * a hold placed, a blocker reopened, the task cancelled — and the CAS admits
+ * the claim anyway, because the CAS only defends against other claimants. An
+ * unattended pass has nobody watching who would notice the stale dispatch, so
+ * the readiness conditions are re-proved inside the same transaction as the
+ * acquire, against rows the write lock has already pinned.
+ *
+ * "Not ready" is a different answer from "held": held means somebody else got
+ * it, which is a race being won; not-ready means nobody should have it, and
+ * says why.
+ */
+export declare function acquireIfReady(store: Store, taskRef: number, runner: string, options: AcquireOptions & {
+    repo?: string;
+    maxOpenDecisions?: number;
+    /** The provider this dispatch resolved to — the quota key. */
+    provider?: string;
+    /** The model this dispatch would run — the quota scope. */
+    model?: string;
+    /** What this dispatch is FOR. Re-proved inside the transaction — the
+     * caller's survey is not trusted (Codex planning review, finding 2). */
+    dispatchRole?: "builder" | "planner" | "scout";
+}): AcquireResult | NotReady;
+/**
+ * The FALLBACK-ADMISSION claim (E3d, review finding 4): the one gate a
+ * pending-admission chain cycle dispatches through. It enforces everything
+ * `acquireIfReady` enforces — task state, holds, blockers, the approved
+ * scope + live-mode belt, capability, capacity, and quota — with EXACTLY
+ * ONE deliberate difference: a BACKOFF hold does not gate, because the
+ * pending admission IS the system's answer to the predecessor's failure
+ * (waiting out the exhausted entry's backoff to run a different credential
+ * would be waiting for nothing). Quota is keyed by the PINNED entry's
+ * provider, model, and auth mode — the credential that would actually
+ * spend — so an exhausted fallback credential refuses here, before any
+ * claim exists.
+ */
+export declare function acquireFallback(store: Store, taskRef: number, runner: string, options: AcquireOptions & {
+    repo?: string;
+    provider: string;
+    model: string;
+    authMode: "subscription" | "api-key";
+    maxOpenDecisions?: number;
+}): AcquireResult | NotReady;
+/**
+ * "I am still here." Extends the lease, and tells a superseded runner that it
+ * has been superseded — which is the cheapest moment for it to find out, well
+ * before it has finished work nobody will accept.
+ */
+export declare function heartbeat(store: Store, leaseId: string, now: Date, ttlMs?: number): FenceResult;
+/**
+ * Hand the task back.
+ *
+ * Accepted only from the lease that currently holds it. A completion arriving
+ * on a superseded lease is the failure this whole module exists for, and it is
+ * rejected without touching anything — the work is not lost, it is simply not
+ * this runner's to report, and the record says so rather than overwriting a
+ * live claim with a dead runner's opinion.
+ */
+export declare function release(store: Store, leaseId: string, now: Date): FenceResult;
+/**
+ * Release the lease and write the task's terminal state, as one step.
+ *
+ * Release-then-mark is a window: between the two, the freed task is back in
+ * the ready set, and another pass can claim it before the terminal state
+ * lands — two builders for one task, the second dispatched by our own
+ * bookkeeping. Here the state is written inside the same transaction as the
+ * fenced release, so a task is never simultaneously free and unfinished.
+ *
+ * A fenced or unknown lease writes nothing: a runner the world moved past
+ * does not get to say how the task ended. A duplicate release reports
+ * `duplicate` and also writes nothing — the first completion already said,
+ * and a retry changing the answer would make "done" negotiable.
+ */
+export declare function completeFenced(store: Store, leaseId: string, state: Extract<TaskState, "done" | "failed">, now: Date, mutation?: Mutation): CompleteResult;
+/**
+ * Seal a park, fenced at the write (§7).
+ *
+ * The builder proved its lease after the agent ran; this transaction proves
+ * it again *in the same statement that releases it*, because everything a
+ * park creates — the decision, its hold, the outbox row — is only true if
+ * this lease still spoke for the task at the moment of sealing. A superseded
+ * lease creates none of it: no decision, no hold, no notification, and the
+ * run is finalized as the fenced refusal it was. A crash anywhere inside
+ * rolls all of it back together; there is no instant at which a decision
+ * exists without its hold.
+ *
+ * `released_by = 'parked'` so a late retry from this lease is answered with
+ * the fence, not "duplicate": a park hands the task to a person, and nothing
+ * the runner says afterwards is that person's answer.
+ */
+/**
+ * Continuation admission (Phase 2E, A4 / v3 R7): the AUTHORIZATION is the
+ * claimable unit — the finished parent task is never re-queued, its state,
+ * strikes, holds, and dependents untouched. Every shared gate still runs
+ * (acquireLocked: reservation, external mirror, the attended gates, the
+ * lease CAS); the queued-state readiness gate alone is replaced by
+ * construction. Liveness, the named runner, and the unspent attempt are
+ * re-proved HERE at claim time and again at the final dispatch proof.
+ */
+export declare function acquireContinuation(store: Store, authorization: import("./store.js").AttendedAuthorization, runner: string, options: AcquireOptions): AcquireResult | {
+    ok: false;
+    reason: "attended-only" | "contest-open" | "continuation-blocked";
+    message: string;
+};
+/**
+ * The HELD park (Phase 2E, v2 S1f): the decision is recorded, paged, and
+ * causally linked to the session turn that produced it — and NOTHING else
+ * ends. The lease stays; the run stays open; the process stays held. The
+ * conversation continues when the answer is injected as the next turn.
+ * The one-unresolved-per-run partial unique refuses a second open park.
+ */
+export declare function finalizeParkHeld(store: Store, args: {
+    runId: number;
+    taskId: string;
+    decision: ParsedDecision;
+    artifactIds: readonly number[];
+    sessionTurn: number;
+    now: Date;
+}): {
+    ok: true;
+    decisionId: number;
+} | {
+    ok: false;
+    reason: "decision-open" | "not-held";
+};
+export declare function finalizeParkFenced(store: Store, args: {
+    leaseId: string;
+    runId: number;
+    taskId: string;
+    decision: ParsedDecision;
+    artifactIds: readonly number[];
+    /** Open planner correction that authored the accepted payload. It is
+     * settled in this same fence, never earlier. */
+    repairRunId?: number | null;
+    now: Date;
+}): {
+    ok: true;
+    decisionId: number;
+} | {
+    ok: false;
+    reason: "fenced" | "unknown" | "stopped";
+};
+/**
+ * Seal a park whose payload never became a decision (§6's bounded repair ran
+ * out). Same fence, same atomicity, different record: an incident that stays
+ * in every brief until a person resolves it, holding the task so the next
+ * pass does not spend the same tokens hitting the same wall nightly. The
+ * malformed payload is preserved as evidence — a person may still be able to
+ * read what the agent meant.
+ */
+export declare function finalizeMalformedFenced(store: Store, args: {
+    leaseId: string;
+    runId: number;
+    taskId: string;
+    problems: readonly Problem[];
+    now: Date;
+}): {
+    ok: true;
+    incidentId: number;
+} | {
+    ok: false;
+    reason: "fenced" | "unknown" | "stopped";
+};
+/** How a failed attempt is classified, per gnhf. Decides retry, backoff, or stall. */
+export type FailureClass = "agent-reported" | "retryable-infra" | "no-op" | "commit-failure" | "unknown";
+export declare const MAX_STRIKES = 3;
+export type FailureDisposition = {
+    ok: true;
+    disposition: "backoff";
+    strikes: number;
+    until: string;
+} | {
+    ok: true;
+    disposition: "stalled";
+    strikes: number;
+    incidentId: number;
+} | {
+    ok: true;
+    disposition: "commit-incident";
+    incidentId: number;
+} | {
+    ok: false;
+    reason: "fenced" | "unknown" | "stopped";
+};
+export type InterruptSeal = {
+    ok: true;
+    stopRun: number;
+    requeued: boolean;
+    fenced: false;
+} | {
+    ok: true;
+    stopRun: number;
+    requeued: false;
+    fenced: true;
+};
+/**
+ * Seal an operator-stopped attempt (v52): ONE fenced transaction for the
+ * claim's release as `interrupted`, the run's ending as `failed` /
+ * `interrupted` (the same words dead-runner recovery writes, so the
+ * recovered-draft road inherits the preserved work exactly as after a
+ * crash), every open run the attempt owns, the task's return to the
+ * queue under the stop's own hold, and the stop's settlement. Nothing
+ * here is a failure: no strike, no backoff, no incident, no automatic
+ * repair task, no notification page. A commit the attempt already made
+ * is kept as a reviewable artifact — `committed` records that it exists.
+ *
+ * A lease the world moved past (reaped, recovered, superseded) still
+ * ends the run as interrupted — that IS the honest ending — but touches
+ * no task state: the task belongs to whoever holds it now.
+ */
+export declare function finalizeInterruptedFenced(store: Store, args: {
+    leaseId: string;
+    runId: number;
+    taskId: string;
+    stopRun: number;
+    message?: string;
+    committed?: boolean;
+    now: Date;
+}): InterruptSeal;
+/**
+ * THE STOP FENCE at settlement (v52): when a stop applies to the run —
+ * its own or an owning ancestor's — seal the attempt as interrupted and
+ * answer with the seal; otherwise null, and the caller's own ending
+ * proceeds. Every fenced finalizer asks this first, inside its own
+ * transaction, so a stop that commits before terminal settlement wins
+ * whatever the attempt was about to say.
+ */
+export declare function interruptIfStopped(store: Store, args: {
+    leaseId: string;
+    runId: number;
+    taskId: string;
+    message?: string;
+    committed?: boolean;
+    now: Date;
+}): InterruptSeal | null;
+/**
+ * Seal a failed attempt: one fenced transaction for the release, the run,
+ * the strike, the hold, and the page (§6, gnhf adopted rather than
+ * reinvented).
+ *
+ * Strikes count only top-level builder attempts; built, no-change, and
+ * parked reset them elsewhere; refusals, fenced attempts, and repair
+ * children never reach this function. Under three strikes the task
+ * requeues behind a doubling backoff hold the failure owns; at three it
+ * stalls — an 'attempts-exhausted' incident, the task marked failed, held,
+ * and paged once — because a fourth identical attempt at 3am is a token
+ * bonfire, not persistence. A commit-stage failure takes neither road: the
+ * worktree holds unpreserved work, ordinary re-pooling would refuse it as
+ * dirty forever, so it is an immediate incident naming the checkout.
+ */
+export declare function finalizeFailureFenced(store: Store, args: {
+    leaseId: string;
+    runId: number;
+    taskId: string;
+    failureClass: FailureClass;
+    message: string;
+    worktree: string;
+    now: Date;
+}): FailureDisposition;
+/** The live claim on a task, if there is one. */
+export declare const MAX_PLAN_STRIKES = 3;
+export type PlanFinalize = {
+    ok: true;
+    changes: number;
+    amendment: string | null;
+} | {
+    ok: false;
+    reason: "fenced" | "unknown" | "stopped";
+}
+/** The filed request moved while the planner ran (contract handoff,
+ * task 1): the draft was planned against terms that no longer exist,
+ * so nothing of it is ingested — the newer source stands, the claim
+ * releases, and the task stays requested for a fresh attempt. */
+ | {
+    ok: false;
+    reason: "stale-source" | "source-invalid";
+    detail: string;
+};
+/**
+ * Seal a successful planning run: the proposed scope, the plan document
+ * artifact, the drafted state, the run outcome, and the page to the
+ * operator exist together or — if the lease was superseded — not at all.
+ * The scope proposal is authority-bearing (it is what the approve card
+ * will restate), which is why this is the park discipline, not the DONE
+ * one (Codex planning review, question 2).
+ */
+export declare function finalizePlanFenced(store: Store, args: {
+    leaseId: string;
+    runId: number;
+    taskId: string;
+    plan: ParsedPlan;
+    /** The already-captured plan document file, described; null when the
+     * capture itself failed (the plan still lands as scope + handoff). */
+    artifact: {
+        key: string;
+        bytesOriginal: number;
+        bytesStored: number;
+        truncated: boolean;
+        sha256: string;
+        capture: string;
+    } | null;
+    /** Open planner correction that authored the accepted payload. */
+    repairRunId?: number | null;
+    /** The filed request this attempt planned for, and the recorded
+     * evidence of it (contract handoff, task 1). The source identity is
+     * re-derived from the store INSIDE this transaction and compared:
+     * a concurrent scope, authority, or term change refuses the draft
+     * atomically rather than letting an old plan overwrite the newer
+     * source. Optional only for the pre-source road (tests that seal a
+     * hand-built plan); every dispatch presents one. */
+    source?: PlannerSource;
+    sourceArtifact?: number | null;
+    /** Where the plan-contract ingestion record is written. */
+    evidenceRoot?: string;
+    now: Date;
+}): PlanFinalize;
+export type RevisionFinalize = {
+    ok: true;
+    revisionId: number;
+    authorityKind: "plan-only" | "authority-change";
+} | {
+    ok: false;
+    reason: "fenced" | "unknown" | "stopped";
+};
+/**
+ * Seal a running build's plan-revision proposal (adaptive execution plans).
+ *
+ * A builder that finds repository evidence invalidating a named dependency,
+ * risk, or assumption in the plan it was given files ONE proposal and stops
+ * without committing — the park discipline, applied to the road rather than
+ * to a question. The ledger row, the hold when one is owed, the run's
+ * outcome, and the page exist together or, if the lease was superseded,
+ * not at all. Structurally `finalizePlanFenced`'s twin: the same
+ * open-attempt assertion, the same fenced release, the same all-or-nothing
+ * transaction.
+ *
+ * Two dispositions, decided by the caller's classification and recorded
+ * here:
+ *
+ *   plan-only        the signed scope and publication authority are
+ *                    byte-identical to what this build started under, so
+ *                    nothing authority-bearing moved and the revision is
+ *                    APPLIED. The claim releases plainly, the task returns
+ *                    to the ready set, and the next attempt reads the new
+ *                    plan — that is the "resume" the subject line promises.
+ *
+ *   authority-change something else moved the signed scope or the
+ *                    publication authority WHILE this build ran. Whatever
+ *                    the revision proposes, it is never auto-applied: the
+ *                    row lands 'blocked', a `revision` hold keeps the task
+ *                    out of every ready set until a person accepts or
+ *                    rejects it, and the page names exactly which fields
+ *                    changed.
+ *
+ * The lease is released either way — the attempt is over — and the run is
+ * finished as `refused`, reusing the existing outcome vocabulary rather
+ * than growing it: no work was committed, and nothing failed.
+ */
+export declare function finalizeRevisionFenced(store: Store, args: {
+    leaseId: string;
+    runId: number;
+    taskId: string;
+    taskRef: number;
+    /** Every content column of the row about to be appended. `status` is
+     * NOT the caller's to set: it follows from `authorityKind`, decided in
+     * exactly one place — here — so a caller can never file an
+     * authority-changing revision as already applied. */
+    revision: {
+        revision: number;
+        artifact: number;
+        parentHash: string | null;
+        reason: string;
+        evidenceLink: string | null;
+        author: string;
+        originRun: number | null;
+        authorityKind: "plan-only" | "authority-change";
+        authorityDigest: string;
+        changedFields: readonly AuthorityChangeField[];
+    };
+    now: Date;
+}): RevisionFinalize;
+export type PlanFailureDisposition = {
+    ok: true;
+    disposition: "malformed-incident";
+    incidentId: number;
+} | {
+    ok: true;
+    disposition: "backoff";
+    strikes: number;
+} | {
+    ok: true;
+    disposition: "exhausted";
+    incidentId: number;
+    strikes: number;
+} | {
+    ok: false;
+    reason: "fenced" | "unknown" | "stopped";
+};
+/**
+ * The planner's own fenced failure finalizer (Codex planning review,
+ * finding 6): releases exactly the planner claim, finishes the run,
+ * counts a SEPARATE planning strike — a planner that cannot finish must
+ * never spend the builder's three attempts — and eventually leaves a
+ * durable incident + hold + page. It never marks the task done, never
+ * touches builder strikes, never commits, never publishes.
+ *
+ * A malformed payload goes straight to its incident with no strike: the
+ * protocol failed, not the weather, and retrying the same session buys
+ * nothing without the repair machinery (deliberately not wired for
+ * planners in v1).
+ */
+export declare function finalizePlanFailureFenced(store: Store, args: {
+    leaseId: string;
+    runId: number;
+    taskId: string;
+    kind: "malformed" | "failure";
+    /** Which payload was malformed (v4 review, finding 12): the mailbox is a `malformed-decision`. */
+    malformed?: "decision" | "plan";
+    message: string;
+    now: Date;
+}): PlanFailureDisposition;
+export type ScoutFinalize = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "fenced" | "unknown" | "stopped";
+};
+/**
+ * Seal a successful scouting run (mate arc §10): the report artifact, the
+ * run outcome, the task's terminal state, and the page to the operator
+ * exist together or — if the lease was superseded — not at all. Nothing
+ * here touches a branch, a publication, or a scope: the deliverable is
+ * the artifact, and the task is done the moment it verifies.
+ */
+export declare function finalizeScoutFenced(store: Store, args: {
+    leaseId: string;
+    runId: number;
+    taskId: string;
+    report: ParsedReport;
+    /** The already-captured report file, described. Required: a report
+     * that was not captured is a FAILED attempt, never a finished task
+     * (v4 review, finding 1). */
+    artifact: {
+        key: string;
+        bytesOriginal: number;
+        bytesStored: number;
+        truncated: boolean;
+        sha256: string;
+        capture: string;
+        redacted: boolean;
+    };
+    now: Date;
+}): ScoutFinalize;
+export type ScoutFailureDisposition = {
+    ok: true;
+    disposition: "malformed-incident";
+    incidentId: number;
+} | {
+    ok: true;
+    disposition: "backoff";
+    strikes: number;
+} | {
+    ok: true;
+    disposition: "stalled";
+    incidentId: number;
+    strikes: number;
+} | {
+    ok: false;
+    reason: "fenced" | "unknown" | "stopped";
+};
+/**
+ * The scout's fenced failure finalizer: the BUILDER's discipline, not the
+ * planner's — a scout task has no builder attempts, so its strikes are the
+ * task's own (three stall it, `task requeue` clears them), and a malformed
+ * report is a straight incident with no strike. Never a branch, never a
+ * repair session, never a commit.
+ */
+export declare function finalizeScoutFailureFenced(store: Store, args: {
+    leaseId: string;
+    runId: number;
+    taskId: string;
+    kind: "malformed" | "failure";
+    /** Which payload was malformed (v4 review, finding 12): the park
+     * mailbox is a `malformed-decision` incident, the handoff a
+     * `malformed-report` one — the taxonomy says what actually broke. */
+    malformed?: "decision" | "report";
+    message: string;
+    now: Date;
+}): ScoutFailureDisposition;
+export declare function currentClaim(store: Store, taskRef: number, now: Date): Claim | null;
+/**
+ * Release every lease that has run out.
+ *
+ * Expiry alone already frees a task for acquisition, so this is not what makes
+ * reclaim work — it is what makes it *visible*. A daemon reaping on a tick
+ * turns "this lease is being ignored because its timestamp is in the past" into
+ * a released row somebody can read, which is the difference between a system
+ * that recovers and a system that appears to have lost the work.
+ */
+export declare function reap(store: Store, now: Date): Claim[];