@desplega.ai/agent-swarm 1.90.0 → 1.91.0

package/src/be/seed-scripts/catalog/tool-usage.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+
+export const argsSchema = z.object({
+  days: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("Look back this many days (default 7)"),
+  agentId: z.string().optional().describe("Filter by agent ID (default: all agents)"),
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("Top N tools to return (default 20)"),
+});
+
+/** Tool usage histogram from session_logs — top tools by call count. */
+export default async function toolUsage(args: any, ctx: any) {
+  const parsed = argsSchema.safeParse(args);
+  if (!parsed.success) return { error: "invalid args: " + parsed.error.message };
+  const days = parsed.data.days || 7;
+  const limit = parsed.data.limit || 20;
+  const agentId = parsed.data.agentId;
+
+  const agentFilter = agentId ? `AND agent_id = '${agentId}'` : "";
+  const query = `
+    SELECT tool_name, count(*) as calls
+    FROM session_logs
+    WHERE tool_name IS NOT NULL
+      AND created_at > datetime('now', '-${days} days')
+      ${agentFilter}
+    GROUP BY tool_name
+    ORDER BY calls DESC
+    LIMIT ${limit}
+  `;
+
+  const res: any = await ctx.swarm.db_query({ query });
+  const payload = res?.data ?? res;
+  const rows: any[] = payload?.rows ?? [];
+
+  const totalCalls = rows.reduce((sum: number, r: any) => sum + (r.calls ?? 0), 0);
+
+  return {
+    days,
+    agentId: agentId ?? "all",
+    totalDistinctTools: rows.length,
+    totalCalls,
+    tools: rows.map((r: any) => ({
+      tool: r.tool_name,
+      calls: r.calls,
+      pct: totalCalls > 0 ? Math.round((r.calls / totalCalls) * 1000) / 10 : 0,
+    })),
+  };
+}

package/src/be/seed-scripts/index.ts

@@ -22,6 +22,7 @@ import { getScript, upsertScriptByName } from "../scripts/db";
 import { extractArgsJsonSchema } from "../scripts/extract-schema";
 import { typecheckScript } from "../scripts/typecheck";
 import type { Seeder, SeedItem } from "../seed/types";
+import compoundInsightsSrc from "./catalog/compound-insights.ts" with { type: "text" };
 import dateResolveSrc from "./catalog/date-resolve.ts" with { type: "text" };
 import fetchReadableSrc from "./catalog/fetch-readable.ts" with { type: "text" };
 import ghPrSnapshotSrc from "./catalog/gh-pr-snapshot.ts" with { type: "text" };
@@ -29,9 +30,12 @@ import groupCountSrc from "./catalog/group-count.ts" with { type: "text" };
 import jsonQuerySrc from "./catalog/json-query.ts" with { type: "text" };
 import linearIssueSrc from "./catalog/linear-issue.ts" with { type: "text" };
 import memoryDedupCheckSrc from "./catalog/memory-dedup-check.ts" with { type: "text" };
+import scheduleHealthSrc from "./catalog/schedule-health.ts" with { type: "text" };
 import slackThreadFlattenSrc from "./catalog/slack-thread-flatten.ts" with { type: "text" };
+import smartRecallSrc from "./catalog/smart-recall.ts" with { type: "text" };
 import taskFailureAuditSrc from "./catalog/task-failure-audit.ts" with { type: "text" };
 import textDiffSrc from "./catalog/text-diff.ts" with { type: "text" };
+import toolUsageSrc from "./catalog/tool-usage.ts" with { type: "text" };
 
 export type SeedScript = {
   name: string;
@@ -122,6 +126,38 @@ export const SEED_SCRIPTS: SeedScript[] = [
     intent: "Turn a Slack thread into plain text for summarizing or as task context.",
     source: asText(slackThreadFlattenSrc),
   },
+  {
+    name: "smart-recall",
+    description:
+      "Multi-query fan-out memory search with dedup and composite reranking (bestSimilarity + 0.05 * hitCount). Returns unique memories across all queries.",
+    intent:
+      "Recall relevant memories using multiple search angles — better coverage than a single query. Use for task onboarding, context gathering, or before writing new memories.",
+    source: asText(smartRecallSrc),
+  },
+  {
+    name: "schedule-health",
+    description:
+      "Per-schedule failure rate check over recent tasks — flags schedules with failure rates above a configurable threshold.",
+    intent:
+      "Find unhealthy schedules that keep failing — for daily compounding, reliability reviews, or ops triage.",
+    source: asText(scheduleHealthSrc),
+  },
+  {
+    name: "tool-usage",
+    description:
+      "Tool usage histogram from session_logs — top tools by call count over a time window, optionally filtered by agent.",
+    intent:
+      "See which MCP tools agents use most — for SDK gap analysis, optimization, or daily ops snapshots.",
+    source: asText(toolUsageSrc),
+  },
+  {
+    name: "compound-insights",
+    description:
+      "All-in-one swarm-wide daily ops snapshot: task completion/failure summary, real failure clusters (excludes superseded/cancelled bookkeeping), schedule health flags, tool usage top-25, memory health stats, and a per-agent breakdown. Aggregates across ALL agents via direct read-only SQL.",
+    intent:
+      "Single-call daily compounding Phase 0 helper — replaces ~25 raw tool roundtrips with one compressed JSON result covering every agent. For daily evolution, ops reviews, or heartbeat context.",
+    source: asText(compoundInsightsSrc),
+  },
 ];
 
 /** A catalog entry resolved into a generic {@link SeedItem}. */

package/src/commands/artifact.ts

@@ -1,6 +1,7 @@
 import { Hono } from "hono";
 import { createArtifactServer } from "../artifact-sdk";
 import { getApiKey } from "../utils/api-key";
+import { getMcpBaseUrl } from "../utils/constants";
 
 interface ArtifactArgs {
   additionalArgs: string[];
@@ -139,7 +140,7 @@ async function artifactServe(args: ArtifactArgs) {
 
 async function artifactList() {
   const apiKey = getApiKey();
-  const mcpBaseUrl = process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
+  const mcpBaseUrl = getMcpBaseUrl();
   const agentId = process.env.AGENT_ID || "";
 
   try {
@@ -197,7 +198,7 @@ async function artifactStop(args: ArtifactArgs) {
   }
 
   const apiKey = getApiKey();
-  const mcpBaseUrl = process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
+  const mcpBaseUrl = getMcpBaseUrl();
   const agentId = process.env.AGENT_ID || "";
 
   // 1. Try to stop PM2 process

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();