@hasna/machines 0.0.30 → 0.0.31

package/dist/cli/index.js

@@ -3164,15 +3164,9 @@ function print(value, json, text) {
   else
     console.log(text);
 }
-function hasJsonOption(options) {
-  return Boolean(options?.json || options?.opts?.().json || options?.optsWithGlobals?.().json || options?.parent?.opts?.().json || options?.parent?.optsWithGlobals?.().json);
-}
-function wantsJson(actionOptions, command) {
-  return hasJsonOption(actionOptions) || hasJsonOption(command);
-}
 function registerWebhookCommands(program2, options) {
   const webhooks = program2.command(options.webhooksCommandName ?? "webhooks").description("Manage Hasna event webhook subscriptions");
-  webhooks.command("add").description("Add or replace a webhook or command subscription").argument("<target>", "Webhook URL or command binary").requiredOption("--id <id>", "Subscription/channel identifier").option("--transport <kind>", "Transport kind: webhook or command", "webhook").option("--name <name>", "Display name").option("--type <pattern>", "Event type filter, e.g. todos.task.*").option("--source <pattern>", "Event source filter").option("--subject <pattern>", "Event subject filter").option("--severity <pattern>", "Event severity filter").option("--secret <secret>", "Webhook HMAC secret").option("--header <name=value...>", "Webhook header", collectValues, []).option("--arg <arg...>", "Command argument", collectValues, []).option("--timeout-ms <ms>", "Transport timeout in milliseconds", parseNumber).option("--retry-attempts <n>", "Maximum delivery attempts", parseNumber).option("--retry-backoff-ms <ms>", "Initial retry backoff in milliseconds", parseNumber).option("--redact <path...>", "Event field path to redact before delivery", collectValues, []).option("--disabled", "Create channel disabled", false).option("-j, --json", "Print JSON output", false).action(async (target, actionOptions, command) => {
+  webhooks.command("add").description("Add or replace a webhook or command subscription").argument("<target>", "Webhook URL or command binary").requiredOption("--id <id>", "Subscription/channel identifier").option("--transport <kind>", "Transport kind: webhook or command", "webhook").option("--name <name>", "Display name").option("--type <pattern>", "Event type filter, e.g. todos.task.*").option("--source <pattern>", "Event source filter").option("--subject <pattern>", "Event subject filter").option("--severity <pattern>", "Event severity filter").option("--secret <secret>", "Webhook HMAC secret").option("--header <name=value...>", "Webhook header", collectValues, []).option("--arg <arg...>", "Command argument", collectValues, []).option("--timeout-ms <ms>", "Transport timeout in milliseconds", parseNumber).option("--retry-attempts <n>", "Maximum delivery attempts", parseNumber).option("--retry-backoff-ms <ms>", "Initial retry backoff in milliseconds", parseNumber).option("--redact <path...>", "Event field path to redact before delivery", collectValues, []).option("--disabled", "Create channel disabled", false).option("-j, --json", "Print JSON output", false).action(async (target, actionOptions) => {
     const timestamp = new Date().toISOString();
     const channel = {
       id: actionOptions.id,
@@ -3193,11 +3187,11 @@ function registerWebhookCommands(program2, options) {
       throw new Error(`Transport ${actionOptions.transport} is reserved for future use and cannot be added yet`);
     }
     const saved = await createClient(options).addChannel(channel);
-    print(sanitizeChannelForOutput(saved), wantsJson(actionOptions, command), `Added ${saved.transport} channel ${saved.id}`);
+    print(sanitizeChannelForOutput(saved), Boolean(actionOptions.json), `Added ${saved.transport} channel ${saved.id}`);
   });
-  webhooks.command("list").description("List configured subscriptions").option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
+  webhooks.command("list").description("List configured subscriptions").option("-j, --json", "Print JSON output", false).action(async (actionOptions) => {
     const channels = await createClient(options).listChannels();
-    if (wantsJson(actionOptions, command)) {
+    if (actionOptions.json) {
       console.log(JSON.stringify(sanitizeChannelsForOutput(channels), null, 2));
       return;
     }
@@ -3209,11 +3203,11 @@ function registerWebhookCommands(program2, options) {
       console.log(`${channel.id}	${channel.enabled ? "enabled" : "disabled"}	${channel.transport}	${channel.webhook?.url ?? channel.command?.command ?? channel.transport}`);
     }
   });
-  webhooks.command("remove").description("Remove a subscription").argument("<id>", "Subscription/channel identifier").option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
+  webhooks.command("remove").description("Remove a subscription").argument("<id>", "Subscription/channel identifier").option("-j, --json", "Print JSON output", false).action(async (id, actionOptions) => {
     const removed = await createClient(options).removeChannel(id);
-    print({ removed }, wantsJson(actionOptions, command), removed ? `Removed ${id}` : `Channel not found: ${id}`);
+    print({ removed }, Boolean(actionOptions.json), removed ? `Removed ${id}` : `Channel not found: ${id}`);
   });
-  webhooks.command("test").description("Send a test event to one subscription").argument("<id>", "Subscription/channel identifier").option("--type <type>", "Event type", "events.test").option("--subject <subject>", "Event subject").option("--message <message>", "Event message", "Hasna events test delivery").option("--data <json>", "Event data JSON object").option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
+  webhooks.command("test").description("Send a test event to one subscription").argument("<id>", "Subscription/channel identifier").option("--type <type>", "Event type", "events.test").option("--subject <subject>", "Event subject").option("--message <message>", "Event message", "Hasna events test delivery").option("--data <json>", "Event data JSON object").option("-j, --json", "Print JSON output", false).action(async (id, actionOptions) => {
     const result = await createClient(options).testChannel(id, {
       source: options.source,
       type: actionOptions.type,
@@ -3221,13 +3215,13 @@ function registerWebhookCommands(program2, options) {
       message: actionOptions.message,
       data: parseJsonObject(actionOptions.data, { test: true })
     });
-    print(result, wantsJson(actionOptions, command), `${result.status}: ${result.channelId}`);
+    print(result, Boolean(actionOptions.json), `${result.status}: ${result.channelId}`);
   });
   return webhooks;
 }
 function registerEventCommands(program2, options) {
   const events = program2.command(options.eventsCommandName ?? "events").description("Emit, list, and replay Hasna events");
-  events.command("emit").description("Emit an event from this app").argument("<type>", "Event type").option("--source <source>", "Event source override").option("--subject <subject>", "Event subject").option("--severity <severity>", "Event severity", "info").option("--message <message>", "Event message").option("--dedupe-key <key>", "Dedupe key").option("--data <json>", "Event data JSON object").option("--metadata <json>", "Event metadata JSON object").option("--no-deliver", "Record without delivering").option("--no-dedupe", "Allow duplicate id/dedupeKey events").option("-j, --json", "Print JSON output", false).action(async (type, actionOptions, command) => {
+  events.command("emit").description("Emit an event from this app").argument("<type>", "Event type").option("--source <source>", "Event source override").option("--subject <subject>", "Event subject").option("--severity <severity>", "Event severity", "info").option("--message <message>", "Event message").option("--dedupe-key <key>", "Dedupe key").option("--data <json>", "Event data JSON object").option("--metadata <json>", "Event metadata JSON object").option("--no-deliver", "Record without delivering").option("--no-dedupe", "Allow duplicate id/dedupeKey events").option("-j, --json", "Print JSON output", false).action(async (type, actionOptions) => {
     const result = await createClient(options).emit({
       source: actionOptions.source ?? options.source,
       type,
@@ -3238,9 +3232,9 @@ function registerEventCommands(program2, options) {
       data: parseJsonObject(actionOptions.data, {}),
       metadata: parseJsonObject(actionOptions.metadata, {})
     }, { deliver: actionOptions.deliver, dedupe: actionOptions.dedupe });
-    print(result, wantsJson(actionOptions, command), `${result.deduped ? "Deduped" : "Emitted"} ${result.event.id} to ${result.deliveries.length} channel(s)`);
+    print(result, Boolean(actionOptions.json), `${result.deduped ? "Deduped" : "Emitted"} ${result.event.id} to ${result.deliveries.length} channel(s)`);
   });
-  events.command("list").description("List recorded events").option("--source <source>", "Filter by source").option("--type <type>", "Filter by type").option("--limit <n>", "Limit results", parseNumber).option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
+  events.command("list").description("List recorded events").option("--source <source>", "Filter by source").option("--type <type>", "Filter by type").option("--limit <n>", "Limit results", parseNumber).option("-j, --json", "Print JSON output", false).action(async (actionOptions) => {
     let rows = await createClient(options).listEvents();
     if (actionOptions.source)
       rows = rows.filter((event) => event.source === actionOptions.source);
@@ -3248,7 +3242,7 @@ function registerEventCommands(program2, options) {
       rows = rows.filter((event) => event.type === actionOptions.type);
     if (actionOptions.limit)
       rows = rows.slice(-actionOptions.limit);
-    if (wantsJson(actionOptions, command)) {
+    if (actionOptions.json) {
       console.log(JSON.stringify(rows, null, 2));
       return;
     }
@@ -3259,14 +3253,14 @@ function registerEventCommands(program2, options) {
     for (const event of rows)
       console.log(`${event.time}	${event.id}	${event.source}	${event.type}	${event.severity}`);
   });
-  events.command("replay").description("Replay recorded events").option("--id <id>", "Replay one event id").option("--source <source>", "Filter by source").option("--type <type>", "Filter by type").option("--dry-run", "Preview without delivery", false).option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
+  events.command("replay").description("Replay recorded events").option("--id <id>", "Replay one event id").option("--source <source>", "Filter by source").option("--type <type>", "Filter by type").option("--dry-run", "Preview without delivery", false).option("-j, --json", "Print JSON output", false).action(async (actionOptions) => {
     const result = await createClient(options).replay({
       eventId: actionOptions.id,
       source: actionOptions.source,
       type: actionOptions.type,
       dryRun: actionOptions.dryRun
     });
-    print(result, wantsJson(actionOptions, command), `Replayed ${result.events.length} event(s), ${result.deliveries.length} delivery result(s)`);
+    print(result, Boolean(actionOptions.json), `Replayed ${result.events.length} event(s), ${result.deliveries.length} delivery result(s)`);
   });
   return events;
 }
@@ -7918,996 +7912,610 @@ function manifestValidate() {
 // src/commands/setup.ts
 import { homedir as homedir3 } from "os";
 init_db();
-function quote(value) {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
+
+// src/remote.ts
+init_db();
+import { spawnSync as spawnSync2 } from "child_process";
+import { hostname as hostname4 } from "os";
+
+// src/topology.ts
+init_db();
+import { existsSync as existsSync5 } from "fs";
+import { arch as arch2, hostname as hostname3, platform as platform2, userInfo as userInfo2 } from "os";
+import { spawnSync } from "child_process";
+init_paths();
+var MACHINES_CONSUMER_CONTRACT_VERSION = 1;
+var MACHINES_PACKAGE_NAME = "@hasna/machines";
+var DEFAULT_MACHINE_RESOLVER_TTL_MS = 24 * 60 * 60 * 1000;
+var MACHINES_CONSUMER_CAPABILITIES = {
+  topology: true,
+  compatibility: true,
+  route_resolution: true,
+  cli_json_fallback: true,
+  workspace_path_mapping: true,
+  workspace_diagnostics: true,
+  schema_artifacts: true,
+  cacheability_metadata: true,
+  resolver_snapshots: true,
+  field_capability_descriptors: true
+};
+function getMachinesConsumerCapabilities() {
+  return { ...MACHINES_CONSUMER_CAPABILITIES };
 }
-function buildBaseSteps(machine) {
-  const steps = [
-    {
-      id: "workspace",
-      title: "Ensure workspace directory exists",
-      command: `mkdir -p ${quote(machine.workspacePath)}`,
-      manager: "shell"
-    },
-    {
-      id: "bun",
-      title: "Install Bun if missing",
-      command: "command -v bun >/dev/null 2>&1 || curl -fsSL https://bun.sh/install | bash",
-      manager: "shell"
-    }
-  ];
-  if (machine.platform === "linux") {
-    steps.push({
-      id: "apt-base",
-      title: "Install core Linux tooling",
-      command: "sudo apt-get update && sudo apt-get install -y git curl unzip build-essential",
-      manager: "apt",
-      privileged: true
-    });
-  } else if (machine.platform === "macos") {
-    steps.push({
-      id: "brew-base",
-      title: "Install Homebrew if missing",
-      command: 'command -v brew >/dev/null 2>&1 || /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"',
-      manager: "brew"
-    });
-    steps.push({
-      id: "brew-core",
-      title: "Install core macOS tooling",
-      command: "brew install git coreutils",
-      manager: "brew"
-    });
-  }
-  return steps;
+function normalizePlatform2(value = platform2()) {
+  const normalized = value.toLowerCase();
+  if (normalized === "darwin" || normalized === "macos")
+    return "macos";
+  if (normalized === "win32" || normalized === "windows")
+    return "windows";
+  if (normalized === "linux")
+    return "linux";
+  return value;
 }
-function buildPackageSteps(machine) {
-  return (machine.packages || []).map((pkg, index) => {
-    const manager = pkg.manager || (machine.platform === "macos" ? "brew" : "apt");
-    let command = pkg.name;
-    if (manager === "bun") {
-      command = `bun install -g ${quote(pkg.name)}`;
-    } else if (manager === "brew") {
-      command = `brew install ${quote(pkg.name)}`;
-    } else if (manager === "apt") {
-      command = `sudo apt-get install -y ${quote(pkg.name)}`;
-    }
-    return {
-      id: `package-${index + 1}`,
-      title: `Install package ${pkg.name}`,
-      command,
-      manager,
-      privileged: manager === "apt"
-    };
+function defaultRunner(command) {
+  const result = spawnSync("bash", ["-c", command], {
+    encoding: "utf8",
+    env: process.env
   });
-}
-function buildSetupPlan(machineId) {
-  const manifest = readManifest();
-  const currentMachineId = getLocalMachineId();
-  const selected = machineId ? manifest.machines.find((machine) => machine.id === machineId) : manifest.machines.find((machine) => machine.id === currentMachineId);
-  const target = selected || {
-    id: currentMachineId,
-    platform: "linux",
-    workspacePath: `${homedir3()}/workspace`
-  };
-  const steps = [...buildBaseSteps(target), ...buildPackageSteps(target)];
   return {
-    machineId: target.id,
-    mode: "plan",
-    steps,
-    executed: 0
+    stdout: result.stdout || "",
+    stderr: result.stderr || "",
+    exitCode: result.status ?? 1
   };
 }
-function runSetup(machineId, options = {}) {
-  const plan = buildSetupPlan(machineId);
-  if (!options.apply) {
-    return plan;
+function hasCommand(command, runner) {
+  return runner(`command -v ${command} >/dev/null 2>&1`).exitCode === 0;
+}
+function parseTailscaleStatus(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object")
+      return null;
+    return parsed;
+  } catch {
+    return null;
   }
-  if (!options.yes) {
-    throw new Error("Setup execution requires --yes.");
+}
+function loadTailscalePeers(runner, warnings) {
+  const peers = new Map;
+  if (!hasCommand("tailscale", runner)) {
+    warnings.push("tailscale_not_available");
+    return peers;
   }
-  let executed = 0;
-  for (const step of plan.steps) {
-    const result = Bun.spawnSync(["bash", "-lc", step.command], {
-      stdout: "pipe",
-      stderr: "pipe",
-      env: process.env
-    });
-    if (result.exitCode !== 0) {
-      recordSetupRun(plan.machineId, "failed", {
-        executed,
-        failedStep: step,
-        stderr: result.stderr.toString()
-      });
-      throw new Error(`Setup step failed (${step.id}): ${result.stderr.toString().trim()}`);
-    }
-    executed += 1;
+  const result = runner("tailscale status --json");
+  if (result.exitCode !== 0) {
+    warnings.push(`tailscale_status_failed:${result.stderr.trim() || result.exitCode}`);
+    return peers;
   }
-  const summary = {
-    machineId: plan.machineId,
-    mode: "apply",
-    steps: plan.steps,
-    executed
+  const status = parseTailscaleStatus(result.stdout);
+  if (!status) {
+    warnings.push("tailscale_status_invalid_json");
+    return peers;
+  }
+  const addPeer = (peer) => {
+    if (!peer)
+      return;
+    const id = peer.HostName || peer.DNSName?.split(".")[0];
+    if (id)
+      peers.set(id, peer);
   };
-  recordSetupRun(plan.machineId, "completed", summary);
-  return summary;
+  addPeer(status.Self);
+  for (const peer of Object.values(status.Peer ?? {}))
+    addPeer(peer);
+  return peers;
 }
-
-// src/commands/backup.ts
-import { homedir as homedir4, hostname as hostname3 } from "os";
-import { join as join4 } from "path";
-var MACHINES_BACKUP_BUCKET_ENV = "HASNA_MACHINES_S3_BUCKET";
-var MACHINES_BACKUP_BUCKET_FALLBACK_ENV = "MACHINES_S3_BUCKET";
-var MACHINES_BACKUP_PREFIX_ENV = "HASNA_MACHINES_S3_PREFIX";
-var MACHINES_BACKUP_PREFIX_FALLBACK_ENV = "MACHINES_S3_PREFIX";
-var DEFAULT_BACKUP_PREFIX = "machines";
-function quote2(value) {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
+function machineKeys(machine) {
+  return [
+    machine.id,
+    machine.hostname,
+    machine.tailscaleName?.split(".")[0],
+    machine.tailscaleName,
+    machine.sshAddress?.split("@").pop()
+  ].filter((value) => Boolean(value));
 }
-function readEnv(name) {
-  const value = process.env[name]?.trim();
-  return value || undefined;
+function findTailscalePeer(machine, machineId, peers) {
+  if (machine) {
+    for (const key of machineKeys(machine)) {
+      const peer = peers.get(key) ?? peers.get(key.replace(/\.$/, ""));
+      if (peer)
+        return peer;
+    }
+  }
+  return peers.get(machineId) ?? null;
 }
-function readBackupBucketEnv() {
-  const primary = readEnv(MACHINES_BACKUP_BUCKET_ENV);
-  if (primary)
-    return { bucket: primary, bucketSource: MACHINES_BACKUP_BUCKET_ENV };
-  const fallback = readEnv(MACHINES_BACKUP_BUCKET_FALLBACK_ENV);
-  if (fallback)
-    return { bucket: fallback, bucketSource: MACHINES_BACKUP_BUCKET_FALLBACK_ENV };
-  return null;
+function envReachableHosts() {
+  const raw = process.env["HASNA_MACHINES_REACHABLE_HOSTS"];
+  return new Set((raw || "").split(",").map((value) => value.trim()).filter(Boolean));
 }
-function readBackupPrefixEnv() {
-  const primary = readEnv(MACHINES_BACKUP_PREFIX_ENV);
-  if (primary)
-    return { prefix: primary, prefixSource: MACHINES_BACKUP_PREFIX_ENV };
-  const fallback = readEnv(MACHINES_BACKUP_PREFIX_FALLBACK_ENV);
-  if (fallback)
-    return { prefix: fallback, prefixSource: MACHINES_BACKUP_PREFIX_FALLBACK_ENV };
-  return null;
+function manifestHostReachable(target) {
+  const overrides = envReachableHosts();
+  if (overrides.size === 0)
+    return null;
+  return overrides.has(target);
 }
-function resolveBackupTarget(options = {}) {
-  const explicitBucket = options.bucket?.trim();
-  const envBucket = explicitBucket ? null : readBackupBucketEnv();
-  const bucket = explicitBucket || envBucket?.bucket;
-  if (!bucket) {
-    throw new Error(`Missing S3 backup bucket. Pass --bucket or set ${MACHINES_BACKUP_BUCKET_ENV} or ${MACHINES_BACKUP_BUCKET_FALLBACK_ENV}.`);
+function routeHints(input) {
+  const hints = [];
+  if (input.machineId === input.localMachineId) {
+    hints.push({ kind: "local", target: "localhost", reachable: true });
   }
-  const explicitPrefix = options.prefix?.trim();
-  const envPrefix = explicitPrefix ? null : readBackupPrefixEnv();
-  return {
-    bucket,
-    prefix: explicitPrefix || envPrefix?.prefix || DEFAULT_BACKUP_PREFIX,
-    bucketSource: explicitBucket ? "argument" : envBucket.bucketSource,
-    prefixSource: explicitPrefix ? "argument" : envPrefix?.prefixSource || "default"
-  };
-}
-function defaultBackupSources() {
-  const home = homedir4();
-  return [
-    join4(home, ".hasna"),
-    join4(home, ".ssh"),
-    join4(home, ".secrets")
-  ];
-}
-function buildBackupPlan(bucket, prefix) {
-  const target = resolveBackupTarget({ bucket, prefix });
-  const archivePath = join4(homedir4(), ".hasna", "machines", "backup.tgz");
-  const sources = defaultBackupSources();
-  const steps = [
-    {
-      id: "backup-archive",
-      title: "Create compressed machine backup archive",
-      command: `tar -czf ${quote2(archivePath)} ${sources.map((source) => quote2(source)).join(" ")}`,
-      manager: "shell"
-    },
-    {
-      id: "backup-upload",
-      title: "Upload archive to S3",
-      command: `aws s3 cp ${quote2(archivePath)} ${quote2(`s3://${target.bucket}/${target.prefix}/${hostname3()}-backup.tgz`)}`,
-      manager: "custom"
-    }
-  ];
-  return {
-    machineId: process.env["HASNA_MACHINES_MACHINE_ID"] || "local",
-    mode: "plan",
-    steps,
-    executed: 0
-  };
-}
-function runBackup(bucket, prefix, options = {}) {
-  const plan = buildBackupPlan(bucket, prefix);
-  if (!options.apply)
-    return plan;
-  if (!options.yes) {
-    throw new Error("Backup execution requires --yes.");
+  if (input.manifest?.sshAddress) {
+    hints.push({ kind: "ssh", target: input.manifest.sshAddress, reachable: manifestHostReachable(input.manifest.sshAddress) });
   }
-  let executed = 0;
-  for (const step of plan.steps) {
-    const result = Bun.spawnSync(["bash", "-lc", step.command], {
-      stdout: "pipe",
-      stderr: "pipe",
-      env: process.env
-    });
-    if (result.exitCode !== 0) {
-      throw new Error(`Backup step failed (${step.id}): ${result.stderr.toString().trim()}`);
-    }
-    executed += 1;
+  if (input.manifest?.hostname) {
+    hints.push({ kind: "lan", target: input.manifest.hostname, reachable: manifestHostReachable(input.manifest.hostname) });
   }
-  return {
-    machineId: plan.machineId,
-    mode: "apply",
-    steps: plan.steps,
-    executed
-  };
+  const tailscaleTarget = input.manifest?.tailscaleName ?? input.peer?.DNSName ?? input.peer?.TailscaleIPs?.[0];
+  if (tailscaleTarget) {
+    hints.push({ kind: "tailscale", target: tailscaleTarget.replace(/\.$/, ""), reachable: input.peer?.Online ?? null });
+  }
+  return hints;
 }
-
-// src/commands/cert.ts
-import { homedir as homedir5, platform as platform2 } from "os";
-import { join as join5 } from "path";
-function quote3(value) {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
+function routeRank(hint) {
+  if (hint.kind === "local")
+    return 0;
+  if (hint.reachable === true && hint.kind === "ssh")
+    return 1;
+  if (hint.reachable === true && hint.kind === "lan")
+    return 2;
+  if (hint.reachable === true && hint.kind === "tailscale")
+    return 3;
+  if (hint.reachable === false)
+    return 8;
+  if (hint.kind === "ssh")
+    return 4;
+  if (hint.kind === "lan")
+    return 5;
+  if (hint.kind === "tailscale")
+    return 6;
+  return 9;
 }
-function certDir() {
-  return join5(homedir5(), ".hasna", "machines", "certs");
+function selectRouteHint(hints) {
+  return [...hints].sort((left, right) => routeRank(left) - routeRank(right))[0] ?? null;
 }
-function buildCertPlan(domains) {
-  if (domains.length === 0) {
-    throw new Error("At least one domain is required.");
-  }
-  const primary = domains[0];
-  const certPath = join5(certDir(), `${primary}.pem`);
-  const keyPath = join5(certDir(), `${primary}-key.pem`);
-  const steps = [];
-  if (platform2() === "darwin") {
-    steps.push({
-      id: "mkcert-install-macos",
-      title: "Install mkcert on macOS",
-      command: "brew install mkcert nss",
-      manager: "brew"
-    });
-  } else {
-    steps.push({
-      id: "mkcert-install-linux",
-      title: "Install mkcert on Linux",
-      command: "sudo apt-get update && sudo apt-get install -y mkcert libnss3-tools",
-      manager: "apt",
-      privileged: true
-    });
-  }
-  steps.push({
-    id: "mkcert-local-ca",
-    title: "Install local mkcert CA",
-    command: "mkcert -install",
-    manager: "custom"
-  }, {
-    id: "mkcert-issue",
-    title: `Issue certificate for ${domains.join(", ")}`,
-    command: `mkdir -p ${quote3(certDir())} && mkcert -cert-file ${quote3(certPath)} -key-file ${quote3(keyPath)} ${domains.map((domain) => quote3(domain)).join(" ")}`,
-    manager: "custom"
+function buildEntry(input) {
+  const manifest = input.manifest;
+  const peer = input.peer;
+  const hints = routeHints({
+    machineId: input.machineId,
+    localMachineId: input.localMachineId,
+    manifest,
+    peer
   });
+  const selectedRoute = selectRouteHint(hints);
+  const route = selectedRoute?.kind === "ssh" ? "ssh" : selectedRoute?.kind ?? "unknown";
   return {
-    machineId: process.env["HASNA_MACHINES_MACHINE_ID"] || "local",
-    mode: "plan",
-    steps,
-    executed: 0
+    machine_id: input.machineId,
+    hostname: manifest?.hostname ?? peer?.HostName ?? null,
+    platform: manifest?.platform ?? (peer?.OS ? normalizePlatform2(peer.OS) : null),
+    os: peer?.OS ?? null,
+    user: typeof manifest?.metadata?.user === "string" ? manifest.metadata.user : null,
+    workspace_path: manifest?.workspacePath ?? null,
+    manifest_declared: Boolean(manifest),
+    heartbeat_status: input.heartbeat?.status ?? "unknown",
+    last_heartbeat_at: input.heartbeat?.updated_at ?? null,
+    tailscale: {
+      dns_name: manifest?.tailscaleName ?? peer?.DNSName?.replace(/\.$/, "") ?? null,
+      ips: peer?.TailscaleIPs ?? [],
+      online: peer?.Online ?? null,
+      active: peer?.Active ?? null,
+      last_seen: peer?.LastSeen ?? null
+    },
+    ssh: {
+      address: manifest?.sshAddress ?? null,
+      route,
+      command_target: selectedRoute?.target ?? null
+    },
+    route_hints: hints,
+    tags: manifest?.tags ?? [],
+    metadata: manifest?.metadata ?? {}
   };
 }
-function runCertPlan(domains, options = {}) {
-  const plan = buildCertPlan(domains);
-  if (!options.apply)
-    return plan;
-  if (!options.yes) {
-    throw new Error("Certificate generation requires --yes.");
-  }
-  let executed = 0;
-  for (const step of plan.steps) {
-    const result = Bun.spawnSync(["bash", "-lc", step.command], {
-      stdout: "pipe",
-      stderr: "pipe",
-      env: process.env
+function discoverMachineTopology(options = {}) {
+  const now2 = options.now ?? new Date;
+  const runner = options.runner ?? defaultRunner;
+  const warnings = [];
+  const manifest = readManifest();
+  const heartbeats = listHeartbeats();
+  const heartbeatByMachine = new Map(heartbeats.map((heartbeat) => [heartbeat.machine_id, heartbeat]));
+  const localMachineId = getLocalMachineId();
+  const peers = options.includeTailscale === false ? new Map : loadTailscalePeers(runner, warnings);
+  const machineIds = new Set([
+    localMachineId,
+    ...manifest.machines.map((machine) => machine.id),
+    ...heartbeats.map((heartbeat) => heartbeat.machine_id),
+    ...peers.keys()
+  ]);
+  const manifestById = new Map(manifest.machines.map((machine) => [machine.id, machine]));
+  const machines = [...machineIds].sort().map((machineId) => {
+    const manifestMachine = manifestById.get(machineId);
+    return buildEntry({
+      machineId,
+      localMachineId,
+      manifest: manifestMachine,
+      peer: findTailscalePeer(manifestMachine ?? null, machineId, peers),
+      heartbeat: heartbeatByMachine.get(machineId)
     });
-    if (result.exitCode !== 0) {
-      throw new Error(`Certificate step failed (${step.id}): ${result.stderr.toString().trim()}`);
-    }
-    executed += 1;
-  }
+  });
   return {
-    machineId: plan.machineId,
-    mode: "apply",
-    steps: plan.steps,
-    executed
+    schema_version: MACHINES_CONSUMER_CONTRACT_VERSION,
+    package: {
+      name: MACHINES_PACKAGE_NAME,
+      version: getPackageVersion()
+    },
+    capabilities: getMachinesConsumerCapabilities(),
+    generated_at: now2.toISOString(),
+    local_machine_id: localMachineId,
+    local_hostname: hostname3(),
+    current_platform: normalizePlatform2(),
+    manifest_path_known: existsSync5(getManifestPath()),
+    machines,
+    warnings
   };
 }
-
-// src/commands/dns.ts
-init_paths();
-import { existsSync as existsSync5, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
-import { join as join6 } from "path";
-function getDnsPath() {
-  return join6(getDataDir(), "dns.json");
-}
-function readMappings() {
-  const path = getDnsPath();
-  if (!existsSync5(path))
-    return [];
-  return JSON.parse(readFileSync3(path, "utf8"));
-}
-function writeMappings(mappings) {
-  const path = getDnsPath();
-  ensureParentDir(path);
-  writeFileSync2(path, `${JSON.stringify(mappings, null, 2)}
-`, "utf8");
-  return path;
-}
-function addDomainMapping(domain, port, targetHost = "127.0.0.1") {
-  const mappings = readMappings().filter((entry) => entry.domain !== domain);
-  mappings.push({ domain, port, targetHost });
-  writeMappings(mappings);
-  return mappings.sort((left, right) => left.domain.localeCompare(right.domain));
+function normalizeMachineAlias(value) {
+  return value.trim().replace(/\.$/, "").toLowerCase();
 }
-function listDomainMappings() {
-  return readMappings().sort((left, right) => left.domain.localeCompare(right.domain));
+function routeTargetMatches(machine, requested) {
+  const normalized = normalizeMachineAlias(requested);
+  const values = [
+    machine.ssh.address,
+    machine.ssh.command_target,
+    machine.tailscale.dns_name,
+    machine.tailscale.dns_name?.split(".")[0],
+    ...machine.tailscale.ips,
+    ...machine.route_hints.map((hint) => hint.target),
+    ...machine.route_hints.map((hint) => hint.target.split("@").pop() ?? hint.target)
+  ].filter((value) => Boolean(value));
+  return values.some((value) => normalizeMachineAlias(value) === normalized);
 }
-function renderDomainMapping(domain) {
-  const entry = readMappings().find((mapping) => mapping.domain === domain);
-  if (!entry) {
-    throw new Error(`Domain mapping not found: ${domain}`);
+function findRouteMachine(topology, requestedMachineId) {
+  const requested = normalizeMachineAlias(requestedMachineId);
+  if (requested === "local" || requested === "localhost" || requested === normalizeMachineAlias(hostname3()) || requested === normalizeMachineAlias(topology.local_machine_id)) {
+    return {
+      machine: topology.machines.find((machine) => machine.machine_id === topology.local_machine_id) ?? null,
+      matchedBy: "local_alias"
+    };
   }
-  return {
-    hostsEntry: `${entry.targetHost} ${entry.domain}`,
-    caddySnippet: `${entry.domain} {
-  reverse_proxy 127.0.0.1:${entry.port}
-  tls ${join6(getDataDir(), "certs", `${entry.domain}.pem`)} ${join6(getDataDir(), "certs", `${entry.domain}-key.pem`)}
-}`,
-    certPath: join6(getDataDir(), "certs", `${entry.domain}.pem`),
-    keyPath: join6(getDataDir(), "certs", `${entry.domain}-key.pem`)
-  };
+  const machineIdMatch = topology.machines.find((machine) => normalizeMachineAlias(machine.machine_id) === requested);
+  if (machineIdMatch)
+    return { machine: machineIdMatch, matchedBy: "machine_id" };
+  const hostnameMatch = topology.machines.find((machine) => machine.hostname && normalizeMachineAlias(machine.hostname) === requested);
+  if (hostnameMatch)
+    return { machine: hostnameMatch, matchedBy: "hostname" };
+  const tailscaleMatch = topology.machines.find((machine) => {
+    if (!machine.tailscale.dns_name)
+      return false;
+    const dns = normalizeMachineAlias(machine.tailscale.dns_name);
+    return dns === requested || dns.split(".")[0] === requested;
+  });
+  if (tailscaleMatch)
+    return { machine: tailscaleMatch, matchedBy: "tailscale" };
+  const routeMatch = topology.machines.find((machine) => routeTargetMatches(machine, requestedMachineId));
+  if (routeMatch)
+    return { machine: routeMatch, matchedBy: "route_target" };
+  return { machine: null, matchedBy: null };
 }
-
-// src/commands/diff.ts
-function packageNames(machine) {
-  return (machine.packages || []).map((pkg) => pkg.name).sort();
+function routeConfidence(input) {
+  if (input.matchedBy === "local_alias")
+    return "exact";
+  if (input.hint?.kind === "local")
+    return "exact";
+  if (input.hint?.reachable === true)
+    return "high";
+  if (input.machine.manifest_declared && (input.hint?.kind === "ssh" || input.hint?.kind === "lan"))
+    return "medium";
+  if (input.hint)
+    return "low";
+  return "none";
 }
-function fileTargets(machine) {
-  return (machine.files || []).map((file) => `${file.source}->${file.target}`).sort();
+function addMilliseconds(date, milliseconds) {
+  return new Date(date.getTime() + milliseconds).toISOString();
 }
-function diffMachines(leftMachineId, rightMachineId) {
-  const left = getManifestMachine(leftMachineId);
-  if (!left) {
-    throw new Error(`Machine not found in manifest: ${leftMachineId}`);
-  }
-  const right = rightMachineId ? getManifestMachine(rightMachineId) : detectCurrentMachineManifest();
-  if (!right) {
-    throw new Error(`Machine not found in manifest: ${rightMachineId}`);
+function routeAuthority(input) {
+  if (!input.machine)
+    return "unresolved";
+  if (input.matchedBy === "fallback")
+    return "fallback";
+  if (input.selectedHint?.kind === "local")
+    return "live_topology";
+  if (input.selectedHint?.kind === "tailscale" || input.machine.tailscale.online !== null)
+    return "live_topology";
+  if (input.machine.manifest_declared)
+    return "manifest";
+  return "open-machines";
+}
+function workspaceAuthority(paths) {
+  const sources = [paths.workspace_root.source, paths.project_root.source, paths.open_files_root.source];
+  if (sources.some((source) => source === "argument"))
+    return "argument";
+  if (sources.some((source) => source === "manifest_metadata"))
+    return "manifest_metadata";
+  if (sources.some((source) => source === "manifest"))
+    return "manifest";
+  if (sources.some((source) => source === "inferred"))
+    return "inferred";
+  if (sources.every((source) => source === "unresolved"))
+    return "unresolved";
+  return "open-machines";
+}
+function cacheability(input) {
+  const ttlMs = input.ttlMs === undefined ? DEFAULT_MACHINE_RESOLVER_TTL_MS : input.ttlMs;
+  const expiresAt = typeof ttlMs === "number" && ttlMs > 0 ? addMilliseconds(input.observedAt, ttlMs) : null;
+  const stale = expiresAt ? input.now.getTime() > new Date(expiresAt).getTime() : false;
+  const confidenceCacheable = input.confidence !== "none" && input.confidence !== "low";
+  const cacheable = input.ok && confidenceCacheable && !stale && input.authority !== "unresolved";
+  const reasons = [...input.reasons];
+  if (!input.ok)
+    reasons.push("resolver_not_ok");
+  if (!confidenceCacheable)
+    reasons.push(`low_confidence:${input.confidence}`);
+  if (stale)
+    reasons.push("stale");
+  if (input.authority === "unresolved")
+    reasons.push("unresolved_authority");
+  return {
+    observed_at: input.observedAt.toISOString(),
+    verified_at: input.ok ? input.now.toISOString() : null,
+    expires_at: expiresAt,
+    ttl_ms: typeof ttlMs === "number" && ttlMs > 0 ? ttlMs : null,
+    source_authority: input.authority,
+    confidence: input.confidence,
+    cacheable,
+    stale,
+    reasons: [...new Set(reasons)].sort()
+  };
+}
+function resolveMachineRoute(machineId, options = {}) {
+  const now2 = options.now ?? new Date;
+  const topology = options.topology ?? discoverMachineTopology(options);
+  const warnings = [...topology.warnings];
+  const { machine, matchedBy } = findRouteMachine(topology, machineId);
+  const generatedAt = now2.toISOString();
+  if (!machine) {
+    warnings.push(`machine_not_found:${machineId}`);
+    return {
+      schema_version: MACHINES_CONSUMER_CONTRACT_VERSION,
+      package: { name: MACHINES_PACKAGE_NAME, version: getPackageVersion() },
+      ok: false,
+      machine_id: null,
+      requested_machine_id: machineId,
+      generated_at: generatedAt,
+      route: "unknown",
+      source: "unknown",
+      target: null,
+      command_target: null,
+      confidence: "none",
+      local: false,
+      evidence: {
+        topology: true,
+        matched_by: null,
+        manifest_declared: null,
+        heartbeat_status: null,
+        tailscale_online: null,
+        selected_hint: null
+      },
+      cacheability: cacheability({
+        ok: false,
+        observedAt: now2,
+        now: now2,
+        ttlMs: options.resolverTtlMs,
+        authority: "unresolved",
+        confidence: "none",
+        reasons: [`machine_not_found:${machineId}`]
+      }),
+      warnings
+    };
   }
-  const changedFields = [
-    left.platform !== right.platform ? "platform" : null,
-    left.connection !== right.connection ? "connection" : null,
-    left.workspacePath !== right.workspacePath ? "workspacePath" : null,
-    left.bunPath !== right.bunPath ? "bunPath" : null
-  ].filter(Boolean);
-  const leftPackages = new Set(packageNames(left));
-  const rightPackages = new Set(packageNames(right));
-  const leftFiles = new Set(fileTargets(left));
-  const rightFiles = new Set(fileTargets(right));
+  const selectedHint = selectRouteHint(machine.route_hints);
+  const route = selectedHint?.kind ?? machine.ssh.route ?? "unknown";
+  const local = route === "local" || machine.machine_id === topology.local_machine_id;
+  const confidence = routeConfidence({ machine, hint: selectedHint, matchedBy });
+  const ok = Boolean(selectedHint?.target);
   return {
-    leftMachineId: left.id,
-    rightMachineId: right.id,
-    changedFields,
-    missingPackages: {
-      leftOnly: [...leftPackages].filter((pkg) => !rightPackages.has(pkg)),
-      rightOnly: [...rightPackages].filter((pkg) => !leftPackages.has(pkg))
+    schema_version: MACHINES_CONSUMER_CONTRACT_VERSION,
+    package: topology.package,
+    ok,
+    machine_id: machine.machine_id,
+    requested_machine_id: machineId,
+    generated_at: generatedAt,
+    route,
+    source: route,
+    target: selectedHint?.target ?? null,
+    command_target: selectedHint?.target ?? null,
+    confidence,
+    local,
+    evidence: {
+      topology: true,
+      matched_by: matchedBy,
+      manifest_declared: machine.manifest_declared,
+      heartbeat_status: machine.heartbeat_status,
+      tailscale_online: machine.tailscale.online,
+      selected_hint: selectedHint
     },
-    missingFiles: {
-      leftOnly: [...leftFiles].filter((file) => !rightFiles.has(file)),
-      rightOnly: [...rightFiles].filter((file) => !leftFiles.has(file))
-    }
+    cacheability: cacheability({
+      ok,
+      observedAt: now2,
+      now: now2,
+      ttlMs: options.resolverTtlMs,
+      authority: routeAuthority({ machine, selectedHint, matchedBy }),
+      confidence,
+      reasons: selectedHint ? [] : ["route_target_unresolved"]
+    }),
+    warnings
   };
 }
-
-// src/remote.ts
-init_db();
-import { spawnSync as spawnSync2 } from "child_process";
-import { hostname as hostname5 } from "os";
-
-// src/topology.ts
-init_db();
-import { existsSync as existsSync6 } from "fs";
-import { arch as arch2, hostname as hostname4, platform as platform3, userInfo as userInfo2 } from "os";
-import { spawnSync } from "child_process";
-init_paths();
-var MACHINES_CONSUMER_CONTRACT_VERSION = 1;
-var MACHINES_PACKAGE_NAME = "@hasna/machines";
-var DEFAULT_MACHINE_RESOLVER_TTL_MS = 24 * 60 * 60 * 1000;
-var MACHINES_CONSUMER_CAPABILITIES = {
-  topology: true,
-  compatibility: true,
-  route_resolution: true,
-  cli_json_fallback: true,
-  workspace_path_mapping: true,
-  workspace_diagnostics: true,
-  schema_artifacts: true,
-  cacheability_metadata: true,
-  resolver_snapshots: true,
-  field_capability_descriptors: true
-};
-function getMachinesConsumerCapabilities() {
-  return { ...MACHINES_CONSUMER_CAPABILITIES };
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
-function normalizePlatform2(value = platform3()) {
-  const normalized = value.toLowerCase();
-  if (normalized === "darwin" || normalized === "macos")
-    return "macos";
-  if (normalized === "win32" || normalized === "windows")
-    return "windows";
-  if (normalized === "linux")
-    return "linux";
-  return value;
+function metadataString(metadata, keys) {
+  for (const key of keys) {
+    const value = metadata[key];
+    if (typeof value === "string" && value.trim())
+      return value.trim();
+  }
+  return null;
 }
-function defaultRunner(command) {
-  const result = spawnSync("bash", ["-c", command], {
-    encoding: "utf8",
-    env: process.env
-  });
-  return {
-    stdout: result.stdout || "",
-    stderr: result.stderr || "",
-    exitCode: result.status ?? 1
-  };
-}
-function hasCommand(command, runner) {
-  return runner(`command -v ${command} >/dev/null 2>&1`).exitCode === 0;
-}
-function parseTailscaleStatus(raw) {
-  try {
-    const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== "object")
-      return null;
-    return parsed;
-  } catch {
-    return null;
+function metadataBoolean(metadata, keys) {
+  for (const key of keys) {
+    const value = metadata[key];
+    if (typeof value === "boolean")
+      return value;
   }
+  return null;
 }
-function loadTailscalePeers(runner, warnings) {
-  const peers = new Map;
-  if (!hasCommand("tailscale", runner)) {
-    warnings.push("tailscale_not_available");
-    return peers;
-  }
-  const result = runner("tailscale status --json");
-  if (result.exitCode !== 0) {
-    warnings.push(`tailscale_status_failed:${result.stderr.trim() || result.exitCode}`);
-    return peers;
-  }
-  const status = parseTailscaleStatus(result.stdout);
-  if (!status) {
-    warnings.push("tailscale_status_invalid_json");
-    return peers;
+function metadataStringArray(metadata, keys) {
+  for (const key of keys) {
+    const value = metadata[key];
+    if (Array.isArray(value))
+      return value.filter((entry) => typeof entry === "string");
   }
-  const addPeer = (peer) => {
-    if (!peer)
-      return;
-    const id = peer.HostName || peer.DNSName?.split(".")[0];
-    if (id)
-      peers.set(id, peer);
-  };
-  addPeer(status.Self);
-  for (const peer of Object.values(status.Peer ?? {}))
-    addPeer(peer);
-  return peers;
-}
-function machineKeys(machine) {
-  return [
-    machine.id,
-    machine.hostname,
-    machine.tailscaleName?.split(".")[0],
-    machine.tailscaleName,
-    machine.sshAddress?.split("@").pop()
-  ].filter((value) => Boolean(value));
+  return [];
 }
-function findTailscalePeer(machine, machineId, peers) {
-  if (machine) {
-    for (const key of machineKeys(machine)) {
-      const peer = peers.get(key) ?? peers.get(key.replace(/\.$/, ""));
-      if (peer)
-        return peer;
+function readMappedPath(input) {
+  for (const containerName of input.containers) {
+    const container = input.metadata[containerName];
+    if (!isRecord(container))
+      continue;
+    for (const key of input.keys) {
+      const value = container[key];
+      if (typeof value === "string" && value.trim())
+        return value.trim();
+      if (isRecord(value)) {
+        const path = metadataString(value, ["path", "root", "workspacePath", "workspace_path"]);
+        if (path)
+          return path;
+      }
     }
   }
-  return peers.get(machineId) ?? null;
+  return null;
 }
-function envReachableHosts() {
-  const raw = process.env["HASNA_MACHINES_REACHABLE_HOSTS"];
-  return new Set((raw || "").split(",").map((value) => value.trim()).filter(Boolean));
+function trimTrailingSlash(value) {
+  return value.replace(/\/+$/, "");
 }
-function manifestHostReachable(target) {
-  const overrides = envReachableHosts();
-  if (overrides.size === 0)
-    return null;
-  return overrides.has(target);
+function joinPath(left, right) {
+  return `${trimTrailingSlash(left)}/${right.replace(/^\/+/, "")}`;
 }
-function routeHints(input) {
-  const hints = [];
-  if (input.machineId === input.localMachineId) {
-    hints.push({ kind: "local", target: "localhost", reachable: true });
-  }
-  if (input.manifest?.sshAddress) {
-    hints.push({ kind: "ssh", target: input.manifest.sshAddress, reachable: manifestHostReachable(input.manifest.sshAddress) });
-  }
-  if (input.manifest?.hostname) {
-    hints.push({ kind: "lan", target: input.manifest.hostname, reachable: manifestHostReachable(input.manifest.hostname) });
-  }
-  const tailscaleTarget = input.manifest?.tailscaleName ?? input.peer?.DNSName ?? input.peer?.TailscaleIPs?.[0];
-  if (tailscaleTarget) {
-    hints.push({ kind: "tailscale", target: tailscaleTarget.replace(/\.$/, ""), reachable: input.peer?.Online ?? null });
+function inferRepoRoot(workspaceRoot, repoName) {
+  if (!workspaceRoot || !repoName)
+    return null;
+  const root = trimTrailingSlash(workspaceRoot);
+  if (root.endsWith(`/${repoName}`) || root === repoName)
+    return root;
+  if (root.endsWith("/workspace") || root.endsWith("/Workspace")) {
+    return joinPath(root, `hasna/opensource/${repoName}`);
   }
-  return hints;
+  return joinPath(root, repoName);
 }
-function routeRank(hint) {
-  if (hint.kind === "local")
-    return 0;
-  if (hint.reachable === true && hint.kind === "ssh")
-    return 1;
-  if (hint.reachable === true && hint.kind === "lan")
-    return 2;
-  if (hint.reachable === true && hint.kind === "tailscale")
-    return 3;
-  if (hint.reachable === false)
-    return 8;
-  if (hint.kind === "ssh")
-    return 4;
-  if (hint.kind === "lan")
-    return 5;
-  if (hint.kind === "tailscale")
-    return 6;
-  return 9;
+function shellQuote(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
 }
-function selectRouteHint(hints) {
-  return [...hints].sort((left, right) => routeRank(left) - routeRank(right))[0] ?? null;
+function shellCommand(command) {
+  return command.map(shellQuote).join(" ");
 }
-function buildEntry(input) {
-  const manifest = input.manifest;
-  const peer = input.peer;
-  const hints = routeHints({
-    machineId: input.machineId,
-    localMachineId: input.localMachineId,
-    manifest,
-    peer
-  });
-  const selectedRoute = selectRouteHint(hints);
-  const route = selectedRoute?.kind === "ssh" ? "ssh" : selectedRoute?.kind ?? "unknown";
-  return {
-    machine_id: input.machineId,
-    hostname: manifest?.hostname ?? peer?.HostName ?? null,
-    platform: manifest?.platform ?? (peer?.OS ? normalizePlatform2(peer.OS) : null),
-    os: peer?.OS ?? null,
-    user: typeof manifest?.metadata?.user === "string" ? manifest.metadata.user : null,
-    workspace_path: manifest?.workspacePath ?? null,
-    manifest_declared: Boolean(manifest),
-    heartbeat_status: input.heartbeat?.status ?? "unknown",
-    last_heartbeat_at: input.heartbeat?.updated_at ?? null,
-    tailscale: {
-      dns_name: manifest?.tailscaleName ?? peer?.DNSName?.replace(/\.$/, "") ?? null,
-      ips: peer?.TailscaleIPs ?? [],
-      online: peer?.Online ?? null,
-      active: peer?.Active ?? null,
-      last_seen: peer?.LastSeen ?? null
-    },
-    ssh: {
-      address: manifest?.sshAddress ?? null,
-      route,
-      command_target: selectedRoute?.target ?? null
-    },
-    route_hints: hints,
-    tags: manifest?.tags ?? [],
-    metadata: manifest?.metadata ?? {}
-  };
+function canCheckPathForMachine(machine, localMachineId) {
+  if (!machine)
+    return false;
+  if (machine.machine_id === localMachineId)
+    return true;
+  return machine.route_hints.some((hint) => hint.kind === "local");
 }
-function discoverMachineTopology(options = {}) {
-  const now2 = options.now ?? new Date;
-  const runner = options.runner ?? defaultRunner;
-  const warnings = [];
-  const manifest = readManifest();
-  const heartbeats = listHeartbeats();
-  const heartbeatByMachine = new Map(heartbeats.map((heartbeat) => [heartbeat.machine_id, heartbeat]));
-  const localMachineId = getLocalMachineId();
-  const peers = options.includeTailscale === false ? new Map : loadTailscalePeers(runner, warnings);
-  const machineIds = new Set([
-    localMachineId,
-    ...manifest.machines.map((machine) => machine.id),
-    ...heartbeats.map((heartbeat) => heartbeat.machine_id),
-    ...peers.keys()
-  ]);
-  const manifestById = new Map(manifest.machines.map((machine) => [machine.id, machine]));
-  const machines = [...machineIds].sort().map((machineId) => {
-    const manifestMachine = manifestById.get(machineId);
-    return buildEntry({
-      machineId,
-      localMachineId,
-      manifest: manifestMachine,
-      peer: findTailscalePeer(manifestMachine ?? null, machineId, peers),
-      heartbeat: heartbeatByMachine.get(machineId)
-    });
-  });
+function checkedPathExists(path, check) {
+  if (!path || !check)
+    return null;
+  return existsSync5(path);
+}
+function repairHint(input) {
+  const command = [
+    "machines",
+    "workspace",
+    "repair",
+    "--machine",
+    input.machineId,
+    "--project",
+    input.projectId
+  ];
+  if (input.repoName)
+    command.push("--repo", input.repoName);
+  if (input.openFilesRepoName)
+    command.push("--open-files-repo", input.openFilesRepoName);
+  command.push("--json");
+  const applyCommand = [...command.slice(0, -1), "--apply", "--json"];
   return {
-    schema_version: MACHINES_CONSUMER_CONTRACT_VERSION,
-    package: {
-      name: MACHINES_PACKAGE_NAME,
-      version: getPackageVersion()
-    },
-    capabilities: getMachinesConsumerCapabilities(),
-    generated_at: now2.toISOString(),
-    local_machine_id: localMachineId,
-    local_hostname: hostname4(),
-    current_platform: normalizePlatform2(),
-    manifest_path_known: existsSync6(getManifestPath()),
-    machines,
-    warnings
+    id: `repair:${input.machineId}:${input.projectId}`,
+    reason: input.reason,
+    command,
+    shell_command: shellCommand(command),
+    apply_command: applyCommand,
+    apply_shell_command: shellCommand(applyCommand)
   };
 }
-function normalizeMachineAlias(value) {
-  return value.trim().replace(/\.$/, "").toLowerCase();
-}
-function routeTargetMatches(machine, requested) {
-  const normalized = normalizeMachineAlias(requested);
-  const values = [
-    machine.ssh.address,
-    machine.ssh.command_target,
-    machine.tailscale.dns_name,
-    machine.tailscale.dns_name?.split(".")[0],
-    ...machine.tailscale.ips,
-    ...machine.route_hints.map((hint) => hint.target),
-    ...machine.route_hints.map((hint) => hint.target.split("@").pop() ?? hint.target)
-  ].filter((value) => Boolean(value));
-  return values.some((value) => normalizeMachineAlias(value) === normalized);
-}
-function findRouteMachine(topology, requestedMachineId) {
-  const requested = normalizeMachineAlias(requestedMachineId);
-  if (requested === "local" || requested === "localhost" || requested === normalizeMachineAlias(hostname4()) || requested === normalizeMachineAlias(topology.local_machine_id)) {
+function pathDiagnostic(input) {
+  if (!input.path.path) {
     return {
-      machine: topology.machines.find((machine) => machine.machine_id === topology.local_machine_id) ?? null,
-      matchedBy: "local_alias"
+      id: input.id,
+      status: "missing",
+      severity: input.required ? "fail" : "warn",
+      message: `${input.label} is unresolved.`,
+      path: null,
+      source: input.path.source,
+      path_exists: null
     };
   }
-  const machineIdMatch = topology.machines.find((machine) => normalizeMachineAlias(machine.machine_id) === requested);
-  if (machineIdMatch)
-    return { machine: machineIdMatch, matchedBy: "machine_id" };
-  const hostnameMatch = topology.machines.find((machine) => machine.hostname && normalizeMachineAlias(machine.hostname) === requested);
-  if (hostnameMatch)
-    return { machine: hostnameMatch, matchedBy: "hostname" };
-  const tailscaleMatch = topology.machines.find((machine) => {
-    if (!machine.tailscale.dns_name)
-      return false;
-    const dns = normalizeMachineAlias(machine.tailscale.dns_name);
-    return dns === requested || dns.split(".")[0] === requested;
-  });
-  if (tailscaleMatch)
-    return { machine: tailscaleMatch, matchedBy: "tailscale" };
-  const routeMatch = topology.machines.find((machine) => routeTargetMatches(machine, requestedMachineId));
-  if (routeMatch)
-    return { machine: routeMatch, matchedBy: "route_target" };
-  return { machine: null, matchedBy: null };
-}
-function routeConfidence(input) {
-  if (input.matchedBy === "local_alias")
-    return "exact";
-  if (input.hint?.kind === "local")
-    return "exact";
-  if (input.hint?.reachable === true)
-    return "high";
-  if (input.machine.manifest_declared && (input.hint?.kind === "ssh" || input.hint?.kind === "lan"))
-    return "medium";
-  if (input.hint)
-    return "low";
-  return "none";
-}
-function addMilliseconds(date, milliseconds) {
-  return new Date(date.getTime() + milliseconds).toISOString();
-}
-function routeAuthority(input) {
-  if (!input.machine)
-    return "unresolved";
-  if (input.matchedBy === "fallback")
-    return "fallback";
-  if (input.selectedHint?.kind === "local")
-    return "live_topology";
-  if (input.selectedHint?.kind === "tailscale" || input.machine.tailscale.online !== null)
-    return "live_topology";
-  if (input.machine.manifest_declared)
-    return "manifest";
-  return "open-machines";
-}
-function workspaceAuthority(paths) {
-  const sources = [paths.workspace_root.source, paths.project_root.source, paths.open_files_root.source];
-  if (sources.some((source) => source === "argument"))
-    return "argument";
-  if (sources.some((source) => source === "manifest_metadata"))
-    return "manifest_metadata";
-  if (sources.some((source) => source === "manifest"))
-    return "manifest";
-  if (sources.some((source) => source === "inferred"))
-    return "inferred";
-  if (sources.every((source) => source === "unresolved"))
-    return "unresolved";
-  return "open-machines";
-}
-function cacheability(input) {
-  const ttlMs = input.ttlMs === undefined ? DEFAULT_MACHINE_RESOLVER_TTL_MS : input.ttlMs;
-  const expiresAt = typeof ttlMs === "number" && ttlMs > 0 ? addMilliseconds(input.observedAt, ttlMs) : null;
-  const stale = expiresAt ? input.now.getTime() > new Date(expiresAt).getTime() : false;
-  const confidenceCacheable = input.confidence !== "none" && input.confidence !== "low";
-  const cacheable = input.ok && confidenceCacheable && !stale && input.authority !== "unresolved";
-  const reasons = [...input.reasons];
-  if (!input.ok)
-    reasons.push("resolver_not_ok");
-  if (!confidenceCacheable)
-    reasons.push(`low_confidence:${input.confidence}`);
-  if (stale)
-    reasons.push("stale");
-  if (input.authority === "unresolved")
-    reasons.push("unresolved_authority");
-  return {
-    observed_at: input.observedAt.toISOString(),
-    verified_at: input.ok ? input.now.toISOString() : null,
-    expires_at: expiresAt,
-    ttl_ms: typeof ttlMs === "number" && ttlMs > 0 ? ttlMs : null,
-    source_authority: input.authority,
-    confidence: input.confidence,
-    cacheable,
-    stale,
-    reasons: [...new Set(reasons)].sort()
-  };
-}
-function resolveMachineRoute(machineId, options = {}) {
-  const now2 = options.now ?? new Date;
-  const topology = options.topology ?? discoverMachineTopology(options);
-  const warnings = [...topology.warnings];
-  const { machine, matchedBy } = findRouteMachine(topology, machineId);
-  const generatedAt = now2.toISOString();
-  if (!machine) {
-    warnings.push(`machine_not_found:${machineId}`);
+  if (input.pathExists === false) {
     return {
-      schema_version: MACHINES_CONSUMER_CONTRACT_VERSION,
-      package: { name: MACHINES_PACKAGE_NAME, version: getPackageVersion() },
-      ok: false,
-      machine_id: null,
-      requested_machine_id: machineId,
-      generated_at: generatedAt,
-      route: "unknown",
-      source: "unknown",
-      target: null,
-      command_target: null,
-      confidence: "none",
-      local: false,
-      evidence: {
-        topology: true,
-        matched_by: null,
-        manifest_declared: null,
-        heartbeat_status: null,
-        tailscale_online: null,
-        selected_hint: null
-      },
-      cacheability: cacheability({
-        ok: false,
-        observedAt: now2,
-        now: now2,
-        ttlMs: options.resolverTtlMs,
-        authority: "unresolved",
-        confidence: "none",
-        reasons: [`machine_not_found:${machineId}`]
-      }),
-      warnings
+      id: input.id,
+      status: "stale",
+      severity: "fail",
+      message: `${input.label} points to a path that does not exist on this machine.`,
+      path: input.path.path,
+      source: input.path.source,
+      path_exists: false
+    };
+  }
+  if (input.path.source === "inferred") {
+    return {
+      id: input.id,
+      status: "inferred",
+      severity: "warn",
+      message: `${input.label} was inferred from the workspace root; write an explicit manifest mapping for repeatable downstream sync.`,
+      path: input.path.path,
+      source: input.path.source,
+      path_exists: input.pathExists
     };
   }
-  const selectedHint = selectRouteHint(machine.route_hints);
-  const route = selectedHint?.kind ?? machine.ssh.route ?? "unknown";
-  const local = route === "local" || machine.machine_id === topology.local_machine_id;
-  const confidence = routeConfidence({ machine, hint: selectedHint, matchedBy });
-  const ok = Boolean(selectedHint?.target);
   return {
-    schema_version: MACHINES_CONSUMER_CONTRACT_VERSION,
-    package: topology.package,
-    ok,
-    machine_id: machine.machine_id,
-    requested_machine_id: machineId,
-    generated_at: generatedAt,
-    route,
-    source: route,
-    target: selectedHint?.target ?? null,
-    command_target: selectedHint?.target ?? null,
-    confidence,
-    local,
-    evidence: {
-      topology: true,
-      matched_by: matchedBy,
-      manifest_declared: machine.manifest_declared,
-      heartbeat_status: machine.heartbeat_status,
-      tailscale_online: machine.tailscale.online,
-      selected_hint: selectedHint
-    },
-    cacheability: cacheability({
-      ok,
-      observedAt: now2,
-      now: now2,
-      ttlMs: options.resolverTtlMs,
-      authority: routeAuthority({ machine, selectedHint, matchedBy }),
-      confidence,
-      reasons: selectedHint ? [] : ["route_target_unresolved"]
-    }),
-    warnings
+    id: input.id,
+    status: "ok",
+    severity: "ok",
+    message: `${input.label} is explicit enough for downstream sync.`,
+    path: input.path.path,
+    source: input.path.source,
+    path_exists: input.pathExists
   };
 }
-function isRecord(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-function metadataString(metadata, keys) {
-  for (const key of keys) {
-    const value = metadata[key];
-    if (typeof value === "string" && value.trim())
-      return value.trim();
-  }
-  return null;
-}
-function metadataBoolean(metadata, keys) {
-  for (const key of keys) {
-    const value = metadata[key];
-    if (typeof value === "boolean")
-      return value;
-  }
-  return null;
-}
-function metadataStringArray(metadata, keys) {
-  for (const key of keys) {
-    const value = metadata[key];
-    if (Array.isArray(value))
-      return value.filter((entry) => typeof entry === "string");
-  }
-  return [];
-}
-function readMappedPath(input) {
-  for (const containerName of input.containers) {
-    const container = input.metadata[containerName];
-    if (!isRecord(container))
-      continue;
-    for (const key of input.keys) {
-      const value = container[key];
-      if (typeof value === "string" && value.trim())
-        return value.trim();
-      if (isRecord(value)) {
-        const path = metadataString(value, ["path", "root", "workspacePath", "workspace_path"]);
-        if (path)
-          return path;
-      }
-    }
-  }
-  return null;
-}
-function trimTrailingSlash(value) {
-  return value.replace(/\/+$/, "");
-}
-function joinPath(left, right) {
-  return `${trimTrailingSlash(left)}/${right.replace(/^\/+/, "")}`;
-}
-function inferRepoRoot(workspaceRoot, repoName) {
-  if (!workspaceRoot || !repoName)
-    return null;
-  const root = trimTrailingSlash(workspaceRoot);
-  if (root.endsWith(`/${repoName}`) || root === repoName)
-    return root;
-  if (root.endsWith("/workspace") || root.endsWith("/Workspace")) {
-    return joinPath(root, `hasna/opensource/${repoName}`);
-  }
-  return joinPath(root, repoName);
-}
-function shellQuote(value) {
-  return `'${value.replace(/'/g, "'\\''")}'`;
-}
-function shellCommand(command) {
-  return command.map(shellQuote).join(" ");
-}
-function canCheckPathForMachine(machine, localMachineId) {
-  if (!machine)
-    return false;
-  if (machine.machine_id === localMachineId)
-    return true;
-  return machine.route_hints.some((hint) => hint.kind === "local");
-}
-function checkedPathExists(path, check) {
-  if (!path || !check)
-    return null;
-  return existsSync6(path);
-}
-function repairHint(input) {
-  const command = [
-    "machines",
-    "workspace",
-    "repair",
-    "--machine",
-    input.machineId,
-    "--project",
-    input.projectId
-  ];
-  if (input.repoName)
-    command.push("--repo", input.repoName);
-  if (input.openFilesRepoName)
-    command.push("--open-files-repo", input.openFilesRepoName);
-  command.push("--json");
-  const applyCommand = [...command.slice(0, -1), "--apply", "--json"];
-  return {
-    id: `repair:${input.machineId}:${input.projectId}`,
-    reason: input.reason,
-    command,
-    shell_command: shellCommand(command),
-    apply_command: applyCommand,
-    apply_shell_command: shellCommand(applyCommand)
-  };
-}
-function pathDiagnostic(input) {
-  if (!input.path.path) {
-    return {
-      id: input.id,
-      status: "missing",
-      severity: input.required ? "fail" : "warn",
-      message: `${input.label} is unresolved.`,
-      path: null,
-      source: input.path.source,
-      path_exists: null
-    };
-  }
-  if (input.pathExists === false) {
-    return {
-      id: input.id,
-      status: "stale",
-      severity: "fail",
-      message: `${input.label} points to a path that does not exist on this machine.`,
-      path: input.path.path,
-      source: input.path.source,
-      path_exists: false
-    };
-  }
-  if (input.path.source === "inferred") {
-    return {
-      id: input.id,
-      status: "inferred",
-      severity: "warn",
-      message: `${input.label} was inferred from the workspace root; write an explicit manifest mapping for repeatable downstream sync.`,
-      path: input.path.path,
-      source: input.path.source,
-      path_exists: input.pathExists
-    };
-  }
-  return {
-    id: input.id,
-    status: "ok",
-    severity: "ok",
-    message: `${input.label} is explicit enough for downstream sync.`,
-    path: input.path.path,
-    source: input.path.source,
-    path_exists: input.pathExists
-  };
-}
-function workspaceDiagnostics(input) {
-  const checkPaths = canCheckPathForMachine(input.machine, input.localMachineId);
-  const diagnostics = [];
-  if (!input.machine) {
-    diagnostics.push({
-      id: "manifest",
-      status: "missing_manifest",
-      severity: "fail",
-      message: "Machine is not present in topology or manifest.",
-      path: null,
-      source: "manifest",
-      path_exists: null
-    });
-  } else if (!input.resolution.evidence.manifest_declared) {
-    diagnostics.push({
-      id: "manifest",
-      status: "missing_manifest",
-      severity: "warn",
-      message: "Machine came from live topology but is not declared in the manifest.",
-      path: null,
-      source: "manifest",
-      path_exists: null
-    });
+function workspaceDiagnostics(input) {
+  const checkPaths = canCheckPathForMachine(input.machine, input.localMachineId);
+  const diagnostics = [];
+  if (!input.machine) {
+    diagnostics.push({
+      id: "manifest",
+      status: "missing_manifest",
+      severity: "fail",
+      message: "Machine is not present in topology or manifest.",
+      path: null,
+      source: "manifest",
+      path_exists: null
+    });
+  } else if (!input.resolution.evidence.manifest_declared) {
+    diagnostics.push({
+      id: "manifest",
+      status: "missing_manifest",
+      severity: "warn",
+      message: "Machine came from live topology but is not declared in the manifest.",
+      path: null,
+      source: "manifest",
+      path_exists: null
+    });
   }
   diagnostics.push(pathDiagnostic({
     id: "workspace_root",
@@ -9144,80 +8752,478 @@ function resolveMachineWorkspace(options) {
     }),
     warnings
   };
-  const diagnostics = workspaceDiagnostics({
-    machine,
-    localMachineId: topology.local_machine_id,
-    resolution,
-    openFilesRepoName
-  });
+  const diagnostics = workspaceDiagnostics({
+    machine,
+    localMachineId: topology.local_machine_id,
+    resolution,
+    openFilesRepoName
+  });
+  return {
+    ...resolution,
+    diagnostics: diagnostics.diagnostics,
+    repair_hints: diagnostics.repairHints
+  };
+}
+
+// src/commands/ssh.ts
+function shellQuote2(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function resolveSshTarget(machineId, options = {}) {
+  const resolved = resolveMachineRoute(machineId, options);
+  if (!resolved.ok || !resolved.target) {
+    throw new Error(`Machine route not found: ${machineId}`);
+  }
+  if (resolved.route !== "local" && resolved.route !== "lan" && resolved.route !== "tailscale" && resolved.route !== "ssh") {
+    throw new Error(`Machine route is not SSH-capable: ${machineId}`);
+  }
+  return {
+    machineId: resolved.machine_id ?? machineId,
+    target: resolved.target,
+    route: resolved.route,
+    confidence: resolved.confidence,
+    warnings: resolved.warnings
+  };
+}
+function buildSshCommand(machineId, remoteCommand, options = {}) {
+  const resolved = resolveSshTarget(machineId, options);
+  return remoteCommand ? `ssh ${resolved.target} ${shellQuote2(remoteCommand)}` : `ssh ${resolved.target}`;
+}
+
+// src/remote.ts
+function shellQuote3(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function machineIsLocal(machineId, localMachineId) {
+  return machineId === "local" || machineId === "localhost" || machineId === localMachineId || machineId === hostname4();
+}
+function resolveMachineCommand(machineId, command, localMachineId = getLocalMachineId()) {
+  if (machineIsLocal(machineId, localMachineId)) {
+    return { source: "local", shellCommand: command };
+  }
+  try {
+    return {
+      source: resolveSshTarget(machineId).route,
+      shellCommand: buildSshCommand(machineId, command)
+    };
+  } catch (error) {
+    const message = String(error.message ?? error);
+    if (message.includes("Machine route not found") || message.includes("Machine not found in manifest")) {
+      return { source: "ssh", shellCommand: `ssh ${shellQuote3(machineId)} ${shellQuote3(command)}` };
+    }
+    throw error;
+  }
+}
+function runMachineCommand(machineId, command) {
+  const resolved = resolveMachineCommand(machineId, command);
+  const result = spawnSync2("bash", ["-c", resolved.shellCommand], {
+    encoding: "utf8",
+    env: process.env
+  });
+  return {
+    machineId,
+    source: resolved.source,
+    stdout: result.stdout || "",
+    stderr: result.stderr || "",
+    exitCode: result.status ?? 1
+  };
+}
+function describeMachineCommandFailure(operation, result) {
+  const detail = (result.stderr || result.stdout || "").trim();
+  const suffix = detail ? `: ${detail}` : "";
+  return `${operation} failed on ${result.machineId} via ${result.source} (exit ${result.exitCode})${suffix}`;
+}
+function requireMachineCommandSuccess(operation, result) {
+  if (result.exitCode !== 0) {
+    throw new Error(describeMachineCommandFailure(operation, result));
+  }
+  return result;
+}
+
+// src/commands/setup.ts
+function quote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function buildBaseSteps(machine) {
+  const steps = [
+    {
+      id: "workspace",
+      title: "Ensure workspace directory exists",
+      command: `mkdir -p ${quote(machine.workspacePath)}`,
+      manager: "shell"
+    },
+    {
+      id: "bun",
+      title: "Install Bun if missing",
+      command: "command -v bun >/dev/null 2>&1 || curl -fsSL https://bun.sh/install | bash",
+      manager: "shell"
+    }
+  ];
+  if (machine.platform === "linux") {
+    steps.push({
+      id: "apt-base",
+      title: "Install core Linux tooling",
+      command: "sudo apt-get update && sudo apt-get install -y git curl unzip build-essential",
+      manager: "apt",
+      privileged: true
+    });
+  } else if (machine.platform === "macos") {
+    steps.push({
+      id: "brew-base",
+      title: "Install Homebrew if missing",
+      command: 'command -v brew >/dev/null 2>&1 || /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"',
+      manager: "brew"
+    });
+    steps.push({
+      id: "brew-core",
+      title: "Install core macOS tooling",
+      command: "brew install git coreutils",
+      manager: "brew"
+    });
+  }
+  return steps;
+}
+function buildPackageSteps(machine) {
+  return (machine.packages || []).map((pkg, index) => {
+    const manager = pkg.manager || (machine.platform === "macos" ? "brew" : "apt");
+    let command = pkg.name;
+    if (manager === "bun") {
+      command = `bun install -g ${quote(pkg.name)}`;
+    } else if (manager === "brew") {
+      command = `brew install ${quote(pkg.name)}`;
+    } else if (manager === "apt") {
+      command = `sudo apt-get install -y ${quote(pkg.name)}`;
+    }
+    return {
+      id: `package-${index + 1}`,
+      title: `Install package ${pkg.name}`,
+      command,
+      manager,
+      privileged: manager === "apt"
+    };
+  });
+}
+function buildSetupPlan(machineId) {
+  const manifest = readManifest();
+  const currentMachineId = getLocalMachineId();
+  const selected = machineId ? manifest.machines.find((machine) => machine.id === machineId) : manifest.machines.find((machine) => machine.id === currentMachineId);
+  const target = selected || {
+    id: currentMachineId,
+    platform: "linux",
+    workspacePath: `${homedir3()}/workspace`
+  };
+  const steps = [...buildBaseSteps(target), ...buildPackageSteps(target)];
+  return {
+    machineId: target.id,
+    mode: "plan",
+    steps,
+    executed: 0
+  };
+}
+function runSetup(machineId, options = {}, runner = runMachineCommand) {
+  const plan = buildSetupPlan(machineId);
+  if (!options.apply) {
+    return plan;
+  }
+  if (!options.yes) {
+    throw new Error("Setup execution requires --yes.");
+  }
+  let executed = 0;
+  for (const step of plan.steps) {
+    const result = runner(plan.machineId, step.command);
+    if (result.exitCode !== 0) {
+      recordSetupRun(plan.machineId, "failed", {
+        executed,
+        failedStep: step,
+        stderr: result.stderr,
+        stdout: result.stdout,
+        exitCode: result.exitCode,
+        source: result.source
+      });
+      throw new Error(describeMachineCommandFailure(`Setup step ${step.id}`, result));
+    }
+    executed += 1;
+  }
+  const summary = {
+    machineId: plan.machineId,
+    mode: "apply",
+    steps: plan.steps,
+    executed
+  };
+  recordSetupRun(plan.machineId, "completed", summary);
+  return summary;
+}
+
+// src/commands/backup.ts
+import { homedir as homedir4, hostname as hostname5 } from "os";
+import { join as join4 } from "path";
+var MACHINES_BACKUP_BUCKET_ENV = "HASNA_MACHINES_S3_BUCKET";
+var MACHINES_BACKUP_BUCKET_FALLBACK_ENV = "MACHINES_S3_BUCKET";
+var MACHINES_BACKUP_PREFIX_ENV = "HASNA_MACHINES_S3_PREFIX";
+var MACHINES_BACKUP_PREFIX_FALLBACK_ENV = "MACHINES_S3_PREFIX";
+var DEFAULT_BACKUP_PREFIX = "machines";
+function quote2(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function readEnv(name) {
+  const value = process.env[name]?.trim();
+  return value || undefined;
+}
+function readBackupBucketEnv() {
+  const primary = readEnv(MACHINES_BACKUP_BUCKET_ENV);
+  if (primary)
+    return { bucket: primary, bucketSource: MACHINES_BACKUP_BUCKET_ENV };
+  const fallback = readEnv(MACHINES_BACKUP_BUCKET_FALLBACK_ENV);
+  if (fallback)
+    return { bucket: fallback, bucketSource: MACHINES_BACKUP_BUCKET_FALLBACK_ENV };
+  return null;
+}
+function readBackupPrefixEnv() {
+  const primary = readEnv(MACHINES_BACKUP_PREFIX_ENV);
+  if (primary)
+    return { prefix: primary, prefixSource: MACHINES_BACKUP_PREFIX_ENV };
+  const fallback = readEnv(MACHINES_BACKUP_PREFIX_FALLBACK_ENV);
+  if (fallback)
+    return { prefix: fallback, prefixSource: MACHINES_BACKUP_PREFIX_FALLBACK_ENV };
+  return null;
+}
+function resolveBackupTarget(options = {}) {
+  const explicitBucket = options.bucket?.trim();
+  const envBucket = explicitBucket ? null : readBackupBucketEnv();
+  const bucket = explicitBucket || envBucket?.bucket;
+  if (!bucket) {
+    throw new Error(`Missing S3 backup bucket. Pass --bucket or set ${MACHINES_BACKUP_BUCKET_ENV} or ${MACHINES_BACKUP_BUCKET_FALLBACK_ENV}.`);
+  }
+  const explicitPrefix = options.prefix?.trim();
+  const envPrefix = explicitPrefix ? null : readBackupPrefixEnv();
+  return {
+    bucket,
+    prefix: explicitPrefix || envPrefix?.prefix || DEFAULT_BACKUP_PREFIX,
+    bucketSource: explicitBucket ? "argument" : envBucket.bucketSource,
+    prefixSource: explicitPrefix ? "argument" : envPrefix?.prefixSource || "default"
+  };
+}
+function defaultBackupSources() {
+  const home = homedir4();
+  return [
+    join4(home, ".hasna"),
+    join4(home, ".ssh"),
+    join4(home, ".secrets")
+  ];
+}
+function buildBackupPlan(bucket, prefix) {
+  const target = resolveBackupTarget({ bucket, prefix });
+  const archivePath = join4(homedir4(), ".hasna", "machines", "backup.tgz");
+  const sources = defaultBackupSources();
+  const steps = [
+    {
+      id: "backup-archive",
+      title: "Create compressed machine backup archive",
+      command: `tar -czf ${quote2(archivePath)} ${sources.map((source) => quote2(source)).join(" ")}`,
+      manager: "shell"
+    },
+    {
+      id: "backup-upload",
+      title: "Upload archive to S3",
+      command: `aws s3 cp ${quote2(archivePath)} ${quote2(`s3://${target.bucket}/${target.prefix}/${hostname5()}-backup.tgz`)}`,
+      manager: "custom"
+    }
+  ];
+  return {
+    machineId: process.env["HASNA_MACHINES_MACHINE_ID"] || "local",
+    mode: "plan",
+    steps,
+    executed: 0
+  };
+}
+function runBackup(bucket, prefix, options = {}) {
+  const plan = buildBackupPlan(bucket, prefix);
+  if (!options.apply)
+    return plan;
+  if (!options.yes) {
+    throw new Error("Backup execution requires --yes.");
+  }
+  let executed = 0;
+  for (const step of plan.steps) {
+    const result = Bun.spawnSync(["bash", "-lc", step.command], {
+      stdout: "pipe",
+      stderr: "pipe",
+      env: process.env
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(`Backup step failed (${step.id}): ${result.stderr.toString().trim()}`);
+    }
+    executed += 1;
+  }
   return {
-    ...resolution,
-    diagnostics: diagnostics.diagnostics,
-    repair_hints: diagnostics.repairHints
+    machineId: plan.machineId,
+    mode: "apply",
+    steps: plan.steps,
+    executed
   };
 }
 
-// src/commands/ssh.ts
-function shellQuote2(value) {
-  return `'${value.replace(/'/g, "'\\''")}'`;
+// src/commands/cert.ts
+import { homedir as homedir5, platform as platform3 } from "os";
+import { join as join5 } from "path";
+function quote3(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
 }
-function resolveSshTarget(machineId, options = {}) {
-  const resolved = resolveMachineRoute(machineId, options);
-  if (!resolved.ok || !resolved.target) {
-    throw new Error(`Machine route not found: ${machineId}`);
+function certDir() {
+  return join5(homedir5(), ".hasna", "machines", "certs");
+}
+function buildCertPlan(domains) {
+  if (domains.length === 0) {
+    throw new Error("At least one domain is required.");
   }
-  if (resolved.route !== "local" && resolved.route !== "lan" && resolved.route !== "tailscale" && resolved.route !== "ssh") {
-    throw new Error(`Machine route is not SSH-capable: ${machineId}`);
+  const primary = domains[0];
+  const certPath = join5(certDir(), `${primary}.pem`);
+  const keyPath = join5(certDir(), `${primary}-key.pem`);
+  const steps = [];
+  if (platform3() === "darwin") {
+    steps.push({
+      id: "mkcert-install-macos",
+      title: "Install mkcert on macOS",
+      command: "brew install mkcert nss",
+      manager: "brew"
+    });
+  } else {
+    steps.push({
+      id: "mkcert-install-linux",
+      title: "Install mkcert on Linux",
+      command: "sudo apt-get update && sudo apt-get install -y mkcert libnss3-tools",
+      manager: "apt",
+      privileged: true
+    });
   }
+  steps.push({
+    id: "mkcert-local-ca",
+    title: "Install local mkcert CA",
+    command: "mkcert -install",
+    manager: "custom"
+  }, {
+    id: "mkcert-issue",
+    title: `Issue certificate for ${domains.join(", ")}`,
+    command: `mkdir -p ${quote3(certDir())} && mkcert -cert-file ${quote3(certPath)} -key-file ${quote3(keyPath)} ${domains.map((domain) => quote3(domain)).join(" ")}`,
+    manager: "custom"
+  });
   return {
-    machineId: resolved.machine_id ?? machineId,
-    target: resolved.target,
-    route: resolved.route,
-    confidence: resolved.confidence,
-    warnings: resolved.warnings
+    machineId: process.env["HASNA_MACHINES_MACHINE_ID"] || "local",
+    mode: "plan",
+    steps,
+    executed: 0
   };
 }
-function buildSshCommand(machineId, remoteCommand, options = {}) {
-  const resolved = resolveSshTarget(machineId, options);
-  return remoteCommand ? `ssh ${resolved.target} ${shellQuote2(remoteCommand)}` : `ssh ${resolved.target}`;
+function runCertPlan(domains, options = {}) {
+  const plan = buildCertPlan(domains);
+  if (!options.apply)
+    return plan;
+  if (!options.yes) {
+    throw new Error("Certificate generation requires --yes.");
+  }
+  let executed = 0;
+  for (const step of plan.steps) {
+    const result = Bun.spawnSync(["bash", "-lc", step.command], {
+      stdout: "pipe",
+      stderr: "pipe",
+      env: process.env
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(`Certificate step failed (${step.id}): ${result.stderr.toString().trim()}`);
+    }
+    executed += 1;
+  }
+  return {
+    machineId: plan.machineId,
+    mode: "apply",
+    steps: plan.steps,
+    executed
+  };
 }
 
-// src/remote.ts
-function shellQuote3(value) {
-  return `'${value.replace(/'/g, "'\\''")}'`;
+// src/commands/dns.ts
+init_paths();
+import { existsSync as existsSync6, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { join as join6 } from "path";
+function getDnsPath() {
+  return join6(getDataDir(), "dns.json");
 }
-function machineIsLocal(machineId, localMachineId) {
-  return machineId === "local" || machineId === "localhost" || machineId === localMachineId || machineId === hostname5();
+function readMappings() {
+  const path = getDnsPath();
+  if (!existsSync6(path))
+    return [];
+  return JSON.parse(readFileSync3(path, "utf8"));
 }
-function resolveMachineCommand(machineId, command, localMachineId = getLocalMachineId()) {
-  if (machineIsLocal(machineId, localMachineId)) {
-    return { source: "local", shellCommand: command };
-  }
-  try {
-    return {
-      source: resolveSshTarget(machineId).route,
-      shellCommand: buildSshCommand(machineId, command)
-    };
-  } catch (error) {
-    const message = String(error.message ?? error);
-    if (message.includes("Machine route not found") || message.includes("Machine not found in manifest")) {
-      return { source: "ssh", shellCommand: `ssh ${shellQuote3(machineId)} ${shellQuote3(command)}` };
-    }
-    throw error;
+function writeMappings(mappings) {
+  const path = getDnsPath();
+  ensureParentDir(path);
+  writeFileSync2(path, `${JSON.stringify(mappings, null, 2)}
+`, "utf8");
+  return path;
+}
+function addDomainMapping(domain, port, targetHost = "127.0.0.1") {
+  const mappings = readMappings().filter((entry) => entry.domain !== domain);
+  mappings.push({ domain, port, targetHost });
+  writeMappings(mappings);
+  return mappings.sort((left, right) => left.domain.localeCompare(right.domain));
+}
+function listDomainMappings() {
+  return readMappings().sort((left, right) => left.domain.localeCompare(right.domain));
+}
+function renderDomainMapping(domain) {
+  const entry = readMappings().find((mapping) => mapping.domain === domain);
+  if (!entry) {
+    throw new Error(`Domain mapping not found: ${domain}`);
   }
+  return {
+    hostsEntry: `${entry.targetHost} ${entry.domain}`,
+    caddySnippet: `${entry.domain} {
+  reverse_proxy 127.0.0.1:${entry.port}
+  tls ${join6(getDataDir(), "certs", `${entry.domain}.pem`)} ${join6(getDataDir(), "certs", `${entry.domain}-key.pem`)}
+}`,
+    certPath: join6(getDataDir(), "certs", `${entry.domain}.pem`),
+    keyPath: join6(getDataDir(), "certs", `${entry.domain}-key.pem`)
+  };
 }
-function runMachineCommand(machineId, command) {
-  const resolved = resolveMachineCommand(machineId, command);
-  const result = spawnSync2("bash", ["-c", resolved.shellCommand], {
-    encoding: "utf8",
-    env: process.env
-  });
+
+// src/commands/diff.ts
+function packageNames(machine) {
+  return (machine.packages || []).map((pkg) => pkg.name).sort();
+}
+function fileTargets(machine) {
+  return (machine.files || []).map((file) => `${file.source}->${file.target}`).sort();
+}
+function diffMachines(leftMachineId, rightMachineId) {
+  const left = getManifestMachine(leftMachineId);
+  if (!left) {
+    throw new Error(`Machine not found in manifest: ${leftMachineId}`);
+  }
+  const right = rightMachineId ? getManifestMachine(rightMachineId) : detectCurrentMachineManifest();
+  if (!right) {
+    throw new Error(`Machine not found in manifest: ${rightMachineId}`);
+  }
+  const changedFields = [
+    left.platform !== right.platform ? "platform" : null,
+    left.connection !== right.connection ? "connection" : null,
+    left.workspacePath !== right.workspacePath ? "workspacePath" : null,
+    left.bunPath !== right.bunPath ? "bunPath" : null
+  ].filter(Boolean);
+  const leftPackages = new Set(packageNames(left));
+  const rightPackages = new Set(packageNames(right));
+  const leftFiles = new Set(fileTargets(left));
+  const rightFiles = new Set(fileTargets(right));
   return {
-    machineId,
-    source: resolved.source,
-    stdout: result.stdout || "",
-    stderr: result.stderr || "",
-    exitCode: result.status ?? 1
+    leftMachineId: left.id,
+    rightMachineId: right.id,
+    changedFields,
+    missingPackages: {
+      leftOnly: [...leftPackages].filter((pkg) => !rightPackages.has(pkg)),
+      rightOnly: [...rightPackages].filter((pkg) => !leftPackages.has(pkg))
+    },
+    missingFiles: {
+      leftOnly: [...leftFiles].filter((file) => !rightFiles.has(file)),
+      rightOnly: [...rightFiles].filter((file) => !leftFiles.has(file))
+    }
   };
 }
 
@@ -9313,27 +9319,28 @@ function buildAppsPlan(machineId) {
     executed: 0
   };
 }
-function getAppsStatus(machineId) {
+function getAppsStatus(machineId, runner = runMachineCommand) {
   const machine = resolveMachine(machineId);
+  const readiness = requireMachineCommandSuccess("Apps status readiness check", runner(machine.id, "true"));
   const apps = (machine.apps || []).map((app) => {
-    const probe = runMachineCommand(machine.id, buildAppProbeCommand(machine, app));
+    const probe = requireMachineCommandSuccess(`App probe ${app.name}`, runner(machine.id, buildAppProbeCommand(machine, app)));
     return parseProbeOutput(app, machine, probe.stdout);
   });
   return {
     machineId: machine.id,
-    source: apps.length > 0 ? runMachineCommand(machine.id, "true").source : machine.id === detectCurrentMachineManifest().id ? "local" : runMachineCommand(machine.id, "true").source,
+    source: readiness.source,
     apps
   };
 }
-function diffApps(machineId) {
-  const status = getAppsStatus(machineId);
+function diffApps(machineId, runner = runMachineCommand) {
+  const status = getAppsStatus(machineId, runner);
   return {
     ...status,
     missing: status.apps.filter((app) => !app.installed).map((app) => app.name),
     installed: status.apps.filter((app) => app.installed).map((app) => app.name)
   };
 }
-function runAppsInstall(machineId, options = {}) {
+function runAppsInstall(machineId, options = {}, runner = runMachineCommand) {
   const plan = buildAppsPlan(machineId);
   if (!options.apply)
     return plan;
@@ -9342,14 +9349,7 @@ function runAppsInstall(machineId, options = {}) {
   }
   let executed = 0;
   for (const step of plan.steps) {
-    const result = Bun.spawnSync(["bash", "-lc", step.command], {
-      stdout: "pipe",
-      stderr: "pipe",
-      env: process.env
-    });
-    if (result.exitCode !== 0) {
-      throw new Error(`App install failed (${step.id}): ${result.stderr.toString().trim()}`);
-    }
+    requireMachineCommandSuccess(`App install ${step.id}`, runner(plan.machineId, step.command));
     executed += 1;
   }
   return {
@@ -9420,25 +9420,28 @@ function buildClaudeInstallPlan(machineId, tools) {
     executed: 0
   };
 }
-function getClaudeCliStatus(machineId, tools) {
+function getClaudeCliStatus(machineId, tools, runner = runMachineCommand) {
   const machine = resolveMachine2(machineId);
   const normalizedTools = normalizeTools(tools);
-  const route = runMachineCommand(machine.id, "true").source;
+  const route = requireMachineCommandSuccess("AI CLI status readiness check", runner(machine.id, "true")).source;
   return {
     machineId: machine.id,
     source: route,
-    tools: normalizedTools.map((tool) => parseProbe(tool, runMachineCommand(machine.id, buildProbeCommand(tool)).stdout))
+    tools: normalizedTools.map((tool) => {
+      const result = requireMachineCommandSuccess(`AI CLI probe ${tool}`, runner(machine.id, buildProbeCommand(tool)));
+      return parseProbe(tool, result.stdout);
+    })
   };
 }
-function diffClaudeCli(machineId, tools) {
-  const status = getClaudeCliStatus(machineId, tools);
+function diffClaudeCli(machineId, tools, runner = runMachineCommand) {
+  const status = getClaudeCliStatus(machineId, tools, runner);
   return {
     ...status,
     missing: status.tools.filter((tool) => !tool.installed).map((tool) => tool.tool),
     installed: status.tools.filter((tool) => tool.installed).map((tool) => tool.tool)
   };
 }
-function runClaudeInstall(machineId, tools, options = {}) {
+function runClaudeInstall(machineId, tools, options = {}, runner = runMachineCommand) {
   const plan = buildClaudeInstallPlan(machineId, tools);
   if (!options.apply)
     return plan;
@@ -9447,14 +9450,7 @@ function runClaudeInstall(machineId, tools, options = {}) {
   }
   let executed = 0;
   for (const step of plan.steps) {
-    const result = Bun.spawnSync(["bash", "-lc", step.command], {
-      stdout: "pipe",
-      stderr: "pipe",
-      env: process.env
-    });
-    if (result.exitCode !== 0) {
-      throw new Error(`AI CLI install failed (${step.id}): ${result.stderr.toString().trim()}`);
-    }
+    requireMachineCommandSuccess(`AI CLI install ${step.id}`, runner(plan.machineId, step.command));
     executed += 1;
   }
   return {
@@ -9506,7 +9502,7 @@ function buildTailscaleInstallPlan(machineId) {
     executed: 0
   };
 }
-function runTailscaleInstall(machineId, options = {}) {
+function runTailscaleInstall(machineId, options = {}, runner = runMachineCommand) {
   const plan = buildTailscaleInstallPlan(machineId);
   if (!options.apply)
     return plan;
@@ -9515,14 +9511,7 @@ function runTailscaleInstall(machineId, options = {}) {
   }
   let executed = 0;
   for (const step of plan.steps) {
-    const result = Bun.spawnSync(["bash", "-lc", step.command], {
-      stdout: "pipe",
-      stderr: "pipe",
-      env: process.env
-    });
-    if (result.exitCode !== 0) {
-      throw new Error(`Tailscale install failed (${step.id}): ${result.stderr.toString().trim()}`);
-    }
+    requireMachineCommandSuccess(`Tailscale install ${step.id}`, runner(plan.machineId, step.command));
     executed += 1;
   }
   return {
@@ -10563,16 +10552,17 @@ function quote4(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function packageCheckCommand(machine, packageName, manager = machine.platform === "macos" ? "brew" : "apt") {
+  const quotedPackageName = quote4(packageName);
   if (manager === "bun") {
-    return `bun pm ls -g --all | grep -F ${quote4(packageName)}`;
+    return `if bun pm ls -g --all 2>/dev/null | grep -F ${quotedPackageName} >/dev/null 2>&1; then printf 'installed=1\\n'; else printf 'installed=0\\n'; fi`;
   }
   if (manager === "brew") {
-    return `brew list --versions ${quote4(packageName)}`;
+    return `if brew list --versions ${quotedPackageName} >/dev/null 2>&1; then printf 'installed=1\\n'; else printf 'installed=0\\n'; fi`;
   }
   if (manager === "apt") {
-    return `dpkg -s ${quote4(packageName)} >/dev/null 2>&1`;
+    return `if dpkg -s ${quotedPackageName} >/dev/null 2>&1; then printf 'installed=1\\n'; else printf 'installed=0\\n'; fi`;
   }
-  return `command -v ${quote4(packageName)} >/dev/null 2>&1`;
+  return `if command -v ${quotedPackageName} >/dev/null 2>&1; then printf 'installed=1\\n'; else printf 'installed=0\\n'; fi`;
 }
 function packageInstallCommand(machine, packageName, manager = machine.platform === "macos" ? "brew" : "apt") {
   if (manager === "bun") {
@@ -10586,15 +10576,15 @@ function packageInstallCommand(machine, packageName, manager = machine.platform
   }
   return packageName;
 }
-function detectPackageActions(machine) {
+function detectPackageActions(machine, runner) {
   return (machine.packages || []).map((pkg, index) => {
     const manager = pkg.manager || (machine.platform === "macos" ? "brew" : "apt");
-    const check = Bun.spawnSync(["bash", "-lc", packageCheckCommand(machine, pkg.name, manager)], {
-      stdout: "ignore",
-      stderr: "ignore",
-      env: process.env
-    });
-    const installed = check.exitCode === 0;
+    const check = runner(machine.id, packageCheckCommand(machine, pkg.name, manager));
+    if (check.exitCode !== 0) {
+      throw new Error(describeMachineCommandFailure(`Sync package probe ${pkg.name}`, check));
+    }
+    const installed = check.stdout.split(`
+`).some((line) => line.trim() === "installed=1");
     return {
       id: `package-${index + 1}`,
       title: `${installed ? "Package present" : "Install package"} ${pkg.name}`,
@@ -10605,6 +10595,9 @@ function detectPackageActions(machine) {
   });
 }
 function detectFileActions(machine) {
+  if ((machine.files || []).length > 0 && resolveMachineCommand(machine.id, "true").source !== "local") {
+    throw new Error(`Remote file sync planning is not supported for ${machine.id}; refusing to inspect or apply local paths as remote state.`);
+  }
   return (machine.files || []).map((file, index) => {
     const sourceExists = existsSync9(file.source);
     const targetExists = existsSync9(file.target);
@@ -10628,7 +10621,7 @@ function detectFileActions(machine) {
     };
   });
 }
-function buildSyncPlan(machineId) {
+function buildSyncPlan(machineId, runner = runMachineCommand) {
   const manifest = readManifest();
   const currentMachineId = getLocalMachineId();
   const selected = machineId ? manifest.machines.find((machine) => machine.id === machineId) : manifest.machines.find((machine) => machine.id === currentMachineId);
@@ -10638,7 +10631,7 @@ function buildSyncPlan(machineId) {
     workspacePath: `${homedir7()}/workspace`
   };
   const actions = [
-    ...detectPackageActions(target),
+    ...detectPackageActions(target, runner),
     ...detectFileActions(target)
   ];
   return {
@@ -10668,8 +10661,8 @@ function applyFileAction(command) {
     symlinkSync(sourcePath, targetPath);
   }
 }
-function runSync(machineId, options = {}) {
-  const plan = buildSyncPlan(machineId);
+function runSync(machineId, options = {}, runner = runMachineCommand) {
+  const plan = buildSyncPlan(machineId, runner);
   if (!options.apply) {
     return plan;
   }
@@ -10683,18 +10676,17 @@ function runSync(machineId, options = {}) {
     if (action.kind === "file") {
       applyFileAction(action.command);
     } else {
-      const result = Bun.spawnSync(["bash", "-lc", action.command], {
-        stdout: "pipe",
-        stderr: "pipe",
-        env: process.env
-      });
+      const result = runner(plan.machineId, action.command);
       if (result.exitCode !== 0) {
         recordSyncRun(plan.machineId, "failed", {
           executed,
           failedAction: action,
-          stderr: result.stderr.toString()
+          stderr: result.stderr,
+          stdout: result.stdout,
+          exitCode: result.exitCode,
+          source: result.source
         });
-        throw new Error(`Sync action failed (${action.id}): ${result.stderr.toString().trim()}`);
+        throw new Error(describeMachineCommandFailure(`Sync action ${action.id}`, result));
       }
     }
     executed += 1;