@open-everywhere/core 0.1.0

package/agent/model/turn-state.ts

@@ -0,0 +1,461 @@
+// turn-state — THE DURABLE HALF OF THE PER-TURN GUARDS (OPE-1522).
+//
+// ── THE FAILURE THIS EXISTS FOR ──────────────────────────────────────────────────────────────────
+// `model/step-boundary.ts` counted a turn's model round-trips in a module-level `Map`, and
+// `model/turn-closeout.ts` latched a turn's post-closeout refusal in a second one. On Vercel a turn
+// does not belong to one process: eve replays a turn's COMPLETED steps and re-runs the interrupted
+// one, so a turn interrupted by a timeout or a redeploy resumes on a FRESH INSTANCE — where both
+// maps are empty. A replayed step makes no model call, so the resolver is never asked about it and
+// the count is never rebuilt: the new instance starts the turn at zero.
+//
+// Measured on prod 2026-09-07 (seat session `wrun_41M1XN60YB0GQDPMXNZJ1588BA`): turn_3 ended at step
+// 121 — the soft boundary firing exactly where it should — and turn_4 ran to 198 round-trips ($2.93)
+// before the same boundary fired. 198 is not a value `classifyStepCount` can produce against a
+// budget of 120 in one process; it is two counts, 120 + 78, on two instances.
+//
+// The closeout latch has the same shape and a sharper cost: it is armed by ONE refusal
+// (`CLOSEOUT_REFUSAL_LIMIT`), so an instance change between the arming refusal and the next model
+// round-trip loses the arming outright and the turn spins to the step budget again.
+//
+// ── WHAT THIS MODULE IS ──────────────────────────────────────────────────────────────────────────
+// One durable row per (eve session id, eve turn id) holding both guards' state. The two in-memory
+// maps stay, as CACHES: a warm instance reads its own map and pays the store one small read and one
+// small write per model round-trip; a cold instance reads the row and CONTINUES the count instead of
+// restarting it. The count is therefore `max(cache, row) + 1`, never `row + 1`, so a row that
+// answers STALE costs at most a step on a warm instance.
+//
+// 🔴 A READ THAT FAILED IS NOT A ROW THAT IS ABSENT, and the write must be able to tell them apart.
+// The write is a whole-row overwrite (`putTaskResult`), so a failed read followed by a healthy write
+// would persist the count the caller computed from nothing — erasing a real 118-step row and its
+// armed latch, on exactly the cold instance this module exists for, where the cache offers no floor.
+// {@link readTurnState} therefore answers `undefined` for "could not read" and {@link
+// EMPTY_TURN_STATE} only for a row that genuinely is not there, and BOTH writers skip the write on
+// `undefined`. A turn whose row is unreadable falls back to its in-memory caches — the pre-OPE-1522
+// behaviour — instead of losing the record it could not see.
+//
+// 🔴 ONE ROW, NOT TWO. Both guards key on the same (session, turn) pair and both are read on the
+// SAME model round-trip, so a row apiece would double the store traffic on the hottest path OE has.
+// The two guards still own their own semantics — this module owns only the row.
+//
+// ── WHERE THE ROW LIVES ──────────────────────────────────────────────────────────────────────────
+// The operational store's opaque key-value scratch table (`task_result`, see its schema comment),
+// under this module's own `oe-turn-state:` prefix, exactly as the subagent taint markers, the
+// question bridge and the task-wake join use it. That table is TTL-pruned per write, org-partitioned
+// and already the store's home for short-lived per-run rows, so this needs no migration.
+//
+// THE COST, STATED: one small keyed read and one small keyed write per MODEL ROUND-TRIP, and
+// `putTaskResult` prunes that org's expired rows on each write. A model round-trip is seconds and
+// cents; these are milliseconds against a primary key on a table that holds a handful of short-lived
+// rows. The alternative — a row per guard — doubles it for nothing, which is why both guards share
+// one row.
+//
+// The org is {@link deploymentOrg}, never `resolvePartition(ctx).org`. The two are the same value
+// today (`bindFrom` stamps `org: deploymentOrg()`), but `resolvePartition` THROWS on an unbindable
+// context — which is exactly the state the dynamic-model resolver seam can be in, and where
+// `reportStepBoundary` already gives up. A partition key the writer and the reader can disagree
+// about is worse than no durability at all, so this reads the deployment constant that cannot fail.
+//
+// ── A SESSIONLESS TURN HAS NO DURABLE HALF (OPE-1551) ────────────────────────────────────────────
+// {@link turnPairKey} falls back to the bare `turn_N` when no session is bindable (evals,
+// sessionless schedules), and eve mints that id identically for every session's Nth turn. As a CACHE
+// key that collision is bounded to one process's map. As a ROW key it is not: the row is a six-hour
+// entry in one ORG-WIDE partition, so two sessionless turns would share a step count AND a closeout
+// latch — a latch armed by run A would end run B's first model round-trip with the `closed` stub.
+//
+// So the durable half is SESSION-SCOPED ONLY. {@link durableTurnKey} answers `undefined` for a
+// sessionless turn, and both call sites then skip the read and the write and run on their caches —
+// the pre-OPE-1522 behaviour, which is correct for that population rather than merely tolerable.
+// The CACHE key is unchanged: an in-process collision between two sessionless turns is the older
+// OPE-423 hazard, and narrowing the row does not widen it.
+//
+// ── FAIL-SOFT, IN ONE DIRECTION ──────────────────────────────────────────────────────────────────
+// Every entry point swallows its own failures. An unreachable store or an unparsable row degrades
+// that turn to "no durable half", which is the in-memory behaviour this module was added to
+// improve — never a turn ended on a guess. Because the writers skip a read they could not complete,
+// that degradation costs the CURRENT round-trip and leaves the stored record for the next one.
+//
+// 🔴 A `try/catch` CATCHES A REJECTION, NOT A HANG (OPE-1555). Every model round-trip awaits a read
+// and a write here, and neither store adapter sets a statement or connect timeout, so a
+// pool-exhausted or blackholed store would stall each round-trip to the 800-second function cap —
+// the swallowed-failure contract above says nothing about a call that never settles. So each store
+// call is raced against {@link TURN_STATE_STORE_DEADLINE_MS} and the expiry takes the SAME path a
+// failure takes: the read answers `undefined` (cache-only, and no write over a row it did not see)
+// and the write is abandoned. What this module guarantees is therefore bounded, not absolute: a
+// broken store costs a round-trip its durable half, never the turn.
+//
+// 🔴 THE BOUND IS PER CALL, NOT PER ROUND-TRIP, AND THE TWO DIFFER BY 5x. Count the worst case
+// honestly: `noteTurnStep` pays a read and a write; a `reply` into a stood-down conversation pays
+// `stoppedAckSpent`'s read, then `noteStoppedAck`'s read and write. That is FIVE deadline-bounded
+// calls, so about 2.5 s of added wall clock on such a round-trip against a store sitting just past
+// the deadline — not 500 ms. It is still a bound, and it is still far from the 800 s function cap,
+// which is what this deadline exists to keep the turn away from.
+//
+// AND IT COVERS THIS MODULE'S CALLS ONLY. `channels/engagement.ts`'s `isThreadStopped`, on the same
+// reply path, has no deadline at all. That is another module's to bound, and claiming otherwise here
+// would be exactly the kind of overclaim this section replaced.
+//
+// 🔴 THE RESIDUAL, STATED: this is read-modify-write with NO compare-and-set, because the shared
+// scratch table offers none. A write can therefore land on top of a row it never saw — ACROSS
+// PROCESSES: the resolver on instance A reads the row, a tool on instance B arms the latch and
+// writes, and A then writes a row built before B's arming.
+//
+// WITHIN ONE PROCESS the row is safe. eve serialises resolver → model → tool, so two writers cannot
+// interleave in program order, and since OPE-1564 {@link chainRowCall} keeps an ABANDONED write
+// from overtaking its successor as well (see the section below).
+//
+// WHAT THE CROSS-PROCESS RESIDUAL LOSES, AND THE FAIL DIRECTION OF EACH FIELD:
+//   • `steps` rewinds, so the turn counts on from a lower floor — the pre-OPE-1522 behaviour, and the
+//     step budget is still behind it;
+//   • `closeout` loses an arming, so the turn falls back to the step budget rather than ending here —
+//     the pre-OPE-1520 behaviour, and never a turn ended wrongly;
+//   • `stoppedAck` reads UNSPENT, so a resumed turn gets ONE more post into a conversation the person
+//     asked the seat to leave. That is the sharpest of the three, and it is the same one-duplicate
+//     cost the whole stand-down path already fails open with (`tools/reply.ts`), never a lost answer.
+//
+// 🔴 THE IN-PROCESS SAFETY OF `stoppedAck` COMES FROM THE FRESH READ, NOT FROM A CACHE. The latch
+// has an in-memory cache the resolver's snapshot reads; this field has none. What keeps it correct is
+// that every writer spreads the row it just read, so no writer names a subset of the fields and drops
+// the rest. A future writer that names fields instead of spreading breaks this silently.
+//
+// ── THE IN-FLIGHT HALF IS CLOSED (OPE-1564) ──────────────────────────────────────────────────────
+// {@link chainRowCall} orders every store call this module makes to ONE pair's row — the READS as
+// well as the writes and the delete. A call is ISSUED only after its predecessor has SETTLED, so the
+// store sees this process's calls in program order and last-write-wins gives the LATER write. An
+// abandoned write can no longer overtake its successor, which is what un-spent `stoppedAck` and
+// rewound `steps` on a slow store.
+//
+// 🔴 THE READ HAD TO JOIN THE CHAIN, OR THE LOSS ONLY MOVES. Every writer here is read-modify-write
+// over a whole-row overwrite. Order the writes alone and a FAST read can still see the row as it
+// stood before a SLOW predecessor lands; its writer then spreads those stale bytes into a new row,
+// and the chain lands that row last — deterministically dropping the field the reader never saw.
+// `stoppedAck` is the field that costs, because it is the one with no in-memory cache to repair it.
+// {@link chainRowCall} spells the interleaving out.
+//
+// The CALLER still pays only the deadline: the deadline races the queued call, so a caller whose
+// predecessor is hung waits {@link TURN_STATE_STORE_DEADLINE_MS} and no longer. What it gives up is
+// stated plainly — while a predecessor hangs, its successors stay QUEUED and never reach the store,
+// so a broken store now costs the pair its later calls as well as its abandoned one. That is the
+// same fail-soft direction the rest of this module takes: a read that did not complete answers
+// `undefined`, both writers then skip, and the turn falls back to its in-memory caches.
+//
+// THE CROSS-PROCESS HALF IS UNCHANGED and still open: the resolver on instance A reads the row,
+// instance B arms the latch and writes, and A then writes a row built before B's arming. Closing that
+// needs a CAS primitive the shared scratch table does not offer.
+
+import { deploymentOrg } from "../identity/deployment-identity.js";
+import { getOperationalStore } from "../operational/provider.js";
+
+/** Key prefix for this module's rows in the shared scratch table — namespaced so a turn-state row
+ *  can never collide with the taint markers, the question bridge or the task-wake join that share
+ *  it. */
+const TURN_STATE_PREFIX = "oe-turn-state:";
+
+/**
+ * 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 const TURN_STATE_TTL_MS = 6 * 60 * 60 * 1000;
+
+/**
+ * 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 const TURN_STATE_STORE_DEADLINE_MS = 500;
+
+/**
+ * Race one store call against {@link TURN_STATE_STORE_DEADLINE_MS} and answer `fallback` when the
+ * deadline wins. The abandoned call keeps running — nothing here can cancel a driver's in-flight
+ * query — so its eventual rejection is swallowed rather than left to surface as an unhandled
+ * rejection on a process that has already moved on.
+ */
+/** The answer a store call gives when the deadline beat it. Its own value, distinct from every
+ *  answer the store itself can give — `null` is a row that is genuinely absent, and conflating the
+ *  two is the read/write hazard this module's header opens with. */
+const TIMED_OUT: unique symbol = Symbol("turn-state-store-deadline");
+
+async function withStoreDeadline<T>(work: Promise<T>, fallback: T): Promise<T> {
+  work.catch(() => undefined); // the loser of the race must not crash the process later
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      work,
+      // 🔴 NOT `unref`ed. The deadline is the ONLY thing that can settle this race when the store
+      // call never does, so an unref'd timer lets the event loop drain and leaves the caller's await
+      // pending forever — the exact stall this deadline exists to end. `clearTimeout` in the
+      // `finally` is what keeps a healthy call from holding the loop open, and it runs on every path.
+      new Promise<T>((resolve) => {
+        timer = setTimeout(() => resolve(fallback), TURN_STATE_STORE_DEADLINE_MS);
+      }),
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+/**
+ * ONE PENDING CALL CHAIN PER PAIR — the tail of every store call this process has issued for that
+ * row, or nothing when the row has none outstanding.
+ *
+ * 🔴 KEYED BY PAIR, NEVER GLOBAL. A single chain would make every turn on the instance wait behind
+ * one hung store call, and turns of different pairs cannot overwrite each other's rows at all.
+ */
+const rowCalls = new Map<string, Promise<void>>();
+
+/** The empty tail every pair's first call chains onto. */
+const NO_PENDING_CALL: Promise<void> = Promise.resolve();
+
+/** The answer a chained call gives when it rejected. Its own value, distinct from every answer the
+ *  store itself can give, for the same reason {@link TIMED_OUT} is. */
+const CHAIN_FAILED: unique symbol = Symbol("turn-state-chain-failed");
+
+/**
+ * Issue one store call on `pair`'s row AFTER every call this process already issued for it has
+ * SETTLED (OPE-1564), and answer a promise that never rejects.
+ *
+ * 🔴 THE ORDER IS WHAT THIS BUYS. `putTaskResult` is an unconditional last-write-wins upsert
+ * (`agent/operational/postgres.ts`), so two calls in flight at once let the SLOWER one win — and the
+ * slow one is exactly the write {@link withStoreDeadline} already gave up on. Chaining on SETTLEMENT
+ * rather than on issue is the load-bearing half: two calls issued back to back still race inside the
+ * driver's pool, so "issued first" does not mean "landed first".
+ *
+ * 🔴 THE READ IS ON THIS CHAIN TOO, AND THAT IS NOT TIDINESS. Ordering the WRITES alone moves the
+ * loss instead of closing it. Every writer here is read-modify-write over a whole-row overwrite, so a
+ * read that beat a slow predecessor would hand its writer a row built from PRE-predecessor bytes —
+ * and the chain would then land that stale-built row LAST, deterministically. Worked through:
+ * `noteStoppedAck` writes `{steps:5, stoppedAck:true}` and is abandoned at the deadline; the next
+ * round-trip reads fast, sees `{steps:5}`, and `noteTurnStep` spreads what it read into
+ * `{steps:6}` — no `stoppedAck` (`model/step-boundary.ts`). `steps` and `closeout` survive that on a
+ * warm instance because `bump` floors the count from its cache; `stoppedAck` has no cache, so the
+ * valve would read UNSPENT. Chaining the read means a reader either sees the predecessor's bytes or
+ * loses its own deadline race and answers `undefined`, and both writers skip a write over a row they
+ * did not see.
+ *
+ * The caller does NOT wait for the chain: every entry point races this promise against the deadline
+ * exactly as it raced the bare store call. A queued call whose predecessor hangs is therefore never
+ * issued, which is the fail-soft direction — no write over a newer row, and no row read as absent.
+ *
+ * The map entry is dropped once this link is the tail AND has settled, so an instance serving many
+ * turns holds one promise per LIVE pair rather than one per turn it ever saw. A pair whose store call
+ * never settles keeps its entry, which is the same broken-store cost the rest of this module pays.
+ */
+function chainRowCall<T>(pair: string, issue: () => Promise<T>): Promise<T | typeof CHAIN_FAILED> {
+  const pending = rowCalls.get(pair) ?? NO_PENDING_CALL;
+  // Never rejects: a link that failed must not stop its successor from being issued, and must not
+  // surface as an unhandled rejection either.
+  const call: Promise<T | typeof CHAIN_FAILED> = pending.then(issue).then(
+    (value) => value,
+    () => CHAIN_FAILED,
+  );
+  const tail: Promise<void> = call.then(() => undefined);
+  rowCalls.set(pair, tail);
+  void tail.then(() => {
+    if (rowCalls.get(pair) === tail) rowCalls.delete(pair);
+  });
+  return call;
+}
+
+/** 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 const EMPTY_TURN_STATE: TurnState = { steps: 0 };
+
+/**
+ * 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 function turnPairKey(sessionId: string | undefined, turnId: string): string {
+  return sessionId !== undefined ? `${sessionId}:${turnId}` : turnId;
+}
+
+/**
+ * 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 function durableTurnKey(sessionId: string | undefined, turnId: string): string | undefined {
+  return sessionId === undefined || sessionId.length === 0 ? undefined : turnPairKey(sessionId, turnId);
+}
+
+/** 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 function turnStateRowKey(pair: string): string {
+  return `${TURN_STATE_PREFIX}${pair}`;
+}
+
+/** Read one field off an unknown parsed row, or `undefined` when it is not the expected type. */
+function numberField(row: Record<string, unknown>, name: string): number | undefined {
+  const value = row[name];
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.floor(value) : undefined;
+}
+
+/**
+ * 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 function parseTurnState(raw: string | null): TurnState | undefined {
+  if (raw === null) return EMPTY_TURN_STATE;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined;
+  const row = parsed as Record<string, unknown>;
+  // `steps` is written on EVERY row this module stores, so its absence means these are not this
+  // module's bytes — treat them as unreadable rather than as a turn that has taken no steps.
+  const steps = numberField(row, "steps");
+  if (steps === undefined) return undefined;
+  // Only ever written as `true`, so anything else — absent, `false`, a string — reads as "not spent".
+  const stoppedAck = row.stoppedAck === true ? ({ stoppedAck: true } as const) : undefined;
+  const closeoutRaw = row.closeout;
+  if (typeof closeoutRaw !== "object" || closeoutRaw === null) return { steps, ...stoppedAck };
+  const closeout = closeoutRaw as Record<string, unknown>;
+  const count = numberField(closeout, "count");
+  const reason = closeout.reason;
+  if (count === undefined || count === 0 || typeof reason !== "string" || reason.length === 0) return { steps, ...stoppedAck };
+  return { steps, ...stoppedAck, closeout: { count, reason, reported: closeout.reported === true } };
+}
+
+/**
+ * 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 async function readTurnState(pair: string): Promise<TurnState | undefined> {
+  try {
+    const raw = await withStoreDeadline<string | null | typeof TIMED_OUT | typeof CHAIN_FAILED>(
+      // ON THE PAIR'S CALL CHAIN (OPE-1564), so this cannot read bytes an abandoned predecessor is
+      // about to replace — see {@link chainRowCall} for the row that interleaving would otherwise
+      // build and land last.
+      chainRowCall(pair, () => getOperationalStore().getTaskResult(deploymentOrg(), turnStateRowKey(pair))),
+      TIMED_OUT,
+    );
+    // A read that ran out of time, or that the chain could not issue, is a read that did not
+    // complete, so it takes the `undefined` path and nothing is written over the row it never saw
+    // (OPE-1555).
+    return raw === TIMED_OUT || raw === CHAIN_FAILED ? undefined : parseTurnState(raw);
+  } catch {
+    return 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 async function writeTurnState(pair: string, state: TurnState): Promise<void> {
+  try {
+    // Stamped when the CALLER asked, not when the chain issues the call: this is the row's
+    // `created_at` and therefore its TTL anchor, and a queued write must not read as fresher than the
+    // state it holds. Inside the `try` with everything else — this function never throws.
+    const at = new Date().toISOString();
+    const body = JSON.stringify(state);
+    // Deadline-bounded like the read (OPE-1555): a write nobody is waiting on must not be the thing
+    // that holds a model round-trip open. An abandoned write is still IN FLIGHT — nothing here can
+    // cancel a driver's query — so {@link chainRowCall} keeps the NEXT write behind it rather
+    // than letting the two race (OPE-1564). The deadline still bounds what this caller awaits.
+    await withStoreDeadline(
+      chainRowCall(pair, () =>
+        getOperationalStore().putTaskResult(deploymentOrg(), turnStateRowKey(pair), body, at, TURN_STATE_TTL_MS),
+      ),
+      undefined,
+    );
+  } catch {
+    /* the in-memory caches still bound this turn on THIS instance — see the header */
+  }
+}
+
+/**
+ * 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 async function noteStoppedAck(pair: string): Promise<void> {
+  const state = await readTurnState(pair);
+  if (state === undefined) return;
+  await writeTurnState(pair, { ...state, stoppedAck: true });
+}
+
+/**
+ * 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 async function stoppedAckSpent(pair: string): Promise<boolean> {
+  return (await readTurnState(pair))?.stoppedAck === true;
+}
+
+/** 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 async function deleteTurnState(pair: string): Promise<void> {
+  try {
+    await withStoreDeadline(
+      chainRowCall(pair, () => getOperationalStore().deleteTaskResult(deploymentOrg(), turnStateRowKey(pair))),
+      undefined,
+    );
+  } catch {
+    /* a clear that cannot reach the store must not break the caller that asked for it */
+  }
+}

package/agent/model/vision.ts

@@ -0,0 +1,112 @@
+// The image-describer seam (multimodal reduction-to-text). GLM-5.2 — OE's primary — is
+// text-only, and more fundamentally, model context is text: anything non-text is reduced to
+// text (or disk) BEFORE it enters context (memory mcp-context-and-code-mode.md). A vision call
+// is exactly that reduction stage — image bytes → a text description + any OCR — so it rides a
+// registered seam, EXACTLY like the dream cycle's judge (memory/dream/judge.ts): core owns the
+// interface + registry; the vendor transport (image bytes → a multimodal `generateText` call on
+// a gateway model) lives behind this seam in @open-everywhere/adapters
+// (agent/model/gateway-vision.ts). Core never imports a vendor SDK; a self-host swaps the one
+// adapter file to point at a local vLLM Qwen3-VL and nothing else changes.
+//
+// FAIL-CLOSED CONSUMER: tools/describe_image.ts calls getImageDescriber() and, on ANY
+// error OR a missing describer, reports "image could not be described" rather than guessing —
+// a hallucinated screenshot is worse than an admitted blind spot (docs Part B.4). That
+// fail-closed contract is what carries the ZERO-DATA-RETENTION posture, and it is deliberately
+// stated as a property of THIS seam rather than of any one transport's call options: whatever
+// makes a non-ZDR route unavailable — the gateway refusing to route it under a "ZDR models
+// only" org policy (the reference deployment's posture since OPE-323), or a transport that
+// chooses to pin ZDR per call — arrives here as a thrown describe(), and the tool turns it into
+// the same fail-closed message. Tommy's D6 call: for image bytes, failing the description is
+// safer than leaking them. Core states the requirement; where it is enforced is the
+// deployment's choice, not this file's.
+
+/** One image to describe — raw bytes + their media type, plus an optional focus hint. */
+export interface ImageDescribeRequest {
+  /** The image bytes (already fetched host-side by the tool — never a URL the describer fetches). */
+  readonly bytes: Uint8Array;
+  /** IANA media type, e.g. "image/png" — steers the provider's decode. */
+  readonly mimeType: string;
+  /** Optional caller hint (e.g. the filename or "what does this dashboard show?"). */
+  readonly hint?: string;
+}
+
+/**
+ * WHAT ONE VISION CALL COST, as the transport observed it (OPE-403) — the reason the vision plane
+ * is not a hole in the spend plane.
+ *
+ * 🔴 WHY THE TRANSPORT REPORTS THIS RATHER THAN STAMPING IT. Every OTHER model call OE makes is
+ * costed from eve's `step.completed` event, whose model id comes from the per-session stamp
+ * (model/model-stamp.ts) that model/routing.ts leaves immediately before the call. A vision call
+ * cannot use that channel twice over: it emits no step event (it is a plain `generateText` inside
+ * a tool's `execute`), and stamping it would CORRUPT the next real step's attribution, because the
+ * vision call runs BETWEEN two steps of the same session and the stamp slot holds only the last
+ * write. So the transport hands its own accounting back with the result, and the tool — which
+ * holds the calling turn's context, and therefore the org/surface/principal/routine/lineage —
+ * writes the attributed rows through hooks/spend.ts's `recordModelCall`.
+ *
+ * OPTIONAL, on purpose: a transport that cannot observe its usage (a local model, a stub) still
+ * satisfies the seam. describe_image warns rather than failing, because a describable image is
+ * worth more than a bookkeeping row — but the warning is what stops the hole being silent again.
+ */
+export interface ImageDescribeUsage {
+  /** The model id that actually ran, as the transport asked for it — the row's `model` column. */
+  readonly model: string;
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+  readonly cacheReadTokens?: number;
+  readonly cacheWriteTokens?: number;
+  /** REASONING tokens this call spent (OPE-1611), when the provider reported them under
+   *  `usage.outputTokenDetails.reasoningTokens`. Absent = unreported, never a zero it did not
+   *  claim. Attribution only — no rate prices it. */
+  readonly reasoningTokens?: number;
+  /** The gateway's own measured cost for this call, USD (`providerMetadata.gateway.cost`). */
+  readonly costUsd?: number;
+  /** The gateway's per-call trace id (`providerMetadata.gateway.generationId`) — the join key
+   *  between this row and the gateway's billing record. */
+  readonly generationId?: string;
+}
+
+/** The reduction result: a prose description, plus any transcribed on-image text (OCR). */
+export interface ImageDescribeResult {
+  /** A plain-text description of what the image shows (capped by the caller). */
+  readonly description: string;
+  /** Verbatim on-image text, when the image is text-dense (a screenshot/dashboard). Omitted
+   *  when there's no meaningful text. UNTRUSTED like the description — the tool wraps both. */
+  readonly ocrText?: string;
+  /** What the call cost (OPE-403) — see {@link ImageDescribeUsage} for why it rides the RESULT
+   *  rather than the model stamp. Absent ⇒ describe_image warns that this vision spend is
+   *  unattributed, which is the condition OPE-403 existed to end. */
+  readonly usage?: ImageDescribeUsage;
+}
+
+/**
+ * The image describer the `describe_image` tool calls. A single method; a throw means "could
+ * not describe" (fetch/decode/vision-call errors, and a gateway that will not route the model
+ * under a ZDR-only policy, all propagate as a throw — the tool's fail-closed contract). Mirrors
+ * DreamJudge's transport-behind-a-registry shape.
+ */
+export interface ImageDescriber {
+  describe(req: ImageDescribeRequest): Promise<ImageDescribeResult>;
+}
+
+// --- registry (app wires a transport at boot; absent → the tool reports "can't see images") --
+
+let registered: ImageDescriber | null = null;
+
+/** Register the deploy's vision transport (agent.ts, at boot). A later call replaces it.
+ *  Without this the `describe_image` tool has no backend and fails closed on every call —
+ *  registration IS the "the agent can see images" opt-in, same discipline as the dream judge. */
+export function registerImageDescriber(describer: ImageDescriber): void {
+  registered = describer;
+}
+
+/** The registered describer, or null when none is wired (→ the tool reports it can't see the
+ *  image, never guesses). */
+export function getImageDescriber(): ImageDescriber | null {
+  return registered;
+}
+
+/** Test seam: clear the registered describer so a test starts from the unregistered state. */
+export function _resetImageDescriberForTest(): void {
+  registered = null;
+}