@open-everywhere/core 0.1.0

package/agent/channels/reply-fold.ts

@@ -0,0 +1,517 @@
+// reply-fold — THE SHOULD-BE-EDIT POLICY (Claude Tag steal, OPE-837).
+//
+// THE OBSERVATION. Tag's harness refuses a post that would land immediately after the agent's OWN
+// previous post with no message from the room in between, and directs the agent to fold the new text
+// into that previous message instead. Observed live 2026-08-19: Tag complied and folded. The room
+// then reads ONE message that says the whole thing, rather than a stack the agent built one line at
+// a time.
+//
+// 🔴 OE DECIDES IT HOST-SIDE, DETERMINISTICALLY. Tag runs a model-judged reviewer over the outgoing
+// post. We do not adopt that (it is a separate, deferred question): this module reads a record the
+// host already keeps and answers yes or no. The verdict is therefore reproducible, testable without a
+// model, and cheap — one store read on the reply path.
+//
+// THE EVIDENCE IS THE STANDING-SEAT RING, and deliberately nothing else. `channels/session-tail.ts`
+// records, per generation and per ROOM, the wake messages the deployment delivered and the posts the
+// seat made, in one interleaved timeline. "Our own last post, nothing said since" is therefore a
+// single question about the last row of that timeline. Inventing a second source of truth — a
+// platform history fetch, a per-turn counter — would be a second opinion that can disagree with the
+// ring, and the ring is what `edit_reply` and the rotation already read.
+//
+// WHAT THE REFUSAL DOES, AND WHAT IT MUST NOT DO. It refuses BEFORE the post choke point, so no byte
+// leaves, the `postOnce` dedupe key is never claimed, and the turn's reply obligation is not
+// discharged — the model can still post, and the `edit_reply` it is steered to is itself a terminal
+// verb (channels/turn-terminal-actions.ts), so a turn that folds is not nudged for a further answer.
+// The refusal copy names the message id to edit, because the model needs it, and it is the model's
+// own post.
+//
+// 🔴 THE COPY MUST WARN THAT AN EDIT REPLACES. `edit_reply` rewrites a message outright. A model that
+// folds badly can therefore DELETE what the previous message said. That is the one harm this policy
+// can cause, so the refusal states the rule the model must follow: write the whole message, old
+// content included.
+//
+// 🔴 A FOLD TARGET MUST ANSWER THE SAME WAKE (OPE-905, and it is narrowing 5 below). The ring's last
+// row being our own post is not enough on its own. A burst puts two wakes in one room, and BOTH are
+// recorded at ingress BEFORE either is answered. The seat answers wake A (a post row), and on its
+// answer to wake B the ring's last row is that wake-A post. The old verdict then asked the model to
+// merge the answer to question 2 into the message that answers question 1.
+//
+// THE MEASUREMENT SAYS THE MODEL WAS RIGHT TO DECLINE. Across deploy #106's two live passes the seat
+// folded 17 of 17 SAME-wake refusals and 0 of 9 CROSS-wake ones, on the three surfaces that window
+// carried — slack, discord and teams; they are not the whole editable set, see narrowing 1. The
+// per-surface asymmetry the ticket first reported was a confound — every Discord and Teams verdict in
+// the window happened to be cross-wake. One mechanical fault still sits under a cross-wake verdict:
+// the edit marks wake A replied while wake B stays unmarked, which the per-wake accounting pass
+// (channels/wake-accounting.ts) then counts as a dropped wake. The other — a refusal copy that named
+// `message_id` but not the `wake` argument a wake-addressed `edit_reply` also takes — is closed:
+// {@link foldIntoEditRefusalMessage} names both (OPE-1528).
+//
+// Tommy's ratified precondition — "no intervening HUMAN message" — is what this restores. The human
+// message that woke B DID arrive before our post, and is still unanswered; reading only the ring's
+// last row could not see it.
+//
+// THE FIVE NARROWINGS, each of which turns the policy OFF rather than on:
+//   1. ONLY WHERE AN EDIT WOULD WORK. The previous post's surface must have an `editMessage` arm
+//      (channels/post-arms.ts), and the caller must hold an editable ADDRESS for it. SIX arms carry
+//      the member today — slack, discord, teams, github, linear, notion — so this policy is NOT a
+//      chat-surface one: it can refuse on a GitHub thread as readily as on a Teams channel. The
+//      address is what turns it off, and it does so per ORIGIN, not per platform: a Linear MENTION
+//      reply is an Agent Activity with no update mutation, and a Notion origin carrying no
+//      workspace/page has no composite key, so `replyEditLocus` / `unifiedEditLocus` answer `null`
+//      and the post proceeds. Refusing there would leave the model no way to say the thing at all.
+//   2. ONLY A POST THE LEDGER STILL ACCEPTS. The ring says what was said; the OWN-POST LEDGER
+//      (channels/own-post-ledger.ts) is what `edit_reply` actually fences on, so the fold target is
+//      confirmed against it before the model is sent there. Without that confirmation a ring row
+//      whose ledger write was lost — the write is best-effort by design — would produce a refusal
+//      steering at an id `edit_reply` then refuses as `not-own-post`. The ledger read runs LAST, only
+//      once the pure verdict already says "fold", so the happy path pays nothing for it.
+//   3. ONLY A RECENT POST. The pure verdict also bounds the target by {@link OWN_POST_TTL_MS}. That
+//      is the same window the ledger enforces, kept here as well so the decision is complete and
+//      testable without a store.
+//   4. ONLY WHERE THE ROOM IS KNOWN. No seeded tail window (a delegated worker, a task session, a
+//      routine fire, a native seat), no `container`, or an unreadable store — all answer "no fold".
+//   5. ONLY A POST THAT PROVABLY ANSWERED THIS WAKE (OPE-905, above), and 🔴 ONLY A TARGET WHOSE OWN
+//      WAKE IS RECORDED (OPE-1528). The target's id must be KNOWN; the caller's, when it has one,
+//      must MATCH. A fold needs positive evidence, and a target row with no wake carries none — the
+//      old shape read that silence as permission, which is the one door left open into the very
+//      cross-wake fold this narrowing exists to stop.
+//
+//      🔴 SAY THE CONSEQUENCE PLAINLY: THIS TURNS THE POLICY OFF FOR A PER-SURFACE SEAT. The
+//      per-surface `reply` records its posts with no wake (tools/reply.ts passes none to
+//      `replyAuditFor`), so on a seat that mounts it every ring row is a target with no wake and the
+//      verdict is always "no fold". A standing container-supervisor on a non-unified domain is such
+//      a seat, and it DID draw fold verdicts before this change. It no longer does.
+//
+//      That is a deliberate cost, not an oversight, and the deploy-#106 measurement above does NOT
+//      justify it — that split was computed where BOTH ids were known, so a wake-less seat was never
+//      in its population. The honest reason is narrower: on such a ring the host cannot tell a
+//      same-wake fold (which the model accepted 17 of 17 times) from a cross-wake one (which it
+//      declined 9 of 9 times), and OPE-905 already ruled the cross-wake fold wrong. Refusing on a
+//      coin-flip is worse than not refusing, and the policy's whole enforcement is a nudge. The way
+//      back is to give that variant a wake id, not to soften this rule — see tools/reply.ts.
+//
+// A BOT MESSAGE CLEARS THE FOLD, and this is narrower than the ratified precondition on purpose. The
+// precondition Tommy ratified says "no intervening HUMAN message". The ring records every delivered
+// wake, human or bot. A bot message that woke the seat sits between the two posts IN THE ROOM, so the
+// new post is no longer adjacent to our own and an edit would land above somebody else's message.
+// Counting it keeps the policy about ADJACENCY, which is what makes a fold read correctly, and it
+// only ever refuses less.
+//
+// THE VALVE IS THE SAME ONE THE FRESHNESS GATE USES (channels/reply-freshness.ts): the gate refuses
+// at most ONCE per turn per room. A model that re-sends the same call posts. So a genuinely new
+// message — a scheduled report, an unrelated second answer — costs one step and always gets through,
+// and refuse → refuse can never cycle. On the unified variant `force: true` overrides the verdict
+// outright, exactly as it does for staleness, and the FIRST override of a room writes its own row.
+//
+// 🔴 THE OVERRIDE IS RECORDED ONCE PER TURN PER ROOM (OPE-1659), and that changes the TRAIL, never
+// what lands. Until then the force branch read the verdict and wrote a row on EVERY call, so one live
+// turn wrote 101 `should-be-edit-forced` rows for one room while the model read back an identical
+// success note each time. Now the first override writes the row and later ones write none, and past
+// `FORCED_OVERRIDE_TURN_LIMIT` the reply tool ends the TURN through the closeout latch
+// (model/turn-closeout.ts). Every one of those calls still posts — channels/reply-signal.ts §FORCED
+// carries the measurement, and states why ending a turn is not blocking a message.
+//
+// 🔴 THIS POLICY DISCOURAGES A DOUBLE POST, IT NEVER BLOCKS ONE (Tommy's ruling, 2026-09-03: "we
+// should never be hard-blocking this, it's okay for the model to double-post, just discouraged").
+// The two valves above are THIS policy's whole enforcement: it adds no ceiling on posts, no arm and
+// no approval gate. The model's own judgement decides, and the refusal copy's job is to make the
+// cost of a second post legible rather than to stop it.
+//
+// THE SIBLING POLICY HOLDS THE SAME SHAPE. The same-turn `done` teeth (channels/reply-signal.ts
+// §DONE-VALVE, applied in tools/reply.ts) refuse a wake already answered with `done: true` — once
+// per turn per wake, `force: true` honoured, the same valve sentence (OPE-1452). It was a hard
+// refusal reading no flag until then, and it was the last DUPLICATE-POST gate on this path that
+// was. A multi-part answer still passes `done: false` and draws no refusal at all.
+//
+// THREE MECHANISMS STILL STOP A SECOND POST OUTRIGHT, and none is this one — a reader auditing the
+// ruling against the code must not read the paragraph above as a claim about them:
+//   • the same-turn `done` teeth on the ONE route where the first answer closed the conversation: a
+//     Linear mention reply is a `response` Agent Activity and ends its agent session (OPE-869), so
+//     `terminalPostClosesConversation` (channels/unified-reply.ts) keeps the wall there. A valve is
+//     for a post the host COULD make and would rather not; that post cannot be made at all.
+//   • the wake fence's own `answered` arm (channels/unified-window.ts): a wake an EARLIER turn
+//     answered. It throws every time and reads no `force` either. It IS about a repeat answer, and
+//     the ruling does not reach it: the arm refuses on the answered mark of a resolved row, and the
+//     conversation re-opens by itself on the next message there, under a new wake id.
+//   • the outbound post-once claim (operational/post-once.ts): byte-identical text on the same wake
+//     inside its TTL is put in the room once. It fences the BYTES, not the decision, and it does not
+//     refuse at all — it returns the skip sentinel and the tool still answers `posted: true`. It
+//     never fires on the valve above: this policy refuses BEFORE the choke point, so the refused
+//     text never claimed a key (proven live: reply-fold-test.ts §6/DEDUPE).
+//
+// Three further refusals on this path throw every time and read no `force` — `declined-this-turn`,
+// `task-wake-unread` and `delegation-pending` — and none of them judges a duplicate. See
+// channels/reply-signal.ts §DONE-VALVE for why the ruling does not reach them.
+//
+// FAIL-OPEN IN EVERY UNKNOWN DIRECTION, the same direction reply-freshness.ts holds: a store error,
+// a missing container, an unparseable timestamp and an absent message id all post the reply. A lost
+// message is a product failure; a message that should have been an edit is a stylistic one.
+
+import { defineState } from "eve/context";
+import { postArm } from "./post-arms.js";
+import { isOwnPost, OWN_POST_TTL_MS, type OwnPostLedgerDeps, type OwnPostLocus } from "./own-post-ledger.js";
+import { auditReplyForced, auditReplyRefused, type ReplyAudit } from "./reply-post.js";
+import { noteForcedOverrideThisTurn, secondMessageValve } from "./reply-signal.js";
+import type { SessionTailEntry } from "./session-tail.js";
+import type { TailWindow } from "./session-tail-record.js";
+
+/** The audit reason a reply refused by this policy carries, on its own `reply.refused` row — so a
+ *  should-be-edit refusal is countable apart from a staleness refusal or a fence refusal. */
+export const REPLY_FOLD_REFUSAL_REASON = "should-be-edit";
+
+/** The audit reason a FORCED send carries on its own `reply.forced` row, when the model overrode a
+ *  real fold verdict. The pair (refusals, overrides) is what says whether the policy helps. */
+export const REPLY_FOLD_FORCED_AUDIT_REASON = "should-be-edit-forced";
+
+/** The message this post should fold into: our own last post in this room, and where it lives. */
+export interface FoldTarget {
+  readonly messageId: string;
+  readonly platform: string;
+}
+
+/** The ring slice this policy reads. Its own interface, so a test drives it with a small fake and the
+ *  dependency direction stays one-way (the same shape reply-freshness.ts uses for its store). */
+export interface ReplyFoldStore {
+  readSessionTail(org: string, surfaceKey: string, token: string): Promise<SessionTailEntry[]>;
+}
+
+/** Can this surface edit one of its own posts? The post arm's `editMessage` member IS the honest
+ *  answer, which is the same predicate `edit_reply` itself refuses on (tools/edit_reply.ts). */
+export function platformCanEdit(platform: string): boolean {
+  return typeof postArm(platform)?.editMessage === "function";
+}
+
+/**
+ * THE WHOLE DECISION, PURE. Given one generation's ring, should a post into `container` fold into a
+ * message already there — and which one?
+ *
+ * The ring is sorted by time before the last row is read. That sort is NOT redundant with the store's
+ * ordering, for the same reason `buildTail` states: one ring takes writes from two processes (the
+ * ingress route records a delivered wake, the workflow process records a post), so insertion order
+ * can differ from real time by the width of that race. The tie-break keeps `wake` LAST when a wake
+ * and a post share a timestamp, which is the fail-open direction — a tie answers "somebody spoke".
+ *
+ * Every exit below is a NO-FOLD, and each is one of the narrowings in the header.
+ */
+export function foldTargetInTail(
+  ring: readonly SessionTailEntry[],
+  input: {
+    /** The room this post is going into. Absent ⇒ the rooms cannot be told apart ⇒ no fold. */
+    readonly container: string | undefined;
+    /** The surface this post is going to. A fold target on another surface is another room. */
+    readonly platform: string;
+    /**
+     * The wake this post ANSWERS (OPE-905). A candidate row that answered a DIFFERENT wake is not a
+     * fold target. `undefined` — the per-surface `reply`, which holds no wake id — compares nothing
+     * and keeps the pre-OPE-905 verdict. It is the TARGET's wake that must be known (OPE-1528), and
+     * a per-surface seat's own posts record none, so such a seat draws no verdict either way.
+     */
+    readonly answeringWake?: string | undefined;
+    /** Injected for the test; the live callers take {@link platformCanEdit}. */
+    readonly canEdit?: (platform: string) => boolean;
+    readonly nowMs?: number;
+    readonly windowMs?: number;
+  },
+): FoldTarget | null {
+  if (!input.container) return null;
+  const rows = ring.filter((e) => e.container === input.container);
+  if (rows.length === 0) return null;
+  const ordered = [...rows].sort((a, b) => Date.parse(a.at) - Date.parse(b.at) || a.kind.localeCompare(b.kind));
+  const last = ordered[ordered.length - 1];
+  // The room said something after our post ⇒ this post is not adjacent to ours ⇒ nothing to fold.
+  if (last.kind !== "post" || last.from !== "self") return null;
+  // A post whose platform id was never recorded cannot be named to `edit_reply`, so there is no
+  // instruction to give and the refusal would be a wall rather than a redirect.
+  if (!last.id) return null;
+  // 🔴 OPE-1528 — A TARGET WHOSE OWN WAKE IS UNKNOWN IS NOT A FOLD TARGET. The old shape read that
+  // silence as permission, so a post row recorded without the wake it answered folded into ANY later
+  // post in the room — the cross-wake fold OPE-905 exists to stop, reached through the one door it
+  // left open. Positive evidence, never the absence of a contradiction.
+  if (last.wake === undefined) return null;
+  // 🔴 OPE-905 — and it must be THIS wake. A caller with no wake of its own (the per-surface `reply`)
+  // compares nothing and keeps the pre-OPE-905 verdict, which is deliberately unchanged here: this
+  // ticket narrows what counts as a TARGET, not what counts as a caller.
+  if (input.answeringWake !== undefined && last.wake !== input.answeringWake) return null;
+  const platform = last.platform ?? input.platform;
+  if (platform !== input.platform) return null;
+  if (!(input.canEdit ?? platformCanEdit)(platform)) return null;
+  const at = Date.parse(last.at);
+  if (!Number.isFinite(at)) return null;
+  if ((input.nowMs ?? Date.now()) - at > (input.windowMs ?? OWN_POST_TTL_MS)) return null;
+  return { messageId: last.id, platform };
+}
+
+/**
+ * The live read: resolve this turn's generation ring, run {@link foldTargetInTail} over it, and
+ * CONFIRM the winner against the own-post ledger.
+ *
+ * `window` is the per-turn tail window (channels/session-tail-record.ts `tailWindow()`), seeded once
+ * by the turn-start hook. `null` means this session files no posts on any ring — a delegated worker, a
+ * task session, a native seat — and so the host holds no record of what this room last heard. That is
+ * a no-fold, not a guess.
+ *
+ * `locus` is the EDITABLE ADDRESS of this conversation, resolved host-side by the caller — the SAME
+ * address its own choke point recorded the post under (channels/reply-post.ts `replyEditLocus` for a
+ * per-surface reply, channels/unified-reply.ts `unifiedEditLocus` for a unified one). `null` means the
+ * surface has no editable address at all, which is a no-fold.
+ *
+ * 🔴 THE LEDGER IS THE FENCE `edit_reply` ACTUALLY APPLIES, so the redirect is checked against it and
+ * not only against the ring. The ring write and the ledger write are independent best-effort calls
+ * (channels/reply-post.ts `recordLandedPost`), so a ring row can outlive its ledger row; steering the
+ * model at that id would produce a `not-own-post` refusal on the very call this policy just demanded.
+ * The read runs only after the pure verdict says "fold", so a normal reply never pays for it.
+ *
+ * `answeringWake` is this post's own wake id (OPE-905), passed straight to the pure verdict.
+ *
+ * ONE OPTIONS ARGUMENT, not a positional list: the call already carried five, and the two newest
+ * facts — the answering wake and the ledger injection seam — are both optional, so a positional form
+ * makes a caller count `undefined`s to reach the one it wants.
+ *
+ * NEVER THROWS. An unreadable ring answers `null`, and `isOwnPost` is itself fail-closed, which here
+ * means fail-OPEN for the policy: an unprovable target is no target, and the reply posts.
+ */
+export async function replyFoldTarget(input: {
+  readonly store: ReplyFoldStore;
+  readonly window: TailWindow | null;
+  readonly platform: string;
+  readonly locus: OwnPostLocus | null;
+  readonly answeringWake?: string | undefined;
+  readonly nowMs?: number | undefined;
+  readonly ledgerDeps?: OwnPostLedgerDeps;
+}): Promise<FoldTarget | null> {
+  const { store, window, platform, locus } = input;
+  if (!window || !locus) return null;
+  let ring: SessionTailEntry[];
+  try {
+    ring = await store.readSessionTail(window.org, window.registryKey, window.token);
+  } catch {
+    return null; // store unavailable → the policy is off, the message still lands
+  }
+  const target = foldTargetInTail(ring, {
+    container: window.container,
+    platform,
+    answeringWake: input.answeringWake,
+    ...(input.nowMs === undefined ? {} : { nowMs: input.nowMs }),
+  });
+  if (!target) return null;
+  if (!(await isOwnPost(window.org, locus, target.messageId, input.ledgerDeps ?? {}))) return null;
+  // 🔴 THE FENCE-AWARE HALF OF "CAN THIS SURFACE EDIT" (OPE-1753). {@link platformCanEdit}, which the
+  // pure `foldTargetInTail` above consults, can only ask whether the arm HAS an `editMessage`. That is
+  // not the whole answer: a credential may carry endpoint rules forbidding the method the edit issues,
+  // enforced in-process before any byte leaves. Notion is the measured case — the arm PATCHes
+  // `/v1/comments/{id}` while this deployment's channel key declares `GET,POST` on purpose, so on soak
+  // `soak-2026-09-12-a` every Notion edit was refused before dispatch while this policy went on
+  // steering the seat at it.
+  // IT LIVES HERE, NOT IN `platformCanEdit`, because deciding it needs the LOCUS and a credential
+  // resolve — asynchronous, and `foldTargetInTail` is pure and synchronous by design. Same verdict,
+  // asked where the answer is actually available.
+  // FAIL-OPEN: an arm that declares no `editReachable`, or one that throws, keeps the pre-OPE-1753
+  // answer. This predicate may only ever REMOVE a fold offer, never add one.
+  const reachable = postArm(platform)?.editReachable;
+  if (reachable) {
+    try {
+      if (!(await reachable.call(postArm(platform), locus))) return null;
+    } catch {
+      /* an arm that cannot decide does not get to refuse the fold */
+    }
+  }
+  return target;
+}
+
+/**
+ * What the model reads when the policy refuses. It states the five things the model needs and nothing
+ * else: nothing was posted, WHY a second post is a poor move, WHICH message to fold into, that the
+ * edit REPLACES that message outright (the one way this policy can lose information from the room),
+ * and the way past it.
+ *
+ * 🔴 IT NAMES EVERY ARGUMENT THE VERB IT STEERS TO ACTUALLY TAKES (OPE-1528). `edit_reply` has two
+ * variants: the wake-addressed one (tools/edit_reply.ts) takes `wake` AND `message_id`, the
+ * per-surface one takes `message_id` alone. The copy named only `message_id`, so on a wake-addressed
+ * seat it steered the model at a call that cannot be made as written — the refusal that started
+ * ship #174's J-TEAMS failure was exactly this seat.
+ *
+ * 🔴 `answeringWake` IS A PROXY FOR THE MOUNTED VARIANT, NOT THE THING ITSELF. It works because the
+ * two travel together today: the caller that holds a wake (tools/reply.ts's unified variant) is the
+ * caller whose session mounts the wake-addressed `edit_reply`. A future variant that held a wake and
+ * mounted the BASE `edit_reply` — whose schema is `{text, message_id}` — would make this copy name an
+ * argument that call rejects, which is this ticket's own defect mirrored. Anyone adding such a
+ * variant must pass the mounted variant, not the wake.
+ *
+ * 🔴 THE VALVE SENTENCE IS {@link secondMessageValve}, SHARED WITH THE SAME-TURN `done` TEETH
+ * (channels/reply-signal.ts §VALVE). Both refusals tell the model the same thing, so they tell it in
+ * the same words. It names the valve as DISCOURAGED, never as an invitation, and states its cost.
+ * Every variant of it leaves a working way to post — `force: true` where the caller holds it, a
+ * re-send where it does not — because this policy discourages a double post and never blocks one.
+ *
+ * It names only the model's OWN message id and the wake it is already answering, so the copy
+ * discloses nothing it was not already holding.
+ */
+export function foldIntoEditRefusalMessage(target: FoldTarget, canForce: boolean, answeringWake?: string | undefined): string {
+  const valve = secondMessageValve(canForce);
+  const args = answeringWake === undefined ? `message_id \`${target.messageId}\`` : `wake \`${answeringWake}\` and message_id \`${target.messageId}\``;
+  return (
+    "reply: your last message in this conversation is still the newest one — nobody has said anything since. " +
+    "NOTHING was posted. The room already has your answer, so a second post beside it reads as noise. " +
+    "Fold this into that message instead: call `edit_reply` with " +
+    `${args}. ` +
+    "🔴 An edit REPLACES the message outright, so write the FULL message — everything the old one said that still " +
+    "holds, plus what you are adding — never only the new part. " +
+    valve
+  );
+}
+
+/**
+ * THE WHOLE POLICY AT A REPLY CHOKE POINT, in one call: read the verdict, honour the once-per-room
+ * loop guard, audit, and either THROW the refusal or return so the post proceeds.
+ *
+ * 🔴 IT IS ONE FUNCTION BECAUSE TWO CALL SITES DRIFT. `reply` has two variants — the per-surface one
+ * and the cross-surface one — and this repo has already paid for that shape once: OPE-804's recorder
+ * reached only one of the two reply choke points, and every post a standing seat made on the other was
+ * recorded nowhere. A third variant can now only get this policy whole or not at all.
+ *
+ * `force` is `undefined` on a variant that has NO force input (the per-surface `reply`). That is not
+ * the same as `false`: it also decides whether the refusal copy names a valve the caller does not
+ * have. `true` overrides the verdict and writes the override row.
+ *
+ * THE READ RUNS EVEN UNDER `force`, deliberately — the same discipline the freshness gate holds. It
+ * is what makes a `reply.forced` row mean "the model overrode a REAL verdict" rather than "the model
+ * passed a flag", so the override count stays honest.
+ *
+ * 🔴 IT RETURNS HOW MANY TIMES THIS TURN HAS OVERRIDDEN THIS ROOM'S VERDICT (OPE-1659), `0` when it
+ * overrode nothing. The row is written on the FIRST override only — a later one is the same decision
+ * about the same room in the same turn, and repeating the row buries the trail rather than extending
+ * it (channels/reply-signal.ts §FORCED carries the live measurement). The caller ends the TURN past
+ * that section's `FORCED_OVERRIDE_TURN_LIMIT`; this function still refuses nothing, and every forced
+ * call still posts.
+ */
+export async function refuseIfShouldFold(input: {
+  readonly store: ReplyFoldStore;
+  readonly window: TailWindow | null;
+  readonly platform: string;
+  readonly locus: OwnPostLocus | null;
+  readonly turnId: string | undefined;
+  readonly audit: ReplyAudit;
+  /** The wake this post answers (OPE-905). `undefined` on the per-surface variant, which holds no
+   *  wake id. It is also the PROXY for which `edit_reply` variant the seat mounts, which is what the
+   *  refusal copy needs — see {@link foldIntoEditRefusalMessage}. */
+  readonly answeringWake?: string | undefined;
+  /** `undefined` ⇒ this variant has no `force` input at all. */
+  readonly force?: boolean | undefined;
+  /**
+   * THIS POST IS THE SETTLEMENT REPORT THIS TURN OWES (OPE-1753), so the policy DOES NOT APPLY.
+   *
+   * 🔴 THE FOLD'S PROXY IS FALSE ON A SETTLEMENT TURN, WHICH IS WHY THIS IS AN EXEMPTION AND NOT A
+   * FORCE. The policy asks "is this seat's own last post still the newest message in the room?" and
+   * reads a yes as "nobody has spoken since, so a second post stacks where an edit reads as one
+   * message". On a settlement turn the answer is structurally yes — the hand-off banner IS the
+   * seat's own last post and a task wake enters no surface (channels/task-wake.ts) — so the gate
+   * fires on 100% of delegated steps by construction. But somebody DID speak: the worker. Its report
+   * is new information the room has never seen, and an edit notifies nobody, so folding it in trades
+   * a duplicate for a silent drop — the member who delegated minutes ago never learns the work
+   * finished unless they happen to re-read an old message.
+   *
+   * 🔴 IT RETURNS 0 AND WRITES NOTHING — no refusal row, and no `reply.forced` row either. A forced
+   * row would assert the model overrode a host verdict, and nothing was overridden: the host is
+   * declining to hold a verdict here at all. Recording one would also spend a turn override, so the
+   * next genuine forced post would end the turn as if it were the second, and it would leave the
+   * measurement reading a compliant settlement as a fold the seat fought.
+   *
+   * WHAT THIS REPLACED. Until OPE-1753 the settlement turn met the full gate: it was refused and
+   * steered to `edit_reply`; `edit_reply` succeeded and told the seat "nobody was notified, anything
+   * NEW still needs a `reply`"; and the duty stayed armed, so `no_reply` was refused with "post it
+   * with `reply`". Three host instructions that cannot all be obeyed. The deciding record is soak
+   * `soak-2026-09-12-a` step 28, turn_8: the model called `no_reply` explaining it had "delivered by
+   * updating the existing thread message, avoiding a duplicate post", was refused, and the duplicate
+   * went out three seconds later. The model diagnosed the defect correctly and the host overrode it.
+   */
+  readonly settlementReport?: boolean | undefined;
+}): Promise<number> {
+  // Placed FIRST, above the ring read: the policy does not apply here, so there is no verdict to
+  // reach and no reason to pay for the store read that would produce one.
+  if (input.settlementReport === true) return 0;
+  const room = input.window?.container;
+  // 🔴 THE SPENT REFUSAL DISARMS THE REFUSAL, NOT THE COUNT (OPE-1664). This test used to sit ahead of
+  // everything and answer `0`, so a turn shaped "refused once, then forced on every later call"
+  // recorded no override at all and the fourth arming arm (model/turn-closeout.ts) never saw the loop
+  // — the one `done: false` shape left with no terminator from this side. It now only skips the
+  // REFUSAL below; the read and the force branch run exactly as they do on a room this turn has
+  // refused nothing, so every forced call is counted under the same (reason, room) key.
+  const refusedThisTurn = wasFoldRefusedThisTurn(input.turnId, room);
+  const target = await replyFoldTarget({
+    store: input.store,
+    window: input.window,
+    platform: input.platform,
+    locus: input.locus,
+    answeringWake: input.answeringWake,
+  });
+  if (!target) return 0;
+  if (input.force === true) {
+    // Keyed on the ROOM, exactly like this policy's own refusal record above — the fold is about what
+    // the room last heard, so an override of it is too.
+    const overrides = noteForcedOverrideThisTurn(input.turnId, REPLY_FOLD_FORCED_AUDIT_REASON, room);
+    if (overrides === 1) await auditReplyForced(input.audit, REPLY_FOLD_FORCED_AUDIT_REASON);
+    return overrides;
+  }
+  // The refusal itself is still spent once per turn per room — §LOOP GUARD below says why.
+  if (refusedThisTurn) return 0;
+  markFoldRefusedThisTurn(input.turnId, room);
+  await auditReplyRefused(input.audit, REPLY_FOLD_REFUSAL_REASON);
+  throw new Error(foldIntoEditRefusalMessage(target, input.force !== undefined, input.answeringWake));
+}
+
+// =================================================================================================
+// §LOOP GUARD — the policy refuses at most ONCE per turn per room.
+//
+// The same shape, and the same reasoning, as reply-freshness.ts's stale-refusal record: a
+// `defineState` slot keyed by the turn id, so it self-invalidates at the turn boundary and no reader
+// has to clear it. A plain array rather than a Set because the container is serialized between steps.
+//
+// WHY A REFUSAL DISARMS THE POLICY. The refusal has already told the model everything the policy
+// knows. A model that reads it and still wants a separate message is making a judgement the host
+// cannot second-guess — a scheduled report, an unrelated answer, a message that must notify. Refusing
+// once makes this a speed bump costing one step; refusing forever would make those unsayable.
+//
+// 🔴 IT DISARMS THE REFUSAL ALONE, NEVER THE OVERRIDE COUNT (OPE-1664). A spent refusal used to
+// return `0` before the read, so a "refused once, then forced on every later call" loop recorded
+// nothing and the turn-closeout arm had no terminator for that shape. The record is read into
+// `refusedThisTurn` and consulted only at the refusal, so the force branch counts every call.
+
+interface FoldRefusedRooms {
+  readonly turnId: string;
+  readonly rooms: readonly string[];
+}
+
+const refusedSlot = defineState<FoldRefusedRooms | null>("open-everywhere.reply-fold-refused", () => null);
+
+/** Cap on the recorded set — the same bound, for the same reason, as reply-freshness.ts's: it stops a
+ *  looping turn from growing the serialized container without bound. Past the cap the policy stops
+ *  RECORDING, so it keeps refusing rather than silently going quiet. */
+const MAX_REFUSED_ROOMS = 32;
+
+/** Record that the policy refused a post into `room` in THIS turn. No-op without a turn id or room. */
+function markFoldRefusedThisTurn(turnId: string | undefined, room: string | undefined): void {
+  if (turnId === undefined || turnId.length === 0) return;
+  if (typeof room !== "string" || room.length === 0) return;
+  try {
+    refusedSlot.update((prev) => {
+      const rooms = prev !== null && prev.turnId === turnId ? prev.rooms : [];
+      if (rooms.includes(room) || rooms.length >= MAX_REFUSED_ROOMS) return { turnId, rooms };
+      return { turnId, rooms: [...rooms, room] };
+    });
+  } catch {
+    /* no session context — the guard degrades to OFF, exactly as the header says */
+  }
+}
+
+/** Did the policy ALREADY refuse a post into `room` in this turn? False whenever the answer is
+ *  unknown, which leaves the policy armed — the fail direction here is "refuse once", not "never". */
+function wasFoldRefusedThisTurn(turnId: string | undefined, room: string | undefined): boolean {
+  if (turnId === undefined || turnId.length === 0) return false;
+  if (typeof room !== "string" || room.length === 0) return false;
+  try {
+    const cur = refusedSlot.get();
+    return cur !== null && cur.turnId === turnId && cur.rooms.includes(room);
+  } catch {
+    return false;
+  }
+}