@desplega.ai/agent-swarm 1.89.0 → 1.91.0

package/src/commands/profile-sync.ts

@@ -0,0 +1,310 @@
+/**
+ * Harness-agnostic FS → DB profile sync (worker-side, HTTP-only).
+ *
+ * Persists an agent's self-editable identity / config files back to the API:
+ *   - SOUL.md / IDENTITY.md / TOOLS.md / HEARTBEAT.md  (bundled identity POST)
+ *   - ~/.claude/CLAUDE.md                              (claude POST)
+ *   - /workspace/start-up.sh (agent-managed section)   (setup POST)
+ *
+ * This mirrors the per-session sync that the Claude plugin hooks
+ * (`src/hooks/hook.ts`) and the pi extension (`src/providers/pi-mono-extension.ts`)
+ * already perform, but lifted into a single shared module the runner can call
+ * at session end for ANY `hasLocalEnvironment` harness (claude, pi, codex,
+ * opencode). Before this module, codex/opencode had no sync path at all and
+ * pi's path could silently not-fire (2026-06-01 regression).
+ *
+ * Boundary rules (enforced by CI):
+ *   - MUST NOT import `src/be/db` or `bun:sqlite` (worker/API DB boundary —
+ *     `scripts/check-db-boundary.sh`). This module is HTTP-only.
+ *   - MUST NOT read the API key from `process.env` directly
+ *     (`scripts/check-api-key-boundary.sh`). The caller passes the key
+ *     (resolved via `getApiKey()`) in `opts.apiKey`.
+ *
+ * Hardening vs. the original copies: every POST checks `resp.ok` and surfaces
+ * a scrubbed warning on a non-2xx response or thrown error instead of
+ * silently swallowing it (the swallow is exactly what hid the 2026-06-01 pi
+ * drop). The sync stays NON-FATAL — a failed sync must never fail the task —
+ * but it must be VISIBLE.
+ */
+
+import { scrubSecrets } from "../utils/secret-scrubber.ts";
+
+export const SOUL_MD_PATH = "/workspace/SOUL.md";
+export const IDENTITY_MD_PATH = "/workspace/IDENTITY.md";
+export const TOOLS_MD_PATH = "/workspace/TOOLS.md";
+export const HEARTBEAT_MD_PATH = "/workspace/HEARTBEAT.md";
+export const SETUP_SCRIPT_PATH = "/workspace/start-up.sh";
+/**
+ * Claude Code's personal-file CLAUDE.md path. This is what the Claude plugin
+ * Stop hook reads and owns — the runner only uses it as a backstop for an
+ * all-Claude batch (never overwriting it with the workspace materialization).
+ */
+export const CLAUDE_MD_PATH = `${process.env.HOME}/.claude/CLAUDE.md`;
+/**
+ * Workspace CLAUDE.md — the agent-level instructions file the runner
+ * materializes from the `claudeMd` DB field at boot (`runner.ts`) and that the
+ * base-prompt truncation notice tells NON-Claude harnesses (codex/pi/opencode)
+ * to edit. Distinct from CLAUDE_MD_PATH; this is the FS→DB source for the
+ * non-Claude providers that previously had no sync path at all.
+ */
+export const WORKSPACE_CLAUDE_MD_PATH = "/workspace/CLAUDE.md";
+
+// Minimum length for SOUL.md and IDENTITY.md to prevent accidental corruption.
+// Mirrors `hook.ts` (raised from 100 to 500 after profile-corruption recurrences
+// where a short test sentinel synced into the real agent's DB row).
+const IDENTITY_FILE_MIN_LENGTH = 500;
+// Maximum file size we are willing to sync (>64KB is almost certainly not a
+// hand-edited identity/config file).
+const MAX_FILE_LENGTH = 65536;
+
+const SETUP_MARKER_START = "# === Agent-managed setup (from DB) ===";
+const SETUP_MARKER_END = "# === End agent-managed setup ===";
+
+export type ProfileSyncField = "identity" | "claude" | "setup";
+export type ProfileChangeSource = "self_edit" | "session_sync";
+
+export interface ProfileSyncOptions {
+  agentId: string;
+  apiUrl: string;
+  apiKey: string;
+  /** Session-end sync uses "session_sync"; on-edit hooks use "self_edit". */
+  changeSource?: ProfileChangeSource;
+  /** Subset of field groups to sync. Defaults to all three. */
+  fields?: ProfileSyncField[];
+  /**
+   * Path to read the CLAUDE.md source from. Defaults to CLAUDE_MD_PATH (Claude
+   * Code's personal-file path). Non-Claude local harnesses must pass
+   * WORKSPACE_CLAUDE_MD_PATH so their `/workspace/CLAUDE.md` edits sync. See
+   * `resolveClaudeMdPath`.
+   */
+  claudeMdPath?: string;
+  /** Injectable fetch for tests. Defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * Choose which CLAUDE.md source the runner should sync, given the harness
+ * providers of the completed local sessions in a batch. Claude Code's personal
+ * file lives at `~/.claude/CLAUDE.md` (CLAUDE_MD_PATH — the Stop hook's path);
+ * every other local harness edits `/workspace/CLAUDE.md` (the file the runner
+ * materializes and the base prompt points them to). When a batch mixes
+ * providers, the presence of any non-Claude session means the workspace file is
+ * the edited source of truth; an all-Claude batch uses the personal-file path,
+ * where the runner only acts as a backstop for a Stop hook that didn't fire and
+ * never clobbers a real personal-file edit with the stale workspace copy.
+ */
+export function resolveClaudeMdPath(completedProviders: readonly string[]): string {
+  const anyNonClaude = completedProviders.some((p) => p !== "claude");
+  return anyNonClaude ? WORKSPACE_CLAUDE_MD_PATH : CLAUDE_MD_PATH;
+}
+
+/** A single profile-update POST body, tagged with a label for logging. */
+interface ProfilePayload {
+  label: string;
+  body: Record<string, unknown>;
+}
+
+/**
+ * Pure: given the raw `start-up.sh` contents, return the agent-managed content
+ * to sync, or `null` if there is nothing syncable. Extracts ONLY the content
+ * between the agent-managed markers when present (so operator content isn't
+ * duplicated); otherwise treats the whole file (minus a leading shebang) as
+ * agent-managed.
+ */
+export function extractSetupScriptContent(raw: string): string | null {
+  if (!raw.trim()) return null;
+
+  const startIdx = raw.indexOf(SETUP_MARKER_START);
+  const endIdx = raw.indexOf(SETUP_MARKER_END);
+
+  let content: string;
+  if (startIdx !== -1 && endIdx !== -1) {
+    // Markers present — extract ONLY the content between them.
+    content = raw.substring(startIdx + SETUP_MARKER_START.length, endIdx).trim();
+  } else {
+    // No markers — agent created/replaced the entire file. Store as-is minus shebang.
+    content = raw.replace(/^#!\/bin\/bash\n/, "").trim();
+  }
+
+  if (!content || content.length > MAX_FILE_LENGTH) return null;
+  return content;
+}
+
+/**
+ * Pure: build the bundled identity-update body from raw file contents. Applies
+ * the trim / max-length guards and the SOUL/IDENTITY min-length guard. Returns
+ * an empty object when nothing is syncable (callers should skip the POST).
+ * `undefined` inputs mean the file was absent.
+ */
+export function buildIdentityPayload(files: {
+  soulMd?: string;
+  identityMd?: string;
+  toolsMd?: string;
+  heartbeatMd?: string;
+}): Record<string, string> {
+  const updates: Record<string, string> = {};
+
+  if (files.soulMd !== undefined) {
+    const content = files.soulMd;
+    if (content.trim() && content.length <= MAX_FILE_LENGTH) {
+      if (content.length < IDENTITY_FILE_MIN_LENGTH) {
+        console.error(
+          `[profile-sync] Skipping SOUL.md sync: content too short (${content.length} chars, minimum ${IDENTITY_FILE_MIN_LENGTH}). This prevents accidental profile corruption.`,
+        );
+      } else {
+        updates.soulMd = content;
+      }
+    }
+  }
+
+  if (files.identityMd !== undefined) {
+    const content = files.identityMd;
+    if (content.trim() && content.length <= MAX_FILE_LENGTH) {
+      if (content.length < IDENTITY_FILE_MIN_LENGTH) {
+        console.error(
+          `[profile-sync] Skipping IDENTITY.md sync: content too short (${content.length} chars, minimum ${IDENTITY_FILE_MIN_LENGTH}). This prevents accidental profile corruption.`,
+        );
+      } else {
+        updates.identityMd = content;
+      }
+    }
+  }
+
+  if (files.toolsMd !== undefined) {
+    const content = files.toolsMd;
+    if (content.trim() && content.length <= MAX_FILE_LENGTH) {
+      updates.toolsMd = content;
+    }
+  }
+
+  if (files.heartbeatMd !== undefined) {
+    const content = files.heartbeatMd;
+    if (content.length <= MAX_FILE_LENGTH) {
+      updates.heartbeatMd = content;
+    }
+  }
+
+  return updates;
+}
+
+/** Reads a file's text, returning `undefined` when it does not exist. */
+export type FileReader = (path: string) => Promise<string | undefined>;
+
+/** Default file reader — reads from the worker's local FS via Bun. */
+async function readFileIfExists(path: string): Promise<string | undefined> {
+  try {
+    const file = Bun.file(path);
+    if (!(await file.exists())) return undefined;
+    return await file.text();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Collect the profile-update POST bodies to send. Each entry is one POST.
+ * `fields` selects which groups to include. The file reader is injectable so
+ * the field-selection / guard logic can be unit-tested without touching the FS.
+ */
+export async function collectProfilePayloads(
+  fields: ProfileSyncField[],
+  changeSource: ProfileChangeSource,
+  readFile: FileReader = readFileIfExists,
+  claudeMdPath: string = CLAUDE_MD_PATH,
+): Promise<ProfilePayload[]> {
+  const payloads: ProfilePayload[] = [];
+
+  if (fields.includes("identity")) {
+    const updates = buildIdentityPayload({
+      soulMd: await readFile(SOUL_MD_PATH),
+      identityMd: await readFile(IDENTITY_MD_PATH),
+      toolsMd: await readFile(TOOLS_MD_PATH),
+      heartbeatMd: await readFile(HEARTBEAT_MD_PATH),
+    });
+    if (Object.keys(updates).length > 0) {
+      payloads.push({ label: "identity", body: { ...updates, changeSource } });
+    }
+  }
+
+  if (fields.includes("claude")) {
+    const raw = await readFile(claudeMdPath);
+    if (raw?.trim() && raw.length <= MAX_FILE_LENGTH) {
+      payloads.push({ label: "claude", body: { claudeMd: raw, changeSource } });
+    }
+  }
+
+  if (fields.includes("setup")) {
+    const raw = await readFile(SETUP_SCRIPT_PATH);
+    if (raw !== undefined) {
+      const content = extractSetupScriptContent(raw);
+      if (content !== null) {
+        payloads.push({ label: "setup", body: { setupScript: content, changeSource } });
+      }
+    }
+  }
+
+  return payloads;
+}
+
+/**
+ * POST a single profile update. NON-FATAL but VISIBLE: a non-2xx response or a
+ * thrown error is logged (scrubbed) and swallowed so it never fails the task,
+ * but — unlike the original copies — it is never silently ignored.
+ */
+export async function postProfileUpdate(
+  opts: Pick<ProfileSyncOptions, "agentId" | "apiUrl" | "apiKey" | "fetchImpl">,
+  payload: ProfilePayload,
+): Promise<void> {
+  const doFetch = opts.fetchImpl ?? fetch;
+  try {
+    const resp = await doFetch(`${opts.apiUrl}/api/agents/${opts.agentId}/profile`, {
+      method: "PUT",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${opts.apiKey}`,
+        "X-Agent-ID": opts.agentId,
+      },
+      body: JSON.stringify(payload.body),
+    });
+    if (!resp.ok) {
+      let detail = "";
+      try {
+        detail = (await resp.text()).slice(0, 500);
+      } catch {
+        /* ignore body read failure */
+      }
+      console.warn(
+        scrubSecrets(
+          `[profile-sync] ${payload.label} sync failed: HTTP ${resp.status}${detail ? ` — ${detail}` : ""}`,
+        ),
+      );
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(scrubSecrets(`[profile-sync] ${payload.label} sync errored: ${msg}`));
+  }
+}
+
+/**
+ * Sync the agent's local profile files back to the API. Reads SOUL/IDENTITY/
+ * TOOLS/HEARTBEAT/CLAUDE.md + the agent-managed section of start-up.sh and
+ * POSTs each changed group. Idempotent server-side: the profile route only
+ * writes a new `context_versions` row when the content hash changes, so a
+ * redundant sync (pi extension + runner, or an unchanged file) is a no-op.
+ *
+ * Always resolves (never throws) — failures are logged, not propagated.
+ */
+export async function syncProfileFilesToServer(opts: ProfileSyncOptions): Promise<void> {
+  const changeSource = opts.changeSource ?? "session_sync";
+  const fields = opts.fields ?? ["identity", "claude", "setup"];
+
+  const payloads = await collectProfilePayloads(
+    fields,
+    changeSource,
+    readFileIfExists,
+    opts.claudeMdPath ?? CLAUDE_MD_PATH,
+  );
+  for (const payload of payloads) {
+    await postProfileUpdate(opts, payload);
+  }
+}

package/src/commands/runner.ts

@@ -36,6 +36,7 @@ import { initTelemetry, telemetry } from "../telemetry.ts";
 import type { ProviderName, RepoGuidelines } from "../types.ts";
 import { getApiKey } from "../utils/api-key.ts";
 import { computeBudgetBackoffMs } from "../utils/budget-backoff.ts";
+import { getMcpBaseUrl } from "../utils/constants.ts";
 import { getContextWindowSize } from "../utils/context-window.ts";
 import { type CredentialSelection, resolveCredentialPools } from "../utils/credentials.ts";
 import {
@@ -52,6 +53,7 @@ import { validateJsonSchema } from "../workflows/json-schema-validator.ts";
 import { interpolate } from "../workflows/template.ts";
 import { buildContextPreamble, buildResumeContextPreamble } from "./context-preamble.ts";
 import { awaitCredentials, BootMaxWaitExceededError, EX_CONFIG } from "./credential-wait.ts";
+import { resolveClaudeMdPath, syncProfileFilesToServer } from "./profile-sync.ts";
 import {
   buildCredStatusReport,
   buildLatestModelReport,
@@ -70,6 +72,34 @@ import "./templates.ts";
 /** Throttle interval for progress updates (3 seconds). */
 const PROGRESS_THROTTLE_MS = 3000;
 
+/** Minimum spacing for explicit runner GC sweeps. */
+const RUNNER_GC_MIN_INTERVAL_MS = 5 * 60 * 1000;
+
+let lastRunnerGcAt = 0;
+
+type GcCapableGlobal = typeof globalThis & { gc?: () => void };
+
+function scheduleRunnerGc(reason: string): boolean {
+  const gc = (globalThis as GcCapableGlobal).gc;
+  if (typeof gc !== "function") return false;
+
+  const now = Date.now();
+  if (now - lastRunnerGcAt < RUNNER_GC_MIN_INTERVAL_MS) return false;
+  lastRunnerGcAt = now;
+
+  const timer = setTimeout(() => {
+    const startedAt = Date.now();
+    try {
+      gc();
+      console.log(`[runner] Explicit GC completed after ${reason} in ${Date.now() - startedAt}ms`);
+    } catch (err) {
+      console.warn(`[runner] Explicit GC failed after ${reason}: ${err}`);
+    }
+  }, 0);
+  timer.unref?.();
+  return true;
+}
+
 /** Save PM2 process list for persistence across container restarts */
 async function savePm2State(role: string): Promise<void> {
   try {
@@ -1424,6 +1454,21 @@ interface RunningTask {
     keySuffix: string;
     keyIndex: number;
   };
+  /**
+   * Harness provider this session was actually spawned/resumed on, snapshotted
+   * at spawn time. The runner lets in-flight sessions finish on their original
+   * adapter after a live provider swap, so the session-end profile sync must
+   * decide based on THIS value — not the mutable global `state.harnessProvider`.
+   */
+  harnessProvider: ProviderName;
+  /**
+   * Whether this session ran in a local `/workspace` environment, snapshotted
+   * from `adapter.traits.hasLocalEnvironment` at spawn time. Gates the
+   * session-end FS → DB profile sync per finished session (a session that
+   * started local must still sync even if the worker was swapped to a remote
+   * provider before it completed, and vice versa).
+   */
+  hasLocalEnvironment: boolean;
 }
 
 /** Runner state for tracking concurrent tasks */
@@ -3010,6 +3055,7 @@ async function spawnProviderProcess(
         }
         closeActiveToolSpans(result.exitCode === 0 ? "ok" : "error", result.failureReason);
         sessionSpan.end();
+        scheduleRunnerGc("session completion");
 
         return result;
       }),
@@ -3024,6 +3070,7 @@ async function spawnProviderProcess(
         });
         closeActiveToolSpans("error", error instanceof Error ? error.message : String(error));
         sessionSpan.end();
+        scheduleRunnerGc("session error");
         throw error;
       }),
     );
@@ -3046,6 +3093,11 @@ async function spawnProviderProcess(
     promise,
     result: null,
     credentialInfo,
+    // Snapshot the provider + local-env trait of the adapter this session is
+    // spawned on, so the session-end sync decision survives a live provider
+    // swap that mutates the global RunnerState (review finding 2).
+    harnessProvider: opts.harnessProvider,
+    hasLocalEnvironment: adapter.traits.hasLocalEnvironment,
   };
 
   // Non-blocking completion tracking
@@ -3073,6 +3125,8 @@ async function checkCompletedProcesses(
     cursorUpdates?: Array<{ channelId: string; ts: string }>;
     workingDir?: string;
     credentialInfo?: RunningTask["credentialInfo"];
+    harnessProvider: ProviderName;
+    hasLocalEnvironment: boolean;
   }> = [];
 
   for (const [taskId, task] of state.activeTasks) {
@@ -3088,6 +3142,8 @@ async function checkCompletedProcesses(
         cursorUpdates: task.cursorUpdates,
         workingDir: task.workingDir,
         credentialInfo: task.credentialInfo,
+        harnessProvider: task.harnessProvider,
+        hasLocalEnvironment: task.hasLocalEnvironment,
       });
     }
   }
@@ -3217,6 +3273,40 @@ async function checkCompletedProcesses(
       }
     }
   }
+
+  // Harness-agnostic FS → DB profile sync at session end.
+  //
+  // The Claude plugin Stop hook and the pi extension sync SOUL/IDENTITY/TOOLS/
+  // CLAUDE.md + start-up.sh on their own, but codex/opencode have no such path
+  // and pi's can silently not-fire (2026-06-01 regression). Running the sync
+  // here — at the single point where every completed harness session converges
+  // (including crashes, since the process resolved with an exit code) — makes
+  // persistence reliable for ALL local-environment harnesses without
+  // per-adapter code. Idempotent: the profile route only writes a new context
+  // version when the content hash changes, so pi's double-sync and claude's
+  // redundant POST collapse to a no-op. NON-FATAL — never blocks completion;
+  // failures are logged (scrubbed) inside the helper.
+  //
+  // The local-env gate is per FINISHED session, snapshotted at spawn time —
+  // NOT the mutable global `state.hasLocalEnvironment`. The runner lets
+  // in-flight sessions finish on their original adapter after a live provider
+  // swap, so reading the global would (a) skip a session that started local
+  // when the worker has since flipped to a remote provider, and (b) sync stale
+  // local files after a remote session finishes once the worker flipped local.
+  // We sync when ANY finished session in this batch ran locally, and pick the
+  // CLAUDE.md source from those sessions' providers (review finding 2 + 1).
+  const localCompleted = completedTasks.filter((t) => t.hasLocalEnvironment);
+  if (apiConfig && localCompleted.length > 0) {
+    await syncProfileFilesToServer({
+      agentId: apiConfig.agentId,
+      apiUrl: apiConfig.apiUrl,
+      apiKey: apiConfig.apiKey,
+      changeSource: "session_sync",
+      claudeMdPath: resolveClaudeMdPath(localCompleted.map((t) => t.harnessProvider)),
+    }).catch((err) => {
+      console.warn(`[${role}] ${scrubSecrets(`Profile sync failed: ${err}`)}`);
+    });
+  }
 }
 
 const TEMPLATE_CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
@@ -3299,7 +3389,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
   // Get agent identity and swarm URL for base prompt
   const agentId = process.env.AGENT_ID || "unknown";
 
-  const apiUrl = process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
+  const apiUrl = getMcpBaseUrl();
   const swarmUrl = process.env.SWARM_URL || "localhost";
   const apiKey = getApiKey();
 

package/src/heartbeat/heartbeat.ts

@@ -1,5 +1,6 @@
 import {
   assignUnassignedTaskPending,
+  backfillSupersedeTaskResumeTaskId,
   cleanupStaleSessions,
   createTaskExtended,
   deleteActiveSession,
@@ -25,7 +26,7 @@ import {
   updateAgentStatus,
 } from "../be/db";
 import { resolveTemplate } from "../prompts/resolver";
-import { createResumeFollowUp } from "../tasks/worker-follow-up";
+import { createResumeFollowUp, getNextResumeGeneration } from "../tasks/worker-follow-up";
 import type { AgentTask } from "../types";
 import { getExecutorRegistry } from "../workflows";
 import { recoverIncompleteRuns } from "../workflows/recovery";
@@ -60,6 +61,11 @@ const STALE_CLEANUP_THRESHOLD_MINUTES = Number(process.env.HEARTBEAT_STALE_CLEAN
 /** Max pool tasks to auto-assign per sweep */
 const MAX_AUTO_ASSIGN_PER_SWEEP = Number(process.env.HEARTBEAT_MAX_AUTO_ASSIGN) || 5;
 
+/** Max crash-recovery resume generations before failing for lead triage */
+export const MAX_RESUME_GENERATIONS = Number(process.env.HEARTBEAT_MAX_RESUME_GENERATIONS) || 3;
+
+export const RESUME_BUDGET_EXHAUSTED_REASON = "resume_budget_exhausted";
+
 /** Heartbeat checklist interval: how often to check HEARTBEAT.md (default: 30 min) */
 const HEARTBEAT_CHECKLIST_INTERVAL_MS =
   Number(process.env.HEARTBEAT_CHECKLIST_INTERVAL_MS) || 30 * 60 * 1000;
@@ -98,10 +104,17 @@ export interface HeartbeatFindings {
 let heartbeatInterval: ReturnType<typeof setInterval> | null = null;
 let checklistInterval: ReturnType<typeof setInterval> | null = null;
 let isSweeping = false;
+let beforeHeartbeatSupersedeForTests: ((task: AgentTask) => void) | null = null;
 
 /** Tasks auto-failed during the reboot sweep, consumed by boot triage */
 let rebootAffectedTasks: Array<{ original: AgentTask; retryTaskId: string | null }> = [];
 
+export function setBeforeHeartbeatSupersedeForTests(
+  hook: ((task: AgentTask) => void) | null,
+): void {
+  beforeHeartbeatSupersedeForTests = hook;
+}
+
 // ============================================================================
 // Tier 1: Preflight Gate
 // ============================================================================
@@ -300,16 +313,40 @@ function remediateCrashedWorkerTask(
     return;
   }
 
-  // Supersede + resume path.
+  const nextResumeGeneration = getNextResumeGeneration(task);
+  if (nextResumeGeneration > MAX_RESUME_GENERATIONS) {
+    const failed = failTask(task.id, RESUME_BUDGET_EXHAUSTED_REASON);
+    if (failed) {
+      findings.autoFailedTasks.push({
+        taskId: task.id,
+        agentId: task.agentId,
+        reason: RESUME_BUDGET_EXHAUSTED_REASON,
+      });
+      if (opts.cleanupActiveSession) deleteActiveSession(task.id);
+      console.warn(
+        `[Heartbeat] Auto-failed task ${task.id.slice(0, 8)} — ${RESUME_BUDGET_EXHAUSTED_REASON} (${opts.shortLabel})`,
+      );
+      const remaining = getActiveTaskCount(task.agentId);
+      if (remaining === 0) updateAgentStatus(task.agentId, "idle");
+    }
+    return;
+  }
+
+  beforeHeartbeatSupersedeForTests?.(task);
+
   const superseded = supersedeTask(task.id, {
     reason: opts.supersedeReason,
     resumeTaskId: null,
   });
-  if (!superseded) return;
+  if (!superseded) {
+    return;
+  }
 
   const resume = createResumeFollowUp({ parentId: task.id, reason: "crash_recovery" });
 
   if (resume.kind === "created") {
+    backfillSupersedeTaskResumeTaskId(task.id, resume.task.id);
+
     findings.autoResumedTasks.push({
       taskId: task.id,
       resumeTaskId: resume.task.id,
@@ -320,10 +357,20 @@ function remediateCrashedWorkerTask(
       `[Heartbeat] Auto-superseded task ${task.id.slice(0, 8)} — created resume ${resume.task.id.slice(0, 8)} (${opts.shortLabel})`,
     );
   } else {
-    // `workflow-skip` is unreachable here (handled above). `skipped` covers
-    // parent-not-found / lead-not-found edge cases — just log for operators.
-    console.log(
-      `[Heartbeat] Task ${task.id.slice(0, 8)} superseded but no resume created (${
+    const reason =
+      resume.kind === "skipped"
+        ? `resume_creation_skipped_${resume.reason}`
+        : "resume_creation_skipped_workflow";
+    const failed = failTask(task.id, reason);
+    if (failed) {
+      findings.autoFailedTasks.push({
+        taskId: task.id,
+        agentId: task.agentId,
+        reason,
+      });
+    }
+    console.warn(
+      `[Heartbeat] Task ${task.id.slice(0, 8)} failed because no resume was created (${
         resume.kind === "skipped" ? resume.reason : "workflow-skip"
       })`,
     );

package/src/hooks/hook.ts

@@ -11,6 +11,7 @@ import {
 } from "../be/memory/raters/llm";
 import type { Agent } from "../types";
 import { getApiKey } from "../utils/api-key";
+import { getMcpBaseUrl } from "../utils/constants";
 import { summarizeSession as runSummarize } from "../utils/internal-ai";
 import { checkToolLoop, clearToolHistory } from "./tool-loop-detection";
 
@@ -82,6 +83,27 @@ interface CancelledTasksResponse {
   cancelled: CancelledTask[];
 }
 
+/**
+ * Decide whether to show the "not registered — use join-swarm" nudge.
+ *
+ * Rules:
+ *  1. Only nudge on SessionStart — other events should not prompt re-registration.
+ *  2. If X-Agent-ID header is present the agent is pre-assigned; a null lookup
+ *     is transient, not a real "unregistered" state → suppress the nudge.
+ *  3. Only genuinely-unregistered agents (no X-Agent-ID, null lookup, SessionStart)
+ *     see the nudge.
+ */
+export function shouldShowRegistrationNudge(opts: {
+  agentInfoPresent: boolean;
+  eventType: string;
+  hasAgentIdHeader: boolean;
+}): boolean {
+  if (opts.agentInfoPresent) return false;
+  if (opts.eventType !== "SessionStart") return false;
+  if (opts.hasAgentIdHeader) return false;
+  return true;
+}
+
 /**
  * Check if a path is under the agent's own subdirectory on the shared disk.
  * Shared disk categories: thoughts, memory, downloads, misc.
@@ -150,7 +172,7 @@ async function readTaskFile(): Promise<TaskFileData | null> {
 async function fetchTaskDetails(
   taskId: string,
 ): Promise<{ id: string; task: string; progress?: string } | null> {
-  const apiUrl = process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
+  const apiUrl = getMcpBaseUrl();
   const apiKey = getApiKey();
   const headers: Record<string, string> = {};
   if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
@@ -889,13 +911,15 @@ export async function handleHook(): Promise<void> {
         console.log(tray);
       }
     }
-  } else {
+  } else if (
+    shouldShowRegistrationNudge({
+      agentInfoPresent: false,
+      eventType: msg.hook_event_name,
+      hasAgentIdHeader: hasAgentIdHeader(),
+    })
+  ) {
     console.log(
-      `You are not registered in the agent swarm yet. Use the join-swarm tool to register yourself, then check your status with my-agent-info.
-
-If the ${SERVER_NAME} server is not running or disabled, disregard this message.
-
-${hasAgentIdHeader() ? `You have a pre-defined agent ID via header: ${mcpConfig?.headers["X-Agent-ID"]}, it will be used automatically on join-swarm.` : "You do not have a pre-defined agent ID, you will receive one when you join the swarm, or optionally you can request one when calling join-swarm."}`,
+      `You are not registered in the agent swarm yet. Use the join-swarm tool to register yourself, then check your status with my-agent-info.\n\nIf the ${SERVER_NAME} server is not running or disabled, disregard this message.\n\nYou do not have a pre-defined agent ID, you will receive one when you join the swarm, or optionally you can request one when calling join-swarm.`,
     );
   }
 
@@ -1151,8 +1175,7 @@ ${hasAgentIdHeader() ? `You have a pre-defined agent ID via header: ${mcpConfig?
             editedPath.startsWith("/workspace/shared/memory/"))
         ) {
           try {
-            const apiUrl =
-              process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
+            const apiUrl = getMcpBaseUrl();
             const apiKey = getApiKey();
             const fileContent = await Bun.file(editedPath).text();
             const isShared = editedPath.startsWith("/workspace/shared/");