@aiaiai-pt/martha-cli 0.51.7 → 0.53.1

package/dist/index.js

@@ -9339,7 +9339,7 @@ async function loginClientCredentials(opts) {
   });
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`Client credentials login failed (${res.status}): ${text}`);
+    throw new CLIError(`Client credentials login failed (${res.status}): ${text}`, 2 /* Auth */, "Check MARTHA_CLIENT_ID / MARTHA_CLIENT_SECRET and that the profile's keycloak_url + keycloak_realm match the principal.");
   }
   const data = await res.json();
   const now = Math.floor(Date.now() / 1000);
@@ -9356,6 +9356,7 @@ async function loginClientCredentials(opts) {
 }
 var init_client_credentials = __esm(() => {
   init_token_store();
+  init_errors();
 });
 
 // src/lib/sse.ts
@@ -10726,6 +10727,13 @@ async function refreshAccessToken(opts) {
 // src/lib/context.ts
 init_api_client();
 init_errors();
+function belongsToClient(tokens, clientId) {
+  if (tokens.auth_type !== "client_credentials")
+    return false;
+  const claims = decodeJwtPayload(tokens.access_token);
+  const azp = claims?.azp ?? claims?.client_id;
+  return azp ? azp === clientId : true;
+}
 function createContext(opts) {
   const config = loadConfig(opts.configDir);
   const profileName = opts.profileOverride ?? process.env.MARTHA_PROFILE ?? config.current_profile;
@@ -10743,8 +10751,9 @@ function createContext(opts) {
     if (envClientId && envSecret) {
       if (!tokenStore.needsRefresh(profileName)) {
         const existing = tokenStore.getTokens(profileName);
-        if (existing)
+        if (existing && belongsToClient(existing, envClientId)) {
           return existing.access_token;
+        }
       }
       const { loginClientCredentials: loginClientCredentials2 } = await Promise.resolve().then(() => (init_client_credentials(), exports_client_credentials));
       const tokens2 = await loginClientCredentials2({
@@ -11120,7 +11129,7 @@ init_config();
 init_errors();
 
 // src/version.ts
-var CLI_VERSION = "0.51.7";
+var CLI_VERSION = "0.53.1";
 
 // src/commands/sessions.ts
 function relativeTime(iso) {
@@ -11396,6 +11405,48 @@ Then drive it from chat:`));
   console.log(source_default.dim(`
 Check it's connected any time:  martha agents doctor ${r.agent}`));
 }
+function printChecks(checks, write = (line) => console.log(line)) {
+  for (const c of checks) {
+    const glyph = c.ok === true ? source_default.green("PASS") : c.ok === false ? source_default.red("FAIL") : source_default.yellow("WARN");
+    const detail = c.detail ? source_default.dim(c.detail) : "";
+    write(`  ${glyph}  ${c.label.padEnd(32)} ${detail}`);
+    if (c.ok !== true && c.fix) {
+      write(`         ${source_default.dim("→ " + c.fix)}`);
+    }
+  }
+}
+var CLIENT_SCAN_CAP = 200;
+var CLIENT_SCAN_CONCURRENCY = 8;
+async function scanClientsForAgent(ctx, agentName, opts = {}) {
+  const subPath = opts.subPath ?? "agents";
+  const clientsResp = await ctx.api.get("/api/admin/clients");
+  const clients = Array.isArray(clientsResp) ? clientsResp : clientsResp?.clients ?? clientsResp?.items ?? [];
+  const target = clients.slice(0, CLIENT_SCAN_CAP);
+  const granting = [];
+  let failed = false;
+  for (let i = 0;i < target.length; i += CLIENT_SCAN_CONCURRENCY) {
+    const batch = target.slice(i, i + CLIENT_SCAN_CONCURRENCY);
+    const results = await Promise.all(batch.map(async (c) => {
+      try {
+        const rows = await ctx.api.get(`/api/admin/definitions/clients/${c.id}/${subPath}`);
+        const names = (Array.isArray(rows) ? rows : []).map((r) => String(r.name ?? r.agent_name ?? "")).filter(Boolean);
+        const ids = (Array.isArray(rows) ? rows : []).map((r) => String(r.agent_id ?? r.id ?? ""));
+        const hit = names.includes(agentName) || !!opts.agentId && ids.includes(opts.agentId);
+        return hit ? { client: String(c.name ?? c.id), agents: names } : null;
+      } catch {
+        failed = true;
+        return null;
+      }
+    }));
+    granting.push(...results.filter((r) => !!r));
+  }
+  return {
+    granting,
+    scanned: target.length,
+    total: clients.length,
+    incomplete: failed || clients.length > CLIENT_SCAN_CAP
+  };
+}
 async function diagnoseHostRunner(ctx, name) {
   const A = `${API_PATH}/${encodeURIComponent(name)}`;
   const checks = [];
@@ -11446,25 +11497,18 @@ async function diagnoseHostRunner(ctx, name) {
     detail: hostTools.length ? hostTools.join(", ") : "none",
     fix: hostTools.length ? undefined : setupFix
   });
-  let grantingClients = [];
+  let scan = null;
   try {
-    const clientsResp = await ctx.api.get("/api/admin/clients");
-    const clientList = Array.isArray(clientsResp) ? clientsResp : clientsResp?.clients ?? clientsResp?.items ?? [];
-    const probes = await Promise.all(clientList.slice(0, 25).map(async (c) => {
-      try {
-        const acc = await ctx.api.get(`/api/admin/definitions/clients/${c.id}/agents/access`);
-        const has = (Array.isArray(acc) ? acc : []).some((r) => String(r.agent_name ?? r.name ?? "") === name || String(r.agent_id ?? "") === String(def.id ?? ""));
-        return has ? String(c.name ?? c.id) : null;
-      } catch {
-        return null;
-      }
-    }));
-    grantingClients = probes.filter((x) => !!x);
+    scan = await scanClientsForAgent(ctx, name, {
+      subPath: "agents/access",
+      agentId: String(def.id ?? "")
+    });
   } catch {}
+  const grantingClients = scan?.granting.map((g) => g.client) ?? [];
   checks.push({
-    ok: grantingClients.length > 0,
+    ok: grantingClients.length > 0 ? true : !scan || scan.incomplete ? null : false,
     label: "a chat client can select it",
-    detail: grantingClients.length ? grantingClients.join(", ") : "no client granted access",
+    detail: grantingClients.length ? grantingClients.join(", ") : !scan ? "could not read the client list" : scan.incomplete ? `inconclusive — read ${scan.scanned} of ${scan.total} clients` : "no client granted access",
     fix: grantingClients.length ? undefined : setupFix
   });
   const takeover = def.runs_as_chat === true;
@@ -11865,14 +11909,7 @@ Attach it as this agent's host executor:
       }
       console.log(source_default.bold(`Martha CLI doctor — host runner: ${agent}
 `));
-      for (const c of dx.checks) {
-        const glyph = c.ok === true ? source_default.green("PASS") : c.ok === false ? source_default.red("FAIL") : source_default.yellow("WARN");
-        const detail = c.detail ? source_default.dim(c.detail) : "";
-        console.log(`  ${glyph}  ${c.label.padEnd(32)} ${detail}`);
-        if (c.ok === false && c.fix) {
-          console.log(`         ${source_default.dim("→ " + c.fix)}`);
-        }
-      }
+      printChecks(dx.checks);
       console.log();
       if (dx.drivableFromChat && dx.runnerAttached) {
         console.log(source_default.green.bold("Ready — a runner is attached and the agent can be driven from chat."));
@@ -14209,10 +14246,1062 @@ function parseTimeoutSeconds(raw) {
   return n;
 }
 
+// src/commands/acp-serve.ts
+import { createInterface as createInterface3 } from "node:readline";
+import { execFile } from "node:child_process";
+init_errors();
+function logJson(level, msg, fields) {
+  process.stderr.write(JSON.stringify({ ts: new Date().toISOString(), level, msg, ...fields }) + `
+`);
+}
+function extractPromptText(prompt) {
+  if (!Array.isArray(prompt))
+    return "";
+  return prompt.filter((b) => typeof b === "object" && b !== null && b.type === "text" && typeof b.text === "string").map((b) => b.text).join(`
+
+`);
+}
+function parseBuzzReplyTarget(promptText) {
+  const uuid = "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}";
+  const named = promptText.match(new RegExp(`Channel:[^\\n]*\\(#(${uuid})\\)`));
+  const bare = promptText.match(new RegExp(`Channel:\\s*(${uuid})`));
+  const channelId = named?.[1] ?? bare?.[1];
+  const instructed = promptText.match(/--reply-to\s+([0-9a-f]{64})/);
+  if (instructed)
+    return { channelId, replyTo: instructed[1] };
+  const steered = promptText.match(/root=([0-9a-f]{64})/);
+  if (steered)
+    return { channelId, replyTo: steered[1] };
+  const newRoot = promptText.match(/Event ID:\s*([0-9a-f]{64})/);
+  if (newRoot)
+    return { channelId, replyTo: newRoot[1] };
+  return { channelId, replyTo: undefined };
+}
+function agentMessageChunk(sessionId, text) {
+  return {
+    jsonrpc: "2.0",
+    method: "session/update",
+    params: {
+      sessionId,
+      update: {
+        sessionUpdate: "agent_message_chunk",
+        content: { type: "text", text }
+      }
+    }
+  };
+}
+function classifyPrompt(promptText) {
+  const kinds = [...promptText.matchAll(/^\s*Kind:\s*(\d+)/gm)].map((m) => Number(m[1]));
+  if (kinds.length > 0 && kinds.every((k) => k === 7))
+    return "reaction";
+  return "message";
+}
+function captureDeliveryTarget(promptText) {
+  const { channelId, replyTo } = parseBuzzReplyTarget(promptText);
+  if (!channelId)
+    return null;
+  return { channelId, threadRef: replyTo };
+}
+async function deliverToChannel(buzzBin, target, text) {
+  const args = ["messages", "send", "--channel", target.channelId, "--content", text];
+  if (target.threadRef)
+    args.push("--reply-to", target.threadRef);
+  const send = () => new Promise((resolve2) => {
+    execFile(buzzBin, args, { timeout: 20000, maxBuffer: 1024 * 1024 }, (err, stdout, stderr) => {
+      resolve2({
+        ok: !err,
+        out: stdout?.slice(0, 2000) ?? "",
+        err: err ? `${err.message}
+${stderr ?? ""}`.slice(0, 2000) : ""
+      });
+    });
+  });
+  let res = await send();
+  if (!res.ok) {
+    await new Promise((r) => setTimeout(r, 750));
+    res = await send();
+  }
+  if (res.ok) {
+    logJson("info", "delivered to channel", {
+      channel: target.channelId,
+      thread_ref: target.threadRef,
+      output: res.out
+    });
+  } else {
+    logJson("error", "delivery failed — answer NOT relocated", {
+      channel: target.channelId,
+      thread_ref: target.threadRef,
+      error: res.err,
+      undelivered: text.slice(0, 4000)
+    });
+  }
+}
+async function runAcpServer(ctx, input, output, opts) {
+  const sessions = new Map;
+  let writeChain = Promise.resolve();
+  const writeLine = (msg) => {
+    writeChain = writeChain.then(() => new Promise((resolve2) => {
+      output.write(JSON.stringify(msg) + `
+`, () => resolve2());
+    }));
+    return writeChain;
+  };
+  const respond = (id, result) => writeLine({ jsonrpc: "2.0", id, result });
+  const respondError = (id, code, message) => writeLine({ jsonrpc: "2.0", id, error: { code, message } });
+  async function handlePrompt(id, params) {
+    const sessionId = typeof params.sessionId === "string" ? params.sessionId : "";
+    const session = sessions.get(sessionId);
+    if (!session) {
+      await respondError(id, -32602, `unknown sessionId: ${sessionId}`);
+      return;
+    }
+    if (session.inFlight) {
+      await respondError(id, -32000, "another prompt is already in flight for this session");
+      return;
+    }
+    const text = extractPromptText(params.prompt);
+    if (!text) {
+      await respondError(id, -32602, "prompt contains no text content blocks");
+      return;
+    }
+    if (classifyPrompt(text) === "reaction") {
+      logJson("info", "reaction observed — feedback, not a request", {
+        session_id: sessionId,
+        excerpt: text.slice(0, 300)
+      });
+      await respond(id, { stopReason: "end_turn" });
+      return;
+    }
+    const abort = new AbortController;
+    session.inFlight = abort;
+    logJson("info", "session/prompt started", {
+      session_id: sessionId,
+      prompt_chars: text.length
+    });
+    try {
+      const result = await sendMessage(ctx, sessionId, text, {
+        signal: abort.signal,
+        clientId: opts.clientId,
+        agentName: opts.agentName,
+        timeoutMs: opts.timeoutMs,
+        onToken: (token) => {
+          writeLine(agentMessageChunk(sessionId, token));
+        }
+      });
+      if (result.aborted) {
+        logJson("info", "session/prompt cancelled", { session_id: sessionId });
+        session.inFlight = null;
+        await respond(id, { stopReason: "cancelled" });
+        return;
+      }
+      if (opts.postReply) {
+        const target = captureDeliveryTarget(text);
+        if (target) {
+          await deliverToChannel(opts.buzzBin, target, result.response);
+        } else {
+          logJson("warn", "no channel in prompt — nothing to deliver to");
+        }
+      }
+      logJson("info", "session/prompt completed", {
+        session_id: sessionId,
+        response_chars: result.response.length
+      });
+      session.inFlight = null;
+      await respond(id, { stopReason: "end_turn" });
+    } catch (err) {
+      session.inFlight = null;
+      if (abort.signal.aborted) {
+        await respond(id, { stopReason: "cancelled" });
+        return;
+      }
+      const message = err instanceof MarthaAPIError ? `Martha API ${err.status}: ${err.message}` : err instanceof Error ? err.message : String(err);
+      logJson("error", "session/prompt failed", {
+        session_id: sessionId,
+        error: message
+      });
+      await respondError(id, -32000, message);
+    }
+  }
+  async function dispatch(msg) {
+    const { id, method } = msg;
+    const params = msg.params ?? {};
+    if (!method)
+      return;
+    switch (method) {
+      case "initialize": {
+        const requested = params.protocolVersion;
+        await respond(id, {
+          protocolVersion: typeof requested === "number" ? requested : 1,
+          agentCapabilities: {
+            loadSession: false,
+            promptCapabilities: {
+              image: false,
+              audio: false,
+              embeddedContext: false
+            }
+          },
+          authMethods: [],
+          agentInfo: { name: "martha-acp-serve", version: CLI_VERSION }
+        });
+        logJson("info", "initialized", { client: params.clientInfo });
+        break;
+      }
+      case "session/new": {
+        if (params.systemPrompt) {
+          logJson("warn", "session/new: systemPrompt ignored in v1", {
+            chars: String(params.systemPrompt).length
+          });
+        }
+        try {
+          const sessionId = await createSession(ctx, opts.clientId);
+          sessions.set(sessionId, { inFlight: null });
+          logJson("info", "session created", { session_id: sessionId });
+          await respond(id, { sessionId });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          logJson("error", "session/new failed", { error: message });
+          await respondError(id, -32000, message);
+        }
+        break;
+      }
+      case "session/prompt":
+        handlePrompt(id, params);
+        break;
+      case "session/cancel": {
+        const sessionId = typeof params.sessionId === "string" ? params.sessionId : "";
+        const session = sessions.get(sessionId);
+        if (session?.inFlight) {
+          logJson("info", "session/cancel: aborting in-flight prompt", {
+            session_id: sessionId
+          });
+          session.inFlight.abort();
+        } else {
+          logJson("debug", "session/cancel: nothing in flight", {
+            session_id: sessionId
+          });
+        }
+        break;
+      }
+      case "session/set_config_option":
+      case "session/set_model":
+        logJson("debug", `${method} ignored (v1 fence)`, { params });
+        if (id !== undefined && id !== null)
+          await respond(id, {});
+        break;
+      case "authenticate":
+        if (id !== undefined && id !== null)
+          await respond(id, {});
+        break;
+      default:
+        if (id !== undefined && id !== null) {
+          await respondError(id, -32601, `Method not found: ${method}`);
+        } else {
+          logJson("debug", "ignoring unknown notification", { method });
+        }
+    }
+  }
+  const rl = createInterface3({ input, terminal: false });
+  for await (const line of rl) {
+    const trimmed = line.trim();
+    if (!trimmed)
+      continue;
+    let msg;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      logJson("warn", "skipping non-JSON input line", {
+        head: trimmed.slice(0, 120)
+      });
+      continue;
+    }
+    await dispatch(msg);
+  }
+  await writeChain;
+  logJson("info", "stdin closed — exiting");
+}
+async function probeStartup(ctx) {
+  try {
+    const who = await ctx.api.get("/api/tasks/whoami");
+    logJson("info", "authenticated", { kind: who.kind, subject: who.subject });
+  } catch (err) {
+    if (err instanceof MarthaAPIError && (err.status === 401 || err.status === 403)) {
+      throw new CLIError(`ACP startup failed: Martha API rejected the credential (${err.status}: ${err.message})`, 2 /* Auth */, "Set MARTHA_CLIENT_ID/MARTHA_CLIENT_SECRET (bootstrap integration principal), or MARTHA_TOKEN, or run `martha auth login`.");
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    throw new CLIError(`ACP startup failed: cannot reach Martha API at ${ctx.profile.api_url}: ${message}`, 1 /* Error */, "Check the API URL (--api-url / profile) and that the Martha API is up.");
+  }
+}
+function registerAcpServeCommand(program2) {
+  program2.command("acp-serve").description("Serve the Agent Client Protocol over stdio (newline-delimited JSON-RPC 2.0) so an ACP harness like Buzz's buzz-acp can drive a Martha agent").option("--client <nameOrId>", "Use a specific client id for the Martha session").option("--agent <name>", "Drive turns with a specific Martha agent (defaults to the credential/profile binding)").option("--post-reply", "After each completed turn, post the final answer back to the triggering Buzz channel via the `buzz` CLI (parsed from the prompt's [Context] section)").option("--buzz-bin <path>", "Path to the buzz CLI for --post-reply", "buzz").option("--timeout <seconds>", "Per-prompt HTTP timeout in seconds (default: 600)").action(async (opts) => {
+    const ctx = createContext({
+      profileOverride: program2.opts().profile,
+      apiUrlOverride: program2.opts().apiUrl,
+      verbose: program2.opts().verbose
+    });
+    const timeoutMs = opts.timeout ? Math.max(1, Number(opts.timeout)) * 1000 : undefined;
+    logJson("info", "martha acp-serve starting", {
+      version: CLI_VERSION,
+      api_url: ctx.profile.api_url,
+      post_reply: !!opts.postReply
+    });
+    await probeStartup(ctx);
+    logJson("info", "startup probe ok — speaking ACP on stdio");
+    await runAcpServer(ctx, process.stdin, process.stdout, {
+      clientId: opts.client,
+      agentName: opts.agent,
+      postReply: !!opts.postReply,
+      buzzBin: opts.buzzBin,
+      timeoutMs
+    });
+  });
+}
+
+// src/commands/principals.ts
+init_errors();
+var AGENTS_PATH = "/api/admin/definitions/agents";
+var BOOTSTRAP_PATH = "/api/admin/definitions/principals/bootstrap";
+function parseIntents(raw) {
+  return (raw ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+}
+async function bootstrapAgentPrincipal(ctx, agent, opts = {}) {
+  const A = `${AGENTS_PATH}/${encodeURIComponent(agent)}`;
+  const steps = [];
+  const warnings = [];
+  let def = null;
+  try {
+    def = await ctx.api.get(A);
+  } catch (e) {
+    if (!(e instanceof MarthaAPIError && e.status === 404))
+      throw e;
+  }
+  if (!def) {
+    if (!opts.prompt) {
+      throw new CLIError(`Agent '${agent}' not found.`, 3 /* NotFound */, `Pass --prompt "<system prompt>" to create it, or create it first with: martha agents create --name ${agent} --reasoning martha --prompt "..."`);
+    }
+    const deliveryNote = `
+
+When a message asks you to reply in a channel, reply with the ` + "message content ONLY — delivery is handled for you. Never output " + "delivery commands (e.g. `buzz messages send`).";
+    def = await ctx.api.post(AGENTS_PATH, {
+      name: agent,
+      system_prompt: opts.prompt + deliveryNote,
+      agent_type: "cloud",
+      runs_as_chat: true,
+      description: "Agent principal for external drivers (#1117)"
+    });
+    steps.push(`created Martha-hosted agent '${agent}' (runs_as_chat)`);
+  } else {
+    if (String(def.agent_type ?? "") === "external") {
+      throw new CLIError(`Agent '${agent}' is self-hosted (reasoning runs in your own service). ` + `An agent principal drives a Martha-hosted agent — recreate it with --reasoning martha.`, 4 /* Validation */);
+    }
+    if (def.runs_as_chat !== true) {
+      await ctx.api.put(A, { runs_as_chat: true });
+      steps.push("enabled chat takeover (runs_as_chat)");
+    }
+  }
+  const agentName = String(def?.name ?? agent);
+  const boot = await ctx.api.post(BOOTSTRAP_PATH, {
+    mode: "integration",
+    label: opts.label ?? agentName,
+    intents: parseIntents(opts.intents)
+  });
+  if (!boot.service_account || boot.client_id == null) {
+    throw new CLIError("Bootstrap did not return service-account credentials.", 1 /* Error */, "Check that your user has the admin realm role (integration mode requires it).");
+  }
+  steps.push(boot.adopted ? `reusing principal '${boot.service_account.client_id}' (same secret — recovery, not rotation)` : `provisioned principal '${boot.service_account.client_id}'`);
+  const granted = await ctx.api.get(`/api/admin/definitions/clients/${boot.client_id}/agents`);
+  const names = granted.map((g) => String(g.name ?? g.agent_name ?? ""));
+  if (!names.includes(agentName)) {
+    await ctx.api.post(`/api/admin/definitions/clients/${boot.client_id}/agents`, { agent_name: agentName });
+    steps.push(`bound '${agentName}' to client ${boot.client_id}`);
+  } else {
+    steps.push(`'${agentName}' already bound to client ${boot.client_id}`);
+  }
+  const others = names.filter((n) => n && n !== agentName);
+  if (others.length) {
+    warnings.push(`client ${boot.client_id} also has agent(s) ${others.join(", ")} — chat takeover requires exactly ONE bound agent; revoke the others or use a fresh --label.`);
+  }
+  return {
+    agent: agentName,
+    clientId: boot.client_id,
+    clientKey: boot.client_key ?? boot.service_account.client_id,
+    saClientId: boot.service_account.client_id,
+    saClientSecret: boot.service_account.client_secret,
+    tokenEndpoint: boot.service_account.token_endpoint,
+    steps,
+    warnings
+  };
+}
+function printAgentPrincipalReady(r) {
+  console.log(source_default.bold.green(`
+✓ agent principal ready — the credential acts as '${r.agent}'
+`));
+  for (const s of r.steps)
+    console.log(source_default.dim(`  • ${s}`));
+  for (const w of r.warnings)
+    console.log(source_default.yellow(`  ! ${w}`));
+  console.log();
+  console.log(source_default.bold("Service-account secret (shown once — store it like one):"));
+  console.log(source_default.cyan(`  export MARTHA_CLIENT_ID=${r.saClientId}
+` + `  export MARTHA_CLIENT_SECRET=${r.saClientSecret}`));
+  console.log(source_default.dim("  The host also needs a Martha profile (api_url + keycloak): run `martha init` once."));
+  console.log();
+  console.log("Any ACP client can now drive the agent via `martha acp-serve`. For Buzz,\n" + "let the CLI check the preconditions and start the adapter for you:");
+  console.log(source_default.cyan(`  export BUZZ_PRIVATE_KEY=<agent nsec>        # buzz-admin generate-key
+` + `  martha channels connect buzz --agent ${r.agent} --relay ws://<relay>:<port>`));
+  console.log(source_default.dim(`
+  It names anything missing (buzz-acp, the buzz CLI, membership, …) and
+` + `  exits rather than half-starting. Starting from Buzz Desktop instead?
+` + "  `martha channels install-harness buzz`, then pick Martha in New agent."));
+  console.log(source_default.dim(`
+  Then: buzz channels add-member --channel <id> --pubkey <agent pubkey> --role member
+` + "  and @mention the agent in the channel."));
+}
+function registerPrincipalCommands(program2) {
+  const principals = program2.command("principals").description("Provision principals — who may act, with what credential (mirrors the API's principals/bootstrap)");
+  principals.command("bootstrap").description("Provision a principal. --mode human: your run-as client (what `martha init` wraps). " + "--mode integration: headless service account. --mode agent: service account bound " + "to ONE Martha-hosted agent (chat takeover) so the credential acts as the agent — " + "the shape an external ACP driver (Buzz, Zed) needs.").requiredOption("--mode <mode>", "human | integration | agent").option("--agent <name>", "Agent to bind (agent mode)").option("--prompt <text>", "System prompt — creates the agent when it doesn't exist yet (agent mode)").option("--label <label>", "Label for the service-account client id (default: the agent name in agent mode)").option("--intents <list>", "Comma-separated tool intents to grant (rag, documents, workflows, tasks)").action(async (opts) => {
+    const ctx = createContext({
+      profileOverride: program2.opts().profile,
+      apiUrlOverride: program2.opts().apiUrl,
+      verbose: program2.opts().verbose
+    });
+    const isJson = !!program2.opts().json;
+    switch (opts.mode) {
+      case "agent": {
+        if (!opts.agent) {
+          throw new CLIError("--mode agent requires --agent <name>", 4 /* Validation */);
+        }
+        const result = await bootstrapAgentPrincipal(ctx, opts.agent, {
+          label: opts.label,
+          prompt: opts.prompt,
+          intents: opts.intents
+        });
+        if (isJson) {
+          console.log(JSON.stringify({
+            mode: "agent",
+            agent: result.agent,
+            client_id: result.clientId,
+            client_key: result.clientKey,
+            martha_client_id: result.saClientId,
+            martha_client_secret: result.saClientSecret,
+            token_endpoint: result.tokenEndpoint,
+            steps: result.steps,
+            warnings: result.warnings
+          }, null, 2));
+          return;
+        }
+        printAgentPrincipalReady(result);
+        break;
+      }
+      case "integration":
+      case "human": {
+        const body = {
+          mode: opts.mode,
+          intents: parseIntents(opts.intents)
+        };
+        if (opts.label)
+          body.label = opts.label;
+        const resp = await ctx.api.post(BOOTSTRAP_PATH, body);
+        if (isJson) {
+          console.log(JSON.stringify(resp, null, 2));
+          return;
+        }
+        console.log(source_default.bold.green(`
+✓ ${opts.mode} principal ready
+`));
+        if (resp.service_account) {
+          console.log(source_default.bold("Service-account secret (shown once):"));
+          console.log(source_default.cyan(`  export MARTHA_CLIENT_ID=${resp.service_account.client_id}
+` + `  export MARTHA_CLIENT_SECRET=${resp.service_account.client_secret}`));
+          console.log(source_default.dim("  Re-running with the same --label returns this same secret (recovery, not rotation)."));
+        }
+        if (resp.granted_functions?.length) {
+          console.log(source_default.dim(`  functions: ${resp.granted_functions.join(", ")}`));
+        }
+        if (opts.mode === "human") {
+          console.log(source_default.dim("  Tip: `martha init` wraps this mode and also saves the client onto your profile."));
+        }
+        break;
+      }
+      default:
+        throw new CLIError(`Invalid --mode '${opts.mode}'. Use human | integration | agent.`, 4 /* Validation */);
+    }
+  });
+}
+
+// src/commands/channels.ts
+import { accessSync, constants, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync } from "node:fs";
+import { execFile as execFile2, spawn as spawn3 } from "node:child_process";
+import { homedir } from "node:os";
+import { join as join3 } from "node:path";
+init_errors();
+var AGENTS_PATH2 = "/api/admin/definitions/agents";
+var SUPPORTED_CHANNELS = ["buzz"];
+var BUZZ_HARNESS_ID = "martha";
+function buzzHarnessDefinition(opts = {}) {
+  return {
+    id: opts.id ?? BUZZ_HARNESS_ID,
+    label: opts.label ?? "Martha",
+    command: opts.command ?? "martha",
+    args: ["acp-serve", "--post-reply"],
+    env: { BUZZ_ACP_MULTIPLE_EVENT_HANDLING: "queue" },
+    installInstructionsUrl: "https://docs.martha.nomadriver.co/cli/buzz",
+    installHint: "npm i -g @aiaiai-pt/martha-cli"
+  };
+}
+function isValidHarnessId(id) {
+  return /^[a-z0-9_][a-z0-9_-]*$/.test(id);
+}
+function buzzAppDataCandidates(platform, env2, home) {
+  const ids = [
+    { build: "release", id: "xyz.block.buzz.app" },
+    { build: "dev", id: "xyz.block.buzz.app.dev" }
+  ];
+  const base = () => {
+    if (platform === "darwin")
+      return join3(home, "Library", "Application Support");
+    if (platform === "win32")
+      return env2.APPDATA ?? join3(home, "AppData", "Roaming");
+    return env2.XDG_DATA_HOME ?? join3(home, ".local", "share");
+  };
+  const root = base();
+  return ids.map(({ build, id }) => ({ build, dir: join3(root, id) }));
+}
+function chooseAppDataDir(candidates, exists) {
+  return candidates.find((c) => exists(c.dir)) ?? null;
+}
+function buzzAppCandidates(platform, env2, home) {
+  if (platform === "darwin") {
+    return ["/Applications/Buzz.app", join3(home, "Applications", "Buzz.app")];
+  }
+  if (platform === "win32") {
+    const base = env2.LOCALAPPDATA ?? join3(home, "AppData", "Local");
+    return [join3(base, "Programs", "Buzz")];
+  }
+  return [
+    "/opt/Buzz",
+    "/usr/bin/buzz-desktop",
+    join3(home, ".local", "bin", "buzz-desktop")
+  ];
+}
+var BUZZ_RELEASES_URL = "https://github.com/block/buzz/releases/latest";
+function missingAppDataMessage(candidates, appInstalled) {
+  const looked = candidates.map((c) => `  ${c.dir}  (${c.build})`).join(`
+`);
+  if (appInstalled) {
+    return `Buzz Desktop is installed but has never been launched — it creates its ` + `data directory on first run.
+
+Looked for:
+${looked}
+` + `Open Buzz Desktop once, then re-run this. Or pass --app-data <dir>.`;
+  }
+  return `Buzz Desktop is not installed on this machine. This command registers ` + `Martha as a runtime INSIDE Desktop, so there is nothing to register with.
+
+` + `Looked for:
+${looked}
+` + `Install it: ${BUZZ_RELEASES_URL}
+
+` + `If you do not want Desktop at all, you do not need this command — run the ` + `adapter yourself instead:
+  martha channels connect buzz --agent <name> --relay <url>`;
+}
+var DEFAULT_BUZZ_KINDS = "9,46010,40007,7";
+function buzzAcpEnv(opts) {
+  const env2 = {
+    BUZZ_RELAY_URL: opts.relayUrl,
+    BUZZ_ACP_AGENT_COMMAND: opts.marthaBin,
+    BUZZ_ACP_AGENT_ARGS: "acp-serve,--post-reply",
+    BUZZ_ACP_SUBSCRIBE: opts.subscribe,
+    BUZZ_ACP_MULTIPLE_EVENT_HANDLING: opts.multipleEventHandling,
+    BUZZ_ACP_RESPOND_TO: opts.respondTo
+  };
+  if (opts.subscribe === "all")
+    env2.BUZZ_ACP_KINDS = opts.kinds;
+  return env2;
+}
+function resolveOnPath(bin, env2, platform, isExecutable) {
+  if (bin.includes("/") || bin.includes("\\")) {
+    return isExecutable(bin) ? bin : null;
+  }
+  const exts = platform === "win32" ? (env2.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean) : [""];
+  const sep = platform === "win32" ? ";" : ":";
+  for (const dir of (env2.PATH ?? "").split(sep).filter(Boolean)) {
+    for (const ext of exts) {
+      const candidate = join3(dir, bin + ext);
+      if (isExecutable(candidate))
+        return candidate;
+    }
+  }
+  return null;
+}
+function executableOnDisk(p) {
+  try {
+    accessSync(p, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function which(bin) {
+  return resolveOnPath(bin, process.env, process.platform, executableOnDisk);
+}
+function runBin(bin, args, env2) {
+  return new Promise((resolve2) => {
+    execFile2(bin, args, { env: env2, timeout: 15000, maxBuffer: 4 * 1024 * 1024 }, (err, stdout, stderr) => {
+      const code = err && typeof err.code === "number" ? err.code ?? 1 : err ? 1 : 0;
+      resolve2({
+        code,
+        stdout: stdout ?? "",
+        stderr: (stderr ?? "").slice(0, 2000)
+      });
+    });
+  });
+}
+async function reachable(url) {
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
+    return { ok: true, detail: `${url} → HTTP ${res.status}` };
+  } catch (err) {
+    return {
+      ok: false,
+      detail: `${url} unreachable: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+}
+function relayHttpUrl(relayUrl) {
+  return relayUrl.replace(/^ws:/, "http:").replace(/^wss:/, "https:");
+}
+async function preflightBuzz(ctx, opts) {
+  const checks = [];
+  const marthaPath = which(opts.marthaBin);
+  checks.push({
+    ok: !!marthaPath,
+    label: "martha CLI on PATH",
+    detail: marthaPath ?? `'${opts.marthaBin}' not found`,
+    fix: marthaPath ? undefined : "install it: npm i -g @aiaiai-pt/martha-cli (buzz-acp spawns it by name)"
+  });
+  if (marthaPath) {
+    const probe = await runBin(marthaPath, ["--help"], process.env);
+    const supported = /^\s+acp-serve\b/m.test(probe.stdout);
+    checks.push({
+      ok: supported,
+      label: "that martha can serve ACP",
+      detail: supported ? "acp-serve available" : `${marthaPath} has no acp-serve subcommand`,
+      fix: supported ? undefined : "upgrade the CLI that is FIRST on PATH: npm i -g @aiaiai-pt/martha-cli@latest (or point --martha-bin at the right one)"
+    });
+  }
+  const acpPath = which(opts.buzzAcpBin);
+  checks.push({
+    ok: !!acpPath,
+    label: "buzz-acp on PATH",
+    detail: acpPath ?? `'${opts.buzzAcpBin}' not found`,
+    fix: acpPath ? undefined : "build it from block/buzz: cargo build -p buzz-acp, then put target/debug on PATH (or pass --buzz-acp-bin)"
+  });
+  const buzzPath = which(opts.buzzBin);
+  checks.push({
+    ok: !!buzzPath,
+    label: "buzz CLI on PATH",
+    detail: buzzPath ?? `'${opts.buzzBin}' not found`,
+    fix: buzzPath ? undefined : "build it from block/buzz: cargo build -p buzz-cli — acp-serve --post-reply shells it to deliver the answer"
+  });
+  let whoami = null;
+  try {
+    whoami = await ctx.api.get("/api/tasks/whoami");
+    checks.push({
+      ok: true,
+      label: "Martha API + credential",
+      detail: `${ctx.profile.api_url} — ${whoami.kind ?? "?"}${whoami.agent_name ? ` (${whoami.agent_name})` : whoami.sub ? ` (${whoami.sub})` : ""}`
+    });
+  } catch (err) {
+    const status = err instanceof MarthaAPIError ? err.status : undefined;
+    const rejectedByApi = status === 401 || status === 403;
+    const rejectedByIdp = !rejectedByApi && err instanceof CLIError && err.exitCode === 2 /* Auth */;
+    checks.push({
+      ok: false,
+      label: "Martha API + credential",
+      detail: rejectedByApi ? `credential rejected by the API (HTTP ${status})` : rejectedByIdp ? `credential rejected by Keycloak: ${err instanceof Error ? err.message : String(err)}` : `${ctx.profile.api_url}: ${err instanceof Error ? err.message : String(err)}`,
+      fix: rejectedByApi ? "export MARTHA_CLIENT_ID/MARTHA_CLIENT_SECRET for the agent's principal, or run `martha auth login`" : rejectedByIdp ? `check MARTHA_CLIENT_ID/MARTHA_CLIENT_SECRET, and that profile '${ctx.profileName}' points at the Keycloak that issued them — or mint a fresh one: martha principals bootstrap --mode agent --agent ${opts.agent}` : "check api_url in ~/.martha/config.yaml and that the Martha API is up"
+    });
+  }
+  let def = null;
+  try {
+    def = await ctx.api.get(`${AGENTS_PATH2}/${encodeURIComponent(opts.agent)}`);
+  } catch (err) {
+    if (!(err instanceof MarthaAPIError && err.status === 404)) {
+      checks.push({
+        ok: null,
+        label: "agent exists",
+        detail: `could not read '${opts.agent}': ${err instanceof Error ? err.message : String(err)}`,
+        fix: "this credential may not be allowed to read agent definitions — check with `martha agents list`"
+      });
+    }
+  }
+  if (def) {
+    const marthaHosted = String(def.agent_type ?? "") !== "external";
+    checks.push({
+      ok: marthaHosted,
+      label: "agent is Martha-hosted",
+      detail: marthaHosted ? String(def.agent_type ?? "cloud") : "external (self-hosted)",
+      fix: marthaHosted ? undefined : "acp-serve drives a Martha-hosted agent — recreate it with --reasoning martha"
+    });
+    const takeover = def.runs_as_chat === true;
+    checks.push({
+      ok: takeover,
+      label: "chat takeover (runs_as_chat)",
+      fix: takeover ? undefined : `run: martha principals bootstrap --mode agent --agent ${opts.agent}`
+    });
+  } else if (!checks.some((c) => c.label === "agent exists")) {
+    checks.push({
+      ok: false,
+      label: "agent exists",
+      detail: `'${opts.agent}' not found`,
+      fix: `create it: martha principals bootstrap --mode agent --agent ${opts.agent} --prompt "…"`
+    });
+  }
+  checks.push(await checkAgentPrincipal(ctx, opts.agent, def));
+  const hasSa = !!(process.env.MARTHA_CLIENT_ID && process.env.MARTHA_CLIENT_SECRET);
+  const hasToken = !!process.env.MARTHA_TOKEN;
+  checks.push({
+    ok: hasSa || hasToken ? true : null,
+    label: "durable credential in env",
+    detail: hasSa ? `MARTHA_CLIENT_ID=${process.env.MARTHA_CLIENT_ID}` : hasToken ? "MARTHA_TOKEN" : "none — the adapter will fall back to the profile's stored token",
+    fix: hasSa || hasToken ? undefined : `mint one: martha principals bootstrap --mode agent --agent ${opts.agent}`
+  });
+  const relayProbe = await reachable(relayHttpUrl(opts.relayUrl));
+  checks.push({
+    ok: relayProbe.ok,
+    label: "relay reachable",
+    detail: relayProbe.detail,
+    fix: relayProbe.ok ? undefined : `start the relay, or correct --relay (${opts.relayUrl})`
+  });
+  const identity2 = process.env.BUZZ_PRIVATE_KEY;
+  checks.push({
+    ok: !!identity2,
+    label: "channel identity",
+    detail: identity2 ? "BUZZ_PRIVATE_KEY set (not shown)" : "BUZZ_PRIVATE_KEY not set",
+    fix: identity2 ? undefined : "export BUZZ_PRIVATE_KEY=<the agent's nsec> — Martha-issued identities land in #1119"
+  });
+  if (identity2 && relayProbe.ok && buzzPath) {
+    checks.push(await checkMembership(buzzPath, opts.relayUrl, identity2, opts.channelId));
+  } else {
+    checks.push({
+      ok: null,
+      label: "channel membership",
+      detail: "skipped — needs the identity, a reachable relay, and the buzz CLI"
+    });
+  }
+  return checks;
+}
+async function checkAgentPrincipal(ctx, agent, def) {
+  const label = "agent principal (bound client)";
+  const fix = `run: martha principals bootstrap --mode agent --agent ${agent}`;
+  try {
+    const scan = await scanClientsForAgent(ctx, agent);
+    if (!scan.granting.length) {
+      return scan.incomplete ? {
+        ok: null,
+        label,
+        detail: `inconclusive — read ${scan.scanned} of ${scan.total} clients`
+      } : { ok: false, label, detail: "no client is bound to this agent", fix };
+    }
+    const shared = scan.granting.filter((h) => h.agents.length > 1);
+    const names = scan.granting.map((h) => h.client);
+    if (shared.length) {
+      return {
+        ok: null,
+        label,
+        detail: `bound to ${names.join(", ")} — but ${shared.map((h) => h.client).join(", ")} also has other agents, which disables chat takeover`,
+        fix: "give this agent its own principal: martha principals bootstrap --mode agent --label <fresh>"
+      };
+    }
+    return { ok: true, label, detail: names.join(", ") };
+  } catch (err) {
+    const status = err instanceof MarthaAPIError ? err.status : undefined;
+    return {
+      ok: null,
+      label,
+      detail: status === 403 || status === 401 ? `not verifiable with this credential (HTTP ${status})` : `not verifiable: ${err instanceof Error ? err.message : String(err)}`,
+      fix: def ? undefined : fix
+    };
+  }
+}
+async function checkMembership(buzzBin, relayUrl, identity2, channelId) {
+  const label = "channel membership";
+  const res = await runBin(buzzBin, ["--format", "compact", "channels", "list", "--member"], {
+    ...process.env,
+    BUZZ_RELAY_URL: relayUrl,
+    BUZZ_PRIVATE_KEY: identity2
+  });
+  if (res.code !== 0) {
+    const why = res.code === 3 ? "the relay rejected this identity" : res.code === 2 ? "relay/network error" : `buzz exited ${res.code}`;
+    return {
+      ok: false,
+      label,
+      detail: `${why}: ${res.stderr.trim().slice(0, 200)}`,
+      fix: "check BUZZ_PRIVATE_KEY belongs to a registered user on this relay"
+    };
+  }
+  let channels = [];
+  try {
+    channels = JSON.parse(res.stdout.trim() || "[]");
+  } catch {
+    return {
+      ok: null,
+      label,
+      detail: `could not parse \`buzz channels list\` output (${res.stdout.slice(0, 120)})`
+    };
+  }
+  if (channelId) {
+    const hit = channels.find((c) => c.channel_id === channelId);
+    return {
+      ok: !!hit,
+      label,
+      detail: hit ? `${hit.name ?? channelId}` : `not a member of ${channelId}`,
+      fix: hit ? undefined : `buzz channels add-member --channel ${channelId} --pubkey <the agent's pubkey> --role member`
+    };
+  }
+  return {
+    ok: channels.length > 0,
+    label,
+    detail: channels.length ? `${channels.length} channel(s): ${channels.map((c) => c.name ?? c.channel_id).slice(0, 5).join(", ")}` : "the identity is in no channels",
+    fix: channels.length ? undefined : "buzz channels add-member --channel <id> --pubkey <the agent's pubkey> --role member"
+  };
+}
+function emitManifest(kind, env2, opts) {
+  const secretKeys = [
+    "BUZZ_PRIVATE_KEY",
+    "MARTHA_CLIENT_ID",
+    "MARTHA_CLIENT_SECRET"
+  ];
+  const entries = Object.entries(env2);
+  if (kind === "docker") {
+    const lines = [
+      "docker run --rm \\",
+      ...entries.map(([k, v]) => `  -e ${k}=${JSON.stringify(v)} \\`),
+      ...secretKeys.map((k) => `  -e ${k}="$${k}" \\`),
+      `  ${opts.image}`
+    ];
+    return lines.join(`
+`);
+  }
+  if (kind === "compose") {
+    return [
+      "services:",
+      `  martha-buzz-${opts.agent}:`,
+      `    image: ${opts.image}`,
+      "    restart: unless-stopped",
+      "    environment:",
+      ...entries.map(([k, v]) => `      ${k}: ${JSON.stringify(v)}`),
+      ...secretKeys.map((k) => `      ${k}: \${${k}:?set ${k}}`)
+    ].join(`
+`);
+  }
+  return [
+    "apiVersion: apps/v1",
+    "kind: Deployment",
+    "metadata:",
+    `  name: martha-buzz-${opts.agent}`,
+    "spec:",
+    "  replicas: 1",
+    "  selector:",
+    `    matchLabels: { app: martha-buzz-${opts.agent} }`,
+    "  template:",
+    "    metadata:",
+    `      labels: { app: martha-buzz-${opts.agent} }`,
+    "    spec:",
+    "      containers:",
+    `        - name: adapter`,
+    `          image: ${opts.image}`,
+    "          env:",
+    ...entries.flatMap(([k, v]) => [
+      `            - name: ${k}`,
+      `              value: ${JSON.stringify(v)}`
+    ]),
+    ...secretKeys.flatMap((k) => [
+      `            - name: ${k}`,
+      "              valueFrom:",
+      `                secretKeyRef: { name: martha-buzz-${opts.agent}, key: ${k} }`
+    ])
+  ].join(`
+`);
+}
+function assertSupportedChannel(kind) {
+  if (!SUPPORTED_CHANNELS.includes(kind)) {
+    throw new CLIError(`Channel type '${kind}' is not implemented.`, 4 /* Validation */, `Supported: ${SUPPORTED_CHANNELS.join(", ")}. Slack and others land as separate slices — the verb and the preflight generalize, the precondition list does not.`);
+  }
+}
+function registerChannelCommands(program2) {
+  const channels = program2.command("channels").description("Put a Martha agent in an external conversation channel — from Buzz (install-harness) or from Martha (connect)");
+  channels.command("install-harness <type>").description("Register Martha as a runtime in Buzz Desktop (a tier-3 custom harness definition). " + "Desktop then owns the agent's keypair, attestation and lifecycle — we only declare how to start the adapter.").option("--app-data <dir>", "Buzz Desktop app-data dir (default: auto-detect)").option("--id <id>", "Harness id", BUZZ_HARNESS_ID).option("--label <label>", "Name shown in Buzz's runtime picker", "Martha").option("--command <bin>", "Executable Buzz should spawn", "martha").option("--print", "Print the definition instead of writing it").option("--force", "Overwrite an existing definition").action(async (type, opts) => {
+    assertSupportedChannel(type);
+    const def = buzzHarnessDefinition({
+      id: opts.id,
+      label: opts.label,
+      command: opts.command
+    });
+    if (!isValidHarnessId(def.id)) {
+      throw new CLIError(`Harness id '${def.id}' is invalid.`, 4 /* Validation */, "Buzz requires [a-z0-9_][a-z0-9_-]* — a file with any other id is skipped by their loader.");
+    }
+    const json = JSON.stringify(def, null, 2) + `
+`;
+    if (opts.print) {
+      console.log(json);
+      return;
+    }
+    const chosen = opts.appData ? { build: "release", dir: String(opts.appData) } : chooseAppDataDir(buzzAppDataCandidates(process.platform, process.env, homedir()), (d) => existsSync(d));
+    if (!chosen) {
+      const candidates = buzzAppDataCandidates(process.platform, process.env, homedir());
+      const appInstalled = buzzAppCandidates(process.platform, process.env, homedir()).some((p) => existsSync(p));
+      throw new CLIError(appInstalled ? "Buzz Desktop has no data directory yet." : "Buzz Desktop is not installed.", 3 /* NotFound */, missingAppDataMessage(candidates, appInstalled));
+    }
+    const dir = join3(chosen.dir, "custom_harnesses");
+    const file = join3(dir, `${def.id}.json`);
+    if (existsSync(file) && !opts.force) {
+      throw new CLIError(`${file} already exists.`, 5 /* Conflict */, "Re-run with --force to overwrite it.");
+    }
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(file, json, "utf8");
+    console.log(source_default.bold.green(`
+✓ registered '${def.label}' as a Buzz runtime
+`));
+    console.log(source_default.dim(`  ${file}  (${chosen.build} build)`));
+    console.log();
+    for (const line of installHarnessNotes(def))
+      console.log(line);
+  });
+  channels.command("preflight <type>").description("Check every precondition for an agent to answer in a channel, and name the one command that fixes each gap. Exits non-zero if any check fails.").requiredOption("--agent <name>", "The Martha agent that will answer").option("--relay <url>", "Relay URL", "ws://localhost:3030").option("--channel <uuid>", "Check membership of one specific channel").option("--buzz-acp-bin <path>", "buzz-acp binary", "buzz-acp").option("--buzz-bin <path>", "buzz CLI binary", "buzz").option("--martha-bin <path>", "martha binary buzz-acp will spawn", "martha").action(async (type, opts) => {
+    assertSupportedChannel(type);
+    const ctx = contextFor(program2);
+    const checks = await preflightBuzz(ctx, {
+      agent: opts.agent,
+      relayUrl: opts.relay,
+      channelId: opts.channel,
+      marthaBin: opts.marthaBin,
+      buzzAcpBin: opts.buzzAcpBin,
+      buzzBin: opts.buzzBin
+    });
+    reportPreflight(type, opts.agent, checks);
+    if (checks.some((c) => c.ok === false))
+      process.exitCode = 1 /* Error */;
+  });
+  channels.command("connect <type>").description("Preflight, then launch the channel adapter (buzz-acp → martha acp-serve) — or emit a deployable unit with --emit. Never half-starts: a failed check exits non-zero.").requiredOption("--agent <name>", "The Martha agent that will answer").option("--relay <url>", "Relay URL", "ws://localhost:3030").option("--channel <uuid>", "Check membership of one specific channel").option("--subscribe <mode>", "mentions | all", "all").option("--kinds <list>", "Event kinds when --subscribe all (a wildcard REQ without it)", DEFAULT_BUZZ_KINDS).option("--respond-to <mode>", "Who the agent answers (buzz-acp gate)", "anyone").option("--buzz-acp-bin <path>", "buzz-acp binary", "buzz-acp").option("--buzz-bin <path>", "buzz CLI binary", "buzz").option("--martha-bin <path>", "martha binary buzz-acp will spawn", "martha").option("--emit <target>", "Print a deployable unit instead of launching: docker | compose | k8s").option("--image <ref>", "Image for --emit", "ghcr.io/westeuropeco/martha-buzz-adapter:latest").option("--dry-run", "Preflight and print the launch, but don't spawn anything").action(async (type, opts) => {
+    assertSupportedChannel(type);
+    if (opts.subscribe !== "mentions" && opts.subscribe !== "all") {
+      throw new CLIError(`--subscribe must be 'mentions' or 'all' (got '${opts.subscribe}').`, 4 /* Validation */);
+    }
+    const ctx = contextFor(program2);
+    const checks = await preflightBuzz(ctx, {
+      agent: opts.agent,
+      relayUrl: opts.relay,
+      channelId: opts.channel,
+      marthaBin: opts.marthaBin,
+      buzzAcpBin: opts.buzzAcpBin,
+      buzzBin: opts.buzzBin
+    });
+    reportPreflight(type, opts.agent, checks, opts.emit ? "stderr" : "stdout");
+    const env2 = buzzAcpEnv({
+      relayUrl: opts.relay,
+      subscribe: opts.subscribe,
+      kinds: opts.kinds,
+      multipleEventHandling: "queue",
+      respondTo: opts.respondTo,
+      marthaBin: opts.marthaBin
+    });
+    if (opts.emit) {
+      if (!["docker", "compose", "k8s"].includes(opts.emit)) {
+        throw new CLIError(`--emit must be docker, compose or k8s (got '${opts.emit}').`, 4 /* Validation */);
+      }
+      console.log(emitManifest(opts.emit, env2, {
+        agent: opts.agent,
+        image: opts.image
+      }));
+      return;
+    }
+    const failed = checks.filter((c) => c.ok === false);
+    if (failed.length) {
+      console.log(source_default.red.bold(`Not connecting — ${failed.length} precondition(s) unmet. Nothing was started.`));
+      process.exitCode = 1 /* Error */;
+      return;
+    }
+    const acp = which(opts.buzzAcpBin);
+    if (opts.dryRun) {
+      console.log(source_default.bold(`Would launch:
+`));
+      for (const [k, v] of Object.entries(env2))
+        console.log(`  ${k}=${v}`);
+      console.log(`  ${acp}
+`);
+      return;
+    }
+    console.log(source_default.bold(`
+Connecting '${opts.agent}' to ${opts.relay} …
+`));
+    const child = spawn3(acp, [], {
+      env: { ...process.env, ...env2 },
+      stdio: "inherit"
+    });
+    await new Promise((resolve2) => {
+      child.on("exit", (code, signal) => {
+        if (signal) {
+          console.log(source_default.dim(`
+buzz-acp terminated by ${signal}`));
+          process.exitCode = 1 /* Error */;
+        } else if (code) {
+          process.exitCode = code;
+        }
+        resolve2();
+      });
+      child.on("error", (err) => {
+        console.error(source_default.red(`failed to start ${acp}: ${err.message}`));
+        process.exitCode = 1 /* Error */;
+        resolve2();
+      });
+    });
+  });
+}
+function contextFor(program2) {
+  return createContext({
+    profileOverride: program2.opts().profile,
+    apiUrlOverride: program2.opts().apiUrl,
+    verbose: program2.opts().verbose
+  });
+}
+function reportPreflight(type, agent, checks, stream = "stdout") {
+  const write = stream === "stderr" ? (line = "") => process.stderr.write(line + `
+`) : (line = "") => console.log(line);
+  write(source_default.bold(`Martha CLI preflight — ${type} channel: ${agent}
+`));
+  printChecks(checks, write);
+  const failed = checks.filter((c) => c.ok === false).length;
+  const unknown = checks.filter((c) => c.ok === null).length;
+  write();
+  if (failed) {
+    write(source_default.red.bold(`  ${failed} precondition(s) unmet — fix the FAIL items above.`));
+  } else if (unknown) {
+    write(source_default.yellow.bold(`  All required preconditions met (${unknown} unverifiable).`));
+  } else {
+    write(source_default.green.bold("  Ready."));
+  }
+}
+function installHarnessNotes(def) {
+  return [
+    "In Buzz Desktop:",
+    source_default.cyan(`  1. New agent → runtime "${def.label}"`),
+    source_default.cyan("  2. Edit Agent → env vars → MARTHA_CLIENT_ID / MARTHA_CLIENT_SECRET"),
+    source_default.dim("     (credentials belong per-agent, never in the shared definition file)"),
+    "",
+    source_default.dim(`Desktop owns the rest: the Nostr keypair in your keyring, the NIP-OA
+` + "attestation, spawning buzz-acp, and attaching the agent to channels."),
+    "",
+    source_default.dim(`If you set BUZZ_ACP_SUBSCRIBE=all on the agent, you MUST also set
+` + `BUZZ_ACP_KINDS=${DEFAULT_BUZZ_KINDS} — 'all' with no kinds is a wildcard
+` + "subscription and turns typing and presence events into prompts.")
+  ];
+}
+
 // src/commands/config.ts
 init_config();
 init_errors();
-import { createInterface as createInterface3 } from "node:readline";
+import { createInterface as createInterface4 } from "node:readline";
 function prompt(rl, question, defaultValue) {
   const suffix = defaultValue ? ` [${defaultValue}]` : "";
   return new Promise((resolve2) => {
@@ -14237,7 +15326,7 @@ async function configInit(configDir) {
     console.log(`No configuration found. Let's set up your first profile.
 `);
   }
-  const rl = createInterface3({
+  const rl = createInterface4({
     input: process.stdin,
     output: process.stderr
   });
@@ -14524,7 +15613,7 @@ function registerConfigCommand(program2) {
         throw new CLIError("Cannot confirm in non-interactive mode.", 4 /* Validation */, "Use --yes to skip confirmation.");
       }
       const ok = await new Promise((resolve2) => {
-        const rl = createInterface3({
+        const rl = createInterface4({
           input: process.stdin,
           output: process.stderr
         });
@@ -14576,7 +15665,9 @@ var MUTABLE_FIELDS = {
     "is_active",
     "collection_id_param",
     "risk_tags",
-    "risk_level"
+    "risk_level",
+    "verification_safe",
+    "idempotent"
   ]),
   Workflow: new Set([
     "description",
@@ -14591,9 +15682,27 @@ var MUTABLE_FIELDS = {
     "is_active"
   ])
 };
+var FUNCTION_DECLARATION_FIELDS = new Set([
+  "verification_safe",
+  "idempotent"
+]);
 function isPlainObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+function declarationEnabled(value) {
+  if (isPlainObject(value))
+    return value.enabled === true;
+  return value === true;
+}
+function declarationFieldMatches(requested, observed) {
+  if (!declarationEnabled(requested)) {
+    return !declarationEnabled(observed);
+  }
+  if (isPlainObject(observed)) {
+    return observed.enabled === true && requestedValueMatches(requested, observed);
+  }
+  return observed === true;
+}
 function valuesEqual(left, right) {
   if (left === right)
     return true;
@@ -14655,6 +15764,10 @@ function normalizeDefinitionWriteBody(kind, body) {
   }
   delete normalized.definition;
   for (const [key, nestedValue] of Object.entries(nested)) {
+    if (kind === "Function" && FUNCTION_DECLARATION_FIELDS.has(key)) {
+      normalized[key] = nestedValue;
+      continue;
+    }
     if (key in normalized && !valuesEqual(normalized[key], nestedValue)) {
       throw new CLIError(`Conflicting values for '${key}' in flat and nested ${kind} fields`, 4 /* Validation */);
     }
@@ -14722,6 +15835,9 @@ function fieldValueMatches(kind, field, requested, observed) {
   if (kind === "Function" && field === "parameters") {
     return parameterMapMatches(requested, observed);
   }
+  if (kind === "Function" && FUNCTION_DECLARATION_FIELDS.has(field)) {
+    return declarationFieldMatches(requested, observed);
+  }
   const isExactTypedValue = kind === "Function" && (field === "request_body" || field === "auth") || kind === "Workflow" && (field === "nodes" || field === "edges");
   if (isExactTypedValue) {
     return valuesEqual(requested, observed);
@@ -16377,6 +17493,13 @@ function colorStatus2(status) {
   const fn = STATUS_COLORS2[status] ?? source_default.white;
   return fn(status);
 }
+function documentCountLabel(count, fetched) {
+  if (count != null)
+    return String(count);
+  if (fetched != null)
+    return String(fetched);
+  return "unknown";
+}
 function unwrapList(res) {
   if (Array.isArray(res))
     return res;
@@ -16566,7 +17689,16 @@ ${items.length} collections`));
     if (col.slug)
       console.log(`  Slug:      ${col.slug}`);
     console.log(`  Status:    ${col.is_active !== false ? source_default.green("active") : source_default.dim("inactive")}`);
-    console.log(`  Documents: ${col.document_count ?? 0}`);
+    let fetchedCount = null;
+    if (col.document_count == null) {
+      try {
+        const docsRes = await ctx.api.get(`/api/admin/collections/${encodeURIComponent(col.id)}/documents`, { params: { active_only: "true" } });
+        fetchedCount = unwrapList(docsRes).length;
+      } catch {
+        fetchedCount = null;
+      }
+    }
+    console.log(`  Documents: ${documentCountLabel(col.document_count, fetchedCount)}`);
     console.log(`  Storage:   ${col.storage_backend ?? "-"}`);
     console.log(`  Drive:     ${col.drive_folder_id ? source_default.cyan(col.drive_folder_id) : source_default.dim("not linked")}`);
     if (col.total_size_bytes != null) {
@@ -21301,6 +22433,125 @@ function registerPolicyCommands(program2) {
   });
 }
 
+// src/commands/agent-step.ts
+import { readFileSync as readFileSync3 } from "node:fs";
+init_errors();
+var BASE = "/api/admin/agent-step/trust-roots";
+function resolveKeyMaterial(value) {
+  if (value.startsWith("@")) {
+    const path9 = value.slice(1);
+    try {
+      return readFileSync3(path9, "utf8").trim();
+    } catch (e) {
+      throw new CLIError(`Could not read public key file '${path9}': ${e.message}`, 4 /* Validation */);
+    }
+  }
+  return value;
+}
+function printOne(tr) {
+  const status = tr.is_active ? source_default.green("active") : source_default.red("revoked");
+  console.log(`${source_default.bold(tr.name)}  [${status}]`);
+  console.log(source_default.dim("-".repeat(40)));
+  console.log(`  Algorithm:    ${tr.algorithm}`);
+  if (tr.key_id)
+    console.log(`  Key id:       ${tr.key_id}`);
+  if (tr.bound_runner)
+    console.log(`  Bound runner: ${tr.bound_runner}`);
+  if (tr.description)
+    console.log(`  Description:  ${tr.description}`);
+  if (tr.created_by)
+    console.log(`  Created by:   ${tr.created_by}`);
+  if (tr.created_at)
+    console.log(`  Created:      ${tr.created_at}`);
+  if (tr.updated_at)
+    console.log(`  Updated:      ${tr.updated_at}`);
+}
+function registerAgentStepCommands(program2) {
+  const cmd = program2.command("agent-step").description("Author agent_step assets (execution_proof trust roots)");
+  const roots = cmd.command("trust-roots").description("Manage per-tenant/per-runner attestation trust roots (#1083)");
+  function getCtx() {
+    return createContext({
+      profileOverride: program2.opts().profile,
+      apiUrlOverride: program2.opts().apiUrl,
+      verbose: program2.opts().verbose
+    });
+  }
+  const isJson = () => !!program2.opts().json;
+  roots.command("list").description("List the tenant's trust roots").action(async () => {
+    const ctx = getCtx();
+    const rows = await ctx.api.get(BASE);
+    if (isJson()) {
+      console.log(JSON.stringify(rows, null, 2));
+      return;
+    }
+    if (rows.length === 0) {
+      console.log(source_default.dim("No trust roots registered."));
+      return;
+    }
+    for (const r of rows) {
+      const status = r.is_active ? source_default.green("active") : source_default.red("revoked");
+      const runner = r.bound_runner ? ` runner=${r.bound_runner}` : "";
+      console.log(`${source_default.bold(r.name)}  [${status}]  ${r.algorithm}${runner}`);
+    }
+  });
+  roots.command("get <name>").description("Show one trust root").action(async (name) => {
+    const ctx = getCtx();
+    const tr = await ctx.api.get(`${BASE}/${encodeURIComponent(name)}`);
+    if (isJson()) {
+      console.log(JSON.stringify(tr, null, 2));
+      return;
+    }
+    printOne(tr);
+  });
+  roots.command("register <name>").alias("create").description("Register a signer's public key as a trust root").requiredOption("-k, --public-key <pemOrBase64>", "PEM text or raw-base64 public key, or @path to read it from a file").option("-a, --algorithm <algo>", "Signature algorithm", "ed25519").option("--key-id <id>", "Key id the signed envelope must match").option("--bound-runner <runner>", "AgentDefinition/runner name this identity belongs to").option("-d, --description <text>", "Human description").action(async (name, opts) => {
+    const ctx = getCtx();
+    const body = {
+      name,
+      public_key: resolveKeyMaterial(opts.publicKey),
+      algorithm: opts.algorithm
+    };
+    if (opts.keyId)
+      body.key_id = opts.keyId;
+    if (opts.boundRunner)
+      body.bound_runner = opts.boundRunner;
+    if (opts.description)
+      body.description = opts.description;
+    const tr = await ctx.api.post(BASE, body);
+    if (isJson()) {
+      console.log(JSON.stringify(tr, null, 2));
+      return;
+    }
+    console.log(source_default.green(`Registered trust root '${tr.name}'`));
+    printOne(tr);
+  });
+  roots.command("revoke <name>").description("Deactivate a trust root (no hard delete; preserves the audit trail)").action(async (name) => {
+    const ctx = getCtx();
+    const tr = await ctx.api.patch(`${BASE}/${encodeURIComponent(name)}`, {
+      is_active: false
+    });
+    if (isJson()) {
+      console.log(JSON.stringify(tr, null, 2));
+      return;
+    }
+    console.log(source_default.yellow(`Revoked trust root '${tr.name}' (is_active=false)`));
+  });
+  roots.command("rotate <name>").description("Rotate a trust root's public key (and optionally key id)").requiredOption("-k, --public-key <pemOrBase64>", "New PEM text or raw-base64 public key, or @path to read it from a file").option("--key-id <id>", "New key id the signed envelope must match").action(async (name, opts) => {
+    const ctx = getCtx();
+    const body = {
+      public_key: resolveKeyMaterial(opts.publicKey)
+    };
+    if (opts.keyId)
+      body.key_id = opts.keyId;
+    const tr = await ctx.api.patch(`${BASE}/${encodeURIComponent(name)}`, body);
+    if (isJson()) {
+      console.log(JSON.stringify(tr, null, 2));
+      return;
+    }
+    console.log(source_default.green(`Rotated trust root '${tr.name}'`));
+    printOne(tr);
+  });
+}
+
 // src/commands/authz.ts
 init_errors();
 
@@ -21862,7 +23113,7 @@ function normalizeList(values) {
     return [];
   return values.flatMap((v) => v.split(/[,\s]+/)).map((v) => v.trim()).filter(Boolean);
 }
-function parseIntents(raw) {
+function parseIntents2(raw) {
   const out = [];
   for (const v of raw) {
     if (!VALID_INTENTS.includes(v)) {
@@ -21974,7 +23225,7 @@ Provision an access principal now so calls just work?`, true);
   } else {
     mode = "human";
   }
-  let intents = parseIntents(normalizeList(opts.intent));
+  let intents = parseIntents2(normalizeList(opts.intent));
   if (intents.length === 0 && interactive) {
     intents = await askIntents();
   }
@@ -22179,7 +23430,7 @@ async function askIntents() {
     const n = Number(t);
     return Number.isInteger(n) && n >= 1 && n <= VALID_INTENTS.length ? VALID_INTENTS[n - 1] : t;
   });
-  return parseIntents(raw);
+  return parseIntents2(raw);
 }
 function registerInitCommand(program2) {
   program2.command("init").description("Create or update a profile, and optionally bootstrap an access principal").option("--preset <name>", "Preset: cloud or local", "cloud").option("--name <name>", "Profile name (defaults to preset name)").option("--force", "Overwrite an existing profile").option("--api-url <url>", "Override the API URL").option("--keycloak-url <url>", "Override the Keycloak URL").option("--keycloak-realm <realm>", "Override the Keycloak realm").option("--no-interactive", "Skip prompts; use defaults / overrides only").option("--bootstrap", "Provision an intent-scoped principal + grants after saving the profile").option("--mode <mode>", "Bootstrap mode: 'human' (your own client) or 'integration' (service account)").option("--intent <intents...>", "Usage buckets to grant: rag, documents, workflows, custom").option("--workflow <names...>", "Workflow name(s) to grant (workflows/custom intent)").option("--function <names...>", "Extra function name(s) to grant (custom intent)").option("--label <name>", "Integration mode: label for the SA client id").option("--agent", "Also provision a personal chat copilot (human mode) and set it as the default").option("--agent-name <name>", "Copilot agent name (defaults to copilot-{user})").option("--model <id>", "Copilot LLM model id (defaults to the platform default)").option("--host-runner", "Also set the copilot up to run host tools on THIS machine (mints a runner key + prints the `martha runner` command)").option("--yes", "Acknowledge non-interactive bootstrap side effects").action(async (opts, command) => {
@@ -22694,6 +23945,9 @@ auth.command("token").description("Print current access token").action(async ()
   await authTokenCommand(ctx);
 });
 registerChatCommand(program2);
+registerAcpServeCommand(program2);
+registerPrincipalCommands(program2);
+registerChannelCommands(program2);
 registerConfigCommand(program2);
 registerDefinitionCommands(program2, functionsConfig);
 registerDefinitionCommands(program2, workflowsConfig);
@@ -22719,6 +23973,7 @@ registerModelsCommand(program2);
 registerSessionCommands(program2);
 registerMCPCommands(program2);
 registerPolicyCommands(program2);
+registerAgentStepCommands(program2);
 registerAuthzCommands(program2);
 registerInitCommand(program2);
 registerDoctorCommand(program2);