@humwick/server 0.0.0-stage → 0.130.0

package/src/db/carry-pending-marker.ts

@@ -0,0 +1,129 @@
+// #1456 — the DB side of the workspace-durable carry-pending marker (round-4 BLOCKER 3 + HIGH 6).
+//
+// The per-Task blocker (db/carry-pending.ts) only protects Tasks bound AT revert time. A Task that
+// binds to the branch AFTER the revert would be unprotected — so the obligation is ALSO recorded on
+// the workspace row (`metadata.carryPending`), and every land/advance re-derives the block from it.
+// This module owns the workspace-metadata reads/writes and the task→workspace reverse lookups the
+// lowest task-state primitive uses as its backstop.
+import { getDb } from "./connection.ts";
+import { parseJson } from "../utils";
+import { getRepoSteward, getWorkspace } from "./workspaces.ts";
+import { patchWorkspaceMetadata } from "./workspace-writes.ts";
+import { activeCarryPendingHeads, carryPendingDiscardedHead, openCarryPendingBlocker, withWorkspaceCarryPendingHead, withWorkspaceCarryPendingConfirmed } from "./carry-pending.ts";
+import type { TaskBlocker } from "../types";
+
+type TaskBinding = { ownerAgentId?: string; branch?: string; id?: number };
+
+// Shared SQL EXISTS fragment (correlated to an outer `workspaces w` row + a task id) that is TRUE when
+// the task is bound to workspace `w` via the SPAWN-REQUEST path — the third binding
+// `boundTaskIdsForWorkspace` (task-lifecycle.ts) resolves and the one both guards below previously
+// omitted (round-8 BLOCKER): `w`'s owner agent carries a `meta.spawnRequestId` that the task recorded
+// an `agent.spawn_requested` event for. This is `deliverableTaskIdsBySpawnRequestId` (task-entity.ts)
+// inverted. A fire-and-forget task can have BOTH `owner_agent_id` and `branch` NULL while still bound
+// here, so without this arm the durable-marker guard silently misses it.
+//
+// NORMALIZATION (round-10 DURABLE fix) — earlier rounds tried to mirror the forward resolver's JS
+// `.trim()` inside SQL and kept losing: SQLite `trim()` strips only ASCII space (0x20), not the full
+// ECMAScript whitespace set (tab, NBSP, U+2000–200A, U+FEFF…), and `trim(json_extract(...))` coerces
+// non-string JSON scalars to text where the forward path requires `typeof === "string"`. Both re-opened
+// the leak. The durable fix moved normalization to the INGRESS (`withCanonicalSpawnRequestId` at
+// upsertAgent/mergeAgentMeta + a one-time migration), so `agent.meta.spawnRequestId` is ALWAYS canonical
+// — a JS-trimmed non-empty string, byte-identical to the event side (also canonical via `requireText`).
+// With both sides canonical this fragment needs NO SQL trimming: it just requires each side to be a JSON
+// STRING and compares them EXACTLY. The type check uses the TWO-ARGUMENT `json_type(json, path)` — which
+// returns the type of the element AT the path (NULL if absent) — NOT `json_type(json_extract(...))`: the
+// latter would re-parse the extracted scalar as JSON and raise "malformed JSON" on an ordinary string
+// like `spawn-x`. `json_type(meta,'$.spawnRequestId') = 'text'` is the exact analog of the forward
+// `typeof === "string"` (it also excludes a missing/NULL or numeric/boolean value). Empty can't
+// spuriously bind: canonical storage never persists an empty string and the event side is never empty,
+// so the exact compare cannot match on blanks.
+//
+// `taskIdExpr` must be a TRUSTED SQL expression — a bound `?` placeholder OR a table-qualified column
+// ref — NEVER user input. The outer query MUST alias the workspaces table as `w`.
+function sqlWorkspaceBoundToTaskViaSpawnRequest(taskIdExpr: string): string {
+  return `EXISTS (SELECT 1 FROM agents a`
+    + ` WHERE a.id = w.owner_agent_id`
+    + ` AND json_type(a.meta, '$.spawnRequestId') = 'text'`
+    + ` AND EXISTS (SELECT 1 FROM task_events te`
+    +   ` WHERE te.task_id = ${taskIdExpr}`
+    +   ` AND te.type = 'agent.spawn_requested'`
+    +   ` AND json_type(te.metadata, '$.spawnRequestId') = 'text'`
+    +   ` AND json_extract(te.metadata, '$.spawnRequestId') = json_extract(a.meta, '$.spawnRequestId')))`;
+}
+
+// Durably record a discarded delivered head on the workspace. Returns false when the workspace row
+// does not exist (nothing durable could be written — the caller treats that as a fail-closed
+// signal); throws only on a genuine db error, which the caller also fails closed on.
+export function markWorkspaceCarryPending(workspaceId: string, discardedHead: string, at = Date.now()): boolean {
+  const head = discardedHead.trim();
+  if (!head) return false;
+  const ws = getWorkspace(workspaceId);
+  if (!ws) return false;
+  const marker = withWorkspaceCarryPendingHead(ws.metadata, head, at);
+  return patchWorkspaceMetadata(workspaceId, { carryPending: marker }) != null;
+}
+
+// The workspaces a Task is bound to — mirrors ALL THREE binding paths `boundTaskIdsForWorkspace`
+// (task-lifecycle.ts) resolves: owner agent, branch, AND the spawn-request fallback (round-8 BLOCKER:
+// a fire-and-forget task with NULL owner+branch is still bound via spawnRequestId). Kept as a narrow
+// SQL read so the lowest primitive can call it without importing the service-layer land resolver.
+// The spawn arm is only correlated when the caller passes the task `id`; callers that pass a full task
+// detail (confirm/land re-derivation) get it, so no spawn-request-bound task is missed by the marker.
+function boundWorkspaceRows(task: TaskBinding): Array<{ id: string; repoRoot: string; steward_agent_id: string | null; metadata: Record<string, unknown> }> {
+  const owner = task.ownerAgentId?.trim();
+  const branch = task.branch?.trim();
+  const taskId = typeof task.id === "number" && Number.isSafeInteger(task.id) && task.id > 0 ? task.id : undefined;
+  if (!owner && !branch && taskId === undefined) return [];
+  const spawnArm = taskId === undefined ? "" : ` OR ${sqlWorkspaceBoundToTaskViaSpawnRequest("?")}`;
+  const params: unknown[] = [owner ?? "", branch ?? "", ...(taskId === undefined ? [] : [taskId])];
+  const rows = getDb()
+    .query(`SELECT w.id AS id, w.repo_root AS repo_root, w.steward_agent_id AS steward_agent_id, w.metadata AS metadata FROM workspaces w WHERE w.owner_agent_id = ? OR w.branch = ?${spawnArm}`)
+    .all(...(params as never[])) as Array<{ id: string; repo_root: string; steward_agent_id: string | null; metadata: string }>;
+  return rows.map((r) => ({ id: r.id, repoRoot: r.repo_root, steward_agent_id: r.steward_agent_id, metadata: parseJson<Record<string, unknown>>(r.metadata, {}) }));
+}
+
+// The ACTIVE (unconfirmed) discarded heads across every workspace this Task is bound to. Empty when
+// the Task binds to no marked workspace — the common case, so the gated-stage primitive pays this
+// read only on a landed/deploy advance.
+export function activeWorkspaceCarryPendingHeadsForTask(task: TaskBinding): string[] {
+  const heads = new Set<string>();
+  for (const ws of boundWorkspaceRows(task)) {
+    for (const head of activeCarryPendingHeads(ws.metadata)) heads.add(head);
+  }
+  return [...heads];
+}
+
+// #1456 (BLOCKERs 2 & 3 gate) — the carry-pending head that blocks a gated stage advance for this
+// task, or undefined when clear: its OWN carry-pending blocker first, else — for a late binder whose
+// blocker was never stamped — its workspace's active discarded head (re-derived from the durable
+// marker). The `setTaskStage` primitive calls this and refuses the advance when it returns a head.
+export function carryPendingHeadBlockingAdvance(task: TaskBinding & { blockedBy?: TaskBlocker[] }): string | undefined {
+  const taskBlocker = openCarryPendingBlocker(task);
+  if (taskBlocker) return carryPendingDiscardedHead(taskBlocker) || "(unknown)";
+  return activeWorkspaceCarryPendingHeadsForTask(task)[0];
+}
+
+// Clear the workspace-durable obligation for a Task's bound workspace(s) — the workspace-side half
+// of an explicit confirm. With no `heads`, clears all active heads on those workspaces.
+export function confirmWorkspaceCarryPendingForTask(task: TaskBinding, heads?: string[]): void {
+  for (const ws of boundWorkspaceRows(task)) {
+    if (activeCarryPendingHeads(ws.metadata).length === 0) continue;
+    const marker = withWorkspaceCarryPendingConfirmed(ws.metadata, heads);
+    patchWorkspaceMetadata(ws.id, { carryPending: marker });
+  }
+}
+
+// The steward agent(s) for a Task's bound workspace(s) — used to authorize an explicit carry confirm
+// (round-4 HIGH 5: the confirm is a privileged recovery op, not any task:write holder). Resolves BOTH
+// the per-workspace steward column AND the authoritative elected repo steward (`getRepoSteward`): the
+// column is only mirrored onto a workspace row when the steward CHANGES, so a workspace that joined
+// under an already-elected steward has a null column while `repo_stewards` holds the real steward.
+export function boundWorkspaceStewards(task: TaskBinding): string[] {
+  const stewards = new Set<string>();
+  for (const ws of boundWorkspaceRows(task)) {
+    if (ws.steward_agent_id?.trim()) stewards.add(ws.steward_agent_id.trim());
+    const repoSteward = getRepoSteward(ws.repoRoot)?.stewardAgentId?.trim();
+    if (repoSteward) stewards.add(repoSteward);
+  }
+  return [...stewards];
+}

package/src/db/carry-pending.ts

@@ -0,0 +1,145 @@
+// #1456 — STATE-BASED fail-safe encoding for the moved-base delivered-tip drop (PURE; no db).
+//
+// When a #1242 protected-tip moved-base revert discards a worker's delivered head, the obligation
+// to carry that head onto the new base is recorded as DURABLE STATE in two places, so no land path
+// can silently drop it and no git read is needed at land time (multi-host-safe):
+//
+//   1. a per-Task `carry-pending` blocker (encoded here as an `external` blocker whose `ref` embeds
+//      the discarded head) — protects Tasks BOUND at revert time; and
+//   2. a per-Workspace durable marker in `workspaces.metadata.carryPending` (the discarded heads) —
+//      protects Tasks that bind to the branch AFTER the revert (round-4 BLOCKER 3), and survives a
+//      per-Task stamp failure (the land drive re-derives the block from it).
+//
+// This module owns ONLY the pure encode/decode of both. The db reads/writes live in
+// `carry-pending-marker.ts`; the un-bypassable stage/status invariant is enforced in the lowest
+// task-state primitives (`db/task-entity.ts` setTaskStage / setTaskStatus) — never in a high-level
+// wrapper that a lower writer could sidestep (round-4 BLOCKERs 1 & 2).
+import type { TaskBlocker, TaskDeliverableStage, TaskStatus } from "../types";
+
+export const CARRY_PENDING_BLOCKER_REF_PREFIX = "carry-pending:";
+
+// SQL boolean (for a WHERE clause) that is TRUE when the given JSON `blocked_by` column holds NO
+// carry-pending blocker. EXACT match via `json_each`: a real blocker object (`type='external'` AND
+// `ref` beginning with the prefix AT POSITION 0), never a `LIKE '%carry-pending:%'` substring that
+// trips on an unrelated blocker whose note merely mentions the prefix or a ref like
+// `not-a-carry-pending:x` (round-6 MED). Reconciliation uses the same predicate as the
+// object-level primitive latch (setTaskStatus/setTaskStage).
+// `blockedByCol` must be a TRUSTED column reference (a code constant, never user input).
+export function sqlBlockedByHasNoCarryPending(blockedByCol: string): string {
+  const prefix = CARRY_PENDING_BLOCKER_REF_PREFIX;
+  return `NOT EXISTS (SELECT 1 FROM json_each(${blockedByCol}) je`
+    + ` WHERE json_extract(je.value, '$.type') = 'external'`
+    + ` AND substr(json_extract(je.value, '$.ref'), 1, ${prefix.length}) = '${prefix}')`;
+}
+
+// The deliverable stages that constitute "landed / shipping". Reaching ANY of these while a
+// carry-pending obligation is open is what the primitive stage-gate refuses (round-4 BLOCKER 2:
+// `stampDeployedTasks` advances deploying/deployed straight through the primitive).
+export const CARRY_PENDING_GATED_STAGES: ReadonlySet<TaskDeliverableStage> = new Set<TaskDeliverableStage>([
+  "landed-on-main",
+  "deploying",
+  "deployed",
+]);
+
+export function carryPendingBlocker(discardedHead: string): TaskBlocker {
+  return {
+    type: "external",
+    ref: `${CARRY_PENDING_BLOCKER_REF_PREFIX}${discardedHead}`,
+    note: `carry-pending (#1456): a moved-base protected-tip revert discarded delivered head ${discardedHead}; confirm the delivered change was carried onto the current base before this task can land`,
+  };
+}
+
+export function isCarryPendingBlocker(blocker: TaskBlocker): boolean {
+  return blocker.type === "external" && typeof blocker.ref === "string" && blocker.ref.startsWith(CARRY_PENDING_BLOCKER_REF_PREFIX);
+}
+
+export function openCarryPendingBlocker(task: { blockedBy?: TaskBlocker[] }): TaskBlocker | undefined {
+  return (task.blockedBy ?? []).find(isCarryPendingBlocker);
+}
+
+// EVERY carry-pending blocker on the task — a task can carry more than one when the base moved
+// again and a SECOND delivered head was discarded before the first was confirmed (round-4 HIGH 6).
+export function allCarryPendingBlockers(task: { blockedBy?: TaskBlocker[] }): TaskBlocker[] {
+  return (task.blockedBy ?? []).filter(isCarryPendingBlocker);
+}
+
+export function carryPendingDiscardedHead(blocker: TaskBlocker): string {
+  return typeof blocker.ref === "string" ? blocker.ref.slice(CARRY_PENDING_BLOCKER_REF_PREFIX.length) : "";
+}
+
+// #1456 (BLOCKER 1 latch) — true when a status write would DROP an existing carry-pending blocker:
+// the row currently carries one and the resulting persisted blocked_by set (empty unless the new
+// status is `blocked`) would not retain every existing carry-pending blocker. The `setTaskStatus`
+// primitive calls this and refuses unless the write is an authorized confirm.
+export function statusWriteDropsCarryPending(
+  current: { blockedBy?: TaskBlocker[] },
+  nextStatus: TaskStatus,
+  nextBlockedBy: TaskBlocker[] | undefined,
+): boolean {
+  const existingCarry = allCarryPendingBlockers(current);
+  if (existingCarry.length === 0) return false;
+  const nextBlockers = nextStatus === "blocked" ? (nextBlockedBy ?? []) : [];
+  return !existingCarry.every((c) => nextBlockers.some((n) => n.type === "external" && n.ref === c.ref));
+}
+
+// --- Workspace-durable marker codec (pure over a metadata object) -----------------------------
+export interface WorkspaceCarryPendingMarker {
+  /** Discarded delivered heads whose carry is NOT yet confirmed — the active obligation set. */
+  discardedHeads: string[];
+  /** First-mark timestamp (audit only). */
+  markedAt?: number;
+  /** Heads an explicit confirm has cleared (audit only). */
+  confirmedHeads?: string[];
+}
+
+export function readWorkspaceCarryPending(metadata: Record<string, unknown> | undefined): WorkspaceCarryPendingMarker | undefined {
+  const raw = metadata?.carryPending;
+  if (!raw || typeof raw !== "object") return undefined;
+  const m = raw as Record<string, unknown>;
+  const discardedHeads = Array.isArray(m.discardedHeads) ? m.discardedHeads.filter((h): h is string => typeof h === "string" && h.length > 0) : [];
+  const confirmedHeads = Array.isArray(m.confirmedHeads) ? m.confirmedHeads.filter((h): h is string => typeof h === "string" && h.length > 0) : undefined;
+  return {
+    discardedHeads,
+    ...(typeof m.markedAt === "number" ? { markedAt: m.markedAt } : {}),
+    ...(confirmedHeads && confirmedHeads.length ? { confirmedHeads } : {}),
+  };
+}
+
+// The workspace's ACTIVE (unconfirmed) obligation heads.
+export function activeCarryPendingHeads(metadata: Record<string, unknown> | undefined): string[] {
+  return readWorkspaceCarryPending(metadata)?.discardedHeads ?? [];
+}
+
+// Add a discarded head to the marker (dedup) — the next marker value to persist.
+export function withWorkspaceCarryPendingHead(
+  metadata: Record<string, unknown> | undefined,
+  head: string,
+  at: number,
+): WorkspaceCarryPendingMarker {
+  const current = readWorkspaceCarryPending(metadata);
+  const discardedHeads = current?.discardedHeads ?? [];
+  const next = discardedHeads.includes(head) ? discardedHeads : [...discardedHeads, head];
+  return {
+    discardedHeads: next,
+    markedAt: current?.markedAt ?? at,
+    ...(current?.confirmedHeads ? { confirmedHeads: current.confirmedHeads } : {}),
+  };
+}
+
+// Confirm (clear) the obligation. With no `heads`, clears ALL active heads (the confirmer asserts
+// the current base carries every discarded change); with `heads`, clears only those.
+export function withWorkspaceCarryPendingConfirmed(
+  metadata: Record<string, unknown> | undefined,
+  heads?: string[],
+): WorkspaceCarryPendingMarker {
+  const current = readWorkspaceCarryPending(metadata);
+  const discardedHeads = current?.discardedHeads ?? [];
+  const clearing = heads && heads.length ? new Set(heads) : new Set(discardedHeads);
+  const remaining = discardedHeads.filter((h) => !clearing.has(h));
+  const confirmed = [...new Set([...(current?.confirmedHeads ?? []), ...discardedHeads.filter((h) => clearing.has(h))])];
+  return {
+    discardedHeads: remaining,
+    ...(current?.markedAt ? { markedAt: current.markedAt } : {}),
+    ...(confirmed.length ? { confirmedHeads: confirmed } : {}),
+  };
+}

package/src/db/channel-binding-delete.ts

@@ -0,0 +1,15 @@
+import { getDb } from "./connection";
+import { channelSessionIsCurrent, type ChannelBindingSessionFence } from "./channels-session-fence";
+
+export function channelBindingOwner(id: string): { channelId: string; agentId: string } | null {
+  return getDb().query(`SELECT b.channel_id AS channelId, c.agent_id AS agentId
+    FROM channel_bindings b JOIN channels c ON c.id = b.channel_id WHERE b.id = ?`)
+    .get(id) as { channelId: string; agentId: string } | null;
+}
+
+/** Recheck ownership and incarnation under the writer transaction. */
+export function deleteChannelBindingBody(id: string, fence: ChannelBindingSessionFence): boolean | null {
+  if (!channelSessionIsCurrent(fence)) return null;
+  return getDb().query(`DELETE FROM channel_bindings WHERE id = ? AND channel_id IN
+    (SELECT id FROM channels WHERE agent_id = ?)`).run(id, fence.agentId).changes > 0;
+}

package/src/db/channel-egress-allowlist.ts

@@ -0,0 +1,200 @@
+// #2335 (P1 privacy) — the CHANNEL-EGRESS ALLOWLIST: what may be handed to a channel bridge.
+//
+// A bridge forwards what it receives to a real human's DM. The leak: an agent inherited a reply
+// obligation from a message the BRIDGE sent it (an egress-failure notice), and at turn end the runner
+// auto-captured the agent's raw terminal narration and addressed it at that obligation's originator —
+// skipping only the literal `"user"` sentinel, so `'telegram:default' !== 'user'` and the agent's
+// internal running commentary was DM'd to that account's allowlisted human, twice. The exposure is
+// generic per account, not specific to one bot.
+//
+// The clean SOURCE fix is the runner's (runner/src/response-capture-report.ts): auto-captured narration
+// is never a freeform note, so refusing to emit it at a channel target has zero collateral. This module
+// is the routing BACKSTOP behind it — the layer that still holds when the sender is NOT a current-checkout
+// runner (a stale runner, an automation, a plugin, a raw POST /api/messages from a script).
+//
+// Kept as a pure decision — kind + payload shape only, no DB reach — because it is enforced at TWO
+// boundaries, and both must reach the same verdict:
+//
+//   SEND side. The sole message insert (db/messages.ts) resolves whether the target is a channel
+//     (isChannelEgressTarget) and stamps the verdict onto the row, so every fan-out consumer decides
+//     identically: decideDelivery (services/agent-message-fanout.ts) routes a stamped row to `history`
+//     — still stored, still on the thread, still on the dashboard, never fanned. This covers the SSE and
+//     bus consumers, which is how channels-host subscribes (GET /api/events?for=<channelAgentId>).
+//   RECEIVE side. The channel-recipient poll (routes/messages.ts) applies this same decision to what it
+//     is about to hand back. The stamp ALONE was not enough and the #2335 review proved it: the fanout
+//     seam gates the HTTP poll only when the caller passes `delivery=turn`, which exactly one caller in
+//     the tree does (runner-core.ts) — the Telegram bridge polls without it, so a stamp-only guard was
+//     inert for the very bridge that leaked. Applying the decision at the recipient boundary also covers
+//     what a stamp structurally cannot: a fan-out/broadcast row (never stamped, because at insert time
+//     `to` is `broadcast`, not a channel) and any row written before this guard existed.
+import { isRecord, type MessagePayload } from "@humwick/sdk";
+import type { Message } from "../types";
+
+/** The pinned outbound channel envelope (emitChannelEgress / sendOutboundChannelReaction). */
+export const CHANNEL_ENVELOPE_SCHEMA = "agent-relay.channel.v1";
+
+/**
+ * #2335 — message kinds that are INTERNAL bookkeeping and are never legitimate channel content, no
+ * matter what payload they carry. `session` is the runner's turn mirror (the leak's other half);
+ * `control`/`system`/`task`/`pair` are relay lifecycle traffic. The same split the conversation
+ * projection already draws (CONVERSATION_FILTER, src/db/stats.ts) and the session-only batch
+ * endpoint assumes (src/routes/messages.ts) — a human on the far side of a bridge should never be
+ * shown any of it.
+ */
+export const INTERNAL_CHANNEL_KINDS: ReadonlySet<Message["kind"]> = new Set<Message["kind"]>(["session", "control", "system", "task", "pair"]);
+
+/**
+ * #2335 — does this payload carry an AUTO-CAPTURE marker anywhere inside it?
+ *
+ * Deliberately a DEEP scan rather than a top-level key test. The two shapes that leaked
+ * (`payload.responseCapture`, `payload.session`) are the ones we know about today; a wrapper that
+ * nests either one — a batch envelope, a forwarded mirror, some future carrier — would sail past a
+ * top-level check while carrying exactly the same narration.
+ *
+ * UNBOUNDED, and that is deliberate. An earlier depth cap looked like prudent input hygiene but was
+ * actually a hole with a number on it: the two arms that skip the top-level key check (a strict
+ * envelope, a replyContext/attachments reply) are exactly where this scan is the ONLY thing standing
+ * between a nested marker and the bridge, so a sender that simply nested one level past the cap walked
+ * through. Raising the cap only moves the hole. Termination and cost are bounded by the things that
+ * actually bound them: the payload is capped at 64 KB before it reaches here (cleanParams,
+ * src/validation.ts) and `seen` visits each object once, which also makes an in-process cyclic or
+ * shared-reference object safe — the case a depth cap was really protecting against.
+ */
+function carriesAutoCaptureMarker(value: unknown, seen = new Set<object>()): boolean {
+  if (typeof value !== "object" || value === null) return false;
+  if (seen.has(value)) return false;
+  seen.add(value);
+  if (Array.isArray(value)) return value.some((item) => carriesAutoCaptureMarker(item, seen));
+  if (!isRecord(value)) return false;
+  if (isRecord(value.responseCapture) || isRecord(value.session)) return true;
+  return Object.values(value).some((nested) => carriesAutoCaptureMarker(nested, seen));
+}
+
+/**
+ * #2335 — the top-level keys the `agent-relay.channel.v1` envelope contract recognises.
+ *
+ * DERIVED from the contract's own validator family in `src/routes/integrations.ts`
+ * (validateChannelEnvelope + validateChannelPayloadContent + validateChannelAttachmentRefs) — every
+ * `payload.<key>` those functions read. Not hand-picked, and not allowed to drift: the guard test
+ * `channel-egress-allowlist.envelope-keys.test.ts` re-derives the set from that source and fails if
+ * the validator ever learns a key this set does not know. It lives HERE rather than being imported
+ * from the route module because this is the lower layer (db/ must not import routes/), and because a
+ * routing guard has to keep working even if the ingest validator relaxes.
+ */
+export const CHANNEL_ENVELOPE_TOP_LEVEL_KEYS: ReadonlySet<string> = new Set([
+  "schema", "direction", "channel", "conversation", "actor", "event",
+  "attachments", "message", "reaction", "interaction", "activity", "dedupe",
+]);
+
+/**
+ * #2335 — is this an outbound envelope, STRICTLY?
+ *
+ * The schema/direction pair alone is not enough. Matching only those two fields lets a payload WEAR
+ * the envelope while carrying arbitrary extra top-level keys alongside it — bookkeeping, internal
+ * state, some future carrier — and be waved through as eligible channel content purely because it
+ * declared the right two strings. That is envelope IMPERSONATION, and it is a residual of exactly the
+ * kind this allowlist exists to close: the check has to bound what the payload MAY contain, not just
+ * confirm what it does contain. So every top-level key must be one the contract recognises
+ * ({@link CHANNEL_ENVELOPE_TOP_LEVEL_KEYS}); an envelope plus one unrecognised key is dead-lettered.
+ */
+function isStrictOutboundEnvelope(payload: MessagePayload): boolean {
+  if (payload.schema !== CHANNEL_ENVELOPE_SCHEMA || payload.direction !== "outbound") return false;
+  return Object.keys(payload).every((key) => CHANNEL_ENVELOPE_TOP_LEVEL_KEYS.has(key));
+}
+
+/**
+ * #2335 — the only keys a plain (un-enveloped) agent reply into a channel may carry. See arm 3 of
+ * {@link isDeliverableChannelPayload}. All three are relay-side routing/content plumbing rather than
+ * agent-authored structure, and all three are already recognised by the envelope contract
+ * ({@link CHANNEL_ENVELOPE_TOP_LEVEL_KEYS}).
+ *
+ * #2395 — `message` is a rendering HINT (today, just `{format: "text"|"markdown"|"markdownv2"}`),
+ * emitted by `humwick /reply --format` (`cli/reply.ts`) and MCP `relay_reply`'s `format` arg
+ * (`mcp/tools-messaging.ts`) on every reply, channel or not — it carries no agent-authored content
+ * of its own to leak. Before this it was not on the allowlist, so any channel reply that passed
+ * `--format` (the CLI's own usage string advertises it) was silently and permanently suppressed:
+ * accepted, persisted, stamped `channelReportSuppressed`, and never handed to the bridge — the sender
+ * saw success. Two genuine human-addressed replies were lost this way (#2395). `carriesAutoCaptureMarker`
+ * still scans `message` (and everything else) for a nested `responseCapture`/`session` marker at any
+ * depth, so admitting the key does not reopen the #2335 leak.
+ */
+const PLAIN_CHANNEL_REPLY_KEYS: ReadonlySet<string> = new Set(["replyContext", "attachments", "message"]);
+
+/**
+ * #2335 — the payload half of the channel allowlist. Three shapes are legitimate outbound content:
+ *
+ *  1. NO payload / an empty one — a plain freeform note an agent deliberately posts into a channel.
+ *     This is a real, kept feature: the body IS the message, and there is nothing internal to leak.
+ *  2. A STRICT outbound envelope ({@link isStrictOutboundEnvelope}) — what emitChannelEgress, the
+ *     escalation path and reactions build, and nothing riding along beside it.
+ *  3. A plain agent REPLY into the channel: nothing but {@link PLAIN_CHANNEL_REPLY_KEYS}.
+ *     `replyContext` is the routing breadcrumb applyReplyRouting stamps on an explicit `relay_reply`
+ *     back into the channel a message arrived from (services/send-message.ts; the #2181/#2057 lane) —
+ *     channel/conversation ids only, no agent-authored content. `attachments` is how a reply carries an
+ *     image or file: `POST /api/messages` lifts a top-level `attachments` into `payload.attachments`
+ *     (withPayloadAttachments, routes/_shared.ts) and the bridge downloads each ref and sends it as a
+ *     photo/document, so an agent answering a DM with a screenshot produces `{replyContext, attachments}`
+ *     or `{attachments}` alone. `message` is the `--format`/`format` rendering hint (#2395) — see
+ *     {@link PLAIN_CHANNEL_REPLY_KEYS} for why it belongs here. All three are contract-recognised
+ *     content — each is in {@link CHANNEL_ENVELOPE_TOP_LEVEL_KEYS} — the allowlist just has to admit
+ *     them outside a full envelope too, or a plain reply carrying one silently vanishes.
+ *
+ *     Kept as a strict SUBSET test rather than "contains one of these": nothing else may ride along, so
+ *     the arm cannot become a hatch. Enveloping the reply path and then dropping this arm entirely is
+ *     tracked as a follow-up (#2336); it is not something to slip in behind a privacy fix.
+ *
+ * Anything else — bookkeeping fields, nested wrappers, unknown internal structure — is not channel
+ * content and is dropped. Allowlist, not denylist: a denylist is only ever as good as the last
+ * incident and cannot see the carrier nobody has invented yet.
+ */
+function isDeliverableChannelPayload(payload: MessagePayload | undefined): boolean {
+  if (!payload) return true;
+  const keys = Object.keys(payload);
+  if (keys.length === 0) return true;
+  if (isStrictOutboundEnvelope(payload)) return true;
+  if ("message" in payload) {
+    if (!isRecord(payload.message) || !Object.keys(payload.message).every(key => key === "format")) return false;
+    const format = payload.message.format;
+    if (format !== undefined && (typeof format !== "string" || !["text", "markdown", "markdownv2"].includes(format.toLowerCase()))) return false;
+  }
+  return keys.every((key) => PLAIN_CHANNEL_REPLY_KEYS.has(key));
+}
+
+/**
+ * Is this row DISALLOWED as channel content? Asked as an allowlist — state what legitimate outbound
+ * traffic looks like and drop everything else — because a denylist of leaked shapes is only ever as
+ * good as the last incident and cannot see the carrier nobody has invented yet.
+ *
+ * Two ways to fail:
+ *  - an INTERNAL kind ({@link INTERNAL_CHANNEL_KINDS}) is never channel content, whatever it carries;
+ *  - otherwise the payload must be one of the deliverable shapes ({@link isDeliverableChannelPayload})
+ *    and must not smuggle an auto-capture marker at any depth ({@link carriesAutoCaptureMarker}).
+ *
+ * SUPERSEDES #2089 (T2219), which suppressed the runner's capture report only when a sibling explicit
+ * reply to the same inbound already existed (the Telegram double-reply). That case is strictly implied
+ * here, so the double stays fixed; what changes is the case #2089 deliberately let through — the
+ * "capture-only" channel, where an agent's turn-final narration was allowed to BE the reply. That lane
+ * is the leak: it publishes whatever the agent happened to say to itself at turn end.
+ *
+ * It also breaks a self-sustaining loop independently of any bridge-side fix: bookkeeping row → bridge
+ * poison → egress-failure notice → inherited reply obligation → auto-narration back at the channel →
+ * repeat.
+ */
+export function isDisallowedChannelContent(payload: MessagePayload | undefined, kind: Message["kind"], meta?: Message["meta"]): boolean {
+  if (INTERNAL_CHANNEL_KINDS.has(kind)) return true;
+  // #2338 — a redundant capture can carry the suppression in meta with an empty payload (narration in the
+  // body); an empty payload alone reads as an eligible freeform note, so honor the meta flag here too.
+  if (meta?.channelReportSuppressed === true) return true;
+  if (carriesAutoCaptureMarker(payload)) return true;
+  return !isDeliverableChannelPayload(payload);
+}
+
+/**
+ * #2395 — the reason recorded when a row is suppressed by {@link isDisallowedChannelContent}. Stamped
+ * onto `delivery_poison_reason`/`delivery_last_error` at insert (src/db/messages.ts) so the permanent,
+ * non-retryable non-delivery is OBSERVABLE — via `GET /messages/:id/delivery`, the dashboard delivery-
+ * failure notification (src/sse.ts `notificationForDelivery`), and the send receipt — instead of a row
+ * that silently sits `pending` forever. Before this fix the sender got an ordinary success receipt for
+ * a message that would never reach the channel; two genuine human replies were lost this way undetected.
+ */
+export const CHANNEL_SUPPRESSION_REASON = "channel egress guard (#2335): payload not on the channel-content allowlist — will not be delivered to the bridge";

package/src/db/channel-identity.ts

@@ -0,0 +1,38 @@
+import { stringValue } from "@humwick/sdk";
+import type { AgentCard, RegisterAgentInput } from "../types";
+
+export function channelProviderForAgent(agent: AgentCard): string {
+  return stringValue(agent.meta?.provider) ??
+    stringValue(agent.meta?.channelType) ??
+    stringValue(agent.meta?.transport) ??
+    agent.tags.find((tag) => tag.startsWith("channel:"))?.slice("channel:".length) ??
+    "custom";
+}
+
+export function channelProviderForInput(input: Pick<RegisterAgentInput, "tags" | "meta">): string {
+  return stringValue(input.meta?.provider) ??
+    stringValue(input.meta?.channelType) ??
+    stringValue(input.meta?.transport) ??
+    (input.tags ?? []).find((tag) => tag.startsWith("channel:"))?.slice("channel:".length) ??
+    "custom";
+}
+
+export function channelAccountIdForAgent(agent: AgentCard, provider: string): string {
+  const accountId = stringValue(agent.meta?.accountId);
+  if (accountId) return accountId;
+  const prefix = `${provider}:`;
+  return agent.id.startsWith(prefix) ? agent.id.slice(prefix.length) : agent.id;
+}
+
+function channelAccountIdForInput(input: Pick<RegisterAgentInput, "id" | "meta">, provider: string): string {
+  const accountId = stringValue(input.meta?.accountId);
+  if (accountId) return accountId;
+  const prefix = `${provider}:`;
+  return input.id.startsWith(prefix) ? input.id.slice(prefix.length) : input.id;
+}
+
+export function expectedChannelAgentId(input: Pick<RegisterAgentInput, "id" | "tags" | "meta">): string {
+  const provider = channelProviderForInput(input);
+  const accountId = channelAccountIdForInput(input, provider);
+  return `${provider}:${accountId}`;
+}

package/src/db/channel-runtime.ts

@@ -0,0 +1,19 @@
+import { activeTeamCoordinatorId } from "./coordinator-seat.ts";
+import { runningAgentForPolicy } from "./policy-runtime.ts";
+
+export type BindingAgentIds = Record<string, string>;
+
+/** Resolve dynamic bindings in the reader snapshot, keeping health projection DB-free. */
+export function bindingAgentIdsForChannelRows(channelRows: readonly unknown[]): BindingAgentIds {
+  const resolved: BindingAgentIds = {};
+  for (const row of channelRows as any[]) {
+    const type = row.binding_target_type;
+    const id = row.binding_target_id;
+    if ((type !== "policy" && type !== "coordinator") || !id) continue;
+    const key = `${type}:${id}`;
+    if (key in resolved) continue;
+    const agentId = type === "policy" ? runningAgentForPolicy(id) : activeTeamCoordinatorId(id);
+    if (agentId) resolved[key] = agentId;
+  }
+  return resolved;
+}

package/src/db/channels-async.ts

@@ -0,0 +1,55 @@
+// Async channels facades (S3.2 L-G #1902).
+//
+// #1869 W0.2: the health projection no longer touches the database from the main thread. It used to —
+// the roster and the `policy` binding target's running-agent lookup were both resolved with sync
+// `getDb()` reads reached through `projectChannelSnapshot`, so these facades were async in name only
+// while 5 hot `routes/integrations.ts` sites kept paying for a synchronous roster scan on the loop.
+// Both now come off `readChannelSnapshot` (worker-local). What stays on the main thread is only what
+// is main-thread-OWNED and carries no DB access: the buffered presence fold, the caller-injected
+// `disabledBackingPolicyNames` health option (already resolved config, passed in as data), and the
+// live outbound SSE subscriber probe.
+import { getGateway } from "./gateway.ts";
+import {
+  projectChannelSnapshot,
+  type ChannelHealthOptions,
+  type ChannelSnapshot,
+  type PoolBindingChange,
+  type UpsertChannelBindingInput,
+} from "./channels.ts";
+import type { ChannelBindingSessionFence } from "./channels-session-fence.ts";
+import { snapshotBufferedPresence } from "./presence-buffer.ts";
+import { ValidationError } from "./connection.ts";
+import type { ChannelBinding, ChannelSummary } from "../types";
+
+const write = <T>(op: string, args: unknown): Promise<T> =>
+  getGateway().write(op as never, args as never) as unknown as Promise<T>;
+const read = <T>(op: string, args: unknown = {}): Promise<T> =>
+  getGateway().read(op as never, args as never) as unknown as Promise<T>;
+
+export async function listChannelsAsync(options: ChannelHealthOptions = {}): Promise<ChannelSummary[]> {
+  return projectChannelSnapshot(await read<ChannelSnapshot>("channels.snapshot"), options);
+}
+export async function getChannelAsync(channelId: string, options: ChannelHealthOptions = {}): Promise<ChannelSummary | null> {
+  return (await listChannelsAsync(options)).find((channel) => channel.id === channelId) ?? null;
+}
+export const listChannelBindingsAsync = (channelId?: string): Promise<ChannelBinding[]> => read("channels.bindings", { channelId });
+export const resolveChannelRoutesAsync = (channelId: string, conversationId?: string): Promise<ChannelBinding[]> =>
+  read("channels.routes", { channelId, conversationId });
+export async function upsertChannelBindingAsync(input: UpsertChannelBindingInput, fence?: ChannelBindingSessionFence): Promise<ChannelBinding> {
+  const binding = await write<ChannelBinding | null>("channels.upsertBinding", { input, fence, presence: snapshotBufferedPresence() });
+  if (!binding) throw new ValidationError("stale agent instance");
+  return binding;
+}
+
+/** Registering a channel is writer-owned and epoch-fenced against a newer registration. */
+export const upsertChannelForAgentAsync = (agentId: string, expectedEpoch: number): Promise<boolean> =>
+  write("channels.registerAgent", { agentId, expectedEpoch, presence: snapshotBufferedPresence() });
+
+/** The common no-pool path stays on a reader and takes no BEGIN IMMEDIATE lock. */
+export async function evaluatePoolBindingsAsync(): Promise<PoolBindingChange[]> {
+  if (!await read<boolean>("channels.hasPoolBindings")) return [];
+  return write("channels.evaluatePoolBindings", { presence: snapshotBufferedPresence() });
+}
+
+export const channelBindingOwnerAsync = (id: string): Promise<{ channelId: string; agentId: string } | null> => read("channels.bindingOwner", { id });
+export const deleteChannelBindingAsync = (id: string, fence: ChannelBindingSessionFence): Promise<boolean | null> => write("channels.deleteBinding", { id, fence });

package/src/db/channels-read-ops.ts

@@ -0,0 +1,13 @@
+import { channelBindingOwner } from "./channel-binding-delete";
+// Channels reader operations (S3.2 L-G #1902). Health projection stays on the main thread.
+import { hasPoolBindings, listChannelBindings, readChannelSnapshot, resolveChannelRoutes } from "./channels.ts";
+
+export const CHANNELS_READ_OPS = {
+  "channels.bindingOwner": (args: { id: string }) => channelBindingOwner(args.id),
+  // Policy attachments, buffered presence, and subscriber liveness are process state, so return
+  // raw DB rows from the reader and project them in the async facade on the main thread.
+  "channels.snapshot": () => readChannelSnapshot(),
+  "channels.bindings": (args: { channelId?: string }) => listChannelBindings(args.channelId),
+  "channels.routes": (args: { channelId: string; conversationId?: string }) => resolveChannelRoutes(args.channelId, args.conversationId),
+  "channels.hasPoolBindings": () => hasPoolBindings(),
+};

package/src/db/channels-session-fence.ts

@@ -0,0 +1,18 @@
+// Atomic channel-binding session fence. Kept separate from channels.ts to keep the routing domain
+// below its size ratchet while preserving the query beside the DB boundary it protects.
+import { getDb } from "./connection.ts";
+import type { AgentSessionGuard } from "../types";
+
+export interface ChannelBindingSessionFence {
+  agentId: string;
+  guard: AgentSessionGuard;
+}
+
+export function channelSessionIsCurrent(fence: ChannelBindingSessionFence | undefined): boolean {
+  if (!fence) return true;
+  const row = getDb().query("SELECT instance_id, epoch FROM agents WHERE id = ?").get(fence.agentId) as
+    { instance_id: string | null; epoch: number } | undefined;
+  if (!row) return false;
+  return (!fence.guard.instanceId || row.instance_id === fence.guard.instanceId) &&
+    (fence.guard.epoch === undefined || row.epoch === fence.guard.epoch);
+}