agent-relay-server 0.121.0 → 0.121.2

package/src/services/spawn-agent.ts

@@ -23,7 +23,7 @@
 // shared `buildSpawnCommand`/`buildManagedSpawnParams` payload home directly. Folding
 // them through `spawnAgent(systemCtx)` is a clean belt-and-suspenders follow-up (#342),
 // deliberately out of scope here — this slice converges the two external TRANSPORTS.
-import type { SpawnProvider } from "agent-relay-sdk";
+import type { ReportVerbosity, SpawnProvider } from "agent-relay-sdk";
 import { DEFAULT_USER_ID, errMessage, isRecord, stringValue } from "agent-relay-sdk";
 import { statSync } from "node:fs";
 import { dirname, resolve } from "node:path";
@@ -211,6 +211,12 @@ export interface SpawnAgentInput {
    * Explicit true is preserved in the command payload for compatibility only.
    */
   expectReply?: boolean;
+  /**
+   * #1037 — per-spawn report-up verbosity (`quiet` default | `normal` | `verbose`). Persisted in
+   * the spawn command params and stamped onto the child's meta at registration, where the lineage
+   * report-up delivery gate reads it. Absent = `quiet`.
+   */
+  reportVerbosity?: ReportVerbosity;
   tags?: string[];
   capabilities?: string[];
   providerArgs?: string[];
@@ -249,6 +255,8 @@ export interface SpawnAgentResult {
   agentId: string | null;
   registered: boolean;
   command: Command;
+  /** #1033 — the durable Task this spawn is bound to (explicit taskId or auto-scaffolded), when any. */
+  taskId?: number;
   task?: { id: number; autoScaffolded: boolean; nudge: string };
 }
 
@@ -332,7 +340,16 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
 
   // #255/#328 — bias the host to the caller's own machine when neither an explicit
   // orchestratorId nor a cwd pins it, so an agent spawning a helper lands on its own host.
-  const orchestrator = selectSpawnOrchestrator(input.provider, input.orchestratorId, requestedCwd, caller?.machine ?? lineageAgent?.machine);
+  // #1034 — pass the token's orchestrator allow-set so host selection can NEVER land on a host
+  // the caller isn't authorized for (which would then trip assertResourceAllowed with a
+  // misleading `-32001 component token cannot access this resource` — the concurrent-spawn flap).
+  const orchestrator = selectSpawnOrchestrator(
+    input.provider,
+    input.orchestratorId,
+    requestedCwd,
+    caller?.machine ?? lineageAgent?.machine,
+    ctx.constraints?.orchestrators,
+  );
 
   // #308 §3 — an explicit cwd must resolve within the TARGET host's base dir (a path valid on
   // your host may not exist on a different orchestrator).
@@ -638,6 +655,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
       resumeWorkspace: input.resumeWorkspace,
       acquisition,
       ...(expectReply ? { expectReply } : {}),
+      ...(input.reportVerbosity ? { reportVerbosity: input.reportVerbosity } : {}),
       policyName: input.policyName,
       spawnRequestId,
       env,
@@ -727,6 +745,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
     agentId,
     registered: agentId !== null,
     command,
+    ...(input.taskId !== undefined ? { taskId: input.taskId } : {}),
     ...(autoScaffoldedTask ? { task: autoScaffoldedTask } : {}),
   };
 }

package/src/services/task-semantic-events.ts

@@ -1,6 +1,7 @@
 import { getAgent } from "../db";
 import { addSubscription } from "../db/notification-subscriptions";
 import { emitRelayEvent } from "../events";
+import { hasRecentLifecycleSignal, taskSignalKey } from "../lifecycle-signal-registry";
 import { notifySystemMessage } from "../notify";
 import type { NotificationScope, NotificationType } from "../notification-types";
 import { routeNotification } from "../notification-router";
@@ -216,7 +217,18 @@ function dedupeRecipients(recipients: Array<{ agentId: string; matchedRule: stri
   return out;
 }
 
+// #1032b — a status pulse is redundant when a first-class lifecycle event (agent.ready, the lineage
+// report-up, branch.landed/merge) already conveyed this task's state to this recipient. Suppress it
+// rather than waking the spawner a second time for the same fact.
+// #1038 — keyed by the pulse's own transition: a progress signal (report-up / ready) supersedes only
+// a redundant `working` pulse, never a later DISTINCT-state transition (committed / landed / done)
+// for the same task within the TTL.
+function pulseSupersededByLifecycle(agentId: string, taskId: number, transition: TaskSemanticTransition): boolean {
+  return hasRecentLifecycleSignal(agentId, taskSignalKey(taskId, transition));
+}
+
 function enqueueStatusPulse(agentId: string, item: StatusPulseDigestItem): void {
+  if (pulseSupersededByLifecycle(agentId, item.taskId, item.transition)) return; // #1032b/#1038
   const batch = statusPulseBatches.get(agentId) ?? { items: [] };
   batch.items.push(item);
   if (!batch.timer) {
@@ -233,7 +245,11 @@ export function flushTaskStatusPulses(agentId?: string): void {
     if (batch.timer) clearTimeout(batch.timer);
     statusPulseBatches.delete(target);
     if (batch.items.length === 0) continue;
-    const items = compactStatusPulseItems(batch.items);
+    // #1032b — a lifecycle event that fired AFTER these items were queued (but within the batch
+    // window) also supersedes them; drop those before flushing so the digest carries only news.
+    const fresh = batch.items.filter((item) => !pulseSupersededByLifecycle(target, item.taskId, item.transition));
+    if (fresh.length === 0) continue;
+    const items = compactStatusPulseItems(fresh);
     notifySystemMessage(target, {
       subject: `Task status pulse (${items.length})`,
       body: taskStatusPulseBody(items),

package/src/spawn-command.ts

@@ -109,6 +109,8 @@ interface BuildSpawnCommandOptions {
    * registration from the persisted spawn command params.
    */
   expectReply?: boolean;
+  /** #1037 — per-spawn report-up verbosity, persisted so registration can stamp it onto child meta. */
+  reportVerbosity?: string;
   profile?: string;
   agentProfile?: unknown;
   headless?: boolean;
@@ -174,6 +176,7 @@ export function buildSpawnCommand(opts: BuildSpawnCommandOptions): Record<string
     ...def(opts.reviewer, "reviewer"),
     ...def(opts.taskId, "taskId"),
     ...def(opts.expectReply, "expectReply"),
+    ...def(opts.reportVerbosity, "reportVerbosity"),
     ...def(opts.headless, "headless"),
     ...def(opts.policyName, "policyName"),
     ...def(opts.automationId, "automationId"),

package/src/spawn-targets.ts

@@ -500,7 +500,25 @@ export function selectSpawnOrchestrator(
   orchestratorId?: string,
   cwd?: string,
   preferHost?: string,
+  /**
+   * #1034 — the caller token's `constraints.orchestrators` allow-set. When present, host
+   * SELECTION must stay INSIDE it: never silently fall back to a host the token isn't
+   * authorized for. Previously, when neither an explicit id nor a cwd nor a resolvable
+   * `preferHost` pinned the host (e.g. the caller's `machine` was transiently unset, or the
+   * caller's own host briefly flapped offline), selection grabbed `candidates[0]` — an
+   * arbitrary online host. If that host was outside the token's allow-set, the downstream
+   * `assertResourceAllowed` gate then rejected the spawn with a MISLEADING `-32001 component
+   * token cannot access this resource`, which cleared "seconds later" once the caller's host
+   * re-appeared (issue #1034). Filtering candidates to the allow-set makes selection
+   * authz-consistent: for the common single-authorized-host token it deterministically returns
+   * that host regardless of transient machine/cwd resolution, so concurrent spawns no longer
+   * spuriously reject; when the authorized host is genuinely offline, the error is an honest
+   * "authorized host offline", not a confusing authz denial. Undefined/empty = no filtering
+   * (admin `*` tokens, byte-identical to before).
+   */
+  allowedOrchestratorIds?: string[],
 ): Orchestrator {
+  const allowSet = allowedOrchestratorIds?.length ? new Set(allowedOrchestratorIds) : null;
   if (orchestratorId) {
     const orchestrator = getOrchestrator(orchestratorId);
     if (!orchestrator) throw new McpNotFoundError(`orchestrator ${orchestratorId} not found`);
@@ -515,7 +533,9 @@ export function selectSpawnOrchestrator(
     }
     return orchestrator;
   }
-  const candidates = listOrchestrators().filter((item) => item.status === "online" && item.providers.includes(provider));
+  const candidates = listOrchestrators().filter(
+    (item) => item.status === "online" && item.providers.includes(provider) && (!allowSet || allowSet.has(item.id)),
+  );
   if (cwd) {
     const match = candidates.find((item) => isPathWithinBase(cwd, item.baseDir));
     if (match) return match;
@@ -530,6 +550,11 @@ export function selectSpawnOrchestrator(
   }
   const orchestrator = candidates[0];
   if (!orchestrator) {
+    // #1034 — when the token's host allow-set is what emptied the candidate list, say so plainly
+    // (the caller's authorized host is offline) instead of the generic "no orchestrator" miss.
+    if (allowSet) {
+      throw new McpNotFoundError(`no online orchestrator authorized for this token runs provider '${provider}'. Your token is scoped to host(s): ${[...allowSet].join(", ")} — check that one is online (call relay_spawn_targets for the live matrix).`);
+    }
     throw new McpNotFoundError(`no online orchestrator runs provider '${provider}'. Available: ${spawnAlternatives()} (call relay_spawn_targets for the live matrix).`);
   }
   return orchestrator;

package/src/sse.ts

@@ -1,5 +1,5 @@
 import { getAgent, getOrchestrator, matchingDeliveryAgents, onWorkspaceChange, sendMessageWithResult, setChannelSubscriberProbe } from "./db";
-import { getOldestOutboxCursor, getOutboxCursor, replayEvents, type BusEvent } from "./bus-outbox";
+import { getOutboxCursor, hasReplayGap, replayEventsSlice, type BusEvent } from "./bus-outbox";
 import { projectAgentStatusData } from "./agent-card-projection";
 import { emitRelayEvent, subscribeRelayEvents, type RelayEvent } from "./events";
 import { messageMatchesAgent, targetMatchesAgent } from "./agent-ref";
@@ -348,8 +348,7 @@ interface ReplayPlan {
 function replayPlan(lastEventId: number): ReplayPlan {
   const since = Number.isSafeInteger(lastEventId) && lastEventId > 0 ? lastEventId : 0;
   if (since === 0) return { requested: false, since: 0, available: false, gap: false };
-  const oldest = getOldestOutboxCursor();
-  const gap = oldest > 0 && oldest > since + 1;
+  const gap = hasReplayGap(since);
   return { requested: true, since, available: !gap, gap };
 }
 
@@ -359,9 +358,18 @@ function replayEventsToConnection(conn: Connection | undefined, plan: ReplayPlan
     send(conn, "replay.gap", { since: plan.since }, getOutboxCursor());
     return;
   }
+  // Drain the whole backlog in pages. A single capped replay dropped everything past the first 500
+  // events between the client's cursor and the outbox head (#1022 F1) — the SSE stream then went
+  // live from the head with no signal, so the tail was lost. Loop until the page is not truncated.
   const agentCache = new Map<string, AgentCard | null>();
-  for (const event of replayEvents(plan.since)) {
-    sendReplayEvent(conn, outboxToRelayEvent(event), agentCache);
+  let since = plan.since;
+  for (;;) {
+    const slice = replayEventsSlice(since);
+    for (const event of slice.events) {
+      sendReplayEvent(conn, outboxToRelayEvent(event), agentCache);
+    }
+    if (!slice.truncated) break;
+    since = slice.lastSeq;
   }
 }
 

package/src/workspace-auto-merge.ts

@@ -43,6 +43,7 @@ import { settleWorkspaceCommand } from "./workspace-command-settle";
 import { CLEAR_MERGE_NO_PROGRESS, MAX_NO_PROGRESS_MERGE_ATTEMPTS, mergeNoProgressCount, noteMergeNoProgress } from "./workspace-merge-progress";
 import { workspaceOwnerOrchestrator } from "./workspace-host";
 import { workspaceActiveClaim } from "./workspace-claim";
+import { notifyWorkspaceHumanEscalation } from "./workspace-human-escalation";
 import { DIRTY_WORKTREE_LAND_SKIP_REASON, READY_TO_LAND_STATUSES } from "./workspace-phase";
 import { fetchHostMergePreview } from "./workspace-probe";
 import type { Command, WorkspaceAutoMergePolicy, WorkspaceLandingPolicy, WorkspaceMergePreview, WorkspaceMergeStrategy, WorkspaceRecord } from "./types";
@@ -119,20 +120,33 @@ function autoMergeRequestOptions(ws: WorkspaceRecord): AutoMergeRequestOptions {
 // auto-provision the policy on the workspace-owning host, then queue a `policy:` wake
 // message (which also spawns the on-demand agent now via onMessageForPolicy). Honors a
 // per-workspace cooldown so a persistent conflict/behind row isn't re-pinged every sweep.
-// Returns the steward policy name on a fresh wake, or null (disabled / no owner / cooled down).
-export function wakeRepoSteward(ws: WorkspaceRecord, reason: string): string | null {
+// The result of trying to wake the managed steward (#1021 A1). `ok` carries the policy name
+// only when a steward is genuinely alive or was just spawned. On `!ok`, `cooldown` tells a
+// fresh failure (nothing spawned — the caller should advance the loop-breaker) apart from a
+// recent successful wake still inside its cooldown window (NOT a failure — leave it be).
+export type StewardWakeOutcome =
+  | { ok: true; policy: string }
+  | { ok: false; cooldown: boolean; error?: string };
+
+// Wake the managed per-host/repo steward for a workspace it should handle: auto-provision
+// the policy on the workspace-owning host, queue a `policy:` wake message, and spawn the
+// on-demand agent. Only reports `ok` when the spawn actually happened (or a steward was
+// already live) — a queued message alone is NOT a wake (#1021 A1). Honors a per-workspace
+// cooldown so a persistent conflict/behind row isn't re-pinged every sweep.
+export function wakeRepoSteward(ws: WorkspaceRecord, reason: string): StewardWakeOutcome {
   const meta = ws.metadata as Record<string, unknown>;
   const lastWoke = typeof meta.stewardWokenAt === "number" ? meta.stewardWokenAt : 0;
-  if (lastWoke && Date.now() - lastWoke < STEWARD_WAKE_COOLDOWN_MS) return null;
+  if (lastWoke && Date.now() - lastWoke < STEWARD_WAKE_COOLDOWN_MS) return { ok: false, cooldown: true };
   const ownerResult = stewardOwnerForWorkspace(ws);
   if ("error" in ownerResult) {
     patchWorkspaceMetadata(ws.id, { stewardWakeError: ownerResult.error, stewardWakeErrorAt: Date.now() });
-    return null;
+    return { ok: false, cooldown: false, error: ownerResult.error };
   }
   const policyName = ensureRepoSteward(ws.repoRoot, ownerResult.owner);
   if (!policyName) {
-    patchWorkspaceMetadata(ws.id, { stewardWakeError: "cannot spawn steward: steward policy could not be provisioned", stewardWakeErrorAt: Date.now() });
-    return null;
+    const error = "cannot spawn steward: steward policy could not be provisioned";
+    patchWorkspaceMetadata(ws.id, { stewardWakeError: error, stewardWakeErrorAt: Date.now() });
+    return { ok: false, cooldown: false, error };
   }
   // #640 — resolve the identity triangle so the steward isn't blind to the people-graph:
   // the workspace's branch agent (owner) and that agent's coordinator (owner's `spawnedBy`).
@@ -163,7 +177,16 @@ export function wakeRepoSteward(ws: WorkspaceRecord, reason: string): string | n
         payload: { kind: "workspace.steward-task", workspaceId: ws.id, repoRoot: ws.repoRoot, worktreePath: ws.worktreePath, branch: ws.branch, baseRef: ws.baseRef, status: ws.status, reason, ownerAgentId, coordinatorAgentId },
       },
     });
-    getLifecycleManager().onMessageForPolicy(policyName);
+    // #1021 A1 — the durable `policy:` obligation is enqueued above (it survives until a
+    // steward claims it), but a wake is only real if a steward actually spawned or is
+    // already live. If nothing spawned (host offline / provider error), record the error and
+    // report failure — do NOT stamp stewardWokenAt (which arms the cooldown) or claim a
+    // hand-off that never happened.
+    const spawn = getLifecycleManager().onMessageForPolicy(policyName);
+    if (!spawn.woke) {
+      patchWorkspaceMetadata(ws.id, { stewardWakeError: spawn.reason, stewardWakeErrorAt: Date.now() });
+      return { ok: false, cooldown: false, error: spawn.reason };
+    }
     patchWorkspaceMetadata(ws.id, {
       stewardWokenAt: Date.now(),
       stewardPolicy: policyName,
@@ -173,10 +196,11 @@ export function wakeRepoSteward(ws: WorkspaceRecord, reason: string): string | n
     });
     // #641/#642 — tell the owner which steward took over and proactively loop in its coordinator.
     notifyStewardHandoff({ workspace: ws, stewardId: policyName, coordinatorAgentId, reason });
-    return policyName;
+    return { ok: true, policy: policyName };
   } catch (e) {
-    patchWorkspaceMetadata(ws.id, { stewardWakeError: e instanceof Error ? e.message : "failed to wake steward", stewardWakeErrorAt: Date.now() });
-    return null;
+    const error = e instanceof Error ? e.message : "failed to wake steward";
+    patchWorkspaceMetadata(ws.id, { stewardWakeError: error, stewardWakeErrorAt: Date.now() });
+    return { ok: false, cooldown: false, error };
   }
 }
 
@@ -227,25 +251,36 @@ function escalateNoProgressMerge(ws: WorkspaceRecord): void {
   const { coordinatorAgentId } = resolveStewardIdentity(ws);
   const fallback = stewardFallbackTarget();
   const recipients = [...new Set([coordinatorAgentId, fallback, ws.ownerAgentId].filter((r): r is string => Boolean(r)))];
+  const subject = "Workspace can't auto-land — needs attention";
+  const body = renderTemplate("steward.merge-stall", {
+    branch: `\`${ws.branch ?? ws.id}\``,
+    repoRoot: ws.repoRoot,
+    attempts: String(MAX_NO_PROGRESS_MERGE_ATTEMPTS),
+    mergeError,
+    baseRef: ws.baseRef ?? "base",
+  });
+  const payload = { kind: "workspace.auto-merge-stuck", workspaceId: ws.id, repoRoot: ws.repoRoot, branch: ws.branch, baseRef: ws.baseRef, attempts: MAX_NO_PROGRESS_MERGE_ATTEMPTS, reason: mergeError };
+  let escalated = false;
   if (recipients.length) {
     routeNotification({
       type: "workspace.stranded_escalation",
       scope: { workspaceId: ws.id, repoRoot: ws.repoRoot, author: ws.ownerAgentId, parent: coordinatorAgentId ?? undefined },
       recipients,
       message: {
-        subject: "Workspace can't auto-land — needs attention",
-        body: renderTemplate("steward.merge-stall", {
-          branch: `\`${ws.branch ?? ws.id}\``,
-          repoRoot: ws.repoRoot,
-          attempts: String(MAX_NO_PROGRESS_MERGE_ATTEMPTS),
-          mergeError,
-          baseRef: ws.baseRef ?? "base",
-        }),
-        payload: { kind: "workspace.auto-merge-stuck", workspaceId: ws.id, repoRoot: ws.repoRoot, branch: ws.branch, baseRef: ws.baseRef, attempts: MAX_NO_PROGRESS_MERGE_ATTEMPTS, reason: mergeError },
+        subject,
+        body,
+        payload,
       },
     });
+    escalated = true;
+  } else {
+    const human = notifyWorkspaceHumanEscalation({ subject, body, payload, source: "workspace-auto-merge" });
+    escalated = human.accepted;
+    if (!human.accepted) {
+      console.warn(`[workspace-auto-merge] no-progress escalation for ${ws.id} had zero agent recipients and no human channel: ${human.reason ?? "unknown reason"}`);
+    }
   }
-  patchWorkspaceMetadata(ws.id, { autoMergeBackedOffAt: Date.now() });
+  if (escalated) patchWorkspaceMetadata(ws.id, { autoMergeBackedOffAt: Date.now() });
   createActivityEvent({
     clientId: `workspace-auto-merge-backoff-${ws.id}-${Date.now()}`,
     kind: "state",
@@ -349,6 +384,22 @@ async function landCandidates(
     const preview = await fetchFirstUsableMergePreview(ws, orchestrators);
     if (!preview) {
       previewUnavailable.push(ws.id);
+      // #1025 A5 — a lane whose preview is persistently unusable (owner host offline, the
+      // worktree path is gone, or every probe returns error/missing) used to exit here with
+      // ZERO side effects: no no-progress, no wake, no notify — a ready branch would strand
+      // silently forever. Give it the SAME no-progress/strand path as the unknown-merge-state
+      // lane so no status is escalation-blind: advance the loop-breaker, and once it crosses
+      // the cap, escalateNoProgressMerge fires the owner `landed-failure` wake + steward/
+      // coordinator escalation. A transient blip self-clears when a usable preview returns.
+      const held = patchWorkspaceMetadata(ws.id, {
+        ...noteMergeNoProgress(ws.metadata),
+        mergeError: "no online host returned a usable merge preview (owner offline, worktree missing, or probe error)",
+        lastPreviewUnavailableAt: Date.now(),
+      }) ?? ws;
+      if (mergeNoProgressCount(held.metadata) >= MAX_NO_PROGRESS_MERGE_ATTEMPTS) {
+        backedOff.push(ws.id);
+        escalateNoProgressMerge(held);
+      }
       continue;
     }
     const p = preview as WorkspaceMergePreview;
@@ -401,21 +452,26 @@ async function landCandidates(
         }
       }
       leftForSteward.push(ws.id);
-      let woke: string | null = null;
       if (stewardEnabled) {
-        woke = wakeRepoSteward(handoffWorkspace, p.conflict === true ? "conflict" : "merge state unknown");
-        if (woke) wokeStewards.push(woke);
-      }
-      if (stewardEnabled && !woke && p.conflict === true) {
-        const failedHandoff = patchWorkspaceMetadata(ws.id, {
-          ...noteMergeNoProgress(ws.metadata),
-          mergeError: "cannot spawn steward on the workspace owning host",
-          lastStewardWakeFailedAt: Date.now(),
-        }) ?? ws;
-        if (mergeNoProgressCount(failedHandoff.metadata) >= MAX_NO_PROGRESS_MERGE_ATTEMPTS) {
-          backedOff.push(ws.id);
-          escalateNoProgressMerge(failedHandoff);
-          continue;
+        const wake = wakeRepoSteward(handoffWorkspace, p.conflict === true ? "conflict" : "merge state unknown");
+        if (wake.ok) {
+          wokeStewards.push(wake.policy);
+        } else if (!wake.cooldown && p.conflict === true) {
+          // #1021 A1+A2 — a GENUINE wake failure (nothing spawned: host offline / provider
+          // error) now correctly yields !ok, so the conflict lane's loop-breaker advances and
+          // escalateNoProgressMerge becomes reachable. A cooldown means a steward WAS woken
+          // recently and is presumably working — that is not a failure, so don't count it (and
+          // don't mislabel the cooldown as a spawn failure in mergeError). Carry the real error.
+          const failedHandoff = patchWorkspaceMetadata(ws.id, {
+            ...noteMergeNoProgress(ws.metadata),
+            mergeError: wake.error ?? "cannot spawn steward on the workspace owning host",
+            lastStewardWakeFailedAt: Date.now(),
+          }) ?? ws;
+          if (mergeNoProgressCount(failedHandoff.metadata) >= MAX_NO_PROGRESS_MERGE_ATTEMPTS) {
+            backedOff.push(ws.id);
+            escalateNoProgressMerge(failedHandoff);
+            continue;
+          }
         }
       }
       if (p.conflict === true) {

package/src/workspace-escalation.ts

@@ -1,23 +1,43 @@
 import { stewardFallbackTarget } from "./config";
 import { routeNotification } from "./notification-router";
+import { raiseOperatorAlarm } from "./operator-alarm";
 import { resolveStewardIdentity } from "./steward-identity";
+import { notifyWorkspaceHumanEscalation } from "./workspace-human-escalation";
 import type { NotificationType } from "./notification-types";
 import type { WorkspaceRecord, WorkspaceStatus } from "./types";
 
 export const READY_TO_LAND_ESCALATION_STATUSES = new Set<WorkspaceStatus>(["ready", "review_requested"]);
 
-export function routeWorkspaceCustodyEscalation(input: {
+export interface WorkspaceCustodyEscalationInput {
   workspace: Pick<WorkspaceRecord, "id" | "repoRoot" | "branch" | "status" | "ownerAgentId">;
   type?: NotificationType;
   subject: string;
   body: string;
   payload: Record<string, unknown>;
   idempotencyKey?: string;
-}): string[] {
+}
+
+export function routeWorkspaceCustodyEscalation(input: WorkspaceCustodyEscalationInput): string[] {
   const { ownerAgentId, coordinatorAgentId } = resolveStewardIdentity(input.workspace);
   const fallback = stewardFallbackTarget();
   const recipients = [...new Set([ownerAgentId, coordinatorAgentId, fallback].filter((value): value is string => Boolean(value)))];
-  if (!recipients.length) return [];
+  if (!recipients.length) {
+    const payload = {
+      ...input.payload,
+      coordinatorAgentId,
+      ownerAgentId,
+      fallbackTarget: fallback || undefined,
+    };
+    const human = notifyWorkspaceHumanEscalation({
+      subject: input.subject,
+      body: input.body,
+      payload,
+      source: "workspace-custody",
+    });
+    if (human.accepted && human.channelId) return [human.channelId];
+    console.warn(`[workspace-escalation] zero agent recipients and no human channel for workspace ${input.workspace.id}: ${human.reason ?? "unknown reason"}`);
+    return [];
+  }
 
   routeNotification({
     type: input.type ?? "workspace.stranded_escalation",
@@ -43,3 +63,32 @@ export function routeWorkspaceCustodyEscalation(input: {
   });
   return recipients;
 }
+
+// Route a custody escalation, and if it resolves to ZERO reachable recipients — owner
+// exited, coordinator idle, no `AGENT_RELAY_WORKSPACE_STEWARD_FALLBACK` configured —
+// raise a louder operator-visible alarm instead of letting the caller silently record it
+// as "escalated" (#1025 C1/C4, same class as #1021 A4). A disk-only orphan (ownerAgentId
+// undefined) and most `review_requested` auto-abandons have no agent to page by default,
+// so without this the notice is swallowed and the strand loops in the dark. Returns the
+// (possibly empty) recipient list so the caller can still decide whether to stamp state.
+export function routeWorkspaceCustodyEscalationOrAlarm(
+  input: WorkspaceCustodyEscalationInput & { source: string },
+): string[] {
+  const { source, ...escalation } = input;
+  const targets = routeWorkspaceCustodyEscalation(escalation);
+  if (!targets.length) {
+    raiseOperatorAlarm({
+      clientId: `${escalation.idempotencyKey ?? `${escalation.workspace.id}:${escalation.subject}`}:no-recipients`,
+      source,
+      subject: escalation.subject,
+      detail: `${escalation.body} — no owner, coordinator, or fallback configured to escalate to. Configure AGENT_RELAY_WORKSPACE_STEWARD_FALLBACK or reclaim the worktree manually.`,
+      metadata: {
+        workspaceId: escalation.workspace.id,
+        repoRoot: escalation.workspace.repoRoot,
+        branch: escalation.workspace.branch,
+        status: escalation.workspace.status,
+      },
+    });
+  }
+  return targets;
+}

package/src/workspace-human-escalation.ts

@@ -0,0 +1,68 @@
+import { errMessage } from "agent-relay-sdk";
+import { stewardFallbackTarget } from "./config";
+import { getChannel } from "./db";
+import { relayEgressToChannel, relayNotifyNtfy } from "./mcp-egress-tools";
+import { getResolvedNotificationsConfig } from "./notification-settings-store";
+
+const DEFAULT_NTFY_CHANNEL_ID = "ntfy:default";
+const WARN = "no human-reachable escalation target - stranded workspaces will page nobody. Set AGENT_RELAY_WORKSPACE_STEWARD_FALLBACK or configure ntfy.";
+
+export interface WorkspaceHumanEscalationInput {
+  subject: string;
+  body: string;
+  payload?: Record<string, unknown>;
+  priority?: "min" | "low" | "default" | "high" | "urgent";
+  tags?: string[];
+  source?: string;
+}
+
+export interface WorkspaceHumanEscalationResult {
+  accepted: boolean;
+  channelId?: string;
+  reason?: string;
+}
+
+export function workspaceHumanEscalationChannelId(): string {
+  return getResolvedNotificationsConfig().humanEscalationChannelId.trim();
+}
+
+export function hasHumanEscalationChannel(): boolean {
+  const channelId = workspaceHumanEscalationChannelId();
+  return Boolean(channelId && getChannel(channelId));
+}
+
+export function hasHumanReachableEscalationTarget(): boolean {
+  return Boolean(stewardFallbackTarget() || hasHumanEscalationChannel());
+}
+
+export function warnIfNoHumanReachableEscalationTarget(log: (message: string) => void = console.warn): boolean {
+  if (hasHumanReachableEscalationTarget()) return false;
+  log(WARN);
+  return true;
+}
+
+export function notifyWorkspaceHumanEscalation(input: WorkspaceHumanEscalationInput): WorkspaceHumanEscalationResult {
+  const channelId = workspaceHumanEscalationChannelId();
+  if (!channelId) return { accepted: false, reason: "no human escalation channel configured" };
+  if (!getChannel(channelId)) return { accepted: false, reason: `human escalation channel ${channelId} is not registered` };
+
+  const event: Record<string, unknown> = {
+    title: input.subject,
+    body: input.body,
+    priority: input.priority ?? "urgent",
+    tags: input.tags ?? ["agent-relay", "workspace"],
+    ...(input.payload ? { relay: input.payload } : {}),
+    ...(input.source ? { source: input.source } : {}),
+  };
+
+  try {
+    if (channelId === DEFAULT_NTFY_CHANNEL_ID) {
+      relayNotifyNtfy(event);
+    } else {
+      relayEgressToChannel({ channelId, event });
+    }
+    return { accepted: true, channelId };
+  } catch (error) {
+    return { accepted: false, channelId, reason: errMessage(error) };
+  }
+}

package/src/workspace-merge.ts

@@ -144,6 +144,22 @@ export function withOwnerOnline<T extends { ownerAgentId?: string }>(workspace:
   return { ...workspace, ownerOnline: isOwnerAlive(workspace.ownerAgentId) };
 }
 
+// #1049 — process-level death, distinct from "offline". `offline` is set on a mere
+// heartbeat lapse (exactly what a relay self-stall fakes for a batch of LIVE agents,
+// the 2026-07-04 cascade). A genuine process exit is only known when the owning
+// orchestrator REPORTS it: it stamps `meta.lastExit` (routes/orchestrator.ts). So
+// require both offline AND a reported exit before treating the owner as gone — never
+// nuke/land a worktree on a heartbeat gap alone. Conservative by design: an unmanaged
+// agent with no orchestrator never gets `lastExit`, so it reads as maybe-alive and the
+// orphan reaper's land-safety + grace window handle its eventual cleanup instead.
+export function isOwnerProcessConfirmedGone(ownerAgentId: string | undefined): boolean {
+  if (!ownerAgentId) return false;
+  const agent = getAgent(ownerAgentId);
+  if (!agent || agent.status !== "offline") return false;
+  const meta = isRecord(agent.meta) ? agent.meta : undefined;
+  return Boolean(meta && meta.lastExit);
+}
+
 function workspaceOwnerHostKeys(workspace: WorkspaceRecord): Set<string> {
   const keys = new Set<string>();
   const owner = workspace.ownerAgentId ? getAgent(workspace.ownerAgentId) : undefined;

package/src/workspace-orphans.ts

@@ -30,7 +30,7 @@ import { isOwnerAlive, liveAgentCwds, worktreeInUseByLiveAgent } from "./workspa
 import { applyWorkspaceAction } from "./workspace-actions";
 import { workspaceOwnerOrchestrator } from "./workspace-host";
 import { UNLANDED_FLAG_COOLDOWN_MS, orphanGraceMs, orphanWorktreeReapEnabled, relayToken } from "./config";
-import { READY_TO_LAND_ESCALATION_STATUSES, routeWorkspaceCustodyEscalation } from "./workspace-escalation";
+import { READY_TO_LAND_ESCALATION_STATUSES, routeWorkspaceCustodyEscalationOrAlarm } from "./workspace-escalation";
 
 // Don't re-flag the same un-landed orphan every sweep — surface it once, then
 // stay quiet for this window. In-memory (keyed by worktree path) like the
@@ -425,7 +425,8 @@ export async function reapOrphanedWorktrees(): Promise<Record<string, unknown>>
         ? "uncommitted changes in the worktree"
         : `${orphan.unmergedAhead ?? orphan.ahead ?? "?"} un-landed commit(s)`;
     if (orphanHasWorkEvidence(orphan)) {
-      routeWorkspaceCustodyEscalation({
+      routeWorkspaceCustodyEscalationOrAlarm({
+        source: "workspace-orphan-reaper",
         workspace: { id: `orphan:${orphan.worktreePath}`, repoRoot: orphan.repoRoot, branch: orphan.branch, status: "review_requested", ownerAgentId: undefined },
         subject: "Stranded worktree needs attention",
         body: `${orphan.branch ?? orphan.worktreePath} in ${orphan.repoRoot} is orphaned and holds work that has not landed - ${detail}. Recover the commits before removing it.`,
@@ -456,7 +457,8 @@ export async function reapOrphanedWorktrees(): Promise<Record<string, unknown>>
       if (now - last < UNLANDED_FLAG_COOLDOWN_MS) continue;
       flaggedAt.set(key, now);
       if (workspaceNeedsCustodyEscalation(workspace, false)) {
-        routeWorkspaceCustodyEscalation({
+        routeWorkspaceCustodyEscalationOrAlarm({
+          source: "workspace-orphan-reaper",
           workspace,
           subject: "Workspace row has no worktree on disk",
           body: `Workspace \`${workspace.branch ?? workspace.id}\` in ${workspace.repoRoot} is ${workspace.status}, but its worktree ${workspace.worktreePath} is missing on disk. This was in Relay custody; recover or explicitly abandon it.`,
@@ -506,7 +508,8 @@ export async function reapOrphanedWorktrees(): Promise<Record<string, unknown>>
       autoAbandoned.push(workspace.id);
       flaggedAt.delete(key);
       if (workspaceNeedsCustodyEscalation(workspace, previewHasWorkEvidence(probe.kind === "preview" ? probe.preview : null))) {
-        routeWorkspaceCustodyEscalation({
+        routeWorkspaceCustodyEscalationOrAlarm({
+          source: "workspace-orphan-reaper",
           workspace,
           type: "workspace.auto_abandoned",
           subject: "Workspace auto-abandoned",
@@ -547,7 +550,8 @@ export async function reapOrphanedWorktrees(): Promise<Record<string, unknown>>
         ? `host could not confirm whether branch ${workspace.branch} has landed`
         : "host could not confirm whether recoverable branch work remains";
     if (workspaceNeedsCustodyEscalation(workspace, hasWorkEvidence)) {
-      routeWorkspaceCustodyEscalation({
+      routeWorkspaceCustodyEscalationOrAlarm({
+        source: "workspace-orphan-reaper",
         workspace,
         subject: "Missing-worktree workspace needs attention",
         body: `${workspace.id} in ${workspace.repoRoot} has no worktree on disk and cannot be auto-abandoned safely - ${detail}. Recover it, then abandon or clean it up explicitly.`,
@@ -657,7 +661,8 @@ export async function reapOrphanedWorktrees(): Promise<Record<string, unknown>>
         : `${preview?.unmergedAhead ?? preview?.ahead ?? "?"} un-landed commit(s)`;
     const hasWorkEvidence = previewHasWorkEvidence(preview);
     if (workspaceNeedsCustodyEscalation(workspace, hasWorkEvidence)) {
-      routeWorkspaceCustodyEscalation({
+      routeWorkspaceCustodyEscalationOrAlarm({
+        source: "workspace-orphan-reaper",
         workspace,
         subject: "Dead-owner worktree needs attention",
         body: `${workspace.branch ?? workspace.id} in ${workspace.repoRoot} is owned by gone agent ${workspace.ownerAgentId ?? "?"} and holds work that has not landed (${detail}). Recover the commits, then clean it up explicitly.`,