@myagentroam/marctl 0.10.3 → 0.10.4

package/NOTICE

@@ -9,3 +9,29 @@ Author and licensing contact: aCHAOS (achaosxyz@gmail.com)
 Licensed under MyAgentRoam Enterprise Source-Available License 1.0; see
 ee/LICENSE and LICENSING.md. Independent core and third-party notices remain
 applicable; this attribution does not transfer any contributor's copyright.
+
+Third-party supplement: http_ece@1.2.0 (Web Push encryption dependency)
+The npm archive omits its license file; the upstream v1.2.0 text follows.
+Source: https://github.com/martinthomson/encrypted-content-encoding/blob/0562510a30819f52424724a6fd5504becacd98a1/LICENSE
+
+The MIT License (MIT)
+
+Copyright (c) 2015 Martin Thomson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/marctl",
-  "version": "0.10.3",
+  "version": "0.10.4",
   "description": "MyAgentRoam command-line interface for authorized Node access.",
   "license": "Apache-2.0",
   "type": "module",

package/src/cli.mjs

@@ -4,6 +4,7 @@ import { MarctlError, loadConfig } from './config.mjs';
 import { createTranslator } from './i18n/index.mjs';
 import { runTerminalSession } from './terminal.mjs';
 import { runScp } from './scp.mjs';
+import { parseSessionArgs, runSessionCommand, sessionExitCode } from './sessions.mjs';
 
 export async function main(
   argv = process.argv.slice(2),
@@ -11,14 +12,16 @@ export async function main(
     env = process.env,
     stdout = process.stdout,
     stderr = process.stderr,
+    stdin = process.stdin,
     program = 'marctl',
     client,
     WebSocketClass
   } = {}
 ) {
   const translate = createTranslator(env);
+  let args;
   try {
-    const args = parseArgs(argv, translate);
+    args = parseArgs(argv, translate);
     if (args.help) {
       writeLine(
         stdout,
@@ -56,6 +59,18 @@ export async function main(
       }
       return 0;
     }
+    if (args.command === 'sessions') {
+      const result = await runSessionCommand({
+        args,
+        client: marctlClient,
+        env,
+        stdin,
+        WebSocketClass,
+        translate
+      });
+      writeLine(stdout, JSON.stringify(result, null, args.json ? undefined : 2));
+      return 0;
+    }
     if (args.command === 'scp') {
       const socketClass = WebSocketClass ?? (await import('ws')).default;
       return await runScp({
@@ -82,6 +97,22 @@ export async function main(
       translate
     });
   } catch (error) {
+    if (argv[0] === 'sessions') {
+      const failure = {
+        code: error.code ?? 'MARCTL_COMMAND_FAILED',
+        message: error instanceof MarctlError ? error.message : translate('errors.commandFailed'),
+        ...(error.requestId === undefined ? {} : { requestId: error.requestId }),
+        ...(error.upstreamRequestId === undefined
+          ? {}
+          : { upstreamRequestId: error.upstreamRequestId }),
+        ...(error.details === undefined ? {} : { details: error.details }),
+        ...(error.clientMessageId === undefined ? {} : { clientMessageId: error.clientMessageId })
+      };
+      if (args?.json === true || (args === undefined && argv.includes('--json')))
+        writeLine(stdout, JSON.stringify({ error: failure }));
+      else writeLine(stderr, program + ': ' + failure.message + ' [' + failure.code + ']');
+      return sessionExitCode(error);
+    }
     writeLine(
       stderr,
       `${program}: ${error instanceof MarctlError ? error.message : translate('errors.commandFailed')}`
@@ -110,6 +141,7 @@ export function executableArgs(executable, args) {
 }
 
 export function parseArgs(argv, translate = createTranslator()) {
+  if (argv[0] === 'sessions') return parseSessionArgs(argv.slice(1), translate);
   let command;
   let nodeId;
   const remoteArgs = [];
@@ -141,6 +173,7 @@ export function parseArgs(argv, translate = createTranslator()) {
         argument !== 'nodes' &&
         argument !== 'ssh' &&
         argument !== 'scp' &&
+        argument !== 'sessions' &&
         argument !== 'version'
       )
         throw unsupportedSshOption(argument, translate);

package/src/client.mjs

@@ -49,6 +49,19 @@ export class MarctlClient {
     });
   }
 
+  async sessionCommand(body) {
+    const result = await this.#requestJson('/api/marctl/sessions', {
+      method: 'POST',
+      body,
+      preserveError: true
+    });
+    if (!isRecord(result))
+      throw new MarctlError(this.#translate('errors.serverInvalidJson'), {
+        code: 'MARCTL_RESPONSE_INVALID'
+      });
+    return result;
+  }
+
   async createTerminal({ nodeId, rows, cols, command, binary = false }) {
     validateNodeId(nodeId, this.#translate);
     validateDimensions(rows, cols, this.#translate);
@@ -158,7 +171,7 @@ export class MarctlClient {
     return this.#request(pathname, { ...options, json: true });
   }
 
-  async #request(pathname, { method = 'GET', body, json = false } = {}) {
+  async #request(pathname, { method = 'GET', body, json = false, preserveError = false } = {}) {
     const headers = {
       Accept: 'application/json',
       Authorization: `Bearer ${this.#key}`
@@ -173,7 +186,35 @@ export class MarctlClient {
     const timer = setTimeout(() => controller.abort(), this.#requestTimeoutMs);
     try {
       const response = await this.#fetch(new URL(pathname, `${this.#serverUrl}/`), request);
-      if (!response?.ok) throw new MarctlError(this.#translate('errors.serverRejected'));
+      if (!response?.ok) {
+        if (preserveError) {
+          const payload = await response?.json().catch(() => undefined);
+          const failure = payload?.error;
+          if (
+            isRecord(failure) &&
+            typeof failure.code === 'string' &&
+            /^[A-Za-z][A-Za-z0-9_]{0,127}$/u.test(failure.code) &&
+            typeof failure.message === 'string'
+          ) {
+            throw new MarctlError(failure.message.slice(0, 2000), {
+              code: failure.code,
+              statusCode: response.status,
+              requestId:
+                typeof failure.requestId === 'string' ? failure.requestId.slice(0, 160) : undefined,
+              upstreamRequestId:
+                typeof failure.upstreamRequestId === 'string'
+                  ? failure.upstreamRequestId.slice(0, 160)
+                  : undefined,
+              details:
+                typeof failure.details === 'string' ? failure.details.slice(0, 4000) : undefined
+            });
+          }
+        }
+        throw new MarctlError(this.#translate('errors.serverRejected'), {
+          code: 'MARCTL_SERVER_REJECTED',
+          statusCode: response?.status
+        });
+      }
       if (!json) return response;
       try {
         return await response.json();
@@ -181,7 +222,8 @@ export class MarctlClient {
         throw new MarctlError(
           this.#translate(
             controller.signal.aborted ? 'errors.serverTimeout' : 'errors.serverInvalidJson'
-          )
+          ),
+          { code: controller.signal.aborted ? 'MARCTL_REQUEST_TIMEOUT' : 'MARCTL_RESPONSE_INVALID' }
         );
       }
     } catch (error) {
@@ -189,7 +231,8 @@ export class MarctlClient {
       throw new MarctlError(
         this.#translate(
           controller.signal.aborted ? 'errors.serverTimeout' : 'errors.serverUnreachable'
-        )
+        ),
+        { code: controller.signal.aborted ? 'MARCTL_REQUEST_TIMEOUT' : 'MARCTL_SERVER_UNREACHABLE' }
       );
     } finally {
       clearTimeout(timer);

package/src/config.mjs

@@ -4,6 +4,11 @@ export class MarctlError extends Error {
   constructor(message, options = {}) {
     super(message, options);
     this.name = 'MarctlError';
+    this.code = options.code;
+    this.requestId = options.requestId;
+    this.upstreamRequestId = options.upstreamRequestId;
+    this.details = options.details;
+    this.statusCode = options.statusCode;
   }
 }
 
@@ -16,7 +21,10 @@ export async function loadConfig({ env = process.env, translate = createTranslat
     token === undefined ||
     !/^marctl_user_[A-Za-z0-9_-]{43}$/u.test(token)
   )
-    throw new MarctlError(translate('errors.userContextUnavailable'));
+    throw new MarctlError(translate('errors.userContextUnavailable'), {
+      code: 'UNAUTHENTICATED',
+      statusCode: 401
+    });
   return Object.freeze({ serverUrl: validateServerUrl(serverUrl, translate), key: token });
 }
 

package/src/i18n/en-US.mjs

@@ -11,6 +11,7 @@ Usage:
   marctl help [command]
 
 Commands:
+  sessions Inspect and coordinate Sessions in the current Workspace.
   nodes    List accessible Nodes and their connection status.
   ssh      Open a Node terminal or execute a remote command.
   scp      Copy a regular file between this machine and Nodes, or between Nodes.
@@ -41,6 +42,8 @@ Notes:
   Each alias shows only its own command help. Use marctl help <command> for details.
   Remote access uses authorized Node Terminal transport, not system SSH or SCP.`,
   commandHelp: Object.freeze({
+    sessions:
+      '{program} — Coordinate Sessions in the current MAR Workspace\n\nUsage:\n  {program} current [--json]\n  {program} list [--cursor <cursor>] [--limit <1..100>] [--json]\n  {program} show <session-id> [--json]\n  {program} history <session-id> [--cursor <cursor>] [--limit <1..100>] [--json]\n  {program} start --runner <runner> [-m <text> | --message-file <file|->] [--image <path> ...] [--model <id>] [--title <name>] [--client-message-id <id>] [--json]\n  {program} send <session-id> [-m <text> | --message-file <file|->] [--image <path> ...] [--delivery send|queue|replace-current] [--client-message-id <id>] [--json]\n  {program} stop <session-id> [--run <run-id>] [--json]\n  {program} goal get|clear <session-id> [--json]\n  {program} goal set <session-id> (-m <text> | --message-file <file|->) [--json]\n  {program} wait <session-id> --run <run-id> --timeout <30s|5m> [--json]\n\nRunners: mar-agent, codex, claude-code, opencode; actual capabilities apply.\n-m / --message supplies text; it is mutually exclusive with --message-file.\nFiles use UTF-8; - reads stdin. Repeat --image for PNG/JPEG/GIF/WebP files.\nStart/send allow image-only input: up to 5 images, 5 MiB each, 10 MiB total.\nGoal set accepts text only. Start/send return a clientMessageId.\nCredentials expire 24 hours after issue without automatic renewal. Scope is bound\nby MAR to the current Node/Workspace; there are no scope override options.\nSend defaults to non-interrupting delivery. Queued runId may identify another\nactive input: correlate queueItemId/clientMessageId with visible history.\nWait observes the specified Run through Watch. Timeout does not stop it;\nRun success is not proof of task success. Completion never wakes a Coordinator.\nOn an unknown delivery outcome, inspect state/history; do not blindly resend.\nCreate workers as needed, e.g. --title "fixer#42 Handle empty totals" or\n--title "reviewer#42 Review empty totals". Titles are not routing identities;\nrecord returned Session IDs. Put task/role instructions in the first message.\nSessions share files and the Git index; no automatic worktree or worker pool.\n\nExit codes: 1 failure, 2 input, 3 authorization, 4 unsupported, 5 timeout,\n6 unknown outcome, 130 cancelled wait. --json prints one result/error object.',
     nodes: `{program} — List accessible Nodes
 
 Usage:
@@ -148,6 +151,16 @@ or Server connection is required.`
   connected: 'connected',
   disconnected: 'disconnected',
   errors: Object.freeze({
+    sessionOutcomeUnknown:
+      'The delivery outcome is unknown. Inspect Session state/history before retrying.',
+    sessionMessageInvalid:
+      'The message must be non-empty and within the length limit; input files must be readable UTF-8.',
+    sessionImageInvalid:
+      'Images must be readable PNG, JPEG, GIF or WebP files: at most 5 images, 5 MiB each and 10 MiB total.',
+    sessionWaitUnknown: 'The specified Run could not be confirmed. Inspect Session state/history.',
+    sessionWaitCancelled: 'Waiting was cancelled; the target Run was not stopped.',
+    sessionWaitTimeout: 'Waiting timed out; the target Run was not stopped.',
+
     userContextUnavailable: 'This Node session has no valid marctl user authorization.',
     serverUrlInvalid: 'MAR_CTL_SERVER_URL is invalid.',
     serverUrlTransport: 'MAR_CTL_SERVER_URL must use HTTPS or loopback HTTP.',

package/src/i18n/zh-CN.mjs

@@ -10,6 +10,7 @@ export default Object.freeze({
   marctl help [子命令]
 
 子命令：
+  sessions 查看和协调当前工作区中的会话。
   nodes    列出有权限的节点及连接状态。
   ssh      打开节点终端或执行远程命令。
   scp      在当前机器与节点之间、节点之间复制普通文件。
@@ -40,6 +41,8 @@ ${configurationHelp}
   快捷命令仅显示对应操作的帮助。用 marctl help <子命令> 查看详细说明。
   远程访问使用授权的 Node Terminal 传输，不是系统 SSH 或 SCP 协议。`,
   commandHelp: Object.freeze({
+    sessions:
+      '{program} — 协调当前 MAR 工作区中的会话\n\n用法：\n  {program} current [--json]\n  {program} list [--cursor <cursor>] [--limit <1..100>] [--json]\n  {program} show <session-id> [--json]\n  {program} history <session-id> [--cursor <cursor>] [--limit <1..100>] [--json]\n  {program} start --runner <runner> [-m <text> | --message-file <file|->] [--image <path> ...] [--model <id>] [--title <name>] [--client-message-id <id>] [--json]\n  {program} send <session-id> [-m <text> | --message-file <file|->] [--image <path> ...] [--delivery send|queue|replace-current] [--client-message-id <id>] [--json]\n  {program} stop <session-id> [--run <run-id>] [--json]\n  {program} goal get|clear <session-id> [--json]\n  {program} goal set <session-id> (-m <text> | --message-file <file|->) [--json]\n  {program} wait <session-id> --run <run-id> --timeout <30s|5m> [--json]\n\nRunner：mar-agent、codex、claude-code、opencode，操作以实际能力为准。\n-m / --message 直接传文本，与 --message-file 互斥；文件用 UTF-8，- 从 stdin 读取。\nstart/send 可重复 --image 传 PNG/JPEG/GIF/WebP 图片，也可只发送图片。\n最多 5 张，单张 5 MiB、合计 10 MiB；goal set 只接受文本。\nstart/send 返回 clientMessageId。\n凭据自签发起 24 小时到期，不自动续签。MAR 绑定当前 Node/Workspace，\n不提供覆盖范围的参数。send 默认不打断；排队回执的 runId 可能属于\n其他活动输入，需按 queueItemId/clientMessageId 与可见历史核对。\nwait 通过 Watch 等待指定 Run；超时不会停止任务，Run 成功不等于业务完成。\nWorker 完成不自动唤醒 Coordinator。投递结果未知时先查状态/历史，不盲目重发。\n按任务需要创建会话，例如 --title "fixer#42 Handle empty totals" 或\n--title "reviewer#42 Review empty totals"；标题不是寻址身份，保存返回的会话 ID。\n角色和任务要求放入首条普通消息。会话共享文件与 Git 索引，不自动隔离工作目录或维护池。\n\n退出码：1 失败，2 参数，3 授权，4 不支持，5 超时，6 结果未知，130 取消等待。\n--json 只输出一个结果或错误对象。',
     nodes: `{program} — 列出有权限的节点
 
 用法：
@@ -142,6 +145,14 @@ ${configurationHelp}`,
   connected: '在线',
   disconnected: '离线',
   errors: Object.freeze({
+    sessionOutcomeUnknown: '投递结果未知，请先查看会话状态和历史，不要盲目重试。',
+    sessionMessageInvalid: '消息不能为空或超过长度限制；输入文件必须是可读取的 UTF-8 文本。',
+    sessionImageInvalid:
+      '图片必须是可读取的 PNG、JPEG、GIF 或 WebP 文件：最多 5 张，单张 5 MiB，合计 10 MiB。',
+    sessionWaitUnknown: '无法确认指定 Run，请查看会话状态和历史。',
+    sessionWaitCancelled: '已取消等待，未停止目标 Run。',
+    sessionWaitTimeout: '等待超时，未停止目标 Run。',
+
     userContextUnavailable: '此 Node 会话没有有效的 marctl 用户授权。',
     serverUrlInvalid: 'MAR_CTL_SERVER_URL 无效。',
     serverUrlTransport: 'MAR_CTL_SERVER_URL 必须使用 HTTPS 或回环 HTTP。',

package/src/sessions.mjs

@@ -0,0 +1,386 @@
+import { randomUUID } from 'node:crypto';
+import { open } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { MarctlError } from './config.mjs';
+import { createTranslator } from './i18n/index.mjs';
+
+const terminal = new Set(['SUCCEEDED', 'FAILED', 'CANCELLED', 'INTERRUPTED']);
+const commands = {
+  current: [],
+  list: ['cursor', 'limit'],
+  show: [],
+  history: ['cursor', 'limit'],
+  start: ['runner', 'model', 'title', 'message', 'message-file', 'image', 'client-message-id'],
+  send: ['message', 'message-file', 'image', 'delivery', 'client-message-id'],
+  stop: ['run'],
+  'goal.get': [],
+  'goal.set': ['message', 'message-file'],
+  'goal.clear': [],
+  wait: ['run', 'timeout']
+};
+const fieldNames = {
+  'message-file': 'messageFile',
+  'client-message-id': 'clientMessageId',
+  run: 'runId',
+  timeout: 'timeoutMs',
+  image: 'images'
+};
+
+export function parseSessionArgs(argv, translate = createTranslator()) {
+  const invalid = () =>
+    new MarctlError(translate('errors.invalidArguments'), { code: 'MARCTL_SESSION_INPUT_INVALID' });
+  if (
+    argv.length === 0 ||
+    argv.some(
+      (value, index) =>
+        (value === '--help' || value === '-h') && !['-m', '--message'].includes(argv[index - 1])
+    )
+  )
+    return { command: 'sessions', help: true };
+  const input = [...argv];
+  let action = input.shift();
+  if (action === 'goal') action += '.' + input.shift();
+  if (!Object.hasOwn(commands, action)) throw invalid();
+  const args = { command: 'sessions', action };
+  if (!['current', 'list', 'start'].includes(action)) {
+    const sessionId = input.shift();
+    if (!sessionId || sessionId.startsWith('-') || sessionId.length > 512) throw invalid();
+    args.sessionId = sessionId;
+  }
+  while (input.length > 0) {
+    const rawFlag = input.shift();
+    const flag = rawFlag === '-m' ? '--message' : rawFlag;
+    if (flag === '--json' && args.json === undefined) {
+      args.json = true;
+      continue;
+    }
+    const name = flag.startsWith('--') ? flag.slice(2) : '';
+    const key = fieldNames[name] ?? name;
+    if (!commands[action].includes(name) || (name !== 'image' && Object.hasOwn(args, key)))
+      throw invalid();
+    const value = input.shift();
+    if (value === undefined || value === '' || (name !== 'message' && value.startsWith('--')))
+      throw invalid();
+    if (name === 'image') {
+      (args.images ??= []).push(value);
+      if (args.images.length > 5) throw invalid();
+    } else if (name === 'limit') {
+      if (!/^[1-9][0-9]*$/u.test(value) || Number(value) > 100) throw invalid();
+      args[key] = Number(value);
+    } else if (name === 'timeout') {
+      const match = /^([1-9][0-9]*)(ms|s|m)$/u.exec(value);
+      const ms = match === null ? 0 : Number(match[1]) * { ms: 1, s: 1000, m: 60000 }[match[2]];
+      if (!Number.isSafeInteger(ms) || ms < 1 || ms > 3600000) throw invalid();
+      args[key] = ms;
+    } else args[key] = value;
+  }
+  if (args.message !== undefined && args.messageFile !== undefined) throw invalid();
+  if (
+    ['start', 'send', 'goal.set'].includes(action) &&
+    args.messageFile === undefined &&
+    args.message === undefined &&
+    !args.images?.length
+  )
+    throw invalid();
+  if (
+    action === 'start' &&
+    !['mar-agent', 'codex', 'claude-code', 'opencode'].includes(args.runner)
+  )
+    throw invalid();
+  if (action === 'wait' && (args.runId === undefined || args.timeoutMs === undefined))
+    throw invalid();
+  if (args.delivery !== undefined && !['send', 'queue', 'replace-current'].includes(args.delivery))
+    throw invalid();
+  if (args.title !== undefined && args.title.length > 160) throw invalid();
+  return args;
+}
+
+export async function runSessionCommand({ args, client, env, stdin, WebSocketClass, translate }) {
+  if (args.action === 'wait') {
+    const controller = new AbortController();
+    const cancel = () => controller.abort();
+    process.once('SIGINT', cancel);
+    process.once('SIGTERM', cancel);
+    try {
+      return await waitForSessionRun({
+        client,
+        sessionId: args.sessionId,
+        runId: args.runId,
+        timeoutMs: args.timeoutMs,
+        WebSocketClass,
+        translate,
+        signal: controller.signal
+      });
+    } finally {
+      process.off('SIGINT', cancel);
+      process.off('SIGTERM', cancel);
+    }
+  }
+  const body = { action: args.action };
+  for (const name of ['sessionId', 'runner', 'model', 'title', 'cursor', 'limit', 'runId'])
+    if (args[name] !== undefined) body[name] = args[name];
+  if (args.action === 'current' && env.MAR_CTL_SESSION_ID) body.sessionId = env.MAR_CTL_SESSION_ID;
+  if (args.messageFile !== undefined || args.message !== undefined)
+    body.content = await messageContent(
+      args,
+      stdin,
+      args.action === 'goal.set' ? 20000 : 100000,
+      translate
+    );
+  if (args.images !== undefined) {
+    body.attachments = await imageAttachments(args.images, translate);
+    body.content ??= '';
+  }
+  if (args.action === 'start' || args.action === 'send')
+    body.clientMessageId = args.clientMessageId ?? randomUUID();
+  if (args.action === 'send')
+    body.deliveryIntent = { send: 'SEND', queue: 'QUEUE', 'replace-current': 'REPLACE_CURRENT' }[
+      args.delivery ?? 'send'
+    ];
+  try {
+    const result = await client.sessionCommand(body);
+    return {
+      ...result,
+      ...(typeof result?.session?.id === 'string' ? { sessionId: result.session.id } : {}),
+      ...(typeof result?.run?.id === 'string' ? { runId: result.run.id } : {}),
+      ...(body.clientMessageId === undefined ? {} : { clientMessageId: body.clientMessageId })
+    };
+  } catch (error) {
+    if (body.clientMessageId !== undefined) error.clientMessageId = body.clientMessageId;
+    if (
+      ['start', 'send', 'stop', 'goal.set', 'goal.clear'].includes(args.action) &&
+      ['MARCTL_REQUEST_TIMEOUT', 'MARCTL_SERVER_UNREACHABLE', 'MARCTL_RESPONSE_INVALID'].includes(
+        error.code
+      )
+    ) {
+      error.code = 'MARCTL_OUTCOME_UNKNOWN';
+      error.message = translate('errors.sessionOutcomeUnknown');
+    }
+    throw error;
+  }
+}
+
+async function messageContent({ message, messageFile: path }, stdin, limit, translate) {
+  let file;
+  try {
+    let content = message;
+    if (content === undefined) {
+      const input =
+        path === '-'
+          ? stdin
+          : (file = await open(path, 'r')).createReadStream({ autoClose: false });
+      const parts = [];
+      let bytes = 0;
+      for await (const part of input) {
+        const chunk = Buffer.from(part);
+        bytes += chunk.length;
+        if (bytes > limit * 4) throw new Error('MESSAGE_TOO_LONG');
+        parts.push(chunk);
+      }
+      content = new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(parts));
+    }
+    if (content.trim().length === 0 || content.length > limit) throw new Error('MESSAGE_INVALID');
+    return content;
+  } catch {
+    throw new MarctlError(translate('errors.sessionMessageInvalid'), {
+      code: 'MARCTL_SESSION_INPUT_INVALID'
+    });
+  } finally {
+    await file?.close();
+  }
+}
+
+async function imageAttachments(paths, translate) {
+  const attachments = [];
+  let total = 0;
+  for (const path of paths) {
+    let file;
+    try {
+      file = await open(path, 'r');
+      const info = await file.stat();
+      if (!info.isFile() || info.size === 0 || info.size > 5 * 1024 * 1024)
+        throw new Error('IMAGE_INVALID');
+      const parts = [];
+      let size = 0;
+      for await (const part of file.createReadStream({ autoClose: false })) {
+        size += part.length;
+        total += part.length;
+        if (size > 5 * 1024 * 1024 || total > 10 * 1024 * 1024) throw new Error('IMAGE_TOO_LARGE');
+        parts.push(part);
+      }
+      const data = Buffer.concat(parts);
+      const mime = imageMime(data);
+      if (mime === undefined) throw new Error('IMAGE_INVALID');
+      attachments.push({ name: basename(path), mime, dataBase64: data.toString('base64') });
+    } catch {
+      throw new MarctlError(translate('errors.sessionImageInvalid'), {
+        code: 'MARCTL_SESSION_INPUT_INVALID'
+      });
+    } finally {
+      await file?.close();
+    }
+  }
+  return attachments;
+}
+
+function imageMime(data) {
+  if (data.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex'))) return 'image/png';
+  if (data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) return 'image/jpeg';
+  if (['GIF87a', 'GIF89a'].includes(data.subarray(0, 6).toString('ascii'))) return 'image/gif';
+  if (
+    data.subarray(0, 4).toString('ascii') === 'RIFF' &&
+    data.subarray(8, 12).toString('ascii') === 'WEBP'
+  )
+    return 'image/webp';
+}
+
+/** One CLI-owned Workbench connection and one existing Session Watch, never history polling. */
+export async function waitForSessionRun({
+  client,
+  sessionId,
+  runId,
+  timeoutMs,
+  WebSocketClass,
+  translate = createTranslator(),
+  signal
+}) {
+  const socket = client.openWorkbenchWebSocket(WebSocketClass ?? (await import('ws')).default);
+  const watchId = randomUUID();
+  let connectionId;
+  let renewal;
+  let settled = false;
+  let subscribed = false;
+  let accept;
+  let rejectResult;
+  const result = new Promise((resolve, fail) => {
+    accept = resolve;
+    rejectResult = fail;
+  });
+  const reject = (error) => {
+    if (settled) return;
+    settled = true;
+    rejectResult(error);
+  };
+  const fail = (code, key, options = {}) =>
+    reject(new MarctlError(translate(key), { ...options, code }));
+  const command = (mode) =>
+    client.sessionCommand({
+      action: 'watch',
+      sessionId,
+      workbenchConnectionId: connectionId,
+      watchId,
+      mode
+    });
+  const scheduleRenewal = (expiresAt) => {
+    clearTimeout(renewal);
+    const remaining = expiresAt - Date.now();
+    if (!Number.isFinite(remaining) || remaining <= 0) {
+      fail('MARCTL_WAIT_UNKNOWN', 'errors.sessionWaitUnknown');
+      return;
+    }
+    renewal = setTimeout(
+      () => {
+        command('renew')
+          .then((ack) => {
+            if (!settled) scheduleRenewal(ack?.expiresAt);
+          })
+          .catch((error) => {
+            if ([401, 403].includes(error.statusCode)) reject(error);
+            else fail('MARCTL_WAIT_UNKNOWN', 'errors.sessionWaitUnknown');
+          });
+      },
+      Math.max(50, Math.floor(remaining / 2))
+    );
+  };
+  const check = (run) => {
+    if (run?.id === runId && run.sessionId === sessionId && terminal.has(run.status) && !settled) {
+      settled = true;
+      accept({ run });
+    }
+  };
+  const onMessage = (raw) => {
+    if (settled) return;
+    let message;
+    try {
+      message = JSON.parse(String(raw));
+    } catch {
+      return;
+    }
+    if (message?.type === 'watch.event') message = message.event;
+    if (!message || typeof message !== 'object') return;
+    if (
+      message.type === 'workbench.ready' &&
+      connectionId === undefined &&
+      typeof message.workbenchConnectionId === 'string'
+    ) {
+      connectionId = message.workbenchConnectionId;
+      subscribed = true;
+      command('initial').catch(reject);
+    }
+    if (message.watchId !== watchId) return;
+    if (message.type === 'watch.failed') {
+      fail('MARCTL_WAIT_UNKNOWN', 'errors.sessionWaitUnknown');
+      return;
+    }
+    if (message.type === 'watch.session.snapshot') {
+      const runs = message.payload?.runs;
+      if (!Array.isArray(runs)) {
+        fail('MARCTL_WAIT_UNKNOWN', 'errors.sessionWaitUnknown');
+        return;
+      }
+      const run = runs.find((value) => value.id === runId && value.sessionId === sessionId);
+      if (run === undefined) {
+        fail('MARCTL_WAIT_UNKNOWN', 'errors.sessionWaitUnknown');
+        return;
+      }
+      check(run);
+    } else if (message.type === 'watch.session.event') check(message.event?.payload?.run);
+    if (!settled && message.expiresAt !== undefined) scheduleRenewal(message.expiresAt);
+  };
+  const onClose = (code, reason) => {
+    if (code === 1008 && String(reason) === 'UNAUTHENTICATED')
+      fail('UNAUTHENTICATED', 'errors.userContextUnavailable', { statusCode: 401 });
+    else fail('MARCTL_WAIT_UNKNOWN', 'errors.sessionWaitUnknown');
+  };
+  const onOpen = () => {
+    try {
+      socket.send(JSON.stringify({ type: 'resume' }));
+    } catch {
+      onClose();
+    }
+  };
+  const onAbort = () => fail('MARCTL_WAIT_CANCELLED', 'errors.sessionWaitCancelled');
+  const timer = setTimeout(
+    () => fail('MARCTL_WAIT_TIMEOUT', 'errors.sessionWaitTimeout'),
+    timeoutMs
+  );
+  socket.on('open', onOpen);
+  socket.on('message', onMessage);
+  socket.on('error', onClose);
+  socket.on('close', onClose);
+  signal?.addEventListener('abort', onAbort, { once: true });
+  if (signal?.aborted) onAbort();
+  try {
+    return await result;
+  } finally {
+    settled = true;
+    clearTimeout(timer);
+    clearTimeout(renewal);
+    signal?.removeEventListener('abort', onAbort);
+    if (subscribed) await command('stop').catch(() => undefined);
+    socket.off('open', onOpen);
+    socket.off('message', onMessage);
+    socket.off('close', onClose);
+    socket.close();
+  }
+}
+
+export function sessionExitCode(error) {
+  if (error.code === 'MARCTL_SESSION_INPUT_INVALID') return 2;
+  if ([401, 403].includes(error.statusCode)) return 3;
+  if (error.code?.includes('UNSUPPORTED')) return 4;
+  if (error.code === 'MARCTL_WAIT_TIMEOUT' || error.code === 'MARCTL_REQUEST_TIMEOUT') return 5;
+  if (['MARCTL_OUTCOME_UNKNOWN', 'MARCTL_WAIT_UNKNOWN'].includes(error.code)) return 6;
+  if (error.code === 'MARCTL_WAIT_CANCELLED') return 130;
+  return 1;
+}