@parall/parel-channel 1.40.0 → 1.41.0

package/dist/channel-prompt.d.ts

@@ -25,6 +25,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 +38,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;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;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

@@ -31,6 +31,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 +62,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.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;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,eAAe,EACzB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CAqH5B"}

package/dist/delivery.js

@@ -1,5 +1,6 @@
 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 { 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.
@@ -28,12 +29,14 @@ export async function buildParallDelivery(delivery, 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) {
+        // 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);
@@ -48,7 +51,24 @@ export async function buildParallDelivery(delivery, ctx) {
     // 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 });
+    // 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.
+    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);
+        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',
@@ -99,9 +119,17 @@ export async function buildParallDelivery(delivery, ctx) {
     // 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.
+    // 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) {
-        await idleUnlessSuperseded(ctx, route.envelopeId, 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,145 @@
+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).
+ *
+ * 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.
+ */
+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":"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"}

package/dist/fork.js

@@ -0,0 +1,320 @@
+/**
+ * Fork-on-busy scheduling (the parall-side half of parel F4, parel-mono #140;
+ * strategy ownership per parel-session-alignment-plan.md §6 — the platform
+ * provides the spawnChildSession primitive, WHEN to fork is connector code).
+ *
+ * Model, mirroring the standard runtimes' fork-on-busy:
+ * - The main session is the single orchestrator. While it is mid-turn, a
+ *   message for a DIFFERENT conversation would head-of-line block behind it.
+ * - Instead, the connector spawns a fork child session (inherits main's
+ *   transcript at the last turn boundary — platform-guaranteed) keyed by an
+ *   opaque childRef, and routes that conversation's follow-ups to the child
+ *   via emitEvent deliverTo.
+ * - The child replies through the normal turn-end deliver (its envelopes
+ *   carry the same replyRoute shape), and its summary flows back to main via
+ *   the platform's async child notification. Same-conversation messages keep
+ *   riding main (steer/inject handles mid-turn arrival there).
+ *
+ * Busy tracking is BEST-EFFORT on the E1 turn stream (turn_started /
+ * turn_completed / turn_failed): a missed event mis-classifies busy vs idle,
+ * which costs a fork too many or a queued message too long — never
+ * correctness (F2 subject grouping guarantees turns don't mix conversations
+ * either way). Stale entries expire by TTL so a lost done event cannot wedge
+ * the classifier.
+ *
+ * Ack discipline: the spawn opening message — and any follow-up routed to
+ * the child before provisioning is confirmed — is NOT acked on emit; spawn
+ * failures come back asynchronously (child_spawn_failed) and an
+ * acked-but-never-processed message would be silently lost. Parked acks ride
+ * the child bookkeeping row and fire (by WorkItem id, re-sent a bounded
+ * number of times) on the child's observed events. On spawn failure the
+ * inbound layer arms an onTimer re-drive (FORK_RETRY_DELAY_MS) so the
+ * messages are re-planned promptly on a healthy long-lived connection —
+ * transient failures re-issue the SAME spawn ref (branch 1a), terminal ones
+ * re-plan from scratch (fresh ref or main).
+ */
+/** Main-session turn considered over after this long without a done event. */
+const MAIN_TURN_TTL_MS = 15 * 60 * 1000;
+/** A child with no observed activity for this long is considered gone. */
+const CHILD_TTL_MS = 10 * 60 * 1000;
+/** After a disabled/unsupported spawn failure, stop trying to fork for a while. */
+const FORK_DISABLED_TTL_MS = 60 * 60 * 1000;
+/** Delay before a failed spawn's messages are re-driven through onTimer. */
+export const FORK_RETRY_DELAY_MS = 15_000;
+/** Cap on un-acked follow-ups parked on an unconfirmed child. */
+const MAX_PENDING_FOLLOWUPS = 20;
+/** Stop re-sending acks after this many settle rounds. */
+const MAX_ACK_ATTEMPTS = 3;
+const MAIN_TURN_KEY = 'forkMainTurn';
+export const FORK_RETRY_PREFIX = 'forkRetry:';
+const FORK_DISABLED_KEY = 'forkDisabled';
+const childKey = (subject) => `forkChild:${subject}`;
+const childSubjectKey = (childRef) => `forkChildSubject:${childRef}`;
+function isLive(at, ttl, now) {
+    return typeof at === 'number' && now - at < ttl;
+}
+/**
+ * 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 async function planForkDecision(ctx, subject, sourceId) {
+    const now = ctx.now();
+    const child = (await ctx.store?.get(childKey(subject)).catch(() => null));
+    if (child?.childRef && isLive(child.at, CHILD_TTL_MS, now)) {
+        // 1a. A replay of the fork's own opening message: re-issue the spawn
+        //     with the SAME childRef. The platform spawn is idempotent (same ref
+        //     → same child, duplicate input suppressed, transient
+        //     concurrency_limit failures retry through) — this is both the retry
+        //     path for transient spawn failures and the duplicate-processing
+        //     guard (a deliverTo here would bypass ingress dedupe, the opening
+        //     input never was an envelope). Matched on the row-lifetime
+        //     openingSourceId, not pendingAcks — the acks list can be dropped
+        //     after bounded re-sends while replays must keep matching.
+        if (child.openingSourceId === sourceId) {
+            return { mode: 'spawn', childRef: child.childRef };
+        }
+        // 1b. An existing live child owns its conversation's follow-ups. Until
+        //     the child's first observed event confirms provisioning, follow-up
+        //     acks are parked on the row (a deliverTo into a terminally-failed
+        //     spawn is host-ignored — acking up front would lose the message).
+        return { mode: 'deliverTo', childRef: child.childRef, trackAck: child.confirmed !== true };
+    }
+    // 2. Forking disabled (binding opt-out observed) — everything rides main.
+    const disabled = (await ctx.store?.get(FORK_DISABLED_KEY).catch(() => null));
+    if (disabled && isLive(disabled.at, FORK_DISABLED_TTL_MS, now)) {
+        return { mode: 'main' };
+    }
+    // 3. Main mid-turn on a DIFFERENT conversation → fork. Same conversation
+    //    stays on main (inject-in-flight absorbs it there).
+    const turn = (await ctx.store?.get(MAIN_TURN_KEY).catch(() => null));
+    if (turn?.turnId && isLive(turn.at, MAIN_TURN_TTL_MS, now) && turn.subject !== subject) {
+        // now() suffix: a childRef is burned once its spawn fails terminally
+        // (platform mapping row is three-state), so a re-plan after a terminal
+        // failure must mint a fresh ref; retries of a still-pending spawn go
+        // through branch 1a with the recorded ref instead.
+        return { mode: 'spawn', childRef: `fk-${now.toString(36)}-${subject}` };
+    }
+    return { mode: 'main' };
+}
+/** 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 async function recordSpawn(ctx, subject, childRef, opening) {
+    const existing = (await ctx.store?.get(childKey(subject)).catch(() => null));
+    const row = existing?.childRef === childRef
+        ? { ...existing, at: ctx.now() }
+        : { childRef, at: ctx.now(), pendingAcks: [opening], openingSourceId: opening.sourceId };
+    await ctx.store?.set(childKey(subject), row).catch(() => { });
+    await ctx.store?.set(childSubjectKey(childRef), subject).catch(() => { });
+}
+/**
+ * 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 async function trackFollowUpAck(ctx, subject, childRef, ack) {
+    const child = (await ctx.store?.get(childKey(subject)).catch(() => null));
+    if (!child || child.childRef !== childRef)
+        return false;
+    const acks = child.pendingAcks ?? [];
+    if (acks.some((a) => a.dispatchId === ack.dispatchId))
+        return true; // replay — already parked
+    if (acks.length >= MAX_PENDING_FOLLOWUPS)
+        return false;
+    const row = { ...child, at: ctx.now(), pendingAcks: [...acks, ack] };
+    await ctx.store?.set(childKey(subject), row).catch(() => { });
+    return true;
+}
+/** 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 async function childRefKnown(ctx, childRef) {
+    const subject = (await ctx.store?.get(childSubjectKey(childRef)).catch(() => null));
+    if (!subject)
+        return false;
+    const child = (await ctx.store?.get(childKey(subject)).catch(() => null));
+    return child?.childRef === childRef;
+}
+/** Whether a subject's live child has ever produced an observed event. */
+export async function childConfirmed(ctx, subject, childRef) {
+    const child = (await ctx.store?.get(childKey(subject)).catch(() => null));
+    return child?.childRef === childRef && child.confirmed === true;
+}
+/** Drop one subject's fork routing (give-up path: message re-plans fresh). */
+export async function clearForkSubject(ctx, subject, childRef) {
+    const child = (await ctx.store?.get(childKey(subject)).catch(() => null));
+    if (child?.childRef === childRef) {
+        await ctx.store?.delete(childKey(subject)).catch(() => { });
+    }
+    await ctx.store?.delete(childSubjectKey(childRef)).catch(() => { });
+}
+/**
+ * Bump-and-park a fork retry ledger row (also the spawn-verification
+ * coordinate onTimer re-plans). Returns the attempt count INCLUDING this one.
+ */
+export async function bumpForkRetryAttempts(ctx, retryKey, data) {
+    const prior = (await ctx.store?.get(retryKey).catch(() => null));
+    const attempts = (prior?.attempts ?? 0) + 1;
+    await ctx.store?.set(retryKey, { ...data, attempts }).catch(() => { });
+    return attempts;
+}
+/** Give up re-verifying a spawn after this many timer rounds. */
+export 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 async function clearForkState(ctx) {
+    const refs = [];
+    try {
+        // EVERY fork-scoped key deliberately shares the `fork` prefix
+        // (forkChild / forkChildSubject / forkMainTurn / forkDisabled /
+        // forkRetry) so this one list-and-delete purges the whole family — a
+        // surviving disabled latch would suppress F4 for an hour after a reset,
+        // and a surviving retry row would re-drive a pre-reset message into the
+        // fresh session. Keep new fork keys on the prefix.
+        const keys = (await ctx.store?.list('fork').catch(() => [])) ?? [];
+        for (const key of keys) {
+            if (key.startsWith('forkChildSubject:')) {
+                refs.push(key.slice('forkChildSubject:'.length));
+            }
+            await ctx.store?.delete(key).catch(() => { });
+        }
+    }
+    catch {
+        // Best-effort: leftover rows expire by TTL anyway.
+    }
+    return refs;
+}
+/**
+ * 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 async function noteMainTurnEvent(ctx, event) {
+    if (event.type === 'turn_started') {
+        const row = { turnId: event.turnId, subject: event.subject, at: ctx.now() };
+        await ctx.store?.set(MAIN_TURN_KEY, row).catch(() => { });
+        return;
+    }
+    if (event.type === 'turn_completed' || event.type === 'turn_failed') {
+        const turn = (await ctx.store?.get(MAIN_TURN_KEY).catch(() => null));
+        // Clear only the turn this done event belongs to — a stale done for a
+        // superseded turn must not mark a newer running turn idle.
+        if (!turn || turn.turnId === event.turnId) {
+            await ctx.store?.delete(MAIN_TURN_KEY).catch(() => { });
+        }
+    }
+}
+/**
+ * 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 async function settleChildEvent(ctx, event) {
+    const childRef = event.childRef;
+    if (!childRef)
+        return null;
+    const subject = event.subject ||
+        (await ctx.store?.get(childSubjectKey(childRef)).catch(() => null)) ||
+        '';
+    if (!subject)
+        return null;
+    const child = (await ctx.store?.get(childKey(subject)).catch(() => null));
+    if (!child || child.childRef !== childRef) {
+        // Unknown/superseded child — refresh nothing, ack nothing.
+        return { subject, pendingAcks: [] };
+    }
+    // Acks are re-issued on subsequent events (bounded) rather than cleared on
+    // first send: the ack rides a fire-and-forget fetch effect, and clearing
+    // eagerly would let one lost request orphan the WorkItem in `received`
+    // forever (its replay would then re-enter the child as a duplicate).
+    const acks = child.pendingAcks ?? [];
+    const attempts = (child.ackAttempts ?? 0) + 1;
+    const done = attempts >= MAX_ACK_ATTEMPTS;
+    const refreshed = {
+        childRef,
+        at: ctx.now(),
+        confirmed: true,
+        // openingSourceId survives the ack-list drop — replay identity is
+        // row-lifetime (see the field doc).
+        ...(child.openingSourceId ? { openingSourceId: child.openingSourceId } : {}),
+        ...(done ? {} : { pendingAcks: acks, ackAttempts: attempts }),
+    };
+    await ctx.store?.set(childKey(subject), refreshed).catch(() => { });
+    return { subject, pendingAcks: acks };
+}
+/**
+ * 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 async function handleChildSpawnFailed(ctx, event) {
+    console.error(`[parel-channel] child spawn failed (${event.code}): ${event.error} (ref ${event.childRef})`);
+    const subject = (await ctx.store?.get(childSubjectKey(event.childRef)).catch(() => null)) ??
+        '';
+    const child = subject
+        ? (await ctx.store?.get(childKey(subject)).catch(() => null))
+        : null;
+    const pendingAcks = child?.childRef === event.childRef ? (child.pendingAcks ?? []) : [];
+    if (event.code === 'concurrency_limit') {
+        // Transient: the platform keeps the mapping in `provisioning` and the
+        // SAME childRef can retry — keep the bookkeeping; the caller's retry
+        // timer re-drives the opening message through branch 1a.
+        return { cleared: false, subject, pendingAcks };
+    }
+    if (subject) {
+        if (child?.childRef === event.childRef) {
+            await ctx.store?.delete(childKey(subject)).catch(() => { });
+        }
+        await ctx.store?.delete(childSubjectKey(event.childRef)).catch(() => { });
+    }
+    if (event.code === 'disabled' || event.code === 'unsupported_routing') {
+        await ctx.store?.set(FORK_DISABLED_KEY, { at: ctx.now() }).catch(() => { });
+    }
+    return { cleared: true, subject, pendingAcks };
+}
+/**
+ * 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).
+ *
+ * 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.
+ */
+export function buildForkScopePrefix(subject, threadRootId) {
+    // Quoted-heredoc input form (mirrors agent-core's send hint): plain
+    // `--text "…"` lets the sandbox shell expand $, backticks and eat quotes —
+    // and this is the opening turn's ONLY delivery path.
+    const send = threadRootId
+        ? `parall messages send ${subject} --thread-root-id ${threadRootId} --text-file - <<'EOF'`
+        : `parall messages send ${subject} --text-file - <<'EOF'`;
+    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`);
+}