agent-relay-server 0.120.6 → 0.121.1

package/src/db/retention.ts

@@ -0,0 +1,130 @@
+import { getDb, getDbPath, runDbMaintenanceWorker } from "./connection.ts";
+
+interface RetentionPruneInput {
+  messageCutoff: number;
+  activityCutoff: number;
+  activityMaxRows: number;
+  spawnCommandCutoff: number;
+  batchSize: number;
+}
+
+interface RetentionPruneResult {
+  prunedMessages: number;
+  prunedActivityEvents: number;
+  prunedSpawnCommands: number;
+  offThread: boolean;
+}
+
+function boundedBatchSize(batchSize: number): number {
+  return Math.min(Math.max(Math.trunc(batchSize), 1), 50_000);
+}
+
+function pruneMessagesBefore(cutoff: number, batchSize: number): number {
+  return getDb().transaction(() => {
+    getDb().query(`
+      UPDATE messages
+      SET reply_to = NULL
+      WHERE reply_to IN (
+        SELECT id FROM messages
+        WHERE created_at < ?
+        ORDER BY created_at ASC, id ASC
+        LIMIT ?
+      )
+    `).run(cutoff, batchSize);
+    return getDb().query(`
+      DELETE FROM messages
+      WHERE id IN (
+        SELECT id FROM messages
+        WHERE created_at < ?
+        ORDER BY created_at ASC, id ASC
+        LIMIT ?
+      )
+    `).run(cutoff, batchSize).changes;
+  })();
+}
+
+function pruneActivityEvents(input: RetentionPruneInput): number {
+  return getDb().query(`
+    DELETE FROM activity_events
+    WHERE id IN (
+      SELECT ae.id
+      FROM activity_events ae
+      WHERE (
+          ae.created_at < ?
+          OR ae.id NOT IN (
+            SELECT id
+            FROM activity_events
+            ORDER BY created_at DESC, id DESC
+            LIMIT ?
+          )
+        )
+        AND NOT (
+          ae.kind = 'state'
+          AND ae.title = 'Agent registered'
+          AND EXISTS (
+            SELECT 1
+            FROM commands c
+            WHERE c.type = 'agent.spawn'
+              AND c.status = 'succeeded'
+              AND coalesce(json_extract(c.params, '$.registrationConfirmed'), 0) != 1
+              AND (
+                c.correlation_id = json_extract(ae.metadata, '$.spawnRequestId')
+                OR json_extract(c.params, '$.spawnRequestId') = json_extract(ae.metadata, '$.spawnRequestId')
+              )
+          )
+        )
+      ORDER BY ae.created_at ASC, ae.id ASC
+      LIMIT ?
+    )
+  `).run(input.activityCutoff, input.activityMaxRows, input.batchSize).changes;
+}
+
+function pruneTerminalSpawnCommands(cutoff: number, batchSize: number): number {
+  return getDb().query(`
+    DELETE FROM commands
+    WHERE id IN (
+      SELECT c.id
+      FROM commands c
+      WHERE c.type = 'agent.spawn'
+        AND c.status IN ('succeeded', 'failed', 'canceled', 'timed_out')
+        AND c.updated_at < ?
+        AND NOT (
+          c.status = 'succeeded'
+          AND coalesce(json_extract(c.params, '$.registrationConfirmed'), 0) != 1
+        )
+        AND NOT EXISTS (
+          SELECT 1
+          FROM managed_agent_state mas
+          WHERE mas.spawn_request_id IS NOT NULL
+            AND (
+              mas.spawn_request_id = c.correlation_id
+              OR mas.spawn_request_id = json_extract(c.params, '$.spawnRequestId')
+            )
+        )
+      ORDER BY c.updated_at ASC, c.created_at ASC
+      LIMIT ?
+    )
+  `).run(cutoff, batchSize).changes;
+}
+
+export function pruneRetentionBatch(input: RetentionPruneInput): Omit<RetentionPruneResult, "offThread"> {
+  const batchSize = boundedBatchSize(input.batchSize);
+  return getDb().transaction(() => ({
+    prunedMessages: pruneMessagesBefore(input.messageCutoff, batchSize),
+    prunedActivityEvents: pruneActivityEvents({ ...input, batchSize }),
+    prunedSpawnCommands: pruneTerminalSpawnCommands(input.spawnCommandCutoff, batchSize),
+  }))();
+}
+
+export async function pruneRetentionBatchAsync(input: RetentionPruneInput, options: { signal?: AbortSignal } = {}): Promise<RetentionPruneResult> {
+  const normalized = { ...input, batchSize: boundedBatchSize(input.batchSize) };
+  if (!getDbPath() || getDbPath() === ":memory:") {
+    return { ...pruneRetentionBatch(normalized), offThread: false };
+  }
+  const result = await runDbMaintenanceWorker<Omit<RetentionPruneResult, "offThread">>(
+    "retention-prune",
+    [JSON.stringify(normalized)],
+    options.signal,
+  );
+  return { ...result, offThread: true };
+}

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 (
@@ -114,6 +120,7 @@ export function initDb(path: string = "agent-relay.db"): Database {
       last_seen INTEGER NOT NULL,
       created_at INTEGER NOT NULL
     );
+    CREATE INDEX IF NOT EXISTS idx_agents_spawn_request ON agents(json_extract(meta, '$.spawnRequestId'));
     CREATE TABLE IF NOT EXISTS notification_subscriptions (
       id TEXT PRIMARY KEY,
       agent_id TEXT NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
@@ -865,6 +872,9 @@ export function initDb(path: string = "agent-relay.db"): Database {
     CREATE INDEX IF NOT EXISTS idx_activity_operator ON activity_events(operator_id, created_at);
     CREATE INDEX IF NOT EXISTS idx_activity_created ON activity_events(created_at);
     CREATE INDEX IF NOT EXISTS idx_activity_agent ON activity_events(agent_id, created_at); CREATE INDEX IF NOT EXISTS idx_activity_policy_created ON activity_events(json_extract(metadata, '$.policyName'), created_at DESC, id DESC);
+    CREATE INDEX IF NOT EXISTS idx_activity_registered_spawn_request
+      ON activity_events(json_extract(metadata, '$.spawnRequestId'))
+      WHERE kind = 'state' AND title = 'Agent registered';
     -- issue_ref_id/issue_action indexes are created in applyMigrations() AFTER the ALTER — never inline here (#483: inline index over a not-yet-migrated column crashes initDb on existing DBs).
 
     CREATE TABLE IF NOT EXISTS channels (
@@ -942,6 +952,7 @@ export function initDb(path: string = "agent-relay.db"): Database {
     CREATE INDEX IF NOT EXISTS idx_commands_status ON commands(status);
     CREATE INDEX IF NOT EXISTS idx_commands_created ON commands(created_at);
     CREATE INDEX IF NOT EXISTS idx_commands_correlation ON commands(correlation_id);
+    CREATE INDEX IF NOT EXISTS idx_commands_spawn_watchdog ON commands(type, status, updated_at);
 
     CREATE TABLE IF NOT EXISTS recipe_instances (
       id TEXT PRIMARY KEY,

package/src/db/stats.ts

@@ -20,6 +20,7 @@ import { summarizeExpiredUndeliveredMessages } from "./delivery.ts";
 import { messageTaskClosed } from "./claim-sql.ts";
 import { claimTaskWhere } from "./task-core.ts";
 import { getDb } from "./connection.ts";
+import { getEventLoopLagSnapshot } from "../event-loop-lag";
 import type {
   AgentCard,
   ActivityEvent,
@@ -408,6 +409,27 @@ export function getHealth(now: number = Date.now()): HealthReport {
     checks.push({ name: "database", status: "error", detail: e instanceof Error ? e.message : "database check failed" });
   }
 
+  const eventLoopLag = getEventLoopLagSnapshot();
+  const eventLoopLagHealthMaxMs = Math.max(eventLoopLag.maxMs, eventLoopLag.maxSinceLastReadMs);
+  const eventLoopLagWarn = eventLoopLag.warnThresholdMs > 0 && eventLoopLag.sampleCount > 0 && eventLoopLagHealthMaxMs >= eventLoopLag.warnThresholdMs;
+  checks.push({
+    name: "event-loop-lag",
+    status: eventLoopLagWarn ? "warn" : "ok",
+    detail: eventLoopLagWarn
+      ? `event loop lag max ${Math.round(eventLoopLagHealthMaxMs)}ms over ${eventLoopLag.sampleCount}/${eventLoopLag.windowSamples} sample(s)`
+      : undefined,
+    metrics: {
+      currentMs: eventLoopLag.currentMs,
+      maxMs: eventLoopLag.maxMs,
+      maxSinceLastReadMs: eventLoopLag.maxSinceLastReadMs,
+      sampleCount: eventLoopLag.sampleCount,
+      windowSamples: eventLoopLag.windowSamples,
+      sampleIntervalMs: eventLoopLag.sampleIntervalMs,
+      warnThresholdMs: eventLoopLag.warnThresholdMs,
+      ...(eventLoopLag.lastSampleAt === undefined ? {} : { lastSampleAt: eventLoopLag.lastSampleAt }),
+    },
+  });
+
   const staleLiveAgents = (getDb()
     .query("SELECT COUNT(*) as c FROM agents WHERE status != 'offline' AND last_seen <= ? AND id NOT IN ('user', 'system')")
     .get(now - STALE_TTL_MS) as any).c as number;

package/src/event-loop-lag.ts

@@ -0,0 +1,90 @@
+import {
+  EVENT_LOOP_LAG_LOG_MS,
+  EVENT_LOOP_LAG_SAMPLE_MS,
+  EVENT_LOOP_LAG_WARN_MS,
+  EVENT_LOOP_LAG_WINDOW_SAMPLES,
+} from "./config";
+
+export interface EventLoopLagSnapshot {
+  currentMs: number;
+  maxMs: number;
+  maxSinceLastReadMs: number;
+  sampleCount: number;
+  windowSamples: number;
+  sampleIntervalMs: number;
+  warnThresholdMs: number;
+  lastSampleAt?: number;
+}
+
+const samples = new Array<number>(EVENT_LOOP_LAG_WINDOW_SAMPLES).fill(0);
+let sampleIndex = 0;
+let sampleCount = 0;
+let currentMs = 0;
+let maxSinceLastReadMs = 0;
+let lastSampleAt: number | undefined;
+let timer: ReturnType<typeof setInterval> | undefined;
+let lastTickAt = 0;
+
+export function computeEventLoopLagMs(elapsedMs: number, expectedMs: number): number {
+  if (!Number.isFinite(elapsedMs) || !Number.isFinite(expectedMs)) return 0;
+  return Math.max(0, elapsedMs - expectedMs);
+}
+
+export function recordEventLoopLagSample(lagMs: number, sampledAt: number = Date.now(), logSpike = false): void {
+  const normalized = Number.isFinite(lagMs) ? Math.max(0, lagMs) : 0;
+  currentMs = normalized;
+  maxSinceLastReadMs = Math.max(maxSinceLastReadMs, normalized);
+  lastSampleAt = sampledAt;
+  samples[sampleIndex] = normalized;
+  sampleIndex = (sampleIndex + 1) % samples.length;
+  sampleCount = Math.min(sampleCount + 1, samples.length);
+  if (logSpike && EVENT_LOOP_LAG_LOG_MS > 0 && normalized >= EVENT_LOOP_LAG_LOG_MS) {
+    console.warn(`[health] event-loop lag ${Math.round(normalized)}ms`);
+  }
+}
+
+export function getEventLoopLagSnapshot(): EventLoopLagSnapshot {
+  let maxMs = 0;
+  for (let i = 0; i < sampleCount; i += 1) maxMs = Math.max(maxMs, samples[i] ?? 0);
+  const maxSinceLastRead = maxSinceLastReadMs;
+  maxSinceLastReadMs = 0;
+  return {
+    currentMs,
+    maxMs,
+    maxSinceLastReadMs: maxSinceLastRead,
+    sampleCount,
+    windowSamples: EVENT_LOOP_LAG_WINDOW_SAMPLES,
+    sampleIntervalMs: EVENT_LOOP_LAG_SAMPLE_MS,
+    warnThresholdMs: EVENT_LOOP_LAG_WARN_MS,
+    lastSampleAt,
+  };
+}
+
+export function startEventLoopLagSampler(): void {
+  if (timer) return;
+  lastTickAt = performance.now();
+  timer = setInterval(() => {
+    const now = performance.now();
+    const lagMs = computeEventLoopLagMs(now - lastTickAt, EVENT_LOOP_LAG_SAMPLE_MS);
+    lastTickAt = now;
+    recordEventLoopLagSample(lagMs, Date.now(), true);
+  }, EVENT_LOOP_LAG_SAMPLE_MS);
+  timer.unref?.();
+}
+
+export function stopEventLoopLagSampler(): void {
+  if (!timer) return;
+  clearInterval(timer);
+  timer = undefined;
+}
+
+export function resetEventLoopLagForTests(): void {
+  stopEventLoopLagSampler();
+  samples.fill(0);
+  sampleIndex = 0;
+  sampleCount = 0;
+  currentMs = 0;
+  maxSinceLastReadMs = 0;
+  lastSampleAt = undefined;
+  lastTickAt = 0;
+}

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"]);