@ai-development-environment/control-agent 0.0.76 → 0.0.78

package/README.md

@@ -21,6 +21,42 @@ control-agent enroll \
 control-agent run
 ```
 
+### Local and remote endpoints
+
+One control plane is often reachable at two addresses — a LAN address at the desk and a public or VPN address elsewhere. Configure both and the agent prefers the local one, moving to the remote one when the local address stops answering and the remote one is confirmed to be answering. A control plane that is down at _every_ configured address is not a failover: the agent keeps its session and the jobs running under it, and reconnects when the server comes back.
+
+```bash
+control-agent enroll \
+  --server http://192.168.1.10:3090 \
+  --remote-server https://control.example.com \
+  --enrollment-token <one-time-token>
+```
+
+Change the addresses on an enrolled agent, or print the current ones by passing no flags:
+
+```bash
+control-agent endpoints
+control-agent endpoints --remote-server https://control.example.com
+control-agent endpoints --clear-remote
+```
+
+The websocket address of each endpoint is derived from its server URL unless `--websocket-server` or `--remote-websocket-server` sets it explicitly.
+
+Changing a server address re-derives its websocket address, because one stored against the old server no longer points anywhere useful. If the websocket is served from somewhere other than `/graphql` on the same host and port — behind a reverse proxy, say — pass it alongside the new server address:
+
+```bash
+control-agent endpoints --server http://192.168.1.20:3090 --websocket-server ws://192.168.1.20:3092/graphql
+```
+
+### Enrollment
+
+```bash
+control-agent enrollment
+control-agent unenroll
+```
+
+`enrollment` reports whether this machine is enrolled and whether each configured endpoint answers for it. `unenroll` removes the local credential; the control plane still lists the agent until it is deleted there.
+
 Diagnostics:
 
 ```bash

package/dist/control-agent.js

@@ -4204,6 +4204,9 @@ var require_cross_spawn = __commonJS({
   }
 });
 
+// src/index.ts
+import { rm as rm14 } from "node:fs/promises";
+
 // src/config.ts
 import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -4226,6 +4229,32 @@ function defaultWebSocketServer(server) {
   url.hash = "";
   return url.toString();
 }
+function agentEndpoints(config) {
+  const endpoints2 = [
+    {
+      kind: "local",
+      server: config.server,
+      websocketServer: config.websocketServer
+    }
+  ];
+  if (config.remoteServer) {
+    endpoints2.push({
+      kind: "remote",
+      server: config.remoteServer,
+      websocketServer: config.remoteWebSocketServer ?? defaultWebSocketServer(config.remoteServer)
+    });
+  }
+  return endpoints2;
+}
+function configForEndpoint(config, endpoint) {
+  return {
+    ...config,
+    server: endpoint.server,
+    websocketServer: endpoint.websocketServer,
+    remoteServer: null,
+    remoteWebSocketServer: null
+  };
+}
 async function loadConfig(path = configPath()) {
   try {
     const value = JSON.parse(await readFile(path, "utf8"));
@@ -4249,107 +4278,6 @@ async function saveConfig(config, path = configPath()) {
   await rename(temporaryPath, path);
 }
 
-// ../agent-contract/src/index.ts
-var CCUSAGE_REPORT_JOB_KIND = "ccusage.report";
-var DEFAULT_AGENT_HEARTBEAT_INTERVAL_SECONDS = 15;
-var MIN_AGENT_HEARTBEAT_INTERVAL_SECONDS = 5;
-var MAX_AGENT_HEARTBEAT_INTERVAL_SECONDS = 300;
-var DEFAULT_AGENT_JOB_RECONCILIATION_INTERVAL_SECONDS = 15;
-var MIN_AGENT_JOB_RECONCILIATION_INTERVAL_SECONDS = 5;
-var MAX_AGENT_JOB_RECONCILIATION_INTERVAL_SECONDS = 3600;
-function objectValue(value, name) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`${name} must be an object`);
-  }
-  return value;
-}
-function numericValue(value, name) {
-  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
-    throw new Error(`${name} must be a non-negative finite number`);
-  }
-  return value;
-}
-function stringValue(value, name) {
-  if (typeof value !== "string" || value.length === 0) {
-    throw new Error(`${name} must be a non-empty string`);
-  }
-  return value;
-}
-function stringArray(value, name) {
-  if (!Array.isArray(value)) throw new Error(`${name} must be an array`);
-  return value.map((item, index) => stringValue(item, `${name}[${index}]`));
-}
-function tokenTotals(value, name) {
-  return {
-    inputTokens: numericValue(value.inputTokens, `${name}.inputTokens`),
-    outputTokens: numericValue(value.outputTokens, `${name}.outputTokens`),
-    cacheCreationTokens: numericValue(
-      value.cacheCreationTokens,
-      `${name}.cacheCreationTokens`
-    ),
-    cacheReadTokens: numericValue(
-      value.cacheReadTokens,
-      `${name}.cacheReadTokens`
-    ),
-    totalTokens: numericValue(value.totalTokens, `${name}.totalTokens`),
-    totalCost: numericValue(value.totalCost, `${name}.totalCost`)
-  };
-}
-function modelBreakdown(value, name) {
-  const model2 = objectValue(value, name);
-  return {
-    modelName: stringValue(model2.modelName, `${name}.modelName`),
-    inputTokens: numericValue(model2.inputTokens, `${name}.inputTokens`),
-    outputTokens: numericValue(model2.outputTokens, `${name}.outputTokens`),
-    cacheCreationTokens: numericValue(
-      model2.cacheCreationTokens,
-      `${name}.cacheCreationTokens`
-    ),
-    cacheReadTokens: numericValue(
-      model2.cacheReadTokens,
-      `${name}.cacheReadTokens`
-    ),
-    cost: numericValue(model2.cost, `${name}.cost`)
-  };
-}
-function dailyEntry(value, index) {
-  const name = `ccusage.daily[${index}]`;
-  const entry = objectValue(value, name);
-  const metadata = objectValue(entry.metadata, `${name}.metadata`);
-  if (!Array.isArray(entry.modelBreakdowns)) {
-    throw new Error(`${name}.modelBreakdowns must be an array`);
-  }
-  const period = stringValue(entry.period, `${name}.period`);
-  if (!/^\d{4}-\d{2}-\d{2}$/.test(period)) {
-    throw new Error(`${name}.period must use YYYY-MM-DD`);
-  }
-  return {
-    ...tokenTotals(entry, name),
-    agent: stringValue(entry.agent, `${name}.agent`),
-    period,
-    metadata: {
-      agents: stringArray(metadata.agents, `${name}.metadata.agents`)
-    },
-    modelBreakdowns: entry.modelBreakdowns.map(
-      (model2, modelIndex) => modelBreakdown(model2, `${name}.modelBreakdowns[${modelIndex}]`)
-    ),
-    modelsUsed: stringArray(entry.modelsUsed, `${name}.modelsUsed`)
-  };
-}
-function parseCcusageReport(value) {
-  const report = objectValue(value, "ccusage report");
-  if (!Array.isArray(report.daily)) {
-    throw new Error("ccusage.daily must be an array");
-  }
-  return {
-    daily: report.daily.map((entry, index) => dailyEntry(entry, index)),
-    totals: tokenTotals(
-      objectValue(report.totals, "ccusage.totals"),
-      "ccusage.totals"
-    )
-  };
-}
-
 // src/graphql-client.ts
 import { createReadStream } from "node:fs";
 import { rm, stat } from "node:fs/promises";
@@ -5588,6 +5516,140 @@ function subscribeToAgentEvents(client2, agentId, onEvent) {
   };
 }
 
+// src/endpoint-selection.ts
+var PROBE_TIMEOUT_MS = 5e3;
+var probeEndpoint = async (endpoint, config) => {
+  try {
+    const response = await new AgentGraphQLClient(
+      endpoint.server,
+      config.credential,
+      PROBE_TIMEOUT_MS,
+      config.headers
+    ).self();
+    return response.agentSelf?.id === config.agentId;
+  } catch {
+    return false;
+  }
+};
+async function selectAgentEndpoint(config, signal, probe = probeEndpoint) {
+  const endpoints2 = agentEndpoints(config);
+  if (endpoints2.length === 1) return endpoints2[0];
+  for (const endpoint of endpoints2) {
+    if (signal.aborted) break;
+    if (await probe(endpoint, config)) return endpoint;
+  }
+  return endpoints2[0];
+}
+async function findHealthyAlternate(config, active, signal, probe = probeEndpoint) {
+  for (const endpoint of agentEndpoints(config)) {
+    if (signal.aborted) break;
+    if (endpoint.server === active.server) continue;
+    if (await probe(endpoint, config)) return endpoint;
+  }
+  return void 0;
+}
+
+// ../agent-contract/src/index.ts
+var CCUSAGE_REPORT_JOB_KIND = "ccusage.report";
+var DEFAULT_AGENT_HEARTBEAT_INTERVAL_SECONDS = 15;
+var MIN_AGENT_HEARTBEAT_INTERVAL_SECONDS = 5;
+var MAX_AGENT_HEARTBEAT_INTERVAL_SECONDS = 300;
+var DEFAULT_AGENT_JOB_RECONCILIATION_INTERVAL_SECONDS = 15;
+var MIN_AGENT_JOB_RECONCILIATION_INTERVAL_SECONDS = 5;
+var MAX_AGENT_JOB_RECONCILIATION_INTERVAL_SECONDS = 3600;
+function objectValue(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${name} must be an object`);
+  }
+  return value;
+}
+function numericValue(value, name) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new Error(`${name} must be a non-negative finite number`);
+  }
+  return value;
+}
+function stringValue(value, name) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`${name} must be a non-empty string`);
+  }
+  return value;
+}
+function stringArray(value, name) {
+  if (!Array.isArray(value)) throw new Error(`${name} must be an array`);
+  return value.map((item, index) => stringValue(item, `${name}[${index}]`));
+}
+function tokenTotals(value, name) {
+  return {
+    inputTokens: numericValue(value.inputTokens, `${name}.inputTokens`),
+    outputTokens: numericValue(value.outputTokens, `${name}.outputTokens`),
+    cacheCreationTokens: numericValue(
+      value.cacheCreationTokens,
+      `${name}.cacheCreationTokens`
+    ),
+    cacheReadTokens: numericValue(
+      value.cacheReadTokens,
+      `${name}.cacheReadTokens`
+    ),
+    totalTokens: numericValue(value.totalTokens, `${name}.totalTokens`),
+    totalCost: numericValue(value.totalCost, `${name}.totalCost`)
+  };
+}
+function modelBreakdown(value, name) {
+  const model2 = objectValue(value, name);
+  return {
+    modelName: stringValue(model2.modelName, `${name}.modelName`),
+    inputTokens: numericValue(model2.inputTokens, `${name}.inputTokens`),
+    outputTokens: numericValue(model2.outputTokens, `${name}.outputTokens`),
+    cacheCreationTokens: numericValue(
+      model2.cacheCreationTokens,
+      `${name}.cacheCreationTokens`
+    ),
+    cacheReadTokens: numericValue(
+      model2.cacheReadTokens,
+      `${name}.cacheReadTokens`
+    ),
+    cost: numericValue(model2.cost, `${name}.cost`)
+  };
+}
+function dailyEntry(value, index) {
+  const name = `ccusage.daily[${index}]`;
+  const entry = objectValue(value, name);
+  const metadata = objectValue(entry.metadata, `${name}.metadata`);
+  if (!Array.isArray(entry.modelBreakdowns)) {
+    throw new Error(`${name}.modelBreakdowns must be an array`);
+  }
+  const period = stringValue(entry.period, `${name}.period`);
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(period)) {
+    throw new Error(`${name}.period must use YYYY-MM-DD`);
+  }
+  return {
+    ...tokenTotals(entry, name),
+    agent: stringValue(entry.agent, `${name}.agent`),
+    period,
+    metadata: {
+      agents: stringArray(metadata.agents, `${name}.metadata.agents`)
+    },
+    modelBreakdowns: entry.modelBreakdowns.map(
+      (model2, modelIndex) => modelBreakdown(model2, `${name}.modelBreakdowns[${modelIndex}]`)
+    ),
+    modelsUsed: stringArray(entry.modelsUsed, `${name}.modelsUsed`)
+  };
+}
+function parseCcusageReport(value) {
+  const report = objectValue(value, "ccusage report");
+  if (!Array.isArray(report.daily)) {
+    throw new Error("ccusage.daily must be an array");
+  }
+  return {
+    daily: report.daily.map((entry, index) => dailyEntry(entry, index)),
+    totals: tokenTotals(
+      objectValue(report.totals, "ccusage.totals"),
+      "ccusage.totals"
+    )
+  };
+}
+
 // src/inventory.ts
 import { statfsSync } from "node:fs";
 import {
@@ -12062,6 +12124,69 @@ var deleteSigningIdentity = async (payload, timeoutMs, signal) => {
 // src/handlers/ccusage.ts
 import { Buffer as Buffer2 } from "node:buffer";
 
+// src/executable-lookup.ts
+import { accessSync, constants } from "node:fs";
+import { homedir as homedir4 } from "node:os";
+import { delimiter, dirname as dirname3, join as join6 } from "node:path";
+function isExecutable(path) {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function toolDirectories(options = {}) {
+  const home = options.home ?? homedir4();
+  const platform2 = options.platform ?? process.platform;
+  return [
+    join6(home, ".local", "bin"),
+    join6(home, ".bun", "bin"),
+    join6(home, ".npm-global", "bin"),
+    // Where the opencode.ai install script puts its binary.
+    join6(home, ".opencode", "bin"),
+    // Global npm installs land next to the node binary running this agent.
+    options.nodeDirectory ?? dirname3(process.execPath),
+    ...platform2 === "darwin" ? ["/opt/homebrew/bin", "/usr/local/bin"] : []
+  ];
+}
+function findExecutable(name, options = {}) {
+  const env = options.env ?? process.env;
+  const platform2 = options.platform ?? process.platform;
+  const executable = platform2 === "win32" ? `${name}.exe` : name;
+  const directories = [
+    ...(env.PATH ?? "").split(delimiter).filter(Boolean),
+    ...toolDirectories(options)
+  ];
+  const override = options.overrideVariable ? env[options.overrideVariable]?.trim() : void 0;
+  const candidates = [
+    ...override ? [override] : [],
+    ...directories.map((directory) => join6(directory, executable))
+  ];
+  const canExecute = options.isExecutable ?? isExecutable;
+  return [...new Set(candidates)].find(canExecute);
+}
+function extendedPath(options = {}) {
+  const env = options.env ?? process.env;
+  const existing = (env.PATH ?? "").split(delimiter).filter(Boolean);
+  const additions = toolDirectories(options).filter(
+    (directory) => !existing.includes(directory)
+  );
+  return [...existing, ...additions].join(delimiter);
+}
+function repairToolPath(options = {}) {
+  const env = options.env ?? process.env;
+  env.PATH = extendedPath(options);
+}
+function prependPathDirectory(directory, env = process.env) {
+  const existing = (env.PATH ?? "").split(delimiter).filter(Boolean);
+  if (existing[0] === directory) return;
+  env.PATH = [
+    directory,
+    ...existing.filter((entry) => entry !== directory)
+  ].join(delimiter);
+}
+
 // src/process-runner.ts
 import { spawn as spawn5 } from "node:child_process";
 async function runProcess(options) {
@@ -12180,11 +12305,19 @@ function validateCcusagePayload(payload) {
 }
 async function runCcusage(payload, timeoutMs, signal, onLog) {
   validateCcusagePayload(payload);
+  const command3 = findExecutable("ccusage", {
+    overrideVariable: "CONTROL_AGENT_CCUSAGE_EXECUTABLE"
+  });
+  if (!command3) {
+    throw new Error(
+      "ccusage was not found. Install it (brew install ccusage, or npm install -g ccusage) or set CONTROL_AGENT_CCUSAGE_EXECUTABLE to its full path."
+    );
+  }
   const stdout = [];
   let stdoutBytes = 0;
   let exceededLimit = false;
   const result = await runProcess({
-    command: "ccusage",
+    command: command3,
     args: ["--json"],
     timeoutMs,
     signal,
@@ -12229,8 +12362,8 @@ import {
   stat as stat5,
   statfs
 } from "node:fs/promises";
-import { homedir as homedir4 } from "node:os";
-import { basename as basename4, dirname as dirname3, isAbsolute as isAbsolute4, join as join6, resolve as resolve4 } from "node:path";
+import { homedir as homedir5 } from "node:os";
+import { basename as basename4, dirname as dirname4, isAbsolute as isAbsolute4, join as join7, resolve as resolve4 } from "node:path";
 var successfulProcess4 = {
   exitCode: 0,
   signal: null,
@@ -12247,7 +12380,7 @@ function safeRelativePath3(value) {
 }
 async function configuredRoots(payload) {
   if (payload.mode === "DEFAULT") {
-    return [join6(homedir4(), "Library", "Developer", "Xcode", "DerivedData")];
+    return [join7(homedir5(), "Library", "Developer", "Xcode", "DerivedData")];
   }
   if (payload.mode === "ABSOLUTE") {
     if (!payload.path || !isAbsolute4(payload.path)) {
@@ -12309,10 +12442,10 @@ async function scanRoot(configuredRoot, timeoutMs, signal) {
   for (const child of children) {
     signal.throwIfAborted();
     if (!child.isDirectory()) continue;
-    const path = join6(rootPath2, child.name);
+    const path = join7(rootPath2, child.name);
     const information = await lstat2(path);
     const projectPath = await workspacePath(
-      join6(path, "info.plist"),
+      join7(path, "info.plist"),
       timeoutMs,
       signal
     );
@@ -12330,8 +12463,8 @@ async function scanRoot(configuredRoot, timeoutMs, signal) {
   return { entries, warning: null };
 }
 async function scanDeviceSupport(signal) {
-  const configuredRoot = join6(
-    process.env.ADE_IOS_DEVICE_SUPPORT_DIRECTORY ?? homedir4(),
+  const configuredRoot = join7(
+    process.env.ADE_IOS_DEVICE_SUPPORT_DIRECTORY ?? homedir5(),
     ...process.env.ADE_IOS_DEVICE_SUPPORT_DIRECTORY ? [] : ["Library", "Developer", "Xcode", "iOS DeviceSupport"]
   );
   signal.throwIfAborted();
@@ -12351,7 +12484,7 @@ async function scanDeviceSupport(signal) {
     const children = await readdir3(rootPath2, { withFileTypes: true });
     return {
       entries: children.filter((child) => child.isDirectory() && !child.isSymbolicLink()).map((child) => ({
-        path: join6(rootPath2, child.name),
+        path: join7(rootPath2, child.name),
         rootPath: rootPath2,
         name: child.name,
         kind: "DEVICE_SUPPORT",
@@ -12398,7 +12531,7 @@ function assertDirectChild(rootPath2, path) {
   }
   const root = resolve4(rootPath2);
   const target2 = resolve4(path);
-  if (target2 === root || dirname3(target2) !== root || basename4(target2) !== basename4(path)) {
+  if (target2 === root || dirname4(target2) !== root || basename4(target2) !== basename4(path)) {
     throw new Error("Build Data target must be a direct child of its root");
   }
 }
@@ -12412,7 +12545,7 @@ async function allocatedBytes(path, signal) {
   try {
     for await (const entry of directory) {
       signal.throwIfAborted();
-      total += await allocatedBytes(join6(path, entry.name), signal);
+      total += await allocatedBytes(join7(path, entry.name), signal);
     }
   } finally {
     await directory.close().catch(() => void 0);
@@ -12427,7 +12560,7 @@ var sizeBuildData = async (rawPayload, _timeoutMs, signal) => {
     try {
       assertDirectChild(target2.rootPath, target2.path);
       const rootPath2 = await realpath4(target2.rootPath);
-      if (rootPath2 !== resolve4(target2.rootPath) || dirname3(resolve4(target2.path)) !== rootPath2) {
+      if (rootPath2 !== resolve4(target2.rootPath) || dirname4(resolve4(target2.path)) !== rootPath2) {
         throw new Error("Build Data root changed since the scan");
       }
       const stats = await lstat2(target2.path);
@@ -12458,7 +12591,7 @@ var deleteBuildData = async (rawPayload, _timeoutMs, signal) => {
     try {
       assertDirectChild(target2.rootPath, target2.path);
       const rootPath2 = await realpath4(target2.rootPath);
-      if (rootPath2 !== resolve4(target2.rootPath) || dirname3(resolve4(target2.path)) !== rootPath2) {
+      if (rootPath2 !== resolve4(target2.rootPath) || dirname4(resolve4(target2.path)) !== rootPath2) {
         throw new Error("Build Data root changed since the scan");
       }
       const stats = await lstat2(target2.path);
@@ -12512,13 +12645,13 @@ async function inspectVolume(configuredPath, role, signal, allowMissing) {
     let candidate = resolve4(configuredPath);
     for (; ; ) {
       signal.throwIfAborted();
-      const parent = dirname3(candidate);
+      const parent = dirname4(candidate);
       if (parent === candidate) throw error;
       missingSegments.unshift(basename4(candidate));
       candidate = parent;
       try {
         inspectionPath = await realpath4(candidate);
-        canonicalPath = join6(inspectionPath, ...missingSegments);
+        canonicalPath = join7(inspectionPath, ...missingSegments);
         break;
       } catch (parentError) {
         if (parentError.code !== "ENOENT") {
@@ -12625,8 +12758,8 @@ async function collectAgentDiskSpace(configuration, signal) {
 
 // src/handlers/codebases.ts
 import { readdir as readdir4, realpath as realpath5, stat as stat6 } from "node:fs/promises";
-import { homedir as homedir5 } from "node:os";
-import { dirname as dirname4, join as join7, resolve as resolve5 } from "node:path";
+import { homedir as homedir6 } from "node:os";
+import { dirname as dirname5, join as join8, resolve as resolve5 } from "node:path";
 var successfulProcess5 = {
   exitCode: 0,
   signal: null,
@@ -12703,7 +12836,7 @@ function baseSnapshot(folder) {
 }
 async function fetchedAt(commonDirectory) {
   try {
-    return (await stat6(join7(commonDirectory, "FETCH_HEAD"))).mtime.toISOString();
+    return (await stat6(join8(commonDirectory, "FETCH_HEAD"))).mtime.toISOString();
   } catch {
     return null;
   }
@@ -12882,7 +13015,7 @@ async function inspectCodebase(selectedFolder, timeoutMs, signal, expectedOrigin
 }
 var browseCodebaseDirectories = async (payload) => {
   const input = codebaseBrowsePayload(payload);
-  const homePath = await realpath5(homedir5());
+  const homePath = await realpath5(homedir6());
   const path = await realpath5(input.path ? resolve5(input.path) : homePath);
   if (!(await stat6(path)).isDirectory())
     throw new Error("Path is not a directory");
@@ -12892,12 +13025,12 @@ var browseCodebaseDirectories = async (payload) => {
     if (candidate.isDirectory()) {
       entries.push({
         name: candidate.name,
-        path: join7(path, candidate.name),
+        path: join8(path, candidate.name),
         hidden: candidate.name.startsWith(".")
       });
     } else if (candidate.isSymbolicLink()) {
       try {
-        const target2 = join7(path, candidate.name);
+        const target2 = join8(path, candidate.name);
         if ((await stat6(target2)).isDirectory()) {
           entries.push({
             name: candidate.name,
@@ -12912,7 +13045,7 @@ var browseCodebaseDirectories = async (payload) => {
   entries.sort((first, second) => first.name.localeCompare(second.name));
   const listing = {
     path,
-    parentPath: dirname4(path) === path ? null : dirname4(path),
+    parentPath: dirname5(path) === path ? null : dirname5(path),
     homePath,
     entries: entries.slice(0, 1e3),
     truncated: entries.length > 1e3
@@ -13510,8 +13643,8 @@ import {
   stat as stat7,
   writeFile as writeFile5
 } from "node:fs/promises";
-import { homedir as homedir6 } from "node:os";
-import { dirname as dirname5, isAbsolute as isAbsolute5, join as join8, relative as relative6, resolve as resolve6, sep as sep6 } from "node:path";
+import { homedir as homedir7 } from "node:os";
+import { dirname as dirname6, isAbsolute as isAbsolute5, join as join9, relative as relative6, resolve as resolve6, sep as sep6 } from "node:path";
 import { promisify } from "node:util";
 var executeFile = promisify(execFile);
 var successfulProcess6 = {
@@ -13572,17 +13705,17 @@ async function directoryExists(path) {
   }
 }
 async function configuredTools(tools) {
-  const homePath = homedir6();
+  const homePath = homedir7();
   return Promise.all(
     AI_TOOLS.filter((tool) => tools.includes(tool)).map(async (tool) => ({
       tool,
-      configured: await directoryExists(join8(homePath, ...CONFIG_PATHS[tool])),
+      configured: await directoryExists(join9(homePath, ...CONFIG_PATHS[tool])),
       homePath
     }))
   );
 }
 function rootPath(location) {
-  const base = location.scope === "GLOBAL" ? homedir6() : location.folder;
+  const base = location.scope === "GLOBAL" ? homedir7() : location.folder;
   const parts = location.scope === "GLOBAL" ? GLOBAL_ROOTS[location.rootKind] : PROJECT_ROOTS[location.rootKind];
   const path = resolve6(base, ...parts);
   const normalizedBase = resolve6(base);
@@ -13599,7 +13732,7 @@ async function listPackageFiles(skillDirectory) {
   let totalBytes = 0;
   const visit = async (directory) => {
     for (const entry of await readdir5(directory, { withFileTypes: true })) {
-      const path = join8(directory, entry.name);
+      const path = join9(directory, entry.name);
       const metadata = await lstat3(path);
       if (metadata.isSymbolicLink()) {
         throw new Error(
@@ -13688,7 +13821,7 @@ async function scanRoot2(location, configured, targets, warnings) {
   const installations = [];
   for (const entry of await readdir5(root, { withFileTypes: true })) {
     if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
-    const directory = join8(root, entry.name);
+    const directory = join9(root, entry.name);
     try {
       const skillPackage = await readPackage(directory);
       const relativeDirectory = location.folder ? relative6(location.folder, directory).split(sep6).join("/") : "";
@@ -13767,7 +13900,7 @@ var readSkills = async (payload) => {
     }
     packages.push({
       ...request,
-      package: await readPackage(join8(root, request.skillName))
+      package: await readPackage(join9(root, request.skillName))
     });
   }
   return { ...successfulProcess6, packages };
@@ -13785,7 +13918,7 @@ async function gitExcludePath(folder) {
 }
 async function updateManagedExclude(folder, relativeSkillPath, present) {
   const excludePath = await gitExcludePath(folder);
-  await mkdir4(dirname5(excludePath), { recursive: true });
+  await mkdir4(dirname6(excludePath), { recursive: true });
   let existing = "";
   try {
     existing = await readFile5(excludePath, "utf8");
@@ -13829,18 +13962,18 @@ async function writePackage(location, skillPackage) {
     throw new Error("New skill copies may only be written to shared roots");
   }
   const root = rootPath(location);
-  const destination = join8(root, skillPackage.name);
+  const destination = join9(root, skillPackage.name);
   await assertUntracked(location, destination);
   await mkdir4(root, { recursive: true });
-  const temporary = join8(root, `.${skillPackage.name}.${randomUUID3()}.tmp`);
-  const backup = join8(root, `.${skillPackage.name}.${randomUUID3()}.bak`);
+  const temporary = join9(root, `.${skillPackage.name}.${randomUUID3()}.tmp`);
+  const backup = join9(root, `.${skillPackage.name}.${randomUUID3()}.bak`);
   await mkdir4(temporary, { recursive: true });
   try {
     for (const file of skillPackage.files) {
       const path = resolve6(temporary, ...file.path.split("/"));
       if (!path.startsWith(`${temporary}${sep6}`))
         throw new Error("Skill file escaped temporary directory");
-      await mkdir4(dirname5(path), { recursive: true });
+      await mkdir4(dirname6(path), { recursive: true });
       await writeFile5(path, Buffer.from(file.contentsBase64, "base64"));
       await chmod3(path, file.executable ? 493 : 420);
     }
@@ -13871,7 +14004,7 @@ var applySkills = async (payload) => {
   for (const operation of operations) {
     const root = rootPath(operation);
     const skillName = operation.kind === "WRITE" ? operation.package.name : operation.skillName;
-    const destination = join8(root, skillName);
+    const destination = join9(root, skillName);
     await assertUntracked(operation, destination);
     if (operation.kind === "WRITE") {
       await writePackage(operation, operation.package);
@@ -13901,8 +14034,8 @@ var applySkills = async (payload) => {
 
 // src/handlers/runs.ts
 import { readFile as readFile6, readdir as readdir6, stat as stat8 } from "node:fs/promises";
-import { homedir as homedir7 } from "node:os";
-import { join as join9 } from "node:path";
+import { homedir as homedir8 } from "node:os";
+import { join as join10 } from "node:path";
 var successfulProcess7 = {
   exitCode: 0,
   signal: null,
@@ -13917,7 +14050,7 @@ async function fileExists(path) {
   }
 }
 async function findClaudeSessionFile(nativeId, home) {
-  const projectsDir = join9(home, ".claude", "projects");
+  const projectsDir = join10(home, ".claude", "projects");
   let entries;
   try {
     entries = await readdir6(projectsDir, { withFileTypes: true });
@@ -13927,13 +14060,13 @@ async function findClaudeSessionFile(nativeId, home) {
   const target2 = `${nativeId}.jsonl`;
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
-    const candidate = join9(projectsDir, entry.name, target2);
+    const candidate = join10(projectsDir, entry.name, target2);
     if (await fileExists(candidate)) return candidate;
   }
   return null;
 }
 async function findCodexSessionFile(nativeId, home) {
-  const sessionsDir = join9(home, ".codex", "sessions");
+  const sessionsDir = join10(home, ".codex", "sessions");
   const suffix = `-${nativeId}.jsonl`;
   const walk = async (dir) => {
     let entries;
@@ -13943,7 +14076,7 @@ async function findCodexSessionFile(nativeId, home) {
       return null;
     }
     for (const entry of entries) {
-      const path = join9(dir, entry.name);
+      const path = join10(dir, entry.name);
       if (entry.isDirectory()) {
         const found = await walk(path);
         if (found) return found;
@@ -13960,7 +14093,7 @@ async function locateSessionFile(payload, home) {
 }
 var readRunSession = async (payload) => {
   const input = parseRunSessionReadPayload(payload);
-  const path = await locateSessionFile(input, homedir7());
+  const path = await locateSessionFile(input, homedir8());
   if (!path) {
     throw new Error(
       `No ${input.provider === "CLAUDE" ? "Claude" : "Codex"} session file found for this run on this agent`
@@ -13990,13 +14123,13 @@ import {
   writeFile as writeFile6
 } from "node:fs/promises";
 import { tmpdir as tmpdir5 } from "node:os";
-import { join as join11 } from "node:path";
+import { join as join12 } from "node:path";
 
 // src/runs/git-checkpoint.ts
 import { execFile as execFile2 } from "node:child_process";
 import { copyFile, mkdtemp as mkdtemp4, rm as rm7 } from "node:fs/promises";
 import { tmpdir as tmpdir4 } from "node:os";
-import { join as join10 } from "node:path";
+import { join as join11 } from "node:path";
 import { promisify as promisify2 } from "node:util";
 var execFileAsync = promisify2(execFile2);
 async function git2(cwd, args, env) {
@@ -14111,12 +14244,12 @@ async function captureGitCheckpoint(cwd, runId, kind) {
   const manifest = await optionalGit(cwd, ["status", "--porcelain=v2", "-z"]);
   const staged = await optionalGit(cwd, ["diff", "--cached", "--stat", "HEAD"]);
   const unstaged = await optionalGit(cwd, ["diff", "--stat", "HEAD"]);
-  const directory = await mkdtemp4(join10(tmpdir4(), "aide-run-index-"));
+  const directory = await mkdtemp4(join11(tmpdir4(), "aide-run-index-"));
   let worktreeTree = null;
   let refName = null;
   try {
     const actualIndex = await git2(cwd, ["rev-parse", "--git-path", "index"]);
-    const temporaryIndex = join10(directory, "index");
+    const temporaryIndex = join11(directory, "index");
     try {
       await copyFile(actualIndex, temporaryIndex);
     } catch {
@@ -14186,10 +14319,10 @@ var runWorkflowTerminal = async (payloadValue, timeoutMs, signal, onLog, context
   const information = await stat9(cwd);
   if (!information.isDirectory())
     throw new Error("Workflow working directory is not a directory");
-  const directory = await mkdtemp5(join11(tmpdir5(), "aide-workflow-"));
+  const directory = await mkdtemp5(join12(tmpdir5(), "aide-workflow-"));
   const extension2 = payload.interpreter === "NODE" ? "mjs" : "sh";
-  const scriptPath = join11(directory, `step.${extension2}`);
-  const sessionPath = join11(directory, "session.json");
+  const scriptPath = join12(directory, `step.${extension2}`);
+  const sessionPath = join12(directory, "session.json");
   try {
     await writeFile6(scriptPath, `${payload.script}
 `, { mode: 384 });
@@ -14282,7 +14415,7 @@ var runWorkflowGitCheckpoint = async (payloadValue, _timeoutMs, signal) => {
 import { createWriteStream as createWriteStream2, watch } from "node:fs";
 import { mkdtemp as mkdtemp6, open as open2, readFile as readFile8, realpath as realpath8, rm as rm9, stat as stat10 } from "node:fs/promises";
 import { tmpdir as tmpdir6 } from "node:os";
-import { basename as basename5, dirname as dirname6, isAbsolute as isAbsolute6, join as join12, relative as relative7 } from "node:path";
+import { basename as basename5, dirname as dirname7, isAbsolute as isAbsolute6, join as join13, relative as relative7 } from "node:path";
 import { spawn as spawn6 } from "node:child_process";
 var successfulProcess8 = {
   exitCode: 0,
@@ -14337,7 +14470,7 @@ async function rebaseInProgress(folder, timeoutMs, signal) {
     const candidate = pathResult.stdout.trim();
     if (!candidate) continue;
     try {
-      await stat10(isAbsolute6(candidate) ? candidate : join12(folder, candidate));
+      await stat10(isAbsolute6(candidate) ? candidate : join13(folder, candidate));
       return true;
     } catch {
     }
@@ -14357,7 +14490,7 @@ async function rebaseBranch(folder, timeoutMs, signal) {
     if (!candidate) continue;
     try {
       const headName = (await readFile8(
-        isAbsolute6(candidate) ? candidate : join12(folder, candidate),
+        isAbsolute6(candidate) ? candidate : join13(folder, candidate),
         "utf8"
       )).trim();
       if (headName.startsWith("refs/heads/")) {
@@ -15003,7 +15136,7 @@ async function comparisonSides(input, folder, timeoutMs, signal) {
   if (!input.path) return { before: null, after: null };
   const path = input.path;
   const previousPath = input.previousPath ?? path;
-  const currentPath = join12(folder, path);
+  const currentPath = join13(folder, path);
   if (input.scope === "UNTRACKED") {
     return { before: null, after: { kind: "FILE", path: currentPath } };
   }
@@ -15178,7 +15311,7 @@ async function inspectRequestedDiff(input, folder, timeoutMs, signal) {
   let patch;
   if (input.scope === "UNTRACKED") {
     const bounded = await readBoundedFile(
-      join12(folder, input.path),
+      join13(folder, input.path),
       MAX_DIFF_BYTES
     );
     const contents = bounded.contents;
@@ -15360,8 +15493,8 @@ var downloadWorktreeDiffAsset = async (payload, timeoutMs, signal, _onLog, conte
       if (!/^\d+$/.test(size) || Number(size) > 20 * 1024 * 1024) {
         throw new Error("Diff image exceeds the 20 MiB limit");
       }
-      temporaryDirectory = await mkdtemp6(join12(tmpdir6(), "ade-diff-image-"));
-      uploadPath = join12(temporaryDirectory, basename5(input.path));
+      temporaryDirectory = await mkdtemp6(join13(tmpdir6(), "ade-diff-image-"));
+      uploadPath = join13(temporaryDirectory, basename5(input.path));
       await writeGitObject(
         folder,
         selected.specification,
@@ -15624,8 +15757,8 @@ var branchWorktree = async (payload, timeoutMs, signal) => {
     timeoutMs,
     signal
   ) : input.candidates[0];
-  const targetFolder = input.action === "CREATE" ? join12(
-    dirname6(rootFolder),
+  const targetFolder = input.action === "CREATE" ? join13(
+    dirname7(rootFolder),
     `${basename5(rootFolder)}-${branch.replaceAll("/", "-")}`
   ) : changeFolder;
   if (input.action === "CREATE") {
@@ -15864,8 +15997,8 @@ var checkoutMovedWorktree = async (payload, timeoutMs, signal) => {
         `Branch ${input.branch} is already checked out in ${occupiedFolder}`
       );
     }
-    targetFolder = join12(
-      dirname6(rootFolder),
+    targetFolder = join13(
+      dirname7(rootFolder),
       `${basename5(rootFolder)}-${input.branch.replaceAll("/", "-")}`
     );
     try {
@@ -16804,7 +16937,7 @@ var CodebaseMonitor = class {
 // src/runs/run-manager.ts
 import { execFile as execFile4 } from "node:child_process";
 import { mkdir as mkdir6, rm as rm13 } from "node:fs/promises";
-import { dirname as dirname8, join as join17 } from "node:path";
+import { dirname as dirname10, join as join17 } from "node:path";
 import { promisify as promisify4 } from "node:util";
 
 // src/runs/journal.ts
@@ -16817,7 +16950,7 @@ import {
   rm as rm10,
   writeFile as writeFile7
 } from "node:fs/promises";
-import { dirname as dirname7, join as join13 } from "node:path";
+import { dirname as dirname8, join as join14 } from "node:path";
 var RunJournal = class {
   constructor(runId, attemptId) {
     this.runId = runId;
@@ -16836,13 +16969,13 @@ var RunJournal = class {
     this.attemptId = attemptId;
   }
   get directory() {
-    return join13(dirname7(configPath()), "runs", this.runId);
+    return join14(dirname8(configPath()), "runs", this.runId);
   }
   get eventsPath() {
-    return join13(this.directory, "events.jsonl");
+    return join14(this.directory, "events.jsonl");
   }
   get statePath() {
-    return join13(this.directory, "state.json");
+    return join14(this.directory, "state.json");
   }
   async load() {
     if (this.loaded) return;
@@ -16957,9 +17090,6 @@ var RunJournal = class {
 
 // src/runs/claude-adapter.ts
 import { randomUUID as randomUUID5 } from "node:crypto";
-import { accessSync, constants } from "node:fs";
-import { homedir as homedir8 } from "node:os";
-import { delimiter, join as join15 } from "node:path";
 
 // ../../node_modules/@anthropic-ai/claude-agent-sdk/sdk.mjs
 import { createRequire as RV } from "node:module";
@@ -42767,27 +42897,11 @@ function answerArrays(value) {
 }
 
 // src/runs/claude-adapter.ts
-function isExecutable(path) {
-  try {
-    accessSync(path, constants.X_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
 function findClaudeCodeExecutable(options = {}) {
-  const env = options.env ?? process.env;
-  const home = options.home ?? homedir8();
-  const platform2 = options.platform ?? process.platform;
-  const executable = platform2 === "win32" ? "claude.exe" : "claude";
-  const candidates = [
-    env.CONTROL_AGENT_CLAUDE_EXECUTABLE?.trim(),
-    ...(env.PATH ?? "").split(delimiter).filter(Boolean).map((directory) => join15(directory, executable)),
-    join15(home, ".local", "bin", executable),
-    ...platform2 === "darwin" ? ["/opt/homebrew/bin/claude", "/usr/local/bin/claude"] : []
-  ].filter((candidate) => Boolean(candidate));
-  const canExecute = options.isExecutable ?? isExecutable;
-  return [...new Set(candidates)].find(canExecute);
+  return findExecutable("claude", {
+    ...options,
+    overrideVariable: "CONTROL_AGENT_CLAUDE_EXECUTABLE"
+  });
 }
 var MessageQueue = class {
   values = [];
@@ -43205,10 +43319,24 @@ var CodexAppServer = class {
     this.initialized ??= this.start();
     return this.initialized;
   }
+  // The service PATH omits Homebrew and npm, so resolve the install once and
+  // use the absolute path for every codex invocation.
+  executable() {
+    const executable = findExecutable("codex", {
+      overrideVariable: "CONTROL_AGENT_CODEX_EXECUTABLE"
+    });
+    if (!executable) {
+      throw new Error(
+        "codex was not found. Install it (brew install codex, or npm install -g @openai/codex) or set CONTROL_AGENT_CODEX_EXECUTABLE to its full path."
+      );
+    }
+    return executable;
+  }
   async start() {
-    const modelCatalogPath = await this.createBundledModelCatalog();
+    const executable = this.executable();
+    const modelCatalogPath = await this.createBundledModelCatalog(executable);
     const modelCatalogDirectory = this.modelCatalogDirectory;
-    const child = spawn7("codex", codexAppServerArgs(modelCatalogPath), {
+    const child = spawn7(executable, codexAppServerArgs(modelCatalogPath), {
       stdio: ["pipe", "pipe", "pipe"],
       env: process.env
     });
@@ -43276,11 +43404,11 @@ var CodexAppServer = class {
       );
     }
   }
-  async createBundledModelCatalog() {
+  async createBundledModelCatalog(executable) {
     const directory = await mkdtemp7(join16(tmpdir7(), "aide-codex-models-"));
     try {
       const { stdout } = await execFileAsync2(
-        "codex",
+        executable,
         ["debug", "models", "--bundled"],
         {
           encoding: "utf8",
@@ -43718,6 +43846,7 @@ var CodexAdapter = class {
 };
 
 // src/runs/opencode-adapter.ts
+import { dirname as dirname9 } from "node:path";
 import { pathToFileURL } from "node:url";
 
 // ../../node_modules/@opencode-ai/sdk/dist/v2/gen/core/serverSentEvents.gen.js
@@ -49389,7 +49518,18 @@ var OpenCodeAdapter = class {
   };
   runtime;
   async client() {
-    this.runtime ??= await createOpencode();
+    if (!this.runtime) {
+      const executable = findExecutable("opencode", {
+        overrideVariable: "CONTROL_AGENT_OPENCODE_EXECUTABLE"
+      });
+      if (!executable) {
+        throw new Error(
+          "opencode was not found. Install it (brew install sst/tap/opencode, or npm install -g opencode-ai) or set CONTROL_AGENT_OPENCODE_EXECUTABLE to its full path."
+        );
+      }
+      prependPathDirectory(dirname9(executable));
+      this.runtime = await createOpencode();
+    }
     return this.runtime.client;
   }
   async catalog() {
@@ -50011,7 +50151,7 @@ var RunManager = class {
         5
       );
       await this.completeCommand(command3.id, "SUCCEEDED");
-      await rm13(join17(dirname8(configPath()), "runs", run.id, "attachments"), {
+      await rm13(join17(dirname10(configPath()), "runs", run.id, "attachments"), {
         recursive: true,
         force: true
       }).catch(() => void 0);
@@ -50193,7 +50333,7 @@ var RunManager = class {
         this.active.delete(run.id);
       this.interruptionRequests.delete(run.id);
       this.executingCommands.delete(command3.id);
-      await rm13(join17(dirname8(configPath()), "runs", run.id, "attachments"), {
+      await rm13(join17(dirname10(configPath()), "runs", run.id, "attachments"), {
         recursive: true,
         force: true
       }).catch(() => void 0);
@@ -50421,7 +50561,7 @@ var RunManager = class {
   }
   async stageAttachments(runId, attachments) {
     if (!attachments.length) return [];
-    const directory = join17(dirname8(configPath()), "runs", runId, "attachments");
+    const directory = join17(dirname10(configPath()), "runs", runId, "attachments");
     await mkdir6(directory, { recursive: true, mode: 448 });
     return Promise.all(
       attachments.map(async (attachment) => {
@@ -50549,7 +50689,8 @@ var DISK_SPACE_STALE_AFTER_SECONDS = DISK_SPACE_POLL_INTERVAL_SECONDS * 2;
 function configuredIntervalMs(value, fallbackSeconds, minSeconds, maxSeconds) {
   return (Number.isInteger(value) && value >= minSeconds && value <= maxSeconds ? value : fallbackSeconds) * 1e3;
 }
-async function runAgent(config, signal) {
+var UNHEALTHY_HEARTBEAT_FAILURES = 3;
+async function runAgentSession(config, signal, onUnhealthy) {
   const client2 = new AgentGraphQLClient(
     config.server,
     config.credential,
@@ -50571,6 +50712,7 @@ async function runAgent(config, signal) {
   let diskSpaceRunning = false;
   let diskSpaceIntervalMs = DISK_SPACE_POLL_INTERVAL_SECONDS * 1e3;
   let startupRecoveryPending = true;
+  let heartbeatFailures = 0;
   const interruptedJobs = /* @__PURE__ */ new Set();
   const reconcileJobs = async (recoverInterrupted) => {
     let jobs;
@@ -50653,11 +50795,17 @@ async function runAgent(config, signal) {
     heartbeatTimer = void 0;
     try {
       await client2.heartbeat(collectInventory());
+      heartbeatFailures = 0;
     } catch (error) {
+      heartbeatFailures += 1;
       console.error(
         "Heartbeat failed:",
         error instanceof Error ? error.message : error
       );
+      if (heartbeatFailures >= UNHEALTHY_HEARTBEAT_FAILURES && onUnhealthy) {
+        heartbeatFailures = 0;
+        onUnhealthy();
+      }
     } finally {
       heartbeatRunning = false;
       scheduleHeartbeat();
@@ -50802,6 +50950,53 @@ async function runAgent(config, signal) {
   await executor.cancelAll();
   await runManager.close();
 }
+async function runAgent(config, signal) {
+  const failoverEnabled = agentEndpoints(config).length > 1;
+  let preferred;
+  while (!signal.aborted) {
+    const endpoint = preferred ?? await selectAgentEndpoint(config, signal);
+    preferred = void 0;
+    if (signal.aborted) break;
+    if (failoverEnabled) {
+      console.log(
+        `Using the ${endpoint.kind} control plane at ${endpoint.server}`
+      );
+    }
+    const session = new AbortController();
+    const abortSession = () => session.abort();
+    signal.addEventListener("abort", abortSession, { once: true });
+    let probing = false;
+    const onUnhealthy = () => {
+      if (probing || session.signal.aborted) return;
+      probing = true;
+      void findHealthyAlternate(config, endpoint, session.signal).then((alternate) => {
+        if (session.signal.aborted) return;
+        if (!alternate) {
+          console.log(
+            `The ${endpoint.kind} control plane is not answering and no other endpoint is either; keeping the session and retrying`
+          );
+          return;
+        }
+        console.log(
+          `The ${endpoint.kind} control plane stopped responding; switching to the ${alternate.kind} control plane at ${alternate.server}`
+        );
+        preferred = alternate;
+        session.abort();
+      }).finally(() => {
+        probing = false;
+      });
+    };
+    try {
+      await runAgentSession(
+        configForEndpoint(config, endpoint),
+        session.signal,
+        failoverEnabled ? onUnhealthy : void 0
+      );
+    } finally {
+      signal.removeEventListener("abort", abortSession);
+    }
+  }
+}
 
 // src/dev-runtime.ts
 var DEFAULT_SERVER_WAIT_MS = 12e4;
@@ -50883,10 +51078,10 @@ async function prepareDevelopmentAgent(options, signal, dependencies = defaultDe
     }
   } catch {
   }
-  const enrollment = await anonymousClient.createEnrollmentToken();
+  const enrollment2 = await anonymousClient.createEnrollmentToken();
   const response = await anonymousClient.enroll({
     ...inventory,
-    enrollmentToken: enrollment.createAgentEnrollmentToken.token,
+    enrollmentToken: enrollment2.createAgentEnrollmentToken.token,
     name
   });
   const config = {
@@ -50936,12 +51131,17 @@ function redactedRequestHeaders(headers) {
 }
 
 // src/index.ts
+var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["clear-remote"]);
 function flags(args) {
   const result = {};
   const headerValues = [];
   for (let index = 0; index < args.length; index += 1) {
     const argument = args[index];
     if (!argument.startsWith("--")) continue;
+    if (BOOLEAN_FLAGS.has(argument.slice(2))) {
+      result[argument.slice(2)] = "true";
+      continue;
+    }
     const value = args[index + 1];
     if (!value || value.startsWith("--"))
       throw new Error(`Missing value for ${argument}`);
@@ -50955,26 +51155,50 @@ function usage() {
   console.log(`control-agent <command>
 
 Commands:
-  enroll --enrollment-token <token> [--server http://127.0.0.1:3090] [--websocket-server ws://127.0.0.1:3090/graphql] [--name <name>] [--header "Name: value"]...
+  enroll --enrollment-token <token> [--server http://127.0.0.1:3090] [--websocket-server ws://127.0.0.1:3090/graphql] [--remote-server https://control.example.com] [--remote-websocket-server wss://control.example.com/graphql] [--name <name>] [--header "Name: value"]...
+  endpoints [--server <url>] [--websocket-server <url>] [--remote-server <url>] [--remote-websocket-server <url>] [--clear-remote]
+  enrollment
+  unenroll
   dev [--server http://127.0.0.1:3000] [--websocket-server ws://127.0.0.1:3092/graphql] [--name <name>]
   run
   status
   doctor`);
 }
+function endpointOptions(options, fallback) {
+  const server = normalizeServer(
+    options.server ?? fallback?.server ?? "http://127.0.0.1:3090"
+  );
+  const websocketServer = options["websocket-server"] ?? // A new local address invalidates a websocket address derived from the old
+  // one, so only an explicitly stored value survives a server change.
+  (options.server ? void 0 : fallback?.websocketServer) ?? defaultWebSocketServer(server);
+  const clearRemote = options["clear-remote"] === "true";
+  const remote = options["remote-server"] ?? (clearRemote ? null : void 0);
+  const remoteServer = remote === void 0 ? fallback?.remoteServer ?? null : remote && normalizeServer(remote);
+  const remoteWebSocketServer = !remoteServer ? null : options["remote-websocket-server"] ?? (options["remote-server"] ? void 0 : fallback?.remoteWebSocketServer) ?? defaultWebSocketServer(remoteServer);
+  return {
+    server,
+    websocketServer,
+    remoteServer,
+    remoteWebSocketServer
+  };
+}
 async function enroll(args) {
   const parsed = flags(args);
   const options = parsed.values;
   const enrollmentToken = options["enrollment-token"];
   if (!enrollmentToken) throw new Error("--enrollment-token is required");
-  const server = normalizeServer(options.server ?? "http://127.0.0.1:3090");
-  const websocketServer = options["websocket-server"] ?? defaultWebSocketServer(server);
+  const addresses = endpointOptions(options);
   const inventory = collectInventory();
   const name = options.name ?? inventory.hostname;
-  const client2 = new AgentGraphQLClient(server, null, 1e4, parsed.headers);
+  const client2 = new AgentGraphQLClient(
+    addresses.server,
+    null,
+    1e4,
+    parsed.headers
+  );
   const response = await client2.enroll({ ...inventory, enrollmentToken, name });
   await saveConfig({
-    server,
-    websocketServer,
+    ...addresses,
     agentId: response.enrollAgent.agent.id,
     credential: response.enrollAgent.credential,
     name,
@@ -50982,6 +51206,63 @@ async function enroll(args) {
   });
   console.log(`Enrolled agent ${name} (${response.enrollAgent.agent.id})`);
 }
+async function endpoints(args) {
+  const options = flags(args).values;
+  const config = await loadConfig();
+  const changing = [
+    "server",
+    "websocket-server",
+    "remote-server",
+    "remote-websocket-server",
+    "clear-remote"
+  ].some((flag) => flag in options);
+  const updated = changing ? { ...config, ...endpointOptions(options, config) } : config;
+  if (changing) await saveConfig(updated);
+  for (const endpoint of agentEndpoints(updated)) {
+    console.log(
+      `${endpoint.kind}: ${endpoint.server} (${endpoint.websocketServer})`
+    );
+  }
+  if (!updated.remoteServer) console.log("remote: not configured");
+}
+async function enrollment() {
+  let config;
+  try {
+    config = await loadConfig();
+  } catch (error) {
+    console.log("Enrolled: no");
+    console.log(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+    return;
+  }
+  console.log("Enrolled: yes");
+  console.log(`Agent: ${config.name} (${config.agentId})`);
+  console.log(`Configuration: ${configPath()}`);
+  let reachable = false;
+  for (const endpoint of agentEndpoints(config)) {
+    const ok2 = await probeEndpoint(endpoint, config);
+    reachable ||= ok2;
+    console.log(
+      `${endpoint.kind}: ${endpoint.server} \u2014 ${ok2 ? "reachable" : "unreachable"}`
+    );
+  }
+  if (!reachable) process.exitCode = 1;
+}
+async function unenroll() {
+  const path = configPath();
+  let config = null;
+  try {
+    config = await loadConfig(path);
+  } catch {
+  }
+  await rm14(path, { force: true });
+  console.log(
+    config ? `Removed the enrollment for ${config.name} (${config.agentId}) from ${path}` : `Removed ${path}`
+  );
+  console.log(
+    "The control plane still lists this agent; delete it there to finish removing it."
+  );
+}
 async function status() {
   const config = await loadConfig();
   const response = await new AgentGraphQLClient(
@@ -51018,26 +51299,39 @@ async function doctor() {
       detail: error instanceof Error ? error.message : String(error)
     });
   }
-  try {
-    const server = config?.server ?? "http://127.0.0.1:3090";
-    const health = await new AgentGraphQLClient(
-      server,
-      null,
-      1e4,
-      config?.headers
-    ).health();
-    checks.push({
-      check: "control plane",
-      ok: health.health === "ok",
-      detail: health.health
-    });
-  } catch (error) {
-    checks.push({
-      check: "control plane",
-      ok: false,
-      detail: error instanceof Error ? error.message : String(error)
-    });
-  }
+  const reachable = config ? agentEndpoints(config) : [
+    {
+      kind: "local",
+      server: "http://127.0.0.1:3090",
+      websocketServer: "ws://127.0.0.1:3090/graphql"
+    }
+  ];
+  const results = await Promise.all(
+    reachable.map(async (endpoint) => {
+      try {
+        const health = await new AgentGraphQLClient(
+          endpoint.server,
+          null,
+          1e4,
+          config?.headers
+        ).health();
+        return {
+          ok: health.health === "ok",
+          detail: `${endpoint.kind} ${endpoint.server}: ${health.health}`
+        };
+      } catch (error) {
+        return {
+          ok: false,
+          detail: `${endpoint.kind} ${endpoint.server}: ${error instanceof Error ? error.message : String(error)}`
+        };
+      }
+    })
+  );
+  checks.push({
+    check: "control plane",
+    ok: results.some((result) => result.ok),
+    detail: results.map((result) => result.detail).join("; ")
+  });
   for (const check of checks)
     console.log(
       `${check.ok ? "PASS" : "FAIL"} ${check.check}: ${check.detail}`
@@ -51045,12 +51339,16 @@ async function doctor() {
   if (checks.some((check) => !check.ok)) process.exitCode = 1;
 }
 async function main() {
+  repairToolPath();
   const [command3, ...args] = process.argv.slice(2);
   if (!command3 || command3 === "help" || command3 === "--help") {
     usage();
     return;
   }
   if (command3 === "enroll") return enroll(args);
+  if (command3 === "endpoints") return endpoints(args);
+  if (command3 === "enrollment") return enrollment();
+  if (command3 === "unenroll") return unenroll();
   if (command3 === "status") return status();
   if (command3 === "doctor") return doctor();
   if (command3 === "run" || command3 === "dev") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-development-environment/control-agent",
-  "version": "0.0.76",
+  "version": "0.0.78",
   "description": "Control agent for the AI Development Environment",
   "license": "MIT",
   "repository": {