@stigmer/runner 3.10.0 → 3.11.1-dev.20260812192248

package/src/shared/attachment-naming.ts

@@ -0,0 +1,78 @@
+/**
+ * Naming policy for execution attachments — the single owner of the rule that
+ * resolves duplicate attachment filenames (issue #364).
+ *
+ * Both harnesses materialize attachments into the platform inputs namespace
+ * keyed by filename, so two attachments carrying the same name contend for
+ * one on-disk path. Before this module existed each harness had an accidental
+ * answer: the deep-agent injector failed the whole execution on the collision
+ * and the Cursor resolver silently overwrote the earlier file. The platform
+ * answer is neither — a duplicate is mechanically renamed (`report.pdf`,
+ * `report-2.pdf`, ...) and the rename is disclosed to the agent through the
+ * input-files prompt section, so no execution is ever burned over a
+ * resolvable name and no user file silently vanishes.
+ *
+ * The `stem-2.ext` semantics deliberately mirror the React SDK composer's
+ * client-side rename (sdk/react/src/attachment/attachment-utils.ts,
+ * `uniquifyFilename` — kept in sync by hand, the packages share no
+ * dependency), so a user sees the same rename shape whether the client or the
+ * runner performed it.
+ *
+ * Scope: this module owns NAMES only. What constitutes a collision is the
+ * caller's business — the deep-agent injector keys on full mount paths
+ * (explicit `mountPath` values participate), the Cursor resolver keys on bare
+ * filenames under `inputs/`. Callers that consider a collision a user
+ * contradiction (two attachments explicitly pinning the same mount path)
+ * keep rejecting; only mechanically derived names are renamed.
+ */
+
+/** The outcome of allocating a unique name for one attachment. */
+export interface AllocatedName {
+  /** The final name — unchanged when it was free, `stem-N.ext` otherwise. */
+  readonly name: string;
+  /**
+   * The original requested name, present only when a rename happened — the
+   * disclosure payload the prompt builders render so the agent can still
+   * connect "the two report.pdfs" in the user's message to distinct files.
+   */
+  readonly renamedFrom?: string;
+}
+
+/**
+ * Returns `name` unchanged when it is not in `taken`, otherwise the first
+ * free `stem-2.ext`, `stem-3.ext`, … variant.
+ *
+ * Byte-for-byte twin of the React SDK's `uniquifyFilename`
+ * (sdk/react/src/attachment/attachment-utils.ts) so client-side and
+ * runner-side renames are indistinguishable to the user.
+ */
+export function uniquifyFilename(
+  name: string,
+  taken: ReadonlySet<string>,
+): string {
+  if (!taken.has(name)) return name;
+
+  const dotIndex = name.lastIndexOf(".");
+  // A leading dot (".env") is a hidden-file prefix, not an extension.
+  const stem = dotIndex > 0 ? name.slice(0, dotIndex) : name;
+  const ext = dotIndex > 0 ? name.slice(dotIndex) : "";
+
+  for (let n = 2; ; n++) {
+    const candidate = `${stem}-${n}${ext}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+}
+
+/**
+ * Allocate a unique name against `taken`, claiming the result in the set so
+ * sequential allocations see each other. Returns the disclosure payload
+ * (`renamedFrom`) when the name had to change.
+ */
+export function allocateUniqueName(
+  name: string,
+  taken: Set<string>,
+): AllocatedName {
+  const unique = uniquifyFilename(name, taken);
+  taken.add(unique);
+  return unique === name ? { name: unique } : { name: unique, renamedFrom: name };
+}

package/src/shared/caller-identity.ts

@@ -10,8 +10,10 @@
  *   2. The session creator (`stigmer_user`) from the Session resource's
  *      audit actor — console/CLI sessions have no channel sender, but the
  *      platform knows exactly who created the session.
- *   3. The anonymous sentinel — discovery (no session exists) and sessions
- *      with no readable creator. Consumers must treat anonymous as a
+ *   3. The anonymous sentinel — discovery (no session exists), sessions
+ *      with no readable creator, and sessions whose creator is the
+ *      backend's "system" audit placeholder (not a principal — see
+ *      SYSTEM_CREATOR_SENTINEL). Consumers must treat anonymous as a
  *      first-class caller: answer tools/list, refuse tool calls.
  *
  * Injection is opt-in by construction: the values enter the env map used
@@ -54,6 +56,20 @@ export const STIGMER_USER_KIND = "stigmer_user";
  */
 export const ANONYMOUS_KIND = "anonymous";
 
+/**
+ * Audit-actor id that backends stamp when NO caller identity exists —
+ * the OSS server writes it on every create (no local auth), and the
+ * cloud's AuditActorBuilder falls back to it for caller-less internal
+ * writes. It names "nobody in particular": unrelated sessions from
+ * unrelated people all carry it, so presenting it as a caller identity
+ * would make the one string a grantable value that silently covers ALL
+ * such traffic in an MCP server's binding sheet. A creator matching this
+ * sentinel (and carrying no email) is therefore unresolvable and falls
+ * to anonymous — the deny-by-default the docs guide already promises
+ * for self-hosted backends.
+ */
+export const SYSTEM_CREATOR_SENTINEL = "system";
+
 /** The resolved caller identity. */
 export interface CallerIdentity {
   kind: string;
@@ -79,6 +95,12 @@ export function anonymousCallerIdentity(): CallerIdentity {
  * humans, and the audit actor's `id` field is historically mixed
  * (identity-account id vs email — see the proto's own @internal note).
  * Binding matchers should compare emails case-insensitively.
+ *
+ * A creator with no email whose id is the "system" audit placeholder is
+ * NOT a principal (see SYSTEM_CREATOR_SENTINEL) and resolves to
+ * anonymous. Email-first is deliberate here too: a real account that
+ * merely has "system" somewhere in its id is never demoted, because its
+ * email wins before the sentinel check runs.
  */
 export function resolveCallerIdentity(
   sessionMetadata: Record<string, string> | undefined,
@@ -90,10 +112,23 @@ export function resolveCallerIdentity(
   }
 
   const email = creator?.email?.trim();
+  if (email) {
+    return { kind: STIGMER_USER_KIND, value: email };
+  }
+
   const id = creator?.id?.trim();
-  const value = email || id;
-  if (value) {
-    return { kind: STIGMER_USER_KIND, value };
+  if (id === SYSTEM_CREATOR_SENTINEL) {
+    // Operator tripwire: identity-gated MCP tools will refuse this
+    // session; the fix is real caller attribution, never a "system" grant.
+    console.info(
+      `Session creator is the "${SYSTEM_CREATOR_SENTINEL}" audit placeholder ` +
+      `(no email) — not a resolvable principal; presenting the anonymous ` +
+      `caller identity to MCP servers`,
+    );
+    return anonymousCallerIdentity();
+  }
+  if (id) {
+    return { kind: STIGMER_USER_KIND, value: id };
   }
 
   return anonymousCallerIdentity();

package/src/shared/channel-attachment.ts

@@ -128,6 +128,7 @@ export function synthesizeChannelAttachment(
     slug: CHANNEL_ATTACHMENT_SLUG,
     toolApprovals: [],
     pinnedToolApprovals: [],
+    toolApprovalOverrides: [],
     discoveredCapabilitiesEmpty: false,
   };
 

package/src/shared/checkpointer/__tests__/http-saver.test.ts

@@ -29,9 +29,17 @@ async function serializeForProxy(obj: unknown): Promise<{ type: string; binary:
 describe("HttpCheckpointSaver", () => {
   let saver: HttpCheckpointSaver;
   let fetchSpy: ReturnType<typeof vi.fn>;
+  let recordedDelays: number[];
 
   beforeEach(() => {
-    saver = new HttpCheckpointSaver(PROXY, TOKEN);
+    // delayFn injected so retry-path tests record the backoff schedule
+    // instead of sleeping through it (~7.75 s of real delays otherwise).
+    recordedDelays = [];
+    saver = new HttpCheckpointSaver(PROXY, TOKEN, {
+      delayFn: async (ms) => {
+        recordedDelays.push(ms);
+      },
+    });
     fetchSpy = vi.fn();
     vi.stubGlobal("fetch", fetchSpy);
   });
@@ -163,6 +171,193 @@ describe("HttpCheckpointSaver", () => {
     });
   });
 
+  // The bounded-backoff loop (cloud#188). Classification policy itself is
+  // covered by shared/__tests__/http-retry.test.ts; these cases pin the
+  // loop's behavior at the saver's call sites: transient failures recover,
+  // deterministic failures never retry, budget exhaustion still fails
+  // loudly, and 404 semantics survive unchanged.
+  describe("retry behavior", () => {
+    const ok404 = { status: 404, ok: false, statusText: "Not Found" };
+    const err503 = { status: 503, ok: false, statusText: "Service Unavailable" };
+    const err400 = { status: 400, ok: false, statusText: "Bad Request" };
+    const err401 = { status: 401, ok: false, statusText: "Unauthorized" };
+
+    function makeCheckpoint(): Checkpoint {
+      return {
+        v: 4,
+        id: "cp-retry",
+        ts: new Date().toISOString(),
+        channel_values: {},
+        channel_versions: {},
+        versions_seen: {},
+      };
+    }
+    const md: CheckpointMetadata = { source: "loop", step: 0, parents: {} };
+
+    it("recovers a put from a transient 503", async () => {
+      fetchSpy
+        .mockResolvedValueOnce(err503)
+        .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve({}) });
+
+      const result = await saver.put(makeConfig(), makeCheckpoint(), md, {});
+      expect(result.configurable?.checkpoint_id).toBe("cp-retry");
+      expect(fetchSpy).toHaveBeenCalledTimes(2);
+      expect(recordedDelays).toEqual([250]);
+    });
+
+    it("recovers a put from a network-level rejection (undici TypeError)", async () => {
+      fetchSpy
+        .mockRejectedValueOnce(new TypeError("fetch failed"))
+        .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve({}) });
+
+      await expect(saver.put(makeConfig(), makeCheckpoint(), md, {})).resolves.toBeDefined();
+      expect(fetchSpy).toHaveBeenCalledTimes(2);
+    });
+
+    it("backs off exponentially across consecutive transient failures", async () => {
+      fetchSpy
+        .mockResolvedValueOnce(err503)
+        .mockResolvedValueOnce(err503)
+        .mockResolvedValueOnce(err503)
+        .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve({}) });
+
+      await saver.put(makeConfig(), makeCheckpoint(), md, {});
+      expect(recordedDelays).toEqual([250, 500, 1000]);
+    });
+
+    it("fails loudly when the budget is exhausted on a retryable status", async () => {
+      fetchSpy.mockResolvedValue(err503);
+
+      await expect(saver.put(makeConfig(), makeCheckpoint(), md, {}))
+        .rejects.toThrow("Checkpoint PUT failed: 503");
+      // 1 initial attempt + 5 retries (the default budget).
+      expect(fetchSpy).toHaveBeenCalledTimes(6);
+      expect(recordedDelays).toEqual([250, 500, 1000, 2000, 4000]);
+    });
+
+    it("rethrows the original error when the budget is exhausted on network rejections", async () => {
+      const netErr = new TypeError("fetch failed");
+      fetchSpy.mockRejectedValue(netErr);
+
+      await expect(saver.putWrites(makeConfig(), [["messages", { a: 1 }]], "t1"))
+        .rejects.toBe(netErr);
+      expect(fetchSpy).toHaveBeenCalledTimes(6);
+    });
+
+    it("never retries a deterministic 400", async () => {
+      fetchSpy.mockResolvedValue(err400);
+
+      await expect(saver.put(makeConfig(), makeCheckpoint(), md, {}))
+        .rejects.toThrow("Checkpoint PUT failed: 400");
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+      expect(recordedDelays).toEqual([]);
+    });
+
+    it("never retries a rejected credential (401)", async () => {
+      fetchSpy.mockResolvedValue(err401);
+
+      await expect(saver.getTuple(makeConfig())).rejects.toThrow("Checkpoint GET failed: 401");
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it("never retries a manual abort (AbortError)", async () => {
+      const abortErr = new DOMException("This operation was aborted", "AbortError");
+      fetchSpy.mockRejectedValue(abortErr);
+
+      await expect(saver.getTuple(makeConfig())).rejects.toBe(abortErr);
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it("retries a hung request aborted by the per-request timeout (TimeoutError)", async () => {
+      fetchSpy
+        .mockRejectedValueOnce(
+          new DOMException("The operation was aborted due to timeout", "TimeoutError"),
+        )
+        .mockResolvedValueOnce(ok404);
+
+      await expect(saver.getTuple(makeConfig())).resolves.toBeUndefined();
+      expect(fetchSpy).toHaveBeenCalledTimes(2);
+    });
+
+    it("preserves getTuple's 404 semantics without retrying", async () => {
+      fetchSpy.mockResolvedValue(ok404);
+
+      await expect(saver.getTuple(makeConfig())).resolves.toBeUndefined();
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it("preserves deleteThread's 404 tolerance without retrying", async () => {
+      fetchSpy.mockResolvedValue(ok404);
+
+      await expect(saver.deleteThread("thread-1")).resolves.toBeUndefined();
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it("bounds every request with an abort signal", async () => {
+      fetchSpy.mockResolvedValue(ok404);
+
+      await saver.getTuple(makeConfig());
+      const [, opts] = fetchSpy.mock.calls[0];
+      expect(opts.signal).toBeInstanceOf(AbortSignal);
+    });
+
+    it("surfaces a pending-writes read failure instead of silently degrading", async () => {
+      // The checkpoint GET succeeds; the follow-up writes GET fails on every
+      // attempt. Pre-#188 code mapped this to "no pending writes" and
+      // returned a tuple stripped of resume state.
+      const cp = makeCheckpoint();
+      const cpSer = await serializeForProxy(cp);
+      const mdSer = await serializeForProxy(md);
+      const checkpointDoc = {
+        thread_id: "thread-1",
+        checkpoint_ns: "",
+        checkpoint_id: cp.id,
+        type: cpSer.type,
+        checkpoint: cpSer.binary,
+        metadata_type: mdSer.type,
+        metadata: mdSer.binary,
+      };
+      fetchSpy.mockImplementation((url: string) => {
+        if (url.includes("/writes")) return Promise.resolve(err503);
+        return Promise.resolve({ ok: true, json: () => Promise.resolve(checkpointDoc) });
+      });
+
+      await expect(saver.getTuple(makeConfig())).rejects.toThrow(
+        "Checkpoint writes GET failed: 503",
+      );
+    });
+
+    it("recovers the pending-writes read from a transient failure", async () => {
+      const cp = makeCheckpoint();
+      const cpSer = await serializeForProxy(cp);
+      const mdSer = await serializeForProxy(md);
+      const checkpointDoc = {
+        thread_id: "thread-1",
+        checkpoint_ns: "",
+        checkpoint_id: cp.id,
+        type: cpSer.type,
+        checkpoint: cpSer.binary,
+        metadata_type: mdSer.type,
+        metadata: mdSer.binary,
+      };
+      let writesCalls = 0;
+      fetchSpy.mockImplementation((url: string) => {
+        if (url.includes("/writes")) {
+          writesCalls++;
+          return writesCalls === 1
+            ? Promise.resolve(err503)
+            : Promise.resolve({ ok: true, json: () => Promise.resolve({ writes: [] }) });
+        }
+        return Promise.resolve({ ok: true, json: () => Promise.resolve(checkpointDoc) });
+      });
+
+      const tuple = await saver.getTuple(makeConfig());
+      expect(tuple?.checkpoint.id).toBe(cp.id);
+      expect(tuple?.pendingWrites).toEqual([]);
+      expect(writesCalls).toBe(2);
+    });
+  });
+
   describe("URL construction", () => {
     it("strips trailing slashes from proxy endpoint", () => {
       const s = new HttpCheckpointSaver("https://proxy.test///", "tok");

package/src/shared/checkpointer/http-saver.ts

@@ -13,6 +13,19 @@
  *
  * The Java proxy calls Document.parse(json) which handles $binary
  * natively, and doc.toJson() emits the same format on reads.
+ *
+ * Every request runs through the shared bounded-backoff loop
+ * (http-retry.ts's fetchWithRetry, with this saver's policy: transient
+ * classification + a per-request abort timeout). That loop is the ONLY
+ * retry layer between an agent execution and its checkpoints — the deep
+ * agent activity is deliberately non-retryable at the Temporal level
+ * (maximumAttempts: 1; replaying a whole agent run is not safe), so before
+ * this existed a single dropped request killed the execution
+ * (stigmer/stigmer-cloud#188). Retrying puts is safe by server contract:
+ * CheckpointStore documents putCheckpoint/putWrite as keyed save-or-replace
+ * upserts. Budget exhaustion still fails loudly — checkpoints are not
+ * lossy-tolerable (unlike status updates, see status.ts), and silently
+ * dropping one would corrupt resume state.
  */
 
 import type { RunnableConfig } from "@langchain/core/runnables";
@@ -25,6 +38,8 @@ import {
   type ChannelVersions,
 } from "@langchain/langgraph-checkpoint";
 import type { CheckpointMetadata, PendingWrite } from "@langchain/langgraph-checkpoint";
+import type { RetryOptions } from "../grpc-retry.js";
+import { fetchWithRetry, type FetchRetryPolicy } from "../http-retry.js";
 
 function encodeB64(data: Uint8Array): string {
   if (typeof Buffer !== "undefined") {
@@ -77,17 +92,59 @@ function configOrg(config: RunnableConfig): string | undefined {
   return config.configurable?.org as string | undefined;
 }
 
+/** Retry policy plus the per-request bound; every field is defaulted. */
+export interface HttpCheckpointSaverOptions extends RetryOptions {
+  /**
+   * Milliseconds before an in-flight request is aborted and the attempt is
+   * classified retryable. Without it a hung connection (the realistic
+   * unplanned-pod-kill symptom) stalls forever and the retry never engages.
+   */
+  readonly requestTimeoutMs?: number;
+}
+
+/**
+ * Default transient-retry policy. Wider than status.ts's DEFAULT_PERSIST_RETRY
+ * (3 retries, ~700 ms) on purpose: a dropped status update is lossy-tolerable,
+ * a dropped checkpoint kills the execution, so the budget here is sized to
+ * span a pod-restart reroute (~7.75 s of delays across 5 retries). Worst case
+ * with every attempt hanging — 6 x 30 s + delays, ~3.7 min — stays well inside
+ * the deep-agent activity's 1 h startToCloseTimeout (no heartbeatTimeout).
+ */
+const DEFAULT_RETRY = {
+  baseDelayMs: 250,
+  backoffFactor: 2,
+  maxRetries: 5,
+  requestTimeoutMs: 30_000,
+} as const;
+
 export class HttpCheckpointSaver extends BaseCheckpointSaver {
   private readonly baseUrl: string;
   private readonly headers: Record<string, string>;
+  private readonly retryPolicy: FetchRetryPolicy;
 
-  constructor(proxyEndpoint: string, authToken: string) {
+  constructor(
+    proxyEndpoint: string,
+    authToken: string,
+    options: HttpCheckpointSaverOptions = {},
+  ) {
     super();
     this.baseUrl = `${proxyEndpoint.replace(/\/+$/, "")}/v1/proxy/checkpoints`;
     this.headers = {
       Authorization: `Bearer ${authToken}`,
       "Content-Type": "application/json",
     };
+    this.retryPolicy = {
+      label: "HttpCheckpointSaver",
+      baseDelayMs: options.baseDelayMs ?? DEFAULT_RETRY.baseDelayMs,
+      backoffFactor: options.backoffFactor ?? DEFAULT_RETRY.backoffFactor,
+      maxRetries: options.maxRetries ?? DEFAULT_RETRY.maxRetries,
+      requestTimeoutMs: options.requestTimeoutMs ?? DEFAULT_RETRY.requestTimeoutMs,
+      delayFn: options.delayFn,
+    };
+  }
+
+  private fetchWithRetry(url: string, init?: RequestInit): Promise<Response> {
+    return fetchWithRetry(url, init, this.retryPolicy);
   }
 
   private async serializeTyped(obj: unknown): Promise<[string, BinaryObj]> {
@@ -113,7 +170,7 @@ export class HttpCheckpointSaver extends BaseCheckpointSaver {
       params.set("checkpoint_id", checkpointId);
     }
 
-    const resp = await fetch(`${this.baseUrl}/checkpoint?${params}`, {
+    const resp = await this.fetchWithRetry(`${this.baseUrl}/checkpoint?${params}`, {
       headers: this.headers,
     });
     if (resp.status === 404) return undefined;
@@ -143,7 +200,7 @@ export class HttpCheckpointSaver extends BaseCheckpointSaver {
       params.set("before", beforeId);
     }
 
-    const resp = await fetch(`${this.baseUrl}/checkpoints?${params}`, {
+    const resp = await this.fetchWithRetry(`${this.baseUrl}/checkpoints?${params}`, {
       headers: this.headers,
     });
     if (!resp.ok) {
@@ -183,7 +240,7 @@ export class HttpCheckpointSaver extends BaseCheckpointSaver {
     const orgId = configOrg(config);
     if (orgId) doc.org_id = orgId;
 
-    const resp = await fetch(`${this.baseUrl}/checkpoint`, {
+    const resp = await this.fetchWithRetry(`${this.baseUrl}/checkpoint`, {
       method: "PUT",
       headers: this.headers,
       body: JSON.stringify(doc),
@@ -203,7 +260,7 @@ export class HttpCheckpointSaver extends BaseCheckpointSaver {
 
   async deleteThread(threadId: string): Promise<void> {
     const params = new URLSearchParams({ thread_id: threadId });
-    const resp = await fetch(`${this.baseUrl}/thread?${params}`, {
+    const resp = await this.fetchWithRetry(`${this.baseUrl}/thread?${params}`, {
       method: "DELETE",
       headers: this.headers,
     });
@@ -238,7 +295,7 @@ export class HttpCheckpointSaver extends BaseCheckpointSaver {
       return doc;
     }));
 
-    const resp = await fetch(`${this.baseUrl}/writes`, {
+    const resp = await this.fetchWithRetry(`${this.baseUrl}/writes`, {
       method: "PUT",
       headers: this.headers,
       body: JSON.stringify({ writes: docs }),
@@ -272,7 +329,7 @@ export class HttpCheckpointSaver extends BaseCheckpointSaver {
       };
     }
 
-    const writesResp = await fetch(
+    const writesResp = await this.fetchWithRetry(
       `${this.baseUrl}/writes?${new URLSearchParams({
         thread_id: threadId,
         checkpoint_ns: checkpointNs,
@@ -280,8 +337,14 @@ export class HttpCheckpointSaver extends BaseCheckpointSaver {
       })}`,
       { headers: this.headers },
     );
+    // Fail loudly, never degrade: this used to map ANY non-ok response to "no
+    // pending writes", which silently stripped resume state on a transient
+    // 500 — a checkpoint would load without the writes recorded against it.
+    if (!writesResp.ok) {
+      throw new Error(`Checkpoint writes GET failed: ${writesResp.status} ${writesResp.statusText}`);
+    }
     const pendingWrites = await this.parseWrites(
-      writesResp.ok ? (await writesResp.json()) as Record<string, any> : {},
+      (await writesResp.json()) as Record<string, any>,
     );
 
     return {

package/src/shared/conversation-attachment.ts

@@ -105,6 +105,7 @@ export function synthesizeConversationAttachment(
     slug: CONVERSATION_ATTACHMENT_SLUG,
     toolApprovals: [],
     pinnedToolApprovals: [],
+    toolApprovalOverrides: [],
     discoveredCapabilitiesEmpty: false,
     connectionType: "http",
     url: options.bridgeEndpoint.replace(/\/+$/, "") + CONVERSATION_ROUTE,

package/src/shared/conversation-catchup.ts

@@ -1,8 +1,15 @@
 /**
  * Conversation catchup (cloud channel-conversations DD-006): what happened on
  * a live channel conversation that the agent has not seen — customer messages
- * handled by a human teammate, the teammate's replies, platform notices the
- * customer received, notes, and the agent's own earlier escalations.
+ * handled by a human teammate, the teammate's replies, platform notices,
+ * notes, and the agent's own earlier escalations. Since cloud#347 a line
+ * whose send is known-undelivered carries a `(not delivered)` speaker
+ * annotation and an in-flight one carries `(sending)` — the digest no longer
+ * implies every public-lane line reached the customer. Since cloud#352 the
+ * digest also closes the feedback loop on send OUTCOMES: the agent's own
+ * dead-lettered sends surface as `You (not delivered):` lines, and a send
+ * that failed only after an earlier digest already conveyed it surfaces as a
+ * `System:` delivery-failure notice at the moment the failure became known.
  *
  * The cloud composes the CONTENT (bare `Customer:` / `Teammate:` / `System:` /
  * `You escalated:` / `Note:` lines, oldest first) on the execution spec's
@@ -29,16 +36,42 @@ import type { ConversationCatchup } from "@stigmer/protos/ai/stigmer/agentic/age
  * drift between them. Deliberately takeover-neutral: a digest can exist with
  * no human handoff at all (a failed turn's re-composed window), so the
  * preamble asserts only what is always true (the A15/A20 honesty bar).
+ *
+ * The send-status annotations (cloud#347) get an explicit exception from the
+ * don't-re-answer contract: a `(not delivered)` teammate reply is words the
+ * customer never got, so treating it as settled history would silently
+ * abandon whatever it was meant to convey. The preamble defines the
+ * annotations — the DD-013 split puts model-facing meaning here, while the
+ * cloud composer owns which lines earn them.
+ *
+ * The send-outcome lines (cloud#352, cloud triage DD-009) extend the same
+ * exception to the agent's OWN sends: `You (not delivered):` lines and
+ * `System:` delivery-failure notices mean the customer never got those
+ * words. The behavioral contract is owner-ruled (DD-009 Q-4): treat the
+ * failure as unfinished conversation business — weigh what still needs
+ * saying and re-say it naturally in the next turn — but never resend the
+ * failed text verbatim: a multi-chunk send can partially land, and a
+ * word-for-word repeat risks the customer reading the same message twice.
  */
 const CONVERSATION_CATCHUP_PREAMBLE =
   "Below is activity from this conversation that you have not seen — " +
   "oldest first. It may include customer messages that were handled by a " +
-  "human teammate, the teammate's own replies, notices the customer " +
-  "received, internal notes, and escalations you raised earlier. Treat it " +
+  "human teammate, the teammate's own replies, notices sent to the " +
+  "customer, internal notes, and escalations you raised earlier. Treat it " +
   "as conversation history you already know: do not answer or re-answer " +
   "these messages, do not repeat or summarize them back, and do not " +
-  "mention any handoff unless asked. Continue from the customer's newest " +
-  "message.";
+  "mention any handoff unless asked. One exception: lines marked " +
+  "(not delivered) never reached the customer, and lines marked (sending) " +
+  "were still on their way when this summary was built — the customer may " +
+  "not have seen those words, so weigh that when deciding what still needs " +
+  "saying. That includes your own words: a line marked " +
+  "You (not delivered), or a System line reporting that a message was not " +
+  "delivered, means the customer never received it. Treat such a failure " +
+  "as unfinished business — if what it said still matters, work it " +
+  "naturally into your reply in your own words, but never resend the " +
+  "failed text word-for-word (part of it may have reached the customer, " +
+  "and an exact repeat reads as a duplicate). " +
+  "Continue from the customer's newest message.";
 
 /**
  * Read the catchup digest from an execution spec's `conversation_catchup`.