@stigmer/runner 3.12.1 → 3.12.2

package/src/activities/generate-session-subject.ts

@@ -0,0 +1,370 @@
+/**
+ * GenerateSessionSubject Temporal activity — replaces the sentinel subject of
+ * an auto-created session with a concise LLM-generated conversation title.
+ *
+ * Called fire-and-forget by the Go InvokeAgentExecutionWorkflow (Step 1.5 of
+ * BOTH the deep-agent and cursor flows) on the runner task queue, with a 60 s
+ * deadline and a single attempt. Failures are non-critical by contract: the
+ * session simply keeps its sentinel subject, and the workflow logs a warning.
+ *
+ * Cross-edition parity: this is the behavioral twin of stigmer-cloud's
+ * GenerateSessionSubjectActivityImpl (Java, runs in-process on the server
+ * because the Java server owns an LLM call service; the OSS LLM stack lives
+ * here in the runner). The system prompt, skip rules, 50-char cap, and the
+ * heuristic fallback are kept in lockstep so both editions title sessions
+ * identically. The previous owner was the retired Python agent-runner
+ * (stigmer/stigmer#665).
+ *
+ * Model + credential resolution follows ClassifyToolApprovals: the economy
+ * model for the configured primary (registry costTier=economy, graceful
+ * degrade to the primary), routed through the Stigmer proxy when one is
+ * configured, else called directly with the operator's provider key. Unlike
+ * classification — a security gate that fails closed — a missing credential
+ * here degrades to a heuristic title (the first words of the user message):
+ * a title is worth having even when no model is reachable.
+ *
+ * Activity contract (the Go stub dispatches exactly ONE argument — the cloud
+ * Java signature carries a second, invokerIdentityAccountId, that never
+ * crosses this wire):
+ *   Name:   "GenerateSessionSubject"
+ *   Input:  (executionId: string)
+ *   Output: void
+ */
+
+import { SystemMessage, HumanMessage } from "@langchain/core/messages";
+import { ConnectError, Code } from "@connectrpc/connect";
+import { activityStarted, activityFinished } from "../idle-watchdog.js";
+import { StigmerClient } from "../client/stigmer-client.js";
+import { getSummarizationModel } from "../shared/model-registry.js";
+import { buildChatModel } from "../shared/model-client.js";
+import { checkDirectCredentials } from "../shared/llm-backend.js";
+import { tryInferProvider } from "../shared/llm-proxy.js";
+import type { Config } from "../config.js";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import type { AgentInstance } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
+
+/**
+ * The sentinel written by the server on auto-created sessions — byte-identical
+ * to `autoCreatedSessionSubject` in stigmer-server's agentexecution create
+ * pipeline and to AUTO_CREATED_SUBJECT in the cloud activity. Only sessions
+ * still carrying it (or an empty subject) are ever titled.
+ */
+export const AUTO_CREATED_SUBJECT = "Auto-created session";
+
+const MAX_SUBJECT_LENGTH = 50;
+/** Titles are tiny; matches the cloud activity's completion budget. */
+const MAX_COMPLETION_TOKENS = 100;
+const TEMPERATURE = 0.7;
+
+/** Kept verbatim in lockstep with the cloud activity's SYSTEM_PROMPT. */
+const SYSTEM_PROMPT = `\
+You are a session title generator. Given a user's message and agent context, \
+produce a concise conversation title.
+
+Rules:
+- 3 to 7 words, maximum 50 characters
+- Capture the user's core intent or topic
+- Be specific (e.g. "PostgreSQL Multi-AZ Setup" not "Database Help")
+- No filler words ("help with", "question about", "I need")
+- No quotes, no punctuation at the end
+- Output ONLY the title, nothing else`;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Core logic (no Temporal coupling)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The client surface this activity needs — StigmerClient satisfies it. */
+export interface SessionSubjectClient {
+  getExecution(executionId: string): Promise<AgentExecution>;
+  getSession(sessionId: string): Promise<Session>;
+  getAgent(agentId: string): Promise<Agent>;
+  getAgentInstance(instanceId: string): Promise<AgentInstance>;
+  updateSessionSubject(sessionId: string, subject: string): Promise<Session>;
+}
+
+export interface GenerateSessionSubjectOptions {
+  /** Null when the deployment has no proxy — the runner calls providers directly. */
+  proxyEndpoint: string | null;
+  stigmerToken: string | null;
+  primaryModel: string;
+}
+
+export async function generateSessionSubject(
+  executionId: string,
+  client: SessionSubjectClient,
+  options: GenerateSessionSubjectOptions,
+): Promise<void> {
+  const execution = await getOrSkip(
+    () => client.getExecution(executionId),
+    `execution not found: ${executionId}`,
+  );
+  if (execution === undefined) return;
+
+  const sessionId = execution.spec?.sessionId ?? "";
+  const userMessage = execution.spec?.message ?? "";
+  if (sessionId === "") {
+    log(`no session_id on execution ${executionId}, skipping`);
+    return;
+  }
+  if (userMessage === "") {
+    log(`no user message on execution ${executionId}, skipping`);
+    return;
+  }
+
+  const session = await getOrSkip(
+    () => client.getSession(sessionId),
+    `session not found: ${sessionId}`,
+  );
+  if (session === undefined) return;
+
+  const currentSubject = session.spec?.subject ?? "";
+  if (currentSubject !== "" && currentSubject !== AUTO_CREATED_SUBJECT) {
+    log(`subject is '${currentSubject}' (already set), skipping`);
+    return;
+  }
+
+  const agentId = await resolveAgentId(execution, session, client);
+  if (agentId === "") {
+    log(`cannot resolve agent_id for execution ${executionId}, skipping`);
+    return;
+  }
+
+  const agent = await getOrSkip(
+    () => client.getAgent(agentId),
+    `agent not found: ${agentId}`,
+  );
+  if (agent === undefined) return;
+
+  const subject = await generateTitle({
+    userMessage,
+    agentName: agent.metadata?.name ?? "",
+    agentDescription: agent.spec?.description ?? "",
+    executionId,
+    options,
+  });
+
+  if (subject === "") {
+    log("subject is empty after generation, skipping");
+    return;
+  }
+
+  try {
+    await client.updateSessionSubject(sessionId, subject);
+  } catch (err) {
+    log(`failed to persist subject for session ${sessionId}: ${message(err)}`);
+    return;
+  }
+
+  log(`updated session ${sessionId} subject to '${subject}'`);
+}
+
+/**
+ * The agent behind the execution: the direct agent_id when the execution
+ * carries one, else resolved through the session's agent-instance chain.
+ * Empty string when unresolvable. Mirrors the cloud activity's resolveAgentId.
+ */
+export async function resolveAgentId(
+  execution: AgentExecution,
+  session: Session,
+  client: Pick<SessionSubjectClient, "getAgentInstance">,
+): Promise<string> {
+  const direct = execution.spec?.agentId ?? "";
+  if (direct !== "") return direct;
+
+  const instanceId = session.spec?.agentInstanceId ?? "";
+  if (instanceId === "") return "";
+
+  const instance = await getOrSkip(
+    () => client.getAgentInstance(instanceId),
+    `agent instance not found: ${instanceId}`,
+  );
+  return instance?.spec?.agentId ?? "";
+}
+
+interface GenerateTitleParams {
+  userMessage: string;
+  agentName: string;
+  agentDescription: string;
+  executionId: string;
+  options: GenerateSessionSubjectOptions;
+}
+
+/**
+ * LLM title with heuristic degrade. Every unavailability class — no direct
+ * credential, model build failure, provider error, empty completion — lands on
+ * the heuristic, matching the cloud activity (its LlmCallService swallows
+ * provider failures into a null completion; heuristicSubject documents the
+ * same "expired API key, rate limit, registry miss" cases).
+ */
+async function generateTitle(params: GenerateTitleParams): Promise<string> {
+  const { userMessage, agentName, agentDescription, executionId, options } = params;
+
+  const model = await getSummarizationModel(options.primaryModel);
+
+  // Direct mode with no credential path degrades up front with one actionable
+  // message (the ClassifyToolApprovals idiom — the provider follows the
+  // economy-model resolution, not the operator's key, so the log names it).
+  if (!options.proxyEndpoint) {
+    const provider = tryInferProvider(model);
+    const missing = provider === null ? null : checkDirectCredentials(provider);
+    if (missing !== null) {
+      log(
+        `title model '${model}' (${provider}) has no credential path — ` +
+        `using heuristic fallback. ${missing}`,
+      );
+      return heuristicSubject(userMessage);
+    }
+  }
+
+  try {
+    const { model: llm } = await buildChatModel({
+      modelName: model,
+      proxyEndpoint: options.proxyEndpoint ?? undefined,
+      stigmerToken: options.stigmerToken ?? undefined,
+      headerScope: { executionId },
+      maxTokens: MAX_COMPLETION_TOKENS,
+      temperature: TEMPERATURE,
+    });
+
+    const result = await llm.invoke([
+      new SystemMessage(SYSTEM_PROMPT),
+      new HumanMessage(buildUserPrompt(userMessage, agentName, agentDescription)),
+    ]);
+
+    const generated = contentToString(result.content).trim();
+    if (generated === "") {
+      log("LLM returned empty content, using heuristic fallback");
+      return heuristicSubject(userMessage);
+    }
+    return cleanSubject(generated);
+  } catch (err) {
+    log(`LLM title generation failed, using heuristic fallback: ${message(err)}`);
+    return heuristicSubject(userMessage);
+  }
+}
+
+/** Kept in lockstep with the cloud activity's buildUserPrompt. */
+export function buildUserPrompt(
+  userMessage: string,
+  agentName: string,
+  agentDescription: string,
+): string {
+  let prompt = `User's first message:\n"${userMessage}"\n\n`;
+  prompt += `Agent: ${agentName}\n`;
+  if (agentDescription !== "") {
+    prompt += `Agent purpose: ${agentDescription}\n`;
+  }
+  prompt += "\nGenerate the title:";
+  return prompt;
+}
+
+/**
+ * Best-effort subject from the first few words of the user message. Used when
+ * the LLM is unavailable. Kept in lockstep with the cloud activity.
+ */
+export function heuristicSubject(userMessage: string): string {
+  const words = userMessage.trim().split(/\s+/);
+  let subject = words.slice(0, 7).join(" ");
+  if (subject.length > MAX_SUBJECT_LENGTH) {
+    subject = subject.slice(0, MAX_SUBJECT_LENGTH - 3) + "...";
+  }
+  return subject;
+}
+
+/**
+ * Strip one layer of wrapping quotes and enforce the length cap. Kept in
+ * lockstep with the cloud activity.
+ */
+export function cleanSubject(raw: string): string {
+  let subject = raw.trim();
+  if (subject.length > 1 && subject.startsWith('"') && subject.endsWith('"')) {
+    subject = subject.slice(1, -1);
+  }
+  if (subject.length > 1 && subject.startsWith("'") && subject.endsWith("'")) {
+    subject = subject.slice(1, -1);
+  }
+  subject = subject.trim();
+  if (subject.length > MAX_SUBJECT_LENGTH) {
+    subject = subject.slice(0, MAX_SUBJECT_LENGTH - 3) + "...";
+  }
+  return subject;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Run a lookup, translating NOT_FOUND into a logged skip (undefined) — the
+ * cloud activity's Optional.isEmpty branches. Anything else propagates as a
+ * genuine activity failure; the workflow's fire-and-forget wrapper logs it
+ * as non-critical.
+ */
+async function getOrSkip<T>(
+  fetch: () => Promise<T>,
+  skipMessage: string,
+): Promise<T | undefined> {
+  try {
+    return await fetch();
+  } catch (err) {
+    if (err instanceof ConnectError && err.code === Code.NotFound) {
+      log(`${skipMessage}, skipping`);
+      return undefined;
+    }
+    throw err;
+  }
+}
+
+/** LangChain message content is a string or an array of typed parts. */
+function contentToString(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part) =>
+        typeof part === "object" && part !== null && "text" in part
+          ? String((part as { text: unknown }).text)
+          : "",
+      )
+      .join("");
+  }
+  return "";
+}
+
+function message(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+function log(msg: string): void {
+  console.log(`[GenerateSessionSubject] ${msg}`);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Temporal Activity Factory
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function createGenerateSessionSubjectActivities(config: Config) {
+  const client = new StigmerClient({
+    endpoint: config.stigmerBackendEndpoint,
+    token: config.stigmerToken,
+    tokenRef: config.stigmerTokenRef,
+    runnerTokenRef: config.stigmerRunnerTokenRef,
+  });
+
+  return {
+    GenerateSessionSubject: async (executionId: string): Promise<void> => {
+      activityStarted();
+      try {
+        log(`started: execution=${executionId}`);
+        await generateSessionSubject(executionId, client, {
+          proxyEndpoint: config.proxyEndpoint,
+          stigmerToken: config.stigmerToken,
+          primaryModel: config.primaryModel,
+        });
+      } finally {
+        activityFinished();
+      }
+    },
+  };
+}

package/src/client/stigmer-client.ts

@@ -524,6 +524,17 @@ export class StigmerClient {
     return this.sessionCommand.update(session);
   }
 
+  /**
+   * Race-safe, field-level subject write. The dedicated updateSubject RPC
+   * exists precisely so concurrent writers (title generation vs a user
+   * rename) cannot lose each other's updates the way full-resource
+   * {@link updateSession} round-trips can — always prefer it for subject
+   * changes.
+   */
+  async updateSessionSubject(sessionId: string, subject: string): Promise<Session> {
+    return this.sessionCommand.updateSubject({ id: sessionId, subject });
+  }
+
   async getAgent(agentId: string): Promise<Agent> {
     return this.agentQuery.get({ value: agentId });
   }

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

@@ -423,7 +423,10 @@ describe("ApprovalGateMiddleware", () => {
       expect(mockedInterrupt).toHaveBeenCalledTimes(1);
     });
 
-    it("KEEPS GATING a gitignored delete", async () => {
+    it("KEEPS GATING a gitignored delete when no CAS routing is configured", async () => {
+      // captureIgnored unset: there is no substrate to capture the before-bytes
+      // into, so the delete stays on the interrupt gate (fail-closed). The CAS
+      // delete-flow cases live in the captureIgnored suite below (issue #303).
       const mw = createApprovalGateMiddleware(makeConfig({
         fileCaptureMode: true,
         isCapturablePath: async () => false,
@@ -624,6 +627,132 @@ describe("ApprovalGateMiddleware", () => {
     });
   });
 
+  describe("capture mode — CAS delete capture (captureDeleteBefore, issue #303)", () => {
+    it("flows a non-secret CAS-owned delete: captures before-bytes, runs, never interrupts", async () => {
+      const handler = vi.fn(passthrough);
+      const captureDeleteBefore = vi.fn(async () => {});
+      const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      try {
+        const mw = createApprovalGateMiddleware(makeConfig({
+          fileCaptureMode: true,
+          isCapturablePath: async () => false, // gitignored / non-git
+          captureIgnored: true,
+          captureDeleteBefore,
+          fingerprintKey: "test-key",
+          executionId: "exec-del",
+        }));
+
+        const result = await mw.wrapToolCall!(
+          makeRequest({ name: "delete", args: { path: "scratch/tmp.txt" } }),
+          handler,
+        );
+
+        expect((result as ToolMessage).content).toBe("tool result");
+        expect(captureDeleteBefore).toHaveBeenCalledWith("scratch/tmp.txt");
+        expect(handler).toHaveBeenCalledTimes(1); // the delete flowed (apply-then-review)
+        expect(mockedInterrupt).not.toHaveBeenCalled();
+
+        // The gateway records the flow with file_capture provenance, like writes.
+        const receipt = logSpy.mock.calls
+          .map((c) => String(c[0] ?? ""))
+          .filter((line) => line.startsWith("[hitl-gateway] receipt "))
+          .map((line) => JSON.parse(line.slice("[hitl-gateway] receipt ".length)) as Record<string, unknown>)[0];
+        expect(receipt.policySource).toBe("file_capture");
+        expect(receipt.category).toBe("delete");
+      } finally {
+        logSpy.mockRestore();
+      }
+    });
+
+    it("captures before-bytes BEFORE the tool runs (the bytes exist only until then)", async () => {
+      const order: string[] = [];
+      const captureDeleteBefore = vi.fn(async () => { order.push("capture"); });
+      const handler = vi.fn((req: ToolCallRequest) => {
+        order.push("delete");
+        return passthrough(req);
+      });
+      const mw = createApprovalGateMiddleware(makeConfig({
+        fileCaptureMode: true,
+        isCapturablePath: async () => false,
+        captureIgnored: true,
+        captureDeleteBefore,
+      }));
+
+      await mw.wrapToolCall!(
+        makeRequest({ name: "delete", args: { path: "scratch/tmp.txt" } }),
+        handler,
+      );
+
+      expect(order).toEqual(["capture", "delete"]);
+    });
+
+    it("keeps a SECRET-LIKE delete on the interrupt gate: approvable, never captured, never hard-blocked", async () => {
+      // A delete's args expose no secret content (unlike a write), so a human
+      // may safely approve it — but its before-bytes must never enter CAS.
+      const handler = vi.fn(passthrough);
+      const captureDeleteBefore = vi.fn(async () => {});
+      const recordBlockedSecret = vi.fn();
+      const mw = createApprovalGateMiddleware(makeConfig({
+        fileCaptureMode: true,
+        isCapturablePath: async () => false,
+        captureIgnored: true,
+        captureDeleteBefore,
+        recordBlockedSecret,
+      }));
+      mockedInterrupt.mockReturnValue({ action: "approve" });
+
+      const result = await mw.wrapToolCall!(
+        makeRequest({ name: "delete", args: { path: ".env" } }),
+        handler,
+      );
+
+      expect(mockedInterrupt).toHaveBeenCalledTimes(1); // gated, not blocked
+      expect(captureDeleteBefore).not.toHaveBeenCalled(); // bytes never staged
+      expect(recordBlockedSecret).not.toHaveBeenCalled(); // not a blocked write
+      expect(handler).toHaveBeenCalledTimes(1); // the human approved it
+      expect((result as ToolMessage).content).toBe("tool result");
+    });
+
+    it("keeps gating a CAS-owned delete when no captureDeleteBefore is configured", async () => {
+      // Fail-closed: a delete whose before-bytes cannot be captured cannot be
+      // reviewed post-hoc, so it must be approved up front.
+      const mw = createApprovalGateMiddleware(makeConfig({
+        fileCaptureMode: true,
+        isCapturablePath: async () => false,
+        captureIgnored: true,
+      }));
+      mockedInterrupt.mockReturnValue({ action: "approve" });
+
+      await mw.wrapToolCall!(
+        makeRequest({ name: "delete", args: { path: "scratch/tmp.txt" } }),
+        passthrough,
+      );
+
+      expect(mockedInterrupt).toHaveBeenCalledTimes(1);
+    });
+
+    it("keeps gating a delete with captureIgnored OFF even when captureDeleteBefore is present", async () => {
+      // An unobserved-backend gate (captureIgnored false) must not flow deletes:
+      // the callback alone is not a substrate.
+      const captureDeleteBefore = vi.fn(async () => {});
+      const mw = createApprovalGateMiddleware(makeConfig({
+        fileCaptureMode: true,
+        isCapturablePath: async () => false,
+        captureIgnored: false,
+        captureDeleteBefore,
+      }));
+      mockedInterrupt.mockReturnValue({ action: "approve" });
+
+      await mw.wrapToolCall!(
+        makeRequest({ name: "delete", args: { path: "scratch/tmp.txt" } }),
+        passthrough,
+      );
+
+      expect(mockedInterrupt).toHaveBeenCalledTimes(1);
+      expect(captureDeleteBefore).not.toHaveBeenCalled();
+    });
+  });
+
   describe("degraded deny-gate (no capture substrate — non-git + no storage)", () => {
     // When deriveCaptureMode returns false (a non-git workspace with no artifact
     // storage), setup builds the gate with fileCaptureMode/captureIgnored OFF, so

package/src/middleware/approval-gate.ts

@@ -88,10 +88,11 @@ export interface ApprovalGateConfig {
    * `write`/`delete` whose target path is capturable (git-tracked — see
    * {@link isCapturablePath}) FLOWS instead of interrupting: the edit is reviewed
    * post-hoc as a captured `FileChangeSet`, not gated before it runs. A gitignored
-   * path is NOT capturable, so it stays gated (the git substrate cannot capture or
-   * revert it) — the exact twin of the Cursor hook's `__stigmer_is_gitignored`
-   * allow-branch. `shell` and MCP tools are never bypassed by this flag. Off (the
-   * default) keeps the classic true-pause gate for every mutation.
+   * path is NOT capturable by the git substrate, so it stays gated unless
+   * {@link captureIgnored} routes it into CAS capture — the exact twin of the
+   * Cursor hook's `__stigmer_is_gitignored` allow-branch. `shell` and MCP tools
+   * are never bypassed by this flag. Off (the default) keeps the classic
+   * true-pause gate for every mutation.
    */
   readonly fileCaptureMode?: boolean;
   /**
@@ -107,12 +108,12 @@ export interface ApprovalGateConfig {
    * instead of the interrupt gate, applying the DD-E secret gate. When off, a
    * gitignored path stays on the interrupt gate exactly as before.
    *
-   * TRUE ONLY FOR THE PARENT GATE. Sub-agents build their own plain filesystem
-   * backends, which the CAS observer does not wrap, so flowing their gitignored
-   * edits would apply unobserved, unreviewable bytes. `buildSubAgentMiddleware`
-   * therefore forces this to false for sub-agent gates — it must NOT be inherited
-   * as true. (Sub-agent git-tracked edits are still captured by the turn-boundary
-   * git diff, which is backend-agnostic.)
+   * True only for gates whose backend a CAS observer wraps: the parent gate
+   * always (setup.ts), and — since DD-19 — sub-agent gates too, because
+   * `compileSubagents` gives every sub-agent a CAS-observing backend wired to
+   * the SAME shared observer and `buildSubAgentMiddleware` then inherits this
+   * config verbatim. A gate over an UNOBSERVED backend must keep this false:
+   * flowing its gitignored edits would apply unobserved, unreviewable bytes.
    */
   readonly captureIgnored?: boolean;
   /**
@@ -122,6 +123,20 @@ export interface ApprovalGateConfig {
    * secret; the CONTENT never leaves the workspace). Absent ⇒ nothing recorded.
    */
   readonly recordBlockedSecret?: (rawPath: string) => void;
+  /**
+   * Capture a file's pre-delete bytes into the CAS observer so a CAS-owned
+   * (gitignored / non-git) DELETE can flow under {@link captureIgnored} and be
+   * reviewed post-hoc exactly like a write (issue #303) — the delete twin of the
+   * backend's `recordBefore` write observation. A delete is the one mutation the
+   * backend cannot observe (deepagents has no backend delete method to wrap), so
+   * the gate captures at authorization time instead: the file's bytes are still
+   * on disk here, and the turn boundary then reads after=null and authors a
+   * `FILE_CHANGE_KIND_DELETE` with the same discard-restores contract.
+   *
+   * Absent ⇒ deletes keep today's interrupt-gate behavior (fail-closed: a delete
+   * we cannot capture cannot be reviewed, so it must be approved up front).
+   */
+  readonly captureDeleteBefore?: (rawPath: string) => Promise<void>;
   /**
    * Unattended approval mode (ExecutionConfig.approval_mode = UNATTENDED):
    * the creating surface — a messaging channel, a guest share — has no
@@ -213,22 +228,39 @@ export function createApprovalGateMiddleware(
             emitExecutionReceipt(config, toolCall, serverSlug, category, "auto_approve", "file_capture");
             return await handler(request);
           }
-          // Gitignored path. Only the PARENT gate (captureIgnored) routes it into
-          // CAS capture; sub-agent gates fall through to the interrupt gate below,
-          // exactly as before (their backends are not CAS-observed).
+          // Gitignored / non-git path: a gate whose backend the shared CAS
+          // observer wraps (captureIgnored — the parent gate, and sub-agent
+          // gates since DD-19) routes it into CAS capture; any other gate falls
+          // through to the interrupt gate below.
           if (config.captureIgnored) {
-            if (isSecretLikePath(path)) {
-              // DD-E fail-closed: a secret-like gitignored edit is NEVER applied
-              // and NEVER captured. Record it so the turn boundary authors a
-              // DIFF_UNREVIEWABLE entry (blocking approval); nothing is written.
-              config.recordBlockedSecret?.(path);
-              return secretBlockToolMessage(toolName, path, toolCall.id);
-            }
             if (category === "write") {
+              if (isSecretLikePath(path)) {
+                // DD-E fail-closed: a secret-like gitignored WRITE is NEVER
+                // applied and NEVER captured — its content must not surface
+                // anywhere, approval prompt included. Record it so the turn
+                // boundary authors a DIFF_UNREVIEWABLE entry (blocking
+                // approval); nothing is written.
+                config.recordBlockedSecret?.(path);
+                return secretBlockToolMessage(toolName, path, toolCall.id);
+              }
               // Non-secret gitignored write/edit: flows (apply-then-review). The
               // CAS observer already holds its before-bytes and the turn boundary
-              // captures it into CAS. (A gitignored delete has no backend capture
-              // path, so it falls through to the interrupt gate.)
+              // captures it into CAS.
+              emitExecutionReceipt(config, toolCall, serverSlug, category, "auto_approve", "file_capture");
+              return await handler(request);
+            }
+            if (category === "delete" && config.captureDeleteBefore && !isSecretLikePath(path)) {
+              // Non-secret CAS-owned delete: capture the before-bytes NOW (the
+              // one moment they still exist on disk — no backend delete method
+              // to observe them), then flow. The turn boundary reads after=null
+              // and authors a reviewable, restorable DELETE entry (issue #303).
+              //
+              // A SECRET-LIKE delete deliberately falls through to the interrupt
+              // gate instead: unlike a write, its args expose no secret content,
+              // so a human may safely approve it — but its before-bytes must
+              // never enter CAS, so it cannot flow. (This also aligns the twins:
+              // the Cursor hook routes secret deletes to its deny-gate.)
+              await config.captureDeleteBefore(path);
               emitExecutionReceipt(config, toolCall, serverSlug, category, "auto_approve", "file_capture");
               return await handler(request);
             }
@@ -244,8 +276,10 @@ export function createApprovalGateMiddleware(
       // continues) exactly like the capture-mode secret block — a secret write is
       // never applied or persisted in ANY mode. Placed AFTER the capture block so
       // capture-mode paths stay byte-identical (a capturable write already flowed;
-      // a captureIgnored gitignored secret is already blocked). Deletes carry no
-      // content and stay on the deny-gate. recordBlockedSecret is a no-op unless a
+      // a captureIgnored gitignored secret write is already blocked). A delete
+      // carries no content, so a secret-like delete needs no hard-block: it stays
+      // on the interrupt gate below, where a human may still approve it (its
+      // bytes are simply never captured). recordBlockedSecret is a no-op unless a
       // turn boundary reads it (the git-no-storage case, where it authors a
       // content-less DIFF_UNREVIEWABLE).
       if (!serverSlug && category === "write") {

package/src/middleware/otel-spans.ts

@@ -2,7 +2,8 @@
  * OpenTelemetry spans and metrics middleware for deep-agent execution.
  *
  * Creates stigmer.llm.call and stigmer.mcp.tool_call spans with
- * attributes matching the Go workflow-runner schema (pkg/otel/spans.go).
+ * attributes matching the span schema inherited from the retired Go
+ * workflow-runner (kept stable so dashboards survived the migration).
  * Also records metrics (histograms + counters) for aggregate dashboards.
  *
  * Graceful no-op when no TracerProvider/MeterProvider is configured.