nolo-cli 0.1.30 → 0.1.32

package/cli/localRuntimeDb.ts

@@ -0,0 +1,65 @@
+import type { CliLocalRuntimeDb } from "./client/localRuntimeAdapter";
+import path from "node:path";
+import { resolveNoloHome } from "../database/server/dbPath";
+
+type EnvLike = Record<string, string | undefined>;
+
+type CliLocalRuntimeDbPathOptions = {
+  env?: EnvLike;
+  homeDir?: string;
+};
+
+export function resolveCliLocalRuntimeDbPath(options: CliLocalRuntimeDbPathOptions = {}) {
+  return path.join(resolveNoloHome(options), "data", "leveldb");
+}
+
+export function buildCliLocalRuntimeDbEnv(env: EnvLike = process.env) {
+  return {
+    ...env,
+    NOLO_SERVER_DB_PATH: env.NOLO_SERVER_DB_PATH?.trim() || resolveCliLocalRuntimeDbPath({ env }),
+  };
+}
+
+export function isCliLocalRuntimeDbLockError(error: unknown): boolean {
+  const queue: unknown[] = [error];
+  const seen = new Set<unknown>();
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current || seen.has(current)) continue;
+    seen.add(current);
+
+    const text = `${(current as any)?.code ?? ""} ${(current as any)?.message ?? current}`;
+    if (/LEVEL_LOCKED|Resource temporarily unavailable|\/LOCK|LOCK:|db locked|locked/i.test(text)) {
+      return true;
+    }
+
+    if ((current as any)?.cause) queue.push((current as any).cause);
+    if (Array.isArray((current as any)?.errors)) queue.push(...(current as any).errors);
+  }
+
+  return false;
+}
+
+export function formatCliLocalRuntimeDbOpenError(dbPath: string, error: unknown) {
+  if (!isCliLocalRuntimeDbLockError(error)) {
+    return error instanceof Error ? error : new Error(String(error));
+  }
+  return new Error(
+    `CLI local runtime DB is locked at ${dbPath}. Another nolo local runtime is already using it. ` +
+      "Stop the other local runtime, rerun without --local, or set NOLO_SERVER_DB_PATH to a different cache path.",
+    { cause: error instanceof Error ? error : undefined }
+  );
+}
+
+export async function getDefaultCliLocalRuntimeDb(): Promise<CliLocalRuntimeDb> {
+  const dbPath = buildCliLocalRuntimeDbEnv(process.env).NOLO_SERVER_DB_PATH;
+  process.env.NOLO_SERVER_DB_PATH = dbPath;
+  const { default: serverDb, ensureServerDbOpen } = await import("../database/server/db");
+  try {
+    await ensureServerDbOpen();
+  } catch (error) {
+    throw formatCliLocalRuntimeDbOpenError(dbPath, error);
+  }
+  return serverDb as CliLocalRuntimeDb;
+}

package/cli/machineCommandPrompts.ts

@@ -0,0 +1,79 @@
+import {
+  buildMachinePermissionPromptBlock,
+  resolveMachineRunPermissionPolicy,
+  type MachineRunPermissionPolicy,
+} from "../ai/agent/machineRunPermissions";
+import { buildNoloReadOnlyBridgePrompt } from "./noloReadBridgePrompt";
+
+export function inferTaskRunRole(agentKey: string, agentConfig: any) {
+  const haystack = [agentKey, agentConfig?.name, agentConfig?.prompt]
+    .filter(Boolean)
+    .join("\n")
+    .toLowerCase();
+  if (haystack.includes("frontend") || haystack.includes("前端")) return "frontend";
+  if (haystack.includes("fullstack") || haystack.includes("全栈")) return "fullstack";
+  if (haystack.includes("review") || haystack.includes("审查")) return "reviewer";
+  if (haystack.includes("project-manager") || haystack.includes("项目经理")) return "pm";
+  return "codex";
+}
+
+export function buildTaskRunBridgePrompt(args: {
+  agentKey: string;
+  agentConfig: any;
+  runtimeContext: any;
+}) {
+  const taskRun = args.runtimeContext?.taskRun;
+  const rowDbKey = typeof taskRun?.rowDbKey === "string" ? taskRun.rowDbKey.trim() : "";
+  if (!rowDbKey) return "";
+  const workItemId = typeof taskRun?.workItemId === "string" ? taskRun.workItemId.trim() : "";
+  const role = inferTaskRunRole(args.agentKey, args.agentConfig);
+  return [
+    "--- Nolo task-run tool bridge ---",
+    "This CLI runtime does not receive server-side function tools directly.",
+    "Use the local task-run bridge command for durable task state writes. Do not edit meta.taskRun with table or database commands.",
+    "Run commands from the repository root. The runner already provides server URL and auth in the environment.",
+    "Release boundary: after review passes, AI/reviewer/Codex may advance alpha for verification. Do not merge, push, or release main/release unless the human owner explicitly authorizes it in the current task context.",
+    "Cost boundary: read taskRun.control from context. Prefer low-cost/free-window models for routine work, and reserve Codex for supervision, quality gates, complex unblocking, and main/release decisions.",
+    "Handoff context: start from read-context, then inspect existing refs such as workItems.dialogIds, workItems.outcome, review.dialogId, activityRefs, agentRuns.dialogId/resultSummary, and artifactRefs. Use dialog read/search for exact evidence; do not infer completion from handoff text alone.",
+    `Read context: bun packages/cli/index.ts task-run read-context --row-dbkey ${JSON.stringify(rowDbKey)}`,
+    ...(workItemId
+      ? [
+          `Claim work item: bun packages/cli/index.ts task-run claim-work-item --row-dbkey ${JSON.stringify(rowDbKey)} --work-item-id ${JSON.stringify(workItemId)} --agent-key ${JSON.stringify(args.agentKey)} --role ${role}`,
+          `Set blocker: bun packages/cli/index.ts task-run set-blocker --row-dbkey ${JSON.stringify(rowDbKey)} --work-item-id ${JSON.stringify(workItemId)} --layer tool --code <CODE> --message <MESSAGE>`,
+          `Clear resolved blocker: bun packages/cli/index.ts task-run clear-blocker --row-dbkey ${JSON.stringify(rowDbKey)} --work-item-id ${JSON.stringify(workItemId)} --blocker-id <BLOCKER_ID>`,
+          `Submit outcome: bun packages/cli/index.ts task-run submit-outcome --row-dbkey ${JSON.stringify(rowDbKey)} --work-item-id ${JSON.stringify(workItemId)} --summary <SUMMARY>`,
+          `Request review: bun packages/cli/index.ts task-run request-review --row-dbkey ${JSON.stringify(rowDbKey)} --work-item-id ${JSON.stringify(workItemId)} --reviewer-agent-key <AGENT_KEY> --message <MESSAGE>`,
+          `Record review: bun packages/cli/index.ts task-run record-review --row-dbkey ${JSON.stringify(rowDbKey)} --work-item-id ${JSON.stringify(workItemId)} --review-status <passed|needs_changes|blocked> --reviewer-agent-key ${JSON.stringify(args.agentKey)} --findings <FINDINGS>`,
+          `Close work item: bun packages/cli/index.ts task-run close-work-item --row-dbkey ${JSON.stringify(rowDbKey)} --work-item-id ${JSON.stringify(workItemId)} --summary <SUMMARY>`,
+        ]
+      : []),
+    "If a bridge command fails, report the exact command and error.",
+  ].join("\n");
+}
+
+export function buildConnectorCliPrompt(
+  agentConfig: any,
+  userInput: string,
+  bridgeArgs?: {
+    agentKey: string;
+    runtimeContext: any;
+  },
+  permissionPolicy?: MachineRunPermissionPolicy,
+) {
+  const policy = permissionPolicy ?? resolveMachineRunPermissionPolicy(agentConfig);
+  return [
+    typeof agentConfig?.prompt === "string" ? agentConfig.prompt.trim() : "",
+    buildNoloReadOnlyBridgePrompt(),
+    bridgeArgs
+      ? buildTaskRunBridgePrompt({
+          agentKey: bridgeArgs.agentKey,
+          agentConfig,
+          runtimeContext: bridgeArgs.runtimeContext,
+        })
+      : "",
+    buildMachinePermissionPromptBlock(policy),
+    `--- User task ---\n${userInput}`,
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+}

package/cli/machineCommandResolution.ts

@@ -0,0 +1,43 @@
+import {
+  hasFlag,
+  readCliOptionValue,
+  resolveAuthToken as resolveCliAuthToken,
+  resolveAuthTokenFromArgs,
+  resolveServerUrlFromArgs,
+  resolveServerUrlFromEnv,
+  type EnvLike,
+} from "./cliEnvHelpers";
+import type { OutputLike } from "./cliIoTypes";
+export type { OutputLike } from "./cliIoTypes";
+export { hasFlag };
+
+export function resolveServerUrl(env: EnvLike) {
+  return resolveServerUrlFromEnv(env);
+}
+
+export function resolveAuthToken(env: EnvLike) {
+  return resolveCliAuthToken(env);
+}
+
+export function writeAuthMissing(output: OutputLike) {
+  output.write(
+    "[nolo] Machine commands require an auth token. Run `nolo login` or set AUTH_TOKEN.\n"
+  );
+}
+
+export function readOption(args: string[], flag: string) {
+  return readCliOptionValue(args, flag);
+}
+
+export function resolveConnectServerUrl(args: string[], env: EnvLike) {
+  return resolveServerUrlFromArgs(args, env);
+}
+
+export function resolveConnectAuthToken(args: string[], env: EnvLike) {
+  return resolveAuthTokenFromArgs(args, env);
+}
+
+export function resolveConnectorReconnectDelayMs(env: EnvLike) {
+  const raw = Number(env.NOLO_CONNECT_RECONNECT_MS ?? "");
+  return Number.isFinite(raw) && raw >= 0 ? raw : 5_000;
+}

package/cli/machineCommands.ts

@@ -0,0 +1,324 @@
+import type { MachineHeartbeat } from "../connector-experimental/protocol";
+import { NOLO_CLUSTER_SERVERS, normalizeKnownServerOrigin } from "../database/config";
+import { detectMachineInfo } from "../connector-experimental/machineInfo";
+import {
+  type HeartbeatLoopOptions,
+  runHeartbeatLoop as defaultRunHeartbeatLoop,
+} from "../connector-experimental/heartbeatLoop";
+import { resolveConnectorWebSocketTarget } from "./connectorWebSocketTarget";
+import {
+  checkConnectorWorkspaceLinks,
+  runMachineDaemonCommand,
+} from "./machineDaemonCommands";
+import { runMachineHeartbeatConnectCommand } from "./machineHeartbeatCommands";
+import { runMachineWatchCommand } from "./machineWatchCommands";
+import {
+  handleConnectorRunMessage,
+  type LocalCliExecutor,
+} from "./machineWsRunDispatch";
+import {
+  defaultConnectWebSocket,
+  runMachineWsSession,
+  type ConnectorWebSocketOptions,
+} from "./machineWsSession";
+import {
+  buildConnectorCliPrompt,
+} from "./machineCommandPrompts";
+import {
+  hasFlag,
+  readOption,
+  resolveConnectAuthToken,
+  resolveConnectServerUrl,
+  resolveConnectorReconnectDelayMs,
+  writeAuthMissing,
+  type EnvLike,
+  type OutputLike,
+} from "./machineCommandResolution";
+export {
+  formatMachineStatus,
+  runMachineStatusCommand,
+  type MachineSummary,
+} from "./machineStatusCommands";
+
+type MachineCommandDeps = {
+  env?: EnvLike;
+  output?: OutputLike;
+  signal?: AbortSignal;
+  cliEntrypointPath?: string;
+  maxConnectorAttempts?: number;
+  sleep?: (ms: number) => Promise<void>;
+  fetchImpl?: typeof fetch;
+  machineInfo?: () => MachineHeartbeat;
+  runHeartbeatLoop?: (options: HeartbeatLoopOptions) => Promise<void>;
+  connectWebSocket?: (url: string, options: ConnectorWebSocketOptions) => Promise<void>;
+  executeCli?: LocalCliExecutor;
+  validateWorkspaceLinks?: (cwd: string) => string[] | Promise<string[]>;
+  spawnDaemon?: (args: {
+    cmd: string[];
+    cwd: string;
+    env: EnvLike;
+    logPath: string;
+  }) => { pid?: number };
+};
+
+const defaultSleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+const MACHINE_TOKEN_PREFIX = "sk_machine_";
+
+async function sleepWithAbort(ms: number, sleep: (ms: number) => Promise<void>, signal?: AbortSignal) {
+  if (!signal) {
+    await sleep(ms);
+    return;
+  }
+  if (signal.aborted) return;
+  await Promise.race([
+    sleep(ms),
+    new Promise<void>((resolve) => {
+      signal.addEventListener("abort", () => resolve(), { once: true });
+    }),
+  ]);
+}
+
+function resolveConnectorReconnectDelayMs(env: EnvLike) {
+  const raw = Number(env.NOLO_CONNECT_RECONNECT_MS ?? "");
+  return Number.isFinite(raw) && raw >= 0 ? raw : 5_000;
+}
+
+function isMachineToken(token: string) {
+  return token.trim().startsWith(MACHINE_TOKEN_PREFIX);
+}
+
+function resolveClusterConnectServerUrls(serverUrl: string, authToken: string) {
+  const normalizedPrimary = normalizeKnownServerOrigin(serverUrl) ?? serverUrl.trim().replace(/\/+$/, "");
+  if (isMachineToken(authToken)) return [normalizedPrimary];
+  const normalizedCluster = NOLO_CLUSTER_SERVERS
+    .map((baseUrl) => normalizeKnownServerOrigin(baseUrl) ?? baseUrl)
+    .filter((value, index, list) => value && list.indexOf(value) === index);
+  if (!normalizedCluster.includes(normalizedPrimary)) return [normalizedPrimary];
+  return [normalizedPrimary, ...normalizedCluster.filter((baseUrl) => baseUrl !== normalizedPrimary)];
+}
+
+function linkAbortSignal(signal: AbortSignal | undefined, controller: AbortController) {
+  if (!signal) return;
+  if (signal.aborted) {
+    controller.abort();
+    return;
+  }
+  signal.addEventListener("abort", () => controller.abort(), { once: true });
+}
+
+async function sendMachineHeartbeat(args: {
+  serverUrl: string;
+  authToken: string;
+  fetchImpl: typeof fetch;
+  machine: MachineHeartbeat;
+}) {
+  const res = await args.fetchImpl(`${args.serverUrl}/api/machines/heartbeat`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${args.authToken}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(args.machine),
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`HTTP ${res.status}\n${text}`);
+  }
+}
+
+async function sendHeartbeatAcrossServers(args: {
+  serverUrls: string[];
+  authToken: string;
+  fetchImpl: typeof fetch;
+  machine: MachineHeartbeat;
+  output: OutputLike;
+}) {
+  let primaryError: Error | null = null;
+  for (const [index, serverUrl] of args.serverUrls.entries()) {
+    try {
+      await sendMachineHeartbeat({
+        serverUrl,
+        authToken: args.authToken,
+        fetchImpl: args.fetchImpl,
+        machine: args.machine,
+      });
+    } catch (error) {
+      const resolvedError = error instanceof Error ? error : new Error(String(error));
+      if (index === 0) {
+        primaryError = resolvedError;
+      } else {
+        args.output.write(
+          `[nolo] secondary connector registration failed for ${serverUrl}: ${resolvedError.message}\n`
+        );
+      }
+    }
+  }
+  if (primaryError) throw primaryError;
+}
+
+async function defaultExecuteCli(
+  provider: string,
+  prompt: string,
+  options: { model?: string; timeout?: number; cwd?: string; yolo?: boolean; env?: EnvLike }
+) {
+  const { executeCli } = await import("../ai/agent/cliExecutor");
+  return executeCli(provider as any, prompt, options);
+}
+
+function detectLaunchableMachineInfo() {
+  return detectMachineInfo({ probeLaunchable: true });
+}
+
+export async function runMachineConnectCommand(
+  args: string[],
+  deps: MachineCommandDeps = {}
+) {
+  const env = deps.env ?? process.env;
+  const output = deps.output ?? process.stdout;
+  const authToken = resolveConnectAuthToken(args, env);
+  if (!authToken) {
+    writeAuthMissing(output);
+    return 1;
+  }
+
+  const serverUrl = resolveConnectServerUrl(args, env);
+  const serverUrls = resolveClusterConnectServerUrls(serverUrl, authToken);
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const machine = (deps.machineInfo ?? detectLaunchableMachineInfo)();
+  const sendHeartbeat = async () => {
+    await sendHeartbeatAcrossServers({
+      serverUrls,
+      authToken,
+      fetchImpl,
+      machine,
+      output,
+    });
+  };
+
+  if (hasFlag(args, "--daemon") || hasFlag(args, "--background")) {
+    return runMachineDaemonCommand({
+      env: {
+        ...env,
+        NOLO_SERVER: serverUrl,
+        NOLO_SERVER_URL: serverUrl,
+        BASE_URL: serverUrl,
+        AUTH_TOKEN: authToken,
+        NOLO_MACHINE_API_KEY: authToken,
+      },
+      output,
+      cliEntrypointPath: deps.cliEntrypointPath,
+      validateWorkspaceLinks: deps.validateWorkspaceLinks,
+      spawnDaemon: deps.spawnDaemon,
+    });
+  }
+
+  if (hasFlag(args, "--ws")) {
+    const validateWorkspaceLinks = deps.validateWorkspaceLinks ?? (() => []);
+    if (!(await checkConnectorWorkspaceLinks(process.cwd(), output, validateWorkspaceLinks))) {
+      return 1;
+    }
+    const maxAttempts = deps.maxConnectorAttempts ?? Infinity;
+    const sleep = deps.sleep ?? defaultSleep;
+    const reconnectDelayMs = resolveConnectorReconnectDelayMs(env);
+    const runServerSession = async (targetServerUrl: string, signal?: AbortSignal) => {
+      for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        if (signal?.aborted) {
+          return { serverUrl: targetServerUrl, exitCode: 0 };
+        }
+        const runtimeServerUrl =
+          env.NOLO_CONNECT_RUNTIME_SERVER_URL ||
+          env.NOLO_RUNTIME_SERVER_URL ||
+          targetServerUrl;
+        const sessionResult = await runMachineWsSession({
+          env,
+          output,
+          signal,
+          machine,
+          sendHeartbeat: () =>
+            sendMachineHeartbeat({
+              serverUrl: targetServerUrl,
+              authToken,
+              fetchImpl,
+              machine,
+            }),
+          runHeartbeatLoop: deps.runHeartbeatLoop ?? defaultRunHeartbeatLoop,
+          connectWebSocket: deps.connectWebSocket ?? defaultConnectWebSocket,
+          serverUrl: targetServerUrl,
+          authToken,
+          resolveConnectorWebSocketTarget: (options) =>
+            resolveConnectorWebSocketTarget({
+              ...options,
+              fetchImpl,
+            }),
+          onMessage: (message, send) =>
+            handleConnectorRunMessage(
+              message,
+              send,
+              deps.executeCli ?? defaultExecuteCli,
+              {
+                ...env,
+                NOLO_SERVER: runtimeServerUrl,
+                NOLO_SERVER_URL: runtimeServerUrl,
+                BASE_URL: runtimeServerUrl,
+                AUTH_TOKEN: authToken,
+                NOLO_MACHINE_API_KEY: authToken,
+              },
+              fetchImpl,
+              {
+                buildConnectorCliPrompt,
+              }
+            ),
+        });
+        const exitCode = sessionResult.exitCode;
+        if (exitCode === 2) return { serverUrl: targetServerUrl, exitCode: 2 };
+        if (signal?.aborted) {
+          return { serverUrl: targetServerUrl, exitCode: 0 };
+        }
+        if (attempt >= maxAttempts) return { serverUrl: targetServerUrl, exitCode };
+        const retryDelayMs = sessionResult.retryAfterMs ?? reconnectDelayMs;
+        const reconnectContext =
+          sessionResult.reconnectReason === "core_draining" ? " during core draining" : "";
+        output.write(
+          `[nolo] Connector websocket disconnected${reconnectContext}. Reconnecting in ${retryDelayMs}ms.\n`
+        );
+        await sleepWithAbort(retryDelayMs, sleep, signal);
+      }
+      return { serverUrl: targetServerUrl, exitCode: 0 };
+    };
+
+    const sessionAbort = new AbortController();
+    linkAbortSignal(deps.signal, sessionAbort);
+
+    const sessionPromises = serverUrls.map(async (targetServerUrl, index) => {
+      const result = await runServerSession(targetServerUrl, sessionAbort.signal);
+      if (index > 0 && result.exitCode !== 0 && !sessionAbort.signal.aborted) {
+        output.write(
+          `[nolo] secondary connector registration failed for ${targetServerUrl}: exit ${result.exitCode}\n`
+        );
+      }
+      return result;
+    });
+    const results = await Promise.all(sessionPromises);
+    if (results.some((result) => result.exitCode === 0)) return 0;
+    if (results.some((result) => result.exitCode === 2)) return 1;
+    return results[0]?.exitCode ?? 1;
+  }
+
+  if (hasFlag(args, "--watch")) {
+    return runMachineWatchCommand({
+      env,
+      output,
+      machine,
+      sendHeartbeat,
+      runHeartbeatLoop: deps.runHeartbeatLoop ?? defaultRunHeartbeatLoop,
+    });
+  }
+
+  return runMachineHeartbeatConnectCommand({
+    output,
+    machine,
+    sendHeartbeat,
+  });
+}
+

package/cli/machineDaemonCommands.ts

@@ -0,0 +1,29 @@
+import {
+  checkConnectorWorkspaceLinks,
+  runConnectorDaemon,
+  type ConnectorDaemonDeps,
+} from "../connector-experimental/daemonLauncher";
+import type { OutputLike } from "./cliIoTypes";
+
+type EnvLike = Record<string, string | undefined>;
+
+export type MachineDaemonCommandDeps = {
+  env?: EnvLike;
+  output?: OutputLike;
+  cliEntrypointPath?: string;
+  validateWorkspaceLinks?: (cwd: string) => string[] | Promise<string[]>;
+  spawnDaemon?: (args: {
+    cmd: string[];
+    cwd: string;
+    env: EnvLike;
+    logPath: string;
+  }) => { pid?: number };
+};
+
+export async function runMachineDaemonCommand(
+  deps: MachineDaemonCommandDeps = {}
+) {
+  return runConnectorDaemon(deps as ConnectorDaemonDeps);
+}
+
+export { checkConnectorWorkspaceLinks };

package/cli/machineHeartbeatCommands.ts

@@ -0,0 +1,29 @@
+import type { MachineHeartbeat } from "../connector-experimental/protocol";
+import type { OutputLike } from "./cliIoTypes";
+
+export type MachineHeartbeatConnectDeps = {
+  output?: OutputLike;
+  machine: MachineHeartbeat;
+  sendHeartbeat: () => Promise<void>;
+};
+
+export async function runMachineHeartbeatConnectCommand(
+  deps: MachineHeartbeatConnectDeps
+) {
+  const output = deps.output ?? process.stdout;
+  const machine = deps.machine;
+
+  try {
+    await deps.sendHeartbeat();
+  } catch (error) {
+    output.write(
+      `[nolo] Machine connect failed: ${
+        error instanceof Error ? error.message : String(error)
+      }\n`
+    );
+    return 1;
+  }
+
+  output.write(`Connected machine: ${machine.name} (${machine.platform}/${machine.arch})\n`);
+  return 0;
+}

package/cli/machineStatusCommands.ts

@@ -0,0 +1,87 @@
+import type { OutputLike } from "./cliIoTypes";
+import { resolveAuthToken, resolveServerUrl } from "./cliEnvHelpers";
+
+type EnvLike = Record<string, string | undefined>;
+
+export type MachineSummary = {
+  machineId: string;
+  name: string;
+  platform: string;
+  arch: string;
+  connectorVersion: string | null;
+  capabilities: string[];
+  connectorStatus?: "connected" | "disconnected";
+  status: "online" | "offline";
+  lastSeenAt: number;
+};
+
+export type MachineStatusCommandDeps = {
+  env?: EnvLike;
+  output?: OutputLike;
+  fetchImpl?: typeof fetch;
+};
+
+function writeAuthMissing(output: OutputLike) {
+  output.write(
+    "[nolo] Machine commands require an auth token. Run `nolo login` or set AUTH_TOKEN.\n"
+  );
+}
+
+export function formatMachineStatus(machines: MachineSummary[]) {
+  if (machines.length === 0) {
+    return "No connected machines.\nRun `nolo connect` on this computer to register it once.\n";
+  }
+
+  return [
+    "Connected machines:",
+    ...machines.map((machine) => {
+      const caps = machine.capabilities.length ? machine.capabilities.join(", ") : "no capabilities";
+      const connector = machine.connectorStatus ? `  ws:${machine.connectorStatus}` : "";
+      return `- ${machine.name}  ${machine.status}${connector}  ${machine.platform}/${machine.arch}  ${caps}`;
+    }),
+    "",
+  ].join("\n");
+}
+
+export async function runMachineStatusCommand(
+  args: string[],
+  deps: MachineStatusCommandDeps = {}
+) {
+  const env = deps.env ?? process.env;
+  const output = deps.output ?? process.stdout;
+  const authToken = resolveAuthToken(args, env);
+  if (!authToken) {
+    writeAuthMissing(output);
+    return 1;
+  }
+
+  const serverUrl = resolveServerUrl(args, env);
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  let res: Response;
+  try {
+    res = await fetchImpl(`${serverUrl}/api/machines`, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${authToken}`,
+      },
+    });
+  } catch (error) {
+    output.write(
+      `[nolo] Machine status failed: ${
+        error instanceof Error ? error.message : String(error)
+      }\n`
+    );
+    return 1;
+  }
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    output.write(`[nolo] Machine status failed: HTTP ${res.status}\n${text}\n`);
+    return 1;
+  }
+
+  const data = await res.json().catch(() => ({ machines: [] }));
+  const machines = Array.isArray(data?.machines) ? data.machines : [];
+  output.write(formatMachineStatus(machines));
+  return 0;
+}