agent-relay-server 0.27.1 → 0.28.0

package/runner/src/adapter.ts

@@ -211,9 +211,19 @@ function isPersistedRelayMessage(message: Message): boolean {
   return Number.isSafeInteger(message.id) && message.id > 0;
 }
 
+// #283 — one-line nudge that replaces the reply-scaffold footer for notification-class
+// (replyExpected:false) messages. Deliberately tiny so a bloated context can't drown the
+// no-reply rule established at session start. Shared with the Claude delivery path.
+export const NOTIFICATION_NUDGE = "↪ Notification — no reply needed.";
+
+// A notification is a persisted message the server marked replyExpected:false.
+export function isNotificationMessage(message: Message): boolean {
+  return isPersistedRelayMessage(message) && message.replyExpected === false;
+}
+
 function latestReplyableMessage(messages: Message[]): Message | undefined {
   return messages
-    .filter((message) => isPersistedRelayMessage(message) && !isMemoryInjection(message) && !isReactionNotification(message))
+    .filter((message) => isPersistedRelayMessage(message) && !isMemoryInjection(message) && !isReactionNotification(message) && message.replyExpected !== false)
     .at(-1);
 }
 
@@ -316,6 +326,9 @@ export function providerMessageText(messages: Message[]): string {
       "If you already delivered the useful response through Relay, do not send a separate status-only confirmation.",
       "If multiple messages arrived together, cover them in one reply instead of answering each line separately.",
     ].join("\n"));
+  } else if (messages.some(isNotificationMessage)) {
+    // #283 — pure notification batch: no scaffold, just the one-line no-reply nudge.
+    sections.push(NOTIFICATION_NUDGE);
   }
   return sections.join("\n\n");
 }

package/src/branch-landed.ts

@@ -78,6 +78,7 @@ export function notifyBranchLanded(input: BranchLandedInput): void {
       subject: "Your branch landed",
       body: `✅ ${branchLabel} landed on \`${base}\`${shaLabel}${subjectLabel}.${continueLabel}`,
       payload,
+      replyExpected: false,
     });
   }
 
@@ -93,6 +94,7 @@ export function notifyBranchLanded(input: BranchLandedInput): void {
       subject: `Merged to ${base}`,
       body: `🔀 ${branchLabel}${authorLabel} merged to \`${base}\`${shaLabel}${subjectLabel}.`,
       payload,
+      replyExpected: false,
     });
   }
 }

package/src/db.ts

@@ -226,6 +226,7 @@ export function initDb(path: string = "agent-relay.db"): Database {
       body TEXT NOT NULL,
       thread_id INTEGER,
       reply_to INTEGER REFERENCES messages(id),
+      reply_expected INTEGER NOT NULL DEFAULT 1,
       claimable INTEGER NOT NULL DEFAULT 0,
       claimed_by TEXT,
       claimed_at INTEGER,
@@ -857,6 +858,9 @@ export function initDb(path: string = "agent-relay.db"): Database {
     db.run("ALTER TABLE messages ADD COLUMN thread_id INTEGER");
     db.run("ALTER TABLE messages ADD COLUMN reply_to INTEGER REFERENCES messages(id)");
   }
+  if (!colNames.includes("reply_expected")) {
+    db.run("ALTER TABLE messages ADD COLUMN reply_expected INTEGER NOT NULL DEFAULT 1");
+  }
   if (!colNames.includes("claimable")) {
     db.run("ALTER TABLE messages ADD COLUMN claimable INTEGER NOT NULL DEFAULT 0");
     db.run("ALTER TABLE messages ADD COLUMN claimed_by TEXT");
@@ -1292,6 +1296,9 @@ function rowToMessage(row: any): Message {
     body: row.body,
     threadId: row.thread_id ?? undefined,
     replyTo: row.reply_to ?? undefined,
+    // Default (true) stays absent to match the `claimable` idiom and keep notification-free
+    // messages byte-identical on the wire; only an explicit notification surfaces false (#283).
+    replyExpected: row.reply_expected === 0 ? false : undefined,
     claimable: row.claimable === 1 ? true : undefined,
     claimedBy: row.claimed_by ?? undefined,
     claimedAt: row.claimed_at ?? undefined,
@@ -3794,12 +3801,12 @@ export function sendMessageWithResult(input: SendMessageInput): { message: Messa
 
   const insert = db.query(`
     INSERT INTO messages (
-      from_agent, to_target, kind, channel, subject, body, thread_id, reply_to, claimable,
+      from_agent, to_target, kind, channel, subject, body, thread_id, reply_to, reply_expected, claimable,
       idempotency_key, delivery_status, queued_at, max_age_seconds, resolved_to_agent,
       payload, meta, created_at, occurred_at
     )
     VALUES (
-      $from, $to, $kind, $channel, $subject, $body, $threadId, $replyTo, $claimable,
+      $from, $to, $kind, $channel, $subject, $body, $threadId, $replyTo, $replyExpected, $claimable,
       $idempotencyKey, $deliveryStatus, $queuedAt, $maxAgeSeconds, $resolvedToAgent,
       $payload, $meta, $now, $occurredAt
     )
@@ -3833,6 +3840,9 @@ export function sendMessageWithResult(input: SendMessageInput): { message: Messa
       $body: input.body,
       $threadId: threadId,
       $replyTo: input.replyTo ?? null,
+      // Server-owned reply obligation (#283): true by default; only an explicit false marks
+      // a notification. Stored 0/1 so the footer renderer + reply tracker key off one column.
+      $replyExpected: input.replyExpected === false ? 0 : 1,
       $claimable: claimable ? 1 : 0,
       $idempotencyKey: input.idempotencyKey ?? null,
       $deliveryStatus: deliveryStatus,
@@ -4318,6 +4328,9 @@ export function pollMessages(query: PollQuery): Message[] {
 }
 
 function messageRequiresReply(message: Message): boolean {
+  // Server-owned notification flag (#283) wins over every kind/sender heuristic below: an
+  // explicit replyExpected:false is a fire-and-forget message that must never become an obligation.
+  if (message.replyExpected === false) return false;
   if (message.kind === "system" || message.kind === "control" || message.kind === "session") return false;
   if (message.from === "user") return true;
   if (message.kind === "task" || message.kind === "channel.event") return true;

package/src/mcp.ts

@@ -247,19 +247,19 @@ const TOOLS: ToolDefinition[] = [
   },
   {
     name: "relay_spawn_agent",
-    description: "Spawn a long-living provider agent through Relay's orchestrator. Gated: requires the command:spawn scope, granted only to agents whose profile sets maxSpawnedAgents>0, up to that live-children quota. Spawned agents cannot themselves spawn (no grandchildren).",
+    description: "Spawn a long-living provider agent through Relay's orchestrator, optionally handing it its first task via `prompt` in the same call. Defaults to your own host (override with orchestratorId) and returns the resolved agent id once it registers. Gated: requires the command:spawn scope, granted only to agents whose profile sets maxSpawnedAgents>0, up to that live-children quota. Spawned agents cannot themselves spawn (no grandchildren).",
     requiredScopes: ["command:spawn"],
     inputSchema: {
       type: "object",
       properties: {
         provider: { type: "string", enum: SPAWN_PROVIDERS },
-        orchestratorId: { type: "string" },
-        cwd: { type: "string" },
+        orchestratorId: { type: "string", description: "Target host. Defaults to the host that owns cwd, else YOUR OWN host — only set it to spawn onto a different machine." },
+        cwd: { type: "string", description: "Working directory for the agent. Must resolve within the target orchestrator's base directory (enforced server-side)." },
         label: { type: "string" },
         model: { type: "string" },
         effort: { type: "string", enum: VALID_EFFORTS },
         approvalMode: { type: "string", enum: APPROVAL_MODES },
-        prompt: { type: "string" },
+        prompt: { type: "string", description: "Initial task/message delivered to the agent on launch — spawn and hand it its first instruction in one call (no separate follow-up message needed)." },
         systemPromptAppend: { type: "string" },
         profile: { type: "string", description: "Agent profile name to apply (env, instructions, permissions, MCP/skills, spawn quota)." },
         tags: { type: "array", items: { type: "string" } },
@@ -267,6 +267,7 @@ const TOOLS: ToolDefinition[] = [
         providerArgs: { type: "array", items: { type: "string" } },
         policyName: { type: "string" },
         spawnRequestId: { type: "string" },
+        waitForRegistrationMs: { type: "integer", minimum: 0, maximum: 30000, description: "How long to wait for the spawned agent to register before returning, so the response carries its resolved agent id (default 8000; 0 = return immediately with just spawnRequestId)." },
       },
       required: ["provider"],
       additionalProperties: false,
@@ -485,7 +486,7 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name === "relay_agent_status") result = relayAgentStatus(args);
     else if (name === "relay_find_agents") result = relayFindAgents(auth, args);
     else if (name === "relay_whoami") result = relayWhoami(auth);
-    else if (name === "relay_spawn_agent") result = relaySpawnAgent(auth, args);
+    else if (name === "relay_spawn_agent") result = await relaySpawnAgent(auth, args);
     else if (name === "relay_shutdown_agent") result = relayShutdownAgent(auth, args);
     else if (name === "relay_workspace_status") result = await relayWorkspaceStatus(auth, args);
     else if (name === "relay_workspace_list") result = relayWorkspaceList(auth, args);
@@ -763,10 +764,12 @@ function relayFindAgents(auth: McpAuthContext, args: Record<string, unknown>): R
   return { agents, count: agents.length };
 }
 
-function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
+async function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): Promise<Record<string, unknown>> {
   const provider = enumField(args.provider, "provider", SPAWN_PROVIDERS) as SpawnProvider;
   const cwd = optionalString(args.cwd, "cwd", 500);
-  const orchestrator = selectSpawnOrchestrator(provider, optionalString(args.orchestratorId, "orchestratorId", 200), cwd);
+  const callerId = callerAgentId(auth);
+  const preferHost = callerId ? getAgent(callerId)?.machine : undefined;
+  const orchestrator = selectSpawnOrchestrator(provider, optionalString(args.orchestratorId, "orchestratorId", 200), cwd, preferHost);
   const resolvedCwd = cwd || orchestrator.baseDir;
   if (cwd && !isPathWithinBase(cwd, orchestrator.baseDir)) {
     throw new ValidationError(`cwd must be within orchestrator base directory: ${orchestrator.baseDir}`);
@@ -781,7 +784,6 @@ function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): R
   // #221 runtime gate (belt; the coarse `command:spawn` scope is enforced in callTool, and is
   // granted only to agents whose profile sets maxSpawnedAgents>0 and never to children).
   // Server/admin tokens have no caller identity → unrestricted by design.
-  const callerId = callerAgentId(auth);
   if (callerId) {
     const me = getAgent(callerId);
     if (me?.spawnedBy) {
@@ -841,7 +843,27 @@ function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): R
     }),
   });
   emitCommand(command);
-  return { ok: true, orchestratorId: orchestrator.id, provider, command };
+
+  // #255: resolve the spawned agent id once it registers. Spawn is a fire-and-forget command
+  // over the bus; the child registers back to THIS relay (same DB) with meta.spawnRequestId set,
+  // so a bounded poll links the request to the agent without a separate relay_find_agents round
+  // trip. waitForRegistrationMs:0 opts out (pure fire-and-forget); the default is short because
+  // isolated-worktree spawns register near-instantly (symlinked deps).
+  const waitMs = Math.min(optionalNonNegativeInt(args.waitForRegistrationMs, "waitForRegistrationMs") ?? 8000, 30000);
+  const agentId = waitMs > 0 ? await waitForSpawnedAgent(spawnRequestId, waitMs) : null;
+  return { ok: true, spawnRequestId, orchestratorId: orchestrator.id, provider, agentId, registered: agentId !== null, command };
+}
+
+// Poll the agents table for the child that registers with this spawnRequestId (#255). Returns
+// the resolved agent id, or null on timeout (the caller still has spawnRequestId to poll later).
+async function waitForSpawnedAgent(spawnRequestId: string, timeoutMs: number, pollMs = 300): Promise<string | null> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const match = listAgents().find((a) => a.meta?.spawnRequestId === spawnRequestId);
+    if (match) return match.id;
+    if (Date.now() >= deadline) return null;
+    await new Promise<void>((resolve) => setTimeout(resolve, Math.min(pollMs, Math.max(0, deadline - Date.now()))));
+  }
 }
 
 function relayShutdownAgent(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
@@ -1062,7 +1084,12 @@ function policyStatusPayload(policy: NonNullable<ReturnType<typeof getSpawnPolic
   };
 }
 
-function selectSpawnOrchestrator(provider: SpawnProvider, orchestratorId?: string, cwd?: string): NonNullable<ReturnType<typeof getOrchestrator>> {
+function selectSpawnOrchestrator(
+  provider: SpawnProvider,
+  orchestratorId?: string,
+  cwd?: string,
+  preferHost?: string,
+): NonNullable<ReturnType<typeof getOrchestrator>> {
   if (orchestratorId) {
     const orchestrator = getOrchestrator(orchestratorId);
     if (!orchestrator) throw new McpNotFoundError(`orchestrator ${orchestratorId} not found`);
@@ -1075,6 +1102,14 @@ function selectSpawnOrchestrator(provider: SpawnProvider, orchestratorId?: strin
     const match = candidates.find((item) => isPathWithinBase(cwd, item.baseDir));
     if (match) return match;
   }
+  // #255: with neither an explicit id nor a cwd to pin the host, default to the CALLER's own
+  // host instead of silently grabbing candidates[0] (a foreign host whose baseDir would then
+  // reject the caller's cwd — the footgun the spawn recipe warned about). An agent's `machine`
+  // is its OS hostname; match it against the orchestrator hostname (or id, defensively).
+  if (preferHost) {
+    const own = candidates.find((item) => item.hostname === preferHost || item.id === preferHost);
+    if (own) return own;
+  }
   const orchestrator = candidates[0];
   if (!orchestrator) throw new McpNotFoundError(`no orchestrator available for provider: ${provider}`);
   return orchestrator;
@@ -1327,6 +1362,12 @@ function optionalPositiveInt(value: unknown, field: string): number | undefined
   return value;
 }
 
+function optionalNonNegativeInt(value: unknown, field: string): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new ValidationError(`${field} must be a non-negative integer`);
+  return value;
+}
+
 function optionalFutureTimestamp(value: unknown, field: string): number | undefined {
   const timestamp = optionalPositiveInt(value, field);
   if (timestamp !== undefined && timestamp <= Date.now()) throw new ValidationError(`${field} must be a future unix timestamp in milliseconds`);

package/src/notify.ts

@@ -10,6 +10,13 @@ export interface SystemNotifyOptions {
   kind?: MessageKind;
   /** Sender id; defaults to "system". */
   from?: string;
+  /**
+   * #283 — set false for a fire-and-forget notification (merge notice, lifecycle event): the
+   * server suppresses the reply-scaffold footer and the reply-obligation tracker skips it.
+   * Omit (default true) for system messages that genuinely want the agent to act/answer
+   * (steward task assignments, conflict handoffs).
+   */
+  replyExpected?: boolean;
 }
 
 /**
@@ -25,6 +32,7 @@ export function notifySystemMessage(to: string, opts: SystemNotifyOptions): Mess
     subject: opts.subject,
     body: opts.body,
     payload: opts.payload,
+    replyExpected: opts.replyExpected,
   });
   emitNewMessage(msg);
   return msg;

package/src/routes.ts

@@ -520,6 +520,9 @@ function normalizeMessageInput(body: unknown): SendMessageInput {
   if (body.claimable !== undefined && typeof body.claimable !== "boolean") {
     throw new ValidationError("claimable must be a boolean");
   }
+  if (body.replyExpected !== undefined && typeof body.replyExpected !== "boolean") {
+    throw new ValidationError("replyExpected must be a boolean");
+  }
 
   const input: SendMessageInput = {
     from: cleanString(body.from, "from", { required: true, max: 200 })!,
@@ -527,6 +530,7 @@ function normalizeMessageInput(body: unknown): SendMessageInput {
     body: cleanString(body.body, "body", { required: true, max: MAX_BODY_BYTES })!,
     kind: kind as SendMessageInput["kind"] | undefined,
     replyTo: cleanPositiveId(body.replyTo, "replyTo"),
+    replyExpected: body.replyExpected as boolean | undefined,
     claimable: body.claimable as boolean | undefined,
     idempotencyKey: cleanString(body.idempotencyKey, "idempotencyKey", { max: 240 }),
   };

package/src/workspace-orphans.ts

@@ -5,11 +5,15 @@
 // visible to the agent or the dashboard, so unlanded work can sit stranded for
 // weeks (one real casualty: a CI-guard test, recovered by hand).
 //
-// THE invariant (single home, see `worktreeReapable`): reaping is gated on
-// "nothing would be lost" — landed or empty — NEVER on session liveness or a
-// timer. A worktree holding un-landed commits is flagged for attention, never
-// force-removed. This module is the disk⇄DB reconciler the GC's `git worktree
-// prune` (a no-op while the directory exists) never was.
+// THE invariant (single home, see `worktreeReapable`): a worktree is reaped only
+// when BOTH hold — "nothing would be lost" (landed or empty; un-landed commits are
+// flagged, never force-removed) AND "nobody is using it" (the owner is dead, and no
+// live row claims the path). #278 proved the first half alone is not enough: a
+// post-land recycled worktree (ahead 0) owned by a LIVE session is reap-safe by
+// land-state, yet destroying it kills that session's toolchain mid-flight. Path-keyed
+// row matching (never repoRoot-scoped) plus an owner-liveness guard enforce the
+// second half. This module is the disk⇄DB reconciler the GC's `git worktree prune`
+// (a no-op while the directory exists) never was.
 
 import { resolve } from "node:path";
 import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
@@ -20,6 +24,7 @@ import { emitRelayEvent } from "./events";
 import { isPathWithinBase } from "./utils";
 import { TERMINAL_WORKSPACE_STATUSES, worktreeReapable, type WorktreeReapState } from "./workspace-phase";
 import { isOwnerAlive } from "./workspace-merge";
+import { applyWorkspaceAction } from "./workspace-actions";
 
 // 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
@@ -29,10 +34,21 @@ const UNLANDED_FLAG_COOLDOWN_MS = Number(process.env.AGENT_RELAY_ORPHAN_FLAG_COO
 // remove them (parity with the session reaper's detect-only switch).
 const orphanWorktreeReapEnabled = () => process.env.AGENT_RELAY_ORPHAN_WORKTREE_REAP !== "0";
 const flaggedAt = new Map<string, number>();
-const IN_FLIGHT_MISSING_WORKTREE_STATUSES = new Set<WorkspaceStatus>(["merge_planned", "cleanup_requested"]);
+const IN_FLIGHT_WORKSPACE_STATUSES = new Set<WorkspaceStatus>(["merge_planned", "cleanup_requested"]);
+
+// #279 dead-owner grace window: a tracked worktree whose owner has died is only
+// reaped after the owner is observed dead continuously for this window, so a
+// reconnecting agent isn't raced. Keyed by resolved worktree path; in-memory like
+// the session reaper's tracker (a restart re-arms the clock — conservative).
+const orphanGraceMs = (): number => {
+  const v = Number(process.env.AGENT_RELAY_ORPHAN_GRACE_MS);
+  return Number.isFinite(v) && v >= 0 ? v : 30 * 60 * 1000;
+};
+const deadOwnerTracker = new Map<string, { firstSeenDeadAt: number }>();
 
 export function resetOrphanWorktreeStateForTests(): void {
   flaggedAt.clear();
+  deadOwnerTracker.clear();
 }
 
 interface OnlineOrchestrator {
@@ -138,6 +154,17 @@ export interface CollectOrphansResult {
     baseSha?: string;
     ownerAgentId?: string;
   }>;
+  /** Non-terminal isolated rows whose worktree IS present on disk (#279). Tracked,
+   * not orphaned — the reaper decides on owner-liveness + grace + land-state. */
+  deadOwnerWorkspaces: Array<{
+    workspaceId: string;
+    worktreePath: string;
+    repoRoot: string;
+    branch?: string;
+    baseRef?: string;
+    baseSha?: string;
+    ownerAgentId?: string;
+  }>;
   reason?: string;
 }
 
@@ -150,11 +177,27 @@ export interface CollectOrphansResult {
  */
 export async function collectWorkspaceOrphans(): Promise<CollectOrphansResult> {
   const orchestrators = onlineOrchestrators();
-  if (!orchestrators.length) return { orphans: [], missingWorktrees: [], reason: "no online orchestrators" };
+  if (!orchestrators.length) return { orphans: [], missingWorktrees: [], deadOwnerWorkspaces: [], reason: "no online orchestrators" };
 
   const all = listWorkspaces();
   const orphans: WorkspaceOrphan[] = [];
   const missingWorktrees: CollectOrphansResult["missingWorktrees"] = [];
+  const deadOwnerWorkspaces: CollectOrphansResult["deadOwnerWorkspaces"] = [];
+
+  // Worktree paths are globally unique, so a row from ANY repoRoot that records a
+  // path is the authoritative claim on it. Match disk→DB across ALL rows, NEVER
+  // scoped to one repoRoot: the scoped version false-orphaned chained workspaces
+  // (managed session → base checkout → isolated worktree, whose row records the base
+  // checkout as repoRoot, not the main repo the probe is seeded from), so the reaper
+  // destroyed a live session's worktree (#278).
+  const rowsByPath = new Map(all.filter((ws) => ws.worktreePath).map((ws) => [resolve(ws.worktreePath), ws]));
+
+  // Union of every probed repo's on-disk worktrees + the repoRoots we actually
+  // reached. The DB→disk (missing-worktree) pass runs ONCE, globally, after the loop
+  // against these — per-repo scoping there falsely flagged chained rows as missing
+  // (their worktree lives under a different repo's probe than the one iterating). #278
+  const onDiskAll = new Set<string>();
+  const probedRepoRoots = new Set<string>();
 
   for (const repoRoot of knownRepoRoots(all)) {
     const orch = orchestrators.find((candidate) => candidate.apiUrl && isPathWithinBase(repoRoot, candidate.baseDir));
@@ -162,40 +205,32 @@ export async function collectWorkspaceOrphans(): Promise<CollectOrphansResult> {
     const probe = await fetchHostProbe(orch.apiUrl, repoRoot);
     if (!probe?.worktrees) continue;
 
-    const liveRowsByPath = new Map(
-      all
-        .filter((ws) => ws.repoRoot === repoRoot && ws.worktreePath && !TERMINAL_WORKSPACE_STATUSES.has(ws.status))
-        .map((ws) => [resolve(ws.worktreePath), ws]),
-    );
-    const onDisk = new Set(probe.worktrees.map((wt) => (wt.path ? resolve(wt.path) : "")).filter(Boolean));
-
-    // DB→disk drift: a live isolated row whose worktree is no longer on disk.
-    for (const [path, ws] of liveRowsByPath) {
-      if (ws.mode === "isolated" && !onDisk.has(path)) {
-        missingWorktrees.push({
-          workspaceId: ws.id,
-          worktreePath: ws.worktreePath,
-          repoRoot,
-          status: ws.status,
-          branch: ws.branch,
-          baseRef: ws.baseRef,
-          baseSha: ws.baseSha,
-          ownerAgentId: ws.ownerAgentId,
-        });
-      }
-    }
+    probedRepoRoots.add(resolve(repoRoot));
+    for (const wt of probe.worktrees) if (wt.path) onDiskAll.add(resolve(wt.path));
 
-    // disk→DB drift: a worktree on disk with no live row.
-    const rowsByPath = new Map(
-      all.filter((ws) => ws.repoRoot === repoRoot && ws.worktreePath).map((ws) => [resolve(ws.worktreePath), ws]),
-    );
+    // disk→DB drift: a worktree on disk with no live row → orphan. A worktree with a
+    // live isolated row is NOT an orphan, but if its owner has died it's the #279
+    // dead-owner case — surface it for the reaper to evaluate (liveness + grace).
     for (const worktree of probe.worktrees) {
       if (!worktree.path || resolve(worktree.path) === resolve(repoRoot)) continue;
       // Only agent-relay-created worktrees (agent/* branches) are reclaimable —
       // never touch a user's own linked worktrees.
       if (!worktree.branch?.startsWith("agent/")) continue;
       const row = rowsByPath.get(resolve(worktree.path));
-      if (row && !TERMINAL_WORKSPACE_STATUSES.has(row.status)) continue; // tracked & live
+      if (row && !TERMINAL_WORKSPACE_STATUSES.has(row.status)) {
+        if (row.mode === "isolated") {
+          deadOwnerWorkspaces.push({
+            workspaceId: row.id,
+            worktreePath: worktree.path,
+            repoRoot: row.repoRoot,
+            branch: row.branch ?? worktree.branch,
+            baseRef: row.baseRef,
+            baseSha: row.baseSha,
+            ownerAgentId: row.ownerAgentId,
+          });
+        }
+        continue; // tracked & live — not an orphan
+      }
 
       const orphan: WorkspaceOrphan = {
         worktreePath: worktree.path,
@@ -223,7 +258,32 @@ export async function collectWorkspaceOrphans(): Promise<CollectOrphansResult> {
     }
   }
 
-  return { orphans, missingWorktrees };
+  // DB→disk drift: a non-terminal isolated row whose worktree is gone from disk. Run
+  // once, globally, against the union of probed repos. Flag "missing" only when the
+  // path is absent from EVERY probe AND the row was COVERABLE — its repoRoot was
+  // probed, OR its repoRoot is itself a worktree we saw on disk (the chained case: an
+  // isolated row's repoRoot is its session base checkout, a linked worktree of a
+  // probed repo). The coverability gate is what stops rows under an un-probeable host
+  // from being falsely flagged missing. #278
+  for (const ws of all) {
+    if (ws.mode !== "isolated" || !ws.worktreePath) continue;
+    if (TERMINAL_WORKSPACE_STATUSES.has(ws.status)) continue;
+    if (onDiskAll.has(resolve(ws.worktreePath))) continue;
+    const coverable = probedRepoRoots.has(resolve(ws.repoRoot)) || onDiskAll.has(resolve(ws.repoRoot));
+    if (!coverable) continue;
+    missingWorktrees.push({
+      workspaceId: ws.id,
+      worktreePath: ws.worktreePath,
+      repoRoot: ws.repoRoot,
+      status: ws.status,
+      branch: ws.branch,
+      baseRef: ws.baseRef,
+      baseSha: ws.baseSha,
+      ownerAgentId: ws.ownerAgentId,
+    });
+  }
+
+  return { orphans, missingWorktrees, deadOwnerWorkspaces };
 }
 
 function dispatchCleanup(orch: OnlineOrchestrator, orphan: WorkspaceOrphan): string {
@@ -254,7 +314,7 @@ function dispatchCleanup(orch: OnlineOrchestrator, orphan: WorkspaceOrphan): str
  * directions surface. Never removes on uncertainty.
  */
 export async function reapOrphanedWorktrees(): Promise<Record<string, unknown>> {
-  const { orphans, missingWorktrees, reason } = await collectWorkspaceOrphans();
+  const { orphans, missingWorktrees, deadOwnerWorkspaces, reason } = await collectWorkspaceOrphans();
   if (reason) return { skipped: reason };
 
   const orchestrators = onlineOrchestrators();
@@ -263,14 +323,27 @@ export async function reapOrphanedWorktrees(): Promise<Record<string, unknown>>
   const flagged: string[] = [];
   const autoAbandoned: string[] = [];
   const flaggedMissingWorktrees: string[] = [];
+  const deadOwnerReaped: string[] = [];
+  const deadOwnerFlagged: string[] = [];
   const now = Date.now();
 
+  // Defense in depth (#278): the matching fix in collectWorkspaceOrphans should keep
+  // any path with a live, non-terminal row out of `orphans`. This is the belt to that
+  // suspenders — re-read rows fresh and never reap a path one still claims, even if a
+  // future refactor reintroduces a lookup gap. False-reaping a live session is fatal.
+  const nonTerminalRowsByPath = new Map(
+    listWorkspaces()
+      .filter((ws) => ws.worktreePath && !TERMINAL_WORKSPACE_STATUSES.has(ws.status))
+      .map((ws) => [resolve(ws.worktreePath), ws]),
+  );
+
   for (const orphan of orphans) {
     const orch = orchestrators.find((candidate) => isPathWithinBase(orphan.repoRoot, candidate.baseDir));
     if (!orch) continue;
 
     if (orphan.safeToReap === true) {
       if (!reapEnabled) continue; // detect-only mode
+      if (nonTerminalRowsByPath.has(resolve(orphan.worktreePath))) continue; // still claimed — never reap (#278)
       const commandId = dispatchCleanup(orch, orphan);
       reaped.push(orphan.worktreePath);
       flaggedAt.delete(orphan.worktreePath);
@@ -315,7 +388,7 @@ export async function reapOrphanedWorktrees(): Promise<Record<string, unknown>>
     if (!workspace || TERMINAL_WORKSPACE_STATUSES.has(workspace.status) || workspace.mode !== "isolated" || !workspace.worktreePath) continue;
     const key = `missing:${workspace.worktreePath}`;
     const ownerAlive = isOwnerAlive(workspace.ownerAgentId);
-    const inFlight = IN_FLIGHT_MISSING_WORKTREE_STATUSES.has(workspace.status);
+    const inFlight = IN_FLIGHT_WORKSPACE_STATUSES.has(workspace.status);
     const last = flaggedAt.get(key) ?? 0;
     if (ownerAlive || inFlight) {
       if (now - last < UNLANDED_FLAG_COOLDOWN_MS) continue;
@@ -410,9 +483,95 @@ export async function reapOrphanedWorktrees(): Promise<Record<string, unknown>>
     });
   }
 
+  // #279: a tracked worktree whose owner died — the common stale case the reaper
+  // never handled (inverse of #278's false kill). Gate on owner-liveness + a grace
+  // window + "nothing would be lost", then dispatch through the GUARDED action (the
+  // #254 isOwnerAlive re-check at dispatch is the safety net against a stale read).
+  const graceMs = orphanGraceMs();
+  const liveDeadOwnerKeys = new Set<string>();
+  for (const cand of deadOwnerWorkspaces) {
+    const workspace = getWorkspace(cand.workspaceId);
+    if (!workspace || workspace.mode !== "isolated" || !workspace.worktreePath) continue;
+    if (TERMINAL_WORKSPACE_STATUSES.has(workspace.status)) continue;
+    if (IN_FLIGHT_WORKSPACE_STATUSES.has(workspace.status)) continue; // cleanup/merge already dispatched
+    const key = `dead-owner:${resolve(workspace.worktreePath)}`;
+    liveDeadOwnerKeys.add(key);
+
+    if (isOwnerAlive(workspace.ownerAgentId)) {
+      deadOwnerTracker.delete(key); // owner alive — reset the grace window (regression vs #278)
+      continue;
+    }
+
+    // Owner observed dead. Require continuous dead-ness for the grace window so a
+    // reconnecting agent isn't raced; the in-memory tracker re-arms on restart. A
+    // grace of 0 reaps on the first dead observation (the env's escape hatch).
+    const tracked = deadOwnerTracker.get(key);
+    const firstSeenDeadAt = tracked?.firstSeenDeadAt ?? now;
+    if (!tracked) deadOwnerTracker.set(key, { firstSeenDeadAt });
+    if (now - firstSeenDeadAt < graceMs) continue;
+
+    // Grace elapsed + owner dead. Gate on land-state — "nothing would be lost".
+    const orch = orchestrators.find((candidate) => candidate.apiUrl && isPathWithinBase(workspace.repoRoot, candidate.baseDir));
+    const preview = orch?.apiUrl
+      ? await fetchWorktreeReapState(orch.apiUrl, workspace.worktreePath, workspace.baseRef)
+      : null;
+    const safeToReap = preview && !preview.missing && !preview.error
+      ? worktreeReapable({ landed: preview.landed, ahead: preview.ahead, unmergedAhead: preview.unmergedAhead, dirtyCount: preview.dirtyCount })
+      : undefined;
+
+    if (safeToReap === true) {
+      if (!reapEnabled) continue; // detect-only mode
+      // Route through the guarded action (#279): no `force`, so a flipped-alive owner
+      // is rejected (409) — our safety net. Also does the cleanup_requested transition
+      // + audit. Attributed to a distinct requester so incidents are traceable.
+      const result = applyWorkspaceAction(workspace, {
+        action: "cleanup",
+        agentId: "workspace-dead-owner-reaper",
+        auditMetadata: { source: "server", maintenanceJobId: "workspace-orphan-reaper", requestedBy: "workspace-dead-owner-reaper", deadOwner: workspace.ownerAgentId },
+      });
+      if (!result.ok) continue; // guard tripped (owner came back) or no owning orchestrator — re-evaluate next sweep
+      if (result.command) {
+        emitRelayEvent({ type: `command.${result.command.status}`, source: result.command.source, subject: result.command.id, data: { command: result.command } });
+      }
+      deadOwnerReaped.push(workspace.id);
+      deadOwnerTracker.delete(key);
+      continue;
+    }
+
+    // Un-landed or un-probeable: flag as stranded (dead owner), never remove.
+    const flagKey = `dead-owner-stranded:${resolve(workspace.worktreePath)}`;
+    liveDeadOwnerKeys.add(flagKey);
+    const last = flaggedAt.get(flagKey) ?? 0;
+    if (now - last < UNLANDED_FLAG_COOLDOWN_MS) continue;
+    flaggedAt.set(flagKey, now);
+    deadOwnerFlagged.push(workspace.id);
+    const detail = safeToReap === undefined
+      ? "host could not be probed for land-state"
+      : (preview && (preview.dirtyCount ?? 0) > 0)
+        ? "uncommitted changes in the worktree"
+        : `${preview?.unmergedAhead ?? preview?.ahead ?? "?"} un-landed commit(s)`;
+    createActivityEvent({
+      clientId: `workspace-dead-owner-stranded-${workspace.id}-${now}`,
+      kind: "state",
+      title: "Dead-owner worktree needs attention",
+      body: `${workspace.branch ?? workspace.id} in ${workspace.repoRoot} — owning agent ${workspace.ownerAgentId ?? "?"} is gone and the worktree holds work that hasn't landed (${detail}). Recover the commits, then clean it up explicitly.`,
+      meta: workspace.branch ?? workspace.id,
+      icon: "ti-alert-triangle",
+      view: "orchestrators",
+      metadata: { source: "server", maintenanceJobId: "workspace-orphan-reaper", workspaceId: workspace.id, worktreePath: workspace.worktreePath, branch: workspace.branch, ownerAgentId: workspace.ownerAgentId, deadOwner: true },
+    });
+  }
+  // Drop grace-tracker entries for worktrees that are gone (reaped/landed) so a
+  // future re-orphaning re-arms the window from scratch.
+  for (const key of deadOwnerTracker.keys()) if (!liveDeadOwnerKeys.has(key)) deadOwnerTracker.delete(key);
+
   // Forget cooldown entries for orphans that are gone (reaped/recovered) so a
   // future re-orphaning of the same path re-announces immediately.
-  const liveKeys = new Set([...orphans.map((o) => o.worktreePath), ...missingWorktrees.map((m) => `missing:${m.worktreePath}`)]);
+  const liveKeys = new Set([
+    ...orphans.map((o) => o.worktreePath),
+    ...missingWorktrees.map((m) => `missing:${m.worktreePath}`),
+    ...liveDeadOwnerKeys,
+  ]);
   for (const key of flaggedAt.keys()) if (!liveKeys.has(key) && !reaped.includes(key)) flaggedAt.delete(key);
 
   return {
@@ -422,6 +581,8 @@ export async function reapOrphanedWorktrees(): Promise<Record<string, unknown>>
     autoAbandoned,
     flaggedMissingWorktrees,
     missingWorktrees: missingWorktrees.map((m) => m.workspaceId),
+    deadOwnerReaped,
+    deadOwnerFlagged,
     reapEnabled,
   };
 }