claudemesh-cli 1.27.1 → 1.27.3

package/dist/entrypoints/cli.js

@@ -103,7 +103,7 @@ __export(exports_urls, {
   VERSION: () => VERSION,
   URLS: () => URLS
 });
-var URLS, VERSION = "1.27.1", env;
+var URLS, VERSION = "1.27.3", env;
 var init_urls = __esm(() => {
   URLS = {
     BROKER: process.env.CLAUDEMESH_BROKER_URL ?? "wss://ic.claudemesh.com/ws",
@@ -3588,12 +3588,6 @@ var init_spinner = __esm(() => {
 });
 
 // src/daemon/paths.ts
-var exports_paths = {};
-__export(exports_paths, {
-  DAEMON_TCP_HOST: () => DAEMON_TCP_HOST,
-  DAEMON_TCP_DEFAULT_PORT: () => DAEMON_TCP_DEFAULT_PORT,
-  DAEMON_PATHS: () => DAEMON_PATHS
-});
 import { join as join3 } from "node:path";
 var DAEMON_PATHS, DAEMON_TCP_HOST = "127.0.0.1", DAEMON_TCP_DEFAULT_PORT = 47823;
 var init_paths2 = __esm(() => {
@@ -3623,6 +3617,255 @@ var init_paths2 = __esm(() => {
   };
 });
 
+// src/daemon/local-token.ts
+import { mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { dirname as dirname2 } from "node:path";
+import { randomBytes as randomBytes4 } from "node:crypto";
+function readLocalToken() {
+  try {
+    return readFileSync4(DAEMON_PATHS.TOKEN_FILE, "utf8").trim();
+  } catch {
+    return null;
+  }
+}
+function ensureLocalToken() {
+  const existing = readLocalToken();
+  if (existing)
+    return existing;
+  mkdirSync3(dirname2(DAEMON_PATHS.TOKEN_FILE), { recursive: true, mode: 448 });
+  const tok = randomBytes4(32).toString("base64url");
+  writeFileSync4(DAEMON_PATHS.TOKEN_FILE, tok + `
+`, { mode: 384 });
+  return tok;
+}
+var init_local_token = __esm(() => {
+  init_paths2();
+});
+
+// src/daemon/ipc/client.ts
+import { request as httpRequest } from "node:http";
+async function ipc(opts) {
+  const useTcp = !!opts.preferTcp;
+  const headers = {
+    accept: "application/json",
+    host: "localhost"
+  };
+  let bodyBuf;
+  if (opts.body !== undefined) {
+    bodyBuf = Buffer.from(JSON.stringify(opts.body), "utf8");
+    headers["content-type"] = "application/json";
+    headers["content-length"] = String(bodyBuf.length);
+  }
+  if (useTcp) {
+    const tok = readLocalToken();
+    if (!tok)
+      throw new IpcError(0, null, "daemon local token not found; is the daemon running?");
+    headers.authorization = `Bearer ${tok}`;
+  }
+  return new Promise((resolve, reject) => {
+    const req = httpRequest(useTcp ? { host: DAEMON_TCP_HOST, port: DAEMON_TCP_DEFAULT_PORT, path: opts.path, method: opts.method ?? "GET", headers } : { socketPath: DAEMON_PATHS.SOCK_FILE, path: opts.path, method: opts.method ?? "GET", headers }, (res) => {
+      const chunks = [];
+      res.on("data", (c) => chunks.push(c));
+      res.on("end", () => {
+        const raw = Buffer.concat(chunks).toString("utf8");
+        let parsed = raw;
+        try {
+          parsed = raw.length > 0 ? JSON.parse(raw) : null;
+        } catch {}
+        resolve({ status: res.statusCode ?? 0, body: parsed });
+      });
+    });
+    req.setTimeout(opts.timeoutMs ?? 5000, () => req.destroy(new Error("ipc_timeout")));
+    req.on("error", (err) => reject(err));
+    if (bodyBuf)
+      req.write(bodyBuf);
+    req.end();
+  });
+}
+var IpcError;
+var init_client3 = __esm(() => {
+  init_paths2();
+  init_local_token();
+  IpcError = class IpcError extends Error {
+    status;
+    payload;
+    constructor(status, payload, msg) {
+      super(msg);
+      this.status = status;
+      this.payload = payload;
+    }
+  };
+});
+
+// src/services/daemon/lifecycle.ts
+var exports_lifecycle = {};
+__export(exports_lifecycle, {
+  ensureDaemonReady: () => ensureDaemonReady,
+  _resetDaemonReadyCache: () => _resetDaemonReadyCache
+});
+import { existsSync as existsSync5, readFileSync as readFileSync5, statSync, unlinkSync as unlinkSync2, writeFileSync as writeFileSync5 } from "node:fs";
+import { join as join4 } from "node:path";
+async function ensureDaemonReady(opts = {}) {
+  if (lastResultThisProcess && (lastResultThisProcess.state === "up" || lastResultThisProcess.state === "started")) {
+    return lastResultThisProcess;
+  }
+  if (process.env.CLAUDEMESH_INTERNAL_NO_AUTOSPAWN === "1") {
+    opts = { ...opts, noAutoSpawn: true };
+  }
+  const result = await runEnsureDaemon(opts);
+  lastResultThisProcess = result;
+  return result;
+}
+function _resetDaemonReadyCache() {
+  lastResultThisProcess = null;
+}
+async function runEnsureDaemon(opts) {
+  const t0 = Date.now();
+  const probe = await probeDaemon();
+  if (probe === "up")
+    return { state: "up", durationMs: Date.now() - t0 };
+  if (probe === "stale")
+    cleanupStaleFiles();
+  if (opts.noAutoSpawn) {
+    return { state: "down", durationMs: Date.now() - t0, reason: "auto-spawn disabled" };
+  }
+  if (recentSpawnFailureFresh()) {
+    return {
+      state: "spawn-suppressed",
+      durationMs: Date.now() - t0,
+      reason: `daemon failed to start within last ${Math.round(SPAWN_FAIL_TTL_MS / 1000)}s`
+    };
+  }
+  const spawnRes = await spawnDaemon(opts);
+  if (spawnRes.ok) {
+    return { state: "started", durationMs: Date.now() - t0 };
+  }
+  markSpawnFailure();
+  return { state: "spawn-failed", durationMs: Date.now() - t0, reason: spawnRes.reason };
+}
+async function probeDaemon() {
+  if (!existsSync5(DAEMON_PATHS.SOCK_FILE))
+    return "absent";
+  try {
+    const res = await ipc({ path: "/v1/version", timeoutMs: PROBE_TIMEOUT_MS });
+    if (res.status === 200)
+      return "up";
+    return "stale";
+  } catch (err) {
+    if (err instanceof IpcError)
+      return "stale";
+    const msg = String(err);
+    if (/ENOENT|ECONNREFUSED|ipc_timeout|EPIPE|ECONNRESET/.test(msg))
+      return "stale";
+    return "stale";
+  }
+}
+function cleanupStaleFiles() {
+  for (const p of [DAEMON_PATHS.SOCK_FILE, DAEMON_PATHS.PID_FILE]) {
+    try {
+      unlinkSync2(p);
+    } catch {}
+  }
+}
+function recentSpawnFailureFresh() {
+  try {
+    const st = statSync(SPAWN_FAIL_FILE());
+    return Date.now() - st.mtimeMs < SPAWN_FAIL_TTL_MS;
+  } catch {
+    return false;
+  }
+}
+function markSpawnFailure() {
+  try {
+    writeFileSync5(SPAWN_FAIL_FILE(), String(Date.now()), { mode: 384 });
+  } catch {}
+}
+function clearSpawnFailure() {
+  try {
+    unlinkSync2(SPAWN_FAIL_FILE());
+  } catch {}
+}
+async function spawnDaemon(opts) {
+  const lockResult = await acquireOrShareLock(opts);
+  if (lockResult === "wait-existing") {
+    return await pollForSocket(opts.budgetMs ?? 3000);
+  }
+  try {
+    const { spawn } = await import("node:child_process");
+    const binary = await resolveCliBinary();
+    const args = ["daemon", "up"];
+    if (opts.mesh)
+      args.push("--mesh", opts.mesh);
+    const child = spawn(binary, args, {
+      detached: true,
+      stdio: "ignore",
+      env: { ...process.env, CLAUDEMESH_INTERNAL_NO_AUTOSPAWN: "1" }
+    });
+    child.unref();
+    const polled = await pollForSocket(opts.budgetMs ?? 3000);
+    if (polled.ok)
+      clearSpawnFailure();
+    return polled;
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+  } finally {
+    releaseLock();
+  }
+}
+async function acquireOrShareLock(_opts) {
+  const lockPath = SPAWN_LOCK_FILE();
+  if (existsSync5(lockPath)) {
+    try {
+      const pidStr = readFileSync5(lockPath, "utf8").trim();
+      const pid = Number.parseInt(pidStr, 10);
+      if (Number.isFinite(pid) && pid > 0) {
+        try {
+          process.kill(pid, 0);
+          return "wait-existing";
+        } catch {}
+      }
+    } catch {}
+  }
+  try {
+    writeFileSync5(lockPath, String(process.pid), { mode: 384 });
+  } catch {}
+  return "acquired";
+}
+function releaseLock() {
+  try {
+    unlinkSync2(SPAWN_LOCK_FILE());
+  } catch {}
+}
+async function pollForSocket(budgetMs) {
+  const start = Date.now();
+  while (Date.now() - start < budgetMs) {
+    if (existsSync5(DAEMON_PATHS.SOCK_FILE)) {
+      const probe = await probeDaemon();
+      if (probe === "up")
+        return { ok: true };
+    }
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  return { ok: false, reason: `socket did not appear within ${budgetMs}ms` };
+}
+async function resolveCliBinary() {
+  const argv1 = process.argv[1] ?? "claudemesh";
+  if (/\.ts$/.test(argv1) || /node_modules|src\/entrypoints/.test(argv1)) {
+    try {
+      const { execSync } = await import("node:child_process");
+      return execSync("which claudemesh", { encoding: "utf8" }).trim() || "claudemesh";
+    } catch {
+      return "claudemesh";
+    }
+  }
+  return argv1;
+}
+var SPAWN_LOCK_FILE = () => join4(DAEMON_PATHS.DAEMON_DIR, ".spawn.lock"), SPAWN_FAIL_FILE = () => join4(DAEMON_PATHS.DAEMON_DIR, ".spawn-failure"), SPAWN_FAIL_TTL_MS = 30000, PROBE_TIMEOUT_MS = 800, lastResultThisProcess = null;
+var init_lifecycle = __esm(() => {
+  init_client3();
+  init_paths2();
+});
+
 // src/commands/launch.ts
 var exports_launch = {};
 __export(exports_launch, {
@@ -3630,42 +3873,26 @@ __export(exports_launch, {
 });
 import { spawnSync as spawnSync2 } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { mkdtempSync, writeFileSync as writeFileSync4, rmSync, readdirSync, statSync, existsSync as existsSync5, readFileSync as readFileSync4 } from "node:fs";
+import { mkdtempSync, writeFileSync as writeFileSync6, rmSync, readdirSync, statSync as statSync2, existsSync as existsSync6, readFileSync as readFileSync6 } from "node:fs";
 import { tmpdir, hostname as hostname2, homedir as homedir3 } from "node:os";
-import { join as join4 } from "node:path";
+import { join as join5 } from "node:path";
 import { createInterface as createInterface4 } from "node:readline";
 async function ensureDaemonRunning(meshSlug, quiet) {
-  const { DAEMON_PATHS: DAEMON_PATHS2 } = await Promise.resolve().then(() => (init_paths2(), exports_paths));
-  if (existsSync5(DAEMON_PATHS2.SOCK_FILE))
-    return;
+  const { ensureDaemonReady: ensureDaemonReady2 } = await Promise.resolve().then(() => (init_lifecycle(), exports_lifecycle));
   if (!quiet)
-    render.info("starting claudemesh daemon…");
-  const { spawn } = await import("node:child_process");
-  const argv0 = process.argv[1] ?? "claudemesh";
-  let binary = argv0;
-  if (/\.ts$/.test(binary) || /node_modules|src\/entrypoints/.test(binary)) {
-    try {
-      const { execSync } = await import("node:child_process");
-      binary = execSync("which claudemesh", { encoding: "utf8" }).trim();
-    } catch {
-      binary = "claudemesh";
-    }
+    render.info("ensuring claudemesh daemon is running…");
+  const res = await ensureDaemonReady2({ budgetMs: 1e4, mesh: meshSlug });
+  if (res.state === "up") {
+    if (!quiet)
+      render.ok("daemon already running");
+    return;
   }
-  const child = spawn(binary, ["daemon", "up", "--mesh", meshSlug], {
-    detached: true,
-    stdio: "ignore"
-  });
-  child.unref();
-  const start = Date.now();
-  while (Date.now() - start < 1e4) {
-    if (existsSync5(DAEMON_PATHS2.SOCK_FILE)) {
-      if (!quiet)
-        render.ok("daemon ready");
-      return;
-    }
-    await new Promise((r) => setTimeout(r, 200));
+  if (res.state === "started") {
+    if (!quiet)
+      render.ok(`daemon ready (${res.durationMs}ms)`);
+    return;
   }
-  render.warn("daemon failed to start within 10s", "Run `claudemesh daemon up --mesh " + meshSlug + "` manually, then re-launch.");
+  render.warn(`daemon ${res.state}${res.reason ? `: ${res.reason}` : ""}`, "Run `claudemesh daemon up --mesh " + meshSlug + "` manually, then re-launch.");
 }
 function parseGroupsString(raw) {
   return raw.split(",").map((s) => s.trim()).filter(Boolean).map((token) => {
@@ -3986,17 +4213,17 @@ async function runLaunch(flags, rawArgs) {
     for (const entry of readdirSync(tmpBase)) {
       if (!entry.startsWith("claudemesh-"))
         continue;
-      const full = join4(tmpBase, entry);
-      const age = Date.now() - statSync(full).mtimeMs;
+      const full = join5(tmpBase, entry);
+      const age = Date.now() - statSync2(full).mtimeMs;
       if (age > 3600000)
         rmSync(full, { recursive: true, force: true });
     }
   } catch {}
   await ensureDaemonRunning(mesh.slug, args.quiet);
   try {
-    const claudeConfigPath = join4(homedir3(), ".claude.json");
-    if (existsSync5(claudeConfigPath)) {
-      const claudeConfig = JSON.parse(readFileSync4(claudeConfigPath, "utf-8"));
+    const claudeConfigPath = join5(homedir3(), ".claude.json");
+    if (existsSync6(claudeConfigPath)) {
+      const claudeConfig = JSON.parse(readFileSync6(claudeConfigPath, "utf-8"));
       const mcpServers = claudeConfig.mcpServers ?? {};
       let cleaned = 0;
       for (const key of Object.keys(mcpServers)) {
@@ -4014,7 +4241,7 @@ async function runLaunch(flags, rawArgs) {
       }
       if (cleaned > 0) {
         claudeConfig.mcpServers = mcpServers;
-        writeFileSync4(claudeConfigPath, JSON.stringify(claudeConfig, null, 2) + `
+        writeFileSync6(claudeConfigPath, JSON.stringify(claudeConfig, null, 2) + `
 `, "utf-8");
       }
     }
@@ -4031,7 +4258,7 @@ async function runLaunch(flags, rawArgs) {
       console.log("  (Could not fetch service catalog — mesh services won't be natively available)");
     }
   }
-  const tmpDir = mkdtempSync(join4(tmpdir(), "claudemesh-"));
+  const tmpDir = mkdtempSync(join5(tmpdir(), "claudemesh-"));
   const sessionConfig = {
     version: 1,
     meshes: [mesh],
@@ -4040,17 +4267,17 @@ async function runLaunch(flags, rawArgs) {
     ...parsedGroups.length > 0 ? { groups: parsedGroups } : {},
     messageMode
   };
-  writeFileSync4(join4(tmpDir, "config.json"), JSON.stringify(sessionConfig, null, 2) + `
+  writeFileSync6(join5(tmpDir, "config.json"), JSON.stringify(sessionConfig, null, 2) + `
 `, "utf-8");
   if (!args.quiet) {
     printBanner(displayName, mesh.slug, role, parsedGroups, messageMode);
   }
   const meshMcpEntries = [];
   if (serviceCatalog.length > 0) {
-    const claudeConfigPath = join4(homedir3(), ".claude.json");
+    const claudeConfigPath = join5(homedir3(), ".claude.json");
     let claudeConfig = {};
     try {
-      claudeConfig = JSON.parse(readFileSync4(claudeConfigPath, "utf-8"));
+      claudeConfig = JSON.parse(readFileSync6(claudeConfigPath, "utf-8"));
     } catch {
       claudeConfig = {};
     }
@@ -4077,7 +4304,7 @@ async function runLaunch(flags, rawArgs) {
       meshMcpEntries.push({ key: entryKey, entry });
     }
     claudeConfig.mcpServers = mcpServers;
-    writeFileSync4(claudeConfigPath, JSON.stringify(claudeConfig, null, 2) + `
+    writeFileSync6(claudeConfigPath, JSON.stringify(claudeConfig, null, 2) + `
 `, "utf-8");
     if (!args.quiet && meshMcpEntries.length > 0) {
       console.log(`  ${meshMcpEntries.length} mesh service(s) registered as native MCPs:`);
@@ -4114,12 +4341,12 @@ async function runLaunch(flags, rawArgs) {
   let claudeBin = "claude";
   if (!isWindows2) {
     const candidates = [
-      join4(homedir3(), ".local", "bin", "claude"),
+      join5(homedir3(), ".local", "bin", "claude"),
       "/usr/local/bin/claude",
-      join4(homedir3(), ".claude", "bin", "claude")
+      join5(homedir3(), ".claude", "bin", "claude")
     ];
     for (const c of candidates) {
-      if (existsSync5(c)) {
+      if (existsSync6(c)) {
         claudeBin = c;
         break;
       }
@@ -4128,14 +4355,14 @@ async function runLaunch(flags, rawArgs) {
   const cleanup = () => {
     if (meshMcpEntries.length > 0) {
       try {
-        const claudeConfigPath = join4(homedir3(), ".claude.json");
-        const claudeConfig = JSON.parse(readFileSync4(claudeConfigPath, "utf-8"));
+        const claudeConfigPath = join5(homedir3(), ".claude.json");
+        const claudeConfig = JSON.parse(readFileSync6(claudeConfigPath, "utf-8"));
         const mcpServers = claudeConfig.mcpServers ?? {};
         for (const { key } of meshMcpEntries) {
           delete mcpServers[key];
         }
         claudeConfig.mcpServers = mcpServers;
-        writeFileSync4(claudeConfigPath, JSON.stringify(claudeConfig, null, 2) + `
+        writeFileSync6(claudeConfigPath, JSON.stringify(claudeConfig, null, 2) + `
 `, "utf-8");
       } catch {}
     }
@@ -4832,8 +5059,8 @@ __export(exports_join, {
   runJoin: () => runJoin
 });
 import sodium3 from "libsodium-wrappers";
-import { writeFileSync as writeFileSync5, mkdirSync as mkdirSync3 } from "node:fs";
-import { join as join5, dirname as dirname2 } from "node:path";
+import { writeFileSync as writeFileSync7, mkdirSync as mkdirSync4 } from "node:fs";
+import { join as join6, dirname as dirname3 } from "node:path";
 import { homedir as homedir4, hostname as hostname3 } from "node:os";
 function deriveAppBaseUrl() {
   const override = process.env.CLAUDEMESH_APP_URL;
@@ -4953,11 +5180,11 @@ async function runJoin(args) {
     joinedAt: new Date().toISOString()
   });
   writeConfig(config);
-  const configDir = env.CLAUDEMESH_CONFIG_DIR ?? join5(homedir4(), ".claudemesh");
-  const inviteFile = join5(configDir, `invite-${payload.mesh_slug}.txt`);
+  const configDir = env.CLAUDEMESH_CONFIG_DIR ?? join6(homedir4(), ".claudemesh");
+  const inviteFile = join6(configDir, `invite-${payload.mesh_slug}.txt`);
   try {
-    mkdirSync3(dirname2(inviteFile), { recursive: true });
-    writeFileSync5(inviteFile, link, "utf-8");
+    mkdirSync4(dirname3(inviteFile), { recursive: true });
+    writeFileSync7(inviteFile, link, "utf-8");
   } catch {}
   console.log("");
   console.log(`✓ Joined "${payload.mesh_slug}" as ${displayName}${enroll.alreadyMember ? " (already a member — re-enrolled with same pubkey)" : ""}`);
@@ -7160,9 +7387,9 @@ var init_ban = __esm(() => {
 
 // src/services/bridge/protocol.ts
 import { homedir as homedir5 } from "node:os";
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 function socketPath(meshSlug) {
-  return join6(homedir5(), ".claudemesh", "sockets", `${meshSlug}.sock`);
+  return join7(homedir5(), ".claudemesh", "sockets", `${meshSlug}.sock`);
 }
 function frame(obj) {
   return JSON.stringify(obj) + `
@@ -7189,11 +7416,11 @@ var init_protocol = () => {};
 
 // src/services/bridge/client.ts
 import { createConnection } from "node:net";
-import { existsSync as existsSync6 } from "node:fs";
+import { existsSync as existsSync7 } from "node:fs";
 import { randomUUID as randomUUID2 } from "node:crypto";
 async function tryBridge(meshSlug, verb, args = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
   const path = socketPath(meshSlug);
-  if (!existsSync6(path))
+  if (!existsSync7(path))
     return null;
   return new Promise((resolve) => {
     const id = randomUUID2();
@@ -7255,88 +7482,44 @@ async function tryBridge(meshSlug, verb, args = {}, timeoutMs = DEFAULT_TIMEOUT_
   });
 }
 var DEFAULT_TIMEOUT_MS = 5000;
-var init_client3 = __esm(() => {
+var init_client4 = __esm(() => {
   init_protocol();
 });
 
-// src/daemon/local-token.ts
-import { mkdirSync as mkdirSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync6 } from "node:fs";
-import { dirname as dirname3 } from "node:path";
-import { randomBytes as randomBytes4 } from "node:crypto";
-function readLocalToken() {
-  try {
-    return readFileSync5(DAEMON_PATHS.TOKEN_FILE, "utf8").trim();
-  } catch {
-    return null;
-  }
-}
-function ensureLocalToken() {
-  const existing = readLocalToken();
-  if (existing)
-    return existing;
-  mkdirSync4(dirname3(DAEMON_PATHS.TOKEN_FILE), { recursive: true, mode: 448 });
-  const tok = randomBytes4(32).toString("base64url");
-  writeFileSync6(DAEMON_PATHS.TOKEN_FILE, tok + `
-`, { mode: 384 });
-  return tok;
-}
-var init_local_token = __esm(() => {
-  init_paths2();
-});
-
-// src/daemon/ipc/client.ts
-import { request as httpRequest } from "node:http";
-async function ipc(opts) {
-  const useTcp = !!opts.preferTcp;
-  const headers = {
-    accept: "application/json",
-    host: "localhost"
-  };
-  let bodyBuf;
-  if (opts.body !== undefined) {
-    bodyBuf = Buffer.from(JSON.stringify(opts.body), "utf8");
-    headers["content-type"] = "application/json";
-    headers["content-length"] = String(bodyBuf.length);
-  }
-  if (useTcp) {
-    const tok = readLocalToken();
-    if (!tok)
-      throw new IpcError(0, null, "daemon local token not found; is the daemon running?");
-    headers.authorization = `Bearer ${tok}`;
+// src/ui/warnings.ts
+function warnDaemonState(res, opts = {}) {
+  if (alreadyWarned)
+    return false;
+  if (opts.quiet || opts.json)
+    return false;
+  if (res.state === "up")
+    return false;
+  alreadyWarned = true;
+  const tag = (label) => `[claudemesh] ${label}`;
+  const hint = (s) => dim(s);
+  switch (res.state) {
+    case "started":
+      process.stderr.write(`${tag("info")} daemon restarted automatically ${hint(`(took ${res.durationMs}ms)`)}
+`);
+      return true;
+    case "down":
+      process.stderr.write(`${tag("info")} daemon not running — using cold path ${hint("(slower; run `claudemesh daemon up` for warm path)")}
+`);
+      return true;
+    case "spawn-suppressed":
+      process.stderr.write(`${tag("warn")} ${res.reason ?? "daemon failed to start recently"} — using cold path ${hint("(run `claudemesh doctor`)")}
+`);
+      return true;
+    case "spawn-failed":
+      process.stderr.write(`${tag("warn")} daemon spawn failed${res.reason ? `: ${res.reason}` : ""} — using cold path ${hint("(check ~/.claudemesh/daemon/daemon.log)")}
+`);
+      return true;
   }
-  return new Promise((resolve, reject) => {
-    const req = httpRequest(useTcp ? { host: DAEMON_TCP_HOST, port: DAEMON_TCP_DEFAULT_PORT, path: opts.path, method: opts.method ?? "GET", headers } : { socketPath: DAEMON_PATHS.SOCK_FILE, path: opts.path, method: opts.method ?? "GET", headers }, (res) => {
-      const chunks = [];
-      res.on("data", (c) => chunks.push(c));
-      res.on("end", () => {
-        const raw = Buffer.concat(chunks).toString("utf8");
-        let parsed = raw;
-        try {
-          parsed = raw.length > 0 ? JSON.parse(raw) : null;
-        } catch {}
-        resolve({ status: res.statusCode ?? 0, body: parsed });
-      });
-    });
-    req.setTimeout(opts.timeoutMs ?? 5000, () => req.destroy(new Error("ipc_timeout")));
-    req.on("error", (err) => reject(err));
-    if (bodyBuf)
-      req.write(bodyBuf);
-    req.end();
-  });
+  return false;
 }
-var IpcError;
-var init_client4 = __esm(() => {
-  init_paths2();
-  init_local_token();
-  IpcError = class IpcError extends Error {
-    status;
-    payload;
-    constructor(status, payload, msg) {
-      super(msg);
-      this.status = status;
-      this.payload = payload;
-    }
-  };
+var alreadyWarned = false;
+var init_warnings = __esm(() => {
+  init_styles();
 });
 
 // src/services/bridge/daemon-route.ts
@@ -7353,12 +7536,16 @@ __export(exports_daemon_route, {
   tryGetSkillViaDaemon: () => tryGetSkillViaDaemon,
   tryForgetViaDaemon: () => tryForgetViaDaemon
 });
-import { existsSync as existsSync7 } from "node:fs";
 function meshQuery(mesh) {
   return mesh ? `?mesh=${encodeURIComponent(mesh)}` : "";
 }
+async function daemonReachable() {
+  const res = await ensureDaemonReady();
+  warnDaemonState(res, {});
+  return res.state === "up" || res.state === "started";
+}
 async function tryListPeersViaDaemon(mesh) {
-  if (!existsSync7(DAEMON_PATHS.SOCK_FILE))
+  if (!await daemonReachable())
     return null;
   try {
     const res = await ipc({ path: `/v1/peers${meshQuery(mesh)}`, timeoutMs: 3000 });
@@ -7373,7 +7560,7 @@ async function tryListPeersViaDaemon(mesh) {
   }
 }
 async function tryListSkillsViaDaemon(mesh) {
-  if (!existsSync7(DAEMON_PATHS.SOCK_FILE))
+  if (!await daemonReachable())
     return null;
   try {
     const res = await ipc({ path: `/v1/skills${meshQuery(mesh)}`, timeoutMs: 3000 });
@@ -7388,7 +7575,7 @@ async function tryListSkillsViaDaemon(mesh) {
   }
 }
 async function tryGetSkillViaDaemon(name, mesh) {
-  if (!existsSync7(DAEMON_PATHS.SOCK_FILE))
+  if (!await daemonReachable())
     return null;
   try {
     const res = await ipc({
@@ -7405,7 +7592,7 @@ async function tryGetSkillViaDaemon(name, mesh) {
   }
 }
 async function tryGetStateViaDaemon(key, mesh) {
-  if (!existsSync7(DAEMON_PATHS.SOCK_FILE))
+  if (!await daemonReachable())
     return null;
   try {
     const path = `/v1/state?key=${encodeURIComponent(key)}${mesh ? `&mesh=${encodeURIComponent(mesh)}` : ""}`;
@@ -7423,7 +7610,7 @@ async function tryGetStateViaDaemon(key, mesh) {
   }
 }
 async function tryListStateViaDaemon(mesh) {
-  if (!existsSync7(DAEMON_PATHS.SOCK_FILE))
+  if (!await daemonReachable())
     return null;
   try {
     const res = await ipc({ path: `/v1/state${meshQuery(mesh)}`, timeoutMs: 3000 });
@@ -7438,7 +7625,7 @@ async function tryListStateViaDaemon(mesh) {
   }
 }
 async function trySetStateViaDaemon(key, value, mesh) {
-  if (!existsSync7(DAEMON_PATHS.SOCK_FILE))
+  if (!await daemonReachable())
     return false;
   try {
     const res = await ipc({
@@ -7453,7 +7640,7 @@ async function trySetStateViaDaemon(key, value, mesh) {
   }
 }
 async function tryRememberViaDaemon(content, tags, mesh) {
-  if (!existsSync7(DAEMON_PATHS.SOCK_FILE))
+  if (!await daemonReachable())
     return null;
   try {
     const res = await ipc({
@@ -7470,7 +7657,7 @@ async function tryRememberViaDaemon(content, tags, mesh) {
   }
 }
 async function tryRecallViaDaemon(query, mesh) {
-  if (!existsSync7(DAEMON_PATHS.SOCK_FILE))
+  if (!await daemonReachable())
     return null;
   try {
     const path = `/v1/memory?q=${encodeURIComponent(query)}${mesh ? `&mesh=${encodeURIComponent(mesh)}` : ""}`;
@@ -7486,7 +7673,7 @@ async function tryRecallViaDaemon(query, mesh) {
   }
 }
 async function tryForgetViaDaemon(id, mesh) {
-  if (!existsSync7(DAEMON_PATHS.SOCK_FILE))
+  if (!await daemonReachable())
     return false;
   try {
     const path = `/v1/memory/${encodeURIComponent(id)}${meshQuery(mesh)}`;
@@ -7497,7 +7684,7 @@ async function tryForgetViaDaemon(id, mesh) {
   }
 }
 async function trySendViaDaemon(args) {
-  if (!existsSync7(DAEMON_PATHS.SOCK_FILE))
+  if (!await daemonReachable())
     return null;
   try {
     const res = await ipc({
@@ -7529,8 +7716,9 @@ async function trySendViaDaemon(args) {
   }
 }
 var init_daemon_route = __esm(() => {
-  init_client4();
-  init_paths2();
+  init_client3();
+  init_lifecycle();
+  init_warnings();
 });
 
 // src/commands/peers.ts
@@ -7631,7 +7819,7 @@ var FIELD_ALIAS;
 var init_peers = __esm(() => {
   init_connect();
   init_facade();
-  init_client3();
+  init_client4();
   init_render();
   init_styles();
   FIELD_ALIAS = {
@@ -7739,7 +7927,7 @@ async function runSend(flags, to, message) {
 var init_send = __esm(() => {
   init_connect();
   init_facade();
-  init_client3();
+  init_client4();
   init_daemon_route();
   init_render();
   init_styles();
@@ -8387,7 +8575,7 @@ async function runTaskComplete(id, result, opts) {
 var init_broker_actions = __esm(() => {
   init_connect();
   init_facade();
-  init_client3();
+  init_client4();
   init_daemon_route();
   init_render();
   init_styles();
@@ -8622,35 +8810,35 @@ var init_whoami = __esm(() => {
 });
 
 // src/daemon/lock.ts
-import { existsSync as existsSync8, mkdirSync as mkdirSync5, readFileSync as readFileSync6, unlinkSync as unlinkSync2, writeFileSync as writeFileSync7 } from "node:fs";
+import { existsSync as existsSync8, mkdirSync as mkdirSync5, readFileSync as readFileSync7, unlinkSync as unlinkSync3, writeFileSync as writeFileSync8 } from "node:fs";
 import { dirname as dirname4 } from "node:path";
 function acquireSingletonLock() {
   mkdirSync5(dirname4(DAEMON_PATHS.PID_FILE), { recursive: true, mode: 448 });
   if (existsSync8(DAEMON_PATHS.PID_FILE)) {
-    const raw = readFileSync6(DAEMON_PATHS.PID_FILE, "utf8").trim();
+    const raw = readFileSync7(DAEMON_PATHS.PID_FILE, "utf8").trim();
     const oldPid = Number.parseInt(raw, 10);
     if (Number.isFinite(oldPid) && oldPid > 0 && isProcessAlive(oldPid)) {
       return { result: "already-running", pid: oldPid };
     }
     try {
-      unlinkSync2(DAEMON_PATHS.PID_FILE);
+      unlinkSync3(DAEMON_PATHS.PID_FILE);
     } catch {}
-    writeFileSync7(DAEMON_PATHS.PID_FILE, String(process.pid), { mode: 384 });
+    writeFileSync8(DAEMON_PATHS.PID_FILE, String(process.pid), { mode: 384 });
     return { result: "stale", pid: process.pid };
   }
-  writeFileSync7(DAEMON_PATHS.PID_FILE, String(process.pid), { mode: 384 });
+  writeFileSync8(DAEMON_PATHS.PID_FILE, String(process.pid), { mode: 384 });
   return { result: "acquired", pid: process.pid };
 }
 function releaseSingletonLock() {
   try {
-    const raw = readFileSync6(DAEMON_PATHS.PID_FILE, "utf8").trim();
+    const raw = readFileSync7(DAEMON_PATHS.PID_FILE, "utf8").trim();
     if (Number.parseInt(raw, 10) === process.pid)
-      unlinkSync2(DAEMON_PATHS.PID_FILE);
+      unlinkSync3(DAEMON_PATHS.PID_FILE);
   } catch {}
 }
 function readRunningPid() {
   try {
-    const raw = readFileSync6(DAEMON_PATHS.PID_FILE, "utf8").trim();
+    const raw = readFileSync7(DAEMON_PATHS.PID_FILE, "utf8").trim();
     const pid = Number.parseInt(raw, 10);
     if (Number.isFinite(pid) && pid > 0 && isProcessAlive(pid))
       return pid;
@@ -9082,7 +9270,7 @@ function bindSseStream(res, bus) {
 
 // src/daemon/ipc/server.ts
 import { createServer as createServer2 } from "node:http";
-import { chmodSync as chmodSync3, existsSync as existsSync9, unlinkSync as unlinkSync3 } from "node:fs";
+import { chmodSync as chmodSync3, existsSync as existsSync9, unlinkSync as unlinkSync4 } from "node:fs";
 import { timingSafeEqual } from "node:crypto";
 import { randomUUID as randomUUID4 } from "node:crypto";
 function startIpcServer(opts) {
@@ -9100,7 +9288,7 @@ function startIpcServer(opts) {
   });
   if (existsSync9(DAEMON_PATHS.SOCK_FILE)) {
     try {
-      unlinkSync3(DAEMON_PATHS.SOCK_FILE);
+      unlinkSync4(DAEMON_PATHS.SOCK_FILE);
     } catch {}
   }
   const uds = createServer2(handler);
@@ -9136,7 +9324,7 @@ function startIpcServer(opts) {
         tcp ? new Promise((res) => tcp.close(() => res())) : Promise.resolve()
       ]);
       try {
-        unlinkSync3(DAEMON_PATHS.SOCK_FILE);
+        unlinkSync4(DAEMON_PATHS.SOCK_FILE);
       } catch {}
     }
   };
@@ -10533,12 +10721,12 @@ __export(exports_identity, {
   checkFingerprint: () => checkFingerprint,
   acceptCurrentHost: () => acceptCurrentHost
 });
-import { existsSync as existsSync10, readFileSync as readFileSync7, writeFileSync as writeFileSync8 } from "node:fs";
-import { join as join7 } from "node:path";
+import { existsSync as existsSync10, readFileSync as readFileSync8, writeFileSync as writeFileSync9 } from "node:fs";
+import { join as join8 } from "node:path";
 import { createHash as createHash2 } from "node:crypto";
 import { networkInterfaces } from "node:os";
 function path() {
-  return join7(DAEMON_PATHS.DAEMON_DIR, FILE_NAME);
+  return join8(DAEMON_PATHS.DAEMON_DIR, FILE_NAME);
 }
 function computeCurrentFingerprint() {
   const host_id = readHostId() ?? "";
@@ -10555,12 +10743,12 @@ function computeCurrentFingerprint() {
 function checkFingerprint() {
   const current = computeCurrentFingerprint();
   if (!existsSync10(path())) {
-    writeFileSync8(path(), JSON.stringify(current, null, 2), { mode: 384 });
+    writeFileSync9(path(), JSON.stringify(current, null, 2), { mode: 384 });
     return { result: "first_run", current };
   }
   let stored;
   try {
-    stored = JSON.parse(readFileSync7(path(), "utf8"));
+    stored = JSON.parse(readFileSync8(path(), "utf8"));
   } catch {
     return { result: "unavailable", current };
   }
@@ -10570,14 +10758,14 @@ function checkFingerprint() {
 }
 function acceptCurrentHost() {
   const current = computeCurrentFingerprint();
-  writeFileSync8(path(), JSON.stringify(current, null, 2), { mode: 384 });
+  writeFileSync9(path(), JSON.stringify(current, null, 2), { mode: 384 });
   return current;
 }
 function readHostId() {
   if (process.platform === "linux") {
     for (const p of ["/etc/machine-id", "/var/lib/dbus/machine-id"]) {
       try {
-        const raw = readFileSync7(p, "utf8").trim();
+        const raw = readFileSync8(p, "utf8").trim();
         if (raw)
           return `linux:${raw}`;
       } catch {}
@@ -10622,7 +10810,7 @@ var init_identity = __esm(() => {
 });
 
 // src/daemon/run.ts
-import { existsSync as existsSync11, mkdirSync as mkdirSync6, readFileSync as readFileSync8 } from "node:fs";
+import { existsSync as existsSync11, mkdirSync as mkdirSync6, readFileSync as readFileSync9 } from "node:fs";
 function detectContainer() {
   if (process.env.KUBERNETES_SERVICE_HOST)
     return true;
@@ -10631,7 +10819,7 @@ function detectContainer() {
   try {
     if (existsSync11("/.dockerenv"))
       return true;
-    const cg = readFileSync8("/proc/1/cgroup", "utf8");
+    const cg = readFileSync9("/proc/1/cgroup", "utf8");
     if (/(docker|kubepods|containerd)/.test(cg))
       return true;
   } catch {}
@@ -10832,10 +11020,10 @@ __export(exports_service_install, {
   installService: () => installService,
   detectPlatform: () => detectPlatform
 });
-import { existsSync as existsSync12, mkdirSync as mkdirSync7, writeFileSync as writeFileSync9, unlinkSync as unlinkSync4, readFileSync as readFileSync9 } from "node:fs";
+import { existsSync as existsSync12, mkdirSync as mkdirSync7, writeFileSync as writeFileSync10, unlinkSync as unlinkSync5, readFileSync as readFileSync10 } from "node:fs";
 import { execSync as execSync2 } from "node:child_process";
 import { homedir as homedir6 } from "node:os";
-import { join as join8, dirname as dirname5 } from "node:path";
+import { join as join9, dirname as dirname5 } from "node:path";
 function detectPlatform() {
   if (process.platform === "darwin")
     return "darwin";
@@ -10870,7 +11058,7 @@ function uninstallService() {
       execSync2(`launchctl bootout gui/$(id -u)/${SERVICE_LABEL}`, { stdio: "ignore" });
     } catch {}
     if (existsSync12(p)) {
-      unlinkSync4(p);
+      unlinkSync5(p);
       removed.push(p);
     }
   } else if (platform5 === "linux") {
@@ -10879,14 +11067,14 @@ function uninstallService() {
       execSync2(`systemctl --user disable --now ${SYSTEMD_UNIT}`, { stdio: "ignore" });
     } catch {}
     if (existsSync12(p)) {
-      unlinkSync4(p);
+      unlinkSync5(p);
       removed.push(p);
     }
   }
   return { platform: platform5, removed };
 }
 function darwinPlistPath() {
-  return join8(homedir6(), "Library", "LaunchAgents", `${SERVICE_LABEL}.plist`);
+  return join9(homedir6(), "Library", "LaunchAgents", `${SERVICE_LABEL}.plist`);
 }
 function installDarwin(args) {
   const plist = darwinPlistPath();
@@ -10931,7 +11119,7 @@ function installDarwin(args) {
 </dict>
 </plist>
 `;
-  writeFileSync9(plist, xml, { mode: 420 });
+  writeFileSync10(plist, xml, { mode: 420 });
   return {
     platform: "darwin",
     unitPath: plist,
@@ -10939,7 +11127,7 @@ function installDarwin(args) {
   };
 }
 function linuxUnitPath() {
-  return join8(homedir6(), ".config", "systemd", "user", SYSTEMD_UNIT);
+  return join9(homedir6(), ".config", "systemd", "user", SYSTEMD_UNIT);
 }
 function installLinux(args) {
   const unit = linuxUnitPath();
@@ -10968,7 +11156,7 @@ Environment=PATH=/usr/local/bin:/usr/bin:/bin
 [Install]
 WantedBy=default.target
 `;
-  writeFileSync9(unit, content, { mode: 420 });
+  writeFileSync10(unit, content, { mode: 420 });
   return {
     platform: "linux",
     unitPath: unit,
@@ -10991,7 +11179,7 @@ function readInstalledUnit() {
   if (!existsSync12(path2))
     return { platform: platform5, path: null, content: null };
   try {
-    return { platform: platform5, path: path2, content: readFileSync9(path2, "utf8") };
+    return { platform: platform5, path: path2, content: readFileSync10(path2, "utf8") };
   } catch {
     return { platform: platform5, path: path2, content: null };
   }
@@ -11319,7 +11507,7 @@ async function runStop(opts) {
 }
 var init_daemon = __esm(() => {
   init_run();
-  init_client4();
+  init_client3();
   init_lock();
   init_paths2();
 });
@@ -11335,17 +11523,17 @@ import {
   copyFileSync,
   existsSync as existsSync13,
   mkdirSync as mkdirSync8,
-  readFileSync as readFileSync10,
-  writeFileSync as writeFileSync10
+  readFileSync as readFileSync11,
+  writeFileSync as writeFileSync11
 } from "node:fs";
 import { homedir as homedir7, platform as platform5 } from "node:os";
-import { dirname as dirname6, join as join9, resolve } from "node:path";
+import { dirname as dirname6, join as join10, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync as spawnSync3 } from "node:child_process";
 function readClaudeConfig() {
   if (!existsSync13(CLAUDE_CONFIG))
     return {};
-  const text = readFileSync10(CLAUDE_CONFIG, "utf-8").trim();
+  const text = readFileSync11(CLAUDE_CONFIG, "utf-8").trim();
   if (!text)
     return {};
   try {
@@ -11357,10 +11545,10 @@ function readClaudeConfig() {
 function backupClaudeConfig() {
   if (!existsSync13(CLAUDE_CONFIG))
     return;
-  const backupDir = join9(dirname6(CLAUDE_CONFIG), ".claude", "backups");
+  const backupDir = join10(dirname6(CLAUDE_CONFIG), ".claude", "backups");
   mkdirSync8(backupDir, { recursive: true });
   const ts = Date.now();
-  const dest = join9(backupDir, `.claude.json.pre-claudemesh.${ts}`);
+  const dest = join10(backupDir, `.claude.json.pre-claudemesh.${ts}`);
   copyFileSync(CLAUDE_CONFIG, dest);
 }
 function patchMcpServer(entry) {
@@ -11398,7 +11586,7 @@ function removeMcpServer() {
 }
 function flushClaudeConfig(obj) {
   mkdirSync8(dirname6(CLAUDE_CONFIG), { recursive: true });
-  writeFileSync10(CLAUDE_CONFIG, JSON.stringify(obj, null, 2) + `
+  writeFileSync11(CLAUDE_CONFIG, JSON.stringify(obj, null, 2) + `
 `, "utf-8");
   try {
     chmodSync4(CLAUDE_CONFIG, 384);
@@ -11420,7 +11608,7 @@ function resolveEntry() {
 function resolveBundledSkillsDir() {
   const here = fileURLToPath(import.meta.url);
   const pkgRoot = resolve(dirname6(here), "..", "..");
-  const skillsDir = join9(pkgRoot, "skills");
+  const skillsDir = join10(pkgRoot, "skills");
   if (existsSync13(skillsDir))
     return skillsDir;
   return null;
@@ -11434,13 +11622,13 @@ function installSkills() {
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
     if (!entry.isDirectory())
       continue;
-    const srcDir = join9(src, entry.name);
-    const dstDir = join9(CLAUDE_SKILLS_ROOT, entry.name);
+    const srcDir = join10(src, entry.name);
+    const dstDir = join10(CLAUDE_SKILLS_ROOT, entry.name);
     mkdirSync8(dstDir, { recursive: true });
     for (const file of fs.readdirSync(srcDir, { withFileTypes: true })) {
       if (!file.isFile())
         continue;
-      copyFileSync(join9(srcDir, file.name), join9(dstDir, file.name));
+      copyFileSync(join10(srcDir, file.name), join10(dstDir, file.name));
     }
     installed.push(entry.name);
   }
@@ -11455,7 +11643,7 @@ function uninstallSkills() {
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
     if (!entry.isDirectory())
       continue;
-    const dstDir = join9(CLAUDE_SKILLS_ROOT, entry.name);
+    const dstDir = join10(CLAUDE_SKILLS_ROOT, entry.name);
     if (existsSync13(dstDir)) {
       try {
         fs.rmSync(dstDir, { recursive: true, force: true });
@@ -11483,7 +11671,7 @@ function entriesEqual(a, b) {
 function readClaudeSettings() {
   if (!existsSync13(CLAUDE_SETTINGS))
     return {};
-  const text = readFileSync10(CLAUDE_SETTINGS, "utf-8").trim();
+  const text = readFileSync11(CLAUDE_SETTINGS, "utf-8").trim();
   if (!text)
     return {};
   try {
@@ -11494,7 +11682,7 @@ function readClaudeSettings() {
 }
 function writeClaudeSettings(obj) {
   mkdirSync8(dirname6(CLAUDE_SETTINGS), { recursive: true });
-  writeFileSync10(CLAUDE_SETTINGS, JSON.stringify(obj, null, 2) + `
+  writeFileSync11(CLAUDE_SETTINGS, JSON.stringify(obj, null, 2) + `
 `, "utf-8");
 }
 function installAllowedTools() {
@@ -11644,7 +11832,7 @@ function runInstall(args = []) {
       const installed = installSkills();
       if (installed.length > 0) {
         render.ok(`Claude skill${installed.length === 1 ? "" : "s"} installed`, installed.join(", "));
-        render.info(dim(`  ${join9(CLAUDE_SKILLS_ROOT, installed[0])}/SKILL.md`));
+        render.info(dim(`  ${join10(CLAUDE_SKILLS_ROOT, installed[0])}/SKILL.md`));
       }
     } catch (e) {
       render.warn(`skill install failed: ${e instanceof Error ? e.message : String(e)}`);
@@ -11781,9 +11969,9 @@ var init_install = __esm(() => {
   init_facade();
   init_render();
   init_styles();
-  CLAUDE_CONFIG = join9(homedir7(), ".claude.json");
-  CLAUDE_SETTINGS = join9(homedir7(), ".claude", "settings.json");
-  CLAUDE_SKILLS_ROOT = join9(homedir7(), ".claude", "skills");
+  CLAUDE_CONFIG = join10(homedir7(), ".claude.json");
+  CLAUDE_SETTINGS = join10(homedir7(), ".claude", "settings.json");
+  CLAUDE_SKILLS_ROOT = join10(homedir7(), ".claude", "skills");
   CLAUDEMESH_TOOLS = [
     "mcp__claudemesh__cancel_scheduled",
     "mcp__claudemesh__check_messages",
@@ -11838,26 +12026,26 @@ var exports_uninstall = {};
 __export(exports_uninstall, {
   uninstall: () => uninstall
 });
-import { readFileSync as readFileSync11, writeFileSync as writeFileSync11, existsSync as existsSync14, rmSync as rmSync2, readdirSync as readdirSync2 } from "node:fs";
-import { join as join10, dirname as dirname7 } from "node:path";
+import { readFileSync as readFileSync12, writeFileSync as writeFileSync12, existsSync as existsSync14, rmSync as rmSync2, readdirSync as readdirSync2 } from "node:fs";
+import { join as join11, dirname as dirname7 } from "node:path";
 import { homedir as homedir8 } from "node:os";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 function bundledSkillsDir() {
   const here = fileURLToPath2(import.meta.url);
-  const pkgRoot = join10(dirname7(here), "..", "..");
-  const skillsDir = join10(pkgRoot, "skills");
+  const pkgRoot = join11(dirname7(here), "..", "..");
+  const skillsDir = join11(pkgRoot, "skills");
   return existsSync14(skillsDir) ? skillsDir : null;
 }
 async function uninstall() {
   let removed = 0;
   if (existsSync14(PATHS.CLAUDE_JSON)) {
     try {
-      const raw = readFileSync11(PATHS.CLAUDE_JSON, "utf-8");
+      const raw = readFileSync12(PATHS.CLAUDE_JSON, "utf-8");
       const config = JSON.parse(raw);
       const servers = config.mcpServers;
       if (servers && "claudemesh" in servers) {
         delete servers.claudemesh;
-        writeFileSync11(PATHS.CLAUDE_JSON, JSON.stringify(config, null, 2) + `
+        writeFileSync12(PATHS.CLAUDE_JSON, JSON.stringify(config, null, 2) + `
 `, "utf-8");
         render.ok("removed MCP server", dim("~/.claude.json"));
         removed++;
@@ -11866,7 +12054,7 @@ async function uninstall() {
   }
   if (existsSync14(PATHS.CLAUDE_SETTINGS)) {
     try {
-      const raw = readFileSync11(PATHS.CLAUDE_SETTINGS, "utf-8");
+      const raw = readFileSync12(PATHS.CLAUDE_SETTINGS, "utf-8");
       const config = JSON.parse(raw);
       const hooks = config.hooks;
       if (hooks) {
@@ -11887,7 +12075,7 @@ async function uninstall() {
           }
         }
         if (removedHooks > 0) {
-          writeFileSync11(PATHS.CLAUDE_SETTINGS, JSON.stringify(config, null, 2) + `
+          writeFileSync12(PATHS.CLAUDE_SETTINGS, JSON.stringify(config, null, 2) + `
 `, "utf-8");
           render.ok(`removed ${removedHooks} claudemesh hook${removedHooks === 1 ? "" : "s"}`, dim("settings.json"));
           removed++;
@@ -11902,7 +12090,7 @@ async function uninstall() {
       for (const entry of readdirSync2(src, { withFileTypes: true })) {
         if (!entry.isDirectory())
           continue;
-        const dst = join10(CLAUDE_SKILLS_ROOT2, entry.name);
+        const dst = join11(CLAUDE_SKILLS_ROOT2, entry.name);
         if (existsSync14(dst)) {
           try {
             rmSync2(dst, { recursive: true, force: true });
@@ -11927,7 +12115,7 @@ var init_uninstall = __esm(() => {
   init_render();
   init_styles();
   init_exit_codes();
-  CLAUDE_SKILLS_ROOT2 = join10(homedir8(), ".claude", "skills");
+  CLAUDE_SKILLS_ROOT2 = join11(homedir8(), ".claude", "skills");
 });
 
 // src/commands/doctor.ts
@@ -11935,9 +12123,9 @@ var exports_doctor = {};
 __export(exports_doctor, {
   runDoctor: () => runDoctor
 });
-import { existsSync as existsSync15, readFileSync as readFileSync12, statSync as statSync2 } from "node:fs";
+import { existsSync as existsSync15, readFileSync as readFileSync13, statSync as statSync3 } from "node:fs";
 import { homedir as homedir9, platform as platform6 } from "node:os";
-import { join as join11 } from "node:path";
+import { join as join12 } from "node:path";
 import { spawnSync as spawnSync4 } from "node:child_process";
 function checkNode() {
   const major = Number(process.versions.node.split(".")[0]);
@@ -11961,7 +12149,7 @@ function checkClaudeOnPath() {
   };
 }
 function checkMcpRegistered() {
-  const claudeConfig = join11(homedir9(), ".claude.json");
+  const claudeConfig = join12(homedir9(), ".claude.json");
   if (!existsSync15(claudeConfig)) {
     return {
       name: "claudemesh MCP registered in ~/.claude.json",
@@ -11970,7 +12158,7 @@ function checkMcpRegistered() {
     };
   }
   try {
-    const cfg = JSON.parse(readFileSync12(claudeConfig, "utf-8"));
+    const cfg = JSON.parse(readFileSync13(claudeConfig, "utf-8"));
     const registered = Boolean(cfg.mcpServers?.["claudemesh"]);
     return {
       name: "claudemesh MCP registered in ~/.claude.json",
@@ -11987,7 +12175,7 @@ function checkMcpRegistered() {
   }
 }
 function checkHooksRegistered() {
-  const settings = join11(homedir9(), ".claude", "settings.json");
+  const settings = join12(homedir9(), ".claude", "settings.json");
   if (!existsSync15(settings)) {
     return {
       name: "Status hooks registered in ~/.claude/settings.json",
@@ -11996,7 +12184,7 @@ function checkHooksRegistered() {
     };
   }
   try {
-    const raw = readFileSync12(settings, "utf-8");
+    const raw = readFileSync13(settings, "utf-8");
     const has = raw.includes("claudemesh hook ");
     return {
       name: "Status hooks registered in ~/.claude/settings.json",
@@ -12022,7 +12210,7 @@ function checkConfigFile() {
   }
   try {
     readConfig();
-    const st = statSync2(path2);
+    const st = statSync3(path2);
     const mode = (st.mode & 511).toString(8);
     const secure = platform6() === "win32" || mode === "600";
     return {
@@ -12196,7 +12384,7 @@ var exports_status = {};
 __export(exports_status, {
   runStatus: () => runStatus2
 });
-import { statSync as statSync3, existsSync as existsSync16 } from "node:fs";
+import { statSync as statSync4, existsSync as existsSync16 } from "node:fs";
 import WebSocket3 from "ws";
 async function probeBroker(url, timeoutMs = 4000) {
   return new Promise((resolve2) => {
@@ -12227,7 +12415,7 @@ async function runStatus2() {
   const configPath = getConfigPath();
   let configPermsNote = "missing";
   if (existsSync16(configPath)) {
-    const mode = (statSync3(configPath).mode & 511).toString(8).padStart(4, "0");
+    const mode = (statSync4(configPath).mode & 511).toString(8).padStart(4, "0");
     configPermsNote = mode === "0600" ? `${mode}` : `${mode} — expected 0600`;
   }
   render.kv([["config", configPath], ["perms", configPermsNote]]);
@@ -12372,13 +12560,13 @@ var init_check_claude_binary = __esm(() => {
 });
 
 // src/services/health/check-mcp-registered.ts
-import { existsSync as existsSync17, readFileSync as readFileSync13 } from "node:fs";
+import { existsSync as existsSync17, readFileSync as readFileSync14 } from "node:fs";
 function checkMcpRegistered2() {
   try {
     if (!existsSync17(PATHS.CLAUDE_JSON)) {
       return { name: "mcp-registered", ok: false, message: "~/.claude.json not found" };
     }
-    const raw = readFileSync13(PATHS.CLAUDE_JSON, "utf-8");
+    const raw = readFileSync14(PATHS.CLAUDE_JSON, "utf-8");
     const config = JSON.parse(raw);
     if (config.mcpServers && "claudemesh" in config.mcpServers) {
       return { name: "mcp-registered", ok: true, message: "MCP server registered" };
@@ -12393,13 +12581,13 @@ var init_check_mcp_registered = __esm(() => {
 });
 
 // src/services/health/check-hooks-registered.ts
-import { existsSync as existsSync18, readFileSync as readFileSync14 } from "node:fs";
+import { existsSync as existsSync18, readFileSync as readFileSync15 } from "node:fs";
 function checkHooksRegistered2() {
   try {
     if (!existsSync18(PATHS.CLAUDE_SETTINGS)) {
       return { name: "hooks-registered", ok: false, message: "~/.claude/settings.json not found" };
     }
-    const raw = readFileSync14(PATHS.CLAUDE_SETTINGS, "utf-8");
+    const raw = readFileSync15(PATHS.CLAUDE_SETTINGS, "utf-8");
     const config = JSON.parse(raw);
     if (config.hooks) {
       return { name: "hooks-registered", ok: true, message: "Hooks configured" };
@@ -12414,14 +12602,14 @@ var init_check_hooks_registered = __esm(() => {
 });
 
 // src/services/health/check-config-perms.ts
-import { existsSync as existsSync19, statSync as statSync4 } from "node:fs";
+import { existsSync as existsSync19, statSync as statSync5 } from "node:fs";
 function checkConfigPerms() {
   const configFile = PATHS.CONFIG_FILE;
   if (!existsSync19(configFile)) {
     return { name: "config-perms", ok: true, message: "No config file yet (first run)" };
   }
   try {
-    const mode = statSync4(configFile).mode & 511;
+    const mode = statSync5(configFile).mode & 511;
     if (mode <= 384) {
       return { name: "config-perms", ok: true, message: `config.json mode ${mode.toString(8)}` };
     }
@@ -12435,13 +12623,13 @@ var init_check_config_perms = __esm(() => {
 });
 
 // src/services/health/check-keypairs-valid.ts
-import { existsSync as existsSync20, readFileSync as readFileSync15 } from "node:fs";
+import { existsSync as existsSync20, readFileSync as readFileSync16 } from "node:fs";
 function checkKeypairsValid() {
   if (!existsSync20(PATHS.CONFIG_FILE)) {
     return { name: "keypairs-valid", ok: true, message: "No config (first run)" };
   }
   try {
-    const raw = readFileSync15(PATHS.CONFIG_FILE, "utf-8");
+    const raw = readFileSync16(PATHS.CONFIG_FILE, "utf-8");
     const config = JSON.parse(raw);
     const meshes = config.meshes ?? [];
     if (meshes.length === 0) {
@@ -12922,17 +13110,17 @@ __export(exports_url_handler, {
   runUrlHandler: () => runUrlHandler
 });
 import { platform as platform7, homedir as homedir10 } from "node:os";
-import { existsSync as existsSync21, mkdirSync as mkdirSync9, writeFileSync as writeFileSync12, rmSync as rmSync3, chmodSync as chmodSync5 } from "node:fs";
-import { join as join12 } from "node:path";
+import { existsSync as existsSync21, mkdirSync as mkdirSync9, writeFileSync as writeFileSync13, rmSync as rmSync3, chmodSync as chmodSync5 } from "node:fs";
+import { join as join13 } from "node:path";
 import { spawnSync as spawnSync5 } from "node:child_process";
 function resolveClaudemeshBin() {
   return process.argv[1] ?? "claudemesh";
 }
 function installDarwin2() {
   const binPath = resolveClaudemeshBin();
-  const appDir = join12(homedir10(), "Library", "Application Support", "claudemesh", "ClaudemeshHandler.app");
-  const contents = join12(appDir, "Contents");
-  const macOS = join12(contents, "MacOS");
+  const appDir = join13(homedir10(), "Library", "Application Support", "claudemesh", "ClaudemeshHandler.app");
+  const contents = join13(appDir, "Contents");
+  const macOS = join13(contents, "MacOS");
   mkdirSync9(macOS, { recursive: true });
   const plist = `<?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">
@@ -12956,7 +13144,7 @@ function installDarwin2() {
   </array>
 </dict>
 </plist>`;
-  writeFileSync12(join12(contents, "Info.plist"), plist);
+  writeFileSync13(join13(contents, "Info.plist"), plist);
   const shim = `#!/bin/sh
 URL="$1"
 CODE=\${URL#claudemesh://}
@@ -12970,8 +13158,8 @@ tell application "Terminal"
 end tell
 EOF
 `;
-  const shimPath = join12(macOS, "open-url");
-  writeFileSync12(shimPath, shim);
+  const shimPath = join13(macOS, "open-url");
+  writeFileSync13(shimPath, shim);
   chmodSync5(shimPath, 493);
   const lsreg = spawnSync5("/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister", ["-f", appDir], { encoding: "utf-8" });
   if (lsreg.status !== 0) {
@@ -12982,7 +13170,7 @@ EOF
 }
 function installLinux2() {
   const binPath = resolveClaudemeshBin();
-  const appsDir = join12(homedir10(), ".local", "share", "applications");
+  const appsDir = join13(homedir10(), ".local", "share", "applications");
   mkdirSync9(appsDir, { recursive: true });
   const desktop = `[Desktop Entry]
 Type=Application
@@ -12994,8 +13182,8 @@ Terminal=true
 MimeType=x-scheme-handler/claudemesh;
 NoDisplay=true
 `;
-  const desktopPath = join12(appsDir, "claudemesh.desktop");
-  writeFileSync12(desktopPath, desktop);
+  const desktopPath = join13(appsDir, "claudemesh.desktop");
+  writeFileSync13(desktopPath, desktop);
   const xdg1 = spawnSync5("xdg-mime", ["default", "claudemesh.desktop", "x-scheme-handler/claudemesh"], { encoding: "utf-8" });
   if (xdg1.status !== 0) {
     render.warn("xdg-mime not available — skipped mime default registration");
@@ -13017,8 +13205,8 @@ function installWindows() {
     `[HKEY_CURRENT_USER\\Software\\Classes\\claudemesh\\shell\\open\\command]`,
     `@="\\"${binPath.replace(/\\/g, "\\\\")}\\" \\"%1\\""`
   ];
-  const regPath = join12(homedir10(), "claudemesh-handler.reg");
-  writeFileSync12(regPath, lines.join(`\r
+  const regPath = join13(homedir10(), "claudemesh-handler.reg");
+  writeFileSync13(regPath, lines.join(`\r
 `));
   const res = spawnSync5("reg.exe", ["import", regPath], { encoding: "utf-8" });
   if (res.status !== 0) {
@@ -13029,14 +13217,14 @@ function installWindows() {
   return EXIT.SUCCESS;
 }
 function uninstallDarwin() {
-  const appDir = join12(homedir10(), "Library", "Application Support", "claudemesh", "ClaudemeshHandler.app");
+  const appDir = join13(homedir10(), "Library", "Application Support", "claudemesh", "ClaudemeshHandler.app");
   if (existsSync21(appDir))
     rmSync3(appDir, { recursive: true, force: true });
   render.ok("removed claudemesh:// handler on macOS");
   return EXIT.SUCCESS;
 }
 function uninstallLinux() {
-  const desktopPath = join12(homedir10(), ".local", "share", "applications", "claudemesh.desktop");
+  const desktopPath = join13(homedir10(), ".local", "share", "applications", "claudemesh.desktop");
   if (existsSync21(desktopPath))
     rmSync3(desktopPath, { force: true });
   render.ok("removed claudemesh:// handler on Linux");
@@ -13082,8 +13270,8 @@ var exports_status_line = {};
 __export(exports_status_line, {
   runStatusLine: () => runStatusLine
 });
-import { existsSync as existsSync22, readFileSync as readFileSync16 } from "node:fs";
-import { join as join13 } from "node:path";
+import { existsSync as existsSync22, readFileSync as readFileSync17 } from "node:fs";
+import { join as join14 } from "node:path";
 import { homedir as homedir11 } from "node:os";
 async function runStatusLine() {
   try {
@@ -13092,11 +13280,11 @@ async function runStatusLine() {
       process.stdout.write("◇ claudemesh (not joined)");
       return EXIT.SUCCESS;
     }
-    const cachePath = join13(homedir11(), ".claudemesh", "peer-cache.json");
+    const cachePath = join14(homedir11(), ".claudemesh", "peer-cache.json");
     let cache = {};
     if (existsSync22(cachePath)) {
       try {
-        cache = JSON.parse(readFileSync16(cachePath, "utf-8"));
+        cache = JSON.parse(readFileSync17(cachePath, "utf-8"));
       } catch {}
     }
     const pick = config.meshes[0];
@@ -13127,7 +13315,7 @@ __export(exports_backup, {
   runRestore: () => runRestore,
   runBackup: () => runBackup
 });
-import { readFileSync as readFileSync17, writeFileSync as writeFileSync13, existsSync as existsSync23 } from "node:fs";
+import { readFileSync as readFileSync18, writeFileSync as writeFileSync14, existsSync as existsSync23 } from "node:fs";
 import { createInterface as createInterface11 } from "node:readline";
 function readHidden(prompt5) {
   return new Promise((resolve2) => {
@@ -13173,7 +13361,7 @@ async function runBackup(outPath) {
     console.error("  No config found — nothing to back up. Join a mesh first.");
     return EXIT.NOT_FOUND;
   }
-  const plaintext = readFileSync17(configPath);
+  const plaintext = readFileSync18(configPath);
   const pass = await readHidden("  Passphrase (min 12 chars): ");
   if (pass.length < 12) {
     console.error("  ✗ Passphrase too short.");
@@ -13191,7 +13379,7 @@ async function runBackup(outPath) {
   const ciphertext = Buffer.from(s.crypto_aead_xchacha20poly1305_ietf_encrypt(plaintext, null, null, nonce, key));
   const blob = Buffer.concat([MAGIC, salt, nonce, ciphertext]);
   const file = outPath ?? `claudemesh-backup-${new Date().toISOString().replace(/[:.]/g, "-")}.cmb`;
-  writeFileSync13(file, blob, { mode: 384 });
+  writeFileSync14(file, blob, { mode: 384 });
   console.log(`
   ✓ Backup saved: ${file}`);
   console.log(`  Size: ${blob.length} bytes. Guard the passphrase — there is no recovery.
@@ -13207,7 +13395,7 @@ async function runRestore(inPath) {
     console.error(`  ✗ File not found: ${inPath}`);
     return EXIT.NOT_FOUND;
   }
-  const blob = readFileSync17(inPath);
+  const blob = readFileSync18(inPath);
   if (blob.length < 4 + 16 + 24 + 17 || !blob.subarray(0, 4).equals(MAGIC)) {
     console.error("  ✗ Not a claudemesh backup file (bad magic).");
     return EXIT.INVALID_ARGS;
@@ -13228,10 +13416,10 @@ async function runRestore(inPath) {
   const configPath = getConfigPath();
   if (existsSync23(configPath)) {
     const backupOld = `${configPath}.before-restore.${Date.now()}`;
-    writeFileSync13(backupOld, readFileSync17(configPath), { mode: 384 });
+    writeFileSync14(backupOld, readFileSync18(configPath), { mode: 384 });
     console.log(`  ↻ Existing config saved to ${backupOld}`);
   }
-  writeFileSync13(configPath, Buffer.from(plaintext), { mode: 384 });
+  writeFileSync14(configPath, Buffer.from(plaintext), { mode: 384 });
   console.log(`
   ✓ Config restored to ${configPath}`);
   console.log("  Run `claudemesh list` to verify your meshes.\n");
@@ -13252,7 +13440,7 @@ __export(exports_upgrade, {
 });
 import { spawnSync as spawnSync6 } from "node:child_process";
 import { existsSync as existsSync24 } from "node:fs";
-import { dirname as dirname8, join as join14, resolve as resolve2 } from "node:path";
+import { dirname as dirname8, join as join15, resolve as resolve2 } from "node:path";
 async function latestVersion() {
   try {
     const res = await fetch(URLS.NPM_REGISTRY, { signal: AbortSignal.timeout(8000) });
@@ -13265,14 +13453,14 @@ async function latestVersion() {
   }
 }
 function findNpm() {
-  const portable = join14(process.env.HOME ?? "", ".claudemesh", "node", "bin", "npm");
+  const portable = join15(process.env.HOME ?? "", ".claudemesh", "node", "bin", "npm");
   if (existsSync24(portable)) {
-    return { npm: portable, prefix: join14(process.env.HOME ?? "", ".claudemesh") };
+    return { npm: portable, prefix: join15(process.env.HOME ?? "", ".claudemesh") };
   }
   let cur = resolve2(process.argv[1] ?? ".");
   for (let i = 0;i < 6; i++) {
     cur = dirname8(cur);
-    const candidate = join14(cur, "bin", "npm");
+    const candidate = join15(cur, "bin", "npm");
     if (existsSync24(candidate))
       return { npm: candidate };
   }
@@ -13335,9 +13523,9 @@ __export(exports_grants, {
   runBlock: () => runBlock,
   isAllowed: () => isAllowed
 });
-import { existsSync as existsSync25, mkdirSync as mkdirSync10, readFileSync as readFileSync18, writeFileSync as writeFileSync14 } from "node:fs";
+import { existsSync as existsSync25, mkdirSync as mkdirSync10, readFileSync as readFileSync19, writeFileSync as writeFileSync15 } from "node:fs";
 import { homedir as homedir12 } from "node:os";
-import { join as join15 } from "node:path";
+import { join as join16 } from "node:path";
 async function syncToBroker(meshSlug, grants) {
   const auth = getStoredToken();
   if (!auth)
@@ -13358,16 +13546,16 @@ function readGrants() {
   if (!existsSync25(GRANT_FILE))
     return {};
   try {
-    return JSON.parse(readFileSync18(GRANT_FILE, "utf-8"));
+    return JSON.parse(readFileSync19(GRANT_FILE, "utf-8"));
   } catch {
     return {};
   }
 }
 function writeGrants(g) {
-  const dir = join15(homedir12(), ".claudemesh");
+  const dir = join16(homedir12(), ".claudemesh");
   if (!existsSync25(dir))
     mkdirSync10(dir, { recursive: true });
-  writeFileSync14(GRANT_FILE, JSON.stringify(g, null, 2), { mode: 384 });
+  writeFileSync15(GRANT_FILE, JSON.stringify(g, null, 2), { mode: 384 });
 }
 function resolveCaps(input) {
   if (input.includes("all"))
@@ -13523,7 +13711,7 @@ var init_grants = __esm(() => {
   BROKER_HTTP7 = URLS.BROKER.replace("wss://", "https://").replace("ws://", "http://").replace("/ws", "");
   ALL_CAPS = ["read", "dm", "broadcast", "state-read", "state-write", "file-read"];
   DEFAULT_CAPS = ["read", "dm", "broadcast", "state-read"];
-  GRANT_FILE = join15(homedir12(), ".claudemesh", "grants.json");
+  GRANT_FILE = join16(homedir12(), ".claudemesh", "grants.json");
 });
 
 // src/commands/profile.ts
@@ -14595,15 +14783,56 @@ Once \`claudemesh install\` has run (registers MCP entry + starts daemon service
 | \`--groups "name:role,name2:role2,all"\` | the group selection prompt | comma-separated \`<groupname>:<role>\` entries; the literal \`all\` joins \`@all\` |
 | \`--role <lead\\|member\\|observer>\` | the role prompt | applied to all groups in \`--groups\` that didn't specify their own |
 | \`--message-mode <push\\|inbox>\` | the message-mode prompt | \`push\` (default) emits \`<channel>\` notifications mid-turn; \`inbox\` only buffers — quieter for headless agents |
-| \`--system-prompt <path>\` | nothing — pure pass-through | forwarded to \`claude --append-system-prompt\` |
+| \`--system-prompt <text>\` | nothing — pure pass-through | forwarded to \`claude --system-prompt\` (overrides default; pass a string, not a path) |
 | \`--resume <session-id>\` | nothing — pure pass-through | forwarded to \`claude --resume\` to continue a prior Claude Code session |
-| \`--continue\` | nothing — pure pass-through | forwarded to \`claude --continue\` |
+| \`--continue\` | nothing — pure pass-through | forwarded to \`claude --continue\` (resumes the last session in this cwd) |
 | \`-y\` / \`--yes\` | every confirmation prompt | including the "you'll skip ALL permission prompts" gate. **Use for autonomous agents; omit for shared/multi-person meshes.** |
-| \`-q\` / \`--quiet\` | the welcome banner | useful when the spawning script wants clean stdout |
+| \`--quiet\` | the wizard + welcome banner | suppresses the launch wizard and banner. Combine with \`-y\` for true headless: \`--quiet\` alone won't bypass Claude's permission prompts, so a script using only \`--quiet\` will hang on the first tool call. |
 | \`--\` | (separator) | everything after \`--\` is forwarded verbatim to \`claude\`. Example: \`claudemesh launch --name X -y -- --resume abc123 --model opus\` |
 
+> **All twelve flags are end-to-end wired as of \`claudemesh-cli@1.27.1\`.** Earlier builds silently dropped \`--role\`, \`--groups\`, \`--message-mode\`, \`--system-prompt\`, \`--continue\`, and \`--quiet\` at the CLI entrypoint — they were declared but never reached \`runLaunch\`. If a script targets older versions, those flags are no-ops.
+
 ### Wizard-free spawn templates
 
+#### Canonical fully-populated spawn (every flag set explicitly)
+
+The kitchen-sink form — copy, set every value, and the session boots without a single interactive prompt or banner. Use as a base when scripting from cron, hooks, CI, or another agent:
+
+\`\`\`bash
+claudemesh launch \\
+  --name "ci-bot" \\
+  --mesh openclaw \\
+  --role member \\
+  --groups "frontend:lead,reviewers:observer,all" \\
+  --message-mode inbox \\
+  --system-prompt "$(cat ~/agents/ci-bot.md)" \\
+  --quiet \\
+  -y \\
+  -- \\
+  --model opus \\
+  --resume "$LAST_SESSION_ID"
+\`\`\`
+
+Annotated:
+
+| Position | Value | Effect |
+|---|---|---|
+| \`--name "ci-bot"\` | identity | what peers see in \`peer list\` and \`<channel from_name>\` — pin so peers always see the same name across machines |
+| \`--mesh openclaw\` | workspace | required when you have ≥2 joined meshes; safe to include even with 1 (becomes a no-op assertion) |
+| \`--role member\` | session label | free-form tag used by group conventions; common values: \`lead\`, \`member\`, \`observer\`, \`bot\`, \`oncall\` |
+| \`--groups "frontend:lead,..."\` | group memberships | comma-separated \`<group>:<role>\` pairs; bare \`all\` joins \`@all\` with no role |
+| \`--message-mode inbox\` | delivery | \`push\` interrupts mid-turn (default); \`inbox\` buffers silently; \`off\` disables messages but keeps tool calls |
+| \`--system-prompt "..."\` | claude system prompt | overrides Claude's default. Pass a string, not a path — wrap with \`$(cat …)\` if you keep prompts in files |
+| \`--quiet\` | output | suppress the wizard and banner — clean stdout for the spawning script |
+| \`-y\` | consent | skips every permission prompt (claudemesh's policy gate **and** Claude's \`--dangerously-skip-permissions\`). Required for true headless |
+| \`--\` | separator | everything after is passed verbatim to \`claude\` |
+| \`--model opus\` | claude flag | example claude-side override |
+| \`--resume "$LAST_SESSION_ID"\` | claude flag | resume a prior Claude session inside this mesh identity |
+
+**Rule of thumb:** for any unattended spawn, the minimum is \`--name + --mesh + -y + --quiet\`. Add \`--system-prompt\` to seed task context, \`--message-mode inbox\` to keep the bot quiet, and \`--role\` + \`--groups\` so peers know how to address it. Drop \`--quiet\` when a human is watching the script's stdout.
+
+#### Trimmed templates
+
 \`\`\`bash
 # Minimal — single joined mesh, fresh agent, autonomous:
 claudemesh launch --name "Lug Nut" -y
@@ -14624,9 +14853,9 @@ claudemesh launch --name "Mou" --mesh openclaw -y -- --resume abc123-...
 
 # Quiet, headless, system-prompt loaded — for cron / hooks:
 claudemesh launch --name "ci-bot" --mesh openclaw \\
-  --system-prompt /path/to/ci-bot.md \\
+  --system-prompt "$(cat ~/agents/ci-bot.md)" \\
   --message-mode inbox \\
-  -q -y
+  --quiet -y
 \`\`\`
 
 If any required flag is missing AND stdin is a TTY, \`launch\` falls back to its prompt for that single field. **In a non-TTY context (Bash tool, cron, AppleScript pipe), missing flags cause the verb to fail-closed — never silently use a default that affects identity.**
@@ -15164,7 +15393,7 @@ __export(exports_file, {
 });
 import { hostname as osHostname } from "node:os";
 import { resolve as resolvePath, basename, dirname as dirname9 } from "node:path";
-import { statSync as statSync6, existsSync as existsSync26, writeFileSync as writeFileSync15, mkdirSync as mkdirSync11 } from "node:fs";
+import { statSync as statSync7, existsSync as existsSync26, writeFileSync as writeFileSync16, mkdirSync as mkdirSync11 } from "node:fs";
 function emitJson2(data) {
   console.log(JSON.stringify(data, null, 2));
 }
@@ -15185,7 +15414,7 @@ async function runFileShare(filePath, opts) {
     render.err(`File not found: ${absPath}`);
     return EXIT.INVALID_ARGS;
   }
-  const stat = statSync6(absPath);
+  const stat = statSync7(absPath);
   if (!stat.isFile()) {
     render.err(`Not a regular file: ${absPath}`);
     return EXIT.INVALID_ARGS;
@@ -15261,7 +15490,7 @@ async function runFileGet(fileId, opts) {
     const buf = Buffer.from(await res.arrayBuffer());
     const outPath = opts.out ? resolvePath(opts.out) : resolvePath(process.cwd(), meta.name);
     mkdirSync11(dirname9(outPath), { recursive: true });
-    writeFileSync15(outPath, buf);
+    writeFileSync16(outPath, buf);
     if (opts.json) {
       emitJson2({ fileId, name: meta.name, savedTo: outPath, sizeBytes: buf.length });
     } else {
@@ -15871,7 +16100,7 @@ __export(exports_bridge, {
   runBridge: () => runBridge,
   bridgeConfigTemplate: () => bridgeConfigTemplate
 });
-import { readFileSync as readFileSync19, existsSync as existsSync27 } from "node:fs";
+import { readFileSync as readFileSync20, existsSync as existsSync27 } from "node:fs";
 function parseConfig(text) {
   const trimmed = text.trim();
   if (trimmed.startsWith("{"))
@@ -15921,7 +16150,7 @@ async function runBridge(configPath) {
   }
   let cfg;
   try {
-    cfg = parseConfig(readFileSync19(configPath, "utf-8"));
+    cfg = parseConfig(readFileSync20(configPath, "utf-8"));
   } catch (e) {
     render.err(`failed to parse ${configPath}: ${e instanceof Error ? e.message : String(e)}`);
     return EXIT.INVALID_ARGS;
@@ -19197,4 +19426,4 @@ main().catch((err) => {
   process.exit(EXIT.INTERNAL_ERROR);
 });
 
-//# debugId=BE929AB7D782557264756E2164756E21
+//# debugId=1F2A51E3A3AE432A64756E2164756E21