@openscout/scout 0.2.72 → 0.2.73

package/dist/runtime/broker-process-manager.mjs

@@ -1,12 +1,13 @@
 // @bun
 // packages/runtime/src/broker-process-manager.ts
-import { spawnSync } from "child_process";
-import { chmodSync, existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
-import { homedir as homedir3 } from "os";
-import { dirname as dirname2, join as join3, resolve as resolve2 } from "path";
+import { spawn as spawn2, spawnSync } from "child_process";
+import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
+import { homedir as homedir5 } from "os";
+import { dirname as dirname3, join as join5, resolve as resolve2 } from "path";
 import { fileURLToPath } from "url";
 
 // packages/runtime/src/broker-api.ts
+import { existsSync } from "fs";
 import { request as httpRequest } from "http";
 var DEFAULT_BROKER_JSON_REQUEST_TIMEOUT_MS = 30000;
 function normalizeBaseUrl(baseUrl) {
@@ -55,13 +56,17 @@ async function requestBrokerOverHttp(baseUrl, path, options) {
 }
 function shouldFallbackFromUnixSocket(error) {
   const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
-  return code === "ENOENT" || code === "ECONNREFUSED" || code === "ENOTSOCK" || code === "EACCES" || code === "FailedToOpenSocket";
+  return code === "ENOENT" || code === "ECONNREFUSED" || code === "ENOTSOCK" || code === "EACCES" || code === "EINVAL" || code === "FailedToOpenSocket";
 }
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
 function requestBrokerOverUnixSocket(socketPath, baseUrl, path, options) {
   return new Promise((resolve, reject) => {
+    if (!existsSync(socketPath)) {
+      reject(Object.assign(new Error(`Scout broker socket does not exist: ${socketPath}`), { code: "ENOENT" }));
+      return;
+    }
     const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
     const url = new URL(path, normalizedBaseUrl);
     const body = requestBody(options);
@@ -142,100 +147,1585 @@ async function requestBrokerWire(baseUrl, path, options) {
     }
   }
   return {
-    response: await requestBrokerOverHttp(baseUrl, path, requestOptions),
-    trace: {
-      transport: "http"
-    }
+    response: await requestBrokerOverHttp(baseUrl, path, requestOptions),
+    trace: {
+      transport: "http"
+    }
+  };
+}
+async function requestScoutBrokerJsonWithTrace(baseUrl, path, options = {}) {
+  const { response, trace } = await requestBrokerWire(baseUrl, path, options);
+  let parsed;
+  let parsedJson = false;
+  if (response.text.length > 0) {
+    try {
+      parsed = JSON.parse(response.text);
+      parsedJson = true;
+    } catch {
+      parsedJson = false;
+    }
+  }
+  if (!response.ok) {
+    if (parsedJson && options.acceptErrorJson?.(parsed)) {
+      return { value: parsed, trace };
+    }
+    throw new Error(`${path} returned ${response.status}: ${response.text}`);
+  }
+  if (parsedJson) {
+    return { value: parsed, trace };
+  }
+  return { value: undefined, trace };
+}
+
+// packages/runtime/src/support-paths.ts
+import { homedir } from "os";
+import { join } from "path";
+var OPENSCOUT_RPC_CUTOVER_MARKER = "rpc-runtime-cutover-v1";
+function resolveOpenScoutSupportPaths() {
+  const home = homedir();
+  const supportDirectory = process.env.OPENSCOUT_SUPPORT_DIRECTORY ?? join(home, "Library", "Application Support", "OpenScout");
+  const logsDirectory = join(supportDirectory, "logs");
+  const runtimeDirectory = join(supportDirectory, "runtime");
+  const catalogDirectory = join(supportDirectory, "catalog");
+  const controlHome = process.env.OPENSCOUT_CONTROL_HOME ?? join(home, ".openscout", "control-plane");
+  const knowledgeDirectory = join(controlHome, "knowledge");
+  return {
+    supportDirectory,
+    logsDirectory,
+    appLogsDirectory: join(logsDirectory, "app"),
+    brokerLogsDirectory: join(logsDirectory, "broker"),
+    runtimeDirectory,
+    catalogDirectory,
+    relayAgentsDirectory: join(runtimeDirectory, "agents"),
+    settingsPath: join(supportDirectory, "settings.json"),
+    harnessCatalogPath: join(catalogDirectory, "harness-catalog.json"),
+    relayAgentsRegistryPath: join(supportDirectory, "relay-agents.json"),
+    managedInstallsPath: join(supportDirectory, "managed-installs.json"),
+    hostInfoPath: join(supportDirectory, ".host-info"),
+    relayHubDirectory: process.env.OPENSCOUT_RELAY_HUB ?? join(home, ".openscout", "relay"),
+    controlHome,
+    knowledgeDirectory,
+    knowledgeQmdDirectory: join(knowledgeDirectory, "qmd"),
+    knowledgeSqlitePath: join(knowledgeDirectory, "knowledge.sqlite"),
+    desktopStatusPath: join(supportDirectory, "agent-status.json"),
+    workspaceStatePath: join(supportDirectory, "workspace-state.json"),
+    cutoverMarkerPath: join(supportDirectory, OPENSCOUT_RPC_CUTOVER_MARKER)
+  };
+}
+
+// packages/runtime/src/open-scout-network.ts
+import { readFileSync } from "fs";
+var DEFAULT_OPENSCOUT_NETWORK_RENDEZVOUS_URL = "https://mesh.oscout.net";
+var DEFAULT_OPENSCOUT_NETWORK_PAIRING_RELAY_URL = "wss://mesh.oscout.net/v1/relay";
+function defaultOpenScoutNetworkSettings() {
+  return {
+    discoveryEnabled: false,
+    rendezvousUrl: DEFAULT_OPENSCOUT_NETWORK_RENDEZVOUS_URL,
+    pairingRelayUrl: DEFAULT_OPENSCOUT_NETWORK_PAIRING_RELAY_URL,
+    keepPairingRelayRunning: true
+  };
+}
+function normalizeOpenScoutNetworkSettings(input) {
+  const base = defaultOpenScoutNetworkSettings();
+  const record = isRecord(input) ? input : {};
+  return {
+    discoveryEnabled: typeof record.discoveryEnabled === "boolean" ? record.discoveryEnabled : base.discoveryEnabled,
+    rendezvousUrl: normalizeUrlString(record.rendezvousUrl, base.rendezvousUrl),
+    pairingRelayUrl: normalizeUrlString(record.pairingRelayUrl, base.pairingRelayUrl),
+    keepPairingRelayRunning: typeof record.keepPairingRelayRunning === "boolean" ? record.keepPairingRelayRunning : base.keepPairingRelayRunning
+  };
+}
+function readOpenScoutNetworkSettingsSync() {
+  try {
+    const raw = readFileSync(resolveOpenScoutSupportPaths().settingsPath, "utf8");
+    const parsed = JSON.parse(raw);
+    const network = isRecord(parsed) && isRecord(parsed.network) ? parsed.network : {};
+    return normalizeOpenScoutNetworkSettings(isRecord(network.openScoutNetwork) ? network.openScoutNetwork : {});
+  } catch {
+    return defaultOpenScoutNetworkSettings();
+  }
+}
+function openScoutNetworkDiscoveryEnabled(env = process.env) {
+  const explicit = readBooleanEnv(env.OPENSCOUT_NETWORK_DISCOVERY_ENABLED) ?? readBooleanEnv(env.OPENSCOUT_OSN_DISCOVERY_ENABLED);
+  if (explicit !== undefined) {
+    return explicit;
+  }
+  return readOpenScoutNetworkSettingsSync().discoveryEnabled;
+}
+function normalizeUrlString(value, fallback) {
+  if (typeof value !== "string") {
+    return fallback;
+  }
+  const trimmed = value.trim().replace(/\/$/, "");
+  return trimmed || fallback;
+}
+function readBooleanEnv(value) {
+  const normalized = value?.trim().toLowerCase();
+  if (!normalized)
+    return;
+  if (["1", "true", "yes", "on"].includes(normalized))
+    return true;
+  if (["0", "false", "no", "off"].includes(normalized))
+    return false;
+  return;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// packages/runtime/src/tailscale.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { execFileSync } from "child_process";
+
+// packages/runtime/src/system-probes/tailscale-status.ts
+import { readFile } from "fs/promises";
+
+// packages/runtime/src/system-probes/registry.ts
+var DEFAULT_MIN_MAX_STALE_MS = 2 * 60000;
+var PROBE_RUN_OUTPUT = Symbol("openscout.probeRunOutput");
+var registeredProbes = [];
+
+class ProbeBackendError extends Error {
+  backend;
+  fallbackSince;
+  fallbackReason;
+  code;
+  timedOut;
+  constructor(message, metadata, cause) {
+    super(message);
+    this.name = "ProbeBackendError";
+    this.backend = metadata.backend;
+    this.fallbackSince = metadata.fallbackSince;
+    this.fallbackReason = metadata.fallbackReason;
+    const details = probeErrorDetails(cause);
+    if (details.code) {
+      this.code = details.code;
+    }
+    if (details.timedOut !== undefined) {
+      this.timedOut = details.timedOut;
+    }
+  }
+}
+function probeRunOutput(value, metadata) {
+  return {
+    [PROBE_RUN_OUTPUT]: true,
+    value,
+    ...metadata
+  };
+}
+function isProbeRunOutput(value) {
+  return typeof value === "object" && value !== null && value[PROBE_RUN_OUTPUT] === true;
+}
+function backendMetadataFromError(error) {
+  if (error instanceof ProbeBackendError) {
+    return {
+      backend: error.backend,
+      fallbackSince: error.fallbackSince,
+      fallbackReason: error.fallbackReason
+    };
+  }
+  if (typeof error === "object" && error !== null) {
+    const record = error;
+    if (record.backend === "local" || record.backend === "scoutd" || record.backend === "local-fallback") {
+      return {
+        backend: record.backend,
+        fallbackSince: typeof record.fallbackSince === "number" ? record.fallbackSince : undefined,
+        fallbackReason: typeof record.fallbackReason === "string" ? record.fallbackReason : undefined
+      };
+    }
+  }
+  return null;
+}
+function probeErrorDetails(error) {
+  if (typeof error !== "object" || error === null) {
+    return {};
+  }
+  const record = error;
+  const code = typeof record.code === "string" && record.code.trim() ? record.code.trim() : undefined;
+  const timedOut = record.timedOut === true || code === "timeout" ? true : record.timedOut === false ? false : undefined;
+  return { code, timedOut };
+}
+function assertProbeSpec(spec) {
+  if (!spec.id.trim()) {
+    throw new Error("Probe id is required");
+  }
+  if (!Number.isFinite(spec.ttlMs) || spec.ttlMs <= 0) {
+    throw new Error(`Probe ${spec.id} must declare a positive ttlMs`);
+  }
+  if (!Number.isFinite(spec.timeoutMs) || spec.timeoutMs <= 0) {
+    throw new Error(`Probe ${spec.id} must declare a positive timeoutMs`);
+  }
+  if (spec.maxStaleMs !== undefined && (!Number.isFinite(spec.maxStaleMs) || spec.maxStaleMs <= 0)) {
+    throw new Error(`Probe ${spec.id} maxStaleMs must be positive when set`);
+  }
+}
+function maxStaleMsFor(spec) {
+  return spec.maxStaleMs ?? Math.max(DEFAULT_MIN_MAX_STALE_MS, spec.ttlMs * 10);
+}
+function failureBackoffMs(consecutiveFailures) {
+  if (consecutiveFailures <= 0) {
+    return 0;
+  }
+  return Math.min(30000, 1000 * 2 ** Math.min(consecutiveFailures - 1, 5));
+}
+function probeErrorFromUnknown(error, at, timedOut = false) {
+  if (typeof error === "object" && error !== null) {
+    const record = error;
+    const code = typeof record.code === "string" && record.code.trim() ? record.code.trim() : timedOut ? "timeout" : typeof record.name === "string" && record.name.trim() ? record.name.trim() : "error";
+    const message = typeof record.message === "string" && record.message.trim() ? record.message : String(error);
+    return { code, message, at, ...timedOut ? { timedOut: true } : {} };
+  }
+  return {
+    code: timedOut ? "timeout" : "error",
+    message: String(error),
+    at,
+    ...timedOut ? { timedOut: true } : {}
+  };
+}
+function timeoutError(probeId, timeoutMs) {
+  return {
+    code: "timeout",
+    message: `Probe ${probeId} timed out after ${timeoutMs}ms`,
+    at: Date.now(),
+    timedOut: true
+  };
+}
+function staleTooLongError(probeId, ageMs, maxStaleMs) {
+  return {
+    code: "max_stale_exceeded",
+    message: `Probe ${probeId} last good snapshot is ${ageMs}ms old, exceeding maxStaleMs ${maxStaleMs}`,
+    at: Date.now()
+  };
+}
+function isFreshEnough(state, maxAgeMs) {
+  if (state.at === null || state.invalidated) {
+    return false;
+  }
+  return Date.now() - state.at <= maxAgeMs;
+}
+function logBackendTransition(input) {
+  if (input.from === input.to) {
+    return;
+  }
+  const keySuffix = input.key === undefined ? "" : ` key=${JSON.stringify(input.key)}`;
+  const reasonSuffix = input.reason ? ` (${input.reason})` : "";
+  console.warn(`[openscout] system probe ${input.id}${keySuffix} backend ${input.from} -> ${input.to}${reasonSuffix}`);
+}
+
+class ProbeInstance {
+  spec;
+  key;
+  runProbe;
+  scheduleRun;
+  state = {
+    value: null,
+    at: null,
+    error: null,
+    consecutiveFailures: 0,
+    inFlight: null,
+    invalidated: false,
+    invalidationReason: null,
+    invalidationSerial: 0,
+    nextRetryAt: 0,
+    backend: "local",
+    fallbackSince: null,
+    fallbackReason: null
+  };
+  metricState;
+  lastAccessAt = Date.now();
+  constructor(options) {
+    this.spec = options.spec;
+    this.key = options.key;
+    this.runProbe = options.run;
+    this.scheduleRun = options.scheduleRun ?? ((task) => task());
+    this.metricState = {
+      id: options.spec.id,
+      ...options.key !== undefined ? { key: options.key } : {},
+      backend: "local",
+      runCount: 0,
+      failureCount: 0,
+      timeoutCount: 0,
+      staleServedCount: 0,
+      lastRunAt: null,
+      lastDurationMs: null,
+      lastSuccessAt: null
+    };
+  }
+  read() {
+    this.touch();
+    if (this.shouldRefreshForRead(Date.now())) {
+      this.ensureRefresh(false, this.spec.ttlMs);
+    }
+    const snap = this.snapshot();
+    if (snap.status === "stale" || snap.status === "failed" && snap.at !== null) {
+      this.metricState.staleServedCount += 1;
+    }
+    return snap;
+  }
+  async fresh(options = {}) {
+    this.touch();
+    const maxAgeMs = options.maxAgeMs ?? this.spec.ttlMs;
+    for (let attempt = 0;attempt < 3; attempt += 1) {
+      if (isFreshEnough(this.state, maxAgeMs)) {
+        return this.snapshot();
+      }
+      await this.ensureRefresh(true, maxAgeMs);
+      if (!this.state.invalidated) {
+        return this.snapshot();
+      }
+    }
+    return this.snapshot();
+  }
+  snapshot() {
+    const now = Date.now();
+    const ageMs = this.state.at === null ? null : Math.max(0, now - this.state.at);
+    const maxStaleMs = maxStaleMsFor(this.spec);
+    const exceededMaxStale = ageMs !== null && ageMs > maxStaleMs;
+    const fresh = ageMs !== null && !this.state.invalidated && ageMs <= this.spec.ttlMs;
+    const status = this.state.at === null ? this.state.error ? "failed" : "empty" : exceededMaxStale ? "failed" : fresh ? "fresh" : "stale";
+    const error = exceededMaxStale ? this.state.error ?? staleTooLongError(this.spec.id, ageMs ?? 0, maxStaleMs) : this.state.error;
+    return {
+      id: this.spec.id,
+      ...this.key !== undefined ? { key: this.key } : {},
+      value: status === "failed" && exceededMaxStale ? null : this.state.value,
+      at: this.state.at,
+      ageMs,
+      stale: status === "stale" || status === "failed" && this.state.at !== null,
+      refreshing: this.state.inFlight !== null,
+      status,
+      error,
+      consecutiveFailures: this.state.consecutiveFailures,
+      backend: this.state.backend,
+      ...this.state.fallbackSince !== null ? { fallbackSince: this.state.fallbackSince } : {},
+      ...this.state.fallbackReason !== null ? { fallbackReason: this.state.fallbackReason } : {}
+    };
+  }
+  invalidate(reason) {
+    this.touch();
+    this.state.invalidated = true;
+    this.state.invalidationReason = reason ?? null;
+    this.state.invalidationSerial += 1;
+    this.state.nextRetryAt = 0;
+  }
+  metrics() {
+    return {
+      ...this.metricState,
+      consecutiveFailures: this.state.consecutiveFailures,
+      inFlight: this.state.inFlight !== null,
+      ...this.state.fallbackSince !== null ? { fallbackSince: this.state.fallbackSince } : {},
+      ...this.state.fallbackReason !== null ? { fallbackReason: this.state.fallbackReason } : {}
+    };
+  }
+  isRefreshing() {
+    return this.state.inFlight !== null;
+  }
+  touch() {
+    this.lastAccessAt = Date.now();
+  }
+  shouldRefreshForRead(now) {
+    if (this.state.inFlight !== null) {
+      return false;
+    }
+    if (this.state.nextRetryAt > now) {
+      return false;
+    }
+    if (this.state.at === null) {
+      return true;
+    }
+    if (this.state.invalidated) {
+      return true;
+    }
+    return now - this.state.at > this.spec.ttlMs;
+  }
+  ensureRefresh(force, maxAgeMs) {
+    if (this.state.inFlight) {
+      return this.state.inFlight;
+    }
+    const now = Date.now();
+    if (!force && this.state.nextRetryAt > now) {
+      return Promise.resolve();
+    }
+    const inFlight = this.scheduleRun(() => this.executeRun(maxAgeMs)).finally(() => {
+      if (this.state.inFlight === inFlight) {
+        this.state.inFlight = null;
+      }
+    });
+    this.state.inFlight = inFlight;
+    return inFlight;
+  }
+  async executeRun(maxAgeMs) {
+    const startedAt = Date.now();
+    const previousBackend = this.state.backend;
+    const invalidationSerialAtStart = this.state.invalidationSerial;
+    const controller = new AbortController;
+    let timeout = null;
+    this.metricState.runCount += 1;
+    this.metricState.lastRunAt = startedAt;
+    const ctx = {
+      probeId: this.spec.id,
+      ...this.key !== undefined ? { key: this.key } : {},
+      signal: controller.signal,
+      timeoutMs: this.spec.timeoutMs,
+      maxAgeMs,
+      startedAt
+    };
+    const timeoutProbeError = timeoutError(this.spec.id, this.spec.timeoutMs);
+    const runPromise = this.runProbe(ctx);
+    runPromise.catch(() => {
+      return;
+    });
+    try {
+      const result = await new Promise((resolve, reject) => {
+        timeout = setTimeout(() => {
+          controller.abort(timeoutProbeError);
+          reject(timeoutProbeError);
+        }, this.spec.timeoutMs);
+        runPromise.then(resolve, reject);
+      });
+      const output = isProbeRunOutput(result) ? result : probeRunOutput(result, { backend: "local" });
+      this.state.value = output.value;
+      this.state.at = output.generatedAt ?? Date.now();
+      this.state.error = null;
+      this.state.consecutiveFailures = 0;
+      if (this.state.invalidationSerial === invalidationSerialAtStart) {
+        this.state.invalidated = false;
+        this.state.invalidationReason = null;
+      }
+      this.state.nextRetryAt = 0;
+      this.state.backend = output.backend;
+      this.state.fallbackSince = output.fallbackSince ?? null;
+      this.state.fallbackReason = output.fallbackReason ?? null;
+      this.metricState.backend = output.backend;
+      this.metricState.lastSuccessAt = this.state.at;
+      logBackendTransition({
+        id: this.spec.id,
+        key: this.key,
+        from: previousBackend,
+        to: output.backend,
+        reason: output.fallbackReason
+      });
+    } catch (error) {
+      const timedOut = error === timeoutProbeError || typeof error === "object" && error !== null && (error.code === "timeout" || error.timedOut === true);
+      const at = Date.now();
+      this.state.error = error === timeoutProbeError ? timeoutProbeError : probeErrorFromUnknown(error, at, timedOut);
+      this.state.consecutiveFailures += 1;
+      this.state.nextRetryAt = at + failureBackoffMs(this.state.consecutiveFailures);
+      const backendMetadata = backendMetadataFromError(error);
+      if (backendMetadata) {
+        this.state.backend = backendMetadata.backend;
+        this.state.fallbackSince = backendMetadata.fallbackSince ?? null;
+        this.state.fallbackReason = backendMetadata.fallbackReason ?? null;
+        this.metricState.backend = backendMetadata.backend;
+        logBackendTransition({
+          id: this.spec.id,
+          key: this.key,
+          from: previousBackend,
+          to: backendMetadata.backend,
+          reason: backendMetadata.fallbackReason
+        });
+      }
+      this.metricState.failureCount += 1;
+      if (this.state.error.timedOut || this.state.error.code === "timeout") {
+        this.metricState.timeoutCount += 1;
+      }
+    } finally {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+      this.metricState.lastDurationMs = Date.now() - startedAt;
+    }
+  }
+}
+
+class FamilyLimiter {
+  maxConcurrent;
+  active = 0;
+  queue = [];
+  constructor(maxConcurrent) {
+    this.maxConcurrent = maxConcurrent;
+  }
+  queued() {
+    return this.queue.length;
+  }
+  async run(task) {
+    if (this.active >= this.maxConcurrent) {
+      await new Promise((resolve) => this.queue.push(resolve));
+    }
+    this.active += 1;
+    try {
+      return await task();
+    } finally {
+      this.active -= 1;
+      const next = this.queue.shift();
+      if (next) {
+        next();
+      }
+    }
+  }
+}
+
+class ProbeFamily {
+  spec;
+  entries = new Map;
+  limiter;
+  constructor(spec) {
+    this.spec = spec;
+    assertProbeSpec(spec);
+    if (!Number.isInteger(spec.maxKeys) || spec.maxKeys <= 0) {
+      throw new Error(`Probe family ${spec.id} must declare a positive maxKeys`);
+    }
+    if (!Number.isFinite(spec.idleKeyTtlMs) || spec.idleKeyTtlMs <= 0) {
+      throw new Error(`Probe family ${spec.id} must declare a positive idleKeyTtlMs`);
+    }
+    if (!Number.isInteger(spec.maxConcurrentKeys) || spec.maxConcurrentKeys <= 0) {
+      throw new Error(`Probe family ${spec.id} must declare a positive maxConcurrentKeys`);
+    }
+    this.limiter = new FamilyLimiter(spec.maxConcurrentKeys);
+  }
+  for(rawKey) {
+    const key = this.normalize(rawKey);
+    this.cleanupIdle(Date.now());
+    let entry = this.entries.get(key);
+    if (!entry) {
+      entry = new ProbeInstance({
+        spec: this.spec,
+        key,
+        run: (ctx) => this.spec.run(key, ctx),
+        scheduleRun: (task) => this.limiter.run(task)
+      });
+      this.entries.set(key, entry);
+    }
+    entry.lastAccessAt = Date.now();
+    this.evictLruIfNeeded();
+    return entry;
+  }
+  snapshot(key) {
+    return this.for(key).snapshot();
+  }
+  invalidate(key, reason) {
+    this.for(key).invalidate(reason);
+  }
+  metrics() {
+    this.cleanupIdle(Date.now());
+    return {
+      id: this.spec.id,
+      keyCount: this.entries.size,
+      maxKeys: this.spec.maxKeys,
+      activeRuns: this.limiter.active,
+      queuedRuns: this.limiter.queued(),
+      keys: Array.from(this.entries.values(), (entry) => entry.metrics())
+    };
+  }
+  keys() {
+    this.cleanupIdle(Date.now());
+    return Array.from(this.entries.keys());
+  }
+  normalize(rawKey) {
+    const key = this.spec.normalizeKey(rawKey).trim();
+    if (!key) {
+      throw new Error(`Probe family ${this.spec.id} normalized an empty key`);
+    }
+    return key;
+  }
+  cleanupIdle(now) {
+    for (const [key, entry] of this.entries) {
+      if (!entry.isRefreshing() && now - entry.lastAccessAt > this.spec.idleKeyTtlMs) {
+        this.entries.delete(key);
+      }
+    }
+  }
+  evictLruIfNeeded() {
+    while (this.entries.size > this.spec.maxKeys) {
+      let oldestKey = null;
+      let oldestAccess = Number.POSITIVE_INFINITY;
+      for (const [key, entry] of this.entries) {
+        if (entry.isRefreshing()) {
+          continue;
+        }
+        if (entry.lastAccessAt < oldestAccess) {
+          oldestAccess = entry.lastAccessAt;
+          oldestKey = key;
+        }
+      }
+      if (!oldestKey) {
+        return;
+      }
+      this.entries.delete(oldestKey);
+    }
+  }
+}
+function defineProbe(spec) {
+  assertProbeSpec(spec);
+  const handle = new ProbeInstance({
+    spec,
+    run: spec.run
+  });
+  registeredProbes.push({
+    kind: "probe",
+    id: spec.id,
+    handle
+  });
+  return handle;
+}
+
+// packages/runtime/src/system-probes/exec.ts
+import { spawn } from "child_process";
+
+// packages/runtime/src/system-probes/scoutd-client.ts
+import { existsSync as existsSync2 } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+import { Socket } from "net";
+
+// packages/runtime/src/system-probes/scout-host-catalog.ts
+var SCOUT_HOST_PROBE_SCHEMA_VERSIONS = {
+  "tailscale.status": 1,
+  "git.buildInfo": 1,
+  "git.revParse": 1,
+  "git.diffShortstat": 1,
+  "git.statusPorcelain": 1,
+  "git.mergeBase": 1,
+  "git.logLastCommitUnix": 1,
+  "git.worktreeListPorcelain": 1,
+  "tmux.sessions": 1,
+  "tmux.panes": 1,
+  "zellij.sessions": 1,
+  "ps.runtime": 1,
+  "ps.discovery": 1,
+  "ps.cwd": 1,
+  "net.listeners": 1,
+  "repo.scan": 1,
+  "repo.diff": 1
+};
+var SCOUT_HOST_EXEC_VERB_SCHEMA_VERSIONS = {
+  "tmux.sendKeys": 1,
+  "tmux.sendKeysLiteral": 1,
+  "tmux.loadBuffer": 1,
+  "tmux.pasteBuffer": 1,
+  "tmux.deleteBuffer": 1,
+  "tmux.killSession": 1,
+  "tmux.newSession": 1,
+  "tmux.detachClient": 1,
+  "tailscale.cert": 1,
+  "reveal.open": 1
+};
+function expectedScoutHostProbeSchemaVersion(probeId) {
+  return Object.hasOwn(SCOUT_HOST_PROBE_SCHEMA_VERSIONS, probeId) ? SCOUT_HOST_PROBE_SCHEMA_VERSIONS[probeId] : null;
+}
+function expectedScoutHostExecVerbSchemaVersion(verb) {
+  return Object.hasOwn(SCOUT_HOST_EXEC_VERB_SCHEMA_VERSIONS, verb) ? SCOUT_HOST_EXEC_VERB_SCHEMA_VERSIONS[verb] : null;
+}
+
+// packages/runtime/src/system-probes/scoutd-client.ts
+var CAPABILITIES_SCHEMA = "openscout.probe.capabilities/v1";
+var REQUEST_SCHEMA = "openscout.probe.request/v1";
+var SNAPSHOT_SCHEMA = "openscout.probe.snapshot/v1";
+var ERROR_SCHEMA = "openscout.probe.error/v1";
+var EXEC_REQUEST_SCHEMA = "openscout.exec.request/v1";
+var EXEC_RESPONSE_SCHEMA = "openscout.exec.response/v1";
+var CAPABILITY_RECHECK_MS = 1e4;
+var SOCKET_TIMEOUT_MS = 900;
+var MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+function readString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function readNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function fallbackMessage(error) {
+  if (error instanceof Error && error.message.trim()) {
+    return error.message;
+  }
+  return String(error);
+}
+
+class ScoutdExecResponseError extends Error {
+  code;
+  timedOut;
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "ScoutdExecResponseError";
+    this.code = options.code ?? "exec_error";
+    this.timedOut = options.timedOut ?? false;
+  }
+}
+
+class ScoutdProbeResponseError extends Error {
+  code;
+  timedOut;
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "ScoutdProbeResponseError";
+    this.code = options.code ?? "probe_error";
+    this.timedOut = options.timedOut ?? false;
+  }
+}
+function resolveScoutdProbesSocketPath(env = process.env) {
+  const explicit = env.OPENSCOUT_PROBES_SOCKET?.trim();
+  if (explicit) {
+    return explicit;
+  }
+  const openScoutHome = env.OPENSCOUT_HOME?.trim() || join2(homedir2(), ".openscout");
+  return join2(openScoutHome, "run", "scoutd-probes.sock");
+}
+
+class ScoutdProbeClient {
+  env;
+  capabilities = null;
+  lastCapabilityCheckAt = null;
+  lastError = null;
+  daemonObserved = false;
+  fallbackByProbe = new Map;
+  fallbackByExec = new Map;
+  constructor(env = process.env) {
+    this.env = env;
+  }
+  async requestProbe(input) {
+    const socketPath = resolveScoutdProbesSocketPath(this.env);
+    const socketTimeoutMs = probeSocketTimeoutMs(input.timeoutMs);
+    const socketExists = existsSync2(socketPath);
+    if (!socketExists) {
+      this.capabilities = null;
+      this.lastError = null;
+      return this.daemonObserved ? this.fallback(input.probeId, input.key, `probe socket is missing: ${socketPath}`) : { state: "local" };
+    }
+    this.daemonObserved = true;
+    const capabilities = await this.ensureCapabilities(socketPath, socketTimeoutMs);
+    if (!capabilities) {
+      return this.fallback(input.probeId, input.key, this.lastError ?? "probe capabilities unavailable");
+    }
+    const capability = capabilities.families.get(input.probeId);
+    if (!capability) {
+      return this.fallback(input.probeId, input.key, `scoutd does not serve ${input.probeId}`);
+    }
+    const expectedSchemaVersion = expectedScoutHostProbeSchemaVersion(input.probeId);
+    if (expectedSchemaVersion === null) {
+      return this.fallback(input.probeId, input.key, `client has no compiled schema version for ${input.probeId}`);
+    }
+    if (capability.schemaVersion !== expectedSchemaVersion) {
+      return this.fallback(input.probeId, input.key, `scoutd serves ${input.probeId} schema v${capability.schemaVersion}, expected v${expectedSchemaVersion}`);
+    }
+    try {
+      const response = await requestJson(socketPath, {
+        schema: REQUEST_SCHEMA,
+        schemaVersion: expectedSchemaVersion,
+        probeId: input.probeId,
+        key: input.key ?? null,
+        maxAgeMs: input.maxAgeMs,
+        opTimeoutMs: requestOpTimeoutMs(input.timeoutMs)
+      }, { timeoutMs: socketTimeoutMs });
+      if (!isRecord2(response) || response.schema !== SNAPSHOT_SCHEMA) {
+        throw new Error("scoutd returned an invalid probe snapshot envelope");
+      }
+      if (response.error) {
+        const error = isRecord2(response.error) ? response.error : {};
+        const code = readString(error.code) ?? "probe_error";
+        const message = readString(error.message) ?? code;
+        const timedOut = error.timedOut === true || error.timed_out === true;
+        throw new ScoutdProbeResponseError(message, { code, timedOut });
+      }
+      this.fallbackByProbe.delete(fallbackKey(input.probeId, input.key));
+      this.lastError = null;
+      return {
+        state: "scoutd",
+        value: response.value,
+        generatedAt: readNumber(response.generatedAt) ?? Date.now(),
+        daemonVersion: readString(response.daemonVersion) ?? capabilities.daemonVersion
+      };
+    } catch (error) {
+      if (!(error instanceof ScoutdProbeResponseError)) {
+        this.capabilities = null;
+        this.lastCapabilityCheckAt = null;
+      }
+      this.lastError = fallbackMessage(error);
+      return this.fallback(input.probeId, input.key, this.lastError);
+    }
+  }
+  async requestExecVerb(input) {
+    const socketPath = resolveScoutdProbesSocketPath(this.env);
+    const socketTimeoutMs = execSocketTimeoutMs(input.args);
+    const socketExists = existsSync2(socketPath);
+    if (!socketExists) {
+      this.capabilities = null;
+      this.lastError = null;
+      return this.daemonObserved ? this.execFallback(input.verb, `probe socket is missing: ${socketPath}`) : { state: "local" };
+    }
+    this.daemonObserved = true;
+    const capabilities = await this.ensureCapabilities(socketPath, socketTimeoutMs);
+    if (!capabilities) {
+      return this.execFallback(input.verb, this.lastError ?? "probe capabilities unavailable");
+    }
+    const capability = capabilities.verbs.get(input.verb);
+    if (!capability) {
+      return this.execFallback(input.verb, `scoutd does not serve ${input.verb}`);
+    }
+    const expectedSchemaVersion = expectedScoutHostExecVerbSchemaVersion(input.verb);
+    if (expectedSchemaVersion === null) {
+      return this.execFallback(input.verb, `client has no compiled schema version for ${input.verb}`);
+    }
+    if (capability.schemaVersion !== expectedSchemaVersion) {
+      return this.execFallback(input.verb, `scoutd serves ${input.verb} schema v${capability.schemaVersion}, expected v${expectedSchemaVersion}`);
+    }
+    try {
+      const response = await requestJson(socketPath, {
+        schema: EXEC_REQUEST_SCHEMA,
+        schemaVersion: expectedSchemaVersion,
+        verb: input.verb,
+        args: input.args
+      }, { timeoutMs: socketTimeoutMs });
+      if (!isRecord2(response) || response.schema !== EXEC_RESPONSE_SCHEMA) {
+        throw new Error("scoutd returned an invalid exec response envelope");
+      }
+      if (!response.ok) {
+        const error = isRecord2(response.error) ? response.error : {};
+        const code = readString(error.code) ?? "exec_error";
+        const message = readString(error.message) ?? code;
+        const timedOut = error.timedOut === true || error.timed_out === true;
+        throw new ScoutdExecResponseError(message, { code, timedOut });
+      }
+      this.fallbackByExec.delete(input.verb);
+      this.lastError = null;
+      return {
+        state: "scoutd",
+        value: response.value,
+        daemonVersion: readString(response.daemonVersion) ?? capabilities.daemonVersion
+      };
+    } catch (error) {
+      if (error instanceof ScoutdExecResponseError) {
+        throw error;
+      }
+      this.capabilities = null;
+      this.lastCapabilityCheckAt = null;
+      this.lastError = fallbackMessage(error);
+      return this.execFallback(input.verb, this.lastError);
+    }
+  }
+  diagnostics() {
+    const socketPath = resolveScoutdProbesSocketPath(this.env);
+    return {
+      socketPath,
+      socketExists: existsSync2(socketPath),
+      daemonObserved: this.daemonObserved,
+      daemonVersion: this.capabilities?.daemonVersion ?? null,
+      supportedProbeIds: this.capabilities ? [...this.capabilities.families.keys()].sort() : [],
+      supportedExecVerbs: this.capabilities ? [...this.capabilities.verbs.keys()].sort() : [],
+      lastCapabilityCheckAt: this.lastCapabilityCheckAt,
+      lastError: this.lastError
+    };
+  }
+  resetForTests() {
+    this.capabilities = null;
+    this.lastCapabilityCheckAt = null;
+    this.lastError = null;
+    this.daemonObserved = false;
+    this.fallbackByProbe.clear();
+    this.fallbackByExec.clear();
+  }
+  async ensureCapabilities(socketPath, timeoutMs = SOCKET_TIMEOUT_MS) {
+    const now = Date.now();
+    if (this.capabilities && this.lastCapabilityCheckAt !== null && now - this.lastCapabilityCheckAt < CAPABILITY_RECHECK_MS) {
+      return this.capabilities;
+    }
+    this.lastCapabilityCheckAt = now;
+    try {
+      const response = await requestJson(socketPath, { schema: CAPABILITIES_SCHEMA }, { timeoutMs });
+      if (!isRecord2(response) || response.schema !== CAPABILITIES_SCHEMA) {
+        throw new Error("scoutd returned an invalid capabilities envelope");
+      }
+      const daemonVersion = readString(response.daemonVersion) ?? "unknown";
+      const families = new Map;
+      if (Array.isArray(response.families)) {
+        for (const entry of response.families) {
+          if (!isRecord2(entry))
+            continue;
+          const probeId = readString(entry.probeId);
+          const schemaVersion = readNumber(entry.schemaVersion);
+          const ttlMs = readNumber(entry.ttlMs);
+          if (probeId && schemaVersion !== null && ttlMs !== null) {
+            families.set(probeId, { probeId, schemaVersion, ttlMs });
+          }
+        }
+      }
+      const verbs = new Map;
+      if (Array.isArray(response.verbs)) {
+        for (const entry of response.verbs) {
+          if (!isRecord2(entry))
+            continue;
+          const verb = readString(entry.verb);
+          const schemaVersion = readNumber(entry.schemaVersion);
+          if (verb && schemaVersion !== null) {
+            verbs.set(verb, { verb, schemaVersion });
+          }
+        }
+      }
+      this.capabilities = { daemonVersion, families, verbs };
+      this.daemonObserved = true;
+      this.lastError = null;
+      return this.capabilities;
+    } catch (error) {
+      this.capabilities = null;
+      this.lastError = fallbackMessage(error);
+      return null;
+    }
+  }
+  fallback(probeId, key, reason) {
+    const id = fallbackKey(probeId, key);
+    let state = this.fallbackByProbe.get(id);
+    if (!state || state.reason !== reason) {
+      state = { since: Date.now(), reason };
+      this.fallbackByProbe.set(id, state);
+    }
+    return {
+      state: "local",
+      fallbackSince: state.since,
+      fallbackReason: state.reason
+    };
+  }
+  execFallback(verb, reason) {
+    let state = this.fallbackByExec.get(verb);
+    if (!state || state.reason !== reason) {
+      state = { since: Date.now(), reason };
+      this.fallbackByExec.set(verb, state);
+    }
+    return {
+      state: "local",
+      fallbackSince: state.since,
+      fallbackReason: state.reason
+    };
+  }
+}
+var singletonClient = null;
+function getScoutdProbeClient() {
+  singletonClient ??= new ScoutdProbeClient;
+  return singletonClient;
+}
+async function runWithScoutdFallback(input) {
+  const client = getScoutdProbeClient();
+  const scoutd = await client.requestProbe({
+    probeId: input.probeId,
+    key: input.key,
+    maxAgeMs: input.ctx.maxAgeMs,
+    timeoutMs: input.ctx.timeoutMs
+  });
+  if (scoutd.state === "scoutd") {
+    return probeRunOutput(scoutd.value, {
+      backend: "scoutd",
+      generatedAt: scoutd.generatedAt
+    });
+  }
+  const metadata = scoutd.fallbackSince ? {
+    backend: "local-fallback",
+    fallbackSince: scoutd.fallbackSince,
+    fallbackReason: scoutd.fallbackReason ?? "scoutd unavailable"
+  } : { backend: "local" };
+  try {
+    const local = await input.local();
+    return probeRunOutput(local, metadata);
+  } catch (error) {
+    throw new ProbeBackendError(error instanceof Error ? error.message : String(error), metadata, error);
+  }
+}
+function probeSocketTimeoutMs(timeoutMs) {
+  if (timeoutMs === undefined || !Number.isFinite(timeoutMs)) {
+    return SOCKET_TIMEOUT_MS;
+  }
+  return Math.max(SOCKET_TIMEOUT_MS, Math.min(Math.max(0, timeoutMs) + 1000, 31000));
+}
+function requestOpTimeoutMs(timeoutMs) {
+  if (timeoutMs === undefined || !Number.isFinite(timeoutMs)) {
+    return;
+  }
+  return Math.max(0, Math.floor(timeoutMs));
+}
+function execSocketTimeoutMs(args) {
+  const timeoutMs = typeof args.timeoutMs === "number" && Number.isFinite(args.timeoutMs) ? Math.max(0, args.timeoutMs) : 5000;
+  return Math.max(SOCKET_TIMEOUT_MS, Math.min(timeoutMs + 1000, 31000));
+}
+async function requestJson(socketPath, payload, options = {}) {
+  const bun = globalThis.Bun;
+  if (bun?.connect) {
+    return await requestJsonWithBun(bun.connect, socketPath, payload, options);
+  }
+  return await new Promise((resolve, reject) => {
+    const socket = new Socket;
+    let response = "";
+    let settled = false;
+    const finish = (error, value) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      socket.removeAllListeners();
+      socket.destroy();
+      if (error) {
+        reject(error);
+      } else {
+        resolve(value);
+      }
+    };
+    const timeoutMs = options.timeoutMs ?? SOCKET_TIMEOUT_MS;
+    const timer = setTimeout(() => {
+      finish(new Error(`scoutd probe socket timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    timer.unref?.();
+    const finishFromResponse = () => {
+      if (settled)
+        return;
+      try {
+        const parsed = JSON.parse(response);
+        if (isRecord2(parsed) && parsed.schema === ERROR_SCHEMA) {
+          const error = isRecord2(parsed.error) ? parsed.error : {};
+          const message = readString(error.message) ?? readString(error.code) ?? "scoutd probe request failed";
+          finish(new Error(message));
+          return;
+        }
+        finish(null, parsed);
+      } catch (error) {
+        finish(new Error(`scoutd probe response was not JSON: ${fallbackMessage(error)}`));
+      }
+    };
+    socket.setEncoding("utf8");
+    socket.on("connect", () => {
+      socket.write(`${JSON.stringify(payload)}
+`);
+    });
+    socket.on("data", (chunk) => {
+      response += chunk;
+      if (Buffer.byteLength(response, "utf8") > MAX_RESPONSE_BYTES) {
+        finish(new Error("scoutd probe response exceeded output limit"));
+      }
+    });
+    socket.on("error", (error) => finish(error));
+    socket.on("end", finishFromResponse);
+    socket.on("close", () => {
+      if (!settled) {
+        if (response.length === 0) {
+          finish(new Error("scoutd probe socket closed without a response"));
+        } else {
+          finishFromResponse();
+        }
+      }
+    });
+    socket.connect(socketPath);
+  });
+}
+async function requestJsonWithBun(connect, socketPath, payload, options = {}) {
+  return await new Promise((resolve, reject) => {
+    let response = "";
+    let settled = false;
+    let socketRef = null;
+    const decoder = new TextDecoder;
+    const finish = (error, value) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        socketRef?.end?.();
+      } catch {}
+      if (error) {
+        reject(error);
+      } else {
+        resolve(value);
+      }
+    };
+    const finishFromResponse = () => {
+      if (settled)
+        return;
+      try {
+        const parsed = JSON.parse(response);
+        if (isRecord2(parsed) && parsed.schema === ERROR_SCHEMA) {
+          const error = isRecord2(parsed.error) ? parsed.error : {};
+          const message = readString(error.message) ?? readString(error.code) ?? "scoutd probe request failed";
+          finish(new Error(message));
+          return;
+        }
+        finish(null, parsed);
+      } catch (error) {
+        finish(new Error(`scoutd probe response was not JSON: ${fallbackMessage(error)}`));
+      }
+    };
+    const timeoutMs = options.timeoutMs ?? SOCKET_TIMEOUT_MS;
+    const timer = setTimeout(() => {
+      finish(new Error(`scoutd probe socket timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    timer.unref?.();
+    connect({
+      unix: socketPath,
+      socket: {
+        open(socket) {
+          socketRef = socket;
+          socket.write(`${JSON.stringify(payload)}
+`);
+        },
+        data(_socket, data) {
+          response += decoder.decode(data, { stream: true });
+          if (Buffer.byteLength(response, "utf8") > MAX_RESPONSE_BYTES) {
+            finish(new Error("scoutd probe response exceeded output limit"));
+          }
+        },
+        close() {
+          if (response.length === 0) {
+            finish(new Error("scoutd probe socket closed without a response"));
+          } else {
+            response += decoder.decode();
+            finishFromResponse();
+          }
+        },
+        error(_socket, error) {
+          finish(error);
+        }
+      }
+    }).then((socket) => {
+      socketRef = socket;
+    }, (error) => {
+      finish(error instanceof Error ? error : new Error(String(error)));
+    });
+  });
+}
+function fallbackKey(probeId, key) {
+  return `${probeId}\x00${key ?? ""}`;
+}
+
+// packages/runtime/src/system-probes/exec.ts
+class ProbeCommandError extends Error {
+  code;
+  exitCode;
+  signal;
+  constructor(message, options) {
+    super(message);
+    this.name = "ProbeCommandError";
+    this.code = options.code;
+    this.exitCode = options.exitCode;
+    this.signal = options.signal;
+  }
+}
+var DEFAULT_STDOUT_CAP_BYTES = 1024 * 1024;
+var DEFAULT_STDERR_CAP_BYTES = 128 * 1024;
+var SIGKILL_DELAY_MS = 500;
+var EXEC_SYSTEM_TRANSPORT_METADATA = Symbol.for("openscout.execSystem.transport");
+var spawnProcess = spawn;
+function bufferByteLength(chunks) {
+  return chunks.reduce((total, chunk) => total + chunk.byteLength, 0);
+}
+function abortMessage(ctx) {
+  const reason = ctx.signal.reason;
+  if (typeof reason === "object" && reason !== null && "message" in reason) {
+    const message = reason.message;
+    if (typeof message === "string" && message.trim()) {
+      return message;
+    }
+  }
+  return `Probe ${ctx.probeId} aborted`;
+}
+async function execProbeFile(ctx, file, args, options = {}) {
+  const maxStdoutBytes = options.maxStdoutBytes ?? DEFAULT_STDOUT_CAP_BYTES;
+  const maxStderrBytes = options.maxStderrBytes ?? DEFAULT_STDERR_CAP_BYTES;
+  return await new Promise((resolve, reject) => {
+    if (ctx.signal.aborted) {
+      reject(new ProbeCommandError(abortMessage(ctx), { code: "aborted" }));
+      return;
+    }
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let settled = false;
+    let killTimer = null;
+    const child = spawnProcess(file, [...args], {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: [options.input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+      windowsHide: true
+    });
+    const cleanup = () => {
+      ctx.signal.removeEventListener("abort", onAbort);
+      if (killTimer) {
+        clearTimeout(killTimer);
+        killTimer = null;
+      }
+    };
+    const fail = (error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      if (!child.killed) {
+        child.kill("SIGTERM");
+      }
+      reject(error);
+    };
+    const onAbort = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      ctx.signal.removeEventListener("abort", onAbort);
+      child.kill("SIGTERM");
+      killTimer = setTimeout(() => {
+        child.kill("SIGKILL");
+      }, SIGKILL_DELAY_MS);
+      reject(new ProbeCommandError(abortMessage(ctx), { code: "timeout" }));
+    };
+    ctx.signal.addEventListener("abort", onAbort, { once: true });
+    if (options.input !== undefined) {
+      child.stdin?.end(options.input);
+    }
+    child.stdout?.on("data", (chunk) => {
+      if (settled) {
+        return;
+      }
+      stdoutChunks.push(chunk);
+      if (bufferByteLength(stdoutChunks) > maxStdoutBytes) {
+        fail(new ProbeCommandError(`Probe ${ctx.probeId} stdout exceeded ${maxStdoutBytes} bytes`, { code: "output_cap" }));
+      }
+    });
+    child.stderr?.on("data", (chunk) => {
+      if (settled) {
+        return;
+      }
+      stderrChunks.push(chunk);
+      if (bufferByteLength(stderrChunks) > maxStderrBytes) {
+        fail(new ProbeCommandError(`Probe ${ctx.probeId} stderr exceeded ${maxStderrBytes} bytes`, { code: "output_cap" }));
+      }
+    });
+    child.once("error", (error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      const code = typeof error.code === "string" ? String(error.code) : "spawn";
+      reject(new ProbeCommandError(error.message, { code }));
+    });
+    child.once("close", (exitCode, signal) => {
+      if (settled) {
+        cleanup();
+        return;
+      }
+      settled = true;
+      cleanup();
+      const stdout = Buffer.concat(stdoutChunks).toString("utf8");
+      const stderr = Buffer.concat(stderrChunks).toString("utf8");
+      if (exitCode === 0) {
+        resolve({ stdout, stderr, exitCode });
+        return;
+      }
+      reject(new ProbeCommandError(`${file} exited with ${exitCode ?? signal ?? "unknown status"}`, { code: "exit", exitCode, signal }));
+    });
+  });
+}
+
+// packages/runtime/src/system-probes/tailscale-status.ts
+var DEFAULT_TAILSCALE_STATUS_TIMEOUT_MS = 1500;
+function parseTailscaleStatusJson(raw) {
+  return JSON.parse(raw);
+}
+function parsePeers(status) {
+  const peers = Object.entries(status.Peer ?? {});
+  return peers.map(([fallbackId, peer]) => ({
+    id: peer.ID ?? fallbackId,
+    name: peer.HostName ?? peer.DNSName ?? fallbackId,
+    dnsName: peer.DNSName,
+    addresses: peer.TailscaleIPs ?? [],
+    online: peer.Online ?? false,
+    hostName: peer.HostName,
+    os: peer.OS,
+    tags: peer.Tags ?? []
+  }));
+}
+function parseSelf(status) {
+  const self = status.Self;
+  if (!self) {
+    return null;
+  }
+  return {
+    id: self.ID ?? self.DNSName ?? self.HostName ?? "self",
+    name: self.HostName ?? self.DNSName ?? "self",
+    dnsName: self.DNSName,
+    addresses: self.TailscaleIPs ?? [],
+    online: self.Online ?? true,
+    hostName: self.HostName,
+    os: self.OS,
+    tailnetName: status.CurrentTailnet?.Name,
+    magicDnsSuffix: status.CurrentTailnet?.MagicDNSSuffix
+  };
+}
+function isTailscaleBackendRunning(status) {
+  return (status.BackendState ?? "").trim().toLowerCase() === "running";
+}
+function normalizeHost(value) {
+  const normalized = value?.trim().replace(/\.$/, "").toLowerCase();
+  if (!normalized || normalized.includes("/") || /\s/.test(normalized)) {
+    return null;
+  }
+  return normalized;
+}
+function uniq(values) {
+  const seen = new Set;
+  const out = [];
+  for (const value of values) {
+    const normalized = normalizeHost(value ?? undefined);
+    if (!normalized || seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    out.push(normalized);
+  }
+  return out;
+}
+function tailscaleSelfWebHosts(self) {
+  if (!self) {
+    return [];
+  }
+  return uniq([
+    self.dnsName,
+    self.hostName && self.magicDnsSuffix ? `${self.hostName}.${self.magicDnsSuffix}` : undefined,
+    ...self.addresses
+  ]);
+}
+function summarizeTailscaleStatus(status) {
+  return {
+    backendState: status.BackendState ?? null,
+    running: isTailscaleBackendRunning(status),
+    health: status.Health ?? [],
+    peers: parsePeers(status),
+    self: parseSelf(status)
   };
 }
-async function requestScoutBrokerJsonWithTrace(baseUrl, path, options = {}) {
-  const { response, trace } = await requestBrokerWire(baseUrl, path, options);
-  let parsed;
-  let parsedJson = false;
-  if (response.text.length > 0) {
+function statusTimeoutMs(env) {
+  const parsed = Number.parseInt(env.OPENSCOUT_TAILSCALE_STATUS_TIMEOUT_MS ?? "", 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_TAILSCALE_STATUS_TIMEOUT_MS;
+}
+async function readStatusJsonFromFile(filePath) {
+  try {
+    const raw = await readFile(filePath, "utf8");
+    return parseTailscaleStatusJson(raw);
+  } catch {
+    return null;
+  }
+}
+function isDomainUnavailableError(error) {
+  if (!(error instanceof ProbeCommandError)) {
+    return false;
+  }
+  return error.code === "ENOENT" || error.code === "spawn" || error.code === "exit";
+}
+async function readTailscaleStatusSummaryLocal(ctx) {
+  const fixturePath = process.env.OPENSCOUT_TAILSCALE_STATUS_JSON;
+  if (fixturePath) {
+    const status = await readStatusJsonFromFile(fixturePath);
+    return status ? summarizeTailscaleStatus(status) : null;
+  }
+  const tailscaleBin = process.env.OPENSCOUT_TAILSCALE_BIN ?? "tailscale";
+  try {
+    const { stdout } = await execProbeFile(ctx, tailscaleBin, ["status", "--json"], {
+      maxStdoutBytes: 4 * 1024 * 1024,
+      maxStderrBytes: 256 * 1024
+    });
+    return summarizeTailscaleStatus(parseTailscaleStatusJson(stdout));
+  } catch (error) {
+    if (isDomainUnavailableError(error)) {
+      return null;
+    }
+    throw error;
+  }
+}
+var tailscaleStatusProbe = defineProbe({
+  id: "tailscale.status",
+  ttlMs: 30000,
+  timeoutMs: statusTimeoutMs(process.env),
+  run: (ctx) => runWithScoutdFallback({
+    probeId: "tailscale.status",
+    ctx,
+    local: () => readTailscaleStatusSummaryLocal(ctx)
+  })
+});
+
+// packages/runtime/src/tailscale.ts
+var DEFAULT_TAILSCALE_STATUS_TIMEOUT_MS2 = 1500;
+function readStatusJsonFromFileSync(filePath) {
+  const raw = readFileSync2(filePath, "utf8");
+  return parseTailscaleStatusJson(raw);
+}
+function statusTimeoutMs2(env) {
+  const parsed = Number.parseInt(env.OPENSCOUT_TAILSCALE_STATUS_TIMEOUT_MS ?? "", 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_TAILSCALE_STATUS_TIMEOUT_MS2;
+}
+function readStatusJsonSync(env = process.env) {
+  if (env.OPENSCOUT_TAILSCALE_AUTO_HOSTS === "0") {
+    return null;
+  }
+  const fixturePath = env.OPENSCOUT_TAILSCALE_STATUS_JSON;
+  if (fixturePath) {
     try {
-      parsed = JSON.parse(response.text);
-      parsedJson = true;
+      return readStatusJsonFromFileSync(fixturePath);
     } catch {
-      parsedJson = false;
+      return null;
     }
   }
-  if (!response.ok) {
-    if (parsedJson && options.acceptErrorJson?.(parsed)) {
-      return { value: parsed, trace };
-    }
-    throw new Error(`${path} returned ${response.status}: ${response.text}`);
+  const tailscaleBin = env.OPENSCOUT_TAILSCALE_BIN ?? (env === process.env ? "tailscale" : undefined);
+  if (!tailscaleBin) {
+    return null;
   }
-  if (parsedJson) {
-    return { value: parsed, trace };
+  try {
+    const stdout = execFileSync(tailscaleBin, ["status", "--json"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: statusTimeoutMs2(env),
+      windowsHide: true
+    });
+    return parseTailscaleStatusJson(stdout);
+  } catch {
+    return null;
   }
-  return { value: undefined, trace };
+}
+function readTailscaleSelfWebHostsSync(env = process.env) {
+  const status = readStatusJsonSync(env);
+  if (!status || !isTailscaleBackendRunning(status)) {
+    return [];
+  }
+  return tailscaleSelfWebHosts(summarizeTailscaleStatus(status).self);
 }
 
-// packages/runtime/src/support-paths.ts
-import { existsSync, mkdirSync, rmSync, writeFileSync } from "fs";
-import { homedir } from "os";
-import { join } from "path";
-var OPENSCOUT_RPC_CUTOVER_MARKER = "rpc-runtime-cutover-v1";
-function resolveOpenScoutSupportPaths() {
-  const home = homedir();
-  const supportDirectory = process.env.OPENSCOUT_SUPPORT_DIRECTORY ?? join(home, "Library", "Application Support", "OpenScout");
-  const logsDirectory = join(supportDirectory, "logs");
-  const runtimeDirectory = join(supportDirectory, "runtime");
-  const catalogDirectory = join(supportDirectory, "catalog");
-  const controlHome = process.env.OPENSCOUT_CONTROL_HOME ?? join(home, ".openscout", "control-plane");
-  const knowledgeDirectory = join(controlHome, "knowledge");
+// packages/runtime/src/local-config.ts
+import {
+  existsSync as existsSync3,
+  mkdirSync,
+  readFileSync as readFileSync3,
+  renameSync,
+  writeFileSync
+} from "fs";
+import { homedir as homedir3, hostname as osHostname } from "os";
+import { dirname, join as join3 } from "path";
+var LOCAL_CONFIG_VERSION = 1;
+var DEFAULT_SCOUT_WEB_PORTAL_HOST = "scout.local";
+var DEFAULT_SCOUT_WEB_DEV_HOST = `dev.${DEFAULT_SCOUT_WEB_PORTAL_HOST}`;
+var OPENSCOUT_PORTS = {
+  broker: 43110,
+  web: 43120,
+  webTerminalRelay: 43121,
+  vite: 43122,
+  pairingBridge: 43130,
+  pairingRelay: 43131,
+  pairingFileServer: 43132,
+  studio: 43140
+};
+var DEFAULT_LOCAL_CONFIG = {
+  version: LOCAL_CONFIG_VERSION,
+  host: "127.0.0.1",
+  webLocalName: undefined,
+  ports: {
+    broker: OPENSCOUT_PORTS.broker,
+    web: OPENSCOUT_PORTS.web,
+    pairing: OPENSCOUT_PORTS.pairingBridge
+  }
+};
+function localConfigHome() {
+  return process.env.OPENSCOUT_HOME ?? join3(homedir3(), ".openscout");
+}
+function localConfigPath() {
+  return join3(localConfigHome(), "config.json");
+}
+function loadLocalConfig() {
+  const configPath = localConfigPath();
+  if (!existsSync3(configPath))
+    return { version: LOCAL_CONFIG_VERSION };
+  try {
+    return validateLocalConfig(JSON.parse(readFileSync3(configPath, "utf8")));
+  } catch {
+    return { version: LOCAL_CONFIG_VERSION };
+  }
+}
+function validateLocalConfig(input) {
+  if (!input || typeof input !== "object")
+    return { version: LOCAL_CONFIG_VERSION };
+  const raw = input;
+  const out = { version: LOCAL_CONFIG_VERSION };
+  if (typeof raw.host === "string" && raw.host.trim().length > 0) {
+    out.host = raw.host.trim();
+  }
+  if (typeof raw.webLocalName === "string" && raw.webLocalName.trim().length > 0) {
+    out.webLocalName = raw.webLocalName.trim();
+  }
+  if (raw.ports && typeof raw.ports === "object") {
+    const ports = raw.ports;
+    const p = {};
+    if (isValidPort(ports.broker))
+      p.broker = ports.broker;
+    if (isValidPort(ports.web))
+      p.web = ports.web;
+    if (isValidPort(ports.pairing))
+      p.pairing = ports.pairing;
+    if (Object.keys(p).length > 0)
+      out.ports = p;
+  }
+  return out;
+}
+function isValidPort(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 && value < 65536;
+}
+function parseEnvPort(name) {
+  const raw = process.env[name]?.trim();
+  if (!raw) {
+    return;
+  }
+  const parsed = Number.parseInt(raw, 10);
+  return isValidPort(parsed) ? parsed : undefined;
+}
+function resolveEffectiveLocalConfig() {
+  const file = loadLocalConfig();
+  const host = process.env.OPENSCOUT_BROKER_HOST?.trim() || process.env.OPENSCOUT_HOST?.trim() || file.host;
+  const ports = {
+    broker: parseEnvPort("OPENSCOUT_BROKER_PORT") ?? file.ports?.broker,
+    web: parseEnvPort("OPENSCOUT_WEB_PORT") ?? parseEnvPort("SCOUT_WEB_PORT") ?? file.ports?.web,
+    pairing: parseEnvPort("OPENSCOUT_PAIRING_PORT") ?? file.ports?.pairing
+  };
   return {
-    supportDirectory,
-    logsDirectory,
-    appLogsDirectory: join(logsDirectory, "app"),
-    brokerLogsDirectory: join(logsDirectory, "broker"),
-    runtimeDirectory,
-    catalogDirectory,
-    relayAgentsDirectory: join(runtimeDirectory, "agents"),
-    settingsPath: join(supportDirectory, "settings.json"),
-    harnessCatalogPath: join(catalogDirectory, "harness-catalog.json"),
-    relayAgentsRegistryPath: join(supportDirectory, "relay-agents.json"),
-    managedInstallsPath: join(supportDirectory, "managed-installs.json"),
-    relayHubDirectory: process.env.OPENSCOUT_RELAY_HUB ?? join(home, ".openscout", "relay"),
-    controlHome,
-    knowledgeDirectory,
-    knowledgeQmdDirectory: join(knowledgeDirectory, "qmd"),
-    knowledgeSqlitePath: join(knowledgeDirectory, "knowledge.sqlite"),
-    desktopStatusPath: join(supportDirectory, "agent-status.json"),
-    workspaceStatePath: join(supportDirectory, "workspace-state.json"),
-    cutoverMarkerPath: join(supportDirectory, OPENSCOUT_RPC_CUTOVER_MARKER)
+    version: LOCAL_CONFIG_VERSION,
+    ...host ? { host } : {},
+    ...file.webLocalName ? { webLocalName: file.webLocalName } : {},
+    ...ports.broker || ports.web || ports.pairing ? { ports } : {}
   };
 }
-function ensureOpenScoutCleanSlateSync() {
-  const paths = resolveOpenScoutSupportPaths();
-  if (existsSync(paths.cutoverMarkerPath)) {
-    return;
+function localBrokerControlHost(host) {
+  const trimmed = host.trim();
+  if (!trimmed || trimmed === "0.0.0.0" || trimmed === "::" || trimmed === "[::]") {
+    return DEFAULT_LOCAL_CONFIG.host;
+  }
+  return trimmed;
+}
+function resolveBrokerControlUrl(config = resolveEffectiveLocalConfig()) {
+  const injected = process.env.OPENSCOUT_BROKER_INTERNAL_URL?.trim();
+  if (injected) {
+    return injected;
   }
-  rmSync(paths.supportDirectory, { recursive: true, force: true });
-  rmSync(paths.controlHome, { recursive: true, force: true });
-  rmSync(paths.relayHubDirectory, { recursive: true, force: true });
-  mkdirSync(paths.supportDirectory, { recursive: true });
-  writeFileSync(paths.cutoverMarkerPath, `${Date.now()}
-`, "utf8");
+  const host = config.host ?? DEFAULT_LOCAL_CONFIG.host;
+  const port = config.ports?.broker ?? DEFAULT_LOCAL_CONFIG.ports.broker;
+  return `http://${localBrokerControlHost(host)}:${port}`;
+}
+function resolveBrokerPort() {
+  return resolveEffectiveLocalConfig().ports?.broker ?? DEFAULT_LOCAL_CONFIG.ports.broker;
 }
 
 // packages/runtime/src/tool-resolution.ts
-import { accessSync, constants, existsSync as existsSync2 } from "fs";
-import { homedir as homedir2 } from "os";
-import { basename, dirname, join as join2, resolve } from "path";
+import { accessSync, constants, existsSync as existsSync4 } from "fs";
+import { homedir as homedir4 } from "os";
+import { basename, dirname as dirname2, join as join4, resolve } from "path";
 var DEFAULT_COMMON_EXECUTABLE_DIRECTORIES = [
-  join2(homedir2(), ".bun", "bin"),
+  join4(homedir4(), ".bun", "bin"),
   "/opt/homebrew/bin",
   "/usr/local/bin"
 ];
 function expandHomePath(value, env = process.env) {
-  const home = env.HOME ?? homedir2();
+  const home = env.HOME ?? homedir4();
   if (value === "~") {
     return home;
   }
   if (value.startsWith("~/")) {
-    return join2(home, value.slice(2));
+    return join4(home, value.slice(2));
   }
   return value;
 }
@@ -292,7 +1782,7 @@ function resolveExecutableFromSearch(options) {
   ], env);
   for (const directory of searchDirectories) {
     for (const name of options.names) {
-      const candidate = join2(directory, name);
+      const candidate = join4(directory, name);
       if (isExecutablePath(candidate)) {
         return {
           path: candidate,
@@ -316,7 +1806,7 @@ function findExecutableOnSearchPath(name, env) {
     ...DEFAULT_COMMON_EXECUTABLE_DIRECTORIES
   ], env);
   for (const directory of searchDirectories) {
-    const candidate = join2(directory, name);
+    const candidate = join4(directory, name);
     if (isExecutablePath(candidate)) {
       return { path: candidate, source: "path" };
     }
@@ -324,25 +1814,68 @@ function findExecutableOnSearchPath(name, env) {
   return null;
 }
 
+// packages/runtime/src/runtime-adapters.ts
+function normalizeRuntimeHost(value) {
+  const normalized = value?.trim().toLowerCase();
+  if (normalized === "bun")
+    return "bun";
+  if (normalized === "node")
+    return "node";
+  return null;
+}
+function normalizeRuntimeServiceAdapter(value) {
+  const normalized = value?.trim().toLowerCase().replaceAll("_", "-");
+  if (normalized === "macos-scoutd" || normalized === "macos-launchd")
+    return "macos-scoutd";
+  if (normalized === "linux-systemd-user" || normalized === "systemd-user")
+    return "linux-systemd-user";
+  if (normalized === "headless-foreground" || normalized === "foreground" || normalized === "headless") {
+    return "headless-foreground";
+  }
+  if (normalized === "windows-service")
+    return "windows-service";
+  return null;
+}
+function defaultServiceAdapterForPlatform(platform = process.platform, env = process.env) {
+  const explicit = normalizeRuntimeServiceAdapter(env.OPENSCOUT_SERVICE_ADAPTER);
+  if (explicit)
+    return explicit;
+  if (normalizeRuntimeHost(env.OPENSCOUT_RUNTIME_HOST) === "node") {
+    return "headless-foreground";
+  }
+  if (platform === "darwin")
+    return "macos-scoutd";
+  if (platform === "linux")
+    return "headless-foreground";
+  if (platform === "win32")
+    return "windows-service";
+  return "headless-foreground";
+}
+
 // packages/runtime/src/broker-process-manager.ts
 function isTmpPath(p) {
   return /^\/(?:private\/)?tmp\//.test(p);
 }
 var DEFAULT_BROKER_HOST = "127.0.0.1";
 var DEFAULT_BROKER_HOST_MESH = "0.0.0.0";
-var DEFAULT_BROKER_PORT = 65535;
+var DEFAULT_BROKER_PORT = OPENSCOUT_PORTS.broker;
 var DEFAULT_ADVERTISE_SCOPE = "local";
-function resolveAdvertiseScope() {
-  const raw = (process.env.OPENSCOUT_ADVERTISE_SCOPE ?? "").trim().toLowerCase();
+function resolveAdvertiseScope(env = process.env) {
+  if (openScoutNetworkDiscoveryEnabled(env))
+    return "mesh";
+  const raw = (env.OPENSCOUT_ADVERTISE_SCOPE ?? "").trim().toLowerCase();
   if (raw === "mesh")
     return "mesh";
   if (raw === "local")
     return "local";
   return DEFAULT_ADVERTISE_SCOPE;
 }
-function resolveBrokerHost(scope = resolveAdvertiseScope()) {
-  const explicit = process.env.OPENSCOUT_BROKER_HOST;
-  if (typeof explicit === "string" && explicit.trim().length > 0) {
+function resolveBrokerHost(scope = resolveAdvertiseScope(), env = process.env) {
+  const explicit = env.OPENSCOUT_BROKER_HOST?.trim();
+  if (explicit) {
+    if (scope === "mesh" && isLoopbackHost(explicit)) {
+      return DEFAULT_BROKER_HOST_MESH;
+    }
     return explicit;
   }
   return scope === "mesh" ? DEFAULT_BROKER_HOST_MESH : DEFAULT_BROKER_HOST;
@@ -351,14 +1884,46 @@ function isLoopbackHost(host) {
   const trimmed = host.trim();
   return trimmed === "127.0.0.1" || trimmed === "::1" || trimmed === "localhost";
 }
-var BROKER_SERVICE_POLL_INTERVAL_MS = 100;
-var DEFAULT_BROKER_START_TIMEOUT_MS = 15000;
-var DEFAULT_BROKER_STOP_TIMEOUT_MS = 20000;
+function localBrokerControlHost2(host) {
+  const trimmed = host.trim();
+  if (!trimmed || isWildcardHost(trimmed)) {
+    return DEFAULT_BROKER_HOST;
+  }
+  return trimmed;
+}
 function buildDefaultBrokerUrl(host = DEFAULT_BROKER_HOST, port = DEFAULT_BROKER_PORT) {
   return `http://${host}:${port}`;
 }
+function resolveBrokerUrl(host, port, scope, env = process.env) {
+  const explicit = env.OPENSCOUT_BROKER_URL?.trim();
+  if (explicit && !(scope === "mesh" && isUnreachableMeshBrokerUrl(explicit))) {
+    return explicit;
+  }
+  if (scope === "mesh") {
+    const tailnetHost = readTailscaleSelfWebHostsSync(env)[0];
+    if (tailnetHost) {
+      return buildDefaultBrokerUrl(tailnetHost, port);
+    }
+  }
+  return buildDefaultBrokerUrl(host, port);
+}
+function isUnreachableMeshBrokerUrl(value) {
+  try {
+    const host = new URL(value).hostname;
+    return isLoopbackHost(host) || isWildcardHost(host);
+  } catch {
+    return false;
+  }
+}
+function isWildcardHost(host) {
+  const trimmed = host.trim();
+  return trimmed === "0.0.0.0" || trimmed === "::" || trimmed === "[::]";
+}
+function buildLocalBrokerControlUrl(host = DEFAULT_BROKER_HOST, port = DEFAULT_BROKER_PORT) {
+  return buildDefaultBrokerUrl(localBrokerControlHost2(host), port);
+}
 function buildDefaultBrokerSocketPath(runtimeDirectory) {
-  return join3(runtimeDirectory, "broker.sock");
+  return join5(runtimeDirectory, "broker.sock");
 }
 var DEFAULT_BROKER_URL = buildDefaultBrokerUrl();
 function normalizeBrokerUrl(value) {
@@ -368,8 +1933,15 @@ function normalizeBrokerUrl(value) {
     return value.trim();
   }
 }
+function resolveScoutBrokerControlUrl(_config = resolveBrokerServiceConfig()) {
+  return resolveBrokerControlUrl();
+}
 function resolveBrokerSocketPathForBaseUrl(baseUrl, config = resolveBrokerServiceConfig()) {
-  return normalizeBrokerUrl(baseUrl) === normalizeBrokerUrl(config.brokerUrl) ? config.brokerSocketPath : null;
+  const normalized = normalizeBrokerUrl(baseUrl);
+  if (normalized === normalizeBrokerUrl(config.brokerUrl) || normalized === normalizeBrokerUrl(resolveScoutBrokerControlUrl(config))) {
+    return config.brokerSocketPath;
+  }
+  return null;
 }
 function runtimePackageDir() {
   const explicit = process.env.OPENSCOUT_RUNTIME_PACKAGE_DIR?.trim();
@@ -384,17 +1956,17 @@ function runtimePackageDir() {
   const fromGlobal = findGlobalRuntimeDir();
   if (fromGlobal)
     return fromGlobal;
-  const moduleDir = dirname2(fileURLToPath(import.meta.url));
+  const moduleDir = dirname3(fileURLToPath(import.meta.url));
   return resolve2(moduleDir, "..");
 }
 function isInstalledRuntimePackageDir(candidate) {
-  return existsSync3(join3(candidate, "package.json")) && existsSync3(join3(candidate, "bin", "openscout-runtime.mjs"));
+  return existsSync5(join5(candidate, "package.json")) && existsSync5(join5(candidate, "bin", "openscout-runtime.mjs"));
 }
 function findGlobalRuntimeDir() {
   const candidates = [
-    join3(homedir3(), ".bun", "node_modules", "@openscout", "runtime"),
-    join3(homedir3(), ".bun", "install", "global", "node_modules", "@openscout", "runtime"),
-    join3(homedir3(), ".bun", "install", "global", "node_modules", "@openscout", "scout", "node_modules", "@openscout", "runtime")
+    join5(homedir5(), ".bun", "node_modules", "@openscout", "runtime"),
+    join5(homedir5(), ".bun", "install", "global", "node_modules", "@openscout", "runtime"),
+    join5(homedir5(), ".bun", "install", "global", "node_modules", "@openscout", "scout", "node_modules", "@openscout", "runtime")
   ];
   for (const c of candidates) {
     if (isInstalledRuntimePackageDir(c))
@@ -407,7 +1979,7 @@ function findGlobalRuntimeDir() {
       const scoutPkg = resolve2(scoutBin, "..", "..");
       if (isInstalledRuntimePackageDir(scoutPkg))
         return scoutPkg;
-      const nested = join3(scoutPkg, "node_modules", "@openscout", "runtime");
+      const nested = join5(scoutPkg, "node_modules", "@openscout", "runtime");
       if (isInstalledRuntimePackageDir(nested))
         return nested;
       const sibling = resolve2(scoutPkg, "..", "runtime");
@@ -418,30 +1990,43 @@ function findGlobalRuntimeDir() {
   return null;
 }
 function findBundledRuntimeDir() {
-  const moduleDir = dirname2(fileURLToPath(import.meta.url));
-  const candidate = resolve2(moduleDir, "..");
-  return isInstalledRuntimePackageDir(candidate) ? candidate : null;
+  const moduleDir = dirname3(fileURLToPath(import.meta.url));
+  return resolveBundledRuntimeDirFromModuleDir(moduleDir);
+}
+function resolveBundledRuntimeDirFromModuleDir(moduleDir) {
+  const candidates = [
+    resolve2(moduleDir, ".."),
+    resolve2(moduleDir, "..", "..")
+  ];
+  for (const candidate of candidates) {
+    if (isInstalledRuntimePackageDir(candidate))
+      return candidate;
+  }
+  return null;
 }
 function findWorkspaceRuntimeDir(startDir) {
   let current = resolve2(startDir);
   while (true) {
-    const candidate = join3(current, "packages", "runtime");
-    if (existsSync3(join3(candidate, "package.json")) && existsSync3(join3(candidate, "src"))) {
+    const candidate = join5(current, "packages", "runtime");
+    if (existsSync5(join5(candidate, "package.json")) && existsSync5(join5(candidate, "src"))) {
       return candidate;
     }
-    const parent = dirname2(current);
+    const parent = dirname3(current);
     if (parent === current)
       return null;
     current = parent;
   }
 }
 function resolveBunExecutable2() {
-  const bun = resolveBunExecutable(process.env);
+  const bun = resolveOptionalBunExecutable();
   if (bun) {
-    return bun.path;
+    return bun;
   }
   throw new Error("Unable to locate Bun for broker service management. Install Bun or set OPENSCOUT_BUN_BIN.");
 }
+function resolveOptionalBunExecutable() {
+  return resolveBunExecutable(process.env)?.path ?? null;
+}
 function resolveBrokerServiceMode() {
   const explicit = (process.env.OPENSCOUT_BROKER_SERVICE_MODE ?? "").trim().toLowerCase();
   if (explicit === "prod" || explicit === "production") {
@@ -452,20 +2037,6 @@ function resolveBrokerServiceMode() {
   }
   return "dev";
 }
-function resolveBrokerStartTimeoutMs() {
-  const explicit = Number.parseInt(process.env.OPENSCOUT_BROKER_START_TIMEOUT_MS ?? "", 10);
-  if (Number.isFinite(explicit) && explicit > 0) {
-    return Math.max(explicit, BROKER_SERVICE_POLL_INTERVAL_MS);
-  }
-  return DEFAULT_BROKER_START_TIMEOUT_MS;
-}
-function resolveBrokerStopTimeoutMs() {
-  const explicit = Number.parseInt(process.env.OPENSCOUT_BROKER_STOP_TIMEOUT_MS ?? "", 10);
-  if (Number.isFinite(explicit) && explicit > 0) {
-    return Math.max(explicit, BROKER_SERVICE_POLL_INTERVAL_MS);
-  }
-  return DEFAULT_BROKER_STOP_TIMEOUT_MS;
-}
 function resolveBrokerServiceLabel(mode) {
   const explicit = process.env.OPENSCOUT_SERVICE_LABEL?.trim() || process.env.OPENSCOUT_BROKER_SERVICE_LABEL?.trim();
   if (explicit) {
@@ -481,33 +2052,23 @@ function resolveBrokerServiceLabel(mode) {
       return "dev.openscout";
   }
 }
-function legacyBrokerServiceLabel(mode) {
-  switch (mode) {
-    case "prod":
-      return "com.openscout.broker";
-    case "custom":
-      return "com.openscout.broker.custom";
-    case "dev":
-    default:
-      return "dev.openscout.broker";
-  }
-}
 function resolveBrokerServiceConfig() {
   const mode = resolveBrokerServiceMode();
   const label = resolveBrokerServiceLabel(mode);
+  const serviceAdapter = resolveBrokerServiceAdapter();
   const uid = typeof process.getuid === "function" ? process.getuid() : Number.parseInt(process.env.UID ?? "0", 10);
   const supportPaths = resolveOpenScoutSupportPaths();
-  const defaultSupportDir = join3(homedir3(), "Library", "Application Support", "OpenScout");
+  const defaultSupportDir = join5(homedir5(), "Library", "Application Support", "OpenScout");
   const supportDirectory = isTmpPath(supportPaths.supportDirectory) ? defaultSupportDir : supportPaths.supportDirectory;
-  const runtimeDirectory = join3(supportDirectory, "runtime");
-  const logsDirectory = join3(supportDirectory, "logs", "broker");
-  const controlHome = isTmpPath(supportPaths.controlHome) ? join3(homedir3(), ".openscout", "control-plane") : supportPaths.controlHome;
+  const runtimeDirectory = join5(supportDirectory, "runtime");
+  const logsDirectory = join5(supportDirectory, "logs", "broker");
+  const controlHome = isTmpPath(supportPaths.controlHome) ? join5(homedir5(), ".openscout", "control-plane") : supportPaths.controlHome;
   const advertiseScope = resolveAdvertiseScope();
   const brokerHost = resolveBrokerHost(advertiseScope);
-  const brokerPort = Number.parseInt(process.env.OPENSCOUT_BROKER_PORT ?? String(DEFAULT_BROKER_PORT), 10);
-  const brokerUrl = process.env.OPENSCOUT_BROKER_URL ?? buildDefaultBrokerUrl(brokerHost, brokerPort);
+  const brokerPort = Number.parseInt(process.env.OPENSCOUT_BROKER_PORT ?? String(resolveBrokerPort()), 10);
+  const brokerUrl = resolveBrokerUrl(brokerHost, brokerPort, advertiseScope);
   const brokerSocketPath = process.env.OPENSCOUT_BROKER_SOCKET_PATH ?? buildDefaultBrokerSocketPath(runtimeDirectory);
-  const launchAgentPath = join3(homedir3(), "Library", "LaunchAgents", `${label}.plist`);
+  const launchAgentPath = join5(homedir5(), "Library", "LaunchAgents", `${label}.plist`);
   return {
     label,
     mode,
@@ -518,11 +2079,11 @@ function resolveBrokerServiceConfig() {
     supportDirectory,
     runtimeDirectory,
     logsDirectory,
-    stdoutLogPath: join3(logsDirectory, "stdout.log"),
-    stderrLogPath: join3(logsDirectory, "stderr.log"),
+    stdoutLogPath: join5(logsDirectory, "stdout.log"),
+    stderrLogPath: join5(logsDirectory, "stderr.log"),
     controlHome,
     runtimePackageDir: runtimePackageDir(),
-    bunExecutable: resolveBunExecutable2(),
+    bunExecutable: serviceAdapter === "macos-scoutd" ? resolveBunExecutable2() : resolveOptionalBunExecutable(),
     brokerHost,
     brokerPort,
     brokerUrl,
@@ -531,86 +2092,259 @@ function resolveBrokerServiceConfig() {
     coreAgents: readCoreAgentsSync()
   };
 }
-function renderLaunchAgentPlist(config) {
-  const launchPath = resolveLaunchAgentPATH();
-  const coreAgentsValue = (config.coreAgents ?? []).join(",");
-  const envEntries = {
+function resolveBrokerServiceAdapter(env = process.env, platform = process.platform) {
+  return defaultServiceAdapterForPlatform(platform, env);
+}
+function executableCandidate(path) {
+  return isExecutablePath(path) ? path : null;
+}
+function resolveExecutableName(name) {
+  return resolveExecutableFromSearch({ names: [name] })?.path ?? null;
+}
+function resolveEnvExecutable(value) {
+  const trimmed = value?.trim();
+  if (!trimmed)
+    return null;
+  if (trimmed.includes("/") || trimmed.startsWith(".")) {
+    const expanded = resolve2(expandHomePath(trimmed));
+    return executableCandidate(expanded);
+  }
+  return resolveExecutableName(trimmed);
+}
+function findWorkspaceRootFromRuntimeDir(runtimePackageDir2) {
+  let current = resolve2(runtimePackageDir2);
+  while (true) {
+    if (existsSync5(join5(current, "Cargo.toml")) && existsSync5(join5(current, "crates", "scoutd", "Cargo.toml"))) {
+      return current;
+    }
+    const parent = dirname3(current);
+    if (parent === current)
+      return null;
+    current = parent;
+  }
+}
+function workspaceScoutdAllowed() {
+  const raw = process.env.OPENSCOUT_ALLOW_WORKSPACE_SCOUTD?.trim().toLowerCase();
+  return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
+function resolveScoutdCommand(config = resolveBrokerServiceConfig()) {
+  const explicit = resolveEnvExecutable(process.env.OPENSCOUT_SCOUTD_BIN);
+  if (explicit) {
+    return { path: explicit, source: "env" };
+  }
+  const workspaceRoot = findWorkspaceRootFromRuntimeDir(config.runtimePackageDir);
+  const packageCandidates = [
+    join5(config.runtimePackageDir, "bin", "scoutd"),
+    join5(config.runtimePackageDir, "native", "scoutd"),
+    join5(config.runtimePackageDir, "scoutd"),
+    workspaceRoot ? join5(workspaceRoot, "packages", "cli", "bin", "scoutd") : null,
+    workspaceRoot ? join5(workspaceRoot, "packages", "runtime", "bin", "scoutd") : null,
+    join5(config.runtimeDirectory, "scoutd"),
+    join5(dirname3(config.runtimePackageDir), "scout", "bin", "scoutd")
+  ];
+  for (const candidate of packageCandidates) {
+    const resolved = executableCandidate(candidate);
+    if (resolved) {
+      return { path: resolved, source: "package" };
+    }
+  }
+  const fromPath = resolveExecutableName("scoutd");
+  if (fromPath) {
+    return { path: fromPath, source: "path" };
+  }
+  if (workspaceRoot && workspaceScoutdAllowed()) {
+    for (const candidate of [
+      join5(workspaceRoot, "target", "release", "scoutd"),
+      join5(workspaceRoot, "target", "debug", "scoutd")
+    ]) {
+      const resolved = executableCandidate(candidate);
+      if (resolved) {
+        return { path: resolved, source: "workspace" };
+      }
+    }
+  }
+  return null;
+}
+function nativeServiceEnvironment(config, scoutdPath) {
+  const env = {
+    ...process.env,
+    OPENSCOUT_SCOUTD_BIN: scoutdPath,
+    OPENSCOUT_RUNTIME_PACKAGE_DIR: config.runtimePackageDir,
+    OPENSCOUT_SUPPORT_DIRECTORY: config.supportDirectory,
+    OPENSCOUT_CONTROL_HOME: config.controlHome,
     OPENSCOUT_BROKER_HOST: config.brokerHost,
     OPENSCOUT_BROKER_PORT: String(config.brokerPort),
     OPENSCOUT_BROKER_URL: config.brokerUrl,
     OPENSCOUT_BROKER_SOCKET_PATH: config.brokerSocketPath,
-    OPENSCOUT_CONTROL_HOME: config.controlHome,
     OPENSCOUT_BROKER_SERVICE_MODE: config.mode,
     OPENSCOUT_BROKER_SERVICE_LABEL: config.label,
     OPENSCOUT_SERVICE_LABEL: config.label,
-    OPENSCOUT_ADVERTISE_SCOPE: config.advertiseScope,
-    HOME: homedir3(),
-    PATH: launchPath,
-    ...collectOptionalEnvVars([
-      "OPENSCOUT_MESH_ID",
-      "OPENSCOUT_MESH_SEEDS",
-      "OPENSCOUT_MESH_DISCOVERY_INTERVAL_MS",
-      "OPENSCOUT_NODE_NAME",
-      "OPENSCOUT_NODE_ID",
-      "OPENSCOUT_NODE_QUALIFIER",
-      "OPENSCOUT_TAILSCALE_BIN",
-      "OPENSCOUT_TAILSCALE_STATUS_JSON",
-      "OPENSCOUT_SSE_KEEPALIVE_MS",
-      "OPENSCOUT_WEB_EDGE_SCHEME",
-      "OPENSCOUT_WEB_PUBLIC_ORIGIN",
-      "OPENSCOUT_WEB_PORTAL_HOST",
-      "OPENSCOUT_WEB_LOCAL_NAME",
-      "OPENSCOUT_WEB_ADVERTISED_HOST",
-      "OPENSCOUT_WEB_TRUSTED_HOSTS",
-      "OPENSCOUT_WEB_TRUSTED_ORIGINS",
-      "OPENSCOUT_WEB_PORT",
-      "OPENSCOUT_WEB_FLAG_BUNDLE",
-      "OPENSCOUT_WEB_EXPERIENCE",
-      "OPENSCOUT_WEB_AB_VARIANT"
-    ])
+    OPENSCOUT_ADVERTISE_SCOPE: config.advertiseScope
+  };
+  if (config.bunExecutable) {
+    env.OPENSCOUT_BUN_BIN = config.bunExecutable;
+  }
+  if (config.coreAgents.length > 0) {
+    env.OPENSCOUT_CORE_AGENTS = config.coreAgents.join(",");
+  }
+  return env;
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readString2(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+function readBoolean(value) {
+  return typeof value === "boolean" ? value : undefined;
+}
+function readNumber2(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function readHealthTransport(value) {
+  return value === "unix_socket" || value === "http" || value === "in_process" ? value : undefined;
+}
+function normalizeNativeServiceStatus(input, config) {
+  const healthRecord = isRecord3(input.health) ? input.health : {};
+  const healthReachable = readBoolean(healthRecord.reachable) ?? readBoolean(input.reachable) ?? false;
+  const healthOk = readBoolean(healthRecord.ok) ?? (typeof input.health === "boolean" ? input.health : undefined) ?? false;
+  const healthError = readString2(healthRecord.error) ?? readString2(input.healthError);
+  const healthTransport = readHealthTransport(healthRecord.transport) ?? readHealthTransport(input.healthTransport);
+  const healthNodeId = readString2(healthRecord.nodeId);
+  const healthMeshId = readString2(healthRecord.meshId);
+  const healthSocketFallbackError = readString2(healthRecord.socketFallbackError);
+  const healthCounts = isRecord3(healthRecord.counts) ? healthRecord.counts : undefined;
+  const installed = readBoolean(input.installed) ?? existsSync5(config.launchAgentPath);
+  const loaded = readBoolean(input.loaded) ?? false;
+  const stdoutLogPath = readString2(input.stdoutLogPath) ?? config.stdoutLogPath;
+  const stderrLogPath = readString2(input.stderrLogPath) ?? config.stderrLogPath;
+  const lastLogLine = readString2(input.lastLogLine) ?? (healthReachable ? readLastLogLine([stdoutLogPath, stderrLogPath]) : readLastLogLine([stderrLogPath, stdoutLogPath]));
+  return {
+    label: readString2(input.label) ?? config.label,
+    mode: readString2(input.mode) ?? config.mode,
+    launchAgentPath: readString2(input.launchAgentPath) ?? config.launchAgentPath,
+    bootoutCommand: readString2(input.bootoutCommand) ?? bootoutCommand(config),
+    brokerUrl: readString2(input.brokerUrl) ?? config.brokerUrl,
+    brokerSocketPath: readString2(input.brokerSocketPath) ?? config.brokerSocketPath,
+    supportDirectory: readString2(input.supportDirectory) ?? config.supportDirectory,
+    runtimeDirectory: readString2(input.runtimeDirectory) ?? config.runtimeDirectory,
+    controlHome: readString2(input.controlHome) ?? config.controlHome,
+    stdoutLogPath,
+    stderrLogPath,
+    installed,
+    loaded,
+    pid: readNumber2(input.pid) ?? null,
+    launchdState: readString2(input.launchdState) ?? null,
+    lastExitStatus: readNumber2(input.lastExitStatus) ?? null,
+    usesLaunchAgent: readBoolean(input.usesLaunchAgent) ?? (installed || loaded),
+    reachable: healthReachable,
+    serviceAdapter: "macos-scoutd",
+    health: {
+      reachable: healthReachable,
+      ok: healthOk,
+      checkedAt: readNumber2(healthRecord.checkedAt) ?? Date.now(),
+      transport: healthTransport,
+      socketPath: config.brokerSocketPath,
+      ...healthSocketFallbackError ? { socketFallbackError: healthSocketFallbackError } : {},
+      ...healthNodeId ? { nodeId: healthNodeId } : {},
+      ...healthMeshId ? { meshId: healthMeshId } : {},
+      ...healthCounts ? { counts: healthCounts } : {},
+      ...isRecord3(healthRecord.build) ? { build: healthRecord.build } : {},
+      ...isRecord3(healthRecord.services) ? { services: healthRecord.services } : {},
+      error: healthError
+    },
+    lastLogLine
   };
-  if (coreAgentsValue) {
-    envEntries["OPENSCOUT_CORE_AGENTS"] = coreAgentsValue;
-  }
-  const envBlock = Object.entries(envEntries).map(([key, value]) => `
-    <key>${xmlEscape(key)}</key>
-    <string>${xmlEscape(value)}</string>`).join("");
-  return `<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>Label</key>
-  <string>${xmlEscape(config.label)}</string>
-  <key>ProgramArguments</key>
-  <array>
-    <string>${xmlEscape(config.bunExecutable)}</string>
-    <string>${xmlEscape(join3(config.runtimePackageDir, "bin", "openscout-runtime.mjs"))}</string>
-    <string>base</string>
-  </array>
-  <key>WorkingDirectory</key>
-  <string>${xmlEscape(config.runtimePackageDir)}</string>
-  <key>RunAtLoad</key>
-  <true/>
-  <key>KeepAlive</key>
-  <dict>
-    <key>SuccessfulExit</key>
-    <false/>
-  </dict>
-  <key>StandardOutPath</key>
-  <string>${xmlEscape(config.stdoutLogPath)}</string>
-  <key>StandardErrorPath</key>
-  <string>${xmlEscape(config.stderrLogPath)}</string>
-  <key>EnvironmentVariables</key>
-  <dict>${envBlock}
-  </dict>
-</dict>
-</plist>
-`;
+}
+var SCOUTD_MAX_BUFFER = 2 * 1024 * 1024;
+var SCOUTD_DEFAULT_TIMEOUT_MS = 45000;
+var SCOUTD_KILL_GRACE_MS = 250;
+function spawnScoutdJson(scoutdPath, command, env, timeoutMs) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn2(scoutdPath, [command, "--json"], {
+      env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let timedOut = false;
+    const killTimer = setTimeout(() => {
+      timedOut = true;
+      terminate();
+      fail(new Error(`scoutd ${command} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    killTimer.unref?.();
+    function terminate() {
+      child.kill("SIGTERM");
+      const hardKillTimer = setTimeout(() => child.kill("SIGKILL"), SCOUTD_KILL_GRACE_MS);
+      hardKillTimer.unref?.();
+    }
+    function cleanup() {
+      clearTimeout(killTimer);
+    }
+    function fail(error) {
+      if (settled)
+        return;
+      settled = true;
+      cleanup();
+      reject(error);
+    }
+    function succeed(output) {
+      if (settled)
+        return;
+      settled = true;
+      cleanup();
+      resolvePromise(output);
+    }
+    function append(kind, chunk) {
+      const text = typeof chunk === "string" ? chunk : String(chunk);
+      if (kind === "stdout")
+        stdout += text;
+      else
+        stderr += text;
+      if (stdout.length + stderr.length > SCOUTD_MAX_BUFFER) {
+        terminate();
+        fail(new Error(`scoutd ${command} exceeded output limit`));
+      }
+    }
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => append("stdout", chunk));
+    child.stderr.on("data", (chunk) => append("stderr", chunk));
+    child.on("error", (error) => fail(new Error(`scoutd ${command} failed: ${error.message}`)));
+    child.on("close", (code, signal) => {
+      if (settled || timedOut)
+        return;
+      const trimmedStdout = stdout.trim();
+      const trimmedStderr = stderr.trim();
+      if ((code ?? 1) !== 0) {
+        const detail = trimmedStderr || trimmedStdout || `exit ${signal ?? code ?? "unknown status"}`;
+        fail(new Error(`scoutd ${command} failed: ${detail}`));
+        return;
+      }
+      succeed(trimmedStdout);
+    });
+  });
+}
+async function runScoutdServiceCommand(command, config, timeoutMs = SCOUTD_DEFAULT_TIMEOUT_MS, runScoutdJson = spawnScoutdJson) {
+  const scoutd = resolveScoutdCommand(config);
+  if (!scoutd) {
+    throw new Error("Unable to locate scoutd for broker service management. Build scoutd with `npm run scoutd:build`, install a package that includes scoutd, or set OPENSCOUT_SCOUTD_BIN.");
+  }
+  const stdout = await runScoutdJson(scoutd.path, command, nativeServiceEnvironment(config, scoutd.path), timeoutMs);
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    throw new Error(`scoutd ${command} returned non-JSON stdout: ${stdout.slice(0, 400)}`);
+  }
+  return normalizeNativeServiceStatus(parsed, config);
 }
 function readCoreAgentsSync() {
   try {
     const settingsPath = resolveOpenScoutSupportPaths().settingsPath;
-    const raw = readFileSync(settingsPath, "utf8");
+    const raw = readFileSync4(settingsPath, "utf8");
     const settings = JSON.parse(raw);
     const raw_agents = settings?.agents?.coreAgents;
     if (Array.isArray(raw_agents)) {
@@ -619,88 +2353,14 @@ function readCoreAgentsSync() {
   } catch {}
   return [];
 }
-function collectOptionalEnvVars(keys) {
-  const entries = {};
-  for (const key of keys) {
-    const value = process.env[key];
-    if (typeof value === "string" && value.trim().length > 0) {
-      entries[key] = value;
-    }
-  }
-  return entries;
-}
-function resolveLaunchAgentPATH() {
-  const entries = [
-    join3(homedir3(), ".bun", "bin"),
-    ...(process.env.PATH ?? "").split(":").filter(Boolean),
-    "/opt/homebrew/bin",
-    "/usr/local/bin",
-    "/usr/bin",
-    "/bin",
-    "/usr/sbin",
-    "/sbin"
-  ];
-  return Array.from(new Set(entries)).filter((e) => !isTmpPath(e)).join(":");
-}
-function xmlEscape(value) {
-  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
-}
-function ensureParentDirectory(filePath) {
-  mkdirSync2(dirname2(filePath), { recursive: true });
-}
-function ensureServiceDirectories(config) {
-  ensureOpenScoutCleanSlateSync();
-  mkdirSync2(config.supportDirectory, { recursive: true });
-  mkdirSync2(config.runtimeDirectory, { recursive: true, mode: 448 });
-  chmodSync(config.runtimeDirectory, 448);
-  mkdirSync2(config.logsDirectory, { recursive: true });
-  mkdirSync2(config.controlHome, { recursive: true });
-  ensureParentDirectory(config.launchAgentPath);
-}
-function writeLaunchAgentPlist(config) {
-  ensureServiceDirectories(config);
-  writeFileSync2(config.launchAgentPath, renderLaunchAgentPlist(config), "utf8");
-}
 function bootoutCommand(config) {
-  return `${launchctlPath()} bootout ${config.serviceTarget}`;
-}
-function legacyLaunchAgentPath(config) {
-  return join3(homedir3(), "Library", "LaunchAgents", `${legacyBrokerServiceLabel(config.mode)}.plist`);
-}
-function legacyServiceTarget(config) {
-  return `${config.domainTarget}/${legacyBrokerServiceLabel(config.mode)}`;
-}
-function bootoutLegacyBrokerService(config) {
-  const legacyTarget = legacyServiceTarget(config);
-  if (legacyTarget === config.serviceTarget) {
-    return;
-  }
-  runCommand(launchctlPath(), ["bootout", legacyTarget], { allowFailure: true });
-}
-function runCommand(command, args, options) {
-  const result = spawnSync(command, args, {
-    env: {
-      ...process.env,
-      ...options?.env ?? {}
-    },
-    encoding: "utf8"
-  });
-  const stdout = (result.stdout ?? "").trim();
-  const stderr = (result.stderr ?? "").trim();
-  const exitCode = result.status ?? 1;
-  if (exitCode !== 0 && !options?.allowFailure) {
-    throw new Error(stderr || stdout || `${command} exited with status ${exitCode}`);
-  }
-  return { exitCode, stdout, stderr };
-}
-function launchctlPath() {
-  return "/bin/launchctl";
+  return `/bin/launchctl bootout ${config.serviceTarget}`;
 }
 function readLogLines(path) {
-  if (!existsSync3(path)) {
+  if (!existsSync5(path)) {
     return [];
   }
-  return readFileSync(path, "utf8").split(`
+  return readFileSync4(path, "utf8").split(`
 `).map((line) => line.trim()).filter(Boolean);
 }
 function isPackageScriptBanner(line) {
@@ -733,170 +2393,120 @@ function readLastLogLine(paths) {
   }
   return fallback;
 }
-function parseLaunchctlPrint(output) {
-  const pidMatch = output.match(/\bpid = (\d+)/);
-  const stateMatch = output.match(/\bstate = ([^\n]+)/);
-  const lastExitMatch = output.match(/\blast exit code = (-?\d+)/i) || output.match(/\blast exit status = (-?\d+)/i);
+async function readHeadlessBrokerHealth(config) {
+  const result = await requestScoutBrokerJsonWithTrace(config.brokerUrl, "/health", { socketPath: config.brokerSocketPath });
   return {
-    pid: pidMatch ? Number.parseInt(pidMatch[1] ?? "0", 10) : null,
-    launchdState: stateMatch?.[1]?.trim() ?? null,
-    lastExitStatus: lastExitMatch ? Number.parseInt(lastExitMatch[1] ?? "0", 10) : null
+    health: result.value,
+    trace: result.trace
   };
 }
-function inspectLaunchctl(config) {
-  const printResult = runCommand(launchctlPath(), ["print", config.serviceTarget], { allowFailure: true });
-  if (printResult.exitCode !== 0) {
-    return {
-      loaded: false,
-      pid: null,
-      launchdState: null,
-      lastExitStatus: null,
-      raw: printResult.stderr || printResult.stdout
-    };
-  }
-  return {
-    loaded: true,
-    raw: printResult.stdout,
-    ...parseLaunchctlPrint(printResult.stdout)
-  };
+function headlessLifecycleError(command) {
+  return new Error(`Next step: run \`openscout-runtime broker\` in this shell or under your process manager. ` + `The headless service adapter leaves broker ${command} to that foreground process.`);
 }
-async function fetchHealthSnapshot(config) {
-  const controller = new AbortController;
-  const timeout = setTimeout(() => controller.abort(), 1000);
+async function runHeadlessForegroundServiceCommand(command, config, readHealth = readHeadlessBrokerHealth) {
+  if (command !== "status") {
+    throw headlessLifecycleError(command);
+  }
   const checkedAt = Date.now();
   try {
-    const { value: payload, trace } = await requestScoutBrokerJsonWithTrace(config.brokerUrl, "/health", {
-      signal: controller.signal,
-      socketPath: config.brokerSocketPath
-    });
+    const { health, trace } = await readHealth(config);
+    const reachable = true;
     return {
-      reachable: true,
-      ok: Boolean(payload.ok),
-      checkedAt,
-      transport: trace.transport,
-      socketPath: trace.socketPath,
-      socketFallbackError: trace.socketFallbackError,
-      nodeId: payload.nodeId,
-      meshId: payload.meshId,
-      counts: payload.counts ? {
-        nodes: payload.counts.nodes ?? 0,
-        actors: payload.counts.actors ?? 0,
-        agents: payload.counts.agents ?? 0,
-        agentRecords: payload.counts.agentRecords,
-        rawAgentRecords: payload.counts.rawAgentRecords,
-        configuredAgents: payload.counts.configuredAgents,
-        scoutManagedAgents: payload.counts.scoutManagedAgents,
-        currentAgentRegistrations: payload.counts.currentAgentRegistrations,
-        localAgentRegistrations: payload.counts.localAgentRegistrations,
-        remoteAgentRegistrations: payload.counts.remoteAgentRegistrations,
-        staleAgentRegistrations: payload.counts.staleAgentRegistrations,
-        retiredAgentRegistrations: payload.counts.retiredAgentRegistrations,
-        oneTimeAgentCards: payload.counts.oneTimeAgentCards,
-        persistentAgentCards: payload.counts.persistentAgentCards,
-        conversations: payload.counts.conversations ?? 0,
-        messages: payload.counts.messages ?? 0,
-        flights: payload.counts.flights ?? 0,
-        collaborationRecords: payload.counts.collaborationRecords ?? 0
-      } : undefined
+      serviceAdapter: "headless-foreground",
+      label: config.label,
+      mode: config.mode,
+      launchAgentPath: config.launchAgentPath,
+      bootoutCommand: "headless-foreground does not use launchd",
+      brokerUrl: config.brokerUrl,
+      brokerSocketPath: config.brokerSocketPath,
+      supportDirectory: config.supportDirectory,
+      runtimeDirectory: config.runtimeDirectory,
+      controlHome: config.controlHome,
+      stdoutLogPath: config.stdoutLogPath,
+      stderrLogPath: config.stderrLogPath,
+      installed: false,
+      loaded: reachable,
+      pid: null,
+      launchdState: null,
+      lastExitStatus: null,
+      usesLaunchAgent: false,
+      reachable,
+      health: {
+        reachable,
+        ok: Boolean(health.ok),
+        checkedAt,
+        transport: trace.transport,
+        socketPath: trace.socketPath,
+        socketFallbackError: trace.socketFallbackError,
+        nodeId: health.nodeId ?? undefined,
+        meshId: health.meshId ?? undefined,
+        counts: health.counts ?? undefined,
+        build: health.build,
+        services: health.services
+      },
+      lastLogLine: readLastLogLine([config.stderrLogPath, config.stdoutLogPath])
     };
   } catch (error) {
     return {
+      serviceAdapter: "headless-foreground",
+      label: config.label,
+      mode: config.mode,
+      launchAgentPath: config.launchAgentPath,
+      bootoutCommand: "headless-foreground does not use launchd",
+      brokerUrl: config.brokerUrl,
+      brokerSocketPath: config.brokerSocketPath,
+      supportDirectory: config.supportDirectory,
+      runtimeDirectory: config.runtimeDirectory,
+      controlHome: config.controlHome,
+      stdoutLogPath: config.stdoutLogPath,
+      stderrLogPath: config.stderrLogPath,
+      installed: false,
+      loaded: false,
+      pid: null,
+      launchdState: null,
+      lastExitStatus: null,
+      usesLaunchAgent: false,
       reachable: false,
-      ok: false,
-      checkedAt,
-      socketPath: config.brokerSocketPath,
-      error: error instanceof Error ? error.message : String(error)
+      health: {
+        reachable: false,
+        ok: false,
+        checkedAt,
+        error: error instanceof Error ? error.message : String(error)
+      },
+      lastLogLine: readLastLogLine([config.stderrLogPath, config.stdoutLogPath])
     };
-  } finally {
-    clearTimeout(timeout);
+  }
+}
+async function runBrokerServiceCommand(command, config) {
+  const adapter = resolveBrokerServiceAdapter();
+  switch (adapter) {
+    case "macos-scoutd":
+      return await runScoutdServiceCommand(command, config);
+    case "headless-foreground":
+      return await runHeadlessForegroundServiceCommand(command, config);
+    case "linux-systemd-user":
+      throw new Error("The linux-systemd-user service adapter is not implemented yet. " + "Use OPENSCOUT_SERVICE_ADAPTER=headless-foreground and run `openscout-runtime broker` under your process manager.");
+    case "windows-service":
+      throw new Error("The windows-service adapter is not implemented yet. " + "Use OPENSCOUT_SERVICE_ADAPTER=headless-foreground and run `openscout-runtime broker` from a shell.");
   }
 }
 async function brokerServiceStatus(config = resolveBrokerServiceConfig()) {
-  ensureServiceDirectories(config);
-  const launchctl = inspectLaunchctl(config);
-  const health = await fetchHealthSnapshot(config);
-  const installed = existsSync3(config.launchAgentPath);
-  const lastLogLine = health.reachable ? readLastLogLine([config.stdoutLogPath, config.stderrLogPath]) : readLastLogLine([config.stderrLogPath, config.stdoutLogPath]);
-  return {
-    label: config.label,
-    mode: config.mode,
-    launchAgentPath: config.launchAgentPath,
-    bootoutCommand: bootoutCommand(config),
-    brokerUrl: config.brokerUrl,
-    brokerSocketPath: config.brokerSocketPath,
-    supportDirectory: config.supportDirectory,
-    runtimeDirectory: config.runtimeDirectory,
-    controlHome: config.controlHome,
-    stdoutLogPath: config.stdoutLogPath,
-    stderrLogPath: config.stderrLogPath,
-    installed,
-    loaded: launchctl.loaded,
-    pid: launchctl.pid,
-    launchdState: launchctl.launchdState,
-    lastExitStatus: launchctl.lastExitStatus,
-    usesLaunchAgent: installed || launchctl.loaded,
-    reachable: health.reachable,
-    health,
-    lastLogLine
-  };
+  return runBrokerServiceCommand("status", config);
 }
 async function installBrokerService(config = resolveBrokerServiceConfig()) {
-  bootoutLegacyBrokerService(config);
-  writeLaunchAgentPlist(config);
-  return brokerServiceStatus(config);
+  return runBrokerServiceCommand("install", config);
 }
 async function startBrokerService(config = resolveBrokerServiceConfig()) {
-  bootoutLegacyBrokerService(config);
-  writeLaunchAgentPlist(config);
-  runCommand(launchctlPath(), ["bootout", config.serviceTarget], { allowFailure: true });
-  await waitForBrokerServiceStopped(config);
-  runCommand(launchctlPath(), ["bootstrap", config.domainTarget, config.launchAgentPath], { allowFailure: true });
-  runCommand(launchctlPath(), ["kickstart", "-k", config.serviceTarget], { allowFailure: true });
-  const attempts = Math.ceil(resolveBrokerStartTimeoutMs() / BROKER_SERVICE_POLL_INTERVAL_MS);
-  for (let attempt = 0;attempt < attempts; attempt += 1) {
-    const status2 = await brokerServiceStatus(config);
-    if (status2.health.reachable) {
-      return status2;
-    }
-    await sleep(BROKER_SERVICE_POLL_INTERVAL_MS);
-  }
-  const status = await brokerServiceStatus(config);
-  throw new Error(status.lastLogLine ?? status.health.error ?? "Broker service did not become healthy.");
-}
-function sleep(ms) {
-  return new Promise((resolve3) => setTimeout(resolve3, ms));
-}
-async function waitForBrokerServiceStopped(config) {
-  let status = await brokerServiceStatus(config);
-  const attempts = Math.ceil(resolveBrokerStopTimeoutMs() / BROKER_SERVICE_POLL_INTERVAL_MS);
-  for (let attempt = 0;attempt < attempts; attempt += 1) {
-    status = await brokerServiceStatus(config);
-    if (!status.loaded && !status.health.reachable) {
-      return status;
-    }
-    await sleep(BROKER_SERVICE_POLL_INTERVAL_MS);
-  }
-  return status;
+  return runBrokerServiceCommand("start", config);
 }
 async function stopBrokerService(config = resolveBrokerServiceConfig()) {
-  runCommand(launchctlPath(), ["bootout", config.serviceTarget], { allowFailure: true });
-  return waitForBrokerServiceStopped(config);
+  return runBrokerServiceCommand("stop", config);
 }
 async function restartBrokerService(config = resolveBrokerServiceConfig()) {
-  await stopBrokerService(config);
-  return startBrokerService(config);
+  return runBrokerServiceCommand("restart", config);
 }
 async function uninstallBrokerService(config = resolveBrokerServiceConfig()) {
-  await stopBrokerService(config);
-  if (existsSync3(config.launchAgentPath)) {
-    rmSync2(config.launchAgentPath, { force: true });
-  }
-  const legacyPath = legacyLaunchAgentPath(config);
-  bootoutLegacyBrokerService(config);
-  if (existsSync3(legacyPath)) {
-    rmSync2(legacyPath, { force: true });
-  }
-  return brokerServiceStatus(config);
+  return runBrokerServiceCommand("uninstall", config);
 }
 async function main() {
   const command = process.argv[2] ?? "status";
@@ -934,6 +2544,7 @@ async function main() {
 }
 function formatBrokerServiceStatus(status) {
   const lines = [
+    `service adapter: ${status.serviceAdapter ?? "unknown"}`,
     `label: ${status.label}`,
     `mode: ${status.mode}`,
     `launch agent: ${status.installed ? status.launchAgentPath : "not installed"}`,
@@ -968,15 +2579,21 @@ export {
   stopBrokerService,
   startBrokerService,
   selectLastRelevantLogLine,
+  runScoutdServiceCommand,
+  runHeadlessForegroundServiceCommand,
   restartBrokerService,
+  resolveScoutdCommand,
+  resolveScoutBrokerControlUrl,
+  resolveBundledRuntimeDirFromModuleDir,
+  resolveBrokerUrl,
   resolveBrokerSocketPathForBaseUrl,
   resolveBrokerServiceConfig,
+  resolveBrokerServiceAdapter,
   resolveBrokerHost,
   resolveAdvertiseScope,
-  renderLaunchAgentPlist,
-  parseLaunchctlPrint,
   isLoopbackHost,
   installBrokerService,
+  buildLocalBrokerControlUrl,
   buildDefaultBrokerUrl,
   buildDefaultBrokerSocketPath,
   brokerServiceStatus,