@myagentroam/marctl 0.11.3 → 0.11.5

package/src/session-args.mjs

@@ -0,0 +1,247 @@
+import { MarctlError } from './errors.mjs';
+import { createTranslator } from './i18n/index.mjs';
+import { sessionTarget } from './session-target.mjs';
+
+const commands = {
+  current: [],
+  list: ['cursor', 'limit', 'query', 'parent', 'scope', 'agent', 'runner'],
+  graph: ['limit'],
+  show: [],
+  view: ['cursor', 'limit', 'history'],
+  history: ['cursor', 'limit'],
+  start: [
+    'runner',
+    'model',
+    'effort',
+    'title',
+    'message',
+    'message-file',
+    'image',
+    'client-message-id',
+    'parent',
+    'goal',
+    'clear-goal'
+  ],
+  config: ['model', 'effort'],
+  rename: ['title'],
+  'prompt.get': [],
+  'prompt.set': ['message', 'message-file'],
+  'prompt.clear': [],
+  'approval.decide': ['run', 'approval', 'decision'],
+  'schedule.list': ['cursor', 'limit'],
+  'schedule.get': [],
+  'schedule.create': ['cron', 'message', 'message-file'],
+  'schedule.update': ['cron', 'message', 'message-file', 'expected-revision'],
+  send: [
+    'message',
+    'message-file',
+    'image',
+    'steer',
+    'queue',
+    'client-message-id',
+    'goal',
+    'clear-goal',
+    'approval',
+    'decision'
+  ],
+  stop: ['execution'],
+  'goal.get': [],
+  'goal.set': ['message', 'message-file'],
+  'goal.clear': [],
+  wait: ['timeout', 'wait-for', 'mode', 'agent', 'run', 'until']
+};
+const fieldNames = {
+  parent: 'parentSessionId',
+  'expected-revision': 'expectedRevision',
+  'message-file': 'messageFile',
+  'client-message-id': 'clientMessageId',
+  run: 'runId',
+  approval: 'approvalId',
+  timeout: 'timeoutMs',
+  execution: 'executionId',
+  'wait-for': 'waitFor',
+  'clear-goal': 'clearGoal',
+  image: 'images'
+};
+
+export function parseSessionArgs(argv, translate = createTranslator()) {
+  const invalid = (key = 'errors.invalidArguments', details) =>
+    new MarctlError(translate(key), {
+      code: 'MARCTL_SESSION_INPUT_INVALID',
+      details:
+        details ??
+        (argv[0] === 'prompt'
+          ? 'Use prompt get|clear [session-id], or prompt set [session-id] with exactly one of -m/--message or --message-file.'
+          : argv[0] === 'approval'
+            ? 'Use approval decide <session-id> --run <run-id> --approval <approval-id> --decision approve|reject.'
+            : undefined)
+    });
+  if (
+    argv.length === 0 ||
+    argv.some(
+      (value, index) =>
+        (value === '--help' || value === '-h') && !['-m', '--message'].includes(argv[index - 1])
+    )
+  )
+    return { command: 'agents', help: true };
+  const input = [...argv];
+  let action = input.shift();
+  if (['goal', 'schedule', 'prompt', 'approval'].includes(action)) action += '.' + input.shift();
+  if (!Object.hasOwn(commands, action)) throw invalid();
+  const args = { command: 'agents', action };
+  if (sessionTarget[action] !== 'workspace') {
+    if (
+      (input[0] === undefined || input[0].startsWith('-')) &&
+      sessionTarget[action] === 'explicit'
+    )
+      throw invalid();
+    if (input[0] !== undefined && !input[0].startsWith('-')) {
+      const sessionId = input.shift();
+      if (!sessionId || 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;
+    }
+    if (action === 'send' && (flag === '--steer' || flag === '--queue')) {
+      const key = flag.slice(2);
+      if (Object.hasOwn(args, key)) throw invalid();
+      args[key] = true;
+      continue;
+    }
+    if (
+      (flag === '--clear-goal' && ['start', 'send'].includes(action)) ||
+      (flag === '--history' && action === 'view')
+    ) {
+      const key = flag === '--history' ? 'history' : 'clearGoal';
+      if (Object.hasOwn(args, key)) throw invalid();
+      args[key] = true;
+      continue;
+    }
+    const name = flag.startsWith('--') ? flag.slice(2) : '';
+    const key = fieldNames[name] ?? name;
+    if (
+      !commands[action].includes(name) ||
+      (name !== 'image' && !(name === 'agent' && action === 'wait') && Object.hasOwn(args, key))
+    )
+      throw invalid();
+    const value = input.shift();
+    if (
+      value === undefined ||
+      (value === '' && name !== 'effort') ||
+      (name !== 'message' && value.startsWith('--'))
+    )
+      throw invalid();
+    if (name === 'agent' && action === 'wait') {
+      (args.agentIds ??= []).push(value);
+      if (args.agentIds.length > 8) throw invalid();
+    } else if (name === 'image') {
+      (args.images ??= []).push(value);
+      if (args.images.length > 5) throw invalid();
+    } else if (name === 'limit' || name === 'expected-revision') {
+      if (
+        !/^[1-9][0-9]*$/u.test(value) ||
+        !Number.isSafeInteger(Number(value)) ||
+        (name === 'limit' && Number(value) > 100)
+      )
+        throw invalid();
+      args[key] = Number(value);
+    } else if (name === 'timeout') {
+      const match = /^(0|[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 (match === null || !Number.isSafeInteger(ms) || ms > 300000) throw invalid();
+      args[key] = ms;
+    } else args[key] = value;
+  }
+  if (action === 'send' && args.steer === true && args.queue === true)
+    throw invalid('errors.sessionDeliveryRequired');
+  if (
+    action === 'send' &&
+    ((args.approvalId === undefined) !== (args.decision === undefined) ||
+      (args.decision !== undefined && !['approve', 'reject'].includes(args.decision)))
+  )
+    throw invalid();
+  if (args.goal !== undefined && (args.clearGoal || !args.goal.trim() || args.goal.length > 20000))
+    throw invalid();
+  if (args.message !== undefined && args.messageFile !== undefined) throw invalid();
+  if (
+    ['start', 'send', 'goal.set', 'schedule.create', 'prompt.set'].includes(action) &&
+    args.messageFile === undefined &&
+    args.message === undefined &&
+    !args.images?.length &&
+    !(
+      action === 'send' &&
+      (args.goal !== undefined || args.clearGoal || args.approvalId !== undefined)
+    )
+  )
+    throw invalid();
+  if (
+    action === 'start' &&
+    args.runner !== undefined &&
+    !['mar-agent', 'codex', 'claude-code', 'opencode'].includes(args.runner)
+  )
+    throw invalid();
+  if (action === 'stop' && !args.executionId) throw invalid();
+  if (action === 'wait' && args.sessionId && args.agentIds?.length) throw invalid();
+  if (
+    args.until !== undefined &&
+    (args.until !== 'approval' ||
+      !args.sessionId ||
+      !args.runId ||
+      !args.timeoutMs ||
+      args.agentIds?.length)
+  )
+    throw invalid();
+  if (
+    action === 'wait' &&
+    args.runId !== undefined &&
+    (!args.sessionId ||
+      args.timeoutMs === 0 ||
+      args.agentIds?.length ||
+      args.mode !== undefined ||
+      args.waitFor !== undefined)
+  )
+    throw invalid();
+  if (args.waitFor !== undefined && !['message', 'completion'].includes(args.waitFor))
+    throw invalid();
+  if (args.mode !== undefined && !['any', 'all'].includes(args.mode)) throw invalid();
+  if (
+    args.scope !== undefined &&
+    !['children', 'descendants', 'workspace', 'profile'].includes(args.scope)
+  )
+    throw invalid();
+  if (
+    action === 'approval.decide' &&
+    (!args.runId || !args.approvalId || !['approve', 'reject'].includes(args.decision))
+  )
+    throw invalid(
+      undefined,
+      'Approval decisions require --run, --approval and --decision approve|reject.'
+    );
+  if (action === 'rename' && args.title !== undefined) args.title = args.title.trim();
+  if (args.title !== undefined && args.title.length > 160) throw invalid();
+  if (args.model !== undefined && (args.model.trim().length === 0 || args.model.length > 120))
+    throw invalid();
+  if (args.effort !== undefined && args.effort.length > 120) throw invalid();
+  if (action === 'config' && args.model === undefined && args.effort === undefined) throw invalid();
+  if (action === 'rename') {
+    if (args.title === undefined || args.title.trim().length === 0) throw invalid();
+  }
+  if (action === 'schedule.create' && args.cron === undefined) throw invalid();
+  if (args.cron !== undefined && (args.cron.trim().length === 0 || args.cron.length > 512))
+    throw invalid();
+  if (
+    action === 'schedule.update' &&
+    (args.expectedRevision === undefined ||
+      (args.cron === undefined && args.message === undefined && args.messageFile === undefined))
+  )
+    throw invalid();
+  if (args.query !== undefined && args.query.length > 160) throw invalid();
+  if (args.parentSessionId !== undefined && args.parentSessionId.length > 512) throw invalid();
+  return args;
+}

package/src/session-input.mjs

@@ -0,0 +1,88 @@
+import { open } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { MarctlError } from './errors.mjs';
+
+export async function messageContent(
+  { message, messageFile: path },
+  stdin,
+  limit,
+  translate,
+  diagnostic = false
+) {
+  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 (error) {
+    throw new MarctlError(translate('errors.sessionMessageInvalid'), {
+      code: 'MARCTL_SESSION_INPUT_INVALID',
+      ...(diagnostic
+        ? {
+            details: `${path === undefined ? 'message' : path === '-' ? 'stdin' : 'message-file'}: provide non-blank UTF-8 text of at most ${limit} characters.${typeof error.code === 'string' && /^[A-Z_]+$/u.test(error.code) ? ' File error: ' + error.code + '.' : ''}`
+          }
+        : {})
+    });
+  } finally {
+    await file?.close();
+  }
+}
+
+export 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';
+}

package/src/session-prepare.mjs

@@ -0,0 +1,99 @@
+import { randomUUID } from 'node:crypto';
+import { messageContent, imageAttachments } from './session-input.mjs';
+
+const networkActions = new Set(['start', 'send', 'wait', 'stop', 'list', 'view']);
+
+/** Adapt CLI syntax to the same Node Agent Network command used by native tools. */
+export async function prepareAgentNetworkRequest({ args, stdin, translate, sessionId }) {
+  const input = {};
+  for (const name of [
+    'runner',
+    'model',
+    'effort',
+    'title',
+    'cursor',
+    'limit',
+    'query',
+    'parentSessionId',
+    'scope',
+    'waitFor',
+    'mode',
+    'executionId'
+  ])
+    if (args[name] !== undefined) input[name] = args[name];
+  if (args.action === 'list' && input.parentSessionId !== undefined) {
+    input.parent = input.parentSessionId;
+    delete input.parentSessionId;
+  }
+  if (args.action === 'list' && args.agent !== undefined) input.agentId = args.agent;
+  if (['send', 'stop', 'view', 'wait'].includes(args.action) && sessionId)
+    input.agentId = sessionId;
+  if (args.action === 'wait' && args.agentIds?.length) input.agentIds = args.agentIds;
+  if (args.action === 'wait' && args.timeoutMs !== undefined) input.waitMs = args.timeoutMs;
+  if (args.action === 'view' && args.history) input.includeHistory = true;
+  if (args.message !== undefined || args.messageFile !== undefined)
+    input.content = await messageContent(args, stdin, 100000, translate);
+  if (args.images?.length) input.attachments = await imageAttachments(args.images, translate);
+  if (args.goal !== undefined) input.goal = { objective: args.goal.trim() };
+  if (args.clearGoal) input.goal = { clear: true };
+  if (args.action === 'send' && args.approvalId !== undefined)
+    input.approval = { approvalId: args.approvalId, decision: args.decision };
+  if (args.action === 'start' || args.action === 'send')
+    input.clientMessageId = args.clientMessageId ?? randomUUID();
+  if (args.action === 'send')
+    input.deliveryIntent = args.steer ? 'REPLACE_CURRENT' : args.queue ? 'QUEUE' : 'SEND';
+  return { action: 'network', command: { operation: args.action, input } };
+}
+
+export function isAgentNetworkAction(action) {
+  return networkActions.has(action);
+}
+
+export async function prepareSessionRequest({ args, env, stdin, translate, sessionId, targeted }) {
+  const body = { action: args.action };
+  for (const name of [
+    'sessionId',
+    'parentSessionId',
+    'runner',
+    'model',
+    'effort',
+    'title',
+    'cursor',
+    'limit',
+    'query',
+    'runId',
+    'approvalId',
+    'cron',
+    'expectedRevision'
+  ])
+    if (args[name] !== undefined) body[name] = args[name];
+  if (targeted) body.sessionId = sessionId;
+  if (args.action === 'current' && env.MAR_CTL_SESSION_ID) body.sessionId = env.MAR_CTL_SESSION_ID;
+  if (args.action === 'start' && env.MAR_CTL_SESSION_ID)
+    body.parentSessionId = env.MAR_CTL_SESSION_ID;
+  if (['start', 'send'].includes(args.action) && env.MAR_CTL_SESSION_ID)
+    body.sourceSessionId = env.MAR_CTL_SESSION_ID;
+  if (args.messageFile !== undefined || args.message !== undefined)
+    body.content = await messageContent(
+      args,
+      stdin,
+      args.action === 'goal.set' ||
+        args.action.startsWith('schedule.') ||
+        args.action === 'prompt.set'
+        ? 20000
+        : 100000,
+      translate,
+      args.action === 'prompt.set'
+    );
+  if (args.action === 'approval.decide')
+    body.decision = args.decision === 'approve' ? 'APPROVED' : 'REJECTED';
+  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 = args.steer === true ? 'REPLACE_CURRENT' : 'QUEUE';
+  return Object.freeze(body);
+}

package/src/session-target.mjs

@@ -0,0 +1,26 @@
+// Scope is a command property, independent of input or the remote session state.
+export const sessionTarget = Object.freeze({
+  current: 'workspace',
+  list: 'workspace',
+  start: 'workspace',
+  'schedule.list': 'workspace',
+  show: 'current',
+  view: 'current',
+  config: 'current',
+  history: 'current',
+  graph: 'current',
+  rename: 'current',
+  'prompt.get': 'current',
+  'prompt.set': 'current',
+  'prompt.clear': 'current',
+  'schedule.get': 'current',
+  'schedule.create': 'current',
+  'schedule.update': 'current',
+  send: 'explicit',
+  stop: 'explicit',
+  wait: 'optional',
+  'approval.decide': 'explicit',
+  'goal.get': 'explicit',
+  'goal.set': 'explicit',
+  'goal.clear': 'explicit'
+});

package/src/session-wait.mjs

@@ -0,0 +1,232 @@
+import { randomUUID } from 'node:crypto';
+import { MarctlError } from './errors.mjs';
+import { createTranslator } from './i18n/index.mjs';
+
+const terminal = new Set(['SUCCEEDED', 'FAILED', 'CANCELLED', 'INTERRUPTED']);
+
+/** One CLI-owned Workbench connection and one existing Session Watch, never history polling. */
+export async function waitForSessionRun({
+  client,
+  sessionId,
+  runId,
+  timeoutMs,
+  until,
+  WebSocketClass,
+  translate = createTranslator(),
+  signal
+}) {
+  let socket;
+  const watchId = randomUUID();
+  let connectionId;
+  let renewal;
+  let settled = false;
+  let subscribed = false;
+  let progress;
+  let accept;
+  let rejectResult;
+  const result = new Promise((resolve, fail) => {
+    accept = resolve;
+    rejectResult = fail;
+  });
+  const reject = (error, stage) => {
+    if (settled) return;
+    settled = true;
+    Object.assign(error, { sessionId, runId, stage });
+    rejectResult(error);
+  };
+  const fail = (code, key, { stage, upstreamCode, ...options } = {}) => {
+    const error = new MarctlError(translate(key), { ...options, code });
+    if (upstreamCode !== undefined) error.upstreamCode = upstreamCode;
+    if (stage === 'timeout' && progress !== undefined) error.progress = progress;
+    reject(error, stage);
+  };
+  const unknown = (stage, detail, source) =>
+    fail('MARCTL_WAIT_UNKNOWN', 'errors.sessionWaitUnknown', {
+      stage,
+      upstreamCode:
+        typeof source?.code === 'string' && /^[A-Za-z][A-Za-z0-9_]{0,127}$/u.test(source.code)
+          ? source.code
+          : undefined,
+      requestId: typeof source?.requestId === 'string' ? source.requestId.slice(0, 160) : undefined,
+      upstreamRequestId:
+        typeof source?.upstreamRequestId === 'string'
+          ? source.upstreamRequestId.slice(0, 160)
+          : undefined,
+      details: [detail, source?.message, source?.details]
+        .filter((value) => typeof value === 'string')
+        .join(' ')
+        .slice(0, 4000)
+    });
+  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) {
+      unknown('lease', 'The Watch lease is missing or expired.');
+      return;
+    }
+    renewal = setTimeout(
+      () => {
+        command('renew')
+          .then((ack) => {
+            if (!settled) scheduleRenewal(ack?.expiresAt);
+          })
+          .catch((error) => {
+            if ([401, 403].includes(error.statusCode)) reject(error, 'renew');
+            else
+              unknown(
+                'renew',
+                'The Watch lease could not be renewed.',
+                error instanceof MarctlError ? error : undefined
+              );
+          });
+      },
+      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 checkApproval = () => {
+    if (settled || until !== 'approval' || progress === undefined) return;
+    if (!Array.isArray(progress.pendingApprovals)) {
+      fail('NODE_OPERATION_UNSUPPORTED', 'errors.sessionApprovalUnsupported', {
+        stage: 'approval'
+      });
+      return;
+    }
+    const pendingApprovals = progress.pendingApprovals.filter(
+      (approval) => approval.runId === runId
+    );
+    if (pendingApprovals.length === 0) return;
+    settled = true;
+    accept({
+      sessionId,
+      runId,
+      stopReason: 'APPROVAL_REQUIRED',
+      pendingApprovals,
+      ...(progress.pendingApprovalsTruncated ? { pendingApprovalsTruncated: true } : {})
+    });
+  };
+  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((error) => reject(error, 'subscribe'));
+    }
+    if (message.watchId !== watchId) return;
+    if (message.type === 'watch.failed') {
+      unknown('watch', 'The Session Watch failed.', message);
+      return;
+    }
+    if (message.type === 'watch.session.snapshot') {
+      const runs = message.payload?.runs;
+      if (!Array.isArray(runs)) {
+        unknown('snapshot', 'The Watch snapshot did not contain a Run list.');
+        return;
+      }
+      const run = runs.find((value) => value?.id === runId && value.sessionId === sessionId);
+      if (run === undefined) {
+        unknown('snapshot', 'The requested Run was absent from the Watch snapshot.');
+        return;
+      }
+      if (message.payload?.session?.id === sessionId && message.payload?.progress?.runId === runId)
+        progress = message.payload.progress;
+      check(run);
+      if (!settled && until === 'approval' && progress === undefined) {
+        fail('NODE_OPERATION_UNSUPPORTED', 'errors.sessionApprovalUnsupported', {
+          stage: 'approval'
+        });
+      }
+      checkApproval();
+    } else if (message.type === 'watch.session.event') {
+      const payload = message.event?.payload;
+      if (
+        (payload?.sessionId ?? payload?.run?.sessionId) === sessionId &&
+        payload?.progress?.runId === runId
+      )
+        progress = payload.progress;
+      check(payload?.run);
+      checkApproval();
+    }
+    if (!settled && message.expiresAt !== undefined) scheduleRenewal(message.expiresAt);
+  };
+  const onClose = (code, reason) => {
+    if (code === 1008 && String(reason) === 'UNAUTHENTICATED')
+      fail('UNAUTHENTICATED', 'errors.userContextUnavailable', {
+        statusCode: 401,
+        stage: 'connection'
+      });
+    else
+      unknown(
+        'connection',
+        Number.isInteger(code)
+          ? `The Watch connection closed (code ${code}).`
+          : 'The Watch connection closed.'
+      );
+  };
+  const onError = (error) =>
+    unknown('connection', 'The Watch connection failed.', { code: error?.code });
+  const onOpen = () => {
+    try {
+      socket.send(JSON.stringify({ type: 'resume' }));
+    } catch (error) {
+      onError(error);
+    }
+  };
+  const onAbort = () =>
+    fail('MARCTL_WAIT_CANCELLED', 'errors.sessionWaitCancelled', { stage: 'cancel' });
+  try {
+    socket = client.openWorkbenchWebSocket(WebSocketClass ?? (await import('ws')).default);
+  } catch (error) {
+    if (error instanceof MarctlError) reject(error, 'connection');
+    else unknown('connection', 'The Watch connection could not be opened.');
+    return await result;
+  }
+  const timer = setTimeout(
+    () => fail('MARCTL_WAIT_TIMEOUT', 'errors.sessionWaitTimeout', { stage: 'timeout' }),
+    timeoutMs
+  );
+  socket.on('open', onOpen);
+  socket.on('message', onMessage);
+  socket.on('error', onError);
+  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();
+  }
+}