@open-everywhere/core 0.1.0

package/agent/channels/turn-cancel.ts

@@ -0,0 +1,431 @@
+// turn-cancel — the surface-neutral half of "stop the turn". Every stop trigger on every surface funnels through {@link cancelAnchoredTurn}: resolve the anchor from the durable registry, call eve's cancel door, write one audit row. NO SESSION IS MINTED, NO MODEL IS CALLED, NOTHING IS SPENT — which is the point, because an inference-priced stop would stop working for exactly the person most likely to need it.
+// THE RESULT LIES, so do not report it as truth: eve answers `accepted` for a cancel it then drops, and that proves only the session's command hook existed. This module's return is a RECEIPT for the ingress's own logging, never a claim that work stopped; the truth arrives as the `turn.cancelled` EVENT, and a stop that was accepted and never applied earns its OWN `turn.stop_ignored` row rather than widening that one. Copy discipline: "stood down", never "stopped" and never "undone" — the side effects of an aborted step already happened and are irreversible.
+
+import { appendAudit, readAudit } from "../audit/audit.js";
+import { resolveTurnAnchor, TURN_ANCHOR_TTL_MS, type TurnAnchorQuery } from "./turn-registry.js";
+
+/** The audit action for an ingress-side cancel request. One row per REQUEST (not per outcome), so
+ *  "someone asked it to stop and nothing was running" is as visible as a successful cancel. */
+export const TURN_CANCEL_ACTION = "turn.cancel_requested";
+
+/** The audit action for a turn that was actually cancelled — written from the TURN's process
+ *  (hooks/turn-anchor.ts), which is the only one that observes `turn.cancelled`. The ingress writes
+ *  {@link TURN_CANCEL_ACTION}; the pair is what lets "asked to stop" and "actually stopped" be told
+ *  apart, which matters because eve's own `cancel()` return value cannot distinguish them. */
+export const TURN_CANCELLED_ACTION = "turn.cancelled";
+
+/**
+ * The audit action for a stop the ingress ACCEPTED and the runtime never APPLIED (OPE-1190) — the
+ * second, distinct row of the cancel evidence pair, written from the turn's process
+ * (hooks/turn-anchor.ts).
+ *
+ * 🔴 IT EXISTS SO `turn.cancelled` CAN STAY STRICT. eve answers the ingress `accepted` for a cancel
+ * it then drops; measured, ~18% of sequential runs of the cancel liveness family end the stopped
+ * turn on the ordinary completion path with no `turn.cancelled` event at all. Before this row that
+ * left NO record: an operator saw an acknowledgement, and the audit held a `turn.cancel_requested`
+ * with nothing paired to it — indistinguishable from a request the store simply lost. Widening
+ * `turn.cancelled` to cover it would have closed the visible hole by weakening the evidence claim:
+ * a reader could no longer tell a genuine cancel from an ignored stop. This row keeps both facts
+ * legible, and turns the hole into evidence.
+ *
+ * READ THE PAIR TOGETHER, AND READ IT AS STRONG EVIDENCE RATHER THAN AS AN INVARIANT. Both rows
+ * carry the ids that join back to the request, and in the ordinary case exactly one of them follows
+ * it. Five states break that, and an operator has to know them or the pair misleads:
+ *   • BOTH rows ⇒ the cancel settled later than the turn's own settle grace. The `turn.cancelled`
+ *     row is the true one; the ignored-stop row is a false finding, and the room got two notes.
+ *   • NEITHER row YET ⇒ the turn has not ended. Both partner rows are written from a terminal arm,
+ *     and NOTHING CAPS A TURN'S DURATION, so a stop of a long-running turn is simply not owed a
+ *     partner yet. This is the ordinary case, not a defect, and it is the biggest population in
+ *     {@link unpairedStops}.
+ *   • NEITHER row ⇒ the decision never resolved. The check is scheduled and drained from awaited
+ *     hook arms, but a process suspended before any of them runs takes the answer with it.
+ *   • NEITHER row, and the turn had ALREADY ENDED when the request landed ⇒ there was no terminal
+ *     arm left to notice the stop at all (OPE-1195). {@link unpairedStops} is the reader-side join
+ *     that lists the candidates for this class, because no seam inside the turn can see it.
+ *   • DUPLICATE ignored-stop rows for ONE turn ⇒ the arm's own pre-check (`pairedRowExists` in
+ *     hooks/turn-anchor.ts) READS the audit and then appends, with no transaction between the two,
+ *     so two processes can each see no row and each write one. 🔴 COUNT DISTINCT
+ *     `(sessionId, turnId)` PAIRS, NEVER ROWS — every count over these actions, this module's own
+ *     partner set included.
+ * So an unpaired `turn.cancel_requested` is worth investigating and is not proof on its own.
+ */
+export const TURN_STOP_IGNORED_ACTION = "turn.stop_ignored";
+
+/**
+ * Is this message body a bare STOP DIRECTIVE? It exists for ONE surface, and only because that vendor sends no webhook for a reaction at all, so the ✋ affordance every other surface reaches through a reaction event is unreachable there.
+ * It is narrow on purpose rather than a magic string: it matches ONLY a comment whose ENTIRE body is the word, so "please stop" and a stop word inside a sentence stay messages for the agent to read. There is deliberately NO @mention spelling, because that would be a MENTION and eve's native channel would open a session for it — cancelling the running turn and starting a new one in the same breath.
+ */
+export function isStopDirective(body: string | undefined): boolean {
+  if (typeof body !== "string") return false;
+  return STOP_DIRECTIVE.test(body.trim());
+}
+
+/** The one shape {@link isStopDirective} accepts. Anchored at both ends: a body with anything else
+ *  in it is a message, not a directive. */
+const STOP_DIRECTIVE = /^(?:\/oe\s+)?stop[.!]?$/i;
+
+/** eve's cancel door, narrowed to what this module uses. Injected rather than imported so the whole
+ *  path is unit-testable without a live runtime — and because the real one is only reachable as
+ *  `args.attachSession` inside a channel route handler. */
+export type AttachSessionForCancel = (sessionId: string) => {
+  cancel(options?: { turnId?: string }): Promise<{ readonly status?: string } | undefined>;
+};
+
+/** What actually happened, in the ingress's own terms. */
+export type CancelOutcome =
+  /** An anchor resolved and eve accepted the cancel command. Truth still arrives via `turn.cancelled`. */
+  | "requested"
+  /** eve says this session has no active turn — it is parked, waiting. Nothing to stop. */
+  | "no_active_turn"
+  /** No anchor resolved: nothing is running here, or the turn ended between the trigger and the read. */
+  | "no_turn_found"
+  /** The cancel door itself threw. */
+  | "error";
+
+export interface CancelResult {
+  readonly outcome: CancelOutcome;
+  /** User-facing, already written for a human to read verbatim. */
+  readonly message: string;
+  /** The cancelled session/turn, when one resolved — for the caller's logs, never for a prompt. */
+  readonly sessionId?: string;
+  readonly turnId?: string;
+}
+
+export interface CancelAnchoredTurnInput {
+  readonly org: string;
+  /** The platform the trigger arrived on — for the audit row only; the cancel itself is surface-neutral. */
+  readonly platform: string;
+  /** The binding's workspace segment, for the audit row. */
+  readonly workspace: string;
+  /** WHO asked. Recorded; never used to decide (the surface's own reactor/sender guard decides). */
+  readonly requestedBy?: string;
+  /**
+   * Which affordance carried the stop. Both route into this ONE cancel path, so the audit can answer "which door do people actually reach for".
+   * A third value once named the agent's own stop verb, whose door is deleted; historical rows may still carry it, and nothing writes it now.
+   */
+  readonly via: "reaction" | "command";
+  readonly query: TurnAnchorQuery;
+  readonly attachSession: AttachSessionForCancel;
+}
+
+/**
+ * Ask eve to cancel the turn a stop trigger points at: resolve the anchor, call the cancel door with the turn id, audit, and return a receipt.
+ * `turnId` is passed ALWAYS — without it a stop that raced a turn boundary would kill the NEXT turn, the one the human never asked to stop, and they would have no way to tell. It NEVER THROWS: a stop affordance that can 500 an ingress route is worse than one that quietly reports it found nothing.
+ */
+export async function cancelAnchoredTurn(input: CancelAnchoredTurnInput): Promise<CancelResult> {
+  const anchor = await resolveTurnAnchor(input.org, input.query);
+  if (!anchor) {
+    await auditCancel(input, { outcome: "no_turn_found" });
+    return { outcome: "no_turn_found", message: NOTHING_RUNNING };
+  }
+
+  let status: string | undefined;
+  try {
+    const res = await input.attachSession(anchor.sessionId).cancel({ turnId: anchor.turnId });
+    status = typeof res?.status === "string" ? res.status : undefined;
+  } catch (err) {
+    await auditCancel(input, { outcome: "error", anchorSurfaceKey: anchor.surfaceKey, note: String(err), sessionId: anchor.sessionId, turnId: anchor.turnId });
+    return { outcome: "error", message: "Couldn't reach that turn to stand it down — try again in a moment.", sessionId: anchor.sessionId, turnId: anchor.turnId };
+  }
+
+  // eve reports `no_active_turn` for a session that is parked rather than working. That is a real
+  // answer, not a failure — and it is one a human genuinely wants to hear, because it means the
+  // agent is already waiting on them.
+  const outcome: CancelOutcome = status === "no_active_turn" ? "no_active_turn" : "requested";
+  await auditCancel(input, { outcome, anchorSurfaceKey: anchor.surfaceKey, sessionId: anchor.sessionId, turnId: anchor.turnId, ...(status ? { status } : {}) });
+  return {
+    outcome,
+    message: outcome === "no_active_turn" ? NOTHING_RUNNING : STANDING_DOWN,
+    sessionId: anchor.sessionId,
+    turnId: anchor.turnId,
+  };
+}
+
+/** Nothing was running. Deliberately the SAME sentence for "no anchor" and "parked": from the
+ *  human's side the two are one fact — the agent isn't doing anything right now. */
+const NOTHING_RUNNING = "Nothing running here right now — I'm already waiting on you.";
+
+/**
+ * The receipt for an accepted cancel. IT PROMISES A REQUEST, NEVER AN OUTCOME: eve answers `accepted` for a cancel it then drops, so a claim about the TURN is one this process can neither make nor check.
+ * What it CAN promise is the follow-up — the turn's own process posts the outcome into the thread on both paths. Three things break even that: a surface with no message transport, a post whose transport failure is swallowed, and an ignored-stop decision that never resolves on a suspended instance.
+ */
+const STANDING_DOWN = "Standing down — I've asked this turn to stop. I'll post the outcome in the thread.";
+
+/** How many recent cancel-request rows the join scans. Generous: a stop is a rare, human-paced act,
+ *  so the matching row is all but always the newest one for the org. */
+const CANCEL_REQUEST_SCAN = 50;
+
+/**
+ * How far back {@link findCancelRequest} looks — a PERFORMANCE bound, not a policy one. The audit table is indexed on `(org, ts)` and NOT on `action`, so an action filter with no time bound walks the org's whole history newest-first, which is unaffordable for a question asked at the end of EVERY turn.
+ * IT IS A COVERAGE TRADE, NOT A PROOF: nothing in this repo caps a turn's duration, so a turn still running past this window finds no request row and writes no ignored-stop row at all — and a runaway turn is exactly what an ignored stop leaves behind. Widening it is cheap in code and expensive in scan.
+ */
+const CANCEL_REQUEST_WINDOW_MS = 2 * TURN_ANCHOR_TTL_MS;
+
+/**
+ * A principal id this module is willing to put in front of the MODEL. The reminder lands in the TRUSTED standing block inside a markdown code span, so a value carrying a backtick, a newline or an angle bracket could close that span and forge instruction text.
+ * The shape is therefore checked rather than assumed, and a value that fails is DROPPED — never escaped and never truncated, because a mangled id names nobody and this feature exists to name somebody or say nothing.
+ */
+const PLAIN_PRINCIPAL_ID = /^[A-Za-z0-9._:@|+-]{1,64}$/;
+
+/**
+ * The ingress's own row for a stop request against ONE turn, narrowed to what the turn's own process can use.
+ * `outcome` is the field that matters most to a reader: only `"requested"` means eve ACCEPTED the cancel command, and the other outcomes resolved nothing to cancel.
+ */
+export interface CancelRequestRecord {
+  /** WHO asked, verbatim from the row. NOT yet checked for model-safety — see {@link findCancelRequester}. */
+  readonly principalId?: string;
+  /** Which affordance carried the stop — `"reaction"` or `"command"`. */
+  readonly via?: string;
+  /** The ingress's own {@link CancelOutcome} for this request. */
+  readonly outcome?: string;
+  /** When the ingress wrote the row. */
+  readonly at?: string;
+}
+
+/**
+ * The paired `turn.cancel_requested` row for one turn, or `undefined`. THIS IS THE ONLY WAY THE ANSWER IS KNOWABLE: eve's terminal events carry no cancel history at all, so the turn's own process cannot learn from the runtime that a stop was ever asked for. The ingress records it, and the session and turn ids in that row's detail are what make the pair joinable.
+ * BOTH IDS, not just the turn: eve numbers turns PER SESSION, so a turn id alone repeats across sessions and can match a different turn's request row. It THROWS when the store does, deliberately — a caller whose whole job is to notice a missing row must tell "no request" apart from "could not read". Bounded twice: a row cap, and the TIME window that is what keeps this affordable at the end of every turn.
+ */
+export async function findCancelRequest(input: { readonly org: string; readonly turnId: string; readonly sessionId?: string }): Promise<CancelRequestRecord | undefined> {
+  const since = new Date(Date.now() - CANCEL_REQUEST_WINDOW_MS).toISOString();
+  const rows = await readAudit({ org: input.org, action: TURN_CANCEL_ACTION, since, limit: CANCEL_REQUEST_SCAN });
+  for (const row of rows) {
+    // Newest-first, so the first match is the most recent request for this turn — the right answer
+    // when a human pressed ✋ twice.
+    const detail = row.detail ?? {};
+    if (detail["turnId"] !== input.turnId) continue;
+    const rowSessionId = detail["sessionId"];
+    if (input.sessionId !== undefined && typeof rowSessionId === "string" && rowSessionId !== input.sessionId) continue;
+    return {
+      ...(typeof row.principalId === "string" ? { principalId: row.principalId } : {}),
+      ...(typeof detail["via"] === "string" ? { via: detail["via"] as string } : {}),
+      ...(typeof detail["outcome"] === "string" ? { outcome: detail["outcome"] as string } : {}),
+      ...(typeof row.ts === "string" ? { at: row.ts } : {}),
+    };
+  }
+  return undefined;
+}
+
+/**
+ * WHO asked to stop this turn, from the paired `turn.cancel_requested` row — or `undefined`.
+ * It NEVER THROWS AND NEVER GUESSES: `undefined` covers all four honest cases — the stop did not come through OE, the request row has not landed, the store is unreachable, or the recorded id is not a shape safe to show a model. The caller renders the anonymous wording for all of them.
+ */
+export async function findCancelRequester(org: string, turnId: string, sessionId?: string): Promise<string | undefined> {
+  try {
+    const by = (await findCancelRequest({ org, turnId, ...(sessionId === undefined ? {} : { sessionId }) }))?.principalId;
+    return typeof by === "string" && PLAIN_PRINCIPAL_ID.test(by) ? by : undefined;
+  } catch {
+    return undefined; // the store is unreachable — a missing name must never affect the turn
+  }
+}
+
+// --- the reader-side join (OPE-1195) -----------------------------------------------------------
+//
+// {@link findCancelRequest} above joins from the TURN's side: a turn that is ending asks whether a
+// stop was requested for it. That join can only run while there is still a turn to end, so it
+// cannot see the one shape that has no arm at all — a `turn.cancel_requested` row that lands AFTER
+// its turn already ended. The window is small (the ingress reads a live anchor, the turn ends and
+// clears it, eve still answers `accepted` because the session is alive, and the ingress writes the
+// request row), and NOBODY HAS EVER COUNTED IT, because the audit could not answer the question.
+//
+// {@link unpairedStops} is that question, asked from the READER's side: which accepted stop
+// requests hold no partner row after a grace.
+//
+// 🔴 IT LISTS CANDIDATES, IT DOES NOT MEASURE A RATE. Both partner rows are written from a terminal
+// arm and nothing caps a turn's duration, so the biggest population in any answer is the ordinary
+// one — stops of turns that are simply still running. The constant docs above list all four states
+// that put a request here, and only one of them is this residual. What isolates the residual is the
+// GRACE: set it longer than the longest turn the deployment actually runs, and what remains is the
+// class with no arm. Counting the rows at the default grace and calling the number a rate is wrong.
+//
+// THE LIST IS PER REQUEST ROW, NOT PER TURN. One turn can carry several accepted requests — a person
+// who pressed ✋ twice — and each unpaired one lists separately. The partner side already collapses
+// duplicates (the join builds a SET of `(sessionId, turnId)` keys, which is what the duplicate
+// ignored-stop row above requires); the request side deliberately does not, because who asked and
+// when are per-request facts. A caller counting TURNS must reduce on `(sessionId, turnId)` itself.
+
+/** How far back {@link unpairedStops} looks by default. A day: long enough to hold a working
+ *  session's stops, short enough that the `(org, ts)` index does the work. */
+const UNPAIRED_STOP_DEFAULT_WINDOW_MS = 24 * 60 * 60_000;
+/** The widest window {@link unpairedStops} will take. The audit table is indexed on `(org, ts)` and
+ *  NOT on `action`, so every widening is paid in scan. */
+export const UNPAIRED_STOP_MAX_WINDOW_MS = 30 * 24 * 60 * 60_000;
+/**
+ * How settled a request must be before an absent partner is worth listing. Six times the turn's own
+ * cancel-settle grace (10s, hooks/turn-anchor.ts): the ignored-stop decision resolves on a timer
+ * inside the turn's process, so a request younger than this is still pairing, and listing it would
+ * manufacture candidates out of ordinary latency.
+ *
+ * IT IS A FLOOR, NOT AN ISOLATOR. It clears the settle timer and nothing else; a stop of a turn that
+ * runs for ten minutes still lists at this grace, because no partner row is due until that turn
+ * ends. Pass a grace longer than the deployment's longest turn to narrow the answer to the class
+ * that has no arm at all.
+ */
+const UNPAIRED_STOP_DEFAULT_GRACE_MS = 60_000;
+/** Rows read per action. A cap, not a policy: a scan that hits it sets `scanTruncated`, and the
+ *  caller must narrow the window before reading "no unpaired stops" as an answer. */
+const UNPAIRED_STOP_SCAN = 1000;
+/** Default and maximum rows RETURNED. The scan is what costs; the page is what a reader can hold. */
+const UNPAIRED_STOP_DEFAULT_LIMIT = 200;
+
+/** One accepted stop request with no `turn.cancelled` and no `turn.stop_ignored` beside it. */
+export interface UnpairedStopRow {
+  readonly sessionId: string;
+  readonly turnId: string;
+  /** When the ingress wrote the request row (ISO-8601, verbatim from the audit). */
+  readonly requestedAt: string;
+  /** How long the request has stood unpaired, at the instant of the query. */
+  readonly ageMs: number;
+  /** WHO asked, when the row recorded it. */
+  readonly principalId?: string;
+  /** Which affordance carried the stop — `"reaction"` or `"command"`. */
+  readonly via?: string;
+  readonly surfaceKey?: string;
+}
+
+/** What {@link unpairedStops} answers. The counts are the measurement; `unpaired` is the worklist. */
+export interface UnpairedStopsResult {
+  readonly org: string;
+  /** The window's lower bound (ISO-8601) — every count below is over this window and no other. */
+  readonly since: string;
+  readonly graceMs: number;
+  /** Accepted requests inside the window that were old enough to judge — the DENOMINATOR. */
+  readonly requestsConsidered: number;
+  /** Accepted requests skipped because they are younger than the grace and may still be pairing. */
+  readonly requestsWithinGrace: number;
+  /** Rows whose `ts` did not parse, so no age could be taken. Counted rather than dropped in
+   *  silence: a reader must be able to see that the denominator is incomplete. */
+  readonly requestsUndated: number;
+  /** True when ANY of the three scans hit its row cap. A `false` in `unpaired` means nothing while
+   *  this is true — narrow the window and ask again. */
+  readonly scanTruncated: boolean;
+  /** Capped at `limit`; newest first. */
+  readonly unpaired: readonly UnpairedStopRow[];
+  /** True when more unpaired rows were found than `limit` returned. */
+  readonly capped: boolean;
+}
+
+export interface UnpairedStopsQuery {
+  readonly org: string;
+  readonly windowMs?: number;
+  readonly graceMs?: number;
+  readonly limit?: number;
+  /** Injected in tests so a seeded row's age is deterministic. */
+  readonly now?: number;
+}
+
+/** The join key. Both ids, never the turn alone: eve numbers turns PER SESSION, so a turn id
+ *  repeats across sessions and would pair a request with a stranger's terminal row. */
+function pairKey(detail: Readonly<Record<string, unknown>>): string | undefined {
+  const sessionId = detail["sessionId"];
+  const turnId = detail["turnId"];
+  if (typeof sessionId !== "string" || typeof turnId !== "string" || !sessionId || !turnId) return undefined;
+  return JSON.stringify([sessionId, turnId]);
+}
+
+/**
+ * Accepted stop requests in this org's recent audit with no partner row after the grace — a
+ * CANDIDATE LIST, not a rate. See {@link UNPAIRED_STOP_DEFAULT_GRACE_MS} for why the default grace
+ * lists live turns too, and what to pass instead.
+ *
+ * ONLY `outcome: "requested"` ROWS ARE OWED A PARTNER, and that is the whole precision of the
+ * query: `no_turn_found`, `no_active_turn` and `error` each resolved nothing to cancel, so nothing
+ * inside a turn ever writes a terminal row for them and an absent partner is correct, not a
+ * finding. Counting them would make every "Nothing running here right now" reply look like a bug.
+ *
+ * IT THROWS WHEN THE STORE DOES. A reader whose whole job is to notice missing rows must be able to
+ * tell "no unpaired stops" from "could not read" — the control tool renders the error.
+ */
+export async function unpairedStops(q: UnpairedStopsQuery): Promise<UnpairedStopsResult> {
+  const now = q.now ?? Date.now();
+  const windowMs = Math.min(Math.max(q.windowMs ?? UNPAIRED_STOP_DEFAULT_WINDOW_MS, 0), UNPAIRED_STOP_MAX_WINDOW_MS);
+  const graceMs = Math.max(q.graceMs ?? UNPAIRED_STOP_DEFAULT_GRACE_MS, 0);
+  const limit = Math.min(Math.max(q.limit ?? UNPAIRED_STOP_DEFAULT_LIMIT, 1), UNPAIRED_STOP_SCAN);
+  const since = new Date(now - windowMs).toISOString();
+  const scan = { org: q.org, since, limit: UNPAIRED_STOP_SCAN };
+
+  const [requests, cancelled, ignored] = await Promise.all([
+    readAudit({ ...scan, action: TURN_CANCEL_ACTION }),
+    readAudit({ ...scan, action: TURN_CANCELLED_ACTION }),
+    readAudit({ ...scan, action: TURN_STOP_IGNORED_ACTION }),
+  ]);
+
+  const partners = new Set<string>();
+  for (const row of [...cancelled, ...ignored]) {
+    const key = pairKey(row.detail ?? {});
+    if (key) partners.add(key);
+  }
+
+  const found: UnpairedStopRow[] = [];
+  let requestsConsidered = 0;
+  let requestsWithinGrace = 0;
+  let requestsUndated = 0;
+  for (const row of requests) {
+    const detail = row.detail ?? {};
+    if (detail["outcome"] !== "requested") continue;
+    const key = pairKey(detail);
+    if (!key) continue; // an accepted request always carries both ids (auditCancel); a row without them cannot be joined either way
+    const at = typeof row.ts === "string" ? Date.parse(row.ts) : Number.NaN;
+    if (!Number.isFinite(at)) {
+      requestsUndated++;
+      continue;
+    }
+    const ageMs = now - at;
+    if (ageMs < graceMs) {
+      requestsWithinGrace++;
+      continue;
+    }
+    requestsConsidered++;
+    if (partners.has(key)) continue;
+    const [sessionId, turnId] = JSON.parse(key) as [string, string];
+    found.push({
+      sessionId,
+      turnId,
+      requestedAt: row.ts as string,
+      ageMs,
+      ...(typeof row.principalId === "string" ? { principalId: row.principalId } : {}),
+      ...(typeof detail["via"] === "string" ? { via: detail["via"] as string } : {}),
+      ...(typeof detail["surfaceKey"] === "string" ? { surfaceKey: detail["surfaceKey"] as string } : {}),
+    });
+  }
+
+  return {
+    org: q.org,
+    since,
+    graceMs,
+    requestsConsidered,
+    requestsWithinGrace,
+    requestsUndated,
+    scanTruncated: requests.length >= UNPAIRED_STOP_SCAN || cancelled.length >= UNPAIRED_STOP_SCAN || ignored.length >= UNPAIRED_STOP_SCAN,
+    unpaired: found.slice(0, limit),
+    capped: found.length > limit,
+  };
+}
+
+async function auditCancel(
+  input: CancelAnchoredTurnInput,
+  detail: { outcome: CancelOutcome; anchorSurfaceKey?: string; status?: string; note?: string; sessionId?: string; turnId?: string },
+): Promise<void> {
+  try {
+    await appendAudit({
+      org: input.org,
+      platform: input.platform,
+      workspace: input.workspace,
+      action: TURN_CANCEL_ACTION,
+      ...(input.requestedBy ? { principalId: input.requestedBy } : {}),
+      // Names and ids only, never message content, the same discipline every other operational row keeps. `via` is the interesting field: it says which affordance people actually reach for.
+      // `sessionId` and `turnId` are what make this row JOINABLE to the `turn.cancelled` row the turn's own process writes: without them "someone asked" and "it actually stopped" could be counted but never connected. Absent on the `no_turn_found` arm, where by definition no turn resolved.
+      detail: {
+        via: input.via,
+        outcome: detail.outcome,
+        ...(detail.sessionId ? { sessionId: detail.sessionId } : {}),
+        ...(detail.turnId ? { turnId: detail.turnId } : {}),
+        ...(detail.anchorSurfaceKey ? { surfaceKey: detail.anchorSurfaceKey } : {}),
+        ...(detail.status ? { eveStatus: detail.status } : {}),
+        ...(detail.note ? { note: detail.note } : {}),
+      },
+    });
+  } catch {
+    /* observation only — a stop must never fail because the audit write did */
+  }
+}