agentrejoin-agent 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1393 @@
+'use strict';
+
+var commander = require('commander');
+var node_os = require('node:os');
+var node_path = require('node:path');
+var node_fs = require('node:fs');
+var node_crypto = require('node:crypto');
+var tweetnacl = require('tweetnacl');
+var axios = require('axios');
+var qrcode = require('qrcode-terminal');
+var socket_ioClient = require('socket.io-client');
+var node_events = require('node:events');
+
+function loadConfig() {
+  const serverUrl = (process.env.AGENTREJOIN_SERVER_URL ?? "https://agentrejoin.zhandj.com").replace(/\/+$/, "");
+  const homeDir = process.env.AGENTREJOIN_HOME_DIR ?? node_path.join(node_os.homedir(), ".agentrejoin");
+  const credentialPath = node_path.join(homeDir, "agent.key");
+  return { serverUrl, homeDir, credentialPath };
+}
+
+function encodeBase64(buffer) {
+  return Buffer.from(buffer).toString("base64");
+}
+function decodeBase64(base64) {
+  return new Uint8Array(Buffer.from(base64, "base64"));
+}
+function encodeBase64Url(buffer) {
+  return Buffer.from(buffer).toString("base64").replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+}
+function getRandomBytes(size) {
+  return new Uint8Array(node_crypto.randomBytes(size));
+}
+function hmac_sha512(key, data) {
+  const hmac = node_crypto.createHmac("sha512", key);
+  hmac.update(data);
+  return new Uint8Array(hmac.digest());
+}
+function deriveSecretKeyTreeRoot(seed, usage) {
+  const I = hmac_sha512(new TextEncoder().encode(usage + " Master Seed"), seed);
+  return {
+    key: I.slice(0, 32),
+    chainCode: I.slice(32)
+  };
+}
+function deriveSecretKeyTreeChild(chainCode, index) {
+  const data = new Uint8Array([0, ...new TextEncoder().encode(index)]);
+  const I = hmac_sha512(chainCode, data);
+  return {
+    key: I.slice(0, 32),
+    chainCode: I.slice(32)
+  };
+}
+function deriveKey(master, usage, path) {
+  let state = deriveSecretKeyTreeRoot(master, usage);
+  for (const index of path) {
+    state = deriveSecretKeyTreeChild(state.chainCode, index);
+  }
+  return state.key;
+}
+function deriveContentKeyPair(secret) {
+  const seed = deriveKey(secret, "AgentRejoin EnCoder", ["content"]);
+  const hashedSeed = new Uint8Array(node_crypto.createHash("sha512").update(seed).digest());
+  const boxSecretKey = hashedSeed.slice(0, 32);
+  const keyPair = tweetnacl.box.keyPair.fromSecretKey(boxSecretKey);
+  return { publicKey: keyPair.publicKey, secretKey: keyPair.secretKey };
+}
+function encryptWithDataKey(data, dataKey) {
+  const nonce = getRandomBytes(12);
+  const cipher = node_crypto.createCipheriv("aes-256-gcm", dataKey, nonce);
+  const plaintext = new TextEncoder().encode(JSON.stringify(data));
+  const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+  const bundle = new Uint8Array(1 + 12 + encrypted.length + 16);
+  bundle[0] = 0;
+  bundle.set(nonce, 1);
+  bundle.set(new Uint8Array(encrypted), 13);
+  bundle.set(new Uint8Array(authTag), 13 + encrypted.length);
+  return bundle;
+}
+function decryptWithDataKey(bundle, dataKey) {
+  if (bundle.length < 1 + 12 + 16) return null;
+  if (bundle[0] !== 0) return null;
+  const nonce = bundle.slice(1, 13);
+  const authTag = bundle.slice(bundle.length - 16);
+  const ciphertext = bundle.slice(13, bundle.length - 16);
+  try {
+    const decipher = node_crypto.createDecipheriv("aes-256-gcm", dataKey, nonce);
+    decipher.setAuthTag(authTag);
+    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return JSON.parse(new TextDecoder().decode(decrypted));
+  } catch {
+    return null;
+  }
+}
+function encryptLegacy(data, secret) {
+  const nonce = getRandomBytes(tweetnacl.secretbox.nonceLength);
+  const plaintext = new TextEncoder().encode(JSON.stringify(data));
+  const encrypted = tweetnacl.secretbox(plaintext, nonce, secret);
+  const result = new Uint8Array(nonce.length + encrypted.length);
+  result.set(nonce);
+  result.set(encrypted, nonce.length);
+  return result;
+}
+function decryptLegacy(data, secret) {
+  try {
+    const nonce = data.slice(0, tweetnacl.secretbox.nonceLength);
+    const encrypted = data.slice(tweetnacl.secretbox.nonceLength);
+    const decrypted = tweetnacl.secretbox.open(encrypted, nonce, secret);
+    if (!decrypted) return null;
+    return JSON.parse(new TextDecoder().decode(decrypted));
+  } catch {
+    return null;
+  }
+}
+function encrypt(key, variant, data) {
+  if (variant === "legacy") {
+    return encryptLegacy(data, key);
+  } else {
+    return encryptWithDataKey(data, key);
+  }
+}
+function decrypt(key, variant, data) {
+  if (variant === "legacy") {
+    return decryptLegacy(data, key);
+  } else {
+    return decryptWithDataKey(data, key);
+  }
+}
+function libsodiumEncryptForPublicKey(data, recipientPublicKey) {
+  const ephemeralKeyPair = tweetnacl.box.keyPair();
+  const nonce = getRandomBytes(tweetnacl.box.nonceLength);
+  const encrypted = tweetnacl.box(data, nonce, recipientPublicKey, ephemeralKeyPair.secretKey);
+  const result = new Uint8Array(32 + 24 + encrypted.length);
+  result.set(ephemeralKeyPair.publicKey, 0);
+  result.set(nonce, 32);
+  result.set(encrypted, 56);
+  return result;
+}
+function decryptBoxBundle(bundle, recipientSecretKey) {
+  if (bundle.length < 32 + 24) return null;
+  const ephemeralPublicKey = bundle.slice(0, 32);
+  const nonce = bundle.slice(32, 56);
+  const ciphertext = bundle.slice(56);
+  const decrypted = tweetnacl.box.open(ciphertext, nonce, ephemeralPublicKey, recipientSecretKey);
+  return decrypted ? new Uint8Array(decrypted) : null;
+}
+
+function readCredentials(config) {
+  try {
+    const raw = node_fs.readFileSync(config.credentialPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed.token || !parsed.secret) return null;
+    const secret = decodeBase64(parsed.secret);
+    const contentKeyPair = deriveContentKeyPair(secret);
+    return {
+      token: parsed.token,
+      secret,
+      contentKeyPair
+    };
+  } catch {
+    return null;
+  }
+}
+function writeCredentials(config, token, secret) {
+  node_fs.mkdirSync(node_path.dirname(config.credentialPath), { recursive: true, mode: 448 });
+  const data = JSON.stringify({ token, secret: encodeBase64(secret) });
+  node_fs.writeFileSync(config.credentialPath, data, { mode: 384 });
+}
+function clearCredentials(config) {
+  try {
+    node_fs.unlinkSync(config.credentialPath);
+  } catch {
+  }
+}
+function requireCredentials(config) {
+  const creds = readCredentials(config);
+  if (!creds) {
+    throw new Error("Not authenticated. Run `agentrejoin-agent auth login` first.");
+  }
+  return creds;
+}
+
+const POLL_INTERVAL_MS = 1e3;
+const AUTH_TIMEOUT_MS = 12e4;
+async function authLogin(config) {
+  const seed = getRandomBytes(32);
+  const keypair = tweetnacl.box.keyPair.fromSecretKey(seed);
+  const publicKeyBase64 = encodeBase64(keypair.publicKey);
+  try {
+    await axios.post(`${config.serverUrl}/v1/auth/account/request`, {
+      publicKey: publicKeyBase64
+    }, {
+      headers: { "X-AgentRejoin-Client": "cli-control-plane/0.1.0" }
+    });
+  } catch (err) {
+    if (err instanceof axios.AxiosError) {
+      throw new Error(`Failed to initiate auth: ${err.message}`);
+    }
+    throw err;
+  }
+  const qrData = `agentrejoin:///account?${encodeBase64Url(keypair.publicKey)}`;
+  console.log("");
+  qrcode.generate(qrData, { small: true }, (code) => {
+    console.log(code);
+  });
+  console.log("## Authentication");
+  console.log("- Action: Scan this QR code with the AgentRejoin app");
+  console.log("- Path: Settings -> Account -> Link New Device");
+  console.log(`- Public Key: \`${publicKeyBase64}\``);
+  console.log(`- URL: \`${qrData}\``);
+  console.log("");
+  const startTime = Date.now();
+  while (Date.now() - startTime < AUTH_TIMEOUT_MS) {
+    await sleep(POLL_INTERVAL_MS);
+    let result;
+    try {
+      const resp = await axios.post(`${config.serverUrl}/v1/auth/account/request`, {
+        publicKey: publicKeyBase64
+      }, {
+        headers: { "X-AgentRejoin-Client": "cli-control-plane/0.1.0" }
+      });
+      result = resp.data;
+    } catch (err) {
+      if (err instanceof axios.AxiosError) {
+        throw new Error(`Auth polling failed: ${err.message}`);
+      }
+      throw err;
+    }
+    if (result.state === "authorized" && result.token && result.response) {
+      const encryptedResponse = decodeBase64(result.response);
+      const secret = decryptBoxBundle(encryptedResponse, keypair.secretKey);
+      if (!secret) {
+        throw new Error("Failed to decrypt auth response");
+      }
+      writeCredentials(config, result.token, secret);
+      console.log("## Authentication");
+      console.log("- Status: Authenticated");
+      return;
+    }
+  }
+  throw new Error("Authentication timed out. Please try again.");
+}
+async function authLogout(config) {
+  clearCredentials(config);
+  console.log("## Authentication");
+  console.log("- Status: Logged out");
+  console.log("- Credentials: Cleared");
+}
+async function authStatus(config) {
+  const creds = readCredentials(config);
+  console.log("## Authentication");
+  if (creds) {
+    console.log("- Status: Authenticated");
+    console.log(`- Public Key: \`${encodeBase64(creds.contentKeyPair.publicKey)}\``);
+  } else {
+    console.log("- Status: Not authenticated");
+    console.log("- Action: Run `agentrejoin-agent auth login` to authenticate.");
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function resolveRecordEncryption(record, creds, recordLabel) {
+  if (record.dataEncryptionKey) {
+    const encrypted = decodeBase64(record.dataEncryptionKey);
+    const bundle = encrypted.slice(1);
+    const sessionKey = decryptBoxBundle(bundle, creds.contentKeyPair.secretKey);
+    if (!sessionKey) {
+      throw new Error(`Failed to decrypt ${recordLabel} key for ${recordLabel} ${record.id}`);
+    }
+    return { key: sessionKey, variant: "dataKey" };
+  }
+  return { key: creds.secret, variant: "legacy" };
+}
+function resolveSessionEncryption(session, creds) {
+  return resolveRecordEncryption(session, creds, "session");
+}
+function resolveMachineEncryption(machine, creds) {
+  return resolveRecordEncryption(machine, creds, "machine");
+}
+function decryptField(encrypted, encryption) {
+  if (!encrypted) return null;
+  const data = decodeBase64(encrypted);
+  if (encryption.variant === "dataKey") {
+    return decryptWithDataKey(data, encryption.key);
+  }
+  return decryptLegacy(data, encryption.key);
+}
+function decryptSession(raw, creds) {
+  const encryption = resolveSessionEncryption(raw, creds);
+  return {
+    id: raw.id,
+    seq: raw.seq,
+    createdAt: raw.createdAt,
+    updatedAt: raw.updatedAt,
+    active: raw.active,
+    activeAt: raw.activeAt,
+    metadata: decryptField(raw.metadata, encryption),
+    agentState: decryptField(raw.agentState, encryption),
+    dataEncryptionKey: raw.dataEncryptionKey,
+    encryption
+  };
+}
+function decryptMachine(raw, creds) {
+  const encryption = resolveMachineEncryption(raw, creds);
+  return {
+    id: raw.id,
+    seq: raw.seq,
+    createdAt: raw.createdAt,
+    updatedAt: raw.updatedAt,
+    active: raw.active,
+    activeAt: raw.activeAt,
+    metadata: decryptField(raw.metadata, encryption),
+    metadataVersion: raw.metadataVersion,
+    daemonState: decryptField(raw.daemonState, encryption),
+    daemonStateVersion: raw.daemonStateVersion,
+    dataEncryptionKey: raw.dataEncryptionKey,
+    encryption
+  };
+}
+function handleApiError(err, context) {
+  if (err instanceof axios.AxiosError) {
+    const status = err.response?.status;
+    if (status === 401) {
+      throw new Error("Authentication expired. Run `agentrejoin-agent auth login` to re-authenticate.");
+    }
+    if (status === 403) {
+      throw new Error(`Forbidden: ${context}. Check your account permissions.`);
+    }
+    if (status === 404) {
+      throw new Error(`Not found: ${context}`);
+    }
+    if (status && status >= 400 && status < 500) {
+      const detail = err.response?.data ? `: ${JSON.stringify(err.response.data)}` : "";
+      throw new Error(`Request failed (${status})${detail}`);
+    }
+    if (status && status >= 500) {
+      throw new Error(`Server error (${status}): ${context}`);
+    }
+    throw new Error(`Request failed: ${err.message}`);
+  }
+  throw err;
+}
+function authHeaders(creds) {
+  return {
+    Authorization: `Bearer ${creds.token}`,
+    "X-AgentRejoin-Client": "cli-control-plane/0.1.0"
+  };
+}
+async function listSessions(config, creds) {
+  let data;
+  try {
+    const resp = await axios.get(`${config.serverUrl}/v1/sessions`, {
+      headers: authHeaders(creds)
+    });
+    data = resp.data;
+  } catch (err) {
+    handleApiError(err, "listing sessions");
+  }
+  return data.sessions.map((raw) => decryptSession(raw, creds));
+}
+async function listMachines(config, creds) {
+  let data;
+  try {
+    const resp = await axios.get(`${config.serverUrl}/v1/machines`, {
+      headers: authHeaders(creds)
+    });
+    data = resp.data;
+  } catch (err) {
+    handleApiError(err, "listing machines");
+  }
+  return data.map((raw) => decryptMachine(raw, creds));
+}
+async function listActiveSessions(config, creds) {
+  let data;
+  try {
+    const resp = await axios.get(`${config.serverUrl}/v2/sessions/active`, {
+      headers: authHeaders(creds)
+    });
+    data = resp.data;
+  } catch (err) {
+    handleApiError(err, "listing active sessions");
+  }
+  return data.sessions.map((raw) => decryptSession(raw, creds));
+}
+async function createSession(config, creds, opts) {
+  const sessionKey = getRandomBytes(32);
+  const encryptedKey = libsodiumEncryptForPublicKey(sessionKey, creds.contentKeyPair.publicKey);
+  const withVersion = new Uint8Array(1 + encryptedKey.length);
+  withVersion[0] = 0;
+  withVersion.set(encryptedKey, 1);
+  const dataEncryptionKeyBase64 = encodeBase64(withVersion);
+  const encryptedMetadata = encryptWithDataKey(opts.metadata, sessionKey);
+  const metadataBase64 = encodeBase64(encryptedMetadata);
+  let data;
+  try {
+    const resp = await axios.post(
+      `${config.serverUrl}/v1/sessions`,
+      {
+        tag: opts.tag,
+        metadata: metadataBase64,
+        dataEncryptionKey: dataEncryptionKeyBase64
+      },
+      { headers: authHeaders(creds) }
+    );
+    data = resp.data;
+  } catch (err) {
+    handleApiError(err, "creating session");
+  }
+  const decrypted = decryptSession(data.session, creds);
+  return { ...decrypted, sessionKey: decrypted.encryption.key };
+}
+async function getSessionMessages(config, creds, sessionId, encryption) {
+  let data;
+  try {
+    const resp = await axios.get(
+      `${config.serverUrl}/v1/sessions/${encodeURIComponent(sessionId)}/messages`,
+      { headers: authHeaders(creds) }
+    );
+    data = resp.data;
+  } catch (err) {
+    handleApiError(err, `session ${sessionId} messages`);
+  }
+  return data.messages.map((msg) => ({
+    id: msg.id,
+    seq: msg.seq,
+    content: decryptField(msg.content.c, encryption),
+    localId: msg.localId ?? null,
+    createdAt: msg.createdAt,
+    updatedAt: msg.updatedAt
+  }));
+}
+
+function waitForConnect(socket, timeoutMs = 1e4) {
+  return new Promise((resolve, reject) => {
+    if (socket.connected) {
+      resolve();
+      return;
+    }
+    const timeout = setTimeout(() => {
+      socket.off("connect", onConnect);
+      socket.off("connect_error", onError);
+      reject(new Error("Timeout waiting for socket connection"));
+    }, timeoutMs);
+    const onConnect = () => {
+      clearTimeout(timeout);
+      socket.off("connect_error", onError);
+      resolve();
+    };
+    const onError = (error) => {
+      clearTimeout(timeout);
+      socket.off("connect", onConnect);
+      reject(error);
+    };
+    socket.once("connect", onConnect);
+    socket.once("connect_error", onError);
+  });
+}
+function normalizeRpcError(error, machineId) {
+  if (!error) {
+    return "RPC call failed";
+  }
+  if (error === "RPC method not available") {
+    return `Machine ${machineId} is offline or its daemon is not connected.`;
+  }
+  return error;
+}
+async function spawnSessionOnMachine(config, machine, token, options) {
+  const socket = socket_ioClient.io(config.serverUrl, {
+    auth: {
+      token
+    },
+    path: "/v1/updates",
+    transports: ["websocket"],
+    autoConnect: false,
+    reconnection: false
+  });
+  socket.connect();
+  try {
+    await waitForConnect(socket);
+    const params = encodeBase64(
+      encrypt(machine.encryption.key, machine.encryption.variant, {
+        type: "spawn-in-directory",
+        directory: options.directory,
+        approvedNewDirectoryCreation: options.approvedNewDirectoryCreation ?? false,
+        token: options.providerToken,
+        agent: options.agent
+      })
+    );
+    const response = await socket.timeout(3e4).emitWithAck("rpc-call", {
+      method: `${machine.id}:spawn-agentrejoin-session`,
+      params
+    });
+    if (!response.ok) {
+      throw new Error(normalizeRpcError(response.error, machine.id));
+    }
+    if (!response.result) {
+      throw new Error("RPC call returned no result");
+    }
+    const decrypted = decrypt(
+      machine.encryption.key,
+      machine.encryption.variant,
+      decodeBase64(response.result)
+    );
+    if (decrypted == null || typeof decrypted !== "object" || Array.isArray(decrypted)) {
+      throw new Error("RPC call returned invalid data");
+    }
+    if ("error" in decrypted && typeof decrypted.error === "string") {
+      throw new Error(String(decrypted.error));
+    }
+    if (!("type" in decrypted) || decrypted.type !== "success" && decrypted.type !== "requestToApproveDirectoryCreation" && decrypted.type !== "error") {
+      throw new Error("RPC call returned unexpected data");
+    }
+    return decrypted;
+  } finally {
+    socket.close();
+  }
+}
+async function resumeSessionOnMachine(config, machine, token, sessionId) {
+  const socket = socket_ioClient.io(config.serverUrl, {
+    auth: {
+      token
+    },
+    path: "/v1/updates",
+    transports: ["websocket"],
+    autoConnect: false,
+    reconnection: false
+  });
+  socket.connect();
+  try {
+    await waitForConnect(socket);
+    const params = encodeBase64(
+      encrypt(machine.encryption.key, machine.encryption.variant, {
+        sessionId
+      })
+    );
+    const response = await socket.timeout(3e4).emitWithAck("rpc-call", {
+      method: `${machine.id}:resume-agentrejoin-session`,
+      params
+    });
+    if (!response.ok) {
+      throw new Error(normalizeRpcError(response.error, machine.id));
+    }
+    if (!response.result) {
+      throw new Error("RPC call returned no result");
+    }
+    const decrypted = decrypt(
+      machine.encryption.key,
+      machine.encryption.variant,
+      decodeBase64(response.result)
+    );
+    if (decrypted == null || typeof decrypted !== "object" || Array.isArray(decrypted)) {
+      throw new Error("RPC call returned invalid data");
+    }
+    if ("error" in decrypted && typeof decrypted.error === "string") {
+      throw new Error(String(decrypted.error));
+    }
+    if (!("type" in decrypted) || decrypted.type !== "success" && decrypted.type !== "requestToApproveDirectoryCreation" && decrypted.type !== "error") {
+      throw new Error("RPC call returned unexpected data");
+    }
+    return decrypted;
+  } finally {
+    socket.close();
+  }
+}
+
+function checkIdleState(metadata, agentState) {
+  const meta = metadata;
+  if (meta?.lifecycleState === "archived") {
+    return "archived";
+  }
+  const state = agentState;
+  if (!state) {
+    return false;
+  }
+  const controlledByUser = state.controlledByUser === true;
+  const requests = state.requests;
+  const hasRequests = requests != null && typeof requests === "object" && !Array.isArray(requests) && Object.keys(requests).length > 0;
+  return !controlledByUser && !hasRequests;
+}
+function getTurnEvent(content) {
+  if (content == null || typeof content !== "object" || Array.isArray(content)) {
+    return null;
+  }
+  const envelope = content;
+  if (envelope.role !== "session") {
+    return null;
+  }
+  const body = envelope.content;
+  if (body == null || typeof body !== "object" || Array.isArray(body)) {
+    return null;
+  }
+  if (body.ev?.t !== "turn-start" && body.ev?.t !== "turn-end") {
+    return null;
+  }
+  return {
+    type: body.ev.t,
+    turnId: typeof body.turn === "string" ? body.turn : null
+  };
+}
+function isReadyEvent(content) {
+  if (content == null || typeof content !== "object" || Array.isArray(content)) {
+    return false;
+  }
+  const envelope = content;
+  if (envelope.role !== "agent") {
+    return false;
+  }
+  const body = envelope.content;
+  if (body == null || typeof body !== "object" || Array.isArray(body)) {
+    return false;
+  }
+  return body.type === "event" && body.data?.type === "ready";
+}
+class SessionClient extends node_events.EventEmitter {
+  sessionId;
+  encryptionKey;
+  encryptionVariant;
+  socket;
+  metadata = null;
+  metadataVersion = 0;
+  agentState = null;
+  agentStateVersion = 0;
+  constructor(opts) {
+    super();
+    this.sessionId = opts.sessionId;
+    this.encryptionKey = opts.encryptionKey;
+    this.encryptionVariant = opts.encryptionVariant;
+    if (opts.initialAgentState !== void 0) {
+      this.agentState = opts.initialAgentState;
+    }
+    this.on("error", () => {
+    });
+    this.socket = socket_ioClient.io(opts.serverUrl, {
+      auth: {
+        token: opts.token,
+        clientType: "session-scoped",
+        sessionId: opts.sessionId
+      },
+      path: "/v1/updates",
+      reconnection: true,
+      reconnectionAttempts: Infinity,
+      reconnectionDelay: 1e3,
+      reconnectionDelayMax: 5e3,
+      transports: ["websocket"],
+      autoConnect: false
+    });
+    this.socket.on("connect", () => {
+      this.emit("connected");
+    });
+    this.socket.on("disconnect", (reason) => {
+      this.emit("disconnected", reason);
+    });
+    this.socket.on("connect_error", (error) => {
+      this.emit("connect_error", error);
+    });
+    this.socket.on("update", (data) => {
+      try {
+        const body = data?.body;
+        if (!body) return;
+        if (body.t === "new-message" && body.message?.content?.t === "encrypted") {
+          const msg = body.message;
+          const decrypted = decrypt(
+            this.encryptionKey,
+            this.encryptionVariant,
+            decodeBase64(msg.content.c)
+          );
+          if (decrypted === null) return;
+          this.emit("message", {
+            id: msg.id,
+            seq: msg.seq,
+            content: decrypted,
+            localId: msg.localId,
+            createdAt: msg.createdAt,
+            updatedAt: msg.updatedAt
+          });
+        } else if (body.t === "update-session") {
+          if (body.metadata && body.metadata.version > this.metadataVersion) {
+            this.metadata = decrypt(
+              this.encryptionKey,
+              this.encryptionVariant,
+              decodeBase64(body.metadata.value)
+            );
+            this.metadataVersion = body.metadata.version;
+          }
+          if (body.agentState && body.agentState.version > this.agentStateVersion) {
+            this.agentState = body.agentState.value ? decrypt(
+              this.encryptionKey,
+              this.encryptionVariant,
+              decodeBase64(body.agentState.value)
+            ) : null;
+            this.agentStateVersion = body.agentState.version;
+          }
+          this.emit("state-change", {
+            metadata: this.metadata,
+            agentState: this.agentState
+          });
+        }
+      } catch (err) {
+        this.emit("error", err);
+      }
+    });
+    this.socket.connect();
+  }
+  sendMessage(text, meta) {
+    const content = {
+      role: "user",
+      content: {
+        type: "text",
+        text
+      },
+      meta: {
+        sentFrom: "agentrejoin-agent",
+        ...meta
+      }
+    };
+    const encrypted = encodeBase64(encrypt(this.encryptionKey, this.encryptionVariant, content));
+    this.socket.emit("message", {
+      sid: this.sessionId,
+      message: encrypted
+    });
+  }
+  getMetadata() {
+    return this.metadata;
+  }
+  getAgentState() {
+    return this.agentState;
+  }
+  waitForConnect(timeoutMs = 1e4) {
+    return new Promise((resolve, reject) => {
+      if (this.socket.connected) {
+        resolve();
+        return;
+      }
+      const timeout = setTimeout(() => {
+        this.removeListener("connected", onConnect);
+        this.removeListener("connect_error", onError);
+        reject(new Error("Timeout waiting for socket connection"));
+      }, timeoutMs);
+      const onConnect = () => {
+        clearTimeout(timeout);
+        this.removeListener("connect_error", onError);
+        resolve();
+      };
+      const onError = (err) => {
+        clearTimeout(timeout);
+        this.removeListener("connected", onConnect);
+        reject(err);
+      };
+      this.once("connected", onConnect);
+      this.once("connect_error", onError);
+    });
+  }
+  waitForIdle(timeoutMs = 3e5) {
+    return new Promise((resolve, reject) => {
+      const cleanup = () => {
+        clearTimeout(timeout);
+        this.removeListener("state-change", onStateChange);
+        this.removeListener("disconnected", onDisconnect);
+      };
+      const result = checkIdleState(this.metadata, this.agentState);
+      if (result === "archived") {
+        reject(new Error("Session is archived"));
+        return;
+      }
+      if (result === true) {
+        resolve();
+        return;
+      }
+      const timeout = setTimeout(() => {
+        cleanup();
+        reject(new Error("Timeout waiting for agent to become idle"));
+      }, timeoutMs);
+      const onStateChange = () => {
+        const r = checkIdleState(this.metadata, this.agentState);
+        if (r === "archived") {
+          cleanup();
+          reject(new Error("Session is archived"));
+        } else if (r === true) {
+          cleanup();
+          resolve();
+        }
+      };
+      const onDisconnect = () => {
+        cleanup();
+        reject(new Error("Socket disconnected while waiting for agent to become idle"));
+      };
+      this.on("state-change", onStateChange);
+      this.on("disconnected", onDisconnect);
+    });
+  }
+  waitForTurnCompletion(timeoutMs = 3e5) {
+    return new Promise((resolve, reject) => {
+      let sawActivity = false;
+      let activeTurnId = null;
+      let sawTurnStart = false;
+      let sawNonReadyMessage = false;
+      const cleanup = () => {
+        clearTimeout(timeout);
+        this.removeListener("message", onMessage);
+        this.removeListener("state-change", onStateChange);
+        this.removeListener("disconnected", onDisconnect);
+      };
+      const finish = (error) => {
+        cleanup();
+        if (error) {
+          reject(error);
+        } else {
+          resolve();
+        }
+      };
+      const timeout = setTimeout(() => {
+        finish(new Error("Timeout waiting for agent turn completion"));
+      }, timeoutMs);
+      const onMessage = (message) => {
+        sawActivity = true;
+        const turnEvent = getTurnEvent(message.content);
+        if (turnEvent) {
+          if (turnEvent.type === "turn-start") {
+            sawTurnStart = true;
+            sawNonReadyMessage = true;
+            activeTurnId = turnEvent.turnId;
+            return;
+          }
+          if (activeTurnId == null || turnEvent.turnId == null || turnEvent.turnId === activeTurnId) {
+            finish();
+          }
+          return;
+        }
+        if (isReadyEvent(message.content)) {
+          if (sawTurnStart || sawNonReadyMessage) {
+            finish();
+          }
+          return;
+        }
+        sawNonReadyMessage = true;
+      };
+      const onStateChange = () => {
+        if (!sawActivity || sawTurnStart) {
+          return;
+        }
+        const result = checkIdleState(this.metadata, this.agentState);
+        if (result === "archived") {
+          finish(new Error("Session is archived"));
+        } else if (result === true) {
+          finish();
+        }
+      };
+      const onDisconnect = () => {
+        finish(new Error("Socket disconnected while waiting for agent turn completion"));
+      };
+      this.on("message", onMessage);
+      this.on("state-change", onStateChange);
+      this.on("disconnected", onDisconnect);
+    });
+  }
+  sendStop() {
+    this.socket.emit("session-end", {
+      sid: this.sessionId,
+      time: Date.now()
+    });
+  }
+  close() {
+    this.socket.close();
+  }
+}
+
+function formatTime(ts) {
+  if (!ts) return "-";
+  const date = new Date(ts);
+  const now = /* @__PURE__ */ new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffMin = Math.floor(diffMs / 6e4);
+  if (diffMin < 1) return "just now";
+  if (diffMin < 60) return `${diffMin}m ago`;
+  const diffHr = Math.floor(diffMin / 60);
+  if (diffHr < 24) return `${diffHr}h ago`;
+  const diffDay = Math.floor(diffHr / 24);
+  return `${diffDay}d ago`;
+}
+function formatIsoTime(ts) {
+  if (!ts) return "-";
+  const date = new Date(ts);
+  if (Number.isNaN(date.getTime())) return "-";
+  return date.toISOString();
+}
+function formatLastActive(ts) {
+  const relative = formatTime(ts);
+  const absolute = formatIsoTime(ts);
+  if (absolute === "-") return relative;
+  return `${relative} (${absolute})`;
+}
+function toMarkdownInline(value) {
+  const escaped = value.replace(/`/g, "\\`");
+  return `\`${escaped}\``;
+}
+function normalizeCodeBlockText(value) {
+  const text = value.trim().length > 0 ? value : "(empty)";
+  return text.replace(/```/g, "``\\`");
+}
+function normalizeListValue(value) {
+  return value.replace(/\r?\n/g, " ").trim();
+}
+function toNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function extractSessionSummary(meta) {
+  const direct = toNonEmptyString(meta.summary);
+  if (direct) return direct;
+  if (meta.summary != null && typeof meta.summary === "object") {
+    return toNonEmptyString(meta.summary.text);
+  }
+  return void 0;
+}
+function formatSessionTable(sessions) {
+  if (sessions.length === 0) {
+    return "## Sessions\n\n- Total: 0\n- Items: none";
+  }
+  const sections = sessions.map((s, index) => {
+    const meta = s.metadata ?? {};
+    const name = normalizeListValue(extractSessionSummary(meta) ?? toNonEmptyString(meta.tag) ?? "-");
+    const path = normalizeListValue(toNonEmptyString(meta.path) ?? "-");
+    const status = s.active ? "active" : "inactive";
+    const lastActive = normalizeListValue(formatLastActive(s.activeAt));
+    return [
+      `### Session ${index + 1}`,
+      `- ID: ${toMarkdownInline(s.id)}`,
+      `- Name: ${name}`,
+      `- Path: ${path}`,
+      `- Status: ${status}`,
+      `- Last Active: ${lastActive}`
+    ].join("\n");
+  });
+  return `## Sessions
+
+- Total: ${sessions.length}
+
+${sections.join("\n\n")}`;
+}
+function formatMachineTable(machines) {
+  if (machines.length === 0) {
+    return "## Machines\n\n- Total: 0\n- Items: none";
+  }
+  const sections = machines.map((machine, index) => {
+    const metadata = machine.metadata ?? {};
+    const daemonState = machine.daemonState ?? null;
+    const host = normalizeListValue(toNonEmptyString(metadata.host) ?? "-");
+    const platform = normalizeListValue(toNonEmptyString(metadata.platform) ?? "-");
+    const status = machine.active ? toNonEmptyString(daemonState?.status) ?? "online" : "offline";
+    const homeDir = normalizeListValue(toNonEmptyString(metadata.homeDir) ?? "-");
+    return [
+      `### Machine ${index + 1}`,
+      `- ID: ${toMarkdownInline(machine.id)}`,
+      `- Host: ${host}`,
+      `- Platform: ${platform}`,
+      `- Status: ${status}`,
+      `- Home: ${homeDir}`,
+      `- Last Active: ${normalizeListValue(formatLastActive(machine.activeAt))}`
+    ].join("\n");
+  });
+  return `## Machines
+
+- Total: ${machines.length}
+
+${sections.join("\n\n")}`;
+}
+function formatSessionStatus(session) {
+  const meta = session.metadata ?? {};
+  const state = session.agentState ?? null;
+  const tag = toNonEmptyString(meta.tag);
+  const summary = extractSessionSummary(meta);
+  const path = toNonEmptyString(meta.path);
+  const host = toNonEmptyString(meta.host);
+  const lifecycleState = toNonEmptyString(meta.lifecycleState);
+  const lines = [
+    "## Session Status",
+    "",
+    `- Session ID: ${toMarkdownInline(session.id)}`
+  ];
+  if (tag) lines.push(`- Tag: ${tag}`);
+  if (summary) lines.push(`- Summary: ${summary}`);
+  if (path) lines.push(`- Path: ${path}`);
+  if (host) lines.push(`- Host: ${host}`);
+  if (lifecycleState) lines.push(`- Lifecycle: ${lifecycleState}`);
+  lines.push(`- Active: ${session.active ? "yes" : "no"}`);
+  lines.push(`- Last Active: ${formatLastActive(session.activeAt)}`);
+  if (state) {
+    const requests = state.requests != null && typeof state.requests === "object" ? Object.keys(state.requests).length : 0;
+    const busy = state.controlledByUser === true || requests > 0;
+    const agentStatus = busy ? "busy" : "idle";
+    lines.push(`- Agent: ${agentStatus}`);
+    if (requests > 0) {
+      lines.push(`- Pending Requests: ${requests}`);
+    }
+  } else {
+    lines.push("- Agent: no state");
+  }
+  return lines.join("\n");
+}
+function formatMessageHistory(messages) {
+  if (messages.length === 0) {
+    return "## Message History\n\n- Count: 0\n- Items: none";
+  }
+  const sections = messages.map((msg, index) => {
+    const content = msg.content;
+    const role = content?.role ?? "unknown";
+    const timestamp = formatIsoTime(msg.createdAt);
+    let text;
+    if (content?.content && typeof content.content === "object" && content.content.text) {
+      text = String(content.content.text);
+    } else if (content?.content && typeof content.content === "string") {
+      text = content.content;
+    } else {
+      text = JSON.stringify(content);
+    }
+    return [
+      `### Message ${index + 1}`,
+      `- ID: ${toMarkdownInline(msg.id)}`,
+      `- Time: ${timestamp}`,
+      `- Role: ${role}`,
+      "- Text:",
+      "```text",
+      normalizeCodeBlockText(text),
+      "```"
+    ].join("\n");
+  });
+  return `## Message History
+
+- Count: ${messages.length}
+
+${sections.join("\n\n")}`;
+}
+function formatJson(data) {
+  return JSON.stringify(data, (key, value) => {
+    if (key === "encryption" || key === "dataEncryptionKey") return void 0;
+    if (value instanceof Uint8Array) {
+      return Buffer.from(value).toString("base64");
+    }
+    return value;
+  }, 2);
+}
+
+const SUPPORTED_AGENTS = ["claude", "codex", "gemini", "openclaw", "agy"];
+function resolveByPrefix(items, value, label) {
+  if (!value || value.trim().length === 0) {
+    throw new Error(`${label} is required`);
+  }
+  const matches = items.filter((item) => item.id.startsWith(value));
+  if (matches.length === 0) {
+    throw new Error(`No ${label.toLowerCase()} found matching "${value}"`);
+  }
+  if (matches.length > 1) {
+    throw new Error(`Ambiguous ${label.toLowerCase()} "${value}" matches ${matches.length} records. Be more specific.`);
+  }
+  return matches[0];
+}
+async function resolveSession(config, creds, sessionId) {
+  const sessions = await listSessions(config, creds);
+  return resolveByPrefix(sessions, sessionId, "Session ID");
+}
+async function resolveMachine(config, creds, machineId) {
+  const machines = await listMachines(config, creds);
+  return resolveByPrefix(machines, machineId, "Machine ID");
+}
+function createClient(session, creds, config) {
+  return new SessionClient({
+    sessionId: session.id,
+    encryptionKey: session.encryption.key,
+    encryptionVariant: session.encryption.variant,
+    token: creds.token,
+    serverUrl: config.serverUrl,
+    initialAgentState: session.agentState ?? null
+  });
+}
+function resolveRemotePath(rawPath, machine) {
+  const metadata = machine.metadata ?? {};
+  const homeDir = typeof metadata.homeDir === "string" && metadata.homeDir.trim().length > 0 ? metadata.homeDir : void 0;
+  const path = rawPath ?? homeDir;
+  if (!path) {
+    throw new Error("Machine metadata does not include a home directory. Pass --path explicitly.");
+  }
+  if (path === "~") {
+    if (!homeDir) {
+      throw new Error("Machine metadata does not include a home directory, so `~` cannot be resolved. Pass an absolute --path.");
+    }
+    return homeDir;
+  }
+  if (path.startsWith("~/")) {
+    if (!homeDir) {
+      throw new Error("Machine metadata does not include a home directory, so `~/...` cannot be resolved. Pass an absolute --path.");
+    }
+    const normalizedHome = homeDir.endsWith("/") || homeDir.endsWith("\\") ? homeDir.slice(0, -1) : homeDir;
+    const separator = normalizedHome.includes("\\") && !normalizedHome.includes("/") ? "\\" : "/";
+    return node_path.join(normalizedHome, path.slice(2)).replaceAll("/", separator);
+  }
+  return path;
+}
+function resolveSessionMachineId(session) {
+  const metadata = session.metadata ?? {};
+  if (typeof metadata.machineId !== "string" || metadata.machineId.trim().length === 0) {
+    throw new Error(`Session ${session.id} is missing machine metadata and cannot be resumed.`);
+  }
+  return metadata.machineId;
+}
+function ensureMachineCanResume(machine) {
+  const metadata = machine.metadata ?? {};
+  if (metadata.resumeSupport?.rpcAvailable === true) {
+    return;
+  }
+  if (metadata.resumeSupport?.agentRejoinAgentAuthenticated === false) {
+    throw new Error("Resume is unavailable on this machine. Run `agentrejoin-agent auth login` in that machine environment first.");
+  }
+  throw new Error("Resume RPC is unavailable on this machine right now.");
+}
+const program = new commander.Command();
+program.name("agentrejoin-agent").description("CLI client for controlling AgentRejoin sessions remotely").version("0.1.0");
+program.command("auth").description("Manage authentication").addCommand(
+  new commander.Command("login").description("Authenticate via QR code").action(async () => {
+    const config = loadConfig();
+    await authLogin(config);
+  })
+).addCommand(
+  new commander.Command("logout").description("Clear stored credentials").action(async () => {
+    const config = loadConfig();
+    await authLogout(config);
+  })
+).addCommand(
+  new commander.Command("status").description("Show authentication status").action(async () => {
+    const config = loadConfig();
+    await authStatus(config);
+  })
+);
+program.command("machines").description("List all machines").option("--active", "Show only active machines").option("--json", "Output as JSON").action(async (opts) => {
+  const config = loadConfig();
+  const creds = requireCredentials(config);
+  const machines = await listMachines(config, creds);
+  const filtered = opts.active ? machines.filter((machine) => machine.active) : machines;
+  if (opts.json) {
+    console.log(formatJson(filtered));
+  } else {
+    console.log(formatMachineTable(filtered));
+  }
+});
+program.command("list").description("List all sessions").option("--active", "Show only active sessions").option("--json", "Output as JSON").action(async (opts) => {
+  const config = loadConfig();
+  const creds = requireCredentials(config);
+  const sessions = opts.active ? await listActiveSessions(config, creds) : await listSessions(config, creds);
+  if (opts.json) {
+    console.log(formatJson(sessions));
+  } else {
+    console.log(formatSessionTable(sessions));
+  }
+});
+program.command("status").description("Get live session state").argument("<session-id>", "Session ID or prefix").option("--json", "Output as JSON").action(async (sessionId, opts) => {
+  const config = loadConfig();
+  const creds = requireCredentials(config);
+  const session = await resolveSession(config, creds, sessionId);
+  const client = createClient(session, creds, config);
+  let liveData = false;
+  try {
+    await new Promise((resolve) => {
+      let resolved = false;
+      const done = () => {
+        if (resolved) return;
+        resolved = true;
+        clearTimeout(timeout);
+        client.removeAllListeners("state-change");
+        client.removeAllListeners("connect_error");
+        resolve();
+      };
+      const timeout = setTimeout(done, 3e3);
+      client.once("state-change", (data) => {
+        session.metadata = data.metadata ?? session.metadata;
+        session.agentState = data.agentState ?? session.agentState;
+        liveData = true;
+        done();
+      });
+      client.once("connect_error", () => {
+        done();
+      });
+    });
+  } finally {
+    client.close();
+  }
+  if (opts.json) {
+    console.log(formatJson(session));
+  } else {
+    if (!liveData) {
+      console.log("> Note: showing cached data (could not get live status).");
+    }
+    console.log(formatSessionStatus(session));
+  }
+});
+program.command("spawn").description("Spawn a new session on a machine").requiredOption("--machine <machine-id>", "Machine ID or prefix").option("--path <path>", "Working directory path (defaults to machine home directory)").option("--agent <agent>", `Agent to start (${SUPPORTED_AGENTS.join(", ")})`, (value) => {
+  if (!SUPPORTED_AGENTS.includes(value)) {
+    throw new Error(`--agent must be one of: ${SUPPORTED_AGENTS.join(", ")}`);
+  }
+  return value;
+}).option("--create-dir", "Allow creating the directory if it does not exist").option("--json", "Output as JSON").action(async (opts) => {
+  const config = loadConfig();
+  const creds = requireCredentials(config);
+  const machine = await resolveMachine(config, creds, opts.machine);
+  const directory = resolveRemotePath(opts.path, machine);
+  const result = await spawnSessionOnMachine(config, machine, creds.token, {
+    directory,
+    approvedNewDirectoryCreation: opts.createDir,
+    agent: opts.agent
+  });
+  const payload = {
+    machineId: machine.id,
+    directory,
+    agent: opts.agent ?? null,
+    ...result
+  };
+  if (opts.json) {
+    console.log(formatJson(payload));
+    if (result.type !== "success") {
+      process.exitCode = 1;
+    }
+    return;
+  }
+  switch (result.type) {
+    case "success":
+      console.log([
+        "## Session Spawned",
+        "",
+        `- Machine ID: \`${machine.id}\``,
+        `- Session ID: \`${result.sessionId}\``,
+        `- Path: ${directory}`,
+        `- Agent: ${opts.agent ?? "default"}`
+      ].join("\n"));
+      break;
+    case "requestToApproveDirectoryCreation":
+      throw new Error(`The directory '${result.directory}' does not exist. Re-run with --create-dir to allow creating it.`);
+    case "error":
+      throw new Error(result.errorMessage);
+  }
+});
+program.command("resume").description("Resume a session on its original machine").argument("<session-id>", "Session ID or prefix").option("--json", "Output as JSON").action(async (sessionId, opts) => {
+  const config = loadConfig();
+  const creds = requireCredentials(config);
+  const session = await resolveSession(config, creds, sessionId);
+  const machineId = resolveSessionMachineId(session);
+  const machine = await resolveMachine(config, creds, machineId);
+  ensureMachineCanResume(machine);
+  const result = await resumeSessionOnMachine(config, machine, creds.token, session.id);
+  const payload = {
+    sourceSessionId: session.id,
+    machineId: machine.id,
+    ...result
+  };
+  if (opts.json) {
+    console.log(formatJson(payload));
+    if (result.type !== "success") {
+      process.exitCode = 1;
+    }
+    return;
+  }
+  switch (result.type) {
+    case "success":
+      console.log([
+        "## Session Resumed",
+        "",
+        `- Machine ID: \`${machine.id}\``,
+        `- Source Session ID: \`${session.id}\``,
+        `- Resumed Session ID: \`${result.sessionId}\``
+      ].join("\n"));
+      break;
+    case "requestToApproveDirectoryCreation":
+      throw new Error(`Resume unexpectedly requested directory creation for '${result.directory}'. Resume should reuse the saved path.`);
+    case "error":
+      throw new Error(result.errorMessage);
+  }
+});
+program.command("create").description("Create a new session").requiredOption("--tag <tag>", "Session tag").option("--path <path>", "Working directory path").option("--json", "Output as JSON").action(async (opts) => {
+  const config = loadConfig();
+  const creds = requireCredentials(config);
+  const metadata = {
+    tag: opts.tag,
+    path: opts.path ?? process.cwd(),
+    host: node_os.hostname()
+  };
+  const session = await createSession(config, creds, {
+    tag: opts.tag,
+    metadata
+  });
+  if (opts.json) {
+    console.log(formatJson(session));
+  } else {
+    console.log([
+      "## Session Created",
+      "",
+      `- Session ID: \`${session.id}\``
+    ].join("\n"));
+  }
+});
+program.command("send").description("Send a message to a session").argument("<session-id>", "Session ID or prefix").argument("<message>", "Message text").option("--yolo", "Send with permissionMode=yolo").option("--wait", "Wait for agent to become idle").option("--json", "Output as JSON").action(async (sessionId, message, opts) => {
+  const config = loadConfig();
+  const creds = requireCredentials(config);
+  const session = await resolveSession(config, creds, sessionId);
+  const permissionMode = opts.yolo ? "yolo" : null;
+  const client = createClient(session, creds, config);
+  try {
+    await client.waitForConnect();
+    const completion = opts.wait ? client.waitForTurnCompletion() : null;
+    client.sendMessage(message, permissionMode ? { permissionMode } : void 0);
+    if (completion) {
+      await completion;
+    } else {
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+  } finally {
+    client.close();
+  }
+  if (opts.json) {
+    console.log(formatJson({ sessionId: session.id, message, sent: true, permissionMode }));
+  } else {
+    console.log([
+      "## Message Sent",
+      "",
+      `- Session ID: \`${session.id}\``,
+      `- Permission Mode: ${permissionMode ?? "default"}`,
+      `- Waited For Idle: ${opts.wait ? "yes" : "no"}`
+    ].join("\n"));
+  }
+});
+program.command("history").description("Read message history").argument("<session-id>", "Session ID or prefix").option("--limit <n>", "Limit number of messages", (v) => {
+  const n = parseInt(v, 10);
+  if (isNaN(n) || n <= 0) throw new Error("--limit must be a positive integer");
+  return n;
+}).option("--json", "Output as JSON").action(async (sessionId, opts) => {
+  const config = loadConfig();
+  const creds = requireCredentials(config);
+  const session = await resolveSession(config, creds, sessionId);
+  let messages = await getSessionMessages(config, creds, session.id, session.encryption);
+  messages.sort((a, b) => a.createdAt - b.createdAt);
+  if (opts.limit && opts.limit > 0) {
+    messages = messages.slice(-opts.limit);
+  }
+  if (opts.json) {
+    console.log(formatJson(messages));
+  } else {
+    console.log(formatMessageHistory(messages));
+  }
+});
+program.command("stop").description("Stop a session").argument("<session-id>", "Session ID or prefix").action(async (sessionId) => {
+  const config = loadConfig();
+  const creds = requireCredentials(config);
+  const session = await resolveSession(config, creds, sessionId);
+  const client = createClient(session, creds, config);
+  try {
+    await client.waitForConnect();
+    client.sendStop();
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  } finally {
+    client.close();
+  }
+  console.log([
+    "## Session Stopped",
+    "",
+    `- Session ID: \`${session.id}\``
+  ].join("\n"));
+});
+program.command("wait").description("Wait for agent to become idle").argument("<session-id>", "Session ID or prefix").option("--timeout <seconds>", "Timeout in seconds", (v) => {
+  const n = parseInt(v, 10);
+  if (isNaN(n) || n <= 0) throw new Error("--timeout must be a positive integer");
+  return n;
+}, 300).action(async (sessionId, opts) => {
+  const config = loadConfig();
+  const creds = requireCredentials(config);
+  const session = await resolveSession(config, creds, sessionId);
+  const client = createClient(session, creds, config);
+  try {
+    await client.waitForConnect();
+    await client.waitForIdle(opts.timeout * 1e3);
+    console.log([
+      "## Session Idle",
+      "",
+      `- Session ID: \`${session.id}\``
+    ].join("\n"));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(msg);
+    process.exitCode = 1;
+  } finally {
+    client.close();
+  }
+});
+program.parseAsync(process.argv).catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exitCode = 1;
+});