@parall/parel-channel 1.40.0 → 1.42.0

package/dist/channel-prompt.d.ts

@@ -5,9 +5,10 @@
  * chat shares the agent's ONE parel session, so consecutive turns can come
  * from different conversations — each message is framed with its originating
  * chat so the model registers the context switch instead of answering chat B
- * with chat A's thread of thought. No reply hint: the turn-end reply is
- * auto-delivered to the right chat by replyRoute (deliver()), and sandbox CLI
- * calls get the right PRLL_CHAT_ID via per-turn invocation context.
+ * with chat A's thread of thought. No per-message reply hint: the system
+ * prompt teaches the CLI-only reply contract once (SSOT — plain text is
+ * never delivered; reply via `parall messages send`), and per-turn
+ * invocation context presets PRLL_CHAT_ID so the bare send hits this chat.
  *
  * External IM channel messages (buildChannelPrompt, channel_message
  * dispatches). Mirrors agent-core's event-format.ts channel branch, adapted
@@ -25,6 +26,12 @@
  *   form ({"message_id": …}) so threaded conversations aren't nudged toward
  *   new top-level messages.
  */
+export interface PromptAttachment {
+    id: string;
+    fileName: string;
+    fileSize: number;
+    mimeType: string;
+}
 export interface ChatPromptArgs {
     chatId: string;
     /** Display name of the chat; undefined when unresolved (best-effort). */
@@ -32,8 +39,10 @@ export interface ChatPromptArgs {
     /** Sender user id (usr_); display-name enrichment is a follow-up. */
     senderId?: string;
     threadRootId?: string;
-    /** The inbound message text (raw, un-framed). */
+    /** The inbound message text (raw, un-framed); may be empty (attachment-only). */
     text: string;
+    /** Message attachments — rendered as reference lines (agent fetches via CLI). */
+    attachments?: PromptAttachment[];
 }
 /**
  * Frame a Parall chat message with its conversation of origin. Kept to a

package/dist/channel-prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel-prompt.d.ts","sourceRoot":"","sources":["../src/channel-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AASH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAS5D;AAED,MAAM,WAAW,iBAAiB;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAkBlE"}
+{"version":3,"file":"channel-prompt.d.ts","sourceRoot":"","sources":["../src/channel-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AASH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,WAAW,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAClC;AAmBD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAU5D;AAED,MAAM,WAAW,iBAAiB;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAkBlE"}

package/dist/channel-prompt.js

@@ -5,9 +5,10 @@
  * chat shares the agent's ONE parel session, so consecutive turns can come
  * from different conversations — each message is framed with its originating
  * chat so the model registers the context switch instead of answering chat B
- * with chat A's thread of thought. No reply hint: the turn-end reply is
- * auto-delivered to the right chat by replyRoute (deliver()), and sandbox CLI
- * calls get the right PRLL_CHAT_ID via per-turn invocation context.
+ * with chat A's thread of thought. No per-message reply hint: the system
+ * prompt teaches the CLI-only reply contract once (SSOT — plain text is
+ * never delivered; reply via `parall messages send`), and per-turn
+ * invocation context presets PRLL_CHAT_ID so the bare send hits this chat.
  *
  * External IM channel messages (buildChannelPrompt, channel_message
  * dispatches). Mirrors agent-core's event-format.ts channel branch, adapted
@@ -31,6 +32,22 @@ function sanitizeMeta(value) {
         .replace(/[[\]|]/g, ' ')
         .trim();
 }
+/**
+ * One reference line per attachment, byte-identical to agent-core's
+ * event-format rendering: the agent learns the attachment EXISTS and pulls
+ * the bytes itself through its sandbox CLI (`parall files download prll://…`)
+ * — same discover-then-fetch contract the standard runtimes use.
+ */
+function attachmentLines(attachments) {
+    if (!attachments?.length)
+        return [];
+    return attachments.map((att) => {
+        const sizeStr = att.fileSize >= 1048576
+            ? `${(att.fileSize / 1048576).toFixed(1)}MB`
+            : `${Math.round(att.fileSize / 1024)}KB`;
+        return `[Attachment: prll://${att.id} | ${sanitizeMeta(att.mimeType)} | ${sizeStr} | ${sanitizeMeta(att.fileName)}]`;
+    });
+}
 /**
  * Frame a Parall chat message with its conversation of origin. Kept to a
  * minimal metadata header: the text itself is the user message, and heavier
@@ -46,6 +63,7 @@ export function buildChatPrompt(args) {
         lines.push(`[From: ${sanitizeMeta(args.senderId)}]`);
     if (args.threadRootId)
         lines.push(`[Thread: ${sanitizeMeta(args.threadRootId)}]`);
+    lines.push(...attachmentLines(args.attachments));
     lines.push('', args.text);
     return lines.join('\n');
 }

package/dist/connect.d.ts

@@ -18,5 +18,12 @@ export declare function parallOrgId(ctx: ConnectorContext): string;
  * shipped — reporting degrades to off until the agent is redeployed.
  */
 export declare function parallAgentId(ctx: ConnectorContext): string;
+/**
+ * Whether this deployment provisions a sandbox (shell + `parall` CLI) for the
+ * agent. Server writes `parallSandbox: "off"` into the connection config only
+ * for conversational-only deployments (no platform E2B key) — an absent field
+ * means sandbox-enabled (every config generated before the field existed was).
+ */
+export declare function sandboxEnabled(ctx: ConnectorContext): boolean;
 export declare function requireAgk(ctx: ConnectorContext): string;
 //# sourceMappingURL=connect.d.ts.map

package/dist/connect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAE1E;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAyBlF;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAE1D;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAE3D;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAMxD"}
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAE1E;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAyBlF;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAE1D;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAE3D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAE7D;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAMxD"}

package/dist/connect.js

@@ -48,6 +48,15 @@ export function parallOrgId(ctx) {
 export function parallAgentId(ctx) {
     return String(ctx.config.parallAgentId ?? '');
 }
+/**
+ * Whether this deployment provisions a sandbox (shell + `parall` CLI) for the
+ * agent. Server writes `parallSandbox: "off"` into the connection config only
+ * for conversational-only deployments (no platform E2B key) — an absent field
+ * means sandbox-enabled (every config generated before the field existed was).
+ */
+export function sandboxEnabled(ctx) {
+    return String(ctx.config.parallSandbox ?? '') !== 'off';
+}
 export function requireAgk(ctx) {
     const agk = ctx.secrets.parallApiKey;
     if (!agk) {

package/dist/delivery.d.ts

@@ -1,24 +1,31 @@
 import type { ChannelDelivery, ConnectorContext, ConnectorEffect } from '@parel/plugin-sdk';
 /**
- * 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 declare function buildParallDelivery(delivery: ChannelDelivery, ctx: ConnectorContext): Promise<ConnectorEffect[]>;
 //# sourceMappingURL=delivery.d.ts.map

package/dist/delivery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delivery.d.ts","sourceRoot":"","sources":["../src/delivery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAU5F;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,eAAe,EACzB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CA2F5B"}
+{"version":3,"file":"delivery.d.ts","sourceRoot":"","sources":["../src/delivery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAa5F;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,eAAe,EACzB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CAgF5B"}

package/dist/delivery.js

@@ -1,107 +1,104 @@
-import { parallApiUrl, parallOrgId, requireAgk } from './connect.js';
-import { ensureSession, invalidateSession, patchSession, REQUEST_TIMEOUT_MS, TURN_ENVELOPE_KEY, } from './session.js';
+import { childRefKnown } from './fork.js';
+import { completeFencedEnvelopes, createSuppressedTextStep, ensureChildSession, ensureSession, invalidateChildSession, invalidateSession, patchSession, 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, ctx) {
-    const apiUrl = parallApiUrl(ctx);
-    const agk = requireAgk(ctx);
-    const orgId = parallOrgId(ctx);
     const route = (delivery.replyRoute?.data ?? {});
-    const chatId = route.chatId;
-    if (!chatId) {
-        // External IM turn (channel_message): the reply already went out through
-        // the provider clip, agent-invoked — 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.conversationId) {
-            const sessionId = await ensureSession(ctx, { timeoutMs: 3_000 });
-            if (sessionId) {
-                await idleUnlessSuperseded(ctx, route.envelopeId, sessionId);
-            }
-        }
+    // 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) {
+        console.warn('[parel-channel] dropping turn-end text from stale fork', route.childRef);
         return [];
     }
-    const payload = delivery.payload;
-    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.
-    const sessionId = 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;
+        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 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]);
     }
-    // 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.
-    if (sessionId) {
-        await idleUnlessSuperseded(ctx, route.envelopeId, sessionId);
+    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/dist/fork.d.ts

@@ -0,0 +1,148 @@
+import type { ConnectorContext } from '@parel/plugin-sdk';
+import type { AgentEventWithChild, ChildSpawnFailedEvent } from './parel-sdk-compat.js';
+/** Delay before a failed spawn's messages are re-driven through onTimer. */
+export declare const FORK_RETRY_DELAY_MS = 15000;
+export declare const FORK_RETRY_PREFIX = "forkRetry:";
+export interface PendingAck {
+    dispatchId: string;
+    sourceId: string;
+}
+export interface ChildRow {
+    childRef: string;
+    at: number;
+    /**
+     * The opening message's replay identity — set at spawn and NEVER cleared
+     * while the row lives. pendingAcks can be dropped after MAX_ACK_ATTEMPTS,
+     * but a replay of the opening source must still match branch 1a (its input
+     * was a spawn payload, not an envelope — a deliverTo replay would bypass
+     * ingress dedupe and inject the user's first message twice).
+     */
+    openingSourceId?: string;
+    /**
+     * Un-acked WorkItems this child holds: the spawn opening dispatch plus any
+     * follow-ups routed to the child BEFORE its provisioning was confirmed (a
+     * deliverTo into a spawn that then fails terminally is ignored by the host
+     * — acking those up front would lose them). Acked (by WorkItem id) on the
+     * child's observed events; sourceIds double as replay identities (a swept
+     * dispatch whose sourceId appears here is one of these very messages).
+     * pendingAcks[0] is always the opening message.
+     */
+    pendingAcks?: PendingAck[];
+    /** Set on the child's first observed event — provisioning demonstrably done. */
+    confirmed?: boolean;
+    /** Ack re-send counter: acks are re-issued on later events until this hits
+     * MAX_ACK_ATTEMPTS (fetch effects are fire-and-forget; one lost ack must
+     * not orphan the WorkItem forever). */
+    ackAttempts?: number;
+}
+export type ForkDecision = {
+    mode: 'main';
+}
+/** trackAck: the child is not yet confirmed — the caller must park the
+ * WorkItem ack on the bookkeeping row instead of acking on emit. */
+ | {
+    mode: 'deliverTo';
+    childRef: string;
+    trackAck: boolean;
+} | {
+    mode: 'spawn';
+    childRef: string;
+};
+/**
+ * Decide how to route one inbound chat message. Called on the message hot
+ * path — store reads only, never a fetch.
+ *
+ * Concurrency: the decision-then-record sequence is NOT internally locked —
+ * it relies on the parel host executing one connection's hooks serially (the
+ * C3 contract; the same guarantee the turnEnvelope marker's read-then-patch
+ * ordering already leans on). Two same-chat dispatches therefore cannot both
+ * observe "no child" — the second runs after the first's recordSpawn.
+ */
+export declare function planForkDecision(ctx: ConnectorContext, subject: string, sourceId: string): Promise<ForkDecision>;
+/** Record a just-issued spawn so follow-ups route to the child. Idempotent
+ * for the 1a replay path: an existing row for the same ref keeps its parked
+ * follow-up acks and confirmation state, only refreshing liveness. */
+export declare function recordSpawn(ctx: ConnectorContext, subject: string, childRef: string, opening: PendingAck): Promise<void>;
+/**
+ * Park a follow-up's WorkItem ack on an unconfirmed child. Returns false when
+ * the row is gone or the cap is hit — the caller then acks on emit (the cap
+ * bounds the loss window of a pathological never-confirming child; beyond it
+ * we prefer at-most-once for the tail over unbounded growth).
+ */
+export declare function trackFollowUpAck(ctx: ConnectorContext, subject: string, childRef: string, ack: PendingAck): Promise<boolean>;
+/** Whether a childRef is still part of live fork bookkeeping. Late child
+ * callbacks after a New Session purge (or after give-up) must NOT recreate
+ * fork ase_ rows via the blind get-or-create — a pre-reset child's delayed
+ * trace/reply would attach a fresh session under the NEW conversation line. */
+export declare function childRefKnown(ctx: ConnectorContext, childRef: string): Promise<boolean>;
+/** Whether a subject's live child has ever produced an observed event. */
+export declare function childConfirmed(ctx: ConnectorContext, subject: string, childRef: string): Promise<boolean>;
+/** Drop one subject's fork routing (give-up path: message re-plans fresh). */
+export declare function clearForkSubject(ctx: ConnectorContext, subject: string, childRef: string): Promise<void>;
+/**
+ * Bump-and-park a fork retry ledger row (also the spawn-verification
+ * coordinate onTimer re-plans). Returns the attempt count INCLUDING this one.
+ */
+export declare function bumpForkRetryAttempts(ctx: ConnectorContext, retryKey: string, data: Record<string, unknown>): Promise<number>;
+/** Give up re-verifying a spawn after this many timer rounds. */
+export declare const MAX_SPAWN_VERIFY_ATTEMPTS = 3;
+/**
+ * Purge ALL fork routing state — called on `agent.new_session`. The binding
+ * reset rotates main's conversation line; stale child routing surviving it
+ * would deliver post-reset messages into pre-reset forks (old context), and
+ * a stale busy marker would fork off a session that no longer exists.
+ * Returns the childRefs that were live so the caller can also invalidate
+ * their cached ase_ rows.
+ */
+export declare function clearForkState(ctx: ConnectorContext): Promise<string[]>;
+/**
+ * Track main-session busyness from the E1 turn stream. Child events (they
+ * carry childRef) must NOT feed this — only the main session's turns do.
+ */
+export declare function noteMainTurnEvent(ctx: ConnectorContext, event: AgentEventWithChild): Promise<void>;
+/**
+ * Resolve a child event's bookkeeping row (by its subject mirror) and fire
+ * the pending spawn ack exactly once. Returns the ack request when due.
+ */
+export declare function settleChildEvent(ctx: ConnectorContext, event: AgentEventWithChild): Promise<{
+    subject: string;
+    pendingAcks: PendingAck[];
+} | null>;
+/**
+ * A spawn failed before the child ran. NEVER acks the opening dispatch — it
+ * stays received and the catch-up sweep re-plans it. Failure codes split
+ * three ways (parel §18.2 three-state mapping semantics):
+ * - `concurrency_limit` is TRANSIENT: the platform keeps the mapping in
+ *   `provisioning` and the same childRef can retry — keep the bookkeeping so
+ *   the sweep's replay re-issues the same spawn key (branch 1a) instead of
+ *   abandoning one provisioning row per attempt.
+ * - `disabled` / `unsupported_routing` are configuration-shaped: clear the
+ *   bookkeeping AND park a no-fork flag so the connector stops re-trying a
+ *   fork the binding will never allow.
+ * - Everything else is terminal for this childRef (the ref is burned): clear
+ *   the bookkeeping so the sweep's re-plan mints a fresh ref.
+ * Returns true when the bookkeeping was cleared (the caller then settles the
+ * orphaned child ase_).
+ */
+export declare function handleChildSpawnFailed(ctx: ConnectorContext, event: ChildSpawnFailedEvent): Promise<{
+    cleared: boolean;
+    subject: string;
+    pendingAcks: PendingAck[];
+}>;
+/**
+ * Scope guard prepended to a fork child's opening input — the behavioral
+ * fallback agent-core applies to every forked dispatch (buildForkScopePrefix
+ * equivalent; the platform already excludes in-flight output from the seed,
+ * this line keeps the child from "finishing" main's visible work).
+ *
+ * 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 declare function buildForkScopePrefix(subject: string, threadRootId?: string): string;
+//# sourceMappingURL=fork.d.ts.map

package/dist/fork.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fork.d.ts","sourceRoot":"","sources":["../src/fork.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AA+CxF,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAS1C,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAW9C,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,gFAAgF;IAChF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;2CAEuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;AAClB;oEACoE;GAClE;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAMxC;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,CAAC,CAwCvB;AAED;;sEAEsE;AACtE,wBAAsB,WAAW,CAC/B,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,UAAU,GACd,OAAO,CAAC,OAAO,CAAC,CASlB;AAED;;;+EAG+E;AAC/E,wBAAsB,aAAa,CAAC,GAAG,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO7F;AAED,0EAA0E;AAC1E,wBAAsB,cAAc,CAClC,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED,8EAA8E;AAC9E,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED,iEAAiE;AACjE,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAoB7E;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,UAAU,EAAE,CAAA;CAAE,GAAG,IAAI,CAAC,CA+BhE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,UAAU,EAAE,CAAA;CAAE,CAAC,CA2B3E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAYnF"}