@open-everywhere/core 0.1.0

package/dist/agent/model/turn-closeout.js

@@ -0,0 +1,289 @@
+// turn-closeout — THE HARD TURN BOUNDARY FOR A TURN THAT HAS ALREADY CLOSED ITS WAKE (OPE-1520).
+//
+// ── THE FAILURE THIS EXISTS FOR ──────────────────────────────────────────────────────────────────
+// A seat closes its wake with `no_reply`, and then nothing ends the turn. The model calls `reply`
+// again a few seconds later, the host refuses it (`declined-this-turn`, tools/reply.ts), the refusal
+// text tells the model to output the sentinel, the model ignores it, and the loop repeats until the
+// GENERIC soft step budget cuts in at 120 round-trips. Measured on prod on 2026-09-07 (seat session
+// `wrun_41M1XN60YB0GQDPMXNZJ1588BA`): 68 `reply.refused` rows carrying `declined-this-turn` over 8
+// minutes 30 seconds, ended by `turn.step_boundary` at step 121, about $0.73 of model spend.
+//
+// Two costs, and the first is the expensive one:
+//   • A DISPATCHED BACKGROUND WORKER CANNOT START. The `agent` tool hands back a task handle at
+//     once, but eve only starts the child session after the PARENT PARKS. On that turn the child
+//     was named 4.4 seconds after the parent parked and answered 19 seconds later — so every step
+//     the seat spent spinning was a step the delegated job spent not existing. The control case in
+//     the same session (a turn that ended promptly) delivered the same shape of answer in 45
+//     seconds.
+//   • The turn keeps posting. A stand-down stored MID-TURN gates future wakes but not the running
+//     turn, so the seat acknowledged "standing down" and then posted the same answer six more times.
+//
+// ── WHAT THIS MODULE IS, AND WHAT IT IS NOT ──────────────────────────────────────────────────────
+// It is a per-turn LATCH: "this turn has closed its reply obligation and has since tried to speak
+// anyway". The reply path sets it on a refusal it draws AFTER the closeout; `model/step-boundary.ts`
+// reads it on the next model round-trip and returns the `closed` tier, which resolves the same
+// text-only stub model the hard backstop uses. That stub's assistant message carries no tool call,
+// so EVE'S OWN continue-decision ends the turn through its supported path. No patched byte, no new
+// mechanism, and the child dispatch starts one round-trip later instead of 120.
+//
+// 🔴 IT IS NOT A DUPLICATE-POST BLOCK, and the §DONE-VALVE is untouched. Tommy's OPE-1452 ruling
+// stands: a second post in one turn is DISCOURAGED, never hard-blocked
+// (channels/reply-signal.ts §DONE-VALVE). This module refuses nothing at all — it ends a TURN whose
+// reply obligation is closed and which is still trying to speak. The valve and this latch answer
+// different questions: the valve asks "may this message land?", this asks "is this turn still doing
+// anything?".
+//
+// 🔴 AND ONE ARMING ARM IS A POST THAT LANDED, NOT A REFUSAL (OPE-1659). The reply tool arms this
+// latch after a call that OVERRODE the same discouraged-duplicate verdict twice in one turn
+// (`forced-override-repeat`, channels/reply-signal.ts §FORCED). That post is in the room — the latch
+// runs after it, deliberately — and so was every one before it. Measured live on 2026-09-09: one wake
+// drew 201 override rows and 40 posts of one answer, and nothing on the host ended it; the session's
+// 30,000,000-token limit did. So the header's claim holds in the only sense that matters — no message
+// is blocked — but do not read "the host has already refused" as true of every arm. Three arms are
+// refusals, and the fourth is a repetition the host let through.
+//
+// 🔴 BE PRECISE ABOUT WHAT THE WHOLE CHANGE ADDS, THOUGH. One of the three arming arms is a NEW hard
+// refusal on the reply path: the stored stand-down (tools/reply.ts, reason `stopped`) refuses every
+// post after the acknowledgement, reads no `force`, and offers no valve. It sits with the wake
+// fence's arms and `declined-this-turn` rather than with the duplicate-post gates, and for their
+// reason: the OPE-1452 ruling is about a SECOND MESSAGE, and this one is about a conversation the
+// person asked the agent to leave. A stop is not a matter of style, so there is nothing there to
+// discourage instead of refuse. Do not read "not a duplicate-post block" as "no new hard refusal".
+//
+// ── WHY THE LIMIT IS ONE ─────────────────────────────────────────────────────────────────────────
+// The arming refusals are CONTRADICTIONS INSIDE ONE TURN, not matters of style: replying to a wake
+// this turn declined, posting into a conversation this turn was told to leave, or recording silence
+// twice. A model that draws one of those has already been told in words what to do instead, and the
+// prod trace is 68 rounds of it ignoring exactly that text. So the first one ends the turn.
+//
+// The `forced-override-repeat` arm reaches the same limit by its own route: the FIRST override of a
+// verdict is a judgement the ruling says must stay possible, so the reply tool counts to two before
+// it arms anything (channels/reply-signal.ts §FORCED). By the time it calls in here the turn has
+// already made the same override twice, which is the contradiction the other three arms name.
+//
+// 🔴 THE LOSS CASE, STATED HONESTLY: ENDING THE TURN DROPS EVERY WAKE IT HAD NOT YET ANSWERED. On a
+// COALESCED turn — several surfaces' wakes merged into one turn — that is a real cost, and it is
+// accepted rather than absent. THREE of the four arms are small enough to accept because they fire
+// only on a turn that has ALREADY closed its reply obligation:
+//   • `declined-this-turn` and `stopped` fire only on the turn's own declined or stopped wake, so a
+//     turn that simply answers its sibling never arms the latch;
+//   • the redundant-`no_reply` arm is TURN-scoped and takes no wake, so it CAN fire on a turn that
+//     still holds an unanswered sibling. But `no_reply` is turn-terminal by its own contract — its
+//     note reads "Turn reply requirement satisfied … Do not call another tool" — so a turn that has
+//     called it twice has, by the host's own declaration, nothing left to deliver to any wake.
+//
+// 🔴 THE FOURTH ARM CARRIES NO SUCH GUARANTEE, AND THE COST IS ACCEPTED ON ITS OWN TERMS (OPE-1659).
+// `forced-override-repeat` reads no `done`: the freshness gate applies to a `done: false` part
+// (channels/reply-freshness.ts) and the fold gate never sees `done` at all, so a MULTI-PART answer
+// that forces the same verdict twice arms the latch with its wake still OPEN, and the part it had not
+// written yet is never written. Two things bound that cost. The wake stays PENDING — no arm consumes
+// one — so the answer is not lost, only deferred to the next turn, exactly as it is when a turn ends
+// any other way. And reaching the arm at all means the model overrode ONE verdict about ONE room
+// twice: on the fold gate that is two posts stacked under its own previous post with nothing said in
+// between, which is the shape the policy exists to discourage, not a legitimate serialised answer.
+// The alternative — gating this arm on `input.done !== false` — was considered and rejected: it would
+// leave the loop THIS TRACE TOOK with no terminator at all, which is the failure OPE-1659 exists to end.
+// 🔴 THE FOLD GATE NOW COVERS BOTH SHAPES; THE FRESHNESS GATE STILL COVERS ONE (OPE-1664).
+// `refuseIfShouldFold` reads its spent-refusal record but no longer returns on it: the read and the
+// force branch run on a room it already refused, so a `done: false` loop shaped "refused once, then
+// forced on every later call" records an override per call and arms this latch at the bound. The
+// freshness gate is not fixed here — `tools/reply.ts` still wraps its whole block in
+// `wasStaleRefusedThisTurn`, so a loop refused once by THAT gate and then forced counts nothing on it
+// and runs to the two older step-boundary tiers. A turn of that shape usually also stacks under its
+// own post, and then the fold gate ends it; a turn where only the freshness verdict repeats has no
+// terminator from this arm. That residual gap is real and is stated here rather than claimed closed.
+// The wake itself is not consumed by any of this: an unanswered wake stays PENDING and is answerable
+// on a later turn, exactly as it is when a turn ends any other way. What is lost is this turn's
+// remaining steps, and before this change those steps were the 68-refusal spin.
+//
+// ── DURABILITY, KEYING AND FAIL DIRECTION ────────────────────────────────────────────────────────
+// An in-memory Map keyed by (eve session id, eve turn id), for the same reason
+// `step-boundary.ts`'s counter is (OPE-423): eve mints `turn.id` as `` `turn_${sequence}` ``, which
+// repeats identically across every session's Nth turn, so a turnId-only key would let one session's
+// latch end a different session's turn. The two maps are INDEPENDENT and are never joined by key
+// string — they only have to agree on the (session, turn) PAIR, which `model/turn-state.ts`
+// (`turnPairKey`) now spells once for both.
+//
+// 🔴 THE MAP IS A CACHE, NOT THE RECORD (OPE-1522). The writer runs in a tool `execute` and the
+// reader in the `step.started` model resolver, and on Vercel those two are NOT guaranteed to be the
+// same process: eve resumes an interrupted turn on a fresh instance, where this map is empty. A
+// latch armed just before such a resume was simply lost, and the turn spun to the 120-step budget —
+// the exact failure this module exists to end. So every arming also writes the durable per-turn row
+// (`model/turn-state.ts`), the reader merges the row with this map, and `reported` is carried in the
+// row too, which is what keeps one turn to one audit row across an instance change as well as within
+// one instance. Best-effort, like every property that row carries: a dropped read or write costs
+// that round-trip its durable half and the turn falls back to its caches and the step budget.
+//
+// FAIL-SOFT EVERYWHERE, and the direction is deliberate: an unreadable context, a missing turn id,
+// an unreachable store or any throw leaves the latch UNSET, so the turn keeps running and the
+// 120-step budget is still behind it. A guard that ended turns it could not identify would be far
+// worse than one that occasionally misses.
+import { currentSessionId, currentTurnId } from "../identity/binding.js";
+import { durableTurnKey, readTurnState, turnPairKey, writeTurnState } from "./turn-state.js";
+/**
+ * How many post-closeout refusals arm the latch. ONE — see the header's "why the limit is one".
+ * Exported as a named constant rather than a setting: this is not a policy dial. Every value above
+ * one buys the model more rounds of the exact behaviour the refusal text has already told it to
+ * stop, and the prod trace is 68 of them.
+ */
+export const CLOSEOUT_REFUSAL_LIMIT = 1;
+/**
+ * How many turns' latches are retained, matching `step-boundary.ts`'s `MAX_TRACKED_TURNS` and
+ * bounding the map for the same reason: nothing clears an entry at the turn's terminal decision, so
+ * the map self-bounds by evicting the least-recently-STARTED turn. An evicted latch simply un-arms
+ * a turn, which is the fail-open direction the header commits to.
+ */
+const MAX_TRACKED_CLOSEOUTS = 512;
+const latches = new Map();
+/** The map key one turn's latch is tracked under — the (session, turn) pair, spelled by
+ *  `model/turn-state.ts` so this map, the step counter's map and the durable row all address a turn
+ *  the same way. */
+function closeoutKey(sessionId, turnId) {
+    return turnPairKey(sessionId, turnId);
+}
+/**
+ * Fold a durable row's latch into the cache and answer the merged record. The count is the MAX of
+ * the two and `reported` is their OR, so neither half can rewind the other: a cold instance adopts
+ * the row, a warm one keeps a count the row has not caught up with, and a boundary already reported
+ * on either instance is never reported twice. The FIRST reason wins — the cache's, because a warm
+ * instance armed the latch itself and holds the refusal that actually ended this turn.
+ */
+function mergeLatch(key, durable) {
+    const cached = latches.get(key);
+    if (cached === undefined && durable === undefined)
+        return undefined;
+    const merged = {
+        count: Math.max(cached?.count ?? 0, durable?.count ?? 0),
+        reason: cached?.reason ?? durable?.reason ?? "",
+        reported: (cached?.reported ?? false) || (durable?.reported ?? false),
+    };
+    if (merged.reason.length === 0 || merged.count === 0)
+        return undefined;
+    remember(key, merged);
+    return merged;
+}
+/** Write one turn's latch into the cache, evicting the least-recently-STARTED turn when the map is
+ *  over-full. `Map.set` on an existing key does NOT reorder, so a refreshed latch keeps its original
+ *  position and the eviction still sheds the oldest. */
+function remember(key, record) {
+    latches.set(key, record);
+    if (latches.size > MAX_TRACKED_CLOSEOUTS) {
+        const oldest = latches.keys().next();
+        if (!oldest.done && oldest.value !== key)
+            latches.delete(oldest.value);
+    }
+}
+/**
+ * Record one post-closeout event for THIS turn and return the latch's new count (`0` when nothing
+ * could be recorded). Called from the refusal arms in `tools/reply.ts` and `tools/no_reply.ts` BEFORE
+ * they throw, so the row the refusal writes and the turn ending share one cause — and from the reply
+ * tool's repeated-override arm AFTER its post has landed, so ending the turn can never cost the
+ * message (OPE-1659, and see the header's fourth arm).
+ *
+ * `reason` is the caller's own audit reason — this module owns no vocabulary of its own, so a new
+ * arming shape needs no edit here.
+ *
+ * Never throws: a latch that cannot be written must not turn a refusal into a different error than
+ * the one the model needs to read.
+ */
+export async function noteTurnCloseoutRefusal(ctx, reason) {
+    if (typeof reason !== "string" || reason.length === 0)
+        return 0;
+    let turnId;
+    let sessionId;
+    try {
+        turnId = currentTurnId(ctx);
+        sessionId = currentSessionId(ctx);
+    }
+    catch {
+        return 0;
+    }
+    if (turnId === undefined)
+        return 0; // nothing to key a latch on — the turn runs to the step budget
+    const key = closeoutKey(sessionId, turnId);
+    // The durable row is read BEFORE the merge so an arming that happened on a previous instance is
+    // counted rather than restarted, and it is written back so THIS arming survives the next instance
+    // change. `steps` is carried through untouched: the step counter owns that field, and this call
+    // runs between two of its round-trips (OPE-1522).
+    // A sessionless turn has no durable half (OPE-1551): the bare `turn_N` row key is shared by every
+    // session's Nth turn, and a latch is the one field here that ENDS a turn — an arming leaked from
+    // run A would end run B's first round-trip with the `closed` stub. The cache still latches, which
+    // is the pre-OPE-1522 behaviour for that population.
+    const rowKey = durableTurnKey(sessionId, turnId);
+    const state = rowKey === undefined ? undefined : await readTurnState(rowKey);
+    const prior = mergeLatch(key, state?.closeout);
+    const merged = {
+        count: (prior?.count ?? 0) + 1,
+        reason: prior?.reason ?? reason,
+        reported: prior?.reported ?? false,
+    };
+    remember(key, merged);
+    // Only a read that SUCCEEDED may be written back. `state` is `undefined` when the row could not be
+    // read, and the write replaces the whole row — so writing here would put this arming's `steps: 0`
+    // over a real count. The arming then lives in the cache alone, which is the pre-OPE-1522
+    // behaviour, and the turn is still bounded by the step budget behind it.
+    if (rowKey !== undefined && state !== undefined)
+        await writeTurnState(rowKey, { ...state, closeout: merged });
+    return merged.count;
+}
+/** This turn's CACHED latch state, or `undefined` when this instance has not seen one. PURE — it
+ *  neither creates a latch nor marks one reported, so a test (or a future reader) can ask the
+ *  question without changing the answer. It reads only the in-memory cache: the durable row reaches
+ *  this map through {@link claimTurnCloseoutReport}, which is the one caller on the round-trip path
+ *  that has the row in hand. */
+export function turnCloseoutFor(sessionId, turnId) {
+    if (turnId === undefined || turnId.length === 0)
+        return undefined;
+    const rec = latches.get(closeoutKey(sessionId, turnId));
+    return rec === undefined ? undefined : { count: rec.count, reason: rec.reason };
+}
+/** Has this turn's cached latch tripped — has it drawn at least {@link CLOSEOUT_REFUSAL_LIMIT}
+ *  refusals? Cache-only, exactly like {@link turnCloseoutFor}. */
+export function turnCloseoutTripped(sessionId, turnId) {
+    const rec = turnCloseoutFor(sessionId, turnId);
+    return rec !== undefined && rec.count >= CLOSEOUT_REFUSAL_LIMIT;
+}
+/** This turn's merged latch, for the caller that PERSISTS the durable row. `undefined` when the turn
+ *  has armed nothing, which is what a writer stores as "no closeout". */
+export function turnCloseoutSnapshot(sessionId, turnId) {
+    if (turnId === undefined || turnId.length === 0)
+        return undefined;
+    return latches.get(closeoutKey(sessionId, turnId));
+}
+/**
+ * The reader `model/step-boundary.ts` calls once per model round-trip: the tripped latch's reason
+ * plus whether THIS call is the FIRST to see it. It flips the `reported` flag, which is what keeps
+ * one turn to one console line and one audit row however many round-trips the stub then serves —
+ * within an instance always, and across an instance change as far as the durable row got written.
+ * `undefined` whenever the latch is unset or has not reached the limit.
+ *
+ * `durable` is the closeout half of the turn's durable row (OPE-1522), which the caller has already
+ * read for its own step count — passing it in keeps this one store read per round-trip rather than
+ * two, and keeps this function synchronous. It is merged into the cache first, so a latch armed on a
+ * PREVIOUS instance trips here, and the flipped `reported` flag then rides back out through
+ * {@link turnCloseoutSnapshot} for the caller to persist.
+ */
+export function claimTurnCloseoutReport(sessionId, turnId, durable) {
+    if (turnId === undefined || turnId.length === 0)
+        return undefined;
+    const key = closeoutKey(sessionId, turnId);
+    const rec = mergeLatch(key, durable);
+    if (rec === undefined || rec.count < CLOSEOUT_REFUSAL_LIMIT)
+        return undefined;
+    const first = !rec.reported;
+    if (first)
+        remember(key, { count: rec.count, reason: rec.reason, reported: true });
+    return { reason: rec.reason, count: rec.count, first };
+}
+// There is deliberately NO per-turn clear. This module has no hook into eve's terminal decision —
+// the same gap `step-boundary.ts` documents for its counter — so a cache entry lives until the LRU
+// bound evicts it and the durable row until its TTL prunes it (`TURN_STATE_TTL_MS`). A latch that
+// outlives its turn reaches nobody: every reader keys on (session, turn), and eve never reissues a
+// turn id inside one session.
+/** Test seam: forget every tracked latch's CACHE entry, leaving the durable rows alone — the pair a
+ *  fresh serverless instance sees mid-turn, and so how a test stages an instance change (OPE-1522).
+ *  `deleteTurnState` drops the row itself. */
+export function _resetTurnCloseoutForTest() {
+    latches.clear();
+}
+//# sourceMappingURL=turn-closeout.js.map

package/dist/agent/model/turn-closeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-closeout.js","sourceRoot":"","sources":["../../../agent/model/turn-closeout.ts"],"names":[],"mappings":"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"}

package/dist/agent/model/turn-state.d.ts

@@ -0,0 +1,119 @@
+/**
+ * How long a turn's row outlives its last write. Generous on purpose: it bounds a TURN, and a turn
+ * may legitimately run for hours (auto-compaction at ~50% of a 1M window is what makes long turns a
+ * feature rather than a fault — see `model/step-boundary.ts`'s header). Each write refreshes the
+ * row's `created_at`, so the TTL is measured from a turn's LAST round-trip, not its first. The same
+ * six hours `access/subagent-taint.ts` bounds its markers with.
+ */
+export declare const TURN_STATE_TTL_MS: number;
+/**
+ * How long ONE store call on the per-round-trip path may take before this module gives up on it and
+ * runs cache-only (OPE-1555). Hundreds of milliseconds: the read is a primary-key lookup and the
+ * write a single upsert on a table holding a handful of short-lived rows, so a healthy store answers
+ * in single-digit milliseconds and this budget is two orders of magnitude of headroom. It is not a
+ * latency dial — it is the bound that keeps an UNHEALTHY store off the model's critical path, and
+ * every expiry degrades exactly as a failure does.
+ */
+export declare const TURN_STATE_STORE_DEADLINE_MS = 500;
+/** The durable half of one turn's closeout latch — see `model/turn-closeout.ts` for the semantics.
+ *  `reason` is the FIRST arming refusal's reason; `reported` is what keeps a turn to one audit row
+ *  across an instance change as well as within one instance. */
+export interface DurableCloseout {
+    readonly count: number;
+    readonly reason: string;
+    readonly reported: boolean;
+}
+/** One turn's durable state. `steps` is the round-trip count INCLUDING every step already served on
+ *  a previous instance; `closeout` is absent until a refusal arms the latch; `stoppedAck` is absent
+ *  until this turn has spent its one post into a stood-down conversation. */
+export interface TurnState {
+    readonly steps: number;
+    readonly closeout?: DurableCloseout;
+    readonly stoppedAck?: true;
+}
+/** The verdict for a turn whose row is genuinely NOT THERE — the first round-trip of every turn.
+ *  Distinct from `undefined`, which means the row could not be read and must not be written over. */
+export declare const EMPTY_TURN_STATE: TurnState;
+/**
+ * The (eve session id, eve turn id) pair both guards key on — THE one spelling, so the counter's
+ * map, the latch's map and the durable row can never address a turn three different ways.
+ *
+ * SESSION-scoped, not turn-id-scoped alone (OPE-423): eve mints `turn.id` as `` `turn_${sequence}` ``
+ * (harness/emission.js), which is IDENTICAL across every session's Nth turn, so two sessions warm on
+ * one instance would otherwise share one counter. Falls back to the bare `turnId` when no session is
+ * bindable (evals, sessionless schedules) — the population `currentSessionId` already answers
+ * `undefined` for.
+ */
+export declare function turnPairKey(sessionId: string | undefined, turnId: string): string;
+/**
+ * The pair a DURABLE ROW may be stored under, or `undefined` when this turn has no durable half at
+ * all (OPE-1551). The one difference from {@link turnPairKey} is the sessionless case, and it is the
+ * whole point: the bare `turn_N` fallback is safe in a per-process map and unsafe as a key in an
+ * org-wide table, where every session's Nth turn spells it the same way. See the header's section.
+ *
+ * 🔴 CALL THIS FOR THE STORE AND {@link turnPairKey} FOR THE CACHE — they are not interchangeable.
+ * A caller that keys its cache on this would stop bounding sessionless turns at all.
+ */
+export declare function durableTurnKey(sessionId: string | undefined, turnId: string): string | undefined;
+/** The scratch-table key one turn's row is stored under. Exported so a test asserts the exact row
+ *  rather than re-deriving the prefix. */
+export declare function turnStateRowKey(pair: string): string;
+/**
+ * Parse a stored row back into a {@link TurnState}. `null` — no row — answers {@link
+ * EMPTY_TURN_STATE}. Anything PRESENT but unrecognised answers `undefined`, which is the caller's
+ * signal to leave the row alone: bytes this build cannot read may be a richer row a newer build
+ * wrote during a rolling deploy, and overwriting them would throw away a live turn's real count.
+ */
+export declare function parseTurnState(raw: string | null): TurnState | undefined;
+/**
+ * This turn's durable state: {@link EMPTY_TURN_STATE} when the row is genuinely absent, and
+ * `undefined` when it COULD NOT BE READ — an unreachable store, a rejected query, bytes this build
+ * does not recognise. Never throws.
+ *
+ * 🔴 THE TWO ANSWERS ARE NOT INTERCHANGEABLE. A caller that treats `undefined` as "empty" computes a
+ * count from nothing and then overwrites a real row with it; see the header. Read the count from
+ * `?? EMPTY_TURN_STATE` if you like, but gate the WRITE on the raw `undefined`.
+ */
+export declare function readTurnState(pair: string): Promise<TurnState | undefined>;
+/**
+ * Persist this turn's state, so the NEXT instance to serve a round-trip of this turn continues the
+ * count and sees the latch. It REPLACES the row, so call it only with a record built from a read
+ * that succeeded (see {@link readTurnState}).
+ *
+ * Best-effort and never throws — a failed write degrades this turn to the pre-OPE-1522 in-memory
+ * behaviour rather than breaking a model call. That is also why every property this row carries is
+ * best-effort rather than guaranteed: one dropped write and the next instance re-reads an older
+ * count, or re-reports a crossing the previous one already recorded.
+ */
+export declare function writeTurnState(pair: string, state: TurnState): Promise<void>;
+/**
+ * Record that this turn has spent its ONE post into a stood-down conversation, durably (OPE-1551).
+ *
+ * The valve itself lives in an eve `defineState` slot (`channels/reply-signal.ts` §STOPPED), and
+ * that slot is serialized into the TURN STEP's own input and output — so a mid-turn write survives
+ * only if the turn step completes. eve runs a whole turn as ONE durable step and re-runs the
+ * interrupted one, so a turn resumed after an instance change reads the context as it stood at the
+ * turn's START and the valve reads UNSPENT. The post it already made is in the room regardless: a
+ * platform post is not rolled back. This row is the half that survives, exactly as the closeout
+ * latch's is.
+ *
+ * READ-MODIFY-WRITE over the shared row, so `steps` and `closeout` are carried through untouched;
+ * skipped entirely when the read did not complete, for the reason the header states. Never throws —
+ * a valve that cannot be recorded costs one duplicate post, which is the fail-open direction the
+ * reply path already takes.
+ */
+export declare function noteStoppedAck(pair: string): Promise<void>;
+/**
+ * Has this turn already spent its one post into a stood-down conversation, on ANY instance? `false`
+ * whenever the row is absent or could not be read — the same fail-open direction
+ * `wasStoppedAckSpentThisTurn` takes, and for the same reason: silencing the acknowledgement a human
+ * asked for is worse than one duplicate. Never throws.
+ */
+export declare function stoppedAckSpent(pair: string): Promise<boolean>;
+/** Forget one turn's durable state — the other half of `clearTurnStepCount`, and how a test stages a
+ *  turn that has never run at all. Never throws, for the same reason the writer does not.
+ *
+ *  ON THE SAME CHAIN as {@link writeTurnState} (OPE-1564), because it mutates the same row: a delete
+ *  that raced an abandoned write would leave the row RESURRECTED with the bytes the write carried. */
+export declare function deleteTurnState(pair: string): Promise<void>;
+//# sourceMappingURL=turn-state.d.ts.map

package/dist/agent/model/turn-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-state.d.ts","sourceRoot":"","sources":["../../../agent/model/turn-state.ts"],"names":[],"mappings":"AAwJA;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,QAAqB,CAAC;AAEpD;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AA8FhD;;gEAEgE;AAChE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED;;6EAE6E;AAC7E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC;CAC5B;AAED;qGACqG;AACrG,eAAO,MAAM,gBAAgB,EAAE,SAAwB,CAAC;AAExD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEhG;AAED;0CAC0C;AAC1C,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAQD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,SAAS,CAuBxE;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAgBhF;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBlF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhE;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEpE;AAED;;;;sGAIsG;AACtG,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CASjE"}