agent-relay-server 0.121.0 → 0.121.2

package/src/maintenance/jobs.ts

@@ -1,6 +1,7 @@
 import { getArtifactStorage } from "../artifact-storage";
 import { deriveAgentBusyHealth } from "../agent-busy-health";
 import { expireStaleBusAgents } from "../bus";
+import { eventLoopLagMaxMs } from "../event-loop-lag";
 import { pruneOutbox } from "../bus-outbox";
 import { expireCommands } from "../commands-db";
 import { getRetentionConfig } from "../retention-config-store";
@@ -26,6 +27,7 @@ import {
 } from "../db";
 import { isAgentUnavailable } from "../db/agent-predicates";
 import { flushQueuedDirectMessages } from "../services/managed-running";
+import { sweepDeferredLineageReportsOnStartup } from "../services/send-message";
 import { notifyAgentOffline } from "../agent-lifecycle-events";
 import { diagnoseAgentDeath } from "../agent-death-diagnosis";
 import { autoMergeCleanFastForwards, runAutoMergeWatchdog, scheduleRepoMerge } from "../workspace-auto-merge";
@@ -49,6 +51,7 @@ import { reapUnregisteredSpawnCommands } from "../services/spawn-registration-wa
 import { resumeRateLimitedAgents } from "../services/rate-limit-resume";
 import { collectCodexWhamQuota } from "../codex-wham-quota";
 import { MERGE_PAUSE_MAINTENANCE_JOB } from "../merge-pause-maintenance";
+import { SELF_RESUME_INJECTION_SWEEP_JOB } from "../self-resume";
 import {
   CODEX_WHAM_QUOTA_INTERVAL_MS,
   DB_MAINTENANCE_INTERVAL_MS,
@@ -171,6 +174,7 @@ export const definitions: MaintenanceJobDefinition[] = [
     },
   },
   MERGE_PAUSE_MAINTENANCE_JOB,
+  SELF_RESUME_INJECTION_SWEEP_JOB,
   {
     id: "drive-lease-expiration",
     title: "Drive lease expiration",
@@ -237,7 +241,18 @@ export const definitions: MaintenanceJobDefinition[] = [
     intervalMs: REAP_INTERVAL_MS,
     runOnStart: true,
     handler() {
-      const commands = expireCommands();
+      // #1025 A6 — also expire PENDING commands whose target orchestrator/agent is
+      // permanently gone. Orchestrators register an `orchestrator-<id>` agent kept fresh
+      // by heartbeat and deleted on removal, so a missing/offline agent record for the
+      // target means it will never poll this command again. A merely-busy (online) host is
+      // left alone, preserving the #930/#953 "don't sweep before the host can claim it".
+      const commands = expireCommands(Date.now(), {
+        isTargetGone: (command) => {
+          if (!command.target || command.target === "system") return false;
+          const agent = getAgent(command.target);
+          return !agent || agent.status === "offline";
+        },
+      });
       for (const command of commands) {
         settleWorkspaceCommand(command, { onMergeSettled: scheduleRepoMerge });
         applyCommandToRecipe(command);
@@ -263,7 +278,7 @@ export const definitions: MaintenanceJobDefinition[] = [
     intervalMs: REAP_INTERVAL_MS,
     runOnStart: true,
     handler() {
-      const expired = expireStaleBusAgents();
+      const expired = expireStaleBusAgents(undefined, eventLoopLagMaxMs());
       for (const id of expired.agentIds) {
         getLifecycleManager().onAgentDisappeared(id);
         // #636/#659 — only after the stale reconnect grace expires do we turn a bare
@@ -286,7 +301,12 @@ export const definitions: MaintenanceJobDefinition[] = [
     intervalMs: REAP_INTERVAL_MS,
     runOnStart: true,
     handler() {
-      const reapedAgentIds = reapStaleAgents(STALE_TTL_MS);
+      // #1048 — gate staleness on the relay's OWN event-loop health. eventLoopLagMaxMs()
+      // is side-effect-free (does not consume the /health poller's spike max). During a
+      // relay self-stall this grace keeps live agents whose heartbeats we simply couldn't
+      // process from being reaped as dead.
+      const lagGraceMs = eventLoopLagMaxMs();
+      const reapedAgentIds = reapStaleAgents(STALE_TTL_MS, lagGraceMs);
       for (const id of reapedAgentIds) {
         emitAgentStatus(id);
         createActivityEvent({
@@ -325,6 +345,14 @@ export const definitions: MaintenanceJobDefinition[] = [
     handler: () => reapOrphanedSessions(),
   },
   { id: "transient-agent-reaper", title: "Transient agent reaper", description: "Cleanly shut down transient spawned agents once they are idle and any isolated branch work has landed.", intervalMs: REAP_INTERVAL_MS, runOnStart: false, handler: () => reapTransientAgents() },
+  {
+    id: "lineage-report-startup-sweep",
+    title: "Lineage report startup sweep",
+    description: "Re-promote turn-final report-ups whose in-memory hold was lost across a relay restart (#1040).",
+    intervalMs: DAY_MS,
+    runOnStart: true,
+    handler: () => sweepDeferredLineageReportsOnStartup(),
+  },
   { id: "rate-limit-resume", title: "Rate-limit resume", description: "Auto-resume agents held on a provider usage/rate-limit stall once their reset window has passed (#286).", intervalMs: REAP_INTERVAL_MS, runOnStart: false, handler: () => resumeRateLimitedAgents() },
   {
     id: "stuck-busy-watchdog",
@@ -530,7 +558,11 @@ export const definitions: MaintenanceJobDefinition[] = [
     title: "Workspace GC",
     description: "Prune terminal workspace rows past retention, auto-abandon stale review_requested worktrees, and trigger git worktree prune on orchestrators.",
     intervalMs: WORKSPACE_GC_INTERVAL_MS,
-    runOnStart: false,
+    // #1021 A4 — the last-line strand backstop MUST run on start: it is the only sweep that
+    // catches ready/review_requested/conflict rows stranded independent of steward health, and
+    // a relay restarted more often than the hourly interval (normal during active dev) would
+    // otherwise never run it at all — the backstop effectively off exactly when it's needed.
+    runOnStart: true,
     timeoutMs: 60 * 1000,
     handler: workspaceGC,
   },

package/src/maintenance/workspaces.ts

@@ -21,7 +21,8 @@ import { preparePrCompletionScan, reconcileLandedPr } from "../workspace-pr-comp
 import { applyBranchFreshness, fetchHostMergePreview, workspacePathWithinBase } from "../workspace-probe";
 import { wakeRepoSteward } from "../workspace-auto-merge";
 import { workspaceOwnerOrchestrator } from "../workspace-host";
-import { routeWorkspaceCustodyEscalation } from "../workspace-escalation";
+import { routeWorkspaceCustodyEscalation, routeWorkspaceCustodyEscalationOrAlarm } from "../workspace-escalation";
+import { raiseOperatorAlarm } from "../operator-alarm";
 import {
   CONFLICT_SCAN_STATUSES,
   DAY_MS,
@@ -31,7 +32,6 @@ import {
   WORKSPACE_RETENTION_MS,
   WORKSPACE_REVIEW_TTL_MS,
   stewardEscalationMs,
-  stewardFallbackTarget,
 } from "./constants";
 import { emitCommand, notifyTarget } from "./events";
 
@@ -97,8 +97,8 @@ export async function scanWorkspaceConflicts(): Promise<Record<string, unknown>>
         metadata: { source: "server", maintenanceJobId: "workspace-conflict-scan", workspaceId: ws.id, ahead: p.ahead, behind: p.behind },
       });
       if (getStewardConfig().enabled) {
-        const woke = wakeRepoSteward(getWorkspace(ws.id) ?? ws, "conflict");
-        if (woke) notifiedStewards.push(woke);
+        const wake = wakeRepoSteward(getWorkspace(ws.id) ?? ws, "conflict");
+        if (wake.ok) notifiedStewards.push(wake.policy);
       } else if (ws.stewardAgentId) {
         try {
           // #640 — carry the identity triangle (branch agent + its coordinator) so the
@@ -146,7 +146,12 @@ function previewProvesLanded(preview: WorkspaceMergePreview): boolean {
 
 async function reviewAutoAbandonDecision(ws: WorkspaceRecord, orchestrators: ReturnType<typeof listOrchestrators>): Promise<AutoAbandonDecision> {
   const owner = workspaceOwnerOrchestrator(ws, orchestrators, { requireApiUrl: true });
-  if (!owner?.apiUrl) return ws.orchestratorId ? { kind: "defer", reason: "owner-unavailable" } : { kind: "abandon" };
+  // #1025 C3 — no reachable owner means we cannot probe land-state. Deferring is the safe
+  // outcome for BOTH cases: a known-but-offline host (may reconnect) AND an unknown host (no
+  // orchestratorId, no path match). The old code abandoned the unknown-host case BLIND — the
+  // less-certain input got the more destructive outcome. Deferring instead keeps the row for
+  // the strand-escalation loop / orphan scan to handle with an actual probe.
+  if (!owner?.apiUrl) return { kind: "defer", reason: ws.orchestratorId ? "owner-unavailable" : "unknown-host" };
   const preview = await fetchHostMergePreview(owner.apiUrl, ws, { checkPr: true });
   if (!preview || (preview as { available?: false }).available === false) return { kind: "defer", reason: "owner-unavailable" };
   const p = preview as WorkspaceMergePreview;
@@ -204,13 +209,28 @@ export async function workspaceGC(): Promise<Record<string, unknown>> {
     if (getStewardConfig().enabled) {
       wakeRepoSteward(fresh, `workspace ${fresh.status} stranded for ${Math.round((now - strandedAt) / (60 * 60 * 1000))}h`);
     }
+    const strandedHours = Math.round((now - strandedAt) / (60 * 60 * 1000));
     const targets = routeWorkspaceCustodyEscalation({
       workspace: fresh,
       subject: "Stranded workspace needs an owner",
-      body: `Workspace \`${fresh.branch ?? fresh.id}\` in ${fresh.repoRoot} is ${fresh.status} and has been stranded for ${Math.round((now - strandedAt) / (60 * 60 * 1000))}h. Please coordinate ${fresh.status === "conflict" ? "conflict resolution" : "review/merge"} or clean up the worktree.`,
+      body: `Workspace \`${fresh.branch ?? fresh.id}\` in ${fresh.repoRoot} is ${fresh.status} and has been stranded for ${strandedHours}h. Please coordinate ${fresh.status === "conflict" ? "conflict resolution" : "review/merge"} or clean up the worktree.`,
       payload: { kind: "workspace.stranded-escalation", workspaceId: fresh.id, repoRoot: fresh.repoRoot, branch: fresh.branch, status: fresh.status, strandedAt },
       idempotencyKey: `workspace-stranded:${fresh.id}:${strandedAt}:${Math.floor(now / escalationMs)}`,
     });
+    if (!targets.length) {
+      // #1021 A4 — the escalation reached ZERO recipients (owner exited, coordinator idle, no
+      // fallback configured). Marking this "escalated" would silently swallow the strand and
+      // repeat every sweep forever. Instead leave it UNescalated (don't stamp escalatedAt, so
+      // the next sweep retries once recipients exist) and raise a louder operator-visible alarm.
+      raiseOperatorAlarm({
+        clientId: `workspace-gc-unescalatable-${fresh.id}:${strandedAt}:${Math.floor(now / escalationMs)}`,
+        source: "workspace-gc",
+        subject: "Stranded workspace has no one to escalate to",
+        detail: `${fresh.branch ?? fresh.id} in ${fresh.repoRoot} has been ${fresh.status} for ${strandedHours}h but has no owner, coordinator, or fallback configured to escalate to. Configure AGENT_RELAY_WORKSPACE_STEWARD_FALLBACK or reclaim the worktree manually.`,
+        metadata: { maintenanceJobId: "workspace-gc", workspaceId: fresh.id, repoRoot: fresh.repoRoot, branch: fresh.branch, status: fresh.status, strandedAt },
+      });
+      continue;
+    }
     escalationTargets.push(...targets);
     patchWorkspaceMetadata(fresh.id, { escalatedAt: now });
     escalatedIds.push(fresh.id);
@@ -218,7 +238,7 @@ export async function workspaceGC(): Promise<Record<string, unknown>> {
       clientId: `workspace-gc-escalate-${fresh.id}-${now}`,
       kind: "state",
       title: "Workspace escalated",
-      body: `${fresh.branch ?? fresh.id} in ${fresh.repoRoot} - stranded ${fresh.status} escalated${targets.length ? ` to ${targets.join(", ")}` : " (no owner, coordinator, or fallback configured)"}`,
+      body: `${fresh.branch ?? fresh.id} in ${fresh.repoRoot} - stranded ${fresh.status} escalated to ${targets.join(", ")}`,
       meta: fresh.branch ?? fresh.id,
       icon: "ti-alert-octagon",
       view: "orchestrators",
@@ -230,45 +250,56 @@ export async function workspaceGC(): Promise<Record<string, unknown>> {
   const autoAbandonDeferred: string[] = [];
   const notifiedStewards: string[] = [];
   const reviewOrchestrators = listOrchestrators();
-  const fallbackTarget = stewardFallbackTarget();
   for (const ws of all) {
-    if (ws.status === "review_requested" && ws.updatedAt < reviewCutoff) {
-      const fresh = getWorkspace(ws.id);
-      if (!fresh || fresh.status !== "review_requested") continue;
-      const decision = await reviewAutoAbandonDecision(fresh, reviewOrchestrators);
-      if (decision.kind === "defer") {
-        autoAbandonDeferred.push(`${fresh.id}:${decision.reason}`);
-        continue;
-      }
-      if (decision.kind === "landed") {
-        reconcileLandedWorkspace(fresh, decision.preview);
-        reconciledLandedIds.push(fresh.id);
-        continue;
-      }
-
-      updateWorkspaceStatus(fresh.id, "abandoned", { autoAbandoned: true, abandonedReason: "review_requested TTL exceeded", abandonedAt: now });
-      abandonedIds.push(fresh.id);
-      const target = fresh.stewardAgentId ?? fallbackTarget;
-      const sent = notifyTarget(
-        "workspace.auto_abandoned",
-        { workspaceId: fresh.id, repoRoot: fresh.repoRoot },
-        target,
-        "Workspace auto-abandoned",
-        `Workspace \`${fresh.branch ?? fresh.id}\` in ${fresh.repoRoot} was auto-abandoned after ${Math.round(WORKSPACE_REVIEW_TTL_MS / DAY_MS)}d without steward action. Run workspace cleanup to reclaim the worktree.`,
-        { kind: "workspace.auto-abandoned", workspaceId: fresh.id, repoRoot: fresh.repoRoot, branch: fresh.branch },
-      );
-      if (sent) notifiedStewards.push(sent);
-      createActivityEvent({
-        clientId: `workspace-gc-abandon-${fresh.id}-${now}`,
-        kind: "state",
-        title: "Workspace auto-abandoned",
-        body: `${fresh.branch ?? fresh.id} in ${fresh.repoRoot} - review_requested for ${Math.round((now - fresh.updatedAt) / DAY_MS)}d`,
-        meta: fresh.branch ?? fresh.id,
-        icon: "ti-clock-x",
-        view: "orchestrators",
-        metadata: { source: "server", maintenanceJobId: "workspace-gc", workspaceId: fresh.id },
-      });
+    if (ws.mode !== "isolated" || !ws.worktreePath) continue;
+    // #1025 C2 — auto-abandon covers the whole strandable set (ready, review_requested,
+    // conflict, merge_planned), not just `review_requested`; a stuck `ready` was exempt and
+    // leaked forever. Clock the TTL on `readyAt` (the stable hand-off time) rather than
+    // `updatedAt` — updatedAt bumps on every owner heartbeat, so a live-but-idle owner's
+    // workspace never aged past the TTL. Fall back to updatedAt when readyAt is absent
+    // (e.g. an active→conflict autoflag that never passed through `ready`).
+    if (!STRANDABLE_STATUSES.has(ws.status)) continue;
+    if ((ws.readyAt ?? ws.updatedAt) >= reviewCutoff) continue;
+    const fresh = getWorkspace(ws.id);
+    if (!fresh || !STRANDABLE_STATUSES.has(fresh.status)) continue;
+    if ((fresh.readyAt ?? fresh.updatedAt) >= reviewCutoff) continue;
+    const decision = await reviewAutoAbandonDecision(fresh, reviewOrchestrators);
+    if (decision.kind === "defer") {
+      autoAbandonDeferred.push(`${fresh.id}:${decision.reason}`);
+      continue;
     }
+    if (decision.kind === "landed") {
+      reconcileLandedWorkspace(fresh, decision.preview);
+      reconciledLandedIds.push(fresh.id);
+      continue;
+    }
+
+    updateWorkspaceStatus(fresh.id, "abandoned", { autoAbandoned: true, abandonedReason: `${fresh.status} TTL exceeded`, abandonedAt: now });
+    abandonedIds.push(fresh.id);
+    // #1025 C4 — route through the owner/coordinator/fallback custody chain (with a loud
+    // operator alarm when it resolves to nobody) instead of `stewardAgentId ?? fallback`.
+    // Most strandable workspaces have no steward, so the old notice silently dropped while
+    // the state change still happened.
+    const targets = routeWorkspaceCustodyEscalationOrAlarm({
+      source: "workspace-gc",
+      workspace: fresh,
+      type: "workspace.auto_abandoned",
+      subject: "Workspace auto-abandoned",
+      body: `Workspace \`${fresh.branch ?? fresh.id}\` in ${fresh.repoRoot} was auto-abandoned after ${Math.round(WORKSPACE_REVIEW_TTL_MS / DAY_MS)}d ${fresh.status} without action. Run workspace cleanup to reclaim the worktree.`,
+      payload: { kind: "workspace.auto-abandoned", workspaceId: fresh.id, repoRoot: fresh.repoRoot, branch: fresh.branch, status: fresh.status },
+      idempotencyKey: `workspace-auto-abandoned:${fresh.id}:${now}`,
+    });
+    if (targets.length) notifiedStewards.push(...targets);
+    createActivityEvent({
+      clientId: `workspace-gc-abandon-${fresh.id}-${now}`,
+      kind: "state",
+      title: "Workspace auto-abandoned",
+      body: `${fresh.branch ?? fresh.id} in ${fresh.repoRoot} - ${fresh.status} past the ${Math.round(WORKSPACE_REVIEW_TTL_MS / DAY_MS)}d TTL`,
+      meta: fresh.branch ?? fresh.id,
+      icon: "ti-clock-x",
+      view: "orchestrators",
+      metadata: { source: "server", maintenanceJobId: "workspace-gc", workspaceId: fresh.id, status: fresh.status },
+    });
   }
 
   const orchestrators = listOrchestrators().filter((orch) => orch.status === "online" && orch.agentId);

package/src/managed-policy-escalation.ts

@@ -2,16 +2,81 @@ import { getAgent, getDb } from "./db";
 import { getSpawnPolicy } from "./config-store";
 import { stewardFallbackTarget } from "./config";
 import { routeNotification } from "./notification-router";
+import { raiseOperatorAlarm } from "./operator-alarm";
 import type { ManagedAgentState, Orchestrator, SpawnPolicy } from "./types";
 
 const ORCHESTRATOR_OFFLINE_ESCALATION_FAILURES = 3;
 
-export function escalateOfflineOrchestrator(policy: SpawnPolicy, state: ManagedAgentState, orch: Orchestrator | null | undefined): void {
-  if (state.consecutiveFailures < ORCHESTRATOR_OFFLINE_ESCALATION_FAILURES) return;
+function managedPolicyEscalationRecipients(policy: SpawnPolicy, state: ManagedAgentState): string[] {
   const updatedBy = getSpawnPolicy(policy.name)?.updatedBy?.trim();
   const previousParent = state.agentId ? getAgent(state.agentId)?.spawnedBy?.trim() : undefined;
   const fallback = stewardFallbackTarget();
-  const recipients = [...new Set([updatedBy, previousParent, fallback].filter((item): item is string => Boolean(item && item !== "system")))];
+  return [...new Set([updatedBy, previousParent, fallback].filter((item): item is string => Boolean(item && item !== "system")))];
+}
+
+// #1021 A3 — the spawn chain used to escalate only the "orchestrator offline" branch; every
+// OTHER terminal failure (crash-on-boot fast-fail storm → status `failed` → reconcilePolicy
+// returns forever; a spawn that dispatched but never registered a live session → 120s timeout
+// that backs off forever) emitted dashboard state only, so nobody was ever told the managed
+// agent — often the repo steward that lands branches — is down. Route those to the same
+// recipients as the offline branch, and when there is no reachable recipient raise an
+// operator-visible alarm instead of silently dropping the signal.
+export function escalateManagedSpawnFailure(
+  policy: SpawnPolicy,
+  state: ManagedAgentState,
+  opts: { phase: "failed" | "register-timeout"; error: string },
+): void {
+  const recipients = managedPolicyEscalationRecipients(policy, state);
+  const queuedMessages = queuedPolicyMessageCount(policy.name);
+  const subject = opts.phase === "failed"
+    ? "Managed policy failed and stopped retrying"
+    : "Managed policy spawn never registered";
+  const body = [
+    opts.phase === "failed"
+      ? `Managed policy \`${policy.name}\` has failed and will not retry on its own (${opts.error}).`
+      : `Managed policy \`${policy.name}\` keeps spawning but no session ever registers (${opts.error}).`,
+    `Queued messages: ${queuedMessages}. Consecutive failures: ${state.consecutiveFailures}.`,
+  ].join("\n");
+  const payload = {
+    kind: opts.phase === "failed" ? "managed-policy.failed" : "managed-policy.register-timeout",
+    policyName: policy.name,
+    orchestratorId: policy.orchestratorId,
+    queuedMessages,
+    consecutiveFailures: state.consecutiveFailures,
+    error: opts.error,
+  };
+  if (!recipients.length) {
+    raiseOperatorAlarm({
+      clientId: `managed-policy-alarm-${opts.phase}-${policy.name}-${policy.orchestratorId}`,
+      source: "lifecycle-manager",
+      subject,
+      detail: `${body}\nNo owner, coordinator, or fallback is reachable to page.`,
+      view: "managed-agents",
+      metadata: payload,
+    });
+    return;
+  }
+  routeNotification({
+    type: "agent.spawn_failed",
+    scope: { target: `policy:${policy.name}` },
+    recipients,
+    message: {
+      subject,
+      body,
+      payload,
+      // Once per failed episode (failed: this spawn's request id; register-timeout: once per
+      // policy+host) — dedups so a wedged policy pages the coordinator once, not every tick.
+      idempotencyKey: opts.phase === "failed"
+        ? `managed-policy-failed:${policy.name}:${state.spawnRequestId ?? state.consecutiveFailures}`
+        : `managed-policy-register-timeout:${policy.name}:${policy.orchestratorId}`,
+      replyExpected: false,
+    },
+  });
+}
+
+export function escalateOfflineOrchestrator(policy: SpawnPolicy, state: ManagedAgentState, orch: Orchestrator | null | undefined): void {
+  if (state.consecutiveFailures < ORCHESTRATOR_OFFLINE_ESCALATION_FAILURES) return;
+  const recipients = managedPolicyEscalationRecipients(policy, state);
   if (!recipients.length) return;
   const host = orch?.hostname ? `${orch.hostname} (${policy.orchestratorId})` : policy.orchestratorId;
   const queuedMessages = queuedPolicyMessageCount(policy.name);

package/src/mcp/tools-spawn.ts

@@ -12,7 +12,7 @@ import { countLiveSpawnedAgents, listAgents, listWorkspaces, ValidationError } f
 import { listCommands } from "../commands-db";
 import { DEFAULT_SPAWN_PROFILE_NAME } from "../config-store";
 import { optionalEnum } from "../validation";
-import { APPROVAL_MODES, AUTO_MERGE_POLICIES, SPAWN_PROVIDERS, stringValue, VALID_AGENT_LIFECYCLES, VALID_EFFORTS, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
+import { APPROVAL_MODES, AUTO_MERGE_POLICIES, REPORT_VERBOSITIES, SPAWN_PROVIDERS, stringValue, VALID_AGENT_LIFECYCLES, VALID_EFFORTS, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
 import type { ProviderEffort } from "agent-relay-sdk/provider-catalog";
 import type { AgentCard, AgentLifecycle, Command, SpawnApprovalMode, SpawnProvider, WorkspaceAutoMergePolicy, WorkspaceLandingPolicy, WorkspaceMode, WorkspaceRecord } from "../types";
 import type { McpAuthContext, ToolDefinition } from "./types";
@@ -74,7 +74,9 @@ export const SPAWN_TOOLS: ToolDefinition[] = [
           required: ["branch", "mode"],
           additionalProperties: false,
         },
+        reportVerbosity: { type: "string", enum: REPORT_VERBOSITIES, description: "#1037 — how much of this worker's turn output reaches you (the spawner). `quiet` (default): only the worker's turn-final report, and only once it goes idle/awaiting-input — mid-task narration is suppressed. `normal`: every turn-final response, forwarded immediately. `verbose`: every turn-final response plus all narration/reasoning/tool steps. Lifecycle signals (ready/exit/merge), escalations, and messages the worker addresses to you directly always arrive regardless." },
         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 0 = fire-and-forget; you will be PUSHED agent.ready when the child is ready)." },
+        verbose: { type: "boolean", description: "#1033 — return the FULL spawn detail (resolved agent profile + provisioning manifest + the dispatched command payload) instead of the default lean receipt. Off by default: the lean receipt is `{ok, spawnRequestId, agentId, taskId, orchestratorId, provider, registered, status}` — everything you need to track/shutdown the child, without the ~50-60KB profile/manifest + triple prompt echo that blows the tool-result cap. Set true only when you actually need to inspect the resolved provisioning." },
       },
       required: ["provider"],
       additionalProperties: false,
@@ -166,21 +168,29 @@ export async function relaySpawnAgent(auth: McpAuthContext, args: Record<string,
     requestedVia: "mcp",
     waitForRegistrationMs: optionalNonNegativeInt(args.waitForRegistrationMs, "waitForRegistrationMs") ?? 0,
     resumeWorkspace: parseResumeWorkspace(args.resumeWorkspace),
+    reportVerbosity: optionalEnum(args.reportVerbosity, "reportVerbosity", REPORT_VERBOSITIES),
   };
+  const verbose = optionalBoolean(args.verbose, "verbose") === true;
   const result = await spawnAgent(input, authContextFromMcp(auth));
-  // #734 — return the lean shape callers need (spawnRequestId + agentId for idempotency/shutdown)
-  // plus a sanitized command summary. The full resolved provisioning already went to the
-  // orchestrator on the dispatched command; echoing it here blows the MCP result token cap.
-  return {
+  // #1033 — LEAN RECEIPT by default. The full resolved provisioning (agent profile + manifest +
+  // plugin file listing) and the hydrated prompt (echoed three times across params.prompt,
+  // systemPromptAppend and relayInjectionEvents) already went to the orchestrator on the DISPATCHED
+  // command; echoing any of it back to the caller is ~50-60KB that blows the MCP result token cap
+  // (#1033) for zero orchestration value — the caller only needs the identity fields to track /
+  // shutdown the child. Full detail (behind #734's content-stripped summary) is opt-in via `verbose`.
+  const receipt: Record<string, unknown> = {
     ok: result.ok,
     spawnRequestId: result.spawnRequestId,
     orchestratorId: result.orchestratorId,
     provider: result.provider,
     agentId: result.agentId,
     registered: result.registered,
-    command: summarizeSpawnCommandForCaller(result.command),
+    status: result.registered ? "registered" : "pending",
+    ...(result.taskId !== undefined ? { taskId: result.taskId } : {}),
     ...(result.task ? { task: result.task } : {}),
   };
+  if (verbose) receipt.command = summarizeSpawnCommandForCaller(result.command);
+  return receipt;
 }
 
 export function relaySpawnTargets(auth: McpAuthContext): Record<string, unknown> {

package/src/mcp-plan-tools.ts

@@ -22,7 +22,7 @@ const PLAN_NODE_REFS_SCHEMA = {
   type: "object",
   properties: {
     taskId: { oneOf: [{ type: "string" }, { type: "integer", minimum: 1 }] },
-    issueId: { type: "string" },
+    issueId: { type: "string", description: "issue_<id>, #number, owner/repo#number, or a GitHub issue URL. A bare #number resolves against the calling agent's own project repo (cwd → project → issueRepo), falling back to AGENT_RELAY_DEFAULT_ISSUE_REPO/GITHUB_REPOSITORY (#220) — it throws if neither is configured." },
   },
   additionalProperties: false,
 } as const;
@@ -56,7 +56,7 @@ const PLAN_EDGE_SCHEMA = {
 export const PLAN_TOOLS = [
   {
     name: "relay_plan_create",
-    description: "Create a persisted, versioned plan DAG attached to a message thread/channel. MVP statusSource is always manual.",
+    description: "Create a persisted, versioned plan DAG attached to a message thread/channel. threadId is optional — omit it and a thread is minted server-side (#1035), so a fresh coordinator needn't send a throwaway message just to anchor a plan. MVP statusSource is always manual.",
     requiredScopes: ["plans:write"],
     inputSchema: {
       type: "object",
@@ -69,7 +69,6 @@ export const PLAN_TOOLS = [
         nodes: { type: "array", items: PLAN_NODE_SCHEMA },
         edges: { type: "array", items: PLAN_EDGE_SCHEMA },
       },
-      required: ["threadId"],
       additionalProperties: false,
     },
   },

package/src/notification-settings.ts

@@ -25,6 +25,7 @@ export const NOTIFICATIONS_CONFIG_DEFAULTS: NotificationsConfig = {
   agentReady: true,
   agentExited: true,
   agentSpawnFailed: true,
+  humanEscalationChannelId: "ntfy:default",
   contextThreshold: DEFAULT_CONTEXT_THRESHOLD_CONFIG,
   quotaThreshold: DEFAULT_QUOTA_THRESHOLD_CONFIG,
 };
@@ -63,6 +64,7 @@ export const NOTIFICATIONS_SETTINGS_SCHEMA: JSONSchema = {
     agentReady: { type: "boolean" },
     agentExited: { type: "boolean" },
     agentSpawnFailed: { type: "boolean" },
+    humanEscalationChannelId: { type: "string", maxLength: 200 },
     contextThreshold: CONTEXT_THRESHOLD_SETTINGS_SCHEMA,
     quotaThreshold: QUOTA_THRESHOLD_SETTINGS_SCHEMA,
   },
@@ -103,6 +105,7 @@ export function validateNotificationSettingsLayer(value: unknown): NotificationS
     ...(bool("agentReady") !== undefined ? { agentReady: bool("agentReady")! } : {}),
     ...(bool("agentExited") !== undefined ? { agentExited: bool("agentExited")! } : {}),
     ...(bool("agentSpawnFailed") !== undefined ? { agentSpawnFailed: bool("agentSpawnFailed")! } : {}),
+    ...(value.humanEscalationChannelId === undefined ? {} : { humanEscalationChannelId: cleanOptionalString(value.humanEscalationChannelId, "humanEscalationChannelId", 200) }),
     ...(value.contextThreshold === undefined ? {} : { contextThreshold: validateContextThresholdConfig(value.contextThreshold) }),
     ...(value.quotaThreshold === undefined ? {} : { quotaThreshold: validateQuotaThresholdConfig(value.quotaThreshold) }),
   };
@@ -144,6 +147,14 @@ function cleanBoolean(value: unknown, field: string): boolean {
   return value;
 }
 
+function cleanOptionalString(value: unknown, field: string, max: number): string {
+  if (typeof value !== "string") throw new ValidationError(`${field} must be a string`);
+  const clean = value.trim();
+  if (clean.length > max) throw new ValidationError(`${field} must be at most ${max} characters`);
+  if (clean.includes("\n") || clean.includes("\r")) throw new ValidationError(`${field} must not contain newlines`);
+  return clean;
+}
+
 function cleanLayerId(value: string, field: string): string {
   const clean = value.trim();
   if (!clean) throw new ValidationError(`${field} required`);

package/src/notification-types.ts

@@ -28,6 +28,7 @@ export type NotificationType =
   | "agent.quota_threshold"
   | "agent.resume_budget_warning"
   | "agent.resume_budget_exhausted"
+  | "agent.resume_injection_failed"
   | "agent.transient_land_hold"
   | "agent.rate_limit_resume"
   | "agent.provider_blocked"
@@ -127,6 +128,9 @@ export const DEFAULT_TTL_MS: Record<NotificationType, number | null> = {
   "agent.quota_threshold": 15 * MINUTES,
   "agent.resume_budget_warning": null,
   "agent.resume_budget_exhausted": null,
+  // #1023 — the agent may be running with an empty/stale context; durable like the other
+  // resume-lifecycle notices above, not a bystander ping that should silently expire.
+  "agent.resume_injection_failed": null,
   "agent.transient_land_hold": null,
   "agent.rate_limit_resume": 15 * MINUTES,
   "agent.provider_blocked": null,

package/src/operator-alarm.ts

@@ -0,0 +1,37 @@
+import { createActivityEvent } from "./db";
+import { emitRelayEvent } from "./events";
+
+export interface OperatorAlarmInput {
+  /** Stable client id → repeated alarms for the same condition dedup instead of spamming the timeline. */
+  clientId: string;
+  source: string;
+  subject: string;
+  detail: string;
+  view?: string;
+  metadata?: Record<string, unknown>;
+}
+
+// A "louder", operator-visible signal for a condition that would otherwise be swallowed —
+// specifically an escalation that resolved to ZERO reachable recipients (#1021 A3/A4). A
+// normal escalation pages an agent; when there is no agent to page (owner exited,
+// coordinator idle, no fallback configured) the escalation must not silently mark itself
+// done. This raises a distinct `operator.alarm` relay event (dashboard banner) plus a
+// persisted `operator`-kind activity event, so a relay with no reachable escalation target
+// is observable instead of looping forever in the dark.
+export function raiseOperatorAlarm(input: OperatorAlarmInput): void {
+  emitRelayEvent({
+    type: "operator.alarm",
+    source: input.source,
+    subject: input.subject,
+    data: { subject: input.subject, detail: input.detail, ...(input.metadata ?? {}) },
+  });
+  createActivityEvent({
+    clientId: input.clientId,
+    kind: "operator",
+    title: input.subject,
+    body: input.detail,
+    icon: "ti-alert-octagon",
+    view: input.view ?? "orchestrators",
+    metadata: { source: input.source, operatorAlarm: true, ...(input.metadata ?? {}) },
+  });
+}

package/src/routes/agents.ts

@@ -9,6 +9,7 @@ import { emitAgentRemoved, emitAgentStatus } from "../sse";
 import { notifyAgentReady } from "../agent-lifecycle-events";
 import { bindSpawnedTaskToReadyAgent } from "../services/register-agent";
 import { flushQueuedDirectMessages } from "../services/managed-running";
+import { flushIdleLineageReport } from "../services/send-message";
 import { isAgentUnavailable } from "../db/agent-predicates";
 import { getCompactionWatch } from "../compaction-watch";
 import { isRecord } from "agent-relay-sdk";
@@ -198,6 +199,9 @@ export const patchAgentStatus: Handler = async (req, params) => {
     const before = getAgent(params.id!);
     if (!setStatus(params.id!, body.status as (typeof VALID_AGENT_STATUSES)[number], guard)) return error("agent not found", 404);
     auditAgentStateTransition(params.id!, before, getAgent(params.id!));
+    // #1040 — the HTTP status PATCH is also a busy→idle edge (a runner without a live bus socket).
+    // Flush any held turn-final report-up so it reaches the spawner on this path too.
+    if (before?.status === "busy" && body.status !== "busy") flushIdleLineageReport(params.id!);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;

package/src/routes/orchestrator-proxy.ts

@@ -5,7 +5,7 @@ import { authorizeRoute, cleanJsonArray, error, json, type Handler } from "./_sh
 import { cleanStringArray } from "../validation";
 import { emitOrchestratorStatus } from "../sse";
 import { type OrchestratorRuntimeInput, type SpawnProvider } from "../types";
-import { relayToken } from "../config";
+import { isTrustedOrchestratorApiUrl, relayToken } from "../config";
 import { isTerminalSessionRequestAuthorized } from "../terminal-authz";
 
 export const getOrchestratorDirectories: Handler = async (req, params) => {
@@ -13,6 +13,9 @@ export const getOrchestratorDirectories: Handler = async (req, params) => {
   if (!orch) return error("orchestrator not found", 404);
   if (!orch.apiUrl) return error("orchestrator does not expose an API", 422);
   if (orch.status !== "online") return error("orchestrator is offline", 422);
+  // #1024 — never forward the relay master token (or the caller's query string) to an untrusted
+  // apiUrl. Refuse the proxy outright rather than leak credentials to an attacker-controlled host.
+  if (!isTrustedOrchestratorApiUrl(orch.apiUrl)) return error("orchestrator apiUrl is not a trusted origin", 502);
   const url = new URL(req.url);
   const path = url.searchParams.get("path") || "";
   const proxyUrl = `${orch.apiUrl}/api/directories${path ? `?path=${encodeURIComponent(path)}` : ""}`;
@@ -30,6 +33,9 @@ export const postOrchestratorCreateDirectory: Handler = async (req, params) => {
   if (!orch) return error("orchestrator not found", 404);
   if (!orch.apiUrl) return error("orchestrator does not expose an API", 422);
   if (orch.status !== "online") return error("orchestrator is offline", 422);
+  // #1024 — never forward the relay master token (or the caller's query string) to an untrusted
+  // apiUrl. Refuse the proxy outright rather than leak credentials to an attacker-controlled host.
+  if (!isTrustedOrchestratorApiUrl(orch.apiUrl)) return error("orchestrator apiUrl is not a trusted origin", 502);
   try {
     const body = await req.json();
     const res = await fetch(`${orch.apiUrl}/api/directories`, {
@@ -62,6 +68,9 @@ async function proxyOrchestratorGet(req: Request, orchestratorId: string, path:
   if (!orch) return error("orchestrator not found", 404);
   if (!orch.apiUrl) return error("orchestrator does not expose an API", 422);
   if (orch.status !== "online") return error("orchestrator is offline", 422);
+  // #1024 — never forward the relay master token (or the caller's query string) to an untrusted
+  // apiUrl. Refuse the proxy outright rather than leak credentials to an attacker-controlled host.
+  if (!isTrustedOrchestratorApiUrl(orch.apiUrl)) return error("orchestrator apiUrl is not a trusted origin", 502);
   const incoming = new URL(req.url);
   const proxyUrl = `${orch.apiUrl}${path}${incoming.search}`;
   const headers: Record<string, string> = {};
@@ -85,6 +94,9 @@ async function proxyOrchestratorPost(req: Request, orchestratorId: string, path:
   if (!orch) return error("orchestrator not found", 404);
   if (!orch.apiUrl) return error("orchestrator does not expose an API", 422);
   if (orch.status !== "online") return error("orchestrator is offline", 422);
+  // #1024 — never forward the relay master token (or the caller's query string) to an untrusted
+  // apiUrl. Refuse the proxy outright rather than leak credentials to an attacker-controlled host.
+  if (!isTrustedOrchestratorApiUrl(orch.apiUrl)) return error("orchestrator apiUrl is not a trusted origin", 502);
   const incoming = new URL(req.url);
   const proxyUrl = `${orch.apiUrl}${path}${incoming.search}`;
   const headers: Record<string, string> = {

package/src/routes/orchestrator.ts

@@ -11,6 +11,7 @@ import { createCommand, updateCommand } from "../commands-db";
 import { emitAgentStatus, emitOrchestratorStatus } from "../sse";
 import { getLifecycleManager } from "../lifecycle-manager";
 import { issueOrchestratorRuntimeToken } from "../runtime-tokens";
+import { isOrchestratorRegistrationAuthorized } from "../security";
 import { type ManagedAgent, type ManagedSessionExitDiagnostics, type OrchestratorRuntimeInput, type RegisterOrchestratorInput, type SpawnApprovalMode, type SpawnProvider } from "../types";
 
 function cleanProtocolVersion(value: unknown): number | undefined {
@@ -51,6 +52,9 @@ function cleanRuntimeCapabilities(value: unknown): RuntimeCapabilities | undefin
 }
 
 export const postOrchestrator: Handler = async (req) => {
+  // #1024 — registering/upserting an orchestrator is admin-class; a provider-agent runtime token
+  // must NOT be able to seed a rogue orchestrator row (its apiUrl is the master-token exfil sink).
+  if (!isOrchestratorRegistrationAuthorized(req)) return error("forbidden", 403);
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {