agent-relay-server 0.121.0 → 0.121.2

package/src/db/message-reads.ts

@@ -1,6 +1,6 @@
 import { Database } from "bun:sqlite";
 import { randomUUID } from "node:crypto";
-import { isRecord, stringValue, isMechanicalMessageKind } from "agent-relay-sdk";
+import { isRecord, stringValue, isMechanicalMessageKind, isReportVerbosity, type ReportVerbosity } from "agent-relay-sdk";
 import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "../config.ts";
 import { parseJson } from "../utils";
 import { isLiveIsolatedWorkspace } from "../workspace-phase";
@@ -19,7 +19,7 @@ import { sendMessageWithResult } from "./messages.ts";
 import { deleteArtifactLinksForEntity } from "./artifacts.ts";
 import { getDb, getDbPath, runDbMaintenanceWorker, timedQuery } from "./connection.ts";
 import { legacyChannelTargets, isChannelAgentId } from "./delivery.ts";
-import { messageTaskClosed } from "./claim-sql.ts";
+import { claimableHandledNoTask, messageTaskClosed } from "./claim-sql.ts";
 import { MSG_SELECT, rowToMessage } from "./mappers.ts";
 import type {
   AgentCard,
@@ -306,7 +306,11 @@ export function pollMessages(query: PollQuery): Message[] {
     targetClauses.push(freshFanoutTargetClause(`tag:${tag}`, agent, params));
   }
   for (const cap of agentCaps) {
+    // A capability fan-out is accepted at send time under both `cap:` and its `capability:` alias
+    // (planSend/FANOUT_PREFIXES + the SDK matcher). Poll for BOTH stored forms, or a message sent
+    // to `capability:X` gets a delivered receipt yet is invisible to every poll (#1022 F3).
     targetClauses.push(freshFanoutTargetClause(`cap:${cap}`, agent, params));
+    targetClauses.push(freshFanoutTargetClause(`capability:${cap}`, agent, params));
   }
   if (agentLabel) {
     targetClauses.push(freshFanoutTargetClause(`label:${agentLabel}`, agent, params));
@@ -338,7 +342,9 @@ export function pollMessages(query: PollQuery): Message[] {
   // pruned/deleted its message claims are released to NULL (see pruneOfflineAgents/deleteAgent),
   // so without it a finished task's message resurrects as fresh work on the next restart (which
   // mints a new agent id, so message_reads no longer dedups it) — the automation re-delivery bug.
-  conditions.push(`(claimable = 0 OR claimed_by = ? OR ((claimed_by IS NULL OR claim_expires_at IS NULL OR claim_expires_at <= ?) AND NOT ${messageTaskClosed("m.id")}))`);
+  // `claimableHandledNoTask` closes the same gap for claimables with NO linked task: once the
+  // holder handled one, its lease expired and it got re-offered to everyone forever (#1022 F6).
+  conditions.push(`(claimable = 0 OR claimed_by = ? OR ((claimed_by IS NULL OR claim_expires_at IS NULL OR claim_expires_at <= ?) AND NOT ${messageTaskClosed("m.id")} AND NOT ${claimableHandledNoTask("m.id")}))`);
   params.push(query.for, Date.now());
 
   if (query.sinceId !== undefined) {
@@ -594,6 +600,30 @@ export function seedSpawnPromptMirror(
   }
 }
 
+/**
+ * #1037 — the per-spawn report-up verbosity a spawner chose, read from the persisted `agent.spawn`
+ * command params by spawnRequestId. Mirrors seedSpawnPromptMirror: at first registration the relay
+ * has both the resolved child id and the spawn command, so registration stamps this onto child meta
+ * where the lineage report-up delivery gate reads it. Returns undefined when absent/unparseable
+ * (the gate then defaults to `quiet`).
+ */
+export function readSpawnReportVerbosity(spawnRequestId: string | undefined): ReportVerbosity | undefined {
+  if (!spawnRequestId) return undefined;
+  try {
+    const row = getDb().query(`
+      SELECT params FROM commands
+      WHERE type = 'agent.spawn' AND correlation_id = ?
+      ORDER BY created_at DESC
+      LIMIT 1
+    `).get(spawnRequestId) as { params: string } | undefined;
+    const params = row ? parseJson<unknown>(row.params, {}) : {};
+    if (!isRecord(params)) return undefined;
+    return isReportVerbosity(params.reportVerbosity) ? params.reportVerbosity : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export function markRead(messageId: number, agentId: string): boolean {
   const exists = getDb().query("SELECT 1 FROM messages WHERE id = ?").get(messageId);
   if (!exists) return false;
@@ -607,7 +637,7 @@ export function markRead(messageId: number, agentId: string): boolean {
         delivery_next_retry_at = NULL,
         delivery_poison_reason = NULL,
         delivery_updated_at = ?
-    WHERE id = ? AND (to_target = ? OR resolved_to_agent = ? OR to_target = 'broadcast' OR to_target LIKE 'tag:%' OR to_target LIKE 'cap:%' OR to_target LIKE 'label:%' OR to_target LIKE 'team:%')
+    WHERE id = ? AND (to_target = ? OR resolved_to_agent = ? OR to_target = 'broadcast' OR to_target LIKE 'tag:%' OR to_target LIKE 'cap:%' OR to_target LIKE 'capability:%' OR to_target LIKE 'label:%' OR to_target LIKE 'team:%')
   `).run(Date.now(), messageId, agentId, agentId);
   return true;
 }

package/src/db/messages.ts

@@ -1,6 +1,7 @@
 import { Database } from "bun:sqlite";
 import { randomUUID } from "node:crypto";
-import { isRecord, stringValue, isMechanicalMessageKind } from "agent-relay-sdk";
+import { isRecord, stringValue, isMechanicalMessageKind, isReportVerbosity, type ReportVerbosity } from "agent-relay-sdk";
+import { LIFECYCLE_STATE_WORKING, childSignalKey, stampLifecycleSignal, taskSignalKey } from "../lifecycle-signal-registry";
 import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "../config.ts";
 import { parseJson } from "../utils";
 import { isLiveIsolatedWorkspace } from "../workspace-phase";
@@ -13,7 +14,7 @@ import {
   type RuntimeContracts,
 } from "../contracts";
 import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS, DEFAULT_FANOUT_TTL_SECONDS } from "../config";
-import { matchAgents } from "../agent-ref";
+import { matchAgents, messageMatchesAgent } from "../agent-ref";
 import { isFanoutTarget } from "../channel-target";
 import { getAgent, validateAgentSession } from "./agents.ts";
 import { cleanAttachmentRefs, linkAttachmentRefs, validateAttachmentRefs } from "./artifacts.ts";
@@ -26,6 +27,7 @@ import { getMessage } from "./message-queries.ts";
 import { childStreamSubscribed, type ChildStream } from "./notification-subscriptions.ts";
 import { runningAgentForPolicy } from "./policy-runtime.ts";
 import { getTask, releaseExpiredClaims } from "./tasks.ts";
+import { deliverableTaskIdsBySpawnRequestId } from "./task-entity.ts";
 import { insertTaskEvent, claimTaskWhere, CLAIM_TASK_KIND } from "./task-core.ts";
 import type {
   AgentCard,
@@ -334,6 +336,105 @@ function findRecentExplicitLineageDuplicate(input: {
   return row ? rowToMessage(row) : null;
 }
 
+/** Per-spawn report-up verbosity (#1037), read from the child's meta; defaults to `quiet`. */
+function reportVerbosityOf(child: AgentCard): ReportVerbosity {
+  const value = child.meta?.reportVerbosity;
+  return isReportVerbosity(value) ? value : "quiet";
+}
+
+/** The child is mid-turn (not yet idle/awaiting-input). The authoritative "still working" signal. */
+function childIsBusy(child: AgentCard): boolean {
+  return child.status === "busy";
+}
+
+// #1037 — a quiet child's turn-final response that arrives while the child is still busy is a
+// mid-task yield, not the end of its work. Instead of shipping it upstream (mid-work narration) or
+// dropping it (a genuine last turn whose idle status simply hasn't landed yet), we HOLD the latest
+// one per child and flush it when the child transitions to idle (see flushDeferredLineageReport,
+// driven off the bus turn-end edge). Coalescing on childId means only the final turn's report lands.
+const deferredLineageReports = new Map<string, number>();
+
+function deferLineageReport(childId: string, messageId: number): void {
+  deferredLineageReports.set(childId, messageId);
+}
+
+function clearDeferredLineageReport(childId: string): void {
+  deferredLineageReports.delete(childId);
+}
+
+/** Test seam: clear the #1037 deferred report-up hold between tests. */
+export function __resetDeferredLineageReports(): void {
+  deferredLineageReports.clear();
+}
+
+/**
+ * #1037 — flush a child's deferred turn-final report to its spawner. Called when the child
+ * transitions out of busy (idle/awaiting-input): re-runs the promotion, which now passes the idle
+ * gate and delivers. No-op when nothing was deferred. Returns the promoted message, or null.
+ */
+export function flushDeferredLineageReport(childId: string): { message: Message; created: boolean } | null {
+  const messageId = deferredLineageReports.get(childId);
+  if (messageId === undefined) return null;
+  deferredLineageReports.delete(childId);
+  const message = getMessage(messageId);
+  if (!message) return null;
+  return promoteLineageCapturedResponse(message);
+}
+
+/**
+ * #1040/#1041 — the persisted turn-final response captures needed to rebuild the in-memory
+ * deferred-report hold after a relay restart. Bounded by a recency window (a report is only ever
+ * held while its child was mid-turn, so it is inherently recent). Grouped to the single newest
+ * (highest-id) final capture per from_agent child *before* the row cap is applied, so that: (a) an
+ * older mid-task final that #1037 coalesced away — persisted but never given an idempotency key —
+ * is never resurrected alongside the real verdict, and (b) a chatty child's own history can't push
+ * another child's final out of the cap. The caller re-runs promotion, which is idempotent: an
+ * already-delivered capture is a no-op, an idle child's lost report is delivered, and a still-busy
+ * child simply re-defers (holding the newest one, matching the live #1037 coalescing contract).
+ */
+export function listRecentFinalResponseCaptures(sinceMs: number, limit = 1000): Message[] {
+  const rows = getDb().query(`
+    ${MSG_SELECT}
+    INNER JOIN (
+      SELECT from_agent, MAX(id) AS latest_id
+      FROM messages
+      WHERE kind = 'session'
+        AND created_at >= ?
+        AND json_extract(payload, '$.session.type') = 'response'
+        AND json_extract(payload, '$.session.final') = 1
+      GROUP BY from_agent
+    ) latest ON latest.latest_id = m.id
+    ORDER BY m.id DESC
+    LIMIT ?
+  `).all(sinceMs, limit) as any[];
+  return rows
+    .map(rowToMessage)
+    .filter((message) => {
+      const session = sessionMeta(message);
+      return session ? isFinalSessionResponse(session) : false;
+    });
+}
+
+/** Deliverable task ids this child is executing, from its direct meta.taskId + spawnRequestId link. */
+function childTaskIds(child: AgentCard): number[] {
+  const ids = new Set<number>();
+  const direct = child.meta?.taskId;
+  const directNum = typeof direct === "string" ? Number(direct) : direct;
+  if (typeof directNum === "number" && Number.isSafeInteger(directNum) && directNum > 0) ids.add(directNum);
+  const spawnRequestId = stringValue(child.meta?.spawnRequestId);
+  if (spawnRequestId) for (const id of deliverableTaskIdsBySpawnRequestId(spawnRequestId)) ids.add(id);
+  return [...ids];
+}
+
+// #1032b — a delivered report-up is a first-class lifecycle signal to the spawner. Stamp it so a
+// redundant "Task status pulse" for the same child/task is suppressed rather than double-waking.
+// #1038 — a report-up conveys "the child is progressing", so it is state-keyed to `working`: it
+// supersedes only a redundant `working` pulse, never a later distinct milestone (committed/landed/done).
+function stampReportUpLifecycleSignal(parent: string, child: AgentCard): void {
+  stampLifecycleSignal(parent, childSignalKey(child.id));
+  for (const taskId of childTaskIds(child)) stampLifecycleSignal(parent, taskSignalKey(taskId, LIFECYCLE_STATE_WORKING));
+}
+
 export function promoteLineageCapturedResponse(message: Message): { message: Message; created: boolean } | null {
   if (message.kind !== "session") return null;
   const session = sessionMeta(message);
@@ -344,7 +445,17 @@ export function promoteLineageCapturedResponse(message: Message): { message: Mes
   const child = getAgent(message.from);
   const parent = child?.spawnedBy;
   if (!parent) return null;
-  if (stream !== "responses" && !childStreamSubscribed({ parentId: parent, child, stream })) return null;
+  const verbosity = reportVerbosityOf(child);
+  // #1037 verbose: forward every child stream without an explicit per-stream subscription.
+  if (stream !== "responses" && verbosity !== "verbose" && !childStreamSubscribed({ parentId: parent, child, stream })) return null;
+
+  // #1037 — the report-up delivery gate. In `quiet` (default), a turn-final response that arrives
+  // while the child is still busy is mid-task narration: defer it (flushed on the idle transition)
+  // rather than waking the spawner mid-work. `normal`/`verbose` forward every turn-final at once.
+  if (stream === "responses" && verbosity === "quiet" && childIsBusy(child)) {
+    deferLineageReport(child.id, message.id);
+    return null;
+  }
 
   const idempotencyKey = lineageStreamReportKey(message, session, stream);
   const existing = findMessageByIdempotencyKey(message.from, idempotencyKey);
@@ -378,7 +489,7 @@ export function promoteLineageCapturedResponse(message: Message): { message: Mes
     }
   }
 
-  return sendMessageWithResult({
+  const result = sendMessageWithResult({
     from: message.from,
     to: parent,
     kind: "chat",
@@ -390,6 +501,11 @@ export function promoteLineageCapturedResponse(message: Message): { message: Mes
       : { childStreamCapture: { stream, ...session } },
     occurredAt: message.occurredAt ?? message.createdAt,
   });
+  if (stream === "responses" && result.created) {
+    clearDeferredLineageReport(child.id);
+    stampReportUpLifecycleSignal(parent, child);
+  }
+  return result;
 }
 
 // Event time may be queued-then-backfilled, so it can legitimately be older than the
@@ -621,6 +737,14 @@ export function claimMessage(messageId: number, agentId: string, guard?: AgentSe
   // A same-agent re-claim is allowed (idempotent lease refresh, see claimMessageRow); only a
   // claim held by a *different* agent blocks (#261).
   if (msg.claimedBy && msg.claimedBy !== agentId) return { ok: false, error: `already claimed by ${msg.claimedBy}` };
+  // The claimer must actually be a recipient — the same predicate that gates live delivery (bus/sse
+  // push) and poll. Without it an unrelated agent could claim a claimable addressed directly to
+  // someone else, and `pollMessages`/`messageMatchesAgent` then hid it from the rightful recipient,
+  // so the message vanished for its intended owner (#1022 F7). Checked AFTER the claimedBy guard so
+  // a genuine "already claimed" contention still reports that precise reason; a fan-out claimable
+  // (tag:/cap:/broadcast/…) still matches every eligible pool member, and the holder's own re-claim
+  // still matches (claimedBy is null or itself here, so the ownership short-circuit never fires).
+  if (!messageMatchesAgent(msg, agentId, agent)) return { ok: false, error: "message is not addressed to this agent" };
 
   try {
     return getDb().transaction(() => {

package/src/db/pairs.ts

@@ -205,6 +205,7 @@ export function createPair(input: CreatePairInput): {
 
   const resolved = resolvePairTarget(input.target, input.from);
   if (!resolved.ok) return resolved;
+  if (resolved.agent.id === input.from) return { ok: false, code: "invalid", error: "cannot pair with yourself" };
 
   const now = Date.now();
   const ttlMs = Math.min(Math.max(input.ttlMs ?? DEFAULT_PAIR_TTL_MS, 10_000), MAX_PAIR_TTL_MS);

package/src/db/schema.ts

@@ -15,6 +15,8 @@ import {
 import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "../config";
 import { matchAgents } from "../agent-ref";
 import { applyConnectionPragmas, getDb, setDb } from "./connection.ts";
+import { __resetDeferredLineageReports } from "./messages.ts";
+import { __resetLifecycleSignals } from "../lifecycle-signal-registry";
 import { ensureContinuationArchiveSearchSchema } from "./continuation-archives.ts";
 import { applyMigrations } from "./migrations.ts";
 import { PROMPT_TEMPLATES_SCHEMA_SQL, seedPromptTemplatesIfNeeded } from "./prompt-templates-schema";
@@ -92,6 +94,10 @@ export function initDb(path: string = "agent-relay.db"): Database {
   const conn = new Database(path, { create: true });
   applyConnectionPragmas(conn);
   setDb(conn, path);
+  // A fresh DB is a fresh relay: drop in-memory report-up state keyed by the OLD db's message ids /
+  // agent lineage so it can never misfire against reused ids (#1037/#1032b, and per-test isolation).
+  __resetDeferredLineageReports();
+  __resetLifecycleSignals();
 
   getDb().run(`
     CREATE TABLE IF NOT EXISTS agents (

package/src/event-loop-lag.ts

@@ -43,9 +43,18 @@ export function recordEventLoopLagSample(lagMs: number, sampledAt: number = Date
   }
 }
 
-export function getEventLoopLagSnapshot(): EventLoopLagSnapshot {
+// Max lag over the retained ring buffer. SIDE-EFFECT-FREE: unlike
+// getEventLoopLagSnapshot it does NOT reset maxSinceLastReadMs, so a caller that
+// only needs the recent-lag ceiling (the stale reaper's grace, #1048) can read it
+// without stealing the spike the /health poller owns.
+export function eventLoopLagMaxMs(): number {
   let maxMs = 0;
   for (let i = 0; i < sampleCount; i += 1) maxMs = Math.max(maxMs, samples[i] ?? 0);
+  return maxMs;
+}
+
+export function getEventLoopLagSnapshot(): EventLoopLagSnapshot {
+  const maxMs = eventLoopLagMaxMs();
   const maxSinceLastRead = maxSinceLastReadMs;
   maxSinceLastReadMs = 0;
   return {

package/src/gate-resolver.ts

@@ -0,0 +1,124 @@
+// #1036 — resolve the validation/land gate commands for a repo WITHOUT hardcoding
+// `bun test`. agent-relay is a bun repo, and that assumption used to leak into every
+// foreign repo the steward operated on: running `bun test` in a Jest-only repo
+// produced bogus failures and refused a genuinely-green branch. Derive the gate,
+// never assume the home-repo runner.
+//
+// Priority order:
+//   1. Project-config pin — the repo's own `.agent-relay/land-gates.json` (#892) wins
+//      outright. A project that declared gates knows better than any heuristic.
+//   2. Derive from `package.json` — run the repo's DECLARED scripts via its detected
+//      package manager (from `packageManager` field or lockfile). A repo whose
+//      `scripts.test` is `jest` gets `<pm> run test`, never `bun test`.
+//   3. Default — the legacy bun heuristic, only when there's nothing to derive from
+//      (no repo path, or no readable package.json).
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadRepoLandGates } from "./land-gates";
+
+export interface StewardCheck {
+  command: string;
+  reason: string;
+  cwd?: string;
+}
+
+export type PackageManager = "bun" | "npm" | "pnpm" | "yarn";
+
+interface PackageInfo {
+  pm: PackageManager;
+  scripts: Record<string, string>;
+}
+
+/** Detect the repo's package manager from its `packageManager` field, then its
+ *  lockfile. Defaults to npm — the ecosystem default when nothing else is declared. */
+export function detectPackageManager(repoRoot: string, packageManagerField?: unknown): PackageManager {
+  if (typeof packageManagerField === "string") {
+    const name = packageManagerField.split("@")[0]?.trim().toLowerCase();
+    if (name === "bun" || name === "pnpm" || name === "yarn" || name === "npm") return name;
+  }
+  if (existsSync(join(repoRoot, "bun.lock")) || existsSync(join(repoRoot, "bun.lockb"))) return "bun";
+  if (existsSync(join(repoRoot, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(repoRoot, "yarn.lock"))) return "yarn";
+  if (existsSync(join(repoRoot, "package-lock.json"))) return "npm";
+  return "npm";
+}
+
+/** Read `package.json` scripts + detect the package manager. Returns null when there
+ *  is no readable/parseable package.json (→ caller falls back to the default). */
+function readPackageInfo(repoRoot: string): PackageInfo | null {
+  let raw: string;
+  try {
+    raw = readFileSync(join(repoRoot, "package.json"), "utf8");
+  } catch {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const record = parsed as Record<string, unknown>;
+  const rawScripts = record.scripts;
+  const scripts: Record<string, string> = {};
+  if (typeof rawScripts === "object" && rawScripts !== null) {
+    for (const [k, v] of Object.entries(rawScripts as Record<string, unknown>)) {
+      if (typeof v === "string") scripts[k] = v;
+    }
+  }
+  return { pm: detectPackageManager(repoRoot, record.packageManager), scripts };
+}
+
+/**
+ * Suggest validation gate commands from a workspace's changed files, deriving the
+ * runner from the repo (never hardcoding `bun test`) when `repoRoot` is known.
+ *
+ * @param files    changed file paths (drive which checks are relevant)
+ * @param repoRoot the repo/worktree to derive gates from; omit → legacy bun default
+ */
+export function resolveStewardChecks(files: string[], repoRoot?: string): StewardCheck[] {
+  const has = (re: RegExp) => files.some((f) => re.test(f));
+
+  // 1. Project-config pin: repo-authored land gates override every heuristic.
+  if (repoRoot) {
+    try {
+      const gates = loadRepoLandGates(repoRoot);
+      if (gates.length)
+        return gates.map((g) => ({ command: g.command, reason: `pinned land gate "${g.name}"`, ...(g.cwd ? { cwd: g.cwd } : {}) }));
+    } catch {
+      // A malformed land-gates.json is caught by the real land-gate runner (#902);
+      // for a mere check suggestion, fall through to derivation rather than throw.
+    }
+  }
+
+  const checks: StewardCheck[] = [];
+
+  // 2. Derive from package.json: run the repo's DECLARED scripts via its package manager.
+  const pkg = repoRoot ? readPackageInfo(repoRoot) : null;
+  if (pkg) {
+    const runScript = (name: string) => `${pkg.pm} run ${name}`;
+    if (has(/\.(ts|tsx|mts|cts)$/) && pkg.scripts.typecheck) {
+      checks.push({ command: runScript("typecheck"), reason: "TypeScript files changed" });
+    }
+    if (pkg.scripts.test) {
+      if (has(/\.test\.|(^|\/)tests?\//)) checks.push({ command: runScript("test"), reason: "test files changed" });
+      else if (files.length) checks.push({ command: runScript("test"), reason: "repo default" });
+    } else if (pkg.pm === "bun") {
+      // bun runs tests with no declared script; a missing scripts.test doesn't mean "no tests".
+      if (has(/\.test\.|(^|\/)tests?\//)) checks.push({ command: "bun test", reason: "test files changed" });
+      else if (files.length) checks.push({ command: "bun test", reason: "repo default" });
+    }
+    if (has(/(^|\/)dashboard\//) && pkg.scripts["build:dashboard"]) {
+      checks.push({ command: runScript("build:dashboard"), reason: "dashboard sources changed" });
+    }
+    return checks;
+  }
+
+  // 3. Default (last resort): no package.json to derive from — legacy bun heuristic.
+  if (has(/\.(ts|tsx|mts|cts)$/)) checks.push({ command: "bun run typecheck", reason: "TypeScript files changed" });
+  if (has(/\.test\.|(^|\/)tests?\//)) checks.push({ command: "bun test", reason: "test files changed" });
+  else if (files.length) checks.push({ command: "bun test", reason: "repo default" });
+  if (has(/(^|\/)dashboard\//)) checks.push({ command: "bun run build:dashboard", reason: "dashboard sources changed" });
+  return checks;
+}

package/src/lifecycle-manager.ts

@@ -5,7 +5,7 @@ import { createActivityEvent, deleteWorkspace, getAgent, getDb, getOrchestrator,
 import { getManagedAgentState, listSpawnPolicies, updateManagedAgentState, upsertManagedAgentState } from "./config-store";
 import { emitRelayEvent } from "./events";
 import { alwaysReloadTags, reconcileLifecycleContextPressure, requestAgentCompact } from "./lifecycle-context-pressure";
-import { escalateOfflineOrchestrator } from "./managed-policy-escalation";
+import { escalateManagedSpawnFailure, escalateOfflineOrchestrator } from "./managed-policy-escalation";
 import { markManagedAgentRunning, emitManagedState } from "./services/managed-running";
 import { authContextFromSystem } from "./services/auth-context";
 import { emitCommandEvent } from "./command-events";
@@ -31,6 +31,13 @@ interface LifecycleManagerOptions {
   now?: () => number;
 }
 
+// #1021 A1 — the outcome of trying to wake an on-demand policy via a queued message. A
+// caller (e.g. wakeRepoSteward) must be able to tell "a live agent will handle this" from
+// "nothing spawned" so it never claims a hand-off that didn't happen.
+export type PolicySpawnOutcome =
+  | { woke: true; via: "spawned" | "already-active"; command?: Command }
+  | { woke: false; reason: string };
+
 export class LifecycleManager {
   private timer?: Timer;
   private readonly tickMs: number;
@@ -69,12 +76,19 @@ export class LifecycleManager {
     }
   }
 
-  onMessageForPolicy(policyName: string): void {
+  onMessageForPolicy(policyName: string): PolicySpawnOutcome {
     const policy = this.loadPolicies().find((item) => item.name === policyName);
-    if (!policy || policy.mode !== "on-demand" || policy.enabled === false) return;
+    if (!policy) return { woke: false, reason: `no spawn policy '${policyName}'` };
+    if (policy.mode !== "on-demand") return { woke: false, reason: `spawn policy '${policyName}' is not on-demand` };
+    if (policy.enabled === false) return { woke: false, reason: `spawn policy '${policyName}' is disabled` };
     const state = getManagedAgentState(policy.name);
-    if (state && ["starting", "running", "stopping"].includes(state.status)) return;
-    this.spawnAgent(policy, "message-trigger");
+    // A live (or coming-up / draining) agent will pick up the queued message — that IS a wake.
+    if (state && ["starting", "running", "stopping"].includes(state.status)) return { woke: true, via: "already-active" };
+    // #1021 A1 — spawnAgent returns null when the pinned host is offline; that is a spawn
+    // FAILURE, not a success. Propagate it so callers don't stamp a false hand-off.
+    const command = this.spawnAgent(policy, "message-trigger");
+    if (!command) return { woke: false, reason: `steward spawn failed for '${policyName}' (owning host offline)` };
+    return { woke: true, via: "spawned", command };
   }
 
   // NOTE: the bus registration path used to call `onAgentRegistered` here for the
@@ -136,7 +150,7 @@ export class LifecycleManager {
           (state.tmuxSession && agent.tmuxSession === state.tmuxSession) ||
           (agent.policyName === policy.name && (!state.spawnRequestId || agent.spawnRequestId === state.spawnRequestId))
         ));
-        this.markPolicyFailure(policy, state, exited?.lastError ?? "orchestrator session disappeared", exited);
+        this.markPolicyFailure(policy, state, exited?.lastError ?? "orchestrator session disappeared", { exited });
       } else if (state.status === "stopping" && !reported) {
         const next = updateManagedAgentState(policy.name, {
           status: "stopped",
@@ -322,7 +336,10 @@ export class LifecycleManager {
 
     if (state.status === "starting") {
       if (state.lastSpawnAt && this.now() - state.lastSpawnAt > START_TIMEOUT_MS) {
-        this.markPolicyFailure(policy, state, "spawn timed out before registration");
+        // #1021 A3 — a never-registered spawn has no exit diagnostics, so isFastFailStorm
+        // can never trip and it would back off/retry forever in silence. Flag it so the
+        // escalation fires once it has failed repeatedly.
+        this.markPolicyFailure(policy, state, "spawn timed out before registration", { registerTimeout: true });
       }
       return;
     }
@@ -410,22 +427,33 @@ export class LifecycleManager {
     this.emitState(state);
   }
 
-  private markPolicyFailure(policy: SpawnPolicy, state: ManagedAgentState, error: string, exited?: ManagedSessionExitDiagnostics): void {
+  private markPolicyFailure(
+    policy: SpawnPolicy,
+    state: ManagedAgentState,
+    error: string,
+    opts: { exited?: ManagedSessionExitDiagnostics; registerTimeout?: boolean } = {},
+  ): void {
     if (state.status === "stopping") return;
     // Read the terminal reason from the adapter-surfaced typed provider state rather
     // than re-parsing raw provider log text (#745 / #725 §4.4 leak #13).
-    const agentId = state.agentId || exited?.agentId;
+    const agentId = state.agentId || opts.exited?.agentId;
     const modelUnavailable = agentId ? agentTerminalFailureMessage(getAgent(agentId)) : null;
     if (modelUnavailable) {
       this.markFailed(policy, state, modelUnavailable);
       return;
     }
     const failures = state.consecutiveFailures + 1;
-    if (isFastFailStorm(failures, exited)) {
+    if (isFastFailStorm(failures, opts.exited)) {
       this.markFailed(policy, state, error);
       return;
     }
     this.markBackoff(policy, state, error, failures);
+    // #1021 A3 — a register-never spawn never reaches markFailed (no exit diagnostics), so
+    // without this its escalation would never fire. Escalate once it has failed repeatedly.
+    if (opts.registerTimeout && failures >= MAX_FAST_FAILURES) {
+      const next = getManagedAgentState(policy.name);
+      if (next) escalateManagedSpawnFailure(policy, next, { phase: "register-timeout", error });
+    }
   }
 
   private markBackoff(policy: SpawnPolicy, state: ManagedAgentState, error: string, failures = state.consecutiveFailures + 1): void {
@@ -465,6 +493,9 @@ export class LifecycleManager {
       lastError: error,
     });
     this.emitState(next);
+    // #1021 A3 — a failed policy stops retrying (reconcilePolicy returns on `failed`
+    // forever). Tell the coordinator/owner instead of leaving only a dashboard state.
+    escalateManagedSpawnFailure(policy, next, { phase: "failed", error });
   }
 
   private backoffDelay(policy: SpawnPolicy, state: ManagedAgentState | null): number {

package/src/lifecycle-signal-registry.ts

@@ -0,0 +1,87 @@
+// #1032b — cross-subsystem "a first-class lifecycle event already told this spawner about this
+// subject" registry. A spawned child's state reaches its spawner through TWO independent lanes:
+//   1. First-class lifecycle notifications — agent.ready, the lineage report-up (turn-final
+//      response), agent.exited, branch.landed/merge.
+//   2. "Task status pulse" digests emitted from task transitions (working / committed-on-branch /
+//      landed-on-main / done / …).
+// When lane 1 has just conveyed the state, the lane-2 pulse is redundant noise that wakes the
+// spawner a second time for the same fact. This registry is the shared memory: lane-1 emitters
+// STAMP `(recipient, subjectKey)`; the pulse enqueue/flush path CHECKS it and suppresses.
+//
+// In-memory + short-TTL by design: it only needs to catch the near-simultaneous double-notify
+// (both lanes fire within seconds of the same underlying event). A relay restart wiping it merely
+// means a pulse that would have been suppressed is delivered once — never a lost signal.
+
+const DEFAULT_LIFECYCLE_SIGNAL_TTL_MS = 60_000;
+
+interface SignalEntry {
+  at: number;
+}
+
+const signals = new Map<string, SignalEntry>();
+
+// Delimiter between recipient and subject key. A pipe can't occur in an agent id or a subject key
+// (subject keys are `task:<n>` / `child:<id>` and ids are dot/dash/colon-only), so the composite is
+// unambiguous. Kept a plain visible character so the source stays grep-friendly.
+const KEY_DELIMITER = " || ";
+
+function compositeKey(recipient: string, subjectKey: string): string {
+  return `${recipient}${KEY_DELIMITER}${subjectKey}`;
+}
+
+// #1038 — the semantic state a child-progress lifecycle signal (a report-up / agent.ready) conveys:
+// "the child is actively working this task". Suppression is state-keyed on this, so a progress
+// signal supersedes only a redundant `working` pulse — a later DISTINCT milestone pulse (committed /
+// landed / done) for the same task still reaches the spawner within the TTL instead of being dropped.
+export const LIFECYCLE_STATE_WORKING = "working";
+
+/** Subject key for a task-scoped lifecycle signal, keyed by semantic state so a signal about one
+ * state cannot suppress a pulse for a distinct state (#1038). The stamp and the check MUST pass the
+ * same `state` (the pulse's transition) to line up; omitting it keeps the legacy subject-only key. */
+export function taskSignalKey(taskId: number | string, state?: string): string {
+  return state ? `task:${taskId}::${state}` : `task:${taskId}`;
+}
+
+/** Subject key for a child-agent-scoped lifecycle signal (report-up / ready / exit about a child). */
+export function childSignalKey(childId: string): string {
+  return `child:${childId}`;
+}
+
+/** Record that a first-class lifecycle event just conveyed `subjectKey`'s state to `recipient`. */
+export function stampLifecycleSignal(recipient: string, subjectKey: string, now: number = Date.now()): void {
+  const rec = recipient.trim();
+  if (!rec || !subjectKey) return;
+  signals.set(compositeKey(rec, subjectKey), { at: now });
+  pruneExpired(now);
+}
+
+/** True when a lifecycle event stamped `subjectKey` for `recipient` within the TTL window. */
+export function hasRecentLifecycleSignal(
+  recipient: string,
+  subjectKey: string,
+  now: number = Date.now(),
+  ttlMs: number = DEFAULT_LIFECYCLE_SIGNAL_TTL_MS,
+): boolean {
+  const rec = recipient.trim();
+  if (!rec || !subjectKey) return false;
+  const key = compositeKey(rec, subjectKey);
+  const entry = signals.get(key);
+  if (!entry) return false;
+  if (now - entry.at > ttlMs) {
+    signals.delete(key);
+    return false;
+  }
+  return true;
+}
+
+function pruneExpired(now: number, ttlMs: number = DEFAULT_LIFECYCLE_SIGNAL_TTL_MS): void {
+  if (signals.size < 512) return; // amortized cleanup only when the map grows
+  for (const [key, entry] of signals) {
+    if (now - entry.at > ttlMs) signals.delete(key);
+  }
+}
+
+/** Reset seam: clear all recorded lifecycle signals (per-test / on a fresh relay DB). */
+export function __resetLifecycleSignals(): void {
+  signals.clear();
+}

package/src/maintenance/constants.ts

@@ -30,7 +30,11 @@ export { DAY_MS, REAP_INTERVAL_MS, TERMINAL_WORKSPACE_STATUSES };
 
 export const DEFAULT_TIMEOUT_MS = 30_000;
 export const SCHEDULER_TICK_MS = 10_000;
-export const STRANDABLE_STATUSES = new Set<WorkspaceStatus>([...READY_TO_LAND_STATUSES, "conflict"]);
+// #1025 A6 — `merge_planned` is included so a merge whose command/result was lost (target
+// host gone, POST dropped) can't wedge forever off every strand path: the in-flight
+// watchdog + pending-command expiry are the fast recovery, and workspace-gc escalation is
+// the last-line backstop. Without it a stuck `merge_planned` was escalation-blind.
+export const STRANDABLE_STATUSES = new Set<WorkspaceStatus>([...READY_TO_LAND_STATUSES, "conflict", "merge_planned"]);
 export const CONFLICT_SCAN_STATUSES = new Set<WorkspaceStatus>(["active", "ready", "review_requested", "merge_planned", "conflict"]);
 export const LANDED_RECONCILE_STATUSES = new Set<WorkspaceStatus>(["merge_planned", "review_requested", "conflict"]);