@stigmer/runner 3.6.0 → 3.8.0

package/src/activities/execute-deep-agent/setup.ts

@@ -25,6 +25,7 @@ import type { StigmerClient } from "../../client/stigmer-client.js";
 import { TimingRecorder, emitTimingLog } from "../../shared/cold-start-timing.js";
 import { createCheckpointer } from "../../shared/checkpointer/factory.js";
 import { readContextBridge } from "../../shared/context-bridge.js";
+import { readConversationCatchup } from "../../shared/conversation-catchup.js";
 import { readSenderIdentity } from "../../shared/sender-identity.js";
 import {
   injectCallerIdentityEnv,
@@ -44,7 +45,12 @@ import {
   formatChannelTemplatesSection,
   synthesizeChannelAttachment,
 } from "../../shared/channel-attachment.js";
+import {
+  readChannelConversationId,
+  synthesizeConversationAttachment,
+} from "../../shared/conversation-attachment.js";
 import { injectSynthesizedAttachment } from "../../shared/synthesized-attachment.js";
+import { shouldConnectMcp } from "./mcp-gate.js";
 import { WorkspaceProvisioner } from "../../shared/workspace/provisioner.js";
 import { LocalWorkspaceBackend } from "../../shared/workspace/local-backend.js";
 import type { WorkspaceBackend, ProvisionResult } from "../../shared/workspace/types.js";
@@ -59,7 +65,7 @@ import { resolveSessionWorkspaceRoot } from "../../shared/workspace/session-root
 import { buildWorkspaceFileTree } from "../../shared/workspace/file-tree.js";
 import { reportSetupProgress } from "../../shared/status.js";
 import { resolveEnvironment, type EnvironmentResult } from "./environment.js";
-import { buildEnhancedSystemPrompt } from "./prompt-builder.js";
+import { buildEnhancedSystemPrompt, composeUserMessage } from "./prompt-builder.js";
 import { buildMiddlewareStack } from "../../middleware/index.js";
 import type { GracefulStopMiddleware } from "../../middleware/index.js";
 import { createThinkTool, createWebFetchTool, resolveGuardPosture } from "../../tools/index.js";
@@ -361,8 +367,18 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
     // answer — no tool, no section, execution unharmed.
     const channelMessaging = await discoverChannelMessaging(client, exchangedRunnerToken);
 
+    // The conversation-attachment decision (DD-008 D-c): the channel-id
+    // session label, stamped server-side on every channel session — a
+    // free, synchronous read, so no hoisted discovery needed.
+    const conversationChannelId = readChannelConversationId(session.metadata?.labels);
+
     let resolvedMcpServers: Awaited<ReturnType<typeof resolveMcpServers>> | null = null;
-    if (mcpServerUsages.length > 0 || datastoreUsages.length > 0 || channelMessaging.length > 0) {
+    if (shouldConnectMcp({
+      mcpServerUsageCount: mcpServerUsages.length,
+      datastoreUsageCount: datastoreUsages.length,
+      channelMessagingCount: channelMessaging.length,
+      conversationChannelId,
+    })) {
       await reportSetupProgress(client, executionId, "Connecting tools…");
       const transportPosture = resolveMcpTransportPosture(config.mode);
       // The MCP-bound env map (and ONLY it) carries the reserved
@@ -424,6 +440,21 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
           );
         }
       }
+
+      // The conversation participation attachment (DD-008 D-c) — the
+      // third sibling, same after-backfill rule. HTTP-only: synthesize
+      // answers undefined with no bridge endpoint by design (see
+      // shared/conversation-attachment.ts).
+      const conversationAttachment = synthesizeConversationAttachment(conversationChannelId, {
+        bridgeEndpoint: config.mcpBridgeEndpoint,
+        credential: attachmentCredential,
+        backendEndpoint: config.stigmerBackendEndpoint,
+      });
+      if (conversationAttachment) {
+        backfilledServers = injectSynthesizedAttachment(
+          backfilledServers, conversationAttachment, "conversation participation",
+        );
+      }
       resolvedMcpServers = { resolvedServers: backfilledServers };
       timing.mark("backfill_mcp");
 
@@ -743,8 +774,13 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       ...(isPlanMode ? { permissions: planModePermissions } : {}),
     } as Parameters<typeof createDeepAgent>[0]);
 
-    // Step 11: Prepare invocation input and config
-    let userMessage = execution.spec!.message;
+    // Step 11: Prepare invocation input and config. The conversation catchup
+    // (cloud DD-006) rides the USER MESSAGE, not the system prompt — see
+    // composeUserMessage for the durability rationale (A27).
+    let userMessage = composeUserMessage(
+      execution.spec!.message,
+      readConversationCatchup(execution.spec!.conversationCatchup),
+    );
     if (outputSchema) {
       userMessage += `\n\n---\nIMPORTANT: When your analysis is complete, provide your findings as structured output matching the required schema. The system will capture your structured response automatically.`;
     }

package/src/client/stigmer-client.ts

@@ -49,7 +49,7 @@ import { WorkflowQueryController } from "@stigmer/protos/ai/stigmer/agentic/work
 import type { Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
 import { WorkflowInstanceQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/query_pb";
 import type { WorkflowInstance } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/api_pb";
-import { PlatformQueryController, GetRunnerScopedTokenInputSchema } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+import { PlatformQueryController, GetRunnerScopedTokenInputSchema, TokenRenewalSchema } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
 import { ChannelMessageQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_query_pb";
 import type { ChannelTemplate, MessagingChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
 import { isEmbeddedRunnerToken } from "./token-claims.js";
@@ -94,12 +94,16 @@ export interface RunnerScopedToken {
  * `poolClaimSessionId` is the warm-pool attach exchange: a pool sandbox
  * presenting its pool_sandbox credential for the session it was claimed for
  * (the server authorizes against the claim record, not the caller's FGA
- * relations). The execution arms remain embedded_runner-only.
+ * relations). `renewal` is a live sandbox extending its own credential
+ * before expiry: no id is named because every mint parameter comes from the
+ * presented credential's verified claims (see sandbox-token-renewal.ts).
+ * The execution arms remain embedded_runner-only.
  */
 export type RunnerScopedTokenScope =
   | { agentExecutionId: string }
   | { workflowExecutionId: string }
-  | { poolClaimSessionId: string };
+  | { poolClaimSessionId: string }
+  | { renewal: true };
 
 /**
  * Map the scope union onto the proto oneof init shape. The narrowing chain is
@@ -113,7 +117,10 @@ function toRunnerScopedTokenOneof(scope: RunnerScopedTokenScope) {
   if ("workflowExecutionId" in scope) {
     return { case: "workflowExecutionId", value: scope.workflowExecutionId } as const;
   }
-  return { case: "poolClaim", value: { sessionId: scope.poolClaimSessionId } } as const;
+  if ("poolClaimSessionId" in scope) {
+    return { case: "poolClaim", value: { sessionId: scope.poolClaimSessionId } } as const;
+  }
+  return { case: "renewal", value: create(TokenRenewalSchema) } as const;
 }
 
 /**

package/src/main.ts

@@ -213,6 +213,25 @@ async function runPoolMode(
     executionMode: config.mode,
   });
 
+  // Sandbox credential self-renewal (see sandbox-token-renewal.ts). Watches
+  // the env var because manager.updateToken keeps it in lockstep with the
+  // manager's internal ref: a blank member's pool_sandbox token parks the
+  // loop, the claim's updateToken swaps in a renewable session token, and
+  // from then on renewal applies fresh tokens back through the same
+  // updateToken (which also cascades to the proxy-credential coordinator).
+  const { startSandboxTokenRenewal } = await import("./sandbox-token-renewal.js");
+  const { StigmerClient } = await import("./client/stigmer-client.js");
+  const renewalClient = new StigmerClient({
+    endpoint: config.stigmerBackendEndpoint,
+    token: null,
+  });
+  const tokenRenewal = startSandboxTokenRenewal({
+    getToken: () => process.env.STIGMER_TOKEN ?? null,
+    renew: (currentToken) =>
+      renewalClient.getRunnerScopedToken({ renewal: true }, currentToken),
+    applyToken: (token) => manager.updateToken(token),
+  });
+
   let taskQueue: string;
   if (intent.kind === "pool-control") {
     registerPoolMemberContext({
@@ -277,6 +296,7 @@ async function runPoolMode(
       }
       shutdownRequested = true;
       console.warn(`[pool-member] Received ${signal}, shutting down gracefully...`);
+      tokenRenewal.stop();
       void manager.shutdown().then(resolve, (err) => {
         console.error("[pool-member] Shutdown failed:", err);
         resolve();

package/src/runner.ts

@@ -114,6 +114,56 @@ export interface StigmerRunner {
   shutdown(): void;
 }
 
+/**
+ * Wire up self-renewal for a static cloud sandbox's control-plane credential
+ * (see sandbox-token-renewal.ts for the model). The applied token reaches
+ * every consumer: activity gRPC clients read {@code tokenRef} per request,
+ * env-reading call sites (call-llm, registry-endpoint) read
+ * {@code process.env.STIGMER_TOKEN} per call, artifact storage resolves the
+ * ref per call, and the two Cursor SDK interceptors are updated directly —
+ * a static runner has no {@code RunnerTokenCoordinator} minting a separate
+ * proxy credential, so its x-stigmer-auth IS this token.
+ */
+async function startStaticSandboxTokenRenewal(
+  config: Config,
+  tokenRef: { current: string | null },
+): Promise<{ stop(): void } | null> {
+  const { isRenewableSandboxToken, startSandboxTokenRenewal } = await import(
+    "./sandbox-token-renewal.js"
+  );
+  // Static mode's credential class never changes (it is baked into the pod's
+  // env), so a non-renewable credential — desktop/OSS/local — never starts
+  // the loop at all.
+  if (!isRenewableSandboxToken(tokenRef.current)) {
+    return null;
+  }
+
+  const { StigmerClient } = await import("./client/stigmer-client.js");
+  const { updateInterceptorToken } = await import(
+    "./activities/execute-cursor/fetch-interceptor.js"
+  );
+  const { updateHttp2InterceptorToken } = await import(
+    "./activities/execute-cursor/http2-interceptor.js"
+  );
+  const client = new StigmerClient({
+    endpoint: config.stigmerBackendEndpoint,
+    token: null,
+    tokenRef,
+  });
+
+  return startSandboxTokenRenewal({
+    getToken: () => tokenRef.current,
+    renew: (currentToken) =>
+      client.getRunnerScopedToken({ renewal: true }, currentToken),
+    applyToken: (token) => {
+      tokenRef.current = token;
+      process.env.STIGMER_TOKEN = token;
+      updateInterceptorToken(token);
+      updateHttp2InterceptorToken(token);
+    },
+  });
+}
+
 /**
  * Create a Stigmer runner ready to poll a Temporal task queue.
  *
@@ -198,13 +248,24 @@ export async function createStigmerRunner(
     token: options.stigmerToken,
     stigmerEndpoint: baseConfig.stigmerBackendEndpoint,
   });
+  // The control-plane credential lives in a shared mutable ref (as in manager
+  // mode) so the sandbox-token renewal below can rotate it in-process:
+  // activity clients read the ref per request instead of pinning the boot
+  // token for the pod's whole life.
+  const tokenRef = { current: baseConfig.stigmerToken };
   const config: Config = {
     ...baseConfig,
     temporalAddress: coordinates.temporalAddress,
     temporalNamespace: coordinates.temporalNamespace,
+    stigmerTokenRef: tokenRef,
   };
   markBoot("bootstrap_resolved");
 
+  // Cloud sandbox credential self-renewal (no-op for desktop/OSS/local
+  // credentials — see the helper). Started before the worker so the first
+  // renewal point is scheduled even if the pod boots with a part-used token.
+  const tokenRenewal = await startStaticSandboxTokenRenewal(config, tokenRef);
+
   const { setExecutionContextRef } = await import(
     "./activities/execute-cursor/rejection-capture.js"
   );
@@ -242,6 +303,7 @@ export async function createStigmerRunner(
       console.log("Worker stopped");
     },
     shutdown() {
+      tokenRenewal?.stop();
       worker.shutdown();
     },
   };

package/src/sandbox-token-renewal.ts

@@ -0,0 +1,212 @@
+/**
+ * Self-renewal of a cloud sandbox's control-plane credential (STIGMER_TOKEN).
+ *
+ * A sandbox token is minted with a fixed TTL, but the sandbox it serves has
+ * no fixed lifetime: an active conversation extends a session sandbox
+ * indefinitely, and a long workflow run can outlast any TTL chosen at
+ * provisioning. Before this module, the only refresh path was the control
+ * plane's Secret-rewrite + pod restart — which the 2026-08-05 incident
+ * showed both sacrifices the turn that trips it (the old pod picks up the
+ * work holding the dead env token) and wipes an ephemeral sandbox's
+ * workspace. Renewal decouples credential lifetime from sandbox lifetime:
+ * the runner re-mints in-process before expiry via the getRunnerScopedToken
+ * `renewal` arm, and the server bounds renewability by the live sandbox
+ * record (a reaped sandbox's credential dies with it).
+ *
+ * Relationship to {@link createRunnerTokenCoordinator}
+ * (runner-token-coordinator.ts): the coordinator owns the PROXY credential
+ * (x-stigmer-auth) and re-mints it using the control-plane token; this
+ * module keeps that control-plane token itself fresh, so the two form one
+ * chain with no expiring root. They stay separate modules because their
+ * hosts differ — every proxy-mode runner has a coordinator, but only
+ * in-cluster sandbox runners (static cloud sandboxes and pool members) hold
+ * a renewable credential; the desktop's control-plane token is the user's
+ * own Auth0 token, refreshed by the host app.
+ *
+ * The loop re-reads the CURRENT token every cycle rather than binding to
+ * the boot credential, because the credential's class can change under it:
+ * a pool member boots with a non-renewable pool_sandbox token and swaps to
+ * a renewable session token at claim time (attach-session.ts). A
+ * non-renewable token parks the loop on a slow recheck instead of stopping
+ * it, so the swap is picked up without any coupling to the claim path.
+ */
+
+/**
+ * Renew once the token has lived this fraction of its issued lifetime
+ * (anchored on iat/exp, the coordinator's 0.8 convention). Anchoring on the
+ * ISSUED lifetime matters: a fraction of the *remaining* lifetime re-arms at
+ * 80% of an ever-shrinking remainder and never reaches the renewal point.
+ */
+const RENEW_AT_LIFETIME_FRACTION = 0.8;
+
+/**
+ * Fallback safety margin before expiry for a token without an iat claim:
+ * renew this early, leaving room for two retry cycles.
+ */
+const FALLBACK_RENEW_MARGIN_MS = 10 * 60_000;
+
+/** Retry delay after a failed renewal — short enough to recover well before expiry. */
+const RETRY_DELAY_MS = 60_000;
+
+/** Recheck cadence while the current token is not a renewable class (pre-claim pool member). */
+const RECHECK_DELAY_MS = 60_000;
+
+/** Floor for any scheduled delay so a malformed expiry cannot spin a hot loop. */
+const MIN_DELAY_MS = 5_000;
+
+/** The token_type claims the renewal arm accepts (mirrors the server's gate). */
+const RENEWABLE_TOKEN_TYPES = new Set(["sandbox", "workflow_sandbox"]);
+
+export interface SandboxTokenRenewalOptions {
+  /** Reads the credential currently in effect (re-read every cycle; see module doc). */
+  readonly getToken: () => string | null | undefined;
+  /**
+   * Calls the getRunnerScopedToken `renewal` arm authenticated with
+   * {@code currentToken}. Returns undefined when the server minted nothing;
+   * the loop retries rather than crashing the runner.
+   */
+  readonly renew: (currentToken: string) => Promise<
+    { token: string; expiresInSeconds?: number } | undefined
+  >;
+  /** Applies a freshly minted credential to every sink the host wires (ref, env, interceptors). */
+  readonly applyToken: (token: string) => void;
+  /** Optional structured logger; defaults to console. */
+  readonly log?: Pick<typeof console, "log" | "warn">;
+}
+
+export interface SandboxTokenRenewal {
+  /** Stop the renewal timer. Idempotent. */
+  stop(): void;
+}
+
+/**
+ * Whether a token's decoded claims mark it as renewable through the
+ * `renewal` arm. Exported so a static-mode host can decide not to start
+ * the loop at all for a credential whose class can never change.
+ */
+export function isRenewableSandboxToken(token: string | null | undefined): boolean {
+  const claims = decodeClaims(token);
+  return claims !== null
+    && RENEWABLE_TOKEN_TYPES.has(claims.tokenType ?? "")
+    && claims.expMs !== null;
+}
+
+/**
+ * Start the renewal loop. The first cycle runs immediately (it only reads
+ * the token and schedules; no network call unless the credential is already
+ * past its renewal point).
+ */
+export function startSandboxTokenRenewal(
+  options: SandboxTokenRenewalOptions,
+): SandboxTokenRenewal {
+  const log = options.log ?? console;
+  let stopped = false;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  const schedule = (delayMs: number): void => {
+    if (stopped) {
+      return;
+    }
+    timer = setTimeout(() => {
+      void cycle();
+    }, Math.max(MIN_DELAY_MS, delayMs));
+    // Never keep the process alive solely for a token renewal.
+    timer.unref?.();
+  };
+
+  const cycle = async (): Promise<void> => {
+    if (stopped) {
+      return;
+    }
+    const token = options.getToken() ?? null;
+    const claims = decodeClaims(token);
+
+    if (token === null || claims === null
+        || !RENEWABLE_TOKEN_TYPES.has(claims.tokenType ?? "")) {
+      // Not (yet) a renewable credential — a pre-claim pool member, or a
+      // credential class this loop does not own. Park and look again.
+      schedule(RECHECK_DELAY_MS);
+      return;
+    }
+
+    if (claims.expMs === null) {
+      // A renewable-class token without an expiry is a mint-side anomaly;
+      // renewing "before expiry" is undefined, so park rather than spin.
+      log.warn("[sandbox-token-renewal] Credential carries no exp claim; parking");
+      schedule(RECHECK_DELAY_MS);
+      return;
+    }
+
+    const renewAtMs = claims.iatMs !== null
+      ? claims.iatMs + (claims.expMs - claims.iatMs) * RENEW_AT_LIFETIME_FRACTION
+      : claims.expMs - FALLBACK_RENEW_MARGIN_MS;
+    const delayMs = renewAtMs - Date.now();
+    if (delayMs > MIN_DELAY_MS) {
+      schedule(delayMs);
+      return;
+    }
+
+    // At or past the renewal point (possibly past expiry after a long pod
+    // pause — the attempt is still correct: the server decides).
+    try {
+      const renewed = await options.renew(token);
+      if (renewed) {
+        options.applyToken(renewed.token);
+        log.log("[sandbox-token-renewal] Sandbox credential renewed");
+        // Recompute from the fresh token (its own exp is authoritative).
+        schedule(MIN_DELAY_MS);
+      } else {
+        log.warn("[sandbox-token-renewal] Server minted no renewal; will retry");
+        schedule(RETRY_DELAY_MS);
+      }
+    } catch (err) {
+      log.warn(
+        "[sandbox-token-renewal] Renewal failed; will retry: " +
+        `${err instanceof Error ? err.message : err}`,
+      );
+      schedule(RETRY_DELAY_MS);
+    }
+  };
+
+  void cycle();
+
+  return {
+    stop(): void {
+      stopped = true;
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    },
+  };
+}
+
+/**
+ * Decode the claims this module reads (token_type, iat, exp) from an
+ * unverified JWT. Decode-only on purpose: this is the runner's OWN
+ * credential, minted by the server it will present it back to —
+ * verification happens there.
+ */
+function decodeClaims(
+  token: string | null | undefined,
+): { tokenType: string | undefined; iatMs: number | null; expMs: number | null } | null {
+  if (!token) {
+    return null;
+  }
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    return null;
+  }
+  try {
+    const payload = JSON.parse(
+      Buffer.from(parts[1], "base64url").toString("utf-8"),
+    ) as { token_type?: string; iat?: number; exp?: number };
+    return {
+      tokenType: payload.token_type,
+      iatMs: typeof payload.iat === "number" ? payload.iat * 1000 : null,
+      expMs: typeof payload.exp === "number" ? payload.exp * 1000 : null,
+    };
+  } catch {
+    return null;
+  }
+}

package/src/shared/__tests__/channel-attachment.test.ts

@@ -3,9 +3,9 @@
  * discovery with the never-throw failure posture, both connection
  * shapes, the structural approval-freedom the datastore attachment
  * pinned before it, and the prompt section's filter/order/cap rules
- * (DD-006 D6). The cross-repo pinned strings (slug, route, roster) are
- * guarded here and in the mcp-server integration test — the
- * TOOL_CALL_LIMIT precedent.
+ * (DD-006 D6). The route is the cross-repo string, guarded here and in
+ * the mcp-server integration test (the TOOL_CALL_LIMIT precedent); the
+ * slug and roster are runner-internal and guarded here alone.
  */
 
 import { describe, expect, it, vi } from "vitest";

package/src/shared/__tests__/conversation-attachment.test.ts

@@ -0,0 +1,138 @@
+/**
+ * The conversation participation attachment (channel-conversations
+ * DD-008 D-c, A14): the label-keyed attachment decision, the HTTP-only
+ * shape (the deliberate no-stdio divergence from both siblings), the
+ * structural approval-freedom, and the pinned strings. The route is the
+ * cross-repo string — pinned here and in the mcp-server's conversation
+ * integration test (the TOOL_CALL_LIMIT precedent); the label is pinned
+ * here and in the cloud's ChannelSessionBrokerTest (the sender-identity
+ * mirror-guard precedent).
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { mergeApprovalPolicies, type ActiveLeases } from "../approval-policy.js";
+import { needsBackfill } from "../connect-backfill.js";
+import {
+  CHANNEL_ID_LABEL,
+  CONVERSATION_ATTACHMENT_SLUG,
+  CONVERSATION_ROUTE,
+  readChannelConversationId,
+  synthesizeConversationAttachment,
+} from "../conversation-attachment.js";
+
+const noLeases: ActiveLeases = {
+  global: false,
+  categories: new Set(),
+  servers: new Set(),
+};
+
+const cloudOptions = {
+  bridgeEndpoint: "https://mcp.stigmer.ai",
+  credential: "sandbox-token",
+  backendEndpoint: "http://localhost:7234",
+};
+
+describe("cross-repo and cross-file pinned strings", () => {
+  it("pins the label verbatim to the cloud's ChannelRuntimeConstants (mirror guard)", () => {
+    // Pinned to ChannelRuntimeConstants.CHANNEL_ID_METADATA_KEY in
+    // stigmer-cloud (ChannelSessionCreateScopeStep stamps it; the
+    // mirror-guard test lives in ChannelSessionBrokerTest). Drift
+    // degrades to honest absence — the escalation tool silently stops
+    // attaching — never worse; change BOTH sides together.
+    expect(CHANNEL_ID_LABEL).toBe("stigmer.ai/channel-id");
+  });
+
+  it("pins the attachment slug and the bridge route", () => {
+    // The slug is runner-internal (the resolved-server name and shadow
+    // key). The route is cross-repo: the mcp-server's conversation
+    // integration test pins CONVERSATION_ROUTE independently — a drift
+    // strands every synthesized attachment on a 404.
+    expect(CONVERSATION_ATTACHMENT_SLUG).toBe("stigmer-conversation");
+    expect(CONVERSATION_ROUTE).toBe("/conversation");
+  });
+});
+
+describe("readChannelConversationId", () => {
+  it("reads the serving channel id from the session labels", () => {
+    expect(readChannelConversationId({ [CHANNEL_ID_LABEL]: "agch_1" })).toBe("agch_1");
+  });
+
+  it("treats missing labels, a missing key, and blank values as absent", () => {
+    expect(readChannelConversationId(undefined)).toBeUndefined();
+    expect(readChannelConversationId({})).toBeUndefined();
+    expect(readChannelConversationId({ [CHANNEL_ID_LABEL]: "" })).toBeUndefined();
+    expect(readChannelConversationId({ [CHANNEL_ID_LABEL]: "   " })).toBeUndefined();
+  });
+
+  it("ignores unrelated labels", () => {
+    expect(
+      readChannelConversationId({ "stigmer.ai/channel-conversation-key": "919000000001" }),
+    ).toBeUndefined();
+  });
+});
+
+describe("synthesizeConversationAttachment", () => {
+  it("returns undefined when the session serves no channel conversation", () => {
+    expect(synthesizeConversationAttachment(undefined, cloudOptions)).toBeUndefined();
+  });
+
+  it("returns undefined without a bridge endpoint — HTTP-only, no stdio fallback", () => {
+    // The deliberate divergence from both sibling attachments: escalate
+    // is cloud-only (OSS refuses FAILED_PRECONDITION) AND
+    // session-token-only (a stdio child's API key carries no session_id
+    // claim), so a stdio shape could only ever fail. Honest absence.
+    expect(
+      synthesizeConversationAttachment("agch_1", {
+        bridgeEndpoint: null,
+        credential: "sandbox-token",
+        backendEndpoint: "http://localhost:7234",
+      }),
+    ).toBeUndefined();
+    expect(
+      synthesizeConversationAttachment("agch_1", {
+        bridgeEndpoint: "",
+        credential: "sandbox-token",
+        backendEndpoint: "http://localhost:7234",
+      }),
+    ).toBeUndefined();
+  });
+
+  it("builds the HTTP shape against the bridge /conversation route with the credential", () => {
+    const attachment = synthesizeConversationAttachment("agch_1", {
+      ...cloudOptions,
+      bridgeEndpoint: "https://mcp.stigmer.ai/",
+    });
+
+    expect(attachment).toMatchObject({
+      slug: CONVERSATION_ATTACHMENT_SLUG,
+      connectionType: "http",
+      url: "https://mcp.stigmer.ai/conversation",
+      headers: { Authorization: "Bearer sandbox-token" },
+    });
+  });
+
+  it("omits the Authorization header without a credential", () => {
+    const attachment = synthesizeConversationAttachment("agch_1", {
+      ...cloudOptions,
+      credential: null,
+    });
+    expect(attachment?.headers).toBeUndefined();
+  });
+
+  it("is approval-free by construction: zero entries in the merged approval map", () => {
+    const attachment = synthesizeConversationAttachment("agch_1", cloudOptions)!;
+
+    // Channel surfaces run APPROVAL_MODE_UNATTENDED, where a gated tool
+    // resolves as skip-and-adapt — a gated escalation would never fire
+    // (DD-008's approval-free ruling, the DD-001 SD-3 structural bypass).
+    const merged = mergeApprovalPolicies([attachment], [], noLeases);
+    expect(merged.size).toBe(0);
+  });
+
+  it("is structurally immune to the connect backfill", () => {
+    const attachment = synthesizeConversationAttachment("agch_1", cloudOptions)!;
+    expect(attachment.discoveredCapabilitiesEmpty).toBe(false);
+    expect(needsBackfill(attachment)).toBe(false);
+  });
+});