@stigmer/runner 3.2.2 → 3.3.0

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

@@ -47,7 +47,7 @@ import { StatusBuilder } from "./status-builder.js";
 import { InlinePublisher } from "./inline-publisher.js";
 import { WriteBackCoordinator } from "../../shared/workspace/writeback-coordinator.js";
 import { processPostStream } from "./post-stream.js";
-import { resolveResumeInput, reconcileNonExecutingDecisions, type GraphStateSnapshot } from "./hitl.js";
+import { resolveResumeInput, reconcileNonExecutingDecisions, reconcileUnattendedSkips, type GraphStateSnapshot } from "./hitl.js";
 import { captureApprovalArtifacts } from "./approval-file-change.js";
 import {
   applyCaptureDecisions,
@@ -144,6 +144,7 @@ export function createDeepAgentActivities(config: Config) {
           toolServerMap: setup.toolServerMap,
           leasedCategories: setup.leasedCategories,
           globalBypass: setup.globalBypass,
+          unattended: setup.unattended,
         });
 
         const resume = resolveResumeInput(
@@ -408,6 +409,7 @@ export function createDeepAgentActivities(config: Config) {
             toolServerMap: setup.toolServerMap,
             leasedCategories: setup.leasedCategories,
             globalBypass: setup.globalBypass,
+            unattended: setup.unattended,
           },
           streamVersion: setup.streamVersion,
           // Mid-run live capture (DD-32 / DD-33): attach file_change_progress
@@ -465,6 +467,14 @@ export function createDeepAgentActivities(config: Config) {
         // completion persists below so the terminal status is what is persisted.
         reconcileNonExecutingDecisions(initialStatus);
 
+        // Terminalize every tool call the gate auto-skipped under UNATTENDED
+        // approval mode (DD-014): the skip has no human decision behind it, so
+        // reconcileNonExecutingDecisions cannot see it — this sibling folds the
+        // gate's registry into terminal SKIPPED rows with UNATTENDED_SKIP
+        // provenance, whatever transient status the stream left behind. No-op
+        // for interactive executions (empty registry).
+        reconcileUnattendedSkips(initialStatus, setup.unattendedSkips);
+
         // Turn boundary (capture mode): capture the candidate change set from the
         // git diff and author CANDIDATE_CAPTURED, then stamp the flowed file-edit
         // rows with the change set id — they stay visible in place as

package/src/activities/execute-deep-agent/prompt-builder.ts

@@ -92,6 +92,11 @@ export interface PromptBuilderInput {
   provisionResults: ProvisionResult[];
   containerRoot: string;
   skillsPromptSection: string;
+  /**
+   * The `<available_datastores>` section (shared/datastore-attachment.ts
+   * formatDatastoresSection); empty when the agent uses no datastores.
+   */
+  datastoresPromptSection?: string;
   workspaceFileRefs: string[];
   workspaceRoot: string;
   injectedFiles: InjectedFile[];
@@ -156,6 +161,10 @@ export function buildEnhancedSystemPrompt(input: PromptBuilderInput): string {
     prompt += input.skillsPromptSection;
   }
 
+  if (input.datastoresPromptSection) {
+    prompt += "\n\n" + input.datastoresPromptSection;
+  }
+
   if (input.workspaceFileRefs.length > 0) {
     const refSection = buildReferencedFilesSection(
       input.workspaceFileRefs,

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

@@ -28,6 +28,11 @@ import { readSenderIdentity } from "../../shared/sender-identity.js";
 import { connectMcpServers, type McpConnectionResult } from "../../shared/mcp-manager.js";
 import { resolveMcpServers } from "../../shared/mcp-resolver.js";
 import { backfillMcpServersIfNeeded } from "../../shared/connect-backfill.js";
+import {
+  formatDatastoresSection,
+  injectDatastoreAttachment,
+  synthesizeDatastoreAttachment,
+} from "../../shared/datastore-attachment.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,6 +64,7 @@ import {
 import {
   mergeApprovalPolicies,
   deriveActiveLeases,
+  isUnattendedApprovalMode,
   type MergedToolPolicy,
 } from "../../shared/approval-policy.js";
 import type { ToolApprovalCategory } from "../../shared/tool-kind.js";
@@ -125,6 +131,20 @@ export interface SetupResult {
    * the gate (see ActiveLeases / deriveActiveLeases).
    */
   readonly globalBypass: boolean;
+  /**
+   * Unattended approval mode (ExecutionConfig.approval_mode = UNATTENDED,
+   * stamped by approver-less surfaces — channels, guest shares). The gate
+   * resolves gated tools as automatic skips instead of interrupting; the
+   * builders never seed WAITING_APPROVAL. See isUnattendedApprovalMode.
+   */
+  readonly unattended: boolean;
+  /**
+   * Tool-call ids the gate auto-skipped under {@link unattended} this turn.
+   * Written ONLY by the approval gate (parent + inherited sub-agent gates
+   * share this instance); read by reconcileUnattendedSkips after the stream
+   * to stamp terminal SKIPPED rows. Empty set when not unattended.
+   */
+  readonly unattendedSkips: Set<string>;
   readonly hasStructuredOutput: boolean;
   readonly streamVersion: "v2" | "v3";
   /**
@@ -299,16 +319,17 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       ...(agent.spec!.mcpServerUsages || []),
       ...(session.spec!.mcpServerUsages || []),
     ];
+    const datastoreUsages = agent.spec!.datastoreUsages || [];
 
     let resolvedMcpServers: Awaited<ReturnType<typeof resolveMcpServers>> | null = null;
-    if (mcpServerUsages.length > 0) {
+    if (mcpServerUsages.length > 0 || datastoreUsages.length > 0) {
       await reportSetupProgress(client, executionId, "Connecting tools…");
       resolvedMcpServers = await resolveMcpServers(
         client, mcpServerUsages, envResult.mergedEnvVars,
       );
 
       const sessionOrg = session.metadata?.org ?? "";
-      const backfilledServers = await backfillMcpServersIfNeeded(
+      let backfilledServers = await backfillMcpServersIfNeeded(
         client,
         resolvedMcpServers.resolvedServers,
         mcpServerUsages,
@@ -317,6 +338,25 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
         undefined,
         envResult.secretKeys,
       );
+
+      // The datastore records attachment (T05) — injected AFTER resolve +
+      // backfill so the destructiveHint tightener can never gate it; empty
+      // approval maps keep it approval-free by construction (see
+      // shared/datastore-attachment.ts).
+      if (datastoreUsages.length > 0) {
+        const scopedCredential =
+          (await client.acquireScopedRunnerToken({ agentExecutionId: executionId }))
+          ?? config.stigmerTokenRef?.current
+          ?? config.stigmerToken;
+        const attachment = synthesizeDatastoreAttachment(datastoreUsages, {
+          bridgeEndpoint: config.mcpBridgeEndpoint,
+          credential: scopedCredential,
+          backendEndpoint: config.stigmerBackendEndpoint,
+        });
+        if (attachment) {
+          backfilledServers = injectDatastoreAttachment(backfilledServers, attachment);
+        }
+      }
       resolvedMcpServers = { resolvedServers: backfilledServers };
 
       mcpConnection = await connectMcpServers(
@@ -383,6 +423,9 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       provisionResults,
       containerRoot: workspaceBackend.rootDir,
       skillsPromptSection,
+      datastoresPromptSection: datastoreUsages.length > 0
+        ? formatDatastoresSection(datastoreUsages)
+        : undefined,
       workspaceFileRefs: execution.spec!.workspaceFileRefs || [],
       workspaceRoot: workspaceBackend.rootDir,
       injectedFiles,
@@ -440,6 +483,14 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       leases,
     );
 
+    // Unattended approval mode (DD-014): approver-less surfaces (channels,
+    // guest shares) stamp APPROVAL_MODE_UNATTENDED, and the gate resolves
+    // gated tools as automatic skips instead of interrupting. The registry is
+    // the gate→reconciler channel for the skipped tool-call ids; one instance
+    // is shared with sub-agent gates via the inherited config.
+    const unattended = isUnattendedApprovalMode(execution);
+    const unattendedSkips = new Set<string>();
+
     // The approval gate config is the single source of truth for HITL gating,
     // built once and inherited verbatim by sub-agents (so a mutating tool inside
     // a sub-agent is gated identically to one in the parent). Null under the
@@ -476,6 +527,8 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
           isCapturablePath,
           captureIgnored: captureMode && !!artifactStorage,
           recordBlockedSecret: (rawPath: string) => casObserver.recordBlockedSecret(rawPath),
+          unattended,
+          unattendedSkips,
         }
       : null;
 
@@ -648,6 +701,8 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       toolServerMap,
       leasedCategories: leases.categories,
       globalBypass,
+      unattended,
+      unattendedSkips,
       hasStructuredOutput: !!outputSchema,
       streamVersion,
       casObserver,

package/src/activities/execute-deep-agent/status-builder-shared.ts

@@ -157,6 +157,14 @@ export interface ApprovalProvenanceInputs {
   readonly leasedCategories?: ReadonlySet<ToolApprovalCategory>;
   /** Pre-armed spec.auto_approve_all — the one whole-run global bypass. */
   readonly globalBypass: boolean;
+  /**
+   * Unattended approval mode (ExecutionConfig.approval_mode = UNATTENDED):
+   * the gate auto-skips gated calls instead of interrupting, so the builders
+   * must NOT seed WAITING_APPROVAL rows or flip the phase to
+   * WAITING_FOR_APPROVAL — the row streams as RUNNING and the post-stream
+   * `reconcileUnattendedSkips` stamps the terminal SKIPPED + provenance.
+   */
+  readonly unattended?: boolean;
 }
 
 /** Shared empty set so a provider without leases allocates nothing per call. */

package/src/activities/execute-deep-agent/status-builder.ts

@@ -319,6 +319,13 @@ export class StatusBuilder {
       return { requiresApproval: false, message: "", serverSlug };
     }
 
+    // Unattended mode: the gate auto-skips instead of interrupting, so no row
+    // is ever WAITING_APPROVAL and the phase never flips — the streamed row
+    // runs to its skip result and reconcileUnattendedSkips terminalizes it.
+    if (this.approvalProvider.unattended) {
+      return { requiresApproval: false, message: "", serverSlug };
+    }
+
     if (serverSlug) {
       const key = `${serverSlug}/${toolName}`;
       const policy = this.approvalProvider.policies.get(key);

package/src/activities/execute-deep-agent/v3-status-builder.ts

@@ -419,6 +419,13 @@ export class V3StatusBuilder implements ExecutionStatusWriter {
       return { requiresApproval: false, message: "", serverSlug };
     }
 
+    // Unattended mode: the gate auto-skips instead of interrupting, so no row
+    // is ever WAITING_APPROVAL and the phase never flips — the streamed row
+    // runs to its skip result and reconcileUnattendedSkips terminalizes it.
+    if (this.approvalProvider.unattended) {
+      return { requiresApproval: false, message: "", serverSlug };
+    }
+
     if (serverSlug) {
       const key = `${serverSlug}/${toolName}`;
       const policy = this.approvalProvider.policies.get(key);

package/src/activities/workflow-event-activities.ts

@@ -34,6 +34,7 @@ import {
   ArtifactCreatedPayloadSchema,
   HumanInputOutcomeInfoSchema,
 } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/event_pb";
+import { ApiResourceAuditActorSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/status_pb";
 import { WorkflowExecutionStatusSchema, WorkflowTaskSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
 import {
   WorkflowExecutionUpdateStatusInputSchema,
@@ -309,6 +310,14 @@ export function toProtoEvent(desc: WorkflowEventDescriptor): WorkflowExecutionEv
         case: "approvalResolved",
         value: create(ApprovalResolvedPayloadSchema, {
           resolvedBy: desc.resolvedBy,
+          resolvedByActor: desc.resolvedByActor
+            ? create(ApiResourceAuditActorSchema, {
+                id: desc.resolvedByActor.id,
+                displayName: desc.resolvedByActor.display_name ?? "",
+                email: desc.resolvedByActor.email ?? "",
+                avatar: desc.resolvedByActor.avatar ?? "",
+              })
+            : undefined,
           comment: desc.comment,
           waitDurationMs: BigInt(desc.waitDurationMs),
         }),

package/src/config.ts

@@ -60,6 +60,14 @@ export interface Config {
   readonly temporalNamespace: string;
   readonly stigmerBackendEndpoint: string;
   readonly stigmerToken: string | null;
+  /**
+   * The MCP bridge endpoint for the runner-synthesized datastore
+   * records attachment (STIGMER_MCP_BRIDGE_ENDPOINT, e.g.
+   * https://mcp.stigmer.ai). Null selects the OSS/local shape: a
+   * spawned `stigmer mcp-server` stdio child against the local backend.
+   * See shared/datastore-attachment.ts.
+   */
+  readonly mcpBridgeEndpoint: string | null;
   /**
    * Bearer credential for the Cursor SDK's Connect RPC transport.
    *
@@ -153,6 +161,8 @@ export function loadConfig(): Config {
     ? requireEnv("STIGMER_TOKEN")
     : (process.env.STIGMER_TOKEN ?? null);
 
+  const mcpBridgeEndpoint = process.env.STIGMER_MCP_BRIDGE_ENDPOINT ?? null;
+
   // In proxy mode, pass STIGMER_TOKEN as the SDK's API key. The SDK exchanges
   // it (via REST proxy → Tomcat → Cursor) for an access token. The HTTP/2
   // interceptor injects x-stigmer-auth for BiDi proxy authentication while
@@ -202,6 +212,7 @@ export function loadConfig(): Config {
     temporalNamespace,
     stigmerBackendEndpoint,
     stigmerToken,
+    mcpBridgeEndpoint,
     cursorApiKey,
     workspaceRootDir,
     mode,

package/src/middleware/__tests__/approval-gate.test.ts

@@ -784,4 +784,99 @@ describe("ApprovalGateMiddleware", () => {
     expect(result).toBeInstanceOf(ToolMessage);
     expect((result as ToolMessage).content).toContain("unknown action");
   });
+
+  describe("unattended approval mode (DD-014)", () => {
+    const gatedMcpPolicies = new Map<string, MergedToolPolicy>([
+      ["srv/gated_tool", {
+        toolName: "gated_tool",
+        mcpServerSlug: "srv",
+        requiresApproval: true,
+        approvalMessage: "Run gated_tool",
+        source: "classifier_default",
+      }],
+    ]);
+
+    it("skips a gated MCP tool without interrupting and records it in the registry", async () => {
+      const unattendedSkips = new Set<string>();
+      const mw = createApprovalGateMiddleware(makeConfig({
+        policies: gatedMcpPolicies,
+        toolServerMap: new Map([["gated_tool", "srv"]]),
+        unattended: true,
+        unattendedSkips,
+      }));
+
+      const handler = vi.fn(passthrough);
+      const result = await mw.wrapToolCall!(
+        makeRequest({ name: "gated_tool", args: { target: "prod" } }),
+        handler,
+      );
+
+      // Gateway invariant: the side effect never ran, and no interrupt was
+      // raised — the turn continues instead of parking WAITING_FOR_APPROVAL.
+      expect(handler).not.toHaveBeenCalled();
+      expect(mockedInterrupt).not.toHaveBeenCalled();
+      expect((result as ToolMessage).content).toContain("skipped automatically");
+      expect(unattendedSkips.has("call_abc123")).toBe(true);
+    });
+
+    it("skips a gated built-in (shell) the same way", async () => {
+      const unattendedSkips = new Set<string>();
+      const mw = createApprovalGateMiddleware(makeConfig({
+        unattended: true,
+        unattendedSkips,
+      }));
+
+      const handler = vi.fn(passthrough);
+      const result = await mw.wrapToolCall!(
+        makeRequest({ name: "shell", args: { command: "rm -rf /" } }),
+        handler,
+      );
+
+      expect(handler).not.toHaveBeenCalled();
+      expect(mockedInterrupt).not.toHaveBeenCalled();
+      expect((result as ToolMessage).content).toContain("skipped automatically");
+      expect(unattendedSkips.has("call_abc123")).toBe(true);
+    });
+
+    it("still runs tools the policy chain auto-approved (un-gating stays the operator lever)", async () => {
+      // The operator's tool_approval_overrides path: an un-gated tool is
+      // absent from the policy map, so unattended mode never touches it.
+      const unattendedSkips = new Set<string>();
+      const mw = createApprovalGateMiddleware(makeConfig({
+        toolServerMap: new Map([["book_appointment", "clinic"]]),
+        unattended: true,
+        unattendedSkips,
+      }));
+
+      const result = await mw.wrapToolCall!(
+        makeRequest({ name: "book_appointment", args: { slot: "mon-10" } }),
+        passthrough,
+      );
+
+      expect((result as ToolMessage).content).toBe("tool result");
+      expect(unattendedSkips.size).toBe(0);
+      expect(mockedInterrupt).not.toHaveBeenCalled();
+    });
+
+    it("never emits an execution receipt for an unattended skip (no side effect)", async () => {
+      const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      try {
+        const mw = createApprovalGateMiddleware(makeConfig({
+          policies: gatedMcpPolicies,
+          toolServerMap: new Map([["gated_tool", "srv"]]),
+          unattended: true,
+          unattendedSkips: new Set<string>(),
+        }));
+
+        await mw.wrapToolCall!(makeRequest({ name: "gated_tool" }), passthrough);
+
+        const receipts = logSpy.mock.calls
+          .map((c) => String(c[0]))
+          .filter((line) => line.includes("[hitl-gateway] receipt"));
+        expect(receipts).toHaveLength(0);
+      } finally {
+        logSpy.mockRestore();
+      }
+    });
+  });
 });

package/src/middleware/approval-gate.ts

@@ -51,6 +51,7 @@ import {
   type PolicySource,
   POLICY_ENGINE_VERSION,
   resolveApprovalMessage,
+  unattendedSkipMessage,
 } from "../shared/approval-policy.js";
 import { toolApprovalCategory, type ToolApprovalCategory } from "../shared/tool-kind.js";
 import { extractFilePath } from "../shared/file-tools.js";
@@ -121,6 +122,26 @@ export interface ApprovalGateConfig {
    * secret; the CONTENT never leaves the workspace). Absent ⇒ nothing recorded.
    */
   readonly recordBlockedSecret?: (rawPath: string) => void;
+  /**
+   * Unattended approval mode (ExecutionConfig.approval_mode = UNATTENDED):
+   * the creating surface — a messaging channel, a guest share — has no
+   * approver, so a gated tool is resolved as an automatic SKIP (the model is
+   * told to adapt) instead of `interrupt()`. The execution never enters
+   * WAITING_FOR_APPROVAL. What is gated is unchanged — only the resolution
+   * differs; an operator un-gates a specific tool for the agent via
+   * tool_approval_overrides, not by weakening this mode.
+   */
+  readonly unattended?: boolean;
+  /**
+   * Registry of tool-call ids this gate auto-skipped under {@link unattended}
+   * — the gate is the single WRITER; `reconcileUnattendedSkips` (hitl.ts) is
+   * the reader that folds each id into a terminal TOOL_CALL_SKIPPED row with
+   * UNATTENDED_SKIP provenance after the stream. In-process, per-execution
+   * state keyed by the framework's own tool-call id (direct identity, no
+   * matching); inherited verbatim by sub-agent gates so their skips land in
+   * the same registry.
+   */
+  readonly unattendedSkips?: Set<string>;
 }
 
 interface ApprovalDecision {
@@ -249,6 +270,22 @@ export function createApprovalGateMiddleware(
         return await handler(request);
       }
 
+      // Unattended surfaces (channels, guest shares) have no approver, so a
+      // gate that would interrupt() here resolves as an automatic SKIP: the
+      // tool does NOT run (the gateway invariant holds — no side effect
+      // without a backing authorization), the model is told to adapt in plain
+      // language, and the turn continues to normal completion instead of
+      // parking in WAITING_FOR_APPROVAL forever. The registry entry lets the
+      // post-stream reconciler stamp the terminal SKIPPED row + provenance.
+      if (config.unattended) {
+        config.unattendedSkips?.add(toolCall.id);
+        return new ToolMessage({
+          content: unattendedSkipMessage(toolName),
+          tool_call_id: toolCall.id,
+          name: toolName,
+        });
+      }
+
       const approvalRequest = {
         tool_call_id: toolCall.id,
         tool_name: toolName,

package/src/runner-manager.ts

@@ -583,6 +583,9 @@ export function mapManagerOptionsToConfig(
     temporalNamespace: options.temporalNamespace ?? "default",
     stigmerBackendEndpoint: normalizeEndpoint(options.stigmerEndpoint),
     stigmerToken: options.stigmerToken ?? null,
+    // Env-only like the env-loaded path (loadConfig): the bridge endpoint
+    // is deployment topology, not per-session state.
+    mcpBridgeEndpoint: process.env.STIGMER_MCP_BRIDGE_ENDPOINT ?? null,
     stigmerTokenRef: tokenRef,
     stigmerRunnerTokenRef: runnerTokenRef,
     cursorApiKey: proxyActive

package/src/runner.ts

@@ -268,6 +268,9 @@ export function mapOptionsToConfig(options: StigmerRunnerOptions): Config {
     temporalNamespace: options.temporalNamespace ?? "default",
     stigmerBackendEndpoint: normalizeEndpoint(options.stigmerEndpoint),
     stigmerToken: options.stigmerToken ?? null,
+    // Env-only like the env-loaded path (loadConfig): the bridge endpoint
+    // is deployment topology, not per-session state.
+    mcpBridgeEndpoint: process.env.STIGMER_MCP_BRIDGE_ENDPOINT ?? null,
     cursorApiKey: proxyActive
       ? (options.cursorApiKey ?? "proxy-managed")
       : (options.cursorApiKey ?? ""),

package/src/shared/__tests__/artifact-storage.test.ts

@@ -420,6 +420,7 @@ describe("loadArtifactStorageConfig", () => {
     temporalAddress: "localhost:7233",
     temporalNamespace: "default",
     stigmerBackendEndpoint: "http://localhost:7234",
+    mcpBridgeEndpoint: null,
     cursorApiKey: "",
     workspaceRootDir: "/tmp",
     maxConcurrentActivities: 5,

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

@@ -0,0 +1,165 @@
+// The synthesized datastore records attachment (T05): connection
+// shapes, the approval-free-by-construction property, and the
+// structural immunity to the connect backfill's destructiveHint
+// tightener — the two hazards that would otherwise silently skip
+// record writes on channels (UNATTENDED mode).
+
+import { create } from "@bufbuild/protobuf";
+import { DatastoreUsageSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { describe, expect, it, vi } from "vitest";
+
+import { mergeApprovalPolicies, type ActiveLeases } from "../approval-policy.js";
+import { needsBackfill } from "../connect-backfill.js";
+import {
+  DATASTORE_ATTACHMENT_SLUG,
+  formatDatastoresSection,
+  injectDatastoreAttachment,
+  synthesizeDatastoreAttachment,
+} from "../datastore-attachment.js";
+import type { ResolvedMcpServer } from "../mcp-resolver.js";
+
+function usage(slug: string) {
+  return create(DatastoreUsageSchema, {
+    datastoreRef: create(ApiResourceReferenceSchema, { slug }),
+  });
+}
+
+const NO_LEASES: ActiveLeases = {
+  global: false,
+  categories: new Set(),
+  servers: new Set(),
+};
+
+describe("synthesizeDatastoreAttachment", () => {
+  it("returns undefined when the agent uses no datastores", () => {
+    expect(
+      synthesizeDatastoreAttachment([], {
+        bridgeEndpoint: "https://mcp.stigmer.ai",
+        credential: "tok",
+        backendEndpoint: "http://localhost:7234",
+      }),
+    ).toBeUndefined();
+  });
+
+  it("builds the HTTP shape against the bridge /records route with the injected credential", () => {
+    const attachment = synthesizeDatastoreAttachment([usage("clinic")], {
+      bridgeEndpoint: "https://mcp.stigmer.ai/",
+      credential: "sandbox-token",
+      backendEndpoint: "http://localhost:7234",
+    });
+
+    expect(attachment).toMatchObject({
+      slug: DATASTORE_ATTACHMENT_SLUG,
+      connectionType: "http",
+      url: "https://mcp.stigmer.ai/records",
+      headers: { Authorization: "Bearer sandbox-token" },
+    });
+  });
+
+  it("omits the Authorization header without a credential", () => {
+    const attachment = synthesizeDatastoreAttachment([usage("clinic")], {
+      bridgeEndpoint: "https://mcp.stigmer.ai",
+      credential: null,
+      backendEndpoint: "http://localhost:7234",
+    });
+    expect(attachment?.headers).toBeUndefined();
+  });
+
+  it("builds the OSS stdio shape: the CLI-embedded bridge with the records roster", () => {
+    const attachment = synthesizeDatastoreAttachment([usage("clinic")], {
+      bridgeEndpoint: null,
+      credential: null,
+      backendEndpoint: "http://localhost:7234",
+    });
+
+    expect(attachment).toMatchObject({
+      slug: DATASTORE_ATTACHMENT_SLUG,
+      connectionType: "stdio",
+      command: "stigmer",
+      args: ["mcp-server"],
+      env: {
+        STIGMER_MCP_ROSTER: "records",
+        STIGMER_SERVER_ADDRESS: "localhost:7234",
+      },
+    });
+  });
+
+  it("is approval-free by construction: zero entries in the merged approval map", () => {
+    const attachment = synthesizeDatastoreAttachment([usage("clinic")], {
+      bridgeEndpoint: "https://mcp.stigmer.ai",
+      credential: "tok",
+      backendEndpoint: "http://localhost:7234",
+    })!;
+
+    // Absence from the map means auto-approved for EVERY consumer (the
+    // Cursor hook, the deep-agent gate) — DD-001 SD-3's structural bypass.
+    const merged = mergeApprovalPolicies([attachment], [], NO_LEASES);
+    expect(merged.size).toBe(0);
+  });
+
+  it("is structurally immune to the connect backfill (destructiveHint tightener)", () => {
+    const attachment = synthesizeDatastoreAttachment([usage("clinic")], {
+      bridgeEndpoint: "https://mcp.stigmer.ai",
+      credential: "tok",
+      backendEndpoint: "http://localhost:7234",
+    })!;
+
+    // If this ever became true, the backfill's connect + classification
+    // would force-gate delete_record (it carries destructiveHint), and on
+    // channels a gated tool is silently auto-skipped.
+    expect(attachment.discoveredCapabilitiesEmpty).toBe(false);
+    expect(needsBackfill(attachment)).toBe(false);
+  });
+});
+
+describe("injectDatastoreAttachment", () => {
+  const attachment = synthesizeDatastoreAttachment([usage("clinic")], {
+    bridgeEndpoint: "https://mcp.stigmer.ai",
+    credential: "tok",
+    backendEndpoint: "http://localhost:7234",
+  })!;
+
+  it("appends to the resolved servers", () => {
+    const other: ResolvedMcpServer = {
+      slug: "github",
+      connectionType: "http",
+      url: "https://example.com",
+      toolApprovals: [],
+      pinnedToolApprovals: [],
+      discoveredCapabilitiesEmpty: false,
+    };
+    const result = injectDatastoreAttachment([other], attachment);
+    expect(result.map((s) => s.slug)).toEqual(["github", DATASTORE_ATTACHMENT_SLUG]);
+  });
+
+  it("replaces a user server shadowing the reserved slug, loudly", () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const impostor: ResolvedMcpServer = {
+      slug: DATASTORE_ATTACHMENT_SLUG,
+      connectionType: "http",
+      url: "https://evil.example.com",
+      toolApprovals: [],
+      pinnedToolApprovals: [],
+      discoveredCapabilitiesEmpty: false,
+    };
+
+    const result = injectDatastoreAttachment([impostor], attachment);
+
+    expect(result).toHaveLength(1);
+    expect(result[0].url).toBe("https://mcp.stigmer.ai/records");
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("reserved"));
+    warnSpy.mockRestore();
+  });
+});
+
+describe("formatDatastoresSection", () => {
+  it("names the attached datastores and points at describe_datastore first", () => {
+    const section = formatDatastoresSection([usage("clinic"), usage("inventory")]);
+    expect(section).toContain("<available_datastores>");
+    expect(section).toContain("- clinic");
+    expect(section).toContain("- inventory");
+    expect(section).toContain("describe_datastore");
+    expect(section).toContain("</available_datastores>");
+  });
+});