@myagentroam/marctl 0.10.1 → 0.10.3

package/package.json

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

package/src/cli.mjs

@@ -38,7 +38,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();
@@ -110,7 +110,6 @@ export function executableArgs(executable, args) {
 }
 
 export function parseArgs(argv, translate = createTranslator()) {
-  let envFile;
   let command;
   let nodeId;
   const remoteArgs = [];
@@ -133,18 +132,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;
@@ -186,12 +173,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 +184,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

@@ -86,6 +86,14 @@ export class MarctlClient {
     };
   }
 
+  async openDirectTerminal(options) {
+    const { openDirectTerminalProcess } = await import('./direct-process.mjs');
+    return openDirectTerminalProcess({
+      ...options,
+      connection: { serverUrl: this.#serverUrl, key: this.#key }
+    });
+  }
+
   async createAttachTicket({ nodeId, terminalId, afterSequence }) {
     validateNodeId(nodeId, this.#translate);
     validateTerminalId(terminalId, this.#translate);

package/src/config.mjs

@@ -1,10 +1,5 @@
-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);
@@ -12,56 +7,17 @@ export class MarctlError extends Error {
   }
 }
 
-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
-    });
-  }
-  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
-  });
+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'));
+  return Object.freeze({ serverUrl: validateServerUrl(serverUrl, translate), key: token });
 }
 
 export function validateServerUrl(value, translate = createTranslator()) {
@@ -86,80 +42,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/direct-process.mjs

@@ -0,0 +1,351 @@
+import { fork } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { fileURLToPath } from 'node:url';
+import { DirectFallbackError, DirectUnsafeError } from './direct.mjs';
+
+const CLEANUP_TIMEOUT_MS = 1000;
+const MAX_BUFFER_BYTES = 2 * 1024 * 1024;
+const ipcBytes = new WeakMap();
+
+function sendIpc(target, message, onError = () => {}, onSent = () => {}) {
+  const bytes = Buffer.byteLength(JSON.stringify(message));
+  const pending = ipcBytes.get(target) ?? 0;
+  if (!target.connected || pending + bytes > MAX_BUFFER_BYTES) {
+    onError(new Error('TERMINAL_CONNECTION_LOST'));
+    return false;
+  }
+  ipcBytes.set(target, pending + bytes);
+  try {
+    target.send(message, (error) => {
+      ipcBytes.set(target, (ipcBytes.get(target) ?? 0) - bytes);
+      if (error) onError(error);
+      else onSent();
+    });
+    return true;
+  } catch (error) {
+    ipcBytes.set(target, (ipcBytes.get(target) ?? 0) - bytes);
+    onError(error);
+    return false;
+  }
+}
+
+export function openDirectTerminalProcess({
+  connection,
+  nodeId,
+  terminalId,
+  manifest,
+  afterSequence = 0,
+  timeoutMs = 15000,
+  heartbeatMs = 10000,
+  onPrepared,
+  onIceConnected,
+  onTransportReady,
+  signal,
+  forkImpl = fork
+}) {
+  if (signal?.aborted) return Promise.reject(new DirectFallbackError('DIRECT_RACE_CANCELLED'));
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = forkImpl(new URL('./direct-process.mjs', import.meta.url), [], {
+        stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+        execArgv: []
+      });
+    } catch {
+      reject(new DirectFallbackError('DIRECT_UNAVAILABLE'));
+      return;
+    }
+    let settled = false;
+    let opening = false;
+    let stopping = false;
+    let exited = false;
+    let cleanupTimer;
+    const stop = () => {
+      if (stopping) return;
+      stopping = true;
+      clearTimeout(setupTimer);
+      signal?.removeEventListener('abort', onAbort);
+      if (exited) return;
+      sendIpc(child, { type: 'abort' });
+      // Native cleanup may block. Only this connection's process is terminated.
+      cleanupTimer = setTimeout(() => child.kill('SIGKILL'), CLEANUP_TIMEOUT_MS);
+    };
+    const transport = new IsolatedDirectTransport(child, stop);
+    const fail = (error) => {
+      if (settled) {
+        transport.fail(error);
+      } else {
+        settled = true;
+        reject(error);
+        stop();
+      }
+    };
+    const setupError = () =>
+      opening
+        ? new DirectUnsafeError('DIRECT_OPEN_CANCEL_UNCONFIRMED')
+        : new DirectFallbackError('DIRECT_UNAVAILABLE');
+    const setupTimer = setTimeout(() => fail(setupError()), timeoutMs);
+    const onAbort = () =>
+      fail(
+        opening
+          ? new DirectUnsafeError('DIRECT_OPEN_CANCEL_UNCONFIRMED')
+          : new DirectFallbackError('DIRECT_RACE_CANCELLED')
+      );
+    child.on('message', (message) => {
+      if (message.type === 'callback') {
+        const callback = { prepared: onPrepared, ice: onIceConnected, transport: onTransportReady }[
+          message.event
+        ];
+        if (message.event === 'opening') opening = true;
+        Promise.resolve()
+          .then(() => {
+            if (stopping) throw new DirectFallbackError('DIRECT_RACE_CANCELLED');
+            return callback?.();
+          })
+          .then(
+            () =>
+              sendIpc(child, { type: 'callback.result', id: message.id }, () => fail(setupError())),
+            () => sendIpc(child, { type: 'callback.result', id: message.id, failed: true })
+          );
+      } else if (message.type === 'attached' && !settled) {
+        settled = true;
+        clearTimeout(setupTimer);
+        resolve(transport);
+      } else if (message.type === 'failure') {
+        const error = settled
+          ? new Error(message.code ?? 'TERMINAL_CONNECTION_LOST')
+          : message.name === 'DirectUnsafeError' ||
+              (opening && message.name !== 'DirectFallbackError')
+            ? new DirectUnsafeError(message.code)
+            : new DirectFallbackError(message.code);
+        fail(error);
+      } else if (message.type === 'frame') {
+        transport.frame(message.frame, message.isBinary);
+      } else if (message.type === 'send.result') {
+        transport.written(message.id, message.code);
+      } else if (message.type === 'finished') {
+        clearTimeout(cleanupTimer);
+      }
+    });
+    child.on('error', () => fail(setupError()));
+    child.on('disconnect', () => {
+      if (!stopping) fail(setupError());
+    });
+    child.on('exit', () => {
+      exited = true;
+      clearTimeout(cleanupTimer);
+      clearTimeout(setupTimer);
+      signal?.removeEventListener('abort', onAbort);
+      if (!stopping) fail(setupError());
+    });
+    signal?.addEventListener('abort', onAbort, { once: true });
+    sendIpc(
+      child,
+      {
+        type: 'start',
+        options: { connection, nodeId, terminalId, manifest, afterSequence, timeoutMs, heartbeatMs }
+      },
+      () => fail(setupError())
+    );
+    if (signal?.aborted) onAbort();
+  });
+}
+
+class IsolatedDirectTransport extends EventEmitter {
+  #child;
+  #stop;
+  #active = false;
+  #closed = false;
+  #events = [];
+  #bytes = 0;
+  #writes = new Map();
+  #writeBytes = 0;
+  #nextId = 0;
+
+  constructor(child, stop) {
+    super();
+    this.#child = child;
+    this.#stop = stop;
+  }
+
+  activate() {
+    if (this.#active) return;
+    this.#active = true;
+    const events = this.#events;
+    this.#events = [];
+    this.#bytes = 0;
+    for (const [type, value, isBinary] of events) this.#emit(type, value, isBinary);
+  }
+
+  frame(frame, isBinary = false) {
+    if (this.#closed) return;
+    if (!this.#active) {
+      this.#bytes += Buffer.byteLength(frame);
+      if (this.#bytes > MAX_BUFFER_BYTES)
+        return this.fail(new Error('TERMINAL_DIRECT_BUFFER_EXCEEDED'));
+    }
+    this.#emit('message', frame, isBinary);
+  }
+
+  send(frame) {
+    if (this.#closed) return Promise.reject(new Error('TERMINAL_CONNECTION_LOST'));
+    const value = typeof frame === 'string' ? frame : JSON.stringify(frame);
+    const bytes = Buffer.byteLength(value);
+    if (this.#writeBytes + bytes > MAX_BUFFER_BYTES)
+      return Promise.reject(new Error('TERMINAL_DIRECT_BUFFER_EXCEEDED'));
+    const id = ++this.#nextId;
+    return new Promise((resolve, reject) => {
+      this.#writeBytes += bytes;
+      this.#writes.set(id, { resolve, reject, bytes });
+      sendIpc(this.#child, { type: 'send', id, frame: value }, () =>
+        this.fail(new Error('TERMINAL_CONNECTION_LOST'))
+      );
+    });
+  }
+
+  written(id, code) {
+    const write = this.#writes.get(id);
+    if (!write) return;
+    this.#writes.delete(id);
+    this.#writeBytes -= write.bytes;
+    if (code) write.reject(new Error(code));
+    else write.resolve();
+  }
+
+  fail(error) {
+    if (this.#closed) return;
+    this.#emit(
+      'error',
+      new Error(
+        error instanceof DirectFallbackError || error instanceof DirectUnsafeError
+          ? 'TERMINAL_CONNECTION_LOST'
+          : error.message
+      )
+    );
+    this.close();
+  }
+
+  close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    for (const { reject } of this.#writes.values()) reject(new Error('TERMINAL_CONNECTION_LOST'));
+    this.#writes.clear();
+    this.#writeBytes = 0;
+    this.#stop();
+    this.#emit('close');
+  }
+
+  #emit(type, value, isBinary = false) {
+    if (!this.#active) this.#events.push([type, value, isBinary]);
+    else if (type !== 'error' || this.listenerCount('error') > 0) this.emit(type, value, isBinary);
+  }
+}
+
+function runChild() {
+  const controller = new AbortController();
+  const callbacks = new Map();
+  let nextId = 0;
+  let transport;
+  let native;
+  let cleaning = false;
+  const cleanup = () => {
+    if (cleaning) return;
+    cleaning = true;
+    setImmediate(() => {
+      try {
+        native?.cleanup();
+      } catch {
+        /* Process exit also releases native resources. */
+      }
+      sendIpc(
+        process,
+        { type: 'finished' },
+        () => process.exit(0),
+        () => process.exit(0)
+      );
+    });
+  };
+  const callback = (event) =>
+    new Promise((resolve, reject) => {
+      const id = ++nextId;
+      callbacks.set(id, { resolve, reject });
+      sendIpc(process, { type: 'callback', id, event }, reject);
+    });
+  const abort = () => {
+    controller.abort();
+    for (const { reject } of callbacks.values())
+      reject(new DirectFallbackError('DIRECT_RACE_CANCELLED'));
+    callbacks.clear();
+    if (transport) transport.close();
+  };
+  process.on('disconnect', () => {
+    abort();
+    cleanup();
+  });
+  process.on('message', async (message) => {
+    if (message.type === 'callback.result') {
+      const pending = callbacks.get(message.id);
+      callbacks.delete(message.id);
+      if (message.failed) pending?.reject(new DirectFallbackError('DIRECT_RACE_CANCELLED'));
+      else pending?.resolve();
+    } else if (message.type === 'abort') {
+      abort();
+    } else if (message.type === 'send') {
+      try {
+        await transport.send(message.frame);
+        sendIpc(process, { type: 'send.result', id: message.id });
+      } catch {
+        sendIpc(process, { type: 'send.result', id: message.id, code: 'TERMINAL_INPUT_FAILED' });
+      }
+    } else if (message.type === 'start') {
+      try {
+        const { MarctlClient } = await import('./client.mjs');
+        const { openDirectTerminal } = await import('./direct.mjs');
+        const { default: WebSocketClass } = await import('ws');
+        native = await import('node-datachannel');
+        const { connection, ...options } = message.options;
+        let iceSelection;
+        transport = await openDirectTerminal({
+          ...options,
+          client: new MarctlClient(connection),
+          WebSocketClass,
+          peerConnectionFactory: (name, config) => new native.PeerConnection(name, config),
+          cleanupNative: cleanup,
+          signal: controller.signal,
+          onPrepared: () => callback('prepared'),
+          onIceConnected: () => {
+            iceSelection = callback('ice');
+            iceSelection.catch(() => controller.abort());
+          },
+          onTransportReady: async () => {
+            await iceSelection;
+            await callback('transport');
+          },
+          beforeOpen: () => callback('opening')
+        });
+        sendIpc(process, { type: 'attached' });
+        transport.on('message', (frame, isBinary) =>
+          sendIpc(process, { type: 'frame', frame: String(frame), isBinary }, abort)
+        );
+        transport.on('error', (error) => {
+          sendIpc(process, { type: 'failure', code: error.message });
+          abort();
+        });
+        transport.on('close', () => {
+          sendIpc(process, { type: 'failure', code: 'TERMINAL_DIRECT_CLOSED' });
+          cleanup();
+        });
+        transport.activate();
+      } catch (error) {
+        sendIpc(process, {
+          type: 'failure',
+          name: error instanceof DirectUnsafeError ? 'DirectUnsafeError' : 'DirectFallbackError',
+          code: error.code ?? 'DIRECT_UNAVAILABLE'
+        });
+        cleanup();
+      }
+    }
+  });
+}
+
+if (process.send && process.argv[1] === fileURLToPath(import.meta.url)) runChild();

package/src/direct.mjs

@@ -22,21 +22,26 @@ export class DirectUnsafeError extends Error {
   }
 }
 
-export async function openDirectTerminal({
-  client,
-  WebSocketClass,
-  nodeId,
-  terminalId,
-  manifest,
-  afterSequence = 0,
-  timeoutMs = DIRECT_SETUP_TIMEOUT_MS,
-  heartbeatMs = DIRECT_HEARTBEAT_MS,
-  peerConnectionFactory,
-  onPrepared,
-  onIceConnected,
-  onTransportReady,
-  signal
-}) {
+export async function openDirectTerminal(options) {
+  const {
+    client,
+    WebSocketClass,
+    nodeId,
+    terminalId,
+    afterSequence = 0,
+    timeoutMs = DIRECT_SETUP_TIMEOUT_MS,
+    heartbeatMs = DIRECT_HEARTBEAT_MS,
+    peerConnectionFactory,
+    onPrepared,
+    onIceConnected,
+    onTransportReady,
+    beforeOpen,
+    cleanupNative: cleanupNativeImpl,
+    signal
+  } = options;
+  let { manifest } = options;
+  if (peerConnectionFactory === undefined && typeof client.openDirectTerminal === 'function')
+    return client.openDirectTerminal(options);
   if (manifest === undefined && typeof client.getTerminalManifest !== 'function')
     throw new DirectFallbackError('DIRECT_MANIFEST_UNAVAILABLE');
 
@@ -50,7 +55,7 @@ export async function openDirectTerminal({
   let unsafeFallback = false;
   let transportControlCleanup;
   let transportNegotiationActive = true;
-  let cleanupNative;
+  let cleanupNative = cleanupNativeImpl;
   try {
     manifest ??= await client.getTerminalManifest(nodeId);
     if (
@@ -82,7 +87,7 @@ export async function openDirectTerminal({
 
     const native =
       peerConnectionFactory === undefined ? await import('node-datachannel') : undefined;
-    cleanupNative = native?.cleanup;
+    cleanupNative ??= native?.cleanup;
     const createPeer =
       peerConnectionFactory ?? ((name, options) => new native.PeerConnection(name, options));
     peer = createPeer(`marctl-${transportSessionId}`, { iceServers: [] });
@@ -252,6 +257,7 @@ export async function openDirectTerminal({
       heartbeatMs,
       cleanupNative
     });
+    if (beforeOpen) await beforeOpen();
     await withTimeout(
       transport.waitForAttachment(terminalPrepared.grant),
       timeoutMs,

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
@@ -20,7 +18,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 +37,21 @@ ${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({
     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 +61,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 +90,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 +102,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.
@@ -156,21 +149,9 @@ or Server connection is required.`
   disconnected: 'disconnected',
   errors: Object.freeze({
     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 +193,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 命令行工具
@@ -20,7 +17,6 @@ export default Object.freeze({
   help     显示工具或指定子命令的帮助。
 
 选项：
-  --env-file PATH  使用指定的管理配置文件。
   -h, --help       显示帮助后退出。
   -V, --version    显示 CLI 包版本后退出。
 
@@ -40,23 +36,21 @@ ${configurationHelp}
 
 说明：
   帮助和版本查询离线可用，无需配置或授权。
-  本机帮助、版本选项须放在节点或文件端点前；--env-file 也可放在子命令后。
+  本机帮助、版本选项须放在节点或文件端点前。
   快捷命令仅显示对应操作的帮助。用 marctl help <子命令> 查看详细说明。
   远程访问使用授权的 Node Terminal 传输，不是系统 SSH 或 SCP 协议。`,
   commandHelp: Object.freeze({
     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 +60,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 +87,7 @@ ${configurationHelp}`,
     scp: `{program} — 复制普通文件
 
 用法：
-  {program} [--env-file PATH] [选项] <源> <目标>
+  {program} [选项] <源> <目标>
 
 参数：
   <源>            本机文件或有权限的节点文件端点。
@@ -106,7 +99,6 @@ ${configurationHelp}`,
 选项：
   -p              保留源文件权限及访问、修改时间。
   -q              不显示进度（默认已不显示）。
-  --env-file PATH  使用指定的管理配置文件。
   -h, --help       显示帮助后退出，须放在第一个文件端点前。
   -V, --version    显示 CLI 包版本后退出，须放在第一个文件端点前。
   --              后续参数按字面路径处理。
@@ -151,20 +143,9 @@ ${configurationHelp}`,
   disconnected: '离线',
   errors: Object.freeze({
     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 +184,6 @@ ${configurationHelp}`,
     terminalSessionFailed: '终端会话失败。',
     terminalDirectUnsafeFallback: 'OPEN 后无法安全取消直连终端，已跳过 relay 回退。',
     invalidArguments: '命令参数无效。',
-    envFileValueRequired: '--env-file 必须提供值。',
     sshOptionsUnsupported: '不支持 SSH 选项，请使用 marssh <节点>。',
     scpOptionsUnsupported: 'Node Terminal 传输不支持此 SCP 选项。',
     terminalBinaryUnavailable: '二进制复制需要支持 pipe 终端的 Server 与 Node。',

package/src/terminal.mjs

@@ -583,7 +583,9 @@ function runAttachedTerminal({
     const onResize = () => {
       try {
         const { rows, cols } = getDimensions(stdout);
-        send({ type: 'resize', terminalId, rows, cols });
+        Promise.resolve(send({ type: 'resize', terminalId, rows, cols })).catch(() =>
+          fail('errors.terminalResizeFailed')
+        );
       } catch {
         fail('errors.terminalResizeFailed');
       }
@@ -686,7 +688,7 @@ function rawToString(raw) {
 function sendCloseFrame(socket, terminalId) {
   if (!terminalId || !isSocketOpen(socket)) return;
   try {
-    socket.send(JSON.stringify({ type: 'close', terminalId }));
+    Promise.resolve(socket.send(JSON.stringify({ type: 'close', terminalId }))).catch(() => {});
   } catch {
     // The DELETE request below remains the authoritative cleanup path.
   }