@parall/parel-channel 1.41.0 → 1.42.0

package/src/delivery.ts

@@ -1,44 +1,48 @@
 import type { ChannelDelivery, ConnectorContext, ConnectorEffect } from '@parel/plugin-sdk';
-import { parallApiUrl, parallOrgId, requireAgk } from './connect.js';
 import { childRefKnown } from './fork.js';
 import {
+  completeFencedEnvelopes,
+  createSuppressedTextStep,
   ensureChildSession,
   ensureSession,
   invalidateChildSession,
   invalidateSession,
   patchSession,
-  REQUEST_TIMEOUT_MS,
   TURN_ENVELOPE_KEY,
 } from './session.js';
 
 /**
- * Post the agent's reply back to the Parall chat. The chat id rides the
- * replyRoute.data set in inbound.ts.
+ * Turn-end delivery — which, under the platform reply contract, delivers
+ * NOTHING to the chat.
  *
- * Contract (confirmed against parel #104): provider_http reply routes are
- * auto-delivered at turn end via this hook; `payload` is the plain reply text
- * string and `replyRoute` is the one captured from the originating envelope.
+ * The runtime-standard output contract (agent-dm-loop-prevention.md Layer 0,
+ * parel-reply-contract-alignment.md): plain turn output is never projected as
+ * a chat message — the agent replies explicitly via `parall messages send`
+ * from its sandbox, and that send carries the dispatch_source ledger binding.
+ * This hook records the turn-end text as a suppressed audit step on the
+ * session (the same posture the claude-agent / openclaw bridges enforce),
+ * runs a fence-checked ledger close, and a redundant session idle; nothing
+ * else.
  *
- * The reply POST is awaited (not returned as a host fetch effect) so the
- * session link resolution and failure handling stay in one place; a
- * retryable failure falls back to the host effect (at-least-once, idempotent
- * by delivery id + message idempotency_key). The turn's PRIMARY done signal
- * lives in onAgentEvent (turn_completed); the idle here is a deliberate
- * redundant close for bindings without `observe: [turn]` — see the inline
- * comment at the bottom.
+ * parel still auto-invokes deliver() at turn end for provider_http reply
+ * routes (C4) — ignoring the payload here is the connector's half of the
+ * contract; no parel-side change is needed.
  *
- * External IM turns (channel_message dispatches) route here too but deliver
- * NOTHING: their replyRoute carries a conversationId and no chatId, and the
- * agent replies through the provider clip itself — this hook only runs the
- * same redundant session idle for them.
+ * A fork-owned turn (replyRoute carries childRef) records its audit step on
+ * the CHILD's ase_ and idles IT — its session panel owns the turn, not
+ * main's. A stale childRef (fork purged by New Session / given up on) drops
+ * the text entirely: blind-recreating a fork ase_ under the new conversation
+ * line would resurrect pre-reset state.
+ *
+ * External IM turns (channel_message dispatches) route here too with a
+ * conversationId and no chatId: their reply goes out through the provider
+ * clip, agent-invoked, and their turn-end text was already deliberately
+ * undelivered — only the ledger close + redundant idle run for them.
  */
 export async function buildParallDelivery(
   delivery: ChannelDelivery,
   ctx: ConnectorContext,
 ): Promise<ConnectorEffect[]> {
-  const apiUrl = parallApiUrl(ctx);
-  const agk = requireAgk(ctx);
-  const orgId = parallOrgId(ctx);
   const route = (delivery.replyRoute?.data ?? {}) as {
     chatId?: string;
     messageId?: string;
@@ -47,108 +51,74 @@ export async function buildParallDelivery(
     conversationId?: string;
     childRef?: string;
   };
-  const chatId = route.chatId;
-  if (!chatId) {
-    // No delivery target: external IM turns (channel_message — the reply
-    // already went out through the provider clip, agent-invoked) and typed
-    // dispatch turns (task/schedule/trigger/wiki — the agent acts via its
-    // sandbox CLI). The turn-end text is deliberately NOT delivered anywhere
-    // (same contract as agent-core: plain output is not the reply). Only run
-    // the redundant idle so a binding without `observe: [turn]` still closes
-    // the session.
-    if (route.envelopeId) {
-      const sessionId = await ensureSession(ctx, { timeoutMs: 3_000 });
-      if (sessionId) {
-        await idleUnlessSuperseded(ctx, route.envelopeId, sessionId);
-      }
-    }
-    return [];
-  }
-
-  const payload = delivery.payload as { text?: string } | string | undefined;
-  const text = typeof payload === 'string' ? payload : (payload?.text ?? '');
-  if (!text) return [];
 
-  // Short timeout: this sits in front of the user-visible reply POST. Cache
-  // hit (every dispatch after the agent's first) is a store read; on a slow
-  // miss we degrade to a reply without the session link rather than delay it.
-  // A fork-owned envelope (replyRoute carries childRef) links to the CHILD's
-  // ase_ — its session panel owns this turn, not main's. Same short timeout
-  // as the main path: this sits in front of the user-visible reply POST, so
-  // a slow resolve degrades to a reply without the session link, never a
-  // 10s-delayed message.
+  // A fork-owned envelope whose bookkeeping is gone is a late/stale delivery
+  // (post-reset or post-give-up) — drop it entirely, audit step included.
   const childLive = route.childRef ? await childRefKnown(ctx, route.childRef) : false;
   if (route.childRef && !childLive) {
-    // Terminal stale-child delivery: the fork was purged (New Session) or
-    // given up on (black hole → the opening already re-planned onto main).
-    // Posting would land pre-reset output in the fresh conversation line, or
-    // duplicate a reply main already produced — drop it entirely (no POST,
-    // no retry effect).
-    console.warn('[parel-channel] dropping reply from stale fork', route.childRef);
+    console.warn('[parel-channel] dropping turn-end text from stale fork', route.childRef);
     return [];
   }
-  const sessionId = route.childRef
-    ? await ensureChildSession(ctx, route.childRef, { timeoutMs: 3_000 })
-    : await ensureSession(ctx, { timeoutMs: 3_000 });
 
-  const request = {
-    url: `${apiUrl}/api/v1/orgs/${orgId}/chats/${chatId}/messages`,
-    method: 'POST',
-    headers: {
-      Authorization: `Bearer ${agk}`,
-      'Content-Type': 'application/json',
-    },
-    // message_type must be explicit: the server persists it verbatim, and
-    // a blank type skips text normalization (prll:// refs, mentions) and
-    // renders as an unknown-type fallback on clients. agent_session_id links
-    // the reply bubble to its session panel (server validates ownership).
-    // idempotency_key dedupes the ambiguous-failure case where the direct
-    // POST committed but its response was lost and the host retry re-sends —
-    // same body on both paths, so the server collapses them to one message.
-    body: JSON.stringify({
-      message_type: 'text',
-      content: { text },
-      idempotency_key: `parel-reply:${delivery.id}`,
-      // A reply to a thread message stays in that thread.
-      ...(route.threadRootId ? { thread_root_id: route.threadRootId } : {}),
-      ...(sessionId ? { agent_session_id: sessionId } : {}),
-    }),
-  };
-
-  try {
-    const res = await fetch(request.url, {
-      method: request.method,
-      headers: request.headers,
-      body: request.body,
-      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-    });
-    if (!res.ok) {
-      // 4xx (bar 429) is permanent — retrying an unprocessable reply burns
-      // requests forever. Drop it (logged); turn_completed still closes the
-      // turn's indicator.
-      const permanent = res.status >= 400 && res.status < 500 && res.status !== 429;
-      if (!permanent) throw new Error(`reply post failed (${res.status})`);
-      console.error(`[parel-channel] reply rejected (${res.status}) — dropping`);
+  if (route.chatId) {
+    const payload = delivery.payload as { text?: string } | string | undefined;
+    const text = typeof payload === 'string' ? payload : (payload?.text ?? '');
+    if (text) {
+      // Audit-only: the session panel shows what the model produced, the
+      // chat never does. Short timeout — this hook sits at turn end, nothing
+      // user-visible waits on it. Fork turns land the step on the child ase_.
+      const sessionId = route.childRef
+        ? await ensureChildSession(ctx, route.childRef, { timeoutMs: 3_000 })
+        : await ensureSession(ctx, { timeoutMs: 3_000 });
+      if (sessionId) {
+        const result = await createSuppressedTextStep(ctx, sessionId, {
+          subject: route.chatId,
+          deliveryId: delivery.id,
+          text,
+        });
+        if (result === 'stale') {
+          if (route.childRef) await invalidateChildSession(ctx, route.childRef);
+          else await invalidateSession(ctx);
+        }
+      }
     }
-  } catch (err) {
-    console.error('[parel-channel] direct reply failed; falling back to host retry', err);
-    return [{ type: 'fetch', request, idempotencyKey: `reply:${delivery.id}` }];
   }
 
-  // Redundant done signal, kept deliberately: turn_completed (onAgentEvent)
-  // is the primary close for every turn — including no-reply turns this hook
-  // never sees — but a binding deployed without `observe: [turn]` that still
-  // resolves this connector (npm ^1 fallback path; the artifact path freezes
-  // connector+config atomically) would otherwise never idle. Both signals
-  // run the same turnEnvelope staleness guard and idle is idempotent, so the
-  // overlap is harmless. Child turns skip the guard entirely — the marker is
-  // main's; a child's own turn ending always idles the child ase_.
-  if (sessionId) {
-    if (route.childRef) {
-      const result = await patchSession(ctx, sessionId, { status: 'idle' });
-      if (result === 'stale') await invalidateChildSession(ctx, route.childRef);
-    } else {
-      await idleUnlessSuperseded(ctx, route.envelopeId, sessionId);
+  // Redundant turn-end ledger close, fence-checked — the deliver-side twin of
+  // onAgentEvent's complete. Exists for bindings WITHOUT `observe: [turn]`
+  // (the npm ^1 fallback path): there turn events never arrive and, with
+  // ack-on-emit gone, this hook is the only terminal ledger path — without it
+  // a delivered turn's row would stay live and re-emit on every TTL sweep.
+  // Under the normal artifact path both hooks run; the fence makes the
+  // overlap free (whichever completes first consumes it, the other skips).
+  // Fork-handled envelopes never wrote a fence, so this is a no-op for them
+  // (their ack machinery owns the ledger there).
+  // Known bound of this fallback: the replyRoute snapshot carries ONE
+  // envelope id, so a folded turn's OTHER sources heal only via the TTL
+  // re-emit here. Reaching that state needs a binding with injectInFlight
+  // ON and observe OFF — the platform template always sets both together,
+  // so it exists only on a hand-crafted binding.
+  if (route.envelopeId) {
+    await completeFencedEnvelopes(ctx, [route.envelopeId]);
+  }
+
+  const subject = route.chatId ?? route.conversationId;
+  if (subject) {
+    // Redundant done signal, kept deliberately: turn_completed (onAgentEvent)
+    // is the primary close for every turn — including no-reply turns — but a
+    // binding deployed without `observe: [turn]` would otherwise never idle.
+    // Child turns skip the marker guard entirely — the marker is main's; a
+    // child's own turn ending always idles the child ase_.
+    const sessionId = route.childRef
+      ? await ensureChildSession(ctx, route.childRef, { timeoutMs: 3_000 })
+      : await ensureSession(ctx, { timeoutMs: 3_000 });
+    if (sessionId) {
+      if (route.childRef) {
+        const result = await patchSession(ctx, sessionId, { status: 'idle' });
+        if (result === 'stale') await invalidateChildSession(ctx, route.childRef);
+      } else {
+        await idleUnlessSuperseded(ctx, route.envelopeId, sessionId);
+      }
     }
   }
   return [];

package/src/fork.ts

@@ -411,11 +411,14 @@ export async function handleChildSpawnFailed(
  * equivalent; the platform already excludes in-flight output from the seed,
  * this line keeps the child from "finishing" main's visible work).
  *
- * The opening turn has no envelope (it starts from the spawn input), so its
- * turn-end text is NOT auto-delivered anywhere (parel §18.3: outward replies
- * from a child are the agent's own job) — the prefix therefore spells out
- * the CLI reply command for THIS message; follow-ups arrive as deliverTo
- * envelopes whose replies auto-deliver like any chat message.
+ * Replies are CLI-only on EVERY fork turn (the platform reply contract —
+ * nothing auto-delivers, parel-reply-contract-alignment.md). The opening
+ * turn additionally has no envelope (it starts from the spawn input), so it
+ * gets no per-turn invocation context either — the prefix therefore spells
+ * out the full CLI reply command with the explicit chat target; follow-ups
+ * arrive as deliverTo envelopes whose invocation context presets
+ * PRLL_CHAT_ID, so the system prompt's bare `parall messages send` teaching
+ * covers them.
  */
 export function buildForkScopePrefix(subject: string, threadRootId?: string): string {
   // Quoted-heredoc input form (mirrors agent-core's send hint): plain
@@ -427,6 +430,6 @@ export function buildForkScopePrefix(subject: string, threadRootId?: string): st
   return (
     `[Fork scope: you are a parallel branch of your main session, handling ONE conversation (${subject}) only. ` +
     `Act only on this conversation's request. Do not continue, complete, or produce output for other work visible in your inherited history — the main session owns it.]\n` +
-    `<system-reminder>Reply to THIS message with your sandbox CLI: \`${send}\` … \`EOF\` — the quoted heredoc keeps \`$\`, backticks and apostrophes literal. For this opening message your plain text output is NOT auto-delivered; later messages in this conversation deliver replies automatically.</system-reminder>\n\n`
+    `<system-reminder>Reply to THIS message with your sandbox CLI: \`${send}\` … \`EOF\` — the quoted heredoc keeps \`$\`, backticks and apostrophes literal. Your plain text output is NOT delivered anywhere — on this and every later message in this conversation, reply via \`parall messages send\`.</system-reminder>\n\n`
   );
 }

package/src/inbound-channel.ts

@@ -7,9 +7,12 @@ import {
   ensureSession,
   invalidateSession,
   markDispatchReceived,
+  nextEnvelopeId,
   patchSession,
+  readActiveEmit,
   REQUEST_TIMEOUT_MS,
   TURN_ENVELOPE_KEY,
+  writeActiveEmit,
 } from './session.js';
 
 /**
@@ -42,7 +45,6 @@ export const PROVIDER_LOOKUP_TIMEOUT_MS = 3_000;
  */
 export async function effectsForChannelDispatch(
   sourceId: string,
-  dispatchId: string,
   ctx: ConnectorContext,
 ): Promise<ConnectorEffect[]> {
   const apiUrl = parallApiUrl(ctx);
@@ -109,10 +111,12 @@ export async function effectsForChannelDispatch(
   const externalMessageId = msg?.external_message_id ? String(msg.external_message_id) : undefined;
 
   // Progress reporting — identical ordering contract to the message path
-  // (see the comments there): received settles before the ack effect is
-  // returned; the turnEnvelope marker goes down before any session write.
+  // (see the comments there): received settles before this function returns;
+  // the turnEnvelope marker goes down before any session write; the row
+  // stays 'received' until the turn event's complete-sources.
   const receivedSettled = markDispatchReceived(ctx, 'channel_message', sourceId);
-  const envelopeId = dispatchId || `channel_message:${sourceId}`;
+  const priorEmit = await readActiveEmit(ctx, 'channel_message', sourceId);
+  const envelopeId = nextEnvelopeId('channel_message', sourceId, priorEmit);
   let sessionId = await ensureSession(ctx);
   if (sessionId) {
     await ctx.store?.set(TURN_ENVELOPE_KEY, envelopeId).catch(() => {});
@@ -148,6 +152,7 @@ export async function effectsForChannelDispatch(
     void recordConversationSession(ctx, conversationId, sessionId).catch(() => {});
   }
   await receivedSettled;
+  await writeActiveEmit(ctx, 'channel_message', sourceId, envelopeId);
 
   return [
     {
@@ -190,10 +195,13 @@ export async function effectsForChannelDispatch(
         },
         // No invocation context: PRLL_CHAT_ID must not point CLI defaults at
         // a chat that doesn't exist, and the reply targets (external ids)
-        // already ride the prompt verbatim.
+        // already ride the prompt verbatim. (So no PRLL_DISPATCH_SOURCE_*
+        // either — the external reply goes out through the provider clip,
+        // and this row's ledger close is the turn event's complete-sources.)
       },
     },
-    ackEffect(ctx, 'channel_message', sourceId),
+    // No ack effect — see the message path (inbound.ts): the row stays
+    // received until complete-sources closes it.
   ];
 }
 

package/src/inbound.ts

@@ -34,22 +34,27 @@ import {
 import {
   ackByIdEffect,
   ackEffect,
+  completeFencedEnvelopes,
   conversationKey,
   createErrorStep,
   fetchMainSessionFresh,
   createInputStep,
   createTraceStep,
   createTypedInputStep,
+  EMIT_TTL_MS,
   ensureChildSession,
   ensureSession,
   invalidateChildSession,
   invalidateSession,
   markDispatchReceived,
+  nextEnvelopeId,
   patchSession,
+  readActiveEmit,
   reportingEnabled,
   REQUEST_TIMEOUT_MS,
   SESSION_CACHE_KEY,
   TURN_ENVELOPE_KEY,
+  writeActiveEmit,
 } from './session.js';
 import { isTypedEventType, planTypedDispatch } from './typed-dispatch.js';
 
@@ -58,10 +63,20 @@ import { isTypedEventType, planTypedDispatch } from './typed-dispatch.js';
  *
  * The Parall gateway pushes `dispatch.new` signals on the agent's WS; the
  * dispatch is a pointer (source_type/source_id), not the payload. For each
- * message dispatch we pull the source message text, emit it to the agent as a
- * ChannelEnvelope, and ack the dispatch by source so it isn't redelivered.
- * On (re)connect, onOpen sweeps `GET /dispatch` so dispatches that arrived
- * while the socket was down are not lost — the WS push has no replay.
+ * message dispatch we pull the source message text, mark it received, and
+ * emit it to the agent as a ChannelEnvelope. MAIN-path rows then stay
+ * `received` for the whole turn — their terminal resolution is the CLI
+ * reply's dispatch_source (effect) or the turn event's complete-sources
+ * (broad-cover / no_action), the ledger lifecycle the chat activity
+ * indicator rides on (parel-reply-contract-alignment.md; the old ack-on-emit
+ * killed the indicator at turn start). Redelivery protection is the
+ * per-source attempt fence in the durable store: on (re)connect, onOpen
+ * sweeps `GET /dispatch` (the WS push has no replay), skips rows whose fence
+ * is younger than EMIT_TTL_MS, and re-emits stale ones under a fresh
+ * attempt-suffixed envelope id. FORK paths (deliverTo/spawn) keep their own
+ * ack machinery — the pending ack doubles as spawn-failure recovery there —
+ * so fork-handled rows still resolve as legacy_ack (indicator parity for
+ * forked turns is a design follow-up, parel-reply-contract-alignment.md §6).
  *
  * Contract (confirmed against parel #102–#107, routing switched with #127):
  * raw WS frames are handed to onMessage verbatim; the binding created by the
@@ -317,6 +332,30 @@ async function catchUpParallInner(ctx: ConnectorContext): Promise<ConnectorEffec
   return effects;
 }
 
+/**
+ * Turn-in-flight guard for redelivery (catch-up sweep AND repeated
+ * dispatch.new pushes). Main-path rows stay live (not acked) for the whole
+ * turn now, and GET /dispatch lists pending AND received rows — so redelivery
+ * re-sees every in-flight source. Skip any row whose attempt fence is younger
+ * than EMIT_TTL_MS, REGARDLESS of row status: a transiently-failed
+ * /dispatch/received leaves the row `pending` while the emit succeeded (fence
+ * written), and re-emitting it inside the TTL would duplicate the in-flight
+ * turn — complete-sources resolves pending rows just as well, so the fence
+ * alone is the truth. Past the TTL (crashed emit, lost turn events) fall
+ * through and re-emit with a fresh attempt-suffixed envelope id. Brand-new
+ * sources have no fence and never skip; fork-handled rows never write a
+ * fence (their ack machinery owns redelivery there).
+ * Design: parel-reply-contract-alignment.md §5.3.
+ */
+async function shouldSkipLiveRow(
+  ctx: ConnectorContext,
+  sourceType: string,
+  sourceId: string,
+): Promise<boolean> {
+  const active = await readActiveEmit(ctx, sourceType, sourceId);
+  return active !== null && ctx.now() - active.at < EMIT_TTL_MS;
+}
+
 async function effectsForDispatch(
   data: DispatchData,
   ctx: ConnectorContext,
@@ -328,7 +367,8 @@ async function effectsForDispatch(
   if (sourceType === 'channel_message' && sourceId) {
     // External IM message (chat_id is NULL by design — the conversation
     // lives on the provider, not in a Parall chat).
-    return effectsForChannelDispatch(sourceId, dispatchId, ctx);
+    if (await shouldSkipLiveRow(ctx, sourceType, sourceId)) return [];
+    return effectsForChannelDispatch(sourceId, ctx);
   }
   const eventType = String(data.event_type ?? '');
   if (sourceId && isTypedEventType(eventType)) {
@@ -341,10 +381,13 @@ async function effectsForDispatch(
       return [];
     }
     // Conversational-only deployments (no sandbox → no `parall` CLI) cannot
-    // act on CLI-only typed work — emitting AND acking it would silently
-    // consume real work. Keep it pending (same posture as unknown types);
-    // approval_decided is exempt (it lives in a chat, replies auto-deliver).
-    if (!sandboxEnabled(ctx) && eventType !== 'approval_decided') {
+    // act on typed work AT ALL under the CLI-only reply contract — nothing
+    // auto-delivers anymore, approval_decided included — so emitting AND
+    // acking would silently consume real work. Keep it pending (same
+    // posture as unknown types). Defensive-only: the server's mandatory
+    // sandbox gate (422 PAREL_SANDBOX_REQUIRED) means no such managed
+    // agent can be provisioned.
+    if (!sandboxEnabled(ctx)) {
       return [];
     }
     return effectsForTypedDispatch(data, ctx);
@@ -359,6 +402,7 @@ async function effectsForDispatch(
     // A message dispatch with no chat can never be routed or replied to.
     return [ackEffect(ctx, sourceType, sourceId)];
   }
+  if (await shouldSkipLiveRow(ctx, sourceType, sourceId)) return [];
 
   const apiUrl = parallApiUrl(ctx);
   const agk = requireAgk(ctx);
@@ -426,7 +470,11 @@ async function effectsForDispatch(
     text,
     attachments,
   });
-  const envelopeId = dispatchId || `${sourceType}:${sourceId}`;
+  // Deterministic source-derived envelope id (+ attempt suffix on re-emits):
+  // complete-sources strips the suffix back to the source, and every re-emit
+  // is globally unique so parel's dedupe (either way) can't strand a retry.
+  const priorEmit = await readActiveEmit(ctx, sourceType, sourceId);
+  const envelopeId = nextEnvelopeId(sourceType, sourceId, priorEmit);
   // Input-step summary must never be empty (attachment-only messages).
   const stepText = text || `[${attachments.length} attachment(s)]`;
   // Thread-aware conversation identity: F2 grouping / F3 injection / fork
@@ -443,9 +491,16 @@ async function effectsForDispatch(
   // Per-turn invocation context: parel snapshots this at turn start and
   // consume-gated plugins receive it — sandbox-e2b flattens it into per-exec
   // env, so `parall` CLI calls inside the sandbox land on the right chat.
+  // The PRLL_DISPATCH_SOURCE_* pair is the CLI's by-source ledger binding: a
+  // send back into the exact trigger (chat, thread) carries dispatch_source
+  // so the server resolves this WorkItem in the reply's own transaction.
+  // (Fork turns get it too — their rows are legacy-acked so the resolve is a
+  // no-op today, and it wires up for free when fork ledger parity lands.)
   const invocationContext: Record<string, string> = {
     PRLL_CHAT_ID: chatId,
     PRLL_TRIGGER_MESSAGE_ID: sourceId,
+    PRLL_DISPATCH_SOURCE_TYPE: sourceType,
+    PRLL_DISPATCH_SOURCE_ID: sourceId,
     ...(threadRootId ? { PRLL_THREAD_ROOT_ID: threadRootId } : {}),
   };
 
@@ -617,15 +672,16 @@ async function effectsForDispatch(
     // fall through: black-holed spawn rides main below.
   }
 
-  // Main path. Progress reporting (best-effort,
-  // parall-runtime-indicator-plan.md §3): received lights the pending ring,
-  // the active+trigger patch arms the done signal, the input step flips the
-  // ring to processing. received MUST settle before this function returns —
-  // the ack effect below moves the dispatch row out of 'pending', and
-  // MarkReceived only transitions pending rows. It is deliberately NOT gated
-  // on the session resolving: it only touches the dispatch row, and a
-  // transient session failure must not also cost the pending ring (a later
-  // successful turn's idle clears agent-level pendings).
+  // Main path. Progress reporting (best-effort): received flips the row out
+  // of 'pending' and lights the indicator (dispatch.received → active); the
+  // row then STAYS 'received' for the whole turn — resolution comes from the
+  // CLI reply's dispatch_source or the turn event's complete-sources, never
+  // from an ack here (the old ack-on-emit is what killed the indicator
+  // early; parel-reply-contract-alignment.md §1.1). received still settles
+  // before this function returns so a same-batch reply can never race the
+  // pending→received transition. It is deliberately NOT gated on the
+  // session resolving: a transient session failure must not also cost the
+  // indicator.
   const receivedSettled = markDispatchReceived(ctx, sourceType, sourceId);
   let sessionId = await ensureSession(ctx);
   if (sessionId) {
@@ -664,8 +720,21 @@ async function effectsForDispatch(
     }
   }
   await receivedSettled;
+  // Arm the attempt fence BEFORE the emit effect is returned: turn events
+  // complete a source only while `active:{source}` matches their envelope id
+  // exactly, and the redelivery-skip window starts at this timestamp. Only
+  // the main path writes it — fork paths keep their own ack machinery.
+  // Deliberate ordering tradeoff: a crash between this write and the host
+  // executing the emit leaves an armed fence for an un-emitted source, so
+  // the reconnect sweep hides it until the TTL re-emit (≤30min delay). The
+  // reverse order (fence after emit) would instead double-emit on a crash —
+  // a duplicate agent turn. Delay heals; duplicates don't.
+  await writeActiveEmit(ctx, sourceType, sourceId, envelopeId);
 
-  return [{ type: 'emitEvent', event: envelope }, ackEffect(ctx, sourceType, sourceId)];
+  // No ack effect: the row stays 'received' until the reply (dispatch
+  // _source) or the turn event (complete-sources) resolves it — the
+  // indicator's whole lifecycle rides on that.
+  return [{ type: 'emitEvent', event: envelope }];
 }
 
 /**
@@ -744,9 +813,11 @@ async function effectsForTypedDispatch(
         replyRoute: {
           kind: 'provider_http',
           connectionId: ctx.connectionId,
-          // approval_decided replies deliver to its chat; every other typed
-          // event has no delivery target (deliver() only runs the redundant
-          // idle off envelopeId) — the agent acts via its sandbox CLI.
+          // Replies are CLI-only for every typed event (nothing
+          // auto-delivers). chatId — only approval_decided has one — merely
+          // routes deliver()'s suppressed turn-end audit step to the chat;
+          // chat-less routes carry just the envelopeId for the redundant
+          // ledger close + idle.
           data: plan.chatId
             ? { chatId: plan.chatId, messageId: sourceId, envelopeId }
             : { envelopeId },
@@ -911,6 +982,21 @@ async function handleParallAgentEventInner(
     await noteMainTurnEvent(ctx, withChild).catch(() => {});
     if (!chatId) return [];
     if (event.type === 'turn_completed' || event.type === 'turn_failed') {
+      // Ledger close FIRST, fenced per source — deliberately NOT behind the
+      // agent-global marker guard below: that guard protects the shared
+      // session's idle (last-emit-wins), while the ledger rows are
+      // per-source facts that must close whenever THEIR envelope is the one
+      // this turn consumed (a concurrent conversation-B emit must not leave
+      // conversation-A's resolution hanging). The attempt fence inside
+      // completeFencedEnvelopes drops late events from a superseded attempt
+      // (the TTL re-emit took the source over) AND fork-handled envelopes
+      // (no fence written), so it can never close the in-flight retry's
+      // work nor double-close fork acks. F3-absorbed envelopes appear in
+      // the absorbing turn's envelopeIds and settle here naturally. The
+      // server decides reply broad-cover vs no_action per batch; turn_failed
+      // sweeps the same way with the error step below as the visible record.
+      await completeFencedEnvelopes(ctx, event.envelopeIds);
+
       // Staleness guard: only idle if this event's turn covers the AGENT'S
       // latest emitted envelope (the marker is agent-global — all chats share
       // the one main session, so a done signal for chat A's turn must not