@slock-ai/daemon 0.55.0 → 0.55.1

package/dist/cli/index.js

@@ -8,7 +8,20 @@ var __export = (target, all) => {
 // src/index.ts
 import { Command } from "commander";
 
-// src/output.ts
+// src/core/errors.ts
+var CliError = class extends Error {
+  code;
+  exitCode;
+  suggestedNextAction;
+  constructor(options) {
+    super(options.message);
+    this.name = "CliError";
+    this.code = options.code;
+    this.exitCode = options.exitCode ?? 1;
+    this.cause = options.cause;
+    this.suggestedNextAction = options.suggestedNextAction;
+  }
+};
 var CliExit = class extends Error {
   constructor(exitCode) {
     super(`CliExit(${exitCode})`);
@@ -16,16 +29,29 @@ var CliExit = class extends Error {
     this.name = "CliExit";
   }
 };
-function emit(payload) {
-  process.stdout.write(JSON.stringify(payload) + "\n");
-}
-function fail(code, message, options) {
-  const body = { ok: false, code, message };
-  if (options?.suggestedNextAction) {
-    body.suggested_next_action = options.suggestedNextAction;
+var InternalBugError = class extends CliError {
+  constructor(cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    super({
+      code: "INTERNAL_BUG",
+      message: `Unexpected error: ${message}`,
+      cause
+    });
+    this.name = "InternalBugError";
   }
-  process.stderr.write(JSON.stringify(body) + "\n");
-  throw new CliExit(options?.exitCode ?? 1);
+};
+function cliError(code, message, options = {}) {
+  return new CliError({
+    code,
+    message,
+    exitCode: options.exitCode,
+    cause: options.cause,
+    suggestedNextAction: options.suggestedNextAction
+  });
+}
+function toCliError(err) {
+  if (err instanceof CliError) return err;
+  return new InternalBugError(err);
 }
 
 // src/version.ts
@@ -100,6 +126,153 @@ function buildFetchDispatcher(targetUrl, env = process.env) {
   return dispatcher;
 }
 
+// src/transportTrace.ts
+import { randomBytes } from "crypto";
+import { appendFileSync, mkdirSync } from "fs";
+import path from "path";
+var CLI_TRACE_DIR_ENV = "SLOCK_CLI_TRANSPORT_TRACE_DIR";
+var TRACE_ID_HEX_LENGTH = 32;
+var SPAN_ID_HEX_LENGTH = 16;
+var traceSinkForTest = null;
+var traceFilePath = null;
+function emitCliTransportNormalizedError(attrs, env = process.env) {
+  try {
+    traceSinkForTest?.("cli.transport.normalized_error", attrs);
+    const traceDir = env[CLI_TRACE_DIR_ENV];
+    if (!traceDir) return;
+    mkdirSync(traceDir, { recursive: true, mode: 448 });
+    if (!traceFilePath) {
+      traceFilePath = path.join(
+        traceDir,
+        `daemon-trace-cli-transport-${safeTimestamp(Date.now())}-${process.pid}-${randomHex(4)}.jsonl`
+      );
+    }
+    appendFileSync(traceFilePath, `${JSON.stringify(spanRecord("cli.transport.normalized_error", attrs))}
+`, {
+      encoding: "utf8",
+      mode: 384
+    });
+  } catch {
+  }
+}
+function routeFamilyForPath(pathname) {
+  const normalized = pathname.split("?")[0] || "/";
+  if (normalized === "/internal/agent-api/send") return "agent-api/send";
+  if (normalized === "/internal/agent-api/events") return "agent-api/events";
+  if (normalized === "/internal/agent-api/receive-ack") return "agent-api/events";
+  if (normalized === "/internal/agent-api/tasks/claim") return "tasks/claim";
+  if (normalized === "/internal/agent-api/tasks/update-status") return "tasks/update";
+  if (normalized === "/internal/agent-api/tasks" || normalized.startsWith("/internal/agent-api/tasks/")) {
+    return "tasks";
+  }
+  if (normalized.startsWith("/internal/agent-api/attachments/")) return "agent-api/attachments";
+  if (normalized.startsWith("/api/attachments/")) return "attachments/download";
+  if (/^\/internal\/agent-api\/messages\/[^/]+\/reactions$/.test(normalized)) return "agent-api/messages/reactions";
+  if (normalized === "/internal/agent-api/server") return "server";
+  if (normalized.startsWith("/internal/agent-api/history")) return "agent-api/events";
+  if (normalized.startsWith("/internal/agent-api/search")) return "agent-api/events";
+  if (normalized.startsWith("/internal/agent-api/channel-members")) return "channel-members";
+  if (normalized.startsWith("/internal/agent-api/knowledge")) return "knowledge";
+  if (normalized === "/internal/agent-api/profile" || normalized.startsWith("/internal/agent-api/profile/")) return "profile";
+  if (normalized === "/internal/agent-api/integrations" || normalized.startsWith("/internal/agent-api/integrations/")) return "integrations";
+  if (normalized === "/internal/agent-api/upload") return "attachments/upload";
+  if (normalized === "/internal/agent-api/resolve-channel") return "resolve-channel";
+  if (normalized === "/internal/agent-api/threads/unfollow") return "threads/unfollow";
+  if (normalized === "/internal/agent-api/prepare-action") return "action/prepare";
+  if (normalized === "/internal/agent-api/reminders" || normalized.startsWith("/internal/agent-api/reminders/")) return "reminders";
+  if (/^\/internal\/agent-api\/channels\/[^/]+\/join$/.test(normalized)) return "channels/join";
+  if (/^\/internal\/agent-api\/channels\/[^/]+\/leave$/.test(normalized)) return "channels/leave";
+  if (normalized.startsWith("/internal/agent/")) {
+    const parts = normalized.split("/").filter(Boolean);
+    const firstAfterAgentId = parts[3] ?? "unknown";
+    if (firstAfterAgentId === "server") return "server";
+    if (firstAfterAgentId === "send") return "agent-api/send";
+    if (firstAfterAgentId === "history" || firstAfterAgentId === "search" || firstAfterAgentId === "receive" || firstAfterAgentId === "receive-ack") {
+      return "agent-api/events";
+    }
+    if (firstAfterAgentId === "channel-members") return "channel-members";
+    if (firstAfterAgentId === "knowledge") return "knowledge";
+    if (firstAfterAgentId === "profile") return "profile";
+    if (firstAfterAgentId === "integrations") return "integrations";
+    if (firstAfterAgentId === "upload") return "attachments/upload";
+    if (firstAfterAgentId === "resolve-channel") return "resolve-channel";
+    if (firstAfterAgentId === "threads") return "threads/unfollow";
+    if (firstAfterAgentId === "prepare-action") return "action/prepare";
+    if (firstAfterAgentId === "tasks") {
+      if (normalized.endsWith("/tasks/claim")) return "tasks/claim";
+      if (normalized.endsWith("/tasks/update-status")) return "tasks/update";
+      return "tasks";
+    }
+    if (firstAfterAgentId === "reminders") return "reminders";
+    if (firstAfterAgentId === "messages" && normalized.endsWith("/reactions")) return "agent-api/messages/reactions";
+    if (firstAfterAgentId === "channels" && normalized.endsWith("/join")) return "channels/join";
+    if (firstAfterAgentId === "channels" && normalized.endsWith("/leave")) return "channels/leave";
+  }
+  return "unknown";
+}
+function targetHostClassForUrl(url2) {
+  const hostname3 = url2.hostname.toLowerCase();
+  if (hostname3 === "127.0.0.1" || hostname3 === "localhost" || hostname3 === "::1") return "local_daemon";
+  if (hostname3 === "api.slock.ai") return "api.slock.ai";
+  return "custom_server";
+}
+function upstreamLayerForFetchError(url2, err) {
+  if (targetHostClassForUrl(url2) === "local_daemon") return "local_daemon_loopback";
+  const code = errorCode(err).toUpperCase();
+  const message = errorMessage(err).toLowerCase();
+  if (code === "ENOTFOUND" || code === "EAI_AGAIN" || message.includes("dns")) return "dns";
+  if (code === "ECONNREFUSED" || code === "ECONNRESET" || code === "EPIPE" || message.includes("socket")) return "tcp";
+  if (code.includes("TLS") || message.includes("certificate") || message.includes("tls")) return "tls";
+  if (code === "UND_ERR_HEADERS_TIMEOUT" || code === "UND_ERR_BODY_TIMEOUT" || message.includes("timeout")) return "read_timeout";
+  if (message.includes("proxy")) return "proxy_connect";
+  if (message.includes("fly")) return "fly_edge";
+  return "unknown";
+}
+function boundedOriginalMessage(err) {
+  const message = sanitizeOriginalMessage(errorMessage(err));
+  return message || void 0;
+}
+function spanRecord(name, attrs) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    type: "span",
+    schema_version: 1,
+    trace_id: randomHex(TRACE_ID_HEX_LENGTH / 2),
+    span_id: randomHex(SPAN_ID_HEX_LENGTH / 2),
+    parent_span_id: null,
+    name,
+    surface: "cli",
+    kind: "client",
+    status: "error",
+    start_time: now,
+    end_time: now,
+    duration_ms: 0,
+    attrs: Object.fromEntries(Object.entries(attrs).filter(([, value]) => value !== void 0 && value !== null && value !== "")),
+    events: []
+  };
+}
+function randomHex(bytes) {
+  return randomBytes(bytes).toString("hex");
+}
+function safeTimestamp(timeMs) {
+  return new Date(timeMs).toISOString().replace(/[:.]/g, "-");
+}
+function errorCode(err) {
+  if (typeof err === "object" && err && "code" in err && typeof err.code === "string") {
+    return err.code;
+  }
+  if (typeof err === "object" && err && "cause" in err) return errorCode(err.cause);
+  return "";
+}
+function errorMessage(err) {
+  if (err instanceof Error) return err.message;
+  return String(err ?? "");
+}
+function sanitizeOriginalMessage(message) {
+  const normalized = message.replace(/sk_(?:agent|machine|computer)_[A-Za-z0-9_-]+/g, "sk_[redacted]").replace(/sap_[A-Za-z0-9_-]+/g, "sap_[redacted]").replace(/https?:\/\/\S+/g, "[url]").replace(/\s+/g, " ").trim();
+  return normalized.length > 240 ? `${normalized.slice(0, 237)}...` : normalized;
+}
+
 // src/client.ts
 var ApiClient = class {
   constructor(ctx) {
@@ -169,7 +342,7 @@ var ApiClient = class {
   async parseJsonResponse(res) {
     let data = null;
     let error48 = null;
-    let errorCode = null;
+    let errorCode2 = null;
     const contentType = res.headers.get("content-type") ?? "";
     if (contentType.includes("application/json")) {
       let parseFailed = false;
@@ -191,34 +364,76 @@ var ApiClient = class {
       } else {
         const body = parsed;
         if (res.status === 403 && body?.requiredScope) {
-          errorCode = "SCOPE_DENIED";
+          errorCode2 = "SCOPE_DENIED";
           error48 = `Permission denied. The human has revoked the \`${body.requiredScope}\` capability for this agent under the agent profile's Permissions tab, so this command can't run. If you need it, ask the human to re-enable the corresponding toggle.`;
         } else {
           error48 = body?.error ?? `HTTP ${res.status}`;
-          errorCode = body?.errorCode ?? null;
+          errorCode2 = body?.errorCode ?? body?.code ?? null;
         }
+        const suggestedNextAction = body?.suggestedNextAction ?? body?.suggested_next_action;
+        return { ok: res.ok, status: res.status, data, error: error48, errorCode: errorCode2, suggestedNextAction };
       }
     } else if (!res.ok) {
       error48 = `HTTP ${res.status}`;
     }
-    return { ok: res.ok, status: res.status, data, error: error48, errorCode };
+    return { ok: res.ok, status: res.status, data, error: error48, errorCode: errorCode2 };
+  }
+  async fetchWithTransportTrace(url2, pathname, init) {
+    try {
+      const res = await fetch(url2, init);
+      if (res.status >= 500) {
+        this.emitTransportNormalizedError({
+          url: url2,
+          pathname,
+          normalizedCode: "server_5xx",
+          responseStarted: true,
+          upstreamLayer: "http_status",
+          upstreamStatus: res.status
+        });
+      }
+      return res;
+    } catch (err) {
+      this.emitTransportNormalizedError({
+        url: url2,
+        pathname,
+        normalizedCode: "transport_failure",
+        responseStarted: false,
+        upstreamLayer: upstreamLayerForFetchError(url2, err),
+        originalMessage: boundedOriginalMessage(err)
+      });
+      throw err;
+    }
+  }
+  emitTransportNormalizedError(input) {
+    emitCliTransportNormalizedError({
+      producer: "cli",
+      normalized_code: input.normalizedCode,
+      route_family: routeFamilyForPath(input.pathname),
+      response_started: input.responseStarted,
+      upstream_layer: input.upstreamLayer,
+      ...input.upstreamStatus === void 0 || input.upstreamStatus === null ? {} : { upstream_status: input.upstreamStatus },
+      ...input.originalMessage ? { original_message: input.originalMessage } : {},
+      ...this.ctx.serverId ? { serverId: this.ctx.serverId } : {},
+      agentId: this.ctx.agentId,
+      target_host_class: targetHostClassForUrl(input.url)
+    });
   }
   async request(method, pathname, body) {
     pathname = this.rewriteAgentCredentialPath(pathname);
-    const url2 = new URL(pathname, this.ctx.serverUrl).toString();
+    const url2 = new URL(pathname, this.ctx.serverUrl);
     const headers = this.buildAuthHeaders();
     headers["Content-Type"] = "application/json";
     if (this.ctx.activeCapabilities && this.ctx.activeCapabilities.length > 0) {
       headers["X-Slock-Agent-Active-Capabilities"] = this.ctx.activeCapabilities.join(",");
     }
-    const dispatcher = buildFetchDispatcher(url2);
+    const dispatcher = buildFetchDispatcher(url2.toString());
     const init = {
       method,
       headers,
       body: body === void 0 ? void 0 : JSON.stringify(body)
     };
     if (dispatcher) init.dispatcher = dispatcher;
-    const res = await fetch(url2, init);
+    const res = await this.fetchWithTransportTrace(url2, pathname, init);
     const parsed = await this.parseJsonResponse(res);
     if (parsed.ok && parsed.data !== null) {
       parsed.data = this.normalizeAgentCredentialResponse(pathname, parsed.data);
@@ -230,8 +445,8 @@ var ApiClient = class {
   // boundary itself.
   async requestMultipart(method, pathname, form) {
     pathname = this.rewriteAgentCredentialPath(pathname);
-    const url2 = new URL(pathname, this.ctx.serverUrl).toString();
-    const dispatcher = buildFetchDispatcher(url2);
+    const url2 = new URL(pathname, this.ctx.serverUrl);
+    const dispatcher = buildFetchDispatcher(url2.toString());
     const headers = this.buildAuthHeaders();
     if (this.ctx.activeCapabilities && this.ctx.activeCapabilities.length > 0) {
       headers["X-Slock-Agent-Active-Capabilities"] = this.ctx.activeCapabilities.join(",");
@@ -242,7 +457,7 @@ var ApiClient = class {
       body: form
     };
     if (dispatcher) init.dispatcher = dispatcher;
-    const res = await fetch(url2, init);
+    const res = await this.fetchWithTransportTrace(url2, pathname, init);
     return this.parseJsonResponse(res);
   }
   // Returns the raw Response so the caller can stream / save the body.
@@ -250,8 +465,8 @@ var ApiClient = class {
   // consuming the body. On non-2xx, attempts to surface a JSON error.
   async requestRaw(method, pathname) {
     pathname = this.rewriteAgentCredentialPath(pathname);
-    const url2 = new URL(pathname, this.ctx.serverUrl).toString();
-    const dispatcher = buildFetchDispatcher(url2);
+    const url2 = new URL(pathname, this.ctx.serverUrl);
+    const dispatcher = buildFetchDispatcher(url2.toString());
     const headers = this.buildAuthHeaders();
     if (this.ctx.activeCapabilities && this.ctx.activeCapabilities.length > 0) {
       headers["X-Slock-Agent-Active-Capabilities"] = this.ctx.activeCapabilities.join(",");
@@ -262,7 +477,7 @@ var ApiClient = class {
       redirect: "follow"
     };
     if (dispatcher) init.dispatcher = dispatcher;
-    const res = await fetch(url2, init);
+    const res = await this.fetchWithTransportTrace(url2, pathname, init);
     let error48 = null;
     if (!res.ok) {
       const contentType = res.headers.get("content-type") ?? "";
@@ -280,7 +495,7 @@ var ApiClient = class {
 // src/auth/env.ts
 import fs from "fs";
 import os from "os";
-import path from "path";
+import path2 from "path";
 var RAW_AGENT_ENV_KEYS = [
   "SLOCK_AGENT_ID",
   "SLOCK_SERVER_URL",
@@ -303,13 +518,13 @@ function resolveProfileDir(slug, env = process.env) {
     return env.SLOCK_PROFILE_DIR;
   }
   if (env.SLOCK_HOME) {
-    return path.join(env.SLOCK_HOME, "profiles", slug);
+    return path2.join(env.SLOCK_HOME, "profiles", slug);
   }
   const home = env.HOME ?? os.homedir();
-  return path.join(home, ".slock", "profiles", slug);
+  return path2.join(home, ".slock", "profiles", slug);
 }
 function resolveProfileCredentialPath(slug, env) {
-  return path.join(resolveProfileDir(slug, env), "credential.json");
+  return path2.join(resolveProfileDir(slug, env), "credential.json");
 }
 function readProfileCredential(slug, env) {
   const filePath = resolveProfileCredentialPath(slug, env);
@@ -450,42 +665,33 @@ function loadAgentContext(env = process.env) {
 // src/core/io.ts
 function defaultCliIo() {
   return {
+    stdin: process.stdin,
     stdout: process.stdout,
     stderr: process.stderr
   };
 }
 
-// src/core/errors.ts
-var CliError = class extends Error {
-  code;
-  exitCode;
-  suggestedNextAction;
-  constructor(options) {
-    super(options.message);
-    this.name = "CliError";
-    this.code = options.code;
-    this.exitCode = options.exitCode ?? 1;
-    this.cause = options.cause;
-    this.suggestedNextAction = options.suggestedNextAction;
-  }
-};
-var InternalBugError = class extends CliError {
-  constructor(cause) {
-    const message = cause instanceof Error ? cause.message : String(cause);
-    super({
-      code: "INTERNAL_BUG",
-      message: `Unexpected error: ${message}`,
-      cause
-    });
-    this.name = "InternalBugError";
+// src/core/context.ts
+function bootstrapSuggestedNextAction(code) {
+  switch (code) {
+    case "MISSING_AGENT_ID":
+    case "MISSING_SERVER_URL":
+    case "MISSING_TOKEN":
+      return "Use a Slock profile with `slock --profile <slug> ...`; create one with `slock agent login --server <server-url> --agent <agent-id> --profile-slug <slug>`.";
+    case "PROFILE_FILE_UNREADABLE":
+    case "PROFILE_FILE_INVALID":
+      return "Check the selected Slock profile, or recreate it with `slock agent login --server <server-url> --agent <agent-id> --profile-slug <slug>`.";
+    case "TOKEN_FILE_UNREADABLE":
+    case "TOKEN_FILE_EMPTY":
+      return "Check the daemon-injected token file, or restart the Slock daemon so it can inject a fresh credential.";
+    case "MISSING_AGENT_PROXY_URL":
+    case "MISSING_AGENT_PROXY_TOKEN":
+    case "MULTIPLE_AGENT_PROXY_TOKENS":
+      return "Restart the Slock daemon so it can inject a complete local proxy environment, or remove the partial proxy env vars before retrying.";
+    default:
+      return void 0;
   }
-};
-function toCliError(err) {
-  if (err instanceof CliError) return err;
-  return new InternalBugError(err);
 }
-
-// src/core/context.ts
 function createCommandContext(options = {}) {
   const io = options.io ?? defaultCliIo();
   const env = options.env ?? process.env;
@@ -502,7 +708,8 @@ function createCommandContext(options = {}) {
           throw new CliError({
             code: err.code,
             message: err.message,
-            cause: err
+            cause: err,
+            suggestedNextAction: bootstrapSuggestedNextAction(err.code)
           });
         }
         throw err;
@@ -514,16 +721,14 @@ function createCommandContext(options = {}) {
 
 // src/core/renderer.ts
 function renderError(io, err) {
-  const body = {
-    ok: false,
-    code: err.code,
-    message: err.message
-  };
+  io.stderr.write(`Error: ${err.message}
+`);
+  io.stderr.write(`Code: ${err.code}
+`);
   if (err.suggestedNextAction) {
-    body.suggested_next_action = err.suggestedNextAction;
-  }
-  io.stderr.write(`${JSON.stringify(body)}
+    io.stderr.write(`Next action: ${err.suggestedNextAction}
 `);
+  }
 }
 function writeText(io, text) {
   io.stdout.write(text);
@@ -543,16 +748,23 @@ function registerCliCommand(parent, command, runtimeOptions = {}) {
     child.argument(arg);
   }
   for (const option of command.spec.options ?? []) {
-    child.option(option.flags, option.description);
+    if (option.parse) {
+      child.option(option.flags, option.description, option.parse);
+    } else {
+      child.option(option.flags, option.description);
+    }
+  }
+  if (command.spec.helpAfter) {
+    child.addHelpText("after", command.spec.helpAfter);
   }
   child.action(async (...args) => {
     const ctx = createCommandContext(runtimeOptions);
     try {
       await command.handler(ctx, ...args);
     } catch (err) {
-      const cliError = toCliError(err);
-      renderError(ctx.io, cliError);
-      throw new CliExit(cliError.exitCode);
+      const cliError2 = toCliError(err);
+      renderError(ctx.io, cliError2);
+      throw new CliExit(cliError2.exitCode);
     }
   });
 }
@@ -561,8 +773,7 @@ function registerCliCommand(parent, command, runtimeOptions = {}) {
 var whoamiCommand = defineCommand(
   {
     name: "whoami",
-    description: "Print the agent context resolved from env (token value redacted)",
-    rationale: "denied"
+    description: "Print the agent context resolved from env (token value redacted)"
   },
   (ctx) => {
     const agentContext = ctx.loadAgentContext();
@@ -698,17 +909,26 @@ function describeListResult(reason, serverUrl) {
       return "You have `manageAgents` on at least one server, but no agents exist on those servers yet. Ask the user to create an agent first (via web UI), then rerun `slock agent list`.";
   }
 }
-function registerAgentListCommand(parent) {
-  parent.command("list").description(
-    "List Slock agents the user can mint credentials for (after a device-code login)."
-  ).requiredOption("--server <url>", "Slock server base URL, e.g. https://slock.example.com").option("--client-name <label>", "Human-readable label shown on the web approval page").action(async (options) => {
+var agentListCommand = defineCommand(
+  {
+    name: "list",
+    description: "List Slock agents the user can mint credentials for (after a device-code login).",
+    options: [
+      { flags: "--server <url>", description: "Slock server base URL, e.g. https://slock.example.com" },
+      { flags: "--client-name <label>", description: "Human-readable label shown on the web approval page" }
+    ]
+  },
+  async (ctx, options) => {
+    if (!options.server?.trim()) {
+      throw cliError("INVALID_ARG", "--server is required");
+    }
     let userSession;
     try {
       userSession = await runDeviceCodeLogin({
         serverUrl: options.server,
         ...options.clientName ? { clientName: options.clientName } : {},
         onUserAction: ({ verificationUri, userCode, expiresInSeconds }) => {
-          process.stderr.write(
+          ctx.io.stderr.write(
             `Open ${verificationUri} in your browser, enter code ${userCode} (expires in ~${Math.max(0, Math.floor(expiresInSeconds / 60))}m).
 `
           );
@@ -716,7 +936,7 @@ function registerAgentListCommand(parent) {
       });
     } catch (err) {
       if (err instanceof DeviceCodeLoginError) {
-        fail(err.code, err.message);
+        throw cliError(err.code, err.message, { cause: err });
       }
       throw err;
     }
@@ -736,7 +956,7 @@ function registerAgentListCommand(parent) {
         body = await res.json();
       } catch {
       }
-      fail(
+      throw cliError(
         body?.code ?? `list_failed_${res.status}`,
         body?.error ?? `Failed to list manageable agents (status ${res.status}).`
       );
@@ -745,7 +965,7 @@ function registerAgentListCommand(parent) {
     const agents = payload.data?.agents ?? [];
     const reason = payload.data?.reason ?? (agents.length > 0 ? "ok" : "no_agents_on_manageable_servers");
     const suggestedNextAction = describeListResult(reason, options.server);
-    emit({
+    writeJson(ctx.io, {
       ok: true,
       data: {
         agents,
@@ -754,28 +974,46 @@ function registerAgentListCommand(parent) {
         suggested_next_action: suggestedNextAction
       }
     });
-  });
+  }
+);
+function registerAgentListCommand(parent, runtimeOptions = {}) {
+  registerCliCommand(parent, agentListCommand, runtimeOptions);
 }
 
 // src/commands/agent/login.ts
 import { mkdir, stat, writeFile } from "fs/promises";
-import path2 from "path";
+import path3 from "path";
 import { fetch as undiciFetch2 } from "undici";
-function registerAgentLoginCommand(parent) {
-  parent.command("login").description(
-    "Sign this CLI in as a specific Slock agent via the device-code login grant."
-  ).requiredOption("--server <url>", "Slock server base URL, e.g. https://slock.example.com").requiredOption("--agent <agentId>", "Agent id to log in as").option("--client-name <label>", "Human-readable label shown on the web approval page").option("--profile-slug <slug>", "Slug to save the new profile under (defaults to the agent id). Distinct from root `slock --profile`, which selects an existing profile to use.").option("--profile-dir <path>", "Override the profile directory root (default resolution: SLOCK_HOME/profiles/<slug> when SLOCK_HOME is set, else ~/.slock/profiles/<slug>)").action(async (options) => {
+var agentLoginCommand = defineCommand(
+  {
+    name: "login",
+    description: "Sign this CLI in as a specific Slock agent via the device-code login grant.",
+    options: [
+      { flags: "--server <url>", description: "Slock server base URL, e.g. https://slock.example.com" },
+      { flags: "--agent <agentId>", description: "Agent id to log in as" },
+      { flags: "--client-name <label>", description: "Human-readable label shown on the web approval page" },
+      { flags: "--profile-slug <slug>", description: "Slug to save the new profile under (defaults to the agent id). Distinct from root `slock --profile`, which selects an existing profile to use." },
+      { flags: "--profile-dir <path>", description: "Override the profile directory root (default resolution: SLOCK_HOME/profiles/<slug> when SLOCK_HOME is set, else ~/.slock/profiles/<slug>)" }
+    ]
+  },
+  async (ctx, options) => {
+    if (!options.server?.trim()) {
+      throw cliError("INVALID_ARG", "--server is required");
+    }
+    if (!options.agent?.trim()) {
+      throw cliError("INVALID_AGENT_ID", "--agent must not be empty.");
+    }
     const invalidShape = describeInvalidAgentIdShape(options.agent);
     if (invalidShape) {
-      fail("INVALID_AGENT_ID", invalidShape, {
+      throw cliError("INVALID_AGENT_ID", invalidShape, {
         suggestedNextAction: `Run \`slock agent list --server ${options.server}\` to see valid agent ids, then rerun login with --agent <id>.`
       });
     }
     const profileSlug = options.profileSlug ?? options.agent;
     const profileDir = options.profileDir ?? resolveProfileDir(profileSlug);
-    const credentialPath = path2.join(profileDir, "credential.json");
+    const credentialPath = path3.join(profileDir, "credential.json");
     if (await profileFileExists(credentialPath)) {
-      fail(
+      throw cliError(
         "PROFILE_ALREADY_EXISTS",
         `Profile '${profileSlug}' already has a credential at ${credentialPath}.`,
         {
@@ -789,7 +1027,7 @@ function registerAgentLoginCommand(parent) {
         serverUrl: options.server,
         ...options.clientName ? { clientName: options.clientName } : {},
         onUserAction: ({ verificationUri, userCode, expiresInSeconds }) => {
-          process.stderr.write(
+          ctx.io.stderr.write(
             `Open ${verificationUri} in your browser, enter code ${userCode} (expires in ~${Math.max(0, Math.floor(expiresInSeconds / 60))}m).
 `
           );
@@ -797,7 +1035,7 @@ function registerAgentLoginCommand(parent) {
       });
     } catch (err) {
       if (err instanceof DeviceCodeLoginError) {
-        fail(err.code, err.message);
+        throw cliError(err.code, err.message, { cause: err });
       }
       throw err;
     }
@@ -816,7 +1054,7 @@ function registerAgentLoginCommand(parent) {
       const body = await safeJson2(mintRes);
       const code = body?.code ?? `mint_failed_${mintRes.status}`;
       const detail = describeMintError(code, options.server);
-      fail(
+      throw cliError(
         code,
         detail?.message ?? body?.error ?? `Failed to mint agent credential (status ${mintRes.status}).`,
         detail?.suggestedNextAction ? { suggestedNextAction: detail.suggestedNextAction } : void 0
@@ -824,7 +1062,7 @@ function registerAgentLoginCommand(parent) {
     }
     const minted = await mintRes.json();
     if (!minted.apiKey || !minted.agentId || !minted.serverId) {
-      fail(
+      throw cliError(
         "mint_response_invalid",
         "Server mint response was missing apiKey / agentId / serverId."
       );
@@ -849,7 +1087,7 @@ function registerAgentLoginCommand(parent) {
       ) + "\n",
       { mode: 384 }
     );
-    emit({
+    writeJson(ctx.io, {
       ok: true,
       data: {
         agentId: minted.agentId,
@@ -861,7 +1099,10 @@ function registerAgentLoginCommand(parent) {
         credentialPath
       }
     });
-  });
+  }
+);
+function registerAgentLoginCommand(parent, runtimeOptions = {}) {
+  registerCliCommand(parent, agentLoginCommand, runtimeOptions);
 }
 async function safeJson2(res) {
   try {
@@ -944,30 +1185,30 @@ var CHANNEL_MESSAGE_RE = new RegExp(
 
 // ../shared/src/tracing/index.ts
 var DEFAULT_TRACE_FLAGS = "00";
-var TRACE_ID_HEX_LENGTH = 32;
-var SPAN_ID_HEX_LENGTH = 16;
+var TRACE_ID_HEX_LENGTH2 = 32;
+var SPAN_ID_HEX_LENGTH2 = 16;
 var TRACE_FLAGS_HEX_LENGTH = 2;
 var TRACE_ID_PATTERN = /^[0-9a-f]{32}$/;
 var SPAN_ID_PATTERN = /^[0-9a-f]{16}$/;
 var TRACE_FLAGS_PATTERN = /^[0-9a-f]{2}$/;
 function isTraceId(value) {
-  return TRACE_ID_PATTERN.test(value) && value !== "0".repeat(TRACE_ID_HEX_LENGTH);
+  return TRACE_ID_PATTERN.test(value) && value !== "0".repeat(TRACE_ID_HEX_LENGTH2);
 }
 function isSpanId(value) {
-  return SPAN_ID_PATTERN.test(value) && value !== "0".repeat(SPAN_ID_HEX_LENGTH);
+  return SPAN_ID_PATTERN.test(value) && value !== "0".repeat(SPAN_ID_HEX_LENGTH2);
 }
 function isTraceFlags(value) {
   return TRACE_FLAGS_PATTERN.test(value);
 }
 function assertTraceContext(context) {
   if (!isTraceId(context.traceId)) {
-    throw new Error(`Invalid traceId: expected ${TRACE_ID_HEX_LENGTH} lowercase hex chars`);
+    throw new Error(`Invalid traceId: expected ${TRACE_ID_HEX_LENGTH2} lowercase hex chars`);
   }
   if (!isSpanId(context.spanId)) {
-    throw new Error(`Invalid spanId: expected ${SPAN_ID_HEX_LENGTH} lowercase hex chars`);
+    throw new Error(`Invalid spanId: expected ${SPAN_ID_HEX_LENGTH2} lowercase hex chars`);
   }
   if (context.parentSpanId !== null && !isSpanId(context.parentSpanId)) {
-    throw new Error(`Invalid parentSpanId: expected null or ${SPAN_ID_HEX_LENGTH} lowercase hex chars`);
+    throw new Error(`Invalid parentSpanId: expected null or ${SPAN_ID_HEX_LENGTH2} lowercase hex chars`);
   }
   if (!isTraceFlags(context.traceFlags)) {
     throw new Error(`Invalid traceFlags: expected ${TRACE_FLAGS_HEX_LENGTH} lowercase hex chars`);
@@ -1007,19 +1248,19 @@ var NoopActiveSpan = class {
 };
 var noopTracer = new NoopTracer();
 function generateTraceId() {
-  return randomNonZeroHex(TRACE_ID_HEX_LENGTH);
+  return randomNonZeroHex(TRACE_ID_HEX_LENGTH2);
 }
 function generateSpanId() {
-  return randomNonZeroHex(SPAN_ID_HEX_LENGTH);
+  return randomNonZeroHex(SPAN_ID_HEX_LENGTH2);
 }
 function randomNonZeroHex(length) {
-  let value = randomHex(length);
+  let value = randomHex2(length);
   while (value === "0".repeat(length)) {
-    value = randomHex(length);
+    value = randomHex2(length);
   }
   return value;
 }
-function randomHex(length) {
+function randomHex2(length) {
   const bytes = new Uint8Array(length / 2);
   globalThis.crypto.getRandomValues(bytes);
   return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
@@ -1795,10 +2036,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path4) {
-  if (!path4)
+function getElementAtPath(obj, path6) {
+  if (!path6)
     return obj;
-  return path4.reduce((acc, key) => acc?.[key], obj);
+  return path6.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -2181,11 +2422,11 @@ function aborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path4, issues) {
+function prefixIssues(path6, issues) {
   return issues.map((iss) => {
     var _a2;
     (_a2 = iss).path ?? (_a2.path = []);
-    iss.path.unshift(path4);
+    iss.path.unshift(path6);
     return iss;
   });
 }
@@ -2368,7 +2609,7 @@ function formatError(error48, mapper = (issue2) => issue2.message) {
 }
 function treeifyError(error48, mapper = (issue2) => issue2.message) {
   const result = { errors: [] };
-  const processError = (error49, path4 = []) => {
+  const processError = (error49, path6 = []) => {
     var _a2, _b;
     for (const issue2 of error49.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
@@ -2378,7 +2619,7 @@ function treeifyError(error48, mapper = (issue2) => issue2.message) {
       } else if (issue2.code === "invalid_element") {
         processError({ issues: issue2.issues }, issue2.path);
       } else {
-        const fullpath = [...path4, ...issue2.path];
+        const fullpath = [...path6, ...issue2.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue2));
           continue;
@@ -2410,8 +2651,8 @@ function treeifyError(error48, mapper = (issue2) => issue2.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path4 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path4) {
+  const path6 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path6) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -14388,13 +14629,13 @@ function resolveRef(ref, ctx) {
   if (!ref.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path4 = ref.slice(1).split("/").filter(Boolean);
-  if (path4.length === 0) {
+  const path6 = ref.slice(1).split("/").filter(Boolean);
+  if (path6.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path4[0] === defsKey) {
-    const key = path4[1];
+  if (path6[0] === defsKey) {
+    const key = path6[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref}`);
     }
@@ -15044,52 +15285,60 @@ async function resolveActionInput(input = process.stdin) {
     );
   }
 }
-function registerActionPrepareCommand(parent) {
-  parent.command("prepare").description("Prepare an action card for a human to commit (B-mode quick-commit shortcut)").requiredOption(
-    "--target <target>",
-    "Channel/DM/thread target to post the card. Same format as slock message send: '#channel', 'dm:@peer', '#channel:shortid'"
-  ).action(async (opts) => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
+var actionPrepareCommand = defineCommand(
+  {
+    name: "prepare",
+    description: "Prepare an action card for a human to commit (B-mode quick-commit shortcut)",
+    options: [
+      {
+        flags: "--target <target>",
+        description: "Channel/DM/thread target to post the card. Same format as slock message send: '#channel', 'dm:@peer', '#channel:shortid'"
+      }
+    ]
+  },
+  async (ctx, opts) => {
+    if (!opts.target?.trim()) {
+      throw cliError("INVALID_ARG", "--target is required");
     }
+    const agentContext = ctx.loadAgentContext();
     let raw;
     try {
-      raw = await resolveActionInput();
+      raw = await resolveActionInput(ctx.io.stdin ?? process.stdin);
     } catch (err) {
-      if (err instanceof PrepareActionInputError) fail(err.code, err.message);
+      if (err instanceof PrepareActionInputError) throw cliError(err.code, err.message, { cause: err });
       throw err;
     }
     const parsed = actionCardActionSchema.safeParse(raw);
     if (!parsed.success) {
       const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
-      fail("INVALID_ACTION", `Action failed validation: ${issues}`);
+      throw cliError("INVALID_ACTION", `Action failed validation: ${issues}`);
     }
     const crossFieldError = validateActionCardAction(parsed.data);
     if (crossFieldError) {
-      fail("INVALID_ACTION", `Action failed validation: ${crossFieldError}`);
+      throw cliError("INVALID_ACTION", `Action failed validation: ${crossFieldError}`);
     }
-    const client = new ApiClient(ctx);
+    const client = ctx.createApiClient(agentContext);
     const res = await client.request(
       "POST",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/prepare-action`,
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/prepare-action`,
       { target: opts.target, action: parsed.data }
     );
     if (!res.ok) {
       const code = res.status >= 500 ? "SERVER_5XX" : "PREPARE_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw cliError(code, res.error ?? `HTTP ${res.status}`);
     }
     const data = res.data;
     const shortId = data.messageId ? data.messageId.slice(0, 8) : null;
-    process.stdout.write(
+    writeText(
+      ctx.io,
       shortId ? `Action card posted to ${opts.target} as message ${data.messageId} (short ${shortId}). The human can click the action verb to commit.
 ` : `Action card posted to ${opts.target}.
 `
     );
-  });
+  }
+);
+function registerActionPrepareCommand(parent, runtimeOptions = {}) {
+  registerCliCommand(parent, actionPrepareCommand, runtimeOptions);
 }
 
 // src/commands/server/_format.ts
@@ -15196,12 +15445,9 @@ var channelMembersCommand = defineCommand(
   {
     name: "members",
     description: "List agents and humans who are members of a channel, DM, or thread",
-    rationale: "denied",
     arguments: ["<target>"]
   },
   async (ctx, target) => {
-    const agentContext = ctx.loadAgentContext();
-    const client = ctx.createApiClient(agentContext);
     const channel = String(target || "").trim();
     if (!channel) {
       throw new CliError({
@@ -15209,6 +15455,8 @@ var channelMembersCommand = defineCommand(
         message: "target is required"
       });
     }
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
     const encoded = encodeURIComponent(channel);
     const res = await client.request(
       "GET",
@@ -15244,7 +15492,6 @@ var channelLeaveCommand = defineCommand(
   {
     name: "leave",
     description: "Leave a regular channel you have joined",
-    rationale: "required",
     options: [
       {
         flags: "--target <target>",
@@ -15312,7 +15559,6 @@ var channelJoinCommand = defineCommand(
   {
     name: "join",
     description: "Join a visible public channel",
-    rationale: "required",
     options: [
       {
         flags: "--target <target>",
@@ -15373,8 +15619,7 @@ function registerChannelJoinCommand(parent, runtimeOptions) {
 var serverInfoCommand = defineCommand(
   {
     name: "info",
-    description: "List channels, agents, and humans on the current server",
-    rationale: "denied"
+    description: "List channels, agents, and humans on the current server"
   },
   async (ctx) => {
     const agentContext = ctx.loadAgentContext();
@@ -15417,8 +15662,8 @@ function formatKnowledgeStdout(content) {
   return content.endsWith("\n") ? content : `${content}
 `;
 }
-function toKnowledgeErrorCode(errorCode, status) {
-  switch (errorCode) {
+function toKnowledgeErrorCode(errorCode2, status) {
+  switch (errorCode2) {
     case "INVALID_JSON_RESPONSE":
     case "SCOPE_DENIED":
     case "knowledge_agent_missing":
@@ -15430,7 +15675,7 @@ function toKnowledgeErrorCode(errorCode, status) {
     case "knowledge_trace_id_invalid":
     case "knowledge_turn_id_invalid":
     case "unsupported_capability":
-      return errorCode;
+      return errorCode2;
     default:
       return status >= 500 ? "SERVER_5XX" : "KNOWLEDGE_GET_FAILED";
   }
@@ -15439,7 +15684,6 @@ var knowledgeGetCommand = defineCommand(
   {
     name: "get",
     description: "Fetch an agent knowledge topic from the current server",
-    rationale: "optional",
     arguments: ["<topic>"],
     options: [
       {
@@ -15466,7 +15710,8 @@ var knowledgeGetCommand = defineCommand(
     if (!res.ok) {
       throw new CliError({
         code: toKnowledgeErrorCode(res.errorCode, res.status),
-        message: res.error ?? `HTTP ${res.status}`
+        message: res.error ?? `HTTP ${res.status}`,
+        suggestedNextAction: res.suggestedNextAction ?? (res.errorCode === "knowledge_not_found" ? "Run `slock knowledge get index` to see all available knowledge topics." : void 0)
       });
     }
     const data = res.data;
@@ -15512,7 +15757,6 @@ var threadUnfollowCommand = defineCommand(
   {
     name: "unfollow",
     description: "Stop following a thread you no longer need ordinary delivery for",
-    rationale: "required",
     options: [
       {
         flags: "--target <target>",
@@ -15718,10 +15962,10 @@ ${opts.heldAction} Review the bounded context shown here, then choose one path.$
 // src/commands/message/_continueDraftState.ts
 import fs2 from "fs";
 import os2 from "os";
-import path3 from "path";
+import path4 from "path";
 var DEFAULT_LOCAL_DRAFT_TTL_MS = 10 * 60 * 1e3;
 function stateFilePath(agentId) {
-  return path3.join(process.env.SLOCK_CLI_DRAFT_STATE_DIR ?? os2.tmpdir(), "slock-cli-attested-send", agentId, "continue-state.json");
+  return path4.join(process.env.SLOCK_CLI_DRAFT_STATE_DIR ?? os2.tmpdir(), "slock-cli-attested-send", agentId, "continue-state.json");
 }
 function readState(agentId) {
   const filePath = stateFilePath(agentId);
@@ -15735,7 +15979,7 @@ function readState(agentId) {
 }
 function writeState(agentId, state) {
   const filePath = stateFilePath(agentId);
-  fs2.mkdirSync(path3.dirname(filePath), { recursive: true });
+  fs2.mkdirSync(path4.dirname(filePath), { recursive: true });
   fs2.writeFileSync(filePath, JSON.stringify(state), "utf8");
 }
 function getSavedDraft(agentId, target) {
@@ -15887,48 +16131,68 @@ To send the current draft unchanged:
 `
   });
 }
-function registerSendCommand(parent) {
-  parent.command("send").description("Send a message to a channel, DM, or thread").argument("[content...]", "Unsupported positional message content. Pipe content to stdin instead.").requiredOption("--target <target>", "Target: '#channel', 'dm:@peer', '#channel:threadId', 'dm:@peer:threadId'").option("--send-draft", "Send the current saved draft after reviewing newer messages").option("--anyway", "Escape hatch: send a saved draft even if freshness re-check is still stale").option("--content <content>", "Unsupported. Pipe message content to stdin instead.").option(
-    "--attachment-id <id>",
-    "Attachment id to link (repeatable). Get one from `slock attachment upload`.",
-    (value, prev = []) => prev.concat(value)
-  ).action(async (positionalContent, opts) => {
-    try {
-      rejectArgContent(positionalContent, opts);
-    } catch (err) {
-      if (err instanceof SendContentError) fail(err.code, err.message);
-      throw err;
+var messageSendCommand = defineCommand(
+  {
+    name: "send",
+    description: "Send a message to a channel, DM, or thread",
+    arguments: ["[content...]"],
+    options: [
+      { flags: "--target <target>", description: "Target: '#channel', 'dm:@peer', '#channel:threadId', 'dm:@peer:threadId'" },
+      { flags: "--send-draft", description: "Send the current saved draft after reviewing newer messages" },
+      { flags: "--anyway", description: "Escape hatch: send a saved draft even if freshness re-check is still stale" },
+      { flags: "--content <content>", description: "Unsupported. Pipe message content to stdin instead." },
+      {
+        flags: "--attachment-id <id>",
+        description: "Attachment id to link (repeatable). Get one from `slock attachment upload`.",
+        parse: (value, prev = []) => prev.concat(value)
+      }
+    ]
+  },
+  async (ctx, positionalContent, opts) => {
+    if (!opts.target?.trim()) {
+      throw cliError("INVALID_ARG", "--target is required");
     }
-    let ctx;
     try {
-      ctx = loadAgentContext();
+      rejectArgContent(positionalContent, opts);
     } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
+      if (err instanceof SendContentError) throw cliError(err.code, err.message, { cause: err });
       throw err;
     }
-    const client = new ApiClient(ctx);
     try {
       validateDraftSendFlags(opts);
     } catch (err) {
-      if (err instanceof SendContentError) fail(err.code, err.message);
+      if (err instanceof SendContentError) throw cliError(err.code, err.message, { cause: err });
       throw err;
     }
     let content;
-    let outgoingContent;
+    let outgoingContent = "";
     let outgoingAttachmentIds = [];
     let previousDraftReholdCount = 0;
     let seenUpToSeq;
     if (opts.sendDraft) {
-      content = await resolveOptionalSendContent();
+      content = await resolveOptionalSendContent(ctx.io.stdin ?? process.stdin);
       try {
         rejectSendDraftStdin(content, opts.target);
       } catch (err) {
-        if (err instanceof SendContentError) fail(err.code, err.message);
+        if (err instanceof SendContentError) throw cliError(err.code, err.message, { cause: err });
+        throw err;
+      }
+    } else {
+      try {
+        content = await resolveSendContent(ctx.io.stdin ?? process.stdin);
+      } catch (err) {
+        if (err instanceof SendContentError) throw cliError(err.code, err.message, { cause: err });
         throw err;
       }
-      const savedDraft = getSavedDraft(ctx.agentId, opts.target);
+      outgoingContent = content;
+      outgoingAttachmentIds = opts.attachmentId && opts.attachmentId.length > 0 ? opts.attachmentId : [];
+    }
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
+    if (opts.sendDraft) {
+      const savedDraft = getSavedDraft(agentContext.agentId, opts.target);
       if (!savedDraft) {
-        fail(
+        throw cliError(
           "SEND_DRAFT_NOT_FOUND",
           [
             "No saved draft exists for this target.",
@@ -15945,15 +16209,7 @@ function registerSendCommand(parent) {
       previousDraftReholdCount = savedDraft.reholdCount;
       seenUpToSeq = savedDraft.seenUpToSeq;
     } else {
-      try {
-        content = await resolveSendContent();
-      } catch (err) {
-        if (err instanceof SendContentError) fail(err.code, err.message);
-        throw err;
-      }
-      outgoingContent = content;
-      outgoingAttachmentIds = opts.attachmentId && opts.attachmentId.length > 0 ? opts.attachmentId : [];
-      const previousDraft = getSavedDraft(ctx.agentId, opts.target);
+      const previousDraft = getSavedDraft(agentContext.agentId, opts.target);
       previousDraftReholdCount = previousDraft?.reholdCount ?? 0;
       seenUpToSeq = previousDraft?.seenUpToSeq;
     }
@@ -15976,26 +16232,26 @@ function registerSendCommand(parent) {
     }
     const res = await client.request(
       "POST",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/send`,
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/send`,
       body
     );
     if (!res.ok) {
       const code = res.status >= 500 ? "SERVER_5XX" : "SEND_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw cliError(code, res.error ?? `HTTP ${res.status}`);
     }
     const data = res.data;
     if (data.state === "held") {
-      setSavedDraft(ctx.agentId, opts.target, {
+      setSavedDraft(agentContext.agentId, opts.target, {
         content: outgoingContent,
         attachmentIds: outgoingAttachmentIds,
         savedAt: Date.now(),
         reholdCount: previousDraftReholdCount + 1,
         seenUpToSeq: data.seenUpToSeq
       });
-      process.stdout.write(formatHeldSendOutput(opts.target, data));
+      writeText(ctx.io, formatHeldSendOutput(opts.target, data));
       return;
     }
-    clearSavedDraft(ctx.agentId, opts.target);
+    clearSavedDraft(agentContext.agentId, opts.target);
     const shortId = data.messageId ? data.messageId.slice(0, 8) : null;
     const replyHint = shortId ? ` (to reply in this message's thread, use target "${opts.target.includes(":") ? opts.target : opts.target + ":" + shortId}")` : "";
     let unreadSection = "";
@@ -16005,9 +16261,12 @@ function registerSendCommand(parent) {
 --- New messages you may have missed ---
 ${formatMessages(data.recentUnread)}`;
     }
-    process.stdout.write(`Message sent to ${opts.target}. Message ID: ${data.messageId}${replyHint}${unreadSection}
+    writeText(ctx.io, `Message sent to ${opts.target}. Message ID: ${data.messageId}${replyHint}${unreadSection}
 `);
-  });
+  }
+);
+function registerSendCommand(parent, runtimeOptions = {}) {
+  registerCliCommand(parent, messageSendCommand, runtimeOptions);
 }
 
 // src/commands/message/_inbox.ts
@@ -16017,8 +16276,8 @@ async function drainInbox(ctx, opts, client = new ApiClient(ctx)) {
   const query = [];
   if (opts.block) query.push("block=true");
   if (opts.block && opts.timeoutMs !== void 0) query.push(`timeout=${opts.timeoutMs}`);
-  const path4 = query.length > 0 ? `${agentPath}/receive?${query.join("&")}` : `${agentPath}/receive`;
-  const res = await client.request("GET", path4);
+  const path6 = query.length > 0 ? `${agentPath}/receive?${query.join("&")}` : `${agentPath}/receive`;
+  const res = await client.request("GET", path6);
   if (!res.ok) {
     throw new CliError({
       code: res.status >= 500 ? "SERVER_5XX" : failCode,
@@ -16042,8 +16301,7 @@ async function drainInbox(ctx, opts, client = new ApiClient(ctx)) {
 var messageCheckCommand = defineCommand(
   {
     name: "check",
-    description: "Drain the agent inbox (non-blocking). Acks delivered seqs before returning.",
-    rationale: "denied"
+    description: "Drain the agent inbox (non-blocking). Acks delivered seqs before returning."
   },
   async (ctx) => {
     const agentContext = ctx.loadAgentContext();
@@ -16104,7 +16362,6 @@ var messageReadCommand = defineCommand(
   {
     name: "read",
     description: "Read message history for a channel, DM, or thread",
-    rationale: "denied",
     options: [
       { flags: "--channel <target>", description: "Target: '#channel', 'dm:@peer', '#channel:threadId', 'dm:@peer:threadId'" },
       { flags: "--before <seq>", description: "Return messages strictly before this seq (paginate backwards)" },
@@ -16214,11 +16471,11 @@ function buildSearchPath(agentId, opts) {
   if (opts.limit !== void 0) params.set("limit", String(opts.limit));
   return `/internal/agent/${encodeURIComponent(agentId)}/search?${params.toString()}`;
 }
-function toSearchErrorCode(errorCode, status) {
-  switch (errorCode) {
+function toSearchErrorCode(errorCode2, status) {
+  switch (errorCode2) {
     case "SCOPE_DENIED":
     case "INVALID_JSON_RESPONSE":
-      return errorCode;
+      return errorCode2;
     default:
       return status >= 500 ? "SERVER_5XX" : "SEARCH_FAILED";
   }
@@ -16227,7 +16484,6 @@ var messageSearchCommand = defineCommand(
   {
     name: "search",
     description: "Search messages across channels the agent can see",
-    rationale: "denied",
     options: [
       { flags: "--query <q>", description: "Search query string" },
       { flags: "--channel <target>", description: "Restrict to a single channel/DM/thread" },
@@ -16268,40 +16524,48 @@ function normalizeReactionEmoji(value) {
   }
   return emoji3;
 }
-function registerReactCommand(parent) {
-  parent.command("react").description("Add or remove your reaction on a message").requiredOption("--message-id <id>", "Message UUID to react to").requiredOption("--emoji <emoji>", "Reaction emoji").option("--remove", "Remove your reaction instead of adding it").addHelpText("after", [
-    "",
-    "Agent guidance:",
-    "  Use reactions sparingly. Prefer acknowledgement/follow-up signals like \u{1F440}.",
-    "  Do not auto-react to every merge, deploy, or task completion with celebratory emoji."
-  ].join("\n")).action(async (opts) => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
+var messageReactCommand = defineCommand(
+  {
+    name: "react",
+    description: "Add or remove your reaction on a message",
+    options: [
+      { flags: "--message-id <id>", description: "Message UUID to react to" },
+      { flags: "--emoji <emoji>", description: "Reaction emoji" },
+      { flags: "--remove", description: "Remove your reaction instead of adding it" }
+    ],
+    helpAfter: "\nAgent guidance:\n  Use this only when a human explicitly asks for a reaction or when a reaction is a clear acknowledgement.\n  Do not auto-react to every merge, deploy, task completion, or routine status update.\n"
+  },
+  async (ctx, opts) => {
+    if (!opts.messageId?.trim()) {
+      throw cliError("INVALID_ARG", "--message-id is required");
+    }
+    if (typeof opts.emoji !== "string") {
+      throw cliError("INVALID_ARG", "--emoji is required");
     }
     let emoji3;
     try {
       emoji3 = normalizeReactionEmoji(opts.emoji);
     } catch (err) {
-      fail("INVALID_REACTION", err instanceof Error ? err.message : "Invalid reaction emoji");
+      throw cliError("INVALID_REACTION", err instanceof Error ? err.message : "Invalid reaction emoji", { cause: err });
     }
-    const client = new ApiClient(ctx);
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
     const res = await client.request(
       opts.remove ? "DELETE" : "POST",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/messages/${encodeURIComponent(opts.messageId)}/reactions`,
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/messages/${encodeURIComponent(opts.messageId)}/reactions`,
       { emoji: emoji3 }
     );
     if (!res.ok) {
       const code = res.status >= 500 ? "SERVER_5XX" : "REACT_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw cliError(code, res.error ?? `HTTP ${res.status}`);
     }
     const verb = opts.remove ? "removed from" : "added to";
-    process.stdout.write(`Reaction ${emoji3} ${verb} message ${opts.messageId.slice(0, 8)}.
+    writeText(ctx.io, `Reaction ${emoji3} ${verb} message ${opts.messageId.slice(0, 8)}.
 `);
-  });
+  }
+);
+function registerReactCommand(parent, runtimeOptions = {}) {
+  registerCliCommand(parent, messageReactCommand, runtimeOptions);
 }
 
 // src/commands/attachment/upload.ts
@@ -16390,59 +16654,65 @@ function formatBytes(bytes) {
   }
   return `${unitIndex === 0 ? value.toFixed(0) : value.toFixed(1)}${units[unitIndex]}`;
 }
-function registerAttachmentUploadCommand(parent) {
-  parent.command("upload").description(`Upload a local file as an attachment (max ${MAX_ATTACHMENT_UPLOAD_LABEL})`).requiredOption("--path <filepath>", "Absolute path to the local file to upload").option(
-    "--channel <target>",
-    "Target where the attachment will be used: '#channel', 'dm:@peer', or thread variants. Required by the v0 server until channel-less uploads land."
-  ).option("--mime-type <type>", "Explicit MIME type override, e.g. image/png").action(async (opts) => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
+var attachmentUploadCommand = defineCommand(
+  {
+    name: "upload",
+    description: `Upload a local file as an attachment (max ${MAX_ATTACHMENT_UPLOAD_LABEL})`,
+    options: [
+      { flags: "--path <filepath>", description: "Absolute path to the local file to upload" },
+      {
+        flags: "--channel <target>",
+        description: "Target where the attachment will be used: '#channel', 'dm:@peer', or thread variants. Required by the v0 server until channel-less uploads land."
+      },
+      { flags: "--mime-type <type>", description: "Explicit MIME type override, e.g. image/png" }
+    ]
+  },
+  async (ctx, opts) => {
+    if (typeof opts.path !== "string" || opts.path.length === 0) {
+      throw cliError("INVALID_ARG", "--path is required");
     }
     if (!existsSync(opts.path)) {
-      fail("INVALID_ARG", `--path does not exist: ${opts.path}`);
+      throw cliError("INVALID_ARG", `--path does not exist: ${opts.path}`);
     }
     const stat2 = statSync(opts.path);
     if (!stat2.isFile()) {
-      fail("INVALID_ARG", `--path is not a regular file: ${opts.path}`);
+      throw cliError("INVALID_ARG", `--path is not a regular file: ${opts.path}`);
     }
     try {
       validateUploadFileSize(stat2.size);
     } catch (err) {
-      if (err instanceof AttachmentUploadArgError) fail(err.code, err.message);
+      if (err instanceof AttachmentUploadArgError) throw cliError(err.code, err.message, { cause: err });
       throw err;
     }
     if (!opts.channel) {
-      fail(
+      throw cliError(
         "MISSING_CHANNEL",
         "v0 server requires a channel to attach the upload to. Pass --channel '#name', 'dm:@peer', or a thread target."
       );
     }
-    const client = new ApiClient(ctx);
-    const agentPath = `/internal/agent/${encodeURIComponent(ctx.agentId)}`;
-    const resolved = await client.request(
-      "POST",
-      `${agentPath}/resolve-channel`,
-      { target: opts.channel }
-    );
-    if (!resolved.ok || !resolved.data?.channelId) {
-      const code = resolved.status >= 500 ? "SERVER_5XX" : "RESOLVE_FAILED";
-      fail(code, resolved.error ?? `Could not resolve channel: ${opts.channel}`);
-    }
-    const channelId = resolved.data.channelId;
     const buffer = readFileSync2(opts.path);
     const filename = basename(opts.path);
     let explicitMimeType;
     try {
       explicitMimeType = normalizeExplicitMimeType(opts.mimeType);
     } catch (err) {
-      if (err instanceof AttachmentUploadArgError) fail(err.code, err.message);
+      if (err instanceof AttachmentUploadArgError) throw cliError(err.code, err.message, { cause: err });
       throw err;
     }
     const uploadMimeType = inferUploadMimeType(filename, buffer, explicitMimeType);
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
+    const agentPath = `/internal/agent/${encodeURIComponent(agentContext.agentId)}`;
+    const resolved = await client.request(
+      "POST",
+      `${agentPath}/resolve-channel`,
+      { target: opts.channel }
+    );
+    if (!resolved.ok || !resolved.data?.channelId) {
+      const code = resolved.status >= 500 ? "SERVER_5XX" : "RESOLVE_FAILED";
+      throw cliError(code, resolved.error ?? `Could not resolve channel: ${opts.channel}`);
+    }
+    const channelId = resolved.data.channelId;
     const blob = new Blob([buffer], { type: uploadMimeType });
     const form = new FormData();
     form.append("file", blob, filename);
@@ -16457,15 +16727,18 @@ function registerAttachmentUploadCommand(parent) {
     );
     if (!res.ok) {
       const code = res.status >= 500 ? "SERVER_5XX" : "UPLOAD_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw cliError(code, res.error ?? `HTTP ${res.status}`);
     }
     const d = res.data;
-    process.stdout.write(`File uploaded: ${d.filename} (${(d.sizeBytes / 1024).toFixed(1)}KB)
+    writeText(ctx.io, `File uploaded: ${d.filename} (${(d.sizeBytes / 1024).toFixed(1)}KB)
 Attachment ID: ${d.id}
 
 Use this ID with slock message send --attachment-id ${d.id} to include it in a message.
 `);
-  });
+  }
+);
+function registerAttachmentUploadCommand(parent, runtimeOptions = {}) {
+  registerCliCommand(parent, attachmentUploadCommand, runtimeOptions);
 }
 
 // src/commands/attachment/view.ts
@@ -16491,7 +16764,6 @@ var attachmentViewCommand = defineCommand(
   {
     name: "view",
     description: "Download an attachment by id and save it to a local path",
-    rationale: "denied",
     options: [
       { flags: "--id <attachmentId>", description: "Attachment UUID" },
       { flags: "--output <path>", description: "Local path to write the file to" }
@@ -16605,7 +16877,6 @@ var taskListCommand = defineCommand(
   {
     name: "list",
     description: "List tasks in a channel",
-    rationale: "denied",
     options: [
       { flags: "--channel <target>", description: "Channel target: '#channel'" },
       { flags: "--status <s>", description: "Filter: all|todo|in_progress|in_review|done (default: server-side)" }
@@ -16634,86 +16905,103 @@ function registerTaskListCommand(parent, runtimeOptions) {
 }
 
 // src/commands/task/create.ts
-function registerTaskCreateCommand(parent) {
-  parent.command("create").description("Create one or more tasks in a channel").requiredOption("--channel <target>", "Channel target: '#channel'").requiredOption(
-    "--title <title>",
-    "Task title (repeatable for batch create)",
-    (value, prev = []) => prev.concat(value)
-  ).action(async (opts) => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
+var taskCreateCommand = defineCommand(
+  {
+    name: "create",
+    description: "Create one or more tasks in a channel",
+    options: [
+      { flags: "--channel <target>", description: "Channel target: '#channel'" },
+      {
+        flags: "--title <title>",
+        description: "Task title (repeatable for batch create)",
+        parse: (value, prev = []) => prev.concat(value)
+      }
+    ]
+  },
+  async (ctx, opts) => {
+    if (!opts.channel?.trim()) {
+      throw cliError("INVALID_ARG", "--channel is required");
     }
     const titles = opts.title ?? [];
-    if (titles.length === 0) fail("INVALID_ARG", "--title is required (at least one)");
-    const client = new ApiClient(ctx);
+    if (titles.length === 0) throw cliError("INVALID_ARG", "--title is required (at least one)");
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
     const res = await client.request(
       "POST",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/tasks`,
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/tasks`,
       { channel: opts.channel, tasks: titles.map((title) => ({ title })) }
     );
     if (!res.ok) {
       const code = res.status >= 500 ? "SERVER_5XX" : "CREATE_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw cliError(code, res.error ?? `HTTP ${res.status}`);
     }
-    process.stdout.write(formatTasksCreated(opts.channel, res.data) + "\n");
-  });
+    writeText(ctx.io, formatTasksCreated(opts.channel, res.data) + "\n");
+  }
+);
+function registerTaskCreateCommand(parent, runtimeOptions = {}) {
+  registerCliCommand(parent, taskCreateCommand, runtimeOptions);
 }
 
 // src/commands/task/claim.ts
-function registerTaskClaimCommand(parent) {
-  parent.command("claim").description("Claim one or more tasks (by task number or message id)").requiredOption("--channel <target>", "Channel target: '#channel'").option(
-    "--number <n>",
-    "Task number to claim (repeatable)",
-    (value, prev = []) => prev.concat(value)
-  ).option(
-    "--message-id <id>",
-    "Message id (full or short) to claim (repeatable)",
-    (value, prev = []) => prev.concat(value)
-  ).action(async (opts) => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
+var taskClaimCommand = defineCommand(
+  {
+    name: "claim",
+    description: "Claim one or more tasks (by task number or message id)",
+    options: [
+      { flags: "--channel <target>", description: "Channel target: '#channel'" },
+      {
+        flags: "--number <n>",
+        description: "Task number to claim (repeatable)",
+        parse: (value, prev = []) => prev.concat(value)
+      },
+      {
+        flags: "--message-id <id>",
+        description: "Message id (full or short) to claim (repeatable)",
+        parse: (value, prev = []) => prev.concat(value)
+      }
+    ]
+  },
+  async (ctx, opts) => {
+    if (!opts.channel?.trim()) {
+      throw cliError("INVALID_ARG", "--channel is required");
     }
     const numbers = (opts.number ?? []).map((raw) => {
       const n = Number(raw);
       if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
-        fail("INVALID_ARG", `--number must be a positive integer; got ${raw}`);
+        throw cliError("INVALID_ARG", `--number must be a positive integer; got ${raw}`);
       }
       return n;
     });
     const messageIds = opts.messageId ?? [];
     if (numbers.length === 0 && messageIds.length === 0) {
-      fail("INVALID_ARG", "Provide at least one --number or --message-id");
+      throw cliError("INVALID_ARG", "Provide at least one --number or --message-id");
     }
     const body = { channel: opts.channel };
     if (numbers.length > 0) body.task_numbers = numbers;
     if (messageIds.length > 0) body.message_ids = messageIds;
-    const client = new ApiClient(ctx);
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
     const res = await client.request(
       "POST",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/tasks/claim`,
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/tasks/claim`,
       body
     );
     if (!res.ok) {
       const code = res.status >= 500 ? "SERVER_5XX" : "CLAIM_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw cliError(code, res.error ?? `HTTP ${res.status}`);
     }
     if (isFreshnessHeldResponse(res.data)) {
-      process.stdout.write(formatFreshnessHoldOutput(opts.channel, res.data, {
+      writeText(ctx.io, formatFreshnessHoldOutput(opts.channel, res.data, {
         heldAction: "Your task claim was not applied.",
         draftInstructions: "After reviewing the newer context, rerun the task claim command if it is still correct.\n"
       }));
       return;
     }
-    process.stdout.write(formatClaimResults(opts.channel, res.data) + "\n");
-  });
+    writeText(ctx.io, formatClaimResults(opts.channel, res.data) + "\n");
+  }
+);
+function registerTaskClaimCommand(parent, runtimeOptions = {}) {
+  registerCliCommand(parent, taskClaimCommand, runtimeOptions);
 }
 
 // src/commands/task/unclaim.ts
@@ -16741,7 +17029,6 @@ var taskUnclaimCommand = defineCommand(
   {
     name: "unclaim",
     description: "Release a previously-claimed task",
-    rationale: "required",
     options: [
       { flags: "--channel <target>", description: "Channel target: '#channel'" },
       { flags: "--number <n>", description: "Task number to unclaim" }
@@ -16809,7 +17096,6 @@ var taskUpdateCommand = defineCommand(
   {
     name: "update",
     description: "Update task status",
-    rationale: "required",
     options: [
       { flags: "--channel <target>", description: "Channel target: '#channel'" },
       { flags: "--number <n>", description: "Task number to update" },
@@ -16934,7 +17220,6 @@ var profileShowCommand = defineCommand(
   {
     name: "show",
     description: "Show a profile. Omit the target to show your own profile.",
-    rationale: "denied",
     arguments: ["[target]"],
     options: [{ flags: "--json", description: "Emit machine-readable JSON" }]
   },
@@ -17003,14 +17288,14 @@ function inferImageMimeType(filename, buffer) {
 }
 function readAvatarFile(avatarFile) {
   if (!existsSync2(avatarFile)) {
-    fail("PROFILE_FILE_NOT_FOUND", `Avatar file does not exist: ${avatarFile}`);
+    throw cliError("PROFILE_FILE_NOT_FOUND", `Avatar file does not exist: ${avatarFile}`);
   }
   const stat2 = statSync2(avatarFile);
   if (!stat2.isFile()) {
-    fail("PROFILE_FILE_NOT_FOUND", `Avatar file is not a regular file: ${avatarFile}`);
+    throw cliError("PROFILE_FILE_NOT_FOUND", `Avatar file is not a regular file: ${avatarFile}`);
   }
   if (stat2.size > MAX_PROFILE_AVATAR_BYTES) {
-    fail(
+    throw cliError(
       "PROFILE_AVATAR_TOO_LARGE",
       `Avatar file is ${stat2.size} bytes; max size is ${MAX_PROFILE_AVATAR_BYTES} bytes`
     );
@@ -17019,7 +17304,7 @@ function readAvatarFile(avatarFile) {
   const filename = basename2(avatarFile);
   const mimeType = inferImageMimeType(filename, buffer);
   if (!mimeType || !PROFILE_AVATAR_MIME_TYPES.has(mimeType)) {
-    fail(
+    throw cliError(
       "PROFILE_AVATAR_BAD_FORMAT",
       "Avatar must be a JPEG, PNG, GIF, or WebP image"
     );
@@ -17029,31 +17314,35 @@ function readAvatarFile(avatarFile) {
 function normalizeAvatarUrl(avatarUrl) {
   const trimmed = avatarUrl.trim();
   if (trimmed.length === 0) {
-    fail("INVALID_ARG", "--avatar-url must not be empty");
+    throw cliError("INVALID_ARG", "--avatar-url must not be empty");
   }
   if (!trimmed.startsWith("pixel:")) {
-    fail("INVALID_ARG", "--avatar-url currently supports only pixel avatar URLs; use --avatar-file for image uploads");
+    throw cliError("INVALID_ARG", "--avatar-url currently supports only pixel avatar URLs; use --avatar-file for image uploads");
   }
   return trimmed;
 }
-function registerProfileUpdateCommand(parent) {
-  parent.command("update").description("Update your own profile").option("--avatar-file <path>", "Path to a local image file to use as your avatar").option("--avatar-url <value>", "Set a pixel avatar URL such as pixel:random:<seed>").option("--display-name <name>", "Set your display name (non-empty)").option("--description <text>", "Set your profile description (non-empty)").option("--json", "Emit machine-readable JSON").action(async (opts) => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
-    }
+var profileUpdateCommand = defineCommand(
+  {
+    name: "update",
+    description: "Update your own profile",
+    options: [
+      { flags: "--avatar-file <path>", description: "Path to a local image file to use as your avatar" },
+      { flags: "--avatar-url <value>", description: "Set a pixel avatar URL such as pixel:random:<seed>" },
+      { flags: "--display-name <name>", description: "Set your display name (non-empty)" },
+      { flags: "--description <text>", description: "Set your profile description (non-empty)" },
+      { flags: "--json", description: "Emit machine-readable JSON" }
+    ]
+  },
+  async (ctx, opts) => {
     const hasAvatar = opts.avatarFile !== void 0;
     const hasAvatarUrl = opts.avatarUrl !== void 0;
     const hasDisplayName = opts.displayName !== void 0;
     const hasDescription = opts.description !== void 0;
     if (!hasAvatar && !hasAvatarUrl && !hasDisplayName && !hasDescription) {
-      fail("INVALID_ARG", "Provide at least one of --avatar-file, --avatar-url, --display-name, or --description");
+      throw cliError("INVALID_ARG", "Provide at least one of --avatar-file, --avatar-url, --display-name, or --description");
     }
     if (hasAvatar && hasAvatarUrl) {
-      fail("INVALID_ARG", "Use either --avatar-file or --avatar-url, not both");
+      throw cliError("INVALID_ARG", "Use either --avatar-file or --avatar-url, not both");
     }
     let normalizedAvatarUrl;
     if (hasAvatarUrl) {
@@ -17063,21 +17352,23 @@ function registerProfileUpdateCommand(parent) {
     if (hasDisplayName) {
       trimmedDisplayName = opts.displayName.trim();
       if (trimmedDisplayName.length === 0) {
-        fail("INVALID_ARG", "--display-name must not be empty");
+        throw cliError("INVALID_ARG", "--display-name must not be empty");
       }
       if (trimmedDisplayName.length > MAX_PROFILE_DISPLAY_NAME_LENGTH) {
-        fail("INVALID_ARG", `--display-name must be at most ${MAX_PROFILE_DISPLAY_NAME_LENGTH} characters`);
+        throw cliError("INVALID_ARG", `--display-name must be at most ${MAX_PROFILE_DISPLAY_NAME_LENGTH} characters`);
       }
     }
     if (hasDescription) {
       if (opts.description.length === 0) {
-        fail("INVALID_ARG", "--description must not be empty");
+        throw cliError("INVALID_ARG", "--description must not be empty");
       }
       if (opts.description.length > MAX_PROFILE_DESCRIPTION_LENGTH) {
-        fail("INVALID_ARG", `--description must be at most ${MAX_PROFILE_DESCRIPTION_LENGTH} characters`);
+        throw cliError("INVALID_ARG", `--description must be at most ${MAX_PROFILE_DESCRIPTION_LENGTH} characters`);
       }
     }
-    const client = new ApiClient(ctx);
+    const avatar = hasAvatar ? readAvatarFile(opts.avatarFile) : null;
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
     let latestProfile = null;
     if (hasAvatarUrl || hasDisplayName || hasDescription) {
       const body = {};
@@ -17092,41 +17383,43 @@ function registerProfileUpdateCommand(parent) {
       }
       const res = await client.request(
         "POST",
-        `/internal/agent/${encodeURIComponent(ctx.agentId)}/profile`,
+        `/internal/agent/${encodeURIComponent(agentContext.agentId)}/profile`,
         body
       );
       if (!res.ok || !res.data) {
         const code = res.errorCode ?? (res.status >= 500 ? "SERVER_5XX" : "PROFILE_UPDATE_FAILED");
-        fail(code, res.error ?? `HTTP ${res.status}`);
+        throw cliError(code, res.error ?? `HTTP ${res.status}`);
       }
       latestProfile = res.data;
     }
     if (hasAvatar) {
-      const avatar = readAvatarFile(opts.avatarFile);
       const form = new FormData();
       const avatarBytes = Uint8Array.from(avatar.buffer);
       form.append("avatar", new Blob([avatarBytes], { type: avatar.mimeType }), avatar.filename);
       const res = await client.requestMultipart(
         "POST",
-        `/internal/agent/${encodeURIComponent(ctx.agentId)}/profile/avatar`,
+        `/internal/agent/${encodeURIComponent(agentContext.agentId)}/profile/avatar`,
         form
       );
       if (!res.ok || !res.data) {
         const code = res.errorCode ?? (res.status >= 500 ? "SERVER_5XX" : "PROFILE_UPDATE_FAILED");
-        fail(code, res.error ?? `HTTP ${res.status}`);
+        throw cliError(code, res.error ?? `HTTP ${res.status}`);
       }
       latestProfile = res.data;
     }
     if (!latestProfile) {
-      fail("PROFILE_UPDATE_FAILED", "No profile returned from server");
+      throw cliError("PROFILE_UPDATE_FAILED", "No profile returned from server");
     }
     if (opts.json) {
-      emit({ ok: true, data: latestProfile });
+      writeJson(ctx.io, { ok: true, data: latestProfile });
       return;
     }
-    process.stdout.write(`${formatProfile(latestProfile)}
+    writeText(ctx.io, `${formatProfile(latestProfile)}
 `);
-  });
+  }
+);
+function registerProfileUpdateCommand(parent, runtimeOptions = {}) {
+  registerCliCommand(parent, profileUpdateCommand, runtimeOptions);
 }
 
 // src/commands/integration/_format.ts
@@ -17157,6 +17450,10 @@ function formatIntegrationList(data) {
       lines.push(`  id: ${service.id}`);
       lines.push(`  status: ${active ? "active login" : "not logged in"}`);
       lines.push(`  return URL: ${formatMaybe(service.returnUrl)}`);
+      if (service.agentManifestUrl) {
+        lines.push(`  agent behavior manifest: ${service.agentManifestUrl}`);
+        lines.push(`  local CLI env: slock integration env --service ${JSON.stringify(service.clientId)}`);
+      }
       if (service.homepageUrl) lines.push(`  homepage: ${service.homepageUrl}`);
       if (service.description) lines.push(`  description: ${service.description}`);
       if (!active) lines.push(`  next: slock integration login --service ${JSON.stringify(service.clientId)}`);
@@ -17173,6 +17470,10 @@ function formatIntegrationList(data) {
       lines.push(`  grant id: ${login.id}`);
       lines.push(`  scopes: ${login.scopes.length > 0 ? login.scopes.join(", ") : "-"}`);
       lines.push(`  return URL: ${formatMaybe(login.returnUrl)}`);
+      if (login.agentManifestUrl) {
+        lines.push(`  agent behavior manifest: ${login.agentManifestUrl}`);
+        lines.push(`  local CLI env: slock integration env --service ${JSON.stringify(login.clientId)}`);
+      }
       lines.push(`  created: ${login.createdAt}`);
     }
   }
@@ -17185,10 +17486,14 @@ function formatIntegrationLogin(data) {
     `service: ${data.service.clientId}`,
     `id: ${data.service.id}`,
     `scopes: ${data.scopes.length > 0 ? data.scopes.join(", ") : "-"}`,
-    `return URL: ${formatMaybe(data.service.returnUrl)}`,
-    "complete: this agent login is configured in Slock; no human OAuth is required",
-    "identity: run `slock profile show` if the service or human asks for your Slock Agent identity card"
+    `return URL: ${formatMaybe(data.service.returnUrl)}`
   ];
+  if (data.service.agentManifestUrl) {
+    lines.push(`agent behavior manifest: ${data.service.agentManifestUrl}`);
+    lines.push(`local CLI env: slock integration env --service ${JSON.stringify(data.service.clientId)}`);
+  }
+  lines.push("complete: this agent login is configured in Slock; no human OAuth is required");
+  lines.push("identity: run `slock profile show` if the service or human asks for your Slock Agent identity card");
   const agentAppUrl = buildAgentAppUrl(data.service.returnUrl, data.requestId);
   if (agentAppUrl) {
     lines.push(`app URL: ${agentAppUrl}`);
@@ -17200,31 +17505,33 @@ function formatIntegrationLogin(data) {
 }
 
 // src/commands/integration/list.ts
-function registerIntegrationListCommand(parent) {
-  parent.command("list").description("List registered third-party services and this agent's active logins").option("--json", "Emit machine-readable JSON").action(async (opts) => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
-    }
-    const client = new ApiClient(ctx);
+var integrationListCommand = defineCommand(
+  {
+    name: "list",
+    description: "List registered third-party services and this agent's active logins",
+    options: [{ flags: "--json", description: "Emit machine-readable JSON" }]
+  },
+  async (ctx, opts) => {
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
     const res = await client.request(
       "GET",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/integrations`
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/integrations`
     );
     if (!res.ok || !res.data) {
       const code = res.status >= 500 ? "SERVER_5XX" : "INTEGRATION_LIST_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw cliError(code, res.error ?? `HTTP ${res.status}`);
     }
     if (opts.json) {
-      emit({ ok: true, data: res.data });
+      writeJson(ctx.io, { ok: true, data: res.data });
       return;
     }
-    process.stdout.write(`${formatIntegrationList(res.data)}
+    writeText(ctx.io, `${formatIntegrationList(res.data)}
 `);
-  });
+  }
+);
+function registerIntegrationListCommand(parent, runtimeOptions = {}) {
+  registerCliCommand(parent, integrationListCommand, runtimeOptions);
 }
 
 // src/commands/integration/login.ts
@@ -17234,46 +17541,389 @@ function normalizeScopes(raw) {
     raw.flatMap((value) => value.split(",")).map((value) => value.trim()).filter(Boolean)
   )).sort();
   if (scopes.length === 0) {
-    fail("INVALID_ARG", "--scope must include at least one non-empty scope");
+    throw cliError("INVALID_ARG", "--scope must include at least one non-empty scope");
   }
   return scopes;
 }
-function registerIntegrationLoginCommand(parent) {
-  parent.command("login").description("Provision or reuse this agent's login for a registered service").requiredOption("--service <id>", "Registered service id, client id, or exact service name").option("--scope <scope>", "Requested scope; can be repeated or comma-separated", (value, previous = []) => {
-    previous.push(value);
-    return previous;
-  }).option("--json", "Emit machine-readable JSON").action(async (opts) => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
-    }
-    const service = opts.service.trim();
+var integrationLoginCommand = defineCommand(
+  {
+    name: "login",
+    description: "Provision or reuse this agent's login for a registered service",
+    options: [
+      { flags: "--service <id>", description: "Registered service id, client id, or exact service name" },
+      {
+        flags: "--scope <scope>",
+        description: "Requested scope; can be repeated or comma-separated",
+        parse: (value, previous = []) => {
+          previous.push(value);
+          return previous;
+        }
+      },
+      { flags: "--json", description: "Emit machine-readable JSON" }
+    ]
+  },
+  async (ctx, opts) => {
+    const service = opts.service?.trim() ?? "";
     if (!service) {
-      fail("INVALID_ARG", "--service must not be empty");
+      throw cliError("INVALID_ARG", "--service is required");
     }
-    const client = new ApiClient(ctx);
+    const scopes = normalizeScopes(opts.scope);
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
     const res = await client.request(
       "POST",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/integrations/login`,
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/integrations/login`,
       {
         service,
-        scopes: normalizeScopes(opts.scope)
+        scopes
       }
     );
     if (!res.ok || !res.data) {
       const code = res.status >= 500 ? "SERVER_5XX" : "INTEGRATION_LOGIN_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw cliError(code, res.error ?? `HTTP ${res.status}`);
     }
     if (opts.json) {
-      emit({ ok: true, data: res.data });
+      writeJson(ctx.io, { ok: true, data: res.data });
       return;
     }
-    process.stdout.write(`${formatIntegrationLogin(res.data)}
+    writeText(ctx.io, `${formatIntegrationLogin(res.data)}
 `);
+  }
+);
+function registerIntegrationLoginCommand(parent, runtimeOptions = {}) {
+  registerCliCommand(parent, integrationLoginCommand, runtimeOptions);
+}
+
+// src/commands/integration/manifest.ts
+import fs3 from "fs";
+import os3 from "os";
+import path5 from "path";
+var AGENT_MANIFEST_MAX_BYTES = 64 * 1024;
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function requireUrl(value, field) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${field} must be a non-empty URL string`);
+  }
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error(`${field} must be a valid URL`);
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new Error(`${field} must use http or https`);
+  }
+  if (parsed.username || parsed.password) {
+    throw new Error(`${field} must not include credentials`);
+  }
+  return parsed.toString();
+}
+function requireCommand(value) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error("execution.command must be a non-empty string for local_cli manifests");
+  }
+  const command = value.trim();
+  if (command.includes("/") || command.includes("\\") || /\s/.test(command)) {
+    throw new Error("execution.command must be a bare command name, not a path or shell fragment");
+  }
+  return command;
+}
+function validateAgentManifestV0(value) {
+  if (!isRecord(value)) throw new Error("manifest must be a JSON object");
+  if (value.schema !== "slock-agent-manifest.v0") {
+    throw new Error("manifest schema must be slock-agent-manifest.v0");
+  }
+  const execution = value.execution;
+  if (!isRecord(execution)) throw new Error("execution must be an object");
+  if (execution.mode !== "local_cli" && execution.mode !== "http_api") {
+    throw new Error("execution.mode must be local_cli or http_api");
+  }
+  const credentialBoundary = value.credential_boundary;
+  if (credentialBoundary !== void 0 && !isRecord(credentialBoundary)) {
+    throw new Error("credential_boundary must be an object when present");
+  }
+  if (isRecord(credentialBoundary) && credentialBoundary.storage !== "per_agent_home" && credentialBoundary.storage !== "slock_managed_token") {
+    throw new Error("credential_boundary.storage must be per_agent_home or slock_managed_token");
+  }
+  const credentialStorage = isRecord(credentialBoundary) && (credentialBoundary.storage === "per_agent_home" || credentialBoundary.storage === "slock_managed_token") ? credentialBoundary.storage : void 0;
+  const forbidUserHome = isRecord(credentialBoundary) && credentialBoundary.forbid_user_home === true;
+  if (value.context_check !== void 0 && !isRecord(value.context_check)) {
+    throw new Error("context_check must be an object when present");
+  }
+  return {
+    schema: value.schema,
+    service: typeof value.service === "string" && value.service.trim() ? value.service.trim() : void 0,
+    docs_url: value.docs_url === void 0 ? void 0 : requireUrl(value.docs_url, "docs_url"),
+    execution: {
+      mode: execution.mode,
+      command: execution.mode === "local_cli" ? requireCommand(execution.command) : void 0,
+      base_url: execution.base_url === void 0 ? void 0 : requireUrl(execution.base_url, "execution.base_url")
+    },
+    credential_boundary: credentialStorage ? {
+      storage: credentialStorage,
+      forbid_user_home: forbidUserHome
+    } : void 0,
+    context_check: value.context_check
+  };
+}
+async function fetchAgentManifest(url2) {
+  const parsed = new URL(url2);
+  if (parsed.protocol !== "https:") {
+    throw new Error("agent behavior manifest URL must use HTTPS");
+  }
+  if (parsed.username || parsed.password) {
+    throw new Error("agent behavior manifest URL must not include credentials");
+  }
+  const response = await fetch(parsed, {
+    headers: { accept: "application/json" },
+    redirect: "follow"
   });
+  const finalUrl = new URL(response.url);
+  if (finalUrl.protocol !== "https:" || finalUrl.username || finalUrl.password) {
+    throw new Error("manifest redirects must remain on credential-free HTTPS URLs");
+  }
+  if (!response.ok) {
+    throw new Error(`manifest fetch failed with HTTP ${response.status}`);
+  }
+  const contentType = response.headers.get("content-type") ?? "";
+  if (contentType && !contentType.includes("application/json")) {
+    throw new Error("manifest response must be application/json");
+  }
+  const contentLength = Number(response.headers.get("content-length") ?? "");
+  if (Number.isFinite(contentLength) && contentLength > AGENT_MANIFEST_MAX_BYTES) {
+    throw new Error("manifest response is too large");
+  }
+  const body = Buffer.from(await response.arrayBuffer());
+  if (body.byteLength > AGENT_MANIFEST_MAX_BYTES) {
+    throw new Error("manifest response is too large");
+  }
+  const raw = body.toString("utf8");
+  let parsedJson;
+  try {
+    parsedJson = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`manifest response is not valid JSON: ${err.message}`);
+  }
+  return validateAgentManifestV0(parsedJson);
+}
+function sanitizePathSegment(value) {
+  const segment = value.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return segment || "service";
+}
+function resolveSlockHome(env) {
+  if (env.SLOCK_HOME?.trim()) return path5.resolve(env.SLOCK_HOME);
+  return path5.join(env.HOME ?? os3.homedir(), ".slock");
+}
+function buildLocalCliProfileEnv(input) {
+  if (input.manifest.execution.mode !== "local_cli" || !input.manifest.execution.command) {
+    throw new Error("manifest is not a local_cli integration");
+  }
+  if (input.manifest.credential_boundary?.storage !== "per_agent_home") {
+    throw new Error("manifest does not request per_agent_home credential storage");
+  }
+  if (input.manifest.credential_boundary.forbid_user_home !== true) {
+    throw new Error("manifest must set credential_boundary.forbid_user_home=true for local_cli isolation");
+  }
+  const root = resolveSlockHome(input.env ?? process.env);
+  const profileHome = path5.join(
+    root,
+    "integration-profiles",
+    sanitizePathSegment(input.ctx.serverId ?? "server"),
+    sanitizePathSegment(input.ctx.agentId),
+    sanitizePathSegment(input.serviceId)
+  );
+  fs3.mkdirSync(profileHome, { recursive: true, mode: 448 });
+  fs3.chmodSync(profileHome, 448);
+  return {
+    serviceId: input.serviceId,
+    command: input.manifest.execution.command,
+    profileHome,
+    env: {
+      SLOCK_INTEGRATION_SERVICE: input.serviceId,
+      SLOCK_INTEGRATION_PROFILE_HOME: profileHome,
+      HOME: profileHome,
+      XDG_CONFIG_HOME: path5.join(profileHome, ".config"),
+      XDG_CACHE_HOME: path5.join(profileHome, ".cache"),
+      XDG_DATA_HOME: path5.join(profileHome, ".local", "share"),
+      XDG_STATE_HOME: path5.join(profileHome, ".local", "state")
+    }
+  };
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function formatShellExports(profile) {
+  const lines = [
+    `# Slock integration profile for ${profile.serviceId}`,
+    `# command: ${profile.command}`,
+    "# This only exports env; Slock does not execute manifest commands.",
+    "# Apply these exports before invoking the local CLI yourself."
+  ];
+  for (const [key, value] of Object.entries(profile.env)) {
+    lines.push(`export ${key}=${shellQuote(value)}`);
+  }
+  return lines.join("\n");
+}
+
+// src/commands/integration/env.ts
+function normalizeService(value) {
+  return value.trim().toLowerCase();
+}
+function findService(data, service) {
+  const normalized = normalizeService(service);
+  if (!normalized) return null;
+  return data.services.find(
+    (candidate) => candidate.id === service || normalizeService(candidate.clientId) === normalized || normalizeService(candidate.name) === normalized
+  ) ?? null;
+}
+function buildIntegrationEnvListPath(agentId) {
+  return `/internal/agent/${encodeURIComponent(agentId)}/integrations`;
+}
+function describeNoLocalEnv(manifest) {
+  if (manifest.execution.mode !== "local_cli") {
+    return "manifest execution mode is not local_cli; no local CLI env is required";
+  }
+  if (!manifest.credential_boundary) {
+    return "manifest does not request a Slock-managed local environment";
+  }
+  if (manifest.credential_boundary.storage === "slock_managed_token") {
+    return "manifest uses Slock-managed token storage; no local HOME/XDG exports are required";
+  }
+  return "manifest does not request local CLI env exports";
+}
+var IntegrationEnvError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "IntegrationEnvError";
+  }
+};
+async function resolveIntegrationEnv(input) {
+  if (!input.service.agentManifestUrl) {
+    throw new IntegrationEnvError(
+      "INTEGRATION_MANIFEST_MISSING",
+      `${input.service.name} does not expose an agent behavior manifest`
+    );
+  }
+  const fetchManifestImpl = input.fetchManifest ?? fetchAgentManifest;
+  let manifest;
+  try {
+    manifest = await fetchManifestImpl(input.service.agentManifestUrl);
+  } catch (err) {
+    throw new IntegrationEnvError("INTEGRATION_MANIFEST_INVALID", err.message);
+  }
+  if (manifest.execution.mode !== "local_cli" || manifest.credential_boundary?.storage !== "per_agent_home") {
+    return {
+      kind: "no-local-env",
+      service: input.service,
+      manifestUrl: input.service.agentManifestUrl,
+      manifest,
+      message: describeNoLocalEnv(manifest)
+    };
+  }
+  try {
+    return {
+      kind: "local-env",
+      service: input.service,
+      manifestUrl: input.service.agentManifestUrl,
+      profile: buildLocalCliProfileEnv({
+        ctx: input.ctx,
+        serviceId: input.service.clientId,
+        manifest,
+        env: input.env
+      })
+    };
+  } catch (err) {
+    throw new IntegrationEnvError("INTEGRATION_MANIFEST_UNSUPPORTED", err.message);
+  }
+}
+function formatNoLocalEnv(input) {
+  return [
+    `# Slock integration profile for ${input.service}`,
+    `# manifest: ${input.manifestUrl}`,
+    "# No local CLI environment exports are required by this manifest.",
+    `# ${input.message}`,
+    "# Slock did not set HOME/XDG exports and did not execute manifest commands."
+  ].join("\n");
+}
+var integrationEnvCommand = defineCommand(
+  {
+    name: "env",
+    description: "Print per-agent local environment for a manifest-backed local CLI integration",
+    options: [
+      { flags: "--service <id>", description: "Registered service id, client id, or exact service name" },
+      { flags: "--json", description: "Emit machine-readable JSON" }
+    ]
+  },
+  async (cmdCtx, opts) => {
+    const serviceQuery = opts.service?.trim() ?? "";
+    if (!serviceQuery) {
+      throw cliError("INVALID_ARG", "--service must not be empty");
+    }
+    const ctx = cmdCtx.loadAgentContext();
+    const client = cmdCtx.createApiClient(ctx);
+    const res = await client.request("GET", buildIntegrationEnvListPath(ctx.agentId));
+    if (!res.ok || !res.data) {
+      const code = res.status >= 500 ? "SERVER_5XX" : "INTEGRATION_LIST_FAILED";
+      throw cliError(code, res.error ?? `HTTP ${res.status}`);
+    }
+    const integrations = res.data;
+    const service = findService(integrations, serviceQuery);
+    if (!service) {
+      throw cliError("INTEGRATION_NOT_FOUND", `No registered integration matched ${serviceQuery}`);
+    }
+    let resolution;
+    try {
+      resolution = await resolveIntegrationEnv({ ctx, service });
+    } catch (err) {
+      if (err instanceof IntegrationEnvError) throw cliError(err.code, err.message, { cause: err });
+      throw err;
+    }
+    if (resolution.kind === "no-local-env") {
+      if (opts.json) {
+        writeJson(cmdCtx.io, {
+          ok: true,
+          data: {
+            service: resolution.service.clientId,
+            manifestUrl: resolution.manifestUrl,
+            requiresLocalEnv: false,
+            command: resolution.manifest.execution.command ?? null,
+            env: {},
+            message: resolution.message
+          }
+        });
+        return;
+      }
+      writeText(cmdCtx.io, `${formatNoLocalEnv({
+        service: resolution.service.clientId,
+        manifestUrl: resolution.manifestUrl,
+        message: resolution.message
+      })}
+`);
+      return;
+    }
+    if (opts.json) {
+      writeJson(cmdCtx.io, {
+        ok: true,
+        data: {
+          service: resolution.service.clientId,
+          manifestUrl: resolution.manifestUrl,
+          requiresLocalEnv: true,
+          command: resolution.profile.command,
+          profileHome: resolution.profile.profileHome,
+          env: resolution.profile.env
+        }
+      });
+      return;
+    }
+    writeText(cmdCtx.io, `${formatShellExports(resolution.profile)}
+`);
+  }
+);
+function registerIntegrationEnvCommand(parent, runtimeOptions = {}) {
+  registerCliCommand(parent, integrationEnvCommand, runtimeOptions);
 }
 
 // src/commands/reminder/_format.ts
@@ -17375,66 +18025,62 @@ function buildScheduleBody(opts, now = () => Intl.DateTimeFormat().resolvedOptio
   }
   return { body };
 }
-function registerReminderScheduleCommand(parent) {
-  parent.command("schedule").description("Schedule a reminder that fires at a future time").requiredOption("--title <t>", "Short description of what the reminder is about").option(
-    "--delay-seconds <n>",
-    "Preferred for relative times. Fires this many seconds from now (server-computed, timezone-safe)"
-  ).option(
-    "--fire-at <iso>",
-    "ISO-8601 UTC timestamp, e.g. 2026-04-21T09:00:00Z. Use only for absolute calendar times"
-  ).option(
-    "--repeat <rule>",
-    "Recurrence rule: every:15m | every:2h | every:1d | daily@09:00 | weekly:mon,fri@09:00"
-  ).option(
-    "--channel <ref>",
-    "Optional channel to post a receipt message in (e.g. #general, dm:@alice)."
-  ).requiredOption(
-    "--msg-id <id>",
-    "Message id this reminder is anchored to. Required for agent-created reminders."
-  ).action(async (opts) => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
+var reminderScheduleCommand = defineCommand(
+  {
+    name: "schedule",
+    description: "Schedule a reminder that fires at a future time",
+    options: [
+      { flags: "--title <t>", description: "Short description of what the reminder is about" },
+      { flags: "--delay-seconds <n>", description: "Preferred for relative times. Fires this many seconds from now (server-computed, timezone-safe)" },
+      { flags: "--fire-at <iso>", description: "ISO-8601 UTC timestamp, e.g. 2026-04-21T09:00:00Z. Use only for absolute calendar times" },
+      { flags: "--repeat <rule>", description: "Recurrence rule: every:15m | every:2h | every:1d | daily@09:00 | weekly:mon,fri@09:00" },
+      { flags: "--channel <ref>", description: "Optional channel to post a receipt message in (e.g. #general, dm:@alice)." },
+      { flags: "--msg-id <id>", description: "Message id this reminder is anchored to. Required for agent-created reminders." }
+    ]
+  },
+  async (ctx, opts) => {
+    if (!opts.title?.trim()) {
+      throw cliError("INVALID_ARG", "--title is required");
     }
     const built = buildScheduleBody(opts);
-    if (built.error) fail(built.error.code, built.error.message);
-    const client = new ApiClient(ctx);
+    if (built.error) throw cliError(built.error.code, built.error.message);
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
     const res = await client.request(
       "POST",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/reminders`,
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/reminders`,
       built.body
     );
     if (!res.ok || !res.data?.reminder) {
       const code = res.status >= 500 ? "SERVER_5XX" : "SCHEDULE_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw cliError(code, res.error ?? `HTTP ${res.status}`);
     }
-    process.stdout.write(
+    writeText(
+      ctx.io,
       formatReminderScheduled(res.data.reminder, res.data.warning ?? null) + "\n"
     );
-  });
+  }
+);
+function registerReminderScheduleCommand(parent, runtimeOptions = {}) {
+  registerCliCommand(parent, reminderScheduleCommand, runtimeOptions);
 }
 
 // src/commands/reminder/list.ts
 var VALID_STATUSES2 = /* @__PURE__ */ new Set(["scheduled", "fired", "canceled"]);
-function registerReminderListCommand(parent) {
-  parent.command("list").description("List your own reminders (defaults to scheduled and fired)").option("--all", "Include canceled reminders").option(
-    "--status <s>",
-    "Comma-separated statuses (scheduled,fired,canceled). Default: scheduled,fired"
-  ).action(async (opts) => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
-    }
+var reminderListCommand = defineCommand(
+  {
+    name: "list",
+    description: "List your own reminders (defaults to scheduled and fired)",
+    options: [
+      { flags: "--all", description: "Include canceled reminders" },
+      { flags: "--status <s>", description: "Comma-separated statuses (scheduled,fired,canceled). Default: scheduled,fired" }
+    ]
+  },
+  async (ctx, opts) => {
     const statusRaw = opts.status && opts.status.trim().length > 0 ? opts.status.trim() : "scheduled,fired";
     for (const s of statusRaw.split(",").map((x) => x.trim()).filter(Boolean)) {
       if (!VALID_STATUSES2.has(s)) {
-        fail("INVALID_ARG", `--status entries must be one of ${Array.from(VALID_STATUSES2).join("|")}; got ${s}`);
+        throw cliError("INVALID_ARG", `--status entries must be one of ${Array.from(VALID_STATUSES2).join("|")}; got ${s}`);
       }
     }
     const params = new URLSearchParams();
@@ -17443,23 +18089,27 @@ function registerReminderListCommand(parent) {
     } else {
       params.set("status", statusRaw);
     }
-    const client = new ApiClient(ctx);
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
     const res = await client.request(
       "GET",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/reminders?${params.toString()}`
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/reminders?${params.toString()}`
     );
     if (!res.ok) {
       const code = res.status >= 500 ? "SERVER_5XX" : "LIST_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw cliError(code, res.error ?? `HTTP ${res.status}`);
     }
-    process.stdout.write(formatReminderList(res.data?.reminders ?? []) + "\n");
-  });
+    writeText(ctx.io, formatReminderList(res.data?.reminders ?? []) + "\n");
+  }
+);
+function registerReminderListCommand(parent, runtimeOptions = {}) {
+  registerCliCommand(parent, reminderListCommand, runtimeOptions);
 }
 
 // src/commands/reminder/_resolve.ts
 async function resolveReminderId(client, agentId, id, opts) {
   const trimmed = id.trim();
-  if (!trimmed) fail("INVALID_ARG", "--id is required");
+  if (!trimmed) throw cliError("INVALID_ARG", "--id is required");
   if (trimmed.length >= 32) return trimmed;
   const params = new URLSearchParams();
   if (opts.all) {
@@ -17474,47 +18124,49 @@ async function resolveReminderId(client, agentId, id, opts) {
   );
   if (!res.ok) {
     const code = res.status >= 500 ? "SERVER_5XX" : opts.failureCode;
-    fail(code, res.error ?? `HTTP ${res.status}`);
+    throw cliError(code, res.error ?? `HTTP ${res.status}`);
   }
   const matches = (res.data?.reminders ?? []).filter((r) => r.reminderId.startsWith(trimmed));
   if (matches.length === 0) {
     const scope = opts.all ? "reminder" : `${opts.statuses?.join("/") ?? "active"} reminder`;
-    fail("NOT_FOUND", `No ${scope} matches id prefix '${trimmed}'.`);
+    throw cliError("NOT_FOUND", `No ${scope} matches id prefix '${trimmed}'.`);
   }
   if (matches.length > 1) {
-    fail("AMBIGUOUS", `Ambiguous id prefix '${trimmed}' matches ${matches.length} reminders; pass a longer id.`);
+    throw cliError("AMBIGUOUS", `Ambiguous id prefix '${trimmed}' matches ${matches.length} reminders; pass a longer id.`);
   }
   return matches[0].reminderId;
 }
 
 // src/commands/reminder/cancel.ts
-function registerReminderCancelCommand(parent) {
-  parent.command("cancel").description("Cancel a scheduled reminder by id (full uuid or 8-char prefix)").requiredOption("--id <id>", "Reminder id (full uuid or short prefix)").action(async (opts) => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
-    }
+var reminderCancelCommand = defineCommand(
+  {
+    name: "cancel",
+    description: "Cancel a scheduled reminder by id (full uuid or 8-char prefix)",
+    options: [{ flags: "--id <id>", description: "Reminder id (full uuid or short prefix)" }]
+  },
+  async (ctx, opts) => {
     if (!opts.id || opts.id.trim().length === 0) {
-      fail("INVALID_ARG", "--id is required");
+      throw cliError("INVALID_ARG", "--id is required");
     }
-    const client = new ApiClient(ctx);
-    const fullId = await resolveReminderId(client, ctx.agentId, opts.id, {
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
+    const fullId = await resolveReminderId(client, agentContext.agentId, opts.id, {
       statuses: ["scheduled", "fired"],
       failureCode: "CANCEL_FAILED"
     });
     const res = await client.request(
       "DELETE",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/reminders/${encodeURIComponent(fullId)}`
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/reminders/${encodeURIComponent(fullId)}`
     );
     if (!res.ok || !res.data?.reminder) {
       const code = res.status >= 500 ? "SERVER_5XX" : "CANCEL_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw cliError(code, res.error ?? `HTTP ${res.status}`);
     }
-    process.stdout.write(formatReminderCanceled(res.data.reminder) + "\n");
-  });
+    writeText(ctx.io, formatReminderCanceled(res.data.reminder) + "\n");
+  }
+);
+function registerReminderCancelCommand(parent, runtimeOptions = {}) {
+  registerCliCommand(parent, reminderCancelCommand, runtimeOptions);
 }
 
 // src/commands/reminder/_duration.ts
@@ -17531,57 +18183,75 @@ function parseDurationSeconds(input) {
 }
 
 // src/commands/reminder/snooze.ts
-function registerReminderSnoozeCommand(parent) {
-  parent.command("snooze").description("Snooze a scheduled or fired reminder").requiredOption("--id <id>", "Reminder id (full uuid or short prefix)").requiredOption("--by <duration>", "Snooze duration, e.g. 30m, 2h, 1d").action(async (opts) => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
+var reminderSnoozeCommand = defineCommand(
+  {
+    name: "snooze",
+    description: "Snooze a scheduled or fired reminder",
+    options: [
+      { flags: "--id <id>", description: "Reminder id (full uuid or short prefix)" },
+      { flags: "--by <duration>", description: "Snooze duration, e.g. 30m, 2h, 1d" }
+    ]
+  },
+  async (ctx, opts) => {
+    if (!opts.id?.trim()) {
+      throw cliError("INVALID_ARG", "--id is required");
+    }
+    if (!opts.by?.trim()) {
+      throw cliError("INVALID_ARG", "--by is required");
     }
     const delaySeconds = parseDurationSeconds(opts.by);
     if (delaySeconds == null) {
-      fail("INVALID_ARG", "--by must be a positive duration like 30m, 2h, or 1d");
+      throw cliError("INVALID_ARG", "--by must be a positive duration like 30m, 2h, or 1d");
     }
-    const client = new ApiClient(ctx);
-    const fullId = await resolveReminderId(client, ctx.agentId, opts.id, {
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
+    const fullId = await resolveReminderId(client, agentContext.agentId, opts.id, {
       statuses: ["scheduled", "fired"],
       failureCode: "SNOOZE_FAILED"
     });
     const res = await client.request(
       "POST",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/reminders/${encodeURIComponent(fullId)}/snooze`,
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/reminders/${encodeURIComponent(fullId)}/snooze`,
       { delaySeconds }
     );
     if (!res.ok || !res.data?.reminder) {
       const code = res.status >= 500 ? "SERVER_5XX" : "SNOOZE_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw cliError(code, res.error ?? `HTTP ${res.status}`);
     }
-    process.stdout.write(formatReminderSnoozed(res.data.reminder) + "\n");
-  });
+    writeText(ctx.io, formatReminderSnoozed(res.data.reminder) + "\n");
+  }
+);
+function registerReminderSnoozeCommand(parent, runtimeOptions = {}) {
+  registerCliCommand(parent, reminderSnoozeCommand, runtimeOptions);
 }
 
 // src/commands/reminder/update.ts
-function registerReminderUpdateCommand(parent) {
-  parent.command("update").description("Update one field on a scheduled reminder").requiredOption("--id <id>", "Reminder id (full uuid or short prefix)").option("--fire-at <iso>", "New absolute next fire time").option("--in <duration>", "New relative next fire time, e.g. 30m, 2h").option("--cadence <rule>", "New recurrence rule: every:15m | daily@09:00 | weekly:mon,fri@09:00").option("--title <text>", "New reminder title").action(async (opts) => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
+var reminderUpdateCommand = defineCommand(
+  {
+    name: "update",
+    description: "Update one field on a scheduled reminder",
+    options: [
+      { flags: "--id <id>", description: "Reminder id (full uuid or short prefix)" },
+      { flags: "--fire-at <iso>", description: "New absolute next fire time" },
+      { flags: "--in <duration>", description: "New relative next fire time, e.g. 30m, 2h" },
+      { flags: "--cadence <rule>", description: "New recurrence rule: every:15m | daily@09:00 | weekly:mon,fri@09:00" },
+      { flags: "--title <text>", description: "New reminder title" }
+    ]
+  },
+  async (ctx, opts) => {
+    if (!opts.id?.trim()) {
+      throw cliError("INVALID_ARG", "--id is required");
     }
     const mutationCount = [opts.fireAt, opts.in, opts.cadence, opts.title].filter((x) => x !== void 0 && x !== null).length;
     if (mutationCount !== 1) {
-      fail("INVALID_ARG", "Pass exactly one of --fire-at, --in, --cadence, or --title");
+      throw cliError("INVALID_ARG", "Pass exactly one of --fire-at, --in, --cadence, or --title");
     }
     const body = {};
     if (opts.fireAt !== void 0) body.fireAt = opts.fireAt;
     if (opts.in !== void 0) {
       const delaySeconds = parseDurationSeconds(opts.in);
       if (delaySeconds == null) {
-        fail("INVALID_ARG", "--in must be a positive duration like 30m, 2h, or 1d");
+        throw cliError("INVALID_ARG", "--in must be a positive duration like 30m, 2h, or 1d");
       }
       body.delaySeconds = delaySeconds;
     }
@@ -17590,49 +18260,58 @@ function registerReminderUpdateCommand(parent) {
       body.tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
     }
     if (opts.title !== void 0) body.title = opts.title;
-    const client = new ApiClient(ctx);
-    const fullId = await resolveReminderId(client, ctx.agentId, opts.id, {
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
+    const fullId = await resolveReminderId(client, agentContext.agentId, opts.id, {
       all: true,
       failureCode: "UPDATE_FAILED"
     });
     const res = await client.request(
       "PATCH",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/reminders/${encodeURIComponent(fullId)}`,
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/reminders/${encodeURIComponent(fullId)}`,
       body
     );
     if (!res.ok || !res.data?.reminder) {
       const code = res.status >= 500 ? "SERVER_5XX" : "UPDATE_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw cliError(code, res.error ?? `HTTP ${res.status}`);
     }
-    process.stdout.write(formatReminderUpdated(res.data.reminder, res.data.warning ?? null) + "\n");
-  });
+    writeText(ctx.io, formatReminderUpdated(res.data.reminder, res.data.warning ?? null) + "\n");
+  }
+);
+function registerReminderUpdateCommand(parent, runtimeOptions = {}) {
+  registerCliCommand(parent, reminderUpdateCommand, runtimeOptions);
 }
 
 // src/commands/reminder/log.ts
-function registerReminderLogCommand(parent) {
-  parent.command("log").description("Show lifecycle events for one reminder").requiredOption("--id <id>", "Reminder id (full uuid or short prefix)").action(async (opts) => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
+var reminderLogCommand = defineCommand(
+  {
+    name: "log",
+    description: "Show lifecycle events for one reminder",
+    options: [{ flags: "--id <id>", description: "Reminder id (full uuid or short prefix)" }]
+  },
+  async (ctx, opts) => {
+    if (!opts.id?.trim()) {
+      throw cliError("INVALID_ARG", "--id is required");
     }
-    const client = new ApiClient(ctx);
-    const fullId = await resolveReminderId(client, ctx.agentId, opts.id, {
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
+    const fullId = await resolveReminderId(client, agentContext.agentId, opts.id, {
       all: true,
       failureCode: "LOG_FAILED"
     });
     const res = await client.request(
       "GET",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/reminders/${encodeURIComponent(fullId)}/log`
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/reminders/${encodeURIComponent(fullId)}/log`
     );
     if (!res.ok || !res.data?.events) {
       const code = res.status >= 500 ? "SERVER_5XX" : "LOG_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw cliError(code, res.error ?? `HTTP ${res.status}`);
     }
-    process.stdout.write(formatReminderLog(res.data.events) + "\n");
-  });
+    writeText(ctx.io, formatReminderLog(res.data.events) + "\n");
+  }
+);
+function registerReminderLogCommand(parent, runtimeOptions = {}) {
+  registerCliCommand(parent, reminderLogCommand, runtimeOptions);
 }
 
 // src/index.ts
@@ -17685,6 +18364,7 @@ registerProfileUpdateCommand(profileCmd);
 var integrationCmd = program.command("integration").description("Third-party service integration operations");
 registerIntegrationListCommand(integrationCmd);
 registerIntegrationLoginCommand(integrationCmd);
+registerIntegrationEnvCommand(integrationCmd);
 var reminderCmd = program.command("reminder").description("Reminder operations");
 registerReminderScheduleCommand(reminderCmd);
 registerReminderListCommand(reminderCmd);