@humwick/server 0.0.0-stage → 0.130.0

package/src/memory-retirement.ts

@@ -0,0 +1,11 @@
+// Compatibility guidance for stale custom configuration and tool calls (#3456).
+export const RETIRED_MEMORY_REFERENCES = new Set([
+  "memory-steward", "profile.memory-steward.charter",
+  "relay_store_memory", "relay_retrieve_memory", "relay_memory_write", "relay_memory_read",
+  "relay_memory_search", "relay_memory_promote", "relay_memory_retract", "relay_memory_consolidate",
+]);
+
+export function memoryRetirementMessage(reference: string): string | undefined {
+  if (!RETIRED_MEMORY_REFERENCES.has(reference.toLowerCase())) return undefined;
+  return `${reference} was retired. Remove memory-steward schedules, profile references and retired memory tool includes from custom configuration. Use relay_project_read, relay_project_write_entry and relay_project_retract to curate project entries. Historical steward entries remain editable. Export retained state with bun scripts/export-retired-memory.ts <database> <output.ndjson>.`;
+}

package/src/memory-seam.ts

@@ -0,0 +1,273 @@
+// #1625 — ONE resolution of WHO an agent is for memory purposes, made once at the spawn seam and
+// replayed at every later identity-sensitive seam.
+//
+// #1565 P4/P5.5 put three seams over the same memory chain — spawn (`spawn-agent.ts`), restart
+// (`services/restart-instructions.ts`) and the clear/compact boundary (`memory-injection.ts`) —
+// and each re-derived identity from whatever it happened to have in hand. They diverged silently
+// on HOST (#1625 F3): spawn resolved `resolveCanonicalHost(orchestrator.hostname)` — the registered
+// name, which trivially maps to itself. The boundary and restart resolved
+// `resolveCanonicalHost(agent.machine)` — the runner's raw `os.hostname()`. #1608 taught that
+// comparison to fold case AND `.`/`-`, which closed the variants of the DEVELOPMENT host and
+// nothing else: `wbox-1.local` against a registered `wbox-1`/`wbox`, a foreign `MacMiniNG.local`,
+// a cloud instance id `ip-10-0-0-5`, or an empty `machine` all still fall through
+// `host-identity.ts`'s raw-value fallback (or to `undefined`) and name a DIFFERENT host cell than
+// the one the spawn block was composed from. No amount of further folding closes that set:
+// `machine` is a value the spawn seam never consulted, so it can be anything.
+//
+// THE FIX IS NOT A BETTER DERIVATION — it is to stop deriving identity twice. What the spawn seam
+// resolved is stamped into the IMMUTABLE `agent.spawn` / `agent.restart` command params
+// (`memorySeam`, beside the composed `systemPromptAppend` it produced), and every later seam reads
+// it back. Project inclusion is always derived from the current profile named by that identity.
+// Its launch-time value is persisted only to verify whether a later supersede notice may safely
+// describe an absent project rule as retracted; it never gates composition.
+//
+// The derivation survives as a FALLBACK, for agents that never went through a composing spawn seam
+// (a self-registered runner, an automation worker with no agent id at compose time, an agent that
+// launched before this shipped). Those are reported rather than papered over: `fromLaunch:false`
+// is what the boundary uses to soften the supersede notice from "was retracted" to "unverified"
+// (`withMemorySupersedeNotice`), because a notice that claims retraction for something merely
+// resolved differently is worse than no notice — the agent acts on it.
+import { isRecord, stringValue } from "@humwick/sdk";
+import { findLaunchMemorySeamCommandForAgent, findLaunchMemorySeamCommandsForAgents } from "./commands-db";
+import { projectMemoryEnabledForProfile } from "./config-store";
+import { resolveAgentOwnership } from "./db/agent-ownership";
+import type { MemoryIdentity } from "./db/memory-resolve";
+import { resolveCanonicalHost } from "./host-identity";
+import { resolveProjectForCanonicalCwd } from "./services/project-cwd";
+import type { AgentCard, Command } from "./types";
+
+/** The spawn seam's memory resolution, in the shape the composer consumes. */
+export interface MemorySeam {
+  /** WHO the agent is — the `base → provider → host → project` cell keys plus the audience. */
+  identity: MemoryIdentity;
+  /** Launch-time Project Instructions result, for supersede-notice agreement only. Composition
+   * always re-derives the current value through {@link projectMemoryEnabledForSeam}. */
+  projectMemoryEnabled?: boolean;
+}
+
+export function projectMemoryEnabledForSeam(seam: MemorySeam): boolean {
+  return projectMemoryEnabledForProfile(seam.identity.profile);
+}
+
+export interface ResolvedMemorySeam extends MemorySeam {
+  /** True when this is the launch-recorded identity. False when it was re-derived from the agent
+   * card, i.e. when seam agreement is unproven. */
+  fromLaunch: boolean;
+  /** #2264 — true when the LAUNCH RECORD resolved no project at all. Then the launch block was
+   * composed without a project cell, so it is not byte-comparable to anything this seam composes
+   * and a supersede notice must never claim the difference is a retraction — in EITHER direction.
+   *
+   * Deliberately keyed on the RECORD, not on whether the backfill below found anything. Keying it
+   * on the probe would make the claim FLAP: the cwd stops resolving (a worktree removed after the
+   * land, a relay restarted without the path, an archived project), the backfill goes quiet, and
+   * the boundary would go straight back to telling an agent that still carries the previous block
+   * that its entries were retracted — the exact defect this change exists to kill. */
+  launchProjectAbsent?: boolean;
+  /** #2264 — and the agent's CURRENT cwd supplied one, so this seam carries a project cell the
+   * launch block did not. Reported for the operator; the notice is governed by
+   * {@link ResolvedMemorySeam.launchProjectAbsent}, which does not depend on the probe. */
+  projectBackfilled?: boolean;
+}
+
+/** The command-param key the spawn/restart payloads carry it under. */
+export const MEMORY_SEAM_PARAM = "memorySeam";
+
+/** Strip the resolution provenance back to the storable shape — `fromLaunch` describes THIS read,
+ *  not the record, and must never be stamped into a command payload. */
+export function memorySeamParams(seam: MemorySeam): MemorySeam {
+  return {
+    identity: seam.identity,
+    ...(seam.projectMemoryEnabled !== undefined ? { projectMemoryEnabled: seam.projectMemoryEnabled } : {}),
+  };
+}
+
+function identityFrom(value: Record<string, unknown>): MemoryIdentity {
+  const field = (key: keyof MemoryIdentity): string | undefined => stringValue(value[key]);
+  return {
+    ...(field("operator") ? { operator: field("operator")! } : {}),
+    ...(field("provider") ? { provider: field("provider")! } : {}),
+    ...(field("host") ? { host: field("host")! } : {}),
+    ...(field("projectId") ? { projectId: field("projectId")! } : {}),
+    ...(field("profile") ? { profile: field("profile")! } : {}),
+  };
+}
+
+/** Read a stamped seam back out of a command payload, field by field. Legacy sourcePolicy is
+ * deliberately ignored; projectMemoryEnabled is retained only as the launch agreement witness. */
+export function parseMemorySeam(value: unknown): MemorySeam | null {
+  if (!isRecord(value) || !isRecord(value.identity)) return null;
+  return {
+    identity: identityFrom(value.identity),
+    ...(typeof value.projectMemoryEnabled === "boolean" ? { projectMemoryEnabled: value.projectMemoryEnabled } : {}),
+  };
+}
+
+/**
+ * The seam the launch that produced THIS agent's current process actually resolved — from the
+ * immutable command params, top-level (`agent.spawn`, and the restart's own projected block) or
+ * nested under `restartSpawn` (the successor payload a restart builds). Newest wins, so a restarted
+ * agent replays its latest recorded identity rather than its first.
+ */
+export function launchMemorySeamForAgent(agent: AgentCard): MemorySeam | null {
+  return seamFromLaunchCommand(
+    findLaunchMemorySeamCommandForAgent(agent.id, stringValue(agent.meta?.spawnRequestId)) ?? undefined,
+  );
+}
+
+/** Pull the stamped seam out of a resolved launch command — top-level, then the restart's nested
+ *  `restartSpawn` block. Shared by the single-agent and batched lookups so both read it identically.
+ *  Typed on just `params` (not the full `Command`) because that is all either lookup's result
+ *  carries this far: the single-agent path hands in a full `Command`, the batched path hands in the
+ *  narrower `LaunchSeamCommand` projection (#1958) — both satisfy this. A missing command (no launch
+ *  record for this agent) resolves to `null`, the caller's cue to fall back to the derivation. */
+function seamFromLaunchCommand(command: Pick<Command, "params"> | undefined): MemorySeam | null {
+  if (!command) return null;
+  const nested = command.params.restartSpawn;
+  return parseMemorySeam(command.params[MEMORY_SEAM_PARAM])
+    ?? (isRecord(nested) ? parseMemorySeam(nested[MEMORY_SEAM_PARAM]) : null);
+}
+
+/**
+ * The batched form of {@link memorySeamForAgent}, reading only the projected launch fields (see
+ * {@link findLaunchMemorySeamCommandsForAgents}, indexed per agent since #2712). Each RESOLVABLE agent
+ * gets the SAME `ResolvedMemorySeam` the per-agent path would — launch record wins, derivation is the
+ * flagged fallback.
+ *
+ * An agent whose derivation THROWS (a deleted project, a malformed cwd) is OMITTED from the result
+ * rather than failing the whole batch: a fleet-wide caller must not lose every OTHER agent to one
+ * bad row. That is a property of the row, and its own seams already report it — so the map holds one
+ * entry per RESOLVABLE agent, and a missing id means "could not resolve", not "no such agent".
+ */
+export function memorySeamsForAgents(agents: ReadonlyArray<AgentCard>): Map<string, ResolvedMemorySeam> {
+  const commands = findLaunchMemorySeamCommandsForAgents(
+    agents.map((agent) => ({ id: agent.id, spawnRequestId: stringValue(agent.meta?.spawnRequestId) })),
+  );
+  const seams = new Map<string, ResolvedMemorySeam>();
+  for (const agent of agents) {
+    const launched = seamFromLaunchCommand(commands.get(agent.id));
+    if (launched) {
+      // Same replay (and the same #2264 backfill) the per-agent path performs, or the fleet sweep
+      // would report a project cell the boundary does not compose. The backfill's cwd→project probe
+      // only runs for an agent whose launch record has NO projectId — the derivation below already
+      // pays it for every agent with no launch record at all — and `canonicalRoot` caches per cwd.
+      seams.set(agent.id, replayedSeam(agent, launched));
+      continue;
+    }
+    try {
+      seams.set(agent.id, { ...derivedMemorySeamForAgent(agent), fromLaunch: false });
+    } catch {
+      // Omitted on purpose — see the doc comment. The bad row's own seams report it.
+    }
+  }
+  return seams;
+}
+
+/** The project the agent's CURRENT cwd resolves to, canonicalized (#1597) — the one input the
+ *  derivation and the backfill below share, so they can never disagree about it. */
+function derivedProjectIdForAgent(agent: AgentCard): string | undefined {
+  const cwd = stringValue(agent.meta?.cwd);
+  return cwd ? resolveProjectForCanonicalCwd(cwd).project?.id : undefined;
+}
+
+/**
+ * Replay a launch-recorded seam — and BACKFILL a project the launch could not resolve (#2264).
+ *
+ * The launch record is a snapshot, and `projectId` is the one field in it that is not a fact about
+ * the agent: it is a fact about the PROJECT REGISTRY, which moves underneath a long-lived agent.
+ * A live coordinator proved it — spawned 2026-08-14 12:49, its stamped identity is
+ * `{operator, provider, host, profile}` with no `projectId`, because its project row was
+ * only created at 15:33 that day. #2154 left the project cell as the ONLY injected cell, so
+ * replaying that snapshot literally composed 0 entries at every later boundary, forever, while a
+ * fresh spawn of the same identity resolved 65. #2261's clear-commit fix then turned that on for the
+ * clear boundary (the P4b path is gated on `status === "succeeded"`, which a clear-inject never
+ * reported before), so the agent was handed a block with no entries AND a supersede notice saying
+ * everything missing from it had been retracted.
+ *
+ * ABSENT ONLY, NEVER OVERRIDE. A recorded `projectId` is what the launch block was actually composed
+ * from and stays authoritative — re-deriving over it is exactly the #1625 divergence this module
+ * exists to prevent, and it could LOSE a cell (a worktree the relay cannot stat resolves to no
+ * project at all; see the `#1625 — projectId agreement` fixture). Filling an ABSENT one can only
+ * ever ADD the cell the agent should have had, so it fails toward keeping memory rather than
+ * dropping it. The result is flagged, because the composed block is then no longer byte-comparable
+ * to the launch block: `launchProjectAbsent` downgrades the boundary's retraction claim to
+ * "unverified" and both flags show up in the accounting event. A restart re-stamps the healed
+ * identity, so the successor generation replays it as an ordinary launch seam.
+ *
+ * WHAT IT STILL DOES NOT RECOVER, all failing SAFE (a blank cell, never a wrong one):
+ *   • a launch record naming a project that was later archived or deleted — only an ABSENT id is
+ *     filled, never a stale one;
+ *   • a cwd whose project row was never SEEDED — this probe is read-only, while the spawn path
+ *     creates the row through `autoSeedProjectForCwdAsync`;
+ *   • GIT_DIR-style repos, where the sync resolver has no `git rev-parse --git-common-dir`
+ *     fallback and so resolves no canonical root at all.
+ */
+function replayedSeam(agent: AgentCard, launched: MemorySeam): ResolvedMemorySeam {
+  const replayed: ResolvedMemorySeam = { ...launched, fromLaunch: true };
+  if (launched.identity.projectId !== undefined) return replayed;
+  // Stamped BEFORE the probe, and never removed by its outcome: this is a fact about the launch
+  // record, and it is what governs the notice. See `launchProjectAbsent` — a probe-derived signal
+  // would let the retraction claim flap back on the first cwd that stops resolving.
+  const absent: ResolvedMemorySeam = { ...replayed, launchProjectAbsent: true };
+  let projectId: string | undefined;
+  try {
+    projectId = derivedProjectIdForAgent(agent);
+  } catch {
+    // A probe that throws (a deleted project row, an unstattable worktree) is not evidence of a
+    // project. Keep the launch seam exactly as recorded rather than losing the whole agent.
+    return absent;
+  }
+  if (!projectId) return absent;
+  return { ...absent, identity: { ...launched.identity, projectId }, projectBackfilled: true };
+}
+
+/**
+ * The pre-#1625 derivation, kept as the fallback for agents with no recorded launch seam. Every
+ * field still comes from where the boundary took it: the owner, the reported machine canonicalized
+ * through `resolveCanonicalHost`, the provider, the canonicalized cwd project (#1597), and the
+ * profile. Deterministic, but NOT guaranteed to agree with a spawn seam, which is exactly why
+ * callers are told which one they got.
+ */
+export function derivedMemorySeamForAgent(agent: AgentCard): MemorySeam {
+  const provider = stringValue(agent.meta?.provider) ?? stringValue(agent.providerCapabilities?.model?.provider);
+  const projectId = derivedProjectIdForAgent(agent);
+  const profile = stringValue(agent.meta?.profile);
+  const host = resolveCanonicalHost(agent.machine);
+  return {
+    identity: {
+      // #1895 (S3.2 L10 review, deferred) — `resolveAgentOwnership` DELIBERATELY left sync here.
+      // This function (via `memorySeamsForAgents`) is called once PER AGENT inside
+      // `memoryStoreHealthSweepTargets`'s tight loop over the WHOLE registered fleet — the exact
+      // sweep `memorySeamsForAgents`'s own header comment protects from O(agents) per-tick cost
+      // (#1726, ~40s stall at 127 agents before that fix). Switching this one call to
+      // `resolveAgentOwnershipAsync` would reintroduce an O(agents) async round-trip per sweep
+      // tick — the class of stale-read/async-loop regression this leaf's brief explicitly warns
+      // against — for a sync in-process lookup that is otherwise cheap. It also feeds
+      // `settleMemoryInjectionAfterContextCommand`, which runs from BOTH an HTTP handler and the
+      // synchronous bus command-settle chain; making it awaitable would mean restructuring that
+      // reactive pipeline, not a mechanical caller-swap. Batch-resolving ownership for the sweep
+      // (mirroring the commands-scan batching below) is the right fix, but it changes this
+      // function's per-agent shape — real follow-up work, not same-leaf scope.
+      operator: resolveAgentOwnership(agent.id).ownerUserId,
+      ...(host ? { host } : {}),
+      ...(provider ? { provider } : {}),
+      ...(projectId ? { projectId } : {}),
+      ...(profile ? { profile } : {}),
+    },
+  };
+}
+
+/**
+ * THE answer to "under what identity does this agent's memory resolve" — the one every non-spawn
+ * seam must ask. The launch record wins; the derivation is the flagged fallback. Project memory
+ * inclusion is derived separately from that identity's current profile; the recorded result is
+ * comparison-only provenance for the supersede notice.
+ *
+ * #2264: a launch record with NO project is the one part of the snapshot that is refreshed rather
+ * than replayed — see {@link replayedSeam}.
+ */
+export function memorySeamForAgent(agent: AgentCard): ResolvedMemorySeam {
+  const launched = launchMemorySeamForAgent(agent);
+  return launched
+    ? replayedSeam(agent, launched)
+    : { ...derivedMemorySeamForAgent(agent), fromLaunch: false };
+}

package/src/memory-tokens.ts

@@ -0,0 +1,91 @@
+// Shared token estimates for project-memory tools, prompt composition and dashboard accounting.
+
+import type { ProjectEntry } from "./types";
+
+/** The per-entry framing overhead (title bullet, id, scope label) the raw text does not carry. */
+const ENTRY_FRAMING_TOKENS = 24;
+
+export type EstimableEntry = Pick<ProjectEntry, "title" | "tags"> & { body?: string };
+
+/** Estimated tokens an entry costs when rendered whole (title + tags + body). */
+export function estimateEntryTokens(entry: EstimableEntry): number {
+  const text = [entry.title, entry.tags.join(" "), entry.body ?? ""].join("\n");
+  return Math.max(1, Math.ceil(text.length / 4) + ENTRY_FRAMING_TOKENS);
+}
+
+/** Estimated tokens for a run of plain prompt text — the same chars/4 arithmetic as
+ *  `estimateEntryTokens`, WITHOUT the per-entry framing overhead, because the instruction preface
+ *  (#1565 P5.1) is prose the composer emits verbatim rather than a framed entry. */
+export function estimateTextTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+/** Advisory per-scope injection budget (§4.3(2), the §3.1 example's `cap`). P3 REPORTS against
+ *  it at write time; P4 owns the enforcing render (greedy, least-specific dropped first). */
+export const MEMORY_SCOPE_TOKEN_CAP = 2048;
+
+/** Ceiling on the full-body (`pinned`) part of the startup block, across every cell of the chain.
+ *
+ *  The per-scope cap bounds a cell; this bounds the PROMPT, whatever the chain looks like. #3508 cut
+ *  it from 6144 to 1024: startup memory is a few global rules, and everything else loads on demand
+ *  (on-touch area memory, relay_project_search). A pinned rule past it demotes to an index line. */
+export const MEMORY_TOTAL_TOKEN_CAP = 1024;
+
+/** Cap on the INDEX SECTION of the startup block (#1979 I1), its own allowance beside
+ *  `MEMORY_TOTAL_TOKEN_CAP`. Since #3508 only `pinned` entries reach startup, so the index holds just
+ *  the pinned rules the body ceiling demoted; past it they keep a hookless id line (#3525) rather
+ *  than vanish, and only a natively-`indexed` entry is omitted (reason `index`). Overridable per compose (`indexTokenBudget`). */
+export const MEMORY_INDEX_TOKEN_CAP = 256;
+
+/** Max title length, in CHARACTERS, for a memory entry (#1979 Wave A I2).
+ *
+ *  Enforced at WRITE time (the `relay_store_memory` tool) so a new title cannot exceed it, and at
+ *  RENDER time (the index headline) so a legacy over-long title cannot bloat an index row. A title
+ *  is a hook, not the entry; 120 chars is generous for one and still bounds the row. */
+export const MEMORY_MAX_TITLE_CHARS = 120;
+
+/** Tokens of the global ceiling RESERVED for the `base` cell (#1602 residual).
+ *
+ *  The ceiling is spent most-specific-cell-first, which is the right drop direction — but a
+ *  well-stocked `host` or `provider` cell could then spend all of it and evict the operator's
+ *  own base memory, which under #559 had a budget of its own that nothing else could touch. A
+ *  reservation restores that floor: the non-base cells are admitted against `total − reserved`,
+ *  where `reserved` is what base can actually use (never more than base demands, and never more
+ *  than base's own per-scope cap). Base then spends the full ceiling, so an under-stocked base
+ *  cell gives its unused reservation straight back to the more specific cells. */
+export const MEMORY_BASE_TOKEN_FLOOR = 2048;
+
+/** Cut text to an allowance of estimated tokens, marking the cut. "" when nothing fits.
+ *
+ *  The inverse of `estimateTextTokens`, and deliberately its arithmetic read backwards (chars =
+ *  tokens × 4, one reserved for the ellipsis): a truncation measured by a different rule than the
+ *  budget that triggered it can cut to something the budget still rejects. */
+export function cutToTokens(text: string, allowanceTokens: number): string {
+  const chars = allowanceTokens * 4 - 1;
+  if (chars <= 0) return "";
+  return `${text.slice(0, chars)}…`;
+}
+
+/** Cap on ONE boundary-capture clause (#1565 P5.2, §10.2).
+ *
+ *  Same hazard as the preface cap below, at a seam with less slack: these two slugs are
+ *  dashboard-editable text that rides INSIDE the continuation envelope and the context advisory —
+ *  payloads whose whole job is to carry an agent's working state across a boundary. An unbounded
+ *  clause would compete with the very state it is asking about. One sentence or two is the
+ *  designed size (§10.2); this is roughly four times that, so only an accident hits it. */
+export const MEMORY_CAPTURE_CLAUSE_TOKEN_CAP = 256;
+
+/** Cap on the whole INSTRUCTION preface of the block (#1565 P5.1, §10.1).
+ *
+ *  Charged OUTSIDE the per-cell budgets and outside the whole-block ceiling, deliberately: the
+ *  preface is dashboard-editable text, so an operator (or a well-meaning agent) could otherwise
+ *  make the charter big enough to evict the very rules it is telling the agent to write. An
+ *  instruction is not an entry and must never compete with one — so it gets its own bound, and
+ *  overrun is TRUNCATED and reported (reason `instruction`) rather than allowed to spill. */
+export const MEMORY_INSTRUCTION_TOKEN_CAP = 512;
+
+/** Full-body allowance of one on-touch area block (#3410): bodies are spent first, pinned then newest. */
+export const AREA_MEMORY_BODY_TOKEN_CAP = 400;
+
+/** `[id] title` allowance of one on-touch area block (#3410), spent after the bodies; the rest is a count. */
+export const AREA_MEMORY_INDEX_TOKEN_CAP = 150;

package/src/merge-drain.ts

@@ -0,0 +1,101 @@
+// #2102/#2148 — the deploy-restart interlock's DRAIN SIGNAL.
+//
+// A CD-driven relay restart co-deploys server+orchestrator, killing whichever `workspace.merge` an
+// executor happens to be running at that instant. #2094 Fix A reclaims that orphan in seconds, so the
+// strand is no longer permanent — but the merge attempt itself is still wasted, and under a burst of
+// lands every deploy tick can burn another one. This is the fact a deploy driver polls so it can hold
+// its restart until the merge lease drains (BOUNDED — see scripts/cd-merge-drain.ts; the wait always
+// falls through to the deploy, and #2094 covers whatever it does not catch).
+//
+// This module composes two halves that deliberately live apart: the command-lifecycle query
+// (`activeWorkspaceMergeCommands`, commands-db.ts — which must not import the orchestrator DB) and
+// the executor-liveness discriminator #2094 already built (`commandExecutorConfirmedGone`, a pure
+// predicate over caller-resolved owner facts). This is the one place that can reach both.
+import { activeRestartSensitiveCommands, commandExecutorConfirmedGone, getCommandClaimOwnerToken, type CommandExecutorOwner } from "./commands-db.ts";
+// The specific module, NOT the src/db barrel: the barrel re-exports the reader-op registry that
+// reaches back into this file, and importing it here would close that cycle (src/circular-deps.test.ts).
+import { listOrchestrators } from "./db/orchestrators.ts";
+import type { Command, Orchestrator } from "./types.ts";
+
+/** The read-only deploy-restart interlock signal. The legacy name remains API-compatible. */
+export interface MergeDrainStatus {
+  /** True iff a deploy restart would kill a claimed merge or pre-registration spawn. */
+  draining: boolean;
+  activeMerges: number;
+  activeSpawns: number;
+  /** `updated_at` of the longest-running active merge: the time of its LAST status write (the claim,
+   *  or the accepted→running transition), not necessarily the claim itself. Diagnostic only — it lets
+   *  an operator see how long a merge has been running against its own lease. Null when none active. */
+  oldestActiveSince: number | null;
+  observedAt: number;
+}
+
+/**
+ * #2094 Fix A — resolve the owning-orchestrator liveness facts `commandExecutorConfirmedGone` needs. A
+ * `workspace.merge` command targets the owner's AGENT id (workspace-merge.ts createCommand target =
+ * onlineOwner.agentId); `meta.claimInstanceId` is the fingerprint of the owner PROCESS's current
+ * claimOwnerToken (reconnect-stable; see the helper's docstring in commands-db.ts). Returns null when
+ * the target host has no live record at all.
+ *
+ * Shared, not copied: the auto-merge watchdog's reclaim (#2094) and this drain signal must agree on
+ * what "the executor that claimed this command is gone" means, or a deploy would hold for a merge the
+ * watchdog has already written off.
+ */
+export function resolveCommandExecutorOwner(command: Command, orchestrators: Orchestrator[]): CommandExecutorOwner | null {
+  const owner = orchestrators.find((orch) => orch.agentId === command.target);
+  if (!owner) return null;
+  return { status: owner.status, claimInstanceId: typeof owner.meta?.claimInstanceId === "string" ? owner.meta.claimInstanceId : undefined };
+}
+
+/**
+ * Is a `workspace.merge` in flight right now — one that a deploy restart would kill AND that could
+ * still finish if we waited? Read-only; the candidate set is the fleet's concurrent merges (single
+ * digits), so this is one indexed query plus one orchestrator read.
+ *
+ * The executor-liveness exclusion is what makes this a signal rather than just a timer. Without it,
+ * a merge that a PREVIOUS deploy already killed sits `running` and within-lease until the watchdog
+ * reclaims it — so the very next CD tick would read `draining: true` for a merge that can never
+ * drain and burn the entire ceiling, every tick, for as long as the restart loop continues. Reusing
+ * #2094's discriminator means a provably-orphaned merge stops holding deploys the moment it is
+ * provable.
+ *
+ * KNOWN RESIDUAL WINDOW, and it is deliberate: `commandExecutorConfirmedGone` is conservative by
+ * design — it only says "gone" once the replacement orchestrator generation has been up past
+ * EXECUTOR_ORPHAN_GRACE_MS (90s), and every unresolvable input (no owner record, an offline/stale
+ * owner, a missing claim fingerprint) returns false. So for roughly the first grace period after a
+ * restart, a merge that deploy N killed still reads as draining and one deploy may hold for it. That
+ * costs a bounded wait, never a stall, and the conservative direction is the correct one: mistaking a
+ * genuinely-running land gate for a corpse would restart the fleet straight through it.
+ *
+ * The signal is therefore an OPTIMISTIC hint, never a guarantee — a `pending` merge claimed one tick
+ * after the poll still gets killed. That residual is exactly what #2094's fast reclaim covers, and it
+ * is why this interlock is a churn-reducer rather than a correctness mechanism.
+ */
+export function workspaceMergeDrainStatus(now: number = Date.now()): MergeDrainStatus {
+  const candidates = activeRestartSensitiveCommands(now);
+  const mergeCandidates = candidates.filter((command) => command.type === "workspace.merge");
+  const spawnCandidates = candidates.filter((command) => command.type === "agent.spawn");
+  // Read the roster ONCE, and only when there is something to judge.
+  const orchestrators = mergeCandidates.length + spawnCandidates.length > 0 ? listOrchestrators() : [];
+  const stillOwned = (command: Command) => !commandExecutorConfirmedGone(
+    command,
+    getCommandClaimOwnerToken(command.id),
+    resolveCommandExecutorOwner(command, orchestrators),
+    now,
+  );
+  // A replacement registration is not process-tree proof for the cgroup controller. The explicit
+  // legacy-unfenced compatibility mode retains current-main's liveness exclusion; only a cgroup land
+  // waits for ownership-aware positive death/completion regardless of registration generation.
+  const activeMerges = mergeCandidates.filter((command) =>
+    command.landingContainmentMode === "legacy-unfenced-v0" ? stillOwned(command) : true,
+  );
+  const activeSpawns = spawnCandidates.filter(stillOwned);
+  const oldest = [...activeMerges, ...activeSpawns].sort((a, b) => a.updatedAt - b.updatedAt)[0];
+  return {
+    draining: activeMerges.length + activeSpawns.length > 0,
+    activeMerges: activeMerges.length,
+    activeSpawns: activeSpawns.length,
+    oldestActiveSince: oldest?.updatedAt ?? null,
+    observedAt: now,
+  };
+}

package/src/merge-pause-maintenance.ts

@@ -0,0 +1,19 @@
+import { REAP_INTERVAL_MS } from "./config";
+import { releaseExpiredMergePauses } from "./db";
+
+export const MERGE_PAUSE_MAINTENANCE_JOB = {
+  id: "merge-pause-expiration",
+  critical: false,
+  title: "Merge pause expiration",
+  description: "Release expired repo/base auto-merge pauses.",
+  intervalMs: REAP_INTERVAL_MS,
+  runOnStart: true,
+  // #1819 — SYNCHRONOUS, and ONE atomic statement: `releaseExpiredMergePauses` is a single UPDATE …
+  // RETURNING. There is no interior checkpoint to add — splitting it would mean splitting a
+  // transaction — so the pre-flight check is the whole of its cooperation. It cannot overrun a
+  // deadline in any realistic fleet; if it ever does, the fix is #1809 offload, not more checks.
+  handler(context: { signal?: AbortSignal }) {
+    if (context.signal?.aborted) return { releasedMergePauseIds: [], aborted: true };
+    return { releasedMergePauseIds: releaseExpiredMergePauses() };
+  },
+};

package/src/message-visibility.ts

@@ -0,0 +1,50 @@
+// #3567 D6 — which human may read which message. A signed-in non-admin sees messages to and from
+// their own sink, never another human's; admins and machine callers (agents, integrations) see all.
+// One predicate for inbox reads, the thread view and the SSE stream (messages and notifications).
+import { canonicalHumanAgentId, isHumanAgentId } from "@humwick/sdk";
+import { visibleAgentIds, type ViewerScope } from "./db/viewer-scope";
+import type { Message, RelayNotification } from "./types";
+
+/** The human reading: their canonical sink (`user` for the default user) and whether they see all. */
+export type MessageViewer = ViewerScope;
+
+function partyVisible(party: string | undefined, sink: string): boolean {
+  return !party || !isHumanAgentId(party) || canonicalHumanAgentId(party) === sink;
+}
+
+/** True when `viewer` may read `msg`. A null viewer is a machine caller (no human filter). */
+export function messageVisibleTo(viewer: MessageViewer | null | undefined, msg: Pick<Message, "from" | "to" | "resolvedToAgent">, visibleIds?: ReadonlySet<string>): boolean {
+  if (!viewer || viewer.seesAll) return true;
+  if (!partyVisible(msg.from, viewer.sink) || !partyVisible(msg.to, viewer.sink)) return false;
+  const endpoints = [msg.from, ...(msg.to ? [msg.to] : []), ...(msg.resolvedToAgent ? [msg.resolvedToAgent] : [])];
+  return visibleIds ? endpoints.some((id) => visibleIds.has(id)) : visibleAgentIds(viewer, endpoints).length > 0;
+}
+
+/** Resolve endpoint ownership once per page, then preserve its original order. */
+export function visibleMessages<T extends Pick<Message, "from" | "to" | "resolvedToAgent">>(viewer: MessageViewer | null | undefined, messages: T[]): T[] {
+  if (!viewer || viewer.seesAll) return messages;
+  const endpoints = new Set(messages.flatMap((message) => [message.from, ...(message.to ? [message.to] : []), ...(message.resolvedToAgent ? [message.resolvedToAgent] : [])]));
+  const visible = new Set(visibleAgentIds(viewer, [...endpoints]));
+  return messages.filter((message) => messageVisibleTo(viewer, message, visible));
+}
+
+/** True when `sink` is a human sink `viewer` may not read (a 403, not an empty inbox). */
+export function isOtherHumanSink(viewer: MessageViewer | null | undefined, sink: string): boolean {
+  return Boolean(viewer && !viewer.seesAll && isHumanAgentId(sink) && canonicalHumanAgentId(sink) !== viewer.sink);
+}
+
+/** Notifications are personal: one addressed to a human reaches only that human's dashboards. */
+export function notificationVisibleTo(viewer: MessageViewer | null | undefined, notification: Pick<RelayNotification, "recipient">): boolean {
+  return !viewer || viewer.seesAll || !notification.recipient || canonicalHumanAgentId(notification.recipient) === viewer.sink;
+}
+
+/** Activity rows that echo a message (its body, its parties) follow that message's visibility. */
+export function activityVisibleTo(
+  viewer: MessageViewer | null | undefined,
+  activity: { messageId?: number | null },
+  messageOf: (id: number) => Pick<Message, "from" | "to" | "resolvedToAgent"> | null | undefined,
+): boolean {
+  if (!viewer || viewer.seesAll || !activity.messageId) return true;
+  const message = messageOf(activity.messageId);
+  return !message || messageVisibleTo(viewer, message);
+}

package/src/messaging-policy.ts

@@ -0,0 +1,94 @@
+// #2968 — the ONE agent-to-agent messaging rule. Messaging is a property of the agent's profile:
+// `open` by default (any agent may message any agent), `isolated` for `isolated-research`, whose
+// agents only talk within their own run and never receive fan-out. Send authorization
+// (services/send-message.ts), every fan-out matcher and the delivery predicate (poll SQL, bus/SSE
+// matcher, store-ahead rebinding) read it from here, so no spawn path or token remembers a target list.
+import { isReservedAgentId, LEGACY_HUMAN_AGENT_ID, USER_NAMESPACE_PREFIX } from "@humwick/sdk";
+import { getAgentProfile } from "./config-store";
+// The run fields (teamId, spawnedBy) are durable columns, so the persisted read is enough; db/agents
+// would close an import cycle through agent-ref.
+import { getPersistedAgentCard, listPersistedAgentCards } from "./db/agent-card-read.ts";
+import type { AgentCard, AgentProfileMessagingPolicy, Message, TokenConstraints } from "./types";
+
+export type MessagingParty = Pick<AgentCard, "id" | "teamId" | "spawnedBy"> & { meta?: AgentCard["meta"] };
+
+// Matchers run per (message × connected agent); profile resolution builds and validates the profile,
+// so memoize per profile name briefly. A profile edit takes effect within the TTL.
+const POLICY_TTL_MS = 2_000;
+const POLICY_CACHE_MAX = 256;
+const policyCache = new Map<string, { at: number; policy: AgentProfileMessagingPolicy }>();
+
+export function messagingPolicyForProfile(profileName: unknown, now = Date.now()): AgentProfileMessagingPolicy {
+  if (typeof profileName !== "string" || !profileName) return "open";
+  const cached = policyCache.get(profileName);
+  if (cached && now - cached.at < POLICY_TTL_MS) return cached.policy;
+  const policy = getAgentProfile(profileName)?.value.messaging ?? "open";
+  if (policyCache.size >= POLICY_CACHE_MAX) policyCache.clear();
+  policyCache.set(profileName, { at: now, policy });
+  return policy;
+}
+
+export function resetMessagingPolicyCache(): void {
+  policyCache.clear();
+}
+
+/** `meta.profile` is server-pinned at registration (register-agent.ts), so it is a trusted operand. */
+export function isMessagingIsolated(agent: Pick<AgentCard, "meta"> | null | undefined): boolean {
+  return messagingPolicyForProfile(agent?.meta?.profile) === "isolated";
+}
+
+const FANOUT_PREFIXES = ["tag:", "cap:", "capability:", "team:"];
+
+/** Group fan-out an isolated agent never receives. `label:` is addressing, gated at send time instead. */
+export function isGroupFanoutTarget(target: string): boolean {
+  return target === "broadcast" || FANOUT_PREFIXES.some((prefix) => target.startsWith(prefix));
+}
+
+export function agentReceivesGroupFanout(agent: Pick<AgentCard, "meta"> | null | undefined): boolean {
+  return !isMessagingIsolated(agent);
+}
+
+/** The agent behind a signed caller identity, with its messaging posture. The signed
+ * `constraints.profile` counts when it is isolated, so a card that lost `meta.profile` cannot open an
+ * isolated agent. */
+export function messagingPartyFor(
+  id: string,
+  constraints: TokenConstraints | undefined,
+  card: Pick<AgentCard, "teamId" | "spawnedBy" | "meta"> | null | undefined,
+): MessagingParty {
+  const signedProfile = constraints?.profile;
+  const profile = isMessagingIsolated({ meta: { profile: signedProfile } }) ? signedProfile : card?.meta?.profile;
+  return { id, teamId: card?.teamId, spawnedBy: card?.spawnedBy ?? constraints?.spawnedBy, meta: { ...card?.meta, profile } };
+}
+
+/** The agent and every persisted agent in its run. */
+export function messagingRunAgentIds(agent: MessagingParty): string[] {
+  return [agent.id, ...listPersistedAgentCards().filter((other) => inSameMessagingRun(other, agent)).map((other) => other.id)];
+}
+
+/** Same run: spawner and child, or a shared team or spawner. */
+export function inSameMessagingRun(a: MessagingParty | null | undefined, b: MessagingParty | null | undefined): boolean {
+  if (!a || !b) return false;
+  return a.id === b.spawnedBy
+    || b.id === a.spawnedBy
+    || Boolean(a.teamId && a.teamId === b.teamId)
+    || Boolean(a.spawnedBy && a.spawnedBy === b.spawnedBy);
+}
+
+/** The delivery predicate: may this stored message reach `agent`? Evaluated where a message is bound
+ * to or read by a concrete agent, because a store-ahead `policy:`/`label:` send had no recipient to
+ * check at send time. Reserved senders (system, the operator, automations) keep their direct lane. */
+export function messageMayReachAgent(msg: Pick<Message, "from" | "to">, agent: AgentCard | null | undefined): boolean {
+  if (!isMessagingIsolated(agent)) return true;
+  if (isGroupFanoutTarget(msg.to)) return false;
+  return msg.from === agent!.id || isReservedAgentId(msg.from) || inSameMessagingRun(getPersistedAgentCard(msg.from), agent);
+}
+
+/** messageMayReachAgent's sender rule as a poll-query clause (filtering before `LIMIT`), or null for
+ * an open agent. The reserved operands are the SQL form of isReservedAgentId. */
+export function isolatedSenderSql(agent: AgentCard | null | undefined, column: string, params: unknown[]): string | null {
+  if (!agent || !isMessagingIsolated(agent)) return null;
+  const run = messagingRunAgentIds(agent);
+  params.push(...run, "system", LEGACY_HUMAN_AGENT_ID, `${USER_NAMESPACE_PREFIX}%`);
+  return `(${column} IN (${run.map(() => "?").join(", ")}) OR ${column} IN (?, ?) OR ${column} LIKE ?)`;
+}