@amaster.ai/employee-runtime-connector 0.1.0-beta.0

package/dist/amaster-runtime.mjs

@@ -0,0 +1,1005 @@
+#!/usr/bin/env node
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { homedir, hostname } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const CONNECTOR_VERSION = "0.1.0-beta.0";
+
+const CAPABILITIES = [
+  "remote_registration",
+  "heartbeat",
+  "executor_discovery",
+  "workspace_binding",
+  "run_wakeup",
+  "model_call",
+  "run_cancel",
+  "run_terminate",
+  "logs_cost_workspace_status",
+];
+
+const CONFIG_KEY_MAP = new Map([
+  ["server_url", "AMASTER_EMPLOYEE_SERVER_URL"],
+  ["server", "AMASTER_EMPLOYEE_SERVER_URL"],
+  ["app_url", "AMASTER_EMPLOYEE_SERVER_URL"],
+  ["connector_token", "AMASTER_CONNECTOR_TOKEN"],
+  ["token", "AMASTER_CONNECTOR_TOKEN"],
+  ["auth_header", "AMASTER_CONNECTOR_AUTH_HEADER"],
+  ["company_id", "AMASTER_COMPANY_ID"],
+  ["company", "AMASTER_COMPANY_ID"],
+  ["device_name", "AMASTER_CONNECTOR_NAME"],
+  ["connector_name", "AMASTER_CONNECTOR_NAME"],
+  ["machine_id", "AMASTER_MACHINE_ID"],
+  ["workspace_allowlist", "AMASTER_WORKSPACE_ALLOWLIST"],
+  ["workspace_bindings", "AMASTER_WORKSPACE_ALLOWLIST"],
+  ["workspace", "AMASTER_WORKSPACE_ALLOWLIST"],
+  ["executors", "AMASTER_EXECUTORS"],
+  ["executor_paths", "AMASTER_EXECUTOR_PATHS"],
+  ["max_concurrent_commands", "AMASTER_MAX_CONCURRENT_COMMANDS"],
+  ["maxconcurrentcommands", "AMASTER_MAX_CONCURRENT_COMMANDS"],
+  ["capabilities", "AMASTER_CAPABILITIES"],
+  ["network_domains", "AMASTER_NETWORK_DOMAINS"],
+  ["state_file", "AMASTER_DAEMON_STATE_FILE"],
+  ["poll_interval_seconds", "AMASTER_POLL_INTERVAL_SECONDS"],
+  ["lease_seconds", "AMASTER_LEASE_SECONDS"],
+  ["executor_timeout_seconds", "AMASTER_EXECUTOR_TIMEOUT_SECONDS"],
+  ["runtime_workspaces_root", "AMASTER_RUNTIME_WORKSPACES_ROOT"],
+  ["pi_provider", "AMASTER_PI_PROVIDER"],
+  ["pi_model", "AMASTER_PI_MODEL"],
+  ["pi_extra_args", "AMASTER_PI_EXTRA_ARGS"],
+  ["pi_coding_agent_dir", "PI_CODING_AGENT_DIR"],
+  ["pi_agent_home", "PI_AGENT_HOME"],
+  ["pi_agent_node", "PI_AGENT_NODE"],
+  ["heartbeat_log_mode", "AMASTER_HEARTBEAT_LOG_MODE"],
+]);
+
+const ENV_ORDER = [
+  "AMASTER_EMPLOYEE_SERVER_URL",
+  "AMASTER_CONNECTOR_TOKEN",
+  "AMASTER_CONNECTOR_AUTH_HEADER",
+  "AMASTER_COMPANY_ID",
+  "AMASTER_CONNECTOR_NAME",
+  "AMASTER_MACHINE_ID",
+  "AMASTER_WORKSPACE_ALLOWLIST",
+  "AMASTER_EXECUTORS",
+  "AMASTER_EXECUTOR_PATHS",
+  "AMASTER_MAX_CONCURRENT_COMMANDS",
+  "AMASTER_CAPABILITIES",
+  "AMASTER_NETWORK_DOMAINS",
+  "AMASTER_DAEMON_STATE_FILE",
+  "AMASTER_POLL_INTERVAL_SECONDS",
+  "AMASTER_LEASE_SECONDS",
+  "AMASTER_EXECUTOR_TIMEOUT_SECONDS",
+  "AMASTER_RUNTIME_WORKSPACES_ROOT",
+  "AMASTER_PI_PROVIDER",
+  "AMASTER_PI_MODEL",
+  "AMASTER_PI_EXTRA_ARGS",
+  "PI_CODING_AGENT_DIR",
+  "PI_AGENT_HOME",
+  "PI_AGENT_NODE",
+  "AMASTER_HEARTBEAT_LOG_MODE",
+];
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const defaultStateHome = process.env.AMASTER_RUNTIME_STATE_HOME
+  || process.env.AMASTER_RUNTIME_HOME
+  || join(homedir(), ".amaster-employee");
+const configDir = resolve(defaultStateHome);
+const updateDir = resolve(process.env.AMASTER_RUNTIME_UPDATE_HOME || "/run/amaster-runtime/updates");
+const envFile = process.env.AMASTER_RUNTIME_ENV_FILE || join(configDir, "runtime-daemon.env");
+const pidFile = process.env.AMASTER_RUNTIME_PID_FILE || join(configDir, "runtime-daemon.pid");
+const logFile = process.env.AMASTER_RUNTIME_LOG_FILE || join(configDir, "runtime-daemon.log");
+
+function exactSemver(value) {
+  const normalized = typeof value === "string" ? value.trim() : "";
+  const match = normalized.match(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/);
+  if (!match) return null;
+  const invalidNumericPrerelease = (match[4]?.split(".") ?? [])
+    .some((identifier) => /^\d+$/.test(identifier) && identifier.length > 1 && identifier.startsWith("0"));
+  return invalidNumericPrerelease ? null : normalized;
+}
+
+function delegateToActiveConnectorVersion(argv) {
+  const activeVersionPath = join(updateDir, "active-connector-version");
+  if (!existsSync(activeVersionPath)) return false;
+  const activeVersion = exactSemver(readFileSync(activeVersionPath, "utf8"));
+  if (!activeVersion || activeVersion === CONNECTOR_VERSION) return false;
+  const activeCliPath = join(
+    updateDir,
+    "packages",
+    activeVersion,
+    "node_modules",
+    "@amaster.ai",
+    "employee-runtime-connector",
+    "dist",
+    "amaster-runtime.mjs",
+  );
+  if (!existsSync(activeCliPath)) return false;
+  const result = spawnSync(process.execPath, [activeCliPath, ...argv], {
+    env: process.env,
+    stdio: "inherit",
+  });
+  if (result.error) throw result.error;
+  process.exit(result.status ?? (result.signal ? 1 : 0));
+}
+
+function normalizeKey(key) {
+  return String(key ?? "").trim().toLowerCase().replaceAll("-", "_");
+}
+
+function envKeyFor(key) {
+  const normalized = normalizeKey(key);
+  if (CONFIG_KEY_MAP.has(normalized)) return CONFIG_KEY_MAP.get(normalized);
+  if (/^AMASTER_[A-Z0-9_]+$/.test(String(key))) return String(key);
+  throw new Error(`Unknown config key: ${key}`);
+}
+
+function parseFlags(argv) {
+  const flags = {};
+  const positional = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) {
+      positional.push(token);
+      continue;
+    }
+    const eqIndex = token.indexOf("=");
+    if (eqIndex !== -1) {
+      flags[normalizeKey(token.slice(2, eqIndex))] = token.slice(eqIndex + 1);
+      continue;
+    }
+    const name = normalizeKey(token.slice(2));
+    const next = argv[index + 1];
+    if (next && !next.startsWith("--")) {
+      flags[name] = next;
+      index += 1;
+    } else {
+      flags[name] = "true";
+    }
+  }
+  return { flags, positional };
+}
+
+function unquoteEnvValue(value) {
+  const trimmed = String(value ?? "").trim();
+  if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1).replaceAll("'\\''", "'");
+  }
+  if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    return trimmed.slice(1, -1).replace(/\\(["\\$`])/g, "$1");
+  }
+  return trimmed;
+}
+
+function readConfig() {
+  if (!existsSync(envFile)) return {};
+  const config = {};
+  for (const rawLine of readFileSync(envFile, "utf8").split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const match = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/.exec(line);
+    if (!match) continue;
+    config[match[1]] = unquoteEnvValue(match[2]);
+  }
+  return config;
+}
+
+function shellQuote(value) {
+  const text = String(value ?? "");
+  if (text && /^[A-Za-z0-9_@%+=:,./~-]+$/.test(text)) return text;
+  return `'${text.replaceAll("'", "'\\''")}'`;
+}
+
+function defaultMachineId() {
+  return `${hostname()}-${process.platform}-${process.arch}`;
+}
+
+function normalizeServerUrl(value) {
+  const text = String(value ?? "").trim();
+  if (!text) throw new Error("server URL is required");
+  return text.replace(/\/+$/, "");
+}
+
+function splitList(value) {
+  return String(value ?? "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function uniqueList(entries) {
+  const seen = new Set();
+  const result = [];
+  for (const entry of entries) {
+    const trimmed = String(entry ?? "").trim();
+    if (!trimmed || seen.has(trimmed)) continue;
+    seen.add(trimmed);
+    result.push(trimmed);
+  }
+  return result;
+}
+
+function withDefaults(config) {
+  const runtimeWorkspacesRoot = config.AMASTER_RUNTIME_WORKSPACES_ROOT || join(configDir, "workspaces");
+  return {
+    AMASTER_EMPLOYEE_SERVER_URL: "http://127.0.0.1:3100",
+    AMASTER_CONNECTOR_NAME: `${hostname()}-amaster`,
+    AMASTER_MACHINE_ID: defaultMachineId(),
+    AMASTER_WORKSPACE_ALLOWLIST: runtimeWorkspacesRoot,
+    AMASTER_CAPABILITIES: CAPABILITIES.join(","),
+    AMASTER_NETWORK_DOMAINS: "self-host",
+    AMASTER_DAEMON_STATE_FILE: join(configDir, "runtime-connector-state.json"),
+    AMASTER_RUNTIME_WORKSPACES_ROOT: runtimeWorkspacesRoot,
+    AMASTER_POLL_INTERVAL_SECONDS: "10",
+    ...config,
+  };
+}
+
+function writeConfig(config) {
+  mkdirSync(dirname(envFile), { recursive: true });
+  const merged = withDefaults(config);
+  mkdirSync(merged.AMASTER_RUNTIME_WORKSPACES_ROOT, { recursive: true });
+  const lines = [
+    "# AMaster Runtime local daemon config",
+    "# Edit with `amaster-runtime config set <key> <value>` where possible.",
+  ];
+  for (const key of ENV_ORDER) {
+    if (merged[key] === undefined || merged[key] === null || merged[key] === "") continue;
+    lines.push(`${key}=${shellQuote(merged[key])}`);
+  }
+  writeFileSync(envFile, `${lines.join("\n")}\n`);
+}
+
+function readState(config) {
+  const statePath = config.AMASTER_DAEMON_STATE_FILE || join(configDir, "runtime-connector-state.json");
+  if (!existsSync(statePath)) return {};
+  try {
+    return JSON.parse(readFileSync(statePath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function writeState(config, state) {
+  const statePath = withDefaults(config).AMASTER_DAEMON_STATE_FILE || join(configDir, "runtime-connector-state.json");
+  mkdirSync(dirname(statePath), { recursive: true });
+  writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`);
+}
+
+function readPidInfo() {
+  if (!existsSync(pidFile)) return null;
+  try {
+    return JSON.parse(readFileSync(pidFile, "utf8"));
+  } catch {
+    const pid = Number(readFileSync(pidFile, "utf8").trim());
+    return Number.isFinite(pid) ? { pid } : null;
+  }
+}
+
+function writePidInfo(info) {
+  mkdirSync(dirname(pidFile), { recursive: true });
+  writeFileSync(pidFile, `${JSON.stringify(info, null, 2)}\n`);
+}
+
+function pidRunning(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function runningStatePid(state, config) {
+  const runtimeStatus = state && typeof state === "object" && state.runtimeStatus && typeof state.runtimeStatus === "object"
+    ? state.runtimeStatus
+    : null;
+  if (runtimeStatus?.daemon !== "running") return null;
+  const statusHostname = typeof runtimeStatus.hostname === "string" ? runtimeStatus.hostname.trim() : "";
+  if (statusHostname !== hostname()) return null;
+  const statusMachineId = typeof runtimeStatus.machineId === "string" ? runtimeStatus.machineId.trim() : "";
+  if (statusMachineId !== config.AMASTER_MACHINE_ID) return null;
+  const updatedAtMs = Date.parse(String(runtimeStatus.updatedAt ?? ""));
+  const pollIntervalSeconds = Number(runtimeStatus.pollIntervalSeconds);
+  const staleMs = Number.isFinite(pollIntervalSeconds) && pollIntervalSeconds > 0
+    ? Math.max(60_000, (pollIntervalSeconds * 2 + 30) * 1000)
+    : 60_000;
+  if (!Number.isFinite(updatedAtMs) || Date.now() - updatedAtMs > staleMs) return null;
+  const pid = Number(runtimeStatus.pid);
+  return pidRunning(pid) ? pid : null;
+}
+
+function daemonScriptPath() {
+  const candidates = [
+    join(scriptDir, "amaster-runtime-daemon.mjs"),
+    join(dirname(scriptDir), "scripts", "amaster-runtime-daemon.mjs"),
+  ];
+  const found = candidates.find((candidate) => existsSync(candidate));
+  if (!found) throw new Error("Cannot find amaster-runtime-daemon.mjs next to the runtime CLI.");
+  return found;
+}
+
+function daemonEnv(config = readConfig()) {
+  return {
+    ...process.env,
+    ...withDefaults(config),
+  };
+}
+
+function refreshManagedEnvConfig(config, env = process.env) {
+  for (const key of ENV_ORDER) {
+    if (env[key] !== undefined) config[key] = env[key];
+  }
+}
+
+function printConfig(config) {
+  const merged = withDefaults(config);
+  const safeEntries = [
+    ["server_url", merged.AMASTER_EMPLOYEE_SERVER_URL],
+    ["device_name", merged.AMASTER_CONNECTOR_NAME],
+    ["machine_id", merged.AMASTER_MACHINE_ID],
+    ["workspace_bindings", merged.AMASTER_WORKSPACE_ALLOWLIST],
+    ["managed_workspaces_root", merged.AMASTER_RUNTIME_WORKSPACES_ROOT],
+    ["executors", merged.AMASTER_EXECUTORS || "(auto discovery)"],
+    ["executor_paths", merged.AMASTER_EXECUTOR_PATHS || "(PATH only)"],
+    ["max_concurrent_commands", merged.AMASTER_MAX_CONCURRENT_COMMANDS || "(default: 1)"],
+    ["pi_provider", merged.AMASTER_PI_PROVIDER || "(default)"],
+    ["pi_model", merged.AMASTER_PI_MODEL || "(default)"],
+    ["pi_extra_args", merged.AMASTER_PI_EXTRA_ARGS || "(none)"],
+    ["pi_coding_agent_dir", merged.PI_CODING_AGENT_DIR || "(default)"],
+    ["pi_agent_home", merged.PI_AGENT_HOME || "(default)"],
+    ["pi_agent_node", merged.PI_AGENT_NODE || "(default)"],
+    ["heartbeat_log_mode", merged.AMASTER_HEARTBEAT_LOG_MODE || "(compact)"],
+    ["network_domains", merged.AMASTER_NETWORK_DOMAINS],
+    ["capabilities", merged.AMASTER_CAPABILITIES],
+    ["state_file", merged.AMASTER_DAEMON_STATE_FILE],
+    ["env_file", envFile],
+  ];
+  for (const [key, value] of safeEntries) {
+    process.stdout.write(`${key}: ${value}\n`);
+  }
+  process.stdout.write(`token: ${merged.AMASTER_CONNECTOR_TOKEN ? "(configured)" : "(not configured)"}\n`);
+  process.stdout.write(`auth_header: ${merged.AMASTER_CONNECTOR_AUTH_HEADER ? "(configured)" : "(not configured)"}\n`);
+}
+
+function workspaceBindingsFromConfig(config = readConfig()) {
+  return splitList(withDefaults(config).AMASTER_WORKSPACE_ALLOWLIST);
+}
+
+function writeWorkspaceBindings(config, bindings) {
+  config.AMASTER_WORKSPACE_ALLOWLIST = uniqueList(bindings).join(",");
+  writeConfig(config);
+}
+
+function commandSetup(argv) {
+  const { flags, positional } = parseFlags(argv);
+  const serverUrl = positional[0] || flags.server_url;
+  if (!serverUrl) throw new Error("Usage: amaster-runtime setup <server-url>");
+  const config = readConfig();
+  const envDefaults = {};
+  for (const key of ENV_ORDER) {
+    if (process.env[key] !== undefined) envDefaults[key] = process.env[key];
+  }
+  const defaultConfig = withDefaults({ ...envDefaults, ...config });
+  config.AMASTER_EMPLOYEE_SERVER_URL = normalizeServerUrl(serverUrl);
+  config.AMASTER_CONNECTOR_NAME = flags.device_name || flags.connector_name || defaultConfig.AMASTER_CONNECTOR_NAME;
+  config.AMASTER_MACHINE_ID = flags.machine_id || defaultConfig.AMASTER_MACHINE_ID;
+  config.AMASTER_RUNTIME_WORKSPACES_ROOT = flags.runtime_workspaces_root || defaultConfig.AMASTER_RUNTIME_WORKSPACES_ROOT;
+  config.AMASTER_WORKSPACE_ALLOWLIST = flags.workspace_allowlist || flags.workspace || defaultConfig.AMASTER_WORKSPACE_ALLOWLIST;
+  config.AMASTER_CAPABILITIES = flags.capabilities || defaultConfig.AMASTER_CAPABILITIES;
+  config.AMASTER_NETWORK_DOMAINS = flags.network_domains || defaultConfig.AMASTER_NETWORK_DOMAINS;
+  config.AMASTER_DAEMON_STATE_FILE = flags.state_file || defaultConfig.AMASTER_DAEMON_STATE_FILE;
+  if (flags.executors) config.AMASTER_EXECUTORS = flags.executors;
+  if (flags.executor_paths) config.AMASTER_EXECUTOR_PATHS = flags.executor_paths;
+  writeConfig(config);
+  process.stdout.write(`AMaster runtime config written: ${envFile}\n`);
+}
+
+function commandConfig(argv) {
+  const [action, key, ...valueParts] = argv;
+  const config = readConfig();
+  if (!action || action === "list" || action === "get") {
+    if (action === "get" && key) {
+      const envKey = envKeyFor(key);
+      process.stdout.write(`${withDefaults(config)[envKey] ?? ""}\n`);
+      return;
+    }
+    printConfig(config);
+    return;
+  }
+  if (action !== "set") {
+    throw new Error("Usage: amaster-runtime config set <key> <value>");
+  }
+  if (!key || valueParts.length === 0) {
+    throw new Error("Usage: amaster-runtime config set <key> <value>");
+  }
+  const envKey = envKeyFor(key);
+  const value = valueParts.join(" ").trim();
+  config[envKey] = envKey === "AMASTER_EMPLOYEE_SERVER_URL" ? normalizeServerUrl(value) : value;
+  writeConfig(config);
+  process.stdout.write(`${normalizeKey(key)} updated\n`);
+}
+
+async function commandWorkspace(argv) {
+  const [action = "list", maybePath, ...rest] = argv;
+  const config = readConfig();
+  const bindings = workspaceBindingsFromConfig(config);
+
+  if (action === "gc") {
+    const { flags } = parseFlags([maybePath, ...rest].filter(Boolean));
+    const dryRun = flags.dry_run === "true" || flags.dry === "true" || flags.n === "true";
+    if (!dryRun) {
+      throw new Error("Usage: amaster-runtime workspace gc --dry-run");
+    }
+    const passthroughArgs = ["workspace-gc-dry-run"];
+    if (flags.ttl_hours) passthroughArgs.push("--ttl-hours", flags.ttl_hours);
+    if (flags.root) passthroughArgs.push("--root", flags.root);
+    passthroughDaemon(passthroughArgs[0], passthroughArgs.slice(1));
+    return;
+  }
+
+  if (action === "list") {
+    if (bindings.length === 0) {
+      process.stdout.write("No workspace bindings configured\n");
+      return;
+    }
+    process.stdout.write("workspace_bindings:\n");
+    bindings.forEach((binding, index) => {
+      process.stdout.write(`  ${index + 1}. ${binding}\n`);
+    });
+    return;
+  }
+
+  if (action === "add") {
+    if (!maybePath) {
+      throw new Error("Usage: amaster-runtime workspace add <path> [--name <name>]");
+    }
+    const { flags } = parseFlags(rest);
+    const nextPath = resolve(maybePath);
+    writeWorkspaceBindings(config, [...bindings, nextPath]);
+    process.stdout.write(`workspace binding added: ${nextPath}\n`);
+    if (flags.name) {
+      process.stdout.write(`workspace name noted for display: ${flags.name}\n`);
+    }
+    return;
+  }
+
+  if (action === "remove") {
+    if (!maybePath) {
+      throw new Error("Usage: amaster-runtime workspace remove <path-or-name> [--force]");
+    }
+    const { flags } = parseFlags(rest);
+    const target = String(maybePath).trim();
+    const exact = bindings.filter((binding) => binding === target || resolve(binding) === resolve(target));
+    const basenameMatches = bindings.filter((binding) => binding.split("/").filter(Boolean).at(-1) === target);
+    const matches = uniqueList([...exact, ...basenameMatches]);
+    if (matches.length === 0) {
+      throw new Error(`Workspace binding not found: ${target}`);
+    }
+    if (matches.length > 1) {
+      throw new Error(`Workspace binding name is ambiguous: ${target}`);
+    }
+    const force = flags.force === "true" || flags.yes === "true";
+    const impact = await fetchWorkspaceBindingImpact(config, matches[0]);
+    const affectedAgents = Array.isArray(impact?.affectedAgents) ? impact.affectedAgents : [];
+    if (affectedAgents.length > 0 && !force) {
+      throw new Error([
+        `Workspace binding is used by ${affectedAgents.length} agent(s):`,
+        ...affectedAgents.map((agent) => {
+          const executor = agent.executorKind || "unknown executor";
+          const workspacePath = agent.workspacePath || "unknown workspace";
+          return `  - ${agent.name} (${executor}, ${workspacePath})`;
+        }),
+        `Re-run with --force to remove ${matches[0]} anyway.`,
+      ].join("\n"));
+    }
+    writeWorkspaceBindings(config, bindings.filter((binding) => binding !== matches[0]));
+    process.stdout.write(`workspace binding removed: ${matches[0]}\n`);
+    if (affectedAgents.length > 0) {
+      process.stdout.write(`affected_agents: ${affectedAgents.length}\n`);
+    }
+    return;
+  }
+
+  throw new Error("Usage: amaster-runtime workspace <list|add|remove>");
+}
+
+function commandDiscover() {
+  const result = spawnSync(process.execPath, [daemonScriptPath(), "render-register-payload"], {
+    env: daemonEnv(),
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (result.status !== 0) {
+    throw new Error(result.stderr.trim() || "AMaster runtime discovery failed");
+  }
+  const payload = JSON.parse(result.stdout);
+  process.stdout.write("executors:\n");
+  for (const executor of payload.executors ?? []) {
+    const version = executor.version ? ` (${executor.version})` : "";
+    process.stdout.write(`  - ${executor.kind}: ${executor.command}${version}\n`);
+  }
+  process.stdout.write("workspace_bindings:\n");
+  for (const binding of payload.workspaceBindings ?? []) {
+    process.stdout.write(`  - ${binding}\n`);
+  }
+}
+
+async function postJson(serverUrl, path, payload, headers = {}) {
+  const res = await fetch(`${serverUrl}${path}`, {
+    method: "POST",
+    headers: { "content-type": "application/json", ...headers },
+    body: JSON.stringify(payload),
+  });
+  const text = await res.text();
+  const body = text ? JSON.parse(text) : null;
+  if (!res.ok) {
+    throw new Error(`POST ${path} returned HTTP ${res.status}: ${text}`);
+  }
+  return body;
+}
+
+async function getJson(serverUrl, path, headers = {}) {
+  const res = await fetch(`${serverUrl}${path}`, {
+    method: "GET",
+    headers,
+  });
+  const text = await res.text();
+  const body = text ? JSON.parse(text) : null;
+  if (!res.ok) {
+    throw new Error(`GET ${path} returned HTTP ${res.status}: ${text}`);
+  }
+  return body;
+}
+
+function connectorAuthHeaders(config, state = readState(withDefaults(config))) {
+  if (config.AMASTER_CONNECTOR_AUTH_HEADER) {
+    return { authorization: config.AMASTER_CONNECTOR_AUTH_HEADER };
+  }
+  const token = state.connectorToken || config.AMASTER_CONNECTOR_TOKEN;
+  return token ? { authorization: `Bearer ${token}` } : {};
+}
+
+async function fetchWorkspaceBindingImpact(config, binding) {
+  const merged = withDefaults(config);
+  const state = readState(merged);
+  if (!state.connectorId) return null;
+  const headers = connectorAuthHeaders(merged, state);
+  if (!headers.authorization) return null;
+  const serverUrl = normalizeServerUrl(merged.AMASTER_EMPLOYEE_SERVER_URL);
+  return getJson(
+    serverUrl,
+    `/api/amaster/runtime-connectors/${encodeURIComponent(state.connectorId)}/workspace-bindings/impact?path=${encodeURIComponent(binding)}`,
+    headers,
+  );
+}
+
+function renderRegisterPayload(config) {
+  const result = spawnSync(process.execPath, [daemonScriptPath(), "render-register-payload"], {
+    env: daemonEnv(config),
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (result.status !== 0) {
+    throw new Error(result.stderr.trim() || "AMaster runtime discovery failed");
+  }
+  return JSON.parse(result.stdout);
+}
+
+async function commandManagedEnsure(argv) {
+  const { flags } = parseFlags(argv);
+  const config = readConfig();
+  if (flags.server || flags.server_url) {
+    config.AMASTER_EMPLOYEE_SERVER_URL = normalizeServerUrl(flags.server || flags.server_url);
+  }
+  const merged = withDefaults(config);
+  const serverUrl = normalizeServerUrl(merged.AMASTER_EMPLOYEE_SERVER_URL);
+  const provisionerKey = String(
+    flags.provisioner_key
+    ?? flags.provisioner
+    ?? process.env.AMASTER_MANAGED_RUNTIME_PROVISIONER_KEY
+    ?? process.env.AMASTER_PI_CLI_RUNTIME_PROVISIONER_KEY
+    ?? merged.AMASTER_MACHINE_ID,
+  ).trim();
+  const provisionToken = String(
+    flags.token
+    ?? process.env.AMASTER_BUILTIN_RUNTIME_PROVISION_TOKEN
+    ?? process.env.AMASTER_MANAGED_RUNTIME_PROVISION_TOKEN
+    ?? "",
+  ).trim();
+  if (!provisionerKey) {
+    throw new Error("Usage: amaster-runtime managed-ensure --provisioner-key <key>");
+  }
+  if (!provisionToken) {
+    throw new Error("AMASTER_BUILTIN_RUNTIME_PROVISION_TOKEN is required for managed runtime provisioning");
+  }
+
+  const payload = renderRegisterPayload(config);
+  const result = await postJson(
+    serverUrl,
+    "/api/amaster/runtime-connectors/managed/ensure",
+    {
+      ...payload,
+      provisionerKey,
+      metadata: {
+        ...payload.metadata,
+        source: "amaster-runtime-managed-ensure",
+      },
+    },
+    { authorization: `Bearer ${provisionToken}` },
+  );
+
+  config.AMASTER_EMPLOYEE_SERVER_URL = serverUrl;
+  writeConfig(config);
+  writeState(config, {
+    ...readState(withDefaults(config)),
+    connectorId: result.connectorId,
+    connectorToken: result.connectorToken,
+    companyId: null,
+    managed: true,
+    provisionerKey,
+    serverUrl,
+    connectedAt: new Date().toISOString(),
+  });
+
+  process.stdout.write(`AMaster managed runtime ensured: ${result.connectorId}\n`);
+  process.stdout.write(`${JSON.stringify({
+    status: result.status,
+    created: result.created,
+    credentialReissued: result.credentialReissued,
+    recoveredFromRevoked: result.recoveredFromRevoked,
+  }, null, 2)}\n`);
+}
+
+function heartbeatAfterConnect(config) {
+  const result = spawnSync(process.execPath, [daemonScriptPath(), "heartbeat"], {
+    env: daemonEnv(config),
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (result.status !== 0) {
+    throw new Error(result.stderr.trim() || "AMaster runtime heartbeat after connect failed");
+  }
+}
+
+function readDaemonStatusSummary(config) {
+  const result = spawnSync(process.execPath, [daemonScriptPath(), "status-summary"], {
+    env: daemonEnv(config),
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (result.status !== 0) return null;
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    return null;
+  }
+}
+
+function formatDaemonStatusValue(value, fallback = "-") {
+  return typeof value === "string" && value.trim() ? value : fallback;
+}
+
+function formatDaemonStatusLastOutput(entry) {
+  const lastOutputAt = formatDaemonStatusValue(entry?.lastOutputAt, null);
+  const stream = formatDaemonStatusValue(entry?.lastOutputStream, "unknown");
+  const bytes = typeof entry?.lastOutputBytes === "number" && Number.isFinite(entry.lastOutputBytes)
+    ? `${entry.lastOutputBytes}B`
+    : "0B";
+  return lastOutputAt ? `${lastOutputAt} ${stream} ${bytes}` : `${stream} ${bytes}`;
+}
+
+async function commandConnect(argv) {
+  const { flags, positional } = parseFlags(argv);
+  const code = positional[0] || flags.code;
+  if (!code) {
+    throw new Error("Usage: amaster-runtime connect <pairing-code>");
+  }
+
+  const config = readConfig();
+  if (flags.server || flags.server_url) {
+    config.AMASTER_EMPLOYEE_SERVER_URL = normalizeServerUrl(flags.server || flags.server_url);
+  }
+  const serverUrl = normalizeServerUrl(withDefaults(config).AMASTER_EMPLOYEE_SERVER_URL);
+  const payload = renderRegisterPayload(config);
+  const result = await postJson(
+    serverUrl,
+    `/api/amaster/runtime-connectors/pairing-codes/${encodeURIComponent(code)}/claim`,
+    payload,
+  );
+
+  config.AMASTER_EMPLOYEE_SERVER_URL = serverUrl;
+  if (result.companyId) config.AMASTER_COMPANY_ID = result.companyId;
+  if (Array.isArray(result.workspaceBindings) && result.workspaceBindings.length > 0) {
+    config.AMASTER_WORKSPACE_ALLOWLIST = result.workspaceBindings.join(",");
+  }
+  writeConfig(config);
+  writeState(config, {
+    ...readState(withDefaults(config)),
+    connectorId: result.connectorId,
+    connectorToken: result.connectorToken,
+    companyId: result.companyId ?? null,
+    serverUrl,
+    connectedAt: new Date().toISOString(),
+  });
+  heartbeatAfterConnect(config);
+
+  process.stdout.write(`AMaster runtime connected: ${result.connectorId}\n`);
+  if (Array.isArray(result.workspaceBindings)) {
+    process.stdout.write(`workspace_bindings: ${result.workspaceBindings.join(",")}\n`);
+  }
+}
+
+function commandLogin(argv) {
+  const { flags, positional } = parseFlags(argv);
+  const token = flags.token || positional[0];
+  const authHeader = flags.auth_header;
+  if (!token && !authHeader) {
+    throw new Error("Usage: amaster-runtime login --token <token>");
+  }
+  const config = readConfig();
+  if (token) {
+    config.AMASTER_CONNECTOR_TOKEN = token;
+    delete config.AMASTER_CONNECTOR_AUTH_HEADER;
+  }
+  if (authHeader) {
+    config.AMASTER_CONNECTOR_AUTH_HEADER = authHeader;
+    delete config.AMASTER_CONNECTOR_TOKEN;
+  }
+  writeConfig(config);
+  process.stdout.write("AMaster runtime auth saved\n");
+}
+
+function spawnDaemonForeground(args = []) {
+  const result = spawnSync(process.execPath, [daemonScriptPath(), ...args], {
+    env: {
+      ...daemonEnv(),
+      AMASTER_RUNTIME_DAEMON_FOREGROUND: "1",
+    },
+    stdio: "inherit",
+  });
+  process.exit(result.status ?? 1);
+}
+
+function commandDaemon(argv) {
+  const [action = "status", ...rest] = argv;
+  if (action === "status") {
+    commandStatus();
+    return;
+  }
+  if (action === "stop") {
+    commandStop();
+    return;
+  }
+  if (action === "run-once" || action === "once") {
+    spawnDaemonForeground(["run-once"]);
+    return;
+  }
+  if (action !== "start" && action !== "restart") {
+    throw new Error("Usage: amaster-runtime daemon <start|status|stop|restart|run-once>");
+  }
+
+  const { flags } = parseFlags(rest);
+  const config = readConfig();
+  refreshManagedEnvConfig(config);
+  if (flags.device_name) config.AMASTER_CONNECTOR_NAME = flags.device_name;
+  if (flags.machine_id) config.AMASTER_MACHINE_ID = flags.machine_id;
+  if (flags.workspace_allowlist) config.AMASTER_WORKSPACE_ALLOWLIST = flags.workspace_allowlist;
+  if (flags.executors) config.AMASTER_EXECUTORS = flags.executors;
+  if (flags.executor_paths) config.AMASTER_EXECUTOR_PATHS = flags.executor_paths;
+  writeConfig(config);
+
+  if (action === "restart") commandStop({ quiet: true });
+
+  const current = readPidInfo();
+  if (current?.pid && pidRunning(current.pid) && flags.force !== "true") {
+    process.stdout.write(`AMaster runtime daemon already running pid=${current.pid}\n`);
+    return;
+  }
+
+  if (flags.foreground === "true") {
+    spawnDaemonForeground(["start"]);
+    return;
+  }
+
+  mkdirSync(configDir, { recursive: true });
+  const fd = openSync(logFile, "a");
+  const child = spawn(process.execPath, [daemonScriptPath(), "start"], {
+    cwd: scriptDir,
+    detached: true,
+    env: {
+      ...daemonEnv(config),
+      AMASTER_RUNTIME_DAEMON_FOREGROUND: "0",
+    },
+    stdio: ["ignore", fd, fd],
+  });
+  child.unref();
+  closeSync(fd);
+  writePidInfo({
+    pid: child.pid,
+    startedAt: new Date().toISOString(),
+    serverUrl: withDefaults(config).AMASTER_EMPLOYEE_SERVER_URL,
+    logFile,
+  });
+  process.stdout.write(`AMaster runtime daemon started pid=${child.pid}\n`);
+  process.stdout.write(`log: ${logFile}\n`);
+}
+
+function commandStatus() {
+  const config = withDefaults(readConfig());
+  const pidInfo = readPidInfo();
+  const state = readState(config);
+  const foregroundPid = runningStatePid(state, config);
+  const runningPid = pidInfo?.pid && pidRunning(pidInfo.pid) ? pidInfo.pid : foregroundPid;
+  process.stdout.write("AMaster runtime daemon\n");
+  process.stdout.write(`status: ${runningPid ? "running" : "stopped"}\n`);
+  if (runningPid) process.stdout.write(`pid: ${runningPid}\n`);
+  else if (pidInfo?.pid) process.stdout.write(`pid: ${pidInfo.pid}\n`);
+  process.stdout.write(`server_url: ${config.AMASTER_EMPLOYEE_SERVER_URL}\n`);
+  process.stdout.write(`device_name: ${config.AMASTER_CONNECTOR_NAME}\n`);
+  process.stdout.write(`workspace_bindings: ${config.AMASTER_WORKSPACE_ALLOWLIST}\n`);
+  process.stdout.write(`managed_workspaces_root: ${config.AMASTER_RUNTIME_WORKSPACES_ROOT}\n`);
+  process.stdout.write(`executors: ${config.AMASTER_EXECUTORS || "(auto discovery)"}\n`);
+  process.stdout.write(`executor_paths: ${config.AMASTER_EXECUTOR_PATHS || "(PATH only)"}\n`);
+  process.stdout.write(`max_concurrent_commands: ${config.AMASTER_MAX_CONCURRENT_COMMANDS || "1"}\n`);
+  process.stdout.write(`connector_id: ${state.connectorId || "(not registered yet)"}\n`);
+  process.stdout.write(`connector_token: ${state.connectorToken || config.AMASTER_CONNECTOR_TOKEN ? "(configured)" : "(not configured)"}\n`);
+  const localSummary = readDaemonStatusSummary(config);
+  if (localSummary) {
+    process.stdout.write(`managed_workdirs: ${localSummary.managedWorkdirCount ?? 0}\n`);
+    process.stdout.write(`managed_workdir_bytes: ${localSummary.managedWorkdirBytes ?? 0}\n`);
+    process.stdout.write(`stale_managed_workdirs: ${localSummary.staleManagedWorkdirCount ?? 0}\n`);
+    process.stdout.write(`result_outbox_pending: ${localSummary.resultOutboxPending ?? 0}\n`);
+    process.stdout.write(`result_outbox_invalid: ${localSummary.resultOutboxInvalid ?? 0}\n`);
+    const recentManagedRuns = Array.isArray(localSummary.recentManagedRuns)
+      ? localSummary.recentManagedRuns
+      : [];
+    process.stdout.write(`recent_managed_runs: ${recentManagedRuns.length}\n`);
+    for (const entry of recentManagedRuns) {
+      process.stdout.write([
+        "recent_run:",
+        `run=${formatDaemonStatusValue(entry.runId)}`,
+        `command=${formatDaemonStatusValue(entry.commandId)}`,
+        `issue=${formatDaemonStatusValue(entry.issueId)}`,
+        `executor=${formatDaemonStatusValue(entry.executorKind)}`,
+        `last_output=${formatDaemonStatusLastOutput(entry)}`,
+        `outbox_pending=${entry.outboxPending ?? 0}`,
+        `manifest=${formatDaemonStatusValue(entry.manifestPath)}`,
+      ].join(" "));
+      process.stdout.write("\n");
+    }
+  }
+  process.stdout.write(`env_file: ${envFile}\n`);
+  process.stdout.write(`log_file: ${logFile}\n`);
+}
+
+function commandStop(opts = {}) {
+  const pidInfo = readPidInfo();
+  if (!pidInfo?.pid || !pidRunning(pidInfo.pid)) {
+    if (!opts.quiet) process.stdout.write("AMaster runtime daemon is not running\n");
+    rmSync(pidFile, { force: true });
+    return;
+  }
+  try {
+    process.kill(pidInfo.pid, "SIGTERM");
+  } catch {
+    // Process may exit between the status check and SIGTERM.
+  }
+  rmSync(pidFile, { force: true });
+  if (!opts.quiet) process.stdout.write(`AMaster runtime daemon stopped pid=${pidInfo.pid}\n`);
+}
+
+function passthroughDaemon(command, argv = []) {
+  const diagnosticEnv = command === "heartbeat"
+    ? {
+      AMASTER_HEARTBEAT_MODE: "diagnostic",
+      AMASTER_HEARTBEAT_DIAGNOSTIC_SOURCE: "amaster-runtime-cli",
+    }
+    : {};
+  const result = spawnSync(process.execPath, [daemonScriptPath(), command, ...argv], {
+    env: {
+      ...daemonEnv(),
+      ...diagnosticEnv,
+    },
+    stdio: "inherit",
+  });
+  process.exit(result.status ?? 1);
+}
+
+function commandSmoke(argv) {
+  const [action = "print", ...rest] = argv;
+  if (action !== "print" && action !== "print-smoke") {
+    throw new Error("Usage: amaster-runtime smoke print");
+  }
+  passthroughDaemon("print-smoke", rest);
+}
+
+function help() {
+  process.stdout.write(`Usage: amaster-runtime <command> [args]
+
+Commands:
+  setup <server-url>                         Write the local daemon config.
+  config list                                Show local config without secrets.
+  config set <key> <value>                   Set server_url, workspace_bindings, executors, executor_paths, etc.
+  workspace list                             Show authorized local workspace bindings.
+  workspace add <path> [--name <name>]       Add a local workspace binding.
+  workspace remove <path-or-name> [--force] Remove a local workspace binding after checking linked agents.
+  workspace gc --dry-run [--ttl-hours 72]    Preview managed runtime workdirs eligible for cleanup.
+  discover                                   Show detected executors and workspace bindings.
+  connect <pairing-code>                     Pair this terminal with a workspace code from the UI.
+  managed-ensure --provisioner-key <key>     Ensure a deployment-managed shared runner and rotate its connector token.
+  login --token <token>                      Store a reserved connector bearer token for authenticated deployments.
+  daemon start [--device-name <name>]        Start the local runtime daemon in the background.
+  daemon start --foreground                  Start the daemon in the foreground.
+  daemon status                              Show daemon pid, connector id, and config summary.
+  daemon stop                                Stop the background daemon.
+  smoke print                                Print register/poll/ack/result/ingest smoke commands.
+  register | heartbeat | poll | ack | result Pass through to amaster-runtime-daemon.mjs.
+
+Config file:
+  ${envFile}
+
+Advanced:
+  company_id is normally set by \`connect <pairing-code>\`; set it manually only for diagnostics or separate runtime homes.
+`);
+}
+
+async function main(argv) {
+  delegateToActiveConnectorVersion(argv);
+  const [command = "help", ...rest] = argv;
+  switch (command) {
+    case "setup":
+      commandSetup(rest);
+      break;
+    case "config":
+      commandConfig(rest);
+      break;
+    case "workspace":
+      await commandWorkspace(rest);
+      break;
+    case "discover":
+      commandDiscover();
+      break;
+    case "connect":
+      await commandConnect(rest);
+      break;
+    case "managed-ensure":
+      await commandManagedEnsure(rest);
+      break;
+    case "login":
+      commandLogin(rest);
+      break;
+    case "daemon":
+      commandDaemon(rest);
+      break;
+    case "smoke":
+      commandSmoke(rest);
+      break;
+    case "register":
+    case "heartbeat":
+    case "poll":
+    case "ack":
+    case "result":
+    case "print-smoke":
+      passthroughDaemon(command, rest);
+      break;
+    case "help":
+    case "--help":
+    case "-h":
+      help();
+      break;
+    case "--version":
+    case "-v":
+      process.stdout.write(`${CONNECTOR_VERSION}\n`);
+      break;
+    default:
+      throw new Error(`Unknown command: ${command}`);
+  }
+}
+
+main(process.argv.slice(2)).catch((err) => {
+  process.stderr.write(`${err.stack ?? err.message}\n`);
+  process.exit(1);
+});