@desplega.ai/agent-swarm 1.123.0 → 1.124.0

package/src/slack/watcher.ts

@@ -301,6 +301,24 @@ export async function processTreeMessages(): Promise<void> {
     // Check if tree is fully terminal — do one final render then clean up
     const fullyTerminal = isTreeFullyTerminal(nodes);
 
+    // Deliver any output that the compact tree would truncate before the tree
+    // is finalized and removed from tracking. Previously cleanup marked these
+    // tasks notified first, so the completion loop below never posted them.
+    let outputDeliverySucceeded = true;
+    for (const node of nodes.flatMap((root) => [root, ...root.children])) {
+      const task = getTaskById(node.taskId);
+      if (!task || !shouldPostInlineCompletionOutput(task)) continue;
+
+      const sent = await sendInlineTaskOutput(task);
+      if (sent) {
+        node.slackReplySent = true;
+        notifiedCompletions.set(task.id, now);
+        console.log(`[Slack] Sent full output for tree-tracked completion ${task.id.slice(0, 8)}`);
+      } else {
+        outputDeliverySucceeded = false;
+      }
+    }
+
     // Build blocks
     let blocks: unknown[];
     try {
@@ -315,7 +333,7 @@ export async function processTreeMessages(): Promise<void> {
     const lastSerialized = lastRenderedTree.get(messageTs);
     if (serialized === lastSerialized) {
       // No changes — skip update
-      if (fullyTerminal) {
+      if (fullyTerminal && outputDeliverySucceeded) {
         // Even though nothing changed visually, clean up if terminal
         cleanupCompletedTree(messageTs, tree, nodes);
       }
@@ -380,7 +398,7 @@ export async function processTreeMessages(): Promise<void> {
     }
 
     // Clean up fully terminal trees after final render
-    if (fullyTerminal && success) {
+    if (fullyTerminal && success && outputDeliverySucceeded) {
       cleanupCompletedTree(messageTs, tree, nodes);
     }
   }
@@ -711,11 +729,10 @@ export function startTaskWatcher(intervalMs = 3000): void {
         if (lastSent && now - lastSent < MIN_SEND_INTERVAL) continue;
 
         // Tasks tracked in a tree are still rendered by processTreeMessages().
-        // For prose-only completions, add one inline output reply so the user
+        // For truncated completions, add one inline output reply so the user
         // sees the actual answer instead of only the compact tree preview.
         if (taskToTree.has(task.id)) {
-          const attachments = task.status === "completed" ? getTaskAttachments(task.id) : [];
-          if (!shouldPostInlineCompletionOutput(task, attachments)) {
+          if (!shouldPostInlineCompletionOutput(task)) {
             notifiedCompletions.set(task.id, now);
             continue;
           }

package/src/telemetry.ts

@@ -15,9 +15,15 @@ const PRODUCT = "agent-swarm";
 const TIMEOUT_MS = 5_000;
 
 let installationId: string | null = null;
+let installedAt: string | null = null;
 let source = "unknown";
 let cachedIsCloud = false;
 let cachedIsE2b = false;
+let cachedHasEmbedding = false;
+let cachedHasSlackChannel = false;
+let cachedHasEmailChannel = false;
+let cachedInstallMethod = "manual";
+let cachedInstallPreset: string | undefined;
 
 function isEnabled(): boolean {
   return isEnvFlagEnabled("ANONYMIZED_TELEMETRY", true);
@@ -80,6 +86,92 @@ export function _resolveCloudMode(mcpBaseUrl: string | undefined | null): {
   return { isCloud: isCloudHostname(hostname) };
 }
 
+const KNOWN_INSTALL_METHODS = new Set(["onboard_interactive", "onboard_noninteractive"]);
+
+/**
+ * Resolve the "which entry point produced this install" cohort.
+ *
+ * `raw` comes from `INSTALL_METHOD`, written into `.env` by the onboard
+ * wizard's `generateEnv()` (`onboard_interactive` / `onboard_noninteractive`
+ * per `--yes`/`-y`). Installs that never ran the wizard — hand-written
+ * docker-compose, a bare `bun run start:http` clone — never set this var, so
+ * an unrecognized/missing value falls back to `"e2b"` (detected independently
+ * via `E2B_SANDBOX_ID`, since the `e2b start-stack` CLI path doesn't go
+ * through `generateEnv()`) or `"manual"`.
+ *
+ * Exported for tests; not part of the public API.
+ */
+export function _resolveInstallMethod(raw: string | undefined | null, isE2b: boolean): string {
+  const normalized = raw?.trim();
+  if (normalized && KNOWN_INSTALL_METHODS.has(normalized)) return normalized;
+  if (isE2b) return "e2b";
+  return "manual";
+}
+
+/**
+ * Preset IDs defined in `src/commands/onboard/presets.ts` (`PRESETS`).
+ * Duplicated as a literal set here — rather than imported — to preserve this
+ * file's zero-dependency contract (see file header); bump this list in the
+ * same PR that adds/removes/renames a preset.
+ */
+const KNOWN_INSTALL_PRESETS = new Set(["dev", "content", "research", "solo", "custom"]);
+
+/**
+ * Validate `INSTALL_PRESET` against the wizard's known preset IDs.
+ *
+ * Unlike `_resolveInstallMethod`, an unrecognized value is omitted entirely
+ * rather than mapped to a fallback sentinel: `INSTALL_PRESET` is free-form
+ * operator-set environment text, so forwarding an unrecognized value (an
+ * email address, a customer name, anything placed in that env var by
+ * mistake) would violate telemetry's enum-only / no-PII contract. Returning
+ * `undefined` here means the `install_preset` metadata key is omitted from
+ * the event entirely (see the spread-guard in `track()`).
+ *
+ * Exported for tests; not part of the public API.
+ */
+export function _resolveInstallPreset(raw: string | undefined | null): string | undefined {
+  const normalized = raw?.trim();
+  return normalized && KNOWN_INSTALL_PRESETS.has(normalized) ? normalized : undefined;
+}
+
+/**
+ * Whether semantic memory is likely enabled — i.e. an embedding-capable key
+ * is present. The onboard wizard's `generateEnv()` currently only writes
+ * Anthropic credentials (`src/commands/onboard/env-generator.ts`), so this
+ * lets us measure how many installs are silently running with memory search
+ * degraded/off. Boolean only — never the key value.
+ *
+ * Exported for tests; not part of the public API.
+ */
+export function _hasEmbeddingKey(env: NodeJS.ProcessEnv = process.env): boolean {
+  return !!(env.EMBEDDING_API_KEY || env.OPENAI_API_KEY);
+}
+
+/**
+ * Mirrors `initSlackApp()`'s enablement check (`src/slack/app.ts`) without
+ * importing the Slack module — this file is intentionally dependency-free
+ * (see file header) so both the api-server and workers can import it cheaply.
+ * If Slack's disable/credential logic changes, update this in the same PR.
+ *
+ * Exported for tests; not part of the public API.
+ */
+export function _hasSlackChannel(env: NodeJS.ProcessEnv = process.env): boolean {
+  return (
+    !!(env.SLACK_BOT_TOKEN && env.SLACK_APP_TOKEN) && !isEnvFlagEnabled("SLACK_DISABLE", false, env)
+  );
+}
+
+/**
+ * Mirrors `isAgentMailEnabled()` (`src/agentmail/app.ts`) without importing
+ * the AgentMail module — see `_hasSlackChannel` for why. AgentMail is the
+ * swarm's only outbound email channel today.
+ *
+ * Exported for tests; not part of the public API.
+ */
+export function _hasEmailChannel(env: NodeJS.ProcessEnv = process.env): boolean {
+  return !!env.AGENTMAIL_WEBHOOK_SECRET && !isEnvFlagEnabled("AGENTMAIL_DISABLE", false, env);
+}
+
 interface InitTelemetryOptions {
   /**
    * Whether to mint and persist a new install ID when the config read returns
@@ -113,15 +205,38 @@ export async function initTelemetry(
   const resolved = _resolveCloudMode(process.env.MCP_BASE_URL);
   cachedIsCloud = resolved.isCloud;
   cachedIsE2b = _isE2bSandbox();
-  console.log(`telemetry: cloud=${cachedIsCloud} e2b=${cachedIsE2b}`);
+  cachedHasEmbedding = _hasEmbeddingKey();
+  cachedHasSlackChannel = _hasSlackChannel();
+  cachedHasEmailChannel = _hasEmailChannel();
+  cachedInstallMethod = _resolveInstallMethod(process.env.INSTALL_METHOD, cachedIsE2b);
+  cachedInstallPreset = _resolveInstallPreset(process.env.INSTALL_PRESET);
+  console.log(
+    `telemetry: cloud=${cachedIsCloud} e2b=${cachedIsE2b} install_method=${cachedInstallMethod}`,
+  );
 
   try {
     const existing = await getConfig("telemetry_installation_id");
     if (existing) {
       installationId = existing;
+      // A pre-existing installation ID with no stored anchor means this
+      // install predates `telemetry_installed_at` tracking. Do NOT mint
+      // now() as a stand-in "install date" here — that back-fills a date
+      // that's wrong by however long the install has actually existed
+      // (seen: 110 days on our own production install after a routine
+      // upgrade). Leave installedAt null so the field is omitted from the
+      // payload: absence unambiguously means "pre-existing install, anchor
+      // unknown", and consumers can fall back to min(occurred_at) per
+      // installation_id in ClickHouse for the real anchor. Only a
+      // genuinely new installationId (the branch below) mints one.
+      const existingInstalledAt = await getConfig("telemetry_installed_at");
+      if (existingInstalledAt) {
+        installedAt = existingInstalledAt;
+      }
     } else if (generateIfMissing) {
-      installationId = `install_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
-      await setConfig("telemetry_installation_id", installationId);
+      const candidateId = `install_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+      await setConfig("telemetry_installation_id", candidateId);
+      installationId = candidateId;
+      await tryPersistInstalledAt(setConfig);
     }
     // else: leave installationId = null; track() will no-op
   } catch {
@@ -129,11 +244,39 @@ export async function initTelemetry(
     if (generateIfMissing) {
       // Generate ephemeral ID so telemetry still works this session.
       installationId = `ephemeral_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+      // Not persisted — config access is failing, so there's nowhere durable
+      // to write it. Leave installedAt null rather than a fake fresh mint.
     }
     // else: leave installationId = null; track() will no-op
   }
 }
 
+/**
+ * Mint + persist the `telemetry_installed_at` anchor, but only commit it to
+ * module state (and therefore only emit it on this session's events) once
+ * the write actually lands.
+ *
+ * The anchor's entire value is being a stable, one-time identity for "when
+ * did this install first appear" — a failed write here must not fabricate
+ * that stability. If `setConfig` throws, this process emits no anchor at
+ * all (rather than an unpersisted one that the next boot won't see and will
+ * mint a *different* replacement for), and — critically — the failure is
+ * swallowed locally so it can't unwind into the caller's `catch`, which
+ * would otherwise discard an already-resolved `installationId` that has
+ * nothing to do with this write.
+ */
+async function tryPersistInstalledAt(
+  setConfig: (key: string, value: string) => Promise<void> | void,
+): Promise<void> {
+  const candidate = new Date().toISOString();
+  try {
+    await setConfig("telemetry_installed_at", candidate);
+    installedAt = candidate;
+  } catch {
+    // Leave installedAt null for this session.
+  }
+}
+
 interface TrackOptions {
   event: string;
   properties?: Record<string, unknown>;
@@ -208,6 +351,15 @@ export function track(options: TrackOptions): void {
         is_cloud: cachedIsCloud || isCloudDeployment(),
         is_e2b: cachedIsE2b,
         swarmVersion: pkg.version,
+        // Instrumentation-gap closure (2026-07-29): activation-funnel signals.
+        // All boolean/enum, resolved once at init from process.env — never a
+        // secret, URL, channel ID, address, or other identifier. Spread LAST
+        // (same rule as is_cloud/is_e2b above) so callers can't spoof them.
+        has_embedding_key: cachedHasEmbedding,
+        has_slack_channel: cachedHasSlackChannel,
+        has_email_channel: cachedHasEmailChannel,
+        has_notification_channel: cachedHasSlackChannel || cachedHasEmailChannel,
+        install_method: cachedInstallMethod,
       },
       metadata: {
         transport: "https",
@@ -215,6 +367,9 @@ export function track(options: TrackOptions): void {
         environment: getTelemetryEnvironment(),
         is_cloud: isCloudDeployment(),
         ...getOrgIdentity(),
+        // Optional — only present when known, same pattern as organization_*.
+        ...(cachedInstallPreset ? { install_preset: cachedInstallPreset } : {}),
+        ...(installedAt ? { install_created_at: installedAt } : {}),
         ...options.metadata,
       },
     };
@@ -235,9 +390,15 @@ export function track(options: TrackOptions): void {
  */
 export function _resetTelemetryStateForTests(): void {
   installationId = null;
+  installedAt = null;
   source = "unknown";
   cachedIsCloud = false;
   cachedIsE2b = false;
+  cachedHasEmbedding = false;
+  cachedHasSlackChannel = false;
+  cachedHasEmailChannel = false;
+  cachedInstallMethod = "manual";
+  cachedInstallPreset = undefined;
 }
 
 /** Test-only: read the resolved install ID. */
@@ -245,6 +406,11 @@ export function _getInstallationIdForTests(): string | null {
   return installationId;
 }
 
+/** Test-only: read the resolved install-created-at anchor. */
+export function _getInstalledAtForTests(): string | null {
+  return installedAt;
+}
+
 export const telemetry = {
   taskEvent(
     event: string,

package/src/tests/base-prompt.test.ts

@@ -42,6 +42,51 @@ function disableSlackPromptTools() {
   delete process.env.SLACK_APP_TOKEN;
 }
 
+/** Heading of `system.agent.script_authoring_contract` — used for dedupe checks */
+const AUTHORING_CONTRACT_MARKER = "### Script Authoring Contract";
+
+/** How many times the authoring contract appears in a rendered prompt */
+function countAuthoringContract(text: string): number {
+  return text.split(AUTHORING_CONTRACT_MARKER).length - 1;
+}
+
+// ---------------------------------------------------------------------------
+// Script authoring contract — must reach every script-carrying composite, and
+// must never be duplicated (scripts-only mode renders after a composite that
+// already carries the rubric).
+// ---------------------------------------------------------------------------
+describe("getBasePrompt — script authoring contract", () => {
+  const combos: { role: string; provider?: "claude" | "pi"; scriptsOnly?: boolean }[] = [
+    { role: "worker" },
+    { role: "lead" },
+    { role: "worker", provider: "pi" },
+    { role: "lead", provider: "pi" },
+    { role: "worker", scriptsOnly: true },
+    { role: "lead", scriptsOnly: true },
+    { role: "worker", provider: "pi", scriptsOnly: true },
+  ];
+
+  for (const combo of combos) {
+    const label = `${combo.role}/${combo.provider ?? "default"}${
+      combo.scriptsOnly ? "/scripts-only" : ""
+    }`;
+    test(`renders exactly once for ${label}`, async () => {
+      const result = await getBasePrompt({ ...minimalArgs, ...combo });
+      expect(countAuthoringContract(result)).toBe(1);
+      expect(result).toContain("`args` FIRST, `ctx` SECOND");
+      expect(result).toContain("[REDACTED:<CONFIG_KEY>]");
+    });
+  }
+
+  test("remote provider (no MCP) gets no script authoring contract", async () => {
+    const result = await getBasePrompt({
+      ...minimalArgs,
+      traits: { hasMcp: false, hasLocalEnvironment: false },
+    });
+    expect(countAuthoringContract(result)).toBe(0);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Basic fields
 // ---------------------------------------------------------------------------
@@ -663,6 +708,40 @@ describe("getBasePrompt — context-mode provider gating", () => {
     expect(result).not.toContain("batch_execute");
     expect(result).toContain("Agent Scripts");
     expect(result).toContain("Pre-built Seed Scripts");
+    // Scheduling rules live outside the ctx_* advertisement — pi keeps them.
+    expect(result).toContain("Scheduling — Pick the Right targetType");
+  });
+
+  test("pi LEAD also skips the context-mode block (lead.pi composite)", async () => {
+    const result = await getBasePrompt({
+      ...minimalArgs,
+      role: "lead",
+      traits: localTraits,
+      provider: "pi",
+    });
+    // Lead content is present
+    expect(result).toContain("CRITICAL: You are a coordinator");
+    // ...but no phantom ctx_* tooling
+    expect(result).not.toContain("Context Window Management");
+    expect(result).not.toContain("batch_execute");
+    expect(result).not.toContain("execute_file");
+    // Script guidance (incl. the authoring contract) survives
+    expect(result).toContain("Agent Scripts");
+    expect(result).toContain(AUTHORING_CONTRACT_MARKER);
+    expect(result).toContain("Pre-built Seed Scripts");
+    // Scheduling rules live outside the ctx_* advertisement — pi keeps them.
+    expect(result).toContain("Scheduling — Pick the Right targetType");
+  });
+
+  test("claude LEAD keeps the context-mode block", async () => {
+    const result = await getBasePrompt({
+      ...minimalArgs,
+      role: "lead",
+      traits: localTraits,
+      provider: "claude",
+    });
+    expect(result).toContain("Context Window Management");
+    expect(result).toContain("batch_execute");
   });
 
   for (const provider of ["claude", "codex", "opencode"] as const) {

package/src/tests/mcp-tools-user.test.ts

@@ -45,6 +45,18 @@ function textOf(result: CallToolResult): string {
   return "";
 }
 
+/**
+ * Structured payload the registrar composes: `{ ...data, success, message,
+ * details?, nudge? }` (see finalizeSwarmToolResult in src/tools/utils.ts).
+ * Tool-specific data keys (status/unknown/ambiguous/candidates/externalIds/id/...)
+ * are spread at the TOP LEVEL alongside the envelope keys — this is where the
+ * machine-readable payload now lives ("never prose" = never ONLY in the text
+ * channel; structuredContent is always populated).
+ */
+function structuredOf(result: CallToolResult): Record<string, unknown> {
+  return (result.structuredContent ?? {}) as Record<string, unknown>;
+}
+
 function eventsFor(userId: string): Array<{ eventType: string; afterJson: string | null }> {
   return getDb()
     .prepare<{ eventType: string; afterJson: string | null }, string>(
@@ -90,6 +102,12 @@ describe("resolve-user MCP tool (new {kind, externalId, email} shape)", () => {
     const text = textOf(result);
     expect(text).toContain(user.id);
     expect(text).toContain("Slack User One");
+    expect(result.isError).toBe(false);
+    expect(structuredOf(result)).toMatchObject({
+      success: true,
+      id: user.id,
+      name: "Slack User One",
+    });
   });
 
   test("matches by email → findUserByEmail hit (primary + alias)", async () => {
@@ -101,22 +119,34 @@ describe("resolve-user MCP tool (new {kind, externalId, email} shape)", () => {
 
     const byPrimary = await callTool(server, "resolve-user", { email: "primary@example.com" });
     expect(textOf(byPrimary)).toContain(user.id);
+    expect(byPrimary.isError).toBe(false);
+    expect(structuredOf(byPrimary)).toMatchObject({ success: true, id: user.id });
 
     const byAlias = await callTool(server, "resolve-user", { email: "alias@example.com" });
     expect(textOf(byAlias)).toContain(user.id);
+    expect(byAlias.isError).toBe(false);
+    expect(structuredOf(byAlias)).toMatchObject({ success: true, id: user.id });
   });
 
-  test("returns a structured {status: 'unknown', ...} payload when nothing matches — never prose", async () => {
+  test("returns a structured {status: 'unknown', ...} payload when nothing matches — machine-readable via structuredContent, not prose-only", async () => {
     const result = await callTool(server, "resolve-user", {
       kind: "slack",
       externalId: "U_DOES_NOT_EXIST",
     });
-    const parsed = JSON.parse(textOf(result));
-    expect(parsed).toEqual({
+    // A miss is a successful, honest lookup outcome — not a tool failure.
+    expect(result.isError).toBe(false);
+    // NEW CONTRACT (SwarmToolResult): the {status, kind, externalId} payload is
+    // spread at the top level of structuredContent alongside the envelope
+    // (success/message), not embedded as a JSON blob inside content[0].text.
+    expect(structuredOf(result)).toMatchObject({
+      success: true,
       status: "unknown",
       kind: "slack",
       externalId: "U_DOES_NOT_EXIST",
     });
+    // Prose summary still shows up in the text channel for harnesses that
+    // only read content.text.
+    expect(textOf(result)).toContain('No user found for slack="U_DOES_NOT_EXIST"');
   });
 
   // Schema-level validation tests. The MCP SDK runs Zod at the transport
@@ -183,18 +213,21 @@ describe("resolve-user MCP tool (new {kind, externalId, email} shape)", () => {
       kind: "github",
       externalId: "extid-gh-handle",
     });
-    const parsed = JSON.parse(textOf(result));
+    const parsed = structuredOf(result);
     expect(parsed.id).toBe(user.id);
     expect(Array.isArray(parsed.externalIds)).toBe(true);
-    const kinds = parsed.externalIds.map((e: { kind: string }) => e.kind).sort();
+    const kinds = (parsed.externalIds as Array<{ kind: string }>).map((e) => e.kind).sort();
     expect(kinds).toEqual(["github", "slack"]);
+    // Both channels must be independently self-sufficient — the same payload
+    // is also present (via `details`) in the text channel.
+    expect(textOf(result)).toContain(user.id);
   });
 
   test("externalIds is empty array when user has no identities", async () => {
     const user = createUser({ name: "No Identities User", email: "noid@example.com" });
 
     const result = await callTool(server, "resolve-user", { email: "noid@example.com" });
-    const parsed = JSON.parse(textOf(result));
+    const parsed = structuredOf(result);
     expect(parsed.id).toBe(user.id);
     expect(parsed.externalIds).toEqual([]);
   });
@@ -204,17 +237,21 @@ describe("resolve-user MCP tool (new {kind, externalId, email} shape)", () => {
     linkIdentity(user.id, "linear", "L_UIDLOOKUP", SYSTEM_ACTOR);
 
     const result = await callTool(server, "resolve-user", { userId: user.id });
-    const parsed = JSON.parse(textOf(result));
+    const parsed = structuredOf(result);
     expect(parsed.id).toBe(user.id);
     expect(parsed.name).toBe("User ID Lookup");
     expect(parsed.externalIds).toHaveLength(1);
-    expect(parsed.externalIds[0]).toMatchObject({ kind: "linear", externalId: "L_UIDLOOKUP" });
+    expect((parsed.externalIds as unknown[])[0]).toMatchObject({
+      kind: "linear",
+      externalId: "L_UIDLOOKUP",
+    });
   });
 
   test("userId lookup returns a structured {status: 'unknown', ...} payload for an unknown ID", async () => {
     const result = await callTool(server, "resolve-user", { userId: "nonexistent-user-id-xyz" });
-    const parsed = JSON.parse(textOf(result));
-    expect(parsed).toEqual({
+    expect(result.isError).toBe(false);
+    expect(structuredOf(result)).toMatchObject({
+      success: true,
       status: "unknown",
       kind: "userId",
       externalId: "nonexistent-user-id-xyz",
@@ -225,7 +262,7 @@ describe("resolve-user MCP tool (new {kind, externalId, email} shape)", () => {
     const user = createUser({ name: "Zbigniew Solo", email: "zbigniew@example.com" });
 
     const result = await callTool(server, "resolve-user", { name: "Zbigniew Solo" });
-    const parsed = JSON.parse(textOf(result));
+    const parsed = structuredOf(result);
     expect(parsed.id).toBe(user.id);
     expect(parsed.name).toBe("Zbigniew Solo");
   });
@@ -234,7 +271,7 @@ describe("resolve-user MCP tool (new {kind, externalId, email} shape)", () => {
     const user = createUser({ name: "Priyanka Unique Prefix", email: "priyanka@example.com" });
 
     const result = await callTool(server, "resolve-user", { name: "Priyanka" });
-    const parsed = JSON.parse(textOf(result));
+    const parsed = structuredOf(result);
     expect(parsed.id).toBe(user.id);
   });
 
@@ -243,17 +280,22 @@ describe("resolve-user MCP tool (new {kind, externalId, email} shape)", () => {
     const b = createUser({ name: "Alberto Dubois", email: "alberto.dubois@example.com" });
 
     const result = await callTool(server, "resolve-user", { name: "Alberto" });
-    const parsed = JSON.parse(textOf(result));
+    const parsed = structuredOf(result);
     expect(parsed.status).toBe("ambiguous");
     expect(parsed.message).toMatch(/AMBIGUOUS/);
-    const candidateIds = parsed.candidates.map((c: { userId: string }) => c.userId).sort();
+    const candidateIds = (parsed.candidates as Array<{ userId: string }>)
+      .map((c) => c.userId)
+      .sort();
     expect(candidateIds).toEqual([a.id, b.id].sort());
+    // The "never guess" message must also reach harnesses that only read text.
+    expect(textOf(result)).toMatch(/AMBIGUOUS/);
   });
 
   test("name lookup: zero matches return a structured {status: 'unknown', kind: 'name', ...} payload", async () => {
     const result = await callTool(server, "resolve-user", { name: "Nobody Registered Xyz" });
-    const parsed = JSON.parse(textOf(result));
-    expect(parsed).toEqual({
+    expect(result.isError).toBe(false);
+    expect(structuredOf(result)).toMatchObject({
+      success: true,
       status: "unknown",
       kind: "name",
       externalId: "Nobody Registered Xyz",
@@ -364,7 +406,11 @@ describe("manage-user MCP tool (identities array)", () => {
 
   test("non-lead caller is rejected", async () => {
     const result = await callTool(server, "manage-user", { action: "list" }, WORKER_ID);
+    // NEW CONTRACT: failures set isError=true (derived from ok=false) and
+    // structuredContent.success=false — not just prose in content.text.
+    expect(result.isError).toBe(true);
     expect(textOf(result)).toContain("Only the lead agent");
+    expect(structuredOf(result)).toMatchObject({ success: false });
   });
 
   test("create no longer accepts old top-level slackUserId / linearUserId / githubUsername / gitlabUsername", async () => {

package/src/tests/mcp-tools.test.ts

@@ -48,13 +48,16 @@ describe("script MCP tools", () => {
       "script-search":
         "Semantic search over swarm-shared TypeScript scripts (catalog persisted in the agent-swarm DB; callable from agents and workflows). For ephemeral throwaway TS on your local machine, use code-mode instead.",
       "script-run":
-        "Run a named swarm-shared script (callable across agents and from workflow `swarm-script` nodes), OR inline source (auto-saved as scratch to the catalog). Use for swarm-visible, durable scripts. For local-only throwaway TS, use code-mode `run`.",
+        "Run a named swarm-shared script (callable across agents and from workflow `swarm-script` nodes), OR inline source (auto-saved as scratch to the catalog). Inline source executes without the `script-upsert` compile-time typecheck. Use for swarm-visible, durable scripts. For local-only throwaway TS, use code-mode `run`.",
       "script-upsert":
-        "Persist a TypeScript script to the swarm catalog under your agent scope (or global if you're a lead). Other agents and workflow nodes will be able to find and run it. For local-only scripts, use code-mode `save`.",
+        'Typecheck and persist a TypeScript script to the swarm catalog under your agent scope (or global if you\'re a lead). Import `ScriptContext` from "swarm-sdk" for a real context type. Other agents and workflow nodes will be able to find and run it. For local-only scripts, use code-mode `save`.',
       "script-delete":
         "Remove a swarm-shared script from the catalog. Versions table preserves history.",
       "script-query-types":
-        "Fetch the signature + the auto-generated `swarm-sdk.d.ts` (derived from the live MCP tool registry) + the `stdlib.d.ts` blobs — for IDE-style introspection before authoring or running a script. The same types are used by `script-upsert`'s typecheck pass, so they are authoritative.",
+        // Updated for the frozen SwarmToolResult contract refactor: `name` is
+        // now optional — omit it to get the swarm-wide type surface instead
+        // of a single script's signature.
+        "Fetch the auto-generated `swarm-sdk.d.ts` (derived from the live MCP tool registry) + the `stdlib.d.ts` blobs — for IDE-style introspection before authoring or running a script. Pass `name` to also get that script's signature; omit it for the swarm-wide type surface. The same types are used by `script-upsert`'s typecheck pass, so they are authoritative.",
       "launch-script-run":
         "Launch a durable one-off script workflow run. The run executes in the background and can be inspected with get-script-run for terminal status and journal entries.",
       "get-script-run":

package/src/tests/memory-edit.test.ts

@@ -254,13 +254,30 @@ describe("memory editing", () => {
           intent: "test stale-link pruning",
         },
         meta(),
-      )) as { structuredContent: { success: boolean; message: string; changed?: boolean } };
+      )) as {
+        isError?: boolean;
+        content: Array<{ type: string; text: string }>;
+        structuredContent: {
+          success: boolean;
+          message: string;
+          changed?: boolean;
+          version?: number;
+          memory?: { id?: string };
+        };
+      };
 
-      // Assert on the message first — on failure it carries the tool's error
-      // (a bare success:false told us nothing when this flaked in CI).
-      expect(result.structuredContent.message).toStartWith("Memory edited to version");
+      // New envelope contract (src/tools/utils.ts finalizeSwarmToolResult):
+      // isError = !ok, structuredContent = { ...data, success, message }, and
+      // content[0].text carries the same message. Assert on the message first
+      // — on failure it carries the tool's error (a bare success:false told us
+      // nothing when this flaked in CI).
+      expect(result.isError).toBe(false);
+      expect(result.structuredContent.message).toStartWith(`Memory "${a.id}" edited to version`);
+      expect(result.content[0]?.text).toStartWith(`Memory "${a.id}" edited to version`);
       expect(result.structuredContent.success).toBe(true);
       expect(result.structuredContent.changed).toBe(true);
+      expect(result.structuredContent.version).toBe(2);
+      expect(result.structuredContent.memory?.id).toBe(a.id);
 
       const rows = linkRowsFor(a.id);
       expect(rows).toHaveLength(2);