@myagentroam/marctl 0.10.2 → 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.2",
+  "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,
@@ -38,7 +41,7 @@ export async function main(
       return 0;
     }
 
-    const config = await loadConfig({ env, envFile: args.envFile, translate });
+    const config = await loadConfig({ env, translate });
     const marctlClient = client ?? new MarctlClient({ ...config, translate });
     if (args.command === 'nodes') {
       const nodes = await marctlClient.listNodes();
@@ -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,7 +141,7 @@ export function executableArgs(executable, args) {
 }
 
 export function parseArgs(argv, translate = createTranslator()) {
-  let envFile;
+  if (argv[0] === 'sessions') return parseSessionArgs(argv.slice(1), translate);
   let command;
   let nodeId;
   const remoteArgs = [];
@@ -133,18 +164,6 @@ export function parseArgs(argv, translate = createTranslator()) {
       version = true;
       continue;
     }
-    if (!separator && argument === '--env-file') {
-      envFile = argv[index + 1];
-      if (!envFile || envFile.startsWith('-'))
-        throw new MarctlError(translate('errors.envFileValueRequired'));
-      index += 1;
-      continue;
-    }
-    if (!separator && argument.startsWith('--env-file=')) {
-      envFile = argument.slice('--env-file='.length);
-      if (!envFile) throw new MarctlError(translate('errors.envFileValueRequired'));
-      continue;
-    }
     if (!separator && argument === '--') {
       separator = true;
       continue;
@@ -154,6 +173,7 @@ export function parseArgs(argv, translate = createTranslator()) {
         argument !== 'nodes' &&
         argument !== 'ssh' &&
         argument !== 'scp' &&
+        argument !== 'sessions' &&
         argument !== 'version'
       )
         throw unsupportedSshOption(argument, translate);
@@ -186,12 +206,10 @@ export function parseArgs(argv, translate = createTranslator()) {
 
   if (help) return { help: true, ...(command === undefined ? {} : { command }) };
   if (version || command === 'version') return { version: true };
-  if (command === 'nodes' && nodeId === undefined && remoteArgs.length === 0)
-    return { command, ...(envFile === undefined ? {} : { envFile }) };
+  if (command === 'nodes' && nodeId === undefined && remoteArgs.length === 0) return { command };
   if (command === 'scp' && nodeId !== undefined && remoteArgs.length === 1)
     return {
       command,
-      ...(envFile === undefined ? {} : { envFile }),
       source: nodeId,
       destination: remoteArgs[0],
       preserve
@@ -199,7 +217,6 @@ export function parseArgs(argv, translate = createTranslator()) {
   if (command === 'ssh' && nodeId !== undefined && nodeId !== '')
     return {
       command,
-      ...(envFile === undefined ? {} : { envFile }),
       nodeId,
       ...(remoteArgs.length === 0
         ? {}

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

@@ -1,67 +1,31 @@
-import { lstat, readFile } from 'node:fs/promises';
-import os from 'node:os';
-import path from 'node:path';
 import { createTranslator } from './i18n/index.mjs';
 
-export const CONFIG_KEYS = Object.freeze(['MAR_CTL_SERVER_URL', 'MAR_CTL_KEY']);
-
 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;
   }
 }
 
-export function defaultConfigPath({
-  env = process.env,
-  platform = process.platform,
-  homeDirectory = os.homedir()
-} = {}) {
-  const configuredHome =
-    nonEmptyString(env.HOME) ??
-    (platform === 'win32' ? nonEmptyString(env.USERPROFILE) : undefined) ??
-    homeDirectory;
-  return path.join(configuredHome, '.marctl', 'default.env');
-}
-
-export async function loadConfig({
-  env = process.env,
-  envFile,
-  platform = process.platform,
-  homeDirectory = os.homedir(),
-  translate = createTranslator(env)
-} = {}) {
-  if (env.MAR_CTL_CONTEXT_REQUIRED === '1') {
-    const serverUrl = nonEmptyString(env.MAR_CTL_SERVER_URL);
-    const token = nonEmptyString(env.MAR_CTL_USER_TOKEN);
-    if (
-      serverUrl === undefined ||
-      token === undefined ||
-      !/^marctl_user_[A-Za-z0-9_-]{43}$/u.test(token)
-    )
-      throw new MarctlError(translate('errors.userContextUnavailable'));
-    return Object.freeze({
-      serverUrl: validateServerUrl(serverUrl, translate),
-      key: token
+export async function loadConfig({ env = process.env, translate = createTranslator(env) } = {}) {
+  const serverUrl = nonEmptyString(env.MAR_CTL_SERVER_URL);
+  const token = nonEmptyString(env.MAR_CTL_USER_TOKEN);
+  if (
+    env.MAR_CTL_CONTEXT_REQUIRED !== '1' ||
+    serverUrl === undefined ||
+    token === undefined ||
+    !/^marctl_user_[A-Za-z0-9_-]{43}$/u.test(token)
+  )
+    throw new MarctlError(translate('errors.userContextUnavailable'), {
+      code: 'UNAUTHENTICATED',
+      statusCode: 401
     });
-  }
-  const configPath = envFile ?? defaultConfigPath({ env, platform, homeDirectory });
-  const values = await readConfigFile(configPath, { platform, translate });
-
-  const serverUrlValue = nonEmptyString(values.MAR_CTL_SERVER_URL);
-  if (serverUrlValue === undefined)
-    throw new MarctlError(translate('errors.configServerUrlMissing'));
-
-  const keyValue = nonEmptyString(values.MAR_CTL_KEY);
-  if (keyValue === undefined) throw new MarctlError(translate('errors.configKeyMissing'));
-  // eslint-disable-next-line no-control-regex -- Reject control characters explicitly at the input boundary.
-  if (/[\u0000-\u001f\u007f]/u.test(keyValue))
-    throw new MarctlError(translate('errors.configKeyInvalid'));
-
-  return Object.freeze({
-    serverUrl: validateServerUrl(serverUrlValue, translate),
-    key: keyValue
-  });
+  return Object.freeze({ serverUrl: validateServerUrl(serverUrl, translate), key: token });
 }
 
 export function validateServerUrl(value, translate = createTranslator()) {
@@ -86,80 +50,6 @@ export function validateServerUrl(value, translate = createTranslator()) {
   return url.origin;
 }
 
-async function readConfigFile(filePath, { platform, translate }) {
-  let before;
-  try {
-    before = await lstat(filePath);
-  } catch (error) {
-    if (error?.code === 'ENOENT') throw new MarctlError(translate('errors.envFileMissing'));
-    throw new MarctlError(translate('errors.envFileRead'));
-  }
-  assertSecureConfigFile(before, platform, translate);
-
-  let content;
-  try {
-    content = await readFile(filePath, 'utf8');
-  } catch {
-    throw new MarctlError(translate('errors.envFileRead'));
-  }
-
-  let after;
-  try {
-    after = await lstat(filePath);
-  } catch {
-    throw new MarctlError(translate('errors.envFileRead'));
-  }
-  assertSecureConfigFile(after, platform, translate);
-  if (before.dev !== after.dev || before.ino !== after.ino)
-    throw new MarctlError(translate('errors.envFileRead'));
-
-  const values = {};
-  for (const rawLine of content.replace(/^\uFEFF/u, '').split(/\r?\n/u)) {
-    const line = rawLine.trim();
-    if (line === '' || line.startsWith('#')) continue;
-
-    const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/u.exec(line);
-    if (match === null) throw new MarctlError(translate('errors.envFileEntry'));
-
-    const [, name, rawValue] = match;
-    if (!CONFIG_KEYS.includes(name)) throw new MarctlError(translate('errors.envFileUnsupported'));
-    values[name] = parseEnvValue(rawValue, translate);
-  }
-  return values;
-}
-
-function parseEnvValue(rawValue, translate) {
-  const value = rawValue.trim();
-  if (value.startsWith('"') || value.startsWith("'")) {
-    const quote = value[0];
-    if (!value.endsWith(quote) || value.length < 2)
-      throw new MarctlError(translate('errors.envFileQuoted'));
-    const body = value.slice(1, -1);
-    if (quote === "'") return body;
-    return body.replace(/\\(["\\nrt])/gu, (_match, escaped) => {
-      if (escaped === 'n') return '\n';
-      if (escaped === 'r') return '\r';
-      if (escaped === 't') return '\t';
-      return escaped;
-    });
-  }
-  return value;
-}
-
-function assertSecureConfigFile(stats, platform, translate) {
-  if (stats.isSymbolicLink()) throw new MarctlError(translate('errors.envFileSymlink'));
-  if (!stats.isFile()) throw new MarctlError(translate('errors.envFileType'));
-  if (platform === 'win32') return;
-
-  const permissions = stats.mode & 0o7777;
-  const ownerUid = typeof process.getuid === 'function' ? process.getuid() : undefined;
-  if (
-    (ownerUid !== undefined && stats.uid !== ownerUid) ||
-    (permissions !== 0o600 && permissions !== 0o400)
-  )
-    throw new MarctlError(translate('errors.envFilePermissions'));
-}
-
 function nonEmptyString(value) {
   return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
 }

package/src/i18n/en-US.mjs

@@ -1,9 +1,7 @@
-const configurationHelp = `Configuration:
-  MAR-launched terminals and Workspace Agent Runs use the current user's Node permissions;
-  scheduled runs use the task owner. No management key is needed in these contexts.
-  Outside MAR, use ~/.marctl/default.env (%HOME%\\.marctl\\default.env on Windows;
-  the system home directory is used when HOME is unset), or select a file with --env-file.
-  The file must contain MAR_CTL_SERVER_URL and MAR_CTL_KEY. Never pass a key as an argument.`;
+const configurationHelp = `Authorization:
+  Node access is available only in MAR-launched terminals and Workspace Agent Runs;
+  scheduled runs use the task owner. MAR supplies short-lived user credentials.
+  External terminals and persistent administrator keys are not supported.`;
 
 export default Object.freeze({
   help: `marctl — MyAgentRoam command-line interface
@@ -13,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.
@@ -20,7 +19,6 @@ Commands:
   help     Show help for the CLI or a command.
 
 Options:
-  --env-file PATH  Use the specified management configuration file.
   -h, --help       Show help and exit.
   -V, --version    Print the CLI package version and exit.
 
@@ -40,23 +38,23 @@ ${configurationHelp}
 
 Notes:
   Help and version work offline without configuration or authorization.
-  Put local help/version options before a Node or file endpoint; --env-file may also follow a command.
+  Put local help/version options before a Node or file endpoint.
   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:
-  {program} [--env-file PATH] [options]
+  {program} [options]
 
 Options:
-  --env-file PATH  Use the specified management configuration file.
   -h, --help       Show help and exit.
   -V, --version    Print the CLI package version and exit.
 
 Examples:
   {program}
-  {program} --env-file ~/.marctl/production.env
 
 Output:
   Tab-separated columns: ID, NAME, STATUS, PLATFORM.
@@ -66,14 +64,13 @@ ${configurationHelp}`,
     ssh: `{program} — Open a terminal or execute a remote command
 
 Usage:
-  {program} [--env-file PATH] [options] <node> [command [arg...]]
+  {program} [options] <node> [command [arg...]]
 
 Arguments:
   <node>          An authorized Node ID or an exact, unique Node name.
   [command ...]   A command for the remote shell; omit it for an interactive shell.
 
 Options (before <node>):
-  --env-file PATH  Use the specified management configuration file.
   -h, --help       Show help and exit.
   -V, --version    Print the CLI package version and exit.
 
@@ -96,7 +93,7 @@ ${configurationHelp}`,
     scp: `{program} — Copy a regular file
 
 Usage:
-  {program} [--env-file PATH] [options] <source> <destination>
+  {program} [options] <source> <destination>
 
 Arguments:
   <source>        A local file or an authorized Node file endpoint.
@@ -108,7 +105,6 @@ Arguments:
 Options:
   -p              Preserve source permissions and access/modification times.
   -q              Suppress progress output (already the default).
-  --env-file PATH  Use the specified management configuration file.
   -h, --help       Show help and exit; place before the first endpoint.
   -V, --version    Print the CLI package version and exit; place before the first endpoint.
   --              Treat remaining arguments as literal paths.
@@ -155,22 +151,20 @@ 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.',
-    configServerUrlMissing: 'MAR_CTL_SERVER_URL is not configured.',
-    configKeyMissing: 'MAR_CTL_KEY is not configured.',
-    configKeyInvalid: 'MAR_CTL_KEY contains invalid characters.',
     serverUrlInvalid: 'MAR_CTL_SERVER_URL is invalid.',
     serverUrlTransport: 'MAR_CTL_SERVER_URL must use HTTPS or loopback HTTP.',
     serverUrlOrigin: 'MAR_CTL_SERVER_URL must be an origin without credentials or query data.',
-    envFileMissing: 'The requested environment file was not found.',
-    envFileRead: 'The environment file could not be read.',
-    envFileSymlink: 'The environment file must not be a symbolic link. Use chmod 600.',
-    envFileType: 'The environment file must be a regular file. Use chmod 600.',
-    envFilePermissions:
-      'The environment file must be owned by the current user and have mode 0600 or 0400. Use chmod 600.',
-    envFileEntry: 'Invalid environment entry.',
-    envFileUnsupported: 'Unsupported environment variable.',
-    envFileQuoted: 'Invalid quoted environment value.',
     fetchUnavailable: 'Fetch is unavailable in this Node.js runtime.',
     serverInvalidNodes: 'The server returned an invalid node list.',
     serverInvalidManifest: 'The server returned an invalid node manifest.',
@@ -212,7 +206,6 @@ or Server connection is required.`
     terminalDirectUnsafeFallback:
       'Direct terminal setup could not be safely canceled after OPEN; relay fallback was skipped.',
     invalidArguments: 'Invalid command arguments.',
-    envFileValueRequired: 'A value is required for --env-file.',
     sshOptionsUnsupported: 'SSH options are not supported; use marssh <host>.',
     scpOptionsUnsupported: 'This SCP option is not supported by the Node Terminal transport.',
     commandFailed: 'The command failed.'

package/src/i18n/zh-CN.mjs

@@ -1,9 +1,6 @@
-const configurationHelp = `配置：
-  MAR 打开的终端和普通 Workspace Agent Run 使用当前用户的节点权限，定时任务使用任务 owner 的权限；
-  这些上下文无需管理密钥。
-  独立使用时读取 ~/.marctl/default.env（Windows 为 %HOME%\\.marctl\\default.env，
-  HOME 未设置时使用系统主目录），也可用 --env-file 指定文件。
-  文件须包含 MAR_CTL_SERVER_URL 和 MAR_CTL_KEY。不要通过命令参数传递密钥。`;
+const configurationHelp = `授权：
+  仅 MAR 打开的终端和普通 Workspace Agent Run 可访问节点，定时任务使用任务 owner 的权限。
+  MAR 自动提供短期用户凭证；不支持外部终端或持久管理员密钥。`;
 
 export default Object.freeze({
   help: `marctl — MyAgentRoam 命令行工具
@@ -13,6 +10,7 @@ export default Object.freeze({
   marctl help [子命令]
 
 子命令：
+  sessions 查看和协调当前工作区中的会话。
   nodes    列出有权限的节点及连接状态。
   ssh      打开节点终端或执行远程命令。
   scp      在当前机器与节点之间、节点之间复制普通文件。
@@ -20,7 +18,6 @@ export default Object.freeze({
   help     显示工具或指定子命令的帮助。
 
 选项：
-  --env-file PATH  使用指定的管理配置文件。
   -h, --help       显示帮助后退出。
   -V, --version    显示 CLI 包版本后退出。
 
@@ -40,23 +37,23 @@ ${configurationHelp}
 
 说明：
   帮助和版本查询离线可用，无需配置或授权。
-  本机帮助、版本选项须放在节点或文件端点前；--env-file 也可放在子命令后。
+  本机帮助、版本选项须放在节点或文件端点前。
   快捷命令仅显示对应操作的帮助。用 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} — 列出有权限的节点
 
 用法：
-  {program} [--env-file PATH] [选项]
+  {program} [选项]
 
 选项：
-  --env-file PATH  使用指定的管理配置文件。
   -h, --help       显示帮助后退出。
   -V, --version    显示 CLI 包版本后退出。
 
 示例：
   {program}
-  {program} --env-file ~/.marctl/production.env
 
 输出：
   以制表符分隔的节点 ID、名称、状态、平台列。
@@ -66,14 +63,13 @@ ${configurationHelp}`,
     ssh: `{program} — 打开终端或执行远程命令
 
 用法：
-  {program} [--env-file PATH] [选项] <节点> [command [arg...]]
+  {program} [选项] <节点> [command [arg...]]
 
 参数：
   <节点>          有权限的节点 ID，或精确、唯一的节点名称。
   [command ...]   交给远端 Shell 的命令；省略时打开交互 Shell。
 
 选项（放在节点前）：
-  --env-file PATH  使用指定的管理配置文件。
   -h, --help       显示帮助后退出。
   -V, --version    显示 CLI 包版本后退出。
 
@@ -94,7 +90,7 @@ ${configurationHelp}`,
     scp: `{program} — 复制普通文件
 
 用法：
-  {program} [--env-file PATH] [选项] <源> <目标>
+  {program} [选项] <源> <目标>
 
 参数：
   <源>            本机文件或有权限的节点文件端点。
@@ -106,7 +102,6 @@ ${configurationHelp}`,
 选项：
   -p              保留源文件权限及访问、修改时间。
   -q              不显示进度（默认已不显示）。
-  --env-file PATH  使用指定的管理配置文件。
   -h, --help       显示帮助后退出，须放在第一个文件端点前。
   -V, --version    显示 CLI 包版本后退出，须放在第一个文件端点前。
   --              后续参数按字面路径处理。
@@ -150,21 +145,18 @@ ${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 用户授权。',
-    configServerUrlMissing: '未配置 MAR_CTL_SERVER_URL。',
-    configKeyMissing: '未配置 MAR_CTL_KEY。',
-    configKeyInvalid: 'MAR_CTL_KEY 包含无效字符。',
     serverUrlInvalid: 'MAR_CTL_SERVER_URL 无效。',
     serverUrlTransport: 'MAR_CTL_SERVER_URL 必须使用 HTTPS 或回环 HTTP。',
     serverUrlOrigin: 'MAR_CTL_SERVER_URL 必须是不含凭据或查询参数的 Origin。',
-    envFileMissing: '指定的环境文件不存在。',
-    envFileRead: '无法读取环境文件。',
-    envFileSymlink: '环境文件不能是符号链接。请使用 chmod 600。',
-    envFileType: '环境文件必须是普通文件。请使用 chmod 600。',
-    envFilePermissions: '环境文件必须归当前用户所有，权限必须为 0600 或 0400。请使用 chmod 600。',
-    envFileEntry: '环境文件条目无效。',
-    envFileUnsupported: '环境变量不受支持。',
-    envFileQuoted: '带引号的环境变量值无效。',
     fetchUnavailable: '当前 Node.js 运行时没有 Fetch。',
     serverInvalidNodes: 'Server 返回的节点列表无效。',
     serverInvalidManifest: 'Server 返回的节点清单无效。',
@@ -203,7 +195,6 @@ ${configurationHelp}`,
     terminalSessionFailed: '终端会话失败。',
     terminalDirectUnsafeFallback: 'OPEN 后无法安全取消直连终端，已跳过 relay 回退。',
     invalidArguments: '命令参数无效。',
-    envFileValueRequired: '--env-file 必须提供值。',
     sshOptionsUnsupported: '不支持 SSH 选项，请使用 marssh <节点>。',
     scpOptionsUnsupported: 'Node Terminal 传输不支持此 SCP 选项。',
     terminalBinaryUnavailable: '二进制复制需要支持 pipe 终端的 Server 与 Node。',

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;
+}