@parall/cli 1.36.1 → 1.38.0

package/dist/commands/chats.js

@@ -120,7 +120,7 @@ export function registerChatCommands(program) {
         .action(async (chatId, opts) => {
         try {
             if (opts.role !== undefined && opts.role !== 'member') {
-                throw new Error('--role only supports "member"; update the role after adding the member');
+                throw new Error('--role only supports "member"; the CLI cannot change member roles');
             }
             const { client, orgId } = resolveCredentials();
             await client.addChatMember(orgId, stripPrllScheme(chatId), stripPrllScheme(opts.userId));

package/dist/commands/dm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dm.d.ts","sourceRoot":"","sources":["../../src/commands/dm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiCpC,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,QAwDlD"}
+{"version":3,"file":"dm.d.ts","sourceRoot":"","sources":["../../src/commands/dm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuCpC,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,QA+DlD"}

package/dist/commands/dm.js

@@ -1,5 +1,6 @@
 import { resolveCredentials, resolveRuntimeContext } from '../lib/client.js';
 import { printJson, printError, printRefHint, stripPrllScheme } from '../lib/output.js';
+import { NO_BODY_ERROR, resolveMessageText, TEXT_FILE_OPTION_DESC, TEXT_OPTION_DESC, } from '../lib/text-input.js';
 import { uploadFile } from '../lib/upload.js';
 /**
  * Resolve a name-or-id argument to a user ID.
@@ -25,7 +26,8 @@ export function registerDMCommands(program) {
         .command('dm')
         .description('Send a direct message to a user by name or ID (auto-creates chat if needed)')
         .argument('<nameOrId>', 'Target user display name or ID (usr_...)')
-        .option('--text <text>', 'Message text')
+        .option('--text <text>', TEXT_OPTION_DESC)
+        .option('--text-file <path>', TEXT_FILE_OPTION_DESC)
         .option('--file <path>', 'Upload and attach a local file')
         .option('--attachment <id>', 'Attach an existing attachment (att_xxx or prll://att_xxx)')
         .option('--no-reply', 'Hint that the recipient should not reply')
@@ -38,7 +40,7 @@ export function registerDMCommands(program) {
                 printError(new Error('--file and --attachment are mutually exclusive'));
                 return;
             }
-            const text = opts.text || '';
+            const text = resolveMessageText(opts) || '';
             let attachmentIds;
             if (opts.file) {
                 const result = await uploadFile(client, orgId, opts.file);
@@ -48,7 +50,7 @@ export function registerDMCommands(program) {
                 attachmentIds = [stripPrllScheme(opts.attachment)];
             }
             if (!text && !attachmentIds) {
-                printError(new Error('Provide --text, --file, or --attachment'));
+                printError(new Error(NO_BODY_ERROR));
                 return;
             }
             const req = {

package/dist/commands/messages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/commands/messages.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKzC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,QAwJvD"}
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/commands/messages.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkBzC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,QA8MvD"}

package/dist/commands/messages.js

@@ -1,6 +1,8 @@
 import { ApiError } from '@parall/sdk';
-import { resolveCredentials, resolveRuntimeContext } from '../lib/client.js';
+import { randomUUID } from 'node:crypto';
+import { LaneContextError, markLaneReplyCommitted, resolveCredentials, resolveLaneDispatchContext, resolveRuntimeContext, } from '../lib/client.js';
 import { printError, printJson, printRefHint, stripPrllScheme } from '../lib/output.js';
+import { NO_BODY_ERROR, resolveMessageText, TEXT_FILE_OPTION_DESC, TEXT_OPTION_DESC, } from '../lib/text-input.js';
 import { uploadFile } from '../lib/upload.js';
 export function registerMessageCommands(program) {
     const messages = program.command('messages').description('Manage messages');
@@ -53,7 +55,8 @@ export function registerMessageCommands(program) {
         .command('send')
         .description('Send a message to a chat (text, file, or both)')
         .argument('[chatId]', 'Chat ID (defaults to PRLL_CHAT_ID if set)')
-        .option('--text <text>', 'Message text')
+        .option('--text <text>', TEXT_OPTION_DESC)
+        .option('--text-file <path>', TEXT_FILE_OPTION_DESC)
         .option('--file <path>', 'Upload and attach a local file')
         .option('--attachment <id>', 'Attach an existing attachment (att_xxx or prll://att_xxx)')
         .option('--thread-root-id <id>', 'Reply to a thread')
@@ -70,14 +73,14 @@ export function registerMessageCommands(program) {
             // `messages send` targets a chat. A user id here is an addressing
             // mistake — point at `dm` instead of letting the server reject it.
             if (chatId.startsWith('usr_')) {
-                printError(new ApiError(400, `prll://${chatId} is a user, not a chat. To message a user use: parall dm prll://${chatId} --text "..."`, 'INVALID_TARGET'));
+                printError(new ApiError(400, `prll://${chatId} is a user, not a chat. To message a user use: parall dm prll://${chatId} --text-file -`, 'INVALID_TARGET'));
                 return;
             }
             if (opts.file && opts.attachment) {
                 printError(new Error('--file and --attachment are mutually exclusive'));
                 return;
             }
-            const text = opts.text || '';
+            const text = resolveMessageText(opts) || '';
             let attachmentIds;
             if (opts.file) {
                 const result = await uploadFile(client, orgId, opts.file);
@@ -87,7 +90,7 @@ export function registerMessageCommands(program) {
                 attachmentIds = [stripPrllScheme(opts.attachment)];
             }
             if (!text && !attachmentIds) {
-                printError(new Error('Provide --text, --file, or --attachment'));
+                printError(new Error(NO_BODY_ERROR));
                 return;
             }
             const req = {
@@ -96,19 +99,59 @@ export function registerMessageCommands(program) {
             };
             if (attachmentIds)
                 req.attachment_ids = attachmentIds;
-            if (opts.threadRootId !== undefined)
-                req.thread_root_id = stripPrllScheme(opts.threadRootId);
+            const threadRootId = opts.threadRootId !== undefined ? stripPrllScheme(opts.threadRootId) : undefined;
+            if (threadRootId !== undefined)
+                req.thread_root_id = threadRootId;
             if (opts.reply === false)
                 req.hints = { no_reply: true };
             if (ctx.stepId)
                 req.agent_step_id = ctx.stepId;
             if (ctx.sessionId)
                 req.agent_session_id = ctx.sessionId;
-            const result = await client.sendMessage(orgId, chatId, req);
+            // Dispatch lane binding (PRLL_CONTEXT_DIR contract): a send whose
+            // exact (chat, thread) target has an active lane context rides the
+            // server's dispatch ledger — the lane token authorizes the write,
+            // and the FIRST conversational reply of the lane carries the
+            // reply:<dispatch_event_id> effect key so it resolves the dispatched
+            // work in the same transaction. Later sends in the same turn (and
+            // cross-chat sends, which find no lane context) use a random
+            // per-invocation idempotency key. All of this stays out of the
+            // model's view.
+            const laneCtx = resolveLaneDispatchContext(chatId, threadRootId);
+            let usedReplyKey = false;
+            if (laneCtx) {
+                req.dispatch_lane = laneCtx.lane;
+                if (laneCtx.dispatchEventId && !laneCtx.replyCommitted) {
+                    req.idempotency_key = `reply:${laneCtx.dispatchEventId}`;
+                    usedReplyKey = true;
+                }
+                else {
+                    req.idempotency_key = `cli:${randomUUID()}`;
+                }
+                if (!req.agent_step_id && laneCtx.stepId)
+                    req.agent_step_id = laneCtx.stepId;
+                if (!req.agent_session_id && laneCtx.sessionId)
+                    req.agent_session_id = laneCtx.sessionId;
+            }
+            const { message: result, deduplicated } = await client.sendMessageDetailed(orgId, chatId, req);
+            if (laneCtx && usedReplyKey) {
+                markLaneReplyCommitted(laneCtx);
+            }
             printJson(result);
+            if (deduplicated && usedReplyKey) {
+                console.error('Note: this reply was already sent by a previous run (deduplicated) — do not resend it.');
+            }
             printRefHint(result.id, 'Sent');
         }
         catch (err) {
+            if (err instanceof ApiError && err.code === 'STALE_LANE') {
+                printError(new ApiError(err.status, 'Your processing slot was taken over by a newer run — stop working on this conversation.', 'STALE_LANE'));
+                return;
+            }
+            if (err instanceof LaneContextError) {
+                printError(err);
+                return;
+            }
             printError(err);
         }
     });

package/dist/commands/tasks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../src/commands/tasks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QAqTpD"}
+{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../src/commands/tasks.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QAsWpD"}

package/dist/commands/tasks.js

@@ -1,4 +1,5 @@
-import { resolveCredentials } from '../lib/client.js';
+import { ApiError } from '@parall/sdk';
+import { resolveCredentials, resolveTypedDispatchBinding } from '../lib/client.js';
 import { printJson, printError, printRefHint, stripPrllScheme } from '../lib/output.js';
 function stripUndefined(obj) {
     return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
@@ -113,10 +114,30 @@ export function registerTaskCommands(program) {
             if (Object.keys(data).length === 0) {
                 printError(new Error('No fields to update. Provide at least one option.'));
             }
-            const result = await client.updateTask(orgId, taskId, data);
+            // Typed dispatch binding: when this turn is a typed dispatch about
+            // exactly this task, the update rides the claimed typed lane; the
+            // first update also carries the canonical task_update:<dsp> effect
+            // key so it resolves the dispatched work in the same transaction.
+            // Invisible to the model — same contract as message replies.
+            const binding = resolveTypedDispatchBinding(taskId);
+            const req = { ...data };
+            if (binding) {
+                req.dispatch_lane = binding.lane;
+                req.dispatch_event_id = binding.dispatchEventId;
+                if (binding.effectKey)
+                    req.dispatch_effect_key = binding.effectKey;
+            }
+            const result = await client.updateTask(orgId, taskId, req);
+            if (binding?.effectKey) {
+                binding.markCommitted();
+            }
             printJson(result);
         }
         catch (err) {
+            if (err instanceof ApiError && err.code === 'STALE_LANE') {
+                printError(new ApiError(err.status, 'Your processing slot was taken over by a newer run — stop working on this task.', 'STALE_LANE'));
+                return;
+            }
             printError(err);
         }
     });
@@ -268,10 +289,20 @@ export function registerTaskCommands(program) {
         .command('watch')
         .description('Watch a task (subscribe to comment notifications)')
         .argument('<taskId>', 'Task ID')
-        .action(async (taskId) => {
+        .option('--user-id <userId>', 'Subscribe another user instead of yourself (requires you to be the task creator, assignee, project lead, or an org owner/admin)')
+        .action(async (taskId, opts) => {
         try {
             const { client, orgId } = resolveCredentials();
-            await client.watchTask(orgId, stripPrllScheme(taskId));
+            const normalizedTaskId = stripPrllScheme(taskId);
+            const targetUserId = opts.userId ? stripPrllScheme(opts.userId) : undefined;
+            // A self-targeted --user-id is equivalent to plain self-watch; route it
+            // back to /watch so the behaviour matches `parall tasks watch` exactly.
+            if (targetUserId && targetUserId !== (await client.getMe()).id) {
+                await client.subscribeTaskMember(orgId, normalizedTaskId, targetUserId);
+            }
+            else {
+                await client.watchTask(orgId, normalizedTaskId);
+            }
             printJson({ ok: true });
         }
         catch (err) {
@@ -282,10 +313,20 @@ export function registerTaskCommands(program) {
         .command('unwatch')
         .description('Unwatch a task (stop receiving comment notifications)')
         .argument('<taskId>', 'Task ID')
-        .action(async (taskId) => {
+        .option('--user-id <userId>', 'Unsubscribe another user instead of yourself (requires you to be the task creator, assignee, project lead, or an org owner/admin)')
+        .action(async (taskId, opts) => {
         try {
             const { client, orgId } = resolveCredentials();
-            await client.unwatchTask(orgId, stripPrllScheme(taskId));
+            const normalizedTaskId = stripPrllScheme(taskId);
+            const targetUserId = opts.userId ? stripPrllScheme(opts.userId) : undefined;
+            // A self-targeted --user-id is equivalent to plain self-unwatch; route it
+            // back to /watch so the behaviour matches `parall tasks unwatch` exactly.
+            if (targetUserId && targetUserId !== (await client.getMe()).id) {
+                await client.unsubscribeTaskMember(orgId, normalizedTaskId, targetUserId);
+            }
+            else {
+                await client.unwatchTask(orgId, normalizedTaskId);
+            }
             printJson({ ok: true });
         }
         catch (err) {

package/dist/lib/client.d.ts

@@ -11,6 +11,12 @@ export type RuntimeContext = {
     triggerMessageId?: string;
     /** When true, CLI should not send automatic reply messages — the bridge handles text projection. */
     noReply: boolean;
+    /** Dispatch ledger binding of the current turn (additive; bridge-written). */
+    dispatchEventId?: string;
+    lane?: string;
+    laneTargetUri?: string;
+    /** Typed binding hint: the task this dispatch is about (task dispatch turns only). */
+    taskId?: string;
 };
 /**
  * Read per-dispatch context from ENV + sideband files.
@@ -21,5 +27,60 @@ export type RuntimeContext = {
  * 3. PRLL_STEP_ID_FILE plain text (legacy step-id-only backward compat)
  */
 export declare function resolveRuntimeContext(): RuntimeContext;
+/** Typed dispatch binding for a task write, derived from the turn context. */
+export type TypedDispatchBinding = {
+    lane: string;
+    dispatchEventId: string;
+    /** Set for the first (resolving) update of this dispatch. */
+    effectKey?: string;
+    markCommitted: () => void;
+};
+/**
+ * Resolve the typed-lane binding for `parall task update <taskId>`: the
+ * current turn must be a typed dispatch (lane target `dsp:<id>`) about this
+ * exact task. The first update carries the canonical
+ * `task_update:<dispatch_event_id>` effect key (resolves the WorkItem in the
+ * same transaction); later updates go keyless (lane-checked only). The
+ * committed flag lives in a CLI-owned sidecar keyed by the typed lane; when
+ * PRLL_CONTEXT_DIR is absent the sidecar can't exist, so no effect key is
+ * ever attached (a blind key would make a *different* second update replay
+ * the first one's result instead of applying).
+ */
+export declare function resolveTypedDispatchBinding(taskId: string): TypedDispatchBinding | null;
+/** Per-lane dispatch context (PRLL_CONTEXT_DIR contract), keyed by send target. */
+export type LaneDispatchContext = {
+    lane: string;
+    dispatchEventId?: string;
+    targetUri: string;
+    threadRootId?: string;
+    sessionId?: string;
+    stepId?: string;
+    /** True when the reply slot for this lane was already consumed (sidecar). */
+    replyCommitted: boolean;
+    replyStatePath: string;
+};
+/**
+ * Error thrown when a lane context file exists for the send target but lacks
+ * the dispatch/lane fields — the strong-idempotency path must fail closed
+ * rather than silently degrade to a best-effort write.
+ */
+export declare class LaneContextError extends Error {
+}
+/**
+ * Look up the dispatch lane context for a send target under the
+ * PRLL_CONTEXT_DIR contract. Returns null when the contract is not in effect
+ * (env unset) or no lane file exists for this exact (target, thread) — i.e.
+ * a cross-chat / non-dispatch send, which stays on the best-effort path.
+ *
+ * The lane key encodes the full lane identity: a thread send only matches a
+ * thread lane, a channel send only a channel lane.
+ */
+export declare function resolveLaneDispatchContext(chatId: string, threadRootId?: string): LaneDispatchContext | null;
+/**
+ * Record that this lane's first conversational reply has been committed. The
+ * sidecar is CLI-owned — never the bridge-owned context file, which the
+ * bridge rewrites throughout the turn and would clobber inline state.
+ */
+export declare function markLaneReplyCommitted(laneCtx: LaneDispatchContext): void;
 export declare function resolveCredentials(): ResolvedCredentials;
 //# sourceMappingURL=client.d.ts.map

package/dist/lib/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,6DAA6D;AAC7D,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oGAAoG;IACpG,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,cAAc,CAiCtD;AAED,wBAAgB,kBAAkB,IAAI,mBAAmB,CA8BxD"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,6DAA6D;AAC7D,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oGAAoG;IACpG,OAAO,EAAE,OAAO,CAAC;IACjB,8EAA8E;IAC9E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,cAAc,CAmDtD;AAED,8EAA8E;AAC9E,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,IAAI,CAAC;CAC3B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAwCvF;AAED,mFAAmF;AACnF,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;CAAG;AAE9C;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,EACd,YAAY,CAAC,EAAE,MAAM,GACpB,mBAAmB,GAAG,IAAI,CA+E5B;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAYzE;AAED,wBAAgB,kBAAkB,IAAI,mBAAmB,CA8BxD"}

package/dist/lib/client.js

@@ -1,4 +1,5 @@
 import * as fs from 'node:fs';
+import { laneContextFilePath, laneReplyStateFilePath } from '@parall/agent-core';
 import { ParallClient } from '@parall/sdk';
 /**
  * Read per-dispatch context from ENV + sideband files.
@@ -14,6 +15,10 @@ export function resolveRuntimeContext() {
     let chatId = process.env.PRLL_CHAT_ID?.trim() || undefined;
     let triggerMessageId = process.env.PRLL_TRIGGER_MESSAGE_ID?.trim() || undefined;
     let noReply = process.env.PRLL_NO_REPLY === '1';
+    let dispatchEventId;
+    let lane;
+    let laneTargetUri;
+    let taskId;
     if (process.env.PRLL_CONTEXT_FILE) {
         try {
             const raw = fs.readFileSync(process.env.PRLL_CONTEXT_FILE, 'utf-8').trim();
@@ -25,6 +30,10 @@ export function resolveRuntimeContext() {
                 stepId ??= ctx.step_id || undefined;
                 if (ctx.no_reply === true)
                     noReply = true;
+                dispatchEventId = ctx.dispatch_event_id || undefined;
+                lane = ctx.lane || undefined;
+                laneTargetUri = ctx.target_uri || undefined;
+                taskId = ctx.task_id || undefined;
             }
         }
         catch {
@@ -41,7 +50,170 @@ export function resolveRuntimeContext() {
             // File not yet written or unreadable — no step context
         }
     }
-    return { sessionId, stepId, chatId, triggerMessageId, noReply };
+    return {
+        sessionId,
+        stepId,
+        chatId,
+        triggerMessageId,
+        noReply,
+        dispatchEventId,
+        lane,
+        laneTargetUri,
+        taskId,
+    };
+}
+/**
+ * Resolve the typed-lane binding for `parall task update <taskId>`: the
+ * current turn must be a typed dispatch (lane target `dsp:<id>`) about this
+ * exact task. The first update carries the canonical
+ * `task_update:<dispatch_event_id>` effect key (resolves the WorkItem in the
+ * same transaction); later updates go keyless (lane-checked only). The
+ * committed flag lives in a CLI-owned sidecar keyed by the typed lane; when
+ * PRLL_CONTEXT_DIR is absent the sidecar can't exist, so no effect key is
+ * ever attached (a blind key would make a *different* second update replay
+ * the first one's result instead of applying).
+ */
+export function resolveTypedDispatchBinding(taskId) {
+    const ctx = resolveRuntimeContext();
+    if (!ctx.lane || !ctx.dispatchEventId)
+        return null;
+    if (!ctx.laneTargetUri?.startsWith('dsp:'))
+        return null;
+    if (!ctx.taskId || ctx.taskId !== taskId)
+        return null;
+    const binding = {
+        lane: ctx.lane,
+        dispatchEventId: ctx.dispatchEventId,
+        markCommitted: () => { },
+    };
+    const contextDir = process.env.PRLL_CONTEXT_DIR?.trim();
+    if (!contextDir)
+        return binding;
+    const sidecarPath = laneReplyStateFilePath(contextDir, ctx.laneTargetUri);
+    let committed = false;
+    try {
+        const sidecar = JSON.parse(fs.readFileSync(sidecarPath, 'utf-8'));
+        committed =
+            sidecar.reply_committed === true && sidecar.dispatch_event_id === ctx.dispatchEventId;
+    }
+    catch {
+        // No sidecar yet — resolving update not committed.
+    }
+    if (!committed) {
+        const dispatchEventId = ctx.dispatchEventId;
+        binding.effectKey = `task_update:${dispatchEventId}`;
+        binding.markCommitted = () => {
+            try {
+                fs.writeFileSync(sidecarPath, JSON.stringify({ dispatch_event_id: dispatchEventId, reply_committed: true }), 'utf-8');
+            }
+            catch {
+                // Best-effort — a lost sidecar means the next update retries the key
+                // and the server's effect ledger replies idempotently.
+            }
+        };
+    }
+    return binding;
+}
+/**
+ * Error thrown when a lane context file exists for the send target but lacks
+ * the dispatch/lane fields — the strong-idempotency path must fail closed
+ * rather than silently degrade to a best-effort write.
+ */
+export class LaneContextError extends Error {
+}
+/**
+ * Look up the dispatch lane context for a send target under the
+ * PRLL_CONTEXT_DIR contract. Returns null when the contract is not in effect
+ * (env unset) or no lane file exists for this exact (target, thread) — i.e.
+ * a cross-chat / non-dispatch send, which stays on the best-effort path.
+ *
+ * The lane key encodes the full lane identity: a thread send only matches a
+ * thread lane, a channel send only a channel lane.
+ */
+export function resolveLaneDispatchContext(chatId, threadRootId) {
+    const contextDir = process.env.PRLL_CONTEXT_DIR?.trim();
+    if (!contextDir)
+        return null;
+    const targetUri = `prll://${chatId}`;
+    const filePath = laneContextFilePath(contextDir, targetUri, threadRootId);
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf-8').trim();
+    }
+    catch (err) {
+        // Only a genuinely-absent file means "not a dispatch-bound send".
+        // Permission errors etc. must fail closed, not silently degrade the
+        // write out of the ledger.
+        const code = err.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return null;
+        throw new LaneContextError(`Dispatch context for ${targetUri} is unreadable (${filePath}) — retry, or escalate if this persists`);
+    }
+    if (!raw) {
+        throw new LaneContextError(`Dispatch context for ${targetUri} is empty (${filePath}) — retry, or escalate if this persists`);
+    }
+    let ctx;
+    try {
+        ctx = JSON.parse(raw);
+    }
+    catch {
+        throw new LaneContextError(`Dispatch context for ${targetUri} is unreadable (${filePath}) — retry, or escalate if this persists`);
+    }
+    const lane = typeof ctx.lane === 'string' && ctx.lane ? ctx.lane : undefined;
+    if (!lane) {
+        // File exists but the lane fields are missing: fail closed instead of
+        // silently writing a side effect outside the ledger.
+        throw new LaneContextError(`Dispatch context for ${targetUri} is missing its lane binding — retry, or escalate if this persists`);
+    }
+    const dispatchEventId = typeof ctx.dispatch_event_id === 'string' && ctx.dispatch_event_id
+        ? ctx.dispatch_event_id
+        : undefined;
+    if (!dispatchEventId) {
+        // The bridge folds every group member before dispatching (fail-closed
+        // ensureLane), so a lane context without its trigger WorkItem id is
+        // corruption — never a legitimate degraded state.
+        throw new LaneContextError(`Dispatch context for ${targetUri} is missing its dispatch_event_id — retry, or escalate if this persists`);
+    }
+    const replyStatePath = laneReplyStateFilePath(contextDir, targetUri, threadRootId);
+    let replyCommitted = false;
+    try {
+        const sidecar = JSON.parse(fs.readFileSync(replyStatePath, 'utf-8'));
+        // The sidecar only counts for the same trigger — a new turn (new
+        // dispatch_event_id) resets the reply slot.
+        replyCommitted =
+            sidecar.reply_committed === true &&
+                dispatchEventId != null &&
+                sidecar.dispatch_event_id === dispatchEventId;
+    }
+    catch {
+        // No sidecar yet — reply slot unused.
+    }
+    return {
+        lane,
+        dispatchEventId,
+        targetUri,
+        threadRootId,
+        sessionId: typeof ctx.session_id === 'string' && ctx.session_id ? ctx.session_id : undefined,
+        stepId: typeof ctx.step_id === 'string' && ctx.step_id ? ctx.step_id : undefined,
+        replyCommitted,
+        replyStatePath,
+    };
+}
+/**
+ * Record that this lane's first conversational reply has been committed. The
+ * sidecar is CLI-owned — never the bridge-owned context file, which the
+ * bridge rewrites throughout the turn and would clobber inline state.
+ */
+export function markLaneReplyCommitted(laneCtx) {
+    if (!laneCtx.dispatchEventId)
+        return;
+    try {
+        fs.writeFileSync(laneCtx.replyStatePath, JSON.stringify({ dispatch_event_id: laneCtx.dispatchEventId, reply_committed: true }), 'utf-8');
+    }
+    catch {
+        // Best-effort — a lost sidecar means the next send retries the reply key
+        // and the server's effect ledger dedupes it.
+    }
 }
 export function resolveCredentials() {
     const url = process.env.PRLL_API_URL;

package/dist/lib/text-input.d.ts

@@ -0,0 +1,30 @@
+export declare const TEXT_OPTION_DESC = "Message text (shell-safe only for short literals with no $, backtick, or quote)";
+export declare const TEXT_FILE_OPTION_DESC = "Read message text from a file ('-' = stdin) \u2014 shell-safe channel for content with $, backticks, or quotes";
+export declare const NO_BODY_ERROR = "Provide --text, --text-file, --file, or --attachment";
+/**
+ * Resolve message body text from the mutually-exclusive `--text` / `--text-file`
+ * options shared by `messages send` and `dm`.
+ *
+ * Agents build these commands with an LLM and run them through a shell, so any
+ * body passed as a double-quoted `--text "..."` argument is mangled by shell
+ * expansion *before* the CLI ever sees it: `$1,000` becomes `,000`, `$USER`
+ * expands, and `` `cmd` `` / `$(cmd)` execute. Single quotes are no better —
+ * they break on the apostrophes that fill natural-language replies. `--text-file`
+ * sidesteps the shell entirely: the body comes from a file the agent wrote (raw
+ * bytes, no shell) or from stdin via a quoted heredoc (`<<'EOF'`, which disables
+ * all expansion). `-` means stdin.
+ *
+ * A single trailing newline — the structural newline a heredoc or editor appends
+ * — is stripped so a one-line reply doesn't arrive with a dangling blank line;
+ * this mirrors how `$(...)` command substitution trims trailing newlines, and
+ * leading/interior whitespace is preserved untouched.
+ *
+ * Returns `undefined` when neither option is set (preserving the old
+ * `opts.text`-or-nothing contract). Throws on conflicting options or an
+ * unreadable file; callers already funnel that into `printError`.
+ */
+export declare function resolveMessageText(opts: {
+    text?: string;
+    textFile?: string;
+}): string | undefined;
+//# sourceMappingURL=text-input.d.ts.map

package/dist/lib/text-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-input.d.ts","sourceRoot":"","sources":["../../src/lib/text-input.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,gBAAgB,oFACsD,CAAC;AACpF,eAAO,MAAM,qBAAqB,mHAC2E,CAAC;AAC9G,eAAO,MAAM,aAAa,yDAAyD,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,GAAG,SAAS,CA8BjG"}

package/dist/lib/text-input.js

@@ -0,0 +1,61 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+// Shared option help + validation copy for the message-body flags, so
+// `messages send` and `dm` stay in lockstep. commander's --help prints these
+// verbatim (no markdown), so keep them backtick-free.
+export const TEXT_OPTION_DESC = 'Message text (shell-safe only for short literals with no $, backtick, or quote)';
+export const TEXT_FILE_OPTION_DESC = "Read message text from a file ('-' = stdin) — shell-safe channel for content with $, backticks, or quotes";
+export const NO_BODY_ERROR = 'Provide --text, --text-file, --file, or --attachment';
+/**
+ * Resolve message body text from the mutually-exclusive `--text` / `--text-file`
+ * options shared by `messages send` and `dm`.
+ *
+ * Agents build these commands with an LLM and run them through a shell, so any
+ * body passed as a double-quoted `--text "..."` argument is mangled by shell
+ * expansion *before* the CLI ever sees it: `$1,000` becomes `,000`, `$USER`
+ * expands, and `` `cmd` `` / `$(cmd)` execute. Single quotes are no better —
+ * they break on the apostrophes that fill natural-language replies. `--text-file`
+ * sidesteps the shell entirely: the body comes from a file the agent wrote (raw
+ * bytes, no shell) or from stdin via a quoted heredoc (`<<'EOF'`, which disables
+ * all expansion). `-` means stdin.
+ *
+ * A single trailing newline — the structural newline a heredoc or editor appends
+ * — is stripped so a one-line reply doesn't arrive with a dangling blank line;
+ * this mirrors how `$(...)` command substitution trims trailing newlines, and
+ * leading/interior whitespace is preserved untouched.
+ *
+ * Returns `undefined` when neither option is set (preserving the old
+ * `opts.text`-or-nothing contract). Throws on conflicting options or an
+ * unreadable file; callers already funnel that into `printError`.
+ */
+export function resolveMessageText(opts) {
+    if (opts.text !== undefined && opts.textFile !== undefined) {
+        throw new Error('--text and --text-file are mutually exclusive');
+    }
+    if (opts.textFile === undefined)
+        return opts.text;
+    let raw;
+    if (opts.textFile === '-') {
+        // fd 0 = stdin; readFileSync drains a heredoc / pipe synchronously. Guard
+        // the interactive case — reading a TTY would block until EOF (which an
+        // agent never sends), hanging the dispatch until its deadline.
+        if (process.stdin.isTTY) {
+            throw new Error("--text-file - reads the body from stdin; pipe it in (e.g. a quoted heredoc `<<'EOF'`), don't run it interactively");
+        }
+        raw = fs.readFileSync(0, 'utf-8');
+    }
+    else {
+        const resolved = path.resolve(opts.textFile);
+        try {
+            raw = fs.readFileSync(resolved, 'utf-8');
+        }
+        catch (err) {
+            // Surface the underlying reason (missing / no permission / is-a-directory)
+            // so the agent can self-correct — printError renders only `.message` — and
+            // keep the original error as `cause` for anything that inspects it.
+            const reason = err instanceof Error ? err.message : String(err);
+            throw new Error(`Cannot read --text-file ${opts.textFile}: ${reason}`, { cause: err });
+        }
+    }
+    return raw.replace(/\r?\n$/, '');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/cli",
-  "version": "1.36.1",
+  "version": "1.38.0",
   "description": "CLI client for Parall — universal agent & human access to Parall API",
   "license": "MIT",
   "repository": {
@@ -36,13 +36,14 @@
     "diff": "^8.0.3",
     "js-yaml": "^4.1.0",
     "zod": "^4.3.6",
-    "@parall/sdk": "1.36.1"
+    "@parall/agent-core": "1.38.0",
+    "@parall/sdk": "1.38.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0",
-    "@parall/agent-core": "1.36.1"
+    "@parall/agent-core": "1.38.0"
   },
   "scripts": {
     "build": "tsc",