@open-everywhere/core 0.1.0

package/agent/channels/standing-authority.ts

@@ -0,0 +1,237 @@
+// WHAT STOOD BEHIND AN ACT THIS TURN, OTHER THAN A CARD (OPE-1876).
+//
+// 🔴 THE SOURCE IS THE HOST'S OWN OBSERVATION, NEVER THE MODEL'S SELF-REPORT — the same rule
+// `memory/write-evidence.ts` keeps for durable writes. A model asked why nothing prompted it answers
+// from its impression of the turn, and ship #216 measured what that costs.
+//
+// ── WHAT WAS MEASURED ───────────────────────────────────────────────────────────────────────────
+// S-CONNECTOR-TIER, ship #216, Slack channel `C0EXGENRL`, 11:16:23Z–11:18:40Z. The seat created a
+// Notion page and answered: "The Notion page was created and verified … No confirmation or approval
+// requirement was presented." The audit window holds ZERO `connector.op` rows and ZERO `approval.*`
+// rows for that window. The write did not take the connector plane at all: the channel's
+// `egress.policy` row grants the connector's REST host GET, POST and PATCH under the `notion-rest`
+// credential — a standing grant declared in `agent/access/bundles.ts` and reviewed there. The
+// firewall stamps the header at the sandbox boundary, so no card can appear on that road, by design.
+// (`test:boundary` keeps a vendor's API host out of core, so the host is described here and spelled
+// in the bundle that declares it.)
+//
+// So the sentence was true about the CARD and false about the ROOM: a reader was told that nothing
+// gates this act, when what really happened is that a named standing grant already covered it. That
+// reading is the defect this ledger exists to remove — see `channels/approval-claim-guard.ts`, the
+// one reader.
+//
+// ── THE TWO THINGS RECORDED HERE, AND WHY THEY ARE ONE SUBJECT ──────────────────────────────────
+// Both answer "what authority stood behind this act, if not a card":
+//   • STANDING WRITE GRANTS — the compiled egress policy's write-capable hosts, each beside the
+//     connection id whose credential the firewall stamps there. Written by `hooks/egress.ts` from
+//     `access/egress.ts` `openWriteHosts`, which reads the COMPILED policy, so a revoked host is
+//     absent. SESSION-scoped, because the policy is: it is applied once per generation and governs
+//     every turn until it changes.
+//   • GATED CONNECTOR WRITES — a `write`- or `destructive`-tier connector op that COMPLETED this
+//     turn. Written by `hooks/connector-audit.ts`, beside the `connector.op` row it already writes.
+//     TURN-scoped, because an op belongs to the turn that called it.
+//
+// 🔴 A COMPLETED GATED WRITE WITH NO CARD MEANS AN APPROVAL ALREADY STOOD. `connectorOpApproval`
+// (`connections/connector-auth.ts`) answers `user-approval` for every write it has not already seen
+// approved this session, and a DENIED op never runs — so a write that reached `action.result`
+// without a card this turn ran under one of: an "approve for session" grant given earlier, a
+// routine's declared permission lifted by the unattended fence, or the pre-tiering blanket `once()`
+// memo. All three are an approval that already stood. The ledger records the op; it does not claim
+// to know which of the three, and the reader's sentence says only what is common to them.
+//
+// ── WHAT IS NOT HERE, STATED ────────────────────────────────────────────────────────────────────
+// 🔴 AN INDIVIDUAL REST CALL OVER THE FIREWALL IS NOT OBSERVABLE, and no ledger can pretend
+// otherwise. The firewall stamps credentials at the sandbox boundary; the host sees the POLICY, not
+// the requests. So the standing-grant half records a REACH the deployment granted, never a call
+// anybody made — the same distinction `access/egress.ts` `writeHostsAuditFields` draws with its
+// `unit: "policy"` stamp. A reader must not turn it into "a write happened".
+//
+// An UNCREDENTIALED write host is deliberately not recorded. It is reach without a lent identity,
+// and it names no grant — so it cannot be the subject of a sentence whose whole job is to NAME the
+// authority that stood. The residual: a room reachable only through uncredentialed write hosts backs
+// no naming, and the reader then leaves the reply alone.
+//
+// FAIL-SOFT, ALWAYS. Outside an eve context every function no-ops or answers "nothing observed".
+// Answering "nothing observed" makes the reader leave a claim ALONE rather than strike it, so this
+// module can never mangle a reply because a container was missing.
+
+import { defineState } from "eve/context";
+
+/** One write-capable host the compiled egress policy leaves open under a NAMED credential. A view of
+ *  `access/egress.ts` `OpenWriteHost`, narrowed to the credentialed entries and to the three fields a
+ *  room-facing sentence may carry. */
+export interface StandingWriteGrant {
+  /** The allow-list key — one host name, or `"*"` for the `networkAccessLevel: "full"` catch-all. */
+  readonly host: string;
+  /** The egress `Connection.id` whose credential the firewall stamps here. The credential's IDENTITY,
+   *  never its value — the same field `egress.policy` rows carry. */
+  readonly credential: string;
+  /** The methods the rules admit, upper-cased — or `"any"` when a rule declares no method match and
+   *  therefore admits every verb. The SHARED egress-row spelling, not a local one: `access/egress.ts`
+   *  `OpenWriteHost` names the same field, and renaming either stops the cross-plane join. */
+  readonly verb: readonly string[] | "any";
+}
+
+/** One gated-tier connector op that COMPLETED this turn. Ids and verbs only, like the
+ *  `connector.op` row written beside it. */
+export interface GatedConnectorWrite {
+  /** The connection segment of the qualified tool name — `notion`. */
+  readonly connection: string;
+  /** The op segment — `create-pages`. */
+  readonly op: string;
+  /** `write` or `destructive`. `read` never reaches this ledger: it takes no card in the first
+   *  place, so its absence explains nothing. */
+  readonly tier: "write" | "destructive";
+}
+
+interface StandingAuthorityState {
+  /** The session's standing write grants. No turn stamp: the policy governs every turn it is in
+   *  force for, and `hooks/egress.ts` re-stamps whenever it recompiles. */
+  readonly grants?: readonly StandingWriteGrant[];
+  /** The turn the `writes` below belong to. */
+  readonly turn?: string;
+  readonly writes?: readonly GatedConnectorWrite[];
+}
+
+const slot = defineState<StandingAuthorityState>("open-everywhere.standing-authority", () => ({}));
+
+/** How many grants and how many writes one state records. Past either cap the ledger stops
+ *  recording, which UNDER-reports — and under-reporting here leaves a reply alone rather than
+ *  rewriting it on a partial reading. */
+const MAX_GRANTS = 20;
+const MAX_WRITES = 32;
+
+/** Read one grant defensively. A resumed session can hand back anything an older deployment wrote,
+ *  and anything unrecognised reads as "nothing observed". */
+function readGrant(v: unknown): StandingWriteGrant[] {
+  if (typeof v !== "object" || v === null) return [];
+  const raw = v as { host?: unknown; credential?: unknown; verb?: unknown };
+  if (typeof raw.host !== "string" || raw.host.length === 0) return [];
+  if (typeof raw.credential !== "string" || raw.credential.length === 0) return [];
+  const verb =
+    raw.verb === "any"
+      ? ("any" as const)
+      : Array.isArray(raw.verb)
+        ? raw.verb.filter((m): m is string => typeof m === "string" && m.length > 0)
+        : undefined;
+  if (verb === undefined) return [];
+  return [{ host: raw.host, credential: raw.credential, verb }];
+}
+
+/** Read one gated write defensively, on the same terms. */
+function readWrite(v: unknown): GatedConnectorWrite[] {
+  if (typeof v !== "object" || v === null) return [];
+  const raw = v as { connection?: unknown; op?: unknown; tier?: unknown };
+  if (typeof raw.connection !== "string" || raw.connection.length === 0) return [];
+  if (typeof raw.op !== "string" || raw.op.length === 0) return [];
+  if (raw.tier !== "write" && raw.tier !== "destructive") return [];
+  return [{ connection: raw.connection, op: raw.op, tier: raw.tier }];
+}
+
+function readState(v: unknown): StandingAuthorityState {
+  if (typeof v !== "object" || v === null) return {};
+  const s = v as { grants?: unknown; turn?: unknown; writes?: unknown };
+  const grants = Array.isArray(s.grants) ? s.grants.flatMap(readGrant) : [];
+  const turn = typeof s.turn === "string" && s.turn.length > 0 ? s.turn : undefined;
+  const writes = turn === undefined || !Array.isArray(s.writes) ? [] : s.writes.flatMap(readWrite);
+  return { grants, ...(turn === undefined ? {} : { turn }), writes };
+}
+
+/**
+ * Record the standing write grants this session's compiled egress policy leaves open.
+ *
+ * Called by `hooks/egress.ts` and by nothing else, on every pass that reaches the apply plan — which
+ * is BEFORE the skip-unchanged gate, so a warm session that recompiles to the same bytes keeps its
+ * stamp rather than losing it. The input is the compiled policy's own `OpenWriteHost` list, so a
+ * host the policy does not open cannot appear here.
+ *
+ * REPLACES rather than merges: the newest compile is the policy in force, and a grant it dropped is
+ * a grant that is gone.
+ */
+export function noteStandingWriteGrants(hosts: readonly { host: string; credential: string | null; verb: readonly string[] | "any" }[]): void {
+  const grants = hosts
+    .flatMap((h) => (h.credential === null ? [] : [{ host: h.host, credential: h.credential, verb: h.verb }]))
+    .slice(0, MAX_GRANTS);
+  try {
+    slot.update((cur) => ({ ...readState(cur), grants }));
+  } catch {
+    /* no eve context — nothing to record, and never a reason to disturb the pass */
+  }
+}
+
+/**
+ * Record that a gated-tier connector op COMPLETED on this turn.
+ *
+ * Called by `hooks/connector-audit.ts` and by nothing else, from the same `action.result` event that
+ * writes the `connector.op` row — so an op the host did not observe finishing is never recorded. An
+ * errored op is not recorded either: it did not act, so nothing about it needs explaining.
+ *
+ * Deduplicated on the whole entry, so a turn that writes the same op twice contributes one
+ * observation. No-op outside a turn and outside an eve context.
+ */
+export function noteGatedConnectorWrite(turnId: string | undefined, write: GatedConnectorWrite): void {
+  if (turnId === undefined || turnId.length === 0) return;
+  const same = (a: GatedConnectorWrite, b: GatedConnectorWrite): boolean =>
+    a.connection === b.connection && a.op === b.op && a.tier === b.tier;
+  try {
+    slot.update((cur) => {
+      const state = readState(cur);
+      // A turn change drops the previous turn's writes and KEEPS the grants: the policy did not
+      // change because the turn did.
+      const writes = state.turn === turnId ? (state.writes ?? []) : [];
+      if (writes.length >= MAX_WRITES || writes.some((w) => same(w, write))) {
+        return { ...state, turn: turnId, writes };
+      }
+      return { ...state, turn: turnId, writes: [...writes, write] };
+    });
+  } catch {
+    /* no eve context — nothing to record, and never a reason to disturb the turn */
+  }
+}
+
+/** The standing write grants in force, or an empty list whenever the host observed none — an
+ *  unreadable container, a session that compiled no credentialed write host, a policy that denied
+ *  everything. */
+export function standingWriteGrantsInForce(): readonly StandingWriteGrant[] {
+  try {
+    return readState(slot.get()).grants ?? [];
+  } catch {
+    return [];
+  }
+}
+
+/** Every gated connector write this turn completed, or an empty list. Answers empty for an
+ *  unreadable turn id, for a ledger stamped for another turn, and outside an eve context. */
+export function gatedConnectorWritesThisTurn(turnId: string | undefined): readonly GatedConnectorWrite[] {
+  if (turnId === undefined || turnId.length === 0) return [];
+  let state: StandingAuthorityState;
+  try {
+    state = readState(slot.get());
+  } catch {
+    return [];
+  }
+  if (state.turn !== turnId) return [];
+  return state.writes ?? [];
+}
+
+/** The verbs that only read, so they are not what a WRITE grant is about. It mirrors
+ *  `access/egress.ts`'s own `READ_ONLY_METHODS`, which is not exported and sits behind the merge
+ *  fence; `scripts/approval-claim-guard-test.ts` pins the two equal by driving `openWriteHosts` and
+ *  reading what survives this filter. */
+const READ_ONLY_VERBS: ReadonlySet<string> = new Set(["GET", "HEAD", "OPTIONS"]);
+
+/**
+ * How one grant reads in a room-facing sentence: `<credential> may POST, PATCH to <host>`.
+ *
+ * The MUTATING verbs only — a write grant's read half explains no write, and listing it would make
+ * the sentence longer without making it more true. `"any"` is said in words rather than expanded
+ * into a verb set nobody declared, and a grant whose list holds nothing mutating still reads as a
+ * write grant, because `openWriteHosts` put it here and this function may not overrule that.
+ */
+export function describeStandingWriteGrant(grant: StandingWriteGrant): string {
+  if (grant.verb === "any") return `${grant.credential} may make any request to ${grant.host}`;
+  const mutating = grant.verb.filter((v) => !READ_ONLY_VERBS.has(v.toUpperCase()));
+  return mutating.length === 0
+    ? `${grant.credential} may write to ${grant.host}`
+    : `${grant.credential} may ${mutating.join(", ")} to ${grant.host}`;
+}

package/agent/channels/stranded-seat.ts

@@ -0,0 +1,155 @@
+// stranded-seat — the SEND-TIME self-heal for a standing seat whose workflow run belongs to a deployment Vercel has PRUNED. eve seals a run with a key derived from the deployment that created it and fetches that key on resume; a pruned deployment answers 404, so the seat is deaf FOREVER and silently, while every rotation rung still reads the row as healthy. Unlike the sibling unresumable class, this one is fixable: the throw lands inside the AWAITED send in the ingress process, where OE still holds the failure and can classify it.
+// The remedy is the OPERATOR MARK, never an out-of-band rotation. The mark makes the next wake take the seat's OWN rotate leg, which is the only leg that carries the outgoing generation's recorded tail; rotating here instead would mint a tail-less generation and orphan the ring. The classifier demands BOTH markers, so a 500 or a timeout stays a transient and keeps its context, and a token with no registry row gets the audit row with `remedy: "none"` and nothing else.
+
+import { appendAudit } from "../audit/audit.js";
+import type { AuditInput } from "../operational/store.js";
+import { deploymentOrg } from "../identity/binding.js";
+import { getOperationalStore } from "../operational/provider.js";
+import type { OperationalStore } from "../operational/store.js";
+import { parseWindowToken } from "./window-key.js";
+import { unifiedDomainSessionKey } from "./unified-supervisor.js";
+
+/** eve's marker for "I could not get the key that unseals this run" (compiled/@workflow/world-vercel
+ *  `Failed to fetch run key for ${runId} (deployment ${deploymentId}): HTTP …`). Matched as a
+ *  substring, so the variable ids in the middle of the sentence cannot defeat it. */
+export const RUN_KEY_FETCH_MARKER = "Failed to fetch run key";
+
+/** The Vercel API's own body for a deployment that no longer exists. */
+export const DEPLOYMENT_GONE_MARKER = "Deployment not found";
+
+/** eve renders the status into the same sentence (`HTTP ${status} ${statusText}`), so the status is
+ *  readable without the body. Either marker satisfies the second half of the predicate. */
+export const HTTP_404_MARKER = "HTTP 404";
+
+/** The durable audit action for "OE found a seat pinned to a deployment that no longer exists".
+ *  Actions-only: one row per stranded wake, and it is the ONE record that names the class. */
+export const PRUNED_DEPLOYMENT_AUDIT_ACTION = "session.pruned_deployment_strand";
+
+/** Flatten an error and its `cause` chain into one string. eve throws the run-key failure as a plain
+ *  `Error` whose own `message` carries the sentence (the measured audit row proves it), but a future
+ *  wrapper must not silently defeat the classifier. Depth-bounded so a cyclic cause cannot hang. */
+function errorText(err: unknown): string {
+  const parts: string[] = [];
+  let cur: unknown = err;
+  for (let depth = 0; depth < 5 && cur != null; depth++) {
+    parts.push(cur instanceof Error ? cur.message : String(cur));
+    cur = cur instanceof Error ? (cur as { cause?: unknown }).cause : undefined;
+  }
+  return parts.join(" | ");
+}
+
+/**
+ * Is this send failure the PRUNED-DEPLOYMENT class — a seat whose run belongs to a deployment that no longer exists? PURE, TOTAL and FAIL-SOFT: anything unrecognised classifies FALSE.
+ * BOTH halves are required, and that tightness is the point: a true verdict retires a generation and throws away its accumulated context, so a run-key fetch that failed with a 500, a timeout or a missing token must classify FALSE and keep its retry.
+ */
+export function isPrunedDeploymentWakeError(err: unknown): boolean {
+  const text = errorText(err);
+  if (!text.includes(RUN_KEY_FETCH_MARKER)) return false;
+  return text.includes(DEPLOYMENT_GONE_MARKER) || text.includes(HTTP_404_MARKER);
+}
+
+/** The run id and deployment id eve names in the sentence — recovered for the audit row so the
+ *  incident is diagnosable from the control plane without the raw log. Absent when unparseable. */
+export function prunedDeploymentIds(err: unknown): { runId?: string; deploymentId?: string } {
+  const m = /Failed to fetch run key for (\S+) \(deployment ([^)]+)\)/u.exec(errorText(err));
+  return m ? { runId: m[1], deploymentId: m[2] } : {};
+}
+
+/** What the heal did. Every value is a distinct, reportable state — never a bare boolean. */
+export type StrandHealOutcome =
+  /** Not this class — the caller's failure is untouched. */
+  | "not-classified"
+  /** Marked: the seat's next wake rotates through its own leg and lands in a fresh run. */
+  | "marked"
+  /** The token parses as a window but no `channel_session` row exists — nothing to mark. */
+  | "no-row"
+  /** The token is not a window token (a thread seat, a native session) — no rotatable row exists. */
+  | "not-a-window"
+  /** The store or the audit refused. The caller's failure still propagates. */
+  | "failed";
+
+export interface StrandHealInput {
+  /** The BARE continuation token the failing send was addressed to (no `unified:` prefix). */
+  readonly token: string;
+  /** The woken surface's `platform/workspace/surface` key — the audit row's partition. */
+  readonly surfaceKey: string;
+  /** The platform the wake came from — the audit row's partition. */
+  readonly platform: string;
+  readonly atIso: string;
+  /** The error the send rejected with. */
+  readonly err: unknown;
+  readonly org?: string;
+  readonly store?: Pick<OperationalStore, "markChannelSessionRotation">;
+  /** The audit sink. Injectable so the heal is provable without a live store; the default is the
+   *  process one. */
+  readonly audit?: (entry: AuditInput) => Promise<void>;
+  /**
+   * The `channel_session` registry key to mark, when the caller already knows it and `token` does not parse as a window token — a NATIVE supervisor session, whose registry key the surface's own grain resolution already computed.
+   * When present it WINS over the token-derived key. Omitted, the heal derives the key from `token`, so an existing window call site sees byte-identical behaviour.
+   */
+  readonly registryKey?: string;
+  /** The audit row's `workspace` label, when the caller already knows it. It WINS over the token-derived domain; omitted, the row falls back to that domain, or to "unknown". */
+  readonly workspace?: string;
+}
+
+/**
+ * Classify a failed wake send and, when it is the pruned-deployment class, MARK the seat's generation for retirement so the next wake rotates into a fresh run.
+ * NEVER THROWS: the caller is already handling a failure, and a heal that threw would replace a diagnosable error with its own.
+ */
+export async function healPrunedDeploymentStrand(input: StrandHealInput): Promise<StrandHealOutcome> {
+  if (!isPrunedDeploymentWakeError(input.err)) return "not-classified";
+  try {
+    const org = input.org ?? deploymentOrg();
+    const key = parseWindowToken(input.token);
+    const ids = prunedDeploymentIds(input.err);
+    // OPE-971: an explicit registryKey (a native/flag-off surface's own surfaceKey) wins over the
+    // token-derived one. `key` may be undefined even when `registryKey` is supplied — a native
+    // token never parses as a window token in the first place.
+    const registryKey = input.registryKey ?? (key ? unifiedDomainSessionKey(key.windowId) : undefined);
+    const marked = registryKey
+      ? await (input.store ?? getOperationalStore()).markChannelSessionRotation(org, registryKey, input.atIso)
+      : false;
+    const outcome: StrandHealOutcome = registryKey ? (marked ? "marked" : "no-row") : "not-a-window";
+    await (input.audit ?? appendAudit)({
+      ts: input.atIso,
+      org,
+      platform: input.platform,
+      workspace: input.workspace ?? key?.domain ?? "unknown",
+      surface: input.surfaceKey,
+      action: PRUNED_DEPLOYMENT_AUDIT_ACTION,
+      detail: {
+        token: input.token,
+        ...(registryKey ? { registryKey } : {}),
+        ...ids,
+        outcome,
+        // The remedy in one word, so a control-plane reader never has to infer it from `outcome`.
+        remedy: outcome === "marked" ? "rotate-at-next-wake" : "none",
+      },
+    }).catch(() => undefined);
+    return outcome;
+  } catch {
+    return "failed";
+  }
+}
+
+// The heal above marks the SEAT, which is what lets the NEXT wake land in a fresh generation. It says nothing about THIS wake, whose member is still owed an answer or, failing that, a distinguishable reason.
+// A surface that re-delivers after the heal tags the error its retry throws, BEFORE rethrowing it unchanged, so the surface's own failure recorder can give this class its own reason instead of the ordinary send-failure message.
+
+/** A private, unexported symbol so the tag can never collide with a real error property and can
+ *  never be set by anything outside this module. */
+const UNDELIVERED_AFTER_HEAL = Symbol("oeUndeliveredAfterHeal");
+
+/**
+ * Tag `err` as "a re-delivery attempted after the pruned-deployment heal, and it ALSO failed", so the surface's own wake-failure recorder can give this class its own reason. It mutates the error object in place and never throws.
+ * A non-object `err` cannot carry a property, so the tag is silently skipped and the failure still records as an ORDINARY wake-failure row rather than crashing the caller's own failure handling.
+ */
+export function markUndeliveredAfterHeal(err: unknown): void {
+  if (err && typeof err === "object") {
+    (err as Record<PropertyKey, unknown>)[UNDELIVERED_AFTER_HEAL] = true;
+  }
+}
+
+/** Was `err` tagged by {@link markUndeliveredAfterHeal}? */
+export function isUndeliveredAfterHeal(err: unknown): boolean {
+  return Boolean(err && typeof err === "object" && (err as Record<PropertyKey, unknown>)[UNDELIVERED_AFTER_HEAL] === true);
+}

package/agent/channels/supervisor-complete.ts

@@ -0,0 +1,141 @@
+// supervisor-complete — the SHARED terminal `message.completed` arm for the per-surface ticketing supervisors, so one decision and lifecycle-audit flow lives ONCE instead of being re-implemented per surface. THIS ARM POSTS NOTHING: what it owns is the TERMINAL RECORD, exactly one row per turn, closing the `<platform>.dispatched` row a webhook opened.
+// The outcome is decided on what the TURN DID, never on what this arm posted. A tool reply files `<platform>.replied` WHATEVER the closing action was, because the disciplined `reply` then `no_reply` shape arrives here as a silence and would otherwise be mislabelled; a judged silence files `<platform>.no_reply`, ungated by `audit.silences`, which covers only the ambient chat surfaces; closing prose with no tool reply files `turn.supervisor_prose_dropped`. A `reply.post` row says bytes left for a room and these say the WAKE was accounted for, so the two families never double-count.
+
+import { supervisorTextDelivery, type FinalMessageAction } from "./turn-delivery.js";
+import { appendAudit } from "../audit/audit.js";
+import { consumeRepliedThisTurn } from "./reply-signal.js";
+
+/**
+ * Read-and-reset THIS turn's reply-tool mark from a channel-event ctx — the value every caller hands back as {@link SupervisorCompletionSpec.repliedViaTool}.
+ * It is ONE function because the read is DESTRUCTIVE and its placement is load-bearing: each surface must consume the mark exactly once per TERMINAL completion, below its own buffer-tool-status return, since an intermediate step's pending tool call may BE the `reply` call.
+ */
+export function consumeSupervisorReplyMark(ctx: unknown): boolean {
+  return consumeRepliedThisTurn((ctx as { session?: { turn?: { id?: string } } } | undefined)?.session?.turn?.id);
+}
+
+/** An audit partition + optional provenance for one supervisor lifecycle row. Taint-clean by
+ *  construction — the caller only ever puts ids/counts into the anchor detail, never message text. */
+export interface SupervisorAuditRow {
+  readonly org: string;
+  readonly platform: string;
+  readonly workspace: string;
+  readonly surface?: string;
+  readonly principalId?: string;
+}
+
+/** Everything a surface's `message.completed` hands the shared arm for ONE supervisor turn. */
+export interface SupervisorCompletionSpec {
+  /** The result of finalMessageActionForTurn (the caller resolves it; the arm short-circuits the
+   *  non-terminal buffer-tool-status kind). */
+  readonly action: FinalMessageAction;
+  /** The eve session id → stamped into every row (the audit→transcript join key). */
+  readonly sessionId?: string;
+  /** Did this turn deliver through the `reply` tool? The caller's own destructive read of the
+   *  turn-keyed mark (channels/reply-signal.ts `consumeRepliedThisTurn`). TRUE wins over every
+   *  closing action — see the module header's first terminal outcome. */
+  readonly repliedViaTool: boolean;
+  /**
+   * Whether the `reply` tool is a WORKING route on THIS supervisor turn, read from the platform manifest's own `midTurnPost`. True on all three ticketing surfaces, which is what makes the message-tool-only gate live and the closing prose undeliverable.
+   * The parameter survives because the gate must READ that fact rather than assume it: a surface that ever lost its post arm would fail OPEN here, and the arm would then be posting nothing while claiming a drop.
+   */
+  readonly midTurnPost: boolean;
+  /** The per-surface lifecycle action names — the "a row closes a row" family. Each one closes the
+   *  `<platform>.dispatched` row a webhook opened. */
+  readonly noReplyAction: string; // "github.no_reply" | "linear.no_reply" | "notion.no_reply"
+  readonly repliedAction: string; // "github.replied"  | "linear.replied"  | "notion.replied"
+  /** Partition for the SILENT + prose-dropped rows (context labels — the seed container on a
+   *  cleared-target row). */
+  readonly contextRow: SupervisorAuditRow;
+  /** Partition for the REPLIED row (the post-target container — the WAKING container on a unified
+   *  session). May equal {@link contextRow}. */
+  readonly repliedRow: SupervisorAuditRow;
+  /** Reply-anchor detail on the SILENT row (id-or-null): { issueNumber: n ?? null } etc. */
+  readonly silentAnchor: Record<string, unknown>;
+  /** Reply-anchor detail on the prose-DROPPED row: { issueNumber } etc. */
+  readonly droppedAnchor: Record<string, unknown>;
+  /** Reply-anchor detail on the REPLIED row (id + any extras — Linear's parentId). */
+  readonly repliedAnchor: Record<string, unknown>;
+  /** The surface's logger (slog/log) — the arm normalises the drop / fail-open messages through it. */
+  readonly log: (msg: string) => void;
+}
+
+/** `detail.route` on a `<platform>.replied` row: the reply tool posted the bytes, and the canonical
+ *  `reply.post` row (channels/reply-post.ts) is where their count lives. ONE greppable string. */
+export const SUPERVISOR_REPLIED_ROUTE = "tool";
+
+/** Run one ticketing-supervisor terminal completion through the shared decision and lifecycle audit row. Writes exactly one row per terminal turn, and posts nothing. */
+export async function completeSupervisorTurn(spec: SupervisorCompletionSpec): Promise<void> {
+  const { action } = spec;
+  if (action.kind === "buffer-tool-status") return; // mid-turn tool call — not terminal, leave alone
+  const sid = spec.sessionId ? { sessionId: spec.sessionId } : {};
+
+  // 1. THE TURN DELIVERED. First, and above the closing action, for the reason the header states:
+  // the disciplined `reply` → `no_reply` shape arrives here as kind "silent", and filing it as a
+  // silence would make the silence count meaningless the moment this doctrine is followed.
+  if (spec.repliedViaTool) {
+    await appendAudit({
+      org: spec.repliedRow.org,
+      platform: spec.repliedRow.platform,
+      workspace: spec.repliedRow.workspace,
+      surface: spec.repliedRow.surface,
+      principalId: spec.repliedRow.principalId,
+      action: spec.repliedAction,
+      detail: { ...spec.repliedAnchor, route: SUPERVISOR_REPLIED_ROUTE, ...sid },
+    });
+    return;
+  }
+
+  if (action.kind === "silent") {
+    // The judged-silence lifecycle row — UNCONDITIONAL (the ticketing triple is not gated behind
+    // audit.silences; that flag is the ambient-chat surfaces' judged-silence gate). The await is
+    // uncaught, like its `replied` sibling: this row closes a dispatched row.
+    await appendAudit({
+      org: spec.contextRow.org,
+      platform: spec.contextRow.platform,
+      workspace: spec.contextRow.workspace,
+      surface: spec.contextRow.surface,
+      principalId: spec.contextRow.principalId,
+      action: spec.noReplyAction,
+      detail: { ...spec.silentAnchor, reason: action.reason, ...sid },
+    });
+    return;
+  }
+
+  // `action.kind === "post"` with no tool reply — a non-empty closing completion the model wrote as if it were the delivery, which the MESSAGE-TOOL-ONLY gate drops on every surface with a working reply route.
+  // This is the load-bearing leak case: the turn produced an answer and took no action to deliver it, so the row is the only witness that anything was owed.
+  const delivery = supervisorTextDelivery(true /* non-empty prose */, spec.midTurnPost);
+  if (!delivery.postText) {
+    spec.log(`supervisor message-tool-only: DROPPED terminal prose (${action.text.length}c) — reply must come from the reply tool`);
+    await appendAudit({
+      org: spec.contextRow.org,
+      platform: spec.contextRow.platform,
+      workspace: spec.contextRow.workspace,
+      surface: spec.contextRow.surface,
+      principalId: spec.contextRow.principalId,
+      action: "turn.supervisor_prose_dropped",
+      detail: { ...spec.droppedAnchor, chars: action.text.length, ...sid },
+    });
+    return;
+  }
+
+  // FAIL OPEN — reachable only when a surface declares `midTurnPost: false`, meaning it has no mid-turn post arm at all. No ticketing surface is in that state today.
+  // The branch is kept DEAD-BUT-STRUCTURAL on purpose: an arm that silently swallowed the prose here would be a lost answer wearing a green test. It posts nothing and says so loudly, so a regressed manifest is found by a log line and an unclosed dispatched row.
+  spec.log(
+    `supervisor terminal prose (${action.text.length}c) NOT delivered — this surface declares no mid-turn post route, so nothing can post it; wire a post arm (channels/post-arms.ts) or the answer is lost`,
+  );
+}
+
+/**
+ * The shared "a failed judge turn or dead session must not spam the surface" arm: audit, and nothing posted — the reserved posture every ticketing supervisor shares.
+ * Best-effort and never throws. The action name, workspace and detail are the caller's.
+ */
+export async function auditSupervisorFailure(row: SupervisorAuditRow, action: string, detail: Record<string, unknown>): Promise<void> {
+  await appendAudit({
+    org: row.org,
+    platform: row.platform,
+    workspace: row.workspace,
+    surface: row.surface,
+    action,
+    detail,
+  }).catch(() => undefined);
+}